You edit the application module in JDeveloper to create a web service interface that exposes the top-level view objects and defines the available service operations it supports. Top-level view objects that you may service-enable and make accessible by the service client are:

• View instances of standalone view objects (does not participate in a hierarchical relationship)

• Master view instances of master-detail related view objects (does not include the child view instance)

• View instances of view objects that extend a parent view object (must not include a subtype discriminator attribute to define a polymorphic view object)

View objects that do not automatically participate in the service interface are:

• Child view instances of master-detail related view objects

  You can add child view objects individually to the service interface. For information on how to create SDO classes for child view objects, see How to Service-Enable Individual View Objects.

• View instances of polymorphic view objects (as defined by a subtype discriminator attribute)

  In JDeveloper, you can create a web service proxy client to access and manipulate for polymorphic view objects. For an example of a JAX-WS client, see Accessing Polymorphic Collections in the Consuming Application.

The primary purpose of the standard service operations is to expose data manipulation operations on the view objects. Any business logic that you have defined on the underlying framework objects (for example, business rule validation) will be applied when you invoke a standard service operation.

Table 15-1 shows the list of standard operations that service view instances support.

Additionally, several built-in methods can be optionally added to the client service interface of the application module (AppModuleService.java). Table 15-2 shows the list of built-in methods that provide runtime support for service view instances that you enable.

Before you begin:

It may be helpful to have an understanding of how the SDO framework supports service-enabled ADF application modules and enables web service clients to access rows of data and perform service operations. For more information, see Publishing Service-Enabled Application Modules.

When you create the service-enabled application module, do not create it in a project that already contains a standard web service (a Java class or interface with the @WebService annotation). JDeveloper deployment profiles do not support deploying a standard web service and an ADF Business Service web service from the same project. If you attempt to deploy the ADF Business Service web service from the same project as a standard web service, the deployment will fail with an Oracle WebLogic Server exception error.

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Additional Functionality for Service-Enabled Application Modules.

You will need to complete these tasks:

• Create the desired view objects, as described in How to Create an Entity-Based View Object and How to Create a Custom SQL Mode View Object.

• Create the desired application module, as described in How to Create an Application Module.

• Optionally, set JDeveloper preferences to specify a default suffix for the names of generated SDO classes, modify the default subpackage where the service interface and classes reside, and set the default namespace prefix for the generated SDO schema and web service, as described in How to Set Preferences for Generating the ADF Web Service Interface.

• If you want to expose custom find operations on the service, create declarative view criteria to specify the custom query, as described in How to Create Named View Criteria Declaratively.

To create the web service interface:

1. In the Applications window, double-click the application module.

2. In the overview editor, click the Service Interface navigation tab and then click the Enable support for Service Interface button.

   Use the Create Service Interface wizard to configure the desired options.

3. In Create Service Interface wizard, on the Service Interface page, enter the name and target namespace for the web service.

   The target namespace is a URI for the service that you can assign to group similar services together by entering the same URI. The default target namespace is the package name of the application module combined with package names that you specify in the Preferences dialog.

   Tip:

   You can define JDeveloper preferences that will shape the URI and allow you to define a unique target namespace for your service. For details about namespace URI shaping preferences, see How to Set Preferences for Generating the ADF Web Service Interface.

4. To expose the methods of the application module as asynchronous service methods and enable both synchronous and asynchronous operations on the web service, select Generate Asynchronous Web Service Methods.

   By default, the web service supports synchronous service methods. This forces the invoking client application to wait for the response to return before it can continue with its work. In cases where the response returns immediately, this method of invoking the web service is common. However, because request processing can be delayed, it is often useful for the client application to continue its work and to handle the response later on.

5. The Service Categories list will appear empty unless role shaping has been defined based on previously defined customization roles. Leave the Selected list empty unless your organization is classifying services.

   This feature has no impact on the service WSDL file and has no relevance to the operation of web services.

6. On the Service Built-in Methods page, optionally, select Generate Object and Attribute Control Hints Operation to generate a method that will return the static control hints (UI hints) defined on a view instance and its attributes.

   When you enable this option, the wizard adds the getDfltObjAttrHints() method to the client service interface (AppModuleService.java). The web service consuming application can invoke this method to resolve UI hints on the server without requiring a database roundtrip. The method takes a service view object name and a locale name and returns the base UI hints, including object and attribute display name labels, for an object based on a specific locale. If the locale name is not specified, the method uses the default locale.

7. Optionally, select Generate Last Update Time Operation to generate a method that will return the last modified time for the service schema files.

   When you enable this option, the wizard adds the getServiceLastUpdateTime() method to the client service interface (AppModuleService.java). Before any customization occurs, this method returns the file timestamp of the last updated schema file. When a schema is customized at runtime, the last-update timestamp is updated, and this latest timestamp will be returned. This feature is primarily useful in web service consuming applications that cache the service XSD.

8. Optionally, select Generate Entity List Operation to generate a method that will return the list of service view instances.

   When you enable this option, the wizard adds the getEntityList() method to the client service interface (AppModuleService.java). The method returns the list of service view instance names, XSD type, and flags that indicate whether the service view supports Create, Update, Merge, and Delete operations. This feature is primarily useful in web service consuming applications that require customization.

9. On the Service Custom Methods page, add the custom methods you want to expose in the service interface and define the data types of each method's parameters and return value.

   The parameters and non-void return value of the custom service methods you enable must be one of the service-interface supported data types, such as a Java primitive type, or a list of the service-interface supported data types (including oracle.jbo.server.ViewRowImpl, java.util.List<ViewRowImpl>, oracle.jbo.AttributeList, java.util.List<AttributeList>, or java.util.List<PrimitiveType>).

   Note that although both ViewRowImpl and AttributeList data types expose the identical row structure to the web service client, at runtime there will be a fundamental difference. For a description of the supported data types, see What You May Need to Know About Method Signatures on the ADF Web Service Interface.

   After selecting a qualifying custom method to appear in the service interface, for each parameter and return value using the ViewRowImpl or AttributeList data type, you must in turn select the name of the view object instance corresponding to the row structure:

   1. In the Selected list, expand return or parameters and select the item.

   2. Enter the Java element data type in Element Java Type.

   3. In the case where the Java element type is ViewRowImpl or AttributeList, enter the view object instance name to identify the row structure in Element View Object.

      For example, if you define a custom method to return a single row of the CustomerInfo view object instance, you would need a custom method signature like this:

      public ViewRowImpl findCustomerInfo(int id)
      

      Then, after selecting the findCustomerInfo() custom method to appear in the service interface, you would select its return value in the tree and configure its View Object property to be CustomerInfo, the view instance name whose row structure should be used at runtime.

10. To expose service information messages for a custom method or warnings for process operation methods, select Include Warnings in Return Service Data Object.

    For example, you might want to display an informational message when a method returns the total employee compensation and the total is outside of the desired range.

    If Include Warnings is not selected, no informational messages will be returned with the service response.

    This option is only enabled when the method does not return a view row or a list of view rows. When the method returns view rows, the underlying view object determines whether the method supports warnings, as described How to Service-Enable Individual View Objects.

    The informational messages (and warnings) are reported as part of the return object. JDeveloper generates appropriate wrappers as the return objects, and the wrappers contain the actual method return and the informational messages.

