javax.slee.resource

Interface ResourceAdaptor

public interface ResourceAdaptor

The ResourceAdaptor interface is implemented by every resource adaptor class. Every Resource Adaptor must include a resource adaptor class. The SLEE uses the methods defined in this interface to notify resource adaptor objects about lifecycle changes, configuration changes, services (event consumers) installed in the SLEE, and to notify the resource adaptor object about the result of event processing.

Since:

SLEE 1.1

Method Summary

Methods

Modifier and Type	Method and Description
void	activityEnded(ActivityHandle handle) The SLEE invokes this method on a resource adaptor object when the SLEE has completed activity end processing for the activity corresponding to the specified activity handle.
void	activityUnreferenced(ActivityHandle handle) The SLEE invokes this method on a resource adaptor object when the Activity Context in the SLEE corresponding to the given activity handle is no longer attached to any SBB entities, is no longer referenced by any SLEE Facilities, and has no events being processed or waiting to be processed on the activity.
void	administrativeRemove(ActivityHandle handle) The SLEE invokes this method to inform the resource adaptor that the activity and activity context corresponding to the specified activity handle has been removed from the SLEE due to an administrative action.
void	eventProcessingFailed(ActivityHandle handle, FireableEventType eventType, Object event, Address address, ReceivableService service, int flags, FailureReason reason) The SLEE invokes this method on a resource adaptor object to inform it that an event it fired to the SLEE could not be processed successfully.
void	eventProcessingSuccessful(ActivityHandle handle, FireableEventType eventType, Object event, Address address, ReceivableService service, int flags) The SLEE invokes this method on a resource adaptor object to inform it that an event it fired to the SLEE has been processed successfully.
void	eventUnreferenced(ActivityHandle handle, FireableEventType eventType, Object event, Address address, ReceivableService service, int flags) The SLEE invokes this method on a resource adaptor object when the event object for an event fired by the resource adaptor is no longer referenced by the SLEE.
Object	getActivity(ActivityHandle handle) Get the activity object corresponding to the specified activity handle.
ActivityHandle	getActivityHandle(Object activity) Get the activity handle corresponding to the specified activity object.
Marshaler	getMarshaler() Get the activity handle and event marshaler for the resource adaptor.
Object	getResourceAdaptorInterface(String className) Get an implementation object of the specified resource adaptor interface.
void	queryLiveness(ActivityHandle handle) The SLEE invokes this method to ask the resource adaptor to check an activity for liveness.
void	raActive() The SLEE invokes this method on a resource adaptor object when it transitions from the Inactive state to the Active state.
void	raConfigurationUpdate(ConfigProperties properties) This method is invoked by the SLEE whenever the Administrator successfully updates a resource adaptor entity with new configuration properties.
void	raConfigure(ConfigProperties properties) The SLEE invokes this method on a resource adaptor object in the Unconfigured state to provide the resource adaptor object with configuration properties for the resource adaptor entity.
void	raInactive() The SLEE invokes this method on a resource adaptor object in the Stopping state once all activities owned by the resource adaptor object have ended in the SLEE.
void	raStopping() The SLEE invokes this method on a resource adaptor object in the Active state to notify the resource adaptor object that it must stop generating new activities and begin to cleanup any existing activities.
void	raUnconfigure() The SLEE invokes this method on a resource adaptor object in the Inactive state in order to unconfigure it.
void	raVerifyConfiguration(ConfigProperties properties) This method is invoked by the SLEE whenever a new resource adaptor entity is created by the Administrator, or when the Administrator attempts to update the configuration properties of an existing resource adaptor entity.
void	serviceActive(ReceivableService serviceInfo) The SLEE invokes this method on a resource adaptor object when a service that is interested in events generated by this resource adaptor has transitioned to the Active state.
void	serviceInactive(ReceivableService serviceInfo) The SLEE invokes this method on a resource adaptor object when a service that is interested in events generated by this resource adaptor has transitioned from the Stopping state to the Inactive state.
void	serviceStopping(ReceivableService serviceInfo) The SLEE invokes this method on a resource adaptor object when a service that is interested in events generated by this resource adaptor has transitioned to the Stopping state.
void	setResourceAdaptorContext(ResourceAdaptorContext context) Set the ResourceAdaptorContext object for the resource adaptor object.
void	unsetResourceAdaptorContext() Unset the ResourceAdaptorContext object for the resource adaptor object.

