Work on #385, added documentation and class diagram. Made refactoring changes to pass checkstyle and PMD checks

mute-idiom/etc/mute-idiom.ucls

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<class-diagram version="1.1.8" icons="true" automaticImage="PNG" always-add-relationships="false" generalizations="true" 
+  realizations="true" associations="true" dependencies="true" nesting-relationships="true">  
+  <class id="1" language="java" name="com.iluwatar.mute.App" project="mute-idiom" 
+    file="/mute-idiom/src/main/java/com/iluwatar/mute/App.java" binary="false" corner="BOTTOM_RIGHT">    
+    <position height="-1" width="-1" x="519" y="122"/>    
+    <display autosize="true" stereotype="true" package="true" initial-value="false" signature="true" 
+      sort-features="false" accessors="true" visibility="true">      
+      <attributes public="true" package="true" protected="true" private="false" static="true"/>      
+      <operations public="true" package="true" protected="true" private="false" static="true"/>    
+    </display>  
+  </class>  
+  <class id="2" language="java" name="com.iluwatar.mute.Mute" project="mute-idiom" 
+    file="/mute-idiom/src/main/java/com/iluwatar/mute/Mute.java" binary="false" corner="BOTTOM_RIGHT">    
+    <position height="115" width="203" x="291" y="267"/>    
+    <display autosize="false" stereotype="true" package="true" initial-value="false" signature="true" 
+      sort-features="false" accessors="true" visibility="true">      
+      <attributes public="true" package="true" protected="true" private="true" static="true"/>      
+      <operations public="true" package="true" protected="true" private="false" static="true"/>    
+    </display>  
+  </class>  
+  <interface id="3" language="java" name="com.iluwatar.mute.CheckedRunnable" project="mute-idiom" 
+    file="/mute-idiom/src/main/java/com/iluwatar/mute/CheckedRunnable.java" binary="false" corner="BOTTOM_RIGHT">    
+    <position height="-1" width="-1" x="723" y="322"/>    
+    <display autosize="true" stereotype="true" package="true" initial-value="false" signature="true" 
+      sort-features="false" accessors="true" visibility="true">      
+      <attributes public="true" package="true" protected="true" private="true" static="true"/>      
+      <operations public="true" package="true" protected="true" private="true" static="true"/>    
+    </display>  
+  </interface>  
+  <dependency id="4">    
+    <end type="SOURCE" refId="1"/>    
+    <end type="TARGET" refId="2"/>  
+  </dependency>  
+  <dependency id="5">    
+    <end type="SOURCE" refId="2"/>    
+    <end type="TARGET" refId="3"/>  
+  </dependency>  
+  <classifier-display autosize="true" stereotype="true" package="true" initial-value="false" signature="true" 
+    sort-features="false" accessors="true" visibility="true">    
+    <attributes public="true" package="true" protected="true" private="true" static="true"/>    
+    <operations public="true" package="true" protected="true" private="true" static="true"/>  
+  </classifier-display>  
+  <association-display labels="true" multiplicity="true"/>
+</class-diagram>

mute-idiom/src/main/java/com/iluwatar/mute/App.java

@@ -20,6 +20,7 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
+
 package com.iluwatar.mute;
 
 import static org.mockito.Mockito.doThrow;
@@ -28,10 +29,34 @@ import static org.mockito.Mockito.mock;
 import java.io.ByteArrayOutputStream;
 import java.sql.Connection;
 import java.sql.SQLException;
+import java.sql.Statement;
 
