As Published In September/October 2012

TECHNOLOGY: Oracle ADF

Consume Early, Consume Often

How to service-enable Oracle ADF Business Components application modules for consumption by SOA and Web services clients

Forward-looking enterprises build applications on a distributed architecture that transparently brings together Web, SOA, collaboration, content, and social networking services for user access from multiple device types (mobile, laptop, and so on).

The Oracle Application Development Framework Business Components (Oracle ADF Business Components) feature supports application development for distributed architectures, enabling developers to build business services with data persistence for Web applications and SOA by using a single development skill: the ability to develop with Oracle ADF.

In my last column (“Service, Please!,” Oracle Magazine, July/August 2012), I showed you how to consume and integrate remote services in an Oracle ADF Business Components application. In this column, I will show you how to expose Oracle ADF Business Components application modules as services for remote use with the primary consumers of such services: Java EE service clients, SOA components, and remote and local Oracle ADF Business Components application modules.

Service-Enabled Oracle ADF Business Components Modules

Creating service-enabled components with Oracle ADF Business Components requires little programming—it’s mostly a matter of configuration: you configure view objects, view criteria, and public methods defined on the application module for access from SOA components, Java API for XML Web Services (JAX-WS) clients, and remote Oracle ADF Business Components modules.

Technically, as shown in Figure 1, Oracle ADF Business Components services are implemented as Enterprise JavaBeans (EJB) 3.0 session beans. When you expose an Oracle ADF Business Components application module as a service, Oracle JDeveloper generates all required Web service artifacts, including XML schema definitions (XSDs), Web Service Description Language (WSDL) files for service discovery, and Java classes for the application module and the exposed view objects.

Figure 1: Oracle ADF Business Components service interface architecture

In this architecture, Oracle ADF Business Components view object rows are exposed as Service Data Objects (SDOs) on the service interface for create, read, update, and delete (CRUD) operations.

SDO is the linchpin of this architecture, providing an interface to data from the service to various back-end datasources. In such an architecture, the Oracle ADF Business Components application module acts as a data access service that queries data from and persists changes to the datasource.

The data bindings supported by SDO are EJB remote method invocation for service access from other Oracle ADF Business Components application modules, SOAP for JAX-WS service clients, and SOA bindings for component access in applications built based on the Service Component Architecture (SCA) standard.

As you work through the example for this column, you’ll use Oracle JDeveloper 11g Release 1 to generate the necessary SDO artifacts and to configure the completed service to fully implement this architecture and then see it in action with the sample Web client.

Getting Started

To follow the hands-on steps in this article, you’ll need the Studio edition of Oracle JDeveloper 11g Release 1 (11.1.1.6), available as a free download on Oracle Technology Network. You’ll also need an Oracle Database instance with an unlocked HR schema. Get started by downloading the sample application and unzipping the file. The file contains two folders:

• OraMagService holds a starter workspace in which you can build, test, and deploy a service-enabled Oracle ADF Business Components application module.

• OraMagServiceClients is a test client application that references the deployed Oracle ADF Business Components service from an Oracle ADF Business Components entity.

To prepare for the steps in this article, change the database connection in the Service Model to point to your HR database schema:

1. Launch Oracle JDeveloper 11g Release 1. From the menu, select File -> Open, and then navigate to the directory containing the unpacked sample application.

2. Open the OraMagService folder, select OraMagService.jws, and click Open. The workspace opens in Oracle Jdeveloper.

3. From the menu, select View -> Database -> Database Navigator, and then expand the OraMagService node to display the hrconn node.

4. Right-click the hrconn node, and select Properties from the context menu. Edit the database connection information to work with your setup. Test the changes, and click OK to close the connection properties.

 As another preliminary task, start the Oracle WebLogic Server instance integrated with Oracle JDeveloper. You’ll use the integrated Oracle WebLogic Server for service deployment and testing and for running the client Web application. 

To start Oracle WebLogic Server

1. From the Oracle JDeveloper menu, select Run -> Start Server Instance (IntegratedWebLogicServer).

2. If a Create Default Domain dialog box appears, create a password for the default Oracle WebLogic Server domain and select an address from those listed for Listen Address, for best results. For example, choose localhost rather than leaving the address empty. Click OK to save the change, create the default domain, and configure it for Oracle ADF. 

Sample Application Overview

