20 Building Offline Mobile Web Applications Using BC4J: A Tutorial

This document enables you to create, deploy, and use a BC4J application, using a tutorial. Topics include:

• Section 20.1, "Overview"

• Section 20.2, "Developing the Application"

• Section 20.3, "Packaging the JSP Application"

• Section 20.4, "Publishing and Configuring the JSP Application from the Mobile Manager"

• Section 20.5, "Testing the BC4J Application"

• Section 20.6, "Running the BC4J Application on the Mobile Client for Web-to-Go"

• Section 20.7, "Deploying the Sample Application"

20.1 Overview

The Oracle BC4J (Business Components for Java) is a part of the Oracle JDeveloper IDE (Integrated Development Environment), and provides Java developers with tools to create and manage reusable Java components.

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 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, BC4J automatically generates database oriented components, so that you can focus on the business logic instead of on database related components.

The sample BC4J application used in this tutorial maintains employee details and stores all items in a relational database.

20.1.1 Before You Start

Before you start developing business components in Java, ensure that the computer you are using for your development meets the requirements specified in this section. Table 20-1 lists configuration and installation requirements for the development computer.

Table 20-1 Development Computer Requirements

Requirement	Description
Windows NT/2000/XP User Login	The Windows NT/2000/XP login user must have Administrator privileges on the development computer.
Installed Java Components	Java Development Kit 1.4.2 or higher.
Installed Oracle Components	Mobile Server or Mobile Development Kit (Oracle Database Lite CD-ROM) Oracle 8.1.7 or higher Oracle9i JDeveloper, Release 9.0.3.

Note: The BC4J tutorial is shipped with the Mobile Development Kit as a JAR file named OracleLite_BC4J_Tutorial.jar. The file is located in the directory <ORACLE_HOME>\mobile\sdk\wtgsdk\src. You can use this JAR file to publish the BC4J tutorial to the Mobile Server and then continue with the rest of the tutorial by following the steps given in Section 20.7, "Deploying the Sample Application". If you want to develop the same application (as packaged in OracleLite_BC4J_Tutorial.jar), follow the steps from Section 20.2, "Developing the Application" on.

20.2 Developing the Application

This section enables you to develop the BC4J application for Oracle Database Lite in phases.

To develop the BC4J application, you must perform the following tasks.

1. Section 20.2.1, "Creating the Database Connection"

2. Section 20.2.2, "Creating the BC4J Component"

3. Section 20.2.3, "Configuring the BC4J Component to Use the WTGJdbc Connection"

4. Section 20.2.4, "Building and Deploying the BC4J Component as a Simple Archive"

5. Section 20.2.5, "Writing the JSP Application to Access the BC4J Component"

6. Section 20.2.6, "Deploying the JSP Application as a Simple Archive"

20.2.1 Creating the Database Connection

For developing an application using BC4J, you must create two database connections, as follows:

• A connection to the back-end Oracle database that is used only within BC4J to test the application while developing within BC4J.

• The permanent connection used between the back-end Oracle database and the Oracle Database Lite, which is used by the application after deployment for synchronization between the two databases.

During development and testing within BC4J, use the first connection. After you are done developing the application and are ready to deploy it, change the connection from to the second connection before deploying the application.

The following sections provide details on how to create each type of connection:

• Section 20.2.1.1, "Create the Connection to the Back-End Oracle Database"

• Section 20.2.1.2, "Create the Connection to the Oracle Lite Database"

20.2.1.1 Create the Connection to the Back-End Oracle Database

You need to create a connection to the back-end Oracle database, which is used only within BC4J to test the application while developing within BC4J. For this example, we create the tutorialConn connection to connect to the back-end Oracle database using the oracle.jdbc.driver.OracleDriver for the BC4J development process.

To create the tutorialConn connection, perform the following steps.

1. In the JDeveloper System Navigator panel and as displayed in Figure 20-1, right-click the Connections node and choose the New Database Connection option.

   Figure 20-1 Choosing a New Database Connection

   
   Description of the illustration newconn.gif
   
   

