Saturday, December 18, 2010

How to Create Oracle ADF BC Services (2)

This article is a continued writing from the previous how-to article. Here we will demonstrate how to create an ADF BC service using Create Business Components from Tables wizard.

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., EmployeeWS2)
    • Specify "oracle.apps" to be your Default Package name
  • Click Finish.

Step 2: Creating a Database Connection[8]

  • Open the Create Database Connection dialog [File > New > General > Connections > Database Connection] .
  • Select Application Resources if it is not selected as the Create Connection In option.
  • Enter a name for the connection, select the connection type, and enter the username and password (use scott/tiger because we're going to use EMP table in SCOTT schema)
  • Click Test Connection to confirm that you can connect.
  • Click OK if the connection was successful.

Step 3: Create Business Components from Tables

When you create an entity object from an existing table, first JDeveloper interrogates the data dictionary to infer the following information: the primary and unique key attributes, the SQL and Java data types of each attribute based on those of the underlying column, etc.
JDeveloper then creates the XML component definition file that represents its declarative settings and saves it in the directory that corresponds to the name of its package. This XML file contains the name of the table, the names and data types of each entity attribute, and the column name for each attribute.
  • In the Application Navigator, select the Model project and launch the Create Business Components from Tables wizard [File > New > Business Tier > ADF Business Components > Business Components from Tables].

  • In the Initialize Business Components Project dialog which opens before the wizard, confirm that the database connection you created is the current selection and click OK.
  • On step 1 of the Create Business Components from Tables wizard, Entity Objects, enter EMP% in Name Filter, click Query to populate the Available list.
  • Select EMP table from the Available list and shuttle it to the Selected list to create default business components based on it. Then click Next.

  • On step 2, Updatable View Objects, select business component, EmpView(Emp), from the Available list and shuttle it to the Selected list. Then click Next.

  • On step 3, Read-Only View Objects, skip it.
  • On step 4, Application Module, click Finish.
    • Each ADFbc service needs to have a backing application module. The view object instances in the application module can be published as SDOs.
  • Click Save All to save your work.

Step 4: Edit the View Object

  • In the Application Navigator, double-click EmpView in the Model project to open it in the view object editor.
  • Select the Attributes tab to display all the attributes in the EmpView view object.
  • In the attributes table, select attribute Empno and edit it. Make it a key by checking Key Attribute.

  • In the attributes table, select attribute RowID and delete it (see previous how-to article for explanation)

  • Click Save All to save your work.

Step 5: Edit the Entity Object

  • In the Application Navigator, double-click Emp entity object in the Model project to open it in the entity object editor.
  • Select the Attributes tab to display all the attributes in the Emp entity object.
  • In the attributes table, select attribute Empno and edit it. Make it a primary key by checking Primary Key.

  • In the attributes table, select attribute RowID and delete it.
  • Click Save All to save your work.

Test the Application in the Business Component Tester

  • In the Application Navigator, right-click AppModuleAM and choose Run.
  • In the Oracle Business Component Browser, double-click EmpView1.
  • Jot down the Empno (i.e., 7369) shown in the diagram. You need this information in the test step below (i.e., step 7)
  • Click '>' icon to navigate to the next record.

Step 6: Publish Application Module as Web Service

  • In the Application Navigator, double-click the AppModule.
  • In the Application Module Editor, select Service Interface tab to open the Service Interface page.
  • In the Service Interface page, select the '+' icon to enable support for service interface.
  • Use the Create Service Interface wizard to configure the options you want.
    • Click twice to skip Step 1 and 2 (we use default settings).
    • On the Service View Instances page, select EmpView1 and shuttle it over to the Selected list, and enable Create, Delete, Update, and GetByKey in the Basic Operations section. Then click Finish.
  • You should be able to see the following files are generated under AppModule ->serviceInterface:
    • AppModuleServiceImpl.java
    • AppModuleService.java
    • AppModuleService.wsdl
    • AppModuleService.xsd

Step 7: Test ADFbc Service

  • In the Application Navigator, right-click the AppModuleServiceImpl.java in the serviceInterface folder and select Run.
  • Select Target URL (i.e., http://localhost:7101/EmployeeWS2-Model-context-root/AppModuleService) in the Running:DefaultServer Log window and click on it.
  • Test ADF BC Service using HTTP Analyzer.

Possible Improvements and Other Use Cases

An application module can expose its standard CRUD methods of view objects to web service clients without requiring any custom Java code. When used without customization, your component is completely defined by its XML component definition and it will be fully functional without custom Java code or even a Java class file for the component. If you have no need to extend the built-in functionality of a component in ADF Business Components, and no need to write any custom code to handle its built-in events, you can use the component in this XML-only fashion. However, sometimes you do need to write custom methods and expose them as service methods. For example, your custom methods can:
  • Configure view object properties to query the correct data to display
  • Iterate over view object rows to return an aggregate calculation
  • Perform any kind of multistep procedural logic with one or more view objects
In the next step, we will show sayHello as our custom method for simplicity.

Customizing an Application Module with Service Methods

To add a custom service method to your application module, you must first enable a custom Java class for it. To generate a Java file for your application module class:
  1. In the Application Navigator, double-click the application module.
  2. In the overview editor, click the Java navigation tab.
  3. On the Java Classes page, click Edit Java Classes (i.e., pencil icon).
  4. In the Select Java Options dialog, select Generate Application Module Class.
  5. Click OK and click Save All button.

To add sayHello service method to Employee Service and publish it to the service interface:
  1. In the Application Navigator, double-click the AppModuleImpl.java.
  2. Add the following code snippets at the bottom of the file:
     public String sayHello(String name) {
    return "Hi " + name;
    }
  3. Click Save to save changes.
  4. In the Application Navigator, double-click the application module.
  5. In the overview editor, click the Service Interface navigation tab.
  6. On the Service Interface page, click Edit Service Interface Custom Methods (i.e. pencil icon).
  7. On the Service Custom Methods dialog, shuttle sayHello(Strig):String from the Available list to the Selected list. Click OK.
  8. Click Save All to save your work.
  9. Use Step 8 above to test it.

Creating Multiple Entity Objects and Associations

To create a single entity object, you can use Create Entity Object wizard. However, if you need to create multiple entity objects and associations from existing tables, you use the Create Business Components from Tables wizard. See Section 4 "Creating a Business Domain Layer Using Entity Objects" in [4] for more details.
The Create Business Components from Tables wizard makes it easy to quickly generate many business components at the same time. In practice, this does not mean that you should use it to immediately create entity objects for every table in your database schema just because it is possible to do so. If your application requires all of the tables, then that strategy might be appropriate. But because you can use the wizard whenever needed, you should create the entity objects for the tables that you know will be involved in the application.
Section 9.4 "Defining Nested Application Modules" in [4] describes a use case-driven design approach for your business services that can assist you in understanding which entity objects are required to support your application's business logic needs. You can always add more entity objects later as necessary.

Generic Application Template

Notice that we've created our application using Fusion Web Application (ADF) template. Two projects have been created for us: Model and ViewController. However, if you don't plan to create UI components using ViewController project, you might be better off using "Generic Application" template.

In this case, you need to select ADF Business Components from the list of available technologies in step 2 of Create Generic Application wizard and shuffle it to the right as shown below:
This will create an application with an empty project preconfgured for you to create your ADF-BC Components and ADF-BC services.
References
  1. ADF Business Components
  2. Open SOA
  3. Oracle Application Development Framework
  4. Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework 11g Release 1 (11.1.1)
  5. Oracle JDeveloper
  6. Service Data Objects Home
  7. Web Services Description Language (WSDL) 1.1
  8. Database Connections in JDeveloper 11
  9. Open Source sample applications for Oracle Fusion Middleware technology

No comments: