org.ahmadsoft.postal
Class USPostalCodeService

java.lang.Object
  org.ahmadsoft.postal.USPostalCodeService

public class USPostalCodeService
extends java.lang.Object

Provides a postal code service implementation for the United States of America.

Author:

Amin Ahmad

Nested Class Summary

static class	USPostalCodeService.MatchOptions Specifies options for performing an advanced match operation.
static class	USPostalCodeService.MatchResult The result of a matching operation.

Constructor Summary

USPostalCodeService()

Method Summary

void	dispose() Disposes an instance of this object.
PostalCodeEntry	getActualFor(int postalCode) Returns the PostalCodeEntry for the actual city registered with the U.S.
java.util.List	getCandidates(int postalCode) Returns a list of all recognized candidate cities for a given postal code.
void	initialize(PostalRetrievalStrategy retrievalStrategy) Initializes an instance of the US Postal Code Service.
boolean	isPostalCodeIn(int postalCode, java.lang.String stateAbbr) Returns true if the given postal code is within the given state, or false otherwise.
java.util.List	match(java.lang.String city, int postalCode) Performs a match using default matching options well-suited to common validation.
java.util.List	match(java.lang.String city, int postalCode, USPostalCodeService.MatchOptions options) Returns a list of the closest matches to the specified city within the specified postal code.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

USPostalCodeService

public USPostalCodeService()

Method Detail

dispose

public void dispose()
             throws java.lang.Exception

Disposes an instance of this object. Subsequent use of this object is a logical programming error.

Throws:

java.lang.Exception

initialize

public void initialize(PostalRetrievalStrategy retrievalStrategy)
                throws java.lang.Exception

Initializes an instance of the US Postal Code Service. Initialization is required prior to use.

Parameters:

retrievalStrategy - an initialized postal retrieval strategy.

Throws:

java.lang.Exception - if an error occurs during initialization. Renders this service instance unusable.

getCandidates

public java.util.List getCandidates(int postalCode)

Returns a list of all recognized candidate cities for a given postal code. Candidate cities are catogorized as actual, acceptable, and unacceptable.

Parameters:

postalCode - the postal code.

Returns:

a list of all recognized candidate cities for a given postal code.

isPostalCodeIn

public boolean isPostalCodeIn(int postalCode,
                              java.lang.String stateAbbr)

Returns true if the given postal code is within the given state, or false otherwise. For example, isPostalCodeIn(85050, "AZ") will return true because the 85050 postal code is within Arizona, but isPostalCodeIn(43202, "CA") will return false because the 43202 is not in California, but rather in Ohio.

Parameters:

postalCode - the postal code.

stateAbbr - the two-digit, upper-case abbreviation for a state, as specified in United States Postal Service - Abbreviations.

Returns:

true if the given postal code is within the given state, or false otherwise.

getActualFor

public PostalCodeEntry getActualFor(int postalCode)

Returns the PostalCodeEntry for the actual city registered with the U.S. Post Office for this postal code. This is a useful operation because every postal code has an official city name associated with it, as well as several other names recognized by the post office as acceptable or unacceptable.

For example, getActualFor(90064) will return a PostalCodeEntry for Los Angeles, CA, which is the official city for the 90064 postal code. Rancho Park, CA is an acceptable, but not the actual, name.

Parameters:

postalCode -

Returns:

the PostalCodeEntry for the actual city registered with the U.S. Post Office for this postal code, or null if there is no "actual" candidate for this postal code. This may occur if the postal code is not yet assigned, or is out of range.

match

public java.util.List match(java.lang.String city,
                            int postalCode)

Performs a match using default matching options well-suited to common validation. Specifically, ignore capitalization is true, ignore punctuation is true, ignore whitespace is false, and the minimum match level is PostalCodeConstants.CITY_ACCEPTABLE.

Parameters:

city - the city to match.

postalCode - the postal code within which to match the city.

Returns:

the closest matches to the specified city within the specified postal code.

See Also:

match(String, int, MatchOptions)

match

public java.util.List match(java.lang.String city,
                            int postalCode,
                            USPostalCodeService.MatchOptions options)

Returns a list of the closest matches to the specified city within the specified postal code. The details of the matching process can be controlled by specifying match options.

Note: This method does not take the state into consideration. Rather, use #isPostalCodeIn(int, String) to determine if a postal code is within a given state.

Parameters:

city - the city to match.

postalCode - the postal code within which to match the city.

options - parameters to control the matching process.

Returns:

a list of the closest matches to the specified city within the specfied postal code.

See Also:

USPostalCodeService.MatchOptions