http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/bundles/sling-pipes.md ---------------------------------------------------------------------- diff --git a/content/documentation/bundles/sling-pipes.md b/content/documentation/bundles/sling-pipes.md index fb4bfbd..a19d19c 100644 --- a/content/documentation/bundles/sling-pipes.md +++ b/content/documentation/bundles/sling-pipes.md @@ -1,10 +1,7 @@ -title=TODO title for sling-pipes.md -date=1900-01-01 -type=post -tags=blog +title=Sling Pipes +type=page status=published ~~~~~~ -Title: Sling Pipes tool for doing extract - transform - load operations through a resource tree configuration. @@ -12,14 +9,14 @@ often one-shot data transformations need sample code to be written & executed. T ## What is a pipe - getOutputBinding - ^ - | - getInput +---+---+ getOutput - | | - +----> Pipe +----> - | | - +-------+ +getOutputBinding +^ +| +getInput +---+---+ getOutput +| | ++----> Pipe +----> +| | ++-------+ A sling pipe is essentially a sling resource stream: @@ -32,14 +29,14 @@ At this moment, there are 3 types of pipes to consider: - "reader" pipes, that will just output a set of resource depending on the input - "writer" pipes, that write to the repository, depending on configuration and output - "container" pipes, that contains pipes, and whose job is to chain their execution : input is the input of their first pipe, - output is the output of the last pipe it contains. +output is the output of the last pipe it contains. A `Plumber` osgi service is provided to help getting & executing pipes. ## Registered Pipes a pipe configuration is a jcr node, with: -- `sling:resourceType` property, which must be a pipe type registered by the plumber +- `sling:resourceType` property, which must be a pipe type registered by the plumber - `name` property, that will be used in bindings as an id, and will be the key for the output bindings (default value being a value map of the current output resource). Note that the node name will be used in case no name is provided. - `path` property, defines pipe's input. Note that property is not mandatory in case the pipe is streamed after another pipe, in which case previous pipe output's can be used as input. - `expr` property, expression through which the pipe will execute (depending on the type) @@ -165,11 +162,11 @@ Following configurations are evaluated: - `expr` - name/value of each property of some pipes (write, remove) -you can use name of previous pipes in the pipe container, or the special binding `path`, where `path.previousPipe` +you can use name of previous pipes in the pipe container, or the special binding `path`, where `path.previousPipe` is the path of the current resource of previous pipe named `previousPipe` global bindings can be set at pipe execution, external scripts can be added to the execution as well (see pipe - configurations) +configurations) ## How to execute a pipe for now it's possible to execute Pipes through GET (read) or POST (read/write) commands: @@ -178,11 +175,11 @@ for now it's possible to execute Pipes through GET (read) or POST (read/write) c - either you'll need to create a slingPipes/plumber resource, say `etc/pipes` and then to execute - curl -u admin:admin -F "path=/etc/pipes/mySamplePipe" http://localhost:8080/etc/pipes.json +curl -u admin:admin -F "path=/etc/pipes/mySamplePipe" http://localhost:8080/etc/pipes.json - either you execute the request directly on the pipe Path, e.g. - curl -u admin:admin http://localhost:8080/etc/pipes/mySamplePipe.json +curl -u admin:admin http://localhost:8080/etc/pipes/mySamplePipe.json which will return you the path of the pipes that have been through the output of the configured pipe. @@ -193,17 +190,17 @@ you can add as `bindings` parameter a json object of global bindings you want to e.g. - curl -u admin:admin -F "path=/etc/pipes/test" -F "bindings={testBinding:'foo'}" http://localhost:4502/etc/pipes.json +curl -u admin:admin -F "path=/etc/pipes/test" -F "bindings={testBinding:'foo'}" http://localhost:4502/etc/pipes.json will returns something like - {"size":2, "items":["/one/output/resource", "another/one"]} +{"size":2, "items":["/one/output/resource", "another/one"]} ### Request Parameter `writer` you can add as `writer` parameter a json object as a pattern to the result you want to have. The values of the json -object are expressions and can reuse each pipe's subpipe binding. +object are expressions and can reuse each pipe's subpipe binding. Note this works only if the pipe called is a container pipe. @@ -211,7 +208,7 @@ pipe. e.g. - curl -u admin:admin http://localhost:4502/etc/pipes/users.json?writer={"user":"${user.fullName}"} +curl -u admin:admin http://localhost:4502/etc/pipes/users.json?writer={"user":"${user.fullName}"} will returns something similar to @@ -228,133 +225,133 @@ default response is truncated to 10 items, if you need more (or less), you can m ### slingQuery | write this pipe parse all profile nodes, and - { - "sling:resourceType":"slingPipes/container", - "name":"Dummy User prefix Sample", - "jcr:description":"prefix all full names of profile with "Mr" or "Ms" depending on gender", - "conf":{ - "profile": { - "sling:resourceType":"slingPipes/slingQuery", - "expr":"nt:unstructured#profile", - "path":"/home/users" - }, - "writeFullName": { - "sling:resourceType":"slingPipes/write", - "conf": { - "fullName":"${(profile.gender === 'female' ? 'Ms ' + profile.fullName : 'Mr ' + profile.fullName)}", - "generatedBy":"slingPipes" - } - } - } - } +{ +"sling:resourceType":"slingPipes/container", +"name":"Dummy User prefix Sample", +"jcr:description":"prefix all full names of profile with "Mr" or "Ms" depending on gender", +"conf":{ +"profile": { +"sling:resourceType":"slingPipes/slingQuery", +"expr":"nt:unstructured#profile", +"path":"/home/users" +}, +"writeFullName": { +"sling:resourceType":"slingPipes/write", +"conf": { +"fullName":"${(profile.gender === 'female' ? 'Ms ' + profile.fullName : 'Mr ' + profile.fullName)}", +"generatedBy":"slingPipes" +} +} +} +} ### slingQuery | multiProperty | authorizable | write - { - "jcr:primaryType": "sling:Folder", - "jcr:description": "move badge<->user relation ship from badge MV property to a user MV property" - "name": "badges", - "sling:resourceType": "slingPipes/container", - "conf": { - "jcr:primaryType": "sling:OrderedFolder", - "badge": { - "jcr:primaryType": "sling:Folder", - "jcr:description": "outputs all badge component resources", - "expr": "[sling:resourceType=myApp/components/badge]", - "path": "/etc/badges/badges-admin/jcr:content", - "sling:resourceType": "slingPipes/slingQuery" - }, - "profile": { - "jcr:primaryType": "sling:Folder", - "jcr:description": "retrieve all user ids from a mv property", - "path": "${path.badge}/profiles", - "sling:resourceType": "slingPipes/multiProperty" - }, - "user": { - "jcr:primaryType": "sling:OrderedFolder", - "jcr:description": "outputs user resource", - "expr": "profile", - "sling:resourceType": "slingPipes/authorizable" - }, - "write": { - "jcr:primaryType": "sling:OrderedFolder", - "jcr:descritption": "patches the badge path to the badges property of the user profile" - "path": "${path.user}/profile", - "sling:resourceType": "slingPipes/write", - "conf": { - "jcr:primaryType": "nt:unstructured", - "badges": "+[${path.badge}]" - } - } - } - } +{ +"jcr:primaryType": "sling:Folder", +"jcr:description": "move badge<->user relation ship from badge MV property to a user MV property" +"name": "badges", +"sling:resourceType": "slingPipes/container", +"conf": { +"jcr:primaryType": "sling:OrderedFolder", +"badge": { +"jcr:primaryType": "sling:Folder", +"jcr:description": "outputs all badge component resources", +"expr": "[sling:resourceType=myApp/components/badge]", +"path": "/etc/badges/badges-admin/jcr:content", +"sling:resourceType": "slingPipes/slingQuery" +}, +"profile": { +"jcr:primaryType": "sling:Folder", +"jcr:description": "retrieve all user ids from a mv property", +"path": "${path.badge}/profiles", +"sling:resourceType": "slingPipes/multiProperty" +}, +"user": { +"jcr:primaryType": "sling:OrderedFolder", +"jcr:description": "outputs user resource", +"expr": "profile", +"sling:resourceType": "slingPipes/authorizable" +}, +"write": { +"jcr:primaryType": "sling:OrderedFolder", +"jcr:descritption": "patches the badge path to the badges property of the user profile" +"path": "${path.user}/profile", +"sling:resourceType": "slingPipes/write", +"conf": { +"jcr:primaryType": "nt:unstructured", +"badges": "+[${path.badge}]" +} +} +} +} ### xpath | json | write this use case is for completing repository profiles with external system's data (that has an json api) - { - "jcr:primaryType": "nt:unstructured", - "jcr:description": "this pipe retrieves json info from an external system and writes them to the user profile, uses moment.js, it - distributes modified resources using publish distribution agent", - "sling:resourceType": "slingPipes/container", - "distribution.agent": "publish", - "additionalScripts": "/etc/source/moment.js", - "conf": { - "jcr:primaryType": "sling:OrderedFolder", - "profile": { - "jcr:primaryType": "sling:OrderedFolder", - "expr": "/jcr:root/home/users//element(profile,nt:unstructured)[@uid]", - "jcr:description": "query all user profile nodes", - "sling:resourceType": "slingPipes/xpath" - }, - "json": { - "jcr:primaryType": "sling:OrderedFolder", - "expr": "${(profile.uid ? 'https://my.external.system.corp.com/profiles/' + profile.uid.substr(0,2) + '/' + profile.uid + '.json' : '')", - "jcr:description": "retrieves json information relative to the given profile, if the uid is not found, expr is empty: the pipe will do nothing", - "sling:resourceType": "slingPipes/json" - }, - "write": { - "jcr:primaryType": "sling:OrderedFolder", - "path": "path.profile", - "jcr:description": "write json information to the profile node", - "sling:resourceType": "slingPipes/write", - "conf": { - "jcr:primaryType": "sling:OrderedFolder", - "background": "${json.opt('background')}", - "about": "${json.opt('about')}", - "birthday": "${(json.opt('birthday') ? moment(json.opt('birthday'), \"MMMM DD\").toDate() : '')}", - "mobile": "${json.opt('mobile')}" - } - } - } - } +{ +"jcr:primaryType": "nt:unstructured", +"jcr:description": "this pipe retrieves json info from an external system and writes them to the user profile, uses moment.js, it +distributes modified resources using publish distribution agent", +"sling:resourceType": "slingPipes/container", +"distribution.agent": "publish", +"additionalScripts": "/etc/source/moment.js", +"conf": { +"jcr:primaryType": "sling:OrderedFolder", +"profile": { +"jcr:primaryType": "sling:OrderedFolder", +"expr": "/jcr:root/home/users//element(profile,nt:unstructured)[@uid]", +"jcr:description": "query all user profile nodes", +"sling:resourceType": "slingPipes/xpath" +}, +"json": { +"jcr:primaryType": "sling:OrderedFolder", +"expr": "${(profile.uid ? 'https://my.external.system.corp.com/profiles/' + profile.uid.substr(0,2) + '/' + profile.uid + '.json' : '')", +"jcr:description": "retrieves json information relative to the given profile, if the uid is not found, expr is empty: the pipe will do nothing", +"sling:resourceType": "slingPipes/json" +}, +"write": { +"jcr:primaryType": "sling:OrderedFolder", +"path": "path.profile", +"jcr:description": "write json information to the profile node", +"sling:resourceType": "slingPipes/write", +"conf": { +"jcr:primaryType": "sling:OrderedFolder", +"background": "${json.opt('background')}", +"about": "${json.opt('about')}", +"birthday": "${(json.opt('birthday') ? moment(json.opt('birthday'), "MMMM DD").toDate() : '')}", +"mobile": "${json.opt('mobile')}" +} +} +} +} ### xpath | parent | rm - { - "jcr:primaryType": "nt:unstructured", - "jcr:description": "this pipe removes user with bad property in their profile", - "sling:resourceType": "slingPipes/container", - "conf": { - "jcr:primaryType": "sling:OrderedFolder", - "profile": { - "jcr:primaryType": "sling:OrderedFolder", - "expr": "/jcr:root/home/users//element(profile,nt:unstructured)[@bad]", - "jcr:description": "query all user profile nodes with bad properties", - "sling:resourceType": "slingPipes/xpath" - }, - "parent": { - "jcr:primaryType": "sling:OrderedFolder", - "jcr:description": "get the parent node (user node)", - "sling:resourceType": "slingPipes/parent" - }, - "rm": { - "jcr:primaryType": "sling:OrderedFolder", - "jcr:description": "remove it", - "sling:resourceType": "slingPipes/rm", - } - } - } +{ +"jcr:primaryType": "nt:unstructured", +"jcr:description": "this pipe removes user with bad property in their profile", +"sling:resourceType": "slingPipes/container", +"conf": { +"jcr:primaryType": "sling:OrderedFolder", +"profile": { +"jcr:primaryType": "sling:OrderedFolder", +"expr": "/jcr:root/home/users//element(profile,nt:unstructured)[@bad]", +"jcr:description": "query all user profile nodes with bad properties", +"sling:resourceType": "slingPipes/xpath" +}, +"parent": { +"jcr:primaryType": "sling:OrderedFolder", +"jcr:description": "get the parent node (user node)", +"sling:resourceType": "slingPipes/parent" +}, +"rm": { +"jcr:primaryType": "sling:OrderedFolder", +"jcr:description": "remove it", +"sling:resourceType": "slingPipes/rm", +} +} +} some other samples are in https://github.com/npeltier/sling-pipes/tree/master/src/test/
http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/bundles/sling-query.md ---------------------------------------------------------------------- diff --git a/content/documentation/bundles/sling-query.md b/content/documentation/bundles/sling-query.md index 3a8e9ff..ee2fd7f 100644 --- a/content/documentation/bundles/sling-query.md +++ b/content/documentation/bundles/sling-query.md @@ -1,10 +1,7 @@ -title=TODO title for sling-query.md -date=1900-01-01 -type=post -tags=blog +title=Sling Query +type=page status=published ~~~~~~ -Title: Sling Query SlingQuery is a Sling resource tree traversal tool inspired by the [jQuery](http://api.jquery.com/category/traversing/tree-traversal/) JavaScript API. @@ -12,25 +9,25 @@ SlingQuery is a Sling resource tree traversal tool inspired by the [jQuery](http The recommended way to find resources in the Sling repository is using tree-traversal methods, like `listChildren()` and `getParent()` rather than JCR queries. The latter are great for listing resources with given properties, but we can't leverage the repository tree structure with such queries. On the other hand, using tree-traversal method is quite verbose. Consider following code that takes an resource and returns its first ancestor, being `cq:Page`, with given `jcr:content/cq:template` attribute: - Resource resource = ...; - while ((resource = resource.getParent()) != null) { - if (!resource.isResourceType("cq:Page")) { - continue; - } - Resource template = resource.getChild("jcr:content/cq:template"); - if (template != null && "my/template".equals(template.adaptTo(String.class))) { - break; - } - } - if (resource != null) { - // we've found appropriate ancestor - } +Resource resource = ...; +while ((resource = resource.getParent()) != null) { +if (!resource.isResourceType("cq:Page")) { +continue; +} +Resource template = resource.getChild("jcr:content/cq:template"); +if (template != null && "my/template".equals(template.adaptTo(String.class))) { +break; +} +} +if (resource != null) { +// we've found appropriate ancestor +} SlingQuery is a tool that helps creating such queries in a more concise way. Above code could be written as: - import static org.apache.sling.query.SlingQuery.$; - // ... - $(resource).closest("cq:Page[jcr:content/cq:template=my/template]") +import static org.apache.sling.query.SlingQuery.$; +// ... +$(resource).closest("cq:Page[jcr:content/cq:template=my/template]") Dollar sign is a static method that takes the resource array and creates SlingQuery object. The `closest()` method returns the first ancestor matching the selector string passed as the argument. @@ -48,11 +45,11 @@ SlingQuery is inspired by the jQuery framework. jQuery is the source of method n Add following Maven dependency to your `pom.xml`: - <dependency> - <groupId>org.apache.sling</groupId> - <artifactId>org.apache.sling.query</artifactId> - <version>3.0.0</version> - </dependency> +<dependency> +<groupId>org.apache.sling</groupId> +<artifactId>org.apache.sling.query</artifactId> +<version>3.0.0</version> +</dependency> ## Documentation @@ -60,9 +57,9 @@ Add following Maven dependency to your `pom.xml`: * [Basic ideas](https://github.com/Cognifide/Sling-Query/wiki/Basic-ideas) * [Method list](https://github.com/Cognifide/Sling-Query/wiki/Method-list) * [Selector syntax](https://github.com/Cognifide/Sling-Query/wiki/Selector-syntax) - * [Operator list](https://github.com/Cognifide/Sling-Query/wiki/Operator-list) - * [Modifier list](https://github.com/Cognifide/Sling-Query/wiki/Modifier-list) - * [Hierarchy operator list](https://github.com/Cognifide/Sling-Query/wiki/Hierarchy-operator-list) +* [Operator list](https://github.com/Cognifide/Sling-Query/wiki/Operator-list) +* [Modifier list](https://github.com/Cognifide/Sling-Query/wiki/Modifier-list) +* [Hierarchy operator list](https://github.com/Cognifide/Sling-Query/wiki/Hierarchy-operator-list) * [Examples](https://github.com/Cognifide/Sling-Query/wiki/Examples) ## External resources http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/bundles/sling-settings-org-apache-sling-settings.md ---------------------------------------------------------------------- diff --git a/content/documentation/bundles/sling-settings-org-apache-sling-settings.md b/content/documentation/bundles/sling-settings-org-apache-sling-settings.md index a0dc727..7d99a92 100644 --- a/content/documentation/bundles/sling-settings-org-apache-sling-settings.md +++ b/content/documentation/bundles/sling-settings-org-apache-sling-settings.md @@ -1,10 +1,7 @@ -title=TODO title for sling-settings-org-apache-sling-settings.md -date=1900-01-01 -type=post -tags=blog +title=Sling Settings and Run Modes (org.apache.sling.settings) +type=page status=published ~~~~~~ -Title: Sling Settings and Run Modes (org.apache.sling.settings) # Overview @@ -35,7 +32,7 @@ The `sling.run.mode.options` property on the other hand is used at each startup, The value of the both these properties is a string which looks like: - red,green,blue|one|moon,mars +red,green,blue|one|moon,mars where *comma-separated run modes form a group*. The individual groups are separated by a pipe character (`|`, which is not an OR operation, it's just as separator). A group defines a number of run modes which are **mutually exclusive**. It means once a group is defined, exactly one run mode will be active from that group. @@ -45,16 +42,16 @@ The example from above consists out of 3 different groups 2. `one` 3. `moon,mars` -The rules for determining the active run modes from the selected run mode (`sling.run.modes`) and the run mode options (`sling.run.mode.install.options` and `sling.run.mode.options`) are as follows : +The rules for determining the active run modes from the selected run mode (`sling.run.modes`) and the run mode options (`sling.run.mode.install.options` and `sling.run.mode.options`) are as follows : -1. If none of the run modes in the options are selected, the first one from each group in the options is activated by default. +1. If none of the run modes in the options are selected, the first one from each group in the options is activated by default. 1. If one is selected from a group in the options, this is active. 1. If several are selected from one group in the options, the first one from the list of valid run modes is used. 1. If the selected run mode is not mentioned in any of the option groups it is active Examples - sling.run.mode.options=a,b|c,d,e +sling.run.mode.options=a,b|c,d,e User defined run modes (e.g. via property `sling.run.modes`) | Effectively active run modes --- | --- @@ -71,14 +68,14 @@ Remember to look at the `RunModeImplTest` mentioned above for details, and feel The `SlingSettings` service provides the Run Modes of the running Sling instance as in this example: - :::java - SlingSettings settings = ...get from BundleContext... - Set<String> currentRunModes = settings.getRunModes(); - - Set<String> expectedRunModes = new HashSet<String>(){{ add("foo");add("wii"); }}; - if(expectedRunModes.removeAll(currentRunModes)) { - // at least one of (foo,wii) run modes - // is active - } - +:::java +SlingSettings settings = ...get from BundleContext... +Set<String> currentRunModes = settings.getRunModes(); + +Set<String> expectedRunModes = new HashSet<String>(){{ add("foo");add("wii"); }}; +if(expectedRunModes.removeAll(currentRunModes)) { +// at least one of (foo,wii) run modes +// is active +} + Getting run modes in this way is usually not needed, it's better to define bundles or configurations that are only valid in specific run modes, rather than making decisions in code based on run modes. http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/bundles/subsystem-installer-factory.md ---------------------------------------------------------------------- diff --git a/content/documentation/bundles/subsystem-installer-factory.md b/content/documentation/bundles/subsystem-installer-factory.md index 58bcfeb..5b5e3f4 100644 --- a/content/documentation/bundles/subsystem-installer-factory.md +++ b/content/documentation/bundles/subsystem-installer-factory.md @@ -1,16 +1,13 @@ -title=TODO title for subsystem-installer-factory.md -date=1900-01-01 -type=post -tags=blog +title=Subsystems Installer Factory +type=page status=published ~~~~~~ -Title: Subsystems Installer Factory The subsystems installer factory provides support for subsystems to the [OSGI installer](/documentation/bundles/osgi-installer.html). The provisioning of artifacts is handled by installer providers like the file installer or the JCR installer. ## Subsystems - + The subsystem file must end with ".esa" and the manifest must at least contain the subsystem symbolic name "Subsystem-SymbolicName" header. # Project Info http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/bundles/validation.md ---------------------------------------------------------------------- diff --git a/content/documentation/bundles/validation.md b/content/documentation/bundles/validation.md index 5131512..af1c7f4 100644 --- a/content/documentation/bundles/validation.md +++ b/content/documentation/bundles/validation.md @@ -1,10 +1,7 @@ -title=TODO title for validation.md -date=1900-01-01 -type=post -tags=blog +title=Sling Validation +type=page status=published ~~~~~~ -Title: Sling Validation [TOC] @@ -21,40 +18,40 @@ In addition a [service resolver mapping](/documentation/the-sling-engine/service # Basic Usage To validate a resource one first needs to get a `ValidationModel` and then validate the resource with that model. Both functionalities are provided by the `ValidationService` OSGi service: - ::java - try { - ValidationModel validationModel = validationService.getValidationModel(resource, true); - if (validationModel != null) { - ValidationResult result = validationService.validate(resource, validationModel); - if (!result.isValid()) { - // give out validation messages from result.get - } - } - } catch (IllegalStateException e) { - // give out error message that the validation model is invalid! - } - +::java +try { +ValidationModel validationModel = validationService.getValidationModel(resource, true); +if (validationModel != null) { +ValidationResult result = validationService.validate(resource, validationModel); +if (!result.isValid()) { +// give out validation messages from result.get +} +} +} catch (IllegalStateException e) { +// give out error message that the validation model is invalid! +} + Apart from that it is also possible to validate resources including all child resources having their own validation model (i.e. a merged view of the validation models is applied). The appropriate validation model is being looked up by getting the resource type for each node. Since by default the JCR will return the primary type in case there is no `sling:resourceType` property found on the node, either the 2nd parameter `enforceValidation` should be set to `false` or some resource types must be explicitly ignored by the given filter in the 3rd parameter `filter` to also properly support validation models which have children resources on their own. - ::java - try { - final Predicate ignoreResourceType1Predicate = new Predicate<Resource>() { - @Override - public boolean test(final Resource resource) { - return !"resourcetype1".equals(resource.getResourceType()); - } - }; - ValidationResult result = validationService.validateResourceRecursively(resource, false, ignoreResourceType1Predicate, false); - if (!result.isValid()) { - // give out validation messages from result.getFailureMessages() - } - - } catch (IllegalStateException e) { - // give out error message that an invalid validation model for at least one sub resource was found - } catch (IllegalArgumentException e) { - // one of the resource types is absolute or there was no validation model found for at least one sub resource - } - +::java +try { +final Predicate ignoreResourceType1Predicate = new Predicate<Resource>() { +@Override +public boolean test(final Resource resource) { +return !"resourcetype1".equals(resource.getResourceType()); +} +}; +ValidationResult result = validationService.validateResourceRecursively(resource, false, ignoreResourceType1Predicate, false); +if (!result.isValid()) { +// give out validation messages from result.getFailureMessages() +} + +} catch (IllegalStateException e) { +// give out error message that an invalid validation model for at least one sub resource was found +} catch (IllegalArgumentException e) { +// one of the resource types is absolute or there was no validation model found for at least one sub resource +} + All methods to retrieve a validation model support a boolean parameter `considerResourceSuperTypeModels`. If this is set to true, the validation model is not only being looked up for exactly the given resource type but also for all its resource super types. The returned model is then a merged model of all found validation model along the resource type hierarchy. ## ValidationResult @@ -68,25 +65,25 @@ You have to use a `ResourceBundle` ([Internationalization Support](/documentatio # Validation Model Resources The `ValidationModel` is constructed from resources with the resourceType **sling/validation/model**. Those resources are considered validation model resources if they are located below the Sling ResourceResolver search paths (*/apps* and */libs*). - + The resources should have the following format: -Property/Resource Name | Property or Resource | Type | Description | Mandatory | Example +Property/Resource Name | Property or Resource | Type | Description | Mandatory | Example -------------------- | ------- | -------------- | -------------| --------- | ------ `sling:resourceType` | Property | `String` | Always `sling/validation/model`, otherwise model will never be picked up by Sling Validation. | yes | `sling/validation/model` -`validatingResourceType` | Property | `String` | The resource type of the resource for which this validation model should be applied. Must always be relative to the resource resolver's search path (i.e. not start with a "/"). | yes | `my/own/resourcetype` +`validatingResourceType` | Property | `String` | The resource type of the resource for which this validation model should be applied. Must always be relative to the resource resolver's search path (i.e. not start with a "/"). | yes | `my/own/resourcetype` `applicablePaths` | Property | `String[]` | Path prefixes which restrict the validation model to resources which are below one of the given prefixes. No wildcards are supported. If not given, there is no path restriction. If there are multiple validation models registered for the same resource type the one with the longest matching applicablePath is chosen. | no | `/content/mysite` -`properties\<propertyName>` | Resource | - | This resource ensures that the property with the name `<propertyName>` is there. The resource name has no longer a meaning if the property `nameRegex` is set on this node. | no | `false` -`properties\<propertyName>\optional` | Property | `Boolean` | If `true` it is not an error if there is no property with the given `<propertyName>` or none matching the `nameRegex`. If not set or `false` the property must be there. | no | `false` -`properties\<propertyName>\propertyMultiple` | Property | `Boolean` | If `true` only multivalue properties are allowed with the name `<propertyName>` or matching the `nameRegex`. If not set or `false`, multi- and single-value properties are accepted. | no | `false` -`properties\<propertyName>\nameRegex` | Property | `String` | If set the `<propertyName>` has no longer a meaning. Rather all properties which match the given regular expression are considered. At least one match is required, otherwise the validated resource/valuemap is considered invalid. | no | `property[0-8]` -`properties\<propertyName>\validators\<validatorId>` | Resource | - | The `<validatorId>` must be the id of a validator. The id is given by the OSGi service property `validator.id` set in the validator. Each validators node might have arbitrarily many child resources (one per validator). | no | `false` -`properties\<propertyName>\validators\<validatorId>\validatorArguments` | Property | `String[]` | The parametrization for the validator with the id `<validatorId>`. Each value must have the pattern `key=value`. The parametrization differs per validator. | no | `regex=^[a-z]*$` -`properties\<propertyName>\validators\<validatorId>\severity` | Property | `Integer` | The severity which should be set on all emitted validation failures by this validator. | no | `0` -`children\<resourceName>` | Resource | - | This resource ensures that the resource with the name `<resourceName>` is there. The resource name has no longer a meaning if the property `nameRegex` is set on this node. | no | `child1` -`children\<resourceName>\nameRegex` | Property | `String` | If set the `<resourceName>` has no longer a meaning. Rather all resources whose name match the given regular expression are considered. At least one match is required, otherwise the validated resource/valuemap is considered invalid. | no | `child[1-9]` -`children\<resourceName>\optional` | Property | `Boolean` | If `true` it is not an error if there is no resource with the given `<resourceName>` or none matching the `nameRegex`. If not set or `false` the resource must be there. | no | `false` -`children\<resourceName>\properties` | Resource | - | The properties can be configured on the child level in the same way as on the root level. | no | - +`properties<propertyName>` | Resource | - | This resource ensures that the property with the name `<propertyName>` is there. The resource name has no longer a meaning if the property `nameRegex` is set on this node. | no | `false` +`properties<propertyName>optional` | Property | `Boolean` | If `true` it is not an error if there is no property with the given `<propertyName>` or none matching the `nameRegex`. If not set or `false` the property must be there. | no | `false` +`properties<propertyName>propertyMultiple` | Property | `Boolean` | If `true` only multivalue properties are allowed with the name `<propertyName>` or matching the `nameRegex`. If not set or `false`, multi- and single-value properties are accepted. | no | `false` +`properties<propertyName>nameRegex` | Property | `String` | If set the `<propertyName>` has no longer a meaning. Rather all properties which match the given regular expression are considered. At least one match is required, otherwise the validated resource/valuemap is considered invalid. | no | `property[0-8]` +`properties<propertyName>validators<validatorId>` | Resource | - | The `<validatorId>` must be the id of a validator. The id is given by the OSGi service property `validator.id` set in the validator. Each validators node might have arbitrarily many child resources (one per validator). | no | `false` +`properties<propertyName>validators<validatorId>validatorArguments` | Property | `String[]` | The parametrization for the validator with the id `<validatorId>`. Each value must have the pattern `key=value`. The parametrization differs per validator. | no | `regex=^[a-z]*$` +`properties<propertyName>validators<validatorId>severity` | Property | `Integer` | The severity which should be set on all emitted validation failures by this validator. | no | `0` +`children<resourceName>` | Resource | - | This resource ensures that the resource with the name `<resourceName>` is there. The resource name has no longer a meaning if the property `nameRegex` is set on this node. | no | `child1` +`children<resourceName>nameRegex` | Property | `String` | If set the `<resourceName>` has no longer a meaning. Rather all resources whose name match the given regular expression are considered. At least one match is required, otherwise the validated resource/valuemap is considered invalid. | no | `child[1-9]` +`children<resourceName>optional` | Property | `Boolean` | If `true` it is not an error if there is no resource with the given `<resourceName>` or none matching the `nameRegex`. If not set or `false` the resource must be there. | no | `false` +`children<resourceName>properties` | Resource | - | The properties can be configured on the child level in the same way as on the root level. | no | - ## Validation Model Inheritance Sling Validation optionally supports the inheritance of Sling Validation Models. This means not only the model for exactly the given resource type is considered, but also the models for all resource super types. @@ -102,34 +99,34 @@ See [Sling Models validation](/documentation/bundles/models.html#validation) ## Before Sling Models 1.2.0 One needs to call the validate method within the PostConstruct method of the according Sling Model - ::java - @SlingObject - protected Resource resource; - - @OSGiService - protected ValidationService validation; - - @PostConstruct - public void validate() { - try { - ValidationModel validationModel = validation.getValidationModel(resource); - if (validationModel == null) { - LOG.warn("No validation defined for resource '{}' with type '{}'", resource.getPath(), resource.getResourceType()); - - } else { - ValidationResult result = validation.validate(resource, validationModel); - if (!result.isValid()) { - // give out the validation result - } - } - } catch (IllegalStateException e) { - LOG.warn("Invalid validation model for resource '{}' with type '{}'", resource.getPath(), resource.getResourceType()); - } - } +::java +@SlingObject +protected Resource resource; + +@OSGiService +protected ValidationService validation; + +@PostConstruct +public void validate() { +try { +ValidationModel validationModel = validation.getValidationModel(resource); +if (validationModel == null) { +LOG.warn("No validation defined for resource '{}' with type '{}'", resource.getPath(), resource.getResourceType()); + +} else { +ValidationResult result = validation.validate(resource, validationModel); +if (!result.isValid()) { +// give out the validation result +} +} +} catch (IllegalStateException e) { +LOG.warn("Invalid validation model for resource '{}' with type '{}'", resource.getPath(), resource.getResourceType()); +} +} # Validators -Validator ID | Description | Parameters | Since +Validator ID | Description | Parameters | Since ---------------|-------------|------------|------- [`org.apache.sling.validation.core.RegexValidator`](https://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/validation/core/src/main/java/org/apache/sling/validation/impl/validators/RegexValidator.java) | Validates that a property value matches a given regular expression | `regex`, mandatory parameter giving a regular expression according to the pattern described in [java.util.regex.Pattern](http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html). Only if the property value matches this expression it is considered valid. | 1.0.0 http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/bundles/web-console-extensions.md ---------------------------------------------------------------------- diff --git a/content/documentation/bundles/web-console-extensions.md b/content/documentation/bundles/web-console-extensions.md index 05dc9cc..fef0adb 100644 --- a/content/documentation/bundles/web-console-extensions.md +++ b/content/documentation/bundles/web-console-extensions.md @@ -1,10 +1,7 @@ -title=TODO title for web-console-extensions.md -date=1900-01-01 -type=post -tags=blog +title=Web Console Extensions +type=page status=published ~~~~~~ -Title: Web Console Extensions The Apache Sling project provides two extensions to the [Apache Felix Web Console](http://felix.apache.org/site/apache-felix-web-console.html) (in addition to a number of plugins, of course): http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/bundles/xml-support.md ---------------------------------------------------------------------- diff --git a/content/documentation/bundles/xml-support.md b/content/documentation/bundles/xml-support.md index 1afe75f..5513fec 100644 --- a/content/documentation/bundles/xml-support.md +++ b/content/documentation/bundles/xml-support.md @@ -1,10 +1,7 @@ -title=TODO title for xml-support.md -date=1900-01-01 -type=post -tags=blog +title=XML support +type=page status=published ~~~~~~ -Title: XML support Excerpt: XML mechanisms supported by Sling Out of the box, Sling provides no special bundles for XML. However, Sling supports multiple mechanisms and libraries. The ones we have validated with integration tests are: http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/configuration.md ---------------------------------------------------------------------- diff --git a/content/documentation/configuration.md b/content/documentation/configuration.md index 8ad5a3b..147277f 100644 --- a/content/documentation/configuration.md +++ b/content/documentation/configuration.md @@ -1,23 +1,20 @@ -title=TODO title for configuration.md -date=1900-01-01 -type=post -tags=blog +title=Configuration +type=page status=published ~~~~~~ -Title: Configuration ## Introduction Configuration in Sling is aligned with respective support by the OSGi specification: - * Framework and Java system properties are available through the `BundleContext.getProperty(String)` method. These properties are provided in Sling through the Sling launcher. - * Bundle Header values are available through the `Bundle.getHeaders()` and `Bundle.getHeaders(String)` methods. These header values are set by the bundle developer in the `META-INF/MANIFEST.MF` file. In fact, all main manifest attributes are available through these methods. - * Components managed by the Service Component Runtime and declared in component descriptor files listed in the `Service-Component` manifest header access configuration properties through the `ComponentContext.getProperties()` method. These properties have three sources: - 1. Configuration specified specifically for factory components - 2. Properties retrieved from the Configuration Admin Service - 3. Properties set in the component descriptor - * Configuration properties provided to `ManagedService` and `ManagedServiceFactory` instances by the Configuration Admin Service. +* Framework and Java system properties are available through the `BundleContext.getProperty(String)` method. These properties are provided in Sling through the Sling launcher. +* Bundle Header values are available through the `Bundle.getHeaders()` and `Bundle.getHeaders(String)` methods. These header values are set by the bundle developer in the `META-INF/MANIFEST.MF` file. In fact, all main manifest attributes are available through these methods. +* Components managed by the Service Component Runtime and declared in component descriptor files listed in the `Service-Component` manifest header access configuration properties through the `ComponentContext.getProperties()` method. These properties have three sources: +1. Configuration specified specifically for factory components +2. Properties retrieved from the Configuration Admin Service +3. Properties set in the component descriptor +* Configuration properties provided to `ManagedService` and `ManagedServiceFactory` instances by the Configuration Admin Service. For the discussion to follow we differentiate between initial configuration provided by Framework and system properties and managed configuration provided by the Configuration Admin Service. @@ -41,8 +38,8 @@ The Sling launcher is responsible to provide the Framework properties to the OSG 1. Handle OSGi boot delegation support (see below). 1. Resolve property references of the form `${propName`} 1. For each property value starting with `ontext:/` do the following, assuming the value to be an URL with scheme `context:`: - * Copy the application resource to `${sling.home`} preserving the URL path unless such a file already exists. - * Replace the property value with the path to the newly created file. The path has the form `${sling.home}/relpath`. +* Copy the application resource to `${sling.home`} preserving the URL path unless such a file already exists. +* Replace the property value with the path to the newly created file. The path has the form `${sling.home}/relpath`. 1. Store the properties as `${sling.home}/sling.properties` to be re-used on next startup 1. Setup Bundle auto installation for the Felix Framework @@ -101,7 +98,7 @@ The names of the files are resolved as follows: The packaged `sling.properties` file contains the following properties file inclusion setting: - sling.include.jre = jre-${java.specification.version}.properties +sling.include.jre = jre-${java.specification.version}.properties This is used to include the JRE package list to be made visible inside the OSGi framework. @@ -153,14 +150,14 @@ As listed in the above section on OSGi Boot Delegation Support, the `org.osgi.fr The following system property names are reserved: - * Names starting with `org.osgi.` are reserved for OSGi defined Framework properties - * Names starting with `org.apache.felix.` are reserved for the Felix Framework - * Names starting with `sling.` and `org.apache.sling.` are reserved for Sling +* Names starting with `org.osgi.` are reserved for OSGi defined Framework properties +* Names starting with `org.apache.felix.` are reserved for the Felix Framework +* Names starting with `sling.` and `org.apache.sling.` are reserved for Sling To prevent property name collisions, I suggest the following convention: - * Use fully qualified property names for initial configuration through Framework properties - * Use unqualified property names for configuration through the Configuration Admin Service +* Use fully qualified property names for initial configuration through Framework properties +* Use unqualified property names for configuration through the Configuration Admin Service ## Well Known Properties http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/development.md ---------------------------------------------------------------------- diff --git a/content/documentation/development.md b/content/documentation/development.md index f748bb2..97f16be 100644 --- a/content/documentation/development.md +++ b/content/documentation/development.md @@ -1,10 +1,7 @@ -title=TODO title for development.md -date=1900-01-01 -type=post -tags=blog +title=Development +type=page status=published ~~~~~~ -Title: Development Welcome to the wonderful world of extending Sling. Refer to these pages to find out how we envision the extension of Sling and how to do it. http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/development/client-request-logging.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/client-request-logging.md b/content/documentation/development/client-request-logging.md index 0dc213f..341fd41 100644 --- a/content/documentation/development/client-request-logging.md +++ b/content/documentation/development/client-request-logging.md @@ -1,10 +1,7 @@ -title=TODO title for client-request-logging.md -date=1900-01-01 -type=post -tags=blog +title=Client Request Logging +type=page status=published ~~~~~~ -Title: Client Request Logging Sling provides extensive support to log various information at the before and after processing client requests. Out of the box, there are two loggers configured to write traditional `access.log` and `request.log` files. In addition more logging can be configured by providing OSGi Configuration Admin configuration. @@ -16,10 +13,10 @@ In the Sling Web Console locate the Configuration page (`/system/console/configM | Parameter | Name | Default | Description | |--|--|--|--| -| Request Log Name | `request.log.output` | logs/request.log | Name of the destination for the request log. The request log logs the entry and exit of each request into and out of the system together with the entry time, exit time, time to process the request, a request counter as well as the final status code and response content type. In terms of Request Logger Service formats, request entry is logged with the format `%t \[%R\] \-> %m %U%q %H` and request exit is logged with the format `%\{end}t \[%R] <\- %s %\{Content-Type}o %Dms` (See [Log Format Specification](#log-format-specification) below for the specification of the format). | +| Request Log Name | `request.log.output` | logs/request.log | Name of the destination for the request log. The request log logs the entry and exit of each request into and out of the system together with the entry time, exit time, time to process the request, a request counter as well as the final status code and response content type. In terms of Request Logger Service formats, request entry is logged with the format `%t [%R] -> %m %U%q %H` and request exit is logged with the format `%{end}t [%R] <- %s %{Content-Type}o %Dms` (See [Log Format Specification](#log-format-specification) below for the specification of the format). | | Request Log Type | `request.log.outputtype` | Logger Name | Type of Logger named with the Logger Name parameter. See [Log Output](#log-output) below | | Enable Request Log | `request.log.enabled` | true | Whether to enable Request logging or not. | -| Access Log Name | `access.log.output` | logs/access.log | Name of the destination for the access log. The access log writes an entry for each request as the request terminates using the NCSA extended/combined log format. In terms of Request Logger Service formats the access log is written with the format `%h %l %u %t "%r" %>s %b "%\{Referer}i" "%\{User-Agent}i"` (See [Log Format Specification](#log-format-specification) below for the specification of the format). | +| Access Log Name | `access.log.output` | logs/access.log | Name of the destination for the access log. The access log writes an entry for each request as the request terminates using the NCSA extended/combined log format. In terms of Request Logger Service formats the access log is written with the format `%h %l %u %t "%r" %>s %b "%{Referer}i" "%{User-Agent}i"` (See [Log Format Specification](#log-format-specification) below for the specification of the format). | | Access Log Type | `access.log.outputtype` | Logger Name | Type of Logger named with the Logger Name parameter. See [Log Output](#log-output) below | | Enable Access Log | `access.log.enabled` | true | Whether to enable Access logging or not. | @@ -65,28 +62,28 @@ The characteristics of the request itself are logged by placing "%" directives i | `%A` | Local IP-address | | `%B` | Size of response in bytes, excluding HTTP headers. | | `%b` | Size of response in bytes, excluding HTTP headers. In CLF format, i.e. a '-' rather than a 0 when no bytes are sent. | -| `%\{Foobar}C` | The contents of cookie Foobar in the request sent to the server. | +| `%{Foobar}C` | The contents of cookie Foobar in the request sent to the server. | | `%D` | The time taken to serve the request, in milliseconds. Please note that this deviates from the Apache httpd format. | -| `%\{FOOBAR}e` |Not supported in Sling; prints nothing. | +| `%{FOOBAR}e` |Not supported in Sling; prints nothing. | | `%f` | The absolute path of the resolved resource | | `%h` | Remote host | | `%H` | The request protocol | -| `%\{Foobar}i` | The contents of Foobar: header line(s) in the request sent to the server. | +| `%{Foobar}i` | The contents of Foobar: header line(s) in the request sent to the server. | | `%k` | Not supported in Sling; prints nothing. | | `%l` | Not supported in Sling; prints nothing. | | `%m` | The request method | -| `%\{Foobar}n` | Not supported in Sling; prints nothing. | -| `%\{Foobar}o` | The contents of Foobar: header line(s) in the reply. | +| `%{Foobar}n` | Not supported in Sling; prints nothing. | +| `%{Foobar}o` | The contents of Foobar: header line(s) in the reply. | | `%p` | The canonical port of the server serving the request | -| `%\{format}p` | The canonical port of the server serving the request or the server's actual port or the client's actual port. Valid formats are canonical, local, or remote. | +| `%{format}p` | The canonical port of the server serving the request or the server's actual port or the client's actual port. Valid formats are canonical, local, or remote. | | `%P` | The *name of the thread* ~~process ID of the child~~ that serviced the request. | -| `%\{format}P` | Same as `%P`; the `format` parameter is ignored. | +| `%{format}P` | Same as `%P`; the `format` parameter is ignored. | | `%q` | The query string (prepended with a ? if a query string exists, otherwise an empty string) | | `%r` | First line of request | | `%R` | The number of requests processed by Sling since the last start. | | `%s` | Status. | | `%t` | Time the request was received (standard english format) | -| `%\{format}t` | Same as `%t`; the `format` parameter is ignored unless it is the literal value *end* indicating to use the time of request terminating (instead of the time of request receipt). | +| `%{format}t` | Same as `%t`; the `format` parameter is ignored unless it is the literal value *end* indicating to use the time of request terminating (instead of the time of request receipt). | | `%T` | The time taken to serve the request, in seconds. | | `%u` | Remote user (from auth; may be bogus if return status (%s) is 401) | | `%U` | The URL path requested, not including any query string. | @@ -99,14 +96,14 @@ The characteristics of the request itself are logged by placing "%" directives i **Modifiers** -Particular items can be restricted to print only for responses with specific HTTP status codes by placing a comma-separated list of status codes immediately following the "%". For example, "%400,501\{User-agent}i" logs User-agent on 400 errors and 501 errors only. For other status codes, the literal string "-" will be logged. The status code list may be preceded by a "!" to indicate negation: "%!200,304,302\{Referer}i" logs Referer on all requests that do not return one of the three specified codes. +Particular items can be restricted to print only for responses with specific HTTP status codes by placing a comma-separated list of status codes immediately following the "%". For example, "%400,501{User-agent}i" logs User-agent on 400 errors and 501 errors only. For other status codes, the literal string "-" will be logged. The status code list may be preceded by a "!" to indicate negation: "%!200,304,302{Referer}i" logs Referer on all requests that do not return one of the three specified codes. The Apache httpd modifiers "<" and ">" are not supported by Sling and currently ignored. **Some Notes** -For security reasons non-printable and other special characters in %C, %i and %o are escaped using \uhhhh sequences, where hhhh stands for the hexadecimal representation of the character's unicode value. Exceptions from this rule are " and \, which are escaped by prepending a backslash, and all whitespace characters, which are written in their Java-style notation (\n, \t, etc). +For security reasons non-printable and other special characters in %C, %i and %o are escaped using uhhhh sequences, where hhhh stands for the hexadecimal representation of the character's unicode value. Exceptions from this rule are " and , which are escaped by prepending a backslash, and all whitespace characters, which are written in their Java-style notation (n, t, etc). #### Rotating Logger Files @@ -115,8 +112,8 @@ If you want to write the request (and access) logging information into a rotated 1. Configure the Log Type to be a *Logger Name* and some usefull Logger name. For example `clientlog.request`. 1. Create an *Apache Sling Logging Logger Configuration* for this Logger name according to [Logging Configuration]({{ refs.logging-logger-configuration.path }}) with the following setup: - * Allow message at INFO (Information) level to be logged which is the level used by the request loggers - * Define the appropriate log file name, for example `logs/client.request.log` - * Use only `\{5`} as the message format because request logger messages are generally already fully formated with required timestamp etc. - * Add any Logger names used for the client request log configuration, `clientlog.request` in the example above, to the Logger field. By clicking on the `+` (plus) button you may add more than a single logger name whose messages are written to this file. +* Allow message at INFO (Information) level to be logged which is the level used by the request loggers +* Define the appropriate log file name, for example `logs/client.request.log` +* Use only `{5`} as the message format because request logger messages are generally already fully formated with required timestamp etc. +* Add any Logger names used for the client request log configuration, `clientlog.request` in the example above, to the Logger field. By clicking on the `+` (plus) button you may add more than a single logger name whose messages are written to this file. 1. Optionally, you may create an *Apache Sling Logging Writer Configuration* for the log file defined in the previous step to better control rotation setup. See [Log Writer Configuration]({{ refs.logging-log-writer-configuration.path }}) for full details. http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/development/dependency-management.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/dependency-management.md b/content/documentation/development/dependency-management.md index d96ae5f..88b9e1d 100644 --- a/content/documentation/development/dependency-management.md +++ b/content/documentation/development/dependency-management.md @@ -1,10 +1,7 @@ -title=TODO title for dependency-management.md -date=1900-01-01 -type=post -tags=blog +title=Dependency Management +type=page status=published ~~~~~~ -Title: Dependency Management Excerpt: This page is about how we do and don't do dependency management in the Sling project. This page is about how we do and don't do dependency management in the Sling project. @@ -35,9 +32,9 @@ As a consequence, I suggest we drop dependency management in the parent POM (alm The parent POM only does dependency management for build time dependencies and a very limited number of API dependencies used Sling wide. These dependencies are: - * All plugin dependencies. That is `pluginManagement` is still used. Maven plugins are actually build time dependencies and therefore have no influence on the actual deployment. - * Dependencies on commonly used testing environment helpers. Test helper classes are also build time dependencies used to run the unit and integration tests. As such, they may well be managed. - * Sling makes a small number of assumptions about the environment, which we codify in the dependency management: The minimum version number of the OSGi specificaiton used, the Servlet API version and the JCR API version. +* All plugin dependencies. That is `pluginManagement` is still used. Maven plugins are actually build time dependencies and therefore have no influence on the actual deployment. +* Dependencies on commonly used testing environment helpers. Test helper classes are also build time dependencies used to run the unit and integration tests. As such, they may well be managed. +* Sling makes a small number of assumptions about the environment, which we codify in the dependency management: The minimum version number of the OSGi specificaiton used, the Servlet API version and the JCR API version. The `<dependencyManagement>` element currently contains the following managed dependencies: http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/development/embedding-sling.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/embedding-sling.md b/content/documentation/development/embedding-sling.md index 7dd3730..e07672b 100644 --- a/content/documentation/development/embedding-sling.md +++ b/content/documentation/development/embedding-sling.md @@ -1,18 +1,15 @@ -title=TODO title for embedding-sling.md -date=1900-01-01 -type=post -tags=blog +title=Embedding Sling +type=page status=published ~~~~~~ translation_pending: true -Title: Embedding Sling The Sling Launchpad Launcher can be used to embed the OSGi Framework startup in your own Java application. This functionality is implemented in the [Sling Launchpad Base project](http://svn.apache.org/repos/asf/sling/trunk/launchpad/base). This project has the following features: * Builds three artifacts: - * A standalone Java Application with the artifact qualifier *app*; e.g. `org.apache.sling.launchpad.base-2.3.1-SNAPSHOT-app.jar` - * A Web Application with the artifact qualifier *webapp*; e.g `org.apache.sling.launchpad.base-2.3.1-SNAPSHOT-wepabb.war` - * The primary artifact without an artifact qualifier; e.g. `org.apache.sling.launchpad.base-2.3.1-SNAPSHOT.jar` +* A standalone Java Application with the artifact qualifier *app*; e.g. `org.apache.sling.launchpad.base-2.3.1-SNAPSHOT-app.jar` +* A Web Application with the artifact qualifier *webapp*; e.g `org.apache.sling.launchpad.base-2.3.1-SNAPSHOT-wepabb.war` +* The primary artifact without an artifact qualifier; e.g. `org.apache.sling.launchpad.base-2.3.1-SNAPSHOT.jar` * Embeds the OSGi Framework (Apache Felix) in the primary artifact * Encapsulates the OSGi Framework in its own `URLClassLoader` * Supports Framework restart http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/development/getting-and-building-sling.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/getting-and-building-sling.md b/content/documentation/development/getting-and-building-sling.md index fad2c3b..331c7d4 100644 --- a/content/documentation/development/getting-and-building-sling.md +++ b/content/documentation/development/getting-and-building-sling.md @@ -1,31 +1,28 @@ -title=TODO title for getting-and-building-sling.md -date=1900-01-01 -type=post -tags=blog +title=Getting and Building Sling +type=page status=published ~~~~~~ -Title: Getting and Building Sling Excerpt: A quick guide for getting the Sling source, then building and running the resulting Sling instance; either without or with Eclipse. A quick guide for getting the Sling source, then building and running the resulting Sling instance; either without or with Eclipse. -Note that you don't *have* to build Sling yourself, if you don't need the bleeding-edge stuff you can get prebuilt +Note that you don't *have* to build Sling yourself, if you don't need the bleeding-edge stuff you can get prebuilt binaries from the [Downloads](/downloads.cgi) page. But those, especially the launchpad runnable jar, are not released often and can be outdated. In case of doubt, build it yourself as shown below or ask on the Sling users mailing list. Rather than performing a full build of Sling, which can take 5-10 minutes on a recent computer once your local Maven repository is up to date, it's recommended to build only the launchpad and the modules you're interested in. -## tl:dr - Short form build + run instructions +## tl:dr - Short form build + run instructions If you already have the required svn (or Git, see below) client, JDK and Maven installed, here's the short form recipe: - $ svn co http://svn.apache.org/repos/asf/sling/trunk sling - $ cd sling # you are now in the Sling SVN checkout - $ cd launchpad/builder - $ mvn --update-snapshots clean install - $ export DBG="-Xmx384M -agentlib:jdwp..." # (see below) - $ java $DBG -jar target/org.apache.sling.launchpad... # (see below) - +$ svn co http://svn.apache.org/repos/asf/sling/trunk sling +$ cd sling # you are now in the Sling SVN checkout +$ cd launchpad/builder +$ mvn --update-snapshots clean install +$ export DBG="-Xmx384M -agentlib:jdwp..." # (see below) +$ java $DBG -jar target/org.apache.sling.launchpad... # (see below) + With this, Sling should be running at http://localhost:8080 with remote debugging active as per the $DBG variable. ## Prerequisites @@ -37,8 +34,8 @@ Before you begin, you need to have the following tools installed on your system: If you want to set up Eclipse (not required to build Sling) you'll also need the following installed: -* Eclipse (tested with 3.4.2 and 3.5.x on Win XP, SP3, 3.6.x on Win7, 3.7 on MacOS X 10.6); just a plain installation of the platform runtime binary and the JDT will be adequate (you can install the IDE for Java Developers for convenience) -* M2Eclipse plugin for Eclipse (sonatype) \-> [instructions](http://m2eclipse.sonatype.org/installing-m2eclipse.html) +* Eclipse (tested with 3.4.2 and 3.5.x on Win XP, SP3, 3.6.x on Win7, 3.7 on MacOS X 10.6); just a plain installation of the platform runtime binary and the JDT will be adequate (you can install the IDE for Java Developers for convenience) +* M2Eclipse plugin for Eclipse (sonatype) -> [instructions](http://m2eclipse.sonatype.org/installing-m2eclipse.html) * [Subversive plugin](http://www.polarion.com/products/svn/subversive.php) or [Subclipse-plugin](http://subclipse.tigris.org) for Eclipse ## Environment Setup @@ -47,16 +44,16 @@ The full build process requires quite a lot of resources, so you may run into li ### Environment Variable Space -* *Problem* \- Build aborts when trying to launch the integration tests with the message +* *Problem* - Build aborts when trying to launch the integration tests with the message + +[INFO] Error while executing forked tests.; nested exception is org.apache.maven.surefire.booter.shade.org.codehaus.plexus.util.cli.CommandLineException: Error setting up environmental variables - [INFO] Error while executing forked tests.; nested exception is org.apache.maven.surefire.booter.shade.org.codehaus.plexus.util.cli.CommandLineException: Error setting up environmental variables - - error=12, Not enough space +error=12, Not enough space This problem is caused by insufficient swap space. When running the integration tests in the `launchpad/testing` modules, a process is launched by calling the `exec` system call. This copies the process (copy-on-write, though) and thus allocates as much virtual memory as is owned by the parent process. This may fail if swap space is exhausted. -* *Platform* \- OpenSolaris -* *Fix* \- If this issue persists you will need to check your system requirements and configuration with regard to swap, before taking action - if necessary. +* *Platform* - OpenSolaris +* *Fix* - If this issue persists you will need to check your system requirements and configuration with regard to swap, before taking action - if necessary. ## Configuring Maven @@ -70,7 +67,7 @@ See [MavenTipsAndTricks](/documentation/development/maventipsandtricks.html). 1. Checkout Sling from the Subversion repository - $ svn checkout http://svn.apache.org/repos/asf/sling/trunk sling +$ svn checkout http://svn.apache.org/repos/asf/sling/trunk sling ### From the Sling GitHub mirror @@ -78,7 +75,7 @@ See [MavenTipsAndTricks](/documentation/development/maventipsandtricks.html). 1. Checkout Sling from the GitHub mirror - $ git clone https://github.com/apache/sling.git +$ git clone https://github.com/apache/sling.git ### With Eclipse Subversive or Subclipse First note how simple the above SVN instructions are...but if you *really* want to do this, read on. @@ -91,14 +88,14 @@ Also, make sure that you have installed either the "Maven SCM handler for Subcli It's best to create a new workspace for the sling project: - 1. List item - 1. Menu: File->Switch Workspace->Other... - 1. Enter a path for the new workspace and click OK - 1. When Eclipse has restarted it's time to adjust some configs - 1. Turn off automatic build (Menu: Project->Build Automatically) - 1. Go to menu: Eclipse->Preferences, in the preferences dialog select Java \-> Compiler \-> Errors/Warnings - 1. Expand the "Deprecated and restricted API" and change "Forbidden references (access rules)" from "Error" to "Warning" - 1. Click OK +1. List item +1. Menu: File->Switch Workspace->Other... +1. Enter a path for the new workspace and click OK +1. When Eclipse has restarted it's time to adjust some configs +1. Turn off automatic build (Menu: Project->Build Automatically) +1. Go to menu: Eclipse->Preferences, in the preferences dialog select Java -> Compiler -> Errors/Warnings +1. Expand the "Deprecated and restricted API" and change "Forbidden references (access rules)" from "Error" to "Warning" +1. Click OK #### Checkout the Sling source @@ -108,7 +105,7 @@ It's best to create a new workspace for the sling project: 1. In the "SCM URL" field pick "SVN" and enter the url "http://svn.apache.org/repos/asf/sling/trunk"; 1. Click Finish -Eclipse will now start to download the source and import the Maven projects. You might encounter some "Problem Occured" dialogs about "An internal error...", but just click OK on those and let Eclipse continue with the import. Be warned: This could take some time (it was 30 minutes on my laptop)\! +Eclipse will now start to download the source and import the Maven projects. You might encounter some "Problem Occured" dialogs about "An internal error...", but just click OK on those and let Eclipse continue with the import. Be warned: This could take some time (it was 30 minutes on my laptop)! Possibly something in sling-builder might get a bit messed up (I didn't experience that problem, but Pontus reported it) then you can simply fix it with revert: @@ -126,19 +123,19 @@ you're working on at the moment. 1. Enter the directory, then do a build and local install of the launchpad (below are unix/linux commands, slightly different under windows) - $ cd sling - $ cd launchpad/builder # you are now in the Sling SVN checkout - $ mvn --update-snapshots clean install - $ java -jar target/org.apache.sling.launchpad-*.jar -c test -f - +$ cd sling +$ cd launchpad/builder # you are now in the Sling SVN checkout +$ mvn --update-snapshots clean install +$ java -jar target/org.apache.sling.launchpad-*.jar -c test -f - <div class="note"> When starting Sling inside the `launchpad/builder` folder you should not use the default Sling Home folder name `sling` because this folder is removed when running `mvn clean`. </div> Messages should now be printed to the console which is being used as the "log file"; - -* the `-f` command line option is set to `-`, indicating the use of standard output as the log file. -* the `-c sling` command line option instructs Sling to use the `sling` directory in the current directory for its data store, which is the Apache Felix bundle archive, the Jackrabbit repository data and configuration. You may also specify another directory here, either a relative or absolute path name (See also [Configuration](/documentation/configuration.html) for more information). + +* the `-f` command line option is set to `-`, indicating the use of standard output as the log file. +* the `-c sling` command line option instructs Sling to use the `sling` directory in the current directory for its data store, which is the Apache Felix bundle archive, the Jackrabbit repository data and configuration. You may also specify another directory here, either a relative or absolute path name (See also [Configuration](/documentation/configuration.html) for more information). * Use the `-h` option to see the list of flags and options. After all messages have been printed you should be able to open the Sling Management Console by pointing your web browser at [http://localhost:8080/system/console](http://localhost:8080/system/console). You will be prompted for a user name and password. Enter `admin` for both the user name and the password (this may be set on the *Configuration* page later). From this console, you can manage the installed bundles, modify configuration objects, dump a configuration status and see some system information. @@ -147,9 +144,9 @@ To stop Sling, just hit `Ctrl-C` in the console or click the *Stop* button on th 2. Enter the directory of the bundle you're working on, then do a build and deploy the bundle to the running launchpad instance - $ cd sling - $ cd bundles/servlets/get - $ mvn clean install sling:install +$ cd sling +$ cd bundles/servlets/get +$ mvn clean install sling:install The Maven build command ensure that: @@ -165,7 +162,7 @@ The Maven build command ensure that: 1. Click "Browse Workspace..." and select "sling-builder" 1. Enter "clean install" in Goals 1. Click on the JRE tab -1. Enter "-Xmx256m \-XX:MaxPermSize=128m" in "VM arguments" +1. Enter "-Xmx256m -XX:MaxPermSize=128m" in "VM arguments" 1. Click Apply 1. Click Run @@ -178,9 +175,9 @@ In the case that you do not want to use the M2Eclipse plugin there's another set 1. Add all required libraries to the build path 1. Now you can build either in Eclipse or even better use "mvn clean install" on the command line -If you use "mvn clean install" to build Sling be sure you have set MAVEN_OPTS to "-Xmx384m \-XX:PermSize=256m" otherwise you will probably get OutOfmemory errors. +If you use "mvn clean install" to build Sling be sure you have set MAVEN_OPTS to "-Xmx384m -XX:PermSize=256m" otherwise you will probably get OutOfmemory errors. -Congratulations \! You should now have a running Sling instance, that you can start playing around with. +Congratulations ! You should now have a running Sling instance, that you can start playing around with. ## Further Tips and Tricks @@ -191,7 +188,7 @@ You can use remote debugging to debug Sling in Eclipse, here's a little How-To 1. start Sling from the command line with - java -Xmx384M -agentlib:jdwp=transport=dt_socket,address=30303,server=y,suspend=n -jar org.apache.sling.launchpad.app-6-SNAPSHOT.jar +java -Xmx384M -agentlib:jdwp=transport=dt_socket,address=30303,server=y,suspend=n -jar org.apache.sling.launchpad.app-6-SNAPSHOT.jar 1. Open Menu Run-> Debug configurations 1. Right-click on "Remote Java Applications" @@ -211,7 +208,7 @@ Now you should be able to set breakpoints, evaluate properties, and so on as usu In the same way as you can debug the sling app, you are also able to debug a maven test. Just run the maven tests like this - mvn -Dmaven.surefire.debug test +mvn -Dmaven.surefire.debug test The tests will automatically pause and await a remote debugger on port 5005. You can then attach to the running tests using Eclipse. You can setup a "Remote Java Application" launch configuration via the menu command "Run" > "Open Debug Dialog..." (see above). @@ -227,6 +224,6 @@ The easiest way that I found is to create a new folder in the existing Eclipse w * Choose File/Import in Eclipse and select "Existing projects into workspace" * Now you can create, edit and compile the files in Eclipse * To create the bundle jar and install it, just use the command line "mvn clean install" in the project directory -* If you have a running Sling app you can install the bundle from the command line with "mvn \-P autoInstallBundle clean install \-Dsling.url=http://localhost:8080/system/console"; +* If you have a running Sling app you can install the bundle from the command line with "mvn -P autoInstallBundle clean install -Dsling.url=http://localhost:8080/system/console"; If adding dependencies to the poms, run mvn eclipse:eclipse again and refresh the project in Eclipse. Debugging works as described above. http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/development/hamcrest.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/hamcrest.md b/content/documentation/development/hamcrest.md index 67f6870..d8e9bf9 100644 --- a/content/documentation/development/hamcrest.md +++ b/content/documentation/development/hamcrest.md @@ -1,10 +1,7 @@ -title=TODO title for hamcrest.md -date=1900-01-01 -type=post -tags=blog +title=Hamcrest Integration +type=page status=published ~~~~~~ -Title: Hamcrest Integration Deeper integration with the [Hamcrest matcher library](http://hamcrest.org/). @@ -14,11 +11,11 @@ Deeper integration with the [Hamcrest matcher library](http://hamcrest.org/). This module has not yet been officially released. </div> - #!xml - <dependency> - <groupId>org.apache.sling</groupId> - <artifactId>org.apache.sling.testing.hamcrest</artifactId> - </dependency> +#!xml +<dependency> +<groupId>org.apache.sling</groupId> +<artifactId>org.apache.sling.testing.hamcrest</artifactId> +</dependency> Note that to keep the classpath consistent this module has all its dependencies marked as `provided`. It relies on your own project to define the needed dependencies, such as `org.hamcrest:hamcrest-core` and `org.apache.sling:org.apache.sling.api` . @@ -28,21 +25,21 @@ See latest version on the [downloads page](/downloads.cgi). The class `org.apache.sling.testing.hamcrest.ResourceMatchers` is the main entry point. It contains static methods that can be used to create assertions. - #!java - import static org.apache.sling.hamcrest.ResourceMatchers.resourceOfType; - - public void MyServiceTest { - - @Test - public void loadResources() { - Map<String, Object> expectedProperties = /* define properties */; - Resource resource = /* load resource */ null; - - assertThat(resource, resourceOfType("my/app")); - assertThat(resource, hasChildren("header", "body")); - assertThat(resource, resourceWithProps(expectedProperties)); - } - - } +#!java +import static org.apache.sling.hamcrest.ResourceMatchers.resourceOfType; + +public void MyServiceTest { + +@Test +public void loadResources() { +Map<String, Object> expectedProperties = /* define properties */; +Resource resource = /* load resource */ null; + +assertThat(resource, resourceOfType("my/app")); +assertThat(resource, hasChildren("header", "body")); +assertThat(resource, resourceWithProps(expectedProperties)); +} + +} The Slingshot sample application uses these matchers, see [SetupServiceTest.java](http://svn.apache.org/repos/asf/sling/trunk/samples/slingshot/src/test/java/org/apache/sling/sample/slingshot/impl/SetupServiceTest.java) for an example. http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/development/htl-maven-plugin.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/htl-maven-plugin.md b/content/documentation/development/htl-maven-plugin.md index 4df28c6..1a95313 100644 --- a/content/documentation/development/htl-maven-plugin.md +++ b/content/documentation/development/htl-maven-plugin.md @@ -1,9 +1,6 @@ -title=TODO title for htl-maven-plugin.md -date=1900-01-01 -type=post -tags=blog +title=HTL Maven Plugin +type=page status=published ~~~~~~ -Title: HTL Maven Plugin See [Apache Sling HTL Maven Plugin documentation](http://sling.apache.org/components/htl-maven-plugin/). http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/development/ide-tooling.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/ide-tooling.md b/content/documentation/development/ide-tooling.md index b7dc9c0..d50807c 100644 --- a/content/documentation/development/ide-tooling.md +++ b/content/documentation/development/ide-tooling.md @@ -1,10 +1,7 @@ -title=TODO title for ide-tooling.md -date=1900-01-01 -type=post -tags=blog +title=Sling IDE tooling for Eclipse User Guide +type=page status=published ~~~~~~ -Title: Sling IDE tooling for Eclipse User Guide [TOC] @@ -24,7 +21,7 @@ The links to the latest update site, including a permanent URL which stays up to The update sites are provided as a convenience for users that do not wish to build the project themselves. Building the project only requires a recent Maven installation. The project can be checked out, either [from trunk for the latest development version](https://svn.apache.org/repos/asf/sling/trunk/tooling/ide/) or [from a tag for released versions](https://svn.apache.org/repos/asf/sling/tags/), where the tags names have the format sling-ide-tooling-$VERSION. Once you have obtained the source code, it is enough to run - mvn package +mvn package and you will find a p2 update site in p2update/target/repository . http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/development/ide-tooling/ide-tooling-incremental-build.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/ide-tooling/ide-tooling-incremental-build.md b/content/documentation/development/ide-tooling/ide-tooling-incremental-build.md index 022251f..5322669 100644 --- a/content/documentation/development/ide-tooling/ide-tooling-incremental-build.md +++ b/content/documentation/development/ide-tooling/ide-tooling-incremental-build.md @@ -1,10 +1,7 @@ -title=TODO title for ide-tooling-incremental-build.md -date=1900-01-01 -type=post -tags=blog +title=Incremental Builds in Sling IDE tooling for Eclipse +type=page status=published ~~~~~~ -Title: Incremental Builds in Sling IDE tooling for Eclipse [TOC] http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/development/issue-tracker.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/issue-tracker.md b/content/documentation/development/issue-tracker.md index 88a55a1..e1d0d03 100644 --- a/content/documentation/development/issue-tracker.md +++ b/content/documentation/development/issue-tracker.md @@ -1,10 +1,7 @@ -title=TODO title for issue-tracker.md -date=1900-01-01 -type=post -tags=blog +title=Issue Tracker +type=page status=published ~~~~~~ -Title: Issue Tracker Apache Sling uses Jira for tracking bug reports and requests for improvements, new features, and other changes. http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/development/jcr-mock.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/jcr-mock.md b/content/documentation/development/jcr-mock.md index 1e80cd2..5d1a8db 100644 --- a/content/documentation/development/jcr-mock.md +++ b/content/documentation/development/jcr-mock.md @@ -1,10 +1,7 @@ -title=TODO title for jcr-mock.md -date=1900-01-01 -type=post -tags=blog +title=JCR Mocks +type=page status=published ~~~~~~ -Title: JCR Mocks Mock implementation of selected JCR APIs for easier testing. It stores all data in-memory in a HashMap to ensure instantly creating and destroying of the JCR repository. @@ -13,11 +10,11 @@ Mock implementation of selected JCR APIs for easier testing. It stores all data ## Maven Dependency - #!xml - <dependency> - <groupId>org.apache.sling</groupId> - <artifactId>org.apache.sling.testing.jcr-mock</artifactId> - </dependency> +#!xml +<dependency> +<groupId>org.apache.sling</groupId> +<artifactId>org.apache.sling.testing.jcr-mock</artifactId> +</dependency> See latest version on the [downloads page](/downloads.cgi). @@ -38,7 +35,7 @@ The following features are *not supported*: * Transactions not supported * Observation events can be registered but are ignored * Access control always grants access -* Exporting/Importing data via document and system views not supported +* Exporting/Importing data via document and system views not supported * Workspace management methods not supported @@ -50,12 +47,12 @@ The factory class `MockJcr` allows to instantiate the different mock implementat Example: - #!java - // get session - Session session = MockJcr.newSession(); +#!java +// get session +Session session = MockJcr.newSession(); - // get repository - Repository repository = MockJcr.newRepository(); +// get repository +Repository repository = MockJcr.newRepository(); The repository is empty and contains only the root node. You can use the JCR API to read or write content. @@ -66,14 +63,14 @@ If you want to test code that contains a JCR query you can simulate a query exec Example: - #!java - // prepare mocked search result - List<Node> resultNodes = ImmutableList.of(node1, node2, node3); +#!java +// prepare mocked search result +List<Node> resultNodes = ImmutableList.of(node1, node2, node3); - // return this result for all queries - MockJcr.setQueryResult(session, resultNodes); +// return this result for all queries +MockJcr.setQueryResult(session, resultNodes); - // return this result for a specific query - MockJcr.setQueryResult(session, "your query statement", Query.JCR_SQL2, resultNodes); +// return this result for a specific query +MockJcr.setQueryResult(session, "your query statement", Query.JCR_SQL2, resultNodes); Alternatively you can use the `MockJcr.addQueryResultHandler` method to pass a callback object that allows you to return a query result after inspecting the given query object. http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/development/jspc.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/jspc.md b/content/documentation/development/jspc.md index dde8f8d..e1a3ab8 100644 --- a/content/documentation/development/jspc.md +++ b/content/documentation/development/jspc.md @@ -1,9 +1,6 @@ -title=TODO title for jspc.md -date=1900-01-01 -type=post -tags=blog +title=HTL Maven Plugin +type=page status=published ~~~~~~ -Title: HTL Maven Plugin See [Apache Sling JspC Maven Plugin documentation](http://sling.apache.org/components/jspc-maven-plugin/).
