3 Getting Started with ADF Business Components

This chapter describes getting started with the ADF Business Components in Oracle ADF applications. It describes key features such as the design-time wizards, overview editors, and ADF Model Tester. It also provides an overview of the process that you follow when creating business components in the data model project.

This chapter includes the following sections:

3.1 About ADF Business Components

In the Fusion web application, the business service layer handles connecting to the database, retrieving data, locking database records, and managing transactions. Consider the following three simple examples of business service layer functionality:

  • New data appears in relevant displays without requerying

    A person logs into a customer management application and displays a customer and their existing orders. Then if the person creates a new order, when he views the inventory for the ordered product, the amount of product in stock is updated without the need to requery the database.

  • Changes caused by business domain logic automatically reflected

    A back office application causes an update to the order status. Business logic encapsulated in the Orders entity object in the business domain layer contains a simple rule that updates the last update date whenever the order status attribute is changed. The user interface updates to automatically reflect the last update date that was changed by the logic in the business domain layer.

  • Invocation of a business service method by the ADF Model layer binding requeries data and sets current rows

    In a tree display, the end user clicks on a specific node in a tree. This action declaratively invokes a business service method by the ADF tree binding on your application module that requeries master-detail information and sets the current rows to an appropriate row in the row set. The display updates to reflect the new master-detail data and current row displayed.

Developers save time building business services using ADF Business Components since the JDeveloper design time makes typical development tasks entirely declarative. In particular, JDeveloper supports declarative development with ADF Business Components to:

  • Author and test business logic in components which automatically integrate with databases

  • Reuse business logic through multiple SQL-based views of data, supporting different application tasks

  • Access and update the views from browser, desktop, mobile, and web service clients

  • Customize application functionality in layers without requiring modification of the delivered application

ADF Business Components supports the business service layer through the following set of cooperating business components:

  • Entity object

    An entity object represents a row in a database table and simplifies modifying its data by handling all data manipulation language (DML) operations for you. It can encapsulate business logic for the row to ensure that your business rules are consistently enforced. You associate an entity object with others to reflect relationships in the underlying database schema to create a layer of business domain objects to reuse in multiple applications.

  • View object

    A view object represents a SQL query. You use the full power of the familiar SQL language to join, filter, sort, and aggregate data into exactly the shape required by the end-user task. This includes the ability to link a view object with others to create master-detail hierarchies of any complexity. When end users modify data in the user interface, your view objects collaborate with entity objects to consistently validate and save the changes.

  • Application module

    An application module is the transactional component that UI clients use to work with application data. It defines an updatable data model and top-level procedures and functions (called service methods) related to a logical unit of work related to an end-user task.

Figure 3-1 shows the overall components of the ADF Business Components and their relationships.

Figure 3-1 Overview of ADF Business Components

overview of ADF Business Components

3.1.1 ADF Business Components Use Cases and Examples

ADF Business Components provides a foundation of Java classes that allow the business service layer of the Fusion web application to leverage the functionality depicted in the following examples:

Simplify Data Access

  • Design a data model for client displays, including only necessary data

  • Include master-detail hierarchies of any complexity as part of the data model

  • Implement end-user Query-by-Example data filtering without code

  • Automatically coordinate data model changes with the business services layer

  • Automatically validate and save any changes to the database

Enforce Business Domain Validation and Business Logic

  • Declaratively enforce required fields, primary key uniqueness, data precision-scale, and foreign key references

  • Easily capture and enforce both simple and complex business rules, programmatically or declaratively, with multilevel validation support

  • Navigate relationships between business domain objects and enforce constraints related to compound components

Support User Interfaces with Multipage Units of Work

  • Automatically reflect changes made by business service application logic in the user interface

  • Retrieve reference information from related tables, and automatically maintain the information when the end user changes foreign-key values

  • Simplify multistep web-based business transactions with automatic web-tier state management

  • Handle images, video, sound, and documents without having to use code

  • Synchronize pending data changes across multiple views of data

  • Consistently apply prompts, tooltips, format masks, and error messages in any application

  • Define custom metadata for any business components to support metadata-driven user interface or application functionality

  • Add dynamic attributes at runtime to simplify per-row state management

Implement a Service-Oriented Architecture

  • Support highly functional web service interfaces for business integration without writing code

  • Enforce best-practice interface-based programming style

  • Simplify application security with automatic JAAS integration and audit maintenance

  • "Write once, run anywhere": use the same business service as plain Java class or web service

Support Application Customization

  • Extend component functionality after delivery without modifying source code

  • Globally substitute delivered components with extended ones without modifying the application

  • Deliver application upgrades without losing or having to reapply downstream customizations manually

3.1.2 Additional Functionality for ADF Business Components

You may find it helpful to understand related Oracle ADF features before you start working with ADF Business Components. Following are links to other functionality that may be of interest.

3.2 Creating the ADF Business Components Data Model Project

JDeveloper includes comprehensive design time support for ADF Business Components. Collectively, these facilities let you create, edit, diagram, test, and refactor the business components.

3.2.1 How to Create a Data Model Project for ADF Business Components

JDeveloper provides an application template that aids in creating databound web applications with Oracle ADF. When you use the ADF Fusion Web Application template, your application will consist of one project for the data model (with ADF Business Components) and another project for the view and controller components (ADF Faces and ADF task flows).

Before you begin:

It may be helpful to have an understanding of the Fusion web application. For more information, see Chapter 1, "Introduction to Building Fusion Web Applications with Oracle ADF."

You may also find it helpful to understand ADF Business Components preferences that can be specified globally across data model projects. For more information, see Section 3.2.9, "How to Customize ADF Business Components Preferences."

You may also find it helpful to understand more about the tools and features that JDeveloper provides to create and manage applications. For more information, see the "Getting Started with Developing Applications with Oracle JDeveloper" chapter in Developing Applications with Oracle JDeveloper.

To create a data model project with the ADF Fusion Web Application template:

  1. In the main menu, choose File and then Application > New.

  2. In the New Gallery, in the Items list, double-click ADF Fusion Web Application.

  3. In the Create ADF Fusion Web Application wizard, enter application details like the name and directory. For help with the wizard, press F1.

    The Project 1 Name page of the wizard shows the list of features needed to complete the data model project. The project feature ADF Business Components should appear in the list.

  4. Click Finish.

3.2.2 How to Add an ADF Business Components Data Model Project to an Existing Application

Applications that you create without using a predefined technology template, may be constructed by adding project folders from the New Gallery. When you add a project for ADF Business Components, you will select ADF Model Project from the list in the New Gallery. This creates a project that defines a data model for an ADF web application that relies on ADF Business Components.

Before you begin:

It may be helpful to have an understanding of the Fusion web application. For more information, see Chapter 1, "Introduction to Building Fusion Web Applications with Oracle ADF."

You may also find it helpful to understand more about the tools and features that JDeveloper provides to create and manage applications. For more information, see the "Getting Started with Developing Applications with Oracle JDeveloper" chapter in Developing Applications with Oracle JDeveloper.

To add an ADF model project to your application:

  1. In the Applications window, select any existing project and in the main menu, choose File and then New > Project.

  2. In the New Gallery, in the Items list, double-click ADF Model Project.

  3. In the Create ADF Model Project wizard, enter project details like the name and directory. For help with the wizard, press F1.

    The Project Name page of the wizard shows the list of features needed to complete the model project. The project feature ADF Business Components should appear in the list.

  4. Click Finish.

3.2.3 How to Initialize the Data Model Project With a Database Connection

The first time you create a business component in your ADF Business Components model project, you'll see the Initialize Business Components Project dialog shown in Figure 3-2. You use this dialog to select a design time application resource connection to use while working on your business components in this data model project or to create a new application resource connection by copying an existing IDE-level connection. You can specify whether the database that JDeveloper will use to create business components will be online or offline. The dialog default specifies an online database, for more details about working with an offline database, see Section 3.2.4, "How to Change the Data Model Project to Work With Offline Database Objects."

Figure 3-2 Initialize Business Components Project Dialog

Initialize Business Components Project dialog

Since this dialog appears before you create your first business component, you also use it to globally control the SQL platform that the view objects will use to formulate SQL statements. SQL platforms that you can choose include:

  • Oracle SQL platform for an Oracle database connection (the default)

  • OLite for the Oracle Lite database

  • SQLServer for a Microsoft SQLServer database

  • DB2 for an IBM DB2 database

  • SQL92 for any other supported SQL92- compliant database

Note:

If you plan to have your application run against both Oracle and non-Oracle databases, you should select the SQL92 SQL platform when you begin building your application, not later. While this sacrifices some of the Oracle-specific optimizations that are inherent in using the Oracle SQL platform, it makes the application portable to both Oracle and non-Oracle databases.

Additionally, the dialog lets you determine which set of data types that you want the data model project to use. JDeveloper uses the data type selection to define the data types of attributes when you create entity object and view objects in the data model project. It is therefore important that you make the appropriate selection before you save the settings in the Initialize Business Components Project dialog. The dialog provides these options:

  • Java Extended for Oracle type map is selected by default if JDeveloper detects you are using an Oracle database driver. The Java Extended for Oracle type map uses standard Java types and the optimized types in the oracle.jbo.domain package for common data types.

    Tip:

    New Fusion web applications should use the default Java Extended for Oracle type.

  • Java type map is provided to support applications that will run on a non-Oracle database and that you create using SQL92-compliance. In this case, you should set the data type map to Java to globally use only the basic Java data types.

  • Oracle Domains type map is provided for backward compatibility and for ADF applications that do not use ADF Faces as the view layer technology, as explained in Section 3.2.7, "What You May Need to Know About Displaying Numeric Values."Please note that when you migrate an application developed with JDeveloper version 11.1.1.4.0 or earlier, your application will continue to use the Oracle Domains type map and will not change to the current default type map Java Extended for Oracle

Once you save project selections in the Initialize Business Components Project dialog, the project is considered initialized. You will not be able to change the data type map of the initialized project and it is not recommended to change the SQL platform after you have created business components.

Before you begin:

It may be helpful to have an understanding about database connections as resources in JDeveloper. For more information, see the "Connecting to and Working with Databases" chapter in Developing Applications with Oracle JDeveloper.

You will need to complete these tasks:

To initialize the data model project:

  1. In the Application window, right-click the model project in which you want to create business components and choose New > Business Components from Tables.

    You can select any other ADF Business Components option, but the option to create business components from tables is particularly useful for generating the first pass of business components that you anticipate needing. If you do not see ADF Business Components options in the context menu, make sure that a model project created for ADF Business Components appears selected in the Applications window.

  2. In the Initialize Business Components Project dialog, leave Online Database selected and either choose an existing database resource from the dropdown list or click the Create a New Database Connection icon.

    If you are creating a database connection, enter the connection information into the Create Database Connection dialog. For help with the dialog, press F1. You can begin working with offline database objects at any time, as described in Section 3.2.4, "How to Change the Data Model Project to Work With Offline Database Objects."

  3. Select the SQL platform that your business components will use.

    You can select the SQL platform in this dialog only when you first initialize your data model project. After you initialize the project, you can override the SQL platform in the Business Components page of the overview editor for the adf-config.xml file, but you must do this before you add business components to the project. You can locate the file in the Application Resources panel by expanding the Descriptors and ADF META-INF nodes. Specifying the database type in the adf-config.xml file supports generating SQL statements during runtime that can require the actual database type of the deployed Fusion web application.

  4. Select the data type map that your business components will use. Note that you cannot change the data type map after you have initialized the data model project for ADF Business Components.

    For an application running against an Oracle database, you can usually accept the default Java Extended for Oracle which uses standard Java types wherever possible and provides custom Oracle domain types for common data types like numbers and dates. Other supported data type maps include Oracle Domains (provided for backward compatibility) and Java (select for use with SQL92-compliant applications that will run on a non-Oracle database).

  5. Click OK.

3.2.4 How to Change the Data Model Project to Work With Offline Database Objects

ADF Business Components supports using offline database as its database object provider. After you have initialized the data model project to specify a database you can switch to working with the database in offline mode. Working with an offline database to create business components in the model project lets you work in a disconnected fashion and pick up database changes when are ready. This also keeps your project independent of schema changes that might force you to make changes to the business objects.

When you create or select an existing offline database, you still need an online connection; this will be used for testing (using the Oracle ADF Model Tester) and deployment. During design time, the offline database will be used. You can also update an offline database to synchronize with the source database. A database object compare feature lets you obtain a visual mapping that you can use to accept or reject each difference.

Before you begin:

It may be helpful to have an understanding about offline databases in JDeveloper. For more information, see the "Connecting to and Working with Databases" chapter in Developing Applications with Oracle JDeveloper.

You will need to complete these tasks:

To change the data model project to work with an offline database:

  1. In the Application window, right-click the data model project in which you want to create the offline database and choose Project Properties.

  2. In the Project Properties dialog, select ADF Business Components.

  3. On the ADF Business Components page, select Offline Database and click the Create a New Offline Database icon.

  4. In the Create Offline Database dialog, enter the database and schema names that you want the data model project to display, select other options to complete the dialog, and then click OK.

    The data model project is updated with a new Offline Database Sources folder and contains an empty folder with the name of the offline database.

  5. In the Connection list, choose the online database that you will connect to when testing business components in the data model project.

    The online database and offline database that you select must have the same schema to ensure database object names and enable testing. For more information about testing business components, see Section 3.4.1, "How to Use the Oracle ADF Model Tester."

  6. Click OK.

To create offline database definitions in the data model project:

  1. In the Application window, right-click the folder in which you want to create the offline database and choose New > Offline Database Objects from Source Database.

  2. In the Reverse Engineer Database Objects wizard, on the Database page, verify that your online database connection is displayed as the Source Database and click Next.

  3. On the Select Objects page, click Query and select one or more desired methods from the Available list and click the Add button to shuttle them into the Selected list.

  4. Click Finish.

3.2.5 What You May Need to Know About Application Server or Database Independence

Applications built using ADF Business Components can be deployed to and run on any application server that Oracle certifies for ADF applications (such as Oracle WebLogic Server or GlassFish). Because business components are implemented using plain Java classes and XML files, you can use them in any runtime environment where a Java Virtual Machine is present. This means that services built using ADF Business Components are easy to use both inside a Java EE server — known as the "container" of your application at runtime — and outside. For more information about deploying ADF applications and the supported application servers, see Chapter 48, "Deploying Fusion Web Applications."

Customers routinely use application modules in such diverse configurations as command-line batch programs, web services, custom servlets, and JSP pages.

You can also build applications that work with non-Oracle databases, as described in Section 3.2.3, "How to Initialize the Data Model Project With a Database Connection." However, applications that target Oracle databases will find numerous optimizations built into ADF Business Components.

3.2.6 What You May Need to Know About Basic Data Types

ADF Business Components is compatible with the built-in data types the Java language provides, including strings, dates, and numeric data. In addition to these Java data types, the oracle.jbo.domain and oracle.ord.im packages of ADF Business Components provides types that are optimized for the Oracle database. Table 3-2 shows the ADF Business Components-specific types that you may use in addition to the built-in types provided by the Java language.

Table 3-1 Basic Data Types in the oracle.jbo.domain and oracle.ord.im Packages

Data Type Package Represents

DBSequence

oracle.jbo.domain

Sequential integer assigned by a database trigger

RowID

oracle.jbo.domain

Oracle database ROWID

BFileDomain

oracle.jbo.domain

Binary File (BFILE) object

BlobDomain

oracle.jbo.domain

Binary Large Object (BLOB)

ClobDomain

oracle.jbo.domain

Character Large Object (CLOB)

OrdImageDomain

oracle.ord.im

Oracle Intermedia Image (ORDIMAGE)

OrdAudioDomain

oracle.ord.im

Oracle Intermedia Audio (ORDAUDIO)

OrdVideoDomain

oracle.ord.im

Oracle Intermedia Video (ORDVIDEO)

OrdDocDomain

oracle.ord.im

Oracle Intermedia Document (ORDDOC)

Struct

oracle.jbo.domain

User-defined object type

Array

oracle.jbo.domain

User-defined collection type (e.g. VARRAY)

For backward compatibility, ADF Business Components still provides the option to select a set of data types in the oracle.jbo.domain and oracle.ord.im packages that were available before Java types became the standard. Table 3-2 shows the types that you may use when backward compatibility is desired.

Table 3-2 Backward Compatible Data Types in the oracle.jbo.domain and oracle.ord.im Packages

Data Type Package Represents

Number (not used by default)

oracle.jbo.domain

Any numerical data. If you receive compiler or runtime errors related to "Number is an abstract class" it means you are using java.lang.Number instead of oracle.jbo.domain.Number. Adding the following line at the top of your class, after the package line, prevents these kinds of errors:

import oracle.jbo.domain.Number;

Date

oracle.jbo.domain

Date with optional time

Timestamp

oracle.jbo.domain

Timestamp value

TimestampTZ

oracle.jbo.domain

Timestamp value with time zone information

TimestampLTZ

oracle.jbo.domain

Timestamp value with local time zone information retrieved from JavaVM or from the ADF Context when configured in the application's adf-config.xml with an EL expression:

<user-time-zone-config xmlns=
  "http://xmlns.oracle.com/adf/usertimezone/config">
  <user-timezone expression= "EL exp" />
</user-time-zone-config>

The EL expression will be evaluated to determine the time zone of the current end user; otherwise, the value defaults to the time zone of the JavaVM.

3.2.7 What You May Need to Know About Displaying Numeric Values

The Java Extended for Oracle type map and the Oracle Domains type map handle numeric data differently. When you create a new application the default type map Java Extended for Oracle maps numeric data to the java.math.BigDecimal class, which inherits from java.math.Number. The java.math.BigDecimal default matches the way the Fusion web application view layer, consisting of ADF Faces components, preserves alignment of numeric data (such as numeric values displayed by ADF Faces input fields in a web page). Whereas the Oracle Domains type map, which maps numeric data to the oracle.jbo.domain.Number class, may not display the data with the alignment expected by certain ADF Faces components. Aside from this alignment issue, the Oracle Domains type map remains a valid choice and applications without ADF Faces components will function without issue.

3.2.8 How to Customize Model Project Properties for ADF Business Components

Before you begin creating business components, it is a good idea to familiarize yourself with the many project properties that are available to configure ADF Business Components. Selections that you make in the Project Properties dialog will apply to the data model project you are editing. You can specify a variety of properties including suffix naming conventions for generated business components and subpackage names for the data model project.

Before you begin:

It may be helpful to have an understanding about managing projects in JDeveloper. For more information, see the "Getting Started with Developing Applications with Oracle JDeveloper" chapter in Developing Applications with Oracle JDeveloper.

You may also find it helpful to understand preferences that can be specified globally across data model projects. For more information, see Section 3.2.9, "How to Customize ADF Business Components Preferences."

You will need to complete this task:

Create the data model project for ADF Business Components, as described in Section 3.2.1, "How to Create a Data Model Project for ADF Business Components."

To customize data model project properties:

  1. In the Application window, right-click the project in which you want to create the shared application module and choose Project Properties.

  2. In the Project Properties dialog, expand ADF Business Components and select the desired node in the tree. For help with any of the pages of the dialog, press F1.

3.2.9 How to Customize ADF Business Components Preferences

Many design time and runtime options that you can configure for ADF Business Components are specified at the level of JDeveloper preferences. It is a good idea to familiarize yourself with these preferences for ADF Business Components. Selections that you make in the Preferences dialog will apply to each data model project you create.

Certain preferences that you specify globally may be overridden for individual data model projects, as described in Section 3.2.8, "How to Customize Model Project Properties for ADF Business Components."

Before you begin:

You may also find it helpful to understand properties that can be specified for individual data model projects. For more information, see Section 3.2.8, "How to Customize Model Project Properties for ADF Business Components."

You will need to complete this task:

Create the data model project for ADF Business Components, as described in Section 3.2.1, "How to Create a Data Model Project for ADF Business Components."

To customize ADF Business Components preferences:

  1. In JDeveloper, choose Tools > Preferences.

  2. In the Preferences dialog, expand ADF Business Components and select the desired node in the tree. For help with any of the pages of the dialog, press F1.

3.3 Creating and Editing Business Components

JDeveloper includes comprehensive design time support to create and customize the business components of the data model project. These facilities let you create the components using dedicated wizards, modify their properties with overview editors, and view their definition files in source editors.

3.3.1 How to Create New Components Using Wizards

In the New Gallery, in the ADF Business Components category, JDeveloper offers a wizard to create each kind of business component. Each wizard allows you to specify the component name for the new component and to select the package into which you'd like to organize the component. If the package does not yet exist, the new component becomes the first component in that new package.

Each wizard presents a series of panels that capture the necessary information to create the component type. When you click Finish, JDeveloper creates the new component by saving its XML document file. And, when you change the default Code Generation option in the ADF Business Components - Options page of the Project Properties dialog to generate custom Java class files, JDeveloper can also create initial custom Java class files in addition to the XML document file.

The Create Business Components from Tables wizard is particularly useful in JDeveloper because it is the only wizard that combines generating the various business component types in a single end to end process. This wizard lets you create a large number of business components quickly and easily. You can create entity objects based on an online or offline database, then you can create either entity-based view objects or query-based view objects, and an application module to contain the view instances of the data model. Finally, the wizard gives you the option to generate a business components diagram to display the relationships between the collaborating business components.

After you use a wizard, you can edit any business components you create and you can add new business components later.

Before you begin:

It may be helpful to have an understanding of the various ADF business components. For more information, see Section 3.1, "About ADF Business Components."