11. On the Service View Instances page, select the top-level view instances in the application module that you want to expose in the service interface.

    View object subtypes of the top-level view instance will automatically be service-enabled.

    Also, on this page, you can enable the available data manipulation operations supported on the exposed methods, as shown in Figure 15-1.

    Figure 15-1 View Instances and CRUD Operation Selection

    

12. In the Basic Operations tab, select the data manipulation operations for the currently selected view instance and in the Method Name field, change the names of the selected service operations to the names that you prefer to expose in the service interface.

    The primary purpose of the standard service operations is to expose data manipulation operations on the view objects. Any business logic that you have defined on the underlying framework objects (for example, business rule validation) will be applied when you invoke the service operations. For a description of the operations that service view instances support, see Table 15-1.

    In the case of the find method operation that you can select, the find method must not reference a required bind variable in the view object's query statement. A required bind variable is one that makes the query execution dependent on the availability of a valid value for the bind variable. The service interface does not expose required bind variables at runtime. For details about defining a find operation for this scenario, see How to Expose a Declarative Find Operation Filtered By a Required Bind Variable.

13. To expose declarative find operations, select the View Criteria Find Operations tab and click the Add View Criteria icon.

    You can define custom find operations when you want the service to support executing a predefined query. For information about defining a named view criteria, see Working with Named View Criteria.

    Caution:

    The service interface find operations are based on specific view criteria that your project defines. This means that the bind variables of the view criteria must match the parameters of the corresponding find operation method. If you change the number or order of the bind variables after the find operation is defined and the service interface generated, the corresponding method will not execute at runtime. Therefore, after changing the underlying view criteria, you must regenerate the service interface.

    1. In the Configure View Criteria Find Operation dialog, choose the named view criteria for the find operation.

       The dialog displays the list of view criteria exposed by the referenced view object. For example, OrdersView defines OrdersViewCriteria with a bind variable OrdId that specifies the order ID, as shown in Figure 15-2.

       Figure 15-2 Specialized Find Methods Based on Named View Criteria

       

    2. If the view criteria uses a bind variable, you can double-click the XML name to customize the name as it will appear in the XML definition for the service.

14. Click Next to review the custom methods that your service view instances will expose.

15. Click Finish.

As a result of enabling the web service interface using the overview editor for the application module, JDeveloper automatically enables your parent view instance selections as Service Data Object (SDO) components. The generated SDO components for each view instance will reference the same namespace and will be configured with the same settings for options such as whether or not warnings are supported. You can use the Java page of the overview editor to customize the SDO definition of these existing service-enabled view objects. You can also use the Java page to service-enable view objects that were not added already to the service interface. For example, if you selected a parent view object that represents the master in a master-detail relationship, the child view object will not be automatically service-enabled. You can use the Java page of the overview editor for the child view object to individually add it to the service interface.

You use the Java page of the overview editor for the view object to configure the SDO name and namespace for a view object, or to selectively service-enable child view objects.

Before you begin:

It may be helpful to have an understanding of how the SDO framework supports service-enabled ADF view objects and enables web service clients to access rows of data and perform service operations. For more information, see Publishing Service-Enabled Application Modules.

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Additional Functionality for Service-Enabled Application Modules.

You will need to complete these tasks:

1. Create the desired view objects, as described in How to Create an Entity-Based View Object, and How to Create a Custom SQL Mode View Object.

2. Enable the service interface for the application module, as described in How to Enable the Application Module Service Interface.

3. Optionally, set JDeveloper preferences to specify a default suffix for the names of generated SDO classes, modify the default subpackage where the service interface and classes reside, and set the default namespace prefix for the generated SDO schema and web service, as described in How to Set Preferences for Generating the ADF Web Service Interface.

To set the SDO name and namespace for a view object:

When your data model defines master-detail relationships between parent and child view objects, the service operations that you enable for the master view object may not automatically be executed on the detail view object. Post operations on the detail view object are supported by default when the primary source entity object of the master view object is composed with the primary destination entity object of the detail view object. This master-detail relationship is known as a composition association and is created in JDeveloper when the source entity object contains the destination entity object as a logical, nested part, as described in What You May Need to Know About Composition Associations.

To support create/merge/update/process methods that post child details along with the parent, you will need to create a view link to define the master-detail relationship according to one of these scenarios:

• The view link uses the composition association, then post operations on the detail view object are supported by default.

• The view link is based on an association, and the association has the destination accessor generated, and the association has a custom property SERVICE_PROCESS_CHILDREN=true defined.

• The view link is not based on an association but has a custom property SERVICE_PROCESS_CHILDREN=true defined.

The custom property provides an alternative to using a composition association that makes it convenient to support nested processing for any view objects with a view link defined. You can define SERVICE_PROCESS_CHILDREN as a custom property in the overview editor for either the view link or the view link's association (when present).

To support get and find methods that retrieve child details along with the parent, the view link between the master and detail view objects must have the destination accessor generated. The destination accessor permits traversal of the hierarchy from the master to the detail view object.

Before you begin:

It may be helpful to have an understanding of how the SDO framework supports service-enabled ADF view objects and enables web service clients to access rows of data and perform service operations. For more information, see Publishing Service-Enabled Application Modules.

You may also find it helpful to have an understanding of how master-detail relationships are defined using view links or entity associations:

• For more information about view links, see Working with Multiple Tables in a Master-Detail Hierarchy.

• For more information about associations, see Creating and Configuring Associations.

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Additional Functionality for Service-Enabled Application Modules.

You will need to complete these tasks:

1. Create the desired view objects and service-enable the child view object in the master-detail hierarchy, as described in How to Service-Enable Individual View Objects.

2. If the view link is not based on an association, confirm that a destination accessor exists for the view link by opening the view link in the overview editor and viewing the Relationship page. To generate the accessor so it appears in the Relationship page, click the Edit Accessors button, and then, in the View Link Properties dialog, select Generate Accessor in View Object for the destination accessor.

   If the view link is based on an association, then the destination accessor must exist for the association's destination entity object. To generate one, use the Relationship page of the overview editor for the association.

To support nested processing in a master-detail hierarchy:

The ADF service interface framework allows you to expose declarative find operations to execute the query define by a view object you select. However, when that query uses a bind variable to filter the query results, the bind variable must not be specified as Required and Updatable. Because the service interface does not expose required, updatable bind variables, a find operation that you execute for such a view object would fail to return any result.

When you want to filter a query result using bind parameters, use the view criteria and expose it as a find operation on the service interface. A service interface find operation based on a view criteria that you create can specify required bind variables.

Before you begin:

It may be helpful to have an understanding of how the SDO framework supports service-enabled ADF view objects and enables web service clients to access rows of data and perform service operations. For more information, see Publishing Service-Enabled Application Modules.

You may also find it helpful to have an understanding of how to filter view object queries using bind variables. For more information, see Working with Bind Variables.

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Additional Functionality for Service-Enabled Application Modules.

You will need to complete these tasks:

1. Create the desired application module, as described in How to Create an Application Module.

2. Create the view criteria, as described in How to Create Named View Criteria Declaratively. In the Edit View Criteria dialog, set the criteria item as a bind variable and set the Validation field to Required. This selection ensures that the query will not execute without a valid value.

To expose a find operation for a view criteria with required bind variable:

As an alternative to exposing a declarative find operation that relies on a view criteria, you can define a service method in your data model project's application module implementation class. The class you create for this purpose allows you to encapsulate business service functionality into a single method that you implement. For details about the purpose of the custom application module implementation class, see Customizing an Application Module with Service Methods.

