Access Keys:
Skip to content (Access Key - 0)









SLEE 1.1 Resource Adaptors

Print this page

Introduction

This document contains a brief introduction to Resource Adaptors in Rhino 2.0. The intention here is not to provide a complete Resource Adaptor tutorial, but to highlight important features of the new Resource Adaptor API. More complete information on the Resource Adaptor API is available in the SLEE 1.1 specification. Developers who have Rhino 1.x.x Resource Adaptors may want to refer to the migration tips in the later part of the document for updating their Resource Adaptors to the SLEE 1.1 specification.

The major areas of interest covered here are:

  • Resource Adaptor Lifecycle methods
  • ResourceAdaptorContext & SLEE facilities
  • Logging
  • Activity Management & Event Firing
  • Transaction management
  • Event, Activity and Service callbacks
  • Alarm management
  • Query liveness
  • Administrative removal of activities
  • Usage parameter sets

Each of these areas is discussed briefly in the following sections.

Resource Adaptor overview

A Resource Adaptor is a SLEE component which is used for communicating between the SLEE and an external resource. For example, a simple Resource Adaptor might bind to a network socket and translate incoming network messages into Events which are then delivered to the SLEE. These Events would then drive logic in a Service, which could then send messages back to the network via the Resource Adaptor.

The following terminology may be useful while reading this document:

  • A Resource Adaptor Entity is an instantiation of a Resource Adaptor implementation (i.e. an Entity created via a management command). Multiple Resource Adaptor Entities may be created from the same Resource Adaptor implementation.
  • A Resource Adaptor Object is a Java object created from a Resource Adaptor implementation for the purpose of executing Resource Adaptor logic. There is at most one configured Resource Adaptor Object per Resource Adaptor Entity in a JVM, though each Resource Adaptor Entity may have additional unconfigured Resource Adaptor Objects associated with it for the purpose of configuration verification.

Refer to the SLEE 1.1 specification for complete definitions of these two concepts.

Lifecycle Methods

The RA lifecycle methods are used to manage the configuration, unconfiguration, and state transitions of a Resource Adaptor Entity. They are called by the SLEE, usually in response to management operations of SLEE state changes. The expected ordering of lifecycle method calls (i.e. legal state transitions) is specified in the SLEE 1.1 specification.

The following table provides a brief overview of the lifecycle methods available:

Method Description
raConfigure(ConfigProperties properties) Called on a Resource Adaptor Object when a Resource Adaptor Entity is created.
raActive() Called in response to an RA Entity being started. This callback should be used for resource allocation (e.g. binding network sockets).
raStopping() Called in response to an RA Entity being stopped. After this is called the RA is in the 'stopping' state and will be unable to create new activities.
raInactive() Called when an RA Entity finishes stopping (i.e. no activities remain associated with this RA Entity). The RA should release any resources it has allocated (e.g. unbind from network sockets) before returning from this method.
raUnconfigure() Called when the RA Entity has been removed.
raConfigurationUpdate(ConfigProperties properties) Called in response to a management operation which updates an RAs configuration properties (assuming this RA has specified support for active reconfiguration in its Deployment Descriptor).
raVerifyConfiguration(ConfigProperties properties) Called before the raConfigure and raConfigurationUpdate methods to verify that the supplied properties are valid for the Resource Adaptor. The implementation of this method should not rely on any internal RA state, as it may be called on a Resource Adaptor Object which has been created specifically for the invocation of this method.
setResourceAdaptorContext(ResourceAdaptorContext context) Called after an RA Object is created. This callback should only be used for looking up SLEE facilities and similar.
unsetResourceAdaptorContext() Called when an RA Object is being cleaned up. This is the last method the SLEE will call on an RA Object.

ResourceAdaptorContext & SLEE Facilities

