public class KeenClient
extends java.lang.Object
KeenClient provides all of the functionality required to:
To create a KeenClient, use a subclass of KeenClient.Builder
which provides the default interfaces for various operations (HTTP, JSON, queueing, async).
| Modifier and Type | Class and Description |
|---|---|
static class |
KeenClient.Builder
Builder class for instantiating Keen clients.
|
| Modifier | Constructor and Description |
|---|---|
protected |
KeenClient(KeenClient.Builder builder)
Constructs a Keen client using system environment variables.
|
| 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.
|
protected KeenClient(KeenClient.Builder builder)
builder - The builder from which to retrieve this client's interfaces and settings.public static KeenClient client()
KeenClient singleton instance.public static void initialize(KeenClient client)
client - The KeenClient implementation to use as the
singleton client for the library.public static boolean isInitialized()
true if and only if the client has been initialized.public void addEvent(java.lang.String eventCollection,
java.util.Map<java.lang.String,java.lang.Object> event)
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!).addEvent(KeenProject, String, java.util.Map, java.util.Map, KeenCallback)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)
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()addEvent(KeenProject, String, java.util.Map, java.util.Map, KeenCallback)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)
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.public void addEventAsync(java.lang.String eventCollection,
java.util.Map<java.lang.String,java.lang.Object> event)
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!).addEvent(KeenProject, String, java.util.Map, java.util.Map, KeenCallback)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)
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()addEvent(KeenProject, String, java.util.Map, java.util.Map, KeenCallback)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)
Executor executes the publish operation.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.public void queueEvent(java.lang.String eventCollection,
java.util.Map<java.lang.String,java.lang.Object> event)
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!).queueEvent(KeenProject, String, java.util.Map, java.util.Map, KeenCallback)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)
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()queueEvent(KeenProject, String, java.util.Map, java.util.Map, KeenCallback)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)
KeenEventStore until the next call to either
sendQueuedEvents() or sendQueuedEventsAsync().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.public void sendQueuedEvents()
public void sendQueuedEvents(KeenProject project)
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.sendQueuedEvents(KeenProject, KeenCallback)public void sendQueuedEvents(KeenProject project, KeenCallback callback)
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.public void sendQueuedEventsAsync()
public void sendQueuedEventsAsync(KeenProject project)
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.sendQueuedEventsAsync(KeenProject, KeenCallback)public void sendQueuedEventsAsync(KeenProject project, KeenCallback callback)
Executor executes the publish operation.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.public KeenJsonHandler getJsonHandler()
KeenJsonHandler.public KeenEventStore getEventStore()
KeenEventStore.public java.util.concurrent.Executor getPublishExecutor()
Executor.public KeenProject getDefaultProject()
KeenClient will use if no project is specified.public void setDefaultProject(KeenProject defaultProject)
KeenClient should use if no project is specified.defaultProject - The new default project.public java.lang.String getBaseUrl()
KeenClient.public void setBaseUrl(java.lang.String baseUrl)
KeenClient.
Use this if you want to disable SSL.
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').public void setMaxAttempts(int maxAttempts)
maxAttempts - the maximum number attemptspublic int getMaxAttempts()
public GlobalPropertiesEvaluator getGlobalPropertiesEvaluator()
GlobalPropertiesEvaluator associated with this instance of the KeenClient.GlobalPropertiesEvaluatorpublic void setGlobalPropertiesEvaluator(GlobalPropertiesEvaluator globalPropertiesEvaluator)
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);
globalPropertiesEvaluator - The evaluator which is invoked any time an event is added to an event
collection.public java.util.Map<java.lang.String,java.lang.Object> getGlobalProperties()
setGlobalProperties(java.util.Map).public void setGlobalProperties(java.util.Map<java.lang.String,java.lang.Object> globalProperties)
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);
globalProperties - The new map you wish to use as the Keen Global Properties.public boolean isDebugMode()
true if debug mode is enabled, otherwise false.public void setDebugMode(boolean isDebugMode)
isDebugMode - true to enable debug mode, or false to disable it.public boolean isActive()
true if the client is active,; false if it is inactive.public void setProxy(java.lang.String proxyHost,
int proxyPort)
proxyHost - The proxy hostname or IP address.proxyPort - The proxy port number.public void setProxy(java.net.Proxy proxy)
proxy - The Proxy object to set.public java.net.Proxy getProxy()
protected void setActive(boolean isActive)
isActive - true to make the client active, or false to make it
inactive.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)
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.