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:

• "iiop" -- Corba IIOP protocol is enabled
• "jrmp" -- Native java remote protocol is enabled

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