Package ca.cgjennings.apps.arkham.project

Class Member

  • All Implemented Interfaces:
    IconProvider, java.lang.Comparable<Member>, java.lang.Iterable<Member>
    Direct Known Subclasses:
    Task
    public class Member
extends java.lang.Object
implements IconProvider, java.lang.Iterable<Member>, java.lang.Comparable<Member>
    A member of a project. This is the base class for objects that that can be part of a project. Members of a project also correspond to files in the file system; the file for a given member can be obtained by calling getFile().
    Since:
    2.1
    Author:
    Chris Jennings

    • Constructor Summary

      Constructors 
      Constructor Description
      Member​(Member parent, java.io.File file)
      Creates a new project member with the specified parent, representing the specified file.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int compareTo​(Member rhs)
      Compares two project members.
      void deleteFile()
      Deletes the file associated with this member.
      boolean equals​(java.lang.Object obj)
      Returns true if and only if the specified object is a project member for the same file as this project member.
      Member findChild​(java.io.File file)
      Returns the child of this member whose file is equal to the specified file, or null if there is no such child.
      Member findChild​(java.lang.String name)
      Finds a child of this member by name.
      java.lang.String getBaseName()
      Returns the base file name of this project member.
      Member getChildAt​(int childIndex)
      Returns the child member at the specified index.
      int getChildCount()
      Returns the number of children that this member has (possibly zero).
      Member[] getChildren()
      Returns the children of this member as an array.
      static java.lang.String[] getExcludedFilePatterns()
      Returns an array containing the file name patterns that will be ignored by the project system.
      java.lang.String getExtension()
      Returns the file name extension of this project member.
      java.io.File getFile()
      Returns the file represented by this project member.
      ThemedIcon getIcon()
      Returns an icon that is appropriate for this member.
      int getIndex​(Member potentialChild)
      Returns the index at which the specified member can be found as a child of this member.
      MetadataSource getMetadataSource()
      Returns a MetadataSource that is appropriate for fetching metadata for a file of the type represented by this member.
      java.lang.String getName()
      Returns the name of this project member.
      Member getParent()
      Returns the member that is this member's parent, or null if this is the member representing the Project (or if it was explicitly created with a null parent).
      Project getProject()
      Returns the Project this member belongs to.
      Task getTask()
      Returns the Task this member belongs to.
      java.net.URL getURL()
      Returns a project: URL that can be used to access this member whenever this project is the main open project.
      boolean hasChildren()
      Returns true if this member has children.
      int hashCode()
      Returns a hash code for this member.
      boolean isAncestorOf​(Member child)
      Returns true if this is an ancestor of child.
      static boolean isFileExcluded​(java.io.File f)
      Returns true if file exclusion patterns have been set and f matches one of the patterns.
      boolean isFolder()
      Returns true if this member is a folder rather than a file.
      java.util.Iterator<Member> iterator()
      Returns an iterator over this member's children.
      static void registerMetadataSource​(MetadataSource source)
      Adds a new source of metadata.
      void renameFile​(java.lang.String newFileName)
      Renames the file associated with this member.
      static void setExcludedFilePatterns​(java.lang.String... patterns)
      Sets a list of file name patterns that will be ignored by the project system.
      void synchronize()
      Hints to the project that this is a good time to update this node's children to reflect changes to the file system.
      java.lang.String toString()
      Returns the project member's base name.
      static void unregisterMetadataSource​(MetadataSource source)
      Removes a previously registered source of metadata.

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator

    • Constructor Detail

      • Member

        public Member​(Member parent,
              java.io.File file)
        Creates a new project member with the specified parent, representing the specified file. Project members are not normally created this way, but are instead obtained, directly or indirectly from a Project's children.

        Note that this constructor can be used to explicitly create a member that is not actually in a project. This is sometimes useful (for example, to obtain a MetadataSource for an arbitrary file), but it will invalidate some parts of the Member contract (such as getProject() always returning a non-null value).

        Parameters:
        parent - the member that will be the new member's parent
        file - the file that the member represents

    • Method Detail

      • getParent

        public final Member getParent()
        Returns the member that is this member's parent, or null if this is the member representing the Project (or if it was explicitly created with a null parent).
        Returns:
        this member's parent, or null

      • getTask

        public final Task getTask()
        Returns the Task this member belongs to. Returns this member if it is a task or project. If the member is in a project but not in a task folder, the Project is returned.

        In the event that the member is not actually in a project, returns null (this is only possible when a member is explicitly created with a null parent).

        Returns:
        the task that owns this member

      • getProject

        public final Project getProject()
        Returns the Project this member belongs to.

        In the event that the member is not actually in a project, returns null (this is only possible when a member is explicitly created with a null parent).

        Returns:
        the project that owns this member

      • getFile

        public final java.io.File getFile()
        Returns the file represented by this project member. The result will never be null, although the returned file may not exist if changes have been made to the filesystem that have not yet been detected by the project system.
        Returns:
        the file that this project member refers to
        See Also:
        synchronize()

      • getURL

        public java.net.URL getURL()
        Returns a project: URL that can be used to access this member whenever this project is the main open project. Returns null if the file has been deleted.
        Returns:
        a project URL for the file.

      • getName

        public java.lang.String getName()
        Returns the name of this project member. Typically, this is the same as the name of the corresponding file, including any file name extensions.
        Returns:
        the name of this project member

      • getBaseName

        public java.lang.String getBaseName()
        Returns the base file name of this project member. The base file name is the same as the file name, less the file name extension and accompanying dot (if any). For example, the base name of "image.png" is "image".
        Returns:
        the base name of the file
        See Also:
        getName(), getExtension()

      • getExtension

        public java.lang.String getExtension()
        Returns the file name extension of this project member. File name extensions are commonly used to deduce the type of a file. They are the portion of the file's name that falls after a dot character ('.'). For example, if the file name is "image.png", then the returned extension is "png". If the file name has multiple extensions, only the final extension is returned. For example, if the file name is "archive.tar.gz", then this method would return "gz" as the extension. If the file name does not include a dot, then an empty string is returned to indicate that the file name has no extension. Note that this means that the method returns the same extension for files with no extension as it does for files that end in a dot character.
        Returns:
        the file name extension, or an empty string
        See Also:
        getName(), getBaseName()

      • getIcon

        public ThemedIcon getIcon()
        Returns an icon that is appropriate for this member. This is essentially a cover method for getMetadataSource().getIcon( this ).
        Specified by:
        getIcon in interface IconProvider
        Returns:
        an icon for this member

      • isFolder

        public boolean isFolder()
        Returns true if this member is a folder rather than a file. (All Tasks and Projects are also folders.)
        Returns:
        true if this member represents a folder rather than a regular file
        See Also:
        hasChildren()

      • hasChildren

        public boolean hasChildren()
        Returns true if this member has children.
        Returns:
        true if the member has any children; false otherwise

      • getChildCount

        public int getChildCount()
        Returns the number of children that this member has (possibly zero).
        Returns:
        the number of direct child members that this member has

      • getChildAt

        public Member getChildAt​(int childIndex)
        Returns the child member at the specified index. The index must be from 0 to getChildCount()-1, inclusive.
        Parameters:
        childIndex - the index of the child being requested
        Returns:
        the child at the requested index
        Throws:
        java.lang.IndexOutOfBoundsException - if childIndex < 0 or childIndex >= getChildCount()

      • getChildren

        public Member[] getChildren()
        Returns the children of this member as an array. Excluded and hidden files will not be listed as children of the member (see setExcludedFilePatterns(java.lang.String[]) for more information).
        Returns:
        an array of this member's children, or an empty array if this is not a folder

      • iterator

        public java.util.Iterator<Member> iterator()
        Returns an iterator over this member's children. The returned iterator does not support the remove operation.
        Specified by:
        iterator in interface java.lang.Iterable<Member>
        Returns:
        an iterator that iterates over all of this member's children

      • findChild

        public Member findChild​(java.io.File file)
        Returns the child of this member whose file is equal to the specified file, or null if there is no such child. The file must be an immediate child of this child, not simply a descendant.
        Parameters:
        file - the child to find
        Returns:
        the child that represents the specified file, or null
        See Also:
        findChild(java.lang.String)

      • findChild

        public Member findChild​(java.lang.String name)
        Finds a child of this member by name. Returns null if there is no such child. If the specified name contains one or more slashes ('/'), then the find operation will be repeated recursively for each path segment. For example, findChild( "nested/folder/file.png" ) is equivalent to calling findChild( "nested" ).findChild( "folder" ).findChild( "file.png" ), except that if any of the calls returns null, the process stops immediately and the method returns null.
        Parameters:
        name - the member name to search for
        Returns:
        the child with this name, or null

      • getIndex

        public int getIndex​(Member potentialChild)
        Returns the index at which the specified member can be found as a child of this member. If the specified member is not a child of this member, returns -1.
        Parameters:
        potentialChild - the member to search for
        Returns:
        the index of the specified member in the immediate children of this member, or null
        See Also:
        getChildAt(int), findChild(java.lang.String)

      • renameFile

        public void renameFile​(java.lang.String newFileName)
                throws java.io.IOException
        Renames the file associated with this member. Calling this method is preferable to calling getFile().renameTo because this method correctly handles additional details and special cases that the File method is unaware of, such as updating any editors displaying the file and informing RenameListeners.
        Parameters:
        newFileName - the new name for the member
        Throws:
        java.io.IOException - if an I/O error occurs during renaming

      • deleteFile

        public void deleteFile()
                throws java.io.IOException
        Deletes the file associated with this member. If this member is a folder, then any children it may have will also be deleted. Calling this method is preferable to calling getFile().delete() because this method correctly handles additional details and special cases that the File method is unaware of, such as updating any editors displaying the file and informing RenameListeners.
        Throws:
        java.io.IOException - if an I/O error prevents the file from being deleted
        See Also:
        ProjectUtilities.deleteAll(java.io.File)

      • setExcludedFilePatterns

        public static void setExcludedFilePatterns​(java.lang.String... patterns)
        Sets a list of file name patterns that will be ignored by the project system. Any file name that matches one of the specified patterns will be ignored. It will not be returned as one of the children of its parent member and it will not appear in project views. Each pattern in the array is a string (empty or null strings in the array will be ignored). The patterns can either specify an exact name to match or they can include wildcards: the * wildcard matches 0 or more characters, while the ? wildcard matches any one character. For example, the pattern "*.gif" would exclude all files ending in ".gif". File patterns are case insensitive: in the previous example, a file named "SAMPLE.GIF" would also be excluded.

        Excluded versus Hidden:
        When a member's children are requested, files that are excluded or hidden are not listed. The difference is that excluded files (files that match one of the excluded patterns set with this method) are not considered to be part of the project at all, while hidden files are parts of the project that are not shown to the user. For example, task folders include a configuration file that is hidden so that it does not appear in the project view, but the configuration file is still part of the project (it is required for the project to function correctly!). Files that start with a '.' or that are considered hidden by the operating system (on Windows, files have a "hidden" attribute that can be set hide the file) are also considered hidden by projects.

        Most of the time there is no practical difference between hidden or excluded files for plug-in authors. The main exception is that if you are copying project files from one place to another, you should leave out excluded files but copy hidden files. To do this, you could get a list of files from the parent member using member.getFile().listFiles(), then skip any files for which isFileExcluded(java.io.File) returns true.

        Parameters:
        patterns - an array of pattern strings
        See Also:
        getExcludedFilePatterns(), isFileExcluded(java.io.File)

      • getExcludedFilePatterns

        public static java.lang.String[] getExcludedFilePatterns()
        Returns an array containing the file name patterns that will be ignored by the project system.
        Returns:
        a copy of the patterns that will be ignored by the project system
        See Also:
        setExcludedFilePatterns(java.lang.String...)

      • isFileExcluded

        public static boolean isFileExcluded​(java.io.File f)
        Returns true if file exclusion patterns have been set and f matches one of the patterns.
        Parameters:
        f - the file to test
        Returns:
        true if the file matches an active exclusion pattern

      • compareTo

        public int compareTo​(Member rhs)
        Compares two project members. This method is designed to sort members in the same folder into a nice order for display. It is not intended for general comparison of arbitrary project members.
        Specified by:
        compareTo in interface java.lang.Comparable<Member>
        Parameters:
        rhs - the member to compare this member to
        Returns:
        a negative number, zero, or a positive number indicating whether this member should be displayed before, at the same position as, or after the specified member

      • equals

        public boolean equals​(java.lang.Object obj)
        Returns true if and only if the specified object is a project member for the same file as this project member.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        obj - the object to compare this object to
        Returns:
        if the object is a member for the same underlying file

      • hashCode

        public int hashCode()
        Returns a hash code for this member.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        a hash code

      • toString

        public java.lang.String toString()
        Returns the project member's base name.
        Overrides:
        toString in class java.lang.Object
        Returns:
        the member's base name
        See Also:
        getBaseName()

      • synchronize

        public void synchronize()
        Hints to the project that this is a good time to update this node's children to reflect changes to the file system. This method is typically called after creating, deleting, or updating a number of this member's children.

        Projects monitor their members for changes. For example, a folder in a project will detect when a new file has been added to it and update its children accordingly. However, there is typically a short delay before such changes will be reflected in the project view. The exact delay is platform dependent, but it is typically between 100-5000 ms. This delay allows changes to the project structure to be made in bulk when a large number of files are being updated. Calling this method is suggests two things to the project system: that the contents of this node have been modified, and that now is a good time to resynchronize the project's member tree with the actual files on disk. Thus, calling this method is entirely optional, but it may make the project view appear more responsive.

        Note: If you write files to a project folder from a thread other than the event dispatch thread, you can safely update the project from that thread by calling this method. However, it is not safe in general to work with project members from outside of the EDT. Instead, keep a reference to the member that requires updating, and work only with File objects within the other thread (except for calling this method).

      • isAncestorOf

        public boolean isAncestorOf​(Member child)
        Returns true if this is an ancestor of child.
        Parameters:
        child - the member to test
        Returns:
        true if and only if child is a direct or indirect child of this member

      • getMetadataSource

        public MetadataSource getMetadataSource()
        Returns a MetadataSource that is appropriate for fetching metadata for a file of the type represented by this member.
        Returns:
        the metadata source that is best suited for this member

      • registerMetadataSource

        public static void registerMetadataSource​(MetadataSource source)
        Adds a new source of metadata. Sources are always checked in most recent first order. The first source that applies to a given member will be returned as its source. Note, however, that sources can be cached. After adding a new source to a live project, synchronize relevant members to clear any cached sources.
        Parameters:
        source - the source to add

      • unregisterMetadataSource

        public static void unregisterMetadataSource​(MetadataSource source)
        Removes a previously registered source of metadata.
        Parameters:
        source - the source to remove