Example of creating a web service to query the number of items in a catalog

This example shows how to retrieve a simple piece of information (in this case, the number of items in a catalog) from IBM® Product Master by using the Java™ API.

1. Write the Java code. Here is an example of a simple web service that returns the number of items in a catalog:

   public class CatalogService
   {
       public static final int CATALOG_NULL = -1;
       public static final int CATALOG_ITEMS_NULL = -2;
       public static final int EXCEPTION_CAUGHT = -3;
   
       public int getNumberOfItemsInCatalog(String catalogName)
       {
           Context context = null;
           int result;
   
           try
           {
               context = PIMContextFactory.getContext("Joe", "passw0rd", "Acme");
               CatalogManager catalogManager = context.getCatalogManager();
               Catalog catalog = catalogManager.getCatalog(catalogName);
   
               if (catalog == null)
               {
                   return CATALOG_NULL;
               }
               else
               {
                   Collection<Item> items = catalog.getItems();
                   if (items == null)
                   {
                       return CATALOG_ITEMS_NULL;
                   }
                   else
                   {
                       result = items.size();
                   }
               }
           }
           catch (Exception e)
           {
               e.printStackTrace();
               return EXCEPTION_CAUGHT;
           }
   
           return result;
       }
   }
   

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: Type <definition/> to indicate that Product Master is to generate the WSDL for you.
      • 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.
      • Deployed: Select this check box. Clearing this selection enables you to store 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 the $TOP/etc/default/common.properties file. In this scenario, the password will not be 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 the common.properties file 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.
4. Test starting your web service. Your web service is now deployed and ready for use. You can develop a web service client to call your web service, but it is also possible as a quick test to start the web service in a web browser. Type
   http://YourWPCServer:YourWPCPort /services/ServiceName?method=getNumberOfItemsInCatalog&catalogName=YourCatalogName

   Where YourWPCServer and YourWPCPort is the URL for accessing your Product Master system, ServiceName is the name that you gave the web service when you deployed it to Product Master, and YourCatalogName is the catalog that you are querying.