Package org.sellcom.geotemporal.geography

Class GeoRegion

java.lang.Object

org.sellcom.geotemporal.geography.GeoRegion

public class GeoRegion
extends Object

Representation of a specific geographical or political region.

Structure of a GeoRegion

Every region is defined by a country code and up to five codes of administrative units at different subdivision levels. The overall region code is composed of the individual codes separated by a comma.

Regions are strictly hierarchical, however the administrative units at some subdivision levels may be skipped. This situation can be found in Germany, for instance, where the subdivision level of "governmental districts" (orig. "Regierungsbezirke") is defined only in some of the "federal states" (orig. "Bundesländer").

Predefined GeoRegions

Region codes defined by this library can be found in the StandardGeoRegions class and its inner classes. Custom-defined region codes shall be compatible with these codes.

Default GeoRegion

Similarly to Locale, this class defines a default region. The default region is set at class loading time from the "user.georegion" system property. If the property is not defined or if its value is empty, a qualified guess of the default region is made from the default locale. If the qualified guess fails, a GeoRegionException is thrown. The default region can be changed at any time using the setDefault(GeoRegion) method.

Since:

1.0

Field Summary

Fields

Modifier and Type	Field	Description
static GeoRegion	ROOT	The root region.

Constructor Summary

Constructors

Constructor	Description
GeoRegion(String countryCode)	Creates a region for the given country code.
GeoRegion(String countryCode, String level1SubdivisionCode)	Creates a region for the given country code and the codes at the 1st subdivision level.
GeoRegion(String countryCode, String level1SubdivisionCode, String level2SubdivisionCode)	Creates a region for the given country code and the codes at the 1st and 2nd subdivision levels.
GeoRegion(String countryCode, String level1SubdivisionCode, String level2SubdivisionCode, String level3SubdivisionCode)	Creates a region for the given country code and the codes at the 1st to 3rd subdivision levels.
GeoRegion(String countryCode, String level1SubdivisionCode, String level2SubdivisionCode, String level3SubdivisionCode, String level4SubdivisionCode)	Creates a region for the given country code and the codes at the 1st to 4th subdivision levels.
GeoRegion(String countryCode, String level1SubdivisionCode, String level2SubdivisionCode, String level3SubdivisionCode, String level4SubdivisionCode, String level5SubdivisionCode)	Creates a region for the given country code and the codes at the 1st to 5th subdivision levels.

Method Summary

Modifier and Type	Method	Description
GeoRegion	atLevel(int level)	Returns this region limited to the given administrative level.
boolean	equals(Object other)
String	getCode()	Return the overall code of this region.
String	getCountryCode()	Return the country code of this region.
static GeoRegion	getDefault()	Returns the default region.
GeoRegion	getParent()	Returns the immediate parent of this region.
int	hashCode()
static GeoRegion	parse(String code)	Returns a region corresponding to the given code.
static void	setDefault(GeoRegion region)	Sets the default region.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ROOT

public static final GeoRegion ROOT

The root region.

Since:

1.0

Constructor Detail

GeoRegion

public GeoRegion(String countryCode)

Creates a region for the given country code.

Throws:

IllegalArgumentException - if countryCode is null

Since:

1.0

GeoRegion

public GeoRegion(String countryCode,
                 String level1SubdivisionCode)

Creates a region for the given country code and the codes at the 1st subdivision level.

Throws:

IllegalArgumentException - if countryCode is null

IllegalArgumentException - if level1SubdivisionCode is null

Since:

1.0

GeoRegion

public GeoRegion(String countryCode,
                 String level1SubdivisionCode,
                 String level2SubdivisionCode)

Creates a region for the given country code and the codes at the 1st and 2nd subdivision levels.

Throws:

IllegalArgumentException - if countryCode is null

IllegalArgumentException - if level1SubdivisionCode is null

IllegalArgumentException - if level2SubdivisionCode is null

Since:

1.0

GeoRegion

public GeoRegion(String countryCode,
                 String level1SubdivisionCode,
                 String level2SubdivisionCode,
                 String level3SubdivisionCode)

Creates a region for the given country code and the codes at the 1st to 3rd subdivision levels.

Throws:

IllegalArgumentException - if countryCode is null

IllegalArgumentException - if level1SubdivisionCode is null

IllegalArgumentException - if level2SubdivisionCode is null

IllegalArgumentException - if level3SubdivisionCode is null

Since:

1.0

GeoRegion

public GeoRegion(String countryCode,
                 String level1SubdivisionCode,
                 String level2SubdivisionCode,
                 String level3SubdivisionCode,
                 String level4SubdivisionCode)

Creates a region for the given country code and the codes at the 1st to 4th subdivision levels.

Throws:

IllegalArgumentException - if countryCode is null

IllegalArgumentException - if level1SubdivisionCode is null

IllegalArgumentException - if level2SubdivisionCode is null

IllegalArgumentException - if level3SubdivisionCode is null

IllegalArgumentException - if level4SubdivisionCode is null

Since:

1.0

GeoRegion

public GeoRegion(String countryCode,
                 String level1SubdivisionCode,
                 String level2SubdivisionCode,
                 String level3SubdivisionCode,
                 String level4SubdivisionCode,
                 String level5SubdivisionCode)

Creates a region for the given country code and the codes at the 1st to 5th subdivision levels.

Throws:

IllegalArgumentException - if countryCode is null

IllegalArgumentException - if level1SubdivisionCode is null

IllegalArgumentException - if level2SubdivisionCode is null

IllegalArgumentException - if level3SubdivisionCode is null

IllegalArgumentException - if level4SubdivisionCode is null

IllegalArgumentException - if level5SubdivisionCode is null

Since:

1.0

Method Detail

atLevel

public GeoRegion atLevel(int level)

Returns this region limited to the given administrative level.

Throws:

IllegalArgumentException - if level is negative

IllegalArgumentException - if level is greater than 5

Since:

1.0

equals

public boolean equals(Object other)

Overrides:

equals in class Object

getCode

public String getCode()

Return the overall code of this region.

Since:

1.0

getCountryCode

public String getCountryCode()

Return the country code of this region.

Since:

1.0

getDefault

public static GeoRegion getDefault()

Returns the default region.

Since:

1.0

getParent

public GeoRegion getParent()

Returns the immediate parent of this region.

Since:

1.0

hashCode

public int hashCode()

Overrides:

hashCode in class Object

parse

public static GeoRegion parse(String code)

Returns a region corresponding to the given code.

Throws:

IllegalArgumentException - if code is null

GeoRegionParseException - if the region code cannot be parsed

Since:

1.0

setDefault

public static void setDefault(GeoRegion region)

Sets the default region.

Since:

1.0

toString

public String toString()

Overrides:

toString in class Object