Merge remote-tracking branch 'remotes/origin/development'

jopa-api/src/main/java/cz/cvut/kbss/jopa/exceptions/CardinalityConstraintViolatedException.java

@@ -1,11 +1,11 @@
 /**
  * Copyright (C) 2016 Czech Technical University in Prague
- *
+ * <p>
  * This program is free software: you can redistribute it and/or modify it under
  * the terms of the GNU General Public License as published by the Free Software
  * Foundation, either version 3 of the License, or (at your option) any
  * later version.
- *
+ * <p>
  * This program is distributed in the hope that it will be useful, but WITHOUT
  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
@@ -16,21 +16,12 @@
 
 /**
  * This exception is thrown when cardinality restriction constraint is violated.
- * <p/>
+ * <p>
  * For example when the model expects only single value of a property but multiple are present.
- * <p/>
  */
 public class CardinalityConstraintViolatedException extends IntegrityConstraintViolatedException {
 
-    public CardinalityConstraintViolatedException(String message, Throwable cause) {
-        super(message, cause);
-    }
-
     public CardinalityConstraintViolatedException(String message) {
         super(message);
     }
-
-    public CardinalityConstraintViolatedException(Throwable cause) {
-        super(cause);
-    }
 }

jopa-api/src/main/java/cz/cvut/kbss/jopa/model/EntityManager.java

@@ -1,11 +1,11 @@
 /**
  * Copyright (C) 2016 Czech Technical University in Prague
- *
+ * <p>
  * This program is free software: you can redistribute it and/or modify it under
  * the terms of the GNU General Public License as published by the Free Software
  * Foundation, either version 3 of the License, or (at your option) any
  * later version.
- *
+ * <p>
  * This program is distributed in the hope that it will be useful, but WITHOUT
  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
@@ -30,7 +30,7 @@
 public interface EntityManager {
 
     /**
-     * Make an instance managed and persistent. </p>
+     * Make an instance managed and persistent.
      * <p>
      * The entity is persisted into the default context.
      *
@@ -47,7 +47,7 @@ public interface EntityManager {
     void persist(final Object entity);
 
     /**
-     * Make an instance managed and persistent. </p>
+     * Make an instance managed and persistent.
      * <p>
      * The {@code descriptor} represents repository and context into which the entity and its fields should be
      * persisted.
@@ -65,7 +65,7 @@ public interface EntityManager {
     void persist(final Object entity, final Descriptor descriptor);
 
     /**
-     * Merge the state of the given entity into the current persistence context. </p>
+     * Merge the state of the given entity into the current persistence context.
      * <p>
      * The entity is merged into the default repository context.
      *
@@ -101,8 +101,10 @@ public interface EntityManager {
     void remove(final Object entity);
 
     /**
-     * Find by primary key. </p> <p> Search for an entity of the specified class and primary key. If the entity instance
-     * is contained in the persistence context, it is returned from there. </p>
+     * Find by primary key.
+     * <p>
+     * Search for an entity of the specified class and primary key. If the entity instance is contained in the
+     * persistence context, it is returned from there.
      *
      * @param entityClass Entity class
      * @param primaryKey  Primary key
@@ -114,8 +116,10 @@ public interface EntityManager {
     <T> T find(final Class<T> entityClass, final Object primaryKey);
 
     /**
-     * Find by primary key. </p> <p> Search for an entity of the specified class and primary key. If the entity instance
-     * is contained in the persistence context, it is returned from there. </p>
+     * Find by primary key.
+     * <p>
+     * Search for an entity of the specified class and primary key. If the entity instance is contained in the
+     * persistence context, it is returned from there.
      * <p>
      * The {@code repository} parameter represents repository and context in which the entity should be looked for.
      *
@@ -130,7 +134,7 @@ public interface EntityManager {
      * @see #getContexts()
      */
     <T> T find(final Class<T> entityClass, final Object primaryKey,
-                      final Descriptor descriptor);
+               final Descriptor descriptor);
 
     // TODO JPA 2.0 find with properties
 
