com.ibm.retail.AEF.server
Interface SessionServer

All Superinterfaces:
java.rmi.Remote

public interface SessionServer
extends java.rmi.Remote

SessionServer provides the client interface for requesting AEFSession objects.

Clients may request either an "available" session (i.e., a session that is not in use by another session) or a specific session by terminal number. If no session is available, an AEFException is thrown. The session returned via a call to getAvailableSession will not be available to any other callers of getAvailableSession until the session.release method is called. Note that getting an available session does not prevent other clients from accessing the session by specifying the specific terminal number.

Examples: (server is an object of type SessionServer)

Obtaining any available session:

    try
    {
      AEFSession mySession = server.getAvailableSession();
      if (mySession != null)
      {
         System.out.println("Using terminal number: " + mySession.getTerminalNumber();
      }
    }
    catch (RemoteException re)
    {
       System.err.println("Couldn't access remote session");
    }  
    catch (AEFException ae)
    {
       System.err.println("Couldn't obtain an available session");
    }  
  

Obtaining a specific session without regard to availability:

To obtain a specific session, either specify the terminal number or, if in a non-TSS environment where only a single session exists, use the constant LOCAL_SESSION. In this case, a session is returned if it is a valid terminal number, even if it is already assigned to a client.

      AEFSession mySession = server.getSession("100");  
      AEFSession aSession = server.getSession(SessionServer.LOCAL_SESSION);  
  

Releasing a session:

Clients are responsible for releasing sessions after they are finished using the session. This mechanism allows other clients to access the session through the getAvailableSession method. Since sessions are a limited resource, this is a critical responsibility of each client and failure to perform this step may cause performance and memory degradation, and may eventually exhaust the capacity of the server.

Sessions are released through the releaseSession method:

  server.releaseSession(mySession);
  mySession = null;
  

(Note: it is important to set the session pointer to null since the client still has a valid pointer to a session, but no longer "owns" the session).


Field Summary
static java.lang.String ACTIVE
           
static java.lang.String INITIALIZING
          Valid values for the state of this object, as returned by getState()
static java.lang.String LOCAL_SESSION
          Identifier to be used to obtain the local terminal session in non-TSS.
static java.lang.String NAME
          Name used to register this object with RMI naming
 
Method Summary
 boolean addFactory(com.ibm.retail.AEF.factory.AEFSessionFactory factory)
          Register an AEFSessionFactory with the session server.
 java.lang.String addFactoryBeaconInfo(java.lang.String factoryBeaconInfo)
          Register a AEFSessionFactory with the session server given it's beacon info.
 void destroySession(java.lang.String terminalNumber)
          Destroy an AEFSession.
 com.ibm.retail.AEF.session.AEFSession getAvailableSession()
          Get an AEFSession object with a status of "available".
 com.ibm.retail.AEF.session.AEFSession getAvailableSession(int timeout)
          Get an AEFSession object with a status of "available".
 com.ibm.retail.AEF.session.AEFSession getAvailableSession(com.ibm.retail.AEF.session.SessionParameters parms)
          Get an AEFSession object with a status of "available".
 com.ibm.retail.AEF.factory.AEFSessionFactory getFactory(int index)
          Get a factory registered with this session server.
 com.ibm.retail.AEF.factory.AEFSessionFactory getFactoryFromInfo(com.ibm.retail.AEF.factory.AEFSessionFactoryInfo info, java.lang.StringBuffer narrative)
          Get a session factory reference given it's info object.
 java.util.List getFactoryIDs()
          Get the number of factories registered with this session server.
 java.lang.String getID()
          Get the identifier for this session server.
 com.ibm.retail.AEF.util.LoggerControl getLoggerControl()
          Get the LoggerControl object for the Server JVM.
 int getNumberOfFactories()
          Get the IDs of the factories registered with this session server.
 com.ibm.retail.AEF.server.SessionServer getSelfReference()
          Returns a self reference.
 com.ibm.retail.AEF.session.AEFSession getSession(java.lang.String terminalNumber)
          Get a AEFSession object by terminal number.
 com.ibm.retail.AEF.session.AEFSession getSession(java.lang.String terminalNumber, int timeout)
          Get a AEFSession object by terminal number.
 com.ibm.retail.AEF.session.AEFSession getSession(java.lang.String terminalNumber, com.ibm.retail.AEF.session.SessionParameters parms)
          Get a AEFSession object by terminal number.
 com.ibm.retail.AEF.session.AEFSession getSessionFromFactory(com.ibm.retail.AEF.factory.AEFSessionFactory factory, java.lang.String terminalNumber, com.ibm.retail.AEF.session.SessionParameters parms)
          Get a session from a factory.
 java.lang.String getState()
          Get the state of this session server.
 void releaseSession(com.ibm.retail.AEF.session.AEFSession session)
          Release an AEFSession to free it for other clients to use
 void removeFactory(com.ibm.retail.AEF.factory.AEFSessionFactory factory)
          Remove a registered AEFSessionFactory from the session server.
 boolean sessionExists(java.lang.String terminalNumber)
          Indicates if a session for this terminal number has been created.
 void updateFactory(com.ibm.retail.AEF.factory.AEFSessionFactory factory)
          Update factory info from a AEFSessionFactory with the session server.
 

Field Detail

NAME

public static final java.lang.String NAME
Name used to register this object with RMI naming

See Also:
Constant Field Values

LOCAL_SESSION

public static final java.lang.String LOCAL_SESSION
Identifier to be used to obtain the local terminal session in non-TSS. (Resolves to the actual terminal number).

Example: mySession = server.getSession(SessionServer.LOCAL_SESSION)

See Also:
Constant Field Values

INITIALIZING

public static final java.lang.String INITIALIZING
Valid values for the state of this object, as returned by getState()

See Also:
Constant Field Values

ACTIVE

public static final java.lang.String ACTIVE
See Also:
Constant Field Values
Method Detail

getAvailableSession

public com.ibm.retail.AEF.session.AEFSession getAvailableSession()
                                                          throws java.rmi.RemoteException,
                                                                 AEFException
Get an AEFSession object with a status of "available".

An AEFSession is in the available state if no other clients have references to it

This method establishes a client reference to the session and removes it from the pool of available sessions.

Clients must use the release() method to return the session to the pool of available sessions.

A session must be in a "ready state", ie ready for input. An exception is thrown otherwise. This method uses the default timeout value specified by the property ready.wait.timeout contained in the config.properties file.

If the client wishes the AEF to log some sort of client id with the session number, then the client should call getAvailableSession(parms) instead, where parms includes the client ID.

Returns:
an instance of an AEFSession object
Throws:
java.rmi.RemoteException
AEFException - if a session can not be accessed AEFException error codes are:
AEFConst.NO_SESSION_FACTORIES_FOUND, AEFConst.NONE
AEFConst.SERVER_NO_SESSION_AVAILABLE, AEFConst.NONE
AEFConst.SESSION_READY_WAIT_TIMEOUT, AEFConst.NONE - the timeout associated with ready.wait.timeout expired before the session was ready.
See Also:
Releasing a session

getAvailableSession

public com.ibm.retail.AEF.session.AEFSession getAvailableSession(int timeout)
                                                          throws java.rmi.RemoteException,
                                                                 AEFException
Get an AEFSession object with a status of "available".

An AEFSession is in the available state if no other clients have references to it.

This method establishes a client reference to the session and removes it from the pool of available sessions.

Clients must use the release() method to return the session to the pool of available sessions.

This method provides a parameter for specifying a timeout value for waiting on a "ready" session. A timeout value of -1 can be used to specify that no wait is to be performed and "non-ready" sessions should be returned. This allows clients access to sessions which have not reached the ready state.

If the client wishes the AEF to log some sort of client id with the session number, then the client should call getAvailableSession(parms) instead, where parms includes the client ID.

Parameters:
timeout - time to wait for sessions which are not ready for input (milliseconds)

Use a timeout value of -1 to indicate that the session should be returned even if it is not in a ready state.

Returns:
an instance of an AEFSession object
Throws:
java.rmi.RemoteException
AEFException - if a session can not be accessed AEFException error codes are:
AEFConst.NO_SESSION_FACTORIES_FOUND, AEFConst.NONE
AEFConst.SERVER_NO_SESSION_AVAILABLE, AEFConst.NONE
AEFConst.SESSION_READY_WAIT_TIMEOUT, AEFConst.NONE - the timeout associated with ready.wait.timeout expired before the session was ready.
See Also:
Releasing a session

getAvailableSession

public com.ibm.retail.AEF.session.AEFSession getAvailableSession(com.ibm.retail.AEF.session.SessionParameters parms)
                                                          throws java.rmi.RemoteException,
                                                                 AEFException
Get an AEFSession object with a status of "available".

An AEFSession is in the available state if no other clients have references to it.

This method establishes a client reference to the session and removes it from the pool of available sessions.

Clients must use the release() method to return the session to the pool of available sessions.

If the client wishes the AEF to log some sort of client id with the session number, then the client should call setClientID on the SessionParamemters argument. When a session is returned, an AEF log entry will be made to record the association between the client ID and the session ID. This information could be used to determine which session was associated with a particular client.

This method provides a SessionParameter object for specifying parameters.

Parameters:
parms - SessionParameters object specifies all parameters for this session
Returns:
an instance of an AEFSession object
Throws:
java.rmi.RemoteException
AEFException - if a session can not be accessed AEFException error codes are:
AEFConst.NO_SESSION_FACTORIES_FOUND, AEFConst.NONE
AEFConst.SERVER_NO_SESSION_AVAILABLE, AEFConst.NONE
AEFConst.SESSION_READY_WAIT_TIMEOUT, AEFConst.NONE - the timeout associated with ready.wait.timeout expired before the session was ready.
See Also:
Releasing a session

getSession

public com.ibm.retail.AEF.session.AEFSession getSession(java.lang.String terminalNumber)
                                                 throws java.rmi.RemoteException,
                                                        AEFException
Get a AEFSession object by terminal number.

If this is a valid terminal number for the factory, the session is returned, regardless of the number of client accesses. This allows sharing of a session among multiple clients.

This method does not remove the session from pool of available sessions. Clients can remove the session from the available session pool by invoking the reference() method of the AEFSession.

A session must be in a "ready state", ie ready for input. An exception is thrown otherwise. This method uses the default timeout value specified in the config.properties property=ready.wait.timeout.

If the client wishes the AEF to log some sort of client id with the session number, then the client should call getSession(String terminalNumber, SessionParameters parms) instead, where parms includes the client ID.

Parameters:
terminalNumber - identifies the session. Use SessionServer.LOCAL_SESSION to request the real terminal session running in a real terminal.
Returns:
an instance of an AEFSession object
Throws:
java.rmi.RemoteException
AEFException - if a session can not be accessed AEFException error codes are:
AEFConst.ERROR_ACCESSING_FACTORY, AEFConst.NONE
AEFConst.FACTORY_NO_SESSIONS_AVAILABLE, AEFConst.NONE
AEFConst.INVALID_TERMINAL_NUMBER, AEFConst.NONE
AEFConst.SESSION_READY_WAIT_TIMEOUT, AEFConst.NONE
See Also:
Referencing a session

getSession

public com.ibm.retail.AEF.session.AEFSession getSession(java.lang.String terminalNumber,
                                                        int timeout)
                                                 throws java.rmi.RemoteException,
                                                        AEFException
Get a AEFSession object by terminal number.

If this is a valid terminal number for the factory, the session is returned, regardless of the number of client accesses. This allows sharing of a session among multiple clients.

This method does not remove the session from pool of available sessions. Clients can remove the session from the available session pool by invoking the reference() method of the AEFSession.

This method provides a parameter for specifying a timeout value for waiting on a "ready" session. A timeout value of -1 can be used to specify that no wait is to be performed and "non-ready" sessions should be returned. This allows clients access to sessions which have not reached the ready state.

If the client wishes the AEF to log some sort of client id with the session number, then the client should call getSession(String terminalNumber, SessionParameters parms) instead, where parms includes the client ID.

Parameters:
terminalNumber - identifies the session. Use SessionServer.LOCAL_SESSION to request the real terminal session running in a real terminal.
Returns:
an instance of a AEFSession object
Throws:
java.rmi.RemoteException
AEFException - if a session can not be accessed AEFException error codes are:
AEFConst.INVALID_TERMINAL_NUMBER, AEFConst.NONE
AEFConst.FACTORY_NO_SESSIONS_AVAILABLE, AEFConst.NONE
AEFConst.SESSION_READY_WAIT_TIMEOUT, AEFConst.NONE
See Also:
Referencing a session

getSession

public com.ibm.retail.AEF.session.AEFSession getSession(java.lang.String terminalNumber,
                                                        com.ibm.retail.AEF.session.SessionParameters parms)
                                                 throws java.rmi.RemoteException,
                                                        AEFException
Get a AEFSession object by terminal number.

If this is a valid terminal number for the factory, the session is returned, regardless of the number of client accesses. This allows sharing of a session among multiple clients.

This method does not remove the session from pool of available sessions. Clients can remove the session from the available session pool by invoking the reference() method of the AEFSession.

This method provides a SessionParameter object for specifying the session parms.

If the client wishes the AEF to log some sort of client id with the session number, then the client should call setClientID on the SessionParamemters argument. When a session is returned, an AEF log entry will be made to record the association between the client ID and the session ID. This information could be used to determine which session was associated with a particular client.

Parameters:
terminalNumber - identifies the session. Use SessionServer.LOCAL_SESSION to request the real terminal session running in a real terminal.
parms - SessionParameters object contains the session parameter vales
Returns:
an instance of a AEFSession object
Throws:
java.rmi.RemoteException
AEFException - if a session can not be accessed AEFException error codes are:
AEFConst.INVALID_TERMINAL_NUMBER, AEFConst.NONE
AEFConst.FACTORY_NO_SESSIONS_AVAILABLE, AEFConst.NONE
AEFConst.SESSION_READY_WAIT_TIMEOUT, AEFConst.NONE
See Also:
Referencing a session

releaseSession

public void releaseSession(com.ibm.retail.AEF.session.AEFSession session)
                    throws java.rmi.RemoteException,
                           AEFException
Release an AEFSession to free it for other clients to use

Parameters:
session - AEFSession to be released
Throws:
java.rmi.RemoteException - if server is not available
AEFException - if an error occurs accessing a session

destroySession

public void destroySession(java.lang.String terminalNumber)
                    throws java.rmi.RemoteException,
                           AEFException
Destroy an AEFSession.

This method applies only to virtual (TSS) sessions. It terminates the POS sales application and removes the AEFSession from the SessionPool.

Parameters:
terminalNumber - identifies the session
Throws:
java.rmi.RemoteException
AEFException - if a session can not be destroyed AEFException error codes are:
AEFConst.SESSION_NOT_ACTIVE, AEFConst.NONE
AEFConst.API_VALID_FOR_TSS_ONLY, AEFConst.NONE
AEFConst.INVALID_TERMINAL_NUMBER, AEFConst.NONE

sessionExists

public boolean sessionExists(java.lang.String terminalNumber)
                      throws java.rmi.RemoteException
Indicates if a session for this terminal number has been created.

Returns:
true if the session for this terminal exists
Throws:
java.rmi.RemoteException

addFactory

public boolean addFactory(com.ibm.retail.AEF.factory.AEFSessionFactory factory)
                   throws java.rmi.RemoteException
Register an AEFSessionFactory with the session server.

This method is used by factories which create and provide session instances to the server. Several factories may exist on local and remote servers, load balanced by the session server.

Parameters:
factory - AEFSessionFactory to be added
Returns:
boolean true if the factory was added successfully.
Throws:
java.rmi.RemoteException

addFactoryBeaconInfo

public java.lang.String addFactoryBeaconInfo(java.lang.String factoryBeaconInfo)
                                      throws java.rmi.RemoteException
Register a AEFSessionFactory with the session server given it's beacon info.

Returns:
null if the factory was added successfully; if there was a terminal number collision with an already existing factory, then this method returns the name of the existing factory.
Throws:
java.rmi.RemoteException - if server is not available

removeFactory

public void removeFactory(com.ibm.retail.AEF.factory.AEFSessionFactory factory)
                   throws java.rmi.RemoteException
Remove a registered AEFSessionFactory from the session server.

Parameters:
factory - AEFSessionFactory to be removed
Throws:
java.rmi.RemoteException - if server is not available

updateFactory

public void updateFactory(com.ibm.retail.AEF.factory.AEFSessionFactory factory)
                   throws java.rmi.RemoteException,
                          AEFException
Update factory info from a AEFSessionFactory with the session server.

This method is used by factories as a callback to keep the SessionServer up-to-date with factory information. Several factories may exist on local and remote servers, load balanced by the session server.

Parameters:
factory - AEFSessionFactory to be updated
Throws:
java.rmi.RemoteException
AEFException

getFactoryIDs

public java.util.List getFactoryIDs()
                             throws java.rmi.RemoteException
Get the number of factories registered with this session server.

Several factories may exist on local and remote servers, load balanced by the session server.

Returns:
Number of factories
Throws:
java.rmi.RemoteException - if server is not available

getNumberOfFactories

public int getNumberOfFactories()
                         throws java.rmi.RemoteException
Get the IDs of the factories registered with this session server.

Several factories may exist on local and remote servers, load balanced by the session server.

Returns:
Number of factories
Throws:
java.rmi.RemoteException - if server is not available

getFactoryFromInfo

public com.ibm.retail.AEF.factory.AEFSessionFactory getFactoryFromInfo(com.ibm.retail.AEF.factory.AEFSessionFactoryInfo info,
                                                                       java.lang.StringBuffer narrative)
                                                                throws java.rmi.RemoteException
Get a session factory reference given it's info object. This method will attempt to establish a remote reference if we have a URI to go on. If we have a URI, but cannot establish the reference, the factory info will be removed from the session server.

Parameters:
info - The AEFSessionFactoryInfo object which contains the factory URI.
narrative - A StringBuffer to which will be appended a description of the attempt to get the factory. This may be set to null if no narrative is desired.
Returns:
AEFSessionFactory
Throws:
java.rmi.RemoteException

getSessionFromFactory

public com.ibm.retail.AEF.session.AEFSession getSessionFromFactory(com.ibm.retail.AEF.factory.AEFSessionFactory factory,
                                                                   java.lang.String terminalNumber,
                                                                   com.ibm.retail.AEF.session.SessionParameters parms)
                                                            throws java.rmi.RemoteException,
                                                                   AEFException
Get a session from a factory.

Parameters:
factory - AEFSessionFactory
terminalNumber - identifies terminal number or null for any available terminal
parms - SessionParameters object contains all parms for the session as name-value pairs.
Returns:
AEFSession
Throws:
java.rmi.RemoteException
AEFException - AEFException return codes are:
AEFConst.ERROR_ACCESSING_FACTORY, AEFConst.NONE
AEFConst.INVALID_TERMINAL_NUMBER, AEFConst.NONE
AEFConst.FACTORY_NO_SESSIONS_AVAILABLE, AEFConst.NONE
AEFConst.FACTORY_SESSION_NOT_READY, AEFConst.NONE

getFactory

public com.ibm.retail.AEF.factory.AEFSessionFactory getFactory(int index)
                                                        throws java.rmi.RemoteException,
                                                               AEFException
Get a factory registered with this session server.

Several factories may exist on local and remote servers, load balanced by the session server.

Parameters:
index - index of factory
Returns:
Factory
Throws:
AEFException
java.rmi.RemoteException

getLoggerControl

public com.ibm.retail.AEF.util.LoggerControl getLoggerControl()
                                                       throws java.rmi.RemoteException,
                                                              AEFException
Get the LoggerControl object for the Server JVM.

Returns:
instance of LoggerControl
Throws:
java.rmi.RemoteException
AEFException

getID

public java.lang.String getID()
                       throws java.rmi.RemoteException
Get the identifier for this session server.

Returns:
Server ID
Throws:
java.rmi.RemoteException

getState

public java.lang.String getState()
                          throws java.rmi.RemoteException
Get the state of this session server. Valid values are SessionServerMBean.SERVER_INITIALIZING and SessionServerMBean.SERVER_ACTIVE.

Returns:
state
Throws:
java.rmi.RemoteException

getSelfReference

public com.ibm.retail.AEF.server.SessionServer getSelfReference()
                                                         throws java.rmi.RemoteException
Returns a self reference. This method is used to retrieve the actual factory reference if given a proxy reference of the type SessionServerRef.

Returns:
SessionServer
Throws:
java.rmi.RemoteException


Copyright © 2004 IBM. All Rights Reserved.
Generated: July 19 2004