org.openeai.implementations.services.eas.commands
Class ApplicationSessionRequestCommand

java.lang.Object
  |
  +--org.openeai.OpenEaiObject
        |
        +--org.openeai.jms.consumer.commands.ConsumerCommand
              |
              +--org.openeai.jms.consumer.commands.RequestCommandImpl
                    |
                    +--org.openeai.implementations.services.eas.commands.EnterpriseApplicationServiceCommand
                          |
                          +--org.openeai.implementations.services.eas.commands.ApplicationSessionRequestCommand

All Implemented Interfaces:

RequestCommand

public class ApplicationSessionRequestCommand

extends EnterpriseApplicationServiceCommand

implements RequestCommand

This class implements message support for the EnterpriseApplicationService.

Specifically, this command handles org.openeai.CoreApplication/ApplicationSession/Query-Request messages and replies with an org.openeai.CoreApplication/ApplicationSession/Provide-Reply. It also handles org.openeai.CoreApplication/ApplicationSession/Create-Request, org.openeai.CoreApplication/ApplicationSession/Update-Request, and org.openeai.CoreApplication/EnterpriseSession/Delete-Request messages and replies with org.openeai.CoreApplication/Generic/Response-Reply messages.

1. org.openeai.CoreApplication/ApplicationSession/Query-Request

Consults APPLSVC.T_APPLICATION_SESSION to determine if the ApplicationSession being queried for exists and is valid. It locates the ApplicationSession by ApplicationSessionId, which corresponds to APPLSVC.T_APPL_SESSION.APPL_SESSION_COOKIE_ID. If the ApplicationSession cannot be located by ApplicationSessionId, it returns an org.openeai.CoreApplication/EnterpriseSession/Provide-Reply with a status of ‘success’ and an empty DataArea as prescribed by the OpenEAI Message Protocol.

The command updates the LastActivityDate of both the ApplicationSession and the EnterpriseSession the reflect the activity of the query.

See the retrieveApplicationSession(String) method of EnterpriseApplicationServiceCommand for details on how ApplicationSessions are retrieved and validated.

2. org.openeai.CoreApplication/ApplicationSession/Create-Request

The command creates the new ApplicationSession by inserting the appropriate record into APPLSVC.T_APPL_SESSION. It also updates the LastActivityDate of the EnterpriseSession to reflect the activity of a new ApplicationSession creation.

See the createSession(ApplicationSession) method of EnterpriseApplicationServiceCommand for details on how ApplicationSessions are created.

3. org.openeai.CoreApplication/ApplicationSession/Update-Request

The command updates and ApplicationSession by updating the appropriate record in APPLSVC.T_APPL_SESSION. It also updates the LastActivityDate of the EnterpriseSession to reflect the activity of the ApplicationSession update. Only the update of the SessionEnvironment element is support. Attempts to update other elements will result in an error.

See the updateSession(ApplicationSession) method of EnterpriseApplicationServiceCommand for details on how ApplicationSessions are created.

4. org.openeai.CoreApplication/ApplicationSession/Delete-Request

As an overview, this command supports delete actions both of type 'delete' and 'purge'. When the delete action is of type 'delete' it terminates the ApplicationSession. When the delete action is of type 'purge' it removes the ApplicationSession from the EnterpriseApplicationService database.

For the purpose of historical data and auditing, a delete action of type 'purge' should really not be supported in a production deployment. However, support for a delete action of type 'purge' can be very helpful for tear down during testing. To allow support for the delete action of 'purge', set the value of the allowPurge property to 'true'. Set the value of this property to 'false' to disable support the delete action of type 'purge' as desired; for example, in a production deployment.

See the terminateSession(ApplicationSession) and purgeSession(ApplicationSession) methods of EnterpriseApplicationServiceCommand for precise details on how ApplicationSessions are terminated and purged. The command replies with a org.openeai.CoreMessaging/Generic/Response-Reply with a status of 'success' or 'failure' and appropriate error messages.

Configuration Parameters:

This command expects exactly one properties object in the command configuration with the following properties. The properties object may have any name, because it is retrieved by type.