The following example shows a custom find method implemented in the AppModuleNameImpl.java file to set the bind variable and execute the view object instance query. It uses setNamedWhereClauseParam() on the view object instance to set the bind variable. Before executing the query, the find method sets the view object in forward-only mode to prevent caching the view rows that the find method iterates over.

public class AppModuleImpl extends ApplicationModuleImpl
{
   public List<ViewRowImpl> findProducts(String location)
   {
      List<ViewRowImpl> result = new ArrayList<ViewRowImpl>();
      ViewObjectImpl vo = getProductsView1();
      vo.setNamedWhereClauseParam("TheLocation", location);
      vo.setForwardOnly(true);
      vo.executeQuery();
      while (vo.hasNext()) {
        result.add((ViewRowImpl)vo.next());
      }
      return result;
   }
}

Before you begin:

It may be helpful to have an understanding of how the SDO framework supports service-enabled view objects and enables web service clients to access rows of data and perform service operations. For more information, see Publishing Service-Enabled Application Modules.

You may also find it helpful to have an understanding of how to filter view object queries using bind variables. For more information, see Working with Bind Variables.

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Additional Functionality for Service-Enabled Application Modules.

You will need to complete these tasks:

1. Create the custom application module class, as described in How to Generate a Custom Class for an Application Module.

2. Create the custom find method to programmatically filter a query result and set the required bind variable, as described in How to Add a WHERE Clause with Named Bind Variables at Runtime.

To expose a find method that sets a required bind variable:

By default, the web service supports synchronous service methods. This forces the invoking client application to wait for the response to return before it can continue with its work. In cases where the response returns immediately, this method of invoking the web service is common. However, because request processing can be delayed, it is often useful for the client application to continue its work and to handle the response later on.

Before you begin:

It may be helpful to have an understanding of how the SDO framework supports service-enabled view objects and enables web service clients to access rows of data and perform service operations. For more information, see Publishing Service-Enabled Application Modules.

You may also find it helpful to have an understanding of invoking web services using asynchronous request-response. For more information, see the "Overview of Asynchronous Web Services" section of the "Developing Asynchronous Web Services" chapter in Developing Oracle Infrastructure Web Services.

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Additional Functionality for Service-Enabled Application Modules.

You will need to complete this task:

• Before you can deploy an asynchronous web service, you must configure the queues used to store the request and response. For information about configuring the request and response queues, see the "Creating the Request and Response Queues" section of the "Developing Asynchronous Web Services" chapter in Developing Oracle Infrastructure Web Services.

To expose asynchronous web service methods:

You have additional control of the service generated by JDeveloper. You can set JDeveloper preferences to perform the following tasks:

• Specify a default suffix for the names of generated SDO classes

• Modify the default subpackage where the service interface and classes reside

• Shape the URI of the generated SDO schema and web service target namespace by setting a default namespace prefix and by specifying the names of packages that you want to exclude from the URI.

To set the SDO class name suffix:

1. In the main menu, choose Tools and then Preferences.

2. In the Preferences dialog, expand ADF Business Components and choose Class Naming.

3. In the View Object suffix list, enter a suffix for SDO, for example, SDO.

To set the default subpackage for the generated service interface:

1. In the main menu, choose Tools and then Preferences.

2. In the Preferences dialog, expand ADF Business Components and choose Packages.

3. In the Relative Package Specification for Classes list, specify the default package names:

   • To set the Service Interface package name, enter a value for the Client Interface. (The Service Interface displays the same package name you specify for the client interface). The default package name is common.

   • Enter a value for the Service Interface Subpackage of the Service Interface. The default subpackage name is serviceinterface.

   For example, if you enter common for Service Interface and serviceinterface for Service Interface Subpackage (the defaults), service interfaces for data model components in the data model package oracle.summit.model.amservice will be placed in the subpackage oracle.summit.model.amservice.common.serviceinterface.

To shape the URI of the generated SDO schema and service interface target namespace:

Display names are labels that support the web service consuming application to programmatically generate a user interface and to display the service view instance and its attributes with the correct identifying labels. To enable access to these display names at runtime by the consuming application, you use the Create Service Interface wizard to add the built-in method getDfltObjAttrHints() to the remote client service interface. This method lets the consuming application developer programmatically retrieve the Display Name UI hint associated with the service view instance and its attributes. You define the UI hints in the Property window for the view object, where you can define a singular label and a plural label for each view instance name and attribute name. For example, as Figure 15-13 shows, you may define UI hints for the OrdersVO view object with the labels Order and Orders.

Figure 15-13 Display Name UI Hints for View Objects

Description of "Figure 15-13 Display Name UI Hints for View Objects"

Before you begin:

You will need to complete this task:

• Define the built-in method getDfltObjAttrHints() in the remote client service interface, as described in How to Enable the Application Module Service Interface.

To set UI Hint labels for the view instance and its attributes:

At runtime, the web service client will invoke the service-enable methods of the application module through the SOAP protocol. You can configure an Oracle Web Service Manager (OWSM) security policy to enable authentication and authorization on the service. The security policy that you select will require the SOAP client call to provide credential information (or SAML token) as part of the SOAP header. You can also configure other policies to enable message protection (integrity and confidentiality) for inbound SOAP requests, for instance.

To secure the web service for SOAP clients:

1. Configure an OWSM authentication policy.

2. Configure an OWSM authorization policy.

You can enable authentication to require users to supply credentials before they have access to the service methods on the service interface. The type of authentication required is configured on the service implementation class using an OWSM authentication policy annotation.

You can enable permission checking to enable only users with sufficient privileges to invoke a service method on the service interface. Permission checking is configured on the service implementation class using this OWSM authorization annotation:

• binding_permission_authorization_policy

  This policy provides simple permission-based authorization for the request based on the authenticated Subject at the SOAP binding level. This policy ensures that the Subject has permission to perform the operation. This policy should follow an authentication policy where the Subject is established and can be attached to any SOAP-based endpoint.

As an alternative to the permission checking policy, you can configure one of these role-based OWSM security policies:

• binding_authorization_denyall_policy

  This policy provides simple role-based authorization for the request based on the authenticated Subject at the SOAP binding level. This policy denies all users with any roles. It should follow an authentication policy where the Subject is established and can be attached to any SOAP-based endpoint.

• binding_authorization_permitall_policy

  This policy provides a simple role-based authorization for the request based on the authenticated Subject at the SOAP binding level. This policy permits all users with any roles. It should follow an authentication policy where the Subject is established and can be attached to any SOAP-based endpoint.

For further details about the authorization policies, see Security Policies—Authorization Only in Securing Web Services and Managing Policies with Oracle Web Services Manager.

ADF service interface framework also provides an EJB interceptor ServicePermissionCheckInterceptor which does the same permission check as oracle/binding_permission_authorization_policy, and additionally covers RMI invocation to services. If your services will always be invoked through SOAP, you should attach the OWSM oracle/binding_permission_authorization_policy authorization policy. If your services will also be invoked through RMI, you should attach the EJB interceptor ServicePermissionCheckInterceptor.

Before you begin:

It may be helpful to have an understanding of how the SDO framework supports service-enabled ADF view objects and enables web service clients to access rows of data and perform service operations. For more information, see Publishing Service-Enabled Application Modules.

