Package ghidra.framework.store.local

Class LocalFileSystem

java.lang.Object

ghidra.framework.store.local.LocalFileSystem

All Implemented Interfaces:

FileSystem

Direct Known Subclasses:

IndexedLocalFileSystem, MangledLocalFileSystem

public abstract class LocalFileSystem
extends java.lang.Object
implements FileSystem

LocalFileSystem provides access to FolderItem's which exist within a File-based directory structure. Although FolderItem caching is highly recommended, it is not provided by this implementation and should be provided by an encompassing set of folder/file objects.

A LocalFileSystem may optionally support version control of its FolderItem's. When versioned, FolderItem's must be checked-out to create new versions. When not versioned, the check-out mechanism is not used.

FileSystemListener's will only be notified of changes made by the associated LocalFileSystem instance. For this reason, it is important that proper measures are taken to prevent concurrent modification of the underlying files/directories by another instance or by any other means.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static class	LocalFileSystem.ItemStorage

Field Summary

Fields

Modifier and Type	Field	Description
protected FileSystemEventManager	eventManager
static java.lang.String	HIDDEN_DIR_PREFIX
static char	HIDDEN_DIR_PREFIX_CHAR	Hidden directory name prefix.
static java.lang.String	HIDDEN_ITEM_PREFIX	Hidden item name prefix.
protected boolean	isVersioned
protected boolean	readOnly
protected java.io.File	root

Fields inherited from interface ghidra.framework.store.FileSystem

SEPARATOR, SEPARATOR_CHAR

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	LocalFileSystem()	Constructor for an empty read-only file-system.
protected	LocalFileSystem(java.lang.String rootPath, boolean isVersioned, boolean readOnly, boolean enableAsyncronousDispatching)	Constructor.

Method Summary

Modifier and Type	Method	Description
void	addFileSystemListener(FileSystemListener listener)	Adds the given listener to be notified of file system changes.
protected abstract LocalFileSystem.ItemStorage	allocateItemStorage(java.lang.String folderPath, java.lang.String itemName)	Allocate a new storage location
protected void	cleanupAfterConstruction()
LocalDatabaseItem	createDatabase(java.lang.String parentPath, java.lang.String name, java.lang.String fileID, BufferFile bufferFile, java.lang.String comment, java.lang.String contentType, boolean resetDatabaseId, TaskMonitor monitor, java.lang.String user)	Create a new database item within the specified parent folder using the contents of the specified BufferFile.
LocalManagedBufferFile	createDatabase(java.lang.String parentPath, java.lang.String name, java.lang.String fileID, java.lang.String contentType, int bufferSize, java.lang.String user, java.lang.String projectPath)	Create a new empty database item within the specified parent folder.
LocalDataFile	createDataFile(java.lang.String parentPath, java.lang.String name, java.io.InputStream istream, java.lang.String comment, java.lang.String contentType, TaskMonitor monitor)	Creates a new empty data file within the specified parent folder.
LocalDatabaseItem	createFile(java.lang.String parentPath, java.lang.String name, java.io.File packedFile, TaskMonitor monitor, java.lang.String user)	Creates a new file item from a packed file.
LocalDatabaseItem	createTemporaryDatabase(java.lang.String parentPath, java.lang.String name, java.lang.String fileID, BufferFile bufferFile, java.lang.String contentType, boolean resetDatabaseId, TaskMonitor monitor)
protected abstract void	deallocateItemStorage(java.lang.String folderPath, java.lang.String itemName)	Deallocate item storage
protected void	deleteEmptyVersionedFolders(java.lang.String folderPath)	Remove the directory which corresponds to the specified folder path if it is empty.
void	dispose()	Cleanup and release resources
static java.lang.String	escapeHiddenDirPrefixChars(java.lang.String name)	Escape hidden prefix chars in name
boolean	fileExists(java.lang.String folderPath, java.lang.String name)	Returns true if the file exists
protected void	fileIdChanged(PropertyFile propertyFile, java.lang.String oldFileId)	Notification that FileID has been changed within propertyFile
protected abstract LocalFileSystem.ItemStorage	findItemStorage(java.lang.String folderPath, java.lang.String itemName)	Find an existing storage location
abstract boolean	folderExists(java.lang.String folderPath)	Returns true if the folder specified by the path exists.
FolderItem	getItem(java.lang.String fileID)	Returns the FolderItem specified by its unique File-ID
LocalFolderItem	getItem(java.lang.String folderPath, java.lang.String name)	Returns the FolderItem in the given folder with the given name
java.lang.String[]	getItemNames(java.lang.String folderPath)	Returns a list of the folder item names contained in the given folder.
protected abstract java.lang.String[]	getItemNames(java.lang.String folderPath, boolean includeHiddenFiles)
static LocalFileSystem	getLocalFileSystem(java.lang.String rootPath, boolean create, boolean isVersioned, boolean readOnly, boolean enableAsyncronousDispatching)	Construct a local filesystem for existing data
abstract int	getMaxNameLength()
protected static java.lang.String	getName(java.lang.String path)
protected static java.lang.String	getParentPath(java.lang.String path)
protected static java.lang.String	getPath(java.lang.String parentPath, java.lang.String name)	Returns the full path for a specific folder or item
java.lang.String	getUserName()	Get user name associated with this filesystem.
static boolean	isHiddenDirName(java.lang.String name)	Determines if the specified storage directory name corresponds to a hidden directory (includes both system and application hidden directories).
boolean	isOnline()	Returns true if file-system is on-line.
boolean	isReadOnly()	Returns true if file-system is read-only.
static boolean	isRefreshRequired()
boolean	isShared()	Returns true if this file system is shared
static boolean	isValidNameCharacter(char c)
boolean	isVersioned()	Returns true if the file-system requires check-outs when modifying folder items.
protected void	itemDeleted(java.lang.String folderPath, java.lang.String itemName)	Notify the filesystem that the property file and associated data files for an item have been removed from the filesystem.
protected void	log(LocalFolderItem item, java.lang.String msg, java.lang.String user)
boolean	migrationInProgress()
void	moveItem(java.lang.String folderPath, java.lang.String name, java.lang.String newFolderPath, java.lang.String newName)	Moves the specified item to a new folder.
void	removeFileSystemListener(FileSystemListener listener)	Removes the listener from being notified of file system changes.
void	setAssociatedRepositoryLogger(RepositoryLogger repositoryLogger)	Associate file system with a specific repository logger
static void	setValidationRequired()	If set, the state of folder item resources will be continually refreshed.
void	testValidName(java.lang.String name, boolean isPath)	Validate a folder/item name or path.
static java.lang.String	unescapeHiddenDirPrefixChars(java.lang.String name)	Unescape a non-hidden directory name

