Procedure 6.1. Add Address Information to the WSDL

1. If the WSDL was retrieved from STAR repository, the service information in the WSDL is incomplete. It must be changed to reflect your Web Service implementation. An unmodified WSDL will have an XML comment beginning with “Note to implementors…” along with an example of what the address information should look like. The example below is based off of the ProcessRetailDeliveryReporting.wsdl in Rev5.2.1. Assuming you are running a local instance of Tomcat, with 8080 as your HTTP port, the service information will look like the following:

   Example 6.1. Sample Service

   <wsdl:service name="ProcessRetailDeliveryReportingWebService">
      <wsdl:port name="ProcessRetailDeliveryReportingStarTransport" binding="starbindings:starTransport">
         <soap:address location="http://localhost:8080/StarQuickStartService/StarTransport/"/>
      </wsdl:port>
   </wsdl:service>
           

   
   

   Once the WSDL has been edited with the address information, it can be used by wsimport to produce source for the service and client, as well as classes for JAXB marshalling and unmarshalling.

2. At a windows command prompt, move to the <JAX-WS Install Directory>\jaxws-ri\bin directory. Execute the wsimport script. Be sure to set the output location for the source (-s) since the default behavior is to produce compiled code. This location must already exist since the script will not create the directory for you. It will give an error, “directory not found…” if the directory does not exist. Also, if you run into memory errors, edit the wsimport.bat script to increase the Java heap size. For this example the initial and maximum values were increased to 512MB, so the launch section of the wsimport.bat script looked like this (edited section in bold):

   %JAVA% %WSIMPORT_OPTS% -Xms512M -Xmx512M -jar "%JAXWS_HOME%\lib\jaxws-tools.jar" %*
       

   Example 6.2. Example WSImport command

   wsimport -d classes -s src -verbose C:\JAX-WS\jaxws-ri\bin\STAR\Rev5.1.2\WSDL\ProcessRetailDeliveryReporting.wsdl > results.txt   
           

   
   

3. Import the generated source into a WAR, adding the necessary jar files from <JAX-WS Install Directory>\jaxws-ri\lib

   Figure 6.1. Import Source

   
   
   

4. Create the Web Service implementation class. This class can implement the StarTransportPortTypes interface that was created by wsimport. It is not required that it implement the interface, though it may help if using an IDE since the IDE can generate the inherited abstract methods. For this example, I called my class ProcessRetailDeliveryReportingWebServiceImpl. Once this class is created, add an annotation above the class declaration to refer to the endpointInterface:

   @javax.jws.WebService (endpointInterface="org.starstandards.webservices._2005._10.transport.bindings.StarTransportPortTypes")  
       

5. For now, only add print statements to the implementation class so you can tell when you have called the method via the client that we will soon create. Below is how your ProcessRetailDeliverWebServiceImpl class should currently look:

   package org.starstandards.webservices._2005._10.transport.bindings;
   
   import org.starstandards.webservices._2005._10.transport.AcknowledgeRetailDeliveryReportingPayload;
   import org.starstandards.webservices._2005._10.transport.ProcessRetailDeliveryReportingPayload;
   
   @javax.jws.WebService (endpointInterface="org.starstandards.webservices._2005._10.transport.bindings.StarTransportPortTypes")
   public class ProcessRetailDeliveryReportingWebServiceImpl implements
                   StarTransportPortTypes {
   
           public AcknowledgeRetailDeliveryReportingPayload processMessage(
                           ProcessRetailDeliveryReportingPayload payload) {
                   System.out.println("Called processMessage");
                   return null;
           }
   
           @SuppressWarnings("unchecked")
           public AcknowledgeRetailDeliveryReportingPayload pullMessage()
           {
               System.out.println("Called pullMessage!");
               return null;
           }
   
           public void putMessage(ProcessRetailDeliveryReportingPayload payload) {
                   System.out.println("Called putMessage");
           }
   }
       

Procedure 6.2. Create the sun-jaxws.xml

