Merge branch 'v1.0.0-dev'

Author: th3hunt

ChangeLog.md

@@ -0,0 +1,28 @@
+# ChangeLog
+
+## v1.0.0
+
+### New
+
+ - `errorHandler.run(BlockExecutor)` saves you from a `try/catch` block or two 
+   ```java
+     try {
+        doSomething();
+     } catch(Exception ex) {
+        errorHandler.handle(ex);
+     }
+     
+     // can now be written as
+     
+     errorHandler.run(() -> doSomething())
+   ```
+
+### Breaking
+ 
+ - `bindErrorCode` renamed to `bind`
+ - `bindErrorCodeClass` renamed to `bindClass`
+ 
+
+
+
+

README.md

@@ -5,21 +5,23 @@
 
 > Error handling library for Android and Java
 
+Encapsulate error handling logic into objects that adhere to configurable defaults. Then pass them around as parameters or inject them via DI. 
+
 ## Download
 Download the [latest JAR](https://bintray.com/workable/maven/ErrorHandler/_latestVersion) or grab via Maven:
 ```xml
 <dependency>
   <groupId>com.workable</groupId>
   <artifactId>error-handler</artifactId>
-  <version>0.9.1</version>
+  <version>1.0.0</version>
   <type>pom</type>
 </dependency>
 ```
 
 or Gradle:
 
 ```groovy
-compile 'com.workable:error-handler:0.9.1'
+compile 'com.workable:error-handler:1.0.0'
 ```
 
 
@@ -42,22 +44,22 @@ ErrorHandler
   .defaultErrorHandler()
 
   // Bind certain exceptions to "offline"
-  .bindErrorCode("offline", errorCode -> throwable -> {
+  .bind("offline", errorCode -> throwable -> {
       return throwable instanceof UnknownHostException || throwable instanceof ConnectException;
   })
 
   // Bind HTTP 404 status to 404
-  .bindErrorCode(404, errorCode -> throwable -> {
+  .bind(404, errorCode -> throwable -> {
       return ((HttpException) throwable).code() == 404;
   })
 
   // Bind HTTP 500 status to 500
-  .bindErrorCode(500, errorCode -> throwable -> {
+  .bind(500, errorCode -> throwable -> {
       return ((HttpException) throwable).code() == 500;
   })
 
   // Bind all DB errors to a custom enumeration
-  .bindErrorCodeClass(DBError.class, errorCode -> throwable -> {
+  .bindClass(DBError.class, errorCode -> throwable -> {
       return DBError.from(throwable) == errorCode;
   })
 
@@ -100,6 +102,12 @@ try {
 }
 ```
 
+### Run blocks of code using ErrorHandler.run
+
+```java
+ErrorHandler.run(() -> fetchNewMessages());
+```
+
 ### Override defaults when needed
 
 ```java
@@ -150,7 +158,7 @@ ErrorHandler is __thread-safe__.
 
 * `on(Class<? extends Exception>, Action)` Register an _Action_ to be executed if error is an instance of `Exception`.
 
-* `on(T, Action)` Register an _Action_ to be executed if error is bound to T, through `bindErrorCode()` or `bindErrorCodeClass()`.
+* `on(T, Action)` Register an _Action_ to be executed if error is bound to T, through `bind()` or `bindClass()`.
 
 * `otherwise(Action)` Register an _Action_ to be executed only if no other _Action_ gets executed.
 
@@ -162,9 +170,9 @@ ErrorHandler is __thread-safe__.
 
 * `skipDefaults()` Skip any default actions. Meaning any actions registered on the `defaultErrorHandler` instance.
 
-* `bindErrorCode(T, MatcherFactory<T>)` Bind instances of _T_ to match errors through a matcher provided by _MatcherFactory_.
+* `bind(T, MatcherFactory<T>)` Bind instances of _T_ to match errors through a matcher provided by _MatcherFactory_.
 
-* `bindErrorCodeClass(Class<T>, MatcherFactory<T>)` Bind class _T_ to match errors through a matcher provided by _MatcherFactory_.
+* `bindClass(Class<T>, MatcherFactory<T>)` Bind class _T_ to match errors through a matcher provided by _MatcherFactory_.
 
 * `clear()` Clear all registered _Actions_.
 
@@ -174,23 +182,18 @@ ErrorHandler is __thread-safe__.
 
 
 ## About
-A common problem in software, specially in UI software is that of error handling.
-
-One way to classify errors can be by how they relate to the [problem domain](https://en.wikipedia.org/wiki/Problem_domain). Some errors, like `network` or `database` errors are orthogonal to the problem domain and designate truly **exceptional conditions**, while others are core parts of the domain like `validation` and `authentication` errors.
-
-Another way to classify errors is by their **scope**. Are they **common** throughout the application or **specific** to a single screen, object or even method? Think of `UnauthorizedException` versus `InvalidPasswordException`.
-
-And let's not forget another very simple distinction between errors. Those that are known at authoring time and thus **expected** (despite of how probable is that they occur), and those that are **unknown** until runtime.
 
-With that in mind, we usually want to:
+When designing for errors, we usually need to:
 
-1. have a **default** handler for every **expected** (exceptional, common or not) error
-2. handle **specific** errors **as appropriate** based on where and when they occur
-3. have a **default** catch-all handler for **unknown** errors
-4. **override** any default handler if needed
-5. keep our code **DRY**
+1. have a **default** handler for every **expected** error 
+   // i.e. network, subscription errors
+2. handle **specific** errors **as appropriate** based on where and when they occur 
+   // i.e. network error while uploading a file, invalid login
+3. have a **catch-all** handler for **unknown** errors 
+   // i.e. system libraries runtime errors we don't anticipate
+4. keep our code **DRY**
 
-Java, as a language, provides you with a way to do the above. By mapping exceptional or very common errors to runtime exceptions and catching them lower in the call stack, while having specific expected errors mapped to checked exceptions and handle them near where the error occurred. Still, countless are the projects where this simple strategy has gone astray with lots of errors being either swallowed or left for the catch-all `Thread.UncaughtExceptionHandler`. Moreover, it usually comes with significant boilerplate code. `ErrorHandler` however eases this practice through its fluent API, error aliases and defaults mechanism.
+Java, as a language, provides you with a way to do the above. By mapping cross-cutting errors to runtime exceptions and catching them lower in the call stack, while having specific expected errors mapped to checked exceptions and handle them near where the error occurred. Still, countless are the projects where this simple strategy has gone astray with lots of errors being either swallowed or left for the catch-all `Thread.UncaughtExceptionHandler`. Moreover, it usually comes with significant boilerplate code. `ErrorHandler` however eases this practice through its fluent API, error aliases and defaults mechanism.
 
 This library doesn't try to solve Java specific problems, although it does help with the `log and shallow` anti-pattern as it provides an opinionated and straightforward way to act inside every `catch` block.  It was created for the needs of an Android app and proved itself useful very quickly. So it may work for you as well. If you like the concept and you're developing in  _Swift_ or _Javascript_, we're baking 'em and will be available really soon.
 

build.gradle

@@ -1,5 +1,5 @@
 group 'com.workable'
-version '0.9'
+version '1.0.0'
 
 apply plugin: 'java'
 

errorhandler-matchers/retrofit-rx-matcher/build.gradle

@@ -1,5 +1,5 @@
 group 'com.workable'
-version '0.9'
+version '1.0.0'
 
 apply plugin: 'java'
 

errorhandler-matchers/retrofit-rx-matcher/src/main/java/com/workable/errorhandler/matchers/retrofit/Range.java

@@ -10,9 +10,10 @@ public class Range {
 
     /**
      * Creates a Range object with lower and upper bound
-     * @param lowerBound
-     * @param upperBound
-     * @return
+     * @param lowerBound lower limit of Range
+     * @param upperBound upper limit of Range
+     *
+     * @return a Range instance
      */
     public static Range of(int lowerBound, int upperBound) {
         return new Range(lowerBound, upperBound);
@@ -25,7 +26,8 @@ private Range(int lowerBound, int upperBound) {
 
     /**
      * Checks if the passed httpStatusCode is contained in given range
-     * @param httpStatusCode
+     *
+     * @param httpStatusCode the status code to check
      * @return true if contains, otherwise false
      */
     public boolean contains(int httpStatusCode) {

errorhandler-matchers/retrofit-rx-matcher/src/main/java/com/workable/errorhandler/matchers/retrofit/RetrofitMatcherFactory.java

@@ -14,7 +14,8 @@ private RetrofitMatcherFactory() {
 
     /**
      * Creates a {@link MatcherFactory} that checks HTTP statuses
-     * @return
+     *
+     * @return new MatcherFactory for Retrofit Rx HttpException that works with Integer
      */
     public static MatcherFactory<Integer> create() {
         return new MatcherFactory<Integer>() {
@@ -31,7 +32,8 @@ public boolean matches(Throwable throwable) {
 
     /**
      * Creates a {@link MatcherFactory} that checks if HTTP status is in given {@link Range}
-     * @return
+     *
+     * @return new MatcherFactory for Retrofit Rx HttpException that works with Range
      */
     public static MatcherFactory<Range> createRange() {
         return new MatcherFactory<Range>() {

errorhandler-matchers/retrofit-rx-matcher/src/test/java/com/workable/errorhandler/matchers/retrofit/RetrofitMatcherFactoryTest.java

@@ -27,8 +27,8 @@ protected void setUp() throws Exception {
     public void test_catching_exact_http_code() {
         ErrorHandler
                 .createIsolated()
-                .bindErrorCode(400, RetrofitMatcherFactory.create())
-                .bindErrorCodeClass(Range.class, RetrofitMatcherFactory.createRange())
+                .bind(400, RetrofitMatcherFactory.create())
+                .bindClass(Range.class, RetrofitMatcherFactory.createRange())
                 .on(400, new Action() {
                     @Override
                     public void execute(Throwable throwable, ErrorHandler errorHandler) {
@@ -51,8 +51,8 @@ public void execute(Throwable throwable, ErrorHandler errorHandler) {
     public void test_not_catching_exact_http_code() {
         ErrorHandler
                 .createIsolated()
-                .bindErrorCode(400, RetrofitMatcherFactory.create())
-                .bindErrorCodeClass(Range.class, RetrofitMatcherFactory.createRange())
+                .bind(400, RetrofitMatcherFactory.create())
+                .bindClass(Range.class, RetrofitMatcherFactory.createRange())
                 .on(400, new Action() {
                     @Override
                     public void execute(Throwable throwable, ErrorHandler errorHandler) {
@@ -75,7 +75,7 @@ public void execute(Throwable throwable, ErrorHandler errorHandler) {
     public void test_catching_with_class() {
         ErrorHandler
                 .createIsolated()
-                .bindErrorCodeClass(Integer.class, RetrofitMatcherFactory.create())
+                .bindClass(Integer.class, RetrofitMatcherFactory.create())
                 .on(500, new Action() {
                     @Override
                     public void execute(Throwable throwable, ErrorHandler errorHandler) {

errorhandler/build.gradle

@@ -9,7 +9,7 @@ plugins {
 }
 
 group 'com.workable'
-version '0.9.1'
+version '1.0.0'
 
 apply plugin: 'java'
 apply plugin: 'maven-publish'
@@ -36,18 +36,27 @@ task sourceJar(type: Jar) {
     from sourceSets.main.allJava
 }
 
+task javadocJar(type: Jar) {
+    classifier = 'javadoc'
+    from javadoc
+}
+
 publishing {
     publications {
         mavenJava(MavenPublication) {
             groupId 'com.workable'
             artifactId 'error-handler'
-            version '0.9.1'
+            version '1.0.0'
 
             from components.java
 
             artifact sourceJar {
                 classifier "sources"
             }
+
+            artifact javadocJar {
+                classifier "javadoc"
+            }
         }
     }
 
@@ -81,10 +90,10 @@ bintray {
         labels = ['java', 'error handler', 'errors', 'android']
         publicDownloadNumbers = true
         version {
-            name = '0.9.1'
+            name = '1.0.0'
 
             desc = 'Error handling library for Android and Java'
-            vcsTag = '0.9.1'
+            vcsTag = 'v1.0.0'
             gpg {
                 sign = true //Determines whether to GPG sign the files. The default is false
             }

errorhandler/src/main/java/com/workable/errorhandler/Action.java

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  *
- * Copyright (c) 2010-2016 Workable SA
+ * Copyright (c) 2013-2016 Workable SA
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

errorhandler/src/main/java/com/workable/errorhandler/ActionEntry.java

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  *
- * Copyright (c) 2010-2016 Workable SA
+ * Copyright (c) 2013-2016 Workable SA
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -71,6 +71,7 @@ public int hashCode() {
      *
      * @param matcher the matcher object in the ActionEntry
      * @param action  the action object in the ActionEntry
+     * @return a new ActionEntry
      */
     public static ActionEntry from(Matcher matcher, Action action) {
         return new ActionEntry(matcher, action);