Quickstart

This is a step-by-step guide to create a simple chat application. It consists of a sender to post messages you type to a JMS Topic and a receiver to display all messages coming in from that topic. Both are implemented as simple servlets. Most of the things in it could have to be done with plain JMS as well. But if you know JMS, you'll see the big difference in the code you don't have to write. If you prefer to download everything, you can get it here. To make the interesting things more visible, the stuff that's not specific to the MessageApi but just to make the servlets work, is set in grey. You can skip that, if you just want to get an impression of how to work with the MessageApi.

Things we are working on to make it even easier, are set in green and small.

This demo is done with maven 2.2.1 and Glassfish 3.0.1. But it should be straight forward to adapt to any container supporting JMS and to any build tool.

Build the MessageApi

  1. svn co https://messageapi.dev.java.net/svn/messageapi/tags/1.1 messageapi
  2. cd messageapi
  3. mvn clean install
    we are working on getting the messageapi into a maven repository, so you could skip this step.

Create the Chat-API

  1. mvn archetype:create -DgroupId=chat -DartifactId=chat-api -DarchetypeGroupId=net.java.messageapi -DarchetypeArtifactId=api-archetype -DarchetypeVersion=1.1 -DremoteRepositories=http://download.java.net/maven/2
  2. replace the sample MyMessageApi.java with your own ChatApi.java:
    @MessageApi
    public interface ChatApi {
    	public void send(String message);
    }
  3. mvn clean install

Create the Sender

  1. create a web project: mvn archetype:generate -B -DarchetypeGroupId=org.codehaus.mojo.archetypes -DarchetypeArtifactId=webapp-javaee6 -DgroupId=chat -DartifactId=chat-send -Dpackage=chat
  2. add dependencies to your chat-api, to joda-time:1.6.2, and the net.java.messageapi:adapter:1.1
  3. remove the file src/main/webapp/index.jsp
  4. create the folder src/main/webapp/WEB-INF
  5. create the file web.xml in that folder with this contents:
    <?xml version="1.0" encoding="UTF-8"?>
    <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
    	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
    	<servlet>
    		<servlet-name>ChatSend</servlet-name>
    		<servlet-class>chat.ChatSend</servlet-class>
    	</servlet>
    	<servlet-mapping>
    		<servlet-name>ChatSend</servlet-name>
    		<url-pattern>/chat-send</url-pattern>
    	</servlet-mapping>
    	<welcome-file-list>
    		<welcome-file>chat-send</welcome-file>
    	</welcome-file-list>
    </web-app>
    
  6. create the chat.ChatSend.java (the imports and stuff are left out for brevity):
    public class ChatSend extends HttpServlet {
        private static final long serialVersionUID = 1L;
    
        private final ChatApi chat = MessageSender.of(ChatApi.class);
    
        @Override
        protected void doGet(HttpServletRequest request, HttpServletResponse response)
                throws IOException {
            // we're not expecting any GET parameters!
            response(response);
        }
    
        @Override
        protected void doPost(HttpServletRequest request, HttpServletResponse response)
                throws IOException {
            request(request);
            response(response);
        }
    
        private void request(HttpServletRequest request) {
            String message = request.getParameter("message");
            if (message != null && message.length() > 0) {
                chat.send(message);
            }
        }
    
        private void response(HttpServletResponse response) throws IOException {
            PrintWriter out = response.getWriter();
            out.println("<html>");
            out.println("  <head><title>Chat Send</title></head>");
            out.println("  <body>");
            out.println("    <h2>Please enter your message</h2>");
            out.println("    <form method=\"post\" action=\"chat-send\"><p/>");
            out.println("      <input type=\"text\" name=\"message\" size=\"50\"/><br/>");
            out.println("      <input type=\"submit\" value=\"Send\" />");
            out.println("    </form>");
            out.println("  </body>");
            out.println("</html>");
        }
    }
    
  7. Create the configuration file chat.ChatApi.config:
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <jmsSenderFactory api="net.java.messageapi.test.TestApi">
        <destination name="Chat">
            <factory>ConnectionFactory</factory>
            <user>guest</user>
            <pass>guest</pass>
            <transacted>true</transacted>
        </destination>
        <xmlJmsPayloadHandler/>
    </jmsSenderFactory>
    
    we are working on a automatic registry for services, so this config would be unnecessary.
  8. build the war: mvn clean verify

