Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Java


[Previous] [Class List] [Next]

NSFileWrapper


Inherits from: NSObject
Package: com.apple.yellow.application


Class Description


An NSFileWrapper holds a file's contents in dynamic memory. In this role it enables a document object to embed a file, treating it as a unit of data that can be displayed as an image (and possibly edited in place), saved to disk, or transmitted to another application. It can also store an icon for representing the file in a document or in a dragging operation.

Instances of this class are referred to as file wrapper objects, and when no confusion will result, merely as file wrappers. A file wrapper can be one of three specific types: a regular file wrapper, which holds the contents of a single actual file; a directory wrapper, which holds a directory and all of the files or directories within it; or a link wrapper, which simply represents a symbolic link in the file system (sometimes called a shortcut or alias). Some NSFileWrapper methods apply only to a specific type, and throw an exception if sent to a file wrapper of the wrong type. To determine the type of a file wrapper, use the isRegularFile, isDirectory, and isSymbolicLink methods.

You can create a file wrapper from data in memory using initWithSerializedRepresentation: or from data on disk using initWithPath:. Both create the appropriate type of file wrapper based on the nature of the serialized representation or of the file on disk. Three convenience methods each create a file wrapper of a specific type: initRegularFileWithContents:, initDirectoryWithFileWrappers:, and initSymbolicLinkWithDestination:. Because each initialization method creates file wrappers of different types or states, they're all designated initializers for this class-subclasses must meaningfully override them all as necessary.

Memory and Disk Representations

Because the purpose of a file wrapper is to represent files in memory, it's very loosely coupled to any disk representation. A file wrapper doesn't record the path to the disk representation of its contents. This allows you to save the same file wrapper with different paths, but it also requires you to record those paths if you want to update the file wrapper from disk later. NSFileWrapper allows you to set a preferred filename for save operations and records the last filename it was actually saved to; the preferredFilename and filename methods return these names. This feature is more important for directory wrappers, though, and so is discussed under "Working with Directory Wrappers" below.

A file wrapper stores file system information (such as modification time and access permissions), which it updates when reading from disk and uses when writing files to disk. The fileAttributes method returns this information in the format described in the NSFileManager class specification. You can also set the file attributes using the setFileAttributes method.

When saving a file wrapper to disk, you typically determine the directory you want to save it in, then append the preferred filename to that directory path and use writeToFile, which saves the file wrapper's contents and updates the file attributes. You can save a file wrapper under a different name if you wish, but this may result in the recorded filename differing from the preferred filename, depending on how you invoke the writeToFile:... method.

Besides saving its contents to disk, a file wrapper can re-read them from disk when necessary. The needsToBeUpdatedFromPath: method determines whether a disk representation may have changed, based on the file attributes stored the last time the file was read or written. If the file wrapper's modification time or access permissions are different from those of the file on disk, this method returns YES. You can then use updateFromPath: to re-read the file from disk.

Finally, to transmit a file wrapper to another process or system (for example, over a distributed objects connection or through the pasteboard), you use the serializedRepresentation method to get an NSData object containing the file wrapper's contents in the NSFileContentsPboardType format. You can safely transmit this representation over whatever channel you desire. The recipient of the representation can then reconstitute the file wrapper using the initWithSerializedRepresentation: method.

Working with Directory Wrappers

A directory wrapper contains other file wrappers (of any type), and allows you to access them by keys derived from their preferred filenames. You can add any type of file wrapper to a directory wrapper with addFileWrapper or addFileWithPath, and remove it with removeFileWrapper. The convenience methods addRegularFileWithContents and addSymbolicLinkWithDestination allow you to add regular file and link wrappers while also setting their preferred names.

A directory wrapper stores its contents in an NSDictionary, which you can retrieve using the fileWrappers method. The keys of this dictionary are based on the preferred filenames of each file wrapper contained in the directory wrapper. There exist, then, three identifiers for a file wrapper within a directory wrapper:

When working with the contents of a directory wrapper, you can use a dictionary enumerator to retrieve each file wrapper and perform whatever operation you need. Note that with the exceptions of saving and updating, a directory file wrapper defines no recursive operations for its contents. To set the file attributes for all contained file wrappers, or to perform any other such operation, you must define a recursive method that examines the type of each file wrapper and invokes itself anew for any directory wrapper it encounters.


Method Types


