xyz.thepathfinder.android

Class Pathfinder

java.lang.Object

xyz.thepathfinder.android.Pathfinder

public class Pathfinder
extends Object

The Pathfinder class is the main entry point to the Pathfinder API. To create the Pathfinder class you need a valid application identifier provided from your Pathfinder service manager, we provide the ability to get an application identifier from thepathfinder.xyz. The connection also requires a JWT in the form of a String to authenticate the user. The URI to your pathfinder provider is also required to initiate the connection.

The default cluster is available via the getDefaultCluster() method. Any other cluster available to the user may be obtained through the getCluster(String) method, where the path is of the form "/default/clusterName/subclusterName/subsubclusterName".

Note, when connecting thePathfinder object the thread is blocked until the web socket to the Pathfinder service is opened.

   Pathfinder pathfinder = new Pathfinder("myAppId", "userJWT");
   pathfinder.addAuthenticationListener(new MyAuthListener());
   pathfinder.connect();
   Cluster cluster = pathfinder.getCluster("/root/cluster1/subcluster2");
   MyClusterListener clusterListener = new MyClusterListener();
   cluster.addListener(clusterListener);
   cluster.connect();
    // more code ...
   pathfinder.close();

See Also:

Cluster, Commodity, Transport

Field Summary

Fields

Modifier and Type	Field and Description
private String	applicationIdentifier Application Identifier that identifies the application on the pathfinder server.
private Authenticator	authenticator The authenticator controlling the authentication sequence.
private static String	DEFAULT_AUTH_URI The default authentication server URI.
private static String	DEFAULT_WEBSOCKET_URI The default web socket URI.
private static org.slf4j.Logger	logger Logs actions performed by the class.
private PathfinderServices	services Keeps track of all the Pathfinder models and connection to the server.
private URI	webSocketUrl URL to the Pathfinder server being connected to.

Constructor Summary

Constructors

Modifier	Constructor and Description
	Pathfinder(String applicationIdentifier, String userCredentials) Constructs a Pathfinder object.
	Pathfinder(String applicationIdentifier, String userCredentials, String authenticationServerURL) Constructs a Pathfinder object.
protected	Pathfinder(String applicationIdentifier, String userCredentials, URI webSocketUrl) Constructs a Pathfinder object.

Method Summary

Modifier and Type	Method and Description
void	addAuthenticationListener(AuthenticationListener listener) Adds an AuthenticationListener to listen for the success or failure of the authentication sequence.
void	close() Closes the web socket connection to the Pathfinder server with a normal close condition.
void	close(CloseReason reason) Closes the web socket connection to the Pathfinder server, if it is still open, with the specified reason.
void	connect() Establishes a connection to the Pathfinder server, if the connection is not already open.
void	connect(boolean isAsync) Establishes a connection to the Pathfinder server, if the connection is not already open.
private void	constructPathfinderServices(String applicationIdentifier, String userCredentials, String authenticationServerURL) Sets the PathfinderServices object.
Cluster	getCluster(String path) Gets an unconnected cluster pointing to the path specified.
Commodity	getCommodity(String path) Gets an unconnected commodity pointing to the path specified.
Cluster	getDefaultCluster() Gets an unconnected cluster pointing to the default cluster for the application identifier provided.
protected long	getReceivedMessageCount() Returns the number of web socket messages received from the Pathfinder server.
protected long	getSentMessageCount() Returns the number of web socket messages sent to the Pathfinder server.
Transport	getTransport(String path) Gets an unconnected transport pointing to the path specified.
boolean	isConnected() Returns true if the web socket connection to the Pathfinder server is open.
void	removeAuthenticationListener(AuthenticationListener listener) Removes an AuthenticationListener.

Methods inherited from class java.lang.Object

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

Field Detail

logger

private static final org.slf4j.Logger logger

Logs actions performed by the class.

DEFAULT_AUTH_URI

private static final String DEFAULT_AUTH_URI

The default authentication server URI.

See Also:

Constant Field Values

DEFAULT_WEBSOCKET_URI

private static final String DEFAULT_WEBSOCKET_URI

The default web socket URI.

See Also:

Constant Field Values

applicationIdentifier

private final String applicationIdentifier

Application Identifier that identifies the application on the pathfinder server.

authenticator

private Authenticator authenticator

The authenticator controlling the authentication sequence.

services

private PathfinderServices services

Keeps track of all the Pathfinder models and connection to the server.

webSocketUrl

private URI webSocketUrl

URL to the Pathfinder server being connected to.

Constructor Detail

Pathfinder

public Pathfinder(String applicationIdentifier,
                  String userCredentials)

Constructs a Pathfinder object.

Parameters:

applicationIdentifier - application Identifier provided by a Pathfinder service provider

userCredentials - JWT of the user's credentials

Pathfinder

public Pathfinder(String applicationIdentifier,
                  String userCredentials,
                  String authenticationServerURL)

Constructs a Pathfinder object.

Parameters:

applicationIdentifier - application Identifier provided by a Pathfinder service provider

userCredentials - JWT of the user's credentials

authenticationServerURL - URL to use when authenticating users

Pathfinder

protected Pathfinder(String applicationIdentifier,
                     String userCredentials,
                     URI webSocketUrl)

Constructs a Pathfinder object.

Parameters:

applicationIdentifier - application Identifier provided by a Pathfinder service provider

userCredentials - JWT of the user's credentials

webSocketUrl - URL to the Pathfinder web socket service provider

Method Detail

constructPathfinderServices

private void constructPathfinderServices(String applicationIdentifier,
                                         String userCredentials,
                                         String authenticationServerURL)

Sets the PathfinderServices object.

Parameters:

applicationIdentifier - application Identifier provided by a Pathfinder service provider

userCredentials - the user's identity JWT.

authenticationServerURL - URL to use when authenticating users

connect

public void connect()

Establishes a connection to the Pathfinder server, if the connection is not already open. This method doesn't blocks until the connection is established.

Throws:

RuntimeException - if could not connect to the Pathfinder server.

connect

public void connect(boolean isAsync)

Establishes a connection to the Pathfinder server, if the connection is not already open. This method blocks until the connection is established if isAsync is false. Setting isAsync to false helps test for SSL problems, as when isAsync is true no exception is thrown when SSL fails.

Parameters:

isAsync - if true it will asynchronously connect to the Pathfinder server, if false it will synchronously connect to the Pathfinder server

Throws:

RuntimeException - if could not connect to the Pathfinder server.

addAuthenticationListener

public void addAuthenticationListener(AuthenticationListener listener)

Adds an AuthenticationListener to listen for the success or failure of the authentication sequence.

Parameters:

listener - to add.

removeAuthenticationListener

public void removeAuthenticationListener(AuthenticationListener listener)

Removes an AuthenticationListener.

Parameters:

listener - to remove.

getDefaultCluster

public Cluster getDefaultCluster()

Gets an unconnected cluster pointing to the default cluster for the application identifier provided.

Returns:

an unconnected cluster

getCluster

public Cluster getCluster(String path)

Gets an unconnected cluster pointing to the path specified.

Parameters:

path - to the cluster

Returns:

an unconnected cluster

getCommodity

public Commodity getCommodity(String path)

Gets an unconnected commodity pointing to the path specified.

Parameters:

path - to the commodity

Returns:

an unconnected commodity

getTransport

public Transport getTransport(String path)

Gets an unconnected transport pointing to the path specified.

Parameters:

path - to the transport

Returns:

an unconnected transport

isConnected

public boolean isConnected()

Returns true if the web socket connection to the Pathfinder server is open.

Returns:

true if the connection is still open

getSentMessageCount

protected long getSentMessageCount()

Returns the number of web socket messages sent to the Pathfinder server.

Returns:

The number of web socket messages sent

getReceivedMessageCount

protected long getReceivedMessageCount()

Returns the number of web socket messages received from the Pathfinder server.

Returns:

The number of web socket messsages received.

close

public void close()
           throws IOException

Closes the web socket connection to the Pathfinder server with a normal close condition.

Throws:

IOException - If there was error closing the connection.

close

public void close(CloseReason reason)
           throws IOException

Closes the web socket connection to the Pathfinder server, if it is still open, with the specified reason.

Parameters:

reason - The reason to close the connection.

Throws:

IOException - If there was error closing the connection.