9 min read

Invoking a web service using the Java client

A web service exposes a set of operations over the network, typically via HTTP protocol. In order to invoke the web services, the web service client needs to know the following information:

  • What operations are exposed by the web service
  • The input and output message formats required to access the service operations
  • What protocol, for instance HTTP or JMS, to use to invoke the web service
  • The URL location of the web service

All of the above information is contained in the standard XML descriptor called WSDL (Web Service Description Language). The WSDL file provides a format contract between the web service provider and the web service client. The web service client typically inspects the WSDL file to determine what operations are exposed by the web service, what parameters need to be supplied to invoke the web service operation and to formulate the request, and invokes the web service over the supported protocol. Similarly, the web service clients need to write the code to inspect the response and convert it into the required format. CXF hides the complexity of creating web service clients by providing the WSDL to Java command line tool, which takes a WSDL file and generates client code. The client code can be used by developers with no changes to invoke the web services.

In this section, we will look at how to generate client code from an existing WSDL. For this example, we will take a real world scenario, where we will invoke a .NET service located over the Web using the Java client generated by the WSDL to Java tool. This shows the true power of web service interoperability, where applications implemented in different languages can communicate with each other.

The process of generating web service clients does not differ for web services implemented in different languages, as you generate web service clients from WSDL and XML Schema definitions.

Before invoking the .NET service, let’s examine the WSDL to determine which operations are exposed by the web service.

Analyzing the service WSDL definition

We will invoke a publicly available .NET web service located at http://www.ignyte.com/webservices/ignyte.whatsshowing.webservice/moviefunctions.asmx?wsdl. This web service retrieves US Theaters and Movie Showtime information based on a valid US zip code and a radius supplied by the web service clients.

The .NET web service is a WS-I compliant web service.

The Web Services Interoperability Organization (WS-I), an open industry organization, was formed to promote web services interoperability across platforms, operating systems, and programming languages. One concrete product of WS-I is the Basic Profile. Basic Profile narrows the scope of specifications to a reasonable set of rules and guidelines that are best suited to help interoperability.

If you type in the given URL in the browser, you see the WSDL definition, as shown in the following screenshot:

Let’s analyze the important sections of the WSDL file to get an understanding of which operations are exposed by the movie information web service and which message formats are required to invoke the web service.

The web service provides two operations, GetTheatersAndMovies and GetUpcomingMovies, as shown in listing below. For this article, we will focus on how to invoke the GetTheatersAndMovies operation. The GetTheatersAndMovies takes the GetTheatersAndMoviesSoapIn message as the input and provides GetTheatersAndMoviesSoapOut as the output message.

<wsdl:portType name="MovieInformationSoap">
 <wsdl:operation name="GetTheatersAndMovies">
 <wsdl:documentation >This method will retrieve a list of all theaters and the movies
playing today.</wsdl:documentation>
 <wsdl:input message="tns:GetTheatersAndMoviesSoapIn" />
 <wsdl:output message="tns:GetTheatersAndMoviesSoapOut" />
 </wsdl:operation>
</wsdl:portType>

The web service client invokes the GetTheatersAndMovies operation to get theater and movie information. The input to the GetTheatersAndMovies operation is the GetTheatersAndMoviesSoapIn XML message.

The GetTheatersAndMoviesSoapIn message references the GetTheatersAndMovies element, which defines the actual XML schema definition for the input message. The following is the code listing of GetTheatersAndMovies schema definition:


<s:element name="GetTheatersAndMovies">
 <s:complexType>
 <s:sequence>
 <s:element minOccurs="0" maxOccurs="1"
 name="zipCode" type="s:string" />
 <s:element minOccurs="1" maxOccurs="1"
 name="radius" type="s:int" />
 </s:sequence>
 </s:complexType>
</s:element>

The GetTheatersAndMovies contains an element zipCode of type String and radius which is of type integer that needs to be passed as input by the web services client as an input to the GetTheatersAndMoviesSoapIn operation. The minOccurs and maxOccurs attribute associated with zipCode and radius is used to specify the minimum and maximum occurrence of the element inside a GetTheatersAndMovies element. The zipCode and radius element can appear only once inside a GetTheatersAndMovies element as it specifies the value of maxOccurs=”1″. If maxOccurs has the value Unbounded, then it implies that multiple occurrences of the element can exist.

