javax.slee.resource.ResourceAdaptor Maven / Gradle / Ivy
package javax.slee.resource;
import javax.slee.Address;
/**
* 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
*/
public interface ResourceAdaptor {
/**
* 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
* {@link javax.slee.transaction.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).
* @param context the ResourceAdaptorContext object given to the resource
* adaptor object by the SLEE.
*/
public void setResourceAdaptorContext(ResourceAdaptorContext context);
/**
* 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 {@link #setResourceAdaptorContext 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
* {@link javax.slee.transaction.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).
*/
public void unsetResourceAdaptorContext();
/**
* 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
* {@link javax.slee.transaction.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).
* @param properties the configuration properties specified for the resource adaptor
* entity.
*/
public void raConfigure(ConfigProperties properties);
/**
* 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
* {@link #raConfigure 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
* {@link javax.slee.transaction.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).
*/
public void raUnconfigure();
/**
* 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:
*
* - The SLEE is in the Running state.
*
- 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
* {@link javax.slee.transaction.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).
*/
public void raActive();
/**
* 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:
*
* - The SLEE transitions to the Stopping state.
*
- 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
* {@link javax.slee.transaction.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).
*/
public void raStopping();
/**
* 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 {@link #raActive 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
* {@link javax.slee.transaction.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).
*/
public void raInactive();
/**
* 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
* {@link javax.slee.transaction.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).
* @param 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.
*/
public void raVerifyConfiguration(ConfigProperties properties)
throws InvalidConfigurationException;
/**
* 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
* {@link javax.slee.transaction.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).
* @param properties contains the new values for all configuration properties specified
* for the resource adaptor entity.
*/
public void raConfigurationUpdate(ConfigProperties properties);
/**
* 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.
* @param className the fully-qualified class name of the resource adaptor interface,
* as specified by the resource adaptor type, required by the SLEE.
* @return an object that implements (and is therefore type-castable to) the specified
* resource adaptor interface.
*/
public Object getResourceAdaptorInterface(String className);
/**
* Get the activity handle and event marshaler for the resource adaptor.
*
* This method is invoked with an unspecified transaction context.
* @return the activity handle and event marshaler.
*/
public Marshaler getMarshaler();
/**
* 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
* {@link javax.slee.transaction.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).
* @param serviceInfo information about the service that is now Active and the types
* of events that SBBs in the service may receive.
*/
public 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
* 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
* {@link javax.slee.transaction.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).
* @param serviceInfo information about the service that is now Stopping and the types
* of events that SBBs in the service may receive.
*/
public 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 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
* {@link javax.slee.transaction.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).
* @param serviceInfo information about the service that is now Inactive and the types
* of events that SBBs in the service may receive.
*/
public void serviceInactive(ReceivableService serviceInfo);
/**
* 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 {@link 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
* {@link javax.slee.transaction.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).
* @param handle the activity handle corresponding to the activity to check.
*/
public void queryLiveness(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
* {@link javax.slee.transaction.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).
* @param handle the activity handle of the activity.
* @return the activity object corresponding to the activity handle.
*/
public Object getActivity(ActivityHandle handle);
/**
* 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
* {@link javax.slee.transaction.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).
* @param activity the activity object.
* @return 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.
*/
public ActivityHandle getActivityHandle(Object activity);
/**
* 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
* {@link javax.slee.transaction.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).
* @param handle the activity handle corresponding to the activity that has been
* removed from the SLEE.
*/
public void administrativeRemove(ActivityHandle handle);
/**
* 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
* {@link EventFlags#REQUEST_PROCESSING_SUCCESSFUL_CALLBACK 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
* {@link javax.slee.transaction.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).
* @param handle the activity handle corresponding to the activity on which the
* event was fired.
* @param eventType the event type of the fired event.
* @param event the event object.
* @param address the optional default address associated with the event.
* @param service the optional service the event was fired to.
* @param flags the flags associated with the outcome of event processing. Currently
* only the {@link EventFlags#SBB_PROCESSED_EVENT SBB_PROCESSED_EVENT} flag is
* defined by the SLEE specification to be included in this argument.
*/
public 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 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
* {@link EventFlags#REQUEST_PROCESSING_FAILED_CALLBACK 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
* {@link javax.slee.transaction.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).
* @param handle the activity handle corresponding to the activity on which the
* event was fired.
* @param eventType the event type of the fired event.
* @param event the event object.
* @param address the optional default address associated with the event.
* @param service the optional service the event was fired to.
* @param flags the flags associated with the outcome of event processing. Currently
* only the {@link EventFlags#SBB_PROCESSED_EVENT SBB_PROCESSED_EVENT} flag is
* defined by the SLEE specification to be included in this argument.
* @param reason the reason why event processing failed.
*/
public 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 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
* {@link EventFlags#REQUEST_EVENT_UNREFERENCED_CALLBACK 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
* {@link javax.slee.transaction.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).
* @param handle the activity handle corresponding to the activity on which the
* event was fired.
* @param eventType the event type of the fired event.
* @param event the event object.
* @param address the optional default address associated with the event.
* @param service the optional service the event was fired to.
* @param flags the flags associated with the event. Currently no flags are defined
* by the SLEE specification to be included in this argument.
*/
public 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 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
* {@link ActivityFlags#REQUEST_ENDED_CALLBACK 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
* {@link javax.slee.transaction.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).
* @param handle the activity handle corresponding to the activity that has ended.
*/
public void activityEnded(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
* {@link ActivityFlags#REQUEST_ACTIVITY_UNREFERENCED_CALLBACK 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
* {@link javax.slee.transaction.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).
* @param handle the activity handle corresponding to the activity that has become
* unreferenced.
*/
public void activityUnreferenced(ActivityHandle handle);
}