tw.net.ocs
Class OCSServer

java.lang.Object
  tw.net.Server
      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[])