Name	Required	Description
provideDocumentUri	yes	URI for retrieving the primed org.openeai.CoreApplication/EnterpriseSession/Provide-Reply document
responseDocumentUri	yes	URI for retrieving the primed org.openeai.CoreMessaging/Generic/Response-Reply document
maxIdleTime	no	The maximum idle time for an EnterpriseSession in seconds. If this property is specified, this command will use this value to determine if idle EnterpriseSessions should be terminated. If this property is not specified, the command will query the EnterpriseApplicationService database for the maximum idle time for an EnterpriseSession in APPLSVC.T_ENTERPRISE_SESSSION_PROPERTY. The maximum idle time is specified in that table by inserting a row for a property with a name of 'maxIdleTime' and a value of the maximum idle time in seconds. Each of these two options for specifying the maximum idle time for an EnterpriseSession has advantages and disadvantages. Most significantly, if you specify this value in the deployment descriptor, that value is set once upon initialization of this command in the EnterpriseApplicationService and available to all subsequent executions of the command. This has a slight performance advantage over querying the database for the maxIdleTime when handling each request. However, this approach has two notable disadvantages. First, if one ever wishes to change the maxIdleTime for an EnterpriseSession, you would have to bounce all instances of the EnterpriseApplicationService in sequence to reinitialize this command. Second, if the maxIdleTime is managed in the deployment descriptor, administrators must remember that the ApplicationSessionRequestCommand also validates EnterpriseSessions and must have this property set as well. The values of these two properties in these two commands must be identical. If the maxIdleTime is specified in the EnterpriseApplicationService database, then there is clearly some slight additional overhead in querying the database for this value when validating each EnterpriseSession. However, there are two distinct advantages. First, the maxIdleTime for an EnterpriseSession can be dynamically changed by simply updating the property in the database. The change will be effective immediately with no further administrative intervention. Second, if the maxIdleTime is set in the database, then it must only be maintained in that one place instead of in two command configurations.
allowPurge	yes	If allowPurge has a value of 'true' then Delete-Requests with a delete action type of purge will be processed and delete an ApplicationSession completely from the EnterpriseApplicationService database store. Support for purges can be useful in testing such as running test suites with the OpenEAI TestSuiteApplication using tear-down test steps. If allowPurge has a value of 'false' then Delete-Requests with a delete action of type purge are not supported. If such a message is received, the command replies with an org.openeai.CoreApplication/Generic/Response-Reply with containing and OpenEAI-1009 (purge disabled) error message (see below).

Error Messages:

