Building SMODL Service in Eclipse

Overview

This tutorial is the first of two articles on SMODL services. In this part we will guide the reader through the SMODL service development process. In the next article our simple service will grow into a user-profile registry which requires a session management and a role validation. Test service implementation is available online.

The series takes an example-based approach to describe advantages of Smodl Development Suite. We rely on the Eclipse IDE for Java EE Developers for its support for most popular application servers and its ability to deploy projects to servers directly from within the IDE and last but not the least – for its public license.

Prerequisites

You will need the following software to build the project:

• Eclipse IDE for Java EE Developers package. The download package and installation instructions can be found on Eclipse web site. Screenshots in this document are from Eclipse JEE "Galileo" edition.

• Tomcat 6.0, available from Apache Tomcat web site. This tutorial was written using version 6.0.18.

• JRE 6.0, available from Sun.

• Smodl Development Suite, please visit this page for installation instructions. Screenshots in this tutorial may be from slightly different versions of Smodl Development Suite but should all be relevant for the latest version. If this is not the case, please contact us and let us know!

  What is SMODL Service?

  All throughout this tutorial by "service" we mean a SMODL service. A SMODL service is a Web service which in addition to SOAP also includes JSON-RPC and XML-RPC bindings. Another advantage of the SMODL service is its ability to provide secure, role-based access. We will have a closer look at role-based validation in the second article of the series.

  Step-By-Step Development Process

  In this tutorial we show step-by-step how to build a very simple service that receives user credentials: login and password, and replies with boolean true/false to alert method call output back to the caller.

  1. Creating a Web Project

     We shall now create a dynamic Web project. Please make sure the Java EE Perspective is the active perspective. Start from main menu: File -> New -> Dynamic Web Project.

     

     The next step is to add an application Tomcat server. Note that Tomcat is not a part of Eclipse therefore you should install it first as suggested here. Then, click on the "New" button in the "Target runtime" section and follow the screenshot instructions.

     

     

     Once you finish configuring the Target Runtime you get back to the Dynamic Web Project creation wizard. There is no need to change the structure of Java folders, just click "Next". On the Web Module screen enable checkbox "Generate web.xml deployment descriptor" and complete the wizard by pressing the "Finish" button.

     

     Now add "Smodl Nature" to the project. Please consult with our "SMODL Tutorial" for the detailed instructions.

     Notice that as of Smodl Development Suite v. 1.3 all "Dynamic Web Projects" must "Add SMODL Web Deployment" when it is planned to use "SmodlHttpServlet" to deploy SMODL Service. See the image below.

     

     Then, open the property-page for the project, select Java EE Module Dependencies pane and add both SMODL Library and SMODL Web Library as Web Library dependency (see the images below).

     The pane "Java EE Module Dependencies" was renamed in Eclipse 3.6/Helios to "Deployment Assembly".

     

  2. Setting up a SMODL File

     Add a package named "org.smodl.tutorial.service" under the "Java Resources" folder.

     

     You will now create a file called "service.smodl" as a part of the "org.smodl.tutorial.service" package. The SMODL file contains the SMODL model describing the service. For the sake of simplicity the service provides only one method that acknowledges receiving of user credentials. Paste in the XML listed below to the SMODL file.

     
     

  3. Generating a Java Interface for the Service

     Now, we generate a Java-interface for the service:

     • open the property-page for the file service.smodl,
     • choose the SMODL pane and select the "Java Module" tab,
     • check the box "Generate interface" (see the picture below).

     

     You can refer to the SMODL tutorial, section 3 for more details.

  4. Implementing the Service

     Now, we implement the IRepositoryService-interface. Here is the list to follow:

     • select the "org.smodl.tutorial.service" package,
     • add a new class called "RepositoryServiceImpl" and make it implement the IRepositoryService-interface,
     • set the "Inherited abstract methods" checkbox (see the image below).

     

     Paste the following code into the "RepositoryServiceImpl.java" – the newly generated class. For simplicity we store profiles of registered customers in a "Hashtable", then we serialize the "Hashtable" down to the disk for persistency. Note, that in a real-life scenario, a database would have to be used as a persistent storage.

     Make sure that "IRepositoryService.Profile" class implements "java.io.Serializable" interface and it includes a universal version identifier – the "serialVersionUID" field. You should also make sure that the "loginUser" method of the "IRepositoryService" interface is declared as the one that throws "Exception". This requirement is conditioned by implementation logic.

  5. SmodlHttpServlet as an Application Container (optional reading)

     As an application container we suggest to extend a "SmodlHttpServlet" rather than the standard Java "HttpServlet". This is because our servlet implements an "ISmodlServerRuntime" interface which represents the SMODL runtime engine. As any other runtime engine, the SMODL engine must be running in order for the SMODL service to execute. For successful initialization of the runtime the following sequence should occur in the servlet:

     • The servlet binds the runtime with a SMODL service implementation by calling a corresponding method of the "ISmodlServerRuntime" interface

       ISmodlServerRuntime.setImplementation (Object implementation);

     • Then it provides the runtime with a SMODL definition. During the initialization the runtime manager first looks up for the SMODL definition constant – _SMODL_DEFINITION – in the service implementation class. If the implementation is generated by Smodl Development Suite then the constant is set by default. An alternative approach to provide the runtime with the SMODL definition is by calling

       ISmodlServerRuntime.setSmodlXml (String smodl);

     • Finally, the servlet calls the init() method

       ISmodlServerRuntime.init ();

     • It is worth while to mention that the "SmodlHttpServlet" calls service methods via

       ISmodlServerRuntime.invoke (SmodlProtocol protocol, byte[] input);

       where the protocol can be either SOAP, JSON or XML-RPC. The input parameter represents the actual service method call as received from a service client. This is the task of the "SmodlHttpServlet" to extract a payload from the HTTP-request and to pass it on as an input parameter to the invoke() method.

     For information about Cross-Origin Resource Sharing (CORS) and a custom HTTP-headers usage example please consult our AJAX tutorial.

  6. Servlet Implementation

     We will now add an application container to the project. Right click on the "org.smodl.tutorial.service" package (under the "Java Resources" folder), select New –> Servlet and fill in the fields in a servlet generation wizard.

     

     Enter the following information which will be automatically added by Eclipse to a servlet descriptor located in a "/WebContent/WEB_INF/web.xml" file.

     

     In some cases the servlet may be required to serve cross-origin requests made from JavaScript. In such a case cross-origin support must be activated for the servlet. Set the "smodlAllowCors" property to "true" in order to achieve it. Click "Next".

     Specify which interfaces and inherited methods the servlet shall implement.

     

     Verify that you have the following content in an XML-file called "/WebContent/WEB_INF/web.xml" and in a Java file called "RepositoryServiceServlet":

     The actual implementation of the servlet can be copied from the listing below.

     Notice that the "SmodlHttpServlet.doPost" method call commits HTTP-response. Which means that whenever the "SmodlHttpServlet.doPost" is called, addition of HTTP-headers become unfeasible. If some extra headers must be set they should be added prior calling the "SmodlHttpServlet.doPost".

  7. Run the Service in Tomcat

     In Java EE perspective of the "RepositoryWeb" project open "Servers" tab, right click on "Tomcat Server" and select "Add and Remove...". The image below can help you out.

     

     Now move the "RepositoryServiceWeb" resource to the server: select the resource and click on the "Add" button.

     

     Right click on the "Tomcat Server" again and select the "Start" option from the popup window.

  8. Validate Service Deployment

     To verify that the service is up and running you can retrieve service contract file – the SMODL model – using the following URL:

     http://localhost:8080/RepositoryServiceWeb/service/JSON?smodl

     Alternatively, you can obtain the WSDL describing the service and its SOAP binding from the following URL:

     http://localhost:8080/RepositoryServiceWeb/service/SOAP?wsdl

  9. Accessing Service in a Browser

     If you need assistance in building an AJAX client that uses the service please look into our AJAX tutorial. For help in adding service security you can consult with our Session Management and Role Validation Tutorial.