org.openide.filesystems 7.3.1

org.openide.filesystems
Class FileUtil

java.lang.Object
  extended by org.openide.filesystems.FileUtil

public final class FileUtil
extends Object

Common utilities for handling files. This is a dummy class; all methods are static.


Method Summary
static boolean affectsOrder(FileAttributeEvent event)
          Checks whether a change in a given file attribute would affect the result of getOrder(java.util.Collection, boolean).
static void copy(InputStream is, OutputStream os)
          Copies stream of files.
static void copyAttributes(FileObject source, FileObject dest)
          Copies attributes from one file to another.
static FileObject copyFile(FileObject source, FileObject destFolder, String newName)
          Copies file to the selected folder.
static FileObject copyFile(FileObject source, FileObject destFolder, String newName, String newExt)
          Copies file to the selected folder.
static FileObject createData(File data)
          Returns FileObject for a data file.
static FileObject createData(FileObject folder, String name)
          Returns a data file on given filesystem if such a data file exists.
static FileObject createFolder(File folder)
          Returns FileObject for a folder.
static FileObject createFolder(FileObject folder, String name)
          Returns a folder on given filesystem if such a folder exists.
static FileSystem createMemoryFileSystem()
          Factory method that creates an empty implementation of a filesystem that completely resides in a memory.
static void extractJar(FileObject fo, InputStream is)
          Deprecated. Use of XML filesystem layers generally obsoletes this method.
static FileObject findBrother(FileObject fo, String ext)
          Finds brother file with same base name but different extension.
static String findFreeFileName(FileObject folder, String name, String ext)
          Finds an unused file name similar to that requested in the same folder.
static String findFreeFolderName(FileObject folder, String name)
          Finds an unused folder name similar to that requested in the same parent folder.
static FileObject[] fromFile(File file)
          Deprecated. Use toFileObject(java.io.File) instead.
static FileObject getArchiveFile(FileObject fo)
          Returns a FileObject representing an archive file containing the FileObject given by the parameter.
static URL getArchiveFile(URL url)
          Returns the URL of the archive file containing the file referred to by a jar-protocol URL.
static FileObject getArchiveRoot(FileObject fo)
          Returns a FileObject representing the root folder of an archive.
static URL getArchiveRoot(URL url)
          Returns a URL representing the root of an archive.
static String getExtension(String fileName)
          Gets the extension of a specified file name.
static String getFileDisplayName(FileObject fo)
          Get an appropriate display name for a file object.
static String getMIMEType(FileObject fo)
          Resolves MIME type.
static String getMIMEType(String ext)
          Deprecated. use getMIMEType(FileObject) as MIME cannot be generally detected by file object extension.
static List<FileObject> getOrder(Collection<FileObject> children, boolean logWarnings)
          Sorts some sibling file objects.
static String getRelativePath(FileObject folder, FileObject fo)
          Gets a relative resource path between folder and fo.
static boolean isArchiveFile(FileObject fo)
          Tests if a file represents a JAR or ZIP archive.
static boolean isArchiveFile(URL url)
          Tests if a URL represents a JAR or ZIP archive.
static boolean isParentOf(FileObject folder, FileObject fo)
          Recursively checks whether the file is underneath the folder.
static FileObject moveFile(FileObject source, FileObject destFolder, String newName)
          Moves file to the selected folder.
static URLStreamHandler nbfsURLStreamHandler()
          Construct a stream handler that handles the nbfs URL protocol used for accessing file objects directly.
static File normalizeFile(File file)
          Normalize a file path to a clean form.
static void preventFileChooserSymlinkTraversal(JFileChooser chooser, File currentDirectory)
          Make sure that a JFileChooser does not traverse symlinks on Unix.
static void setMIMEType(String ext, String mimeType)
          Deprecated. You should instead use the more general MIMEResolver system.
static void setOrder(List<FileObject> children)
          Imposes an order on some sibling file objects.
static File toFile(FileObject fo)
          Finds appropriate java.io.File to FileObject if possible.
static FileObject toFileObject(File file)
          Converts a disk file to a matching file object.
static FileChangeListener weakFileChangeListener(FileChangeListener l, Object source)
          Creates a weak implementation of FileChangeListener.
static FileStatusListener weakFileStatusListener(FileStatusListener l, Object source)
          Creates a weak implementation of FileStatusListener.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

createFolder

public static FileObject createFolder(File folder)
                               throws IOException
Returns FileObject for a folder. If such a folder does not exist then it is created, including any necessary but nonexistent parent folders. Note that if this operation fails it may have succeeded in creating some of the necessary parent folders.

Parameters:
folder - folder to be created
Returns:
FileObject for a folder
Throws:
IOException - if the creation fails
Since:
7.0

createData

public static FileObject createData(File data)
                             throws IOException
Returns FileObject for a data file. If such a data file does not exist then it is created, including any necessary but nonexistent parent folders. Note that if this operation fails it may have succeeded in creating some of the necessary parent folders.

Parameters:
data - data file to be created
Returns:
FileObject for a data file
Throws:
IOException - if the creation fails
Since:
7.0

copy

public static void copy(InputStream is,
                        OutputStream os)
                 throws IOException
Copies stream of files.

Please be aware, that this method doesn't close any of passed streams.

Parameters:
is - input stream
os - output stream
Throws:
IOException

createMemoryFileSystem

public static FileSystem createMemoryFileSystem()
Factory method that creates an empty implementation of a filesystem that completely resides in a memory.

Returns:
a blank writable filesystem
Since:
4.43

copyFile

public static FileObject copyFile(FileObject source,
                                  FileObject destFolder,
                                  String newName,
                                  String newExt)
                           throws IOException
Copies file to the selected folder. This implementation simply copies the file by stream content.

Parameters:
source - source file object
destFolder - destination folder
newName - file name (without extension) of destination file
newExt - extension of destination file
Returns:
the created file object in the destination folder
Throws:
IOException - if destFolder is not a folder or does not exist; the destination file already exists; or another critical error occurs during copying

copyFile

public static FileObject copyFile(FileObject source,
                                  FileObject destFolder,
                                  String newName)
                           throws IOException
Copies file to the selected folder. This implementation simply copies the file by stream content. Uses the extension of the source file.

Parameters:
source - source file object
destFolder - destination folder
newName - file name (without extension) of destination file
Returns:
the created file object in the destination folder
Throws:
IOException - if destFolder is not a folder or does not exist; the destination file already exists; or another critical error occurs during copying

moveFile

public static FileObject moveFile(FileObject source,
                                  FileObject destFolder,
                                  String newName)
                           throws IOException
Moves file to the selected folder. This implementation uses a copy-and-delete mechanism, and automatically uses the necessary lock.

Parameters:
source - source file object
destFolder - destination folder
newName - file name (without extension) of destination file
Returns:
new file object
Throws:
IOException - if either the copy or delete failed

createFolder

public static FileObject createFolder(FileObject folder,
                                      String name)
                               throws IOException
Returns a folder on given filesystem if such a folder exists. If not then a folder is created, including any necessary but nonexistent parent folders. Note that if this operation fails it may have succeeded in creating some of the necessary parent folders. The name of the new folder can be specified as a multi-component pathname whose components are separated by File.separatorChar or "/" (forward slash).

Parameters:
folder - where the new folder will be placed in
name - name of the new folder
Returns:
the new folder
Throws:
IOException - if the creation fails

createData

public static FileObject createData(FileObject folder,
                                    String name)
                             throws IOException
Returns a data file on given filesystem if such a data file exists. If not then a data file is created, including any necessary but nonexistent parent folders. Note that if this operation fails it may have succeeded in creating some of the necessary parent folders. The name of data file can be composed as resource name (e. g. org/netbeans/myfolder/mydata ).

Parameters:
folder - to begin with creation at
name - name of data file as a resource
Returns:
the data file for given name
Throws:
IOException - if the creation fails

toFile

public static File toFile(FileObject fo)
Finds appropriate java.io.File to FileObject if possible. If not possible then null is returned. This is the inverse operation of toFileObject(java.io.File).

Parameters:
fo - FileObject whose corresponding File will be looked for
Returns:
java.io.File or null if no corresponding File exists.
Since:
1.29

toFileObject

public static FileObject toFileObject(File file)
Converts a disk file to a matching file object. This is the inverse operation of toFile(org.openide.filesystems.FileObject).

If you are running with the MasterFS module enabled, that will guarantee that this method never returns null for a file which exists on disk.

Parameters:
file - a disk file (may or may not exist). This file must be normalized.
Returns:
a corresponding file object, or null if the file does not exist or there is no URLMapper available to convert it
Since:
4.29

fromFile

@Deprecated
public static FileObject[] fromFile(File file)
Deprecated. Use toFileObject(java.io.File) instead.

Finds appropriate FileObjects to java.io.File if possible. If not possible then empty array is returned. More FileObjects may correspond to one java.io.File that`s why array is returned.

Parameters:
file - File whose corresponding FileObjects will be looked for. The file has to be "normalized" otherwise IllegalArgumentException is thrown. See normalizeFile(java.io.File) for how to do that.
Returns:
corresponding FileObjects or empty array if no corresponding FileObject exists.
Since:
1.29

copyAttributes

public static void copyAttributes(FileObject source,
                                  FileObject dest)
                           throws IOException
Copies attributes from one file to another. Note: several special attributes will not be copied, as they should semantically be transient. These include attributes used by the template wizard (but not the template attribute itself).

Parameters:
source - source file object
dest - destination file object
Throws:
IOException - if the copying failed

extractJar

@Deprecated
public static void extractJar(FileObject fo,
                                         InputStream is)
                       throws IOException
Deprecated. Use of XML filesystem layers generally obsoletes this method.

Extract jar file into folder represented by file object. If the JAR contains files with name filesystem.attributes, it is assumed that these files has been created by DefaultAttributes implementation and the content of these files is treated as attributes and added to extracted files.

META-INF/ directories are skipped over.

Parameters:
fo - file object of destination folder
is - input stream of jar file
Throws:
IOException - if the extraction fails

getExtension

public static String getExtension(String fileName)
Gets the extension of a specified file name. The extension is everything after the last dot.

Parameters:
fileName - name of the file
Returns:
extension of the file (or "" if it had none)

findFreeFileName

public static String findFreeFileName(FileObject folder,
                                      String name,
                                      String ext)
Finds an unused file name similar to that requested in the same folder. The specified file name is used if that does not yet exist or is isVirtual. Otherwise, the first available name of the form basename_nnn.ext (counting from one) is used.

Caution: this method does not lock the parent folder to prevent race conditions: i.e. it is possible (though unlikely) that the resulting name will have been created by another thread just as you were about to create the file yourself (if you are, in fact, intending to create it just after this call). Since you cannot currently lock a folder against child creation actions, the safe approach is to use a loop in which a free name is retrieved; an attempt is made to create that file; and upon an IOException during creation, retry the loop up to a few times before giving up.

Parameters:
folder - parent folder
name - preferred base name of file
ext - extension to use
Returns:
a free file name (without the extension)

findFreeFolderName

public static String findFreeFolderName(FileObject folder,
                                        String name)
Finds an unused folder name similar to that requested in the same parent folder.

See caveat for findFreeFileName.

Parameters:
folder - parent folder
name - preferred folder name
Returns:
a free folder name
See Also:
findFreeFileName

getRelativePath

public static String getRelativePath(FileObject folder,
                                     FileObject fo)
Gets a relative resource path between folder and fo.

Parameters:
folder - root of filesystem or any other folder in folders hierarchy
fo - arbitrary FileObject in folder's tree (including folder itself)
Returns:
relative path between folder and fo. The returned path never starts with a '/'. It never ends with a '/'. Specifically, if folder==fo, returns "". Returns null if fo is not in folder's tree.
Since:
4.16
See Also:
isParentOf(org.openide.filesystems.FileObject, org.openide.filesystems.FileObject)

findBrother

public static FileObject findBrother(FileObject fo,
                                     String ext)
Finds brother file with same base name but different extension.

Parameters:
fo - the file to find the brother for or null
ext - extension for the brother file
Returns:
a brother file (with the requested extension and the same parent folder as the original) or null if the brother file does not exist or the original file was null

getMIMEType

@Deprecated
public static String getMIMEType(String ext)
Deprecated. use getMIMEType(FileObject) as MIME cannot be generally detected by file object extension.

Obtain MIME type for a well-known extension. If there is a case-sensitive match, that is used, else will fall back to a case-insensitive match.

Parameters:
ext - the extension: "jar", "zip", etc.
Returns:
the MIME type for the extension, or null if the extension is unrecognized

getMIMEType

public static String getMIMEType(FileObject fo)
Resolves MIME type. Registered resolvers are invoked and used to achieve this goal. Resolvers must subclass MIMEResolver. If resolvers don`t recognize MIME type then MIME type is obtained for a well-known extension.

