(For more resources on JDeveloper, see here.)

Creating and using generic extension interfaces

In this recipe, we will go over how to expose any of that common functionality as a generic extension interface. By doing so, this generic interface becomes available to all derived business components, which in turn can be exposed to its own client interface and make it available to the ViewController layer through the bindings layer.

How to do it…

1. Open the shared components workspace in JDeveloper
2. Create an interface called ExtApplicationModule as follows:

   public interface ExtApplicationModule {
     // return some user authority level, based on
     // the user's name
     public int getUserAuthorityLevel();
   }

3. Locate and open the custom application module framework extension class ExtApplicationModuleImpl. Modify it so that it implements the ExtApplicationModule interface.
4. Then, add the following method to it:

   public int getUserAuthorityLevel() {
     // return some user authority level, based on the user's name
     return ("anonymous".equalsIgnoreCase(this.
   getUserPrincipalName()))? 
       AUTHORITY_LEVEL_MINIMAL : AUTHORITY_LEVEL_NORMAL;
   }

5. Rebuild the SharedComponents workspace and deploy it as an ADF Library JAR.
6. Now, open the HRComponents workspace
7. Locate and open the HrComponentsAppModule application module defnition.
8. Go to the Java section and click on the Edit application module client interface button (the pen icon in the Client Interface section).
9. On the Edit Client Interface dialog, shuttle the getUserAuthorityLevel() interface from the Available to the Selected list.

How it works…

In steps 1 and 2, we have opened the SharedComponents workspace and created an interface called HrComponentsAppModule. This interface contains a single method called getUserAuthorityLevel().

Then, we updated the application module framework extension class HrComponentsAppModuleImpl so that it implements the HrComponentsAppModule interface (step 3). We also implemented the method getUserAuthorityLevel() required by the interface (step 4). For the sake of this recipe, this method returns a user authority level based on the authenticated user's name. We retrieve the authenticated user's name by calling getUserPrincipal().getName() on the SecurityContext, which we retrieve from the current ADF context (ADFContext.getCurrent().getSecurityContext()). If security is not enabled for the ADF application, the user's name defaults to anonymous. In this example, we return AUTHORITY_LEVEL_MINIMAL for anonymous users, and for all others we return AUTHORITY_LEVEL_NORMAL. We rebuilt and redeployed the SharedComponents workspace in step 5.

In steps 6 through 9, we opened the HRComponents workspace and added the getUserAuthorityLevel() method to the HrComponentsAppModuleImpl client interface. By doing this, we exposed the getUserAuthorityLevel() generic extension interface to a derived application module, while keeping its implementation in the base framework extension class ExtApplicationModuleImpl.

There's more…

Note that the steps followed in this recipe to expose an application module framework extension class method to a derived class' client interface can be followed for other business components framework extension classes as well.

Exposing a custom method as a web service

Service-enabling an application module allows you, among others, to expose custom application module methods as web services. This is one way for service consumers to consume the service-enabled application module. The other possibilities are accessing the application module by another application module, and accessing it through a Service Component Architecture (SCA) composite. Service-enabling an application module allows access to the same application module both through web service clients and interactive web user interfaces. In this recipe, we will go over the steps involved in service-enabling an application module by exposing a custom application module method to its service interface.

Getting ready

The HRComponents workspace requires a database connection to the HR schema.

How to do it…

1. Open the HRComponents project in JDeveloper.
2. Double-click on the HRComponentsAppModule application module in the Application Navigator to open its defnition.
3. Go to the Service Interface section and click on the Enable support for Service Interface button (the green plus sign icon in the Service Interface section). This will start the Create Service Interface wizard.
4. In the Service Interface page, accept the defaults and click Next.
5. In the Service Custom Methods page, locate the adjustCommission() method and shuttle it from the Available list to the Selected list. Click on Finish.



6. Observe that the adjustCommission() method is shown in the Service Interface Custom Methods section of the application module's Service Interface. The service interface fles were generated in the serviceinterface package under the application module and are shown in the Application Navigator.



7. Double-click on the weblogic-ejb-jar.xml fle under the META-INF package in the Application Navigator to open it.
8. In the Beans section, select the com.packt.jdeveloper. cookbook.hr.components.model.application.common. HrComponentsAppModuleService Bean bean and click on the Performance tab. For the Transaction timeout feld, enter 120.

How it works…

