xyz.thepathfinder.android

Class Cluster

java.lang.Object

xyz.thepathfinder.android.Listenable<E,JsonObject>

xyz.thepathfinder.android.Model<T,E>

xyz.thepathfinder.android.SubscribableModel<T,E>

xyz.thepathfinder.android.SubscribableCrudModel<Cluster,ClusterListener>

xyz.thepathfinder.android.Cluster

public class Cluster
extends SubscribableCrudModel<Cluster,ClusterListener>

A cluster represents a set of commodities, sub-clusters, and transports. A cluster is used to group related models. That relation could be geographic type of transportation, or anything else. To sync the cluster with a cluster on the Pathfinder server use the SubscribableCrudModel.connect() method.

Note, that clusters, as are all models, are implemented as singletons. If a cluster already exists with the same path it will be returned, not a new object. Use getInstance(java.lang.String, xyz.thepathfinder.android.PathfinderServices) to retrieve an cluster object.

See Also:

Commodity, ClusterListener, Transport

Field Summary

Fields

Modifier and Type	Field and Description
private Map<String,Commodity>	commodities Maps a path in the form of a string to the commodities directly under this cluster
private static org.slf4j.Logger	logger Logs actions performed by the class.
private List<Route>	routes List of routes for this cluster.
private Map<String,Cluster>	subclusters Maps a path in the form of a string to the sub-clusters directly under this cluster
private Map<String,Transport>	transports Maps a path in the form of a string to the transports directly under this cluster

Constructor Summary

Constructors

Modifier	Constructor and Description
private	Cluster(String path, PathfinderServices services) Constructor for a cluster object.

Method Summary

Modifier and Type	Method and Description
protected void	addCommodity(Commodity commodity) Adds a commodity to this cluster's list of available commodities.
protected void	addTransport(Transport transport) Adds a transport to this cluster's list of available transports.
private static boolean	checkClusterFields(JsonObject clusterJson) Checks the json object for all the required fields of a cluster object.
Commodity	createCommodity(double startLatitude, double startLongitude, double endLatitude, double endLongitude, CommodityStatus status, JsonObject metadata) Creates a commodity under this cluster on the pathfinder server.
private Commodity	createCommodity(JsonObject commodityJson) Creates a commodity with a values specified in the JSON object.
Cluster	createSubcluster(String name) Creates a subcluster under this cluster on the pathfinder server.
Transport	createTransport(double latitude, double longitude, TransportStatus status, JsonObject metadata) Creates a transport under this cluster on the pathfinder server.
protected JsonObject	createValueJson() Returns the value used in create request to the Pathfinder server
Collection<Commodity>	getCommodities() Returns an immutable collection of this cluster's commodities.
Map<String,Commodity>	getCommoditiesMap() Returns an immutable map of this cluster's commodities.
Commodity	getCommodity(String path) Returns a commodity directly under this cluster by its path.
protected static Cluster	getInstance(JsonObject clusterJson, PathfinderServices services) Returns an instance of cluster object based on the path in clusterJson.
protected static Cluster	getInstance(String path, PathfinderServices services) Returns an instance of cluster object based on the path parameter.
private static String	getPath(JsonObject clusterJson) Returns the path as a string from a JSON object formatted as cluster.
Collection<Route>	getRoutes() Returns an immutable collection of this cluster's routes.
Cluster	getSubcluster(String path) Returns a direct descendant subcluster by its path.
Collection<Cluster>	getSubclusters() Returns an immutable collection of this cluster's direct subclusters.
Map<String,Cluster>	getSubclustersMap() Returns an immutable map of this cluster's direct subclusters.
private String	getSubmodelPath(JsonObject json) Returns the path name of a JSON Model.
protected Cluster	getThis() Returns the current object represented by this.
Transport	getTransport(String path) Returns a transport directly under this cluster by its path.
Collection<Transport>	getTransports() Returns an immutable collection of this cluster's transports.
Map<String,Transport>	getTransportsMap() Returns an immutable map of this cluster's transports.
protected void	route(JsonObject json, PathfinderServices services) Updates the models routes.
private void	setCommodities(Iterable<Commodity> commodities) Sets this cluster's commodities.
private void	setCommodities(Map<String,Commodity> commodities) Sets this cluster's commodities.
private void	setRoutes(List<Route> routes) Sets this cluster's routes.
private void	setSubclusters(Iterable<Cluster> subclusters) Sets this cluster's sub-clusters.
private void	setSubclusters(Map<String,Cluster> subclusters) Sets this cluster's sub-clusters.
private void	setTransports(Iterable<Transport> transports) Sets this cluster's transports.
private void	setTransports(Map<String,Transport> transports) Sets this cluster's transports.
JsonObject	toJson() Converts the Model to JSON.
String	toString()
protected boolean	updateFields(JsonObject json) Updates the fields of the model.

Methods inherited from class xyz.thepathfinder.android.SubscribableCrudModel

connect, create, delete, update

Methods inherited from class xyz.thepathfinder.android.SubscribableModel

getMessageHeader, routeSubscribe, routeUnsubscribe, subscribe, unsubscribe

Methods inherited from class xyz.thepathfinder.android.Model

getChildPath, getModelType, getName, getParentCluster, getParentPath, getPath, getPathName, getServices, isConnected, isPathUnknown, notifyUpdate, sendMessage, setConnected, setPathName

Methods inherited from class xyz.thepathfinder.android.Listenable

addListener, getListeners, removeListener

Methods inherited from class java.lang.Object

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

Field Detail

logger

private static final org.slf4j.Logger logger

Logs actions performed by the class.

commodities

private Map<String,Commodity> commodities

Maps a path in the form of a string to the commodities directly under this cluster

subclusters

private Map<String,Cluster> subclusters

Maps a path in the form of a string to the sub-clusters directly under this cluster

transports

private Map<String,Transport> transports

Maps a path in the form of a string to the transports directly under this cluster

routes

private List<Route> routes

List of routes for this cluster. The routes object is an immutable list. The object should always be reassigned, never mutated.

Constructor Detail

Cluster

private Cluster(String path,
                PathfinderServices services)

Constructor for a cluster object. This should called by getInstance(String, PathfinderServices). Each path must only refer to one object.

Parameters:

path - The path name of the cluster.

services - A service object to send messages to the server and keep track of all Model objects.

Throws:

IllegalArgumentException - occurs when a cluster has already been registered with the same path.

IllegalArgumentException - if path is null.

Method Detail

getInstance

protected static Cluster getInstance(String path,
                                     PathfinderServices services)

Returns an instance of cluster object based on the path parameter. If there is a cluster with that path already created, it will return that cluster object. If there isn't a cluster with that path already created, it will create a new cluster object.

Parameters:

path - The full path to pathfinder model

services - The pathfinder services object.

Returns:

A cluster with the specified path. If path is an empty string it returns null.

getInstance

protected static Cluster getInstance(JsonObject clusterJson,
                                     PathfinderServices services)

Returns an instance of cluster object based on the path in clusterJson. If there is a cluster with that path already created, it will return that cluster object with updated fields. If there isn't a cluster with that path already created, it will create a new cluster object and update the fields. If the path is associated with a different model type or the json will not parse to a cluster object's required fields it will throw a IllegalArgumentException.

Parameters:

clusterJson - A json object that parses to a cluster.

services - The pathfinder services object.

Returns:

A cluster with the specified path.

Throws:

IllegalArgumentException - occurs if the json object doesn't parse to a cluster object.

checkClusterFields

private static boolean checkClusterFields(JsonObject clusterJson)

Checks the json object for all the required fields of a cluster object.

Parameters:

clusterJson - JsonObject to check if it will parse to a cluster.

Returns:

Whether the json can be parsed to a cluster.

getPath

private static String getPath(JsonObject clusterJson)

Returns the path as a string from a JSON object formatted as cluster.

Parameters:

clusterJson - JSON object that represents a cluster

Returns:

The path of the cluster

createValueJson

protected JsonObject createValueJson()

Returns the value used in create request to the Pathfinder server

Specified by:

createValueJson in class SubscribableCrudModel<Cluster,ClusterListener>

Returns:

the value JSON

createCommodity

public Commodity createCommodity(double startLatitude,
                                 double startLongitude,
                                 double endLatitude,
                                 double endLongitude,
                                 CommodityStatus status,
                                 JsonObject metadata)

Creates a commodity under this cluster on the pathfinder server. Returns the commodity waiting for the server to respond to it's creation. The commodity will not be accessible through the cluster until the server responds. Also, all messages to the server will be stored until the server responds with the creation of the commodity. Once the server responds the stored messages will be sent in the order created.

Parameters:

startLatitude - The pick up latitude of the commodity.

startLongitude - The pick up longitude of the commodity.

endLatitude - The drop off latitude of the commodity.

endLongitude - The drop off longitude of the commodity.

status - The current status of the commodity. If null it will default to CommodityStatus.OFFLINE.

metadata - A JsonObject representing the metadata field of the commodity. If null it will default to an empty JsonObject.

Returns:

Commodity with unknown path.

addCommodity

protected void addCommodity(Commodity commodity)

Adds a commodity to this cluster's list of available commodities.

Parameters:

commodity - to be added.

createCommodity

private Commodity createCommodity(JsonObject commodityJson)

Creates a commodity with a values specified in the JSON object.

Parameters:

commodityJson - a JSON object that represents a commodity

Returns:

A commodity with the values in the JSON object

getCommodity

public Commodity getCommodity(String path)

Returns a commodity directly under this cluster by its path.

Parameters:

path - of the commodity.

Returns:

A commodity associated with that path if one exists, null if it doesn't exist.

getCommodities

public Collection<Commodity> getCommodities()

Returns an immutable collection of this cluster's commodities.

Returns:

A collection of commodities.

setCommodities

private void setCommodities(Iterable<Commodity> commodities)

Sets this cluster's commodities.

Parameters:

commodities - an iterable collection of commodities

setCommodities

private void setCommodities(Map<String,Commodity> commodities)

Sets this cluster's commodities.

Parameters:

commodities - a map of commodities

getCommoditiesMap

public Map<String,Commodity> getCommoditiesMap()

Returns an immutable map of this cluster's commodities. The key is the path of commodity.

Returns:

A map of commodities.

createSubcluster

public Cluster createSubcluster(String name)

Creates a subcluster under this cluster on the pathfinder server.

Parameters:

name - Name of the subcluster, it must form a unique identifier when concatenated with this cluster's path.

Returns:

subcluster.

getSubcluster

public Cluster getSubcluster(String path)

Returns a direct descendant subcluster by its path.

Parameters:

path - of the subcluster

Returns:

A subcluster associated with the provided path if exists, null if it doesn't exist.

getSubclusters

public Collection<Cluster> getSubclusters()

Returns an immutable collection of this cluster's direct subclusters.

Returns:

An immutable collection of clusters.

setSubclusters

private void setSubclusters(Iterable<Cluster> subclusters)

Sets this cluster's sub-clusters.

Parameters:

subclusters - an iterable collection of clusters

setSubclusters

private void setSubclusters(Map<String,Cluster> subclusters)

Sets this cluster's sub-clusters.

Parameters:

subclusters - a map of clusters

getSubclustersMap

public Map<String,Cluster> getSubclustersMap()

Returns an immutable map of this cluster's direct subclusters.

Returns:

An immutable map of clusters.

addTransport

protected void addTransport(Transport transport)

Adds a transport to this cluster's list of available transports.

Parameters:

transport - to be added.

createTransport

public Transport createTransport(double latitude,
                                 double longitude,
                                 TransportStatus status,
                                 JsonObject metadata)

Creates a transport under this cluster on the pathfinder server.

Parameters:

latitude - The current latitude of the transport.

longitude - The current longitude of the transport.

status - The current status of the transport. If null it defaults to TransportStatus.OFFLINE

metadata - The transports's metadata field. If null it defaults to an empty JSON object.

Returns:

transport with the specified arguments.

getTransport

public Transport getTransport(String path)

Returns a transport directly under this cluster by its path.

Parameters:

path - of the transport.

Returns:

A transport associated with the provided path if exists, null if it doesn't exist.

getTransports

public Collection<Transport> getTransports()

Returns an immutable collection of this cluster's transports.

Returns:

A collection of transports.

setTransports

private void setTransports(Iterable<Transport> transports)

Sets this cluster's transports.

Parameters:

transports - an iterable collection of transports

setTransports

private void setTransports(Map<String,Transport> transports)

Sets this cluster's transports.

Parameters:

transports - a map of transports

getTransportsMap

public Map<String,Transport> getTransportsMap()

Returns an immutable map of this cluster's transports.

Returns:

A map of transports.

getRoutes

public Collection<Route> getRoutes()

Returns an immutable collection of this cluster's routes.

Returns:

A collection of routes.

setRoutes

private void setRoutes(List<Route> routes)

Sets this cluster's routes.

Parameters:

routes - a list of routes for this cluster

getSubmodelPath

private String getSubmodelPath(JsonObject json)

Returns the path name of a JSON Model.

Parameters:

json - of a Model.

Returns:

String of the path.

updateFields

protected boolean updateFields(JsonObject json)

Updates the fields of the model.

Specified by:

updateFields in class Model<Cluster,ClusterListener>

Parameters:

json - of the model.

Returns:

true if model changed in any way, false otherwise.

route

protected void route(JsonObject json,
                     PathfinderServices services)

Updates the models routes.

Specified by:

route in class Model<Cluster,ClusterListener>

Parameters:

json - of the model.

services - pathfinder services object.

toJson

public JsonObject toJson()

Converts the Model to JSON.

Specified by:

toJson in class Model<Cluster,ClusterListener>

Returns:

the Model as JSON.

toString

public String toString()

Overrides:

toString in class Object

getThis

protected Cluster getThis()

Returns the current object represented by this.

Specified by:

getThis in class Model<Cluster,ClusterListener>

Returns:

this.