DNA SVN: r1584 - in trunk/docs: gettingstarted/src/main/docbook/en-US/content and 2 other directories.
by dna-commits@lists.jboss.org
Author: rhauch
Date: 2010-01-10 10:56:55 -0500 (Sun, 10 Jan 2010)
New Revision: 1584
Modified:
trunk/docs/gettingstarted/src/main/docbook/en-US/content/downloading_and_running.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/introduction.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/repository_example.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/sequencer_example.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/use_cases.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/custom.dtd
trunk/docs/reference/src/main/docbook/en-US/content/core/connector.xml
trunk/docs/reference/src/main/docbook/en-US/custom.dtd
Log:
Merge branch 'dna-621'
Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/downloading_and_running.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/downloading_and_running.xml 2010-01-10 07:57:11 UTC (rev 1583)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/downloading_and_running.xml 2010-01-10 15:56:55 UTC (rev 1584)
@@ -35,7 +35,7 @@
with a JCR repository to automatically sequence changing content to extract useful information. So read on to get the simple
application running.
</para>
- <para>JBoss DNA uses Maven 2 for its build system, as is this example. Using Maven 2 has several advantages, including
+ <para>JBoss DNA uses Maven 2 for its build system, as does this example. Using Maven 2 has several advantages, including
the ability to manage dependencies. If a library is needed, Maven automatically finds and downloads that library, plus
everything that library needs. This means that it's very easy to build the examples - or even create a maven project that
depends on the JBoss DNA JARs.</para>
Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/introduction.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/introduction.xml 2010-01-10 07:57:11 UTC (rev 1583)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/introduction.xml 2010-01-10 15:56:55 UTC (rev 1584)
@@ -131,14 +131,14 @@
<para>
As we'll see in the <link linkend="use_cases">next chapter</link>, the ability of JBoss DNA to
federate, integrate, and sequence information make JBoss DNA a powerful asset and tool.
- Then <link linkend="using_dna">Chapter 3</link> will show that once a JBoss DNA repository is set up, application see
- JBoss DNA just as another JCR <code>javax.jcr.Repository</code> instance and uses the standard JCR API to obtain a <code>javax.jcr.Session</code>
+ Then <link linkend="using_dna">Chapter 3</link> will show that once a JBoss DNA repository is set up, applications see
+ JBoss DNA just as another JCR <code>javax.jcr.Repository</code> instance and use the standard JCR API to obtain a <code>javax.jcr.Session</code>
and work with the content.
</para>
<para>
<link linkend="downloading_and_running">Chapter 4</link> walks you through downloading
and building the JBoss DNA examples, while <link linkend="sequencer_example">Chapter 5</link>
- and <link linkend="repository_example">Chapter 6</link> will run these very simple examples and walking through code.
+ and <link linkend="repository_example">Chapter 6</link> will run these very simple examples and walk through their code.
<link linkend="conclusion">Chapter 7</link> wraps things up with a discussion about the future of JBoss DNA
and what you can do next to start using JBoss DNA in your own applications.
</para>
Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/repository_example.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/repository_example.xml 2010-01-10 07:57:11 UTC (rev 1583)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/repository_example.xml 2010-01-10 15:56:55 UTC (rev 1584)
@@ -39,7 +39,7 @@
<sect1 id="running_repository_example">
<title>Running the repository example</title>
<para>The repository example consists of a client application that sets up three DNA repositories (named "Cars", "Airplanes", and "UFOs") and
- a federated repository ("Vehicles") that dynamically federates the information from the other two repositories.
+ a federated repository ("Vehicles") that dynamically federates the information from the other three repositories.
The client application allows you to interactively navigate each of these repositories just as you would navigate the
directory structure on a file system.</para>
<para>This collection of repositories is shown in the following figure:
@@ -48,7 +48,7 @@
<graphic align="center" scale="60" fileref="example-repositories.png"/>
</figure>
The "Cars" repository is an in-memory repository (using the In-Memory repository connector), the "Aircraft" repository is a JPA repository
- (although it points to an in-memory HSQL database using the JPA repository connector), and the "UFOs" repository is
+ (using an in-memory HSQL database using the JPA repository connector), and the "UFOs" repository is
a file system repository (using the File System repository connector). The federated "Vehicles" repository
content is federated from the other repositories and cached into the "Cache" repository. This is shown in the following figure:
<figure id="example-federated-repository">
@@ -105,6 +105,7 @@
</para>
<para>You can also choose to navigate the "Vehicles" repository, which projects the "Cars" repository content under the
<code>/Vehicles/Cars</code> node, the "Airplanes" content under the <code>/Vehicles/Airplanes</code> branch,
+ the "UFOs" content under the <code>/Vehicles/UFOs</code> branch,
and the "Configuration" content under <code>/dna:system</code>.
</para>
<para>Try using the client to walk the different repositories. And while this is a contrived application, it does demonstrate
@@ -215,19 +216,27 @@
</listitem>
</itemizedlist>
<para>As an example, consider that we want JBoss DNA to give us access through JCR to the schema information contained in a
- relational databases. We first have to develop a connector that allows us to interact with relational databases using JDBC.
- That connector would contain a <code>JdbcRepositorySource</code> Java class that implements &RepositorySource;,
+ relational database. We first have to develop a connector that allows us to interact with relational databases using JDBC.
+ That connector would contain a &JdbcMetadataSource; Java class that implements &RepositorySource;,
and that has all of the various JavaBean properties for setting the name of the driver class, URL, username, password,
- and other properties. (Or we might have a JavaBean property that defines the JNDI name where we can find a JDBC
- <code>DataSource</code> instance pointing to our JDBC database.)
+ and other properties. If we add a JavaBean property defining the JNDI name, our connector could look in JNDI to find a JDBC
+ <code>DataSource</code> instance, perhaps already configured to use connection pools.
</para>
+ <note>
+ <para>
+ Of course, before you develop a connector, you should probably check the
+ <ulink url="http://docs.jboss.org/jbossdna/latest/manuals/reference/html/provied-conn...">list of connectors</ulink> JBoss DNA already provides out of the box.
+ With this latest release, JBoss DNA already includes this JDBC metadata connector! And we're always interested in new
+ connectors and new contributors, so please consider developing your custom connector as part of JBoss DNA.
+ </para>
+ </note>
<para>So with this very high-level summary, let's dive a little deeper and look at the repository example.</para>
</sect1>
<sect1 id="example_repository_application_review">
<title>Reviewing the example repository application</title>
<para>Recall that the example repository application consists of a client application that sets up a repository service and the
repositories defined in a configuration repository, allowing the user to pick a repository and interactively navigate
- the selected repository. Several repositories are set up, including several in-memory repositories and one federated repository
+ the selected repository. Several repositories are set up, including several standalone repositories and one federated repository
that dynamically federates the content from the other repositories.</para>
<para>
The example is comprised of 2 classes and 1 interface, located in the <code>src/main/java</code> directory:</para>
@@ -238,8 +247,8 @@
]]></programlisting>
<para><code>RepositoryClient</code> is the class that contains the main application. It uses an instance of the
<code>UserInterface</code> interface to methods that will be called at runtime to obtain information about the
- files that are imported into the in-memory repositories and the JAAS <code>CallbackHandler</code> implementation
- that will be used by JAAS to prompt the user for authentication information. Finally, the <code>ConsoleInput</code>
+ files that are imported into the standalone repositories and the JAAS <code>CallbackHandler</code> implementation
+ that will be used by JAAS to collect the authentication information. Finally, the <code>ConsoleInput</code>
is an implementation of this that creates a text user interface, allowing the user to operate the client from the command-line.
We can easily create a graphical implementation of <code>UserInterface</code> at a later date, or we can also create a mock
implementation for testing purposes that simulates a user entering data. This allows us to check the behavior of the client
@@ -312,9 +321,10 @@
...
- // For this example, we're using a couple of in-memory repositories (including one for the configuration repository).
- // Normally, these would exist already and would simply be accessed. But in this example, we're going to
- // populate these repositories here by importing from files. First do the configuration repository ...
+ // For this example, we're using a couple of in-memory repositories (including one for the
+ // configuration repository). Normally, these would exist already and would simply be accessed.
+ // But in this example, we're going to populate these repositories here by importing from files.
+ // First do the configuration repository ...
String location = this.userInterface.getLocationOfRepositoryFiles();
// Now import the content for the two in-memory repositories ...
@@ -334,7 +344,8 @@
done to keep the example simple.
</para>
<para>
- The <code>shutdown()</code> method of the example then logs out and requests the <code>JcrEngine</code> instance shuts down and, since that may take
+ The <code>shutdown()</code> method of the example then logs out and requests that the <code>JcrEngine</code> instance
+ shut down and, since that may take
a few moments (if there are any ongoing operations or enqueued activities) awaits for it to complete the shutdown.
</para>
<programlisting role="JAVA"><![CDATA[
Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/sequencer_example.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/sequencer_example.xml 2010-01-10 07:57:11 UTC (rev 1583)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/sequencer_example.xml 2010-01-10 15:56:55 UTC (rev 1584)
@@ -48,9 +48,6 @@
<para>an MP3 sequencer that extracts the ID3 metadata (e.g., the author, title, album, year and comment)</para>
</listitem>
<listitem>
- <para>an MP3 sequencer that extracts the ID3 metadata (e.g., the author, title, album, year and comment)</para>
- </listitem>
- <listitem>
<para>a Java source code sequencer that extracts the structure of Java classes by parsing the source code</para>
</listitem>
<listitem>
@@ -171,8 +168,8 @@
<para><code>SequencingClient</code> is the class that contains the main application. <code>ContentInfo</code> is a simple class
that encapsulate metadata generated by the sequencers and accessed by this example application, and there are two subclasses:
<code>MediaInfo</code> encapsulates metadata about media (image and MP3) files, while <code>JavaInfo</code> is a subclass
- encapsulating information about a Java class. The client accesses the content from the repository and represent the
- information using instances of <code>ContentInfo</code> (and its subclasses) and then passing them to the <code>UserInterface</code>.
+ encapsulating information about a Java class. The client accesses the content from the repository and represents the
+ information using instances of <code>ContentInfo</code> (and its subclasses) and then passes them to the <code>UserInterface</code>.
<code>UserInterface</code> is an interface with methods that will be called at runtime to
request data from the user. <code>ConsoleInput</code> is an implementation of this that creates a text user interface,
allowing the user to operate the client from the command-line. We can easily create a graphical implementation of
@@ -195,7 +192,8 @@
String repositoryId = "content";
String workspaceName = "default";
JcrConfiguration config = new JcrConfiguration();
-// Set up the in-memory source where we'll upload the content and where the sequenced output will be stored ...
+// Set up the in-memory source where we'll upload the content and where the sequenced output will
+// be stored ...
config.repositorySource("store")
.usingClass(InMemoryRepositorySource.class)
.setDescription("The repository for our content")
@@ -209,7 +207,8 @@
.usingClass("org.jboss.dna.sequencer.image.ImageMetadataSequencer")
.loadedFromClasspath()
.setDescription("Sequences image files to extract the characteristics of the image")
- .sequencingFrom("//(*.(jpg|jpeg|gif|bmp|pcx|png|iff|ras|pbm|pgm|ppm|psd)[*])/jcr:content[@jcr:data]")
+ .sequencingFrom(
+ "//(*.(jpg|jpeg|gif|bmp|pcx|png|iff|ras|pbm|pgm|ppm|psd)[*])/jcr:content[@jcr:data]")
.andOutputtingTo("/images/$1");
// Set up the MP3 sequencer ...
config.sequencer("MP3 Sequencer")
@@ -397,7 +396,7 @@
<title>What's next</title>
<para>
This chapter walked through running the sequencer example and looked at the example code. With the sequencer client, you could upload files into a
- JCR repository, while JBoss DNA automatically sequenced the image, MP3, or Java source files you uploaded, extracted the metadata from the
+ JCR repository, while JBoss DNA automatically sequenced the source files you uploaded, extracted the metadata from the
files, and stored that metadata inside the repository.
</para>
<para>
Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/use_cases.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/use_cases.xml 2010-01-10 07:57:11 UTC (rev 1583)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/use_cases.xml 2010-01-10 15:56:55 UTC (rev 1584)
@@ -61,7 +61,7 @@
with the content, allowing the same content to be presented in different hierarchical classifications.
But JBoss DNA capabilities also offer a great advantage, since any file that is uploaded can be automatically sequenced and processed
to extract information that's meaningful and useful but often locked up within the file. For example, when a WSDL file is uploaded,
- the appropriate sequencer(s) process the file and extract and stores in the repository the structured information describing the types,
+ the appropriate sequencer(s) process the file and extract and store in the repository the structured information describing the types,
message structures, operations, port types, bindings, and services found within the WSDL file.
When an XML Schema Document is uploaded, JBoss DNA can do the same for the schema's complex and simple types, element and attribute
declarations, model groups, namespaces, imports, includes, annotations, etc. And JBoss DNA can do the same for the various policy files,
@@ -69,7 +69,7 @@
</para>
<para>
Integration with a management system can be done in a similar manner. A JBoss DNA connector could access the management system
- to discover the servers and enable auto-discovery of the services, and "tag" the services deployments with the lifecycle phase
+ to discover the servers and enable auto-discovery of the services, and "tag" the services' deployments with the lifecycle phase
(dev, test, production, etc.). Plus, JBoss DNA sequencers can automatically process the uploaded artifacts to extract a useful
structured representation of their content, and can then store that additional information in the repository. So not only are
the original artifacts stored in the repository, but a structured representation of their content is also stored. And all of
@@ -117,7 +117,7 @@
<title>Configuration repository</title>
<para>
Many applications and libraries have configuration files that allow the users (or developers) to dictate the setup and behavior.
- Often this involves multiple files in a specific structure on the file system. But invalid or inopportune changes to these files
+ Often this involves multiple files in a specific structure on the file system. Invalid or inopportune changes to these files
sometimes corrupt the environment, but creating a more robust configuration management system is often way beyond the desired
effort.
</para>
Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna.xml 2010-01-10 07:57:11 UTC (rev 1583)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna.xml 2010-01-10 15:56:55 UTC (rev 1584)
@@ -118,7 +118,7 @@
<itemizedlist>
<listitem>
<para><emphasis role="strong"><code>Loading from a file</code></emphasis> is conceptually the easiest and requires the least amount
- of Java code, but it now requires a configuration file. More on that in a bit.</para>
+ of Java code, but it does require a configuration file. More on that in a bit.</para>
</listitem>
<listitem>
<para><emphasis role="strong"><code>Loading from a configuration repository</code></emphasis> is not much more complicated than loading
@@ -176,7 +176,8 @@
<jaasLoginConfigName jcr:primaryType="dna:option" dna:value="dna-jcr"/>
<!--
As a convenience, DNA defaults to granting guest users full access.
- In a production system, you would want to limit this access by uncommenting one of the options below:
+ In a production system, you would want to limit this access by uncommenting one of the
+ options below:
for no access:
<anonymousUserRoles jcr:PrimaryType="dna:option" dna:value="" />
@@ -188,11 +189,15 @@
</dna:repository>
</dna:repositories>
<!--
- Define the sources for the content. These sources are directly accessible using the DNA-specific Graph API.
+ Define the sources for the content. These sources are directly accessible using the DNA-specific
+ Graph API.
-->
<dna:sources jcr:primaryType="nt:unstructured">
- <dna:source jcr:name="Cars" dna:classname="org.jboss.dna.graph.connector.inmemory.InMemoryRepositorySource" dna:retryLimit="3" dna:defaultWorkspaceName="workspace1"/>
- <dna:source jcr:name="Aircraft" dna:classname="org.jboss.dna.graph.connector.inmemory.InMemoryRepositorySource">
+ <dna:source jcr:name="Cars"
+ dna:classname="org.jboss.dna.graph.connector.inmemory.InMemoryRepositorySource"
+ dna:retryLimit="3" dna:defaultWorkspaceName="workspace1"/>
+ <dna:source jcr:name="Aircraft"
+ dna:classname="org.jboss.dna.graph.connector.inmemory.InMemoryRepositorySource">
<!-- Define the name of the workspace used by default. Optional, but convenient. -->
<defaultWorkspaceName>workspace2</defaultWorkspaceName>
</dna:source>
@@ -201,17 +206,20 @@
Define the sequencers. This is an optional section.
-->
<dna:sequencers>
- <dna:sequencer jcr:name="Image Sequencer" dna:classname="org.jboss.dna.sequencer.image.ImageMetadataSequencer">
+ <dna:sequencer jcr:name="Image Sequencer"
+ dna:classname="org.jboss.dna.sequencer.image.ImageMetadataSequencer">
<dna:description>Image metadata sequencer</dna:description>
<dna:pathExpression>/foo/source => /foo/target</dna:pathExpression>
<dna:pathExpression>/bar/source => /bar/target</dna:pathExpression>
</dna:sequencer>
</dna:sequencers>
<!--
- Define how JBoss DNA will determine the MIME type of files. This is an optional section (and the default works pretty well).
+ Define how JBoss DNA will determine the MIME type of files. This is an optional section
+ (and the default works pretty well).
-->
<dna:mimeTypeDetectors>
- <dna:mimeTypeDetector jcr:name="Detector" dna:description="Standard extension-based MIME type detector"/>
+ <dna:mimeTypeDetector jcr:name="Detector"
+ dna:description="Standard extension-based MIME type detector"/>
</dna:mimeTypeDetectors>
</configuration>]]></programlisting>
</sect2>
@@ -465,19 +473,14 @@
and then close the &Session;. Here's an example of a JSP page that does this:
</para>
<programlisting role="JAVA"><![CDATA[
-<%@ page import="
- javax.naming.*,
- javax.jcr.*,
- org.jboss.security.config.IDTrustConfiguration
- " %>
+<%@ page import="javax.naming.*, javax.jcr.*, org.jboss.security.config.IDTrustConfiguration" %>
<%!
static {
// Initialize IDTrust
- String configFile = "security/jaas.conf.xml";
IDTrustConfiguration idtrustConfig = new IDTrustConfiguration();
try {
- idtrustConfig.config(configFile);
+ idtrustConfig.config("security/jaas.conf.xml");
} catch (Exception ex) {
throw new IllegalStateException(ex);
}
@@ -504,9 +507,7 @@
Since this uses a servlet container, there is no JAAS implementation configured, so note the
loading of IDTrust to create the JAAS realm. (To make this work in Tomcat, the security
folder that contains the <code>jaas.conf.xml</code>, <code>users.properties</code>, and
- <code>roles.properties</code> needs to be moved into the <code>%CATALINA_HOME%</code> directory.
- Moving the security folder into the <code>conf</code> directory did not allow those files
- to be visible by the JSP page.)
+ <code>roles.properties</code> needs to be moved into the <code>%CATALINA_HOME%</code> directory.)
</para>
<note>
<para>
Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/custom.dtd
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/custom.dtd 2010-01-10 07:57:11 UTC (rev 1583)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/custom.dtd 2010-01-10 15:56:55 UTC (rev 1584)
@@ -132,6 +132,7 @@
<!ENTITY JBossCacheRepository "<ulink url='&API;connector/jbosscache/JBossCacheRepository.html'><classname>JBossCacheRepository</classname></ulink>">
<!ENTITY JBossCacheSource "<ulink url='&API;connector/jbosscache/JBossCacheSource.html'><classname>JBossCacheSource</classname></ulink>">
+<!ENTITY JdbcMetadataSource "<ulink url='&API;connector/meta/jdbc/JdbcMetadataSource.html'><classname>JdbcMetadataSource</classname></ulink>">
<!ENTITY ImageMetadataSequencer "<ulink url='&API;sequencer/image/ImageMetadataSequencer.html'><classname>ImageMetadataSequencer</classname></ulink>">
<!ENTITY ImageMetadata "<ulink url='&API;sequencer/image/ImageMetadata.html'><classname>ImageMetadata</classname></ulink>">
<!ENTITY ImageSequencerI18n "<ulink url='&API;sequencer/image/ImageSequencerI18n.html'><classname>ImageSequencerI18n</classname></ulink>">
Modified: trunk/docs/reference/src/main/docbook/en-US/content/core/connector.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/core/connector.xml 2010-01-10 07:57:11 UTC (rev 1583)
+++ trunk/docs/reference/src/main/docbook/en-US/content/core/connector.xml 2010-01-10 15:56:55 UTC (rev 1584)
@@ -164,12 +164,20 @@
</listitem>
</itemizedlist>
<para>As an example, consider that we want JBoss DNA to give us access through JCR to the schema information contained in a
- relational databases. We first have to develop a connector that allows us to interact with relational databases using JDBC.
- That connector would contain a <code>JdbcRepositorySource</code> Java class that implements &RepositorySource;,
+ relational database. We first have to develop a connector that allows us to interact with relational databases using JDBC.
+ That connector would contain a &JdbcMetadataSource; Java class that implements &RepositorySource;,
and that has all of the various JavaBean properties for setting the name of the driver class, URL, username, password,
- and other properties. (Or we might have a JavaBean property that defines the JNDI name where we can find a JDBC
- <code>DataSource</code> instance pointing to our JDBC database.)
+ and other properties. If we add a JavaBean property defining the JNDI name, our connector could look in JNDI to find a JDBC
+ <code>DataSource</code> instance, perhaps already configured to use connection pools.
</para>
+ <note>
+ <para>
+ Of course, before you develop a connector, you should probably check the
+ <ulink url="http://docs.jboss.org/jbossdna/latest/manuals/reference/html/provied-conn...">list of connectors</ulink> JBoss DNA already provides out of the box.
+ With this latest release, JBoss DNA already includes this JDBC metadata connector! And we're always interested in new
+ connectors and new contributors, so please consider developing your custom connector as part of JBoss DNA.
+ </para>
+ </note>
<para>
Our new connector would also have a <code>JdbcRepositoryConnection</code> Java class that implements the
&RepositoryConnection; interface. This class would probably wrap a JDBC database connection,
@@ -180,8 +188,8 @@
</para>
<para>
To use our connector in an application that uses JBoss DNA, we need to create an instance of the
- <classname>JdbcRepositorySource</classname> for each database instance that we want to access. If we have 3 MySQL databases,
- 9 Oracle databases, and 4 PostgreSQL databases, then we'd need to create a total of 16 <classname>JdbcRepositorySource</classname>
+ &JdbcMetadataSource; for each database instance that we want to access. If we have 3 MySQL databases,
+ 9 Oracle databases, and 4 PostgreSQL databases, then we'd need to create a total of 16 &JdbcMetadataSource;
instances, each with the properties describing a single database instance. Those sources are then available for use by
JBoss DNA components, including the <link linkend="jcr">JCR</link> implementation.
</para>
@@ -218,14 +226,24 @@
<listitem>
<para>
Implement the &RepositorySource; interface, using JavaBean properties for each bit of information the implementation will
- need to establish a connection to the source system.
- </para>
- <para>
- Then, implement the &RepositoryConnection; interface with a class that represents a connection to the source. The
+ need to establish a connection to the source system. Then, implement the &RepositoryConnection; interface with
+ a class that represents a connection to the source. The
<code>execute(&ExecutionContext;, &Request;)</code> method should process any and all requests that may come down the pike,
- and the results of each request can be put directly on that request.
+ and the results of each request can be put directly on that request. This approach is pretty straightforward, and gives
+ you ultimate freedom in terms of your class structure.
</para>
<para>
+ Alternatively, an easier way to get a complete read-write connector would be to extend one of our two abstract
+ &RepositorySource; implementations. If the content your connector exposes has unique keys (such as a unique string,
+ UUID or other identifier), consider implementing &MapRepositorySource;, subclassing &MapRepository;, and
+ using the existing &MapRepositoryConnection; implementation. This &MapRepositoryConnection; does most of the work
+ already, relying upon your &MapRepository; subclass for anything that might be source-specific.
+ Or, if the content your connector exposes is simply path-based, consider implementing &PathRepositorySource;,
+ subclassing &PathRepository;, and using the existing &PathRepositoryConnection; implementation.
+ Again, &PathRepositoryConnection; class does almost all of the work and delegates to your &PathRepository;
+ subclass for anything that might be source-specific.
+ </para>
+ <para>
Don't forget unit tests that verify that the connector is doing what it's expected to do. (If you'll be committing the connector
code to the JBoss DNA project, please ensure that the unit tests can be run by others that may not have access to the
source system. In this case, consider writing integration tests that can be easily configured to use different sources
Modified: trunk/docs/reference/src/main/docbook/en-US/custom.dtd
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/custom.dtd 2010-01-10 07:57:11 UTC (rev 1583)
+++ trunk/docs/reference/src/main/docbook/en-US/custom.dtd 2010-01-10 15:56:55 UTC (rev 1584)
@@ -137,6 +137,13 @@
<!ENTITY RepositorySourceException "<ulink url='&API;graph/connector/RepositorySourceException.html'><classname>RepositorySourceException</classname></ulink>">
<!ENTITY InMemoryRepository "<ulink url='&API;graph/connector/inmemory/InMemoryRepository.html'><classname>InMemoryRepository</classname></ulink>">
<!ENTITY InMemoryRepositorySource "<ulink url='&API;graph/connector/inmemory/InMemoryRepositorySource.html'><classname>InMemoryRepositorySource</classname></ulink>">
+<!ENTITY PathRepositorySource "<ulink url='&API;graph/connector/path/PathRepositorySource.html'><classname>PathRepositorySource</classname></ulink>">
+<!ENTITY PathRepositoryConnection "<ulink url='&API;graph/connector/path/PathRepositoryConnection.html'><classname>PathRepositoryConnection</classname></ulink>">
+<!ENTITY PathRepository "<ulink url='&API;graph/connector/path/PathRepository.html'><classname>PathRepository</classname></ulink>">
+<!ENTITY MapRepositorySource "<ulink url='&API;graph/connector/map/MapRepositorySource.html'><classname>MapRepositorySource</classname></ulink>">
+<!ENTITY MapRepositoryConnection "<ulink url='&API;graph/connector/map/MapRepositoryConnection.html'><classname>MapRepositoryConnection</classname></ulink>">
+<!ENTITY MapRepository "<ulink url='&API;graph/connector/map/PathRepository.html'><classname>MapRepository</classname></ulink>">
+<!ENTITY InMemoryRepository "<ulink url='&API;graph/connector/inmemory/InMemoryRepository.html'><classname>InMemoryRepository</classname></ulink>">
<!ENTITY FederatedRepository "<ulink url='&API;graph/connector/federation/FederatedRepository.html'><classname>FederatedRepository</classname></ulink>">
<!ENTITY FederatedRepositorySource "<ulink url='&API;graph/connector/federation/FederatedRepositorySource.html'><classname>FederatedRepositorySource</classname></ulink>">
<!ENTITY ForkRequestProcessor "<ulink url='&API;graph/connector/federation/ForkRequestProcessor.html'><classname>ForkRequestProcessor</classname></ulink>">
14 years, 4 months
DNA SVN: r1583 - trunk/docs/reference/src/main/docbook/en-US/content/jcr.
by dna-commits@lists.jboss.org
Author: rhauch
Date: 2010-01-10 02:57:11 -0500 (Sun, 10 Jan 2010)
New Revision: 1583
Modified:
trunk/docs/reference/src/main/docbook/en-US/content/jcr/query_and_search.xml
Log:
Merge branch 'dna-621'
Modified: trunk/docs/reference/src/main/docbook/en-US/content/jcr/query_and_search.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/jcr/query_and_search.xml 2010-01-10 07:36:05 UTC (rev 1582)
+++ trunk/docs/reference/src/main/docbook/en-US/content/jcr/query_and_search.xml 2010-01-10 07:57:11 UTC (rev 1583)
@@ -496,6 +496,7 @@
Support for the "<code>FULL OUTER JOIN</code>" and "<code>CROSS JOIN</code>" join types, in addition to the
"<code>LEFT OUTER JOIN</code>", "<code>RIGHT OUTER JOIN</code>" and "<code>INNER JOIN</code>" types defined by
JCR-SQL2. Note that "<code>JOIN</code>" is a shorthand for "<code>INNER JOIN</code>".
+ For detail, see the <link linkend="jcr-sql2-joins">grammar for joins</link>.
</para>
</listitem>
<listitem>
@@ -505,11 +506,13 @@
The <code>UNION</code> operator combines the rows from two result sets, the <code>INTERSECT</code> operator returns
the difference between two result sets, and the <code>EXCEPT</code> operator returns the rows that are common to
two result sets. Duplicate rows are removed unless the operator is followed by the <code>ALL</code> keyword.
+ For detail, see the <link linkend="jcr-sql2-queries">grammar for set queries</link>.
</para>
</listitem>
<listitem>
<para>
Removal of duplicate rows in the results, using "<code>SELECT DISTINCT ...</code>".
+ For detail, see the <link linkend="jcr-sql2-queries">grammar for queries</link>.
</para>
</listitem>
<listitem>
@@ -517,6 +520,7 @@
Limiting the number of rows in the result set with the "<code>LIMIT count</code>" clause, where <code>count</code>
is the maximum number of rows that should be returned. This clause may optionally be followed by the
"<code>OFFSET number</code>" clause to specify the number of initial rows that should be skipped.
+ For detail, see the <link linkend="jcr-sql2-limits">grammar for limits and offsets</link>.
</para>
</listitem>
<listitem>
@@ -526,24 +530,30 @@
can be used in a manner similar to "<code>NAME([<selectorName>])</code>" and "<code>LOCALNAME([<selectorName>])</code>"
that are defined by JCR-SQL2. Note in each of these cases, the selector name is optional if there is only one
selector in the query.
+ For detail, see the <link linkend="jcr-sql2-dynamic-operands">grammar for dynamic operands</link>.
</para>
</listitem>
<listitem>
<para>
Support for the <code>IN</code> and <code>NOT IN</code> clauses to more easily and concisely supply multiple
- of discreet static operands: "<code><dynamicOperand> [NOT] IN (<staticOperand> {, <staticOperand>})"</code>.
+ of discreet static operands.
+ For example, "<code>WHERE ... [my:type].[prop1] IN (3,5,7,10,11,50) ...</code>".
+ For detail, see the <link linkend="jcr-sql2-set-constraints">grammar for set constraints</link>.
</para>
</listitem>
<listitem>
<para>
- Support for the <code>BETWEEN</code> clause to more easily and concisely supply a range of discreet operands:
- "<code><dynamicOperand> [NOT] BETWEEN <lowerBoundStaticOperand> [EXCLUSIVE] AND <upperBoundStaticOperand> [EXCLUSIVE]</code>"
+ Support for the <code>BETWEEN</code> clause to more easily and concisely supply a range of discreet operands.
+ For example, "<code>WHERE ... [my:type].[prop1] BETWEEN 3 EXCLUSIVE AND 10 ...</code>".
+ For detail, see the <link linkend="jcr-sql2-between-constraints">grammar for between constraints</link>.
</para>
</listitem>
<listitem>
<para>
Support for simple arithmetic in numeric-based criteria and order-by clauses. For example,
- "<code>... WHERE SCORE(type1) + SCORE(type2) > 1.0</code>" or "<code>... ORDER BY (SCORE(type1) * SCORE(type2)) ASC</code>".
+ "<code>... WHERE</code> <code>SCORE(type1) +</code> <code>SCORE(type2) > 1.0</code>" or
+ "<code>... ORDER BY</code> <code>(SCORE(type1) * SCORE(type2)) ASC,</code> <code>LENGTH(type2.property1) DESC</code>".
+ For detail, see the <link linkend="jcr-sql2-ordering">grammar for order-by clauses</link>.
</para>
</listitem>
</itemizedlist>
@@ -561,13 +571,13 @@
Literals (or keywords) are denoted by single-quotes.
</para>
</note>
- <sect2>
+ <sect2 id="jcr-sql2-queries">
<title>Queries</title>
<programlisting><![CDATA[
QueryCommand ::= Query | SetQuery
-SetQuery ::= Query ('UNION'|'INTERSECT'|'EXCEPT') [ALL] Query
- { ('UNION'|'INTERSECT'|'EXCEPT') [ALL] Query }
+SetQuery ::= Query ('UNION'|'INTERSECT'|'EXCEPT') ['ALL'] Query
+ { ('UNION'|'INTERSECT'|'EXCEPT') ['ALL'] Query }
Query ::= 'SELECT' ['DISTINCT'] columns
'FROM' Source
@@ -587,7 +597,7 @@
]]></programlisting>
</sect2>
- <sect2>
+ <sect2 id="jcr-sql2-joins">
<title>Joins</title>
<programlisting><![CDATA[
@@ -707,7 +717,7 @@
]]></programlisting>
</sect2>
- <sect2>
+ <sect2 id="jcr-sql2-between-constraints">
<title>Between Constraints</title>
<programlisting><![CDATA[
@@ -728,7 +738,7 @@
]]></programlisting>
</sect2>
- <sect2>
+ <sect2 id="jcr-sql2-set-constraints">
<title>Set Constraints</title>
<programlisting><![CDATA[
@@ -857,7 +867,7 @@
]]></programlisting>
</sect2>
- <sect2>
+ <sect2 id="jcr-sql2-dynamic-operands">
<title>Dynamic Operands</title>
<programlisting><![CDATA[
@@ -899,7 +909,7 @@
]]></programlisting>
</sect2>
- <sect2>
+ <sect2 id="jcr-sql2-ordering">
<title>Ordering</title>
<programlisting><![CDATA[
@@ -926,7 +936,7 @@
]]></programlisting>
</sect2>
- <sect2>
+ <sect2 id="jcr-sql2-limits">
<title>Limit and Offset</title>
<programlisting><![CDATA[
14 years, 4 months
DNA SVN: r1582 - trunk/docs/reference/src/main/docbook/en-US/content/jcr.
by dna-commits@lists.jboss.org
Author: rhauch
Date: 2010-01-10 02:36:05 -0500 (Sun, 10 Jan 2010)
New Revision: 1582
Modified:
trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml
trunk/docs/reference/src/main/docbook/en-US/content/jcr/query_and_search.xml
Log:
DNA-621 More minor edits to the Reference Guide.
Modified: trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml 2010-01-10 07:23:33 UTC (rev 1581)
+++ trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml 2010-01-10 07:36:05 UTC (rev 1582)
@@ -201,11 +201,11 @@
<ulink url="&Roadmap;">current list of known issues and bugs</ulink>.</emphasis>
</para>
<sect2>
- <title>L1 and L2 Features</title>
+ <title>Level 1 and Level 2 (Required) Features</title>
<para>
JBoss DNA currently supports all Level 1 features and most of the Level 2 features defined by the
<ulink url="&JSR170;">JSR-170</ulink> specification.
- This release adds support for queries, which is described in more detail in <link linkend="jcr-query-and-search">later</link>.
+ This release adds support for queries, which is described in more detail in the <link linkend="jcr-query-and-search">next chapter</link>.
However, referential integrity for <code>REFERENCE</code> properties, a Level 2 feature, is not yet implemented.
As the current implementation does provide many of the features that may be needed by an application, we really hope
that this release will allow you to give us some feedback on what we have so far.
Modified: trunk/docs/reference/src/main/docbook/en-US/content/jcr/query_and_search.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/jcr/query_and_search.xml 2010-01-10 07:23:33 UTC (rev 1581)
+++ trunk/docs/reference/src/main/docbook/en-US/content/jcr/query_and_search.xml 2010-01-10 07:36:05 UTC (rev 1582)
@@ -557,7 +557,8 @@
The grammar is presented using the same EBNF nomenclature as used in the JCR 2.0 specification.
Terms are surrounded by '[' and ']' denote optional terms that appear zero or one times.
Terms surrounded by '{' and '}' denote terms that appear zero or more times.
- Parentheses are used to identify groups, and are often used to surround possible values.
+ Parentheses are used to identify groups, and are often used to surround possible values.
+ Literals (or keywords) are denoted by single-quotes.
</para>
</note>
<sect2>
14 years, 4 months
DNA SVN: r1581 - trunk/docs/reference/src/main/docbook/en-US/content/jcr.
by dna-commits@lists.jboss.org
Author: rhauch
Date: 2010-01-10 02:23:33 -0500 (Sun, 10 Jan 2010)
New Revision: 1581
Modified:
trunk/docs/reference/src/main/docbook/en-US/content/jcr/query_and_search.xml
Log:
DNA-617 Changed the section levels of the JCR-SQL2 and Full-text Search languages so that they are navigable from the Table of Contents.
Modified: trunk/docs/reference/src/main/docbook/en-US/content/jcr/query_and_search.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/jcr/query_and_search.xml 2010-01-10 07:10:48 UTC (rev 1580)
+++ trunk/docs/reference/src/main/docbook/en-US/content/jcr/query_and_search.xml 2010-01-10 07:23:33 UTC (rev 1581)
@@ -548,21 +548,19 @@
</listitem>
</itemizedlist>
</para>
- <sect2 id="jcr-sql2-grammar">
- <title>Grammar</title>
+ <para>
+ The grammar for the JCR-SQL2 query language is actually a superset of that defined by the
+ <ulink url="&JSR283;">JCR 2.0 specification</ulink>, and as such the complete grammar is included here.
+ </para>
+ <note>
<para>
- The grammar for the JCR-SQL2 query language is actually a superset of that defined by the
- <ulink url="&JSR283;">JCR 2.0 specification</ulink>, and as such the complete grammar is included here.
+ The grammar is presented using the same EBNF nomenclature as used in the JCR 2.0 specification.
+ Terms are surrounded by '[' and ']' denote optional terms that appear zero or one times.
+ Terms surrounded by '{' and '}' denote terms that appear zero or more times.
+ Parentheses are used to identify groups, and are often used to surround possible values.
</para>
- <note>
- <para>
- The grammar is presented using the same EBNF nomenclature as used in the JCR 2.0 specification.
- Terms are surrounded by '[' and ']' denote optional terms that appear zero or one times.
- Terms surrounded by '{' and '}' denote terms that appear zero or more times.
- Parentheses are used to identify groups, and are often used to surround possible values.
- </para>
- </note>
- <sect3>
+ </note>
+ <sect2>
<title>Queries</title>
<programlisting><![CDATA[
QueryCommand ::= Query | SetQuery
@@ -576,8 +574,8 @@
['ORDER BY' orderings]
[Limit]
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Sources</title>
<programlisting><![CDATA[
Source ::= Selector | Join
@@ -587,8 +585,8 @@
nodeTypeName ::= Name
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Joins</title>
<programlisting><![CDATA[
@@ -614,8 +612,8 @@
ChildNodeJoinCondition | DescendantNodeJoinCondition
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Equi-Join Conditions</title>
<programlisting><![CDATA[
@@ -627,8 +625,8 @@
property2Name ::= propertyName
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Same-Node Join Conditions</title>
<programlisting><![CDATA[
@@ -637,8 +635,8 @@
selector2Path ::= Path
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Child-Node Join Conditions</title>
<programlisting><![CDATA[
@@ -648,8 +646,8 @@
parentSelectorName ::= selectorName
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Descendant-Node Join Conditions</title>
<programlisting><![CDATA[
@@ -659,8 +657,8 @@
ancestorSelectorName ::= selectorName
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Constraints</title>
<programlisting><![CDATA[
@@ -670,8 +668,8 @@
SetConstraint | FullTextSearch | SameNode | ChildNode | DescendantNode
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>And Constraints</title>
<programlisting><![CDATA[
@@ -681,24 +679,24 @@
constraint2 ::= Constraint
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Or Constraints</title>
<programlisting><![CDATA[
Or ::= constraint1 'OR' constraint2
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Not Constraints</title>
<programlisting><![CDATA[
Not ::= 'NOT' Constraint
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Comparison Constraints</title>
<programlisting><![CDATA[
@@ -707,8 +705,8 @@
Operator ::= '=' | '!=' | '<' | '<=' | '>' | '>=' | 'LIKE'
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Between Constraints</title>
<programlisting><![CDATA[
@@ -719,8 +717,8 @@
upperBound ::= StaticOperand
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Property Existence Constraints</title>
<programlisting><![CDATA[
@@ -728,8 +726,8 @@
propertyName 'IS' ['NOT'] 'NULL' /* If only one selector exists in this query */
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Set Constraints</title>
<programlisting><![CDATA[
@@ -740,8 +738,8 @@
additionalStaticOperand ::= StaticOperand
]]></programlisting>
- </sect3>
- <sect3 id="jcr-sql2-full-text-search-constraints">
+ </sect2>
+ <sect2 id="jcr-sql2-full-text-search-constraints">
<title>Full-text Search Constraints</title>
<programlisting><![CDATA[
@@ -749,11 +747,36 @@
',' ''' fullTextSearchExpression''' ')'
/* If only one selector exists in this query, explicit specification of the selectorName
preceding the propertyName is optional */
-fullTextSearchExpression ::= /* a full-text search expression, see FullTextSearchParser */
+fullTextSearchExpression ::= FulltextSearch
+
]]></programlisting>
- </sect3>
- <sect3>
+ <para> where <code>FulltextSearch</code> is defined by the following, and is the same as the
+ <link linkend='fulltext-search-expressions'>full-text search language</link> supported by JBoss DNA:
+ </para>
+<programlisting><![CDATA[
+
+FulltextSearch ::= Disjunct {Space 'OR' Space Disjunct}
+
+Disjunct ::= Term {Space Term}
+
+Term ::= ['-'] SimpleTerm
+
+SimpleTerm ::= Word | '"' Word {Space Word} '"'
+
+Word ::= NonSpaceChar {NonSpaceChar}
+
+Space ::= SpaceChar {SpaceChar}
+
+NonSpaceChar ::= Char - SpaceChar /* Any Char except SpaceChar */
+
+SpaceChar ::= ' '
+
+Char ::= /* Any character */
+
+]]></programlisting>
+ </sect2>
+ <sect2>
<title>Same-Node Constraint</title>
<programlisting><![CDATA[
@@ -762,8 +785,8 @@
preceding the path is optional */
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Child-Node Constraints</title>
<programlisting><![CDATA[
@@ -772,8 +795,8 @@
preceding the path is optional */
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Descendant-Node Constraints</title>
<programlisting><![CDATA[
@@ -782,8 +805,8 @@
preceding the propertyName is optional */
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Paths and Names</title>
<programlisting><![CDATA[
@@ -800,8 +823,8 @@
characters (namely letters, digits, and underscore) */
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Static Operands</title>
<programlisting><![CDATA[
@@ -821,8 +844,8 @@
UnquotedLiteral ::= /* String form of a JCR Value, as defined in the JCR specification */
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Bind Variables</title>
<programlisting><![CDATA[
@@ -832,8 +855,8 @@
does not need to be a registered namespace prefix. */
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Dynamic Operands</title>
<programlisting><![CDATA[
@@ -874,8 +897,8 @@
Arithmetic ::= DynamicOperand ('+'|'-'|'*'|'/') DynamicOperand
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Ordering</title>
<programlisting><![CDATA[
@@ -886,8 +909,8 @@
Order ::= 'ASC' | 'DESC'
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Columns</title>
<programlisting><![CDATA[
@@ -901,8 +924,8 @@
columnName ::= Name
]]></programlisting>
- </sect3>
- <sect3>
+ </sect2>
+ <sect2>
<title>Limit and Offset</title>
<programlisting><![CDATA[
@@ -910,7 +933,6 @@
count ::= /* Positive integer value */
offset ::= /* Non-negative integer value */
]]></programlisting>
- </sect3>
</sect2>
</sect1>
<sect1 id="fulltext-search-query-language">
@@ -950,20 +972,20 @@
a <emphasis>negative term</emphasis>, and it reduces the rank of any node whose property values contain the
the value. To specify a negative term, simply prefix the term with a hyphen ('-').
</para>
- <sect2 id='fulltext-grammar'>
- <title>Grammar</title>
- <para>
- The grammar for this full-text search language is specified in Section 6.7.19 of the
- <ulink url="&JSR283;">JCR 2.0 specification</ulink>, but it is also included here as a convenience.
- <note>
- <para>
- The grammar is presented using the same EBNF nomenclature as used in the JCR 2.0 specification.
- Terms are surrounded by '[' and ']' denote optional terms that appear zero or one times.
- Terms surrounded by '{' and '}' denote terms that appear zero or more times.
- Parentheses are used to identify groups, and are often used to surround possible values.
- </para>
- </note>
- </para>
+ <para>
+ The grammar for this full-text search language is specified in Section 6.7.19 of the
+ <ulink url="&JSR283;">JCR 2.0 specification</ulink>, but it is also included here as a convenience.
+ <note>
+ <para>
+ The grammar is presented using the same EBNF nomenclature as used in the JCR 2.0 specification.
+ Terms are surrounded by '[' and ']' denote optional terms that appear zero or one times.
+ Terms surrounded by '{' and '}' denote terms that appear zero or more times.
+ Parentheses are used to identify groups, and are often used to surround possible values.
+ </para>
+ </note>
+ </para>
+ <sect2 id='fulltext-search-expressions'>
+ <title>Full-text Search Expressions</title>
<programlisting><![CDATA[
FulltextSearch ::= Disjunct {Space 'OR' Space Disjunct}
14 years, 4 months
DNA SVN: r1580 - in trunk/docs/reference/src/main/docbook/en-US: content/jcr and 1 other directory.
by dna-commits@lists.jboss.org
Author: rhauch
Date: 2010-01-10 02:10:48 -0500 (Sun, 10 Jan 2010)
New Revision: 1580
Modified:
trunk/docs/reference/src/main/docbook/en-US/content/jcr/configuration.xml
trunk/docs/reference/src/main/docbook/en-US/content/jcr/query_and_search.xml
trunk/docs/reference/src/main/docbook/en-US/custom.dtd
Log:
DNA-617 Completed the initial version of the chapter on query and search functionality. Also removed text that pointed to the Reference Guide from within the Reference Guide.
Modified: trunk/docs/reference/src/main/docbook/en-US/content/jcr/configuration.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/jcr/configuration.xml 2010-01-10 03:07:50 UTC (rev 1579)
+++ trunk/docs/reference/src/main/docbook/en-US/content/jcr/configuration.xml 2010-01-10 07:10:48 UTC (rev 1580)
@@ -230,7 +230,6 @@
]]></programlisting>
<para>
This really is a more advanced way to define your configuration, so we won't go into how you configure a &RepositorySource;.
- For more information, consult the &ReferenceGuide;.
</para>
<note>
<para>The <code>loadFrom(...)</code> method can be called any number of times, but each time it is called it completely wipes
@@ -329,8 +328,7 @@
(loaded from the classpath), that is to sequence the "jcr:data" property on any new or changed nodes that are named
"jcr:content" below a parent node with a name ending in ".jpg", ".jpeg", ".gif", ".bmp", ".pcx", ".iff", ".ras",
".pbm", ".pgm", ".ppm" or ".psd". The output of the sequencing operation should be placed at the "/images/$1" node,
- where the "$1" value is captured as the name of the parent node. (The capture groups work the same was as regular expressions;
- see the &ReferenceGuide; for more details.)
+ where the "$1" value is captured as the name of the parent node. (The capture groups work the same was as regular expressions.)
Of course, the class can be specified as Class reference or a string (followed by whether the class should be loaded from
the classpath or from a specific classpath).
</para>
@@ -448,7 +446,7 @@
<para>
Before the server can start, however, all of the JBoss DNA jars need to be placed on the classpath for the server.
JAAS also needs to be configured, and this can be done using the application server's configuration or in your
- web application if you're using a simple servlet container. For more details, see the &ReferenceGuide;.
+ web application if you're using a simple servlet container.
</para>
<note>
<para>
Modified: trunk/docs/reference/src/main/docbook/en-US/content/jcr/query_and_search.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/jcr/query_and_search.xml 2010-01-10 03:07:50 UTC (rev 1579)
+++ trunk/docs/reference/src/main/docbook/en-US/content/jcr/query_and_search.xml 2010-01-10 07:10:48 UTC (rev 1580)
@@ -31,24 +31,887 @@
<chapter id="jcr-query-and-search">
<title>Querying and Searching using JCR</title>
<para>
+ The JCR API defines a way to query a repository for content that meets user-defined criteria.
+ The JCR API actually makes it possible for implementations to support multiple query languages,
+ and the only language required by <ulink url="&JSR170;">JCR 1.0</ulink> is a subset of XPath. The 1.0 specification
+ also defines a SQL-like query language, but supporting it is optional.
+ </para>
+ <para>
+ JBoss DNA now support this query feature, including the required XPath language and two other languages not
+ defined by the specification. This chapter describes how your applications can use queries to search
+ your repositories, and defines the three query languages that are available with JBoss DNA.
</para>
<sect1 id="jcr-query-api">
<title>JCR Query API</title>
<para>
+ Like most operations in the JCR API, querying is done through a &Session; instance, from which can be obtained
+ the &QueryManager; that defines methods for creating &Query; objects, storing queries as &Node;s in the repository,
+ and reconstituting queries that were stored on &Nodes;s. Thus, querying a repository generally follows this pattern:
</para>
+<programlisting role="JAVA"><![CDATA[
+// Obtain the query manager for the session ...
+javax.jcr.query.QueryManager queryManager = session.getWorkspace().getQueryManager();
+
+// Create a query object ...
+String language = ...
+String expression = ...
+javax.jcr.Query query = queryManager.createQuery(expression,language);
+
+// Execute the query and get the results ...
+javax.jcr.QueryResult result = query.execute();
+
+// Iterate over the nodes in the results ...
+javax.jcr.NodeIterator nodeIter = result.getNodes();
+while ( nodeIter.hasNext() ) {
+ javax.jcr.Node node = nodeIter.nextNode();
+ ...
+}
+
+// Or iterate over the rows in the results ...
+String[] columnNames = result.getColumnNames();
+javax.jcr.query.RowIterator rowIter = result.getRows();
+while ( rowIter.hasNext() ) {
+ javax.jcr.query.Row row = rowIter.nextRow();
+ // Iterate over the column values in each row ...
+ javax.jcr.Value[] values = row.getValues();
+ for ( javax.jcr.Value value : values ) {
+ ...
+ }
+ // Or access the column values by name ...
+ for ( String columnName : columnNames ) {
+ javax.jcr.Value value = row.getValue(columnName);
+ ...
+ }
+}
+
+// When finished, close the session ...
+session.logout();
+]]></programlisting>
+ <para>
+ For more detail about these methods or about how to use other facets of the JCR query API, please consult Section 6.7 of the
+ <ulink url="&JSR170;">JCR 1.0 specification</ulink>.
+ </para>
</sect1>
<sect1 id="jcr-xpath-query-language">
<title>JCR XPath Query Language</title>
<para>
+ The <ulink url="&JSR170;">JCR 1.0 specification</ulink> uses the XPath query language because node structures in JCR
+ are very analogous to the structure of an XML document. Thus, XPath provides a useful language for selecting
+ and searching workspace content. And since JCR 1.0 defines a mapping between XML and a workspace view called
+ the "document view", adapting XPath to workspace content is quite natural.
</para>
+ <para>
+ An JCR XPath query specifies the subset of nodes in a workspace that satisfy the constraints defined in the query.
+ Constraints can limit the nodes in the results to be those nodes with a specific (primary or mixin) node type,
+ with properties having particular values, or to be within a specific subtree of the workspace.
+ The query also defines how the nodes are to be returned in the result sets using column specifiers
+ and ordering specifiers.
+ </para>
+ <note>
+ <para>
+ As an aside, JBoss DNA actually implements XPath queries by transforming them into the equivalent JCR-SQL2 representation.
+ And the JCR-SQL2 language, although often more verbose, is much more capable of representing complex queries with multiple combinations
+ of type, property, and path constraints.
+ </para>
+ </note>
+ <sect2 id="jcr-xpath-column-specifiers">
+ <title>Column Specifiers</title>
+ <para>
+ JCR 1.0 specifies that support is required only for returning column values based upon single-valued, non-residual
+ properties that are declared on or inherited by the node types specified in the type constraint.
+ JBoss DNA follows this requirement, and does not specifying residual properties. However, JBoss DNA does allow
+ multi-valued properties to be specified as result columns.
+ And as per the specification, JBoss DNA always returns the "<code>jcr:path</code>" and "<code>jcr:score</code>"
+ pseudo-columns.
+ </para>
+ <para>
+ JBoss DNA uses the last location step with an attribute axis to specify the properties that are to be returned
+ as result columns. Multiple properties are specified with a union.
+ For example, the following table shows several XPath queries and how they map to JCR-SQL2 queries.
+ </para>
+ <table frame='all'>
+ <title>Specifying result set columns</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='0'>
+ <colspec colname='c1' colwidth="1*"/>
+ <colspec colname='c2' colwidth="1*"/>
+ <thead>
+ <row>
+ <entry>XPath</entry>
+ <entry>JCR-SQL2</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><code>//*</code></entry>
+ <entry><programlisting>SELECT * FROM [nt:base]</programlisting></entry>
+ </row>
+ <row>
+ <entry><code>//element(*,my:type)</code></entry>
+ <entry><programlisting>SELECT * FROM [my:type]</programlisting></entry>
+ </row>
+ <row>
+ <entry><code>//element(*,my:type)/@my:title</code></entry>
+ <entry><programlisting>SELECT [my:title] FROM [my:type]</programlisting></entry>
+ </row>
+ <row>
+ <entry><code>//element(*,my:type)/(@my:title | @my:text)</code></entry>
+ <entry><programlisting>SELECT [my:title], [my:text] FROM [my:type]</programlisting></entry>
+ </row>
+ <row>
+ <entry><code>//element(*,my:type)/(@my:title union @my:text)</code></entry>
+ <entry><programlisting>SELECT [my:title], [my:text] FROM [my:type]</programlisting></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect2>
+ <sect2 id="jcr-xpath-type-constraints">
+ <title>Type Constraints</title>
+ <para>
+ JCR 1.0 specifies that support is required only for specifying constraints of one primary type, and it
+ is optional to support specifying constraints on one (or more) mixin types. The specification
+ also defines that the XPath <code>element</code> test be used to test against node types,
+ and that it is optional to support <code>element</code> tests on location steps other than the last one.
+ Type constraints are inherently inheritance-sensitive, in that a constraint against a particular node type
+ 'X' will be satisfied by nodes explicitly declared to be of type 'X' or of subtypes of 'X'.
+ </para>
+ <para>
+ JBoss DNA does support using the <code>element</code> test to test against primary or mixin type.
+ JBoss DNA also only supports using an <code>element</code> test on the last location step.
+ For example, the following table shows several XPath queries and how they map to JCR-SQL2 queries.
+ </para>
+ <table frame='all'>
+ <title>Specifying type constraints</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='0'>
+ <colspec colname='c1' colwidth="1*"/>
+ <colspec colname='c2' colwidth="1*"/>
+ <thead>
+ <row>
+ <entry>XPath</entry>
+ <entry>JCR-SQL2</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><code>//*</code></entry>
+ <entry><programlisting>SELECT * FROM [nt:base]</programlisting></entry>
+ </row>
+ <row>
+ <entry><code>//element(*,my:type)</code></entry>
+ <entry><programlisting>SELECT * FROM [my:type]</programlisting></entry>
+ </row>
+ <row>
+ <entry><code>/jcr:root/nodes/element(*,my:type)</code></entry>
+ <entry><programlisting>SELECT * FROM [my:type]
+WHERE PATH([my:type])> LIKE '/nodes/%'
+ AND DEPTH([my:type]) = CAST(2 AS LONG)</programlisting></entry>
+ </row>
+ <row>
+ <entry><code>/jcr:root/nodes//element(*,my:type)</code></entry>
+ <entry><programlisting>SELECT * FROM [my:type]
+WHERE PATH([my:type]) LIKE '/nodes/%'</programlisting></entry>
+ </row>
+ <row>
+ <entry><code>/jcr:root/nodes//element(ex:nodeName,my:type)</code></entry>
+ <entry><programlisting>SELECT * FROM [my:type]
+WHERE PATH([my:type]) LIKE '/nodes/%'
+ AND NAME([my:type]) = 'ex:nodeName'</programlisting></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ Note that the JCR-SQL2 language supported by JBoss DNA is far more capable of joining
+ multiple sets of nodes with different type, property and path constraints.
+ </para>
+ </sect2>
+ <sect2 id="jcr-xpath-property-constraints">
+ <title>Property Constraints</title>
+ <para>
+ JCR 1.0 specifies that attribute tests on the last location step is required, but that
+ predicate tests on any other location steps is optional.
+ </para>
+ <para>
+ JBoss DNA does support using attribute tests on the last location step to specify
+ property constraints, as well as supporting axis and filter predicates on other location steps.
+ For example, the following table shows several XPath queries and how they map to JCR-SQL2 queries.
+ </para>
+ <table frame='all'>
+ <title>Specifying property constraints</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='0'>
+ <colspec colname='c1' colwidth="1*"/>
+ <colspec colname='c2' colwidth="1*"/>
+ <thead>
+ <row>
+ <entry>XPath</entry>
+ <entry>JCR-SQL2</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><code>//*[@prop1]</code></entry>
+ <entry><programlisting>SELECT * FROM [nt:base]
+WHERE [nt:base].prop1 IS NOT NULL</programlisting></entry>
+ </row>
+ <row>
+ <entry><code>//element(*,my:type)[@prop1]</code></entry>
+ <entry><programlisting>SELECT * FROM [my:type]
+WHERE [my:type].prop1 IS NOT NULL</programlisting></entry>
+ </row>
+ <row>
+ <entry><code>//element(*,my:type)[@prop1=xs:boolean('true')]</code></entry>
+ <entry><programlisting>SELECT * FROM [my:type]
+WHERE [my:type].prop1 = CAST('true' AS BOOLEAN)</programlisting></entry>
+ </row>
+ <row>
+ <entry><code>//element(*,my:type)[@id<1 and @name='john']</code></entry>
+ <entry><programlisting>SELECT * FROM [my:type]
+WHERE id < 1 AND name = 'john'</programlisting></entry>
+ </row>
+ <row>
+ <entry><code>//element(*,my:type)[a/b/@id]</code></entry>
+ <entry><programlisting>SELECT * FROM [my:type]
+JOIN [nt:base] as nodeSet1
+ ON ISCHILDNODE(nodeSet1,[my:type])
+JOIN [nt:base] as nodeSet2
+ ON ISCHILDNODE(nodeSet2,nodeSet1)
+WHERE (NAME(nodeSet1) = 'a'
+ AND NAME(nodeSet2) = 'b')
+ AND nodeSet2.id IS NOT NULL</programlisting></entry>
+ </row>
+ <row>
+ <entry><code>//element(*,my:type)[./*/*/@id]</code></entry>
+ <entry><programlisting>SELECT * FROM [my:type]
+JOIN [nt:base] as nodeSet1
+ ON ISCHILDNODE(nodeSet1,[my:type])
+JOIN [nt:base] as nodeSet2
+ ON ISCHILDNODE(nodeSet2,nodeSet1)
+WHERE nodeSet2.id IS NOT NULLL</programlisting></entry>
+ </row>
+ <row>
+ <entry><code>//element(*,my:type)[.//@id]</code></entry>
+ <entry><programlisting>SELECT * FROM [my:type]
+JOIN [nt:base] as nodeSet1
+ ON ISDESCENDANTNODE(nodeSet1,[my:type])
+WHERE nodeSet2.id IS NOT NULLL</programlisting></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ Section 6.6.3.3 of the JCR 1.0 specification contains an in-depth description of property value constraints using
+ various comparison operators.
+ </para>
+ </sect2>
+ <sect2 id="jcr-xpath-path-constraints">
+ <title>Path Constraints</title>
+ <para>
+ JCR 1.0 specifies that exact, child node, and descendants-or-self path constraints be supported
+ on the location steps in an XPath query.
+ </para>
+ <para>
+ JBoss DNA does support the four kinds of path constraints.
+ For example, the following table shows several XPath queries and how they map to JCR-SQL2 queries.
+ </para>
+ <table frame='all'>
+ <title>Specifying path constraints</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='0'>
+ <colspec colname='c1' colwidth="1*"/>
+ <colspec colname='c2' colwidth="1*"/>
+ <thead>
+ <row>
+ <entry>XPath</entry>
+ <entry>JCR-SQL2</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><code>/jcr:root/a/b[*]</code></entry>
+ <entry><programlisting>SELECT * FROM [nt:base]
+WHERE PATH([nt:base]) = '/a/b'</programlisting></entry>
+ </row>
+ <row>
+ <entry><code>/jcr:root/a[1]/b[*]</code></entry>
+ <entry><programlisting>SELECT * FROM [nt:base]
+WHERE PATH([nt:base]) = '/a/b'</programlisting></entry>
+ </row>
+ <row>
+ <entry><code>/jcr:root/a[2]/b</code></entry>
+ <entry><programlisting>SELECT * FROM [nt:base]
+WHERE PATH([nt:base]) = '/a[2]/b'</programlisting></entry>
+ </row>
+ <row>
+ <entry><code>/jcr:root/a/b[2]//c[4]</code></entry>
+ <entry><programlisting>SELECT * FROM [my:type]
+WHERE PATH([nt:base]) = '/a/b[2]/c[4]'
+ OR PATH(nodeSet1) LIKE '/a/b[2]/%/c[4]'</programlisting></entry>
+ </row>
+ <row>
+ <entry><code>/jcr:root/a/b//c//d</code></entry>
+ <entry><programlisting>SELECT * FROM [my:type]
+WHERE PATH([nt:base]) = '/a/b/c/d'
+ OR PATH([nt:base]) LIKE '/a/b/%/c/d'
+ OR PATH([nt:base]) LIKE '/a/b/c/%/d'
+ OR PATH([nt:base]) LIKE '/a/b/%/c/%/d'</programlisting></entry>
+ </row>
+ <row>
+ <entry><code>//element(*,my:type)[@id<1 and @name='john']</code></entry>
+ <entry><programlisting>SELECT * FROM [my:type]
+WHERE id < 1 AND name = 'john'</programlisting></entry>
+ </row>
+ <row>
+ <entry><code>/jcr:root/a/b//element(*,my:type)</code></entry>
+ <entry><programlisting>SELECT * FROM [my:type]
+WHERE PATH([my:type]) = '/a/b/%'</programlisting></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ Note that the JCR-SQL2 language supported by JBoss DNA is capable of representing a wider
+ combination of path constraints.
+ </para>
+ </sect2>
+ <sect2 id="jcr-xpath-ordering-specifiers">
+ <title>Ordering Specifiers</title>
+ <para>
+ JCR 1.0 extends the XPath grammar to add support for ordering the results according to the
+ natural ordering of the values of one or more properties on the nodes.
+ </para>
+ <para>
+ JBoss DNA does support zero or more ordering specifiers, including whether each specifier
+ is ascending or descending. If no ordering specifiers are defined, the ordering of the results
+ is not predefined and may vary (though ordering by score is often the approach).
+ For example, the following table shows several XPath queries and how they map to JCR-SQL2 queries.
+ </para>
+ <table frame='all'>
+ <title>Specifying result ordering</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='0'>
+ <colspec colname='c1' colwidth="1*"/>
+ <colspec colname='c2' colwidth="1*"/>
+ <thead>
+ <row>
+ <entry>XPath</entry>
+ <entry>JCR-SQL2</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><code>//element(*,*) order by @title</code></entry>
+ <entry><programlisting>SELECT nodeSet1.title
+FROM [nt:base] AS nodeSet1
+ORDER BY nodeSet1.title</programlisting></entry>
+ </row>
+ <row>
+ <entry><code>//element(*,*) order by @title, @jcr:score</code></entry>
+ <entry><programlisting>SELECT nodeSet1.title
+FROM [nt:base] AS nodeSet1
+ORDER BY nodeSet1.title,
+ SCORE([nt:base])</programlisting></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ Note that the JCR-SQL2 language supported by JBoss DNA has a far richer <code>ORDER BY</code> clause,
+ allowing the use of any kind of dynamic operand, including ordering upon arithmetic operations
+ of multiple dynamic operands.
+ </para>
+ </sect2>
+ <sect2 id="jcr-xpath-misc">
+ <title>Miscellaneous</title>
+ <para>
+ JCR 1.0 defines a number of other optional and required features, and these are summarized in this section.
+ <itemizedlist>
+ <listitem>
+ <para>
+ Only abbreviated XPath syntax is supported.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Only the <code>child</code> axis (the default axis, represented by '/' in abbreviated syntax),
+ <code>descendant-or-self</code> axis (represented by '//' in abbreviated syntax),
+ <code>self</code> axis (represented by '.' in abbreviated syntax),
+ and <code>attribute</code> axis (represent by '@' in abbreviated syntax) are supported.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <code>text()</code> node test is <emphasis>not</emphasis> supported.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <code>element()</code> node test is supported.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <code>jcr:like()</code> function is supported.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <code>jcr:contains()</code> function is supported.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <code>jcr:score()</code> function is supported.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <code>jcr:deref()</code> function is <emphasis>not</emphasis> supported.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
</sect1>
+ <sect1 id="jcr-sql-query-language">
+ <title>JCR-SQL Query Language</title>
+ <para>
+ The JCR-SQL query language is defined by the <ulink url="&JSR170;">JCR 1.0 specification</ulink> as a way to express
+ queries using strings that are similar to SQL. Support for the language is optional, and in fact this language
+ was deprecated in the <ulink url="&JSR283;">JCR 2.0 specification</ulink> in favor of the improved and more powerful
+ (and more SQL-like) <link linkend="jcr-sql2-query-language">JCR-SQL2</link> language, which is covered in the next section.
+ As such, <emphasis role="strong">JBoss DNA does not support the original JCR-SQL language</emphasis>.
+ </para>
+ </sect1>
<sect1 id="jcr-sql2-query-language">
<title>JCR-SQL2 Query Language</title>
<para>
The JCR-SQL2 query language is defined by the <ulink url="&JSR283;">JCR 2.0 specification</ulink> as a way to express
- queries using strings that are similar to SQL. JBoss DNA includes full support for this query language, and even
- adds several extensions to make it even more powerful.
+ queries using strings that are similar to SQL. This query language is an improvement over the earlier JCR-SQL language,
+ which has been deprecated in JCR 2.0 (see previous section).
</para>
+ <para>
+ JBoss DNA includes full support for the complete JCR-SQL2 query language.
+ However, JBoss DNA adds several extensions to make it even more powerful:
+ <itemizedlist>
+ <listitem>
+ <para>
+ Support for the "<code>FULL OUTER JOIN</code>" and "<code>CROSS JOIN</code>" join types, in addition to the
+ "<code>LEFT OUTER JOIN</code>", "<code>RIGHT OUTER JOIN</code>" and "<code>INNER JOIN</code>" types defined by
+ JCR-SQL2. Note that "<code>JOIN</code>" is a shorthand for "<code>INNER JOIN</code>".
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Support for the <code>UNION</code>, <code>INTERSECT</code>, and <code>EXCEPT</code> set operations on multiple result
+ sets to form a single result set. As with standard SQL, the result sets being combined must have the same columns.
+ The <code>UNION</code> operator combines the rows from two result sets, the <code>INTERSECT</code> operator returns
+ the difference between two result sets, and the <code>EXCEPT</code> operator returns the rows that are common to
+ two result sets. Duplicate rows are removed unless the operator is followed by the <code>ALL</code> keyword.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Removal of duplicate rows in the results, using "<code>SELECT DISTINCT ...</code>".
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Limiting the number of rows in the result set with the "<code>LIMIT count</code>" clause, where <code>count</code>
+ is the maximum number of rows that should be returned. This clause may optionally be followed by the
+ "<code>OFFSET number</code>" clause to specify the number of initial rows that should be skipped.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Additional dynamic operands "<code>DEPTH([<selectorName>])</code>" and "<code>PATH([<selectorName>])</code>"
+ that enable placing constraints on the node depth and path, respectively. These dynamic operands
+ can be used in a manner similar to "<code>NAME([<selectorName>])</code>" and "<code>LOCALNAME([<selectorName>])</code>"
+ that are defined by JCR-SQL2. Note in each of these cases, the selector name is optional if there is only one
+ selector in the query.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Support for the <code>IN</code> and <code>NOT IN</code> clauses to more easily and concisely supply multiple
+ of discreet static operands: "<code><dynamicOperand> [NOT] IN (<staticOperand> {, <staticOperand>})"</code>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Support for the <code>BETWEEN</code> clause to more easily and concisely supply a range of discreet operands:
+ "<code><dynamicOperand> [NOT] BETWEEN <lowerBoundStaticOperand> [EXCLUSIVE] AND <upperBoundStaticOperand> [EXCLUSIVE]</code>"
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Support for simple arithmetic in numeric-based criteria and order-by clauses. For example,
+ "<code>... WHERE SCORE(type1) + SCORE(type2) > 1.0</code>" or "<code>... ORDER BY (SCORE(type1) * SCORE(type2)) ASC</code>".
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <sect2 id="jcr-sql2-grammar">
+ <title>Grammar</title>
+ <para>
+ The grammar for the JCR-SQL2 query language is actually a superset of that defined by the
+ <ulink url="&JSR283;">JCR 2.0 specification</ulink>, and as such the complete grammar is included here.
+ </para>
+ <note>
+ <para>
+ The grammar is presented using the same EBNF nomenclature as used in the JCR 2.0 specification.
+ Terms are surrounded by '[' and ']' denote optional terms that appear zero or one times.
+ Terms surrounded by '{' and '}' denote terms that appear zero or more times.
+ Parentheses are used to identify groups, and are often used to surround possible values.
+ </para>
+ </note>
+ <sect3>
+ <title>Queries</title>
+<programlisting><![CDATA[
+QueryCommand ::= Query | SetQuery
+
+SetQuery ::= Query ('UNION'|'INTERSECT'|'EXCEPT') [ALL] Query
+ { ('UNION'|'INTERSECT'|'EXCEPT') [ALL] Query }
+
+Query ::= 'SELECT' ['DISTINCT'] columns
+ 'FROM' Source
+ ['WHERE' Constraint]
+ ['ORDER BY' orderings]
+ [Limit]
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Sources</title>
+<programlisting><![CDATA[
+Source ::= Selector | Join
+
+Selector ::= nodeTypeName ['AS' selectorName]
+
+nodeTypeName ::= Name
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Joins</title>
+<programlisting><![CDATA[
+
+Join ::= left [JoinType] 'JOIN' right 'ON' JoinCondition
+ // If JoinType is omitted INNER is assumed.
+
+left ::= Source
+right ::= Source
+
+JoinType ::= Inner | LeftOuter | RightOuter | FullOuter | Cross
+
+Inner ::= 'INNER' ['JOIN']
+
+LeftOuter ::= 'LEFT JOIN' | 'OUTER JOIN' | 'LEFT OUTER JOIN'
+
+RightOuter ::= 'RIGHT OUTER' ['JOIN']
+
+RightOuter ::= 'FULL OUTER' ['JOIN']
+
+RightOuter ::= 'CROSS' ['JOIN']
+
+JoinCondition ::= EquiJoinCondition | SameNodeJoinCondition |
+ ChildNodeJoinCondition | DescendantNodeJoinCondition
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Equi-Join Conditions</title>
+<programlisting><![CDATA[
+
+EquiJoinCondition ::= selector1Name'.'property1Name '=' selector2Name'.'property2Name
+
+selector1Name ::= selectorName
+selector2Name ::= selectorName
+property1Name ::= propertyName
+property2Name ::= propertyName
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Same-Node Join Conditions</title>
+<programlisting><![CDATA[
+
+SameNodeJoinCondition ::= 'ISSAMENODE(' selector1Name ',' selector2Name [',' selector2Path] ')'
+
+selector2Path ::= Path
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Child-Node Join Conditions</title>
+<programlisting><![CDATA[
+
+ChildNodeJoinCondition ::= 'ISCHILDNODE(' childSelectorName ',' parentSelectorName ')'
+
+childSelectorName ::= selectorName
+parentSelectorName ::= selectorName
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Descendant-Node Join Conditions</title>
+<programlisting><![CDATA[
+
+DescendantNodeJoinCondition ::= 'ISDESCENDANTNODE(' descendantSelectorName
+ ',' ancestorSelectorName ')'
+descendantSelectorName ::= selectorName
+ancestorSelectorName ::= selectorName
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Constraints</title>
+<programlisting><![CDATA[
+
+Constraint ::= ConstraintItem | '(' ConstraintItem ')'
+
+ConstraintItem ::= And | Or | Not | Comparison | Between | PropertyExistence |
+ SetConstraint | FullTextSearch | SameNode | ChildNode | DescendantNode
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>And Constraints</title>
+<programlisting><![CDATA[
+
+And ::= constraint1 'AND' constraint2
+
+constraint1 ::= Constraint
+constraint2 ::= Constraint
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Or Constraints</title>
+<programlisting><![CDATA[
+
+Or ::= constraint1 'OR' constraint2
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Not Constraints</title>
+<programlisting><![CDATA[
+
+Not ::= 'NOT' Constraint
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Comparison Constraints</title>
+<programlisting><![CDATA[
+
+Comparison ::= DynamicOperand Operator StaticOperand
+
+Operator ::= '=' | '!=' | '<' | '<=' | '>' | '>=' | 'LIKE'
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Between Constraints</title>
+<programlisting><![CDATA[
+
+Between ::= DynamicOperand ['NOT'] 'BETWEEN' lowerBound ['EXCLUSIVE']
+ 'AND' upperBound ['EXCLUSIVE']
+
+lowerBound ::= StaticOperand
+upperBound ::= StaticOperand
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Property Existence Constraints</title>
+<programlisting><![CDATA[
+
+PropertyExistence ::= selectorName'.'propertyName 'IS' ['NOT'] 'NULL' |
+ propertyName 'IS' ['NOT'] 'NULL' /* If only one selector exists in this query */
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Set Constraints</title>
+<programlisting><![CDATA[
+
+SetConstraint ::= selectorName'.'propertyName ['NOT'] 'IN' |
+ propertyName ['NOT'] 'IN' /* If only one selector exists in this query */
+ '(' firstStaticOperand {',' additionalStaticOperand } ')'
+firstStaticOperand ::= StaticOperand
+additionalStaticOperand ::= StaticOperand
+
+]]></programlisting>
+ </sect3>
+ <sect3 id="jcr-sql2-full-text-search-constraints">
+ <title>Full-text Search Constraints</title>
+<programlisting><![CDATA[
+
+FullTextSearch ::= 'CONTAINS(' ([selectorName'.']propertyName | selectorName'.*')
+ ',' ''' fullTextSearchExpression''' ')'
+ /* If only one selector exists in this query, explicit specification of the selectorName
+ preceding the propertyName is optional */
+fullTextSearchExpression ::= /* a full-text search expression, see FullTextSearchParser */
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Same-Node Constraint</title>
+<programlisting><![CDATA[
+
+SameNode ::= 'ISSAMENODE(' [selectorName ','] Path ')'
+ /* If only one selector exists in this query, explicit specification of the selectorName
+ preceding the path is optional */
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Child-Node Constraints</title>
+<programlisting><![CDATA[
+
+ChildNode ::= 'ISCHILDNODE(' [selectorName ','] Path ')'
+ /* If only one selector exists in this query, explicit specification of the selectorName
+ preceding the path is optional */
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Descendant-Node Constraints</title>
+<programlisting><![CDATA[
+
+DescendantNode ::= 'ISDESCENDANTNODE(' [selectorName ','] Path ')'
+ /* If only one selector exists in this query, explicit specification of the selectorName
+ preceding the propertyName is optional */
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Paths and Names</title>
+<programlisting><![CDATA[
+
+Name ::= '[' quotedName ']' | '[' simpleName ']' | simpleName
+
+quotedName ::= /* A JCR Name (see the JCR specification) */
+simpleName ::= /* A JCR Name that contains only SQL-legal
+ characters (namely letters, digits, and underscore) */
+
+Path ::= '[' quotedPath ']' | '[' simplePath ']' | simplePath
+
+quotedPath ::= /* A JCR Path that contains non-SQL-legal characters */
+simplePath ::= /* A JCR Path (rather Name) that contains only SQL-legal
+ characters (namely letters, digits, and underscore) */
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Static Operands</title>
+<programlisting><![CDATA[
+
+StaticOperand ::= Literal | BindVariableValue
+
+Literal
+Literal ::= CastLiteral | UncastLiteral
+
+CastLiteral ::= 'CAST(' UncastLiteral ' AS ' PropertyType ')'
+
+PropertyType ::= 'STRING' | 'BINARY' | 'DATE' | 'LONG' | 'DOUBLE' | 'DECIMAL' |
+ 'BOOLEAN' | 'NAME' | 'PATH' | 'REFERENCE' | 'WEAKREFERENCE' | 'URI'
+ /* 'WEAKREFERENCE' is not currently supported in JCR 1.0 */
+
+UncastLiteral ::= UnquotedLiteral | ''' UnquotedLiteral ''' | '"' UnquotedLiteral '"'
+
+UnquotedLiteral ::= /* String form of a JCR Value, as defined in the JCR specification */
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Bind Variables</title>
+<programlisting><![CDATA[
+
+BindVariableValue ::= '$'bindVariableName
+
+bindVariableName ::= /* A string that conforms to the JCR Name syntax, though the prefix
+ does not need to be a registered namespace prefix. */
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Dynamic Operands</title>
+<programlisting><![CDATA[
+
+DynamicOperand ::= PropertyValue | Length | NodeName | NodeLocalName | NodePath | NodeDepth |
+ FullTextSearchScore | LowerCase | UpperCase | Arithmetic |
+ '(' DynamicOperand ')'
+
+PropertyValue ::= [selectorName'.'] propertyName
+ /* If only one selector exists in this query, explicit specification of the selectorName
+ preceding the propertyName is optional */
+
+Length ::= 'LENGTH(' PropertyValue ')'
+
+NodeName ::= 'NAME(' [selectorName] ')'
+ /* If only one selector exists in this query, explicit specification of the selectorName
+ is optional */
+
+NodeLocalName ::= 'LOCALNAME(' [selectorName] ')'
+ /* If only one selector exists in this query, explicit specification of the selectorName
+ is optional */
+
+NodePath ::= 'PATH(' [selectorName] ')'
+ /* If only one selector exists in this query, explicit specification of the selectorName
+ is optional */
+
+NodeDepth ::= 'DEPTH(' [selectorName] ')'
+ /* If only one selector exists in this query, explicit specification of the selectorName
+ is optional */
+
+FullTextSearchScore ::= 'SCORE(' [selectorName] ')'
+ /* If only one selector exists in this query, explicit specification of the selectorName
+ is optional */
+
+LowerCase ::= 'LOWER(' DynamicOperand ')'
+
+UpperCase ::= 'UPPER(' DynamicOperand ')'
+
+Arithmetic ::= DynamicOperand ('+'|'-'|'*'|'/') DynamicOperand
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Ordering</title>
+<programlisting><![CDATA[
+
+orderings ::= Ordering {',' Ordering}
+
+Ordering ::= DynamicOperand [Order]
+
+Order ::= 'ASC' | 'DESC'
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Columns</title>
+<programlisting><![CDATA[
+
+columns ::= (Column ',' {Column}) | '*'
+
+Column ::= ([selectorName'.']propertyName ['AS' columnName]) | (selectorName'.*')
+ /* If only one selector exists in this query, explicit specification of the selectorName
+ preceding the propertyName is optional */
+selectorName ::= Name
+propertyName ::= Name
+columnName ::= Name
+
+]]></programlisting>
+ </sect3>
+ <sect3>
+ <title>Limit and Offset</title>
+<programlisting><![CDATA[
+
+Limit ::= 'LIMIT' count [ 'OFFSET' offset ]
+count ::= /* Positive integer value */
+offset ::= /* Non-negative integer value */
+]]></programlisting>
+ </sect3>
+ </sect2>
</sect1>
<sect1 id="fulltext-search-query-language">
<title>Full-Text Search Language</title>
@@ -59,8 +922,9 @@
you to use the JCR query API but with a far simpler, Google-style search grammar.
</para>
<para>
- This query language is actually defined by the <ulink url="&JSR283;">JCR 2.0 specification</ulink> as the full-text
- search expression grammar used in the second parameter of the <code>CONTAINS(...)</code> function of the JCR-SQL2 language.
+ This query language is actually defined by the <ulink url="&JSR283;">JCR 2.0 specification</ulink> as the
+ <link linkend="jcr-sql2-full-text-search-constraint">full-text search expression grammar</link>
+ used in the second parameter of the <code>CONTAINS(...)</code> function of the JCR-SQL2 language.
We just pulled it out and made it available as a first-class query language.
</para>
<para>
@@ -90,7 +954,15 @@
<title>Grammar</title>
<para>
The grammar for this full-text search language is specified in Section 6.7.19 of the
- <ulink url="&JSR283;">JCR 2.0 specification</ulink>, but it is also included here as a convenience:
+ <ulink url="&JSR283;">JCR 2.0 specification</ulink>, but it is also included here as a convenience.
+ <note>
+ <para>
+ The grammar is presented using the same EBNF nomenclature as used in the JCR 2.0 specification.
+ Terms are surrounded by '[' and ']' denote optional terms that appear zero or one times.
+ Terms surrounded by '{' and '}' denote terms that appear zero or more times.
+ Parentheses are used to identify groups, and are often used to surround possible values.
+ </para>
+ </note>
</para>
<programlisting><![CDATA[
Modified: trunk/docs/reference/src/main/docbook/en-US/custom.dtd
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/custom.dtd 2010-01-10 03:07:50 UTC (rev 1579)
+++ trunk/docs/reference/src/main/docbook/en-US/custom.dtd 2010-01-10 07:10:48 UTC (rev 1580)
@@ -78,6 +78,7 @@
<!ENTITY QueryResult "<interface>QueryResult</interface>">
<!ENTITY NodeIterator "<interface>NodeIterator</interface>">
<!ENTITY RowIterator "<interface>RowIterator</interface>">
+<!ENTITY Node "<interface>Node</interface>">
<!-- Types in dna-common -->
14 years, 4 months
DNA SVN: r1579 - trunk/extensions/dna-connector-store-jpa/src/main/java/org/jboss/dna/connector/store/jpa/model/basic.
by dna-commits@lists.jboss.org
Author: rhauch
Date: 2010-01-09 22:07:50 -0500 (Sat, 09 Jan 2010)
New Revision: 1579
Modified:
trunk/extensions/dna-connector-store-jpa/src/main/java/org/jboss/dna/connector/store/jpa/model/basic/BasicJpaConnection.java
Log:
DNA-617 BasicJpaConnection no longer needs the EntityManager field, since a new one is always checked out and checked in within the execute(...) method. The same behavior was added to the ping(...) method.
Modified: trunk/extensions/dna-connector-store-jpa/src/main/java/org/jboss/dna/connector/store/jpa/model/basic/BasicJpaConnection.java
===================================================================
--- trunk/extensions/dna-connector-store-jpa/src/main/java/org/jboss/dna/connector/store/jpa/model/basic/BasicJpaConnection.java 2010-01-10 00:38:45 UTC (rev 1578)
+++ trunk/extensions/dna-connector-store-jpa/src/main/java/org/jboss/dna/connector/store/jpa/model/basic/BasicJpaConnection.java 2010-01-10 03:07:50 UTC (rev 1579)
@@ -48,7 +48,6 @@
private final String name;
private final CachePolicy cachePolicy;
private final EntityManagers entityManagers;
- private EntityManager entityManager;
private final UUID rootNodeUuid;
private final String nameOfDefaultWorkspace;
private final String[] predefinedWorkspaceNames;
@@ -76,8 +75,6 @@
this.name = sourceName;
this.cachePolicy = cachePolicy; // may be null
this.entityManagers = entityManagers;
- // this.entityManager = entityManagers.checkout();
- // assert this.entityManagers != null;
this.rootNodeUuid = rootNodeUuid;
this.largeValueMinimumSizeInBytes = largeValueMinimumSizeInBytes;
this.compressData = compressData;
@@ -121,7 +118,12 @@
*/
public boolean ping( long time,
TimeUnit unit ) {
- return entityManager != null ? entityManager.isOpen() : false;
+ EntityManager entityManager = entityManagers.checkout();
+ try {
+ return entityManager != null ? entityManager.isOpen() : false;
+ } finally {
+ entityManagers.checkin(entityManager);
+ }
}
/**
@@ -141,10 +143,10 @@
}
RequestProcessor processor = null;
+ EntityManager entityManager = null;
boolean commit = true;
-
try {
- this.entityManager = entityManagers.checkout();
+ entityManager = entityManagers.checkout();
if (entityManager == null) {
throw new RepositorySourceException(JpaConnectorI18n.connectionIsNoLongerOpen.text(name));
@@ -161,37 +163,39 @@
commit = false;
}
} finally {
- try {
- processor.close();
- } finally {
- // Now commit or rollback ...
+ if (processor != null) {
try {
- EntityTransaction txn = entityManager.getTransaction();
- if (txn != null) {
- if (commit) {
- // Now commit the transaction ...
- txn.commit();
- } else {
- // Need to rollback the changes made to the repository ...
- txn.rollback();
+ processor.close();
+ } finally {
+ // Now commit or rollback ...
+ try {
+ EntityTransaction txn = entityManager.getTransaction();
+ if (txn != null) {
+ if (commit) {
+ // Now commit the transaction ...
+ txn.commit();
+ } else {
+ // Need to rollback the changes made to the repository ...
+ txn.rollback();
+ }
}
+ } catch (Throwable commitOrRollbackError) {
+ if (commit && !request.hasError()) {
+ // Record the error on the request ...
+ request.setError(commitOrRollbackError);
+ }
+ commit = false; // couldn't do it
}
- } catch (Throwable commitOrRollbackError) {
- if (commit && !request.hasError()) {
- // Record the error on the request ...
- request.setError(commitOrRollbackError);
+ if (commit) {
+ // Now that we're not in a transaction anymore, notify the observer of the committed changes ...
+ processor.notifyObserverOfChanges();
}
- commit = false; // couldn't do it
}
- if (commit) {
- // Now that we're not in a transaction anymore, notify the observer of the committed changes ...
- processor.notifyObserverOfChanges();
- }
}
// Do this only once ...
try {
- entityManagers.checkin(entityManager);
+ entityManagers.checkin(entityManager); // even if null
} finally {
entityManager = null;
}
14 years, 4 months
DNA SVN: r1578 - trunk/extensions/dna-connector-store-jpa/src/main/java/org/jboss/dna/connector/store/jpa/model/basic.
by dna-commits@lists.jboss.org
Author: bcarothers
Date: 2010-01-09 19:38:45 -0500 (Sat, 09 Jan 2010)
New Revision: 1578
Modified:
trunk/extensions/dna-connector-store-jpa/src/main/java/org/jboss/dna/connector/store/jpa/model/basic/BasicJpaConnection.java
Log:
DNA-617 NPE while updating indexes (during integration tests)
Attach patch that corrects the behavior of the BasicJpaConnector with regard to EntityManager lifetime.
Prior to the patch, the BJC obtained an EntityManager in its constructor and released the EntityManager in its close method. The typical lifecycle for a connection is a call to the constructor followed by a single call to execute(...) followed by a call to close(). With this lifecycle, the EntityManager is only used for one call to execute(...) and the transaction is committed or rolled back after the call as appropriate.
Now that the RepositoryConnectionPool is being used (and was fixed to reuse connections), the typical lifecycle is one call to the constructor followed by multiple calls to execute(...) within different transactions followed by (eventually) a call to close(). Since the same EntityManager was being held for the entire life of the BJC object, the EntityManager would be used for multiple transactions without any attempt being made to clear out its cache. We're using Hibernate as our JPA implementation, so the Hibernate session cache was gradually accumulating copies of the data in the database _that were gradually falling out of sync with the database_.
In other words, BJC1 would be used to create a node and set a property leaving the ChildEntity and the PropertiesEntity for the node in the Hibernate session cache for BJC1's EntityManager. BJC2 would then be used to read the same node and update its property. Since the entities for the node weren't yet in in the session cache for BJC2's EntityManager, BJC2 would execute select statements to load the necessary data and would perform the updates. THEN in a subsequent call, BJC1 would be reused to read from the same node. Since BJC already had the ChildEntity and PropertiesEntity for the node in its session cache, it would reuse the cached (and now stale) versions instead of trying to hit the database. Hilarity ensued.
The patch makes BJC obtain an EntityManager at the beginning of the execute(...) call and release the EntityManager at the end of the execute(...) call. Since "released" EntityManager objects are really closed by the EntityManagers factory object, this will cure the session cache issue.
This fixes all but 5 of the TCK failures with the JPA connector using the basic model.
Modified: trunk/extensions/dna-connector-store-jpa/src/main/java/org/jboss/dna/connector/store/jpa/model/basic/BasicJpaConnection.java
===================================================================
--- trunk/extensions/dna-connector-store-jpa/src/main/java/org/jboss/dna/connector/store/jpa/model/basic/BasicJpaConnection.java 2010-01-09 22:27:32 UTC (rev 1577)
+++ trunk/extensions/dna-connector-store-jpa/src/main/java/org/jboss/dna/connector/store/jpa/model/basic/BasicJpaConnection.java 2010-01-10 00:38:45 UTC (rev 1578)
@@ -76,8 +76,8 @@
this.name = sourceName;
this.cachePolicy = cachePolicy; // may be null
this.entityManagers = entityManagers;
- this.entityManager = entityManagers.checkout();
- assert this.entityManagers != null;
+ // this.entityManager = entityManagers.checkout();
+ // assert this.entityManagers != null;
this.rootNodeUuid = rootNodeUuid;
this.largeValueMinimumSizeInBytes = largeValueMinimumSizeInBytes;
this.compressData = compressData;
@@ -132,9 +132,6 @@
*/
public void execute( ExecutionContext context,
Request request ) throws RepositorySourceException {
- if (entityManager == null) {
- throw new RepositorySourceException(JpaConnectorI18n.connectionIsNoLongerOpen.text(name));
- }
Logger logger = context.getLogger(getClass());
Stopwatch sw = null;
@@ -142,14 +139,21 @@
sw = new Stopwatch();
sw.start();
}
- // Do any commands update/write?
- RequestProcessor processor = new BasicRequestProcessor(name, context, observer, entityManager, rootNodeUuid,
- nameOfDefaultWorkspace, predefinedWorkspaceNames,
- largeValueMinimumSizeInBytes, creatingWorkspacesAllowed,
- compressData, enforceReferentialIntegrity);
+ RequestProcessor processor = null;
boolean commit = true;
+
try {
+ this.entityManager = entityManagers.checkout();
+
+ if (entityManager == null) {
+ throw new RepositorySourceException(JpaConnectorI18n.connectionIsNoLongerOpen.text(name));
+ }
+
+ // Do any commands update/write?
+ processor = new BasicRequestProcessor(name, context, observer, entityManager, rootNodeUuid, nameOfDefaultWorkspace,
+ predefinedWorkspaceNames, largeValueMinimumSizeInBytes,
+ creatingWorkspacesAllowed, compressData, enforceReferentialIntegrity);
// Obtain the lock and execute the commands ...
processor.process(request);
if (request.hasError() && !request.isReadOnly()) {
@@ -184,7 +188,15 @@
processor.notifyObserverOfChanges();
}
}
+
+ // Do this only once ...
+ try {
+ entityManagers.checkin(entityManager);
+ } finally {
+ entityManager = null;
+ }
}
+
if (logger.isTraceEnabled()) {
assert sw != null;
sw.stop();
@@ -198,14 +210,6 @@
* @see org.jboss.dna.graph.connector.RepositoryConnection#close()
*/
public void close() {
- if (entityManager != null) {
- // Do this only once ...
- try {
- entityManagers.checkin(entityManager);
- } finally {
- entityManager = null;
- }
- }
}
}
14 years, 4 months
DNA SVN: r1577 - trunk/dna-jcr/src/main/java/org/jboss/dna/jcr.
by dna-commits@lists.jboss.org
Author: rhauch
Date: 2010-01-09 17:27:32 -0500 (Sat, 09 Jan 2010)
New Revision: 1577
Modified:
trunk/dna-jcr/src/main/java/org/jboss/dna/jcr/JndiRepositoryFactory.java
Log:
Added missing JavaDoc @return parameter.
Modified: trunk/dna-jcr/src/main/java/org/jboss/dna/jcr/JndiRepositoryFactory.java
===================================================================
--- trunk/dna-jcr/src/main/java/org/jboss/dna/jcr/JndiRepositoryFactory.java 2010-01-09 22:09:07 UTC (rev 1576)
+++ trunk/dna-jcr/src/main/java/org/jboss/dna/jcr/JndiRepositoryFactory.java 2010-01-09 22:27:32 UTC (rev 1577)
@@ -30,11 +30,11 @@
* <pre>
* <GlobalNamingResources>
* <!-- Other configuration omitted -->
- * <Resource name="jcr/local" auth="Container"
- * type="javax.jcr.Repository"
- * factory="org.jboss.dna.jcr.JndiRepositoryFactory"
- * configFile="/tck/default/configRepository.xml"
- * repositoryName="Test Repository Source"
+ * <Resource name="jcr/local" auth="Container"
+ * type="javax.jcr.Repository"
+ * factory="org.jboss.dna.jcr.JndiRepositoryFactory"
+ * configFile="/tck/default/configRepository.xml"
+ * repositoryName="Test Repository Source"
* />
* </GlobalNamingResources>
* </pre>
@@ -110,6 +110,7 @@
* @param name ignored
* @param nameCtx ignored
* @param environment ignored
+ * @return the repository; never null
* @throws IOException if there is an error or problem reading the configuration resource at the supplied path
* @throws SAXException if the contents of the configuration resource are not valid XML
* @throws NamingException if there is an error registering the namespace listener
14 years, 4 months
DNA SVN: r1576 - trunk/docs/reference/src/main/docbook/en-US/content/jcr.
by dna-commits@lists.jboss.org
Author: rhauch
Date: 2010-01-09 17:09:07 -0500 (Sat, 09 Jan 2010)
New Revision: 1576
Modified:
trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml
Log:
DNA-621 Updated the Reference Guide section that talks about the levels of JCR support.
Modified: trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml 2010-01-09 22:08:50 UTC (rev 1575)
+++ trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml 2010-01-09 22:09:07 UTC (rev 1576)
@@ -214,11 +214,14 @@
<sect2>
<title>Optional Features</title>
<para>
- JBoss DNA does currently supports the optional JCR locking and observation features.
+ JBoss DNA does currently supports the optional JCR locking and observation features (though there still are
+ a few known issues with our implementation of observation).
<note>
<para>
- The JCR-SQL optional feature is not planned to be implemented as it has been dropped from the <ulink url="&JSR283;">JSR-283</ulink> specification.
- Instead, JBoss DNA supports the JCR-SQL2 query language defined by the <ulink url="&JSR283;">JSR-283</ulink> specification.
+ The JCR-SQL optional feature of <ulink url="&JSR170;">JSR-170</ulink> is not planned to be implemented
+ as it has been dropped from the <ulink url="&JSR283;">JSR-283</ulink> specification.
+ Instead, JBoss DNA already supports its replacement, the JCR-SQL2 query language defined by the
+ <ulink url="&JSR283;">JSR-283</ulink> specification.
For details, see the chapter on <link linkend="jcr-query-and-search">queries and search languages</link>.
</para>
</note>
14 years, 4 months
DNA SVN: r1575 - trunk/docs/reference/src/main/docbook/en-US/content/jcr.
by dna-commits@lists.jboss.org
Author: rhauch
Date: 2010-01-09 17:08:50 -0500 (Sat, 09 Jan 2010)
New Revision: 1575
Modified:
trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml
Log:
DNA-621 Updated the Reference Guide section that talks about the levels of JCR support.
Modified: trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml 2010-01-09 21:31:34 UTC (rev 1574)
+++ trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml 2010-01-09 22:08:50 UTC (rev 1575)
@@ -194,7 +194,8 @@
<sect1>
<title>JCR Specification Support</title>
<para>
- The JBoss DNA JCR implementation will not be JCR-compliant prior to the 1.0 release. Additionally, the JCR
+ The JBoss DNA JCR implementation is actually very close to being JCR-compliant, but it only passes about 96% of the JCR TCK.
+ Our goal is to pass 100% of the TCK tests by the 1.0 release. Additionally, the JCR
specification allows some latitude to implementors for some implementation details. The sections below
clarify JBoss DNA's current and planned behavior. <emphasis>As always, please consult the
<ulink url="&Roadmap;">current list of known issues and bugs</ulink>.</emphasis>
@@ -202,20 +203,23 @@
<sect2>
<title>L1 and L2 Features</title>
<para>
- JBoss DNA currently supports most of the Level 1 and Level 2 feature set defined by the <ulink url="&JSR170;">JSR-170</ulink> specification.
- Queries, which are part of Level 1, are not implemented. Referential integrity for <code>REFERENCE</code> properties, a Level 2 feature, is also not yet implemented.
- As the current implementation does provide many of the features that may be needed by an application, we really hope that this release will allow you to give us
- some feedback on what we have so far.
+ JBoss DNA currently supports all Level 1 features and most of the Level 2 features defined by the
+ <ulink url="&JSR170;">JSR-170</ulink> specification.
+ This release adds support for queries, which is described in more detail in <link linkend="jcr-query-and-search">later</link>.
+ However, referential integrity for <code>REFERENCE</code> properties, a Level 2 feature, is not yet implemented.
+ As the current implementation does provide many of the features that may be needed by an application, we really hope
+ that this release will allow you to give us some feedback on what we have so far.
</para>
</sect2>
<sect2>
<title>Optional Features</title>
<para>
- JBoss DNA does currently supports the optional JCR locking feature. Currently, the observation optional feature is planned to be complete prior
- to the 1.0 release.
+ JBoss DNA does currently supports the optional JCR locking and observation features.
<note>
<para>
The JCR-SQL optional feature is not planned to be implemented as it has been dropped from the <ulink url="&JSR283;">JSR-283</ulink> specification.
+ Instead, JBoss DNA supports the JCR-SQL2 query language defined by the <ulink url="&JSR283;">JSR-283</ulink> specification.
+ For details, see the chapter on <link linkend="jcr-query-and-search">queries and search languages</link>.
</para>
</note>
</para>
14 years, 4 months