Creating A Web Service

Let's put the theory into practice to create a sample web service!

In the src/ directory of your module, create a new java interface called "HelloWorld". Copy the following into that interface:

import javax.jws.WebParam;

import javax.jws.WebService;

import org.apache.cxf.annotations.WSDLDocumentation;

import org.apache.cxf.annotations.WSDLDocumentationCollection;

@WebService

@WSDLDocumentationCollection({

@WSDLDocumentation("A Hello World SOAP Web Service"),

@WSDLDocumentation(value = "A hello world soap web service providing operation sayHi", placement = WSDLDocumentation.Placement.TOP), })

public interface HelloWorld {

@WSDLDocumentationCollection({ @WSDLDocumentation("Says Hi"),

@WSDLDocumentation(value = "Takes String input", placement = WSDLDocumentation.Placement.INPUT_MESSAGE),

@WSDLDocumentation(value = "Returns a String output", placement = WSDLDocumentation.Placement.OUTPUT_MESSAGE) })

String sayHi(@WebParam(name = "text") String text);

}

This creates a new WebService contract, with a single method called "sayHi".

The @WebService annotation marks this java interface as a web service interface. The @WebService annotation will also be used later to mark a Java class as implementing a web service.

The @WebParam annotation customizes the mapping of a parameter to a web service message part. For example, the parameter can be exposed with a different name than the one defined in the method using the "name" property of the annotation

The @WSDLDocumentationCollection and @WSDLDocumentation annotations are used for documenting the WSDL. They are part of the Apache CXF library, which is used by ONE's Platform to handle SOAP. The @WSDLDocumentation annotation provides documentation inside different elements in the generated WSDL. The @WSDLDocumentationCollection annotation is used to group together more than one @WSDLDocumentation annotations.

[OPTIONAL] You can use @WebMethod annotation to customize a method that is exposed as a web service operation. The @WebMethod annotation has optional properties to set action, an operation name that exposes this method with a different name, and a boolean flag that can be used to mark a method to NOT be exposed as a web method.
Next, create a class HelloWorldImpl which implements the interface above. Be sure to replace yourpackagehere with the actual interface package.

import javax.jws.WebService;

import com.onenetwork.platform.integ.soap.BaseSOAPService;

@WebService(endpointInterface = "com.onenetwork.platformapitestmodule.ws2.HelloWorld", serviceName = "PCTA.HelloWorld")

public class HelloWorldImpl extends BaseSOAPService implements HelloWorld {

public String sayHi(String text) {

return "Hello " + getPlatformUserContext().getUserName() + ": " + text;

}

}

This provides an implementation of the HelloWorld web service. Please note that it extends BaseSOAPService; this base class provides useful methods, such as getPlatformUserContext().

The @WebService annotation defines the endpoint interface, service name, etc.
Finally, register the service in the spring "beans" file located at modulebasepkg/moduleprefix-app-context.xml:

<jaxws:endpoint id="PCTA.Hello"

implementor="yourpackagehere.HelloWorldImpl"

address="/PCTA/hello"/>

Available SOAP Services

The registered web service will now be displayed under http://localhost/oms/services/ . This includes hyperlinks to WSDLs which can be used to generate client code.

Accessing WSDL

The WSDL can be accessed by clicking on the link next to "WSDL:" in the Available SOAP Services web page. A sample HelloWorld WSDL is shown below.

NOTE: The @WSDLDocumentation annotation defined on the web service interface with placement parameter as WSDLDocumentation.Placement.TOP is shown in the WSDL as part of wsdl:documentation element at the beginning of the file.

<wsdl:documentation>A hello world soap web service providing operations for sayHi and getSampleWsVal</wsdl:documentation>

<wsdl:types>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://ws2.platformapitestmodule.onenetwork.com/" elementFormDefault="unqualified" targetNamespace="http://ws2.platformapitestmodule.onenetwork.com/" version="1.0">

<xs:element name="sayHi" type="tns:sayHi"/>

<xs:element name="sayHiResponse" type="tns:sayHiResponse"/>

<xs:complexType name="sayHi">

<xs:sequence>

<xs:element minOccurs="0" name="text" type="xs:string"/>

</xs:sequence>

</xs:complexType>

<xs:complexType name="sayHiResponse">

<xs:sequence>

<xs:element minOccurs="0" name="return" type="xs:string"/>

</xs:sequence>

</xs:complexType>

</xs:schema>

</wsdl:types>

<wsdl:message name="sayHiResponse">

<wsdl:documentation>Returns a String output</wsdl:documentation>

<wsdl:part element="tns:sayHiResponse" name="parameters">

</wsdl:part>

</wsdl:message>

<wsdl:message name="sayHi">

<wsdl:documentation>Takes String input</wsdl:documentation>

<wsdl:part element="tns:sayHi" name="parameters">

</wsdl:part>

</wsdl:message>

<wsdl:portType name="HelloWorld">

<wsdl:documentation>A Hello World SOAP Web Service</wsdl:documentation>

<wsdl:operation name="sayHi">

<wsdl:documentation>Says Hi</wsdl:documentation>

<wsdl:input message="tns:sayHi" name="sayHi">

</wsdl:input>

<wsdl:output message="tns:sayHiResponse" name="sayHiResponse">

</wsdl:output>

</wsdl:operation>

</wsdl:portType>

<wsdl:binding name="PCTA.HelloWorldSoapBinding" type="tns:HelloWorld">

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

<wsdl:operation name="sayHi">

<soap:operation soapAction="" style="document"/>

<wsdl:input name="sayHi">

<soap:body use="literal"/>

</wsdl:input>

<wsdl:output name="sayHiResponse">

<soap:body use="literal"/>

</wsdl:output>

</wsdl:operation>

</wsdl:binding>

<wsdl:service name="PCTA.HelloWorld">

<wsdl:port binding="tns:PCTA.HelloWorldSoapBinding" name="HelloWorldImplPort">

<soap:address location="http://localhost/oms/services/PCTA/HW"/>

</wsdl:port>

</wsdl:service>

</wsdl:definitions>

Accessing WSDL