This appendix describes how common Oracle Forms tasks are implemented in Oracle ADF. In Oracle Forms, you do some tasks in the data block, and others in the UI. For this reason, the appendix is divided into two sections: tasks that relate to data, and tasks that relate to the UI.
This appendix includes the following sections:
ADF Business Components implements all of the data-centric aspects of Oracle Forms runtime functionality, but in a way that is independent of the user interface. Responsibilities between the querying and entity-related functions are cleanly separated, resulting in better reuse, as described in Table G-1.
|This concept||Maps to Oracle ADF||With these similarities|
Headless Form Module
The application module component is the "data portion" of the form. The application module is a smart data service containing a data model of master-detail-related queries that your client interface needs to work with. It also provides a transaction and database connection used by the components it contains. It can contain form-level procedures and functions, referred to as service methods, that are encapsulated within the service implementation. You can decide which of these procedures and functions should be private and which ones should be public.
Forms Record Manager
The entity object component implements the "validation and database changes" portion of the data block functionality. In the Forms runtime, this duty is performed by the record manager. The record manager is responsible for keeping track of which of the rows in the data block have changed, for firing the block-level and item-level validation triggers when appropriate, and for coordinating the saving of changes to the database. This is exactly what an entity object does for you. The entity object is a component that represents your business domain entity through an underlying database table. The entity object gives you a single place to encapsulate business logic related to validation, defaulting, and database modification behavior for that business object.
The view object component performs the "data retrieval" portion of the data block functionality. Each view object encapsulates a SQL query, and at runtime each one manages its own query result set. If you connect two or more view objects in master-detail relationships, that coordination is handled automatically. While defining a view object, you can link any of its query columns to underlying entity objects. By capturing this information, the view object and entity object can cooperate automatically for you at runtime to enforce your domain business logic, regardless of the "shape" of the business data required by the user's task.
In Oracle Forms, tasks that relate solely to data are performed in the data block. In Oracle ADF, these tasks are done on the business components that persist data (entity objects) and on the objects that query data (view objects).
In Oracle Forms, an editable table often has foreign key lookup columns to other tables. The user-friendly display values corresponding to the foreign key column values exist in related tables. You often need to present these related display values to the user.
In Oracle Forms, this was a complicated task that required adding nondatabase items to the data block, adding a block-level
POST-QUERY trigger to the data block, and writing a SQL select statement for each foreign key attribute. Additionally, if the user changed the data, you needed to sync the foreign key values with an item-level
WHEN-VALIDATE-ITEM trigger. This process is much easier in Oracle ADF.
Create a view object that includes the following:
The main, editable entity object as the primary entity usage
Secondary "reference" entity usages for the one or more associated entities whose underlying tables contain the display text
For more information, see Section 5.6.1, "How to Create Joins for Entity-Based View Objects."
Select the desired attributes (at least the display text) from the secondary entity usages as described in Section 5.6.3, "How to Select Additional Attributes from Reference Entity Usages."
At runtime, the data for the main entity and all related lookup display fields is retrieved from the database in a single join.
If the user can change the data, no additional steps are required. If the user changes the value of a foreign key attribute, the reference information is automatically retrieved for the new, related row in the associated table.
In Oracle Forms, when you wanted to get the current date and time, you retrieved the
sysdate from the database. In Oracle ADF, you also have the option of getting the system date using a Java method or a Groovy expression.
To get the system date from the database, you can use the following Groovy expression at the entity level:
DBTransaction reference is for entity-level Groovy expressions only.
If you want to assign a default value to an attribute using this Groovy expression, see Section 4.10.7, "How to Define a Default Value Using an Expression."
To get the system date from Java, you call the
getCurrentDate() method. For more information, see Section 12.10, "Accessing the Current Date and Time."
In Oracle Forms, you might have been concerned with read consistency, that is, the ability of the database to deliver the state of the data at the time the SQL statement was issued.
If you use an entity-based view object, the query sees the changes currently in progress by the current user's session in the pending transaction. This is the default behavior, and the most accurate.
If instead, you want a snapshot of the data on the database without considering the pending changes made by the current user, you can use a read-only view object and reexecute the query to see the latest committed database values. For more information on read-only view objects, see Section 5.8.1, "How to Create an Expert Mode View Object."
Calculated fields are often used to show the sum of two values, but they could also be used for the concatenated value of two or more fields, or the result of a method call.
Calculated attributes are usually not stored in the database, as their values can easily be obtained programmatically. Attributes that are used in the middle tier, but that are not stored in the database are called transient attributes. Transient attributes can be defined at the entity object level or the view object level.
If a transient attribute will be used by more than one view object that might be based on an entity object, then define the attribute at the entity object level. Otherwise, define the transient attribute at the view object level for a particular view object.
To define transient attributes at the entity object level, see Section 4.11, "Adding Transient and Calculated Attributes to an Entity Object." To define transient attributes at the view object level, see Section 5.4, "Adding Calculated and Transient Attributes to a View Object."
In Oracle Forms, you may be used to using mirrored items to show two or more fields that share identical values.
There is no need to have mirrored items in Oracle ADF, because the UI and data are separated. The same view object can appear on any number of pages, so you don't need to create mirrored items that have the same value. Likewise, a form could have the same field represented in more than one place and it would not have to be mirrored.
If you are used to working with standard database types, you may be wondering how to use the
BLOB types in Oracle ADF.
In Oracle ADF, use the built-in data types
BlobDomain. These are automatically created when you reverse-engineer entity objects or view objects from existing tables with these column types. ADF Business Components also supports data types for Intermedia column types:
OrdVideo. For more information, see Section 4.10.1, "How to Set Database and Java Data Types for an Entity Object Attribute."
In Oracle ADF, common UI-related tasks (such as master-detail screens, popup list of values, and page layout) are handled quite differently than they were in Oracle Forms.
Oracle Forms is based on an absolute pixel or point-based layout, as compared to the container-based approach of JSF, and the Layout Manager approach in ADF Swing.
See Developing Web User Interfaces with Oracle ADF Faces for information on how to lay out a page in Oracle ADF.
In Oracle Forms, stacked canvases were often used to hide and display areas of the screen.
The analog of stacked canvases in Oracle ADF is panels (layout containers) with the rendered property set to
false. See Developing Web User Interfaces with Oracle ADF Faces for more information.
Master-detail relationships in Oracle ADF are coordinated through a view link. A view link is conceptually similar to an Oracle Forms relation.
For information on how create view links, see Section 6.2, "Working with Multiple Tables in a Master-Detail Hierarchy." Once you have established a relationship between two view objects with a view link, see Section 6.2.4, "How to Enable Active Master-Detail Coordination in the Data Model."
In Oracle Forms, another common task was creating an enter query screen. That is, a screen that starts in Find mode.
In Oracle ADF, this accomplished with a search form. Complete information on how to create a search form is covered in Chapter 33, "Creating ADF Databound Search Forms." In particular, you may want to look at Section 33.3.1, "How to Set Search Form Properties on the View Criteria."
In Oracle Forms, you may be used to creating tables where you can edit and insert many records at the same time. This can be slightly more complicated when using a JSF page in Oracle ADF, because the operations to edit an existing record and to create a new record are not the same.
In Oracle ADF, this is done using an input table. To create an input table, see Section 29.4, "Creating an Input Table."
In Oracle Forms, it was simple to create a list of values (LOV) object and then associate that object with a field in a declarative manner. This LOV would display a popup window and provide the following capabilities:
Selection of modal values
Query area at the top of the LOV dialog
Display of multiple columns
Automatic reduction of LOV contents, possibly based on the contents of the field that launched the LOV
Automatic selection of the list value when only one value matches the value in the field when the LOV function is invoked
Validation of the field value based on the values cached by the LOV
Automatic popup of the LOV if the field contents are not valid
To implement a popup list in Oracle ADF, you configure one of the view object's attributes to be of LOV type, and select Input Text with List of Values as the style for its UI hint. For a description of how to do this, see Section 5.12, "Working with List of Values (LOV) in View Object Attributes."
In Oracle Forms, you could create a list of values (LOV) object and then associate that object with a field in a declarative manner. In Oracle ADF, you can implement an LOV (lookup-value) screen with a search item, usable for a lookup field with many possible values.
To implement a dropdown list in Oracle ADF, you configure one of the view object's attributes to be of LOV type, and select Input Text with List of Values as the style for its UI hint. For a description of how to do this, see Section 5.12, "Working with List of Values (LOV) in View Object Attributes."
In Oracle Forms, you could create a list of values (LOV) object and then associate that object with a field in a declarative manner. In Oracle ADF, you can implement a dropdown list with string values from a different table. These string values populate the field with an id code that is valid input in the table that the screen is based on.
To implement a dropdown list of this type in Oracle ADF, you configure one of the view object's attributes to be of LOV type, and select Choice List as the style for its UI hint. For a description of how to do this, see Section 5.12, "Working with List of Values (LOV) in View Object Attributes."
In Oracle ADF, you can lock a record in the database at the first moment it is obvious that the user is going to change a specific record.
Immediate row locking can be configured in ADF Business Components, although it is not the default and is typically not used in web application scenarios. For web applications, use the default configuration setting
jbo.locking.mode=optimistic. For more information, see Section 49.11.1, "How to Confirm That Applications Use Optimistic Locking."
When a record has been locked by a user, it's helpful to throw an error to let other users know that the record is not currently updatable.
Locking rows and throwing an exception if the row is already locked is built-in ADF Business Components functionality. There are a couple of different ways that you can handle the error message, depending on whether you want a static error message or a custom message with information about the current row.
To throw a static message, register a custom message bundle in your data model project to substitute the default
RowAlreadyLockedException's error message with something more meaningful or user-friendly.
To throw a message that contains information about the row, override the
lock() method on the entity object, using a try/catch block to catch the
RowAlreadyLocked exception. After you catch the exception, you can throw an error message that might contain more specific information about the current row.