tw.net.ocs
Class OCSServer

java.lang.Object
  extended by tw.net.Server
      extended by tw.net.ocs.OCSServer
All Implemented Interfaces:
OCSServerAdminInterface, OCSServerUserInterface

public final class OCSServer
extends Server
implements OCSServerUserInterface, OCSServerAdminInterface

The OCSServer receives requests from the client-side
proxies and routes them to associated subjects.

Several server instances can be maintained in the class.
If none is created explicitly, one server instance exists
which can be directly linked to an OCSClient for local
communication.

There are methods to
        create instances,
        get information about hosted subjects,
        add and remove subjects,
        constrain access,
        set the key to use for encrypted data transmission,
        shutdown the server, and
        miscellaneous.

Server methods may also be called remotely, using proxies
implementing OCSServerAdminInterface and OCSServerUserInterface
as returned by methods of OCSClient.
        

Author:
Tillmann Wegst
See Also:
Server, OCSClient.getServerAdminProxy(), OCSClient.getServerUserProxy(), OCSServerAdminInterface, OCSServerUserInterface

Field Summary
 
Fields inherited from class tw.net.Server
DEFAULT_PORT, LOCAL, UNBOUND
 
Method Summary
 void addAdminPassword(java.lang.String pw)
           Adds a password allowing administrative access to the server.
 void addAdminPasswords(java.lang.String[] pw)
          Adds one or more password(s) allowing administrative access to the server.
 java.lang.String addSubject(java.lang.Object subject)
           Adds a subject to the server.
 java.lang.String addSubject(java.lang.Object subject, boolean gc)
           Adds a subject to the server.
 java.lang.String addSubject(java.lang.Object subject, java.lang.Class c, java.lang.String id)
           Adds a subject associated with some class to the server.
 java.lang.String addSubject(java.lang.Object subject, java.lang.Class c, java.lang.String id, boolean gc)
           Adds a subject associated with some class to the server.
 java.lang.String addSubject(java.lang.Object subject, java.lang.String id)
           Adds a subject to the server.
 java.lang.String addSubject(java.lang.Object subject, java.lang.String id, boolean gc)
           Adds a subject to the server.
 void addUserPassword(java.lang.String pw)
           Adds a password allowing user access to the server.
 void addUserPasswords(java.lang.String[] pw)
          Adds one or more password(s) allowing user access to the server.
 void allowSubjectClass(java.lang.Class c)
           Allows the hosting of subjects of a certain class.
 void allowSubjectClasses(java.lang.String[] cc)
           Allows the hosting of subjects of certain classes.
static OCSServer createInstance()
           Creates a server instance with default values.
static OCSServer createInstance(int port, java.lang.String name)
           Creates a server instance listening on a certain port.
 void encryptAccordingToClient(boolean value)
           Sets the server to accept both encrypting and non-encrypting clients.
 boolean existsSubject(java.lang.Class c)
          Tells whether at least one subject of a certain class exists on this server
 boolean existsSubject(java.lang.Class c, java.lang.String id)
          Tells whether a certain subject exists on this server
 void forbidSubjectClass(java.lang.Class c)
           Forbids the hosting of subjects of a certain class.
 void forbidSubjectClasses(java.lang.String[] cc)
           Forbids the hosting of subjects of certain classes.
static OCSServer getInstance(int port)
          Returns a server instance identified by its port
static OCSServer getInstance(java.lang.String name)
          Returns a server instance identified by name
static java.util.Collection<OCSServer> getInstances()
          Returns all instances.
 java.lang.String getName()
          Returns the name of the instance.
 java.lang.Object getSubject(java.lang.Class c)
          Returns an arbitrary instance of a subject class
 java.lang.Object getSubject(java.lang.Class c, java.lang.String id)
           Returns an identified instance of a subject class.
 java.util.List<java.lang.Class> getSubjectClasses()
          Returns the classes of which instances (subjects) exist on this server
 java.lang.String getSubjectID(java.lang.Class c)
          Returns the ID of an arbitrary instance of a subject class
 java.util.List<java.lang.String> getSubjectNames(java.lang.Class c)
           Returns the names of subjects of a certain class.
 boolean isLocal()
          Tells whether the server is working in local mode, configured to be referenced directly by a client
