com.sssw.rt.util
Class AgRuntime

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

public class AgRuntime

extends Object

This class contains static initialization methods that may be used by non-SilverStream applications (either standalone applications or applets) to communicate with the SilverStream server. This includes supporting the ability to use:

• SilverStream Data Source Objects (via the AgrData class)
• SilverStream invocable business objects
• The SilverStream administration API (via the AgAdmin class)
• Enterprise Java Beans running on a SilverStream server

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. Finally, the application may create its AgrData's, initialize the admin API, or invoke business methods, using the AgrServerSession object.

See Also:

AgrServerSession, AgrData

Method Summary

static void	checkInitNameSpace() Verifies that SilverStream was able to initialize the JNDI name space.
static AgrServerSession	connect(String host) Create a server session on the server with the specified host name.
static AgrServerSession	connect(String host, int port) Create a server session on the server with the specified host name and port.
static AgrServerSession	connect(URL urlOnServer) Create a server session on the server named by the specified URL.
static AgrServerSession	connectRMI(String host) Create an RMI (actually, RMI/IIOP) session on the server, using the specified host name to obtain the server object to connect to.
static AgrServerSession	connectRMI(String host, int port) Create an RMI (actually, RMI/IIOP) session on the server, using the specified host name to obtain the server object to connect to.
static AgrServerSession	connectRMI(String host, int port, int rmiPort) Create an RMI (RMI/IIOP) session on the server, using the specified host name to obtain the server object to connect to.
static AgrServerSession	connectRMI(String host, int port, int rmiPort, String username, String password) Create an RMI (RMI/IIOP) session on the server, using the specified host name to obtain the server object to connect to.
static File	getApplicationRoot() Get the "application root" directory, if any.
static void	init(AgiUserLogin login) Initialize the SilverStream runtime.
static void	initFromApplet(Applet applet) Initialize the SilverStream runtime.

Methods inherited from class java.lang.Object

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

Method Detail

initFromApplet

public static void initFromApplet(Applet applet)

Initialize the SilverStream runtime. This should be the first SilverStream method called by an applet that uses any SilverStream functionality.

Parameters:

applet - the Applet object in which the SilverStream code is to run

init

public static void init(AgiUserLogin login)

Initialize the SilverStream runtime. This method should be called before use of any of the SilverStream runtime functions. Specifies the "login handler" to be called back when user credentials must be supplied. The login handler may be called back at AgRuntime.connect() time (if the server requires login for all accesses), or on reference to an object that requires login, or when the AgrServerSession.login() method is explicitly invoked. Note that this method will have no effect if used in an applet or in the SilverStream server -- user logins in an applet are always handled by the browser and there is no support for login callbacks in the server.

Parameters:

login - Callback class, to be called back if the server requires the user to log in. May be null if no login handler is required.

connect

public static AgrServerSession connect(URL urlOnServer)
                                throws AgoApiException,
                                       AgoVersionUnsupportedException

Create a server session on the server named by the specified URL. (The URL does not have to name the server itself -- it can name an arbitrary resource on the server). This method establishes a session with the specified server, which may require the user to log in to the server if the server requires authorization (via the AgiLoginUser callback specified to init()).

Parameters:

urlOnServer - the URL of an object on the server to be contacted

Returns:

an established session on the specified server

Throws:

AgoApiException - if a communication or authentication error occurs trying to contact the server.

AgoVersionUnsupportedException - if the server's protocol version number doesn't match this client

connect

public static AgrServerSession connect(String host,
                                       int port)
                                throws AgoApiException,
                                       AgoVersionUnsupportedException

Create a server session on the server with the specified host name and port. This method assumes the use of HTTP to communicate with the server; to use a different protocol, use the flavor of connect() that takes a URL or the "connectRMI" flavor. This method establishes a session with the specified server, which may require the user to log in to the server if the server requires authorization (via the AgiLoginUser callback specified to init()).

Parameters:

host - the host name (or Internet address) of the server to be contacted

port - the port number of the HTTP server on the host

Returns:

an established session on the specified server

Throws:

AgoApiException - if a communication or authentication error occurs trying to contact the server.

AgoVersionUnsupportedException - if the server's protocol version number doesn't match this client

connect

