org.openorb.adapter
Interface ObjectAdapter

All Known Implementing Classes:

BOA, ForwardAdapter

public interface ObjectAdapter

Object adapters act as a contianer for servant objects and for child adapters. Servants and adapters may be created by object adapters in response to a particular request being initiated.

Version:

$Revision: 1.4 $ $Date: 2002/06/28 08:59:04 $

Author:

Chris Wood

Method Summary

byte[]	adapter_id(byte[] object_key) Return the adapter id.
int	cache_priority() Expected lifetime of the adapter.
void	cancel_dispatch(ServerRequest req, TargetInfo target) Cancel a dispatch.
void	dispatch(ServerRequest req, TargetInfo target) Dispatch a request from a client.
void	etherealize(boolean cleanup_in_progress) Etherealize the adapter.
ObjectAdapter	find_adapter(byte[] object_key) Find an adapter or an ancestor adapter to serve requests to the specified object key.
boolean	forced_marshal(byte[] object_key) If this returns true then requests for the specified object id must be sent through the network.
Object	get_component(byte[] object_key) get_componenent operation.
DomainManager[]	get_domain_managers(byte[] object_key) get_domain_manager operation.
Object	get_interface_def(byte[] object_key) get_interface_def operation.
Policy[]	get_server_policies(int[] ts) Returns a PolicyList containing the Polices set for the requested PolicyTypes.
ServerManager.AdapterManager	getAdapterManager() Queue manager for the adapter.
boolean	is_a(byte[] object_key, java.lang.String repository_id) is_a operation.
boolean	locate(byte[] object_key) Respond to a local locate request.
byte[]	object_id(byte[] object_key) Return the object id.
TargetInfo	predispatch(ServerRequest req) Locate the servant object for a request.
void	servant_postinvoke(byte[] object_key, ServantObject srvObject) Close off a local operation.
ServantObject	servant_preinvoke(byte[] object_key, java.lang.String operation, java.lang.Class expectedType) Preinvoke a local operation.
boolean	single_threaded() Adapter is single threaded.

Method Detail

cache_priority

public int cache_priority()

Expected lifetime of the adapter. Higher numbers are more likley to be dropped from the lookup cache. If this returns 0 then the adapter should never be dropped. This value should be stable throughout the lifetime of the adapter. The highest byte will be used for determining the binding priority.

 Suggested values:
 = 0          Root adapters. Always keep.
 < 0x1000000  Adpaters created directly. (these will never be
              temporarily etherialized)
 < 0x2000000  Adapters created dynamicaly. 
 < 0x3000000  Objects created directly.
 < 0x4000000  Objects created dynamicaly.
 < 0          Never cache adapter, single invocation only.
             These should not be returned from find_adapter.
 

single_threaded

public boolean single_threaded()

Adapter is single threaded. All non-local calls to single threaded adapters are serialized.

etherealize

public void etherealize(boolean cleanup_in_progress)

Etherealize the adapter. When this function returns the adapter's memory resident state should have been minimized. This function will always be called before purging the adapter from the cache.

Parameters:

cleanup_in_progress - if true the adapter is being perminently deactivated and will no longer have to dispatch operations.

getAdapterManager

public ServerManager.AdapterManager getAdapterManager()

Queue manager for the adapter. This may return null for an adapter which is always active. To create an adapter manager for an adapter use the create_manager operation on the ServerManager.

find_adapter

public ObjectAdapter find_adapter(byte[] object_key)
                           throws AdapterDestroyedException

Find an adapter or an ancestor adapter to serve requests to the specified object key. If this adapter serves this object directly it should return itself, if it can find a decendant adapter which serves the request without entering user code the decendant is returned. If user code associated with a decendant adapter which does not share this adapter's adapter manager or is a single thread adapter must be excecuted in order to create an adapter then that decendant adapter is returned. In essence the requirement that the adapter manager must be consulted before excecuting user code is preserved. If a decendant adapter is in the process of being destroyed the AdapterDestroyedException is thrown. The find operation can be re-tried once the adapter has been destroyed. The object key passed to this argument will always be prefixed by the adapter id as registered in the server manager. If only one registration is present then the prefix does not need to be checked for a match with the adapter id.

