Most Commonly Used Methods in ADF Business Components

Abstract

This paper provides a high-level description of the key ADF Business Components classes in the Oracle Application Development Framework, summarizing the methods that ADF developers write, call, and override most frequently.

Contents

Overview

Service-oriented J2EE Applications built using the ADF framework encapsulate their business logic into one or more business services. Clients access these business services either as web services or, when the client is a user interface, using the ADF data-binding layer that implements the Data Controls and Bindings from JSR-227. The data controls abstract the back-end business service implementations and binding objects link front-end user interface controls in a declarative way to back-end data.

ADF supports business services implemented as simple Java objects, web services, EJB Session beans, and framework-based Java objects that inherit built-in functionality from the ADF Business Components base classes. These ADF Business Components are business-tier building-block classes, and related design-time extensions to JDeveloper, that give you a prescriptive architecture for building richly-functional and cleanly layered J2EE business services with great performance. This paper offers a high-level description of the key components that comprise ADF Business Components, and provides a summary of the methods that developers leveraging ADF BC base classes write, call, and override most frequently while building their J2EE-compliant business services.

Logical Architecture of Services Built with ADF Business Components

You can use business services you build with ADF Business Components in one of three ways:

1. As lightweight local Java service classes,
2. As EJB session beans, or
3. As stateless web services

In all three cases, there is a clean separation between the client tier code that invokes the service and the business service tier where the service's implementation details reside.

With the J2EE web service option, your web service client interacts with the service using a web service proxy class generated by the client tool environment based on the service's WSDL service description. The methods that appear on your web service are the custom methods you've written on your business service component.

With the local Java service class and the EJB session bean options, your Java client code interacts with either the base ADF component interfaces or custom component interfaces that JDeveloper 10g generates for you automatically after indicating which custom methods should appear on the component's client interface.

Since ADF adopts this best-practice approach of having your client work with interfaces instead of directly with implementation classes, it offers the additional benefit of allowing you to change between deploying your business service as a local Java class or an EJB session bean without changing your client code. Along with the custom service interface, JDeveloper generates appropriate client-side proxy implementation classes that implement your custom interface. As such, it's an implementation detail you don't need to worry about yourself. With either 2-tier or 3-tier deployment of your application modules, thing just work...which is nice.

Figure 1 shows the relationships between the key components in the Oracle Application Development Framework. The dashed vertical line in the diagram represents the clean separation of component interfaces that are available on the client, and which ones are only available in the business tier implementation.

Figure 1: Relationship Between Key ADF Business Components Classes

Whenever you deploy an ADF Business Components project using a Business Components deployment profile in JDeveloper 10g, two separate JAR files get created, further emphasizing this logical separation between business tier and client tier:

• YourProjectNameCSMT.jar

  This archive contains all of the implementation classes that comprise your project's business service application module components and other ADF BC components that your application modules use. We picked the MT suffix in the name to represent Middle Tier. When deploying your application module as an EJB Session Bean, this JAR file lives on the EJB middle tier. It never is downloaded to the remote client.

• YourProjectNameCSCommon.jar

  This archive contains any custom client interfaces, generated custom remote client proxy classes, custom domains, and message bundles that are accessible by both the client-tier and the business service tier. We picked the suffix Common in the archive name to remind you that this jar is common to both tiers. This file is generally relatively quite small compared to the middle-tier JAR.

The following sections briefly explain each component and give tips about the methods J2EE developers using ADF Business Components will use most frequently for each kind of component.

Most Commonly Used Methods in the Client Tier

All of the interfaces described in this section are designed for use by client-layer code and are part of the oracle.jbo.* package.

ApplicationModule Interface

The ApplicationModule is a business service component that acts as a transactional container for other ADF components and coordinates with them to implement a number of J2EE design patterns important to business application developers. These design pattern implementations enable your client code to work easily with updateable collections of value objects, based on fast-lane reader SQL queries that retrieve only the data needed by the client, in the way the client wants to view it. Changes made to these value objects are automatically coordinated with your persistent business domain objects in the business service tier to enforce business rules consistently and save changes back to the database.