You will need to complete this task:

Create the data model project that will contain the business components, as described in Section 3.2.1, "How to Create a Data Model Project for ADF Business Components."

To create collaborating business components in one pass:

  1. In the Applications window, right-click the project in which you want to create the entity objects and choose New.

  2. In the New Gallery, expand Business Tier, select ADF Business Components and then Business Components from Tables, and click OK.

    If 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. Complete the dialog, as described in Section 3.2.3, "How to Initialize the Data Model Project With a Database Connection."

  3. In the Create Business Components from Tables wizard, on the Entity Objects page, filter the database schema to display available database objects and select those database objects for which you want to create entity objects. Click Next.

  4. On the Entity-based View Objects page, select among the available entity objects to create updatable view object definitions for your entity object definitions. Click Next.

    Note that the view object definitions you create in this wizard will contain a single usage of an entity object, and will expose all the attributes in that object.

  5. On the Query-based View Objects page, select among the available database objects to create read-only view object definitions. Click Next.

  6. On the Application Module page, leave the default selections unchanged, and click Next.

  7. On the Diagram page, select Add to Business Components Diagram, and click Next.

  8. On the Summary page, review the list of business components that the wizard will create, and click Finish

3.3.2 How to Create New Components Using the Context Menu

Once a package exists in the Applications window, you can quickly create additional business components of any type by selecting the package in the Applications window and using one of the options on the context menu, as shown in Figure 3-3.

Figure 3-3 Context Menu Options on a Package to Create Any Kind of Business Component

Context menu options in Application Navigator

The Applications window context menu displays options that are appropriate for the project that you right-click. If the context menu does not display ADF Business Components options, confirm that the project you right-clicked is an ADF Business Components model project.

Before you begin:

It may be helpful to have an understanding of the various ADF business components. For more information, see Section 3.1, "About ADF Business Components."

You will need to complete this task:

Create the data model project that will contain the business components, as described in Section 3.2.1, "How to Create a Data Model Project for ADF Business Components."

To add individual business components to the data model project:

  1. In the Applications window, right-click the package in the model project in which you want to create a new business component and choose New - business component name.

  2. In the wizard for the business component, complete the pages of the wizard and click Finish. For help with any of the pages of the wizard, press F1.

3.3.3 What Happens When You Create Business Components

Each kind of component in ADF Business Components comes with built-in runtime functionality that you control through declarative settings. These settings are stored in an XML document file with the same name as the component that it represents. Figure 3-4 shows how the Applications window displays the XML document for each business component in the data model project.

Figure 3-4 Applications Window Displays Component XML Files

Application Navigator with component files

Figure 3-5 illustrates the XML document file for an application-specific component like an application module named YourService that you create in a package named com.yourcompany.yourapp. The corresponding XML document resides in a ./com/yourcompany/yourapp subdirectory of the data model project's source path root directory. That XML file records the name of the Java class it should use at runtime to provide the application module implementation. In this case, the XML records the name of the base oracle.jbo.server.ApplicationModuleImpl class provided by Oracle ADF.

Figure 3-5 XML Document File for an Application Module

Component definition file for application module

When used without customization, your component is completely defined by its XML document 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.

When you need to write custom code for a component, for example to augment the component's behavior, you can enable an optional custom Java class for the component in question, as described in Section 3.5.1, "How to Generate Business Component Java Subclasses."

3.3.4 What You May Need to Know About the Model Project Organization

Since ADF Business Components is implemented in Java, its classes and interfaces are organized into packages. Java packages are identified by dot-separated names that developers use to arrange code into a hierarchical naming structure.

The classes and interfaces that comprise the source code provided by ADF Business Components reside in the oracle.jbo package and numerous subpackages. However, in day to day work with ADF Business Components, you'll work typically with classes and interfaces in these two key packages:

  • The oracle.jbo package, which contains all of the interfaces that are designed for the business service client to work with

  • The oracle.jbo.server package, which contains the classes that implement these interfaces

Note:

The term client here refers to any code in the model, view, or controller layers that accesses the application module component as a business service.

Figure 3-6 shows a concrete example of the application module component. The client interface for the application module is the ApplicationModule interface in the oracle.jbo package. This interface defines the names and signatures of methods that clients can use while working with the application module, but it does not include any specifics about the implementation of that functionality. The class that implements the base functionality of the application module component resides in the oracle.jbo.server package and is named ApplicationModuleImpl.

Figure 3-6 ADF Business Components Separate Interface and Implementation

Separation of interface and implementation

3.3.5 What You May Need to Know About Package Naming Conventions

Since ADF Business Components is implemented in Java, the components of your application (including their classes, interfaces, and metadata files) will also be organized into packages.

To ensure that your components won't clash with reusable components from other organizations, choose package names that begin with your organization's name or web domain name. So, for example, the Apache organization chose org.apache.tomcat for a package name related to its Tomcat web server, while Oracle picked oracle.xml.parser as a package name for its XML parser. Components you create for your own applications might reside in packages with names like com.yourcompany.yourapp and subpackages of these.

As a specific example, the business components that make up the main business service for the Summit sample application for Oracle ADF are organized into the oracle.summit.model package and its subpackages. As shown in Figure 3-7, these components reside in the Model project in the SummitADF workspace, and are organized as follows:

  • oracle.summit.model.diagram contains the business components diagram

  • oracle.summit.model.entities contains the entity objects

  • oracle.summit.model.services contains the SummitAppModule application module

  • oracle.summit.model.views contains the view objects

Figure 3-7 Organization of ADF Business Components in the Core Summit ADF Sample Application

Application Navigator and model layer

In your own applications, you can choose any package organization that you believe best. In particular, keep in mind that you are not constrained to organize components of the same type into a single package.

There is no optimal number of components in a package. However, the best structure should fall somewhere between the two extremes of placing all components in a single package and placing each component in its own, separate package.

One thing to consider is that the project is the unit of granularity that JDeveloper supports for reuse in other data model projects. So, you might factor this consideration into how you choose to organize components. For more information, see Section 44.2, "Packaging a Reusable ADF Component into an ADF Library."

3.3.6 What You May Need to Know About Renaming Components

JDeveloper supports component refactoring through specific refactoring actions that help you to incorporate changes as your application evolves. When you use JDeveloper to refactor the business components of your data model project, you can rename components or move them to a different package and JDeveloper will find and update all references to the refactored component. Whenever possible, you should use JDeveloper's refactoring actions to avoid error-prone manual editing of the project. For more information about the usages and limitations of refactoring business components in the data model project, see Chapter 43, "Refactoring a Fusion Web Application."

3.3.7 How to Edit Components Using the Component Overview Editor

Once a business component exists, you can edit its properties using the respective overview editor that you access either by double-clicking the component in the Applications window or by selecting it and choosing the Open option from the context menu.

The overview editor presents the same editing options that you see in the wizard but it may arrange them differently. The overview editor allows you to change any aspect of the component. When you make a change in the component's editor, JDeveloper updates the component's XML document file and, if necessary, any of its related custom Java files. Because the overview editor is a JDeveloper editor window, rather than a modal dialog, you can open and view the overview editor for as many components as you require.

Before you begin:

It may be helpful to have an understanding of the tools available for managing project. For more information, see the "Working with Oracle JDeveloper" chapter in Developing Applications with Oracle JDeveloper.

