EXTEND: ADOxxWEB API

(Details - Use - Extend)

In this section we describe the steps to set up the ADOxxWEB API, in order to access the ADOxx data base and execute write and read AdoScript Commands that are defined in the ADOxxWEB API.

1. Setup of Development Environment

The proposed development environment consists of the following tools and technologies:

• Eclipse IDE for Java EE Developer: As an integrated development environment, we propose to use the Eclipse EE environment. Necessary plugins are listed as technologies below. The version used for this documentation is "Mars."
• Java: As the baseline technology for realizing the building block. The tested/used version is Java JDK 7.
• SVN: The source code of this building block is maintained in the ADOxx.org SVN Repository. Make sure to have the SVN plugin for Eclipse installed to check-out and commit directly from within your IDE.

As a prerequesite to get started, make sure to have the Eclipse IDE up and running and the necessary connectors/plugins for SVN installed. 

2. Check-out ADOxxWEB API projects from SVN

i) For the stabilization of the ADOxxWeb service, which is the software component that executes AdoScipts, one needs the LBRS/RAM component. This component consists of two web application projects.
- https://www.adoxx.org/svn/devtools/2 ADOxx Building Blocks/2 ADOxxWEB API/LBRSWS
- https://www.adoxx.org/svn/devtools/2 ADOxx Building Blocks/2 ADOxxWEB API/RemoteADOWSMonitor

ii) ADOxxWEB API: On top of the LBRS/RAM component, we have a functional implementation of a generic API, this API enables interaction with the web-services in Java for the development of business logic. The API is implemented generically, meaning that it works with any library. Further extensions are possible to wrap method/modelling tool specific functionality on this level. Currently, two different interaction protocols for the development of web applications are supported, SOAP and ReST.

- The ADOxxWeb API is a web application that communicates with the LBRS/RAM component in order to execute commands and retrive information. This web application is a Maven project and has dependencies to three other projects (see below) and can be downloaded at the following link:
https://www.adoxx.org/svn/devtools/2 ADOxx Building Blocks/2 ADOxxWEB API/ADOxxWeb API

- The Data Access Object: This component is for communication between the LBRS and the execution commands, for instance to write and read commands.
https://www.adoxx.org/svn/devtools/2 ADOxx Building Blocks/2 ADOxxWEB API/ADOxxWeb DAO Service

- The ADOxxWEB Read Service project contains the read commands that are used in the ADOxxWeb interface project.
https://www.adoxx.org/svn/devtools/2 ADOxx Building Blocks/2 ADOxxWEB API/ADOxxWeb Read Service

- The ADOxxWEB Write Service project contains the write commands that are used in the ADOxxWeb interface project.
https://www.adoxx.org/svn/devtools/2 ADOxx Building Blocks/2 ADOxxWEB API/ADOxxWeb Write Service

A. Right-click in the project explorer, select "Import" -> "Import project from SVN"

B. Enter the URL of the project (as listed above). Since the ADOxx.org SVN is public, no username or password is needed.

C. Click on Next and Finish to trigger the checkout (in the next steps you can configure the name of the project in Eclipse. In case you want to update, please use the respective wizard steps).

Repeat steps A-C for the other projects. All projects needs to be available locally, as there is a dependency (in Maven) between the Webapp and the other projects.

3. Configure LBRS/RAM component and Run on Server

The 'Load Balancer and Restart Service' (LBRS) and the 'Remote ADOWS Monitor' (RAM) in combination are an apllication that runs between a web application and the ADOWS instances. Its functionality is to give these ADOWS instances more stability and therefore the availibilty of the ADOWS to a web application. This is achieved through the watcher functionality that monitors all aspects of the operations of the ADOWS, restarting when necessary any stalled or non-functioning ADOWS instances.

The periodicity of these checks are dependent on the configuration of the LBRS web-service.

ADOWS.zip

B. LBRS settings configuration:

      In the //LBRS/WebContent/conf/LBRSConfiguration.xml file the following settings for the MainLBRAS and the VirtualLBRS can be customized.

      (i) MainLBRS
The MainLBRS has a queue where all of the tasks sent to the LBRS are initially stored. Each task waits in this queue until a VirtualLBRS picks it up. The MainLBRS has a watcher service to check on the queue and to discard tasks whose wait time has elapsed. It uses the RAM to start, monitor and stop ADOWS instances on request.

      (ii) VirtualLBRS
Each VirtualLBRS must have a section within the LBRSConfiguration.xml file. Each section has the following nodes:

      (iii) ADOWSLogin
- ADOWSLoginname:The name given to the ADOWS instance, used in logging. This must be unique.
- Port: The port number that the ADOWS instance will be listening on for tasks passed to it via the VirtualLBRS task queue.
- Host: The host of the RAM and the ADOWS instance. This can only be the "localhost" for LBRS installations where the LBRS/RAM/ADOWS are all running on the same machine, otherwise this should be the machine name of the RAM/ADOWS target.
- Username: The user login name for the ADOWS instance. This must be unique for each ADOWS instance.
- Password: The encrypted password for the ADOWS instance. An invalid password will cause the ADOWS instance never to start. You can download the password encrypting tool to encrypt the passwords here.
- Executable: The full path to the executable to run for the ADOWS instance. Note that this must be the path on the machine that the ADOWS and RAM will be running on. It is checked for existence at start up and on change of configuration.
- portSwitch: Allows for the set up of the port switch to be sent to the awssrv.exe. Two switches should be specified for an ADOWS instance.
   The first is the –autokick switch which allows the RAM to start the ADOWS instance regardless of whether the user is already logged in.
