Oracle Application Server Wireless Developer's Guide 10g (9.0.4) Part Number B10948-01 |
|
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 mobile 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:
To get started using the OracleAS Wireless location application components, follow these steps:
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.
iAS-Wireless-Home/wireless/doc/index.html
where ias-Wireless-Home is your OracleAS Wireless home directory.
Figure 14-1 shows part of the index.html
display. Navigate to find detailed information about packages and classes.
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.
Figure 14-2 shows the System Manager page with the Component Configuration section expanded.
As shown in Figure 14-2, the Location-Related section in the Component Configuration section contains the following links:
Location services are based on the architecture shown in Figure 14-3.
As shown in Figure 14-3:
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:
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 14.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:
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 14-4 in Section 14.1.5.1), select the appropriate type of service for configuration:
The provider information (described in Section 14.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 14.1.5.1.3, "Country Name Alias Configuration") and address formats (see Section 14.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 14.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 14.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:
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:
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:
For programming information and examples relating to international address formats, see Section 14.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 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:
The performance information is written to a table named PTG_LBS_LOG
. You can see this information using the Wireless System Manager, as follows:
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:
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.
The Geocoder
interface defines how an application programmer accesses the geocoding service. An object of a class implementing this interface is returned by the SpatialManager
.
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 14.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 14.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.
Table 14-1lists the columns in the LOCATIONMARK table.
The mapping API provides functions for creating map images for any of the following:
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 14.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:
Secondary options include:
Secondary options can be mandatory or preferred:
If the application developer requests a secondary option without specifying whether it is mandatory or preferred, the following defaults are applied:
The application can query the following components of a returned route:
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:
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 14.1.10.2.
The Maneuver
class defines a single maneuver in a route (see Section 14.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 14-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 14.1.11.1.
<?xml version="1.0" standalone="yes"?> <Categories> ... <Category CategoryName = "Berry crops"> <Provider Name = "..." Parameter = "..."/> <Category CategoryName = "Cranberry farm"> <Provider Name = "..." Parameter = "..."/> </Category> </Category> ... <Category CategoryName = "Ornamental nursery products"> <Provider Name = "..." Parameter = "..."/> <Category CategoryName = "Florists' greens and flowers"> <Provider Name = "..." Parameter = "..."/> </Category> <Category CategoryName = "Bulbs and seeds"> <Provider Name = "..." Parameter = "..."/> </Category> </Category> <Category CategoryName = "Crops grown under cover"> <Provider Name = "..." Parameter = "..."/> <Category CategoryName = "Mushrooms grown under cover"> <Provider Name = "..." Parameter = "..."/> </Category> </Category> ... </Categories>
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:
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:
In each of these region types, businesses can be found:
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:
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:
Examples of traffic queries include returning the traffic report for:
The traffic API processes requests and returns responses. The requests and responses can be in Java or XML format. Section 14.1.12.2 provides examples of an XML request and response in XML format. Section 14.1.12.3 describes the traffic Java API.
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:
Example 14-2 shows a city-level request in XML format for traffic information for Boston.
<?xml version="1.0" encoding="UTF-8"?> <traffic_request> <query_list> <query_info query_type="city_level_query" city_name="boston" state_name="MA" country_name="US" /> </query_list> </traffic_request>
Example 14-3 shows a response in XML format for traffic information 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:
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:
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:
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;
You can develop a location-based application by using any of the following approaches:
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 JavaServer 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 14-2 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.
Category | Tags |
---|---|
General |
|
Geocoding |
|
Mapping |
|
Routing |
|
Business directory (YP) |
|
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).
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 14.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 14-4 displays small and large maps of two locations.
<%@ taglib uri="LocationTags" prefix="loc" %> <%! public String transformString(String orig) { String result = ""; for (int i=0;i<orig.length();i++) { if (orig.charAt(i) == '&') result = result + "&"; 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 14-5 displays the route between two locations and the driving directions (maneuvers).
<%@ 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 14-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.
<%@ 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 14-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.
<%@ 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 14.3.2.6, "Mobile Communities".
Table 14-4 lists the addMembers
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example adds the user named Song
, at the request of the user named Mike
, to the mobile community associated with the variable named comm_private
. It also creates a java.util.Enumeration
object of members of this community, and displays this object.
<loc:addMembers name="add_members" type="Boolean" userName="Mike" communityID="comm_private" communityMembers="Song" /> <loc:listAllMembers name="list_all_mem1" type="java.util.Enumeration" communityID="comm_private" /> <%= list_all_mem1.toString() %>
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 14-4 lists the address tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates a route named myRoute
between two addresses (a person's office and home), displays a map of the route followed by a horizontal rule, and presents each driving maneuver (using the iterateManeuvers
tag and the getMap
and getNarrative
function calls) followed by a horizontal rule. Each driving maneuver description is also a link that users can click to display a map of the maneuver.
<loc:route name="myRoute" type="oracle.panama.spatial.jsptags.beans.Route" xres="800" yres="600"> <loc:address name="office" type="oracle.panama.model.Location" businessName="My office" firstLine="1 Oracle Dr" city="Nashua" state="NH" postalCode="03062" country="US"/> <loc:address name="home" type="oracle.panama.model.Location" businessName="My home" firstLine="2 Royal Crest Dr" city="Nashua" state="NH" postalCode="03060" country="US"/> </loc:route> <img src="<%= myRoute.getMap() %>"> <HR> <loc:iterateManeuvers name="aManeuver" type="oracle.panama.spatial.jsptags.beans.Maneuver" routeID="myRoute"> <a href="<%= aManeuver.getMap() %>"> <%= aManeuver.getNarrative() %> </a> <HR> </loc:iterateManeuvers>
The businesses
tag creates a collection (of oracle.panama.spatial.yp.YPBusiness
objects) of businesses that share one or more attributes.
Table 14-5 lists the businesses tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example of the businesses
tag specifies all businesses named Borders
in the state of California in the United States. The use of the map
tag to enclose the businesses
tag causes a map to be created that includes and labels each Borders bookstore.
<loc:map name="map1" type="oracle.panama.spatial.jsptags.beans.Map" xres="1000" yres="500"> <loc:businesses name="bord" type="java.util.Collection" businessName="Borders" country="US" state="CA"/> </loc:map>
The category
tag creates a business category (an oracle.panama.spatial.yp.YPCategory
object).
Table 14-6 lists the category
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example uses two category
tags. The first category
tag creates an object named cat_auto
that specifies a category named Automotive
. The second category
tag creates an object named cat_dealers
that specifies a category named Dealers
that is a child of the cat_auto
(Automotive) parent category.
<loc:category name="cat_auto" type="oracle.panama.spatial.yp.YPCategory" categoryName="Automotive" /> <loc:category name="cat_dealers" type="oracle.panama.spatial.yp.YPCategory" parentCategory="cat_auto" categoryName="Dealers" />
The createPrivateCommunity
tag creates a private mobile community. For an explanation of mobile communities, including types of communities, see Section 14.3.2.6, "Mobile Communities".
Table 14-7 lists the createPrivateCommunity
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates a private community owned by user Mike
and including two users (Mike
and Jing
). If the community already exists, it is not created. It also displays information about the community.
<loc:createPrivateCommunity name="comm_private" type="oracle.panama.model.Community" userName="Mike" communityName="My Private Community" communityMembers="Mike Jing" returnNullIfExists="FALSE" /> <%= comm_private.toString() %>
The createSharedCommunity
tag creates a shared mobile community. For an explanation of mobile communities, including types of communities, see Section 14.3.2.6, "Mobile Communities".
Table 14-8 lists the createSharedCommunity
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates a shared community owned by user Mike
and including two users (Mike
and Jing
). If the community already exists, it is not created. It also displays information about the community.
<loc:createSharedCommunity name="comm_shared" type="oracle.panama.model.Community" userName="Mike" communityName="My Shared Community" communityMembers="Mike Jing" returnNullIfExists="FALSE" /> <%= comm_private.toString() %>
The createSystemCommunity
tag creates a system mobile community. For an explanation of mobile communities, including types of communities, see Section 14.3.2.6, "Mobile Communities".
Table 14-9 lists the createSystemCommunity
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates a system community owned by user Mike
and including two users (Mike
and Jing
). If the community already exists, it is not created. It also displays information about the community.
<loc:createSystemCommunity name="comm_system" type="oracle.panama.model.Community" userName="Mike" communityName="My System Community" communityMembers="Mike Jing" returnNullIfExists="FALSE" /> <%= comm_private.toString() %>
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 14-10 lists the defaultLocationbMark
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates an object representing the default location mark for user Mike, and it displays information about that object.
<loc:defaultLocationMark name="user_mark" type="oracle.panama.model.LocationMark" userName="Mike" /> <%= user_mark.toString() %>
The deleteCommunity
tag deletes a private, shared, or system mobile community. For an explanation of mobile communities, including types of communities, see Section 14.3.2.6, "Mobile Communities".
Table 14-11 lists the deleteCommunity
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example deletes, at the request of the user named Mike
, the community named My Private Community
, and it displays the result of the operation (TRUE
or FALSE
).
<loc:deleteCommunity name="delete_comm1" type="Boolean" userName="Mike" communityName="My Private Community" /> <%= delete_comm1.toString() %>
The drivingDistance
tag presents the driving distance for a route or driving maneuver, as determined by the provider.
Table 14-12 lists the drivingDistance
tag parameters. Although route
and maneuver
are listed as optional, you must specify one of these parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates a route named myRoute
between two addresses (a person's office and home), and displays the driving distance for the route.
<loc:route name="myRoute" type="oracle.panama.spatial.jsptags.beans.Route" xres="800" yres="600"> <loc:address name="office" type="oracle.panama.model.Location" businessName="My office" firstLine="1 Oracle Dr" city="Nashua" state="NH" postalCode="03062" country="US"/> <loc:address name="home" type="oracle.panama.model.Location" businessName="My home" firstLine="2 Royal Crest Dr" city="Nashua" state="NH" postalCode="03060" country="US"/> </loc:route> <loc:drivingDistance name="drive_dist" type="String" route="myRoute" /> <%= drive_dist.toString() %>
The drivingTime
tag creates an object containing the estimated driving time for a route.
Table 14-13 lists the drivingTime
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
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 14-14 lists the geocode
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example of the geocode
tag specifies an address (for a store named Mike's Hardware) to be geocoded.
<loc:geocode name = "hardware1" type = "oracle.panama.model.Location" businessName = "Mike's Hardware" houseNumber = "22" streetName = "Monument Sq" city = "Concord" state = "MA" postalCode = "01742" country = "US" makeCorrections = "TRUE" />
The geometry
tag creates a java.util.List
object of points of type oracle.panama.model.Point
.
Table 14-15 lists the geometry
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.) You must specify the points
, route
, or maneuver
parameter.
The following example creates a route between a user's office and home addresses, uses the geometry
tag to create an unformatted list of points along the route, and displays the list.
<loc:route name="myRoute" type="oracle.panama.spatial.jsptags.beans.Route" xres="800" yres="600" requestGeom="true"> <loc:address name="office" type="oracle.panama.model.Location" businessName="My office" firstLine="1 Oracle Dr" city="Nashua" state="NH" postalCode="03062" country="US"/> <loc:address name="home" type="oracle.panama.model.Location" businessName="My home" firstLine="2 Royal Crest Dr" city="Nashua" state="NH" postalCode="03060" country="US"/> </loc:route> <loc:geometry name="my_geom" type="java.util.List" route="myRoute" /> <%= my_geom.toString() %>
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 14.3.2.6, "Mobile Communities".
Table 14-16 lists the getCommunity
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example returns, at the request of the user named Mike
, the community named My Private Community
, and it displays information about the community.
<loc:getCommunity name="get_comm" type="oracle.panama.model.Community" userName="Mike" communityName="My Private Community" /> <%= get_comm.toString() %>
The iterateBusinesses
tag presents individually the businesses in a collection returned by the businesses
tag.
Table 14-17 lists the iterateBusinesses
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates a map that shows the 10 Starbucks business locations nearest to Oracle headquarters, and for each location displays information about it followed by a horizontal rule. Each line of information is a link that the user can click to display a detailed map of the location and its surrounding area.
<loc:address name="HQ" type="oracle.panama.model.Location" businessName="HQ" firstLine="500 Oracle Parkway" city="Redwood City" state="CA" postalCode="94065" country="US"/> <loc:map name="starbucksMap" type="oracle.panama.spatial.jsptags.beans.Map" xres="800" yres="600"> <loc:businesses name="starbucks" type="java.util.Collection" businessName="Starbucks" centerID="HQ" nearestN="10"/> </loc:map> <img src="<%= starbucksMap %>"> <HR> <loc:iterateBusinesses name="singleStarbucks" type="oracle.panama.spatial.yp.YPBusiness" collection="starbucks"> <loc:map name="singleStarbucksMap" type="oracle.panama.spatial.jsptags.beans.Map" xres="800" yres="600" points="singleStarbucks"/> <a href="<%= singleStarbucksMap %>"> <%= singleStarbucks %> </a> <HR> </loc:iterateBusinesses>
The iterateBusinessesInCity
tag presents individually businesses in a specified city.
Table 14-18 lists the iterateBusinessesInCity
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example presents individually all Borders bookstores in San Francisco, California. For each location, it displays information about the location followed by a horizontal rule.
<loc:iterateBusinessesInCity name="a_business_city" type="oracle.panama.spatial.yp.YPBusiness" city="San Francisco" state="CA" country="US" businessName="Borders"> <%= a_business_city.toString() %> <HR> </loc:iterateBusinessesInCity>
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 14-19 lists the iterateBusinessesInCorridor
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates a route between an office and another location, and presents individually the Starbucks locations that are within 3000 meters of any point in the corridor associated with the route. For each location, the example, displays information about the location followed by a horizontal rule.
<loc:route name="myRoute" type="oracle.panama.spatial.jsptags.beans.Route" xres="800" yres="600" requestGeom="true"> <loc:address name="office" type="oracle.panama.model.Location" businessName="Some office" firstLine="500 Oracle Parkway" city="Redwood City" state="CA" postalCode="94065" country="US"/> <loc:address name="ucsb" type="oracle.panama.model.Location" businessName="UCSB" firstLine="6750 El Colegio Rd" city="Goleta" state="CA" postalCode="93117" country="US"/> </loc:route> <loc:geometry name="myRouteGeom" type="java.util.List" route="myRoute"/> <loc:iterateBusinessesInCorridor name="a_business_corridor" type="oracle.panama.spatial.yp.YPBusiness" businessName="Starbucks" corridorID="myRouteGeom" radiusInMeters="3000"> <%= a_business_corridor.toString() %> <HR> </loc:iterateBusinessesInCorridor>
The iterateBusinessesInPostalCode
tag presents individually businesses in a specified postal code.
Table 14-20 lists the iterateBusinessesInPostalCode
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example presents individually all Starbucks locations in postal code 93117 in the United States. For each location, it displays information about the location followed by a horizontal rule.
<loc:iterateBusinessesInPostalCode name="a_business_pcode" type="oracle.panama.spatial.yp.YPBusiness" postalCode="93117" country="US" businessName="Starbucks"> <%= a_business_pcode.toString() %> <HR> </loc:iterateBusinessesInPostalCode>
The iterateBusinessesInRadius
tag presents individually businesses within a circular area, associated with a specified radius in meters, around a point.
Table 14-21 lists the iterateBusinessesInRadius
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example presents individually all Starbucks locations within 5000 meters (5 kilometers) of the point associated with the address for Oracle headquarters. For each location, it displays information about the location followed by a horizontal rule.
<loc:address name="HQ" type="oracle.panama.model.Location" businessName="HQ" firstLine="500 Oracle Parkway" city="Redwood City" state="CA" postalCode="94065" country="US"/> <loc:iterateBusinessesInRadius name="a_business_radius" type="oracle.panama.spatial.yp.YPCategory" businessName="Starbucks" centerID="HQ" radiusInMeters="5000"> <%= a_business_radius.toString() %> <HR> </loc:iterateBusinessesInRadius>
The iterateBusinessesInState
tag presents individually businesses in a specified state.
Table 14-22 lists the iterateBusinessesInState
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example presents individually all Starbucks locations in the state of New Hampshire. For each location, it displays information about the location followed by a horizontal rule.
<loc:iterateBusinessesInState name="a_business_state" type="oracle.panama.spatial.yp.YPBusiness" state="CA" country="US" businessName="Starbucks"> <%= a_business_state.toString() %> <HR> </loc:iterateBusinessesInState>
The iterateBusinessesNearestTo
tag presents individually businesses within a circular area, associated with a specified radius in meters, around a point.
Table 14-23 lists the iterateBusinessesNearestTo
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example presents individually the 10 Starbucks locations nearest to the point associated with the address for Oracle headquarters. For each location, it displays information about the location followed by a horizontal rule.
<loc:address name="HQ" type="oracle.panama.model.Location" businessName="HQ" firstLine="500 Oracle Parkway" city="Redwood City" state="CA" postalCode="94065" country="US"/> <loc:iterateBusinessesNearestTo name="a_business_nearest" type="oracle.panama.spatial.yp.YPBusiness" businessName="Starbucks" centerID="HQ" n="10"> <%= a_business_nearest.toString() %> <HR> </loc:iterateBusinessesNearestTo>
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 14-24 lists the iterateByDistance
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates a collection of the 10 Starbucks business locations nearest to Oracle headquarters. It uses the iterateByDistance
tag to present individually the locations sorted by distance from headquarters, and it displays the information about each location followed by a horizontal rule.
<loc:address name="HQ" type="oracle.panama.model.Location" businessName="HQ" firstLine="500 Oracle Parkway" city="Redwood City" state="CA" postalCode="94065" country="US"/> <loc:businesses name="starbucks" type="java.util.Collection" businessName="Starbucks" centerID="HQ" nearestN="10"/> <loc:iterateByDistance name="iter_dist" type="oracle.panama.model.Point" collection="starbucks" centerID="HQ"> <%= iter_dist.toString() %> <HR> </loc:iterateByDistance>
The iterateByDrivingDistance
tag presents individually the points in a collection, sorted by driving distance from a specified point, as determined by the routing provider.
Table 14-25 lists the iterateByDrivingDistance
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates a collection of the 10 Starbucks business locations nearest to Oracle headquarters, and it uses the iterateByDrivingDistance
tag to sort the locations by driving distance from headquarters, and display the information about each location followed by a horizontal rule.
<loc:address name="HQ" type="oracle.panama.model.Location" businessName="HQ" firstLine="500 Oracle Parkway" city="Redwood City" state="CA" postalCode="94065" country="US"/> <loc:businesses name="starbucks" type="java.util.Collection" businessName="Starbucks" centerID="HQ" nearestN="10"/> <loc:iterateByDrivingDistance name="iter_drive" type="oracle.panama.model.Point" collection="starbucks" centerID="HQ"> <%= iter_drive.toString() %> <HR> </loc:iterateByDrivingDistance>
The iterateByName
tag presents individually the points in a collection, sorted by business name.
Table 14-26 lists the iterateByName
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example presents individually the businesses, sorted by name, in a collection named bookstores
, which was previously created. For each business, it displays information about the location followed by a horizontal rule.
<loc:iterateByName name="iter_name" type="oracle.panama.model.Point" collection="bookstores"> <%= iter_name.toString() %> <HR> </loc:iterateByName>
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 14-27 lists the iterateByRegionName
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example presents individually the businesses, sorted by region name (country, then state, then city, then postal code), in a collection named starbucks
, which was previously created. For each business, it displays information about the location followed by a horizontal rule.
<loc:iterateByRegionName name="iter_reg_name" type="oracle.panama.model.Point" collection="starbucks"> <%= iter_reg_name.toString() %> <HR> </loc:iterateByRegionName>
The iterateCategoriesMatchingKeyword
tag creates a collection of categories that match a specified keyword value, and presents the categories individually.
Table 14-28 lists the iterateCategoriesMatchingKeyword
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example presents individually the categories that match the keyword restaurant
. For each category, it displays the fully qualified name followed by a horizontal rule.
<loc:iterateCategoriesMatchingKeyword name="a_category" type="oracle.panama.spatial.yp.YPCategory" keyword="restaurant"> <%= a_category.getFullyQualifiedName() %> <HR> </loc:iterateCategoriesMatchingKeyword>
The iterateChildCategories
tag specifies a collection of immediate child subcategories, presented individually.
Table 14-29 lists the iterateChildCategories
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example presents individually all child categories of the parent category associated with the variable restaurant
. For each child category, it displays the fully qualified name followed by a horizontal rule.
<loc:iterateChildCategories name="a_child_category" type="oracle.panama.spatial.yp.YPCategory" parentCategory="restaurant"> <%= a_child_category.getFullyQualifiedName() %> <HR> </loc:iterateChildCategories>
The iterateGeocodes
tag returns a collection of geocoded addresses, presented individually.
Table 14-30 lists the iterateGeocodes
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example of the iterateGeocodes
tag presents each geocoded address on Daniel Webster Highway in postal code 03060 in Nashua, New Hampshire. For each geocoded address, it displays a horizontal rule and a line of text, performs a line break, and displays the address information from the provider.
<loc:iterateGeocodes name = "a_business" type = "oracle.panama.model.Location" streetName = "Daniel Webster Hwy" city = "Nashua" state = "NH" postalCode = "03060" country = "US"> <HR> Another business in our community: <br> <%= a_business.toString() %> </loc:iterateGeocodes>
The iterateLocationMarks
tag presents individually the location marks for an Oracle Application Server Wireless user.
Table 14-31 lists the iterateLocationMarks
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example presents each location mark for user Mike
as an object associated with the variable iter_marks
, and for each object it displays information about the object followed by a horizontal rule.
<loc:iterateLocationMarks name="iter_marks" type="oracle.panama.model.LocationMark" userName="Mike" > <%= iter_marks.toString() %> <HR> </loc:iterateLocationMarks>
The iterateManeuvers
tag creates a collection of driving maneuvers, and it presents the maneuvers individually.
Table 14-32 lists the iterateManeuvers
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates a route named myRoute
between two addresses (a person's office and home), displays a map of the route followed by a horizontal rule, and presents each driving maneuver (using the iterateManeuvers
tag and the getMap
and getNarrative
function calls) followed by a horizontal rule. Each driving maneuver description is also a link that users can click to display a map of the maneuver.
<loc:route name="myRoute" type="oracle.panama.spatial.jsptags.beans.Route" xres="800" yres="600"> <loc:address name="office" type="oracle.panama.model.Location" businessName="My office" firstLine="1 Oracle Dr" city="Nashua" state="NH" postalCode="03062" country="US"/> <loc:address name="home" type="oracle.panama.model.Location" businessName="My home" firstLine="2 Royal Crest Dr" city="Nashua" state="NH" postalCode="03060" country="US"/> </loc:route> <img src="<%= myRoute.getMap() %>"> <HR> <loc:iterateManeuvers name="aManeuver" type="oracle.panama.spatial.jsptags.beans.Maneuver" routeID="myRoute"> <a href="<%= aManeuver.getMap() %>"> <%= aManeuver.getNarrative() %> </a> <HR> </loc:iterateManeuvers>
The iterateReverseGeocodes
tag returns a collection of reverse geocoded addresses (addresses associated by the provider with a specified point), presented individually.
Table 14-33 lists the iterateReverseGeocodes
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example of the iterateReverseGeocodes
tag presents each geocoded address that the provider associates with a specified point For each geocoded address, it displays the address information from the provider followed by a horizontal rule.
<loc:iterateReverseGeocodes name = "iter_rev" type = "oracle.panama.model.Location" lon = "-71.4424" lat = "42.712" label = "You Are Here" > <%= iter_rev.toString() %> <HR> </loc:iterateReverseGeocodes>
The listAllMembers
tag creates an unformatted list of all members of a specified mobile community.
Table 14-34 lists the listAllMembers
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates an unformatted list of all members of the community associated with the variable named comm_private
, and it displays the java.util.Enumeration
object that is created.
<loc:listAllMembers name="list_all_mem" type="java.util.Enumeration" communityID="comm_private" /> <%= list_all_mem.toString() %>
The listBusinessesInCity
creates an unformatted list of businesses in a specified city.
Table 14-35 lists the listBusinessesInCity
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates an unformatted list of all Borders bookstores in San Francisco, California, and it displays the list.
<loc:listBusinessesInCity name="all_businesses_city" type="java.util.List" city="San Francisco" state="CA" country="US" businessName="Borders"> </loc:listBusinessesInCity> <%= all_businesses_city.toString() %>
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 14-36 lists the listBusinessesInCorridor
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates a route between an office and another location, creates an unformatted list of the Starbucks locations that are within 3000 meters of any point in the corridor associated with the route, and displays the list.
<loc:route name="myRoute" type="oracle.panama.spatial.jsptags.beans.Route" xres="800" yres="600" requestGeom="true"> <loc:address name="office" type="oracle.panama.model.Location" businessName="Some office" firstLine="500 Oracle Parkway" city="Redwood City" state="CA" postalCode="94065" country="US"/> <loc:address name="ucsb" type="oracle.panama.model.Location" businessName="UCSB" firstLine="6750 El Colegio Rd" city="Goleta" state="CA" postalCode="93117" country="US"/> </loc:route> <loc:geometry name="myRouteGeom" type="java.util.List" route="myRoute"/> <loc:listBusinessesInCorridor name="all_businesses_corridor" type="java.util.List" businessName="Starbucks" corridorID="myRouteGeom" radiusInMeters="3000"> </loc:listBusinessesInCorridor> <%= all_businesses_corridor.toString() %>
The listBusinessesInPostalCode
tag creates an unformatted list of businesses in a specified postal code.
Table 14-37 lists the listBusinessesInPostalCode
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates an unformatted list of all Starbucks locations in postal code 93117 in the United States, and it displays the list.
<loc:listBusinessesInPostalCode name="all_businesses_pcode" type="java.util.List" postalCode="93117" country="US" businessName="Starbucks"> </loc:listBusinessesInPostalCode> <%= all_businesses_pcode.toString() %>
The listBusinessesInRadius
tag creates an unformatted list of businesses within a circular area, associated with a specified radius in meters, around a point.
Table 14-38 lists the listBusinessesInRadius
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates an unformatted list of all Starbucks locations within 5000 meters (5 kilometers) of the point associated with the address for Oracle headquarters, and it displays the list.
<loc:address name="HQ" type="oracle.panama.model.Location" businessName="HQ" firstLine="500 Oracle Parkway" city="Redwood City" state="CA" postalCode="94065" country="US"/> <loc:listBusinessesInRadius name="all_businesses_radius" type="java.util.List" businessName="Starbucks" centerID="HQ" radiusInMeters="5000"> </loc:listBusinessesInRadius> <%= all_businesses_radius.toString() %>
The listBusinessesInState
tag creates an unformatted list of businesses in a specified state.
Table 14-39 lists the listBusinessesInState
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates an unformatted list of all Starbucks locations in the state of New Hampshire, and it displays the list.
<loc:listBusinessesInState name="all_businesses_state" type="java.util.List" state="CA" country="US" businessName="Borders"> </loc:listBusinessesInState> <%= all_businesses_state.toString() %>
The listBusinessesNearestTo
tag creates an unformatted list of businesses within a circular area, associated with a specified radius in meters, around a point.
Table 14-40 lists the listBusinessesNearestTo
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates an unformatted list of the 10 Starbucks locations nearest to the point associated with the address for Oracle headquarters, and it displays the list.
<loc:address name="HQ" type="oracle.panama.model.Location" businessName="HQ" firstLine="500 Oracle Parkway" city="Redwood City" state="CA" postalCode="94065" country="US"/> <loc:listBusinessesNearestTo name="all_businesses_nearest" type="java.util.List" businessName="Starbucks" centerID="HQ" n="10"> </loc:listBusinessesNearestTo> <%= all_businesses_nearest.toString() %>
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 14-41 lists the listByDistance
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates a collection of the 10 Starbucks business locations nearest to Oracle headquarters, uses the listByDistance
tag to create an unformatted list of locations sorted by distance from headquarters, and displays the list.
<loc:address name="HQ" type="oracle.panama.model.Location" businessName="HQ" firstLine="500 Oracle Parkway" city="Redwood City" state="CA" postalCode="94065" country="US"/> <loc:businesses name="starbucks" type="java.util.Collection" businessName="Starbucks" centerID="HQ" nearestN="10"/> <loc:listByDistance name="list_dist" type="java.util.List" collection="starbucks" centerID="HQ"> </loc:listByDistance> <%= list_dist.toString() %>
The listByDrivingDistance
tag creates an unformatted list of the points in a collection, sorted by driving distance from a specified point, as determined by the routing provider.
Table 14-42 lists the listByDrivingDistance
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates a collection of the 10 Starbucks business locations nearest to Oracle headquarters, uses the listByDrivingDistance
tag to create an unformatted list of locations sorted by driving distance from headquarters, and displays the list.
<loc:address name="HQ" type="oracle.panama.model.Location" businessName="HQ" firstLine="500 Oracle Parkway" city="Redwood City" state="CA" postalCode="94065" country="US"/> <loc:businesses name="starbucks" type="java.util.Collection" businessName="Starbucks" centerID="HQ" nearestN="10"/> <loc:listByDrivingDistance name="list_drive" type="java.util.List" collection="starbucks" centerID="HQ"> </loc:listByDrivingDistance> <%= list_drive.toString() %>
The listByName
tag creates an unformatted list of the points in a collection, sorted by business name.
Table 14-43 lists the listByName
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates an unformatted list of the businesses, sorted by name, in a collection named bookstores
(which was previously created), and it displays the list.
<loc:listByName name="list_name" type="java.util.List" collection="bookstores"> </loc:listByName> <%= list_name.toString() %>
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 14-44 lists the listByName
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates an unformatted list of the businesses, sorted by region name (country, then state, then city, then postal code), in a collection named starbucks
(which was previously created), and it displays the list.
<loc:listByRegionName name="list_reg_name" type="java.util.List" collection="starbucks"> </loc:listByRegionName> <%= list_reg_name.toString() %>
The listCategoriesMatchingKeyword
tag creates an unformatted list of business directory categories that match a specified keyword.
Table 14-45 lists the listCategoriesMatchingKeyword
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates an unformatted list of the categories that match the keyword restaurant
, and it displays the list.
<loc:listCategoriesMatchingKeyword name="all_categories_key" type="java.util.List" keyword="restaurant"> </loc:listCategoriesMatchingKeyword> <%= all_categories_key.toString() %>
The listChildCategories
tag creates an unformatted list of immediate child subcategories.
Table 14-46 lists the listChildCategories
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates an unformatted list of all child categories of the parent category associated with the variable restaurant
, and it displays the list.
<loc:listChildCategories name="all_categories_child" type="java.util.List" parentCategory="restaurant"> </loc:listChildCategories> <%= all_categories_child.toString() %>
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 14.3.2.6, "Mobile Communities".
Table 14-47 lists the listCreatedCommunities
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example created an unformatted list, at the request of the user named Mike
, of all mobile communities, and it displays the list.
<loc:listCreatedCommunities name="list_cr_comm" type="java.util.List" userName="Mike" /> <%= list_cr_comm.toString() %>
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 14.3.2.6, "Mobile Communities".
Table 14-48 lists the listCreatedPrivateCommunities
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example created an unformatted list, at the request of the user named Mike
, of all mobile private communities, and it displays the list.
<loc:listCreatedPrivateCommunities name="list_cr_priv_comm" type="java.util.List" userName="Mike" /> <%= list_cr_priv_comm.toString() %>
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 14.3.2.6, "Mobile Communities".
Table 14-49 lists the listCreatedSharedCommunities
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example created an unformatted list, at the request of the user named Mike
, of all mobile shared communities, and it displays the list.
<loc:listCreatedSharedCommunities name="list_cr_shar_comm" type="java.util.List" userName="Mike" /> <%= list_cr_shar_comm.toString() %>
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 14.3.2.6, "Mobile Communities".
Table 14-50 lists the listCreatedSystemCommunities
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example created an unformatted list, at the request of the user named Mike
, of all mobile system communities, and it displays the list.
<loc:listCreatedSystemCommunities name="list_cr_sys_comm" type="java.util.List" userName="Mike" /> <%= list_cr_sys_comm.toString() %>
The listGeocodes
tag creates an unformatted list of geocoded addresses.
Table 14-51 lists the listGeocodes
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example of the listGeocodes
tag presents all geocoded addresses on Daniel Webster Highway in postal code 03060 in Nashua, New Hampshire.
<loc:listGeocodes name = "all_businesses" type = "java.util.List" streetName = "Daniel Webster Hwy" city = "Nashua" state = "NH" postalCode = "03060" country = "US" />
The listLocationMarks
tag creates an unformatted list of the location marks for an OracleAS Wireless user.
Table 14-52 lists the listLocationMarks
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates an unformatted list of the location marks for user Mike
as an object associated with the variable list_marks
, and it displays information about the object.
<loc:listLocationMarks name="list_marks" type="java.util.List" userName="Mike" /> <%= list_marks.toString() %>
The listManeuvers
tag creates an unformatted list of driving maneuvers.
Table 14-53 lists the listManeuvers
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates a route named myRoute between two addresses (a person's office and home), displays a map of the route followed by a horizontal rule, and presents an unformatted list of all the driving maneuvers for the route.
<loc:route name="myRoute" type="oracle.panama.spatial.jsptags.beans.Route" xres="800" yres="600"> <loc:address name="office" type="oracle.panama.model.Location" businessName="My office" firstLine="1 Oracle Dr" city="Nashua" state="NH" postalCode="03062" country="US"/> <loc:address name="home" type="oracle.panama.model.Location" businessName="My home" firstLine="2 Royal Crest Dr" city="Nashua" state="NH" postalCode="03060" country="US"/> </loc:route> <loc:listManeuvers name="all_maneuvers" type="java.util.List" routeID="myRoute" /> <%= all_maneuvers.toString() %>
The listReverseGeocodes
tag creates an unformatted list of reverse geocoded addresses (addresses associated by the provider with a specified point).
Table 14-54 lists the listReverseGeocodes
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example of the listReverseGeocodes
tag presents addresses associated by the provider with a specified point.
<loc:listReverseGeocodes name = "list_rev" type = "java.util.List" lon = "-71.4424" lat = "42.712" label = "You Are Here" /> <%= list_rev.toString() %>
The map
tag specifies a map with a specified resolution and showing one of the following:
Table 14-55 lists the map
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example of the map
tag creates a map named NEDCSmall
400 pixels wide and 300 pixels high. The center point for the map is the address defined by the address
tag enclosed in the map
tag.
<loc:map name="NEDCSmall" type="oracle.panama.spatial.jsptags.beans.Map" xres="400" yres="300"> <loc:address name="NEDC" type="oracle.panama.model.Location" businessName="NEDC" firstLine="1 Oracle Dr" city="Nashua" state="NH" postalCode="03062" country="US"/> </loc:map>
The mobilePos
tag creates an object with positioning information about a mobile user.
Table 14-56 lists the mobilePos
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example creates an object with positioning information for user Mike
. By default, if the current position cannot be obtained, the default location mark for that user is used. The example also displays the positioning information.
<loc:mobilePos name="position" type="oracle.panama.model.Point" userName="Mike" /> <%= position.toString() %>
The point
tag specifies the longitude and latitude value of a point, using the WGS 84 coordinate system (Oracle Spatial SRID value 8307).
Table 14-57 lists the point
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example of the point
tag specifies the point at 75.3 degrees west longitude and 45.71 degrees north latitude.
<loc:point lon = "-73.5" lat = "45.71" />
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 14.3.2.6, "Mobile Communities".
Table 14-58 lists the removeAllMembers
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example removes, at the request of the user named Mike
, all members from the mobile community associated with the variable named comm_private
. It also creates a java.util.Enumeration
object of members of this community, and displays this object.
<loc:removeAllMembers name="remove_all_members" type="Boolean" userName="Mike" communityID="comm_private" /> <loc:listAllMembers name="list_all_mem3" type="java.util.Enumeration" communityID="comm_private" /> <%= list_all_mem3.toString() %>
The removeMembers
tag removes one or more members from a mobile community. For an explanation of mobile communities, see Section 14.3.2.6, "Mobile Communities".
Table 14-59 lists the removeMembers
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example removes, at the request of the user named Mike
, the users named Oscar
and Maria
from the mobile community associated with the variable named comm_private
. It also creates a java.util.Enumeration
object of members of this community, and displays this object.
<loc:removeMembers name="remove_members" type="Boolean" userName="Mike" communityID="comm_private" communityMembers="Oscar Maria" /> <loc:listAllMembers name="list_all_mem2" type="java.util.Enumeration" communityID="comm_private" /> <%= list_all_mem2.toString() %>
The route
tag specifies a route with a specified map resolution. It includes maneuvers, an overview map, and maneuver maps.
Table 14-60 lists the route
tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
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 14-61 lists the address tag parameters. (See Section 14.2.1, "Creating JavaServer Pages (JSP) Files" for an explanation of the information provided.)
The following example sets, at the request of the user named Mike
, the community name of the existing community that is associated with the variable named comm_shared
. The community name is set to the value Renamed Shared Community
. The example also displays the result of the operation (TRUE
or FALSE
).
<loc:setCommunityName name="set_comm_name" type="Boolean" userName="Mike" communityID="comm_shared" newName="Renamed Shared Community" /> <%= set_comm_name.toString() %>
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 MobileXML 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 14-9.
<SimpleResult> <SimpleForm target="EnterAddress2.jsp"> <SimpleFormItem name="businessName" title="Business Name" value="Oracle"/> <SimpleFormItem name="houseNum" title="House Number" value="500"/> <SimpleFormItem name="street" title="Street" value="Oracle Parkway"/> <SimpleFormItem name="city" title="City" value="Redwood City"/> <SimpleFormItem name="state" title="State" value="CA"/> <SimpleFormItem name="postalCode" title="Postal Code" value="94065"/> <SimpleFormItem name="country" title="Country" value="US"/> </SimpleForm> </SimpleResult>
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 14-9.
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 14-10. (Another format of SpatialManager.createlocation
, not shown in Example 14-10, specifies a point with longitude and latitude coordinates, in which case a Location
object is created but no geocoding is done.)
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 14-11.
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 14.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 14-12 creates a drop-down SimpleFormSelect
element that lets the user select an address format (US, German, French, and so on).
<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 14-13.
<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 14-14 displays the result. The components to display and the number of lines depend on the country.
<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 14-15 retrieves the location marks into an array. (Code not relevant to location marks is omitted from this example.)
... LocationMark locMarks[] = sr.getSession().getUser().getLocationMarks(); ...
Note that LocationMark
extends Location
(an address).
You can create an adapter that provides routing information between a start address and an end address that the user enters. The adapter must:
Example 14-16 sets the routing settings and options by constructing a RoutingSettings
object and specifying the resolution (height and width) of the resulting overview and maneuver maps.
RoutingSettings rS = new RoutingSettings(true, false); rS.setSecondaryOption(RoutingOption.overviewMapHeight, "600"); rS.setSecondaryOption(RoutingOption.overviewMapWidth, "800"); rS.setSecondaryOption(RoutingOption.maneuverMapHeight, "600"); rS.setSecondaryOption(RoutingOption.maneuverMapWidth, "800");
Example 14-17 computes the route, returning a RoutingResult
object.
RoutingResult rR = SpatialManager.getRouter().computeRoute( startLoc, endLoc, null, // via points rS, // routing options Locale.US);
Example 14-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.)
<%! 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 14-19 gets the map image URL of an address to be mapped. (The variable loc
of type Location
contains an address that has been previously geocoded.)
String url = SpatialManager.getMapper().getMapURL( loc, oracle.panama.imagex.ImageFormats.GIF, 800, // width 600, // height false); // allow turning
In Example 14-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 14-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 14-20.
YPFinder ypF = SpatialManager.getYPFinder(); YPCategory cats[] = ypF.getCategoryAtRoot().getCategoriesMatchingName(keyword);
Example 14-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.
<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 14-22.
YPCategory cat = YPCategory.fromFullyQualifiedName(categoryNameString); YPBusiness b[] = SpatialManager.getYPFinder().getBusinessesInCity( cat, country, state, city, Locale.US);
The conversion in Example 14-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:
CityInfo
, RouteInfo
, Point
, and Location
) for the query.
TrafficReporter
and summit the query.
TrafficReport
and process the information.
The rest of this section contains examples of typical operations. Example 14-23 performs a city-level query.
TrafficReporter reporter = SpatialManager.getTrafficReporter(); CityInfo c = new CityInfo("BOSTON", "MA", "US"); TrafficReport report = null; try{ report = reporter.getReportViaCity(c); }catch(LBSException e){ System.out.println(e.getLocalizedMessage()); }
Example 14-24 performs a route-level query without specifying a direction, and returns 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 14-25 performs a route-level query for a specified direction (north).
try{ report = reporter.getReportViaRoute(r,TrafficReporter.North,c); }catch(LBSException e){ System.out.println(e.getLocalizedMessage()); }
Example 14-26 performs a route-level query for an area 10 miles around a specified 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 14-27 performs a route-level query for an area 10 miles around a specified 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 14-28 processes a traffic report to get useful information.
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 14-29 returns a list of cities for which traffic support is provided.
TrafficCityManager manager = reporter.getCityManager(); CityInfo[] cities = null; try{ cities = manager.getActiveCities(); }catch(LBSException e){ System.out.println(e.getLocalizedMessage()); }
Example 14-30 returns a list of routes for which traffic support is provided in a specified city (San Francisco, California).
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, and business directory (YP) 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:
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 14.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:
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 mobile 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 mobile 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 14.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 14.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:
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 14-5.
As Figure 14-5 shows:
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 14.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:
You can specify the positioning quality of service value in either of the following ways:
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 14.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:
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:
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.
Programs should check that the PositionResult
has a nonzero error code before using it.
Example 14-31 gets the user's position using system default providers and the default positioning quality of service.
Positioner positioner = MPManager.getPositioner(); PositionResult res = positioner.requestPosition("46708123456790"); Date timeStamp = res.getTimeStamp(); double lon = res.getPositionAreas()[0].getCenterPointLongitude(); double lat = res.getPositionAreas()[0].getCenterPointLatitude();
Example 14-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 14.3.2.3 explains the ways in which you can specify positioning quality of service.)
PositionResult res = positioner.requestPosition("46708123456790", ServiceQoS.HIGH_QUAL); PositionResult res = positioner.requestPosition("46708123456790", new ServiceQos(120));
Example 14-33 gets the user's position based on an array of specific providers.
MPProvider[] providers = new MPProvider[2]; providers[0] = MPManager.lookup("CellPoint", "1.2"); providers[1] = MPManager.lookup("Ericsson", "3.0"); Positioner positioner = MPManager.getPositioner(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:
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 mobile 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 14.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:
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:
The following community operations are supported:
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:
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.
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.
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 14.3.2.3.)
Developers of mobile 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 14-34 lists all communities of a specified type that are 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 14-35 grants the positioning right to a user or a community based on user input.
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:
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:
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:
LBCondition
class; see Section 14.4.3, "Location-Based Condition Object (LBCondition)")
LBEventAgent
class; see Section 14.4.4, "Location Event Agent Object (LBEventAgent)")
LBEventHandler
class; see Section 14.4.5, "Location Event Handler Object (LBEventHandler)")
Example 14-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.
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:
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:
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:
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.
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.
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.
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:
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:
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:
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.
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.
The region modeling tool is displayed, as shown in Figure 14-7.
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 14-62.
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 14-63.
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 14-37 shows the DESCRIBE statement output with information about all of the tables.
SQL> DESCRIBE continent; Name Null? Type ----------------------------------------- -------- ---------------------------- ID NOT NULL NUMBER NAME VARCHAR2(100) REFCNT NUMBER DESCRIPTION VARCHAR2(2000) GEOMETRY MDSYS.SDO_GEOMETRY SQL> DESCRIBE country; Name Null? Type ----------------------------------------- -------- ---------------------------- ID NOT NULL NUMBER NAME VARCHAR2(300) REFCNT NUMBER CONT_ID NUMBER DESCRIPTION VARCHAR2(2000) GEOMETRY MDSYS.SDO_GEOMETRY SQL> DESCRIBE state; Name Null? Type ----------------------------------------- -------- ---------------------------- ID NOT NULL NUMBER NAME VARCHAR2(400) REFCNT NUMBER ABBR VARCHAR2(32) CONT_ID NUMBER COUNTRY_ID NUMBER DESCRIPTION VARCHAR2(2000) GEOMETRY MDSYS.SDO_GEOMETRY SQL> DESCRIBE county; Name Null? Type ----------------------------------------- -------- ---------------------------- ID NOT NULL NUMBER NAME VARCHAR2(400) REFCNT NUMBER CONT_ID NUMBER COUNTRY_ID NUMBER STATE_ID NUMBER DESCRIPTION VARCHAR2(2000) GEOMETRY MDSYS.SDO_GEOMETRY SQL> DESCRIBE city; Name Null? Type ----------------------------------------- -------- ---------------------------- ID NOT NULL NUMBER NAME VARCHAR2(400) REFCNT NUMBER CONT_ID NUMBER COUNTRY_ID NUMBER STATE_ID NUMBER DESCRIPTION VARCHAR2(2000) GEOMETRY MDSYS.SDO_GEOMETRY MIN_LON NUMBER MIN_LAT NUMBER MAX_LON NUMBER MAX_LAT NUMBER SQL> DESCRIBE postalcode; Name Null? Type ----------------------------------------- -------- ---------------------------- ID NOT NULL NUMBER NAME VARCHAR2(400) REFCNT NUMBER CONT_ID NUMBER COUNTRY_ID NUMBER STATE_ID NUMBER DESCRIPTION VARCHAR2(2000) GEOMETRY MDSYS.SDO_GEOMETRY SQL> DESCRIBE userdefined; Name Null? Type ----------------------------------------- -------- ---------------------------- ID NOT NULL NUMBER NAME VARCHAR2(200) REFCNT NUMBER TYPE NUMBER PARENT_FOLDER_ID NUMBER DESCRIPTION VARCHAR2(2000) GEOMETRY MDSYS.SDO_GEOMETRY
You can use the SQL statement INSERT to insert rows into the region tables. The following considerations apply when you are inserting region data:
idseq.nextval
to generate the ID column value whenever you insert a new row, as shown in Example 14-38. The idseq sequence is created automatically during installation; you should not create it.
Example 14-38 shows an INSERT statement to insert a row for Concord, Massachusetts into the CITY table. It assumes that the geometry representing Concord exists in another table named MY_CITIES.
DECLARE city_geom MDSYS.SDO_GEOMETRY; BEGIN -- Populate geometry variable with city geometry from another table. SELECT m.geometry into city_geom FROM my_cities m WHERE m.name = 'Concord'; -- Insert into the CITY table. INSERT INTO CITY VALUES ( idseq.nextval, 'Concord', 0, 5004, -- continent ID for North America 5006, -- country ID for USA 5028, -- state ID for Massachusetts 'The historic town of Concord', city_geom, -71.35, -- minimum longitude 42.46, -- minimum latitude -71.34, -- maximum longitude 42.47); -- maximum latitude END; /
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 14.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:
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 includes the following steps:
Step 4 in the preceding list (invoking one or more mobile positioning providers) involves the following specific actions:
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:
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 14.7.2.
This section describes guidelines for handling runtime mobile positioning errors and exceptions, which can occur in any of the following ways:
requestPosition
methods described in Section 14.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:
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.
PositionResult
object with the error ID and error message from the provider.
|
![]() Copyright © 2003 Oracle Corporation. All Rights Reserved. |
|