blob: 1d4437fa05e0df1bac25bd596a9a98b0c1837997 [file] [log] [blame]
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 1.7.1 at 2017-12-08
| 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="20171208" />
<meta http-equiv="Content-Language" content="en" />
<title>Apache Sling Maven Sling Plugin &#x2013; sling:install</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 Maven Sling 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: 2017-12-08<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 2.3.4</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="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="sling:install"></a>sling:install</h2>
<p><b>Full name</b>:</p>
<p>org.apache.sling:maven-sling-plugin:2.3.4:install</p>
<p><b>Description</b>:</p>
<div>Install an OSGi bundle to a running Sling instance. The plugin
places an HTTP POST request to <a class="externalLink" href="http://felix.apache.org/documentation/subprojects/apache-felix-web-console/web-console-restful-api.html#post-requests">Felix
Web Console</a>. It's also possible to HTTP PUT instead of POST
leveraging the <a class="externalLink" href="http://sling.apache.org/documentation/development/repository-based-development.html">WebDAV
bundle from Sling</a>. Since version 2.1.8 you can also leverage
the the <a class="externalLink" href="http://sling.apache.org/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html">Sling
POST servlet</a> for that The chosen method depends on the
parameter <tt>deploymentMethod</tt>. <br />
<p><b>Intermediate Node Creation</b></p>
<p>For all <tt>deploymentMethod</tt>s except WebDAV the bundle
is not directly deployed within the OSGi container, but rather
being uploaded to the JCR and from there on being picked up by the
<a class="externalLink" href="https://sling.apache.org/documentation/bundles/jcr-installer-provider.html">JCR
Installer Provider</a> asynchronously, which takes care of
deploying it in the OSGi container. For both other deployment
methods, intermediate nodes (i.e. inexisting parent nodes) are
automatically created. The primary type of those intermediate nodes
depend on the deployment method.</p>
<ul>
<li>WebDAV, uses the configured collection node type, by default
<tt>sling:Folder</tt> (see also <a class="externalLink" href="https://sling.apache.org/documentation/development/repository-based-development.html">WebDAV
Configuration</a>)</li>
<li>SlingPostServlet, uses internally
<tt>ResourceResolverFactory.create(...)</tt> without setting
any <tt>jcr:primaryType</tt>. Therefore the
<tt>JcrResourceProviderFactory</tt> will call
<tt>Node.addNode(String relPath)</tt> which determines a
fitting node type automatically, depending on the parents node type
definition (see <a class="externalLink" href="http://www.day.com/specs/jsr170/javadocs/jcr-2.0/javax/jcr/Node.html#addNode%28java.lang.String%29">Javadoc</a>).
So in most of the cases this should be a <tt>sling:Folder</tt>,
as this is the first allowed child node definition in
<tt>sling:Folder</tt>. This only may differ, if your existing
parent node is not of type <tt>sling:Folder</tt> itself.</li>
</ul></div>
<p><b>Attributes</b>:</p>
<ul>
<li>Requires a Maven project to be executed.</li>
<li>Binds by default to the <a class="externalLink" href="http://maven.apache.org/ref/current/maven-core/lifecycles.html">lifecycle phase</a>: <tt>install</tt>.</li>
</ul>
<div class="section">
<h3><a name="Required_Parameters"></a>Required Parameters</h3>
<table class="table table-striped" border="0">
<tr class="a">
<th>Name</th>
<th>Type</th>
<th>Since</th>
<th>Description</th>
</tr>
<tr class="b">
<td><b><a href="#bundleFileName">bundleFileName</a></b></td>
<td><tt>String</tt></td>
<td><tt>-</tt></td>
<td>The name of the generated JAR file.<br /><b>Default value is</b>: <tt>${project.build.directory}/${project.build.finalName}.jar</tt>.<br /><b>User property is</b>: <tt>sling.file</tt>.</td>
</tr>
<tr class="a">
<td><b><a href="#bundleStart">bundleStart</a></b></td>
<td><tt>boolean</tt></td>
<td><tt>-</tt></td>
<td>Whether to start the uploaded bundle or not. Only applies when
POSTing to Felix Web Console<br /><b>Default value is</b>: <tt>true</tt>.<br /><b>User property is</b>: <tt>sling.bundle.start</tt>.</td>
</tr>
<tr class="b">
<td><b><a href="#bundleStartLevel">bundleStartLevel</a></b></td>
<td><tt>String</tt></td>
<td><tt>-</tt></td>
<td>The start level to set on the installed bundle. If the bundle is
already installed and therefore is only updated this parameter is
ignored. The parameter is also ignored if the running Sling
instance has no StartLevel service (which is unusual actually).
Only applies when POSTing to Felix Web Console.<br /><b>Default value is</b>: <tt>20</tt>.<br /><b>User property is</b>: <tt>sling.bundle.startlevel</tt>.</td>
</tr>
<tr class="a">
<td><b><a href="#failOnError">failOnError</a></b></td>
<td><tt>boolean</tt></td>
<td><tt>-</tt></td>
<td>Determines whether or not to fail the build if the HTTP POST or PUT
returns an non-OK response code.<br /><b>Default value is</b>: <tt>true</tt>.<br /><b>User property is</b>: <tt>sling.failOnError</tt>.</td>
</tr>
<tr class="b">
<td><b><a href="#mimeType">mimeType</a></b></td>
<td><tt>String</tt></td>
<td><tt>-</tt></td>
<td>The content type / mime type used for WebDAV or Sling POST
deployment.<br /><b>Default value is</b>: <tt>application/java-archive</tt>.<br /><b>User property is</b>: <tt>sling.mimeType</tt>.</td>
</tr>
<tr class="a">
<td><b><a href="#mountByFS">mountByFS</a></b></td>
<td><tt>boolean</tt></td>
<td><tt>-</tt></td>
<td>Whether to add the mapping for the <a class="externalLink" href="https://sling.apache.org/documentation/bundles/accessing-filesystem-resources-extensions-fsresource.html">Apache
Sling File System Resource Provider</a>.<br /><b>Default value is</b>: <tt>false</tt>.<br /><b>User property is</b>: <tt>sling.mountByFS</tt>.</td>
</tr>
<tr class="b">
<td><b><a href="#password">password</a></b></td>
<td><tt>String</tt></td>
<td><tt>-</tt></td>
<td>The password to authenticate at the running Sling instance.<br /><b>Default value is</b>: <tt>admin</tt>.<br /><b>User property is</b>: <tt>sling.password</tt>.</td>
</tr>
<tr class="a">
<td><b><a href="#refreshPackages">refreshPackages</a></b></td>
<td><tt>boolean</tt></td>
<td><tt>-</tt></td>
<td>Whether to refresh the packages after installing the uploaded
bundle. Only applies when POSTing to Felix Web Console<br /><b>Default value is</b>: <tt>true</tt>.<br /><b>User property is</b>: <tt>sling.refreshPackages</tt>.</td>
</tr>
<tr class="b">
<td><b><a href="#skip">skip</a></b></td>
<td><tt>boolean</tt></td>
<td><tt>-</tt></td>
<td>Whether to skip this step even though it has been configured in the
project to be executed. This property may be set by the
<tt>sling.install.skip</tt> comparable to the
<tt>maven.test.skip</tt> property to prevent running the unit
tests.<br /><b>Default value is</b>: <tt>false</tt>.<br /><b>User property is</b>: <tt>sling.install.skip</tt>.</td>
</tr>
<tr class="a">
<td><b><a href="#slingUrl">slingUrl</a></b></td>
<td><tt>String</tt></td>
<td><tt>-</tt></td>
<td>The URL of the running Sling instance. The default is only useful
for <b>WebConsole</b> deployment.<br /><b>Default value is</b>: <tt>http://localhost:8080/system/console</tt>.<br /><b>User property is</b>: <tt>sling.url</tt>.</td>
</tr>
<tr class="b">
<td><b><a href="#user">user</a></b></td>
<td><tt>String</tt></td>
<td><tt>-</tt></td>
<td>The user name to authenticate at the running Sling instance.<br /><b>Default value is</b>: <tt>admin</tt>.<br /><b>User property is</b>: <tt>sling.user</tt>.</td>
</tr>
</table>
</div>
<div class="section">
<h3><a name="Optional_Parameters"></a>Optional Parameters</h3>
<table class="table table-striped" border="0">
<tr class="a">
<th>Name</th>
<th>Type</th>
<th>Since</th>
<th>Description</th>
</tr>
<tr class="b">
<td><b><a href="#deploymentMethod">deploymentMethod</a></b></td>
<td><tt>BundleDeploymentMethod</tt></td>
<td><tt>-</tt></td>
<td>Bundle deployment method. One of the following three values are
allowed
<ol style="list-style-type: decimal">
<li><b>WebConsole</b>, uses the <a class="externalLink" href="http://felix.apache.org/documentation/subprojects/apache-felix-web-console/web-console-restful-api.html#post-requests">Felix
Web Console REST API</a> for deployment (HTTP POST). This is the
default. Make sure that <tt>slingUrl</tt> points to the Felix
Web Console in that case.</li>
<li><b>WebDAV</b>, uses <a class="externalLink" href="https://sling.apache.org/documentation/development/repository-based-development.html">WebDAV</a>
for deployment (HTTP PUT). Make sure that <tt>slingUrl</tt>
points to the entry path of the Sling WebDAV bundle (usually below
regular Sling root URL). Issues a HTTP Delete for the uninstall
goal.</li>
<li><b>SlingPostServlet</b>, uses the <a class="externalLink" href="https://sling.apache.org/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html">Sling
Post Servlet</a> for deployment (HTTP POST). Make sure that
<tt>slingUrl</tt> points a path which is handled by the Sling
POST Servlet (usually below regular Sling root URL).</li>
</ol>
This has precedence over the deprecated parameter
<tt>usePut</tt>.<br /><b>User property is</b>: <tt>sling.deploy.method</tt>.</td>
</tr>
<tr class="a">
<td><b><a href="#slingConsoleUrl">slingConsoleUrl</a></b></td>
<td><tt>String</tt></td>
<td><tt>-</tt></td>
<td>The WebConsole URL of the running Sling instance. This is required
for file system provider operations. If not configured the value of
slingUrl is used.<br /><b>User property is</b>: <tt>sling.console.url</tt>.</td>
</tr>
<tr class="b">
<td><b><a href="#slingUrlSuffix">slingUrlSuffix</a></b></td>
<td><tt>String</tt></td>
<td><tt>-</tt></td>
<td>An optional url suffix which will be appended to the
<tt>sling.url</tt> for use as the real target url. This allows
to configure different target URLs in each POM, while using the
same common <tt>sling.url</tt> in a parent POM (eg.
<tt>sling.url=http://localhost:8080</tt> and
<tt>sling.urlSuffix=/project/specific/path</tt>). This is
typically used in conjunction with WebDAV or SlingPostServlet
deployment methods.<br /><b>User property is</b>: <tt>sling.urlSuffix</tt>.</td>
</tr>
<tr class="a">
<td><b><a href="#usePut">usePut</a></b></td>
<td><tt>boolean</tt></td>
<td><tt>-</tt></td>
<td><b>Deprecated.</b> Use <tt>deploymentMethod</tt> instead.<br /><b>Default value is</b>: <tt>false</tt>.<br /><b>User property is</b>: <tt>sling.usePut</tt>.</td>
</tr>
</table>
</div>
<div class="section">
<h3><a name="Parameter_Details"></a>Parameter Details</h3>
<p><b><a name="bundleFileName">bundleFileName</a>:</b></p>
<div>The name of the generated JAR file.</div>
<ul>
<li><b>Type</b>: <tt>java.lang.String</tt></li>
<li><b>Required</b>: <tt>Yes</tt></li>
<li><b>User Property</b>: <tt>sling.file</tt></li>
<li><b>Default</b>: <tt>${project.build.directory}/${project.build.finalName}.jar</tt></li>
</ul><hr />
<p><b><a name="bundleStart">bundleStart</a>:</b></p>
<div>Whether to start the uploaded bundle or not. Only applies when
POSTing to Felix Web Console</div>
<ul>
<li><b>Type</b>: <tt>boolean</tt></li>
<li><b>Required</b>: <tt>Yes</tt></li>
<li><b>User Property</b>: <tt>sling.bundle.start</tt></li>
<li><b>Default</b>: <tt>true</tt></li>
</ul><hr />
<p><b><a name="bundleStartLevel">bundleStartLevel</a>:</b></p>
<div>The start level to set on the installed bundle. If the bundle is
already installed and therefore is only updated this parameter is
ignored. The parameter is also ignored if the running Sling
instance has no StartLevel service (which is unusual actually).
Only applies when POSTing to Felix Web Console.</div>
<ul>
<li><b>Type</b>: <tt>java.lang.String</tt></li>
<li><b>Required</b>: <tt>Yes</tt></li>
<li><b>User Property</b>: <tt>sling.bundle.startlevel</tt></li>
<li><b>Default</b>: <tt>20</tt></li>
</ul><hr />
<p><b><a name="deploymentMethod">deploymentMethod</a>:</b></p>
<div>Bundle deployment method. One of the following three values are
allowed
<ol style="list-style-type: decimal">
<li><b>WebConsole</b>, uses the <a class="externalLink" href="http://felix.apache.org/documentation/subprojects/apache-felix-web-console/web-console-restful-api.html#post-requests">Felix
Web Console REST API</a> for deployment (HTTP POST). This is the
default. Make sure that <tt>slingUrl</tt> points to the Felix
Web Console in that case.</li>
<li><b>WebDAV</b>, uses <a class="externalLink" href="https://sling.apache.org/documentation/development/repository-based-development.html">WebDAV</a>
for deployment (HTTP PUT). Make sure that <tt>slingUrl</tt>
points to the entry path of the Sling WebDAV bundle (usually below
regular Sling root URL). Issues a HTTP Delete for the uninstall
goal.</li>
<li><b>SlingPostServlet</b>, uses the <a class="externalLink" href="https://sling.apache.org/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html">Sling
Post Servlet</a> for deployment (HTTP POST). Make sure that
<tt>slingUrl</tt> points a path which is handled by the Sling
POST Servlet (usually below regular Sling root URL).</li>
</ol>
This has precedence over the deprecated parameter
<tt>usePut</tt>.</div>
<ul>
<li><b>Type</b>: <tt>org.apache.sling.maven.bundlesupport.deploy.BundleDeploymentMethod</tt></li>
<li><b>Required</b>: <tt>No</tt></li>
<li><b>User Property</b>: <tt>sling.deploy.method</tt></li>
</ul><hr />
<p><b><a name="failOnError">failOnError</a>:</b></p>
<div>Determines whether or not to fail the build if the HTTP POST or PUT
returns an non-OK response code.</div>
<ul>
<li><b>Type</b>: <tt>boolean</tt></li>
<li><b>Required</b>: <tt>Yes</tt></li>
<li><b>User Property</b>: <tt>sling.failOnError</tt></li>
<li><b>Default</b>: <tt>true</tt></li>
</ul><hr />
<p><b><a name="mimeType">mimeType</a>:</b></p>
<div>The content type / mime type used for WebDAV or Sling POST
deployment.</div>
<ul>
<li><b>Type</b>: <tt>java.lang.String</tt></li>
<li><b>Required</b>: <tt>Yes</tt></li>
<li><b>User Property</b>: <tt>sling.mimeType</tt></li>
<li><b>Default</b>: <tt>application/java-archive</tt></li>
</ul><hr />
<p><b><a name="mountByFS">mountByFS</a>:</b></p>
<div>Whether to add the mapping for the <a class="externalLink" href="https://sling.apache.org/documentation/bundles/accessing-filesystem-resources-extensions-fsresource.html">Apache
Sling File System Resource Provider</a>.</div>
<ul>
<li><b>Type</b>: <tt>boolean</tt></li>
<li><b>Required</b>: <tt>Yes</tt></li>
<li><b>User Property</b>: <tt>sling.mountByFS</tt></li>
<li><b>Default</b>: <tt>false</tt></li>
</ul><hr />
<p><b><a name="password">password</a>:</b></p>
<div>The password to authenticate at the running Sling instance.</div>
<ul>
<li><b>Type</b>: <tt>java.lang.String</tt></li>
<li><b>Required</b>: <tt>Yes</tt></li>
<li><b>User Property</b>: <tt>sling.password</tt></li>
<li><b>Default</b>: <tt>admin</tt></li>
</ul><hr />
<p><b><a name="refreshPackages">refreshPackages</a>:</b></p>
<div>Whether to refresh the packages after installing the uploaded
bundle. Only applies when POSTing to Felix Web Console</div>
<ul>
<li><b>Type</b>: <tt>boolean</tt></li>
<li><b>Required</b>: <tt>Yes</tt></li>
<li><b>User Property</b>: <tt>sling.refreshPackages</tt></li>
<li><b>Default</b>: <tt>true</tt></li>
</ul><hr />
<p><b><a name="skip">skip</a>:</b></p>
<div>Whether to skip this step even though it has been configured in the
project to be executed. This property may be set by the
<tt>sling.install.skip</tt> comparable to the
<tt>maven.test.skip</tt> property to prevent running the unit
tests.</div>
<ul>
<li><b>Type</b>: <tt>boolean</tt></li>
<li><b>Required</b>: <tt>Yes</tt></li>
<li><b>User Property</b>: <tt>sling.install.skip</tt></li>
<li><b>Default</b>: <tt>false</tt></li>
</ul><hr />
<p><b><a name="slingConsoleUrl">slingConsoleUrl</a>:</b></p>
<div>The WebConsole URL of the running Sling instance. This is required
for file system provider operations. If not configured the value of
slingUrl is used.</div>
<ul>
<li><b>Type</b>: <tt>java.lang.String</tt></li>
<li><b>Required</b>: <tt>No</tt></li>
<li><b>User Property</b>: <tt>sling.console.url</tt></li>
</ul><hr />
<p><b><a name="slingUrl">slingUrl</a>:</b></p>
<div>The URL of the running Sling instance. The default is only useful
for <b>WebConsole</b> deployment.</div>
<ul>
<li><b>Type</b>: <tt>java.lang.String</tt></li>
<li><b>Required</b>: <tt>Yes</tt></li>
<li><b>User Property</b>: <tt>sling.url</tt></li>
<li><b>Default</b>: <tt>http://localhost:8080/system/console</tt></li>
</ul><hr />
<p><b><a name="slingUrlSuffix">slingUrlSuffix</a>:</b></p>
<div>An optional url suffix which will be appended to the
<tt>sling.url</tt> for use as the real target url. This allows
to configure different target URLs in each POM, while using the
same common <tt>sling.url</tt> in a parent POM (eg.
<tt>sling.url=http://localhost:8080</tt> and
<tt>sling.urlSuffix=/project/specific/path</tt>). This is
typically used in conjunction with WebDAV or SlingPostServlet
deployment methods.</div>
<ul>
<li><b>Type</b>: <tt>java.lang.String</tt></li>
<li><b>Required</b>: <tt>No</tt></li>
<li><b>User Property</b>: <tt>sling.urlSuffix</tt></li>
</ul><hr />
<p><b><a name="usePut">usePut</a>:</b></p>
<div><b>Deprecated.</b> Use <tt>deploymentMethod</tt> instead.</div>
<div>If a PUT via WebDAV should be used instead of the standard POST to
the Felix Web Console. In the <tt>uninstall</tt> goal, a HTTP
DELETE will be used.</div>
<ul>
<li><b>Type</b>: <tt>boolean</tt></li>
<li><b>Required</b>: <tt>No</tt></li>
<li><b>User Property</b>: <tt>sling.usePut</tt></li>
<li><b>Default</b>: <tt>false</tt></li>
</ul><hr />
<p><b><a name="user">user</a>:</b></p>
<div>The user name to authenticate at the running Sling instance.</div>
<ul>
<li><b>Type</b>: <tt>java.lang.String</tt></li>
<li><b>Required</b>: <tt>Yes</tt></li>
<li><b>User Property</b>: <tt>sling.user</tt></li>
<li><b>Default</b>: <tt>admin</tt></li>
</ul>
</div>
</div>
</div>
</div>
</div>
<hr/>
<footer>
<div class="container-fluid">
<div class="row-fluid">
<p>Copyright &copy;2007&#x2013;2017
<a href="https://www.apache.org/">The Apache Software Foundation</a>.
All rights reserved.</p>
</div>
</div>
</footer>
</body>
</html>