2. The Connection Wizard Welcome panel appears, which is displayed in Figure 20-2. Click Next.

   Figure 20-2 Welcome Panel - Connection Wizard

   
   Description of the illustration cwiz_wel.gif
   
   

3. The Connection Wizard - Step 1 of 4: Type panel appears, as displayed in Figure 20-3. Create a connection named tutorialConn and choose Oracle (JDBC) from the Connection Type list. Click Next.

   Figure 20-3 Connection Wizard - Step 1 of 4: Type

   
   Description of the illustration cwstep2.gif
   
   

4. The Connection Wizard - Step 2 of 4: Authentication panel appears, as displayed in Figure 20-4. Enter scott as the user name and tiger as the password. Select the Deploy Password box. Click Next.

   Figure 20-4 Connection Wizard - Step 2 of 4: Authentication Panel

   
   Description of the illustration cwstep3.gif
   
   

5. The Connection Wizard - Step 3 of 4: Connection panel appears, as displayed in Figure 20-5. Choose the thin option from the Driver list and enter your PC Host Name, JDBC Port number, and the database SID in the corresponding fields. Do not select the Enter Custom JDBC URL box. Click Next.

   Figure 20-5 Connection Wizard - Step 3 of 4: Connection Panel

   
   Description of the illustration cwstep4.gif
   
   

6. The Connection Wizard - Step 4 of 4: Test panel appears, as displayed in Figure 20-6. Click Test Connection. The Connection Wizard displays a connection status message. Click Finish.

   Figure 20-6 Connection Wizard - Step 4 of 4: Test Panel

   
   Description of the illustration cwstep5.gif
   
   

   You have finished creating the tutorialConn, as displayed in Figure 20-7.

   Figure 20-7 Connection Wizard - Finish Panel

   
   Description of the illustration cwstep6.gif
   
   

7. In JDeveloper, the tutorialConn icon appears in the System Navigator window under the Connections node, as displayed in Figure 20-8.

   Figure 20-8 Tutorial Connection Icon in the System Navigator

   
   Description of the illustration cwstep7.gif
   
   

   In summary, Table 20-2 shows the values that you provide for this connection in the Connection Wizard.

   Table 20-2 TutorialConn - Connection Wizard Description

   Field Name	Value
   Connection Name	tutorialConn
   User name	scott
   Password	tiger
   Select a JDBC Driver	Thin
   SID	Your Oracle database SID

   
   

20.2.1.2 Create the Connection to the Oracle Lite Database

Create the permanent connection used by the application between the back-end Oracle database and the Oracle Database Lite. This connection is used after the application is deployed for synchronization between the two databases—the back-end Oracle database and the local Oracle Lite database.

For this example, create the WTGJdbc connection, which uses the oracle.lite.web.WTGJdbcDriver.

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

1. Configure the project settings and include the Oracle Database Lite user library named webtogo.jar. Start JDeveloper and click the Project menu. As displayed in Figure 20-9, select the Default Project Settings option. Then select Development->Configuration->Libraries in the left side pane. Click New Button.

   Figure 20-9 Choosing Default Project Settings

   
   Description of the illustration prset1.gif
   
   

2. In the Project Settings panel, add a new library and name the new library as webtogo. Enter the CLASSPATH as given below and displayed in Figure 20-10. Click OK.

   <mobile_serverhome>/server/bin/webtogo.jar
   

   Figure 20-10 Adding a New Library and Classpath

   
   Description of the illustration prset2.gif
   
   

3. Move the webtogo library from the Available Libraries list to the Selected Libraries list, as displayed in Figure 20-11. Click OK.

   Figure 20-11 Moving the Webtogo Library to the Selected Libraries List

   
   Description of the illustration prset3.gif
   
   

