Adding documentation

Author: cardil

README.md

@@ -29,7 +29,7 @@ If you also need support for mapping JPA managed entities and be able to update
 * `Mappings` object that will provides mapping for given source and target class - mapping is information how to update existing object (managed entity) with data from source object,
 * `IdentifierCollector` should collect managed entity ID from source object
 
-The easiest way to setup all of this is to extend `AbstractCompositeContextProvider`, implement `IdentifierCollector` and implement a set of `MappingProvider` for each type of entity. To provide implementations of `MappingProvider` you should create update methods in your MapStruct mappers.
+The easiest way to setup all of this is to extend `AbstractJpaContextProvider`, implement `IdentifierCollector` and implement a set of `MappingProvider` for each type of entity. To provide implementations of `MappingProvider` you should create update methods in your MapStruct mappers. It utilize `CompositeContext` which can incorporate any number of contexts as a composite.
 
 All of this can be managed by some DI container like Spring or Guice.
 

src/main/java/pl/wavesoftware/lang/package-info.java

@@ -1,5 +1,5 @@
 /**
- * @author <a href="krzysztof.suszynski@wavesoftware.pl">Krzysztof Suszyński</a>
+ * @author <a href="mailto:krzysztof.suszynski@wavesoftware.pl">Krzysztof Suszyński</a>
  * @since 2018-05-03
  */
 @ParametersAreNonnullByDefault

src/main/java/pl/wavesoftware/utils/mapstruct/jpa/AbstractCompositeContextMapping.java

@@ -3,16 +3,71 @@
 import pl.wavesoftware.lang.TriConsumer;
 
 /**
- * @author <a href="krzysztof.suszynski@wavesoftware.pl">Krzysztof Suszyński</a>
+ * An abstract class that can be extended to provide logic in how to apply data from
+ * {@link I} input object to an target {@link O} output object. It uses {@link CompositeContext}
+ * as a MapStruct context.
+ *
+ * <p>
+ * It's designed to be used easily with
+ * <a href="http://mapstruct.org/documentation/stable/reference/html/#updating-bean-instances">
+ *     MapStruct update methods</a>.
+ * <pre>
+ * &#064;Service
+ * &#064;RequiredArgsConstructor
+ * final class PetCompositeContextMapping extends AbstractCompositeContextMapping&lt;Pet,PetData&gt; {
+ *   private final PetMapper petMapper;
+ *   &#064;Override
+ *   public void accept(Pet pet, PetData data, CompositeContext context) {
+ *     petMapper.updateFromPet(pet, data, context);
+ *   }
+ * }
+ * </pre>
+ *
+ * There is also a convenience method {@link #mappingFor(Class, Class, TriConsumer)} which can be
+ * used to create mapping easily with {@link AbstractJpaContextProvider}:
+ *
+ * <br>
+ * <pre>
+ * &#064;RequiredArgsConstructor
+ * final class OwnerMappingProvider implements MappingProvider&lt;Owner, OwnerJPA, CompositeContext&gt; {
+ *   private final OwnerMapper ownerMapper;
+ *
+ *   &#064;Override
+ *   public Mapping&lt;Owner, OwnerJPA, CompositeContext&gt; provide() {
+ *     return AbstractCompositeContextMapping.mappingFor(
+ *       Owner.class, OwnerJPA.class,
+ *       ownerMapper::updateFromOwner
+ *     );
+ *   }
+ * }
+ * </pre>
+ *
+ * @param <I> a type of input object to map from
+ * @param <O> a type of output object to map to
+ * @author <a href="mailto:krzysztof.suszynski@wavesoftware.pl">Krzysztof Suszyński</a>
  * @since 2018-05-02
  */
