Web Service Compiler Configuration File - Java

As with the servlet-based Web Service, you will need to provide additional information in addition to the standard J2EE deployment descriptor for this type of component. In the J2EE Reference Implementation, you again use wscompile to generate this information. The configuration file used to generate the artifacts for the agency Service bean, shown in listing 20.10, is almost identical to that for the servlet-based Web Service, as shown in Listing 20.3 (only the names have changed).

Listing 20.10 wscompile Web Service Configuration File (config-service.xml)

<?xml version="1.0" encoding="UTF-8"?>
<configuration 
xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config">
<service 
name="AgencyService" 
targetNamespace="urn:J2EE21Agency" 
typeNamespace="urn:J2EE21AgencyTypes" 
packageName="agency">
<interface name="agency.Service"/>
</service>
</configuration>

The wscompile command line is identical to that for the servlet-based Web Service, and the same files will be produced, namely the WSDL description and the mapping.xml file.

As before, the sample code is on the Web site that accompanies this book. As it forms the basis of the exercise, you will find this example in the exercise directory for Day 20. With the code supplied on the accompanying Web site, you can use the following Ant command to build the supplied agency Web Service, which includes the creation of the WSDL and the mapping file:

asant build

The WSDL File

As the interface is different from the greeting service defined earlier, the WSDL generated will also be different. As the findJobsAtLocation() method returns something other than a simple type, a complex type is defined in the types section of the WSDL description:

<types>
<schema targetNamespace="urn:J2EE21AgencyTypes"
xmlns:tns="urn:J2EE21AgencyTypes"
xmlns:soap11-enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns="http://www.w3.org/2001/XMLSchema">
<import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
<complexType name="ArrayOfstring">
<complexContent>
<restriction base="soap11-enc:Array">
<attribute ref="soap11-enc:arrayType" wsdl:arrayType="string[]"/>
</restriction>
</complexContent>
</complexType>
</schema>
</types>

Without going into too much detail, the new type—ArrayOfString— is defined to be an unbounded array of the simple string type. This new type is defined in the scope of the urn:J2EE21Agency namespace specified for types in the wscompile configuration file. This ArrayOfString type can then be used later in the WSDL document to define the return type of the findJobsAtLocation operation:

<message name="Service_findJobsAtLocationResponse">
<part name="result" type="ns2:ArrayOfstring"/>
</message>

As you can see, the findJobsAtLocation response is defined to contain an ArrayOfString, which is scoped to namespace ns2 (ns2 is defined to be urn:J2EE21Types in the overall definitions element). Other than this, the WSDL document is very similar to the greeting service WSDL described earlier.

The Mapping File

As you would expect, the mapping file is also very similar to that for the greeting service. It contains nothing specific to the service being implemented by an EJB and simply reflects the changes in the interface, such as the use of the array of strings as a return type:

<java-wsdl-mapping version="1.1" ...>
<service-endpoint-interface-mapping>
...
<service-endpoint-method-mapping>
...
<wsdl-return-value-mapping>
<method-return-value>java.lang.String[]</method-return-value>
<wsdl-message xmlns:wsdlMsgNS="urn:J2EE21Agency">
wsdlMsgNS:Service_findJobsAtLocationResponse
</wsdl-message>
<wsdl-message-part-name>result</wsdl-message-part-name>
</wsdl-return-value-mapping>
</service-endpoint-interface-mapping>
...
</service-endpoint-method-mapping>
...
</java-wsdl-mapping>

Packaging and Deploying the Agency Web Service Using J2EE RI deploytool

This section shows how to deploy the simple Web Service to the J2EE RI. As noted before, you will need to start up the PointBase database server and J2EE RI server before starting deploytool.

Creating the Agency EAR

By choosing File, Open, load up the Day20/exercise/j2ee-ri/agency.ear enterprise application archive. This defines a single group of Entity beans called Entity which will be used by the Web Service session bean. Highlight the Agency application in the explorer on the left side of the deploytool GUI and its contents will be shown on the right side, as shown in Figure 20.13.

Figure 20.13
Partially built Agency case study EAR.

You will package up the Web Service in an EJB-JAR file, so choose File, New, Enterprise Bean to create a new one. Click Next to skip the introduction screen and move onto the EJB-JAR file screen. You will be creating your New JAR Module in the Application called agency, so ensure that this option is selected. Next, under JAR Naming, enter "agency-session-ejb" as the File Name.

Now you can populate your EJB-JAR with the files you saw earlier. Under the Contents section, click the Edit button to display the Edit Contents of agency-session-ejb screen. Browse to find the class files (Service.class and ServiceBean.class), the WSDL file (AgencyService.wsdl), and the mapping file (mapping.xml). You will also need to add the interface definitions for the entity beans used that can be found under the folder Day20\exercise\classes\data. Add each of these files to the contents as shown in Figure 20.14 and click OK.

Figure 20.14
Adding class and configuration files to EJB-based Web Service.

Now click Next to move onto the General screen. Select agency.ServiceBean as your Enterprise Bean Class (this will be offered from the drop-down list). Ensure that the Enterprise Bean Type is set to Stateless Session. There is no need to define home, local or remote interfaces for this Web Service bean. So click Next to move to the Configuration Options screen.

Ensure that Expose Bean as Web Service Endpoint is selected and click Next.

On the Choose Service screen in the Service Definition section, select AgencyService.wsdl as your WSDL File and mapping.xml as your mapping file (these will be offered from the drop-down lists). The other fields will be populated based on the information in the files as shown in Figure 20.15.

Figure 20.15
Service definition for EJB-based Web Service.

Click Next to move on to the Web Service Endpoint screen. Select agency.Service as your Service Endpoint Interface. In the WSDL Port section, set the Namespace to be urn:J2EE21Agency and ensure that the Local Part becomes ServicePort. In the Sun-specific Settings section, set the Endpoint Address to be jaxrpc/ServiceBean as shown in Figure 20.16.

Figure 20.16
Endpoint configuration for EJB-based Web Service.

That completes the initial configuration, so click Next followed by Finish. You should be presented with a deploytool screen that looks like Figure 20.17.

Figure 20.17
EJB-based Web Service viewed in deploytool.