Deployment of SMODL Web Service in an application container

This short tutorial provides general information about SMODL service deployment in an application container. In the tutorial we use Apache Tomcat as an application container but any other application server can be used instead of Tomcat. For a short SMODL description see SMODL Tutorial.

Preliminaries

In order to get the most of this tutorial, the reader shall be familiar with the basics of web application development.

Software requirements

General Deployment Process

Overview

the following provides a short checklist of steps that you need to take to deploy a SMODL service in a servlet container.

1. Create web application.
2. Add all necessary libraries.
3. Add the SMODL file to your application.
4. Add the SMODL service implementation to your application.
5. Create web.xml file for the web application.

These items are discussed in more detail in the sections that follow.

1. Create web application

   Basically you create web application by creating corresponding directory structure under the webapp directory inside the Tomcat installation. For reference or if you are not familiar with web application concept see Tomcat Application Developer's Guide.

2. Add all necessary libraries

   To add libraries you just need to copy the corresponding jar files into the WEB-INF/lib directory of your web application. Please make sure that the following libraries are added:

   1. SMODL model com.runitsoft.smodl.model_x.x.x.jar – where x.x.x is the version of the library
   2. SMODL runtime com.runitsoft.smodl.javaruntime_x.x.x.jar – where x.x.x is the version of the library
   3. Xml pull parser xpp3-min-x.x.x.x.x.jar – where x.x.x.x.x is the version of the library
   4. SAAJ libraries saaj-api.jar and saaj-impl.jar
   5. Java Activation Framework activation.jar required by SAAJ
   6. All other libraries that may be needed by the SMODL service implementation

3. Add the SMODL file to the web application

   The SMODL file is a file containing SMODL service definition. For this tutorial the SMODL service is just a simple employee registry that provides basic operations to manipulate with employee objects: delete, create, update, retrieve.

   
   
   

   The syntax of the SMODL language is human-readable and can be easily understood. For more details about SMODL language and the example see SMODL Tutorial. The SMODL file can be placed anywhere inside the web application directory structure. You will need the path to this file to configure the SMODL service servlet.

4. Add the SMODL service implementation to your application

   Your SMODL service implementation may or may not implement an interface corresponding to SMODL service definition. In case one chooses to implement the interface, an Eclipse IDE can do the work as described here and here. An alternative solution is to generate the interface from the command line. It is important to note though, that the implementation of the interface must define methods and types that correspond to methods and types defined in the SMODL service definition.

   The runtime engine during its initialization will check that all SMODL elements are mapped to the corresponding Java elements. The implementation of the SMODL service we described above may look like the following.

   
   
   

   In the code fragment the SMODL service implements the interface that was generated from the SMODL service definition.

   If your SMODL service implementation is packed into a jar file then you can add it to the web application by the same way you added libraries. If you have just compiled classes then you have to copy them into the WEB-INF/classes directory of the web application. The SMODL service servlet that we will use in this tutorial supports implementations that can be instantiated with zero-parameters constructor. If your SMODL implementation requires more sophisticated instantiation, for example it needs Spring container, then you can extend the com.runitsoft.mservlet.SmodlHttpServlet servlet and redefine the getImplementation() method that returns the implementation object.

5. Create web.xml file for the web application

   The web.xml file for SMODL service web application may contain only the SMODL service servlet definition.The Java class for this servlet will be com.runitsoft.mservlet.SmodlHttpServlet. It serves as a front door for your SMODL service. The servlet retrieves requests and passes them to the runtime that does the rest of the job. To properly initialize the runtime the SMODL servlet needs the SMODL file and the object that implements the SMODL service. The path to the SMODL file is specified as the smodlFileName init-param for the servlet. If the SMODL service implementation implements a SMODL service interface generated from the SMODL file then the SMODL file name parameter can be omitted since the runtime is able to use the SMODL definition from the SMODL service interface. The servlet instantiates the implementation object using the class name provided as the implementationClassName init-param. This parameter is mandatory. Here you can see an example of web.xml file for the SMODL service we used above as an example.

   <?xml version="1.0" encoding="ISO-8859-1"?>
   <web-app 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"
   	version="2.5">
   <servlet>
   	<servlet-name>epmloyeeRegistryServlet</servlet-name>
   	<servlet-class>com.runitsoft.mservlet.SmodlHttpServlet</servlet-class>
   	<init-param>
   		<param-name>implementationClassName</param-name>
   		<param-value>org.smodl.tutorial.impl.CrudImpl</param-value>
   	</init-param>
   	<init-param>
   		<param-name>smodlFileName</param-name>
   		<param-value>Crud.smodl</param-value>
   	</init-param>
   </servlet>
   <servlet-mapping>
   	<servlet-name>employeeRegistryServlet</servlet-name>
   	<url-pattern>/employeeRegistry/*</url-pattern>
   </servlet-mapping>
   </web-app>
   

   Now you can start your web application. If your servlet container is running on the port 8080 the service can be accessed via the following urls:
   http://localhost:8080/<your application context>/employeeRegistry/SOAP for SOAP style of calls
   http://localhost:8080/<your application context>/employeeRegistry/XML-RPC for XML-RPC style of calls
   http://localhost:8080/<your application context>/employeeRegistry/JSON for JSON-RPC style of calls
   

   To get WSDL for the SMODL service you can use the following url:
   http://localhost:8080/<your application context>/employeeRegistry/SOAP?wsdl

   See SMODL tutorial to create a client.