Creating and Configuring EJB Data Controls

3 Creating and Configuring EJB Data Controls

This chapter describes how to create data controls for EJB session beans and also includes information on paging and failover support.

This chapter includes the following sections:

About EJB Data Controls

You can create data controls for EJB session beans to simplify the creation of web application that rely on accessing data from a database. EJB session beans supports page ranging, simplified search criteria, and failover. With EJB session beans, you can create functional web pages.

Data controls are an abstraction provided by ADF Model than enable you to work with data and business services in a declarative manner and easily create UI components. For general information, see About ADF Model.

You can create data controls for EJB session beans to simplify the creation of web applications that rely on object model data, such as accessing data from a database. In addition to the features that are common for all adapter data controls (such as declarative UI hints and validation rules), EJB data controls have the following features built in:

Range paging in order to improve performance of queries to large data sets
Declarative named criteria to simplify creation of search-by-example forms
Transactional operations (based on transactional business methods in the session bean)
Failover support (based on failover methods that you implement)

EJB Data Control Use Cases and Examples

You can use EJB data controls to do the following kinds of things:

Create highly functional web pages that are bound to an EJB session facade, without manually writing any binding code.
Create an application that integrates existing EJB business services with ADF features such as ADF Model data binding, ADF Faces, and ADF task flows.
Take advantage of UI hints, validation rules, and other declarative metadata to provide consistent application of prompts, tooltips, format masks, and error messages throughout the application. For information on adding business logic to data controls, see Adding Business Logic to Data Controls .
Take advantage of ADF Model features to declaratively add query-by-example forms and list-of-value (LOV) components to pages. For information on creating LOV components, see Creating List of Values Objects.
Enable MDS customization on the application, which allows customers to customize an application without modifying the source code.

Additional Functionality for EJB Data Controls

You may find it helpful to understand other ADF and JDeveloper features before you implement your data controls. Following are links to other sections that may be useful.

General data control features: Before beginning work with EJB data controls, it is important to understand the broader data control concepts. For information on data controls, see Using ADF Data Controls.
ADF Model and data binding: When you create forms in an ADF web application, you use ADF Model and data binding. For information on the ADF model , see Using ADF Model in a Fusion Web Application in Developing Fusion Web Applications with Oracle Application Development Framework and Java API Reference for Oracle ADF Model.
ADF Faces: When you create databound UI components, they are likely to be from the ADF Faces component set. For information on databound web user interface, see Creating a Databound Web User Interface in Developing Fusion Web Applications with Oracle Application Development Framework.
ADF task flows: Task flows extend JSF page flows to provide a modular and transaction-aware approach to navigation and application control. For information on ADF task flows, see Creating ADF Task Flows in Developing Fusion Web Applications with Oracle Application Development Framework.
Java EE support in JDeveloper: JDeveloper provides support for creating Java EE components in a way that is optimized for use with EJB data controls. For information on EJB and JPA components, see Developing with EJB and JPA Components in Developing Applications with Oracle JDeveloper.

Preparing a Session Bean to Use With a Data Control

You can use JDeveloper’s wizard to create EJB entity classes and session beans that are optimized for use with data controls. When you create a data control based on EJB session bean, the data control exposes different types of objects, which you can bind to a variety of UI components.

An EJB data control encapsulates an EJB session bean and exposes the bean's code elements as data control objects, which can then be used to bind those code elements to UI components. When you create a data control based on an EJB session bean, the data control relies on coding patterns in the bean. This section shows the mapping between given code patterns and data control objects and shows patterns that you can use in your beans to maximize the data control features.

Note:

The data control does not replace the bean code. Rather, it serves as a thin adapter layer between the bean and the binding layer. The methods in your bean are used at runtime as you have coded them. Any declarative metadata that you specify in the data control, such as UI hints or validation rules, augments the session bean's business logic. Likewise, if you add or change methods after you have created the data control, the data control works with those new or revised methods.

Supported Types and Constructs in EJB Data Controls

EJB (and bean) data controls are compatible with classes that use the following Java types and constructs:

Java primitive types and arrays
Complex Java types, such as your own beans
Java scalar types, including types from the java.math, java.sql, and java.util packages
Collection types encompassed by the java.util.Collection, java.util.List, and java.util.Map packages
Generics, strongly-typed collections, and wildcards
Java Persistence API (JPA) features such as:
- @Id annotations to determine primary keys
- @NamedQuery annotations and the full range of JPQL syntax for named queries
- @JoinColumn annotations to denote master-detail and list-of-value (LOV) relationships.

EJB Data Control Objects

When you create a data control based on an EJB session bean (or a POJO bean), the data control exposes several different types of objects, each of which you can bind to a variety of UI components.

For EJB and bean data controls, data control objects are exposed for collections that are returned by any public method starting with get, as well as complex types and primitives that are returned by a collection or a get method. In these cases, the name of the data control object typically matches the name of the get method, but with the leading get removed from the name.

If a returned object has a relationship to another object defined through a JoinColumn annotation, then a child object is displayed in the Data Controls panel.

If the fields of a bean are exposed with public get methods, those fields are exposed as child attributes of the collection or structured attribute in the Data Controls panel. For get methods that return arrays and simple collections composed of primitives or strings, a child attribute node called element is exposed the Data Controls panel.

For methods that are not pre-pended with get, the methods are exposed as method objects in the Data Controls panel. Returns of these methods are exposed as method return objects.

In addition, built-in data control operations become available for many of those objects. See Data Control Built-in Operations for the full list of those operations.

Note:

EJB and bean data controls also expose bean constructors, which you can use to create buttons in the UI for creating new instances of the bean. This provides an alternative to using the data control's Create operation for creating instances. Buttons created from constructor nodes in the Data Controls enable the user to create a new object instance without adding that object to the persistence context (which typically happens during the Create operation). You can declaratively access that object instance by binding to the result property of the binding object for the constructor.

Table 3-1 shows how the various data control objects map to the elements of EJB classes. For information on using these objects, see Creating Databound UI Components from the Data Controls Panel.

Table 3-1 Important EJB and Bean Data Control Objects

