Skip Headers
Oracle® Database Lite Tools and Utilities Guide
10g (10.0.0)
Part No. B12263-01
  Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

2 Using the Packaging Wizard

This chapter enables you to package and publish your mobile applications using the Packaging Wizard. Topics include:

2.1 Using the Packaging Wizard for Web Applications

The Packaging Wizard is a graphical tool that enables you to perform the following tasks.

When you create a new mobile application, you define its components and publish them to the Mobile Server Repository. In some cases, you may want to edit the definition of an existing mobile application's components. For example, if you develop a new servlet for your application, you can use the Packaging Wizard to add the servlet to your application definition and then publish the modified application to the Mobile Server Repository. The Packaging Wizard also enables you to package application components in a .jar file for easy deployment.

Additionally, the Packaging Wizard supports the Web Application Archive (WAR) file format including the web.xml descriptor file. WAR files can be created using tools such as JDeveloper, according to the Java Servlet Specification 2.3.

The following sections describe how to use the Packaging Wizard. Topics include:

2.1.1 Starting the Packaging Wizard

To launch the Packaging Wizard, enter the following using a Command Prompt window.

wtgpack

As Figure 2-1 displays, the Packaging Wizard appears and displays the Make a Selection dialog. Using this dialog, you can create, edit, open, or delete a packaged application using the following features.

Figure 2-1 Packaging Wizard - Make A Selection Dialog

Packaging Wizard Selection dialog

Table 2-1 describes the Make a Selection dialog.

Table 2-1 Make a Selection Dialog

Feature Description
Create a new application If selected, this option enables you to define a new application.
Edit an existing application If selected, this option enables you to edit an existing application. Users can select an existing application from the list displayed.
Delete an existing application If selected, this option enables you to delete an existing application from the XML file, but not from the Mobile Server Repository.
Creating a new application using a WAR file If selected, this option enables you to create an application using a Web Application Archive (WAR) file. You can enter the name of the WAR file or locate it using the 'Browse' button.
Open a Packaged application If selected, this option enables you to select an application that has been packaged a JAR file. You can enter the name of the packaged application or locate it using the 'Browse' button.

Using the 'Select a Platform' dialog, select the platform for which you want to package your application. As Figure 2-2 displays, this dialog enables you to specify a platform. If you are packaging a WAR file, this dialog only displays web based platforms.

Figure 2-2 Select a Platform Dialog

Select a platform dialog

2.1.2 Specifying New Application Details

Using the Application dialog, you can name a new Web-to-Go application and specify its storage location on the Mobile Server. As Figure 2-3 displays, the Application dialog includes the following fields.

Figure 2-3 Application Dialog

Application dialog

Table 2-2 describes the Application dialog.

Table 2-2 Application Dialog Description

Field Name Description Required
Application Name The name of the new mobile application.

When packaging a WAR file, the application name must be set to the value of the element <display-name>, which can be found under the main element <web-app> in the file web.xml.

Yes
Virtual Path A path that is mapped from the root directory of the server repository to the mobile application itself. The virtual path eliminates the need to refer to the application's entire directory structure. It indicates that all of the subdirectories and all of the files that are in the virtual path will be uploaded exactly as they are in the directory structure to the Mobile Server Repository when the application is published. It also provides the application with a unique identity.

Application Root Directory

As Figure 2-3 displays, the name /tutorial indicates the virtual path of the application. The name that you enter as the virtual path of the application becomes the application root directory within the Mobile Server Repository, when the application is published. Consequently, you can specify the application root directory by the name that you enter in the virtual path field. This name can be different from the application name, but should not contain spaces. For example, your application name can be 'Sales Office' and your virtual path '/Admin'. In this case, '/Admin' becomes the name of the application root directory within the Mobile Server Repository. The application root directory is the location where the actual application files are stored within the Mobile Server Repository.

When the administrator publishes the application, the Packaging Wizard automatically uses the name that you entered in the virtual path as the name of the application root directory in the Mobile Server Repository. However, the administrator can change the name of the application root directory in the Mobile Server Repository by entering a different name for it when the administrator publishes the application.

Yes
Description A brief description of the mobile application.

When packaging a WAR file, the description must be set to the value of the element <description> found under the main element <web-app> in the web.xml file.

Yes
Application Classpath

[Web Applications Only]

The application classpath specifies where the classes (servlets, beans) for the application are located. The default application classpath is always the application root directory. To specify additional locations that the Mobile Server can search for application classes, add other directories or jar and zip files to the application classpath for web applications.

Entries must be separated by semicolons (;)

In addition, Web-to-Go automatically appends the following to the application classpath:

  1. Application root directory

  2. Classpath as specified in the 'Application' dialog in the Packaging Wizard

  3. Classes located under WEB-INF/classes

  4. All jar and zip files located in the directory WEB-INF/lib

  5. Classes located under the directory /shared/WEB-INF/classes

  6. All jar and zip files located in the directory /shared/WEB-INF/lib

  7. SYSTEM classpath

No
Default Page

[Web Applications Only]

The server location of the Web page that functions as the mobile application's entry point. This is a relative path to the repository directory. For example, if the server directory is /apps and the default page is index.htm, the Default Page is /apps/index.htm. The default page can be a servlet. A generic page is issued if the user does not specify a default page.

When packaging a WAR file, the default page must be set to the value of the element <welcome-file-list> in the web.xml file.

Yes
Local Application Directory The directory on the local machine that contains all components of the application. You can type this location or locate it using the 'Browse' button.

During development, the application root directory is set to the local application directory.

Yes
Icon

[Web Applications Only]

The GIF image of the mobile application is used as the application icon in the mobile workspace. Users may enter the icon name in the corresponding field or locate it using the 'Browse' button.

When packaging a WAR file, the description field must be set to the value of the element <large-icon> as a primary choice or <small-icon> as a secondary choice found under the main element <web-app> in the web.xml file.



2.1.3 Listing Application Files

Use the Files panel to list your application files and to specify their location on the local machine. The Packaging Wizard analyzes the contents of the Local Application Directory and displays each file's local path. As Table 2-3 describes, the Files tab contains the following field.

Figure 2-4 displays the Files tab.

Figure 2-4 Files Tab

Files tab

Table 2-3 Files Tab Description

Field Description Required
Local Path The absolute path of each mobile application file. Each entry on the list includes the complete path of the individual file or directory. Yes

You can add, remove, load, or compile any of the files that are listed in the 'Files' dialog. If you are creating a new application, the Packaging Wizard automatically analyzes and loads all files listed under the local directory when you proceed to the 'Files' dialog. If you are editing an existing application, upload your individual application files using the 'Load' button.

If you are importing a WAR file into an existing application, click the Import WAR File button on the 'Files' tab. Once you have specified the location of the WAR file, the 'Files' tab displays content of the WAR file.

2.1.3.1 Compile JSP (For Web Applications Only)

The 'Compile JSP' button enables you to compile your JSP files for deployment. If you click the 'Compile JSP' button, the following 'Compile JSP' dialog appears with detailed compilation information. If there are any errors, you should correct the JSP files before proceeding.

Figure 2-5 displays the Compile JSP Dialog.

Figure 2-5 Compile JSP Dialog

Compile JSP dialog

You can sort the files by their extensions or by the directory in which they are located. To sort files, click the 'By Extension' or 'By Directory' options.

2.1.3.2 Filters

When you click the 'Load' button, the 'Input' dialog appears. You can use the 'Input' dialog to create a comma-separated list of filters that either include or exclude application files from the upload process. To exclude a file, type a preceding minus sign (-) before the file name. For example, to load all files but exclude files with the .bak and .java suffixes, enter the following.

*,-*.bak,-*.java

Figure 2-6 displays the Input dialog.

Figure 2-6 Input Dialog

Input dialog

2.1.4 Adding Servlets (For Web Applications Only)

The Packaging Wizard analyzes servlets in the File tab and defines them on the Mobile Server. As displayed in Figure 2-7, you can view your application's servlets in the Servlets tab.

Figure 2-7 Servlets Tab

Servlets tab

As described in Table 2-4, the 'Servlets' tab includes the following fields.

Table 2-4 Servlets Tab Description

Field Description Required
Servlet Name The servlet's name. For example: DeleteDetail. You will then refer the servlet as:

application_virtualpath/servlet name

Yes
Servlet Class The fully qualified class of the servlets to be added. Yes

Using the 'Servlets' tab, you can add, remove, or load any servlets that are listed under the 'Servlets' tab. If you are creating a new application, the Packaging Wizard automatically lists all 'Servlets' based on files that are listed in the 'Files' tab. If you are editing an existing application, use the 'Load' button to locate and load individual servlets.

2.1.5 Entering Database Information

Using the Database tab, you can provide connection information and specify how the mobile application user connects to the replication master groups on the Oracle server.

Table 2-4 displays the Database tab.

Figure 2-8 Database Tab

Database tab

Enter the database name that you want to create on the client side. For example, a native Windows 32 application accesses the client database with this name. However, this is not required for web applications.

2.1.6 Defining Application Roles

Use the 'Roles' tab to define the Mobile Server application's roles. Developers create roles in the application's code and the Packaging Wizard re-declares them for the Oracle database. After you publish the application to the Mobile Server, you can assign roles to users and groups, using the Mobile Manager.

Figure 2-9 displays the Roles tab.

Figure 2-9 Roles Tab

Roles tab

As described in Table 2-5, the Roles tab includes the following field.

Table 2-5 Roles Tab Description

Field Description
Roles Assigns roles to the Web-to-Go/Mobile Server application.

All Web-to-Go/Mobile Server applications contain a default role. You can add or remove roles from the Roles dialog using the 'New' or 'Delete' button.

2.1.7 Defining Snapshots for Replication

Use the Snapshots tab to create replication snapshots for your application. A snapshot must have the same name as the database object such as a table or view. It must be unique across all applications. However, you must ensure that you use unique names when creating database objects. The Packaging Wizard enables you to create snapshots for the chosen platform. When you specify a view as the base object type, the Packaging Wizard enables you to specify the Parent Hint, Virtual Primary Hint, and the Primary Key Hint. For Web-to-Go, use the Windows 32 platform.

Figure 2-10 displays the Snapshots tab.

Figure 2-10 Snapshots Tab

Snapshots tab

Note:

Once you have specified a database connection, it is used for the remainder of your Packaging Wizard session. If you need to switch between an Oracle database and Oracle Database Lite, but have already established a connection, you must quit the Packaging Wizard application completely and run wtgpack.exe again.

Table 2-6 describes the Snapshots tab.

Table 2-6 Snapshots Tab Description

Field Description Required
Name The name(s) of the snapshot(s) associated with the Web-to-Go/Mobile Server application. It must be the same name as the underlining database object. Yes
Template Lists available snapshot templates. The template is a SQL statement that is used to create the snapshot. The template may contain variables. After you publish the template to the Mobile Server, you can specify user-specific template variables using the Mobile Manager. However, you cannot modify snapshots in the Mobile Manager. Yes
Weight This is the order of tables to be replicated. For tables with a master-detail relationship, the master table needs to be replicated first and therefore should have a lower weight. No

You can add or remove snapshots from the Snapshots tab using the 'New' or 'Delete' button. You can also import or edit snapshots using the 'Import' or 'Edit' button.


Note:

You can import multiple snapshots from the Snapshots tab or import one when you create a new table from the 'New Table Dialog'.

2.1.7.1 Creating New Snapshots

To create new snapshots, click 'New'. The 'New Snapshots' dialog appears. As Figure 2-11 displays, if you click the Server tab, the Server dialog appears, which contains fields for snapshot name, weight, owner, and SQL, as well as a check box for generating SQL.

Figure 2-11 New Snapshots Dialog - Server Tab

New snapshots dialog, server tab

For a description of Weight, see Section 2.1.7, "Defining Snapshots for Replication".

If you enable Generate SQL, you should provide a CreateTable SQL statement to construct the database table. Enter the SQL statement in the SQL field. At the end of the defining phase, you will have the option to generate a SQL file.

Use the Win32 tab for the Mobile Client for Web-to-Go.

If you click the Win32 tab, the following dialog appears.

Figure 2-12 Edit Snapshots Dialog - Win32 Tab

Edit snapshots dialog, Win32 tab

Create a new snapshot on the Mobile Client for Web-to-Go by modifying the following features in the New Snapshots dialog.

As Figure 2-12 describes, the New Snapshots dialog displays the following information.

Table 2-7 New Snapshots Dialog Description

Field Description
Updatable When selected, this check box creates an updatable snapshot of the named table.
Template Displays the snapshot template for the named table. You can modify the snapshot template. Administrators can instantiate variables for different users to this template using the Mobile Manager. For more information about template variables, see Section 2.1.7, "Defining Snapshots for Replication".

2.1.7.2 Creating Indexes for Snapshots

To create an index for a snapshot using the Packaging Wizard, use the following procedure.

  1. From the Snapshots dialog, select the Edit button to create an index from an existing snapshot, or the New button for creating a new snapshot and new index.

  2. Select the platform tab on the dialog which appears, for example Win 32. The SQL statement which defines your snapshot appears in the 'Template' field. Below that is an 'Indices' table; to create a new index, select the 'New' button beneath this table.

    As Table 2-8 describes, enter values in the Win32 tab of the Edit Snapshots dialog.

    Table 2-8 Win32 Tab - Edit Snapshots Dialog

    Field Description
    Create on Client If selected, creates the snapshot on the client machine.
    Updatable If selected, creates an updatable snapshot of the specified table or view.
    Base Object Type Select Table to include a table as the base object type.

    or

    Select View to include a view as the base object type.

    Conflict Resolution Select Server Wins to specify conflict resolution in favour of the server.

    or

    Select Client Wins to specify conflict resolution in favour of the client.

    DML Procedure To specify the DML procedure, enter the name of the Callout Package for DML operation.
    Refresh Type Select Fast Refresh to specify a quick refresh of the snapshot.

    or

    Select Complete Refresh to specify a complete refresh of the snapshot.

    Parent Hint To specify the parent hint, enter the Parent Table Name.
    Virtual Primary Hint To specify the virtual primary hint, enter the Base Object Name and Base Object Column in the corresponding fields.
    Template Displays the snapshot template for the named table. You can modify the snapshot template. Administrators can instantiate variables for different users to this template using the Mobile Manager. For more information about template variables, see Section 2.1.7, "Defining Snapshots for Replication".
    Primary Key Hint This section displays the table name, column name, and mapping column name of the snapshot.
    Indices This section displays the name, type, and column name of indices used in a snapshot.

  3. There are three columns in the 'Indices' table:

    1. Name - This is the name of the index.

    2. Type - Indexes can be Regular, Primary, or Unique. There is a drop down menu to select this.

    3. Columns - Enter the column name which the index uses.

2.1.7.3 Importing Snapshots

To import snapshots from an Oracle database or from Oracle Database Lite, click the 'Import' button. As Figure 2-13 describes, the database connection window appears if you have not specified a connection.

Figure 2-13 Connect to Database Dialog

Connect to database dialog

Enter the user name, password, and database URL for the Oracle database, or Oracle Database Lite from which you are importing your snapshot(s). The Tables window appears.


Note:

Use the following format when entering the database URL for an Oracle database: jdbc:oracle:oci8:@webtogo.world. For Oracle Database Lite, use jdbc:polite:webtogo.

Figure 2-14 displays the Tables dialog.

Figure 2-14 Tables Dialog

Tables dialog

Click the Schema list and choose the required schema from the list displayed. The Tables dialog displays views associated with the chosen schema. Select the view that you need to import. Click Add and click Close.

2.1.7.4 Editing Snapshots

To edit a snapshot, select the snapshot from the Snapshots dialog and click Edit. As displayed in Figure 2-15, the Edit Snapshots dialog appears.

Figure 2-15 Edit Snapshots Dialog - Win32 Tab

Edit snapshots dialog, Win32 tab

As described in Table 2-9, edit the snapshot by modifying the following features of the Edit Table window:

Table 2-9 Edit Snapshots Dialog - Win32 Tab Description

Feature Description
Create on Client When selected, the checkbox allows you to edit the snapshot on the Mobile Client for Web-to-Go.
Updatable When selected, this check box creates an updatable snapshot of the named table.
Template Displays the snapshot template for the named table. You can modify the snapshot template. Administrators can instantiate variables for different users to this template using the Mobile Manager.

2.1.8 Defining Sequences for Replication

Use the Sequences dialog to define offline sequence support for the Web-to-Go application. Web-to-Go uses sequences to assign unique primary key values to an application before it disconnects and is in offline mode. These unique primary key values are used for replication when the client goes back online. Sequences are important because they eliminate replication conflicts by preventing duplicate primary key values across disconnected applications. All sequences must have a unique name. You can accomplish this by modifying your sequence names by preceding them with your application name.

Figure 2-16 displays the Sequences tab.

Figure 2-16 Sequences Tab

Sequences tab

As described in Table 2-10, the Sequences dialog includes the following fields.

Table 2-10 Sequences Dialog Description

Field Description Required
Name The name of the sequence used by the Web-to-Go application in disconnected mode. Yes
Type The type of sequence used by the Web-to-Go application in disconnected mode.

Window. The window sequence assigns a unique range of values to each client. Window sequences are unique to each client and never overlap with those of other clients. When a client uses all the values in its sequence range, Web-to-Go recreates the sequence with a new, unique range of values the next time the client goes offline.

Yes
Start Value The sequence's start value on the Mobile Client for Web-to-Go. The sequence begins at this number and then increments according to the increment number you define. Yes
Increment The number by which the sequence increments on the Mobile Client for Web-to-Go, beginning at its start value. Yes
Window Size Defines the range of numbers in a window sequence. Yes
Threshold Defines the minimum range of required numbers in a window sequence. Web-to-Go creates a new sequence when the existing one reaches this range and when the client goes offline. Yes
Server Start The sequence's start value on the Oracle database. The sequence begins at this number and then increments according to the increment number you define. This number must be different from the sequence's start value on the Mobile Client for Web-to-Go. No
Server Increment The number by which the sequence increments on the Oracle database, beginning at its start value. No
Server Minimum The minimum start value for an ascending sequence on the Oracle database. For example, an ascending sequence could start at 1 and continue on in ascending order. No
Server Maximum The maximum start value for a descending sequence on the Oracle database. For example, a descending sequence could start at -1 and continue in descending order. No

You can add or remove sequences from the Sequences dialog by clicking the Add or Remove button.

2.1.8.1 Importing Sequences

To import sequences from an Oracle database, click the Import button. As Figure 2-17 displays, the Sequences dialog appears.

Figure 2-17 Sequences Dialog

Sequences dialog

Select the sequence you want to import, click Add, and then click Close.

To edit a sequence, select the sequence from the Sequences dialog and click Edit. As Figure 2-18 displays, the Edit Sequences dialog appears.

Figure 2-18 Edit Sequences Dialog

Edit sequences dialog

As Table 2-11 describes, edit the sequence by modifying the following features of the Edit Sequences dialog.

Table 2-11 Edit Sequences Dialog Description

Feature Description
Name The name of the sequence.
Create on Server When selected, this check box enables the options for creating a sequence on the Oracle database. Information entered by the user is used to generate a SQL script to create the sequence on the Oracle server.
Start Value The start value of the sequence on the Oracle database.
Increment The increment of the sequence on the Oracle database, beginning with its start value.
Minimum The minimum start value for an ascending sequence on the Oracle database. For example, an ascending sequence could start at 1 and continue in ascending order.
Maximum The maximum start value for a descending sequence on the Oracle database. For example, a descending sequence could start at -1 and continue in descending order.
Create on Client When selected, this check box enables the options for creating a sequence on the Mobile Client for Web-to-Go.
Type Defines the type of sequence on the Mobile Client for Web-to-Go. Options include the window and leapfrog sequences.
Start Value The sequence start value on the Mobile Client for Web-to-Go.
Increment The increment of the sequence on the Mobile Client for Web-to-Go, beginning with its start value.
Window Size The range of numbers that constitute a window sequence on the Mobile Client for Web-to-Go. This information is not used by the leapfrog sequence.
Threshold The minimum range of required numbers in a window sequence. Web-to-Go creates a new sequence when the existing one reaches this range and when the client goes offline. This information is not used by the leapfrog sequence.

2.1.9 Defining Application DDLs

Use the DDLs dialog to define any DDL (Data Definition Language) statements that the Web-to-Go application can execute the first time it goes offline. DDLs are only supported on Windows 32 and Windows CE platforms. All DDL statements must have a unique name and the weight must be specified for every DDL. One way to accomplish this is to modify your DDL names by preceding them with your application name. After you publish the application to the Mobile Server, you can create additional DDL statements using the Mobile Manager.

