Procedure 5.1. Generating Web Service Class code from STAR WSDL

1. Retrieve WSDL from Star Schema Repository and extract the StarTransport_2005.wsdl file.

   Figure 5.1. WSDL Extract

   
   
   

2. Open Visual Studio 2003 command prompt.

   Figure 5.2. Visual Studio 2003 Command Prompt

   
   
   

3. Run wsdl.exe against the extracted WSDL file.  By default WSDL generated codes are generated in C# language. You can optionally specify the target language to ‘VB’ (Visual Basic) by using the /language parameter. Make sure to execute this command where you have extracted the STAR WSDL.

   wsdl startransport_2005.wsdl /language:VB
         

Procedure 5.2. Creating the ASP.Net Web Service

1. Open up the Visual Studio .Net 2003 and create a new ASP.Net Web Service Project.

   Figure 5.3. Create ASP.NET Web Service

   
   
   

2. Rename the Service1.asmx file to StarWebService.asmx.

   Figure 5.4. Rename Service1.asmx

   
   
   

3. Copy contents of generated GenericWebService.vb to the code behind of your new web service page.

4. Rename the Class name to StarWebService

   Figure 5.5. Rename StarWebService

   
   
   

5. Set the URL in the class constructor to the actual URL of the web service.

   Figure 5.6. Set URL for Web Service

   
   
   

6. Add a WebMethod attribute for each of the STAR WebMethods.

   Figure 5.7. Add Web Method to ProcessMessage

   
   
   

   Figure 5.8. Add Web Method to Pull Message

   
   
   

   Figure 5.9. Add Web Method to Put Message

   
   
   

7. Replace the ProcessMessage function’s code with the following line:

   Figure 5.10. Update Process Message

   
   
   

8. Insert the following function anywhere inside the class code.

   Figure 5.11. Add Playload Response

   
   
   

9. Modify the ASMX file to refence the StarWebService Class.

   Figure 5.12. Modify ASMX Web Service

   
   
   

10. Compile the code and run.  You should now have a web service that has all three STAR Methods.

    Figure 5.13. Deployed Web Service

    
    
    

Procedure 5.3. Creating Web Service Client

1. Create a new windows application project.

   Figure 5.14. Create .NET Client

   
   
   

2. Create a Windows form that has the following layout:

   Figure 5.15. Create Windows Form

   
   
   

3. Add a web reference to the star web service you’ve previously created.

   Figure 5.16. Add Web Reference

   
   
   

4. Create a function that would process the request BOD.

   Figure 5.17. Create Function Process Request

   
   
   

5. Recompile the Client Code.

Procedure 5.4. Running the Client and Web Service Code

1. Run the windows application code and copy any STAR BOD examples from the Repository's example folder to the Input BOD text box.

   Figure 5.18. Copy sample BOD

   
   
   

2. Click on the Submit button and examine the output BOD and Content IDs in the Diagnostic Textbox.

   Figure 5.19. Client Results

   
   
   

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.