com.threerings.presents.server
Class InvocationManager

java.lang.Object
  com.threerings.presents.server.InvocationManager

All Implemented Interfaces:

ChangeListener, EventListener

public class InvocationManager
extends Object
implements EventListener

The invocation services provide client to server invocations (service requests) and server to client invocations (responses and notifications). Via this mechanism, the client can make requests of the server, be notified of its response and the server can asynchronously invoke code on the client.

Invocations are like remote procedure calls in that they are named and take arguments. All arguments must be Streamable objects, primitive types, or String objects. All arguments are passed by value (by serializing and unserializing the arguments); there is no special facility provided for referencing non-local objects (it is assumed that the distributed object facility will already be in use for any objects that should be shared).

The server invocation manager listens for invocation requests from the client and passes them on to the invocation provider registered for the requested invocation module. It also provides a mechanism by which responses and asynchronous notification invocations can be delivered to the client.

Nested Class Summary

protected static interface

InvocationManager.Dispatcher

Field Summary

protected Multimap<String,InvocationMarshaller<?>>	_bootlists Maps bootstrap group to lists of services to be provided to clients at boot time.
protected IntMap<InvocationManager.Dispatcher>	_dispatchers A table of invocation dispatchers each mapped by a unique code.
protected int	_invCode Used to generate monotonically increasing provider ids.
protected int	_invoid The object id of the object on which we receive invocation service requests.
protected PresentsDObjectMgr	_omgr The distributed object manager we're working with.
protected Map<Integer,String>	_recentRegServices Tracks recently registered services so that we can complain informatively if a request comes in on a service we don't know about.
protected Client	_standaloneClient A reference to the standalone client, if any.
protected static String	FAILED_SUFFIX The text appended to the procedure name when generating a failure response.

Constructor Summary

InvocationManager(PresentsDObjectMgr omgr)
Constructs an invocation manager which will use the supplied distributed object manager to operate its invocation services.

Method Summary

void	clearDispatcher(InvocationMarshaller<?> marsh) Clears out a dispatcher registration.
protected void	dispatchRequest(int clientOid, int invCode, int methodId, Object[] args, Transport transport) Called when we receive an invocation request message.
void	eventReceived(DEvent event) Called when any event has been dispatched on an object.
List<InvocationMarshaller<?>>	getBootstrapServices(String[] bootGroups) Constructs a list of all bootstrap services registered in any of the supplied groups.
Class<?>	getDispatcherClass(int invCode) Get the class that is being used to dispatch the specified invocation code, for informational purposes.
int	getOid() Returns the object id of the invocation services object.
protected int	nextInvCode() Used to generate monotonically increasing provider ids.
<T extends InvocationMarshaller<?>> T	registerDispatcher(InvocationDispatcher<T> dispatcher) Registers the supplied invocation dispatcher, returning a marshaller that can be used to send requests to the provider for whom the dispatcher is proxying.
<T extends InvocationMarshaller<?>> T	registerDispatcher(InvocationDispatcher<T> dispatcher, boolean bootstrap) Deprecated. use registerDispatcher(InvocationDispatcher).
<T extends InvocationMarshaller<?>> T	registerDispatcher(InvocationDispatcher<T> dispatcher, String group) Registers the supplied invocation dispatcher, returning a marshaller that can be used to send requests to the provider for whom the dispatcher is proxying.
<T extends InvocationMarshaller<?>> T	registerProvider(InvocationProvider provider, Class<T> mclass) Registers the supplied invocation service provider.
<T extends InvocationMarshaller<?>> T	registerProvider(InvocationProvider provider, Class<T> mclass, String group) Registers the supplied invocation service provider.

Methods inherited from class java.lang.Object

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

Field Detail

_invoid

protected int _invoid

The object id of the object on which we receive invocation service requests.

_invCode

protected int _invCode

Used to generate monotonically increasing provider ids.

_standaloneClient

@Inject(optional=true)
protected Client _standaloneClient

A reference to the standalone client, if any.

_omgr

protected PresentsDObjectMgr _omgr

The distributed object manager we're working with.

_dispatchers

protected IntMap<InvocationManager.Dispatcher> _dispatchers

