[dna-commits] DNA SVN: r1584 - in trunk/docs: gettingstarted/src/main/docbook/en-US/content and 2 other directories.
dna-commits at lists.jboss.org
dna-commits at lists.jboss.org
Sun Jan 10 10:56:55 EST 2010
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-connectors-part.html">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-connectors-part.html">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>">
More information about the dna-commits
mailing list