4. After configuring project settings as mentioned in this step, create the WTGJdbc connection using the same method that you used to create tutorialConnection.

   To create the WTGJdbc connection, start JDeveloper and right-click the Connection object and choose New Database Connection Option. As displayed in Figure 20-12, the Connection Wizard - Step 1 of 4: Type panel appears. Enter WTGJdbc as the Connection Name and choose Third Party JDBC Driver as the JDBC Connection Type. Click Next.

   Figure 20-12 Connection Wizard - Step 1 of 4: Type Panel

   
   Description of the illustration wtgcw1.gif
   
   

5. The Connection Wizard - Step 2 of 4: Authentication panel appears, as displayed in Figure 20-13. Do not enter any values in this panel. Click Next.

   Figure 20-13 Connection Wizard - Step 2 of 4: Authentication Panel

   
   Description of the illustration wtgcw2.gif
   
   

6. The Connection Wizard - Step 3 of 4: Connection panel appears, as displayed in Figure 20-14. Click New.

   Figure 20-14 Connection Wizard - Step 3 of 4: Connection Panel

   
   Description of the illustration wtgcw3.gif
   
   

7. The Register JDBC Driver dialog appears, as Figure 20-15 displays. Enter oracle.lite.web.WTGJdbcDriver as the Driver Class. Choose webtogo from the Library list and click OK. Enter the following URL.

   jdbc:oracle:webtogo
   
   

   Click Next.

   Figure 20-15 JDBC Driver Dialog

   
   Description of the illustration wtgcw3a.gif
   
   

8. The Connection Wizard - Step 4 of 4: Test panel appears, as Figure 20-16 displays. To test your WTGJdbc connection, click Test Connection. The Status box displays that the WTGJdbc connection has been created successfully. Click Finish.

   Figure 20-16 Connection Wizard - Step 4 of 4: Test Panel

   
   Description of the illustration wtgcw4.gif
   
   

In summary, Table 20-3 describes the values that are entered in the Connection Wizard to create the WTGJdbc connection:

Table 20-3 WTGJdbc Connection - Connection Wizard Description

Field Name	Values
Connection Name	WTGJdbc
Select a JDBC Driver	Third Party JDBC Driver
Class Name	oracle.lite.web.WTGJdbcDriver
Datasource URL	jdbc:oracle:webtogo

Note: In the Connection Wizard, enter values as specified in Table 20-2 and Table 20-3 only. Retain all other values as default values.

20.2.2 Creating the BC4J Component

Using JDeveloper, create the BC4J component named tutorialapp, as follows:

1. In JDeveloper, select New from the File menu. In the New dialog box that appears, the options—Projects in the left panel under General Categories and Empty Project in the right panel are pre-selected as defaults. Select Workspace to enable the OK button and click OK. JDeveloper creates a new empty project named Project.jpr.

2. Rename Project.jpr to tutorialapp.jpr, which creates a new project by that name. Select the project and then select File->Rename.

3. Right click tutorialapp.jpr in the JDeveloper workspace. Select New Business Components Package. As shown in Figure 20-17, the "Business Components Package Wizard, Welcome" dialog appears. Click Next.

   Figure 20-17 The Business Components Package Wizard, Welcome Dialog

   
   Description of the illustration bcopwiz.gif
   
   

4. The "Business Components Package Wizard, Step 1 of 3: Package Name" dialog appears, as illustrated in Figure 20-18. In the Package Name field, enter tutapp. Click Next.

   Figure 20-18 Business Components Package Wizard Step 1 of 3: Package Name

   
   Description of the illustration bcpwiz2.gif
   
   

5. The "Business Components Package Wizard, Step 2 of 3: Connection" dialog appears, as depicted in Figure 20-19.

   Figure 20-19 Business Components Package Wizard Step 2 of 3: Connection

   
   Description of the illustration bcpwiz3.gif
   
   

   Select the values that are listed in Table 20-4 and click Next.

   Table 20-4 Values for Business Components Package Wizard, Step 2 of 3: Connection

   Field	Description
   Connection Name	tutorialConn
   SQL Flavor	SQL92
   Type Map	Oracle

   
   

6. In the "Business Components Project Wizard, Step 3 of 3: Business Components" dialog, select EMP from the list displayed in the left panel and move it to the "Selected" list, as illustrated by the example in Figure 20-20. Click Finish.

   Figure 20-20 Business Components Package Wizard, Step 3 of 3: Business Components Dialog

   
   Description of the illustration bcpwiz4.gif
   
   

7. JDeveloper creates the TutorialAppModule BC4J component.

20.2.3 Configuring the BC4J Component to Use the WTGJdbc Connection

After you have completed developing and testing your application, switch the connection to use the WTGJdbc connection, which is the connection between the Oracle database and Oracle Database Lite. To configure the BC4J component to use the WTGJdbc connection, perform the following steps.

1. Right-click on the TutorialAppModule and click the Configurations... option. The Configuration Manager appears.

2. In the Oracle Business Component Configuration dialog, click Edit. Choose WTGJdbc as the JDBC connection.

3. Click OK. The BC4J component is now configured to use the WTGJdbc connection.

4. Click OK in the Configuration Manager window.

20.2.4 Building and Deploying the BC4J Component as a Simple Archive

To build and deploy the BC4J component as a simple archive, perform the following steps.

1. Right-click the tutorialapp.jpr file and select the Create Business Components Deployment Profiles option. The Business Component Deployment Wizard appears.

2. Select the Simple Archive Files option from the list displayed and move it to the Selected list. Click Next. By default, this option is already selected.

3. The "Business Component Deployment Wizard Step 2 of 2: Simple Archive Files" appears. Under the 'Selected Platform - Simple Archive Files' section, accept the default Profile name.

4. Click Next. Click Finish. The tutorialapp.bcdeploy file is created under tutorial.jpr.

5. Right-click the file tutorialapp.bcdeploy and select Deploy. JDeveloper creates two jar files—tutorialappCSCommon.jar and tutorialappCSMT.jar.

   
   

   Note: To check the location of the .jar files that you created, check the Deployment Log window in the JDeveloper UI.

   
   

20.2.5 Writing the JSP Application to Access the BC4J Component

To write the JSP application that will access the BC4J component, perform the following steps.

1. In JDeveloper, select File->New Options. Select Empty Project in the right-hand pane. Click OK. The system automatically creates a new empty project called MyProject.jpr.

2. Under the File menu, select Rename... and rename MyProject.jpr to tutorialclientapp.jpr.

3. Click the tutorialclientapp.jpr file in the JDeveloper workspace. Select File->New. Click Web Tier and select JSP for Business Components. Click OK. The Business Components JSP Application Wizard appears. Click Next.

   Figure 20-21 Business Components JSP Application Wizard - Welcome Dialog

   
   Description of the illustration bc4j1.gif
   
   

4. Click New. The 'Business Components JSP Application Wizard' appears. Click Next. The wizard displays the 'Business Components JSP Application Wizard - Step 1 of 3:Data Definition' dialog.

   Figure 20-22 Business Components JSP Application Wizard - Step 1 of 3: Data Definition Dialog

   
   Description of the illustration bc4j2.gif
   
   

5. Click New in the 'Business Components JSP Application Wizard - Step 1 of 3:Data Definition' dialog. The 'BC4J Client Data Model Definition Wizard' appears. Click Next.

   Figure 20-23 BC4J Client Data Model Definition Wizard - Welcome Dialog

   
   Description of the illustration bc4j3.gif
   
   

6. The 'BC4J Client Data Model Definition Wizard: Step 1 of 2: Definition' appears.

   Figure 20-24 BC4J Client Data Model Definition Wizard, Step 1 of 2: Definition Dialog

   
   Description of the illustration bc4j4.gif
   
   

