SMODL in a Contract-Last approach

Quite often it is useful to allow partners or customers exchange data with your existing, internal systems. Such existing systems may have developed and matured over time, users know and trust them, and they are in daily use in your organization. Developing a new system or changing the existing one is not an option. The solution can be to build a facade to your existing system without interfering with it in any way, offering this facade as a Web service. Exactly what this Web service should do, and how your partners or customers would prefer to use it, may be rather unclear when you start, but the understanding of this will mature while you work.

Smodl Development Suite offers the power and flexibility needed to achive this task! You may take the approach from the SMODL tutorial, defining your facade from scratch, but if you have sufficient knowledge and access to your internal systems, there is a different and possibly faster approach...

Smodl Development Suite can start with any Java class or interface and extract a SMODL model from it. Later on this model can be used as any other Web service description (contract). We refer to this development technique in creating Web services as the contract-last approach. The present tutorial follows contract-last  approach and outlines differences between this approach and the so-called contract-first approach. You will find that the steps to create the Web service using Smodl Development Suite are similar in both approaches, but kind of in reverse. You will also notice how smooth it is to apply the contract-last approach to Eclipse workflow.

Please refer to Eclipse tutorials at http://www.eclipse.org for details about how to use Eclipse in general and for downloading a copy of Eclipse (if you have not already done so). Screenshots in this document are from Eclipse version 3.4.1 "Ganymede".

We also assume that Smodl Development Suite is installed in your Eclipse environment. 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!

  1. Generate SMODL from the existing code

    First, set up a new Java project containing a package called "org.smodl.tutorial". We will create a new class called "ExistingClass" which will represent your existing application. Use the Package Explorer to open the wizard for creating new classes, referring to picture below for details, and press the "Finish" button to create the class.

    Create new class

    In the same manner, create another class called "ExistingDTO" to represent existing data structures used by your application (of-course these could be part of "ExistingClass" as well, but we'll keep them separate for now). Now, enable SMODL for the new project like described in this section of the tutorial. Your Package Explorer view should now look approximately like the picture below.

    Package Explorer

  2. Set up automatic SMODL-generation

    In the Package Explorer view, righ-click on the file "ExistingClass.java" and open the Properties page. Then navigate to the SMODL-section. Fill in values as shown in the picture below.

    Generate SMODL-file

    A file called "ExistingClass.smodl" will be generated, containing the (relatively simple) SMODL listed below.

  3. Add one method to the Java-class

    Add the following code to "ExistingClass" and observe how "ExistingClass.smodl" changes (modern Java compilers, starting with Java 5, will issue warnings about the usage of Hashtable, but this is not important for this tutorial).

  4. Fill in the rest of the code

    Now, add the following code to "ExistingDTO"

    and the following into "ExistingClass"

    Your SMODL file should now contain the definition of the structure "ExistingDTO" and also a service called "ExistingClass" containing four methods. Observe that nothing is generated from the SMODL file yet, and that the class "ExistingClass" does not implement or extend anything.

    Smodl Development Suite is not yet able to trace all Java classes which contributes to the model, and isolated changes to "ExistingDTO.java" do not automatically regenerate the SMODL-file. This is because only "ExistingClass.java" is considered to be the source of the SMODL model and consequently only changes to this file trigger regeneration. Do a full rebuild of the project to work around this issue.

  5. Run the service

    Referring to this section in the tutorial, go to the Package View, right click on "ExistingClass.java" and choose "Run As" (or "Debug As") then "Standalone SMODL service".

    Launch configuration

    An Eclipse launch-configuration looking approximately like the picture above should appear. Change the default name to something sensible, then click on the "Find Smodl Model" button and locate the generated SMODL file ("ExistingClass.smodl"). Finally, press the "Run" (or "Debug") button in order to start up the service in the standalone Http-server.

  6. Create a client

    From the Package Explorer view, create the package "org.smodl.tutorial.client" to hold client-related code. Open the property page for "ExistingClass.smodl" and choose the "Java Module" tab. Select the checkbox "Generate client factory".

    Note that the "Generate interface" checkbox is automatically selected when you request a client factory. This generated interface is meant to be used on the client – your existing application running on the server side is not affected. Note also that "Target Path for client code" is set to "src" in order to keep things simple in this tutorial, but in a real project it may make sense to keep client-code in a separate source-directory.

    Fill in all details as shown in the picture below, then close the property page by pushing the "Ok" button. As these steps are similar to this section of the tutorial, please refer to it for more details.

    Launch configuration

    Use the Package Explorer view to create the class org.smodl.tutorial.client.ExistingClassClient then copy the code below and paste into the class.

    Run the client by right-clicking on org.smodl.tutorial.client.ExistingClassClient in the Package Explorer view and choose "Run As" (or "Debug As") "Java Application".

  7. Summing up differences

    In the contract-last approach, the SMODL file is generated from an existing class (or interface). This class is not required to extend or implement anything, meaning that any class can be used in this approach. Code which is generated by Smodl Development Suite in the contract-last approach is meant to be used by client applications. Smodl Development Suite keeps the SMODL model in sync with any changes made to the source class (or interface). Manual changes to the model will be overwritten until you disable automatic SMODL generation.

    Running the service in the contract-last approach require you to identify both the target implementation (class implementing the service) and the SMODL model describing the service. The runtime engine will complain if these are incompatible.

    Code generated by Smodl Development Suite does not currently contain Java primitive types, but rather their class-counterparts (i.e. this code will never contain the primitive type int, but rather Integer). This means that if you generate SMODL from an existing class which uses primitive types, and then you generate client-code from the SMODL model, this client code will have the primitive types replaced by their class-counterparts. Compare, for instance, the input parameter for the method findSubscriptionByNumber() in ExistingClass.java, ExistingClass.smodl and ExistingClassInterface.java. This does not represent a problem, but may seem confusing at first glance.