io.keen.client.java

Class KeenClient

java.lang.Object

io.keen.client.java.KeenClient

public class KeenClient
extends java.lang.Object

KeenClient provides all of the functionality required to:

• Create events from map objects
• Automatically insert properties into events as they are created
• Post events to the Keen server, either one-at-a-time or in batches
• Store events in between batch posts, if desired
• Perform posts either synchronously or asynchronously

To create a KeenClient, use a subclass of KeenClient.Builder which provides the default interfaces for various operations (HTTP, JSON, queueing, async).

Since:

1.0.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	KeenClient.Builder Builder class for instantiating Keen clients.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	KeenClient(KeenClient.Builder builder) Constructs a Keen client using system environment variables.

Method Summary

Modifier and Type	Method and Description
void	addEvent(KeenProject project, java.lang.String eventCollection, java.util.Map<java.lang.String,java.lang.Object> event, java.util.Map<java.lang.String,java.lang.Object> keenProperties, KeenCallback callback) Synchronously adds an event to the specified collection.
void	addEvent(java.lang.String eventCollection, java.util.Map<java.lang.String,java.lang.Object> event) Adds an event to the default project with default Keen properties and no callbacks.
void	addEvent(java.lang.String eventCollection, java.util.Map<java.lang.String,java.lang.Object> event, java.util.Map<java.lang.String,java.lang.Object> keenProperties) Adds an event to the default project with no callbacks.
void	addEventAsync(KeenProject project, java.lang.String eventCollection, java.util.Map<java.lang.String,java.lang.Object> event, java.util.Map<java.lang.String,java.lang.Object> keenProperties, KeenCallback callback) Asynchronously adds an event to the specified collection.
void	addEventAsync(java.lang.String eventCollection, java.util.Map<java.lang.String,java.lang.Object> event) Adds an event to the default project with default Keen properties and no callbacks.
void	addEventAsync(java.lang.String eventCollection, java.util.Map<java.lang.String,java.lang.Object> event, java.util.Map<java.lang.String,java.lang.Object> keenProperties) Adds an event to the default project with no callbacks.
static KeenClient	client() Call this to retrieve the KeenClient singleton instance.
java.lang.String	getBaseUrl() Gets the base API URL associated with this instance of the KeenClient.
KeenProject	getDefaultProject() Gets the default project that this KeenClient will use if no project is specified.
KeenEventStore	getEventStore() Gets the event store for this client.
java.util.Map<java.lang.String,java.lang.Object>	getGlobalProperties() Gets the Keen Global Properties map.
GlobalPropertiesEvaluator	getGlobalPropertiesEvaluator() Gets the GlobalPropertiesEvaluator associated with this instance of the KeenClient.
KeenJsonHandler	getJsonHandler() Gets the JSON handler for this client.
int	getMaxAttempts() Sets the maximum number of HTTPS POST retry attempts for all events added in the future.
java.net.Proxy	getProxy() Gets the client Proxy.
java.util.concurrent.Executor	getPublishExecutor() Gets the executor for asynchronous publishing for this client.
static void	initialize(KeenClient client) Initializes the static Keen client.
boolean	isActive() Gets whether or not the client is in active mode.
boolean	isDebugMode() Gets whether or not the Keen client is running in debug mode.
static boolean	isInitialized() Gets whether or not the singleton KeenClient has been initialized.
void	queueEvent(KeenProject project, java.lang.String eventCollection, java.util.Map<java.lang.String,java.lang.Object> event, java.util.Map<java.lang.String,java.lang.Object> keenProperties, KeenCallback callback) Synchronously queues an event for publishing.
void	queueEvent(java.lang.String eventCollection, java.util.Map<java.lang.String,java.lang.Object> event) Queues an event in the default project with default Keen properties and no callbacks.
void	queueEvent(java.lang.String eventCollection, java.util.Map<java.lang.String,java.lang.Object> event, java.util.Map<java.lang.String,java.lang.Object> keenProperties) Queues an event in the default project with no callbacks.
void	sendQueuedEvents() Sends all queued events for the default project with no callbacks.
void	sendQueuedEvents(KeenProject project) Sends all queued events for the specified project with no callbacks.
void	sendQueuedEvents(KeenProject project, KeenCallback callback) Synchronously sends all queued events for the given project.
void	sendQueuedEventsAsync() Sends all queued events for the default project with no callbacks.
void	sendQueuedEventsAsync(KeenProject project) Sends all queued events for the specified project with no callbacks.
void	sendQueuedEventsAsync(KeenProject project, KeenCallback callback) Asynchronously sends all queued events for the given project.
protected void	setActive(boolean isActive) Sets whether or not the client is in active mode.
void	setBaseUrl(java.lang.String baseUrl) Sets the base API URL associated with this instance of the KeenClient.
void	setDebugMode(boolean isDebugMode) Sets whether or not the Keen client should run in debug mode.
void	setDefaultProject(KeenProject defaultProject) Sets the default project that this KeenClient should use if no project is specified.
void	setGlobalProperties(java.util.Map<java.lang.String,java.lang.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.
void	setMaxAttempts(int maxAttempts) Sets the maximum number of HTTPS POST retry attempts for all events added in the future.
void	setProxy(java.net.Proxy proxy) Sets an HTTP proxy server configuration for this client.
void	setProxy(java.lang.String proxyHost, int proxyPort) Sets an HTTP proxy server configuration for this client.
protected java.util.Map<java.lang.String,java.lang.Object>	validateAndBuildEvent(KeenProject project, java.lang.String eventCollection, java.util.Map<java.lang.String,java.lang.Object> event, java.util.Map<java.lang.String,java.lang.Object> keenProperties) Validates an event and inserts global properties, producing a new event object which is ready to be published to the Keen service.

Methods inherited from class java.lang.Object

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

Constructor Detail

KeenClient

protected KeenClient(KeenClient.Builder builder)

Constructs a Keen client using system environment variables.

Parameters:

builder - The builder from which to retrieve this client's interfaces and settings.

Method Detail

client

public static KeenClient client()

Call this to retrieve the KeenClient singleton instance.

Returns:

The singleton instance of the client.

initialize

public static void initialize(KeenClient client)

Initializes the static Keen client. Only the first call to this method has any effect. All subsequent calls are ignored.

Parameters:

client - The KeenClient implementation to use as the singleton client for the library.

isInitialized

public static boolean isInitialized()

Gets whether or not the singleton KeenClient has been initialized.

Returns:

true if and only if the client has been initialized.

addEvent

public void addEvent(java.lang.String eventCollection,
                     java.util.Map<java.lang.String,java.lang.Object> event)

Adds an event to the default project with default Keen properties and no callbacks.

Parameters:

eventCollection - The name of the collection in which to publish the event.

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

See Also:

addEvent(KeenProject, String, java.util.Map, java.util.Map, KeenCallback)

addEvent

public void addEvent(java.lang.String eventCollection,
                     java.util.Map<java.lang.String,java.lang.Object> event,
                     java.util.Map<java.lang.String,java.lang.Object> keenProperties)

Adds an event to the default project with no callbacks.

Parameters:

eventCollection - The name of the collection in which to publish the event.

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()

See Also:

addEvent(KeenProject, String, java.util.Map, java.util.Map, KeenCallback)

addEvent

public void addEvent(KeenProject project,
                     java.lang.String eventCollection,
                     java.util.Map<java.lang.String,java.lang.Object> event,
                     java.util.Map<java.lang.String,java.lang.Object> keenProperties,
                     KeenCallback callback)

Synchronously adds an event to the specified collection. This method will immediately publish the event to the Keen server in the current thread.

Parameters:

project - The project in which to publish the event. If a default project has been set on the client, this parameter may be null, in which case the default project will be used.

eventCollection - The name of the collection in which to publish the event.

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 optional callback to receive notification of success or failure.

addEventAsync

public void addEventAsync(java.lang.String eventCollection,
                          java.util.Map<java.lang.String,java.lang.Object> event)

Adds an event to the default project with default Keen properties and no callbacks.

Parameters:

eventCollection - The name of the collection in which to publish the event.

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

See Also:

addEvent(KeenProject, String, java.util.Map, java.util.Map, KeenCallback)

addEventAsync

public void addEventAsync(java.lang.String eventCollection,
                          java.util.Map<java.lang.String,java.lang.Object> event,
                          java.util.Map<java.lang.String,java.lang.Object> keenProperties)

Adds an event to the default project with no callbacks.

Parameters:

eventCollection - The name of the collection in which to publish the event.

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()

See Also:

addEvent(KeenProject, String, java.util.Map, java.util.Map, KeenCallback)

addEventAsync

public void addEventAsync(KeenProject project,
                          java.lang.String eventCollection,
                          java.util.Map<java.lang.String,java.lang.Object> event,
                          java.util.Map<java.lang.String,java.lang.Object> keenProperties,
                          KeenCallback callback)

Asynchronously adds an event to the specified collection. This method will request that the Keen client's Executor executes the publish operation.

Parameters:

project - The project in which to publish the event. If a default project has been set on the client this parameter may be null, in which case the default project will be used.

eventCollection - The name of the collection in which to publish the event.

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 optional callback to receive notification of success or failure.

queueEvent

public void queueEvent(java.lang.String eventCollection,
                       java.util.Map<java.lang.String,java.lang.Object> event)

Queues an event in the default project with default Keen properties and no callbacks.

Parameters:

eventCollection - The name of the collection in which to publish the event.

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

See Also:

queueEvent(KeenProject, String, java.util.Map, java.util.Map, KeenCallback)

queueEvent

public void queueEvent(java.lang.String eventCollection,
                       java.util.Map<java.lang.String,java.lang.Object> event,
                       java.util.Map<java.lang.String,java.lang.Object> keenProperties)

Queues an event in the default project with no callbacks.

Parameters:

eventCollection - The name of the collection in which to publish the event.

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()

See Also:

queueEvent(KeenProject, String, java.util.Map, java.util.Map, KeenCallback)

queueEvent

public void queueEvent(KeenProject project,
                       java.lang.String eventCollection,
                       java.util.Map<java.lang.String,java.lang.Object> event,
                       java.util.Map<java.lang.String,java.lang.Object> keenProperties,
                       KeenCallback callback)

Synchronously queues an event for publishing. The event will be cached in the client's KeenEventStore until the next call to either sendQueuedEvents() or sendQueuedEventsAsync().

Parameters:

project - The project in which to publish the event. If a default project has been set on the client this parameter may be null, in which case the default project will be used.

eventCollection - The name of the collection in which to publish the event.

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 optional callback to receive notification of success or failure.

sendQueuedEvents

public void sendQueuedEvents()

Sends all queued events for the default project with no callbacks.

See Also:

sendQueuedEvents(KeenProject, KeenCallback)

sendQueuedEvents

public void sendQueuedEvents(KeenProject project)

Sends all queued events for the specified project with no callbacks.

Parameters:

project - The project for which to send queued events. If a default project has been set on the client this parameter may be null, in which case the default project will be used.

See Also:

sendQueuedEvents(KeenProject, KeenCallback)

sendQueuedEvents

public void sendQueuedEvents(KeenProject project,
                             KeenCallback callback)

Synchronously sends all queued events for the given project. This method will immediately publish the events to the Keen server in the current thread.

Parameters:

project - The project for which to send queued events. If a default project has been set on the client this parameter may be null, in which case the default project will be used.

callback - An optional callback to receive notification of success or failure.

sendQueuedEventsAsync

public void sendQueuedEventsAsync()

Sends all queued events for the default project with no callbacks.

See Also:

sendQueuedEventsAsync(KeenProject, KeenCallback)

sendQueuedEventsAsync

public void sendQueuedEventsAsync(KeenProject project)

Sends all queued events for the specified project with no callbacks.

Parameters:

project - The project for which to send queued events. If a default project has been set on the client this parameter may be null, in which case the default project will be used.

See Also:

sendQueuedEventsAsync(KeenProject, KeenCallback)

sendQueuedEventsAsync

public void sendQueuedEventsAsync(KeenProject project,
                                  KeenCallback callback)

Asynchronously sends all queued events for the given project. This method will request that the Keen client's Executor executes the publish operation.

Parameters:

project - The project for which to send queued events. If a default project has been set on the client this parameter may be null, in which case the default project will be used.

callback - An optional callback to receive notification of success or failure.

getJsonHandler

public KeenJsonHandler getJsonHandler()

Gets the JSON handler for this client.

Returns:

The KeenJsonHandler.

getEventStore

public KeenEventStore getEventStore()

Gets the event store for this client.

Returns:

The KeenEventStore.

getPublishExecutor

public java.util.concurrent.Executor getPublishExecutor()

Gets the executor for asynchronous publishing for this client.

Returns:

The Executor.

getDefaultProject

public KeenProject getDefaultProject()

Gets the default project that this KeenClient will use if no project is specified.

Returns:

The default project.

setDefaultProject

public void setDefaultProject(KeenProject defaultProject)

Sets the default project that this KeenClient should use if no project is specified.

Parameters:

defaultProject - The new default project.

getBaseUrl

public java.lang.String getBaseUrl()

Gets the base API URL associated with this instance of the KeenClient.

Returns:

The base API URL

setBaseUrl

public void setBaseUrl(java.lang.String baseUrl)

Sets the base API URL associated with this instance of the KeenClient.

Use this if you want to disable SSL.

Parameters:

baseUrl - The new base URL (i.e. 'http://api.keen.io'), or null to reset the base URL to the default ('https://api.keen.io').

setMaxAttempts

public void setMaxAttempts(int maxAttempts)

Sets the maximum number of HTTPS POST retry attempts for all events added in the future.

Parameters:

maxAttempts - the maximum number attempts

getMaxAttempts

public int getMaxAttempts()

Sets the maximum number of HTTPS POST retry attempts for all events added in the future.

Returns:

the maximum number attempts

getGlobalPropertiesEvaluator

public GlobalPropertiesEvaluator getGlobalPropertiesEvaluator()

Gets 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:

      KeenClient client = KeenClient.client();
     GlobalPropertiesEvaluator evaluator = new GlobalPropertiesEvaluator() {
         public Map<String, Object> getGlobalProperties(String eventCollection) {
             Map<String, Object> map = new HashMap<String, Object>();
             map.put("some dynamic property name", "some dynamic property value");
             return map;
         }
     };
     client.setGlobalPropertiesEvaluator(evaluator);
     
 

Parameters:

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

getGlobalProperties

public java.util.Map<java.lang.String,java.lang.Object> getGlobalProperties()

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

Returns:

The Global Properties map.

setGlobalProperties

public void setGlobalProperties(java.util.Map<java.lang.String,java.lang.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<String, Object> map = new HashMap<String, Object>();
 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.

isDebugMode

public boolean isDebugMode()

Gets whether or not the Keen client is running in debug mode.

Returns:

true if debug mode is enabled, otherwise false.

setDebugMode

public void setDebugMode(boolean isDebugMode)

Sets whether or not the Keen client should run in debug mode. When debug mode is enabled, all exceptions will be thrown immediately; otherwise they will be logged and reported to any callbacks, but never thrown.

Parameters:

isDebugMode - true to enable debug mode, or false to disable it.

isActive

public boolean isActive()

Gets whether or not the client is in active mode.

Returns:

true if the client is active,; false if it is inactive.

setProxy

public void setProxy(java.lang.String proxyHost,
                     int proxyPort)

Sets an HTTP proxy server configuration for this client.

Parameters:

proxyHost - The proxy hostname or IP address.

proxyPort - The proxy port number.

setProxy

public void setProxy(java.net.Proxy proxy)

Sets an HTTP proxy server configuration for this client.

Parameters:

proxy - The Proxy object to set.

getProxy

public java.net.Proxy getProxy()

Gets the client Proxy.

Returns:

the proxy.

setActive

protected void setActive(boolean isActive)

Sets whether or not the client is in active mode. When the client is inactive, all requests will be ignored.

Parameters:

isActive - true to make the client active, or false to make it inactive.

validateAndBuildEvent

protected java.util.Map<java.lang.String,java.lang.Object> validateAndBuildEvent(KeenProject project,
                                                                                 java.lang.String eventCollection,
                                                                                 java.util.Map<java.lang.String,java.lang.Object> event,
                                                                                 java.util.Map<java.lang.String,java.lang.Object> keenProperties)

Validates an event and inserts global properties, producing a new event object which is ready to be published to the Keen service.

Parameters:

project - The project in which the event will be published.

eventCollection - The name of the collection in which the event will be published.

event - A Map that consists of key/value pairs.

keenProperties - A Map that consists of key/value pairs to override default properties.

Returns:

A new event Map containing Keen properties and global properties.