Oracle® Database Lite Developer's Guide Release 10.3 Part Number E12090-02 |
|
|
View PDF |
The following sections use a tutorial to describe how to create, deploy, and use an ADF/BC4J application:
Section 12.5, "Publish and Configure the ADF/BC4J Application from the Mobile Manager"
Section 12.7, "Run the ADF/BC4J Application on the Mobile Client for Oracle Lite WEB OC4J"
The Oracle Application Development Framework (Oracle ADF) is an end-to-end a application framework that builds on J2EE standards and open-source technologies to simplify and accelerate implementing service-oriented applications. If you develop enterprise solutions that search, display, create, modify and validate data using Web, wireless, desktop or Web services interfaces, then Oracle ADF can simplify your job.
Oracle Business Components for Java (BC4J) is a part of the Oracle JDeveloper IDE (Integrated Development Environment), and provides Java developers with tools to create and manage reusable Java components.
ADF/BC4J offers a standards-based, server-side Java and XML framework for developers. You can build and deploy reusable business components for high performance Internet applications, such as e-commerce and business-to-business systems. Applications, which are created using ADF/BC4J, comprise five basic framework components: Entity Objects, Associations, View Objects, View Links, and Application Modules. Each of these components is interrelated to the other components, which enables you to establish views into database tables. You can combine, filter, and sort data as needed.
When used in application development, ADF/BC4J automatically generates database oriented components, so that you can focus on the business logic instead of on database related components.
The ADF/BC4J sample application used in this tutorial maintains employee details and stores all items in a relational database.
Ensure that the computer you are using for your development meets the requirements specified in this section. Table 12-1 lists configuration and installation requirements for the development computer.
Table 12-1 Development Computer Requirements
Requirement | Description |
---|---|
Windows User Login |
The Windows login user must have Administrator privileges on the development computer. |
Installed Java Components |
|
Installed Oracle Components |
Mobile Server or Mobile Development Kit (Oracle Database Lite CD-ROM) Oracle 9i or higher with the default Master schema installed. Oracle10g JDeveloper Release 3 (10.1.3.0.4) Studio. Studio Edition Version 10.1.3.0.4.3673 BUILD JDEVADF_10.1.3_NT_060125.0900.3673 Note: This tutorial is written and certified using the above-mentioned version of Jdeveloper. |
When using ADF/BC4J, you need to define the database connection in both JDeveloper and Oracle Database Lite, which is shown in the following sections:
Section 12.2.1, "Creating a Database Connection to Oracle Database"
Section 12.2.2, "Specify The Connection To The Oracle Lite Database"
Java Database Connectivity (JDBC) is a standard application-programming interface (API) that is used for connecting a Java application to relational databases. JDeveloper uses a connection navigator to maintain connection information for your application. The connection navigator makes it easy to create, manage, and test database connections. If you have not already established a connection to the database, then perform the following steps:
Connect to Oracle Database as the master
user and execute the adf_main.sql
script, which is located in the <ORACLE_LITE_HOME>
\Mobile\Sdk\wtgsdk\src\bc4jtutorial
directory.
Start Oracle10g JDeveloper Release 3 (10.1.3) Studio.
Select the Connections tab on the Applications Navigator.
Note:
If the Connections tab is not showing, choose View -> Connection Navigator from the JDeveloper main menu.Figure 12-1 JDeveloper Connection tab on the Connection Navigator
Right-click the Database
folder and select New Database Connection. This starts the Create Database Connection Wizard.
Figure 12-2 JDeveloper Connection tab on the Connection Navigator, New Database Connection
Perform the following in the Create Database Connection Wizard:
Review the information on the Welcome page and click Next.
In the Connection Name field, enter adfconn
. Click Next.
Figure 12-3 Connection Wizard - Step 1 of 4: Type Panel
On the Authentication page, enter master
/master
for the username/password fields. Select Deploy password.
Figure 12-4 Connection Wizard - Step 2 of 4: Authentication Panel
On the Connections page, the default values for the connection is as follows:
Driver: thin
Host name: <mobileserver_host>
JDBC Port: <mobileserver_port>
SID: <repository_SID>
Click Next and Test Connection. One of the following occurs:
If the database is available and the connection details are correct, then Success!
displayed in the Status window.
If an error occurs, verify the connection settings. Click Back to make any necessary changes, and then retest the connection.
If the connection is successful, click Finish to complete the connection.
Note:
Leave the fields set to these default values.The Oracle Database Lite connection is used for synchronization between the two databases—the back-end Oracle database and the local Oracle Lite database. Once you specify the connection within JDeveloper, then modify the application to use this connection.
For this example, we will create the WTGJdbc
connection, which uses the oracle.lite.web.WTGJdbcDriver
.
Note:
TheWTGJdbc
connection must be used within the application as well as configured in the project settings. However, during development, you may have used the adfconn
JDBC connection for testing. Once development is complete for the application, make sure that you modify your application to use the WTGJdbc connection before you deploy it.To create the WTGJdbc
connection, do the following:
In JDeveloper, configure the project settings and include the Oracle Database Lite user library named webtogo.jar
, as follows:
Copy the olite40.jar
and webtogo.jar
files from the Oracle Lite MDK into the <JDEV_HOME>
\bc4j\lib
.
Click Tools->Manage Libraries.
Select the Libraries tab.
Select User.
Create the library dialogs for both the webtogo.jar
and olite40.jar
files, as follows:
Click New Button. The "Create Library Dialog" displays.
Enter webtogo.jar
for the library name.
Select Deployed by default.
Click Add Entry and browse for the webtogo.jar
file.
Click OK.
The Manage Libraries screen displays. Click OK.
Repeat step e
for the olite40.jar
file.
Select the Connections tab on the Application Navigator.
Note:
If you do not see the Connections tab, select View->Connection Navigator.Right-click the Database folder and select New Database Connection.
Figure 12-5 JDeveloper Connection tab on the Connection Navigator, New Database Connection
The Create Database Connection Wizard starts. Perform the following in creating a new database connection using this wizard:
Click Next on the Welcome screen.
Enter WTGJdbc
as the Connection Name and choose Third Party JDBC Driver as the JDBC Connection Type.
Click Next.
Figure 12-6 Connection Wizard - Step 1 of 4: Type Panel
The Connection Wizard - Step 2 of 4: Authentication panel appears. Do not enter any values in this panel. Click Next.
The Connection Wizard - Step 3 of 4: Connection panel appears. Click New.
Figure 12-7 Connection Wizard - Step 3 of 4: Connection Panel
The Register JDBC Driver dialog appears, as Figure 12-8 displays. Perform the following:
Enter oracle.lite.web.WTGJdbcDriver
as the Driver Class. Choose webtogo
from the Library list and click OK.
Enter the following jdbc:oracle:webtogo
URL and click Next.
Figure 12-9 Enter URL for Database Connection
The Connection Wizard - Step 4 of 4: Click Finish. Do not test the Connection since you do not have any Client database to test the connection at this point.
The following sections describe the steps to develop the ADF/BC4J application for Oracle Database Lite:
Section 12.3.1, "Build the Data Model with ADF Business Components"
Section 12.3.3, "Create a Master-Detail JavaServer Faces Page"
Section 12.3.5, "Configure the ADF/BC4J Application for the Oracle Database Lite Environment"
The data model provides data access and validation for an application. The data is validated by the model, regardless of the client implementation. This separates the validation and business rules from the user interface.
The following sections describe the steps to create an application in JDeveloper and create a Business Components model for your applications.
In JDeveloper, you work with projects contained in an application. The application is the highest point in the control structure.
A JDeveloper project is an organizational structure that logically groups related files. You can add multiple projects to your application to easily organize, access, modify, and reuse your source code. In the Applications Navigator, projects are displayed as the second level in the hierarchy, under the application.
Before you create any components, you must first create the application and a project. Perform the following steps:
Select the Applications tab to go back to the Applications Navigator.
Right-click the Applications node and select New Application from the context menu.
In the Create Application dialog box, enter the Application Name OrderEntry
. Notice that the directory name changes automatically.
Enter orderentry
as the Application Package Prefix. For the Application Template, select the Web Application [JSF, ADF BC]
value from the Application Template drop-down list.
Click OK.
The Application should contain two projects: Model
and ViewController
.
You now have an application and projects to contain and manage your application.
In this section, you create ADF Business Components based on tables in the database. For this example, use the adfconn
database connection, which you created earlier. You create these objects in the Model project.
In the Applications Navigator, right-click the Model project and select New from the context menu.
In the New Gallery, expand Business Tier and select ADF Business Components in the Categories list.
Select Business Components from Tables in the Items list.
Figure 12-14 Select ADF Business Components from Tables
Click OK.
In the Business Components Project Initialization window, select the adfconn
connection from the Connection list. Change SQL Flavor to OLite and Type Map to Java, and then click OK.
Figure 12-15 Initialize Business Components Project
If the Welcome page of the Create Business Components wizard appears, click Next. If no package name is specified when creating the application, by default it takes the project name, which is model
.
Note:
An ADF Entity Object is a Java component that represents a row in an underlying database table as a domain business object in your J2EE application. It encapsulates the business rules for that domain object and automatically handles saving any change made by the user back to the database. If you are familiar with Oracle Forms, the entity object provides functionality similar to the Oracle Forms record manager, but with the ability to associate encapsulated business rules with each type of 'business record' structure.Select the tables for the business component, as follows:
Select MASTER from the Schema drop down list.
Click Query to populate the list of available tables.
Control-click to select both CUSTOMERS
and ORDERS
in the Available list.
Click the right arrow to move both tables to the Selected list.
Figure 12-16 Select Tables for Business Components
Click Next to continue.
On the Updatable View Objects page of the Create Business Components Wizard, select both Entity objects and click the right arrow button to move both tables to the Selected list.
Note:
An ADF View Object is a Java component that represents a SQL query against one or more underlying tables. It allows you to project, join, filter, and sort business information in exactly the way the end-user needs to see it for the user interface you need to provide to your end users. When related to underlying ADF Entity Objects, the view object allows users to create, update, and remove rows with automatic enforcement of business rules. If you are familiar with Oracle Forms, the view object provides functionality similar to the Oracle Forms Data Block, but adds the flexibility to finely tune the SQL query and to automatically leverage centralized business rules encapsulated by the entity object.Click Next.
Skip the Read-only View Objects page of the wizard by clicking Next. You will only be using view objects that can be updated.
On the Application Module page of the wizard, name the application module OrderEntryAM
.
Note:
An ADF Application Module is a Java component that represents a transactional data model of master/detail-related view object queries. It allows client interface technologies of any kind in a service-oriented architecture to easily manipulate the business information exposed by the view object instances contained in its data model. If you are familiar with Oracle Forms, the application module provides the functionality of a transactional data container similar to the Oracle Forms Form object, but is designed to allow any kind of user interface to work with the data in its view object 'data blocks'.Click Next.
JDeveloper provides several different techniques for managing components. One is to use a diagram of the components and their relationships. In this step, JDeveloper provides such a diagram option.
For this tutorial, you will not use this option. Click Next to continue.
The final page of the Business Components Wizard shows the objects and relationships that will be created.
Click Finish to complete the wizard actions.
Using the far right button of the toolbar in the navigator pane, sort elements by type.
In the previous sections, you created some default Business Components from two tables (Customers
and Orders
). The default view objects expose all of the columns from those tables. For your application, you want to expose only a few of those columns. ADF BC allows you to easily customize hose objects to fit your specific application needs.
In the following steps, you will add an Order By clause to the CustomersView to make sure the returned data is sorted by customer ID.
In the Applications Navigator, right-click the CustomersView node and select Edit CustomersView from the context menu.
Select SQL Statement and add an Order By
clause to the CustomersView to make sure the returned data is sorted by customer ID.
Click OK to apply the changes and exit the View Object Editor.
Click the Save All icon on the JDeveloper menu bar, or select File > Save All from the menu. You have now customized the Customers view to meet the specific needs of your application.
Conforming to the JSF standards, ADF Faces lets you concentrate on the application and layout rather than markup language and tags. Due to the integration of ADF Faces and ADF Business Components, you can easily change the default field labels for the user interface from within ADF Business Components.
In the next few steps, you create an ADF Faces application based on the ADF BC model that you just built. You also modify some of the ADF BC default settings to help enhance the default UI.
When you created the application, two projects were defined: Model
and ViewController
. The Model
project contains the business components that serve as the data model for your application. The ViewController
project will include the View portion of your application, which defines the user interface.
Collapse the Model node so that the Applications Navigator appear as follows:
Create a new JSF by right-clicking ViewController in the Applications Navigator and selecting New from the context menu.
Figure 12-26 New Object Under ViewController
Select JSF JSP from the JSF Category.
Selecting a new JSF opens the Create JSF JSP Wizard. Perform the following for creating the CustomerOrders.jsp
:
Click Next to skip the Welcome page of the JSF JSP Wizard, if it appears.
Name the new JSP CustomerOrders.jsp
. Accept the other defaults and click Next to continue.
On the next page, Component Binding, select the Do Not Automatically Expose UI Components option. Leave other default values and click Next.
Select libraries in the Available Libraries window, and use the Add button to move them into the Selected Libraries section, as needed. Make sure the following libraries appear in Selected Libraries:
JSF Core 1.0
JSF HTML 1.0
ADF Faces Components
ADF Faces HTML
Click Next to accept these libraries.
Click Finish to accept the default HTML options and create the new JSP.
You now have an empty CustomerOrders.jsp
page. In the next few steps, add a data-bound ADF Faces component to the page. This component displays a customer along with the orders that the customer has placed.
When you created the CustomerOrders.jsp
page, JDeveloper opened it in a visual editor in the center of the JDeveloper IDE. You add the ADF Faces components by dragging them from either the Component Palette or the Data Control Palette to the visual editor. Here you will drop some databound components based on the view objects you created earlier using the Data Control Palette.
Expand OrderEntryDataAMControl in the Data Control palette.
Expand CustomersView1
.
Note:
By default, the Business Components from Tables wizard noticed the foreign key relationships between theORDERS
and CUSTOMER
tables and created a default data model in the OrderEntryDataAM data model that features both an OrdersView1
, allowing us to see all orders, as well as an OrdersView2
that is linked with the OrdersView1
showing all of the customers. In this scenario, we'll use the CustomersView1
and the OrdersView2
that displays customers and their set of orders.Drag OrdersView2
to the visual editor. JDeveloper opens a context menu with the available options for that data control.
Place your cursor over the Master-Details option, and then select ADF Master Form, Detail Table.
JDeveloper adds the ADF Master Detail component to your JSF page.
Figure 12-36 Add ADF Master-Detail to JSP
In the JSF Page in the OrderView2, eliminate the Submit button by selecting the Component Submit and click the Delete key on your keyboard. The page should look as follows:
You now have a complete JSF that is databound to your ADF BC business services.
Now that you have built your new ADF Faces application, you need to test it. JDeveloper makes it easy to test JSF through a built-in OC4J server. The server is automatically launched when you test a page from within JDeveloper.
The next few steps take you through the testing process.
To test the page, right-click CustomerOrders.jsp
in the Applications Navigator and select Run from the context menu. Alternatively, you can right-click inside the visual editor and select Run from that context menu.
After execution, the results page should be as follows:
Note:
JDeveloper will open your default web browser and display the page. If this doesn't happen, visit the Tools -> Preferences and select the Web Browser and Proxy category. Here you can enter the command line to your preferred browser. Then, try running the page again after setting this preference.Navigate through the customer rows to see the differences in the orders that each customer has placed. Note that the first few customers in the list have multiple orders.
When you are finished, close the browser. Make sure you stop the JDeveloper OC4J Server before proceeding to next section. To stop the JDeveloper OC4J Server, select Run -> Terminate -> Embedded OC4J Server.
Using JDeveloper, configure the application to use the Oracle Database Lite environment, as described in the following sections:
Change the application configuration to use the WTGJdbcConnection
, as follows:
In the JDeveloper Applications Navigator, right-click the OrderEntryAM node and select Configurations.
Figure 12-40 Selecting Configurations in JDeveloper
Select JDBCName and edit the connection. The Oracle Business Component Configuration window is displayed.
Select WTGJdbc for Connection Name and click OK twice.
Figure 12-41 Business Component Configuration Window
Save your project.
The ADF/BC4J application has been configured to use Oracle Database Lite connection
To deploy the application, create a deployment profile and then deploy the application as a WAR file, as follows:
In the Application Navigator, select the CustomerOrders.jsp
.
Choose Run -> Deploy -> New Deployment Profile and create a new deployment profile.
Choose Run -> Deploy and then select the deployment profile created in step 2.
In order to package the ADF/BC4J application, you must perform the following:
Section 12.4.1, "Include the ADF Runtime Libraries with the ADF/BC4J Application"
Section 12.4.2, "Package the Application from the Packaging Wizard"
In order for the application to execute correctly, the ADF runtime libraries must be included. Perform the following to include these libraries in your ADF/BC4J application:
Unarchive the WAR file with the ADF/BC4J application into a temporary directory, such as adftutapp
. This explodes the CustomerOrders.jsp
and the WEB-INF
directory into the adftutapp
directory.
Navigate to the WEB-INF\lib
directory and copy all ADF/BC4J runtime libraries to this directory.
Note:
For information regarding list of libraries to be copied, refer to Chapter 22.12.3 “Installing the ADF Runtime Libraries Manually” in the Oracle Application Framework, Developer's Guide, 10g Release 3 (10.1.3).To package the JSP application, perform the following steps.
Copy the adftutapp
directory and its contents into the following location:
<Mobile_ServerHome>\Mobile\Sdk\wtgsdk\root
Using the Command Prompt window, run the Packaging Wizard and provide the screen inputs that are listed and described in Table 12-2.
Table 12-2 Packaging Wizard Input Details for BC4J Application
Screen | Input | Details |
---|---|---|
Platform |
Oracle Lite Web OC4J; US |
N/A |
Application |
Application Name |
ADF BC4J Oracle Database Lite Tutorial Application |
Application |
Virtual Path |
|
Application |
Description |
Oracle Lite Tutorial Application |
Application |
Application Classpath |
no input |
Application |
Default Page |
|
Application |
Local Application Directory |
|
Files |
The Packaging Wizard loads all files into the directory under the local application directory. |
N/A |
Note:
For all ADF-based applications, you need to also perform the following:For Platform input, the user should select the correct language for the Oracle Lite Web OC4J; <lang>
.
For the Default page Input for the application screen, always prepend the faces/
directory before the default page name.
If you miss these steps, your application will not perform correctly.
Retain the default values for Files, Servlet, Database and Roles screens.
On the Snapshots screen, click Import. You can now connect to the Oracle Database by providing the values shown in Table 12-3 in the "Connect to Database" dialog:
After specifying the Database Connection values, select CUSTOMERS
from the list of tables and click Add.
Select ORDERS
from the list of tables. Click Add and then click Close.
From the snapshot panel, select Customers and change the weight from 0 to 1.
From the snapshot panel, select ORDERS and click Edit. Change the weight from 0 to 2.
Retain the default values for Sequences and DDLs.
Package the ADF/BC4J application into a JAR file.
To publish and configure the JSP application from the Mobile Manager, perform the following steps:
Using the Command Prompt window, enter runmobileserver
to start the Mobile Server.
Using the following URL, browse the local host.
http://<localhost>:<portnumber>/webtogo
Note:
If the above port number is other than 80, specify the appropriate port number.Login into the Mobile Server using the administrator username and password.
Click Mobile Manager. Select the Mobile Server tab and then click Host name.
Click Applications and publish the JAR file that you just created.
Perform the following to test your ADF/BC4J application:
Log on to the Mobile Server with the administrator username and password.
Select Mobile Manager.
Click on the Mobile Server tab.
Select the host.
Click Users.
Create a new user called tutorial
and grant permission to this user for the "ADF/BC4J Oracle Database Lite Tutorial Application."
Test the application by executing the ADF/BC4J application on the Mobile Client for Oracle Lite WEB OC4J, as described in Section 12.7, "Run the ADF/BC4J Application on the Mobile Client for Oracle Lite WEB OC4J".
Before you execute, you must have JRE 1.5.x or higher installed for the OC4J client.
To execute the ADF/BC4J application on the Mobile Client for Oracle Lite WEB OC4J, perform the following steps:
Point the client machine browser to the following URL:
http://<Server_IP_Address>/setup
where Server_IP_Address
is your server machine IP address.
Download and install the Mobile Client for Oracle Lite WEB OC4J
Point the client machine browser to the following URL: http://<localhostname>
, where localhostname
is the client machine host name.
Log in to the client machine-using tutorial
as both the username and password.
After the client machine synchronizes the application and data from the server, click the “ADF/BC4J Oracle Database Lite Tutorial” Application link to test the application on the client machine.