-public abstract class AbstractCompositeContextMapping<I, O> extends AbstractMapping<I, O, CompositeContext> {
+public abstract class AbstractCompositeContextMapping<I, O>
+  extends AbstractMapping<I, O, CompositeContext> {
+
   protected AbstractCompositeContextMapping(Class<I> sourceClass,
                                             Class<O> targetClass) {
     super(sourceClass, targetClass, CompositeContext.class);
   }
 
-  public static <I, O> AbstractCompositeContextMapping<I, O> mapperFor(
+  /**
+   * A convenience method which can be used to create mapping easily with
+   * {@link AbstractJpaContextProvider}.
+   *
+   * @param inputClass  a class of an input object
+   * @param outputClass a class of an output object
+   * @param consumer    a consumer of 3 values: input object, output object
+   *                    and {@link CompositeContext} object
+   * @param <I> a type of input object to map from
+   * @param <O> a type of output object to map to
+   * @return a mapping for given values
+   */
+  public static <I, O> Mapping<I, O, CompositeContext> mappingFor(
     Class<I> inputClass,
     Class<O> outputClass,
     TriConsumer<I, O, CompositeContext> consumer) {

src/main/java/pl/wavesoftware/utils/mapstruct/jpa/AbstractJpaContextProvider.java

@@ -0,0 +1,52 @@
+package pl.wavesoftware.utils.mapstruct.jpa;
+
+import javax.persistence.EntityManager;
+import java.util.function.Supplier;
+
+/**
+ * A base abstract class that can be used as a provider for configured and fully working
+ * JPA aware mapping context with update capability. It's designed to be implemented and
+ * configured in your DI container to used in your mapper facade to produce new context each
+ * time you are doing a mapping.
+ *
+ * @author <a href="mailto:krzysztof.suszynski@wavesoftware.pl">Krzysztof Suszyński</a>
+ * @since 2018-05-03
+ */
+public abstract class AbstractJpaContextProvider
+  implements MapStructContextProvider<CompositeContext> {
+
+  private final JpaMappingContextProviderImpl provider =
+    new JpaMappingContextProviderImpl();
+
+  /**
+   * A method to that returns a supplier of JPA's {@link EntityManager} bounded to
+   * current transaction context.
+   *
+   * @return a supplier of current <code>EntityManager</code>
+   */
+  protected abstract Supplier<EntityManager> getEntityManager();
+
+  /**
+   * Returns a collection of mapping providers to be used in mapping. Each mapping provider
+   * is for other mapping (for ex.: Pet to PetData etc.).
+   *
+   * @return a collection of mapping providers
+   */
+  protected abstract Iterable<MappingProvider<?, ?, ?>> getMappingProviders();
+
+  /**
+   * Returns a identifier collector that can fetch an ID to be used to fetch a managed entity
+   * from {@link EntityManager}. It will try to fetch the ID from source mapping object, so
+   * it must contain some kind of way to provide it.
+   *
+   * @return a identifier collector
+   */
+  protected abstract IdentifierCollector getIdentifierCollector();
+
+  @Override
+  public CompositeContext createNewContext() {
+    return provider.provide(
+      getEntityManager(), getMappingProviders(), getIdentifierCollector()
+    );
+  }
+}

src/main/java/pl/wavesoftware/utils/mapstruct/jpa/AbstractMapping.java

@@ -4,6 +4,12 @@
 import lombok.RequiredArgsConstructor;
 
 /**
+ * An abstract mapping that holds all classes representations.
+ *
+ * @param <I> a type of input object for map from
+ * @param <O> a type of output (target) object for map to
+ * @param <C> a type of context to be used in the mapping
+ *
  * @author <a href="mailto:krzysztof.suszynski@wavesoftware.pl">Krzysztof Suszynski</a>
  * @since 25.04.18
  */

src/main/java/pl/wavesoftware/utils/mapstruct/jpa/CompositeContext.java

@@ -12,7 +12,9 @@
 import java.util.Optional;
 
 /**
- * A composite mapping context that can utilize multiple mapping contexts.
+ * A composite mapping context that can utilize multiple mapping contexts to provide
+ * the joined processing. User can add any number of {@link MappingContext} to use in
+ * this composite class.
  *
  * @author <a href="mailto:krzysztof.suszynski@wavesoftware.pl">Krzysztof Suszynski</a>
  * @since 02.05.18
@@ -75,11 +77,10 @@ private static final class CompositeContextBuilderImpl implements CompositeConte
     private final List<MappingContext> mappingContexts = new ArrayList<>();
 
     @Override
-    public CompositeContextBuilderImpl addContext(MappingContext... mappingContexts) {
+    public void addContext(MappingContext... mappingContexts) {
       this.mappingContexts.addAll(
         Arrays.asList(mappingContexts)
       );
-      return this;
     }
 
     @Override

src/main/java/pl/wavesoftware/utils/mapstruct/jpa/CompositeContextBuilder.java

@@ -1,10 +1,25 @@
 package pl.wavesoftware.utils.mapstruct.jpa;
 
 /**
+ * This is a builder for composite context.
+ *
+ * @see CompositeContext
  * @author <a href="mailto:krzysztof.suszynski@wavesoftware.pl">Krzysztof Suszynski</a>
  * @since 04.05.18
  */
 public interface CompositeContextBuilder {
-  CompositeContextBuilder addContext(MappingContext... mappingContexts);
+  /**
+   * Adds context to the builder.
+   *
+   * @param mappingContexts A mapping contexts to be added to builder and then created
+   *                        the composite context from it.
+   */
+  void addContext(MappingContext... mappingContexts);
+
+  /**
+   * Builds a composite context from provided set of other mapping contexts.
+   *
+   * @return a builded instance of composite context
+   */
   CompositeContext build();
 }

src/main/java/pl/wavesoftware/utils/mapstruct/jpa/CyclicGraphContext.java

@@ -18,7 +18,7 @@
  * cycles.
  *
  * @author Andreas Gudian
- * @author <a href="krzysztof.suszynski@wavesoftware.pl">Krzysztof Suszyński</a>
+ * @author <a href="mailto:krzysztof.suszynski@wavesoftware.pl">Krzysztof Suszyński</a>
  * @since 2018-04-12
  */
 public final class CyclicGraphContext implements MapStructContext {

src/main/java/pl/wavesoftware/utils/mapstruct/jpa/IdentifierCollector.java

@@ -21,7 +21,7 @@
  * }
  * </pre>
  *
- * @author <a href="krzysztof.suszynski@wavesoftware.pl">Krzysztof Suszyński</a>
+ * @author <a href="mailto:krzysztof.suszynski@wavesoftware.pl">Krzysztof Suszyński</a>
  * @since 2018-05-02
  */
 public interface IdentifierCollector {

src/main/java/pl/wavesoftware/utils/mapstruct/jpa/JpaMappingContext.java

@@ -1,6 +1,9 @@
 package pl.wavesoftware.utils.mapstruct.jpa;
 
 /**
+ * This is provided {@link JpaMappingContext} and  it have a factory
+ * {@link JpaMappingContextFactory}. This interface represents a JPA aware mapping context.
+ *
  * @author <a href="mailto:krzysztof.suszynski@wavesoftware.pl">Krzysztof Suszynski</a>
  * @since 02.05.18
  */