Consumers instead of methods with many parameters (#8)

* reworked the methods with many arguments into consumer ones * fixed wrong message properties being set * tests for new syntax, added license headers * test in pure Java, fixed minor bugs * clean up, left legacy spec with context per feature * bean instantiation test * groovy spec refactoring * finished documentation, message hooks * keeping the changelog more concise
agorapulse · Jul 14, 2021 · 1789dfd · 1789dfd
1 parent f1e222d
commit 1789dfd
Show file tree

Hide file tree

Showing 35 changed files with 3,216 additions and 974 deletions.
diff --git a/build.gradle b/build.gradle
@@ -104,6 +104,9 @@ config {
                 enabled = false
             }
         }
+        sourceHtml {
+            enabled = false
+        }
     }
 
 }
@@ -133,21 +136,33 @@ gradleProjects {
             dependencies {
                 annotationProcessor platform("io.micronaut:micronaut-bom:$micronautVersion")
                 annotationProcessor "io.micronaut:micronaut-inject-java"
+                annotationProcessor "io.micronaut:micronaut-validation"
 
                 api platform("io.micronaut:micronaut-bom:$micronautVersion")
-                api "io.micronaut:micronaut-runtime-groovy"
                 api "io.micronaut:micronaut-validation"
 
                 compileOnly "io.micronaut:micronaut-inject-groovy"
 
-                testImplementation("org.spockframework:spock-core") {
+                testAnnotationProcessor platform("io.micronaut:micronaut-bom:$micronautVersion")
+                testAnnotationProcessor "io.micronaut:micronaut-inject-java"
+
+                testImplementation("org.spockframework:spock-core:$spockVersion") {
                     exclude group: "org.codehaus.groovy", module: "groovy-all"
                 }
 
                 testImplementation "io.micronaut.test:micronaut-test-spock"
                 testImplementation "io.micronaut:micronaut-inject-groovy"
                 testImplementation 'net.bytebuddy:byte-buddy:1.10.1'
                 testImplementation 'org.objenesis:objenesis:3.0.1'
+
+                testImplementation "org.junit.jupiter:junit-jupiter-api"
+                testImplementation "io.micronaut.test:micronaut-test-junit5"
+                testImplementation 'org.mockito:mockito-core:3.11.2'
+                testRuntimeOnly "org.junit.jupiter:junit-jupiter-engine"
+            }
+
+            test {
+                useJUnitPlatform()
             }
 
             // useful for Micronaut

diff --git a/docs/guide/guide.gradle b/docs/guide/guide.gradle
@@ -1,7 +1,7 @@
 /*
  * SPDX-License-Identifier: Apache-2.0
  *
- * Copyright 2019-2021 Agorapulse.
+ * Copyright 2020-2021 Agorapulse.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,6 +15,10 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+plugins {
+    id 'org.kordamp.gradle.guide'
+    id 'org.ajoberstar.git-publish'
+}
 
 config {
     docs {

diff --git a/docs/guide/src/docs/asciidoc/configuration.adoc b/docs/guide/src/docs/asciidoc/configuration.adoc
@@ -6,8 +6,9 @@ You need to provide `segment.api-key` configuration property to send information
 
 [source,yaml]
 ----
-segment:
-    api-key: some-key
+include::{root-dir}/libs/micronaut-segment/src/test/resources/application-example.yml[]
 ----
+<1> Segment API key is required if you want to send records to Segment but can be ignored in the development environment
+<2> The legacy default options `id`, `language`, `user-agent` or `intercom`, use <<Message Transformation>> instead
 
 You can rely on `SegmentService` bean being always present but if the API key is missing then no-op implementation is provided.
diff --git a/docs/guide/src/docs/asciidoc/index.adoc b/docs/guide/src/docs/asciidoc/index.adoc
@@ -25,6 +25,3 @@ To report any bug, please, use the project http://github.com/agorapulse/micronau
 = Links
 
 link:api/index.html[Javadoc, window="_blank"]
-
-link:api-html/index.html[Source, window="_blank"]
-
diff --git a/docs/guide/src/docs/asciidoc/installation.adoc b/docs/guide/src/docs/asciidoc/installation.adoc
@@ -4,14 +4,18 @@
 
 Micronaut Segment is available in the Maven Central repository.
 
-[source,groovy]
+[source,indent=0,role="primary",subs='verbatim,attributes']
+.Gradle
+----
+api 'com.agorapulse:micronaut-segment:{project-version}'
 ----
-repositories {
-    mavenCentral()
-}
 
-dependencies {
-    // load just simple implementation with POJO client and reflection based parser
-    implementation 'com.agorapulse:micronaut-segment:{project-version}'
-}
+[source,xml,indent=0,role="secondary",subs='verbatim,attributes']
+.Maven
+----
+<dependency>
+    <groupId>com.agorapulse</groupId>
+    <artifactId>micronaut-segment</artifactId>
+    <version>{project-version}</version>
+</dependency>
 ----
diff --git a/docs/guide/src/docs/asciidoc/introduction.adoc b/docs/guide/src/docs/asciidoc/introduction.adoc
@@ -2,12 +2,11 @@
 [[_introduction]]
 = Introduction
 
-**Micronaut Segment** library allows you to integrate http://segment.com[Segment] in your https://micronaut.io[Micronaut] or https://grails.org[Grails] applications.
+**Micronaut Segment** library allows you to integrate http://segment.com[Segment] into your https://micronaut.io[Micronaut] or https://grails.org[Grails] applications.
 
-Segment lets you send your analytics data to any service you want, without you having to integrate with each one individually.
+http://segment.com[Segment] lets you send your analytics data to any service you want, without having to integrate with each one individually.
 
-It provides the following beans:
+The library provides the following beans:
 
  * `Analytics` - official https://segment.com/docs/libraries/java/[Segment Analytics for Java library] analytics services
  * `SegmentService` - A server side service client to call https://segment.com/docs/libraries/http/[Segment APIs], which is a wrapper around the official https://segment.com/docs/libraries/java/[Segment Analytics for Java library].
-
diff --git a/docs/guide/src/docs/asciidoc/usage.adoc b/docs/guide/src/docs/asciidoc/usage.adoc
@@ -2,12 +2,31 @@
 [[_usage]]
 = Usage
 
+== Segment Service
 
-== SegmentService
+You can inject `SegmentService` into your beans in order to call https://segment.com/docs/libraries/[Segment APIs].
+The bean is always present but no-op implementation is injected when the Segment API key is missing in the configuration.
 
-You can inject _SegmentService_ into your beans in order to call https://segment.com/docs/libraries/[Segment APIs].
+Contrary to the native `Analytics` builder methods, all the methods in the `SegmentService` accepts maps with `null` values
+or `null` values in general. `null` arguments are ignored and maps containing `null` values are cleaned up.
 
-[source,groovy]
+[source,java,role=primary]
+.Java
+----
+@Singleton
+public class MyService {
+
+    private final SegmentService segmentService;
+
+    public MyService(SegmentService segmentService) {
+        this.segmentService = segmentService;
+    }
+
+}
+----
+
+[source,groovy,role=secondary]
+.Groovy
 ----
 @Singleton
 class MyService {
@@ -18,88 +37,137 @@ class MyService {
         this.segmentService = segmentService
     }
 
-    void analyzeUsers() {
-
-        // Identify and set traits
-        segmentService.identify('bob@bob.com', [gender: 'male'])
-
-        // Identify and set traits with past date (JodaTime DateTime representing when the identify took place)
-        segmentService.identify(
-            'bob@bob.com',
-            [gender: 'male'],
-            new DateTime(2012, 3, 26, 12, 0, 0, 0)
-        )
-
-        // Identify and set traits with past date and context
-        segmentService.identify(
-            'bob@bob.com', [gender: 'male'],
-            new DateTime(2012, 3, 26, 12, 0, 0, 0),
-            [
-                integrations: [
-                    'All': false,
-                    'Mixpanel': true,
-                    'KISSmetrics': true
-                ],
-                ip: '192.168.0.10'
-            ]
-        )
-
-        // Track an event
-        segmentService.track('bob@bob.com', 'Signed up')
-
-        // Track an event and set properties
-        segmentService.track(
-            'bob@bob.com',
-            'Signed up',
-            [plan: 'Pro', amount: 99.95]
-        )
-
-        // Track a past event and set properties with past date
-        segmentService.track(
-            'bob@bob.com', 'Signed up',
-            [plan: 'Pro', amount: 99.95],
-            new DateTime(2012, 3, 26, 12, 0, 0, 0)
-        )
-
-        // Track a past event and set properties with past date and context
-        segmentService.track(
-            'bob@bob.com',
-            'Signed up',
-            [plan: 'Pro', amount: 99.95],
-            new DateTime(2012, 3, 26, 12, 0, 0, 0),
-            [
-                integrations: [
-                    'All': false,
-                    'Mixpanel': true,
-                    'KISSmetrics': true
-                ],
-                ip: '192.168.0.10'
-            ]
-        )
-
-        // Group
-        segmentService.group('bob@bob.com', 'companyId', [
-            name: 'The company name',
-            website: 'http://www.company.com'
-        ])
-
-        // Record page view
-        segmentService.page('bob@bob.com', 'Pricing')
-
-        // Record page view with extra info
-        segmentService.page('bob@bob.com', 'Pricing', 'Business', [
-            title: 'Segment.io Pricing',
-            path: '/pricing'
-        ])
-
-        // Record screen view
-        segmentService.screen('bob@bob.com', 'Register', 'Business', [
-            type: 'facebook'
-        ])
-
-        // Alias identity
-        segmentService.alias('bob@bob.com', 'bob')
-    }
 }
 ----
 
+=== Creating Aliases
+
+You can alias existing user to another ID.
+
+See the https://segment.com/docs/connections/sources/catalog/libraries/server/java/#alias[documentation] for the further information.
+
+[source,java,role=primary]
+.Java
+----
+include::{root-dir}/libs/micronaut-segment/src/test/groovy/com/agorapulse/micronaut/segment/SegmentServiceTest.java[tag=alias,indent=0]
+----
+
+[source,groovy,role=secondary]
+.Groovy
+----
+include::{root-dir}/libs/micronaut-segment/src/test/groovy/com/agorapulse/micronaut/segment/SegmentServiceSpec.groovy[tag=alias,indent=0]
+----
+
+=== Group Association
+
+You can associate a user with a group, including advanced properties.
+
+See the https://segment.com/docs/connections/sources/catalog/libraries/server/java/#group[documentation] for the further information.
+
+[source,java,role=primary]
+.Java
+----
+include::{root-dir}/libs/micronaut-segment/src/test/groovy/com/agorapulse/micronaut/segment/SegmentServiceTest.java[tag=group,indent=0]
+----
+
+[source,groovy,role=secondary]
+.Groovy
+----
+include::{root-dir}/libs/micronaut-segment/src/test/groovy/com/agorapulse/micronaut/segment/SegmentServiceSpec.groovy[tag=group,indent=0]
+----
+
+=== Identification
+
+You can identify users with their traits.
+
+See the https://segment.com/docs/connections/sources/catalog/libraries/server/java/#identify[documentation] for the further information.
+
+[source,java,role=primary]
+.Java
+----
+include::{root-dir}/libs/micronaut-segment/src/test/groovy/com/agorapulse/micronaut/segment/SegmentServiceTest.java[tag=identify,indent=0]
+----
+
+[source,groovy,role=secondary]
+.Groovy
+----
+include::{root-dir}/libs/micronaut-segment/src/test/groovy/com/agorapulse/micronaut/segment/SegmentServiceSpec.groovy[tag=identify,indent=0]
+----
+
+=== Page Views
+
+You can record page view by the user with additional properties.
+
+See the https://segment.com/docs/connections/sources/catalog/libraries/server/java/#page[documentation] for the further information.
+
+[source,java,role=primary]
+.Java
+----
+include::{root-dir}/libs/micronaut-segment/src/test/groovy/com/agorapulse/micronaut/segment/SegmentServiceTest.java[tag=page,indent=0]
+----
+
+[source,groovy,role=secondary]
+.Groovy
+----
+include::{root-dir}/libs/micronaut-segment/src/test/groovy/com/agorapulse/micronaut/segment/SegmentServiceSpec.groovy[tag=page,indent=0]
+----
+
+=== Screen Views
+
+You can record screen view by the user with additional properties.
+
+See the https://segment.com/docs/connections/sources/catalog/libraries/server/java/#screen[documentation] for the further information.
+
+[source,java,role=primary]
+.Java
+----
+include::{root-dir}/libs/micronaut-segment/src/test/groovy/com/agorapulse/micronaut/segment/SegmentServiceTest.java[tag=screen,indent=0]
+----
+
+[source,groovy,role=secondary]
+.Groovy
+----
+include::{root-dir}/libs/micronaut-segment/src/test/groovy/com/agorapulse/micronaut/segment/SegmentServiceSpec.groovy[tag=screen,indent=0]
+----
+=== Tracking Events
+
+You can track user events with additional properties.
+
+See the https://segment.com/docs/connections/sources/catalog/libraries/server/java/#track[documentation] for the further information.
+
+[source,java,role=primary]
+.Java
+----
+include::{root-dir}/libs/micronaut-segment/src/test/groovy/com/agorapulse/micronaut/segment/SegmentServiceTest.java[tag=track,indent=0]
+----
+
+[source,groovy,role=secondary]
+.Groovy
+----
+include::{root-dir}/libs/micronaut-segment/src/test/groovy/com/agorapulse/micronaut/segment/SegmentServiceSpec.groovy[tag=track,indent=0]
+----
+
+== Customization
+
+You can declare message transformers and interceptors. They are only taken into account when the real
+implementation is used. They are ignored when no-op implementation is used.
+
+=== Message Transformation
+
+You can declare `MessageTransformer` beans to change the payload before sending. Here is the example of transformer which adds default value if not present:
+
+[source,java]
+.Java
+----
+include::{root-dir}/libs/micronaut-segment/src/test/groovy/com/agorapulse/micronaut/segment/DefaultContextMessageTransformer.java[tag=body]
+----
+
+=== Message Interceptors
+
+You can declare `MessageInterceptor` beans to intercept sending of the messages. Here is an example of the interceptor which holds the latest message sent:
+[source,java]
+.Java
+----
+include::{root-dir}/libs/micronaut-segment/src/test/groovy/com/agorapulse/micronaut/segment/LastMessageHolder.java[tag=body]
+----
+
diff --git a/gradle.properties b/gradle.properties
@@ -24,5 +24,9 @@ slug = agorapulse/micronaut-segment
 kordampPluginVersion=0.46.0
 micronautVersion = 1.3.7
 nexusPluginVersion = 1.0.0
+gitPublishVersion = 2.1.3
 
 segmentLibrariesVersion = 3.1.3
+
+groovySupportVersion = 0.6.3
+spockVersion=2.0-groovy-2.5
diff --git a/libs/micronaut-segment/micronaut-segment.gradle b/libs/micronaut-segment/micronaut-segment.gradle
@@ -17,4 +17,5 @@
  */
 dependencies {
     api "com.segment.analytics.java:analytics:$segmentLibrariesVersion"
+    api "space.jasan:groovy-closure-support:$groovySupportVersion"
 }