Xml and More: How to Create Oracle ADF BC Services

Introduction
The Oracle Application Development Framework (Oracle ADF) is an end-to-end application framework that builds on Java Platform, Enterprise Edition (Java EE) standards and open-source technologies to simplify and accelerate implementing service-oriented applications.
Using Oracle JDeveloper 11g and Oracle ADF framework in tandem, you implement business services and publish them as web services using a declarative, component-based approach that allows you to focus on application-specific business logic instead of low-level application "plumbing" code. In other words, creating, testing, and deploying data-centric web services in Oracle ADF is extremely easy and requires no web services specific knowledge or coding on your part.
Oracle ADF Business Components (BC) will be the main source of data access and business logic in Fusion applications. Using it, service provider can easily develop new remotable services (i.e, ADF BC services). For each exposed view objects used in ADF BC services, we can generate standard Create, Retrieve, Update, and Delete (CRUD) methods. In addition to the standard CRUD methods, custom methods can also be selected to be included in the ADF BC service.
Oracle JDeveloper includes a variety of ways to construct ADF BC services. In this article, we will demonstrate the following approach:

Create schema-object-based entity object

This approach starts from creating an entity object with its supporting components (i.e., application module and view object). Then we will expose the auto-generated CRUD methods from view objects as service operations. Using this approach, JDeveloper helps you to construct business components (i.e., application module, entity object, and view object) in one shot.
Every entity object must have at least one attribute marked as a primary key. In our example, EMP table has no primary key constraint. Using our approach, Create Entity Object wizard will allow you to set any attribute as primary key.

ADF Business Components
Oracle ADF Business Components is a framework implements the Business Services layer on top of a data source in a declarative way. It provides out-of-the-box services such as transaction management, resource pooling, locking, declarative validation rules, translation, and object-relational mapping.
To use Oracle ADF BC, you use wizards in JDeveloper to create:

Application Module
- An application module is a service component that UI or Web Service clients use to work with application data. It defines an updatable data model and top-level procedures and functions (called service methods) for a logical unit of work related to an end-user task. To simplify the task of implementing your services, you leverage a set of business components like entity objects and view objects.
- You can enable a service interface on any Application Module. The service interface expose Application Modules as remotable services allowing third-party applications to find, create, update and delete business information using standard web services protocols. All of the business validation rules encapsulated in your Entity Objects are automatically enforced through this service interface as well.
- You can use any application module both as a local component and as remotely-accessible service. This allows you to support both interactive Web user interfaces as well as programmatic Web-service clients with the same component.
Entity object
- An entity object represents a row in a database table and simplifies modifying its data by handling all DML operations for you. It can encapsulate business logic for the row to ensure your business rules are consistently enforced. You associate an entity object with others to reflect relationships in the underlying tables to create a layer of business domain objects to reuse in multiple applications.
View object
- A view object represents a SQL query and simplifies working with its results. You declaratively join, project, filter, sort, and aggregate entity object data into exactly the "shape" required by the end-user task at hand, including the ability to link a view object with others to create master/detail hierarchies of any complexity. When users modify business data using a view object, that component automatically collaborates with entity objects to consistently validate and save the changes.

The following diagram illustrates the relationship among application module, entity object, and view object. A view object defines a query and produces a row set of rows. View objects and entity objects collaborate to enable an updatable data model. Application module contains view objects and it provides transaction.

ADF Business Component Service
ADF BC services are remotable services, typically coarse-grained and designed to be published remotely in a loosely coupled SOA architecture. It's easy to develop business services using ADF Business Components. JDeveloper allows you to publish application modules as web services which use SDOs ( Service Data Objects) to standardize the way that data structures are passed between Java and XML. JDeveloper also generates the WSDL service description that is used by the web service client in the consuming application.
When you use remote ADF Fusion Business Service, each remote call is stateless and the remote service does not participate in the same transaction as their composing parent application module. In the majority of the cases, calls to remote services will be informational in nature and will not be effecting changes to remote objects. However, if you must use a remote service to make changes then keep these points in mind:

An exception thrown by the remote service will cause the local transaction to fail.
However, the converse is not true.

In other words, if you successfully call a remote service that results in modifying data, and then subsequently your local transaction fails for any reason, then it is the responsibility of your error handling code to perform a compensating transaction against the remote service to "undo" the previous change made.
In this article, we will demonstrate how to create ADF BC services that exposes the top-level Employee View Object. Standard data manipulation operations on the Employee View Object including the following operations:

createEmpVO1
updateEmpVO1
deleteEmpVO1
getEmpVO1

Integrated WebLogic Server (WLS)
To run JDeveloper application in a Java EE container, it must be bound to a Server Instance. Integrated WebLogic Server (Integrated WLS) comes packaged with JDeveloper. You can run your applications directly on this server without the need to deploy. The integrated WLS is sufficient to run your application to make sure it displays correctly in browsers, or for testing and debugging portions of the application. However, real end-to-end testing should be done in a standalone WebLogic Server because that is what will be used in a production environment. For simplicity, our sample application will use Integrated WLS for deployment and testing.
JDeveloper is bundled with a WLS domain (i.e., "DefaultDomain"), and "DefaultServer" is defined for it. All JDeveloper applications are bound by default to "DefaultServer." In this document, these default settings are assumed. To view the properties of "DefaultServer" Server Instance, in the Resource Palette -> IDE Connections -> Application Server -> IntegratedWebLogicServer, right click and select "Properties...".