The ResourceAdaptorContext provides the primary means for a Resource Adaptor to interact with SLEE facilities. It is provided to a Resource Adaptor Object as an argument to the setResourceAdaptorContext method, after the RA Object is instantiated. It is likewise unset by the unsetResourceAdaptorContext method if the SLEE ever needs to clean up the RA Object.

It should be noted that not all of the facilities provided by the ResourceAdaptorContext can be usefully used by an RA immediately after becoming available through setResourceAdaptorContext. For example, at the time that setResourceAdaptorContext is called, the RA will not be in a state where it can be used to send events via the SleeEndpoint. The facilities can still be looked up for later use though, as in the following example:

public void setResourceAdaptorContext(ResourceAdaptorContext context) {
  this.context = context;
  this.endpoint = context.getSleeEndpoint();    // Used for managing activities and events
}

public void unsetResourceAdaptorContext() {
  this.endpoint = null;
  this.context = null;
}

private ResourceAdaptorContext context;
private SleeEndpoint endpoint;

The table below highlights some of the methods on the ResourceAdaptorContext:

Method Description
getSleeEndpoint() Returns a SleeEndpoint which can be used to fire Events, and start and end Activities.
getEventLookupFacility() Returns a facility which can be used to lookup ID objects (FireableEventType) for the events this RA handles. FireableEventTypes are required when firing events).
getServiceLookupFacility() Returns a facility which can be used to lookup ID objects (ReceivableService) for the services this RA is interested in for service lifecycle callbacks.
getTracer(String tracerName) Returns a Tracer which can be used to log messages generated by the RA.
getAlarmFacility() Returns a facility which can be used to raise and clear Alarms.
getSleeTransactionManager() Returns the SLEE transaction manager, used for starting SLEE transactions.
getTimer() Returns a generic java.util.Timer for use by the RA.
getProfileTable(String profileTableName) Returns a profile table.
getUsageParamaterSet(string paramSetName) Returns a named usage parameter set.
getInvokingService() Returns the ServiceID of the service currently associated with the current RA call. This can be used in an RA's SBB interface implementation to determine which service is invoking a method.

EventLookupFacility

The event lookup facility is used to look up the FireableEventType objects that the SleeEndpoint uses when firing events. These objects are managed internally by the SLEE, but it can be assumed that they will not change during the lifetime of an RA Entity. A basic example of using the EventLookupFacility follows:

public void raConfigure(ConfigProperties properties) {
  tracer = getTracer("my.resource.adaptor"); // Used for logging

  EventLookupFacility eventLookupFacility = context.getEventLookupFacility();
  EventTypeID eventTypeID = new EventTypeID("EventName", "EventVendor", "EventVersion");

  try {
    myFireableType = eventLookupFacility.getFireableEventType(eventTypeID);
  } catch ( UnrecognizedEventException uree ) {
    tracer.severe("Could not lookup event type for event: " + eventTypeID, uree);
  }
}

private FireableEventType myFireableType;
private Tracer tracer;

ServiceLookupFacility

The service lookup facility is used to look up the ReceivableService objects used by the service lifecycle callbacks. These objects are managed internally by the SLEE, but it can be assumed that they will not change during the lifetime of an RA Entity. A basic example of using the ServiceLookupFacility follows:

public void raConfigure(ConfigProperties properties) {
  tracer = getTracer("my.resource.adaptor"); // Used for logging

  ServiceLookupFacility serviceLookupFacility = context.getServiceLookupFacility();
  ServiceID myServiceID = new ServiceID("ServiceName", "ServiceVendor", "ServiceVersion");

  try {
     myServiceType = serviceLookupFacility.getReceivableService(myServiceID);
  } catch ( UnrecognizedServiceException use ) {
    tracer.severe("Could not lookup receivable service type for service: " + myServiceID, use);
  }
}

public void serviceActive(ReceivableService serviceInfo) {
  if (serviceInfo.equals(myServiceType)) {
    // The service activated is a service this RA is interested in, 
    // so we could do something useful here (such as start firing 
    // the event types which the service is interested in).
    ... ;
  }
}

