Applies to

Introduction

WSO2 Enterprise Service Bus is a simple, lightweight and high performing enterprise service bus which is recognized for its performance, user friendliness and 1st class support for enterprise application integration patterns. This tutorial describes about configuring ESB proxy to publish messages to a Topic. Then a Message Box subscribes to the Topic as the clients can publish and subscribe to Message Box. Here I explain the design and this feature using examples.

Architecture

Forwarding diagram of messages for publishing messages from ESB proxy service to Topic and Message Box is subscribed to Topic.

Message Boxes

Message Box provides Simple Queue Service ( SQS) . It provides the facility for users to store messages in an intermediate location which were sent by some one else to the user and access them on demand. This feature is like a email box we have and any one can send messages to Queue and only the owner of the queue can consume the messages stored in that queue. Though the Message Box is a feature in WSO2 Message Broker server and we can use it as a installed feature to ESB. This is done with the purpose of the connection of ESB proxy service and Message Box together. Message Box is used as an event sink when it is subscribed to a Topic in this usecase.

To access the Message Box, each user must have access keys. Two access keys are required for the accessing and they are called Access Key Id and Secret Access Key. If the request is sent to the SQS service, that should be signed with secret access key and the access key id should be included as a request parameter.

Installing Message Box Feature

To install features, user need to logged in as admin. You can use username, “admin” and password “admin” to log in as the admin. Steps of installing the Message Box features are as follows.

• Go to Home > Configure > Features
• Add repository there: “https://dist.wso2.org/p2/carbon/releases/3.2.0” as the url and any name.(e.g. wso2Repository)
• Click on “Find Features” and it will list available features
• Tick the Message Box and install.
• Restart the server after installing Message Box.

Create a Message Box

Message boxes can be added with a name and a default visibility time out value. Message box name should contain only alpha numeric characters and no white spaces allowed.

When a message is received by a user, that message is unaccessible for a specified time duration, and this message is not visible for other users till that specified time duration is over. If the message received user did not delete the message in that time duration, the message is visible for other users. This time duration is named as visibility timeout. When the message box is created, a default value for visibility timeout is set. This is called as default visibility timeout value.

• Add a Message Box and give any name and an appropriate visibility timeout: I will use “MyMessageBox” in the next steps.

Topic

Concept of Topic allows users to rout message to the required users of particular sector. For example if a particular user want to publish a message to a SportNews sector , he creates a topic with a name 'SportsNews' which is related to the messages that he is going to publish and publish the messages to that topic. Then if another particular user is interested on 'SportsNews' topic, he can subscribe to that topic and receive messages which are published to 'SportsNews' topic by the publisher.

Create a Topic

• Got to Home > Manage> Topics >Add
• Give a name for Topic: I will use “SportsNews” in the next steps.

Subscribe Message Box to Topic

After subscribing to Topic, user can view the content of the message box which are sent from Topic by going through link in list view. In message box page, users can view messages which are retrievable under content of message box and add new messages to Message Box.

• Click on Topic name and then on Subscribe.
• There you only have to fill the “Event Sink URL” to subscribe MyMessageBox. (e.g. sqs://admin/MyMessageBox)

Proxy Service

An ESB may function as a gateway or proxy for applications that do not expose a standardized service interface to the outside world. Here we use a proxy service to publish messages to Topic.

Add a proxy event mediator which can publish messages to Topic we created

• Here we add the proxy using “Source View” option
• Go to Home > Manage > Service Bus > Source View

Create a out sequence for proxy

We need to have a out sequence to publish messages from ESB proxy to Topic which is created before.

• Add a sequence there. (E.g. “PublicEventSource). State “SportsNews” as the event topic

  <sequence name="PublicEventSource">
       	<log level="full">
       	     	<event topic="SportsNews"/>
       	</log>
  </sequence>
  

• Then we create the proxy service which is simply publish its messages to Topic. Give any name : e.g. “EventingProxy”. State the sequence name which we created above as target.

  <proxy name="EventingProxy" startOnLoad="true">
       	<target inSequence="PublicEventSource"/>
  </proxy>
  

  To send messages to proxy service created above, you can invoke it using a tool like SOAP UI.

Example Java client

Finally you have to come to the stage where we can receive messages from the Message Box. Even though the client can publish messages to the Message box and subscribe to Message Box, we only use the subscribing scenario for this article. You can receive these messages using client written in any language. For example, I have provided a java client below to test the scenario using a message receive method. Complete code for SQS client is explained well at [2] and attached as a .zip file at [3].

Initially you have to create an user to act as the client. Steps are here.

• Go to Home>Configure>Users and Roles>Users>Add User
• Create user using any name(e.g. lahiru) and password and click next.
• Leave admin option unchecked at step 2 and finish.

Then we have to enable newly created user to login since we created the user without admin option. We allow everyone to login as follows,

• Go to Home>Configure>Users and Roles>Roles and click on permissions
• Check the login option and update

We have to give Message Box operations permissions to user. We allow to receive and delete messages for now(publish use case is not used here).

• Go to Home>Manage>Message Boxes>List and click on your Message Box(MyMessageBox)
• Add permissions to user created. Give Receive and Delete permissions to him(tick on them and Add permission).
• Then log out and log in as the new user(lahiru).

You need to have two keys namely Access Key ID and Secret Access Key. These keys can be obtained after you log in as new user under Manage menu > MessageBoxes/SQS > Access keys. In each requests to SQS service, the request is signed with secret access key. And the access key id is included as a request parameter.

• Update Java client with above Access key and Secret access key
• Update the Message box URL in following code with host name and port.

public void receiveMessages() throws RemoteException {
	MessageQueueStub messageQueueStub = new 							MessageQueueStub("https://localhost:9772/services/MessageQueue/admin/MyMessageBox");
	MessageQueueStub.ReceiveMessage receiveMessage = new MessageQueueStub.ReceiveMessage();
	receiveMessage.setMaxNumberOfMessages(new BigInteger(MAX_NUMBER_OF_MESSAGES));
	receiveMessage.setVisibilityTimeout(new BigInteger("200000"));
	addSoapHeader(messageQueueStub, "ReceiveMessage");
	MessageQueueStub.ReceiveMessageResponse receiveMessageResponse = 	messageQueueStub.receiveMessage(receiveMessage);
	MessageQueueStub.Message_type0[] message_type0s = 	receiveMessageResponse.getReceiveMessageResult().getMessage();
	if (message_type0s != null) {
		for (MessageQueueStub.Message_type0 message_type0 : message_type0s) {
		System.out.println("message_type0.getBody() = " + message_type0.getBody());

	}
}

You can see the retrieved messages after running this client code sample. More detailed client who do publishing and subscribing is explained at [2].

Conclusion

In this article we discussed about the ESB proxy, Message Box and a use case of them. Also we looked at how to implement that using examples. Finally we wrote a client code to subscribe to the Message Box.

References

[1]. https://aws.amazon.com/archives/Amazon-SQS/2317

[2]. https://wso2.org/project/message-broker/1.0.0/docs/samples/messagebox_as_event_sink.html

[3]. https://wso2.org/files/samples/SqsClient-java.zip

Author

Lahiru Sandaruwan, Software Engineer, [email protected]