org.norther.tammi.core.io
Interface PathFinder

All Known Implementing Classes:

DefaultPathFinder

public interface PathFinder

An interface to file path finders. The path finder maintains mappings between keys and folders. The finder searches for files with relative pathnames from the specified key folders in their definition order. The first one found is returned. If none is found, an abstract pathname to the first defined folder mapped to the specified key is returned.

A set of standard keys are defined as constants, but new ones can be freely added.

Author:

Ilkka Priha

Field Summary

static String	BINARY The binany folders key.
static String	CGI_BIN The cgi-bin folders key.
static String	CONFIG The config folders key.
static String	CONTEXT The context folders key.
static String	CSV_EXTENSION The CSV file extension.
static String	DATA The data folders key.
static String	DEFAULT_DATA_PROPERTY The system property for defining the default data folder.
static String	DEFAULT_LOGS_PROPERTY The system property for defining the default logs folder.
static String	DEFAULT_TEMP_PROPERTY The system property for defining the default temp folder.
static String	LIBRARY The library folders key.
static String	LICENSE The license folders key.
static String	LOGS The logs folders key.
static String	MEDIA The media folders key.
static String	PROPERTIES_EXTENSION The property file extension.
static String	RESOURCE The resource folders key.
static String	SCRIPT The script folders key.
static String	SECURITY The security folders key.
static String	START The start folders key.
static String	STOP The stop folders key.
static String	TEMP The temp folders key.
static String	TEMPLATE The template folders key.
static String	XML_EXTENSION The XML file extension.

Method Summary

void	addContextPath(int index, String path) Adds a context path to the specified index.
void	addContextPath(String path) Adds a context path if not already specified.
void	addFolderPath(String key, int index, String path) Adds a key folder path to the specified index.
void	addFolderPath(String key, String path) Adds a key folder path if not already specified.
void	clearContext() Clears all context paths.
void	clearFolder(String key) Clears a key folder.
void	clearFolders() Clears all key folders.
boolean	deleteFile(File file) Deletes a file or folder and its contents.
File	findFile(String path) Finds a file relative to the root folder.
File	findFile(String key, String path) Finds a file relative to a key folder.
File	findFile(String key, String path, Locale locale) Finds a localized file relative to a key folder.
File	findFile(String key, String path, Locale locale, String variant) Finds a localized file with an optional variant relative to a key folder.
OrderedSet	findFolders(String key) Finds all existing folders corresponding to the specified key by applying the context paths of this path finder.
URL	findResource(String path) Finds a root resource using a local class loader.
URL	findResource(String key, String path) Finds a key resource using a local class loader.
URL	findResource(String key, String path, Locale locale) Finds a localized key resource using a local class loader.
URL	findResource(String key, String path, Locale locale, String variant) Finds a localized key resource with an optional variant using a local class loader.
URL	findURL(String path) Finds a file relative to the root folder or a root resource using a local class loader.
URL	findURL(String key, String path) Finds a file relative to a key folder or a key resource using a local class loader.
URL	findURL(String key, String path, Locale locale) Finds a localized file relative to a key folder or a localized key resource using a local class loader.
URL	findURL(String key, String path, Locale locale, String variant) Finds a localized file relative to a key folder or a localized key resource, with an optional variant, using a local class loader.
Set	folderKeySet() Returns a read-only set of specified folder keys.
ClassLoader	getContextClassLoader() Gets a context class loader loading resources from context paths of this path finder.
String[]	getContextPaths() Gets the context paths.
String[]	getFolderPaths(String key) Gets the specified key folder paths.
File	getRootFolder() Gets the root folder.
String	getRootPath() Gets the root path.
File	getSystemFolder() Gets the operating system folder.
boolean	isNormalizedPaths() Checks whether requested paths are normalized before search to reject absolute search paths and references outside context paths folders.
void	removeContextPath(String path) Removes a context path.
void	removeFolderPath(String key, String path) Removes a key folder path.
void	setContextPaths(String[] paths) Sets the context paths..
void	setFolderPaths(String key, String[] paths) Sets the specified key folder paths.
void	setNormalizedPaths(boolean flag) Sets whether requested paths are normalized before search to reject absolute search paths and references outside context paths folders.
void	setRootPath(String path) Sets the root path.
URL	toURL(String path) Converts a URL path, local path or jar path relative to the root folder to a URL instance.
URL	toURL(String key, String path) Converts a URL path, local path or jar path relative to the key folder to a URL instance.

Field Detail

CONTEXT

static final String CONTEXT

The context folders key.

See Also:

Constant Field Values

BINARY

static final String BINARY

The binany folders key.

See Also:

Constant Field Values

LIBRARY