You will need to complete this task:

Create the business components in the data model project, as described in Section 3.3.1, "How to Create New Components Using Wizards."

To edit properties of a business component in the data model project:

  1. In the Applications window, right-click the business component that you want to edit and choose Open.

  2. In the overview editor for the business component, click the navigation tabs on the left to view and edit related groups of properties. For help with any of the pages of the overview editor, press F1.

  3. In the overview editor, click the Source tab to view the changes in the XML definition source.

  4. In the overview editor, click the History tab to view the revision history and compare the XML source of what appears in the current overview editor with a past revision.

    For details about managing the versions of files, see the "Versioning Applications with Source Control" chapter in Developing Applications with Oracle JDeveloper.

  5. In JDeveloper, choose File > Save to save the property changes to the business component XML definition file.

3.4 Testing, Refactoring, and Visualizing Business Components

JDeveloper includes comprehensive design time support to manage the growing number of business components that you create in the data model project. These facilities let you test, refactor, and visualize the business components.

3.4.1 How to Use the Oracle ADF Model Tester

Once you have created an application module component, you can test it interactively using the built-in Oracle ADF Model Tester. To launch the Oracle ADF Model Tester, select the application module in the Applications window or in the business components diagram and choose either Run or Debug from the context menu.

Figure 3-8 Oracle ADF Model Tester

ADF Model Tester

As shown in Figure 3-8, Oracle ADF Model Tester presents the view object instances in the application module's data model and allows you to interact with them using a dynamically generated user interface. The tool also provides a list of the application module's client interface methods that you can test interactively by double-clicking the application module node. This tool is invaluable for testing or debugging your business service both before and after you create the web page view layer.

Before you begin:

It may be helpful to have an understanding of the runtime behavior of the data model project. For more information, see Chapter 8, "Testing View Instance Queries."

You may also find it helpful to understand functionality that can be used to test Oracle ADF applications, including ADF business components. For more information, see Chapter 42, "Testing and Debugging ADF Components."

You will need to complete this task:

Create the business components in the data model project, as described in Section 3.3.1, "How to Create New Components Using Wizards."

To test view instances in an application module configuration:

  1. In the Applications window, right-click the application module that you want to test and choose Run.

    Alternatively, choose Debug when you want to run the application in the Oracle ADF Model Tester with debugging enabled.

  2. To execute a view instance in the Oracle ADF Model Tester, expand the data model tree and double-click the desired view instance node.

  3. Right-click a node in the data model tree to display the context menu for that node. For example, on a view instance node you can reexecute the query if needed, to remove the view instance from the data model tree, and perform other tasks.

  4. Right-click the tab of an open data viewer to display the context menu for that tab. For example, you can close the data viewer or open it in a separate window.

3.4.2 What You May Need to Know About Obtaining Oracle ADF Source Code

Since ADF Business Components is often used for business critical applications, it's important to understand that the full source for Oracle ADF, including ADF Business Components, is available to supported customers through Oracle Worldwide Support. The full source code for Oracle ADF can be an important tool to assist you in diagnosing problems, as described in Section 42.8, "Using the ADF Declarative Debugger." Working with the full source code for Oracle ADF also helps you understand how to correctly extend the base framework functionality to suit your needs, as described in Section 16.3, "Customizing Framework Behavior with Extension Classes."

3.4.3 How to Find Business Component Usages in the Data Model Project

Before you modify the names of database objects in your offline database or the names of ADF business components, you can view all objects that reference a selected item. You use the Find Usages page in the Log window to display all data model project usages of a selected item.

Before you begin:

It may be helpful to have an understanding of JDeveloper support for refactoring. For more information, see the "Working with Java Code" chapter in Developing Applications with Oracle JDeveloper.

You may also find it helpful to understand the limitations of refactoring ADF business components. For more information, see Section 43.6, "Refactoring ADF Business Component Object Attributes."

You will need to complete this task:

Create the business components in the data model project, as described in Section 3.3.1, "How to Create New Components Using Wizards."

To find an item used by ADF business components:

  1. In the Application window, in the data model project expand data model project and select the item for which you want to discover usages.

    To find usages of database objects, expand the Offline Database Sources folder and select the desired database object.

  2. In the main menu, right-click the item and choose Find Usages.

    To find usages of database columns, display the Structure window and right-click the column in the Structure window.

  3. In the Log window, review the business components that reference the selected item.

    The Find Usages page of the Log window links the named items to editors in JDeveloper. Optionally, click an item in the list to view its details in JDeveloper.

3.4.4 How to Refactor Business Components in the Data Model Project

At any time, you can select a component in the Applications window and choose Refactor > Rename from the context menu to rename the component. The Structure window also provides a Rename context menu option for details of components, such as view object attributes or view instances of the application module data model, that do not display in the Applications window. You can also select one or more components in the navigator by using Ctrl + click and then choosing Refactor > Move from the context menu to move the selected components to a new package. References to the old component names or packages in the current data model project are adjusted automatically.

Before you begin:

It may be helpful to have an understanding of JDeveloper support for refactoring. For more information, see the "Working with Java Code" chapter in Developing Applications with Oracle JDeveloper.

You may also find it helpful to understand the limitations of refactoring ADF business components. For more information, see Section 43.6, "Refactoring ADF Business Component Object Attributes."

You will need to complete this task:

Create the business components in the data model project, as described in Section 3.3.1, "How to Create New Components Using Wizards."

To refactor business components in the data model project:

  1. In the Applications window, right-click the business component and choose Refactor > Rename or Refactor > Move.

  2. To delete the object, choose Delete.

    If the object is used elsewhere in the application, a dialog appears with the following options:

    • Ignore: Unresolved usages will remain in the code as undefined references.

    • View Usages: Display a preview of the usages of the element in the Compiler log. You can use the log to inspect and resolve the remaining usages.

3.4.5 How to Refactor Offline Database Objects and Update Business Components

If you are using offline database sources with the data model project, you can rename the database, individual tables, and individual columns. JDeveloper supports refactoring of these database objects in combination with the ADF business components of the data model project, as well as the offline database itself. Changes that you make will automatically be applied to those business components whose definitions reference the database object. For example, if you change the name of a database table in the offline database, any view object queries that reference that table will be modified to use the new table name.

Before you begin:

It may be helpful to have an understanding of JDeveloper support for refactoring. For more information, see the "Working with Java Code" chapter in Developing Applications with Oracle JDeveloper.

You may also find it helpful to understand the limitations of refactoring ADF business components. For more information, see Section 43.6, "Refactoring ADF Business Component Object Attributes."

You will need to complete these tasks:

  1. Create the business components in the data model project, as described in Section 3.3.1, "How to Create New Components Using Wizards."

  2. Create the offline database in the data model project, as described in Section 3.2.4, "How to Change the Data Model Project to Work With Offline Database Objects."

To refactor offline database table names for ADF business components:

  1. In the Application window, in the data model project expand the Offline Database Sources folder and select the database object that you want to edit.

  2. In the main menu, choose Refactor > Rename.

    You can also right-click the database object and choose Refactor > Rename.

  3. In the Rename dialog, enter the new name and click Preview.

  4. In the Log window, review the business components that reference the database object name.

    The Rename page of the Log window links the named items to editors in JDeveloper. Optionally, click an item in the list to view its details in JDeveloper.

  5. Click Refactor to apply the new names shown in the Log window.