Parameters:
fo - whose MIME type should be recognized
Returns:
the MIME type for the FileObject, or null if the FileObject is unrecognized

setMIMEType

@Deprecated
public static void setMIMEType(String ext,
                                          String mimeType)
Deprecated. You should instead use the more general MIMEResolver system.

Register MIME type for a new extension. Note that you may register a case-sensitive extension if that is relevant (for example *.C for C++) but if you register a lowercase extension it will by default apply to uppercase extensions too (for use on Windows or generally for situations where filenames become accidentally uppercase).

Parameters:
ext - the file extension (should be lowercase unless you specifically care about case)
mimeType - the new MIME type
Throws:
IllegalArgumentException - if this extension was already registered with a different MIME type
See Also:
getMIMEType(java.lang.String)

nbfsURLStreamHandler

public static URLStreamHandler nbfsURLStreamHandler()
Construct a stream handler that handles the nbfs URL protocol used for accessing file objects directly. This method is not intended for module use; only the core should need to call it. Modules probably need only use URLMapper to create and decode such URLs.

Since:
3.17

isParentOf

public static boolean isParentOf(FileObject folder,
                                 FileObject fo)
Recursively checks whether the file is underneath the folder. It checks whether the file and folder are located on the same filesystem, in such case it checks the parent FileObject of the file recursively until the folder is found or the root of the filesystem is reached.

Warning: this method will return false in the case that folder == fo.

Parameters:
folder - the root of folders hierarchy to search in
fo - the file to search for
Returns:
true, if fo lies somewhere underneath the folder, false otherwise
Since:
3.16

weakFileChangeListener

public static FileChangeListener weakFileChangeListener(FileChangeListener l,
                                                        Object source)
Creates a weak implementation of FileChangeListener.

Parameters:
l - the listener to delegate to
source - the source that the listener should detach from when listener l is freed, can be null
Returns:
a FileChangeListener delegating to l.
Since:
4.10

weakFileStatusListener

public static FileStatusListener weakFileStatusListener(FileStatusListener l,
                                                        Object source)
Creates a weak implementation of FileStatusListener.

Parameters:
l - the listener to delegate to
source - the source that the listener should detach from when listener l is freed, can be null
Returns:
a FileChangeListener delegating to l.
Since:
4.10

getFileDisplayName

public static String getFileDisplayName(FileObject fo)
Get an appropriate display name for a file object. If the file corresponds to a path on disk, this will be the disk path. Otherwise the name will mention the filesystem name or archive name in case the file comes from archive and relative path. Relative path will be mentioned just in case that passed FileObject isn't root FileObject.isRoot().

Parameters:
fo - a file object
Returns:
a display name indicating where the file is
Since:
4.39

normalizeFile

public static File normalizeFile(File file)
Normalize a file path to a clean form. This method may for example make sure that the returned file uses the natural case on Windows; that old Windows 8.3 filenames are changed to the long form; that relative paths are changed to be absolute; that . and .. sequences are removed; etc. Unlike File.getCanonicalFile() this method will not traverse symbolic links on Unix.

This method involves some overhead and should not be called frivolously. Generally it should be called on incoming pathnames that are gotten from user input (including filechoosers), configuration files, Ant properties, etc. Internal calculations should not need to renormalize paths since File.listFiles(), File.getParentFile(), etc. will not produce abnormal variants.

Parameters:
file - file to normalize
Returns:
normalized file
Since:
4.48

getArchiveRoot

public static FileObject getArchiveRoot(FileObject fo)
Returns a FileObject representing the root folder of an archive. Clients may need to first call isArchiveFile(FileObject) to determine if the file object refers to an archive file.

Parameters:
fo - a ZIP- (or JAR-) format archive file
Returns:
a virtual archive root folder, or null if the file is not actually an archive
Since:
4.48

