io.keen.client.java
Class KeenClient

java.lang.Object
  io.keen.client.java.KeenClient

public class KeenClient
extends Object

KeenClient has static methods to return managed instances of itself and instance methods to collect new events and upload them through the Keen API.

Example usage:

     KeenClient.initialize("my_project_id", "my_write_key", "my_read_key");
     Map myEvent = new HashMap();
     myEvent.put("property name", "property value");
     KeenClient.client().addEvent("purchases", myEvent);
 

Since:

1.0.0

Author:

dkador

Constructor Summary

KeenClient(String projectId, String writeKey, String readKey)
Call this if your code needs to use more than one Keen project and API Key (or if you don't want to use the managed, singleton instance provided by this library).

Method Summary

void	addEvent(String eventCollection, Map<String,Object> event) Call this any time you want to add an event that will be sent to the Keen IO server.
void	addEvent(String eventCollection, Map<String,Object> event, Map<String,Object> keenProperties, AddEventCallback callback) Call this any time you want to add an event that will be sent to the Keen IO server AND you want to override Keen-defaulted properties (like timestamp).
static KeenClient	client() Call this to retrieve the singleton instance of KeenClient.
Map<String,Object>	getGlobalProperties() Getter for the Keen Global Properties map.
GlobalPropertiesEvaluator	getGlobalPropertiesEvaluator() Getter for the GlobalPropertiesEvaluator associated with this instance of the KeenClient.
String	getProjectId() Getter for the Keen Project Id associated with this instance of the KeenClient.
String	getReadKey() Getter for the Keen Read Key associated with this instance of the KeenClient.
String	getWriteKey() Getter for the Keen Write Key associated with this instance of the KeenClient.
static void	initialize(String projectId, String writeKey, String readKey) Call this to initialize the singleton instance of KeenClient and set its Project Id.
void	processRunnableInNewThread(Runnable runnable) Responsible for taking a Runnable and running it a new thread.
void	setGlobalProperties(Map<String,Object> globalProperties) Call this to set the Keen Global Properties Map for this instance of the KeenClient.
void	setGlobalPropertiesEvaluator(GlobalPropertiesEvaluator globalPropertiesEvaluator) Call this to set the GlobalPropertiesEvaluator for this instance of the KeenClient.

Methods inherited from class java.lang.Object

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

Constructor Detail

KeenClient

public KeenClient(String projectId,
                  String writeKey,
                  String readKey)

Call this if your code needs to use more than one Keen project and API Key (or if you don't want to use the managed, singleton instance provided by this library).

Parameters:

projectId - The Keen IO Project ID.

writeKey - Your Keen IO Write Key.

readKey - Your Keen IO Read Key.

Method Detail

initialize

public static void initialize(String projectId,
                              String writeKey,
                              String readKey)

Call this to initialize the singleton instance of KeenClient and set its Project Id.

You'll generally want to call this at the very beginning of your application's lifecycle. Once you've called this, you can then call KeenClient.client() afterwards.

Parameters:

projectId - The Keen IO Project Id.

writeKey - Your Keen IO Write Key.

readKey - Your Keen IO Read Key.

client

public static KeenClient client()

Call this to retrieve the singleton instance of KeenClient.

If you only have to use a single Keen project, just use this.

Returns:

A managed instance of KeenClient, or null if KeenClient.initialize() hasn't been called previously.

addEvent

public void addEvent(String eventCollection,
                     Map<String,Object> event)
              throws KeenException

Call this any time you want to add an event that will be sent to the Keen IO server.

Parameters:

eventCollection - The name of the event collection you want to put this event into.

event - A Map that consists of key/value pairs. Keen naming conventions apply (see docs). Nested Maps and lists are acceptable (and encouraged!).

Throws:

KeenException

addEvent

public void addEvent(String eventCollection,
                     Map<String,Object> event,
                     Map<String,Object> keenProperties,
                     AddEventCallback callback)
              throws KeenException

Call this any time you want to add an event that will be sent to the Keen IO server AND you want to override Keen-defaulted properties (like timestamp).

Parameters:

eventCollection - The name of the event collection you want to put this event into.

event - A Map that consists of key/value pairs. Keen naming conventions apply (see docs). Nested Maps and lists are acceptable (and encouraged!).

keenProperties - A Map that consists of key/value pairs to override default properties. ex: "timestamp" -> Calendar.getInstance()

callback - An instance of AddEventCallback. Will invoke onSuccess when adding the event succeeds. Will invoke onError when adding the event fails.

Throws:

KeenException

getProjectId

public String getProjectId()

Getter for the Keen Project Id associated with this instance of the KeenClient.

Returns:

the Keen Project Id

getWriteKey

public String getWriteKey()

Getter for the Keen Write Key associated with this instance of the KeenClient.

Returns:

the Keen Write Key

getReadKey

public String getReadKey()

Getter for the Keen Read Key associated with this instance of the KeenClient.

Returns:

the Keen Read Key

getGlobalPropertiesEvaluator

public GlobalPropertiesEvaluator getGlobalPropertiesEvaluator()

Getter for the GlobalPropertiesEvaluator associated with this instance of the KeenClient.

Returns:

the GlobalPropertiesEvaluator

setGlobalPropertiesEvaluator

public void setGlobalPropertiesEvaluator(GlobalPropertiesEvaluator globalPropertiesEvaluator)

Call this to set the GlobalPropertiesEvaluator for this instance of the KeenClient. The evaluator is invoked every time an event is added to an event collection.

Global properties are properties which are sent with EVERY event. For example, you may wish to always capture device information like OS version, handset type, orientation, etc.

The evaluator takes as a parameter a single String, which is the name of the event collection the event's being added to. You're responsible for returning a Map which represents the global properties for this particular event collection.

Note that because we use a class defined by you, you can create DYNAMIC global properties. For example, if you want to capture device orientation, then your evaluator can ask the device for its current orientation and then construct the Map. If your global properties aren't dynamic, then just return the same Map every time.

Example usage:

     {@code KeenClient client = KeenClient.client();
     GlobalPropertiesEvaluator evaluator = new GlobalPropertiesEvaluator() {


Parameters:
globalPropertiesEvaluator - The evaluator which is invoked any time an event is added to an event
                                  collection.

getGlobalProperties

public Map<String,Object> getGlobalProperties()

Getter for the Keen Global Properties map. See docs for setGlobalProperties(java.util.Map).

setGlobalProperties

public void setGlobalProperties(Map<String,Object> globalProperties)

Call this to set the Keen Global Properties Map for this instance of the KeenClient. The Map is used every time an event is added to an event collection.

Keen Global Properties are properties which are sent with EVERY event. For example, you may wish to always capture static information like user ID, app version, etc.

Every time an event is added to an event collection, the SDK will check to see if this property is defined. If it is, the SDK will copy all the properties from the global properties into the newly added event.

Note that because this is just a Map, it's much more difficult to create DYNAMIC global properties. It also doesn't support per-collection properties. If either of these use cases are important to you, please use the GlobalPropertiesEvaluator.

Also note that the Keen properties defined in getGlobalPropertiesEvaluator() take precedence over the properties defined in getGlobalProperties, and that the Keen Properties defined in each individual event take precedence over either of the Global Properties.

Example usage:

 KeenClient client = KeenClient.client();
 Map map = new HashMap();
 map.put("some standard key", "some standard value");
 client.setGlobalProperties(map);
 

Parameters:

globalProperties - The new map you wish to use as the Keen Global Properties.

processRunnableInNewThread

public void processRunnableInNewThread(Runnable runnable)

Responsible for taking a Runnable and running it a new thread.

Default implementation uses an ExecutorService to manage a thread pool and submit jobs to that thread pool.

Override this if you want to manage your own threads. Just make sure you eventually run every Runnable passed in. It's probably a good idea to set KeenConfig.NUM_THREADS_FOR_HTTP_REQUESTS to 0 if you do this.

Parameters:

runnable - The Runnable to run. In practice, this Runnable is responsible for uploading an event to Keen IO.