Refactoring to meet requirements for 2.x

It's about time for major refactoring of Eid library. Introducing 2.x relase with: * Better structure * More obvious exceptions constructors * Better configuration * Optional validation
wavesoftware · Nov 5, 2018 · 9692035 · 9692035
1 parent e4015c4
commit 9692035
Show file tree

Hide file tree

Showing 58 changed files with 3,653 additions and 1,418 deletions.
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
@@ -5,24 +5,9 @@ notifications:
     on_failure: true
 matrix:
   include:
-  - jdk: openjdk6
-    env: JACOCO=true
   - jdk: openjdk7
-    env: JACOCO=true COVERALLS=true
-  - jdk: oraclejdk7
     env: JACOCO=true
+  - jdk: openjdk8
+    env: JACOCO=true COVERALLS=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
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) [![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)
+
+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:
 
@@ -107,14 +120,15 @@ 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;
@@ -132,7 +146,7 @@ There are two versions. One with `UnsafeSupplier` and one with `UnsafeProcedure`
 Example:
 
 ```java
-InputStream is = EidPreconditions.tryToExecute(new UnsafeSupplier<InputStream>() {
+InputStream is = EidExecutions.tryToExecute(new UnsafeSupplier<InputStream>() {
     @Override @Nonnull
     public InputStream get() throws IOException {
         return this.getClass().getClassLoader()
@@ -144,18 +158,22 @@ InputStream is = EidPreconditions.tryToExecute(new UnsafeSupplier<InputStream>()
 or with Java 8:
 
 ```java
-import static pl.wavesoftware.eid.utils.EidPreconditions.tryToExecute;
+import static pl.wavesoftware.eid.utils.EidExecutions.tryToExecute;
 // [..]
-InputStream is = tryToExecute(() -> { resource("project.properties"); }, "20150718:121521");
+InputStream is = tryToExecute(
+    () -> openResource("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(new Eid("20151119:121814").message("REST request received: {0}", request).toString());
 ```
 
 will unfold to something similar to:
@@ -164,6 +182,45 @@ 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>
 ```
 
+#### 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.Configurator`
+
+In that file, place a fully qualified class name of your class that implements `EidConfigurator` 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 `Eid.getBinding().getConfigurationSystem().configure()` method.
+
+```java
+// configure
+EidConfigurator original = Eid.getBinding().getConfigurationSystem().configure(new EidConfigurator() {
+    @Override
+    public void configure(EidConfiguration configuration) {
+        configuration.uniqueIdGenerator(new UniqueIdGenerator() {
+            @Override
+            public String generateUniqId() {
+                return constUniq;
+            }
+        });
+    }
+});
+// restore original configuration with:
+Eid.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 +241,12 @@ 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 

diff --git a/pom.xml b/pom.xml
@@ -1,9 +1,25 @@
 <?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Copyright (c) 2015 Wave Software
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <groupId>pl.wavesoftware</groupId>
     <artifactId>eid-exceptions</artifactId>
-    <version>1.2.1-SNAPSHOT</version>
+    <version>2.0.0-SNAPSHOT</version>
     <packaging>jar</packaging>
 
     <name>EID Runtime Exceptions and Utilities</name>
@@ -36,10 +52,6 @@
         </developer>
     </developers>
 
-    <prerequisites>
-        <maven>${maven.required.version}</maven>
-    </prerequisites>
-
     <scm>
         <connection>scm:git:https://github.com/wavesoftware/java-eid-exceptions.git</connection>
         <developerConnection>scm:git:git@github.com:wavesoftware/java-eid-exceptions.git</developerConnection>
@@ -68,8 +80,6 @@
     </distributionManagement>
 
     <properties>
-        <netbeans.hint.license>apache20</netbeans.hint.license>
-        <maven.required.version>3.0.4</maven.required.version>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
         <sonar.working.directory>${project.build.directory}/sonar</sonar.working.directory>
@@ -93,7 +103,6 @@
             <groupId>com.google.code.findbugs</groupId>
             <artifactId>jsr305</artifactId>
             <version>3.0.1</version>
-            <type>jar</type>
         </dependency>
 
         <!-- Tests -->
@@ -110,12 +119,6 @@
             <version>1.7.1</version>
             <scope>test</scope>
         </dependency>
-        <dependency>
-            <groupId>org.hamcrest</groupId>
-            <artifactId>hamcrest-all</artifactId>
-            <version>1.3</version>
-            <scope>test</scope>
-        </dependency>
         <dependency>
             <groupId>org.openjdk.jmh</groupId>
             <artifactId>jmh-core</artifactId>
@@ -149,7 +152,6 @@
     </dependencies>
 
     <build>
-
         <pluginManagement>
             <plugins>
                 <plugin>
@@ -338,74 +340,6 @@
             </build>
         </profile>
 
-        <profile>
-            <id>sonar</id>
-            <activation>
-                <property>
-                    <!-- tries to determine is interactive user session -->
-                    <name>env.GDMSESSION</name>
-                </property>
-            </activation>
-            <properties>
-                <sonar.analysis.mode>preview</sonar.analysis.mode>
-                <sonar.issuesReport.console.enable>true</sonar.issuesReport.console.enable>
-                <sonar.issuesReport.html.enable>true</sonar.issuesReport.html.enable>
-                <sonar.report.export.path>issues.json</sonar.report.export.path>
-            </properties>
-            <build>
-                <plugins>
-                    <plugin>
-                        <groupId>org.jacoco</groupId>
-                        <artifactId>jacoco-maven-plugin</artifactId>
-                    </plugin>
-
-                    <plugin>
-                        <groupId>org.codehaus.mojo</groupId>
-                        <artifactId>sonar-maven-plugin</artifactId>
-                        <executions>
-                            <execution>
-                                <id>default</id>
-                                <phase>post-integration-test</phase>
-                                <goals>
-                                    <goal>sonar</goal>
-                                </goals>
-                            </execution>
-                        </executions>
-                    </plugin>
-
-                    <plugin>
-                        <groupId>org.codehaus.gmaven</groupId>
-                        <artifactId>groovy-maven-plugin</artifactId>
-                        <version>2.0</version>
-                        <dependencies>
-                            <dependency>
-                                <groupId>org.codehaus.groovy</groupId>
-                                <artifactId>groovy-all</artifactId>
-                                <version>2.4.6</version>
-                            </dependency>
-                        </dependencies>
-                        <configuration>
-                            <defaults>
-                                <sonar.issues.file>${sonar.working.directory}/${sonar.report.export.path}
-                                </sonar.issues.file>
-                                <sonar.skip>${sonar.skip}</sonar.skip>
-                            </defaults>
-                            <source>${project.basedir}/src/test/groovy/verify-sonar-issues.groovy</source>
-                        </configuration>
-                        <executions>
-                            <execution>
-                                <id>verify-sonar-issues</id>
-                                <phase>verify</phase>
-                                <goals>
-                                    <goal>execute</goal>
-                                </goals>
-                            </execution>
-                        </executions>
-                    </plugin>
-                </plugins>
-            </build>
-        </profile>
-
         <profile>
             <id>coveralls</id>
             <activation>