com.swirl

Class Swirl

java.lang.Object

com.swirl.Swirl

public class Swirl
extends java.lang.Object

The Swirl class is the main entry point into the Swirl Proximity Library for delivery of proximity and content events to your app.

You use a singleton instance of this class to start: and stop proximity detection and delivery of proximity events. It supports a listener interface so you can add one or many listener objects to receive callbacks from any of the events broadcast on the eventBus.

See Also:

SwirlListener

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Swirl.BackgroundEvent Event sent when the application goes into the background.
static class	Swirl.DeviceChanged A subclass of Receiver for device related events.
static class	Swirl.ErrorEvent Event sent when Swirl reports an error
static class	Swirl.ForegroundEvent Event sent when the application comes into the foreground.
static class	Swirl.LocationChanged A subclass of Receiver for location related events.
static class	Swirl.Receiver Base class for all BroadcastReceivers.
static class	Swirl.Service This service class presents a STICKY service which runs in the background after the application has been terminated or has no visible activities in the foreground.
static class	Swirl.StartedEvent Event sent when Swirl started without error.
static class	Swirl.StatusChangedEvent Event sent when Swirl status changes.

Field Summary

Fields

Modifier and Type	Field and Description
static int	STATUS_BLUETOOTH If this bit is set, Bluetooth Services are available.
static int	STATUS_DEVICE_MASK A bit mask for accessing device status portion
static int	STATUS_ERROR If this bit is set, the system has reported an error, which is available in the error property.
static int	STATUS_LOCATION If this bit is set, Location Services are authorized.
static int	STATUS_NETWORK If this bit is set, Network Services are available.
static int	STATUS_NONE This value indicates that the system is not running.
static int	STATUS_NOTIFICATIONS If this bit is set, Notifications are enabled.
static int	STATUS_PENDING If this bit is set, the system is transitioning from Stopped to Running or the reverse.
static int	STATUS_RUNNING If this bit is set, the system is either Running or if Pending is also set, Stopping.
static int	STATUS_SWIRL_MASK A bit mask for accessing Swirl status portion

Method Summary

Modifier and Type	Method and Description
Swirl	addListener(java.lang.Object listener) Add a listener to the internal listener bus.
Swirl	addListener(java.lang.Object listener, java.util.concurrent.Executor executor) Add a listener to the internal listener bus, specifying an executor.
static boolean	checkApiVersions()
java.lang.Object	findListener(java.lang.Class aclass) Find the first registered listener of a given class.
int	getError() Return the library's last recorded error.
static Swirl	getInstance() Return the shared singleton, assuming it has already been created.
static Swirl	getInstance(android.content.Context c) Return the shared singleton, assuming it has already been created.
static Swirl	getInstance(android.content.Context c, java.lang.Class[] listeners) Return the shared singleton, assuming it has already been created.
android.location.Location	getLocation() Return the library's internal location object.
int	getStatus() Return the library's running status.
org.json.JSONObject	getUserInfo() * Get the currently stored user-info attributes.
java.lang.String	getUserKey() Returns a string representation of the UUID that the library generates for this device.
java.lang.String	getVersion() Get the current version (as a string) of the library.
Swirl	logEvent(java.lang.String event, java.lang.String data) Log event to the log stream.
void	onLocationChange(Device.LocationChangedEvent event)
void	permissionsChanged() Informs the SDK that the user has changed permissions and to re-initialize things that depend on dynamic permissions
Swirl	post(java.lang.Object object) Post an object to the internal message bus.
Swirl	removeListener(java.lang.Object listener) Remove a listener that had been previously added via addListener().
Swirl	reset() Removes all locally stored data and state.
Swirl	setBackgroundMode(boolean background) Sets the current operating mode to foreground or background.
Swirl	setOptions(android.os.Bundle options) Pushes a bundle of property value pairs into Settings.
void	setUserInfo(org.json.JSONObject info) Set the currently store user attributes
Swirl	start(android.os.Bundle options) Starts the sdk and all loaded managers.
Swirl	stop() Stops the sdk.
Swirl	streamMessage(org.json.JSONObject message) Publish a message to the live event stream.

Methods inherited from class java.lang.Object

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

Field Detail

STATUS_NONE

public static final int STATUS_NONE

This value indicates that the system is not running.

See Also:

Constant Field Values

STATUS_RUNNING

public static final int STATUS_RUNNING

If this bit is set, the system is either Running or if Pending is also set, Stopping.

See Also:

Constant Field Values

STATUS_PENDING

public static final int STATUS_PENDING

If this bit is set, the system is transitioning from Stopped to Running or the reverse.

See Also:

Constant Field Values

STATUS_ERROR

public static final int STATUS_ERROR

If this bit is set, the system has reported an error, which is available in the error property.

See Also:

Constant Field Values

STATUS_LOCATION

public static final int STATUS_LOCATION

If this bit is set, Location Services are authorized.

See Also:

Constant Field Values

STATUS_BLUETOOTH

public static final int STATUS_BLUETOOTH

If this bit is set, Bluetooth Services are available.

See Also:

Constant Field Values

STATUS_NETWORK

public static final int STATUS_NETWORK

If this bit is set, Network Services are available.

See Also:

Constant Field Values

STATUS_NOTIFICATIONS

public static final int STATUS_NOTIFICATIONS

If this bit is set, Notifications are enabled.

See Also:

Constant Field Values

STATUS_SWIRL_MASK

public static final int STATUS_SWIRL_MASK

A bit mask for accessing Swirl status portion

See Also:

Constant Field Values

STATUS_DEVICE_MASK

public static final int STATUS_DEVICE_MASK

A bit mask for accessing device status portion

See Also:

Constant Field Values

Method Detail

getInstance

public static Swirl getInstance()

Return the shared singleton, assuming it has already been created. This flavor of the API will not create the shared instance if it does not already exist.

Returns:

Swirl singleton or null if not already created.

getInstance

public static Swirl getInstance(android.content.Context c)

Return the shared singleton, assuming it has already been created. If the instance has not yet been created, it will be created with default parameters (ie. all standard listeners).

Parameters:

c - Application context

Returns:

Swirl singleton

getInstance

public static Swirl getInstance(android.content.Context c,
                                java.lang.Class[] listeners)

Return the shared singleton, assuming it has already been created. If the instance has not yet been created, it will be created with default parameters (ie. all standard listeners).

Parameters:

c - Application context

listeners - An array of listener classes.

Returns:

Swirl singleton

setOptions

public Swirl setOptions(android.os.Bundle options)

Pushes a bundle of property value pairs into Settings.

Parameters:

options - A Bundle containing property, value pairs of system settings or settings that can be used by custom listeners or managers.

Returns:

Swirl (so calls can be chained)

setBackgroundMode

public Swirl setBackgroundMode(boolean background)

Sets the current operating mode to foreground or background. Background and foreground monitoring enables the library to take different actions based on this state like post notifications when in background, but starting Activities for content when the application is in the foreground. This mode also controls different sets of parameters for the various managers.

Parameters:

background - A boolean value indicating which mode to be in.

Returns:

Swirl (so calls can be chained)

addListener

public Swirl addListener(java.lang.Object listener)

Add a listener to the internal listener bus. Listeners are added to the internal multicast listener bus and can receive messages from any of the listed interfaces (@see #SwirlListener). Listeners added via this method are added using the mainLoopExecutor. This function simply calls addListener(Object,Executor) with the result of **executor** as the executor argument. If the existing listener has already been added, this function takes no action.

Parameters:

listener - The object to receive listener callbacks. This parameter must not be `null`.

Returns:

Swirl instance (so calls can be chained)

See Also:

removeListener(Object), addListener(Object, Executor)

addListener

public Swirl addListener(java.lang.Object listener,
                         java.util.concurrent.Executor executor)

Add a listener to the internal listener bus, specifying an executor. Listeners are added to the internal multicast listener bus and can receive messages from any of the listed interfaces (see x). All messages dispatched to this listener will be delivered on the executor specified. If the existing listener has already been added, this function takes no action.

Parameters:

listener - The object to receive listener callbacks. This parameter must not be `null`.

executor - The executor on which messages should be delivered. This parameter must not be `null`.

Returns:

this Swirl instance

See Also:

removeListener(Object), addListener(Object)

removeListener

public Swirl removeListener(java.lang.Object listener)

Remove a listener that had been previously added via addListener(). If the listener is not present, this method does nothing.

Parameters:

listener - The object to receive listener callbacks. This parameter must not be `null`.

Returns:

this Swirl instance

See Also:

addListener(Object), addListener(Object, Executor)

findListener

public java.lang.Object findListener(java.lang.Class aclass)

Find the first registered listener of a given class.

Parameters:

aclass - Class of the listener to find

Returns:

a listener of the given class or null if not found

getLocation

public android.location.Location getLocation()

Return the library's internal location object. This object is updated by the library in response to Intent's broadcast by the Android LocationManager.

Returns:

The libraries internal OS location object.

getError

public int getError()

Return the library's last recorded error.

Returns:

error code

getStatus

public int getStatus()

Return the library's running status. This value is a bit field whose values are documented above (@see STATUS_*)

Returns:

status bit field

getUserKey

public java.lang.String getUserKey()

Returns a string representation of the UUID that the library generates for this device.

Returns:

UUID String.

getUserInfo

public org.json.JSONObject getUserInfo()

* Get the currently stored user-info attributes.

Returns:

The current user-attributes or null

setUserInfo

public void setUserInfo(org.json.JSONObject info)

Set the currently store user attributes

Parameters:

info - The attributes to store for the current user.

getVersion

public java.lang.String getVersion()

Get the current version (as a string) of the library.

Returns:

library version

start

public Swirl start(android.os.Bundle options)

Starts the sdk and all loaded managers.

Parameters:

options - all of the startup options (see x)

Returns:

this Swirl instance

permissionsChanged

public void permissionsChanged()

Informs the SDK that the user has changed permissions and to re-initialize things that depend on dynamic permissions

stop

public Swirl stop()

Stops the sdk. If there are pending events, they are flushed and this method will block until all queued events have been sent.

Returns:

this Swirl instance

post

public Swirl post(java.lang.Object object)

Post an object to the internal message bus.

Parameters:

object - the object to post

Returns:

this Swirl instance

logEvent

public Swirl logEvent(java.lang.String event,
                      java.lang.String data)

Log event to the log stream.

Parameters:

event - The event name (see the list of known events)

data - The data for event (see the list of events)

Returns:

this Swirl instance

streamMessage

public Swirl streamMessage(org.json.JSONObject message)

Publish a message to the live event stream.

Parameters:

message - a JSON object to put on the stream

Returns:

this Swirl instance

reset

public Swirl reset()

Removes all locally stored data and state. If the sdk is currently running, it will call stop first. After calling this function, the sdk will be in a stopped state.

Returns:

this Swirl instance

checkApiVersions

public static boolean checkApiVersions()

onLocationChange

public void onLocationChange(Device.LocationChangedEvent event)