ADOxxWEB API

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.

The next function that the service will provide is to give the ability of the connected web application to split time consuming tasks from shorter running tasks. Bungled in with this function is the ability to further split tasks by user type and product.
 
The third major function is to enable the ADOWS instances to be spread over one or more servers. This is achieved through the use of SOAP/Web technology and the Remote ADOWS Monitor. The RAM takes care of the ADOWS processes that are running, monitoring them and restarting them if necessary.
 
The final major function is to allow the service to be hot-configurable, thus allowing the system administrator to bring in or take away system resources when needed. This is achieved by allowing to load a new/different configuration via an exposed SOAP function.
 
A. Download the ADOxxWEB service software component and save it on your local device.

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.

LBRSNameThe name given to the MainLBRS, used in logging. This should be unique and have a sensible human readable form since it is used in logging to identify messages from the MainLBRS.
NumberOfVirtualLBRSThis must be equal to the number of VirtualLBRS's declared within the configuration file.
PortThis value is used to create the URL that is sent to the RAM so that it can communicate with the LBRS. The value should be the port that the LBRS is attached to in the Tomcat installation.
HostThis value is used to create the URL that is sent to the RAM so that it can communicate with the LBRS. 
Note that you can only use "localhost" if the LBRS and the RAM instance are communicating with/are on the same machine.
SleepTimeBetweenCheckThis sets how long the watcher service of the MainLBRS should sleep between checks.
QueueTestWaitTimeThis value specifies how long the watcher service should wait for the MainLBRS queue to respond before deciding that the queue is not responding.
QueueSizeSpecifies how big the MainLBRS queue is. Once the queue is full, further tasks will be discarded until space becomes available.
bindingWaitTimeThis value specifies how long a SOAP call to an ADOWS instance will wait before throwing an exception.
checkTasksThe LBRS can check each task straight away to see if it will be picked up by any of the VirtualLBRS. Setting this flag to true means that any non-processable tasks will be discarded straight away without waiting for the task to time out.
        
 

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

LBRSNameThe name given to the VirtualLBRS, used in logging and thread identification. Since this field is used for identification, the name must be unique within the configuration.
NumberOfVirtualADOWSInstancesThe number of actual ADOWS instances that the VirtualLBRS will handle. This must be equal to the number of ADOWS instances declared within the configuration file for the VirtualLBRS.
ParameterThe parameter (database) that all of the ADOWS instances within the VirtualLBRS will handle. This will allow the same product to access different databases. If for the ADOWS instance being started this database is invalid, then no ADOWS instances will be started correctly.
UsertypeThe user type is used to identify tasks for a particular VirtualLBRS. Each VirtualLBRS only accepts tasks that match its acceptance criteria. The Usertype allows for the set up of different privileged users, different VirtualLBRS for different web applications or different VirtualLBRS for different types of tasks.
StartTime/EndTime: The StartTime and the EndTime node allows the user to specifyan estimated execution time range that a particular VirtualLBRS will handle. This allows long running tasks to run on a different set of ADOWS instances to the short running tasks. The time given is in milliseconds.
SleepTimeBetweenChecks:This sets how long the VirtualLBRS watcher service should sleep between its checks.
QueueTestWaitTimeThis value specifies how long the watcher service should wait for the VirtualLBRS to respond to its check.
QueueSizeSpecifies how big the VirtualLBRS queue will be. Once the queue is full further tasks will be discarded until space appears.
 
 

      (iii) ADOWSLogin
ADOWSLoginname:The name given to the ADOWS instance, used in logging. This must be unique.
PortThe port number that the ADOWS instance will be listening on for tasks passed to it via the VirtualLBRS task queue.
HostThe 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.
UsernameThe user login name for the ADOWS instance. This must be unique for each ADOWS instance.
PasswordThe 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.
ExecutableThe 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.
portSwitchAllows 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.
RAMPortThis 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.
adowsInitialisationTimeThis gives the amount of time that the ADOWS instance needs to be ready to receive tasks. 

The following example of the LBRS configuration file contains one VirtualLBRS and one ADOWSLogin with the encrypted password: 'password'. 
 
                                               LBRSConfiguration.xml example (Download)
 
Please be sure that the above configurations of the LBRSConfiguration.xml file is correct, otherwise the next step cannot be performed!

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). 

The ADOxxWeb Interface project has dependencies with three other projects: (i) Data Access Object Service, (ii) ADOxxWeb Read Service, and (iii) ADOxxWeb Read Service.

 

Basic Example: Implement your own ModelRead Command

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:

Intermediate Example: Implement your own SOAP Endpoint

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);
}

4. Configure 'MyFirstRead.java' interface and add above created command into it.
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>
 
id: identificator of the bean. 
class: Path of the implementation of step 1 
<property />: Data Access Object-Execution Service
 

D. Create an entry in the read service endpoints:

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

 



Result: