svn commit: r1524819 - in /commons/proper/configuration/trunk/src: main/java/org/apache/commons/configuration/io/FileLocatorUtils.java test/java/org/apache/commons/configuration/io/TestFileLocatorUtils.java

[oh...@apache.org]

Author: oheger
Date: Thu Sep 19 20:16:25 2013
New Revision: 1524819

URL: http://svn.apache.org/r1524819
Log:
Added a method for checking whether a locator is fully initialized.

Because the way a file is referenced by a FileLocator can make a difference
when the file is actually accessed it makes sense to have a method which checks
this. This helps client code to decide whether fullyInitializedLocator()
needs to be called. FileHandler also needs this information to provide
functionality to initialize its FileLocator on demand.

Modified:
    commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/io/FileLocatorUtils.java
    commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/io/TestFileLocatorUtils.java

Modified: commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/io/FileLocatorUtils.java
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/io/FileLocatorUtils.java?rev=1524819&r1=1524818&r2=1524819&view=diff
==============================================================================
--- commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/io/FileLocatorUtils.java (original)
+++ commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/io/FileLocatorUtils.java Thu Sep 19 20:16:25 2013
@@ -150,6 +150,35 @@ public final class FileLocatorUtils
     }
 
     /**
+     * Returns a flag whether all components of the given {@code FileLocator}
+     * describing the referenced file are defined. In order to reference a file,
+     * it is not necessary that all components are filled in (for instance, the
+     * URL alone is sufficient). For some use cases however, it might be of
+     * interest to have different methods for accessing the referenced file.
+     * Also, depending on the filled out properties, there is a subtle
+     * difference how the file is accessed: If only the file name is set (and
+     * optionally the base path), each time the file is accessed a
+     * {@code locate()} operation has to be performed to uniquely identify the
+     * file. If however the URL is determined once based on the other components
+     * and stored in a fully defined {@code FileLocator}, it can be used
+     * directly to identify the file. If the passed in {@code FileLocator} is
+     * <b>null</b>, result is <b>false</b>.
+     *
+     * @param locator the {@code FileLocator} to be checked (may be <b>null</b>)
+     * @return a flag whether all components describing the referenced file are
+     *         initialized
+     */
+    public static boolean isFullyInitialized(FileLocator locator)
+    {
+        if (locator == null)
+        {
+            return false;
+        }
+        return locator.getBasePath() != null && locator.getFileName() != null
+                && locator.getSourceURL() != null;
+    }
+
+    /**
      * Returns a {@code FileLocator} object based on the passed in one whose
      * location is fully defined. This method ensures that all components of the
      * {@code FileLocator} pointing to the file are set in a consistent way. In
@@ -179,8 +208,7 @@ public final class FileLocatorUtils
             return null;
         }
 
-        if (locator.getBasePath() != null && locator.getFileName() != null
-                && locator.getSourceURL() != null)
+        if (isFullyInitialized(locator))
         {
             // already fully initialized
             return locator;

Modified: commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/io/TestFileLocatorUtils.java
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/io/TestFileLocatorUtils.java?rev=1524819&r1=1524818&r2=1524819&view=diff
==============================================================================
--- commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/io/TestFileLocatorUtils.java (original)
+++ commons/proper/configuration/trunk/src/test/java/org/apache/commons/configuration/io/TestFileLocatorUtils.java Thu Sep 19 20:16:25 2013
@@ -514,4 +514,28 @@ public class TestFileLocatorUtils
         assertSame("Wrong result", locator,
                 FileLocatorUtils.fullyInitializedLocator(locator));
     }
+
+    /**
+     * Tests isFullyInitialized() for null input.
+     */
+    @Test
+    public void testIsFullyInitializedNull()
+    {
+        assertFalse("Wrong result", FileLocatorUtils.isFullyInitialized(null));
+    }
+
+    /**
+     * Tests whether a missing base path is detected when checking for a fully
+     * initialized locator.
+     */
+    @Test
+    public void testIsFullyInitializedNoBasePath()
+    {
+        FileLocator locator =
+                FileLocatorUtils.fileLocator()
+                        .sourceURL(ConfigurationAssert.getTestURL(FILE_NAME))
+                        .fileName(FILE_NAME).create();
+        assertFalse("Wrong result",
+                FileLocatorUtils.isFullyInitialized(locator));
+    }
 }