com.billpringle.utils.wrputils
Class WrpZipCode

java.lang.Object
  extended by com.billpringle.utils.wrputils.WrpZipCode

public class WrpZipCode
extends java.lang.Object

This class encapsulates a USPS zip code with its associated state and city. It also provides an interface to store zip code information in memory as an array of WrpZipCode objects.

Creative Commons License Creative Commons License Symbols Unless noted otherwise, all materials available for download from my site are copyrighted by Bill Pringle, and are licensed under a Creative Commons License.

Author:
Bill Pringle

Field Summary
private  java.util.Vector<java.lang.String> city
          a list of cities associated with the zipcode
private  int id
          unique ID from database
private static java.lang.String query
          stored procedure to retrieve zip codes from database
private  java.lang.String state
          the state abbreviation
private  java.lang.String zipcode
          the zipcode
private  WrpZipCode[] zipList
          An array of all zip codes.
 
Constructor Summary
WrpZipCode()
          The default Constructor
WrpZipCode(java.lang.String zipcode)
          Constructor with only zipcode
WrpZipCode(java.lang.String zipcode, java.lang.String state)
          Constructor with state abbreviation
WrpZipCode(java.lang.String zipcode, java.lang.String state, java.lang.String city)
          Constructor with initial state and city combination
WrpZipCode(WrpDb db)
          Constructor that will load the current list of zipcodes.
WrpZipCode(WrpZipCode zc)
          Constructor to clone a zip code object
 
Method Summary
 void addCity(java.lang.String city)
          Add another city for this zipcode.
 int compareTo(WrpZipCode zip)
          Compare this zipcode with another one
 java.util.Vector<java.lang.String> findCities(java.lang.String strZip)
          Get the list of cities associated with the specified zip code.
private  WrpZipCode findLoadingZipCode(java.util.Vector<WrpZipCode> lst, java.lang.String strZipCode)
          Search for zipcode entry in vector.
 WrpZipCode findZipCode(java.lang.String strZip)
          This routine will search for the specified zipcode
 java.util.Vector<java.lang.String> getCities()
          Get the list of cities assigned to this zipcode
 java.lang.String getCity(int loc)
          Get the corresponding city from the list of cities
 int getId()
          Get the unique ID assigned by the database for this zip code.
 int getNumberCities()
          Get the number of possible city names (or abbreviations) for zipcode
 java.lang.String getState()
          Get the state.
 java.lang.String getZipcode()
          Get the zip code.
 WrpZipCode[] getZipList()
          Get array of zipcodes.
 boolean hasCity(java.lang.String city)
          Determine if the specified city is defined for zip code
 void init()
          initialize instance variables
 boolean isCityValid(java.lang.String strZip, java.lang.String strCity)
          Determine if city is valid for a zipcode.
 boolean isStateValid(java.lang.String strZip, java.lang.String strState)
          Determine if zipcode is defined within a state.
 boolean isZipCodeValid(java.lang.String strZip)
          Determine if specified string is a valid zipcode.
 boolean isZipCodeValid(java.lang.String strZip, java.lang.String strState)
          Determine if a zipcode is valid for a state.
 boolean isZipCodeValid(java.lang.String strZip, java.lang.String strState, java.lang.String strCity)
          Determine if city / state / zipcode combination valid
 void loadZipCodes(WrpDb db)
          Load the zip codes from a database into an array.
static void main(java.lang.String[] args)
          Test driver for zip codes.
 void setId(int id)
          Set the unique ID for this zip code.
 void setState(java.lang.String state)
          Set the state.
 void setZipcode(java.lang.String zipcode)
          Set the zip code.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

query

private static final java.lang.String query
stored procedure to retrieve zip codes from database

See Also:
Constant Field Values

id

private int id
unique ID from database


zipcode

private java.lang.String zipcode
the zipcode


state

private java.lang.String state
the state abbreviation


city

