[MSHARED-860] deprecate PropertyUtils constructor and clean up docs

src/main/java/org/apache/maven/shared/utils/PathTool.java

@@ -35,6 +35,17 @@
  */
 public class PathTool
 {
+
+    /**
+     * The constructor.
+     *
+     * @deprecated This is a utility class with only static methods. Don't create instances of it.
+     */
+    @Deprecated
+    public PathTool()
+    {
+    }    
+
     /**
      * Determines the relative path of a filename from a base directory.
      * This method is useful in building relative links within pages of

src/main/java/org/apache/maven/shared/utils/PropertyUtils.java

@@ -29,35 +29,35 @@
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
-import org.apache.maven.shared.utils.io.IOUtil;
-
 /**
- *
+ * Static utility methods for loading properties.
  */
 public class PropertyUtils
 {
 
     /**
      * The constructor.
+     *
+     * @deprecated This is a utility class with only static methods. Don't create instances of it.
      */
+    @Deprecated
     public PropertyUtils()
     {
-        // should throw new IllegalAccessError( "Utility class" );
     }
 
     /**
-     * @param url The URL which should be used to load the properties.
-     * @return The loaded properties.
-     * @deprecated As of 3.1.0, please use method {@link #loadOptionalProperties(java.net.URL)}. This method should not
+     * @param url the URL which should be used to load the properties
+     * @return the loaded properties
+     * @deprecated use {@link #loadOptionalProperties(java.net.URL)} instead. This method should not
      *             be used as it suppresses exceptions silently when loading properties fails and returns {@code null}
      *             instead of an empty {@code Properties} instance when the given {@code URL} is {@code null}.
      */
     @Deprecated
     public static java.util.Properties loadProperties( @Nonnull URL url )
     {
-        try
+        try ( InputStream in = url.openStream() )
         {
-            return loadProperties( url.openStream() );
+            return loadProperties( in );
         }
         catch ( Exception e )
         {
@@ -67,18 +67,18 @@ public static java.util.Properties loadProperties( @Nonnull URL url )
     }
 
     /**
-     * @param file The file from which the properties will be loaded.
-     * @return The loaded properties.
-     * @deprecated As of 3.1.0, please use method {@link #loadOptionalProperties(java.io.File)}. This method should not
+     * @param file the file from which the properties will be loaded
+     * @return the loaded properties
+     * @deprecated use {@link #loadOptionalProperties(java.io.File)} instead. This method should not
      *             be used as it suppresses exceptions silently when loading properties fails and returns {@code null}
      *             instead of an empty {@code Properties} instance when the given {@code File} is {@code null}.
      */
     @Deprecated
     public static Properties loadProperties( @Nonnull File file )
     {
-        try
+        try  ( InputStream in = new FileInputStream( file ) )
         {
-            return loadProperties( new FileInputStream( file ) );
+            return loadProperties( in );
         }
         catch ( Exception e )
         {
@@ -88,23 +88,26 @@ public static Properties loadProperties( @Nonnull File file )
     }
 
     /**
+     * Loads {@code Properties} from an {@code InputStream} and closes the stream.
+     * In a future release, this will no longer close the stream, so callers
+     * should close the stream themselves.  
+     * 
      * @param is {@link InputStream}
-     * @return The loaded properties.
-     * @deprecated As of 3.1.0, please use method {@link #loadOptionalProperties(java.io.InputStream)}. This method
+     * @return the loaded properties
+     * @deprecated use {@link #loadOptionalProperties(java.io.InputStream)} instead. This method
      *             should not be used as it suppresses exceptions silently when loading properties fails.
      */
     @Deprecated
     public static Properties loadProperties( @Nullable InputStream is )
     {
         try
         {
-            // to make this the same behaviour as the others we should really return null on any error
             Properties result = new Properties();
             if ( is != null )
             {
-                try
+                try ( InputStream in = is )
                 {
-                    result.load( is );
+                    result.load( in );
                 }
                 catch ( IOException e )
                 {
@@ -117,10 +120,6 @@ public static Properties loadProperties( @Nullable InputStream is )
         {
             // ignore
         }
-        finally
-        {
-            IOUtil.close( is );
-        }
         return null;
     }
 
@@ -154,7 +153,7 @@ public static Properties loadOptionalProperties( final @Nullable URL url )
     }
 
     /**
-     * Loads {@code Properties} from a given {@code File}.
+     * Loads {@code Properties} from a {@code File}.
      * <p>
      * If the given {@code File} is {@code null} or the properties file can't be read, an empty properties object is
      * returned.
@@ -185,11 +184,10 @@ public static Properties loadOptionalProperties( final @Nullable File file )
     }
 
     /**
-     * Loads {@code Properties} from a given {@code InputStream}.
-     * <p>
+     * Loads {@code Properties} from an {@code InputStream} and closes the stream.
      * If the given {@code InputStream} is {@code null} or the properties can't be read, an empty properties object is
-     * returned.
-     * </p>
+     * returned. In a future release, this will no longer close the stream, so callers
+     * should close the stream themselves.  
      *
      * @param inputStream the properties resource to load or {@code null}
      * @return the loaded properties or an empty {@code Properties} instance if properties fail to load
@@ -203,18 +201,14 @@ public static Properties loadOptionalProperties( final @Nullable InputStream inp
 
         if ( inputStream != null )
         {
-            try
+            try ( InputStream in = inputStream ) // reassign inputStream to autoclose
             {
-                properties.load( inputStream );
+                properties.load( in );
             }
             catch ( IllegalArgumentException | IOException ex )
             {
                 // ignore and return empty properties
             }
-            finally
-            {
-                IOUtil.close( inputStream );
-            }
         }
 
         return properties;

src/test/java/org/apache/maven/shared/utils/PropertyUtilsTest.java

@@ -33,7 +33,6 @@
 import java.net.URL;
 import java.util.Properties;
 
-import org.apache.maven.shared.utils.io.IOUtil;
 import org.junit.Rule;
 import org.junit.Test;
 import org.junit.rules.TemporaryFolder;
@@ -166,46 +165,30 @@ public void loadValidInputStream() throws UnsupportedEncodingException
     @SuppressWarnings( "deprecation" )
     public void loadValidFile() throws IOException
     {
-        OutputStream out = null;
-        try
+        File valid = tempFolder.newFile( "valid" );
+        Properties value = new Properties();
+        value.setProperty( "a", "b" );
+        try ( OutputStream out = new FileOutputStream( valid ) )
         {
-            File valid = tempFolder.newFile( "valid" );
-            Properties value = new Properties();
-            value.setProperty( "a", "b" );
-            out = new FileOutputStream( valid );
             value.store( out, "a test" );
-            out.close();
-            out = null;
             assertThat( PropertyUtils.loadProperties( valid ), is( value ) );
             assertThat( PropertyUtils.loadOptionalProperties( valid ), is( value ) );
         }
-        finally
-        {
-            IOUtil.close( out );
-        }
     }
 
     @Test
     @NeedsTemporaryFolder
     @SuppressWarnings( "deprecation" )
     public void loadValidURL() throws IOException
     {
-        OutputStream out = null;
-        try
-        {
-            File valid = tempFolder.newFile( "valid" );
-            Properties value = new Properties();
-            value.setProperty( "a", "b" );
-            out = new FileOutputStream( valid );
-            value.store( out, "a test" );
-            out.close();
-            out = null;
-            assertThat( PropertyUtils.loadProperties( valid.toURI().toURL() ), is( value ) );
-            assertThat( PropertyUtils.loadOptionalProperties( valid.toURI().toURL() ), is( value ) );
-        }
-        finally
+        File valid = tempFolder.newFile( "valid" );
+        Properties value = new Properties();
+        value.setProperty( "a", "b" );
+        try ( OutputStream out = new FileOutputStream( valid ) )
         {
-            IOUtil.close( out );
+          value.store( out, "a test" );
+          assertThat( PropertyUtils.loadProperties( valid.toURI().toURL() ), is( value ) );
+          assertThat( PropertyUtils.loadOptionalProperties( valid.toURI().toURL() ), is( value ) );
         }
     }