|
Oracle® Database Lite Developer's Guide
10g (10.2.0) Part No. B15920-01 |
|
 Previous |
 Next |
|
Oracle® Database Lite Developer's Guide
10g (10.2.0) Part No. B15920-01 |
|
|
Previous |
Next |
The following sections enable you to package and publish your Mobile application definitions using the Packaging Wizard.
After you have completed the code implementation for your application, you need to define the SQL commands that retrieve the data for the user snapshot—also known as a publication. MDW (as described in Chapter 5, "Using Mobile Database Workbench to Create Publications") is a graphical tool that enables you to define the publications for your application. Then, use the Packagine Wizard to package the application with the subscription and publish the final application product to the Mobile Server.
Create a new Mobile application definition—An application definition is more than the code that you have implemented. It consists of the implementation, the publication with its publication items, and other components. Use the Mobile Development Workbench (MDW) tool (as described in Chapter 5, "Using Mobile Database Workbench to Create Publications" for performing an iterative approach to defining your publications.
Edit an existing Mobile application definition—You can always go back and edit an existing Mobile application definition for tuning purposes, to modify the publication, or other reasons.
Package a Mobile application definition for easy deployment—Once the application is finished with development, you need to package the components into either a WAR or JAR file before you can publish the application definition.
Publish an application definition to the Mobile Server—You can either publish your application definition to the Mobile Server with the Packaging Wizard or through the Mobile Manager.
The following sections describe how to use the Packaging Wizard GUI tool:
Section 6.1.2, "Specifying New Application Definition Details"
Section 6.1.4, "Adding Servlets (For Web Applications Only)"
To launch the Packaging Wizard, enter the following using a Command Prompt window.
wtgpack
Figure 6-1 shows the Welcome screen for the Packaging Wizard, which enables you to create, edit, or remove the Mobile application definition as described fully in Table 6-1.
Table 6-1 Make a Selection Dialog
| Feature | Description |
|---|---|
| Create a new application definition | Define a new Mobile application definition with the application implementation, publication items, and so on. |
| Edit an existing application definition | Edit an existing Mobile application definition. When selected, all existing application definitions are presented in a drop-down box. Users can select the desired Mobile application definition from the list.
All applications listed in this list have been created or published using the Packaging Wizard. Any application definition created by MDW will not appear in this list. |
| Remove an existing application definition | Remove an existing Mobile application definition. When selected, all existing application definitions are presented in a drop-down box. Users can select the desired Mobile application definition from the list.
This option removes the application definition from the Packaging Wizard; it does not delete the application from within the Mobile Server. |
| Creating a new application definition using a WAR file | Create an application definition 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 definition | Select an application definition 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 definition. As Figure 6-2 displays, this dialog enables you to specify a platform. If you are packaging a WAR file, this dialog only displays Web based platforms.
Using the Application dialog, you can name a new Web-to-Go application and specify its storage location on the Mobile Server. As Figure 6-3 displays, the Application dialog includes the following fields.
Table 6-2 describes the Application dialog.
Table 6-2 Application Dialog Description
| Field Name | Description | Required |
|---|---|---|
| Application Name | The name of the new Mobile application definition.
When packaging a WAR file, the application name must be set to the value of the element |
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 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 6-3 displays, the name 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 |
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:
|
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 |
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 |
|
| Publication Name | Publication name of an existing application in the Mobile Server repository. You can enter the publication name or locate it using the Browse button. | No |
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 6-3 describes, the Files tab contains the following field.
Figure 6-4 displays the Files tab.
Table 6-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.
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 6-5 displays the 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.
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 6-6 displays the Input dialog.
The Packaging Wizard analyzes servlets in the File tab and defines them on the Mobile Server. As displayed in Figure 6-7, you can view your application's servlets in the Servlets tab.
As described in Table 6-4, the 'Servlets' tab includes the following fields.
Table 6-4 Servlets Tab Description
| Field | Description | Required |
|---|---|---|
| Servlet Name | The servlet's name. For example: DeleteDetail. You will then refer the servlet as:
|
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.
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.
Figure 6-8 displays the 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.
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 6-9 displays the Roles tab.
As described in Table 6-5, the Roles tab includes the following field.
Table 6-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.
If you did not use MDW to create a subscription, then you can 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 6-10 displays the 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 runwtgpack.exe again.
|
Table 6-6 describes the Snapshots tab.
Table 6-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'. |
To create new snapshots, click 'New'. The 'New Snapshots' dialog appears. As Figure 6-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.
For a description of Weight, see Section 6.1.7, "Defining Snapshots for Replication".
By default, Generate SQL is enabled, which automatically generates the SQL statement for you. Use the Win32 tab for the Mobile Client for Web-to-Go.
If you click the Win32 tab, the following dialog appears.
Create a new snapshot on the Mobile Client for Web-to-Go by modifying the following features in the New Snapshots dialog.
As Figure 6-12 describes, the New Snapshots dialog displays the following information.
Table 6-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 6.1.7, "Defining Snapshots for Replication". |
To create an index for a snapshot using the Packaging Wizard, use the following procedure.
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.
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 6-8 describes, enter values in the Win32 tab of the Edit Snapshots dialog.
Table 6-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 6.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. |
There are three columns in the 'Indices' table:
Name - This is the name of the index.
Type - Indexes can be Regular, Primary, or Unique. There is a drop down menu to select this.
Columns - Enter the column name which the index uses.
To import snapshots from an Oracle database or from Oracle Database Lite, click the 'Import' button. As Figure 6-13 describes, the database connection window appears if you have not specified a connection.
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:thin:@<MOBILESERVER_JDBC_URL>. For Oracle Database Lite, use jdbc:polite:webtogo.
|
Figure 6-14 displays the 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.
To edit a snapshot, select the snapshot from the Snapshots dialog and click Edit. As displayed in Figure 6-15, the Edit Snapshots dialog appears.
As described in Table 6-9, edit the snapshot by modifying the following features of the Edit Table window:
Table 6-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. |
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 6-16 displays the Sequences tab.
As described in Table 6-10, the Sequences dialog includes the following fields.
Table 6-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 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.
To import sequences from an Oracle database, click the Import button. As Figure 6-17 displays, the Sequences dialog appears.
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 6-18 displays, the Edit Sequences dialog appears.
As Table 6-11 describes, edit the sequence by modifying the following features of the Edit Sequences dialog.
Table 6-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. |
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 6-19 displays the DDLs dialog.
As described in Table 6-12, the DDLs dialog includes the following fields.
Table 6-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 6-20.
To import views and index definitions from an Oracle database, click the Import button. As displayed in Table 6-12, the Import DDLs dialog appears.
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.
You can edit application definitions by launching the Packaging Wizard and selecting "Edit an existing application definition."
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
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 Manager and Resource Manager APIs. Table 6-13 describes basic features.
Table 6-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 Data Synchronization are only generally available by using the Consolidator Manager and Resource Manager APIs. Table 6-14 describes these features.
Table 6-14 Data Synchronization 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 |