You may also find it helpful to have an understanding of the predefined authentication policies supported by OWSM. For more information, see Security Policies-Authentication Only in Securing Web Services and Managing Policies with Oracle Web Services Manager.

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Additional Functionality for Service-Enabled Application Modules.

You will need to complete this task:

• Grant users access to the service, as described in How to Grant Test Users Access to the Service.

To configure an authentication and authorization:

1. In the Applications window, expand the application module, expand the serviceinterface node, and then double-click the service implementation class (AppModuleServiceImpl.java) node.

   In the web service generated from the ServiceAppModule application module in the oracle.summit.model.amservice package in the SummitADF_Examples workspace, the service implementation class is ServiceAppModuleServiceImpl.java.

2. If your services will always be invoked exclusively through SOAP (and not RMI), you should use an OWSM authorization policy as follows:

   1. In the source for the service implementation class, place your cursor on the @PortableWebService annotation.

      For example, ServiceAppModuleServiceImpl.java shows the annotation for the service as follows:

      ...
      @PortableWebService(
        targetNamespace="/oracle/summit/model/amservice/common/",
        serviceName="ServiceAppModuleService",
        portName="ServiceAppModuleServiceSoapHttpPort",
        endpointInterface=
         "oracle.summit.model...common.serviceinterface.ServiceAppModuleService")
      

   2. In the Properties window, expand the Policies section, and click the button next to the Multiple Policies field.

   3. In the Edit Property: Multiple Policies dialog, select the desired security policy and click OK.

      For details about the security policies supported by OWSM, see Security Policies—Authorization Only in Securing Web Services and Managing Policies with Oracle Web Services Manager.

   4. Return to the source file and note that annotation @PolicySet is configured.

      The @PolicySet annotation that you define for the service implementation class specifies the security requirements to potential clients. In this example, the annotation shows both the permission-checking authorization policy (oracle/binding_permission_authorization_policy) and an authentication policy:

      ...
      @PortableWebService(
        targetNamespace="/oracle/summit/model/amservice/common/",
        serviceName="ServiceAppModuleService",
        portName="ServiceAppModuleServiceSoapHttpPort",
        endpointInterface=
         "oracle.summit.model...common.serviceinterface.ServiceAppModuleService")
      @PolicySet(references = {  
         @PolicyReference(value = 
                             "oracle/wss_username_token_service_policy"), 
         @PolicyReference(value = 
                             "oracle/binding_permission_authorization_policy")
      })
      

3. If your services will be invoked through SOAP and RMI, you should use ServicePermissionCheckInterceptor only (there is no need to use an OWSM authorization policy) as follows.

   In the source editor, place your cursor in the @Interceptors annotation and add ServicePermissionCheckInterceptor.class to enable permission checking at runtime.

   ...
   @Interceptors({ ServiceContextInterceptor.class,
                   ServicePermissionCheckInterceptor.class })
   @Stateless(name=
               "oracle.summit.model.amservice.common.ServiceAppModuleServiceBean",
              mappedName="ServiceAppModuleServiceBean")
   

4. Save the service implementation class file.

After you have configured the authorization policy for the service, you must configure the Oracle Platform Security Services (OPSS) security provider to specify which users can invoke method on the service. At design time, you perform this task by editing the jazn-data.xml configuration file to create application roles and make an invoke permission grant to the desired application roles. Then when you deploy the service, the administrator for the target Oracle WebLogic Server will associate enterprise users with the application roles you specify. This allows you to confer the right to invoke a service method to any user who is a member of that application role. Users who are members of a role that has not been granted the invoke permission, will denied access to the service method.

The invoke permission for Oracle Web Services is defined by the oracle.wsm.security.WSFunctionPermission class. You can grant the invoke permission to the application roles you define for all the methods of the service or just to individual methods.

Before you begin:

It may be helpful to have an understanding of how the SDO framework supports service-enabled ADF view objects and enables web service clients to access rows of data and perform service operations. For more information, see Publishing Service-Enabled Application Modules.

You may also find it helpful to have an understanding of application roles and the OPSS security provides. For more information, see the "Introduction to Oracle Platform Security Services" chapter in Securing Applications with Oracle Platform Security Services.

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Additional Functionality for Service-Enabled Application Modules.

You will need to complete these tasks:

1. Configure authentication and authorization policies for your service, as described in How to Secure the ADF Web Service for Access By SOAP Clients, or How to Secure the ADF Web Service for Access By RMI Clients.

2. Add the OPSS security provider configuration file to your project by creating a jazn-data.xml deployment descriptor. For more information about deployment descriptors, see the "Deploying Applications" chapter in Developing Applications with Oracle JDeveloper.

   Note that in JDeveloper you open the New Gallery, expand General, select Deployment Descriptors and then Oracle Deployment Descriptors, and click OK.

3. Create the desired application roles that you want to make grants to, as described in Creating Application Roles.

4. For the purpose of testing your web service in JDeveloper using Integrated WebLogic Server, you can populate the application roles with test users, as described in Creating Test Users.

To grant the web service permission to application roles in the jazn-data.xml file:

The ADF service interface framework supports using Message Transmission Optimization Mechanism (MTOM) to handle sending binary data in any service method that operates on a ViewRow with a BlobDomain/ClobDomain attribute. This permits binary data to accompany XML messages, for example when images are required to document an insurance claim. The SDO data objects of the service-enabled application module maps BlobDomain/ClobDomain to javax.activation.DataHandler. These DataHandler properties could be passed as attachments during SDO data object marshalling/unmarshalling when the web service is called using the SOAP protocol.

To enable MTOM support for your SOAP protocol, you must add the @MTOM annotation to the service implementation class (for example, ServiceAppModuleServiceImpl.java) and your method must operate on a view row with BlobDomain/ClobDomain attribute.

Before you begin:

It may be helpful to have an understanding of how the SDO framework supports service-enabled ADF view objects and enables web service clients to access rows of data and perform service operations. For more information, see Publishing Service-Enabled Application Modules.

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Additional Functionality for Service-Enabled Application Modules.

You will need to complete this task:

• Configure a character encoding format that the ADF service interface framework can use to convert data defined by the view object as ClobDomain attribute, as described in How to Specify Character Encoding for ClobDomain Type Attributes.

To enable support for sending binary data attachments:

A consequence of working with large string data, defined in the database as CLOB type, is the character encoding used when converting string data to and from binary data. When you work with ClobDomain attributes in your service data objects, the ADF service interface framework streams the data by mapping the attribute value to a base64-encoded SDO property. This mapping to base64 binary stream does not include the character set of the original data.

To support converting string data to and from binary data, the ADF service interface framework allows you to configure the encoding character set for individual ClobDomain attributes of the view object. Alternatively, you can configure the encoding character set at the level of the view object definition, when you want all ClobDomain attributes to be converted using the same character encoding scheme.

When the framework needs to convert the binary stream to and from characters for ClobDomain attributes, it can apply the character encoding specified as a value for either of these custom properties that you have defined on the view object:

• SERVICE_USE_SERVER_DEFAULT_CHARSET

• SERVICE_CLOB_CONVERSION_CHARSET

The custom property SERVICE_USE_SERVER_DEFAULT_CHARSET is useful when you do not know the specific character encoding used by the database. Since the character set of the server JVM will be locale dependent, you should take that into account when defaulting to the server's encoding character set.

The ideal configuration for ClobDomain attributes relies on the custom property SERVICE_CLOB_CONVERSION_CHARSET and the character encoding that you specify. This configuration assumes that you can verify the character encoding of the target data to ensure that the ADF service interface framework does not convert using a different encoding character set.

