Skip Headers
Oracle® Database Lite Developer's Guide
10g (10.0.0)
Part No. B13788-01
  Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

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

13.1 Overview

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

BC4J offers a standards based, server side Java and XML framework for developers who 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, namely, Entity Objects, Associations, View Objects, View Links, and Application Modules. Each of these components is interrelated to the other components, thereby enabling 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, enabling Web-to-Go developers to focus on the business logic instead of spending their time on database related components during business application development.

The sample BC4J application which is used in this tutorial stores its items in a relational database. It maintains employee details.

13.1.1 Before You Start

Before you start developing business components in Java, you must ensure that the development computer meets the requirements specified below.

13.1.1.1 Development Computer Requirements

Table 13-1 lists configuration and installation requirements for the development computer.

Table 13-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.3.1 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 9iLite_BC4J_Tutorial.jar. The file is located in the directory &fmv980;\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 13.7, "Deploying the Sample Application". If you want to develop the same application (as packaged in 9iLite_BC4J_Tutorial.jar), follow the steps from Section 13.2, "Developing the Application" to Section 13.6, "Running the BC4J Application on the Mobile Client for Web-to-Go", and then continue to Section 13.7, "Deploying the Sample Application".

13.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. Create a database connection.

  2. Create the BC4J component.

  3. Configure the BC4J component to use the WTGJdbc connection.

  4. Build and deploy the BC4J component as a simple archive.

  5. Write the JSP application to access the BC4J component.

  6. Deploy the JSP application as a simple archive.

  7. Deploy the BC4J component into the Mobile Server.

13.2.1 Creating the Database Connection

You must create two database connections: tutorialConn and WTGJdbc respectively. The tutorialConn connection connects to the primary Oracle database using the oracle.jdbc.driver.OracleDriver for developing and testing the application. The WTGJdbc connection connects to Oracle Database Lite using the oracle.lite.web.WTGJdbcDriver. You can change the connection from tutorialConn to WTGJdbc before deploying the application as a simple archive. The WTGJdbc connection is used during application deployment and uses a different driver.

To create the tutorialConn connection, perform the following steps.

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

    Figure 13-1 Choosing a New Database Connection

    Choose the new database connection option.

    As displayed in Figure 13-2, the Connection Wizard's Welcome panel appears.

    Figure 13-2 Welcome Panel - Connection Wizard

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

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

    Specify the connection name and connection type.
  3. Click Next. As displayed in Figure 13-4, the Connection Wizard - Step 2 of 4: Authentication panel appears. Enter scott as the user name and tiger as the password. Select the Deploy Password box.

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

    authentication panel
    Description of the illustration cwstep3.gif

  4. Click Next. As displayed in Figure 13-5, the Connection Wizard - Step 3 of 4: Connection panel appears. 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.

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

    Specify the driver, host name, JDBC port, and SID.
  5. Click Next. As displayed in Figure 13-6, the Connection Wizard - Step 4 of 4: Test panel appears. Click Test Connection. The Connection Wizard displays a connection status message.

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

    This image enables you to test the connection.
  6. As displayed in Figure 13-7, you have finished creating the tutorialConnection.

    Figure 13-7 Connection Wizard - Finish Panel

    You have finished creating the tutorialConnection.

    As displayed in Figure 13-8, The tutorialConnection icon appears in the System Navigator window under the Connections node.

    Figure 13-8 Tutorial Connection Icon in the System Navigator

    The tutorial connection icon in the System navigator.

    Table 13-2 summarizes values that you must enter or choose in the Connection Wizard.

    Table 13-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

  7. To create the WTGJdbc connection, you must 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 13-9, select the Default Project Settings option.

    Figure 13-9 Choosing Default Project Settings

    Choose default project settings.
  8. 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 13-10.

    mobile_serverhome/server/bin/webtogo.jar

    Figure 13-10 Adding a New Library and Classpath

    add a new library and classpath.
    Description of the illustration prset2.gif

  9. After creating the new user library webtogo, move the library from the Available Libraries list to the Selected Libraries list as displayed in Figure 13-11.

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

    Move the webtogo library to the selected libraries list.

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

  10. To create the WTGJdbc connection, start JDeveloper and right-click the Connection object. As displayed in Figure 13-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.

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

    Type panel
    Description of the illustration wtgcw1.gif

  11. Click Next. As displayed in Figure 13-13, the Connection Wizard - Step 2 of 4: Authentication panel appears. Do not enter any values in this panel.

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

    At this stage, do not enter any values in this panel.
  12. Click Next. As displayed in Figure 13-14, the Connection Wizard - Step 3 of 4: Connection panel appears.

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

    Click the new button in this image.
  13. Click New. As Figure 13-15 displays, the Register JDBC Driver dialog appears. Enter oracle.lite.web.WTGJdbcDriver as the Driver Class. Choose webtogo from the Library list. Enter the following URL.

    jdbc:oracle:webtogo

    Figure 13-15 JDBC Driver Dialog

    JDBC driver dialog
    Description of the illustration wtgcw3a.gif

  14. Click Next. As Figure 13-16 displays, the Connection Wizard - Step 4 of 4: Test panel appears. To test your WTGJdbc connection, click Test Connection. The Status box displays that the WTGJdbc connection has been created successfully.

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

    This image enables you to test your JDBC connection.