@@ -197,7 +201,7 @@ <T> T find(final Class<T> entityClass, final Object primaryKey,
     // TODO JPA 2.0 lock with lock mode and properties
 
     /**
-     * Refresh the state of the instance from the data source, overwriting changes made to the entity, if any. </p>
+     * Refresh the state of the instance from the data source, overwriting changes made to the entity, if any.
      *
      * @param entity The entity instance to refresh
      * @throws IllegalArgumentException     if not an entity or entity is not managed
@@ -236,7 +240,7 @@ <T> T find(final Class<T> entityClass, final Object primaryKey,
     boolean contains(Object entity);
 
     /**
-     * Checks consistency of the specified context. </p>
+     * Checks consistency of the specified context.
      * <p>
      * The context URI can be {@code null}, which indicates that consistency of the whole repository should be
      * verified.
@@ -286,13 +290,15 @@ <T> T find(final Class<T> entityClass, final Object primaryKey,
     /**
      * Create an instance of TypedQuery for executing a SPARQL named query.
      * <p>
-     * The select list of the query must contain only a single item, which must be assignable to the type specified by the resultClass argument.
+     * The select list of the query must contain only a single item, which must be assignable to the type specified by
+     * the resultClass argument.
      *
-     * @param name       the name of a query defined in metadata
+     * @param name        the name of a query defined in metadata
      * @param resultClass the type of the query result
      * @return the new query instance
      * @throws IllegalArgumentException if a query has not been defined with the given name or if the query string is
-     *                                  found to be invalid or if the query result is found to not be assignable to the specified type
+     *                                  found to be invalid or if the query result is found to not be assignable to the
+     *                                  specified type
      */
     <T> TypedQuery<T> createNamedQuery(String name, Class<T> resultClass);
 
@@ -350,6 +356,8 @@ <T> T find(final Class<T> entityClass, final Object primaryKey,
     /**
      * Return the underlying provider object for the EntityManager, if available. The result of this method is
      * implementation specific.
+     *
+     * @return underlying provider object for EntityManager
      */
     Object getDelegate();
 
@@ -380,6 +388,9 @@ <T> T find(final Class<T> entityClass, final Object primaryKey,
     EntityTransaction getTransaction();
 
     /**
+     * Return the entity manager factory for the entity manager.
+     *
+     * @return EntityManagerFactory instance
      * @since JPA 2.0
      */
     EntityManagerFactory getEntityManagerFactory();
@@ -396,25 +407,32 @@ <T> T find(final Class<T> entityClass, final Object primaryKey,
 //	public String getLabel(final String iri);
 
     /**
-     * Returns a list of repository contexts available to this entity manager. </p>
+     * Returns a list of repository contexts available to this entity manager.
      *
      * @return List of repository context URIs
      */
     @NonJPA
     List<URI> getContexts();
 
     // TODO JPA 2.0 public CriteriaBuilder getCriteriaBuilder();
+
+    /**
+     * Return an instance of Metamodel interface for access to the metamodel of the persistence unit.
+     *
+     * @return Metamodel instance
+     */
     Metamodel getMetamodel();
 
     /**
-     * Sets the transactional ontology as the one which will be used when processing SPARQL queries. </p> <p> This
-     * setting may have significant impact on query results, since changes made during transaction are propagated to the
-     * transactional ontology, which is private to this persistence context, before commit. The ontology can even be in
-     * an inconsistent state. </p>
+     * Sets the transactional ontology as the one which will be used when processing SPARQL queries.
+     * <p>
+     * This setting may have significant impact on query results, since changes made during transaction are propagated
+     * to the transactional ontology, which is private to this persistence context, before commit. The ontology can even
+     * be in an inconsistent state.
      * <p>
      * This is the default setting, unless changed by properties passed on persistence initialization.
      *
-     * @see #setUseBackupOntologyForQueryProcessing()
+     * @see #setUseBackupOntologyForQueryProcessing
      */
     @NonJPA
     void setUseTransactionalOntologyForQueryProcessing();
@@ -429,7 +447,7 @@ <T> T find(final Class<T> entityClass, final Object primaryKey,
     boolean useTransactionalOntologyForQueryProcessing();
 
     /**
-     * Sets the backup ontology as the one which will be used for processing of SPARQL queries. </p>
+     * Sets the backup ontology as the one which will be used for processing of SPARQL queries.
      * <p>
      * The backup ontology represents the ontology after the last commit done by any transaction and therefore can
      * produce different results from those produced by the transactional ontology, which is private to this persistence
@@ -441,7 +459,7 @@ <T> T find(final Class<T> entityClass, final Object primaryKey,
     void setUseBackupOntologyForQueryProcessing();
 
     /**
-     * Returns true if the backup (central) ontology should be used for SPARQL query processing. </p>
+     * Returns true if the backup (central) ontology should be used for SPARQL query processing.
      *
      * @return {@code true} if the central ontology will be used, {@code false} otherwise
      * @see #setUseBackupOntologyForQueryProcessing()

jopa-api/src/main/java/cz/cvut/kbss/jopa/model/EntityManagerFactory.java

@@ -1,11 +1,11 @@
 /**
  * Copyright (C) 2016 Czech Technical University in Prague
- *
+ * <p>
  * This program is free software: you can redistribute it and/or modify it under
  * the terms of the GNU General Public License as published by the Free Software
  * Foundation, either version 3 of the License, or (at your option) any
  * later version.
- *
+ * <p>
  * This program is distributed in the hope that it will be useful, but WITHOUT
  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
@@ -35,6 +35,9 @@ public interface EntityManagerFactory {
      * Create a new EntityManager with the specified Map of properties. This
      * method returns a new EntityManager instance each time it is invoked. The
      * isOpen method will return true on the returned instance.
+     *
+     * @param map properties for entity manager
+     * @return entity manager instance
      */
     EntityManager createEntityManager(Map<String, String> map);
 
@@ -97,15 +100,14 @@ public interface EntityManagerFactory {
     PersistenceUnitUtil getPersistenceUnitUtil();
 
     /**
-     * Define the query or typed query as a named query such that future query objects can be
-     * created from it using the {@code createNamedQuery} method.
-     * Any configuration of the query object (except for actual parameter binding) in effect when the named query is
-     * added is retained as part of the named query definition. This includes configuration information such as max results
-     * and result set mapping information.
+     * Define the query or typed query as a named query such that future query objects can be created from it using the
+     * {@code createNamedQuery} method. Any configuration of the query object (except for actual parameter binding) in
+     * effect when the named query is added is retained as part of the named query definition. This includes
+     * configuration information such as max results and result set mapping information.
      * <p>
-     * When the query is executed, information that can be set by means of the query APIs can be overridden.
-     * Information that is overridden does not affect the named query as registered with the entity manager factory,
-     * and thus does not affect subsequent query objects created from it by means of the {@code createNamedQuery} method.
+     * When the query is executed, information that can be set by means of the query APIs can be overridden. Information
+     * that is overridden does not affect the named query as registered with the entity manager factory, and thus does
+     * not affect subsequent query objects created from it by means of the {@code createNamedQuery} method.
      * <p>
      * If a named query of the same name has been previously defined, either statically via metadata or via this method,
      * that query definition is replaced.

jopa-api/src/main/java/cz/cvut/kbss/jopa/model/PersistenceProvider.java

@@ -1,11 +1,11 @@
 /**
  * Copyright (C) 2016 Czech Technical University in Prague
- *
+ * <p>
  * This program is free software: you can redistribute it and/or modify it under
  * the terms of the GNU General Public License as published by the Free Software
  * Foundation, either version 3 of the License, or (at your option) any
  * later version.
- *
+ * <p>
  * This program is distributed in the hope that it will be useful, but WITHOUT
  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
@@ -17,7 +17,10 @@
 import java.util.Map;
 
 /**
- * @see JPA 2.0
+ * Interface implemented by the persistence provider.
+ * <p>
+ * It is invoked by the container in Java EE environments and by the Persistence class in Java SE environments to create
+ * an EntityManagerFactory and/or to cause schema generation to occur.
  */
 public interface PersistenceProvider {
 

jopa-api/src/main/java/cz/cvut/kbss/jopa/model/PersistenceProviderResolver.java

@@ -1,11 +1,11 @@
 /**
  * Copyright (C) 2016 Czech Technical University in Prague
- *
+ * <p>
  * This program is free software: you can redistribute it and/or modify it under
  * the terms of the GNU General Public License as published by the Free Software
  * Foundation, either version 3 of the License, or (at your option) any
  * later version.
- *
+ * <p>
  * This program is distributed in the hope that it will be useful, but WITHOUT
  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
@@ -19,29 +19,27 @@
 /**
  * Determine the list of persistence providers available in the runtime
  * environment.
- * 
+ * <p>
  * Implementations must be thread-safe.
- * 
+ * <p>
  * Note that the getPersistenceProviders method can potentially be called many
  * times: it is recommended that the implementation of this method make use of
  * caching.
+ *
+ * @see PersistenceProvider
  */
 public interface PersistenceProviderResolver {
 
-	/**
-	 * Returns a list of the PersdistenceProvider implementations available in
-	 * the runtime environment.
-	 * 
-	 * @return list of the persistence providers available in the environment
-	 * 
-	 * @see JPA 2.0
-	 */
-	List<PersistenceProvider> getPersistenceProviders();
+    /**
+     * Returns a list of the PersistenceProvider implementations available in
+     * the runtime environment.
+     *
+     * @return list of the persistence providers available in the environment
+     */
+    List<PersistenceProvider> getPersistenceProviders();
 
-	/**
-	 * Clear cache of providers
-	 * 
-	 * @see JPA 2.0
-	 */
-	void clearCachedProviders();
+    /**
+     * Clear cache of providers
+     */
+    void clearCachedProviders();
 }

jopa-api/src/main/java/cz/cvut/kbss/jopa/model/PersistenceProviderResolverHolder.java

@@ -1,11 +1,11 @@
 /**
  * Copyright (C) 2016 Czech Technical University in Prague
- *
+ * <p>
  * This program is free software: you can redistribute it and/or modify it under
  * the terms of the GNU General Public License as published by the Free Software
  * Foundation, either version 3 of the License, or (at your option) any
  * later version.
- *
+ * <p>
  * This program is distributed in the hope that it will be useful, but WITHOUT
  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more