Methods inherited from class java.lang.Object

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

Methods inherited from interface ghidra.framework.store.FileSystem

createFolder, deleteFolder, getFolderNames, getItemCount, moveFolder, renameFolder

Field Detail

HIDDEN_DIR_PREFIX_CHAR

public static final char HIDDEN_DIR_PREFIX_CHAR

Hidden directory name prefix. Should only be prepended to an escaped base-name.

See Also:

escapeHiddenDirPrefixChars(String), Constant Field Values

HIDDEN_DIR_PREFIX

public static final java.lang.String HIDDEN_DIR_PREFIX

HIDDEN_ITEM_PREFIX

public static final java.lang.String HIDDEN_ITEM_PREFIX

Hidden item name prefix.

See Also:

Constant Field Values

root

protected final java.io.File root

isVersioned

protected final boolean isVersioned

readOnly

protected final boolean readOnly

eventManager

protected final FileSystemEventManager eventManager

Constructor Detail

LocalFileSystem

protected LocalFileSystem(java.lang.String rootPath,
                          boolean isVersioned,
                          boolean readOnly,
                          boolean enableAsyncronousDispatching)
                   throws java.io.FileNotFoundException

Constructor.

Parameters:

rootPath - root path directory.

isVersioned - if true item versioning will be enabled.

readOnly - if true modifications within this file-system will not be allowed and result in an ReadOnlyException

enableAsyncronousDispatching - if true a separate dispatch thread will be used to notify listeners. If false, blocking notification will be performed.

Throws:

java.io.FileNotFoundException - if specified rootPath does not exist

LocalFileSystem

protected LocalFileSystem()

Constructor for an empty read-only file-system.

Method Detail

getLocalFileSystem

public static LocalFileSystem getLocalFileSystem(java.lang.String rootPath,
                                                 boolean create,
                                                 boolean isVersioned,
                                                 boolean readOnly,
                                                 boolean enableAsyncronousDispatching)
                                          throws java.io.IOException

Construct a local filesystem for existing data

Parameters:

rootPath -

create -

isVersioned -

readOnly -

enableAsyncronousDispatching -

Returns:

local filesystem

Throws:

java.io.FileNotFoundException - if specified rootPath does not exist

java.io.IOException - if error occurs while reading/writing index files

getUserName

public java.lang.String getUserName()

Description copied from interface: FileSystem

