BaseAPI: The parent of API and Core. More...

#include <base_api.h>

Inheritance diagram for jazz_bebop::BaseAPI:

Public Member Functions
	BaseAPI (pLogger a_logger, pConfigFile a_config, pChannels a_channels, pVolatile a_volatile, pPersisted a_persisted)
	Creates a BaseAPI service without starting it.

virtual pChar const	id ()

StatusCode	start ()

StatusCode	shut_down ()

bool	parse (ApiQueryState &q_state, pChar p_url, int method, bool recurse=false)

bool	block_from_const (pTransaction &p_txn, pChar p_const, bool make_tuple=false)

virtual StatusCode	header (StaticBlockHeader &hea, ApiQueryState &what)

virtual StatusCode	get (pTransaction &p_txn, ApiQueryState &what)

virtual StatusCode	put (ApiQueryState &where, pBlock p_block, int mode=WRITE_AS_BASE_DEFAULT)

virtual StatusCode	remove (ApiQueryState &what)

pChannels	get_channels ()

pVolatile	get_volatile ()

pPersisted	get_persisted ()

Public Member Functions inherited from jazz_elements::Container
	Container (pLogger a_logger, pConfigFile a_config)

StatusCode	start ()

StatusCode	shut_down ()

void	enter_read (pTransaction p_txn)

void	enter_write (pTransaction p_txn)

void	leave_read (pTransaction p_txn)

void	leave_write (pTransaction p_txn)

StatusCode	new_block (pTransaction &p_txn, int cell_type, int dim, int fill_tensor=FILL_NEW_DONT_FILL, int stringbuff_size=0, const char p_text=nullptr, char eol='\n', AttributeMap *att=nullptr)

StatusCode	new_block (pTransaction &p_txn, int num_items, StaticBlockHeader p_hea[], Name p_names[], pBlock p_block[], AttributeMap dims=nullptr, AttributeMap att=nullptr)

StatusCode	new_block (pTransaction &p_txn, pBlock p_from, pBlock p_row_filter, AttributeMap *att=nullptr)

StatusCode	new_block (pTransaction &p_txn, pTuple p_from, pChar name, AttributeMap *att=nullptr)

StatusCode	new_block (pTransaction &p_txn, pBlock p_from_text, int cell_type, pKind p_as_kind=nullptr, AttributeMap *att=nullptr)

StatusCode	new_block (pTransaction &p_txn, pBlock p_from_raw, pChar p_fmt=nullptr, bool ret_as_string=false, AttributeMap *att=nullptr)

StatusCode	new_block (pTransaction &p_txn, int cell_type)

StatusCode	new_block (pTransaction &p_txn, Index &index)

virtual StatusCode	new_transaction (pTransaction &p_txn)

virtual void	destroy_transaction (pTransaction &p_txn)

virtual StatusCode	get (pTransaction &p_txn, pChar p_what)

virtual StatusCode	get (pTransaction &p_txn, pChar p_what, pBlock p_row_filter)

virtual StatusCode	get (pTransaction &p_txn, pChar p_what, pChar name)

virtual StatusCode	locate (Locator &location, pChar p_what)

virtual StatusCode	header (StaticBlockHeader &hea, pChar p_what)

virtual StatusCode	header (pTransaction &p_txn, pChar p_what)

virtual StatusCode	put (pChar p_where, pBlock p_block, int mode=WRITE_AS_BASE_DEFAULT)

virtual StatusCode	new_entity (pChar p_where)

virtual StatusCode	remove (pChar p_where)

virtual StatusCode	copy (pChar p_where, pChar p_what)

virtual StatusCode	exec (pTransaction &p_txn, Locator &function, pTuple p_args)

virtual StatusCode	modify (Locator &function, pTuple p_args)

virtual StatusCode	as_locator (Locator &result, pChar p_what)

virtual StatusCode	get (pTransaction &p_txn, Locator &what)

virtual StatusCode	get (pTransaction &p_txn, Locator &what, pBlock p_row_filter)

