winterwell.jgeoplanet
Class PlaceCollection

java.lang.Object
  winterwell.jgeoplanet.GeoPlanetResource
      winterwell.jgeoplanet.PlaceCollection

public class PlaceCollection
extends GeoPlanetResource

A collection of Place objects.

A PlaceCollection represents a potential collection of places rather than the collection of places themselves.

Use get() and friends to get hold of the actual Places involved.

PlaceCollection returns Places in long form by default. Use shortForm(boolean) to change this behaviour.

Author:

Joe Halliwell

Method Summary

java.util.List<Place>	get() Get all places in this collection.
Place	get(int index) Get a specific place from this collection.
java.util.List<Place>	get(int start, int count) Get a list of (some of) the places contained in this collection.
PlaceType	getType() If this collection is filtered by place type, return that type otherwise return null.
boolean	isShortForm()
PlaceCollection	shortForm(boolean useShortForm) Return short form places from this query.
int	size() Returns the total number of places in this collection if a get() has occurred, or -1 to indicate that no get has occurred.
PlaceCollection	type(PlaceType type) Set the type filter.
PlaceCollection	type(java.lang.String placeTypeName) Convenience wrapper for type(PlaceType).

Methods inherited from class winterwell.jgeoplanet.GeoPlanetResource

getClient

Methods inherited from class java.lang.Object

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

Method Detail

type

public PlaceCollection type(PlaceType type)

Set the type filter.

May be null to unset the type. Example usage:

 Place earth = g.getPlace(1);
 PlaceType country = g.getPlaceType("Country");
 List countries = earth.getChildren().type(country).get();
 

Parameters:

type - The place type to filter on. May be null to unset the type.

Returns:

a version of this collection filtered by the specified type.

type

public PlaceCollection type(java.lang.String placeTypeName)
                     throws InvalidPlaceType

Convenience wrapper for type(PlaceType).

Valid place types names include "County", "Region", "Town" and "Ward"

Parameters:

placeTypeName - the name of a place type. Must be valid.

Returns:

a version of this collection filtered by the specified type.

Throws:

InvalidPlaceType - if the place type is invalid

See Also:

type(PlaceType)

getType

public PlaceType getType()

If this collection is filtered by place type, return that type otherwise return null.

Returns:

the place type filter

shortForm

public PlaceCollection shortForm(boolean useShortForm)

Return short form places from this query. The default is to use long form.

Parameters:

useShortForm -

See Also:

isShortForm()

isShortForm

public boolean isShortForm()

Returns:

true if this place collection will return short form Places; false otherwise

size

public int size()

Returns the total number of places in this collection if a get() has occurred, or -1 to indicate that no get has occurred.

Returns:

the total number of place in this collection if known, or -1

get

public java.util.List<Place> get(int start,
                                 int count)
                          throws GeoPlanetException

Get a list of (some of) the places contained in this collection. Requires network access. Returns an empty list if no results were found.

Parameters:

start - The first result to get indexed from 0

count - The maximum number of results to return. Zero (0) returns all results.

Throws:

GeoPlanetException - for general errors

get

public java.util.List<Place> get()
                          throws GeoPlanetException

Get all places in this collection. Cosmetic method calling get(0,0). Requires network access.

Throws:

GeoPlanetException - for general errors

get

public Place get(int index)
          throws GeoPlanetException

Get a specific place from this collection. Cosmetic method calling get(index, 1).get(0) Not usually used with index != 0. Requires network access.

Throws:

GeoPlanetException - for general errors

java.lang.ArrayIndexOutOfBoundsException - for invalid indices