oracle.panama.spatial.intladdress
Interface IntlAddress

All Superinterfaces:

Location, Point, java.io.Serializable

public interface IntlAddress

extends Location

This interface represents an international address. Each address has a number of components, such as "country", "state", "street", ... with a String value. The components vary for different countries.

Method Summary

java.util.Iterator	getAddressLines(boolean confirmationNecessary, boolean markUnconfirmedComponents) This function will return a String representation of the address.
java.util.Iterator	getComponentNames() This function will return an Iterator of component names contained in the address (for example {"house", "street", "city", "state", "postal code", "country"}).
java.lang.String	getComponentValue(java.lang.String componentName, boolean confirmationNecessary) This function returns the component value for a given component (for example value "US" for component "country").
void	setComponentValue(java.lang.String componentName, java.lang.String componentValue, boolean confirmed) This function sets the component value for a given component (for example value "US" for component "country").
java.lang.String	toString() This function will return a String representation of the address.
java.lang.String	toString(boolean confirmationNecessary, boolean markUnconfirmedComponents) This function will return a String representation of the address.

Methods inherited from interface oracle.panama.model.Location

geocode, getAddressLastLine, getAddressLine1, getAddressLine2, getBlock, getCity, getCompanyName, getCountry, getCounty, getGeocodeProvider, getMatchMode, getPostalCode, getPostalCodeExt, getState, setAddressLastLine, setAddressLine1, setAddressLine2, setBlock, setCity, setCompanyName, setCountry, setCounty, setGeocodeProvider, setMatchMode, setPostalCode, setPostalCodeExt, setState

Methods inherited from interface oracle.panama.model.Point

getDistance, getLabel, getLatitude, getLongitude, getPositionProvider, getRadius, setLabel, setLatitude, setLongitude, setPositionProvider, setRadius

Method Detail

getComponentValue

public java.lang.String getComponentValue(java.lang.String componentName,
                                          boolean confirmationNecessary)

This function returns the component value for a given component (for example value "US" for component "country"). There are two types of values: confirmed or unconfirmed. A confirmed component is informally assumed "trustworthy". When a user enters an address, this address is considered unconfirmed until it is confirmed by a geocoder or any other "authority". Such a confirmation is also exposed in the API and the developer is "given the gun to shoot in his foot" by making unwarranted confirmations himself. In an address "Oracle, 1 Oracleeeeeeeeee Dr, Nashua NH 03060", the geocoder might correct the street name to "Oracle Dr" and then confirm the new value. Alternatively, it might not recognize the street, leave it unconfirmed, but confirm all other components in the address. The fact that the street is not confirmed by the geocoder, shows that the geocoded lat/lon can not be exact. It is, however, in the area defined by the confirmed components ("Nashua NH 03060")

Parameters:

componentName - a String representing the component name, such as "city"

confirmationNecessary - A boolean specifying whether only a confirmed component value should be returned. If so, either "Oracle Dr" or null would be returned, but never "Oracleeeeeeeeee Dr".

Returns:

a String representing the value of the requested component

setComponentValue

public void setComponentValue(java.lang.String componentName,
                              java.lang.String componentValue,
                              boolean confirmed)

This function sets the component value for a given component (for example value "US" for component "country"). There are two types of values: confirmed or unconfirmed. A confirmed component is informally assumed "trustworthy". When a user enters an address, this address is considered unconfirmed until it is confirmed by a geocoder or any other "authority". Such a confirmation is also exposed in the API and the developer is "given the gun to shoot in his foot" by making unwarranted confirmations himself. In an address "Oracle, 1 Oracleeeeeeeeee Dr, Nashua NH 03060", the geocoder might correct the street name to "Oracle Dr" and then confirm the new value. Alternatively, it might not recognize the street, leave it unconfirmed, but confirm all other components in the address. The fact that the street is not confirmed by the geocoder, shows that the geocoded lat/lon can not be exact. It is, however, in the area defined by the confirmed components ("Nashua NH 03060")

Parameters:

componentName - a String representing the component name, such as "city"

confirmed - A boolean specifying whether the component value is confirmed, thus "trustworthy." The developer should be careful when setting the parameter to true. Any value manually entered by a user generally is not "trustworthy" enough. There is, however, no strict standard to define "trustworthy." If a single unconfirmed value is set, the whole address becomes unconfirmed.

getComponentNames

public java.util.Iterator getComponentNames()

This function will return an Iterator of component names contained in the address (for example {"house", "street", "city", "state", "postal code", "country"}).

Returns:

an Iterator returning the component names (not their values) as Strings

toString

public java.lang.String toString()

This function will return a String representation of the address. "\n" is included between the lines. If this is a problem, the signature getAddressLines(boolean confirmationNecessary) is the solution.

Overrides:

toString in class java.lang.Object

Returns:

a String representing the address

toString

public java.lang.String toString(boolean confirmationNecessary,
                                 boolean markUnconfirmedComponents)

This function will return a String representation of the address. "\n" is included between the lines. If this is a problem, the signature getAddressLines(boolean confirmationNecessary) is the solution.

Parameters:

confirmationNecessary - A boolean specifying whether only confirmed component values should be included. If so, either "Oracle Dr" or "(...)" would be used, but never "Oracleeeeeeeeee Dr".

markUnconfirmedComponents - A boolean specifying whether unconfirmed components should be marked as such. This parameter is irrelevant if only confirmed components are included.

Returns:

a String representing the address

getAddressLines

public java.util.Iterator getAddressLines(boolean confirmationNecessary,
                                          boolean markUnconfirmedComponents)

This function will return a String representation of the address. Separate address lines are given in separate Strings.

Parameters:

confirmationNecessary - A boolean specifying whether only confirmed component values should be included. If so, either "Oracle Dr" or "(...)" would be used, but never "Oracleeeeeeeeee Dr".

markUnconfirmedComponents - A boolean specifying whether unconfirmed components should be marked as such. This parameter is irrelevant if only confirmed components are included.

Returns:

an array of Strings representing the address