getArchiveRoot

public static URL getArchiveRoot(URL url)
Returns a URL representing the root of an archive. Clients may need to first call isArchiveFile(URL) to determine if the URL refers to an archive file.

Parameters:
url - of a ZIP- (or JAR-) format archive file
Returns:
the jar-protocol URL of the root of the archive
Since:
4.48

getArchiveFile

public static FileObject getArchiveFile(FileObject fo)
Returns a FileObject representing an archive file containing the FileObject given by the parameter. Remember that any path within the archive is discarded so you may need to check for non-root entries.

Parameters:
fo - a file in a JAR filesystem
Returns:
the file corresponding to the archive itself, or null if fo is not an archive entry
Since:
4.48

getArchiveFile

public static URL getArchiveFile(URL url)
Returns the URL of the archive file containing the file referred to by a jar-protocol URL. Remember that any path within the archive is discarded so you may need to check for non-root entries.

Parameters:
url - a URL
Returns:
the embedded archive URL, or null if the URL is not a jar-protocol URL containing !/
Since:
4.48

isArchiveFile

public static boolean isArchiveFile(FileObject fo)
Tests if a file represents a JAR or ZIP archive.

Parameters:
fo - the file to be tested
Returns:
true if the file looks like a ZIP-format archive
Since:
4.48

isArchiveFile

public static boolean isArchiveFile(URL url)
Tests if a URL represents a JAR or ZIP archive. If there is no such file object, the test is done by heuristic: any URL with an extension is treated as an archive.

Parameters:
url - a URL to a file
Returns:
true if the URL seems to represent a ZIP-format archive
Since:
4.48

preventFileChooserSymlinkTraversal

public static void preventFileChooserSymlinkTraversal(JFileChooser chooser,
                                                      File currentDirectory)
Make sure that a JFileChooser does not traverse symlinks on Unix.

Parameters:
chooser - a file chooser
currentDirectory - if not null, a file to set as the current directory using JFileChooser.setCurrentDirectory(java.io.File) without canonicalizing
Since:
org.openide/1 4.42
See Also:
Issue #46459, JRE bug #4906607

getOrder

public static List<FileObject> getOrder(Collection<FileObject> children,
                                        boolean logWarnings)
                                 throws IllegalArgumentException
Sorts some sibling file objects.

Normally this is done by looking for numeric file attributes named position on the children; children with a lower position number are placed first. Now-deprecated relative ordering attributes of the form earlier/later may also be used; if the above attribute has a boolean value of true, then the file named earlier will be sorted somewhere (not necessarily directly) before the file named later. Numeric and relative attributes may also be mixed.

The sort is stable at least to the extent that if there is no ordering information whatsoever, the returned list will be in the same order as the incoming collection.

Parameters:
children - zero or more files (or folders); must all have the same FileObject.getParent()
logWarnings - true to log warnings about relative ordering attributes or other semantic problems, false to keep quiet
Returns:
a sorted list of the same children
Throws:
IllegalArgumentException - in case there are duplicates, or nulls, or the files do not have a common parent
Since:
org.openide.filesystems 7.2
See Also:
setOrder(java.util.List), Specification

setOrder

public static void setOrder(List<FileObject> children)
                     throws IllegalArgumentException,
                            IOException
Imposes an order on some sibling file objects. After this call, if no other changes have intervened, getOrder(java.util.Collection, boolean) on these files should return a list in the same order. Beyond the fact that this call may manipulate the position attributes of files in the folder, and may delete deprecated relative ordering attributes on the folder, the exact means of setting the order is unspecified.

Parameters:
children - a list of zero or more files (or folders); must all have the same FileObject.getParent()
Throws:
IllegalArgumentException - in case there are duplicates, or nulls, or the files do not have a common parent
IOException - if new file attributes to order the children cannot be written out
Since:
org.openide.filesystems 7.2

affectsOrder

public static boolean affectsOrder(FileAttributeEvent event)
Checks whether a change in a given file attribute would affect the result of getOrder(java.util.Collection, boolean).

Parameters:
event - an attribute change event
Returns:
true if the attribute in question might affect the order of some folder
Since:
org.openide.filesystems 7.2

org.openide.filesystems 7.3.1

Built on January 29 2008.  |  Portions Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.