tw.net.ocs
Class OCSClient

java.lang.Object
  extended by tw.net.ocs.OCSClient
All Implemented Interfaces:
java.io.Serializable

public final class OCSClient
extends java.lang.Object
implements java.io.Serializable

OCSClient manages communication of client-side proxies
with their server-side subjects via an associated OCSServer.

Several OCSClient instances can be maintained in the class.

If none has been created explicitely, one OCSClient instance
exists which links directly with an OCSServer instance for
local use.

There are methods to
        create and retrieve instances,
        set the passwords required for users and administrators,
        set the key to use for encrypted data transmission,
        get proxies allowing access to OCSServer methods, and
        miscellaneous.
        

Author:
Tillmann Wegst
See Also:
OCSServerAdminInterface, OCSServerUserInterface

Method Summary
static OCSClient createInstance()
           Creates and returns an OCSClient instance with default parameters.
static OCSClient createInstance(OCSServer server, java.lang.String name, boolean standard)
           Creates and returns an OCSClient instance which communicates with an OCSServer identified by object.
static OCSClient createInstance(java.lang.String host, int port, java.lang.String name, boolean standard)
           Creates and returns an OCSClient instance.
 void detachProxy(java.lang.Class c, java.lang.String subjectID)
          Detaches a proxy from its subject.
 void disconnect()
           Disconnects the OCSClient from the server.
static OCSClient getInstance(OCSServer server)
           Returns an instance connected to a server specified by instance.
static OCSClient getInstance(java.lang.String name)
          Returns an OCSClient instance identified by name
static OCSClient getInstance(java.lang.String host, int port)
           Returns an instance connected to a server specified by host and port.
static java.util.Collection<OCSClient> getInstances()
          Returns all instances.
 java.lang.String getName()
          Returns the name of the instance.
 java.lang.String getServerAddress()
           Returns the address of the server connected to this OCSClient.
 OCSServerAdminInterface getServerAdminProxy()
           Returns an object that allows to call admin methods on the server.
 java.lang.String getServerHost()
           Returns the host address of the server.
 int getServerPort()
           Returns the port of the server.
 OCSServerUserInterface getServerUserProxy()
           Returns an object that allows to call methods on the server that are open to all users.
static OCSClient getStandardInstance()
          Returns the currently standard OCSClient instance
 boolean isLocal()
          Tells whether the client is working in local mode, referencing the server directly
 boolean isStandardInstance()
           Tells whether this instance is the current standard instance.
static void main(java.lang.String[] args)
           Allows to stop and ping a server, also to retrieve version information.
 java.lang.Object send(int request, java.lang.Class c, java.lang.String subjectID, java.lang.String method, java.lang.Class[] parameterTypes, java.lang.Object[] parameters)
          Sends a proxy's request to the server
 void setAdminPassword(java.lang.String pw)
           Sets a password used to authorize the client for administrative functions.
 void setAsStandardInstance()
           Makes this instance the new standard.
 void setEncryptionKey(java.lang.String key)
           Sets the key for encrypted data transmission.
 void setUserPassword(java.lang.String pw)
           Sets a password used to authorize the client for normal user operations.
 void setVerbose(boolean value)
           Tells the client to print some accompanying messages to the console.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

createInstance

public static OCSClient createInstance(java.lang.String host,
                                       int port,
                                       java.lang.String name,
                                       boolean standard)
Creates and returns an OCSClient instance.

The new instance attaches to a server running at
a certain host and listening at a certain port,
it carries a name and may be made the new standard
OCSClient instance.

If no name is specified, "[host]:[port]" is assumed.
If an instance of the specified name exists already,
the new name is made unique by appending "/[number]".
                

Parameters:
host - host of the server to communicate with
port - port of the server
name - name of the new OCSClient instance
standard - make it the new standard instance?
Returns:
an appropriately configured OCSClient instance

createInstance

public static OCSClient createInstance()
Creates and returns an OCSClient instance
with default parameters.

The new instance attaches to a server on
localhost listening at the default port 23229,
is named accordingly "localhost:23229", and
made the standard OCSClient instance.
                

Returns:
an appropriately configured OCSClient instance

createInstance

public static OCSClient createInstance(OCSServer server,
                                       java.lang.String name,
                                       boolean standard)
Creates and returns an OCSClient instance which communicates
with an OCSServer identified by object.

If the OCSServer is configured for local use, the new
OCSClient instance will link directly to the server
and exchange data with it without networking.

Otherwise, client and server will communicate over the network.
In this case client and server may reside on the same host
and live in the same virtual machine, but not necessarily so: 

The client may itself subsequently get transmitted to a remote
server and then be used to communicate with another server
hosted locally (where it had been created).
                

Parameters:
server - the OCSServer which the new OCSClient shall attach to
name - the name of the OCSClient
standard - make this instance the new standard instance?
Returns:
an appropriately configured OCSClient instance

getStandardInstance

public static OCSClient getStandardInstance()
Returns the currently standard OCSClient instance


setAsStandardInstance

public void setAsStandardInstance()
Makes this instance the new standard.
                

Since:
1.3.1

isStandardInstance

public boolean isStandardInstance()
Tells whether this instance is the current standard instance.
                

Returns:
true if and only if this is the standard instance
Since:
1.3.2

getName

public java.lang.String getName()
Returns the name of the instance.

Returns:
the name
Since:
1.3

getInstance

public static OCSClient getInstance(OCSServer server)
Returns an instance connected to a server specified by instance.

The server may or may not be directly linked to the client,
client and server must reside on the same host, however.

