You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by bd...@apache.org on 2017/06/19 12:31:17 UTC
[33/50] [abbrv] sling-site git commit: Fix front matter,
using existing titles
http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.md
----------------------------------------------------------------------
diff --git a/content/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.md b/content/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.md
index 2a1023d..5c69bd4 100644
--- a/content/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.md
+++ b/content/documentation/bundles/managing-users-and-groups-jackrabbit-usermanager.md
@@ -1,10 +1,7 @@
-title=TODO title for managing-users-and-groups-jackrabbit-usermanager.md
-date=1900-01-01
-type=post
-tags=blog
+title=Managing users and groups (jackrabbit.usermanager)
+type=page
status=published
~~~~~~
-Title: Managing users and groups (jackrabbit.usermanager)
The `jackrabbit-usermanager` bundle delivers a REST interface to create, update and delete users and groups in the JCR. After installing the `jackrabbit-usermanager` bundle all REST services are exposed under the path `/system/userManager`. Its interface for modifing/creating authorizables is similar to the [SlingPostServlet](/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html).
@@ -15,21 +12,21 @@ For getting information about existing authorizables it provides all authorizabl
## List users
To list existing users a GET request to the `/system/userManager/user` resource can be issued. Depending on the configuration of the [Default GET Servlet](/documentation/bundles/rendering-content-default-get-servlets.html)
- and/or the availability of a Servlet or Script handling the `sling/users` resource type, a result may be delivered/
+and/or the availability of a Servlet or Script handling the `sling/users` resource type, a result may be delivered/
Example with curl and the default JSON rendering:
- $ curl http://localhost:8080/system/userManager/user.tidy.1.json
- {
- "admin": {
- "memberOf": [],
- "declaredMemberOf": []
- },
- "anonymous": {
- "memberOf": [],
- "declaredMemberOf": []
- }
- }
+$ curl http://localhost:8080/system/userManager/user.tidy.1.json
+{
+"admin": {
+"memberOf": [],
+"declaredMemberOf": []
+},
+"anonymous": {
+"memberOf": [],
+"declaredMemberOf": []
+}
+}
## Get user
@@ -38,11 +35,11 @@ The properties of a single user can be retrieved by sending a GET request to the
Example with curl and the default JSON rendering:
- $ curl http://localhost:8080/system/userManager/user/admin.tidy.1.json
- {
- "memberOf": [],
- "declaredMemberOf": []
- }
+$ curl http://localhost:8080/system/userManager/user/admin.tidy.1.json
+{
+"memberOf": [],
+"declaredMemberOf": []
+}
If a non-existing user is requested a `404/NOT FOUND` status is sent back.
@@ -51,14 +48,14 @@ If a non-existing user is requested a `404/NOT FOUND` status is sent back.
## Create user
To create a new user POST a request to `/system/userManager/user.create.<html or json>`. The following parameters are available:
-
+
Parameter Name | Required | Description
---- | --- | ---
+--- | --- | ---
`:name` | yes | The name of the new user
`pwd` | yes | The password of the new user
-`pwdConfirm` | yes | The password of the new user (must be equal to the value of `pwd`)
+`pwdConfirm` | yes | The password of the new user (must be equal to the value of `pwd`)
`<anyproperty>` | no | Additional parameters will be stored as node properties in the JCR. Nested properties are supported since 2.2.6 ([SLING-6747](https://issues.apache.org/jira/browse/SLING-6747)).
-
+
Responses:
Status Code | Description
@@ -68,22 +65,21 @@ Status Code | Description
Example with curl:
- curl -F:name=myuser -Fpwd=password -FpwdConfirm=password -Fanyproperty1=value1 \
- http://localhost:8080/system/userManager/user.create.html
+curl -F:name=myuser -Fpwd=password -FpwdConfirm=password -Fanyproperty1=value1 http://localhost:8080/system/userManager/user.create.html
## Update user
To update an existing user POST a request to `/system/userManager/user/username.update.<html or json>`. You can NOT update the username or the password (see Change Password below) only the additional properties are updateable through this URL. The following parameters are available:
-
+
Parameter Name | Required | Description
---- | --- | ---
+--- | --- | ---
`:disabled` | no | (since version 2.1.1) If `true` disables the user to block further login attempts. If `false` enables a disabled user.
-`:disabledReason` | no | Specifies the reason why a user has been disabled.
-`<anyproperty>` | no | Additional parameters will be stored as node properties in the JCR. Nested properties are supported since 2.2.6 ([SLING-6747](https://issues.apache.org/jira/browse/SLING-6747)).
-`<anyproperty>@Delete` | no | Properties with @Delete at the end of the name will be deleted in the JCR. Nested properties are supported since 2.2.6 ([SLING-6747](https://issues.apache.org/jira/browse/SLING-6747)).
-
+`:disabledReason` | no | Specifies the reason why a user has been disabled.
+`<anyproperty>` | no | Additional parameters will be stored as node properties in the JCR. Nested properties are supported since 2.2.6 ([SLING-6747](https://issues.apache.org/jira/browse/SLING-6747)).
+`<anyproperty>@Delete` | no | Properties with @Delete at the end of the name will be deleted in the JCR. Nested properties are supported since 2.2.6 ([SLING-6747](https://issues.apache.org/jira/browse/SLING-6747)).
+
Responses:
Status Code | Description
@@ -91,56 +87,54 @@ Status Code | Description
200 | Success, a redirect is sent to the users resource locator with HTML (or JSON) describing status.
404 | User was not found.
500 | Any other failure. HTML (or JSON) explains failure.
-
+
Example
- curl -Fanyproperty1@Delete -Fproperty2=value2 \
- http://localhost:8080/system/userManager/user/myuser.update.html
+curl -Fanyproperty1@Delete -Fproperty2=value2 http://localhost:8080/system/userManager/user/myuser.update.html
## Change password
To change a password of an existing user POST a request to `/system/userManager/user/username.changePassword.<html or json>`. NOTE: since version 2.1.1, the oldPwd is optional if the current user is a user administrator. The following parameters are available:
-
+
Parameter Name | Required | Description
---- | --- | ---
+--- | --- | ---
`oldPwd` | yes | Old password.
`newPwd` | yes | New password.
`newPwdConfirm` | yes | New password (must be equal to the value of `newPwd`).
-
+
Responses:
Status Code | Description
--- | ---
200 | Success, no body.
404 | User was not found.
-500 | Any other failure. HTML (or JSON) explains failure.
-
+500 | Any other failure. HTML (or JSON) explains failure.
+
Example
- curl -FoldPwd=oldpassword -FnewPwd=newpassword -FnewPwdConfirm=newpassword \
- http://localhost:8080/system/userManager/user/myuser.changePassword.html
+curl -FoldPwd=oldpassword -FnewPwd=newpassword -FnewPwdConfirm=newpassword http://localhost:8080/system/userManager/user/myuser.changePassword.html
## Delete user
To delete an existing user POST a request to `/system/userManager/user/username.delete.<html or json>`. The following parameters are available:
-
+
Parameter Name | Required | Description
---- | --- | ---
+--- | --- | ---
`:applyTo` | no | An array of relative resource references to users to be deleted. If this parameter is present, the username from the URL is ignored and all listed users are removed.
-
+
Responses:
Status Code | Description
--- | ---
200 | Success, no body.
404 | User(s) was/were not found.
-500 | Any other failure. HTML (or JSON) explains failure.
-
+500 | Any other failure. HTML (or JSON) explains failure.
+
Example
- curl -Fgo=1 http://localhost:8080/system/userManager/user/myuser.delete.html
+curl -Fgo=1 http://localhost:8080/system/userManager/user/myuser.delete.html
## List groups
@@ -149,27 +143,27 @@ To list existing groups a GET request to the `/system/userManager/group` resourc
Example with curl and the default JSON rendering:
- $ curl http://localhost:8080/system/userManager/group.tidy.1.json
- {
- "UserAdmin": {
- "members": [],
- "declaredMembers": [],
- "memberOf": [],
- "declaredMemberOf": []
- },
- "GroupAdmin": {
- "members": [],
- "declaredMembers": [],
- "memberOf": [],
- "declaredMemberOf": []
- },
- "administrators": {
- "members": [],
- "declaredMembers": [],
- "memberOf": [],
- "declaredMemberOf": []
- }
- }
+$ curl http://localhost:8080/system/userManager/group.tidy.1.json
+{
+"UserAdmin": {
+"members": [],
+"declaredMembers": [],
+"memberOf": [],
+"declaredMemberOf": []
+},
+"GroupAdmin": {
+"members": [],
+"declaredMembers": [],
+"memberOf": [],
+"declaredMemberOf": []
+},
+"administrators": {
+"members": [],
+"declaredMembers": [],
+"memberOf": [],
+"declaredMemberOf": []
+}
+}
## Get group
@@ -178,13 +172,13 @@ The properties of a single group can be retrieved by sending a GET request to th
Example with curl and the default JSON rendering:
- $ curl http://localhost:8080/system/userManager/group/administrators.tidy.1.json
- {
- "members": [],
- "declaredMembers": [],
- "memberOf": [],
- "declaredMemberOf": []
- }
+$ curl http://localhost:8080/system/userManager/group/administrators.tidy.1.json
+{
+"members": [],
+"declaredMembers": [],
+"memberOf": [],
+"declaredMemberOf": []
+}
If a non-existing group is requested a 404/NOT FOUND status is sent back.
@@ -193,51 +187,49 @@ If a non-existing group is requested a 404/NOT FOUND status is sent back.
## Create group
To create a new group POST a request to `/system/userManager/group.create.<html or json>`. The following parameters are available:
-
-
+
+
Parameter Name | Required | Description
---- | --- | ---
-`:name` | yes | The name of the new group
+--- | --- | ---
+`:name` | yes | The name of the new group
`<anyproperty>` | no | Additional parameters will be stored as node properties in the JCR. Nested properties are supported since 2.2.6 ([SLING-6747](https://issues.apache.org/jira/browse/SLING-6747)).
-
+
Responses:
Status Code | Description
--- | ---
200 | Success, a redirect is sent to the group resource locator with HTML (or JSON) describing status
-500 | Failure including group already exists. HTML (or JSON) explains failure.
-
-
+500 | Failure including group already exists. HTML (or JSON) explains failure.
+
+
Example with curl:
- curl -F:name=mygroup -Fanyproperty1=value1 \
- http://localhost:8080/system/userManager/group.create.html
+curl -F:name=mygroup -Fanyproperty1=value1 http://localhost:8080/system/userManager/group.create.html
## Update group
To update an existing group POST a request to `/system/userManager/group/groupname.update.<html or json>`. You can NOT update the name of the group only the additional properties are updateable. The following parameters are available:
-
+
Parameter Name | Required | Description
---- | --- | ---
+--- | --- | ---
`:member` | no | user(s) (name or URI) to add to the group as a member. Can also be an array of users.
-`:member@Delete` | no | user(s) (name or URI) to remove from the group. Can also be an array of users.
+`:member@Delete` | no | user(s) (name or URI) to remove from the group. Can also be an array of users.
`<anyproperty>` | no | Additional parameters will be stored as node properties in the JCR. Nested properties are supported since 2.2.6 ([SLING-6747](https://issues.apache.org/jira/browse/SLING-6747)).
-`<anyproperty>@Delete` | no | Properties with @Delete at the end of the name will be deleted in the JCR. Nested properties are supported since 2.2.6 ([SLING-6747](https://issues.apache.org/jira/browse/SLING-6747)).
-
+`<anyproperty>@Delete` | no | Properties with @Delete at the end of the name will be deleted in the JCR. Nested properties are supported since 2.2.6 ([SLING-6747](https://issues.apache.org/jira/browse/SLING-6747)).
+
Responses:
Status Code | Description
--- | ---
200 | Success, a redirect is sent to the group resource locator with HTML (or JSON) describing status.
404 | Group was not found.
-500 | Any other failure. HTML (or JSON) explains failure.
-
-
+500 | Any other failure. HTML (or JSON) explains failure.
+
+
Example
- curl -Fanyproperty1@Delete -Fproperty2=value2 -F ":member=/system/userManager/user/myuser" \
- http://localhost:8080/system/userManager/group/mygroup.update.html
+curl -Fanyproperty1@Delete -Fproperty2=value2 -F ":member=/system/userManager/user/myuser" http://localhost:8080/system/userManager/group/mygroup.update.html
## Delete group
@@ -245,25 +237,25 @@ Example
To delete an existing group POST a request to `/system/userManager/group/groupname.delete.<html or json>`. The following parameters are available:
Parameter Name | Required | Description
---- | --- | ---
-`:applyTo` | no | An array of relative resource references to groups to be deleted. If this parameter is present, the name of the group from the URL is ignored and all listed groups are removed.
-
+--- | --- | ---
+`:applyTo` | no | An array of relative resource references to groups to be deleted. If this parameter is present, the name of the group from the URL is ignored and all listed groups are removed.
+
Responses:
Status Code | Description
--- | ---
200 | Success, sent with no body.
404 | Group(s) was/were not found.
-500 | Any other failure. HTML (or JSON) explains failure.
-
+500 | Any other failure. HTML (or JSON) explains failure.
+
Example
- curl -Fgo=1 http://localhost:8080/system/userManager/group/mygroup.delete.html
+curl -Fgo=1 http://localhost:8080/system/userManager/group/mygroup.delete.html
## Automated Tests
-The [launchpad/testing](http://svn.apache.org/repos/asf/sling/trunk/launchpad/testing/src/test/java/org/apache/sling/launchpad/webapp/integrationtest/accessManager/) module contains test classes for various operations of the `jackrabbit-usermanager`. Such tests run as part of our continuous integration process, to demonstrate and verify the behavior of the various operations, in a way that's guaranteed to be in sync with the actual Sling core code. If you have an idea for additional tests, make sure to let us know\!
+The [launchpad/testing](http://svn.apache.org/repos/asf/sling/trunk/launchpad/testing/src/test/java/org/apache/sling/launchpad/webapp/integrationtest/accessManager/) module contains test classes for various operations of the `jackrabbit-usermanager`. Such tests run as part of our continuous integration process, to demonstrate and verify the behavior of the various operations, in a way that's guaranteed to be in sync with the actual Sling core code. If you have an idea for additional tests, make sure to let us know!
## Permissions checking from scripts
@@ -286,30 +278,30 @@ The AuthorizablePrivilegesInfo provides methods for checking the following actio
Example:
- <%
- // lookup the service
- var privilegesInfo = sling.getService(Packages.org.apache.sling.jackrabbit.usermanager.AuthorizablePrivilegesInfo);
-
- if (privilegesInfo.canAddUser(currentSession)) {
- //TODO: render the UI that allows the user to add a user here
- }
-
- if (privilegesInfo.canAddGroup(currentSession)) {
- //TODO: render the UI that allows the user to add a group here
- }
-
- if (privilegesInfo.canUpdateProperties(currentSession, "someUserId")) {
- //TODO: render the UI that allows the user to update the properties of the user here
- }
-
- if (privilegesInfo.canRemove(currentSession, "someUserId")) {
- //TODO: render the UI that allows the user to remove the user here
- }
-
- if (privilegesInfo.canUpdateGroupMembers(currentSession, "GroupName")) {
- //TODO: draw your UI that allows the user to update the group memebership here
- }
- %>
+<%
+// lookup the service
+var privilegesInfo = sling.getService(Packages.org.apache.sling.jackrabbit.usermanager.AuthorizablePrivilegesInfo);
+
+if (privilegesInfo.canAddUser(currentSession)) {
+//TODO: render the UI that allows the user to add a user here
+}
+
+if (privilegesInfo.canAddGroup(currentSession)) {
+//TODO: render the UI that allows the user to add a group here
+}
+
+if (privilegesInfo.canUpdateProperties(currentSession, "someUserId")) {
+//TODO: render the UI that allows the user to update the properties of the user here
+}
+
+if (privilegesInfo.canRemove(currentSession, "someUserId")) {
+//TODO: render the UI that allows the user to remove the user here
+}
+
+if (privilegesInfo.canUpdateGroupMembers(currentSession, "GroupName")) {
+//TODO: draw your UI that allows the user to update the group memebership here
+}
+%>
http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.md
----------------------------------------------------------------------
diff --git a/content/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.md b/content/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.md
index 824930d..dfc84c6 100644
--- a/content/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.md
+++ b/content/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.md
@@ -1,10 +1,7 @@
-title=TODO title for manipulating-content-the-slingpostservlet-servlets-post.md
-date=1900-01-01
-type=post
-tags=blog
+title=Manipulating Content - The SlingPostServlet (servlets.post)
+type=page
status=published
~~~~~~
-Title: Manipulating Content - The SlingPostServlet (servlets.post)
[TOC]
@@ -24,10 +21,10 @@ To create content you simply send an HTTP POST request using the path of the nod
- <form method="POST" action="http://host/some/new/content" enctype="multipart/form-data">
- <input type="text" name="title" value="" />
- <input type="text" name="text" value="" />
- </form>
+<form method="POST" action="http://host/some/new/content" enctype="multipart/form-data">
+<input type="text" name="title" value="" />
+<input type="text" name="text" value="" />
+</form>
@@ -36,22 +33,22 @@ This simple form will set the `title` and `text` properties on a node at `/some/
Similarly, you can do this using the `curl` command line tool:
- $ curl -Ftitle="some title text" -Ftext="some body text content" http://host/some/new/content
+$ curl -Ftitle="some title text" -Ftext="some body text content" http://host/some/new/content
You might want to use a specific JCR node type for a newly created node. This is possible by simply setting a `jcr:primaryType` property on the request, e.g.
- $ curl -F"jcr:primaryType=nt:unstructured" -Ftitle="some title text" \
- -Ftext="some body text content" http://host/some/new/content
+$ curl -F"jcr:primaryType=nt:unstructured" -Ftitle="some title text"
+-Ftext="some body text content" http://host/some/new/content
Similarly, you may assign JCR mixin node types using the `jcr:mixinTypes` property and a Sling resource type using the `sling:resourceType` property. For example:
- $ curl -F"sling:resourceType=sling:sample" -Ftitle="some title text" \
- -Ftext="some body text content" http://host/some/new/content
+$ curl -F"sling:resourceType=sling:sample" -Ftitle="some title text"
+-Ftext="some body text content" http://host/some/new/content
@@ -68,14 +65,14 @@ This support requires Sling Engine 2.1.0 and the Sling Default Post Servlet 2.0.
The SlingPostServlet is actually just a front-end to the actual operations. To select the actual operation to execute, the `:operation` request parameter is used. Out of the box, the SlingPostServlet supports the following operations:
- * property not set or empty -- Create new content or modify existing content
- * `delete` -- Remove existing content
- * `move` -- Move existing content to a new location
- * `copy` -- Copy existing content to a new location
- * `import` -- Import content structures from JSON/XML/Zip
- * `nop` -- Explicitly requests to do nothing and just sets the response status
- * `checkin` - Check in a versionable node
- * `checkout` - Check out a versionable node
+* property not set or empty -- Create new content or modify existing content
+* `delete` -- Remove existing content
+* `move` -- Move existing content to a new location
+* `copy` -- Copy existing content to a new location
+* `import` -- Import content structures from JSON/XML/Zip
+* `nop` -- Explicitly requests to do nothing and just sets the response status
+* `checkin` - Check in a versionable node
+* `checkout` - Check out a versionable node
All these operations always operate on the resource of the request as returned by `SlingHttpServletRequest.getResource()`. Some operations require additional parameters to be set to operate completely.
@@ -89,7 +86,7 @@ Note that the `launchpad/testing` module contains a number of <a href="http://sv
<div class="note">
<b>Trailing star in the :applyTo parameter</b>:
-This applies to operations that use this parameter, since version 2.1.2 of the *org.apache.sling.servlets.post* bundle: If the last segment of the `:applyTo` value is '*' then the operation applies to all the children of the resolved parent resource. This can be used to act on all the children
+This applies to operations that use this parameter, since version 2.1.2 of the *org.apache.sling.servlets.post* bundle: If the last segment of the `:applyTo` value is '*' then the operation applies to all the children of the resolved parent resource. This can be used to act on all the children
of a resource without having to specify the path of each individual child resource.
</div>
@@ -129,23 +126,23 @@ Setting property values is as simple as just adding a request parameter whose na
Here is another example show a simple HTML form to create a new node with an automatically created name:
- <form method="POST" action="/content/page/first" enctype="multipart/form-data">
- <input type="text" name="title" />
- <input type="text" name="text" />
- <input type="Submit" />
- </form>
+<form method="POST" action="/content/page/first" enctype="multipart/form-data">
+<input type="text" name="title" />
+<input type="text" name="text" />
+<input type="Submit" />
+</form>
+
-
If this form is submitted with *title* and *This is some Text* as values for the `title` and `text` fields respectively, a new node is created at the path `/content/page/first` and the `title` and `text` properties set to the respective field values. If a node at `/content/page/first` already existed before submitting the form, the `title` and `text` properties are just updated to the new values from the form fields.
-
+
If a parameter has multiple values, the respective property will be created as a multi-value property. So for example the command line:
-
- $ curl -Fmulti=one -Fmulti=two http://host/content/page
-
+
+$ curl -Fmulti=one -Fmulti=two http://host/content/page
+
Would assign the `/content/page/multi` property the value *[ "one", "two" ]*.
-
+
This is pretty much all there is to know about creating and modifying content. The following sections will now introduce more functionality which help you with more fine-grained control in your content management application.
-
+
##### Automatic property values: last modified and created by
To make it easier to set "last modified" and "created by" property
@@ -163,54 +160,54 @@ following property names _if they are supplied with empty values in such a reque
This is demonstrated by the [SlingAutoPropertiesTest](https://svn.apache.org/repos/asf/sling/trunk/launchpad/integration-tests/src/main/java/org/apache/sling/launchpad/webapp/integrationtest/servlets/post/SlingAutoPropertiesTest.java) which is part of our launchpad integration tests.
##### File Uploads
-
+
File uploads are typically done using the `<input type="file""/>` element of an HTML form and ensuring the correct form encoding. The SlingPostServlet handles uploaded files specially, in that the file data is not simply written into a property, but a node is actually created with three properties:
-
+
* `jcr:data` -- The actual file contents
* `jcr:lastModified` -- The time stamp of processing the uploaded file
* `jcr:mimeType` -- The MIME type from the original file submission (if contained in the file body part) or derived from the original file name
-
+
The name of the node is either taken from the parameter name or if the name is `*` from the name of the uploaded file.
-
+
The primary node type of the uploaded file is selected using the following algorithm:
-
+
* If a `@TypeHint suffixed parameter (see below for a description) is present check whether the value is a known non-mixin node type. If so, the node is created with this primary node type.
* If a `@TypeHint` suffixed parameter is not present or the value does not denote an existing non-mixin node type, the node will be created as an `nt:file` node if the parent node is of type `nt:folder`. Otherwise the node will be created with primary node type `nt:resource`.
-
+
If the node to be created is `nt:file`, the actual file data will really be stored in the `jcr:content` child node of the new `nt:file` node whose primary node type is then set as `nt:resource`.
-
+
Example 1: Upload an image to a node named `image` below `/content/page`:
-
- <form method="POST" action="/content/page" enctype="multipart/form-data">
- <input type="file" name="image" />
- <input type="Submit" />
- </form>
+
+<form method="POST" action="/content/page" enctype="multipart/form-data">
+<input type="file" name="image" />
+<input type="Submit" />
+</form>
Example 2: Upload a file as a node of type `nt:file` below `/content/folder`:
- <form method="POST" action="/content/page" enctype="multipart/form-data">
- <input type="file" name="*" />
- <input type="hidden" name="*@TypeHint" value="nt:file" />
- <input type="Submit" />
- </form>
+<form method="POST" action="/content/page" enctype="multipart/form-data">
+<input type="file" name="*" />
+<input type="hidden" name="*@TypeHint" value="nt:file" />
+<input type="Submit" />
+</form>
+
-
Assuming the user selected a file named `myImage.jpg` the uploaded file would be stored in an `nt:file` node at `/content/folder/myImage.jpg`.
-
-
+
+
##### Date properties
-
+
Parameters providing date/time values to be stored in JCR properties of type *Date* require special handling. The problem is that there are a number of formats to represent such date/time values. To account for this open-ended list of formats, the Sling Post Servlet supports configurability of the process of parsing strings into `Calendar` objects.
-
+
The Sling Post Servlet configuration property `servlet.post.dateFormats` takes a list of format strings which are used to setup `java.text.SimpleDateFormat` instances for parsing date/time string representations. A special format string `ISO8601` is supported to indicate the string to be parsed as a JCR standard string representation of a _Date_ property.
Only the latter supports storing the actual timezone offset. All the parsers leveraging `java.text.SimpleDateFormat` loose the given timezone and convert that just to the default timezone of the JRE (when creating the `Calendar` out of the `Date`, because `java.lang.Date` is not carrying any timezone information).
-
+
The default list of configured date/time parse pattern is:
-
+
* EEE MMM dd yyyy HH:mm:ss 'GMT'Z
* ISO8601, using the org.apache.jackrabbit.util.ISO8601 parser (±YYYY-MM-DDThh:mm:ss.SSSTZD)
* yyyy-MM-dd'T'HH:mm:ss.SSSZ
@@ -218,26 +215,26 @@ The default list of configured date/time parse pattern is:
* yyyy-MM-dd
* dd.MM.yyyy HH:mm:ss
* dd.MM.yyyy
-
+
Any date/time string parameter supplied is subject to the patterns in the configured order. The first pattern accepting the string and parsing it into a `Date` -- and thus a `Calendar` -- object is used. Therefore this list is best ordered in a most-stringent to least-stringent order.
-
-
-
+
+
+
##### Omitting Some Parameters
-
+
There may be times that you have forms which contain a lot of fields which you do not want to actually store in content. Such forms usually are created using some client-side GUI library which uses the fields for its own purposes. To be able to easily differentiate between real content to be actually stored and such control parameters, you may prefix the names of the fields destined for content with a dot-slash (`./`).
-
+
As soon as the SlingPostServlet encounters parameters prefixed with dot-slash, only those parameters are considered for content updates while all other parameters not prefixed are just ignored. In addition to dot-slash prefixed parameters, also parameters prefixed with dot-dot-slash (`../`) and slash (`/`) are considered in this situation.
-
+
For example, the following form only uses the first two fields for content update and ignores the rest:
-
- <form method="POST" action="/content/page/first" enctype="multipart/form-data">
- <input type="text" name="./title" />
- <input type="text" name="../first/text" />
- <input type="hidden" name="control0" /><!-- ignored -->
- <input type="hidden" name="control1" /><!-- ignored -->
- <input type="Submit" />
- </form>
+
+<form method="POST" action="/content/page/first" enctype="multipart/form-data">
+<input type="text" name="./title" />
+<input type="text" name="../first/text" />
+<input type="hidden" name="control0" /><!-- ignored -->
+<input type="hidden" name="control1" /><!-- ignored -->
+<input type="Submit" />
+</form>
Because the SlingPostServlet encounters the `./title` parameter, only parameters prefixed with dot-slash, dot-dot-slash and slash are considered for content update. In this case this would `./title` and `../first/text` while `control0` and `control1` are not prefixed and thus ignored.
@@ -271,40 +268,40 @@ If the `@TypeHint` value ends with `[]`, it indicates a multi-value property. A
Example: The following form sets the numeric `width`, the boolean `checked`, and the multi-valued `hobbys` (with 3 values to enter) properties:
- <form method="POST" action="/content/page/first" enctype="multipart/form-data">
- <input type="text" name="width" />
- <input type="hidden" name="width@TypeHint" value="Long" />
- <input type="checkbox" name="checked" />
- <input type="hidden" name="checked@TypeHint" value="Boolean" />
- <input type="text" name="hobbys"/>
- <input type="text" name="hobbys"/>
- <input type="text" name="hobbys"/>
- <input type="hidden" name="hobbys@TypeHint" value="String[]" />
- <input type="Submit" />
- </form>
-
-
+<form method="POST" action="/content/page/first" enctype="multipart/form-data">
+<input type="text" name="width" />
+<input type="hidden" name="width@TypeHint" value="Long" />
+<input type="checkbox" name="checked" />
+<input type="hidden" name="checked@TypeHint" value="Boolean" />
+<input type="text" name="hobbys"/>
+<input type="text" name="hobbys"/>
+<input type="text" name="hobbys"/>
+<input type="hidden" name="hobbys@TypeHint" value="String[]" />
+<input type="Submit" />
+</form>
+
+
In real applications you would need some JavaScript that allows to add/remove values, ie. add/remove inputs with the name "hobbys". Or a pure JavaScript based form post would be used, that gathers the properties to update programmatically, but the additional parameter `hobbys@TypeHint=String[]` would be the same.
-
+
The `@TypeHint` suffixed parameter is assumed to be single-valued. If the parameter has multiple values, only the first is actually used.
For multi-value properties, see also the `@Patch` option.
-
+
For more information on applying `@TypeHint` to a file upload parameter see the section on File Uploads above.
-
-
+
+
###### `@DefaultValue`
-
-
+
+
The `@DefaultValue` suffixed parameter may be provided to set a property to a default value should no value be provided in the actual parameters. Same as for normal parameters, the `@DefaultValue` parameter may have multiple values to create multi-valued properties.
-
+
Example: Set the `text` property to a default value if the user does not provide one:
-
- <form method="POST" action="/content/page/first" enctype="multipart/form-data">
- <input type="text" name="text" />
- <input type="hidden" name="text@DefaultValue" value="--- Default Value ---" />
- <input type="Submit" />
- </form>
+
+<form method="POST" action="/content/page/first" enctype="multipart/form-data">
+<input type="text" name="text" />
+<input type="hidden" name="text@DefaultValue" value="--- Default Value ---" />
+<input type="Submit" />
+</form>
@@ -312,43 +309,43 @@ Example: Set the `text` property to a default value if the user does not provide
As described above, `@DefaultValue` only takes effect if no value is provided for a particular parameter. However, in some cases, such as HTML checkboxes, this isn't sufficient because the parameter isn't submitted at all. To handle this scenario, you can use the `@UseDefaultWhenMissing` suffixed parameter.
- <form method="POST" action="/content/page/first" enctype="multipart/form-data">
- <input name="queryIgnoreNoise" class="input" type="checkbox" value="true"/>
- <input type="hidden" name="queryIgnoreNoise@DefaultValue" value="false"/>
- <input type="hidden" name="queryIgnoreNoise@UseDefaultWhenMissing" value="true"/>
- </form>
+<form method="POST" action="/content/page/first" enctype="multipart/form-data">
+<input name="queryIgnoreNoise" class="input" type="checkbox" value="true"/>
+<input type="hidden" name="queryIgnoreNoise@DefaultValue" value="false"/>
+<input type="hidden" name="queryIgnoreNoise@UseDefaultWhenMissing" value="true"/>
+</form>
+
+
-
-
###### `@IgnoreBlanks`
-
+
Sometimes a form client will supply empty parameter values resulting in content being created or modified. For example submitting this form:
-
- <form method="POST" action="/content/page/first" enctype="multipart/form-data">
- <input type="hidden" name="stringProperty@TypeHint" value="String[]"/>
- <input type="text" name="stringProperty" value="foo"/>
- <input type="text" name="stringProperty" value="bar"/>
- <input type="text" name="stringProperty" value=""/>
- </form>
+
+<form method="POST" action="/content/page/first" enctype="multipart/form-data">
+<input type="hidden" name="stringProperty@TypeHint" value="String[]"/>
+<input type="text" name="stringProperty" value="foo"/>
+<input type="text" name="stringProperty" value="bar"/>
+<input type="text" name="stringProperty" value=""/>
+</form>
will result in multi-value String property being set to [ "foo", "bar", "" ]. Notice the blank value.
Likewise submitting this form without a value entered:
- <form method="POST" action="/content/page/first" enctype="multipart/form-data">
- <input type="hidden" name="stringProperty@TypeHint" value="String"/>
- <input type="text" name="stringProperty" value=""/>
- </form>
+<form method="POST" action="/content/page/first" enctype="multipart/form-data">
+<input type="hidden" name="stringProperty@TypeHint" value="String"/>
+<input type="text" name="stringProperty" value=""/>
+</form>
+
-
will result in the single-value String property being set to an empty string.
-
+
To overcome this situation the `@IgnoreBlanks` suffix may be used to consider parameters with an empty string value to be ignored during processing. That is such parameter values would be treated as if they would not be supplied.
-
+
Adding
-
- <input type="hidden" name="stringProperty@IgnoreBlanks" value="true"/>
+
+<input type="hidden" name="stringProperty@IgnoreBlanks" value="true"/>
to the above forms will cause the multi-value property be set to the two-element value [ "foo", "bar" ] and to not modify the property at all in the second single-value example.
@@ -359,35 +356,35 @@ In some situations, an HTML form with parameters may be reused to update content
Example: To set the property `text` from a form element `supplied_text`, you might use the following form:
- <form method="POST" action="/content/page/first" enctype="multipart/form-data">
- <input type="text" name="supplied_text" />
- <input type="hidden" name="./text@ValueFrom" value="supplied_text" />
- <input type="Submit" />
- </form>
+<form method="POST" action="/content/page/first" enctype="multipart/form-data">
+<input type="text" name="supplied_text" />
+<input type="hidden" name="./text@ValueFrom" value="supplied_text" />
+<input type="Submit" />
+</form>
+
-
To prevent storing the additional parameters in the repository you might want to use the prefixing mechanism as shown in the example above, where the `@ValueFrom` parameter is prefixed and thus the `supplied_text` parameter is not used for property setting.
-
+
The `@ValueFrom` suffixed parameter is assumed to be single-valued. If the parameter has multiple values it is ignored completely.
-
+
The `@ValueFrom` suffixed parameter is also special in that there must not be a correlated parameter without a suffix. Thus have parameters `text` and `text@ValueFrom` may have unexpected results.
-
-
+
+
###### `@Delete`
-
+
Sometimes it may be required to not set a property to a specific value but to just remove it while processing the content update request. One such situation is a property filled from one or more checkboxes in an HTML form. If none of the checkboxes are checked, no parameter is actually submitted for these checkboxes. Hence the SlingPostServlet will not touch this property and effectively leave it untouched, while the natural reaction would have been to remove the property.
-
+
Here comes the `@Delete` suffixed parameter. This simply causes the indicated property be removed if it exists. If the property does not exist, nothing more happens. The actual value of the `@Delete` suffixed parameter does not care as long as the parameter is submitted.
-
+
Example: To ensure the `color` property is actually removed if no color has been selected, you might use the following form:
-
- <form method="POST" action="/content/page/first" enctype="multipart/form-data">
- <input type="checkbox" name="color" value="red" />
- <input type="checkbox" name="color" value="green" />
- <input type="checkbox" name="color" value="blue" />
- <input type="hidden" name="color@Delete" value="delete text" /><!-- actual value is ignored -->
- <input type="Submit" />
- </form>
+
+<form method="POST" action="/content/page/first" enctype="multipart/form-data">
+<input type="checkbox" name="color" value="red" />
+<input type="checkbox" name="color" value="green" />
+<input type="checkbox" name="color" value="blue" />
+<input type="hidden" name="color@Delete" value="delete text" /><!-- actual value is ignored -->
+<input type="Submit" />
+</form>
The `@Delete` suffixed parameter is also special in that there need not be a correlated parameter without a suffix. If both -- a parameters `text` and `text@Delete` are set, the `text` property is first deleted and then filled with the new content.
@@ -404,37 +401,37 @@ To support this kind of functionality, the `@MoveFrom` suffixed parameter may be
Example: Your Flash-based file upload stored the file on the server at `/tmp/upload/123`. You now want to store this file along with a title and a text in a newly created node. The following form will be your friend:
- <!-- trailing slash generates a name for the new node -->
- <form method="POST" action="/content/page/" enctype="multipart/form-data">
- <input type="hidden" name="image@MoveFrom" value="/tmp/upload/123" />
- <input type="text" name="title" />
- <input type="text" name="text" />
- <input type="Submit" />
- </form>
+<!-- trailing slash generates a name for the new node -->
+<form method="POST" action="/content/page/" enctype="multipart/form-data">
+<input type="hidden" name="image@MoveFrom" value="/tmp/upload/123" />
+<input type="text" name="title" />
+<input type="text" name="text" />
+<input type="Submit" />
+</form>
+
-
If there exists no repository item at the indicated path, nothing is done. If the item indicated by the `@MoveFrom` suffixed parameter already exists, it is replaced by the item addressed by the parameter value -- unless of course there is no item at the named location.
-
+
The `@MoveFrom` suffixed parameter is assumed to be single-valued. If the parameter has multiple values it is ignored completely.
-
+
The `@MoveFrom` suffixed parameter is also special in that there must not be a correlated parameter without a suffix. Thus have parameters `text` and `text@MoveFrom` may have unexpected results.
-
+
The `@MoveFrom` suffixed parameter in fact calls for a sub-operation, which is executed after the `@Delete` sub operation but before any other tasks of content creation and modification are done.
-
-
+
+
###### `@CopyFrom`
-
+
Similar to the `@MoveFrom` suffix exists a `@CopyFrom` suffix. The latter works exactly the same as the former except that the item addressed by the parameter value is not moved but just copied.
-
+
Example: Your Flash-based file upload stored the file on the server at `/tmp/upload/123`. You now want to store this file along with a title and a text in a newly created node. The following form may be your friend:
-
- <!-- trailing slash generates a name for the new node -->
- <form method="POST" action="/content/page/" enctype="multipart/form-data">
- <input type="hidden" name="image@CopyFrom" value="/tmp/upload/123" />
- <input type="text" name="title" />
- <input type="text" name="text" />
- <input type="Submit" />
- </form>
+
+<!-- trailing slash generates a name for the new node -->
+<form method="POST" action="/content/page/" enctype="multipart/form-data">
+<input type="hidden" name="image@CopyFrom" value="/tmp/upload/123" />
+<input type="text" name="title" />
+<input type="text" name="text" />
+<input type="Submit" />
+</form>
If there exists no repository item at the indicated path, nothing is done. If the item indicated by the `@CopyFrom` suffixed parameter already exists, it is replaced by the item addressed by the parameter value -- unless of course there is no item at the named location.
@@ -446,19 +443,19 @@ The `@CopyFrom` suffixed parameter is also special in that there must not be a c
The `@CopyFrom` suffixed parameter in fact calls for a sub-operation, which is executed after the `@MoveFrom` sub operation but before any other tasks of content creation and modification are done.
###### `@Patch`
-
+
When modifying multi-value properties, the `@Patch` suffix can be used to just add `+` or remove `-` individual values without overwriting the full array. This allows to change the array without knowing the current values.
For example, imagine a multi-value string property that stores tags or keywords. To both add a tag "cool" and remove "boring" from the list:
- <form method="POST" action="/content/page/first" enctype="multipart/form-data">
- <input type="hidden" name="tags@TypeHint" value="String[]" />
- <input type="hidden" name="tags@Patch" value="true" />
- <input type="text" name="tags" value="+cool"/>
- <input type="text" name="tags" value="-boring"/>
- <input type="Submit" />
- </form>
-
+<form method="POST" action="/content/page/first" enctype="multipart/form-data">
+<input type="hidden" name="tags@TypeHint" value="String[]" />
+<input type="hidden" name="tags@Patch" value="true" />
+<input type="text" name="tags" value="+cool"/>
+<input type="text" name="tags" value="-boring"/>
+<input type="Submit" />
+</form>
+
The array will be treated like a set: when adding a value, it will only be added once if it does not exist yet; when removing a value, all occurrences of it will be removed. For values not affected by the add or remove operations, nothing changes. An existing array with duplicate entries will not automatically be converted into a set.
The format for an individual parameter value is `<operation><value>`. If there is no or no valid operation given, this value will be ignored.
@@ -512,7 +509,7 @@ The modification operation has the following status responses:
To remove existing content just address the item to be removed and set the `:operation` parameter to `delete`. For example the following command line removes the `/content/sample` page:
- $ curl -F":operation=delete" http://host/content/sample
+$ curl -F":operation=delete" http://host/content/sample
@@ -537,14 +534,14 @@ When specifying the item(s) to be removed with the `:applyTo` parameter, the req
To remove the `/content/page1` and `/content/page2` nodes, for example, you might use the following command line:
- $ curl -F":operation=delete" -F":applyTo=/content/page1" \
- -F":applyTo=/content/page2" http://host/content/sample
+$ curl -F":operation=delete" -F":applyTo=/content/page1"
+-F":applyTo=/content/page2" http://host/content/sample
Using a trailing star in the :applyTo parameter (as mentioned before), you can remove all the children of the `/content` node, for example, as follows:
- $ curl -F":operation=delete" -F":applyTo=/content/*" http://host/content/sample
+$ curl -F":operation=delete" -F":applyTo=/content/*" http://host/content/sample
If any resource listed in the `:applyTo` parameter does not exist, it is silently ignored.
@@ -602,8 +599,8 @@ When specifying the item(s) to be copied with the `:applyTo` parameter, the requ
To copy the `/content/page1` and `/content/page2` nodes to `/content/target`, for example, use:
- $ curl -F":operation=copy" -F":applyTo=/content/page1" -F":applyTo=/content/page2" \
- -F":dest=/content/target/" http://host/content/sample
+$ curl -F":operation=copy" -F":applyTo=/content/page1" -F":applyTo=/content/page2"
+-F":dest=/content/target/" http://host/content/sample
Please note the trailing slash character (`/`) in the value of the `:dest` parameter. This is required for multi-item copy operations using the `:applyTo` parameter. The copied items are created below the node indicated by the `:dest`.
@@ -611,8 +608,8 @@ Please note the trailing slash character (`/`) in the value of the `:dest` param
Using a trailing star in the :applyTo parameter (as mentioned before), you can copy all the children of the `/content` node, for example, as follows:
- $ curl -F":operation=copy" -F":applyTo=/content/*" -F":dest=/content/target/" \
- http://host/content/sample
+$ curl -F":operation=copy" -F":applyTo=/content/*" -F":dest=/content/target/"
+http://host/content/sample
If any resource listed in the `:applyTo` parameter does not exist, it is silently ignored. Any item already existing at the copy destination whose name is the same as the name of an item to be copied is silently overwritten with the source item.
@@ -673,8 +670,8 @@ When specifying the item(s) to be moved with the `:applyTo` parameter, the reque
To for example move the `/content/page1` and `/content/page2` nodes to `/content/target`, you might use the following command line:
- $ curl -F":operation=move" -F":applyTo=/content/page1" -F":applyTo=/content/page2" \
- -F":dest=/content/target/" http://host/content/sample
+$ curl -F":operation=move" -F":applyTo=/content/page1" -F":applyTo=/content/page2"
+-F":dest=/content/target/" http://host/content/sample
Please note the trailing slash character (`/`) in the value of the `:dest` parameter. This is required for multi-item move operations using the `:applyTo` parameter. The moved items are created below the node indicated by the `:dest`.
@@ -682,8 +679,8 @@ Please note the trailing slash character (`/`) in the value of the `:dest` param
Using a trailing star in the :applyTo parameter (as mentioned before), you can move all the children of the `/content` node, for example, as follows:
- $ curl -F":operation=move" -F":applyTo=/content/*" -F":dest=/content/target/" \
- http://host/content/sample
+$ curl -F":operation=move" -F":applyTo=/content/*" -F":dest=/content/target/"
+http://host/content/sample
If any resource listed in the `:applyTo` parameter does not exist, it is silently ignored. Any item already existing at the move destination whose name is the same as the name of an item to be moved is silently overwritten with the source item.
@@ -703,7 +700,7 @@ The move operation applied to multiple resources has the following status respon
### Importing Content Structures
-To import content structures just address the parent item to import into and set the `:operation` parameter to `import`.
+To import content structures just address the parent item to import into and set the `:operation` parameter to `import`.
The optional name of the root node of the imported content may optionally be supplied using the [Algorithm for Node Name Creation](#algorithm-for-node-name-creation).
@@ -723,41 +720,41 @@ Other parameters for the import operation:
For example the following command line imports the `/content/sample` page:
- $ curl -F":operation=import" -F":contentType=json" -F":name=sample" \
- -F':content={ "jcr:primaryType": "nt:unstructured", "propOne" : "propOneValue", "childOne" : { "childPropOne" : true } }' \
- http://host/content
+$ curl -F":operation=import" -F":contentType=json" -F":name=sample"
+-F':content={ "jcr:primaryType": "nt:unstructured", "propOne" : "propOneValue", "childOne" : { "childPropOne" : true } }'
+http://host/content
For example the following command line imports the `/content/sample` page without the optional name parameter:
- $ curl -F":operation=import" -F":contentType=json"
- -F':content={ "sample" : {"propOne" : "propOneValue", "childOne" : { "childPropOne" : true } } }' \
- http://host/content
+$ curl -F":operation=import" -F":contentType=json"
+-F':content={ "sample" : {"propOne" : "propOneValue", "childOne" : { "childPropOne" : true } } }'
+http://host/content
For example the following form imports the `/content/sample` page:
- <form method="POST" action="/content" enctype="multipart/form-data">
- <input type="hidden" name=":operation" value="import" />
- <input type="hidden" name=":contentType" value="json" />
- <input type="hidden" name=":nameHint" value="sample" />
-
- <input type="text" name=":content" value="{ "jcr:primaryType" : "nt:unstructured" , "propOne" : "propOneValue", "childOne" : { "childPropOne" : true } }" />
- <input type="Submit" />
- </form>
+<form method="POST" action="/content" enctype="multipart/form-data">
+<input type="hidden" name=":operation" value="import" />
+<input type="hidden" name=":contentType" value="json" />
+<input type="hidden" name=":nameHint" value="sample" />
+
+<input type="text" name=":content" value="{ "jcr:primaryType" : "nt:unstructured" , "propOne" : "propOneValue", "childOne" : { "childPropOne" : true } }" />
+<input type="Submit" />
+</form>
+
-
For example the following form imports content from a file upload:
- <form method="POST" action="/content" enctype="multipart/form-data">
- <input type="hidden" name=":operation" value="import" />
- <input type="hidden" name=":contentType" value="json" />
- <input type="hidden" name=":nameHint" value="sample" />
-
- <input type="file" name=":contentFile" />
- <input type="Submit" />
- </form>
+<form method="POST" action="/content" enctype="multipart/form-data">
+<input type="hidden" name=":operation" value="import" />
+<input type="hidden" name=":contentType" value="json" />
+<input type="hidden" name=":nameHint" value="sample" />
+
+<input type="file" name=":contentFile" />
+<input type="Submit" />
+</form>
@@ -818,7 +815,7 @@ The `:order` parameter may have the following values:
Note that simple content reordering can be requested without applying any other operations. This is easiest done by placing a request to the resource to be reordered and just setting the `:order` parameter. For example to order the `/content/sample/page5` resource above its sibling resource `/content/sample/other` a simple request
- $ curl -F":order=before other" http://host/content/sample/page5
+$ curl -F":order=before other" http://host/content/sample/page5
does the trick. To be redirected after the reodering, the `:redirect` parameter may optionally also be specified.
http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/bundles/metrics.md
----------------------------------------------------------------------
diff --git a/content/documentation/bundles/metrics.md b/content/documentation/bundles/metrics.md
index 3669732..65e6c47 100644
--- a/content/documentation/bundles/metrics.md
+++ b/content/documentation/bundles/metrics.md
@@ -1,47 +1,44 @@
-title=TODO title for metrics.md
-date=1900-01-01
-type=post
-tags=blog
+title=Sling Metrics
+type=page
status=published
~~~~~~
-Title: Sling Metrics
Sling Metrics bundle provides integration with [Dropwizard Metrics][1] library
-which provides a toolkit to capture runtime performance statistics in your
-application.
+which provides a toolkit to capture runtime performance statistics in your
+application.
## Features
* Registers a [MetricsService][3] which can be used to create various types of Metric
- instances
+instances
* WebConsole Plugin which provides a HTML Reporter for the various Metric instances
* Inventory Plugin which dumps the Metric state in plain text format
## Basic Usage
- :::java
- import org.apache.sling.metrics.Counter;
- import org.apache.sling.metrics.MetricsService;
-
- @Reference
- private MetricsService metricsService;
-
- private Counter counter;
-
- @Activate
- private void activate(){
- counter = metricsService.counter("sessionCounter");
- }
-
- public void onSessionCreation(){
- counter.increment();
- }
-
+:::java
+import org.apache.sling.metrics.Counter;
+import org.apache.sling.metrics.MetricsService;
+
+@Reference
+private MetricsService metricsService;
+
+private Counter counter;
+
+@Activate
+private void activate(){
+counter = metricsService.counter("sessionCounter");
+}
+
+public void onSessionCreation(){
+counter.increment();
+}
+
To make use of `MetricsService`
1. Get a reference to `org.apache.sling.metrics.MetricsService`
-2. Initialize the metric e.g. Counter in above case. This avoids
- any potential lookup cost in critical code paths
+2. Initialize the metric e.g. Counter in above case. This avoids
+any potential lookup cost in critical code paths
3. Make use of metric instance to capture require stats
Refer to [Metric Getting Started][2] guide to see how various types
@@ -51,16 +48,16 @@ bundle class names belong to `org.apache.sling.commons.metrics` package
## Best Practices
1. Use descriptive names - Qualify the name with class/package name where the
- metric is being used
-2. Do not use the metrics for operation which take less than 1E-7s i.e. 1000 nano
- seconds otherwise timer overhead (Metrics makes use of System.nanoTime)
- would start affecting the performance.
+metric is being used
+2. Do not use the metrics for operation which take less than 1E-7s i.e. 1000 nano
+seconds otherwise timer overhead (Metrics makes use of System.nanoTime)
+would start affecting the performance.
## API
-Sling Metrics bundle provides its own Metric classes which are modelled on
+Sling Metrics bundle provides its own Metric classes which are modelled on
[Dropwizard Metrics][1] library. The metric interfaces defined by Sling bundle
-only provides methods related to data collection.
+only provides methods related to data collection.
* [org.apache.sling.commons.metrics.Meter][4] - Similar to [Dropwizard Meter][dw-meter]
* [org.apache.sling.commons.metrics.Timer][6] - Similar to [Dropwizard Timer][dw-timer]
@@ -73,59 +70,59 @@ type of Metrics like Meter, Timer, Counter and Histogram.
### Requirement of wrapper interfaces
* Abstraction - Provides an abstraction around how metrics are collected and how
- they are reported and consumed. Most of the code would only be concerned with
- collecting interesting data. How it gets consumed or reported is implementation
- detail.
+they are reported and consumed. Most of the code would only be concerned with
+collecting interesting data. How it gets consumed or reported is implementation
+detail.
* Ability to turnoff stats collection - We can easily turn off data collection
- by switching to NOOP variant of `MetricsService` in case it starts adding appreciable
- overhead. Turning on and off can also be done on individual metric basis.
-
+by switching to NOOP variant of `MetricsService` in case it starts adding appreciable
+overhead. Turning on and off can also be done on individual metric basis.
+
It also allows us to later extend the type of data collected. For e.g. we can also collect
[TimerSeries][8] type of data for each metric without modifying the caller logic.
-
+
### Access to Dropwizard Metrics API
-Sling Metrics bundle also registers the `MetricRegistry` instance with OSGi service registry.
-The instance registered has a service property `name` set to `sling` (so as allow distinguishing
-from any other registered `MetricRegistry` instance). It can be used to get direct access to Dropwizard
+Sling Metrics bundle also registers the `MetricRegistry` instance with OSGi service registry.
+The instance registered has a service property `name` set to `sling` (so as allow distinguishing
+from any other registered `MetricRegistry` instance). It can be used to get direct access to Dropwizard
Metric API if required.
- :::java
- @Reference(target = "(name=sling)")
- private MetricRegistry registry;
-
+:::java
+@Reference(target = "(name=sling)")
+private MetricRegistry registry;
+
Also the wrapper Metric instance can be converted to actual instance via `adaptTo` calls.
- :::java
- import org.apache.sling.commons.metrics.Counter
+:::java
+import org.apache.sling.commons.metrics.Counter
- Counter counter = metricService.counter("login");
- com.codahale.metrics.Counter = counter.adaptTo(com.codahale.metrics.Counter.class)
+Counter counter = metricService.counter("login");
+com.codahale.metrics.Counter = counter.adaptTo(com.codahale.metrics.Counter.class)
## WebConsole Plugin
-A Web Console plugin is also provided which is accessible at
+A Web Console plugin is also provided which is accessible at
http://localhost:8080/system/console/slingmetrics. It lists down all registered
-Metric instances and their state.
+Metric instances and their state.
-The plugin lists all Metric instances from any `MetricRegistry` instance found in
+The plugin lists all Metric instances from any `MetricRegistry` instance found in
the OSGi service registry. If the `MetricRegistry` service has a `name` property defined
-then that would be prefixed to the Metric names from that registry. This allows
+then that would be prefixed to the Metric names from that registry. This allows
use of same name in different registry instances.
## Installation
Add following Maven dependency to your pom.xml:
- :::xml
- <dependency>
- <groupId>org.apache.sling</groupId>
- <artifactId>org.apache.sling.commons.metrics</artifactId>
- <version>1.0.0</version>
- </dependency>
-
+:::xml
+<dependency>
+<groupId>org.apache.sling</groupId>
+<artifactId>org.apache.sling.commons.metrics</artifactId>
+<version>1.0.0</version>
+</dependency>
+
Or download from [here][9]
[1]: http://metrics.dropwizard.io/
http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/bundles/mime-type-support-commons-mime.md
----------------------------------------------------------------------
diff --git a/content/documentation/bundles/mime-type-support-commons-mime.md b/content/documentation/bundles/mime-type-support-commons-mime.md
index 940f202..11dcdaa 100644
--- a/content/documentation/bundles/mime-type-support-commons-mime.md
+++ b/content/documentation/bundles/mime-type-support-commons-mime.md
@@ -1,10 +1,7 @@
-title=TODO title for mime-type-support-commons-mime.md
-date=1900-01-01
-type=post
-tags=blog
+title=MIME Type Support (commons.mime and commons.contentdetection)
+type=page
status=published
~~~~~~
-Title: MIME Type Support (commons.mime and commons.contentdetection)
Support for MIME type mappings is generally a problematic issue. On the one hand applications have to take care to stay up to date with their mappings on the other hands in web applications it is tedious to maintain the mappings. Apache Sling takes a very user and deployment friendly approadch to this problem which is described in detail on this page.
@@ -35,7 +32,7 @@ Two more methods allow to programmatically add MIME type mappings:
## The Sling ContentAwareMimeTypeService
-For content-based mime type detection (as opposed to filename-based detection), the `org.apache.sling.commons.contentdetection` bundle
+For content-based mime type detection (as opposed to filename-based detection), the `org.apache.sling.commons.contentdetection` bundle
provides the `ContentAwareMimeTypeService`, which takes an `InputStream` that's analyzed to detect its mime type, using Apache Tika
by default:
@@ -75,7 +72,7 @@ The file format for MIME type mapping files is rather simple:
* The files are assumed to be encoded with the *ISO-8859-1* (aka Latin 1) character encoding
* The files consist of lines defining mappings where each line is terminated with either or both of a carriage return (CR, 0x0c) and line feed character (LF, 0x0a). There is no line continuation support *-la shell scripts or Java properties files.
* Empty lines and lines starting with a hash sign (`#`) are ignored
-* Data lines consist of space (any whitespace matching the `\s` regular expression) separated values. The first value is the MIME type name and the remaining values defining mappings to file name extensions. The first listed file name extension is considered the *default mapping* and is returned by the `MimeTypeService.getExtension(String)` method. Entry lines consisting of just a mime type but no extensions are also (currently) ignored.
+* Data lines consist of space (any whitespace matching the `s` regular expression) separated values. The first value is the MIME type name and the remaining values defining mappings to file name extensions. The first listed file name extension is considered the *default mapping* and is returned by the `MimeTypeService.getExtension(String)` method. Entry lines consisting of just a mime type but no extensions are also (currently) ignored.
THe data line format described here also applies to configuration provided by the values of the `mime.types` property of the MIME type service configuration. The file format description applies to all `META-INF/mime.types` files provided by the bundles as well as input streams supplied to the `MimeTypeService.registerMimeType(InputStream)` method.
http://git-wip-us.apache.org/repos/asf/sling-site/blob/88e80480/content/documentation/bundles/models.md
----------------------------------------------------------------------
diff --git a/content/documentation/bundles/models.md b/content/documentation/bundles/models.md
index a5a3060..21669bf 100644
--- a/content/documentation/bundles/models.md
+++ b/content/documentation/bundles/models.md
@@ -1,10 +1,7 @@
-title=TODO title for models.md
-date=1900-01-01
-type=post
-tags=blog
+title=Sling Models
+type=page
status=published
~~~~~~
-Title: Sling Models
[TOC]
@@ -24,53 +21,53 @@ Many Sling projects want to be able to create model objects - POJOs which are au
# Basic Usage
In the simplest case, the class is annotated with `@Model` and the adaptable class. Fields which need to be injected are annotated with `@Inject`:
- ::java
- @Model(adaptables=Resource.class)
- public class MyModel {
-
- @Inject
- private String propertyName;
- }
+::java
+@Model(adaptables=Resource.class)
+public class MyModel {
+
+@Inject
+private String propertyName;
+}
In this case, a property named "propertyName" will be looked up from the Resource (after first adapting it to a `ValueMap`) and it is injected.
-
+
For an interface, it is similar:
- ::java
- @Model(adaptables=Resource.class)
- public interface MyModel {
-
- @Inject
- String getPropertyName();
- }
+::java
+@Model(adaptables=Resource.class)
+public interface MyModel {
+
+@Inject
+String getPropertyName();
+}
Constructor injection is also supported (as of Sling Models 1.1.0):
- ::java
- @Model(adaptables=Resource.class)
- public class MyModel {
- @Inject
- public MyModel(@Named("propertyName") String propertyName) {
- // constructor code
- }
- }
+::java
+@Model(adaptables=Resource.class)
+public class MyModel {
+@Inject
+public MyModel(@Named("propertyName") String propertyName) {
+// constructor code
+}
+}
Because the name of a constructor argument parameter cannot be detected via the Java Reflection API a `@Named` annotation is mandatory for injectors that require a name for resolving the injection.
In order for these classes to be picked up, there is a header which must be added to the bundle's manifest:
- <Sling-Model-Packages>
- org.apache.sling.models.it.models
- </Sling-Model-Packages>
+<Sling-Model-Packages>
+org.apache.sling.models.it.models
+</Sling-Model-Packages>
This header must contain all packages which contain model classes or interfaces. However, subpackages need not be listed
individually, e.g. the header above will also pick up model classes in `org.apache.sling.models.it.models.sub`. Multiple packages
can be listed in a comma-separated list (any whitespace will be removed):
- <Sling-Model-Packages>
- org.apache.sling.models.it.models,
- org.apache.sling.other.models
- </Sling-Model-Packages>
+<Sling-Model-Packages>
+org.apache.sling.models.it.models,
+org.apache.sling.other.models
+</Sling-Model-Packages>
Alternatively it is possible to list all classes individually that are Sling Models classes via the `Sling-Model-Classes` header.
@@ -81,18 +78,18 @@ If you use the Sling Models bnd plugin all required bundle headers are generated
Client code doesn't need to be aware that Sling Models is being used. It just uses the Sling Adapter framework:
- ::java
- MyModel model = resource.adaptTo(MyModel.class)
-
+::java
+MyModel model = resource.adaptTo(MyModel.class)
+
Or
- ::jsp
- <sling:adaptTo adaptable="${resource}" adaptTo="org.apache.sling.models.it.models.MyModel" var="model"/>
+::jsp
+<sling:adaptTo adaptable="${resource}" adaptTo="org.apache.sling.models.it.models.MyModel" var="model"/>
Or
- ::jsp
- ${sling:adaptTo(resource, 'org.apache.sling.models.it.models.MyModel')}
+::jsp
+${sling:adaptTo(resource, 'org.apache.sling.models.it.models.MyModel')}
As with other AdapterFactories, if the adaptation can't be made for any reason, `adaptTo()` returns null.
## ModelFactory (since 1.2.0)
@@ -100,14 +97,14 @@ As with other AdapterFactories, if the adaptation can't be made for any reason,
Since Sling Models 1.2.0 there is another way of instantiating models. The OSGi service `ModelFactory` provides a method for instantiating a model that throws exceptions. This is not allowed by the Javadoc contract of the adaptTo method. That way `null` checks are not necessary and it is easier to see why instantiation of the model failed.
- ::java
- try {
- MyModel model = modelFactory.createModel(object, MyModel.class);
- } catch (Exception e) {
- // give out error message that the model could not be instantiated.
- // The exception contains further information.
- // See the javadoc of the ModelFactory for which Exception can be expected here
- }
+::java
+try {
+MyModel model = modelFactory.createModel(object, MyModel.class);
+} catch (Exception e) {
+// give out error message that the model could not be instantiated.
+// The exception contains further information.
+// See the javadoc of the ModelFactory for which Exception can be expected here
+}
In addition `ModelFactory` provides methods for checking whether a given class is a model at all (having the model annotation) or whether a class can be adapted from a given adaptable.
@@ -115,35 +112,35 @@ In addition `ModelFactory` provides methods for checking whether a given class i
## Names
If the field or method name doesn't exactly match the property name, `@Named` can be used:
- ::java
- @Model(adaptables=Resource.class)
- public class MyModel {
-
- @Inject @Named("secondPropertyName")
- private String otherName;
- }
-
+::java
+@Model(adaptables=Resource.class)
+public class MyModel {
+
+@Inject @Named("secondPropertyName")
+private String otherName;
+}
+
## Optional and Required
`@Inject`ed fields/methods are assumed to be required. To mark them as optional, use `@Optional`:
- ::java
- @Model(adaptables=Resource.class)
- public class MyModel {
-
- @Inject @Optional
- private String otherName;
- }
+::java
+@Model(adaptables=Resource.class)
+public class MyModel {
+
+@Inject @Optional
+private String otherName;
+}
If a majority of `@Inject`ed fields/methods are optional, it is possible (since Sling Models API 1.0.2/Impl 1.0.6) to change the default injection
strategy by using adding `defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL` to the `@Model` annotation:
- ::java
- @Model(adaptables=Resource.class, defaultInjectionStrategy=DefaultInjectionStrategy.OPTIONAL)
- public class MyModel {
+::java
+@Model(adaptables=Resource.class, defaultInjectionStrategy=DefaultInjectionStrategy.OPTIONAL)
+public class MyModel {
- @Inject
- private String otherName;
- }
+@Inject
+private String otherName;
+}
To still mark some fields/methods as being mandatory while relying on `defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL` for all other fields, the annotation `@Required` can be used.
@@ -152,182 +149,182 @@ To still mark some fields/methods as being mandatory while relying on `defaultIn
## Defaults
A default value can be provided (for Strings & primitives):
- ::java
- @Model(adaptables=Resource.class)
- public class MyModel {
-
- @Inject @Default(values="defaultValue")
- private String name;
- }
+::java
+@Model(adaptables=Resource.class)
+public class MyModel {
+
+@Inject @Default(values="defaultValue")
+private String name;
+}
Defaults can also be arrays:
- ::java
- @Model(adaptables=Resource.class)
- public class MyModel {
-
- @Inject @Default(intValues={1,2,3,4})
- private int[] integers;
- }
+::java
+@Model(adaptables=Resource.class)
+public class MyModel {
+
+@Inject @Default(intValues={1,2,3,4})
+private int[] integers;
+}
OSGi services can be injected:
- ::java
- @Model(adaptables=Resource.class)
- public class MyModel {
-
- @Inject
- private ResourceResolverFactory resourceResolverFactory;
- }
+::java
+@Model(adaptables=Resource.class)
+public class MyModel {
+
+@Inject
+private ResourceResolverFactory resourceResolverFactory;
+}
+
-
In this case, the name is not used -- only the class name.
## Collections
Lists and arrays are supported by some injectors. For the details look at the table given in [Available Injectors](#available-injectors):
- ::java
- @Model(adaptables=Resource.class)
- public class MyModel {
-
- @Inject
- private List<Servlet> servlets;
- }
+::java
+@Model(adaptables=Resource.class)
+public class MyModel {
+
+@Inject
+private List<Servlet> servlets;
+}
List injection for *child resources* works by injecting grand child resources (since Sling Models Impl 1.0.6). For example, the class
- ::java
- @Model(adaptables=Resource.class)
- public class MyModel {
+::java
+@Model(adaptables=Resource.class)
+public class MyModel {
- @Inject
- private List<Resource> addresses;
- }
+@Inject
+private List<Resource> addresses;
+}
Is suitable for a resource structure such as:
- +- resource (being adapted)
- |
- +- addresses
- |
- +- address1
- |
- +- address2
++- resource (being adapted)
+|
++- addresses
+|
++- address1
+|
++- address2
In this case, the `addresses` `List` will contain `address1` and `address2`.
-
+
## OSGi Service Filters
OSGi injection can be filtered:
- ::java
- @Model(adaptables=SlingHttpServletRequest.class)
- public class MyModel {
-
- @Inject
- private PrintWriter out;
-
- @Inject
- @Named("log")
- private Logger logger;
-
- @Inject
- @Filter("(paths=/bin/something)")
- private List<Servlet> servlets;
- }
-
-## PostConstruct Methods
+::java
+@Model(adaptables=SlingHttpServletRequest.class)
+public class MyModel {
+
+@Inject
+private PrintWriter out;
+
+@Inject
+@Named("log")
+private Logger logger;
+
+@Inject
+@Filter("(paths=/bin/something)")
+private List<Servlet> servlets;
+}
+
+## PostConstruct Methods
The `@PostConstruct` annotation can be used to add methods which are invoked upon completion of all injections:
- ::java
- @Model(adaptables=SlingHttpServletRequest.class)
- public class MyModel {
-
- @Inject
- private PrintWriter out;
-
- @Inject
- @Named("log")
- private Logger logger;
-
- @PostConstruct
- protected void sayHello() {
- logger.info("hello");
- }
- }
+::java
+@Model(adaptables=SlingHttpServletRequest.class)
+public class MyModel {
+
+@Inject
+private PrintWriter out;
+
+@Inject
+@Named("log")
+private Logger logger;
+
+@PostConstruct
+protected void sayHello() {
+logger.info("hello");
+}
+}
`@PostConstruct` methods in a super class will be invoked first.
-## Via
+## Via
If the injection should be based on a JavaBean property of the adaptable, you can indicate this using the `@Via` annotation:
- ::java
- @Model(adaptables=SlingHttpServletRequest.class)
- public interface MyModel {
-
- // will return request.getResource().adaptTo(ValueMap.class).get("propertyName", String.class)
- @Inject @Via("resource")
- String getPropertyName();
- }
+::java
+@Model(adaptables=SlingHttpServletRequest.class)
+public interface MyModel {
+
+// will return request.getResource().adaptTo(ValueMap.class).get("propertyName", String.class)
+@Inject @Via("resource")
+String getPropertyName();
+}
## Source
If there is ambiguity where a given injection could be handled by more than one injector, the `@Source` annotation can be used to define which injector is responsible:
- ::java
- @Model(adaptables=SlingHttpServletRequest.class)
- public interface MyModel {
-
- // Ensure that "resource" is retrived from the bindings, not a request attribute
- @Inject @Source("script-bindings")
- Resource getResource();
- }
+::java
+@Model(adaptables=SlingHttpServletRequest.class)
+public interface MyModel {
+
+// Ensure that "resource" is retrived from the bindings, not a request attribute
+@Inject @Source("script-bindings")
+Resource getResource();
+}
## Adaptations
If the injected object does not match the desired type and the object implements the `Adaptable` interface, Sling Models will try to adapt it. This provides the ability to create rich object graphs. For example:
- ::java
- @Model(adaptables=Resource.class)
- public interface MyModel {
-
- @Inject
- ImageModel getImage();
- }
-
- @Model(adaptables=Resource.class)
- public interface ImageModel {
-
- @Inject
- String getPath();
- }
+::java
+@Model(adaptables=Resource.class)
+public interface MyModel {
+
+@Inject
+ImageModel getImage();
+}
+
+@Model(adaptables=Resource.class)
+public interface ImageModel {
+
+@Inject
+String getPath();
+}
When a resource is adapted to `MyModel`, a child resource named `image` is automatically adapted to an instance of `ImageModel`.
Constructor injection is supported for the adaptable itself. For example:
- ::java
- @Model(adaptables=Resource.class)
- public class MyModel {
+::java
+@Model(adaptables=Resource.class)
+public class MyModel {
- public MyModel(Resource resource) {
- this.resource = resource;
- }
+public MyModel(Resource resource) {
+this.resource = resource;
+}
- private final Resource resource;
+private final Resource resource;
- @Inject
- private String propertyName;
- }
+@Inject
+private String propertyName;
+}
## Sling Validation (since 1.2.0)
<a name="validation">*See also [SLING-4161](https://issues.apache.org/jira/browse/SLING-4161)*</a>
You can use the attribute `validation` on the Model annotation to call a validation service on the resource being used by the Sling model. That attribute supports three different values:
- Value | Description | Invalid validation model | No validation model found | Resource invalid according to model
- ----- | ------- | ------------- | -------------| ---------
- `DISABLED` (default) | don't validate the resource bound to the Model | Model instantiated | Model instantiated | Model instantiated
- `REQUIRED` | enforce validation of the resource bound to the Model | Model not instantiated | Model not instantiated | Model not instantiated
- `OPTIONAL` | validate the resource bound to the Model (if a validation model is found) | Model not instantiated | Model instantiated | Model not instantiated
+Value | Description | Invalid validation model | No validation model found | Resource invalid according to model
+----- | ------- | ------------- | -------------| ---------
+`DISABLED` (default) | don't validate the resource bound to the Model | Model instantiated | Model instantiated | Model instantiated
+`REQUIRED` | enforce validation of the resource bound to the Model | Model not instantiated | Model not instantiated | Model not instantiated
+`OPTIONAL` | validate the resource bound to the Model (if a validation model is found) | Model not instantiated | Model instantiated | Model not instantiated
In case the model is not instantiated an appropriate error message is logged (if `adaptTo()` is used) or an appropriate exception is thrown (if `ModelFactory.createModel()` is used).
@@ -395,15 +392,15 @@ Sling Object | `sling-object` | `Integer.MAX_VALUE` | 1.1.0
Sometimes it is desirable to use customized annotations which aggregate the standard annotations described above. This will generally have
the following advantages over using the standard annotations:
- * Less code to write (only one annotation is necessary in most of the cases)
- * More robust (in case of name collisions among the different injectors, you make sure that the right injector is used)
- * Better IDE support (because the annotations provide elements for each configuration which is available for that specific injector, i.e. `filter` only for OSGi services)
+* Less code to write (only one annotation is necessary in most of the cases)
+* More robust (in case of name collisions among the different injectors, you make sure that the right injector is used)
+* Better IDE support (because the annotations provide elements for each configuration which is available for that specific injector, i.e. `filter` only for OSGi services)
The follow annotations are provided which are tied to specific injectors:
Annotation | Supported Optional Elements | Injector | Description
----------------- | ------------------------------ |-------------------------
-`@ScriptVariable` | `injectionStrategy` and `name` | `script-bindings` | Injects the script variable defined via [Sling Bindings](https://cwiki.apache.org/confluence/display/SLING/Scripting+variables). If `name` is not set the name is derived from the method/field name.
+`@ScriptVariable` | `injectionStrategy` and `name` | `script-bindings` | Injects the script variable defined via [Sling Bindings](https://cwiki.apache.org/confluence/display/SLING/Scripting+variables). If `name` is not set the name is derived from the method/field name.
`@ValueMapValue` | `injectionStrategy`, `name` and `via` | `valuemap` | Injects a `ValueMap` value. If `via` is not set, it will automatically take `resource` if the adaptable is the `SlingHttpServletRequest`. If `name` is not set the name is derived from the method/field name.
`@ChildResource` | `injectionStrategy`, `name` and `via` | `child-resources` | Injects a child resource by name. If `via` is not set, it will automatically take `resource` if the adaptable is the `SlingHttpServletRequest`. If `name` is not set the name is derived from the method/field name.
`@RequestAttribute` | `injectionStrategy`, `name` and `via` | `request-attributes` | Injects a request attribute by name. If `name` is not set the name is derived from the method/field name.
@@ -414,34 +411,34 @@ Annotation | Supported Optional Elements | Injector | Description
## Hints
-Those annotations replace `@Via`, `@Filter`, `@Named`, `@Optional`, `@Required`, `@Source` and `@Inject`.
+Those annotations replace `@Via`, `@Filter`, `@Named`, `@Optional`, `@Required`, `@Source` and `@Inject`.
Instead of using the deprecated annotation element `optional` you should rather use `injectionStrategy` with the values `DEFAULT`, `OPTIONAL` or `REQUIRED` (see also [SLING-4155](https://issues.apache.org/jira/browse/SLING-4155)).
`@Default` may still be used in addition to the injector-specific annotation to set default values. All elements given above are optional.
-
+
## Custom Annotations
To create a custom annotation, implement the `org.apache.sling.models.spi.injectorspecific.StaticInjectAnnotationProcessorFactory` interface.
This interface may be implemented by the same class as implements an injector, but this is not strictly necessary. Please refer to the
injectors in [Subversion](http://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/models/impl/src/main/java/org/apache/sling/models/impl/injectors/) for examples.
-
+
# Specifying an Alternate Adapter Class (since 1.1.0)
By default, each model class is registered using its own implementation class as adapter. If the class has additional interfaces this is not relevant.
The `@Model` annotations provides an optional `adapters` attribute which allows specifying under which type(s) the model
implementation should be registered in the Models Adapter Factory. Prior to *Sling Models Impl 1.3.10* only the given class names
-are used as adapter classes, since 1.3.10 the implementation class is always being registered implicitly as adapter as well (see [SLING-6658](https://issues.apache.org/jira/browse/SLING-6658)).
+are used as adapter classes, since 1.3.10 the implementation class is always being registered implicitly as adapter as well (see [SLING-6658](https://issues.apache.org/jira/browse/SLING-6658)).
With this attribute it is possible to register the model
to one (or multiple) interfaces, or a superclass. This allows separating the model interface from the implementation, which
makes it easier to provide mock implementations for unit tests as well.
Example:
- ::java
- @Model(adaptables = Resource.class, adapters = MyService.class)
- public class MyModel implements MyService {
- // injects fields and implements the MyService methods
- }
+::java
+@Model(adaptables = Resource.class, adapters = MyService.class)
+public class MyModel implements MyService {
+// injects fields and implements the MyService methods
+}
In this example a `Resource` can be adapted to a `MyService` interface, and the Sling Models implementation instantiates a
`MyModel` class for this.
@@ -474,17 +471,17 @@ programatically exported by calling the `ModelFactory` method `exportModel()`. T
* a target class
* a map of options
-The exact semantics of the exporting will be determined by an implementation of the `ModelExporter` service interface. Sling Models
+The exact semantics of the exporting will be determined by an implementation of the `ModelExporter` service interface. Sling Models
currently includes a single exporter, using the Jackson framework, which is capable of serializing models as JSON or transforming them to `java.util.Map` objects.
In addition, model objects can have servlets automatically registered for their resource type (if it is set) using the `@Exporter` annotation. For example, a model class with the annotation
- ::java
- @Model(adaptable = Resource.class, resourceType = "myco/components/foo")
- @Exporter(name = "jackson", extensions = "json")
+::java
+@Model(adaptable = Resource.class, resourceType = "myco/components/foo")
+@Exporter(name = "jackson", extensions = "json")
-results in the registration of a servlet with the resource type and extension specified and a selector of 'model' (overridable
-through the `@Exporter` annotation's `selector` attribute). When this servlet is invoked, the `Resource` will be adapted to the
+results in the registration of a servlet with the resource type and extension specified and a selector of 'model' (overridable
+through the `@Exporter` annotation's `selector` attribute). When this servlet is invoked, the `Resource` will be adapted to the
model, exported as a `java.lang.String` (via the named Exporter) and then returned to the client.
@@ -494,32 +491,32 @@ With the Sling Models bnd plugin it is possible to automatically generated the n
Example configuration:
- #!xml
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-bundle-plugin</artifactId>
- <extensions>true</extensions>
- <configuration>
- <instructions>
- <_plugin>org.apache.sling.bnd.models.ModelsScannerPlugin</_plugin>
- </instructions>
- </configuration>
- <dependencies>
- <dependency>
- <groupId>org.apache.sling</groupId>
- <artifactId>org.apache.sling.bnd.models</artifactId>
- <version>1.0.0</version>
- </dependency>
- </dependencies>
- </plugin>
+#!xml
+<plugin>
+<groupId>org.apache.felix</groupId>
+<artifactId>maven-bundle-plugin</artifactId>
+<extensions>true</extensions>
+<configuration>
+<instructions>
+<_plugin>org.apache.sling.bnd.models.ModelsScannerPlugin</_plugin>
+</instructions>
+</configuration>
+<dependencies>
+<dependency>
+<groupId>org.apache.sling</groupId>
+<artifactId>org.apache.sling.bnd.models</artifactId>
+<version>1.0.0</version>
+</dependency>
+</dependencies>
+</plugin>
If a `Sling-Model-Packages` or `Sling-Model-Classes` was already manually defined for the bundle the bnd plugin does nothing. So if you want to migrate an existing project to use this plugin remove the existing header definitions.
If you want to generate a bundle header compliant with Sling Models < 1.3.4 (i.e. `Sling-Model-Packages`) you need to specify the attribute `generatePackagesHeader=true`. An example configuration looks like this
- #!xml
- <configuration>
- <instructions>
- <_plugin>org.apache.sling.bnd.models.ModelsScannerPlugin;generatePackagesHeader=true</_plugin>
- </instructions>
- </configuration>
+#!xml
+<configuration>
+<instructions>
+<_plugin>org.apache.sling.bnd.models.ModelsScannerPlugin;generatePackagesHeader=true</_plugin>
+</instructions>
+</configuration>