oracle.integration.platform.blocks.event.jms2

Class EdnJmsConnection

java.lang.Object

oracle.integration.platform.blocks.event.jms2.BaseEdnConnection

oracle.integration.platform.blocks.event.jms2.EdnJmsConnection

All Implemented Interfaces:

BusinessEventConnection, EdnConnection

public final class EdnJmsConnection
extends BaseEdnConnection

Remote EDN connection where events can be published and subscribed. The implementation of this class is based on plain JMS API, and is typically used by J2SE client.

Since:

12.1.2

Field Summary

Fields

Modifier and Type	Field and Description
static String	JNDI_DEFAULT_AQJMS_LOCALTX_CONN_FACTORY
static String	JNDI_DEFAULT_AQJMS_XA_CONN_FACTORY
static String	JNDI_DEFAULT_WLJMS_LOCALTX_CONN_FACTORY
static String	JNDI_DEFAULT_WLJMS_XA_CONN_FACTORY

Constructor Summary

Constructors

Constructor and Description
EdnJmsConnection(Context ctx) Construct a remote JMS Connection to EDN.

Method Summary

Modifier and Type	Method and Description
void	close() close the EDN connection: clean up internal states - wipe out current JMS topic connection factory, close all cached JMS topic connections, JTA user transaction reference, reset subscriber message consuming state flags throws IllegalStateException if the long running event receiver thread is not shutdown
void	forceClose() close the EDN connection: (1) request event receiver thread shutdown; (2) clean up internal states - wipe out current JMS topic connection factory, close all cached JMS topic connections, JTA user transaction reference, reset subscriber message consuming state flags
String	getClientID() Get client ID used for creating durable subscriptions.
javax.jms.TopicConnectionFactory	getTopicConnectionFactory() Get non-XA TopicConnectionFactory instance.
UserTransaction	getUserTransaction() Get UserTranasction instance for XA.
javax.jms.TopicConnectionFactory	getXaTopicConnectionFactory() Get XA TopicConnectionFactory instance.
boolean	isReceiving() check if the receiver is receiving events.
void	publishEvent(BusinessEvent event) Publish an event with default persistent, priority, time to live, and EDL as input source.
void	publishEvent(BusinessEvent event, boolean persistent, int priority, long timeToLive, String edlURI) Publish an event with specified delivery mode, priority, time to live, and EDL URI.
void	publishEvent(BusinessEvent event, int priority) Publish an event with indicated priority
void	setClientID(String clientID) Set client ID used for creating durable subscriptions.
void	setJmsConfig(JmsConfig config) Custom JmsConfig for all the events to be published and subscribed via this Event Connection.
void	setTopicConnectionFactory(javax.jms.TopicConnectionFactory topicConnectionFactory) Set a non-XA TopicConnectionFactory instance.
void	setUserTransaction(UserTransaction userTransaction) Set UserTranasction instance for XA.
void	setXaTopicConnectionFactory(javax.jms.TopicConnectionFactory xaTopicConnectionFactory) Set a XA TopicConnectionFactory instance.
void	stopReceiving() request that receiver stop receiving events (exit the while loop - next time it checked the flag: stopReceivingRequested)
EdnJmsEventReader	subscribe(QName eventName, ConsistencyLevel qos, XPathFilter filter, boolean runAsPublisher, long timeout, String durableSubName) create subscriber (durable / non-durable) and return an associated POJO (EdnJmsEventReader) to the caller, EdnJmsEventReader provides caller with fine grained event consuming (start/stop message delivery, read one event etc.)
void	subscribe(QName eventName, ConsistencyLevel qos, XPathFilter filter, BusinessEventHandler handler, boolean runAsPublisher, long timeout, String durableSubName) Subscribe to EDN JMS topic (fetched from server through jndi lookup::EDNConfig) for EDN event (indicated by eventName), if durableSubName presents, a durable subscriber is created with durableSubName as subscriber name, the jms durable subscriber client ID is using the value from EdnJmsConnection class level clientID;
void	subscribe(QName eventName, String durableSubscriptionName) Subscribe to EDN JMS topic (fetched from server through jndi lookup::EDNConfig) for EDN event (indicated by eventName), if durableSubscriptionName presents, a durable subscriber is created with durableSubscriptionName as subscriber name EDN consistency level : default to class instance consistency level EDN event filter: default to class instance event filter EDN event handler: default to class instance event handler EDN run as publisher: default to class instance value of run as publisher EDN event receiving (read) timeout (in millis) : default to class instance timeout value
EdnJmsEventReader	subscribeOnly(QName eventName, String durableSubscriptionName) create subscriber only, return a EdnJmsEventReader instance where the caller can do fine grained message receiving (start/stop message delivery on the underlying JMS topic connection, read event from the underlying JMS subscriber, etc.) EDN consistency level : default to class instance consistency level EDN event filter: default to class instance event filter EDN event handler: default to class instance event handler EDN run as publisher: default to class instance value of run as publisher EDN event receiving (read) timeout (in millis) : default to class instance timeout value
void	unsubscribe(QName eventName, String durableSubName) Remove a durable subscription that has been created previously.
void	waitOnReceiver() alternative for client sync with event receiving thread (long running)
void	waitOnReceiver(long millis) alternative for client sync with event receiving thread (long running)
void	waitSubscriberCreationComplete() block on the latch until latch zero'd
boolean	waitSubscriberCreationComplete(long timeout, TimeUnit unit) block on the latch with a timeout;

