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:
Section 3.2, "Creating the ADF Business Components Data Model Project"
Section 3.4, "Testing, Refactoring, and Visualizing 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.
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:
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
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
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
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
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
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.
For details about the Java EE design patterns that ADF Business Components implements, see Appendix E, "ADF Business Components Java EE Design Pattern Catalog."
For details about method calls of the ADF Business Components interfaces and classes, see Appendix D, "Most Commonly Used ADF Business Components Methods."
For details about common Oracle Forms tasks are implemented in Oracle ADF, see Appendix G, "Performing Common Oracle Forms Tasks in Oracle ADF."
For API documentation related to the oracle.jbo
package, see the following Javadoc reference document:
JDeveloper includes comprehensive design time support for ADF Business Components. Collectively, these facilities let you create, edit, diagram, test, and refactor the 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).
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:
In the main menu, choose File and then Application > New.
In the New Gallery, in the Items list, double-click ADF Fusion Web Application.
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.
Click Finish.
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.
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:
In the Applications window, select any existing project and in the main menu, choose File and then New > Project.
In the New Gallery, in the Items list, double-click ADF Model Project.
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.
Click Finish.
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."
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.
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:
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."
Obtain the connection credentials for the database that you will use as a data source for the business components you will create.
To initialize the data model project:
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.
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."
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.
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).
Click OK.
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.
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:
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."
Create the database connection for use when testing business components, as described in Section 3.2.3, "How to Initialize the Data Model Project With a Database Connection."
To change the data model project to work with an offline database:
In the Application window, right-click the data model project in which you want to create the offline database and choose Project Properties.
In the Project Properties dialog, select ADF Business Components.
On the ADF Business Components page, select Offline Database and click the Create a New Offline Database icon.
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.
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."
Click OK.
To create offline database definitions in the data model project:
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.
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.
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.
Click Finish.
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.
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 |
---|---|---|
|
|
Sequential integer assigned by a database trigger |
|
|
Oracle database ROWID |
|
|
Binary File (BFILE) object |
|
|
Binary Large Object (BLOB) |
|
|
Character Large Object (CLOB) |
|
|
Oracle Intermedia Image (ORDIMAGE) |
|
|
Oracle Intermedia Audio (ORDAUDIO) |
|
|
Oracle Intermedia Video (ORDVIDEO) |
|
|
Oracle Intermedia Document (ORDDOC) |
|
|
User-defined object type |
|
|
User-defined collection type (e.g. |
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 |
---|---|---|
|
|
Any numerical data. If you receive compiler or runtime errors related to "Number is an abstract class" it means you are using import oracle.jbo.domain.Number; |
|
|
Date with optional time |
|
|
Timestamp value |
|
|
Timestamp value with time zone information |
|
|
Timestamp value with local time zone information retrieved from JavaVM or from the ADF Context when configured in the application's <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. |
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.
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.
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:
To customize data model project properties:
In the Application window, right-click the project in which you want to create the shared application module and choose Project Properties.
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.
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."
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:
To customize ADF Business Components preferences:
In JDeveloper, choose Tools > Preferences.
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.
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.
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.
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:
To create collaborating business components in one pass:
In the Applications window, right-click the project in which you want to create the entity objects and choose New.
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."
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.
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.
On the Query-based View Objects page, select among the available database objects to create read-only view object definitions. Click Next.
On the Application Module page, leave the default selections unchanged, and click Next.
On the Diagram page, select Add to Business Components Diagram, and click Next.
On the Summary page, review the list of business components that the wizard will create, and click Finish
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.
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.
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:
To add individual business components to the data model project:
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.
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.
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-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.
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."
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
.
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
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."
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."
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.
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:
To edit properties of a business component in the data model project:
In the Applications window, right-click the business component that you want to edit and choose Open.
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.
In the overview editor, click the Source tab to view the changes in the XML definition source.
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.
In JDeveloper, choose File > Save to save the property changes to the business component XML definition file.
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.
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.
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.
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:
To test view instances in an application module configuration:
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.
To execute a view instance in the Oracle ADF Model Tester, expand the data model tree and double-click the desired view instance node.
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.
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.
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."
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.
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:
To find an item used by ADF business components:
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.
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.
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.
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.
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:
To refactor business components in the data model project:
In the Applications window, right-click the business component and choose Refactor > Rename or Refactor > Move.
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.
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.
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:
Create the business components in the data model project, as described in Section 3.3.1, "How to Create New Components Using Wizards."
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:
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.
In the main menu, choose Refactor > Rename.
You can also right-click the database object and choose Refactor > Rename.
In the Rename dialog, enter the new name and click Preview.
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.
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:
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.
In the Structure window, double-click the column name.
You can also right-click the database object and choose Go to Declaration.
In the overview editor for the offline database table, edit the column name and press Enter.
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.
Click Refactor to apply the name changes shown in the Log window.
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.
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:
To view relationship diagrams for the business components of the data model project:
In the Applications window, right-click the business component that you want to view and choose Open.
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.
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.
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.
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.
It may be helpful to have an understanding of working programmatically with business components. For more information, see these sections:
Section 13.10, "Working Programmatically with an Application Module's Client Interface"
Section 4.14, "Working Programmatically with Entity Objects and Associations"
Section 10.2, "Working Programmatically with Multiple Named View Criteria"
You will need to complete this task:
To override framework business component classes with a custom class:
In the Application window, double-click the component for which you want to create the custom class.
In the overview editor for the component, select the Java navigation tab.
On the Java page, click the Edit Java options icon.
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.
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.
Click OK.
In the Applications window, expand the business component for which you created the class and double-click the componentName
Impl.java
file.
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.
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.
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:
To expose client methods from the component implementation class:
In the Application window, double-click the component for which you want to create the custom class.
In the overview editor for the component, select the Java navigation tab.
On the Java page, click the Edit client interface icon.
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.
Click OK.
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.
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."
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.
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:
Define a Script Expression validator or Compare validator (see Section 11.5, "Using Groovy Expressions For Validation and Business Rules")
Define error message tokens for handling validation failure (see Section 11.7.4, "How to Embed a Groovy Expression in an Error Message")
Handle conditional execution of validators (see Section 11.7.3, "How to Conditionally Raise Error Messages Using Groovy")
Set the default value of a bind variable in the view object query statement (see Section 5.10, "Working with Bind Variables")
Set the default value of a bind variable that specifies a criteria item in the view criteria statement (see Section 5.9, "Working with Named View Criteria").
Define the default value and optional recalculate condition for an entity object attribute (see Section 4.10.6, "How to Define a Static Default Value")
Determine the value of a transient attribute of an entity object or view object (see Section 4.11, "Adding Transient and Calculated Attributes to an Entity Object" and Section 5.4, "Adding Calculated and Transient Attributes to a View Object")
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.
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
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:
To display Groovy expressions for a business component:
In the Application window, double-click the desired entity object or view object.
In the overview editor, click the Business Rules navigation tab and select Show All Groovy Expressions from the Rules Filter icon.
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
Groovy script language simplifies the authoring of code that you might write to access methods and attributes of your entity object and view objects.
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
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.
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)")