Location¶

public class Location implements Serializable, Listable ¶

This object stores only the city, region, and country ID values, so it acts as a pointer to the more detailed information for the location in each City, Region, and Country’s database entries or network information. No instance of this class should have countryId, regionId, and cityId all equal to NOWHERE. This should only be possible by mis-using the JSON constructor or by supplying -1 as an ID. Neither should ever be done.

Location
                     (IDs only)
                     /                            /                             /                              /                       Place (Abstract)    DatabaseLocation (Abstract)
          (Full Info)                   (IDs)
            /  |                    /                 /   |             NearLocation  FromLocation
      City  Region  Country  (Wrappers for DatabaseLocation)
   (Specific cases of Place)

Fields¶

CITY¶

public static final int CITY¶

Represents a type of Location that has a city defined.

See also: Location.getType()

COUNTRY¶

public static final int COUNTRY¶

Represents a type of Location that has only a country defined.

See also: Location.getType()

NOWHERE¶

protected static final int NOWHERE¶: These constants are used to identify the type of location being stored. See the documentation for getType for more. NOWHERE is protected because it should never be used by clients. It is only for subclasses to denote empty IDs. Creating locations with empty IDs should be handled by subclass constructors or methods.

REGION¶

public static final int REGION¶

Represents a type of Location that has a region defined but not a city.

See also: Location.getType()

URL_NULL_ID¶

public static final int URL_NULL_ID¶: The value to be transmitted to the API in place of a missing country, region, or city ID

cityId¶

public long cityId¶

countryId¶

public long countryId¶: These instance fields store the IDs of the city, region, and country defining the location They can be private because a plain Location object should not need to be stored in the database.

locationName¶

public String locationName¶: This is is only used for other searching in org.codethechange.culturemesh.FindNetworkActivity. Do not use this field anywhere else.

regionId¶

public long regionId¶

Constructors¶

Location¶

public Location(long countryId, long regionId, long cityId)¶

Initializes ID instance fields using the provided IDs

Parameters:	countryId – ID of country regionId – ID of region cityId – ID of city

Location¶

public Location(JSONObject json)¶

Initializes ID instance fields using the provided JSON object If present, the values of the keys city_id, region_id, and country_id will be used automatically. Depending on the presence of those keys, the value of the key id will be used to fill the instance field for the JSON type. See getJsonType for more. This constructor is designed to be used when creating Places. Precondition: The JSON must be validly formatted, with examples in API.java

Parameters:	json – JSON object containing the country, region, and city IDs
Throws:	JSONException – May be thrown if the JSON is improperly formatted

Location¶

public Location(JSONObject json, String cityIdKey, String regionIdKey, String countryIdKey)¶

Initializes ID instance fields using the provided JSON object. The keys extracted are provided as parameters, but those keys need not exist in the JSON. Any missing keys will be treated as if the location does not have such a geographic identifier. This may produce an invalid location, and the JSON is followed blindly. Precondition: JSON must describe a valid location

Parameters:	json – JSON that describes the location to create cityIdKey – The key that, if present in the JSON, has a value of the ID of the city regionIdKey – The key that, if present in the JSON, has a value of the ID of the region countryIdKey – The key that, if present in the JSON, has a value of the ID of the country
Throws:	JSONException – May be thrown in the case of an invalid JSON

Location¶

public Location()¶: Empty constructor for database use only. This should never be called by our code.

Methods¶

getCityId¶

public long getCityId()¶

Getter for the city ID, which may return NOWHERE, so hasCityId should be used to check first

Returns:	The city ID

getCountryId¶

public long getCountryId()¶

Getter for the country ID, which may return NOWHERE, so hasCountryId should be used to check first

Returns:	The country ID

getDatabaseId¶

protected long getDatabaseId()¶

Find the ID that should be used as the PrimaryKey for a database. It is the ID of the most specific geographical descriptor with an ID that is not NOWHERE. WARNING: The returned ID is NOT guaranteed to be unique

Returns:	ID for use as `PrimaryKey` in a database

getFromLocation¶

public FromLocation getFromLocation()¶

Transform a Location into a FromLocation

Returns:	A `FromLocation` with the same IDs as the `Location` object whose method was called

getListableName¶

public String getListableName()¶

Get a UI-ready name for the Location

Returns:	Name for the Location that is suitable for display to the user. Abbreviated to be a maximum of `Listable.MAX_CHARS` characters long.

getNearLocation¶

public NearLocation getNearLocation()¶

Transform a Location into a NearLocation

Returns:	A `NearLocation` with the same IDs as the `Location` object whose method was called

getRegionId¶

public long getRegionId()¶

Getter for the region ID, which may return NOWHERE, so hasRegionId should be used to check first

Returns:	The region ID

getType¶

public int getType()¶

The most specific ID that is not NOWHERE determines the location’s type, even if more general IDs are NOWHERE. For example, if regionId = 0 and countryId = cityId = NOWHERE, the type would be REGION

Returns:	Location’s type as `CITY`, `REGION`, or `COUNTRY`

hasCityId¶

public boolean hasCityId()¶

Check if the city ID is specified (i.e. not NOWHERE)

Returns:	`true` if the city ID is specified, `false` otherwise

hasCountryId¶

public boolean hasCountryId()¶

Check if the country ID is specified (i.e. not NOWHERE)

Returns:	`true` if the country ID is specified, `false` otherwise

hasRegionId¶

public boolean hasRegionId()¶

Check if the region ID is specified (i.e. not NOWHERE)

Returns:	`true` if the region ID is specified, `false` otherwise

toString¶

public String toString()¶

Represent the object as a string suitable for debugging, but not for display to user.

Returns:	String representation of the form `Class[var=value, var=value, var=value, ...]`

urlParam¶

public String urlParam()¶

Represent the Location in a form suitable for use as the value of a key passed in a URL parameter to the API. Specifically, it returns the country, region, and city IDs separated by commas and in that order. The commas are escaped with the UTF-8 scheme and any missing IDs are replaced with the Location.URL_NULL_ID constant, which is understood by the API as signifying null.

Returns:	An API-compatible representation suitable for use as the value in a URL parameter