Merge branch 'master' of https://github.com/atlanmod/NeoEMF

neoemf-core/src/main/java/fr/inria/atlanmod/neoemf/core/DefaultPersistentEObject.java

@@ -47,7 +47,7 @@
  * This class extends {@link MinimalEStoreEObjectImpl} that delegates {@link EStructuralFeature} accesses
  * to an underlying {@link EStore} that interacts with the database used to store the model.
  * <p>
- * {@link DefaultPersistentEObject}s is backend-agnostic, and is as an EMF-level element wrapper in all 
+ * {@link DefaultPersistentEObject}s is backend-agnostic, and is as an EMF-level element wrapper in all
  * existing database implementations.
  */
 public class DefaultPersistentEObject extends MinimalEStoreEObjectImpl implements PersistentEObject {

neoemf-core/src/main/java/fr/inria/atlanmod/neoemf/data/store/FeatureCachingStoreDecorator.java

@@ -115,9 +115,11 @@ public void clear(InternalEObject internalObject, EStructuralFeature feature) {
     /**
      * Remove cached elements, from an initial {@code index} to the size of an element.
      *
-     * @param internalObject ???
-     * @param feature        ???
-     * @param index          ???
+     * @param internalObject the concerned object
+     * @param feature        the feature of the {@code internalObject}
+     * @param index          the index from which to start the removing
+     *
+     * @see FeatureKey#from(InternalEObject, EStructuralFeature)
      */
     private void invalidateValues(InternalEObject internalObject, EStructuralFeature feature, int index) {
         FeatureKey featureKey = FeatureKey.from(internalObject, feature);

neoemf-core/src/main/java/fr/inria/atlanmod/neoemf/resource/DefaultPersistentResource.java

@@ -58,8 +58,8 @@
 /**
  * The default implementation of a {@link PersistentResource} that contains {@link PersistentEObject}.
  * <p>
- * {@link DefaultPersistentResource}s is backend-agnostic and only delegates model element operations 
- * to its internal {@link PersistentStore} which is reponsible of database access.
+ * {@link DefaultPersistentResource}s is backend-agnostic and only delegates model element operations
+ * to its internal {@link PersistentStore} which is responsible of database access.
  */
 public class DefaultPersistentResource extends ResourceImpl implements PersistentResource {
 
@@ -312,19 +312,19 @@ public DummyRootEObject(Resource.Internal resource) {
     private static class PersistenceBackendShutdownHook extends Thread {
 
         /**
-         * The backend to stop when the application will exit
+         * The back-end to stop when the application will exit.
          */
         private final PersistenceBackend backend;
 
         /**
-         * The {@link URI} of the resource used by the {@code backend}
+         * The {@link URI} of the resource used by the {@code backend}.
          */
         private final URI uri;
 
         /**
          * Creates a new {@code PersistenceBackendShutdownHook} with the given {@code backend}.
          *
-         * @param backend the backend to stop when the application will exit
+         * @param backend the back-end to stop when the application will exit
          * @param uri     the {@link URI} of the resource used by the {@code backend}
          */
         private PersistenceBackendShutdownHook(PersistenceBackend backend, URI uri) {
@@ -335,7 +335,7 @@ private PersistenceBackendShutdownHook(PersistenceBackend backend, URI uri) {
         /**
          * Adds a shutdown hook on the given {@code backend}. It will be stopped when the application will exit.
          *
-         * @param backend the backend to stop when the application will exit
+         * @param backend the back-end to stop when the application will exit
          * @param uri     the {@link URI} of the resource used by the {@code backend}
          */
         public static void closeOnExit(PersistenceBackend backend, URI uri) {

neoemf-core/src/main/java/fr/inria/atlanmod/neoemf/resource/PersistentResource.java

@@ -14,16 +14,15 @@
 import org.eclipse.emf.common.util.EList;
 import org.eclipse.emf.ecore.EClass;
 import org.eclipse.emf.ecore.EObject;
-import org.eclipse.emf.ecore.InternalEObject;
 import org.eclipse.emf.ecore.InternalEObject.EStore;
 import org.eclipse.emf.ecore.resource.Resource;
 
 import java.io.Closeable;
 
 /**
  * Extends the {@link Resource} interface by providing efficient model-level operations that
- * are not accessible using the standard EMF API. For example, {@code getAllInstances} is a 
- * utility method that computes efficiently all the instances of a given type by delegating the 
+ * are not accessible using the standard EMF API. For example, {@code getAllInstances} is a
+ * utility method that computes efficiently all the instances of a given type by delegating the
  * operation to the underlying database, that can benefits of its internal optimizations and indices.
  */
 public interface PersistentResource extends Resource, Resource.Internal, Closeable {
@@ -32,10 +31,11 @@ public interface PersistentResource extends Resource, Resource.Internal, Closeab
     void close();
 
     /**
+     * Returns the {@link EStore} used to store the model.
      *
-     * @return the {@link EStore} used to store the model
+     * @return the {@link EStore}
      */
-    InternalEObject.EStore eStore();
+    EStore eStore();
 
     /**
      * Computes the set of instances of the given {@link EClass} (including its sub-types).

neoemf-core/src/main/java/fr/inria/atlanmod/neoemf/util/NeoEContentsEList.java

@@ -125,7 +125,7 @@ public E get(int index) {
     }
 
     /**
-     * ???
+     * An empty {@code NeoEContentsEList}.
      *
      * @param <T> the type of elements in this list
      */

neoemf-core/src/main/javadoc/fr/inria/atlanmod/neoemf/annotations/package-info.java

@@ -13,4 +13,4 @@
  * Provides common annotation types.
  */
 
-package fr.inria.atlanmod.neoemf.core;
+package fr.inria.atlanmod.neoemf.annotations;

neoemf-core/src/main/javadoc/fr/inria/atlanmod/neoemf/core/package-info.java

@@ -10,7 +10,7 @@
  */
 
 /**
- * <b>TODO:</b> Provides...
+ * Provides the base classes that extends EMF API to enable lazy-loading of model elements.
  */
 
 package fr.inria.atlanmod.neoemf.core;

neoemf-core/src/main/javadoc/fr/inria/atlanmod/neoemf/package-info.java

@@ -10,7 +10,7 @@
  */
 
 /**
- * <b>TODO:</b> Provides...
+ * Provides all NeoEMF features.
  */
 
-package fr.inria.atlanmod.neoemf.core;
+package fr.inria.atlanmod.neoemf;

neoemf-core/src/test/java/fr/inria/atlanmod/neoemf/data/AbstractPersistenceBackendFactoryTest.java

@@ -26,6 +26,21 @@ public abstract class AbstractPersistenceBackendFactoryTest extends AbstractUnit
 
     private static final String INNER_BACKEND_FIELDNAME = "backend";
 
+    private static <F> F getField(Object object, String fieldName, Class<?> in, Class<F> out) {
+        if (!in.isInstance(object)) {
+            throw new IllegalArgumentException();
+        }
+
+        try {
+            Field storeField = in.getDeclaredField(fieldName);
+            storeField.setAccessible(true);
+            return out.cast(storeField.get(object));
+        }
+        catch (NoSuchFieldException | IllegalAccessException e) {
+            throw new RuntimeException(e);
+        }
+    }
+
     protected PersistentStore getInnerStore(InternalEObject.EStore store) {
         return getField(store, INNER_STORE_FIELDNAME, AbstractPersistentStoreDecorator.class, PersistentStore.class);
     }
@@ -42,19 +57,4 @@ protected PersistenceBackend getInnerBackend(InternalEObject.EStore store) {
 
         return innerBackend;
     }
-
-    private static <F> F getField(Object object, String fieldName, Class<?> in, Class<F> out) {
-        if (!in.isInstance(object)) {
-            throw new IllegalArgumentException();
-        }
-
-        try {
-            Field storeField = in.getDeclaredField(fieldName);
-            storeField.setAccessible(true);
-            return out.cast(storeField.get(object));
-        }
-        catch (NoSuchFieldException | IllegalAccessException e) {
-            throw new RuntimeException(e);
-        }
-    }
 }

neoemf-data/blueprints/core/src/main/java/fr/inria/atlanmod/neoemf/data/blueprints/BlueprintsPersistenceBackend.java

@@ -323,11 +323,11 @@ private void setMappedVertex(Vertex vertex, PersistentEObject object) {
     }
 
     /**
-     * ???
+     * Compute the {@link EClass} associated to the model element with the provided {@link Vertex}.
      *
-     * @param vertex ???
+     * @param vertex the {@link Vertex} of the model element to compute the {@link EClass} from
      *
-     * @return ???
+     * @return an {@link EClass} representing the metaclass of the element
      */
     private EClass resolveInstanceOf(Vertex vertex) {
         EClass eClass = null;

neoemf-data/blueprints/core/src/main/java/fr/inria/atlanmod/neoemf/data/blueprints/BlueprintsPersistenceBackendFactory.java

@@ -206,14 +206,15 @@ public void copyBackend(PersistenceBackend from, PersistenceBackend to) {
     }
 
     /**
-     * ???
+     * Creates and saves the Blueprints configuration.
      *
-     * @param directory ???
-     * @param options   ???
+     * @param directory the directory where the configuration must be stored
+     * @param options   options to define the behavior of Blueprints
      *
-     * @return ???
+     * @return the created configuration
      *
-     * @throws InvalidDataStoreException if ???
+     * @throws InvalidDataStoreException if the configuration cannot be created in the {@code directory}, or if some
+     *                                   {@code options} are missing or invalid.
      */
     private PropertiesConfiguration getOrCreateBlueprintsConfiguration(File directory, Map<?, ?> options) throws InvalidDataStoreException {
         PropertiesConfiguration configuration;

neoemf-data/blueprints/core/src/main/java/fr/inria/atlanmod/neoemf/data/blueprints/option/AbstractBlueprintsOptionsBuilder.java

@@ -13,6 +13,7 @@
 
 import fr.inria.atlanmod.neoemf.data.blueprints.store.DirectWriteBlueprintsCacheManyStore;
 import fr.inria.atlanmod.neoemf.data.blueprints.store.DirectWriteBlueprintsStore;
+import fr.inria.atlanmod.neoemf.data.store.AutocommitStoreDecorator;
 import fr.inria.atlanmod.neoemf.option.AbstractPersistenceOptionsBuilder;
 import fr.inria.atlanmod.neoemf.option.PersistenceOptions;
 import fr.inria.atlanmod.neoemf.option.PersistenceOptionsBuilder;
@@ -58,6 +59,7 @@ protected B graph(String graphType) {
      * @return this builder (for chaining)
      *
      * @see BlueprintsStoreOptions#AUTOCOMMIT
+     * @see AutocommitStoreDecorator
      */
     public B autocommit() {
         return storeOption(BlueprintsStoreOptions.AUTOCOMMIT);
@@ -71,6 +73,7 @@ public B autocommit() {
      * @return this builder (for chaining)
      *
      * @see BlueprintsStoreOptions#AUTOCOMMIT
+     * @see AutocommitStoreDecorator
      */
     public B autocommit(int chunk) {
         storeOption(BlueprintsStoreOptions.AUTOCOMMIT);

neoemf-data/blueprints/core/src/main/java/fr/inria/atlanmod/neoemf/data/blueprints/option/BlueprintsStoreOptions.java

@@ -14,8 +14,11 @@
 import fr.inria.atlanmod.neoemf.data.blueprints.store.DirectWriteBlueprintsCacheManyStore;
 import fr.inria.atlanmod.neoemf.data.blueprints.store.DirectWriteBlueprintsStore;
 import fr.inria.atlanmod.neoemf.data.store.AutocommitStoreDecorator;
+import fr.inria.atlanmod.neoemf.data.store.DirectWriteStore;
 import fr.inria.atlanmod.neoemf.option.PersistentStoreOptions;
 
+import org.eclipse.emf.ecore.EReference;
+
 /**
  * {@link PersistentStoreOptions} that hold Blueprints related database access features, such as autocommit or direct
  * write behavior.
@@ -27,17 +30,24 @@
 public enum BlueprintsStoreOptions implements PersistentStoreOptions {
 
     /**
-     * ???
+     * Automatically saves modifications as calls are made.
+     *
+     * @see AutocommitStoreDecorator
      */
     AUTOCOMMIT,
 
     /**
-     * ???
+     * Translates model-level operations to Blueprints calls <i>(default {@link DirectWriteStore})</i>.
+     *
+     * @see DirectWriteBlueprintsStore
      */
     DIRECT_WRITE,
 
     /**
-     * ???
+     * Translates model-level operations to Blueprints calls, and uses an internal cache to store elements that are
+     * part of multi-valued {@link EReference}s to speed-up their access.
+     *
+     * @see DirectWriteBlueprintsCacheManyStore
      */
     CACHE_MANY
 }

neoemf-data/blueprints/core/src/main/javadoc/fr/inria/atlanmod/neoemf/data/blueprints/configuration/package-info.java

@@ -11,9 +11,9 @@
 
 /**
  * Provides utility configuration classes that are dynamically called to setup Blueprints databases.
- * 
- * @note The classes in this package have to be overriden for each backend implementation that has to
- * perform some startup configuration.
+ *
+ * @note The classes in this package have to be overriden for each back-end implementation that has to perform some
+ * startup configuration.
  */
 
 package fr.inria.atlanmod.neoemf.data.blueprints.configuration;

neoemf-data/blueprints/core/src/main/javadoc/fr/inria/atlanmod/neoemf/data/blueprints/io/package-info.java

@@ -10,11 +10,13 @@
  */
 
 /**
- * Provides Blueprints' specific readers and writers used in the {@code io} module to save and persist models from external sources.
+ * Provides Blueprints' specific readers and writers used in the {@code io} module to save and persist models from
+ * external sources.
  * <p>
- * Providing efficient model import and export is tightly coupled to the database and the data representation. In order to provide this
- * feature, a backend module should contain an I/O specific package that overrides {@link fr.inria.atlanmod.neoemf.io.persistence.AbstractPersistenceHandler}.
- * 
+ * Providing efficient model import and export is tightly coupled to the database and the data representation. In order
+ * to provide this feature, a back-end module should contain an I/O specific package that overrides {@link
+ * fr.inria.atlanmod.neoemf.io.persistence.AbstractPersistenceHandler}.
+ *
  * @see fr.inria.atlanmod.neoemf.io.persistence.AbstractPersistenceHandler
  */
 

neoemf-data/blueprints/core/src/main/javadoc/fr/inria/atlanmod/neoemf/data/blueprints/option/package-info.java

@@ -11,10 +11,9 @@
 
 /**
  * Provides utility classes to define specific behaviors of Blueprints data persistence.
- * 
- * @note Options defined using the classes inside this package are usable for each Blueprints 
- * implementation. For backend-specific configuration refers to the corresponding package in the
- * backend plugin.
+ *
+ * @note Options defined using the classes inside this package are usable for each Blueprints implementation. For
+ * backend-specific configuration refers to the corresponding package in the backend plugin.
  */
 
 package fr.inria.atlanmod.neoemf.data.blueprints.option;

neoemf-data/blueprints/neo4j/src/main/javadoc/fr/inria/atlanmod/neoemf/data/blueprints/neo4j/option/package-info.java

@@ -11,11 +11,9 @@
 
 /**
  * Provides utility classes to define specific behaviors of Neo4j data persistence.
- * 
- * @note Options defined using the classes inside this package are only usable with Neo4j as the concrete
- * implementation of the Blueprints API. Neo4j specific options can be combined with Blueprints generic
- * options.
- * 
+ *
+ * @note Options defined using the classes inside this package are only usable with Neo4j as the concrete implementation
+ * of the Blueprints API. Neo4j specific options can be combined with Blueprints generic options.
  * @see fr.inria.atlanmod.neoemf.data.blueprints.option.BlueprintsOptionsBuilder
  */
 

neoemf-data/hbase/src/main/java/fr/inria/atlanmod/neoemf/data/hbase/HBasePersistenceBackend.java

@@ -20,12 +20,12 @@
  * Mock {@link PersistenceBackend} implementation for HBase to fit core architecture.
  * <p>
  * This class does not access HBase database, but is here to fit the requirement of the
- * core architecture. For historical reasons the real access to the HBase Table 
+ * core architecture. For historical reasons the real access to the HBase Table
  * is done in {@link DirectWriteHBaseStore} and {@link ReadOnlyHBaseStore}.
  * <p>
- * Moving HBase access to this class to fit NeoEMF backend architecture is planned in
+ * Moving HBase access to this class to fit NeoEMF back-end architecture is planned in
  * a future release.
- * 
+ *
  * @see DirectWriteHBaseStore
  * @see ReadOnlyHBaseStore
  */

neoemf-data/hbase/src/main/java/fr/inria/atlanmod/neoemf/data/hbase/HBasePersistenceBackendFactory.java

@@ -36,15 +36,15 @@
 /**
  * A factory that creates instances of {@link HBasePersistenceBackend}.
  * <p>
- * This class only creates persistent databases that can be configured using 
+ * This class only creates persistent databases that can be configured using
  * {@link PersistentResource#save(Map)} and {@link PersistentResource#load(Map)}
  * options maps.
  * <p>
- * Note that transient backends can be instantiated using this factory, but they will
+ * Note that transient back-ends can be instantiated using this factory, but they will
  * be handed as persistent ones. This is a limitation that will be solved in next releases.
  * To avoid any consistency issue we recommend every HBase resource right after their creation,
- * ensuring the resource is using a persistent backend.
- * 
+ * ensuring the resource is using a persistent back-end.
+ *
  * @see PersistentResource
  * @see HBasePersistenceBackend
  * @see HBaseOptionsBuilder

neoemf-data/hbase/src/main/java/fr/inria/atlanmod/neoemf/data/hbase/option/HBaseResourceOptions.java

@@ -11,6 +11,7 @@
 
 package fr.inria.atlanmod.neoemf.data.hbase.option;
 
+import fr.inria.atlanmod.neoemf.data.hbase.store.ReadOnlyHBaseStore;
 import fr.inria.atlanmod.neoemf.option.PersistentResourceOptions;
 
 /**
@@ -19,7 +20,9 @@
 public interface HBaseResourceOptions extends PersistentResourceOptions {
 
     /**
-     * The key value to set the {@code read-only} nature of the resource.
+     * Only allows read operations on the underlying database.
+     *
+     * @see ReadOnlyHBaseStore
      */
     String READ_ONLY = "hbase.readOnly";
 }