rwsf::JmsClient

Does not inherit

• Local Index
• Header File
• Description
• Public Typedefs
• Public Enums
• Public Constructors
• Public Destructors
• Public Member Functions
• Public Operators

Members

acknowledgeMessage() consumeObject() consumeText() createConsumer() createProducer()

getID() InstanceIdType interruptConsumer() isValid() JmsClient()

operator>>() operator<<() produceObject() produceText() queueMessageCount()

ReceiveMode releaseJmsImp() start() stop() ~JmsClient()

#include rwsf/transport/jms/JmsClient.h

Class JmsClient represents a JMS client. It is instantiated by specifying a JMS provider and queue name. Once instantiated, messages can be produced to, or consumed from, a JMS queue. JMS operations are realized by the RWSFJavaImp.java and other java classes via JNI.

No JNI nor Java knowledge is required to use this class, just a basic understanding of the JMS fundamentals.

Due to JNI limitations, this class cannot be instantiated in one thread and then passed to another. If this is necessary, the class can be instantiated in one thread with the autoRelease constructor argument set to false. Then call getID() and pass that ID to the other thread, and use the id constructor. If autoRelease is false, then the original JmsClient instance may go out of scope, since the actual RWSFJavaImp instance is maintained in the JVM in the RWSFStaticMapper class. When autoRelease is false, the RWSFJavaImp instance is removed from the JVM by calling releaseJmsImp().

jint InstanceIdType;

Instance id type used by methods:

• JmsClient( InstanceIdType id, bool autoRelease )

• InstanceIdType getID()

ReceiveMode { RECEIVE_NOWAIT, RECEIVE_BLOCKING }

Enumeration specifying receive modes. In blocking mode, calls made to consumeText(), consumeObject(), and operator>>() will block until a message is received. In nowait mode, calls made to these methods return immediately. If a JMS messages was available it will be returned, otherwise an empty string will be returned.

Note

An error was found with openJMS when using RECEIVE_NOWAIT when autoAck is set to true and instantiating the JMSClient. Trying to acknowledge a message from the client does not work.

JmsClient(const std::string & providerName,
    const std::string & queueName,
    bool autoAck = true,
    ReceiveMode rxMode = RECEIVE_BLOCKING,
    bool autoRelease = true);

Main constructor. Creates a RWSFJmsImp java instance in the RWSFJmsStaticMapper. The connection is not automatically started and must be started using start(). Once instantiated, use isValid() to check for proper JMS setup.

Parameter descriptions

providerName	looked up in $RWSF_CONF/jms/jmsProviders.xml
queueName	is the queue to produce to or consume from
autoAck	autoAcknowledge received messages or not. If true, then JMS message persistance may be lost if the application fails.
rxMode	receive JMS messages blocking or not
autoRelease	determines whether or not to delete from the RWSFJmsStaticMapper in destructor

Exceptions

rwsf::JmsException

is thrown if an error is occured during intialization.

JmsClient(InstanceIdType id,
    bool autoRelease = true);

The JNI interface pointer (JNIEnv *) is only valid in the current thread. If it is necessary to create an instance in one thread and use it in another, create the instance with the main constructor, call getID() and pass that ID to the other thread, and then use this constructor. Once instantiated, use isValid() to check for proper JMS setup.

Exceptions

rwsf::JmsException

if an error is occured during intialization.

virtual
~JmsClient();

Destructor Release the JNI resources Release the JMS resources in the JVM if autoRelease_ was set true in the ctor

void
acknowledgeMessage(const std::string & msgStr);

Acknowledges the message in the JMS Provider, if this class was instantiated with autoAck set false, It may be possible to have several messages consumed by this instance that haven't been acknowledged yet, so the message text string is used as a key to identify which message to acknowledge.

Exceptions

rwsf::JmsException

thrown upon error.

std::string
consumeObject();

Receives a JMS object message. The string returned will be a valid XML representation of the marshalled Java object. This method blocks and returns the same as consumeText().

Exceptions

rwsf::JmsException

thrown upon error.

std::string
consumeText();

Receives a JMS text message. May block until a message is received. If the object was instantiated with receiveMode set to JmsClient::RECEIVE_NOWAIT, then this call checks for a message and returns it, if one is available; otherwise, returns an empty string.

Exceptions

rwsf::JmsException

thrown upon error.

void
createConsumer();

Creates a consumer. Normally the decision to be a consumer or producer is postponed until either the consume() or produce() method is called, but if it is necessary to have the JMS consumer creation completed before calling consume(), then this method will complete that creation. This is necessary when creating multiple consumers to the same queue in the same process. They should ALL be created before calling start().

void
createProducer();

Creates a producer. Normally the decision to be a consumer or producer is postponed until either a consume() or produce() method is called, but if it is necessary to have the JMS producer creation completed before calling produce(), then this method will complete that creation. This is necessary when creating multiple producers to the same queue in the same process. They should ALL be created before calling start()

InstanceIdType
getID();

Returns the ID of this instance in the RWSFJmsStaticMapper.

Note

Each instantiation of this class is stored in the JVM in the RWSFJmsStaticMapper.

void
interruptConsumer();

If consuming in blocking mode, this method will interrupt the call. Since the current thread will be blocked, this will have to be done from a separate thread via the constructor that takes the instance id.

bool
isValid() const;

Determines if the object was correctly instantiated. Returns true if correctly instantiated; otherwise, false.

void
produceObject(const std::string & className,
    const std::string & msgStr);

Sends a JMS object message to a JMS queue. The given msgStr must be valid XML that can be marshalled into a className java object.

Exceptions

rwsf::JmsException

thrown upon error.

void
produceText(const std::string & msgStr);

Sends a JMS text message to a JMS queue.

Exceptions

rwsf::JmsException

thrown upon error.

int
queueMessageCount();

Returns the number of messages waiting in the queue. This uses a JMS Queue Browser, which is very slow when the queue has a large number of messages.

Exceptions

rwsf::JmsException

thrown upon error.

void
releaseJmsImp();

Release the object in the JVM and releases any unused JMS resources.

Exceptions

rwsf::JmsException

thrown upon error.

Note

Each instantiation of this class is stored in the JVM in the RWSFJmsStaticMapper.

void
start();

Starts the connection once the class is instantiated, or if stop() has been called. Calling this method once the connection is already started has no adverse affects.

Exceptions

rwsf::JmsException

thrown upon error.

void
stop();

Stops the connection. Call start() to start it again. Calling this method once the connection is already stopped has no adverse affects.

Exceptions

rwsf::JmsException

thrown upon error.

void
operator<<(const std::string & msgStr);

Streams a string in, and writes the text to a queue. Calls produceText().

void
operator>>(std::string & consumedMsgText);

Streams a string out, which will read the text string from a queue. Calls consumeText().

© Copyright Rogue Wave Software, Inc. All Rights Reserved. All Rights Reserved. Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. HydraExpress is a trademark of Rogue Wave Software, Inc. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.