javax.slee.connection
Interface SleeConnection


public interface SleeConnection

An application handle to a physical event-delivery connection to a SLEE. This interface is used by EJB components external to a SLEE to communicate with the SLEE's event routing subsystem. A SLEE vendor provides an implementation of this interface if they support external interoperability.

Instances of SleeConnection are created by an EJB application calling SleeConnectionFactory.getConnection()

Implementations may defer validation of arguments and detection of communication errors beyond the return of a method invocation. Clients of this interface should not depend on exceptions being thrown in the face of these errors.

See Also:
SleeConnectionFactory, ExternalActivityHandle

Method Summary
 void close()
          Closes this SleeConnection.
 ExternalActivityHandle createActivityHandle()
          Creates a new external activity handle.
 void fireEvent(java.lang.Object event, EventTypeID eventType, ExternalActivityHandle activityHandle, Address address)
          Fires an event on an external activity.
 EventTypeID getEventTypeID(java.lang.String name, java.lang.String vendor, java.lang.String version)
          Retrieves an EventTypeID that identifies a particular SLEE event.
 

Method Detail

createActivityHandle

public ExternalActivityHandle createActivityHandle()
                                            throws javax.resource.ResourceException
Creates a new external activity handle. The returned handle may be used to fire events to an external SLEE activity. Events fired using a particular external activity handle will be delivered to a single activity within the SLEE, with the exception that the SLEE may end the activity if no SBBs remain attached, and recreate a new activity for a subsequent event fired with the same handle.
Returns:
a new, unique, ExternalActivityHandle object
Throws:
javax.resource.ResourceException - if this connection is closed, or an activity handle could not be allocated due to a system-level failure.

getEventTypeID

public EventTypeID getEventTypeID(java.lang.String name,
                                  java.lang.String vendor,
                                  java.lang.String version)
                           throws UnrecognizedEventException,
                                  javax.resource.ResourceException
Retrieves an EventTypeID that identifies a particular SLEE event. This method does not necessarily validate the existence of the event type in the SLEE.
Parameters:
name - the event's name
vendor - the event's vendor
version - the event's version
Returns:
an EventTypeID object representing the event
Throws:
UnrecognizedEventException - if the SleeConnection determines there is no corresponding event known to the SLEE
javax.resource.ResourceException - if this connection is closed, or the relevant EventTypeID could not be located due to a system-level failure.

fireEvent

public void fireEvent(java.lang.Object event,
                      EventTypeID eventType,
                      ExternalActivityHandle activityHandle,
                      Address address)
               throws java.lang.NullPointerException,
                      UnrecognizedActivityException,
                      UnrecognizedEventException,
                      javax.resource.ResourceException
Fires an event on an external activity. If a transaction is in progress, the event is only delivered to the SLEE activity if the enclosing transaction commits.
Parameters:
event - the event to fire; must be serializable.
eventType - an EventTypeID from getEventTypeID(java.lang.String, java.lang.String, java.lang.String) indicating the SLEE event type of the event being fired.
activityHandle - an ExternalActivityHandle returned by createActivityHandle() indicating the SLEE activity to fire the event on.
address - an optional address to use in event routing; may be null.
Throws:
java.lang.NullPointerException - if event, eventType, or activityHandle are null.
UnrecognizedEventException - if eventType is not a valid SLEE event type
UnrecognizedActivityException - if activityHandle is not a valid external activity handle
javax.resource.ResourceException - if this connection is closed, or the event could not be fired due to a system-level failure.

close

public void close()
           throws javax.resource.ResourceException
Closes this SleeConnection. Any further use of this connection will result in ResourceException being thrown.
Throws:
javax.resource.ResourceException - if this connection is already closed, or could not be closed due to a system-level failure.