de.frame4j.io

Class FileHelper

java.lang.Object

de.frame4j.io.FileHelper

@MinDoc(copyright="Copyright  2016  A. Weinert",
        author="Albrecht Weinert",
        version="V.51",
        lastModified="7.06.2021",
        usage="use en lieu de direct java.io.File",
        purpose="a file with some extra abilities")
public final class FileHelper
extends Object

Support for file handling.

This class provides some operations and comfort for the handling of Files to simplify applications that have to handle files. (And which don't have to?)


© Copyright 1998 - 2009, 2013 Albrecht Weinert.

Version:

51 (7.06.2021)

Author:

Albrecht Weinert

See Also:

FileCriteria, FileService

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	FileHelper.OS Embedded class OS (OutputStream) of FileHelper.

Field Summary

Fields

Modifier and Type	Field and Description
static FileVisitor	ASK_OVERWRITE A FileVisitor default implementation — for asking.
static FileVisitor	askOverwrite Default setting for procedure to ask on file changes.
static Comparator<File>	comparator A extensive File comparator.
static File[]	NO_FileX Array of no Files.
static boolean	sortFNC Case of file names is relevant for sorting.

Method Summary

Modifier and Type	Method and Description
static int	compare(File d1, File d2) Compare two files.
static boolean	contains(File thisFile, File otherFile) Ask if other file or directory may be part of this file.
static int	copyFrom(Input ein, File out, OutMode outMode) Write into a file.
static String	getCompleteFilePath(String basePath, String name) Construct a complete path.
static File	getInstance(String path) Factory by pathname (String).
static File	getInstance(String basePath, String name) Factory by pathname (String) and path relative name (String).
static String	getType(File f) Fetching the file type, meaning the name's extension.
static String	getType(String name) Extracting the file type (extension) from a given file name.
static String	infoLine(File f) Generate a line for a file list.
static StringBuilder	infoLine(File f, StringBuilder dest, boolean noParent, boolean quoteSpace) Generate a line for a file list.
static StringBuilder	infoLine(File f, StringBuilder bastel, boolean noParent, boolean quoteSpace, String relateTo) Generate a line for a file list.
static boolean	isOfType(File f, CharSequence types) Check the file type (i.e. the name's extension).
static String	listLine(File f) Generate a line for a file list.
static FileHelper.OS	makeOS(File f, OutMode mode) Make an output connected to the File.
static FileHelper.OS	makeOS(File f, OutMode mode, Charset outEncoding) Make an output connected to the File given.
static StringBuilder	pathName(File f, StringBuilder dest, boolean noParent, boolean quoteSpace) Generate a file denomination [Path\]Name.
static StringBuilder	pathName(File f, StringBuilder dest, boolean noParent, boolean quoteSpace, String relateTo) Generate a file denomination [Path\]Name.
static boolean	sameDir(File f, Object o) Compare two file paths (only).
static boolean	sameName(File f, Object o) Compare two file names (only).
static boolean	testDescribe(File f, PrintWriter out) Output a test description of this file.
static boolean	wildEqual(File f, String wildName) Compare the name with a pattern with optionally wildcards.

Methods inherited from class java.lang.Object

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

Field Detail

comparator

public static Comparator<File> comparator

A extensive File comparator.

See Also:

compare(File, File)

NO_FileX

public static final File[] NO_FileX

Array of no Files.

sortFNC

public static boolean sortFNC

Case of file names is relevant for sorting.

default: ComVar.NOT_WINDOWS; true, if the platform is definitely not Windows.

ASK_OVERWRITE

public static final FileVisitor ASK_OVERWRITE

A FileVisitor default implementation — for asking.

This is a (default) implementation of the interface FileVisitor by an object of that inetrface's embedded class FileVisitor.AskConsImpl with default settings. It is to ask on the console by nationalised text before writing on existing files.

Value: new FileVisitor.AskConsImpl(false, null, null, null)

Since:

V01.02 (08.12.2001)

askOverwrite

public static volatile FileVisitor askOverwrite

Default setting for procedure to ask on file changes.

This static variable defines the (default) behaviour of some methods of this class before changing existing files respectively opening them (for writing).

The default setting of this static variable is the constant ASK_OVERWRITE. It may be changed.

A graphical or javaw-started application must and other may prefer an asking by a Window. For that purpose use an instance of FileVisitor.AskGrafImpl.

Since:

V01.02 (08.12.2001)

See Also:

makeOS(), ASK_OVERWRITE

Method Detail

compare

public static final int compare(File d1,
                                File d2)

Compare two files.

This method implements the interface java.util.Comparator. This method compares file properties according to their ordering not file content.

The comparing sequence for the attributes is

1. name (case sensitive according to platform settings)
2. length
3. modification date
4. path name (parent directory)
   

The first found non equal comparing "wins", as its value is returned. 0 would only be returned if all compared properties are equal.

This method defines a total ordering that is not consistent to File.equals().

See Also:

ComVar.OS, sortFNC

getCompleteFilePath

public static final String getCompleteFilePath(String basePath,
                                               String name)

Construct a complete path.

If both basePath and name are null, null is returned.

A file name is made specified by the path (parameter basePath) and name. These may be absolute or relative, containing relative path expressions like ..\ or .\ . The returned name will be an unambiguous and complete — "canonical" —) pathname. A missing separator (\ bei DOS/Windows) at the end of basePath will be supplied. basePath if given always denotes directory.)

