PIRL.Utilities

## Class File

- java.lang.Object
- - java.io.File
  - - PIRL.Utilities.File

All Implemented Interfaces:
  Serializable, Comparable<File>

    public class File
    extends File

This File extends the capabilities of the JFC `File` to enable mapping the File's canonical path to a logical path. The mappings are defined by a `pathnames map` obtained from a Configuration.

See Also:
  `File`, `Configuration`, Serialized Form

### Field Summary

Fields
`static String` `DEFAULT_CONFIGURATION_FILENAME` Default configuration file name: "Pathname.conf".
`static int` `EXIT_CONFIGURATION_PROBLEM` Exit Status: A Configuration problem was encountered.
`static int` `EXIT_INVALID_COMMAND_LINE_SYNTAX` Exit Status: Invalid command line syntax.
`static int` `EXIT_IO_ERROR` Exit Status: An IO Error occured.
`static int` `EXIT_SUCCESS` Exit Status: Success.
`static String` `ID` Class name and version identification.
`static String` `PATHNAMES_MAP_GROUP` The Parameter Group in the Configuration containing the logical pathname map.

### Fields inherited from class java.io.File

`pathSeparator, pathSeparatorChar, separator, separatorChar`

### Constructor Summary

Constructors
Constructor and Description
`File(File parent, String child)` Construct a File a directory File and a filename String.
`File(String pathname)` Construct a File from a String.
`File(String parent, String child)` Construct a File from directory and filename Strings.
`File(URI uri)` Construct a File from a URI.

### Method Summary

Methods
`String` `Logical_Path()` Get the logical path for the file.
`static void` `main(String[] arguments)` Map filenames to their logical forms.
`Configuration` `Pathnames_Map()` Get the current pathnames map.
`File` `Pathnames_Map(Configuration configuration)` Set the pathnames map to be used for mapping canonical paths to logical paths.
`File` `Pathnames_Map(String source)` Set the pathnames map from a configuration file source.
`static void` `Usage()` Prints the command line usage syntax.

### Methods inherited from class java.io.File

`canExecute, canRead, canWrite, compareTo, createNewFile, createTempFile, createTempFile, delete, deleteOnExit, equals, exists, getAbsoluteFile, getAbsolutePath, getCanonicalFile, getCanonicalPath, getFreeSpace, getName, getParent, getParentFile, getPath, getTotalSpace, getUsableSpace, hashCode, isAbsolute, isDirectory, isFile, isHidden, lastModified, length, list, list, listFiles, listFiles, listFiles, listRoots, mkdir, mkdirs, renameTo, setExecutable, setExecutable, setLastModified, setReadable, setReadable, setReadOnly, setWritable, setWritable, toPath, toString, toURI, toURL`

### Methods inherited from class java.lang.Object

