5) APyaX Server-side API

APyaX Server-side services can be invoked from the apyax object which is passed as the first parameter to every python function invoked via APyaX.

APyaX provides simple session management. In web services, sessions provide a mechanism for persisting data between function calls originating from the same client. Sessions provide a dictionary-like container for storing and retrieving values, and are usually associated with a timeout.

5.1) Opening and Closing Sessions

The methods getSession and closeSession can be invoked on the apyax object to manage the lifetime of a session object.

class apyax
Server side object to provide APyaX services
method getSession
def getSession(self,sessionType='default',readOnly=False)

Opens a session, and returns an apyax_session object.

The getSession method will re-open an existing session, or if necessary create a new session.

Parameters
sessionTypea string which, if provided, opens a session object which is identified by the both the originating client and the sessionType string. By using different values for sessionType, python functions may open multiple independent session objects.
readOnlya boolean value which, if true, specifies that any updates to the session object will not be persisted after the python function completes. Use this flag to improve concurrency between session objects when multiple functions may be executing at the same time, because most implementations can only open a session for writing in one function at any time (the others will be blocked).
Return Value
an apyax_session object
method closeSession
def closeSession(self,sessionType='default')

Closes the session (identified by the optional sessionType string, if supplied).

Parameters
sessionTypestring name of the session, default value is default

5.2) Configuring Sessions

APyaX provides an optional method for configuring sessions, using a Windows INI style file which is located via the path stored in the environment variable $APYAXCFG.





[TEST]

session.timeout = 3600
session.storage_directory = /tmp/
session.environment.sysname = spam

[PRODUCTION]
session.timeout = 3600
session.storage_directory = /usr/local/production_sessions/
session.environment.sysname = eggs

Contents of an example APyaX configuration file


Each section in the configuration file provides settings for sessions of a specified type. In the example given above, configuration for two session types TEST and PRODUCTION are given. The following keys in the APyaX configuration file are explained below:

session.timeout = <timeout-seconds>

...specifies an integer <timeout-seconds> representing the timeout for sessions of the given type in seconds. The default value is 3600 (1 hour).

session.storage_directory = <directory>

...where sessions have file based storage, specifies the directory in which the session files should be stored.

session.environment.<keyname> = <value>

specifies an initial value of <val> for the key <keyname>.

To configure certain global options, create a section called [apyax]. Currently, only options controlling the global log can be configured, these are discussed further in section 10.

5.3) Other APyaX Services

class apyax
Server side object to provide APyaX services
method getVersion
def getVersion(self)

Gets the version number

Return Value
(VMajor,VMinor) tuple
method getDownloadURL
def getDownloadURL(self,method,download_key)

Gets the download URL for a given download key

returns a URL which will retrieve content identified by a key from a method in the same script as the currently executing method. See section 6 for more information on APyaX file download.

Parameters
methodthe name of the download method (within the python script invoked in the current apyax call)
download_keythe value of the download key
Return Value
URL string
method getLog
def getLog(self)

Gets the logger object

Return Value
an APyaX logging object which provides services for logging (logging is discussed further in section 10).
method raiseError
def raiseError(self,msg,code=0,detail='')

Raises a user-defined exception

Parameters
msgan error message
codethe (optional) error code
detailmore (optional) details on the error

5.4) APyaX Session Services The method getSession can be invoked on the apyax object to open a named session. The resulting object has the following methods:

class apyax_session
Provide APyaX session-specific services
method __getitem__
def __getitem__(self,key)

Dictionary read-access to keyed values, eg =session[key]

Keys are given as strings. Values can be any object that can be represented using JSON.

Parameters
keythe dictionary key
Return Value
value for key or None if no value found for the given key
method __setitem__
def __setitem__(self,key,val)

Dictionary write-access to keyed values, eg session[key]=

Keys are given as strings. Values can be any object that can be represented using JSON. A value of None will remve the key from the dictionary

Parameters
keythe dictionary key
valuethe value to assign for the given key
method getSessionType
def getSessionType(self)

Determine the type of this session

Return Value
a string value containing the session type
method getSessionTimeout
def getSessionTimeout(self)

Determine the timeout setting for this session

Return Value
the session timeout, in seconds
method getSessionId
def getSessionId(self)

Uniquely identify this session

Return Value
a string uniquely identifying the session
method getDbAdapter
def getDbAdapter(self)

Retrieve the database adapter configured for this session

Retrieve the database adapter object configured for this session, or None if no database adapter is configured. The database adapter is a factory for opening connections to a designated database. See section 9 for more details on database adapters.

Return Value
database adapter for this session, or None
method getLog
def getLog(self,key='')

Gets the logger object

Return Value
an APyaX logging object specific to this session which provides services for logging (logging is discussed further in section 10).
method load
def load(self)

(Re)load session information load the session from persistent storage. This has the effect of undoing any changes made to the session within the function. Note that when the session is first opened within a function, it is automatically loaded from persistent storage.

method save
def save(self)

Save session information

Save any changes to the session to persistent storage (has no effect if session was opened in readOnly mode). Note that at the end of a python function call, all APyaX sessions which were opened during the function call (but were not opened in readOnly mode) are automatically saved.