TECHNOLOGY: Oracle ADF
Consume Early, Consume OftenBy Frank Nimphius
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.
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.
To follow the hands-on steps in this article, you’ll need the Studio edition of Oracle JDeveloper 11g Release 1 (188.8.131.52), 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:
To prepare for the steps in this article, change the database connection in the Service Model to point to your HR database schema:
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
Sample Application OverviewThe OraMagService workspace contains an Oracle ADF Business Components application that consists of a single Oracle ADF Business Components application module, AppModule. As you follow the instructions in this article, you’ll be exposing two view object instances on the Oracle ADF Business Components service interface:
In addition, the application module implementation class (AppModuleImpl.java) provided in the sample contains two public methods:
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:
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.
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.
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.
Next create the EAR file required for remote deployment.
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:
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,
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
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.
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:
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
Explore the application, navigating through the data returned from the service and updating data as you see fit.
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).