3 Creating and Configuring EJB Data Controls

3.1.1 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

• Take advantage of ADF Model features to declaratively add query-by-example forms and list-of-value (LOV) components to pages

• Enable MDS customization on the application, which allows customers to customize an application without modifying the source code

3.1.2 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.

• ADF Model and data binding: When you create forms in an ADF web application, you use ADF Model and data binding. For more information, 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 more information, 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 more information, 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 more information, see "Developing with EJB and JPA Components"

3.2.1 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.

3.2.2 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, complex types, and primitives that are returned by any public method starting with get. 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 Section 2.2.4, "Data Control Built-in Operations" for the full list of those operations.

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

3.2.3 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.

3.2.4 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.

/** <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();
    }

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();
}
 

3.2.5 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 more information, see "How to Work with an EJB Business Services Layer" in Developing Applications with Oracle JDeveloper.

3.2.6 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 more information on the use of named criteria, see Section 7.6, "Filtering Result Sets with Named Criteria." For more information on paging, see Section 3.4, "Paginated Fetching of Data in EJB Data Controls."

3.2.7 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

3.2.8 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 more information, see Section 3.2.9, "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.

3.2.9 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:

1. 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).

2. 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.

3. In the overview editor for the persistence unit, select the Schema Generation page.

4. From the Generation Type dropdown list, select the type of schema generation that you want.

For more 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.

3.2.10 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:

1. In the Applications window, right-click the session bean and choose Edit Session Facade.

2. In the Specify Session Facade Options dialog, select any methods that you would like generated in the session bean.

3.2.11 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")

3.3.1 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 more information, see Section 3.3, "Exposing Session Bean Services with ADF Data Controls".

You may also find it helpful to understand the code patterns and constructs in your session bean that the data control uses. For more information, see Section 3.2, "Preparing a Session Bean to Use With a Data Control."

You need to complete this task:

To create an EJB data control:

1. In the Applications window, right-click the session bean for which you want to create a data control and choose Create Data Control.

2. 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 more information, see Section 3.3.11, "How to Create Different Data Controls for a Single Bean."

3. In the Choose Session EJB Business Interface page of the wizard, choose Local or Remote. For web applications, typically you would choose Local.

4. 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 more information, see Section 3.3.5, "What You May Need to Know About CRUD Operations in an EJB Data Control."

   • Failover. For more information, see Section 3.5, "Enabling Failover in an EJB Data Control."

5. 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 more information, see Section 3.4, "Paginated Fetching of Data in EJB Data Controls." The Support Named Criteria option must be selected for you to be able to select an access mode.

   • 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 more information, see Section 7.6, "Filtering Result Sets with Named Criteria."

     WARNING:

     If you deselect this option, built-in options for scrollable paging and range paging access modes are also turned off. For more information, see Section 3.3.4, "What You May Need to Know About the Support Named Criteria Option."

     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 more information, see Section 3.2.6, "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 more information, see Section 7.2.4, "What You May Need to Know About MDS Customization of Data Controls."

6. Click Finish.

3.3.2 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 more information, see Section 3.4, "Paginated Fetching of Data in EJB Data Controls."

  • EagerPersist, which determines whether new rows are added to the persistence context when created. For more information, see Section 3.3.8, "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 more information, see Chapter 7, "Adding Business Logic to Data Controls."

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

3.3.3 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.

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

The Support Named Criteria option that is offered when you create an EJB or JPA-based bean data control affects more than named criteria. In addition, selecting this option enables support for the scrollable and range paging access modes as described in Section 3.4, "Paginated Fetching of Data in EJB Data Controls." If you deselect this option, the data control is generated to use the oracle.adf.model.adapter.bean.BeanDCHandler handler class, which does not contain support for either the paginated or scrollable access modes.

3.3.5 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.

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 Section 4.6, "Enabling Custom CRUD Operations in a Bean Data Control."

3.3.6 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.

3.3.7 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.

3.3.8 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 more information, see Section 3.2.8, "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.

3.3.9 How to Change the EagerPersist Property

If your bean meets the conditions to work with eager persist behavior (as described in Section 3.3.8, "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:

1. In the Data Controls panel, right-click the data control's root node and choose Edit Definition.

2. In the ejb-definition Properties dialog, change the value of the EagerPersist property.

3.3.10 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.

3.3.11 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 more information, see Section 3.3, "Exposing Session Bean Services with ADF Data Controls".

You may also find it helpful to understand the code patterns and constructs in your session bean that the data control uses. For more information, see Section 3.2, "Preparing a Session Bean to Use With a Data Control."

You need to complete this task:

To create an additional data control instance for a bean:

1. Right-click the bean for which you want to create the additional data control instance and choose Create Data Control.

2. 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).

3. Complete the wizard with the options that you want for that instance of the data control.

3.3.12 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

3.4.1 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.

Before you begin:

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

You need to complete this task:

To change paging mode for a data control:

1. In the Data Controls panel, right-click the data control's node and choose Edit Definition.

2. In the ejb-definition Properties or the bean-definition Properties dialog, select rangePaging or scrollable from the AccessMode dropdown list.

3. 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.

3.4.2 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:

1. In the Applications window, select the page containing the component that is bound to the data control.

2. In the Structure window, select the component that is bound to the data control collection.

3. In the Properties window, expand the Behavior node, and set the rangeSize property to the desired value.

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

3.4.3 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 more information, see Section 3.2.4, "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 Section 4.4.1, "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 more information, see Section 4.4.2, "How to Implement a Custom Handler for Querying and Pagination."

3.4.4 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:

1. Open the class on which the data control is based. For EJB data controls, this is the remote or local interface, depending on which you specified in the wizard when creating the data control.

2. 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.

   Example 3-3 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();

3.4.5 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:

1. In the Applications window, double-click the DataControls.dcx file to open it in the overview editor.

2. In the overview editor, select the node for the data control that you want to edit.

3. In the Properties window, set the ImplementsSort property to true.