Get user name associated with this filesystem. In the case of a remote filesystem this will correspond to the name used during login/authentication. A null value may be returned if user name unknown.

Specified by:

getUserName in interface FileSystem

cleanupAfterConstruction

protected void cleanupAfterConstruction()

setAssociatedRepositoryLogger

public void setAssociatedRepositoryLogger(RepositoryLogger repositoryLogger)

Associate file system with a specific repository logger

Parameters:

repositoryLogger -

log

protected void log(LocalFolderItem item,
                   java.lang.String msg,
                   java.lang.String user)

setValidationRequired

public static void setValidationRequired()

If set, the state of folder item resources will be continually refreshed. This is required if multiple instances exist for a single item. The default is disabled. This feature should be enabled for testing only since it may have a significant performance impact. This does not provide locking which may be required for a shared environment (e.g., checkin locking is only managed by a single instance).

isRefreshRequired

public static boolean isRefreshRequired()

Returns:

true if folder item resources must be refreshed.

See Also:

setValidationRequired()

isVersioned

public boolean isVersioned()

Description copied from interface: FileSystem

Returns true if the file-system requires check-outs when modifying folder items.

Specified by:

isVersioned in interface FileSystem

isOnline

public boolean isOnline()

Description copied from interface: FileSystem

Returns true if file-system is on-line.

Specified by:

isOnline in interface FileSystem

isReadOnly

public boolean isReadOnly()

Description copied from interface: FileSystem

Returns true if file-system is read-only.

Specified by:

isReadOnly in interface FileSystem

findItemStorage

protected abstract LocalFileSystem.ItemStorage findItemStorage(java.lang.String folderPath,
                                                               java.lang.String itemName)
                                                        throws java.io.FileNotFoundException

Find an existing storage location

Parameters:

folderPath -

itemName -

Returns:

storage location. A non-null value does not guarantee that the associated item actually exists.

Throws:

java.io.FileNotFoundException

allocateItemStorage

protected abstract LocalFileSystem.ItemStorage allocateItemStorage(java.lang.String folderPath,
                                                                   java.lang.String itemName)
                                                            throws java.io.IOException,
                                                                   InvalidNameException

Allocate a new storage location

Parameters:

folderPath -

itemName -

Returns:

storage location

Throws:

DuplicateFileException - if item path has previously been allocated

java.io.IOException - if invalid path/item name specified

InvalidNameException - if folderPath or itemName contains invalid characters

deallocateItemStorage

protected abstract void deallocateItemStorage(java.lang.String folderPath,
                                              java.lang.String itemName)
                                       throws java.io.IOException

Deallocate item storage

Parameters:

folderPath -

itemName -

Throws:

java.io.IOException

getItemNames

protected abstract java.lang.String[] getItemNames(java.lang.String folderPath,
                                                   boolean includeHiddenFiles)
                                            throws java.io.IOException

Throws:

java.io.IOException

getItemNames

public java.lang.String[] getItemNames(java.lang.String folderPath)
                                throws java.io.IOException

Description copied from interface: FileSystem

Returns a list of the folder item names contained in the given folder.

Specified by:

getItemNames in interface FileSystem

Parameters:

folderPath - the path of the folder.

Returns:

a list of folder item names.

Throws:

java.io.IOException

See Also:

FileSystem.getItemNames(java.lang.String)

getItem

public LocalFolderItem getItem(java.lang.String folderPath,
                               java.lang.String name)
                        throws java.io.IOException

Description copied from interface: FileSystem

Returns the FolderItem in the given folder with the given name

Specified by:

getItem in interface FileSystem

Parameters:

folderPath - the folder path containing the item.

name - the name of the item.

Returns:

the FolderItem with the given folderPath and name, or null if it doesn't exist.

Throws:

java.io.IOException - if IO error occurs.

fileIdChanged

protected void fileIdChanged(PropertyFile propertyFile,
                             java.lang.String oldFileId)
                      throws java.io.IOException

Notification that FileID has been changed within propertyFile

Parameters:

propertyFile -

oldFileId -

Throws:

java.io.IOException

getItem

public FolderItem getItem(java.lang.String fileID)
                   throws java.io.IOException,
                          java.lang.UnsupportedOperationException

Description copied from interface: FileSystem

Returns the FolderItem specified by its unique File-ID

Specified by:

getItem in interface FileSystem

Parameters:

fileID - the items unique file ID

Returns:

the FolderItem with the given folderPath and name, or null if it doesn't exist.

Throws:

java.io.IOException - if IO error occurs.

java.lang.UnsupportedOperationException - if file-system does not support this operation

createDatabase

