[OFBIZ-3877] New Web Service Style

• Type: New Feature
• Status: Closed
• Priority: Minor
• Resolution: Abandoned
• Component/s: framework

Environment

Windows, Ubuntu Linux

• Assignee: Unassigned
• Reporter: Chatree Srichart
• Created: 04/Aug/10 07:10
• Updated: 25/May/20 07:28
• Resolved: 25/May/20 07:28

Description

This is a new stub for new web service style that use a normal style (not hash map [key/value]).

[[ Installation ]]

• Extract webservice.zip file (attached file) to hot-deploy directory of OFBiz framework
• run ant task for apply patch in webservice directory with:
  ant reapply-ofbiz-patches

[[ Features ]]

1.) New classes

There is new important class

org.ofbiz.webapp.webservice.event.WebServiceEventHandler

which corresponds to earlier

org.ofbiz.webapp.event.SOAPEventHandler

but tries to support document style web services using
SOAP with XML-format, or REST with XML and JSON-formats.
This handler class uses other class:

org.ofbiz.service.webservice.WebServiceModel

which wraps inside class

org.ofbiz.service.ModelService

and contains support for WSDL-generation, WADL-generation
and conversion between Java Maps and XML-object models.
WSDL=Web Service Definition Language for SOAP-interface
http://www.w3.org/TR/wsdl
WADL=Web Application Description Language for REST-interface
http://www.w3.org/Submission/wadl/

There is another new important class

org.ofbiz.service.webservice.engine.WebServiceClientEngine

which corresponds to earlier

org.ofbiz.service.engine.SOAPClientEngine

but tries to support document style web services using
SOAP with XML-format. Web services can be called using
their WSDL-document or messages can be specified in
services.xml without using WSDL-document. engine-attribute
in services description is set to "webservice". Location
of WSDL-document is given in attribute wsdlLocation or
it can be left out if messages are described with attribute-
definitions. Name of service in WSDL is given in
attribute webServiceName and name of operation to be
invoked in attribute invoke. One service-definition is
needed for one web service-operation pair.
Example of web service definitions are in file:
framework/common/servicedef/services_test.xml
This engine class uses other class:

org.ofbiz.service.webservice.WebServiceClientModel

which extends org.ofbiz.service.webservice.WebServiceModel

and contains support for filling attribute definitions
in org.ofbiz.service.ModelService from WSDL-document.

2.) Service definitions

Web service interface can be used only if service definition
file services.xml is completed with additional definitions.
Schema of this file is extended.

attribute-elements can have nested attribute elements
which describe structure of Java maps and lists.
If attribute has type Map, it should have nested attributes
which describe contents of this map.
If attribute has type List, it should have nested attributes
which describe element contents of this list.
If List has simple elements, there must be only one
nested attribute, which describes element.
If List has element which is map or other list, there
must be one nested attribute stating that the element
is Map or List, and then this attribute should have
nested attributes describing structure of Map or
structure of list element.
There are also two new modes for attributes
ERROR which means that attribute is responded as error message
OUTERROR which means that attribute is responded as error
or as success message
These modes are needed for web services to describe
which parameters will go to detail-elements of SOAP Fault response
or REST error messages. Also in WSDL- and WADL-files will be
generated XML-schema for general response messages.

File framework\webapp\servicedef\services_test.xml
can be used as example of attribute definitions.
This file is used in unit tests of web service interface.

3.) Web service requests

In REST-services HTTP GET-method is used in services whose
name start with words "find" or "get". These services should
have input parameters in one level, so that they can be
given as query parameters in URL. HTTP DELETE-method is used
with services whose name start with word "remove". Other services
are used with HTTP POST-method and PUT-method. Service must
look itself for method name POST or PUT, if it is required
to operate differently in insert or update cases.

List of links to all WSDL-documents can be requested with URL:

/webtools/control/WebService?wsdl

Specific WSDL-document is requested with URL:

/webtools/control/WebService/<service name here>?wsdl

SOAP web service is called with URL:

/webtools/control/WebService

Notice that no service name is added to URL. Operation
name in request message specifies the service name.

List of links to all WADL-documents can be requested with URL:

/webtools/control/WebService?wadl

Specific WADL-document is requested with URL:

/webtools/control/WebService/<service name here>?wadl

REST web service is called with URL:

/webtools/control/WebService/<service name here>[?parameter=value...]

REST web service with JSON-format is called with URL:

/webtools/control/WebService/<service name here>?format=json[&parameter=value...]

SOAP and REST web service requests are selected by
request URL, where REST web service has appended
service name in URL.

4.) Unit tests

Tests for web services

org.ofbiz.webapp.webservice.test.WebServiceTests

This has 14 different tests which are:
1. Conversion of XML-object model to Map
2. Conversion of Map to XML-object model
3. Call SOAP-web service
4. Call SOAP-web service which needs authorization
5. Call SOAP-web service with wrong credentials
6. Call SOAP-web service with wrong service name
7. Call REST-web service
8. Call REST-web service which needs authorization
9. Call REST-web service with wrong credentials
10. Call REST-web service with wrong service name
11. Call REST-web service using JSON-format
12. Call REST-web service which needs authorization using JSON-format
13. Call REST-web service with wrong credentials using JSON-format
14. Call REST-web service with wrong service name using JSON-format

Junit test suite definitions are in file
framework/webapp/testdef/webservicetests.xml

These unit tests use test service in class
org.ofbiz.webapp.webservice.test.WebServiceTestServices
Service definitions are in file
framework\webapp\servicedef\services_test.xml

Unit tests for web service interface can be run with command:

ant run-single-test-suite -Dtest.component=webapp -Dtest.suiteName=webservicetests

Tests for web service client

org.ofbiz.service.webservice.test.WebServiceClientTests

This has 4 different tests which are:

1. Call SOAP-web service
2. Call SOAP-web service which needs authorization
3. Call SOAP-web service with wrong credentials
4. Call SOAP-web service without WSDL-document using service definitions

Junit test suite definitions are in file
framework/service/testdef/webserviceclienttests.xml

These tests use same test services as tests for web services.

Unit tests for web service client can be run with command:

ant run-single-test-suite -Dtest.component=service -Dtest.suiteName=webserviceclienttests

Created By: Joonas Keturi

Issue Links

• relates to: OFBIZ-4274 Implement a REST Servlet