Method Detail

setResourceAdaptorContext

void setResourceAdaptorContext(ResourceAdaptorContext context)

Set the ResourceAdaptorContext object for the resource adaptor object. The SLEE invokes this method immediately after a new resource adaptor object has been created. The ResourceAdaptorContext object passed to the resource adaptor object via this method provides the resource adaptor object with access to SLEE Facilities. If the resource adaptor object needs to use the ResourceAdaptorContext object during its lifetime, it should store the ResourceAdaptorContext object reference in an instance variable.

The resource adaptor object enters the Unconfigured state after this method returns.

This method is invoked with an unspecified transaction context. If the resource adaptor needs the use of a transaction during this method then it should use the SleeTransactionManager to detect the presence or lack of any current transaction and manage that transaction and any that it starts itself appropriately. The resource adaptor must exit from this method with the same transaction context as it was invoked (if any).

Parameters:

context - the ResourceAdaptorContext object given to the resource adaptor object by the SLEE.

unsetResourceAdaptorContext

void unsetResourceAdaptorContext()

Unset the ResourceAdaptorContext object for the resource adaptor object. If the resource adaptor object stored a reference to the ResourceAdaptorContext object given to it in the setResourceAdaptorContext method, the resource adaptor object should clear that reference during this method.

This method is invoked on a resource adaptor object in the Unconfigured state and is the last method invoked on a resource adaptor object before it becomes a candidate for garbage collection.

This method is invoked with an unspecified transaction context. If the resource adaptor needs the use of a transaction during this method then it should use the SleeTransactionManager to detect the presence or lack of any current transaction and manage that transaction and any that it starts itself appropriately. The resource adaptor must exit from this method with the same transaction context as it was invoked (if any).

raConfigure

void raConfigure(ConfigProperties properties)

The SLEE invokes this method on a resource adaptor object in the Unconfigured state to provide the resource adaptor object with configuration properties for the resource adaptor entity. This may occur when a new resource adaptor entity is created, or for existing resource adaptor entities during SLEE startup.

The resource adaptor object transitions to the Inactive state after this method returns.

This method is invoked with an unspecified transaction context. If the resource adaptor needs the use of a transaction during this method then it should use the SleeTransactionManager to detect the presence or lack of any current transaction and manage that transaction and any that it starts itself appropriately. The resource adaptor must exit from this method with the same transaction context as it was invoked (if any).

Parameters:

properties - the configuration properties specified for the resource adaptor entity.

raUnconfigure

void raUnconfigure()

The SLEE invokes this method on a resource adaptor object in the Inactive state in order to unconfigure it. Typically this occurs when the corresponding resource adaptor entity is being removed from the SLEE and so the resource adaptor object is no longer required. The implementation of this method should release any resources allocated by the resource adaptor object during the raConfigure method.

The resource adaptor object transitions to the Unconfigured state after this method returns.

This method is invoked with an unspecified transaction context. If the resource adaptor needs the use of a transaction during this method then it should use the SleeTransactionManager to detect the presence or lack of any current transaction and manage that transaction and any that it starts itself appropriately. The resource adaptor must exit from this method with the same transaction context as it was invoked (if any).

raActive

void raActive()

The SLEE invokes this method on a resource adaptor object when it transitions from the Inactive state to the Active state. It is used to notify the resource adaptor object that it may now start to generate activities and events. The SLEE invokes this method when the following conditions both become true:

1. The SLEE is in the Running state.
2. The corresponding resource adaptor entity is in the Active state.

The resource adaptor object transitions to the Active state before this method is invoked, allowing it to start activities during this method invocation if required.

This method is invoked with an unspecified transaction context. If the resource adaptor needs the use of a transaction during this method then it should use the SleeTransactionManager to detect the presence or lack of any current transaction and manage that transaction and any that it starts itself appropriately. The resource adaptor must exit from this method with the same transaction context as it was invoked (if any).

raStopping

void raStopping()