• For the hrAllDepartments view object instance, you’ll expose view rows together with methods for CRUD operations.

• For the hrAllEmployees view object instance, you’ll expose (via a method on the service interface) a view criteria definition for querying employees by department ID.

In addition, the application module implementation class (AppModuleImpl.java) provided in the sample contains two public methods: 

• getAllSalaryForDepartment provides the service method (operation) for computing total salaries for a specified department.

• getEmployeesBySalaryRange provides the service method for finding employees within a given salary range. 

As you work through the sample, you’ll create the actual datatypes (generate the view object row classes, for example) that will support these operations. (Be sure to use any names for items provided in the instructions, because many of the prebuilt sample components rely on those names.)

View objects that are exposed on the Oracle ADF Business Components service interface cannot have circular dependencies. The view objects in the sample workspace have been built with this requirement in mind. When creating your own view objects, be aware that the Create ADF Business Components from Tables wizard generates view links for every database constraint.

For example, generating Oracle ADF Business Components objects for the Departments and Employees tables in the Oracle HR schema creates view links for the department-to-employees, employees-to-manager, and departments-to-manager relations. Because the Oracle ADF Business Components SDO service is based on a stateless EJB session bean, the employees-to-manager and departments-to-manager links would cause a circular dependency that would lead to an array out-of-bounds exception at runtime, because of the infinitive loop they represent. To avoid such a problem, if you use the wizard in your own development projects, be sure to delete any generated view links that would result in circular queries. Or—better yet—create view objects and view links manually, as has been done for this sample.

Building the Oracle ADF Business Components SDO Service

View object instances exposed on the Oracle ADF Business Components application module service interface are automatically service-enabled, which means that Oracle JDeveloper creates the SDO implementation classes and metadata files. For other view objects (such as the employees view row objects in this sample), you must explicitly service-enable the object, and you must do so before exposing any method that uses the object on the service interface.

For this sample, you are going to expose a public method that returns employee rows, so first you must ensure that a view object implementation class exists, as follows:

1. In the Application Navigator, expand the ServiceModel node and then the Application Sources node.

2. Expand the oramag.sample.sepoct.model.views package, and note the EmployeesView object. The hrAllEmployees view object instance (in the application module) is based on this view object definition.

3. Right-click the EmployeesView object, and choose Open EmployeesView from the menu to open the view object editor.

4. In the view object editor, select the Java option and then click the pencil icon next to the Java Classes header.

5. In the opened Select Java Options dialog box, check the Generate View Row Class and Generate Service Data Object Class checkboxes, leaving the other settings at their defaults. This creates the view row implementation class and an SDO object that wraps this class in the service.

6. Click OK to close the dialog box, which saves the settings and causes Oracle JDeveloper to generate the necessary classes, including the view row implementation class (EmployeesViewRowImpl) and the SDO object that wraps the implementation in the service (EmployeesViewSDO). 

Next you will configure the Oracle ADF Business Components service to filter the information of the Oracle ADF Business Components model that should be exposed on the service interface. 

1. In the Application Navigator, expand the oramag.sample.sepoct.model.am package and then the AppModule node. Select the AppModuleImpl.java class, right-click, and select Open from the context menu to open the class in the Java code editor.

2. In the code editor, scroll down to getEmployeesBySalaryRange and getAllSalaryForDepartment, to study their implementation. As you can see, getEmployeesBySalaryRange returns a java.util.List of EmployeesViewRowImpl, the class you created earlier to hold the queried employee data objects.

3. Close the Java code editor.

4. Right-click the AppModule node, and select Open AppModule from the context menu to open the application module editor.

5. In the application module editor, select the Service Interface category and click the green plus (+) icon. The Create Service Interface wizard launches. On the Service Interface page (Create Service Interface—Step 1 of 4), enter OraMagService for Web Service Name; leave all other field values at the default settings.

6. Click Next to continue. On the Service Custom Methods page (Step 2 of 4), select the getAllSalaryForDepartment and getEmployeesBySalaryRange methods displayed in the Available list and click the add button (>) to move them to the Selected list. The getEmployeesBy-SalaryRange method returns a list of employee objects for which you’ll next configure the service interface.

7. In the Selected list, click the getEmployeesBySalaryRange method node to expand it and then click the Return node.

8. Select the java.util.List item, and set the value of the Element View Object choice component to hrAllEmployees, the row type returned by the method.