In addition to generic ApplicationModule access, JDeveloper 10g can generate you a custom YourApplicationModuleName interface containing service-level custom methods that you've chosen to expose to the client. You do this by visiting the Client Interface tab of the Application Module editor, and shuttling the methods you'd like to appear in your client interface into the Selected list. JDeveloper will also generate an appropriate YourApplicationModuleNameClient client proxy implementation class that is used automatically by your remote client in the case that you deploy your application module as an EJB Session Bean or whenever you use your application module in Batch Mode.

Transaction Interface

The Transaction interface exposes methods allowing the client to manage pending changes in the current transaction.

ViewObject Interface

A ViewObject encapsulates a database query and simplifies working with the RowSet of results it produces. You use view objects to project, filter, join, or sort business data using SQL from one or more tables into exactly the format that the user should see it on the page or panel. You can create "master/detail" hierarchies of any level of depth or complexity by connecting view objects together using view links. View objects can produce read-only query results, or by associating them with one ore more entity objects at design time, can be fully updateable. Updateable view objects can support insertion, modification, and deletion of rows in the result collection, with automatic delegation to the correct business domain objects.

Every ViewObject aggregates a "default rowset" for simplifying the 90% of use cases where you work with a single RowSet of results for the ViewObject's query. A ViewObject implements all the methods on the RowSet interface by delegating them to this default RowSet. That means you can invoke any RowSet methods on any ViewObject as well.

Every ViewObject implements the StructureDef interface to provide information about the number and types of attributes in a row of its rowsets. So you can call StructureDef methods right on any view object.

In addition to generic ViewObject access, JDeveloper 10g can generate you a custom YourViewObjectName interface containing view-object level custom methods that you've chosen to expose to the client. You do this by visiting the Client Interface tab of the View Object editor, and shuttling the methods you'd like to appear in your client interface into the Selected list. JDeveloper will also generate an appropriate YourViewObjectNameClient client proxy implementation class that is used automatically by your remote client in the case that you deploy your application module as an EJB Session Bean or whenever you use your application module in Batch Mode.

RowSet Interface

A RowSet is a set of rows, typically produced by executing a ViewObject's query.

Every RowSet aggregates a "default rowset iterator" for simplifying the 90% of use cases where you only need a single iterator over the rowset. A RowSet implements all the methods on the RowSetIterator interface by delegating them to this default RowSetIterator. This means you can invoke any RowSetIterator method on any RowSet (or ViewObject, since it implements RowSet as well for its default RowSet).

RowSetIterator Interface

A RowSetIterator is an iterator over the rows in a RowSet. By default it allows you to iterate both forward and backward through the rows.

Row Interface

A Row is generic value object. It contains attributes appropriate in name and Java type for the ViewObject that it's related to.

In addition to generic Row access, JDeveloper 10g can generate you a custom YourViewObjectNameRow interface containing your type-safe attribute getter and setter methods, as well as any desired row-level custom methods that you've chosen to expose to the client. You do this by visiting the Client Row Interface tab of the View Object editor, and shuttling the methods you'd like to appear in your client interface into the Selected list. JDeveloper will also generate an appropriate YourViewObjectNameRowClient client proxy implementation class that is used automatically by your remote client in the case that you deploy your application module as an EJB Session Bean or whenever you use your application module in Batch Mode.

StructureDef Interface

A StructureDef is an interface that provides access to runtime metadata about the structure of a Row.

In addition, for convenience every ViewObject implements the StructureDef interface as well, providing access to metadata about the attributes in the resulting view rows that its query will produce.

AttributeDef Interface

An AttributeDef provides attribute definition information for any attribute of a View Object row or Entity Object instance like attribute name, Java type, and SQL type. It also provides access to custom attribute-specific metadata properties that can be inspected by generic code you write, as well as UI hints that can assist in rendering an appropriate user interface display for the attribute and its value.

AttributeHints Interface

The AttributeHints interface related to an attribute exposes UI hint information that attribute that you can use to render an appropriate user interface display for the attribute and its value.

Most Commonly Used Methods In the Business Service Tier

The implementation classes corresponding to the oracle.jbo.* interfaces described above are consciously designed to not be directly accessed by client code. They live in a different package named oracle.jbo.server.* and have the Impl suffix in their name to help remind you not to using them in your client-layer code.

In your business service tier implementation code, you can use any of the same methods that are available to clients above, but in addition you can also:

• Safely cast any oracle.jbo.* interface to its oracle.jbo.server.* package implementation class and use any methods on that Impl class as well.
• Override any of the base framework implementation class' public or protected methods to augment or change its default functionality by writing custom code in your component subclass before or after calling super.methodName().

This section provides a summary of the most frequently called, written, and overridden methods for the key ADF Business Components classes.

Controlling Custom Java Files For Your Components

Before examining the specifics of individual classes, it's important to understand how you can control which custom Java files each of your components will use. When you don't need a customized subclass for a given component, you can just let the base framework class handle the implementation at runtime.

Each business component you create comprises a single XML component descriptor, and zero or more related custom Java implementation files. Each component that supports Java customization has a Java tab in its component editor in the JDeveloper 10g IDE. By checking or unchecking the different Java classes, you control which ones get created for your component. If none of the boxes is checked, then your component will be an XML-only component, which simply uses the base framework class as its Java implementation. Otherwise, tick the checkbox of the related Java classes for the current component that you need to customize. JDeveloper 10g will create you a custom subclass of the framework base class in which you can add your code.

A best practice is to always generate Entity Object and View Row classes, even if you don't require any custom code in them other than the automatically-generated getter and setter methods. These getter and setter methods offer you compile-time type checking that avoids discovering errors at runtime when you accidentally set an attribute to an incorrect kind of value.

ApplicationModuleImpl Class

The ApplicationModuleImpl class is the base class for application module components. Since the application module is the ADF component used to implement a business service, think of the application module class as the place where you can write your service-level application logic. The application module coordinates with view object instances to support updateable collections of value objects that are automatically "wired" to business domain objects. The business domain objects are implemented as ADF entity objects.

Methods You Typically Call on ApplicationModuleImpl

Methods You Typically Write in Your Custom ApplicationModuleImpl Subclass

JDeveloper 10g can generate you a custom YourApplicationModuleName interface containing service-level custom methods that you've chosen to expose to the client. You do this by visiting the Client Interface tab of the Application Module editor, and shuttling the methods you'd like to appear in your client interface into the Selected list.

Methods You Typically Override in Your Custom ApplicationModuleImpl Subclass

DBTransactionImpl2 Class

The DBTransactionImpl2 class — which extends the base DBTransactionImpl class, and is constructed by the DatabaseTransactionFactory class — is the base class that implements the DBTransaction interface, representing the unit of pending work in the current transaction.

Methods You Typically Call on DBTransaction

If you want to...	Call this method on the DBTransaction object
Commit the transaction	commit()
Rollback the transaction	rollback()
Eagerly validate any pending invalid changes in the transaction	validate()
Create a JDBC PreparedStatement using the transaction's Connection object	createPreparedStatement()
Create a JDBC CallableStatement using the transaction's Connection object	createCallableStatement()
Create a JDBC Statement using the transaction's Connection object	createStatement()
Add a warning to the transaction's warning list.	addWarning()

Methods You Typically Override in Your Custom DBTransactionImpl2 Subclass

In order to have your custom DBTransactionImpl2 subclass get used at runtime, there are two steps you must follow:

1. Create a custom subclass of DatabaseTransactionFactory that overrides the create method to return an instance of your custom DBTransactionImpl2 subclass like this:

   package com.yourcompany.adfextensions;
import oracle.jbo.server.DBTransactionImpl2;
import oracle.jbo.server.DatabaseTransactionFactory;
import com.yourcompany.adfextensions.CustomDBTransactionImpl;
public class CustomDatabaseTransactionFactory extends DatabaseTransactionFactory {
  /**
   * Return an instance of our custom CustomDBTransactionImpl class
   * instead of the default implementation.
   *
   * @return An instance of our custom DBTransactionImpl2 implementation.
   */
  public DBTransactionImpl2 create() {
    return new CustomDBTransactionImpl();
  }
}

2. Tell the framework to use your custom transaction factory class by setting the value of the TransactionFactory configuration property to the fully-qualified class name of your custom transaction factory. As with other configuration properties, if not supplied in the configuration XML file, it can be provided alternatively as a Java system parameter of the same name.

EntityImpl Class

The EntityImpl class is the base class for entity objects, which encapsulate the data, validation rules, and business behavior for your business domain objects.

Methods You Typically Call on EntityImpl

