Merge branch 'release/2.0.0'

wavesoftware · Dec 29, 2018 · 5410358 · 5410358
2 parents 6b4367d + f310b68
commit 5410358
Show file tree

Hide file tree

Showing 102 changed files with 6,523 additions and 1,533 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -0,0 +1,73 @@
+# Java Maven CircleCI 2.0 configuration file
+#
+# Check https://circleci.com/docs/2.0/language-java/ for more details
+#
+version: 2
+
+references:
+  build: &build
+    working_directory: ~/repo
+
+    environment:
+      # Customize the JVM maximum heap limit
+      MAVEN_OPTS: -Xmx2048m
+      JACOCO: false
+
+    steps:
+     - checkout
+
+     # Download and cache dependencies
+     - restore_cache:
+         keys:
+          - v2-dependencies-{{ checksum "pom.xml" }}
+          # fallback to using the latest cache if no exact match is found
+          - v2-dependencies-
+
+     - run:
+         name: Go Offline with Maven
+         command: mvn verify -DskipTests
+
+     - save_cache:
+         paths:
+          - ~/.m2
+         key: v2-dependencies-{{ checksum "pom.xml" }}
+
+     # run tests!
+     - run:
+         name: Run integration tests
+         command: mvn verify
+
+workflows:
+  version: 2
+  integration-tests:
+    jobs:
+      - zulu-6
+      - zulu-7
+      - zulu-8
+      - zulu-9
+      - zulu-11
+
+jobs:
+  zulu-6:
+    docker:
+      - image: wavesoftware/circleci-zulujdk:6
+    <<: *build
+  zulu-7:
+    docker:
+      - image: wavesoftware/circleci-zulujdk:7
+    <<: *build
+  zulu-8:
+    docker:
+      - image: wavesoftware/circleci-zulujdk:8
+    <<: *build
+  zulu-9:
+    docker:
+      - image: wavesoftware/circleci-zulujdk:9
+    <<: *build
+  zulu-11:
+    docker:
+      - image: wavesoftware/circleci-zulujdk:11
+    <<: *build
+
+
+
diff --git a/.editorconfig b/.editorconfig
@@ -9,4 +9,7 @@ end_of_line = lf
 insert_final_newline = true
 charset = utf-8
 indent_style = space
-indent_size = 4
+indent_size = 4
+
+[*.yml]
+indent_size = 2
diff --git a/.gitignore b/.gitignore
@@ -11,10 +11,7 @@
 # Eclipse IDE
 /.classpath
 /.project
-/.settings/org.eclipse.core.resources.prefs
-/.settings/org.eclipse.jdt.core.prefs
-/.settings/org.eclipse.m2e.core.prefs
-/.settings/org.eclipse.jdt.ui.prefs
+/.settings
 
 # Netbeans IDE
 /nbactions.xml

diff --git a/.travis.yml b/.travis.yml
@@ -1,28 +1,26 @@
 language: java
-script: mvn clean install --fail-at-end
+dist: trusty
+before_script: mvn dependency:go-offline
+script: mvn clean verify --fail-at-end
 notifications:
   email:
-    on_failure: true
+    on_failure: change
 matrix:
   include:
-  - jdk: openjdk6
-    env: JACOCO=true
-  - jdk: openjdk7
-    env: JACOCO=true COVERALLS=true
-  - jdk: oraclejdk7
-    env: JACOCO=true
-  - jdk: oraclejdk8
-    env: JACOCO=true
-  - jdk: openjdk7
-    env: JACOCO=true GDMSESSION=sonar
-  - jdk: openjdk7
-    env: JACOCO=true SONAR=publish
-    script: mvn clean install sonar:sonar --fail-at-end
-  - jdk: openjdk6
-    env: JACOCO=false
-  - jdk: openjdk7
-    env: JACOCO=false
-  - jdk: oraclejdk7
-    env: JACOCO=false
-  - jdk: oraclejdk8
-    env: JACOCO=false
+    # Quality testing
+    - jdk: oraclejdk8
+      env: JACOCO=true RELEASE_CHECKS=true
+    - jdk: oraclejdk8
+      env: JACOCO=true COVERALLS=true
+    - jdk: oraclejdk8
+      env: JACOCO=true SONAR=publish
+      script: mvn clean verify sonar:sonar --fail-at-end
+    # Performance testing
+    - jdk: openjdk7
+      env: JACOCO=false
+    - jdk: openjdk8
+      env: JACOCO=false
+    - jdk: oraclejdk9
+      env: JACOCO=false
+    - jdk: oraclejdk11
+      env: JACOCO=false
diff --git a/LICENSE b/LICENSE
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2015 Wave Software
+   Copyright 2015-2018 Wave Software
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/README.md b/README.md
@@ -1,17 +1,30 @@
 # EID Runtime Exceptions and Utilities
 