+/**
+ * Mute pattern is utilized when we need to suppress an exception due to an API flaw or in 
+ * situation when all we can do to handle the exception is to log it. 
+ * This pattern should not be used everywhere. It is very important to logically handle the 
+ * exceptions in a system, but some situations like the ones described above require this pattern, 
+ * so that we don't need to repeat 
+ * <pre>
+ * <code>
+ *   try {
+ *     // code that may throwing exception we need to ignore or may never be thrown
+ *   } catch (Exception ex) {
+ *     // ignore by logging or throw error if unexpected exception occurs
+ *   }
+ * </code>
+ * </pre> every time we need to ignore an exception.
+ * 
+ */
 public class App {
 
-  public static void main(String[] args) {
+  /**
+   * Program entry point.
+   * 
+   * @param args command line args.
+   * @throws Exception if any exception occurs
+   */
+  public static void main(String[] args) throws Exception {
 
     useOfLoggedMute();
 
@@ -39,22 +64,21 @@ public class App {
   }
 
   /*
-   * Typically used when the API declares some exception but cannot do so. Usually a signature mistake.
-   * In this example out is not supposed to throw exception as it is a ByteArrayOutputStream. So we
-   * utilize mute, which will throw AssertionError if unexpected exception occurs.
+   * Typically used when the API declares some exception but cannot do so. Usually a 
+   * signature mistake.In this example out is not supposed to throw exception as it is a
+   * ByteArrayOutputStream. So we utilize mute, which will throw AssertionError if unexpected
+   * exception occurs.
    */
   private static void useOfMute() {
     ByteArrayOutputStream out = new ByteArrayOutputStream();
     Mute.mute(() -> out.write("Hello".getBytes()));
   }
 
-  private static void useOfLoggedMute() {
+  private static void useOfLoggedMute() throws SQLException {
     Connection connection = null;
     try {
       connection = openConnection();
       readStuff(connection);
-    } catch (SQLException ex) {
-      ex.printStackTrace();
     } finally {
       closeConnection(connection);
     }
@@ -64,14 +88,12 @@ public class App {
    * All we can do while failed close of connection is to log it.
    */
   private static void closeConnection(Connection connection) {
-   if (connection != null) {
-     Mute.loggedMute(() -> connection.close());
-   }
+    Mute.loggedMute(() -> connection.close());
   }
 
   private static void readStuff(Connection connection) throws SQLException {
-    if (connection != null) {
-      connection.createStatement();
+    try (Statement statement = connection.createStatement()) {
+      System.out.println("Read data from statement");
     }
   }
 

mute-idiom/src/main/java/com/iluwatar/mute/CheckedRunnable.java

@@ -20,6 +20,7 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
+
 package com.iluwatar.mute;
 
 /**
@@ -32,5 +33,5 @@ public interface CheckedRunnable {
    * Same as {@link Runnable#run()} with a possibility of exception in execution.
    * @throws Exception if any exception occurs.
    */
-  public void run() throws Exception;
+  void run() throws Exception;
 }

mute-idiom/src/main/java/com/iluwatar/mute/Mute.java

@@ -30,6 +30,9 @@ import java.io.IOException;
  */
 public final class Mute {
   
+  // The constructor is never meant to be called.
+  private Mute() {}
+
   /**
    * Executes the <code>runnable</code> and throws the exception occurred within a {@link AssertionError}.
    * This method should be utilized to mute the operations that are guaranteed not to throw an exception.

mute-idiom/src/test/java/com/iluwatar/mute/AppTest.java

@@ -9,7 +9,7 @@ import org.junit.Test;
 public class AppTest {
 
   @Test
-  public void test() {
+  public void test() throws Exception {
     App.main(null);
   }
 }

mute-idiom/src/test/java/com/iluwatar/mute/MuteTest.java

@@ -20,6 +20,7 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
+
 package com.iluwatar.mute;
 
 import static org.junit.Assert.assertTrue;
@@ -38,6 +39,11 @@ public class MuteTest {
   
   @Rule public ExpectedException exception = ExpectedException.none();
   
+  @Test
+  public void muteShouldRunTheCheckedRunnableAndNotThrowAnyExceptionIfCheckedRunnableDoesNotThrowAnyException() {
+    Mute.mute(() -> methodNotThrowingAnyException());
+  }
+  
   @Test
   public void muteShouldRethrowUnexpectedExceptionAsAssertionError() throws Exception {
     exception.expect(AssertionError.class);
@@ -46,8 +52,9 @@ public class MuteTest {
     Mute.mute(() -> methodThrowingException());
   }
   
-  private void methodThrowingException() throws Exception {
-    throw new Exception(MESSAGE);
+  @Test
+  public void loggedMuteShouldRunTheCheckedRunnableAndNotThrowAnyExceptionIfCheckedRunnableDoesNotThrowAnyException() {
+    Mute.loggedMute(() -> methodNotThrowingAnyException());
   }
   
   @Test
@@ -59,4 +66,13 @@ public class MuteTest {
     
     assertTrue(new String(stream.toByteArray()).contains(MESSAGE));
   }
+  
+  
+  private void methodNotThrowingAnyException() {
+    System.out.println("Executed successfully");
+  }
+  
+  private void methodThrowingException() throws Exception {
+    throw new Exception(MESSAGE);
+  }
 }

pom.xml

@@ -123,6 +123,7 @@
 		<module>feature-toggle</module>
 		<module>value-object</module>
 		<module>monad</module>
+		<module>mute-idiom</module>
 	</modules>
 
 	<dependencyManagement>