IJC Plugin tutorial - MySCServer webapp

    Overview

    In this tutorial we will show how to create a RESTful webservice that processes molecules sent to it from clients and returns results back the clients. The MySCServer is a standard Java EE web application that can be deployed into any servlet container like Apache Tomcat 6.x, which we will use. We will use again NetBeans IDE for developing the webservice and deploying it to Tomcat webserver.

    This tutorial assumes that you have NetBeans IDE 6.9.1 installed on your computer as well as Apache Tomcat 6.x webserver, which is bundled with the NetBeans IDE installation. If you followed IJC Plugin: Quick Start tutorial you should have both NetBeans IDE and Apache Tomcat already installed.

    Contents

    Creating MySCServer Web Application project

    Let's start with creating the MySCServer project in NetBeans IDE. It's an ordinary java web application project that we will use for implementing and deploying a web service.

    1. In NetBeans IDE go to the main menu and choose 'File' -> 'New Project...'. This will start the 'New Project' wizard. As a project type choose 'Web Application' in the category 'Java Web' and click 'Next' button.

    images/download/attachments/1802796/create-server-project-1.png
    Create server Web Application - choose 'Web Application' project type in 'Java Web' category

    1. Enter the project name and its location. As the project name enter 'MySCServer' and click 'Next' button.

    images/download/attachments/1802796/create-server-project-2.png
    Create server Web Application - enter the project name and location

    1. Choose the webserver to use for the project. The Apache Tomcat 6.x server should already be defined in your IDE. If it is not, create a new one by clicking the 'Add...' button.

    The `'Java EE'` version should be set to `'Java EE 5'` and the `'Context Path'` to `/MySCServer`.
    <img src="images/download/attachments/1802796/create-server-project-3.png" alt="images/download/attachments/1802796/create-server-project-3.png"/>
    Create server Web Application - selecting the web server

    1. The last panel let's you to add several webapp development frameworks to your project. We don't need any of those, because our project will only contain a webservice. You can just click 'Finish' at this panel.

    images/download/attachments/1802796/create-server-project-4.png
    Create server Web Application - do not add any webapp development frameworks

    1. The IDE will create the new MySCServer project, which should look like the one on the screenshot below.

    images/download/attachments/1802796/server-project-in-projects-explorer.png
    MySCServer Web Application project in IDE's 'Projects' explorer
    <a name="src-1802796-ijcplugintutorial-myscserverwebapp-setup-libraries"></a>

    Setting up libraries

    As a next step we will setup libraries needed by the webservice. This is going to be slightly different from what you are used to when setting up IJC plugin libraries. But we are not developing an IJC plugin here!

    The webservice needs two libraries - it needs parts of MarvinBeans library from Chemaxon to perform operations on the chemical structures sent by webservice clients and it also needs Jersey Multipartextension in order to receive and send complex data.

    Both libraries can either be downloaded from the internet or directly from this tutorial. When downloading from the internet, please, go to Chemaxon's download page and download Marvin Beans for Java Developers. Jersey Multipart is comprised from two jars that can be downloaded from these links - jersey-multipart-2.2.jar and mimepull-1.4.jar. For your convenience the jars from both libraries were packaged to a single zip file, which you can download from here.

    1. If you have downloaded the libraries follow these steps to add them to your MySCServer project. First create folders that will store the library jars.

    In your NetBeans IDE go to the main menu and click `'Window' -> 'Files'`, this will take you to the `'Files'` explorer where you can see directly the files and folders comprising MySCServer project.
    
    In the 'Files' explorer r-click the `MySCServer` folder and choose `'New' -> 'Folder...'`. This will start the `'New Folder'` wizard, which we will use for creating `lib/MarvinBeans` folders as it is shown on the picture below.
    <img src="images/download/attachments/1802796/create-lib-MarvinBeans-folder.png" alt="images/download/attachments/1802796/create-lib-MarvinBeans-folder.png"/>
    'New Folder' wizard - creating `lib/MarvinBeans` folderSimilarly, r-click the `lib` folder's node, choose `'New' -> 'Folder...'` and create `jersey-multipart` subfolder.

    1. Copy the following jars to lib/MarvinBeans folder: MarvinBeans-concurrent.jar, MarvinBeans-diverse-modules.jar, MarvinBeans-formats.jar, MarvinBeans-formats.mdl.jar, MarvinBeans.jar,MarvinBeans-license.jar, MarvinBeans-plugin.jar.

    1. Copy the following jars to lib/jersey-multipart folder: jersey-multipart-1.1.5.1.jar, mimepull-1.4.jar.

    The library folders structure should look like this now.
    <img src="images/download/attachments/1802796/libraries-in-files-explorer.png" alt="images/download/attachments/1802796/libraries-in-files-explorer.png"/>
    The `lib` folder structure with library jars

    1. In NetBeans IDE go back to 'Projects' explorer and r-click the MySCServer's project node. Navigate to 'Properties' -> 'Libraries' -> 'Compile' to see the list of compile-time libraries. Then click'Add JAR/Folder' button. In the 'Add JAR/Folder' dialog select all MarvinBeans jars first. Make sure that the jars are added using the 'Relative Path' and click 'OK'.

    images/download/attachments/1802796/adding-MarvinBeans-jars.png
    Setting up MySCServer libraries - adding MarvinBeans jars

    1. Repeat the process and add Jersey Multipart jars as well.

    images/download/attachments/1802796/adding-jersey-multipart-jars.png
    Setting up MySCServer libraries - adding Jersey Multipart jars

    1. Close the MySCServer properties dialog by clicking 'OK'. The libraries are now set up and we can start creating the webservice.

    Creating RESTful webservice

    Creating a RESTful webservice in NetBeans IDE is fairly simple process where most of the work is done by the IDE's wizard. We only have to supply a few bits of key information to the wizard, which will then generate all necessary files and even update the webapp project with required libraries, etc.

    1. First, we have to create a java package for our webservice implementation files. The web application project by default comes with no java packages. Please r-click the 'Source Packages' node in'Projects' explorer and choose 'New' -> 'Java Package...'. In the wizard panel enter org.myorg.myscserver as the package name and click 'Finish'.

    images/download/attachments/1802796/create-java-package.png
    New Java Package wizard - creating `org.myorg.myscserver` java package

    1. Now, r-click the created package node and choose 'New' -> 'RESTful Web Services from Patterns...' or choose 'New' -> 'Other...' if the 'New' submenu does not offer the link to creating RESTful webservice.

    images/download/attachments/1802796/create-webservice-wizard-1.png
    New RESTful Web Services from Patterns wizard - choosing the right wizard type

    1. On the next panel choose 'Simple Root Resource' webservice pattern and click 'Next'.

    images/download/attachments/1802796/create-webservice-wizard-2.png
    New RESTful Web Services from Patterns wizard - choosing webservice pattern

    1. The next panel lets you specify your webservice details. In particular we are interested in setting 'Path' and 'Class Name' values. Enter validator in the 'Path' text box andStructureValidatorService in the 'Class Name' text box.

    Leave default values in the rest of the boxes and click `'Finish'`.
    <img src="images/download/attachments/1802796/create-webservice-wizard-3.png" alt="images/download/attachments/1802796/create-webservice-wizard-3.png"/>
    New RESTful Web Services from Patterns wizard - entering `'Path'` and `'Class Name'` values

    1. As part of the webservice creation process NetBeans IDE may need to update your MySCServer project configuration and create a REST servlet adaptor for accepting incoming requests. Let it do so using the default values. The IDE will update your web.xml and also add JAX-RS 1.1 library, which is the RESTful webservices API and its reference implementation in Jersey 1.1 (JAX-RS RI) library.

    images/download/attachments/1802796/create-webservice-wizard-4.png
    New RESTful Web Services from Patterns wizard - updating MySCServer project configuration to support RESTful webservices

    1. When the wizard creates the webservice and updates your MySCServer project the project's web.xml configuration file should look like this.

    [web.xml](https://dl.chemaxon.com/instantjchem/ijc_latest/docs/developer/api/examples/structure-checker-server/web.xml.1.html) configuration fileAnd there should be `StructureValidatorService` class in `org.myorg.myscserver` package.
    <a name="src-1802796-ijcplugintutorial-myscserverwebapp-implement-webservice"></a>

    Coding the webservice

    1. Go to 'Projects' explorer and open the StructureValidatorService class in the editor. It contains a skeleton of a webservice generated by the wizard. Replace the generated code with the following:

    [StructureValidatorService.java](https://dl.chemaxon.com/instantjchem/ijc_latest/docs/developer/api/examples/structure-checker-server/StructureValidatorService.java.1.html) source file

    1. The StructureValidatorService class makes use of ErrorBuilder class. We have to create this class alongside StructureValidatorService class. You should now be familiar with NetBeans IDE and be able to do so in several ways.

    Make your `ErrorBuilder` class contain the following code:
    
    [ErrorBuilder.java](https://dl.chemaxon.com/instantjchem/ijc_latest/docs/developer/api/examples/structure-checker-server/ErrorBuilder.java.1.html) source file
    <a name="src-1802796-ijcplugintutorial-myscserverwebapp-build-and-run"></a>

    Building and running the webapp

    The project should be ready to compile and deploy to the web server (eg. Apache Tomcat 6.x in our case). You can do so by r-clicking the project's node in 'Projects' explorer and choosing 'Clean and Build'. In order to run the project choose 'Run' from the same popup menu. The IDE will start Apache Tomcat webserver, deploy the project to it and then use your default web browser to show index.jsp from the deployed project. This is a simple Hello World page.

    Conclusion

    Congratulations, you have successfully created an implementation of a RESTful web service capable of processing chemical structures and sending results back to it clients. In this tutorial you have learned:

    • How to create a web application project in NetBeans IDE

    • How to create add library jars to the project

    • How to create create a RESTful webservice

    • How to run and deploy the web application project

    For other IJC plugin development related tutorials please see their complete list here.