"Canonical" means a complete and free of all relativity and relative expressions according to the rules of the used file system.

Example: D:\otto\emil\oha.txt on Windows would be the canonical form of D:\otto\hugo\..\emil/marzan\..\oha.txt.

If the given path is relative, the current actual path is prepended.

Implementation hint: This method contains (predecessor's) code to fight Java's class call miss-interpretation of X:oha, X: and uhu\oha on Windows. There are strong hints that at least in Java 6 those problems are past. File.getCanonicalPath() on Windows now seems to have the same effect as the (quite older) code here. Be it not for the Exceptions threatening in File's method File.getCanonicalPath() (IO and Security for just a bit file name syntax handling?) the old code here could be removed.

Parameters:

basePath - the path (directory) (or null)

name - the file name

Returns:

a complete name

See Also:

getInstance()

getInstance

public static File getInstance(String basePath,
                               String name)

Factory by pathname (String) and path relative name (String).

A File object is made. It will be tried, to canonicalise the basePath. This means also trying to make relative paths absolute.
(The method getFileWithCompletePath() will be applied to basePath.)

Parameters:

basePath - The name of a directory either absolute or relative to the applications actual path

name - The name of a file or directory relative to path.

Returns:

A fitting File object or null

getInstance

public static File getInstance(String path)

Factory by pathname (String).

A File object is made. It will be tried, to canonicalise the basePath. These means also trying to make relative paths absolute.
(The method getFileWithCompletePath() will be applied to basePath.)

Parameters:

path - The name of a file or directory either absolute or relative to the applications actual path

Returns:

A fitting File object or null

getType

public static String getType(String name)

Extracting the file type (extension) from a given file name.

The name's extension is returned including (!) the leading dot (.).

null is returned if the name contains no dot (.) before the last character.
If the the name (part) before the dot is empty, the name itself is considered as type.

Implementation hint: In Frame4J's predecessor the analogous method of class "Datei" returned the extension in upper case. This (quite bad) idea was dropped for Frame4J.

Parameters:

name - a "pure" name without any paths or drive letters

Returns:

the extension or null

See Also:

getType(File)

getType

public static String getType(File f)

Fetching the file type, meaning the name's extension.

The name's extension is returned including (!) the leading dot (.).

null is returned if the name (part) contains no "inner dot".
This includes the case of the name (part) being itself empty. If the File object was not constructed "canonically" it is possible that the file name wrongly is part of the (parent) path. Then, of course, (not only) this method fails.

Implementation hint: In Frame4J's predecessor the analogous method of class "Datei" returned the extension in upper case. This (quite bad) idea was dropped for Frame4J.

Returns:

the extension or null

See Also:

isOfType(), getCompleteFilePath()

isOfType

public static boolean isOfType(File f,
                               CharSequence types)

Check the file type (i.e. the name's extension).

This file's type will be compared with the type(s) specified by the parameter types. The matching allows for semicolon separated lists as well as wildCards (* ?) in types and is not case sensitive.
Example: ".htm; HTML ".

Is types null, true is returned.

If types has an empty entry (like the second one in ".htm; ;.exe"), than (and only than) a file name with no extension ("otto") will get a true.

Hints:

1. blanks in types are ignored; a missing start dot (.) will be added, and a leading first asterisk (*) before a dot removed.
2. Wildcards (? *) on else places within a type are OK.
3. If the File object was not constructed "canonically" the file name part may wrongly be empty. Than (not only) this method fails.

Implementation hint: In Frame4J's predecessor the equivalent method Datei.isOfType() in fact used "pathSeparator" instead of the semicolon (; in above examples). That (bad) idea is dropped here, as the Linux pathSeparator (:) has nothing to do with a type list in the above sense. Anyway, that concept of file type is foreign to Linux.

Parameters:

types - the extensions asked for

f - the file to get the type from

Returns:

true, if a fit was found

See Also:

getType(), getInstance(), getCompleteFilePath(), wildEqual(), TextHelper.wildEqual(CharSequence, CharSequence, boolean)

contains

public static boolean contains(File thisFile,
                               File otherFile)

Ask if other file or directory may be part of this file.

The method returns true if the path (File.getPath()) of the otherFile provided contains thisFile's path really as a part.

This would mean otherFile being a subdirectory of thisFile or directly or indirectly contained. It must be "real containment"; just same paths return false.

Existence of both files or their type (directory/file) will not be considered.

Parameters:

otherFile - possibly contained in thisFile

Returns:

true, if contained directly or indirectly

wildEqual

public static boolean wildEqual(File f,
                                String wildName)

Compare the name with a pattern with optionally wildcards.

The file f's name is compared to the pattern wildname, that may as well contain wildcard characters (? and *).

The call is equivalent to:
TextHelper.wildEqual(wildName, dieseDatei.getName(), false)

Parameters:

wildName - the pattern, may include wildcards

Returns:

true if matches (according to wildEqual() rules)

See Also:

TextHelper.wildEqual(CharSequence, CharSequence, boolean), isOfType(File, CharSequence)

testDescribe

public static boolean testDescribe(File f,
                                   PrintWriter out)

Output a test description of this file.

A multi-line description of this object is output to parameter out.

Parameters:

out - the destination for the description

Returns:

true, if this file exists

See Also:

listLine()

listLine

public static String listLine(File f)

Generate a line for a file list.

One descriptive line containing name, length, modification date and attributes will be made and returned.

An tabular layout will be tried, as well as keeping the length below 78 characters. If enough space remains the directory path is appended in braces (behind the attributes).

Returns:

the line

See Also:

testDescribe(), infoLine(File)

pathName

public static StringBuilder pathName(File f,
                                     StringBuilder dest,
                                     boolean noParent,
                                     boolean quoteSpace)

Generate a file denomination [Path\]Name.

The call is equivalent to pathName(dest, noParent, quoteSpace, null).

pathName

public static StringBuilder pathName(File f,
                                     StringBuilder dest,
                                     boolean noParent,
                                     boolean quoteSpace,
                                     String relateTo)

Generate a file denomination [Path\]Name.

A text with either path and name or only name plus a prefix "... \ " will be made.

Parameters:

dest - the StringBuilder to append to; if null it is made with starting capacity 89

noParent - true: omit directory information

quoteSpace - true: If name contains spaces, surround by "

relateTo - if the parent directory starts with relateTo this starting part will be omitted

Returns:

dest

See Also:

testDescribe(), listLine()

infoLine

public static String infoLine(File f)

Generate a line for a file list.

The call is equivalent to infoLine(f, null, false, false).

Returns:

the generated line

See Also:

testDescribe(), listLine()

infoLine

public static StringBuilder infoLine(File f,
                                     StringBuilder dest,
                                     boolean noParent,
                                     boolean quoteSpace)

Generate a line for a file list.

The call is equivalent to infoLine(f, dest, noParent, quoteSpace, null).

infoLine

public static StringBuilder infoLine(File f,
                                     StringBuilder bastel,
                                     boolean noParent,
                                     boolean quoteSpace,
                                     String relateTo)

Generate a line for a file list.


A descriptive line containing name, length, modification date and attributes will be made.

Between name and the other denominations is at least one space.

This method favours similar and parsable informations over tabular layout and beauty to the human reader. For the latter use listLine(File).

Parameters:

noParent - true: generate without parent directory information

quoteSpace - true: If name contains spaces, surround by "

relateTo - if the parent directory starts with relateTo this starting part will be omitted

Returns:

the line

See Also:

testDescribe(), listLine(File)

makeOS

public static FileHelper.OS makeOS(File f,
                                   OutMode mode,
                                   Charset outEncoding)

Make an output connected to the File given.

This method generates and returns an object of the inner class FileHelper.OS and hence FileOutputStream plus a PrintWriter (pw) contained.

Parameter mode specifies how to treat an existing file pointed to by the File object given as f; see OutMode for the possible behaviours. null is treated as OutMode.ASK.

Parameters:

mode - how to handle existing files

outEncoding - the PrintWriter's encoding; null or defaults to platform's file encoding

Returns:

An FileHelper.OS for this File or null if impossible or forbidden

See Also:

ASK_OVERWRITE, askOverwrite, FileVisitor, FileVisitor.AskConsImpl, FileVisitor.AskGrafImpl

makeOS

public static final FileHelper.OS makeOS(File f,
                                         OutMode mode)

Make an output connected to the File.

The call is equivalent to makeOS(f, mode, null).

copyFrom

public static int copyFrom(Input ein,
                           File out,
                           OutMode outMode)

Write into a file.

The (remaining or recorded) content of the Input object supplied will be written respectively appended into the given File.

If the file (behind) exists the behaviour is governed by outMode like described for makeOS()).

The OutMode UPDATE means: If the Input object represents a file or an URL and if the given File already exists it is overwritten if the given File's last modification is older than that of the Input.

If Input allows to determine the time of the last modification that is set for the given File after successful copying. (Otherwise it would be the actual time, as this method modified the file.)

Parameters:

ein - the input

outMode - the mode

Returns:

number of bytes copied / written into this file; -1 : no input or no age difference in update mode or no out; < 0 if errors; -3 = IOException

See Also:

makeOS(), Input

sameName

public static boolean sameName(File f,
                               Object o)

Compare two file names (only).

This method returns true, if the other object is a File and just the names (not the paths) are equal. The comparison is or is not case sensitive according to the platform.

See Also:

sortFNC, sameDir

sameDir

public static boolean sameDir(File f,
                              Object o)

Compare two file paths (only).

This method returns true, if the other object is a (Data)File and just the paths (parent directories; not the names) are equal. The comparison is or is not case sensitive according to the platform.

See Also:

sortFNC, sameName