| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.9.2 from src/site/markdown/usage.md.vm at 2021-09-28 |
| | Rendered using Apache Maven Fluido Skin 1.9 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1" /> |
| <meta name="generator" content="Apache Maven Doxia Site Renderer 1.9.2" /> |
| <title>Scripting Bundle Maven Plugin – Usage</title> |
| <link rel="stylesheet" href="./css/apache-maven-fluido-1.9.min.css" /> |
| <link rel="stylesheet" href="./css/site.css" /> |
| <link rel="stylesheet" href="./css/print.css" media="print" /> |
| <script src="./js/apache-maven-fluido-1.9.min.js"></script> |
| </head> |
| <body class="topBarDisabled"> |
| <a href="https://github.com/apache/sling-scriptingbundle-maven-plugin"> |
| <img style="position: absolute; top: 0; right: 0; border: 0; z-index: 10000;" |
| src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" |
| alt="Fork me on GitHub"> |
| </a> |
| <div class="container-fluid"> |
| <header> |
| <div id="banner"> |
| <div class="pull-left"><a href="https://sling.apache.org/" id="bannerLeft"><img src="https://sling.apache.org/res/logos/sling.svg" alt="Apache Sling" width="123" height="63"/></a></div> |
| <div class="pull-right"><a href="https://apache.org/" id="bannerRight"><img src="https://sling.apache.org/res/logos/apache.png" alt="Apache"/></a></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li class=""><a href="https://sling.apache.org/" class="externalLink" title="Apache Sling">Apache Sling</a><span class="divider">/</span></li> |
| <li class=""><a href="https://sling.apache.org/components/" class="externalLink" title="Maven Plugins">Maven Plugins</a><span class="divider">/</span></li> |
| <li class=""><a href="index.html" title="Scripting Bundle Maven Plugin">Scripting Bundle Maven Plugin</a><span class="divider">/</span></li> |
| <li class="active ">Usage <a href="https://github.com/apache/sling-scriptingbundle-maven-plugin/tree/scriptingbundle-maven-plugin-0.5.0/src/site/markdown/usage.md.vm"><img src="./images/accessories-text-editor.png" title="Edit" /></a></li> |
| <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2021-09-28</li> |
| <li id="projectVersion" class="pull-right">Version: 0.5.0</li> |
| </ul> |
| </div> |
| </header> |
| <div class="row-fluid"> |
| <header id="leftColumn" class="span2"> |
| <nav 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><a href="bnd.html" title="Bnd Plugin"><span class="none"></span>Bnd Plugin</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> |
| </nav> |
| <div class="well sidebar-nav"> |
| <hr /> |
| <div id="poweredBy"> |
| <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> |
| </header> |
| <main id="bodyColumn" class="span10" > |
| <section> |
| <h2><a name="Usage"></a>Usage</h2> |
| <p>The plugin can be used either as a regular Maven plugin or as a <a href="bnd.html">bnd plugin</a>. Its purpose is to extract the capabilities required for packaging the scripts (precompiled or not) into an OSGi bundle. Both versions of the plugin can be used for OSGi bundle projects, however the <a href="bnd.html">bnd plugin</a> can also be used with <a class="externalLink" href="https://jackrabbit.apache.org/filevault/index.html">FileVault</a> content package projects.</p> |
| <p>Both versions of the plugin will, by default, look for scripts in two project directories:</p> |
| <ol style="list-style-type: decimal"> |
| |
| <li><code>src/main/scripts</code> - this folder will contain scripts that will be pre-compiled</li> |
| <li><code>src/main/resources/javax.script</code> - 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/bundles/scripting.html#resource-script-naming-conventions">Sling Scripting</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: <code><resourceType>/<version>/</code>. The <code><version></code> should be a valid semantic version (e.g. <code>1.0.0</code>)</p> |
| </li> |
| <li> |
| |
| <p>Defining explicit extends relationships (similar to the <code>sling:resourceSuperType</code> property)<br /> An <code>extends</code> file in the resource type folder (versioned or not) allows defining this explicit relationship. This file must contain a single line with the <code>resourceType</code> used for the <code>extends</code> capability attribute followed by a <code>;version=<version-range></code>; in this case, the plugin will set the <code>extends</code> attribute to the given <code>resourceType</code> and generate a <code>Require-Capability</code> for that <code>resourceType</code> with the given version range. To generate an optional capability header (when the bundled script extends from a non-bundle, resource script), append <code>;resolution:=optional</code> to the line. The line must comply with the OSGI common header syntax from <a class="externalLink" href="http://docs.osgi.org/specification/osgi.core/7.0.0/framework.module.html#framework.common.header.syntax">OSGI Core R7 §3.2.4</a>.</p> |
| </li> |
| <li> |
| |
| <p>Defining an explicit requirement, without an inheritance relationship (e.g. delegation to another resource type)<br /> A <code>requires</code> file (assuming the same conventions and syntax as for the <code>extends</code> file) will generate a <code>Require-Capability</code> for each line based on the given <code>resourceType</code> 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. <code>com.mydomain.components.image</code>). When the resource type is defined as a package name, the resource type label will be the last subpackage (i.e. for <code>com.mydomain.components.image</code>, the resource type label will be <code>image</code>).</p> |
| </li> |
| </ol> |
| <p>Starting with version 0.5.0, the plugin will mark the requirements which are not satisfied by the analysed project as optional; classpath dependencies are not checked for provided capabilities. If you want to generate mandatory requirements, set the <code>missingRequirementsOptional</code> flag to <code>false</code>.</p><section> |
| <h3><a name="Defining_scripts"></a>Defining scripts</h3> |
| <p>As an example, let’s assume the following layout:</p> |
| |
| <div class="source"> |
| <div class="source"><pre class="prettyprint linenums">src/main/resources/javax.script/ |
| org.foo/1.0.0 |
| foo.POST.html |
| </pre></div></div> |
| |
| <p>This will generate following <code>Provide-Capability</code>:</p> |
| |
| <div class="source"> |
| <div class="source"><pre class="prettyprint linenums">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></section><section> |
| <h3><a name="Configure_Maven_Plugin"></a>Configure Maven Plugin</h3> |
| <p>When used as a Maven plugin, the generated <code>Require-Capability</code> and <code>Provide-Capability</code> headers values are made available via Maven project properties:</p> |
| |
| <div class="source"> |
| <div class="source"><pre class="prettyprint linenums">${org.apache.sling.scriptingbundle.maven.plugin.Require-Capability} |
| ${org.apache.sling.scriptingbundle.maven.plugin.Require-Capability} |
| </pre></div></div> |
| |
| <p>That makes it reasonably straightforward to use the plugin by just adding it into your build and use the two properties in the manifest writing instructions of another plugin like the <code>maven-bundle-plugin</code>:</p> |
| |
| <div class="source"> |
| <div class="source"><pre class="prettyprint linenums"><plugin> |
| <groupId>org.apache.sling</groupId> |
| <artifactId>scriptingbundle-maven-plugin</artifactId> |
| <version>0.5.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> |
| |
| <p>The <code>osgi.extender</code> requirement is mandatory to have the bundle wired up to the Apache Sling Servlets Resolver, but this should be manually defined by the developers, so that their bundle is correctly wired up to whatever version of the Servlets Resolver is available on the destination platform.</p></section></section> |
| </main> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| <p>© 2007–2021 |
| <a href="https://www.apache.org/">The Apache Software Foundation</a> |
| </p> |
| </div> |
| </div> |
| </footer> |
| </body> |
| </html> |