public static AgrServerSession connect(String host)
                                throws AgoApiException,
                                       AgoVersionUnsupportedException

Create a server session on the server with the specified host name. This method assumes the use of HTTP to communicate with the server and uses the default HTTP port (80). This method establishes a session with the specified server, which may require the user to log in to the server if the server requires authorization (via the AgiLoginUser callback specified to init()).

Parameters:

host - the host name (or Internet address) of the server to be contacted

Returns:

an established session on the specified server

Throws:

AgoApiException - if a communication or authentication error occurs trying to contact the server.

AgoVersionUnsupportedException - if the server's protocol version number doesn't match this client

connectRMI

public static AgrServerSession connectRMI(String host)
                                   throws AgoApiException,
                                          AgoVersionUnsupportedException

Create an RMI (actually, RMI/IIOP) session on the server, using the specified host name to obtain the server object to connect to. This method looks up the registered server object using COS naming, and connects to the server object to obtain a session. This may result in a login callback to the caller, if the server requires authentication.

Parameters:

host - the host name (or Internet address) of the server to be contacted

Returns:

an established session on the specified server

Throws:

AgoApiException - if a communication or authentication error occurs trying to contact the server.

AgoVersionUnsupportedException - if the server's protocol version number doesn't match this client

connectRMI

public static AgrServerSession connectRMI(String host,
                                          int port)
                                   throws AgoApiException,
                                          AgoVersionUnsupportedException

Create an RMI (actually, RMI/IIOP) session on the server, using the specified host name to obtain the server object to connect to. This method looks up the registered server object using COS naming, and connects to the server object to obtain a session. This may result in a login callback to the caller, if the server requires authentication.

Parameters:

host - the host name (or Internet address) of the server to be contacted

port - the port number on which the naming server on the specified host is listening

Returns:

an established session on the specified server

Throws:

AgoApiException - if a communication or authentication error occurs trying to contact the server.

AgoVersionUnsupportedException - if the server's protocol version number doesn't match this client

connectRMI

public static AgrServerSession connectRMI(String host,
                                          int port,
                                          int rmiPort)
                                   throws AgoApiException,
                                          AgoVersionUnsupportedException

Create an RMI (RMI/IIOP) session on the server, using the specified host name to obtain the server object to connect to. This method looks up the registered server object using COS naming, and connects to the server object to obtain a session. This may result in a login callback to the caller, if the server requires authentication.

Parameters:

host - The host name (or Internet address) of the server to be contacted

port - The port number on which the naming server on the specified host is listening

rmiPort - The RMI port number on which the naming server on the specified host is listening

Returns:

An established session on the specified server

Throws:

AgoApiException - If a communication or authentication error occurs trying to contact the server.

AgoVersionUnsupportedException - If the server's protocol version number doesn't match this client

connectRMI

public static AgrServerSession connectRMI(String host,
                                          int port,
                                          int rmiPort,
                                          String username,
                                          String password)
                                   throws AgoApiException,
                                          AgoVersionUnsupportedException

Create an RMI (RMI/IIOP) session on the server, using the specified host name to obtain the server object to connect to. This method looks up the registered server object using COS naming, and connects to the server object to obtain a session. Use the specified user name and password for login to the server.

Parameters:

host - The host name (or Internet address) of the server to be contacted

port - The port number on which the naming server on the specified host is listening

rmiPort - The RMI port number on which the naming server on the specified host is listening

username - The user name for login to the server

password - The password for login to the server

Returns:

An established session on the specified server

Throws:

AgoApiException - If a communication or authentication error occurs trying to contact the server.

AgoVersionUnsupportedException - If the server's protocol version number doesn't match this client

getApplicationRoot

public static File getApplicationRoot()

Get the "application root" directory, if any. This is the directory at which SilverStream is installed on the machine. For an applet, this will return null (try the getCodeBase() method on the applet for similar uses).

Returns:

The application root directory, or null if unknown.

checkInitNameSpace

public static void checkInitNameSpace()
                               throws Exception

Verifies that SilverStream was able to initialize the JNDI name space. Java forms or other clients might require that the name space be available. For other clients (like browsers) that do not actually require the name space, space initialization errors are silently ignored. However if the name space would not initialize, any application that actually requires the name space can call this method to get a clean error message.