Main Page Class Hierarchy Compound List Compound Members SoamFactory Class Reference
Factory class for the client to allocate the soam API objects. More...
Static Public Methods
void initialize (void) throw (SoamException) Initializes the API. void uninitialize (void) throw (SoamException) Un-initializes the API. Connection * connect (const char *applicationName, ConnectionSecurityCallback *callback=SOAM_NULL_PTR) throw (SoamException) Creates a connection to the specified Symphony application. Connection * connect (const char *CURL, const char *applicationName, ConnectionSecurityCallback *callback=SOAM_NULL_PTR) throw (SoamException) Creates a connection to the specified Symphony application. void * allocateSecurityBuffer (const unsigned long buffSize) throw (SoamException) Allocates a buffer that can be managed by the security framework. void freeSecurityBuffer (void **buffer) throw (SoamException) Frees a buffer that was previously allocated from a call to SoamFactory::AllocateSecurityBuffer. Detailed Description
Factory class for the client to allocate the soam API objects.This factory class is used to allocate the SOAM API objects for the client to provide proper lifetime management for all concrete objects in the SOAM API.
NOTE: If any of the methods of this class are called after the main(...) method exits, the client or service process may behave in an undefined manner (for example, hang or terminate abnormally).
- See also:
- Connection
Member Function Documentation
void initialize ( void ) throw (SoamException) [static]
Initializes the API.
The initialize(...) method should be called before any other soam API method is called. This method is mandatory which means all other API calls will fail if this method is ommitted. initialize(...) can be called multiple times without penalty, however, best practices dictate that this should be called only once, since uninitialize(...) can only be called once.
void uninitialize ( void ) throw (SoamException) [static]
Un-initializes the API.
The uninitialize() method should be called at the end of all API calls. It should be called only once. This means that once uninitialize(...) is called no other API calls are possible for the life of the process.
** NOTE :
1. Never call uninitialize(...) during the execution of a callback method. This will result in a deadlock.
2. Ensure that the uninitialize(...) method is called before the client process exits the main(...) method. On some OS platforms, the client process may behave in an undefined manner (for example, hang or terminate abnormally) if the main(...) method exits without calling uninitialize(...).
Connection* connect ( const char * applicationName, ConnectionSecurityCallback * callback = SOAM_NULL_PTR ) throw (SoamException) [static]
Creates a connection to the specified Symphony application.
Once this connection is acquired you may proceed to interact with the application.
- Parameters:
applicationName [IN] -- The name of the application. callback [IN] -- The security callback to be used for authentication. Ensure the callback exists for the lifetime of the connection.
- Returns:
- a pointer to a Connection object.
- Exceptions:
SoamException - if the connection failed
- See also:
- Connection::createSession , ConnectionSecurityCallback
Connection* connect ( const char * CURL, const char * applicationName, ConnectionSecurityCallback * callback = SOAM_NULL_PTR ) throw (SoamException) [static]
Creates a connection to the specified Symphony application.
Once this connection is acquired you may proceed to interact with the application. This overload of the connect call accepts a Cluster Specific URL which will allow the client to connect to different clusters. Cluster Specific URLs must take the following form:
- file://< filename >
e.g. file://c:\Symphony\kernel\conf\ego.conf
The filename specified must be a valid "ego.conf" file containing all the parameters required to connect to a cluster. If the filename is left blank the default "ego.conf" file will be loaded.
Limitation: The security plugin (EGO_SEC_PLUGIN) is taken from the ego.conf file that is located in the client host's $EGO_CONFDIR directory for UNIX hosts or the%EGO_CONFDIR% directory for Windows hosts. For a Symphony DE installation that is connecting to a grid, $EGO_CONFIR is $SOAM_HOME/conf on UNIX hosts and%EGO_CONFDIR% is%SOAM_HOME%\conf on Windows hosts. This limitation means that a client machine can only connect to clusters that use the same security plugin that is specified in the EGO_CONFDIR ego.conf file.
NOTE: If you specify a Cluster Specific URL ego.conf file that is not located in the EGO_CONFDIR directory, you must ensure that the specified file contains the same EGO_SEC_PLUGIN as the ego.conf file in EGO_CONFDIR.- master_list://< host:port > [< host:port >]
e.g. master_list://host1:7870 host2:7870 host3:7870
Host port combination represents the explicit master candidate list to be used when contacting the cluster. The vemkd port is required.
NOTE : This form of specifying a Cluster Specific URL is very limited. For customization of further values, e.g. communication timeouts and security options the "file://" form must be used. If the developer chooses to use the "master_list://" form then all additional attributes and settings will be set to the defaults.
- Parameters:
CURL [IN] -- A Cluster Specific URL specifying how to connect to the cluster. applicationName [IN] -- The name of the application. callback [IN] -- The security callback to be used for authentication. Ensure the callback exists for the lifetime of the connection.
- Returns:
- a pointer to a Connection object.
- Exceptions:
SoamException - if the connection failed
- See also:
- Connection::createSession , ConnectionSecurityCallback , Connection::connect
void* allocateSecurityBuffer ( const unsigned long buffSize ) throw (SoamException) [static]
Allocates a buffer that can be managed by the security framework.
- Parameters:
buffSize [IN] -- The amount of bytes to be allocated.
- Returns:
- a pointer to the buffer.
- Exceptions:
SoamException - if the buffer cannot be allocated
void freeSecurityBuffer ( void ** buffer ) throw (SoamException) [static]
Frees a buffer that was previously allocated from a call to SoamFactory::AllocateSecurityBuffer.
- Parameters:
buffer [IN] -- The buffer being freed.
- Exceptions:
SoamException - if the buffer cannot be freed.
Date Modified: 28 Apr 2011
Platform Support: support@platform.com
Platform Information Development: doc@platform.com
Platform Computing. Accelerating Intelligence(TM).
Copyright © 2001-2009 Platform Computing Corporation. All rights reserved.