Amazon Queuing Service

Section 1 - Basic Operations

Introduction

The purpose of this example is to implement a user-friendly Queue Service with all possible operations such as Creating Queue, Reading etc, via Axis2-M2 SOAP engine. The Amazon Simple Queue Service (Beta 2) from amazon.com has been chosen for this example as the Web Service Provider.

Using the Amazon Simple Queue Service, developers can decouple components of their application so that they run independently. The Simple Queue Service provides the message management between the independent components. Any component of a distributed application can store any type of data in a reliable queue at Amazon.com. Another component or application can retrieve the data using queue semantics. More information on this service visit here

In this example String objects are used to store in the Amazon queue.

Description of the operations is available at http://webservices.amazon.com/AWSSimpleQueueService/AWSSimpleQueueService.wsdl

Getting Started

The users who need to get the Web services out of this queue need to be registered with the amazon.com, as a developer. (For this particular example a key has been obtained from Amazon and via property file it has called to OMElement). Once being registered, a subscription Id will be given. This key has to be used with your code to get the required Web services. The key that is being obtained, should be incorporated to the key.properties file, which is located at ${user.dir}\modules\samples\properties

Registration can be done at http://www.amazon.com/gp/aws/registration/registration-form.html

There are seven services available for this queue from Amazon. Create Queue, Configure Queue, List My Queues, En-queue, Read and De-queue. For this example Create Queue, En-queue, Read and List My Queues have been implemented.

En-queue operation has not been implemented. This operation has left out for users to implement. It is expected that once the user has implemented this operation, the fundamental perspective of the Axis2-M2 over Web Services is dealt with perfectly.

The code is based on invokeNonBlocking(String, OMElement, Callback) operation to understand the maximum flexibility of the Axis2-M2.

Operations

The manipulation of the queue is divided in to two categories,

IN operations

In these operations user will be given the autonomy to create a new queue or use an existing queue to enqueue the selected queue. Only one queue is subjected to manipulate at a given instance.

OUT operations

In these operations user will be given the autonomy to list the queues that once possess for a given subscription Id and read the entries of a particular queue or if the queue is empty the queue can deliberately be deleted. If the queue is not empty, the delete operation will not work. The queue must empty before it has to be deleted. It is expected that the user to implement the de-queue operation in order to get the full understanding of the code. Necessary steps will be provided at the end of this documentation.

On the perimeters of this example, I have generated a key (0HPJJ4GJDSG2TZ2C8X02) which is the subscription Id and hard coded to the key.properties file and OMElement objects obtained the value through Properties API, for each operation invocation. The service end point also hard coded, (http://webservices.amazon.com/onca/soap?Service=AWSSimpleQueueService ). Thus, when a user reads the queues available, queues pertaining to this key will be displayed.

Section 2 - Architecture and Advanced Operations

Architecture of the Code

The structure of the code has been divided in to three sections for the simplicity of understanding.

• GUI component – This code is pertaining to GUI interface development.
• Underlying Event Listeners and Runnable Component – The code pertaining to GUI and Axis2-M2 codes are being allowed to run on different threads. This is allowed, in order to make sure that the GUI is not blocked during the method invocation and consume the whole power of invokeNonBlocking() method.
• Axis2-M2 Component – Since this example is based on invokeNonBlocking() user has to provide the Callback object. Thus, a class that is extended from Callback can be used manipulate the code after completion of the invocation, which is onComplete() method.

OMElement for relevant operations are carried out by CreateQueue, DeleteQueue, Enqueue and Read classes. Event Listener for IN operations is carried by ListenersIn and OUT operations ListenersOut classes. Separate threads are created by RunnableXXX classes. Extended classes from Callback handled by SimpleQueueXXXCallbackHandler classes.

Once a event is generated by AmazonSimpleQueueServiceXX class, the event is handled by ListnersXX class. The listener classs has references to RunnableXXX class, which is carried out the Axis2-M2 execution code.

Once an event is generated by AmazonSimpleQueueServiceXX class, the event is handled by ListnersXX class. The listener class has a reference to RunnableXXX class, which contains the Axis2-M2 execution code. RunnableXXX class has references to classes that support OMElement, which is needed as references to invokeNonBlocking(String, OMElement,Callback) method and SimpleQueueXXXCallbackHandler classes. Once the onComplete() method executes, the response is send back to GUI's response handling components. Figure below shows the schematic architecture of the sample.

All the Web services are available as rpc-literal encoded style. Thus, OMElemnts adheres to this requirement.

Running the Samples

1. IN operations – Go to ${user.dir}/modules/samples and type “ant amazonIn”
2. OUT operations – Go to ${user.dir}/modules/samples and type “ant amazonOut”

GUI for IN operations is popped by Running RunGUICQ class and OUT operations is popped by running RunGUIRQ class.

Handling the GUI Components

• IN operations – Once the GUI is being loaded, user is given the access to create a new queue. When type the name and Enter a new queue will be generated to the given subscription Id (which is hard coded), if the name exists user will allow to enqueue the queue.
  
• OUT operations – Once the GUI is being loaded, user should load the queues pertaining to the given subscription Id (hard coded for this example). The results will contain the queue name and queue code. It is recommended that the user select only the full queue name only not the queue code. Once selected, it will be displayed on the text field. Select the text field and press enter to read the queue.

Guide to Create the Dequeue Operation

1. It is recommended that the user go through with the Dequeue operation description from WSDL.
2. Write your custom Callback class to handle the onComplete() method.
3. Write the OMElement which corresponds Dequeue opreation.
4. Write the class which implements the Runnable interface to handle the invokeNonBlocking() method.
5. Write the event handler to execute the above mentioned class.
6. Add a Component to the AmazonSimpleQueueServieOut GUI class and add the above class as an action listener.