gnu.cajo

Interface Service

public interface Service

This class defines a proxy enabled network service. It is intended both as a fundamental pattern, and an example of a service specification. It is implemented by services that wish to provide proxy functionality. A proxy enabled network service means one that either furnishes, or accepts proxies, or both.

This service would typically be implemented in situations where the benefit is greater to send all, or a portion, of the code to the receiver; instead of passing a lot of data back or forth. This pattern is also ideal for the provision of graphical user interfaces to requesting JVMs.

All services are defined as plain-old Java interfaces. Typically these interfaces contain:

• Manifest constants: any static final objects or primitives of use
• Custom inner class definitions for:
  • arguments
  • returns
  • exceptions
• Custom inner interface definitons: used for either arguments, or returns
• The collection of shared methods implemented by the service

A JVM may furnish as many service objects as it wishes. Normally, related service interfaces are grouped into packages. Typically the javadoc package.html file is used to provide a detailed explanation of the service collection architecture. The package may also include any custom classes shared between the service interfaces, specifically; objects, interfaces, and exceptions. Once a service interface is defined and distributed, it should be considered immutable. Service feature enhancements should be handled through subclasses of the original service interface, to ensure backward compatibility.

Technically speaking:

• Service method signatures may be either static or instance methods on the implementation.
• Service methods should be considered referentially opaque; e.g. invoking the same method, with the same arguments, at different times is not guaranteed to return the same result.
• All service methods are reentrant, meaning that multiple clients can be executing them simultaneously.
• Whilst not explicitly declared, any service method invocations could fail for network related reasons, resulting in a java.rmi.RemoteException being thrown implicitly.

NB: The service interface is completely cajo project agnostic, as all service definitions properly should be.

Version:

1.0, 17-Oct-09

Author:

John Catherino

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Service.Proxy This class is both used by servers to install proxies in a client's JVM, and by clients to install proxies in a server's JVM.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	isReal() whilst semantically unrelated to this service, it is just too useful to leave out.
Service.Proxy	requestProxy() used to request a client-side running, server proxy.
Object	sendProxy(Service.Proxy proxy) used to send a client's proxy code to run at the service.

Method Detail

sendProxy

Object sendProxy(Service.Proxy proxy)
                 throws ClassNotFoundException

used to send a client's proxy code to run at the service. The client's code runs in the address space of the service JVM. A proxy enabled service need not support client proxies, in which case a ClassNotFound exception will be thrown implicitly.
NB: acceptance of client proxy code implies a significant amount of trust by the server, that the sent code is well behaved. However, client proxies can be made to run in an applet sandbox, as a compromise strategy.

Parameters:

proxy - an object to be sent to the service, which will be provided a local reference to the service upon its arrival.

Returns:

a remote reference to the proxy object, installed in the service JVM, or a server proxy to the installed client proxy, over which the client may now interact.

Throws:

ClassNotFoundException - if the service JVM does not accept client proxies.

requestProxy

Service.Proxy requestProxy()
                           throws ClassNotFoundException

used to request a client-side running, server proxy. It is considered common courtesy of clients to request it, if their use scenario permits, before making use the service reference directly. It allows the service to potentially offload some computing or storage requirements to the client temporarily. It's a bit like the client asking: may I help with my requests?

Returns:

a local object also supporting the service interface, which will be provided with a remote reference to its service.
NB: If a service does not support client proxies, it will return null.

Throws:

ClassNotFoundException - if the client JVM does not accept service proxies.

isReal

boolean isReal()

whilst semantically unrelated to this service, it is just too useful to leave out. Services typically exist as either development, or production. Most often, the unreal, i.e. test/demo/development services, are being used to validate infrastructure, communication, performance, provide simulated functionality, and validate functional correctness. Generally speaking, test/demo/development services interact with each other exclusively, and real/production services behave similarly. However, exceptions can be permitted...

Returns:

false if this service is a test, demo, or development implementation; true if this is a production service.