15 Using Location Services

15.1.5.1 Provider Selection

Location services use a list of providers and support fail-over between them. The sequence in which providers are tried should ideally represent an order of preference. The preference ranking can be a simple ranking of providers, or it might be affected by region, time, performance, reliability, and cost. Whichever criteria are used, they are evaluated by a provider selection framework that determines provider order of preference.

The provider selection framework needs to be configured, as described in this section. If a service request is not satisfied by the framework, then either the provider selection framework implementation has been incorrectly configured or all providers have failed. You can find information about any problems or failures from the console log or the log file, as explained in Section 15.1.5.2.

You must select a provider selection framework to be used. To select the framework, use the OracleAS Wireless System Manager and follow these steps:

1. In the Wireless Server System tab page, click Site Administration.

2. Click to expand Component Configuration.

3. Click Location Services in the Configuration subsection. The Location Services page is displayed, as shown in Figure 15-3.

Figure 15-3 Location Services Page

Description of "Figure 15-3 Location Services Page"

Under Basic Configuration, for Provider Selector Class Name enter a provider selection framework implementation. Your choice of a provider selection framework implementation determines whether more or less complex rules can be used for provider selection. The following implementations are available:

• oracle.panama.spatial.core.ruleengine.SimpleRuleEngineImpl

  This simple implementation tries all providers until one succeeds. The sequence in which providers are tried is specified in the provider configuration list.

  However, this implementation can use more time than the other implementation, because it may issue queries to providers for regions that they do not cover. This implementation might also result in inappropriate selections, because some providers do not fail if they do not cover the requested region, but instead make a best attempt. For example, a provider might cover Europe, only, but receive a route request from San Francisco to Boston. This provider then tries its best and substitutes the places in Europe closest to Boston and San Francisco, respectively.

• oracle.panama.spatial.core.ruleengine.RuleEngineImpl

  This implementation can select providers based on whether or not they provide satisfactory coverage for a given country. Among all providers that provide satisfactory coverage for a given country, providers are tried based on the sequence in the provider configuration list.

  This implementation avoids time being wasted trying providers that do not provide coverage for a country or that provide unsatisfactory service (for example, if the cost is too high or the service quality is poor). However, this selection framework does require more configuration: lists of countries and country aliases need to be specified for each provider (although examples of such configurations are provided).

• oracle.panama.spatial.core.ruleengine.ExtendedRuleEngineImpl

  This implementation automatically adjusts to changing provider properties. It dynamically measures the performance and reliability of each provider. Based on these statistics, the provider list is dynamically re-ranked.

  This implementation automatically favors the providers that are currently fastest and most reliable. It can also be used for load balancing, in that the fastest and most reliable service will be used virtually all the time, until the heavy load slows it down sufficiently for other providers to compete. From that point on, other providers will start getting more requests than they did before.

{name}
{house number/house} {street}[ Apt {apt}]
{city} {state} {postal code}[-{postal code ext}]
{country}

{Name/name}
{Strasse/street/first line} {Hausnummer/house}[ Wohnung {Wohnung/apt}]
{PLZ/postal code} {Stadt/city}
 [{Bundesland/state}]
{Land/country}

15.1.5.2 Logging of Provider Selection Information

The provider selection framework implementation logs selection, success, and failure of providers in the OracleAS Wireless log file (for example, sys_panama.log). For example, you can look for events such as the following:

• The multiplexers for geocoding, mapping, and so on (other types of services) have been initialized.

• The provider selection framework implementation has been initialized.

• The proxies for geocoding, mapping, and so on (other types of services) have been initialized.

• A specific provider has been tried.

• A specific provider has failed.

• A specific provider has succeeded.

• All providers have failed.

15.1.5.3 Logging of Provider Performance Information

The provider selection framework implementation logs provider performance statistics. For each request made to a provider, the following information is logged, regardless of whether the provider succeeds or fails:

• Provider name

• Provider proxy Java class

• Time spent (in ms)

• Success (true or false)

• Time that request was made (timestamp)

The performance information is written to a table named PTG_LBS_LOG. You can see this information using the Wireless System Manager, as follows:

1. In the Wireless Server System tab page, click Site Performance.

2. In the Component Performance section, click Location-Related.

15.1.6.1 Geocoding API

This section describes the geocoding API for location application components.

Two of the following classes, Point and Location, are used by the whole API and are not specific to geocoding. However, they are described here because they represent components central to the geocoding service, both for input and output.

15.1.6.2 Geocoder Interface

The Geocoder interface defines how an application programmer accesses the geocoding service. An object of a class implementing this interface is returned by the SpatialManager.

15.1.10.1 Routing Settings

Routing can be influenced by preferences or requirements, called routing options. These options are combined in a set, called routing settings. There are two types of routing options: basic options and secondary options.

Basic options include:

• Whether maps (images) are requested

• Whether geometries (route coordinates) are requested

Secondary options include:

• Optimization method, such as shortest distance or shortest driving time

• Route properties to avoid, such as toll roads, ferry lanes, or limited-access highways

• Map sizes

Secondary options can be mandatory or preferred:

• If a secondary option is mandatory but not supported by the provider, the API will automatically fail over to the next provider.

• If a secondary option is preferred but not supported by the provider, the API will not check to see if other providers support the option.

If the application developer requests a secondary option without specifying whether it is mandatory or preferred, the following defaults are applied:

• Optimization method: preferred

• Avoid Ferry: preferred

• Avoid Limited Access Hwy: preferred

• Avoid Toll: preferred

• Overview Map size: mandatory

• Maneuver Map size: mandatory

• Overview Map scale and zoom level: preferred

• Maneuver Map scale and zoom level: preferred

15.1.10.2 Routing Results

The application can query the following components of a returned route:

• List of maneuvers

• Total distance

• Total estimated driving time

• Overview map

An overview map shows the source and destination, with the route highlighted.

A set of maneuvers (driving directions) is returned as part of the routing result. Each maneuver corresponds to a driving instruction and contains the following information:

• Textual narrative

• Distance traveled during or prior to this maneuver ("After how many miles do I have to make this right turn?")

• Detailed maneuver map

• Geometry (list of coordinate points, longitude/latitude)

Maps of the complete route or maneuvers can be requested as Java Image objects or as Strings representing a URL.

15.1.10.3 Support for Multiple Languages

If the routing provider supports multiple languages, the API chooses a language based on the Java locale object specified in the request to the router. The language setting can affect the maneuver narratives and distance measures.

15.1.10.4 Routing API

This section describes the routing API for location application components.

15.1.11.1 Different Approaches Among Yellow Pages Providers

Several providers offer YP services on the Web; however, the approaches taken by these providers differ significantly and do not offer a uniform interface. Furthermore, the respective approaches are not final in their methodology and can be expected to change.

A unifying pattern in the various approaches is that businesses are categorized by subject and location. The location component is well understood in that either a ZIP code or the combination of a city and state can be used to determine the location.

The categorization of businesses, on the other hand, is not uniformly implemented. Some providers offer a flat list of categories, user-selected by simple substring matching. Another approach is a 3-level or 4-level hierarchical organization of subcategories, often with a fanout of 20 to 50, sometimes more than 100. A user might start the hierarchy traversal at the root of the hierarchy (by default). Alternatively, a user might enter a keyword that is matched to an appropriate starting point within the hierarchy. Such keyword matching might go beyond simple substring search and result in more intelligent choices.

15.1.11.2 Business Directory Category Configuration

Support for business categories and the hierarchy of categories is provided through an XML configuration file. (You should view and modify business directory provider information using the OracleAS Wireless System Manager; however, you must view and modify business directory category information using the XML file.)

The category hierarchy definition file in Example 15-1 represents the custom hierarchy of business directory categories. Each category can have any number of subcategories. There is no restriction to the level of nesting. A category can be linked to multiple business directory content providers. The flexibility allowed by this file accommodates the different approaches of various business directory service providers, as discussed in Section 15.1.11.1.

<?xml version="1.0" standalone="yes"?>
<Categories>
  ...
  <Category
    CategoryName  = "Berry crops">
    <Provider
      Name  = "..."
      Parameter  = "..."/>    
      <Category
      CategoryName  = "Cranberry farm">
      <Provider
        Name  = "..."
        Parameter  = "..."/>
    </Category>
  </Category>
  ...
  <Category
    CategoryName  = "Ornamental nursery products">
    <Provider
      Name  = "..."
      Parameter  = "..."/>    
    <Category
      CategoryName  = "Florists' greens and flowers">
      <Provider
        Name  = "..."
        Parameter  = "..."/>
    </Category>
      <Category
      CategoryName  = "Bulbs and seeds">
      <Provider
        Name  = "..."
        Parameter  = "..."/>
    </Category>
  </Category>
  <Category
    CategoryName  = "Crops grown under cover">
    <Provider
      Name  = "..."
      Parameter  = "..."/>
    <Category
      CategoryName  = "Mushrooms grown under cover">
      <Provider
        Name  = "..."
        Parameter  = "..."/>
    </Category>
  </Category>
  ...
</Categories>

15.1.11.3 Business Directories (Yellow Pages) API

The application developers can traverse the category hierarchy by using the functions in the YPFinder interface. For any resulting category, the following can be requested:

• List of businesses

• List of direct subcategories

• List of direct or indirect subcategories containing a substring

15.1.12.1 Traffic Report Caching

Traffic report information is cached at the city level. The first time that a traffic report on a city is fetched, the report is written to the traffic report cache. The cached report is considered invalid after a maximum cache age time (for example, 15 minutes), which can be set using the System Manager.

A network round-trip operation to the traffic service provider is required to update the cached traffic report for the city. The cached report is updated only when both of the following conditions are true:

• A query is made for the city or for any Spatial geometry (route or point with radius) that is in or partially in the city (that is, where the queried geometry spatially interacts with the city's geometry).

• The cached report for the city is older than the maximum cache age time.

15.1.12.2 Traffic XML Requests and Responses

Example 15-2 shows a city-level request in XML format for traffic information for Boston.

<?xml version="1.0" encoding="UTF-8"?>
<traffic_request>
  <query_list>
    <query_info 
query_type="city_level_query" 
city_name="boston" 
state_name="MA" 
country_name="US"
    />
  </query_list>
</traffic_request>

<?xml version="1.0"  encoding="UTF-8"?>
<traffic_response>
 <report_list>
  <traffic_report>
    <provider 
    name="Trafficstation" 
    covered_city_name="Boston" 
    state_name="MA" 
    country_name="US"/>
    <report_time month="6" day="19" year="2001" hour="5" minute="28" meridian =
      "PM"/>
      <unit distance_unit="MILES" time_unit="MINUTE"/>
    <incident_list>
      <incident id = "1">
        <incident_type>ACCIDENT</incident_type>
        <description>CAR ACCIDENT</description>
        <route type = "Interstate" name = "I-93" direction = "SOUTH"/>
        <geo_location  longitude = "-71.0607" latitude  = "42.3659" radius =
           "5.0"/>
        <location_range>
          <at_location>EXIT 26</from_location>
        </location_range>
        <time_range>
          <from_time  month = "6" day = "19" year = "2001" hour = "5" minute =
             "28" meridian = "PM"/>
          <to_time  month = "6" day = "19" year = "2001" hour = "5" minute =
             "28" meridian = "PM"/>
         </time_range>
        <severity>HEAVY</severity>
        <speed>15.0</speed>
        <impact>EXPECT DELAY</impact>
        <advice>TAKE LEFT LANE</advice>
      </incident>
      <incident id = "2">
        <incident_type>CONSTRUCTION</incident_type>
        <description>REGULAR MAINTENANCE</description>
        <route type = "Interstate" name = "I-95" direction = "NORTH"/>
        <geo_location  longitude = "-71.3555" latitude  = "42.3601" radius =
          "30.0"/>
        <location_range>
          <at_location>EXIT 36</at_location>
        </location_range>
        <time_range>
          <at_time  month = "6" day = "19" year = "2001" hour = "5" minute =
             "28" meridian = "PM"/>
         </time_range>
        <severity>MINOR</severity>
        <speed>35.0</speed>
        <impact>EXPECT DELAY</impact>
        <advice>USE I-495</advice>
      </incident>
    </incident_list>
  </traffic_report>
 </report_list>
</traffic_response>

15.1.12.3 Traffic Java API

This section describes the traffic Java API for location application components.

15.1.12.4 Traffic Service Configuration

After the region modeling data and city coverage data has been loaded into the repository during the Wireless installation, you can add traffic providers and supported cities for a provider.

15.2.1.1 JSP Examples for Location Services

This section includes several examples of JSP code to perform operations that involve location services. In these examples, addresses are specified in the points attribute of the appropriate tag (<map> or <route>).

Example 15-4 displays small and large maps of two locations.

<%@ taglib uri="LocationTags" prefix="loc" %>

<%!
  public String transformString(String orig)
  {
    String result = "";
    for (int i=0;i<orig.length();i++)
    {
      if (orig.charAt(i) == '&')      result = result + "&amp;";
      else if (orig.charAt(i) == '<') result = result + "&lt;";
      else if (orig.charAt(i) == '>') result = result + "&gt;";
      else                            result = result + orig.charAt(i);
    }
    return result;
  }
%>

<SimpleResult>
    <loc:address
      name="NEDC"
      type="oracle.panama.model.Location"
      businessName="NEDC"
      firstLine="1 Oracle Dr"
      city="Nashua"
      state="NH"
      postalCode="03062"
      country="US"/>
    <loc:map
      name="NEDCSmall" type="oracle.panama.spatial.jsptags.beans.Map" xres="400"
         yres="300" points="NEDC">
    </loc:map>

    <loc:address
      name="HQ"
      type="oracle.panama.model.Location"
      businessName="HQ"
      firstLine="500 Oracle Parkway"
      city="Redwood City"
      state="CA"
      postalCode="94065"
      country="US"/>
    <loc:map name="HQSmall" type="oracle.panama.spatial.jsptags.beans.Map"
       xres="400" yres="300" points="HQ">
    </loc:map>

    <loc:map name="BothSmall" type="oracle.panama.spatial.jsptags.beans.Map"
       xres="400" yres="300" points="NEDC HQ"/>
    <loc:map name="NEDCLarge" type="oracle.panama.spatial.jsptags.beans.Map"
       xres="800" yres="600" points="NEDC"/>
    <loc:map name="HQLarge"   type="oracle.panama.spatial.jsptags.beans.Map"
       xres="800" yres="600" points="HQ"/>
    <loc:map name="BothLarge" type="oracle.panama.spatial.jsptags.beans.Map"
       xres="800" yres="600" points="NEDC HQ"/>

    <SimpleImage target="<%= transformString(NEDCLarge.toString()) %>"
       src="<%= transformString(NEDCSmall.toString()) %>"/>

    <SimpleImage target="<%= transformString(HQLarge.toString()) %>"
       src="<%= transformString(HQSmall.toString()) %>"/>

    <SimpleImage target="<%= transformString(BothLarge.toString()) %>"
       src="<%= transformString(BothSmall.toString()) %>"/>
</SimpleResult>

<%@ taglib uri="LocationTags" prefix="loc" %>

<%!
  public String transformString(String orig)
  {
    String result = "";
    for (int i=0;i<orig.length();i++)
    {
      if (orig.charAt(i) == '&')      result = result + "&amp;";
      else if (orig.charAt(i) == '<') result = result + "&lt;";
      else if (orig.charAt(i) == '>') result = result + "&gt;";
      else                            result = result + orig.charAt(i);
    }
    return result;
  }
%>

<SimpleResult>
  <loc:address
    name="NEDC"
    type="oracle.panama.model.Location"
    businessName="NEDC"
    firstLine="1 Oracle Dr"
    city="Nashua"
    state="NH"
    postalCode="03062"
    country="US"/>
  <loc:address
    name="HQ"
    type="oracle.panama.model.Location"
    businessName="HQ"
    firstLine="500 Oracle Parkway"
    city="Redwood City"
    state="CA"
    postalCode="94065"
    country="US"/>
  <loc:route name="myRoute" type="oracle.panama.spatial.jsptags.beans.Route"
     xres="800" yres="600" points="NEDC HQ">
  </loc:route>

  <SimpleImage src="<%= transformString(myRoute.getMap()) %>"/>

  <SimpleText>
    <loc:iterateManeuvers name="aManeuver" type="oracle.panama.spatial.jsptags.beans.Maneuver" routeID="myRoute">
      <SimpleTextItem>
        <%= aManeuver.getNarrative() %>
      </SimpleTextItem>
    </loc:iterateManeuvers>
  </SimpleText>
</SimpleResult>

<%@ taglib uri="LocationTags" prefix="loc" %>

<%!
  public String transformString(String orig)
  {
    String result = "";
    for (int i=0;i<orig.length();i++)
    {
      if (orig.charAt(i) == '&')      result = result + "&amp;";
      else if (orig.charAt(i) == '<') result = result + "&lt;";
      else if (orig.charAt(i) == '>') result = result + "&gt;";
      else                            result = result + orig.charAt(i);
    }
    return result;
  }
%>

<SimpleResult>
  <loc:address
    name="HQ"
    type="oracle.panama.model.Location"
    businessName="HQ"
    firstLine="500 Oracle Parkway"
    city="Redwood City"
    state="CA"
    postalCode="94065"
    country="US"/>

  <loc:businesses
    name="starbucks"
    type="java.util.Collection"
    businessName="Starbucks"
    centerID="HQ"
    nearestN="10"/>
  <loc:map name="starbucksMap" type="oracle.panama.spatial.jsptags.beans.Map"
     xres="800" yres="600" points="starbucks">
  </loc:map>

  <SimpleImage src="<%= transformString(starbucksMap.toString()) %>"/>

  <SimpleText>
  <loc:iterateBusinesses name="singleStarbucks" type="oracle.panama.model.Point"
     collection="starbucks">
    <SimpleTextItem> <%= singleStarbucks %> </SimpleTextItem>
  </loc:iterateBusinesses>
  </SimpleText>
</SimpleResult>

<%@ taglib uri="LocationTags" prefix="loc" %>

<%!
  public String transformString(String orig)
  {
    String result = "";
    for (int i=0;i<orig.length();i++)
    {
      if (orig.charAt(i) == '&')      result = result + "&amp;";
      else if (orig.charAt(i) == '<') result = result + "&lt;";
      else if (orig.charAt(i) == '>') result = result + "&gt;";
      else                            result = result + orig.charAt(i);
    }
    return result;
  }
%>

<SimpleResult>
  <loc:category name="automotive"       type="oracle.panama.spatial.yp.YPCategory" categoryName="Automotive">
  </loc:category>

  <loc:category name="automotiveDealers"
     type="oracle.panama.spatial.yp.YPCategory" categoryName="Dealers"
     parentCategory="automotive">
  </loc:category>

  <loc:category name="newAutomotiveDealers"
     type="oracle.panama.spatial.yp.YPCategory" categoryName="New"
     parentCategory="automotiveDealers">
  </loc:category>

  <loc:businesses name="dealers" type="java.util.Collection"
     categoryID="newAutomotiveDealers" country="US" state="CA"
     city="San Francisco"/>

  <loc:map name="dealerMap" type="oracle.panama.spatial.jsptags.beans.Map"
     xres="800" yres="600" points="dealers">
  </loc:map>

  <SimpleImage src="<%= transformString(dealerMap.toString()) %>"/>

  <SimpleText>
  <loc:iterateBusinesses name="dealer" type="oracle.panama.model.Point"
     collection="dealers">
    <SimpleTextItem>
      <%= transformString(dealer.toString()) %>
    </SimpleTextItem>
  </loc:iterateBusinesses>
  </SimpleText>
</SimpleResult>

15.2.1.2 addMembers

The addMembers tag adds one or more members to a mobile community. For an explanation of mobile communities, see Section 15.3.2.6, "Mobile Communities".

Table 15-3 lists the addMembers tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example adds the user named Song, at the request of the user named Mike, to the mobile community associated with the variable named comm_private. It also creates a java.util.Enumeration object of members of this community, and displays this object.

<loc:addMembers
      name="add_members"
      type="Boolean"
      userName="Mike"
      communityID="comm_private" 
      communityMembers="Song" />
<loc:listAllMembers
      name="list_all_mem1"
      type="java.util.Enumeration"
      communityID="comm_private" />
<%= list_all_mem1.toString() %>

15.2.1.3 address

The address tag specifies an address to be geocoded, located on a map, or used as the start or end address of a route or as the center for a business directory query.

Table 15-3 lists the address tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates a route named myRoute between two addresses (a person's office and home), displays a map of the route followed by a horizontal rule, and presents each driving maneuver (using the iterateManeuvers tag and the getMap and getNarrative function calls) followed by a horizontal rule. Each driving maneuver description is also a link that users can click to display a map of the maneuver.

<loc:route name="myRoute" type="oracle.panama.spatial.jsptags.beans.Route" xres="800" yres="600">
   <loc:address
        name="office"
        type="oracle.panama.model.Location"
        businessName="My office"
        firstLine="1 Oracle Dr"
        city="Nashua"
        state="NH"
        postalCode="03062"
        country="US"/>
   <loc:address
        name="home"
        type="oracle.panama.model.Location"
        businessName="My home"
        firstLine="2 Royal Crest Dr"
        city="Nashua"
        state="NH"
        postalCode="03060"
        country="US"/>
</loc:route>

<img src="<%= myRoute.getMap() %>">
<HR>

<loc:iterateManeuvers name="aManeuver" type="oracle.panama.spatial.jsptags.beans.Maneuver" routeID="myRoute">
      <a href="<%= aManeuver.getMap() %>">
        <%= aManeuver.getNarrative() %>
      </a>
      <HR>
</loc:iterateManeuvers>

15.2.1.4 businesses

The businesses tag creates a collection (of oracle.panama.spatial.yp.YPBusiness objects) of businesses that share one or more attributes.

Table 15-4 lists the businesses tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example of the businesses tag specifies all businesses named Borders in the state of California in the United States. The use of the map tag to enclose the businesses tag causes a map to be created that includes and labels each Borders bookstore.

<loc:map name="map1" type="oracle.panama.spatial.jsptags.beans.Map" 
       xres="1000" yres="500">
   <loc:businesses name="bord" type="java.util.Collection" businessName="Borders"
        country="US" state="CA"/>
</loc:map>

15.2.1.5 category

The category tag creates a business category (an oracle.panama.spatial.yp.YPCategory object).

Table 15-5 lists the category tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example uses two category tags. The first category tag creates an object named cat_auto that specifies a category named Automotive. The second category tag creates an object named cat_dealers that specifies a category named Dealers that is a child of the cat_auto (Automotive) parent category.

<loc:category name="cat_auto" type="oracle.panama.spatial.yp.YPCategory"
   categoryName="Automotive" />
<loc:category name="cat_dealers" type="oracle.panama.spatial.yp.YPCategory"
   parentCategory="cat_auto" categoryName="Dealers" />

15.2.1.6 createPrivateCommunity

The createPrivateCommunity tag creates a private mobile community. For an explanation of mobile communities, including types of communities, see Section 15.3.2.6, "Mobile Communities".

Table 15-6 lists the createPrivateCommunity tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates a private community owned by user Mike and including two users (Mike and Jing). If the community already exists, it is not created. It also displays information about the community.

<loc:createPrivateCommunity
      name="comm_private"
      type="oracle.panama.model.Community"
      userName="Mike"
      communityName="My Private Community" 
      communityMembers="Mike Jing"
      returnNullIfExists="FALSE" />
<%= comm_private.toString() %>

15.2.1.7 createSharedCommunity

The createSharedCommunity tag creates a shared mobile community. For an explanation of mobile communities, including types of communities, see Section 15.3.2.6, "Mobile Communities".

Table 15-7 lists the createSharedCommunity tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates a shared community owned by user Mike and including two users (Mike and Jing). If the community already exists, it is not created. It also displays information about the community.

<loc:createSharedCommunity
      name="comm_shared"
      type="oracle.panama.model.Community"
      userName="Mike"
      communityName="My Shared Community" 
      communityMembers="Mike Jing"
      returnNullIfExists="FALSE" />
<%= comm_private.toString() %>

15.2.1.8 createSystemCommunity

The createSystemCommunity tag creates a system mobile community. For an explanation of mobile communities, including types of communities, see Section 15.3.2.6, "Mobile Communities".

Table 15-8 lists the createSystemCommunity tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates a system community owned by user Mike and including two users (Mike and Jing). If the community already exists, it is not created. It also displays information about the community.

<loc:createSystemCommunity
      name="comm_system"
      type="oracle.panama.model.Community"
      userName="Mike"
      communityName="My System Community" 
      communityMembers="Mike Jing"
      returnNullIfExists="FALSE" />
<%= comm_private.toString() %>

15.2.1.9 defaultLocationMark

The defaultLocationbMark tag creates an object that represents the default location mark for a specified user. You can use this tag to find a user's default location mark.

Table 15-9 lists the defaultLocationbMark tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates an object representing the default location mark for user Mike, and it displays information about that object.

<loc:defaultLocationMark
      name="user_mark"
      type="oracle.panama.model.LocationMark"
      userName="Mike"  />
<%= user_mark.toString() %>

15.2.1.10 deleteCommunity

The deleteCommunity tag deletes a private, shared, or system mobile community. For an explanation of mobile communities, including types of communities, see Section 15.3.2.6, "Mobile Communities".

Table 15-10 lists the deleteCommunity tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example deletes, at the request of the user named Mike, the community named My Private Community, and it displays the result of the operation (TRUE or FALSE).

<loc:deleteCommunity
      name="delete_comm1"
      type="Boolean"
      userName="Mike"
      communityName="My Private Community"  />
<%= delete_comm1.toString() %>

15.2.1.11 drivingDistance

The drivingDistance tag presents the driving distance for a route or driving maneuver, as determined by the provider.

Table 15-11 lists the drivingDistance tag parameters. Although route and maneuver are listed as optional, you must specify one of these parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates a route named myRoute between two addresses (a person's office and home), and displays the driving distance for the route.

<loc:route name="myRoute" type="oracle.panama.spatial.jsptags.beans.Route" xres="800" yres="600">
   <loc:address
        name="office"
        type="oracle.panama.model.Location"
        businessName="My office"
        firstLine="1 Oracle Dr"
        city="Nashua"
        state="NH"
        postalCode="03062"
        country="US"/>
   <loc:address
        name="home"
        type="oracle.panama.model.Location"
        businessName="My home"
        firstLine="2 Royal Crest Dr"
        city="Nashua"
        state="NH"
        postalCode="03060"
        country="US"/>
</loc:route>
<loc:drivingDistance name="drive_dist" type="String" route="myRoute" />
<%= drive_dist.toString() %>

15.2.1.12 drivingTime

The drivingTime tag creates an object containing the estimated driving time for a route.

Table 15-12 lists the drivingTime tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates a route named myRoute between two addresses (a person's office and home), and displays the driving time for the route.

<loc:route name="myRoute" type="oracle.panama.spatial.jsptags.beans.Route" xres="800" yres="600">
   <loc:address
        name="office"
        type="oracle.panama.model.Location"
        businessName="My office"
        firstLine="1 Oracle Dr"
        city="Nashua"
        state="NH"
        postalCode="03062"
        country="US"/>
   <loc:address
        name="home"
        type="oracle.panama.model.Location"
        businessName="My home"
        firstLine="2 Royal Crest Dr"
        city="Nashua"
        state="NH"
        postalCode="03060"
        country="US"/>
</loc:route>
<loc:drivingTime name="drive_time" type="String" route="myRoute" />
<%= drive_time.toString() %>

15.2.1.13 geocode

The geocode tag specifies an address to be geocoded, located on a map, or used as the start or end address of a route or as the center for a business directory query.

Table 15-13 lists the geocode tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example of the geocode tag specifies an address (for a store named Mike's Hardware) to be geocoded.

<loc:geocode
  name = "hardware1"
  type = "oracle.panama.model.Location"
  businessName = "Mike's Hardware"
  houseNumber = "22"
  streetName = "Monument Sq"
  city = "Concord"
  state = "MA"  
  postalCode = "01742"
  country = "US"
  makeCorrections = "TRUE"  />

15.2.1.14 geometry

The geometry tag creates a java.util.List object of points of type oracle.panama.model.Point.

Table 15-14 lists the geometry tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.) You must specify the points, route, or maneuver parameter.

The following example creates a route between a user's office and home addresses, uses the geometry tag to create an unformatted list of points along the route, and displays the list.

<loc:route name="myRoute" type="oracle.panama.spatial.jsptags.beans.Route" xres="800" yres="600" requestGeom="true">
   <loc:address
        name="office"
        type="oracle.panama.model.Location"
        businessName="My office"
        firstLine="1 Oracle Dr"
        city="Nashua"
        state="NH"
        postalCode="03062"
        country="US"/>
   <loc:address
        name="home"
        type="oracle.panama.model.Location"
        businessName="My home"
        firstLine="2 Royal Crest Dr"
        city="Nashua"
        state="NH"
        postalCode="03060"
        country="US"/>
</loc:route>

<loc:geometry name="my_geom" type="java.util.List" route="myRoute" />
<%= my_geom.toString() %>

15.2.1.15 getCommunity

The getCommunity tag returns the object associated with the specified name of a private, shared, or system mobile community. For an explanation of mobile communities, including types of communities, see Section 15.3.2.6, "Mobile Communities".

Table 15-15 lists the getCommunity tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example returns, at the request of the user named Mike, the community named My Private Community, and it displays information about the community.

<loc:getCommunity
      name="get_comm"
      type="oracle.panama.model.Community"
      userName="Mike"
      communityName="My Private Community"  />
<%= get_comm.toString() %>

15.2.1.16 iterateBusinesses

The iterateBusinesses tag presents individually the businesses in a collection returned by the businesses tag.

Table 15-16 lists the iterateBusinesses tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates a map that shows the 10 Starbucks business locations nearest to Oracle headquarters, and for each location displays information about it followed by a horizontal rule. Each line of information is a link that the user can click to display a detailed map of the location and its surrounding area.

<loc:address
      name="HQ"
      type="oracle.panama.model.Location"
      businessName="HQ"
      firstLine="500 Oracle Parkway"
      city="Redwood City"
      state="CA"
      postalCode="94065"
      country="US"/>
<loc:map name="starbucksMap" type="oracle.panama.spatial.jsptags.beans.Map" xres="800" yres="600">
    <loc:businesses
        name="starbucks"
        type="java.util.Collection"
        businessName="Starbucks"
        centerID="HQ"
        nearestN="10"/>
</loc:map>

<img src="<%= starbucksMap %>">
<HR>

<loc:iterateBusinesses name="singleStarbucks" type="oracle.panama.spatial.yp.YPBusiness" collection="starbucks">
  <loc:map name="singleStarbucksMap" type="oracle.panama.spatial.jsptags.beans.Map" xres="800" yres="600" points="singleStarbucks"/>
  <a href="<%= singleStarbucksMap %>">
    <%= singleStarbucks %>
  </a>
  <HR>
</loc:iterateBusinesses>

15.2.1.17 iterateBusinessesInCity

The iterateBusinessesInCity tag presents individually businesses in a specified city.

Table 15-17 lists the iterateBusinessesInCity tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example presents individually all Borders bookstores in San Francisco, California. For each location, it displays information about the location followed by a horizontal rule.

<loc:iterateBusinessesInCity name="a_business_city"
   type="oracle.panama.spatial.yp.YPBusiness"
   city="San Francisco" state="CA" country="US" businessName="Borders">
   <%= a_business_city.toString() %>
   <HR>
</loc:iterateBusinessesInCity>

15.2.1.18 iterateBusinessesInCorridor

The iterateBusinessesInCorridor tag presents individually the businesses in a corridor. A corridor is a collection of points, such as points representing intersections or exits when creating a route.

Table 15-18 lists the iterateBusinessesInCorridor tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates a route between an office and another location, and presents individually the Starbucks locations that are within 3000 meters of any point in the corridor associated with the route. For each location, the example, displays information about the location followed by a horizontal rule.

<loc:route name="myRoute" type="oracle.panama.spatial.jsptags.beans.Route" xres="800" yres="600" requestGeom="true">
    <loc:address
        name="office"
        type="oracle.panama.model.Location"
        businessName="Some office"
        firstLine="500 Oracle Parkway"
        city="Redwood City"
        state="CA"
        postalCode="94065"
        country="US"/>
    <loc:address
        name="ucsb"
        type="oracle.panama.model.Location"
        businessName="UCSB"
        firstLine="6750 El Colegio Rd"
        city="Goleta"
        state="CA"
        postalCode="93117"
        country="US"/>
</loc:route>

<loc:geometry name="myRouteGeom" type="java.util.List" route="myRoute"/>

<loc:iterateBusinessesInCorridor name="a_business_corridor"
   type="oracle.panama.spatial.yp.YPBusiness"
   businessName="Starbucks" corridorID="myRouteGeom" radiusInMeters="3000">
   <%= a_business_corridor.toString() %>
   <HR>
</loc:iterateBusinessesInCorridor>

15.2.1.19 iterateBusinessesInPostalCode

The iterateBusinessesInPostalCode tag presents individually businesses in a specified postal code.

Table 15-19 lists the iterateBusinessesInPostalCode tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example presents individually all Starbucks locations in postal code 93117 in the United States. For each location, it displays information about the location followed by a horizontal rule.

<loc:iterateBusinessesInPostalCode name="a_business_pcode"
   type="oracle.panama.spatial.yp.YPBusiness"
   postalCode="93117" country="US" businessName="Starbucks">
   <%= a_business_pcode.toString() %>
   <HR>
</loc:iterateBusinessesInPostalCode>

15.2.1.20 iterateBusinessesInRadius

The iterateBusinessesInRadius tag presents individually businesses within a circular area, associated with a specified radius in meters, around a point.

Table 15-20 lists the iterateBusinessesInRadius tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example presents individually all Starbucks locations within 5000 meters (5 kilometers) of the point associated with the address for Oracle headquarters. For each location, it displays information about the location followed by a horizontal rule.

<loc:address
      name="HQ"
      type="oracle.panama.model.Location"
      businessName="HQ"
      firstLine="500 Oracle Parkway"
      city="Redwood City"
      state="CA"
      postalCode="94065"
      country="US"/>
<loc:iterateBusinessesInRadius name="a_business_radius"
   type="oracle.panama.spatial.yp.YPCategory"
   businessName="Starbucks" centerID="HQ"  radiusInMeters="5000">
   <%= a_business_radius.toString() %>
   <HR>
</loc:iterateBusinessesInRadius>

15.2.1.21 iterateBusinessesInState

The iterateBusinessesInState tag presents individually businesses in a specified state.

Table 15-21 lists the iterateBusinessesInState tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example presents individually all Starbucks locations in the state of New Hampshire. For each location, it displays information about the location followed by a horizontal rule.

<loc:iterateBusinessesInState name="a_business_state"
   type="oracle.panama.spatial.yp.YPBusiness"
   state="CA" country="US" businessName="Starbucks">
   <%= a_business_state.toString() %>
   <HR>
</loc:iterateBusinessesInState>

15.2.1.22 iterateBusinessesNearestTo

The iterateBusinessesNearestTo tag presents individually businesses within a circular area, associated with a specified radius in meters, around a point.

Table 15-22 lists the iterateBusinessesNearestTo tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example presents individually the 10 Starbucks locations nearest to the point associated with the address for Oracle headquarters. For each location, it displays information about the location followed by a horizontal rule.

<loc:address
      name="HQ"
      type="oracle.panama.model.Location"
      businessName="HQ"
      firstLine="500 Oracle Parkway"
      city="Redwood City"
      state="CA"
      postalCode="94065"
      country="US"/>
<loc:iterateBusinessesNearestTo name="a_business_nearest"
   type="oracle.panama.spatial.yp.YPBusiness"
   businessName="Starbucks" centerID="HQ"  n="10">
   <%= a_business_nearest.toString() %>
   <HR>
</loc:iterateBusinessesNearestTo>

15.2.1.23 iterateByDistance

The iterateByDistance tag presents individually the points in a collection, sorted by distance from a specified point. The distance is measured along a straight line along the curvature of the Earth.

Table 15-23 lists the iterateByDistance tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates a collection of the 10 Starbucks business locations nearest to Oracle headquarters. It uses the iterateByDistance tag to present individually the locations sorted by distance from headquarters, and it displays the information about each location followed by a horizontal rule.

<loc:address
      name="HQ"
      type="oracle.panama.model.Location"
      businessName="HQ"
      firstLine="500 Oracle Parkway"
      city="Redwood City"
      state="CA"
      postalCode="94065"
      country="US"/>
<loc:businesses
      name="starbucks"
      type="java.util.Collection"
      businessName="Starbucks"
      centerID="HQ"
      nearestN="10"/>
<loc:iterateByDistance name="iter_dist" type="oracle.panama.model.Point" 
       collection="starbucks" centerID="HQ">
   <%= iter_dist.toString() %>
   <HR>
</loc:iterateByDistance>

15.2.1.24 iterateByDrivingDistance

The iterateByDrivingDistance tag presents individually the points in a collection, sorted by driving distance from a specified point, as determined by the routing provider.

Table 15-24 lists the iterateByDrivingDistance tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates a collection of the 10 Starbucks business locations nearest to Oracle headquarters, and it uses the iterateByDrivingDistance tag to sort the locations by driving distance from headquarters, and display the information about each location followed by a horizontal rule.

<loc:address
      name="HQ"
      type="oracle.panama.model.Location"
      businessName="HQ"
      firstLine="500 Oracle Parkway"
      city="Redwood City"
      state="CA"
      postalCode="94065"
      country="US"/>
<loc:businesses
      name="starbucks"
      type="java.util.Collection"
      businessName="Starbucks"
      centerID="HQ"
      nearestN="10"/>
<loc:iterateByDrivingDistance name="iter_drive" type="oracle.panama.model.Point" 
       collection="starbucks" centerID="HQ">
   <%= iter_drive.toString() %>
   <HR>
</loc:iterateByDrivingDistance>

15.2.1.25 iterateByName

The iterateByName tag presents individually the points in a collection, sorted by business name.

Table 15-25 lists the iterateByName tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example presents individually the businesses, sorted by name, in a collection named bookstores, which was previously created. For each business, it displays information about the location followed by a horizontal rule.

<loc:iterateByName name="iter_name" type="oracle.panama.model.Point" 
       collection="bookstores">
   <%= iter_name.toString() %>
   <HR>
</loc:iterateByName>

15.2.1.26 iterateByRegionName

The iterateByName tag presents individually the points in a collection, sorted by region name. The regions are sorted first by country, then by state, then by city, and then by postal code.

Table 15-26 lists the iterateByRegionName tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example presents individually the businesses, sorted by region name (country, then state, then city, then postal code), in a collection named starbucks, which was previously created. For each business, it displays information about the location followed by a horizontal rule.

<loc:iterateByRegionName name="iter_reg_name" type="oracle.panama.model.Point" 
       collection="starbucks">
   <%= iter_reg_name.toString() %>
   <HR>
</loc:iterateByRegionName>

15.2.1.27 iterateCategoriesMatchingKeyword

The iterateCategoriesMatchingKeyword tag creates a collection of categories that match a specified keyword value, and presents the categories individually.

Table 15-27 lists the iterateCategoriesMatchingKeyword tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example presents individually the categories that match the keyword restaurant. For each category, it displays the fully qualified name followed by a horizontal rule.

<loc:iterateCategoriesMatchingKeyword name="a_category"
   type="oracle.panama.spatial.yp.YPCategory"
   keyword="restaurant">
   <%= a_category.getFullyQualifiedName() %>
   <HR>
</loc:iterateCategoriesMatchingKeyword>

15.2.1.28 iterateChildCategories

The iterateChildCategories tag specifies a collection of immediate child subcategories, presented individually.

Table 15-28 lists the iterateChildCategories tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example presents individually all child categories of the parent category associated with the variable restaurant. For each child category, it displays the fully qualified name followed by a horizontal rule.

<loc:iterateChildCategories name="a_child_category"
   type="oracle.panama.spatial.yp.YPCategory"
   parentCategory="restaurant">
   <%= a_child_category.getFullyQualifiedName() %>
   <HR>
</loc:iterateChildCategories>

15.2.1.29 iterateGeocodes

The iterateGeocodes tag returns a collection of geocoded addresses, presented individually.

Table 15-29 lists the iterateGeocodes tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example of the iterateGeocodes tag presents each geocoded address on Daniel Webster Highway in postal code 03060 in Nashua, New Hampshire. For each geocoded address, it displays a horizontal rule and a line of text, performs a line break, and displays the address information from the provider.

<loc:iterateGeocodes
  name = "a_business"
  type = "oracle.panama.model.Location"
  streetName = "Daniel Webster Hwy"
  city = "Nashua"
  state = "NH"  
  postalCode = "03060"
  country = "US">
      <HR>
      Another business in our community:
      <br>
<%= a_business.toString() %>
</loc:iterateGeocodes>

15.2.1.30 iterateLocationMarks

The iterateLocationMarks tag presents individually the location marks for an Oracle Application Server Wireless user.

Table 15-30 lists the iterateLocationMarks tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example presents each location mark for user Mike as an object associated with the variable iter_marks, and for each object it displays information about the object followed by a horizontal rule.

<loc:iterateLocationMarks name="iter_marks" 
       type="oracle.panama.model.LocationMark"
       userName="Mike" >
   <%= iter_marks.toString() %>
   <HR>
</loc:iterateLocationMarks>

15.2.1.31 iterateManeuvers

The iterateManeuvers tag creates a collection of driving maneuvers, and it presents the maneuvers individually.

Table 15-31 lists the iterateManeuvers tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates a route named myRoute between two addresses (a person's office and home), displays a map of the route followed by a horizontal rule, and presents each driving maneuver (using the iterateManeuvers tag and the getMap and getNarrative function calls) followed by a horizontal rule. Each driving maneuver description is also a link that users can click to display a map of the maneuver.

<loc:route name="myRoute" type="oracle.panama.spatial.jsptags.beans.Route" xres="800" yres="600">
   <loc:address
        name="office"
        type="oracle.panama.model.Location"
        businessName="My office"
        firstLine="1 Oracle Dr"
        city="Nashua"
        state="NH"
        postalCode="03062"
        country="US"/>
   <loc:address
        name="home"
        type="oracle.panama.model.Location"
        businessName="My home"
        firstLine="2 Royal Crest Dr"
        city="Nashua"
        state="NH"
        postalCode="03060"
        country="US"/>
</loc:route>

<img src="<%= myRoute.getMap() %>">
<HR>

<loc:iterateManeuvers name="aManeuver" type="oracle.panama.spatial.jsptags.beans.Maneuver" routeID="myRoute">
      <a href="<%= aManeuver.getMap() %>">
        <%= aManeuver.getNarrative() %>
      </a>
      <HR>
</loc:iterateManeuvers>

15.2.1.32 iterateReverseGeocodes

The iterateReverseGeocodes tag returns a collection of reverse geocoded addresses (addresses associated by the provider with a specified point), presented individually.

Table 15-32 lists the iterateReverseGeocodes tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example of the iterateReverseGeocodes tag presents each geocoded address that the provider associates with a specified point For each geocoded address, it displays the address information from the provider followed by a horizontal rule.

<loc:iterateReverseGeocodes
  name = "iter_rev"
  type = "oracle.panama.model.Location"
  lon = "-71.4424"
  lat = "42.712"
  label = "You Are Here" >
<%= iter_rev.toString() %>
<HR>
</loc:iterateReverseGeocodes>

15.2.1.33 listAllMembers

The listAllMembers tag creates an unformatted list of all members of a specified mobile community.

Table 15-33 lists the listAllMembers tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates an unformatted list of all members of the community associated with the variable named comm_private, and it displays the java.util.Enumeration object that is created.

<loc:listAllMembers
      name="list_all_mem"
      type="java.util.Enumeration"
      communityID="comm_private" />
<%= list_all_mem.toString() %>

15.2.1.34 listBusinessesInCity

The listBusinessesInCity creates an unformatted list of businesses in a specified city.

Table 15-34 lists the listBusinessesInCity tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates an unformatted list of all Borders bookstores in San Francisco, California, and it displays the list.

<loc:listBusinessesInCity name="all_businesses_city"
   type="java.util.List"
   city="San Francisco" state="CA" country="US" businessName="Borders">
</loc:listBusinessesInCity>
<%= all_businesses_city.toString() %>

15.2.1.35 listBusinessesInCorridor

The listBusinessesInCorridor tag creates an unformatted list of the businesses in a corridor. A corridor is a collection of points, such as points representing intersections or exits when creating a route.

Table 15-35 lists the listBusinessesInCorridor tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates a route between an office and another location, creates an unformatted list of the Starbucks locations that are within 3000 meters of any point in the corridor associated with the route, and displays the list.

<loc:route name="myRoute" type="oracle.panama.spatial.jsptags.beans.Route" xres="800" yres="600" requestGeom="true">
    <loc:address
        name="office"
        type="oracle.panama.model.Location"
        businessName="Some office"
        firstLine="500 Oracle Parkway"
        city="Redwood City"
        state="CA"
        postalCode="94065"
        country="US"/>
    <loc:address
        name="ucsb"
        type="oracle.panama.model.Location"
        businessName="UCSB"
        firstLine="6750 El Colegio Rd"
        city="Goleta"
        state="CA"
        postalCode="93117"
        country="US"/>
</loc:route>

<loc:geometry name="myRouteGeom" type="java.util.List" route="myRoute"/>

<loc:listBusinessesInCorridor name="all_businesses_corridor"
   type="java.util.List"
   businessName="Starbucks" corridorID="myRouteGeom" radiusInMeters="3000">
</loc:listBusinessesInCorridor>
<%= all_businesses_corridor.toString() %>

15.2.1.36 listBusinessesInPostalCode

The listBusinessesInPostalCode tag creates an unformatted list of businesses in a specified postal code.

Table 15-36 lists the listBusinessesInPostalCode tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates an unformatted list of all Starbucks locations in postal code 93117 in the United States, and it displays the list.

<loc:listBusinessesInPostalCode name="all_businesses_pcode"
   type="java.util.List"
   postalCode="93117" country="US" businessName="Starbucks">
</loc:listBusinessesInPostalCode>
<%= all_businesses_pcode.toString() %>

15.2.1.37 listBusinessesInRadius

The listBusinessesInRadius tag creates an unformatted list of businesses within a circular area, associated with a specified radius in meters, around a point.

Table 15-37 lists the listBusinessesInRadius tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates an unformatted list of all Starbucks locations within 5000 meters (5 kilometers) of the point associated with the address for Oracle headquarters, and it displays the list.

<loc:address
      name="HQ"
      type="oracle.panama.model.Location"
      businessName="HQ"
      firstLine="500 Oracle Parkway"
      city="Redwood City"
      state="CA"
      postalCode="94065"
      country="US"/>
<loc:listBusinessesInRadius name="all_businesses_radius"
   type="java.util.List"
   businessName="Starbucks" centerID="HQ"  radiusInMeters="5000">
</loc:listBusinessesInRadius>
<%= all_businesses_radius.toString() %>

15.2.1.38 listBusinessesInState

The listBusinessesInState tag creates an unformatted list of businesses in a specified state.

Table 15-38 lists the listBusinessesInState tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates an unformatted list of all Starbucks locations in the state of New Hampshire, and it displays the list.

<loc:listBusinessesInState name="all_businesses_state"
   type="java.util.List"
   state="CA" country="US" businessName="Borders">
</loc:listBusinessesInState>
<%= all_businesses_state.toString() %>

15.2.1.39 listBusinessesNearestTo

The listBusinessesNearestTo tag creates an unformatted list of businesses within a circular area, associated with a specified radius in meters, around a point.

Table 15-39 lists the listBusinessesNearestTo tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates an unformatted list of the 10 Starbucks locations nearest to the point associated with the address for Oracle headquarters, and it displays the list.

<loc:address
      name="HQ"
      type="oracle.panama.model.Location"
      businessName="HQ"
      firstLine="500 Oracle Parkway"
      city="Redwood City"
      state="CA"
      postalCode="94065"
      country="US"/>
<loc:listBusinessesNearestTo name="all_businesses_nearest"
   type="java.util.List"
   businessName="Starbucks" centerID="HQ"  n="10">
</loc:listBusinessesNearestTo>
<%= all_businesses_nearest.toString() %>

15.2.1.40 listByDistance

The listByDistance tag creates an unformatted list of the points in a collection, sorted by distance from a specified point. The distance is measured along a straight line along the curvature of the Earth.

Table 15-40 lists the listByDistance tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates a collection of the 10 Starbucks business locations nearest to Oracle headquarters, uses the listByDistance tag to create an unformatted list of locations sorted by distance from headquarters, and displays the list.

<loc:address
      name="HQ"
      type="oracle.panama.model.Location"
      businessName="HQ"
      firstLine="500 Oracle Parkway"
      city="Redwood City"
      state="CA"
      postalCode="94065"
      country="US"/>
<loc:businesses
      name="starbucks"
      type="java.util.Collection"
      businessName="Starbucks"
      centerID="HQ"
      nearestN="10"/>
<loc:listByDistance name="list_dist" type="java.util.List"
   collection="starbucks" centerID="HQ">
</loc:listByDistance>
<%= list_dist.toString() %>

15.2.1.41 listByDrivingDistance

The listByDrivingDistance tag creates an unformatted list of the points in a collection, sorted by driving distance from a specified point, as determined by the routing provider.

Table 15-41 lists the listByDrivingDistance tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates a collection of the 10 Starbucks business locations nearest to Oracle headquarters, uses the listByDrivingDistance tag to create an unformatted list of locations sorted by driving distance from headquarters, and displays the list.

<loc:address
      name="HQ"
      type="oracle.panama.model.Location"
      businessName="HQ"
      firstLine="500 Oracle Parkway"
      city="Redwood City"
      state="CA"
      postalCode="94065"
      country="US"/>
<loc:businesses
      name="starbucks"
      type="java.util.Collection"
      businessName="Starbucks"
      centerID="HQ"
      nearestN="10"/>
<loc:listByDrivingDistance name="list_drive" type="java.util.List"
   collection="starbucks" centerID="HQ">
</loc:listByDrivingDistance>
<%= list_drive.toString() %>

15.2.1.42 listByName

The listByName tag creates an unformatted list of the points in a collection, sorted by business name.

Table 15-42 lists the listByName tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates an unformatted list of the businesses, sorted by name, in a collection named bookstores (which was previously created), and it displays the list.

<loc:listByName name="list_name" type="java.util.List"
   collection="bookstores">
</loc:listByName>
<%= list_name.toString() %>

15.2.1.43 listByRegionName

The listByName tag creates an unformatted list of the points in a collection, sorted by region name. The regions are sorted first by country, then by state, then by city, and then by postal code.

Table 15-43 lists the listByName tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates an unformatted list of the businesses, sorted by region name (country, then state, then city, then postal code), in a collection named starbucks (which was previously created), and it displays the list.

<loc:listByRegionName name="list_reg_name" type="java.util.List"
   collection="starbucks">
</loc:listByRegionName>
<%= list_reg_name.toString() %>

15.2.1.44 listCategoriesMatchingKeyword

The listCategoriesMatchingKeyword tag creates an unformatted list of business directory categories that match a specified keyword.

Table 15-44 lists the listCategoriesMatchingKeyword tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates an unformatted list of the categories that match the keyword restaurant, and it displays the list.

<loc:listCategoriesMatchingKeyword name="all_categories_key"
   type="java.util.List"
   keyword="restaurant">
</loc:listCategoriesMatchingKeyword>
<%= all_categories_key.toString() %>

15.2.1.45 listChildCategories

The listChildCategories tag creates an unformatted list of immediate child subcategories.

Table 15-45 lists the listChildCategories tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates an unformatted list of all child categories of the parent category associated with the variable restaurant, and it displays the list.

<loc:listChildCategories name="all_categories_child"
   type="java.util.List"
   parentCategory="restaurant">
</loc:listChildCategories>
<%= all_categories_child.toString() %>

15.2.1.46 listCreatedCommunities

The listCreatedCommunities tag creates an unformatted list of all mobile communities (private, shared, and system) owned by a specified Oracle Application Server mobile use. For an explanation of mobile communities, including types of communities, see Section 15.3.2.6, "Mobile Communities".

Table 15-46 lists the listCreatedCommunities tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example created an unformatted list, at the request of the user named Mike, of all mobile communities, and it displays the list.

<loc:listCreatedCommunities
      name="list_cr_comm"
      type="java.util.List"
      userName="Mike" />
<%= list_cr_comm.toString() %>

15.2.1.47 listCreatedPrivateCommunities

The listCreatedPrivateCommunities tag creates an unformatted list of all mobile private communities owned by a specified Oracle Application Server mobile use. For an explanation of mobile communities, including types of communities, see Section 15.3.2.6, "Mobile Communities".

Table 15-47 lists the listCreatedPrivateCommunities tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example created an unformatted list, at the request of the user named Mike, of all mobile private communities, and it displays the list.

<loc:listCreatedPrivateCommunities
      name="list_cr_priv_comm"
      type="java.util.List"
      userName="Mike" />
<%= list_cr_priv_comm.toString() %>

15.2.1.48 listCreatedSharedCommunities

The listCreatedSharedCommunities tag creates an unformatted list of all mobile shared communities owned by a specified Oracle Application Server mobile use. For an explanation of mobile communities, including types of communities, see Section 15.3.2.6, "Mobile Communities".

Table 15-48 lists the listCreatedSharedCommunities tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example created an unformatted list, at the request of the user named Mike, of all mobile shared communities, and it displays the list.

<loc:listCreatedSharedCommunities
      name="list_cr_shar_comm"
      type="java.util.List"
      userName="Mike" />
<%= list_cr_shar_comm.toString() %>

15.2.1.49 listCreatedSystemCommunities

The listCreatedSystemCommunities tag creates an unformatted list of all mobile system communities owned by a specified Oracle Application Server mobile use. For an explanation of mobile communities, including types of communities, see Section 15.3.2.6, "Mobile Communities".

Table 15-49 lists the listCreatedSystemCommunities tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example created an unformatted list, at the request of the user named Mike, of all mobile system communities, and it displays the list.

<loc:listCreatedSystemCommunities
      name="list_cr_sys_comm"
      type="java.util.List"
      userName="Mike" />
<%= list_cr_sys_comm.toString() %>

15.2.1.50 listGeocodes

The listGeocodes tag creates an unformatted list of geocoded addresses.

Table 15-50 lists the listGeocodes tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example of the listGeocodes tag presents all geocoded addresses on Daniel Webster Highway in postal code 03060 in Nashua, New Hampshire.

<loc:listGeocodes
  name = "all_businesses"
  type = "java.util.List"
  streetName = "Daniel Webster Hwy"
  city = "Nashua"
  state = "NH"  
  postalCode = "03060"
  country = "US" />

15.2.1.51 listLocationMarks

The listLocationMarks tag creates an unformatted list of the location marks for an OracleAS Wireless user.

Table 15-51 lists the listLocationMarks tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates an unformatted list of the location marks for user Mike as an object associated with the variable list_marks, and it displays information about the object.

<loc:listLocationMarks name="list_marks" 
        type="java.util.List"
       userName="Mike"  />
<%= list_marks.toString() %>

15.2.1.52 listManeuvers

The listManeuvers tag creates an unformatted list of driving maneuvers.

Table 15-52 lists the listManeuvers tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates a route named myRoute between two addresses (a person's office and home), displays a map of the route followed by a horizontal rule, and presents an unformatted list of all the driving maneuvers for the route.

<loc:route name="myRoute" type="oracle.panama.spatial.jsptags.beans.Route" xres="800" yres="600">
   <loc:address
        name="office"
        type="oracle.panama.model.Location"
        businessName="My office"
        firstLine="1 Oracle Dr"
        city="Nashua"
        state="NH"
        postalCode="03062"
        country="US"/>
   <loc:address
        name="home"
        type="oracle.panama.model.Location"
        businessName="My home"
        firstLine="2 Royal Crest Dr"
        city="Nashua"
        state="NH"
        postalCode="03060"
        country="US"/>
</loc:route>
<loc:listManeuvers name="all_maneuvers" type="java.util.List" routeID="myRoute" />
<%= all_maneuvers.toString() %>

15.2.1.53 listReverseGeocodes

The listReverseGeocodes tag creates an unformatted list of reverse geocoded addresses (addresses associated by the provider with a specified point).

Table 15-53 lists the listReverseGeocodes tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example of the listReverseGeocodes tag presents addresses associated by the provider with a specified point.

<loc:listReverseGeocodes
  name = "list_rev"
  type = "java.util.List"
  lon = "-71.4424"
  lat = "42.712"
  label = "You Are Here" />

<%= list_rev.toString() %>

15.2.1.54 map

The map tag specifies a map with a specified resolution and showing one of the following:

• One or more points

• A route

• A driving maneuver

Table 15-54 lists the map tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example of the map tag creates a map named NEDCSmall 400 pixels wide and 300 pixels high. The center point for the map is the address defined by the address tag enclosed in the map tag.

<loc:map name="NEDCSmall" type="oracle.panama.spatial.jsptags.beans.Map"
       xres="400" yres="300">
   <loc:address
     name="NEDC"
     type="oracle.panama.model.Location"
     businessName="NEDC"
     firstLine="1 Oracle Dr"
     city="Nashua"
     state="NH"
     postalCode="03062"
     country="US"/>
</loc:map>

15.2.1.55 mobilePos

The mobilePos tag creates an object with positioning information about a mobile user.

Table 15-55 lists the mobilePos tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates an object with positioning information for user Mike. By default, if the current position cannot be obtained, the default location mark for that user is used. The example also displays the positioning information.

<loc:mobilePos
      name="position"
      type="oracle.panama.model.Point"
      userName="Mike"  />
<%= position.toString() %>

15.2.1.56 point

The point tag specifies the longitude and latitude value of a point, using the WGS 84 coordinate system (Oracle Spatial SRID value 8307).

Table 15-56 lists the point tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example of the point tag specifies the point at 75.3 degrees west longitude and 45.71 degrees north latitude.

<loc:point
  lon = "-73.5"
  lat = "45.71"  />

15.2.1.57 removeAllMembers

The removeAllMembers tag removes all members from a mobile community. (It does not delete the community; to delete a community, use the deleteCommunity tag.) For an explanation of mobile communities, see Section 15.3.2.6, "Mobile Communities".

Table 15-57 lists the removeAllMembers tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example removes, at the request of the user named Mike, all members from the mobile community associated with the variable named comm_private. It also creates a java.util.Enumeration object of members of this community, and displays this object.

<loc:removeAllMembers
      name="remove_all_members"
      type="Boolean"
      userName="Mike"
      communityID="comm_private"  />
<loc:listAllMembers
      name="list_all_mem3"
      type="java.util.Enumeration"
      communityID="comm_private" />
<%= list_all_mem3.toString() %>

15.2.1.58 removeMembers

The removeMembers tag removes one or more members from a mobile community. For an explanation of mobile communities, see Section 15.3.2.6, "Mobile Communities".

Table 15-58 lists the removeMembers tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example removes, at the request of the user named Mike, the users named Oscar and Maria from the mobile community associated with the variable named comm_private. It also creates a java.util.Enumeration object of members of this community, and displays this object.

<loc:removeMembers
      name="remove_members"
      type="Boolean"
      userName="Mike"
      communityID="comm_private" 
      communityMembers="Oscar Maria" />
<loc:listAllMembers
      name="list_all_mem2"
      type="java.util.Enumeration"
      communityID="comm_private" />
<%= list_all_mem2.toString() %>

15.2.1.59 route

The route tag specifies a route with a specified map resolution. It includes maneuvers, an overview map, and maneuver maps.

Table 15-59 lists the route tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example creates a route named myRoute between two addresses (a person's office and home), displays a map of the route followed by a horizontal rule, and presents each driving maneuver (using the iterateManeuvers tag and the getMap and getNarrative function calls) followed by a horizontal rule. Each driving maneuver description is also a link that users can click to display a map of the maneuver.

<loc:route name="myRoute" type="oracle.panama.spatial.jsptags.beans.Route" xres="800" yres="600">
   <loc:address
        name="office"
        type="oracle.panama.model.Location"
        businessName="My office"
        firstLine="1 Oracle Dr"
        city="Nashua"
        state="NH"
        postalCode="03062"
        country="US"/>
   <loc:address
        name="home"
        type="oracle.panama.model.Location"
        businessName="My home"
        firstLine="2 Royal Crest Dr"
        city="Nashua"
        state="NH"
        postalCode="03060"
        country="US"/>
</loc:route>

<img src="<%= myRoute.getMap() %>">
<HR>

<loc:iterateManeuvers name="aManeuver" type="oracle.panama.spatial.jsptags.beans.Maneuver" routeID="myRoute">
      <a href="<%= aManeuver.getMap() %>">
        <%= aManeuver.getNarrative() %>
      </a>
      <HR>
</loc:iterateManeuvers>

15.2.1.60 setCommunityName

The setCommunityName tag specifies an address to be geocoded, located on a map, or used as the start or end address of a route or as the center for a business directory query.

Table 15-60 lists the address tag parameters. (See Section 15.2.1, "Creating Java Server Pages (JSP) Files" for an explanation of the information provided.)

The following example sets, at the request of the user named Mike, the community name of the existing community that is associated with the variable named comm_shared. The community name is set to the value Renamed Shared Community. The example also displays the result of the operation (TRUE or FALSE).

<loc:setCommunityName
      name="set_comm_name"
      type="Boolean"
      userName="Mike"
      communityID="comm_shared" 
      newName="Renamed Shared Community" />
<%= set_comm_name.toString() %>

15.2.2.1 Geocoding

In a geocoding application, the user is asked for an address, and the application geocodes that address. Such an application can start by constructing a SimpleForm object for the address, as shown in Example 15-9.

<SimpleResult>
  <SimpleForm target="EnterAddress2.jsp">
    <SimpleFormItem name="businessName" title="Business Name" value="Oracle"/>
    <SimpleFormItem name="houseNum"     title="House Number"  value="500"/>
    <SimpleFormItem name="street"    title="Street"     value="Oracle Parkway"/>
    <SimpleFormItem name="city"      title="City"       value="Redwood City"/>
    <SimpleFormItem name="state"        title="State"         value="CA"/>
    <SimpleFormItem name="postalCode"   title="Postal Code"   value="94065"/>
    <SimpleFormItem name="country"      title="Country"       value="US"/>
  </SimpleForm>
</SimpleResult>

String
  businessName = request.getParameter("businessName"),
  houseNumber  = request.getParameter("houseNum"),
  streetName   = request.getParameter("street"),
  city         = request.getParameter("city"),
  state        = request.getParameter("state"),
  postalCode   = request.getParameter("postalCode"),
  country      = request.getParameter("country");

Location address =
  SpatialManager.createLocation(
    businessName,
    houseNumber,
    new String[] { streetName },
    null,
    city,
    state,
    postalCode,
    null,
    country);

address.getLongitude()
address.getLatitude()
address.getAddressLine1()
address.getCity()
address.getState()

<SimpleResult>
  <SimpleMenu>
    <%
      java.util.Iterator it =
       oracle.panama.spatial.intladdress.IntlAddressManager.getAddressFormats();
      while(it.hasNext())
      {
        String name = (String)it.next();
    %>
      <SimpleMenuItem target="enterIntlAddress.jsp?name=<%= name %>">
        <%= name %>
      </SimpleMenuItem>
    <%
      }
    %>
  </SimpleMenu>
</SimpleResult>

<SimpleResult>
  <SimpleForm target="readIntlAddress.jsp?name=<%= request.getParameter("name")
                                                %>">
    <%
      java.util.Iterator addressComponentNames =
        oracle.panama.spatial.intladdress.IntlAddressManager.getAddressFormat(
          request.getParameter("name")).getComponentNames();
      int num = 1;
      while(addressComponentNames.hasNext())
      {
        String name = (String)addressComponentNames.next();
    %>
      <SimpleFormItem name="component<%= num++ %>" title="<%= name %>"/>
    <%
      }
    %>
  </SimpleForm>
</SimpleResult>

<SimpleResult>
  <SimpleText>
<%
  String name = request.getParameter("name");
  boolean finished = false;
  java.util.Vector components = new java.util.Vector();
  for(int i = 1; !finished; i++)
  {
    String component = request.getParameter("component" + i);
    if(component != null)
      components.add(component);
    else
      finished = true;
  }
  String componentArray[] = new String[components.size()];
  for(int i = 0; i < componentArray.length; i++)
    componentArray[i] = (String)components.get(i);
  oracle.panama.spatial.intladdress.IntlAddress loc =
    oracle.panama.spatial.intladdress.IntlAddressManager.createAddress(
      name,
      componentArray);

  java.util.Iterator lines = loc.getAddressLines(false, true);
  while(lines.hasNext())
  {
    %>
      <SimpleTextItem>
        <%= (String)lines.next() %>
      </SimpleTextItem>
    <%
  }
%>
  </SimpleText>
</SimpleResult>

15.2.2.2 Location Marks

An adapter can work with location marks. Example 15-15 retrieves the location marks into an array. (Code not relevant to location marks is omitted from this example.)

…
LocationMark locMarks[] = sr.getSession().getUser().getLocationMarks();
…

15.2.2.3 Routing

You can create an adapter that provides routing information between a start address and an end address that the user enters. The adapter must:

1. Set the routing settings and options.

2. Compute the route.

3. Present the resulting route to the user (for example, as a list of maneuvers and maneuver maps, plus an overview map).

Example 15-16 sets the routing settings and options by constructing a RoutingSettings object and specifying the resolution (height and width) of the resulting overview and maneuver maps.

RoutingSettings rS = new RoutingSettings(true, false);
rS.setSecondaryOption(RoutingOption.overviewMapHeight, "600");
rS.setSecondaryOption(RoutingOption.overviewMapWidth, "800");
rS.setSecondaryOption(RoutingOption.maneuverMapHeight, "600");
rS.setSecondaryOption(RoutingOption.maneuverMapWidth, "800");

RoutingResult rR =
   SpatialManager.getRouter().computeRoute(
      startLoc,
      endLoc,
      null,   // via points
      rS,   // routing options
      Locale.US);

<%!
  public static String translate(String orig)
  {
    return oracle.panama.spatial.XMLEncoder.encodeToSimplifiedXML(orig);
  }
%>

<%
  oracle.panama.spatial.router.RoutingResult rR = ...
%>
<SimpleResult>
  <SimpleImage src="<%= translate(rR.getOverviewMapURL()[0].toString()) %>"/>
  <SimpleText>
    <%
      oracle.panama.spatial.router.Maneuver mans[] = rR.getManeuvers();
      for(int i = 0; i < mans.length; i++) {
    %>
      <SimpleTextItem>
        <%= mans[i].getNarrative() %>
      </SimpleTextItem>
    <% } %>
  </SimpleText>
</SimpleResult>

15.2.2.4 Mapping

In a typical mapping application, the user enters an address and wants to see a map. Example 15-19 gets the map image URL of an address to be mapped. (The variable loc of type Location contains an address that has been previously geocoded.)

String url =
   SpatialManager.getMapper().getMapURL(
      loc,
      oracle.panama.imagex.ImageFormats.GIF,
      800,   // width
      600,   // height
      false);   // allow turning

15.2.2.5 Business Directory (YP)

In a typical business directory (YP) application, the user enters a region specifying a country, state, and city, and wants to get businesses in some category, such as relating to wine tasting or wineries. The user must be asked for country, state, and city, and the application must determine the exact category and then all the relevant businesses.

The first step in determining the category is usually to ask the user for a category keyword (for example, wine) through a SimpleForm object.

The next step is to determine all the categories that match the keyword, as shown in Example 15-20.

YPFinder ypF = SpatialManager.getYPFinder();
YPCategory cats[] = ypF.getCategoryAtRoot().getCategoriesMatchingName(keyword);

<SimpleResult>
  <SimpleMenu>
    <%
      oracle.panama.spatial.yp.YPFinder ypF =
        oracle.panama.spatial.SpatialManager.getYPFinder();
      oracle.panama.spatial.yp.YPCategory cats[] =
        ypF.getCategoryAtRoot().getCategoriesMatchingName("auto");
      for(int i = 0; i < cats.length; i++)
      {
        %>
        <SimpleMenuItem
         target="listCategories.jsp?cat=<%= cats[i].getFullyQualifiedName() %>">
            <%= cats[i].getFullyQualifiedName() %>
        </SimpleMenuItem>
       <%
      }
    %>
  </SimpleMenu>
</SimpleResult>

YPCategory cat = YPCategory.fromFullyQualifiedName(categoryNameString);
YPBusiness b[] =
  SpatialManager.getYPFinder().getBusinessesInCity(
    cat,
    country,
    state,
    city,
    Locale.US);

15.2.2.6 Traffic

To create an application based on the traffic services API, you must do the following:

1. Prepare input objects (such as CityInfo, RouteInfo, Point, and Location) for the query.

2. Get TrafficReporter and summit the query.

3. Obtain TrafficReport and process the information.

The rest of this section contains examples of typical operations. Example 15-23 performs a city-level query.

TrafficReporter reporter = SpatialManager.getTrafficReporter();
CityInfo c = new CityInfo("BOSTON", "MA", "US");
TrafficReport report = null;
try{
  report = reporter.getReportViaCity(c);
}catch(LBSException e){
  System.out.println(e.getLocalizedMessage());
}
 

RouteInfo r = new RouteInfo("US 3", null);
try{
  report = reporter.getReportViaRoute(r,c);
}catch(LBSException e){
  System.out.println(e.getLocalizedMessage());
}

try{
  report = reporter.getReportViaRoute(r,TrafficReporter.North,c);
}catch(LBSException e){
  System.out.println(e.getLocalizedMessage());
}

p = SpatialManager.createPoint(-71.0607, 42.3659);
try{
  report = reporter.getReportViaLocation(p, 10, TrafficReporter.MILES,
c);
}catch(LBSException e){
  System.out.println(e.getLocalizedMessage());
}

Location loc = SpatialManager.createLocation(null, null, "839 Kearny
     Street", null, "San Francisco", "CA", null, null, "US");
try{
  report = reporter.getReportViaAddress(loc, 10, TrafficReporter.MILES);
}catch(LBSException e){
  System.out.println(e.getLocalizedMessage());
}

Calendar rTime = report.getReportTime();
TrafficIncident[] incidents = report.getIncidents();
if(incidents != null){
  for(int i=0; i<incidents.length; i++){
    TrafficIncident inc = incidents[i];
    String desc = inc.getDescription();
    String severity = inc.getSeverity();
    String type = inc.getType();
    TrafficRoute route = inc.getIncidentRoute();
    String[] locations = inc.getLocationRange();        //text description 
    if(locations.length == 2){                          //a location range
      String exit1 = locations[0];
      String exit2 = locations[1];
    }
    else if(locations.length == 1){
      String exit1 = locations[0];                      //one location
    }
    Point geoLocation = inc.getIncidentLocation();      //lon/lat or
lon/lat+radius
    Calendar[] tr = inc.getTimeRange();
  }
}       

TrafficCityManager manager = reporter.getCityManager();
CityInfo[] cities = null;
try{
  cities = manager.getActiveCities();
}catch(LBSException e){
  System.out.println(e.getLocalizedMessage());
}

TrafficCityManager manager = reporter.getCityManager();
CityInfo sf = new CityInfo("SAN FRANCISCO", "CA", "US");
RouteInfo[] routes = null;
try{
  routes = manager.getRoutesInCity(sf);
}catch(LBSException e){
  System.out.println(e.getLocalizedMessage());
}

15.2.3.1 WSDL Files

The following WSDL files describe the Web services interfaces for geocoding, mapping, routing, and business directory (yellow pages) services:

• LbsSoapServiceGeocoder.wsdl

• LbsSoapServiceMapper.wsdl

• LbsSoapServiceRouter.wsdl

• LbsSoapServiceYPFinder.wsdl

15.2.3.2 XML Files

The following XML files contain example XML documents for the schema files:

• lbsAddress.xml

• lbsAddressArray.xml

• lbsAddressArray2.xml

• lbsBusiness.xml

• lbsBusinessArray.xml

• lbsCategory.xml

• lbsMap.xml

• lbsMapURL.xml

• lbsMapURLArray2.xml

• lbsPhone.xml

• lbsPhoneArray.xml

• lbsPoint.xml

• lbsPointArray.xml

• lbsRoute.xml

• lbsRouteSettings.xml

15.2.3.3 XSD Files

The following XSD files describe the XML parameters and return values in the Web services calls:

• lbsAddress.xsd

• lbsAddressArray.xsd

• lbsAddressArray2.xsd

• lbsBusiness.xsd

• lbsBusinessArray.xsd

• lbsCategory.xsd

• lbsMap.xsd

• lbsMapURL.xsd

• lbsMapURLArray2.xsd

• lbsPhone.xsd

• lbsPhoneArray.xsd

• lbsPoint.xsd

• lbsPointArray.xsd

• lbsRoute.xsd

• lbsRouteSettings.xsd

15.3.1.1 Enabling Manual Positioning

To enable manual positioning for a user, first set up any location marks that you might want to use. Use the API (LocationMark class) or the Personalization Portal Web interface to create one of more location marks (if they do not already exist), and specify a location mark as the default for that user.

To enable manual positioning using the Personalization Portal interface, follow these steps:

1. Log in to the Personalization Portal Web interface

2. Click the LocationMarks tab.

3. If the location mark that you want for your default location does not already exist it, create it. (Click Create and complete the information on the page that is displayed.)

4. Select the location mark that you want for your default location.

5. Click Set Default.

15.3.2.1 Providing Location Using a GPS Device

A mobile device can send its current location, usually provided through a global positioning system (GPS), to the OracleAS Wireless server. The current location can then be queried using the mobile positioning and privacy APIs.

You must create a client application program that runs on the mobile device and posts the device's current location to the OracleAS Wireless server. The data can be posted either to a JSP running on the OracleAS Wireless server or through a Web service.

The data must be in XML format, and it must conform to the following schema:

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2000/10/XMLSchema"
elementFormDefault="qualified">
 <xsd:element name="MP_GPS">
  <xsd:complexType>
   <xsd:sequence>
    <xsd:element ref="USERNAME"/>
    <xsd:element ref="PASSWORD"/>
    <xsd:element ref="MSID"/>
    <xsd:element ref="TIME" minOccurs="0"/>
    <xsd:element ref="GMT" minOccurs="0"/>
    <xsd:element ref="POS"/>
    <xsd:element ref="ALTITUDE" minOccurs="0"/>
    <xsd:element ref="ALT_UNCERTAINTY" minOccurs="0"/>
    <xsd:element ref="VELOCITY" minOccurs="0"/>
    <xsd:element ref="BEARING" minOccurs="0"/>
   </xsd:sequence>
  </xsd:complexType>
 </xsd:element>
 <xsd:element name="ALTITUDE" type="xsd:string"/>
 <xsd:element name="ALT_UNCERTAINTY" type="xsd:string"/>
 <xsd:element name="BEARING" type="xsd:string"/>
 <xsd:element name="GMT" type="xsd:string"/>
 <xsd:element name="LAT" type="xsd:string"/>
 <xsd:element name="LONG" type="xsd:string"/>
 <xsd:element name="MSID" type="xsd:string"/>
 <xsd:element name="PASSWORD" type="xsd:string"/>
 <xsd:element name="POS">
  <xsd:complexType>
   <xsd:sequence>
    <xsd:element ref="LAT"/>
    <xsd:element ref="LONG"/>
   </xsd:sequence>
  </xsd:complexType>
 </xsd:element>
 <xsd:element name="TIME" type="xsd:string"/>
 <xsd:element name="USERNAME" type="xsd:string"/>
 <xsd:element name="VELOCITY" type="xsd:string"/>
</xsd:schema>

The <USERNAME> and <PASSWORD> elements are used by OracleAS Wireless server to authorize the request.

The <MSID> element is the mobile station ID of the mobile device or user.

The optional <TIME> element indicates the time when this location is generated by a GPS. If this value is missing, the time when the data arrives at the OracleAS Wireless server is used.

The optional <VELOCITY> element specifies the velocity of the mobile device, in meters per second.

The optional <BEARING> element specifies the bearing angle, in degrees, clockwise from North.

The optional <ALTITUDE> element specifies the altitude of the mobile device, in meters, above sea level.

15.3.2.2 Location Cache

The location cache is an area in memory that temporarily stores a mobile user's ID, the most recently acquired location information, and the time when that information was gathered. If the location cache is searched for a mobile positioning request, and if there is an entry in the cache for the user whose location is requested, the time difference between the cache entry time and the current request time is compared against the positioning quality of service level of the positioning request. (Positioning quality of service is explained in Section 15.3.2.3.)

When a positioning request is satisfied by information in the cache, no position sensing is required; that is, no network round-trip operation is required.

15.3.2.3 Positioning Quality of Service

The positioning quality of service (QoS) value controls:

• Whether to check the current device position or the location cache to determine the location.

• If the location cache is checked, a maximum "age" of the most recent cached location value (that is, a number of seconds since that value was written to the location cache) for it to be used by the application.

You can specify the positioning quality of service value in either of the following ways:

• As a number of seconds, representing the maximum age of the position in the location cache for it to be used by the application. If the most recent position in the location cache is older than the appropriate time, the actual current position of the device is obtained, written in the cache, and used by the application. A value of 0 (zero) causes the positioning framework always to give the actual positioning result and not to search the location cache.

• As one of the following string values, each representing a level of positioning quality:

  • Exact: Causes the positioning framework always to give the actual positioning result and not to search the location cache; equivalent to specifying 0 (zero) seconds.

  • High: Represents a high level of probable accuracy.

  • Medium: Represents a medium level of probable accuracy.

  • Low: Represents a lower level of probable accuracy than the Medium value.

For the High, Medium, and Low values, the positioning framework determines an age value (number of seconds) in a heuristic manner.

There is a system default positioning quality of service level, which you can set. If a positioning quality of service level is not specified with a positioning request, the system default is used. The level can be set using the mobile positioning API (see Section 15.3.2.8, "Mobile Positioning API") or the System Manager.

The trade-off in selecting a positioning quality of service level is probable accuracy versus application performance. A value of 0 seconds or Exact guarantees that the actual current position is obtained; however, obtaining the actual position requires network round-trip to the service provider for each mobile positioning request. Such round-trip operations can slow application performance, especially if there are positioning requests for many users or many requests for the same user. You should use a value of 0 seconds or Exact only if the application always needs to know the actual position. A value of Low returns a location that is least likely to be accurate (unless the user has not moved at all); however, it increases the probability that the location will be obtained from the cache, eliminating the need for a network round-trip operation. If the user is not likely to move very far or fast, or if it is not important to know the actual current location, a value of Low may be best.

15.3.2.4 Specifying Positioning Providers

Automatic mobile position is queried by calling the Positioner.requestPosition function. (Positioner is a class in the oracle.panama.mp package). A Positioner object is based on one or more mobile positioning providers. As with other location service providers, a mobile positioning is configured by specifying information such as the name, version, URL, user name, and password.

However, a mobile positioning service differs from other location services in that in some cases positioning can only be handled by one specific provider, which is less likely to be true for other location based services. For example, if you request a map of California, several mapping providers are able to provide the map. However, if you request mobile position for a specific phone number (such as +4412345678), it is very likely only one provider can provide the position. A mobile ID (typically a phone number) usually identifies a wireless carrier and thus also determines the mobile positioning provider or providers. Therefore, application developers need to be able to get a positioner based on specific mobile positioning providers.

To meet different application needs, several getPositioner signatures are provided in the MPManager class:

• getPositioner()

• getPositioner(MPProvider provider)

• getPositioner(MPProvider[] providers)

An Internet portal may have subscribers from different carriers, and they may need to decide dynamically, based on the mobile ID, which provider to use at run time. This need is supported by mobile positioning provider selector hooks (implemented through the oracle.panama.mp.MPProviderSelector interface).

A provider selector hook takes a mobile ID and returns an array of MPProvider objects that can handle the positioning request. The default provider selector hook is provided by oracle.panama.mp.core.ProviderSelectorImpl, which returns all providers in the system, which means by default the positioning framework does not attempt to choose a provider. A selector hook is used by a positioner when calling positioner.requestPosition and is applicable for the getPositioner() signature. If the providers are already specified when the positioner is called, the selector hook is not used.

OracleAS Wireless API enables an application to access a mobile user's current location through the current session (Session.getCurrentLocation()). By default, the user's mobile ID (which is in the user's profile) is used to call the mobile positioning API to get the current position. However, if advanced users want to use a different value for positioning, they can write their own mobile ID hook by implementing the oracle.panama.rt.hook.MobileIDHook interface. A mobile ID hook takes the current user's information and returns his or her mobile ID for positioning. If the automatic positioning fails, the system fails over to the user's default location mark as the current location.

Note that you do not have to implement either the provider selector hook or the mobile ID hook. If the default settings meet your needs, you can simply configure mobile positioning providers and call MPManager.getPositioner().requestPosition().

To summarize:

• A Positioner can be a system default based on all mobile positioning providers configured in the system, or it can be customized based only on one or more specific providers.

• When a system default is used, a provider selector hook is used only when choosing the system default positioner. A selector hook takes a mobile ID and decides which provider or providers can handle it. In the case of batch query, the first mobile ID in the batch determines which provider is selected.

• Failover is provided when a positioner is based on more than one provider and a provider cannot handle the request.

Programs should check that the PositionResult has a nonzero error code before using it.

Example 15-31 gets the user's position using system default providers and the default positioning quality of service.

Positioner positioner = MPManager.getPositioner(); 
PositionResult res = positioner.requestPosition("46708123456790"); 
Date timeStamp = res.getTimeStamp(); 
double lon = res.getPositionAreas()[0].getCenterPointLongitude(); 
double lat = res.getPositionAreas()[0].getCenterPointLatitude(); 

PositionResult res = positioner.requestPosition("46708123456790", ServiceQoS.HIGH_QUAL); 

PositionResult res = positioner.requestPosition("46708123456790", new ServiceQos(120)); 

MPProvider[] providers = new MPProvider[2]; 
providers[0] = MPManager.lookup("CellPoint", "1.2"); 
providers[1] = MPManager.lookup("Ericsson", "3.0"); 
Positioner positioner = MPManager.getPositioner(providers); 

15.3.2.5 Granting and Revoking Positioning Rights

By default a user's location information can only be accessed by himself or herself. No other user has the right to access the user's location information. If users want to allow other users to access their location information, they must grant the positioning right to those users. A user granting the positioning right can later revoke the granted right.

The positioning right can also be granted for a certain duration or recurring interval of time. In many cases, users want to restrict the time periods to grant other users the right to access their location information. For example, users may want to grant coworkers this right from 9:00 am to 5:00 pm during weekdays, but they do not want coworkers to position them at night or during weekends. Users can specify such time restrictions as:

• Starting and ending dates of the granted right

• Starting and ending time during a day

• Exclusions: days that are within the start and end dates but are excluded from the positioning right, such as Saturdays and Sundays

15.3.2.6 Mobile Communities

A mobile community is a collection of one or more users who can be granted or denied positioning rights. Mobile users can be assigned to one or more communities, and users can grant and deny positioning rights to communities. Users can view and manage their community information through the Personalization Portal, and application developers can access these capabilities through the public API.

The concept of mobile community is useful in many application scenarios. For example, a project team can create a project community. A team member can grant to the project community the right of accessing to his or her location information instead of granting the right to each team member individually. For example, with mobile positioning and location-based alerts, a field service manager could know when service representatives are nearby and could contact them to get status updates or to have them respond to local problems.

The concept of visibility applies to communities and to members of communities. Visibility refers to the ability of system users to see that a community or member exists and to obtain some relevant information. Visibility can depend on the relationship of the requesting user to the community or member: for example, whether the requesting user has administrator privileges or is a member of the community in question. Visibility is implemented using calls to the privacy API, which is described in Section 15.3.2.9, "Privacy API".

For any given request by a user to see information about a community or members of a community, the following visibility conditions are possible:

• The community and the members of the community are visible to the requesting user.

• The community is visible to the requesting user, but the members of the community are not visible. For example, the community has been set up so that its existence is visible to all system users; however, information about community members is available only to administrators.

• The community is not visible to the requesting user, and therefore members of the community are not visible either.

Different types of communities are supported, to accommodate different user requirements for visibility. When you create a community, you can specify the type of community, namely:

• Private: A private community is visible only to the creator of the community, who has sole and complete control. No other users, including members of the community, can see or perform operations on a private community.

• Shared: A shared community is visible to all the community members but not to other users in the system. A community member is visible to all other community members. A community member can remove himself or herself from the community.

• Public with Member Visibility: A public community with member visibility is visible to all the users in the system. Any users in the system can add themselves to the community and remove themselves from the community.

• Public Member-Controlled Visibility: A public community with member-controlled visibility is visible to all the users in the system; however, each member can control whether he or she is visible or not visible to other users.

• System: A system community is visible to all users of the system, but the members are visible only to users who have administrator privileges. Users without administrator privileges cannot remove themselves from a system community.

The following community operations are supported:

• Create a community and add initial members

• Delete a community

• View a list of all the communities that are visible to the user

• View all the members in the community who are visible to the user

• Add users to a community (for the creator of a community)

• Remove users from a community (for the creator of a community, or any community member for removing himself or herself from a shared community)

15.3.2.7 Privacy Directives and Enabling/Disabling Automatic Positioning

With the initial default privacy settings, the system does not have the right to position a user and temporarily store the user's position in the location cache, and write the user's location information to the cache log. However, the administrator can use the OracleAS Wireless System Manager to specify a different system default level of privacy -- and users can control their level or privacy through the Personalization Portal -- by using any of the following privacy directives, listed in decreasing order of privacy provided:

• Disable Positioning and Caching: No positioning on the user is allowed. The system has no right to position the user, and no access to the user's location is allowed. This setting provides the most privacy.

• Enable Positioning, Disable Caching: The user's location information is not cached. The system has the right to position the user, but the system cannot store the user's location information in the location cache. In this case, the user's location is always obtained by going to the positioning service providers directly.

  For example, with this directive a mobile user's movements might not be tracked, and the position at any time might be reported as the user's office or whatever location the service provider supplies.

• No Log: The user's location information is stored in the location cache, but is not written to the cache log. Cache items for this user are not written to the log when they are replaced from the cache, but are simply discarded.

  For example, with the No Log directive, a mobile user's current position might be available, but earlier positions might not be available if they had discarded from the location cache.

• Enable Positioning and Caching: The system has the right to acquire and cache the user's location information.

15.3.2.8 Mobile Positioning API

Mobile device positioning is performed by calling the corresponding requestPosition functions in the Positioner class. The API allows application developers to specify the positioning quality of service (QoS) level. (These levels are explained in Section 15.3.2.3.)

15.3.2.9 Privacy API

Developers of applications can manage the privacy capabilities through the location services privacy API. This section describes the privacy API and provides examples.

CommunityManager commMan = CommunityManager.getInstance(); 
...
try{ 
     ResultSetEnumeration comms = commMan.getVisibleCommunities(user,type); 
     while (comms.hasNextElement()){ 
          sfo = XML.makeElement(sfs,"SimpleFormOption"); 
          oracle.panama.model.Community comm =
(oracle.panama.model.Community)(comms.next()); 
          sfo.setAttribute("value",String.valueOf(comm.getId())); 
          txt = XML.makeText(sfo,comm.getCreator().getName()+":"+ comm.getName() ); 
          sfo.appendChild(txt); 
          sfs.appendChild(sfo); 
    } 
  }catch(Exception e){ throw new AdapterException(e);    } 

CommunityManager commMan = CommunityManager.getInstance(); 
LocationPrivacyManager priMan = LocationPrivacyManager.getInstance(); 

...

SimpleDateFormat ddf = new SimpleDateFormat("MM/dd/yyyy"); 
SimpleDateFormat tdf = new SimpleDateFormat("HH:mm"); 
Calendar startD,endD,startT,endT=null; 
try{ 
    startD = Calendar.getInstance(); 
    startD.setTime(ddf.parse(sdate)); 

    endD = Calendar.getInstance(); 
    endD.setTime(ddf.parse(edate)); 

    startT = Calendar.getInstance(); 
    startT.setTime(tdf.parse(stime)); 

    endT = Calendar.getInstance(); 
    endT.setTime(tdf.parse(etime)); 

}catch(ParseException e){ 
      showError(result,sr,"Illegal Date Format","&grantmenu=y"); 
      return; 
} 

StringTokenizer st = new StringTokenizer(excl,","); 
String exclDate = null; 
byte exclusions=0; 
while (st.hasMoreTokens()) { 
    exclDate=st.nextToken(); 
    if ("Mon".equals(exclDate)) 
         exclusions =(byte)(exclusions|AuthPeriod.MONDAY); 
    else if ("Tue".equals(exclDate)) 
         exclusions =(byte)(exclusions | AuthPeriod.TUESDAY); 
    else if ("Wed".equals(exclDate)) 
         exclusions =(byte)(exclusions | AuthPeriod.WEDNESDAY); 
    else if ("Thu".equals(exclDate)) 
         exclusions =(byte)(exclusions | AuthPeriod.THURSDAY); 
    else if ("Fri".equals(exclDate)) 
         exclusions =(byte)(exclusions | AuthPeriod.FRIDAY); 
    else if ("Sat".equals(exclDate)) 
         exclusions =(byte)(exclusions | AuthPeriod.SATURDAY); 
    else if ("Sun".equals(exclDate)) 
         exclusions =(byte)(exclusions | AuthPeriod.SUNDAY); 
    else { 
        showError(result,sr,"Illegal Exclusions.", "&grantmenu=y"); 
        return; 
    } 
 } 

 AuthPeriod period = new AuthPeriod(startD,endD, startT,endT, exclusions); 
 oracle.panama.model.Community commObj = null; 
 User posUserObj = null; 
 try{ 
    if (community!=null && !community.equals("")){ 
       commObj = commMan.getCommunity(Long.parseLong(community)); 
       priMan.grantAuthorization(service,owner,commObj,period); 
    } 
   else{ 
      posUserObj = services.lookupUser(positionUser); 
      priMan.grantAuthorization(service,owner,posUserObj,period); 
  } 
}catch(PanamaException e){ throw new AdapterException(e);   } 

15.5.4.1 Tables for Region Data

Region data is stored in the OracleAS Wireless repository in the tables listed in Table 15-62.

To see the definition of any of these tables, use the SQL statement DESCRIBE. Example 15-37 shows the DESCRIBE statement output with information about all of the tables.

SQL> DESCRIBE continent;
 Name                                      Null?    Type
 ----------------------------------------- -------- ----------------------------
 ID                                        NOT NULL NUMBER
 NAME                                               VARCHAR2(100)
 REFCNT                                             NUMBER
 DESCRIPTION                                        VARCHAR2(2000)
 GEOMETRY                                           MDSYS.SDO_GEOMETRY

SQL> DESCRIBE country;
 Name                                      Null?    Type
 ----------------------------------------- -------- ----------------------------
 ID                                        NOT NULL NUMBER
 NAME                                               VARCHAR2(300)
 REFCNT                                             NUMBER
 CONT_ID                                            NUMBER
 DESCRIPTION                                        VARCHAR2(2000)
 GEOMETRY                                           MDSYS.SDO_GEOMETRY

SQL> DESCRIBE state;
 Name                                      Null?    Type
 ----------------------------------------- -------- ----------------------------
 ID                                        NOT NULL NUMBER
 NAME                                               VARCHAR2(400)
 REFCNT                                             NUMBER
 ABBR                                               VARCHAR2(32)
 CONT_ID                                            NUMBER
 COUNTRY_ID                                         NUMBER
 DESCRIPTION                                        VARCHAR2(2000)
 GEOMETRY                                           MDSYS.SDO_GEOMETRY

SQL> DESCRIBE county;
 Name                                      Null?    Type
 ----------------------------------------- -------- ----------------------------
 ID                                        NOT NULL NUMBER
 NAME                                               VARCHAR2(400)
 REFCNT                                             NUMBER
 CONT_ID                                            NUMBER
 COUNTRY_ID                                         NUMBER
 STATE_ID                                           NUMBER
 DESCRIPTION                                        VARCHAR2(2000)
 GEOMETRY                                           MDSYS.SDO_GEOMETRY

SQL> DESCRIBE city;
 Name                                      Null?    Type
 ----------------------------------------- -------- ----------------------------
 ID                                        NOT NULL NUMBER
 NAME                                               VARCHAR2(400)
 REFCNT                                             NUMBER
 CONT_ID                                            NUMBER
 COUNTRY_ID                                         NUMBER
 STATE_ID                                           NUMBER
 DESCRIPTION                                        VARCHAR2(2000)
 GEOMETRY                                           MDSYS.SDO_GEOMETRY
 MIN_LON                                            NUMBER
 MIN_LAT                                            NUMBER
 MAX_LON                                            NUMBER
 MAX_LAT                                            NUMBER

SQL> DESCRIBE postalcode;
 Name                                      Null?    Type
 ----------------------------------------- -------- ----------------------------
 ID                                        NOT NULL NUMBER
 NAME                                               VARCHAR2(400)
 REFCNT                                             NUMBER
 CONT_ID                                            NUMBER
 COUNTRY_ID                                         NUMBER
 STATE_ID                                           NUMBER
 DESCRIPTION                                        VARCHAR2(2000)
 GEOMETRY                                           MDSYS.SDO_GEOMETRY

SQL> DESCRIBE userdefined;
 Name                                      Null?    Type
 ----------------------------------------- -------- ----------------------------
 ID                                        NOT NULL NUMBER
 NAME                                               VARCHAR2(200)
 REFCNT                                             NUMBER
 TYPE                                               NUMBER
 PARENT_FOLDER_ID                                   NUMBER
 DESCRIPTION                                        VARCHAR2(2000)
 GEOMETRY                                           MDSYS.SDO_GEOMETRY

15.5.4.2 Inserting Data into Region Tables

You can use the SQL statement INSERT to insert rows into the region tables. The following considerations apply when you are inserting region data:

• You should use idseq.nextval to generate the ID column value whenever you insert a new row, as shown in Example 15-38. The idseq sequence is created automatically during installation; you should not create it.

• The REFCNT column should be set to 0 (zero) when you insert a row. The REFCNT column contains the reference count of how many services are associated with the region. The value is automatically incremented when a service is associated with the region and decremented when it is disassociated from the region or when the service is deleted. A region with a nonzero REFCNT value cannot be deleted.

• If you are inserting data about postal codes, cities, or counties for a country that does not use the default region hierarchy, specify 0 (zero) as the STATE_ID in POSTALCODE, CITY, or COUNTY table.

• The GEOMETRY column value must be a valid Oracle Spatial geometry of type MDSYS.SDO_GEOMETRY. The SDO_GTYPE value must be 4 digits, and the SRID (coordinate system) value must be 8307 (for WGS-84 longitude/latitude format). If the SRID value is not currently 8307, you must transform geometries into that format before inserting them into the region data tables. For detailed information about the spatial data type, coordinate systems, and coordinate system transformation, see the Oracle Spatial User's Guide and Reference.

Example 15-38 shows an INSERT statement to insert a row for Concord, Massachusetts into the CITY table. It assumes that the geometry representing Concord exists in another table named MY_CITIES.

DECLARE
  city_geom MDSYS.SDO_GEOMETRY;

BEGIN

-- Populate geometry variable with city geometry from another table.
SELECT m.geometry into city_geom FROM my_cities m
  WHERE m.name = 'Concord';

-- Insert into the CITY table.
INSERT INTO CITY VALUES (
   idseq.nextval,
   'Concord',
   0,
   5004, -- continent ID for North America
   5006, -- country ID for USA
   5028, -- state ID for Massachusetts
   'The historic town of Concord',
   city_geom,
   -71.35, -- minimum longitude
   42.46, -- minimum latitude
   -71.34, -- maximum longitude
   42.47); -- maximum latitude
END;
/

15.6.2.1 Geocoding Services: Available Functions

A geocoding service proxy must implement the following function:

public Location[] geocodeAddress(Location inp, String matchMode);

A geocoding service proxy may implement the following functions:

public Location[][] geocodeAddresses(Location[] inp, String matchMode);
public Location[] reverseGeocodePoint(Point pt);

A geocoding service proxy must not implement the following function:

public String xmlGeocode(Document xmlRequest);

15.6.2.2 Mapping Services: Available Functions

A mapping service proxy must implement the following function:

public String getMapURL(Point[] locations, ImageFormats fileType, double minLon, double maxLon, double minLat, double maxLat, int width, int height, boolean allowTurning);

A mapping service proxy must not implement the following functions:

public String getMapURL(Point[] locations, ImageFormats fileType, int width, int height, boolean allowTurning);
public String getMapURL(Point location, ImageFormats fileType, int width, int height, boolean allowTurning);
public String getMapURL(RoutingResult route, boolean allowTurning);
public String getMapURL(Maneuver man, boolean allowTurning);
public String getMapURL(Point location, ImageFormats fileType, double minLon, double maxLon, double minLat, double maxLat, int width, int height, boolean allowTurning);
public String[][] getMapURLs(Point[] locations, ImageFormats fileType, int width, int height, int subdivisionLevel, boolean allowTurning);
public String[][] getMapURLs(Point[] locations, ImageFormats fileType, double minLon, double maxLon, double minLat, double maxLat, int width, int height, int subdivisionLevel, boolean allowTurning);
public String[][] getMapURLs(Point location, ImageFormats fileType, int width, int height, int subdivisionLevel, boolean allowTurning);
public String[][] getMapURLs(Point location, ImageFormats fileType, double minLon, double maxLon, double minLat, double maxLat, int width, int height, int subdivisionLevel, boolean allowTurning);
public String[][] getMapURLs(RoutingResult route, int subdivisionLevel, boolean allowTurning);
public String[][] getMapURLs(Maneuver man, int subdivisionLevel, boolean allowTurning);
public String xmlMap(Document xmlRequest);

15.6.2.3 Routing Services: Available Functions

A routing service proxy must implement the following function:

public RoutingResult computeRoute(Point source, Point destination, Point[] viaPoints, RoutingSettings opt, Locale locale);

A routing service proxy may implement the following functions:

public RoutingResult computeRoute(Location source, Location destination, Location[] viaPoints, RoutingSettings opt, Locale locale);
public Ranking rankByDrivingDistance(Point source, Point[] locations);

A routing service proxy must not implement the following function:

public String xmlRoute(Document xmlRequest);

15.6.2.4 Traffic Services: Available Functions

A traffic service proxy must implement the following functions:

public TrafficReport getReportViaCity(CityInfo city) throws LBSException;
public TrafficReport getReportViaLocation(Point location, double radius, int unit, CityInfo city) throws LBSException;
public TrafficReport getReportViaRoute(RouteInfo route, CityInfo city) throws LBSException;
public TrafficReport getReportViaRoute(RouteInfo route, String direction, CityInfo city) throws LBSException;

A traffic service proxy must not implement the following functions:

public TrafficCityManager getCityManager();
public TrafficReport getReportViaLocation(Point location, double radius, int unit) throws LBSException;
public TrafficReport getReportViaAddress(Location address, double radius, int unit) throws LBSException;
public String xmlTraffic(Document xmlRequest) throws LBSException;

15.6.2.5 Business Directory (YP) Services: Available Functions

A business directory (YP) service proxy must implement the following functions:

public YPBusiness[] getBusinessesInCity(String businessName, String country, String state, String city, Locale locale);
public YPBusiness[] getBusinessesInState(String businessName, String country, String state, Locale locale);

A business directory (YP) service proxy may implement the following functions:

public Boolean anyBusinessesInCity(YPCategory category, String country, String state, String city);
public Boolean anyBusinessesInState(YPCategory category, String country, String state);
public Boolean anyBusinessesInPCode(YPCategory category, String country, String postalCode);
public Boolean anyBusinessesInRadius(YPCategory category, Point location, double metersRadius);
public YPBusiness[] getBusinessesInRadius(String businessName, Point location, double metersRadius, Locale locale);
public YPBusiness[] getBusinessesInPCode(String businessName, String country, String postalCode, Locale locale);
public YPBusiness[] getBusinessesInCity(YPCategory category, String country, String state, String city, Locale locale);
public YPBusiness[] getBusinessesInState(YPCategory category, String country, String state, Locale locale);
public YPBusiness[] getBusinessesInRadius(YPCategory category, Point location, double metersRadius, Locale locale);
public YPBusiness[] getBusinessesInPCode(YPCategory category, String country, String postalCode, Locale locale);
public YPBusiness[] getNearestNBusinesses(String businessName, Point location, int n, Locale locale);
public YPBusiness[] getNearestNBusinesses(YPCategory category, Point location, int n, Locale locale);

A business directory (YP) service proxy must not implement the following functions:

public Boolean anyBusinessesInSameCity(YPCategory category, Location loc);
public Boolean anyBusinessesInSameState(YPCategory category, Location loc);
public Boolean anyBusinessesInSamePCode(YPCategory category, Location loc);
public YPBusiness[] getBusinessesInSameCity(String businessName, Location loc, Locale locale);
public YPBusiness[] getBusinessesInSameState(String businessName, Location loc, Locale locale);
public YPBusiness[] getBusinessesInSamePCode(String businessName, Location loc, Locale locale);
public YPBusiness[] getBusinessesInSameCity(YPCategory category, Location loc, Locale locale);
public YPBusiness[] getBusinessesInSameState(YPCategory category, Location loc, Locale locale);
public YPBusiness[] getBusinessesInSamePCode(YPCategory category, Location loc, Locale locale);
public YPBusiness[] getBusinessesInSameCity(String businessName, YPCategory category, Location loc, Locale locale);
public YPBusiness[] getBusinessesInSameState(String businessName, YPCategory category, Location loc, Locale locale);
public YPBusiness[] getBusinessesInSamePCode(String businessName, YPCategory category, Location loc, Locale locale);
public YPBusiness[] getBusinessesInCity(String businessName, YPCategory category, String country, String state, String city, Locale locale);
public YPBusiness[] getBusinessesInState(String businessName, YPCategory category, String country, String state, Locale locale);
public YPBusiness[] getBusinessesInRadius(String businessName, YPCategory category, Point location, double metersRadius, Locale locale);
public YPBusiness[] getBusinessesInPCode(String businessName, YPCategory category, String country, String postalCode, Locale locale);
public YPBusiness[] getNearestNBusinesses(String businessName, YPCategory category, Point location, int n, Locale locale);
public String xmlYP(Document xmlRequest);