1. Now it’s time to create the sun-jaxws.xml. This file resides in the same location as the web.xml, the WEB-INF folder. Below is the content of the file for this example:

   Example 6.3. sun-jaxws.xml

   <?xml version="1.0" encoding="UTF-8"?>
   <endpoints xmlns="http://java.sun.com/xml/ns/jax-ws/ri/runtime" version="2.0">
      <endpoint 
            name="starTransportPortTypes" 
            interface="org.starstandards.webservices._2005._10.transport.bindings.StarTransportPortTypes"
            implementation="org.starstandards.webservices._2005._10.transport.bindings.ProcessRetailDeliveryReportingWebServiceImpl"
            url-pattern="/StarTransport"
     />
   </endpoints>
           

   
   

   	Note
   	Note that the endpoint name is the same as the name that you see on the Java annotation from the StarTransportPortTypes class. Also, the interface and implementation classes are provided. The url-pattern provided must match what is in the web.xml file.

2. The service is now ready to deploy. Deploy the WAR to Tomcat or the application server you are working with. You can confirm installation by accessing the service’s URL. For this example, the service can be accessed at http://localhost:8080/StarQuickStartServiceJAXWS/StarTransport in a browser. The following should be returned:

   Figure 6.2. JAX-WS Deploy Endpoint

   
   
   

Procedure 6.3. Create JAX-WS Client

1. Now it is time to create the client. Since the client uses the same source files generated by wsimport that were used for the service, the only item to create is a new class and method that will use the generated code to call the service. Below is an example of a test client that calls the PullMessage method. Since there is currently no implementation code in our service, we will at least see the print statement (“Called pullMessage”) from the service printed to the standard output of the application server. Until implementation code is added to the service to return a valid response, this client will throw an exception.

   package org.star.quickstart.client;
   
   import org.openapplications.oagis._9.unqualifieddatatypes._1.IdentifierType;
   import org.starstandard.star._5.AcknowledgeRetailDeliveryReportingType;
   import org.starstandard.star._5.ApplicationAreaType;
   import org.starstandards.webservices._2005._10.transport.AcknowledgeRetailDeliveryReportingContent;
   import org.starstandards.webservices._2005._10.transport.AcknowledgeRetailDeliveryReportingPayload;
   import org.starstandards.webservices._2005._10.transport.bindings.ProcessRetailDeliveryReportingWebService;
   import org.starstandards.webservices._2005._10.transport.bindings.StarTransportPortTypes;
   
   public class TestClient {
       public static void main(String[] args)
       {
          ProcessRetailDeliveryReportingWebService stub = new ProcessRetailDeliveryReportingWebService();
          StarTransportPortTypes port = stub.getProcessRetailDeliveryReportingStarTransport();
              ((javax.xml.ws.BindingProvider)port).getRequestContext().put(javax.xml.ws.BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "http://localhost:8080/StarQuickStartServiceJAXWS/StarTransport");
          AcknowledgeRetailDeliveryReportingPayload payload = port.pullMessage();
          AcknowledgeRetailDeliveryReportingContent content = payload.getContent().get(0);
          AcknowledgeRetailDeliveryReportingType bod = content.getAcknowledgeRetailDeliveryReporting();
          ApplicationAreaType applicationArea = bod.getApplicationArea();
          IdentifierType BODID = applicationArea.getBODID();
          System.out.println("BODID returned: " + BODID.getValue());
       }
   }
         

2. Once you have created the TestClient class, execute the main method and verify that “pullMessage” has been written to the application server logs by the service.

