fulmine.rpc
Class RpcRegistry

java.lang.Object
  fulmine.AbstractLifeCycle
      fulmine.rpc.RpcRegistry

All Implemented Interfaces:

IDestroyable, ILifeCycle, IRpcPublishOperations, IRpcRegistry

public final class RpcRegistry
extends AbstractLifeCycle
implements IRpcRegistry

Standard IRpcRegistry implementation. This has a single IRecord that represents the set of RPC definitions that are published by local application code. Remote contexts will subscribe for this to receive the current and future RPC definitions. The record is addressed using the following attributes:

1. identity=IRpcRegistry.RPC_REGISTRY
2. type=Type.RECORD
3. domain=Domain.FRAMEWORK

When a new RPC definition is published by application code, a new field is added to the registry record. The field is called the RPC registry key. The RPC registry key format is described in the following ABNF:

 RPC key              =  "rpc" counter "_" compactForm
 counter              =  1*DIGIT ; this increments each time a new definition is registered
 compactForm          =  ALPHA 0*(ALPHA/DIGIT) argTypeCompactForm; this is the RPC name
 argTypeCompactForm   =  0*ALPHA ; this is a string formed from the first letter of each argument type
 

This ensures that the key is deterministic. Application code can cycle through the fields of the RPC registry record and intercept any beginning with this pattern in order to find RPC definitions. The value of the key is the string representation of the RPC definition. E.g. rpc12lasersIDB is the key for the 12th registered RPC, the RPC definition is lasers(IntegerField, DoubleField, BooleanField) - compact form is lasersIDB

An IRpcDefinition can re-construct itself from this representation so this is what is sent on-the-wire to remote contexts. After the key is added, an update event is then triggered for the registry which will be received by all subscribers for the registry (including channels connected to remote contexts).

When an RPC definition is unpublished, the key and value are removed.

This class is thread safe.

Author:

Ramon Servadei

Field Summary

Fields inherited from interface fulmine.rpc.IRpcRegistry

RPC_KEY, RPC_KEY_COUNT, RPC_REGISTRY

Constructor Summary

RpcRegistry(IFrameworkContext context)
Construct the RPC repository

Method Summary

protected void	doDestroy() Overridden in subclasses to perform custom logic on destruction.
protected void	doStart() Overridden in subclasses to perform custom logic on activation.
IRpcDefinition	getDefinition(String registryKey) Get the IRpcDefinition registered against the RPC registry key.
IRpcHandler	getHandler(String registryKey) Get the handler for the RPC registry key.
String	getRegistryKey(String rpcName, IField[] args) Get the RPC registry key for the RPC defined by the procedure name and arguments.
boolean	publishProdedure(IRpcHandler handler, IRpcDefinition rpcDefinition) Publish the named procedure to all known remote contexts.
boolean	publishRpcs(Class<?> definition, Object handler) Allows application code to remotely enable all methods in a handler object that are implementations of methods in an interface definition.
String	toString()
boolean	unpublishProdedure(IRpcDefinition rpcDefinition) Unpublish the procedure from all connected remote contexts.
boolean	unpublishRpcs(Class<?> definition, Object handler) Allows application code to remove any previously remotely enabled methods published via IRpcPublishOperations.publishRpcs(Class, Object)

Methods inherited from class fulmine.AbstractLifeCycle

checkActive, destroy, finalize, getLog, isActive, start

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface fulmine.ILifeCycle

isActive, start

Methods inherited from interface fulmine.IDestroyable

destroy

Constructor Detail

RpcRegistry

public RpcRegistry(IFrameworkContext context)

Construct the RPC repository

Parameters:

context - the local context

Method Detail

publishProdedure

public boolean publishProdedure(IRpcHandler handler,
                                IRpcDefinition rpcDefinition)

Description copied from interface: IRpcPublishOperations

Publish the named procedure to all known remote contexts.

There can only be one handler per procedure instance. Different handlers can be used for overloaded procedures. RPC definitions cannot overload the result type, if this method is called with a definition that attempts to overload the result type, the operation is ignored and no publish happens.

