8:01 a.m.
Author: nzamosenchuk
Date: 2011-08-02 09:01:46 -0400 (Tue, 02 Aug 2011)
New Revision: 4691
Added:
jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/jcr/api-extensions.xml
Modified:
jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/jcr.xml
jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/jcr/configuration/workspace-persistence-storage.xml
Log:
EXOJCR-267 : documentation added
Added:
jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/jcr/api-extensions.xml
===================================================================
---
jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/jcr/api-extensions.xml
(rev 0)
+++
jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/jcr/api-extensions.xml 2011-08-02
13:01:46 UTC (rev 4691)
@@ -0,0 +1,92 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="JCR.APIExtensions">
+ <?dbhtml filename="ch-api-extensions.html"?>
+
+ <title>JCR API Extensions</title>
+
+ <section>
+ <title>"Lazy" child nodes iteration</title>
+
+ <section>
+ <title>Concept</title>
+
+ <para>eXo JCR implementation offers new extended feature beyond JCR
+ specification. Sometimes it happens that one JCR Node has hundreds or
+ even thousands of child nodes. This situation is highly not recommended
+ for content repository data storage, but some times it occurs. JCR Team
+ is pleased to announce new feature that will help to have a deal with
+ huge child lists. They can be iterated in a "lazy" manner now giving
+ improvement in term of performance and RAM usage.</para>
+ </section>
+
+ <section>
+ <title>API and usage</title>
+
+ <para>Lazy child nodes iteration feature is accessible via extended
+ interface org.exoplatform.services.jcr.core.ExtendedNode, the inheritor
+ of javax.jcr.Node. It provides a new single method shown below:</para>
+
+ <programlisting language="java"> /**
+ * Returns a NodeIterator over all child Nodes of this Node. Does not include
properties
+ * of this Node. If this node has no child nodes, then an empty iterator is returned.
+ *
+ * @return A NodeIterator over all child Nodes of this
<code>Node</code>.
+ * @throws RepositoryException If an error occurs.
+ */
+ public NodeIterator getNodesLazily() throws RepositoryException;
+</programlisting>
+
+ <para>From the view of end-user or client application, getNodesLazily()
+ works similar to JCR specified getNodes() returning NodeIterator. "Lazy"
+ iterator supports the same set of features as an ordinary NodeIterator,
+ including skip() and excluding remove() features. "Lazy" implementation
+ performs reading from DB by pages. Each time when it has no more
+ elements stored in memory, it reads next set of items from persistent
+ layer. This set is called "page". Must admit that getNodesLazily feature
+ fully supports session and transaction changes log, so it's a
+ functionally-full analogue of specified getNodes() operation. So when
+ having a deal with huge list of child nodes, getNodes() can be simply
+ and safely substituted with getNodesLazily().</para>
+ </section>
+
+ <section>
+ <title>Configuration</title>
+
+ <para>"Lazy" iterator makes ahead reading into memory, though
reading
+ the "page". "Page" is a set of nodes read at once. Size of the
page by
+ default is 100 nodes and can be configured though workspace container
+ configuration using "lazy-node-iterator-page-size" parameter.
+ I.e.:</para>
+
+ <programlisting language="xml"><container
class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
+ <properties>
+ <property name="source-name" value="jdbcjcr" />
+ <property name="multi-db" value="true" />
+ <property name="max-buffer-size" value="200k" />
+ <property name="swap-directory"
value="target/temp/swap/ws" />
+ <property name="lazy-node-iterator-page-size" value="50"
/>
+ ...
+ </properties></programlisting>
+
+ <para>But it's not recommended to set huge page size</para>
+ </section>
+
+ <section>
+ <title>Implementation notices</title>
+
+ <para>Current "lazy" child nodes iterator supports caching, when
pages
+ are cached atomically in safe and optimized way. Cache is always kept in
+ consistent state using invalidation if child list changed. Take in
+ account the following difference in getNodes and getNodesLazily.
+ Specification defined getNodes method reads whole list of nodes, so
+ child items added after invocation will never be in results.
+ GetNodesLazily doesn't acquire full list of nodes, so child items added
+ after iterator creation can be found in result. So getNodesLazily can
+ represent some kind of "real-time" results. But it is highly depend on
+ numerous conditions and should not be used as a feature, it more likely
+ implementation specific issue typical for "lazy-pattern".</para>
+ </section>
+ </section>
+</chapter>
Modified:
jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/jcr/configuration/workspace-persistence-storage.xml
===================================================================
---
jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/jcr/configuration/workspace-persistence-storage.xml 2011-08-02
08:38:59 UTC (rev 4690)
+++
jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/jcr/configuration/workspace-persistence-storage.xml 2011-08-02
13:01:46 UTC (rev 4691)
@@ -23,6 +23,7 @@
<property name="multi-db" value="true"/>
<property name="max-buffer-size" value="200K"/>
<property name="swap-directory"
value="target/temp/swap/ws"/>
+ <property name="lazy-node-iterator-page-size"
value="50"/>
</properties></programlisting>
<para>Properties are Container specific parameters:</para>
@@ -46,6 +47,10 @@
value will be spooled if no value storage is configured but a
max-buffer-size is exceeded.</para>
+ <para><emphasis
role="bold">lazy-node-iterator-page-size</emphasis>: "Lazy"
+ child nodes iterator settings. Defines size of page, the number of nodes
+ that are retrieved from persistent storage at once.</para>
+
<para>eXo JCR has an RDB (JDBC) based, production ready <emphasis
role="bold">Workspace Data Container</emphasis>.</para>
Modified:
jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/jcr.xml
===================================================================
---
jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/jcr.xml 2011-08-02
08:38:59 UTC (rev 4690)
+++
jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/jcr.xml 2011-08-02
13:01:46 UTC (rev 4691)
@@ -103,7 +103,12 @@
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="jcr/searching/fulltext-search-and-settings.xml"
- xmlns:xi="http://www.w3.org/2001/XInclude" />
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <!-- api extensions -->
+
+ <xi:include href="jcr/api-extensions.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
<!-- protocols -->