How to implement web services?

We will go through creating and implementating web services in our openhub-example module.

WSDL and XSD implementation

  • WSDL and XSD is defined in Contract-First design approach - firstly define web service interfaces, secondly implement them in specific language.
  • there are two files (in package resources/org.openhubframework.openhub.modules.in.hello.ws.v1_0): 
    • WSDL definition (e.g. hello-v1.0.wsdl
    • XSD with requests/responses definition (helloOperations-v1.0.xsd). XSD contains request definitions, imports commonTypes-v1.0.xsd with common types from openhub-core module

hello-v1.0.wsdl:

  • traceHeader is mandatory for asynchronnous messages
  • it's good practice to adhere some name conventions, for example those presented in Best practices


helloOperations-v1.0.xsd:

  • this XSD contains requests and responses for each operation

Generating Java sources from WSDL/XSD

We use jaxws-maven-plugin plugin for generating Java classes from WSDL/XSD:

  • see pom.xml in openhub-example module for more details
  • we use two more plugins before generating Java classes
    • maven-dependency-plugin: copies resources (xjb, xsd) from other modules
    • maven-resources-plugin: copies all xjb, wsdl and xsd files to a single directory for generating Java model from WSDL/XSD,allowing WSDL/XSD files to reference each other easily with a simple relative path.
  • we defined two XJB binding files for use (both from core-api module)
    • jaxb_global_bindings.xjb: global Java type bindings, for example org.joda.time.DateTime vs xs:dateTime
    • jaxb_common_bindings.xjb: bindings of common types defined in commonTypes-v1.0.xsd


Publishing WSDL/XSD

Web service configuration for openhub-example module is in org.openhubframework.openhub.modules.ExampleWebServiceConfig:

  • helloWsdl() publishes WSDL
  • helloOperations() publishes XSD with requests and responses
  • publishing WSDL and XSD files have to be published separately. See Spring Web Services reference manual where you find more information because Spring WS is underlying library for web service communication.

Implementation of WebServiceValidatingSources that registers XSD schemas for validation incoming/outgoing messages (traceHeader is mandatory for asynchronous requests only - set synchronnous requests to ignore requests)

Route implementations

  • Camel has Spring web services (spring-ws) component for definition of incoming endpoint
  • use handy function getInWsUri() from parent class that creates spring-ws endpoint with all necessary settings
  • adhere name conventions with using getRouteId() method
  • classes SyncHelloRequest and SyncHelloResponse are generated by jaxws-maven-plugin mentioned above


Unit test implementations