Table 13-3 describes values that must be entered in the Connection Wizard to create the WTGJdbc connection.

Table 13-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 13-2 and Table 13-3 only. Retain all other values as default values.

13.2.2 Creating the BC4J Component

Using Oracle9i JDeveloper, you can create the BC4J component named "tutorialapp".

To create the BC4J component named "tutorialapp", perform the following steps.

  1. In Oracle9i JDeveloper, select New from the File menu. In the New dialog box that appears, the options named "Projects" in the left panel and "Empty Project" in the right panel are pre-selected as defaults. Click OK. Oracle9i JDeveloper creates a new empty project named "Project.jpr".

  2. Rename "Project.jpr" to "tutorialapp.jpr", which creates a new project by that name.

  3. Right click "tutorialapp.jpr" in the Oracle9i JDeveloper workspace. Select the "New Business Components Package..." option. The "Business Components Package Wizard, Welcome" dialog appears. Click Next.

    Figure 13-17 displays the Business Components Package Wizard, Welcome dialog.

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

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

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

    In this image, enter your package name.
  5. The "Business Components Package Wizard, Step 2 of 3: Connection" dialog appears, as depicted in Figure 13-19. Select the values that are listed in Table 13-4 and click Next.

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

    Specify the connection name, SQL flavor, and type map.

    Table 13-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 13-20. Click Finish.

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

    Move EMP from the available list to the selected list.
  7. At this stage, Oracle9i JDeveloper creates the BC4J component named "tutorialapp".

13.2.3 Configuring the BC4J Component to Use the WTGJdbc Connection

To configure the BC4J component to use the WTGJdbc connection, perform the following steps.

  1. Right-click on the TutorialAppModule and double-click on 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.

13.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.

  3. Click Next. 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. The tutorialapp.bcdeploy file is created under tutorial.jpr.

  5. Right-click the file tutorialapp.bcdeploy and select Deploy.

  6. JDeveloper creates two jar files namely 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.

13.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 Oracle9i JDeveloper, select the Empty Project option under the 'File' menu. The system automatically creates a new empty project called MyProject.jpr.

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

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

  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.

  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.

  6. Click Next. The 'BC4J Client Data Model Definition Wizard: Step 1 of 2: Definition' appears, as displayed in Figure 13-21, Figure 13-22, Figure 13-23, and Figure 13-24.

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

    Displays the JSP Application Wizard’s welcome dialog.

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

    The Data Definition dialog.

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

    Model Definition Wizard’s welcome dialog.
    Description of the illustration bc4j3.gif

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

    The BC4J client data model definition dialog.
  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 13-25. Click Next.

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

    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.

13.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 Oracle9i JDeveloper, click the tutorialclientapp.jpr file and select the file named tutappclient_jpr_war.deploy.

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

13.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.

    &fmv985;\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

    from

    <%@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 13-5.

    Table 13-5 Packaging Wizard Input Details

    Screen Input Details
    Platform Web-To-Go NA
    Application Application Name BC4J 9iLite Tutorial Application
    Application Virtual Path /bc4jtutorial
    Application Description BC4J 9iLite Tutorial Application
    Application Application Classpath no input
    Application Default Page main.html
    Application Local Application Directory &fmv987;\Mobile\Sdk\wtgsdk\root\bc4jtutapp
    Files The Packaging Wizard loads all files in a directory under the Local Application Directory. NA

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

    Table 13-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 13-7 lists server side and client side database values that you must specify in the Packaging Wizard.

    Table 13-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 13-8 lists values that you must specify in the Connect to Database dialog.

    Table 13-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 to "1" from "0".

  9. You must retain the default values for Roles, Sequences, DDLs, and Registry fields.

  10. Package the application into a JAR file.

13.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 java -jar oc4j.jar, to start the Mobile Server.

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

    http://localhost:portnumber

    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's user name and password.

  4. Click Mobile Manager.

  5. Click the Applications link and publish the JAR file that you just created. In the Repository Directory field, enter /bc4jtutorial.

13.5 Testing the BC4J Application

To test the BC4J application, login to the Mobile Server as a 'tutorial' user. In the 'tutorial' workspace, double-click the 'BC4J 9iLite Tutorial Application'. The Business Components JSP Application window appears. Click Emp View and browse through the employee table records.

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

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

  1. Using the following URL, check the Database Server's 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 the user name and password.

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

13.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, run the bc4j.sql script.

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

    &fmv995;\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 the Applications link.

  4. Click the '9iLite 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 a user named 'tutorial' and assign 'user' as the privilege.

  7. Click the Applications link and click the '9iLite BC4J Application' link. To provide access to the '9iLite BC4J Application', click the Access link and provide access 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 '9iLite BC4J Application' link.

  13. Click the '9iLite BC4J Application' link to access the BC4J tutorial application.