org.springframework.roo.process.manager

Interface FileManager

All Known Implementing Classes:

DefaultFileManager

public interface FileManager

Represents the primary means for add-ons to modify the underlying disk storage.

A FileManager instance is acquired from the ProcessManager. A FileManager implementation must guarantee to use an UndoManager that is available to the ProcessManager, such that ProcessManager can undo or reset as required.

An implementation may elect to defer writes to disk or discard them until commit() or clear() respectively is invoked.

Since:

1.0

Author:

Ben Alex

Method Summary

Methods

Modifier and Type	Method and Description
void	clear() Discards proposed changes to the disk that an implementation may have elected to defer.
void	commit() Commits actual changes to the disk that an implementation may have elected to defer.
org.springframework.roo.file.monitor.event.FileDetails	createDirectory(String fileIdentifier) Attempts to create a new directory on the disk.
MutableFile	createFile(String fileIdentifier) Attempts to create a zero-byte file on the disk.
void	createOrUpdateTextFileIfRequired(String fileIdentifier, String newContents, boolean writeImmediately) Provides a simple way to create or update a file, skipping any modification if the file's contents match the proposed contents.
void	createOrUpdateTextFileIfRequired(String fileIdentifier, String newContents, String descriptionOfChange, boolean writeImmediately) Provides a simple way to create or update a file, skipping any modification if the file's contents match the proposed contents.
void	delete(String pathname) Attempts to delete a file or directory on the disk.
void	delete(String pathname, String reasonForDeletion) Attempts to delete a file or directory on the disk.
boolean	exists(String fileIdentifier) Indicates whether the file identified by the passed canonical path exists.
SortedSet<org.springframework.roo.file.monitor.event.FileDetails>	findMatchingAntPath(String antPath) Delegates to FileMonitorService.findMatchingAntPath(String).
InputStream	getInputStream(String fileIdentifier) Obtains an input stream for the indicated file identifier, which must be a file (not a directory) and must exist at the time the method is called.
org.springframework.roo.file.monitor.event.FileDetails	readFile(String fileIdentifier) Obtains an already-existing file for reading.
int	scan() Delegates to FileMonitorService.scanAll() or NotifiableFileMonitorService.scanNotified() if available.
MutableFile	updateFile(String fileIdentifier) Provides an updatable representation of a file on the disk.

Method Detail

clear

void clear()

Discards proposed changes to the disk that an implementation may have elected to defer.

commit

void commit()

Commits actual changes to the disk that an implementation may have elected to defer.

createDirectory

org.springframework.roo.file.monitor.event.FileDetails createDirectory(String fileIdentifier)

Attempts to create a new directory on the disk.

The requested file identifier path must not already exist. It should be in canonical file name format.

Parent directories must also be created automatically by this method. Any created parent directories should be removed as part of the undo behaviour.

An exception will be thrown if the path already exists.

Parameters:

fileIdentifier - a path to be created that does not already exist (required)

Returns:

a representation of the directory (or null if the creation failed)

createFile

MutableFile createFile(String fileIdentifier)

Attempts to create a zero-byte file on the disk.

The requested fileIdentifier path must not already exist. It should be in canonical file name format.

Implementations guarantee to createDirectory(String) as required to create any required parent directories.

An exception will be thrown if the path already exists.

Parameters:

fileIdentifier - a path to be created that does not already exist (required)

Returns:

a representation of the file (or null if the creation failed)

createOrUpdateTextFileIfRequired

void createOrUpdateTextFileIfRequired(String fileIdentifier,
                                    String newContents,
                                    boolean writeImmediately)

Provides a simple way to create or update a file, skipping any modification if the file's contents match the proposed contents. This should only be called for text files.

This mechanism also automatically deletes an unwanted file if the new contents are zero bytes. If deleting, the existence of the file need not be considered in advance (it will only delete if the file is present, but it will not fail if the file does not exist or has been separately deleted).

Implementations guarantee to createDirectory(String) as required to create any required parent directories.

Implementations are required to observe the commit() and clear() semantics defined in the type-level JavaDocs.