Methods You Typically Write in Your Custom EntityImpl Subclass

Methods You Typically Override on EntityImpl

It is also possible to override the validateEntity() method to write entity-level validation code, however if you want to maintain the benefits of the ADF bundled exception mode — where the framework collects and reports a maximal set of validation errors back to the client user interface — it is recommended to adopt the MethodValidator approach suggested in the table above. This allows the framework to automatically collect all of your exceptions that your validation methods throw without your having to understand the bundled exception implementation mechanism. Overriding the validateEntity() method directly shifts the responsibility on your own code to correctly catch and bundle the exceptions like the ADF framework would have done by default, which is non-trivial and a chore to remember and hand-code each time.

EntityDefImpl Class

The EntityDefImpl class is a singleton, shared metadata object for all entity objects of a given type in a single Java VM. It defines the structure of the entity instances and provides methods to create new entity instances and find existing instances by their primary key.

Methods You Typically Call on EntityDefImpl

Methods You Typically Write on EntityDefImpl

Methods You Typically Override on EntityDefImpl

ViewObjectImpl Class

The ViewObjectImpl class the base class for view objects.

Methods You Typically Call on ViewObjectImpl

Methods You Typically Write in Your Custom ViewObjectImpl Subclass

JDeveloper 10g can generate you a custom YourViewObjectName interface containing view object custom methods that you've chosen to expose to the client. You can accomplish this by visiting the Client Interface tab of the View Object editor, and shuttling the methods you'd like to appear in your client interface into the Selected list.

Methods You Typically Override in Your Custom ViewObjectImpl Subclass

ViewRowImpl Class

The ViewRowImpl class the base class for view row objects.

Methods You Typically Call on ViewRowImpl

Methods You Typically Write on ViewRowImpl

JDeveloper 10g can generate you a custom YourViewObjectNameRow interface containing view row custom methods that you've chosen to expose to the client. You can accomplish this by visiting the Client Row Interface tab of the View Object editor, and shuttling the methods you'd like to appear in your client interface into the Selected list.

Methods You Typically Override in Your Custom ViewRowImpl Subclass

Setting Up Your Own Layer of Framework Base Classes

Before you begin to develop application specific business components, we recommend creating yourself a layer of classes that extend all of the ADF Business Components framework base implementation classes described in this paper. An example of a customized framework base class for application module components might look like this:

package com.yourcompany.adfextensions;
import oracle.jbo.server.ApplicationModuleImpl;
public class CustomApplicationModuleImpl extends ApplicationModuleImpl {
  /*
   * We might not yet have any custom code to put here yet, but
   * the first time we need to add a generic feature that all of
   * our company's application modules need, we will be very happy
   * that we thought ahead to leave ourselves a convenient place
   * in our class hierarchy to add it so that all of the application
   * modules we have created will instantly benefit by that new feature,
   * behavior change, or even perhaps, bug workaround.
   */
}

A common set of customized framework base classes in a package name of your own choosing like com.yourcompany.adfextensions, each importing the oracle.jbo.server.* package, would consist of the following classes.

• public class CustomEntityImpl extends EntityImpl
• public class CustomEntityDefImpl extends EntityDefImpl
• public class CustomViewObjectImpl extends ViewObjectImpl
• public class CustomViewRowImpl extends ViewRowImpl
• public class CustomApplicationModuleImpl extends ApplicationModuleImpl
• public class CustomDBTransactionImpl extends DBTransactionImpl2
• public class CustomDatabaseTransactionFactory extends DatabaseTransactionFactory

For completeness, you may also want to create customized framework classes for the following classes as well, but overriding anything in these classes would be a fairly rare requirement.

• public class CustomViewDefImpl extends ViewDefImpl
• public class CustomEntityCache extends EntityCache
• public class CustomApplicationModuleDefImpl extends ApplicationModuleDefImpl

Conclusion

Hopefully this short list of methods will assist you in getting started with Oracle ADF Business Components to focus your attention on these most frequently used methods instead of feeling bewildered about the many other methods that could be overridden but which aren't often done in practice.

If you have already been using ADF Business Components for some time and notice some methods you use frequently that didn't make my list, please send me an email to let me know what I should add to the list. Include in your email a brief description of how you're using the method, or what functionality you often providing in the overridden version of the method. Thanks!

Revision History