Merge pull request #2 from wavesoftware/feature/documentation

Feature: Documentation

Author: cardil

README.md

@@ -1,22 +1,163 @@
 # JPA mapping utilities for MapStruct
-  
-TODO: write readme file
 
-## Dependencies  
-  
- * Java >= 7
+A set of utilities focused on mapping JPA managed entities with MapStruct. There are different utilities for different purposes and also a all-in-one utility for maximizing ease of use.
+
+## Features
+
+* Domain model graph with cycles - via `CyclicGraphContext`
+* JPA aware mapping with update capability - via `JpaMappingContext` factory
+* [N+1 problem](https://stackoverflow.com/questions/97197/what-is-the-n1-select-query-issue) solution via special uninitialized collection classes, that throws exceptions if used
+
+### Domain model graph with cycles
+
+If you need to map a domain model with cycles in entity graph for ex.: (Pet.owner -> Person, Person.pets -> Pet) you can use a `CyclicGraphContext` as a MapStruct `@Context`
+
+```java
+@Mapper
+interface PetMapper {
+  Pet map(PetData data, @Context CyclicGraphContext context);
+  PetData map(Pet pet, @Context CyclicGraphContext context);
+}
+```
+
+### JPA aware mapping with update capability
+
+If you also need support for mapping JPA managed entities and be able to update them (not create new records) there more to be done. There is provided `JpaMappingContext` with factory. It requires couple more configuration to instantiate this context.
+
+`JpaMappingContext` factory requires:
+* Supplier of `StoringMappingContext` to handle cycles - `CyclicGraphContext` can be used here,
+* `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 `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.
+
+**Mapping facade as Spring service:**
+ 
+```java
+@Service
+@RequiredArgsConstructor
+final class MapperFacadeImpl implements MapperFacade {
+
+  private final PetMapper petMapper;
+  private final MapStructContextProvider<CompositeContext> contextProvider;
+
+  @Override
+  public PetJPA map(Pet pet) {
+    return petMapper.map(pet, contextProvider.createNewContext());
+  }
+
+  @Override
+  public Pet map(PetJPA jpa) {
+    return petMapper.map(jpa, contextProvider.createNewContext());
+  }
+}
+```
+
+**Context provider as Spring service:**
+
+```java
+@Service
+@RequiredArgsConstructor
+final class CompositeContextProvider extends AbstractCompositeContextProvider {
+
+  @Getter
+  private final JpaMappingContextFactory jpaMappingContextFactory;
+  private final List<MappingProvider<?, ?, ?>> mappingProviders;
+  @Getter
+  private final IdentifierCollector identifierCollector;
+
+  @Override
+  protected Iterable<MappingProvider> getMappingProviders() {
+    return Collections.unmodifiableSet(mappingProviders);
+  }
+
+}
+```
+
+**Example mapping provider for Pet as Spring service:**
+
+```java
+@Service
+@RequiredArgsConstructor
+final class PetMappingProvider implements MappingProvider<Pet, PetJPA, CompositeContext> {
+
+  private final PetMapper petMapper;
+
+  @Override
+  public Mapping<Pet, PetJPA, CompositeContext> provide() {
+    return AbstractCompositeContextMapping.mapperFor(
+      Pet.class, PetJPA.class,
+      petMapper::updateFromPet
+    );
+  }
+}
+```
+
+**Identifier collector implementation as Spring service:**
+
+```java
+@Service
+final class IdentifierCollectorImpl implements IdentifierCollector {
+  @Override
+  public Optional<Object> getIdentifierFromSource(Object source) {
+    if (source instanceof AbstractEntity) {
+      AbstractEntity entity = AbstractEntity.class.cast(source);
+      return Optional.ofNullable(
+        entity.getReference()
+      );
+    }
+    return Optional.empty();
+  }
+}
+```
+
+**HINT:** Complete working example in Spring can be seen in [coi-gov-pl/spring-clean-architecture hibernate module](https://github.com/coi-gov-pl/spring-clean-architecture/tree/develop/pets/persistence-hibernate/src/main/java/pl/gov/coi/cleanarchitecture/example/spring/pets/persistence/hibernate/mapper)
+ 
+**HINT:** An example for Guice can be seen in this repository in test packages.
+
+### N+1 problem solution via special uninitialized collection classes
+
+The N+1 problem is wide known and prominent problem when dealing with JPA witch utilizes lazy loading of data. Solution to this is that developers should fetch only data that they will need (for ex.: using `JOIN FETCH` in JPQL). In many cases that is not enough. It easy to slip some loop when dealing with couple of records.
+
+My solution is to detect that object is not loaded fully and provide a stub that will fail fast if data is not loaded and been tried to be used by other developer. To do that simple use `Uninitialized*` classes provided. There are `UninitializedList`, `UninitializedSet`, and `UninitializedMap`.
+
+```java
+@Mapper
+interface PetMapper {
+  // [..]
+  default List<Pet> petJPASetToPetList(Set<PetJPA> set,
+                                       @Context CompositeContext context) {
+    if (!Hibernate.isInitialized(set)) {
+      return new UninitializedList<>(PetJPA.class);
+    }
+    return set.stream()
+      .map(j -> map(j, context))
+      .collect(Collectors.toList());
+  }
+  // [..]
+}
+```
+
+**Disclaimer:** In future we plan to provide an automatic solution using dynamic proxy objects.
+
+## Dependencies
+
+ * Java >= 8
+ * [MapStruct JDK8](https://github.com/mapstruct/mapstruct/tree/master/core-jdk8) >= 1.2.0
  * [EID Exceptions](https://github.com/wavesoftware/java-eid-exceptions) library 
-  
-### Contributing  
-  
+
+### Contributing
+
 Contributions are welcome!
-  
+
 To contribute, follow the standard [git flow](http://danielkummer.github.io/git-flow-cheatsheet/) of:
-  
+
 1. Fork it
 1. Create your feature branch (`git checkout -b feature/my-new-feature`)
 1. Commit your changes (`git commit -am 'Add some feature'`)
 1. Push to the branch (`git push origin feature/my-new-feature`)
 1. Create new Pull Request
-  
+
 Even if you can't contribute code, if you have an idea for an improvement please open an [issue](https://github.com/wavesoftware/java-mapstruct-jpa/issues).

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

@@ -1,5 +1,5 @@
 /**
- * @author <a href="[email protected]">Krzysztof Suszyński</a>
+ * @author <a href="mailto:[email protected]">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="[email protected]">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:[email protected]">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:[email protected]">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:[email protected]">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:[email protected]">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:[email protected]">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="[email protected]">Krzysztof Suszyński</a>
+ * @author <a href="mailto:[email protected]">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="[email protected]">Krzysztof Suszyński</a>
+ * @author <a href="mailto:[email protected]">Krzysztof Suszyński</a>
  * @since 2018-05-02
  */
 public interface IdentifierCollector {