Author: dkatayev Date: 2010-08-02 11:25:11 -0400 (Mon, 02 Aug 2010) New Revision: 2854 Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/jcr-advantages.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/jcr-applications.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/jcr-namespace-altering.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/jcr-registry-service.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/nodetype-registration.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/nodetypes-and-namespaces.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/why-jcr.xml Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr.xml Log: EXOJCR-869 JCR concepts documentation added Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/jcr-advantages.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/jcr-advantages.xml (rev 0) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/jcr-advantages.xml 2010-08-02 15:25:11 UTC (rev 2854) @@ -0,0 +1,59 @@ +<?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.AdvantagesofeXoJCR"> + <title>Advantages of eXo JCR</title> + + <section> + <title>Advantages for application developers:</title> + + <para>* Data repository and application are isolated from each other so an + application developer should not learn the details of particular data + storage's interfaces and can concentrate on business logic of a particular + application built on top of JCR</para> + + <para>* Repositories can be simply exchanged between different + applications without changing the applications themselves. This is the + matter of the repository configuration</para> + + <para>* Data storage types/versions can be changed and moreover different + types of data storages can be combined in one repository data model (of + course the complexity and work of building interfaces between the + repository and its data storage don't disappear but these changes are + isolated in the repository and thus manageable from the point of view of + the customer)</para> + + <mediaobject> + <imageobject> + <imagedata fileref="images/concepts/jcr-490x333.gif" /> + </imageobject> + </mediaobject> + </section> + + <section> + <title>Advantages for managers</title> + + <para>* Using a standardized repository for content management reduces the + risk of being dependent on a particular software vendor and proprietary + API.</para> + + <para>* Costs for maintaining and developing a content repository based + custom application is significantly lower than developing and supporting + your own interfaces and maintaining your own data repository applications + (staff can be trained once, it is possible to take help from community and + third party consulters).</para> + + <para>* Thanks to flexible layered JCR API (see below) it is possible to + fit the legacy storage subsystem into new interfaces and again decrease + the costs and risk of losing data.</para> + + <para>An extension to the API exists as we can see in the following layer + schema.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="images/concepts/JCR-Application2.jpg" /> + </imageobject> + </mediaobject> + </section> +</chapter> Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/jcr-applications.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/jcr-applications.xml (rev 0) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/jcr-applications.xml 2010-08-02 15:25:11 UTC (rev 2854) @@ -0,0 +1,40 @@ +<?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.eXoJCRApplicationModel"> + <title>eXo JCR Application Model</title> + + <para>A large picture of interaction between Applications and JCR looks as + follows:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="images/concepts/jcr-applications.gif" /> + </imageobject> + </mediaobject> + + <para>Every Content (JCR) dependent application interacts with eXo JCR via + JSR-170 and eXo JCR API extension (mostly for administration) directly or + using some intermediate Framework (Neither Application nor Framework should + ever rely on Implementation directly!)</para> + + <para>We call <emphasis role="bold">Content Application</emphasis> all + applications that may use JCR as a data storage. Some of them are generic + and completely decoupled from JCR API as interaction protocol hides Content + storage nature (like WebDav client), some partially decoupled (like Command + framework based) meaning that they do not use JCR API directly, and some + (most part) use JSR-170 directly.</para> + + <para><emphasis role="bold">Frameworks</emphasis> is a special kind of JCR + client that acts as an intermediate level between Content Repository and End + Client Application. There are <emphasis role="bold">Protocol</emphasis> + (WebDav, RMI or FTP servers for example) and <emphasis + role="bold">Pattern</emphasis> (Command, Web(servlet), J2EE connector) + specific Frameworks. It is possible to build a multi-layered (in framework + sense) JCR application, for example Web application uses Web framework that + uses Command framework underneath.</para> + + <para>To READ:</para> + + <para>Deployment JCR standalone (ver 1_5)</para> +</chapter> Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/jcr-namespace-altering.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/jcr-namespace-altering.xml (rev 0) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/jcr-namespace-altering.xml 2010-08-02 15:25:11 UTC (rev 2854) @@ -0,0 +1,39 @@ +<?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.Namespacealtering"> + <title>Namespace altering</title> + + <para>eXo JCR implementation since 1.11 version have support of altering + namespaces.</para> + + <section> + <title>Add new namespace</title> + + <programlisting>ExtendedNamespaceRegistry namespaceRegistry = (ExtendedNamespaceRegistry) workspace.getNamespaceRegistry(); +namespaceRegistry.registerNamespace("newMapping", "http://dumb.uri/jcr");</programlisting> + </section> + + <section> + <title>Changing existing namespace</title> + + <programlisting>ExtendedNamespaceRegistry namespaceRegistry = (ExtendedNamespaceRegistry) workspace.getNamespaceRegistry(); +namespaceRegistry.registerNamespace("newMapping", "http://dumb.uri/jcr"); +namespaceRegistry.registerNamespace("newMapping2", "http://dumb.uri/jcr"); +try { + assertNull(namespaceRegistry.getURI("newMapping")); + fail("exception should have been thrown"); +} catch (NamespaceException e) { +} +assertNotNull(namespaceRegistry.getURI("newMapping2")); +assertEquals("http://dumb.uri/jcr", namespaceRegistry.getURI("newMapping2"));</programlisting> + </section> + + <section> + <title>Removing existing namespace</title> + + <programlisting>ExtendedNamespaceRegistry namespaceRegistry = (ExtendedNamespaceRegistry) workspace.getNamespaceRegistry(); +namespaceRegistry.registerNamespace("newMapping", "http://dumb.uri/jcr"); +namespaceRegistry.unregisterNamespace("newMapping");</programlisting> + </section> +</chapter> Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/jcr-registry-service.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/jcr-registry-service.xml (rev 0) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/jcr-registry-service.xml 2010-08-02 15:25:11 UTC (rev 2854) @@ -0,0 +1,140 @@ +<?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.RegistryService"> + <title>Registry Service</title> + + <section id="Concept"> + <title>Concept</title> + + <para>The Registry Service is one of the key parts of the infrastructure + built around eXo JCR. Each JCR based service, applications etc may have + its own configuration and settings data and other data that have to be + stored persistently and used by the approptiate service or application + (let's call it <emphasis role="bold">Consumer</emphasis>).</para> + + <para>The service acts as a centralized collector (Registry) for such + data. Naturally, a registry storage is JCR based i.e. stored in some JCR + workspace (one per Repository) as an Item tree under <emphasis + role="bold">/exo:registry</emphasis> node.</para> + + <para>Despite the fact that the structure of the tree is well defined (see + the scheme below), it is not recommended for other services to manipulate + data using JCR API directly for better flexibility. So the Registry + Service acts as a mediator between a Consumer and its settings.</para> + + <para>The proposed structure of the Registry Service storage.It is divided + into 3 logical groups: services, applications and users:</para> + + <programlisting>/ + exo:registry/ &lt;-- registry "root" (exo:registry) + exo:services/ &lt;-- service data storage (exo:registryGroup) + service1/ + Consumer data (exo:registryEntry) + ... + exo:applications/ &lt;-- application data storage (exo:registryGroup) + app1/ + Consumer data (exo:registryEntry) + ... + exo:users/ &lt;-- user personal data storage (exo:registryGroup) + user1/ + Consumer data (exo:registryEntry) + ...</programlisting> + + <para>Each upper level eXo Service may store its configuration in Exo + Registry. First time start from xml-config (in jar etc). Each next will be + from Registry. In configuration file you can add force-xml-configuration + parameter to component to ignore reading parameters initialization from + RegistryService and to use file instead:</para> + + <programlisting>&lt;value-param&gt; + &lt;name&gt;force-xml-configuration&lt;/name&gt; + &lt;value&gt;true&lt;/value&gt; +&lt;/value-param&gt;</programlisting> + </section> + + <section> + <title>The API</title> + + <para>The main functionality of the Registry Service is pretty simple and + straightforward, it is described in the Registry abstract class as + following:</para> + + <programlisting>public abstract class Registry { + + /** + * Returns the Registry object which wraps the Node of the "exo:registry" type + */ + public abstract RegistryNode getRegistry(SessionProvider sessionProvider) + throws RepositoryConfigurationException, RepositoryException; + + /** + * Returns the existing RegistryEntry which wraps the Node of the "exo:registryEntry" type + */ + public abstract RegistryEntry getEntry(SessionProvider sessionProvider, String groupName, + String entryName) throws RepositoryException; + + /** + * Creates a new RegistryEntry + */ + public abstract void createEntry(SessionProvider sessionProvider, + String groupName, RegistryEntry entry) throws RepositoryException; + + /** + * Replaces a RegistryEntry + */ + public abstract void recreateEntry(SessionProvider sessionProvider, + String groupName, RegistryEntry entry) throws RepositoryException; + + /** + * Removes a RegistryEntry + */ + public abstract void removeEntry(SessionProvider sessionProvider, + String groupName, String entryName) throws RepositoryException;</programlisting> + + <para>As you can see it mainly looks like a simple CRUD interface for the + RegistryEntry object which wraps registry data for some Consumer as a + Registry Entry. The Registry Service itself knows nothing about the + wrapping data, it is Consumer's responsibility to manage and use its data + in its own way.</para> + + <para>To create an Entity Consumer you should have an idea how to + serialize the data to some XML structure and then create a RegistryEntry + from these data at once or populate them in a RegistryEntry object (using + RegistryEntry(String entryName) constructor and then obtain and fill a DOM + document).</para> + + <para>Example of RegistryService using:</para> + + <programlisting> RegistryService regService = (RegistryService) container + .getComponentInstanceOfType(RegistryService.class); + + RegistryEntry registryEntry = regService.getEntry(sessionProvider, + RegistryService.EXO_SERVICES, "my-service"); + + Document doc = registryEntry.getDocument(); + + String mySetting = getElementsByTagName("tagname").item(index).getTextContent(); + .....</programlisting> + </section> + + <section> + <title>Configuration</title> + + <para>RegistryService has only one optional properties parameter <emphasis + role="bold">locations</emphasis>. It is used to mention where exo:registry + is placed for each repository. The name of each property is interpreted as + a repository name and its value as a workspace name (a system workspace by + default).</para> + + <programlisting>&lt;component&gt; + &lt;type&gt;org.exoplatform.services.jcr.ext.registry.RegistryService&lt;/type&gt; + &lt;init-params&gt; + &lt;properties-param&gt; + &lt;name&gt;locations&lt;/name&gt; + &lt;property name="db1" value="ws2"/&gt; + &lt;/properties-param&gt; + &lt;/init-params&gt; +&lt;/component&gt;</programlisting> + </section> +</chapter> Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/nodetype-registration.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/nodetype-registration.xml (rev 0) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/nodetype-registration.xml 2010-08-02 15:25:11 UTC (rev 2854) @@ -0,0 +1,533 @@ +<?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.NodeTypeRegistration"> + <title>NodeType Registration</title> + + <para>eXo JCR implementation supports two ways of Nodetypes + registration:</para> + + <itemizedlist> + <listitem> + <para>From a NodeTypeValue POJO and</para> + </listitem> + + <listitem> + <para>from an XML document (stream).</para> + </listitem> + </itemizedlist> + + <section> + <title>Interfaces and methods</title> + + <section> + <title>ExtendedNodeTypeManager</title> + + <para>The ExtendedNodeTypeManager (from JCR 1.11) interface provides the + following methods related to registering node types</para> + + <programlisting>public static final int IGNORE_IF_EXISTS = 0; + +public static final int FAIL_IF_EXISTS = 2; + +public static final int REPLACE_IF_EXISTS = 4; + + +/** + * Registers node type using value object. + */ +void registerNodeType(NodeTypeValue nodeTypeValue, int alreadyExistsBehaviour) throws RepositoryException; + +/** + * Registers all node types using XML binding value objects from xml stream. + */ +void registerNodeTypes(InputStream xml, int alreadyExistsBehaviour) throws RepositoryException; + +/** + * Return &lt;code&gt;NodeTypeValue&lt;/code&gt; for a given nodetype name. Used for + * nodetype update. Value can be edited and registered via + * &lt;code&gt;registerNodeType(NodeTypeValue nodeTypeValue, int alreadyExistsBehaviour)&lt;/code&gt; + */ +NodeTypeValue getNodeTypeValue(String ntName) throws NoSuchNodeTypeException, RepositoryException; + +/** + * Registers or updates the specified &lt;code&gt;Collection&lt;/code&gt; of + * &lt;code&gt;NodeTypeValue&lt;/code&gt; objects. + */ +public NodeTypeIterator registerNodeTypes(Collection&lt;NodeTypeValue&gt; values, + int alreadyExistsBehaviour) throws UnsupportedRepositoryOperationException, + RepositoryException; + +/** + * Unregisters the specified node type. + */ +public void unregisterNodeType(String name) throws UnsupportedRepositoryOperationException, + NoSuchNodeTypeException, + RepositoryException; + +/** + * Unregisters the specified set of node types.&lt;p/&gt; Used to unregister a set + * of node types with mutual dependencies. + */ +public void unregisterNodeTypes(String[] names) throws UnsupportedRepositoryOperationException, + NoSuchNodeTypeException, + RepositoryException;</programlisting> + </section> + + <section> + <title>NodeTypeValue</title> + + <para>The NodeTypeValue interface represents a simple container + structure used to define node types which are then registered through + the ExtendedNodeTypeManager.registerNodeType method. Implementation of + this interface doesn't contain any validation logic.</para> + + <programlisting>/** + * @return Returns the declaredSupertypeNames. + */ +public List&lt;String&gt; getDeclaredSupertypeNames(); + +/** + * @param declaredSupertypeNames + *The declaredSupertypeNames to set. + */ +public void setDeclaredSupertypeNames(List&lt;String&gt; declaredSupertypeNames); + +/** + * @return Returns the mixin. + */ +public boolean isMixin(); + +/** + * @param mixin + *The mixin to set. + */ +public void setMixin(boolean mixin); + +/** + * @return Returns the name. + */ +public String getName(); + +/** + * @param name + *The name to set. + */ +public void setName(String name); + +/** + * @return Returns the orderableChild. + */ +public boolean isOrderableChild(); + +/** + * @param orderableChild + *The orderableChild to set. + */ +public void setOrderableChild(boolean orderableChild); + +/** + * @return Returns the primaryItemName. + */ +public String getPrimaryItemName(); + +/** + * @param primaryItemName + *The primaryItemName to set. + */ +public void setPrimaryItemName(String primaryItemName); + +/** + * @return Returns the declaredChildNodeDefinitionNames. + */ +public List&lt;NodeDefinitionValue&gt; getDeclaredChildNodeDefinitionValues(); + +/** + * @param declaredChildNodeDefinitionNames + *The declaredChildNodeDefinitionNames to set. + */ +public void setDeclaredChildNodeDefinitionValues(List&lt;NodeDefinitionValue&gt; declaredChildNodeDefinitionValues); + +/** + * @return Returns the declaredPropertyDefinitionNames. + */ +public List&lt;PropertyDefinitionValue&gt; getDeclaredPropertyDefinitionValues(); + +/** + * @param declaredPropertyDefinitionNames + *The declaredPropertyDefinitionNames to set. + */ +public void setDeclaredPropertyDefinitionValues(List&lt;PropertyDefinitionValue&gt; declaredPropertyDefinitionValues);</programlisting> + </section> + + <section> + <title>NodeDefinitionValue</title> + + <para>The NodeDefinitionValue interface extends ItemDefinitionValue with + the addition of write methods, enabling the characteristics of a child + node definition to be set, after which the NodeDefinitionValue is added + to a NodeTypeValue.</para> + + <programlisting>/** + * @return Returns the declaredSupertypeNames. + */ +public List&lt;String&gt; getDeclaredSupertypeNames(); + +/** + * @param declaredSupertypeNames + *The declaredSupertypeNames to set. + */ +public void setDeclaredSupertypeNames(List&lt;String&gt; declaredSupertypeNames); + +/** + * @return Returns the mixin. + */ +public boolean isMixin(); + +/** + * @param mixin + *The mixin to set. + */ +public void setMixin(boolean mixin); + +/** + * @return Returns the name. + */ +public String getName(); + +/** + * @param name + *The name to set. + */ +public void setName(String name); + +/** + * @return Returns the orderableChild. + */ +public boolean isOrderableChild(); + +/** + * @param orderableChild + *The orderableChild to set. + */ +public void setOrderableChild(boolean orderableChild); + +/** + * @return Returns the primaryItemName. + */ +public String getPrimaryItemName(); + +/** + * @param primaryItemName + *The primaryItemName to set. + */ +public void setPrimaryItemName(String primaryItemName); + +/** + * @return Returns the declaredChildNodeDefinitionNames. + */ +public List&lt;NodeDefinitionValue&gt; getDeclaredChildNodeDefinitionValues(); + +/** + * @param declaredChildNodeDefinitionNames + *The declaredChildNodeDefinitionNames to set. + */ +public void setDeclaredChildNodeDefinitionValues(List&lt;NodeDefinitionValue&gt; declaredChildNodeDefinitionValues); + +/** + * @return Returns the declaredPropertyDefinitionNames. + */ +public List&lt;PropertyDefinitionValue&gt; getDeclaredPropertyDefinitionValues(); + +/** + * @param declaredPropertyDefinitionNames + *The declaredPropertyDefinitionNames to set. + */ +public void setDeclaredPropertyDefinitionValues(List&lt;PropertyDefinitionValue&gt; declaredPropertyDefinitionValues); + +</programlisting> + </section> + + <section> + <title>PropertyDefinitionValue</title> + + <para>The PropertyDefinitionValue interface extends ItemDefinitionValue + with the addition of write methods, enabling the characteristics of a + child property definition to be set, after which the + PropertyDefinitionValue is added to a NodeTypeValue.</para> + + <programlisting>/** + * @return Returns the defaultValues. + */ +public List&lt;String&gt; getDefaultValueStrings(); + +/** + * @param defaultValues The defaultValues to set. + */ +public void setDefaultValueStrings(List&lt;String&gt; defaultValues); + +/** + * @return Returns the multiple. + */ +public boolean isMultiple(); + +/** + * @param multiple The multiple to set. + */ +public void setMultiple(boolean multiple); + +/** + * @return Returns the requiredType. + */ +public int getRequiredType(); + +/** + * @param requiredType The requiredType to set. + */ +public void setRequiredType(int requiredType); + +/** + * @return Returns the valueConstraints. + */ +public List&lt;String&gt; getValueConstraints(); + +/** + * @param valueConstraints The valueConstraints to set. + */ +public void setValueConstraints(List&lt;String&gt; valueConstraints);</programlisting> + </section> + + <section> + <title>ItemDefinitionValue</title> + + <programlisting> /** + * @return Returns the autoCreate. + */ +public boolean isAutoCreate(); + +/** + * @param autoCreate The autoCreate to set. + */ +public void setAutoCreate(boolean autoCreate); + +/** + * @return Returns the mandatory. + */ +public boolean isMandatory(); + +/** + * @param mandatory The mandatory to set. + */ +public void setMandatory(boolean mandatory); + +/** + * @return Returns the name. + */ +public String getName(); + +/** + * @param name The name to set. + */ +public void setName(String name); + +/** + * @return Returns the onVersion. + */ +public int getOnVersion(); + +/** + * @param onVersion The onVersion to set. + */ +public void setOnVersion(int onVersion); + +/** + * @return Returns the readOnly. + */ +public boolean isReadOnly(); + +/** + * @param readOnly The readOnly to set. + */ +public void setReadOnly(boolean readOnly);</programlisting> + </section> + </section> + + <section> + <title>Node type registration</title> + + <para>eXo JCR implementation supports various methods of the node-type + registration. The most used is registration from xml file <ulink + url="on JCR startup&gt;Node+types+and+Namespaces">on JCR + startup&gt;Node+types+and+Namespaces</ulink>.</para> + + <section> + <title>Run time registration from xml file.</title> + + <programlisting>ExtendedNodeTypeManager nodeTypeManager = (ExtendedNodeTypeManager) session.getWorkspace() + .getNodeTypeManager(); +InputStream is = MyClass.class.getResourceAsStream("mynodetypes.xml"); +nodeTypeManager.registerNodeTypes(is,ExtendedNodeTypeManager.IGNORE_IF_EXISTS );</programlisting> + </section> + + <section> + <title>Run time registration using NodeTypeValue.</title> + + <programlisting>ExtendedNodeTypeManager nodeTypeManager = (ExtendedNodeTypeManager) session.getWorkspace() + .getNodeTypeManager(); +NodeTypeValue testNValue = new NodeTypeValue(); + +List&lt;String&gt; superType = new ArrayList&lt;String&gt;(); +superType.add("nt:base"); +testNValue.setName("exo:myNodeType"); +testNValue.setPrimaryItemName(""); +testNValue.setDeclaredSupertypeNames(superType); +List&lt;PropertyDefinitionValue&gt; props = new ArrayList&lt;PropertyDefinitionValue&gt;(); +props.add(new PropertyDefinitionValue("*", + false, + false, + 1, + false, + new ArrayList&lt;String&gt;(), + false, + 0, + new ArrayList&lt;String&gt;())); +testNValue.setDeclaredPropertyDefinitionValues(props); + +nodeTypeManager.registerNodeType(testNValue, ExtendedNodeTypeManager.FAIL_IF_EXISTS);</programlisting> + </section> + </section> + + <section> + <title>Change existing node type</title> + + <para>If you want to replace existing node type definition you should pass + ExtendedNodeTypeManager.REPLACE_IF_EXISTS as a second parameter for the + method ExtendedNodeTypeManager.registerNodeType.</para> + + <programlisting>ExtendedNodeTypeManager nodeTypeManager = (ExtendedNodeTypeManager) session.getWorkspace() + .getNodeTypeManager(); +InputStream is = MyClass.class.getResourceAsStream("mynodetypes.xml"); +..... +nodeTypeManager.registerNodeTypes(is,ExtendedNodeTypeManager.REPLACE_IF_EXISTS );</programlisting> + </section> + + <section> + <title>Remove node type</title> + + <note> + <para>Removing node type is only possible when repository doesn't + contains nodes of this type</para> + </note> + + <programlisting>nodeTypeManager.unregisterNodeType("myNodeType");</programlisting> + </section> + + <section> + <title>Practical How to</title> + + <section> + <title>Add new PropertyDefinition</title> + + <programlisting> +NodeTypeValue myNodeTypeValue = nodeTypeManager.getNodeTypeValue(myNodeTypeName); +List&lt;PropertyDefinitionValue&gt; props = new ArrayList&lt;PropertyDefinitionValue&gt;(); +props.add(new PropertyDefinitionValue("tt", + true, + true, + 1, + false, + new ArrayList&lt;String&gt;(), + false, + PropertyType.STRING, + new ArrayList&lt;String&gt;())); +myNodeTypeValue.setDeclaredPropertyDefinitionValues(props); + +nodeTypeManager.registerNodeType(myNodeTypeValue, ExtendedNodeTypeManager.REPLACE_IF_EXISTS);</programlisting> + </section> + + <section> + <title>Add new child NodeDefinition</title> + + <programlisting>NodeTypeValue myNodeTypeValue = nodeTypeManager.getNodeTypeValue(myNodeTypeName); + +List&lt;NodeDefinitionValue&gt; nodes = new ArrayList&lt;NodeDefinitionValue&gt;(); +nodes.add(new NodeDefinitionValue("child", + false, + false, + 1, + false, + "nt:base", + new ArrayList&lt;String&gt;(), + false)); +testNValue.setDeclaredChildNodeDefinitionValues(nodes); + +nodeTypeManager.registerNodeType(myNodeTypeValue, ExtendedNodeTypeManager.REPLACE_IF_EXISTS);</programlisting> + </section> + + <section> + <title>Change or removing existing PropertyDefinition or child + NodeDefinition</title> + + <para>The main note what you should remember before changing or removing + existing definition is <emphasis role="bold">consistency of the existing + data</emphasis>. JCR <emphasis role="bold">do not allow</emphasis> you + to change the node type in that way in which the the existing data would + be incompatible with new node type. But if these changes are needed, you + can do it in several phases, consistently changing the node type and the + existing data.</para> + + <para>Example</para> + + <para>Add new residual property definition with name "downloadCount" to + the existing node type "myNodeType".</para> + + <para>There are two limitations that do not allow us to made the task + with single call of registerNodeType method.</para> + + <itemizedlist> + <listitem> + <para>Existing nodes of the type "myNodeType", wich does not contain + properties "downloadCount" that conflicts with node type what we + need.</para> + </listitem> + + <listitem> + <para>Registered node type "myNodeType" will not allow us to add + properties "downloadCount" because it has no such specific + properties.</para> + </listitem> + </itemizedlist> + + <para>To complete the task we need to make 3 steps</para> + + <itemizedlist> + <listitem> + <para>We change the existing node type "myNodeType" by adding not + mandatory property "downloadCount".</para> + </listitem> + + <listitem> + <para>We add to all existing nodes of the node type "myNodeType" + property "downloadCount".</para> + </listitem> + + <listitem> + <para>We change definition of the property "downloadCount" of the + node type "myNodeType" to mandatory.</para> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Changing list of super types</title> + + <programlisting>NodeTypeValue testNValue = nodeTypeManager.getNodeTypeValue("exo:myNodeType"); + +List&lt;String&gt; superType = testNValue.getDeclaredSupertypeNames(); +superType.add("mix:versionable"); +testNValue.setDeclaredSupertypeNames(superType); + +nodeTypeManager.registerNodeType(testNValue, ExtendedNodeTypeManager.REPLACE_IF_EXISTS);</programlisting> + </section> + </section> +</chapter> Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/nodetypes-and-namespaces.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/nodetypes-and-namespaces.xml (rev 0) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/nodetypes-and-namespaces.xml 2010-08-02 15:25:11 UTC (rev 2854) @@ -0,0 +1,141 @@ +<?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.NodeTypesandNamespaces"> + <title>Node Types and Namespaces</title> + + <section> + <title>Introduction</title> + + <para>Support of node types and namespaces is required by the JSR-170 + specification. Beyond the methods required by the specification, eXo JCR + has its own API extension for the <ulink + url="JCR.NodeTypeRegistration">Node type + registration&gt;NodeType+registration</ulink> as well as the ability to + declaratively define node types in the Repository at the start-up + time.</para> + </section> + + <section> + <title>Node Types definition</title> + + <para>Node type registration extension is declared in + org.exoplatform.services.jcr.core.nodetype.ExtendedNodeTypeManager + interface</para> + + <para>Your custom service can register some neccessary predefined node + types at the start-up time. The node definition should be placed in a + special XML file (see DTD below) and declared in the service's + configuration file thanks to eXo component plugin mechanism, described as + follows:</para> + + <programlisting>&lt;external-component-plugins&gt; + &lt;target-component&gt;org.exoplatform.services.jcr.RepositoryService&lt;/target-component&gt; + &lt;component-plugin&gt; + &lt;name&gt;add.nodeType&lt;/name&gt; + &lt;set-method&gt;addPlugin&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.jcr.impl.AddNodeTypePlugin&lt;/type&gt; + &lt;init-params&gt; + &lt;values-param&gt; + &lt;name&gt;autoCreatedInNewRepository&lt;/name&gt; + &lt;description&gt;Node types configuration file&lt;/description&gt; + &lt;value&gt;jar:/conf/test/nodetypes-tck.xml&lt;/value&gt; + &lt;value&gt;jar:/conf/test/nodetypes-impl.xml&lt;/value&gt; + &lt;/values-param&gt; + &lt;values-param&gt; + &lt;name&gt;repo1&lt;/name&gt; + &lt;description&gt;Node types configuration file for repository with name repo1&lt;/description&gt; + &lt;value&gt;jar:/conf/test/nodetypes-test.xml&lt;/value&gt; + &lt;/values-param&gt; + &lt;values-param&gt; + &lt;name&gt;repo2&lt;/name&gt; + &lt;description&gt;Node types configuration file for repository with name repo2&lt;/description&gt; + &lt;value&gt;jar:/conf/test/nodetypes-test2.xml&lt;/value&gt; + &lt;/values-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt;</programlisting> + + <para>There are two types of registration. First type of registration is + the registration of node types in all created repositories, it is + configured in values-param with the name <emphasis + role="bold">autoCreatedInNewRepository</emphasis>. The second type of + registration is registration of node types in specified repository and it + is configured in values-param with the name of repository.</para> + + <para>Node type definition file format:</para> + + <programlisting> &lt;?xml version="1.0" encoding="UTF-8"?&gt; + &lt;!DOCTYPE nodeTypes [ + &lt;!ELEMENT nodeTypes (nodeType)*&gt; + &lt;!ELEMENT nodeType (supertypes?|propertyDefinitions?|childNodeDefinitions?)&gt; + + &lt;!ATTLIST nodeType + name CDATA #REQUIRED + isMixin (true|false) #REQUIRED + hasOrderableChildNodes (true|false) + primaryItemName CDATA + &gt; + &lt;!ELEMENT supertypes (supertype*)&gt; + &lt;!ELEMENT supertype (CDATA)&gt; + + &lt;!ELEMENT propertyDefinitions (propertyDefinition*)&gt; + + &lt;!ELEMENT propertyDefinition (valueConstraints?|defaultValues?)&gt; + &lt;!ATTLIST propertyDefinition + name CDATA #REQUIRED + requiredType (String|Date|Path|Name|Reference|Binary|Double|Long|Boolean|undefined) #REQUIRED + autoCreated (true|false) #REQUIRED + mandatory (true|false) #REQUIRED + onParentVersion (COPY|VERSION|INITIALIZE|COMPUTE|IGNORE|ABORT) #REQUIRED + protected (true|false) #REQUIRED + multiple (true|false) #REQUIRED + &gt; + &lt;!-- For example if you need to set ValueConstraints [], + you have to add an empty element &lt;valueConstraints/&gt;. + The same order is for other properties like defaultValues, requiredPrimaryTypes etc. + --&gt; + &lt;!ELEMENT valueConstraints (valueConstraint*)&gt; + &lt;!ELEMENT valueConstraint (CDATA)&gt; + &lt;!ELEMENT defaultValues (defaultValue*)&gt; + &lt;!ELEMENT defaultValue (CDATA)&gt; + + &lt;!ELEMENT childNodeDefinitions (childNodeDefinition*)&gt; + + &lt;!ELEMENT childNodeDefinition (requiredPrimaryTypes)&gt; + &lt;!ATTLIST childNodeDefinition + name CDATA #REQUIRED + defaultPrimaryType CDATA #REQUIRED + autoCreated (true|false) #REQUIRED + mandatory (true|false) #REQUIRED + onParentVersion (COPY|VERSION|INITIALIZE|COMPUTE|IGNORE|ABORT) #REQUIRED + protected (true|false) #REQUIRED + sameNameSiblings (true|false) #REQUIRED + &gt; + &lt;!ELEMENT requiredPrimaryTypes (requiredPrimaryType+)&gt; + &lt;!ELEMENT requiredPrimaryType (CDATA)&gt; +]&gt;</programlisting> + </section> + + <section> + <title>Namespaces definition</title> + + <para>Default namespaces are registered by repository at the start-up + time</para> + + <para>Your custom service can extend a set of namespaces with some + application specific ones declaring it in service's configuration file + thanks to eXo component plugin mechanism, described as follows:</para> + + <programlisting> &lt;component-plugin&gt; + &lt;name&gt;add.namespaces&lt;/name&gt; + &lt;set-method&gt;addPlugin&lt;/set-method&gt; + &lt;type&gt;org.exoplatform.services.jcr.impl.AddNamespacesPlugin&lt;/type&gt; + &lt;init-params&gt; + &lt;properties-param&gt; + &lt;name&gt;namespaces&lt;/name&gt; + &lt;property name="test" value="http://www.test.org/test"/&gt; + &lt;/properties-param&gt; + &lt;/init-params&gt; + &lt;/component-plugin&gt;</programlisting> + </section> +</chapter> Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/why-jcr.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/why-jcr.xml (rev 0) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/why-jcr.xml 2010-08-02 15:25:11 UTC (rev 2854) @@ -0,0 +1,100 @@ +<?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.WhyuseJCR"> + <title>Why use JCR?</title> + + <section> + <title>What is this JCR is for?</title> + + <para>You already heard that JCR (Java Content Repository) is an interface + to access the file system, a relational database or an XML document. But + is it a better Hibernate (which is a generic interface for RDBMS), only + more generic? No, that is not correct.</para> + + <para>JCR is a java interface to access - as the name says - content only. + Content? That means most of the times web content and but also other + hierarchically stored data. The content is stored in a repository. The + repository can be a file system, a relational database or an XML document. + The internal structure of JCR data looks similar to an XML document, that + means a document tree with nodes and data - with a small difference in JCR + the data is stored in "property items".</para> + + <para>Or better to cite the specification of JCR: "A content repository is + a high-level information management system that is a superset of + traditional data repositories."</para> + </section> + + <section> + <title>But why use JCR?</title> + + <para>Remember how the data for your web site is stored? The images are + probably in a file system, the meta data is in some dedicated files - + maybe in XML - the text documents and pdfs are stored in different folders + with the meta data in an other place (a database?) and in a proprietary + structure. How do you manage to update these data and how do you manage + the access rights? Probably your boss asks you to manage different + versions of each document? The larger your web site is the more you need a + <ulink + url="http://en.wikipedia.org/wiki/Content_management_system">... + Management Systems</ulink> (CMS) which tackles all these issues.</para> + + <para>These CMS solutions are sold by different vendors and each vendor + provides its own API for interfacing the proprietary content repository. + The developers have to deal with this and need to learn the + vendor-specific API. If one time in future you wish to switch to a + different vendor everything is different, you have a new implementation, a + new interface etc.</para> + + <para>JCR provides a unique java interface for interacting with both text + and binary data, for dealing with any kind and amount of meta data your + documents might have. JCR supplies methods for storing, updating, deleting + and retrieving your data, independent of the fact if this data is stored + in a RDBMS, in a file system or as an XML document - you just don't need + to care about. The JCR interface also defines classes and methods for + searching, versioning, access control, locking, and observation.</para> + + <para>Furthermore an export and import functionality is specified so that + a switch to a different vendor is always possible.</para> + </section> + + <section> + <title>What does eXo do?</title> + + <para>eXo fully complies the JCR standard <ulink + url="http://jcp.org/en/jsr/detail?id=170">JSR 170</ulink> and therefore by + choosing eXo JCR you use a vendor-independent API. That's means you could + switch any time to a different vendor. Using the standard lowers your + lifecycle cost and reduces your long term risk.</para> + + <para>Of course eXo does not only offer JCR, but also the complete + solution for ECM (Enterprise Content Management) and for WCM (Web Content + Management).</para> + </section> + + <section> + <title>Further Reading</title> + + <para>In order to understand the theory of JCR and the API please read + some external documents about this standard:</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> + </section> +</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-02 13:37:39 UTC (rev 2853) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr.xml 2010-08-02 15:25:11 UTC (rev 2854) @@ -65,10 +65,35 @@ <xi:include href="jcr/data-container-howto.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/concepts/why-jcr.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="jcr/concepts/jcr-advantages.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/concepts/jcr-compatibility-levels.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="jcr/concepts/jcr-usage.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="jcr/concepts/jcr-extensions.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="jcr/concepts/jcr-applications.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="jcr/concepts/nodetype-registration.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="jcr/concepts/jcr-registry-service.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="jcr/concepts/jcr-namespace-altering.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="jcr/concepts/nodetypes-and-namespaces.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + </part>