private ReceivableService myServiceType;
private Tracer tracer;

Logging

Logging for a RA should be done through a Tracer retrieved from the ResourceAdaptorContext. Third party logging libraries should not be used in general, as they will decrease the portability of a Resource Adaptor.

The following example briefly shows Tracer use:

public void setResourceAdaptorContext(ResourceAdaptorContext context) {
   this.context = context;
}

public void raConfigure(ConfigProperties properties) {
   tracer = context.getTracer("my.tracer." + context.getEntityName());
   tracer.info("Resource Adaptor Entity configured.");
}

private Tracer tracer;
private ResourceAdaptorContext context;

Activity Management & Event Firing

The SleeEndpoint is responsible for starting and ending activities, and firing events from the Resource Adaptor on those activities. A Resource Adaptor Entity may create activities and fire events while it is active (after raActive has been called by the SLEE), and may end activities (and submit events on existing activities) while the RA Entity is stopping (after raStopping has been called, but before raInactive).

The relevant methods on the SleeEndpoint are:

  • startActivity - Used for activity creation.
  • endActivity - Used to end an existing activity.
  • fireEvent - Used to fire events on an existing activity.

Many of the method arguments can optionally be used to target events more specifically (such as the ServiceID argument). The variants which have the callback flags (ActivityFlags and EventFlags arguments) can be used to request that activity or event processing status information is sent back to the Resource Adaptor. More information on these callbacks is available in a later section. The transacted variants of these methods (startActivityTransaction, endActivityTransacted, fireEventTransacted) can be used to associate the activity or event with the transaction associated with the current thread.

The SLEE makes a distinction between an ActivityHandle and the Activity Object itself, as in many cases it is unnecessarily cumbersome to pass around the Activity Object when it may not be needed. As such, it is necessary for a Resource Adaptor to define the following methods to allow the SLEE to convert between an Activity Object and an ActivityHandle:

Method Description
public Object getActivity(ActivityHandle handle) Returns the Activity Object associated with a particular handle.
public ActivityHandle getActivityHandle(Object activity) Returns the ActivityHandle for an Activity Object.

Transaction management

The SleeTransactionManager can be used to manage SLEE transactions.

The following example demonstrates how to atomically deliver two events on a new activity by using a transaction created by the SLEETranscationManager. In this example, eventAType and eventBType are FireableEventType objects which have previously obtained from the EventLookupFacility. The example is also simplified and ignores error handling.

ActivityHandle handle = new ActivityHandleImpl(); // Unique activity handle.

SleeTransactionManager transactionManager = context.getSleeTransactionManager();
transactionManager.beginSleeTransaction();

endpoint.startActivityTrascated(handle);
endpoint.fireEventTransacted(handle, eventAType, new EventAImpl(), null, null);
endpoint.fireEventTransacted(handle, eventBType, new EventBImpl(), null, null);
endpoint.endActivityTransacted(handle);

transactionManager.commit();

The transaction manager can be used for far more advanced behavior than this simple example, but that lies outside the scope of this document. Please refer to the SLEE 1.1 specification for further information on advanced transaction functionality.

Event, Activity, and Service callbacks

The Resource Adaptor API provides a number of callback methods which are invoked by the SLEE in response to service state changes, event processing completion, and activity state changes. Implementing these callback methods is entirely optional.

Event processing callbacks

The event processing callbacks are called by the SLEE when event processing for an event has finished. For these callbacks to be invoked, appropriate flags must be passed to the fireEvent method when the event is fired.

The event processing callback methods are:

  • eventProcessingSuccessful - Called when an event has been successfully delivered.
  • eventProcessingFailed - Called when a problem occurred in the SLEE during event delivery. This may be called in situations where the SLEE could not deliver the Event due to lack of resources, a system level failure, or other similar scenarios.
  • eventUnreferenced - Called when the SLEE has finished with an Event object. This is mainly for use in RAs which store references to pooled resources in their Events, and need to know when those shared resources can safely be reused elsewhere.