The second need switch is the –s switch followed by the database type, i.e. –sSQLServer.
If any of these switches are missed or invalid, the RAM will enter a never ending circle of creation and destruction of the ADOWS instance.
For debugging and fault tracing, there are two additional switches that are useful: These are –wslogfile and -log_no_dialogs. They both expect a valid file path where the output will be placed.
- RAMPort: This is the port that the RAM will be listening in on the remote machine. It is used by the LBRS to talk to the RAM. It is the port that the RAM is running on in Tomcat.
- adowsInitialisationTime: This gives the amount of time that the ADOWS instance needs to be ready to receive tasks. 

C. Create a New Tomcat Server: "File" -> "New" -> "Server"

D. Add the LBRSWS & RAM web applications to the server

Right-click on the server, which is created in the previous step, and select 'Add and Remove ...'. Select LBRSWS and RemoteADOWSMonitor and add them to the server.

E. Right-click on server -> 'Start'

The web applications are deployed on the server and the LBRSWS is accessible at: http://localhost:8080/LBRSWS

4. Deploy ADOxxWEB API

A. Create a Apache Tomcat server

In order to create a server for the 'ADOxxWEB Interface' web application, please perform step 3.C again.

B. Change port number of the server

Since the port 8080 is already used by the LBRS/RAM server, we have to set a new port number for the server where 'ADOxxWEB Interface' will run on. For this purpose, please double click on the server which was created in the previous step, and change the port number (e.g. to 8180) in the 'Ports' area.

C. Run ADOxxWEB Interface on the server

In order to run the ADOxxWEB Interface on the server we have created in step 4.A please perform steps 3.D and 3.E.

The services that should be available for the interface can be defined in the /src/main/webapp/WEB-INF/context.xml. Within this file you can call the pre-implemented read and write commands as beans and assign them to 'jaxws' (SOAP) or 'jaxrs' (ReST). 

As an initial case to familarize yourself with the extension possibilities for this building block, this example shows you how to add a new AdoScript command into the ModelRead wsdl which already exists in the above imported project.

EXAMPLE: Implement your own 'ModelRead' Command

1. Create a new command

A. Go to the ADOxxWEB Read Service 

B. Open 'src/main/java/org/adoxx/basis/read/ModelReadImpl.java'

C. Copy/paste the following code into the 'ModelRead' class

public String getModelBasename(String modelid) {
    StringBuffer script = new StringBuffer();
    script.append("CC \"Core\" GET_MODEL_BASENAME modelid:(" + modelid + ")\r\n");
    script.append("SET " + RESULTVAR + ":(basename)");
    return daoService.execute(script.toString(), RESULTVAR);
}

2. Add the command into the 'ModelRead'-wsdl

A. Open 'src/main/java/org/adoxx/basis/read/ModelRead.java'

B. Add the above command into the ModelRead interface by copy/paste the following code

public @WebResult(name = "basename") String getModelBasename(@WebParam(name = "modelid") String modelid);

Result:

In the following we are going to implement our own WSDL. This example will be a read function (for the write commands it is equivalent). 

1. Create a public java class in 'src/main/java/org/adoxx/basis/read' package.

A. Rright-click the package -> 'New' -> 'Class'

B. Enter New name -> 'Finish'

2. Create an interface in the 'src/main/java/org/adoxx/basis/read' package

3.  Configure 'MyFirstReadImpl.java' file

A. Assign the interface created in step 2:
@WebService(endpointInterface = "org.adoxx.basis.read.MyFirstRead")

B. Extend the class by the 'ReadUtils.java'. The ReadUtils define the result value and type of the functionalities return.
public class MyFirstReadImpl extends ReadUtils {

C. Add the ChaeManager into the class.
private CacheManager cacheMgr;

D. Define a String class within the MyFirstImpl class with input parameters. The String class represents character strings. All string literals in Java programs, such as "abc", are implemented as instances of this class. 

public String getModelBasename(String modelid) {
   /**
   * Define a String Buffer. 
   * The String Buffer allows you to edit your string by predefined methods.
   */
   StringBuffer script = new StringBuffer();

   /**
   * Add your AdoScript 
   * every line of your code is added by the StringBuffer method 'append' 
   */
   script.append("CC \"Core\" GET_MODEL_BASENAME modelid:(" + modelid + ")\r\n");
   script.append("SET " + RESULTVAR + ":(basename)");

   /**
   * Execute and return the output.
   */
   return daoService.execute(script.toString(), RESULTVAR);
}

package org.adoxx.basis.read;

import javax.jws.WebParam;
import javax.jws.WebResult;
import javax.jws.WebService;

@WebService
public interface MyFirstRead {
   public @WebResult(name = "basename") String getModelBasename(@WebParam(name = "modelid") String modelid);
}

5. Add the interface to the 'context.xml'

In order to display the the above defined interface in the wsdl list one has to make some adjustmaents in the 'ADOxxWEB Interface' project.

A. Go to the 'ADOxxWEB Interface' - project

B. Open the 'src/main/webapp/WEB-INF/context.xml' file.

C. Create a bean node. A bean definition may contain nested tags for constructor arguments,  property values, lookup methods, and replaced methods. Mixing constructor injection and setter injection on the same bean is explicitly supported.

<bean id="myFirstReadService" class="org.adoxx.basis.read.MyFirstReadImpl">
   <property name="daoService" ref="daoService" />
</bean>

D. Create an entry in the read service endpoints:

 <jaxws:endpoint id="myfirstread" implementor="#myFirstReadService"
     address="/myFirstRead" />

Result: