4
Using the Region Modeling Tool

This document describes the Region Modeling Tool. Each section of this document presents a different topic. These sections include:

• Section 4.1, "Overview"

• Section 4.2, "Accessing the Region Modeling Tool"

• Section 4.3, "Managing Spatial Objects"

• Section 4.4, "Creating Location-Based Master Services and Folders"

• Section 4.5, "Creating Location-Based Services with Location-Specific Content"

4.1 Overview

The Wireless Edition enables you to create location-based services using the Region Modeling Tool. The Region Modeling Tool enables you to create services that are visible to Wireless Edition users at specific locations.

The Region Modeling Tool enables developers to create these location-based services by assigning a location to a folder or to a master service from the spatial data repository. The tool enables you to view a spacial object as a map image with its corresponding geometry. In addition, the tool enables you to access, view, and modify the data stored in the spatial database in the Wireless Edition repository.

Figure 4-1 The Region Modeling Tool

Text description of the illustration rmd_stal.gif

The Region Modeling Tool presents spatial data as a set of regions, which are divided into system-defined regions (SDRs) and user-defined regions (UDRs).

4.1.1 The System-Defined Region Hierarchy

The SDRs are administrative boundaries organized in a into hierarchy of subregions as follows:

Figure 4-2 Hierarchy of the System-Defined Region

Text description of the illustration rmd_sdrh.gif

The left frame of the Region Modeling tool presents the SDRs as a hierarchical directory organized by continent, country, state, county, and postal code nodes. Clicking one of these nodes displays its corresponding map and geometry (longitude/latitude) in the right frame, and its identifier (ID: 5055 in Figure 3-6, above), name, and description in the top frame.

In a typical SDR hierarchy, a continent node contains country nodes. Country nodes contain state nodes, and state nodes contain separate child folders for city, postal code, and county. If a country lacks states or provinces, then the country node has separate child folders for city, postal code, and county. If state data exists in any country, then all data for the postal code, city, or county must be contained in a state node.

Note: You cannot have state data and data for postal code, city, or county under country node.

Except for the continent region, which is at the top of the hierarchy, every item in the table of the hierarchy carries the region identifiers of its parent regions. For example, a county region carries the state identifier as well as the country identifier.

The Region Model Data Schema

The following is a description of a region model data schema.

Table 4-1 The Region Model Data Schema

Object	Value
Continent
ID	NOT NULL NUMBER
NAME	VARCHAR2(100)
DESCRIPTION	VARCHAR2(2000)
GEOMETRY	MDSYS.SDO_GEOMETRY
REFCNT	NUMBER
Country
ID	NOT NULL NUMBER
NAME	VARCHAR2(300)
CONT_ID	NUMBER
DESCRIPTION	VARCHAR2(2000)
GEOMETRY	MDSYS.SDO_GEOMETRY
REFCNT	NUMBER
State
ID	NOT NULL NUMBER
NAME	VARCHAR2(400)
CONT_ID	NUMBER
COUNTRY_ID	NUMBER
DESCRIPTION	VARCHAR2(2000)
GEOMETRY	MDSYS.SDO_GEOMETRY
REFCNT	NUMBER
County
ID	NOT NULL NUMBER
NAME	VARCHAR2(400)
COUNT_ID	NUMBER
COUNTRY_ID	NUMBER
STATE_ID	NUMBER
DESCRIPTION	VARCHAR2(2000)
GEOMETRY	MDSYS.SDO_GEOMETRY
REFCNT	NUMBER
City
ID	NOT NULL NUMBER
NAME	VARCHAR2(400)
COUNT_ID	NUMBER
COUNTRY_ID	NUMBER
STATE_ID	NUMBER
DESCRIPTION	VARCHAR2(2000)
GEOMETRY	MDSYS.SDO_GEOMETRY
REFCNT	NUMBER
Postalcode
ID	NOT NULL NUMBER
NAME	VARCHAR2(400)
COUNT_ID	NUMBER
COUNTRY_ID	NUMBER
STATE_ID	NUMBER
DESCRIPTION	VARCHAR2(2000)
Userdefined
ID	NOT NULL NUMBER
NAME	VARCHAR2(400)
REFCNT	NUMBER
TYPE	NUMBER
PARENT_FOLDER_ID	NUMBER
DESCRIPTION	VARCHAR2(2000)
GEOMETRY	MDSYS.SDO_GEOMETRY

Note: When you log into the Wireless Edition repository, you also log into the spatial database.

4.1.2 User-Defined Regions

In addition to the SDRs, you can create your own regions, or user-defined regions (UDRs). These UDRs can be constructed in two ways:

• A point location based on an address or a region around an address.

• An aggregate of existing SDRs.

For example, the Region Modeling Tool allows you to create a service that is available ten miles around a specific address. You can make an aggregate of areas, such as the New England states of Maine, New Hampshire, Vermont, Massachusetts, and Rhode Island.

Unlike the SDRs, the UDRs are not arranged into a hierarchy; however, users can organize their UDRs by creating folders.

4.2 Accessing the Region Modeling Tool

There are two methods for accessing the Region Modeling Tool: you can access it in its Standalone mode through the Tools menu in the Service Designer, or in its browse mode when using the Service Designer to create a location-based master service or folder.

In the Standalone mode, you can create both UDRs and load data into SDRs. For more information on using the Region Modeling Tool in its Standalone mode, see Section 4.3, "Managing Spatial Objects".

When you access the Region Modeling Tool while creating a master service or folder, you access the tool in the browse mode. In the browse mode, you create location based services by assigning regions to services and folders. In addition, you can create UDRs and search for regions. For more information on using the Region Modeling Tool in its browse mode, see Section 4.4.

4.3 Managing Spatial Objects

You use the Region Modeling Tool in its Standalone mode to view and manage regions.

4.3.1 Accessing the Region Modeling Tool in the Standalone Mode

To access the Region Modeling Tool in its Standalone mode:

1. Select the Tools Menu from the Service Designer.

2. Select Region Modeling Tool. The Region Modeling Tool appears.

Figure 4-3 The Region Modeling Tool with Region Menu Displayed

Text description of the illustration rmd_crs1.gif

4.3.2 Creating User-Defined Regions

You can create a UDR by selecting from the SDR hierarchy, or you can create a UDR from an address.

4.3.2.1 Creating a User-Defined Region from the SDR Hierarchy

To create a UDR using the SDR hierarchy:

1. Select the desired region or regions from the SDR hierarchy in the left frame. The Create UDR form appears.

2. Select the Create From Selection from the Region Menu.

   Note: You can select multiple regions by using <CONTROL> + click.

Figure 4-4 The Create UDR Form

Text description of the illustration rmd_crs2.gif

3. In the UDR form, enter a name for your region that is meaningful to you in the Node Name field. Likewise, add a description that is meaningful to you in the Description field. Click Finish.

Note: You can use the Create Folder function from the Region menu to create folders for your UDRs.

4. In the UDR hierarchy, click the UDR that you created. The map of your UDR displays in the right frame, and its ID, name, and description display at the top frame.

Figure 4-5 The User-Defined Region

Text description of the illustration rmd_crs3.gif

4.3.2.2 Creating a UDR from an Address

To create a UDR from an address:

1. From the Region menu, select Create From Address. The Create from Address screen appears.

Figure 4-6 The Create From Address Screen

Text description of the illustration rmd_cra2.gif

2. Enter the name of the location in the Name field.

3. In the Address section of the screen, enter the exact address.

4. In the Type of Region section, select either Point at Address radio box for the exact location, or the Region radio box for a defined parameter around the address.

5. Click Finish to complete the creation of a UDR from an address.

Note: You must have your geocoding service running when creating UDRs from addresses.

4.3.3 Deleting a User-Defined Region

To delete a UDR:

1. Right-click the UDR in the left frame of the Region Modeling Tool.

2. Select Delete.

   Note: You can only delete a region that has no services assigned to it. Regions with reference counts of 0 have no services assigned to them.

4.3.4 Creating a Folder

The UDRs are not automatically arranged in a hierarchy. They can be made easily accessible through the creation of folders. To create a folder:

1. Select the Create Folder option from the Region menu. The Create Folder appears.

Figure 4-7 The Create Folder Screen

Text description of the illustration rmd_crf1.gif

2. Enter a name that is meaningful to you in the Node Name field.

3. Enter a description that is meaningful to you in the Description field.

4. Click Finish.

4.3.5 Deleting a Folder

To delete a folder:

1. Right-click a folder in the left frame of the Region Modeling Tool.

2. Select Delete.

Note: You can only delete a folder that contains UDRs with reference counts of 0, meaning that no services have been assigned to them. Likewise, if you select multiple folders for deletion, all of the folders selected must contain UDRs with reference counts of 0.

4.3.6 Creating System-Defined Regions

You create system-defined regions (SDRs) by loading spatial data into the Wireless Edition repository.

Note: The Wireless Edition repository contains a small set of built-in sample system-defined regions.

The following sections describe two methods of loading data into the repository:

• Section 4.3.6.1, "Loading SDR Data Using SQL*Plus"

• Section 4.3.6.2, "Loading SDRs from the Region Modeling Tool"

4.3.6.1 Loading SDR Data Using SQL*Plus

The following example of loading additional spatial data using SQL*Plus assumes that your data exists in a table and that the geometry is in the Oracle spatial format (MDSYS.SDO_GEOMETRY). An example of a table called mystate of US data is as follows:

Table 4-2 Example of mystate Table

Name	Geometry	Description
Alabama	{.........}	... ...
Alaska	{.........}	... ...
California	{.........}	... ...

Perform the following steps to load SDR data.

1. Use the following SQL statement to find out the country ID and continent ID of the US:

   SELECT id, name, cont_id FROM Country;
   ...
   5009  USA  5001
   ...
   

In this example, the country ID for USA is 5009, and the continent ID is 5001.

2. Use the following SQL statement to insert data from the table mystate:

   INSERT INTO state
   (ID, CONT_ID, COUNTRY_ID, NAME, DESCRIPTION, GEOMETRY, REFCNT)
   SELECT idseq.nextval, 5001, 5009, name, description, geometry, 0 from mystate;
   

Note: The sequence name of the region ID is idseq. Also, if you are loading data for postal codes, cities, or counties directly under a country with a non-default hierarchy, you should use 0 as the state_id in the table for postal code, city, and county.

Formatting Geometry Data

Geometry data is assumed to be in WGS-84 format. If the geometry data is not in WGS-84 format, you need to transform it before loading using MDSYS.SDO_CS.TRANSFORM. The SRID for WGS-84 is 8307. For more information, refer to Oracle Spatial User's Guide and Reference.

Geometry data must be in Oracle 8.1.6 GTYPE or later. Otherwise, the user must migrate the data using SDO_MIGRATE.FROM_815_TO81X. For more information on GTYPE and the migration utility, refer to Oracle Spatial User's Guide and Reference.

4.3.6.2 Loading SDRs from the Region Modeling Tool

To load SRD data from the Region Modeling Tool:

1. Select the Region Modeling Tool from the Tools menu of the Service Designer.

2. Right-click a SDR, a menu appropriate to the the type and the status of the region appears. For example, right-clicking a continent node invokes the option to add country data to that continent hierarchy.

3. Add data by entering the appropriate information into the add data forms. The add data forms contain the following fields.

Table 4-3 Fields in the Add Data Screens

Field	Description
Table Name	The name of the table where the data is located.
Name Column	The name column of the table where the data is located.
Geometry Column	The geometry column of the table where the data is located.
Desc. Column	The description column of the table where the data is located.

4.3.6.2.1 Adding Data Under a Continent

To add data under a continent:

1. Right click a continent node and select Add Country. The Add Country Data form appears.

Figure 4-8 The Add Country Data Form

Text description of the illustration rmd_acnd.gif

2. In the Add Country Data dialog, enter the table name where your data is located.

3. In the Required Columns portion of the Add Country Data form, specify the Name Column, Geometry Column, and Description Columns of the table where the data is located.

4. In the Where Clause field, specify a WHERE clause for the SQL statement. For example, if you are loading the first ten rows of your table, you can specify rownum<11 as the WHERE clause.

   Note: This is an optional step. If you do not specify a WHERE clause, the Region Modeling tool loads all rows from the specified table.

5. Click Finish to complete the country SDR.

4.3.6.2.2 Adding Data Under a Country

To add data under a country:

1. Right-click the country node for which you want to load data.

2. If that country does not have existing data, a form with the options to add state, postal code, city and county appears.

3. Enter the appropriate information.

4. Click Finish to complete the SDR.

Note: If the country has data for state, then you can add only state data. If the country does not have state data but instead has postal code, city, or country data directly under it, then you can add data for postal code, city, or country.

4.3.6.2.3 Adding State Data Under a Country

1. Right-click a country node for which you want to add state data.

2. Select Add state. The Add State Data form appears.

Figure 4-9 The Add State Data Form

Text description of the illustration rmd_astd.gif

3. In the Required Columns portion of the Add State Data form, specify the Name Column, Geometry Column, and Description Columns of the table where the data is located.

4. In the Where Clause field, specify a WHERE clause for the SQL statement. For example, if you are loading the first ten rows of your table, you can specify rownum<11 as the WHERE clause.

   Note: This is an optional step. If you do not specify a WHERE clause, the Region Modeling tool loads all rows from the specified table.

5. Click Finish to complete the state SDR.

4.3.6.2.4 Adding Data for the Postal Code, County, or City

To add data for the postal code, county, or city:

1. Right-click the Postal Code, City, or County folders. The menu listing options to add data for postal code, county or city appears.

2. From the menu, select folder to which you want to add data. The form for the Add postal code, Add county, or Add city menu options appears.

3. Enter the table name where your data is located.

4. In the Required Columns portion, specify the Name Column, Geometry Column, and Description Columns of the table where the data is located.

5. In the Where Clause box, specify a WHERE clause for the SQL statement. For example, if you are loading the first ten rows of your table, you can specify rownum<11 as the WHERE clause.

   Note: This is an optional step. If you do not specify a WHERE clause, the Region Modeling tool loads all rows from the specified table.

6. Click Finish to complete the SDR.

4.3.7 Deleting a System-Defined Region

To delete an SDR:

1. Right-click the SDR in the left frame of the Region Modeling Tool.

2. Select Delete.

   Note: You can only delete SDRs in Standalone mode.

4.4 Creating Location-Based Master Services and Folders

You use the Region Modeling Tool in its browse mode when you make a service or a folder location-based by assigning a region. Folders and services created using the Region Modeling Tool are visibility location-based. Users access these services at specific locations.

In addition, you can use the Region Modeling Tool to create UDRs in the browse mode. For more information on creating UDRs, see Section 4.3.2.

4.4.1 Accessing the Region Modeling Tool in the Browse Mode

You can access the Region Modeling Tool in its browse mode through the Service Designer or through the Master Service Creation Wizard.

In the Service Designer, you access the Region Modeling tool by selecting the Location Dependent check box in the either the General tab (used for modifying a folder or service in the Wireless Edition repository tree), or the Create New Services or the Create New Folders forms (invoked by right-clicking the Wireless Edition repository) and then by clicking the Browse button. For more information on modifying a folder or a master service, see Section 3.2.3, "Modifying Objects" in Chapter 3, "Wireless Edition Services".

In the Master Service Creation Wizard, you access the Region Modeling Tool by selecting the Browse button in the Creating New Folder and Setting Service Properties screens.

4.4.1.1 Modifying a Folder or Service to be Location-Based

To assign a region to a folder or to a service from the Service Designer:

1. In the Wireless Edition repository tree, click the folder or service to which you wish to assign a region. The General tab appears.

2. In the General tab, click the Location Dependent check box. The Browse button appears.

3. Click the Browse Button. The Region Modeling Tool appears.

4. Right-click the region or regions that you wish to assign to the service or folder. Click Select.

Note: You can select multiple regions using <CTRL> + click.

5. The General tab reappears, showing the Area ID of the selected region.

4.4.1.2 Using the Service Designer to Create a Location-Based Folder or Service

To create a location-based folder or service from the Service Designer:

1. In the Wireless Edition repository tree, right-click the folder or service to which you wish to assign a region.

2. In the Create New Folders or Create New Services screens, click the Location Dependent check box. The Browse button appears.

3. Click the Browse Button. The Region Modeling Tool appears.

4. Right-click the region or regions that you wish to assign to the service or folder. Click Select.

   Note: You can select multiple regions using <CTRL> + click.

5. The Create New Folders or Create New Services screen reappears, showing the Area ID of the selected region.

4.4.1.3 Using the Master Service Creation Wizard to Create a Location-Based Service or Folder

To access the Region Modeling Tool from either the Create the Master Service Creation Wizard:

1. In either the Creating New Folder and Setting Service Properties screens, click the Browse button. The Region Modeling Tool appears.

Figure 4-10 The Creating Folder Screen of the Master Service Creation Wizard

Text description of the illustration rmd_cnf1.gif

2. In the left frame, select the region node to which you wish to assign a service. For example, from the SDR hierarchy, expand the North America node to the California node, and then expand to the San Francisco node.

3. Right click the region or regions (for example, San Francisco).

   Note: You can select multiple regions using <CTRL> + click.

4. Click Select. The Creating Folder screen reappears, showing the Area ID of the selected node (for example, 8686, the Area ID of San Francisco). A location has been assigned to the service folder.

4.5 Creating Location-Based Services with Location-Specific Content

In addition to services that are visible only at certain locations, the Wireless Edition edition also supports location-based services that generate content specific to the current location of the Wireless Edition user. For example, a user located in San Francisco would receive content specific to the San Francisco area, such as a listing of restaurants or business located in San Francisco. These services are supported through customized adapter implementation and location-aware runtime support.

To create a content-specific location-dependent service, you must access the current subscriber's location through the Runtime API or through derived location-related system parameters.

4.5.1 Accessing the Current Subscriber's Location Using the Runtime API

From a customized Java adapter, access the subscriber's current location by using either of the following methods:

Request.getCurrentLocation()
Session.getCurrentLocation()

Both of these methods return the geocoded physical location point. If there is no request-specific location information, the Runtime API returns the current location information, if any.

4.5.2 Accessing the Current Subscriber's Location Using Derived Location-Related System Parameters

You can use derived location-related system parameters if you pass the location information to a built-in adapter, such as the WebIntegration adapter, or the SQL adapter. The supported derived location-related system parameters include:

Table 4-4 The Derived Location-Related System Parameters

Parameters	Description
_Longitude	The longitude component of the caller's current location.
_Latitude	The latitude component of the caller's current location.
_Postalcode	The postal code from which the caller is initiating the request.
_State	The state from which the caller is initiating the request.
_Country	The country from which the caller is initiating the request.

To enable the passing of location information to the existing adapter, you must add the corresponding parameters to the service and make them mandatory. For example, if you wish to pass the postal code information of the current caller to the router service, you must add the _Postalcode parameter to the router service and make it mandatory. The Runtime fills in the value for the derived system parameters with the mandatory values that are missing.

Note: A content-specific location-based service is not always a location-dependent service that is visible only in a specific area. If a content-specific location-based service is not visible only at a certain location, you do not need to select the Location Dependent check box.