Initializing a file wrapper
initWithPath:
initDirectoryWithFileWrappers:
initRegularFileWithContents:
initSymbolicLinkWithDestination:
initWithSerializedRepresentation:
Writing to a file or serializing
writeToFile
serializedRepresentation
Checking a file wrapper's type
isRegularFile
isDirectory
isSymbolicLink
Setting attributes
setFilename
filename
setPreferredFilename
preferredFilename
setIcon
icon
setFileAttributes
fileAttributes
Updating
needsToBeUpdatedFromPath
updateFromPath
Modifying a directory wrapper
addFileWrapper
removeFileWrapper
addFileWithPath
addRegularFileWithContents
addSymbolicLinkWithDestination
fileWrappers
keyForFileWrapper
Inspecting a regular file wrapper
regularFileContents
Inspecting a link wrapper
symbolicLinkDestination

Constructors


NSFileWrapper

public NSFileWrapper(String aString, boolean aBoolean)

public NSFileWrapper(NSData aNSData, boolean aBoolean)

public NSFileWrapper()

public NSFileWrapper(NSDictionary aNSDictionary)



Instance Methods



addFileWithPath

public String addFileWithPath(String path)

Adds a new file wrapper to the receiving directory wrapper. Initializes the new file wrapper with initWithPath: using path as the argument, then adds the new file wrapper by invoking addFileWrapper:. Returns the dictionary key used for the newly added file wrapper within the directory wrapper. Throws an exception if sent to a regular file or link wrapper.

See Also: addRegularFileWithContents, addSymbolicLinkWithDestination, removeFileWrapper, fileWrappers



addFileWrapper

public String addFileWrapper(NSFileWrapper wrapper)

Adds wrapper to the receiving directory wrapper. Returns the dictionary key used for wrapper within the directory wrapper. Throws an exception if sent to a regular file or link wrapper, or if tyhe wrapper doesn't have a preferred name (set using setPreferredName:).

See Also: addFileWithPath, addRegularFileWithContents, addSymbolicLinkWithDestination, removeFileWrapper, fileWrappers



addRegularFileWithContents

public String addRegularFileWithContents(NSData contents, String filename)

Adds a new regular file wrapper to the receiving directory wrapper. Initializes the new file wrapper with initRegularFileWithContents: using contents as the argument, sets its preferred name with setPreferredName: using filename as the argument, then adds the new file wrapper by invoking addFileWrapper. Returns the dictionary key used for the newly added file wrapper within the directory wrapper. Throws an exception if sent to a regular file or link wrapper, or if the filename is null or empty.

See Also: addFileWithPath, addSymbolicLinkWithDestination, removeFileWrapper, fileWrappers



addSymbolicLinkWithDestination

public String addSymbolicLinkWithDestination(String path, String filename)

Adds a new link wrapper to the receiving directory wrapper. Initializes the new link wrapper with initSymbolicLinkWithDestination: using path as the argument, sets its preferred name with setPreferredName: using filename as the argument, then adds the new link wrapper by invoking addFileWrapper. Returns the dictionary key used for the newly added link wrapper within the directory wrapper. Throws an exception if sent to a regular file or link wrapper, or if the filename is null or empty.

See Also: addFileWithPath, addFileWrapper, addRegularFileWithContents, removeFileWrapper, fileWrappers



fileAttributes

public NSDictionary fileAttributes()

Returns the file attributes last read from disk or set using setFileAttributes. These attributes are used whenever the file wrapper is saved using writeToFile. See the NSFileManager class specification for information on the contents of the attributes dictionary.

filename

public String filename()

Returns the filename for the last known disk representation of the receiver, or null if the receiver has no filename. The filename is used for record-keeping purposes only, and is set automatically when the file wrapper is created from disk using initWithPath: and when it's saved to a disk using writeToFile:atomically:updateFilenames: (although this method allows you to request that the filename not be updated).

See Also: preferredFilename, setFilename



fileWrappers

public NSDictionary fileWrappers()

Returns the file wrappers contained in a directory wrapper. Throws an exception if sent to a regular file or link wrapper. See "Working with Directory Wrappers" in the class description for information on the dictionary.

See Also: filename, addFileWrapper



icon

public NSImage icon()

Returns an image that can be used to represent the file wrapper to the user, or null if the file wrapper has none. You don't have to use this image; for example, a file viewer typically looks up icons automatically based on file extensions, and so wouldn't need this image. Similarly, if a file wrapper represents an image file, you can display the image directly rather than a file icon.

See Also: setIcon



isDirectory

public boolean isDirectory()

Returns true if the receiver is a directory wrapper, false otherwise.

See Also: isRegularFile, isSymbolicLink



isRegularFile

public boolean isRegularFile()

Returns true if the receiver is a regular file wrapper, false otherwise.

See Also: isDirectory, isSymbolicLink



isSymbolicLink

public boolean isSymbolicLink()

Returns true if the receiver is a link wrapper, false otherwise.

See Also: isDirectory, isRegularFile