adapter_id

public byte[] adapter_id(byte[] object_key)

Return the adapter id. This should be a prefix of the object_key if the object id is cacheable, it should be stable with respect to a given object_key and will be treated as read-only. If an object with the given object_key is not served by this adapter this returns null.

object_id

public byte[] object_id(byte[] object_key)

Return the object id. This should should be a suffix of the object_key if the object id is cacheable, it should be stable with respect to a given object_key and will be treated as read-only. If an object with the given object_key is not served by this adapter this returns null.

get_server_policies

public Policy[] get_server_policies(int[] ts)

Returns a PolicyList containing the Polices set for the requested PolicyTypes. If the specified sequence is empty, all Policy overrides will be returned. If none of the requested PolicyTypes are overridden an empty sequence is returned.

forced_marshal

public boolean forced_marshal(byte[] object_key)
                       throws AdapterDestroyedException

If this returns true then requests for the specified object id must be sent through the network. This will be true for example when using the DSI. This should return true if the object_key is unknown to the adapter. The result should be stable with respect to a given object ID.

servant_preinvoke

public ServantObject servant_preinvoke(byte[] object_key,
                                       java.lang.String operation,
                                       java.lang.Class expectedType)
                                throws ForwardRequest,
                                       AdapterDestroyedException

Preinvoke a local operation. Always paired with a call to servant_postinvoke. If the given object_key was not created by this adapter an OBJ_ADAPTER exception is thrown, if the object does not exist this throws an OBJECT_NOT_EXIST exception.

servant_postinvoke

public void servant_postinvoke(byte[] object_key,
                               ServantObject srvObject)

Close off a local operation. Always paired with a call to servant_preinvoke

locate

public boolean locate(byte[] object_key)
               throws ForwardRequest,
                      AdapterDestroyedException

Respond to a local locate request. This returns true if the object is located locally, false if the object is unknown and throws a forward request for a location forward. This should not throw a system exception.

is_a

public boolean is_a(byte[] object_key,
                    java.lang.String repository_id)
             throws ForwardRequest,
                    AdapterDestroyedException

is_a operation. If the given object_key was not created by this adapter an OBJ_ADAPTER exception is thrown, if the object does not exist OBJECT_NOT_EXIST is thrown.

get_interface_def

public Object get_interface_def(byte[] object_key)
                         throws ForwardRequest,
                                AdapterDestroyedException

get_interface_def operation. If the given object_key was not created by this adapter an OBJ_ADAPTER exception is thrown, if the object does not exist OBJECT_NOT_EXIST is thrown.

get_domain_managers

public DomainManager[] get_domain_managers(byte[] object_key)
                                    throws ForwardRequest,
                                           AdapterDestroyedException

get_domain_manager operation. If the given object_key was not created by this adapter an OBJ_ADAPTER exception is thrown, if the object does not exist OBJECT_NOT_EXIST is thrown.

get_component

public Object get_component(byte[] object_key)
                     throws ForwardRequest,
                            AdapterDestroyedException

get_componenent operation. If the given object_key was not created by this adapter an OBJ_ADAPTER exception is thrown, if the object does not exist OBJECT_NOT_EXIST is thrown.

predispatch

public TargetInfo predispatch(ServerRequest req)
                       throws ForwardRequest,
                              AdapterDestroyedException

Locate the servant object for a request. The returned object is handed to the dispatch operation. This may throw a system exception or respond with a forward request if one is indicated, in which case the dispatch operation will not be called.

Parameters:

ids - out parameter holding repository ids of all available interfaces with the most derived interface appearing first.

Returns:

the 'target' of the operation. This is simply passed to the dispatch operation and is not interpreted in any way.

dispatch

public void dispatch(ServerRequest req,
                     TargetInfo target)

Dispatch a request from a client. This may throw a system exception at any time or call the ResponseHandler interface on the request to create a standard reply. If this returns without calling a response handler an empty reply is constructed, this is the usual situation for a locate request.

cancel_dispatch

public void cancel_dispatch(ServerRequest req,
                            TargetInfo target)

Cancel a dispatch. This may follow a predispatch or dispatch call to indicate that the client no longer expects any reply from the request and the server can stop expending effort towards completing it.