9. Click Next to continue. On the Service View Instances page (step 3 of 4), select the hrAllDepartments and hrAllEmployees entries in the Available list and click the add button (>) to move these to the Selected list (for exposure on the service interface.)

10. Click hrAllDepartments on the Selected list. On the Basic Operations tab, enable the operations listed in Table 1 by checking the checkboxes in the Enable column (see Figure 2).

Figure 2: Oracle ADF Business Components service interface definition

When you expose a view object on the service interface, its attributes become part of the rows returned by a query. You can exclude any attribute from being exposed on the service interface by deselecting its SDO Property option in the view object editor. 

1. Select hrAllEmployees in the Selected list, and click the View Criteria Find Operations tab.

2. On the View Criteria Find Operations tab, click the green plus (+) icon to expose the view criteria defined on the EmployeesView object as a service method.

3. Click Finish. Oracle JDeveloper generates the service implementation classes, an XSD schema, and the WSDL reference in the service interface folder. In addition, Oracle JDeveloper creates the Java classes and an XSD schema for the view objects exposed on the service interface. The application module is updated with a new configuration, OraMagService.

4. In the application module editor, select the Configurations menu item and enter OraMagService for Default Configuration. 

Deploy the Service

The Oracle ADF Business Components service is deployed as an Enterprise Archive (EAR) file to the target deployment server. For the purposes of this example, we’ll use the integrated Oracle WebLogic Server to simulate remote deployment.

1. In the Application Navigator, right-click the ServiceModel project and choose Project Properties from the context menu.

2. In the Project Properties dialog box, select the Deployment node and click the New button.

3. In the opened Create Deployment Profile dialog box, select Business Components Service Interface for Archive Type and enter OraMagServiceArchive in the Name field.

4. Click OK. Oracle JDeveloper creates a deployment profile consisting of two JAR descriptors: Middle tier JAR (which defines the service Oracle ADF Business Components and EJB sources for deployment to the target server) and Common JAR (which defines proxy classes that will be configured in a JAR library to enable service-oriented clients—Java SE, Servlets, and EJB programs—to access the Oracle ADF Business Components service).

5. Click OK to close the Project Properties dialog box.

Next create the EAR file required for remote deployment.

1. Select Application -> Application Properties.

2. Select the Deployment node.

3. Select ServiceModel_OraMagServiceArchive in the Deployment Profiles field, and click the Edit button to open the Edit EAR Deployment Profile Properties dialog box.

4. Expand the Application Assembly node to verify that the Middle Tier archive is selected for deployment. If not, select it.

5. Click OK to close the Edit EAR Deployment Profile Properties dialog box, and then click OK again to close the Application Properties dialog box.

6. To deploy the EAR file, select Application -> Deploy from the menu and click the ServiceModel_OraMagServiceArchive menu item to launch the deployment dialog box for the EAR file.

7. In the dialog box, select Deploy to Application Server and click Next.

8. Select IntegratedWebLogicServer in the Application Server list, and click Next. In the WebLogic Options dialog box, keep the default settings and click Finish.

After successful deployment, you can validate service access by opening a browser and entering the URL of the WSDL available on the Web server, as follows: 

http://localhost:7101/oramag-sample/OraMagService?wsdl
 

The WSDL URL is derived from the Java EE path defined in the ServiceModel project properties (oramag-sample) and the Oracle ADF Business Components service name (OraMagService) you specified for the service-enabled application module; 7101 is the default port number for the integrated Oracle WebLogic Server.

Testing the Deployed Service

For testing Web service deployments on a remote Oracle WebLogic Server instance, I typically recommend using the Oracle Enterprise Manager Fusion Middleware Control feature (available through the Oracle Application Development Runtime Installer)—but for this sample application, you’ll test the remote deployed Oracle ADF Business Components service with the Oracle JDeveloper HTTP Analyzer tool.

To launch the HTTP Analyzer tool,

1. Select Tools -> HTTP Analyzer.

2. In the HTTP Analyzer toolbar, click the Create New Request icon to create a new instance (see Figure 3).

3. Click the Open WSDL button. An HTTP Analyzer: Unsent Message page appears above the HTTP Analyzer tool (in the main window).

4. Enter http://localhost:7101/oramag-sample/OraMagService?wsdl as the value for the WSDL URL reference.

