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 handle, 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

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

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

void fireEvent(java.lang.Object event,
               EventTypeID eventType,
               ExternalActivityHandle handle,
               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.

handle - 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

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.