The following example shows a trivial use of the event processing callbacks:

private void fireMyEvent(ActivityHandle handle, FireableEventType eventType, Object event) {
    int flags = EventFlags.REQUEST_PROCESSING_SUCCESSFUL_CALLBACK | EventFlags.REQUEST_PROCESSING_FAILED_CALLBACK;
    endpoint.fireEvent(handle, eventType, event, null, null, flags)
}

public void eventProcessingSuccessful(ActivityHandle handle, FireableEventType eventType,
                      Object event, Address address, ReceivableService service,
                      int flags) {
    tracer.info("Event processing succesful for event=" + event + ", handle=" + handle);
}

public void eventProcessingFailed(ActivityHandle handle, FireableEventType eventType,
                      Object event, Address address, ReceivableService service,
                      int flags, FailureReason reason) {
    tracer.info("Event processing failed for event=" + event + ", handle=" + handle);
}

Activity callbacks

The activity callbacks behave much the same way as the event processing callbacks. They are invoked by the SLEE when an activity ends, assuming that the activity was started with the appropriate callback flags.

The activity callback methods are:

  • activityEnded - Called when the activity ends.
  • activityUnreferenced - Called when the activity is no longer referenced in the SLEE.

Service state callbacks

These callbacks inform the Resource Adaptor that a service has changed state. Their intended use is to allow a Resource Adaptor to internally filter the events it is firing into the SLEE to prevent unnecessary event processing logic from taking place.

The service state callback methods are:

  • serviceActive - Called when a service has been activated.
  • serviceStopping -Called when a service begins stopping.
  • serviceInactive - Called when a service has finished stopping.

Alarm management

The AlarmFacility can be used to raise and clear alarms from a Resource Adaptor. It should be used for important events such as loss of connection to an external resource to inform a SLEE administrator that there is a problem. e.g.

// called when the RA detects connection loss
private void onConnectionLoss() {
  connectionAlarm = context.getAlarmFacility().raiseAlarm("ConnLoss", "0", AlarmLevel.CRITICAL, "Connection to external resource lost.");
}

// called when the external connection is restored
private void onConnectionReconnect() {
  context.getAlarmFacility().clearAlarm(connectionAlarm);
}

private String connectionAlarm = null;

Query liveness

The queryLiveness method is invoked by the SLEE when it wants to check whether a Resource Adaptor still considers an Activity to be live. It is intended for cleaning up long running Activities which may no longer be active in the Resource Adaptor.

When this method is called, the Resource Adaptor should perform whatever logic is required to determine whether the specified Activity is still active (such as talking to an embedded protocol stack, querying a network resource, or simply looking at an internal list of active Activities). If the RA determines that the Activity is no longer active, it should end it by calling the endActivity method on the SleeEndpoint.

As an example, a Resource Adaptor might clear its internal record of activity state upon losing connection to an external resource. Instead of ending all of the Activities it is responsible for then and there, it might opt to wait for queryLiveness callbacks from the SLEE before removing each old activity. In this way, the Resource Adaptor could avoid queuing a large number of activity end events at the same time, resulting in a more even load on the SLEE.

Administrative removal of activities

The administrativeRemove method is called by the SLEE in response to a management command (e.g. an administrator manually removing a long running activity). The implementation of this method should be used to clean up any internal RA state related to the activity and perform actions such as informing a remote protocol stack that the associated dialog has been closed. The activity will have already been removed from the SLEE when this method is invoked, so only internal RA state needs to be cleaned up in this method.

Usage parameter sets

Usage parameter sets can be used to record counter or sample type data which can later be retrieved from the SLEE via management commands. Usage parameter sets are supported by Resource Adaptors through the getUsageParametersSet and getDefaultUsageParameterSet methods on the ResourceAdaptorContext, though the parameters themselves must be specified in the Resource Adaptor deployment descriptor before these methods are useful. See the SLEE specification for further information regarding Usage Parameters.