Before you begin:

It may be helpful to have an understanding of how the SDO framework supports service-enabled ADF view objects and enables web service clients to access rows of data and perform service operations. For more information, see Publishing Service-Enabled Application Modules.

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Additional Functionality for Service-Enabled Application Modules.

You will need to complete this task:

• Enable MTOM support by adding the @MTOM annotation to the service implementation class to allow service methods to operate on a view row with ClobDomain attributes, as described in How to Enable Support for Binary Attachments for SOAP Clients.

To configure character encoding for individual ClobDomain attributes of the view object:

1. In the Applications window, double-click the view object that contains ClobDomain attributes.

2. In the overview editor, click the Attributes navigation tab.

3. In the Attributes page, select the attribute with Clob displayed in the Type column.

4. Click the Custom Properties tab, click the Add icon and choose Non-Translatable Property from the dropdown list and then enter one of the following predefined custom properties in the Property name field:

   SERVICE_USE_SERVER_DEFAULT_CHARSET - when you want the character encoding of the JVM to be used to convert the data. Enter true for the Value.

   SERVICE_CLOB_CONVERSION_CHARSET - when you want to specify a known character encoding that corresponds to the character encoding of the data. Enter the desired character encoding for the Value. For example, you might enter UTF-16. Note, when no value is supplied, the default UTF-8 will be used.

To configure character encoding for all ClobDomain attributes of the view object:

You can run the web service in JDeveloper using Integrated WebLogic Server. You can also deploy the web service to Oracle WebLogic Server to test the service.

To run and test using Integrated WebLogic Server:

When you test the web service you may find that some of your custom methods exceed the established timeout limitation established by the Java Transaction API (JTA). The JTA timeout setting establishes an execution boundary for service methods that by default may not exceed 30 seconds. You can use the Administration Console for Oracle WebLogic Server to increase the JTA timeout setting. If you still receive a timeout exception or you anticipate that the custom methods of the service interface may be long running, you can specify an EJB transaction attribute for the stateless session bean to prevent the EJB from executing those methods in a JTA transaction.

java.sql.SQLException: The transaction is no longer active - status: 'Committed'. No further JDBC access is allowed within this transaction

To perform custom operations in the case of the afterCommit() method, the service-enabled method annotation TransactionAttribute must be configured as NOT_SUPPORTED. To make a custom method exempt from timing out, you set TransactionAttributeType.NOT_SUPPORTED in the Properties window specifically for that method. As the following example shows, JDeveloper updates the method by adding the annotation @TransactionAttribute(TransactionAttributeType.NOT_SUPPORTED).

@TransactionAttribute(TransactionAttributeType.NOT_SUPPORTED)
public void updateCustomerInterests(List<String> pCategoryIds) throws
                                                       ServiceException {
        invokeCustom((Method) _map.get("updateCustomerInterests"), 
             new Object[] { pCategoryIds }, new String[] { null }, false);
}

Because a method with this transaction attribute setting will not be executed in the JTA transaction, it is your responsibility to enforce control over the transaction using the ADF Business Components methods of the oracle.jbo.ApplicationModule and oracle.jbo.Transaction interfaces. For instance, as the following example shows, the methods of the implementation class of the application module that you service-enabled, will need to call am.getDBTransaction().commit() or rollback() in order to complete the transaction.

public void updateCustomerInterests(List pCategoryIds) {
     try
     {
        if (pCategoryIds != null && pCategoryIds.size() > 0) {
            List<Integer> copyOfCategoryIds = (List<Integer>)
                                       this.cloneList(pCategoryIds);
            ViewObject selectedCategories = 
                                       this.getSelectedCategoriesShuttleList();
            RowSetIterator rsi = selectedCategories.createRowSetIterator(null);
            // remove rows for the current user not in the list of product keys
            while (rsi.hasNext()) {
                Row r = rsi.next();
                Number interestId = (Number)r.getAttribute("CategoryId");
                // existing row is in the list, we're ok, so remove from list.
                if (copyOfCategoryIds.contains(interestId)) {
                    copyOfCategoryIds.remove(interestId);
                }
                // if the existing row is in not list, remove it.
                else {
                    r.remove();
                }
            }
            rsi.closeRowSetIterator();
            // at this point, add new rows for the keys that are left
                    for (int i =0 ;i < copyOfCategoryIds.size(); i++ )  {
                        Row newRow = selectedCategories.createRow();
                        selectedCategories.insertRow(newRow);
                        newRow.setAttribute("CategoryId", (String)
                                       copyOfCategoryIds.get(i).toString());
                    }
        this.getTransaction().commit();
        }
     }
     catch (JboException e)
     {
        this.getTransaction().rollback();
        throw e;
     }
}

You should not change the default transaction attribute setting for the standard service methods generated for the service interface (see Table 15-1). The standard methods will execute within the default execution boundary set for the JTA transaction.

Before you begin:

It may be helpful to have an understanding of how the SDO framework supports service-enabled ADF view objects and enables web service clients to access rows of data and perform service operations. For more information, see Publishing Service-Enabled Application Modules.

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Additional Functionality for Service-Enabled Application Modules.

To prevent custom methods from executing in a JTA transaction:

You can deploy the web service to Oracle WebLogic Server, for example to perform a second stage of testing the service.

Before you begin:

It may be helpful to have an understanding of how the SDO framework supports service-enabled ADF view objects and enables web service clients to access rows of data and perform service operations. For more information, see Publishing Service-Enabled Application Modules.

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Additional Functionality for Service-Enabled Application Modules.

You will need to complete these tasks:

1. If your project contains a standard web service (a Java class or interface with the @WebService annotation), you must remove the @WebService annotation from the Java class before you can deploy the Business Components web service. If you attempt to deploy the Business Components web service from the same project as the standard web service, deployment will fail with an Oracle WebLogic Server exception error. It is therefore necessary to create standard web services in a separate project from your ADF Business Components service.

2. If you created an asynchronous web service, before you can deploy the service you must configure the queues used to store the request and response. For information about configuring the request and response queues, see the "Creating the Request and Response Queues" section of the "Developing Asynchronous Web Services" chapter in Developing Oracle Infrastructure Web Services.

3. If you configured authorization for the web service, as described in How to Secure the ADF Web Service for Access By SOAP Clients, edit the weblogic-application.xml file to define application ID parameters. This file appears in the Applications window in the Application Resources panel, under the Descriptors and META-INF nodes.

   Add the following <application-param> definition as the first element:

   <weblogic-application xmlns="http://www.bea.com/ns/weblogic/weblogic-application"
                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                     xsi:schemaLocation=
                           "http://www.bea.com/ns/weblogic/weblogic-application.xsd">
      <application-param>
         <param-name>jps.policystore.applicationid</param-name>
         <param-value>ApplicationName</param-value>
      </application-param>
      ...
   </weblogic-application>
   

   Note that the ApplicationName that you enter must match the name identified in the jazn-data.xml policy store definition:

   <jazn-data>
      <policy-store>
           <applications>
               <application>
                   <name>ApplicationName</name>
                   <app-roles>
                       ...
                   </app-roles>
                   <jazn-policy>
                       ...
                   </jazn-policy>
               </application>
           </applications>
       </policy-store>
   </jazn-data> 
   

