|
Oracle® Application Server Wireless Developer's Guide
10g Release 2 (10.1.2) B13819-02 |
|
 Previous |
 Next |
|
Oracle® Application Server Wireless Developer's Guide
10g Release 2 (10.1.2) B13819-02 |
|
|
Previous |
Next |
This chapter provides conceptual and usage information for developers of location-based applications. It contains the following major sections:
Developers of location-based applications need specialized services for:
Mobile positioning: associating a location with a mobile user
Geocoding: associating geographical coordinates with addresses
Mapping: providing a graphical map for a point, set of points, route, or driving maneuver
Routing: providing driving directions
Business directories (Yellow Pages): listing businesses by region by either category or name
Traffic: providing information about accidents, construction, and other incidents that affect traffic flow
Several companies provide these types of specialized content and applications. For example, some Web sites have categories for business directories, and some sites provide driving directions. Developers building applications based on the OracleAS Wireless framework can benefit from being able to use the specialized content and services. It is inefficient for each application to write custom interfaces to all the services that it wants to access.
OracleAS Wireless location application components are a set of APIs (application programming interfaces) for performing geocoding, providing driving directions, and looking up business directories. Service proxies are included that map existing important providers to the APIs, and additional providers are expected to be accommodated in the future.
OracleAS Wireless application developers can take advantage of a uniform interface to access different service providers without having to make any changes to their applications. They can also use the infrastructure to prioritize services based on criteria such as quality, availability, or cost. Service providers also benefit from the fact that their contents and specialized functions are available out-of-the-box to all OracleAS Wireless application developers.
This section introduces the location application components API, describes how to find the detailed javadoc-generated documentation and online examples, and explains conceptual and usage information that you must understand before using the components. It contains the following major subsections:
Section 15.1.2, "Using the System Manager Interface for Location-Related Information"
Section 15.1.11, "Business Directory (Yellow Pages) Services"
|
Note: For more information, examples, and other resources, see http://www.oracle.com/technology/products/iaswe/lbs/index.html |
To get started using the OracleAS Wireless location application components, follow these steps:
Read the conceptual and usage information in this document before using any example programs or creating any applications.
Go to the sample directory, which contains example files. Read the Readme.txt file in that directory; examine the supplied files, and use any that meet your needs.
View the javadoc documentation, and refer to it for detailed reference information about packages and classes. To view the javadoc documentation, open the following file in a Web browser:
iAS-Wireless-Home/wireless/doc/index.html
where ias-Wireless-Home is your OracleAS Wireless home directory.
You can use the OracleAS Wireless System Manager (referred to as System Manager) interface within Enterprise Manager to perform configuration operations and find information relating to location application components.
In the Wireless Server System tab page, click Site Administration.
Click to expand Component Configuration.
Figure 15-1 shows the System Manager page with the Component Configuration section expanded.
Figure 15-1 Component Configuration Section of Wireless System Manager
As shown in Figure 15-1, the Location-Related section in the Component Configuration section contains the following links:
Location Management for mobile positioning configuration, mobile positioning provider information and configuration, and mobile ID names
Location Services for configuration options relating to geocoding, routing, mapping, traffic, and business directory services
Location Event Server for options relating to the location event server (described in Section 15.4)
Location Mark Address Format for specifying location mark address fields
Location services are based on the architecture shown in Figure 15-2.
Figure 15-2 Location Services Architecture
As shown in Figure 15-2:
An alert engine and location-based applications are outside the architecture (enclosed in a thick line), but communicate with it.
The architecture can process requests that use Java, XML, or JSP tags.
The processing is handled by components that handle specific activities and kinds of service: business directory, geocoding, routing, map support, region support, positioning, location query, location cache, and privacy management.
The provider connector framework communicates with local and external sources of data and service, and has components for the various kinds of available providers, such as business directory, routing, mapping, and mobile positioning.
Location services are provided in the following major categories: geocoding, mapping, routing, business directory (Yellow Pages), and traffic.
Other sections in this chapter describe how to specify and configure external providers for location services, and describe each type of service in greater detail.
The SpatialManager Java class manages all these location services, and is defined as follows:
package oracle.panama.spatial;
import ...;
public class SpatialManager
{
public static synchronized Geocoder getGeocoder() {...}
public static synchronized Router getRouter() {...}
public static synchronized YPFinder getYPFinder() {...}
public static synchronized Mapper getMapper() {...}
public static synchronized TrafficReporter getTrafficReporter() {...}
}
The actual core computation for location services is generally performed at an external provider. The external provider might be accessed over the Internet or other means of communication, or might be local. OracleAS Wireless Location Application Components API performs the communication and adaptation of results in a unified framework, so that users are generally not aware of which provider is supplying a particular service. In addition, the API minimizes the application developer's implementation effort and dependence on specific providers.
Access to an initial set of providers for most services is included. Some providers have full configuration information included, and some do not. (For providers that do not have configuration information, you usually receive the necessary information after you purchase the right to use their user name and password.)
You can provide access to additional providers by using the OracleAS Wireless System Manager through the Enterprise Manager interface. If a a new provider is added and if the provider does not use the same interface as an existing provider, a Java class must be created to translate between the provider's format and the Wireless location application components API. (This program is specified as the ProviderImpl attribute.) In addition, the implementing class file for the program must be added to the class path.
Using multiple providers for a service increases the probable reliability of the service. The API fails only either if all providers fail or if Web access is temporarily unavailable. Because providers are specified in preference list, the API automatically fails over when the preferred provider cannot perform the requested service, such as when any of the following occurs:
The provider is temporarily inaccessible over the Web.
The provider does not support the exact requested service.
The request is incorrectly specified (such as a nonexistent address).
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:
In the Wireless Server System tab page, click Site Administration.
Click to expand Component Configuration.
Click Location Services in the Configuration subsection. The Location Services page is displayed, as shown in Figure 15-3.
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.
To configure the provider information, on the Location Services page under Location Service Configurations (shown in Figure 15-3 in Section 15.1.5.1), select the appropriate type of service for configuration:
Geocoding Configuration
Routing Configuration
Mapper Configuration
Traffic Configuration
YP Provider Configuration
The provider information (described in Section 15.1.5.1.2, "Provider Configuration") is very similar for all types of services (geocoding, mapping, routing, traffic, and YP).
For geocoding and perhaps other services, you may need to provide configuration information for country name aliases (see Section 15.1.5.1.3, "Country Name Alias Configuration") and address formats (see Section 15.1.5.1.4, "Address Format (International) Configuration").
If the administrator configures the provider list (using the OracleAS Wireless System Manager) to include a Web services proxy, any location service request will automatically (and transparently) use Web services. For information about using Web services, see Section 15.2.3, "Using Web Services".
An ordered list of providers is configured with the following parameters:
Provider Name: the provider name, which serves as an ID
Provider Impl Class: the class implementing the proxy for this provider (for translation and communication with the provider)
URL: the static URL prefix used to access the provider
User Name: a user name as determined by the provider
Password: the password to be used in combination with the user name
Parameters: any parameters required to customize and configure the provider proxy
ISO Locales: a semicolon-delimited list of country IDs (as specified in the country name alias list, described in Section 15.1.5.1.3)
Corporate URL: the corporate URL of the provider (used as an advertisement)
Service Version: the service version for the provider that this proxy uses
Corporate Logo URL: the corporate logo URL of the provider (used as an advertisement)
The country name alias configuration relates country names and synonyms to a single standard identifier for a given country. This standard identifier should be the ISO name (US for United States, DE for Germany, and so on), although you can specify other identifiers.
The aliases are used in combination with the oracle.panama.spatial.core.ruleengine.RuleEngineImpl provider selection framework implementation. Each provider is configured for a set of countries, specified by their IDs. For example, when a service request is made, for example to geocode an address in the United States, the country alias table is consulted to find the standard ID US. Subsequently, only providers with US in their list of covered countries are tried.
If a country name is used which is not configured as a known alias for some country ID, the ID unknown is used, instead. In this case, providers with unknown in the covered country list are tried.
If the simple provider selection framework implementation (oracle.panama.spatial.core.ruleengine.SimpleRuleEngineImpl) is used, country aliases are not required for provider selection.
The address format configuration is used to specify international address formats. The oracle.panama.spatial.intladdress package in the API uses this list to determine which components are part of an address (US, French, German, Chinese, and so on) and how they are presented for input and output.
The international address framework is configured with a list of address formats in the repository, accessible through the OracleAS Wireless System Manager. This configuration specifies all components of an address, aliases for the components, and mappings to standard concepts such as city, state, and street name. The format of the textual representation is also configured, to determine such things as:
How is the address usually divided into separate lines?
In which sequence do the components occur?
Which components are optional, and which are required?
This approach requires that users specify a country-specific format for addresses, in order to view and enter addresses in that format. Otherwise, for example, the system cannot know whether to ask a user to specify a state or province before the country.
The benefits of this approach include the following:
Users see a form that exactly matches the desired address format for mailed letters.
The system can better analyze addresses when each component is known separately and meaningfully identified, rather than simply being included somewhere in first line, second line, and last line.
An application looks more professional if it automatically adapts to the local address format, both for input and output of addresses.
Outside the US, customers are much more impressed when presented with their local address format, as opposed to the US format.
The application does not have to be rewritten for different countries. Everything is handled automatically by the framework
Several international address formats are supplied. Two examples are as follows.
For the US:
{name}
{house number/house} {street}[ Apt {apt}]
{city} {state} {postal code}[-{postal code ext}]
{country}
For Germany:
{Name/name}
{Strasse/street/first line} {Hausnummer/house}[ Wohnung {Wohnung/apt}]
{PLZ/postal code} {Stadt/city}
[{Bundesland/state}]
{Land/country}
Syntax notes:
{ } (braces) enclose an address component.
/ (slash) separates alternative aliases within a component.
[ ] (brackets) enclose optional elements.
Anything outside braces other than brackets is taken as quoted from an address (such as Apt in 123 Main Street Apt 4).
For programming information and examples relating to international address formats, see Section 15.2.2.1.1, "International Addresses".
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.
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:
In the Wireless Server System tab page, click Site Performance.
In the Component Performance section, click Location-Related.
The geocoding API provides the geographic location of a given address. For a user of Wireless, an address is the most common way to specify a location. However, for finding locations such as restaurants in close vicinity or providing driving directions, the text representation of an address may not be useful unless it is first geocoded, that is, translated to geographic coordinates.
The address to be geocoded has a textual representation like that from a standard mailed letter. The result returned is the longitude/latitude corresponding to the address. For example, the input to geocoding might include the following:
firmName: "oracle"
firstLine: "1 Oracle Drive"
secondLine: ""
lastLine: "Nashua NH 03062"
matchMode: "tight"
In this example, the result is: Point( x = -71.455, y = 42.7117)
Because a user might specify an ambiguous address, the GeocodeResult contains an array of Location objects instead of a single object.
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.
The Point class defines a longitude/latitude coordinate point. Additional values for a label and a radius can be used for representing a point on a map. The label and radius are not used by any other functions than map display.
The Location class defines a location with address and longitude/latitude. If the location object is constructed using firstLine, secondLine, and lastLine, then some external providers might not correctly identify the city or state, because lastLine can contain city, state, and postal code in a country-specific and relatively flexible format.
If no specific substring can be identified as the component representing the city, the city is "unknown". In this case, the API itself might not try complex analysis, but instead leave this task to the experts, that is, the external geocode providers.
Due to the limitations of certain mobile devices such as telephones, it is difficult to input/display lengthy alphanumeric strings. A location mark stores a piece of spatial information identified by a concise, easy-to-understand name. For example, My home might be the name of a location mark, while the underlying spatial information might be 123 Main Street, Somewhere City, CA, 12345; Lon = -122.42, Lat = 37.58.
Location marks allow users to avoid inconvenient string input on mobile devices. Users can manage their location marks on a desktop and then access them by referring to their names from mobile devices. Today's location-aware applications typically just use a point location (such as an address or a road intersection). In this case, the spatial information can be provided by geocoding. However, a location mark can also be a circular area around a point (that is, if you specify a point and a radius) or a region that has been defined using the region modeling tool (described in Section 15.5).
Location marks also allow users to try what-if scenarios: to make an application behave as if they were in a location different from their default or current location. For example, a user of an entertainment services application might actually be in Boston now, but will be traveling to San Francisco in a few days. This person could set a location mark in San Francisco as the default, and be presented with information relevant to the San Francisco area.
Each user has personalized location marks, which are stored in the Wireless repository.
A default location mark can be set for each user. If there is no mobile positioning information for a user, that user's default location mark (if defined) is used. For example if the default location mark for user Smith is that person's office, and if there is no current positioning information for Smith, the current location is assumed to be Smith's office.
Location marks are created using the LocationMark class. Users can also create location marks by logging into the Customization Portal, clicking the LocationMarks tab, and clicking Create.
For information about using a location mark to enable mobile positioning, see Section 15.3.1, "Manual Positioning".
A new table named LOCATIONMARK is added to the Wireless repository schema. This table contains detailed information about each location mark, including the user associated with each location mark. For example, several users might have a location mark named Office but with a different location for each.
The mapping API provides functions for creating map images for any of the following:
A single point (such as an address or a location mark)
Multiple points (such as several addresses or location marks)
A complete route
A single driving maneuver
The mapping API lets you specify the size (resolution) of the map and the image format.
Mapping capabilities can be made visible to users as a purely mapping application or as part of a routing application. In a routing application, the mapping of routes and driving maneuvers is performed by the routing provider. For information about routing services, see Section 15.1.10, "Routing Services".
The routing API provides routing (driving directions) information based on a start point, an end point, and optionally a list of intermediate via points. All points are specified as longitude/latitude pairs or addresses.
The routing result consists of a set of maneuvers. A maneuver corresponds to a driving instruction, such as turn left onto I-93 or bear right and merge to Route 3. The routing result also includes estimated driving time and distance. Optionally, maps and route coordinates can be requested.
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
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.
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.
This section describes the routing API for location application components.
The Router interface defines how an application programmer accesses the routing service. An object of a class implementing this interface is returned by the SpatialManager.
The RoutingSettings class defines a set of options passed to routing. There are two types of routing options: basic and secondary.
Basic options include whether or not to request a map or a geometry. Basic options can be specified in the constructor of a RoutingSettings object.
Secondary options can be set using setSecondaryOption. The first parameter is a RoutingOption object, which is a static constant defined in the RoutingOption class. It identifies the option for which a value is set. The second parameter is a String representing the value.
Whether or not the secondary option is mandatory is defined by setSecondaryOptionRequired. The first parameter is the RoutingOption and the second parameter specifies whether this option requirement is mandatory. Unless this function is called, the default value is assumed.
The RoutingResult class defines the routing results, which are described in Section 15.1.10.2.
The Maneuver class defines a single maneuver in a route (see Section 15.1.10.2, "Routing Results" for the maneuver attributes).
Business directory (Yellow Pages, or YP) services provide lists of businesses in a given area and matching a specified name or category.
Existing providers use YP services with different interfaces. Specifically, they all have different YP categories, and even different hierarchical structures. The categories might be organized in a flat list or in a hierarchy of categories and subcategories. A hierarchy tree might be deep or shallow, with a high or low fanout, and might be balanced or unbalanced.
To unify the service of different providers, the Oracle business directory services use a custom hierarchy that the OracleAS Wireless developer defines in an XML file. Each leaf in this hierarchy has a reference to a category of one or more providers. Non-leaf nodes might also have such references. This custom hierarchy defines preferred categories first. Subsequently, the carrier using OracleAS Wireless tries to match these categories to semantically similar categories supported by external providers.
The customized hierarchy with the references to external providers' categories is represented in an XML file that stores hierarchical and ordered structures. Representing order in the category hierarchy can account for the popularity of different categories. For example, on a device with a limited screen size, an application might restrict the choices among the most popular categories.
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.
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.
Example 15-1 Business Directory Category Hierarchy Definition File
<?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>
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
The YPFinder interface defines how an application programmer accesses the YP service. An object of a class implementing this interface is returned by the SpatialManager.
An object of this class lets the user query:
Businesses in a state
Businesses in a city
Businesses in a postal code
Businesses in a radius around a center
The closest n businesses around a center
In each of these region types, businesses can be found:
Matching a given business name or keyword
Matching a given category
Matching both a given business name or keyword and a given category
Matching a keyword in either a business name or category
The YPCategory class defines a single category that is part of the hierarchy. This class lets users access businesses in the category. It also lets users find subcategories of the category; specifically, you can find:
All the direct subcategories
All direct or indirect subcategories matching a keyword
A subcategory with a given name
One of the most popular applications probably is to find subcategories of the root matching a given keyword.
The YPBusiness class defines a single business. It represents an address (Location interface) that also has a telephone number, a description, and a list of categories it matches. You can get all businesses in a category or all categories for each of these businesses. For example, a given bookstore might be both in the categories book store and cafe.
The traffic API provides information about conditions that can affect traffic flow on road networks in major metropolitan areas. These areas are typically further divided into smaller areas, such as downtown, metro West, metro East, and so on. Real-time traffic reports update conditions in short time periods (such as every 5 minutes), thus providing information that is important for fleet management as well as personal navigation.
The major components of traffic reports are incidents. An incident is an event that will probably affect the flow of traffic. Examples of incidents are accidents, construction activity, and traffic congestion (normal or unexpected). Each incident includes such information as the type of incident, where the incident occurred (such as the route number, the location, or the region), the direction along the route (such as northbound), the expected delay, and the length of the traffic backup.
For the current release, the following kinds of queries are supported for incident-based traffic information:
City-level query: return traffic incidents in the entire city.
Route-level query: return traffic incidents on the specified route in a city.
Longitude/latitude (point) or address plus radius-level query: return traffic incidents in the requested circular area.
Examples of traffic queries include returning the traffic report for:
A metropolitan area (such as Boston)
A route in a metropolitan area (such as I-93 South in Boston)
A planned route (such as from Nashua, NH to Boston, MA), returned as a collection of (route, city)
A mobile range consisting of a location (longitude, latitude) and a radius from the location
The vicinity of a given address (such as One Oracle Drive, Nashua, NH 03062)
The traffic API processes requests and returns responses. The requests and responses can be in Java or XML format. Section 15.1.12.2 provides examples of an XML request and response in XML format. Section 15.1.12.3 describes the traffic Java API.
|
Note: For the current release, no traffic service providers are included in the sample configuration files. |
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.
Example 15-2 shows a city-level request in XML format for traffic information for Boston.
Example 15-2 Traffic Request 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>
Example 15-3 shows a response in XML format for traffic information for Boston.
Example 15-3 Traffic Response for Boston
<?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>
This section describes the traffic Java API for location application components.
The CityInfo class provides the city name, state name, and country name for a city. A common use of this class is to create a CityInfo instance with city name, state name (optional), and country name, and pass it to the query for a traffic report at city level, route level, or point and radius level with a city.
The City interface provides information about a city from a specified service provider. The information includes the city name, state name, country name, and information about routes. A City instance could be obtained from the TrafficReport interface.
The RouteInfo class provides the name and type for a route. A common use of this class is to create a RouteInfo instance and pass it to the query for a traffic report at route level.
The TrafficRoute interface provides information for a route from a specified service provider. The information includes the route name, route type, geometry that represents the route, and the city name. A TrafficRoute instance could be obtained from the TrafficIncident interface.
The TrafficReport interface provides information for an incident-based traffic report, such as the report time, the number of incidents, the provider's information, the city, and the incidents. A report could then be created to show to users or administrators of the application.
The TrafficIncident interface provides information for a traffic incident, such as the severity, type, description, route and direction on which the occurred, location, time range, impact, and advice.
The TrafficReporter interface provides functions that return a traffic report based on different queries. The following kinds of queries are supported:
Given the information about a city (city name, state name [optional], country name), return the report.
Given the information about a route (with or without direction) and the city where the route is located in, return the report.
Given the longitude/latitude coordinates of a point and the radius, return the report for the area.
Given the address of a location and the radius, return the report for the area.
When using SpatialManager.createLocation() to get an instance of Location, you must specify the city name and country name. Do not use the LastLine attribute to combine these pieces of information. Set the value of the Point geometry to null to avoid automatic geocoding.
The TrafficCityManager interface provides two functions, one to obtain all the cities for which traffic information is provided, and the other to obtain the routes info for a given city. A common use of these functions is to call them to create a drop-down list of cities and routes supported by the application.
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.
To add support for a new traffic service provider, follow these steps:
Using the System Manager, set the traffic provider information and the traffic report cache time.
For each supported city of this new provider, use the region modeling tool (described in Section 15.5) to check if there is an entry in the CITY table for that city, including a valid GEOMETRY column value. If there is not an entry for the city, including its geometry, add an entry.
Get and note the ID of this city.
Use SQL*Plus connect to the Wireless repository.
For each city to be supported for this traffic service provider, set the value of the COVERED_BY_TRAFFIC column in the CITY_COVERAGE table to 'Y', and use the value of city's ID to perform the update. For example:
UPDATE city_coverage SET covered_by_traffic = 'Y' WHERE id = 12345; COMMIT;
If there is not already an entry in the CITY_COVERAGE table for this city, add a row and set the value of the COVERED_BY_TRAFFIC column to 'Y', and be sure that the ID value in this table is the same as the ID value for the city in the CITY table. For example:
INSERT INTO city_coverage (id, name, state_name, country_name,
covered_by_traffic) VALUES (10750, 'BOSTON', 'MA', 'US', 'Y');
COMMIT;
To add support for a new city for an existing traffic service provider, follow these steps:
For each supported city of this new provider, use the region model tool (described in Section 15.5) to check if there is an entry in the CITY table for that city, including a valid GEOMETRY column value. If there is not an entry for the city, including its geometry, add an entry.
Get and note the ID of this city.
Use SQL*Plus connect to the Wireless repository.
If there is an entry in the CITY_COVERAGE table for this city, set the value of the COVERED_BY_TRAFFIC column in the CITY_COVERAGE table to 'Y', and use the value of city's ID to perform the update. For example:
UPDATE city_coverage SET covered_by_traffic = 'Y' WHERE id = 12345; COMMIT;
If there is not already an entry in the CITY_COVERAGE table for this city, add a row and set the value of the COVERED_BY_TRAFFIC column to 'Y', and be sure that the ID value in this table is the same as the ID value for the city in the CITY table. For example:
INSERT INTO city_coverage (id, name, state_name, country_name,
covered_by_traffic) VALUES (10750, 'BOSTON', 'MA', 'US', 'Y');
COMMIT;
Location-based examples are provided with Oracle Application Server Wireless. You can use these samples to learn about Location-based services, and as a starting point for developing your own applications. Here is a scenario:
A field service engineer is at a customer site fulfilling a service request. Upon completion of the project, the engineer notices that a another piece of equipment is out of order. The engineer walks towards the piece of equipment, takes out a handheld device, and clicks on the Create New Service Request button. The engineer's position is automatically logged by the service station, and a menu is presented for entering the description of the new request, attaching a map, and generating driving directions to the location. All this information is sent to the service station and an alert is automatically sent to an engineer who will be assigned to service this new request.
Development Options
As a developer of Oracle LBS applications, you have several options when deciding which approach to take.
If you are writing an application that will run on a server, you should use server-side Java API or Java Server Pages (JSP) tags from our pre-defined JSP tag library.
If you are writing an application that will run remotely, the Wireless Development Kit (WDK) is a better approach. See Chapter 8, "OracleAS Wireless Developer Kit" for detailed explanations of these options.
Description of Examples
The examples in the sample directory demonstrate the application development approaches mentioned above. In turn, each approach contains three examples that show the functionality of the Geocoder, Mapper, and Router.
The first folder, titled Java, contains three server-side Java API examples. The first, GeocoderExample.jsp, demonstrates the functionality of the LBS Geocoder. The second, MapperExample.jsp, demonstrates the functionality of the Mapper. The third example, RouterExample.jsp, demonstrates the functionality of the Router.
The second folder, titled JSP contains three examples that use the JSP tag library. The first, GeocoderExample.jsp, demonstrates the functionality of the LBS Geocoder. The second, MapperExample.jsp, demonstrates the functionality of the Mapper. The third example, RouterExample.jsp, demonstrates the functionality of the Router.
The third folder, titled WDK contains three examples that use the Wireless Development Kit. The first, GeocoderExampleWDK.java, demonstrates the functionality of the LBS Geocoder. The second, MapperExampleWDK.java, demonstrates the functionality of the Mapper. The third example, RouterExampleWDK.java, demonstrates the functionality of the Router.
In addition to the Geocoder, Mapper, and Router, the LBS platform provides several other features, such as the Yellow Pages business finder. Demonstration of the YP functionality requires a slightly more elaborate setup and is thus available with separate setup instructions for download from Oracle Technology Network.
Developing Your Own Applications
The LBS examples are meant to show you the basic functionality of the LBS platform while using the minimal amount of code. They are independent of one another, and each example only shows one function of the LBS platform. When writing a general LBS application, you will use several of these components in the same application. For example, you may want to write an application which positions the user, displays his location on a map, finds the three nearest restaurants around him, and provides driving directions from his current location to the nearest restaurant. Such an application would make use of many LBS features. The Positioner finds the user location, the Mapper shows him on a map, the YPFinder finds the three nearest restaurants, and the Router would provide the driving directions.
Setup Requirements
To run the server-side Java and JSP tags examples, the files must be copied to the ORACLE_HOME/j2ee/OC4J_Wireless/applications/wireless/location-web/ directory. In addition, a valid geocoder, mapper, and router must be configured by the server administrator. See this document, and OTN for details on configuring providers, and a list of providers that are currently available. To configure eLocation, see OTN.
WDK examples can be run on a remote client or in JDeveloper. There are several jars that are needed for proper compilation and execution of the WDK examples. These jars are:
ORACLE_HOME/wireless/lib/wdk.jar
ORACLE_HOME/j2ee/home/lib/http_client.jar
ORACLE_HOME/lib/xmlparserv2.jar
ORACLE_HOME/soap/soap.jar
In addition, providers must be properly configured on the instance that the WDK will be pointing to for requests. See this guide and OTN for provider configuration information.
You can develop a location-based application by using any of the following approaches:
Creating Java Server Pages (JSP) files that contain OracleAS Wireless XML and/or HTML tags and that include custom Oracle-supplied tags (see Section 15.2.1, "Creating Java Server Pages (JSP) Files")
Using the Java API in JSP files (see Section 15.2.2, "Using the Location Java API")
Using Web services (see Section 15.2.3, "Using Web Services")
Using tags in JSP files is often easier and more convenient than using the Java application programming interface (API); however, using the API gives you greater flexibility and control over the application logic.
If you do not need to write an adapter, you can create Java Server Pages (JSP) files to provide location-based capabilities to users.
This section provides detailed information about the Oracle-supplied tags that you can use. Each reference section includes an example.
Table 15-1 groups the JSP tags for location services by the type of application for which the tag is useful, and briefly describes the information specified by the tag.
Table 15-1 JSP Tags for Location Services
| Category | Tags |
|---|---|
|
General |
|
|
Geocoding |
|
|
Mapping |
|
|
Routing |
|
|
Business directory (YP) |
iterateCategoriesMatchingKeyword |
|
Sorting |
|
|
Location marks |
|
|
Mobile positioning |
|
|
Communities |
|
Many pairs of tags have similar names, with one starting with iterate and the other starting with list (for example, iterateManeuvers and listManeuvers).
Tags with names starting with iterate create a collection and present each item in the collection individually, so that you can perform some processing action. For example, on a Web page you might want display a horizontal rule after each item, and perhaps some static text before each item.
Tags with names starting with list present an unformatted list of returned items. These tags are useful for passing a single list of data for processing by a script or algorithm; they are not typically used for directly displaying data on Web pages.
The JSP tags for location services must be used with a prefix, which must be specified in the JSP file. The following example defines the loc prefix, which is used in other examples of specific tags:
<%@ taglib uri="LocationTags" prefix="loc" %>
The following example shows the loc prefix used with the address tag:
<loc:address name="hq" type="oracle.panama.model.Location"
businessName="Oracle Headquarters" firstLine="500 Oracle Parkway"
city="Redwood City" state="CA" postalCode="94065" country="US"/>
Section 15.2.1.1 provides comprehensive JSP examples for location services. It is followed by sections (in alphabetical order by tag name) that provide reference information for all the parameters available for each tag: the parameter name, a description, and whether or not the parameter is required If a parameter is required, it must be included with the tag. If a parameter is not required and you omit it, the interpretation is performed by the service provider. Each tag reference section also includes a short example.
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.
Example 15-4 Mapping Using JSP Tags
<%@ 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 + "&";
else if (orig.charAt(i) == '<') result = result + "<";
else if (orig.charAt(i) == '>') result = result + ">";
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>
Example 15-5 displays the route between two locations and the driving directions (maneuvers).
Example 15-5 Routing Using JSP Tags
<%@ 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 + "&";
else if (orig.charAt(i) == '<') result = result + "<";
else if (orig.charAt(i) == '>') result = result + ">";
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>
Example 15-6 displays business directory (YP) information by name within a specified distance of a location: specifically, a map with the ten Starbucks locations nearest to Oracle headquarters.
Example 15-6 Business Directory (YP) by Name Using JSP Tags
<%@ 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 + "&";
else if (orig.charAt(i) == '<') result = result + "<";
else if (orig.charAt(i) == '>') result = result + ">";
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>
Example 15-7 displays business directory (YP) information by category within a specified area: specifically, a map with all automobile dealers (new cars) in San Francisco, California.
Example 15-7 Business Directory (YP) by Category Using JSP Tags
<%@ 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 + "&";
else if (orig.charAt(i) == '<') result = result + "<";
else if (orig.charAt(i) == '>') result = result + ">";
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>
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.)
Table 15-2 addMembers Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
userName |
Name of the Oracle Application Server Wireless user requesting the operation. The default is the current user. |
No |
|
communityID |
Name of variable associated with the community to which to add the members. Example: |
Yes |
|
communityMembers |
A space-delimited list of Oracle Application Server Wireless users to be added to the community. |
Yes |
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() %>
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.)
Table 15-3 address Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
businessName |
Descriptive name of the business or other entity at the address. Example: |
No |
|
firstLine |
Street address. |
No |
|
city |
City name. |
No |
|
state |
2-character state (US) or province (Canada) code. |
No |
|
postalCode |
Postal code. |
No |
|
country |
Country name. |
No |
|
provider |
Name of the first-choice provider for the request, if there is a preference. |
No |
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>
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.)
Table 15-4 businesses Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
businessName |
Descriptive name of the business or other entity at the address. Example: |
No |
|
categoryID |
Business services category variable name. Example: |
No |
|
keyword |
Any string to search for in the |
No |
|
city |
City name. |
No |
|
state |
2-character state (US) or province (Canada) code. |
No |
|
postalCode |
Postal code. |
No |
|
country |
Country name |
No |
|
centerID |
A point variable name (such as for an address) to be used as the center point from which to start searching. If you specify |
No |
|
radius |
Length (in meters) of the radius of the circle in which to search. If you specify |
No |
|
nearestN |
Maximum number of nearest results that satisfy the query requirements (for example, to find the 3 nearest banks to a hotel or the user's current position). If you specify |
No |
|
provider |
Name of the first-choice provider for the request, if there is a preference. |
No |
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>
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.)
Table 15-5 category Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
parentCategory |
Name of the object containing the specification of the parent category (created previously using the |
No |
|
categoryName |
Name of the category. Example: |
Yes |
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" />
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.)
Table 15-6 createPrivateCommunity Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
userName |
Name of the Oracle Application Server Wireless user to be the owner of the community. The default is the current user. |
No |
|
communityName |
Descriptive name of the community. Example: |
Yes |
|
communityMembers |
A space-delimited list of Oracle Application Server Wireless users to be included in the community, if they are not already included. |
No |
|
returnNullIfExists |
|
No |
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() %>
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.)
Table 15-7 createSharedCommunity Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
userName |
Name of the OracleAS Wireless user to be the owner of the community. The default is the current user. |
No |
|
communityName |
Descriptive name of the community. Example: |
Yes |
|
communityMembers |
A space-delimited list of Oracle Application Server Wireless users to be included in the community, if they are not already included. |
No |
|
returnNullIfExists |
|
No |
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() %>
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.)
Table 15-8 createSystemCommunity Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
userName |
Name of the Oracle Application Server Wireless user to be the owner of the community. The default is the current user. |
No |
|
communityName |
Descriptive name of the community. Example: |
Yes |
|
communityMembers |
A space-delimited list of Oracle Application Server Wireless users to be included in the community, if they are not already included. |
No |
|
returnNullIfExists |
|
No |
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() %>
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.)
Table 15-9 defaultLocationMark Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
userName |
Name of the Oracle Application Server Wireless user for which to find the default location mark. The default is the current user. |
No |
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() %>
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.)
Table 15-10 deleteCommunity Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
userName |
Name of the Oracle Application Server Wireless user requesting the operation. The default is the current user. |
No |
|
communityName |
Descriptive name of the community (not a variable name). Example: |
Yes |
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() %>
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.)
Table 15-11 drivingDistance Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
route |
Name of the route. Example: |
No |
|
maneuver |
Name of the maneuver. |
No |
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() %>
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.)
Table 15-12 drivingTime Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
route |
Name of the route. Example: |
Yes |
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() %>
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.)
Table 15-13 geocode Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
businessName |
Descriptive name of the business or other entity at the address. Example: |
No |
|
houseNumber |
Number of the address on the street. |
No |
|
streetName |
Name of the street. |
Yes |
|
secondLine |
Second line of street address. |
No |
|
intersection |
Name of the intersecting street, if |
No |
|
city |
City name. |
Yes |
|
state |
2-character state (US) or province (Canada) code. |
Yes |
|
postalCode |
Postal code (main part). Example: |
Yes |
|
postalCodeExt |
Extension of the postal code, such as 4 additional numbers. |
No |
|
country |
Country name or code. |
Yes |
|
makeCorrections |
|
Yes |
|
provider |
Name of the first-choice service provider for the request, if there is a preference. |
No |
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" />
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.
Table 15-14 geometry Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
points |
Name of the variable for the points that make up the geometry. |
No |
|
route |
Name of the variable for the route that makes up the geometry. If you specify this parameter, the |
No |
|
maneuver |
Name of the variable for the maneuver that makes up the geometry. |
No |
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() %>
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.)
Table 15-15 getCommunity Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
userName |
Name of the Oracle Application Server Wireless user requesting the operation.The default is the current user. |
No |
|
communityName |
Descriptive name of the community (not a variable name). Example: |
Yes |
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() %>
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.)
Table 15-16 iterateBusinesses Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
collection |
Name for the returned collection. Example: |
Yes |
|
provider |
Name of the first-choice provider for the request, if there is a preference. |
No |
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>
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.)
Table 15-17 iterateBusinessesInCity Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
businessName |
Descriptive name of the business. Example: |
No |
|
categoryID |
Name of the variable associated with the category, if a category is involved in the query. |
No |
|
keyword |
The keyword, if a keyword is involved in the query. |
No |
|
city |
City name. |
Yes |
|
state |
2-character state (US) or province (Canada) code. |
Yes |
|
country |
Country name. |
Yes |
|
provider |
Name of the first-choice provider for the request, if there is a preference. |
No |
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>
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.)
Table 15-18 iterateBusinessesInCorridor Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
businessName |
Descriptive name of the business. Example: |
No |
|
categoryID |
Name of the variable associated with the category, if a category is involved in the query. |
No |
|
keyword |
The keyword, if a keyword is involved in the query. |
No |
|
corridorID |
Name of the variable associated with the corridor. |
Yes |
|
radiusInMeters |
Radius in meters around each point in the corridor. |
Yes |
|
provider |
Name of the first-choice provider for the request, if there is a preference. |
No |
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>
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.)
Table 15-19 iterateBusinessesInPostalCode Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
businessName |
Descriptive name of the business. Example: |
No |
|
categoryID |
Name of the variable associated with the category, if a category is involved in the query. |
No |
|
keyword |
The keyword, if a keyword is involved in the query. |
No |
|
postalCode |
Postal code. |
Yes |
|
country |
Country name. |
Yes |
|
provider |
Name of the first-choice provider for the request, if there is a preference. |
No |
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>
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.)
Table 15-20 iterateBusinessesInRadius Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
businessName |
Descriptive name of the business. Example: |
No |
|
categoryID |
Name of the variable associated with the category, if a category is involved in the query. |
No |
|
keyword |
The keyword, if a keyword is involved in the query. |
No |
|
centerID |
Name of the variable associated with the center point for the query. |
Yes |
|
radiusInMeters |
Number of meters of the radius for the circle around |
Yes |
|
provider |
Name of the first-choice provider for the request, if there is a preference. |
No |
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>
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.)
Table 15-21 iterateBusinessesInState Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
businessName |
Descriptive name of the business. Example: |
No |
|
categoryID |
Name of the variable associated with the category, if a category is involved in the query. |
No |
|
keyword |
The keyword, if a keyword is involved in the query. |
No |
|
state |
2-character state (US) or province (Canada) code. |
Yes |
|
country |
Country name. |
Yes |
|
provider |
Name of the first-choice provider for the request, if there is a preference. |
No |
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>
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.)
Table 15-22 iterateBusinessesNearestTo Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
businessName |
Descriptive name of the business. Example: |
No |
|
categoryID |
Name of the variable associated with the category, if a category is involved in the query. |
No |
|
keyword |
The keyword, if a keyword is involved in the query. |
No |
|
centerID |
Name of the variable associated with the center point for the query. |
Yes |
|
n |
Number of nearest businesses around |
Yes |
|
provider |
Name of the first-choice provider for the request, if there is a preference. |
No |
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>
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.)
Table 15-23 iterateByDistance Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
collection |
Name of the variable associated with the collection of points to be sorted by distance. |
Yes |
|
centerID |
A point variable name (such as for an address) to be used as the center point from which distances are to be computed. |
Yes |
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>
The iterateByDrivingDistance tag presents individually the points in a collection, sorted by driving distance from a specified point, as determined by the routing provider.
|
Note: The sorting by driving distance is performed by the routing provider. Therefore, this tag can be used only with providers that support sorting by driving distance. |
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.)
Table 15-24 iterateByDrivingDistance Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
collection |
Name of the variable associated with the collection of points to be sorted by driving distance. |
Yes |
|
centerID |
A point variable name (such as for an address) to be used as the center point from which driving distances are to be computed. |
Yes |
|
provider |
Name of the first-choice provider for the request, if there is a preference. |
No |
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>
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.)
Table 15-25 iterateByName Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
collection |
Name of the variable associated with the collection of points to be sorted by name. |
Yes |
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>
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.)
Table 15-26 iterateByRegionName Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
collection |
Name of the variable associated with the collection of points to be sorted by name. |
Yes |
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>
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.)
Table 15-27 iterateCategoriesMatchingKeyword Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
parentCategory |
Name of the object containing the specification of the parent category (created previously using the |
No |
|
keyword |
Word or phrase to be searched for in the parent category name, or in all category names if |
Yes |
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>
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.)
Table 15-28 iterateChildCategories Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
parentCategory |
Name of the object containing the specification of the parent category (created previously using the |
No |
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>
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.)
Table 15-29 iterateGeocodes Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
businessName |
Descriptive name of the business or other entity at the address. Example: |
No |
|
houseNumber |
Number of the address on the street. |
No |
|
streetName |
Name of the street. |
Yes |
|
secondLine |
Second line of street address. |
No |
|
intersection |
Name of the intersecting street, if |
No |
|
city |
City name. |
Yes |
|
state |
2-character state (US) or province (Canada) code. |
Yes |
|
postalCode |
Postal code (main part). Example: |
Yes |
|
postalCodeExt |
Extension of the postal code, such as 4 additional numbers. |
No |
|
country |
Country name or code. |
Yes |
|
provider |
Name of the first-choice service provider for the request, if there is a preference. |
No |
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>
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.)
Table 15-30 iterateLocationMarks Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
userName |
Name of the Oracle Application Server Wireless user for which to present the location marks. The default is the current user. |
No |
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>
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.)
Table 15-31 iterateManeuvers Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
routeID |
Name of the route for which to present the driving maneuvers. |
Yes |
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>
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.)
Table 15-32 iterateReverseGeocodes Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
businessName |
Descriptive name of the business or other entity at the address. Example: |
No |
|
firstLine |
Street address. |
No |
|
city |
City name. |
No |
|
state |
2-character state (US) or province (Canada) code. |
No |
|
postalCode |
Postal code. |
No |
|
country |
Country name. |
No |
|
provider |
Name of the first-choice provider for the request, if there is a preference. |
No |
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>
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.)
Table 15-33 listAllMembers Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
communityID |
Name of the variable associated with the community whose members are to be listed. |
Yes |
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() %>
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.)
Table 15-34 listBusinessesInCity Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
businessName |
Descriptive name of the business. Example: |
No |
|
categoryID |
Name of the variable associated with the category, if a category is involved in the query. |
No |
|
keyword |
The keyword, if a keyword is involved in the query. |
No |
|
city |
City name. |
Yes |
|
state |
2-character state (US) or province (Canada) code. |
Yes |
|
country |
Country name. |
Yes |
|
provider |
Name of the first-choice provider for the request, if there is a preference. |
No |
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() %>
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.)
Table 15-35 listBusinessesInCorridor Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
businessName |
Descriptive name of the business or other entity at the address. Example: |
No |
|
categoryID |
Name of the variable associated with the category, if a category is involved in the query. |
No |
|
keyword |
The keyword, if a keyword is involved in the query. |
No |
|
corridorID |
Name of the variable associated with the corridor. |
Yes |
|
radiusInMeters |
Radius in meters around each point in the corridor. |
Yes |
|
provider |
Name of the first-choice provider for the request, if there is a preference. |
No |
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() %>
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.)
Table 15-36 listBusinessesInPostalCode Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
businessName |
Descriptive name of the business. Example: |
No |
|
categoryID |
Name of the variable associated with the category, if a category is involved in the query. |
No |
|
keyword |
The keyword, if a keyword is involved in the query. |
No |
|
postalCode |
Postal code. |
Yes |
|
country |
Country name. |
Yes |
|
provider |
Name of the first-choice provider for the request, if there is a preference. |
No |
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() %>
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.)
Table 15-37 listBusinessesInRadius Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
businessName |
Descriptive name of the business. Example: |
No |
|
categoryID |
Name of the variable associated with the category, if a category is involved in the query. |
No |
|
keyword |
The keyword, if a keyword is involved in the query. |
No |
|
centerID |
Name of the variable associated with the center point for the query. |
Yes |
|
radiusInMeters |
Number of meters of the radius for the circle around |
Yes |
|
provider |
Name of the first-choice provider for the request, if there is a preference. |
No |
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() %>
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.)
Table 15-38 listBusinessesInState Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
businessName |
Descriptive name of the business. Example: |
No |
|
categoryID |
Name of the variable associated with the category, if a category is involved in the query. |
No |
|
keyword |
The keyword, if a keyword is involved in the query. |
No |
|
state |
2-character state (US) or province (Canada) code. |
Yes |
|
country |
Country name. |
Yes |
|
provider |
Name of the first-choice provider for the request, if there is a preference. |
No |
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() %>
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.)
Table 15-39 listBusinessesNearestTo Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
businessName |
Descriptive name of the business. Example: |
No |
|
categoryID |
Name of the variable associated with the category, if a category is involved in the query. |
No |
|
keyword |
The keyword, if a keyword is involved in the query. |
No |
|
centerID |
Name of the variable associated with the center point for the query. |
Yes |
|
n |
Number of nearest businesses around |
Yes |
|
provider |
Name of the first-choice provider for the request, if there is a preference. |
No |
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() %>
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.)
Table 15-40 listByDistance Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
collection |
Name of the variable associated with the collection of points to be sorted by distance. |
Yes |
|
centerID |
A point variable name (such as for an address) to be used as the center point from which distances are to be computed. |
Yes |
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() %>
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.
|
Note: The sorting by driving distance is performed by the routing provider. Therefore, this tag can be used only with providers that support sorting by driving distance. |
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.)
Table 15-41 listByDrivingDistance Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
collection |
Name of the variable associated with the collection of points to be sorted by driving distance. |
Yes |
|
centerID |
A point variable name (such as for an address) to be used as the center point from which driving distances are to be computed. |
Yes |
|
provider |
Name of the first-choice provider for the request, if there is a preference. |
No |
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() %>
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.)
Table 15-42 listByName Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
collection |
Name of the variable associated with the collection of points to be sorted by name. |
Yes |
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() %>
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.)
Table 15-43 listByRegionName Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
collection |
Name of the variable associated with the collection of points to be sorted by name. |
Yes |
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() %>
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.)
Table 15-44 listCategoriesMatchingKeyword Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
parentCategory |
Name of the object containing the specification of the parent category (created previously using the |
No |
|
keyword |
Word or phrase to be searched for in the parent category name, or in all category names if |
Yes |
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() %>
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.)
Table 15-45 listChildCategories Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
parentCategory |
Name of the object containing the specification of the parent category (created previously using the |
No |
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() %>
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.)
Table 15-46 listCreatedCommunities Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
userName |
Name of the Oracle Application Server Wireless user requesting the operation. The default is the current user. |
Yes |
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() %>
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.)
Table 15-47 listCreatedPrivateCommunities Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
userName |
Name of the Oracle Application Server Wireless user requesting the operation.The default is the current user. |
Yes |
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() %>
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.)
Table 15-48 listCreatedSharedCommunities Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
userName |
Name of the Oracle Application Server Wireless user requesting the operation. The default is the current user. |
Yes |
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() %>
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.)
Table 15-49 listCreatedSystemCommunities Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
userName |
Name of the Oracle Application Server Wireless user requesting the operation. The default is the current user. |
Yes |
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() %>
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.)
Table 15-50 listGeocodes Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
businessName |
Descriptive name of the business or other entity at the address. Example: |
No |
|
houseNumber |
Number of the address on the street. |
No |
|
streetName |
Name of the street. |
Yes |
|
secondLine |
Second line of street address. |
No |
|
intersection |
Name of the intersecting street, if |
No |
|
city |
City name. |
Yes |
|
state |
2-character state (US) or province (Canada) code. |
Yes |
|
postalCode |
Postal code (main part). Example: |
Yes |
|
postalCodeExt |
Extension of the postal code, such as 4 additional numbers. |
No |
|
country |
Country name or code. |
Yes |
|
provider |
Name of the first-choice service provider for the request, if there is a preference. |
No |
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" />
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.)
Table 15-51 listLocationMarks Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
userName |
Name of the Oracle Application Server Wireless user for which to list the location marks. The default is the current user. |
No |
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() %>
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.)
Table 15-52 listManeuvers Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
businessName |
Descriptive name of the business or other entity at the address. Example: |
No |
|
firstLine |
Street address. |
No |
|
city |
City name. |
No |
|
state |
2-character state (US) or province (Canada) code. |
No |
|
postalCode |
Postal code. |
No |
|
country |
Country name. |
No |
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() %>
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.)
Table 15-53 listReverseGeocodes Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
businessName |
Descriptive name of the business or other entity at the address. Example: |
No |
|
firstLine |
Street address. |
No |
|
city |
City name. |
No |
|
state |
2-character state (US) or province (Canada) code. |
No |
|
postalCode |
Postal code. |
No |
|
country |
Country name. |
No |
|
provider |
Name of the first-choice provider for the request, if there is a preference. |
No |
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() %>
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.)
Table 15-54 map Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
points |
Name of a collection of points around which to create the map. |
No |
|
route |
Name of a route around which to create the map. |
No |
|
maneuver |
Name of a maneuver around which to create the map. |
No |
|
xres |
Width of the map in screen display units. |
Yes |
|
yres |
Height of the map in screen display units. |
Yes |
|
provider |
Name of the first-choice provider for the request, if there is a preference. |
No |
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>
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.)
Table 15-55 mobilePos Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
userName |
Name of the Oracle Application Server Wireless user for which to request positioning information. The default is the current user. |
No |
|
requestingUser |
Name of the Oracle Application Server Wireless user for which to request positioning information. The default is the current user. If the requesting user is not authorized to retrieve positioning information about |
No |
|
failoverToDefaultLocationMark |
|
No |
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() %>
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.)
Table 15-56 point Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
lon |
Longitude value of the point (WGS 84 coordinate system). Example: |
Yes |
|
lat |
Latitude value of the point (WGS 84 coordinate system). Example: |
Yes |
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" />
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.)
Table 15-57 removeAllMembers Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
userName |
Name of the Oracle Application Server Wireless user requesting the operation. The default is the current user. |
No |
|
communityID |
Name of variable associated with the community from which to remove all members. Example: |
Yes |
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() %>
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.)
Table 15-58 removeMembers Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
userName |
Name of the Oracle Application Server Wireless user requesting the operation. The default is the current user. |
No |
|
communityID |
Name of variable associated with the community from which to remove the members. Example: |
Yes |
|
communityMembers |
A space-delimited list of Oracle Application Server Wireless users to be removed from the community. |
No |
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() %>
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.)
Table 15-59 route Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
xres |
Width of the displayed route in screen display units. |
Yes |
|
yres |
Height of the displayed route in screen display units. |
Yes |
|
requestGeom |
|
No |
|
requestMap |
|
No |
|
provider |
Name of the first-choice provider for the request, if there is a preference. |
No |
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>
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.)
Table 15-60 setCommunityName Tag Parameters
| Parameter Name | Description | Required |
|---|---|---|
|
name |
Name for the returned object. Example: |
Yes |
|
type |
Type of object. Must be: |
Yes |
|
userName |
Name of the Oracle Application Server Wireless user requesting the operation. The default is the current user. |
No |
|
communityID |
Name of variable associated with the community from which to remove all members. Example: |
Yes |
|
newName |
Descriptive new name to be assigned to the community. |
Yes |
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() %>
You can use the location Java API to write an application, such as in JSP files or servlets, if you need to have more precise control over the application behavior than is possible with JSP tags alone.
This section provides information on using the location Java API. It does not describe JSP concepts or how to write OracleAS Wireless XML applications, because these topics are covered in other chapters of this guide.
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.
Example 15-8 Constructing a SimpleForm Object
<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>
The next time the application is invoked (after the user has entered values into the fields), the application can access the data, as shown in Example 15-9.
Example 15-9 Accessing Address Data
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");
Geocoding can be done with a call, as shown in Example 15-10. (Another format of SpatialManager.createlocation, not shown in Example 15-10, specifies a point with longitude and latitude coordinates, in which case a Location object is created but no geocoding is done.)
Example 15-10 Geocoding the Address
Location address =
SpatialManager.createLocation(
businessName,
houseNumber,
new String[] { streetName },
null,
city,
state,
postalCode,
null,
country);
The resulting longitude and latitude values can be accessed, as shown in Example 15-11.
Example 15-11 Accessing Values of the Geocoded Address
address.getLongitude() address.getLatitude() address.getAddressLine1() address.getCity() address.getState()
Note that the getLongitude and getLatitude methods are inherited from the Point interface.
To better adapt to local address formats, you can use the international address formatting options provided in the oracle.panama.spatial.intladdress package. (For information about international address formats, see Section 15.1.5.1.4, "Address Format (International) Configuration".) The number of steps necessary to have a user input an address increases by one: the user first has to select a country (address format) in order to be presented with a form for entering the address. Because the form depends on the choice of country, the two separate steps cannot be merged to one.
Example 15-12 creates a drop-down SimpleFormSelect element that lets the user select an address format (US, German, French, and so on).
Example 15-12 Selecting an Address Format
<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>
The next step is to provide a form requesting all address components relevant to the given address format. The components are determined dynamically based on the specified country, as shown in Example 15-13.
Example 15-13 Requesting Address Components for a Specified Country
<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>
Example 15-14 displays the result. The components to display and the number of lines depend on the country.
Example 15-14 Displaying Addresses in a Country-Specific Format
<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>
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.)
You can create an adapter that provides routing information between a start address and an end address that the user enters. The adapter must:
Set the routing settings and options.
Compute the route.
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.
Example 15-16 Setting Routing Settings and Options
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");
Example 15-17 computes the route, returning a RoutingResult object.
Example 15-17 Computing the Route
RoutingResult rR =
SpatialManager.getRouter().computeRoute(
startLoc,
endLoc,
null, // via points
rS, // routing options
Locale.US);
Example 15-18 presents the resulting route to the user, displaying a list of maneuvers and maneuver maps, plus an overview map. (In this example, code specific to the routing API is shown in bold.)
Example 15-18 Presenting the Route to the User
<%!
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>
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.)
Example 15-19 Getting a Map Image URL:
String url =
SpatialManager.getMapper().getMapURL(
loc,
oracle.panama.imagex.ImageFormats.GIF,
800, // width
600, // height
false); // allow turning
In Example 15-19, the last parameter specifies whether or not the API can switch the width and height of the image to fit the map better to some mobile device screens. In this example, this option is disabled.
As alternatives to passing a single point object as the first parameter, as shown in Example 15-19, you can pass an array of Point objects or an object of type Location (address) or YPBusiness, which extend the Point interface.
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.
Example 15-20 Finding Categories Matching a Keyword
YPFinder ypF = SpatialManager.getYPFinder(); YPCategory cats[] = ypF.getCategoryAtRoot().getCategoriesMatchingName(keyword);
Example 15-21 shows a simple user interface that presents categories from which to choose. The user is presented a drop-down menu from which select the category that best matches what he or she is looking for.
Example 15-21 User Interface for Selecting a Category
<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>
When the application determines the fully qualified name of the chosen category, you can obtain the appropriate category, as shown in Example 15-22.
Example 15-22 Finding the Category
YPCategory cat = YPCategory.fromFullyQualifiedName(categoryNameString);
YPBusiness b[] =
SpatialManager.getYPFinder().getBusinessesInCity(
cat,
country,
state,
city,
Locale.US);
The conversion in Example 15-22 from a category object to a String object and back to a category object is required because a drop-down menu lets you make a selection among String objects, not among general objects.
To create an application based on the traffic services API, you must do the following:
Prepare input objects (such as CityInfo, RouteInfo, Point, and Location) for the query.
Get TrafficReporter and summit the query.
Obtain TrafficReport and process the information.
The rest of this section contains examples of typical operations. Example 15-23 performs a city-level query.
Example 15-23 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());
}
Example 15-24 performs a route-level query without specifying a direction, and returns incidents in both directions.
Example 15-24 Route-Level Query (Incidents in Both Directions)
RouteInfo r = new RouteInfo("US 3", null);
try{
report = reporter.getReportViaRoute(r,c);
}catch(LBSException e){
System.out.println(e.getLocalizedMessage());
}
Example 15-25 performs a route-level query for a specified direction (north).
Example 15-25 Route-Level Query Specifying Direction
try{
report = reporter.getReportViaRoute(r,TrafficReporter.North,c);
}catch(LBSException e){
System.out.println(e.getLocalizedMessage());
}
Example 15-26 performs a route-level query for an area 10 miles around a specified longitude/latitude point.
Example 15-26 Route-Level Query Around Longitude/Latitude Point
p = SpatialManager.createPoint(-71.0607, 42.3659);
try{
report = reporter.getReportViaLocation(p, 10, TrafficReporter.MILES,
c);
}catch(LBSException e){
System.out.println(e.getLocalizedMessage());
}
Example 15-27 performs a route-level query for an area 10 miles around a specified address.
Example 15-27 Route-Level Query Around Address
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());
}
Example 15-28 processes a traffic report to get useful information.
Example 15-28 Processing a Traffic Report
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();
}
}
Example 15-29 returns a list of cities for which traffic support is provided.
Example 15-29 Returning a List of Cities
TrafficCityManager manager = reporter.getCityManager();
CityInfo[] cities = null;
try{
cities = manager.getActiveCities();
}catch(LBSException e){
System.out.println(e.getLocalizedMessage());
}
Example 15-30 returns a list of routes for which traffic support is provided in a specified city (San Francisco, California).
Example 15-30 Returning a List of Routes in a City
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());
}
Oracle Application Server location services support the use of Web services with wireless applications that use the capabilities of the Geocoder, Mapper, Router, or YPFinder interfaces. Application developers do not need to add special coding if the application runs within OracleAS Wireless. Rather, Web services are integrated as service proxies for geocoding, mapping, routing, business directory (YP), and mobile positioning support.
If you develop external applications, whether written in Java or another language, you can access location-based Web services using the following kinds of files supplied with Wireless:
WSDL files (see Section 15.2.3.1, "WSDL Files")
XML files (see Section 15.2.3.2, "XML Files")
XSD files (see Section 15.2.3.3, "XSD 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
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
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
You can enable mobile positioning for individual users or groups of users of a location-based application. Mobile positioning of a user refers to associating a location with that user. When mobile positioning is enabled for a user, the user's current location, whether it is obtained dynamically from automatic positioning or from a default location mark, is used by OracleAS Wireless to determine the visibility of location-based services or folders. A service or folder can be defined as location-dependent (as described in Section 15.5.3) by associating it with a system region or a previously defined custom region. A location-dependent service or folder appears in a user's portal only when the user's current location (from automatic positioning or from a default location mark) is within the associated region. For example, if the user's current location is in Boston, a Boston traffic information service would be visible to the user; otherwise, the service would not be visible to that user.
Mobile positioning can be manual or automatic:
Manual positioning occurs when a specific location is assigned to a user. The assigned location could be the geocoded result of an address that the user is asked to enter, an explicitly specified location mark, or a default location for the user. For example, the location of the user's home might be specified for mobile positioning, and an application could then offer information and options relevant to that home area (regardless of the user's actual current physical location).
Automatic positioning (sometimes called location acquisition) occurs when the user's location is determined automatically based on positioning information based on the location of the mobile device. For example, the location of a delivery truck driver or service technician might be periodically determined based on the person's mobile device location, and an application could consider that location data when providing information or instructions to the user.
Automatic positioning provides several options relating to frequency of position updates and user privacy.
This section describes manual and automatic positioning in more detail, and describes how to enable each type of positioning.
Manual positioning associates a specific location with the application user. The location can be explicitly specified (such as the user entering an address or the name of a location mark), or it can be a default location mark for that user. A location mark is a position that is typically associated with longitude and latitude coordinates and that has a name. For example, an application user can create location marks named MyHome and MyOffice (for the person's home and office locations, respectively), and associate a geocoded address with each one. If this person designated MyHome as the default location mark, the application would consider the person's home address as the person's location.
If a user tries to set a default location mark that is not geocoded, a geocoding operation is performed before the location mark is made the default. If the geocoding operation fails, it is recommended that you not set that location mark as the default, because many capabilities (such as location-dependent service visibility) depend on the geocoded information of the default location mark.
For more information about location marks, see Section 15.1.7, "Location Marks".
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.
|
Note: If automatic positioning (described in Section 15.3.2) is turned off or if the positioning server is temporarily unavailable, manual positioning is used, and the user's default location mark is used. (Automatic positioning can be turned on and off using the OracleAS Wireless System Manager.) |
To enable manual positioning using the Personalization Portal interface, follow these steps:
Log in to the Personalization Portal Web interface
Click the LocationMarks tab.
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.)
Select the location mark that you want for your default location.
Click Set Default.
Automatic positioning allows the user's location to be determined based on a position based on the location of the user's mobile device. You can determine how timely, and thus potentially how accurate, the location is by setting a positioning quality of service (QoS) value.
The OracleAS Wireless API enables an application to access a mobile user's current location through the current session (see getCurrentLocation() in the oracle.panama.rt.Session interface). If automatic positioning is turned on in the system, the user's current physical location is returned from the mobile positioning system. If automatic positioning is turned off or if the positioning server is temporarily unavailable, the user's default location mark is returned.
Privacy and the security of privacy-related information are important concerns in a location acquisition system. OracleAS Wireless location services provide a privacy management component that allows users to view and edit their privacy settings, to enable and disable the positioning operation on themselves, and to authorize one or more people (a mobile community) to obtain positioning information on them within certain time frames. It also allows application developers to access these capabilities through a public API.
Automatic positioning is controlled by the mobile positioning framework, which is shown in Figure 15-4.
As Figure 15-4 shows:
Application developers can use the mobile positioning API together with the privacy API to provide services.
The mobile positioning API in the application communicates with the location cache (described in Section 15.3.2.2) and the location acquisition layer to determine the user's location. Whether or not the cache is used is affected by the positioning quality of service (QoS) value, which is described in Section 15.3.2.3.
The location acquisition layer passes the actual current position to the location cache and to the mobile positioning API.
Privacy management logic controls privacy-related aspects of the mobile positioning framework, which are described in later sections.
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.
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.
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.
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.
Example 15-31 Getting Position using System Default Providers and Default QoS
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();
Example 15-32 shows two examples of getting the user's position and specifying a positioning quality of service level. The first example specifies the quality descriptively as high, and the second example specifies the quality as a number of seconds. (Section 15.3.2.3 explains the ways in which you can specify positioning quality of service.)
Example 15-32 Getting Position Specifying QoS
PositionResult res = positioner.requestPosition("46708123456790", ServiceQoS.HIGH_QUAL);
PositionResult res = positioner.requestPosition("46708123456790", new ServiceQos(120));
Example 15-33 gets the user's position based on an array of specific providers.
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
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)
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.
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.)
Developers of applications can manage the privacy capabilities through the location services privacy API. This section describes the privacy API and provides examples.
The LocationPrivacyManager class handles all the location privacy-related operations, such as granting and revoking positioning rights, enabling and disabling positioning rights, setting and getting system privacy options, and checking if a user has right to position another user. The class also provides ways to retrieve the LocationPrivacyAuth object, which stores information about a privacy authorization item.
A user can grant authorization to another user or to a mobile community using grantAuthorization. The authorization can be temporarily disabled using disableAuthorization. The disabled authorization can be recovered by using enableAuthorization. The granted right can be permanently revoked using revokeAuthorization. checkAuthorization can be used to check whether a user has right to position another user at specific time.
All the privacy authorization operations are application-specific, which means that they only affects the application in which the operation is performed.
The CommunityManager class handles community-related operations, such as creating and deleting community and retrieving community information. Community operations specific to a single community are defined in the Community interface.
The LocationPrivacyAuth interface provides methods to retrieve information specific to a location authorization item, such as the authorization period, the service where the authorization occurs, the user granting the right, and the user receiving the right.
The Community interface provides methods to retrieve information about the community object, add members to and remove members from the community, and set community attributes.
The AuthPeriod class maintains a time range that is used when a user grants the positioning right to other users. An authorization period is composed of start date, end date, start time, end time, and exclusions. The class also provides a method contains to check whether a specific time falls in the time range represented by the class.
The LocationPrivacyException class is a subclass of PanamaException. It represents a location privacy-specific exception.
This section contains examples of the location services privacy API. The examples are taken from the sample adapters SampleCommunityManager.java and SampleFriendFinder.java is the iAS-wireless-home\sample\sampleadapter\mp\privacy directory. These two sample adapters demonstrate the major capabilities of the privacy API.
Example 15-34 lists all communities of a specified type that are visible to a user.
Example 15-34 List Communities of a Specified Type Visible to a User
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); }
Example 15-35 grants the positioning right to a user or a community based on user input.
Example 15-35 Grant Positioning Right to a User or Community
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); }
The location event server generates an event when a location-based condition occurs. The event could result in a location-based alert being delivered based on a mobile user's current location.
The wireless alert engine allows users to subscribe to a location-based alert service and specify location-based conditions. When a location-based condition is satisfied, the alert engine receives a location event. If all other conditions for delivering the alert are also satisfied, the alert engine sends an alert to the subscriber. The following are some typical scenarios in which location-based alerts can be provided for mobile users:
A traveler wants to receive an alert when the limousine that she will take is within 1 mile of the airport.
A member of a project team wants to receive an alert when all other team members are at corporate headquarters.
A field service coordinator wants to receive an alert when a new service request arrives and an engineer qualified to handle the request is within 2 miles of the service center.
A subscriber to a weather information service wants to receive an alert when the forecast predicts snow and his sister is not at home, because his sister travels frequently and has asked him to take care of her plants when she is out of town.
The potential scenarios reflect a range of complexity, for example, combining a location-related condition and conditions not directly related to location.
A location-based alert is an alert service that has a location-based condition.
A location-based condition is a set of location-based alert criteria plus related information, such as the condition expiration time and the condition evaluation mode. The condition is satisfied only when all criteria in the condition are satisfied.
Location-based alert criteria are components of a location-based condition. Each criterion has three elements: a target, a region, and a type. The target can be a user, a community, or a mobile device. The region is a system-defined or user-defined location. The type must be IN or OUT, indicating the position of the target in relation to the region. Examples of location-based alert criteria include the following:
All team members are in Chicago.
Mr. Smith is outside the state of New York.
A location event server is a standalone process that retrieves the location-related information from the positioning service provider, evaluates the location-based conditions, and generates an event if a condition is satisfied. The location event server cooperates with the mobile positioning and region modeling components to do scheduling: the condition evaluation result is periodically updated, and when a condition is satisfied, a location event is sent out to the client that generated the condition.
A location event client is a wireless application or system component that specifies location-based conditions and reports location-related information. Each location event client has a location event agent that handles two-way communication between the server and the client. The location event agent gets the location-based conditions created in the client instance and registers them to the server side. The agent receives location events from the server and invokes the location event handler to process the event. It also supports the pull query, a request for the evaluation result of a specified location condition.
A location event can be sent out to the client that generated the condition, or to one or more other clients, or any combination. When a condition is activated, the application can determine which recipients should receive a location event.
You can configure and use multiple location event servers and location event clients.
Java classes are provided for implementing a location event client:
Location-based condition (LBCondition class; see Section 15.4.3, "Location-Based Condition Object (LBCondition)")
Location event agent (LBEventAgent class; see Section 15.4.4, "Location Event Agent Object (LBEventAgent)")
Location event handler (LBEventHandler class; see Section 15.4.5, "Location Event Handler Object (LBEventHandler)")
Example 15-36 creates a location event agent and activates a location-based condition, so that a parent will be alerted when his or her child goes out of the region associated with the child's school. A different location event agent (named anotherAgent) will receive the event generated from the server when the condition is satisfied.
Example 15-36 Location Event Agent
try{
LBEventAgent alertAgent = factory.createLBEventAgent("alertAgent",true);
LBEventHandler handler = new ALBEventHandlerImpl();
alertAgent.registerLBEventHandler(handler);
User parent = factory.createUser(USERNAMEPARENT);
User child = factory.createUser(USERNAMECHILD);
LocationPrivacyDomain privacyDomain = new LocationPrivacyDomain();
LBCondition condition = factory.createLBCondition(LBCondition.MODE_ONCE, null,
parent, privacyDomain);
condition.addCriteria(String.valueOf(child.getId()),
LBCondition.TARGETTYPE_USER,LBCondition.TYPE_OUT,SCHOOL_REGION_ID);
alertAgent.activateCondition(condition,null,null,"anotherAgent",false);
}catch(LBEventException e){
......
}
A location-based condition (LBCondition) object represents a location-based condition. A typical alert condition consists of multiple criteria, each of which defines a target, a criterion type (IN or OUT), and a region (system region, custom region, or user-defined region). The relationship between the specified criteria is AND, which means that the condition is satisfied only when all the criteria are satisfied.
The LBCondition object also specifies a condition expiration time and a condition evaluation mode. The condition expiration time indicates when the condition becomes invalid. The condition evaluation mode must be one of the following:
Evaluate only once. After the condition is satisfied for the first time, the condition is not evaluated any more and the condition status becomes inactive.
Evaluate until the expiration time arrives. If the condition is satisfied, a location event is sent to the location event client. Regardless of whether the condition is satisfied or the number of times the condition is satisfied, the condition remains active until the expiration time. If the condition is satisfied, then not satisfied, and then satisfied again, a new event is sent to the user. (For example, if the condition is "user Smith is in Boston" and if Smith enters Boston, leaves Boston, and enters Boston again, an event is sent each time Smith enters Boston.)
A location event agent (LBEventAgent) object communicates with the location event server on behalf of a location event client. A location event agent object performs the following operations:
Activates location-based conditions.
Supports queries about whether a specific location-based condition is satisfied.
Allows the location event client to register a location event handler and to start threads to listen to the location events. When a location event arrives, the location event handler is invoked to process the event.
Deactivates location-based conditions from the server.
Each location event agent has a name and a messaging channel. When a location event client creates a location event agent, it can specify whether it allows other agents to share the same name with the new agent. Location event agents that have the same name share the same messaging channel, which means that location events sent to the messaging channel will be distributed among those location event agents.
When a location-based condition is activated, the condition information is sent to the location event server, and the server begins to evaluate the condition. If the evaluationMode parameter passed to the activateCondition method, its value overrides the evaluation mode defined in the LBCondition object. If the RecipientAgent parameter is passed to the activateCondition method, it specifies the name of the recipient agent, which means that a condition can be created in one agent and the event can be sent to another agent when the condition is satisfied.
The isSatisfied method in the location event agent checks if a specific condition is satisfied or not. If the condition is not active, the isSatisfied method initiates the condition evaluation, and this may take some time (from several seconds to several minutes, depending on how complicated the condition is). The checkStatusNoWait method also checks if a specific condition is satisfied or not, but is the condition is not active, condition evaluation is not activated.
The location event handler (LBEventHandler) object is a public interface. Application developers are expected to implement the handler interface and register it at the location event agent. The implementation should be thread safe. The location event handler is responsible for processing a location event.
After a location event agent receives a location event, it invokes the handleLocationEvent method of the location event handler that is registered with the agent. The handleLocationEvent method accepts a condition ID that uniquely identify a location-based condition, an event type that specifies whether the condition has been satisfied and whether there are any errors, and the time when the event was generated.
You can configure the location event server using the Wireless System Manager, as follows:
In the Wireless Server System tab page, click Site Administration.
Click to expand Component Configuration.
Under Location-Related, click Location Event Server.
The following location event server configuration options are available. The options that you choose affect the behavior and performance of the location event client applications.
Default validity period for no-wait pull request in seconds
The location event agent can use the checkStatusNoWait method to pull a result from a location event server without waiting. The validity period for no-wait pull request determines how old the pulled result can be and still be considered valid. If the result was generated within the validity period, the result is considered valid. If the pulled result is not valid, the no-wait pull request does not wait for the server to generate a new result. For example, if the validity period is 600 seconds (10 minutes) and if the most recent report of a user's position was 11 minutes ago, the positioning report is not considered valid, and the checkStatusNoWait method returns without waiting.
The longer the validity period, the more likely a positioning report is to be considered valid. However, if the application requires recent positioning information, a short validity period might be needed.
Default validity period for pull request in seconds
The location event agent can use the isSatisfied method to pull a result from a location event server. The validity period for pull request decides whether the pulled result is valid. If the result was generated within the validity period, the result is considered valid. If the pulled result is not valid, the pull request will wait till a new result is generated by the server. For example, if the validity period is 600 seconds (10 minutes) and if the most recent report of a user's position was 11 minutes ago, the positioning report is not considered valid, and the isSatisfied method waits until the next report of the user's position is received.
The longer the validity period, the more likely a positioning report is to be considered valid, and the more likely it is that the isSatisfied method will accept the positioning information and return, so that the application can continue. However, if the application requires recent positioning information, a short validity period might be needed, although it may risk delaying the application while the isSatisfied method waits for new information.
Default number of location event listeners
A location event agent can have multiple listeners listening for location-based events. This setting specifies how many listeners a location event agent has.
The value should be based on the system workload. If many location based-conditions are created and processed, a number greater than 1 (such as 5 or 10), is probably better. However, if few location based-conditions are created and processed, one location event listener is sufficient. An application can override this default.
For each location event server, you can specify the following:
Number of Positioning Schedulers
Each location event server can have one or more positioning schedulers that process the location-based conditions. This setting specifies the number of positioning schedulers for each location event server.
The value should be based on the system workload. If many location based-conditions are created and processed, a number greater than 1 (such as 5 or 10), is probably better. However, if few location based-conditions are created and processed, one positioning scheduler is sufficient. System administrators can monitor the performance of the location event server and adjust the value accordingly.
The region modeling tool lets administrators of a wireless portal service manage regions and make a service or folder location-dependent. When you create a service or a folder, you can specify that it is location-dependent by associating a system region or a previously created custom region with the service or folder. A location-dependent service or folder appears is a user's portal only when the user's current location (either from automatic mobile positioning or from the user's default location mark) is within the specified region.
A region is simply a geographic entity, or location. A region can be small (such as a street address) or large (such as a country). A region can be represented by a point, as is often done for addresses and locations of interest (such as airports and museums), or by a polygon, as is usually done for states and countries.
You may want to define specific regions for a variety of applications and services, such as:
City guides for selected metropolitan areas, so that users in those areas receive only services and information (such as restaurant listings or advertisements) relevant to them
Colleges that have a certain ranking or that specialize in certain subject areas, so that prospective students and their parents can receive information about those locations
Art museums in a city or a multistate area, so that art lovers can plan trips to museums
Your company may provide many specialized services, and users may be able to subscribe to and pay for individual services tied to regions. For example, one user might subscribe to city guides for the entire United States, while another user might subscribe only to city guides for southeastern states.
To implement the city guide example, you could do the following:
Create a folder (static, not location dependent) called City_guide.
Under the City_guide folder create city guide services for Boston, San Francisco, and California
Set the default location mark to an address in a city. If the address is in Boston, the user sees the Boston city guide; if the address is in San Francisco, the user sees both the San Francisco and California guides.
In another example scenario, several services may be relevant to a region, in which case you can create a location-dependent folder and place the relevant services in that folder (instead of designating each service as location-dependent on the region). For example, assume that you have ATM Locator, Flight Gate Information, Airport Parking Information, and Taxi Finder services associated with a region named Airport, and that you have Printer Finder, Conference Room Scheduler, and Cafeteria Menu services associated with a region named Office. In this case, you can create two location-dependent folders named Airport and Office, and associate them with the Airport and Office regions, respectively.
Regions are stored in folders. Folders can be in a hierarchy (that is, there can be folders in folders). There are two top-level folders: System-Defined Regions and Custom Regions.
System-defined regions are arranged in a hierarchy of predefined areas: continents, which contain countries. The United States further contains states, which contain postal codes, counties, and cities.
Custom regions are regions created by users, based on entering an address or on selecting one or more other regions (system-defined or custom).
When you specify an application to be location-dependent, you must specify the region for which the service applies or is relevant. Before you can specify the region, it must already exist, either as a system-defined region or a custom region. If it is a custom region, it must have been created using the region modeling tool.
Follow these steps to specify that an application is location-dependent and to use the region modeling tool.
In the Wireless Server Services tab page, click the Applications tab (if it is not already selected).
Select a location-dependent application (or one to be made location-dependent), and click Edit.
Click Additional Info.
Enable (check) Location-Dependent.
To start the region modeling tool, click the flashlight icon next to the Region Name box.
The region modeling tool is displayed, as shown in Figure 15-5.
Figure 15-5 Region Modeling Tool Interface
The Web browser window initially displays the top level of the region hierarchy, with two entries: system-defined regions and custom regions. You can find regions, and you can select regions for viewing or for adding to a collection from which you create a custom region.
To find a region in a display of system or custom regions, enter a character string that is in its name to search by name, or enter a number to search by ID (by region ID). Specify to search all regions or only under current region (the currently selected region), then click Go.
To select a region to perform an operation on it, click the box to the left of its icon and name. (To deselect a selected item, click the box.) You can select all regions in the current display by clicking Select All, and deselect all regions in the current display by clicking Select None.
To perform an operation on the selected region or regions, click the command text link or button shown in Table 15-61.
Table 15-61 Region Modeling Tool Operations
| To Do This: | Click This: |
|---|---|
|
Add selected regions to the collection of regions at the bottom of the display |
Add to Collection |
|
View a map display showing selected regions |
View |
|
Create a custom region from the collection of regions at the bottom of the display |
Create from Collection. A series of pages is then displayed, in which you specify the location in the region hierarchy and the name for the custom region. |
|
Create a custom region from a street address that you enter |
Create from Address. A series of pages is then displayed, in which you specify the address, the location in the region hierarchy, and the name for the custom region. |
|
Create a custom region from the collection of regions at the bottom of the display |
Create from Collection. A series of pages is then displayed, in which you specify a location in the region hierarchy and a name for the custom region. |
|
Create a folder in which to organize regions |
Create Folder. A series of pages is then displayed, in which you specify the location in the region hierarchy under which to create the folder and the name for the folder. |
|
Go to the previous or next set of entries in the display of regions or the current collection |
Previous or Next |
|
Go up one or more levels in the region hierarchy |
The name of the desired level on the current hierarchy line near the top of the page. Example of how this line might look (with all items except the last as links): Regions > System Defined Regions > NORTH AMERICA > USA > California |
|
Get help about any screen |
Help |
The region modeling tool is installed with an extensive set of data for the United States, as well as country data for many countries. However, you can add data about other countries, states, cities, and so on by adding rows to the tables where the region data is stored. For example, you could add a row for each state in India to the STATE table. If you are careful and know what you are doing, you can also modify certain data in those tables, such as editing the DESCRIPTION column values for certain cities or states.
Region data is stored in the OracleAS Wireless repository in the tables listed in Table 15-62.
Table 15-62 Tables for Region Data
| Table Name | Contains Information About |
|---|---|
|
CONTINENT |
Continents |
|
COUNTRY |
Countries |
|
STATE |
States |
|
COUNTY |
Counties |
|
CITY |
Cities |
|
POSTALCODE |
Postal codes |
|
USERDEFINED |
Custom regions |
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.
Example 15-37 Region Data Table Definitions
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
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.
Example 15-38 Inserting a City
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; /
The minimum and maximum longitude and latitude values in the CITY table are required and are used by traffic support services. The minimum longitude and latitude values identify the lower-left corner, and the maximum longitude and latitude values identify the upper-right corner, of the bounding rectangle.
The region modeling tool is based on the region modeling API, which is implemented through the RegionModel interface of the oracle.panama.spatial.region package. The RegionModel interface includes methods for getting the postal code, state, and country, and for determining different kinds of interaction among regions.
OracleAS Wireless supports access to a number of location-related services, such as geocoding, driving directions, business directory (Yellow Pages) services, and mapping. It does not perform many of the services itself, but relies on external providers. This section describes the features that you, the provider, can implement and the interface options for communicating with OracleAS Wireless.
External providers can integrate their products with OracleAS Wireless by creating a custom service proxy for each type of location-based service that you provide. A service proxy is a Java class implementing a common interface; and for each service (geocoding, mapping, routing, traffic, yellow pages), there is one interface. A service proxy is executed on the same system as OracleAS Wireless, rather than on your server.Service Proxies
The service proxy must translate between the interface for your server and the interface specified by Oracle location services. It must also extend an Oracle-supplied class to provide the necessary internal infrastructure.
Depending on the type of service (geocoding, mapping, and so on), you must implement the appropriate interface from the following list:
oracle.panama.spatial.geocoder.Geocoder oracle.panama.spatial.mapper.Mapper oracle.panama.spatial.router.Router oracle.panama.spatial.traffic.TrafficReporter oracle.panama.spatial.yp.YPFinderSimple
Within the interface, there are functions that you must implement, may implement, and must not implement, as explained in Section 15.6.2.
Depending on the type of service (geocoding, mapping, and so on), you must extend the appropriate interface from the following list:
oracle.panama.spatial.core.geocoder.GeocoderImplXMLImpersonator oracle.panama.spatial.core.mapper.MapperImplXMLImpersonator oracle.panama.spatial.core.router.RouterImplXMLImpersonator oracle.panama.spatial.core.traffic.TrafficReporterImplXMLImpersonator oracle.panama.spatial.core.yp.YPFinderSimpleImplXMLImpersonator
For example, if you implement the oracle.panama.spatial.geocoder.Geocoder interface, you must also extend the following interface:
oracle.panama.spatial.core.geocoder.GeocoderImplXMLImpersonator
The service proxies are located on the OracleAS Wireless server, which might be behind a firewall. Content providers, on the other hand, are usually outside the firewall. In this case, the proxy must use the OracleAS Wireless firewall proxy setup (which is different from the location service proxy setup). The following example is an excerpt that shows how to set the firewall proxy, with the important lines in bold type:
URL u = …
try
{
URLConnection c = u.openConnection();
ProxyFirewall.setProxyAuthorization(c);
c.connect();
BufferedReader
bReader = new BufferedReader(
new InputStreamReader(
c.getInputStream()));
...
}
catch(...) { ... }
...
The available functions for a service proxy are in three categories:
Must be implemented: functions that must be implemented as essential parts of each proxy
May be implemented: functions that are optional, but that you can implement (for example, to provide features that distinguish your product from those of competitors)
Must not be implemented: functions that are already implemented by the framework and must not be implemented by the proxy
The Javadoc documentation for each interface explains each available function.
This section lists the functions in each category for each type of service (geocoding, mapping, and so on), with the class name in bold. However, for some types of services, no functions are in the "may be implemented" category.
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);
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);
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);
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;
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);
This section describes how to implement the service proxy for integrating an external mobile positioning provider into OracleAS Wireless. Before you integrate a mobile positioning provider, be sure that you understand the following:
Mobile positioning concepts and options, as explained in Section 15.3
External provider concepts in Section 15.6
Mobile positioning includes the following steps:
Check the location privacy settings to determine if the positioning request is authorized.
Get the user's mobile station ID through the provider selector hook (described in Section 15.3.2.4). The system default is to use the Mobile Station ID field in the user profile.
Check the location cache. If location caching is enabled and the request can be satisfied from the cache, return the location found in the cache, and skip step 4.
If the location not satisfied from the cache, invoke one or more mobile positioning proxies to acquire the user's current location.
Step 4 in the preceding list (invoking one or more mobile positioning providers) involves the following specific actions:
Examine the information about mobile positioning providers in the system configuration file. This information includes the following: provider name, proxy implementation class name, version number, mobile positioning server URL, mobile positioning user name and password, and any additional parameters.
Instantiate the proxy class.
Invoke the requestPosition() method in the class to acquire the location of a mobile station.
To integrate a mobile positioning provider, you must implement the oracle.panama.mp.Positioner interface.
The constuctor of the class must have the following format:
public MyMPImpl (String providerName,
String providerImpl,
String version,
String url,
String username,
String password,
String parameters);
The mobile positioning framework reads this information from the system configuration and uses it to construct your proxy implementation. The class stores the information in class variables for later use.
In addition to the constructor, the class must implement the following methods:
public PositionResult requestPosition ( String msid); public PositionResult requestPosition ( String msid, PositionQoS qos); public PositionResult[] requestPosition ( String[] msids); public PositionResult[] requestPosition ( String[] msids, PositionQoS qos);
The first method takes a mobile station ID as the parameter.
The second method takes a mobile station ID and a quality of position (PositionQoS) parameter. The PositionQoS parameter specifies the maximum acceptable age of the mobile station's location that can served out of the cache. For example, an application may be willing to accept a user's location that is as much as 5 minutes old. In your proxy implementation, you do not need to check with the Oracle Application Server Wireless location cache to determine if the location already exists, because that logic is implemented in the mobile positioning framework. In other words, if a location exists in the system cache and satisfies the request, the proxy will not be invoked. The proxy needs to consider the PositionQoS parameter only if the actual mobile positioning provider has a similar caching concept and can use this parameter.
The third and fourth methods are similar to the first and second methods, respectively, but they are used to request the locations of multiple mobile stations. If the actual mobile positioning provider can handle bulk requests, the proxy should take advantage of this capability and be able to request multiple locations in a single call (for example, using a FOR loop). If the provider cannot handle multiple requests, the proxy must call the provider multiple times, once for each location.
Each method returns a PositionResult object or an array of these objects. The PositionResult object represents the current location of a mobile station. For more information about the PositionResult object, see the Javadoc documentation for the oracle.panama.mp.PositionResult and oracle.panama.mp.PositionArea classes.
The following guidelines apply to using the PositionResult object:
If the mobile positioning provider does not return one or more values in the object, set these values to be null.
The PositionResult object includes an array of PositionArea objects. If the mobile positioning provider returns only one PositionArea object, you still must still include that single object in an array.
Your implementation of the oracle.panama.mp.Positioner interface must also handles exceptions and error, as explained in Section 15.7.2.
This section describes guidelines for handling runtime mobile positioning errors and exceptions, which can occur in any of the following ways:
The provider's response includes an error code and error message.
An exception is thrown during parsing.
If the request is for positioning multiple mobile stations (using the third and fourth requestPosition methods described in Section 15.7.1), the number of returned results and the number of subscriber IDs do not match.
For any errors or exceptions from a request for a single subscriber ID or multiple subscriber IDs, check the error code and error message from the provider:
If the error is a severe error, return null immediately to fail over. Severe errors include authentication errors, errors during XML parsing, and other errors that are not caused by the proxy implementation and that cannot be resolved by re-sending the request.
If the error refers to unknown subscriber ID, construct and return a PositionResult object with the error ID UNKNOWNSUBSCRIBER and the error message UNKNOWNSUBSCRIBER_STR. You can later retrieve the error message by using the getErrorMessage() method on the PositionResult object.
For other error codes, construct and return a PositionResult object with the error ID and error message from the provider.