virtual StatusCode	get (pTransaction &p_txn, Locator &what, pChar name)

virtual StatusCode	locate (Locator &location, Locator &what)

virtual StatusCode	header (StaticBlockHeader &hea, Locator &what)

virtual StatusCode	header (pTransaction &p_txn, Locator &what)

virtual StatusCode	put (Locator &where, pBlock p_block, int mode=WRITE_AS_BASE_DEFAULT)

virtual StatusCode	new_entity (Locator &where)

virtual StatusCode	remove (Locator &where)

virtual StatusCode	copy (Locator &where, Locator &what)

StatusCode	unwrap_received (pTransaction &p_txn)

StatusCode	unwrap_received (pTransaction &p_txn, pBlock p_maybe_block, int rec_size)

void	base_names (BaseNames &base_names)

Public Member Functions inherited from jazz_elements::Service
	Service (pLogger a_logger, pConfigFile a_config)

void	log (int loglevel, const char *message)

void	log_printf (int loglevel, const char *fmt,...)

bool	get_conf_key (const char *key, int &value)

bool	get_conf_key (const char *key, double &value)

bool	get_conf_key (const char *key, std::string &value)

Data Fields
TenBitPtrLUT	base_server
	A LUT to convert TenBitsAtAddress(base) into a pContainer.

Data Fields inherited from jazz_elements::Service
pLogger	p_log
	The logger.

pConfigFile	p_conf
	The configuration file.

Protected Member Functions
bool	parse_locator (Locator &loc, pChar p_url)

int	move_const (pChar p_buff, int buff_size, pChar p_url, pChar p_base=nullptr)

StatusCode	get_right_local (pTransaction &p_txn, ApiQueryState &q_state)

StatusCode	get_right_remote (pTransaction &p_txn, ApiQueryState &q_state)

StatusCode	get_left_local (pTransaction &p_txn, ApiQueryState &q_state)

StatusCode	put_left_local (ApiQueryState &q_state, pBlock p_block)

Protected Member Functions inherited from jazz_elements::Container
void *	malloc (size_t size)

pBlock	block_malloc (size_t size)

void	lock_container ()

void	unlock_container ()

StatusCode	destroy_container ()

int	from_hex (char c)

Protected Attributes
pChannels	p_channels
	The Channels container.

pVolatile	p_volatile
	The Volatile container.

pPersisted	p_persisted
	The Persisted container.

Protected Attributes inherited from jazz_elements::Container
int	max_transactions
	The configured ONE_SHOT_MAX_TRANSACTIONS.

uint64_t	warn_alloc_bytes
	Taken from ONE_SHOT_WARN_BLOCK_KBYTES.

uint64_t	fail_alloc_bytes
	Taken from ONE_SHOT_ERROR_BLOCK_KBYTES.

uint64_t	alloc_bytes
	The current allocation in bytes.

pTransaction	p_buffer
	The buffer for the transactions.

pTransaction	p_free
	The free list of transactions.

bool	alloc_warning_issued
	True if a warning was issued for over-allocation.

Lock32	_lock_
	A lock for the deque of transactions.

Detailed Description

BaseAPI: The parent of API and Core.

This manages parsing queries and them to the appropriate containers.

Constructor & Destructor Documentation

◆ BaseAPI()

jazz_bebop::BaseAPI::BaseAPI	(	pLogger	a_logger,
		pConfigFile	a_config,
		pChannels	a_channels,
		pVolatile	a_volatile,
		pPersisted	a_persisted
	)

Creates a BaseAPI service without starting it.

Parameters

a_logger	A pointer to the logger.
a_config	A pointer to the configuration.
a_channels	A pointer to an initialized Channels Container.
a_volatile	A pointer to an initialized Volatile Container.
a_persisted	A pointer to an initialized Persisted Container.

Member Function Documentation

◆ id()

pChar const jazz_bebop::BaseAPI::id ( )

virtual

Return object ID.

