com.sonicsw.xq
Interface XQServiceContext

All Superinterfaces:

XQContext, XQInitContext

public interface XQServiceContext
extends XQInitContext

An XQServiceContext provides all the information needed by a service when it is performing its per-message processing. Among other things, this includes an inbox containing any incoming messages to be processed, an outbox containing processed messages to be delivered, and a faultbox containing messages to be delivered to a pre-specified fault destination.

Method Summary

void	addFault(XQEnvelope fault) Adds the specified envelope to the faultbox for delivery by the SonicXQ framework to the pre-specified fault destination.
void	addFault(XQMessage fault) Adds the specified fault to the faultbox for delivery by the SonicXQ framework.
void	addOutgoing(XQEnvelope outgoing) Adds the specified envelope to the outbox for delivery by the SonicXQ framework.
void	addOutgoing(XQMessage outgoing) Adds the specified message to the outbox for delivery by the SonicXQ framework.
void	clearFaults() Clears the faultbox of all envelopes.
void	clearOutgoing() Clears the outbox of all envelopes.
XQAccessorFactory	getAccessorFactory() Returns an XQAccessorFactory appropriate to this context.
javax.jms.Connection	getCurrentJMSConnection() Returns the JMS Connection associated with the current dispatch.
javax.jms.Session	getCurrentJMSSession() Returns the JMS Session associated with the current dispatch.
int	getCurrentListener() gets the id of the listener thread that is executing the service() method.
XQDispatch	getDispatcher() Returns a XQDispatch interface that can be used for service extensions dispatch mechanism.
java.lang.String	getEntryEndpoint() Returns the name of the entry endpoint that dispatched this service.
XQEnvelope	getFirstIncoming() Returns the first envelope in the inbox.
XQInvocationContext	getInvocationContext() Returns an Invocation Context object associated with this service invocation.
XQMitigationContext	getMitigationContext() Returns a mitigation context for accessing information about current host conditions.
XQEnvelope	getNextIncoming() Returns the next envelope in the inbox.
XQProcessContext	getProcessContext() Returns the current process context.
XQAddress	getProcessContinuationAddress(XQProcessContinuation continuation) Return a new XQAddress that will continue the process based on the information contained in the continuation object.
XQQualityofService	getQoS() Returns the operating QoS level of this service.
XQAddress	getRMEAddress() Returns the XQAddress of the RME of the service.
boolean	hasNextIncoming() Determines whether or not there are any additional envelopes to be read from the inbox.

Methods inherited from interface com.sonicsw.xq.XQInitContext

getEndpointManager, getInteractorFactory, getLifeCycle

Methods inherited from interface com.sonicsw.xq.XQContext

getAddressFactory, getEnvelopeFactory, getLog, getMessageFactory, getParameters

Method Detail

hasNextIncoming

boolean hasNextIncoming()

Determines whether or not there are any additional envelopes to be read from the inbox. More specifically, this returns true if getNextIncoming() will return non-null.

getNextIncoming

XQEnvelope getNextIncoming()

Returns the next envelope in the inbox.

Returns:

the next XQEnvelope in the inbox

getFirstIncoming

XQEnvelope getFirstIncoming()

Returns the first envelope in the inbox. Note: this does not reset the iteration for hasNextIncoming()/getNextIncoming().

Returns:

the first XQEnvelope in the inbox

addOutgoing

void addOutgoing(XQEnvelope outgoing)

Adds the specified envelope to the outbox for delivery by the SonicXQ framework.

Parameters:

outgoing - an XQEnvelope to add to the outbox

addOutgoing

void addOutgoing(XQMessage outgoing)

Adds the specified message to the outbox for delivery by the SonicXQ framework. The XQMessage will be wrapped in an XQEnvelope created by the EnvelopeFactory

Parameters:

outgoing - an XQMessage to add to the outbox

clearOutgoing

void clearOutgoing()

Clears the outbox of all envelopes.

addFault

void addFault(XQEnvelope fault)

Adds the specified envelope to the faultbox for delivery by the SonicXQ framework to the pre-specified fault destination.

Parameters:

fault - an XQEnvelope to add to the faultbox

addFault

void addFault(XQMessage fault)

Adds the specified fault to the faultbox for delivery by the SonicXQ framework. The fault XQMessage will be wrapped in an XQEnvelope created by the EnvelopeFactory

Parameters:

fault - an XQMessage to add to the faultbox

clearFaults

void clearFaults()

Clears the faultbox of all envelopes.

getAccessorFactory

XQAccessorFactory getAccessorFactory()

Returns an XQAccessorFactory appropriate to this context.

Returns:

an XQEnvelopeFactory

getCurrentListener

int getCurrentListener()