static final String LIBRARY

The library folders key.

See Also:

Constant Field Values

LICENSE

static final String LICENSE

The license folders key.

See Also:

Constant Field Values

MEDIA

static final String MEDIA

The media folders key.

See Also:

Constant Field Values

CGI_BIN

static final String CGI_BIN

The cgi-bin folders key.

See Also:

Constant Field Values

RESOURCE

static final String RESOURCE

The resource folders key.

See Also:

Constant Field Values

TEMPLATE

static final String TEMPLATE

The template folders key.

See Also:

Constant Field Values

DATA

static final String DATA

The data folders key.

See Also:

Constant Field Values

TEMP

static final String TEMP

The temp folders key.

See Also:

Constant Field Values

LOGS

static final String LOGS

The logs folders key.

See Also:

Constant Field Values

START

static final String START

The start folders key.

See Also:

Constant Field Values

STOP

static final String STOP

The stop folders key.

See Also:

Constant Field Values

SCRIPT

static final String SCRIPT

The script folders key.

See Also:

Constant Field Values

CONFIG

static final String CONFIG

The config folders key.

See Also:

Constant Field Values

SECURITY

static final String SECURITY

The security folders key.

See Also:

Constant Field Values

XML_EXTENSION

static final String XML_EXTENSION

The XML file extension.

See Also:

Constant Field Values

CSV_EXTENSION

static final String CSV_EXTENSION

The CSV file extension.

See Also:

Constant Field Values

PROPERTIES_EXTENSION

static final String PROPERTIES_EXTENSION

The property file extension.

See Also:

Constant Field Values

DEFAULT_DATA_PROPERTY

static final String DEFAULT_DATA_PROPERTY

The system property for defining the default data folder.

See Also:

Constant Field Values

DEFAULT_TEMP_PROPERTY

static final String DEFAULT_TEMP_PROPERTY

The system property for defining the default temp folder.

See Also:

Constant Field Values

DEFAULT_LOGS_PROPERTY

static final String DEFAULT_LOGS_PROPERTY

The system property for defining the default logs folder.

See Also:

Constant Field Values

Method Detail

isNormalizedPaths

boolean isNormalizedPaths()

Checks whether requested paths are normalized before search to reject absolute search paths and references outside context paths folders.

Returns:

true if normalized, false otherwise.

setNormalizedPaths

void setNormalizedPaths(boolean flag)

Sets whether requested paths are normalized before search to reject absolute search paths and references outside context paths folders.

Parameters:

flag - true if normalized, false otherwise.

getRootFolder

File getRootFolder()

Gets the root folder.

Returns:

the root folder.

getRootPath

String getRootPath()

Gets the root path. The path of the root folder is the first context path of this path finder.

Returns:

the root path.

setRootPath

void setRootPath(String path)

Sets the root path. The path of the root folder is the first context path of this path finder. If the specified path already exists among context paths, it is moved to be the first one in the list, otherwise the first context path is replaced with the specified path.

Parameters:

path - the root path.

getContextPaths

String[] getContextPaths()

Gets the context paths.

Returns:

an array of context paths.

setContextPaths

void setContextPaths(String[] paths)

Sets the context paths..

Parameters:

paths - an array of context paths.

addContextPath

void addContextPath(String path)

Adds a context path if not already specified.

Parameters:

path - the context path.

addContextPath

void addContextPath(int index,
                    String path)

Adds a context path to the specified index.

Parameters:

index - the path index.

path - the context path.

removeContextPath

void removeContextPath(String path)

Removes a context path.

Parameters:

path - the context path.

clearContext

void clearContext()

Clears all context paths.

getFolderPaths

String[] getFolderPaths(String key)

Gets the specified key folder paths.

Parameters:

key - the folder key.

Returns:

an array of key folder paths.

setFolderPaths

void setFolderPaths(String key,
                    String[] paths)

Sets the specified key folder paths.

Parameters:

key - the folder key.

paths - an array of key folder paths.

addFolderPath

void addFolderPath(String key,
                   String path)

Adds a key folder path if not already specified.

Parameters:

key - the folder key.

path - the key folder path.

addFolderPath

void addFolderPath(String key,
                   int index,
                   String path)

Adds a key folder path to the specified index.

Parameters:

key - the folder key.

index - the path index.

path - the key folder path.

removeFolderPath

void removeFolderPath(String key,
                      String path)

Removes a key folder path.

Parameters:

key - the folder key.

path - the key folder path.

clearFolder

void clearFolder(String key)

Clears a key folder.

Parameters:

key - the folder key.

clearFolders

void clearFolders()

Clears all key folders.

folderKeySet

Set folderKeySet()

