[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.

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>&lt;value&gt; + &lt;object type="org.exoplatform.services.jcr.impl.ext.action.ActionConfiguration"&gt; + &lt;field name="eventTypes"&gt;&lt;string&gt;addNode,read&lt;/string&gt;&lt;/field&gt; + &lt;field name="workspace"&gt;&lt;string&gt;production&lt;/string&gt;&lt;/field &gt; + &lt;field name="actionClassName"&gt;&lt;string&gt;org.exoplatform.services.jcr.ext.SetAccessContextAction&lt;/string&gt;&lt;/field&gt; + &lt;/object&gt; +&lt;/value&gt;</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>&lt;workspace name="ws"&gt; + ... + &lt;!-- after query-handler element --&gt; + &lt;access-manager class="org.exoplatform.services.jcr.CustomAccessManagerImpl"&gt; + &lt;properties&gt; + &lt;property name="someProperty" value="value"/&gt; + ... + &lt;/properties&gt; + &lt;/access-manager&gt; + ... +&lt;/workspace&gt;</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 &gt; 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>&lt;nodeType name="exo:privilegeable" isMixin="true" hasOrderableChildNodes="false" primaryItemName=""&gt; + &lt;propertyDefinitions&gt; + &lt;propertyDefinition name="exo:permissions" requiredType="Permission" autoCreated="true" mandatory="true" + onParentVersion="COPY" protected="true" multiple="true"&gt; + &lt;valueConstraints/&gt; + &lt;/propertyDefinition&gt; + &lt;/propertyDefinitions&gt; +&lt;/nodeType&gt;</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>&lt;nodeType name="exo:owneable" isMixin="true" hasOrderableChildNodes="false" primaryItemName=""&gt; + &lt;propertyDefinitions&gt; + &lt;propertyDefinition name="exo:owner" requiredType="String" autoCreated="true" mandatory="true" onParentVersion="COPY" + protected="true" multiple="false"&gt; + &lt;valueConstraints/&gt; + &lt;/propertyDefinition&gt; + &lt;/propertyDefinitions&gt; +&lt;/nodeType&gt;</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&q... + + <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>&lt;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"&gt; + +&lt;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" /&gt; + +&lt;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" /&gt; + +&lt;/Politics&gt;</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\&lt;String, String\ <ulink url="\">\</ulink>\&gt; + 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&gt;http://wiki.exoplatform.com/xwiki/bin/view... + + <para>Database and workspace persistence storage configuration is + discussed in <ulink + url="http://wiki.exoplatform.com/xwiki/bin/view/JCR/JDBC+Data+Contai... + Data Container config</ulink></para> + + <para>Configuration details for <ulink + url="http://wiki.exoplatform.com/xwiki/bin/view/JCR/External+Value+S... + 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>&lt;!--component&gt; + &lt;type&gt;org.exoplatform.services.organization.impl.mock.DummyOrganizationService&lt;/type&gt; +&lt;/component--&gt;</programlisting> + + <itemizedlist> + <listitem> + <para>Add jcr organization service</para> + </listitem> + </itemizedlist> + + <programlisting>&lt;component&gt; + &lt;key&gt;org.exoplatform.services.organization.OrganizationService&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.jcr.ext.organization.JCROrganizationServiceImpl&lt;/type&gt; + &lt;init-params&gt; + &lt;value-param&gt; + &lt;name&gt;storage-workspace&lt;/name&gt; + &lt;description&gt;Workspace in default repository where organization storage will be created&lt;/description&gt; + &lt;value&gt;ws&lt;/value&gt; + &lt;/value-param&gt; + &lt;/init-params&gt; +&lt;/component&gt;</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>&lt;value-param&gt; + &lt;name&gt;repository&lt;/name&gt; + &lt;description&gt;The name of repository where organization storage will be created&lt;/description&gt; + &lt;value&gt;db1&lt;/value&gt; +&lt;/value-param&gt; +&lt;value-param&gt; + &lt;name&gt;storage-path&lt;/name&gt; + &lt;description&gt;The relative path where organization storage will be created&lt;/description&gt; + &lt;value&gt;/exo:organization&lt;/value&gt; +&lt;/value-param&gt;</programlisting> + + <para>where repository is the name of the repository where the organization + storage will be created&lt;br&gt; storage-path - the relative path to the + stored data&lt;br&gt;</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_20... + Java Content Repository</ulink> (2007)</para> + + <para>* Roy T. Fielding, <ulink + url="http://www.day.com/content/dam/day/whitepapers/JSR_170_White_Pa... + 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=eXoPlatf... + 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>&lt;component&gt; + &lt;key&gt;org.exoplatform.services.webdav.lnkproducer.LnkProducer&lt;/key&gt; + &lt;type&gt;org.exoplatform.services.webdav.lnkproducer.LnkProducer&lt;/type&gt; +&lt;/component&gt;</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>&lt;a href="http://localhost:8080/rest/lnkproducer/openit.lnk?path=/repository/workspace/somenode/somefile.extention"&gt;somefile.extention&lt;/a&gt;</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