4. Edit the ejb-jar.xml file to add the following JpsInterceptor definition required by the EJB for application roles evaluation. This file appears in the Applications window under the META-INF node of the web service project.

   <?xml version = '1.0' encoding = 'windows-1252'?>
   <ejb-jar xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
            http://java.sun.com/xml/ns/j2ee/ejb-jar_3_0.xsd" version="3.0" 
            xmlns="http://java.sun.com/xml/ns/javaee">
     <enterprise-beans>
       ...
     </enterprise-beans>
     <interceptors>
        <interceptor>
           <interceptor-class>
               oracle.security.jps.ee.ejb.JpsInterceptor
           </interceptor-class>
              <env-entry>
                 <env-entry-name>application.name</env-entry-name>
                 <env-entry-type>java.lang.String</env-entry-type>
                 <env-entry-value>ApplicationName</env-entry-value>
                 <injection-target>
                     <injection-target-class>
                         oracle.security.jps.ee.ejb.JpsInterceptor
                     </injection-target-class>
                     <injection-target-name>
                         application_name
                     </injection-target-name>
                 </injection-target>
              </env-entry>
        </interceptor>
        ...
     <interceptors>
     <assembly-descriptor>
        <interceptor-binding>
           <ejb-name>*</ejb-name>
           <interceptor-class>
                oracle.security.jps.ee.ejb.JpsInterceptor
           </interceptor-class>
        </interceptor-binding>
     </assembly-descriptor>
   </ejb-jar>
   

   Note that ApplicationName must also match the application name identified in the jazn-data.xml policy store definition.

To deploy to Oracle WebLogic Server:

1. Create an application server connection to Oracle WebLogic Server:

   1. In the main menu, choose Window and then Application Servers.

   2. In the Application Servers window, right-click the Application Servers node and choose New Application Server, and complete the Create Application Server Connection wizard.

2. Create a service deployment profile:

   1. In the Applications window, right-click the project that contains the web service and choose Project Properties.

   2. In the Project Properties dialog, open the Deployment page and click New.

   3. In the Create Deployment Profile dialog, choose Business Components Service Interface as the archive type, as shown in Figure 15-14.

      Figure 15-14 Dialog for Creating a Business Components Service Deployment Profile

      

3. In the main menu, choose Application > Deploy > deployment profile for the deployment profile you created.

4. In the Deploy wizard, on the Deployment Action page, select Deploy to Application Server and click Next.

5. On the Select Server page, select the application server connection.

6. Click OK.

Before you can launch the Oracle ADF Model Tester, your project must meet the runtime requirements, as described in How to Configure the Service-Backed Business Components Runtime. The Oracle ADF Model Tester will display the view objects you create from the remote web service and allow you to interact with the service to perform standard CRUD operations.

Because the application module that you run can access locally queried data and remotely queried data together, service-backed view objects and database-derived view objects will display in the same tester. If the endpoint is unavailable at the time you select the service-backed view object in the Oracle ADF Model Tester, you will get a runtime exception.

For details about running the Oracle ADF Model Tester, see How to Run the Oracle ADF Model Tester Using Configurations.

The ADF Business Components service interface requires that you return a service proxy to ensure that operations you invoke use the transport protocol specified by the published service.

Before you begin:

It may be helpful to have an understanding of how to access ADF Business Components services in the client Fusion web application. For more information, see Accessing Remote Data Over the Service-Enabled Application Module.

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Additional Functionality for Service-Enabled Application Modules.

You will need to complete this task:

• Ensure that the consuming application has the correct libraries on the classpath. In the Applications window, double-click the project and in the Project Properties dialog, select Libraries and Classpath and confirm the following libraries appear:

  • Java EE 1.5

  • Oracle XML Parser v2

  • BC4J Service Client

  • JAX-WS Client

  • The service's common JAR file

As the following example shows, when you invoke the operation, you perform the following tasks:

import commonj.sdo.DataObject;
import commonj.sdo.helper.DataFactory;
import commonj.sdo.helper.XMLHelper;
import hr.common.Dept;
import hr.common.serviceinterface.HRAppService;
import oracle.jbo.client.svc.ServiceFactory;
   ...
   {
      HRAppService proxy = (HRAppService) ServiceFactory.getServiceProxy(HRAppService.NAME);

      Dept dept = (Dept)
               ServiceFactory.getDataFactory(proxy).create("http://example.com/hr/common/" "Dept");
      dept.setDname("ENGINEERING");
      ...
      dept = proxy.createDept(dept);
      String xml = ServiceFactory.getXMLHelper(proxy).save((DataObject) dept,
                                   "http://example.com/hr/common/", "dept");
      out.print(xml);
   }

In JDeveloper, you can generate Java classes that act as a proxy to the remote service-enabled application module web service that you add to your web service client project. To accomplish this, you use the Create Web Service Client and Proxy wizard and supply a WSDL URL to the deployed service. The wizard creates a client file which uses the proxy classes and allows you to make Java method calls to access the web service.

Before you begin:

It may be helpful to have an understanding of how the SDO framework supports service-enabled ADF view objects and enables web service clients to access rows of data and perform service operations. For more information, see Publishing Service-Enabled Application Modules.

It may be helpful to understand how JDeveloper supports accessing web services in a Java applications by creating JAX-WS web service client and proxy classes. For more information, see the "Creating JAX-WS Web Services and Clients" section in Developing Applications with Oracle JDeveloper.

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Additional Functionality for Service-Enabled Application Modules.

You will need to complete these tasks:

1. Create the desired subtype view objects and configure the polymorphic usages on the application module view instance using the subtypes, as described in Defining Polymorphic View Objects.

2. Enable the service interface for the application module, as described in How to Enable the Application Module Service Interface.

3. Create the client project that will contain the web service proxy classes that you will use to invoke service methods.

   Tip: If you have not already created a Java client project in JDeveloper, you create a custom project to contain the web service proxy classes, as described the "Creating Applications and Projects" section in Developing Applications with Oracle JDeveloper.

4. Run the web service in JDeveloper to obtain the service endpoint URL that you will use to specify the location of the WSDL document.

   Tip: You can run the service in Integrated WebLogic Server and obtain the service endpoint URL from the Log window, as described in How to Test the Web Service Using Integrated WebLogic Server.

To generate the service client and proxy files:

In JDeveloper, you can create a Java client that accesses web services through JAXB (Java Architecture for XML Binding), using generated classes from the web service schemas. To generate JAXB packages, proxy classes, and interfaces, the client developer runs a JAXB binding compiler against the ADF Business Components service schema (WSDL). The developer requires no knowledge of the service XML to work with the proxy classes.

Using the generated proxy classes, developers can access and manipulate polymorphic collections in method calls that you make in the Java class files of your client project. A sample of such a file is the generated SOAP service client Java class file. The generated client file is named for the deployed ADF web service that you supplied with the WSDL document URL. For example, if the name of the ADF web service you deploy is ADFModuleService, the SOAP service client Java class is named AppModuleServiceSoapHttpPortClient.java.

Before you begin:

It may be helpful to have an understanding of why polymorphic collections cannot be accessed as a remote service. For more information, see Accessing Polymorphic Collections in the Consuming Application.

You will need to complete these tasks:

• Create the Java client project that contains Java proxy classes for the service-enabled application module web service. For details, see How to Generate Web Service Client Proxy Classes From the Service-Enabled Application Module.