private java.util.Vector<java.lang.String> city
a list of cities associated with the zipcode


zipList

private WrpZipCode[] zipList
An array of all zip codes. The list is initially created as a vector, but once all the zip codes have been read, it is converted to an array for speed and lack of overhead.

This list can be built using the loadZipCodes method. The list can then be searched using the findZipCode method

Constructor Detail

WrpZipCode

public WrpZipCode()
The default Constructor


WrpZipCode

public WrpZipCode(java.lang.String zipcode)
Constructor with only zipcode

Parameters:
zipcode - the zipcode

WrpZipCode

public WrpZipCode(java.lang.String zipcode,
                  java.lang.String state)
Constructor with state abbreviation

Parameters:
zipcode - the zipcode
state - the state abbreviation

WrpZipCode

public WrpZipCode(java.lang.String zipcode,
                  java.lang.String state,
                  java.lang.String city)
Constructor with initial state and city combination

Parameters:
zipcode - the zipcode
state - the state abbreviation associated with this zipcode
city - a city associated with this zipcode

WrpZipCode

public WrpZipCode(WrpZipCode zc)
Constructor to clone a zip code object

Parameters:
zc - the zip code to clone

WrpZipCode

public WrpZipCode(WrpDb db)
           throws java.sql.SQLException
Constructor that will load the current list of zipcodes.

Parameters:
db - database connection to zipcodes
Throws:
java.sql.SQLException
Method Detail

compareTo

public int compareTo(WrpZipCode zip)
Compare this zipcode with another one

This method compares the zipcode with the argument zipcode. The fields tested are the zipcode, the state, and the city. (The state should always be the same.)

If this zipcode comes before the other, a negative number is returned. If this zipcode comes after the other, a positive number is returned. If the two zipcodes are identical, a zero is returned.

The method compares the zip code, the state, and any cities. If a difference is found, then the appropriate value is returned. If no differences are found (including the two lists of cities), then zero is returned.

Parameters:
zip - the other zipcode to be compared
Returns:
negative number if the zipcode less than the argument, a positive number if the zipcode is greater than the argument, a zero if the two entries are identical.

getCity

public java.lang.String getCity(int loc)
Get the corresponding city from the list of cities

Parameters:
loc - index of city
Returns:
the name of the city or null if the index was invalid

hasCity

public boolean hasCity(java.lang.String city)
Determine if the specified city is defined for zip code

Parameters:
city - the city name to test for
Returns:
true if city in list of cities, false otherwise

getId

public int getId()
Get the unique ID assigned by the database for this zip code.

Returns:
the id

setId

public void setId(int id)
Set the unique ID for this zip code.

Parameters:
id - the id to set

getZipcode

public java.lang.String getZipcode()
Get the zip code.

Returns:
the zipcode

setZipcode

public void setZipcode(java.lang.String zipcode)
Set the zip code.

Parameters:
zipcode - the zipcode to set

getState

public java.lang.String getState()
Get the state.

Returns:
the state

setState

public void setState(java.lang.String state)
Set the state.

Parameters:
state - the state to set

addCity

public void addCity(java.lang.String city)
Add another city for this zipcode. This method checks to determine if the city is already present to prevent duplicate entries.

Parameters:
city - the city (or abbreviation) to be added

getNumberCities

public int getNumberCities()
Get the number of possible city names (or abbreviations) for zipcode

Returns:
the number of cities or abbreviations that are valid for this zipcode

getCities

public java.util.Vector<java.lang.String> getCities()
Get the list of cities assigned to this zipcode

Returns:
the current list of cities

init

public void init()
initialize instance variables


loadZipCodes

public void loadZipCodes(WrpDb db)
                  throws java.sql.SQLException
Load the zip codes from a database into an array. This method uses the string query to read the current list of zip codes from the database and store them into the vector zipList

The query returns a collection of lines with zipcode, state, and city entries. There will be as many entries for a zip code as there are cities defined for that zip code. Each zip code should only have one state assocateid with it.