Create the Receiver

  1. create another web project: mvn archetype:generate -B -DarchetypeGroupId=org.codehaus.mojo.archetypes -DarchetypeArtifactId=webapp-javaee6 -DgroupId=chat -DartifactId=chat-receive -Dpackage=chat
  2. change the maven dependency on javaee-web-api to the full javaee-api; we'll add a MDB
  3. add dependencies to your chat-api and the net.java.messageapi:adapter:1.1
  4. remove the file src/main/webapp/index.jsp
  5. create the folder src/main/webapp/WEB-INF
  6. create the file web.xml in that folder with this contents:
    <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
    	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
    	<servlet>
    		<servlet-name>ChatReceive</servlet-name>
    		<servlet-class>chat.ChatReceiveServlet</servlet-class>
    	</servlet>
    	<servlet-mapping>
    		<servlet-name>ChatReceive</servlet-name>
    		<url-pattern>/chat-receive</url-pattern>
    	</servlet-mapping>
    	<welcome-file-list>
    		<welcome-file>chat-receive</welcome-file>
    	</welcome-file-list>
    </web-app>
    
  7. create the chat.ChatReceiver:
    public class ChatReceiver implements ChatApi {
    
        static List<String> messages = new ArrayList<String>();
    
        @Override
        public void send(String message) {
            ChatReceiver.messages.add(message);
        }
    
        public List<String> getMessages() {
            return ChatReceiver.messages;
        }
    
        public void setMessages(List<String> messages) {
            ChatReceiver.messages = messages;
        }
    }
    
  8. create the chat.ChatMDB:
    @MessageDriven(mappedName = "Chat")
    public class ChatMDB extends MessageDecoder<ChatApi> {
    	public ChatMDB() {
    		super(ChatApi.class, new ChatReceiver());
    	}
    }
    
    we are working on a generic MDB, so you only have to configure the connection between a destination and your business bean
  9. create the chat.ChatReceiveServlet:
    public class ChatReceiveServlet extends HttpServlet {
        private static final long serialVersionUID = 1L;
    
        @Override
        protected void doGet(HttpServletRequest request, HttpServletResponse response)
                throws IOException {
            PrintWriter out = response.getWriter();
            out.println("<html>");
    		out.println("  <head>");
    		out.println("    <meta http-equiv=\"refresh\" content=\"1\" >");
    		out.println("    <title>Chat Receive</title>");
    		out.println("  </head>");
            out.println("  <body>");
            out.println("    <h2>Messages Received</h2>");
            out.println("    <ul>");
            if (ChatReceiver.messages.isEmpty()) {
                out.append("      <li><i>no messages received, yet</i></li>\n");
            }
            for (String message : ChatReceiver.messages) {
                out.append("      <li>").append(message).append("</li>\n");
            }
            out.println("    </ul>");
            out.println("  </body>");
            out.println("</html>");
        }
    }
    
  10. build the war: mvn clean verify

Deploy on your glassfish

  1. open the admin console
  2. create the connection factory jms/ConnectionFactory
    1. go to Resources/JMS Resources/Connection Factories
    2. click New...
    3. set the Pool Name ConnectionFactory
    4. set the Resource Type javax.jms.ConnectionFactory
    5. hit return
  3. create the topic Chat
    1. go to Resources/JMS Resources/Destination Resources
    2. click New...
    3. set the JNDI Name and the Physical Destination Name to Chat
    4. hit return
  4. deploy the apps
    1. go to Applications
    2. click Deploy...
    3. browse for your chat-send.war
    4. hit continue
    5. wait until the deploy is finished
    6. repeat for the chat-receive.war
  5. open the sender
  6. open the receiver