[dna-commits] DNA SVN: r1002 - in trunk/docs/reference/src/main/docbook/en-US: content/core and 1 other directory.
dna-commits at lists.jboss.org
dna-commits at lists.jboss.org
Mon Jun 8 23:30:34 EDT 2009
Author: rhauch
Date: 2009-06-08 23:30:34 -0400 (Mon, 08 Jun 2009)
New Revision: 1002
Added:
trunk/docs/reference/src/main/docbook/en-US/content/core/graph.xml
Modified:
trunk/docs/reference/src/main/docbook/en-US/master.xml
Log:
More Reference Guide content on the graph api.
Added: trunk/docs/reference/src/main/docbook/en-US/content/core/graph.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/core/graph.xml (rev 0)
+++ trunk/docs/reference/src/main/docbook/en-US/content/core/graph.xml 2009-06-09 03:30:34 UTC (rev 1002)
@@ -0,0 +1,256 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ JBoss DNA (http://www.jboss.org/dna)
+ ~
+ ~ See the COPYRIGHT.txt file distributed with this work for information
+ ~ regarding copyright ownership. Some portions may be licensed
+ ~ to Red Hat, Inc. under one or more contributor license agreements.
+ ~ See the AUTHORS.txt file in the distribution for a full listing of
+ ~ individual contributors.
+ ~
+ ~ JBoss DNA is free software. Unless otherwise indicated, all code in JBoss DNA
+ ~ is licensed to you under the terms of the GNU Lesser General Public License as
+ ~ published by the Free Software Foundation; either version 2.1 of
+ ~ the License, or (at your option) any later version.
+ ~
+ ~ JBoss DNA is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+ ~ for more details.
+ ~
+ ~ You should have received a copy of the GNU Lesser General Public License
+ ~ along with this distribution; if not, write to:
+ ~ Free Software Foundation, Inc.
+ ~ 51 Franklin Street, Fifth Floor
+ ~ Boston, MA 02110-1301 USA
+ -->
+<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % CustomDTD SYSTEM "../../custom.dtd">
+%CustomDTD;
+]>
+<chapter id="graph_api">
+ <title>Graph API</title>
+ <para>
+ One of the central concepts within JBoss DNA is that of its <emphasis>graph model</emphasis>.
+ Information is structured into a hierarchy of nodes with properties, where nodes in the hierarchy
+ are identified by their path (and/or identifier properties). Properties are identified by
+ a name that incorporates a namespace and local name, and contain one or more property values
+ consisting of normal Java strings, names, paths, URIs, booleans, longs, doubles, decimals, binary content,
+ dates, UUIDs, references to other nodes, or any other serializable object.
+ </para>
+ <para>
+ This graph model is used throughout JBoss DNA: it forms the basis for the
+ <link linkend="connector_framework">connector framework</link>, it is used by the
+ <link linkend="sequencing_framework">sequencing framework</link> for the generated output,
+ and it is what the <link linkend="jcr">JCR implementation</link> uses internally to access and operate
+ on the repository content.
+ </para>
+ <para>
+ Therefore, this chapter provides essential information that will be essential to really understanding
+ how the connectors, sequencers, and other JBoss DNA features work.
+ </para>
+ <sect1 id="graph-names">
+ <title>Names</title>
+ <para>
+ JBoss DNA uses names to identify quite a few different types of objects. As we'll soon see, each property
+ of a node is given by a name, and each segment in a path is comprised of a name. Therefore,
+ names are a very important concept.
+ </para>
+ <para>
+ JBoss DNA names consist of a local part and are qualified with a namespaces. The local part can consist of
+ any character, and the namespace is identified by a URI. Namespaces were introduced in the
+ <link linkend="execution-context">previous chapter</link> and are managed by the &ExecutionContext;'s
+ <link linkend="namespace-registry">namespace registry</link>. Namespaces help reduce the risk of
+ clashes in names that have an equivalent same local part.
+ </para>
+ <para>
+ All names are immutable, which means that once a &Name; object is created, it will never change.
+ This characteristic makes it much easier to write thread-safe code - the objects never change and therefore
+ require no locks or synchronization to guarantee atomic reads. This is a technique that is more and more
+ often found in newer languages and frameworks that simplify concurrent operations.
+ </para>
+ <para>
+ &Name; is also a interface rather than a concrete class:
+ </para>
+<programlisting>
+</programlisting>
+ <para>
+ This means that you need to use a factory to create &Name; instances.
+ </para>
+ <para>
+ The use of a factory may seem like a disadvantage and unnecessary complexity, but there actually
+ are several benefits. First, it hides the concrete implementations, which is very appealing if
+ an optimized implementation can be chosen for particular situations. It also simplifies the
+ usage, since &Name; only has a few methods. Third, it allows the factory to cache or pool instances
+ where appropriate to help conserve memory. Finally, the very same factory actually serves as
+ a <emphasis>conversion</emphasis> mechanism from other forms. We'll actually see more of this
+ later in this chapter, when we talk about other kinds of <link linkend="graph-properties">property values</link>.
+ </para>
+ <para>
+ The factory for creating &Name; objects is called &NameFactory; and is available within the &ExecutionContext;,
+ via the <code>getValueFactories()</code> method. But before we see that, let's first discuss how names are represented as strings.
+ </para>
+ <para>
+ We mentioned earlier that names are qualified with a namespace, and namespaces are identified by URIs.
+ Also, the local part of the names can contain any character. So what do the string representation of names look like?
+ </para>
+ <para>
+ The &Name; interface defines a number of <code>getString(...)</code> methods that take different parameters.
+ The <code>getString()</code> method (which is called by the <code>toString()</code> method) will simply output
+ the namespace URI followed by a ':' and an local name (encoded with a default &TextEncoder; implementation, which
+ will be discussed in the <link linkend="graph-encoders">next section</link>). If you want to use the
+ namespace prefix, then simply use one of the <code>getString(...)</code> methods that takes a &NamespaceRegistry;
+ parameter.
+ </para>
+ <para>
+ We'll see how names are used later one, but one more point to make: &Name; is both serializable and comparable,
+ and all implementations should support <code>equals(...)</code> and <code>hashCode()</code> so that &Name; can
+ be used as a key in a hash-based map.
+ </para>
+ </sect1>
+ <sect1 id="graph-paths">
+ <title>Paths</title>
+ <para>
+ Another important concept in JBoss DNA's graph model is that of a <emphasis>path</emphasis>, which provides a way
+ of locating a node within a hierarchy. JBoss DNA's &Path; object is actually comprised of an ordered sequence
+ of &PathSegment; objects:
+ </para>
+ <programlisting>
+public interface &Path; extends Comparable<Path>, Iterable<&PathSegment;>, Serializable {
+
+ /**
+ * Return the number of segments in this path.
+ * @return the number of path segments
+ */
+ public int size();
+
+ /**
+ * Return whether this path represents the root path.
+ * @return true if this path is the root path, or false otherwise
+ */
+ public boolean isRoot();
+
+ /**
+ * {@inheritDoc}
+ */
+ public Iterator<&PathSegment;> iterator();
+
+ /**
+ * Obtain a copy of the segments in this path. None of the segments are encoded.
+ * @return the array of segments as a copy
+ */
+ public &PathSegment;[] getSegmentsArray();
+
+ /**
+ * Get an unmodifiable list of the path segments.
+ * @return the unmodifiable list of path segments; never null
+ */
+ public List<&PathSegment;> getSegmentsList();
+ /**
+ * Get the last segment in this path.
+ * @return the last segment, or null if the path is empty
+ */
+ public &PathSegment; getLastSegment();
+
+ /**
+ * Get the segment at the supplied index.
+ * @param index the index
+ * @return the segment
+ * @throws IndexOutOfBoundsException if the index is out of bounds
+ */
+ public &PathSegment; getSegment( int index );
+
+ /**
+ * Return an iterator that walks the paths from the root path down to this path. This method
+ * always returns at least one path (the root returns an iterator containing itself).
+ * @return the path iterator; never null
+ */
+ public Iterator<&Path;> pathsFromRoot();
+
+ /**
+ * Return a new path consisting of the segments starting at <code>beginIndex</code> index (inclusive).
+ * This is equivalent to calling <code>path.subpath(beginIndex,path.size()-1)</code>.
+ * @param beginIndex the beginning index, inclusive.
+ * @return the specified subpath
+ * @exception IndexOutOfBoundsException if the <code>beginIndex</code> is negative or larger
+ * than the length of this <code>Path</code> object
+ */
+ public &Path; subpath( int beginIndex );
+
+ /**
+ * Return a new path consisting of the segments between the <code>beginIndex</code> index (inclusive)
+ * and the <code>endIndex</code> index (exclusive).
+ * @param beginIndex the beginning index, inclusive.
+ * @param endIndex the ending index, exclusive.
+ * @return the specified subpath
+ * @exception IndexOutOfBoundsException if the <code>beginIndex</code> is negative, or
+ * <code>endIndex</code> is larger than the length of this <code>Path</code>
+ * object, or <code>beginIndex</code> is larger than <code>endIndex</code>.
+ */
+ public &Path; subpath( int beginIndex, int endIndex );
+
+ ...
+
+} </programlisting>
+ <para>
+ where each &PathSegment; is comprised of a &Name; and <emphasis>same-name-sibling index</emphasis>:
+ </para>
+ <programlisting>
+ </programlisting>
+ <para>
+
+ </para>
+
+ </sect1>
+ <sect1 id="graph-properties">
+ <title>Properties</title>
+ <para>
+
+ </para>
+ </sect1>
+ <sect1 id="graph-value-factories">
+ <title>Values and value factories</title>
+ <para>
+
+ </para>
+ </sect1>
+ <sect1 id="graph-encoders">
+ <title>Encoders and decoders</title>
+ <para>
+ String representations of &Name; and &Path; objects mentioned earlier that names are qualified with a namespace, and namespaces are identified by URIs.
+ Also, the local part of the names can contain any character. So what do the string representation of names look like?
+ </para>
+ <para>
+ The key is understanding that the namespaces will
+ </para>
+
+
+ </sect1>
+ <sect1 id="graph-api">
+ <title>Graph API</title>
+ <para>
+
+ </para>
+ </sect1>
+ <sect1 id="graph-requests">
+ <title>Request Model</title>
+ <para>
+
+ </para>
+ </sect1>
+ <sect1>
+ <title>Summary</title>
+ <para>
+ In this chapter, we introduced JBoss DNA's <emphasis>graph model</emphasis> and showed the different
+ kinds of objects used to represent nodes, paths, names, and properties. We saw how all of these objects
+ are actually immutable, and how the low-level Graph API uses this characteristic to provide a stateless
+ and thread-safe interface for working with repository content using the <emphasis>request model</emphasis>
+ used to read, update, and change content.
+ </para>
+ <para>
+ Next, we'll dive into the <link linkend="connector_framework">connector framework</link>, which builds
+ on top of the graph model and request model, allowing JBoss DNA to access the graph content stored
+ in many different kinds of systems.
+ </para>
+ </sect1>
+</chapter>
Property changes on: trunk/docs/reference/src/main/docbook/en-US/content/core/graph.xml
___________________________________________________________________
Name: svn:keywords
+ Id Revision
Name: svn:eol-style
+ LF
Modified: trunk/docs/reference/src/main/docbook/en-US/master.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/master.xml 2009-06-08 22:42:13 UTC (rev 1001)
+++ trunk/docs/reference/src/main/docbook/en-US/master.xml 2009-06-09 03:30:34 UTC (rev 1002)
@@ -82,6 +82,7 @@
</para>
</partintro>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/core/execution_context.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/core/graph.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/core/connector.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/core/sequencing.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/core/configuration.xml"/>
More information about the dna-commits
mailing list