| Oracle® Application Development Framework Developer's Guide For Forms/4GL Developers 10g Release 3 (10.1.3.0) Part Number B25947-02 |
|
|
View PDF |
| Oracle® Application Development Framework Developer's Guide For Forms/4GL Developers 10g Release 3 (10.1.3.0) Part Number B25947-02 |
|
|
View PDF |
This chapter provides an overview of the ADF Business Components layer of Oracle ADF, including a description of the key features they provide for building your business services.
This chapter includes the following sections:
Section 4.1, "Prescriptive Approach and Reusable Code for Business Services"
Section 4.2, "What are ADF Business Components and What Can They Do?"
Section 4.3, "Relating ADF Business Components to Familiar 4GL Tools"
Section 4.4, "Overview of ADF Business Components Implementation Architecture"
Section 4.6, "Overview of ADF Business Components Design Time Facilities"
The J2EE platform defines a server-side model for development and deployment of services. However, the task of writing, reusing, and customizing the robust functionality needed for real-world business applications is left as an exercise for the members of each development team to figure out for themselves. In particular, the J2EE specifications do not prescribe an approach for:
writing and enforcing business application logic in a central way
reusing business logic in multiple applications
accessing updatable views of business data tailored specifically to the task at hand
maintaining and customizing the business functionality once the application is delivered.
From years of experience in building the E-Business Suite applications on the J2EE platform, Oracle knows that these are the activities where you'll spend the bulk of your time and effort when you build your own J2EE solutions. ADF Business Components is designed to provide a prescriptive approach to address the these challenging tasks, and offers a reusable library of software components and design time "plugins" to JDeveloper that make it easy to follow the time-tested approach they prescribe.
The ADF Business Components technology in Oracle ADF is the culmination of years of joint design and development work between the Oracle Applications, Oracle Tools, and Oracle Server Technologies divisions to pragmatically implement Oracle's vision for how well-architected, database-centric enterprise J2EE applications will be built now and in the future.
Along with the other layers of the overall Oracle ADF, ADF Business Components is the technology used daily by over 4000 of Oracle's own internal applications developers, and by several thousand external customers including Oracle partners. This means it is a proven solution you can count on, too.
ADF Business Components are "building-blocks" that provide the most productive way to create, deploy, and maintain a business service. ADF Business Components dramatically simplifies the development, delivery, and customization of enterprise J2EE business applications by providing you with a set of intelligent software building-blocks that save development time by making many of the most typical development task declarative. They cooperate "out-of-the-box" to manage all of the common facilities required to:
Productively author and test business logic in components which automatically integrate with databases,
Flexibly reuse business logic through multiple SQL-based views of data, supporting different application tasks,
Efficiently access and update the views from browser, desktop, mobile, and web service clients
Easily customize application functionality in layers without requiring modification of the delivered application.
By eliminating the substantial coding and testing work related to common "application plumbing" facilities, ADF Business Components lets application developers focus full-time on implementing business solutions. ADF Business Components provides a foundation of Java classes that your business-tier application components extend to leverage a robust implementation of the numerous design patterns you need in the following areas:
Design a data model for client displays, including only necessary data
Include master/detail hierarchies of any complexity as part of the data model
Implement end-user query-by-example data filtering without code
Automatically coordinate data model changes with business domain object layer
Automatically validate and save any changes to the database
Declaratively enforce required fields, primary key uniqueness, data precision/scale, and foreign key references
Easily capture and enforce both simple and complex business rules, programmatically or declaratively, with multi-level validation support
Navigate relationships between business domain objects and enforce constraints related to compound components
Automatically reflect changes made by business service application logic in the user interface,
Retrieve reference information from related tables, and automatically maintain the information when user changes foreign-key values
Simplify multi-step web-based business transactions with automatic web-tier state management
Handle images, video, sound, and documents with no code
Synchronize pending data changes across multiple views of data
Consistently apply prompts, tooltips, format masks, and error messages in any application
Define custom metadata for any business components to support metadata-driven user interface or application functionality.
Add dynamic attributes at runtime to simplify per-row state management.
Enforce best-practice interface-based programming style
Simplify application security with automatic JAAS integration and audit maintenance
"Write once, deploy any": use the same business service as plain Java class, EJB session bean, or web service
Switch from 2-tier to 3-tier deployment with no client code changes
Reduce network traffic for remote clients through efficient batch operations
Extend component functionality after delivery without modifying source code
Globally substitute delivered components with extended ones without modifying the application.
Deliver application upgrades without losing or having to reapply downstream customizations manually
All of these features can be summarized by saying that using ADF Business Components for your J2EE business service layer makes your life a lot easier. The key ADF Business Components components that cooperate to provide the business service implementation are:
Entity Object
An entity object represents a row in a database table and simplifies modifying its data by handling all DML operations for you. It can encapsulate business logic for the row to ensure your business rules are consistently enforced. You associate an entity object with others to reflect relationships in the underlying database schema to create a layer of business domain objects to reuse in multiple applications.
Application Module
An application module is the transactional component that UI clients use to work with application data. It defines an updatable data model and top-level procedures and functions (called service methods) related to a logical unit of work related to an end-user task.
View Object
A view object represents a SQL query and simplifies working with its results. You use the full power of the familiar SQL language to join, project, filter, sort, and aggregate data into exactly the "shape" required by the end-user task at hand. This includes the ability to link a view object with others to create master/detail hierarchies of any complexity. When end users modify data in the user interface, your view objects collaborate with entity objects to consistently validate and save the changes.
While the base components handle all the common cases with their sophisticated built-in behavior, taking advantage of their benefits does not compromise your ability to have it your way whenever necessary. Since any automatic behavior provided by the base components can be easily overridden with a few strategic lines of code, you're never locked in to a certain way of doing things for all cases.
ADF Business Components provides components that implement functionality similar to what you are used to in the enterprise 4GL tools you have used prior to embarking on J2EE development. This section will assist you in understanding how the key components in ADF Business Components map conceptually to the ones you have used in other 4GL tools.
ADF Business Components implements all of the data-centric aspects of the familiar Oracle Forms runtime functionality in a way that they can be used with any kind of user interface. In Oracle Forms, each form contains both visual objects like canvases, windows, alerts, and LOVs, as well as non-visual objects like data blocks, relations, and record groups. Individual data block items have both visual properties like Foreground Color and Bevel as well as non-visual properties like Data Type and Maximum Length. Even the different event-handling triggers that Forms defines fall into visual and non-visual categories. For example, it's clear that triggers like WHEN-BUTTON-PRESSED and WHEN-MOUSE-CLICKED are visual in nature, relating to the front-end UI, while triggers like WHEN-VALIDATE-ITEM and ON-INSERT are more related to the back-end data processing. While merging visual and non-visual aspects definitely simplifies the learning curve, the flip side is that it can complicate reuse. With a cleaner separation of UI-related and data-related elements, it would be easier to redesign the user interface without disturbing back-end business logic and easier to repurpose back-end business logic in multiple different forms.
In order to imagine this separation of UI and data, consider lopping a form as you know it today in half, keeping only its non-visual, data-related aspects. What's left would be a container of data blocks, relations, and record groups. This container would continue to provide a database connection for the data blocks to share and be responsible for coordinating transaction commits or rollbacks. Of course, you could still use the non-visual validation and transactional triggers to augment or change the default data-processing behavior as well. This non-visual object your considering is a kind of a "smart data model" or a generic application module, with data and business logic, but no user interface elements. The goal of separating this application module from anything visual is to allow any kind of user interface you need in the future to use it as a data service.
Focus a moment on the role the data blocks would play in this application module. They would query rows of data from the database using SQL, coordinate master/detail relationships with other data blocks, validate user data entry with WHEN-VALIDATE-RECORD and WHEN-VALIDATE-ITEM triggers, and communicate valid user changes back to the database with INSERT, UPDATE, and DELETE statements when you commit the data service's transaction.
Experience tells you that you need to filter, join, order, and group data for your end-users in many different ways depending on the task at hand. On the other hand, the validation rules that you apply to your business domain data remain basically the same over time. Given these observations, it would be genuinely useful to write business entity validation exactly once, and leverage it consistently anywhere that data is manipulated by users in your applications.
Enabling this flexibility requires further "factoring" of your data block functionality. You need one kind of "SQL query" object to represent each of the many different views of data your application requires, and another kind of "business entity" object that will enforce business rules and communicate changes to your base table in a consistent way. By splitting things again like this, you can have multiple different "view objects" working with the same underlying "entity object" when their SQL queries present the same business data.
Oracle ADF breathes life into the UI/data split you imagined above by providing ready-to-use Java components that implement the Forms-inspired functionality you're familiar with in the Java world, with responsibilities divided along the cleanly-separated functional lines you just hypothesized.
The ApplicationModule component is the "data half of the form" you considered above. It's a smart data service containing a data model of master/detail-related queries that your client interface needs to work with. It also provides a transaction and database connection used by the components it contains. It can contain form-level procedures and functions called service methods, that are encapsulated within the service implementation. You can decide which of these procedures and functions should be private and which ones should be public.
The EntityObject implements the "validation and database changes half" of the data block functionality from above. In the Forms runtime, this duty is performed by the record manager. It is responsible for keeping track of which of the rows in a data block have changed, for firing the validation triggers in a data block and its data items, and for coordinating the saving of changes to the database. This is exactly what an entity object does for you. Related to an underlying base table, it's a component that represents your business domain entity and gives you a single place to encapsulate business logic related to validation, defaulting, and database modification behavior for that business object.
The ViewObject component performs the "data retrieval half" of the data block functionality above. Each view object encapsulates a SQL query, and at runtime each one manages its own query result set. If you connect two or more view objects in master/detail relationships, that coordination is handled automatically. While defining a view object, you can link any of its query columns to underlying entity objects. By capturing this information, the view object and entity object can cooperate automatically for you at runtime to enforce your domain business logic regardless of the "shape" of the business data needed by the user for the task at hand.
If you have developed solutions in the past with PeopleTools, you are familiar with the PeopleTools Component structure. ADF Business Components implement the data access functionality you are familiar with from PeopleTools.
Application Module is a ÒheadlessÓ Component
ADF adheres to an MVC pattern and separates the Model from the View. Pages as you are familiar with in the PeopleTools Component are defined in the view layer, using standard technologies like with JSF and ADF Faces components for web-based applications or Swing for desktop-fidelity client displays.
The ADF Application Module defines the data structure, just like the PeopleTools Component Buffer. By defining master/detail relationships between ADF query components that produce row sets of data, you ensure that any Application Module that works with the data can reuse the natural hierarchy as required, similar to the scroll levels in the Component Buffer.
Similar to the Component Interface you are familiar with, the Application Module is a service object that provides access to standard methods as well as additional developer-defined business logic. In order to present a "headless" data service for a particular user interface, the Component Interface restricts a number of PeopleTools functions that are related to UI interaction. The Application Module is similar to the Component Interface in that it provides a "headless" data service, but in contrast it does not do this by wrapping a restricted view of an existing user interface. Instead, the Application Module is architected to deal exclusively with business logic and data access. Rather than building a Component Interface on top of the Component, with ADF you first build the Application Module service that is independent of user interface, and then build one or more pages on top of this service to accomplish some end-user task in your application.
The Application Module is associated with a Transaction object in the same way that the PeopleTools Component Buffer is. The Application Module also provides a database connection for the components it contains. Any logic you associate today with the transaction as Component PeopleCode, in ADF you would define as logic on the Application Module.
Logic associated with records in the transaction, that today you write as Component Record PeopleCode or Component Record Field PeopleCode, should probably not be defined on the Application Module. ADF has View Objects (see below) that allow for better re-use when the same Record appears in different Components.
Entity Object is a Record Definition
The Entity Object is the mapping to the underlying data structure, just like the PeopleTools Record Definition maps to the underlying table or view. You'll often create one Entity Object for each of the tables that you need to manipulate your application.
Similar to how you declare a set of valid values for fields like 'Customer Status' using PeopleTools' translate values, in ADF you can add declarative validations to the individual Attributes of an Entity Object. Any logic you associate with the record that applies throughout your applications, which today you write as Record PeopleCode or Record Field PeopleCode, can be defined in ADF on the Entity Object.
View Object Queries Data Like a Row Set
Just like a PeopleTools row set, a View Object can be populated by a SQL query. Unlike a row set, a View Object definition can contain business logic.
Any logic, which you would find in Component Record PeopleCode, is a likely candidate to define on the View Object. Component Record PeopleCode is directly tied to the Component, but a View Object can be associated with different Application Modules. While you can use the same Record Definition in many PeopleTools Components, Oracle ADF allows you to reuse the business logic across multiple applications.
The View Object queries data in exactly the "shape" that is useful for the current application. Many View Objects can be built on top of the same Entity Object.
You can define relationships between View Objects to create master-detail structures just like you find them in the scroll levels in the PeopleTools Component.
If you have developed solutions in the past with SiebelTools version 7.0 or earlier, you will find that ADF Business Components implements all of the familiar data access functionality you are familiar with, with numerous enhancements.
Entity Object is a Table Object with Encapsulated Business Logic
Like the Siebel Table object, the ADF Entity Object describes the physical characteristics of a single table, including column names and physical data types. Both objects contain sufficient information to generate the DDL to create the physical tables in the DB. In ADF you define Associations between Entity Objects to reflect the foreign keys present in the underlying tables, and these associations are used automatically join business information in the view object queries used by user interface pages or screens. List of values objects that you reference from data columns today are handled in ADF through a combination of declarative entity validation rules and view object queries. You can also encapsulate other declarative or programmatic business logic with these entity object "table" handlers that is automatically reused in any view of the data you create.
View Object is a Business Component
Like the Siebel Business Component, the ADF View Object describes a logical mapping on top of the underlying physical table representation. They both allow you to provide logical field names, data, and calculated fields that match the needs of the user interface. As with the Business Component, you can define View Objects that join information from various underlying tables. The related ADF View Link is similar to the Siebel Link object and allows you to define master/detail relationships. In ADF, your view object definitions can exploit the full power of the SQL language to shape the data as required by the user interface.
Application Module is a Business Object With Connection and Transaction
The Siebel Business Object lets you define a collection of Business Components. The ADF Application Module performs a similar task, allowing you to create a collection of master/detail View Objects that act as a "data model" for a set of related user interface pages. In addition, the Application Module provides a transaction and database connection context for this group of data views. You can make multiple requests to objects obtained from the Application Module and these participate in the same transaction.
If you have developed solutions in the past with Visual Studio 2003 or 2005, you are familiar with using the ADO.NET framework for data access. ADF Business Components implements all of the data access functionality you are familiar with from ADO.NET, with numerous enhancements.
The ApplicationModule component plays the same role as the ADO.NET DataSet. It is a strongly-typed service component that represents a collection of row sets called view objects, which as described below, are similar to ADO.NET DataTables. The application module works with a related Transaction object to provide the context for queries the SQL queries the view objects execute and the modifications saved to the database by the entity objects, which play the role of the ADO.NET DataAdapter.
The EntityObject is like a strongly-typed ADO.NET DataAdapter. It represents the rows in a particular table and handles the find-by-primary-key, insert, update, delete, and lock operations for those rows. In ADF, you don't have to specify these statements yourself, but you can override them if you need to. The entity object encapsulates validation or other business logic related to attributes or entire rows in the underlying table. This validation is enforced when data is modified and saved by the end-user using any view object query that references the underlying entity object.
The ViewObject component encapsulates a SQL query and manages the set of resulting rows. It can be related to an underlying entity object to automatically coordinate validation and saving of modifications made by the user to those rows. This cooperation between a view object's queried data and an entity objects encapsulated business logic offers all of the benefits of the DataTable with the clean encapsulation of business logic into a layer of business domain objects. Like ADO.NET data tables, you can easily work with a view object's data as XML or have a view object read XML data to automatically insert, update, or delete rows based on the information it contains.
Before diving into each of the key components in subsequent chapters, it's good at the outset to understand a few guiding principles that have gone into the design and implementation of this layer of Oracle ADF.
Like the rest of Oracle ADF, the ADF Business Components technology is implemented in Java. The base components implement a large amount of generic, metadata-driven functionality to save you development time by standing on the shoulders of a rich layer of working, tested code. The metadata for ADF Business Components follow J2EE community best practice of using cleanly-separated XML files to hold the metadata that configures each component's runtime behavior.
Since ADF Business Components is often used for bet-your-business applications, it's important to understand that full source for Oracle ADF, including the ADF Business Components layer, is available to supported customers through Oracle Worldwide Support. The full source code for the framework can be an important tool to assist you in diagnosing problems and in correctly extending the base framework functionality for your needs.
Because your business components are implemented using plain Java classes and XML files, you can use them in any runtime environment where a Java Virtual Machine is present. This means that services built using ADF Business Components are easy to use both inside a J2EE server — known as the "container" of your application at runtime — as well as outside. Customers routinely use application modules in such diverse configurations as command-line batch programs, web services, custom servlets, JSP pages, desktop-fidelity clients built using Swing, and others.
Applications built using ADF Business Components can run on any Java-capable application server, including any J2EE-compliant application server. As described in Section 4.6.1, "Choosing a Connection, SQL Flavor, and Type Map", in addition to building applications that target Oracle databases with numerous optimizations, you can also build applications that work with non-Oracle databases.
The ADF Business Components layer implements all of the popular J2EE design patterns that you would normally need to understand, implement, and debug yourself to create a real-world enterprise J2EE application. If it is important to you to cross-reference the names of some of these design patterns you might have read about in J2EE literature with how they are implemented by ADF Business Components, you can refer to Appendix E, "ADF Business Components J2EE Design Pattern Catalog".
Since ADF Business Components is implemented in Java, it is implemented in Java classes and interfaces that are organized into packages. Java packages are identified by dot-separated names that developers use to arrange code into a hierarchical naming structure. To ensure your code won't clash with reusable code from other organizations, best practice dictates choosing package names that begin with your organization's name or web domain name. So, for example, the Apache organization chose org.apache.tomcat for a package name related to its Tomcat web server, while Oracle picked oracle.xml.parser as a package name for its XML parser. Components you create for an your own applications will live in a packages with names like com.yourcompany.yourapp and subpackages of these.
As a specific example, the ADF Business Components that make up the main business service for the SRDemo application are organized into the oracle.srdemo.model package, and subpackages. As shown in Figure 4-1, these components reside in the DataModel project in the workspace, and are organized broadly as follows:
oracle.srdemo.model contains the SRService application module
oracle.srdemo.model.queries contains the view objects
oracle.srdemo.model.entities contains the entity objects
oracle.srdemo.model.design contains UML diagrams documenting the service
In your own applications, you can choose any package organization that you believe best organizes them. In particular, keep in mind that you are not constrained to organize components of the same type into a single package as the creators of the SRDemo application have done.
Due to JDeveloper's support for refactoring, you can easily rename or move components to a different package structure at any time. In other words, you don't need to necessarily get the structure right the first time. Your business service's package structure will almost certainly evolve over time as you gain more experience with the ADF environment.
There is no "magic" number that describes the optimal number of components in a package. However, with experience, you'll realize that the correct structure for your team falls somewhere between the two extremes of:
All components in a single package
Each component in its own, separate package
As described in more detail in Section 25.7, "Working with Libraries of Reusable Business Components", since a package of ADF Business Components is the unit of granularity that JDeveloper supports importing for reuse in other projects, sometimes you'll also factor this consideration into how you choose to organize components.
The classes and interfaces that comprise the pre-built code provided by the ADF Business Components layer live in the oracle.jbo package and numerous subpackages, however in your day to day work with ADF Business Components you'll mostly be working with classes and interfaces in the two key packages oracle.jbo and oracle.jbo.server. The oracle.jbo package contains all of the interfaces that are designed for the business service client to work with, while the oracle.jbo.server package contains the classes that implement these interfaces.
Note:
The term "client" here means any code in the model, view or controller layers that accesses the application module component as a business service.Figure 4-2 shows a concrete example of the application module component. The client interface for the application module is the ApplicationModule interface in the oracle.jbo package. This interface defines the names and signatures of methods that clients can use while working with the application module, but it does not include any specifics about the implementation of that functionality. The class that implements the base functionality of the application module component lives in the oracle.jbo.server package and is named ApplicationModuleImpl.
Each kind of component in ADF Business Components comes with built-in runtime functionality that you control through declarative settings. These settings are stored in an XML component definition file with the same name as the component that it represents. When you need to write custom code for a component, you can enable an optional custom Java class for the component in question.
Figure 4-3 illustrates the XML component definition file for an application-specific component like an application module named YourService that you create in a package named com.yourcompany.yourapp. The corresponding XML component definition resides in a ./com/yourcompany/yourapp subdirectory of the JDeveloper's project's source path root directory. That XML file records the name of the Java class it should use at runtime to provide the application module implementation. In this case, the XML records the name of the base oracle.jbo.server.ApplicationModuleImpl class provided by Oracle ADF.
If you have no need to extend the built-in functionality of a component in ADF Business Components, and no need to write any custom code to handle its built-in events, you can use the component in this XML-only fashion. This means your component is completely defined by its XML component definition and be fully-functionality without requiring any custom Java code or even a Java class file related to the component at all.
When you need to add custom code to extend the base functionality of a component or to handle events, you can enable a custom Java class for any of the key types of ADF Business Components you create. You enable custom classes for a component on the Java panel of its respective component editor in JDeveloper. This creates a Java source file for a custom class related to the component whose name follows a configurable naming standard. This class, whose name is recorded in the component's XML component definition, provides a place where you can write the custom Java code required by that component. Once you've enabled a custom Java class for a component, you can navigate to it at any time using a corresponding Go To... Class option in the component's Application Navigator context menu.
Figure 4-4 illustrates what occurs when you enable a custom Java class for the YourService application module considered above. A YourServiceImpl.java source code file is created in the same directory in the source path as your component's XML component definition file. The YourService.xml file is updated to reflect the fact that at runtime the component should use the com.yourcompany.yourapp.YourServiceImpl class instead of the base ApplicationModuleImpl class.
Note:
The examples in this guide use default settings for generated names of custom component classes and interfaces. If you want to change these defaults for your own applications, use the Business Components: Class Naming page of the JDeveloper Tools Preferences dialog. Changes you make only affect newly created components.You can configure whether JDeveloper generates custom Java files by default for each component type that supports it, as well as whether JDeveloper maintains a list of Oracle ADF business components in each package using a package XML file. This section describes Oracle's recommendations to developers getting started with ADF Business Components on how to configure these options.
Your applications can freely mix XML-only components with components that have related custom Java files. For example, you can define a completely functional, updatable data model with declaratively enforced business rules using XML-only components. On the other end of the spectrum, some developers prefer to proactively generate Java classes for each component they create as part of their team's coding style.
For developers getting started with ADF Business Components, Oracle recommends initially configuring JDeveloper to not generate any custom Java classes by default. This way, you learn the reasons why custom Java is needed and you consciously enable it for the components that require it in your application. Over time, you will develop a personal preference of your own.
Note that this recommended setting is not the default, so you need to perform the following steps to configure the Java generation preferences as recommended here:
Choose Tools | Preferences... from the JDeveloper main menu
Select the Business Components preference category in the tree at the left
Ensure all of the checkboxes are unchecked as shown in Figure 4-5, then click OK.
By default, for upward compatibility with previously releases of Oracle ADF, JDeveloper maintains an XML file in each directory containing the names of the Oracle ADF business components that reside in that package. While previously required by the ADF runtime classes, this package XML file is optional in this version. Since maintaining this "package XML" file can complicate team development, Oracle recommends you disable the use of any package XML files by setting the Copy Package XML Files to Class Path option off in the Business Components: General panel of the IDE preferences as shown in Figure 4-6.
The Java language provides a number of built-in data types for working with strings, dates, numbers, and other data. When working with ADF Business Components, you can use these types, but by default you'll use an optimized set of types in the oracle.jbo.domain and oracle.ord.im packages. These types, shown in Table 4-1, improve the performance of working with data from the Oracle database by allowing the data to remain in its native, internal format avoiding costly type conversions when they are not necessary. For working with string-based data, by default ADF Business Components uses the regular java.lang.String type.
Table 4-1 Basic Data Types in the oracle.jbo.domain and oracle.ord.im Packages
| Data Type | Represents |
|---|---|
|
|
Any numerical data |
|
|
Date with optional time |
|
|
Sequential integer assigned by a database trigger |
|
|
Oracle database ROWID |
|
|
Timestamp value |
|
|
Timestamp value with Timezone information |
|
|
Binary File (BFILE) object |
|
|
Binary Large Object (BLOB) |
|
|
Character Large Object (CLOB) |
|
|
Oracle Intermedia Image (ORDIMAGE) |
|
|
Oracle Intermedia Audio (ORDAUDIO) |
|
|
Oracle Intermedia Video (ORDVIDEO) |
|
|
Oracle Intermedia Document (ORDDOC) |
|
|
User-defined object type |
|
|
User-defined collection type (e.g. |
Note:
The
oracle.jbo.domain.Number class has the same class name as the built-in java.lang.Number type. Since the Java compiler implicitly imports java.lang.* into every class, you need to explicitly import the oracle.jbo.domain.Number class into any class that references this. Typically, JDeveloper will do this automatically for you, but when you begin to write more custom code of your own, you'll learn to recognize compiler or runtime errors related to "Number is an abstract class" mean that you are inadvertently using java.lang.Number instead of oracle.jbo.domain.Number. Adding the:
import oracle.jbo.domain.Number;
line at the top of your class, after the package line, avoids these kinds of errors.
When working with application modules, view objects, and entity objects, you can choose to use a set of generic APIs or can have JDeveloper generate code into a custom Java class to enable a strongly-typed API for that component. For example, when working with an view object, you can access the value of an attribute in any row of its result using a generic API like:
Row row = serviceRequestVO.getCurrentRow();
Date requestDate = (Date)row.getAttribute("RequestDate");
Notice that using the generic APIs, you pass string names for parameters, and you have to cast the return type to the expected type like Date shown in the example.
Alternatively, if you enable the strongly-typed style of working you can write code like this:
ServiceRequestsRow row = (ServiceRequestRow)serviceRequestVO.getCurrentRow(); Date requestDate = row.getRequestDate();
In this case, you work with generated method names whose return type is known at compile time, instead of passing string names and having to cast the results. Subsequent chapters explain how to enable this strongly-typed style of working if you prefer it.
By design, the entity objects in the business domain layer of business service implementation are not designed to be referenced directly by clients. Instead, clients work with the data queried by view objects as part of an application module's data model. Behind the scenes, as you'll learn in Section 7.7, "Understanding How View Objects and Entity Objects Cooperate at Runtime", the view object cooperates automatically with entity objects in the business domain layer to coordinate validating and saving the data the user changes.
Therefore, the client-visible components of your business service are the:
Application Module — representing the service itself
View Objects — representing the query components
View Rows — representing each row in a given query component's results
The oracle.jbo package provides client-accessible API for your business service as a set of Java interfaces. In line with the design mentioned above, this package does not contain any Entity interface, or any methods that allow the client to directly work with entity objects. Instead, client code works with interfaces like:
ApplicationModule — to work with the application module
ViewObject — to work with the view object
Row — to work with the view rows
When you begin adding custom code to your Oracle ADF business components that you want clients to be able to call, you can "publish" that functionality to clients for any client-visible component. For each of your components that publishes at least one custom method to clients on its client interface, JDeveloper automatically maintains the related Java interface file. So, assuming you were working with an application module like the SRService module used in the SRDemo application, you can have custom interfaces like:
Custom Application Module Interface
SRService extends ApplicationModule
Custom View Object Interface
StaffListByEmailNameRole extends ViewObject
Custom View Row Interface
StaffListRowClient extends Row
Client code can then cast one of the generic client interfaces to the more specific one that includes the selected set of client-accessible methods you've selected for your particular component.
One of the key simplifying benefits of using ADF Business Components for your business service implementation is the application module's support for an "active data model" of row sets. For developers coming from a Forms/4GL background, it works just like you are used to in previous tools.
Using a typical J2EE business service implementation puts the burden on the client layer developer to be responsible for:
Invoking service methods to return data to present,
Tracking what data the client has created, deleted, or modified, and
Passing the changes back to one or more different service methods to validate and save them.
The architects that designed the ADF application module recognized that this retrieve, create, edit, delete, and save cycle is so common in enterprise business applications that a smarter, more generic solution was required. Using the application module for your business service, you simply bind client UI controls like fields, tables and trees to the active view object instances in the application module's data model. Your UI displays automatically update to reflect any changes to the rows in the view object row sets in that data model. This includes displays you create using JSP or JSF pages for the web or mobile devices, as well as desktop-fidelity UI's comprising windows and panels using Swing. This "active" data notification includes changes to the data model that are the result of work performed directly or indirectly by your custom business service methods, too.
Under the covers the application module component implements a set of generic service methods to enable the active data model facility in a Service Oriented Architecture (SOA). The client layer simply uses the ADF Business Components interfaces in the oracle.jbo package. These interfaces provide a higher-level API that lets you think in terms of row sets of rows in the data model whose contents your end-user needs to search for, create, delete, modify and save. They hide all of the lower-level generic SOA-method calling complexity. What's more, when you build UI displays that take advantage of the ADF Model layer for declarative data binding, you generally don't need to write client-side code at all to work with the active data model. Your displays are bound declaratively to view objects in the data model, and to custom business service methods when you need to perform any other kind of logic business service function.
Consider the following three simple, concrete examples of the active data model in action:
A customer logs into the SRDemo application and sees their list of open service requests. They visit some wizard pages and create a new service request, when they return back to their home page, the new service request appears in their list of open requests without re-querying the database.
A manager edits a service request and assigns a technician to the case by picking their name from a poplist list of values page. Business logic encapsulated in the ServiceRequest entity object in the business domain layer behind the data model contains a simple rule that updates the assigned date to the current date and time whenever the service request's assigned to attribute is changed. The user interface updates to automatically reflect the assigned date that was changed by the logic in the business domain layer.
In a tree display, the user clicks on a specific node in a tree. This declaratively invokes a business service method on your application module that re-queries master detail information and sets the current rows to an appropriate row in the row set. The display updates to reflect the new master/detail data and current row displayed.
Without an active data model, the developer using a less clever business service implementation approach is forced to write more code in the client to handle the straightforward, everyday CRUD-style operations. In addition, to keep pages up to date, they are forced to manage "refresh flags" that clue the controller layer in to requesting a "repull" of data from the business service to reflect data that might have been modified. When using an ADF application module to implement your business service, you can focus on the business logic at hand, instead of the plumbing to make your business work as your end users expect.
Because the application module's active data model feature ensures your client user interface is always up to date, you can typically avoid writing code in the client that is related to setting up or manipulating the data model. Oracle recommends encapsulating any code of this kind inside custom methods of your application module component. Whenever the programmatic code that manipulates view objects is a logical aspect of implementing your complete business service functionality you should encapsulate the details by writing a custom method in your application module's Java class. This includes, but is not limited to, code that:
Configures view object properties to query the correct data to display
Iterates over view object rows to return an aggregate calculation
Performs any kind of multi-step procedural logic with one or more view objects.
By centralizing these implementation details in your application module, you gain the following benefits:
You make the intent of your code more clear to clients
You allow multiple client pages to easily call the same code if needed
You simplify regression testing your complete business service functionality
You keep the option open to improve your implementation without affecting clients, and
You enable declarative invocation of logical business functionality in your pages.
Another typical type of client-side code you no longer have to write using ADF Business Components is code that coordinates detail data collections when a row in the master changes. By linking the view objects as you'll learn in the next chapter, you can have the coordination performed automatically for you.
JDeveloper offer broad design time support for ADF Business Components. This section highlights the facilities you'll be using throughout the guide to work with your business components.
The first time you create a component, you'll see the Initialize Business Components Project dialog shown in Figure 4-7. You use this dialog to select a design time database connection to work with while working on your business components in this project. The Connection dropdown list shows a list of all the named connection definitions you've created, or clicking New... allows you to create a new one if you don't see the one you need.
The SQL Flavor setting controls the syntax of the SQL statements your view objects will use and the syntax of the DML statements your entity objects will use. If JDeveloper detects you are using an Oracle database driver, it defaults this setting to the Oracle SQL flavor. The supported SQL flavors include:
Oracle — the default, for working with Oracle
OLite — for the Oracle Lite database
SQLServer — for working with a Microsoft SQLServer database
DB2 — for working with an IBM DB2 database
SQL92 — for working with any other supported SQL92- compliant database
The Type Map setting controls whether you want this project to use the optimized set of Oracle data types, or use only the basic Java data types. If JDeveloper detects you are using an Oracle database driver, it defaults this setting to the Oracle Type map. The supported type maps are:
Oracle — use optimized types in the oracle.jbo.domain package
Java — use basic Java types only
Note:
If you plan to have your application run against both Oracle and non-Oracle databases, you should select the
SQL92 SQL Flavor when you begin building your application, not later. While this makes the application portable to both Oracle and non-Oracle databases, it sacrifices using some of the Oracle-specific optimizations that are inherent in using the Oracle SQL Flavor.In the New Gallery in the ADF Business Components category, JDeveloper offers a wizard to create each kind of business component. Each wizard allows you to specify the component name for the new component and to select the package into which you'd like to organize the component. If the package does not yet exist, the new component becomes the first component in that new package. The wizard presents a series of panels that capture the necessary information to create the component type. When you click Finish, JDeveloper creates the new component by saving its XML component definition file. If you have set your Java generation options to prefer their generation by default, JDeveloper also creates the initial custom Java class files.
Once a package exists in the Application Navigator, you can quickly create additional business components of any type in the package by selecting it in the Application Navigator and using one of the options on the right-mouse context menu as shown in Figure 4-8.
Once a component exists, you can edit it using the respective component editor that you access by either double-clicking on the component in the Application Navigator or selecting it and choosing the Edit option from the right-mouse context menu. The component editor presents a superset of the panels available in the wizard, and allows you to change any aspect of the component. When you click OK, JDeveloper updates the components XML component definition file and if necessary any of its related custom Java files.
As highlighted in the walkthrough in Chapter 2, "Overview of Development Process with Oracle ADF and JSF", JDeveloper offers extensive UML diagramming support for ADF Business Components. You can drop existing components you've already created onto a business components diagram to visualize them, use the diagram to create and modify components, or a mixture of the two. The diagrams are kept in sync with changes you make in the editors.
To create a new business components diagram, use the Business Components Diagram item in the ADF Business Components category of the JDeveloper New Gallery. This category is part of the Business Tier choices.
Once you have created an application module component, you can test it interactively using the built-in Business Components Browser. To launch the Business Components Browser, select the application module in the Application Navigator or business components diagram and choose Test... from the right-mouse context menu.
This tool presents the view object instances in the application module's data model and allows you to interact with them using a dynamically generated user interface. This tool is invaluable for testing or debugging your business service both before and after you create the view layer of pages or Swing panels.
At any time, you can select a component in the Application Navigator and choose Refactor > Rename from the right-mouse context menu to rename the component. You can also select one or more components in the navigator — by holding down the [Ctrl] key while you select with the mouse click — and choose Refactor > Move to move the selected components to a new package. References to the old component names or packages in the current project are adjusted automatically.
