Package ca.cgjennings.apps.arkham.project

Class ProjectUtilities

  • public class ProjectUtilities
extends java.lang.Object
    Helper methods that are useful when writing TaskActions and other project-related classes and scripts. The file and stream copying methods are threadsafe.
    Since:
    3.0
    Author:
    Chris Jennings

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static java.io.File changeExtension​(java.io.File f, java.lang.String newExtension)
      Returns a new file with the same name and path as f except that it will have the extension newExtension.
      static boolean contains​(java.io.File container, java.io.File possibleChild)
      Returns true if the possibleChild has container as an ancestor.
      static void copyFile​(java.io.File original, java.io.File copy)
      Copy a file.
      static void copyFile​(java.io.File original, java.io.OutputStream out)
      Copy the content of a file to an output stream.
      static void copyFolder​(java.io.File original, java.io.File parent)
      Recursively copy a file or folder into a folder.
      static void copyReader​(java.io.Reader in, java.io.File out)
      Copy the content of a reader to a file using the ISO-8859-15 encoding.
      static void copyReader​(java.io.Reader in, java.io.File out, java.lang.String enc)
      Copy the content of a reader to a file using a specified encoding.
      static void copyReader​(java.io.Reader in, java.io.Writer out)
      Copy the content of a reader to a writer.
      static void copyResourceToFile​(java.lang.String resource, java.io.File copy)
      Copy the content from a file stored in the application resources to a file.
      static void copyStream​(java.io.InputStream in, java.io.File out)
      Copy the content of an input stream to a file.
      static void copyStream​(java.io.InputStream in, java.io.OutputStream out)
      Copy the content of an input stream to an output stream.
      static void copyToArchive​(java.util.zip.ZipOutputStream out, java.io.File baseFile, java.lang.String baseZIPEntry, boolean recurse, boolean filterFiles, boolean compress)
      Copy one or more files into an archive.
      static java.util.zip.ZipOutputStream createPluginBundleArchive​(java.io.File archive, boolean webSafe)
      This is a convenience method that creates a plug-in bundle archive that will be written to a file.
      static java.util.zip.ZipOutputStream createPluginBundleArchive​(java.io.OutputStream out, boolean webSafe)
      Create a ZIP output stream for writing a plug-in bundle or ZIP archive.
      static boolean deleteAll​(java.io.File target)
      Deletes a file or folder and all of its contents, if possible.
      static int exec​(java.lang.String... commandArray)
      Executes a shell command on the local system.
      static void execAsync​(java.lang.String... commandArray)
      Executes a shell command on the local system.
      static java.lang.String formatByteSize​(long size)
      Returns a localized string that describes a file size (or other measurement in bytes).
      static java.io.File getAvailableFile​(java.io.File preferred)
      Returns the preferred file name if it is not in use, otherwise generates a numbered variant of the name that does not already exist at the time the method is called.
      static java.lang.String getFileAsString​(java.io.File f, java.lang.String enc)
      Returns the contents of a file as a string.
      static java.lang.String getFileExtension​(java.io.File f)
      Returns a file's extension as a lowercase string.
      static java.lang.String getFileText​(java.io.File f, java.lang.String enc)
      Return the complete text of a file as a string.
      static java.lang.String getResourceText​(java.lang.String resource)
      Returns the contents of a text file stored in resources as a string, or null if there is no such resource.
      static java.lang.String getResourceText​(java.lang.String resource, java.lang.String encoding)
      Returns the contents of a text file stored in resources as a string, or null if there is no such resource.
      static java.util.List<Member> listMatchingMembers​(Member parent, boolean recurse, java.lang.String... extensions)  
      static java.io.File makeFileRelativeTo​(java.io.File baseFile, java.io.File fileToMakeRelative)
      Tries to make a file relative to another base file.
      static boolean matchExtension​(Member m, java.lang.String extension)  
      static boolean matchExtension​(Member m, java.lang.String... extensions)  
      static boolean matchExtension​(java.io.File f, java.lang.String extension)  
      static boolean matchExtension​(java.io.File f, java.lang.String... extensions)
      Matches a file against a list of file extensions.
      static Member[] merge​(Member[] members)
      Simplify an array of non-null members, if possible, by eliminating duplicates and keeping only the ancestor if an ancestor and a descendent both occur.
      static void moveFile​(java.io.File source, java.io.File dest)
      Moves a file.
      static java.lang.Object runScript​(java.io.File script)
      Runs a script whose source text is stored in a file.
      static java.lang.Object runScript​(java.io.File script, Project project, Task task, Member member, boolean debug)
      Runs a script whose source text is stored in a file.
      static java.lang.Object runScript​(java.lang.String scriptName, java.lang.String script)
      Runs a script file.
      static java.lang.Object runScript​(java.lang.String scriptName, java.lang.String script, Project project, Task task, Member member, boolean debug)
      Runs a script whose source text is stored in a string.
      static boolean sameFile​(java.io.File a, java.io.File b)
      Check carefully whether two file objects refer to the same file in the file system.
      static void saveAllOpenProjectFiles​(boolean closeAfterSave)
      Tries to save every open editor that is a member of the current project.
      static void saveIfBeingEdited​(java.io.File f)
      If there is a support editor that is being used to edit this file, and the editor supports the Save command, and the editor has unsaved changes, the editor will be asked to save the file.
      static Member simplify​(Project project, Task task, Member member)
      Simplifies a description of the target of an action.
      static void writeTextFile​(java.io.File file, java.lang.String text)
      Creates a file that contains the given text in the UTF-8 encoding.
      static void writeTextFile​(java.io.File file, java.lang.String text, java.lang.String enc)
      Creates a file that contains the given text.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • ENC_SETTINGS

        public static final java.lang.String ENC_SETTINGS
        The encoding used to store settings files.
        See Also:
        Constant Field Values

      • ENC_SCRIPT

        public static final java.lang.String ENC_SCRIPT
        The encoding used to store script files (UTF-8).
        See Also:
        Constant Field Values

      • ENC_UI_PROPERTIES

        public static final java.lang.String ENC_UI_PROPERTIES
        The encoding used to store properties (UI text).
        See Also:
        Constant Field Values

      • ENC_UTF8

        public static final java.lang.String ENC_UTF8
        The UTF-8 encoding.
        See Also:
        Constant Field Values

    • Method Detail

      • simplify

        public static Member simplify​(Project project,
                              Task task,
                              Member member)
        Simplifies a description of the target of an action. Actions are asked whether they apply to a member, along with its task and project. When a task is selected, the member will be null. Likewise, then a project is selected, the task will also be null. If a TaskAction does not wish to alter its behaviour when applied to these different member types, it can call this method to collapse these three parameters to a single value, the selected member (no matter the type).
        Parameters:
        project - the project
        task - the task within the project, or null
        member - the member within the task, or null
        Returns:
        the rightmost non-null parameter, or null if all parameters are null

      • merge

        public static Member[] merge​(Member[] members)
        Simplify an array of non-null members, if possible, by eliminating duplicates and keeping only the ancestor if an ancestor and a descendent both occur. Given the following members: 
         Fred
 Martha
 Martha/Sarah
 Martha/Sarah/Abby
 Fred
 Martha/Jane
 George
 Jim/Ralph
        a merged version would consist of: 
         Fred
 Martha
 George
 Jim/Ralph
        The order of elements in members is maintained in the merged result.
        Parameters:
        members - an array of members to merge
        Returns:
        the merged members, or the original array if merging does not reduce the number of elements

      • deleteAll

        public static boolean deleteAll​(java.io.File target)
        Deletes a file or folder and all of its contents, if possible. Note that if the deletion fails, and the file is a folder, some of the files or folders it contains may have been deleted before the failure occurred.

        This method can be used to safely delete both regular files and project files. It will detect whether any file it should delete is a member of the open project, and hand such files off to Member.deleteFile() for safe deletion.

        Since this method deletes files recursively, the caller should be doubly sure that the specified file is correct. As a precaution, the method will throw an exception if asked to delete the root folder of a file system.

        Parameters:
        target - the file to delete
        Returns:
        true if all of the files were successfully deleted
        Throws:
        java.lang.NullPointerException - if the target is null
        java.lang.IllegalArgumentException - if the specified file is a file system root (such as C: on windows or / on UNIX).

      • copyFolder

        public static void copyFolder​(java.io.File original,
                              java.io.File parent)
                       throws java.io.IOException
        Recursively copy a file or folder into a folder.
        Parameters:
        original - a file or folder to copy
        parent - the parent directory where that should contain the copy
        Throws:
        java.lang.IllegalArgumentException - if parent is not a folder
        java.io.IOException - if an exception occurs while copying

      • copyFile

        public static void copyFile​(java.io.File original,
                            java.io.File copy)
                     throws java.io.IOException
        Copy a file. This is not recursive, and should not be used to copy folders. The file attributes of the source file will also be copied, if possible.
        Parameters:
        original - the file to copy
        copy - the destination to copy to
        Throws:
        java.io.IOException - if an I/O error occurs during the copy

      • moveFile

        public static void moveFile​(java.io.File source,
                            java.io.File dest)
                     throws java.io.IOException
        Moves a file. This is not recursive and should not be used to move folders.
        Parameters:
        source - the file to move
        dest - the destination (including the file name part)
        Throws:
        java.io.IOException - if an I/O error occurs during the move

      • sameFile

        public static boolean sameFile​(java.io.File a,
                               java.io.File b)
        Check carefully whether two file objects refer to the same file in the file system.
        Parameters:
        a - the first file to consider
        b - the second file to consider
        Returns:
        true if a and b are determined to be the same file

      • copyFile

        public static void copyFile​(java.io.File original,
                            java.io.OutputStream out)
                     throws java.io.IOException
        Copy the content of a file to an output stream.
        Parameters:
        original -
        out -
        Throws:
        java.io.IOException

      • copyResourceToFile

        public static void copyResourceToFile​(java.lang.String resource,
                                      java.io.File copy)
                               throws java.io.IOException
        Copy the content from a file stored in the application resources to a file.
        Parameters:
        resource - the path to the resource file
        copy - the file to copy the resource content to
        Throws:
        java.io.IOException - if the file cannot be copied

      • copyStream

        public static void copyStream​(java.io.InputStream in,
                              java.io.OutputStream out)
                       throws java.io.IOException
        Copy the content of an input stream to an output stream.
        Parameters:
        in -
        out -
        Throws:
        java.io.IOException

      • copyStream

        public static void copyStream​(java.io.InputStream in,
                              java.io.File out)
                       throws java.io.IOException
        Copy the content of an input stream to a file.
        Parameters:
        in -
        out -
        Throws:
        java.io.IOException

      • getFileText

        public static java.lang.String getFileText​(java.io.File f,
                                           java.lang.String enc)
                                    throws java.io.IOException
        Return the complete text of a file as a string.
        Parameters:
        f -
        enc - the encoding, e.g., ENC_UTF8
        Returns:
        the text of the file
        Throws:
        java.io.IOException

      • copyReader

        public static void copyReader​(java.io.Reader in,
                              java.io.Writer out)
                       throws java.io.IOException
        Copy the content of a reader to a writer.
        Parameters:
        in -
        out -
        Throws:
        java.io.IOException

      • copyReader

        public static void copyReader​(java.io.Reader in,
                              java.io.File out)
                       throws java.io.IOException
        Copy the content of a reader to a file using the ISO-8859-15 encoding. Specifying an encoding explicitly is recommended.
        Parameters:
        in -
        out -
        Throws:
        java.io.IOException

      • copyReader

        public static void copyReader​(java.io.Reader in,
                              java.io.File out,
                              java.lang.String enc)
                       throws java.io.IOException
        Copy the content of a reader to a file using a specified encoding.
        Parameters:
        in -
        out -
        enc - the encoding method used to write the text
        Throws:
        java.io.IOException

      • createPluginBundleArchive

        public static java.util.zip.ZipOutputStream createPluginBundleArchive​(java.io.OutputStream out,
                                                                      boolean webSafe)
                                                               throws java.io.IOException
        Create a ZIP output stream for writing a plug-in bundle or ZIP archive. In order to be a valid plug-in bundle, a valid eons-plugin file must be written into the archive's root folder. If webSafe is false and the archive contains no eons-plugin file, then the result will be a plain ZIP file that can be used to create a portable archive for other purposes.
        Parameters:
        out - the stream to write the archive to
        webSafe - if true, a Web-safe bundle archive is created (do not use if creating a plain ZIP archive)
        Returns:
        the archive stream to write file data to
        Throws:
        java.io.IOException - if an I/O error occurs while creating the archive stream

      • createPluginBundleArchive

        public static java.util.zip.ZipOutputStream createPluginBundleArchive​(java.io.File archive,
                                                                      boolean webSafe)
                                                               throws java.io.IOException
        This is a convenience method that creates a plug-in bundle archive that will be written to a file.
        Parameters:
        archive - the path to the file that the archive will be written to
        webSafe - if true, a Web-safe bundle archive is created (do not use if creating a plain ZIP archive)
        Returns:
        the archive stream to write file data to
        Throws:
        java.io.IOException - if an I/O error occurs while creating the archive stream
        See Also:
        createPluginBundleArchive(java.io.OutputStream, boolean)

      • copyToArchive

        public static void copyToArchive​(java.util.zip.ZipOutputStream out,
                                 java.io.File baseFile,
                                 java.lang.String baseZIPEntry,
                                 boolean recurse,
                                 boolean filterFiles,
                                 boolean compress)
                          throws java.io.IOException
        Copy one or more files into an archive.
        Parameters:
        out - the archive stream to copy to
        baseFile - the source file to be copied
        baseZIPEntry - the folder name to use as the file's parent in the archive
        recurse - if true, recursively copy all children of baseFile (if any) into the archive
        filterFiles - if files that match the excluded project file list should be ignored
        Throws:
        java.io.IOException - if an I/O error occurs while reading the source file or writing to the archive

      • contains

        public static boolean contains​(java.io.File container,
                               java.io.File possibleChild)
        Returns true if the possibleChild has container as an ancestor. Returns true if the two files are equal. If either file is null, returns false.
        Parameters:
        container - the parent file that may contain possibleChild
        possibleChild - the file to test
        Returns:
        true if and only if both files are non-null and container is a parent of possibleChild

      • getAvailableFile

        public static java.io.File getAvailableFile​(java.io.File preferred)
        Returns the preferred file name if it is not in use, otherwise generates a numbered variant of the name that does not already exist at the time the method is called. A typical use is to create an alternative target file if the target of a copy operation already exists.
        Parameters:
        preferred - the ideal file that should be used if it is available (does not exist)
        Returns:
        either the preferred file or an available variant

      • getFileExtension

        public static java.lang.String getFileExtension​(java.io.File f)
        Returns a file's extension as a lowercase string. If the file has no extension, an empty string is returned. A file's extension consists of the suffix starting after its final period (.) character. Given a file with the name myPony.pony.Zip, this method returns zip as the file extension. Extensions are a fairly reliable cross-platform mechanism for identifying the content type of a file.
        Parameters:
        f - the file whose file name extension is desired
        Returns:
        the lowercase file extension of the file's name

      • matchExtension

        public static boolean matchExtension​(java.io.File f,
                                     java.lang.String... extensions)
        Matches a file against a list of file extensions. If the file is not a folder and it's file name matches any of the extensions, then this method returns true, otherwise false. The list of extensions should be one or more lowercase strings, each of which is a file extension without a '.' (e.g., png, eon, xml, etc.). Note that the file does not need to exist in order to be matched by this function, but if it does exist, it must not be a folder.
        Parameters:
        f - the file to be tested
        extensions - the candidate file extensions to be tested against
        Returns:
        true if f is not a folder and its name matches any of the given extensions

      • matchExtension

        public static boolean matchExtension​(java.io.File f,
                                     java.lang.String extension)

      • matchExtension

        public static boolean matchExtension​(Member m,
                                     java.lang.String... extensions)

      • matchExtension

        public static boolean matchExtension​(Member m,
                                     java.lang.String extension)

      • changeExtension

        public static java.io.File changeExtension​(java.io.File f,
                                           java.lang.String newExtension)
        Returns a new file with the same name and path as f except that it will have the extension newExtension. If the name did not have an extension previously, a period and the new extension are appended. Otherwise, the last extension in the name is removed and the new extension appended to replace it. If the original file has a parent path, the new file will have the same parent.
        Parameters:
        f - the original file
        newExtension - the extension to use, null to remove the extension
        Returns:
        a file with the same base name but a different extension

      • makeFileRelativeTo

        public static java.io.File makeFileRelativeTo​(java.io.File baseFile,
                                              java.io.File fileToMakeRelative)
        Tries to make a file relative to another base file. If this is possible, the relative file is returned. Otherwise, the original file that was to be made relative is returned. If either file is relative, it will be made absolute first (using the current directory).
        Parameters:
        baseFile - the file that the returned file is relative to
        fileToMakeRelative - the file that the returned file will point to when resolved against the base file
        Returns:
        the location of the second file, relative to the first
        Throws:
        java.lang.IllegalArgumentException - if the paths in either of the parameters are not valid local paths

      • formatByteSize

        public static java.lang.String formatByteSize​(long size)
        Returns a localized string that describes a file size (or other measurement in bytes).

      • getResourceText

        public static java.lang.String getResourceText​(java.lang.String resource,
                                               java.lang.String encoding)
                                        throws java.io.IOException
        Returns the contents of a text file stored in resources as a string, or null if there is no such resource.
        Parameters:
        resource - the path to the resource file to read
        encoding - the text encoding, or null to use the default (ISO-8859-15)
        Returns:
        the text content of the file
        Throws:
        java.io.IOException - if an I/O error occurs while reading the resource

      • getResourceText

        public static java.lang.String getResourceText​(java.lang.String resource)
                                        throws java.io.IOException
        Returns the contents of a text file stored in resources as a string, or null if there is no such resource. The text must be encoded in UTF-8.
        Parameters:
        resource - the path to the resource file to read
        Returns:
        the text content of the file
        Throws:
        java.io.IOException - if an I/O error occurs while reading the resource

      • writeTextFile

        public static void writeTextFile​(java.io.File file,
                                 java.lang.String text)
                          throws java.io.IOException
        Creates a file that contains the given text in the UTF-8 encoding.
        Parameters:
        file - the file to write to
        text - the text to write to the file
        Throws:
        java.io.IOException - if an error occurs while writing the text

      • writeTextFile

        public static void writeTextFile​(java.io.File file,
                                 java.lang.String text,
                                 java.lang.String enc)
                          throws java.io.IOException
        Creates a file that contains the given text.
        Parameters:
        file - the file to write to
        text - the text to write to the file
        enc - the encoding to use
        Throws:
        java.io.IOException - if an error occurs while writing the text

      • getFileAsString

        public static java.lang.String getFileAsString​(java.io.File f,
                                               java.lang.String enc)
                                        throws java.io.IOException
        Returns the contents of a file as a string.
        Parameters:
        f - the file to read
        enc - the character encoding of the file
        Returns:
        the contents of the file as a string
        Throws:
        java.io.IOException - if an I/O errors while reading the file

      • runScript

        public static java.lang.Object runScript​(java.io.File script)
                                  throws java.io.IOException
        Runs a script whose source text is stored in a file. This is a cover for runScript( script, null, null, null, false ).
        Parameters:
        script - the file that contains the source text to execute
        Returns:
        the script's return value; typically the value of the last executed statement
        Throws:
        java.io.IOException - if an I/O error occurs while reading the script

      • runScript

        public static java.lang.Object runScript​(java.lang.String scriptName,
                                         java.lang.String script)
        Runs a script file. This is a cover for runScript( scriptName, script, null, null, null, false ).
        Parameters:
        scriptName - the source file name to be used to identify the script
        script - the source code of the script
        Returns:
        the script's return value; typically the value of the last executed statement

      • runScript

        public static java.lang.Object runScript​(java.io.File script,
                                         Project project,
                                         Task task,
                                         Member member,
                                         boolean debug)
                                  throws java.io.IOException
        Runs a script whose source text is stored in a file. The script's return value, if any, is returned by this method. In the script, the variables project, task, and member will be bound to the values passed to this method. The script will be provided with a default PluginContext that is not associated with any plug-in.
        Parameters:
        script - the file that contains the source text to execute
        project - the project associated with the script, or null
        task - the task associated with the script, or null
        member - the project member associated with the script, or null
        debug - if true, the script will be executed in debug mode if possible
        Returns:
        the script's return value; typically the value of the last executed statement
        Throws:
        java.io.IOException - if an I/O error occurs while reading the script

      • runScript

        public static java.lang.Object runScript​(java.lang.String scriptName,
                                         java.lang.String script,
                                         Project project,
                                         Task task,
                                         Member member,
                                         boolean debug)
        Runs a script whose source text is stored in a string. The script's return value, if any, is returned by this method. In the script, the variables project, task, and member will be bound to the values passed to this method. The script will be provided with a default PluginContext that is not associated with any plug-in.
        Parameters:
        scriptName - the source file name to be used to identify the script
        script - the source code of the script
        project - the project associated with the script, or null
        task - the task associated with the script, or null
        member - the project member associated with the script, or null
        debug - if true, the script will be executed in debug mode if possible
        Returns:
        the script's return value; typically the value of the last executed statement

      • exec

        public static int exec​(java.lang.String... commandArray)
        Executes a shell command on the local system. The first string passed in is the command name, and each subsequent string is an argument to pass to the command. This method will not return until the command completes, and any output from the command will appear in the script console.
        Parameters:
        commandArray - the command and arguments to use
        Returns:
        the exit code from the command, or -1 if this thread was interrupted while waiting for the command to finish
        Throws:
        java.lang.NullPointerException - if the command array is null
        java.lang.IllegalArgumentException - if the command array is empty

      • execAsync

        public static void execAsync​(java.lang.String... commandArray)
        Executes a shell command on the local system. The first string passed in is the command name, and each subsequent string is an argument to pass to the command. Any output from the command will appear in the script console. This method will return immediately; the command will run in the background.
        Parameters:
        commandArray - the command and arguments to use
        Throws:
        java.lang.NullPointerException - if the command array is null
        java.lang.IllegalArgumentException - if the command array is empty
        Since:
        3.2

      • saveIfBeingEdited

        public static void saveIfBeingEdited​(java.io.File f)
        If there is a support editor that is being used to edit this file, and the editor supports the Save command, and the editor has unsaved changes, the editor will be asked to save the file.
        Parameters:
        f - the file that, if open in an editor, will be saved

      • saveAllOpenProjectFiles

        public static void saveAllOpenProjectFiles​(boolean closeAfterSave)
        Tries to save every open editor that is a member of the current project.
        Parameters:
        closeAfterSave - if true, each file is closed after being saved

      • listMatchingMembers

        public static java.util.List<Member> listMatchingMembers​(Member parent,
                                                         boolean recurse,
                                                         java.lang.String... extensions)