`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

### Field Detail

#### ID

    public static final String ID

Class name and version identification.

See Also:
  Constant Field Values

#### DEFAULT_CONFIGURATION_FILENAME

    public static final String DEFAULT_CONFIGURATION_FILENAME

Default configuration file name: "Pathname.conf".

See Also:
  Constant Field Values

#### PATHNAMES_MAP_GROUP

    public static final String PATHNAMES_MAP_GROUP

The Parameter Group in the Configuration containing the logical pathname map.

See Also:
  Constant Field Values

#### EXIT_SUCCESS

    public static final int EXIT_SUCCESS

Exit Status: Success.

See Also:
  Constant Field Values

#### EXIT_INVALID_COMMAND_LINE_SYNTAX

    public static final int EXIT_INVALID_COMMAND_LINE_SYNTAX

Exit Status: Invalid command line syntax.

See Also:
  Constant Field Values

#### EXIT_CONFIGURATION_PROBLEM

    public static final int EXIT_CONFIGURATION_PROBLEM

Exit Status: A Configuration problem was encountered.

See Also:
  Constant Field Values

#### EXIT_IO_ERROR

    public static final int EXIT_IO_ERROR

Exit Status: An IO Error occured.

See Also:
  Constant Field Values

### Constructor Detail

#### File

    public File(String pathname)

Construct a File from a String.

Parameters:
  `pathname` - A pathname String.
See Also:
  `File`

#### File

    public File(String parent,
        String child)

Construct a File from directory and filename Strings.

Parameters:
  `parent` - A directory pathname String.
  `child` - A filename String for a file in the parent directory.
See Also:
  `File`

#### File

    public File(File parent,
        String child)

Construct a File a directory File and a filename String.

Parameters:
  `parent` - A directory File.
  `child` - A filename String for a file in the parent directory.
See Also:
  `File`

#### File

    public File(URI uri)

Construct a File from a URI.

Parameters:
  `uri` - A URI.
See Also:
  `URI`

### Method Detail

#### Pathnames_Map

    public File Pathnames_Map(Configuration configuration)
                       throws Configuration_Exception

Set the pathnames map to be used for mapping canonical paths to logical paths.

The canonical to logical pathname mappings are defined by a `PATHNAMES_MAP_GROUP` group of Assignment Parameters of the form:

> <canonical segment> = <logical segment>

The cononical segment is any substring of a pathname that might be returned by the `File.getCanonicalPath()` method. The logical segment replaces the canonical segment wherever it occurs in the pathname to produce the `Logical_Path()` of the File. Initially the logical path is identical to the canonical path, then all mapping parameters are applied in the order they occur in the group. Thus a matching canonical segment may have been produced, in whole or in part, by a preceeding canonical to logical segment mapping replacement.

If the configuration argument is null an attempt will be made to load a Configuration from the `DEFAULT_CONFIGURATION_FILENAME` file. If this file can not be accessed a default Configuration is provided. N.B.: This behaviour is different than the `Pathnames_Map(String)` method which will throw a Configuration_Exception if the source file can not be accessed.

If the configuration is named `PATHNAMES_MAP_GROUP` then a copy of the entire configuration is used as the pathnames map. Otherwise the configuration searched for a Parameter Group with that name which is copied. If no `PATHNAMES_MAP_GROUP` is found then an empty pathnames map is provided; no canonical to logical pathname mapping will be done in this case.

Any `default` Configuration parameters are removed from the pathnames map as well as any Parameters that are a Group or have an Array, or no, Value.

Parameters:
  `configuration` - A Configuration to use as the source of the pathnames map.
Returns:
  This File.
Throws:
  `Configuration_Exception` - If there was a problem obtaining the `PATHNAMES_MAP_GROUP` from the map or reading the `DEFAULT_CONFIGURATION_FILENAME`.

#### Pathnames_Map

    public File Pathnames_Map(String source)
                       throws Configuration_Exception

Set the pathnames map from a configuration file source.

Parameters:
  `source` - The source of a configuration file. This may be a local filename, a URL, or a jar file resource name.
Returns:
  This File.
Throws:
  `Configuration_Exception` - If the source file could not be accessed (not found or no permission to read) or there was a problem constructing a Configuration from the source contents.
See Also:
  `Pathnames_Map(Configuration)`

#### Pathnames_Map

    public Configuration Pathnames_Map()

Get the current pathnames map.

Returns:
  A Configuration containing the current pathnames map parameters. This may be null if no map has yet been assigned.

#### Logical_Path

    public String Logical_Path()
                        throws IOException,
                               Configuration_Exception

Get the logical path for the file.

The logical path is based on the File's `canonical path` with the cononical segments listed in thepathnames map replaced with the logical segments to which they are assigned.

N.B.</b.: If a pathnames map has not yet been bound to this File, a default map will be provided. <p>

Returns:
  The logical path String.
Throws:
  `Configuration_Exception` - If a default pathnames map was needed but the source file could not be accessed (not found or no permission to read) or there was a problem constructing a Configuration from the source contents.
  `IOException` - If the @link java.io.File#getCanonicalPath() canonical path of the File could not be obtained.
See Also:
  `Pathnames_Map(Configuration)`, `Pathnames_Map(String)`

#### main

    public static void main(String[] arguments)

Map filenames to their logical forms.

The command line syntax is described by the `Usage` method.

Each filename specified will be listed along with its canonical path and mapped logical path.

Exit Status Values

0 - Success
1 - Command line syntax problem
2 - A Configuration problem was encountered
3 - An IO Error occured

Parameters:
  `arguments` - Array of command line argument Strings.
See Also:
  `Usage()`

#### Usage

    public static void Usage()

Prints the command line usage syntax.

>     Usage: File <Options> <filename> [...]
>       Options -
>         [-Configuration <filename>
>           (default: Pathnames_Map.conf)
>         [-Help]