In steps 1 through 6, we have exposed the adjustCommission() custom application module method to the application module's service interface. This is a custom method that adjusts all the Sales department employees' commissions by the percentage specifed. As a result of exposing the adjustCommission() method to the application module service interface, JDeveloper generates the following fles:

• HrComponentsAppModuleService.java: Defnes the service interface
• HrComponentsAppModuleServiceImpl.java: The service implementation class
• HrComponentsAppModuleService.xsd: The service schema fle describing the input and output parameters of the service
• HrComponentsAppModuleService.wsdl: The Web Service Defnition Language (WSDL) fle, describing the web service
• ejb-jar.xml: The EJB deployment descriptor. It is located in the src/META-INF directory
• weblogic-ejb-jar.xml: The WebLogic-specifc EJB deployment descriptor, located in the src/META-INF directory

In steps 7 and 8, we adjust the service Java Transaction API (JTA) transaction timeout to 120 seconds (the default is 30 seconds). This will avoid any exceptions related to transaction timeouts when invoking the service. This is an optional step added specifcally for this recipe, as the process of adjusting the commission for all sales employees might take longer than the default 30 seconds, causing the transaction to time out.

To test the service using the JDeveloper integrated WebLogic application server, right-click on the HrComponentsAppModuleServiceImpl.java service implementation fle in the Application Navigator and select Run or Debug from the context menu. This will build and deploy the HrComponentsAppModuleService web service into the integrated WebLogic server. Once the deployment process is completed successfully, you can click on the service URL in the Log window to test the service. This will open a test window in JDeveloper and also enable the HTTP Analyzer. Otherwise, copy the target service URL from the Log window and paste it into your browser's address feld. This will bring up the service's endpoint page.

On this page, select the adjustCommission method from the Operation drop down, specify the commissionPctAdjustment parameter amount and click on the Invoke button to execute the web service. Observe how the employees' commissions are adjusted in the EMPLOYEES table in the HR schema.

There's more…

For more information on service-enabling application modules consult chapter Integrating Service-Enabled Application Modules in the Fusion Developer's Guide for Oracle Application Development Framework which can be found at http://docs.oracle.com/cd/ E24382_01/web.1112/e16182/toc.htm.

Accessing a service interface method from another application module

In the recipe Exposing a custom method as a web service in this article, we went through the steps required to service-enable an application module and expose a custom application module method as a web service. We will continue in this recipe by explaining how to invoke the custom application module method, exposed as a web service, from another application module.

Getting ready

This recipe will call the adjustCommission() custom application module method that was exposed as a web service in the Exposing a custom method as a web service recipe in this article. It requires that the web service is deployed in WebLogic and that it is accessible.

The recipe also requires that both the SharedComponents workspace and the HRComponents workspace are deployed as ADF Library JARs and that are added to the workspace used by this specifc recipe. Additionally, a database connection to the HR schema is required.

How to do it…

1. Ensure that you have built and deployed both the SharedComponents and HRComponents workspaces as ADF Library JARs.
2. Create a File System connection in the Resource Palette to the directory path where the SharedComponents.jar and HRComponents.jar ADF Library JARs are located.
3. Create a new Fusion Web Application (ADF) called HRComponentsCaller using the Create Fusion Web Application (ADF) wizard.
4. Create a new application module called HRComponentsCallerAppModule using the Create Application Module wizard. In the Java page, check on the Generate Application Module Class checkbox to generate a custom application module implementation class. JDeveloper will ask you for a database connection during this step, so make sure that a new database connection to the HR schema is created.
5. Expand the File System | ReUsableJARs connection in the Resource Palette and add both the SharedComponents and HRComponents libraries to the project. You do this by right-clicking on the jar fle and selecting Add to Project… from the context menu.
6. Bring up the business components Project Properties dialog and go to the Libraries and Classpath section. Click on the Add Library… button and add the BC4J Service Client and JAX-WS Client extensions.
7. Double-click on the HRComponentsCallerAppModuleImpl.java custom application module implementation fle in the Application Navigator to open it in the Java editor.
8. Add the following method to it:

   public void adjustCommission(
     BigDecimal commissionPctAdjustment) {
     // get the service proxy
     HrComponentsAppModuleService service =  
       (HrComponentsAppModuleService)ServiceFactory 
       .getServiceProxy( 
       HrComponentsAppModuleService.NAME);
     // call the adjustCommission() service
     service.adjustCommission(commissionPctAdjustment);
   }

