http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/service-authentication.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/service-authentication.html b/documentation/the-sling-engine/service-authentication.html index f1ac4a5..81ba6ef 100644 --- a/documentation/the-sling-engine/service-authentication.html +++ b/documentation/the-sling-engine/service-authentication.html @@ -74,7 +74,7 @@ Service Authentication </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> -<h2>Problem</h2> +<h2><a href="#problem" name="problem">Problem</a></h2> <p>To access the data storage in the Resource Tree and/or the JCR Repository authentication is required to properly setup access control and guard sensitive data from unauthorized access. For regular request processing this authentication step is handled by the Sling <a href="/documentation/the-sling-engine/authentication.html">Authentication</a> subsystem.</p> <p>On the other hand there are also some background tasks to be executed with access to the resources. Such tasks cannot in general be configured with user names and passwords: Neither hard coding the passwords in the code nor having the passwords in – more or less – plain text in some configuration is considered good practice.</p> <p>To solve this problem for services to identify themselves and authenticate with special users properly configured to support those services.</p> @@ -85,7 +85,7 @@ <li>Allow services to use <em>service users</em> which have been specially configured for service level access (as is usually done on unixish systems)</li> <li>Allow administrators to configure the assignment of service users to services</li> </ul> -<h2>Concept</h2> +<h2><a href="#concept" name="concept">Concept</a></h2> <p>A <em>Service</em> is a piece or collection of functionality. Examples of services are the Sling queuing system, Tenant Administration, or some Message Transfer System. Each service is identified by a unique <em>Service Name</em>. Since a service will be implemented in an OSGi bundle (or a collection of OSGi bundles), services are named by the bundles providing them.</p> <p>A Service may be comprised of multiple parts, so each part of the service may be further identified by a <em>Subservice Name</em>. This Subservice Name is optional, though. Examples of <em>Subservice Name</em> are names for subsystems in a Message Transfer System such as accepting messages, queueing messages, delivering messages.</p> <p>Ultimately, the combination of the <em>Service Name</em> and <em>Subservice Name</em> defines the <em>Service ID</em>. It is the <em>Service ID</em> which is finally mapped to a Resource Resolver and/or JCR Repository user ID for authentication.</p> @@ -94,9 +94,9 @@ service-id = service-name [ ":" subservice-name ] . </code></pre> <p>The <code>service-name</code> is the symbolic name of the bundle providing the service.</p> -<h3>Example: Tenant Administration</h3> +<h3><a href="#example-tenant-administration" name="example-tenant-administration">Example: Tenant Administration</a></h3> <p>Tenant Administration mostly deals with creating and managing groups and some other user administration tasks. Instead of just using an administrative session for Tenant administration this feature could define itself as being the <code>tenant-admin</code> service and leverage a properly configured Tenant Administration account.</p> -<h3>Example: Mail Transfer System</h3> +<h3><a href="#example-mail-transfer-system" name="example-mail-transfer-system">Example: Mail Transfer System</a></h3> <p>Consider a Mail Transfer System which may be comprised of the following sub systems:</p> <ul> <li>Accepting mail for processing — for example the SMTP server daemon</li> @@ -106,13 +106,12 @@ service-id = service-name [ ":" subservice-name ] . <p>You could conceive that all these functions serve different purposes and thus should have different access rights to the repository to persist messages while they are being processed.</p> <p>Using the Service Authentication framework, the Mail Transfer System would be consituting the <code>mta</code> service. The sub systems would be called <code>smtp</code>, <code>queue</code>, and <code>deliver</code>.</p> <p>Thus the SMTP server daemon would be represented by a user for the <code>mta:smtp</code> Service. queueing with <code>mta:queue</code>, and delivery with <code>mta:deliver</code>. </p> -<h2>Implementation</h2> +<h2><a href="#implementation" name="implementation">Implementation</a></h2> <p>The implementation in Sling of the <em>Service Authentication</em> concept described above consists of three parts:</p> -<h3><code>ServiceUserMapper</code></h3> +<h3><a href="#serviceusermapper" name="serviceusermapper">ServiceUserMapper</a></h3> <p>The first part is a new OSGi Service <code>ServiceUserMapper</code>. The <code>ServiceUserMapper</code> service allows for mapping <em>Service IDs</em> comprised of the <em>Service Names</em> defined by the providing bundles and optional <em>Subservice Name</em> to ResourceResolver and/or JCR Repository user IDs. This mapping is configurable such that system administrators are in full control of assigning users to services.</p> <p>The <code>ServiceUserMapper</code> defines the following API:</p> -<pre><code>#!java -String getServiceUserID(Bundle bundle, String subServiceName); +<pre><code><!-- TODO syntax marker (#!java) disabled -->String getServiceUserID(Bundle bundle, String subServiceName); </code></pre> <p>The implementation uses two fallbacks in case no mapping can be found for the given subServiceName</p> <ol> @@ -120,31 +119,28 @@ String getServiceUserID(Bundle bundle, String subServiceName); <li>Use default user (if one is configured).</li> </ol> <p>In addition a service named <code>ServiceUserMapped</code> is registered for each bundle and subservice name for which a service user mapping is configured (<a href="https://issues.apache.org/jira/browse/SLING-4312";>SLING-4312</a>). By explicitly defining a (static) reference towards <code>ServiceUserMapped</code> one can defer starting the service until that service user mapping is available.</p> -<h3><code>ResourceResolverFactory</code></h3> +<h3><a href="#resourceresolverfactory" name="resourceresolverfactory">ResourceResolverFactory</a></h3> <p>The second part is support for service access to the Resource Tree. To this avail, the <code>ResourceResolverFactory</code> service is enhanced with a new factory method</p> -<pre><code>#!java -ResourceResolver getServiceResourceResolver(Map<String, Object> authenticationInfo) +<pre><code><!-- TODO syntax marker (#!java) disabled -->ResourceResolver getServiceResourceResolver(Map<String, Object> authenticationInfo) throws LoginException; </code></pre> <p>This method allows for access to the resource tree for services where the service bundle is the bundle actually using the <code>ResourceResolverFactory</code> service. The optional Subservice Name may be provided as an entry in the <code>authenticationInfo</code> map.</p> <p>In addition to having new API on the <code>ResourceResolverFactory</code> service to be used by services, the <code>ResourceProviderFactory</code> service is updated with support for Service Authentication: Now new API is required, though but additional properties are defined to convey the service to authenticate for.</p> <p>The default implementation leverages <code>ServiceUserMapper.getServiceUserID()</code> to resolve the right user id and throws a <code>LoginException</code> in case no mapping has been setup (and none of the fallbacks returned a user id != <code>null</code> either).</p> -<h3><code>SlingRepository</code></h3> +<h3><a href="#slingrepository" name="slingrepository">SlingRepository</a></h3> <p>The third part is an extension to the <code>SlingRepository</code>service interface to support JCR Repository access for services:</p> -<pre><code>#!java -Session loginService(String subServiceName, String workspace) +<pre><code><!-- TODO syntax marker (#!java) disabled -->Session loginService(String subServiceName, String workspace) throws LoginException, RepositoryException; </code></pre> <p>This method allows for access to the JCR Repository for services where the service bundle is the bundle actually using the <code>SlingRepository</code> service. The additional Subservice Name may be provided with the <code>subServiceName</code> parameter.</p> -<h2>Configuration</h2> -<h3>Service User Mappings</h3> +<h2><a href="#configuration" name="configuration">Configuration</a></h2> +<h3><a href="#service-user-mappings" name="service-user-mappings">Service User Mappings</a></h3> <p>For each service/subservice name combination an according mapping needs to be provided. The mapping binds a service name/subservice name to a JCR system user. This is configured through an OSGi configuration for the factory configuration with PID <code>org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl.amended</code> <a href="https://issues.apache.org/jira/browse/SLING-3578";>SLING-3578</a>. There you can set one configuration property named <code>user.mapping</code> getting a String array as value where each entry must stick to the following format:</p> <pre><code><service-name>[:<subservice-name>]=<authorizable id of a JCR system user>] </code></pre> <p>The according user must exist at the point in time where <code>ResourceResolverFactory.getServiceResourceResolver(...)</code> or <code>SlingRepository.loginService(...)</code> is called. If you rely on one of those methods in your <code>activate</code> method of an OSGi component you should make sure that you defer starting your OSGi component until the according service user mapping is in place. For that you can reference the OSGi service <code>ServiceUserMapped</code> (<a href="https://issues.apache.org/jira/browse/SLING-4312";>SLING-4312</a>), optionally with a target filter on property <code>subServiceName</code> (in case such a subservice name is used). The service <code>ServiceUserMapped</code> does not expose any methods but is only a marker interface exclusively used to defer starting of other OSGi components. However this waits only for the mapping configuration to be available, it does not wait for the service user itself to be available.</p> <p>Example OSGi DS Component</p> -<pre><code>:::java -@Component( +<pre><code>:<!-- TODO syntax marker (::java) disabled -->@Component( reference = { // this waits with the activation of this component until a service user mapping with the service name = current bundle's id and the sub service name 'my-subservice-name' is available. // you can leave out "target" if the sub service name is not used. @@ -156,7 +152,7 @@ class MyComponent { } </code></pre> <p>There is a default mapping applied if no OSGi configuration is available for the mapping. The default is: "serviceuser--" + bundleId [ + "--" + subservice-name]. Please note, that these default mappings are not represented as a ServiceUserMapped service and therefore the above mentioned reference does not work.</p> -<h2>Deprecation of administrative authentication</h2> +<h2><a href="#deprecation-of-administrative-authentication" name="deprecation-of-administrative-authentication">Deprecation of administrative authentication</a></h2> <p>Originally the <code>ResourceResolverFactory.getAdministrativeResourceResolver</code> and <code>SlingRepository.loginAdministrative</code> methods have been defined to provide access to the resource tree and JCR Repository. These methods proved to be inappropriate because they allow for much too broad access.</p> <p>Consequently these methods are being deprecated and will be removed in future releases of the service implementations.</p> <p>The following methods are deprecated:</p> @@ -166,7 +162,7 @@ class MyComponent { <li><code>SlingRepository.loginAdministrative</code></li> </ul> <p>The implementations we have in Sling's bundle will remain implemented in the near future. But there will be a configuration switch to disable support for these methods: If the method is disabled, a <code>LoginException</code> is always thrown from these methods. The JavaDoc of the methods is extended with this information.</p> -<h3>Whitelisting bundles for administrative login</h3> +<h3><a href="#whitelisting-bundles-for-administrative-login" name="whitelisting-bundles-for-administrative-login">Whitelisting bundles for administrative login</a></h3> <p>In order to be able to manage few (hopefully legit) uses of the above deprecated methods, a whitelisting mechanism was introduced with <a href="https://issues.apache.org/jira/browse/SLING-5135";>SLING-5153</a> (*JCR Base 2.4.2*).</p> <p>The recommended way to whitelist a bundle for administrative login is via a <em>whitelist fragment configuration</em>. It can be created as an OSGi factory configuration with the factoryPID <code>org.apache.sling.jcr.base.internal.LoginAdminWhitelist.fragment</code>. E.g. a typical configuration file might be called <code>org.apache.sling.jcr.base.internal.LoginAdminWhitelist.fragment-myapp.config</code> and could look as follows: </p> <pre><code>whitelist.name="myapp"
http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/servlets.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/servlets.html b/documentation/the-sling-engine/servlets.html index 16ab837..d5ede4e 100644 --- a/documentation/the-sling-engine/servlets.html +++ b/documentation/the-sling-engine/servlets.html @@ -75,7 +75,7 @@ </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> <p>See also <a href="/documentation/the-sling-engine/url-to-script-resolution.html">URL to Script Resolution</a> which explains how Sling maps URLs to a script or and servlet.</p> -<h2>Servlet Registration</h2> +<h2><a href="#servlet-registration" name="servlet-registration">Servlet Registration</a></h2> <p>Servlets can be registered as OSGi services. The following service reference properties are evaluated for Servlets defined as OSGi services of type <code>javax.servlet.Servlet</code> (all those property names are defined in <code>org.apache.sling.api.servlets.ServletResolverConstants</code> (since API 2.15.2) or <code>org.apache.sling.servlets.resolver.internal.ServletResolverConstants</code> (before API 2.15.2)):</p> <table> <thead> @@ -115,7 +115,7 @@ <p>For a Servlet registered as an OSGi service to be used by the Sling Servlet Resolver, either one or both of the <code>sling.servlet.paths</code> or the <code>sling.servlet.resourceTypes</code> service reference properties must be set. If neither is set, the Servlet service is ignored.</p> <p>Each path to be used for registration - either from the <code>sling.servlet.paths</code> property or constructed from the other <code>sling.servlet.\*</code> properties - must be absolute. Any relative path is made absolute by prefixing it with a root path. This prefix may be set with the <code>sling.servlet.prefix</code> service registration property. If this property is not set, the first entry in the <code>ResourceResolver</code> search path for the <code>ResourceResolver.getResource(String)</code> method is used as the prefix. If this entry cannot be derived, a simpe slash - <code>/</code> - is used as the prefix.</p> <p>If <code>sling.servlet.methods</code> is not specified, the servlet is only registered for handling GET and HEAD requests. Make sure to list all methods you want to be handled by this servlet.</p> -<h3>Caveats when binding servlets by path</h3> +<h3><a href="#caveats-when-binding-servlets-by-path" name="caveats-when-binding-servlets-by-path">Caveats when binding servlets by path</a></h3> <p>Binding servlets by paths has several disadvantages when compared to binding by resource types, namely:</p> <ul> <li>path-bound servlets cannot be access controlled using the default JCR repository ACLs</li> @@ -124,7 +124,7 @@ <li>the mapping is not transparent to a developer looking just at the repository</li> </ul> <p>Given these drawbacks it is strongly recommended to bind servlets to resource types rather than paths. </p> -<h3>Registering a Servlet using Java Annotations</h3> +<h3><a href="#registering-a-servlet-using-java-annotations" name="registering-a-servlet-using-java-annotations">Registering a Servlet using Java Annotations</a></h3> <p>If you are working with the default Apache Sling development stack you can either use </p> <ul> <li><a href="https://osgi.org/javadoc/r6/cmpn/org/osgi/service/component/annotations/package-summary.html";>OSGi DS annotations</a> (introduced with DS 1.2/OSGi 5, properly supported since <a href="https://github.com/bndtools/bndtools/wiki/Changes-in-3.0.0";>bnd 3.0</a>, being used in <a href="http://felix.apache.org/documentation/subprojects/apache-felix-maven-bundle-plugin-bnd.html";>maven-bundle-plugin 3.0.0</a>) or</li> @@ -134,8 +134,7 @@ <ol> <li> <p>OSGi DS annotations (recommended)</p> - <pre><code>:::java -@Component( + <pre><code>:<!-- TODO syntax marker (::java) disabled -->@Component( service = { Servlet.class }, property = { SLING_SERVLET_RESOURCE_TYPES + "=/apps/my/type" @@ -156,8 +155,7 @@ public class MyServlet extends SlingSafeMethodsServlet { </li> <li> <p>The <code>@SlingServlet</code> annotation (evaluated by maven-scr-plugin)</p> - <pre><code>:::java -@SlingServlet( + <pre><code>:<!-- TODO syntax marker (::java) disabled -->@SlingServlet( resourceTypes = "/apps/my/type", selectors = "hello", extensions = "html", @@ -172,11 +170,11 @@ public class MyServlet extends SlingSafeMethodsServlet { </code></pre> </li> </ol> -<h3>Automated tests</h3> +<h3><a href="#automated-tests" name="automated-tests">Automated tests</a></h3> <p>The <a href="http://svn.apache.org/repos/asf/sling/trunk/launchpad/test-services/";>launchpad/test-services</a> module contains test servlets that use various combinations of the above properties.</p> <p>The <a href="http://svn.apache.org/repos/asf/sling/trunk/launchpad/integration-tests/";>launchpad/integration-tests</a> module contains a number of tests (like the [ExtensionServletTest|http://svn.apache.org/repos/asf/sling/trunk/launchpad/integration-tests/src/main/java/org/apache/sling/launchpad/webapp/integrationtest/servlets/resolution/ExtensionServletTest.java] for example) that verify the results.</p> <p>Such tests run as part of our continuous integration process, to demonstrate and verify the behavior of the various servlet registration mechanisms, 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> -<h3>Example: Registration by Path</h3> +<h3><a href="#example-registration-by-path" name="example-registration-by-path">Example: Registration by Path</a></h3> <pre><code>sling.servlet.paths = [ "/libs/sling/sample/html", "/libs/sling/sample/txt" ] sling.servlet.selectors = [ "img" ] sling.servlet.extensions = [ "html", "txt", "json" ] @@ -187,7 +185,7 @@ sling.servlet.extensions = [ "html", "txt", "json" <li><code>/libs/sling/sample/txt</code></li> </ul> <p>The registration properties <code>sling.servlet.selectors</code> and <code>sling.servlet.extensions</code> <em>are ignored</em> because the servlet is registered only by path (only <code>sling.servlet.paths</code> property is set).</p> -<h3>Example: Registration by Resource Type etc.</h3> +<h3><a href="#example-registration-by-resource-type-etc-" name="example-registration-by-resource-type-etc-">Example: Registration by Resource Type etc.</a></h3> <pre><code>sling.servlet.resourceTypes = [ "sling/unused" ] sling.servlet.selectors = [ "img", "tab" ] sling.servlet.extensions = [ "html", "txt", "json" ] @@ -203,7 +201,7 @@ sling.servlet.extensions = [ "html", "txt", "json" </ul> <p>As explained the Servlet is registered for each permutation of the resource types, selectors and extension. See above at the explanation of <code>sling.servlet.prefix</code> how <code><prefix></code> is defined.</p> <p>It is more common to register for absolute resource types or at least explicitly define <code>sling.servlet.prefix</code> as well, because otherwise you are in most cases not sure under which absolute path the Servlet is registered (and therefore by which other paths it might get overwritten).</p> -<h3>Servlet Lifecycle Issues</h3> +<h3><a href="#servlet-lifecycle-issues" name="servlet-lifecycle-issues">Servlet Lifecycle Issues</a></h3> <p>The Servlet API specification states the following with respect to the life cycle of Servlets:</p> <blockquote> <p>The servlet container calls the init method exactly once after instantiating the servlet.</p> @@ -215,11 +213,11 @@ sling.servlet.extensions = [ "html", "txt", "json" </ul> <p>So Sling has not way of making sure a Servlet is only initialized and destroyed once in the life time of the Servlet object instance.</p> <p>The provider of the Servlet service on the other can cope with this situation by making sure to drop the servlet instance once it is destroyed. The mechanism helping the provider here is the OSGi Service Factory.</p> -<h2>Scripts are Servlets</h2> +<h2><a href="#scripts-are-servlets" name="scripts-are-servlets">Scripts are Servlets</a></h2> <p>The Sling API defines a <code>SlingScript</code> interface which is used to represent (executable) scripts inside of Sling. This interface is implemented in the <code>scripting/core</code> bundle in the <code>DefaultSlingScript</code> class which also implements the <code>javax.servlet.Servlet</code>.</p> <p>To further simplify the access to scripts from the Resource tree, the <code>scripting/core</code> bundle registers an <code>AdapterFactory</code> to adapt Resources to Scripts and Servlets (the <code>SlingScriptAdapterFactory</code>). In fact the adapter factory returns instances of the <code>DefaultSlingScript</code> class for both Scripts and Servlets.</p> <p>From the perspective of the Servlet resolver, scripts and servlets are handled exactly the same. In fact, internally, Sling only handles with Servlets, whereas scripts are packed inside a Servlet wrapping and representing the script.</p> -<h2>Default Servlet(s)</h2> +<h2><a href="#default-servlet-s-" name="default-servlet-s-">Default Servlet(s)</a></h2> <p>As explained in the Resolution Process section above, a default Servlet is selected if no servlet (or script) for the current resource type can be found. To make the provisioning of a default Servlet as versatile as provisioning per resource type Servlets (or scripts), the default Servlet is selected with just a special resource type <code>sling/servlet/default</code>.</p> <p>The actual Servlet or Script called as the default Servlet is resolved exactly the same way as for any resource type. That is, also for the default Servlet selection, the request selectors and extension or method are considered. Also, the Servlet may be a Servlet registered as an OSGi service or it may be a Script stored in the repository or provided by any bundle.</p> <p>Finally, if not even a registered default Servlet may be resolved for the request, because none has been registered, the <code>servlets/resolver</code> bundle provides a fall back the <code>DefaultServlet</code> with the following functionality:</p> @@ -227,11 +225,11 @@ sling.servlet.extensions = [ "html", "txt", "json" <li>If an <code>NonExistingResource</code> was created for the request the <code>DefaultServlet</code> sends a 404 (Not Found)</li> <li>Otherwise the <code>DefaultServlet</code> sends a 500 (Internal Server Error), because normally at least a <code>NonExistingResource</code> should be created</li> </ul> -<h2>OptingServlet interface</h2> +<h2><a href="#optingservlet-interface" name="optingservlet-interface">OptingServlet interface</a></h2> <p>If a registered servlet implements the OptingServlet interface, Sling uses that servlet's <code>accepts(SlingHttpServletRequest request)</code> method to refine the servlet resolution process.</p> <p>In this case, the servlet is only selected for processing the current request if its <code>accept</code> method returns true.</p> <p>While an opting servlet seems to be a nice way of picking the right servlet to process the request, the use of an opting servlet is not recommended: the main reason is that it complicates the request processing, makes it less transparent what is going on during a request and prevents optimizations like caching the script resolution in an optimal manner. The other static options are usually sufficient for all use cases.</p> -<h2>Error Handler Servlet(s) or Scripts</h2> +<h2><a href="#error-handler-servlet-s-or-scripts" name="error-handler-servlet-s-or-scripts">Error Handler Servlet(s) or Scripts</a></h2> <p>Error handling support is described on the <a href="/documentation/the-sling-engine/errorhandling.html">Errorhandling</a> page.</p></section></div></div> <div class="footer"> <div class="trademarkFooter"> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/sling-api-crud-support.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/sling-api-crud-support.html b/documentation/the-sling-engine/sling-api-crud-support.html index aa28f7d..212056c 100644 --- a/documentation/the-sling-engine/sling-api-crud-support.html +++ b/documentation/the-sling-engine/sling-api-crud-support.html @@ -74,7 +74,7 @@ Sling API CRUD Support </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> -<h2>Apache Sling API Support</h2> +<h2><a href="#apache-sling-api-support" name="apache-sling-api-support">Apache Sling API Support</a></h2> <p>As of version 2.3.0, the Sling API provides full Create Read Update Delete (CRUD) features. CRUD support is provided by the addition of the following methods to the ResourceResolver:</p> <ul> <li><a href="https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#delete-org.apache.sling.api.resource.Resource-";>void delete(Resource resource) throws PersistenceException</a></li> @@ -85,9 +85,9 @@ <li><a href="https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#refresh--";>void refresh()</a></li> </ul> <p>Which provide the ability to create and delete resources as well as the addition of the ModifiableValueMap interface which is similar to the ValueMap interface, but allows for updating properties on a resource.</p> -<h2>Comparing Sling API CRUD to Sling Post Servlet</h2> +<h2><a href="#comparing-sling-api-crud-to-sling-post-servlet" name="comparing-sling-api-crud-to-sling-post-servlet">Comparing Sling API CRUD to Sling Post Servlet</a></h2> <p>Here are some examples of common operations performed using the Sling Post Servlet and Sling API CRUD support. Note, the examples are derived from the <a href="http://dev.day.com/content/ddc/blog/2008/07/cheatsheet/_jcr_content/images/cheatsheet/back.png";>SlingPostServlet Cheatsheet</a>.</p> -<h3>Updating a Property</h3> +<h3><a href="#updating-a-property" name="updating-a-property">Updating a Property</a></h3> <p>Update /myresource, setting the title and body:</p> <p><strong>Sling Post Servlet</strong></p> <pre><code><form action="/myresource" method="POST"> @@ -102,7 +102,7 @@ properties.put("title", {TITLE}); properties.put("body", {BODY}); resourceResolver.commit(); </code></pre> -<h3>Create New Resource</h3> +<h3><a href="#create-new-resource" name="create-new-resource">Create New Resource</a></h3> <p>Create a new resource below /myresource</p> <p><strong>Sling Post Servlet</strong></p> <pre><code><form action="/myresource/" method="POST"> @@ -117,7 +117,7 @@ properties.put("sling:resourceType", "myapp/components/mytype&quo Resource dummy = resourceResolver.create(myResource, "dummy", properties); resourceResolver.commit(); </code></pre> -<h3>Remove a Property</h3> +<h3><a href="#remove-a-property" name="remove-a-property">Remove a Property</a></h3> <p>Remove the property title</p> <p><strong>Sling Post Servlet</strong></p> <pre><code><form action="/myresource" method="POST"> @@ -130,7 +130,7 @@ ModifiableValueMap properties = myResource.adaptTo(ModifiableValueMap.class); properties.remove("title"); resourceResolver.commit(); </code></pre> -<h3>Copy a Resource</h3> +<h3><a href="#copy-a-resource" name="copy-a-resource">Copy a Resource</a></h3> <p>Copy the resource /myresource to /myresource2</p> <p><strong>Sling Post Servlet</strong></p> <pre><code><form action="/myresource" method="POST"> @@ -144,7 +144,7 @@ resourceResolver.commit(); Resource myResource2 = resourceResolver.create(null, "myresource2", properties); resourceResolver.commit(); </code></pre> -<h3>Move a Resource</h3> +<h3><a href="#move-a-resource" name="move-a-resource">Move a Resource</a></h3> <p>Move the resource /myresource2 to /myresource3</p> <p><strong>Sling Post Servlet</strong></p> <pre><code><form action="/myresource2" method="POST"> @@ -159,7 +159,7 @@ Resource myResource3 = resourceResolver.create(null, "myresource3", pr resourceResolver.delete(myResource2); resourceResolver.commit(); </code></pre> -<h3>Setting non-String Value</h3> +<h3><a href="#setting-non-string-value" name="setting-non-string-value">Setting non-String Value</a></h3> <p>Set the property date to a particular date</p> <p><strong>Sling Post Servlet</strong></p> <pre><code><form action="/myresource3" method="POST"> @@ -174,7 +174,7 @@ ModifiableValueMap properties = myResource3.adaptTo(ModifiableValueMap.class); properties.put("date", calendar); resourceResolver.commit(); </code></pre> -<h3>Delete a Resource</h3> +<h3><a href="#delete-a-resource" name="delete-a-resource">Delete a Resource</a></h3> <p>Delete the resource /myresource</p> <p><strong>Sling Post Servlet</strong></p> <pre><code><form action="/myresource" method="POST"> @@ -186,7 +186,7 @@ resourceResolver.commit(); resourceResolver.delete(myResource); resourceResolver.commit(); </code></pre> -<h2>Value Class Support</h2> +<h2><a href="#value-class-support" name="value-class-support">Value Class Support</a></h2> <div class="info"> Please note, this information is specific to the Sling JCR Resource implementation provided by the Apache Sling project. Other implementations may have different value class support. </div> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/sling-properties.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/sling-properties.html b/documentation/the-sling-engine/sling-properties.html index 13d9e70..1d8dc21 100644 --- a/documentation/the-sling-engine/sling-properties.html +++ b/documentation/the-sling-engine/sling-properties.html @@ -76,7 +76,7 @@ <p>With the exception of the Sling setup properties (<code>sling.home</code>, <code>sling.launchpad</code>, and <code>sling.properties</code>) all properties can be set on the command line using the <code>-D</code> command line option or in the <code>sling.properties</code> file. Properties defined on the command line or in the <code>web.xml</code> file always overwrite properties in the <code>sling.properties</code> file.</p> <p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> -<h2>Sling Setup Properties</h2> +<h2><a href="#sling-setup-properties" name="sling-setup-properties">Sling Setup Properties</a></h2> <table> <thead> <tr> @@ -106,7 +106,7 @@ </tr> </tbody> </table> -<h2>Server Control Port Properties</h2> +<h2><a href="#server-control-port-properties" name="server-control-port-properties">Server Control Port Properties</a></h2> <table> <thead> <tr> @@ -125,7 +125,7 @@ </tbody> </table> <p>| <code>sling.control.action</code> | -- | Action to execute. This is the same as specifying <code>start</code>, <code>status</code>, or <code>stop</code> on the command line. This property is only used by the Standalone Sling Application. | Launchpad |</p> -<h2>Logging Configuration</h2> +<h2><a href="#logging-configuration" name="logging-configuration">Logging Configuration</a></h2> <p>Logging configuration defined by these properties sets up initial configuration for the Sling Commons Log bundle. This configuration is used as long as there is no configuration from the Configuration Admin Service for the service PID <code>org.apache.sling.commons.log.LogManager</code>.</p> <table> <thead> @@ -169,7 +169,7 @@ </tbody> </table> <p>See <a href="http://sling.apache.org/site/logging.html";>Logging</a> for full information on configuring the Sling Logging system.</p> -<h2>Http Service Properties</h2> +<h2><a href="#http-service-properties" name="http-service-properties">Http Service Properties</a></h2> <table> <thead> <tr> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/the-sling-launchpad.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/the-sling-launchpad.html b/documentation/the-sling-engine/the-sling-launchpad.html index 42de85d..b8785f2 100644 --- a/documentation/the-sling-engine/the-sling-launchpad.html +++ b/documentation/the-sling-engine/the-sling-launchpad.html @@ -75,7 +75,7 @@ </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> <p>This tries to explain how exactly the Sling Launchpad works, what constitutes the Sling Launchpad and how you can use the Sling Launchpad to custom create you Sling launchers. For a view behind the scenes of the Sling Launchpad Base module (the actual launcher) you might want to refer to the <a href="/documentation/development/embedding-sling.html">Embedding Sling</a> page.</p> -<h2>Sling Home</h2> +<h2><a href="#sling-home" name="sling-home">Sling Home</a></h2> <p>Since Sling requires some space on the filesystem to store various files Sling has to know where this filesystem space is located.</p> <p>The following is a list of uses for the Sling Home directory:</p> <ul> @@ -87,7 +87,7 @@ <li><code>oak</code> - The directory in which the Apache Jackrabbit Oak JCR Repository is started ( only applicable when using Apache Jackrabbit Oak with the SegmentNodeStoreBackend ). This is only available for Sling Launchpad 8 or newer.</li> <li><code>logs</code> -- Contains the log files generated by Sling. By default this contains the error.log and its rotated generations.</li> </ul> -<h2>Command Line Options</h2> +<h2><a href="#command-line-options" name="command-line-options">Command Line Options</a></h2> <p>The Java Standalone Application supports a number of command line options, which influence the operation of the launch process.</p> <table> <thead> @@ -177,7 +177,7 @@ <li>The <code>SLING_HOME</code> environment variable</li> <li>If none of the above resolves to a non-null value, the default value of <code>sling</code> is assumed</li> </ol> -<h3>Control Port</h3> +<h3><a href="#control-port" name="control-port">Control Port</a></h3> <p>When starting the Sling Standalone Application with the <code>start</code> command line option, a TCP control port is opened to receive simple commands which allow for stopping an instance and getting thread dumps.</p> <p>Currently supported commands are</p> <ul> @@ -217,11 +217,11 @@ mdsryh1k5fpcgvm7suqnckxkr7fvluzv stop OK Connection closed by foreign host. </code></pre> -<h3>Shutdown Hook</h3> +<h3><a href="#shutdown-hook" name="shutdown-hook">Shutdown Hook</a></h3> <p>By default the Sling Launchpad standalone application installs a Shutdown Hook with the Java Runtime to make sure the framework is properly terminated in case of a Java termination. In some situations or setups you want to control shutdown of Sling yourselves, so Sling supports a command line option <code>-n</code> to prevent the installation of a shutdown hook.</p> <p>Apart from the command line option, the <code>sling.shutdown.hook</code> system property is also supported: If this property is set to <code>true</code> or is not set at all the shutdown hook is installed as expected. If the property is set to anything other than <code>true</code>, e.g. <code>false</code>, the shutdown hook is not installed.</p> <p>If you are embedding the Sling Launchpad application's <code>Main</code> class, the <code>sling.shutdown.hook</code> property can also be set as a member of the <code>props</code> map handed to the <code>Main</code> constructor.</p> -<h2>Servlet Parameters</h2> +<h2><a href="#servlet-parameters" name="servlet-parameters">Servlet Parameters</a></h2> <p>The Web Application does not require specific servlet parameters. Those which are specified are used to overwrite any properties with the same name from the <code>sling.properties</code> file. One exception to this rule is the <code>sling.home</code> parameter, which is used to set the value of the <code>sling.home</code> property. If no parameter with this name is defined the Sling home directory is derived from the context path at which the Sling Web Application is registered.</p> <p>The <code>sling.home</code> folders for Sling Web Applications without the <code>sling.home</code> servlet parameter are all located in the <code>sling</code> folder in the current working directory as reported by the <code>user.dir</code> system property. The name of the actual directory is derived from the Web Application Context Path by replacing all slash characters <code>/</code> by underscore characters <code>_</code>. For the root context a single underscore character <code>_</code> is used.</p> <p>Examples:</p> @@ -271,14 +271,14 @@ Connection closed by foreign host. </tr> </tbody> </table> -<h2>sling.properties</h2> +<h2><a href="#sling-properties" name="sling-properties">sling.properties</a></h2> <p>The <code>sling.properties</code> file contains the initial setup of the Sling Application and the OSGi framework. Some of the parameters are required and should not be modified without a very good reason. Some parameters may be freely modified to your needs. Please see the inlined comment in the <code>sling.properties</code> file installed when Sling is first started.</p> <p>One thing to note is, that the <code>sling.properties</code> file is a simple Java Properties file with support for property references. That is, the value of properties may refer other property values by means of the well known <code>${name}</code> notation. Such property references may even be nested as in</p> <pre><code>java.packages=${jre-${java.specification.version}} </code></pre> -<h2>Components</h2> +<h2><a href="#components" name="components">Components</a></h2> <p>The Sling Launchapd consists of <em>Launchbad Base</em> project and three additional projects which ultimately create a Standalone Java Application and a Web Appliction with standard parts of Sling.</p> -<h3>Launchpad Base</h3> +<h3><a href="#launchpad-base" name="launchpad-base">Launchpad Base</a></h3> <p>The <em>Launchpad Base</em> projects creates the following artifacts, which are required in actual setups to get a Sling application:</p> <ul> <li> @@ -293,7 +293,7 @@ Connection closed by foreign host. <p><em>Source JAR</em> -- The secondary artifact with the classifier <em>sources</em> is simple the source of the <em>Launchpad Base</em> project.</p></li> </ul> <p>To build a very basic Sling launcher, the <em>Launchpad Base</em> is actually all you need. But to really glue this together and get a usable system, some more work is required. Lets see how the additionaly projects <em>Launchpad Bundles</em>, <em>Launchpad App</em>, and <em>Launchpad WebApp</em> get to that.</p> -<h3>Launchpad App and Launchpad WebApp</h3> +<h3><a href="#launchpad-app-and-launchpad-webapp" name="launchpad-app-and-launchpad-webapp">Launchpad App and Launchpad WebApp</a></h3> <p>The <em>Launchpad App</em> and <em>Launchpad WebApp</em> bundles are actually projects which just glue together artifacts from the Launchpad projects. There is nothing special about them. Here's what is done:</p> <ul> <li>Take the appropriate secondary artifact from the <em>Launchpad Base</em> project: <em>app</em> for the Standalone Java Application or <em>webapp</em> for the Web Application and unpack</li> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/url-decomposition.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/url-decomposition.html b/documentation/the-sling-engine/url-decomposition.html index a77d1f5..4d28008 100644 --- a/documentation/the-sling-engine/url-decomposition.html +++ b/documentation/the-sling-engine/url-decomposition.html @@ -74,7 +74,7 @@ URL decomposition </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p><!-- TODO reactivate TOC once JBake moves to flexmark-java --> </p> -<h1>Overview</h1> +<h1><a href="#overview" name="overview">Overview</a></h1> <p>During the <em>Resource Resolution</em> step, the client request URI (as being returned by [HttpServletRequest.getRequestURI()](http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getRequestURI())) is decomposed into the following parts (in exactly this order):</p> <ol> <li><strong>Resource Path</strong> - For existing resources the resource path is the longest match (also considering its <a href="/documentation/the-sling-engine/mappings-for-resource-resolution.html">mappings</a>) pointing to a resource where the next character is either a dot (<code>.</code>) or it is the full request URI. Otherwise (for a path not matching any existing resource) the resource path ends at the <em>first dot (<code>.</code>)</em> in the request url. The exact logic for retrieving the resource path is implemented at <a href="https://sling.apache.org/apidocs/sling7/org/apache/sling/api/resource/ResourceResolver.html#resolve-javax.servlet.http.HttpServletRequest-java.lang.String-";>ResourceResolver.resolve(HttpServletRequest,String)</a>. <em>It is impossible to tell from just looking at the request URI where the resource path part ends. You have to know the underlying resource structure to know how a URL is decomposed. You cannot safely assume that the resource path w ill always end at the first dot!</em>.</li> @@ -84,7 +84,7 @@ </ol> <p>Those decomposed parts can be accessed through the <code>RequestPathInfo</code> object, which is retrieved via <a href="https://sling.apache.org/apidocs/sling7/org/apache/sling/api/SlingHttpServletRequest.html#getRequestPathInfo--";>SlingHttpServletRequest.getPathInfo()</a>.</p> <p>There's a cheat sheet in Adobe's AEM documentation at <a href="https://docs.adobe.com/docs/en/aem/6-2/develop/platform/sling-cheatsheet.html";>https://docs.adobe.com/docs/en/aem/6-2/develop/platform/sling-cheatsheet.html</a> available to get you familiar with the URL decomposition of Sling.</p> -<h1>Examples</h1> +<h1><a href="#examples" name="examples">Examples</a></h1> <p>Assume there is a Resource at <code>/a/b</code>, which has no children.</p> <table> <thead> @@ -212,7 +212,7 @@ </tr> </tbody> </table> -<h1>Automated Tests</h1> +<h1><a href="#automated-tests" name="automated-tests">Automated Tests</a></h1> <p>The tests at</p> <ul> <li><a href="http://svn.apache.org/repos/asf/sling/trunk/bundles/resourceresolver/src/test/java/org/apache/sling/resourceresolver/impl/ResourceResolverImplTest.java";>ResourceResolverImplTest</a> shows the split between resource path and the rest. Mostly in the method <code>testBasicAPIAssumptions</code>.</li> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/url-to-script-resolution.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/url-to-script-resolution.html b/documentation/the-sling-engine/url-to-script-resolution.html index 9a3b087..3ea77b1 100644 --- a/documentation/the-sling-engine/url-to-script-resolution.html +++ b/documentation/the-sling-engine/url-to-script-resolution.html @@ -80,13 +80,13 @@ <p>Scripts and servlets are itself resources in Sling and thus have a resource path: this is either the location in the JCR repository, the resource type in a servlet component configuration or the "virtual" bundle resource path (if a script is provided inside a bundle without being installed into the JCR repository). </p> <p>For the whole Truth about script resolution, see the <a href="http://svn.apache.org/repos/asf/sling/trunk/bundles/servlets/resolver/src/test/java/org/apache/sling/servlets/resolver/internal/helper/ScriptSelectionTest.java";>ScriptSelectionTest</a> class. If you see interesting cases that are not covered there, please let us know via the Sling users mailing list.</p> <p>TODO: explain super types, servlet path mappings, node type resource types (<code>my:type -> my/type</code>) </p> -<h2>Fundamental: Scripts and Servlets are equal</h2> +<h2><a href="#fundamental-scripts-and-servlets-are-equal" name="fundamental-scripts-and-servlets-are-equal">Fundamental: Scripts and Servlets are equal</a></h2> <p>In the following discussion, I will write about scripts. This will always include servlets as well. In fact, internally, Sling only handles with Servlets, whereas scripts are packed inside a Servlet wrapping and representing the script. </p> -<h2>Base: Resource Type Inheritance</h2> +<h2><a href="#base-resource-type-inheritance" name="base-resource-type-inheritance">Base: Resource Type Inheritance</a></h2> <p>While not exactly part of our discussion, resource type inheritance as implemented for <a href="https://issues.apache.org/jira/browse/SLING-278";>SLING-278</a> plays a vital role in script resolution. </p> <p>Each resource type may have a resource super type, which may be defined in various ways. One example is having a <code>sling:resourceSuperType</code> property in the node addressed by the resource type. See <a href="http://www.mail-archive.com/[email protected]/msg02365.html";>http://www.mail-archive.com/[email protected]/msg02365.html</a> and <a href="http://issues.apache.org/jira/browse/SLING-278";>SLING-278</a> for more details. </p> <p>If a resource type has no explicit resource super type, the resource super type is assumed to be "sling/servlet/default". That is the resource type used for default script selection is also acting as a basic resource type much like java.lang.Object does for other types in the Java language. </p> -<h2>Script Locations</h2> +<h2><a href="#script-locations" name="script-locations">Script Locations</a></h2> <p>Scripts are looked up in a series of locations defined by the ResourceResolver.getSearchPath() and the resource type (and resource super types) of the requested resource: </p> <pre><code>{scriptPathPrefix}/{resourceTypePath} </code></pre> @@ -108,10 +108,10 @@ while (type != null) { } } </code></pre> -<h2>All requests are NOT equal</h2> +<h2><a href="#all-requests-are-not-equal" name="all-requests-are-not-equal">All requests are NOT equal</a></h2> <p>GET and HEAD request methods are treated differently than the other request methods. Only for GET and HEAD requests will the request selectors and extension be considered for script selection. For other requests the servlet or script name (without the script extension) must exactly match the request method. </p> <p>That is for a PUT request, the script must be PUT.esp or PUT.jsp. For a GET request with a request extension of html, the script name may be html.esp or GET.esp. </p> -<h2>Scripts for GET requests</h2> +<h2><a href="#scripts-for-get-requests" name="scripts-for-get-requests">Scripts for GET requests</a></h2> <p>Apart for supporting scripts named after the request method, scripts handling GET and HEAD requests may be named differently for Sling to support a more elaborate processing order. </p> <p>Depending on whether request selectors are considered, a script may have two forms: </p> <ul> @@ -125,14 +125,14 @@ while (type != null) { <li><code>{scriptExtension}</code> - The extension, e.g. "esp" or "jsp", identifying the scripting langauage used.</li> <li><code>{selectorStringPath}</code> - The selector string converted to a path, along the lines of <code>selectorString.replace('.', '/')</code>. If less selectors are specified in the script name than given in the request, the script will only be taken into consideration if the given selectors are the <strong>first</strong> selectors in the request. This means <em>sel1/sel2.html.jsp</em> will be a candidate for the request url <em>/content/test.sel1.sel2.sel3.html</em> but not for <em>/content/test.sel3.sel1.sel2.html</em>. So the order of selectors is relevant!</li> </ul> -<h2>Priority</h2> +<h2><a href="#priority" name="priority">Priority</a></h2> <p>The rules for script path priorization is defined as follows: </p> <ul> <li>The more request selectors are matched, the better</li> <li>A script including the request extension matches better than one without a request extension (for html only)</li> <li>A script found earlier matches better than a script found later in the processing order. This means, that script closer to the original resource type in the resource type hierarchy is considered earlier.</li> </ul> -<h2>Examples</h2> +<h2><a href="#examples" name="examples">Examples</a></h2> <p>Let's consider the following script paths for a request of a resource whose resource type is <code>sling\sample</code> and the request selectors are <em>print.a4</em> and the request extension is <em>html</em>: </p> <ul> <li>(0) GET.esp</li> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/the-sling-engine/wrap-or-decorate-resources.html ---------------------------------------------------------------------- diff --git a/documentation/the-sling-engine/wrap-or-decorate-resources.html b/documentation/the-sling-engine/wrap-or-decorate-resources.html index 56851bd..d1e7038 100644 --- a/documentation/the-sling-engine/wrap-or-decorate-resources.html +++ b/documentation/the-sling-engine/wrap-or-decorate-resources.html @@ -72,12 +72,11 @@ </div> <div class="main"> <div class="breadcrumbs"><a href="/ng/">Home</a> » <a href="/ng/documentation.html">Documentation</a> » <a href="/ng/documentation/the-sling-engine.html">The Sling Engine</a> » </div> <h1> Wrap or Decorate Resources - </h1><div class="row"><div class="small-12 columns"><section class="wrap"><h2>Introduction</h2> + </h1><div class="row"><div class="small-12 columns"><section class="wrap"><h2><a href="#introduction" name="introduction">Introduction</a></h2> <p>The Sling API provides an easy way to wrap or decorate a resource before returning. Use cases for this could for example be * overwrite resource type/resource super type (for example based on the resource path) * add metadata</p> <p>## </p> <p>To add a resource decorator just register one or more services which implement the interface <code>ResourceDecorator</code></p> -<pre><code>:::java -interface ResourceDecorator { +<pre><code>:<!-- TODO syntax marker (::java) disabled -->interface ResourceDecorator { /** Optionally decorate the supplied Resource */ Resource decorate(Resource) @@ -88,8 +87,7 @@ interface ResourceDecorator { </code></pre> <p>The registered decorators will be called from the resource resolver for each resource returned. If the service decorates the resource it should return the new resource (often using a <code>ResourceWrapper</code> to wrap the original Resource). If the service does not want to decorate the resource, it should return the original resource or null. </p> <p>Starting with version 2.1.0 of the JCR Resource bundle, the two-argument <code>decorate</code> method is not called anymore. Implementors of this interface targeting both newer and older versions of this bundle are advised to implement this method as:</p> -<pre><code>:::java -public Resource decorate(Resource resource, HttpServletRequest request) { +<pre><code>:<!-- TODO syntax marker (::java) disabled -->public Resource decorate(Resource resource, HttpServletRequest request) { return this.decorate(resource); } </code></pre> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/tutorials-how-tos/46-line-blog.html ---------------------------------------------------------------------- diff --git a/documentation/tutorials-how-tos/46-line-blog.html b/documentation/tutorials-how-tos/46-line-blog.html index 6d04755..0d2c9b9 100644 --- a/documentation/tutorials-how-tos/46-line-blog.html +++ b/documentation/tutorials-how-tos/46-line-blog.html @@ -75,13 +75,13 @@ </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p>This tutorial is based on the first <em>Sling Gems</em> on dev.day.com: The <a href="http://dev.day.com/microsling/content/blogs/main/sling-46-lines-blog.html";>Sling gems: a blog in 46 lines of code</a>. It has slightly been adapted to fit here.</p> <p>In this tutorial, the SlingPostServlet and the sling.js library are brought together using 46 (no kidding: <em>fourty-six</em>) lines of code to create a simple blog (or let's say <em>bloggish</em>) application.</p> <p>I used this example in my <a href="http://www.slideshare.net/bdelacretaz/rapid-jcr-applications-development-with-sling-1196003";>Rapid JCR application development with Apache Sling</a> presentation at ApacheCon US 09 in Oakland (slides will be available soon), and I think it's a good testimony to the power and simplicity of Sling.</p> -<h2>Audience</h2> +<h2><a href="#audience" name="audience">Audience</a></h2> <p>Although this is a simple sample, it requires some custom settings to work. If you're just starting with Sling, <a href="/documentation/getting-started/discover-sling-in-15-minutes.html">Discover Sling in 15 minutes</a> might be a better choice.</p> -<h2>Step 0: Start, configure and login to Sling</h2> +<h2><a href="#step-0-start-configure-and-login-to-sling" name="step-0-start-configure-and-login-to-sling">Step 0: Start, configure and login to Sling</a></h2> <p>See <a href="/documentation/development/getting-and-building-sling.html">Getting and Building Sling</a> for how to start Sling. Start it on port 8888 for the below links to work.</p> <p>For this sample we need the optional <em>org.apache.sling.samples.path-based.rtp</em> bundle, if it's not present in the <a href="http://localhost:8888/system/console/bundles";>OSGi console</a>, install and start it. That bundle is not released yet so you might need to build it yourself, from its <a href="http://svn.apache.org/repos/asf/sling/trunk/samples/path-based-rtp";>source</a>. The bundle must then appear in the <a href="http://localhost:8888/system/console/bundles";>OSGI console's list of bundles</a>, with name = <em>org.apache.sling.samples.path-based.rtp</em> and status = <em>Active</em>.</p> <p>Then, login using <a href="http://localhost:8888/?sling:authRequestLogin=1";>http://localhost:8888/?sling:authRequestLogin=1</a> which should prompt you for a username and password, use <em>admin</em> and <em>admin</em>. Once that's done, <a href="http://localhost:8888/index.html";>http://localhost:8888/index.html</a> should say <em>You are currently logged in as user <em>admin</em> to workspace <em>default</em></em>.</p> -<h2>Step 1: Creating content</h2> +<h2><a href="#step-1-creating-content" name="step-1-creating-content">Step 1: Creating content</a></h2> <p>The easiest way to create content in Sling is to use an HTTP POST request, let's use a simple HTML form:</p> <pre><code><html> <body> @@ -116,7 +116,7 @@ If you get an error saying _javax.jcr.AccessDeniedException: ...not allowed to add or modify item_ it means that you are not logged in as user _admin_. See instructions above for logging in. </div> <p>At this point you're probably looking at an empty form with an URL ending in <em>foo</em>, if you used that for the title. Or <em>foo_0</em> or <em>foo_1</em> if other _foo_s already existed. Don't worry about not seeing your content, we'll fix that right away.</p> -<h2>Step 2: Where's my content?</h2> +<h2><a href="#step-2-where-s-my-content-" name="step-2-where-s-my-content-">Step 2: Where's my content?</a></h2> <p>To verify that our content has been created, we can have a look at the JSON data at <a href="http://localhost:8888/content/blog/foo.tidy.json";>http://localhost:8888/content/blog/foo.tidy.json</a>, which should display our new node's values:</p> <pre><code>{ "jcr:primaryType": "nt:unstructured", @@ -136,7 +136,7 @@ If you get an error saying _javax.jcr.AccessDeniedException: ...not allowed to a </code></pre> <p>Reloading the form at <code>http://localhost:8888/content/blog/*.html</code> and creating a new post should now redirect to an editable version of the post, with the form fields correctly initialized.</p> <p>We can now create and edit posts; let's add some navigation, using more of the <em>sling.js</em> functionality. </p> -<h2>Step 3: Navigation</h2> +<h2><a href="#step-3-navigation" name="step-3-navigation">Step 3: Navigation</a></h2> <p>The <em>sling.js</em> library provides utilities to access and manipulate content. For our blog, we'll use the <code>getContent(path)</code> method to list the siblings of the current node.</p> <p>Add the following code to your script, after the <code>Sling.wizard()</code> call that was added in step 2:</p> <pre><code><h3>Navigation</h3> @@ -157,7 +157,7 @@ If you get an error saying _javax.jcr.AccessDeniedException: ...not allowed to a <p>The rest of the javascript runs client-side, as it is not embedded in <code><% %></code> code markers, calls the <code>sling.getContent</code> method to get two levels of node data below <code>/content/blog</code>, and displays links to nodes that it finds.</p> <p>That's a basic navigation, of course, in a real blog we'd need some paging and contextualization to cope with large numbers of posts.</p> <p>Nevertheless, with this addition our ESP script allows us to create, edit and navigate blog posts - not bad for 46 lines of code, including comments, whitespace and output formatting.</p> -<h2>Step 4: Data first, structure later</h2> +<h2><a href="#step-4-data-first-structure-later" name="step-4-data-first-structure-later">Step 4: Data first, structure later</a></h2> <p>You might have heard this mantra, which we apply in many areas of Sling.</p> <p>In this case, adding a new field to our blog posts could not be easier: just add an input field to the form, and Sling will do the rest.</p> <p>Adding this inside our script's <code><form></code> element, for example:</p> @@ -169,7 +169,7 @@ If you get an error saying _javax.jcr.AccessDeniedException: ...not allowed to a <p>Now wait...we said we were going to create an ESP script, but our "application" is just static HTML and some client javascript at this point.</p> <p>That's correct - as we are using only Sling client-facing features at this point (HTTP POST and <code>sling.js</code>), we do not necessarily need to use ESP code.</p> <p>To keep things simple, we'll refrain from adding ESP-based features at this point, but you can of course use any ESP code in the <em>blog.esp</em> "script".</p> -<h2>That's the power of Sling</h2> +<h2><a href="#that-s-the-power-of-sling" name="that-s-the-power-of-sling">That's the power of Sling</a></h2> <p>The 46-line blog is a good example of the power of Sling. It leverages the <a href="/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html">SlingPostServlet</a>, which handles POST requests in a form-friendly way, and the <a href="http://svn.apache.org/repos/asf/sling/trunk/bundles/servlets/post/src/main/resources/system/sling.js";><code>sling.js</code></a> client library, which provides high-level functionality on the client side.</p> <p>///Footnotes Go Here///</p></section></div></div> <div class="footer"> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/tutorials-how-tos/getting-resources-and-properties-in-sling.html ---------------------------------------------------------------------- diff --git a/documentation/tutorials-how-tos/getting-resources-and-properties-in-sling.html b/documentation/tutorials-how-tos/getting-resources-and-properties-in-sling.html index 4f56365..675d2b6 100644 --- a/documentation/tutorials-how-tos/getting-resources-and-properties-in-sling.html +++ b/documentation/tutorials-how-tos/getting-resources-and-properties-in-sling.html @@ -75,10 +75,9 @@ </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p>The Resource is one of the central parts of Sling. Extending from JCR's Everything is Content, Sling assumes Everthing is a Resource. Thus Sling is maintaining a virtual tree of resources, which is a merger of the actual contents in the JCR Repository and resources provided by so called resource providers. By doing this Sling fits very well in the paradigm of the REST architecture.</p> <p>In this article we will explore a few ways to programmatically map a resource path (String) to a resource object (Resource) and its properties in Sling, from within an OSGI service, a servlet and a JSP.</p> <p>The whole game consists in first getting a <code>ResourceResolver</code> and then getting the <code>Resource</code> itself.</p> -<h2>Within an OSGI Service/Compoment</h2> +<h2><a href="#within-an-osgi-service-compoment" name="within-an-osgi-service-compoment">Within an OSGI Service/Compoment</a></h2> <p>You can access a resource through the <code>ResourceResolverFactory</code> service:</p> -<pre><code>#!java -@Reference +<pre><code><!-- TODO syntax marker (#!java) disabled -->@Reference private ResourceResolverFactory resolverFactory; public void myMethod() { @@ -94,48 +93,41 @@ public void myMethod() { } } </code></pre> -<h2>Within a Servlet</h2> +<h2><a href="#within-a-servlet" name="within-a-servlet">Within a Servlet</a></h2> <p>You can access the resource defined by the request URL through the <code>SlingHttpServletRequest</code>:</p> -<pre><code>#!java -// req is the SlingHttpServletRequest +<pre><code><!-- TODO syntax marker (#!java) disabled -->// req is the SlingHttpServletRequest Resource res = req.getResource(); </code></pre> <p>You can access any resource by first accessing the <code>ResourceResolver</code>:</p> -<pre><code>#!java -String resourcePath = "path/to/resource"; +<pre><code><!-- TODO syntax marker (#!java) disabled -->String resourcePath = "path/to/resource"; // req is the SlingHttpServletRequest ResourceResolver resourceResolver = req.getResourceResolver(); Resource res = resourceResolver.getResource(resourcePath); </code></pre> -<h2>Within a JSP file</h2> +<h2><a href="#within-a-jsp-file" name="within-a-jsp-file">Within a JSP file</a></h2> <p>When you use the <code><sling:defineObjects></code> tag in a JSP file, you have access to a few handy objects, one of them is <code>resource</code>, the resource that is resolved from the URL. Another one is <code>resourceResolver</code>, the <code>ResourceResolver</code> defined through the <code>SlingHttpServletRequest</code>. </p> <p>To access a resource:</p> -<pre><code>#!jsp -<sling:defineObjects> +<pre><code><!-- TODO syntax marker (#!jsp) disabled --><sling:defineObjects> <% String resourcePath = "path/to/resource"; Resource res = resourceResolver.getResource(resourcePath); %> </code></pre> <p>If needed you can adapt a Sling Resource to a JCR Node:</p> -<pre><code>#!java -Node node = resource.adaptTo(Node.class); +<pre><code><!-- TODO syntax marker (#!java) disabled -->Node node = resource.adaptTo(Node.class); </code></pre> <p>Note: <code>resource.adaptTo(Node.class)</code> may return null if the resource is not backed by a JCR node. This is particularly the case for <code>NonExistingResource</code> resources or resource provided by a non-JCR resource provider.</p> -<h2>Accessing a Property</h2> +<h2><a href="#accessing-a-property" name="accessing-a-property">Accessing a Property</a></h2> <p>The <code>ValueMap</code> is an easy way to access properties of a resource. With most resources you can use <code>Adaptable.adaptTo(Class)</code> to adapt the resource to a value map:</p> -<pre><code>#!java -// res is the Resource +<pre><code><!-- TODO syntax marker (#!java) disabled -->// res is the Resource ValueMap properties = res.adaptTo(ValueMap.class); </code></pre> <p>You can also access the properties through the <code>ResourceUtil</code> utility class:</p> -<pre><code>#!java -// res is the Resource +<pre><code><!-- TODO syntax marker (#!java) disabled -->// res is the Resource ValueMap properties = ResourceUtil.getValueMap(res); </code></pre> <p>Then, to access a specific String property called <code>propName</code>:</p> -<pre><code>#!java -String rule = properties.get(propName, (String) null); +<pre><code><!-- TODO syntax marker (#!java) disabled -->String rule = properties.get(propName, (String) null); </code></pre> <p>For more details about resources and how to access them in Sling, you can refer to the <a href="/documentation/the-sling-engine/resources.html">Sling documentation about Resources</a>.</p></section></div></div> <div class="footer"> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/tutorials-how-tos/how-to-manage-events-in-sling.html ---------------------------------------------------------------------- diff --git a/documentation/tutorials-how-tos/how-to-manage-events-in-sling.html b/documentation/tutorials-how-tos/how-to-manage-events-in-sling.html index 6e97a47..67c995c 100644 --- a/documentation/tutorials-how-tos/how-to-manage-events-in-sling.html +++ b/documentation/tutorials-how-tos/how-to-manage-events-in-sling.html @@ -80,7 +80,7 @@ <li>Package <a href="/apidocs/sling6/org/apache/sling/event/package-summary.html">org.apache.sling.event</a> of the Sling API.</li> </ul> <p>This page drives you through the implementation of two services that rely on the Sling job mechanism. The services implement the following use case: whenever a file is uploaded to a temporary location in your web application, the file is moved to a specific location according to its MIME type.</p> -<h2>Introduction</h2> +<h2><a href="#introduction" name="introduction">Introduction</a></h2> <p>You will now implement the logic to listen to files posted to <em>/tmp/dropbox</em> and to move them to the appropriate locations depending on the MIME type:</p> <ul> <li>images (.png) are moved to <strong>/dropbox/images/</strong></li> @@ -98,26 +98,23 @@ <li>Processes the former jobs</li> <li>Moves the file according to its extension.</li> </ul> -<h2>Listening to OSGI Events</h2> +<h2><a href="#listening-to-osgi-events" name="listening-to-osgi-events">Listening to OSGI Events</a></h2> <p>To listen to OSGi events in Sling you just need to register an <strong>org.osgi.service.event.EventHandler</strong> service with an <strong>event.topics</strong> property that describes which event topics the handler is interested in.</p> <p>To listen to a Sling <strong>resource added</strong> events, for example, you'll set the <em>event.topics</em> property to <strong>org.apache.sling.api.SlingConstants.TOPIC_RESOURCE_ADDED</strong> in the class annotations:</p> -<pre><code> :::java - @Property(name=org.osgi.service.event.EventConstants.EVENT_TOPIC, +<pre><code> :<!-- TODO syntax marker (::java) disabled --> @Property(name=org.osgi.service.event.EventConstants.EVENT_TOPIC, value=org.apache.sling.api.SlingConstants.TOPIC_RESOURCE_ADDED) </code></pre> <p>The javadocs of the TOPIC_ constants in the <a href="/apidocs/sling6/org/apache/sling/api/SlingConstants.html">org.apache.sling.api.SlingConstants</a> class lists and explains the available event topics available in Sling.</p> -<h2>Starting a job</h2> +<h2><a href="#starting-a-job" name="starting-a-job">Starting a job</a></h2> <p>To start a job, the <em>JobManager</em> service can be used. It needs a job topic and a payload. In our case we define our dropbox job topic and give the resource path as the payload:</p> -<pre><code>:::java - final String resourcePath = ...; // path to the resource to handle +<pre><code>:<!-- TODO syntax marker (::java) disabled --> final String resourcePath = ...; // path to the resource to handle final Map<String, Object> payload = new HashMap<String, Object>(); payload.put("resourcePath", resourcePath); // start job this.jobManager.addJob(JOB_TOPIC, payload); </code></pre> <p>To receive the resource event, the service needs to implement the <strong>org.osgi.service.event.EventHandler</strong> interface and register it as an EventHandler service:</p> -<pre><code>:::java -@Component(immediate=true) // immediate should only be used in rare cases (see below) +<pre><code>:<!-- TODO syntax marker (::java) disabled -->@Component(immediate=true) // immediate should only be used in rare cases (see below) @Service(value=EventHandler.class) public class DropBoxService implements EventHandler { ... @@ -125,13 +122,11 @@ public class DropBoxService implements EventHandler { </code></pre> <p>Usually a service should be lazy and therefore not declare itself to be immediate (in the Component annotation). However as this service is an event handler and might receive a lot of events even concurrently, it is advised to set the immediate flag to true on the component. Otherwise our event handler would be created and destroyed with every event coming in.</p> <p>To start the job we need a reference to the JobManager:</p> -<pre><code>:::java -@Reference +<pre><code>:<!-- TODO syntax marker (::java) disabled -->@Reference private JobManager jobManager; </code></pre> <p>The job topic for dropbox job events needs to be defined:</p> -<pre><code>:::java -/** The job topic for dropbox job events. */ +<pre><code>:<!-- TODO syntax marker (::java) disabled -->/** The job topic for dropbox job events. */ public static final String JOB_TOPIC = "com/sling/eventing/dropbox/job"; </code></pre> <p>The <strong>org.osgi.service.event.EventHandler#handleEvent(Event event)</strong> method needs to be implemented:</p> @@ -150,8 +145,7 @@ public static final String JOB_TOPIC = "com/sling/eventing/dropbox/job" </li> </ul> <p>For example:</p> -<pre><code>:::java -public void handleEvent(final Event event) { +<pre><code>:<!-- TODO syntax marker (::java) disabled -->public void handleEvent(final Event event) { // get the resource event information final String propPath = (String) event.getProperty(SlingConstants.PROPERTY_PATH); final String propResType = (String) event.getProperty(SlingConstants.PROPERTY_RESOURCE_TYPE); @@ -168,16 +162,14 @@ public void handleEvent(final Event event) { } </code></pre> <p>The complete code for the <strong>DropBoxService</strong> service is available <a href="DropBoxService.java">here</a>.</p> -<h2>Consuming Job Events</h2> +<h2><a href="#consuming-job-events" name="consuming-job-events">Consuming Job Events</a></h2> <p>Now that you have implemented a service that starts a job when a file is uploaded to <strong>/tmp/dropbox</strong>, you will implement the service <strong>DropBoxEventHandler</strong> that processes those jobs and moves the files to a location according to their MIME types.</p> <p>To process to the job that have been defined before the property <strong>job.topics</strong> needs to be set to <strong>DropBoxService.JOB_TOPIC</strong> in the class annotations:</p> -<pre><code>:::java -@Property(name="job.topics", +<pre><code>:<!-- TODO syntax marker (::java) disabled -->@Property(name="job.topics", value=DropBoxService.JOB_TOPIC) </code></pre> <p>In addition the service needs to implement the <strong>org.apache.sling.event.jobs.consumer.JobConsumer</strong> interface:</p> -<pre><code>:::java -public class DropBoxEventHandler implements JobConsumer { +<pre><code>:<!-- TODO syntax marker (::java) disabled -->public class DropBoxEventHandler implements JobConsumer { </code></pre> <p>Some class fields need to be defined:</p> <ul> @@ -186,8 +178,7 @@ public class DropBoxEventHandler implements JobConsumer { <li>The destination paths of the files.</li> </ul> <p>For example:</p> -<pre><code>:::java -/** Default log. */ +<pre><code>:<!-- TODO syntax marker (::java) disabled -->/** Default log. */ protected final Logger logger = LoggerFactory.getLogger(this.getClass()); @Reference @@ -207,8 +198,7 @@ private final static String OTHER_PATH = "/dropbox/other/"; <li>The file is moved to the new location by using a JCR session (as the Sling Resource API doesn't support move atm)</li> </ul> <p>or in Java Code:</p> -<pre><code>:::java -public JobResult process(final Job job) { +<pre><code>:<!-- TODO syntax marker (::java) disabled -->public JobResult process(final Job job) { ResourceResolver adminResolver = null; try { adminResolver = resolverFactory.getAdministrativeResourceResolver(null); http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/tutorials-how-tos/installing-and-upgrading-bundles.html ---------------------------------------------------------------------- diff --git a/documentation/tutorials-how-tos/installing-and-upgrading-bundles.html b/documentation/tutorials-how-tos/installing-and-upgrading-bundles.html index b11d4c7..0ec08ad 100644 --- a/documentation/tutorials-how-tos/installing-and-upgrading-bundles.html +++ b/documentation/tutorials-how-tos/installing-and-upgrading-bundles.html @@ -77,11 +77,11 @@ We recommend to use the Apache Felix Web Console. The documentation below descri </div> <p>OSGi bundles installed in the OSGi framework, which is provided by Sling, may be upgraded or removed and new bundles may be installed by using the Sling Management Console. This page is about using the Sling Management Console for those tasks.</p> <p>Basically, you have two choices to install and upgrade bundles: Upload the bundle files or install them from a Bundle Repository.</p> -<h2>Sling Management Console</h2> +<h2><a href="#sling-management-console" name="sling-management-console">Sling Management Console</a></h2> <p>The Sling Management Console is installed by default when Sling is running and may be reached at on the page <code>/system/console</code> in the Sling Context by default. For example if you installed the Sling Web Application in the <code>/sample</code> context of the Servlet Container running at <code>http://somehost:4402</code>, you would access the Sling Management Console at <code>http://somehost:4402/sample/system/console</code>.</p> <p>You will be prompted for a user name and password to access the Sling Management Console. This password is preset to be <em>admin</em> for the user name and <em>admin</em> for the password.</p> <p>NB: Both the username and password and the location of the Sling Management Console inside the Web Application Context is configurable in the <em>Sling Management Console</em> configuration on the <em>Configuration</em> page.</p> -<h2>Installing and upgrading bundles by Upload</h2> +<h2><a href="#installing-and-upgrading-bundles-by-upload" name="installing-and-upgrading-bundles-by-upload">Installing and upgrading bundles by Upload</a></h2> <p>To install a new bundle or upgrade an already installed bundle, go to the <em>Bundles</em> page in the Sling Management Console. At the top and the bottom of the page you have a form to specify and upload a bundle as a file :</p> <ul> <li>Select the bundle file to upload</li> @@ -92,15 +92,15 @@ We recommend to use the Apache Felix Web Console. The documentation below descri <p>After clicking the button, the bundle file will be uploaded. If a bundle with the same bundle symbolic name is already installed, the respective bundle will be updated with the new bundle file. Otherwise the bundle file will be installed as a new bundle and its start level is set as defined. Additionally the bundle will optionally be started.</p> <p>After having updated a bundle, you should also refresh the packages by clicking on the <em>Refresh Packages</em> button. The reson for this is, that the old version of the bundle is still used by other bundles even after upgrading to a new version. Only when the packages are refreshed any users of the bundle will be relinked to use the new bundle version. As this might be a somewhat lengthy operation, which also stops and restarts using bundles, this operation has to be executed explicitly.</p> <p>Also, if you plan to upgrade multiple bundles, you may wish to upgrade all bundles before repackaging the using bundles.</p> -<h2>Installing and upgrading bundles from the Bundle Repository</h2> +<h2><a href="#installing-and-upgrading-bundles-from-the-bundle-repository" name="installing-and-upgrading-bundles-from-the-bundle-repository">Installing and upgrading bundles from the Bundle Repository</a></h2> <p>The OSGi Bundle Repository is a repository of bundles, from which Sling may download and install or upgrade bundles very easily. Unlike the installation of bundles by file upload, the OSGi Bundle Repository has the functionality to resolve and dependencies of bundles to be installed.</p> <p>Say you wish to install bundle <em>X</em> which depends on packages provided by bundle <em>Y</em>. When uploading bundle <em>X</em> as a file it will not resolve, that is Sling (the OSGi framework actually) is not able to ensure proper operation of bundle <em>X</em> and thus prevents the bundle from being started and used. You will have to manually upload bundle <em>Y</em> yourself. When using the OSGi Bundle Repository, you just select bundle <em>X</em> for installation and the bundle repository will find out, that bundle <em>Y</em> is also required and will automatically download and install it along with bundle <em>X</em>.</p> -<h3>The Bundle Repository page</h3> +<h3><a href="#the-bundle-repository-page" name="the-bundle-repository-page">The Bundle Repository page</a></h3> <p>Installation or update of bundles may be done on the <em>Bundle Repository</em> page of the Sling Management Console. In the upper part of the page, you will see a list (usually just a single entry) of OSGi Bundle Repositories known to Sling. In the lower part of the list you see the bundles available from these repositories. To install or update bundles, just check the respective button and click on the <em>Deploy Selected</em> or <em>Deploy and Start Selected</em> button at the bottom of the page depending on whether you want to start the bundle(s) after installation or not.</p> <p>See below for more information on OSGi Bundle Repository management.</p> -<h3>The Bundles page</h3> +<h3><a href="#the-bundles-page" name="the-bundles-page">The Bundles page</a></h3> <p>You may also want to upgrade already installed bundles from the <em>Bundles</em> page of the Sling Management Console. For each bundle listed in this page, there is an <em>Upgrade</em> button. If there is an upgrade to the installed bundle available in the OSGi Bundle Repository, the button is enabled and clicking on the button will upgrade the respective bundle. If no upgrade is available from the OSGi Bundle Repository, this button is disabled.</p> -<h3>Managing OSGi Bundle Repositories</h3> +<h3><a href="#managing-osgi-bundle-repositories" name="managing-osgi-bundle-repositories">Managing OSGi Bundle Repositories</a></h3> <p>Currently management of known OSGi Bundle Repositories is very simple. If a configured bundle repository is not available on startup, it will be marked as being inactive. If you know the repository is now available, you may click on the <em>Refresh</em> button, to activate it. Similarly, the contents of the repository may be modified by for example adding new bundles or updating bundles in the repository, these changes will be made known to Sling by clicking the <em>Refresh</em> button.</p> <p>There exists no GUI functionality yet to add a new repository to the list of known repositories. Instead you may submit a request with parameters <code>action</code> whose value must be <code>refreshOBR</code> and <code>repository</code> whose value must be the URL to the repository descriptor file generally called <code>repository.xml</code>.</p> <p>For example, if you run Sling on <code>http://localhost:7402/sample</code> with default location of the Sling Management Console, the following request would add a repository at <code>/tmp/repo/repository.xml</code> in the filesystem:</p> http://git-wip-us.apache.org/repos/asf/sling-site/blob/f542b22e/documentation/tutorials-how-tos/jackrabbit-persistence.html ---------------------------------------------------------------------- diff --git a/documentation/tutorials-how-tos/jackrabbit-persistence.html b/documentation/tutorials-how-tos/jackrabbit-persistence.html index 97317b4..7d59322 100644 --- a/documentation/tutorials-how-tos/jackrabbit-persistence.html +++ b/documentation/tutorials-how-tos/jackrabbit-persistence.html @@ -74,7 +74,7 @@ Jackrabbit Persistence </h1><div class="row"><div class="small-12 columns"><section class="wrap"><p>Out-of-the-box the embedded Jackrabbit repository used by Sling (the Embedded Jackrabbit Repository bundle) uses Derby to persist the JCR nodes and properties. For some applications or environments it may be required or required to replace Derby with another backing store such as PostgreSQL or Oracle.</p> <p>This page is based on the journey of Tony Giaccone to get Sling running with a PostgreSQL based Jackrabbit instance.</p> -<h2>Management Summary</h2> +<h2><a href="#management-summary" name="management-summary">Management Summary</a></h2> <p>To replace Derby as the persistence manager for Jackrabbit the following steps are required:</p> <ol> <li>Provide a JDBC driver for your database as an OSGi bundle</li> @@ -82,29 +82,27 @@ <li>(Re-) Start the Embedded Jackrabbit bundle</li> </ol> <p>When you are not using the Derby persistence manager, you may safely remove the Derby bundle from your Sling instance.</p> -<h2>JDBC Driver</h2> +<h2><a href="#jdbc-driver" name="jdbc-driver">JDBC Driver</a></h2> <p>The hardest thing to do is probably getting the JDBC driver for your database. One option is to look at the bundles provided by Spring Source in their repository at <a href="http://www.springsource.com/repository/";>http://www.springsource.com/repository/</a>.</p> <p>Another option is to create the bundle on your own using Peter Kriens' <a href="http://bnd.bndtools.org/";>bnd Tool</a>:</p> <ol> <li>Get the JDBC driver for your database from the driver provider</li> <li>Wrap the JDBC driver library into an OSGi bundle: - <pre><code>:::sh -# Example for PostgreSQL JDBC 3 driver 8.4-701 + <pre><code>:<!-- TODO syntax marker (::sh) disabled --># Example for PostgreSQL JDBC 3 driver 8.4-701 $ java -jar bnd.jar wrap postgresql-8.4-701.jdbc3.jar $ mv postgresql-8.4-701.jdbc3.bar postgresql-8.4-701.jdbc3-bnd.jar </code></pre> </li> <li> <p>Deploy the driver to your local Maven 2 Repository (Required if adding the JDBC driver to a Maven build, e.g. using the Sling Launchpad Plugin)</p> - <pre><code>:::sh -$ mvn install:install-file \ + <pre><code>:<!-- TODO syntax marker (::sh) disabled -->$ mvn install:install-file \ -DgroupId=postgresql -DartifactId=postgresql -Dversion=8.4.701.jdbc3 \ -Dpackaging=jar -Dfile=postgresql-8.4-701.jdbc3-bnd.jar </code></pre> </li> </ol> <p>Tony reports no success with the Spring Source bundle, whily the bnd approach worked for the PostgreSQL JDBC driver.</p> -<h2>Replace Derby in a running Sling Instance</h2> +<h2><a href="#replace-derby-in-a-running-sling-instance" name="replace-derby-in-a-running-sling-instance">Replace Derby in a running Sling Instance</a></h2> <p>To replace Derby in a running Sling instance follow these steps (e.g. through the Web Console at <code>/system/console</code>):</p> <ol> <li>Uninstall the Apache Derby bundle</li> @@ -113,13 +111,12 @@ $ mvn install:install-file \ <li>Refresh the packages (click the <em>Refresh Packages</em> button)</li> </ol> <p>Alternatively, you may wish to stop Sling after uninstalling Derby and installing the JDBC bundle. Technically, this is not required, though.</p> -<h2>Reconfiguring Jackrabbit</h2> +<h2><a href="#reconfiguring-jackrabbit" name="reconfiguring-jackrabbit">Reconfiguring Jackrabbit</a></h2> <p>To actually use a persistence manager other than the default (Derby) persistence manager, you have to configure Jackrabbit to use it. Create a <code>repository.xml</code> file in the <code>sling/jackrabbit</code> folder before starting Sling for the first time. If the repository was already started, you can also modify the existing file.</p> <p>To prepare a repository.xml file before first startup, use the <a href="http://svn.apache.org/repos/asf/sling/trunk/bundles/jcr/jackrabbit-server/src/main/resources/repository.xml";><code>repository.xml</code></a> as a template and modify it by replacing the <code><PersistenceManager></code> elements to refer to the selected persistence manager.</p> <p>If the file already exists, you can modifiy this existing file and there is no need to get the original from the SVN repository.</p> <p>For example to use PostgreSQL instead of Derby modify the <code><PersistenceManager></code> elements as follows:</p> -<pre><code>:::xml -<Repository> +<pre><code>:<!-- TODO syntax marker (::xml) disabled --><Repository> ... <Workspace name="${wsp.name}"> ... @@ -153,7 +150,7 @@ $ mvn install:install-file \ <p>Modify the <code>url</code>, <code>user</code>, and <code>password</code> parameters to match your database setup.</p> <p>If you reconfigure Jackrabbit to use the new persistence manager, the existing repository data in the <code>sling/jackrabbit</code> directory, except the <code>repository.xml</code> file, of course, should now be removed.</p> <p>Finally either start Sling or start the Jackrabbit Embedded Repository bundle.</p> -<h2>Credits</h2> +<h2><a href="#credits" name="credits">Credits</a></h2> <p>This description is based on Tony Giaccone's description <a href="http://markmail.org/message/wlbfrukmjjsl33hh";>Swapping Postgres for Derby</a> sent to the Sling Users mailing list.</p></section></div></div> <div class="footer"> <div class="trademarkFooter">
![http://dev.day.com/content/ddc/blog/2008/07/cheatsheet/_jcr_content/images/cheatsheet/back.png"](http://dev.day.com/content/ddc/blog/2008/07/cheatsheet/_jcr_content/images/cheatsheet/back.png"){kind=link}