Click Refactor to apply the name changes shown in the Log window.

To refactor offline database column names for ADF business components:

  1. In the Application window, in the data model project expand the Offline Database Sources folder and select the database table that contains the column that you want to edit.

  2. In the Structure window, double-click the column name.

    You can also right-click the database object and choose Go to Declaration.

  3. In the overview editor for the offline database table, edit the column name and press Enter.

  4. In the Log window, review the business components that reference the column name.

    The Rename page of the Log window links the named items to editors in JDeveloper. Optionally, click an item in the list to view its details in JDeveloper.

  5. Click Refactor to apply the name changes shown in the Log window.

3.4.6 How to Display Related Business Components Using Diagrams

As the number of business components that your project defines increases, you may decide to refactor components to change the relationships that you originally created. To help you understand the relationship between components in the data model project, open any business component in the overview editor and click the Diagram tab. The relationship diagram in the editor identifies the component you are editing in bold text. Related components appear as link text that you can click to display the relationship diagram for the component identified by the link.

For example, Figure 3-9 displays the Diagram tab in the editor for the view object ProductVO. The diagram identifies the entity objects that ProductVO can access (for example, ProductEO), the view link that defines the view object's relationship to a related view object (for example, mousing over the link between ProductVO and ItemVO, displays the view link ItemProductIdFkLink), and the related view object (in this example, ItemVO) named by the view link. Each of these related components displays as a link that you can click to open the component in the Diagram tab for its editor. By clicking on related component links, you can use the diagrams to navigate the component relationships that your project defines.

Figure 3-9 Relationship Diagram Displays Main Object and All Related Components

Diagram tab in overview editor

Before you begin:

It may be helpful to have an understanding of JDeveloper support for modeling applications with UML class diagrams. For more information, see the "Developing Applications Using Modeling" chapter in Developing Applications with Oracle JDeveloper.

You will need to complete this task:

Create the business components in the data model project, as described in Section 3.3.1, "How to Create New Components Using Wizards."

To view relationship diagrams for the business components of the data model project:

  1. In the Applications window, right-click the business component that you want to view and choose Open.

  2. In the overview editor, click the Diagram tab to view the component you are editing and all of its related components in a relationship diagram.

    The relationship diagram identifies the component you are editing in bold text. Related components appear as link text that you can click to display the relationship diagram for the component identified by the link. By clicking on related component links, you can use the diagram to navigate the component relationships that your project defines.

3.4.7 What You May Need to Know About Using UML Diagrams

JDeveloper offers extensive UML diagramming support for ADF Business Components. You can drop components that you've already created onto a business components diagram to visualize them. You can also use the diagram to create and modify components. The diagrams are kept in sync with changes you make in the editors.

To create a new business components diagram, use the Business Components Diagram item in the ADF Business Components category of the JDeveloper New Gallery. This category is part of the Business Tier choices.

3.5 Customizing Business Components

When you need to add custom code to extend the base functionality of a component or to handle events, you must create a custom Java class for any of the key types of ADF Business Components you create, including application modules, entity objects, and view objects.

For example, you can add custom methods to the Java classes of the application module when you want to perform specific business logic. This includes, but is not limited to, code that:

  • Configures view object properties to query the correct data to display

  • Iterates over view object rows to return an aggregate calculation

  • Performs any kind of multistep procedural logic with one or more view objects

By centralizing these implementation details in your application module, you gain the following benefits:

  • You make the intent of your code more clear to clients.

  • You allow multiple client pages to easily call the same code if needed.

  • You simplify regression-testing of your complete business service functionality.

  • You keep the option open to improve your implementation without affecting clients.

  • You enable declarative invocation of logical business functionality in your pages.

3.5.1 How to Generate Business Component Java Subclasses

You can specify company-level subclasses for the entity objects, view objects, and application modules of the data model project. To enable this option so that new business components that you generate are based on these custom classes, you must create Java source files that extend the ADF Business Components implementation classes (in the oracle.jbo package) to which extended functionality may eventually be added. Doing this gives you the flexibility to later make changes to the base framework classes that can be picked up by their subclasses in your application. You can then choose ADF Business Components > Base Classes in the Project Properties dialog to specify the names of your subclasses.

You can further enable the generation of custom classes that you wish to generate for the business components for individual components. When you enable this option on the Java page of its respective overview editor, JDeveloper creates a Java source file for a custom class related to the component whose name follows a configurable naming standard. This class, whose name is recorded in the component's XML document, provides a place where you can write further custom Java code required by that component only. Once you've enabled a custom Java class for a component, you edit the class by expanding the component in the Applications window and double-clicking the Java class.

Alternatively, you can change the project-level settings that control how JDeveloper generates Java classes for each component type, choose Tools > Preferences and open the ADF Business Components page. The settings you choose will apply to all future business components that you create.

Best Practice:

Oracle recommends that developers getting started with ADF Business Components consider overriding the base framework classes to enable all generated custom Java classes to pick up customized behavior. This practice is preferred over creating custom classes for individual entity objects and view objects. You use the ADF Business Components > Base Classes page of the Project Properties dialog to specify the framework classes to override when you generate custom component.

Before you begin:

It may be helpful to have an understanding of working programmatically with business components. For more information, see these sections:

You will need to complete this task:

Create the business components in the data model project, as described in Section 3.3.1, "How to Create New Components Using Wizards."

To override framework business component classes with a custom class:

  1. In the Application window, double-click the component for which you want to create the custom class.

  2. In the overview editor for the component, select the Java navigation tab.

  3. On the Java page, click the Edit Java options icon.

  4. In the Select Java Options dialog, select generate Java class options to create the desired implementation classes:

    • Generate Application Module Class: generates the application module implementation class that may include custom methods to encapsulate functionality that is a logical aspect of the complete business service..

    • Generate Entity Object Class: generates the entity object implementation class that may include custom methods to act on representations of each row in the underlying database table.

    • Generate View Object Class: generates the view object implementation class that may include custom methods to act on a particular view object definition within the application module definition.

    • Generate View Row Class: generates the view row implementation class that may include custom methods to act on representations of a single row returned by the view object.

  5. Select the options to generate methods that will support your custom code.

    In the Select Java Options dialog, when you create these classes and select Include Accessors, JDeveloper generates accessors for all attributes defined by the business component. Because JDeveloper uses the attribute names in the accessor method names, these attribute names will be difficult to refactor and you should edit the generated class files to remove methods that your custom code will not use.

  6. Click OK.

  7. In the Applications window, expand the business component for which you created the class and double-click the componentNameImpl.java file.

  8. If you created an entity object class or a view row class, edit the file to remove generated accessor methods for attributes that you do not need to expose for your business use case.

    Tip:

    Edit the generated class files to remove generated code that is not used by any custom logic to improve overall performance.

3.5.2 How to Expose Business Component Methods to Clients

When you begin adding custom code to your ADF business components that you want clients to be able to call, you can "publish" that functionality to clients for any client-visible component. For each of your components that publishes at least one custom method to clients on its client interface, JDeveloper automatically maintains the related Java interface file. So, assuming you were working with an application module like SummitAppModule, you could have custom interfaces like:

  • Custom application module interface

    SummitAppModule extends ApplicationModule

  • Custom view object interface

    OrderItemsInfo extends ViewObject

  • Custom view row interface

    OrderItemsInfoRowClient extends Row

