BuildScriptExtensibility

build script extensibility

Ant build script extensibility for standard (non-freeform) project types Issuezilla task


API for 3rd party modules extending project type

A new API class needs to be created preferrably in ant/project module, The class will be available in Lookup of project types that support build extensibility.


public class AntBuildExtender {
    /**
     * List of targets for the project type that are allowed to be extended by 3rd party modules.
     */
    public Set<String> getExtendableTargets();

     /**
      * Adds a build extension to the current project.
      * @param id - a unique ID across extensions, cannot add same extension repeatedly
      * @param extensionXml fileobject that contains the build script snippets that is to be imported in the main script. Shall not override
      *                     any targets from main script, preferrable prefixing the target names with id of the extension.
      *                     The file shall be placed in ${basedir}/nbproject directory or below.
      */
    public Extension addExtension(String id, FileObject extensionXml);

    /*
     * remove a previously added extension.
     */
    public void removeExtension(String id);

    /**
     * Returns the extension instance by the given ID.
     */
    public Extension getExtension(String id);



   /**
    * Wrapper around the extension definition.
    */
   public static class Extension {
  
       /**
        * Add a dependency to the mainBuildTarget (has to be declared in getExtendableTargets())
        */
       public void addDependency(String mainBuildTarget, String extensionTarget);


       /**
        * Remove a dependency from the mainBuildTarget
        */
       public void removeDependency(String mainBuildTarget, String extensionTarget);

   }
}

Typical use by 3rd party plugin would look like this.


AntBuildExtender ext = project.getlookup().lookup(AntBuildExtender.class);
if (ext != null && ext.getExtension("jaxb") == null) {
   FileObject jaxbxml = magicMethodForCreatingJaxbXml(project.getProjectDirectory());
   AntBuildExtender.Extension ex = ext.addExtension("jaxb", jaxbxml);
   //if having any dependencies
   ex.addDependency("--pre-compile", "jaxb-generate");
}


Project.xml changes

The additional project.xml content can look like this:

<buildExtensions>
   <extension id="jaxb" file="jaxb-build.xml">
      <dependency target="--pre-compile" dependsOn="jaxb-generate"/>
   </extension>
</buildExtensions>

That could be either in it's own separate namespace which is the same across the project types or become part of the main namespace of the project type.

SPI for project types

The SPI part of the contract is a bit tricky due to the current state of projects. AntProjectHelper is a final class and most project types have wrappers (UpdateWrapper) that handle lazy upgrading to new versions of project's main namespace.

public final class AntBuildExtenderProvider {

       public static AntBuildExtender createExtender( AntExtenterImplementation implementation );

       public static Element getExtenderXmlContent( AntBuildExtender ex );

}


public interface AntExtenderImplementation {

      List<String> getExtendableTargets();

      void stateChanged();
      
}  

The project specific implementation of AntExtenderImplementation will make sure that on stateChanged() the project.xml is correctly written and possibly upgraded from previous version to a new one.

The actual generation of build script can be done in 2 ways:

  • add xslt transformations to the project's generated build-impl template. Pro: uses the same process as all the other enhancements Con: needs rather complex snippets in many places in the xslt doc.
  • add a post processing step after the xslt transformation that would inject the dependencies and imports. Pro: can be done in one place without additional work on the project type side con: makes the generation a 2 step process.
Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo