net.christopherschultz.util.zipcode
Class ZipCodeRegistry

java.lang.Object
  extended by net.christopherschultz.util.zipcode.ZipCodeRegistry
All Implemented Interfaces:
Serializable

public class ZipCodeRegistry
extends Object
implements Serializable

A registry of US postal codes.

The methods in this class are not thread safe, so intermixing calls to add(net.christopherschultz.util.zipcode.ZipCode) with the various forms of get should be synchronized. Usually, the registry is initialized once and then all access is read-only; hence, this class provides no synchronization of its own.

See Also:
Serialized Form

Constructor Summary
ZipCodeRegistry()
          Creates a ZipCodeRegistry object with no ZipCodes.
 
Method Summary
 void add(ZipCode zipCode)
          Adds a ZipCode to the registry.
 ZipCode getClosestZipCode(ZipCode target)
          Gets the ZipCode that is closest geographically from the specified ZipCode.
static ZipCodeRegistry getInstance()
          Gets the default instance of a ZipCodeRegistry.
 ZipCode getNearestMatch(int zipCode)
          Gets the ZipCode which is the closest numerically to the specified zip code.
 ZipCode getZipCode(int zipCode)
          Gets the ZipCode which corresponds to the specified zip code.
 List getZipCodesWithinKilometers(ZipCode target, double km)
          Gets a list of ZipCodes that are within the specified number of kilometers.
 List getZipCodesWithinMiles(ZipCode target, double miles)
          Gets a list of ZipCodes that are within the specified number of miles.
static ZipCodeRegistry load(String resourceName)
          Loads a ZipCodeRegistry from the specified file.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ZipCodeRegistry

public ZipCodeRegistry()

Creates a ZipCodeRegistry object with no ZipCodes.

Method Detail

add

public void add(ZipCode zipCode)

Adds a ZipCode to the registry.

Parameters:
zipCode - The ZipCode to add to the registry.

getZipCode

public ZipCode getZipCode(int zipCode)

Gets the ZipCode which corresponds to the specified zip code.

Parameters:
zipCode - The 5-digit zip code to lookup.
Returns:
The ZipCode object that corresponds to the specified zip code, or null if there is no corresponding ZipCode object for the specified zip code.
See Also:
getNearestMatch(int)

getNearestMatch

public ZipCode getNearestMatch(int zipCode)

Gets the ZipCode which is the closest numerically to the specified zip code.

Numerically looking up zip codes is rather inaccurate, but if you have a zip code which is not in the registry, this may be the only way to find one.

Parameters:
zipCode - The 5-digit zip code to lookup.
Returns:
The ZipCode object that corresponds to the zip code closest numerically to the specified zip code.

getClosestZipCode

public ZipCode getClosestZipCode(ZipCode target)

Gets the ZipCode that is closest geographically from the specified ZipCode.

Parameters:
target - The ZipCode to come closest to.
Returns:
The ZipCode which is closest geographically to the specified ZipCode.

getZipCodesWithinMiles

public List getZipCodesWithinMiles(ZipCode target,
                                   double miles)

Gets a list of ZipCodes that are within the specified number of miles.

Parameters:
target - The ZipCode which should be the center of the search.
miles - The maximum distance (in miles) a ZipCode may be from the target.
Returns:
A list of ZipCode objects each of which has a distance less than or equal to the specified mileage.

getZipCodesWithinKilometers

public List getZipCodesWithinKilometers(ZipCode target,
                                        double km)

Gets a list of ZipCodes that are within the specified number of kilometers.

Parameters:
target - The ZipCode which should be the center of the search.
km - The maximum distance (in kilometers) a ZipCode may be from the target.
Returns:
A list of ZipCode objects each of which has a distance less than or equal to the specified distance in kilometers.

getInstance

public static ZipCodeRegistry getInstance()
                                   throws IOException

Gets the default instance of a ZipCodeRegistry.

This ZipCodeRegistry comes with a zip code location file that it will load for itself.

Returns:
A ZipCodeRegistry containing ZipCode objects for all zip codes.
Throws:
IOException - If there is a problem loading the zip code registry.

load

public static ZipCodeRegistry load(String resourceName)
                            throws IOException

Loads a ZipCodeRegistry from the specified file.

The file should be text with each line like this:

         byte
         0123456789 123456789 12345
 content [ZIP][LATITUDE][LONGITUDE]
 

...where [ZIP] is the 5-digit zip-code and [LATITUDE] and [LONGITUDE] are the latitude and longitude, respectively, of the post office serving that zip code.

The latitude and longitude may be of arbitrary precision, and may begin with a - or + sign. Note that there is no whitespace of any kind necessary. Whitespace must be used to pad any missing digits since the byte count is significant.

Any lines of text starting with a hash mark (#) will be ignored.

Parameters:
resourceName - The name of the resource containing the properly serialized form of the ZipCodeRegistry (see above).
Returns:
A ZipCodeRegistry loaded from the specified file.
Throws:
IOException - If there is a problem reading the resource.