Client code can then cast one of the generic client interfaces to the more specific one that includes the selected set of client-accessible methods you've selected for your particular component.

Before you begin:

You may find it helpful to have an understanding of the methods of the ADF Business Component interfaces that you can override with custom code. For more information, see Appendix D, "Most Commonly Used ADF Business Components Methods."

You will need to complete this task:

Generate the implementation class for the application module or view object and add the custom methods that you want to expose to the client, as described in Section 3.5.1, "How to Generate Business Component Java Subclasses."

To expose client methods from the component implementation class:

  1. In the Application window, double-click the component for which you want to create the custom class.

  2. In the overview editor for the component, select the Java navigation tab.

  3. On the Java page, click the Edit client interface icon.

  4. In the Edit Client Interface dialog, select one or more desired methods from the Available list and click the Add button to shuttle them into the Selected list.

  5. Click OK.

3.5.3 What Happens When You Generate Custom Classes

When you select one or more custom Java classes to generate, JDeveloper creates the Java file(s) you've indicated. For example, assuming an application module named oracle.summit.model.service.SummitAppModule, the default names for its custom Java files will be SummitAppModuleImpl.java for the application module class and SummitAppModuleDefImpl.java for the application module definition class. Both files are created in the same ./oracle/summit/model/services directory as the component's XML document file.

Note:

The examples in this guide use default settings for generated names of custom component classes and interfaces. If you want to change these defaults for your own applications, use the ADF Business Components: Class Naming page of the JDeveloper Preferences dialog. Changes you make only affect newly created components.

The Java generation options for the business components continue to be reflected on subsequent visits to the Java page of the overview editor. Just as with the XML definition file, JDeveloper keeps the generated code in your custom Java classes up to date with any changes you make in the editor. If later you decide you do not require a custom Java file, disabling the relevant options on the Java page removes the corresponding custom Java files.

Figure 3-10 illustrates what occurs when you enable a custom Java class for the YourService application module. A YourServiceImpl.java source code file is created in the same source path directory as your component's XML document file. The YourServiceImpl.xml file is updated to reflect the fact that at runtime the component should use the com.yourcompany.yourapp.YourServiceImpl class instead of the base ApplicationModuleImpl class.

Figure 3-10 Component with Custom Java Class

Component with custom Java class

3.5.4 What You May Need to Know About Custom Interface Support

The Java interfaces of the oracle.jbo package provide a client-accessible API for your business service. Your client code works with interfaces like:

  • ApplicationModule, to work with the application module

  • ViewObject, to work with the view objects

  • Row, to work with the view rows

Only these components of the business service are visible to the client:

  • Application module, representing the service itself

  • View objects, representing the query components

  • View rows, representing each row in a given query component's results

This package intentionally does not contain an Entity interface, or any methods that would allow clients to directly work with entity objects. The entity objects in the business service implementation are intentionally not designed to be referenced directly by clients. Instead, clients work with the data queried by view objects as part of an application module's data model. Behind the scenes, the view object cooperates automatically with entity objects in the business services layer to coordinate validating and saving data that the end user changes. For more information about this runtime interaction, see Section 8.3.11, "What Happens at Runtime: How View Objects and Entity Objects Cooperate."

3.5.5 What You May Need to Know About Generic Versus Strongly Typed APIs

When working with application modules, view objects, and entity objects, you can choose to use a set of generic APIs or you can have JDeveloper generate code into a custom Java class to enable a strongly typed API for that component. For example, when working with an view object, if you wanted to access the value of an attribute in any row of its result, the generic API would look like this:

Row row = ordersVO.getCurrentRow();
Date shippedDate = (Date)row.getAttribute("OrderShippedDate");

Notice that using the generic APIs, you pass string names for parameters to the accessor, and you have to cast the return type to the expected type, as with Date shown in the example.

Alternatively, when you enable the strongly typed style of working you can write code like this:

OrdersRow row = (OrdersRow)ordersVO.getCurrentRow();
Date shippedDate = row.getOrderShippedDate();

In this case, you work with generated method names whose return type is known at compile time, instead of passing string names and having to cast the results. Typically, it is necessary to use strongly typed accessors when you need to invoke the methods from the business logic code without sacrificing compile-time safety. This can also be useful when you are writing custom validation logic in setter methods, although in this case, you may want to consider using Groovy expressions instead of generating entity and view row implementation classes for Business Components. Subsequent chapters explain how to enable this strongly typed style of working by generating Java classes for business logic that you choose to implement using Java.

3.5.6 How to Use Groovy Scripting Language With Business Components

Groovy is a scripting language with Java-like syntax for the Java platform. Groovy language expressions in ADF Business Components differs from the Java code that you might use in a Business Components custom Java class. The Groovy scripting language simplifies the authoring of code by employing dot-separated notation, yet still supporting syntax to manipulate collections, Strings, and JavaBeans. In Groovy expressions, type checking is done at runtime, whereas, in Java, type checking is done during compile time. Additionally, because Groovy expressions are dynamically compiled, they are stored in the XML definition files of the business components where you use it.

ADF Business Components supports the use of the Groovy scripting language in places where access to entity object and view object attributes is useful, including attribute validators (for entity objects), attribute default values (for either entity objects or view objects), transient attribute value calculations (for either entity objects or view objects), bind variable default values (in view object query statements and view criteria filters), and placeholders for error messages (in entity object validation rules). Additionally, ADF Business Components provides a limited set of built-in keywords that can be used in Groovy expressions.

Specifically, the ADF Business Components framework provides support for the use of Groovy language expressions to perform the following tasks:

To perform these tasks in JDeveloper, you use expression editor dialogs that are specific to the task. For example, when you want to create a default value for a transient view object attribute, you use the attribute's Edit Expression Editor dialog to enter an expression that determines a runtime value for the attribute. The same dialog also lets you specify when the value should be calculated (known as a recalculate condition), as shown in Figure 3-11.

Figure 3-11 Dialog to Edit Expression for Default Attribute Values

Expression editor for attribute value

Additionally, the overview editor that you use to edit entity objects and view objects displays the Business Rules page, where you can view and edit all expressions used by a single business component. For example, the Business Rules page that you display for a view object lets you view all expressions that the view object uses on its view accessors, bind variables, and attributes. You can filter the display to show only those items with Groovy expressions defined, as shown in Figure 3-12. Although expressions cannot be verified at design time, all expression editors let you test the syntax of the expression before you save it.

Figure 3-12 Overview Editor's Business Rules Page Shows All Expressions Used by a Business Component

Business Rules page for a view object

Before you begin:

It may be helpful to have an understanding of the Groovy language. For more information, refer to the following website:

You will need to complete this task:

Create the business components in the data model project, as described in Section 3.3.1, "How to Create New Components Using Wizards."

To display Groovy expressions for a business component:

  1. In the Application window, double-click the desired entity object or view object.

  2. In the overview editor, click the Business Rules navigation tab and select Show All Groovy Expressions from the Rules Filter icon.

3.5.7 What You May Need to Know About Referencing Business Components in Groovy Expressions