Icon	Name	Description
	Collection	Is exposed for any public `get` method that returns a collection (any object implementing `java.util.Collection`). The children under a collection may be attributes of the collection, related collections, custom methods that return a value from the collection, or built-in operations that can be performed on the collection.
	Structured Attribute	Is exposed for any public `get` method that returns a complex Java type that is not a collection.
	Attribute	Is exposed for any public `get` method that returns a Java primitive or `String`, such as a column in an entity bean).
	Key Attribute	Is exposed for any attribute that is marked as the primary key (or which is part of a composite primary key). A key attribute can be designated with an `@Id` annotation in the entity bean class or in the data control structure file for a bean. For information on the key attribute, see Recommended Entity Bean Elements and How to Designate an Attribute as Primary Key.
	Method	Represents methods that are not pre-pended with `get`. These methods may return single values, structures, or collections.
	Method Return	Represents an object that is returned by a method or other operation. The returned object can be a single value or a collection. A method return appears as a child under the method that returns it. The objects that appear as children under a method return can be attributes of the collection, other methods that perform actions related to the parent collection, or operations that can be performed on the parent collection.
	Operation	Represents a built-in data control operation that performs actions on the parent object. Data control operations are located in an Operations node under collections or method returns, and also under the root data control node. The operations that are children of a particular collection or method return operate on those objects only, while operations under the data control node operate on all the objects in the data control. If an operation requires one or more parameters, they are listed in a Parameters node under the operation.
	Parameter	Represents a parameter value that is declared by the method or operation under which it appears. Parameters appear in the Parameters node under a method or operation.
	Named criteria	Represents a metadata-based query from which you can create a user search form. You can create custom view criteria and add them to the Data Controls panel. See Filtering Result Sets with Named Criteria.
	Constructor	Represents a constructor for one of the creatable types encompassed by a bean or EJB data control. You can use this data control object to create a command control that the user can click to create a new instance of that type.

About the Session Facade Pattern

EJB data controls are based on the EJB session facade design pattern, in which a session bean mediates access to individual entity beans, which contain the code to query database tables. When you create a data control based on a session bean, the data control exposes top-level objects based on the session bean's methods and lower level objects based on the detail in the entity beans that is retrieved by the session bean's accessor methods.

EJB Data Control Prerequisites and Considerations

In order to take advantage of the full functionality of EJB data controls, you need to include some elements in your classes that the data controls can use to present the structure of the services.

Your project should contain the following types of classes:

JPA entity classes for every database table that your application needs to query.
One or more session beans that contain accessor methods to the entity beans and other business methods. EJB data controls are based on sessions beans.
Optionally, (POJO) service facade classes that mirror the structure of the session beans. These service facade classes are useful for testing the services without having to run them in an application server container. You can also create data controls for service facade classes in order to test the services with the data control.

Recommended Entity Bean Elements

Your entity beans should contain the following elements:

@NamedQuery annotations containing queries that return each row of the collection. You can also take advantage of the constructs of the Java Persistence Query Language (JPQL) to add more selective queries. For information on JPQL, see http://docs.oracle.com/javaee/6/tutorial/doc/bnbtg.html.
@JoinColumn annotations for any columns that reference other tables (or other columns in the same table) by foreign key. The generated data control will then expose these joined columns as master-detail relationships and simplify the creation of UI components that rely on those relationships.
addEntityBeanName(CollectionType collectionParam) and removeEntityBeanName(CollectionType collectionParam) methods for each of the collections represented by the entity beans. The data control's Create and Delete operations rely on these methods to add and remove rows in a collection.
Primary keys designated for each entity bean. This is necessary for the Create operation to function properly when creating new rows at runtime.

You can designate primary key columns in entity beans by adding (or generating) @Id annotations for the appropriate columns.
A strategy for generating primary key values when creating new records. This is particularly important when you are using explicit commit models where you need to persist a new record upon its creation but before the user fills in the details for the other fields. For information on generating primary key values, see About Generating IDs for Primary Keys with the @GeneratedValue Annotation.

Recommended Session Facade Elements

It is recommended that your session beans (and/or Java service facade classes) contain the elements in the following list in order to integrate with data control features. If you use JDeveloper's wizards to create your classes, these elements are generated for you by default.

Getter methods that return the results of named queries specified in the entity beans. For example, the method shown in the following example would return the results of a named query called Customer.findById.
```
/** <code>select o from Customer o where o.id = :custId</code> */
public List<Customer> getCustomerFindById(BigDecimal custId) {
    if (custId != null) {
        Long custIdLong = new Long(String.valueOf(custId));
        return em.createNamedQuery("Customer.findById").setParameter("custId", custIdLong).getResultList();
    } else {
        return getCustomerFindAll();
    }
```
When you create a query that includes named parameters, the data control object that is created for that query includes the ExecuteWithParams built-in operation, which you can use to quickly create forms that are based on parameters that are supplied at runtime.

Tip:

If you have multiple named queries for an entity bean, you can create a getter method for each named query to create distinct data control collection objects for each query.
The queryByRange(String jpqlStmt, int firstResult, int maxResults) method, in order to take advantage of built-in support for JPA named queries, named criteria metadata, scrollable access mode, and range paging access mode. The data control will use this method to perform all named queries, instead of invoking the getter methods for the queries in the session bean.

The following example shows the code that is generated for the queryByRange(String jpqlStmt, int firstResult, int maxResults) method when you use JDeveloper to generate a session bean (or a plain Java facade using the Java Service Facade wizard).
```
public Object queryByRange(String jpqlStmt, int firstResult, int maxResults) {
    Query query = em.createQuery(jpqlStmt);
    if (firstResult > 0) {
        query = query.setFirstResult(firstResult);
    }
    if (maxResults > 0) {
        query = query.setMaxResults(maxResults);
    }
    return query.getResultList();
}
 
```
You can change the implementation of this method, but you need to keep the signature as is, since that's what the ADF Model runtime looks for.
(If your bean has transactional behavior), the following methods with these exact signatures:
- public boolean isTransactionDirty()
- public void rollbackTransaction()
- public void commitTransaction()
These methods are used to implement the data control's commit and rollback operations. When you use the JDeveloper wizards for creating Java service facade classes and EJB stateful container-managed session beans, working implementations of these three methods are generated in the classes by default.

What You May Need to Know About Overloaded Get Methods

When you create a session bean or service facade class to be consumed by a data control, the class should not use overloaded getXxx() methods (i.e. multiple versions of a method that have the same name but each of which takes different parameters). At runtime, the data control is unable to properly distinguish between the different versions of the method. To work around this constraint, rename any overloaded getXxx() methods you may have and give them names that are unique within their class.

Creating EJBs for a Data Control in JDeveloper

JDeveloper's wizards enable you to create EJB entity classes and session beans that are optimized for use with data controls. For information on working with an EJB business services layer, see How to Work with an EJB Business Services Layer in Developing Applications with Oracle JDeveloper.

What You May Need to Know About How EJB and Bean Data Controls Use Getter Methods

When you use the queryByRange(String jpqlStmt, int firstResult, int maxResults) in your session bean (and the data control uses the oracle.adf.model.adapter.bean.jpa.JPQLDataFilterHandler handler), the data control will use this method to perform all named queries, instead of invoking the getter methods for the queries in the session bean. If you have custom logic that you have added to the getter methods, it will not be called when the query is run. If you need that custom logic to run, you can incorporate it into the queryByRange(String jpqlStmt, int firstResult, int maxResults) method.

When you do not include the queryByRange(String jpqlStmt, int firstResult, int maxResults) in your session bean, the data control based on that bean is generated with the oracle.adf.model.adapter.bean.DataFilterHandler handler. In this case, the data control will invoke the session bean's getter methods directly, but you will not be able to use declarative named criteria on objects in the data control and you will need to manually implement methods for scrollable and range paging to work. For information on the use of named criteria, see Filtering Result Sets with Named Criteria. For information on paging, see Paginated Fetching of Data in EJB Data Controls.

About Commit Models for EJB Session Beans

EJB data controls can be used for different varieties of EJB session beans, whether they are bean-managed or container managed or whether they are stateful or stateless. JDeveloper's Create Session Bean wizard can generate code for the following types of session beans on which you can create a data control for updating data:

stateless container-managed transactions (CMT) with implicit commit
stateless bean-managed transactions (BMT) with implicit commit
stateful CMT with implicit commit
stateful BMT with implicit commit
stateful CMT with explicit commit
stateful BMT with explicit commit

Implicit Commit Models

For data controls based on any of the implicit commit variants, the transactional operations Commit and Rollback are not provided. For these beans, any use of the persistEntity or mergeEntity methods update the data in the underlying data source.

Explicit Commit Models

When you work with beans with an explicit commit model, the underlying data source is not updated until the Commit operation is called. This enables a user to create or make changes to multiple rows in multiple tables and then later commit them all to the data source with one click.

For data controls based on any of the explicit commit variants, you still might need to add steps to merge or persist changes to the persistence context before those changes can be committed. For example, you might need to have the user click buttons both to persist new rows and to commit the group of changes.

However, for some session beans, it is possible to configure the data control so that its Create operation automatically calls the entity's persist method when it is invoked. This is the default behavior for data controls for session beans created with JDeveloper's Create Session Bean wizard that are configured as stateful with container-managed transactions and an explicit commit model. For information on automatically persisting new rows, see About Automatically Persisting New Rows.

Where it is not possible to persist new rows immediately upon their creation, you can use a managed bean to override or combine operations and methods. For information on how to override declarative methods, see Overriding Declarative Methods in Developing Fusion Web Applications with Oracle Application Development Framework.

Also for many beans, and particularly for stateful CMT beans with explicit commit, you need to implement ID generation for the primary key columns. For information on generating IDs for primary keys values, see About Generating IDs for Primary Keys with the @GeneratedValue Annotation.

About Generating IDs for Primary Keys with the @GeneratedValue Annotation

In general it is convenient to let JPA auto-generate primary key values when you create a new instance of an entity. For many data models, you must generate values to populate the primary key columns of your tables to avoid constraint violation errors when the user tries to persist a new row. In JPA entity classes that use a simple primary key type (like Integer, long, String, etc.), you can use @GeneratedValue annotation for an entity's primary key column to designate how and from where the new record obtains that value. You then need to ensure that those values are generated by the database.

The Create Entities from Tables wizard in JDeveloper can help you configure your entities to have their primary key values automatically generated and assigned. This option is available to entities which use a simple primary key type, such as Integer, String, long, int, etc. When this option is enabled, the entity's primary key field is annotated with @GeneratedValue, which indicates how the key value should be generated. The wizard enables you to choose between the SequenceGenerator and TableGenerator strategies.

Once your classes have the @GeneratedValue annotation, you need to make sure that the values are generated by the database upon creation of a new row and passed to the entity. You can do this in one of the following ways:

Update the persistence unit for the entities to have the schema objects automatically created upon deployment by setting the eclipselink-ddl-generation property to create-tables or drop-and-create-tables. For information on changing a persistence unit’s schema generation behaviour, see How to Change a Persistence Unit's Schema Generation Behavior.
Manually update the online database schema to incorporate the ID generation objects specified in the @GeneratedValue annotations.

When you use the Create Entities from Tables wizard in JDeveloper, schema objects for any sequence or table generators are created and displayed under the Offline Database Sources node for the data model project in the Applications window. You can add the object to the online schema by right-clicking the node for the object, choosing Generate to > ConnectionName, and completing the ensuing Generate Database Objects from Database wizard.
If you already have ID generation objects in the live database schema, manually change the annotation attributes to refer to those objects. For example, for the @SequenceGenerator annotation, you would change the sequenceName attribute.

How to Change a Persistence Unit's Schema Generation Behavior

By default, when you use the Create Entities from Tables wizard to create entities, it creates a persistence unit with the eclipselink-ddl-generation property configured to use its default value (none). This means that EclipseLink, which is the default persistence provider for the generated entities, will not generate any Data Definition Language (DDL) statements or schema changes at runtime.

However, when you are developing the application, it might be useful to configure this property so that schema objects are created or re-created in the database schema each time that you test deploy the application. That will save you from having to manually keep the database schema in sync with incremental changes that you make as you develop the data model. For example, if you set the eclipselink-ddl-generation property to create-tables, EclipseLink will try to generate any schema objects that are specified by the entities and which do not yet exist in the schema, including sequences and tables for ID generation.

To change a persistence unit's schema generation behavior:

In the Applications window, expand the data model project and double-click the persistence unit file (which is located at Application Sources > META-INF > persistence.xml by default).
If there are multiple persistence units, in the overview editor for the persistence unit file, select the persistence unit for your project and click the Go to the Persistence Unit icon.
In the overview editor for the persistence unit, select the Schema Generation page.
From the Generation Type dropdown list, select the type of schema generation that you want.

For information on the eclipselink-ddl-generation options, see the EclipseLink documentation at http://www.eclipse.org/eclipselink/documentation/2.4/jpa/extensions/p_ddl_generation.htm.

WARNING:

Before deploying your finished application to a production environment, the database schema should be finalized, and you should change the eclipselink-ddl-generation property back to none.

How to Automatically Update a Session Facade

If you change an entity bean, you can use JDeveloper to quickly update the session bean and, if applicable, its remote and local interfaces. The Edit Session Facade wizard enables you to generate code in the session bean to expose named queries and methods that have been added to your entity classes. If you have a data control based on that session bean, any newly added methods become available to you in the Data Controls panel immediately after you refresh the panel.

To update a session facade based on updated entity beans:

In the Applications window, right-click the session bean and choose Edit Session Facade.
In the Specify Session Facade Options dialog, select any methods that you would like generated in the session bean.

What You May Need to Know About Refreshing JPA Queries