Parameters:
db - database connection that contains zipcode definitions
Throws:
java.sql.SQLException

getZipList

public WrpZipCode[] getZipList()
Get array of zipcodes. This method returns the current list of zip codes that was read from the database. If the list wasn't read yet, then it will return null.

This method can be used if the client wants to create some customized searches or lists for zip codes.

Returns:
zipList, which is null if the zipcodes weren't loaded yet

findLoadingZipCode

private WrpZipCode findLoadingZipCode(java.util.Vector<WrpZipCode> lst,
                                      java.lang.String strZipCode)
Search for zipcode entry in vector.

This routine is called when zipcodes are being read from a database. Since the entries are sorted by zipcode, we check the last entry first. If the zipcode matches, we return that entry, but if the zipcode is greater than the one at the end, we return null.

Parameters:
lst - vector containing zipcodes
strZipCode - string containing the zipcode
Returns:
WrpZipCode object for zipcode, or null if not found

findZipCode

public WrpZipCode findZipCode(java.lang.String strZip)
This routine will search for the specified zipcode

This routine will perform a binary search on the array zipList to find the corresponding zipcode.

This method requires the loadZipCodes(WrpDb) method to have been called.

Parameters:
strZip - the desired zipcode
Returns:
the zipcode object if found, or null if not found

findCities

public java.util.Vector<java.lang.String> findCities(java.lang.String strZip)
Get the list of cities associated with the specified zip code. This method searches the list of zip codes for the specified value. If found, the list of cities associated with that zip code is returned. If the zip code isn't found, then null is returned.

This method requires the loadZipCodes(WrpDb) method to have been called.

Parameters:
strZip - the desired zip code
Returns:
a list of cities associated with the zip code, or null if the zip code wasn't found.

isZipCodeValid

public boolean isZipCodeValid(java.lang.String strZip)
Determine if specified string is a valid zipcode.

This method requires the loadZipCodes(WrpDb) method to have been called.

Parameters:
strZip - zipcode string to be validated
Returns:
true is zipcode exists, false otherwise

isZipCodeValid

public boolean isZipCodeValid(java.lang.String strZip,
                              java.lang.String strState)
Determine if a zipcode is valid for a state.

Parameters:
strZip - string with a zipcode
strState - string with a state abbreviation
Returns:
true if zipcode defined within state; false otherwise

isZipCodeValid

public boolean isZipCodeValid(java.lang.String strZip,
                              java.lang.String strState,
                              java.lang.String strCity)
Determine if city / state / zipcode combination valid

This method requires the loadZipCodes(WrpDb) method to have been called.

Parameters:
strZip - the zipcode to be validated
strState - the state abbreviation to be validated
strCity - the city name to be validated
Returns:
true if zipcode defined for city within state; false otherwise

isStateValid

public boolean isStateValid(java.lang.String strZip,
                            java.lang.String strState)
Determine if zipcode is defined within a state. This method assumes that a given zip code is defined within a single state (i.e., a zip code doesn't span more than one state.)

This method requires the loadZipCodes(WrpDb) method to have been called.

Parameters:
strZip - the zipcode to be validated
strState - the state abbreviation to be validated
Returns:
true if zipcode defined within state; false otherwise

isCityValid

public boolean isCityValid(java.lang.String strZip,
                           java.lang.String strCity)
Determine if city is valid for a zipcode.

This routine only compares the city name, not the state. The caller should also validate that the state is valid for the zipcode.

This method requires the loadZipCodes(WrpDb) method to have been called.

Parameters:
strZip - the zipcode to be validated
strCity - the city to be validated
Returns:
true if zipcode includes the city; false otherwise

main

public static void main(java.lang.String[] args)
Test driver for zip codes.

This driver connects to the database, loads the zipcodes, and then lets the user validate city/state/zipcodes

Parameters:
args - not used