Returns: A string identifying the object that is especially useful to track uplifts and versions.

Reimplemented from jazz_elements::Service.

Reimplemented in jazz_bebop::Core, jazz_main::API, and jazz_models::ModelsAPI.

◆ start()

StatusCode jazz_bebop::BaseAPI::start ( )

virtual

Starts the BaseAPI service

Returns: SERVICE_NO_ERROR if successful, an error code otherwise.

Reimplemented from jazz_elements::Service.

Reimplemented in jazz_bebop::Core, and jazz_models::ModelsAPI.

◆ shut_down()

StatusCode jazz_bebop::BaseAPI::shut_down ( )

virtual

Shuts down the BaseAPI Service

Returns: SERVICE_NO_ERROR if successful, an error code otherwise.

Reimplemented from jazz_elements::Service.

Reimplemented in jazz_bebop::Core, and jazz_models::ModelsAPI.

◆ parse()

bool jazz_bebop::BaseAPI::parse	(	ApiQueryState &	q_state,
		pChar	p_url,
		int	method,
		bool	recurse = `false`
	)

Parse an API url into an APIParseBuffer for later execution.

Parameters

q_state	A structure with the parts the url successfully parsed ready to be executed.
p_url	The http url (that has already been checked to start with //)
method	The http method in [HTTP_NOTUSED .. BASE_API_DELETE]
recurse	True in an assignment while processing the r_value

Returns: Some error code or SERVICE_NO_ERROR if successful.

When parse() is successful, the content of the APIParseBuffer must be executed by a call (that depends on the method) and will unlock() all the intermediate blocks.

method	call executed by
BASE_API_GET, HTTP_HEAD	API.http_get()
BASE_API_PUT	API.http_put()
BASE_API_DELETE	API.http_delete()

◆ block_from_const()

bool jazz_bebop::BaseAPI::block_from_const	(	pTransaction &	p_txn,
		pChar	p_const,
		bool	make_tuple = `false`
	)

Creates a block from a constant read in the URL.

Parameters

p_txn	A pointer to a Transaction passed by reference. If successful, the Container will return a pointer to a Transaction inside the Container. The caller can only use it read-only and must destroy_transaction() when done.
p_const	The constant.
make_tuple	Insert it into a Tuple with "input" and "result".

Returns: 'true' if successful.

◆ header()

StatusCode jazz_bebop::BaseAPI::header	(	StaticBlockHeader &	hea,
		ApiQueryState &	what
	)

virtual

"API" interface metadata of a Block retrieval. This uses a parse()d what and is the only BasePI + descendants GET method.

Parameters

hea	A StaticBlockHeader structure that will receive the metadata.
what	Some successfully parse()d ApiQueryState that also distinguishes API interface from Container interface.

Returns: SERVICE_NO_ERROR on success (and a valid hea), or some negative value (error).

This is a faster, not involving RAM allocation version of the other form of header. For a tensor, is will be the only thing you need, but for a Kind or a Tuple, you probably want the types of all its items and need to pass a pTransaction to hold the data.

NOTE: It only supports APPLY_NOTHING and APPLY_NAME. It is used by Core to check argument types of Tensors or Tuple items.

◆ get()

StatusCode jazz_bebop::BaseAPI::get	(	pTransaction &	p_txn,
		ApiQueryState &	what
	)

virtual

"API" interface complete Block retrieval. This uses a parse()d what and is the only BasePI + descendants GET method.

Parameters

p_txn	A pointer to a Transaction passed by reference. If successful, the Container will return a pointer to a Transaction inside the Container.
what	Some successfully parse()d ApiQueryState that also distinguishes API interface from Container interface.

Returns: SERVICE_NO_ERROR on success (and a valid p_txn), or some negative value (error).

In the BaseAPI class, this implements all the apply cases from APPLY_NOTHING to APPLY_SET_ATTRIBUTE (APPLY_JAZZ_INFO is http only). What the aseAPI class does is forwarding the request to the right container (if the base is found, returning SERVICE_ERROR_WRONG_BASE if not).

In the descendants (Core and ModelsAPI) it should support the range from APPLY_NOTHING to APPLY_TEXT. This includes function calls APPLY_FUNCTION and APPLY_FUNCT_CONST, but also APPLY_FILTER and APPLY_FILT_CONST to select from the result of a function call. Also, APPLY_URL is very convenient for passing text as an argument to a function. APPLY_NOTHING can return some metadata about the model including a list of endpoints. APPLY_NAME can define specifics of an endpoint. APPLY_RAW and APPLY_TEXT can be used to select the favorite serialization format of the result. Therefore, the function interface should be considered as the whole range and not just APPLY_FUNCTION.

Reimplemented in jazz_models::ModelsAPI.

◆ put()

StatusCode jazz_bebop::BaseAPI::put	(	ApiQueryState &	where,
		pBlock	p_block,
		int	mode = `WRITE_AS_BASE_DEFAULT`
	)

virtual

"API" interface for Block storing: This uses a parse()d where and is the only BasePI + descendants PUT method.

Parameters

where	Some successfully parse()d ApiQueryState that also distinguishes API interface from Container interface.
p_block	A block to be stored. Notice it is a block, not a Transaction. If necessary, the Container will make a copy, write to disc, PUT it via http, etc. The container does not own the pointer in any way.
mode	Some writing restriction, either WRITE_ONLY_IF_EXISTS or WRITE_ONLY_IF_NOT_EXISTS. WRITE_TENSOR_DATA returns the error SERVICE_ERROR_WRONG_ARGUMENTS. (See NOTE below.

Returns: SERVICE_NO_ERROR on success or some negative value (error).

NOTE: The http API does not use mode, but everything in jazz_elements does. Especially, anything in Channels that uses http as a client makes intensive use of WRITE_AS_STRING, WRITE_AS_CONTENT, ... Also, it is nice that Persisted supports WRITE_ONLY_IF_EXISTS and WRITE_ONLY_IF_NOT_EXISTS to support things like one-time initialization or preventing undesired creation of new variables. Therefore, think twice before completely removing mode even if the http API does not use it. At Bebop level and model level, it can be used.

NOTE: From an API perspective, put() only supports: APPLY_NOTHING, APPLY_RAW, APPLY_TEXT and APPLY_URL (both local and remote).

◆ remove()

StatusCode jazz_bebop::BaseAPI::remove ( ApiQueryState & what )

virtual

The "API" interface: This uses a parse()d what and

Parameters

what	Some successfully parse()d ApiQueryState that also distinguishes API interface from Container interface.

Returns: SERVICE_NO_ERROR on success or some negative value (error).

Internals

It supports any successful HTTP_PUT syntax, that is:

APPLY_NOTHING: With or without node, mandatory base and entity, with of without a key. APPLY_URL: With or without node and just a base.

In all cases, calls with a node (it can only be l_node) what.url contains exactly what has to be forwarded.

◆ get_channels()

pChannels jazz_bebop::BaseAPI::get_channels ( )

inline

Get the Channels container.

Returns: A pointer to the Channels container.

◆ get_volatile()

pVolatile jazz_bebop::BaseAPI::get_volatile ( )

inline

Get the Volatile container.

Returns: A pointer to the Volatile container.

◆ get_persisted()

pPersisted jazz_bebop::BaseAPI::get_persisted ( )

inline

Get the Persisted container.

Returns: A pointer to the Persisted container.

◆ parse_locator()

bool jazz_bebop::BaseAPI::parse_locator	(	Locator &	loc,
		pChar	p_url
	)

protected

Parse a simple //base/entity/key string (Used inside the main API.parse()).

Parameters

loc	A Locator to store the result (that will be left in undetermined on error).
p_url	The input string.

Returns: true if successful.

◆ move_const()

int jazz_bebop::BaseAPI::move_const	(	pChar	p_buff,
		int	buff_size,
		pChar	p_url,
		pChar	p_base = `nullptr`
	)

inlineprotected

Copy the string "as-is" (without percent-decoding) a string into a buffer.

Parameters

p_buff	A buffer to store the result. This first char must be a zero on call or it will not write anything, just check for the return code and return. (This is a trick to avoid overriding the buffer in forward call. This function is an internal part of parse().)
buff_size	The size of the output buffer (ending zero included).
p_url	The input string.
p_base	(optional) Prefix with a base to be prefixed

Returns: RET_MV_CONST_FAILED on error (buffer sizes or start and final characters), RET_MV_CONST_NOTHING normal moving or RET_MV_CONST_NEW_ENTITY there is a ";.new" ending and no errors.

Note: This replaces expand_url_encoded() since the string passed to parse() is already %-decoded by libmicrohttpd.

◆ get_right_local()

StatusCode jazz_bebop::BaseAPI::get_right_local	(	pTransaction &	p_txn,
		ApiQueryState &	q_state
	)

inlineprotected

This is an internal part of get() made independent to keep the function less crowded.

Parameters

p_txn	A pointer to the transaction that will be used to store the result.
q_state	The structure containing the parts of the url successfully parsed.

Returns: SERVICE_NO_ERROR if successful, or an error code.

Context: This in any possible assignment in which the right part is NOT a remote call. Functionally, it is similar to get_left_local(), but since it is the right of an assignment, arguments are stored at a different place and also, apply code are in range APPLY_ASSIGN_NOTHING..APPLY_ASSIGN_CONST instead of APPLY_NOTHING..APPLY_TEXT. It returns the final block as it will be returned with a new_block() interface.

◆ get_right_remote()

StatusCode jazz_bebop::BaseAPI::get_right_remote	(	pTransaction &	p_txn,
		ApiQueryState &	q_state
	)

inlineprotected

This is an internal part of get() made independent to keep the function less crowded.

Parameters

p_txn	A pointer to the transaction that will be used to store the result.
q_state	The structure containing the parts of the url successfully parsed.

Returns: SERVICE_NO_ERROR if successful, or an error code.

Context: This in any possible assignment in which the right part is a remote call. Since q_state.url does not have a valid url, itt is necessary to reconstruct it. We do have the constants if any. It returns the final block as it will be returned to the user with a new_block() interface.

◆ get_left_local()

StatusCode jazz_bebop::BaseAPI::get_left_local	(	pTransaction &	p_txn,
		ApiQueryState &	q_state
	)

inlineprotected

This is an internal part of get() made independent to keep the function less crowded.

Parameters

p_txn	A pointer to the transaction that will be used to store the result.
q_state	The structure containing the parts of the url successfully parsed.

Returns: SERVICE_NO_ERROR if successful, or an error code.

Context: This is called when q_state.apply is APPLY_NOTHING ... APPLY_TEXT and there is no forwarding. It returns the final block as it will be returned to the user with a new_block() interface.

◆ put_left_local()

StatusCode jazz_bebop::BaseAPI::put_left_local	(	ApiQueryState &	q_state,
		pBlock	p_block
	)

inlineprotected

This is an internal part of put() made independent to keep the function less crowded.

Parameters

q_state	The structure containing the parts of the url successfully parsed.
p_block	The block to be stored.

Returns: SERVICE_NO_ERROR if successful, or an error code.

Context: This in any possible assignment in which we could successfully solve the right part and have a valid p_block. We have to do a put call and return whatever status code happened.

The documentation for this class was generated from the following files:

base_api.h
base_api.cpp

Public Member Functions

Data Fields

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ BaseAPI()

Member Function Documentation

◆ id()

◆ start()

◆ shut_down()

◆ parse()

◆ block_from_const()

◆ header()

◆ get()

◆ put()

◆ remove()

Internals

◆ get_channels()

◆ get_volatile()

◆ get_persisted()

◆ parse_locator()

◆ move_const()

◆ get_right_local()

◆ get_right_remote()

◆ get_left_local()

◆ put_left_local()