Topic overview
There are four non-programmable web services already available that use SOAP as protocol for remote call-ups. They include data export, data import, and remote search as specialized web services. Beyond that, every background application can be called up as web service in a stateless manner using Call-Application. This web services interface uses the freely available Apache Axis web services library. In addition, there is another interface for programmable web services at your disposal. Using that interface, you can implement your own web services as SOAP service or REST service as required. This web services interface uses the freely available Apache CXF web services library. For more information about CXF, please refer to the following website: http://cxf.apache.org/
The delivery package includes sample SOAP and REST services as well as a sample SOAP client implemented in Java.
The present documentation describes the steps necessary to develop own programmed web services as well as the sample web services and clients. It also contains a short explanation of the Soap Ui tool used to test SOAP and REST services.
Target group
- Application developers
- Technical consultants
Definitions of terms
Hypermedia
Refers to the text-based combination of hypertext and multimedia data. Hypermedia is based on the concept of links (hyperlinks) which are primarily known from HTML and enable the user to navigate through the web or access embedded data, e.g. PDF documents.
JAXB
Abbreviation of Jakarta XML Binding. This Java interface describes how data from an XML scheme instance is automatically mapped to Java classes and how these Java classes are generated from an XML scheme.
JAX-RS
Abbreviation of Jakarta RESTful Web Services, a Java interface specification that enables and unifies the application of the REST architectural style within the scope of web services.
JAX-WS
Abbreviation of Jakarta XML Web Services, the specification of the Java interface for the creation of web services.
Representation
Representation means any useful information on the state of a resource. It presents a resource in a defined format. A resource’s representation may reference further resources. The following representations may be used: XML, HTML, CSV, binary formats, text without defined structure (text/plain).
Request
A user’s input or interactions are transmitted by the user’s computer – the client – over the network to the server. The data received by the server is called a request. Having processed the data, the server sends a confirmation or new data as response to the client. Thus, communication between client and server always consists of request and response.
Response
A user’s input or interactions are transmitted by the user’s computer – the client – over the network to the server. The server processes the request and answers the client by sending a confirmation or new data. This answer is called a response. Thus, communication between client and server always consists of request and response.
REST
Abbreviation of Representational State Transfer, an architectural style for the exchange of messages in distributed hypermedia information systems based on HTTP. It is not a protocol and currently not standardized. In contrast to SOAP, knowledge of protocol conventions is not required for client and server to be able to communicate. The following guiding principles are of central importance:
- Addressability of resources.
- Utilization of hypermedia based on HTML or XML.
- Application of standard HTTP operations.
- Statelessness of the communication – which does not refer to the state of the server! REST stipulates that the state is either retained by the client or translated into a resource status by the server. What is not acceptable is a transient, client-specific status that is stored on the server beyond the duration of a request.
RESTful HTTP
Applying the HTTP operations as follows:
- GET – requests data from the server
- POST – stores new data on the server
- PUT – updates existing data
- DELETE – removes data
- HEAD – requests the metadata of a resource
- OPTIONS – checks which operations are available for a resource
REST service
A web service using the architectural style of REST.
(Web) Resource
The term web resource (or simply resource) is used to refer to a source anywhere on the web that can be uniquely identified by a URI (see the RFC 3986 standard). Examples of web resources are: files, diagrams, Internet services, and servlets, as well as collections of other resources that can be addressed by URIs. A resource can have several representations.
SOAP
Abbreviation of Simple Object Access Protocol, an XML-based protocol for exchanging messages in distributed systems. SOAP is used for communication between web services clients and servers.
SOAP service
A web service using the SOAP protocol for remote call-ups.
WADL
Abbreviation of Web Application Description Language, the description language for RESTful web services.
WSDL
Abbreviation of Web Services Description Language, the description language for the interface to a web service.
Description
The interface for programmable web services enables you to develop a web service as SOAP service or REST service. Whether to use a SOAP service or a REST service depends on the specific requirements.
Preconditions
The SAS on which a programmable web service is executed must be started together with the web server, which also starts the web services server. That is the standard scenario in the system. The web services server cannot be started separately from the web server.
Developing a programmable web service
The development of a programmable web service consists of several steps: from creating the development object Application to implementing the inner Java class where the web service’s functionalities are realized.
Draft of a web services interface
The interface of a web service to be programmed must be designed in accordance with the technical and business requirements. It is also to be taken into account that the infrastructure available in the system to realize a web service is not suited to transport large volumes of data. The received or sent data may have to be fully prepared in the main memory of the application server. This could put a heavy load on the application server and cause considerable performance losses.
If, during a client’s request and within the scope of the web service implementation, messages are generated in the message queue, they are not automatically returned to the client. It is the task of the web service implementation to return these messages to the client if necessary.
Creating development objects of the Java class and Application categories
Create a development object of the Java class category. We recommend using the same name for Java class and application and adding the suffix service. The namespace should begin like the corresponding .log namespace and end with .soap or .rest instead of .log.
The Java class must be derived from the abstract class CisWebServiceApplication. This parent class defines the init() method. Further implementation depends on whether a SOAP or a REST service is being developed.
Subsequently, a development object Application needs to be created. The fully qualified name of this application identifies the web service.
The category of the application must be RPC service. As special usage, SOAP service or REST service needs to be selected.
Request URI
Request URI of a web service
To call up the web services, you need to invoke a separate URI specific to the respective web service. The structure of this URI is as follows:
- For a SOAP service
https://<base url>/services/soap/<fully qualified name of the application>?oltp=<database name>. Theservices/soapelement of the request URI tells the web services server that a SOAP service is addressed. - For a REST service
https://<base url>/services/rest/<fully qualified name of the application>/<resource>/<possible parameters>/?oltp=<database name>. Theservices/restelement of the request URI tells the web services server that a REST service is addressed. The<resource>element invokes the desired functionality which is called up with the necessary parameters.
Generic query parameters of the request URI
The following generic query parameters can be used:
| Query parameter | Description |
| displayLanguage | Indicates the required display language. |
| contentLanguage | Indicates the required content language. |
| oltp | Name of the OLTP database. |
| context | Code of the required organization. |
| wsdl | Signal for the web services server to provide the WSDL file for a SOAP service. wsdl needs to be specified as the first query parameter. |
| _wadl | Signal for the web services server to provide the WADL file for a REST service. |
If you want to specify multiple query parameters, separate them by ampersand (&) or semicolon (;).
Developing a SOAP service
The created Java class has to contain an inner class marked by the following JAX-WS annotation: @WebService
This annotation does not require any values. The inner class is used as definition and implementation of a SOAP service. The name of the inner class defines the name of the service in the WSDL file. We recommend not to have the inner class end with service.
All public methods that you implement in this inner class will be available to the SOAP client as functional components of the SOAP service.
For more information on JAX-WS and notably the usage of the annotation, please refer to: http://cxf.apache.org/docs/developing-a-service.html
Example of a SOAP service
With the delivery package, you receive the following application and the Java class of the same name: com.cisag.app.system.webservices.service.soap.SOAPExampleService.
The init() method contains the initialization of the internal object and transaction manager. The inner class SOAPExample contains the definition and implementation of the SOAP service. The class is marked by the annotation @WebService.
The following method provides the possibility to concatenate the salutation Hello with the name parameter and have it returned: string sayHello(string name)
With the following method you can query whether a sales order of the defined type and number exists: boolean existSalesOrder(string type, string number) .
The next method returns the bean SalesOrderResult based on the defined type and number; it contains status information of the sales order and the name of the employee responsible. Please keep in mind that the bean needs to be programmed as a static Java class.
public SalesOrderResult getSalesOrderByBusinessKey(string type, string number)
@WebParam(<“name of a parameter”>), you can describe the input parameters of the methods in more detail. The WSDL file and the generated classes will then not contain names like argX but the specified parameter names.
SOAP version
By default, programmable SOAP services use SOAP version 1.2 in the WSDL file. SOAP responses are sent in the SOAP version that the client used in the SOAP request (SOAP 1.1 or SOAP 1.2).
You can specify in a SOAP service that it should only support SOAP 1.1. In this case, SOAP 1.1 will be used in the WSDL file. Additionally, specify the following annotation for the inner class: @javax.xml.ws.BindingType(value = javax.xml.ws.soap.SOAPBinding.SOAP11HTTP_BINDING)
Please note that the non-programmable web services that are described in the Web Services Interface article use SOAP 1.1.
Stateful SOAP services
SOAP services can also be called up in a stateful manner. For each service called up in a session, an instance of the application and a related service object are generated. Further call-ups of the same service within the same session go to the service object already generated.
Therefore, a service is able to store a state between call-ups – by using attributes in the application instance or the service object.
Please note that sessions are automatically terminated after a waiting time if they are not used. In order to keep a session open, at least one call-up of any web service is required for the same session within the waiting time. For this, the system provides the parameterless ping method for SOAP services: com.cisag.sys.tools.webservices.log.Session .
Developing a REST service
The created Java class has to contain an inner class marked by the following JAX-RS annotation: @Path(“fully qualified name of the REST application”).
As value, the annotation requires the fully qualified name of the created application for which RPC service is specified as type and REST service as special usage. This name represents the root resource which is a necessary component of the REST service’s request URI. Furthermore, the inner class has to have a public constructor.
The functionalities of the REST service available to a REST client are represented by the public methods (resource methods) marked by the JAX-RS annotations:
- Request method designator (
@GETor@PUTor@POSTor@DELETE) @Path (“name of the resource and possibly further parameters”)
The values assigned to the @Path annotation constitute further components of the request URI which are relative to the root resource. The values may contain placeholders in curly brackets.
When programming the resource methods, you should observe the following with regard to HTTP operations:
- GET – requests a resource’s representation. Requests should be free from side effects
- POST – allows something to be added to a resource. POST is not free from side effects
- PUT – can be used to create new resources or to replace the contents of existing resources
- DELETE – removes resources
For further reference, please check: Java™ API for RESTful Web Services http://jsr311.java.net/nonav/releases/1.1/spec/spec.html
resource methods contain information on how to call up the functionalities of the REST service. All functionalities marked with the HTTP operation GET, can be directly called up in the Internet Explorer. For other HTTP operations, the Soap Ui tool can be used.Example of a REST service
With the delivery package, you receive the following application and the Java class of the same name:
com.cisag.app.system.webservices.service.rest.RESTExampleService
The init() method contains the initialization of the object and transaction manager. The inner class RESTExample contains the definition and implementation of the REST service. The class is marked by the following annotation: @Path(“com.cisag.app.system.webservices.service.rest.RESTExampleService”)
The following resource method provides the possibility to concatenate the salutation Hello with the given name parameter and have the representation returned as plain/text by default:
@GET
@Path(“sayHello/{name}”)
public string sayHello(@PathParam(“name”) string name)
The @GET annotation indicates that the HTTP method GET must be used in the request. The @Path annotation contains the value sayHello/{name} with sayHello being the identification of the functionality and {name} the necessary placeholder, which is linked to the resource method parameter name through the additional annotation @PathParam("name").
With the following resource method, you can query whether a sales order of the defined type and number exists:
@GET
@Path(“salesOrderAvailable/{type}/{number}”)
public string existSalesOrder(@PathParam(“type”) string type, @PathParam(“number”) string number)
The below resource method returns the bean SalesOrderBean based on the defined type and number; it contains information about the type and number, the status of the sales order, and the name of the employee responsible:
@GET
@Path(“getSalesOrder/{type}/{number}”)
@Produces(MediaType.APPLICATION_XML)
public SalesOrderBean getSalesOrderByBusinessKey(@PathParam(“type”) string type, @PathParam(“number”) string number)
The @Produces annotation describes the representation in XML form. Please note that the bean for JAXB support will be marked with the annotation @XmlRootElement(name = “SalesOrderBean”)
The following resource method generates a new instance of the bean SalesOrderBean with the given type, number, and status in the main memory and returns the representation as HTML.
@POST
@Path(“newSalesOrderBean/{type}/{number}/{orderStatus}”)
@Produces(MediaType.TEXT_HTML)
public SalesOrderBean newSalesOrder(@PathParam(“type”) string type, @PathParam(“number”) string number, @PathParam(“OrderStatus”) short orderStatus)
The instance is not stored. In contrast to other resource methods, this method is marked by the @POST annotation.
@PathParam annotation, the annotation @QueryParam is available, which can be used to access the query parameters of the request URI. Thus, the service is able to define its own query parameters that a client can transfer as a query string. As the first character of the query parameter’s name, always use a capital letter. Query parameter names that begin with a small letter are reserved for the system engine.Requesting the WSDL/WADL file
The WSDL or the WADL file is required for the development of a web services client. The structure of the relevant request URI is as follows:
- For a SOAP service
https://<base uri>/services/soap/<fully qualified name of the application>?wsdl. The wsdl component of the request URI informs the web services server of the ERP system that a WSDL file needs to be prepared and made available. Entering the request URI in the address bar of the Internet Explorer opens an authentication dialog window. After successful authentication, the WSDL file is displayed. It can be stored using the [Save as] option of the Internet Explorer. - For a REST service
https://<base uri>/services/soap/<fully qualified name of the application>?_wadl. The _wadl component of the request URI informs the web services server of the ERP system that a WADL file needs to be prepared and made available. Entering the request URI in the address bar of the Internet Explorer opens an authentication dialog window. After successful authentication, the window for file download is displayed enabling you to store the WADL file. Please be aware that the WADL file may be incomplete, e.g. parameters might be missing. This depends on the programming of the respective REST service.
Authentication and authorization
In order to be able to call up a web service, the client needs to authenticate to the web server. This authentication is performed by digest authentication or by means of a client certificate. In the description of the sample client under Sample SOAP service client, authentication is done via client certificate.
Programmable web services are applications. Therefore, a user has to have the authorization to open the application to be able to call up the web service.
Debugging support
The web services server of the ERP system offers the possibility to output information about client requests. This is true for both non-programmable and programmable web services.
Activate the class debugging of the Java class com.cisag.sys.kernel.webservices.CisWebServicesResource on the SAS that is called up by the clients.
Depending on the debugging level, the following information is output in the tool shell:
| Debugging level | Output |
| INFO | For every call-up of a web service, information is output at the beginning and the end of its processing by the SAS. The output contains: session number, HTTP method, request URI, processing time. |
| FINEST | In addition to the output of the INFO debugging level, the FINEST level delivers the contents (HTTP body) of the client’s request and the web service’s response. |
This output can be activated and deactivated for a running SAS by the tool shell command dbgcls (debug class).
Examples of web services clients
Sample SOAP service client
With the delivery package, you receive the below example of a SOAP service client. This client checks whether a sales order exists or not.
The following class contains the actual client implementation: com.cisag.app.system.webservices.service.soap.client.SOAPExampleClient
Additionally, the following classes are needed for the programming of the client:
com.cisag.app.system.webservices.service.soap.client.ExistSalesOrder com.cisag.app.system.webservices.service.soap.client.ExistSalesOrderResponse com.cisag.app.system.webservices.service.soap.client.GetSalesOrderByBusinessKey com.cisag.app.system.webservices.service.soap.client.GetSalesOrderByBusinessKeyResponse com.cisag.app.system.webservices.service.soap.client.ObjectFactory com.cisag.app.system.webservices.service.soap.client.SalesOrderResult com.cisag.app.system.webservices.service.soap.client.SayHello com.cisag.app.system.webservices.service.soap.client.SayHelloResponse com.cisag.app.system.webservices.service.soap.client.SOAPExample com.cisag.app.system.webservices.service.soap.client.SOAPExampleService
These classes are generated by the wsimport tool from the WSDL file. The wsimport tool is part of the JDK from Java 6.
The WSDL file is created with the following request: https://<base uri>/services/soap/com.cisag.app.system.webservices.service.soap.SOAPExampleService?wsdl
Instead of the placeholder <base uri> the real address is to be specified.
Afterwards, the wsimport tool is called up below <JDK directory>/bin as follows:
wsimport -p com.cisag.app.system.webservices.service.soap.client -d <path for the .class files> -s <path for the source files> <path with the name of the WSDL file> -Xnocompile -extension
Instead of the path placeholders, the real paths are to be specified.
After generation, the following class contains the path to the WSDL file: com.cisag.app.system.webservices.service.soap.client.SOAPExampleService
This path is replaced by the following URI: <base uri>/services/soap/com.cisag.app.system.webservices.service.soap.SOAPExampleService?wsdl&oltp=<oltpname>
<base uri> and <oltpname> with the concrete values of the base URI and the name of the OLTP database.
The following class contains the main method which is responsible for the verification of the parameters: com.cisag.app.system.webservices.service.soap.client.SOAPExampleClient
Within this method, the following is performed:
- Creation of an instance of
SOAPExampleService - Creation of a service object
- Authentication
- Call-up of the SOAP service method
existSalesOrder(salesOrderType, salesNumber)
Outside the system, the call-up of the client looks as follows: com.cisag.app.system.webservices.service.soap.client.SOAPExampleClient SOAPServiceAddress userCertificateFileName userCertificate-FilePassword serverCertificateFileName salesOrderType salesNumber
Instead of SOAPServiceAddress enter the complete address of the SOAP service including the name of the OLTP database, e.g.: https://qas.kauftreu.com/services/soap/com.kauftreu.app.system.webservices.service.soap.SOAPExampleService?oltp=QAS51000
Exception in thread "main"
com.sun.xml.internal.ws.client.ClientTransportException: HTTP transport error: javax.net.ssl.SSLException: Unrecognized SSL mes-sage, plaintext connection? at com.sun.xml.internal.ws.transport.http.client.HttpClientTransport.getOutput(HttpClientTransport.java:121) at
com.sun.xml.internal.ws.transport.http.client.HttpTransportPipe.process(HttpTransportPipe.java:142) at
com.sun.xml.internal.ws.transport.http.client.HttpTransportPipe.processRequest(HttpTransportPipe.java:83) at
com.sun.xml.internal.ws.transport.DeferredTransportPipe.processRequest(DeferredTransportPipe.java:105)
The sample SOAP client is programmed in such a way that all requests are assigned to the same sessions.
Sample REST service client
You can use the Soap Ui tool for the individual requests. A description of that tool is provided under Testing web services with the “Soap Ui” tool.
Testing web services with the Soap Ui tool
The “Soap Ui” tool offers you the possibility to test SOAP and REST services. The below description refers to version 3.6.1. A comprehensive documentation as well as installation instructions for the tool can be found under the following address: http://soapui.org/REST-Testing/getting-started.html
Soap Ui settings
Before you can test a web service, you need a WSDL or WADL file. Additionally, the JKS file of a user certificate is required for authentication, along with the file password. The user certificate must be assigned to the user testing the web service. Enter the file path and the password in the SSL Settings grouping of the SoapUi Preferences dialog.
Socket Timeout under HTTP Settings.To open the dialog window SoapUi Preferences , you can either use the shortcut CTRL+ALT+P or select the File menu item and then the SoapUi Preferences option.
New Soap Ui project
Once you have defined the Soap Ui settings, you can create a new Soap Ui project by using the shortcut CTRL+N or by selecting the option New Soap Ui Project in the File menu item. A dialog window will appear where you are to enter the project name and the path to the WSDL or WADL file. After click on [OK], a project with a hierarchical structure is created. The individual nodes represent the complete web service or separate functionalities or the latter’s HTTP operations (only for a REST service).
Please note that the names of the generic query parameters (e.g. oltp or context) are not part of the WSDL or WADL file. You have to enter these parameters manually:
- For a SOAP service, expand the nodes of functionalities to be tested until you reach the node
Request<number>. Then highlight the address bar of the dialog window, select the [edit current…] option and add the relevant parameter to the URI. - For a REST service, expand the node carrying the name of the web service. That should be the name of the application you created in the ERP system. Double-click on it. A dialog window appears where you can add further parameters.
In order to access a web service, expand the nodes of functionalities to be tested until you reach the node Request<number>. Click on that node. A dialog window will be displayed where you can enter the requests for the web services and view their responses.
It may happen that the WADL file is incomplete, e.g. the parameters needed for the request might be missing. In that case, add the necessary parameters manually.
The Soap Ui tool can display diverse log files. For instance, the lower section of the main window provides the tabs Soap Ui log and error log.