static void main(java.lang.String[] args)
           Allows to start and stop an OCSServer, also to retrieve version information.
 boolean ping()
          A convenience method to check the server's accessibility
 boolean removeAdminPassword(java.lang.String pw)
          Removes a password allowing administrative access to the server.
 void removeAdminPasswords()
          Removes all passwords allowing administrative access to the server.
 boolean removeSubject(java.lang.Class c, java.lang.String id)
          Removes a subject from this server
 boolean removeSubjects()
          Removes all subjects from this server
 boolean removeSubjects(java.lang.Class c)
          Removes all subjects of a given class from this server
 boolean removeUserPassword(java.lang.String pw)
          Removes a password allowing user access to the server.
 void removeUserPasswords()
          Removes all passwords allowing user access to the server.
 void setEncryptionKey(java.lang.String key)
           Sets the key for encrypted data transmission.
 void setLogfile(java.lang.String f)
           Sets a file to receive log messages.
 java.lang.String toString()
           
 
Methods inherited from class tw.net.Server
allowClientIP, allowClientIPs, forbidClientIP, forbidClientIPs, getHostAddress, getHostName, getPort, getPriority, isDaemon, pleaseStop, setDaemon, setPriority, setVerbose, start
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface tw.net.ocs.OCSServerUserInterface
getHostAddress, getHostName, getPort
 
Methods inherited from interface tw.net.ocs.OCSServerAdminInterface
allowClientIP, allowClientIPs, forbidClientIP, forbidClientIPs, getPriority, hashCode, isDaemon, pleaseStop, setDaemon, setPriority, setVerbose
 

Method Detail

addUserPassword

public void addUserPassword(java.lang.String pw)
Adds a password allowing user access to the server.

Several passwords may be used, each independently allowing
access.

If no password has been set, access to the server is
unrestricted. (Note that this is different from the
policy used with admin passwords, where the absence
of passwords means access to admin methods is forbidden.)

Note that passwords are only checked when methods are called
via proxies, i.e. thru an OCSClient. OCSServer method invocations
directly using an OCSServer object do not require authentification.
                

Specified by:
addUserPassword in interface OCSServerAdminInterface
Parameters:
pw - the password
See Also:
addUserPasswords(java.lang.String[]), addAdminPassword(java.lang.String)

addUserPasswords

public void addUserPasswords(java.lang.String[] pw)
Adds one or more password(s) allowing user access to the server.

Specified by:
addUserPasswords in interface OCSServerAdminInterface
Parameters:
pw - an array of password
See Also:
addUserPassword(java.lang.String)

removeUserPassword

public boolean removeUserPassword(java.lang.String pw)
Removes a password allowing user access to the server.

Specified by:
removeUserPassword in interface OCSServerAdminInterface
Parameters:
pw - the password
Returns:
true if and only if the specified password existed and could be removed

removeUserPasswords

public void removeUserPasswords()
Removes all passwords allowing user access to the server.

Specified by:
removeUserPasswords in interface OCSServerAdminInterface

addAdminPassword

public void addAdminPassword(java.lang.String pw)
Adds a password allowing administrative access to the server.

Several admin passwords may be used, each independently allowing
access.

If no admin password has been set, access to administration methods
of OCSServer is forbidden. (Note that this is different from the
policy used with user passwords, where the absence of passwords
means access to user methods is unlimited.)

Note that passwords are only checked when methods are called
via proxies, i.e. thru an OCSClient. OCSServer method invocations
directly using an OCSServer object do not require authentification.
                

Specified by:
addAdminPassword in interface OCSServerAdminInterface
Parameters:
pw - the password
See Also:
addAdminPasswords(java.lang.String[]), addUserPassword(java.lang.String)

addAdminPasswords

public void addAdminPasswords(java.lang.String[] pw)
Adds one or more password(s) allowing administrative access to the server.

Specified by:
addAdminPasswords in interface OCSServerAdminInterface
Parameters:
pw - an array of password
See Also:
addAdminPassword(java.lang.String)

removeAdminPassword

public boolean removeAdminPassword(java.lang.String pw)
Removes a password allowing administrative access to the server.

Specified by:
removeAdminPassword in interface OCSServerAdminInterface
Parameters:
pw - the password
Returns:
true if and only if the specified password existed and could be removed
See Also:
OCSServerAdminInterface.addAdminPassword(java.lang.String)

removeAdminPasswords

public void removeAdminPasswords()
Removes all passwords allowing administrative access to the server.

Specified by:
removeAdminPasswords in interface OCSServerAdminInterface

isLocal

public boolean isLocal()
Tells whether the server is working in local mode, configured to be referenced directly by a client

Specified by:
isLocal in interface OCSServerUserInterface
Returns:
true if the server is configured for local mode

createInstance

public static OCSServer createInstance(int port,
                                       java.lang.String name)
Creates a server instance listening on a certain port.

Special values of port numbers:
If 0 (zero) is specified, an arbitrary port will be used.
If -1 (=Server.LOCAL) is specified, the server will not listen on a port
        but get prepared for direct use by a client within the same VM.

If a specified port is already in use, the server will bind to
some arbitrary unused port.

If no name is specified for the instance, it is given a name automatically:
A remote server will be named after its port number,
a local server will be named "LOCAL".
If the selected name proves to be already in use, it will be made
unique by appending "/[number]".
                

Parameters:
port - number of the port to listen at
name - symbolic ID of the server instance
Returns:
an OCSServer instance appropriately configured

createInstance

public static OCSServer createInstance()
Creates a server instance with default values.

The server will listen on default port 23229 and
be named "23229" or "23229/[number]".

If the default port is already in use, the server will bind to
some arbitrary unused port.
                

Returns:
an OCSServer instance appropriately configured

getInstance

public static OCSServer getInstance(java.lang.String name)
Returns a server instance identified by name

Parameters:
name - name of the instance
Returns:
the OCSServer so named or null if none of that name exists

getInstance

public static OCSServer getInstance(int port)
Returns a server instance identified by its port

Parameters:
port - the port number
Returns:
the OCSServer listening at this port or null
Since:
1.3

forbidSubjectClass

public void forbidSubjectClass(java.lang.Class c)
Forbids the hosting of subjects of a certain class.

Note that forbidding a subject class includes
forbidding all of this class' subclasses.

If there are both forbid and allow specifications,
the latter are ignored.
                

Specified by:
forbidSubjectClass in interface OCSServerAdminInterface
Parameters:
c - the class of which instances must not be hosted
See Also:
allowSubjectClass(java.lang.Class)

forbidSubjectClasses

public void forbidSubjectClasses(java.lang.String[] cc)
                          throws java.lang.ClassNotFoundException
Forbids the hosting of subjects of certain classes.

Specify classes by their qualified names, as for
use by Class.forName().
                

Specified by:
forbidSubjectClasses in interface OCSServerAdminInterface
Parameters:
cc - an array of class names
Throws:
java.lang.ClassNotFoundException
See Also:
forbidSubjectClass(java.lang.Class)

allowSubjectClass

public void allowSubjectClass(java.lang.Class c)
Allows the hosting of subjects of a certain class.

Note that allowing a subject class includes
allowing all of this class' superclasses.

If at least one class is explicitly allowed to be hosted, the
hosting of all classes not explicitly allowed
is forbidden - provided there is no forbid specification:

If at least one class has been forbidden to be hosted,
allow specifications are ignored and all classes
not explicitely forbidden are allowed.
                

Specified by:
allowSubjectClass in interface OCSServerAdminInterface
Parameters:
c - the class of which instances may be hosted
See Also:
forbidSubjectClass(java.lang.Class)

allowSubjectClasses

public void allowSubjectClasses(java.lang.String[] cc)
                         throws java.lang.ClassNotFoundException
Allows the hosting of subjects of certain classes.

Specify classes by their qualified names, as for
use by Class.forName().
                

Specified by:
allowSubjectClasses in interface OCSServerAdminInterface
Parameters:
cc - an array of class names
Throws:
java.lang.ClassNotFoundException
See Also:
allowSubjectClass(java.lang.Class)

getSubject

public java.lang.Object getSubject(java.lang.Class c,
                                   java.lang.String id)
Returns an identified instance of a subject class.

Note: If null is specified as the ID, null will be
returned.
Use getSubject(Class c) to retrieve an arbitrary instance
of a subject class.
                

Specified by:
getSubject in interface OCSServerUserInterface
Parameters:
c - the class of the requested subject
id - the ID of the subject
Returns:
the subject or null

getSubject

public java.lang.Object getSubject(java.lang.Class c)
Returns an arbitrary instance of a subject class

Specified by:
getSubject in interface OCSServerUserInterface
Parameters:
c - the class of the requested subject
Returns:
an arbitrary subject of the class or null

getSubjectNames

public java.util.List<java.lang.String> getSubjectNames(java.lang.Class c)
Returns the names of subjects of a certain class.

If null is specified for the class, the names
of all subjects of whatever class are returned.
                

Specified by:
getSubjectNames in interface OCSServerUserInterface
Parameters:
c - the class to which the request is restricted
Returns:
a list of names of subjects of the specified class

getSubjectClasses

public java.util.List<java.lang.Class> getSubjectClasses()
Returns the classes of which instances (subjects) exist on this server

Specified by:
getSubjectClasses in interface OCSServerUserInterface
Returns:
a list of Class objects

getSubjectID

public java.lang.String getSubjectID(java.lang.Class c)
Returns the ID of an arbitrary instance of a subject class

Specified by:
getSubjectID in interface OCSServerUserInterface
Parameters:
c - the subject class
Returns:
the ID of an arbitrary instance of the specified class

existsSubject

public boolean existsSubject(java.lang.Class c,
                             java.lang.String id)
Tells whether a certain subject exists on this server

Specified by:
existsSubject in interface OCSServerUserInterface
Parameters:
c - the class of the subject
id - the ID of the subject
Returns:
true if and only if a subject so identified exists

existsSubject

public boolean existsSubject(java.lang.Class c)
Tells whether at least one subject of a certain class exists on this server

Specified by:
existsSubject in interface OCSServerUserInterface
Parameters:
c - the class of the subject
Returns:
true if and only if a subject of this class exists

removeSubject

public boolean removeSubject(java.lang.Class c,
                             java.lang.String id)
Removes a subject from this server

Specified by:
removeSubject in interface OCSServerUserInterface
Parameters:
c - the class of the subject
id - the ID of the subject
Returns:
true if and only if the subject was found and removed

removeSubjects

public boolean removeSubjects(java.lang.Class c)
Removes all subjects of a given class from this server

Specified by:
removeSubjects in interface OCSServerUserInterface
Parameters:
c - the class of the subject
Returns:
true if and only if at least one subject was found and removed

removeSubjects

public boolean removeSubjects()
Removes all subjects from this server

Specified by:
removeSubjects in interface OCSServerUserInterface
Returns:
true if and only if at least one subject was found and removed

addSubject

public java.lang.String addSubject(java.lang.Object subject,
                                   java.lang.Class c,
                                   java.lang.String id,
                                   boolean gc)
                            throws OCSException
Adds a subject associated with some class to the server.

The specified class may be a base class of the subject.
If the specified class is neither identical to the
subject's class nor one of its base classes, an
OCSException is thrown.

The subject will be associated with an ID.
If no ID is specified, it will be supplied automatically.

The subject can be marked for garbage collection so
that it will be removed if all proxies that may attach
to it detach from it again.
                

