prepare 5.0.0 release (#195)

Author: LaunchDarklyCI

.circleci/config.yml

@@ -25,11 +25,15 @@ workflows:
       - test-linux:
           name: Java 11 - Linux - OpenJDK
           docker-image: circleci/openjdk:11
+          with-coverage: true
           requires:
             - build-linux
       - packaging:
           requires:
             - build-linux
+      - benchmarks:
+          requires:
+            - build-linux
       - build-test-windows:
           name: Java 11 - Windows - OpenJDK
 
@@ -52,26 +56,44 @@ jobs:
     parameters:
       docker-image:
         type: string
+      with-coverage:
+        type: boolean
+        default: false
     docker:
       - image: <<parameters.docker-image>>
-      - image: redis
     steps:
       - checkout
       - run: cp gradle.properties.example gradle.properties
       - attach_workspace:
           at: build
       - run: java -version
-      - run: ./gradlew test
+      - run:
+          name: Run tests
+          command: ./gradlew test
+      - when:
+          condition: <<parameters.with-coverage>>
+          steps:
+            - run:
+                name: Generate test coverage report
+                command: |
+                  ./gradlew jacocoTestReport
+                  mkdir -p coverage/
+                  cp -r build/reports/jacoco/test/* ./coverage
       - run:
           name: Save test results
           command: |
-            mkdir -p ~/junit/;
+            mkdir -p ~/junit/
             find . -type f -regex ".*/build/test-results/.*xml" -exec cp {} ~/junit/ \;
           when: always
       - store_test_results:
           path: ~/junit
       - store_artifacts:
           path: ~/junit
+      - when:
+          condition: <<parameters.with-coverage>>
+          steps:
+            - store_artifacts:
+                path: coverage
 
   build-test-windows:
     executor:
@@ -85,18 +107,6 @@ jobs:
             $ProgressPreference = "SilentlyContinue"  # prevents console errors from CircleCI host
             iwr -outf openjdk.msi https://developers.redhat.com/download-manager/file/java-11-openjdk-11.0.5.10-2.windows.redhat.x86_64.msi
             Start-Process msiexec.exe -Wait -ArgumentList '/I openjdk.msi /quiet'
-      - run:
-          name: start Redis
-          command: |
-            $ProgressPreference = "SilentlyContinue"
-            iwr -outf redis.zip https://github.com/MicrosoftArchive/redis/releases/download/win-3.0.504/Redis-x64-3.0.504.zip
-            mkdir redis
-            Expand-Archive -Path redis.zip -DestinationPath redis
-            cd redis
-            .\redis-server --service-install
-            .\redis-server --service-start
-            Start-Sleep -s 5
-            .\redis-cli ping
       - run:
           name: build and test
           command: |
@@ -131,3 +141,19 @@ jobs:
       - run:
           name: run packaging tests
           command: cd packaging-test && make all
+
+  benchmarks:
+    docker:
+      - image: circleci/openjdk:11
+    steps:
+      - run: java -version
+      - run: sudo apt-get install make -y -q
+      - checkout
+      - attach_workspace:
+          at: build
+      - run: cat gradle.properties.example >>gradle.properties
+      - run:
+          name: run benchmarks
+          command: cd benchmarks && make
+      - store_artifacts:
+          path: benchmarks/build/reports/jmh

.gitignore

@@ -17,3 +17,4 @@ out/
 classes/
 
 packaging-test/temp/
+benchmarks/lib/

.ldrelease/config.yml

@@ -10,8 +10,11 @@ publications:
 
 template:
   name: gradle
-  env:
-    LD_SKIP_DATABASE_TESTS: 1
+
+releasableBranches:
+  - name: master
+    description: 5.x
+  - name: 4.x
 
 documentation:
   githubPages: true

CONTRIBUTING.md

@@ -1,5 +1,4 @@
-Contributing to the LaunchDarkly Server-side SDK for Java
-================================================
+# Contributing to the LaunchDarkly Server-side SDK for Java
 
 LaunchDarkly has published an [SDK contributor's guide](https://docs.launchdarkly.com/docs/sdk-contributors-guide) that provides a detailed explanation of how our SDKs work. See below for additional information on how to contribute to this SDK.
 
@@ -15,8 +14,10 @@ We encourage pull requests and other contributions from the community. Before su
 
 ### Prerequisites
 
-The SDK builds with [Gradle](https://gradle.org/) and should be built against Java 7.
- 
+The SDK builds with [Gradle](https://gradle.org/) and should be built against Java 8.
+
+Many basic classes are implemented in the module `launchdarkly-java-sdk-common`, whose source code is in the [`launchdarkly/java-sdk-common`](https://github.com/launchdarkly/java-sdk-common) repository; this is so the common code can be shared with the LaunchDarkly Android SDK. By design, the LaunchDarkly Java SDK distribution does not expose a dependency on that module; instead, its classes and Javadoc content are embedded in the SDK jars.
+
 ### Building
 
 To build the SDK without running any tests:
@@ -41,4 +42,28 @@ To build the SDK and run all unit tests:
 ./gradlew test
 ```
 
-By default, the full unit test suite includes live tests of the Redis integration. Those tests expect you to have Redis running locally. To skip them, set the environment variable `LD_SKIP_DATABASE_TESTS=1` before running the tests.
+### Benchmarks
+
+The project in the `benchmarks` subdirectory uses [JMH](https://openjdk.java.net/projects/code-tools/jmh/) to generate performance metrics for the SDK. This is run as a CI job, and can also be run manually by running `make` within `benchmarks` and then inspecting `build/reports/jmh`.
+
+## Coding best practices
+
+### Logging
+
+Currently the SDK uses SLF4J for all log output. Here some things to keep in mind for good logging behavior:
+
+1. Stick to the standardized logger name scheme defined in `Loggers.java`, preferably for all log output, but definitely for all log output above `DEBUG` level. Logger names can be useful for filtering log output, so it is desirable for users to be able to reference a clear, stable logger name like `com.launchdarkly.sdk.server.LDClient.Events` rather than a class name like `com.launchdarkly.sdk.server.EventSummarizer` which is an implementation detail. The text of a log message should be distinctive enough that we can easily find which class generated the message.
+
+2. Use parameterized messages (`Logger.MAIN.info("The value is {}", someValue)`) rather than string concatenation (`Logger.MAIN.info("The value is " + someValue)`). This avoids the overhead of string concatenation if the logger is not enabled for that level. If computing the value is an expensive operation, and it is _only_ relevant for logging, consider implementing that computation via a custom `toString()` method on some wrapper type so that it will be done lazily only if the log level is enabled.
+
+3. Exception stacktraces should only be logged at debug level. For instance: `Logger.MAIN.warn("An error happened: {}", ex.toString()); Logger.MAIN.debug(ex.toString(), ex)`. Also, consider whether the stacktrace would be at all meaningful in this particular context; for instance, in a `try` block around a network I/O operation, the stacktrace would only tell us (a) some internal location in Java standard libraries and (b) the location in our own code where we tried to do the operation; (a) is very unlikely to tell us anything that the exception's type and message doesn't already tell us, and (b) could be more clearly communicated by just writing a specific log message.
+
+### Code coverage
+
+It is important to keep unit test coverage as close to 100% as possible in this project. You can view the latest code coverage report in CircleCI, as `coverage/html/index.html` in the artifacts for the "Java 11 - Linux - OpenJDK" job. You can also run the report locally with `./gradlew jacocoTestCoverage` and view `./build/reports/jacoco/test`. _The CircleCI build will fail if you commit a change that increases the number of uncovered lines_, unless you explicitly add an override as shown below.
+
+Sometimes a gap in coverage is unavoidable, usually because the compiler requires us to provide a code path for some condition that in practice can't happen and can't be tested, or because of a known issue with the code coverage tool. Please handle all such cases as follows:
+
+* Mark the code with an explanatory comment beginning with "COVERAGE:".
+* Run the code coverage task with `./gradlew jacocoTestCoverageVerification`. It should fail and indicate how many lines of missed coverage exist in the method you modified.
+* Add an item in the `knownMissedLinesForMethods` map in `build.gradle` that specifies that number of missed lines for that method signature. For instance, if the method `com.launchdarkly.sdk.server.SomeClass.someMethod(java.lang.String)` has two missed lines that cannot be covered, you would add `"SomeClass.someMethod(java.lang.String)": 2`.

README.md

@@ -1,72 +1,61 @@
-LaunchDarkly Server-side SDK for Java
-=========================
+# LaunchDarkly Server-side SDK for Java
 
 [![Circle CI](https://circleci.com/gh/launchdarkly/java-server-sdk.svg?style=shield)](https://circleci.com/gh/launchdarkly/java-server-sdk)
 [![Javadocs](http://javadoc.io/badge/com.launchdarkly/launchdarkly-java-server-sdk.svg)](http://javadoc.io/doc/com.launchdarkly/launchdarkly-java-server-sdk)
 
-LaunchDarkly overview
--------------------------
+## LaunchDarkly overview
+
 [LaunchDarkly](https://www.launchdarkly.com) is a feature management platform that serves over 100 billion feature flags daily to help teams build better software, faster. [Get started](https://docs.launchdarkly.com/docs/getting-started) using LaunchDarkly today!
 
 [![Twitter Follow](https://img.shields.io/twitter/follow/launchdarkly.svg?style=social&label=Follow&maxAge=2592000)](https://twitter.com/intent/follow?screen_name=launchdarkly)
 
-Supported Java versions
------------------------
+## Supported Java versions
 
-This version of the LaunchDarkly SDK works with Java 7 and above.
+This version of the LaunchDarkly SDK works with Java 8 and above.
 
-Distributions
--------------
+## Distributions
 
 Three variants of the SDK jar are published to Maven:
 
-* The default uberjar - this is accessible as `com.launchdarkly:launchdarkly-java-server-sdk:jar` and is the dependency used in the "[Getting started](https://docs.launchdarkly.com/docs/java-sdk-reference#section-getting-started)" section of the SDK reference guide as well as in the [`hello-java`](https://github.com/launchdarkly/hello-java) sample app. This variant contains the SDK classes, and all of the SDK's dependencies except for Gson and SLF4J, which must be provided by the host application. The bundled dependencies have shaded package names (and are not exported in OSGi), so they will not interfere with any other versions of the same packages.
-* The extended uberjar - add `<classifier>all</classifier>` in Maven, or `:all` in Gradle. This is the same as the default uberjar except that Gson and SLF4J are also bundled, without shading (and are exported in OSGi).
+* The default uberjar - this is accessible as `com.launchdarkly:launchdarkly-java-server-sdk:jar` and is the dependency used in the "[Getting started](https://docs.launchdarkly.com/docs/java-sdk-reference#section-getting-started)" section of the SDK reference guide as well as in the [`hello-java`](https://github.com/launchdarkly/hello-java) sample app. This variant contains the SDK classes, and all of the SDK's dependencies except for SLF4J, which must be provided by the host application. The bundled dependencies have shaded package names (and are not exported in OSGi), so they will not interfere with any other versions of the same packages.
+* The extended uberjar - add `<classifier>all</classifier>` in Maven, or `:all` in Gradle. This is the same as the default uberjar except that SLF4J is also bundled, without shading (and is exported in OSGi).
 * The "thin" jar - add `<classifier>thin</classifier>` in Maven, or `:thin` in Gradle. This contains _only_ the SDK classes.
 
-Getting started
------------
+## Getting started
 
 Refer to the [SDK reference guide](https://docs.launchdarkly.com/docs/java-sdk-reference#section-getting-started) for instructions on getting started with using the SDK.
 
-Logging
--------
+## Logging
 
 The LaunchDarkly SDK uses [SLF4J](https://www.slf4j.org/). All loggers are namespaced under `com.launchdarkly`. For an example configuration check out the [hello-java](https://github.com/launchdarkly/hello-java) project.
 
 Be aware of two considerations when enabling the DEBUG log level:
 1. Debug-level logs can be very verbose. It is not recommended that you turn on debug logging in high-volume environments.
 1. Potentially sensitive information is logged including LaunchDarkly users created by you in your usage of this SDK.
 
-Using flag data from a file
----------------------------
+## Using flag data from a file
 
 For testing purposes, the SDK can be made to read feature flag state from a file or files instead of connecting to LaunchDarkly. See <a href="http://javadoc.io/page/com.launchdarkly/launchdarkly-java-server-sdk/latest/com/launchdarkly/client/files/FileComponents.html">FileComponents</a> for more details.
 
-DNS caching issues
-------------------
+## DNS caching issues
 
 LaunchDarkly servers operate in a load-balancing framework which may cause their IP addresses to change. This could result in the SDK failing to connect to LaunchDarkly if an old IP address is still in your system's DNS cache.
 
 Unlike some other languages, in Java the DNS caching behavior is controlled by the Java virtual machine rather than the operating system. The default behavior varies depending on whether there is a [security manager](https://docs.oracle.com/javase/tutorial/essential/environment/security.html): if there is, IP addresses will _never_ expire. In that case, we recommend that you set the security property `networkaddress.cache.ttl`, as described [here](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/java-dg-jvm-ttl.html), to a number of seconds such as 30 or 60 (a lower value will reduce the chance of intermittent failures, but will slightly reduce networking performance).
 
-Learn more
-----------
+## Learn more
 
 Check out our [documentation](https://docs.launchdarkly.com) for in-depth instructions on configuring and using LaunchDarkly. You can also head straight to the [complete reference guide for this SDK](https://docs.launchdarkly.com/docs/java-sdk-reference) or our [code-generated API documentation](https://launchdarkly.github.io/java-server-sdk/).
 
-Testing
--------
+## Testing
 
 We run integration tests for all our SDKs using a centralized test harness. This approach gives us the ability to test for consistency across SDKs, as well as test networking behavior in a long-running application. These tests cover each method in the SDK, and verify that event sending, flag evaluation, stream reconnection, and other aspects of the SDK all behave correctly.
 
-Contributing
-------------
+## Contributing
 
 We encourage pull requests and other contributions from the community. Check out our [contributing guidelines](CONTRIBUTING.md) for instructions on how to contribute to this SDK.
 
-About LaunchDarkly
------------
+## About LaunchDarkly
 
 * LaunchDarkly is a continuous delivery platform that provides feature flags as a service and allows developers to iterate quickly and safely. We allow you to easily flag your features and manage them from the LaunchDarkly dashboard.  With LaunchDarkly, you can:
     * Roll out a new feature to a subset of your users (like a group of users who opt-in to a beta tester group), gathering feedback and bug reports from real-world use cases.

benchmarks/Makefile

@@ -0,0 +1,36 @@
+.PHONY: benchmark clean sdk
+
+BASE_DIR:=$(shell pwd)
+PROJECT_DIR=$(shell cd .. && pwd)
+SDK_VERSION=$(shell grep "version=" $(PROJECT_DIR)/gradle.properties | cut -d '=' -f 2)
+
+BENCHMARK_ALL_JAR=lib/launchdarkly-java-server-sdk-all.jar
+BENCHMARK_TEST_JAR=lib/launchdarkly-java-server-sdk-test.jar
+SDK_JARS_DIR=$(PROJECT_DIR)/build/libs
+SDK_ALL_JAR=$(SDK_JARS_DIR)/launchdarkly-java-server-sdk-$(SDK_VERSION)-all.jar
+SDK_TEST_JAR=$(SDK_JARS_DIR)/launchdarkly-java-server-sdk-$(SDK_VERSION)-test.jar
+
+benchmark: $(BENCHMARK_ALL_JAR) $(BENCHMARK_TEST_JAR)
+	rm -rf build/tmp
+	../gradlew jmh
+	cat build/reports/jmh/human.txt
+	../gradlew jmhReport
+
+clean:
+	rm -rf build lib
+
+sdk: $(BENCHMARK_ALL_JAR) $(BENCHMARK_TEST_JAR)
+
+$(BENCHMARK_ALL_JAR): $(SDK_ALL_JAR)
+	mkdir -p lib
+	cp $< $@
+
+$(BENCHMARK_TEST_JAR): $(SDK_TEST_JAR)
+	mkdir -p lib
+	cp $< $@
+
+$(SDK_ALL_JAR):
+	cd .. && ./gradlew shadowJarAll
+
+$(SDK_TEST_JAR):
+	cd .. && ./gradlew testJar

benchmarks/build.gradle

@@ -0,0 +1,64 @@
+
+buildscript {
+    repositories {
+        jcenter()
+        mavenCentral()
+    }
+}
+
+plugins {
+    id "me.champeau.gradle.jmh" version "0.5.0"
+    id "io.morethan.jmhreport" version "0.9.0"
+}
+
+repositories {
+    mavenCentral()
+}
+
+ext.versions = [
+    "jmh": "1.21",
+    "guava": "19.0"
+]
+
+dependencies {
+    compile files("lib/launchdarkly-java-server-sdk-all.jar")
+    compile files("lib/launchdarkly-java-server-sdk-test.jar")
+    compile "com.google.code.gson:gson:2.7"
+    compile "com.google.guava:guava:${versions.guava}" // required by SDK test code
+    compile "com.squareup.okhttp3:mockwebserver:3.12.10"
+    compile "org.openjdk.jmh:jmh-core:1.21"
+    compile "org.openjdk.jmh:jmh-generator-annprocess:${versions.jmh}"
+}
+
+jmh {
+    iterations = 10 // Number of measurement iterations to do.
+    benchmarkMode = ['avgt'] // "average time" - reports execution time as ns/op and allocations as B/op.
+    // batchSize = 1 // Batch size: number of benchmark method calls per operation. (some benchmark modes can ignore this setting)
+    fork = 1 // How many times to forks a single benchmark. Use 0 to disable forking altogether
+    // failOnError = false // Should JMH fail immediately if any benchmark had experienced the unrecoverable error?
+    forceGC = true // Should JMH force GC between iterations?
+    humanOutputFile = project.file("${project.buildDir}/reports/jmh/human.txt") // human-readable output file
+    // resultsFile = project.file("${project.buildDir}/reports/jmh/results.txt") // results file
+    operationsPerInvocation = 3 // Operations per invocation.
+    // benchmarkParameters =  [:] // Benchmark parameters.
+    profilers = [ 'gc' ] // Use profilers to collect additional data. Supported profilers: [cl, comp, gc, stack, perf, perfnorm, perfasm, xperf, xperfasm, hs_cl, hs_comp, hs_gc, hs_rt, hs_thr]
+    timeOnIteration = '1s' // Time to spend at each measurement iteration.
+    resultFormat = 'JSON' // Result format type (one of CSV, JSON, NONE, SCSV, TEXT)
+    // synchronizeIterations = false // Synchronize iterations?
+    // threads = 4 // Number of worker threads to run with.
+    // timeout = '1s' // Timeout for benchmark iteration.
+    timeUnit = 'ns' // Output time unit. Available time units are: [m, s, ms, us, ns].
+    verbosity = 'NORMAL' // Verbosity mode. Available modes are: [SILENT, NORMAL, EXTRA]
+    warmup = '1s' // Time to spend at each warmup iteration.
+    warmupBatchSize = 2 // Warmup batch size: number of benchmark method calls per operation.
+    warmupIterations = 1 // Number of warmup iterations to do.
+    // warmupForks = 0 // How many warmup forks to make for a single benchmark. 0 to disable warmup forks.
+    // warmupMode = 'INDI' // Warmup mode for warming up selected benchmarks. Warmup modes are: [INDI, BULK, BULK_INDI].
+
+    jmhVersion = versions.jmh
+}
+
+jmhReport {
+    jmhResultPath = project.file('build/reports/jmh/results.json')
+    jmhReportOutput = project.file('build/reports/jmh')
+}

benchmarks/settings.gradle

@@ -0,0 +1 @@
+rootProject.name = 'launchdarkly-java-server-sdk-benchmarks'