The SLEE invokes this method on a resource adaptor object in the Active state to notify the resource adaptor object that it must stop generating new activities and begin to cleanup any existing activities. The SLEE invokes this method when either of the following conditions become true:

1. The SLEE transitions to the Stopping state.
2. The corresponding resource adaptor entity transitions to the Stopping state.

During this method the resource adaptor object should alter its internal state so that it does not attempt to start new activities once this method returns. The resource adaptor object transitions to the Stopping state after this method returns.

This method is invoked with an unspecified transaction context. If the resource adaptor needs the use of a transaction during this method then it should use the SleeTransactionManager to detect the presence or lack of any current transaction and manage that transaction and any that it starts itself appropriately. The resource adaptor must exit from this method with the same transaction context as it was invoked (if any).

raInactive

void raInactive()

The SLEE invokes this method on a resource adaptor object in the Stopping state once all activities owned by the resource adaptor object have ended in the SLEE. The implementation of this method should release any resources allocated by the resource adaptor object during the raActive method.

The resource adaptor object transitions to the Inactive state after this method returns.

This method is invoked with an unspecified transaction context. If the resource adaptor needs the use of a transaction during this method then it should use the SleeTransactionManager to detect the presence or lack of any current transaction and manage that transaction and any that it starts itself appropriately. The resource adaptor must exit from this method with the same transaction context as it was invoked (if any).

raVerifyConfiguration

void raVerifyConfiguration(ConfigProperties properties)
                           throws InvalidConfigurationException

This method is invoked by the SLEE whenever a new resource adaptor entity is created by the Administrator, or when the Administrator attempts to update the configuration properties of an existing resource adaptor entity. The implementation of this method should examine the configuration properties supplied and verify that the configuration properties are valid for the resource adaptor.

This method may be invoked on a resource adaptor object in any valid state, therefore the implementation of this method should assume nothing about the internal state of the resource adaptor object.

This method is invoked with an unspecified transaction context. If the resource adaptor needs the use of a transaction during this method then it should use the SleeTransactionManager to detect the presence or lack of any current transaction and manage that transaction and any that it starts itself appropriately. The resource adaptor must exit from this method with the same transaction context as it was invoked (if any).

Parameters:

properties - contains the proposed new values for all configuration properties specified for the resource adaptor entity.

Throws:

InvalidConfigurationException - if the configuration properties are not valid for some reason.

raConfigurationUpdate

void raConfigurationUpdate(ConfigProperties properties)

This method is invoked by the SLEE whenever the Administrator successfully updates a resource adaptor entity with new configuration properties. The implementation of this method should apply the new configuration properties to its internal state.

If the supports-active-reconfiguration attribute of the <resource-adaptor-class> element in the resource adaptor's deployment descriptor has the value False, then this method will only be invoked on a resource adaptor object in the Inactive state. If the value of the supports-active-reconfiguration attribute is True, then this method may be invoked on a resource adaptor object that is in the Inactive, Active, or Stopping state.

This method is invoked with an unspecified transaction context. If the resource adaptor needs the use of a transaction during this method then it should use the SleeTransactionManager to detect the presence or lack of any current transaction and manage that transaction and any that it starts itself appropriately. The resource adaptor must exit from this method with the same transaction context as it was invoked (if any).

Parameters:

properties - contains the new values for all configuration properties specified for the resource adaptor entity.

getResourceAdaptorInterface

Object getResourceAdaptorInterface(String className)

Get an implementation object of the specified resource adaptor interface.

Each resource adaptor type may specify a resource adaptor interface that SBBs can use to interact with a resource adaptor implementing that resource adaptor type. This method is used by the SLEE to obtain the implementation objects for the resource adaptor interfaces specified by each resource adaptor type implemented by this resource adaptor.

If none of the resource adaptor types implemented by a resource adaptor specify a resource adaptor interface, this method may return a default value of null as the SLEE will never invoke the method.

This method is invoked with an unspecified transaction context.

Parameters:

className - the fully-qualified class name of the resource adaptor interface, as specified by the resource adaptor type, required by the SLEE.

Returns:

an object that implements (and is therefore type-castable to) the specified resource adaptor interface.