After this method has completed, remote contexts will be able to invoke the RPC.

Specified by:

publishProdedure in interface IRpcPublishOperations

Parameters:

handler - the object that will handle any RPC invocations for this RPC definition. This object must be thread safe.

rpcDefinition - the RPC definition

Returns:

true if the procedure was published, false if has already been published

unpublishProdedure

public boolean unpublishProdedure(IRpcDefinition rpcDefinition)

Description copied from interface: IRpcPublishOperations

Unpublish the procedure from all connected remote contexts.

Specified by:

unpublishProdedure in interface IRpcPublishOperations

Parameters:

rpcDefinition - the RPC definition to unpublish

Returns:

true if the procedure was unpublished

unpublishRpcs

public boolean unpublishRpcs(Class<?> definition,
                             Object handler)

Description copied from interface: IRpcPublishOperations

Allows application code to remove any previously remotely enabled methods published via IRpcPublishOperations.publishRpcs(Class, Object)

Specified by:

unpublishRpcs in interface IRpcPublishOperations

Parameters:

definition - an interface that defines all the methods in the handler that should be remotely disabled. This includes all methods in the super-interfaces, if any.

handler - the object that implements the methods declared in the definition interface. These methods will no longer be available for remote invocation.

Returns:

true if all methods were successfully unpublished

publishRpcs

public boolean publishRpcs(Class<?> definition,
                           Object handler)

Description copied from interface: IRpcPublishOperations

Allows application code to remotely enable all methods in a handler object that are implementations of methods in an interface definition. This essentially publishes these methods as RPCs for other contexts to invoke.

There are some caveats to methods that can be remotely enabled; the method arguments and return types must be scalar and only the following types are supported:

• integer
• long
• float
• double
• boolean
• String

This is a convenience method in-lieu of calling IRpcPublishOperations.publishProdedure(IRpcHandler, IRpcDefinition).

Specified by:

publishRpcs in interface IRpcPublishOperations

Parameters:

definition - an interface that defines all the methods in the handler that should be remotely enabled. This includes all methods in the super-interfaces, if any.

handler - the object that implements the methods declared in the definition interface. The handler does not necessarily have to be an instance of the interface (i.e. does not need to explicitly implement the interface, it only needs to implement all the methods). All remote invocations of these methods will be handled by this object. The remotely enabled methods must be thread safe.

Returns:

true if all methods were successfully published

getHandler

public IRpcHandler getHandler(String registryKey)

Description copied from interface: IRpcRegistry

Get the handler for the RPC registry key. When a remote context invokes an RPC on the local context, only the registry key and the arguments are sent from the remote context.

Specified by:

getHandler in interface IRpcRegistry

Parameters:

registryKey - the registry key of the RPC

Returns:

the handler or null if not found

getDefinition

public IRpcDefinition getDefinition(String registryKey)

Description copied from interface: IRpcRegistry

Get the IRpcDefinition registered against the RPC registry key.

Specified by:

getDefinition in interface IRpcRegistry

Parameters:

registryKey - the registry key of the RPC

Returns:

the definition or null if not found

getRegistryKey

public String getRegistryKey(String rpcName,
                             IField[] args)

Description copied from interface: IRpcRegistry

Get the RPC registry key for the RPC defined by the procedure name and arguments.

Specified by:

getRegistryKey in interface IRpcRegistry

Parameters:

rpcName - the name of the RPC

args - the arguments for the RPC

Returns:

the registry key or null if no match is found

doDestroy

protected void doDestroy()

Description copied from class: AbstractLifeCycle

Overridden in subclasses to perform custom logic on destruction. Any exceptions should be thrown as a RuntimeException or subclass thereof.

Specified by:

doDestroy in class AbstractLifeCycle

doStart

protected void doStart()

Description copied from class: AbstractLifeCycle

Overridden in subclasses to perform custom logic on activation. Any exceptions should be thrown as a RuntimeException or subclass thereof. When this method is called, the AbstractLifeCycle.isActive() method will return true.

Specified by:

doStart in class AbstractLifeCycle

toString

public String toString()

Overrides:

toString in class AbstractLifeCycle