Interface Locator

  • All Known Implementing Classes:
    AbstractLocator, AbstractStreamLocator, ByteArrayLocator, ClassPathLocator, FileLocator, LocatorWrapper, URLLocator

    public interface Locator

    Definition of the base Locator interface.

    A Locator is an object that points to a resource to be loaded by an application. There are many ways how such a resource can be specified, including

    • plain strings representing file paths or URLs
    • File objects
    • URL objects
    and lots of more.

    Typically to be fully compatible with all kinds of clients and to be convenient to use a service class that needs to load resources has to deal with all these various ways. As an implementor of such services classes you find yourself often writing similar code for converting Files to URLs, strings to both or vice versa.

    To make the handling of resources easier the Locator interface was introduced. A Locator provides an abstract view on a resource specification. Concrete implementations will deal with specific ways of describing resources, e.g. as URLs or files or loaded from the class path. So a service class need not deal with conversion between the different formats any longer, but just queries the provided locator.

    The Locator interface defines some methods for returning a pointer to the represented resource, but the only method that must be implemented is the getURL() method. So URLs are the native format. If a stream to the represented resource is to be opened, this task should be delegated to the LocatorUtils class, which contains static utility methods for exactly this purpose. These methods will test, which of the locator's methods return defined values and then use those to open the stream.

    Version:
    $Id: Locator.java 205 2012-01-29 18:29:57Z oheger $
    Author:
    Oliver Heger
    • Method Detail

      • getURL

        URL getURL()
        Returns a URL to the resource represented by this locator. This method must return a non null value.
        Returns:
        a URL for the represented resource
        Throws:
        LocatorException - if an internal error occurs while determining the URL
      • getFile

        File getFile()
        Returns a file for the resource represented by this locator. This is an optional method that can return null if a file makes no sense for the represented resource.
        Returns:
        a File object for the represented resource
        Throws:
        LocatorException - if an internal error occurs
      • getInputStream

        InputStream getInputStream()
                            throws IOException
        Returns an input stream for the represented resource. This method is called first when a stream to the locator is to be obtained. It is an optional method that can return null. In this case the getFile() and, last but not least, the getURL() methods will be tried.
        Returns:
        an input stream to the represented resource
        Throws:
        LocatorException - if an internal error occurs
        IOException - if an IO error occurs when opening the stream