Module imagingbook.core
Package imagingbook.core.resource

Interface NamedResource

All Known Subinterfaces:
ImageResource
public interface NamedResource

This interface is supposed to be implemented by some enum class that specifies the root of a resource tree. The following example defines such an enum type that refers to three images. The path relative to the location of the enum class itself must be specified and images must be stored there. The enum type must define an appropriate constructor and implement method getFileName(): 

 public enum MyImages implements NamedResource {
        image1("image1.tif"),
        image2("image2.png"),
        image3("jpegs/image3.jpg");
        // field to associate the resource's file name
        private final String filename;
        @Override
        public String getFileName() {
                return filename;
    }
        // constructor
        MyImages(String filename) {
                this.filename = filename;
    }
 }

By default, resource files are assumed to be placed in a folder with the same name as the resource class (i.e., "MyImages") relative to the location of the class. Resources may then be simply referenced by their enum-name, for example, 

 URL url = MyImages.image1.getURL();
 ImagePlus im = IJ.openImage(url.toString());

The benefit of using a named resource (over specifying resources by path strings) is that the resource is guaranteed to exist at compile time (this is assured by validating the existence of all named resources in the test phase) and can be retrieved even if located inside a JAR file. Also, everything is defined in a single place and renaming a resource is easy.

Version:
2022/08/23
See Also:

  • Field Details

    • RelativeDirectorySuffix

      static final String RelativeDirectorySuffix
      Specifies the name of the resource directory relative to some resource class. For example, given some resource class in 
      src/main/java/.../foo/ZeClass.java
      the associated resource files are assumed to be in directory 
      src/main/resources/.../foo/ZeClass-data/
      See Also:

  • Method Details

    • getRelativeDirectory

      default String getRelativeDirectory()
      Returns the resource directory relative to the implementing class. The default implementations assumes that this is a single-level directory with exactly the same name as the implementing class, extended by RelativeDirectorySuffix ("-data"). Implementations may override this definition to return some other relative directory. Note that the directory should not have a legal Java package name to avoid confusion in the build process (e.g., by javadoc).
      Returns:
      the relative resource directory for the associated resource

    • getRelativeDirectory

      static String getRelativeDirectory(Class<? extends NamedResource> clazz)

    • getRelativePath

      default String getRelativePath()
      Returns the path to the associated resource relative to the location of the implementing class. This method is not supposed to be overridden.
      Returns:
      the relative path to the associated resource

    • getFileName

      String getFileName()
      Returns the file name for the associated resource (to be implemented by concrete classes).
      Returns:
      the name of the resource file

    • getURL

      default URL getURL()
      Returns the URL to the associated resource. This method is not supposed to be overridden. Throws an exception if the requested resource does not exist.
      Returns:
      the URL to the associated resource

    • isInsideJar

      default boolean isInsideJar()
      Returns true if the associated resource (class) was loaded from a JAR file.
      Returns:
      true if inside a JAR file

    • getStream

      default InputStream getStream()
      Returns an InputStream for reading from this resource. See also Class.getResourceAsStream(String). This method is not supposed to be overridden.
      Returns:
      an InputStream for the associated resource

    • getResourceFileNames

      static String[] getResourceFileNames(Class<? extends NamedResource> clazz)
      Returns the names of the actual files contained in the associated resource directory of the specified class, which must implement the NamedResource interface. This can be used to check if a given named resource has a matching file in a case-sensitive way.
      Parameters:
      clazz - the resource class
      Returns:
      an array of strings