SilverStream
Application Server 3.5

com.sssw.rt.util
Class AgrServerSession

java.lang.Object
 |
 +--com.sssw.rt.util.AgrServerSession

public abstract class AgrServerSession
extends Object

Represents an established server session from a non-SilverStream application This class provides methods to login and out, invoke a business object, and to get session info.

A non-SilverStream application or applet must call one of the flavors of AgRuntime.init() before attempting to contact a SilverStream server. This performs basic initialization of the SilverStream runtime packages. Next, the application must get an "AgrServerSession" object for the SilverStream server it wishes to talk to; this establishes a SilverStream session with the server (including user authentication, if required), and starts the "client heartbeat" which keeps the session alive.

In addition,the application can create AgrData's to access any data source,

See Also:
AgRuntime, AgrServerSession, AgrData

Constructor Summary
AgrServerSession()
           
 
Method Summary
 void close()
          Close the server session.
 String getHostName()
          Return the "basic" host name for this connection.
abstract  Principal getRemoteUser()
          Return an AgiUser representing the user currently logged into the remote session.
 String getServerHostName()
          Return the "actual" host name for this connection.
abstract  int getServerNamingServicePort()
          Return the Server naming service port number.
 int getServerPort()
          Return the "actual" port number (HTTP or HTTPS) on which the server serving this session is listening.
abstract  String getServerRemoteMethodProtocol()
          Return the protocol supported by the Server for remote client access.
 String getSessionId()
          Get the session ID for this session.
abstract  Serializable invokeBusinessObject(String spec)
          Invoke an invocable business object on the specified server in the specified session, and return its result.
abstract  Serializable invokeBusinessObject(String spec, Serializable param)
          Invoke an invocable business object on the specified server in the specified session, passing an argument, and return its result.
abstract  boolean isServerAlive(boolean force)
          Return true if the server is alive, false otherwise.
abstract  boolean loginUser()
          Allow a user to log on to the server.
abstract  void restart()
          Re-establish the server session for this server, if it's been closed or stopped.
abstract  void suspend()
          Suspend this server session.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AgrServerSession

public AgrServerSession()
Method Detail

loginUser

public abstract boolean loginUser()
                           throws AgoUnrecoverableSystemException,
                                  AgoSecurityException
Allow a user to log on to the server. This will result in a callback to the AgiLoginUser class provided during initialization, to prompt for user name and password.
Returns:
true if the user was successfully loggged in, or false if the user cancels.
Throws:
AgoUnrecoverableSystemException - on communications failure
AgoSecurityException - if the user supplies an incorrect user name or password

close

public void close()
Close the server session. Invalidate the session on the server (if possible), and stop the client heartbeat

suspend

public abstract void suspend()
Suspend this server session. Note that if you do this for very long (longer than the session timeout) the session will expire.

restart

public abstract void restart()
                      throws AgoUnrecoverableSystemException
Re-establish the server session for this server, if it's been closed or stopped.

invokeBusinessObject

public abstract Serializable invokeBusinessObject(String spec)
                                           throws Exception
Invoke an invocable business object on the specified server in the specified session, and return its result.
Parameters:
spec - a "full" business object specification on the server, in the form "database:BOname". For example, "MyDB:com.sssw.objs.MyObj".
Returns:
the result returned by the business object. The writer of the business object sets this by calling setResult() on the event object passed to it.
Throws:
any - exception thrown by the business object

invokeBusinessObject

public abstract Serializable invokeBusinessObject(String spec,
                                                  Serializable param)
                                           throws Exception
Invoke an invocable business object on the specified server in the specified session, passing an argument, and return its result.
Parameters:
spec - a "full" business object specification on the server, in the form "database:BOname". For example, "MyDB:com.sssw.objs.MyObj".
param - any Serializable parameter to be passed to the object
Returns:
the result returned by the business object. The writer of the business object sets this by calling setResult() on the event object passed to it.
Throws:
any - exception thrown by the business object

getSessionId

public String getSessionId()
Get the session ID for this session.

getHostName

public String getHostName()
Return the "basic" host name for this connection. In a cluster, this will be the host name of the dispatcher host; in a non-cluster, it will be the server's host name.

getServerHostName

public String getServerHostName()
Return the "actual" host name for this connection. In either a cluster or a non-cluster, it will be the server that is actually servicing the session.

getServerPort

public int getServerPort()
Return the "actual" port number (HTTP or HTTPS) on which the server serving this session is listening. In either a cluster or non-cluster, it will be a port on the server that is actually servicing the session.

getServerRemoteMethodProtocol

public abstract String getServerRemoteMethodProtocol()
                                              throws Exception
Return the protocol supported by the Server for remote client access. This is the protocol that the server will use for supporting EJB clients.

Current return values supported are:


getServerNamingServicePort

public abstract int getServerNamingServicePort()
                                        throws Exception
Return the Server naming service port number.

getRemoteUser

public abstract Principal getRemoteUser()
                                 throws AgoUnrecoverableSystemException
Return an AgiUser representing the user currently logged into the remote session. This will return an "anonymous" user if the remote session is not currently logged in.
Returns:
an AgiUser representing the remote user

isServerAlive

public abstract boolean isServerAlive(boolean force)
                               throws AgoUnrecoverableSystemException
Return true if the server is alive, false otherwise. If the 'force' flag is supplied, this method forces an immediate 'ping' of the server (which may require a long timeout if the server is down); otherwise, we depend on the last heartbeat ping.
Parameters:
force - true to force an immediate ping of the server
Returns:
true if the server is up, false otherwise
Throws:
AgoUnrecoverableSystemException - if something goes wrong

SilverStream
Application Server 3.5