Class 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.

    • 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

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      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 & 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
    • 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:
        #escapeHiddenPrefixChars(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
    • Constructor Detail

      • LocalFileSystem

        protected LocalFileSystem​(java.lang.String rootPath,
                                  boolean isVersioned,
                                  boolean readOnly,
                                  boolean enableAsyncronousDispatching)
                           throws java.io.FileNotFoundException
        Constructor.
        Parameters:
        file - path path for root 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).
        Parameters:
        validationRequired -
      • 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
      • 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
        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.
      • getMaxNameLength

        public abstract int getMaxNameLength()
      • 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 & 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