Parameters:

fileIdentifier - the file to create or update as appropriate (required)

newContents - the replacement contents (required, but can be zero bytes if the file should be deleted)

writeImmediately - forces immediate write of the file to disk (false means it can be deferred, as recommended)

createOrUpdateTextFileIfRequired

void createOrUpdateTextFileIfRequired(String fileIdentifier,
                                    String newContents,
                                    String descriptionOfChange,
                                    boolean writeImmediately)

Provides a simple way to create or update a file, skipping any modification if the file's contents match the proposed contents. This should only be called for text files.

This mechanism also automatically deletes an unwanted file if the new contents are zero bytes. If deleting, the existence of the file need not be considered in advance (it will only delete if the file is present, but it will not fail if the file does not exist or has been separately deleted).

Implementations guarantee to createDirectory(String) as required to create any required parent directories.

Implementations are required to observe the commit() and clear() semantics defined in the type-level JavaDocs.

Parameters:

fileIdentifier - the file to create or update as appropriate (required)

newContents - the replacement contents (required, but can be zero bytes if the file should be deleted)

descriptionOfChange - the additional information about a change (can be null)

writeImmediately - forces immediate write of the file to disk (false means it can be deferred, as recommended)

delete

void delete(String pathname)

Attempts to delete a file or directory on the disk. The path should be in canonical file name format.

If the path refers to a directory, contents of the directory will be recursively deleted.

If a delete fails, an exception will be thrown.

Parameters:

pathname - the file to delete; can be blank to do nothing, otherwise should be a valid pathname as per File.File(String)

Throws:

IllegalArgumentException - if a file is specified but does not exist

delete

void delete(String pathname,
          String reasonForDeletion)

Attempts to delete a file or directory on the disk. The path should be in canonical file name format.

If the path refers to a directory, contents of the directory will be recursively deleted.

If a delete fails, an exception will be thrown.

Parameters:

pathname - the file to delete; can be blank to do nothing, otherwise should be a valid pathname as per File.File(String)

reasonForDeletion - the reason why the file is being deleted (can be blank)

Throws:

IllegalArgumentException - if a file is specified but does not exist

Since:

1.2.0

exists

boolean exists(String fileIdentifier)

Indicates whether the file identified by the passed canonical path exists.

Parameters:

fileIdentifier - the file or directory to locate (required, in canonical path format)

Returns:

true if the file or directory exists

findMatchingAntPath

SortedSet<org.springframework.roo.file.monitor.event.FileDetails> findMatchingAntPath(String antPath)

Delegates to FileMonitorService.findMatchingAntPath(String).

Parameters:

antPath - the Ant path to evaluate, as per the canonical file path format (required)

Returns:

all matching identifiers (may be empty, but never null)

getInputStream

InputStream getInputStream(String fileIdentifier)

Obtains an input stream for the indicated file identifier, which must be a file (not a directory) and must exist at the time the method is called. This method is useful if read-only access to a file is required. For read-write access, use one of the other methods on FileManager.

Parameters:

fileIdentifier - the file to read (required, in canonical path format)

Returns:

the input stream (never null)

readFile

org.springframework.roo.file.monitor.event.FileDetails readFile(String fileIdentifier)

Obtains an already-existing file for reading. The path should be in canonical file name format.

Parameters:

fileIdentifier - the file to read that already exists (required)

Returns:

a representation of the file (or null if the file does not exist)

scan

int scan()

Delegates to FileMonitorService.scanAll() or NotifiableFileMonitorService.scanNotified() if available.

Returns:

the number of changes detected (can be 0 or above)

updateFile

MutableFile updateFile(String fileIdentifier)

Provides an updatable representation of a file on the disk.

The file identifier must refer to a file (not directory) that already exists. A violation of this requirement will result in an exception. The identifier should be in canonical file name format.

Refer to the documentation for MutableFile for important restrictions on usage.

Parameters:

fileIdentifier - the file to update (must be a file that already exists, required)

Returns:

a mutable presentation (never null)