Example of handling namespaces when you create a web service

This example shows how to handle namespaces when you create a web service. Depending on how you structure your code and use the Java2WSDL command to generate WSDL2Java, ensure a valid response is generated when the web service is deployed.

1. Generate the WSDD for the web service.
   1. Create a temporary directory to use while you generate the WSDL and WSDD.
      For example, type mkdir ws_tmp.
   2. Go to the temporary directory. Type cd ws_tmp.
   3. Add the Axis .jar files to your CLASSPATH so that you can run the Axis tools.

      set CLASSPATH=%CLASSPATH%;C:\Axis\lib\axis.jar;
      C:\Axis\lib\jaxrpc.jar;C:\Axis\lib\commons-logging-1.0.4.jar;
         C:\Axis\lib\commons-discovery-0.2.jar;C:\Axis\lib\wsdl4j-1.5.1.jar;
      C:\Axis\lib\saaj.jar;
      

      Note: This example code is for Windows; it differs on other platforms. Also, the directory for Axis might differ on your system. There is no line break in this command. Replace C:\Axis\lib with the location of your Axis lib directory.
   4. Ensure that the directory you are using for Java2WSDL has all the compiled classes and that the folder structure is consistent with the package structure.
      For example, com/acme/service/BookCatalogService.class and com/acme/service/to/Book.class.
   5. Run Java2WSDL to generate the WSDL that describes your web service, WSDD, and Helper Class. Type the following command:

      java org.apache.axis.wsdl.Java2WSDL -o BookCatalogService.wsdl -l 
      "http:// myWpcHost:9080/services/BookCatalogService"  
      com.acme.service.BookCatalogService -y WRAPPED -u LITERAL -d

      Do not include the line break. Where:

      • http://myWpcHost:9080/services/BookCatalogService is the URL for the service that you plan to deploy, in the format:

        http://wpcHostname:wpcPort/services/WebServiceName 

      • wpcHostname is the name that you give when you deploy the web service in the console.
      • com.acme.service.BookCatalogService is the fully qualified name of the Java™ class that implements the service.
      • BookCatalogService.wsdl is the output file name for the WSDL.
      • -y WRAPPED -u LITERAL ensures that the generated WSDL is wrapped-document and literal that is based, which is the correct type for IBM® Product Master literal document and literal deployments. For RPC and Encoding, use -y RPC -u ENCODED.
      • –d is for deployment. This parameter is for convenience, as it generates the WSDD and Helper classes also in the same step.
        Note: The Helper classes can also be generated by using the –H option with WSDL2Java command, but the –d option is more convenient.
      A WSDL document, WSDD, and a Helper class are created. The WSDL is in the ws_tmp folder. The deploy.wsdd is in the /com/acme/service directory, and the helper class for the response object, for example, Book_Helper.java, is in the /com/acme/service/to directory.
   6. Edit the WSDD file for use with Product Master. Open the generated WSDD document com/acme/service/deploy.wsdd where com/acme/service is the package name of the web service implementation class. Perform the following changes:
      • Change provider="java:RPC" to provider="java:WPCDocument". For document literal or for RPC and Encoded based services, use provider="java:WPCRPC". This change is required to ensure Product Master security. The Web Services Console does not save a service that is based on a default Axis provider because these services do not validate Product Master user names for authenticated services.
      • Ensure <parameter name="className" value="..."> has the form <parameter name="className" value="com.acme.service.BookCatalogService"> where the value= parameter is the fully qualified class name of the implementation class. If not, then modify it accordingly. The output XML is a valid WSDD document that can be entered into the WSDD field when you deploy the web service to Product Master.
   7. Copy the Book_Helper.java class to your web service project. Put it in the same folder as the Book.java class. Compile the project and export it as a .jar file.
   8. Clean up your directories. The entire ws_tmp directory can be cleaned up and deleted after the deploy.wsdd, BookCatalogService.wsdl files are copied elsewhere.
2. Deploy the user .jar file.

   For more information, see Deploying a third party or custom user .jar file.

3. Register the web service in Product Master.
   1. Access your Product Master instance and log in.
      For example: http://yourWPCserver:yourWPCport/utils/enterLogin.jsp.
   2. Click Collaboration Manager > Web Services > Web Service Console > New.
   3. Provide the following values:
      • Web Service Name: Provide a name. For example, CatalogService.
      • WSDL: Copy and paste the entire contents of BookCatalogService.wsdl into the WSDL field.
      • Web Service Implementation: Select Java.
      • Java Implementation Class: Type the Java class of your web service. For the above example, you type com.acme.javawbs.CatalogService.
      • WSDD: Copy and paste the entire contents of your edited copy of deploy.wsdd into the WSDD field.
      • Deployed: Select this check box. Clearing this selection stores the web services in an inactive (unusable) state.
      • Authenticated: Do not select this check box.

        Authenticated means that the web service expects a user name and password to be supplied. This is done through an Axis menu dialog if you are calling the web service through the web browser, or if you are using a custom Java client then the user name and password must be included in the SOAP header. The correct format for an Axis user name is "User@Company" for example "Joe@Acme".

        Unauthenticated means that the web service contacts Product Master using the user name and company that is specified in the soap_company and soap_user fields in $TOP/etc/default/common.properties. In this scenario, the password is not checked. Only the administrator should have access to change files on the Product Master server, so this is not constituted a security risk. To protect against unauthorized access, administrators should ensure that the SOAP company and user that are specified for Product Master in common.properties should not be an Admin user.

        The two fields can be kept blank to disable unauthenticated access completely.

        If the service cannot be authenticated, a SOAP fault is returned in the message body.

   4. Click Save. If you get an error similar to: Unable to verify Java implementation class, and you have no typographical errors in your fully qualified Java class name, then you did not successfully deploy your Java class through the user .jar mechanism. Return to Step 2 and check whether your user .jar appears in your class path.
      For example, ps -ef | grep java and check the Java process for Product Master. Your web service is now deployed.
4. Access the web service through the service URL, or generate your own Java application client. Y

   For more information, see Example of creating a web service that uses a business object and complex logic.

   ou can now write a Java client application that starts your web service through the generated Java proxy, which enables you to write business logic easily. Here is an example of some client code:

   /**
    * Test the BookCatalogService via a generated proxy.
    */
   public class BookCatalogApplication {
   
       public static void main(String[] args)
    {
           BookCatalogServiceProxy bookCatalogServiceProxy = new BookCatalogServiceProxy();
           try {
               Book book = bookCatalogServiceProxy.getBookFromCatalog("BookCatalog", "140035206");
               System.out.println("Got the Book instance as : " + book);
               if(book != null){
                   System.out.println("ISBN : " + book.getISBN());
                   System.out.println("Author : " + book.getAuthor());
                   System.out.println("Description : " + book.getDescription());
                   System.out.println("Price : " + book.getPrice());
                   System.out.println("StockLevel : " + book.getStockLevel());
               }
           } catch (RemoteException e) {
               e.printStackTrace();
           }
       }
   }