HHH-8159 - Apply fixups indicated by analysis tools

hibernate-entitymanager/src/main/java/org/hibernate/jpa/AvailableSettings.java

@@ -23,9 +23,6 @@
  */
 package org.hibernate.jpa;
 
-
-import org.hibernate.internal.util.StringHelper;
-
 /**
  * Defines the available HEM settings, both JPA-defined as well as Hibernate-specific
  * <p/>
@@ -444,7 +441,10 @@ public interface AvailableSettings {
 	 * Consider this as experimental
 	 * It is not recommended to set up this property, the configuration is stored
 	 * in the JNDI in a serialized form
+	 *
+	 * @deprecated Configuration going away.
 	 */
+	@Deprecated
 	public static final String CONFIGURATION_JNDI_NAME = "hibernate.ejb.configuration_jndi_name";
 
 	/**
@@ -463,13 +463,21 @@ public interface AvailableSettings {
 	/**
 	 * List of classes names
 	 * Internal use only
+	 *
+	 * @deprecated Was never intended for external use
 	 */
+	@Deprecated
+	@SuppressWarnings("UnusedDeclaration")
 	public static final String CLASS_NAMES = "hibernate.ejb.classes";
 
 	/**
 	 * List of annotated packages
 	 * Internal use only
+	 *
+	 * @deprecated Was never intended for external use
 	 */
+	@Deprecated
+	@SuppressWarnings("UnusedDeclaration")
 	public static final String PACKAGE_NAMES = "hibernate.ejb.packages";
 
 	/**
@@ -509,9 +517,34 @@ public interface AvailableSettings {
 	public static final String XML_FILE_NAMES = "hibernate.ejb.xml_files";
 	public static final String HBXML_FILES = "hibernate.hbmxml.files";
 	public static final String LOADED_CLASSES = "hibernate.ejb.loaded.classes";
+
+	/**
+	 * Deprecated
+	 *
+	 * @deprecated Use {@link org.hibernate.cfg.AvailableSettings#JACC_CONTEXT_ID} instead
+	 */
+	@Deprecated
 	public static final String JACC_CONTEXT_ID = org.hibernate.cfg.AvailableSettings.JACC_CONTEXT_ID;
+
+	/**
+	 * Deprecated
+	 *
+	 * @deprecated Use {@link org.hibernate.cfg.AvailableSettings#JACC_PREFIX} instead
+	 */
+	@Deprecated
 	public static final String JACC_PREFIX = org.hibernate.cfg.AvailableSettings.JACC_PREFIX;
+
+	/**
+	 * Deprecated
+	 *
+	 * @deprecated Use {@link org.hibernate.cfg.AvailableSettings#JACC_ENABLED} instead
+	 */
+	@Deprecated
 	public static final String JACC_ENABLED = org.hibernate.cfg.AvailableSettings.JACC_ENABLED;
+
+	/**
+	 * Used to pass along the name of the persistence unit.
+	 */
 	public static final String PERSISTENCE_UNIT_NAME = "hibernate.ejb.persistenceUnitName";
 
 }

hibernate-entitymanager/src/main/java/org/hibernate/jpa/HibernateEntityManagerFactory.java

@@ -42,5 +42,13 @@ public interface HibernateEntityManagerFactory extends EntityManagerFactory, Ser
 	 */
 	public SessionFactory getSessionFactory();
 
+	/**
+	 * Retrieve the EntityTypeImpl by name.  Use of the Hibernate O/RM notion the "entity name" allows support
+	 * for non-strictly-JPA models to be used in JPA APIs
+	 *
+	 * @param entityName The entity name
+	 *
+	 * @return The EntityTypeImpl
+	 */
 	public EntityTypeImpl getEntityTypeByName(String entityName);
 }

hibernate-entitymanager/src/main/java/org/hibernate/jpa/HibernatePersistenceProvider.java

@@ -80,7 +80,7 @@ public class HibernatePersistenceProvider implements PersistenceProvider {
 		final Map integration = wrap( properties );
 		final List<ParsedPersistenceXmlDescriptor> units;
 		try {
-			 units = PersistenceXmlParser.locatePersistenceUnits( integration );
+			units = PersistenceXmlParser.locatePersistenceUnits( integration );
 		}
 		catch (RuntimeException e) {
 			log.debug( "Unable to locate persistence units", e );
@@ -106,7 +106,7 @@ public class HibernatePersistenceProvider implements PersistenceProvider {
 					persistenceUnitName
 			);
 
-			boolean matches = persistenceUnitName == null || persistenceUnit.getName().equals( persistenceUnitName );
+			final boolean matches = persistenceUnitName == null || persistenceUnit.getName().equals( persistenceUnitName );
 			if ( !matches ) {
 				log.debug( "Excluding from consideration due to name mis-match" );
 				continue;
@@ -146,7 +146,7 @@ public class HibernatePersistenceProvider implements PersistenceProvider {
 	public void generateSchema(PersistenceUnitInfo info, Map map) {
 		log.tracef( "Starting generateSchema : PUI.name=%s", info.getPersistenceUnitName() );
 
-		EntityManagerFactoryBuilder builder = Bootstrap.getEntityManagerFactoryBuilder( info, map );
+		final EntityManagerFactoryBuilder builder = Bootstrap.getEntityManagerFactoryBuilder( info, map );
 		builder.generateSchema();
 	}
 

hibernate-entitymanager/src/main/java/org/hibernate/jpa/QueryHints.java

@@ -26,23 +26,62 @@ import java.util.HashSet;
 import java.util.Set;
 
 /**
- * TODO : javadoc
+ * Defines the supported JPA query hints
  *
  * @author Steve Ebersole
  */
 public class QueryHints {
 	/**
-	 * @deprecated HINT_TIMEOUT (org.hibernate.timeout),
+	 * The hint key for specifying a query timeout per Hibernate O/RM, which defines the timeout in seconds.
-	 * instead use SPEC_HINT_TIMEOUT (javax.persistence.query.timeout)
+	 *
+	 * @deprecated use {@link #SPEC_HINT_TIMEOUT} instead
+	 */
+	@Deprecated
+	public static final String HINT_TIMEOUT = "org.hibernate.timeout";
+
+	/**
+	 * The hint key for specifying a query timeout per JPA, which defines the timeout in milliseconds
+	 */
+	public static final String SPEC_HINT_TIMEOUT = "javax.persistence.query.timeout";
+
+	/**
+	 * The hint key for specifying a comment which is to be embedded into the SQL sent to the database.
 	 */
-	public static final String HINT_TIMEOUT = "org.hibernate.timeout"; // Query timeout in seconds
-	public static final String SPEC_HINT_TIMEOUT = "javax.persistence.query.timeout"; // timeout in milliseconds
 	public static final String HINT_COMMENT = "org.hibernate.comment";
+
+	/**
+	 * The hint key for specifying a JDBC fetch size, used when executing the resulting SQL.
+	 */
 	public static final String HINT_FETCH_SIZE = "org.hibernate.fetchSize";
-	public static final String HINT_CACHE_REGION = "org.hibernate.cacheRegion";
+
+	/**
+	 * The hint key for specifying whether the query results should be cached for the next (cached) execution of the
+	 * "same query".
+	 */
 	public static final String HINT_CACHEABLE = "org.hibernate.cacheable";
+
+	/**
+	 * The hint key for specifying the name of the cache region (within Hibernate's query result cache region)
+	 * to use for storing the query results.
+	 */
+	public static final String HINT_CACHE_REGION = "org.hibernate.cacheRegion";
+
+	/**
+	 * The hint key for specifying that objects loaded into the persistence context as a result of this query execution
+	 * should be associated with the persistence context as read-only.
+	 */
 	public static final String HINT_READONLY = "org.hibernate.readOnly";
+
+	/**
+	 * The hint key for specifying the cache mode ({@link org.hibernate.CacheMode}) to be in effect for the
+	 * execution of the hinted query.
+	 */
 	public static final String HINT_CACHE_MODE = "org.hibernate.cacheMode";
+
+	/**
+	 * The hint key for specifying the flush mode ({@link org.hibernate.FlushMode}) to be in effect for the
+	 * execution of the hinted query.
+	 */
 	public static final String HINT_FLUSH_MODE = "org.hibernate.flushMode";
 
 	private static final Set<String> HINTS = buildHintsSet();
@@ -64,4 +103,7 @@ public class QueryHints {
 	public static Set<String> getDefinedHints() {
 		return HINTS;
 	}
+
+	private QueryHints() {
+	}
 }

hibernate-entitymanager/src/main/java/org/hibernate/jpa/SchemaGenAction.java

@@ -93,10 +93,20 @@ public enum SchemaGenAction {
 		);
 	}
 
+	/**
+	 * Does this action include creations?
+	 *
+	 * @return {@code true} if this action is either {@link #CREATE} or {@link #BOTH}
+	 */
 	public boolean includesCreate() {
 		return this == CREATE || this == BOTH;
 	}
 
+	/**
+	 * Does this action include drops?
+	 *
+	 * @return {@code true} if this action is either {@link #DROP} or {@link #BOTH}
+	 */
 	public boolean includesDrop() {
 		return this == DROP || this == BOTH;
 	}

hibernate-entitymanager/src/main/java/org/hibernate/jpa/boot/archive/internal/ArchiveHelper.java

@@ -36,6 +36,8 @@ import org.jboss.logging.Logger;
 import org.hibernate.jpa.boot.archive.spi.ArchiveException;
 
 /**
+ * Helper for dealing with archives
+ *
  * @author Emmanuel Bernard
  * @author Steve Ebersole
  */
@@ -54,32 +56,36 @@ public class ArchiveHelper {
 	public static URL getJarURLFromURLEntry(URL url, String entry) throws IllegalArgumentException {
 		URL jarUrl;
 		String file = url.getFile();
-		if ( ! entry.startsWith( "/" ) ) entry = "/" + entry;
+		if ( ! entry.startsWith( "/" ) ) {
+			entry = "/" + entry;
+		}
 		file = file.substring( 0, file.length() - entry.length() );
-		if ( file.endsWith( "!" ) ) file = file.substring( 0, file.length() - 1 );
+		if ( file.endsWith( "!" ) ) {
+			file = file.substring( 0, file.length() - 1 );
+		}
 		try {
-			String protocol = url.getProtocol();
+			final String protocol = url.getProtocol();
 
-			if ( "jar".equals( protocol )
+			if ( "jar".equals( protocol ) || "wsjar".equals( protocol ) ) {
-					|| "wsjar".equals( protocol ) ) { //Websphere has it's own way
 				//Original URL is like jar:protocol
+				//WebSphere has it's own way
 				jarUrl = new URL( file );
 				if ( "file".equals( jarUrl.getProtocol() ) ) {
-					//not escaped, need to voodoo
 					if ( file.indexOf( ' ' ) != -1 ) {
-						//not escaped, need to voodoo
+						//not escaped, need to voodoo; goes by toURI to escape the path
-						jarUrl = new File( jarUrl.getFile() ).toURI().toURL(); //goes by toURI to escape the path
+						jarUrl = new File( jarUrl.getFile() ).toURI().toURL();
 					}
-				} //otherwise left as is
+				}
 			}
-			else if ( "zip".equals( protocol ) //Weblogic has it's own way
+			else if ( "zip".equals( protocol )
-					|| "code-source".equals( url.getProtocol() ) //OC4J prevent ejb.jar access (ie everything without path)
+					//OC4J prevent ejb.jar access (ie everything without path)
-					|| "file".equals( protocol )  //if no wrapping is done
+					|| "code-source".equals( url.getProtocol() )
-					) {
+					//if no wrapping is done
+					|| "file".equals( protocol ) ) {
 				//we have extracted the zip file, so it should be read as a file
 				if ( file.indexOf( ' ' ) != -1 ) {
-					//not escaped, need to voodoo
+					//not escaped, need to voodoo; goes by toURI to escape the path
-					jarUrl = new File(file).toURI().toURL(); //goes by toURI to escape the path
+					jarUrl = new File(file).toURI().toURL();
 				}
 				else {
 					jarUrl = new File(file).toURL();
@@ -92,7 +98,7 @@ public class ArchiveHelper {
 					jarUrl = new URL( protocol, url.getHost(), url.getPort(), file );
 				}
 				//HHH-6442: Arquilian
-				catch ( final MalformedURLException murle ) {
+				catch ( final MalformedURLException e ) {
 					//Just use the provided URL as-is, likely it has a URLStreamHandler
 					//associated w/ the instance
 					jarUrl = url;
@@ -104,13 +110,17 @@ public class ArchiveHelper {
 					"Unable to determine JAR Url from " + url + ". Cause: " + e.getMessage()
 			);
 		}
-		log.trace("JAR URL from URL Entry: " + url + " >> " + jarUrl);
+		log.trace( "JAR URL from URL Entry: " + url + " >> " + jarUrl );
 		return jarUrl;
 	}
 
 	/**
 	 * get the URL from a given path string
 	 *
+	 * @param jarPath The path that represents a URL
+	 *
+	 * @return The resolved URL reference
+	 *
 	 * @throws IllegalArgumentException is something goes wrong
 	 */
 	public static URL getURLFromPath(String jarPath) {
@@ -131,30 +141,17 @@ public class ArchiveHelper {
 		return jarUrl;
 	}
 
-	public static String unqualifiedJarFileName(URL jarUrl) {
+	/**
-		// todo : weak algorithm subject to AOOBE
+	 * Extracts the bytes out of an InputStream.  This form is the same as {@link #getBytesFromInputStream}
-		String fileName = jarUrl.getFile();
+	 * except that any {@link IOException} are wrapped as (runtime) {@link ArchiveException}
-		int exclamation = fileName.lastIndexOf( "!" );
+	 *
-		if (exclamation != -1) {
+	 * @param inputStream The stream from which to extract bytes.
-			fileName = fileName.substring( 0, exclamation );
+	 *
-		}
+	 * @return The bytes
-
+	 *
-		int slash = fileName.lastIndexOf( "/" );
+	 * @throws ArchiveException Indicates a problem accessing the stream
-		if ( slash != -1 ) {
+	 */
-			fileName = fileName.substring(
+	public static byte[] getBytesFromInputStreamSafely(InputStream inputStream) throws ArchiveException {
-					fileName.lastIndexOf( "/" ) + 1,
-					fileName.length()
-			);
-		}
-
-		if ( fileName.length() > 4 && fileName.endsWith( "ar" ) && fileName.charAt( fileName.length() - 4 ) == '.' ) {
-			fileName = fileName.substring( 0, fileName.length() - 4 );
-		}
-
-		return fileName;
-	}
-
-	public static byte[] getBytesFromInputStreamSafely(InputStream inputStream) {
 		try {
 			return getBytesFromInputStream( inputStream );
 		}
@@ -163,18 +160,30 @@ public class ArchiveHelper {
 		}
 	}
 
+	/**
+	 * Extracts the bytes out of an InputStream.
+	 *
+	 * @param inputStream The stream from which to extract bytes.
+	 *
+	 * @return The bytes
+	 *
+	 * @throws IOException Indicates a problem accessing the stream
+	 *
+	 * @see #getBytesFromInputStreamSafely(java.io.InputStream)
+	 */
 	public static byte[] getBytesFromInputStream(InputStream inputStream) throws IOException {
 		// Optimized by HHH-7835
 		int size;
-		List<byte[]> data = new LinkedList<byte[]>();
+		final List<byte[]> data = new LinkedList<byte[]>();
-		int bufferSize = 4096;
+		final int bufferSize = 4096;
 		byte[] tmpByte = new byte[bufferSize];
 		int offset = 0;
 		int total = 0;
 		for ( ;; ) {
 			size = inputStream.read( tmpByte, offset, bufferSize - offset );
-			if ( size == -1 )
+			if ( size == -1 ) {
 				break;
+			}
 
 			offset += size;
 
@@ -186,7 +195,7 @@ public class ArchiveHelper {
 			}
 		}
 
-		byte[] result = new byte[total + offset];
+		final byte[] result = new byte[total + offset];
 		int count = 0;
 		for ( byte[] arr : data ) {
 			System.arraycopy( arr, 0, result, count * arr.length, arr.length );
@@ -196,4 +205,7 @@ public class ArchiveHelper {
 
 		return result;
 	}
+
+	private ArchiveHelper() {
+	}
 }

hibernate-entitymanager/src/main/java/org/hibernate/jpa/boot/archive/internal/ExplodedArchiveDescriptor.java

@@ -43,6 +43,8 @@ import org.hibernate.jpa.boot.spi.InputStreamAccess;
 import org.hibernate.jpa.internal.EntityManagerMessageLogger;
 
 /**
+ * Descriptor for exploded (directory) archives
+ *
  * @author Steve Ebersole
  */
 public class ExplodedArchiveDescriptor extends AbstractArchiveDescriptor {
@@ -51,6 +53,13 @@ public class ExplodedArchiveDescriptor extends AbstractArchiveDescriptor {
 			ExplodedArchiveDescriptor.class.getName()
 	);
 
+	/**
+	 * Constructs an ExplodedArchiveDescriptor
+	 *
+	 * @param archiveDescriptorFactory The factory creating this
+	 * @param archiveUrl The directory URL
+	 * @param entryBasePrefix the base (within the url) that described the prefix for entries within the archive
+	 */
 	public ExplodedArchiveDescriptor(
 			ArchiveDescriptorFactory archiveDescriptorFactory,
 			URL archiveUrl,

hibernate-entitymanager/src/main/java/org/hibernate/jpa/boot/archive/internal/JarFileBasedArchiveDescriptor.java

@@ -55,6 +55,13 @@ public class JarFileBasedArchiveDescriptor extends AbstractArchiveDescriptor {
 			JarFileBasedArchiveDescriptor.class.getName()
 	);
 
+	/**
+	 * Constructs a JarFileBasedArchiveDescriptor
+	 *
+	 * @param archiveDescriptorFactory The factory creating this
+	 * @param archiveUrl The url to the JAR file
+	 * @param entry The prefix for entries within the JAR url
+	 */
 	public JarFileBasedArchiveDescriptor(
 			ArchiveDescriptorFactory archiveDescriptorFactory,
 			URL archiveUrl,
@@ -87,7 +94,7 @@ public class JarFileBasedArchiveDescriptor extends AbstractArchiveDescriptor {
 				// This algorithm assumes that the zipped file is only the URL root (including entry), not
 				// just any random entry
 				try {
-					InputStream is = new BufferedInputStream( jarFile.getInputStream( zipEntry ) );
+					final InputStream is = new BufferedInputStream( jarFile.getInputStream( zipEntry ) );
 					try {
 						final JarInputStream jarInputStream = new JarInputStream( is );
 						ZipEntry subZipEntry = jarInputStream.getNextEntry();
@@ -173,7 +180,7 @@ public class JarFileBasedArchiveDescriptor extends AbstractArchiveDescriptor {
 
 	private JarFile resolveJarFileReference() {
 		try {
-			String filePart = getArchiveUrl().getFile();
+			final String filePart = getArchiveUrl().getFile();
 			if ( filePart != null && filePart.indexOf( ' ' ) != -1 ) {
 				// unescaped (from the container), keep as is
 				return new JarFile( getArchiveUrl().getFile() );

hibernate-entitymanager/src/main/java/org/hibernate/jpa/boot/archive/internal/JarInputStreamBasedArchiveDescriptor.java

@@ -52,6 +52,13 @@ public class JarInputStreamBasedArchiveDescriptor extends AbstractArchiveDescrip
 			JarInputStreamBasedArchiveDescriptor.class.getName()
 	);
 
+	/**
+	 * Constructs a JarInputStreamBasedArchiveDescriptor
+	 *
+	 * @param archiveDescriptorFactory The factory creating this
+	 * @param url The url to the JAR file
+	 * @param entry The prefix for entries within the JAR url
+	 */
 	public JarInputStreamBasedArchiveDescriptor(
 			ArchiveDescriptorFactory archiveDescriptorFactory,
 			URL url,
@@ -74,7 +81,7 @@ public class JarInputStreamBasedArchiveDescriptor extends AbstractArchiveDescrip
 		try {
 			JarEntry jarEntry;
 			while ( ( jarEntry = jarInputStream.getNextJarEntry() ) != null ) {
-				String jarEntryName = jarEntry.getName();
+				final String jarEntryName = jarEntry.getName();
 				if ( getEntryBasePrefix() != null && ! jarEntryName.startsWith( getEntryBasePrefix() ) ) {
 					continue;
 				}

hibernate-entitymanager/src/main/java/org/hibernate/jpa/boot/archive/internal/JarProtocolArchiveDescriptor.java

@@ -38,6 +38,13 @@ import org.hibernate.jpa.boot.archive.spi.ArchiveDescriptorFactory;
 public class JarProtocolArchiveDescriptor implements ArchiveDescriptor {
 	private final ArchiveDescriptor delegateDescriptor;
 
+	/**
+	 * Constructs a JarProtocolArchiveDescriptor
+	 *
+	 * @param archiveDescriptorFactory The factory creating this
+	 * @param url The url to the JAR file
+	 * @param incomingEntry The prefix for entries within the JAR url
+	 */
 	public JarProtocolArchiveDescriptor(
 			ArchiveDescriptorFactory archiveDescriptorFactory,
 			URL url,
@@ -60,7 +67,7 @@ public class JarProtocolArchiveDescriptor implements ArchiveDescriptor {
 			subEntry = urlFile.substring( subEntryIndex + 1 );
 		}
 
-		URL fileUrl = archiveDescriptorFactory.getJarURLFromURLEntry( url, subEntry );
+		final URL fileUrl = archiveDescriptorFactory.getJarURLFromURLEntry( url, subEntry );
 		delegateDescriptor = archiveDescriptorFactory.buildArchiveDescriptor( fileUrl, subEntry );
 	}
 

hibernate-entitymanager/src/main/java/org/hibernate/jpa/boot/archive/internal/StandardArchiveDescriptorFactory.java

@@ -32,10 +32,15 @@ import org.hibernate.jpa.boot.archive.spi.ArchiveDescriptor;
 import org.hibernate.jpa.boot.archive.spi.ArchiveDescriptorFactory;
 
 /**
+ * Standard implementation of ArchiveDescriptorFactory
+ *
  * @author Emmanuel Bernard
  * @author Steve Ebersole
  */
 public class StandardArchiveDescriptorFactory implements ArchiveDescriptorFactory {
+	/**
+	 * Singleton access
+	 */
 	public static final StandardArchiveDescriptorFactory INSTANCE = new StandardArchiveDescriptorFactory();
 
 	@Override

hibernate-entitymanager/src/main/java/org/hibernate/jpa/boot/archive/internal/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * The internals of archive scanning support
+ */
+package org.hibernate.jpa.boot.archive.internal;

hibernate-entitymanager/src/main/java/org/hibernate/jpa/boot/archive/spi/AbstractArchiveDescriptor.java

@@ -33,6 +33,8 @@ import org.hibernate.jpa.boot.archive.internal.ArchiveHelper;
 import org.hibernate.jpa.boot.spi.InputStreamAccess;
 
 /**
+ * Base support for ArchiveDescriptor implementors.
+ *
  * @author Steve Ebersole
  */
 public abstract class AbstractArchiveDescriptor implements ArchiveDescriptor {
@@ -57,6 +59,7 @@ public abstract class AbstractArchiveDescriptor implements ArchiveDescriptor {
 		return entryBasePrefix.startsWith( "/" ) ? entryBasePrefix.substring( 1 ) : entryBasePrefix;
 	}
 
+	@SuppressWarnings("UnusedDeclaration")
 	protected ArchiveDescriptorFactory getArchiveDescriptorFactory() {
 		return archiveDescriptorFactory;
 	}

hibernate-entitymanager/src/main/java/org/hibernate/jpa/boot/archive/spi/ArchiveContext.java

@@ -26,12 +26,32 @@ package org.hibernate.jpa.boot.archive.spi;
 import org.hibernate.jpa.boot.spi.PersistenceUnitDescriptor;
 
 /**
+ * Describes the context for visiting the entries within an archive
+ *
 * @author Steve Ebersole
 */
 public interface ArchiveContext {
+	/**
+	 * The persistence-unit descriptor which led to this archive being scanned.
+	 *
+	 * @return The persistence-unit descriptor
+	 */
 	public PersistenceUnitDescriptor getPersistenceUnitDescriptor();
 
+	/**
+	 * Is the archive described (and being visited) the root url for the persistence-unit?
+	 *
+	 * @return {@code true} if it is the root url
+	 */
 	public boolean isRootUrl();
 
+	/**
+	 * Get the handler for the given entry, which generally is indicated by the entry type (a {@code .class} file, a
+	 * mapping file, etc).
+	 *
+	 * @param entry The archive entry
+	 *
+	 * @return The appropriate handler for the entry
+	 */
 	public ArchiveEntryHandler obtainArchiveEntryHandler(ArchiveEntry entry);
 }

hibernate-entitymanager/src/main/java/org/hibernate/jpa/boot/archive/spi/ArchiveDescriptor.java

@@ -30,5 +30,10 @@ package org.hibernate.jpa.boot.archive.spi;
  * @author Emmanuel Bernard
  */
 public interface ArchiveDescriptor {
+	/**
+	 * Perform visitation using the given context
+	 *
+	 * @param archiveContext The visitation context
+	 */
 	public void visitArchive(ArchiveContext archiveContext);
 }

hibernate-entitymanager/src/main/java/org/hibernate/jpa/boot/archive/spi/ArchiveDescriptorFactory.java

@@ -31,9 +31,48 @@ import java.net.URL;
  * @author Steve Ebersole
  */
 public interface ArchiveDescriptorFactory {
+	/**
+	 * Build a descriptor of the archive indicated by the given url
+	 *
+	 * @param url The url to the archive
+	 *
+	 * @return The descriptor
+	 */
 	public ArchiveDescriptor buildArchiveDescriptor(URL url);
-	public ArchiveDescriptor buildArchiveDescriptor(URL jarUrl, String entry);
 
+	/**
+	 * Build a descriptor of the archive indicated by the path relative to the given url
+	 *
+	 * @param url The url to the archive
+	 * @param path The path within the given url that refers to the archive
+	 *
+	 * @return The descriptor
+	 */
+	public ArchiveDescriptor buildArchiveDescriptor(URL url, String path);
+
+	/**
+	 * Given a URL which defines an entry within a JAR (really any "bundled archive" such as a jar file, zip, etc)
+	 * and an entry within that JAR, find the URL to the JAR itself.
+	 *
+	 * @param url The URL to an entry within a JAR
+	 * @param entry The entry that described the thing referred to by the URL relative to the JAR
+	 *
+	 * @return The URL to the JAR
+	 *
+	 * @throws IllegalArgumentException Generally indicates a problem  with malformed urls.
+	 */
 	public URL getJarURLFromURLEntry(URL url, String entry) throws IllegalArgumentException;
+
+	/**
+	 * Not used!
+	 *
+	 * @param jarPath The jar path
+	 *
+	 * @return The url from the path?
+	 *
+	 * @deprecated Not used!
+	 */
+	@Deprecated
+	@SuppressWarnings("UnusedDeclaration")
 	public URL getURLFromPath(String jarPath);
 }

hibernate-entitymanager/src/main/java/org/hibernate/jpa/boot/archive/spi/ArchiveEntry.java

@@ -34,7 +34,7 @@ public interface ArchiveEntry {
 	/**
 	 * Get the entry's name
 	 *
-	 * @return
+	 * @return The name
 	 */
 	public String getName();
 
@@ -42,14 +42,14 @@ public interface ArchiveEntry {
 	 * Get the relative name of the entry within the archive.  Typically what we are looking for here is
 	 * the ClassLoader resource lookup name.
 	 *
-	 * @return
+	 * @return The name relative to the archive root
 	 */
 	public String getNameWithinArchive();
 
 	/**
 	 * Get access to the stream for the entry
 	 *
-	 * @return
+	 * @return Obtain stream access to the entry
 	 */
 	public InputStreamAccess getStreamAccess();
 }

hibernate-entitymanager/src/main/java/org/hibernate/jpa/boot/archive/spi/ArchiveEntryHandler.java

@@ -29,5 +29,11 @@ package org.hibernate.jpa.boot.archive.spi;
  * @author Steve Ebersole
  */
 public interface ArchiveEntryHandler {
+	/**
+	 * Handle the entry
+	 *
+	 * @param entry The entry to handle
+	 * @param context The visitation context
+	 */
 	public void handleEntry(ArchiveEntry entry, ArchiveContext context);
 }

hibernate-entitymanager/src/main/java/org/hibernate/jpa/boot/archive/spi/ArchiveException.java

@@ -26,14 +26,27 @@ package org.hibernate.jpa.boot.archive.spi;
 import org.hibernate.HibernateException;
 
 /**
+ * Indicates a problem accessing or visiting the archive
+ *
  * @author Steve Ebersole
  */
 public class ArchiveException extends HibernateException {
+	/**
+	 * Constructs an ArchiveException
+	 *
+	 * @param message Message explaining the exception condition
+	 */
 	public ArchiveException(String message) {
 		super( message );
 	}
 
-	public ArchiveException(String message, Throwable root) {
+	/**
-		super( message, root );
+	 * Constructs an ArchiveException
+	 *
+	 * @param message Message explaining the exception condition
+	 * @param cause The underlying cause
+	 */
+	public ArchiveException(String message, Throwable cause) {
+		super( message, cause );
 	}
 }

hibernate-entitymanager/src/main/java/org/hibernate/jpa/boot/archive/spi/package-info.java

@@ -0,0 +1,15 @@
+/**
+ * Defines the SPI for support of "scanning" of "archives".
+ * <p/>
+ * Scanning might mean:<ul>
+ *     <li>searching for classes/packages that define certain interfaces</li>
+ *     <li>locating named resources</li>
+ * </ul>
+ * And "archive" might mean:<ul>
+ *     <li>a {@code .jar} file</li>
+ *     <li>an exploded directory</li>
+ *     <li>an OSGi bundle</li>
+ *     <li>etc</li>
+ * </ul>
+ */
+package org.hibernate.jpa.boot.archive.spi;

hibernate-entitymanager/src/main/java/org/hibernate/jpa/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Defines Hibernate implementation of Java Persistence specification.
+ */
+package org.hibernate.jpa;