Code	Type	Description	Explanation
OpenEAI-1001	application	Unsupported message object: [unsupported message object name]. This command expects '[supported message object name(s)]'. (in this case 'ApplicationSession')	Somehow the wrong message object name is getting placed into the message by the sending application or it is sending the wrong message entirely.
OpenEAI-1002	application	Unsupported message action: [unsupported message action name]. This command only supports '[supported message action name(s)]'. (in this case 'query', 'create', 'update', and 'delete')	Somehow the wrong message action name is getting placed into the message by the sending application or it is sending the wrong message entirely. This command supports Query-Requests, Create-Requests, Update-Requests, and Delete-Requests.
OpenEAI-1003	application	Invalid query element found in the Query-Request message. This command expects '[name of the expected query object(s)]'. (in this case 'Identifier')	A null or inappropriate query object is getting placed into the message by the sending application or it is sending the wrong message entirely. This command only supports ApplicationSession/Query-Request, which must have an Identifier as the query object.
OpenEAI-1004	application	Inauthentic request message.	The request message does not appear to come from an application that is authorized to make the request. Verify that the SenderAppId and AuthUserSignature in the request message sent in match the appropriate application name and secret application signature in the EnterpriseApplicationService database (in table APPLSVC.T_APPLICATION). More background: There are several ways to authentication messages. In the case of the EnterpriseApplicationService, administrators issue a secret signature to each application that is authorized to use the EnterpriseApplicationService in addition to all of the normal security principals and credentials that are always established for directory server and broker access. All applications that use the EnterpriseApplicationService must configure themselves to send that secret signature in the AuthUserSignature element of the ControlArea of each message they send. The command authenticates the message by comparing the AuthUserSignature and SenderAppId in the ControlArea of each message to the EnterpriseApplicationService database, specifically APPLSVC.T_APPLICATION, which contains records identifying authorized applications with their secret signatures. For details on how request authentication is performed see the authenticateMessage(Element) method of EnterpriseApplicationServiceCommand.
OpenEAI-1005	system	Error authenticating request message. The exception is: [SQLException message].	Some type of database error occurred while attempting to retrieve the application signature from the EnterpriseApplicationService database to compare it with the signature found in the message. Consult the detail of the SQLException message to get a better idea of what precisely is wrong. The database may be unavailable, there may be a problem with the query the command is using, or there may be a data error or inconsistency in the data in the EnterpriseApplicationService database.
OpenEAI-1006	application	Invalid identifier type found in the Identifier element of the Query-Request message. This command expects a type of [Identifier type(s)] (in this case 'ApplicationSession')	When querying for certain types of objects (like EnterpriseSession and ApplicationSession), the query object used is a generic Identifier. Since the Query-Requests that this command supports are only for ApplicationSession, only identifiers of type 'ApplicationSession' are allowed in these query requests. Verify that the correct Query-Request message containing the correct Identifier type is being sent by the requesting application.
OpenEAI-1007	application	Null identifier value found in the Identifier element of the Query-Request message. This command expects that a value actually be present.	For some reason, no value is being placed in the Identifier element of the Query-Request message being sent. Correct that.
OpenEAI-1008	application	Invalid delete action type. Only delete actions of type 'delete' and 'purge' are allowed.	Somehow an invalid delete action type is being set. Check the sending application or the appropriate EnterpriseObjects document to figure out how this could be and prevent it from happening.
OpenEAI-1009	application	Purge disabled. The delete action type of purge is supported by this implementation, but it is presently disabled.	This command apparently supports a delete action of type purge, but this support is configurable, because there are conditions under which a purge should be allowed (such as test and development use) and should not be allowed (such as production use). Presently, this purge support is toggled off presumably by an appropriate command configuration or runtime configuration property called something like 'allowPurge'.
OpenEAI-1010	application	Invalid delete element found in the Delete-Request message. This command expects an [delete element name(s)] (in this case 'ApplicationSession.').	Somehow there is an unsupported delete element in the message processed by this command. Verify that the sending application is sending the appropriate message and that it contains the appropriate delete element.
OpenEAI-1011	application	Invalid update element found in the NewData element of the Update-Request message. This command expects an [update element name(s)] (in this case 'ApplicationSession.').	Somehow there is an unsupported update element in the NewData element of the message processed by this command. Verify that the sending application is sending the appropriate message and that it contains the appropriate update elements in the NewData and Baseline data elements.
OpenEAI-1012	application	Invalid update element found in the BaselineData element of the Update-Request message. This command expects an [update element name(s)] (in this case 'ApplicationSession.').	Somehow there is an unsupported update element in the BaselineData element of the message processed by this command. Verify that the sending application is sending the appropriate message and that it contains the appropriate update elements in the NewData and Baseline data elements.
EnterpriseApplicationService-1008	system	Error updating the LastActivityDate of the EnterpriseSession in the database to reflect the activity of the Query-Request. The exception is: [SQLException message].	Some type of database error occurred while attempting to update the LastActivityDate of the EnterpriseSession in the EnterpriseApplicationService database. Consult the detail of the SQLException message to get a better idea of what precisely is wrong. The database may be unavailable, there may be a problem with the SQL statement the command is using, or there may be a data error or inconsistency in the data in the EnterpriseApplicationService database.
EnterpriseApplicationService-1017	system	Error retrieving the ApplicationSession from the database. The exception is: [SQLException message].	Some type of database error occurred while attempting to retrieve the ApplicationSession from the EnterpriseApplicationService database. Consult the detail of the SQLException message to get a better idea of what precisely is wrong. The database may be unavailable, there may be a problem with the query the command is using, or there may be a data error or inconsistency in the data in the EnterpriseApplicationService database.
EnterpriseApplicationService-1018	system	Error updating the LastActivityDate of the ApplicationSession in the database to reflect the activity of the Query-Request. The exception is: [SQLException message].	Some type of database error occurred while attempting to update the LastActivityDate of the ApplicationSession in the EnterpriseApplicationService database. Consult the detail of the SQLException message to get a better idea of what precisely is wrong. The database may be unavailable, there may be a problem with the SQL statement the command is using, or there may be a data error or inconsistency in the data in the EnterpriseApplicationService database.
EnterpriseApplicationService-1019	application	Error building the ApplicationSession element from the ApplicationSession object returned from the EnterpriseApplicationService database. The exception is: [EnterpriseLayoutException message].	There was an error serializing the ApplicationSession XmlEnterpriseObject that was retrieved from the EnterpriseApplicationService database to an XML string to be placed into the Provide-Reply message. Verify that the ApplicationSession object that is stored in the database for this person has allowable values.
EnterpriseApplicationService-1020	application	Error building the ApplicationSession object from the ApplicationSession element in the Create-Request message. The exception is: [EnterpriseLayoutException message].	There was an error building an ApplicationSession XmlEnterpriseObject from the ApplicationSession element used as the query object in the incoming Create-Request message. There is most likely bad data in this ApplicationSession element or its children or the element (and therefore the entire message) is not well formed and valid. Verify that the message is well formed and valid and consult the appropriate EnterpriseObjects document for the ApplicationSession object to verify that the data being passed is allowable.
EnterpriseApplicationService-1021	system	Error inserting an ApplicationSession record to create the ApplicationSession in the database. The exception is: [SQLException message].	Some type of database error occurred while attempting to insert an ApplicationSession into the EnterpriseApplicationService database. Consult the detail of the SQLException message to get a better idea of what precisely is wrong. The database may be unavailable, there may be a problem with the SQL statement the command is using, or there may be a data error or inconsistency in the data in the EnterpriseApplicationService database.
EnterpriseApplicationService-1022	application	Error building the ApplicationSession object from the ApplicationSession element in the Delete-Request message. The exception is: [EnterpriseLayoutException message].	There was an error building an ApplicationSession XmlEnterpriseObject from the ApplicationSession element used as the query object in the incoming Delete-Request message. There is most likely bad data in this EnterpriseSession element or its children or the element (and therefore the entire message) is not well formed and valid. Verify that the message is well formed and valid and consult the appropriate EnterpriseObjects document for the ApplicationSession object to verify that the data being passed is allowable.
EnterpriseApplicationService-1023	system	Error updating the database to reflect the delete action of type [delete action type] for the ApplicationSession. The exception is: [SQLException message].	Some type of database error occurred while attempting to update or delete an ApplicationSession record to terminate it or purge it from EnterpriseApplicationService database. Consult the detail of the SQLException message to get a better idea of what precisely is wrong. The database may be unavailable, there may be a problem with the SQL statement the command is using, or there may be a data error or inconsistency in the data in the EnterpriseApplicationService database.
EnterpriseApplicationService-1025	system	Error querying the database to determine if the ApplicationSession is valid. The exception is: [SQLException message].	Some type of database error occurred while attempting to query the EnterpriseApplicationService to determine if the ApplicationSession is valid. Consult the detail of the SQLException message to get a better idea of what precisely is wrong. The database may be unavailable, there may be a problem with the query the command is using, or there may be a data error or inconsistency in the data in the EnterpriseApplicationService database.
EnterpriseApplicationService-1026	system	Error updating the LastActivityDate of the EnterpriseSession in the database to reflect the activity of the Create-Request. The exception is: [CommmandException message].	Some type of error occurred while attempting to update the LastActivityDate of the EnterpriseSession to which the ApplicationSession is supposed to belong. Consult the detail of the CommandException message to get a better idea of what precisely is wrong. The database may be unavailable, there may be a problem with the SQL statement the command is using, or there may be a data error or inconsistency in the data in the EnterpriseApplicationService database.
EnterpriseApplicationService-1027	application	Error building the ApplicationSession object from the ApplicationSession element found in the NewData element in the Update-Request message. The exception is: [EnterpriseLayoutException message]	There was an error building an ApplicationSession XmlEnterpriseObject from the ApplicationSession element found in the NewData element of the Update-Request message. There is most likely bad data in this ApplicationSession element or its children or the element (and therefore the entire message) is not well formed and valid. Verify that the message is well formed and valid and consult the appropriate EnterpriseObjects document for the ApplicationSession object to verify that the data being passed is allowable.
EnterpriseApplicationService-1028	application	Error building the ApplicationSession object from the ApplicationSession element found in the BaselineDate element in the Update-Request message. The exception is: [EnterpriseLayoutException message]	There was an error building an ApplicationSession XmlEnterpriseObject from the ApplicationSession element found in the BaselineData element of the Update-Request message. There is most likely bad data in this ApplicationSession element or its children or the element (and therefore the entire message) is not well formed and valid. Verify that the message is well formed and valid and consult the appropriate EnterpriseObjects document for the ApplicationSession object to verify that the data being passed is allowable.
EnterpriseApplicationService-1029	system	Error updating the ApplicationSession record in the database. The exception is: [CommandException message]	Some type of error occurred while attempting to update the ApplicationSession in the EnterpriseApplicationService database. Consult the detail of the CommandException message to get a better idea of what precisely is wrong. The database may be unavailable, there may be a problem with the SQL statement the command is using, or there may be a data error or inconsistency in the data in the EnterpriseApplicationService database.