Figure 2-19 displays the DDLs dialog.

Figure 2-19 DDLs Dialog

DDLs dialog

As described in Table 2-12, the DDLs dialog includes the following fields.

Table 2-12 DDLs Dialog Description

Field Description
Name The DDL name.
DDL Statement Defines DDL statements with the Web-to-Go application. These DDL statements will be executed when the Web-to-Go application runs on the client.
Weight The order of DDLs to be executed on the Mobile Client.

You can add or remove DDLs from the DDLs dialog by clicking the Add or Remove button. When you click the ADD button, the New DDL dialog appears, as described in Figure 2-20.

Figure 2-20 New DDL Dialog

New DDL dialog

2.1.9.1 Importing Views and Index Definitions

To import views and index definitions from an Oracle database, click the Import button. As displayed in Table 2-12, the Import DDLs dialog appears.

Figure 2-21 Import DDLs Dialog

Import DDLs dialog

To import an index definition, click the Indexes tab and then click the schema from which you want to import an index. Select the index you want to import, click Add, and then click Close.

To import a view definition, click the Views tab and then click the schema from which you want to import a view. Select the view you want to import, click Add, and then click Close.

2.1.10 Editing Applications

You can edit applications by launching the Packaging Wizard and selecting "Edit an existing application." Although you can manually create or edit applications by writing or modifying an XML document that conforms to the Mobile Server's DTD file, for best results, you should use the Packaging Wizard to create or modify applications.

2.1.11 Troubleshooting

The Packaging Wizard also supports development mode. In this mode, the Packaging Wizard only enables you to define web application information, list the application files, compile JSPs, add servlets, and make registry changes. Since the application is packaged to your local machine, it requires neither connectivity nor database information.

To launch the Packaging Wizard in development mode, enter the following using the Command Prompt.

wtgpack -d

2.2 Packaging Wizard Synchronization Support

The Packaging Wizard and the Mobile Manager provide the ability to perform the most commonly used functions of the publish and subscribe model, package and publish applications, create or drop users, and create or drop subscriptions. More sophisticated functionality is provided by the Consolidator and Resource Manager APIs. Table 2-13 describes basic features.

Table 2-13 Packaging Wizard Synchronization Support

Function Packaging Wizard Mobile Manager API
Open Connection No No Yes
Create User No Yes Yes
Drop User No Yes Yes
Create Publication Yes No Yes
Create Publication Item Yes No Yes
Create Publication Item Index Yes No Yes
Drop Publication No Yes Yes
Drop Publication Item Special - See the Packaging Wizard documentation for more details. No Yes
Drop Publication Item Index Yes No Yes
Create Sequence Yes No Yes
Create Sequence Partition Yes No Yes
Drop Sequence Yes No Yes
Drop Sequence Partition Yes No Yes
Add Publication Item Yes No Yes
Remove Publication Item No No Yes
Create Subscription No Yes Yes
Deinstantiate Subscription No No Yes
Set Subscription Parameter No Yes Yes
Drop Subscription No Yes Yes
Commit Transaction No No Yes
Rollback Transaction No No Yes
Close Connection No No Yes

More advanced features of Consolidator are only generally available by using the Consolidator and Resource Manager APIs. Table 2-14 describes these features.

Table 2-14 Consolidator Advanced Function Description

Function Packaging Wizard Mobile Manager API
Create Virtual Primary Key Column Yes No Yes
Drop Virtual Primary Key Column Yes No Yes
Add Mobile DML Procedure Yes No Yes
Remove Mobile DML Procedure Yes No Yes
Reinstantiate Publication Item No No Yes
Parent Hint Yes No Yes
Dependency Hint Yes No Yes
Remove Dependency Hint Yes No Yes
Enable Publication Item Query Cache No No Yes
Disable Publication Item Query Cache No No Yes
Primary Key Hint Yes No Yes
Purge Transaction No No Yes
Execute Transaction No No Yes
Complete Refresh Yes Yes Yes
Execute Statement No No Yes
Generate Metadata No No Yes
Reset Cache No No Yes
Cache Dependencies No No Yes
Remove Cache Dependencies No No Yes
Get Current Time No No Yes
Authenticate No Yes Yes
Set Restricting Predicate No No Yes
Alter Publication Yes No Yes