fulmine.AbstractLifeCycle
fulmine.context.RpcManager
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object
public final class RpcManager
The standard implementation of an IRpcManager.
RPC definitions can be invoked in a multi-threaded context. However, simultaneous calls to the same RPC definition are handled sequentially.
Every RPC definition has an associated 'result record'. When a local context handles an RPC invocation from a remote context, it also creates a result record that will contain the result from the RPC invocation. The result record has a specific naming convention, in ABNF form:
result-record = remote-context-identity ":" RPC-registry-key remote-context-identity = 1*(ALPHA / DIGIT) RPC-registry-key = "RpcKey" + 1*(DIGIT)When invoking an RPC, the local context first subscribes for the result record then issues the RPC. On the receiving end, the invocation is packaged up into an event. The remote context's RpcManager registers an
IEventListener that will respond to these RpcInvokeEvents.
This listener will be responsible for locating the appropriate
IRpcHandler and invoking it with the arguments encapsulated in the
event. The result record attached to the remote context for the RPC
definition is then updated with the result and the invoking context will
receive this result and return it to the application caller.
The sequence diagram below helps to illustrate the operation.
Application IRpcManager RpcResultHandler RpcInvokeHandler IRpcHandler ResultRecord | | | | | | | invoke | | | | | |---------------->| | | | | | | RpcInokeEvent | | | | |------------------------------------->| | | | | (remote call) | | | | | | | | | | | | | handle | | | | | |--------------->| | | | | | | | | | | | result | | | | | |<---------------| | | | | | | | | | | | update with result | | | | |----------------------------->| | | | | | | | | | get result details (after remote transmission) | | | |--------------------------------------------------->| | | | | | | | result | | | | |<---------------------------------| | | | | | | | | |The timeout for RPC calls is defined by the system property
IRpcManager.RPC_TIMEOUT. If the timeout expires, an exception is
printed and a null value will be returned from
invoke(String, String, IField...).
Every context has a special component called the 'RPC registry'. This holds
every RPC that a local context exposes. Remote contexts must subscribe for
this via
IRpcManager.addRpcPublicationListener(String, IRpcPublicationListener)
in order for the remote context to receive the RPC definitions of the
context. Calling IRpcManager.invoke(String, String, IField...)
before the RPC registry is received is safe; when the RPC definition is
received from the target context, the RPC will be invoked.
RpcRegistry| Field Summary |
|---|
| Fields inherited from interface fulmine.rpc.IRpcManager |
|---|
DEFAULT_RPC_TIMEOUT, RPC_TIMEOUT |
| Method Summary | |
|---|---|
boolean |
addRpcPublicationListener(String remoteContextIdentity,
IRpcPublicationListener listener)
Add a listener for RPC publication events. |
protected void |
doDestroy()
Overridden in subclasses to perform custom logic on destruction. |
protected void |
doStart()
Overridden in subclasses to perform custom logic on activation. |
protected AsyncLog |
getLog()
Get the log to use for the object hierarchy |
DualValue<String,IRpcDefinition> |
getRegistryKeyAndDefinition(String remoteContextIdentity,
String procedure,
IField[] args)
Get the RPC registry key and IRpcDefinition for the procedure. |
IRpcMarker |
invoke(IRpcResultHandler resultHandler,
String remoteContextIdentity,
String procedure,
IField... args)
Asynchronously invoke the RPC in the named remote context. |
IRpcResult |
invoke(String remoteContextIdentity,
String procedure,
IField... args)
Synchronously invoke the RPC in the named remote context. |
void |
invoke(String remoteContextIdentity,
String rpcKey,
IRpcDefinition definition,
IField[] args,
IRpcResultHandler resultHandler,
IRpcMarker marker)
Invoke the RPC in the named remote context. |
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. |
boolean |
removeRpcPublicationListener(String remoteContextIdentity,
IRpcPublicationListener listener)
Remove an RPC publication listener. |
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, isActive, start, toString |
| 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 |
| Method Detail |
|---|
public IRpcResult invoke(String remoteContextIdentity,
String procedure,
IField... args)
IRpcManager
It is assumed that this method is called after an RPC publication event
is received by an IRpcPublicationListener.
invoke in interface IRpcManagerremoteContextIdentity - the remote context to invoke the RPC inprocedure - the RPC nameargs - the arguments for the RPC
IRpcManager.RPC_TIMEOUT
public IRpcMarker invoke(IRpcResultHandler resultHandler,
String remoteContextIdentity,
String procedure,
IField... args)
IRpcManagerIRpcPublicationListener
invoke in interface IRpcManagerresultHandler - the handler to process the asynchronous resultremoteContextIdentity - the remote context to invoke the RPC inprocedure - the RPC nameargs - the arguments for the RPC
public void invoke(String remoteContextIdentity,
String rpcKey,
IRpcDefinition definition,
IField[] args,
IRpcResultHandler resultHandler,
IRpcMarker marker)
IRpcManagerOperations
invoke in interface IRpcManagerOperationsremoteContextIdentity - the remote context to invoke the RPC inrpcKey - the RPC keydefinition - the RPC definitionargs - the arguments for the RPCresultHandler - the handler to process the asynchronous resultmarker - the marker that allows the resultHandler to tie up the result
from this specific RPC invocation
public boolean publishProdedure(IRpcHandler handler,
IRpcDefinition rpcDefinition)
IRpcPublishOperationsThere 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.
publishProdedure in interface IRpcPublishOperationshandler - the object that will handle any RPC invocations for this RPC
definition. This object must be thread safe.rpcDefinition - the RPC definition
true if the procedure was published,
false if has already been publishedpublic boolean unpublishProdedure(IRpcDefinition rpcDefinition)
IRpcPublishOperations
unpublishProdedure in interface IRpcPublishOperationsrpcDefinition - the RPC definition to unpublish
true if the procedure was unpublished
public boolean addRpcPublicationListener(String remoteContextIdentity,
IRpcPublicationListener listener)
IRpcManagerThis is an idempotent operation.
addRpcPublicationListener in interface IRpcManagerremoteContextIdentity - the remote context to monitor for RPC publish/unpublish eventslistener - a listener to receive the RPC publish/unpublish events.
true if the listener was added, false
otherwise
public boolean removeRpcPublicationListener(String remoteContextIdentity,
IRpcPublicationListener listener)
IRpcManagerThis is an idempotent operation.
removeRpcPublicationListener in interface IRpcManagerremoteContextIdentity - the remote context that the listener was monitoring for RPC
publish/unpublish eventslistener - the listener to remove
true if the listener was found and removed,
false otherwiseprotected void doDestroy()
AbstractLifeCycleRuntimeException or subclass
thereof.
doDestroy in class AbstractLifeCycleprotected void doStart()
AbstractLifeCycleRuntimeException or subclass
thereof. When this method is called, the AbstractLifeCycle.isActive() method will
return true.
doStart in class AbstractLifeCycleprotected AsyncLog getLog()
AbstractLifeCycle
getLog in class AbstractLifeCycle
public DualValue<String,IRpcDefinition> getRegistryKeyAndDefinition(String remoteContextIdentity,
String procedure,
IField[] args)
IRpcDefinition for the procedure.
This checks the RPC registry record of the remote context to find the key
for an RPC with matching name and arguments.
getRegistryKeyAndDefinition in interface IRpcManagerOperationsremoteContextIdentity - the remote contextprocedure - the RPC nameargs - the RPC arguments
IRpcDefinition for the RPC in
the remote context or null if not found
public boolean unpublishRpcs(Class<?> definition,
Object handler)
IRpcPublishOperationsIRpcPublishOperations.publishRpcs(Class, Object)
unpublishRpcs in interface IRpcPublishOperationsdefinition - 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.
true if all methods were successfully unpublished
public boolean publishRpcs(Class<?> definition,
Object handler)
IRpcPublishOperationsThere 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:
This is a convenience method in-lieu of calling
IRpcPublishOperations.publishProdedure(IRpcHandler, IRpcDefinition).
publishRpcs in interface IRpcPublishOperationsdefinition - 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.
true if all methods were successfully published
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||