http://git-wip-us.apache.org/repos/asf/sling-site/blob/3a935d04/documentation/bundles/jcr-installer-provider.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/jcr-installer-provider.html b/documentation/bundles/jcr-installer-provider.html index 3e99c6f..dd414de 100644 --- a/documentation/bundles/jcr-installer-provider.html +++ b/documentation/bundles/jcr-installer-provider.html @@ -2,27 +2,27 @@ <head> <meta charset="utf-8"/> <title>Apache Sling on JBake</title> - <link rel="stylesheet" href="/res/css/site.css"/> - <link rel="stylesheet" href="/res/css/codehilite.css"/> + <link rel="stylesheet" href="/ng/res/css/site.css"/> + <link rel="icon" href="/ng/res/favicon.ico"/> <div class="title"> <div class="logo"> <a href="http://sling.apache.org";> - <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/> + <img border="0" alt="Apache Sling" src="/ng/res/logos/sling.svg"/> </a> </div><div class="header"> <a href="http://www.apache.org";> - <img border="0" alt="Apache" src="/res/logos/apache.png"/> + <img border="0" alt="Apache" src="/ng/res/logos/apache.png"/> </a> </div> </div> </head><body> <div class="menu"> - <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki";>Wiki</a><br/><a href="http://s.apache.org/sling.faq";>FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/";>License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk";>Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling";>Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html";>Become a Sponsor</a><br/><a href="https://donate.apache.org/";>Donate!</a><br/><a href="http://www.apache.org/foun dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong> + <strong><a href="/ng/documentation.html">Documentation</a></strong><br/><a href="/ng/documentation/getting-started.html">Getting Started</a><br/><a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/ng/documentation/development.html">Development</a><br/><a href="/ng/documentation/bundles.html">Bundles</a><br/><a href="/ng/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/ng/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki";>Wiki</a><br/><a href="http://s.apache.org/sling.faq";>FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/ng/apidocs/sling9/index.html">Sling 9</a><br/><a href="/ng/apidocs/sling8/index.html">Sling 8</a><br/><a href="/ng/apidocs/sling7/index.html">Sling 7</a><br/><a href="/ng/apidocs/sling6/index.html">Sling 6</a><br/><a href="/ng/apidocs/sling5/index.html">Sling 5</a><br/><a href="/ng/javadoc-io.html">Archive at javadoc.io</a><br/><p></p ><strong>Project info</strong><br/><a >href="/ng/downloads.cgi">Downloads</a><br/><a >href="http://www.apache.org/licenses/";>License</a><br/><a >href="/ng/contributing.html">Contributing</a><br/><a >href="/ng/news.html">News</a><br/><a href="/ng/links.html">Links</a><br/><a >href="/ng/project-information.html">Project Information</a><br/><a >href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/><a >href="http://ci.apache.org/builders/sling-trunk";>Build Server</a><br/><a >href="/ng/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a > href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/><a >href="git://git.apache.org/sling.git">Git</a><br/><a >href="https://github.com/apache/sling";>Github >Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a >href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/><a >href="http://www.apache.org/foundation/sponsorship.html";>Become a >Sponsor</a><br/><a href="https://donate.apache. org/">Donate!</a><br/><a href="http://www.apache.org/foundation/buy_stuff.html";>Buy Stuff</a><br/><p></p><strong><a href="/ng/sitemap.html">Site Map</a></strong> </div> <div class="main"> <div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>JCR Installer Provider</h1></header><p>The JCR installer provider scans the JCR repository for artifacts and provides them to the <a href="/documentation/bundles/osgi-installer.html">OSGI installer</a>.</p> <h2>Configuration and Scanning</h2> <p>The JCR installer provider can be configured with weighted paths which are scanned. By default, the installer scans in <em>/apps</em> and <em>/libs</em> where artifacts found in <em>/apps</em> get a higher priority. The installer does a deep scan and uses a regular expression to detect folders containing artifacts to be installed. By default, artifacts from within a folder named <em>install</em> are provided to the OSGi installer.</p> -<p>If such an install folder contains a binary artifact (e.g. a bundle or a config file as described in <a href="/documentation/bundles/configuration-installer-factory.html">Configuration Installer Factory</a>) this is provided to the OSGi installer.</p> +<p>If such an install folder contains a binary artifact (e.g. a bundle or a config file as described in <a href="/documentation/bundles/configuration-installer-factory.html">Configuration Installer Factory</a>) this is provided to the OSGi installer. </p> <p>In addition every node of type <em>sling:OsgiConfig</em> is provided as a configuration to the installer. This has the advantage of leveraging the JCR structure better than binary files, but has the known limitations outlined in <a href="https://issues.apache.org/jira/browse/SLING-4183";>SLING-4183</a> and <a href="https://issues.apache.org/jira/browse/SLING-2477";>SLING-2477</a>, therefore it is recommended to stick to one of the binary formats described in <a href="/documentation/bundles/configuration-installer-factory.html">Configuration Installer Factory</a>.</p> <p>The JCR installer provider does not check or scan the artifacts itself, the detection and installation is deferred to the OSGi installer.</p> <h3>Runmode Support</h3> @@ -32,7 +32,7 @@ <p>The JCR installer supports writing back of configurations which are changed by some other ways, e.g by using the Apache Felix web console. If this is a new configuration which was not originally stored in the repository, a new configuration is stored under <em>/apps/sling/install</em>. The highest search path is used together with a configurable folder (*sling/install* in this case). If a configuration is changed which already exists in the repository, then it depends where the original configuration is stored. If its under <em>/libs</em> a new configuration at the same path under <em>/apps</em> is created. Otherwise the configuration is directly modified. As JCR properties do not support all Java primitive types like Integer, the write back does not generate a node of type <em>sling:OsgiConfig</em> in the repository but a properties file as described in <a href="/documentation/bundles/configuration-installer-factory.html">Configuration Installer Factory</a>.</p> <p>Write back can be turned off by configuration.</p> <h3>Start Level Support</h3> -<p>If the parent folder of a bundle has a name which is a number, this is used as the start level (when installing the bundle for the first time, compare with <a href="https://issues.apache.org/jira/browse/SLING-2011";>SLING-2011</a>). So e.g. a bundle in the path <code>/libs/sling/install/15/somebundle.jar</code> is having the start level <strong>15</strong>.</p> +<p>If the parent folder of a bundle has a name which is a number, this is used as the start level (when installing the bundle for the first time, compare with <a href="https://issues.apache.org/jira/browse/SLING-2011";>SLING-2011</a>). So e.g. a bundle in the path <code>/libs/sling/install/15/somebundle.jar</code> is having the start level <strong>15</strong>. </p> <h1>Example</h1> <p>Here's a quick walkthrough of the JCR installer functionality.</p> <h2>Installation</h2> @@ -42,30 +42,63 @@ <p>We'll use the <a href="http://www.knopflerfish.org/releases/2.0.5/jars/desktop_awt/desktop_awt_all-2.0.0.jar";>Knopflerfish Desktop</a> bundle for this example, it is convenient as it displays a graphical user interface when started.</p> <p>We use <code>curl</code> to create content, to make it easy to reproduce the example by copying and pasting the <code>curl</code> commands. Any other way to create content in the repository will work, of course.</p> <p>By default, JCRInstall picks up bundles found in folders named <em>install</em> under <code>/libs</code> and <code>/apps</code>, so we start by creating such a folder:</p> -<p>curl -X MKCOL http://admin:admin@localhost:8888/apps/jcrtest curl -X MKCOL http://admin:admin@localhost:8888/apps/jcrtest/install</p> +<pre><code>curl -X MKCOL http://admin:admin@localhost:8888/apps/jcrtest +curl -X MKCOL http://admin:admin@localhost:8888/apps/jcrtest/install +</code></pre> <p>And we copy the bundle to install in that folder (a backslash in command lines means <em>continued on next line</em>):</p> -<p>curl -T desktop_awt_all-2.0.0.jar http://admin:admin@localhost:8888/apps/jcrtest/install/desktop_awt_all-2.0.0.jar</p> +<pre><code>curl -T desktop_awt_all-2.0.0.jar \ + http://admin:admin@localhost:8888/apps/jcrtest/install/desktop_awt_all-2.0.0.jar +</code></pre> <p>That's it. After 2-3 seconds, the bundle should be picked up by JCRInstall, installed and started. If this works you'll see a small <em>Knopflerfish Desktop</em> window on your desktop, and Sling's OSGi console can of course be used to check the details.</p> <p>Removing the bundle from the repository will cause it to be uninstalled, so:</p> -<p>curl -X DELETE http://admin:admin@localhost:8888/apps/jcrtest/install/desktop_awt_all-2.0.0.jar</p> +<pre><code>curl -X DELETE \ + http://admin:admin@localhost:8888/apps/jcrtest/install/desktop_awt_all-2.0.0.jar +</code></pre> <p>Should cause the <em>Knopflerfish Desktop</em> window to disappear as the bundle is uninstalled.</p> <h2>Install, modify and remove a configuration</h2> <p>JCRInstall installs OSGi configurations from nodes having the <em>sling:OsgiConfig</em> node type, found in folders named <em>install</em> under the installation roots (/apps and /libs).</p> <p>Let's try this feature by creating a configuration with two properties:</p> -<p>curl -F "jcr:primaryType=sling:OsgiConfig" -F foo=bar -F works=yes http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid</p> +<pre><code>curl \ + -F "jcr:primaryType=sling:OsgiConfig" \ + -F foo=bar -F works=yes \ + http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid +</code></pre> <p>And verify the contents of our config node:</p> -<p>curl http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid.json</p> +<pre><code>curl \ + http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid.json +</code></pre> <p>Which should display something like</p> -<p>{"foo":"bar", "jcr:created":"Wed Aug 26 2009 17:06:40GMT+0200", "jcr:primaryType":"sling:OsgiConfig","works":"yes"}</p> +<pre><code>{"foo":"bar", +"jcr:created":"Wed Aug 26 2009 17:06:40GMT+0200", +"jcr:primaryType":"sling:OsgiConfig","works":"yes"} +</code></pre> <p>At this point, JCRInstall should have picked up our new config and installed it. The logs would confirm that, but we can also use the OSGi console's config status page (http://localhost:8888/system/console/config) to check it. That page should now contain:</p> -<p>PID=some.config.pid BundleLocation=Unbound _jcr_config_path=jcrinstall:/apps/jcrtest/install/some.config.pid foo=bars service.pid=some.config.pid works=yes</p> +<pre><code>PID=some.config.pid + BundleLocation=Unbound + _jcr_config_path=jcrinstall:/apps/jcrtest/install/some.config.pid + foo=bars + service.pid=some.config.pid + works=yes +</code></pre> <p>Indicating that the configuration has been installed.</p> <p>Let's try modifying the configuration parameters:</p> -<p>curl -F works=updated -F even=more http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid</p> +<pre><code>curl \ + -F works=updated -F even=more \ + http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid +</code></pre> <p>And check the changes in the console page:</p> -<p>PID=some.config.pid BundleLocation=Unbound _jcr_config_path=jcrinstall:/apps/jcrtest/install/some.config.pid even=more foo=bars service.pid=some.config.pid works=updated</p> +<pre><code>PID=some.config.pid + BundleLocation=Unbound + _jcr_config_path=jcrinstall:/apps/jcrtest/install/some.config.pid + even=more + foo=bars + service.pid=some.config.pid + works=updated +</code></pre> <p>We can now delete the configuration node:</p> -<p>curl -X DELETE http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid</p> +<pre><code>curl -X DELETE \ + http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid +</code></pre> <p>And verify that the corresponding configuration is gone in the console page (after 1-2 seconds, like for all other JCRInstall operations).</p> <p>A node named like <code>o.a.s.foo.bar-a</code> uses <em>o.a.s.foo.bar</em> as its factory PID creating a configuration with an automatically generated PID. The value of <em>a</em> is stored as an alias in the OSGi installer to correlate the configuration object with the repository node.</p> <h1>Automated Tests</h1>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/3a935d04/documentation/bundles/log-tracers.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/log-tracers.html b/documentation/bundles/log-tracers.html index 149df21..2fb17a8 100644 --- a/documentation/bundles/log-tracers.html +++ b/documentation/bundles/log-tracers.html @@ -2,45 +2,61 @@ <head> <meta charset="utf-8"/> <title>Apache Sling on JBake</title> - <link rel="stylesheet" href="/res/css/site.css"/> - <link rel="stylesheet" href="/res/css/codehilite.css"/> + <link rel="stylesheet" href="/ng/res/css/site.css"/> + <link rel="icon" href="/ng/res/favicon.ico"/> <div class="title"> <div class="logo"> <a href="http://sling.apache.org";> - <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/> + <img border="0" alt="Apache Sling" src="/ng/res/logos/sling.svg"/> </a> </div><div class="header"> <a href="http://www.apache.org";> - <img border="0" alt="Apache" src="/res/logos/apache.png"/> + <img border="0" alt="Apache" src="/ng/res/logos/apache.png"/> </a> </div> </div> </head><body> <div class="menu"> - <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki";>Wiki</a><br/><a href="http://s.apache.org/sling.faq";>FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/";>License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk";>Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling";>Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html";>Become a Sponsor</a><br/><a href="https://donate.apache.org/";>Donate!</a><br/><a href="http://www.apache.org/foun dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong> + <strong><a href="/ng/documentation.html">Documentation</a></strong><br/><a href="/ng/documentation/getting-started.html">Getting Started</a><br/><a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/ng/documentation/development.html">Development</a><br/><a href="/ng/documentation/bundles.html">Bundles</a><br/><a href="/ng/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/ng/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki";>Wiki</a><br/><a href="http://s.apache.org/sling.faq";>FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/ng/apidocs/sling9/index.html">Sling 9</a><br/><a href="/ng/apidocs/sling8/index.html">Sling 8</a><br/><a href="/ng/apidocs/sling7/index.html">Sling 7</a><br/><a href="/ng/apidocs/sling6/index.html">Sling 6</a><br/><a href="/ng/apidocs/sling5/index.html">Sling 5</a><br/><a href="/ng/javadoc-io.html">Archive at javadoc.io</a><br/><p></p ><strong>Project info</strong><br/><a >href="/ng/downloads.cgi">Downloads</a><br/><a >href="http://www.apache.org/licenses/";>License</a><br/><a >href="/ng/contributing.html">Contributing</a><br/><a >href="/ng/news.html">News</a><br/><a href="/ng/links.html">Links</a><br/><a >href="/ng/project-information.html">Project Information</a><br/><a >href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/><a >href="http://ci.apache.org/builders/sling-trunk";>Build Server</a><br/><a >href="/ng/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a > href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/><a >href="git://git.apache.org/sling.git">Git</a><br/><a >href="https://github.com/apache/sling";>Github >Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a >href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/><a >href="http://www.apache.org/foundation/sponsorship.html";>Become a >Sponsor</a><br/><a href="https://donate.apache. org/">Donate!</a><br/><a href="http://www.apache.org/foundation/buy_stuff.html";>Buy Stuff</a><br/><p></p><strong><a href="/ng/sitemap.html">Site Map</a></strong> </div> <div class="main"> <div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Log Tracer</h1></header><p><a href="https://issues.apache.org/jira/browse/SLING-4739";>Log Tracer</a> provides support for enabling the logs for specific category at specific level and only for specific request. It provides a very fine level of control via config provided as part of HTTP request around how the logging should be performed for given category.</p> <p>This is specially useful for those parts of the system which are involved in every request. For such parts enabling the log at global level would flood the logs and create lots of noise. Using Tracer one can enable log for that request which is required to be probed.</p> <p>For e.g. determining what nodes are written for a given POST request can be simply done by including an extra request parameters.</p> -<p>curl -D - -u admin:admin -d "./jcr:content/jcr:title=Summer Collection" -d ":name=summer-collection" -d "./jcr:primaryType=sling:Folder" -d "./jcr:content/jcr:primaryType=nt:unstructured" -d "tracers=oak-writes" http://localhost:4502/content/dam/</p> +<pre><code>curl -D - -u admin:admin \ + -d "./jcr:content/jcr:title=Summer Collection" \ + -d ":name=summer-collection" \ + -d "./jcr:primaryType=sling:Folder" \ + -d "./jcr:content/jcr:primaryType=nt:unstructured" \ + -d "tracers=oak-writes" \ + http://localhost:4502/content/dam/ +</code></pre> <h2>Configuration</h2> <p><img src="/documentation/bundles/tracer-config.png" alt="Tracer Config" /></p> <p><strong>Note that by default Tracer would not be enabled and you would need to save the OSGi config to get it activated</strong></p> <p>Tracer support two ways to enable logging.</p> <h3>Tracer Sets</h3> <p>Tracer sets are collection of predefined logging categories matching specific area of an application. These can for now be configured as part of OSGi config</p> -<p>oak-query : org.apache.jackrabbit.oak.query.QueryEngineImpl;level=debug auth : org.apache.sling.auth;level=trace,org.apache.jackrabbit.oak.security</p> +<pre><code>oak-query : org.apache.jackrabbit.oak.query.QueryEngineImpl;level=debug +auth : org.apache.sling.auth;level=trace,org.apache.jackrabbit.oak.security +</code></pre> <p>The config is of following format</p> -<p>< set name > : <tracer config></p> +<pre><code>< set name > : <tracer config> +</code></pre> <p>Where the config is of following format</p> -<p>tracerConfig := loggerConfig ( ',' loggerConfig) * loggerConfig := loggerName (; attributes)* attributes := attributeName '=' attributeValue</p> +<pre><code>tracerConfig := loggerConfig ( ',' loggerConfig) * +loggerConfig := loggerName (; attributes)* +attributes := attributeName '=' attributeValue +</code></pre> <p>Currently following attributes are support</p> <ul> <li><code>level</code> - Either of TRACE, DEBUG, INFO, WARN, ERROR</li> - <li><code>caller</code> - Used to dump stacktrace of caller. It can have following value (_since 1.0.0_, <a href="https://issues.apache.org/jira/browse/SLING-5505";>SLING-5505</a>)</li> - <li><code>true</code> - Complete call stack for that logger would be included</li> - <li><code><depth></code> - Call stack upto depth (integer) would be included e.g. caller=5</li> - <li><code>caller-exclude-filter</code> - (optional) - '|' separated package prefixes which should not be included in the output. e.g. <em>org.apache.jackrabbit.oak.query.QueryImpl;caller=28;caller-exclude-filter="org.eclipse|org.felix"</em> this would exclude eclipse and felix packages from the resulting stack</li> + <li><code>caller</code> - Used to dump stacktrace of caller. It can have following value (_since 1.0.0_, <a href="https://issues.apache.org/jira/browse/SLING-5505";>SLING-5505</a>) + <ul> + <li><code>true</code> - Complete call stack for that logger would be included</li> + <li><code><depth></code> - Call stack upto depth (integer) would be included e.g. caller=5</li> + </ul> + </li> + <li><code>caller-exclude-filter</code> - (optional) - '|' separated package prefixes which should not be included in the output. e.g. <em>org.apache.jackrabbit.oak.query.QueryImpl;caller=28;caller-exclude-filter="org.eclipse|org.felix"</em> this would exclude eclipse and felix packages from the resulting stack</li> </ul> <h3>Performance Impact</h3> <p>Tracer makes use of <a href="http://logback.qos.ch/manual/filters.html#TurboFilter";>Logback TuboFilter</a> to intercept the logging calls and only enable them for those which are enabled via tracer config for the request. The filter is only registered for the duration of that request hence would avoid adding the cost for normal run.</p> @@ -51,9 +67,14 @@ <p>Sling provides support for recording recent requests which can be accessed via <a href="https://sling.apache.org/documentation/development/monitoring-requests.html";>Recent Requests Plugin</a>. It would list down the list of recent request and then on clicking them you can see the logs showed on the UI.</p> <p>The logging there is done via <a href="https://sling.apache.org/apidocs/sling5/org/apache/sling/api/request/RequestProgressTracker.html";>RequestProgressTracker</a> (<a href="http://dev.day.com/content/ddc/blog/2008/06/requestprogresstracker.html";>intro</a>). By default recent request plugin gets overflown as it captures request even for css, js files. To avoid that you can modify the config as part of <em>Sling Main Servlet</em> config</p> <p><img src="/documentation/bundles/sling-main-servlet-config.png" alt="Sling Main Servlet Config" /></p> -<p>Using a regex like <code>^.*.(?!jpg$|png$|js$|css$|woff$)[^.]+$</code> would avoid noise</p> +<p>Using a regex like <code>^.*\.(?!jpg$|png$|js$|css$|woff$)[^.]+$</code> would avoid noise</p> <p>With that you can see log entries like below at http://localhost:8080/system/console/requests?index=xxx</p> -<p>132 (2015-05-11 17:39:55) LOG [JCR] Query SELECT * FROM [granite:InboxItem] AS s where status='ACTIVE' ORDER BY s.startTime DESC 134 (2015-05-11 17:39:55) TIMER_END{53,/libs/cq/gui/components/endor/badge/badge.jsp#18} ... 1316 (2015-05-11 17:39:56) LOG JCR Query Count 3 1320 (2015-05-11 17:39:56) TIMER_END{1320,Request Processing} Request Processing</p> +<pre><code>132 (2015-05-11 17:39:55) LOG [JCR] Query SELECT * FROM [granite:InboxItem] AS s where status='ACTIVE' ORDER BY s.startTime DESC +134 (2015-05-11 17:39:55) TIMER_END{53,/libs/cq/gui/components/endor/badge/badge.jsp#18} +... +1316 (2015-05-11 17:39:56) LOG JCR Query Count 3 +1320 (2015-05-11 17:39:56) TIMER_END{1320,Request Processing} Request Processing +</code></pre> <h3>Server Logs</h3> <p>Further the logs also go to normal server side logs. By default they would go to the error.log. If you have routed the logs of specific categories to different files then normal Logback logging rules would apply</p> <h2>Usage</h2> @@ -66,13 +87,29 @@ <p>Param names</p> <ul> <li><code>tracers</code> - Tracer set names</li> - <li><code>tracerConfig</code> - Tracer config like org.apache.sling.auth;level=trace`</li> + <li><code>tracerConfig</code> - Tracer config like org.apache.sling.auth;level=trace` + <p>curl -u admin:admin http://localhost:4802/projects.html?tracerConfig=org.apache.sling</p> + </li> </ul> -<p>curl -u admin:admin http://localhost:4802/projects.html?tracerConfig=org.apache.sling</p> <p>Above request would turn on debug level logging (default level for tracer) for <code>org.apache.sling</code> category.</p> -<p>curl -D - -u admin:admin -d "./jcr:content/jcr:title=Summer Collection" -d ":name=summer-collection" -d "./jcr:primaryType=sling:Folder" -d "./jcr:content/jcr:primaryType=nt:unstructured" -d "tracers=oak-writes" http://localhost:4502/content/dam/</p> -<p>Above request would create a folder in Assets and for that we have enabled the <code>oak-writes</code> tracer. This would result in following output</p> -<p>2015-05-11 17:30:42,840 INFO admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] c.a.acs.acs-aem-tools-bundle - Service [4858] ServiceEvent REGISTERED 2015-05-11 17:30:42,846 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] Adding node [/content/dam/summer-collection] 2015-05-11 17:30:42,849 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] setPrimaryType 2015-05-11 17:30:42,849 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] Adding node [/content/dam/summer-collection/jcr:content] 2015-05-11 17:30:42,849 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] Setting property [/content/dam/summer-collection/jcr:content/jcr:title] 2015-05-11 17:30:42,850 TRACE ad min [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] setPrimaryType 2015-05-11 17:30:42,850 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] setPrimaryType 2015-05-11 17:30:42,856 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] save</p> +<pre><code>curl -D - -u admin:admin \ + -d "./jcr:content/jcr:title=Summer Collection" \ + -d ":name=summer-collection" \ + -d "./jcr:primaryType=sling:Folder" \ + -d "./jcr:content/jcr:primaryType=nt:unstructured" \ + -d "tracers=oak-writes" \ + http://localhost:4502/content/dam/ +</code></pre> +<p>Above request would create a folder in Assets and for that we have enabled the <code>oak-writes</code> tracer. This would result in following output </p> +<pre><code>2015-05-11 17:30:42,840 INFO admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] c.a.acs.acs-aem-tools-bundle - Service [4858] ServiceEvent REGISTERED +2015-05-11 17:30:42,846 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] Adding node [/content/dam/summer-collection] +2015-05-11 17:30:42,849 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] setPrimaryType +2015-05-11 17:30:42,849 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] Adding node [/content/dam/summer-collection/jcr:content] +2015-05-11 17:30:42,849 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] Setting property [/content/dam/summer-collection/jcr:content/jcr:title] +2015-05-11 17:30:42,850 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] setPrimaryType +2015-05-11 17:30:42,850 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] setPrimaryType +2015-05-11 17:30:42,856 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] save +</code></pre> <h3>Request Headers</h3> <p>Some request like initial authentication processing does not involve Sling MainServlet and hence for those request logging cannot be done to RequestProgressTracker. Instead we can just get logs enabled and route them to normal logging on server side. For that you need to use HTTP header</p> <ul> @@ -80,27 +117,88 @@ <li><code>Sling-Tracer-Config</code> - Tracer config</li> </ul> <p>So to enable authentication related logging following request can be sent</p> -<p>curl -D - -d "j_username=admin" -d "j_password=admin" -d "j_validate=true" -H "Sling-Tracer-Config : org.apache.sling.auth;level=trace,org.apache.jackrabbit.oak.security;level=trace" http://localhost:8080/libs/content/login.html/j_security_check</p> +<pre><code>curl -D - -d "j_username=admin" \ + -d "j_password=admin" \ + -d "j_validate=true" \ + -H "Sling-Tracer-Config : org.apache.sling.auth;level=trace,org.apache.jackrabbit.oak.security;level=trace" \ + http://localhost:8080/libs/content/login.html/j_security_check +</code></pre> <p>This would result in following server side logs</p> -<p>2015-05-11 17:34:56,531 INFO NA [qtp1395423247-193] c.a.acs.acs-aem-tools-bundle - Service [4859] ServiceEvent REGISTERED 2015-05-11 17:34:56,532 DEBUG NA [qtp1395423247-193] o.a.s.a.c.i.SlingAuthenticator - doHandleSecurity: Trying to get a session for null 2015-05-11 17:34:56,532 DEBUG NA [qtp1395423247-193] o.a.j.o.s.a.LoginContextProviderImpl - Found pre-authenticated subject: No further login actions required. 2015-05-11 17:34:56,532 DEBUG NA [qtp1395423247-193] o.a.j.o.s.a.LoginContextProviderImpl - Found pre-authenticated subject: No further login actions required. 2015-05-11 17:34:56,548 DEBUG NA [qtp1395423247-193] o.a.j.o.s.a.u.LoginModuleImpl - Adding Credentials to shared state. 2015-05-11 17:34:56,548 DEBUG NA [qtp1395423247-193] o.a.j.o.s.a.u.LoginModuleImpl - Adding login name to shared state.</p> +<pre><code>2015-05-11 17:34:56,531 INFO NA [qtp1395423247-193] c.a.acs.acs-aem-tools-bundle - Service [4859] ServiceEvent REGISTERED +2015-05-11 17:34:56,532 DEBUG NA [qtp1395423247-193] o.a.s.a.c.i.SlingAuthenticator - doHandleSecurity: Trying to get a session for null +2015-05-11 17:34:56,532 DEBUG NA [qtp1395423247-193] o.a.j.o.s.a.LoginContextProviderImpl - Found pre-authenticated subject: No further login actions required. +2015-05-11 17:34:56,532 DEBUG NA [qtp1395423247-193] o.a.j.o.s.a.LoginContextProviderImpl - Found pre-authenticated subject: No further login actions required. +2015-05-11 17:34:56,548 DEBUG NA [qtp1395423247-193] o.a.j.o.s.a.u.LoginModuleImpl - Adding Credentials to shared state. +2015-05-11 17:34:56,548 DEBUG NA [qtp1395423247-193] o.a.j.o.s.a.u.LoginModuleImpl - Adding login name to shared state. +</code></pre> <h2>Tracer Recording</h2> <p><em>Since 1.0.0 <a href="https://issues.apache.org/jira/browse/SLING-5459";>SLING-5459</a></em></p> <p>Apart from routing the logs to the server logs they can also be stored in memory and accessed in json form from Felix Web Console. By default support for recording is disabled and it needs to be explicitly enabled via OSGi config</p> <p>Recording features works as explained below</p> <ol> - <li>Client sends an HTTP request with header <code>Sling-Tracer-Record</code>â set to <code>true</code></li> + <li> + <p>Client sends an HTTP request with header <code>Sling-Tracer-Record</code>â set to <code>true</code></p> + <pre><code>curl -D - -u admin:admin \ + -H "Sling-Tracer-Record : true" \ + -d "./jcr:content/jcr:title=Summer Collection" \ + -d ":name=summer-collection" \ + -d "./jcr:primaryType=sling:Folder" \ + -d "./jcr:content/jcr:primaryType=nt:unstructured" \ + -d "tracers=oak-writes" \ + http://localhost:4802/content/dam/ +</code></pre> + </li> + <li> + <p>Server includes a request id as part of <code>Sling-Tracer-Request-Id</code> response headers </p> + <pre><code>HTTP/1.1 201 Created +Date: Wed, 27 Jan 2016 07:30:22 GMT +Sling-Tracer-Request-Id: 9b5b01f6-f269-47c3-a889-2dc8d4d7938f +X-Content-Type-Options: nosniff +X-Frame-Options: SAMEORIGIN +Location: /content/dam/summer-collection +Content-Type: text/html; charset=UTF-8 +Transfer-Encoding: chunked +</code></pre> + </li> + <li> + <p>The logs in json format can then be fetched from server at <code>/system/console/tracer</code> like http://localhost:8080/system/console/tracer/9b5b01f6-f269-47c3-a889-2dc8d4d7938f.json. </p> + <pre><code>curl -s -D - -H "Sling-Tracer-Record : true" -H "Sling-Tracers : oak-query" \ +-H "Sling-Tracer-Config : org.apache.jackrabbit.oak.query" \ +-u admin:admin http://localhost:4512/assets.html/content/dam -o /dev/null +</code></pre> + <p>Below is a json output for GET request</p> + <pre><code>:::javascript +{ + "method": "GET", + "time": 15140, + "timestamp": 1461574009024, + "requestProgressLogs": [ + "0 TIMER_START{Request Processing}", + "0 COMMENT timer_end format is {<elapsed msec>,<timer name>} <optional message>", + ... + ], + "queries": [{ + "query": "/jcr:root/etc/workflow/instances//element(*,app:Workflow)[@status='RUNNING'] order by @startTime descending", + "plan": "[app:Workflow] as [a] /* property status = RUNNING where ([a].[status] = 'RUNNING') and (isdescendantnode([a], [/etc/workflow/instances])) */", + "caller": "com.example.WorkflowManager.getWorkflowInstances(WorkflowManager.java:902)" + } + ], + "logs": [{ + "timestamp": 1461574022401, + "level": "DEBUG", + "logger": "org.apache.jackrabbit.oak.query.QueryEngineImpl", + "message": "Parsing xpath statement: /jcr:root/etc/workflow/instances//element(*,cq:Workflow)[@status='RUNNING'] order by @startTime descending", + "params": [ + "xpath", + "/jcr:root/etc/workflow/instances//element(*,cq:Workflow)[@status='RUNNING'] order by @startTime descending" + ] + } + ... + ] +} +</code></pre> + </li> </ol> -<p>curl -D - -u admin:admin -H "Sling-Tracer-Record : true" -d "./jcr:content/jcr:title=Summer Collection" -d ":name=summer-collection" -d "./jcr:primaryType=sling:Folder" -d "./jcr:content/jcr:primaryType=nt:unstructured" -d "tracers=oak-writes" http://localhost:4802/content/dam/</p> -<ol> - <li>Server includes a request id as part of <code>Sling-Tracer-Request-Id</code> response headers</li> -</ol> -<p>HTTP/1.1 201 Created Date: Wed, 27 Jan 2016 07:30:22 GMT Sling-Tracer-Request-Id: 9b5b01f6-f269-47c3-a889-2dc8d4d7938f X-Content-Type-Options: nosniff X-Frame-Options: SAMEORIGIN Location: /content/dam/summer-collection Content-Type: text/html; charset=UTF-8 Transfer-Encoding: chunked</p> -<ol> - <li>The logs in json format can then be fetched from server at <code>/system/console/tracer</code> like http://localhost:8080/system/console/tracer/9b5b01f6-f269-47c3-a889-2dc8d4d7938f.json.</li> -</ol> -<p>curl -s -D - -H "Sling-Tracer-Record : true" -H "Sling-Tracers : oak-query" -H "Sling-Tracer-Config : org.apache.jackrabbit.oak.query" -u admin:admin http://localhost:4512/assets.html/content/dam -o /dev/null</p> -<p>Below is a json output for GET request</p> -<p>:::javascript { "method": "GET", "time": 15140, "timestamp": 1461574009024, "requestProgressLogs": [ "0 TIMER_START{Request Processing}", "0 COMMENT timer_end format is {<elapsed msec>,<timer name>} <optional message>", ... ], "queries": [{ "query": "/jcr:root/etc/workflow/instances//element(*,app:Workflow)[@status='RUNNING'] order by @startTime descending", "plan": "[app:Workflow] as [a] /* property status = RUNNING where ([a].[status] = 'RUNNING') and (isdescendantnode([a], [/etc/workflow/instances])) */", "caller": "com.example.WorkflowManager.getWorkflowInstances(WorkflowManager.java:902)" } ], "logs": [{ "timestamp": 1461574022401, "level": "DEBUG", "logger": "org.apache.jackrabbit.oak.query.QueryEngineImpl", "message": "Parsing xpath statement: /jcr:root/etc/workflow/instances//element(*,cq:Workflow)[@status='RUNNING'] order by @startTime descending", "params": [ "xpath", "/jcr:root/etc/workflow/instances//element(*,cq:Workflow)[@status='RUNNING'] order by @startTime descen ding" ] } ... ] }</p> <p>JSON output consist of following sections</p> <ol> <li><code>method</code> - Request method</li> @@ -113,7 +211,13 @@ <p>The recordings are held in memory for 15 mins (per default setting) and can be seen listed at http://localhost:8080/system/console/tracer. Look into the OSGi config for more config options around this.</p> <h2>Installation</h2> <p>Download the bundle from <a href="http://sling.apache.org/downloads.cgi";>here</a> or use following Maven dependency</p> -<p>::xml <dependency> <groupId>org.apache.sling</groupId> <artifactId>org.apache.sling.tracer</artifactId> <version>1.0.0</version> </dependency></p></section></div></div> +<pre><code>::xml +<dependency> + <groupId>org.apache.sling</groupId> + <artifactId>org.apache.sling.tracer</artifactId> + <version>1.0.0</version> +</dependency> +</code></pre></section></div></div> <div class="footer"> <div class="timestamp"> TODO display revision number here http://git-wip-us.apache.org/repos/asf/sling-site/blob/3a935d04/documentation/bundles/managing-permissions-jackrabbit-accessmanager.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/managing-permissions-jackrabbit-accessmanager.html b/documentation/bundles/managing-permissions-jackrabbit-accessmanager.html index 1be99b1..ebcd6fb 100644 --- a/documentation/bundles/managing-permissions-jackrabbit-accessmanager.html +++ b/documentation/bundles/managing-permissions-jackrabbit-accessmanager.html @@ -2,22 +2,22 @@ <head> <meta charset="utf-8"/> <title>Apache Sling on JBake</title> - <link rel="stylesheet" href="/res/css/site.css"/> - <link rel="stylesheet" href="/res/css/codehilite.css"/> + <link rel="stylesheet" href="/ng/res/css/site.css"/> + <link rel="icon" href="/ng/res/favicon.ico"/> <div class="title"> <div class="logo"> <a href="http://sling.apache.org";> - <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/> + <img border="0" alt="Apache Sling" src="/ng/res/logos/sling.svg"/> </a> </div><div class="header"> <a href="http://www.apache.org";> - <img border="0" alt="Apache" src="/res/logos/apache.png"/> + <img border="0" alt="Apache" src="/ng/res/logos/apache.png"/> </a> </div> </div> </head><body> <div class="menu"> - <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki";>Wiki</a><br/><a href="http://s.apache.org/sling.faq";>FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/";>License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk";>Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling";>Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html";>Become a Sponsor</a><br/><a href="https://donate.apache.org/";>Donate!</a><br/><a href="http://www.apache.org/foun dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong> + <strong><a href="/ng/documentation.html">Documentation</a></strong><br/><a href="/ng/documentation/getting-started.html">Getting Started</a><br/><a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/ng/documentation/development.html">Development</a><br/><a href="/ng/documentation/bundles.html">Bundles</a><br/><a href="/ng/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/ng/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki";>Wiki</a><br/><a href="http://s.apache.org/sling.faq";>FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/ng/apidocs/sling9/index.html">Sling 9</a><br/><a href="/ng/apidocs/sling8/index.html">Sling 8</a><br/><a href="/ng/apidocs/sling7/index.html">Sling 7</a><br/><a href="/ng/apidocs/sling6/index.html">Sling 6</a><br/><a href="/ng/apidocs/sling5/index.html">Sling 5</a><br/><a href="/ng/javadoc-io.html">Archive at javadoc.io</a><br/><p></p ><strong>Project info</strong><br/><a >href="/ng/downloads.cgi">Downloads</a><br/><a >href="http://www.apache.org/licenses/";>License</a><br/><a >href="/ng/contributing.html">Contributing</a><br/><a >href="/ng/news.html">News</a><br/><a href="/ng/links.html">Links</a><br/><a >href="/ng/project-information.html">Project Information</a><br/><a >href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/><a >href="http://ci.apache.org/builders/sling-trunk";>Build Server</a><br/><a >href="/ng/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a > href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/><a >href="git://git.apache.org/sling.git">Git</a><br/><a >href="https://github.com/apache/sling";>Github >Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a >href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/><a >href="http://www.apache.org/foundation/sponsorship.html";>Become a >Sponsor</a><br/><a href="https://donate.apache. org/">Donate!</a><br/><a href="http://www.apache.org/foundation/buy_stuff.html";>Buy Stuff</a><br/><p></p><strong><a href="/ng/sitemap.html">Site Map</a></strong> </div> <div class="main"> <div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Managing permissions (jackrabbit.accessmanager)</h1></header><p>The <code>jackrabbit-accessmanager</code> bundle delivers a REST interface to manipulate users permissions in the JCR. After installing the <code>jackrabbit-accessmanager</code> bundle the REST services are exposed under the path of the node where you will manipulate the permissions for a user with a specific selector like <code>modifyAce</code>, <code>acl</code> and <code>deleteAce</code>. [TOC]</p> <h2>Privileges</h2> @@ -93,20 +93,24 @@ <li><em>numeric</em> - Place the target ACE at the specified numeric index. |</li> </ul> <p>Responses: | 200 | Success | | 500 | Failure, HTML (or JSON) explains failure. | Example with curl:</p> -<p>curl -FprincipalId=myuser -Fprivilege@jcr:read=granted http://localhost:8080/test/node.modifyAce.html</p> +<pre><code>curl -FprincipalId=myuser -Fprivilege@jcr:read=granted http://localhost:8080/test/node.modifyAce.html +</code></pre> <h2>Delete permissions</h2> <p>To delete permissions for a node POST a request to <code>/<path-to-the-node>.deleteAce.<html or json></code>. The following parameters are available:</p> <p>Responses: | 200 | Success | | 500 | Failure, HTML (or JSON) explains failure. | Example with curl:</p> -<p>curl -F:applyTo=myuser http://localhost:8080/test/node.deleteAce.html</p> +<pre><code>curl -F:applyTo=myuser http://localhost:8080/test/node.deleteAce.html +</code></pre> <h2>Get permissions</h2> <h3>Bound Permissions</h3> -<p>To get the permissions bound to a particular node in a json format for a node send a GET request to <code>/<path-to-the-node>.acl.json</code>.</p> +<p>To get the permissions bound to a particular node in a json format for a node send a GET request to <code>/<path-to-the-node>.acl.json</code>. </p> <p>Example:</p> -<p>http://localhost:8080/test/node.acl.json</p> +<pre><code>http://localhost:8080/test/node.acl.json +</code></pre> <h3>Effective Permissions</h3> -<p>To get the permissions which are effective for a particular node in a json format for a node send a GET request to <code>/<path-to-the-node>.eacl.json</code>.</p> +<p>To get the permissions which are effective for a particular node in a json format for a node send a GET request to <code>/<path-to-the-node>.eacl.json</code>. </p> <p>Example:</p> -<p>http://localhost:8080/test/node.eacl.json</p> +<pre><code>http://localhost:8080/test/node.eacl.json +</code></pre> <div class="note"> See section 16.3 of the JCR 2.0 specification for an explanation of the difference between bound and effective policies. </div> http://git-wip-us.apache.org/repos/asf/sling-site/blob/3a935d04/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.html ---------------------------------------------------------------------- diff --git a/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.html b/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.html index 3f7e530..1e0d644 100644 --- a/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.html +++ b/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.html @@ -2,34 +2,50 @@ <head> <meta charset="utf-8"/> <title>Apache Sling on JBake</title> - <link rel="stylesheet" href="/res/css/site.css"/> - <link rel="stylesheet" href="/res/css/codehilite.css"/> + <link rel="stylesheet" href="/ng/res/css/site.css"/> + <link rel="icon" href="/ng/res/favicon.ico"/> <div class="title"> <div class="logo"> <a href="http://sling.apache.org";> - <img border="0" alt="Apache Sling" src="/res/logos/sling.svg"/> + <img border="0" alt="Apache Sling" src="/ng/res/logos/sling.svg"/> </a> </div><div class="header"> <a href="http://www.apache.org";> - <img border="0" alt="Apache" src="/res/logos/apache.png"/> + <img border="0" alt="Apache" src="/ng/res/logos/apache.png"/> </a> </div> </div> </head><body> <div class="menu"> - <strong><a href="/documentation.html">Documentation</a></strong><br/><a href="/documentation/getting-started.html">Getting Started</a><br/><a href="/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/documentation/development.html">Development</a><br/><a href="/documentation/bundles.html">Bundles</a><br/><a href="/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki";>Wiki</a><br/><a href="http://s.apache.org/sling.faq";>FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/apidocs/sling9/index.html">Sling 9</a><br/><a href="/apidocs/sling8/index.html">Sling 8</a><br/><a href="/apidocs/sling7/index.html">Sling 7</a><br/><a href="/apidocs/sling6/index.html">Sling 6</a><br/><a href="/apidocs/sling5/index.html">Sling 5</a><br/><a href="/javadoc-io.html">Archive at javadoc.io</a><br/><p></p><strong>Project info</strong><br/><a h ref="/downloads.cgi">Downloads</a><br/><a href="http://www.apache.org/licenses/";>License</a><br/><a href="/contributing.html">Contributing</a><br/><a href="/news.html">News</a><br/><a href="/links.html">Links</a><br/><a href="/project-information.html">Project Information</a><br/><a href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/><a href="http://ci.apache.org/builders/sling-trunk";>Build Server</a><br/><a href="/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/><a href="git://git.apache.org/sling.git">Git</a><br/><a href="https://github.com/apache/sling";>Github Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/><a href="http://www.apache.org/foundation/sponsorship.html";>Become a Sponsor</a><br/><a href="https://donate.apache.org/";>Donate!</a><br/><a href="http://www.apache.org/foun dation/buy_stuff.html">Buy Stuff</a><br/><p></p><strong><a href="/sitemap.html">Site Map</a></strong> + <strong><a href="/ng/documentation.html">Documentation</a></strong><br/><a href="/ng/documentation/getting-started.html">Getting Started</a><br/><a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a><br/><a href="/ng/documentation/development.html">Development</a><br/><a href="/ng/documentation/bundles.html">Bundles</a><br/><a href="/ng/documentation/tutorials-how-tos.html">Tutorials & How-Tos</a><br/><a href="/ng/documentation/configuration.html">Configuration</a><p></p><a href="http://s.apache.org/sling.wiki";>Wiki</a><br/><a href="http://s.apache.org/sling.faq";>FAQ</a><br/><p></p><strong>API Docs</strong><br/><a href="/ng/apidocs/sling9/index.html">Sling 9</a><br/><a href="/ng/apidocs/sling8/index.html">Sling 8</a><br/><a href="/ng/apidocs/sling7/index.html">Sling 7</a><br/><a href="/ng/apidocs/sling6/index.html">Sling 6</a><br/><a href="/ng/apidocs/sling5/index.html">Sling 5</a><br/><a href="/ng/javadoc-io.html">Archive at javadoc.io</a><br/><p></p ><strong>Project info</strong><br/><a >href="/ng/downloads.cgi">Downloads</a><br/><a >href="http://www.apache.org/licenses/";>License</a><br/><a >href="/ng/contributing.html">Contributing</a><br/><a >href="/ng/news.html">News</a><br/><a href="/ng/links.html">Links</a><br/><a >href="/ng/project-information.html">Project Information</a><br/><a >href="https://issues.apache.org/jira/browse/SLING";>Issue Tracker</a><br/><a >href="http://ci.apache.org/builders/sling-trunk";>Build Server</a><br/><a >href="/ng/project-information/security.html">Security</a><br/><p></p><strong>Source</strong><br/><a > href="http://svn.apache.org/viewvc/sling/trunk";>Subversion</a><br/><a >href="git://git.apache.org/sling.git">Git</a><br/><a >href="https://github.com/apache/sling";>Github >Mirror</a><br/><p></p><strong>Sponsorship</strong><br/><a >href="http://www.apache.org/foundation/thanks.html";>Thanks</a><br/><a >href="http://www.apache.org/foundation/sponsorship.html";>Become a >Sponsor</a><br/><a href="https://donate.apache. org/">Donate!</a><br/><a href="http://www.apache.org/foundation/buy_stuff.html";>Buy Stuff</a><br/><p></p><strong><a href="/ng/sitemap.html">Site Map</a></strong> </div> <div class="main"> <div class="row"><div class="small-12 columns"><section class="wrap"><header><h1>Managing users and groups (jackrabbit.usermanager)</h1></header><p>The <code>jackrabbit-usermanager</code> bundle delivers a REST interface to create, update and delete users and groups in the JCR. After installing the <code>jackrabbit-usermanager</code> bundle all REST services are exposed under the path <code>/system/userManager</code>. Its interface for modifing/creating authorizables is similar to the <a href="/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html">SlingPostServlet</a>.</p> <p>For getting information about existing authorizables it provides all authorizables as Sling resources through its <code>AuthorizableResourceProvider</code> below <code>/system/userManager/user</code> and <code>/system/userManager/group</code>. Those resources can be exposed via the <a href="/documentation/bundles/rendering-content-default-get-servlets.html">Default GET Servlet</a>.</p> <p>[TOC]</p> <h2>List users</h2> -<p>To list existing users a GET request to the <code>/system/userManager/user</code> resource can be issued. Depending on the configuration of the <a href="/documentation/bundles/rendering-content-default-get-servlets.html">Default GET Servlet</a> and/or the availability of a Servlet or Script handling the <code>sling/users</code> resource type, a result may be delivered/</p> +<p>To list existing users a GET request to the <code>/system/userManager/user</code> resource can be issued. Depending on the configuration of the <a href="/documentation/bundles/rendering-content-default-get-servlets.html">Default GET Servlet</a> and/or the availability of a Servlet or Script handling the <code>sling/users</code> resource type, a result may be delivered/</p> <p>Example with curl and the default JSON rendering:</p> -<p>$ curl http://localhost:8080/system/userManager/user.tidy.1.json { "admin": { "memberOf": [], "declaredMemberOf": [] }, "anonymous": { "memberOf": [], "declaredMemberOf": [] } }</p> +<pre><code>$ curl http://localhost:8080/system/userManager/user.tidy.1.json +{ + "admin": { + "memberOf": [], + "declaredMemberOf": [] + }, + "anonymous": { + "memberOf": [], + "declaredMemberOf": [] + } +} +</code></pre> <h2>Get user</h2> <p><em>since version 2.0.8</em> The properties of a single user can be retrieved by sending a GET request to the user's resource at <code>/system/userManager/user/<username></code> where <code><username></code> would be replaced with the name of the user. Depending on the configuration of the <a href="/documentation/bundles/rendering-content-default-get-servlets.html">Default GET Servlet</a> and/or the availability of a Servlet or Script handling the <code>sling/user</code> resource type, a result may be delivered.</p> <p>Example with curl and the default JSON rendering:</p> -<p>$ curl http://localhost:8080/system/userManager/user/admin.tidy.1.json { "memberOf": [], "declaredMemberOf": [] }</p> +<pre><code>$ curl http://localhost:8080/system/userManager/user/admin.tidy.1.json +{ + "memberOf": [], + "declaredMemberOf": [] +} +</code></pre> <p>If a non-existing user is requested a <code>404/NOT FOUND</code> status is sent back.</p> <h2>Create user</h2> <p>To create a new user POST a request to <code>/system/userManager/user.create.<html or json></code>. The following parameters are available:</p> @@ -84,7 +100,9 @@ </tbody> </table> <p>Example with curl:</p> -<p>curl -F:name=myuser -Fpwd=password -FpwdConfirm=password -Fanyproperty1=value1 http://localhost:8080/system/userManager/user.create.html</p> +<pre><code>curl -F:name=myuser -Fpwd=password -FpwdConfirm=password -Fanyproperty1=value1 \ + http://localhost:8080/system/userManager/user.create.html +</code></pre> <h2>Update user</h2> <p>To update an existing user POST a request to <code>/system/userManager/user/username.update.<html or json></code>. You can NOT update the username or the password (see Change Password below) only the additional properties are updateable through this URL. The following parameters are available:</p> <table> @@ -142,7 +160,9 @@ </tbody> </table> <p>Example</p> -<p>curl -Fanyproperty1@Delete -Fproperty2=value2 http://localhost:8080/system/userManager/user/myuser.update.html</p> +<pre><code>curl -Fanyproperty1@Delete -Fproperty2=value2 \ + http://localhost:8080/system/userManager/user/myuser.update.html +</code></pre> <h2>Change password</h2> <p>To change a password of an existing user POST a request to <code>/system/userManager/user/username.changePassword.<html or json></code>. NOTE: since version 2.1.1, the oldPwd is optional if the current user is a user administrator. The following parameters are available:</p> <table> @@ -195,7 +215,9 @@ </tbody> </table> <p>Example</p> -<p>curl -FoldPwd=oldpassword -FnewPwd=newpassword -FnewPwdConfirm=newpassword http://localhost:8080/system/userManager/user/myuser.changePassword.html</p> +<pre><code>curl -FoldPwd=oldpassword -FnewPwd=newpassword -FnewPwdConfirm=newpassword \ + http://localhost:8080/system/userManager/user/myuser.changePassword.html +</code></pre> <h2>Delete user</h2> <p>To delete an existing user POST a request to <code>/system/userManager/user/username.delete.<html or json></code>. The following parameters are available:</p> <table> @@ -238,15 +260,44 @@ </tbody> </table> <p>Example</p> -<p>curl -Fgo=1 http://localhost:8080/system/userManager/user/myuser.delete.html</p> +<pre><code>curl -Fgo=1 http://localhost:8080/system/userManager/user/myuser.delete.html +</code></pre> <h2>List groups</h2> <p>To list existing groups a GET request to the <code>/system/userManager/group</code> resource can be sent. Depending on the configuration of the <a href="/documentation/bundles/rendering-content-default-get-servlets.html">Default GET Servlet</a> and/or the availability of a Servlet or Script handling the <code>sling/groups</code> resource type, a result may be delivered.</p> <p>Example with curl and the default JSON rendering:</p> -<p>$ curl http://localhost:8080/system/userManager/group.tidy.1.json { "UserAdmin": { "members": [], "declaredMembers": [], "memberOf": [], "declaredMemberOf": [] }, "GroupAdmin": { "members": [], "declaredMembers": [], "memberOf": [], "declaredMemberOf": [] }, "administrators": { "members": [], "declaredMembers": [], "memberOf": [], "declaredMemberOf": [] } }</p> +<pre><code>$ curl http://localhost:8080/system/userManager/group.tidy.1.json +{ + "UserAdmin": { + "members": [], + "declaredMembers": [], + "memberOf": [], + "declaredMemberOf": [] + }, + "GroupAdmin": { + "members": [], + "declaredMembers": [], + "memberOf": [], + "declaredMemberOf": [] + }, + "administrators": { + "members": [], + "declaredMembers": [], + "memberOf": [], + "declaredMemberOf": [] +} +} +</code></pre> <h2>Get group</h2> <p>The properties of a single group can be retrieved by sending a GET request to the group's resource at <code>/system/userManager/group/groupname</code> where <em>groupname</em> would be replaced with the name of the group. Depending on the configuration of the <a href="/documentation/bundles/rendering-content-default-get-servlets.html">Default GET Servlet</a> and/or the availability of a Servlet or Script handling the <code>sling/group</code> resource type, a result may be delivered.</p> <p>Example with curl and the default JSON rendering:</p> -<p>$ curl http://localhost:8080/system/userManager/group/administrators.tidy.1.json { "members": [], "declaredMembers": [], "memberOf": [], "declaredMemberOf": [] }</p> +<pre><code>$ curl http://localhost:8080/system/userManager/group/administrators.tidy.1.json +{ + "members": [], + "declaredMembers": [], + "memberOf": [], + "declaredMemberOf": [] +} +</code></pre> <p>If a non-existing group is requested a 404/NOT FOUND status is sent back.</p> <h2>Create group</h2> <p>To create a new group POST a request to <code>/system/userManager/group.create.<html or json></code>. The following parameters are available:</p> @@ -291,7 +342,9 @@ </tbody> </table> <p>Example with curl:</p> -<p>curl -F:name=mygroup -Fanyproperty1=value1 http://localhost:8080/system/userManager/group.create.html</p> +<pre><code>curl -F:name=mygroup -Fanyproperty1=value1 \ + http://localhost:8080/system/userManager/group.create.html +</code></pre> <h2>Update group</h2> <p>To update an existing group POST a request to <code>/system/userManager/group/groupname.update.<html or json></code>. You can NOT update the name of the group only the additional properties are updateable. The following parameters are available:</p> <table> @@ -349,7 +402,9 @@ </tbody> </table> <p>Example</p> -<p>curl -Fanyproperty1@Delete -Fproperty2=value2 -F ":member=/system/userManager/user/myuser" http://localhost:8080/system/userManager/group/mygroup.update.html</p> +<pre><code>curl -Fanyproperty1@Delete -Fproperty2=value2 -F ":member=/system/userManager/user/myuser" \ + http://localhost:8080/system/userManager/group/mygroup.update.html +</code></pre> <h2>Delete group</h2> <p>To delete an existing group POST a request to <code>/system/userManager/group/groupname.delete.<html or json></code>. The following parameters are available:</p> <table> @@ -392,7 +447,8 @@ </tbody> </table> <p>Example</p> -<p>curl -Fgo=1 http://localhost:8080/system/userManager/group/mygroup.delete.html</p> +<pre><code>curl -Fgo=1 http://localhost:8080/system/userManager/group/mygroup.delete.html +</code></pre> <h2>Automated Tests</h2> <p>The <a href="http://svn.apache.org/repos/asf/sling/trunk/launchpad/testing/src/test/java/org/apache/sling/launchpad/webapp/integrationtest/accessManager/";>launchpad/testing</a> module contains test classes for various operations of the <code>jackrabbit-usermanager</code>. Such tests run as part of our continuous integration process, to demonstrate and verify the behavior of the various operations, in a way that's guaranteed to be in sync with the actual Sling core code. If you have an idea for additional tests, make sure to let us know!</p> <h2>Permissions checking from scripts</h2> @@ -431,12 +487,31 @@ </tbody> </table> <p>Example:</p> -<p><% // lookup the service var privilegesInfo = sling.getService(Packages.org.apache.sling.jackrabbit.usermanager.AuthorizablePrivilegesInfo);</p> -<p>if (privilegesInfo.canAddUser(currentSession)) { //TODO: render the UI that allows the user to add a user here }</p> -<p>if (privilegesInfo.canAddGroup(currentSession)) { //TODO: render the UI that allows the user to add a group here }</p> -<p>if (privilegesInfo.canUpdateProperties(currentSession, "someUserId")) { //TODO: render the UI that allows the user to update the properties of the user here }</p> -<p>if (privilegesInfo.canRemove(currentSession, "someUserId")) { //TODO: render the UI that allows the user to remove the user here }</p> -<p>if (privilegesInfo.canUpdateGroupMembers(currentSession, "GroupName")) { //TODO: draw your UI that allows the user to update the group memebership here } %></p> +<pre><code><% + // lookup the service + var privilegesInfo = sling.getService(Packages.org.apache.sling.jackrabbit.usermanager.AuthorizablePrivilegesInfo); + + if (privilegesInfo.canAddUser(currentSession)) { + //TODO: render the UI that allows the user to add a user here + } + + if (privilegesInfo.canAddGroup(currentSession)) { + //TODO: render the UI that allows the user to add a group here + } + + if (privilegesInfo.canUpdateProperties(currentSession, "someUserId")) { + //TODO: render the UI that allows the user to update the properties of the user here + } + + if (privilegesInfo.canRemove(currentSession, "someUserId")) { + //TODO: render the UI that allows the user to remove the user here + } + + if (privilegesInfo.canUpdateGroupMembers(currentSession, "GroupName")) { + //TODO: draw your UI that allows the user to update the group memebership here + } +%> +</code></pre> <h2>Sample User Interface Implementation</h2> <p><em>Since Version 2.1.1</em></p> <p>A sample implementation of ui pages for user/group management is provided @ <a href="http://svn.apache.org/viewvc/sling/trunk/samples/usermanager-ui/";>http://svn.apache.org/viewvc/sling/trunk/samples/usermanager-ui/</a>.</p></section></div></div>
