<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <title>Amazon Simple Queue Web Service - Sample</title>
  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
</head>

<body>
<h1>Amazon Queuing Service</h1>

<h2>Section 1 - Basic Operations</h2>

<h3>Introduction</h3>

<p>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.</p>

<p>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 <a
href="http://www.amazon.com/gp/aws/sdk/" target="_blank">here</a></p>

<p>In this example String objects are used to store in the Amazon queue.</p>

<p>Description of the operations is available at <a
href="http://webservices.amazon.com/AWSSimpleQueueService/AWSSimpleQueueService.wsdl"
target="_blank">http://webservices.amazon.com/AWSSimpleQueueService/AWSSimpleQueueService.wsdl</a></p>

<h3><strong>Getting Started</strong></h3>

<p>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</p>

<p>Registration can be done at <a
href="http://www.amazon.com/gp/aws/registration/registration-form.html"
target="_blank">http://www.amazon.com/gp/aws/registration/registration-form.html</a></p>

<p>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.</p>

<p>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.</p>

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

<h3><span class="style3">Operations</span></h3>

<p>The manipulation of the queue is divided in to two categories,</p>

<h4><em>IN operations</em></h4>

<p>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.</p>

<h4><em>OUT operations</em></h4>

<p>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.</p>

<p>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, (<a
href="http://webservices.amazon.com/onca/soap?Service=AWSSimpleQueueService">http://webservices.amazon.com/onca/soap?Service=AWSSimpleQueueService</a>
). Thus, when a user reads the queues available, queues pertaining to this
key will be displayed.</p>

<h2>Section 2 - Architecture and Advanced Operations</h2>

<h3>Architecture of the Code</h3>

<p>The structure of the code has been divided in to three sections for the
simplicity of understanding.</p>
<ul>
  <li><em>GUI component</em> &#x2013; This code is pertaining to GUI
    interface development. </li>
  <li><em>Underlying Event Listeners and Runnable Component</em> &#x2013; 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. </li>
  <li><em>Axis2-M2 Component </em>&#x2013; 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. </li>
</ul>

<p>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.</p>

<p>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.</p>

<p>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.</p>

<p><img src="AmazonSimpleWebService_clip_image002.gif" width="579"
height="321"><br>
All the Web services are available as rpc-literal encoded style. Thus,
OMElemnts adheres to this requirement.</p>

<p class="style3">Running the Samples</p>
<ol>
  <li><em>IN operations </em>&#x2013; Go to ${user.dir}/modules/samples and
    type &#x201c;ant amazonIn&#x201d;</li>
  <li><em>OUT operations</em> &#x2013; Go to ${user.dir}/modules/samples and
    type &#x201c;ant amazonOut&#x201d;</li>
</ol>

<p>GUI for IN operations is popped by Running RunGUICQ class and OUT
operations is popped by running RunGUIRQ class.</p>

<p class="style3">Handling the GUI Components</p>
<ul>
  <li><em>IN operations</em> &#x2013; 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. <br>
  </li>
  <li><em>OUT operations</em> &#x2013; 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. </li>
</ul>

<p class="style3">Guide to Create the Dequeue Operation</p>
<ol>
  <li>It is recommended that the user go through with the Dequeue operation
    description from WSDL.</li>
  <li>Write your custom Callback class to handle the onComplete() method.</li>
  <li>Write the OMElement which corresponds Dequeue opreation.</li>
  <li>Write the class which implements the Runnable interface to handle the
    invokeNonBlocking() method.</li>
  <li>Write the event handler to execute the above mentioned class.</li>
  <li>Add a Component to the AmazonSimpleQueueServieOut GUI class and add the
    above class as an action listener.</li>
</ol>

<p><br>
</p>
<hr>
</body>
</html>