Interface ObjectAdapter
-
- All Known Subinterfaces:
TOA
- All Known Implementing Classes:
ObjectAdapterBase
,POAImpl
,TOAImpl
@ManagedObject @Description("ObjectAdapter used to dispatch requests and manage servants") public interface ObjectAdapter
ObjectAdapter represents the abstract model of an object adapter that was introduced by ORT. This means that all object adapters must:- Have an ORB
- Have a name
- Have an adapter manager (represented by an ID)
- Have an adapter template
- Support getting and setting their ObjectReferenceFactory
- Provide access to their current state
- Support adding components to their profiles expressed in the adapter template
- All object adapters must invoke ORB.AdapterCreated when they are created.
- All adapter managers must invoke ORB.AdapterManagerStateChanged when their state changes, mapping the internal state to an ORT state.
- AdapterStateChanged must be invoked (from somewhere) whenever an adapter state changes that is not due to an adapter manager state change.
Object adapters must also provide mechanisms for:
- Managing object reference lifecycle
- Controlling how servants are associated with object references
- Manage the state of the adapter, if the adapter desires to implement such mechanisms
The basic function of an ObjectAdapter is to map object IDs to servants and to support the dispatch operation of the subcontract, which dispatches requests to servants. This is the purpose of the getInvocationServant method. In addition, ObjectAdapters must be able to change state gracefully in the presence of executing methods. This requires the use of the enter/exit methods. Finally, ObjectAdapters often require access to information about requests. This is accomodated through the OAInvocationInfo class and the thread local stack maintained by push/pop/peekInvocationInfo on the ORB.
To be useful, this dispatch cycle must be extremely efficient. There are several scenarios that matter:
- A remote invocation, where the dispatch is handled in the server subcontract.
- A local invocation, where the dispatch is handled in the client subcontract.
- A cached local invocation, where the servant is cached when the IOR is established for the client subcontract, and the dispatch is handled in the client subcontract to the cached subcontract.
Each of these 3 cases is handled a bit differently. On each request, assume as known ObjectId and ObjectAdapterId, which can be obtained from the object key. The ObjectAdaptorFactory is available in the subcontract registry, where it is registered under the subcontract ID. The Subcontract ID is also available in the object key.
- The remote pattern:
- oa = oaf.find( oaid )
- oa.enter()
- info = oa.makeInvocationInfo( oid )
- info.setOperation( operation )
- push info
- oa.getInvocationServant( info )
- sreq.setExecuteReturnServantInResponseConstructor( true )
- dispatch to servant
- oa.returnServant()
- oa.exit()
- pop info
- REVISIT: Is this the required order for exit/pop? Can they be nested instead? Note that getInvocationServant and returnServant may throw exceptions. In such cases, returnServant, exit, and pop must be called in the correct order.
- The local pattern:
- oa = oaf.find( oaid )
- oa.enter()
- info = oa.makeInvocationInfo( oid )
- info.setOperation( operation )
- push info
- oa.getInvocationServant( info )
- dispatch to servant
- oa.returnServant()
- oa.exit()
- pop info
- This is the same as the remote case, except that setExecuteReturnServantInResponseConstructor is not needed (or possible, since there is no server request).
- The fast local pattern: When delegate is constructed,
first extract ObjectKey from IOR in delegate,
then get ObjectId, ObjectAdapterId, and ObjectAdapterFactory (oaf). Then:
- oa = oaf.find( oaid )
- info = oa.makeInvocationInfo( oid ) (note: no operation!)
- push info (needed for the correct functioning of getInvocationServant)
- oa.getInvocationServant( info )
- pop info
Then, on each invocation:
- newinfo = copy of info (clone)
- info.setOperation( operation )
- push newinfo
- oa.enter()
- dispatch to servant
- oa.returnServant()
- oa.exit()
- pop info
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
enter()
enter must be called before each request is invoked on a servant.void
exit()
exit must be called after each request has been completed.ObjectReferenceTemplate
getAdapterTemplate()
ObjectReferenceFactory
getCurrentFactory()
Policy
getEffectivePolicy(int type)
java.lang.String[]
getInterfaces(java.lang.Object servant, byte[] objectId)
Return the most derived interface for the given servant and objectId.void
getInvocationServant(OAInvocationInfo info)
Get the servant for the request given by the parameters.IORTemplate
getIORTemplate()
Returns the IOR template of this adapter.Object
getLocalServant(byte[] objectId)
Get the servant corresponding to the given objectId, if this is supported.int
getManagerId()
Return the ID of the AdapterManager for this object adapter.ORB
getORB()
Returns the ORB associated with this adapter.short
getState()
Return the current state of this object adapter (seeorg.omg.PortableInterceptor
for states).boolean
isNameService()
OAInvocationInfo
makeInvocationInfo(byte[] objectId)
Create an instance of InvocationInfo that is appropriate for this Object adapter.void
returnServant()
Must be called every time getInvocationServant is called after the request has completed.void
setCurrentFactory(ObjectReferenceFactory factory)
Change the current factory.void
setNameService(boolean flag)
-
-
-
Method Detail
-
getORB
ORB getORB()
Returns the ORB associated with this adapter.- Returns:
- the associated ORB
-
getEffectivePolicy
Policy getEffectivePolicy(int type)
-
getIORTemplate
@ManagedAttribute @Description("The IORTemplate used to create Object References") IORTemplate getIORTemplate()
Returns the IOR template of this adapter. The profiles in this template may be updated only during the AdapterCreated call. After that call completes, the IOR template must be made immutable. Note that the server ID, ORB ID, and adapter name are all available from the IOR template.- Returns:
- IOR template of this adapter
-
getManagerId
@ManagedAttribute @Description("The identifier for the AdapterManager that manages this ObjectAdapter") int getManagerId()
Return the ID of the AdapterManager for this object adapter.- Returns:
- the identifier
-
getState
short getState()
Return the current state of this object adapter (seeorg.omg.PortableInterceptor
for states).- Returns:
- the current state of this object adapter
- See Also:
org.omg.PortableInterceptor
-
getAdapterTemplate
@ManagedAttribute @Description("The adapter template") ObjectReferenceTemplate getAdapterTemplate()
-
getCurrentFactory
@ManagedAttribute @Description("The current object reference factory") ObjectReferenceFactory getCurrentFactory()
-
setCurrentFactory
void setCurrentFactory(ObjectReferenceFactory factory)
Change the current factory. This may only be called during the AdapterCreated call.- Parameters:
factory
- replacement factory
-
getLocalServant
Object getLocalServant(byte[] objectId)
Get the servant corresponding to the given objectId, if this is supported. This method is only used for models where the servant is an ObjectImpl, which allows the servant to be used directly as the stub. This allows an object reference to be replaced by its servant when it is unmarshalled locally. Such objects are not ORB mediated.- Parameters:
objectId
- byte array representing the object ID- Returns:
- corresponding servant
-
getInvocationServant
void getInvocationServant(OAInvocationInfo info)
Get the servant for the request given by the parameters. info must contain a valid objectId in this call. The servant is set in the InvocationInfo argument that is passed into this call.- Parameters:
info
- is the InvocationInfo object for the object reference- Throws:
ForwardException
- (a runtime exception) is thrown if the request is to be handled by a different object reference.
-
enter
void enter() throws OADestroyed
enter must be called before each request is invoked on a servant.- Throws:
OADestroyed
- is thrown when an OA has been destroyed, which requires a retry in the case where an AdapterActivator is present.
-
exit
void exit()
exit must be called after each request has been completed. If enter is called and completes normally, there must always be a corresponding exit. If enter throw OADestroyed, exit must NOT be called.
-
returnServant
void returnServant()
Must be called every time getInvocationServant is called after the request has completed.
-
makeInvocationInfo
OAInvocationInfo makeInvocationInfo(byte[] objectId)
Create an instance of InvocationInfo that is appropriate for this Object adapter.- Parameters:
objectId
- ID of object to create- Returns:
- created instance
-
getInterfaces
java.lang.String[] getInterfaces(java.lang.Object servant, byte[] objectId)
Return the most derived interface for the given servant and objectId.- Parameters:
servant
- servant objectobjectId
- byte array forming the objectId- Returns:
- list of derived interfaces
-
isNameService
boolean isNameService()
-
setNameService
void setNameService(boolean flag)
-
-