Merge development

Author: Jonathan Pereira

src/main/java/com/github/jonpereiradev/diffobjects/DiffException.java

@@ -1,5 +1,11 @@
 package com.github.jonpereiradev.diffobjects;
 
+/**
+ * Exception for any generic error found in the diff execution.
+ *
+ * @author Jonathan Pereira
+ * @since 1.0
+ */
 public class DiffException extends RuntimeException {
 
     public DiffException(String message) {

src/main/java/com/github/jonpereiradev/diffobjects/DiffObjects.java

@@ -3,24 +3,33 @@
 import com.github.jonpereiradev.diffobjects.builder.DiffConfiguration;
 import com.github.jonpereiradev.diffobjects.strategy.DiffMetadata;
 import com.github.jonpereiradev.diffobjects.strategy.DiffReflections;
+import com.github.jonpereiradev.diffobjects.strategy.DiffStrategy;
+import java.util.ArrayList;
 
 import java.util.Collections;
-import java.util.LinkedList;
 import java.util.List;
 import java.util.Objects;
 
 /**
- * @author jonpereiradev@gmail.com
+ * Responsible for execute the diff between two objects.
+ *
+ * @author Jonathan Pereira
+ * @since 1.0
  */
 public final class DiffObjects {
 
+    private DiffObjects() {
+        throw new UnsupportedOperationException("No need to create an instance of this class.");
+    }
+
     /**
-     * Executa o instance entre o antes e o depois.
+     * Execute the diff between two objects using annotations.
      *
-     * @param <T>         tipo do objeto comparado.
-     * @param beforeState objeto com as informações antes da alteração.
-     * @param afterState  objeto com as informaçnoes depois da alteração.
-     * @return resultado do instance.
+     * @param <T> type of object been compared.
+     * @param beforeState the before object state to compare with after object.
+     * @param afterState the after object state to compare with befor object.
+     *
+     * @return a list with the results of the diff.
      */
     public static <T> List<DiffResult> diff(T beforeState, T afterState) {
         Objects.requireNonNull(beforeState, "Before state is required.");
@@ -30,59 +39,69 @@ public static <T> List<DiffResult> diff(T beforeState, T afterState) {
     }
 
     /**
-     * Verifica se os objetos são iguais no instance.
+     * Execute the diff between two objects using a configuration.
      *
-     * @param <T>         tipo do objeto comparado.
-     * @param beforeState objeto com as informações antes da alteração.
-     * @param afterState  objeto com as informações depois da alteração.
-     * @return resultado do instance.
-     */
-    public static <T> boolean isEquals(T beforeState, T afterState) {
-        Objects.requireNonNull(beforeState, "Before state is required.");
-        Objects.requireNonNull(afterState, "After state is required.");
-
-        return isEquals(beforeState, afterState, DiffReflections.mapAnnotations(beforeState.getClass()));
-    }
-
-    /**
-     * Executa o instance entre o antes e o depois.
+     * @param <T> type of object been compared.
+     * @param beforeState the before object state to compare with after object.
+     * @param afterState the after object state to compare with befor object.
+     * @param configuration the configuration of the diff.
      *
-     * @param <T>         tipo do objeto comparado.
-     * @param beforeState objeto com as informações antes da alteração.
-     * @param afterState  objeto com as informaçnoes depois da alteração.
-     * @return resultado do instance.
+     * @return a list with the results of the diff.
      */
     public static <T> List<DiffResult> diff(T beforeState, T afterState, DiffConfiguration configuration) {
         Objects.requireNonNull(beforeState, "Before state is required.");
         Objects.requireNonNull(afterState, "After state is required.");
         Objects.requireNonNull(configuration, "Configuration is required.");
 
-        List<DiffResult> results = new LinkedList<>();
+        List<DiffMetadata> metadatas = configuration.build();
+        List<DiffResult> results = new ArrayList<>(metadatas.size());
+
+        for (DiffMetadata metadata : metadatas) {
+            DiffStrategy strategy = metadata.getStrategy();
+            DiffResult diff = strategy.diff(beforeState, afterState, metadata);
 
-        for (DiffMetadata metadata : configuration.build()) {
-            DiffResult diff = metadata.getStrategy().diff(beforeState, afterState, metadata);
             diff.setProperties(Collections.unmodifiableMap(metadata.getProperties()));
+
             results.add(diff);
         }
 
         return results;
     }
 
     /**
-     * Verifica se os objetos são iguais no instance.
+     * Check if exists any difference between the two objects using annotations.
+     *
+     * @param <T> type of object been compared.
+     * @param beforeState the before object state to compare with after object.
+     * @param afterState the after object state to compare with befor object.
+     *
+     * @return {@code true} if no difference exists between the objects or {@code false} otherwise.
+     */
+    public static <T> boolean isEquals(T beforeState, T afterState) {
+        Objects.requireNonNull(beforeState, "Before state is required.");
+        Objects.requireNonNull(afterState, "After state is required.");
+
+        return isEquals(beforeState, afterState, DiffReflections.mapAnnotations(beforeState.getClass()));
+    }
+
+    /**
+     * Check if exists any difference between the two objects.
+     *
+     * @param <T> type of object been compared.
+     * @param beforeState the before object state to compare with after object.
+     * @param afterState the after object state to compare with befor object.
+     * @param configuration the configuration of the diff.
      *
-     * @param <T>         tipo do objeto comparado.
-     * @param beforeState objeto com as informações antes da alteração.
-     * @param afterState  objeto com as informações depois da alteração.
-     * @return resultado do instance.
+     * @return {@code true} if no difference exists between the objects or {@code false} otherwise.
      */
     public static <T> boolean isEquals(T beforeState, T afterState, DiffConfiguration configuration) {
         Objects.requireNonNull(beforeState, "Before state is required.");
         Objects.requireNonNull(afterState, "After state is required.");
         Objects.requireNonNull(configuration, "Configuration is required.");
 
         for (DiffMetadata metadata : configuration.build()) {
-            DiffResult result = metadata.getStrategy().diff(beforeState, afterState, metadata);
+            DiffStrategy strategy = metadata.getStrategy();
+            DiffResult result = strategy.diff(beforeState, afterState, metadata);
 
             if (!result.isEquals()) {
                 return false;

src/main/java/com/github/jonpereiradev/diffobjects/DiffResult.java

@@ -3,13 +3,16 @@
 import java.util.Map;
 
 /**
- * @author jonpereiradev@gmail.com
+ * Result of a diff with the before and after state.
+ *
+ * @author Jonathan Pereira
+ * @since 1.0
  */
-public class DiffResult {
+public final class DiffResult {
 
-    private Object before;
-    private Object after;
-    private boolean equals;
+    private final Object before;
+    private final Object after;
+    private final boolean equals;
     private Map<String, String> properties;
 
     public DiffResult(Object before, Object after, boolean equals) {
@@ -34,7 +37,7 @@ public Map<String, String> getProperties() {
         return properties;
     }
 
-    public void setProperties(Map<String, String> properties) {
+    void setProperties(Map<String, String> properties) {
         this.properties = properties;
     }
 }

src/main/java/com/github/jonpereiradev/diffobjects/annotation/DiffMapping.java

@@ -6,23 +6,24 @@
 import java.lang.annotation.Target;
 
 /**
- * <p>A property or object annotated with this will be checked for difference between two objects.</p>
- * <p>When annotated on a object without value(), the equals method of this object will be executed.</p>
- * <p>When annotated on a object with value(), the property will be evaluated for equality.</p>
+ * A method annotated with this will be checked for difference between two objects. When annotated on a method without
+ * value(), the equals method of this object will be executed. When annotated on a method with value(), the property
+ * will be evaluated for equality.
  *
- * @author jonpereiradev@gmail.com
+ * @author Jonathan Pereira
+ * @since 1.0
  */
 @Retention(RetentionPolicy.RUNTIME)
-@Target({ElementType.METHOD, ElementType.TYPE})
+@Target({ElementType.METHOD})
 public @interface DiffMapping {
 
     /**
-     * Defines the property that will be evaluated for equality. It can be nested property like user.address.id.
+     * @return Defines the property that will be evaluated for equality. It can be nested property like user.address.id.
      */
     String value() default "";
 
     /**
-     * Aditional properties that will be on result for identification.
+     * @return Aditional properties that will be on the diff result object.
      */
     DiffProperty[] properties() default {};
 }

src/main/java/com/github/jonpereiradev/diffobjects/annotation/DiffMappings.java

@@ -6,12 +6,18 @@
 import java.lang.annotation.Target;
 
 /**
- * @author jonpereiradev@gmail.com
+ * Annotation to group multiple mappings on a method or to enable all methods if is used on a class.
+ *
+ * @author Jonathan Pereira
+ * @since 1.0
  */
 @Retention(RetentionPolicy.RUNTIME)
-@Target({ElementType.FIELD, ElementType.METHOD})
+@Target({ElementType.METHOD, ElementType.TYPE})
 public @interface DiffMappings {
 
-    DiffMapping[] value();
+    /**
+     * @return a group of mappings to make multiple diffs on a single method.
+     */
+    DiffMapping[] value() default {};
 
 }

src/main/java/com/github/jonpereiradev/diffobjects/annotation/DiffOrder.java

@@ -6,13 +6,18 @@
 import java.lang.annotation.Target;
 
 /**
- * @author jonpereiradev@gmail.com
- * @see <a href="#">https://github.com/jonpereiradev/diff-objects</a>
+ * Defines an order for the method if necessary.
+ *
+ * @author Jonathan Pereira
+ * @since 1.0
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.FIELD, ElementType.METHOD})
 public @interface DiffOrder {
 
+    /**
+     * @return a number order for the method.
+     */
     int value();
 
 }

src/main/java/com/github/jonpereiradev/diffobjects/annotation/DiffProperty.java

@@ -8,19 +8,20 @@
 /**
  * Maps a property on a mapping to be used on result.
  *
- * @author jonpereiradev@gmail.com
+ * @author Jonathan Pereira
+ * @since 1.0
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.ANNOTATION_TYPE})
 public @interface DiffProperty {
 
     /**
-     * Identifier of the property.
+     * @return identifier of the property.
      */
     String key();
 
     /**
-     * Value of the property.
+     * @return value of the property.
      */
     String value();
 

src/main/java/com/github/jonpereiradev/diffobjects/builder/DiffBuilder.java

@@ -10,7 +10,9 @@
 /**
  * Responsible to map a class and fields to be able to generate diffs.
  *
- * @author jonpereiradev@gmail.com
+ * @author Jonathan Pereira
+ * @since 1.0
+ *
  * @see DiffInstanceBuilder
  * @see DiffMappingBuilder
  * @see DiffConfiguration

src/main/java/com/github/jonpereiradev/diffobjects/builder/DiffConfiguration.java

@@ -7,6 +7,9 @@
 /**
  * Responsible for generate the configuration of the instance.
  *
+ * @author Jonathan Pereira
+ * @since 1.0
+ *
  * @see DiffBuilder
  * @see DiffInstanceBuilder
  * @see DiffMappingBuilder

src/main/java/com/github/jonpereiradev/diffobjects/builder/DiffConfigurationImpl.java

@@ -8,6 +8,16 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Responsible for generate the configuration of the instance.
+ *
+ * @author Jonathan Pereira
+ * @since 1.0
+ *
+ * @see DiffBuilder
+ * @see DiffInstanceBuilder
+ * @see DiffMappingBuilder
+ */
 final class DiffConfigurationImpl implements DiffConfiguration {
 
     private final Map<String, DiffMetadata> metadatas;