7. Verify the default values and click Next. TutappModule appears as the default definition name in the 'BC4J Client Data Model Definition Wizard - Step 2 of 2: Definition Name' dialog. Click Next.

8. Click Finish. The 'Business Components JSP Application Wizard' dialog appears. Click Next.

9. In the 'Business Components JSP Application Wizard - Step 1 of 3: Data Definition' dialog, select TutappModule as the data model definition, as displayed in Figure 20-25. Click Next.

   Figure 20-25 Business Components JSP Application Wizard - Step 1 of 3: Data Definition Dialog

   
   Description of the illustration def_2.gif
   
   

10. Accept the default selections and click Next in the two dialog boxes that appear: 'Business Components JSP Application Wizard - Step 2 of 3: View Object Forms' and 'Business Components JSP Application Wizard - Step 3 of 3: View Link Form'. The 'Summary' window appears. Click Finish.

20.2.6 Deploying the JSP Application as a Simple Archive

To deploy the JSP application as a simple archive, perform the following steps.

1. In JDeveloper, click the tutorialclientapp.jpr file and select the file named tutappclient_jpr_war.deploy. Right click on the tutorialclient_jpr_war.deploy file.

2. Select 'Deploy to WAR file'. The file tutappclient_jpr_war.war is created. To track the deployment location, check the 'Deployment Log' text area in JDeveloper.

20.3 Packaging the JSP Application

To package the JSP application, perform the following steps.

1. Create a sub-directory called bc4jtutapp under the following location:

   <Mobile_ServerHome>\Mobile\Sdk\wtgsdk\root
   
   

2. Unzip the tutappclient_jpr_war.war file into the bc4jtutapp directory.

3. Edit all the JSP files to delete the following.

   charset=windows-1252
   
   

   as shown below:

   <%@page language="Java"errorpage="errorpage.jsp" 
   ContentType="text/html;charset=windows-1252"%>\
   
   

