This is mainly a synchronous library, so in Java-based systems, such as Android, always bear in mind to make
any remote calls in a separate thread so not to block the UI thread. You may download the .jar file or the source code here.

Documentation

For further information please read the documentation of the Java library found here.

Examples

The library resides on three main classes: the TourismClientFactory, visits a given URL, and generates a TourismClient stub with the available server’s capacities. From the TourismClient stub, we can then query the server for single or list of POI-based data. Finally, the DataReader exists to further parse and get details from the returned data more switfly.

Making a TourismClient Stub

To generate a TourismClient stub, one uses the TourismClientFactory by passing the home URL. If the URL is a CitySDK-powered tourism server then the factory class will generate a TourismClient stub. Such URL is visited only once and further calls on the factory with the same URL will just generate another (equal) stub without calling the URL again. If a different URL is passed then the mentioned procedure is repeated.
An example of using the TourismClientFactory class is shown below:

import java.io.IOException;
import citysdk.tourism.client.exceptions.ServerErrorException;
import citysdk.tourism.client.exceptions.UnknownErrorException;
import citysdk.tourism.client.requests.TourismClient;
import citysdk.tourism.client.requests.TourismClientFactory;

public TourismClient getClientWithUrl(String url)
	throws IOException, UnknownErrorException, ServerErrorException {
	TourismClient client = null;
		// get a factory instance (singleton)
		TourismClientFactory factory = TourismClientFactory.getInstance();

		// get a client stub
		client = factory.getClient(url);
	return client;
};

Using the TourismClient Stub

The TourismClient stub allows to call and instantiate the POI objects (like POIs, Events, Routes, Categories and Tags) and its listings. Some examples are shown below:

Getting a List of POI-based Objects

A list of POI-based objects is requested through the use of a parameter list which contains the query parameters to make a given request. An example of getting a list of POIs is shown below:

import java.io.IOException;
import citysdk.tourism.client.exceptions.InvalidParameterException;
import citysdk.tourism.client.exceptions.InvalidValueException;
import citysdk.tourism.client.exceptions.ResourceNotAllowedException;
import citysdk.tourism.client.exceptions.ServerErrorException;
import citysdk.tourism.client.exceptions.UnknownErrorException;
import citysdk.tourism.client.exceptions.VersionNotAvailableException;
import citysdk.tourism.client.requests.TourismClient;
import citysdk.tourism.client.requests.TourismClientFactory;
import citysdk.tourism.client.requests.Parameter;
import citysdk.tourism.client.requests.ParameterList;
import citysdk.tourism.client.terms.ParameterTerms;
import citysdk.tourism.client.poi.lists.ListEvent;

public ListEvent getListEvents(ParameterList parameterList, String url) 
	throws InvalidParameterException, IOException, ResourceNotAllowedException,
		   UnknownErrorException, ServerErrorException, VersionNotAvailableException,
		   InvalidValueException {
	ListEvent list = null;

	// get a factory instance
	TourismClientFactory factory = TourismClientFactory.getInstance();

	// get a client for the given URL
	TourismClient client = factory.getClient(url);
	// set it to use the version 1.0
	client.useVersion("1.0");

	// get a list of events
	list = client.getEvents(parameterList);

	return list;
}
...
String uri = "http://some-url.com/";
// make the parameter list and make the request
List<String> category = new ArrayList<String>();
category.add("Music");
category.add("Live");

ParameterList params = new ParameterList();
params.add(new Parameter(ParameterTerms.CATEGORY, category));
params.add(new Parameter(ParameterTerms.TAG, "rock"));

// do bear in mind to catch all the exceptions
ListEvent eventList = getListEvents(params, uri);
...;

Getting a list of Categories or Tags

A list of Categories can be requested by specifying which list is needed (POIs, Events or Routes). Getting a list of Tags will be similar.
An example is shown below:

import java.io.IOException;
import citysdk.tourism.client.exceptions.InvalidParameterTermException;
import citysdk.tourism.client.exceptions.InvalidParameterException;
import citysdk.tourism.client.exceptions.InvalidValueException;
import citysdk.tourism.client.exceptions.ResourceNotAllowedException;
import citysdk.tourism.client.exceptions.ServerErrorException;
import citysdk.tourism.client.exceptions.UnknownErrorException;
import citysdk.tourism.client.exceptions.VersionNotAvailableException;
import citysdk.tourism.client.requests.TourismClient;
import citysdk.tourism.client.requests.TourismClientFactory;
import citysdk.tourism.client.requests.ParameterList;
import citysdk.tourism.client.poi.single.Category;

public Category getCategories(ParameterList list, String url)
	 throws IOException, UnknownErrorException, InvalidParameterTermException, 
			ServerErrorException, ResourceNotAllowedException, 
			VersionNotAvailableException, InvalidParameterException,
 			InvalidValueException {
	Category categories = null;

	// get a factory instance
	TourismClientFactory factory = TourismClientFactory.getInstance();
	// get a client for the given URL
	TourismClient client = factory.getClient(url)
	// set it to use the version 1.0
	client.useVersion("1.0");

	// get a list of categories
	categories = client.getCategories(list);

	return categories;
}

...
String uri = "http://some-url.com/";
// get a list of categories for POIs
ParameterList list = new ParameterList();
list.add(new Parameter(ParameterTerms.LIST, ParameterTerms.POIS.getTerm()));
Category category = getCategories(list, uri);
...;

Getting a Single POI-based Object

Getting a single POI-based object (like POIs, Events or Routes) can be made by using the base and the id of such object like shown below:

import java.io.IOException;
import citysdk.tourism.client.exceptions.InvalidParameterException;
import citysdk.tourism.client.exceptions.InvalidValueException;
import citysdk.tourism.client.exceptions.ResourceNotAllowedException;
import citysdk.tourism.client.exceptions.ServerErrorException;
import citysdk.tourism.client.exceptions.UnknownErrorException;
import citysdk.tourism.client.exceptions.VersionNotAvailableException;
import citysdk.tourism.client.requests.TourismClient;
import citysdk.tourism.client.requests.TourismClientFactory;
import citysdk.tourism.client.requests.ParameterList;
import citysdk.tourism.client.poi.single.Event;
 
public PointOfInterest getPoiWithId(String base, String id, String url) 
    throws InvalidParameterException, IOException, ResourceNotAllowedException,
           UnknownErrorException, ServerErrorException, VersionNotAvailableException,
           InvalidValueException {
    PointOfInterest poi = null;
 
    // get a factory instance
    TourismClientFactory factory = TourismClientFactory.getInstance();
 
    // get a client for the given URL
    TourismClient client = factory.getClient(url)
    // set it to use the version 1.0
    client.useVersion("1.0");
 
    // get a poi
    poi = client.getPoi(base, id);
 
    return poi;
}
 
...
String uri = "http://some-url.com/";
ListPointOfInterest list = ...; // previously got poi list
PointOfInterest poi = list.get(0);
poi = getPoiWithId(poi.getBase(), poi.getId(), uri);
...

Using the DataReader on returned data

The DataReader is used to parse the objects returned by the methods of TourismClient stub. This class allows to parse any type of SINGLE POI-based object and return the desired value. Some examples are shown next.

import citysdk.tourism.client.parser.DataReader;
import citysdk.tourism.client.parser.data.ImageContent;
import citysdk.tourism.client.parser.data.PointContent;
import citysdk.tourism.client.requests.ParameterList;
import citysdk.tourism.client.poi.lists.ListPOI;
import citysdk.tourism.client.poi.single.POI;
import citysdk.tourism.client.terms.Term;
 
public void parseItems(POIS<POI> poi) {
    String label = null;
    String description = null;
    String thumbnail = null;
    String image = null;
 
    // define the default language to be used, in case the wanted language
    // does not exist. The default language - if this method is not called - is en_GB.
    DataReader.setDefaultLocale(new Locale("en","GB"));
 
    // get the default locale
    Locale locale = new Locale("pt", "PT");
 
    for(int i = 0; i < poi.size(); i++) {
    // go through the list of objects
    POI item = poi.get(i);
 
    // get the primary label in PT language
    label = DataReader.getLabel(item, Term.LABEL_TERM_PRIMARY, locale);
 
    // get a description in PT language
    description = DataReader.getDescription(item, locale);
 
    // get a thumbnail (URI or base-64)
    List<ImageContent> img = DataReader.getThumbnails(item);
    ImageContent imgContent = null;
    if(img.size() > 0) {
        imgContent = img.get(0);
        thumbnail = imgContent.getContent();
    }
 
    // get an image (always a URI)
    List<ImageContent> imgUri = DataReader.getImagesUri(item);
    if(imgUri.size() > 0)
        image = imgUri.get(0).getContent();
 
    // print the values
    System.out.println("LABEL: " + label);
    System.out.println("DESCRIPTION: " + description);
    if(imgContent != null) {
        System.out.println("THUMBNAIL (URI?: " + imgContent.hasImgUri() + ")" + 
        ";(BYTE-CODE?: " + imgContent.hasImgByteCode() + ") : " + thumbnail);
    } else {
        System.out.println("THUMBNAIL: " + thumbnail);
    }
 
        System.out.println("IMAGE: " + image);
    }
}
 
...
// get a list from the TourismClient stub (as previously shown)
ListEvent list = ...; 
 
// parse its values
parseItems(list);
...