3. Now that we have verified that the client can communicate to the service, we can add some JAXB unmarshalling code to service to simulate producing a valid response. Similarly, we can add marshalling code to the client to print out the AcknowledgeRetailDeliveryReporting BOD returned from the service.

   Below is the code added to the pullMessage method of the service implementation class. In this example, the BOD is being read straight from the “examples” directory of a STAR repository. Using the JAXB unmarshaller, the xml data from the file is placed into the Java objects reference by the AcknowledgeRetailDeliveryReportingType class.

   @SuppressWarnings("unchecked")
       public AcknowledgeRetailDeliveryReportingPayload pullMessage()
       {
            System.out.println("Called pullMessage!");
            AcknowledgeRetailDeliveryReportingPayload response = new AcknowledgeRetailDeliveryReportingPayload();
            AcknowledgeRetailDeliveryReportingContent content = new AcknowledgeRetailDeliveryReportingContent();
   
            try
            {
               JAXBContext jaxbContext = JAXBContext.newInstance("org.starstandard.star._5");
               Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();
               JAXBElement<AcknowledgeRetailDeliveryReportingType> bod = 
                   (JAXBElement<AcknowledgeRetailDeliveryReportingType>) unmarshaller.unmarshal(new File("C:\\jaxws-ri\\bin\\STAR\\Rev5.2.1\\BODExamples\\AcknowledgeRetailDeliveryReporting.xml"));
   
               content.setAcknowledgeRetailDeliveryReporting(bod.getValue());
            }
              catch(Exception e)
              {
                 e.printStackTrace();
              }
   
           response.getContent().add(content);
   
           return response;
   }
         

4. Before adding the marshalling code to the client, deploy the service again with the updated implementation code from above. Invoke the service with the TestClient created earlier. If successful, the BOD Id will be printed.

   Below is the code added to the TestClient to take the results from the PullMessage call and print the resulting XML to the standard output stream. The JAXB marshaller is used to get the XML content from the Java object.

   package org.star.quickstart.client;
   
   import java.io.StringWriter;
   
   import javax.xml.bind.JAXBContext;
   import javax.xml.bind.JAXBElement;
   import javax.xml.bind.Marshaller;
   
   import org.starstandard.star._5.AcknowledgeRetailDeliveryReportingType;
   import org.starstandards.webservices._2005._10.transport.AcknowledgeRetailDeliveryReportingContent;
   import org.starstandards.webservices._2005._10.transport.AcknowledgeRetailDeliveryReportingPayload;
   import org.starstandards.webservices._2005._10.transport.bindings.ProcessRetailDeliveryReportingWebService;
   import org.starstandards.webservices._2005._10.transport.bindings.StarTransportPortTypes;
   
   public class TestClient {
   
       public static void main(String[] args) 
       {
          ProcessRetailDeliveryReportingWebService stub = new ProcessRetailDeliveryReportingWebService();
          StarTransportPortTypes port = stub.getProcessRetailDeliveryReportingStarTransport();
              ((javax.xml.ws.BindingProvider)port).getRequestContext().put(javax.xml.ws.BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "http://localhost:8080/StarQuickStartServiceJAXWS/StarTransport");
          AcknowledgeRetailDeliveryReportingPayload payload = port.pullMessage();
          AcknowledgeRetailDeliveryReportingContent content = payload.getContent().get(0);
          AcknowledgeRetailDeliveryReportingType bod = content.getAcknowledgeRetailDeliveryReporting();
   
          try
          {
             JAXBContext jaxbContext = JAXBContext.newInstance("org.starstandard.star._5");
             Marshaller marshaller = jaxbContext.createMarshaller();
   
             JAXBElement<AcknowledgeRetailDeliveryReportingType> processRetailDeliveryReportingElement =
                   (new org.starstandard.star._5.ObjectFactory()).createAcknowledgeRetailDeliveryReporting(bod);
             marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);
             StringWriter writer = new StringWriter();
             marshaller.marshal( processRetailDeliveryReportingElement, writer );
             String xmlStr = writer.toString();
   
             System.out.println(xmlStr);
          }
          catch(Exception e)
          {
             e.printStackTrace();
          }
   
       }
   }
         

5. After adding this code to the TestClient class, run the main method again. Now the entire AcknowledgeRetailDeliveryReporting BOD will be printed.