Specified by:
addSubject in interface OCSServerUserInterface
Parameters:
subject - the subject
c - the class of the subject or a base class thereof
id - the ID to associate the subject with (may be null)
gc - garbage collect the subject once all proxies detach from it?
Returns:
the ID of the subject
Throws:
OCSException
Since:
1.3

addSubject

public java.lang.String addSubject(java.lang.Object subject,
                                   java.lang.Class c,
                                   java.lang.String id)
                            throws OCSException
Adds a subject associated with some class to the server.

The specified class may be a base class of the subject.
If the specified class is neither identical to the
subject's class nor one of its base classes, an
OCSException is thrown.

The subject will be associated with an ID.
If no ID is specified, it will be supplied automatically.

The subject is not marked for garbage collection,
so it will stay on if proxies that may attach to it
detach again.
                

Specified by:
addSubject in interface OCSServerUserInterface
Parameters:
subject - the subject
c - the class of the subject or a base class thereof
id - the ID to associate the subject with (may be null)
Returns:
the ID of the subject
Throws:
OCSException

addSubject

public java.lang.String addSubject(java.lang.Object subject,
                                   java.lang.String id,
                                   boolean gc)
                            throws OCSException
Adds a subject to the server.

The subject will be associated with an ID.
If no ID is specified, it will be supplied automatically.

The subject can be marked for garbage collection so
that it will be removed if all proxies that may attach
to it detach from it again.
                

Specified by:
addSubject in interface OCSServerUserInterface
Parameters:
subject - the subject
id - the ID to associate the subject with (may be null)
gc - garbage collect the subject once all proxies detach from it?
Returns:
the ID of the subject
Throws:
OCSException
Since:
1.3

addSubject

public java.lang.String addSubject(java.lang.Object subject,
                                   java.lang.String id)
                            throws OCSException
Adds a subject to the server.

The subject gets associated with an ID.
If none is specified, the ID is supplied automatically.

The subject is not marked for garbage collection,
so it will stay on if proxies that may attach to it
detach again.
                

Specified by:
addSubject in interface OCSServerUserInterface
Parameters:
subject - the subject
id - the ID to associate the subject with (may be null)
Returns:
the ID of the subject
Throws:
OCSException

addSubject

public java.lang.String addSubject(java.lang.Object subject,
                                   boolean gc)
                            throws OCSException
Adds a subject to the server.

The subject's ID is supplied automatically.

The subject can be marked for garbage collection so
that it will be removed if all proxies that may attach
to it detach from it again.
                

Specified by:
addSubject in interface OCSServerUserInterface
Parameters:
subject - the subject
gc - garbage collect the subject once all proxies detach from it?
Returns:
the automatically generated ID of the subject
Throws:
OCSException
Since:
1.3

addSubject

public java.lang.String addSubject(java.lang.Object subject)
                            throws OCSException
Adds a subject to the server.

The subject's ID is supplied automatically.

The subject is not marked for garbage collection,
so it will stay on if proxies that may attach to it
detach again.
                

Specified by:
addSubject in interface OCSServerUserInterface
Parameters:
subject - the subject
Returns:
the automatically generated ID of the subject
Throws:
OCSException

ping

public boolean ping()
A convenience method to check the server's accessibility

Specified by:
ping in interface OCSServerAdminInterface
Returns:
true come rain or come shine

setLogfile

public void setLogfile(java.lang.String f)
Sets a file to receive log messages.

If the file exists already, new messages will
be appended to it.

Note that setting a logfile does not turn off
logging to System.out but create an additional
log target.
                

Parameters:
f - the path of the log file

setEncryptionKey

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

Setting a key means that encryption begins.

To stop encryption, call the method with a
null argument.

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

Specified by:
setEncryptionKey in interface OCSServerAdminInterface
Parameters:
key - the encryption key or null
Since:
1.3
See Also:
encryptAccordingToClient(boolean)

encryptAccordingToClient

public void encryptAccordingToClient(boolean value)
Sets the server to accept both encrypting and non-encrypting clients.