4. Edit the web.xml file and insert the following tag at the end just before closing </web-app>.

   <filter>
    	<filter-name>CheckSessionFilter</filter-name>
   	 <filter-class>oracle.lite.web.CheckSessionFilter</filter-class>
   </filter>
    
   <filter-mapping>
   	 <filter-name>CheckSessionFilter</filter-name>
   	 <url-pattern>/*</url-pattern>
   </filter-mapping>
   
   

5. Using the Command Prompt window, run the Packaging Wizard and provide the screen inputs that are listed and described in Table 20-5.

   Table 20-5 Packaging Wizard Input Details

   Screen	Input	Details
   Platform	Web-To-Go	N/A
   Application	Application Name	BC4J Oracle Database Lite Tutorial Application
   Application	Virtual Path	/bc4jtutorial
   Application	Description	Oracle Lite Tutorial Application
   Application	Application Classpath	no input
   Application	Default Page	main.html
   Application	Local Application Directory	<ORACLE_HOME>\Mobile\Sdk\wtgsdk\root\bc4jtutapp
   Files	The Packaging Wizard loads all files in a directory under the Local Application Directory.	N/A

   
   

   Table 20-6 lists the servlet names and their corresponding classes that are created in the Packaging Wizard by default.

   Table 20-6 Servlet Names and Classes

   Screen	Servlet Name	Servlet Class
   Servlet	EMDServlet	oracle.jbo.server.emd.EMDServlet
   Servlet	ImageServlet	oracle.cabo.image.servlet.ImageServlet
   Servlet	TecateServlet	oracle.cabo.image.servlet.TecateServlet
   Servlet	BajaServlet	oracle.cabo.servlet.BajaServlet
   Servlet	OrdPlayMediaServlet	oracle.ord.html.OrdPlayMediaServlet

   
   

   Table 20-7 lists server side and client side database values that you must specify in the Packaging Wizard.

   Table 20-7 Database Values

   Screen	Input	Details
   Database	Server side Database User Name	scott
   Database	Number of Connections	0
   Database	Share Connections	Do not select this check box
   Database	Client side Database Name	Client DB

   
   

6. Under the Snapshots section, click Import. You can now connect to the Oracle Database by providing the following values in the "Connect to Database" dialog.

   Table 20-8 lists values that you must specify in the Connect to Database dialog.

   Table 20-8 Connect to Database Dialog Description

   Field	Description
   User Name	scott
   Password	tiger
   Database URL	jdbc:oracle:thin:@DatabaseHostMachineName:port:SID

   
   

7. After specifying the Database Connection values, select Emp from the list of tables.

8. Click Edit and change the weight from 0 to 1.

9. Retain the default values for Roles, Sequences, DDLs, and Registry fields.

10. Package the application into a JAR file.

20.4 Publishing and Configuring the JSP Application from the Mobile Manager

To configure the JSP application from the Mobile Manager, perform the following steps.

1. Using the Command Prompt window, enter runmobileserver to start the Mobile Server.

2. Using the following URL, browse the local host.

   http://localhost:portnumber/webtogo
   

   
   

   Note: If the above port number is other than 80, you must specify the appropriate port number.

   
   

3. Login into the Mobile Server using the administrator user name and password.

4. Click Mobile Manager. Select the Mobile Server tab and then click Host name.

5. Click Applications and publish the JAR file that you just created.

20.5 Testing the BC4J Application

Perform the following to test your BC4J application:

1. Log on to the Mobile Server with the administrator username and password.

2. Select Mobile Manager.

3. Click on the Mobile Server tab.

4. Select the host.

5. Click Users.

6. Create a new user called tutorial and grant permission to this user for the "Oracle Lite Tutorial Application".

7. Test the application by executing the BC4J application on the Webt-to-Go Mobile client, as described in Section 20.6, "Running the BC4J Application on the Mobile Client for Web-to-Go".

20.6 Running the BC4J Application on the Mobile Client for Web-to-Go

To execute the BC4J application on the Mobile Client for Web-to-Go, perform the following steps.

1. Using the following URL, check the Oracle database server IP address setup.

   http://Server_IP_Address/setup
   
   

2. Download and install the Mobile Client for Web-to-Go with BC4J support.

3. Using the following URL, check the local host in the client machine.

   http://localhostname
   
   

4. Log in to the client machine using tutorial as both the user name and password.

5. After the client machine synchronizes the application and data from the server, click the 'Oracle Lite Tutorial Application' link to test the application on the client machine.

20.7 Deploying the Sample Application

To deploy the sample application, perform the following steps.

1. Log in to the database as a system user. If the SCOTT schema does not exist already, execute the bc4j.sql script.

2. Publish the OracleLite_BC4J_Tutorial.jar file. It is found under the following directory.

   <mobile_server_home>\mobile\Sdk\wtgsdk\src\bc4jtutorial>
   
   

   Using the Mobile Manager, publish the above .jar file into the Mobile Server and enter the following virtual path.

   /bc4jtutorial
   
   

3. Click Mobile Manager and click Applications.

4. Click the 'Oracle Lite BC4J Application' link. The Properties page appears.

5. Enter tiger as the database password and click Save.

6. Navigate back to the Mobile Manager home page and click the Users link. In case the user tutorial doesn't exist already, add this user, as described in Section 20.5, "Testing the BC4J Application".

7. Click Applications and select 'Oracle Lite BC4J Application.' To provide access to the 'Oracle Lite BC4J Application', click Access and assign the access privilege to the user named tutorial.

8. Using the following URL, browse the client machine with BC4J support.

   http://servername:port/webtogo/setup
   
   

9. Download and install the Mobile Client for Web-to-Go.

10. If not started already, start the Mobile Client for Web-to-Go.

11. Log in to the Mobile Client for Web-to-Go with tutorial as the user name and password.

12. Upon completion of the Synchronization process, the system displays the 'Oracle Lite BC4J Application' link.

13. Click the 'Oracle Lite BC4J Application' link to access the BC4J tutorial application.