getMarshaler

Marshaler getMarshaler()

Get the activity handle and event marshaler for the resource adaptor.

This method is invoked with an unspecified transaction context.

Returns:

the activity handle and event marshaler.

serviceActive

void serviceActive(ReceivableService serviceInfo)

The SLEE invokes this method on a resource adaptor object when a service that is interested in events generated by this resource adaptor has transitioned to the Active state. This method may be invoked when the service is activated by the Administrator, or when the SLEE is restarted and the service was previously in the Active state before the restart.

This method may be invoked by the SLEE when the resource adaptor object is in the Inactive, Active, or Stopping state.

The SLEE need only provide a resource adaptor with information about the event types received by the service that the resource adaptor may fire. Generally this is limited to the resource adaptor types implemented by the resource adaptor. However a resource adaptor may be able to fire events of any type if its deployment descriptor has disabled this limitation, and in such cases the SLEE should provide the resource adaptor with information about all the event types that may be received by the service.

This method is invoked with an unspecified transaction context. If the resource adaptor needs the use of a transaction during this method then it should use the SleeTransactionManager to detect the presence or lack of any current transaction and manage that transaction and any that it starts itself appropriately. The resource adaptor must exit from this method with the same transaction context as it was invoked (if any).

Parameters:

serviceInfo - information about the service that is now Active and the types of events that SBBs in the service may receive.

serviceStopping

void serviceStopping(ReceivableService serviceInfo)

The SLEE invokes this method on a resource adaptor object when a service that is interested in events generated by this resource adaptor has transitioned to the Stopping state.

This method may be invoked by the SLEE when the resource adaptor object is in the Inactive, Active, or Stopping state.

The SLEE need only provide a resource adaptor with information about the event types received by the service that the resource adaptor may fire. Generally this is limited to the resource adaptor types implemented by the resource adaptor. However a resource adaptor may be able to fire events of any type if its deployment descriptor has disabled this limitation, and in such cases the SLEE should provide the resource adaptor with information about all the event types that may be received by the service.

This method is invoked with an unspecified transaction context. If the resource adaptor needs the use of a transaction during this method then it should use the SleeTransactionManager to detect the presence or lack of any current transaction and manage that transaction and any that it starts itself appropriately. The resource adaptor must exit from this method with the same transaction context as it was invoked (if any).

Parameters:

serviceInfo - information about the service that is now Stopping and the types of events that SBBs in the service may receive.

serviceInactive

void serviceInactive(ReceivableService serviceInfo)

The SLEE invokes this method on a resource adaptor object when a service that is interested in events generated by this resource adaptor has transitioned from the Stopping state to the Inactive state. The resource adaptor may cease firing resource events that the service was interested in receiving if no other services are registered to receive those events.

This method may be invoked by the SLEE when the resource adaptor object is in the Inactive, Active, or Stopping state.

The SLEE need only provide a resource adaptor with information about the event types received by the service that the resource adaptor may fire. Generally this is limited to the resource adaptor types implemented by the resource adaptor. However a resource adaptor may be able to fire events of any type if its deployment descriptor has disabled this limitation, and in such cases the SLEE should provide the resource adaptor with information about all the event types that may be received by the service.

This method is invoked with an unspecified transaction context. If the resource adaptor needs the use of a transaction during this method then it should use the SleeTransactionManager to detect the presence or lack of any current transaction and manage that transaction and any that it starts itself appropriately. The resource adaptor must exit from this method with the same transaction context as it was invoked (if any).

Parameters:

serviceInfo - information about the service that is now Inactive and the types of events that SBBs in the service may receive.

queryLiveness

void queryLiveness(ActivityHandle handle)

The SLEE invokes this method to ask the resource adaptor to check an activity for liveness. This may occur, for example, if an activity has been idle in the SLEE for a prolonged period of time.

If the resource adaptor considers the activity to still be live, it need do nothing. However if the activity should have already ended, the resource adaptor should end the activity using the SleeEndpoint interface.

If the resource adaptor needs to query an external resource to determine if the activity is still live, it should not unduly block the calling thread while waiting for a response. Asynchronous queries are recommended in this case.