• In the Applications window, expand the client project and locate the SOAP service client file. As Figure 15-17 shows, the AppModuleServiceSoapHttpPortClient.java file is located in the com.oracle.xmlns package of the client project.

Figure 15-20 JAXB Generated SOAP Service Client File

You may proceed to edit the SOAP service client file to invoke the exposed operations of the base and subtype view objects. As the following example shows, factory objects are created for the subtype view object:

package com.oracle.xmlns.apps.hr.service;
 
...

import oracle.summit.model.polymorphicvo.views.common.ObjectFactory;
import oracle.summit.model.polymorphicvo.views.common.SEmpViewSDO;
 
import oracle.summit.model.polymorphicvo.views.common.SalespersonViewExSDO;
 
...

public class AppModuleServiceSoapHttpPortClient {
    public static void main(String[] args) {
        AppModuleService_Service appModuleService_Service = 
                                     new AppModuleService_Service();
        AppModuleService appModuleService = 
                       appModuleService_Service.getAppModuleServiceSoapHttpPort();
 
        ...
 
        // Add your code to call the desired methods.
        try {
            SEmpViewSDO emp = testCreate(appModuleService);
            testFind(appModuleService);
            testDelete(appModuleService, emp);
            testFind(appModuleService);
        } catch (ServiceException e) {
        }
        
    }
 
...
    // 1. Create an employee of subtype Salesperson
    private static SEmpViewSDO testCreate(AppModuleService deptService) throws
                                ServiceException
    {
       oracle.summit.model.polymorphicvo.views.common.ObjectFactory factory = new
                oracle.summit.model.polymorphicvo.views.common.ObjectFactory();
 
       System.out.println("\n*** Testing createEmp ***\n");
       SalespersonViewExSDO salesperson = factory.createSalespersonViewExSDO();
       // 2. Set the attrs of the base SEmpView view object
       salesperson.setId(8001);
       salesperson.setFirstName(factory.createSEmpViewSDOFirstName("Lynn"));
       salesperson.setLastName("Munsinger");
       salesperson.setEmail(factory.createSEmpViewSDOEmail
                            ("lmunsing@summit.com"));
       salesperson.setTitleId(factory.createSEmpViewSDOTitleId
                            (new BigDecimal(2)));
       salesperson.setSalary(factory.createSEmpViewSDOSalary
                            (new BigDecimal(2000)));
       // 3. Set the attrs of the subtype SalespersonView view object
       salesperson.setCommissionPct
                            (factory.createSalespersonViewExSDOCommissionPct
                               (new BigDecimal(20)));
       salesperson.setDeptId(factory.createSEmpViewSDODeptId(31));
 
       return printEmp(deptService.createSEmpView1(salesperson));
    }
 
    // 4. Delete the employee of type Salesperson
    private static void testDelete(AppModuleService deptService, SEmpViewSDO emp)
                         throws ServiceException
    {
       System.out.println("\n*** Testing deleteEmp ***\n");
       deptService.deleteSEmpView1(emp);
    }
    
    // 5. Print 
    private static SEmpViewSDO printEmp(SEmpViewSDO emp)
    {
       System.out.print(emp.getId() + "\t" + emp.getEmail().getValue() + "\t" +
             emp.getTitle().getValue() + "\t" +
                        "\t" + emp.getSalary().getValue());
       if (emp instanceof SalespersonViewExSDO)
       {
          System.out.print("\t" + ((SalespersonViewExSDO)
                             emp).getCommissionPct().getValue());
       }
       System.out.println();
       return emp;
    }

    // 6. Find employees by department
    private static void testFind(AppModuleService deptService) throws
                                                             ServiceException
    {
       com.oracle.xmlns.adf.svc.types.ObjectFactory factory = new
                        com.oracle.xmlns.adf.svc.types.ObjectFactory();
 
       System.out.println("\n*** Testing findEmpsByDept ***\n");
       FindCriteria fc = factory.createFindCriteria();
       fc.setFetchStart(0);
       fc.setFetchSize(-1);
 
       List<SEmpViewSDO> empList = 
                          deptService.findSEmpView1ByDept(fc, "SALES", null);
       for (SEmpViewSDO emp : empList)
       {
          printEmp(emp);
       }
    }
}

Running AppModuleServiceSoapHttpPortClient.java client in JDeveloper produces the following output to the Log window. The createEmp method creates an employee in the sales department as a Salesperson subtype of the EmpView collection. The attribute value 20 is the Commission attribute of the new polymorphic view row. The findEmpsByDept method displays a mix of EmpView base view rows and SalespersonView subtype rows. The remaining methods delete the created salesperson from the EmpView collection and print the result.

*** Testing createEmp ***

8001 lmunsing@summit.com    Sales Representative    2000   20

*** Testing findEmpsByDept ***

3     mnagayam@summit.com   VP, Operations          1400
11    cmagee@summit.com     Sales Representative    1400   10
13    ysedeghi@summit.com   Sales Representative    1515   10
14    mnguyen@summit.com    Sales Representative    1525   15
15    adumas@summit.com     Sales Representative    1450   17.5
23    rpatel@summit.com     Stock Clerk             795
8001  lmunsing@summit.com   Sales Representative    2000   20

*** Testing deleteEmp ***

*** Testing findEmpsByDept ***

3   mnagayam@summit.com    VP, Operations           400
11  cmagee@summit.com      Sales Representative     1400   10
13  ysedeghi@summit.com    Sales Representative     1515   10
14  mnguyen@summit.com     Sales Representative     1525   15
15  adumas@summit.com      Sales Representative     1450   17.5
23  rpatel@summit.com      Stock Clerk              795

To construct a find request payload for a SDO, it is necessary to understand the containment hierarchy of the find method filter model. Payload building blocks are derived from the elements defined by the find method XSD. For details about the containment hierarchy, see Working with the Find Method Filter Model in the Consuming Application.

Find up to 50 Locations where the Country attribute value is US or IE. Return only the Country, State, Province, and City attributes. Sort the result set in descending Country order. Do not return any translated values.

Figure 15-25 Find Request on Parent Object

Description of "Figure 15-25 Find Request on Parent Object"

The following request is designed to return a result set for a filtered child object matching this description:

For each row in the result set (each qualifying object instance), include the LocationProfile: including the FloorNumber, Building, City, State, Province, Country and EffectiveStartDate attributes, if the EffectiveStartDate is on or after the date specified.

Figure 15-26 Find Request on Parent and Child Objects

Description of "Figure 15-26 Find Request on Parent and Child Objects"

The standard find method API provides control over the query behavior. To work with the API, it is necessary to understand the object containment hierarchy of the find method filter model. For details about the containment hierarchy, see Working with the Find Method Filter Model in the Consuming Application,

The following sample illustrates the process for programmatically creating a FindCriteria object:

1. Create a new FindCriteria (the Filter).

2. Create a new ViewCriteriaItem (the Item).

3. Create a new ViewCriteriaRow (the Group).

4. Add the created items and groups to the FindCriteria.

//1. Create FindCriteria
     final FindCriteria findCriteria = (FindCriteria)DataFactory.INSTANCE.create(FindCriteria.class);
     findCriteria.setFetchStart(0);
     findCriteria.setFetchSize(-1);
     findCriteria.setExcludeAttribute(false);