keyForFileWrapper

public String keyForFileWrapper(NSFileWrapper wrapper)

Returns the key by which the receiving directory wrapper stores wrapper in its dictionary (as returned by the fileWrappers method). This is not necessarily the filename for wrapper. Throws an exception if sent to a regular file or link wrapper.

See Also: filename



needsToBeUpdatedFromPath

public boolean needsToBeUpdatedFromPath(String path)

Returns true if the receiver's contents on disk may have changed, false otherwise. For a regular file wrapper, this is determined by comparing the modification time and access permissions of the file or directory at path against those of the receiver. For a link wrapper, this is determined by checking whether the destination path has changed (not by checking the modification time or access attributes of the destination). For a directory, this is determined as needed recursively for each file wrapper contained in the directory; added or removed files also count as changes.

See Also: updateFromPath, fileAttributes



preferredFilename

public String preferredFilename()

Returns the file wrapper's preferred filename. This name is used as the default dictionary key and filename when a file wrapper is added to a directory wrapper. However, if another file wrapper with the same preferred name already exists in the directory wrapper when the receiver is added, the dictionary key and filename assigned may differ from the preferred filename.

See Also: setPreferredFilename, filename



regularFileContents

public NSData regularFileContents()

Returns the contents of the receiving regular file wrapper. Throws an exception if sent to a directory or link wrapper.

removeFileWrapper

public void removeFileWrapper(NSFileWrapper wrapper)

Removes wrapper from the receiving directory wrapper and releases it. Throws an exception if sent to a regular file or link wrapper.

See Also: addFileWithPath, addFileWrapper, addRegularFileWithContents, addSymbolicLinkWithDestination, fileWrappers



serializedRepresentation

public NSData serializedRepresentation()

Returns the receiver's contents as an opaque collection of data, in the format used for the pasteboard type NSFileContentsPboardType.

See Also: initWithSerializedRepresentation:



setFileAttributes

public void setFileAttributes(NSDictionary attributes)

Sets the file attributes applied whenever the file wrapper is saved using writeToFile:atomically:updateFilenames: to attributes. See the NSFileManager class specification for information on the contents of the attributes dictionary.

See Also: fileAttributes



setFilename

public void setFilename(String filename)

Sets the filename for the disk representation of the receiver to filename. The filename is used for record-keeping purposes only, and is set automatically when the file wrapper is saved to a disk using writeToFile:atomically:updateFilenames: (although this method allows you to request that the filename not be updated). You should rarely need to invoke this method.

Throws an exception if filename is null or empty.

See Also: setPreferredFilename, filename



setIcon

public void setIcon(NSImage anImage)

Sets the image that can be used to represent the file wrapper to the user to anImage. You don't have to use this image; for example, a file viewer typically looks up icons automatically based on file extensions, and so wouldn't need this image. Similarly, if a file wrapper represents an image file, you can display the image directly rather than a file icon.

See Also: icon



setPreferredFilename

public void setPreferredFilename(String filename)

Sets the receiver's preferred filename to filename. This name is used as the default dictionary key and filename when a file wrapper is added to a directory wrapper. However, if another file wrapper with the same preferred name already exists in the directory wrapper when the receiver is added, the dictionary key and filename assigned may differ from the preferred filename. Throws an exception if filename is null or empty.

See Also: preferredFilename, addFileWrapper, setFilename



symbolicLinkDestination

public String symbolicLinkDestination()

Returns the actual path represented by the receiving link wrapper. Throws an exception if sent to a regular file or directory wrapper.

updateFromPath

public boolean updateFromPath(String path)

Re-reads the file wrapper's information from the file or directory at path, including contents or link destination, icon, file attributes. For a directory wrapper, the contained file wrappers are also sent updateFromPath: messages. If files in the directory on disk have been added or removed, corresponding file wrappers are released or created as needed. Returns true if updating actually occurred, false if it wasn't necessary.

See Also: needsToBeUpdatedFromPath, - updateAttachmentsFromPath: (NSAttributedString)



writeToFile

public boolean writeToFile(String path, boolean atomicFlag, boolean updateNamesFlag)

Writes the receiver's contents to a file or directory at path. Returns true on success and false on failure. If atomicFlag is true, attempts to write the file safely so that an existing file at path is not overwritten, nor does a new file at path actually get created, unless the write is successful. If updateNamesFlag is true and the contents are successfully written, changes the receiver's filename to the last component of path, and the filenames of any children of a directory wrapper to the filenames under which they're written to disk.

If you're executing a "save" or "save as" style operation, pass true for updateNamesFlag; if you're executing a "save to" style operation, pass false for updateNamesFlag.

See Also: filename




[Previous] [Next]