Allow customized locale paths.

- LocaleHandler is a new interface for transforming a default path
  to a localized one.
- setLocalePrefix() continues to work as before.
- getLocalePrefix() has been removed. Is it really needed?
- In methods that try retrieving a resource from several bundles,
  just transform the path into a locale-specific one once.
- I want to use the @Nullable annotation all over the place.

src/main/java/com/threerings/resource/ResourceManager.java

@@ -163,6 +163,20 @@ public class ResourceManager
         public void resourceModified (String path, long lastModified);
     }
 
+    /**
+     * Transforms a regular resource path into a locale-specific path. The returned path
+     * does not need to represent a valid resource. The ResourceManager will attempt to use
+     * the locale-specific path, but if it fails will fall back to the generic path.
+     */
+    public interface LocaleHandler
+    {
+        /**
+         * Return a locale-specific path, or null if the specified path cannot or need not
+         * be transformed.
+         */
+        String getLocalePath (String path);
+    }
+
     /**
      * Constructs a resource manager which will load resources via the classloader, prepending
      * <code>resourceRoot</code> to their path.
@@ -241,19 +255,24 @@ public class ResourceManager
     }
 
     /**
-     * Returns where we're currently looking for locale-specific resources.
+     * Configure a default LocaleHandler with the specified prefix.
      */
-    public String getLocalePrefix ()
+    public void setLocalePrefix (final String prefix)
     {
-        return _localePrefix;
+        setLocaleHandler(
+            new LocaleHandler() {
+                public String getLocalePath (String path) {
+                    return PathUtil.appendPath(prefix, path);
+                }
+            });
     }
 
     /**
-     * Set where we should look for locale-specific resources.
+     * Configure a custom LocaleHandler.
      */
