| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.8.1 at 2020-06-22 |
| | Rendered using Apache Maven Fluido Skin 1.6 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| <meta name="Date-Revision-yyyymmdd" content="20200622" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| <title>Apache Sling Scripting Bundle Maven Plugin – Usage</title> |
| <link rel="stylesheet" href="./css/apache-maven-fluido-1.6.min.css" /> |
| <link rel="stylesheet" href="./css/site.css" /> |
| <link rel="stylesheet" href="./css/print.css" media="print" /> |
| <script type="text/javascript" src="./js/apache-maven-fluido-1.6.min.js"></script> |
| </head> |
| <body class="topBarDisabled"> |
| <div class="container-fluid"> |
| <div id="banner"> |
| <div class="pull-left"><div id="bannerLeft"><h2>Apache Sling Scripting Bundle Maven Plugin</h2> |
| </div> |
| </div> |
| <div class="pull-right"></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li id="publishDate">Last Published: 2020-06-22<span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 0.2.0</li> |
| </ul> |
| </div> |
| <div class="row-fluid"> |
| <div id="leftColumn" class="span2"> |
| <div class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header">Overview</li> |
| <li><a href="index.html" title="Introduction"><span class="none"></span>Introduction</a> </li> |
| <li><a href="plugin-info.html" title="Goals"><span class="none"></span>Goals</a> </li> |
| <li class="active"><a href="#"><span class="none"></span>Usage</a> |
| </li> |
| <li class="nav-header">Project Documentation</li> |
| <li><a href="project-info.html" title="Project Information"><span class="icon-chevron-right"></span>Project Information</a> </li> |
| <li><a href="project-reports.html" title="Project Reports"><span class="icon-chevron-right"></span>Project Reports</a> </li> |
| </ul> |
| <hr /> |
| <div id="poweredBy"> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /></a> |
| </div> |
| </div> |
| </div> |
| <div id="bodyColumn" class="span10" > |
| <div class="section"> |
| <h2><a name="Usage"></a>Usage</h2> |
| <p>The Scripting Bundle Maven Plugin will look for scripts in two project directories:</p> |
| <ol style="list-style-type: decimal"> |
| |
| <li><tt>src/main/scripts</tt> - this folder will contain scripts that will be pre-compiled</li> |
| <li><tt>src/main/resources/javax.script</tt> - this folder will contain scripts that will be embedded as is</li> |
| </ol> |
| <p>The structure in these source directories should then follow the normal way of structuring scripts in an Apache Sling application. For more details, check the <a class="externalLink" href="https://sling.apache.org/documentation/the-sling-engine/url-to-script-resolution.html#script-locations">URL to Script Resolution</a> page. In addition to the normal way of structuring scripts in the file tree, the plugin provides some additional features:</p> |
| <ol style="list-style-type: decimal"> |
| |
| <li> |
| |
| <p>Resource Type Versioning<br /> This works by putting the scripts in a folder that follows this simple naming convention: <tt><resourceType>/<version>/</tt>. The <tt><version></tt> should be a valid semantic version (e.g. <tt>1.0.0</tt>)</p> |
| </li> |
| <li> |
| |
| <p>Defining explicit extends relationships (similar to the <tt>sling:resourceSuperType</tt> property)<br /> An <tt>extends</tt> file in the resource type folder (versioned or not) allows defining this explicit relationship. This file must contain a single line with the <tt>resourceType</tt> used for the <tt>extends</tt> capability attribute followed by a <tt>;version=<version-range></tt>; in this case, the plugin will set the <tt>extends</tt> attribute to the given <tt>resourceType</tt> and generate a <tt>Require-Capability</tt> for that <tt>resourceType</tt> with the given version range.</p> |
| </li> |
| <li> |
| |
| <p>Defining an explicit requirement, without an inheritance relationship (e.g. delegation to another resource type)<br /> A <tt>requires</tt> file (assuming the same conventions and syntax as for the <tt>extends</tt> file) will generate a <tt>Require-Capability</tt> for each line based on the given <tt>resourceType</tt> and version range.</p> |
| </li> |
| <li> |
| |
| <p>The Resource Type can have the form of a path or of a Java package name (e.g. <tt>com.mydomain.components.image</tt>). When the resource type is defined as a package name, the resource type label will be the last subpackage (i.e. for <tt>com.mydomain.components.image</tt>, the resource type label will be <tt>image</tt>).</p> |
| </li> |
| </ol> |
| <div class="section"> |
| <h3><a name="Defining_scripts"></a>Defining scripts</h3> |
| <p>As an example, let’s assume the following layout:</p> |
| |
| <div> |
| <div> |
| <pre class="source">src/main/resources/javax.script/ |
| org.foo/1.0.0 |
| foo.POST.html |
| </pre></div></div> |
| |
| <p>This will generate following <tt>Provide-Capability</tt>:</p> |
| |
| <div> |
| <div> |
| <pre class="source">sling.servlet; |
| sling.servlet.resourceTypes:List<String>="org.foo"; |
| sling.servlet.methods:List<String>=POST; |
| version:Version="1.0.0" |
| </pre></div></div> |
| |
| <p>For more complex examples head over to <a class="externalLink" href="https://github.com/apache/sling-org-apache-sling-scripting-bundle-tracker-it/tree/master/examples">https://github.com/apache/sling-org-apache-sling-scripting-bundle-tracker-it/tree/master/examples</a>.</p></div> |
| <div class="section"> |
| <h3><a name="So_how_do_I_use_the_plugin.3F"></a>So how do I use the plugin?</h3> |
| <p>The plugin doesn’t currently integrate with the <tt>maven-bundle-plugin</tt>, nor the <tt>bnd-maven-plugin</tt>. However, the generated <tt>Require-Capability</tt> and <tt>Provide-Capability</tt> headers values are simply made available via properties:</p> |
| |
| <div> |
| <div> |
| <pre class="source">${org.apache.sling.scriptingbundle.maven.plugin.Require-Capability} |
| ${org.apache.sling.scriptingbundle.maven.plugin.Require-Capability} |
| </pre></div></div> |
| |
| <p>That makes it reasonable straightforward to use the plugin by just adding it into your build in the <tt>prepare-package</tt> phase and use the two properties in the manifest writing instructions of another plugin like the <tt>maven-bundle-plugin</tt>:</p> |
| |
| <div> |
| <div> |
| <pre class="source"><plugin> |
| <groupId>org.apache.sling</groupId> |
| <artifactId>scriptingbundle-maven-plugin</artifactId> |
| <version>0.2.0</version> |
| <executions> |
| <execution> |
| <phase>prepare-package</phase> |
| <goals> |
| <goal>metadata</goal> |
| </goals> |
| </execution> |
| </executions> |
| </plugin> |
| <plugin> |
| <groupId>org.apache.felix</groupId> |
| <artifactId>maven-bundle-plugin</artifactId> |
| <extensions>true</extensions> |
| <configuration> |
| <instructions> |
| <Provide-Capability> |
| ${org.apache.sling.scriptingbundle.maven.plugin.Provide-Capability} |
| </Provide-Capability> |
| <Require-Capability> |
| osgi.extender;filter:="(&amp;(osgi.extender=sling.scripting)(version>=1.0.0)(!(version>=2.0.0)))", |
| ${org.apache.sling.scriptingbundle.maven.plugin.Require-Capability} |
| </Require-Capability> |
| </instructions> |
| </configuration> |
| </plugin> |
| </pre></div></div></div></div> |
| </div> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| <p>Copyright ©2007–2020 |
| <a href="https://www.apache.org/">The Apache Software Foundation</a>. |
| All rights reserved.</p> |
| </div> |
| </div> |
| </footer> |
| </body> |
| </html> |
