- A Lightweight Java Middleware
<< The proxy   The server >>

The client

has the job to transfer a proxy's requests to the server (which passes them on to the final destination, the subject) and to hand the incoming responses back as return values.

Clients in the OCSelot system are instances of class OCSClient.

Association with the proxy instance

Whenever a proxy is created, it immediately associates with an OCSClient instance. Beginning with construction and then in subsequent method invocations, the proxy turns to that and lets it take care of communication with the server side.

This association can take place explicitly or implicitly: For both class and interface proxies there are constructors / generator functions that take an OCSClient parameter and others that do not.

If no OCSClient is handed in with a parameter, the proxy tries to use an instance installed in the proxy class or the OCSInterfaceProxyFactory, respectively. In the absence of that, it uses the OCSClient standard instance, accessible through OCSClient.getStandardInstance().

Note that a proxy's association with its client remains fixed over the proxy's lifetime. There is no way to install another client in the proxy after its construction; also, the creation of a new OCSClient standard instance doesn't affect previously allocated proxies.

... and the proxy class

Static methods of a (class) proxy class forward their invocation to the corresponding method of the subject class.

To do so, they either use an OCSClient instance installed in the proxy class with the static proxy class method ocsSetClientForClassMethods(OCSClient c), or, in the absence of such a specification, they use the standard OCSClient instance.

Creating a client

OCSClient instances are created using the createInstance() class methods.

The instances are given names and a reference to them is kept in class OCSClient. Using their name, they can be accessed at any time.

There may be any number of clients. Typically different clients used in the same VM will connect to different servers, but this is no requirement.

Remote and local use

Usually, what we have in mind when thinking of client/server systems is clients and servers distributed over several machines.

With OCSelot, you can have a client/server structure also in a local application and easily switch between local and remote versions of a program.

To clarify: with a local application we do not mean the scenario where client and server do reside on the same host or even in the same VM and in both cases still use networking. What is meant is a system where client and server link directly and exchange data without networking, simply passing data from object to nearby, referenced object.

Let's look at the remote case first:

The client for remote communication

To create an instance to connect to a remote server you supply it with host address and port of the server, give it a name to allow later reference, and say whether you want it to become the new standard instance:


Proxies subsequently allocated (and not specified otherwise) will use this instance and get associated with subjects on the specified server.

There is also another overload that allows you to specify the server by handing in an OCSServer instance:

OCSServer server; // (initialized elsewhere)

Most of the time, this method will be used to create local client-server-connections (see below), but the effect depends entirely on the configuration of the OCSServer object handed in. If the server is configured for remote use, a "normal" networking connection is established: the client simply reads the server's address and connects to that.

But what use is this? Obviously, both client and server have been created within the same VM, so why connect the two over the network instead of directly, in local mode?

The answer is: The client, though created locally to the server (sL) that it connects to, may be sent away, to another, remote server (sR) and then talk back from a distance to server sL!

To achieve this, you don't have to handle the client itself in a specific way. It is simply done by creating a proxy (p1) which associates with this client, and then passing this proxy as a parameter to a method of some other proxy (p2):

Invoking the p2-method will mean that p2's remote subject will be invoked. As p1 is a parameter to the p2-method, p1 will be passed over to the remote subject at server sR. And since p1 is associated with our client, the client will be taken along with p1 and so come to sit in the remote subject at server sR as well. Whenever then a method of p1 gets invoked from sR, the client will route the invocation back to server sL.

This scenario is probably the most difficult you can set up with OCSelot and still does not take too many lines. See example 4a and example 4b for how this looks in code.

The client for local communication

To create an OCSClient instance that links directly with a server, create an OCSServer configured for local use

OCSServer localServer=OCSServer.createInstance(Server.LOCAL,"localServer",true);

and pass this server to the client create method:


The client will keep a reference to the server instance so they can exchange data without network.

You will not frequently need this setup procedure, however, because OCSelot automatically starts ready to work in local mode: Both class OCSServer and class OCSClient are initialized with standard instances configured to work in local mode, with the standard client instance referencing the standard server instance.

Therefore, you can in many cases turn a remote version of your program into a local version simply by omitting the creation of a client instance configured for remote communication.


Communication with the server may require authentication. Authentication is an option in the case of normal user operations and it is obligatory for administration functions. See the API for how to set passwords.

The server may run in encryption mode. See the API on how to also configure the client for encryption.

Invoking methods on the server

You can invoke methods on the server associated with a client through objects returned by two client methods:

getServerUserProxy() returns an object implementing OCSServerUserInterface, an interface declaring normal user methods of OCSServer.

getServerAdminProxy() returns an object implementing OCSServerAdminInterface, an interface declaring administration methods.

Note that access to admin functions always requires that a proper admin password be set in the client. Access to user functions may or may not require a user password.

See this section about the server and the API for more.

Apart from that, the OCSClient can also be run from the command-line, if only to check the availability of a server and to shut it down. See the API for how to do this.

Last modified Jan 18, 2006