5. Select OraMagServiceSoapHttpPort.getAllSalaryForDepartment from the Operations selector. In the parameters section of the page, enter 60 as the value of the departmentIdVar argument and click SendRequest to submit the message to the server. Assuming that you did not change the HR sample data, you should see 29000 as the result in the XML response in the analyzer.

Figure 3: Creating a new HTTP Analyzer instance

Recommendations for Service Project Layout

An Oracle ADF Business Components application module can be used as a model for Web applications and—if the application module is service-enabled—for service clients. So in theory, you could build a single Oracle ADF Business Components application module and configure it for use with Web and service clients. However, not everything that is possible makes sense in practice, because

• Deployments should be lean, containing only what a service actually needs.

• View objects used in a service model cannot have self-references or circular references defined as view links. Although this is not an issue for Web applications, it is for service models; keeping model projects of these two types separate from each other avoids conflict.

• Deployment profiles are easier to define and manage when each is specific to its service and the service model project to which it applies.

• Team development is easier to manage when Web projects and service model projects are separate from each other.

For these reasons, I recommend creating distinct Oracle ADF Business Components model projects for Web and service use. If you want to share view objects and entity objects among projects, create an appropriate Oracle ADF library and then reference the library from the Web or service project. (Note that you cannot create an Oracle ADF Business Components service module in a project that already contains a Java EE Web service.)

Oracle ADF Business Components Service Clients

With the configuration and deployment complete for the sample Oracle ADF Business Components service, you can now test the deployed service with an Oracle ADF Web application that uses an Oracle ADF Business Components business service for querying data from the deployed service.

The Web application assumes that the deployed Oracle ADF Business Components service is available at http://localhost:7101/oramag-sample/OraMagService?wsdl.

1. From the menu, select File -> Open and navigate to the directory containing the unpacked sample application.

2. Open the OraMagServiceClients folder.

3. Select the OraMagServiceClients.jws file, and click Open. The client application workspace opens in Oracle Jdeveloper.

The WsSdoDepartmentsView (in the oramag.sample.sepoct.client.model package) is based on the WsSdoDepartments entity, which has been configured to access the deployed Oracle ADF Business Components service for CRUD operators. 

Note that when you create a new entity object, you can specify that data should be obtained from a database schema object or from the service interface. To specify the service interface, you will need to provide the valid WSDL reference associated with a deployed Oracle ADF Business Components service, so that at runtime, the framework can create the entity object from an SDO object.

Also note that you should be aware of these two important configurations:

• The model project references the OraMagServiceArchive_Common.jar file in the Libraries and Classpath section of its properties page. Oracle ADF Business Components uses this JAR file reference to access the OraMagService proxy classes. (If the Oracle ADF Business Components client project that accesses the deployed service is exposed in an Oracle ADF library, you must also configure the <service name>common.jar file in the view layer project that consumes that library.)

• The connections.xml file (located in the Application Resources -> Descriptors -> ADF META-INF node) contains a local Java Naming and Directory Interface (JNDI) configuration for the deployed service. This configuration was copied from the connections.xml file of the OraMagService workspace. 

When building your own Oracle ADF Business Components clients for a deployed Oracle ADF Business Components service interface, you’ll configure these items yourself. See Oracle Fusion Middleware Fusion Developer’s Guide for Oracle Application Development Framework for details. For the sample service and application, you have nothing further to do but run the application.

To run the sample application

1. In the Application Navigator, expand the ViewController -> Web Content node so that the ServiceSampleUI.jspx file is visible, and click the file to select it.

2. Right-click the ServiceSampleUI.jspx file, and select Run from the context menu. The application opens in a browser window (see Figure 4).

Figure 4. Running the sample application

Explore the application, navigating through the data returned from the service and updating data as you see fit.

Conclusion

This article showed you how to expose an Oracle ADF Business Components application module as a service for use with Web, service, and SOA clients. This approach demonstrates some of the chief benefits of using Oracle ADF Business Components, such as enabling developers to leverage a single development skill for SOA and Web development.

 Frank Nimphius is a senior principal product manager for Oracle JDeveloper and Oracle ADF. He is a coauthor of Oracle Fusion Developer Guide: Building Rich Internet Applications with Oracle ADF Business Components and Oracle ADF Faces (McGraw-Hill, 2010).


Send us your comments