satin.aro
Class AROremoteServer

java.lang.Object
  |
  +--satin.aro.AROremoteServer

Direct Known Subclasses:

RemoteLauncher

public class AROremoteServer
extends java.lang.Object

This class represents a connection with an ARO server. It is used only by ARO clients, not by ARO servers. The connection is established by the object's constructor.

Author:

Ed Stauff

Field Summary

java.io.Writer	aroLog When this field is non-null, every ARO function call is logged to this stream.
static java.io.PrintStream	debugStream If not null, debugging statements will be written to this stream.
static java.io.Writer	defaultAROlog Copied into aroLog during construction.
int	defaultTimeout The default timeout value, in seconds, for waiting for responses to requests.
protected AROobjectID	server The ARO object ID of the ARO server object.
java.io.Writer	uiLog When this field is non-null, ARO functions that manipulate the server application's UI (directly or indirectly) are logged to this stream.

Constructor Summary

AROremoteServer(java.lang.String host, int port)
Establishes a connection with an ARO server.

Method Summary

void	close() Closes the connection.
boolean	exists(AROobject obj) Returns whether the given ARO object still exists in the ARO server.
protected void	finalize() Terminates the TCP/IP connection when there are no more references to the object.
java.lang.String	getClassName(AROobject obj) Returns the name of the ARO class for the given ARO object.
java.lang.String[]	getClassNames() Returns the ARO class names recognized by the server.
long	getCumReqTime() Returns the cumulative time spent processing ARO requests, including the time spent sending the request and waiting for a response.
java.lang.String[]	getGlobalSubroutineNames() Returns the global subroutine names recognized by the server.
java.lang.String[]	getMethodNames(java.lang.String className) Returns the method names recognized by the server for the given class.
AROobjectID	getServerID() Returns the ARO object ID of the server itself.
AROincomingResponse	makeRequest(AROoutgoingRequest request, int timeout) Sends a request and returns the response.
AROincomingResponse	makeRequestAndThrow(AROoutgoingRequest request) Sends a request and returns the non-exception response.
AROincomingResponse	makeRequestAndThrow(AROoutgoingRequest request, int timeout) Sends a request and returns the non-exception response.
void	sleep(int seconds) Causes the ARO server to sleep for the given number of seconds.

Methods inherited from class java.lang.Object

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

Field Detail

debugStream

public static java.io.PrintStream debugStream

If not null, debugging statements will be written to this stream.

defaultTimeout

public int defaultTimeout

The default timeout value, in seconds, for waiting for responses to requests. Its initial value is 10. There is no magic value to make it wait forever. The timeout can be set for individual requests.

server

protected AROobjectID server

The ARO object ID of the ARO server object.

aroLog

public java.io.Writer aroLog

When this field is non-null, every ARO function call is logged to this stream. Each request begins with '>' and ends with a newline. Each response begins with '<' and ends with a newline.

defaultAROlog

public static java.io.Writer defaultAROlog

Copied into aroLog during construction. This provides a way of logging the ARO traffic that happens during construction of the AROserver.

uiLog

public java.io.Writer uiLog

When this field is non-null, ARO functions that manipulate the server application's UI (directly or indirectly) are logged to this stream. By convention, for any single operation, the uiLog is written before the aroLog.

Constructor Detail

AROremoteServer

public AROremoteServer(java.lang.String host,
                       int port)
                throws java.io.IOException,
                       AROexception

Establishes a connection with an ARO server. Throws an exception if the connection cannot be made.

Parameters:

host

host name or dotted IP address of the system on which the ARO server is running; null or an empty string indicates the local system.

port

the TCP port number on which the server is listening.

Method Detail

finalize

protected void finalize()
                 throws java.lang.Throwable

Terminates the TCP/IP connection when there are no more references to the object.

Overrides:

finalize in class java.lang.Object

close

public void close()
           throws java.lang.Throwable

Closes the connection. You should call this when you are done with the remote server object; don't count on the finalize method getting called when you want it to be. The remote server object is effectively useless after calling this method: you can't call any other methods or you'll get exceptions.

getServerID

public AROobjectID getServerID()

Returns the ARO object ID of the server itself. This is intended primarily for testing the ARO server.

Returns:

the server's object ID.

makeRequest

public AROincomingResponse makeRequest(AROoutgoingRequest request,
                                       int timeout)
                                throws java.io.IOException

Sends a request and returns the response.

Parameters:

request

the request to send to the ARO server.

timeout

how long to wait for a response, in seconds, before giving up. If < 0, uses defaultTimeout instead.

Returns:

the response from the server, which may be an exception.

makeRequestAndThrow

public AROincomingResponse makeRequestAndThrow(AROoutgoingRequest request,
                                               int timeout)
                                        throws java.io.IOException,
                                               AROexception

Sends a request and returns the non-exception response. If the response is an exception, the exception is thrown.

Parameters:

request

the request to send to the ARO server.

timeout

how long to wait for a response, in seconds, before giving up. If < 0, uses defaultTimeout instead.

Returns:

the response from the server.

makeRequestAndThrow

public AROincomingResponse makeRequestAndThrow(AROoutgoingRequest request)
                                        throws java.io.IOException,
                                               AROexception

Sends a request and returns the non-exception response. If the response is an exception, the exception is thrown. This is the form of makeRequest*** you should use in most cases.

Parameters:

request

the request to send to the ARO server.

Returns:

the response from the server.

getCumReqTime

public long getCumReqTime()

Returns the cumulative time spent processing ARO requests, including the time spent sending the request and waiting for a response.

getClassNames

public java.lang.String[] getClassNames()
                                 throws java.io.IOException,
                                        AROexception

Returns the ARO class names recognized by the server.

Returns:

an array of String containing one string for each class.

getGlobalSubroutineNames

public java.lang.String[] getGlobalSubroutineNames()
                                            throws java.io.IOException,
                                                   AROexception

Returns the global subroutine names recognized by the server.

Returns:

an array of String containing one string for each subroutine.

getMethodNames

public java.lang.String[] getMethodNames(java.lang.String className)
                                  throws java.io.IOException,
                                         AROexception

Returns the method names recognized by the server for the given class.

Parameters:

className

the name of the ARO class.

Returns:

an array of String containing one string for each method.

getClassName

public java.lang.String getClassName(AROobject obj)
                              throws java.io.IOException,
                                     AROexception

Returns the name of the ARO class for the given ARO object.

Parameters:

obj

the ARO object whose class name will be returned.

Returns:

the name of the ARO class of the object.

exists

public boolean exists(AROobject obj)
               throws java.io.IOException,
                      AROexception

Returns whether the given ARO object still exists in the ARO server.

Parameters:

obj

the ARO object to test.

Returns:

true if it still exists, false if it does not.

sleep

public void sleep(int seconds)
           throws java.io.IOException,
                  AROexception

Causes the ARO server to sleep for the given number of seconds. This ARO request is typically processed in the main event loop of the application in which the ARO server is embedded, during the application's idle time. Therefore, sleep(0) can be used to wait for the application to become idle.

Revision History

7/10/01 Ed Stauff - added finalize and close method.

6/26/01 Ed Stauff - added getServerID method.

6/7/01 Ed Stauff - added exists method.

6/6/01 Ed Stauff - changes per initial code review.

5/1/01 Ed Stauff - replaced Vectors with arrays.

4/16/01 Ed Stauff - added debugStream.

3/16/01 Ed Stauff - replaced SimpleOutputStream with Writer.

3/13/01 Ed Stauff - doc published for initial review.