If there is more than one client connecting with this server,
the method returns an arbitrary instance.
                

Parameters:
server - the server that the client is associated with
Returns:
the OCSClient or null
Since:
1.3
See Also:
getInstance(java.lang.String)

getInstance

public static OCSClient getInstance(java.lang.String host,
                                    int port)
Returns an instance connected to a server specified by host and port.

If there is more than one client connecting with this server,
the method returns an arbitrary instance.

Note that clients directly linked to local servers cannot be
retrieved with this method.
                

Parameters:
host - the host address of the server
port - the port of the server
Returns:
the OCSClient or null
Since:
1.3
See Also:
getInstance(java.lang.String)

getInstance

public static OCSClient getInstance(java.lang.String name)
Returns an OCSClient instance identified by name

Parameters:
name - name of the OCSClient instance
Returns:
the OCSClient so named or null

getInstances

public static java.util.Collection<OCSClient> getInstances()
Returns all instances.

Returns:
the collection of OCSClient instances
Since:
1.3

isLocal

public boolean isLocal()
Tells whether the client is working in local mode, referencing the server directly

Returns:
true if the client links directly with the server

setUserPassword

public void setUserPassword(java.lang.String pw)
Sets a password used to authorize
the client for normal user operations.

Note: If no password has been set in
the OCSServer, access to user operations
on the server is unrestricted.
                

Parameters:
pw - the password

setAdminPassword

public void setAdminPassword(java.lang.String pw)
Sets a password used to authorize
the client for administrative functions.

Note: If no password has been set in
the OCSServer, access to admin operations
on the server is forbidden.
                

Parameters:
pw - the password

setEncryptionKey

public void setEncryptionKey(java.lang.String key)
Sets the key for encrypted data transmission.

Setting a key means that encryption begins.
Specifying null stops encryption.

(Encryption is inactive if the client is
used locally.)
                

Parameters:
key - the encryption key or null
Since:
1.3

detachProxy

public void detachProxy(java.lang.Class c,
                        java.lang.String subjectID)
Detaches a proxy from its subject.

Parameters:
c - the class of the subject
subjectID - the ID of the subject
Since:
1.3

send

public java.lang.Object send(int request,
                             java.lang.Class c,
                             java.lang.String subjectID,
                             java.lang.String method,
                             java.lang.Class[] parameterTypes,
                             java.lang.Object[] parameters)
Sends a proxy's request to the server.
Returns:
an object (possibly an OCSRuntimeException)

disconnect

public void disconnect()
Disconnects the OCSClient from the server.

Note that this call does not disable the OCSClient
in any way!
If the OCSClient is used next time, another connection
will be established automatically and transparently.

The sole purpose of this method is to free up resources
on the server, concretely: it finishes the thread which
is dedicated to serving the connection to this OCSClient.

Calling disconnect() from time to time, e.g. when some
substantial unit of work is done or, of course, when this
OCSClient will not be used anymore, may be called a good
and sound idea.

Note that disconnect() gets called automatically when
the process is about to terminate.
                


toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

getServerAddress

public java.lang.String getServerAddress()
Returns the address of the server connected to this OCSClient.

The address has either the form {host}:{port} or it is the
string "LOCAL" (if an OCSServer instance is directly linked
to this OCSClient).
                

Returns:
the address of a remote server or "LOCAL"

getServerHost

public java.lang.String getServerHost()
Returns the host address of the server.

If the client references an OCSServer directly
it returns "LOCAL" .
                

Returns:
the address of a remote server's host or "LOCAL"

getServerPort

public int getServerPort()
Returns the port of the server.

If the client references an OCSServer instance directly,
the value is Server.LOCAL (=-1).
                

Returns:
the port of the server

setVerbose

public void setVerbose(boolean value)
Tells the client to print some accompanying
messages to the console.

Default is off.
                

Parameters:
value - verbose on or off

getServerAdminProxy

public OCSServerAdminInterface getServerAdminProxy()
Returns an object that allows to call admin methods
on the server.

The returned object implements all the methods declared in
the OCSServerAdminInterface interface, and delegates their invocation
to the OCSServer instance associated with this OCSClient.

Note that the execution of administrative methods requires a
valid admin password.
                

Returns:
an object allowing access to admin functions on the server
See Also:
setAdminPassword(java.lang.String), getServerUserProxy()

getServerUserProxy

public OCSServerUserInterface getServerUserProxy()
Returns an object that allows to call methods
on the server that are open to all users.

The returned object implements all the methods declared in
the OCSServerUserInterface interface, and delegates their invocation
to the OCSServer instance associated with this OCSClient.

Note that the execution of user methods may require a
valid user password.
                

Returns:
an object allowing access to user functions on the server
See Also:
setUserPassword(java.lang.String), getServerAdminProxy()

main

public static void main(java.lang.String[] args)
Allows to stop and ping a server,
also to retrieve version information.

Stopping and pinging require an admin password
for authorization.
Connecting to the server may also require that
a key for data encryption is set.

Usage:
        tw.net.ocs.OCSClient {parameters...}

        -ping           Checks the connection to a server
        -stop           Stops a server
        -host           Host of the server (opt., default is localhost)
        -port           Port of the server (opt., default is 23229)
        -adminPassword  Password required for admin functions
        -encryptionKey  Encrypt data using this key
        -version        Show OCSelot version info
        -licensee       Show licensee name
                

See Also:
getServerAdminProxy(), getServerUserProxy()


OCSelot @ www.ocselot.net www.ocselot.net