citysdk.tourism.client.requests
Class TourismClient

java.lang.Object
  citysdk.tourism.client.requests.TourismClient

All Implemented Interfaces:

java.lang.Cloneable

public class TourismClient
extends java.lang.Object
implements java.lang.Cloneable

Stub used for the CitySDK Tourism API. It abstracts applications from the different requests allowed in the API and returns the correct data objects from such calls. The stub also provides a logging mechanism defaulting to INFO level messages.

Author:

Pedro Cruz

Method Summary

java.util.Set<java.lang.String>	getAvailableResources() Gets all the available resources of a given version for the queried server.
ListPOIS	getByCode(java.lang.String code) Gets all POI-based objects containing the given code
Category	getCategories(ParameterList list) Returns the list of Category available.
Event	getEvent(java.lang.String eventBase, java.lang.String eventId) Returns the description of a given Event.
ListEvent	getEventRelation(java.lang.String id, Term relation) Returns a list of Events with the given relation with the POI identified by id.
ListEvent	getEvents(ParameterList parameterList) Returns a list of Events following the desired parameters.
POI	getGeneric(java.lang.String base, java.lang.String id) Returns a generic object matching the given base and id
PointOfInterest	getPoi(java.lang.String poiBase, java.lang.String poiId) Returns the complete description of a given POI.
ListPointOfInterest	getPoiRelation(java.lang.String id, Term relation) Returns a list of Points of Interest with the given relation with the POI identified by id.
ListPointOfInterest	getPois(ParameterList parameterList) Returns a list of POIs following the desired parameters.
Route	getRoute(java.lang.String routeBase, java.lang.String routeId) Returns the description of a given Route and its POIs.
ListRoute	getRoutes(ParameterList parameterList) Returns a list of Routes following the desired parameters.
ListTag	getTags(ParameterList list) Returns the list of ListTag available.
java.lang.String	getVersion()
boolean	hasAnyResourcesOf(ResourceTerms resource) Checks whether the server has any resources of POIs, Events or Routes in a given version.
boolean	hasResource(ResourceTerms resource) Verifies if the client has a given resource
boolean	hasResourceParameter(ResourceTerms resource, ParameterTerms parameter) Checks whether a given resource is available for the queried server.
void	setLoggingLevel(java.util.logging.Level level) Set the logging level for the logger
void	useVersion(java.lang.String version) Set the version to use by the stub

Methods inherited from class java.lang.Object

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

Method Detail

setLoggingLevel

public void setLoggingLevel(java.util.logging.Level level)

Set the logging level for the logger

Parameters:

level - the wanted level

getVersion

public java.lang.String getVersion()

useVersion

public void useVersion(java.lang.String version)

Set the version to use by the stub

Parameters:

version - the version to use

getAvailableResources

public java.util.Set<java.lang.String> getAvailableResources()
                                                      throws VersionNotAvailableException

Gets all the available resources of a given version for the queried server.

Returns:

a set of resources allowed for the server

Throws:

VersionNotAvailableException - thrown if a previously set version is not available

hasResource

public boolean hasResource(ResourceTerms resource)
                    throws VersionNotAvailableException

Verifies if the client has a given resource

Parameters:

resource - the resource to find

Returns:

true if the resource is present, false otherwise

Throws:

VersionNotAvailableException - thrown if the version is not supported

hasAnyResourcesOf

public boolean hasAnyResourcesOf(ResourceTerms resource)
                          throws VersionNotAvailableException,
                                 InvalidResourceTermException

Checks whether the server has any resources of POIs, Events or Routes in a given version.

Parameters:

resource - the term to search for. It must be RESOURCE_POIS, RESOURCE_EVENTS or RESOURCE_ROUTES, otherwise it will return false.

Returns:

true if the server has any given capacity of the referred term, false otherwise.

Throws:

VersionNotAvailableException - thrown if a previously set version is not available

InvalidResourceTermException - thrown if the resource term is not one of the presented terms

hasResourceParameter

public boolean hasResourceParameter(ResourceTerms resource,
                                    ParameterTerms parameter)
                             throws VersionNotAvailableException

Checks whether a given resource is available for the queried server.

Parameters:

resource - the wanted resource

parameter - a given search parameter.

Returns:

true if available, false otherwise.

Throws:

VersionNotAvailableException - thrown if a previously set version is not available

getPois

public ListPointOfInterest getPois(ParameterList parameterList)
                            throws InvalidParameterException,
                                   java.io.IOException,
                                   ResourceNotAllowedException,
                                   UnknownErrorException,
                                   ServerErrorException,
                                   VersionNotAvailableException