Prerequisites
This article assumes that you are familiar with

ADF
WSDL
JDeveloper
Web Services

and have access to a running JDeveloper and a running Oracle Database with EMP table in SCOTT schema. The resources section at the end provides you with pointers to documentation and tutorials.

Create Schema-Object-Based Entity Object
Step 1: Create a New Fusion Web Application (ADF)

Open the New Gallery wizard and choose Fusion Web Application (ADF) [File > New > General > Applications > Fusion Web Application (ADF)]
In the Create Fusion Web Application (ADF) wizard, specify your application name (e.g., EmployeeWS)
Click Finish.

Step 2: Create the Entity Object
To create a single entity object, you can use the Create Entity Object wizard, which is available in the New Gallery:

In the Application Navigator, select the Model project and open Create Entity Object wizard [File > New > Business Tier > ADF Business Components > Entity Object].
- Because this is the first component you're creating in the project, the Initialize Business Components Project dialog appears to allow you to select a database connection.
- Edit the Connection in the Initialize Business Components Project wizard by clicking on "pencil" icon. Note that you may need to change the Connection name if it's already being used.
- Enter scott as username and tiger as password. We're going to use EMP table in SCOTT Schema for this example.
- Click Test Connection to confirm that you can connect.
- Click OK if the connection was successful.
- Click OK to close Initialize Business Components Project wizard.
In the "Create Entity Object - Step 1 of 6", enter "EMP" as Schema Object. Click Next.

Click Next to skip "Create Entity Object - Step 2 of 6".
In the "Create Entity Object - Step 3 of 6", make "Empno" attribute a primary key by checking "Primary Key" box. Click Next.

Click Next to skip "Create Entity Object - Step 4 of 6".
In the "Create Entity Object - Step 5 of 6", check "Generate Default View Object" box. Then, check Application Module box. Click Next.

Click Finish.

Step 3: Generate SDO Class
Following the guidelines specified by the Open SOA [2] collaboration, the application module's web service uses Service Data Objects [6] to standardize the way that data structures are passed between Java and XML.
View objects are published in web services as SDOs. Follow the steps below to generate SDO classes for your view objects.

In the Application Navigator, double-click the EmpVO.
In the View Object Editor, select the Java tab.
In the Java page, click the Edit icon in the Java Classes section. The Edit icon resembles a pencil.
In the "Select Java Options" wizard, check "Generate Service Data Object Class" box. Click OK.

You should be able to see the following files are generated:

Emp.java
Emp.xsd
EmpImpl.java

Note that this step actually is optional. If you skip and proceed directly to step 4, JDeveloper will still generate those SDO files for you.

Step 4: Publish Application Module as Web Service
You can use any application module both as a local component and as remotely-accessible service. This allows you to support both interactive Web user interfaces as well as programmatic Web-service clients with the same component.
JDeveloper creates the web service implementation wrapper and other files required to expose the application module as a web service. If you make changes to your application module's declarative service interface settings, JDeveloper automatically keeps the related web service artifacts in sync.
You publish your application module as web service:

In the Application Navigator, double-click the AppModuleAM.
In the Application Module Editor, select Service Interface to open the Service Interface page.
In the Service Interface page, select the '+' sign to enable support for service interface.
Use the Create Service Interface wizard to configure the options you want.
On the Service Interface page of the wizard, click Next twice to skip step 1 and 2.
On the Service View Instances page, select Emp1 and shuttle it over to the Selected list, and enable Create, Update, Delete, and GetByKey in the Basic Operations section. Then click Finish.

You should be able to see the following files are generated under AppModuleAM->serviceInterface

AppModuleAMServiceImpl.java
AppModuleAMService.java
AppModuleAMService.wsdl
AppModuleAMService.xsd

Step 5: Test the Application Modlue in the Oracle Business Component Browser
You can test the application module in the Oracle Business Component Browser:

In the Application Navigator, right-click AppModuleAM and choose Run.
In the Oracle Business Component Browser, double-click EmpVO1.
Click ">" icon to navigate to the next record.
Jot down Empno (e.g., "7369") for the next step.

Step 6: Test ADF BC Service
You can test your service interface without deploying it by selecting the generated web service class in the Application Navigator and choosing Run on the right-mouse menu. JDeveloper starts the embedded WebLogic Server (WLS) instance, and then provides a built-in web service testing tool where you can enter sample data for any of the service methods and verify the result returned.

In the Application Navigator, right-click the AppModuleServiceImpl.java in the serviceInterface folder and select Run.
Select Target URL (i.e., http://localhost:7101/EmployeeWS-Model-context-root/AppModuleAMService) in the Running: DefaultServer Log view and click on it.
Test ADF BC Service using HTTP Analyzer.
On the HTTP Analyzer page, select AppModuleServiceSoapHttpPort.getEmp1 from the operation's pull-down list.
Enter a valid empno (e.g., "7369") and send the request.

References

Saturday, December 18, 2010

How to Create Oracle ADF BC Services

2 comments: