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

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.EnterpriseSessionRequestCommand

All Implemented Interfaces:

RequestCommand

public class EnterpriseSessionRequestCommand

extends EnterpriseApplicationServiceCommand

implements RequestCommand

This class implements message support for the EnterpriseApplicationService.

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

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

Consults APPLSVC.T_ENTERPRISE_SESSION to determine if the EnterpriseSession being queried for exists and is valid. It locates the EnterpriseSession by EnterpriseSessionId, which corresponds to APPLSVC.T_ENTERPRISE_SESSION.ENTERPRISE_SESSION_COOKIE_ID. If the EnterpriseSession cannot be located by EnterpriseSessionId, 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.

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

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

If the EnterpriseUser already has a valid EnterpriseSession, this command replies with an org.openeai.CoreMessaging/Generic/Response-Reply with a status of ‘failure’ and an error indicating that the EnterpriseUser already has an active and valid EnterpriseSession. The generic response reply also includes an error that contains the EnterpriseSessionId of the currently valid and active EnterpriseSession. This EnterpriseSessionId can be used by authentication and authorization foundation components to query for that pre-existing EnterpriseSession.

It creates the new EnterpriseSession by inserting the appropriate record into APPLSVC.T_ENTERPRISE_SESSION.

3. org.openeai.CoreApplication/EnterpriseSession/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 EnterpriseSession. When the delete action is of type 'purge' it removes the EnterpriseSession 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(EnterpriseSession) and purgeSession(EnterpriseSession) methods of EnterpriseApplicationServiceCommand for precise details on how EnterpriseSessions 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 EnterpriseSession 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 'EnterpriseSession')	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')	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 only supports Query-Requests, Create-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 EnterpriseSession/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 isMessageAuthentic(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 'EnterpriseSession')	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 EnterpriseSession, only identifiers of type 'EnterpriseSession' 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 'EnterpriseSession.').	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.
EnterpriseApplicationService-1007	system	Error retrieving the EnterpriseSession from the database. The exception is: [SQLException message].	Some type of database error occurred while attempting to retrieve the EnterpriseSession 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-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-1009	application	Error building EnterpriseSession element from the EnterpriseSession object returned from the EnterpriseApplicationService database. The exception is: [EnterpriseLayoutException message].	There was an error serializing the EnterpriseSession XmlEnterpriseObject that was retrieved from the EnterpriseApplicationService database to an XML string to be placed into the Provide-Reply message. Verify that the EnterpriseSession object that is stored in the database for this person is well formed and has allowable values.
EnterpriseApplicationService-1010	application	Error building the EnterpriseSession object from the EnterpriseSession element in the Create-Request message. The exception is: [EnterpriseLayoutException message].	There was an error building an EnterpriseSession XmlEnterpriseObject from the EnterpriseSession element used as the query object in the incoming Create-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 EnterpriseSession object to verify that the data being passed is allowable.
EnterpriseApplicationService-1011	application	Cannot create a new EnterpriseSession for EnterpriseUser with EnterpriseId. The EnterpriseUser already has a valid EnterpriseSession.	For some reason, a new EnterpriseSession create is being requested for an EnterpriseUser who already has a currently active and valid EnterpriseSession. An EnterpriseUser may have no more than one active and valid EnterpriseSession at any given point in time.
EnterpriseApplicationService-1012	application	[EnterpriseSessionId]	This error is returned in tandem in with EnterpriseApplicatinService-1011. It contains only the EnterpriseSessionId of the pre-existing valid EnterpriseSession for the EnterpriseUser. The requesting applications (for example, the EnterpriseAuthenticationServlet) can parse this error message and use the EnterpriseSessionId to query for the EnterpriseUser's pre-existing EnterpriseSession.
EnterpriseApplicationService-1013	system	Error querying for a pre-existing, valid EnterpriseSession. The exception is: [SQLException message]	Some type of database error occurred while attempting to query for a pre-existing, valid 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 query the command is using, or there may be a data error or inconsistency in the data in the EnterpriseApplicationService database.
EnterpriseApplicationService-1014	system	Error inserting an EnterpriseSession record to create the EnterpriseSession in the database. The exception is: [SQLException message].	Some type of database error occurred while attempting to insert an EnterpriseSession 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-1015	application	Error building the EnterpriseSession object from the EnterpriseSession element in the Delete-Request message. The exception is: [EnterpriseLayoutException message].	There was an error building an EnterpriseSession XmlEnterpriseObject from the EnterpriseSession 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 EnterpriseSession object to verify that the data being passed is allowable.
EnterpriseApplicationService-1016	system	Error updating the database to reflect the delete action of type [delete action type] for the EnterpriseSession. The exception is: [SQLException message].	Some type of database error occurred while attempting to update or delete an EnterpriseSession 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-1024	system	Error querying the database to determine if the EnterpriseSession is valid. The exception is: [SQLException message].	Some type of database error occurred while attempting to query the EnterpriseApplicationService to determine if the EnterpriseSession 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.

Version:

1.0 beta - 18 October 2002

Author:

Steve Wheat (steve@openeai.org)

See Also:

EnterpriseApplicationServiceCommand.retrieveEnterpriseSession(java.lang.String), 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

EnterpriseSessionRequestCommand(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

EnterpriseSessionRequestCommand

public EnterpriseSessionRequestCommand(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