By default, when a JPA query is run, the results of the query are cached and that cache is used if the query is re-issued from the same session. Therefore, if a change occurs to the database from a second user's session after the first user's initial query, the first user might not see the changes made by the second user when re-running the query (e.g. when refreshing a page).

To make sure that a fresh JPA query is always run, you can use a hint on the query to refresh the cache.

In JPA 2.0, you can apply the following hint to the query:

setHint("javax.persistence.cache.storeMode", "REFRESH")

For the getCustomerFindAll() method, this would look like the following:

public List<Customer> getCustomerFindAll() {
    return em.createNamedQuery("Customer.findAll").                 
        setHint("javax.persistence.cache.storeMode", "REFRESH").
        getResultList();
}

In JPA 1.0, you can apply the following hint (assuming TopLink is your persistence provider):

setHint("eclipselink.refresh", "true")

Exposing Session Bean Services with ADF Data Controls

In Oracle ADF, when you create EJB data control, it eliminates the need to coordinate the model and view layers programmatically. The data control encapsulates the services and enables data binding between the layers. You can then create the UI components that are bound to the services through the data controls.

Once you have your application's services in place, you can use JDeveloper to create data controls that provide the information needed to declaratively bind UI components to those services.

In a standard Java EE application, you normally create entity beans that represent tables in a database and then create a session facade over all the EJBs. This facade provides a unified interface to the underlying entities. You then would typically use other classes to coordinate the interaction between the user interface and the services exposed by the session facade.

In an Oracle ADF application, you can eliminate the need to programmatically coordinate the model and view layers by creating a data control to encapsulate the services represented by the service facade and enable declarative data binding between the layers. You then create UI components that are declaratively bound to the services through the data control. The bindings take the form of EL expressions that reference the data control. Figure 3-1 illustrates the coordination between UI components and data control objects that is possible with declarative bindings.

Figure 3-1 Binding Between View and Service

Description of "Figure 3-1 Binding Between View and Service"

Data controls consist of one or more XML metadata files that define the capabilities of the services that the bindings can work with at runtime. The data controls work in conjunction with the underlying beans without changing the implementation of the beans.

For example, Figure 3-2 shows an EJB data model project in the Applications window. The project has a number of entity beans that represent database tables, such as the Customer bean, the Product bean, the Order bean, and so on. The project also contains a session bean, OrdersSessionEJBBean, which is used to access the beans created from tables. This session bean also contains service methods for persisting, merging, and removing records. There is a data control for the session bean, which allows developers to declaratively create UI pages based on the methods of the session bean and the entity beans that the session bean encapsulates. In addition, there are XML files in the persdef.model package that correspond with the Customer, Product, and Order beans that contain additional metadata such as UI hints and validation rules. These additional XML files are only needed if you are adding metadata for a given data collection.

Figure 3-2 EJB Model Project

This image is described in the surrounding text

How to Create EJB Data Controls

You create data controls from within the New Gallery or the Applications window.

Before you begin:

It may be helpful to have a general understanding of using EJB data controls. For information on exposing session bean services with ADF data controls, see Exposing Session Bean Services with ADF Data Controls.

You may also find it helpful to understand general data control features and functionality that you may need to use in the application with the data controls. For information on additional data control features, see Additional Functionality for EJB Data Controls.

In addition, you may find it helpful to understand the code patterns and constructs in your session bean that the data control uses. For information on preparing a session bean to be used with a data control, see Preparing a Session Bean to Use With a Data Control.

You also need to create an application workspace, JPA/EJB 3.0 entities, and one or more session beans for the entities. For information on working with an EJB business services layer, see How to Work with an EJB Business Services Layer in Developing Applications with Oracle JDeveloper.

To create an EJB data control:

In the Applications window, right-click the session bean for which you want to create a data control and choose Create Data Control.
In the Choose Session EJB page of the Create EJB Data Control wizard, specify a name for the data control instance.

Note:

You can create multiple data control instances with different behavior for the same bean. For information on creating different data controls for a single bean, see How to Create Different Data Controls for a Single Bean.
In the Choose Session EJB Business Interface page of the wizard, choose Local or Remote. For web applications, typically you would choose Local.
In the Choose ADF Data Controls Features page, select any of the following checkboxes for additional data control features that you would like to use in your application. (This page of the wizard only appears when you are creating the data control over a stateful session bean.)
Methods will be added to the session bean to implement the selected data control features.
- Transactions. Selecting this feature generates the commitTransaction(), rollbackTransaction(), and isTransactionDirty() methods in your session bean and maps them with the data control's commit and rollback operations. If you have used JDeveloper to create a stateful and container-managed session bean, these methods should already be implemented, in which case the Transactions checkbox would be selected by default.
- Custom CRUD. This feature enables you to provide your own implementation of persistence behavior. EJB data controls already have CRUD functionality from JPA, so you would only select this feature if you want to override JPA's functionality. For information on CRUD operations in an EJB data control, see What You May Need to Know About CRUD Operations in an EJB Data Control.
- Failover. For information on enabling failover in an EJB data control, see Enabling Failover in an EJB Data Control.
In the EJB Data Control Options page, select any additional options.
- Access Mode. Enables you to set how the data control fetches and stores data in memory. For information on access modes, see Paginated Fetching of Data in EJB Data Controls.
- Support Named Criteria. When selected, the data control includes built-in support for declarative named criteria, which can be used to create quick search forms. For information on named criteria, see Filtering Result Sets with Named Criteria.
  
  The Support Named Criteria option is only available for JPA-based beans that also contain a queryByRange() method. The data control uses the bean's queryByRange() method to handle all queries that otherwise would be carried out by individual getter methods on the bean. For information on getter methods, see What You May Need to Know About How EJB and Bean Data Controls Use Getter Methods.
- Generate Metadata. You can select this option to automatically generate metadata files for all of the beans represented by the data control upon the creation of the data control. This option is not necessary, since metadata files are created on demand when you edit a data control. However, this option might be useful if you plan to make the application available for MDS customization. For information on generating metadata, see What You May Need to Know About MDS Customization of Data Controls.
Click Finish.

Note:

If you later rename the bean on which a data control is based, you must again use the Create Data Control command in order to regenerate the data control's metadata. When doing so, you can keep the same data control instance name.

If you merely make changes to a bean after the data control is created, you do not have to regenerate the data control. The data control incorporates any changes made to the bean. However, you might need to close and reopen the project in order for the data control to incorporate the changes to the underlying beans.

What Happens in Your Project When You Create an EJB Data Control

When you create a data control based on an EJB session bean, JDeveloper does the following things:

Creates the data control definition file (DataControls.dcx) and opens the file in the overview editor.

