Class JarInclude

  • public class JarInclude
extends java.lang.Object
    This is a very light-weight class, and has as its primary-operation / primary-feature the ability to allow a user to request that additional files be automatically inserted into the '.jar'-File that's generated by this Build-Tool. There are several "goals" that are acheived during a Build using this Tool, one of which includes creating a '.jar' file containing the Java-Packages that have been specified to the class Config.

    Specifying a list of Java-Packages (using the Configuration-Class BuildPackage) guarantees that all of the required '.class'-Files are properly inserted into your '.jar'. Often, however, there may be other files that need to be inserted into the 'META-INF/' directory inside that '.jar'-File in order for services and API's to work properly. By instantiating an instance of class JarInclude, one may specify a list of as many non-class-file related files that also have to be inserted into your '.jar'-File during the build.

    The Build-Tool that you see here (Torello.Java.Build) is, indeed, the Tool used to generate the Documentation, Tar's and Jar's for the Java-HTML Jar-Library. This is in fact a "Self-Building Build Tool". The Source-Code Snippet included below will hopefully clarify and specify exactly how the class 'JarInclude' is used to insert additional files into a '.jar' so that exported API's properly work.

    Here is a method from the (non-public, non-visible) build source for Java-HTML:

    Example:
     public static JarInclude getJarIncludes()
 {
     // RTF: Return-True-Filter
     final FileNodeFilter RTF = (FileNode fn) -> true;
 
     return new JarInclude()
          // The first one contains the list of annotation processors.  The file is named:
          // Torello/BuildJAR/IncludeFiles/META-INF/services/javax.annotation.processing.Processor
 
          .add("Torello/BuildJAR/IncludeFiles/", "META-INF/", true, RTF, RTF)
 
          // This one is provided by the Glass-Fish JSON Provider.  It is named:
          // Torello/etc/External/META-INF/services/javax.json.spi.JsonProvider
 
          .add("Torello/etc/External/", "META-INF/", true, RTF, RTF);
 }

    The above files will be automatically added into the Archive that's created in the Stage 4 Build-Process / Build-Step. The first file listed helps the Java-Doc Upgrader's Annotaton Processors to work properly. The second file listed is needed to ensure that the Glass-Fish JSON-Processor included in this '.jar'-File works.

    And that, by the way, is all folks! That is all 'JarInclude' does. If you have such files which need to be inserted, then:

    • Create an instance of 'JarInclude' using this class' constructor.

    • Register your instance of 'JarInclude' with the Configuration-Class Config. You may do this, simply, by assigning the instance / reference of this class to the 'Config' class Configuration-Field, which is simply named: Config.jarIncludes.

    • When you obtain a BuilderRecord instance from Config, it wil automatically add your files as soon as your invoke RunBuild.run(BuilderRecord).
    See Also:
    Config.jarIncludes, Config.createBuilder(String[]), RunBuild.run(BuilderRecord)


    • Constructor Summary

      Constructors 
      Constructor Description
      JarInclude()
      Build an instance of this class

    • Method Summary

       
      Request that a Directory or Directory-Tree be added to the '.jar'
      Modifier and Type Method
      JarInclude add​(String workingDirectory, String subDirectory, boolean traverseTree, FileNodeFilter fileFilter, FileNodeFilter dirFilter)
      JarInclude add​(String workingDirectory, String subDirectory, FileNodeFilter fileFilter)

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • add

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public JarInclude add​(java.lang.String workingDirectory,
                      java.lang.String subDirectory,
                      boolean traverseTree,
                      FileNodeFilter fileFilter,
                      FileNodeFilter dirFilter)
        Inserts a request for files to be included in the Tar-Jar Build Stage (Stage 4).
        Parameters:
        workingDirectory - When files are added to a '.jar'-File, the "Working Directory" part of the File-System Path is not included in the name of the files that are inserted.
        subDirectory - The "Sub-Directory" part of the File-System Path is included into the names of any and all files that are inserted in the '.jar'.
        traverseTree - Indicates whether the the String-Parameter 'subDirectory' should be interpreted as a directory-name - or as an entire tree branch whose own sub-directories should be traversed by the file-scanner.
        fileFilter - A filter / "chooser" / specifier for deciding which files residing on the File-System inside 'subDirectory' (or 'subDirectory', and its own sub-directories - in the case that 'traverseTree' was passed TRUE), are to be included in the '.jar'.

        This filter must return TRUE if a file this filter is testing should be inserted into the '.jar', and FALSE, if the file should not be.

        This parameter may be passed null, and if it is it will be quietly ignored. When this filter is null, all files that reside within 'subDirectory' will be inserted into the '.jar'-File.

        If this parameter were passed null, and 'traverseTree' were passed TRUE, then all files inside of 'subDirectory' would be inserted into the '.jar' - and furthermore, all files in all sub-directories of 'subDirectory' would also be inserted.
        dirFilter - This filter can only be employed if 'traverseTree' has been passed TRUE.

        When 'traverseTree' is TRUE as the directory tree rooted at workingDirectory/subDirectory/ is traversed, each sub-directory that is encountered will be passed to this filter. When this test is performed, the filter should return TRUE to indicate that it would like a particular sub-directory searched, and FALSE to indicate that it must be skipped.

        This parameter may be passed null, and if it is it will be silently ignored. If this parameter is null, and 'traverseTree' is TRUE, all sub-directories of workingDirectory/subDirectory/ will be entered / traversed.

        NOTE: If this parameter is passed a non-null filter, but 'traverseTree' has been passed FALSE, then an IllegalArgumentException will throw. Parameter 'dirFilter' has no use or application if the named directory-tree is not going to be traversed!
        Returns:
        'this' instance, for convenience and invocation-chaining.
        Throws:
        java.lang.NullPointerException - If either 'workingDirectory' or 'subDirectory' is passed null.
        java.lang.IllegalArgumentException - If either 'workingDirectory' or 'subDirectory' do not name real directories that actually exist on the File-System.

        This exception will also throw if 'traverseTree' is passed FALSE but 'dirFilter' is non-null.
        Code:
        Exact Method Body:
         File f;

 Objects.requireNonNull(workingDirectory, M1 + "workingDirectory" + M2);
 Objects.requireNonNull(subDirectory, M1 + "subDirectory" + M2);

 if (workingDirectory.length() > 0)
 {
     f = new File(workingDirectory);

     if (! f.exists()) throw new IllegalArgumentException(
         "The directory-name provided to parameter 'workingDirectory' does not exist on " +
         "the File-System:\n[" + workingDirectory + ']'
     );

     if (! f.isDirectory()) throw new IllegalArgumentException(
         "The directory-name provided to parameter 'workingDirectory' is not the name of " +
         "an actual File-System directory:\n[" + workingDirectory + ']'
     );
 }

 if (! workingDirectory.endsWith(File.separator))
     if (workingDirectory.length() > 0)
         workingDirectory = workingDirectory + File.separator;

 String subDir = workingDirectory + subDirectory;

 if (subDir.length() > 0)
 {
     f = new File(subDir);

     if ((! f.exists()) || (! f.isDirectory())) throw new IllegalArgumentException(
         "The directory-name provided to parameter 'subDirectory' does not exist on the " +
         "File-System as a Sub-Directory of 'workingDirectory':\n" +
         "[" + subDirectory + ']'
     );
 }

 if (! subDirectory.endsWith(File.separator))
     if (subDirectory.length() > 0)
         subDirectory = subDirectory + File.separator;

 if ((! traverseTree) && (dirFilter != null)) throw new IllegalArgumentException(
     "You have passed FALSE to 'traverseTree', but a non-null filter to parameter " +
     "'dirFilter'.  This is not allowed."
 );
        
 this.descriptors.add
     (new Descriptor(workingDirectory, subDirectory, traverseTree, fileFilter, dirFilter));

 return this;