Updating Rhino 1.x.x Resource Adaptors to SLEE 1.1

This section of the document contains quick notes for developers who have created their own Rhino 1.x.x Resource Adaptors which need updating to SLEE 1.1. This section will be of limited interest to others.

Deployment descriptor

The deployment descriptor for Resource Adaptors has changed. In general, the configuration and security blocks from oc-resource-adaptor.xml can be copied into a SLEE 1.1 RA deployment descriptor.

Lifecycle methods

The lifecycle methods used in Rhino 1.x.x Resource Adaptors have been replaced with new standardised lifecycle methods in SLEE 1.1. In most cases, the 1.x.x start and stop methods can be changed to raConfigure and raUnconfigure, and the endpointActivated, and endpointDeactivated methods can be changed to raActive and raInactive.

ResourceAdaptorContext

Each Resource Adaptor must now define a setResourceAdaptorContext(ResourceAdaptorContext context) method. This is called when the RA Object (not Entity) is first created. The SLEE may keep a number of RA Objects available for a Resource Adaptor, so resource allocation (e.g. socket bindings) should not be done in the setResourceAdaptorConext method, but in raActive instead.

The ResourceAdaptorContext performs the same function as the BootstrapContext argument to the Rhino 1.x.x start method and allows access to SLEE facilities.

Activities and Events

Activities are now started using the startActivity and endActivity methods on SleeEndpoint, instead of by passing flags to enqueueEvent (which no longer exists). This means that code like the following:

endpoint.fireEvent( ... , SleeEndpoint.START_ACTIVITY | SleeEndpoint.END_ACTIVITY);

becomes:

endpoint.startActivity( ... );
endpoint.fireEvent( ... );
endpoint.endActivity( ...);

It should also be noted that the new RA lifecycle methods govern when activities can be started and ended. Activities can only be started after raActive and before raStopping has been called on an RA Entity.

The enqueueEvent method has been changed into fireEvent, and no longer has an argument determining whether the event starts or ends an Activity. The new fireEvent method also has additional (optional) parameters.

Event, Activity, and Service callbacks

Event callbacks

Any Event processing callbacks from Rhino 1.x.x will not be invoked in SLEE 1.1 unless the event is fired with the new callback flags argument. To replicate the Rhino 1.x.x behaviour, the following event flags need to be passed when firing an event:

int flags = EventFlags.REQUEST_PROCESSING_SUCCESSFUL_CALLBACK | EventFlags.REQUEST_PROCESSING_FAILED_CALLBACK;

The Event processing callbacks themselves have not changed, but a new eventUnreferenced callback has been added. This requires the EventFlags.REQUEST_EVENT_UNREFERENCED_CALLBACK flag to be passed during event firing before it will be invoked.

Activity callbacks

The Activity end callback has not changed, but much like with event callbacks this method will only be invoked if it was requested when the Activity was started (i.e. the ActivityFlags.REQUEST_ENDED_CALLBACK flag). An activityUnreferenced callback was also added, requiring the ActivityFlags.REQUEST_ACTIVITY_UNREFERENCED_CALLBACK before it will be invoked.

Service state callbacks

Service processing callbacks have changed slightly, as shown in the following table:

Rhino 1.x.x method SLEE 1.1 method(s)
serviceInstalled none
serviceUninstalled none
serviceActivated serviceActive
serviceDeactivated serviceStopping
serviceInactive

These methods have also been improved to each provide an integer array of Event IDs which can be used for convenient Event filtering in a Resource Adaptor.

Alarm facility

The AlarmFacility (accessible from the ResourceAdaptorContext) has been updated with new methods for raising and clearing Alarms. These new methods should be used in preference to the deprecated 1.0 methods.

Adaptavist Theme Builder Powered by Atlassian Confluence