Oracle Application Server Wireless Java API Reference
B10400-01

oracle.panama.spatial.region
Interface RegionModel


public interface RegionModel

RegionModel interface.


Method Summary
 Location[] getCitiesInCountry(java.lang.String country)
          Get all cities in a country.
 Location[] getCitiesInState(java.lang.String state, java.lang.String country)
          Get all cities in a state.
 java.lang.String[] getContinents()
          Get the names of all continents.
 Location[] getCountiesInState(java.lang.String state, java.lang.String country)
          Get all counties in a state.
 Location[] getCountriesInContinent(java.lang.String continent)
          Get all the countries in a continent.
 java.lang.String[] getCountry(Point point)
          Given a Point in longitude and latitude, return which country this point is in.
 double getDistanceInMeter(Point point, int regionId)
          Get distance, in meters, between a Point and a Region.
 Location[] getInteractCities(Point point)
          Given a Point (latitude/longitude), find all cities that interact with the point.
 Location[] getInteractCountries(Point point)
          Given a Point (latitude/longitude), find all countries that interact with the point.
 Location[] getInteractPostalCodes(Point point)
          Given a Point (latitude/longitude), find all postal codes that interact with the point.
 int[] getInteractRegions(int regionID)
          Given a region ID, compute all interacting regions.
 int[] getInteractRegions(int regionID, int[] regions)
          Given a region R identified by regID and a list of regions, compute all regions that are in the list and interact with R.
 int[] getInteractRegions(Point location)
          Given a Point (latitude/longitude)we can define an "area of interest" (AOI) with the location as the center.
 int[] getInteractRegions(Point location, int[] regions)
          Given a list of region-ids and an AOI (see documentation), return the region-ids for the regions that interact with the AOI.
 Location[] getInteractStates(Point point)
          Given a Point (latitude/longitude), find all states that interact with the point.
 java.lang.String[] getPostalCode(Point point)
          Deprecated. Replaced by getInteractPostalCodes(Point). The application should call getInteractPostalCodes and get postal code from the returned locations.
 Location[] getPostalCodesInCity(java.lang.String city, java.lang.String state, java.lang.String country)
          Get all postal codes in a city.
 java.lang.String[] getState(Point point)
          Deprecated. Replaced by getInteractStates(Point). The application should call that function and then call getState from the returned locations.
 Location[] getStatesInCountry(java.lang.String country)
          Get all states in a country.
 boolean inside(Point point, int regionId)
          Check whether a Point is inside a region.
 Location[] searchCity(java.lang.String city)
          Search for cities.
 Location[] searchPCode(java.lang.String pcode)
          Search for postal codes.
 Location[] searchPCode(java.lang.String pcode, boolean includeCity)
          Search for postal codes.
 RMRegion[] searchRegions(Location location)
          Search for regions with the given location.
 Location[] searchState(java.lang.String state)
          Search for states.
 Location[] searchStateByAbbr(java.lang.String stateAbbr, java.lang.String country)
          Search for states by abbreviation.

 

Method Detail

getInteractCities

public Location[] getInteractCities(Point point)
Given a Point (latitude/longitude), find all cities that interact with the point. This function depends on the region data in the repository.
Returns:
Location[] An array of Location objects representing the cities that interact with the location. The application should call getCity() getState(), and getCountry() on the returned locations to get the non-ambiguous city information. The application can call getLongitude() and getLatitude() on the returned locations to get the centroid of the city.

getInteractPostalCodes

public Location[] getInteractPostalCodes(Point point)
Given a Point (latitude/longitude), find all postal codes that interact with the point. This function depends on the region data in the repository.
Returns:
Location[] An array of Location objects representing the postal codes that interact with the location. The application should call getPostalCode(), getState(), and getCountry() on the returned locations to get the non-ambiguous postal code information. The application can call getLongitude() and getLatitude() on the returned locations to get the centroid of the postal code.

getInteractStates

public Location[] getInteractStates(Point point)
Given a Point (latitude/longitude), find all states that interact with the point. This function depends on the region data in the repository.
Returns:
Location[] An array of Location objects representing the states that interact with the location. The application should call getState() and getCountry() on the returned locations to get the non-ambiguous state information. The application can call getLongitude() and getLatitude() on the returned locations to get the centroid of the postal code.

getInteractCountries

public Location[] getInteractCountries(Point point)
Given a Point (latitude/longitude), find all countries that interact with the point. This function depends on the region data in the repository.
Returns:
Location[] An array of Location objects representing the countries that interact with the location. The application should call getCountry() on the returned locations to get the country information. The application can call getLongitude() and getLatitude() on the returned locations to get the centroid of the country.

searchPCode

public Location[] searchPCode(java.lang.String pcode)
Search for postal codes. This function depends on the region data in the repository.
Parameters:
pcode - A String representing the postal code. Support '*' and '?' as the wild cards. For example "94065", "94??5", or "0406?".
Returns:
an array of locations representing the matching postal codes. Note: city name will not be included in the return location objects.

searchPCode

public Location[] searchPCode(java.lang.String pcode,
                              boolean includeCity)
Search for postal codes. You can specify whether the city name is included in the return results. This function depends on the region data in the repository.
Parameters:
pcode - A String representing the postal code. Support '*' and '?' as the wild cards. For example "94065", "94??5", or "0406?". Do NOT use just a wild card as the input parameter as that may result in thousands of location and that can be extremely expensive.
includeCity - A boolean value indicating whether you want the city name to be included in the returned location array. Postal code data is not directly associated with city data. In order to figure out what city a postal code resides in a spatial query is required. Therefore, setting this value to true makes the method more expensive. To get city name from a postal code without city information, use getInteractCities() method.
Returns:
an array of locations representing the matching the pcode name.

getCitiesInState

public Location[] getCitiesInState(java.lang.String state,
                                   java.lang.String country)
                            throws oracle.panama.spatial.core.region.RMException
Get all cities in a state. This function depends on the region modeling data in the repository.
Parameters:
state - A String representing the name of the state.
country - A String representing the name of the country. The state and country name parameters must be an exact match (case insensitive) to a state in the region modeling data. You are recommended to do a search for a state first, then use the names in the return result to call this function.
Returns:
an array of locations representing the cities in that state.
Throws:
oracle.panama.spatial.core.region.RMException - if error occurs.

getCitiesInCountry

public Location[] getCitiesInCountry(java.lang.String country)
                              throws oracle.panama.spatial.core.region.RMException
Get all cities in a country. This function depends on the region modeling data in the repository.
Parameters:
country - A String representing the name of the country. The country name parameters must be an exact match (case insensitive) to a country in the region modeling data. You are recommended to do a search for a country first, then use the names in the return result to call this function.
Returns:
an array of locations representing the cities in that country.
Throws:
oracle.panama.spatial.core.region.RMException - if error occurs.

getPostalCodesInCity

public Location[] getPostalCodesInCity(java.lang.String city,
                                       java.lang.String state,
                                       java.lang.String country)
                                throws oracle.panama.spatial.core.region.RMException
Get all postal codes in a city. Note that the postal codes returned by this function may not be strictly inside the city boundary because of allowed data accuracy errors in the spatial data. This function depends on the region modeling data in the repository.
Parameters:
city - A String representing the name of the city.
state - A String representing the name of the state. For countries without state, this parameter must be null.
country - A String representing the name of the country. The city, state and country name parameters must be an exact match (case insensitive) in the region modeling data. You are recommended to do a search for a city first, then use the names in the return result to call this function.
Returns:
an array of locations representing the postal codes in the city.
Throws:
oracle.panama.spatial.core.region.RMException - if error occurs.

getCountiesInState

public Location[] getCountiesInState(java.lang.String state,
                                     java.lang.String country)
                              throws oracle.panama.spatial.core.region.RMException
Get all counties in a state. This function depends on the region modeling data in the repository.
Parameters:
state - A String representing the name of the state.
country - A String representing the name of the country. The state and country name parameters must be an exact match (case insensitive) to a state in the region modeling data. You are recommended to do a search for a state first, then use the names in the return result to call this function.
Returns:
an array of locations representing the counties in that state.
Throws:
oracle.panama.spatial.core.region.RMException - if error occurs.

searchCity

public Location[] searchCity(java.lang.String city)
Search for cities. This function depends on the region data in the repository.
Parameters:
city - A String representing the city name. Support '*' and '?' as the wild cards. For example "San Francisco", "S?n Fran*".
Returns:
an array of locations representing the matching cities.

searchState

public Location[] searchState(java.lang.String state)
Search for states. This function depends on the region data in the repository.
Parameters:
state - A String representing the state name. Support '*' and '?' as the wild cards. For example "Massach*".
Returns:
an array of locations representing the matching states.

searchStateByAbbr

public Location[] searchStateByAbbr(java.lang.String stateAbbr,
                                    java.lang.String country)
Search for states by abbreviation. This function depends on the region data in the repository.
Parameters:
stateAbbr - A String representing the state name abbreviation. Support '*' and '?' as the wild cards. For example "M?".
country - A String representing the name of the country. Support '*' and '?' as the wild cards. For example "US*".
Returns:
an array of locations representing the matching states.

getInteractRegions

public int[] getInteractRegions(Point location)
Given a Point (latitude/longitude)we can define an "area of interest" (AOI) with the location as the center. Then we can find all point locations that lie within the AOI and all "regions" (system and user defined) that overlap the AOI.
Parameters:
location - the Point (latitude/longitude) of the location
Returns:
int[] An asc sorted array of non zero region IDs that interact with the location. The array must be asc sorted to be used for binary search.

getInteractRegions

public int[] getInteractRegions(Point location,
                                int[] regions)
Given a list of region-ids and an AOI (see documentation), return the region-ids for the regions that interact with the AOI.
Parameters:
location - the Point (latitude/longitude) of the location
regions - An asc sorted array of non zero region IDs you want to check
Returns:
int[] An asc sorted array of non zero region IDs that interact with the location. The array must be asc sorted to be used for binary search.

getInteractRegions

public int[] getInteractRegions(int regionID)
Given a region ID, compute all interacting regions.
Parameters:
regionID - Region ID
Returns:
int[] An asc sorted array of non zero region IDs that interact with the location. The array must be asc sorted to be used for binary search.

getInteractRegions

public int[] getInteractRegions(int regionID,
                                int[] regions)
Given a region R identified by regID and a list of regions, compute all regions that are in the list and interact with R.
Parameters:
regionID - Region ID.
regions - An asc sorted array of non zero region IDs you want to check
Returns:
int[] An asc sorted array of non zero region IDs that interact. he array must be asc sorted to be used for binary search.

getPostalCode

public java.lang.String[] getPostalCode(Point point)
Deprecated. Replaced by getInteractPostalCodes(Point). The application should call getInteractPostalCodes and get postal code from the returned locations.
Given a Point in longitude and latitude, return which postal code this point is in.
Parameters:
point - the Point which postal codes we want to find
Returns:
String array representing the postal code that contains the point. If no postal code could be found that contains the point, then null is returned. Please note that this function may return you mutiple postal codes if the point is very close to postal code boundaries. The accuracy of this function depends on the region data quality in the repository.

getState

public java.lang.String[] getState(Point point)
Deprecated. Replaced by getInteractStates(Point). The application should call that function and then call getState from the returned locations.
Given a Point in longitude and latitude, return which state/province this point is in.
Parameters:
point - the Point which state/province we want to find
Returns:
String array representing the states that contains the point. If no state could be found that contains the point, then null is returned. Please note that this function may return you mutiple states if the point is very close to state boundaries. The accuracy of this function depends on the region data quality in the repository.

getCountry

public java.lang.String[] getCountry(Point point)
Given a Point in longitude and latitude, return which country this point is in.
Parameters:
point - the Point which country we want to find
Returns:
String array representing the countries that contains the point. If no country could be found that contains the point, then null is returned. Please note that this function may return you mutiple countries if the point is very close to country boundaries. The accuracy of this function depends on the region data quality in the repository.

getDistanceInMeter

public double getDistanceInMeter(Point point,
                                 int regionId)
                          throws oracle.panama.spatial.core.region.RMException
Get distance, in meters, between a Point and a Region.
Parameters:
point - A Point object.
Returns:
a double representing the distance.
oracle.panama.spatial.core.region.RMException

inside

public boolean inside(Point point,
                      int regionId)
               throws oracle.panama.spatial.core.region.RMException
Check whether a Point is inside a region.
Parameters:
point - A Point object.
Returns:
a boolean value. If it is true then the point is inside the region. otherwise it is outside.
oracle.panama.spatial.core.region.RMException

getStatesInCountry

public Location[] getStatesInCountry(java.lang.String country)
                              throws oracle.panama.spatial.core.region.RMException
Get all states in a country. This function depends on the region modeling data in the repository.
Parameters:
country - A String representing the name of the country. The country name parameter must be an exact match (case insensitive) to a country in the region modeling data. You are recommended to do a search for a country first, then use the names in the return result to call this function.
Returns:
an array of locations representing the states in that country.
Throws:
oracle.panama.spatial.core.region.RMException - if error occurs.

getContinents

public java.lang.String[] getContinents()
                                 throws oracle.panama.spatial.core.region.RMException
Get the names of all continents. This function depends on the region modeling data in the repository.
Returns:
an array of String representing the names of the continents.
Throws:
oracle.panama.spatial.core.region.RMException - if error occurs.

getCountriesInContinent

public Location[] getCountriesInContinent(java.lang.String continent)
                                   throws oracle.panama.spatial.core.region.RMException
Get all the countries in a continent. This function depends on the region modeling data in the repository.
Parameters:
continent - A String representing the name of the continent. The continent name parameter must be an exact match (case insensitive) to a continent in the region modeling data. You are recommended to do a search for continents first, then use the names in the return result to call this function.
Returns:
an array of locations representing the countries in that continent.
Throws:
oracle.panama.spatial.core.region.RMException - if error occurs.

searchRegions

public RMRegion[] searchRegions(Location location)
Search for regions with the given location. This function depends on the region data in the repository.
Parameters:
location - A Location object based on which the search is done.
Returns:
an array of RMRegions representing the matching regions.

Oracle Application Server Wireless Java API Reference
B10400-01

Copyright © 2003 Oracle Corporation. All Rights Reserved.