Similarly, the GetTheatersAndMoviesResponse specifies the output message format for the response. The following is the code listing of the GetTheatersAndMoviesResponse schema definition. We will break down the schema for better understanding:

  • The GetTheatersAndMoviesResponse schema
    The following shows the definition of GetTheatersAndMoviesResponse. The GetTheatersAndMoviesResponse contains an element ArrayOfTheater. 
    <s:element name="GetTheatersAndMoviesResponse">
     <s:complexType>
     <s:sequence>
     <s:element minOccurs="0" maxOccurs="1"
     name="GetTheatersAndMoviesResult" type=
     "tns:ArrayOfTheater" />
     </s:sequence>
     </s:complexType>
    </s:element>
  • The ArrayOfTheater Schema
    The following shows the definition of ArrayOfTheater schema.
    The ArrayOfTheater is an array which consists of Theatre elements.
    The maxOccurs=”unbounded” specifies that multiple occurrences of Theatre elements can exist in an ArrayOfTheater element. 

    <s:complexType name="ArrayOfTheater">
     <s:sequence>
     <s:element minOccurs="0" maxOccurs=
     "unbounded" name="Theater" nillable=
     "true" type="tns:Theater" />
     </s:sequence>
    </s:complexType>

  • The Theater Schema
    The Theater elements consist of the Name and Address elements of type String, which specifies the name and address of the Theater and an array of ArrayOfMovie element. 
    <s:complexType name="Theater">
     <s:sequence>
     <s:element minOccurs="0" maxOccurs="1"
     name="Name" type="s:string" />
     <s:element minOccurs="0" maxOccurs="1"
     name="Address" type="s:string" />
     <s:element minOccurs="0" maxOccurs="1"
     name="Movies" type="tns:ArrayOfMovie" />
     </s:sequence>
    </s:complexType>
  • The ArrayOfMovie Schema
    The following is the ArrayOfMovie definition. The ArrayOfMovie is an array which consists of Movie elements. The maxOccurs=”unbounded” specifies that multiple occurrences of Movie elements can exist in an ArrayOfMovie element. 
    <s:complexType name="ArrayOfMovie">
     <s:sequence>
     <s:element minOccurs="0" maxOccurs=
     "unbounded" name="Movie" nillable=
     "true" type="tns:Movie" />
     </s:sequence>
    </s:complexType>
  • The Movie Schema
    The Movie element contains details of movies such as ratings, names of the movies, running times and show times represented as String type. 
    <s:complexType name="Movie">
     <s:sequence>
     <s:element minOccurs="0" maxOccurs="1"
     name="Rating" type="s:string" />
     <s:element minOccurs="0" maxOccurs="1"
     name="Name" type="s:string" />
     <s:element minOccurs="0" maxOccurs="1"
     name="RunningTime" type="s:string" />
     <s:element minOccurs="0" maxOccurs="1"
     name="ShowTimes" type="s:string" />
     </s:sequence>
    </s:complexType>

Based on the Schema definitions above, the CXF WSDL2Java tool generates Java code that maps to these XML elements. The web service clients communicate with the web services using these generated Java objects to invoke a Java method representing the GetTheatersAndMoviesoperation and leave the SOAP XML to Java conversion and low level implementation details with the CXF framework.

The SOAP address in the WSDL file specifies the location of the service, which is http://www.ignyte.com/webservices/ignyte.whatsshowing.webservice/moviefunctions.asmx, as shown in the listing below:

 <wsdl:service name="MovieInformation">
 <wsdl:port name="MovieInformationSoap" binding=
 "tns:MovieInformationSoap">
 <soap:address location="http://www.ignyte.com/webservices/
 ignyte.whatsshowing.webservice/moviefunctions.asmx" />
 </wsdl:port>
 <wsdl:port name="MovieInformationSoap12" binding=
 "tns:MovieInformationSoap12">
 <soap12:address location="http://www.ignyte.com/webservices/
 ignyte.whatsshowing.webservice/moviefunctions.asmx" />
 </wsdl:port>
 </wsdl:service>
</wsdl:definitions>

We will now look at how to generate the web service client code for the Movie information web service.

Building and running the Java web service clients

The source code and build files for the example are available in the wsdl2Java folder of the downloaded source code. We will follow the steps below to build and execute the web service client:

  • Generate the web service clients
  • Analyze the generated artifacts
  • Modify the generated code
  • Build the web service client
  • Run the web service client

Generate the web service clients

We will use the Ant build script (build.xml) for generating the web service client code and building the project code as shown below. Navigate to the wsdl2java folder of the downloaded source code. Execute the cxfWSDLToJava target by navigating to the wsdl2java folder and running the following command:

ant cxfWSDLToJava

The following figure shows the output generated upon running the ant command:

The cxfWSDLToJava ant target calls the CXF tool apache.cxf.tools.wsdlto.WSDLToJava to generate web service client code based on the URL http://www.ignyte.com/webservices/ignyte.whatsshowing.webservice/moviefunctions.asmx?wsdl

The following is a code snippet of ant target cxfWSDLToJava in build.xml:


<target name="cxfWSDLToJava">
 <java classname="org.apache.cxf.tools.wsdlto.WSDLToJava"
 fork="true">
 <arg value="-client"/>
 <arg value="-d"/>
 <arg value="src"/>
 <arg value="http://www.ignyte.com/webservices/ignyte.
 whatsshowing.webservice/moviefunctions.asmx?wsdl"/>
 <classpath>
 <path refid="cxf.classpath"/>
 </classpath>
 </java>
</target>

WSDLToJava generates JAX-WS compliant Java code for the services defined in the WSDL document. Based on the parameters passed, it can generate the starting point of the code for developing the web service client and service. The client option, as shown in above snippet, generates the client code. The following is a list of augments and descriptions supported by the WSDLToJava tool extracted as it is from the CXF website—http://cwiki.apache.org/CXF20DOC/wsdl-to-java.html

Packt

LEAVE A REPLY

Please enter your comment!
Please enter your name here