-[![Build Status](https://travis-ci.org/wavesoftware/java-eid-exceptions.svg?branch=master)](https://travis-ci.org/wavesoftware/java-eid-exceptions) [![Coverage Status](https://coveralls.io/repos/wavesoftware/java-eid-exceptions/badge.svg?branch=master&service=github)](https://coveralls.io/github/wavesoftware/java-eid-exceptions?branch=master) [![SonarQube Tech Debt](https://img.shields.io/sonar/http/sonar-ro.wavesoftware.pl/pl.wavesoftware:eid-exceptions/tech_debt.svg)](http://sonar-ro.wavesoftware.pl/dashboard/index/2600) [![Dependency Status](https://www.versioneye.com/user/projects/55aafc74306535001b000440/badge.svg?style=flat)](https://www.versioneye.com/user/projects/55aafc74306535001b000440) [![Maven Central](https://img.shields.io/maven-central/v/pl.wavesoftware/eid-exceptions.svg)](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22pl.wavesoftware%22%20AND%20a%3A%22eid-exceptions%22)
+[![Build Status](https://travis-ci.org/wavesoftware/java-eid-exceptions.svg?branch=master)](https://travis-ci.org/wavesoftware/java-eid-exceptions) [![Coverage Status](https://coveralls.io/repos/wavesoftware/java-eid-exceptions/badge.svg?branch=master&service=github)](https://coveralls.io/github/wavesoftware/java-eid-exceptions?branch=master) [![SonarQube Tech Debt](https://img.shields.io/sonar/https/sonar.wavesoftware.pl/pl.wavesoftware%3Aeid-exceptions/tech_debt.svg)](https://sonar.wavesoftware.pl/dashboard?id=pl.wavesoftware%3Aeid-exceptions) [![Maven Central](https://img.shields.io/maven-central/v/pl.wavesoftware/eid-exceptions.svg)](https://search.maven.org/artifact/pl.wavesoftware/eid-exceptions/1.2.0/jar)
 
 This small library holds a set of exceptions and utilities that implements idea of fast, reusable, error codes that can be simply thrown fast in case of unpredictable and unrecoverable application failure. It is meant to be used for application bugs.
 
-## Idea
+## The Idea
 
-The idea is to use a set of simple runtime exceptions. They should always take the Exception ID (Eid) object in the making. This eid object will then be reported when displaying or logging that exception. It can also be viewed on the professional fatal error window of the application as a bug reference. EidRuntimeExceptions contains also additional unique ID to distinguish each single exception from others with same Eid. This approach simplifies the management of exceptions in the application and allows developers to focus on functionalities rather than coming up with the correct statement for the exception.
+The main idea of this library is to use a set of simple runtime exceptions to speedup development and make it more professional in the same time. Those exceptions should always take the Exception ID (Eid for short) object on construction. The Eid object should be generated by developer while writing code and committed in the constructor of an exception. This eid object will then be reported when that exception is being displayed or logged.
 
-This approach is best to use with tools and plugins like:
+This approach simplifies the management of exceptions in the application and allows developers to focus on functionality and code quality, rather than coming up with the correct statement for the exception.
+
+This error number is perfect to be displayed on the error "500" page for your application as a bug reference. It's good idea, because it is static, so wil l not change in subsequent invocations, but it also do not disclose the actual reason why bug occurred.
+
+This approach is best to use with tools and IDE plugins like:
 
- * [EidGenerator for Netbeans IDE](http://plugins.netbeans.org/plugin/53137/exception-id-eid-generator)
  * [Generating Exception Id number in Intellij IDEA with Live Templates](https://github.com/wavesoftware/java-eid-exceptions/wiki/Generating%20Exception%20Id%20number%20in%20Intellij%20IDEA%20with%20Live%20Templates)
+ * [EidGenerator for Netbeans IDE](http://plugins.netbeans.org/plugin/53137/exception-id-eid-generator)
+
+Error page can say something like:
+
+> We are deeply sorry. A fatal error occurred.
+> The reference number is: 20150721:100554
+>
+> Wait a couple of minutes, and try again. If the same error number persists, call IT support. 
+
+That error page is easy to implement, because all those exceptions implement `EidContainer` interface.
 
 Example:
 
@@ -43,7 +56,7 @@ This classes shouldn't be used in any public API or library. It is designed to b
 <dependency>
     <groupId>pl.wavesoftware</groupId>
     <artifactId>eid-exceptions</artifactId>
-    <version>1.1.0</version>
+    <version>1.2.0</version>
 </dependency>
 ```
 
@@ -107,20 +120,26 @@ checkElementIndex(index, list.size(), "20150721:115749");
 
 #### Formatted message support
 
-From release `1.1.0` there have been added methods to support additional formatted messages for `checkArgument`, `checkState`, `checkNotNull` and `checkElementIndex` method. Those method versions can sometimes be used to pass additional information to exceptions that will be displayed in log files.
+From release `1.2.0` methods have been added to support additional formatted messages for `checkArgument`, 
+`checkState`, `checkNotNull` and `checkElementIndex` method. Those method versions can sometimes be used to pass additional information to exceptions that will be displayed in log files.
 
-Message formatting is done using `String.format(String, Object[])` method.
+From release `2.0.0` message formatting is done using `MessageFormat#format(String, Object[])` method.
 
 For example:
 
 ```java
-checkState(transation.isValid(), "20151119:120238", "Invalid transaction: %s, transaction);
+checkState(
+  transation.isValid(), "20151119:120238", 
+  "Invalid transaction: {0}", transaction
+);
 ```
 
 Will produce output similar to;
 
 ```
-pl.wavesoftware.eid.exceptions.EidIllegalStateException: [20151119:120238]<xf4j1l> => Invalid transaction: <Transaction id=null, buyer=null, products=[]>
+pl.wavesoftware.eid.exceptions.EidIllegalStateException: 
+ ↵ [20151119:120238]<xf4j1l> => Invalid transaction:
+ ↵ <Transaction id=null, buyer=null, products=[]>
 ```
 
 #### Functional try to execute blocks
@@ -132,39 +151,84 @@ There are two versions. One with `UnsafeSupplier` and one with `UnsafeProcedure`
 Example:
 
 ```java
-InputStream is = EidPreconditions.tryToExecute(new UnsafeSupplier<InputStream>() {
-    @Override
+import static pl.wavesoftware.eid.utils.EidExecutions.tryToExecute;
+// [..]
+InputStream is = tryToExecute(
+    () -> openResource("project.properties"),
+    "20150718:121521"
+);
+```
+
+or with JDK < 8
+
+```java
+InputStream is = EidExecutions.tryToExecute(new UnsafeSupplier<InputStream>() {
+    @Override @Nonnull
     public InputStream get() throws IOException {
         return this.getClass().getClassLoader()
             .getResourceAsStream("project.properties");
     }
 }, "20150718:121521");
 ```
 
-or with Java 8:
-
-```java
-import static pl.wavesoftware.eid.utils.EidPreconditions.tryToExecute;
-// [..]
-InputStream is = tryToExecute(() -> { resource("project.properties"); }, "20150718:121521");
-```
-
 #### Logging
 
-Eid object can also be useful in logging. That are `makeLogMessage` method provided to do that. Message formatting is done using `String.format(String, Object[])` method.
+Eid object can also be useful in logging. That is `message` method provided to do that. Message formatting is done using 
+`MessageFormat.format(String, Object[])` method.
 For example:
 
 ```java
-log.debug(new Eid("20151119:121814").makeLogMessage("REST request received: %s", request));
+log.debug(DefaultEid
+  .eid("20151119:121814")
+  .message("REST request received: {0}", request).toString()
+);
 ```
 
 will unfold to something similar to:
 
 ```
-2017-01-08T16:45:34,334 DEBUG [a.b.c.RestBroker] [20151119:121814]<d1afca> REST request received: <RestRequest user=<User id=345> flow=ShowLastTransactions step=Confirm>
+2017-01-08T16:45:34,334 DEBUG [a.b.c.RestBroker]
+ ↵ [20151119:121814]<d1afca> REST request received: 
+ ↵ <RestRequest user=<User id=345> flow=ShowLastTransactions step=Confirm>
 ```
 
-###Contributing
+#### Configuration
+
+From release `2.0.0` configuration interfaces have been added. There are 2 ways to configure Eid library.
+
+##### Configuration using Java's ServiceLoader mechanism
+
+Java `ServiceLoader` mechanism is standard for extending libraries. To do that, create on your classpath, a file:
+
+`META-INF/services/pl.wavesoftware.eid.api.Configurator`
+
+In that file, place a fully qualified class name of your class that implements `Configurator` interface. It should be called first time you reference an Eid, or and of the eid exceptions, or utility preconditions class.
+
+##### Programmatic configuration
+
+You can also configure Eid library programmatically. To do just that, use `EidModule.getBinding().getConfigurationSystem().configure()` method.
+
+```java
+// configure
+Configurator original = EidModul.getBinding()
+  .getConfigurationSystem()
+  .configure(configuration ->
+    configuration.uniqueIdGenerator(() -> constUniq)
+  );
+
+// restore original configuration with:
+EidModule.getBinding()
+  .getConfigurationSystem()
+  .configure(original);
+```
+
+Note, that method returns a configurator that  can be used to restore configuration to the state before you invoke this configuration method.
+
+#### Validation
+
+On `2.0.0` release optional validation have been added. If you configure a `Validator` using either of configuration methods, each new Eid will be validated for correctness. Note that this will happen lazily for `EidPreconditions` and `EidExecutions` utility methods.
+
+### Contributing
 
 Contributions are welcome!
 
@@ -184,6 +248,17 @@ Even if you can't contribute code, if you have an idea for an improvement please
 
 ### Releases
 
+- 2.0.0
+  - Complete overhaul of library structure
+  - More obvious exceptions constructors
+  - Better configuration
+  - Optional validation
+
+- 1.2.0
+  - Major performance tweaks and tests for `EidPreconditions` methods #4 
+  - Major performance tweaks and tests for `Eid` class #2 
+  - Switched to new OSSRH maven template
+  - Switched to Git Flow via jgitflow plugin
 - 1.1.0
   - Adding support for formatted messages in exceptions and also in utility methods of `EidPreconditions`  
 - 1.0.1