Depending on the configuration of the bean on which the data control is based and the options that you have chosen in the wizard, various elements and properties are configured in the DataControls.dcx file and can be seen in its source view. These elements and properties include:
- <CreatableTypes>, which specifies the entities that are encompassed by the facade class and for which declarative metadata can be created.
- DataControlHandler, which specifies a handler class that implements various features for the data control, including support for paging and named criteria.
- AccessMode, which determines how the data control fetches data in the running application. For information on paginated fetching of data, see Paginated Fetching of Data in EJB Data Controls.
- EagerPersist, which determines whether new rows are added to the persistence context when created. For information on automatically persisting new rows, see About Automatically Persisting New Rows.
Displays the hierarchy of the resulting data control objects in the Data Controls panel.
If you have selected any features on the ADF Data Controls Features page, adds methods to implement those features to the session bean.
If you have selected Generate Metadata, generates XML data control structure files for the high-level data control objects. These files hold any declarative metadata, such as UI hints and validation rules, that you define for given data control objects. If you have not selected this option, the data control structure files are created on demand when you use the DataControls.dcx overview editor to add declarative metadata to data control objects. For information on adding business logic to data controls, see Adding Business Logic to Data Controls .

For general information on the overview editor and Data Controls panel, see What Happens in Your Project When You Create a Data Control. For information specific to EJB and bean data controls, see How EJB and Bean Data Controls Appear in the IDE.

How EJB and Bean Data Controls Appear in the IDE

Once you have created an EJB or bean data control, you can use the overview editor for the DataControls.dcx file to further configure the data control, and you can use the Data Controls panel to create databound UI components.

DataControls.dcx Overview Editor for EJB and Bean Data Controls

The overview editor for the DataControls.dcx file provides a view of the master-detail hierarchies of your data model as well as methods from the session facade. When you select a node, you can view the fields that can be mapped to database columns in the corresponding entity class in the Attributes tab. In the Accessors tab, you can view fields for the corresponding entity class that have entity relationships defined (such as OneToMany and ManyToOne). In the Operations tab for collections, you can view entity methods that the data control uses for standard operations, such as the add and remove methods of the collection accessors.

See Table 2-1 for a description of the icons that are used in the overview editor and Data Controls panel.

You can change the settings for a data control by selecting an element and clicking the Edit icon. For information on editing a data control, see Adding Business Logic to Data Controls .

Data Controls Panel for EJB and Bean Data Controls

The Data Controls panel serves as a palette, from which you can create databound UI components by dragging nodes from the Data Controls panel to the design editor for a web page. For information on the contents of the Data Controls panel, see Display of Business Services in the Data Controls Panel.

In addition for EJB and JPA-based bean data controls, nodes for named criteria appear, as shown in Table 2-1. Named criteria are used to create quick search forms. By default, an implicit named criteria called All Queriable Attributes appears for each queriable collection when you create the data control. You can create additional declarative named criteria for each collection as described in Filtering Result Sets with Named Criteria.

For information on creating databound UI components from a data control, see Creating Databound UI Components from the Data Controls Panel.

EJB and Bean Data Control Built-in Operations

EJB data controls also provide standard built-in data control operations that you can use to create command components in your user interface for page navigation and data operations.

For information on all of the operations available to data controls, see Data Control Built-in Operations.

What You May Need to Know About the Support Named Criteria Option and Paging

The Support Named Criteria option that is offered when you create an EJB or JPA-based bean data control affects the handler class that is used by the data control, which also affects features such as access mode.

If you select the Scrollable or Range Paging access mode when creating your data control, you should leave the Support Named Criteria option selected. Otherwise, the data control is generated to use the DataFilterHandler handler, which means that you would have to manually implement paging methods. (The JPQLDataFilterHandler, which is used if you select the Scrollable or Range Paging access mode and keep the Support Named Criteria option selected, implements the access mode for you without requiring further coding.)

For information on access modes in data controls, see Paginated Fetching of Data in EJB Data Controls.

What You May Need to Know About CRUD Operations in an EJB Data Control

When you create an EJB data control, CRUD (Create/Read/Update/Delete) features rely on the session bean's service methods and the entity beans encompassed by the session bean.

For example, a session bean's persist and merge methods are represented in the Data Controls panel and you can use them to create buttons that allow the user to persist and merge the current instance of the object.

There are also built-in data control operations available that you can use to bind data operations to the UI. These operations in turn call the appropriate methods in the session facade and entity classes. In addition, they may update the state of the ADF iterator. For example, when invoked, the Create operation for a data collection calls the constructor of the entity class that represents that collection to create the instance and then calls the appropriate persist method in the session bean to add the new instance to the JPA persistence context. Then the newly created instance is added to the ADF iterator.

Tip:

Where applicable, it is generally best to use these built-in operations, because they handle communication with both the JPA entity manager and the ADF iterators, keeping the two in sync.

You can also implement your own logic for CRUD (Create/Read/Update/Delete) operations if you do not wish to rely on JPA for these features. For more information on implementing custom CRUD operations, see Enabling Custom CRUD Operations in a Bean Data Control.

What You May Need to Know About the Merge and Persist Methods

If, when you created your session bean, you chose to expose merge and persist methods, then those methods appear in the Data Controls panel and you can use them to create buttons that allow the user to merge and persist the current instance of the object. Which you use depends on whether the page will need to interact with the instance once updates are made. If you want to be able to continue to work with the instance, then you need to use the persist method.

The merge methods are implementations of the JPA EntityManager.merge method. This method takes the current instance, copies it, and passes the copy to the PersistenceContext. It then returns a reference to that persisted entity and not to the original object. This means that any subsequent changes made to that instance will not be persisted unless the merge method is called again.

The persist methods are implementations of the JPA EntityManager.persist method. Like the merge method, this method passes the current instance to the PersistenceContext. However, the context continues to manage that instance so that any subsequent updates will be made to the instance in the context.

What You May Need to Know About Remove Methods

When you have a data control that is based on a session bean or a Java service facade that contains remove methods (to remove objects from the JPA persistence context), those methods are exposed in the Data Controls panel along with other facade methods. However, when deleting an entity from a form or table bound to an ADF iterator, you should generally use the Delete operation instead of a remove method. The Delete operation calls the remove method on the facade and also notifies the ADF iterator of the changes, ensuring that the iterator and the persistence context stay in sync. If you call the remove methods directly in order to take advantage of any custom behavior that you have coded within them, you also need to provide the code to refresh the ADF iterator.

About Automatically Persisting New Rows

For most variants of EJB (and JPA-based bean) data controls, the Create operation creates a new row and inserts it into the row set. However, it does not add the newly created object to the persistence context. That is generally the desired behavior for stateless and implicit-commit data models, since attempting to persist the instance immediately upon creating it may violate constraint violations due to mandatory fields being empty.

