jackrabbit-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r844404 [4/17] - in /websites/staging/jackrabbit/trunk/content: ./ JCR/ JCR/a-simple-ocm-project-with-maven-eclipse.data/ JCR/concurrency-control.data/ JCR/deployment-models.data/ JCR/how-jackrabbit-works.data/ JCR/how-to-map-associations-b...
Date Mon, 31 Dec 2012 12:40:59 GMT
Added: websites/staging/jackrabbit/trunk/content/JCR/first-hops-with-apache-jackrabbit.html
==============================================================================
--- websites/staging/jackrabbit/trunk/content/JCR/first-hops-with-apache-jackrabbit.html (added)
+++ websites/staging/jackrabbit/trunk/content/JCR/first-hops-with-apache-jackrabbit.html Mon Dec 31 12:40:56 2012
@@ -0,0 +1,647 @@
+
+<!-- 
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE- 2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License. 
+-->
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<HTML>
+  <HEAD>
+    <TITLE>First Hops with Apache Jackrabbit</TITLE>
+    <LINK type="text/css" rel="stylesheet" href="http://jackrabbit.apache.org/style/site.css">
+  <META http-equiv="Content-Type" content="text/html;charset=UTF-8"></HEAD>
+  <BODY>
+    <DIV id="page">
+      <DIV id="header">
+        <P id="jcr"><A href="http://jackrabbit.apache.org/"><IMG src="http://jackrabbit.apache.org/style/jlogo.gif" alt="Apache Jackrabbit" height="100" width="336"></A></P>
+        <P id="asf"><A href="http://www.apache.org/"><IMG src="http://jackrabbit.apache.org/style/asf-logo.gif" alt="Apache Software Foundation" height="100" width="387"></A></P>
+      </DIV>
+      <DIV id="body">
+        <DIV id="navigation">
+  <UL>
+	<LI>Apache Jackrabbit
+	<UL>
+		<LI><A href="welcome-to-apache-jackrabbit.html" title="Welcome to Apache Jackrabbit">Welcome</A></LI>
+		<LI><A href="downloads.html" title="Downloads">Downloads</A></LI>
+		<LI><A href="frequently-asked-questions.html" title="Frequently Asked Questions">FAQ</A></LI>
+		<LI><A href="http://wiki.apache.org/jackrabbit/FrontPage" class="external-link">Jackrabbit Wiki</A></LI>
+		<LI><A href="jackrabbit-history.html" title="Jackrabbit History">Jackrabbit History</A></LI>
+	</UL>
+	</LI>
+	<LI>Documentation
+	<UL>
+		<LI><A href="getting-started-with-apache-jackrabbit.html" title="Getting Started with Apache Jackrabbit">Getting Started</A></LI>
+		<LI><A href="standalone-server.html" title="Standalone Server">Standalone Server</A></LI>
+		<LI><A href="jackrabbit-components.html" title="Jackrabbit Components">Jackrabbit Components</A></LI>
+		<LI><A href="first-hops.html" title="First Hops">First Hops</A></LI>
+		<LI><A href="jcr-api.html" title="JCR & API">JCR &amp; API</A></LI>
+		<LI><A href="jackrabbit-architecture.html" title="Jackrabbit Architecture">Jackrabbit Architecture</A></LI>
+		<LI><A href="deployment-models.html" title="Deployment Models">Deployment Models</A></LI>
+		<LI><A href="jackrabbit-configuration.html" title="Jackrabbit Configuration">Jackrabbit Configuration</A></LI>
+		<LI><A href="node-types.html" title="Node Types">Node Types</A></LI>
+		<LI><A href="object-content-mapping.html" title="Object Content Mapping">Object Content Mapping</A></LI>
+	</UL>
+	</LI>
+	<LI>Development
+	<UL>
+		<LI><A href="jackrabbit-team.html" title="Jackrabbit Team">Jackrabbit Team</A></LI>
+		<LI><A href="jackrabbit-roadmap.html" title="Jackrabbit Roadmap">Jackrabbit Roadmap</A></LI>
+		<LI><A href="building-jackrabbit.html" title="Building Jackrabbit">Building Jackrabbit</A></LI>
+		<LI><A href="mailing-lists.html" title="Mailing Lists">Mailing Lists</A></LI>
+		<LI><A href="issue-tracker.html" title="Issue Tracker">Issue Tracker</A></LI>
+		<LI><A href="source-repository.html" title="Source Repository">Source Repository</A></LI>
+		<LI><A href="continuous-integration.html" title="Continuous Integration">Continuous Integration</A></LI>
+		<LI><A href="website.html" title="Website">Website</A></LI>
+		<LI><A href="creating-releases.html" title="Creating Releases">Creating Releases</A></LI>
+		<LI><A href="supporting-software-attribution.html" title="Supporting software attribution">Attribution</A></LI>
+	</UL>
+	</LI>
+	<LI>Apache Software Foundation
+	<UL>
+		<LI><A href="http://www.apache.org/foundation/how-it-works.html" class="external-link">Introduction</A></LI>
+		<LI><A href="http://www.apache.org/foundation/sponsorship.html" class="external-link">Sponsorship</A></LI>
+		<LI><A href="http://www.apache.org/foundation/thanks.html" class="external-link">Current Sponsors</A></LI>
+	</UL>
+	</LI>
+</UL>
+        </DIV>
+        <DIV id="content">
+          <H1>First Hops with Apache Jackrabbit</H1>
+  <P>Welcome to your first hops into the world of Apache Jackrabbit! This introduction gives you a hands-on experience with Jackrabbit and the JCR API. Once you have finished hopping through this document, you should be all set to continue on your own with the official JCR specification and the documentation on this site.</P>
+
+<H2><A name="FirstHopswithApacheJackrabbit-Hop0%3AGettingstarted"></A>Hop 0: Getting started</H2>
+
+<P>Before you can start using Jackrabbit, you need to have it installed on your computer. You can do this either by downloading a binary release and all the required dependencies or by building the Jackrabbit sources.</P>
+
+<P>Once you have Jackrabbit available locally, you should make sure that you have at least version 1.4 of the Java 2 Platform, Standard Edition (J2SE) installed and the following libraries configured in your Java classpath:</P>
+
+<DIV class="table-wrap">
+<TABLE class="confluenceTable"><TBODY>
+<TR>
+<TH class="confluenceTh"> Library </TH>
+<TH class="confluenceTh"> Comments </TH>
+</TR>
+<TR>
+<TD class="confluenceTd"> jackrabbit-1.0.jar </TD>
+<TD class="confluenceTd"> depending on whether you use a binary release or a locally compiled version </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> jcr-1.0.jar </TD>
+<TD class="confluenceTd"> for the JCR 1.0 API </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> slf4j-log4j12-1.0.jar and log4j-1.2.8.jar </TD>
+<TD class="confluenceTd"> for logging using SLF4J with Log4J (you should be fine with any Log4J 1.2.x version, or you could even replace both of these jars with another SLF4J implementation) </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> commons-collections-3.1.jar </TD>
+<TD class="confluenceTd"> for advanced data structures used by Jackrabbit </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> xercesImpl-2.6.2.jar and xmlParserApis-2.0.2.jar </TD>
+<TD class="confluenceTd"> for advanced XML support (you should be fine with any recent Xerces2 Java Parser implementation and the extra XML API library is only needed for JDK 1.4) </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> derby-10.1.3.1.jar </TD>
+<TD class="confluenceTd"> or any recent Derby release for embedded database storage </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> concurrent-1.3.4.jar </TD>
+<TD class="confluenceTd"> for advanced thread synchronization </TD>
+</TR>
+<TR>
+<TD class="confluenceTd"> lucene-1.4.3.jar </TD>
+<TD class="confluenceTd"> for full text indexing and searching </TD>
+</TR>
+</TBODY></TABLE>
+</DIV>
+
+
+<P>You should also add the current directory in your classpath to make it easy to compile and run the example classes. You may also want to copy the following log4j.properties file to the current directory to avoid warnings of missing log configuration. If you want to see the internal Jackrabbit log, just change the log level to INFO or even DEBUG.</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;"><B>log4j.properties</B></DIV><DIV class="codeContent panelContent">
+<PRE class="code-java">
+log4j.logger.org.apache.jackrabbit=WARN,stdout
+log4j.appender.stdout=org.apache.log4j.ConsoleAppender
+log4j.appender.stdout.layout=org.apache.log4j.SimpleLayout
+</PRE>
+</DIV></DIV>
+
+<DIV class="panelMacro"><TABLE class="tipMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD>If you have build Jackrabbit from sources with Maven 1.x, you can get all the runtime dependencies (and some extra libraries) copied to target/lib by running maven copy-deps in the Jackrabbit project directory.</TD></TR></TABLE></DIV>
+
+<DIV class="panelMacro"><TABLE class="tipMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD>You probably have an error in your classpath if you get a ClassNotFoundException message when trying to compile or run the examples below.</TD></TR></TABLE></DIV>
+
+<H2><A name="FirstHopswithApacheJackrabbit-Hop1%3ALoggingintoJackrabbit"></A>Hop 1: Logging in to Jackrabbit</H2>
+
+<P>Once you are done with the setup tasks, we can start doing some real work. As a warm-up we'll create a Jackrabbit content repository and start a login session for accessing it. The full example application that does this is shown below, with line-by-line explanations following shortly after.</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;"><B>FirstHop.java</B></DIV><DIV class="codeContent panelContent">
+<PRE class="code-java">
+<SPAN class="code-keyword">import</SPAN> javax.jcr.Repository;
+<SPAN class="code-keyword">import</SPAN> javax.jcr.Session;
+<SPAN class="code-keyword">import</SPAN> org.apache.jackrabbit.core.TransientRepository;
+
+/**
+ * First hop example. Logs in to a content repository and prints a
+ * status message.
+ */
+<SPAN class="code-keyword">public</SPAN> class FirstHop {
+
+    /**
+     * The main entry point of the example application.
+     *
+     * @param args command line arguments (ignored)
+     * @<SPAN class="code-keyword">throws</SPAN> Exception <SPAN class="code-keyword">if</SPAN> an error occurs
+     */
+    <SPAN class="code-keyword">public</SPAN> <SPAN class="code-keyword">static</SPAN> void main(<SPAN class="code-object">String</SPAN>[] args) <SPAN class="code-keyword">throws</SPAN> Exception {
+        Repository repository = <SPAN class="code-keyword">new</SPAN> TransientRepository();
+        Session session = repository.login();
+        <SPAN class="code-keyword">try</SPAN> {
+            <SPAN class="code-object">String</SPAN> user = session.getUserID();
+            <SPAN class="code-object">String</SPAN> name = repository.getDescriptor(Repository.REP_NAME_DESC);
+            <SPAN class="code-object">System</SPAN>.out.println(
+                    <SPAN class="code-quote">&quot;Logged in as &quot;</SPAN> + user + <SPAN class="code-quote">&quot; to a &quot;</SPAN> + name + <SPAN class="code-quote">&quot; repository.&quot;</SPAN>);
+        } <SPAN class="code-keyword">finally</SPAN> {
+            session.logout();
+        }
+    }
+
+}
+</PRE>
+</DIV></DIV>
+
+<P>You can also download the source file as FirstHop.java. If you have your classpath set up, you can compile the application with javac FirstHop.java and run it with java FirstHop to get the following output.</P>
+
+<P>Logged in as anonymous to a Jackrabbit repository.</P>
+
+<P>In addition to producing the above status line the application copies a default repository configuration file to repository.xml and creates an initial Jackrabbit content repository in the repository subdirectory. You can use the system properties org.apache.jackrabbit.repository.conf and org.apache.jackrabbit.repository.home to set alternative configuration file and repository directory locations.</P>
+
+<P>Read on for a detailed breakdown of the FirstHop application:</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+<SPAN class="code-keyword">import</SPAN> javax.jcr.Repository;
+<SPAN class="code-keyword">import</SPAN> javax.jcr.Session;
+</PRE>
+</DIV></DIV>
+
+<P>    The JCR API interfaces are located in the javax.jcr package found in the jcr-1.0.jar library. The promise of the JCR API is that if you only use these interfaces in your content application, it should remain mostly independent of the underlying content repository implementation.</P>
+
+<P>    The Repository interface represents a given content repository instance and the Session interface represents a single login session for accessing the repository. A session is needed to access any content within a repository.</P>
+
+<P>    Note that a Session instance is not guaranteed to be thread-safe so you should start multiple sessions if you need to access repository content simultaneously from different threads. This is especially important for things like web applications.<BR>
+import org.apache.jackrabbit.core.TransientRepository;</P>
+
+<P>    The best practice for deploying Jackrabbit is to use JNDI or some other configuration mechanism in a container environment to keep the application code free of direct Jackrabbit dependencies, but since we are creating a simple standalone application we can take a shortcut by using the TransientRepository class from Jackrabbit core.</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+<SPAN class="code-keyword">public</SPAN> class FirstHop
+<SPAN class="code-keyword">public</SPAN> <SPAN class="code-keyword">static</SPAN> void main(<SPAN class="code-object">String</SPAN>[] args) <SPAN class="code-keyword">throws</SPAN> Exception
+</PRE>
+</DIV></DIV>
+
+<P>    The FirstHop example is a simple standalone application that fits nicely in the main() method and lets the JVM take care of the possible exceptions. More substantial content applications could also be written as web application or EJB components with different setup and error handling patterns.</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+Repository repository = <SPAN class="code-keyword">new</SPAN> TransientRepository();
+</PRE>
+</DIV></DIV>
+
+<P>    The TransientRepository class implements the JCR Repository interface, so you can simply assign a TransientRepository instance to a Repository variable. The default constructor contains a utility feature that will take care of the initial configuration and repository construction when the first session is started. Thus there is no need for manual configuration for now unless you want direct control over the repository setup.</P>
+
+<P>    The TransientRepository implementation will automatically initialize the content repository when the first session is started and shut it down when the last session is closed. Thus there is no need for explicit repository shutdown as long as all sessions are properly closed. Note that a Jackrabbit repository directory contains a lock file that prevents it from being accessed simultaneously by multiple processes. You will see repository startup exceptions caused by the lock file if you fail to properly close all sessions or otherwise shut down the repository before leaving the process that accesses a repository. Normally you can just manually remove the lock file in such cases but such cases always present a chance of repository corruption especially if you use a non-transactional persistence manager.</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+Session session = repository.login();
+</PRE>
+</DIV></DIV>
+
+<P>    The default Repository.login() method starts a repository session using the default workspace and no user credentials. Jackrabbit tries to use the Java Authentication and Authorization Service (JAAS) configuration in such cases, but defaults to the anonymous user if a JAAS Subject is not found.</P>
+
+<P>    Since we use the TransientRepository class as the Repository implementation, this step will also cause the repository to be initialized.</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+<SPAN class="code-keyword">try</SPAN> { ... } <SPAN class="code-keyword">finally</SPAN> { session.logout(); }
+</PRE>
+</DIV></DIV>
+
+<P>    It is a good practice to properly release all acquired resources, and the JCR sessions are no exception. The try-finally idiom is a good way to ensure that a resource really gets released, as the release method gets called even if the intervening code throws an exception or otherwise jumps outside the scope (for example using a return, break, or continue statement).</P>
+
+<P>    The Session.logout() method in the finally branch closes the session and since this is the only session we have started, the TransientRepository is automatically shut down.</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+<SPAN class="code-object">String</SPAN> user = session.getUserID();
+</PRE>
+</DIV></DIV>
+
+<P>    The username or identifier of the user associated with a session is available using the Session.getUserID() method. Jackrabbit returns &quot;anonymous&quot; by default.</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+<SPAN class="code-object">String</SPAN> name = repository.getDescriptor(Repository.REP_NAME_DESC);
+</PRE>
+</DIV></DIV>
+
+<P>    Each content repository implementation publishes a number of string descriptors that describe the various implementation properties, like the implementation level and the supported optional JCR features. See the Repository interface for a list of the standard repository descriptors. The REP_NAME_DESC descriptor contains the name of the repository implementation, in this case &quot;Jackrabbit&quot;.</P>
+
+<H2><A name="FirstHopswithApacheJackrabbit-Hop2%3AWorkingwithcontent"></A>Hop 2: Working with content</H2>
+
+<P>The main function of a content repository is allow applications to store and retrieve content. The content in a JCR content repository consists of structured or unstructured data modeled as a hierarchy of nodes with properties that contain the actual data.</P>
+
+<P>The following example application first stores some content to the initially empty content repository, then retrieves the stored content and outputs it, and finally removes the stored content.</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;"><B>SecondHop.java</B></DIV><DIV class="codeContent panelContent">
+<PRE class="code-java">
+<SPAN class="code-keyword">import</SPAN> javax.jcr.Repository;
+<SPAN class="code-keyword">import</SPAN> javax.jcr.Session;
+<SPAN class="code-keyword">import</SPAN> javax.jcr.SimpleCredentials;
+<SPAN class="code-keyword">import</SPAN> javax.jcr.Node;
+<SPAN class="code-keyword">import</SPAN> org.apache.jackrabbit.core.TransientRepository;
+
+/**
+ * Second hop example. Stores, retrieves, and removes example content.
+ */
+<SPAN class="code-keyword">public</SPAN> class SecondHop {
+
+    /**
+     * The main entry point of the example application.
+     *
+     * @param args command line arguments (ignored)
+     * @<SPAN class="code-keyword">throws</SPAN> Exception <SPAN class="code-keyword">if</SPAN> an error occurs
+     */
+    <SPAN class="code-keyword">public</SPAN> <SPAN class="code-keyword">static</SPAN> void main(<SPAN class="code-object">String</SPAN>[] args) <SPAN class="code-keyword">throws</SPAN> Exception {
+        Repository repository = <SPAN class="code-keyword">new</SPAN> TransientRepository();
+        Session session = repository.login(
+                <SPAN class="code-keyword">new</SPAN> SimpleCredentials(<SPAN class="code-quote">&quot;username&quot;</SPAN>, <SPAN class="code-quote">&quot;password&quot;</SPAN>.toCharArray()));
+        <SPAN class="code-keyword">try</SPAN> {
+            Node root = session.getRootNode();
+
+            <SPAN class="code-comment">// Store content
+</SPAN>            Node hello = root.addNode(<SPAN class="code-quote">&quot;hello&quot;</SPAN>);
+            Node world = hello.addNode(<SPAN class="code-quote">&quot;world&quot;</SPAN>);
+            world.setProperty(<SPAN class="code-quote">&quot;message&quot;</SPAN>, <SPAN class="code-quote">&quot;Hello, World!&quot;</SPAN>);
+            session.save();
+
+            <SPAN class="code-comment">// Retrieve content
+</SPAN>            Node node = root.getNode(<SPAN class="code-quote">&quot;hello/world&quot;</SPAN>);
+            <SPAN class="code-object">System</SPAN>.out.println(node.getPath());
+            <SPAN class="code-object">System</SPAN>.out.println(node.getProperty(<SPAN class="code-quote">&quot;message&quot;</SPAN>).getString());
+
+            <SPAN class="code-comment">// Remove content
+</SPAN>            root.getNode(<SPAN class="code-quote">&quot;hello&quot;</SPAN>).remove();
+            session.save();
+        } <SPAN class="code-keyword">finally</SPAN> {
+            session.logout();
+        }
+    }
+
+}
+</PRE>
+</DIV></DIV>
+
+<P>Like in the first hop, this example source is also available as SecondHop.java. You can also compile and run this class just like you did in the first hop example. Running this example should produce the following output:</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+/hello/world
+Hello, World!
+</PRE>
+</DIV></DIV>
+
+<P>The basic structure of this example application is the same as in the First Hop example, so let's just walk through the differences:</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+<SPAN class="code-keyword">import</SPAN> javax.jcr.SimpleCredentials;
+<SPAN class="code-keyword">import</SPAN> javax.jcr.Node;
+</PRE>
+</DIV></DIV>
+
+<P>    These are two new classes we need for this example. The SimpleCredentials class is a simple implementation of the Credentials interface used for passing explicit user credentials to the Repository.login(Credentials) method.</P>
+
+<P>    The Node interface is used to manage the content nodes in a repository. There is a related interface called Property for managing content properties, but in this example we use the Property interface only indirectly.</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+<SPAN class="code-keyword">new</SPAN> SimpleCredentials(<SPAN class="code-quote">&quot;username&quot;</SPAN>, <SPAN class="code-quote">&quot;password&quot;</SPAN>.toCharArray())
+</PRE>
+</DIV></DIV>
+
+<P>    As discussed in the First Hop example, the default Repository.login() method returns an anonymous read-only session in the Jackrabbit default configuration. To be able to store and remove content we need to create a session with write access, and to do that we need to pass some credentials to the Repository.login(Credentials credentials) method.</P>
+
+<P>    The default Jackrabbit login mechanism accepts any username and password as valid credentials and returns a session with full write access. Thus we only need to construct and use a SimpleCredentials instance with some dummy username and password, in this case &quot;username&quot; and &quot;password&quot;.</P>
+
+<P>    The SimpleCredentials constructor follows the JAAS convention of represenenting the username as a normal String, but the password as a character array, so we need to use the String.toCharArray() method to satisfy the constructor.</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+Node root = session.getRootNode();
+</PRE>
+</DIV></DIV>
+
+<P>    Each JCR session is associated with a workspace that contains a single node tree. A simple way to access the root node is to call the Session.getRootNode() method. Having a reference to the root node allows us to easily store and retrieve content in the current workspace.</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+Node hello = root.addNode(<SPAN class="code-quote">&quot;hello&quot;</SPAN>);
+Node world = hello.addNode(<SPAN class="code-quote">&quot;world&quot;</SPAN>);
+</PRE>
+</DIV></DIV>
+
+<P>    New content nodes can be added using the Node.addNode(String relPath) method. The method takes the name (or relative path) of the node to be added and creates the named node in the transient storage associated with the current session. Until the transient storage is persisted, the added node is only visible within the current session and not within any other session that is concurrently accessing the content repository.</P>
+
+<P>    This code snippet creates two new nodes, called &quot;hello&quot; and &quot;world&quot;, with &quot;hello&quot; being a child of the root node and &quot;world&quot; a child of the &quot;hello&quot; node.</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+world.setProperty(<SPAN class="code-quote">&quot;message&quot;</SPAN>, <SPAN class="code-quote">&quot;Hello, World!&quot;</SPAN>);
+</PRE>
+</DIV></DIV>
+
+<P>    To add some content to the structure created using the &quot;hello&quot; and &quot;world&quot; nodes, we use the Node.setProperty(String name, String value) method to add a string property called &quot;message&quot; to the &quot;world&quot; node. The value of the property is the string &quot;Hello, World!&quot;.</P>
+
+<P>    Like the added nodes, also the property is first created in the transient storage associated with the current session. If the named property already exists, then this method will change the value of that property.</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+session.save();
+</PRE>
+</DIV></DIV>
+
+<P>    Even though the rest of our example would work just fine using only the transient storage of the single session, we'd like to persist the changes we've made so far. This way other sessions could also access the example content we just created. If you like, you could even split the example application into three pieces for respectively storing, retrieving, and removing the example content. Such a split would not work unless we persisted the changes we make.</P>
+
+<P>    The Session.save() method persists all pending changes in the transient storage. The changes are written to the persistent repository storage and they become visible to all sessions accessing the same workspace. Without this call all changes will be lost forever when the session is closed.</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+Node node = root.getNode(<SPAN class="code-quote">&quot;hello/world&quot;</SPAN>);
+</PRE>
+</DIV></DIV>
+
+<P>    Since we are still using the same session, we could use the existing hello and world node references to access the stored content, but let's pretend that we've started another session and want to retrieve the content that was previously stored.</P>
+
+<P>    The Node.getNode(String relPath) method returns a reference to the node at the given path relative to this node. The path syntax follows common file system conventions: a forward slash separates node names, a single dot represents the current node, and a double dot the parent node. Thus the path &quot;hello/world&quot; identifies the &quot;world&quot; child node of the &quot;hello&quot; child node of the current node - in this case the root node. The end result is that the method returns a node instance that represents the same content node as the world instance created a few lines earlier.</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+<SPAN class="code-object">System</SPAN>.out.println(node.getPath());
+</PRE>
+</DIV></DIV>
+
+<P>    Each content node and property is uniquely identified by its absolute path within the workspace. The absolute path starts with a forward slash and contains all the names of the ancestor nodes in order before the name of the current node or property.</P>
+
+<P>    The path of a node or property can be retrieved using the Item.getPath() method. The Item inteface is a superinterface of Node and Property, and contains all the functionality shared by nodes and properties.</P>
+
+<P>    The node variable references the &quot;world&quot; node, so this statement will output the line &quot;/hello/world&quot;.</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+<SPAN class="code-object">System</SPAN>.out.println(node.getProperty(<SPAN class="code-quote">&quot;message&quot;</SPAN>).getString());
+</PRE>
+</DIV></DIV>
+
+<P>    Properties can be accessed using the Node.getProperty(String relPath) method that returns an instance of the Property interface that represents the property at the given path relative to the current node. In this case the &quot;message&quot; property is the one we created a few lines earlier.</P>
+
+<P>    A JCR property can contain either a single or multiple values of a given type. There are property types for storing strings, numbers, dates, binary streams, node references, etc. We just want the single string value, so we use the Property.getString() method. The result of this statement is the line &quot;Hello, World!&quot; being outputted.</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+root.getNode(<SPAN class="code-quote">&quot;hello&quot;</SPAN>).remove();
+</PRE>
+</DIV></DIV>
+
+<P>    Nodes and properties can be removed using the Item.remove() method. The method removes the entire content subtree, so we only need to remove the topmost &quot;hello&quot; node to get rid of all the content we added before.</P>
+
+<P>    Removals are first stored in the session-local transient storage, just like added and changed content. Like before, the transient changes need to be explicitly saved for the content to be removed from the persistent storage.</P>
+
+<H2><A name="FirstHopswithApacheJackrabbit-Hop3%3AImportingcontent"></A>Hop 3: Importing content</H2>
+
+<P>TODO: Update to match the style of previous hops.</P>
+
+<P>To add content a bit more efficiently, you may want to try JCR's import facilities, such as Session.importXML. The following XML document by Elliotte Rusty Harold provides an interesting example that demonstrates a repository's namespace capabilities:</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;"><B>test.xml</B></DIV><DIV class="codeContent panelContent">
+<PRE class="code-java">
+&lt;xhtml:html xmlns:xhtml=<SPAN class="code-quote">&quot;http:<SPAN class="code-comment">//www.w3.org/1999/xhtml&quot;</SPAN>
+</SPAN>            xmlns:mathml=<SPAN class="code-quote">&quot;http:<SPAN class="code-comment">//www.w3.org/1998/<SPAN class="code-object">Math</SPAN>/MathML&quot;</SPAN>&gt;
+</SPAN>  &lt;xhtml:head&gt;&lt;xhtml:title&gt;Three Namespaces&lt;/xhtml:title&gt;&lt;/xhtml:head&gt;
+  &lt;xhtml:body&gt;
+    &lt;xhtml:h1 align=<SPAN class="code-quote">&quot;center&quot;</SPAN>&gt;An Ellipse and a Rectangle&lt;/xhtml:h1&gt;
+    &lt;svg:svg xmlns:svg=<SPAN class="code-quote">&quot;http:<SPAN class="code-comment">//www.w3.org/2000/svg&quot;</SPAN> 
+</SPAN>             width=<SPAN class="code-quote">&quot;12cm&quot;</SPAN> height=<SPAN class="code-quote">&quot;10cm&quot;</SPAN>&gt;
+      &lt;svg:ellipse rx=<SPAN class="code-quote">&quot;110&quot;</SPAN> ry=<SPAN class="code-quote">&quot;130&quot;</SPAN> /&gt;
+      &lt;svg:rect x=<SPAN class="code-quote">&quot;4cm&quot;</SPAN> y=<SPAN class="code-quote">&quot;1cm&quot;</SPAN> width=<SPAN class="code-quote">&quot;3cm&quot;</SPAN> height=<SPAN class="code-quote">&quot;6cm&quot;</SPAN> /&gt;
+    &lt;/svg:svg&gt;
+    &lt;xhtml:p&gt;The equation <SPAN class="code-keyword">for</SPAN> ellipses&lt;/xhtml:p&gt;
+&lt;mathml:math&gt;
+  &lt;mathml:apply&gt;
+    &lt;mathml:eq/&gt;
+    &lt;mathml:cn&gt; 1 &lt;/mathml:cn&gt;
+    &lt;mathml:apply&gt;
+      &lt;mathml:plus/&gt;
+      &lt;mathml:apply&gt;
+        &lt;mathml:divide/&gt;
+        &lt;mathml:apply&gt;
+          &lt;mathml:power/&gt;
+          &lt;mathml:ci&gt; x &lt;/mathml:ci&gt;
+          &lt;mathml:cn&gt; 2 &lt;/mathml:cn&gt;
+        &lt;/mathml:apply&gt;
+        &lt;mathml:apply&gt;
+          &lt;mathml:power/&gt;
+          &lt;mathml:ci&gt; a &lt;/mathml:ci&gt;
+          &lt;mathml:cn&gt; 2 &lt;/mathml:cn&gt;
+        &lt;/mathml:apply&gt;
+      &lt;/mathml:apply&gt;
+      &lt;mathml:apply&gt;
+        &lt;mathml:divide/&gt;
+        &lt;mathml:apply&gt;
+          &lt;mathml:power/&gt;
+          &lt;mathml:ci&gt; y &lt;/mathml:ci&gt;
+          &lt;mathml:cn&gt; 2 &lt;/mathml:cn&gt;
+        &lt;/mathml:apply&gt;
+        &lt;mathml:apply&gt;
+          &lt;mathml:power/&gt;
+          &lt;mathml:ci&gt; b &lt;/mathml:ci&gt;
+          &lt;mathml:cn&gt; 2 &lt;/mathml:cn&gt;
+        &lt;/mathml:apply&gt;        
+      &lt;/mathml:apply&gt;
+    &lt;/mathml:apply&gt;
+ &lt;/mathml:apply&gt;
+&lt;/mathml:math&gt;
+    &lt;xhtml:hr/&gt;
+    &lt;xhtml:p&gt;Last Modified January 10, 2002&lt;/xhtml:p&gt;    
+  &lt;/xhtml:body&gt;
+&lt;/xhtml:html&gt;
+</PRE>
+</DIV></DIV>
+
+<P>The third example application shown below will import the XML file called test.xml from the current directory into a new content repository node called importxml. Once the XML content is imported, the application recursively dumps the contents of the entire workspace using the simple dump() method.</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;"><B>ThirdHop.java</B></DIV><DIV class="codeContent panelContent">
+<PRE class="code-java">
+<SPAN class="code-keyword">import</SPAN> javax.jcr.*;
+<SPAN class="code-keyword">import</SPAN> org.apache.jackrabbit.core.TransientRepository;
+<SPAN class="code-keyword">import</SPAN> java.io.FileInputStream;
+
+/**
+ * Third Jackrabbit example application. Imports an example XML file
+ * and outputs the contents of the entire workspace.
+ */
+<SPAN class="code-keyword">public</SPAN> class ThirdHop {
+
+    /** Runs the ThirdHop example. */
+    <SPAN class="code-keyword">public</SPAN> <SPAN class="code-keyword">static</SPAN> void main(<SPAN class="code-object">String</SPAN>[] args) <SPAN class="code-keyword">throws</SPAN> Exception {
+        <SPAN class="code-comment">// Set up a Jackrabbit repository with the specified
+</SPAN>        <SPAN class="code-comment">// configuration file and repository directory
+</SPAN>        Repository repository = <SPAN class="code-keyword">new</SPAN> TransientRepository();
+
+        <SPAN class="code-comment">// Login to the <SPAN class="code-keyword">default</SPAN> workspace as a dummy user
+</SPAN>        Session session = repository.login(
+            <SPAN class="code-keyword">new</SPAN> SimpleCredentials(<SPAN class="code-quote">&quot;username&quot;</SPAN>, <SPAN class="code-quote">&quot;password&quot;</SPAN>.toCharArray()));
+        <SPAN class="code-keyword">try</SPAN> {
+            <SPAN class="code-comment">// Use the root node as a starting point
+</SPAN>            Node root = session.getRootNode();
+
+            <SPAN class="code-comment">// Import the XML file unless already imported
+</SPAN>            <SPAN class="code-keyword">if</SPAN> (!root.hasNode(<SPAN class="code-quote">&quot;importxml&quot;</SPAN>)) {
+                <SPAN class="code-object">System</SPAN>.out.print(<SPAN class="code-quote">&quot;Importing xml... &quot;</SPAN>);
+                <SPAN class="code-comment">// Create an unstructured node under which to <SPAN class="code-keyword">import</SPAN> the XML
+</SPAN>                Node node = root.addNode(<SPAN class="code-quote">&quot;importxml&quot;</SPAN>, <SPAN class="code-quote">&quot;nt:unstructured&quot;</SPAN>);
+                <SPAN class="code-comment">// Import the file <SPAN class="code-quote">&quot;test.xml&quot;</SPAN> under the created node
+</SPAN>                FileInputStream xml = <SPAN class="code-keyword">new</SPAN> FileInputStream(<SPAN class="code-quote">&quot;test.xml&quot;</SPAN>);
+                session.importXML(
+                    <SPAN class="code-quote">&quot;/importxml&quot;</SPAN>, xml, ImportUUIDBehavior.IMPORT_UUID_CREATE_NEW);
+                xml.close();
+                <SPAN class="code-comment">// Save the changes to the repository
+</SPAN>                session.save();
+                <SPAN class="code-object">System</SPAN>.out.println(<SPAN class="code-quote">&quot;done.&quot;</SPAN>);
+            }
+
+            dump(root);
+        } <SPAN class="code-keyword">finally</SPAN> {
+            session.logout();
+        }
+    }
+
+    /** Recursively outputs the contents of the given node. */
+    <SPAN class="code-keyword">private</SPAN> <SPAN class="code-keyword">static</SPAN> void dump(Node node) <SPAN class="code-keyword">throws</SPAN> RepositoryException {
+        <SPAN class="code-comment">// First output the node path
+</SPAN>        <SPAN class="code-object">System</SPAN>.out.println(node.getPath());
+        <SPAN class="code-comment">// Skip the virtual (and large!) jcr:system subtree
+</SPAN>        <SPAN class="code-keyword">if</SPAN> (node.getName().equals(<SPAN class="code-quote">&quot;jcr:system&quot;</SPAN>)) {
+            <SPAN class="code-keyword">return</SPAN>;
+        }
+
+        <SPAN class="code-comment">// Then output the properties
+</SPAN>        PropertyIterator properties = node.getProperties();
+        <SPAN class="code-keyword">while</SPAN> (properties.hasNext()) {
+            Property property = properties.nextProperty();
+            <SPAN class="code-keyword">if</SPAN> (property.getDefinition().isMultiple()) {
+                <SPAN class="code-comment">// A multi-valued property, print all values
+</SPAN>                Value[] values = property.getValues();
+                <SPAN class="code-keyword">for</SPAN> (<SPAN class="code-object">int</SPAN> i = 0; i &lt; values.length; i++) {
+                    <SPAN class="code-object">System</SPAN>.out.println(
+                        property.getPath() + <SPAN class="code-quote">&quot; = &quot;</SPAN> + values[i].getString());
+                }
+            } <SPAN class="code-keyword">else</SPAN> {
+                <SPAN class="code-comment">// A single-valued property
+</SPAN>                <SPAN class="code-object">System</SPAN>.out.println(
+                    property.getPath() + <SPAN class="code-quote">&quot; = &quot;</SPAN> + property.getString());
+            }
+        }
+
+        <SPAN class="code-comment">// Finally output all the child nodes recursively
+</SPAN>        NodeIterator nodes = node.getNodes();
+        <SPAN class="code-keyword">while</SPAN> (nodes.hasNext()) {
+            dump(nodes.nextNode());
+        }
+    }
+
+}
+</PRE>
+</DIV></DIV>
+
+<P>Running the ThirdHop class should produce output like the following:</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java">
+Importing XML... done.
+/
+/jcr:primaryType=rep:root
+/jcr:system
+/testnode
+/testnode/jcr:primaryType=nt:unstructured
+/testnode/testprop=Hello, World.
+/importxml
+/importxml/jcr:primaryType=nt:unstructured
+/importxml/xhtml:html
+/importxml/xhtml:html/jcr:primaryType=nt:unstructured
+/importxml/xhtml:html/xhtml:head
+/importxml/xhtml:html/xhtml:head/jcr:primaryType=nt:unstructured
+/importxml/xhtml:html/xhtml:head/xhtml:title
+/importxml/xhtml:html/xhtml:head/xhtml:title/jcr:primaryType=nt:unstructured
+/importxml/xhtml:html/xhtml:head/xhtml:title/jcr:xmltext
+/importxml/xhtml:html/xhtml:head/xhtml:title/jcr:xmltext/jcr:primaryType=nt:unstructured
+/importxml/xhtml:html/xhtml:head/xhtml:title/jcr:xmltext/jcr:xmlcharacters=Three Namespaces
+/importxml/xhtml:html/xhtml:body
+/importxml/xhtml:html/xhtml:body/jcr:primaryType=nt:unstructured
+/importxml/xhtml:html/xhtml:body/xhtml:h1
+/importxml/xhtml:html/xhtml:body/xhtml:h1/jcr:primaryType=nt:unstructured
+/importxml/xhtml:html/xhtml:body/xhtml:h1/align=center
+/importxml/xhtml:html/xhtml:body/xhtml:h1/jcr:xmltext
+/importxml/xhtml:html/xhtml:body/xhtml:h1/jcr:xmltext/jcr:primaryType=nt:unstructured
+/importxml/xhtml:html/xhtml:body/xhtml:h1/jcr:xmltext/jcr:xmlcharacters=An Ellipse and a Rectangle
+/importxml/xhtml:html/xhtml:body/svg:svg
+/importxml/xhtml:html/xhtml:body/svg:svg/jcr:primaryType=nt:unstructured
+/importxml/xhtml:html/xhtml:body/svg:svg/width=12cm
+/importxml/xhtml:html/xhtml:body/svg:svg/height=10cm
+.
+.
+.
+</PRE>
+</DIV></DIV>
+        </DIV>
+        <DIV id="end"></DIV>
+      </DIV>
+      <DIV id="footer">
+        <P>
+          &copy; 2004-2010 The Apache Software Foundation.
+          - <A href="http://jackrabbit.apache.org/privacy-policy.html">Privacy Policy</A> -
+          [<A href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=69056">edit this page</A>]
+          <BR>
+          Apache Jackrabbit, Jackrabbit, Apache, the Apache feather logo, and the Apache
+          Jackrabbit project logo are trademarks of The Apache Software Foundation.
+        </P>
+      </DIV>
+    </DIV>
+<!-- JCR- 1315: Add Google Analytics to Jackrabbit web site -->
+<SCRIPT type="text/javascript">
+var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
+document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
+</SCRIPT>
+<SCRIPT type="text/javascript">
+var pageTracker = _gat._getTracker("UA-837900-2");
+pageTracker._initData();
+pageTracker._trackPageview();
+</SCRIPT>
+  </BODY>
+</HTML>

Added: websites/staging/jackrabbit/trunk/content/JCR/first-hops.html
==============================================================================
--- websites/staging/jackrabbit/trunk/content/JCR/first-hops.html (added)
+++ websites/staging/jackrabbit/trunk/content/JCR/first-hops.html Mon Dec 31 12:40:56 2012
@@ -0,0 +1,712 @@
+
+<!-- 
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE- 2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License. 
+-->
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<HTML>
+  <HEAD>
+    <TITLE>First Hops</TITLE>
+    <LINK type="text/css" rel="stylesheet" href="http://jackrabbit.apache.org/style/site.css">
+  <META http-equiv="Content-Type" content="text/html;charset=UTF-8"></HEAD>
+  <BODY>
+    <DIV id="page">
+      <DIV id="header">
+        <P id="jcr"><A href="http://jackrabbit.apache.org/"><IMG src="http://jackrabbit.apache.org/style/jlogo.gif" alt="Apache Jackrabbit" height="100" width="336"></A></P>
+        <P id="asf"><A href="http://www.apache.org/"><IMG src="http://jackrabbit.apache.org/style/asf-logo.gif" alt="Apache Software Foundation" height="100" width="387"></A></P>
+      </DIV>
+      <DIV id="body">
+        <DIV id="navigation">
+  <UL>
+	<LI>Apache Jackrabbit
+	<UL>
+		<LI><A href="welcome-to-apache-jackrabbit.html" title="Welcome to Apache Jackrabbit">Welcome</A></LI>
+		<LI><A href="downloads.html" title="Downloads">Downloads</A></LI>
+		<LI><A href="frequently-asked-questions.html" title="Frequently Asked Questions">FAQ</A></LI>
+		<LI><A href="http://wiki.apache.org/jackrabbit/FrontPage" class="external-link">Jackrabbit Wiki</A></LI>
+		<LI><A href="jackrabbit-history.html" title="Jackrabbit History">Jackrabbit History</A></LI>
+	</UL>
+	</LI>
+	<LI>Documentation
+	<UL>
+		<LI><A href="getting-started-with-apache-jackrabbit.html" title="Getting Started with Apache Jackrabbit">Getting Started</A></LI>
+		<LI><A href="standalone-server.html" title="Standalone Server">Standalone Server</A></LI>
+		<LI><A href="jackrabbit-components.html" title="Jackrabbit Components">Jackrabbit Components</A></LI>
+		<LI><A href="" title="First Hops">First Hops</A></LI>
+		<LI><A href="jcr-api.html" title="JCR & API">JCR &amp; API</A></LI>
+		<LI><A href="jackrabbit-architecture.html" title="Jackrabbit Architecture">Jackrabbit Architecture</A></LI>
+		<LI><A href="deployment-models.html" title="Deployment Models">Deployment Models</A></LI>
+		<LI><A href="jackrabbit-configuration.html" title="Jackrabbit Configuration">Jackrabbit Configuration</A></LI>
+		<LI><A href="node-types.html" title="Node Types">Node Types</A></LI>
+		<LI><A href="object-content-mapping.html" title="Object Content Mapping">Object Content Mapping</A></LI>
+	</UL>
+	</LI>
+	<LI>Development
+	<UL>
+		<LI><A href="jackrabbit-team.html" title="Jackrabbit Team">Jackrabbit Team</A></LI>
+		<LI><A href="jackrabbit-roadmap.html" title="Jackrabbit Roadmap">Jackrabbit Roadmap</A></LI>
+		<LI><A href="building-jackrabbit.html" title="Building Jackrabbit">Building Jackrabbit</A></LI>
+		<LI><A href="mailing-lists.html" title="Mailing Lists">Mailing Lists</A></LI>
+		<LI><A href="issue-tracker.html" title="Issue Tracker">Issue Tracker</A></LI>
+		<LI><A href="source-repository.html" title="Source Repository">Source Repository</A></LI>
+		<LI><A href="continuous-integration.html" title="Continuous Integration">Continuous Integration</A></LI>
+		<LI><A href="website.html" title="Website">Website</A></LI>
+		<LI><A href="creating-releases.html" title="Creating Releases">Creating Releases</A></LI>
+		<LI><A href="supporting-software-attribution.html" title="Supporting software attribution">Attribution</A></LI>
+	</UL>
+	</LI>
+	<LI>Apache Software Foundation
+	<UL>
+		<LI><A href="http://www.apache.org/foundation/how-it-works.html" class="external-link">Introduction</A></LI>
+		<LI><A href="http://www.apache.org/foundation/sponsorship.html" class="external-link">Sponsorship</A></LI>
+		<LI><A href="http://www.apache.org/foundation/thanks.html" class="external-link">Current Sponsors</A></LI>
+	</UL>
+	</LI>
+</UL>
+        </DIV>
+        <DIV id="content">
+          <H1>First Hops</H1>
+  <P>Welcome to your first hops into the world of Jackrabbit! This introduction gives you a hands-on experience with Jackrabbit and the JCR API. Once you have finished hopping through this document, you should be all set to continue on your own with the official JCR specification and the documentation on this site. </P>
+
+<H2><A name="FirstHops-Hop0%3AGettingstarted"></A>Hop 0: Getting started </H2>
+
+<P>The easiest way to get started with Jackrabbit is to <A href="downloads.html" title="Downloads">download</A> the runnable <A href="standalone-server.html" title="Standalone Server">Standalone Server</A> jar. In addition to running it, you can also put it in your classpath to quickly access all the classes and interfaces you need below. Alternatively, if you use the <A href="http://maven.apache.org/" class="external-link">Apache Maven</A> build system (which we recommend), you can set up your first hops project with the following dependenecies. </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-xml"> 
+<SPAN class="code-tag">&lt;dependencies&gt;</SPAN> 
+<SPAN class="code-tag"><SPAN class="code-comment">&lt;!-- The JCR API --&gt;</SPAN></SPAN> 
+<SPAN class="code-tag">&lt;dependency&gt;</SPAN> 
+<SPAN class="code-tag">&lt;groupId&gt;</SPAN>javax.jcr<SPAN class="code-tag">&lt;/groupId&gt;</SPAN> 
+<SPAN class="code-tag">&lt;artifactId&gt;</SPAN>jcr<SPAN class="code-tag">&lt;/artifactId&gt;</SPAN> 
+<SPAN class="code-tag">&lt;version&gt;</SPAN>2.0<SPAN class="code-tag">&lt;/version&gt;</SPAN> 
+<SPAN class="code-tag">&lt;/dependency&gt;</SPAN> 
+
+<SPAN class="code-tag"><SPAN class="code-comment">&lt;!-- Jackrabbit content repository --&gt;</SPAN></SPAN> 
+<SPAN class="code-tag">&lt;dependency&gt;</SPAN> 
+<SPAN class="code-tag">&lt;groupId&gt;</SPAN>org.apache.jackrabbit<SPAN class="code-tag">&lt;/groupId&gt;</SPAN> 
+<SPAN class="code-tag">&lt;artifactId&gt;</SPAN>jackrabbit-core<SPAN class="code-tag">&lt;/artifactId&gt;</SPAN> 
+<SPAN class="code-tag">&lt;version&gt;</SPAN>2.2.4<SPAN class="code-tag">&lt;/version&gt;</SPAN> 
+<SPAN class="code-tag">&lt;/dependency&gt;</SPAN> 
+
+<SPAN class="code-tag"><SPAN class="code-comment">&lt;!-- Use Log4J for logging --&gt;</SPAN></SPAN> 
+<SPAN class="code-tag">&lt;dependency&gt;</SPAN> 
+<SPAN class="code-tag">&lt;groupId&gt;</SPAN>org.slf4j<SPAN class="code-tag">&lt;/groupId&gt;</SPAN> 
+<SPAN class="code-tag">&lt;artifactId&gt;</SPAN>slf4j-log4j12<SPAN class="code-tag">&lt;/artifactId&gt;</SPAN> 
+<SPAN class="code-tag">&lt;version&gt;</SPAN>1.5.11<SPAN class="code-tag">&lt;/version&gt;</SPAN> 
+<SPAN class="code-tag">&lt;/dependency&gt;</SPAN> 
+<SPAN class="code-tag">&lt;/dependencies&gt;</SPAN> 
+</PRE>
+</DIV></DIV> 
+
+<DIV class="panelMacro"><TABLE class="noteMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD>You probably have an error in your classpath settings if you get a <TT>ClassNotFoundException</TT> message when trying to compile or run the examples below.</TD></TR></TABLE></DIV> 
+
+<H2><A name="FirstHops-Hop1%3ALoggingintoJackrabbit"></A>Hop 1: Logging in to Jackrabbit </H2>
+
+<P>So let's get started. As a warm-up we'll create a Jackrabbit content repository and start a login session for accessing it. The full example application that does this is shown below, with line-by-line explanations following shortly after. </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;"><B>FirstHop.java</B></DIV><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+<SPAN class="code-keyword">import</SPAN> javax.jcr.Repository; 
+<SPAN class="code-keyword">import</SPAN> javax.jcr.Session; 
+<SPAN class="code-keyword">import</SPAN> org.apache.jackrabbit.core.TransientRepository; 
+
+/** 
+* First hop example. Logs in to a content repository and prints a 
+* status message. 
+*/ 
+<SPAN class="code-keyword">public</SPAN> class FirstHop { 
+
+/** 
+* The main entry point of the example application. 
+* 
+* @param args command line arguments (ignored) 
+* @<SPAN class="code-keyword">throws</SPAN> Exception <SPAN class="code-keyword">if</SPAN> an error occurs 
+*/ 
+<SPAN class="code-keyword">public</SPAN> <SPAN class="code-keyword">static</SPAN> void main(<SPAN class="code-object">String</SPAN>[] args) <SPAN class="code-keyword">throws</SPAN> Exception { 
+Repository repository = <SPAN class="code-keyword">new</SPAN> TransientRepository(); 
+Session session = repository.login(); 
+<SPAN class="code-keyword">try</SPAN> { 
+<SPAN class="code-object">String</SPAN> user = session.getUserID(); 
+<SPAN class="code-object">String</SPAN> name = repository.getDescriptor(Repository.REP_NAME_DESC); 
+<SPAN class="code-object">System</SPAN>.out.println( 
+<SPAN class="code-quote">&quot;Logged in as &quot;</SPAN> + user + <SPAN class="code-quote">&quot; to a &quot;</SPAN> + name + <SPAN class="code-quote">&quot; repository.&quot;</SPAN>); 
+} <SPAN class="code-keyword">finally</SPAN> { 
+session.logout(); 
+} 
+} 
+
+} 
+</PRE>
+</DIV></DIV> 
+
+<P>You can also download the source file as FirstHop.java. If you have your classpath set up, you can compile the application with javac FirstHop.java and run it with java FirstHop to get the following output. </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+Logged in as anonymous to a Jackrabbit repository. 
+</PRE>
+</DIV></DIV> 
+
+<P>In addition to producing the above status line the application copies a default repository configuration file to repository.xml and creates an initial Jackrabbit content repository in the repository subdirectory. You can use the system properties <TT>org.apache.jackrabbit.repository.conf</TT> and <TT>org.apache.jackrabbit.repository.home</TT> to set alternative configuration file and repository directory locations. </P>
+
+<P>Read on for a detailed breakdown of the FirstHop application: </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+<SPAN class="code-keyword">import</SPAN> javax.jcr.Repository; 
+<SPAN class="code-keyword">import</SPAN> javax.jcr.Session; 
+</PRE>
+</DIV></DIV> 
+
+<P>The JCR API interfaces are located in the javax.jcr package found in the jcr-1.0.jar library. The promise of the JCR API is that if you only use these interfaces in your content application, it should remain mostly independent of the underlying content repository implementation. </P>
+
+<P>The <A href="http://www.day.com/maven/javax.jcr/javadocs/jcr-2.0/javax/jcr/Repository.html?is-external=true" class="external-link">Repository</A> interface represents a given content repository instance and the <A href="http://www.day.com/maven/javax.jcr/javadocs/jcr-2.0/javax/jcr/Session.html?is-external=true" class="external-link">Session</A> interface represents a single login session for accessing the repository. A session is needed to access any content within a repository. </P>
+
+<P>Note that a Session instance is not guaranteed to be thread-safe so you should start multiple sessions if you need to access repository content simultaneously from different threads. This is especially important for things like web applications. </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+<SPAN class="code-keyword">import</SPAN> org.apache.jackrabbit.core.TransientRepository; 
+</PRE>
+</DIV></DIV> 
+
+<P>The best practice for deploying Jackrabbit is to use JNDI or some other configuration mechanism in a container environment to keep the application code free of direct Jackrabbit dependencies, but since we are creating a simple standalone application we can take a shortcut by using the <A href="http://jackrabbit.apache.org/api/2.2/org/apache/jackrabbit/core/TransientRepository.html" class="external-link">TransientRepository</A> class from Jackrabbit core. </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+<SPAN class="code-keyword">public</SPAN> class FirstHop 
+<SPAN class="code-keyword">public</SPAN> <SPAN class="code-keyword">static</SPAN> void main(<SPAN class="code-object">String</SPAN>[] args) <SPAN class="code-keyword">throws</SPAN> Exception 
+</PRE>
+</DIV></DIV> 
+
+<P>The FirstHop example is a simple standalone application that fits nicely in the main() method and lets the JVM take care of the possible exceptions. More substantial content applications could also be written as web application or EJB components with different setup and error handling patterns. </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+Repository repository = <SPAN class="code-keyword">new</SPAN> TransientRepository(); 
+</PRE>
+</DIV></DIV> 
+
+<P>The TransientRepository class implements the JCR Repository interface, so you can simply assign a TransientRepository instance to a Repository variable. The default constructor contains a utility feature that will take care of the initial configuration and repository construction when the first session is started. Thus there is no need for manual configuration for now unless you want direct control over the repository setup. </P>
+
+<P>The TransientRepository implementation will automatically initialize the content repository when the first session is started and shut it down when the last session is closed. Thus there is no need for explicit repository shutdown as long as all sessions are properly closed. Note that a Jackrabbit repository directory contains a lock file that prevents it from being accessed simultaneously by multiple processes. You will see repository startup exceptions caused by the lock file if you fail to properly close all sessions or otherwise shut down the repository before leaving the process that accesses a repository. Normally you can just manually remove the lock file in such cases but such cases always present a chance of repository corruption especially if you use a non-transactional persistence manager. </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+Session session = repository.login(); 
+</PRE>
+</DIV></DIV> 
+
+<P>The default Repository.login() method starts a repository session using the default workspace and no user credentials. Jackrabbit tries to use the Java Authentication and Authorization Service (JAAS) configuration in such cases, but defaults to the anonymous user if a JAAS Subject is not found. </P>
+
+<P>Since we use the TransientRepository class as the Repository implementation, this step will also cause the repository to be initialized. </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+<SPAN class="code-keyword">try</SPAN> { ... } <SPAN class="code-keyword">finally</SPAN> { session.logout(); } 
+</PRE>
+</DIV></DIV> 
+
+<P>It is a good practice to properly release all acquired resources, and the JCR sessions are no exception. The try-finally idiom is a good way to ensure that a resource really gets released, as the release method gets called even if the intervening code throws an exception or otherwise jumps outside the scope (for example using a return, break, or continue statement). </P>
+
+<P>The Session.logout() method in the finally branch closes the session and since this is the only session we have started, the TransientRepository is automatically shut down. </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+<SPAN class="code-object">String</SPAN> user = session.getUserID(); 
+</PRE>
+</DIV></DIV> 
+
+<P>The username or identifier of the user associated with a session is available using the Session.getUserID() method. Jackrabbit returns &quot;anonymous&quot; by default. </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+<SPAN class="code-object">String</SPAN> name = repository.getDescriptor(Repository.REP_NAME_DESC); 
+</PRE>
+</DIV></DIV> 
+
+<P>Each content repository implementation publishes a number of string descriptors that describe the various implementation properties, like the implementation level and the supported optional JCR features. See the <A href="http://www.day.com/maven/javax.jcr/javadocs/jcr-2.0/javax/jcr/Repository.html?is-external=true" class="external-link">Repository</A> interface for a list of the standard repository descriptors. The REP_NAME_DESC descriptor contains the name of the repository implementation, in this case &quot;Jackrabbit&quot;. </P>
+
+<H2><A name="FirstHops-Hop2%3AWorkingwithcontent"></A>Hop 2: Working with content </H2>
+
+<P>The main function of a content repository is allow applications to store and retrieve content. The content in a JCR content repository consists of structured or unstructured data modeled as a hierarchy of nodes with properties that contain the actual data. </P>
+
+<P>The following example application first stores some content to the initially empty content repository, then retrieves the stored content and outputs it, and finally removes the stored content. </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;"><B>SecondHop.java</B></DIV><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+<SPAN class="code-keyword">import</SPAN> javax.jcr.Repository; 
+<SPAN class="code-keyword">import</SPAN> javax.jcr.Session; 
+<SPAN class="code-keyword">import</SPAN> javax.jcr.SimpleCredentials; 
+<SPAN class="code-keyword">import</SPAN> javax.jcr.Node; 
+<SPAN class="code-keyword">import</SPAN> org.apache.jackrabbit.core.TransientRepository; 
+
+/** 
+* Second hop example. Stores, retrieves, and removes example content. 
+*/ 
+<SPAN class="code-keyword">public</SPAN> class SecondHop { 
+
+/** 
+* The main entry point of the example application. 
+* 
+* @param args command line arguments (ignored) 
+* @<SPAN class="code-keyword">throws</SPAN> Exception <SPAN class="code-keyword">if</SPAN> an error occurs 
+*/ 
+<SPAN class="code-keyword">public</SPAN> <SPAN class="code-keyword">static</SPAN> void main(<SPAN class="code-object">String</SPAN>[] args) <SPAN class="code-keyword">throws</SPAN> Exception { 
+Repository repository = <SPAN class="code-keyword">new</SPAN> TransientRepository(); 
+Session session = repository.login( 
+<SPAN class="code-keyword">new</SPAN> SimpleCredentials(<SPAN class="code-quote">&quot;username&quot;</SPAN>, <SPAN class="code-quote">&quot;password&quot;</SPAN>.toCharArray())); 
+<SPAN class="code-keyword">try</SPAN> { 
+Node root = session.getRootNode(); 
+
+<SPAN class="code-comment">// Store content 
+</SPAN>Node hello = root.addNode(<SPAN class="code-quote">&quot;hello&quot;</SPAN>); 
+Node world = hello.addNode(<SPAN class="code-quote">&quot;world&quot;</SPAN>); 
+world.setProperty(<SPAN class="code-quote">&quot;message&quot;</SPAN>, <SPAN class="code-quote">&quot;Hello, World!&quot;</SPAN>); 
+session.save(); 
+
+<SPAN class="code-comment">// Retrieve content 
+</SPAN>Node node = root.getNode(<SPAN class="code-quote">&quot;hello/world&quot;</SPAN>); 
+<SPAN class="code-object">System</SPAN>.out.println(node.getPath()); 
+<SPAN class="code-object">System</SPAN>.out.println(node.getProperty(<SPAN class="code-quote">&quot;message&quot;</SPAN>).getString()); 
+
+<SPAN class="code-comment">// Remove content 
+</SPAN>root.getNode(<SPAN class="code-quote">&quot;hello&quot;</SPAN>).remove(); 
+session.save(); 
+} <SPAN class="code-keyword">finally</SPAN> { 
+session.logout(); 
+} 
+} 
+
+} 
+</PRE>
+</DIV></DIV> 
+
+<P>Like in the first hop, this example source is also available as SecondHop.java. You can also compile and run this class just like you did in the first hop example. Running this example should produce the following output: </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+/hello/world 
+Hello, World! 
+</PRE>
+</DIV></DIV> 
+
+<P>The basic structure of this example application is the same as in the First Hop example, so let's just walk through the differences: </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+<SPAN class="code-keyword">import</SPAN> javax.jcr.SimpleCredentials; 
+<SPAN class="code-keyword">import</SPAN> javax.jcr.Node; 
+</PRE>
+</DIV></DIV> 
+
+<P>These are two new classes we need for this example. The <A href="http://www.day.com/maven/javax.jcr/javadocs/jcr-2.0/javax/jcr/SimpleCredentials.html?is-external=true" class="external-link">SimpleCredentials</A> class is a simple implementation of the <A href="http://www.day.com/maven/javax.jcr/javadocs/jcr-2.0/javax/jcr/Credentials.html?is-external=true" class="external-link">Credentials</A> interface used for passing explicit user credentials to the Repository.login(Credentials) method. </P>
+
+<P>The <A href="http://www.day.com/maven/javax.jcr/javadocs/jcr-2.0/javax/jcr/Node.html?is-external=true" class="external-link">Node</A> interface is used to manage the content nodes in a repository. There is a related interface called <A href="http://www.day.com/maven/javax.jcr/javadocs/jcr-2.0/javax/jcr/Property.html?is-external=true" class="external-link">Property</A> for managing content properties, but in this example we use the Property interface only indirectly. </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+<SPAN class="code-keyword">new</SPAN> SimpleCredentials(<SPAN class="code-quote">&quot;username&quot;</SPAN>, <SPAN class="code-quote">&quot;password&quot;</SPAN>.toCharArray()) 
+</PRE>
+</DIV></DIV> 
+
+<P>As discussed in the First Hop example, the default Repository.login() method returns an anonymous read-only session in the Jackrabbit default configuration. To be able to store and remove content we need to create a session with write access, and to do that we need to pass some credentials to the </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+Repository.login(Credentials credentials) method. 
+</PRE>
+</DIV></DIV> 
+
+<P>The default Jackrabbit login mechanism accepts any username and password as valid credentials and returns a session with full write access. Thus we only need to construct and use a SimpleCredentials instance with some dummy username and password, in this case &quot;username&quot; and &quot;password&quot;. </P>
+
+<P>The SimpleCredentials constructor follows the JAAS convention of representing the username as a normal String, but the password as a character array, so we need to use the String.toCharArray() method to satisfy the constructor. </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+Node root = session.getRootNode(); 
+</PRE>
+</DIV></DIV> 
+
+<P>Each JCR session is associated with a workspace that contains a single node tree. A simple way to access the root node is to call the Session.getRootNode() method. Having a reference to the root node allows us to easily store and retrieve content in the current workspace. </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+Node hello = root.addNode(<SPAN class="code-quote">&quot;hello&quot;</SPAN>); 
+Node world = hello.addNode(<SPAN class="code-quote">&quot;world&quot;</SPAN>); 
+</PRE>
+</DIV></DIV> 
+
+<P>New content nodes can be added using the Node.addNode(String relPath) method. The method takes the name (or relative path) of the node to be added and creates the named node in the transient storage associated with the current session. Until the transient storage is persisted, the added node is only visible within the current session and not within any other session that is concurrently accessing the content repository. </P>
+
+<P>This code snippet creates two new nodes, called &quot;hello&quot; and &quot;world&quot;, with &quot;hello&quot; being a child of the root node and &quot;world&quot; a child of the &quot;hello&quot; node. </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+world.setProperty(<SPAN class="code-quote">&quot;message&quot;</SPAN>, <SPAN class="code-quote">&quot;Hello, World!&quot;</SPAN>); 
+</PRE>
+</DIV></DIV> 
+
+<P>To add some content to the structure created using the &quot;hello&quot; and &quot;world&quot; nodes, we use the Node.setProperty(String name, String value) method to add a string property called &quot;message&quot; to the &quot;world&quot; node. The value of the property is the string &quot;Hello, World!&quot;. </P>
+
+<P>Like the added nodes, also the property is first created in the transient storage associated with the current session. If the named property already exists, then this method will change the value of that property. </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+session.save(); 
+</PRE>
+</DIV></DIV> 
+
+<P>Even though the rest of our example would work just fine using only the transient storage of the single session, we'd like to persist the changes we've made so far. This way other sessions could also access the example content we just created. If you like, you could even split the example application into three pieces for respectively storing, retrieving, and removing the example content. Such a split would not work unless we persisted the changes we make. </P>
+
+<P>The Session.save() method persists all pending changes in the transient storage. The changes are written to the persistent repository storage and they become visible to all sessions accessing the same workspace. Without this call all changes will be lost forever when the session is closed. </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+Node node = root.getNode(<SPAN class="code-quote">&quot;hello/world&quot;</SPAN>); 
+</PRE>
+</DIV></DIV> 
+
+<P>Since we are still using the same session, we could use the existing hello and world node references to access the stored content, but let's pretend that we've started another session and want to retrieve the content that was previously stored. </P>
+
+<P>The Node.getNode(String relPath) method returns a reference to the node at the given path relative to this node. The path syntax follows common file system conventions: a forward slash separates node names, a single dot represents the current node, and a double dot the parent node. Thus the path &quot;hello/world&quot; identifies the &quot;world&quot; child node of the &quot;hello&quot; child node of the current node - in this case the root node. The end result is that the method returns a node instance that represents the same content node as the world instance created a few lines earlier. </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+<SPAN class="code-object">System</SPAN>.out.println(node.getPath()); 
+</PRE>
+</DIV></DIV> 
+
+<P>Each content node and property is uniquely identified by its absolute path within the workspace. The absolute path starts with a forward slash and contains all the names of the ancestor nodes in order before the name of the current node or property. </P>
+
+<P>The path of a node or property can be retrieved using the Item.getPath() method. The <A href="http://www.day.com/maven/javax.jcr/javadocs/jcr-2.0/javax/jcr/Item.html?is-external=true" class="external-link">Item</A> inteface is a superinterface of Node and Property, and contains all the functionality shared by nodes and properties. </P>
+
+<P>The node variable references the &quot;world&quot; node, so this statement will output the line &quot;/hello/world&quot;. </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+<SPAN class="code-object">System</SPAN>.out.println(node.getProperty(<SPAN class="code-quote">&quot;message&quot;</SPAN>).getString()); 
+</PRE>
+</DIV></DIV> 
+
+<P>Properties can be accessed using the Node.getProperty(String relPath) method that returns an instance of the <A href="http://www.day.com/maven/javax.jcr/javadocs/jcr-2.0/javax/jcr/Property.html?is-external=true" class="external-link">Property</A> interface that represents the property at the given path relative to the current node. In this case the &quot;message&quot; property is the one we created a few lines earlier. </P>
+
+<P>A JCR property can contain either a single or multiple values of a given type. There are property types for storing strings, numbers, dates, binary streams, node references, etc. We just want the single string value, so we use the Property.getString() method. The result of this statement is the line &quot;Hello, World!&quot; being outputted. </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+root.getNode(<SPAN class="code-quote">&quot;hello&quot;</SPAN>).remove(); 
+</PRE>
+</DIV></DIV> 
+
+<P>Nodes and properties can be removed using the Item.remove() method. The method removes the entire content subtree, so we only need to remove the topmost &quot;hello&quot; node to get rid of all the content we added before. </P>
+
+<P>Removals are first stored in the session-local transient storage, just like added and changed content. Like before, the transient changes need to be explicitly saved for the content to be removed from the persistent storage. </P>
+
+<H2><A name="FirstHops-Hop3%3AImportingcontent"></A>Hop 3: Importing content </H2>
+
+<P>TODO: Update to match the style of previous hops. </P>
+
+<P>To add content a bit more efficiently, you may want to try JCR's import facilities, such as Session.importXML. The following XML document by Elliotte Rusty Harold provides an interesting example that demonstrates a repository's namespace capabilities: </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;"><B>test.xml</B></DIV><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+&lt;xhtml:html xmlns:xhtml=<SPAN class="code-quote">&quot;http:<SPAN class="code-comment">//www.w3.org/1999/xhtml&quot;</SPAN> 
+</SPAN>xmlns:mathml=<SPAN class="code-quote">&quot;http:<SPAN class="code-comment">//www.w3.org/1998/<SPAN class="code-object">Math</SPAN>/MathML&quot;</SPAN>&gt; 
+</SPAN>&lt;xhtml:head&gt;&lt;xhtml:title&gt;Three Namespaces&lt;/xhtml:title&gt;&lt;/xhtml:head&gt; 
+&lt;xhtml:body&gt; 
+&lt;xhtml:h1 align=<SPAN class="code-quote">&quot;center&quot;</SPAN>&gt;An Ellipse and a Rectangle&lt;/xhtml:h1&gt; 
+&lt;svg:svg xmlns:svg=<SPAN class="code-quote">&quot;http:<SPAN class="code-comment">//www.w3.org/2000/svg&quot;</SPAN> 
+</SPAN>width=<SPAN class="code-quote">&quot;12cm&quot;</SPAN> height=<SPAN class="code-quote">&quot;10cm&quot;</SPAN>&gt; 
+&lt;svg:ellipse rx=<SPAN class="code-quote">&quot;110&quot;</SPAN> ry=<SPAN class="code-quote">&quot;130&quot;</SPAN> /&gt; 
+&lt;svg:rect x=<SPAN class="code-quote">&quot;4cm&quot;</SPAN> y=<SPAN class="code-quote">&quot;1cm&quot;</SPAN> width=<SPAN class="code-quote">&quot;3cm&quot;</SPAN> height=<SPAN class="code-quote">&quot;6cm&quot;</SPAN> /&gt; 
+&lt;/svg:svg&gt; 
+&lt;xhtml:p&gt;The equation <SPAN class="code-keyword">for</SPAN> ellipses&lt;/xhtml:p&gt; 
+&lt;mathml:math&gt; 
+&lt;mathml:apply&gt; 
+&lt;mathml:eq/&gt; 
+&lt;mathml:cn&gt; 1 &lt;/mathml:cn&gt; 
+&lt;mathml:apply&gt; 
+&lt;mathml:plus/&gt; 
+&lt;mathml:apply&gt; 
+&lt;mathml:divide/&gt; 
+&lt;mathml:apply&gt; 
+&lt;mathml:power/&gt; 
+&lt;mathml:ci&gt; x &lt;/mathml:ci&gt; 
+&lt;mathml:cn&gt; 2 &lt;/mathml:cn&gt; 
+&lt;/mathml:apply&gt; 
+&lt;mathml:apply&gt; 
+&lt;mathml:power/&gt; 
+&lt;mathml:ci&gt; a &lt;/mathml:ci&gt; 
+&lt;mathml:cn&gt; 2 &lt;/mathml:cn&gt; 
+&lt;/mathml:apply&gt; 
+&lt;/mathml:apply&gt; 
+&lt;mathml:apply&gt; 
+&lt;mathml:divide/&gt; 
+&lt;mathml:apply&gt; 
+&lt;mathml:power/&gt; 
+&lt;mathml:ci&gt; y &lt;/mathml:ci&gt; 
+&lt;mathml:cn&gt; 2 &lt;/mathml:cn&gt; 
+&lt;/mathml:apply&gt; 
+&lt;mathml:apply&gt; 
+&lt;mathml:power/&gt; 
+&lt;mathml:ci&gt; b &lt;/mathml:ci&gt; 
+&lt;mathml:cn&gt; 2 &lt;/mathml:cn&gt; 
+&lt;/mathml:apply&gt; 
+&lt;/mathml:apply&gt; 
+&lt;/mathml:apply&gt; 
+&lt;/mathml:apply&gt; 
+&lt;/mathml:math&gt; 
+&lt;xhtml:hr/&gt; 
+&lt;xhtml:p&gt;Last Modified January 10, 2002&lt;/xhtml:p&gt; 
+&lt;/xhtml:body&gt; 
+&lt;/xhtml:html&gt; 
+</PRE>
+</DIV></DIV> 
+
+<P>The third example application shown below will import the XML file called test.xml from the current directory into a new content repository node called importxml. Once the XML content is imported, the application recursively dumps the contents of the entire workspace using the simple dump() method. </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;"><B>ThirdHop.java</B></DIV><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+<SPAN class="code-keyword">import</SPAN> javax.jcr.*; 
+<SPAN class="code-keyword">import</SPAN> org.apache.jackrabbit.core.TransientRepository; 
+<SPAN class="code-keyword">import</SPAN> java.io.FileInputStream; 
+
+/** 
+* Third Jackrabbit example application. Imports an example XML file 
+* and outputs the contents of the entire workspace. 
+*/ 
+<SPAN class="code-keyword">public</SPAN> class ThirdHop { 
+
+/**
+* The main entry point of the example application.
+*
+* @param args command line arguments (ignored)
+* @<SPAN class="code-keyword">throws</SPAN> Exception <SPAN class="code-keyword">if</SPAN> an error occurs
+*/
+<SPAN class="code-keyword">public</SPAN> <SPAN class="code-keyword">static</SPAN> void main(<SPAN class="code-object">String</SPAN>[] args) <SPAN class="code-keyword">throws</SPAN> Exception { 
+Repository repository = <SPAN class="code-keyword">new</SPAN> TransientRepository(); 
+Session session = repository.login( 
+<SPAN class="code-keyword">new</SPAN> SimpleCredentials(<SPAN class="code-quote">&quot;username&quot;</SPAN>, <SPAN class="code-quote">&quot;password&quot;</SPAN>.toCharArray())); 
+<SPAN class="code-keyword">try</SPAN> { 
+Node root = session.getRootNode(); 
+
+<SPAN class="code-comment">// Import the XML file unless already imported 
+</SPAN><SPAN class="code-keyword">if</SPAN> (!root.hasNode(<SPAN class="code-quote">&quot;importxml&quot;</SPAN>)) { 
+<SPAN class="code-object">System</SPAN>.out.print(<SPAN class="code-quote">&quot;Importing xml... &quot;</SPAN>); 
+
+<SPAN class="code-comment">// Create an unstructured node under which to <SPAN class="code-keyword">import</SPAN> the XML 
+</SPAN>Node node = root.addNode(<SPAN class="code-quote">&quot;importxml&quot;</SPAN>, <SPAN class="code-quote">&quot;nt:unstructured&quot;</SPAN>); 
+
+<SPAN class="code-comment">// Import the file <SPAN class="code-quote">&quot;test.xml&quot;</SPAN> under the created node 
+</SPAN>FileInputStream xml = <SPAN class="code-keyword">new</SPAN> FileInputStream(<SPAN class="code-quote">&quot;test.xml&quot;</SPAN>);
+session.importXML( 
+node.getPath(), xml, ImportUUIDBehavior.IMPORT_UUID_CREATE_NEW); 
+xml.close();
+session.save(); 
+<SPAN class="code-object">System</SPAN>.out.println(<SPAN class="code-quote">&quot;done.&quot;</SPAN>); 
+} 
+
+<SPAN class="code-comment">//output the repository content
+</SPAN>dump(root); 
+} <SPAN class="code-keyword">finally</SPAN> { 
+session.logout(); 
+} 
+} 
+
+/** Recursively outputs the contents of the given node. */ 
+<SPAN class="code-keyword">private</SPAN> <SPAN class="code-keyword">static</SPAN> void dump(Node node) <SPAN class="code-keyword">throws</SPAN> RepositoryException { 
+<SPAN class="code-comment">// First output the node path 
+</SPAN><SPAN class="code-object">System</SPAN>.out.println(node.getPath()); 
+<SPAN class="code-comment">// Skip the virtual (and large!) jcr:system subtree 
+</SPAN><SPAN class="code-keyword">if</SPAN> (node.getName().equals(<SPAN class="code-quote">&quot;jcr:system&quot;</SPAN>)) { 
+<SPAN class="code-keyword">return</SPAN>; 
+} 
+
+<SPAN class="code-comment">// Then output the properties 
+</SPAN>PropertyIterator properties = node.getProperties(); 
+<SPAN class="code-keyword">while</SPAN> (properties.hasNext()) { 
+Property property = properties.nextProperty(); 
+<SPAN class="code-keyword">if</SPAN> (property.getDefinition().isMultiple()) { 
+<SPAN class="code-comment">// A multi-valued property, print all values 
+</SPAN>Value[] values = property.getValues(); 
+<SPAN class="code-keyword">for</SPAN> (<SPAN class="code-object">int</SPAN> i = 0; i &lt; values.length; i++) { 
+<SPAN class="code-object">System</SPAN>.out.println( 
+property.getPath() + <SPAN class="code-quote">&quot; = &quot;</SPAN> + values[i].getString()); 
+} 
+} <SPAN class="code-keyword">else</SPAN> { 
+<SPAN class="code-comment">// A single-valued property 
+</SPAN><SPAN class="code-object">System</SPAN>.out.println( 
+property.getPath() + <SPAN class="code-quote">&quot; = &quot;</SPAN> + property.getString()); 
+} 
+} 
+
+<SPAN class="code-comment">// Finally output all the child nodes recursively 
+</SPAN>NodeIterator nodes = node.getNodes(); 
+<SPAN class="code-keyword">while</SPAN> (nodes.hasNext()) { 
+dump(nodes.nextNode()); 
+} 
+} 
+
+} 
+</PRE>
+</DIV></DIV> 
+
+<P>Running the ThirdHop class should produce output like the following: </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+Importing XML... done. 
+/ 
+/jcr:primaryType=rep:root 
+/jcr:system 
+/importxml 
+/importxml/jcr:primaryType=nt:unstructured 
+/importxml/xhtml:html 
+/importxml/xhtml:html/jcr:primaryType=nt:unstructured 
+/importxml/xhtml:html/xhtml:head 
+/importxml/xhtml:html/xhtml:head/jcr:primaryType=nt:unstructured 
+/importxml/xhtml:html/xhtml:head/xhtml:title 
+/importxml/xhtml:html/xhtml:head/xhtml:title/jcr:primaryType=nt:unstructured 
+/importxml/xhtml:html/xhtml:head/xhtml:title/jcr:xmltext 
+/importxml/xhtml:html/xhtml:head/xhtml:title/jcr:xmltext/jcr:primaryType=nt:unstructured 
+/importxml/xhtml:html/xhtml:head/xhtml:title/jcr:xmltext/jcr:xmlcharacters=Three Namespaces 
+/importxml/xhtml:html/xhtml:body 
+/importxml/xhtml:html/xhtml:body/jcr:primaryType=nt:unstructured 
+/importxml/xhtml:html/xhtml:body/xhtml:h1 
+/importxml/xhtml:html/xhtml:body/xhtml:h1/jcr:primaryType=nt:unstructured 
+/importxml/xhtml:html/xhtml:body/xhtml:h1/align=center 
+/importxml/xhtml:html/xhtml:body/xhtml:h1/jcr:xmltext 
+/importxml/xhtml:html/xhtml:body/xhtml:h1/jcr:xmltext/jcr:primaryType=nt:unstructured 
+/importxml/xhtml:html/xhtml:body/xhtml:h1/jcr:xmltext/jcr:xmlcharacters=An Ellipse and a Rectangle 
+/importxml/xhtml:html/xhtml:body/svg:svg 
+/importxml/xhtml:html/xhtml:body/svg:svg/jcr:primaryType=nt:unstructured 
+/importxml/xhtml:html/xhtml:body/svg:svg/width=12cm 
+/importxml/xhtml:html/xhtml:body/svg:svg/height=10cm 
+. 
+. 
+. 
+</PRE>
+</DIV></DIV> 
+
+<P>This hop has a lot of similarities with the Second Hop example: we create a new session with write access by loggin in, next we insert data into the repository, this time by importing an xml file and finally we output the entire repository content.</P>
+
+<P>By now you should be familiar with loggin into a repository (Repository.login), creating a new node (Node.addNode) under the repository root (Session.getRootNode) and saving the session so that our changes are persisted (Session.save).</P>
+
+<P>Let us look at the new methods used in this example, how to import xml content:</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+session.importXML(node.getPath(), xml, ImportUUIDBehavior.IMPORT_UUID_CREATE_NEW);
+</PRE>
+</DIV></DIV> 
+
+<P>This deserializes an XML document and adds the resulting item subgraph as a child of the node at the provided path.</P>
+
+<P>The flag <A href="http://www.day.com/maven/javax.jcr/javadocs/jcr-2.0/javax/jcr/ImportUUIDBehavior.html?is-external=true" class="external-link">ImportUUIDBehavior</A> governs how the identifiers of incoming nodes are handled. There are four options: </P>
+<UL>
+	<LI>ImportUUIDBehavior.IMPORT_UUID_CREATE_NEW: Incoming nodes are added in the same way that new node is added with Node.addNode. That is, they are either assigned newly created identifiers upon addition or upon save. In either case, identifier collisions will not occur.</LI>
+</UL>
+
+
+<UL>
+	<LI>ImportUUIDBehavior.IMPORT_UUID_COLLISION_REMOVE_EXISTING: If an incoming node has the same identifier as a node already existing in the workspace then the already existing node (and its subgraph) is removed from wherever it may be in the workspace before the incoming node is added. Note that this can result in nodes &quot;disappearing&quot; from locations in the workspace that are remote from the location to which the incoming subgraph is being written. Both the removal and the new addition will be dispatched on save.</LI>
+</UL>
+
+
+<UL>
+	<LI>ImportUUIDBehavior.IMPORT_UUID_COLLISION_REPLACE_EXISTING: If an incoming node has the same identifier as a node already existing in the workspace, then the already-existing node is replaced by the incoming node in the same position as the existing node. Note that this may result in the incoming subgraph being disaggregated and &quot;spread around&quot; to different locations in the workspace. In the most extreme case this behavior may result in no node at all being added as child of parentAbsPath. This will occur if the topmost element of the incoming XML has the same identifier as an existing node elsewhere in the workspace. The change will be dispatched on save.</LI>
+</UL>
+
+
+<UL>
+	<LI>ImportUUIDBehavior.IMPORT_UUID_COLLISION_THROW: If an incoming node has the same identifier as a node already existing in the workspace then an ItemExistsException is thrown.</LI>
+</UL>
+
+
+
+<P>Another interesting method is </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+void dump(Node node)
+</PRE>
+</DIV></DIV> 
+
+<P>This can be used as an example of how to do a recursive traversal of all the repository, and check the properties of each node. </P>
+
+<P>Notice how we have to pay special attention to the multi-value properties, beacuse that impacts the way we use them:</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+property.getDefinition().isMultiple()
+</PRE>
+</DIV></DIV> 
+
+<P>if this yelds true, then we are dealing with an array of values:</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+Value[] values = property.getValues();
+</PRE>
+</DIV></DIV> 
+
+<P>or else, we can use the provided api shortcuts, to get the desired value:</P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+property.getString()
+</PRE>
+</DIV></DIV> 
+
+<P>which is equivalent to </P>
+
+<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
+<PRE class="code-java"> 
+property.getValue().getString()
+</PRE>
+</DIV></DIV> 
+
+<P>A very good entry point for utilities related code examples is <A href="http://jackrabbit.apache.org/api/2.2/org/apache/jackrabbit/commons/JcrUtils.html" class="external-link">JcrUtils</A>.</P>
+        </DIV>
+        <DIV id="end"></DIV>
+      </DIV>
+      <DIV id="footer">
+        <P>
+          &copy; 2004-2010 The Apache Software Foundation.
+          - <A href="http://jackrabbit.apache.org/privacy-policy.html">Privacy Policy</A> -
+          [<A href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=75343">edit this page</A>]
+          <BR>
+          Apache Jackrabbit, Jackrabbit, Apache, the Apache feather logo, and the Apache
+          Jackrabbit project logo are trademarks of The Apache Software Foundation.
+        </P>
+      </DIV>
+    </DIV>
+<!-- JCR- 1315: Add Google Analytics to Jackrabbit web site -->
+<SCRIPT type="text/javascript">
+var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
+document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
+</SCRIPT>
+<SCRIPT type="text/javascript">
+var pageTracker = _gat._getTracker("UA-837900-2");
+pageTracker._initData();
+pageTracker._trackPageview();
+</SCRIPT>
+  </BODY>
+</HTML>



Mime
View raw message