[Maven-js-plugin-developers] Vote on 1.2 release features

[Adam A. <aal...@mo...>]

All:

 

Here is a proposal that I would like to put up for vote pertaining to new
features for the 1.2 release of the maven-js-plugin.  I am pasting in the MS
Word document below.

 


1         Introduction


1.1      Purpose of this Document


This document serves as the introduction to the design and implementation of
the new features that will be included in the 1.2 release of the MobilVox
Maven JavaScript Plugin, otherwise referred to as the maven-js-plugin.  All
planned features proposed in this document will then be viewed and voted on
by the maven-js-plugin development team, which will determine their status
for the 1.2 release.

 


2         Requirements


2.1      Functional Requirements


The planned feature set that will be incorporated with the 1.2 release will
include but, may not be limited to:

 

*	A user shall be able to turn off compression via the command line,
limiting the need for Maven profiles.
*	A user shall be able to configure most POM configuration options via
the command line using the -D{command}={value} format.
*	A user should be able to add a text file that contains licensing and
other necessary information, to be included with the compressed JavaScript
file.
*	A user shall be able to exclude files from the compression process.


2.2      Non-Functional Requirements


2.2.1      Usability Requirements


The maven-js-plugin should remain usable in the same manner as it currently
is.  The added features should not prohibit the existing usability of the
plugin.


3         Feature Design and Implementation


This section will describe the design and implementation of the feature set
contained in Section 2, Requirements.


3.1      Setting Parameters via the Command Line


Javadoc annotations can be used to enable a user to set parameters via the
command line as well as the POM.XML.  The following example contains an
annotation in the Javadoc which can be set: 

 

   /**

     * A boolean used to determine if the compressed JS files in the site

     * will overwrite the original or create duplicates.

     * 

     * @parameter expression="${replaceSiteJavaScript}" default-value="true"

     */

    private boolean replaceSiteJavaScript;:

 

The @parameter expression="${replaceSiteJavaScript}" enables a user to use
the command line to set the parameter for the execution of the plugin.  For
example using:

 -DreplaceSiteJavaScript=true would overwrite all of the JS files in the
site with the created compressed files. 

 

The following parameters will be included to be set via the command line:

 

*	replaceSiteJavaScript - a Boolean used to determine if the
compressed JavaScript files will overwrite the original or create
duplicates.
*	mergeWarFiles - a Boolean used to determine if the WAR files will be
merged into one with compressed JavaScript or a second WAR file will be
created that contains the compressed JavaScript.
*	skipCompression - a Boolean that can be set to tell the MOJO to skip
the compression of the JavaScript files.
*	classifier - the String classifier attached to the created WAR file
if mergeWarFiles is false.
*	siteClassifer - the String classifier attached to the compressed
JavaScript files if the replaceSiteJavaScript is false.
*	skipCompression - described in further detail in section 3.2.

 


3.2      Enabling and Disabling Compression via the Command Line


To enable a user to easily skip the compression during a build, the
skipCompression Boolean will be added.  It will use the command line format
of js.compress.skip.  The default value of the parameter will be false but,
can be set via the command line or the POM.XML to true.

The example below shows the Java variable skipCompression.

 

 

 

    /**

     * Boolean used for skipping compression.

     *

     * @parameter expression="${js.compress.skip}" default-value="false"

     */

    private boolean skipCompression;

 

For a user to then skip the compression, they would only need to add 

-Djs.compress.skip=true to the Maven command that initiates the
maven-js-plugin MOJO(s).


3.3      Adding Licenses to Compressed Files


Licenses and other pertinent information should be able to be added to
compressed JavaScript files during the compression process.  The preferred
way of handling this is to include a text file that contains the information
and point to it using a configurable parameter in the POM.XML setup of the
maven-js-plugin.  If this parameter is valid and the file exists, then all
of the information in the file will be written at the head of each
JavaScript file.  An example text file might be something like this: 

 

/*

 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 

 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 

 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 

 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF

 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 */

 

This licensing agreement would then be added at the head of each JavaScript
file.   The parameter for including the file in the POM.XML would be
contained in the Plugin configuration for the maven-js-plugin in the POM.XML
of the project using the plugin.  It should be configured in the manner of
the sample below:

 

<plugin>

  <groupId>com.mobilvox.ossi.mojo</groupId>

  <artifactId>maven-js-plugin</artifactId>

  <version>1.2</version>

  <configuration>

    <mergeWarFiles>true</mergeWarFiles>

    <classifier>js-compressed</classifier> 

    <licenseFile>/com/myCompany/license/license.txt</licenseFile>

  </configuration>

</plugin>

 

The maven-js-plugin would then include the information in the license.txt
file at the top of each compressed file. 


3.4      Excluding Files from the Compression Process


To exclude files from the compression process, a regular expression within
an <excludes> block in the <configuration> of <plugin> tag will be used.
All files the match the regular expression will not be included in the
compression. The POM.XML should look similar to the example below:

 

<plugin>

  <groupId>com.mobilvox.ossi.mojo</groupId>

  <artifactId>maven-js-plugin</artifactId>

  <version>1.2</version>

  <configuration>

    <mergeWarFiles>true</mergeWarFiles>

    <classifier>js-compressed</classifier> 

    <licenseFile>/com/myCompany/license/license.txt</licenseFile>

    <excludes>

      <exclude>*no-compress*</exclude>

    </excludes>

  </configuration>

</plugin>

 

This would not compress any files that contain no-compress in their name.
The ideal implementation of this would use the Java regular expression
classes java.util.regex.Matcher, java.util.regex.Pattern, and
java.util.regex.PatternSyntaxException (the java.lang.String implementation
CharSequence interface could be another possible scenario for accomplishing
the filtering).  The MOJO would check each file against he excludes in the
POM and if a match was found, the file would be excluded from being
compressed. 

 

 

I am voting a +1 for this feature set, any other features you think would be
appropriate, let me know.

 

Thanks,

 

Adam Altemus

aal...@mo...