Merge branch 'release-0.2'

.gitignore

@@ -6,3 +6,5 @@ build/
 .project
 *.swp
 *.versionsBackup
+.idea/
+*.iml

pom.xml

@@ -5,7 +5,7 @@
   <modelVersion>4.0.0</modelVersion>
   <groupId>ca.eandb.util</groupId>
   <artifactId>eandb-util</artifactId>
-  <version>0.2.2</version>
+  <version>0.2.3</version>
   <name>${project.groupId}:${project.artifactId}</name>
   <description>General purpose utility classes for Java.</description>
   <url>http://util.eandb.ca</url>
@@ -37,19 +37,25 @@
     </repository>
   </distributionManagement>
 
+  <properties>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
+
   <build>
     <plugins>
       <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-compiler-plugin</artifactId>
-        <version>3.1</version>
+        <version>3.7.0</version>
         <configuration>
-          <source>1.7</source>
-          <target>1.7</target>
+          <source>1.8</source>
+          <target>1.8</target>
         </configuration>
       </plugin>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-source-plugin</artifactId>
+        <version>3.0.1</version>
         <executions>
           <execution>
             <id>attach-sources</id>
@@ -62,6 +68,7 @@
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-javadoc-plugin</artifactId>
+        <version>2.10.4</version>
         <executions>
           <execution>
             <id>attach-javadocs</id>
@@ -74,6 +81,7 @@
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-gpg-plugin</artifactId>
+        <version>1.6</version>
         <executions>
           <execution>
             <id>sign-artifacts</id>
@@ -86,14 +94,4 @@
       </plugin>
     </plugins>
   </build>
-
-  <dependencies>
-    <dependency>
-      <groupId>javax.jnlp</groupId>
-      <artifactId>jnlp-api</artifactId>
-      <version>7.0</version>
-      <scope>system</scope>
-      <systemPath>${java.home}/lib/javaws.jar</systemPath>
-    </dependency>
-  </dependencies>
 </project>

src/main/java/ca/eandb/util/io/AlternateClassLoaderObjectInputStream.java

@@ -44,7 +44,8 @@ public final class AlternateClassLoaderObjectInputStream extends
   /**
    * Creates a new <code>AlternateClassLoaderObjectInputStream</code>.
    * @param in The <code>InputStream</code> to read from.
-   * @throws IOException The <code>ClassLoader</code> to use.
+   * @param loader The <code>ClassLoader</code> to use.
+   * @throws IOException if the stream cannot be read from
    */
   public AlternateClassLoaderObjectInputStream(InputStream in, ClassLoader loader)
       throws IOException {

src/main/java/ca/eandb/util/io/Archive.java

@@ -45,7 +45,7 @@ public interface Archive {
    * @return The value read from the data source if this
    *     <code>Archive</code> is for input, or <code>value</code> if this
    *     <code>Archive</code> is for output.
-   * @throws IOException
+   * @throws IOException if {@code value} could not be read or written
    */
   int archiveInt(int value) throws IOException;
 
@@ -61,7 +61,7 @@ public interface Archive {
    * @return The value read from the data source if this
    *     <code>Archive</code> is for input, or <code>value</code> if this
    *     <code>Archive</code> is for output.
-   * @throws IOException
+   * @throws IOException if {@code value} could not be read or written
    */
   boolean archiveBoolean(boolean value) throws IOException;
 
@@ -77,7 +77,10 @@ public interface Archive {
    * @return The value read from the data source if this
    *     <code>Archive</code> is for input, or <code>value</code> if this
    *     <code>Archive</code> is for output.
-   * @throws IOException
+   * @throws IOException if {@code value} could not be read or written
+   * @throws ClassNotFoundException if a class definition could not be found
+   *     while deserializing an object from this {@link Archive} (only applies
+   *     if this archive is in input mode).
    */
   Object archiveObject(Object value) throws IOException, ClassNotFoundException;
 
@@ -93,7 +96,7 @@ public interface Archive {
    * @return The value read from the data source if this
    *     <code>Archive</code> is for input, or <code>value</code> if this
    *     <code>Archive</code> is for output.
-   * @throws IOException
+   * @throws IOException if {@code value} could not be read or written
    */
   byte archiveByte(byte value) throws IOException;
 
@@ -109,7 +112,7 @@ public interface Archive {
    * @return The value read from the data source if this
    *     <code>Archive</code> is for input, or <code>value</code> if this
    *     <code>Archive</code> is for output.
-   * @throws IOException
+   * @throws IOException if {@code value} could not be read or written
    */
   char archiveChar(char value) throws IOException;
 
@@ -125,7 +128,7 @@ public interface Archive {
    * @return The value read from the data source if this
    *     <code>Archive</code> is for input, or <code>value</code> if this
    *     <code>Archive</code> is for output.
-   * @throws IOException
+   * @throws IOException if {@code value} could not be read or written
    */
   double archiveDouble(double value) throws IOException;
 
@@ -141,7 +144,7 @@ public interface Archive {
    * @return The value read from the data source if this
    *     <code>Archive</code> is for input, or <code>value</code> if this
    *     <code>Archive</code> is for output.
-   * @throws IOException
+   * @throws IOException if {@code value} could not be read or written
    */
   float archiveFloat(float value) throws IOException;
 
@@ -157,7 +160,7 @@ public interface Archive {
    * @return The value read from the data source if this
    *     <code>Archive</code> is for input, or <code>value</code> if this
    *     <code>Archive</code> is for output.
-   * @throws IOException
+   * @throws IOException if {@code value} could not be read or written
    */
   long archiveLong(long value) throws IOException;
 
@@ -173,7 +176,7 @@ public interface Archive {
    * @return The value read from the data source if this
    *     <code>Archive</code> is for input, or <code>value</code> if this
    *     <code>Archive</code> is for output.
-   * @throws IOException
+   * @throws IOException if {@code value} could not be read or written
    */
   short archiveShort(short value) throws IOException;
 
@@ -189,7 +192,7 @@ public interface Archive {
    * @return The value read from the data source if this
    *     <code>Archive</code> is for input, or <code>value</code> if this
    *     <code>Archive</code> is for output.
-   * @throws IOException
+   * @throws IOException if {@code value} could not be read or written
    */
   String archiveUTF(String value) throws IOException;
 

src/main/java/ca/eandb/util/io/FileUtil.java

@@ -188,7 +188,8 @@ public static Object readObjectFromFile(File file) throws IOException, ClassNotF
    *     <code>file</code> is an ancestor.
    * @return <code>true</code> if <code>ancestor</code> is equal to or an
    *     ancestor of <code>file</code>, <code>false</code> otherwise.
-   * @throws IOException
+   * @throws IOException if an error occurs in attempting to canonicalize
+   *     {@code file} or {@code ancestor}.
    */
   public static boolean isAncestor(File file, File ancestor) throws IOException {
     file = file.getCanonicalFile();
@@ -334,17 +335,17 @@ public static String getRelativePath(File file, File base) throws IOException {
   }
 
   /**
-     * Returns the appropriate working directory for storing application data. The result of this method is platform
-     * dependant: On linux, it will return ~/applicationName, on windows, the working directory will be located in the
-     * user's application data folder. For Mac OS systems, the working directory will be placed in the proper location
-     * in "Library/Application Support".
-     * <p/>
-     * This method will also make sure that the working directory exists. When invoked, the directory and all required
-     * subfolders will be created.
-     *
-     * @param applicationName Name of the application, used to determine the working directory.
-     * @return the appropriate working directory for storing application data.
-     */
+   * Returns the appropriate working directory for storing application data. The result of this method is platform
+   * dependant: On linux, it will return ~/applicationName, on windows, the working directory will be located in the
+   * user's application data folder. For Mac OS systems, the working directory will be placed in the proper location
+   * in "Library/Application Support".
+   * <p>
+   * This method will also make sure that the working directory exists. When invoked, the directory and all required
+   * subfolders will be created.
+   *
+   * @param applicationName Name of the application, used to determine the working directory.
+   * @return the appropriate working directory for storing application data.
+   */
   public static File getApplicationDataDirectory(final String applicationName) {
         final String userHome = System.getProperty("user.home", ".");
         final File workingDirectory;

src/main/java/ca/eandb/util/io/FileVisitor.java

@@ -40,6 +40,7 @@ public interface FileVisitor {
    * Visits a <code>File</code> while walking a directory tree.
    * @param file The <code>File</code> being visited.
    * @return A value indicating whether the tree walk should continue.
+   * @throws Exception if an error occurs while visiting the file
    * @see FileUtil#postOrderTraversal(File, FileVisitor)
    * @see FileUtil#preOrderTraversal(File, FileVisitor)
    */

src/main/java/ca/eandb/util/io/LimitedInputStream.java

@@ -119,7 +119,8 @@ public int remaining() {
 
   /**
    * Skips over the remainder of the available bytes.
-   * @throws IOException
+   * @throws IOException if an I/O error occurs while seeking within the inner
+   *     stream
    */
   public void moveToEnd() throws IOException {
     int bytes;

src/main/java/ca/eandb/util/io/StreamUtil.java

@@ -42,7 +42,7 @@ public final class StreamUtil {
   /**
    * Reads a null-terminated string of bytes from the specified input stream.
    * @param in The <code>InputStream</code> to read from.
-   * @return The <code>String</string> read from the file.
+   * @return The <code>String</code> read from the file.
    * @throws IOException If an I/O error occurs
    * @throws EOFException If the end of the file is reached before a null
    *     byte is read.
@@ -54,7 +54,7 @@ public static String readNullTerminatedString(InputStream in) throws IOException
   /**
    * Reads a null-terminated string of bytes from the specified input.
    * @param in The <code>DataInput</code> to read from.
-   * @return The <code>String</string> read from the file.
+   * @return The <code>String</code> read from the file.
    * @throws IOException If an I/O error occurs
    * @throws EOFException If the end of the file is reached before a null
    *     byte is read.