This method is invoked with an unspecified transaction context. If the resource adaptor needs the use of a transaction during this method then it should use the SleeTransactionManager to detect the presence or lack of any current transaction and manage that transaction and any that it starts itself appropriately. The resource adaptor must exit from this method with the same transaction context as it was invoked (if any).

Parameters:

handle - the activity handle corresponding to the activity to check.

getActivity

Object getActivity(ActivityHandle handle)

Get the activity object corresponding to the specified activity handle.

This method is generally invoked with an unspecified transaction context. However if the resource adaptor starts an activity transactionally and the SLEE needs to obtain the activity object for that activity during that transaction, then the resource adaptor can expect, in this case, that the transaction context associated with the calling thread when this method is invoked to be the same as that with which the activity was created, as the state for the activity may not be visible outside the transaction. The resource adaptor may use the SleeTransactionManager to detect the presence or lack of any current transaction and manage that transaction and any that it starts itself appropriately. The resource adaptor must exit from this method with the same transaction context as it was invoked (if any).

Parameters:

handle - the activity handle of the activity.

Returns:

the activity object corresponding to the activity handle.

getActivityHandle

ActivityHandle getActivityHandle(Object activity)

Get the activity handle corresponding to the specified activity object.

The SLEE invokes this method when it needs to construct or lookup an Activity Context for the specified activity. The SLEE uses this method to determine the owner of an activity object. When this method is invoked the resource adaptor object must first verify that the activity object was generated by itself (or by a resource adaptor object of the same resource adaptor entity). If the activity object does indeed belong to the resource adaptor entity, the resource adaptor object must return the activity handle for the activity. If the activity object does not belong to the resource adaptor entity, then the resource adaptor object must return null from this method.

This method is generally invoked with an unspecified transaction context. However if the resource adaptor starts an activity transactionally and the SLEE needs to obtain the activity handle for that activity during that transaction, then the resource adaptor can expect, in this case, that the transaction context associated with the calling thread when this method is invoked to be the same as that with which the activity was created, as the state for the activity may not be visible outside the transaction. The resource adaptor may use the SleeTransactionManager to detect the presence or lack of any current transaction and manage that transaction and any that it starts itself appropriately. The resource adaptor must exit from this method with the same transaction context as it was invoked (if any).

Parameters:

activity - the activity object.

Returns:

an activity handle for the activity object if the activity object was created by this resource adaptor entity, null otherwise. Returning a non-null value from this method is deemed to be claiming ownership of the activity.

administrativeRemove

void administrativeRemove(ActivityHandle handle)

The SLEE invokes this method to inform the resource adaptor that the activity and activity context corresponding to the specified activity handle has been removed from the SLEE due to an administrative action. The resource adaptor is expected to remove any internal state related to the activity. Additionally, the resource adaptor may perform a protocol-level operation to clean up any peer-related state.

This method is invoked with an unspecified transaction context. If the resource adaptor needs the use of a transaction during this method then it should use the SleeTransactionManager to detect the presence or lack of any current transaction and manage that transaction and any that it starts itself appropriately. The resource adaptor must exit from this method with the same transaction context as it was invoked (if any).

Parameters:

handle - the activity handle corresponding to the activity that has been removed from the SLEE.

eventProcessingSuccessful

void eventProcessingSuccessful(ActivityHandle handle,
                             FireableEventType eventType,
                             Object event,
                             Address address,
                             ReceivableService service,
                             int flags)

The SLEE invokes this method on a resource adaptor object to inform it that an event it fired to the SLEE has been processed successfully. This method is only invoked for events fired with the REQUEST_PROCESSING_SUCCESSFUL_CALLBACK event flag set.

This method is invoked with an unspecified transaction context. If the resource adaptor needs the use of a transaction during this method then it should use the SleeTransactionManager to detect the presence or lack of any current transaction and manage that transaction and any that it starts itself appropriately. The resource adaptor must exit from this method with the same transaction context as it was invoked (if any).

Parameters:

handle - the activity handle corresponding to the activity on which the event was fired.

eventType - the event type of the fired event.

event - the event object.

address - the optional default address associated with the event.

service - the optional service the event was fired to.