Version:

1.0 beta - 18 October 2002

Author:

Steve Wheat (steve@openeai.org)

See Also:

EnterpriseApplicationServiceCommand.retrieveApplicationSession(java.lang.String), EnterpriseApplicationServiceCommand.createSession(org.any_openeai_enterprise.moa.jmsobjects.coreapplication.v1_0.EnterpriseSession), EnterpriseApplicationServiceCommand.updateSession(org.any_openeai_enterprise.moa.jmsobjects.coreapplication.v1_0.ApplicationSession, org.any_openeai_enterprise.moa.jmsobjects.coreapplication.v1_0.ApplicationSession), EnterpriseApplicationServiceCommand.terminateSession(org.any_openeai_enterprise.moa.jmsobjects.coreapplication.v1_0.EnterpriseSession), EnterpriseApplicationServiceCommand#authenticateMessage, EnterpriseApplicationServiceCommand

Field Summary

Fields inherited from class org.openeai.implementations.services.eas.commands.EnterpriseApplicationServiceCommand

m_allowPurge, m_connPool, m_maxIdleTime, m_provideDoc, m_responseDoc

Fields inherited from class org.openeai.jms.consumer.commands.ConsumerCommand

CREATE_ACTION, DELETE_ACTION, MESSAGE_ACTION, MESSAGE_CATEGORY, MESSAGE_OBJECT, MESSAGE_RELEASE, MESSAGE_TYPE, QUERY_ACTION, UPDATE_ACTION