public LocalDatabaseItem createDatabase(java.lang.String parentPath,
                                        java.lang.String name,
                                        java.lang.String fileID,
                                        BufferFile bufferFile,
                                        java.lang.String comment,
                                        java.lang.String contentType,
                                        boolean resetDatabaseId,
                                        TaskMonitor monitor,
                                        java.lang.String user)
                                 throws InvalidNameException,
                                        java.io.IOException,
                                        CancelledException

Description copied from interface: FileSystem

Create a new database item within the specified parent folder using the contents of the specified BufferFile.

Specified by:

createDatabase in interface FileSystem

Parameters:

parentPath - folder path of parent

name - new database name

fileID - file ID to be associated with new database or null

bufferFile - data source

comment - version comment (used for versioned file system only)

contentType - application defined content type

resetDatabaseId - if true database ID will be reset for new Database

monitor - allows the database copy to be monitored and cancelled.

user - name of user creating item (required for versioned item)

Returns:

new DatabaseItem

Throws:

InvalidNameException - if the name does not have all alphanumerics

java.io.FileNotFoundException - thrown if parent folder does not exist.

DuplicateFileException - if a folder item exists with this name

java.io.IOException - if an IO error occurs.

CancelledException - if cancelled by monitor

createTemporaryDatabase

public LocalDatabaseItem createTemporaryDatabase(java.lang.String parentPath,
                                                 java.lang.String name,
                                                 java.lang.String fileID,
                                                 BufferFile bufferFile,
                                                 java.lang.String contentType,
                                                 boolean resetDatabaseId,
                                                 TaskMonitor monitor)
                                          throws InvalidNameException,
                                                 java.io.IOException,
                                                 CancelledException

Throws:

InvalidNameException

java.io.IOException

CancelledException

createDatabase

public LocalManagedBufferFile createDatabase(java.lang.String parentPath,
                                             java.lang.String name,
                                             java.lang.String fileID,
                                             java.lang.String contentType,
                                             int bufferSize,
                                             java.lang.String user,
                                             java.lang.String projectPath)
                                      throws InvalidNameException,
                                             java.io.IOException

Description copied from interface: FileSystem

Create a new empty database item within the specified parent folder. If this is a versioned file-system, the associated item is checked-out. The resulting checkoutId can be obtained from the returned buffer file.

Specified by:

createDatabase in interface FileSystem

Parameters:

parentPath - folder path of parent

name - new database name

fileID - file ID to be associated with new database or null

contentType - application defined content type

bufferSize - buffer size. If copying an existing BufferFile, the buffer size must be the same as the source file.

user - name of user creating item (required for versioned item)

projectPath - path of project in which database is checked-out (required for versioned item)

Returns:

an empty BufferFile open for read-write.

Throws:

InvalidNameException - if the name does not have all alphanumerics

java.io.FileNotFoundException - thrown if parent folder does not exist.

DuplicateFileException - if a folder item exists with this name

java.io.IOException - if an IO error occurs.

createDataFile

public LocalDataFile createDataFile(java.lang.String parentPath,
                                    java.lang.String name,
                                    java.io.InputStream istream,
                                    java.lang.String comment,
                                    java.lang.String contentType,
                                    TaskMonitor monitor)
                             throws InvalidNameException,
                                    java.io.IOException,
                                    CancelledException

Description copied from interface: FileSystem

Creates a new empty data file within the specified parent folder.

Specified by:

createDataFile in interface FileSystem

Parameters:

parentPath - folder path of parent

name - new data file name

istream - source data

comment - version comment (used for versioned file system only)

contentType - application defined content type

monitor - progress monitor (used for cancel support, progress not used since length of input stream is unknown)

Returns:

new data file

Throws:

InvalidNameException - if the name has illegal characters. all alphanumerics

DuplicateFileException - Thrown if a folderItem with that name already exists.

java.io.IOException - if an IO error occurs.

CancelledException - if cancelled by monitor

createFile

public LocalDatabaseItem createFile(java.lang.String parentPath,
                                    java.lang.String name,
                                    java.io.File packedFile,
                                    TaskMonitor monitor,
                                    java.lang.String user)
                             throws InvalidNameException,
                                    java.io.IOException,
                                    CancelledException

Description copied from interface: FileSystem

Creates a new file item from a packed file. The content/item type must be determined from the input stream.

Specified by:

createFile in interface FileSystem

Parameters:

parentPath - folder path of parent

name - new data file name

packedFile - packed file data

monitor - progress monitor (used for cancel support, progress not used since length of input stream is unknown)

user - name of user creating item (required for versioned item)

Returns:

new item

Throws:

InvalidNameException - if the name has illegal characters. all alphanumerics

java.io.IOException - if an IO error occurs.

CancelledException - if cancelled by monitor

moveItem

public void moveItem(java.lang.String folderPath,
                     java.lang.String name,
                     java.lang.String newFolderPath,
                     java.lang.String newName)
              throws java.io.IOException,
                     InvalidNameException

Description copied from interface: FileSystem

Moves the specified item to a new folder.

Specified by:

moveItem in interface FileSystem

Parameters:

folderPath - path of folder containing the item.

name - name of the item to be moved.

newFolderPath - path of folder where item is to be moved.

Throws:

java.io.FileNotFoundException - if the item does not exist.

DuplicateFileException - if item with the same name exists within the new parent folder.

FileInUseException - if the item is in-use or checked-out

java.io.IOException - if an IO error occurs.

InvalidNameException - if the newName is invalid

folderExists

public abstract boolean folderExists(java.lang.String folderPath)

Description copied from interface: FileSystem

Returns true if the folder specified by the path exists.

Specified by:

folderExists in interface FileSystem

Parameters:

folderPath - the name of the folder to check for existence.

Returns:

true if the folder exists.

fileExists

public boolean fileExists(java.lang.String folderPath,
                          java.lang.String name)

Description copied from interface: FileSystem

Returns true if the file exists

Specified by:

fileExists in interface FileSystem

Parameters:

folderPath - the folderPath of the folder that may contain the file.

name - the name of the file to check for existence.

addFileSystemListener

public void addFileSystemListener(FileSystemListener listener)

Description copied from interface: FileSystem

Adds the given listener to be notified of file system changes.

Specified by:

addFileSystemListener in interface FileSystem

Parameters:

listener - the listener to be added.

removeFileSystemListener

public void removeFileSystemListener(FileSystemListener listener)

Description copied from interface: FileSystem

Removes the listener from being notified of file system changes.

Specified by:

removeFileSystemListener in interface FileSystem

getMaxNameLength

public abstract int getMaxNameLength()

Returns:

the maximum name length permitted for folders or items.

testValidName

public void testValidName(java.lang.String name,
                          boolean isPath)
                   throws InvalidNameException

Validate a folder/item name or path.

Parameters:

name - folder or item name

isPath - if true name represents full path

Throws:

InvalidNameException - if name is invalid

isValidNameCharacter

public static boolean isValidNameCharacter(char c)

Returns:

true if c is a valid character within the FileSystem.

deleteEmptyVersionedFolders

protected void deleteEmptyVersionedFolders(java.lang.String folderPath)

Remove the directory which corresponds to the specified folder path if it is empty. If folder directory is removed, this method is invoked recursively for parent folder path which may also be removed if it is empty. This method is intended for use with a versioned file system which only retains folders if they contain one or more items or sub-folders.

Parameters:

folderPath - folder path

itemDeleted

protected void itemDeleted(java.lang.String folderPath,
                           java.lang.String itemName)
                    throws java.io.IOException

Notify the filesystem that the property file and associated data files for an item have been removed from the filesystem.

Parameters:

folderPath -

itemName -

Throws:

java.io.IOException

getPath

protected static final java.lang.String getPath(java.lang.String parentPath,
                                                java.lang.String name)

Returns the full path for a specific folder or item

Parameters:

parentPath - full parent path

name - child folder or item name

getParentPath

protected static final java.lang.String getParentPath(java.lang.String path)

getName

protected static final java.lang.String getName(java.lang.String path)

isShared

public boolean isShared()

Description copied from interface: FileSystem

Returns true if this file system is shared

Specified by:

isShared in interface FileSystem

dispose

public void dispose()

Description copied from interface: FileSystem

Cleanup and release resources

Specified by:

dispose in interface FileSystem

migrationInProgress

public boolean migrationInProgress()

isHiddenDirName

public static final boolean isHiddenDirName(java.lang.String name)

Determines if the specified storage directory name corresponds to a hidden directory (includes both system and application hidden directories).

Parameters:

name - directory name as it appears on storage file system.

Returns:

true if name is a hidden name, else false

escapeHiddenDirPrefixChars

public static final java.lang.String escapeHiddenDirPrefixChars(java.lang.String name)

Escape hidden prefix chars in name

Parameters:

name -

Returns:

escaped name

unescapeHiddenDirPrefixChars

public static final java.lang.String unescapeHiddenDirPrefixChars(java.lang.String name)

Unescape a non-hidden directory name

Parameters:

name -

Returns:

unescaped name or null if name is a hidden name