However, some models support the option of calling the persist method during the Create operation, because the underlying DML to persist the row is deferred until commit time. When the Create Session Bean wizard in JDeveloper is used to generate a stateful session bean using CMT and explicit commit behavior, it generates a model that supports this eager persist behavior. The advantage this model has in a conversational web application is that the application can combine these steps of create and persist into a single gesture (typically a button). After creating multiple instances, the user can click a commit button to apply all of the pending changes, at which point a transaction is begun and the DML statements are executed in the database to perform any pending INSERT, UPDATE or REMOVE operations.

When you create a data control for an EJB or a bean, the class is scanned to see if it is a candidate for this "eager persist" behavior. If so, the data control's EagerPersist property is set to true. You can override the initial value to enable or disable this option as you wish.

Calling an entity's persist method eagerly is generally desirable only when the following conditions are met:

The session bean has explicit commit behavior (since implicit commit behavior would mean that the object would be committed as soon as it was created).
The model does not attempt to execute SQL right away when the persist method is called.
You have set up ID generation for the primary key column. For information on generating IDs for primary key values, see About Generating IDs for Primary Keys with the @GeneratedValue Annotation.
The EJB session been is stateful and uses the following:
- container-managed transactions
- the @TransactionAttribute(TransactionAttributeType.NOT_SUPPORTED) annotation for the session bean class,
- the @TransactionAttribute(TransactionAttributeType.REQUIRED for the commit method

If you use JDeveloper's Create Session Bean wizard to create a stateful session bean with container-managed transactions and an explicit commit model, any data control that you create for this bean will be generated with the EagerPersist property set to true. Otherwise, EagerPersist is set to false.

How to Change the EagerPersist Property

If your bean meets the conditions to work with eager persist behavior (as described in About Automatically Persisting New Rows) but it is not turned on (which might be the case if you did not use the Create Entities from Tables wizard to create the entity classes), you can manually set the EagerPersist property to true. Likewise, if the property is set to true but you do not want eager persist behavior, you can change it to false.

To change the value of the EagerPersist property for a data control:

In the Data Controls panel, right-click the data control's root node and choose Edit Definition.
In the ejb-definition Properties dialog, change the value of the EagerPersist property.

What You May Need to Know About the Persistence Context and Resubmitting Queries

When you have a data control based on a stateful container-managed session bean, pre-commit changes made in a session are not reflected in any subsequent query that is made to the data source. So, if a user is in the middle of a transaction and performs an operation that requeries the data source, the subsequent refresh of the data on the page will not include changes made in the session.

How to Create Different Data Controls for a Single Bean

You can create multiple instances of a data control for a single bean, which can be useful if you need to make contrasting data control features available to the UI developer. For example, you may want to make it possible for a UI developer to create some UI components with scrollable paging and others with range paging.

Before you begin:

It may be helpful to have a general understanding of using EJB data controls. For information on EJB data controls, see Exposing Session Bean Services with ADF Data Controls.

You may also find it helpful to understand general data control features and functionality that you may need to use in the application with the data controls. For information on EJB’s additional functionality, see Additional Functionality for EJB Data Controls.

In addition, you may find it helpful to understand the code patterns and constructs in your session bean that the data control uses. For information on the code patterns in a session bean, see Preparing a Session Bean to Use With a Data Control.

You also need to create a data control as shown in How to Create EJB Data Controls.

To create an additional data control instance for a bean:

Right-click the bean for which you want to create the additional data control instance and choose Create Data Control.
In the Choose Session EJB page (or Choose Bean Class) page of the wizard, specify a unique name for the data control instance (different from any previous data control instances that you have created).
Complete the wizard with the options that you want for that instance of the data control.

What Happens When You Create an Additional Data Control Instance

When you create an additional data control instance for a bean, an additional high-level node appears in the overview editor for the DataControls.dcx file, as shown in Figure 3-3 and in the Data Controls panel.

Figure 3-3 Data Control Overview Editor with Two Data Control Instances

Description of "Figure 3-3 Data Control Overview Editor with Two Data Control Instances"

Note:

When you add declarative metadata such as UI hints and validators to a data control, the different data control instances for a bean use that same metadata. For information on adding declarative metadata, see Adding Business Logic to Data Controls .

Paginated Fetching of Data in EJB Data Controls

For EJB or bean data control, you can control how to fetch and store data from the database. You can also set the pagination to scrollable, range, or no pagination in the Data Controls panel.

When you create an EJB or bean data control, you can use the wizard's Access Mode dropdown list to determine how records are accessed from the database and whether to limit the number of records that are held in memory at a time.

In EJB and bean data controls, there are the following possibilities for fetching and storing data in memory:

Scrollable access mode.

If you accept the defaults when creating the data control, the data access mode is set to scrollable. This means that the data that your application needs to display is retrieved from the database as needed (in increments equal to the range size specified by the UI component's iterator) and stored in memory. Then, when the user scrolls forward through the application, additional rows are fetched as needed and stored in memory. All rows that have been fetched remain in memory.

For example, if the running application contains a table that displays rows 1 through 20 on a web page and the table's iterator has a range size of 25 (the default), the data control will fetch the first 25 rows. If the user scrolls down to display rows 477 through 496 of the result set, the data will be fetched in sets of 25 as the user scrolls until rows 26 through 500 are fetched. At that point, a total of 500 rows will be stored in memory.

This is the default mode for data controls using oracle.adf.model.adapter.bean.DataFilterHandler and oracle.adf.model.adapter.bean.jpa.JPQLDataFilterHandler. However, for data controls using oracle.adf.model.adapter.bean.DataFilterHandler, you still need to add paging methods to your data control to implement the access mode. For information on adding pagination manually in a data control, see How To Manually Implement Pagination Support in a Data Control.
Range paging access mode

To limit the amount of records that are fetched and stored in memory at a time, you can use the rangePaging access mode. As with scrollable mode, range paging mode allows your applications to fetch data in increments. The main difference in range paging mode is that only the most recently fetched increment is retained in memory. So, for example, if the accessor iterator's rangeSize attribute is set to 25, no more than 25 records will be held in memory at any given time.

In a range paging version of the scrollable example above, the data control would fetch rows 1 through 25 and hold them in memory in order to display rows 1 through 20. If the user scrolled down, the data control would fetch data in increments of 25 as the user was scrolling but release the previous 25 records from memory as it fetched a new range. By the time the user reached rows 477 through 496 as in the example above, only rows 476 through 500 would be in memory.

When scrolling to a position that displays data from multiple increments, only the data from the increment last fetched is held in memory.

You can set page ranging when creating the data control by selecting Range Paging in the Access Mode dropdown of the Create EJB Data Control wizard.

Note:

When you use range paging in a data control, the built-in navigation operation Last does not work on databound UI components created from that data control.
No pagination. When there is no pagination, all available data for a UI component is fetched.

You can configure the data control to not use any paging by selecting No Paging in the Access Mode dropdown of the Create EJB Data Control wizard.

You can also use annotations to turn off paging for specific collections. For information on turning off paging using annotations, see How to Specify Access Mode for Individual Objects in the Data Control.
Custom pagination. If the built-in pagination options do not suit your needs, you can implement your own pagination by implementing a custom handler class. For information on implementing custom pagination, see How to Implement a Custom Handler for Querying and Pagination.

For information on access mode and data control handlers, see What You May Need to Know About the Scrollable and Range Paging Modes.

How to Change Paging Mode for a Data Control

If you want to change the paging mode for a data control, you can do so in the Data Controls panel.

Note:

For data controls using the oracle.adf.model.adapter.bean.DataFilterHandler ororacle.adf.model.adapter.bean.jpa.JPQLDataFilterHandler handler, the default access mode is scrollable.

Before you begin:

It may be helpful to have a general understanding of access modes for EJB and bean data controls. For information on access modes, see Paginated Fetching of Data in EJB Data Controls.

You may also find it helpful to understand general data control features and functionality that you may need to use in the application with the data controls. For information on EJB data controls’ additional functionality, see Additional Functionality for EJB Data Controls.

You also need to create an EJB or bean data control. For information on creating EJB data controls, see How to Create EJB Data Controls.

To change paging mode for a data control:

In the Data Controls panel, right-click the data control's node and choose Edit Definition.
In the ejb-definition Properties or the bean-definition Properties dialog, select rangePaging or scrollable from the AccessMode dropdown list.
If you are changing the data control to use range paging, make sure that the data control's FactoryClass property is specified as oracle.adf.model.adapter.bean.BeanDCFactoryImpl.

You can access the FactoryClass property in the source editor for the DataControls.dcx file or in the Properties window that appears when you open DataControls.dcx in the source editor or overview editor.

How to Set Range Size for a Data Control that Uses Range Paging

When you set a data control's access mode to rangePaging, the data control determines the range size by reading the rangeSize property of the accessor iterator of each component that is bound to a collection in the data control.

To set the range size for a component:

In the Applications window, select the page containing the component that is bound to the data control.
In the Structure window, select the component that is bound to the data control collection.
In the Properties window, expand the Behavior node, and set the rangeSize property to the desired value.

For information on iterator bindings, see Iterator Bindings Created in the Page Definition File in Developing Fusion Web Applications with Oracle Application Development Framework.

What You May Need to Know About the Scrollable and Range Paging Modes

Data controls that support scrollable and range paging modes rely on methods in the bean class to implement that functionality. The method that the data control uses depends on the data control handler class that the data control uses.

For JPA-based data controls, typically the JPQLDataFilterHandler handler is specified. JPQLDataFilterHandler relies on the presence of JPA queries and a queryByRange() method in the bean. For information on controlling EJB data control prerequisites and considerations, see EJB Data Control Prerequisites and Considerations.

For non-JPA bean data controls (and for EJB and JPA-based bean data controls that do not have a queryByRange() method), DataFilterHandler is specified. To implement range paging in data controls that use this handler, you need to add code to your bean class as shown in How To Manually Implement Pagination Support in a Data Control.

For data controls that do not have either of these handler classes (such as EJB data controls where you have explicitly turned off named criteria support), there is no built-in support for scrollable or range paging. However, you can write your own handler class to implement paging support. For information on implementing a custom handler for querying and pagination, see How to Implement a Custom Handler for Querying and Pagination.

How to Specify Access Mode for Individual Objects in the Data Control

If your data control encompasses multiple collections of different sizes, you may wish to set different access modes for some of the collections. You can do so by placing annotations on the accessor methods in the bean that the data control represents.

For the methods on which the annotations are used, the annotations override the access mode set for the data control. If an accessor method does not have such an annotation, it inherits its access mode from the one that is defined for the data control.

To specify access mode for individual objects in a bean or EJB data control:

Open the class on which the data control is based.
Add annotations for the methods for which you want a different access mode than that generally specified for the data control.

Note:

These annotations only work on getter methods.

The following example shows the necessary import statements and the available annotations and how they can be used on a collection.

import oracle.adf.model.adapter.bean.annotation.AccessMode;
import oracle.adf.model.adapter.bean.annotation.AccessModeType;

...
   * List with scrollable access
   */  
  @AccessMode(type=AccessModeType.SCROLLABLE)
  public List<Employees> getEmployeesScrollable() {
 ...
   * List with range paging.
   */  
  @AccessMode(type=AccessModeType.RANGE_PAGING)
  public List<Employees> getEmployeesRangePaging() {
 ...
   * List with no paging.
   */  
  @AccessMode(type=AccessModeType.NO_PAGING)
  public List<Employees> getEmployeesNoPaging() {
...

Note:

You must place the annotation on the class that is specified by the Definition attribute of the AdapterDataControl element in the DataControls.dcx file. By default, this is the bean implementation class.

In the 12.1.2 release of Oracle ADF, the Definition attribute was set to a session bean's business interface (remote or local) by default, meaning that the annotations needed to be placed on the business interface instead of the bean implementation class. If you would like to retain that behavior in this release, you can change the value of the Definition attribute so that it points to the business interface.

What You May Need to Know About Sorting Tables Based on Range Paginated Collections

By default, if a user sorts a table that is bound to a JPA-based data control, the ADF Model runtime forces the iterator to return all rows into memory for sorting, even if the back-end JPQL queries have already done the sort at the database level, which can cause memory problems if collection is too large. If you are using range paging for a collection, you can disable the ADF Model runtime full in-memory sort and have the data control handle it instead, based on just the currently selected range.

To use the data control to handle the sort for range paginated collections:

In the Applications window, double-click the DataControls.dcx file to open it in the overview editor.
In the overview editor, select the node for the data control that you want to edit.
In the Properties window, set the ImplementsSort property to true.

Providing UI Hints for Attributes Using Annotations

You can use Java annotations to provide defaults for how the attributes are displayed in the UI components. These UI hints are then used by the UI components to display the information to the user.

After you create a data control for an EJB session bean or a JavaBeans component, you can use Java annotations to create declarative metadata for data object attributes to provide defaults for how the attributes are displayed in UI components. These UI hints can then be used by UI components to automatically display the queried information to the user in a consistent, locale-sensitive way. For example, you can use UI hints to provide defaults for label and tooltip text when a UI component is created from the data control attribute corresponding to the field returned by that getter.

In web pages, a UI developer may access UI hint values by entering EL expressions utility methods defined on the bindings name space and specified for ADF binding instance names. When you use the Data Controls panel to create UI components based on attributes that are annotated with these UI hints, the EL expressions for accessing the hints are generated in the UI component code. For information on the syntax for these EL expressions, see How to Access UI Hints Using EL Expressions in Developing Fusion Web Applications with Oracle Application Development Framework.

Using annotations, you can set the following UI hints:

label - the component's label.
tooltip - the component's tooltip.
display - whether or not to display the attribute in forms and tables for the collection the UI. If the attribute is set to false, the attribute does not appear among the collection's attributes in the Data Controls panel.
width - component width, in pixels.
height - component height, in pixels.
autoSubmit - whether or not the component will automatically submit when an appropriate action takes place (a click, text change, etc.).
controlType - the control type the client UI will use to display the attribute. The default value for this hint is ControlHintType.DEFAULT, which is interpreted by the client to select the most appropriate component depending on the Java type of the attribute. You can keep this default value for Java-typed attributes. (Other possible values for this hint are only relevant if the attribute is based on a non-Java type.)
formatType - a class that defines the kind of formatting that will be applied to the attribute (such as date, currency, or percentage).
format - a format mask to determine specifically how a numeric or date value is displayed. For example, for a date, it could specify dd/MM/YYYY to indicate that the date is shown with day of the month first, month second, and year last and that each part is delimited by a slash (/).
timezoneId - for attributes of type Date, can be used to specify a fixed time zone to be used. If this UI hint is not set, the time zone is determined by the user's browser (or other client that displays the UI).

The UI hints that you can set through annotations comprise a subset of the metadata that you can set on data controls declaratively using XML data control structure files. Using data control structure files, you can also set declarative validation rules, the default value for the attribute, and other metadata that for the object as a whole. For information on all of the ways you can configure a data control through data control structure files, see Adding Business Logic to Data Controls .

Note:

If you set UI hints for an attribute both using annotations and in an XML data control structure file, the settings in the data control structure file take precedence.

There are three high-level annotations for providing UI hints for bean classes:

oracle.adf.model.adapter.bean.annotation.AttributeHint - enables you to specify default label, tooltip, height, and width for the field. In addition, you can specify whether the attribute is displayed or hidden, whether the field is submitted automatically when a user completes entry, and what type of component should be generated for the field.
oracle.adf.model.adapter.bean.annotation.DateFormatter - enables you to specify a format mask and a time zone for a Date attribute. You can use the format element to set a format mask, such as MM/dd/YYYY See the API documentation for the java.text.SimpleDateFormat at http://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html for information on the syntax for the date and time pattern strings that you can use for the format mask.
oracle.adf.model.adapter.bean.annotation.Formatter - enables you to specify the formatting for other numeric types such as oracle.jbo.format.DefaultCurrencyFormatter and oracle.jbo.format.PercentageFormatter.

In addition, there are the following support classes that enumerate possible values for the above annotations and which might need to be imported into your class when using the above annotations.

oracle.adf.model.adapter.bean.annotation.ControlHintType - provides a list of component types that you can reference from the AttributeHint annotation's controlType element.
oracle.adf.model.adapter.bean.annotation.FormatterType - provides a list of formatter types that are referenced by the DateFormatter and Formatter annotations.
oracle.adf.model.adapter.bean.annotation.TimeZoneID - provides a list of time zones that you can reference from the DateFormatter annotation.

Note:

When adding annotations for attribute hints to a method, you can press use JDeveloper's completion insight feature to help fill in the values. If the completion insight popup does not open automatically as you are typing, press Ctrl-Space.

The following code shows an example of how you might use UI hint annotations on a getter method in an entity bean class. Note that the annotations become available only after you generate the data control or after you add the ADF Model Generic Runtime library to the EJB project.

import oracle.adf.model.adapter.bean.annotation.AttributeHint;
import oracle.adf.model.adapter.bean.annotation.ControlHintType;
import oracle.adf.model.adapter.bean.annotation.DateFormatter;
import oracle.adf.model.adapter.bean.annotation.FormatterType;
import oracle.adf.model.adapter.bean.annotation.TimeZoneID
...
    @AttributeHint (
        label = "Hire Date",
        tooltip = "Type date in the form MM/dd/YYYY",
        display = true,
        controlType = ControlHintType.DEFAULT,
        width = 40,
        height = 20,
        autoSubmit = true)
    @DateFormatter (
        type = FormatterType.SIMPLE_DATE,
        format = "MM/dd/YYYY",
        formatter = "",
        timezoneId = TimeZoneID.DEFAULT)
    public Date getHireDate() {
        return hireDate;
    }

Note:

The formatter element of the @Formatter and @DateFormatter annotations is an advanced option that enables you to specify a separate handler class for providing the date or number format. For example, you could use this element to provide a handler that extends oracle.jbo.format.DefaultDateFormatter.

The following example shows how you might use the @Formatter annotation to specify that an attribute be displayed with currency formatting.

import oracle.model.adapter.bean.annotation.Formatter;
import oracle.model.adapter.bean.annotation.FormatterType;
...
    @Formatter (type = FormatterType.CURRENCY)
    public Integer getMinSalary() {
        return minSalary;
    }

The following formatters can be assigned through the @Formatter type element.

BIGDECIMAL - type defined by oracle.jbo.format.DefaultBigDecimalFormatter

CURRENCY type defined by oracle.jbo.format.DefaultCurrencyFormatter

DATE - oracle.jbo.format.DefaultDateFormatter

PERCENTAGE - type defined by oracle.jbo.format.PercentageFormatter

NUMBER - type defined by oracle.jbo.format.DefaultNumberFormatter

Note:

When you apply annotations for UI hints, you can not see the affect of the hints in the design-time view of pages that you create based on the data controls. However, you can test and verify the hints using the ADF Model Tester. For information on using the tester, see Testing Data Object Metadata Using the Oracle ADF Model Tester.

Enabling Failover in an EJB Data Control

You can configure EJB data controls to manage their state by ADF runtime, which is useful in a high availability or cluster environment. You can add the failover methods that EJB and bean data control supports to your bean class either manually or by using the data control wizard.

You can configure EJB data controls that are based on stateful session beans to have their state managed by the ADF Model runtime and enable failover of the objects encapsulated by the data control. Failover support for EJB data controls works in the same way as it does for bean data controls.

For information on generating method stubs in the session bean for this failover support, see How to Create EJB Data Controls. For information on implementing those methods, see Enabling Failover in a Bean Data Control.