QServlet

QServlet is a JMS message producer that runs inside a Java Servlet engine, such as Tomcat. It accepts HTTP requests and converts them into JMS messages. The new JMS messages will be put into the internal XQueue of root as requests. Upon it receives the response back, the response will be formatted via the specific JSP and the result will be sent back the client. Therefore, it is the web front end of a message flow. Please be aware that QServlet is not an implementation of MessageReceiver. Therefore, it can not be used as a MessageReceiver in a normal message flow. It can be used only inside a Java Servlet engine.

Since it is a Servlet, its configuration contains two parts. The first part is the web.xml of the webapp for the servlet container. The second part is the configuration files for the message flow. Here we will focus on its first part and how it interprets the HTTP requests.

Here are the list of properties to define the servlet in web.xml.
Property Name Data Type Parent Block Requirement Description Examples
servlet-name string servlet required name of the servlet rest
servlet-class string servlet required full path of the classname for the servlet org.qbroker.flow.QServlet
ConfigFile string init-param required full path of the master configuration file for the flow /opt/qbroker/flow/ID/Flow.json
LoggerName string init-param required name of the log file for the flow QFlow_ID
RestURI string init-param optional the path for the REST requests /id
HeaderRegex string init-param optional the regex for selecting HTTP headers to be copied over to message .+
Timeout string init-param optional number of seconds to wait for the response back from the flow 600
servlet-name string servlet-mapping required name of the servlet for the mapping rest
url-pattern string servlet-mapping required the pattern for the mapping /rest/*
where RestURI is only optional.

QServlet interprets the HTTP requests based on either the request type or the end point. For fileupload, the request will be multipart. If the content type is either "text/xml" or "application/json", the request will be processed as either the raw xml or raw json. In this case, the payload will be saved as the message body. The query parameters will be saved as the message properties. If HeaserRegex is defined, it will be used to select HTTP headers to copy over as the properties. Additionally, the IP of the request will be saved as the property of "_clientIP" and the request path info will be saved as JMSType.

Other than the raw requests, QServlet interprets the requests based on the end points. If RestURI is defined in web.xml, all the requests with the end points starting with the RestURI will be treated as REST requests. For REST requests, the query parameters will be saved as the message properties except for the parameter with the name of "text". The value of "text" will be saved as the message body. Additionally, the IP of the request client will be saved to the property of "_clientIP". The request path info will also be saved to JMSType.

Apart from the end ponit starting with the RestURI, QServlet also supports other end points for various interpretations. Here is the list of them:
End Point Interpretation Description
/collectible EventPostable jms events for collectibles
/jms EventPostable jms event not for collectibles
/event EventPostable non-jms event
/json JSON json form data for post only
/xml XML xml form data for post only
/stream byte stream jms event for stream operations
where EventPostable is a special serialization for QBroker Event. In case of the end point is either /json or /xml for post, the data at the key of either "json" or "xml" will be saved as the message body. The request path info will be saved to the message property of "path". The client IP will be saved to the property of "hostname". The content type will be saved to the property of "type".

For the end point not in the above table, the request will be treated as ad hoc request.

Here is an example of web.xml: 
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">
<web-app>
  <display-name>IdService</display-name>
  <context-param>
    <param-name>webAppRootKey</param-name>
    <param-value>id.root</param-value>
  </context-param>
  <servlet>
    <servlet-name>rest</servlet-name>
    <servlet-class>org.qbroker.flow.QServlet</servlet-class>
    <init-param>
      <param-name>ConfigFile</param-name>
      <param-value>/opt/qbroker/flow/ID/Flow.json</param-value>
    </init-param>
    <init-param>
      <param-name>LoggerName</param-name>
      <param-value>QFlow_ID</param-value>
    </init-param>
    <init-param>
      <param-name>RestURI</param-name>
      <param-value>/id</param-value>
    </init-param>
    <init-param>
      <param-name>Timeout</param-name>
      <param-value>600</param-value>
    </init-param>
    <load-on-startup>10</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>rest</servlet-name>
    <url-pattern>/rest/*</url-pattern>
  </servlet-mapping>
</web-app>