Returns a list of POIs following the desired parameters. If such parameters are not valid terms for a POI, it will throw an InvalidParameterException.

Parameters:

parameterList - the parameters that should be followed.

Returns:

a ListPointOfInterest.

Throws:

InvalidParameterException - thrown if the given parameterList contains invalid terms.

java.io.IOException - thrown in case of socket errors.

ResourceNotAllowedException - thrown if the server does not support POIs listing

UnknownErrorException - thrown in case of unforeseen errors.

ServerErrorException - thrown if the server returns a code different from HTTP 200 OK.

VersionNotAvailableException - thrown if a previously set version is not available

getEvents

public ListEvent getEvents(ParameterList parameterList)
                    throws InvalidParameterException,
                           java.io.IOException,
                           ResourceNotAllowedException,
                           UnknownErrorException,
                           ServerErrorException,
                           VersionNotAvailableException

Returns a list of Events following the desired parameters. If such parameters are not valid queries for an Event, it will throw and InvalidParameterException.

Parameters:

parameterList - the parameters that should be followed.

Returns:

a ListEvent.

Throws:

InvalidParameterException - thrown if the given parameterList contains invalid terms.

java.io.IOException - thrown in case of socket errors.

ResourceNotAllowedException - thrown if the server does not support events listing

UnknownErrorException - thrown in case of unforeseen errors.

ServerErrorException - thrown if the server returns a code different from HTTP 200 OK.

VersionNotAvailableException - thrown if a previously set version is not available

getRoutes

public ListRoute getRoutes(ParameterList parameterList)
                    throws InvalidParameterException,
                           java.io.IOException,
                           ResourceNotAllowedException,
                           UnknownErrorException,
                           ServerErrorException,
                           VersionNotAvailableException

Returns a list of Routes following the desired parameters. If such parameters are not valid queries for a Route, it will throw and InvalidParameterException.

Parameters:

parameterList - the parameters that should be followed.

Returns:

a ListRoute.

Throws:

InvalidParameterException - thrown if the given parameterList contains invalid terms.

java.io.IOException - thrown in case of socket errors.

ResourceNotAllowedException - thrown if the server does not support routes listing

UnknownErrorException - thrown in case of unforeseen errors.

ServerErrorException - thrown if the server returns a code different from HTTP 200 OK.

VersionNotAvailableException - thrown if a previously set version is not available

getCategories

public Category getCategories(ParameterList list)
                       throws java.io.IOException,
                              UnknownErrorException,
                              InvalidParameterTermException,
                              ServerErrorException,
                              ResourceNotAllowedException,
                              VersionNotAvailableException

Returns the list of Category available. The term should be either one of the following:

• ParameterTerms.POIS;
• ParameterTerms.EVENTS;
• ParameterTerms.ROUTES.

Parameters:

list - the parameters that should be followed. It should contain a list with one of the above terms specified

Returns:

a Category.

Throws:

java.io.IOException - thrown in case of socket errors.

UnknownErrorException - thrown in case of unforeseen errors.

InvalidParameterTermException - thrown if the term is not one of aforementioned valid terms.

ServerErrorException - thrown if the server returns a code different from HTTP 200 OK.

ResourceNotAllowedException - thrown if the server does not support category listing.

VersionNotAvailableException - thrown if a previously set version is not available.

getTags

public ListTag getTags(ParameterList list)
                throws java.io.IOException,
                       UnknownErrorException,
                       ServerErrorException,
                       InvalidParameterTermException,
                       ResourceNotAllowedException,
                       VersionNotAvailableException

Returns the list of ListTag available. The term should be either one of the following:

• ParameterTerms.POIS;
• ParameterTerms.EVENTS;
• ParameterTerms.ROUTES.

Parameters:

list - the parameters that should be followed. It should contain a list with one of the above terms specified

Returns:

a ListTag.

Throws:

java.io.IOException - thrown in case of socket errors.

UnknownErrorException - thrown in case of unforeseen errors.

InvalidParameterTermException - thrown if the term is not one of aforementioned valid terms.

ServerErrorException - thrown if the server returns a code different from HTTP 200 OK.

ResourceNotAllowedException - thrown if the server does not support tags listing.

VersionNotAvailableException - thrown if a previously set version is not available.

getPoi

public PointOfInterest getPoi(java.lang.String poiBase,
                              java.lang.String poiId)
                       throws java.io.IOException,
                              UnknownErrorException,
                              ServerErrorException

Returns the complete description of a given POI.

Parameters:

poiBase - the base URL of the POI.

poiId - the ID of the POI.

Returns:

a PointOfInterest containing a complete description of the POI.

Throws:

java.io.IOException - thrown in case of socket errors.

UnknownErrorException - thrown in case of unforeseen errors.

ServerErrorException - thrown if the server returns a code different from HTTP 200 OK.

getEvent

public Event getEvent(java.lang.String eventBase,
                      java.lang.String eventId)
               throws java.io.IOException,
                      UnknownErrorException,
                      ServerErrorException

Returns the description of a given Event.

Parameters:

eventBase - the base URL of the Event.

eventId - the ID of the Event.

Returns:

an Event containing a description of the Event.

Throws:

java.io.IOException - thrown in case of socket errors.

UnknownErrorException - thrown in case of unforeseen errors.

ServerErrorException - thrown if the server returns a code different from HTTP 200 OK.

getRoute

public Route getRoute(java.lang.String routeBase,
                      java.lang.String routeId)
               throws java.io.IOException,
                      UnknownErrorException,
                      ServerErrorException

Returns the description of a given Route and its POIs.

Parameters:

routeBase - the base URL of the Route.

routeId - the ID of the Route.

Returns:

a Route containing a description of the Route.

Throws:

java.io.IOException - thrown in case of socket errors.

UnknownErrorException - thrown in case of unforeseen errors.

ServerErrorException - thrown if the server returns a code different from HTTP 200 OK.

getGeneric

public POI getGeneric(java.lang.String base,
                      java.lang.String id)
               throws java.io.IOException,
                      UnknownErrorException,
                      ServerErrorException

Returns a generic object matching the given base and id

Parameters:

base - the base URI of the POI object

id - the id of the POI object

Returns:

a generic POI object

Throws:

java.io.IOException - thrown in case of socket errors.

UnknownErrorException - thrown in case of unforeseen errors.

ServerErrorException - thrown if the server returns a code different from HTTP 200 OK.

getPoiRelation

public ListPointOfInterest getPoiRelation(java.lang.String id,
                                          Term relation)
                                   throws VersionNotAvailableException,
                                          InvalidValueException,
                                          ResourceNotAllowedException,
                                          java.io.IOException,
                                          ServerErrorException,
                                          UnknownErrorException

Returns a list of Points of Interest with the given relation with the POI identified by id. The relation should be either:

• Term.LINK_TERM_PARENT;
• Term.LINK_TERM_CHILD.

Parameters:

id - the id of the poi to find the relations

relation - the wanted relation with the poi

Returns:

a ListPointOfInterest

Throws:

java.io.IOException - thrown in case of socket errors.

ServerErrorException - thrown if the server returns a code different from HTTP 200 OK.

UnknownErrorException - thrown in case of unforeseen errors.

VersionNotAvailableException - thrown if a previously set version is not available

InvalidValueException - thrown if the relation is not one of the presented values

ResourceNotAllowedException - thrown if the server does not support POIs relationships

getEventRelation

public ListEvent getEventRelation(java.lang.String id,
                                  Term relation)
                           throws InvalidParameterTermException,
                                  java.io.IOException,
                                  ServerErrorException,
                                  VersionNotAvailableException,
                                  UnknownErrorException,
                                  InvalidValueException,
                                  ResourceNotAllowedException

Returns a list of Events with the given relation with the POI identified by id. The relation should be either:

• Term.LINK_TERM_PARENT;
• Term.LINK_TERM_CHILD.

Parameters:

id - the id of the event to find the relations

relation - the wanted relation with the related event

Returns:

a ListEvent

Throws:

java.io.IOException - thrown in case of socket errors.

ServerErrorException - thrown if the server returns a code different from HTTP 200 OK.

UnknownErrorException - thrown in case of unforeseen errors.

VersionNotAvailableException - thrown if a previously set version is not available

InvalidValueException - thrown if the relation is not one of the presented values

ResourceNotAllowedException - thrown if the server does not support event relations

InvalidParameterTermException

getByCode

public ListPOIS getByCode(java.lang.String code)
                   throws ResourceNotAllowedException,
                          VersionNotAvailableException,
                          java.io.IOException,
                          ServerErrorException,
                          UnknownErrorException

Gets all POI-based objects containing the given code

Parameters:

code - a link to search for POI-based objects

Returns:

all POI-based objects matching the code

Throws:

ResourceNotAllowedException - thrown if search by code is not available

VersionNotAvailableException - thrown if the given version is not available

java.io.IOException - thrown in case of socket errors

ServerErrorException - thrown in case of a server error (returning code other than HTTP 200 OK)

UnknownErrorException - thrown in case of unforseen errors