[exo-jcr-commits] exo-jcr SVN: r2860 - in jcr/branches/1.12.x/docs/reference/en/src/main: docbook/en-US/modules/jcr and 3 other directories.
do-not-reply at jboss.org
do-not-reply at jboss.org
Tue Aug 3 08:58:25 EDT 2010
Author: dkatayev
Date: 2010-08-03 08:58:24 -0400 (Tue, 03 Aug 2010)
New Revision: 2860
Added:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/acl-ext.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/acl.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/binary-values-processing.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/jcr-organization-service.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/jcr-resources.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/link-producer.xml
jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/
jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/acl-ext.jpg
jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/acl.gif
jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/binaryvalue.png
jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/lnkproducer1.JPG
jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/lnkproducer2.JPG
jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/lnkproducer3.JPG
jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/lnkproducer4.JPG
Modified:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr.xml
Log:
EXOJCR-869 other documentation added
Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/acl-ext.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/acl-ext.xml (rev 0)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/acl-ext.xml 2010-08-03 12:58:24 UTC (rev 2860)
@@ -0,0 +1,153 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="JCR.AccessControlExtension">
+ <title>Access Control Extension</title>
+
+ <section>
+ <title>Prerequisites</title>
+
+ <para>This is an extension of eXo JCR Access Control features. Please read
+ <ulink url="Access Control">Access Control</ulink> and <ulink
+ url="JCR Extensions">JCR Extensions</ulink> topics before.</para>
+ </section>
+
+ <section>
+ <title>Overview</title>
+
+ <para>An extended Access Control system consists of: * Specifically
+ configured custom <emphasis role="bold">Extended Access Manager</emphasis>
+ which is called by eXo JCR internals to check if some user's Session
+ (user) has some privilege to perform some operation * The <emphasis
+ role="bold">Action</emphasis> which sets the thread local <emphasis
+ role="bold">Invocation Context</emphasis> at runtime. This invocation
+ context is used by the Extended Access Manager to make a decision about
+ the current Session's permission * <emphasis role="bold">Invocation
+ Context</emphasis> is a collection of properties which reflect the state
+ of a current Session. For the time being it contains: the type of the
+ current operation on Session (event), current Item (javax.jcr.Item) on
+ which this operation is performed and the current eXo Container</para>
+ </section>
+
+ <section>
+ <title>Access Context Action</title>
+
+ <para>SetAccessContextAction implements Action and may be called by
+ SessionActionInterceptor as a reaction of some event - usually before
+ writing methods and after reading (getNode(), getProperty() etc). This
+ SetAccessContextAction calls the
+ AccessManager.setContext(InvocationContext context) method which sets the
+ ThreadLocal invocation context for the current call.</para>
+
+ <para>Action's Configuration may look like the following:</para>
+
+ <programlisting><value>
+ <object type="org.exoplatform.services.jcr.impl.ext.action.ActionConfiguration">
+ <field name="eventTypes"><string>addNode,read</string></field>
+ <field name="workspace"><string>production</string></field >
+ <field name="actionClassName"><string>org.exoplatform.services.jcr.ext.SetAccessContextAction</string></field>
+ </object>
+</value></programlisting>
+ </section>
+
+ <section>
+ <title>The Invocation Context</title>
+
+ <para>The <emphasis role="bold">InvocationContext</emphasis> contains the
+ current Item, the current ExoContainer and the current EventType like
+ below:</para>
+
+ <programlisting>public interface InvocationContext extends ContextBase {
+
+ Item getCurrentItem();
+
+ int getEventType();
+
+ ExoContainer getContainer();
+}</programlisting>
+ </section>
+
+ <section>
+ <title>Custom Extended Access Manager</title>
+
+ <para>By default all Workspaces share an AccessManager instance, created
+ by RepositoryService at the startup (DefaultAccessManagerImpl) which
+ supports default access control policy as described in the <emphasis
+ role="bold">Access Control</emphasis> chapter. Custom Access Control
+ policy can be applied to certain Workspace configuring <emphasis
+ role="bold">access-manager</emphasis> element inside <emphasis
+ role="bold">workspace</emphasis> as follows:</para>
+
+ <programlisting><workspace name="ws">
+ ...
+ <!-- after query-handler element -->
+ <access-manager class="org.exoplatform.services.jcr.CustomAccessManagerImpl">
+ <properties>
+ <property name="someProperty" value="value"/>
+ ...
+ </properties>
+ </access-manager>
+ ...
+</workspace></programlisting>
+
+ <para>For each interested AccessManager implementation overwrite the
+ hasPermission() method so it will use the current invocation context at
+ its discretion. For instance, it may get some current node's metadata and
+ make a decision if the current User has appropriate permissions. Use
+ Invocation Context's runtime properties to make a decision about current
+ Session's privileges (see the Example below)</para>
+
+ <para>Simplified Sequence diagram for the Session.getNode() method (as an
+ Example):</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/other/acl-ext.jpg" />
+ </imageobject>
+ </mediaobject>
+ </section>
+
+ <section>
+ <title>Example of a custom Access Manager</title>
+
+ <para>The sample CustomAccessManagerImpl below extends the default access
+ manager and uses some DecisionMakingService in the overloaded
+ hasPermission method to find out if a current user has permission to use
+ current <emphasis role="bold">item, event type, userID</emphasis> and some
+ parameter of AccessManager. To make this Access manager work it is
+ necessary to configure it in jcr configuration as mentioned in <emphasis
+ role="bold">Custom Extended Access Manager</emphasis> as well as
+ SetAccessContextAction should be configured in the way mentioned in
+ <emphasis role="bold">Access Context Actio</emphasis></para>
+
+ <programlisting>public class CustomAccessManagerImpl extends AccessManager {
+
+ private String property;
+ private DecisionMakingService theService;
+
+ public CustomAccessManagerImpl (RepositoryEntry config, WorkspaceEntry wsConfig,
+ OrganizationService orgService, DecisionMakingService someService) throws RepositoryException {
+ super(config, wsConfig, orgService);
+ this.property = wsConfig.getAccessManager().getParameterValue("someParam");
+ this.theService = someService;
+ }
+
+ @Override
+ public boolean hasPermission(AccessControlList acl, String[] permission, String userId) {
+ // call the default permission check
+ if (super.hasPermission(acl, permission, userId)) {
+
+ Item curItem = context().getCurrentItem();
+ int eventType = context().getEventType();
+ ExoContainer container = context().getContainer();
+
+// call some service's method
+ return theService.makeDecision(curItem, eventType, userId, property);
+ } else {
+ return false;
+ }
+ }
+}
+</programlisting>
+ </section>
+</chapter>
Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/acl.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/acl.xml (rev 0)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/acl.xml 2010-08-03 12:58:24 UTC (rev 2860)
@@ -0,0 +1,407 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="JCR.AccessControl">
+ <title>Access Control</title>
+
+ <para>eXo JCR is a complete implementation of the standard JSR 170: <ulink
+ url="Content Repository for Java TM Technology API > http://jcp.org/en/jsr/detail?id=170">Content
+ Repository for Java TM Technology API</ulink>, including <emphasis
+ role="bold">Level 1, Level 2 and Additional Features</emphasis> as is
+ specified in the JCR Specification.</para>
+
+ <section>
+ <title>Standard Action Permissions</title>
+
+ <para>The JCR specification (JSR 170), does not have many requirements
+ about Access Control. It only requires the implementation of the
+ Session.checkPermission(String absPath, String actions) method. This
+ method checks if a current session has permissions to perform some actions
+ on absPath:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>absPath : the string representation of a JCR absolute
+ path</para>
+ </listitem>
+
+ <listitem>
+ <para>actions : eXo JCR interprets this string as a comma separated
+ list of individual action names such as the 4 types defined in JSR 170
+ :</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">add_node</emphasis> : Permission to
+ add a node</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">set_property</emphasis> : Permission
+ to set a property</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">remove</emphasis> : Permission to
+ remove an item (node or property)</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">read</emphasis> : Permission to
+ retrieve a node or read a property value</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+
+ <para>Examples :</para>
+
+ <para>session.checkPermission("/Groups/organization",
+ "add_node,set_property") will check if the session is allowed to add a
+ child node to "organization" and to modify its properties. If one the two
+ permissions is denied an AccessDeniedException is thrown.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>session.checkPermission("/Groups/organization/exo:name",
+ "read,set_property") will check if the session is allowed to read and
+ change the "exo:name" property of the "organization" node.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>eXo Access Control</title>
+
+ <para>The JSR170 specification does not define how permissions are managed
+ or checked. So eXo JCR has implemented its own proprietary extension to
+ manage and check permissions on nodes. In essence, this extension uses an
+ <ulink url="http://en.wikipedia.org/wiki/Access_control_list">Access
+ Control List (ACL)</ulink> policy model applied to eXo Organization model
+ (see eXo Platform Organization Service).</para>
+
+ <section>
+ <title>Principal and Identity</title>
+
+ <para>At the heart of eXo Access Control, is the notion of the <emphasis
+ role="bold">identity</emphasis> concept. Access to JCR is made through
+ sessions acquired against a repository. Sessions can be authenticated
+ through the standard (but optional) repository login mechanism. Each
+ session is associated with a <emphasis role="bold">principal</emphasis>.
+ The principal is an authenticated user or group that may act on JCR
+ data. The identity is a string identifying this <emphasis
+ role="bold">group or user</emphasis>.</para>
+
+ <para>There are 3 reserved identities that have special meanings in eXo
+ JCR:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">any</emphasis> : represents any
+ authenticated session.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">anonim</emphasis> : represents a
+ principal for non authenticated sessions. (No error, it's really
+ "\_\_anonim".)</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">system</emphasis> : represents a
+ principal for system sessions, typically used for administrative
+ purposes. System session have full access (all permissions) to all
+ nodes; therefore be careful when working with system
+ sessions.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>ACL</title>
+
+ <para>An access control list (ACL) is a list of permissions attached to
+ an object. An ACL specifies which users, groups or system processes are
+ granted access to JCR nodes, as well as what operations are allowed to
+ be performed on given objects.</para>
+
+ <para>eXo JCR Access Control is based on two facets applied to nodes
+ :</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">Privilegeable</emphasis> : Means that
+ the user or group (also called principal) needs the appropriate
+ privileges to access to this node. The privileges are defined as
+ (positive) permissions that are granted to users or groups.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">Ownable</emphasis> : The node has an
+ <emphasis role="bold">owner</emphasis>. The owner has always
+ <emphasis role="bold">full access</emphasis> (all permissions) to
+ the node, independent of the privilegeable facet.</para>
+ </listitem>
+ </itemizedlist>
+
+ <section>
+ <title>Privilegeable</title>
+
+ <para>A privilegeable node defines the permissions required for
+ actions on this node. For this purpose it contains an ACL.</para>
+
+ <para>At JCR level, this is implemented by an <emphasis
+ role="bold">exo:privilegeable</emphasis> mixin.</para>
+
+ <programlisting><nodeType name="exo:privilegeable" isMixin="true" hasOrderableChildNodes="false" primaryItemName="">
+ <propertyDefinitions>
+ <propertyDefinition name="exo:permissions" requiredType="Permission" autoCreated="true" mandatory="true"
+ onParentVersion="COPY" protected="true" multiple="true">
+ <valueConstraints/>
+ </propertyDefinition>
+ </propertyDefinitions>
+</nodeType></programlisting>
+
+ <para>A privilegeable node can have multiple exo:permissions values.
+ The type of these values is the eXo JCR specific type Permission. The
+ Permission type contains a list of ACL.</para>
+
+ <para>The possible values are corresponding to JCR standard
+ actions:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">read</emphasis>: The node or its
+ properties can be read.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">remove</emphasis>: The node or its
+ properties can be removed.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">add_node</emphasis> : Child nodes can
+ be added to this node.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">set_property</emphasis> : The node's
+ properties can be modified, added or removed.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Ownable</title>
+
+ <para>An ownable node defines an owner identity. The <emphasis
+ role="bold">owner</emphasis> has always <emphasis role="bold">full
+ privileges</emphasis>. These privileges are independent of the
+ permissions set by exo:permissions. At JCR level, the ownership is
+ implemented by an <emphasis role="bold">exo:owneable</emphasis> mixin.
+ This mixin holds an owner property.</para>
+
+ <programlisting><nodeType name="exo:owneable" isMixin="true" hasOrderableChildNodes="false" primaryItemName="">
+ <propertyDefinitions>
+ <propertyDefinition name="exo:owner" requiredType="String" autoCreated="true" mandatory="true" onParentVersion="COPY"
+ protected="true" multiple="false">
+ <valueConstraints/>
+ </propertyDefinition>
+ </propertyDefinitions>
+</nodeType></programlisting>
+
+ <para>The exo:owner property value contains exactly one identity
+ string value. There might be a long list of different permissions for
+ different identities (user or groups). All permissions are always
+ positive permissions; denials are not possible. When checking for a
+ permission of an action it's therefore perfectly sufficient that the
+ principal of a session belongs to one the groups, to who the concerned
+ action is granted.</para>
+ </section>
+
+ <section>
+ <title>ACL Inheritance</title>
+
+ <para>In order to grant or deny access to a node, eXo JCR applies a
+ privilege resolving logic at node access time.</para>
+
+ <para>If a node is <emphasis role="bold">privilegeable</emphasis>, the
+ node's ACL is used exclusively. If the ACL does not match the
+ principal's identity the principal has no access (except if he is the
+ owner of the node).</para>
+
+ <para>Non-privilegeable nodes inherit permissions from their parent
+ node. If the parent node isn't privilegeable either, the resolving
+ logic looks further up the node hierarchy and stops with the first
+ privilegeable ancestor of the current node. All nodes potentially
+ inherit from the <emphasis role="bold">workspace</emphasis> root
+ node.</para>
+
+ <para>The owner of a node is inherited following the same logic: If
+ the node has no owner, the owner information of the closest owneable
+ ancestor is inherited.</para>
+
+ <para>This inheritance is implemented by browsing up the node's
+ hierarchy. At access time, if the node does not have owner or
+ permissions the system looks up into the node's ancestor hierarchy for
+ the <emphasis role="bold">first</emphasis> ACL.</para>
+ </section>
+
+ <section>
+ <title>Default ACL of the root node</title>
+
+ <para>When no matching ACL is found in the ancestor hierarchy, the
+ system may end up looking at the root node's ACL. As ACL are optional,
+ even for the root node, if the root node has no ACL, the following
+ rule is ultimately applied to resolve privileges :</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">any</emphasis> identity (any
+ authenticated session) is granted all permissions</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+
+ <section>
+ <title>Notes</title>
+
+ <para><emphasis role="bold">Access Control nodetypes are not
+ extendible</emphasis> The access control mechanism works for <emphasis
+ role="bold">exo:owneable</emphasis> and <emphasis
+ role="bold">exo:privilegeable</emphasis> nodetypes only, not for their
+ subtypes! So you can NOT extend those nodetypes.</para>
+
+ <para><emphasis role="bold">Autocreation</emphasis> By default, newly
+ created nodes are neither <emphasis
+ role="bold">exo:privilegeable</emphasis> nor <emphasis
+ role="bold">exo:owneable</emphasis> but it is possible to configure the
+ repository to auto-create <emphasis
+ role="bold">exo:privilegeable</emphasis> or/and <emphasis
+ role="bold">exo:owneable</emphasis> thanks to eXo's JCR interceptors
+ extension (see <ulink
+ url="http://wiki.exoplatform.org/xwiki/bin/view/JCR/JCR+Extensions">http://wiki.exoplatform.org/xwiki/bin/view/JCR/JCR+Extensions</ulink>)</para>
+
+ <para><emphasis role="bold">OR-based Privilege Inheritance</emphasis>
+ Note, that eXo's Access Control implementation supports an privilege
+ inheritance that follows a strategy of either...or and has only an ALLOW
+ privilege mechanism (there is no DENY feature). This means that a
+ session is allowed to perform some operation on some node if its
+ identity has an appropriate permission assigned to this node. Only if
+ there is no exo:permission property assigned to the node itself, the
+ permissions of the node's ancestors are used.</para>
+ </section>
+
+ <section>
+ <title>Example</title>
+
+ <section>
+ <title>XML Example</title>
+
+ <para>In the following example, you see a node named "Politics" which
+ contains two nodes named "Cats" and "Dogs".</para>
+
+ <para>#info("These examples are exported from eXo DMS using the
+ \"document view\" representation of JCR. Each value of a multivalue
+ property is separated by a whitespace, each whitespace is escaped by
+ <emphasis>x0020</emphasis>.")</para>
+
+ <programlisting><Politics jcr:primaryType="nt:unstructured" jcr:mixinTypes="exo:owneable exo:datetime exo:privilegeable" exo:dateCreated="2009-10-08T18:02:43.687+02:00"
+exo:dateModified="2009-10-08T18:02:43.703+02:00"
+exo:owner="root"
+exo:permissions="any_x0020_read *:/platform/administrators_x0020_read *:/platform/administrators_x0020_add_node *:/platform/administrators_x0020_set_property *:/platform/administrators_x0020_remove">
+
+<Cats jcr:primaryType="exo:article"
+jcr:mixinTypes="exo:owneable"
+exo:owner="marry"
+exo:summary="The_x0020_secret_x0020_power_x0020_of_x0020_cats_x0020_influences_x0020_the_x0020_leaders_x0020_of_x0020_the_x0020_world."
+exo:text="" exo:title="Cats_x0020_rule_x0020_the_x0020_world" />
+
+<Dogs jcr:primaryType="exo:article"
+jcr:mixinTypes="exo:privilegeable"
+exo:permissions="manager:/organization_x0020_read manager:/organization_x0020_set_property"
+exo:summary="Dogs"
+exo:text="" exo:title="Dogs_x0020_are_x0020_friends" />
+
+</Politics></programlisting>
+
+ <para>The "Politics" node is <emphasis
+ role="bold">exo:owneable</emphasis> and <emphasis
+ role="bold">exo:privilegeable</emphasis>. It has both an <emphasis
+ role="bold">exo:owner</emphasis> property and also an <emphasis
+ role="bold">exo:permissions</emphasis> property. There is an <emphasis
+ role="bold">exo:owner="root"</emphasis> property so that the user root
+ is the owner. In the exo:permissions value you can see the ACL, a list
+ of access controls. In this example the group <emphasis
+ role="bold">\</emphasis>:/platform/administrators* has all rights on
+ this node (remember that the "\*" means any kind of membership/role).
+ Furthermore <emphasis role="bold">any</emphasis> has the read
+ permission.</para>
+
+ <para>As you can see in the jcr:mixinTypes property the "Cats" node is
+ <emphasis role="bold">exo:owneable</emphasis>; hence there is an
+ <emphasis role="bold">exo:owner="marry"</emphasis> property so that
+ the user marry is the owner. The "Cats" node is <emphasis
+ role="bold">not exo:privilegeable</emphasis> and has <emphasis
+ role="bold">no exo:permissions</emphasis>. In this case the <emphasis
+ role="bold">inheritance mechanism</emphasis> enters the game: The
+ "Cats" node has the same permissions as "Politics" node.</para>
+
+ <para>Finally the "Dogs" node is also a child node of "Politics". This
+ node is <emphasis role="bold">not exo:owneable</emphasis> and inherits
+ the owner of the "Politics" node (which is the user root). Otherwise
+ "Dogs" is <emphasis role="bold">exo:privilegeable</emphasis> and does
+ therefore have its own <emphasis
+ role="bold">exo:permissions</emphasis>. That means only the users
+ having a "manager" role in the group "/organization" and the user
+ "root" have the rights to access this node - all others have no access
+ rights.</para>
+ </section>
+
+ <section>
+ <title>Inheritance Examples</title>
+
+ <para>Here is an example showing the accessibility of two nodes (to
+ show inheritance) for two sample users named <emphasis
+ role="bold">manager</emphasis> and <emphasis
+ role="bold">user</emphasis>:</para>
+
+ <para>The "+" symbol means that there is a child node
+ "exo:owneable".</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/other.acl.gif" />
+ </imageobject>
+ </mediaobject>
+ </section>
+ </section>
+
+ <section>
+ <title>Java API</title>
+
+ <para>eXo JCR's ExtendedNode interface which extends javax.jcr.Node
+ interface provides additional methods for Access Control
+ management.</para>
+
+ <para>{table} Method signature |Description void
+ setPermissions(Map\<String, String\ <ulink url="\">\</ulink>\>
+ permissions)| Assigns a set of Permissions to a node void
+ setPermission(String identity, String\ <ulink url="\">\</ulink>
+ permission)| Assigns some Identity's Permission to a node void
+ removePermission(String identity)| Remove Identity's Permission void
+ removePermission(String identity, String permission)|Remove the
+ specified permission for a particular identity void clearACL()| Clears
+ the current ACL so it becomes default AccessControlList getACL()|
+ Returns the current ACL void checkPermission(String actions)| Checks
+ Permission (AccessDeniedException will be thrown if denied)
+ {table}</para>
+
+ <para>The "identity" parameter is the user or group name. The
+ permissions are the literal strings of the standard action permissions
+ (add_node, set_property, remove, read.</para>
+ </section>
+ </section>
+</chapter>
Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/binary-values-processing.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/binary-values-processing.xml (rev 0)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/binary-values-processing.xml 2010-08-03 12:58:24 UTC (rev 2860)
@@ -0,0 +1,179 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="JCR.BinaryValuesProcessing">
+ <title>Binary Values Processing</title>
+
+ <section>
+ <title>Configuration</title>
+
+ <para>Binary large object (BLOB) properties can be stored in two ways in
+ the eXo JCR: in the database with items information or in an external
+ storage on host file system. These options can be configured per workspace
+ in the repository configuration file (repository-configuration.xml in
+ portal and exo-jcr-config.xml in standalone mode). The database storage
+ can't be completely disabled.</para>
+
+ <para>The first case is optimal for most cases where you do not use very
+ large values or/and do not have too many BLOBs. The configuration of the
+ BLOBs size and BLOBs quantity in a repository depend on your database
+ features and hardware.</para>
+
+ <para>The second case is to use an external values storage. The storage
+ can be located on a built-in hard disk or on an attached storage. But in
+ any case you should have access to the storage as if it was a regular
+ file(s). The external value storage is optional and can be enabled in
+ addition to a database configuration.</para>
+
+ <note>
+ <para>eXo JCR Repository service configuration basics is discussed in
+ <ulink
+ url="Configuration>http://wiki.exoplatform.com/xwiki/bin/view/JCR/Configuration">Configuration</ulink></para>
+
+ <para>Database and workspace persistence storage configuration is
+ discussed in <ulink
+ url="http://wiki.exoplatform.com/xwiki/bin/view/JCR/JDBC+Data+Container+config">JDBC
+ Data Container config</ulink></para>
+
+ <para>Configuration details for <ulink
+ url="http://wiki.exoplatform.com/xwiki/bin/view/JCR/External+Value+Storages">External
+ Value Storages</ulink>.</para>
+ </note>
+ </section>
+
+ <section>
+ <title>Usage</title>
+
+ <para>In both cases a developer can set/update the binary Property via
+ Node.setProperty(String, InputStream), Property.setValue(InputStream) as
+ described in the spec JSR-170. Also there is the setter with a ready Value
+ object (obtainer from ValueFactory.createValue(InputStream)).</para>
+
+ <para>An example of a specification usage.</para>
+
+ <programlisting>// Set the property value with given stream content.
+Property binProp = node.setProperty("BinData", myDataStream);
+// Get the property value stream.
+InputStream binStream = binProp.getStream();
+
+// You may change the binary property value with a new Stream, all data will be replaced
+// with the content from the new stream.
+Property updatedBinProp = node.setProperty("BinData", newDataStream);
+// Or update an obtained property
+updatedBinProp.setValue(newDataStream);
+// Or update using a Value object
+updatedBinProp.setValue(ValueFactory.createValue(newDataStream));
+// Get the updated property value stream.
+InputStream newStream = updatedBinProp.getStream();</programlisting>
+
+ <para>But if you need to update the property sequentially and with partial
+ content you have no choice but to edit the whole data stream outside and
+ get it back to the repository each time. In case of really large sized
+ data the application will be stuck and the productivity will decrease a
+ lot. JCR stream setters will also check constraints and perform common
+ validation each time.</para>
+
+ <para>There is a feature of the eXo JCR extension that can be used for
+ binary values partial writing without frequent session level calls. The
+ main idea is to use during runtime a value object obtained from the
+ property as the storage of the property content during
+ writing/reading.</para>
+
+ <para>According to the spec JSR-170 Value interface provides the state of
+ property that can't be changed (edited). The eXo JCR core provides
+ ReadableBinaryValue and EditableBinaryValue interfaces which themselves
+ extend JCR Value. The interfaces allow the user to partially read and
+ change a value content.</para>
+
+ <para>ReadableBinaryValue value can be casted from any value, i.e. String,
+ Binary, Date etc.</para>
+
+ <programlisting>// get the property value of type PropertyType.STRING
+ReadableBinaryValue extValue = (ReadableBinaryValue) node.getProperty("LargeText").getValue();
+// read 200 bytes to a destStream from the position 1024 in the value content
+OutputStream destStream = new FileOutputStream("MyTextFile.txt");
+extValue.read(destStream, 200, 1024);</programlisting>
+
+ <para>But EditableBinaryValue can be applied only to properties of type
+ PropertyType.BINARY. In other cases a cast to EditableBinaryValue will
+ fail.</para>
+
+ <para>After the value has been edited the EditableBinaryValue value can be
+ applied to the property using the standard setters
+ (Property.setValue(Value), Property.setValues(Value),
+ Node.setProperty(String, Value) etc.). Only after the EditableBinaryValue
+ has been set to the property it can be obtained in this session by getters
+ (Property.getValue(), Node.getProperty(String) etc.).</para>
+
+ <para>The user can obtain an EditableBinaryValue instance and fill it with
+ data in an interaction manner (or any other appropriated to the targets)
+ and return (set) the value to the property after the content will be
+ done.</para>
+
+ <programlisting>// get the property value for PropertyType.BINARY Property
+EditableBinaryValue extValue = (EditableBinaryValue) node.getProperty("BinData").getValue();
+
+// update length bytes from the stream starting from the position 1024 in existing Value data
+extValue.update(dataInputStream, dataLength, 1024);
+
+// apply the edited EditableBinaryValue to the Property
+node.setProperty("BinData", extValue);
+
+// save the Property to persistence
+node.save();</programlisting>
+
+ <para>A practical example of the iterative usage. In this example the
+ value is updated with data from the sequence of streams and after the
+ update is done the value will be applied to the property and be visible
+ during the session.</para>
+
+ <programlisting>// update length bytes from the stream starting from the particular
+// position in the existing Value data
+int dpos = 1024;
+while (source.dataAvailable()) {
+ extValue.update(source.getInputStream(), source.getLength(), dpos);
+ dpos = dpos + source.getLength();
+}
+
+// apply the edited EditableBinaryValue to the Property
+node.setProperty("BinData", extValue);</programlisting>
+ </section>
+
+ <section>
+ <title>Value implementations</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/other/binaryvalue.png" />
+ </imageobject>
+ </mediaobject>
+
+ <para>ReadableBinaryValue has one method for Value reading.</para>
+
+ <para>Read length bytes from the binary value from the given position into
+ the stream.</para>
+
+ <programlisting>long read(OutputStream stream, long length, long position) throws IOException, RepositoryException ;</programlisting>
+
+ <para>EditableBinaryValue has two methods for value editing.</para>
+
+ <para>Update with length bytes from the specified stream to this value
+ data at a position. If the position is lower than 0 the IOException
+ exception will be thrown. If the position is higher than the current Value
+ length, the Value length will be increased at first to the size of
+ position and length bytes will be added after the position.</para>
+
+ <programlisting>void update(InputStream stream, long length, long position) throws IOException;</programlisting>
+
+ <para>Set the length of the Value in bytes to the specified size. If the
+ size is lower than 0 the IOException exception will be thrown. This
+ operation can be used both for extending and truncating the Value size.
+ This method is used internally in the update operation in case of
+ extending the size to the given position.</para>
+
+ <programlisting>void setLength(long size) throws IOException;</programlisting>
+
+ <para>An application can perform JCR binary operations more flexible and
+ will have less I/O and CPU usage using these methods.</para>
+ </section>
+</chapter>
Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/jcr-organization-service.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/jcr-organization-service.xml (rev 0)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/jcr-organization-service.xml 2010-08-03 12:58:24 UTC (rev 2860)
@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="JCR.Organizationservice">
+ <title>JCR Organization service</title>
+
+ <para>This is an implementation of the exo.core.component.organization.api
+ API. The information will be stored in the root node /exo:organization of
+ the workspace. The workspace name has to be configured in the configuration
+ file (see below).</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>You need to comment out the previous initialization of the
+ organization service, e.g. DummyOrganizationService</para>
+ </listitem>
+ </itemizedlist>
+
+ <programlisting><!--component>
+ <type>org.exoplatform.services.organization.impl.mock.DummyOrganizationService</type>
+</component--></programlisting>
+
+ <itemizedlist>
+ <listitem>
+ <para>Add jcr organization service</para>
+ </listitem>
+ </itemizedlist>
+
+ <programlisting><component>
+ <key>org.exoplatform.services.organization.OrganizationService</key>
+ <type>org.exoplatform.services.jcr.ext.organization.JCROrganizationServiceImpl</type>
+ <init-params>
+ <value-param>
+ <name>storage-workspace</name>
+ <description>Workspace in default repository where organization storage will be created</description>
+ <value>ws</value>
+ </value-param>
+ </init-params>
+</component></programlisting>
+
+ <para>where storage-workspace is the name of the workspace in the default
+ repository where the organization storage will be created.</para>
+
+ <para>Sice eXo JCR 1.11 you can add two new params:</para>
+
+ <programlisting><value-param>
+ <name>repository</name>
+ <description>The name of repository where organization storage will be created</description>
+ <value>db1</value>
+</value-param>
+<value-param>
+ <name>storage-path</name>
+ <description>The relative path where organization storage will be created</description>
+ <value>/exo:organization</value>
+</value-param></programlisting>
+
+ <para>where repository is the name of the repository where the organization
+ storage will be created<br> storage-path - the relative path to the
+ stored data<br></para>
+
+ <para>You should also read how to use the <ulink
+ url="Core.Organization Service Initializer">Core.Organization Service
+ Initializer</ulink>.</para>
+</chapter>
Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/jcr-resources.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/jcr-resources.xml (rev 0)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/jcr-resources.xml 2010-08-03 12:58:24 UTC (rev 2860)
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="JCR.Resources">
+ <title>JCR Resources:</title>
+
+ <para>* Java Community Process: <ulink
+ url="http://jcp.org/en/jsr/detail?id=170">JSR 170 </ulink> and <ulink
+ url="http://jcp.org/en/jsr/detail?id=283">JSR 283</ulink></para>
+
+ <para>* Tom Wheeler, <ulink
+ url="http://www.tomwheeler.com/java_content_repository_tomwheeler_20071007.pdf">The
+ Java Content Repository</ulink> (2007)</para>
+
+ <para>* Roy T. Fielding, <ulink
+ url="http://www.day.com/content/dam/day/whitepapers/JSR_170_White_Paper.pdf">JSR
+ 170 Overview: Standardizing the Content Repository Interface</ulink> (March
+ 13, 2005)</para>
+
+ <para>* David Nuescheler and Janus Boye, <ulink
+ url="http://www.cmswatch.com/Feature/123">JSR-170 What's in it for
+ me?</ulink> (April 20, 2005)</para>
+
+ <para>* Benjamin Mestrallet, Tuan Nguyen, Gennady Azarenkov, Francois Moron
+ and Brice Revenant <ulink
+ url="http://www.theserverside.com/tt/articles/article.tss?l=eXoPlatform2">eXo
+ Platform v2, Portal, JCR, ECM, Groupware and Business Intelligence</ulink>
+ (January 2006)</para>
+</chapter>
Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/link-producer.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/link-producer.xml (rev 0)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/other/link-producer.xml 2010-08-03 12:58:24 UTC (rev 2860)
@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="JCR.LinkProducerService">
+ <title>Link Producer Service</title>
+
+ <para>Link Producer Service - a simple service, which generates an .lnk
+ file, that is compatible with the Microsoft link file format. It is an
+ extension of the REST Framework library and is included into the WebDav
+ service. On dispatching a GET request the service generates the content of
+ an .lnk file, which points to a JCR resource via WebDav.</para>
+
+ <para>Link Producer has a simple configuration like described below:</para>
+
+ <programlisting><component>
+ <key>org.exoplatform.services.webdav.lnkproducer.LnkProducer</key>
+ <type>org.exoplatform.services.webdav.lnkproducer.LnkProducer</type>
+</component></programlisting>
+
+ <para>When using JCR the resource can be addressed by WebDav reference
+ (href) like <emphasis role="bold"> <ulink
+ url="http://host:port/rest/jcr/repository/workspace/somenode/somefile.extention">http://host:port/rest/jcr/repository/workspace/somenode/somefile.extention</ulink>
+ </emphasis>, the link servlet must be called for this resource by several
+ hrefs, like <emphasis role="bold"> <ulink
+ url="http://localhost:8080/rest/lnkproducer/openit.lnk?path=/repository/workspace/somenode/somefile.extention">http://localhost:8080/rest/lnkproducer/openit.lnk?path=/repository/workspace/somenode/somefile.extention</ulink>
+ </emphasis></para>
+
+ <para>Please note, that when using the portal mode the REST servlet is
+ available using a reference (href) like <emphasis role="bold"> <ulink
+ url="http://localhost:8080/portal/rest/">http://localhost:8080/portal/rest/</ulink>...
+ </emphasis></para>
+
+ <para>The name of the .lnk file can be any. But for the best compatibility
+ it must be the same as the name of the JCR resource.</para>
+
+ <para>Here is a step by step sample of a use case of the link producer... At
+ first, type valid reference to the resource, using the link producer in your
+ browser's adress field:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/other/lnkproducer1.JPG" />
+ </imageobject>
+ </mediaobject>
+
+ <para>Internet Explorer will give a dialog window requesting to Open a file
+ or to Save it. Click on the Open button</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/other/lnkproducer2.JPG" />
+ </imageobject>
+ </mediaobject>
+
+ <para>In Windows system an .lnk file will be downloaded and opened with the
+ application which is registered to open the files, which are pointed to by
+ the .lnk file. In case of a .doc file, Windows opens Microsoft Office Word
+ which will try to open a remote file (test0000.doc). Maybe it will be
+ necessary to enter USERNAME and PASSWORD.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/other/lnkproducer3.JPG" />
+ </imageobject>
+ </mediaobject>
+
+ <para>Next, you will be able to edit the file in Microsoft Word.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/other/lnkproducer4.JPG" />
+ </imageobject>
+ </mediaobject>
+
+ <para>The Link Producer is necessary for opening/editing and then saving the
+ remote files in Microsoft Office Word, without any further updates.</para>
+
+ <para>Also the Link Producer can be referenced to from an HTML page. If page
+ contains code like</para>
+
+ <programlisting><a href="http://localhost:8080/rest/lnkproducer/openit.lnk?path=/repository/workspace/somenode/somefile.extention">somefile.extention</a></programlisting>
+
+ <para>the file "somefile.extention" will open directly.</para>
+</chapter>
Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr.xml 2010-08-03 09:43:46 UTC (rev 2859)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr.xml 2010-08-03 12:58:24 UTC (rev 2860)
@@ -115,12 +115,32 @@
<xi:include href="jcr/backup/search-index-backup.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
-
-
<!-- other -->
<xi:include href="jcr/statistics.xml"
- xmlns:xi="http://www.w3.org/2001/XInclude" />
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="jcr/other/acl.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="jcr/other/acl-ext.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="jcr/other/link-producer.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="jcr/other/binary-values-processing.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="jcr/other/jcr-organization-service.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+
+
+
+
+ <xi:include href="jcr/other/jcr-resources.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
<!-- data container configs -->
Added: jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/acl-ext.jpg
===================================================================
(Binary files differ)
Property changes on: jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/acl-ext.jpg
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/acl.gif
===================================================================
(Binary files differ)
Property changes on: jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/acl.gif
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/binaryvalue.png
===================================================================
(Binary files differ)
Property changes on: jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/binaryvalue.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/lnkproducer1.JPG
===================================================================
(Binary files differ)
Property changes on: jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/lnkproducer1.JPG
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/lnkproducer2.JPG
===================================================================
(Binary files differ)
Property changes on: jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/lnkproducer2.JPG
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/lnkproducer3.JPG
===================================================================
(Binary files differ)
Property changes on: jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/lnkproducer3.JPG
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/lnkproducer4.JPG
===================================================================
(Binary files differ)
Property changes on: jcr/branches/1.12.x/docs/reference/en/src/main/resources/images/other/lnkproducer4.JPG
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
More information about the exo-jcr-commits
mailing list