Your organization has decided that ADF might be the right tool to build your next enterprise application—now you need to set up an experiment to prove that your assumption is correct.
You can compare the situation at the start of a project to standing in front of a mountain with the task to excavate a tunnel. The mountainsides are almost vertical, and there is no way for you to climb the mountain to figure out how wide it is. You can take two approaches:
You can either start blasting and drilling in the full width of the tunnel you need
You can start drilling a very small pilot tunnel all through the mountain, and then expand it to full width later
It's probably more efficient to build in the full width of the tunnel straight from the beginning, but this approach has some serious disadvantages as well. You don't know how wide the mountain is, so you can't tell how long it will take to build the tunnel. In addition, you don't know what kind of surprises might lurk in the mountain—porous rock, aquifers, or any number of other obstacles to your tunnel building.
That's why you should build the pilot tunnel first—so you know the size of the task and have an idea of the obstacles you might meet on the way.
Since you have decided to evaluate ADF for your enterprise application, you probably already have a pretty good idea of its architecture and capabilities. Therefore, this section will only give a very brief overview of ADF—there are many whitepapers, tutorials, and demonstrations available at the Oracle Technology Network website. Your starting point for ADF information is http://otn.oracle.com/developer-tools/jdev/overview.
The View layer is interacting with the user, displaying data as well as receiving updates and user actions. The Controller layer is in charge of interpreting user actions and deciding which screens are presented to the user in which order. And the Model layer is representing the backend business services to the View and Controller, hiding the complexity of storing and retrieving data.
This architecture implements a clean separation of duties— the page doesn't have to worry about where to go next, because that is the task of the controller. And the controller doesn't have to worry about how to store data in the data service, because that is the task of the model.
An enterprise application could also have a desktop application frontend, and might have additional frontends for mobile users or even use existing desktop applications like Microsoft Excel to interact with data. In the ADF technology stack, all of these alternative frontends interact with the same model, making it easy to develop multiple frontend applications against the same data services.
The backend part consists of a business service layer that implements the business logic and provide some way of accessing the underlying data services. Business services can be implemented as API code written in Java, PL/SQL or other languages, web services, or using a business service framework such as ADF Business Components.
Under the business services layer there will be a data service layer actually storing persistent data. Typically, this is based on relational tables, but it could also be XML files in a file system or data in other systems accessed through an interface.
There are many different ways of building applications with Oracle Application Development Framework, but Oracle has chosen a modern SOA-based architecture for Oracle Fusion Applications. This brand new product has been built from the ground up as the successor to Oracle E-Business Suite, Siebel, PeopleSoft, J.D. Edwards and many other applications Oracle has acquired over the last couple of years.
If it is good enough for Oracle Fusion Applications, arguably the biggest enterprise application development effort ever undertaken by mankind, it is probably good enough for you, too.
ADF Controller (ADFc), implementing the features of a normal JSF controller, but extended with the possibility to define modular, reusable page flows. ADFc also allows you to declare transaction boundaries so one database transaction can span many pages.
You can see all of these in the following figure:
There are many ways of getting from A to B—this book is about travelling the straight and well-paved road Oracle has built for Fusion Applications. However, other routes might be appropriate in some situations: You could build the user interface as a desktop application using ADF Swing components, you could use ADF for a mobile device, or you could use ADF Desktop Integration to access your data directly from within Microsoft Excel. Your business services could be based on Web Services, EJBs or many other technologies, using the ADF binding layer to connect to the user interface.
Entity objects (EOs) takes care of object-relational mapping: Making your relational tables available to the application as Java objects. Entity objects are the base that view objects are built on, and all data modifications go through the entity object. You will normally have one entity object for every database table or database view your application uses, and this object is responsible for producing the correct SQL statements to insert, update or delete in the underlying relational tables.
The entity objects helps you build scalable and well-performing applications by intelligently caching records on the application server in order to minimize the load the application places on the database.
Like entity objects are the middle-tier reflection of database tables and database views, Associations are the reflection of foreign key relationships between tables. An association represents a connection between two entity objects and allows ADF to relate data in one entity object with data in another. JDeveloper is normally able to create these automatically by simply inspecting the database, but in case your database does not contain foreign keys, you can build associations by hand to tell ADF about the relationships in your data.
While you do not really need to make any major decisions when building the entity objects for the Proof of Concept, you do need to consider the consumers of your business services when you start building view objects—for example, what information you would display on a screen.
To provide data for your screens
To provide data for lists of values (LOVs)
The data handling view objects are normally specific for each screen or business service. One screen can use multiple view objects—in general, you need to create one view object for each master-detail level you wish to display on your screen. One view object can pull together data from several entity objects, so if you just need to retrieve a reference value from another table, you do not need to create a separate view object for this.
The LOV view objects are used for drop-down lists and other selections in your user interface. They will typically be defined as read-only and because they are reusable, you will define them once and re-use them everywhere you need a drop-down list on a specific data set.
The following figure shows an example of two ways to display the data from the familiar EMP and DEPT tables. The left-hand illustration shows a situation where you wish to display a department with all the employees of the department in a master-detail screen. In this case, you create two view objects connected by a view link. The right-hand illustration shows a situation where you wish to display all employees, together with the name of the department where they work. In this case, you only need one view object, pulling together data from both the EMP and DEPT tables through the entity objects.
Application modules encapsulate the view object instances and business service methods necessary to perform a unit of work. Each application module has its own transactional context and holds its own database connection. This means that all of the work a user performs using view objects from one application module is part of one database transaction.
Application modules can have different granularity, but typically, you will have one application module for each major piece of functionality. If your requirements are specified with use cases, there will often be one application module for each major use case. However, multiple use cases can also be grouped together into one application module – indeed, it is possible to build a small application using just one application modules.
Application modules for Oracle Forms
If you come from an Oracle Forms background and are developing a replacement for an Oracle Forms application, your application will often have a relatively small number of complex, major Forms, and larger number of simple data maintenance Forms. You will often create one Application Module per major Form, and a few application modules that each provide data for a number of simple Forms.
If you wish, you can combine multiple application modules inside one root application module. This is called nesting and allows several application modules to participate in the transaction of the root application module. This also saves database connections because only the root application module needs a connection.
The preferred way to build the user interface in an ADF enterprise application is with JavaServer Faces (JSF). JSF is a component-based framework for building web-based user interfaces that overcome many of the limitations of earlier technologies like JavaServer Pages (JSP).
In a JSF application, the user interface does not contain any code, but is instead built from configurable components from a component library. For your application, you will want to use the sophisticated ADF 11g JavaServer Faces (JSF) component library, known as the ADF Faces Rich Client.
It had long been clear to web developers that in a web application, you cannot just let each page decide where to go next—you need the controller from the MVC architecture. Various frameworks and technologies have implemented controllers (both the popular Struts framework and JSF has this), but the controller in ADF Task Flows is the first controller capable of handling large enterprise applications.
An ADF web application has one Unbounded Task Flow where you place all the publicly accessible pages and define the navigation between them. This corresponds to other controller architectures. But ADF also has Bounded Task Flows, which are complete, reusable mini-applications that can be called from the unbounded task flow or from another bounded task flow.
A bounded task flow has a well-defined entry point, accepts input parameters and can deliver an outcome back to the caller. For example, you might build a customer management task flow to handle customer data. In this way, your application can be built in a modular fashion—the developers in charge of implementing each use case can define their own bounded task flow with a well-defined interface for others to call. The team building the customer management task flow is thus free to add new pages or change the navigation flow without affecting the rest of the application.
In your task flows, you can define either pages or page fragments. Pages are complete web pages that you can run on their own, while page fragments are reusable components that you place inside regions on pages. An enterprise application will often have a small number of pages (possibly only one), and a larger number of page fragments that dynamically replace each other inside a region. This design means that the user does not see the whole browser window redraw itself—only parts of the page will change as one fragment is replaced with another. It is this technique that makes an ADF application seem more like a desktop application than a traditional web application.
On your pages or page fragments, you add content using layout components, data components and control components:
The layout components are containers for other components and control the screen layout. Often, multiple layout components are nested inside each other to achieve the desired layout.
The data components are the fields, drop-down lists, radio buttons and so on that the user interacts with to create and modify data.
The control components are the buttons and links used to perform actions in an ADF application.
The Proof of Concept serves two purposes:
If we return to the tunnel analogy, we need to demonstrate that we can drill all the way through the mountain, and measure our drilling speed.
The most important part of the Proof of Concept is that it goes all the way through the mountain – or in application development terms: All the way from the user interface to the backend data service and back.
If your data service is data in relational tables and you will be presenting it in ordinary fields and tables on the screen, the part of your proof of concept that demonstrates the technology is fairly straightforward.
However, if your data service is not just relational tables – if you are using Web Services or API code in C++, Java, or PL/SQL, you need to demonstrate that you can retrieve data from your data service, display it on the screen, modify it and successfully store the changes in the backend data service.
You might also have user interface requirements that require more advanced components like trees, graphs, or even drag-and-drop functionality for the end user. If that is the case, your proof of concept user interface needs to demonstrate the use of these special components.
There might also be other significant requirements you need to consider. Your application might have to use a legacy authentication mechanism like logging on to the database. Or it might have to integrate with legacy systems for authorization or customization. Or you might need to support accessibility standards allowing your application to be used by people with disabilities. If you have these kinds of requirements, you must evaluate the risk to your project if you cannot meet them. If they are critical to your project's success, you need to validate them in a Proof of Concept.
The short answer is yes. Hundreds of organizations have already followed Oracle's lead and built big enterprise applications using Oracle ADF. It is very straightforward to use the ADF framework with relational tables—the framework handles all the boring object-relational mapping, allowing you to concentrate on building the actual application logic.
You are likely to inherit at least some of the data model from a pre-existing system, but in rare cases, you will be building a data model from scratch for a brand new application. JDeveloper does allow you to build data models, but Oracle also has other tools (for example, SQL Developer Data Modeler) that are specialized for the task of data modeling. Either way, the ADF framework does not place any specific restrictions on your data model—any good data model will work great with ADF.
But your requirements are special, of course. Nobody has ever built an application like the one you are about to build—that is the essence of a project: To do something non-trivial that has not been done before. After all, if you did not need anything special, you could just pick up a standard product off the shelf. So you need to consider all your specific requirements to see if ADF can do it.
The answer is still yes. The ADF framework is immensely powerful as it is, but it also allows you to modify the functionality of ADF applications in myriad ways to meet any conceivable requirement. If you have to work through a data access API, for instance, you can override the
doDML() method in entity objects – allowing you to say: "Instead of issuing an UPDATE SQL statement, call this API instead." And if you need to work with existing web services for modifying data, you can create Data Sources from web services.
But you shoud not just take my word (or anybody else's word) for it. Building an enterprise application is a major undertaking for your organization, and you want to prove that your application can meet the requirements.
It depends mainly on three things: The size of the task, the complexity of the task, and the speed of development.
The size and complexity of the task is given by your requirements. It would be a rare project where all requirements are known exactly at the beginning of the project, but if you have the set of detailed requirements, you can make a good estimate of project size and complexity.
The speed of development will be the great unknown factor if ADF is new to you and your team. Using your previous development tool (for example, Oracle Forms), you were probably able to convert your knowledge of project size and complexity into development effort—but you don't yet know what your development speed will be with ADF.
Development speed varies over time with all tools as shown next. You will often discover that your initial development speed actually decreases slightly in the beginning as you move from using the tool with all default settings to actually figuring out all the options. Then comes a learning period, and finally the take-off point where real productivity starts:
You can use your initial development speed as an approximation of the productive development speed if you need to produce a rough estimate early in the project. However, if you do this, you must be aware that there will be a period of 1-2 months of lower productivity before you start climbing up to your full productive development speed.
The outcome of the proof of concept is not architecture in the form of boxes and arrows on a PowerPoint slide. David Clark from the Internet Engineering Task Force said, "We believe in running code" and that is what the Proof of Concept should deliver in order to be believable and credible to developers, users, and management: Running code.
If you want to convince your project review board that ADF is a viable technology, you need to bring your development laptop before your project review board and perform a live demonstration.
Additionally, it is a good idea to record the running proof of concept application with a screen-recording tool and distribute the resulting video file. This kind of demo tends to get watched in many places in the organization and gives your project visibility and momentum.
You are a developer with DMC Solutions—an IT company selling a system for Destination Management Companies (DMC). A DMC is a specialized travel agency, sometimes called an "incoming" agency, and works with clients in the country where it is based.
On an average packaged tour, you will probably not enjoy the services of a DMC. But if you manage to qualify for a company-paid trip to some exotic location, your company is likely to engage the services of a DMC at the destination. And if you have ever participated in a technology conference, a DMC will normally be taking care of transfers, dinners, receptions, and so on.
The system that DMC Solutions is selling today is based on Oracle Forms, and the sales force is saying that our competitors are offering systems with a more modern look and a more user-friendly interface. Your mission, should you choose to accept it, is as follows:
Prove that ADF is a valid choice for a modern enterprise application
Set up a project to build the next generation of destination management software (the XDM project)
Your manager has dusted off the specification binder for the existing system and asked you to implement Use Case 008 Task Overview and Edit. Additionally, he wants you to implement the newly specified Use Case 104 Person Task Timeline.
These two use cases represent basic application functionality (the ability to search and edit data) as well as a graphical representation of time data—something new that was not possible in Oracle Forms.
This screen allows the user to search for tasks by responsible person, program or a free-text search. Data can be updated and saved back to the database:
For simplicity, we will not implement the application menu, but instead just have a button labeled Timeline that invokes UC104.
The destination management system works with Events (such as "Oracle OpenWorld 2011"). Within each event, there will be a number of programs (for example, "VIP Pharma Customers"). One person is responsible for each programme. Within a programme, there will be a number of Tasks that point to standard elements from the element catalog. Examples of elements could be a Limo transfer, a dinner, an excursion, and so on. Each task will be assigned to exactly one person.
The following diagram shows just the parts of the (much larger) existing data model that we need for the Proof of Concept:
If you want to follow along with the proof of concept, building it in JDeveloper on your own workstation, you can download SQL scripts for creating the relevant part of the data model from the book companion website at www.enterpriseadf.com. This script also contains some anonymized data.
Oracle JDeveloper is Oracle's strategic development tool and the only tool with full support for ADF Development. While Oracle will continue to support NetBeans and offer a lot of functionality for Eclipse, they have also clearly stated that JDeveloper is the tool of choice for building Oracle ADF applications.
JDeveloper is freely available for download and use from the Oracle Technology Network (otn.oracle.com), normally through a download link from the front page. If you do not already have a free oracle.com account, you will have to create one.
The illustrations in this book show JDeveloper 11g Release 1, version 188.8.131.52.0, but since JDeveloper is a rapidly developing product, there might be a newer version out by the time you read the book. However, the basics have not changed over the last couple of years, and you should be able to immediately find the dialogs and options you are looking for. In addition, since Oracle has built a very large application based on this version, you can be sure that there will be a simple migration path moving forward.
The following steps describe how to create a workspace for an ADF enterprise application—if you want to use this chapter as a hands-on exercise, use the suggested values in each step:
Choose File | New. In the New Gallery dialog box, chose Applications (under General) and choose Fusion Web Application (ADF). JDeveloper offers you many other types of applications, including Java Desktop Application (ADF), but you want a Fusion Web Application.
Give your application a name (for example, XdmPoC), choose where to put it in the file system (you can leave the default of
C:\JDeveloper\mywork\XdmPoC), and provide an Application Package Prefix. Use your organization's Java prefix, followed by your project abbreviation (for the proof of concept, use
Java Package prefix
Traditionally, package names start with your organization internet domain with the elements reversed. So, if your company domain is mycompany.com, your package names would all start with
com.mycompany. However, some organizations (like Oracle) feel that their names are sufficiently unique that they don't need to include the first
If your organization has ever used Java before, your Java package prefix has probably already been chosen and documented somewhere. Ask around.
You can simply click Next through the rest of the wizard.
This will create you a new application containing the two projects Model and ViewController. In the main window, JDeveloper will show you the Application Checklist as shown next:
The application checklist actually gives a great overview of the steps involved in building an ADF application, and if you click the little triangles to expand each step, you will see links to the relevant JDeveloper functionality for that step, together with links to relevant places in the documentation. It even has checkboxes that you can check as you have completed the different phases in developing your ADF application.
JDeveloper contains a lot of different windows and panels for different purposes. The above screenshot shows the most commonly used panels, but you can toggle each of the many panels on and off using the View menu.
If you have not worked with JDeveloper before, please take a moment to familiarize yourself with the typical panels shown previously:
In the middle is the main window where you will be configuring business components, designing pages, and writing code.
Below the main window is the Log window showing system messages, compiling results, deployment messages and many other types of information.
In the top left corner is the Application Navigator, where you can see all of the components in your workspace in a hierarchical structure.
In the bottom left corner is the Structure panel. This important panel shows the detailed structure of the component you are working on. When you, for example, are working on a page in the main window, this panel will show a tree with all the components on the page.
In the top right corner is the Resource Palette showing connections to application servers, databases, and so on. The Component Palette will also appear as a separate tab in this location when editing a page, allowing you to select components to add to the page.
In the bottom right corner is the Property Inspector where you can inspect and set properties on the currently selected item.
You can rearrange these panels to your liking by grabbing the tab at the top of each panel and dragging it to a new location or even drag it out of JDeveloper to make it a floating window. This can be useful if you have multiple monitors. If you accidentally change the layout to something you do not like, you can always choose Window | Reset Windows to Factory Settings.
Before you start working with JDeveloper, you should set the preferences (under Tools | Preferences). There are literally hundreds of references to set, most of which will not have any meaning to you yet. That's OK—the defaults are mostly fine.
One setting that you should change is the business package naming. Open the Business Components node and choose Packages. Set values for Entity, Association, View Object, View Link, and Application Module as shown next:
These settings tell JDeveloper to place different types of business components in separate sub packages for an easier overview when you have many components. These are just defaults to create a good starting point—as you build your application, you might decide to move your business components and classes to other packages, and JDeveloper makes this safe and easy.
You should also set Encoding on the Environment node to UTF-8 to have all your files created in UTF-8 for maximum cross-platform portability. (If you're on Microsoft Windows, this value is probably set to a default Windows character encoding.)
Once the data model is in place, the next step is to build the ADF Business Components. The description in this book is fairly brief and assumes that you have worked a little bit with ADF before, for example, by going through a basic ADF tutorial on the Oracle Technology Network website (otn.oracle.com). You can find links to some relevant tutorials on the book companion website www.enterpriseadf.com.
For the Proof of Concept, we will leave all business components in the default location: The Model project in the Proof of Concept application workspace. However, when building a real-life enterprise ADF application, you will be splitting up your application into multiple application workspaces and using ADF libraries to collect these into the master application. Working with smaller workspaces enforces modularity in the code, makes it faster for the developer to find what he's looking for, allows faster checkouts from source control – and JDeveloper also runs faster and better when not handling thousands of objects at the same time.
We will return to the proper structuring of workspaces in Chapter 3, Getting Organized.
As you might have noticed from the application checklist, the first step after Plan your Application is to create a connection to the database schema where your application tables reside. Simply choose File | New and in the New Gallery choose Connections (under General) and then Database Connection.
In the Create Database Connection dialog, give your connection a name and provide username, password, and connection information. If you are working locally with the small, free version of the Oracle Database (Oracle Express Edition), you choose the thin driver, enter localhost as Host Name, leave JDBC Port at the default value of 1521 and enter xe in the SID field. A default local installation of other database editions typically has the value orcl for SID, but is otherwise identical. If you are running against a remote database, ask your database administrator for connection information. Click Test Connection to check that you have entered everything correctly and then OK:
For the Proof of Concept, we will only be building entity objects for the tables that need to meet the requirements of the two use cases. To start building, select the
Model project and choose File | New or right-click on the
Model project and choose New from the context menu.
Make sure you select the
Model project before you start creating business components. A default Fusion Web Application (ADF) workspace comes with two projects: A
Model project for the business components and a
ViewController project for the user interface.
In the New Gallery, choose ADF Business Components (under Business Tier) and then Entity Object. Give the entity object a name (use the name of the corresponding table in mixed case, singular form, for example
person) and select the corresponding schema object. You can either write the database object name in the field or click Browse to query the database.
When you start your enterprise application development project in earnest, you need naming standards for everyone to follow. We'll return to naming standards in Chapter 3, Getting Organized.
In Step 2 of the wizard, just click Next to create entity object attributes for every column in the database. In ADF, there is no overhead at run time from having attributes for unused columns—when the ADF framework issues a
SELECT statement to the database, it retrieves only the attributes that are actually needed by the view object.
In Step 3 of the wizard, you can define the entity attributes in detail. One thing that often needs to be changed here is the type for primary key columns. If the table has a numeric ID column and a database trigger that sets this value when the record is created in the database, you need to set the Type to DBSequence:
Notice that the ADF framework has now changed the values in the right-hand side of the dialog box: Updatable is now set to While New, and in the Refresh After box, the checkbox for Insert is now checked. This means that the entity object will automatically retrieve the primary key value created by your trigger. If you are using an Oracle database, ADF will use the
RETURNING feature in Oracle SQL to get the ID back as part of the insert (without having to make a second round-trip to the database).
You do not have to make any changes in steps four through six, so you can simply click Finish here to close the wizard and create your entity object.
For the proof of concept, you need to follow the previous procedure to create entity objects for the following tables:
ELEMENTS (doesn't need DBSequence chosen)
When you are done, the Model project in the Application Navigator should look like this:
When you have created the entity objects, you will normally find that JDeveloper has automatically discovered the relationships between them, based on the foreign keys defined in the database.
If you have configured JDeveloper Preferences as recommended in the introduction, all of the associations can be found in the application navigator under
assoc as shown in the previous Figure.
To determine which view objects to build, you must look at the screens you need. This allows you to determine both the data you need to present and the value lists you will need.
Looking at the Task Overview screen (UC008), we see that all data is at the same level (no master-detail), so we will just need one Tasks view object to display the data.
Additionally, we'll need three value lists:
Programmes (for the Programme drop-down list for search)
Persons (for the Responsible drop-down list for search)
Services (for the Service drop-down list in the data table)
Looking at the Person Task Timeline screen (UC104), there are clearly no value lists. Because data is presented graphically, it is not immediately obvious whether the data contains any master-detail relationship. To determine if that is the case, consider how you would display the same information in ordinary fields and tables. Such a screen might show:
A number of tasks assigned to that person
This shows us that there is actually a master-detail relationship hidden here, so we need one view object for Persons, one view object for their Tasks, and a view link connecting the two.
To create a view objects for Persons, choose File | New, and in the New Gallery choose View Object. It is a good idea to give your view objects a name that indicates their intended usage as lists of values—for the list of persons, use the name
PersonLOV. Leave the data source at Updatable Access through Entity Objects.
Always use Entity Objects
In ADF 10g and earlier, the recommendation was to use Read-Only Access through SQL Query when you did not need to change the data. In ADF 11g, the benefit from caching that entity objects offer outweighs the slight performance benefit from executing SQL directly. The recommendation is, therefore, to always access data through entity objects.
In step 2 of the wizard, choose the
Person entity object and move it to the box on the right. You can remove the checkmark in the Updatable box, since we will only be using this view object for the drop-down list:
In step 3 of the wizard, move the fields you want to the right-hand side—note that the primary key attribute will always be included:
In step 5 (Query), you define the ordering of records by entering initials in the Order By field. Then click Finish to create the view object.
Repeat this procedure to create the two other value list view objects:
ProgrammeLOV(based on the
Programmeentity object, select the attribute called
name, order by
ServiceLOV(based on the
Elemententity object, select the attribute
description, order by
To create a view object for tasks, look at the Task Overview and Edit page (UC008) and at the data model. You will notice that we need fields for date and time, text, start where, flight number, end where, number of passengers, and service. All of this data comes from the
TASKS table through the
Task entity object.
Create a new view object (
AllTasksVO), leaving the data source at Updatable Access through Entity Objects. In step 2 of the wizard, choose the
Task entity object and move it to the right-hand side. Because we will actually be updating data through the
AllTasksVO view object, we leave the check mark in the Updatable checkbox.
Note that in the Available box on the left-hand side, all attributes are shown in alphabetical order, not in the order you placed them in the entity objects or the order they have in the database table.
Click Next two times and choose to order by
start_date. Then click Next to get to Bind Variables (Step 6).
Bind variables are placeholders in your SQL that you fill with values at run time. The ADF framework enforces the good practice to always use bind variables when you need to change the
WHERE condition of a query. You should never simply concatenate values into an SQL statement; if you do, the database cannot tell that it already knows the SQL statement and will waste time parsing it again, and a malicious user could potentially insert extra statements into your SQL.
Looking at the search box at the top of the screen sketch, you can see that we need to limit the tasks displayed by responsible person, programme, and text. Use the New button to create three bind variables called
pText. You can leave the other settings in this step of the wizard at their default values.
When you're done, click the Back button to return to step 5 of the wizard, and add a
WHERE clause that uses the bind variables. It should look like this:
Downloading the example code
You can download the example code files for all Packt books you have purchased from your account at http://www.PacktPub.com. If you purchased this book elsewhere, you can visit http://www.PacktPub.com/support and register to have the files e-mailed directly to you.
(:pResponsible is null or PERS_ID = :pResponsible) and (:pProgramme is null or PROG_ID = :pProgramme) and (:pText is null or upper(TEXT) like '%' || upper(:pText) || '%')
When you are done entering the
WHERE clause, click on the Test button to verify that your SQL is valid.
In this case, we allow null values for the bind variables, so the SQL statement has to contain an
OR branch handling this case. We are converting both the database
TEXT column and the
pText bind variable to upper case to achieve case-insensitive matching, and concatenating a wildcard character before and after the parameter value to search for occurrences of the search text anywhere in the database value.
Point-and-click Where clauses
You can also define Named View Criteria on your view objects (on the Query sub-tab). These allow you to build a where clause by pointing and clicking. Read about named view criteria and the associated
af:query component in the online help.
When you click Finish, the
AllTasksVO view object is created and appears in the application navigator.
However, we are not quite done with the view object—we still need to define which data elements use lists of values. You might remember from the page layout illustration that Service was rendered as a drop-down list box. Double-click on the
AllTasksVO view object to edit it and choose the Attributes sub-tab. Choose the
ElemKey attribute and then click on the green plus sign next to the heading List of Values. The Create List of Values dialog appears:
In this dialog, click the green plus sign to add the List Data Source. Choose the
ServiceLOV view object and then
ElemKey as List Attribute.
Since we do not want to display the actual key value (
ElemKey) to the user, you should click on UI Hints tab, and move the
Description attribute to the right-hand box. Uncheck the Include No Selection checkbox, and then click OK.
The Attributes tab also allows you to define some hints to the user interface components about rendering the component. Double-click the
StartDate attribute and choose the Control Hints sub-tab. Set the Label Text to
Start time, set Format Type to Simple Date and in the Format field, enter the format mask
The date format string used here is Java
SimpleDateFormat—not the SQL data format strings you might be used to from the database.
Click OK and then set a Label Text for the remaining elements, referring to the user interface sketch for UC008 (Format is only used for date and number objects).
To create an application module for tasks, choose File | New and then Application Module. Give the application module a name (for example,
EditTaskService). In step 2 of the wizard, expand the tree in the left-hand side and shuttle the
AllTasksVO to the right-hand side, together with the
ProgrammeLOV that we need to create the search criteria value lists. This is all you need to do, so you can simply click Finish to close the wizard.
Now you can verify that your application module works the way you expect it to. In the application navigator, right-click on the
EditTaskService application module node (the icon that looks like a little suitcase), and choose Run from the context menu. This will start the Business Components Tester where you can work with all of the view objects that are part of your application module.
Always test your business components using the Business Components Tester before you start using them in pages. Whenever your page does not run the way you expect, always use the Business Components Tester to determine if the error is in the frontend or the backend part of the application.
Double-click on the
AllTasksVO1 view object. A pop-up dialog appears, allowing you to assign values to all the bind variables defined in the view objects. To begin, just click OK to leave all bind variables at the value
Here, you can page through the existing data as well as insert and delete rows using the green plus and the red cross symbol. Click on the Edit Bind Variables button (to the right of the toolbar, with the little pencil icon) to change bind variable values and notice how data is filtered.
We already have a view object showing persons, but this view object only contains initials (because it was intended for the Persons drop-down in UC008). We could create a new persons view object for UC104, but we will change the existing view object instead.
First, you need to change the name of the view object from
PersonsVO to reflect that it is no longer just used for a list of values. Changing name or package for existing objects is called refactoring, and JDeveloper makes this easy. Simply right-click on the
PersonLOV view object and choose Refactor | Rename from the context menu, JDeveloper will change the name of the object and automatically update all references to it:
Next, the view object needs some more attributes. To add these, open the view object by double-clicking on it and choose the Attributes sub-tab. Click the little triangle next to the green plus sign above the attributes and choose Add Attribute from Entity. Do not just click the plus sign—you need to select the little triangle to get access to the Add Attribute from Entity menu item you need:
In the Attributes dialog, add the
LastName attributes to the Selected list. Then select the new
FirstName and click the little pencil icon to edit the attributes. Under Control Hints, set a Label Text. Repeat for
Then create another view object, giving it the name
ScheduledTasksVO. In step 2 of the wizard, move the
Task entity object to the right-hand side. Since we will not be updating tasks either, you can remove the checkbox in the Updatable field here as well. In step 3 of the wizard, you only need to select the
EndDate attributes – note that the
TaskId primary key attribute is automatically added.
In step 5 of the wizard, we need to add a
WHERE clause so that the view object will only show tasks with both a start and an end date. Enter the following
start_date is not null and end_date is not null
Then click Finish.
Since there is a master-detail relationship between persons and tasks, we also need to create a view link. Select File | New and then View Link. Give your view link the name
In step 2 of the wizard, we need to define the relationship between the two view objects. These are connected by the foreign key
PERS_TASK_FK that defines the connection between a person and the tasks assigned to that person. Expand the
PersonsVO node on the left and choose
PersTaskFkAssoc as the left-hand side of the link. On the right, expand the
ScheduledTasksVO node and again choose
PersTaskFkAssoc, this time as the right-hand side of the link. Then click Add. You see the source and destination attributes added at the bottom of the dialog box:
You do not need to change any of the remaining settings in this wizard, so you can simply click Next and Finish to close the dialog box.
One or two lumps?
On one hand, each application module uses a database connection, and your database administrator will tell you to keep this number down. On the other hand, you want to modularize your application so that each piece of functionality is completely developed and delivered by one team—this calls for multiple application modules. We'll return to the discussion of the proper number of application modules in Chapter 3, Getting Organized.
In step 2 of the wizard, first move the
PersonsVO to the right-hand side. Then select the
Persons1 view object instance on the right and the node ScheduledTasksVO via PersonTaskLink on the left, and click the > button to move
ScheduledTasks to the right-hand box:
Note the difference between choosing
ScheduledTasksVO on its own and choosing
ScheduledTasksVO as a child of
PersonsVO. If you choose the view object as a child of another view object, the ADF framework will automatically implement the master detail relationship – the view object will only display the records that are children of the current record in the parent (master) view object. If you choose the view object on its own, it will not have any relationship to the master view object and will simply display all child records.
Then click Finish to close the wizard.
Run your new application module in the business components tester. In the left-hand side, you will see the master view object, the view link, and the detail view object. Double-click on the view link to see master and detail records together. When you use the navigation buttons at the master level, you will see different detail records displayed:
Pages or fragments?
As mentioned in the section on ADF architecture, an application can use either pages or page fragments. The Proof of Concept uses pages for simplicity, while the professional Proof of Concept we will be building in Chapter 6, Building the Enterprise Application will use page fragments.
For the proof of concept, we will implement one bounded ADF task flow. Select the
ViewController projects and then choose File | New. You might notice that the New Gallery looks differently now. That is because the
ViewController project is active, and this project uses different technologies.
Under Web Tier, choose JSF and then ADF Task Flow. Give your task flow a name (for example,
xdm-poc-flow), make sure the Create a Bounded Task Flow checkbox is checked and the Create with Page Fragments checkbox is not checked. Then click OK. You will see a blank task flow diagram in the JDeveloper main window.
In the component palette in the top right corner of the JDeveloper window, expand the Components heading and drag in a View component. Give it the name
taskPage. Drag in another View components and give it the name
Then drag in a Control Flow Case components and drop it on the
taskPage. Move the cursor to the
schedulePage and click. This establishes a control flow from the
taskPage to the
schedulePage. The cursor will be placed in a box in the middle of the line. Type
goSchedule in this box and press Return. Drop another Control Flow Case onto the
schedulePage and drag it to the
taskPage. Give this control flow the name
This defines the two pages that we will be using in the proof of concept, as well as the possible navigation between them. Your task flow should look like this:
Note the green halo behind the
taskPage. That indicates that this is the default activity—the first screen presented to the user when the task flow is run. You can set another page as the default activity by right-clicking on it and choosing Mark Activity and then Default Activity.
You will notice that both the pages in the task flow diagram have a little yellow exclamation mark. That indicates that the pages do not actually exist yet, they are only defined as placeholders in the task flow.
To create the tasks page, double-click on the
taskPage icon in the page flow diagram. The Create JSF Page dialog appears. For the proof of concept, we start from blank pages (make sure Blank Page is selected) – but when actually building the real application, we will, of course, be using page templates. Click OK to create and open the page.
If you drag in a component from the component palette, it is not bound to any data control. This means it has no connection to the data in the ADF business components.If you drag in the data control from the data control palette, JDeveloper will automatically present you with a menu of components that you can drop onto the page. If you use this approach, the dropped component is automatically bound to the data control you dragged in.
To add components to the task page, find and open the Data Controls panel in the left-hand side of the JDeveloper window. You should see two data controls, corresponding to the two application modules you have created in the Model project:
However, before we start dragging in data controls, we need to place a layout component on the page to control where items are to be placed. If you come from a 4GL background (like Oracle Forms), you might be used to pixel–precise placement of items. In JSF, on the other hand, the placement of components is controlled by special layout components. This has the advantage that the layout components can arrange, shrink, and expand the components they contain in order to make the best use of the available screen area. The disadvantage to this approach is that it takes a little while to learn to use the right layout components.
taskPage, we start with a Panel Stretch Layout. Find this component in the Component Palette in the right-hand side of the JDeveloper window (under the Layout heading) and drop it on the page:
It is a good idea to use a "stretchable" layout component as the outer layer to ensure that your application will utilize the entire browser window.
If you expand the Panel Stretch Layout in the Structure Panel at the bottom right of the screen, you will see that it shows a folder-like node called Panel Stretch Layout Facets, and under that additional folder-like nodes called bottom, center, and so on. Many layout containers contain these containers (called facets) that you can place your content in:
If you refer back to the screen design earlier in this chapter, you see that the Panel Stretch Layout matches our requirements: We can place the search criteria on top (in the facet called top), the actual data in the middle (in the facet called center), and some buttons at the bottom (in the facet called bottom). We do not need the start and end facets, but don't have to worry about them—facets without content are not shown at run time.
We will start with the actual data, which we will present using an ADF Table component. Open the Data Controls panel on the right, and then open the
EditTaskServiceDataControl node. You see the
AllTasksVO1 view object. Grab the entire view object and drag it onto the center facet. When you drop a data control onto a page, JDeveloper shows a context menu asking you which user interface elements you want to create and bind to the data control. In this case, select first Table and then ADF Table from the context menu. The Edit Table Columns dialog appears:
In this dialog box, you can remove the columns that you do not need, and re-order the columns if necessary. You will see that JDeveloper has automatically selected an appropriate UI component—ADF Input Date for date attributes or ADF Select One Choice for attributes where a value list has been defined. For the tasks table, you only need to delete the
TaskId column and click OK. You will see a table component in the middle of your page.
Finally, you need to tell ADF which column gets to use any extra space on the screen. Remember that we started with a Panel Stretch Layout, which will automatically stretch the components it contains – but a table component does not stretch until you specify which column should expand to use any extra space.
First select the Text column and make a note of its Id property (look in the Property Inspector in the lower right corner of the JDeveloper window) – it will be something like
c3. Then select the entire table (either in the Design window in the middle of JDeveloper or in the Structure Panel at the lower left). The Property Inspector will now show the properties of the table. Expand the Appearance node and set the ColumnStretching property to the name of the
Text column (for example, column:c3).
Even though we do not have the search functionality built yet, it is about time that we run some code. Simply right-click anywhere on the
taskPage page and choose Run from the pop-up menu. In the log window at the bottom of the JDeveloper window, you can see the WebLogic server starting up. This will take a while.
Once WebLogic has started, a browser window will open, showing your data. Resize the window, checking that the Text column expands and contracts.
You might want to change the initial column size for some of the columns—to do this, in JDeveloper select an af:column element in the main window or the structure panel and change the Width value (under the Appearance heading) in the Property Inspector.
JDeveloper makes it very easy to create items that represent bind variables. If you expand the
AllTasksVO1 node, you will see all the attributes in the view object, as well as a node called Operations. If you expand the Operations node, you will see a number of standard operations that all view objects offer. One of these operations is ExecuteWithParams, and if you expand this fully, you will see the bind variables defined in the view object (
To control the layout of the search criteria, first add a Panel Group Layout (from the Layout Component Palette) to the top facet.
The first criterion is the person responsible for the program. To add this criterion to the page, drop the
pResponsible parameter onto the Panel Group Layout in the top facet. When you release it, a context menu appears. From this menu, select Single Selection and then ADF Select One Choice. The Edit List Binding dialog appears:
Leave Base Data Source at variables and click Add to add a new List Data Source. Choose the Persons view object as the source. Select
PersId as List Attribute (the value that is bound to the variable). At the bottom of the dialog, choose Initials in the Display Attribute drop-down and set "No Selection Item" to Blank Item (First of List), then click OK.
In the Property Inspector at the lower right, set the Label property for this drop-down to Responsible.
The second criterion is the name of the program. From the list of parameters (under ExecuteWithParams), drag the
pProgramme parameter onto the Panel Group Layout next to the
pResponsible drop-down and again drop as Single Selection, ADF Select One Choice. Again leave the Base Data Source unchanged and click on the Add button next to List Data Source. Choose the Programme view object as the data source for this drop-down list, and set List Attribute to
ProgId. Then set Display Attribute to Name and again set "No Selection" Item to Blank Item (First of List). Then click OK. In the Property Inspector, set the Label property to
The last criterion is the search text that is matched with the
TEXT column. Drop the
pName parameter next to the
pProgramme parameter and this time drop it as Text, ADF Input Text w/ Label. Set the Label property to
If you cannot see all the components on the screen, you can grab the bottom edge of the top facet where you added the items, and pull it down.
Finally, you need to create a button that actually executes the search. To achieve this, simply drag the ExecuteWithParams operation (the green gearwheel icon) onto the page inside the Panel Group Layout, next to the three search criteria. Because this is not a data element, but an operation, your drop choices are different. Choose Operation, ADF Button. The default text on the button is the name of the operation (
ExecuteWithParams). In the Property Inspector panel in the bottom-right corner of the JDeveloper window, change the
Text property to
Your objects are probably placed below one another right now. To change this, select the panel group layout that you dropped in the top facet. It can be a bit hard to pick the exact right layout or input component in the design view of the page in the center of the JDeveloper window. Instead, look at the Structure panel at the bottom left of the JDeveloper window:
With the panel group layout selected, look at the Property Inspector in the bottom right-hand corner. Change the Layout property to horizontal to align the search criteria and the button horizontally. If you resized the top facet to see everything, you can make it smaller again.
To make sure we got everything correct, let us run the page again. Right-click anywhere on the
taskPage page and choose run from the pop-up menu. Because WebLogic is already started, your page should appear quicker this time.
Play around with the drop-down lists and try different values in the text search field. Each time you click on the search button, the table should update accordingly.
We can now retrieve data from the database and edit it on the screen. However, we have not yet created a way to commit these changes to the database. For this, we will choose an operation at the application module level. The ExecuteWithParams operation belonged to the
AllTasksVO1 view object. But if you collapse all the view objects, you will see that the
EditTaskServiceDataControl also has an Operations node with operations Commit and Rollback:
Before you drag these operations onto your page, drop a Panel Border Layout on the bottom facet of the page. If you refer back to the sketch of the user interface, you will see that we need some buttons (OK and Cancel) in the left side, and the Timeline button on the right. Because a Panel Border Layout has a number of facets along the edge, this is a good component to ensure this layout. However, since it does not offer a way to control orientation, we have another component to arrange the OK and Cancel buttons.
Use the Structure panel for arranging layout containers
When you have multiple containers within one another, drop them onto the structure panel at the lower left of the JDeveloper window. This part of the JDeveloper UI will present layout components in a tree structure, making it much easier to control where you drop components.
In the structure panel, expand the af:PanelBorderLayout component you just added, and drop a Panel Group Layout on the left facet. In the Property Inspector at the lower right in the JDeveloper window, set the Layout property of this Panel Group Layout to horizontal.
Then drag the Commit and Rollback operations from the Operations node of
EditTaskServiceDataControl onto this Panel Group Layout and drop them as ADF Buttons. The Structure Panel should look as shown next. For both buttons, use the Property Inspector to set the text (to
Cancel), and delete the content of the Disabled field (under Behavior) to ensure that both buttons are always active:
Run the page again, checking that your buttons are placed where you expect. Then make some changes to the data, and click OK. Use a database tool to verify that your changes are committed to the database, or close the browser and run the application again to verify that your changes are actually stored.
We will get back to the navigation button when we have built the other page.
To create the scheduled tasks page, go back to the page flow. If you have closed the page flow window, you can find it again in the application navigator at the top-left in JDeveloper under Web Content, Page Flows. Double-click on the
schedulePage icon and then OK to create the page.
The component we need to implement the graphic representation of tasks assigned to persons is a Gantt chart of type Scheduling.
Under Data Controls, open the
ScheduledTaskServiceDataControl node and drag the Persons view object onto the center facet and drop it as Gantt | Scheduling. The Create Scheduling Gantt dialog appears:
Set the fields in this dialog as follows:
Resource Id: PersId
Tasks Accessor: ScheduledTasks
Task Id: TaskId
Start Time: StartDate
End Time: EndDate
Under Table Columns, remove the extra columns, leaving only
LastName. Then click OK. You will see a graphical representation of a scheduling Gantt chart.
Click in the chart and then go to the Property Inspector to set values for the StartTime and EndTime properties (for example,
2011-10-31). The Gantt component does not automatically scale to the dates used, and making it do so involves a bit of code – we choose to leave this functionality out of this Proof of Concept.
Right-click anywhere on the page and choose Run to see the actual values in the browser, and play around with the capabilities of the Gantt chart component. We are using it in default configuration here, but there are many customization options. Refer to the help (Press F1 with the Gantt component selected) or the documentation for a full description of this powerful component.
taskPage and look in the Structure Panel. Find the facet called Right under the af:panelBorderLayout (right under the af:panelGroupLayout containing the
Cancel buttons). Drag a Button component from the Component Palette at the top right and drop it onto this facet. In the Property Inspector, set the Text property to
Timeline, and under Action, select goSchedule.
Finally, we need to drop a Spacer layout component from the Component Palette directly onto the af:panelBorderLayout. Your Structure Panel should now look like this:
The reason we need the
spacer component is that ADF automatically optimizes the page and does not show any facets that do not have content. So if the Panel Border Layout does not contain anything, the middle part is not shown, and the Left and Right facets are right next to each other. With the spacer in place, the central part will take up all the available space, pushing the Left facet left and the Right facet right.
Now open the
schedulePage. Drag a Panel Group Layout onto the bottom facet and set the Layout property to horizontal and the Halign property to right. Then drop a Button onto the Panel Group Layout, set the Text to
Overview and Action to
To test the navigation, you can now run the entire task flow. Open the
xdm-poc-flow task flow, right-click anywhere on the page and click Run. Your application starts with the default activity (
taskPage). Check that you can use the
Timeline button to go to the
schedulePage, and the Overview button to go back.
In this chapter, we discussed what a Proof of Concept is, and why you need it. You got a very brief introduction to the ADF architecture, and saw or built a Proof of Concept application using the entire ADF technology stack, including the advanced Gantt chart component.
You are ready to go to your boss and demo what you can do with ADF. If he agrees that it seems like ADF is the right tool, your next step is to produce an overall design and estimate how long it will take to build the next generation of destination management software. This is the topic of Chapter 2, Estimating the Effort.