//2. Create ViewCriteriaItem
     final ViewCriteriaItem viewCriteriaItem = (ViewCriteriaItem)DataFactory.INSTANCE.create(ViewCriteriaItem.class);
     viewCriteriaItem.setConjunction("AND"); //Can also be OR
     viewCriteriaItem.setUpperCaseCompare(true);
     viewCriteriaItem.setAttribute("EmpName");
     viewCriteriaItem.setOperator("LIKE"); //LIKE used for WILDCARD comparison
      final List<Object> item_values = new ArrayList<Object>(5);
     item_values.add(viewCriteriaItem);
      viewCriteriaItem.setValue(item_values);

//3. Create ViewCriteriaRow.
//4. Further add ViewCriteriaItem into ViewCriteriaRow and ViewCriteriaRow into FindCriteria.
     final ViewCriteriaRow viewCriteriaRow = (ViewCriteriaRow)DataFactory.INSTANCE.create(ViewCriteriaRow.class);
     viewCriteriaRow.setConjunction("AND");
     viewCriteriaRow.setUpperCaseCompare(true);
     final List<Object> item = new ArrayList<Object>(5);
     item.add(viewCriteriaItem);
     viewCriteriaRow.setItem(item);
     findCriteria.getFilter().getGroup().add(viewCriteriaRow);

When you want to query with a list of partial attributes list

By default, the find operation returns all the attributes including all details. When you only need some attributes, you should set the partial attributes on the FindCriteria parameter of the find method. Do this in the following situations:

• SDO contains LOB, which can be very expensive to retrieve and transfer.

• SDO contains details that are not needed, such as translations. Querying detail is also expensive.

Note: The standard getXXX function does not take a FindCriteria, so this function always returns everything. You should use findXXX to trim your return attributes.

The following example shows how to set the partial attributes to include only Dname, Loc from Dept, and exclude Empno from Emp.

FindCriteria fc = (FindCriteria)datafactory.create(FindCriteria.class);
List l = new ArrayList();
l.add("Dname");
l.add("Loc");
l.add("Emp");
fc.setFindAttribute(l);
List cfcl = new ArrayList();
ChildFindCriteria cfc = (ChildFindCriteria)datafactory.create(ChildFindCriteria.class);
cfc.setChildAttrName("Emp");
List cl = new ArrayList();
cl.add("Empno");
cfc.setFindAttribute(cl);
cfc.setExcludeAttribute(true);
cfcl.add(cfc);
fc.setChildFindCriteria(cfcl);
DeptResult res = svc.findDept(fc, null);

The following example shows how to set the partial attributes to exclude PurchaseOrderLine from PurchaseOrder.

FindCriteria fc = (FindCriteria)datafactory.create(FindCriteria.class);
List l = new ArrayList();
fc.setExcludeAttribute(true);
l.add("PurchaseOrderLine");
fc.setFindAttribute(l);
PchaseOrderResult res = svc.findPurchaseOrder(fc, null);

When you want to filter the result using a view criteria

The find API allows you to specify the WHERE clause of your query. The WHERE clause can be set on any level of the SDO.

The following example shows how to retrieve only the departments with a department number greater than 10 and child employees whose names start with "A".

FindCriteria fc = (FindCriteria)datafactory.create(FindCriteria.class);
//create the view criteria item
List value = new ArrayList();
value.add(new Integer(10));
ViewCriteriaItem vci = (ViewCriteriaItem)datafactory.create(ViewCriteriaItem.class);
vci.setValue(value);
vci.setAttribute("Deptno");
List<ViewCriteriaItem> items = new ArrayList(1);
items.add(vci);
//create view criteria row
ViewCriteriaRow vcr = (ViewCriteriaRow) datafactory.create(ViewCriteriaRow.class);
vcr.setItem(items);
//create the view criteria
List group = new ArrayList();
group.add(vcr);
ViewCriteria vc = (ViewCriteria)datafactory.create(ViewCriteria.class);
vc.setGroup(group);
//set filter
fc.setFilter(vc);

List cfcl = new ArrayList();
//create the child find criteria
ChildFindCriteria cfc = (ChildFindCriteria)datafactory.create(ChildFindCriteria.class);
cfc.setChildAttrName("Emp");
//create the child view criteira
ViewCriteria cvc = (ViewCriteria)datafactory.create(ViewCriteria.class);
cfc.setFilter(cvc);
//create the view criteria item
List cvalue = new ArrayList();
cvalue.add("A%");
ViewCriteriaItem cvci = (ViewCriteriaItem)datafactory.create(ViewCriteriaItem.class);
cvci.setValue(value);
cvci.setAttribute("Dname");
cvci.setOperator("LIKE");
List<ViewCriteriaItem> citems = new ArrayList(1);
citems.add(cvci);
//create child view criteria row
ViewCriteriaRow cvcr = (ViewCriteriaRow) datafactory.create(ViewCriteriaRow.class);
cvcr.setItem(citems);
List cgroup = new ArrayList();
cgroup.add(cvcr);
cvc.setGroup(cgroup);

DeptResult dres = svc.findDept(fc, null);

You can also query the parents with the children that satisfy certain criteria. For example, the following sample retrieves the departments with employees whose salary is greater than $10,000.

//create the view criteria item on the employees
List nvalue = new ArrayList();
nvalue.add(new BigDecimal(10000));
ViewCriteriaItem nvci = (ViewCriteriaItem)datafactory.create(ViewCriteriaItem.class);
nvci.setValue(nvalue);
nvci.setAttribute("Salary");
nvci.setOperation(">");
List<ViewCriteriaItem> nitems = new ArrayList(1);
nitems.add(nvci);
//create view criteria row
ViewCriteriaRow nvcr = (ViewCriteriaRow) datafactory.create(ViewCriteriaRow.class);
nvcr.setItem(nitems);
//create the nested view criteria
List ngroup = new ArrayList();
ngroup.add(nvcr);
ViewCriteria nvc = (ViewCriteria)datafactory.create(ViewCriteria.class);
nvc.setGroup(ngroup);
 
//create the view criteria item on the department
ViewCriteriaItem vci = (ViewCriteriaItem)datafactory.create(ViewCriteriaItem.class);
vci.setAttribute("Emp");
vci.setNested(nvc);
List<ViewCriteriaItem> items = new ArrayList(1);
items.add(vci);
//create view criteria row
ViewCriteriaRow vcr = (ViewCriteriaRow) datafactory.create(ViewCriteriaRow.class);
vcr.setItem(items);
//create view criteria on department
ViewCriteria vc = (ViewCriteria)datafactory.create(ViewCriteria.class);
List group = new ArrayList();
group.add(vcr);
vc.setGroup(group);
//set filter
FindCriteria fc = (FindCriteria)datafactory.create(FindCriteria.class);
fc.setFilter(vc);
 
DeptResult dres = svc.findDept(fc, null);

When you want to page the result

If you know that your query might return a large amount of data, you should make multiple service invocations, and use setFetchStart and setFetchSize to control the amount of the data that you want to retrieve.

The following sample shows how to retrieve only the second employee and the employee's department.

FindCriteria fc = (FindCriteria)datafactory.create(FindCriteria.class);
List cfcl = new ArrayList();
ChildFindCriteria cfc = (ChildFindCriteria)datafactory.create(ChildFindCriteria.class);
cfc.setChildAttrName("Emp");
cfc.setFetchStart(1);
cfc.setFetchSize(1);
cfcl.add(cfc);
fc.setChildFindCriteria(cfcl);
DeptResult dres = svc.findDept(fc, null);