Web Service Design Guidelines

Web Service Design Guidelines

Introduction

This document is a guide line how to create web service components for Comflow. This document is updated for Comflow 2.20.

Purpose

Give a “hands on” around the framework for creating and running web service components, both providing and consuming.

Who should read this document?

Developers.

What is Comflow Web Services

Comflow Web Services are functions for exchanging data with other applications, internally or externally, and into Comflow components.

Introducing Comflow Web Services

Web service interactions consists of two types:

Consuming, which is the concept of acting against an existing web service in order to make it provide services for the consumer.

Providing, which is the concept of providing services for one or several consumers.

Comflow base its Web Service framework upon two main components:

• Design time: Eclipse Web Tools Platform (WTP)
• Runtime: Apache Axis 2

The latter is incorporated in runtime, which makes the implementation of Providing web services very simple. You only have to build a java class that extends the AbstractWebService, deploy it and register it in the sitedef and you are done.

For consuming Web services, you need the former, in order to generate java classes for web services, that you then can call from your Comflow components.

If you only want to Provide web services, you can go directly to chapter 5.

Documentation

When installed, the Eclipse Web Tools Platform documentation can be used via the built in help in Eclipse under Web Tools Platform User Guide:

General Axis 2 documentation can be found via: http://axis.apache.org/axis2/java/core/index.html and the user guide via : http://axis.apache.org/axis2/java/core/docs/userguide.html .

Install Eclipse Web Tools Platform

If you want to create consuming web services, then you must install the Eclipse Web Tools platform.

First, make sure you have access to the update site for Eclipse Web Tools platform:

Then do the following to

Step list

1. Chose “Help/Install New Software” in Eclipse menu
2. Write Web in “Work with” and select “Eclipse Web Tools Platform – WTP”. Note that you might need to enable that software under “Available Software Sites” depending on your Eclipse configuration.
3. Select “Web Tools Platform (WTP SDK) 3.1.2” and press “Finish”

Install Axis2

Sometimes it is a problem to use the built in Axis2 in Comflow in the tooling, why you might need to install a parallel Axis2 runtime for only the tooling purpose;

Download Axis2 1.4.1 from http://axis.apache.org/axis2/java/core/download.cgi

Extract it to your Comflow folder, next to your Apache Tomcat folder.

Point it out in Studio preferences under Web services/Axis2 Preferences.

Create a Providing Web Service

When you provide web services in Comflow you simply do the following:

1. Create a web service class
2. Register the class in the sitedef
3. Deploy the service and the sitedef

Build a service class

To make a java class as a providing web service, you need to extend AbstractWebService, like in the example below. The only thing the class needs is to get Process data. Then you can actually make it do whatever as long as you define proper java methods.

* Copyright (c) 2002, 2013 ComActivity AB, Sweden. All rights reserved.

**************************************************************************/

package net.comactivity.bbtools.customerestablishment.ws;

import net.comactivity.axis2.AbstractWebService;

import net.comactivity.core.omg.base.ProcessData;

public class CustomerEstablishmentWS extends AbstractWebService {

public void test (){

ProcessData processData = getProcessData();

}

}

Setting up the sitedef

In order to make your service work in Comflow, you need to register it in the sitedef:

You do that by defining a Startup segment and then a WebServices segment. Then you register each Web service by first specifying the class, including package, the name of the service as well as the description of it. Finally you specify if the service requires authentication (true or false) and what user that shall run it. See the example below:

</ServerInfo>

           <Startup>

                      <WebServices>

                                 <WebService class="net.comactivity.bbtools.customerestablishment.ws.CustomerEstablishmentWS" serviceName="CustomerEstablishment" description="Customer Establishment" requireAuthentication="false" runAsUser="RIKTRO0610" />

                      </WebServices>           

           </Startup>

           <!-- -->

           <Application>

Deploy

Deploy the project where you have the web service classes.

Request WSDL

In order to get to the dynamically generated WSDL, you use the standard URL for the Comflow service, i.e. http://IP:port/Comflow, with the addition of “/axis2services” and the web-service name + “?wsdl”. Like the example below:

http://172.16.192.132:9090/Comflow/axis2services/CustomerEstablishment?wsdl

You then get a reply back with the WSDL:

<wsdl:definitions xmlns:axis2="http://ws.customerestablishment.bbtools.comactivity.net" xmlns:ns1="http://org.apache.axis2/xsd" xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl"xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" xmlns:xs="http://www.w3.org/2001/XMLSchema"xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"targetNamespace="http://ws.customerestablishment.bbtools.comactivity.net">

<wsdl:documentation>Customer Establishment</wsdl:documentation>

<wsdl:types></wsdl:types>

<wsdl:message name="testRequest"></wsdl:message>

<wsdl:portType name="CustomerEstablishmentPortType">

<wsdl:operation name="test">

<wsdl:input message="axis2:testRequest" wsaw:Action="urn:test"></wsdl:input>

</wsdl:operation>

</wsdl:portType>

<wsdl:binding name="CustomerEstablishmentWSSoap11Binding" type="axis2:CustomerEstablishmentPortType">...</wsdl:binding>

<wsdl:binding name="CustomerEstablishmentWSSoap12Binding" type="axis2:CustomerEstablishmentPortType">

<soap12:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>

<wsdl:operation name="test">

<soap12:operation soapAction="urn:test" style="document"/>

<wsdl:input>

<soap12:body use="literal"/>

</wsdl:input>

</wsdl:operation>

</wsdl:binding>

<wsdl:binding name="CustomerEstablishmentWSHttpBinding" type="axis2:CustomerEstablishmentPortType">...</wsdl:binding>

<wsdl:service name="CustomerEstablishment">

<wsdl:port name="CustomerEstablishmentWSHttpSoap12Endpoint" binding="axis2:CustomerEstablishmentWSSoap12Binding">...</wsdl:port>

<wsdl:port name="CustomerEstablishmentWSHttpEndpoint" binding="axis2:CustomerEstablishmentWSHttpBinding">...</wsdl:port>

<wsdl:port name="CustomerEstablishmentWSHttpSoap11Endpoint" binding="axis2:CustomerEstablishmentWSSoap11Binding">...</wsdl:port>

</wsdl:service>

</wsdl:definitions>

Consuming the provided web service

Open the web perspective:

Launch the Web service Explorer

Press WSDL Main and assign the URL to your web service and press Go:

You now get all the methods for the WS and you can through the supported binding methods test it, like the “test” method below.

Create a Consuming Web Service

How to create components for a consuming web service

Use this task to create the software components for consuming an existing web service. This can for instance be done for a providing web service in Comflow to test the web service.

Before starting

You need to have a Comflow Customer project in Eclipse and you also need an URL for the WSDL that you want to consume.

Step list

1. Right click on your project and chose New/Other.
2. Select “Web Service” under Web Services folder

1. Select “Top down Java bean Web Service”
2. Add the WSDL URL to the service definition
3. Set start service to “assemble”- level.

Now all classes are generated in your project and you can consume the web service via plain Java code.

If you just want to test the generation, but you do not have any WSDL, you can check out www.xmethods.net for examples to test against.

Note that the class hardcodes the URL in the stub, so if the Web service will be used for other endpoints, you have to implement a way to change the URL.

Administrating web services

Enable Axis2 administration

Due to security reasons, the Axis2 admin servlet is disabled in the Web.xml. To enable this, you have to edit the web.xml file on 2 places.

The web.xml file is found at:

…Comflow path…\tomcat\webapps\comflow\WEB-INF

To enable the feature, you search for “Axis2” in web.xml and remove “<--“ and “-->” before and after the settings in XML.

The first part to enable is in bold below:

</servlet>

 

          <!-- Start axis2 -->

          <servlet>

                    <servlet-name>AxisServlet</servlet-name>

                    <display-name>Apache-Axis Servlet</display-name>

                    <servlet-class>net.comactivity.axis2.CaAxisServlet</servlet-class>

                    <!--<init-param>-->

                    <!--<param-name>axis2.xml.path</param-name>-->

                    <!--<param-value>/WEB-INF/conf/axis2.xml</param-value>-->

                    <!--<param-name>axis2.xml.url</param-name>-->

                    <!--<param-value>http://localhot/myrepo/axis2.xml</param-value>-->

                    <!--<param-name>axis2.repository.path</param-name>-->

                    <!--<param-value>/WEB-INF</param-value>-->

                    <!--<param-name>axis2.repository.url</param-name>-->

                    <!--<param-value>http://localhot/myrepo</param-value>-->

                    <!--</init-param>-->

                    <load-on-startup>3</load-on-startup>

          </servlet>

          <!--  By default, the Axis2 admin servlet is disabled -->

          <!--

          <servlet>

                    <servlet-name>AxisAdminServlet</servlet-name>

                    <display-name>Apache-Axis AxisAdmin Servlet (Web Admin)</display-name>

                    <servlet-class>org.apache.axis2.webapp.AxisAdminServlet</servlet-class>

          </servlet>

          -->

          

          <servlet>

The second part is in bold below:

<!-- Start axis2 -->

          <servlet-mapping>

                    <servlet-name>AxisServlet</servlet-name>

                    <url-pattern>/servlet/AxisServlet</url-pattern>

          </servlet-mapping>

 

          <servlet-mapping>

                    <servlet-name>AxisServlet</servlet-name>

                    <url-pattern>*.jws</url-pattern>

          </servlet-mapping>

 

          <servlet-mapping>

                    <servlet-name>AxisServlet</servlet-name>

                    <url-pattern>/axis2services/*</url-pattern>

          </servlet-mapping>

 

          <!--  By default, the Axis2 admin servlet is disabled -->

          <!--

          <servlet-mapping>

                    <servlet-name>AxisAdminServlet</servlet-name>

                    <url-pattern>/axis2-admin/*</url-pattern>

          </servlet-mapping>

          <!--  By default, the Axis2 admin servlet is disabled -->

          <!--

          <servlet-mapping>

                    <servlet-name>AxisAdminServlet</servlet-name>

                    <url-pattern>/axis2-admin/*</url-pattern>

          </servlet-mapping>

          -->

Administrate Axis2

The administration of web services in Axis2 can be reached via this URL

http://”server”:”port”/Comflow/axis2services/CustomerOrderCreateWS?wsdl

You can also reach the Axis2 admin function via the Development menu in Comflow,

The standard login in is “admin” with “axis2” as password.

Changing password

You change the password for “Admin” in the axis2.xml file.

Logging web service calls

In order to logg requests made to published web service, you set the Loggers axis and axis2 to DEBUG level in System Control. You then get a log statement to Stdout with the content sent to the web service.

Upgrading activities

When you upgrade applications to newer versions of Comflow, you should plan for

Axis2 Web Service with https

If you have created a web service used by third parties and have setup the portal with https you have to do an additional configuration. There's an axis configuration file located at this structure: 

D:\Corzia\apache\tdk8080\webapps\comflow\WEB-INF\conf\axis2.xml

In that file you have have a property called "transportReceiver" with a default for http. This has to be modified and an addition one has to be added:

<transportReceiver name="http" class="org.apache.axis2.transport.http.AxisServletListener">
<parameter name="port">8081</parameter>
</transportReceiver>

<transportReceiver name="https" class="org.apache.axis2.transport.http.AxisServletListener">
<parameter name="port">8080</parameter>
</transportReceiver>

So for the default with http you change to port so it's the same as you have set up in the server.xml. Then you add the same one but with https and the port setup for https access in server.xml.

When that is done the tomcat service has to be restarted for the action to take effect.

</ServerInfo>

           <Startup>

                      <WebServices>

                                 <WebService class="net.comactivity.bbtools.customerestablishment.ws.CustomerEstablishmentWS" serviceName="CustomerEstablishment" description="Customer Establishment" requireAuthentication="false" runAsUser="RIKTRO0610" />

                      </WebServices>           

           </Startup>

           <!-- -->

           <Application>