From Online MQ

OnlineMQ provides client libraries for developers in Java, Ruby and PHP for integrating OnlineMQ easily.

Contents 1 Java 1.1 Java Libraries 1.2 Using Java API 1.3 Java API Samples 2 Ruby 2.1 Initializing an OnlinemqClient instance 2.2 Example with quick get and put methods 2.3 Example with use of canonical object 2.4 Example using cheap transaction 3 PHP

Java

OnlineMQ provides a Java library for using OnlineMQ in Java.

If you'd like to implement SOAP, REST or POX in Java please read our Web services guide.

OnlineMQ is also part of Spring Integration starting from version 2.0.8.

Java Libraries

The OnlineMQ java library package contains the following:

• OnlineMQ jar file - contains the API library
• Sample code files - contains sample code for using the library
• 3rd part jar files - the jar files that are needed to use OnlineMQ APi

Download all the above here.

To use the library you must have the following jars (from the java library package ) in your class-path:

• \lib\onlinemq-1.7.jar
• \lib\3rdParty\axis.jar
• \lib\3rdParty\commons-discovery-0.4.jar
• \lib\3rdParty\commons-logging-1.1.jar
• \lib\3rdParty\jaxrpc.jar
• \lib\3rdParty\log4j-1.2.14.jar
• \lib\3rdParty\mail.jar
• \lib\3rdParty\wsdl4j.jar

Using Java API

First you have to acquire a connection to OnlineMQ using the OMQConnection object:

String omqUser = "user";
String omqPassword = "pass";
String omqQueueManager = "qmgr1";
String omqQueue = "q1";
OMQConnection con = OMQConnectionFactory.getConnection(omqUser,omqPassword, new OMQQueueManager(omqQueueManager));

Next you need to create a session using the OMQSession object, sessions are used for transactional and non-transactional actions, currently transactions are not supported.

OMQSession sess = con.createSession(false);

Now you Send a message or Receive a message (or perform any other action against a Queue):

send a message

String stringSent = "hello world";
OMQMessage msgSent = new OMQMessage(stringSent);
int rc = sess.sendMessage(new OMQQueue(omqQueue), msgSent);
System.out.println("sent message ID = "+sess.getLastMessageID());

receive a message

OMQMessage msgReceived = sess.receiveMessage(new OMQQueue(omqQueue));
int rc = sess.getLastErrorCode();
String stringReceived = (String)msgReceived.getMsgBodyAsObject();

You can retrieve the error-code and error-description of the last action performed on the session:

System.out.println("LastErrorCode()="+sess.getLastErrorCode()+", LastErrorDescription()="+sess.getLastErrorDescription());

You can retrieve the message-id of the last message that we sent or received:

System.out.println("received message ID = "+sess.getLastMessageID());

Refer to OnlineMQ API JavaDoc for more info on the API.

Java API Samples

Use the following 4 java samples to integrate OnlineMQ easily:

1. CheckConnection.java
2. SendMessage.java
3. PeekMessage.java
4. ReceiveMessage.java

This library will be provided as a JMS Driver in the future.

Ruby

This library will be provided as a ruby gem in the future. For now it can be downloaded directly

onlinemq_client.rb
download the library here

The library is dependent on the builder gem so install this gem first:

 gem install builder 

Initializing an OnlinemqClient instance

After requiring the client library in your Ruby code you get the OnlinemqClient class. An instance of the OnlinemqClient is used to communicate with the OnlineMQ server and handles the encoding stuff (so you can just use UTF-8 message strings and not worry about the XML interface level).
The OnlinemqClient instance also holds two private variables: An HTTP Adapter and a Canonical Prototype.
The HTTP adapter manages the connection to the OnlineMQ server (the connection is kept open between subsequent requests for performance reasons).
The canonical prototype holds the default canonical values and is cloned for each individual request. The default values of the clone can then be overwritten if needed. Since all OnlineMQ communication (at the XML interface level) happens through the same canonical structure this canonical object can be used for all actions. The following attributes are stored on the canonical object:

• login
• password
• queue_manager_id
• queue_manager_name
• queue_id
• queue_name
• message_id
• message_body
• body_encoding_id
• body_encoding_name
• action
• error_code
• error_description

The default values for the canonical prototype can be assigned through the OnlinemqClient instance methods (just prefix the attribute names with 'default_'):

client = OnlinemqClient.new
client.default_login = 'test_login'
client.default_password = 'test_password'
client.default_queue_manager_name = 'test_queue_manager'
client.default_queue_name = 'test_queue'
...

The default values for the canonical prototype can also be mass assigned:

