10:23 a.m.
Author: bcarothers
Date: 2009-12-19 11:23:31 -0500 (Sat, 19 Dec 2009)
New Revision: 1465
Modified:
trunk/docs/reference/src/main/docbook/en-US/content/connectors/jdbc_metadata.xml
trunk/docs/reference/src/main/docbook/en-US/content/connectors/jdbc_storage.xml
trunk/docs/reference/src/main/docbook/en-US/custom.dtd
trunk/docs/reference/src/main/docbook/en-US/master.xml
Log:
DNA-594 The JDBC Metadata Connector documentation in Reference Guide is missing
Applied patch that fixes the link to the JDBC metadata connector page and brings it up to
the same standard as the other connector pages in the reference guide. Also corrects a
few typos in the JPA connector page.
The patch doesn't explicitly list the connector as "experimental" or
"technology preview" yet because I'm pretty confident that I'll at least
be able to test it against MSSQL and Oracle prior to the 0.7 release. The page does list
the drivers that the connector has been tested against.
Modified:
trunk/docs/reference/src/main/docbook/en-US/content/connectors/jdbc_metadata.xml
===================================================================
---
trunk/docs/reference/src/main/docbook/en-US/content/connectors/jdbc_metadata.xml 2009-12-19
14:06:33 UTC (rev 1464)
+++
trunk/docs/reference/src/main/docbook/en-US/content/connectors/jdbc_metadata.xml 2009-12-19
16:23:31 UTC (rev 1465)
@@ -31,9 +31,200 @@
<chapter id="jdbc-metadata-connector">
<title>JDBC Metadata Connector</title>
<para>
- This connector is a prototype that provides read-only access to the database schema
(metadata) from relational databases through a JDBC
- connection.
- <emphasis>This is still under development.</emphasis>
+ This connector provides read-only access to the metadata (e.g., catalogs, schemas,
table structures) of a relational database.
+ The connector yields a content graph that looks like this:
+<programlisting>
+/ (root node)
+ + <catalog name> - one node for each accessible catalog in the
database.
+ + <schema name> - one node for each accessible schema in the
catalog.
+ + tables - a single node that is the parent of all tables in the schema.
+ | + <table name> - one node for each table in the schema.
+ | + <column name> - one node for each column in the
table.
+ + procedures - a single node that is the parent of all procedures in the
schema.
+ + <procedure name> - one node for each procedure in the
schema.
+</programlisting>
+ The root, table, column, and procedure nodes contain additional properties that
correspond to the metadata provide by the
+ &DatabaseMetaData; class. In databases that do not support catalogs or schemas (or
allow the empty string as a valid
+ catalog or schema name, the value of the <code>defaultCatalogName</code>
and/or <code>defaultSchemaName</code> properties
+ will be used instead when determining the graph name.
+ <note>
+ <para>
+ This connector has currently been tested successfully against MySQL 5 (with the InnoDB
engine), PostgreSQL 8, and HSQLDB.
+ As JDBC driver implementations of the &DatabaseMetaData; interface tend to vary
widely, other databases may or may not work
+ with the default &MetadataCollector; implementation. We are, of course,
interested in correcting any database-specific issues
+ that arise, but the <code>metadataCollectorClassName</code> property
provides a mechanism to support immediate workarounds.
+ </para>
+ </note>
</para>
+ <para>
+ The &JdbcMetadataSource; class provides a number of JavaBean properties that
control its behavior:
+ </para>
+ <table frame='all'>
+ <title>&JdbcMetadataSource; properties</title>
+ <tgroup cols='2' align='left' colsep='1'
rowsep='1'>
+ <colspec colname='c1' colwidth="1*"/>
+ <colspec colname='c2' colwidth="1*"/>
+ <thead>
+ <row>
+ <entry>Property</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>name</entry>
+ <entry>The name of the repository source, which is used by the
&RepositoryService; when obtaining a &RepositoryConnection; by
name.</entry>
+ </row>
+ <row>
+ <entry>rootNodeUuid</entry>
+ <entry>Optional property that, if used, defines the UUID of the root node in
the in-memory repository. If not used,
+ then a new UUID is generated.</entry>
+ </row>
+ <row>
+ <entry>nameOfDefaultWorkspace</entry>
+ <entry>Optional property that is initialized to an empty string and which
defines the name for the workspace that will be used by default
+ if none is specified.</entry>
+ </row>
+ <row>
+ <entry>dataSourceJndiName</entry>
+ <entry>
+ The JNDI name of the JDBC DataSource instance that should be used. If not
specified, the other driver properties must be set.
+ </entry>
+ </row>
+ <row>
+ <entry>driverClassName</entry>
+ <entry>
+ The name of the JDBC driver class.
+ This is not required if the DataSource is found in JNDI, but is required
otherwise.
+ </entry>
+ </row>
+ <row>
+ <entry>driverClassloaderName</entry>
+ <entry>
+ The name of the <!-- link linkend="class_loader_factory" -->class
loader or classpath<!-- /link --> that should be used to load the JDBC driver
class.
+ This is not required if the DataSource is found in JNDI.
+ </entry>
+ </row>
+ <row>
+ <entry>url</entry>
+ <entry>
+ The URL that should be used when creating JDBC connections using the JDBC driver
class.
+ This is not required if the DataSource is found in JNDI.
+ </entry>
+ </row>
+ <row>
+ <entry>username</entry>
+ <entry>
+ The username that should be used when creating JDBC connections using the JDBC
driver class.
+ This is not required if the DataSource is found in JNDI.
+ </entry>
+ </row>
+ <row>
+ <entry>password</entry>
+ <entry>
+ The password that should be used when creating JDBC connections using the JDBC
driver class.
+ This is not required if the DataSource is found in JNDI.
+ </entry>
+ </row>
+ <row>
+ <entry>maximumConnectionsInPool</entry>
+ <entry>
+ The maximum number of connections that may be in the connection pool.
+ The default is "5".
+ </entry>
+ </row>
+ <row>
+ <entry>minimumConnectionsInPool</entry>
+ <entry>
+ The minimum number of connections that will be kept in the connection pool.
+ The default is "0".
+ </entry>
+ </row>
+ <row>
+ <entry>maximumConnectionIdleTimeInSeconds</entry>
+ <entry>
+ The maximum number of seconds that a connection should remain in the pool before
being closed.
+ The default is "600" seconds (or 10 minutes).
+ </entry>
+ </row>
+ <row>
+ <entry>maximumSizeOfStatementCache</entry>
+ <entry>
+ The maximum number of statements that should be cached.
+ Statement caching can be disabled by setting to "0".
+ The default is "100".
+ </entry>
+ </row>
+ <row>
+ <entry>numberOfConnectionsToAcquireAsNeeded</entry>
+ <entry>
+ The number of connections that should be added to the pool when there are not
enough to be used.
+ The default is "1".
+ </entry>
+ </row>
+ <row>
+ <entry>idleTimeInSecondsBeforeTestingConnections</entry>
+ <entry>
+ The number of seconds after a connection remains in the pool that the connection
should be tested to ensure it is still valid.
+ The default is 180 seconds (or 3 minutes).
+ </entry>
+ </row>
+ <row>
+ <entry>retryLimit</entry>
+ <entry>Optional property that, if used, defines the number of times that any
single operation on a &RepositoryConnection; to this source should be retried
+ following a communication failure.
+ The default value is '0'.
+ </entry>
+ </row>
+ <row>
+ <entry>cacheTimeToLiveInMilliseconds</entry>
+ <entry>Optional property that, if used, defines the maximum time in
milliseconds that any information returned by this connector
+ is allowed to be cached before being considered invalid. When not used, this
source will not define a specific
+ duration for caching information.
+ The default value is "600000" milliseconds, or 10 minutes.
+ </entry>
+ </row>
+ <row>
+ <entry>defaultCatalogName</entry>
+ <entry>
+ The name to use for the catalog name if the database does not support catalogs or
the database has a catalog with the empty string
+ as a name. The default value is "default".
+ </entry>
+ </row>
+ <row>
+ <entry>defaultSchemaName</entry>
+ <entry>
+ The name to use for the schema name if the database does not support schemas or the
database has a schema with the empty string
+ as a name. The default value is "default".
+ </entry>
+ </row>
+ <row>
+ <entry>metadataCollectorClassName</entry>
+ <entry>
+ The name of a custom class to use for metadata collection. The class must
implement the &MetadataCollector; interface. If a null
+ value is specified for this property, a default &MetadataCollector;
implementation will be used that relies on the &DatabaseMetaData;
+ provided by the JDBC driver for the connection. This property is provided as a
means for connecting to databases with a JDBC driver
+ that provides a non-standard &DatabaseMetaData; implementation or no
&DatabaseMetaData; implementation at all.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ The JDBC metadata connector is used by creating in the &JcrConfiguration; a
repository source that uses the &JdbcMetadataSource; class.
+ For example:
+ </para>
+ <programlisting role="JAVA"><![CDATA[
+JcrConfiguration config = ...
+config.repositorySource("source A")
+ .usingClass(JdbcMetadataSource.class)
+ .setDescription("The database store for our content")
+ .setProperty("dataSourceJndiName", "java:/MyDataSource")
+ .setProperty("nameOfDefaultWorkspace", "default")
+ ]]></programlisting>
+ <para>
+ Of course, setting other more advanced properties would entail calling
<code>setProperty(...)</code> for each. Since almost all
+ of the properties have acceptable default values, however, we don't need to set
very many of them.
+ </para>
</chapter>
Modified: trunk/docs/reference/src/main/docbook/en-US/content/connectors/jdbc_storage.xml
===================================================================
---
trunk/docs/reference/src/main/docbook/en-US/content/connectors/jdbc_storage.xml 2009-12-19
14:06:33 UTC (rev 1464)
+++
trunk/docs/reference/src/main/docbook/en-US/content/connectors/jdbc_storage.xml 2009-12-19
16:23:31 UTC (rev 1465)
@@ -73,7 +73,7 @@
<row>
<entry>predefinedWorkspaceNames</entry>
<entry>Optional property that, if used, defines names of the workspaces that
are predefined and need not be created before being used.
- This can be coupled with a "fase" value for the
"creatingWorkspaceAllowed" property to allow only the use of only predefined
workspaces.
+ This can be coupled with a "false" value for the
"creatingWorkspaceAllowed" property to allow only the use of only predefined
workspaces.
</entry>
</row>
<row>
@@ -252,7 +252,7 @@
</tgroup>
</table>
<para>
- Using the file system connector is used by creating in the &JcrConfiguration; a
repository source that uses the &JpaSource; class.
+ The JPA connector is used by creating in the &JcrConfiguration; a repository source
that uses the &JpaSource; class.
For example:
</para>
<programlisting role="JAVA"><![CDATA[
Modified: trunk/docs/reference/src/main/docbook/en-US/custom.dtd
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/custom.dtd 2009-12-19 14:06:33 UTC (rev
1464)
+++ trunk/docs/reference/src/main/docbook/en-US/custom.dtd 2009-12-19 16:23:31 UTC (rev
1465)
@@ -50,6 +50,7 @@
<!ENTITY TimeUnit "<ulink
url='&Java;java/util/concurrent/TimeUnit.html'><interface>TimeUnit</interface></ulink>">
<!ENTITY UUID "<ulink
url='&Java;java/util/UUID.html'><classname>UUID</classname></ulink>">
<!ENTITY DataSource "<ulink
url='&Java;javax/sql/DataSource.html'><classname>DataSource</classname></ulink>">
+<!ENTITY DatabaseMetaData "<ulink
url='&Java;java/sql/DatabaseMetaData.html'><classname>DatabaseMetaData</classname></ulink>">
<!ENTITY HttpServletRequest "<ulink
url='&JavaEE;javax/servlet/http/HttpServletRequest.html'><classname>HttpServletRequest</classname></ulink>">
<!ENTITY Serializable "<ulink
url='&Java;java/io/Serializable.html'><interface>Serializable</interface></ulink>">
<!ENTITY Iterator "<ulink
url='&Java;java/util/Iterator.html'><interface>Iterator</interface></ulink>">
@@ -199,7 +200,9 @@
<!ENTITY FileSystemSource "<ulink
url='&API;connector/filesystem/FileSystemSource.html'><classname>FileSystemSource</classname></ulink>">
<!ENTITY CustomPropertiesFactory "<ulink
url='&API;connector/filesystem/CustomPropertiesFactory'><classname>CustomPropertiesFactory</classname></ulink>">
-<!ENTITY JpaSource "<ulink
url='&API;connector/source/jap/JpaSource.html'><classname>JpaSource</classname></ulink>">
+<!ENTITY JpaSource "<ulink
url='&API;connector/store/jpa/JpaSource.html'><classname>JpaSource</classname></ulink>">
+<!ENTITY JdbcMetadataSource "<ulink
url='&API;connector/meta/jdbc/JdbcMetadataSource.html'><classname>JdbcMetadataSource</classname></ulink>">
+<!ENTITY MetadataCollector "<ulink
url='&API;connector/meta/jdbc/MetadataCollector'><classname>MetadataCollector</classname></ulink>">
<!ENTITY SVNRepositorySource "<ulink
url='&API;connector/svn/SVNRepositorySource.html'><classname>SVNRepositorySource</classname></ulink>">
<!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>">
Modified: trunk/docs/reference/src/main/docbook/en-US/master.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/master.xml 2009-12-19 14:06:33 UTC (rev
1464)
+++ trunk/docs/reference/src/main/docbook/en-US/master.xml 2009-12-19 16:23:31 UTC (rev
1465)
@@ -116,7 +116,7 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
href="content/connectors/subversion.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
href="content/connectors/jboss_cache.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
href="content/connectors/infinispan.xml"/>
- <!--xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
href="content/connectors/jdbc_metadata.xml"/-->
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
href="content/connectors/jdbc_metadata.xml"/>
</part>
<part id="provied-sequencers-part">
<title>Sequencer Library</title>