Returns a read-only set of specified folder keys.

Returns:

a set of keys or an empty set.

deleteFile

boolean deleteFile(File file)

Deletes a file or folder and its contents.

Parameters:

file - the file to delete.

Returns:

true if successful, false otherwise.

findFolders

OrderedSet findFolders(String key)

Finds all existing folders corresponding to the specified key by applying the context paths of this path finder.

Parameters:

key - a folder key.

Returns:

folders as a set of java.io.File instances.

findURL

URL findURL(String path)

Finds a file relative to the root folder or a root resource using a local class loader.

Parameters:

path - a path to find.

Returns:

the found file or resource as a URL or null.

findURL

URL findURL(String key,
            String path)

Finds a file relative to a key folder or a key resource using a local class loader.

Parameters:

key - a folder key or null for the root.

path - a path to find.

Returns:

the found file or resource as a URL or null.

findURL

URL findURL(String key,
            String path,
            Locale locale)

Finds a localized file relative to a key folder or a localized key resource using a local class loader. A file having the given locale, or any part of it, embedded into its name is searched for.

Parameters:

key - a folder key or null for the root.

path - a path to find.

locale - the locale of the path.

Returns:

the found file or resource as a URL or null.

findURL

URL findURL(String key,
            String path,
            Locale locale,
            String variant)

Finds a localized file relative to a key folder or a localized key resource, with an optional variant, using a local class loader. A file having the given locale, or any part of it, embedded into its name is searched for. If the variant is not null, it replaces any variants in the locale.

Parameters:

key - a folder key or null for the root.

path - a path to find.

locale - the locale of the path.

variant - a variant to the locale.

Returns:

the found file or resource as a URL or null.

findFile

File findFile(String path)

Finds a file relative to the root folder.

Parameters:

path - a path to find.

Returns:

the found file.

findFile

File findFile(String key,
              String path)

Finds a file relative to a key folder.

Parameters:

key - a folder key or null for the root.

path - a path to find.

Returns:

the found file.

findFile

File findFile(String key,
              String path,
              Locale locale)

Finds a localized file relative to a key folder. A file having the given locale, or any part of it, embedded into its name is searched for.

Parameters:

key - a folder key or null for the root.

path - a path to find.

locale - the locale of the path.

Returns:

the found file.

findFile

File findFile(String key,
              String path,
              Locale locale,
              String variant)

Finds a localized file with an optional variant relative to a key folder. A file having the given locale, or any part of it, embedded into its name is searched for. If the variant is not null, it replaces any variants in the locale.

Parameters:

key - a folder key or null for the root.

path - a path to find.

locale - the locale of the path.

variant - a variant to the locale.

Returns:

the found file.

findResource

URL findResource(String path)

Finds a root resource using a local class loader.

Parameters:

path - a path to find.

Returns:

the found URL or null.

findResource

URL findResource(String key,
                 String path)

Finds a key resource using a local class loader.

Parameters:

key - a folder key or null for the root.

path - a path to find.

Returns:

the found URL or null.

findResource

URL findResource(String key,
                 String path,
                 Locale locale)

Finds a localized key resource using a local class loader. A resource having the given locale, or any part of it, embedded into its name is searched for.

Parameters:

key - a folder key or null for the root.

path - a path to find.

locale - the locale of the path.

Returns:

the found URL or null.

findResource

URL findResource(String key,
                 String path,
                 Locale locale,
                 String variant)

Finds a localized key resource with an optional variant using a local class loader. A resource having the given locale, or any part of it, embedded into its name is searched for. If the variant is not null, it replaces any variants in the locale.

Parameters:

key - a folder key or null for the root.

path - a path to find.

locale - the locale of the path.

variant - a variant to the locale.

Returns:

the found URL or null.

toURL

URL toURL(String path)
          throws MalformedURLException

Converts a URL path, local path or jar path relative to the root folder to a URL instance. The path must specify the protocol to apply (file:, jar:file:, etc).

Parameters:

path - a path to find.

Returns:

the URL or null.

Throws:

MalformedURLException - for an invalid URL path.

toURL

URL toURL(String key,
          String path)
          throws MalformedURLException

Converts a URL path, local path or jar path relative to the key folder to a URL instance. The path must specify the protocol to apply (file:, jar:file:, etc).

Parameters:

key - a folder key.

path - a path to find.

Returns:

the URL or null.

Throws:

MalformedURLException - for an invalid URL path.

getContextClassLoader

ClassLoader getContextClassLoader()

Gets a context class loader loading resources from context paths of this path finder.

Returns:

the context class loader.

getSystemFolder

File getSystemFolder()

Gets the operating system folder.

Returns:

the operating system folder.