flags - the flags associated with the outcome of event processing. Currently only the SBB_PROCESSED_EVENT flag is defined by the SLEE specification to be included in this argument.

eventProcessingFailed

void eventProcessingFailed(ActivityHandle handle,
                         FireableEventType eventType,
                         Object event,
                         Address address,
                         ReceivableService service,
                         int flags,
                         FailureReason reason)

The SLEE invokes this method on a resource adaptor object to inform it that an event it fired to the SLEE could not be processed successfully. Event processing failure is characterized by the inability of the SLEE to successfully attempt to deliver the event to all interested SBBs, not by SBB processing failures (for which the SLEE has successfully made an attempt to deliver the event to the failing SBB).

This method is only invoked for events fired with the REQUEST_PROCESSING_FAILED_CALLBACK event flag set.

This method is invoked with an unspecified transaction context. If the resource adaptor needs the use of a transaction during this method then it should use the SleeTransactionManager to detect the presence or lack of any current transaction and manage that transaction and any that it starts itself appropriately. The resource adaptor must exit from this method with the same transaction context as it was invoked (if any).

Parameters:

handle - the activity handle corresponding to the activity on which the event was fired.

eventType - the event type of the fired event.

event - the event object.

address - the optional default address associated with the event.

service - the optional service the event was fired to.

flags - the flags associated with the outcome of event processing. Currently only the SBB_PROCESSED_EVENT flag is defined by the SLEE specification to be included in this argument.

reason - the reason why event processing failed.

eventUnreferenced

void eventUnreferenced(ActivityHandle handle,
                     FireableEventType eventType,
                     Object event,
                     Address address,
                     ReceivableService service,
                     int flags)

The SLEE invokes this method on a resource adaptor object when the event object for an event fired by the resource adaptor is no longer referenced by the SLEE. Once this method has been invoked the resource adaptor can safely reuse the event object if desired.

This method is only invoked for events fired with the REQUEST_EVENT_UNREFERENCED_CALLBACK event flag set.

This method is invoked with an unspecified transaction context. If the resource adaptor needs the use of a transaction during this method then it should use the SleeTransactionManager to detect the presence or lack of any current transaction and manage that transaction and any that it starts itself appropriately. The resource adaptor must exit from this method with the same transaction context as it was invoked (if any).

Parameters:

handle - the activity handle corresponding to the activity on which the event was fired.

eventType - the event type of the fired event.

event - the event object.

address - the optional default address associated with the event.

service - the optional service the event was fired to.

flags - the flags associated with the event. Currently no flags are defined by the SLEE specification to be included in this argument.

activityEnded

void activityEnded(ActivityHandle handle)

The SLEE invokes this method on a resource adaptor object when the SLEE has completed activity end processing for the activity corresponding to the specified activity handle. The resource adaptor is free to release any internal resources held by this activity as the SLEE will not ask for it again.

This method is only invoked for activities started with the REQUEST_ENDED_CALLBACK activity flag.

This method is invoked with an unspecified transaction context. If the resource adaptor needs the use of a transaction during this method then it should use the SleeTransactionManager to detect the presence or lack of any current transaction and manage that transaction and any that it starts itself appropriately. The resource adaptor must exit from this method with the same transaction context as it was invoked (if any).

Parameters:

handle - the activity handle corresponding to the activity that has ended.

activityUnreferenced

void activityUnreferenced(ActivityHandle handle)

The SLEE invokes this method on a resource adaptor object when the Activity Context in the SLEE corresponding to the given activity handle is no longer attached to any SBB entities, is no longer referenced by any SLEE Facilities, and has no events being processed or waiting to be processed on the activity. The resource adaptor can choose to subsequently end the activity if it wishes.

This method is only invoked for activities started with the REQUEST_ACTIVITY_UNREFERENCED_CALLBACK activity flag.

This method is invoked with an unspecified transaction context. If the resource adaptor needs the use of a transaction during this method then it should use the SleeTransactionManager to detect the presence or lack of any current transaction and manage that transaction and any that it starts itself appropriately. The resource adaptor must exit from this method with the same transaction context as it was invoked (if any).

Parameters:

handle - the activity handle corresponding to the activity that has become unreferenced.