gets the id of the listener thread that is executing the service() method. This should be used to tune listener thread utilization for a particular service.

Returns:

a number between 1 and the number of listeners configured for this service

getEntryEndpoint

java.lang.String getEntryEndpoint()

Returns the name of the entry endpoint that dispatched this service. Note that this will not be the actual entry endpoint if this service is invoked as part of a process.

Returns:

the service's entry endpoint name

getQoS

XQQualityofService getQoS()

Returns the operating QoS level of this service.

Returns:

the QoS level - see XQConstants for additional info

getRMEAddress

XQAddress getRMEAddress()

Returns the XQAddress of the RME of the service. Note that this may be overridden if this service is invoked as part of a process.

Returns:

XQAddress of the service's RME address

getProcessContext

XQProcessContext getProcessContext()

Returns the current process context.

Returns:

current process context or null if not in process

getCurrentJMSSession

javax.jms.Session getCurrentJMSSession()

Returns the JMS Session associated with the current dispatch. If this service is invoked as part of a process, this may not be the JMS Session associated with one of this service's endpoint

The JMS Session may be used send using the JMS API directly. If the endpoint being dispatched to has an ExactlyOnce operating QoS, the JMS Session is transacted. Session.getTransacted() can be called to check if a JMS Session is transacted. JMS messages sent using this JMS Session will be included within the same transaction as the message that triggered the dispatch.

The JMS Session can be cast to progress.message.jclient.Session. This Sonic extension to javax.jms.Session provides access to Sonic JMS extensions for creating MultipartMessage and XMLMessage objects.

Note that the JMS Session object depends on the current listener thread that is executing the service() method, and, therefore, if there are multiple listener threads, may vary from call to call. The JMS Session object will also change if the ESB Container needs to reconnect to the JMS broker because of network or JMS broker failure. Fault-tolerant connections can help reduce this possibility.

If the ESB Service attempts to call any of the following Session methods java.lang.UnsupportedOperationException will be thrown.

• Session.close()
• Session.rollback()
• Session.recover()
• Session.run()
• Session.createBrowser(javax.jms.Queue)
• Session.createBrowser(javax.jms.Queue, java.lang.String)
• Session.createConsumer(javax.jms.Destination)
• Session.createConsumer(javax.jms.Destination, java.lang.String)
• Session.createConsumer(javax.jms.Destination, java.lang.String, boolean)
• Session.createDurableSubscriber(javax.jms.Topic, java.lang.String)
• Session.createDurableSubscriber(javax.jms.Topic, java.lang.String,java.lang.String,boolean)
• Session.unsubscribe(java.lang.String)

Returns:

current JMS Session or null if not available

getCurrentJMSConnection

javax.jms.Connection getCurrentJMSConnection()

Returns the JMS Connection associated with the current dispatch. If this service is invoked as part of a process, this may not be the JMS Connection associated with this service's endpoint

Note that JMS Connection object will change if the ESB Container is required to reconnect to the JMS broker because of network or JMS broker failure. Fault-tolerant connections can help reduce this possibility.

If the ESB Service attempts to call the following Connection methods java.lang.UnsupportedOperationException will be thrown.

• Connection.close()
• Connection.stop()

ESB Service code may call setExceptionListener. Since the underlying JMS Connection can be accessed and shared by multiple ESB Services, registration of multiple listeners is supported by the underlying implementation. The setExceptionListener method may therefore be called multiple times with different ExceptionListener objects. Each individual ExceptionListener object may have its onException method fired at most once. Programmers are advised to avoid setting ExceptionListeners, or, to use with care. No means is provided to unset an ExceptionListener once registered through this call. If you wish to accomplish this flag your ExceptionListener logic as disabled. <

Returns:

current JMS Connection or null if not available

getDispatcher

XQDispatch getDispatcher()

Returns a XQDispatch interface that can be used for service extensions dispatch mechanism.

Specified by:

getDispatcher in interface XQInitContext

Returns:

an XQDispatch

getMitigationContext

XQMitigationContext getMitigationContext()

Returns a mitigation context for accessing information about current host conditions.

getInvocationContext

XQInvocationContext getInvocationContext()

Returns an Invocation Context object associated with this service invocation. If the message mapping feature is not used or if the message mapping feature does not map to/from interface parameters then this method will return null.

getProcessContinuationAddress

XQAddress getProcessContinuationAddress(XQProcessContinuation continuation)

Return a new XQAddress that will continue the process based on the information contained in the continuation object. The service performing the reactivation of the passivated process will use this method.

Parameters:

continuation - The continuation object to be used for reactivation

Returns:

XQAddress to continue the process

Throws:

java.lang.Exception

See Also:

XQProcessContinuation