-    public void setLocalePrefix (String prefix)
+    public void setLocaleHandler (LocaleHandler localeHandler)
     {
-        _localePrefix = prefix;
+        _localeHandler = localeHandler;
     }
 
     /**
@@ -394,8 +413,9 @@ public class ResourceManager
             path = path.replace("/", File.separator);
         }
         // first try a locale-specific file
-        if (_localePrefix != null) {
+        String localePath = getLocalePath(path);
-            File file = new File(_rdir, PathUtil.appendPath(_localePrefix, path));
+        if (localePath != null) {
+            File file = new File(_rdir, localePath);
             if (file.exists()) {
                 return file;
             }
@@ -515,18 +535,20 @@ public class ResourceManager
     public InputStream getResource (String path)
         throws IOException
     {
-        InputStream in = null;
+        String localePath = getLocalePath(path);
+        InputStream in;
 
         // first look for this resource in our default resource bundle
         for (ResourceBundle bundle : _default) {
             // Try a localized version first.
-            if (_localePrefix != null) {
+            if (localePath != null) {
-                in = bundle.getResource(PathUtil.appendPath(_localePrefix, path));
+                in = bundle.getResource(localePath);
+                if (in != null) {
+                    return in;
+                }
             }
             // If that didn't work, try generic.
-            if (in == null) {
+            in = bundle.getResource(path);
-                in = bundle.getResource(path);
-            }
             if (in != null) {
                 return in;
             }
@@ -539,9 +561,8 @@ public class ResourceManager
         }
 
         // if we still didn't find anything, try the classloader; first try a locale-specific file
-        if (_localePrefix != null) {
+        if (localePath != null) {
-            String rpath = PathUtil.appendPath(_rootPath, PathUtil.appendPath(_localePrefix, path));
+            in = getInputStreamFromClasspath(PathUtil.appendPath(_rootPath, localePath));
-            in = getInputStreamFromClasspath(rpath);
             if (in != null) {
                 return in;
             }
@@ -567,19 +588,20 @@ public class ResourceManager
     public BufferedImage getImageResource (String path)
         throws IOException
     {
+        String localePath = getLocalePath(path);
+
         // first look for this resource in our default resource bundle
         for (ResourceBundle bundle : _default) {
             // try a localized version first
-            BufferedImage image = null;
+            BufferedImage image;
-            if (_localePrefix != null) {
+            if (localePath != null) {
-                image = bundle.getImageResource(PathUtil.appendPath(_localePrefix, path), false);
+                image = bundle.getImageResource(localePath, false);
+                if (image != null) {
+                    return image;
+                }
             }
-
             // if we didn't find that, try generic
-            if (image == null) {
+            image = bundle.getImageResource(path, false);
-                image = bundle.getImageResource(path, false);
-            }
-
             if (image != null) {
                 return image;
             }
@@ -591,17 +613,15 @@ public class ResourceManager
             return loadImage(file, path.endsWith(FastImageIO.FILE_SUFFIX));
         }
 
-        // first try a locale-specific file
+        // if we still didn't find anything, try the classloader
-        if (_localePrefix != null) {
+        InputStream in;
-            String rpath = PathUtil.appendPath(_rootPath, PathUtil.appendPath(_localePrefix, path));
+        if (localePath != null) {
-            InputStream in = getInputStreamFromClasspath(rpath);
+            in = getInputStreamFromClasspath(PathUtil.appendPath(_rootPath, localePath));
             if (in != null) {
                 return loadImage(in);
             }
         }
-
+        in = getInputStreamFromClasspath(PathUtil.appendPath(_rootPath, path));
-        // if we still didn't find anything, try the classloader
-        InputStream in = getInputStreamFromClasspath(PathUtil.appendPath(_rootPath, path));
         if (in != null) {
             return loadImage(in);
         }
@@ -630,24 +650,21 @@ public class ResourceManager
                 "Unable to locate resource [set=" + rset + ", path=" + path + "]");
         }
 
+        String localePath = getLocalePath(path);
         // look for the resource in any of the bundles
-        int size = bundles.length;
+        for (ResourceBundle bundle : bundles) {
-        for (int ii = 0; ii < size; ii++) {
+            InputStream in;
-            InputStream instr = null;
-
             // Try a localized version first.
-            if (_localePrefix != null) {
+            if (localePath != null) {
-                instr = bundles[ii].getResource(PathUtil.appendPath(_localePrefix, path));
+                in = bundle.getResource(localePath);
+                if (in != null) {
+                    return in;
+                }
             }
             // If we didn't find that, try a generic.
-            if (instr == null) {
+            in = bundle.getResource(path);
-                instr = bundles[ii].getResource(path);
+            if (in != null) {
-            }
+                return in;
-            if (instr != null) {
-//                 Log.info("Found resource [rset=" + rset +
-//                          ", bundle=" + bundles[ii].getSource().getPath() +
-//                          ", path=" + path + ", in=" + instr + "].");
-                return instr;
             }
         }
 
@@ -672,30 +689,26 @@ public class ResourceManager
                 "Unable to locate image resource [set=" + rset + ", path=" + path + "]");
         }
 
+        String localePath = getLocalePath(path);
         // look for the resource in any of the bundles
-        int size = bundles.length;
+        for (ResourceBundle bundle : bundles) {
-        for (int ii = 0; ii < size; ii++) {
+            BufferedImage image;
-            BufferedImage image = null;
             // try a localized version first
-            if (_localePrefix != null) {
+            if (localePath != null) {
-                image =
+                image = bundle.getImageResource(localePath, false);
-                    bundles[ii].getImageResource(PathUtil.appendPath(_localePrefix, path), false);
+                if (image != null) {
+                    return image;
+                }
             }
-
             // if we didn't find that, try generic
-            if (image == null) {
+            image = bundle.getImageResource(path, false);
-                image = bundles[ii].getImageResource(path, false);
-            }
-
             if (image != null) {
-//                 Log.info("Found image resource [rset=" + rset +
-//                          ", bundle=" + bundles[ii].getSource() + ", path=" + path + "].");
                 return image;
             }
         }
 
-        String errmsg = "Unable to locate image resource [set=" + rset + ", path=" + path + "]";
+        throw new FileNotFoundException(
-        throw new FileNotFoundException(errmsg);
+            "Unable to locate image resource [set=" + rset + ", path=" + path + "]");
     }
 
     /**
@@ -842,6 +855,14 @@ public class ResourceManager
         return new NetworkResourceBundle(root, path, rsrcList);
     }
 
+    /**
+     * Transform the path into a locale-specific one, or return null.
+     */
+    protected String getLocalePath (String path)
+    {
+        return (_localeHandler == null) ? null : _localeHandler.getLocalePath(path);
+    }
+
     /**
      * Loads an image from the supplied file. Supports {@link FastImageIO} files and formats
      * supported by {@link ImageIO} and will load the appropriate one based on the useFastIO param.
@@ -1075,8 +1096,8 @@ public class ResourceManager
     /** A table of our resource sets. */
     protected HashMap<String, ResourceBundle[]> _sets = Maps.newHashMap();
 
-    /** Locale to search for locale-specific resources, if any. */
+    /** Converts a path to a locale-specific path. */
-    protected String _localePrefix = null;
+    protected LocaleHandler _localeHandler;
 
     /** Maps resource paths to observed file resources. */
     protected HashMap<String, ObservedResource> _observed = Maps.newHashMap();