Rename methods and add JavaDoc

src/main/java/com/speedment/core/db/DbmsHandler.java

@@ -28,8 +28,10 @@
 import java.util.stream.Stream;
 
 /**
+ * A DbmsHandler provides the interface between Speedment an an underlying Dbms.
  *
  * @author pemi
+ * @since 2.0
  */
 public interface DbmsHandler {
 

src/main/java/com/speedment/core/db/impl/AbstractRelationalDbmsHandler.java

@@ -118,7 +118,7 @@ protected Map<String, Class<?>> readTypeMapFromDB(Connection connection) throws
         try (final ResultSet rs = connection.getMetaData().getTypeInfo()) {
             while (rs.next()) {
                 final TypeInfo typeInfo = TypeInfo.from(rs);
-                final Class<?> mappedClass = Platform.get().get(SqlTypeMapperComponent.class).map(dbms, typeInfo);
+                final Class<?> mappedClass = Platform.get().get(SqlTypeMapperComponent.class).apply(dbms, typeInfo);
                 result.put(typeInfo.getSqlTypeName(), mappedClass);
             }
         }

src/main/java/com/speedment/core/platform/component/ClassMapper.java

@@ -20,14 +20,18 @@
 import java.util.stream.Stream;
 
 /**
+ * A generic Class mapper interface. I.e. a mapper that can associate a class to
+ * an implementation of that class. Often, an interface is used as class key and
+ * then a concrete implementing class is used as an association to that
+ * interface. This creates a pluggable architecture framework.
  *
  * @author pemi
  * @param <V> The base type
  */
 public interface ClassMapper<V> {
 
     /**
-     * Adds a mapping for an item
+     * Adds a mapping for an item.
      *
      * @param item to add
      * @return the previous mapping that existed, or null

src/main/java/com/speedment/core/platform/component/Component.java

@@ -19,21 +19,23 @@
 import com.speedment.core.annotations.Api;
 
 /**
+ * A Component represents the basic functionality for a Speedment Platform
+ * Component.
  *
  * @author pemi
+ * @since 2.0
  */
 @Api(version = "2.0")
 public interface Component {
 
     /**
-     * Returns the Component interface this Component implements.
+     * Returns the Component interface Class this Component implements.
      *
-     * @return the Component interface this Component implements
+     * @return the Component interface Class this Component implements
      */
     Class<? extends Component> getComponentClass();
 
     // Lifecycle operations for plugins
-
     /**
      * This method is called whenever this Component is added to a Component
      * manager.

src/main/java/com/speedment/core/platform/component/DbmsHandlerComponent.java

@@ -26,6 +26,7 @@
  * found, the #make() method is called to provide a new instance.
  *
  * @author pemi
+ * @since 2.0
  */
 public interface DbmsHandlerComponent extends Component {
 

src/main/java/com/speedment/core/platform/component/EntityManager.java

@@ -26,9 +26,12 @@
 import java.util.Optional;
 
 /**
- * An Entity Manager can be used to handle persistence for any Entity.
+ * An Entity Manager is be used to handle persistence for any Entity. This
+ * Component provides an interface similar to JPA but is not used for any other
+ * purpose. Thus, it acts as a delegator.
  *
  * @author pemi
+ * @since 2.0
  */
 @Api(version = "2.0")
 public interface EntityManager extends Component {
@@ -39,14 +42,47 @@ default Class<EntityManager> getComponentClass() {
     }
 
     // Persistence
+    /**
+     * Persists the given Entity and returns a new {@code Optional<Entity>} that
+     * was the result of the persistence, or Optional.empty() if the method
+     * failed.
+     *
+     * @param <ENTITY> the type of the Entity
+     * @param entity to persist
+     * @return a new {@code Optional<Entity>} that was the result of the
+     * persistence, or Optional.empty() if the method failed
+     */
     <ENTITY> Optional<ENTITY> persist(ENTITY entity);
 
+    /**
+     * Updates the given Entity and returns a new {@code Optional<Entity>} that
+     * was the result of the update, or Optional.empty() if the method failed.
+     *
+     * @param <ENTITY> the type of the Entity
+     * @param entity to update
+     * @return a new {@code Optional<Entity>} that was the result of the update,
+     * or Optional.empty() if the method failed
+     */
     <ENTITY> Optional<ENTITY> update(ENTITY entity);
 
+    /**
+     * Updates the given Entity and returns a new {@code Optional<Entity>} that
+     * was the result of the update, or Optional.empty() if the method failed.
+     *
+     * @param <ENTITY> the type of the Entity
+     * @param entity to remove
+     * @return a new {@code Optional<Entity>} that was the result of the
+     * removal, or Optional.empty() if the method failed
+     */
     <ENTITY> Optional<ENTITY> remove(ENTITY entity);
 
+    /**
+     * Returns the default EntityManager from the Platform. This method is there
+     * for JPA compatibility.
+     *
+     * @return the default EntityManager from the Platform
+     */
     public static EntityManager get() {
         return Platform.get().get(EntityManager.class);
     }
-
 }

src/main/java/com/speedment/core/platform/component/JavaTypeMapperComponent.java

@@ -21,8 +21,12 @@
 import java.util.function.BiFunction;
 
 /**
+ * The JavaTypeMapperComponent provides a mapping from a certain DbmsType and
+ * Class to a certain JavaTypeMapping. By implementing custom implementation of
+ * this interface, arbitrary mappings may be carried out.
  *
  * @author pemi
+ * @since 2.0
  */
 public interface JavaTypeMapperComponent extends Component, BiFunction<DbmsType, Class<?>, JavaTypeMapping> {
 
@@ -31,4 +35,16 @@ default Class<JavaTypeMapperComponent> getComponentClass() {
         return JavaTypeMapperComponent.class;
     }
 
+    /**
+     * Applies and returns the JavaTypeMapping that corresponds to the DbmsType
+     * and the Java Class.
+     *
+     * @param dbmsType to apply
+     * @param clazz to apply
+     * @return the JavaTypeMapping that corresponds to the DbmsType and the Java
+     * Class
+     */
+    @Override
+    public JavaTypeMapping apply(DbmsType dbmsType, Class<?> clazz);
+
 }

src/main/java/com/speedment/core/platform/component/LoggerFactoryComponent.java

@@ -19,6 +19,8 @@
 import com.speedment.logging.LoggerFactory;
 
 /**
+ * The loggerFactoryComponent provides the logger factory that the Speedment
+ * framework is using. You can plug in your own LoggerFactory if needed.
  *
  * @author pemi
  */
@@ -29,8 +31,18 @@ default Class<LoggerFactoryComponent> getComponentClass() {
         return LoggerFactoryComponent.class;
     }
 
+    /**
+     * Returns the current LoggerFactory.
+     *
+     * @return the current LoggerFactory
+     */
     LoggerFactory getLoggerFactory();
 
+    /**
+     * Sets the LoggerFactory to use.
+     *
+     * @param loggerFactory to use
+     */
     void setLoggerFactory(LoggerFactory loggerFactory);
 
 }

src/main/java/com/speedment/core/platform/component/ManagerComponent.java

@@ -22,8 +22,12 @@
 import java.util.stream.Stream;
 
 /**
+ * The ManagerComponent provides the mapping between entities and their
+ * corresponding managers. Custom managers may be plugged into the Speedment
+ * framework.
  *
  * @author Emil Forslund
+ * @since 2.0
  */
 public interface ManagerComponent extends Component {
 
@@ -32,14 +36,66 @@ default Class<ManagerComponent> getComponentClass() {
         return ManagerComponent.class;
     }
 
+    /**
+     * Puts (associates) a {@link Manager} implementation into the
+     * {@code ManagerComponent}. If a previous {@link Manager} was associated
+     * with an Entity class, table or interface, that association(s) is/are
+     * replaced.
+     *
+     * @param <PK> the primary key type
+     * @param <E> the Entity interface type
+     * @param <B> the {@link Buildable} type
+     * @param manager to associate
+     */
     <PK, E, B extends Buildable<E>> void put(Manager<PK, E, B> manager);
 
+    /**
+     * Obtains and returns the currently associated {@link Manager}
+     * implementation for the given Manager interface Class.
+     *
+     * @param <PK> the primary key type
+     * @param <E> the Entity interface type
+     * @param <B> the {@link Buildable} type
+     * @param <M> the {@link Manager} interface type
+     * @param managerClass the {@link Manager} interface {@code Class}
+     * @return the currently associated {@link Manager} implementation for the
+     * given Manager interface Class
+     */
     <PK, E, B extends Buildable<E>, M extends Manager<PK, E, B>> M manager(Class<M> managerClass);
 
+    /**
+     * Obtains and returns the currently associated {@link Manager}
+     * implementation for the given Entity interface Class.
+     *
+     * @param <PK> the primary key type
+     * @param <E> the Entity interface type
+     * @param <B> the {@link Buildable} type
+     * @param entityClass the Entity interface {@code Class}
+     * @return the currently associated {@link Manager} implementation for the
+     * given Entity interface Class
+     */
     <PK, E, B extends Buildable<E>> Manager<PK, E, B> managerOf(Class<E> entityClass);
 
-    Stream<Manager<?, ?, ?>> stream();
-
+    /**
+     * Obtains and returns the currently associated {@link Manager}
+     * implementation for the given Table.
+     *
+     * @param <PK> the primary key type
+     * @param <E> the Entity interface type
+     * @param <B> the {@link Buildable} type
+     * @param table the table to use
+     * @return the currently associated {@link Manager} implementation for the
+     * given table
+     */
     <PK, E, B extends Buildable<E>> Manager<PK, E, B> findByTable(Table table);
 
+    /**
+     * Returns a {@link Stream} of all {@link Manager Managers} associated with
+     * this ManagerComponent.
+     *
+     * @return a {@link Stream} of all {@link Manager Managers} associated with
+     * this ManagerComponent
+     */
+    Stream<Manager<?, ?, ?>> stream();
+
 }

src/main/java/com/speedment/core/platform/component/PrimaryKeyFactoryComponent.java

@@ -19,24 +19,117 @@
 import java.util.List;
 
 /**
+ * The PrimaryKeyFactoryComponent is responsible for generating primary keys. By
+ * plugging in a custom PrimaryKeyFactoryComponent, one may produce custom
+ * primary keys.
  *
  * @author pemi
+ * @since 2.0
  */
 public interface PrimaryKeyFactoryComponent extends Component {
 
-    // Identity function by default
-    default <KEY> KEY make(KEY key) {
+    /**
+     * Optionally creates and return a (possibly) new key for the given key. The
+     * new key must be immutable and must produce the same hash key during its
+     * entire life-cycle.
+     *
+     * @param <K0> key type
+     * @param key the input key
+     * @return the output key that corresponds to the given key
+     */
+    // Identity function by default, Override to change
+    default <K0> K0 make(K0 key) {
         return key;
     }
 
+    // Todo: Investigate if any Object can be returned as composite keys. Not just List
+    /**
+     * Creates and return a new {@code List} that contains the given keys in the
+     * given order. The new List must be immutable and must produce the same
+     * {@link Object#hashCode()} during its entire life-cycle. List with the
+     * same input keys must produce the same {@link Object#hashCode()}.
+     *
+     * @param <K0> 0:th key type
+     * @param <K1> 1:st key type
+     * @param k0 0:th key
+     * @param k1 1:st key
+     * @return an immutable List of the keys provided
+     */
     <K0, K1> List<?> make(K0 k0, K1 k1);
 
+    /**
+     * Creates and return a new {@code List} that contains the given keys in the
+     * given order. The new List must be immutable and must produce the same
+     * {@link Object#hashCode()} during its entire life-cycle. List with the
+     * same input keys must produce the same {@link Object#hashCode()}.
+     *
+     * @param <K0> 0:th key type
+     * @param <K1> 1:st key type
+     * @param <K2> 2:nd key type
+     * @param k0 0:th key
+     * @param k1 1:st key
+     * @param k2 2:nd key
+     * @return an immutable List of the keys provided
+     */
     <K0, K1, K2> List<?> make(K0 k0, K1 k1, K2 k2);
 
+    /**
+     * Creates and return a new {@code List} that contains the given keys in the
+     * given order. The new List must be immutable and must produce the same
+     * {@link Object#hashCode()} during its entire life-cycle. List with the
+     * same input keys must produce the same {@link Object#hashCode()}.
+     *
+     * @param <K0> 0:th key type
+     * @param <K1> 1:st key type
+     * @param <K2> 2:nd key type
+     * @param <K3> 3:rd key type
+     * @param k0 0:th key
+     * @param k1 1:st key
+     * @param k2 2:nd key
+     * @param k3 3:rd key
+     * @return an immutable List of the keys provided
+     */
     <K0, K1, K2, K3> List<?> make(K0 k0, K1 k1, K2 k2, K3 k3);
 
+    /**
+     * Creates and return a new {@code List} that contains the given keys in the
+     * given order. The new List must be immutable and must produce the same
+     * {@link Object#hashCode()} during its entire life-cycle. List with the
+     * same input keys must produce the same {@link Object#hashCode()}.
+     *
+     * @param <K0> 0:th key type
+     * @param <K1> 1:st key type
+     * @param <K2> 2:nd key type
+     * @param <K3> 3:rd key type
+     * @param <K4> 4:th key type
+     * @param k0 0:th key
+     * @param k1 1:st key
+     * @param k2 2:nd key
+     * @param k3 3:rd key
+     * @param k4 4:th key
+     * @return an immutable List of the keys provided
+     */
     <K0, K1, K2, K3, K4> List<?> make(K0 k0, K1 k1, K2 k2, K3 k3, K4 k4);
 
+    /**
+     * Creates and return a new {@code List} that contains the given keys in the
+     * given order. The new List must be immutable and must produce the same
+     * {@link Object#hashCode()} during its entire life-cycle. List with the
+     * same input keys must produce the same {@link Object#hashCode()}.
+     *
+     * @param <K0> 0:th key type
+     * @param <K1> 1:st key type
+     * @param <K2> 2:nd key type
+     * @param <K3> 3:rd key type
+     * @param <K4> 4:th key type
+     * @param k0 0:th key
+     * @param k1 1:st key
+     * @param k2 2:nd key
+     * @param k3 3:rd key
+     * @param k4 4:th key
+     * @param otherKeys the 5:th to the N:th key
+     * @return an immutable List of the keys provided
+     */
     <K0, K1, K2, K3, K4> List<?> make(K0 k0, K1 k1, K2 k2, K3 k3, K4 k4, Object... otherKeys);
 
 }