Setting this option is relevant only if the server runs in encrypting mode:

If set, an encrypting server accepts and serves non-encrypting clients
as well.
If not set, an encrypting server turns non-encrypting clients away.

Per default, this option is not set.

Note that setting this option alone, does not put a server in
encrypting mode. To do this, use setEncryptionKey() with a non-empty
argument.
                

Specified by:
encryptAccordingToClient in interface OCSServerAdminInterface
Parameters:
value - allow both encrypting and non-encrypting clients?
Since:
1.3
See Also:
setEncryptionKey(java.lang.String)

getName

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

Returns:
the name
Since:
1.3

getInstances

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

Returns:
the collection of OCSServer instances
Since:
1.3

toString

public java.lang.String toString()
Specified by:
toString in interface OCSServerAdminInterface
Overrides:
toString in class java.lang.Object

main

public static void main(java.lang.String[] args)
Allows to start and stop an OCSServer, also to
retrieve version information.

When starting, you can
specify passwords required from clients for user or
        administrative functions,
allow / forbid clients connecting from certain IPs,
set the server to encrypted data transmission, and
allow / forbid the installation of subjects of certain classes.

Example:
        java tw.net.ocs.OCSServer -start -port 12345 -adminPassword eddie -allowedClientIP 192.168+123.45.*.1 -encryptionKey secret -allowedSubjectClass my.pack.Clazz

This
        - starts a server
        - at port 12345
        - with admin functions requiring password "eddie",
        - accessible only to clients within the LAN or at an IP
          which matches the pattern 123.45.*.1,
        - encrypting data using the key "secret", and
        - allowing subjects only of class "my.pack.Clazz".

To specify passwords for non-administrative operations, use "-userPassword".
You may specify several passwords. separated by "+".

To forbid client IPs, use "-forbiddenClientIP". If positive and negative
IP constraints are combined and patterns of both types do match,
the type of the more specific pattern will take effect. If on a par,
forbidding takes precedence. See the API doc for details!
You may specify several IPs (IP patterns), separated by "+".

Specifying an encryption key means to put the server into encrypting mode.
Specify the boolean option "-encryptAccordingToClient" in addition
to let the server accept both encrypting and non-encrypting clients;
without this option, a server running in encrypting mode will turn
non-encrypting clients away.

To allow or forbid subject classes, use "-allowedSubjectClass"
or "-forbiddenSubjectClass". Specify one or the other, not both:
If both options are given, only "-forbiddenSubjectClass" is evaluated.
When specifying classes make sure to use their qualified names,
like "my.pack.Clazz", instead of just "Clazz".
You may specify several class names, separated by "+".

When stopping a server, specify the port and the admin password.

Example:
        java tw.net.ocs.OCSServer -stop -port 12345 -adminPassword eddie
This would stop the server started with the command above.

If no port is specified, the default port 23229 is assumed.

Usage:
        java tw.net.ocs.OCSServer {parameters...}

        -start                    Start a server
        -stop                     Stop a server
        -port                     The port number of the server
        -userPassword             Set / use this user password
        -adminPassword            Set / use this admin password
        -allowedClientIP          IP address of acceptable client
        -forbiddenClientIP        IP address of inacceptable client
        -encryptionKey            Encrypt data using this key
        -encryptAccordingToClient Serve both encrypting and non-encrypting clients
        -allowedSubjectClass      Class of which subjects are allowed on the server
        -forbiddenSubjectClass    Class of which subjects are not allowed on the server
        -logfile                  Log errors (activities if verbose) to this file
        -verbose                  Make the server say a bit what it does
        -version                  Show version information
        -licensee                 Show licensee name
                

See Also:
addUserPassword(java.lang.String), addAdminPassword(java.lang.String), Server.allowClientIPs(java.lang.String[]), Server.forbidClientIPs(java.lang.String[]), forbidSubjectClasses(java.lang.String[]), allowSubjectClasses(java.lang.String[])


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