Merge pull request #117 from keenlabs/pbuchman-cached-datasets

Support for cached datasets

Author: piotrek-buchman

README.md

@@ -20,14 +20,14 @@ repositories {
     mavenCentral()
 }
 dependencies {
-    compile 'io.keen:keen-client-api-java:5.3.0'
+    compile 'io.keen:keen-client-api-java:5.4.0'
 }
 ```
 
 For Android, use:
 
 ```groovy
-    compile 'io.keen:keen-client-api-android:5.3.0@aar'
+    compile 'io.keen:keen-client-api-android:5.4.0@aar'
 ```
 
 ### Maven
@@ -38,7 +38,7 @@ Paste the following snippet into your pom.xml:
 <dependency>
   <groupId>io.keen</groupId>
   <artifactId>keen-client-api-java</artifactId>
-  <version>5.3.0</version>
+  <version>5.4.0</version>
 </dependency>
 ```
 
@@ -271,7 +271,7 @@ like to use the query client then you will need to ensure that you also have the
 
 ```groovy
 dependencies {
-    compile 'io.keen:keen-client-api-query:5.3.0' 
+    compile 'io.keen:keen-client-api-query:5.4.0' 
 }
 ```
 
@@ -283,7 +283,7 @@ Paste the following snippet into your pom.xml:
 <dependency>
   <groupId>io.keen</groupId>
   <artifactId>keen-client-api-query</artifactId>
-  <version>5.3.0</version>
+  <version>5.4.0</version>
 </dependency>
 ```
 
@@ -610,6 +610,81 @@ updateEventCollection.put("query", queryUpdates);
 updateResponse = savedQueryApi.updateQuery("cached-query-name", updateEventCollection);
 ```
 
+### Cached Datasets
+
+Cached Datasets are a powerful way for you to build applications with charts and tables that load instantly, 
+even as your Streams volume grows. Conceptually similar to Cached Queries, a Cached Dataset additionally allows 
+you to retrieve results indexed by properties like customer, cohort, article, campaign and more. 
+
+To work with [Cached Datasets](https://keen.io/docs/api/#cached-datasets), create a `KeenQueryClient` as normal, 
+then use it to create a `CachedDatasets` implementation:
+
+```java
+KeenQueryClient queryClient = ...;
+CachedDatasets cachedDatasets = queryClient.getCachedDatasetsClient();
+```
+
+Please notice, that Cached Datasets are [Early Release](https://intercom.help/keen/setup-help/what-does-early-release-mean) 
+and there still some major improvements pending (example: server side error handling). 
+
+#### Creating a Cached Dataset
+
+Depending on your needs you can adjust the query. Please see [Cached Dataset API Reference](https://keen.io/docs/api/#cached-datasets/) for details.
+This example shows the most complicated usage pattern: multi analysis with multiple indexes. 
+
+```java
+String datasetName = "new-project-members";
+String displayName = "New Project Members";
+Collection<String> indexBy = asList("organization.id", "project.is_external");
+
+DatasetQuery datasetQuery = DatasetQueryBuilder
+        .aDatasetQuery()
+        .withAnalysisType("multi_analysis")
+        .withAnalyses(asList(new SubAnalysis("total count", QueryType.COUNT), new SubAnalysis("unique users", QueryType.SELECT_UNIQUE, "user.email")))
+        .withEventCollection("new_project_member")
+        .withFilters(singletonList(new Filter("organization.tag", FilterOperator.EQUAL_TO, "opensource")))
+        .withTimeframe("this_6_months")
+        .withTimezone("UTC")
+        .withInterval("monthly")
+        .build();
+
+DatasetDefinition datasetDefinition = cachedDatasets.create(datasetName, displayName, datasetQuery, indexBy);
+```
+ 
+#### Getting a Dataset Definition
+
+```java
+DatasetDefinition datasetDefinition = cachedDatasets.getDefinition("new-project-members");
+```  
+ 
+#### Retrieving results from a Cached Dataset
+
+```java
+DatasetDefinition datasetDefinition = ...
+
+List<IntervalResultValue> results = cachedDatasets.getResults(
+        datasetDefinition,
+        new HashMap<String, Object>() {{
+            put("organization.id", "the-penguins");
+            put("project.is_external", true);
+        }},
+        new RelativeTimeframe("this_3_months")
+);
+```  
+
+#### Listing Cached Dataset Definitions for Project
+
+```java
+List<DatasetDefinition> definitions = cachedDatasets.getDefinitions(30, "the-name-of-last-skipped-dataset");
+```
+
+#### Deleting a Cached Dataset
+
+```java
+boolean success = cachedDatasets.delete("new-project-members");
+```
+
+
 ### Utility Methods
 
 There are also some utility methods to add filters and timeframes to a `Query`:
@@ -765,6 +840,8 @@ If you are not trying to build the Android client, you can remove `android` from
 
         sdk.dir=<Android SDK path>
 
+If you use Intellij IDE, the `local.properties` file should be created in a root directory of the project.
+
 #### "RuntimeException: Stub!" error in JUnit tests
 
 This is usually caused by the Android SDK being before JUnit in your classpath. (Android includes a stubbed version of JUnit.) To fix this, move JUnit ahead of the Android SDK so it gets picked up first.
@@ -793,6 +870,14 @@ client.addEvent("collection-name", event, keenProperties);
 
 ## Changelog
 
+##### 5.4.0
+
++ Added support for Cached Datasets
++ Added toString, equals and hashCode for objects representing definitions and results of queries/datasets
++ Replaced generation of KeenVersion.java with validation whether committed file got updated manually (faster development in Intellij)
++ Added detailed, optional debug messages for both requests and responses.
++ Minor, backward compatible refactoring  
+
 ##### 5.3.0
 
 + Added withReadTimeout and withConnectTimeout methods to both KeenQueryClient.Builder and KeenClient.Builder

core/build.gradle

@@ -12,31 +12,17 @@ tasks.withType(JavaCompile) {
     options.compilerArgs << "-source" << "1.6" << "-target" << "1.6"
 }
 
-// Build up a KeenVersion.java akin to the Android BuildConfig.java, but available in all projects.
-// We set Implementation-Version on the Manifest, but reading Package.getImplementationVersion()
-// on the core Package seems return null in the Android client, so instead generate this. Also, the
-// Manifest info isn't set for unit tests.
-task generateVersionFile {
-    def outputDir = file("$buildDir/generated/source")
-    outputs.dir outputDir
+task verifyVersionFile {
+    def versionFile = file("$projectDir/src/main/java/io/keen/client/java/KeenVersion.java")
 
     doFirst {
-        def srcFile = new File(outputDir, "io/keen/client/java/KeenVersion.java")
-        srcFile.parentFile.mkdirs()
-        srcFile.write("""
-            package io.keen.client.java;
-            public class KeenVersion {
-                private static final String SDK_VERSION = "$project.version";
-
-                private KeenVersion() {}
-                public static String getSdkVersion() { return SDK_VERSION; }
-            }
-        """)
+        if (!versionFile.text.contains("SDK_VERSION = \"$project.version\"")) {
+            throw new IllegalStateException("Project version set in KeenVersion.java does not match version set in gradle.properties")
+        }
     }
 }
 
-compileJava.dependsOn generateVersionFile
-compileJava.source generateVersionFile.outputs.files, sourceSets.main.java
+compileJava.dependsOn verifyVersionFile
 
 dependencies {
     testCompile 'com.fasterxml.jackson.core:jackson-databind:2.3.0'

core/src/main/java/io/keen/client/java/KeenVersion.java

@@ -0,0 +1,14 @@
+package io.keen.client.java;
+
+public class KeenVersion {
+
+    private static final String SDK_VERSION = "5.4.0";
+
+    private KeenVersion() {
+    }
+
+    public static String getSdkVersion() {
+        return SDK_VERSION;
+    }
+
+}

gradle.properties

@@ -1,5 +1,5 @@
-VERSION_NAME=5.3.0
-VERSION_CODE=15
+VERSION_NAME=5.4.0
+VERSION_CODE=16
 GROUP=io.keen
 
 POM_URL=www.keen.io

query/build.gradle

@@ -7,14 +7,17 @@ tasks.withType(JavaCompile) {
     options.compilerArgs << "-source" << "1.6" << "-target" << "1.6"
 }
 
+project.evaluationDependsOn(":core")
+
 dependencies {
     compile project(':core')
     compile project(':java')
+    compile 'org.apache.commons:commons-lang3:3.8.1'
     testCompile 'com.fasterxml.jackson.core:jackson-databind:2.3.0'
-    testCompile 'commons-io:commons-io:2.4'
     testCompile 'junit:junit:4.11'
     testCompile 'org.hamcrest:hamcrest-library:1.3'
     testCompile 'org.mockito:mockito-core:1.9.5'
+    testCompile 'pl.pragmatists:JUnitParams:1.1.1'
     testCompile project(':core').sourceSets.test.output
 }
 

query/src/main/java/io/keen/client/java/AbsoluteTimeframe.java

@@ -1,5 +1,10 @@
 package io.keen.client.java;
 
+import org.apache.commons.lang3.builder.EqualsBuilder;
+import org.apache.commons.lang3.builder.HashCodeBuilder;
+import org.apache.commons.lang3.builder.ReflectionToStringBuilder;
+import org.apache.commons.lang3.builder.ToStringStyle;
+
 import java.util.HashMap;
 import java.util.Map;
 
@@ -62,4 +67,19 @@ public Map<String, Object> constructTimeframeArgs() {
 
         return timeframe;
     }
+
+    @Override
+    public String toString() {
+        return ReflectionToStringBuilder.toString(this, ToStringStyle.SHORT_PREFIX_STYLE);
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        return EqualsBuilder.reflectionEquals(this, obj);
+    }
+
+    @Override
+    public int hashCode() {
+        return HashCodeBuilder.reflectionHashCode(this);
+    }
 }