net.sf.jguiraffe.locators

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 Summary

Modifier and Type	Method and Description
File	getFile() Returns a file for the resource represented by this locator.
InputStream	getInputStream() Returns an input stream for the represented resource.
URL	getURL() Returns a URL to the resource represented by this locator.

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