Fields inherited from class org.openeai.OpenEaiObject

logger

Constructor Summary

ApplicationSessionRequestCommand(CommandConfig cConfig)
Constructor

Method Summary

javax.jms.Message

execute(int messageNumber, javax.jms.Message aMessage) Method used to implement business logic specific to a message or set of messages consumed by a OpenEAI PointToPointConsumer.

Methods inherited from class org.openeai.implementations.services.eas.commands.EnterpriseApplicationServiceCommand

createSession, createSession, getEnterpriseId, getEnterpriseIdString, getExistingValidEnterpriseSessionId, isMessageAuthentic, isSessionValid, isSessionValid, purgeSession, purgeSession, retrieveApplicationSession, retrieveEnterpriseSession, retrieveEnterpriseUser, terminateSession, terminateSession, updateSession, updateSessionActivity, updateSessionActivity, validEnterpriseSessionExists

Methods inherited from class org.openeai.jms.consumer.commands.RequestCommandImpl

buildReplyDocument, buildReplyDocumentWithErrors, buildReplyDocumentWithErrors, getMessage

Methods inherited from class org.openeai.jms.consumer.commands.ConsumerCommand

addAppConfig, buildError, convertToString, generateRelease, getAppConfig, getAppConfigs, getControlArea, getInboundXmlValidation, getMessageAction, getMessageBody, getMessageCategory, getMessageDumpDirectory, getMessageObject, getMessageRelease, getMessageType, getMsgComponents, getOutboundXmlValidation, initializeInput, setAppConfig, setInboundXmlValidation, setMessageDumpDirectory, setMsgComponents, setOutboundXmlValidation, setWriteToFile, writeMessageToFile, writeToFile

Methods inherited from class org.openeai.OpenEaiObject

addLog4jProperty, getAppName, getDebug, getFromAddr, getLog4jProperties, getMailHost, getMailService, getProperties, getToAddr, initializeLog4j, initializeLog4j, initializeLog4j, setAppName, setDebug, setFromAddr, setMailHost, setMailService, setProperties, setToAddr

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ApplicationSessionRequestCommand

public ApplicationSessionRequestCommand(CommandConfig cConfig)
                                 throws java.lang.InstantiationException

Constructor

Method Detail

execute

public final javax.jms.Message execute(int messageNumber,
                                       javax.jms.Message aMessage)
                                throws CommandException

Description copied from interface: RequestCommand

Method used to implement business logic specific to a message or set of messages consumed by a OpenEAI PointToPointConsumer. When a consumer consumes a message it determines which RequestCommand implementation to execute and calls this method passing the JMS Message. The command then retrieves the body of the message and converts that into an XML Document (org.jdom.Document). Then the command executes business logic appropriate to it based on the contents of the message.

Specified by:

execute in interface RequestCommand

Returns:

Message the JMS Message that should be returned to the calling application after the command has performed its business logic.

CommandException

See Also:

SyncCommand.execute