client = OnlinemqClient.new
client.default_canonical_values( 
  :login => 'test_login', 
  :password => 'test_password',
  :queue_manager_name => 'test_queue_manager',
  :queue_name => 'test_queue' )

A clone of the canonical can be created by the OnlinemqClient instance build_canonical method. This clone can then be used for a request to the OnlineMQ server.

canonical = client.build_canonical

The attributes on an individual (cloned) canonical instance can be accessed like a Hash as well. This is mostly used for the message_body in practice:

canonical = client.build_canonical
canonical[:queue_manager_name] = 'test_queue_manager'
canonical[:queue_name] = 'test_queue'
canonical[:message_body] = 'this is the message body to be send to or received from the queue'

Example with quick get and put methods

This example can be used on queues with auto delete enabled. This means the receive action also directly removes the message from the queue (see the in depth API).

The quick_send_message method takes a string as an argument (the message body) and the quick_receive_message method returns a string (the message body of the received message). With the quick methods, the use a canonical object is hidden from the user.
If the actions were unsuccessful (some errorcode not equal to zero) an exception will be raised by the client. The exception message will have the following structure: "errorcode #{error_code}: #{error_description}"

require 'onlinemq_client'

client = OnlinemqClient.new
client.default_canonical_values( 
  :login => 'test_login', 
  :password => 'test_password',
  :queue_manager_name => 'test_queue_manager',
  :queue_name => 'test_queue' )

message = "test from the client"

client.quick_send_message( message )
puts "Sent Message: #{message}"

received_message = client.quick_receive_message
puts "Received message: #{received_message}"

The quick_send_message method is also available as quick_put
The quick_receive_message method is also available as quick_get

Example with use of canonical object

This example can be used for all types of queues and is the most generic form of using the OnlinemqClient library.

For each request you first clone the canonical prototype object, then set additional parameters on the cloned object and use it in the request. There are 4 methods that can be used with a canonical object. All methods take and return a canonical instance:

• send_message
• receive_message
• peek_message
• delete_message

If the actions were unsuccessful (some errorcode not equal to zero) no exception will be raised by the client. The error code and error description will simply be available on the returned canonical object. You can use the success? method on the canonical object to check if there was an error during the action.

require 'onlinemq_client'

client = OnlinemqClient.new
client.default_canonical_values( 
  :login => 'test_login', 
  :password => 'test_password',
  :queue_manager_name => 'test_queue_manager',
  :queue_name => 'test_queue' )
 
canonical = client.build_canonical
canonical[:message_body] = "test from the client"

puts "Request body: #{canonical[:message_body]}"
response_canonical = client.send_message( canonical )
puts "Request sent successfully: #{response_canonical.success?}"

canonical = client.build_canonical
response_canonical = client.receive_message( canonical )

puts "Response success: #{response_canonical.success?}"
puts "Response body: #{response_canonical[:message_body]}"

The send_message method is also available as put
The receive_message method is also available as get
The peek_message method is also available as peek
The delete_message method is also available as delete

Example using cheap transaction

OnlineMQ also provides cheap transaction support through the means of timeouts (see the in depth API section). A usage example is shown below:

require 'onlinemq_client'

client = OnlinemqClient.new
client.default_canonical_values( 
  :login => 'test_login', 
  :password => 'test_password',
  :queue_manager_name => 'test_queue_manager',
  :queue_name => 'test_queue_with_cheap_transaction' )

### Put something in the queue as a working example ###

canonical = client.build_canonical
canonical[:message_body] = "test from the client"

puts "Request body: #{canonical[:message_body]}"
response_canonical = client.send_message( canonical )
puts "Request sent successfully: #{response_canonical.success?}"

### The Processing Application ###

# Get the message from a queue where the visibility_timeout has been defined (e.g. 10 seconds)
# after getting the message, the message is reserved for this user for 10 seconds and 
# will be invisible for other users

canonical = client.build_canonical
response_canonical = client.receive_message( canonical )
puts "Response success: #{response_canonical.success?}"
puts "Response body: #{response_canonical[:message_body]}"

# Process the message here
# Processing should take considerably less then the visibility_timeout (adjust the timeout accordingly)
process_success = rand > 0.5

if process_success
  
  ### message has been processed and can be removed from the queue
  ### delete the processed message from the queue

  canonical = client.build_canonical
  canonical[:message_id] = response_canonical[:message_id]
  response_canonical = client.delete_message( canonical )
  puts "Delete msg[#{canonical[:message_id]}] success: #{response_canonical.success?}"

else
  
  ### something went wrong in the processing, the message should be retried later
  ### let the visibility_timeout auto rollback the receive message
  ### after 10 seconds the receive_message will be rolled back and 
  ### the message can be received from the queue again by any user
  
end

PHP

TBD...