Methods inherited from class oracle.integration.platform.blocks.event.jms2.BaseEdnConnection

getConsistencyLevel, getContextProvider, getEDL, getEDN, getEventHandler, getEventToJmsMapping, getPriority, getTimeout, getTimeToLive, getXPathFilter, isPersistent, isRunAsPublisher, setConsistencyLevel, setContextProvider, setEDL, setEDN, setEventHandler, setEventToJmsMapping, setPersistent, setPriority, setRunAsPublisher, setTimeout, setTimeToLive, setXPathFilter

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

JNDI_DEFAULT_WLJMS_XA_CONN_FACTORY

public static final String JNDI_DEFAULT_WLJMS_XA_CONN_FACTORY

See Also:

Constant Field Values

JNDI_DEFAULT_WLJMS_LOCALTX_CONN_FACTORY

public static final String JNDI_DEFAULT_WLJMS_LOCALTX_CONN_FACTORY

See Also:

Constant Field Values

JNDI_DEFAULT_AQJMS_XA_CONN_FACTORY

public static final String JNDI_DEFAULT_AQJMS_XA_CONN_FACTORY

See Also:

Constant Field Values

JNDI_DEFAULT_AQJMS_LOCALTX_CONN_FACTORY

public static final String JNDI_DEFAULT_AQJMS_LOCALTX_CONN_FACTORY

See Also:

Constant Field Values

Constructor Detail

EdnJmsConnection

public EdnJmsConnection(Context ctx)

Construct a remote JMS Connection to EDN.

Parameters:

ctx - - JNDI Context.

Method Detail

getTopicConnectionFactory

public javax.jms.TopicConnectionFactory getTopicConnectionFactory()

Get non-XA TopicConnectionFactory instance.

Returns:

non-XA TopicConnectionFactory instance.

setTopicConnectionFactory

public void setTopicConnectionFactory(javax.jms.TopicConnectionFactory topicConnectionFactory)

Set a non-XA TopicConnectionFactory instance.

Parameters:

topicConnectionFactory - - non-XA TopicConnectionFactory instance.

getXaTopicConnectionFactory

public javax.jms.TopicConnectionFactory getXaTopicConnectionFactory()

Get XA TopicConnectionFactory instance.

Returns:

XA TopicConnectionFactory instance.

setXaTopicConnectionFactory

public void setXaTopicConnectionFactory(javax.jms.TopicConnectionFactory xaTopicConnectionFactory)

Set a XA TopicConnectionFactory instance.

Parameters:

xaTopicConnectionFactory - - XA TopicConnectionFactory instance.

getUserTransaction

public UserTransaction getUserTransaction()

Get UserTranasction instance for XA.

Returns:

UserTranasction instance for XA.

setUserTransaction

public void setUserTransaction(UserTransaction userTransaction)

Set UserTranasction instance for XA.

Parameters:

userTransaction - - UserTranasction instance for XA.

getClientID

public String getClientID()

Get client ID used for creating durable subscriptions.

Returns:

client ID used for creating durable subscriptions.

setClientID

public void setClientID(String clientID)

Set client ID used for creating durable subscriptions.

Parameters:

clientID - client ID used for creating durable subscriptions.

close

public void close()

close the EDN connection: clean up internal states - wipe out current JMS topic connection factory, close all cached JMS topic connections, JTA user transaction reference, reset subscriber message consuming state flags throws IllegalStateException if the long running event receiver thread is not shutdown

Specified by:

close in interface BusinessEventConnection

Overrides:

close in class BaseEdnConnection

See Also:

BaseEdnConnection.close()

forceClose

public void forceClose()

close the EDN connection: (1) request event receiver thread shutdown; (2) clean up internal states - wipe out current JMS topic connection factory, close all cached JMS topic connections, JTA user transaction reference, reset subscriber message consuming state flags

publishEvent

public void publishEvent(BusinessEvent event)
                  throws oracle.fabric.common.FabricException

Description copied from interface: EdnConnection

Publish an event with default persistent, priority, time to live, and EDL as input source.

Specified by:

publishEvent in interface EdnConnection

Overrides:

publishEvent in class BaseEdnConnection

Parameters:

event - Business Event to be published

Throws:

oracle.fabric.common.FabricException - If it fails to publish the event with default options.

publishEvent

public void publishEvent(BusinessEvent event,
                         int priority)
                  throws oracle.fabric.common.FabricException

Description copied from interface: BusinessEventConnection

Publish an event with indicated priority

Specified by:

publishEvent in interface BusinessEventConnection

Overrides:

publishEvent in class BaseEdnConnection

Parameters:

event - - Business Event to be published

priority - - event priority

Throws:

oracle.fabric.common.FabricException - if fabric exception occurs

publishEvent

public void publishEvent(BusinessEvent event,
                         boolean persistent,
                         int priority,
                         long timeToLive,
                         String edlURI)
                  throws oracle.fabric.common.FabricException

Description copied from interface: EdnConnection

Publish an event with specified delivery mode, priority, time to live, and EDL URI.

Specified by:

publishEvent in interface EdnConnection

Overrides:

publishEvent in class BaseEdnConnection

Parameters:

event - Business Event to be published

persistent - Persistent (or non persistent) delivery mode

priority - Event priority

timeToLive - Time to live in milliseconds

edlURI - URI with "oramds" referencing Event definition content

Throws:

oracle.fabric.common.FabricException - If it fails to publish the event with specified options.

subscribe

public void subscribe(QName eventName,
                      String durableSubscriptionName)
               throws oracle.fabric.common.FabricException

Subscribe to EDN JMS topic (fetched from server through jndi lookup::EDNConfig) for EDN event (indicated by eventName), if durableSubscriptionName presents, a durable subscriber is created with durableSubscriptionName as subscriber name EDN consistency level : default to class instance consistency level EDN event filter: default to class instance event filter EDN event handler: default to class instance event handler EDN run as publisher: default to class instance value of run as publisher EDN event receiving (read) timeout (in millis) : default to class instance timeout value

Specified by:

subscribe in interface EdnConnection

Overrides:

subscribe in class BaseEdnConnection

Parameters:

eventName - - EDN event name to subscribe to;

durableSubscriptionName - - JMS durable subscriber name (client ID takes default value), when not present, it indicates a non-durable subscriber

Throws:

oracle.fabric.common.FabricException - If it fails to subscribe to events with specified options.

See Also:

BaseEdnConnection.subscribe(javax.xml.namespace.QName, java.lang.String)

subscribe

public void subscribe(QName eventName,
                      ConsistencyLevel qos,
                      XPathFilter filter,
                      BusinessEventHandler handler,
                      boolean runAsPublisher,
                      long timeout,
                      String durableSubName)
               throws oracle.fabric.common.FabricException

Subscribe to EDN JMS topic (fetched from server through jndi lookup::EDNConfig) for EDN event (indicated by eventName), if durableSubName presents, a durable subscriber is created with durableSubName as subscriber name, the jms durable subscriber client ID is using the value from EdnJmsConnection class level clientID;

Specified by:

subscribe in interface EdnConnection

Overrides:

subscribe in class BaseEdnConnection

Parameters:

eventName - - EDN event name to subscribe to;

qos - - EDN consistency level: ConsistencyLevel.ONE_AND_ONLY_ONE/ConsistencyLevel.GUARANTEED_DELIVERY

filter - - XPath repression when presents, will be applied to EDN event payload to determine if the event will be delivered to target (or discarded);

handler - - An impl of BusinessEventHandler provided by client for per event processing;

runAsPublisher - - a hint for EDN inbound delivery security policy, when true, the event publisher's subject will be used when deliver event to target;

timeout - - the timeout (in millis) used for subsequent jms message receiving after the subscriber created;

durableSubName - - durable subscriber name (client ID takes the value from class instance level clientID), when not present, it indicates a non-durable subscriber

Throws:

oracle.fabric.common.FabricException - If it fails to subscribe to events with specified options.

See Also:

BaseEdnConnection.subscribe(javax.xml.namespace.QName, java.lang.String)

waitSubscriberCreationComplete

public void waitSubscriberCreationComplete()
                                    throws InterruptedException

block on the latch until latch zero'd

Throws:

InterruptedException

waitSubscriberCreationComplete

public boolean waitSubscriberCreationComplete(long timeout,
                                              TimeUnit unit)
                                       throws InterruptedException

block on the latch with a timeout;

Parameters:

timeout -

unit -

Returns:

Throws:

InterruptedException

subscribeOnly

public EdnJmsEventReader subscribeOnly(QName eventName,
                                       String durableSubscriptionName)
                                throws Exception

create subscriber only, return a EdnJmsEventReader instance where the caller can do fine grained message receiving (start/stop message delivery on the underlying JMS topic connection, read event from the underlying JMS subscriber, etc.) EDN consistency level : default to class instance consistency level EDN event filter: default to class instance event filter EDN event handler: default to class instance event handler EDN run as publisher: default to class instance value of run as publisher EDN event receiving (read) timeout (in millis) : default to class instance timeout value

Parameters:

eventName - - EDN event name to subscribe to;

durableSubscriptionName - - durable subscriber name (client ID takes the value from class instance level clientID), when not present, it indicates a non-durable subscriber

Returns:

- EdnJmsEventReader instance - an object return to the caller with fine grained event consuming API;

Throws:

Exception - error during subscriber creation;

subscribe

public EdnJmsEventReader subscribe(QName eventName,
                                   ConsistencyLevel qos,
                                   XPathFilter filter,
                                   boolean runAsPublisher,
                                   long timeout,
                                   String durableSubName)
                            throws Exception

create subscriber (durable / non-durable) and return an associated POJO (EdnJmsEventReader) to the caller, EdnJmsEventReader provides caller with fine grained event consuming (start/stop message delivery, read one event etc.)

Parameters:

eventName - - full name of the EDN event subscribe to

qos - - EDN consistency level

filter - - XPathFilter - EDN event filter - if present, will override the filter

runAsPublisher -

timeout - - timeout in milli-sec for

durableSubName - - if present, the durable subscriber name, when null - non-durable subscribe

Returns:

EdnJmsEventReader instance that exposes fine grained event consuming (read one event) with control (start/stop message delivery)

Throws:

Exception - - Error during subscription creation.

unsubscribe

public void unsubscribe(QName eventName,
                        String durableSubName)
                 throws oracle.fabric.common.FabricException

Description copied from interface: EdnConnection

Remove a durable subscription that has been created previously.

Specified by:

unsubscribe in interface EdnConnection

Overrides:

unsubscribe in class BaseEdnConnection

Parameters:

eventName - Event QName to unsubscribe to

durableSubName - Durable subscription name whose subscription is to be removed.

Throws:

oracle.fabric.common.FabricException - if it fails to remove the durable subscription due to some internal error, or the subscription name is invalid.

setJmsConfig

public void setJmsConfig(JmsConfig config)

Custom JmsConfig for all the events to be published and subscribed via this Event Connection.

Parameters:

config - - JmsConfig object to set

isReceiving

public boolean isReceiving()

check if the receiver is receiving events.

Returns:

true - receiver is receiving events (in the receiving loop), false - receiver has been stopped or no receiver (no receiver created yet).

stopReceiving

public void stopReceiving()

request that receiver stop receiving events (exit the while loop - next time it checked the flag: stopReceivingRequested)

waitOnReceiver

public void waitOnReceiver()
                    throws InterruptedException

alternative for client sync with event receiving thread (long running)

Throws:

InterruptedException

waitOnReceiver

public void waitOnReceiver(long millis)
                    throws InterruptedException

alternative for client sync with event receiving thread (long running)

Parameters:

millis -

Throws:

InterruptedException