There is one top-level object named adf that allows you access to objects that the framework makes available to the Groovy script. When you reference an Oracle ADF object in a Groovy expression, the Oracle ADF runtime returns wrapper objects that do not correspond to the actual concrete type of the classes. These wrapper objects support all of the method and field types of the wrapped object. Your expressions can use wrapped objects as if they were the actual object. Note, however, any attempt to cast wrappered objects to its concrete type will fail with a ClassCastException. In general, when working with the Groovy language it is not necessary to use explicit casting, and in the case of these wrapped ADF Business Components objects, doing so will cause an exception.

The accessible Oracle ADF objects consist of the following:

  • adf.context - to reference the ADFContext object

  • adf.object - to reference the object on which the expression is being applied (which can also be referenced using the keyword object, without the adf prefix). Other accessible member names come from the context in which the Groovy script is applied.

    • Entity object attributes: The context is an instance of the entity implementation class. Through this object you can reference custom methods of the custom entity implementation class, any methods defined by the base implementation class as specified by the Javadoc for EntityImpl, and you can reference the attributes of the entity instance.

    • Entity object script validation rules: The context is the validator object (JboValidatorContext) merged with the entity on which the validator is applied. For details about keywords that you can use in this context, see Section 3.5.8.1, "Referencing Members of the Same Business Component."

    • View object attributes: The context is an instance of the view row implementation class. Through this object, you can reference custom methods of the custom view row implementation class, any methods defined by the base implementation class as specified by the Javadoc for ViewRowImpl, and you can reference the attributes of the view row instance as defined by the query row set. The

    • Bind variable in view object query statements: The context is the variable object itself not the view row. You can reference the structureDef property to access other information as well as the viewObject property to access the view object in which the bind variable participates. Note that access to view object attributes through the viewObject property is not supported.

    • Bind variable in view criteria: The context is the current view criteria row. The view criteria with bind variable may be used to create a query search form component in which a bind variable expression can provide the list of search criteria values. You must reference the structureDef property to access the view criteria row, and you can then reference the findAttributeDef() method to derive values from a specified attribute. You cannot use the viewObject property to access the view object on which the view criteria is defined.

    • Bind variable in view accessors: The context is the current view row. The view accessor with bind variable is used to create a cascading List of Value (LOV). The view accessor can derive Groovy-driven values from the current view row in the view accessor view object used to formulate the list of valid choices. You must reference the structureDef property to access the view row, and you can then reference the findAttributeDef() method to derive values from a specified attribute. You cannot use the viewObject property to access the view object for which the view accessor is defined.

    • Transient attributes: The context is the current entity or view row. You can reference attributes by name in the entity or view row in which the attribute appears, as well as public methods on that entity or view row. To access methods on the current object, you must use the object keyword to reference the current object (for example, object.methodName( )). The object keyword is equivalent to the this keyword in Java. Without it, in transient expressions, the method will be assumed to exist on the dynamically compiled Groovy script object itself.

  • adf.error - in validation rules, to access the error handler that allows the validation expression to generate exceptions or warnings

  • adf.userSession - returns a reference to the ADF Business Components user session (which you can use to reference values in the userData hashmap that is part of the session)

You can also reference the current date (time truncated) or current date and time using the following expressions:

  • adf.currentDate

  • adf.currentDateTime

3.5.8 What You May Need to Know About Referencing Custom Business Components Methods and Attributes in Groovy Expressions

Groovy script language simplifies the authoring of code that you might write to access methods and attributes of your entity object and view objects.

3.5.8.1 Referencing Members of the Same Business Component

The simplest example of referencing business component members, including methods and attributes that the entity object and view object define, is to reference attributes that exist in the same entity object or view object as the attribute that you apply the expression.

For example, you could define a Groovy expression to calculate the value of a transient attribute AnnualSalary on an entity object with an attribute Sal that specifies the employee's monthly salary:

Sal * 12

Or, with Groovy you can write a simple validation rule to compare the attributes of a single view object using syntax like:

PromotionDate > HireDate

Using Java, this same comparison would look like:

((Date)getAttribute("PromotionDate")).compareTo((Date)getAttribute("HireDate")) > 0

Note that the current object is passed in to the script as the this object, so you can reference an attribute in the current object by simply using the attribute name. For example, in an attribute-level or entity-level Script Expression validator, to refer to an attribute named "HireDate", the script can simply reference HireDate.

Similar to referencing attributes, when you define custom methods in an entity implementation class, you can invoke those methods as part of your expression. For example, to define an attribute default value:

adf.object.getDefaultSalaryForGrade()

A method reference requires the prefix adf.object which allows you to reference the same entity that defines the attribute on which the expression is applied. This same prefix also allows you to reference the methods of the base class of the entity implementation class (EntityImpl.java) that your custom implementation class extends.

Note that when you want to reference the method of an entity implementation class in a validation rule, you use the source prefix:

source.getDefaultSalaryForGrade()

Use of the source prefix is necessary in validators because the object keyword implies the validation rule object instead of the entity object (where the method is defined).

To allow you to reference members of the validator object (JboValidatorContext), you can use these keywords in your validation rule expression:

  • newValue: in an attribute-level validator, to access the attribute value being set

  • oldValue: in an attribute-level validator, to access the current value of the attribute being set

For example, you might use the following expression to specify a dynamic validation rule check of the salary for a salesman.

if (Job == "SALESMAN")
{
  return newValue < source.getMaxSalaryForGrade(Job)
}
else
return true

3.5.8.2 Referencing Members of Other Business Components

You can also reference the methods and attributes that entity objects and view objects defines in the expressions you apply to a different entity object attribute or validation rule. This is accomplished by referencing the accessor in the entity association.

For example, if you define an entity with a master-detail association for Dept and Emp, by default the accessor for the entity association will be named Dept and Emp, to identity the source and destination data source. Using that accessor in a Groovy expression to set the default value for a new employee's salary based on the location of their department:

adf.object.getDefaultSalaryForGrade(Dept.Loc)

This expression does not reference the entity even though it has the same name (Dept) as the accessor for the association. Instead, assuming a master-detail relationship between departments and employees, referencing the accessor allows the Groovy expression for the employee entity object to walk back to the master department entity and pass in the value of Loc from that master.

3.5.9 What You May Need to Know About Manipulating Business Component Attribute Values in Groovy Expressions

You can use the following built-in aggregate functions on Oracle Business Components RowSet objects:

  • rowSetAttr.sum(GroovyExpr)

  • rowSetAttr.count(GroovyExpr)

  • rowSetAttr.avg(GroovyExpr)

  • rowSetAttr.min(GroovyExpr)

  • rowSetAttr.max(GroovyExpr)

These aggregate functions accept a string-value argument that is interpreted as a Groovy expression that is evaluated in the context of each row in the row set as the aggregate is being computed. The Groovy expression must return a numeric value (or number domain).

For example, in a Dept entity object you could add a transient attribute that displays the sum of all employee salaries that is calculated by this expression:

EmployeesInDept.sum("Sal")

To reference the employees of a specific department, the expression supplies the name of the master-detail association's accessor for the destination Emp entity. In this case, the accessor is EmployeesInDept and salary is interpreted for each record of the Emp entity object.

Or, assume that you want the calculation of the salary total for specific departments to include each employee's benefits package, which varies with job role:

EmployeesInDept.sum("Sal + adf.object.getBenefitsValue(Job)")