com.ccg.util
Class PathSearch

java.lang.Object
  com.ccg.util.PathSearch

public class PathSearch
extends Object

Search for file names through directories. This class is used to search for file names through a list of different directories. It is also designed to allow one to have path separator characters automatically translated to the platform specific form automatically. In other words, you could always specify a path like "/tmp/etc" and know that it would be translated to the proper form for the environment you are running under.

Version:

$Revision: 1.1.1.1 $

Author:

Paul Blankenbaker

Constructor Summary

PathSearch()
Default constructor for the PathSearch class.

PathSearch(boolean autoTranslate)
Minimal constructor for the PathSearch class.

Method Summary

int	addDirectories(String path) Add one or more directories to the search path.
boolean	addDirectory(String path) Add a additional directory to the search path.
File	getDirectory(int i) Retrieve a directory in the path list.
int	getDirectoryCount() Get the number of directories in the search path.
static PathSearch	getSystemPath() Try to look up the standard PATH for the Operating System.
static Enumeration	parsePathString(String path, boolean autoTranslate) Method to parse a PATH string into its components.
File	searchForFile(String name) Try to locate a file in the current search path.
String	toString() Return a PATH looking string of the current search areas.
static String	translatePath(String origPath) Adjust directory separation character for platform.
static String	translatePathList(String origPath) Adjust PATH type separation character for platform.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

PathSearch

public PathSearch()

Default constructor for the PathSearch class.

The following actions are done:

• Initializes the object to first search the current directory
• Initializes the object to automatically translate "/" and "\" separator characters to the platform specific form.

PathSearch

public PathSearch(boolean autoTranslate)

Minimal constructor for the PathSearch class.

Allows one to specify whether directory separator characters are automatically translated or not. In addition, the current directory will not automatically be added to the start of the search path.

Parameters:

boolean - Flag to enable or disable the automatic translation of the '/' and '\' characters to the platform specific format required. (I'd recommend setting it true).

Method Detail

getDirectoryCount

public int getDirectoryCount()

Get the number of directories in the search path.

Returns:

Number of directories in the search path.

Since:

1.0

See Also:

addDirectories(java.lang.String)

getDirectory

public File getDirectory(int i)

Retrieve a directory in the path list. This method allows one to retrieve the individual directories in the PATH list. You can retrieve them in the order that they are searched. A index of 0 is the first directory searched, then 1, and so on.

Parameters:

index - Index in the range of [0,getDirectoryCount()-1]

Returns:

File object for the next element in the directory search path. Or null, if the index is invalid.

Since:

1.0

See Also:

getDirectoryCount()

translatePath

public static String translatePath(String origPath)

Adjust directory separation character for platform. Function to change platform unspecific directory separator characters to the appropriate separator character for the platform. Currently only two possible directory separator characters are recognized, the forward slash '/' (as used by Unix type systems), and the backward slash '/' (as used by Windows, OS/2 type systems). All occurences of these characters will automatically be changed to the platform specific character (java.io.File.separatorChar).

 The following:

 java.util.PathSearch.translatePath("../opt\\java/test.java");

 Would yield: "../opt/java/test.java" on a Unix platform
 Would yield: "..\\opt\\java\\test.java" on a Windows, OS/2 platform
 

Parameters:

String - String containing the path which you want translated. All of the '/' and '\' characters contained will be translated to the appropriate character for the platform.

Returns:

Returns a String object corresponding to the original path list with subsitutions performed.

See Also:

addDirectories(java.lang.String), translatePathList(java.lang.String), File.separatorChar

translatePathList

public static String translatePathList(String origPath)

Adjust PATH type separation character for platform. Function to change platform unspecific directory and path separator characters to the appropriate separator character for the platform. Currently only two possible directory separator characters are recognized, the forward slash '/' (as used by Unix type systems), and the backward slash '/' (as used by Windows, OS/2 type systems). All occurences of these characters will automatically be changed to the platform specific character (java.io.File.separatorChar). In addition, there are two recognized possible path separator character, the colon ':' (on Unix systems), and the semi-colon ';' (on Windows, OS/2 systems). All occurences of these characters will be converted to the platform specific character, except in the case of drive designations (where the first character after the first letter is a colon). For example:

 The following:

 java.util.PathSearch("/opt/java:c:\\tmp;/root");

 Would yield: "/opt/java:c:/tmp:/root" on a Unix platform
 Would yield: "\\opt\\java;c:\\tmp;\\root" on a Windows, OS/2 platform
 

Parameters:

String - String containing the list of zero or more paths which you want translated to the platform form. All of the '/' and '\' characters contained will be translated to the appropriate character for the platform. And all of the ';' characters will be translated to the platform specific character used for displaying paths (unfortunately this can not be done for the ':' characters cleanly since some platforms use these characters in their file paths - so, these characters will be translated UNLESS there is another ':' exactly 2 characters prior in the string).

Returns:

Returns a String object corresponding to the original path list with subsitutions performed.

See Also:

addDirectories(java.lang.String), translatePath(java.lang.String)

parsePathString

public static Enumeration parsePathString(String path,
                                          boolean autoTranslate)

Method to parse a PATH string into its components. This method will take a PATH string like:

 "c:\windows;d:/opt/bin:o:/net/bin"
 

And parse out the individual directories as strings. For example, the above would come back on a windows system as 3 strings "c:\windows", "d:\opt\bin", and "o:\net\bin".

This is a static method (meaning that you don't need to create an object to use it). It has the following features:

• It can "fix" the path and directory name separator characters for you (that is force them to the proper form). This is done by setting the second parameter to true in which case the translatePathList(java.lang.String) method will be used.
• It does NOT verify that each directory exists. This is different than the addDirectory(java.lang.String) method which only adds directories which actually exist and are valid directories. This also means that you can use on abitrary strings (sometimes I use this method to parse a list of files).
• It returns an enumeration of String objects - its up to you to determine whether the object is actually a directory or not.

Most of the time, you will find using the addDirectories(java.lang.String) method suitable for these objects, however there are times when access to this method can be very handy.

Parameters:

path - A standard PATH list (its fairly platform independent, use ":" or ";" to separate each path entry and "/" or "\" to separate directory names within a path).

translate - Set to true if you would like us to automatically translate ":", ";", "/", and "\" characters for you to the platform specific form via translatePathList(). Most likely you will want this set to true, but you can set it to false if you want us to just parse exactly what you send us.

Returns:

Enumeration of String objects of each directory parsed from the PATH string.

Since:

1.0

See Also:

addDirectories(java.lang.String), translatePathList(java.lang.String)

addDirectory

public boolean addDirectory(String path)

Add a additional directory to the search path. This routine is used to add exactly one search path to the object which will be seached when one attempts to look for a specific file.

Parameters:

String - A string corresponding to a path in the file system. If the object has automatic translation enabled, then the '/' and '\' characters will be translated to the appropriate form for the platform.

Returns:

Returns a boolean - true if successfully added. False if String specified could not be resolved to an existing directory on the system.

See Also:

addDirectories(java.lang.String), Example Program, searchForFile(java.lang.String)

addDirectories

public int addDirectories(String path)

Add one or more directories to the search path. This routine is used to add one or more search paths to the object which will be seached when one attempts to look for a specific file. For example, one could pass the string "/tmp/java:../java" and know that the two directories: /tmp/java and ../java will be added to the search path when a file is searched for. The search order will be from left to right and if this function is invoked more than once, all directories added from subsequent calls will be search after the directories added by prior calls.

Parameters:

String - PATH type string with the java.io.File.pathSeparator separating directories (or the characters ';' or ':' if automatic translation is enabled). For example: "/tmp:/usr/local".

Returns:

Returns a count of the number of directories in the path that existed and were added to the path search list.

See Also:

addDirectory(java.lang.String), Example Program, searchForFile(java.lang.String), parsePathString(java.lang.String, boolean)

searchForFile

public File searchForFile(String name)

Try to locate a file in the current search path. This routine searches for a specific file in one of the paths specified. NOTE: if the string provided contains a absolute path then the search will fail; however, a relative path is acceptable. Hence "/tmp/fred.java" won't ever be found, whereas "../tmp/fred.java" and "etc/test.cfg" might be.

Parameters:

String - Name of the file to search for

Returns:

File object if the file was found somewhere in the current list of paths to search (null if not found).

See Also:

addDirectory(java.lang.String), addDirectories(java.lang.String), Example Program

toString

public String toString()

Return a PATH looking string of the current search areas. Returns a PATH type string of all of the current directories in the current search path. Each directory will be separated by the platform specific java.io.File.pathSeparator character.

Overrides:

toString in class Object

Returns:

String of the form like: ".;\\opt\\java" on a Windows or OS/2 type platform, and a string like: ".:/opt/java" on a Unix type platform.

getSystemPath

public static PathSearch getSystemPath()

Try to look up the standard PATH for the Operating System. This method tries to lookup the standard search PATH for the operating system (since the getenv() has been removed from the operating system, this is a non-trivial task). The following attempts will be made:

• We will hope that the user was nice and provided a "os.path" system setting. This can be done at the command line by invoking Java like:

  java -Dos.path=$PATH CLASS ARGS

• Next, if "os.path" is not found we will look first for the property files "$HOME/etc/java.properties" and then "/etc/java.properties". If we find either "os.path.OS" (where OS matches System.getProperty("os.name") in lower case) or "os.path", we will use that value.
• If we are still unlucky, we will attempt to print the users environment and extract it from the line starting with "PATH=" if we are lucky enough to do so. (NOTE: this has not yet been implemented).
• Finally, we will give up and use some predefined paths based on the OS type (which might work).

As this is an expensive computation, it is done only one time and a non-mutable PathSearch object will be returned (attempts to modify it will be ignored).

Returns:

A PathSearch object that can not be modified (you can't add additional directories to it). Subsequent calls to this method will immediately return the results of the first invocation.

Since:

1.0

See Also:

ProcessInvoker