A table of invocation dispatchers each mapped by a unique code.

_bootlists

protected Multimap<String,InvocationMarshaller<?>> _bootlists

Maps bootstrap group to lists of services to be provided to clients at boot time.

_recentRegServices

protected final Map<Integer,String> _recentRegServices

Tracks recently registered services so that we can complain informatively if a request comes in on a service we don't know about.

FAILED_SUFFIX

protected static final String FAILED_SUFFIX

The text appended to the procedure name when generating a failure response.

See Also:

Constant Field Values

Constructor Detail

InvocationManager

@Inject
public InvocationManager(PresentsDObjectMgr omgr)

Constructs an invocation manager which will use the supplied distributed object manager to operate its invocation services. Generally only one invocation manager should be operational in a particular system.

Method Detail

getOid

public int getOid()

Returns the object id of the invocation services object.

registerProvider

public <T extends InvocationMarshaller<?>> T registerProvider(InvocationProvider provider,
                                                              Class<T> mclass)

Registers the supplied invocation service provider.

Parameters:

provider - the provider to be registered.

mclass - the class of the invocation marshaller generated for the service.

registerProvider

public <T extends InvocationMarshaller<?>> T registerProvider(InvocationProvider provider,
                                                              Class<T> mclass,
                                                              String group)

Registers the supplied invocation service provider.

Parameters:

provider - the provider to be registered.

mclass - the class of the invocation marshaller generated for the service.

group - the bootstrap group in which this marshaller is to be registered, or null if it is not a bootstrap service. Do not: register a marshaller with multiple boot groups. You must collect shared marshaller into as fine grained a set of groups as necessary and have different types of clients specify the list of groups they need.

registerDispatcher

public <T extends InvocationMarshaller<?>> T registerDispatcher(InvocationDispatcher<T> dispatcher)

Registers the supplied invocation dispatcher, returning a marshaller that can be used to send requests to the provider for whom the dispatcher is proxying.

Parameters:

dispatcher - the dispatcher to be registered.

registerDispatcher

@Deprecated
public <T extends InvocationMarshaller<?>> T registerDispatcher(InvocationDispatcher<T> dispatcher,
                                                                           boolean bootstrap)

Deprecated. use registerDispatcher(InvocationDispatcher).

registerDispatcher

public <T extends InvocationMarshaller<?>> T registerDispatcher(InvocationDispatcher<T> dispatcher,
                                                                String group)

Registers the supplied invocation dispatcher, returning a marshaller that can be used to send requests to the provider for whom the dispatcher is proxying.

Parameters:

dispatcher - the dispatcher to be registered.

group - the bootstrap group in which this marshaller is to be registered, or null if it is not a bootstrap service. Do not: register a dispatcher with multiple boot groups. You must collect shared dispatchers into as fine grained a set of groups as necessary and have different types of clients specify the list of groups they need.

clearDispatcher

public void clearDispatcher(InvocationMarshaller<?> marsh)

Clears out a dispatcher registration. This should be called to free up resources when an invocation service is no longer going to be used.

getBootstrapServices

public List<InvocationMarshaller<?>> getBootstrapServices(String[] bootGroups)

Constructs a list of all bootstrap services registered in any of the supplied groups.

getDispatcherClass

public Class<?> getDispatcherClass(int invCode)

Get the class that is being used to dispatch the specified invocation code, for informational purposes.

Returns:

the Class, or null if no dispatcher is registered with the specified code.

eventReceived

public void eventReceived(DEvent event)

Description copied from interface: EventListener

Called when any event has been dispatched on an object. The event will be of the derived class that corresponds to the kind of event that occurred on the object. This will be called after the event has been applied to the object. So fetching an attribute upon receiving an attribute changed event will provide the new value for the attribute.

Specified by:

eventReceived in interface EventListener

Parameters:

event - The event that was dispatched on the object.

dispatchRequest

protected void dispatchRequest(int clientOid,
                               int invCode,
                               int methodId,
                               Object[] args,
                               Transport transport)

Called when we receive an invocation request message. Dispatches the request to the appropriate invocation provider via the registered invocation dispatcher.

nextInvCode

protected int nextInvCode()

Used to generate monotonically increasing provider ids.