33.4 Publishing Application Modules as Web Services

Oracle ADF Business Components application modules offer built-in support for web services. Any custom method that you add to the client interface of your application module appears on its web service interface after you enable the optional web service deployment option.

33.4.1 How to Enable the J2EE Web Service Option for an Application Module

To enable your application module as a web service:

1. Enable a custom Java class for your application module and add to it one or more custom methods that you want to appear on the web service interface.

2. Open the Application Module editor and on the Client Interface tab, select one or more custom methods to appear on the client interface.

3. With the Application Module editor still open, on the Remote panel, select Remoteable Application Module, select J2EE Web Service in the Available list and shuttle it to the selected list.

4. Then click OK to save your changes.

33.4.2 What Happens When You Enable the J2EE Web Service Option

Once this J2EE Web Service remoteable option of your application module is enabled, every time you dismiss the Application Module editor, JDeveloper synchronizes your web service classes with any changes you made to the application module's client interface.

JDeveloper creates the generated web service class in the server.webservice subpackage of the package where your application module resides. For example, if you application module were named oracle.srdemo.model.SRService, its generated web service class would be named SRServiceServer in the oracle.srdemo.model.server.webservice package.

For each method named someMethod in your application module's client interface, JDeveloper adds a delegator method in the generated web service class that looks like what you see in Example 33-10. The code performs the following basic steps:

1. Acquires an application module instance from the pool.

2. Delegates the web service method call to the application module instance.

3. Returns the result if the method is non-void.

4. Releases the application module instance to the pool without removing it.

Since the web service code passes false to the releaseRootApplicationModule method of the Configuration object, the application module instance is not removed and remains in the pool ready to handle the next incoming stateless web service method invocation. Then the application pool grows and shrinks with load in the same way the web application will. The only difference is that here the pool is being used in a totally stateless way. For more information on tuning the application module pool, see Chapter 29, "Understanding Application Module Pooling".

Example 33-10 Generated Code for Each Method in Application Module Client Interface

// In YourAppModuleServer.java generated web service class
  :
  public void someMethod(int p1, String p2) {
    AppModuleImpl _am = null;
    try {
    // 1. Acquire an application module instance from the pool
      _am = (AppModuleImpl)Configuration.createRootApplicationModule(
              "com.yourcompany.yourapp.YourAppModule",                "YourAppModuleLocal");
   // 2. Delegate a call to its someMethod() method, passing arguments
      _am.someMethod(p1, p2);
   // 3. If return of method is non-void, return the result here 
    } finally {
      if (_am != null) {
        // 4. Release application module to the pool, without removing it
        Configuration.releaseRootApplicationModule(_am, false);
      }
    }
  :
  }

33.4.3 What You May Need to Know About Deploying an Application Module as a Web Service

JDeveloper creates a web service deployment profile as part of enabling the web service remote option on your application module. To deploy the service, just select Deploy from the context menu of this deployment profile.

33.4.4 What You May Need to Know About Data Types Supported for Web Service Methods

Your custom method parameters and return types can use any datatype that implements the java.io.Serializable interface. This excludes the use of any generic ADF Business Components interfaces from the oracle.jbo package like Row or ViewObject. While these types are allowed on the custom interface of an application module, in general, they are not supported for web services. To return collections of data through a web service interface, you will need to create custom data transfer objects that implement the Serializable interface and populate them from the results of your view object query results before returning them in an array.

For example, if you needed to return a single row of the ServiceRequests view object instance in the SRDemo application's SRService application module, you would need to create a new ServiceRequest bean with appropriate bean properties and corresponding getter and setter methods. This class would need to implement the Serializable interface. Since this is just a marker interface, there is no additional implementation required other than adding the implements Serializable keywords to the class definition. Once you have created this bean, you can populate its properties inside the custom method implementation, and then return it as the return value of a custom service method like:

public ServiceRequest findServiceRequest(int svrid)

If you need to return a collection of serializable objects, you can use any type supported by the web service infrastructure. For example, you could return an array of one or more service requests using a custom method signature like:

public ServiceRequest[] findServiceRequests(String status, String technician)