9. Expose adjustCommission() to the HRComponentsCallerAppModule client interface.
10. Finally, in order to be able to test the HRComponentsCallerAppModule application module with the ADF Model Tester, locate the connections.xml fle in the Application Resources section of the Application Navigator under the Descriptors | ADF META-INF node, and add the following confguration to it:

    <Reference  
      name="{/com/packt/jdeveloper/cookbook/hr/components/model/ 
      application/common/}HrComponentsAppModuleService"
      className="oracle.jbo.client.svc.Service" >
    <Factory  
      className="oracle.jbo.client.svc.ServiceFactory"/>
    <RefAddresses>
    <StringRefAddr addrType="serviceInterfaceName">
    <Contents>com.packt.jdeveloper.cookbook.hr.components.model. 
    application.common.serviceinterface.HrComponentsAppModuleService 
    </Contents>
    </StringRefAddr>
    <StringRefAddr addrType="serviceEndpointProvider">
    <Contents>ADFBC</Contents>
    </StringRefAddr>
    <StringRefAddr addrType="jndiName">
    <Contents>HrComponentsAppModuleServiceBean#com.packt.jdeveloper. 
      cookbook.hr.components.model.application.common. 
      serviceinterface.HrComponentsAppModuleService</Contents>
    </StringRefAddr>
    <StringRefAddr addrType="serviceSchemaName">
    <Contents>HrComponentsAppModuleService.xsd</Contents>
    </StringRefAddr>
    <StringRefAddr addrType="serviceSchemaLocation">
    <Contents>com/packt/jdeveloper/cookbook/hr/components/model/ 
    application/common/serviceinterface/</Contents>
    </StringRefAddr>
    <StringRefAddr addrType="jndiFactoryInitial">
    <Contents>weblogic.jndi.WLInitialContextFactory</Contents>
    </StringRefAddr>
    <StringRefAddr addrType="jndiProviderURL">
    <Contents>t3://localhost:7101</Contents>
    </StringRefAddr>
    </RefAddresses>
    </Reference>

How it works…

In steps 1 and 2, we have made sure that both the SharedComponents and HRComponents ADF Library JARs are deployed and that a fle system connection was created, in order that both of these libraries get added to a newly created project (in step 5). Then, in steps 3 and 4, we create a new Fusion web application based on ADF, and an application module called HRComponentsCallerAppModule. It is from this application module that we intend to call the adjustCommission() custom application module method, exposed as a web service by the HrComponentsAppModule service-enabled application module in the HRComponents library JAR. For this reason, in step 4, we have generated a custom application module implementation class. We proceed by adding the necessary libraries to the new project in steps 5 and 6. Specifcally, the following libraries were added: SharedComponents.jar, HRComponents.jar, BC4J Service Client, and JAX-WS Client.

In steps 7 through 9, we create a custom application module method called adjustCommission(), in which we write the necessary glue code to call our web service. In it, we frst retrieve the web service proxy, as a HrComponentsAppModuleService interface, by calling ServiceFactory.getServiceProxy() and specifying the name of the web service, which is indicated by the constant HrComponentsAppModuleService.NAME in the service interface. Then we call the web service through the retrieved interface.

In the last step, we have provided the necessary confguration in the connections.xml so that we will be able to call the web service from an RMI client (the ADF Model Tester). This fle is used by the web service client to locate the web service. For the most part, the Reference information that was added to it was generated automatically by JDeveloper in the Exposing a custom method as a Web service recipe, so it was copied from there. The extra confguration information that had to be added is the necessary JNDI context properties jndiFactoryInitial and jndiProviderURL that are needed to resolve the web service on the deployed server. You should change these appropriately for your deployment. Note that these parameters are the same as the initial context parameters used to lookup the service when running in a managed environment.

To test calling the web service, ensure that you have frst deployed it and that it is running. You can then use the ADF Model Tester, select the adjustCommission method and execute it.

There's more…

For additional information related to such topics as securing the ADF web service, enabling support for binary attachments, deploying to WebLogic, and more, refer to the Integrating Service-Enabled Application Modules section in the Fusion Developer's Guide for Oracle Application Development Framework which can be found at http://docs.oracle.com/ cd/E24382_01/web.1112/e16182/toc.htm.