[dna-commits] DNA SVN: r1588 - in trunk/docs/reference/src/main/docbook/en-US: content and 5 other directories.

Author: rhauch Date: 2010-01-10 18:32:54 -0500 (Sun, 10 Jan 2010) New Revision: 1588 Modified: trunk/docs/reference/src/main/docbook/en-US/content/connectors/federation.xml trunk/docs/reference/src/main/docbook/en-US/content/connectors/file_system.xml trunk/docs/reference/src/main/docbook/en-US/content/connectors/in_memory.xml trunk/docs/reference/src/main/docbook/en-US/content/connectors/infinispan.xml trunk/docs/reference/src/main/docbook/en-US/content/connectors/jboss_cache.xml 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/content/connectors/subversion.xml trunk/docs/reference/src/main/docbook/en-US/content/core/connector.xml trunk/docs/reference/src/main/docbook/en-US/content/core/execution_context.xml trunk/docs/reference/src/main/docbook/en-US/content/core/graph.xml trunk/docs/reference/src/main/docbook/en-US/content/core/sequencing.xml trunk/docs/reference/src/main/docbook/en-US/content/developers/testing.xml trunk/docs/reference/src/main/docbook/en-US/content/developers/tools.xml trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml trunk/docs/reference/src/main/docbook/en-US/content/jcr/configuration.xml 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 trunk/docs/reference/src/main/docbook/en-US/content/jcr/rest_service.xml trunk/docs/reference/src/main/docbook/en-US/content/sequencers/compact_node_types.xml trunk/docs/reference/src/main/docbook/en-US/content/sequencers/ddl.xml trunk/docs/reference/src/main/docbook/en-US/content/sequencers/java_class.xml trunk/docs/reference/src/main/docbook/en-US/custom.dtd Log: DNA-621 Applied Brian's patch (with one or two very minor modifications) for the Reference Guide. Modified: trunk/docs/reference/src/main/docbook/en-US/content/connectors/federation.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/connectors/federation.xml 2010-01-10 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/connectors/federation.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -237,7 +237,7 @@ <programlisting> /Vehicles => / for source "Cars" /Vehicles/Aircraft => /Aviation for source "Aircraft" -/Vehicles/Spacecraft => /Space Vehicles for source "Cars" +/Vehicles/Spacecraft => /Space Vehicles for source "Spacecraft" </programlisting> <para> The result is a unified repository with the following structure: @@ -436,7 +436,7 @@ We're using XML to represent a graph structure, since the two map pretty well. Each XML element represents a node and XML attributes represent properties on a node. The name of the node is defined by either the <code>jcr:name</code> attribute (if it exists) or the name of the XML element. And we use XML namespaces - to define the namespaces used in the node and property names. BTW, this is exactly how the XML graph importer + to define the namespaces used in the node and property names. As an aside, this is exactly how the XML graph importer works. </para> </note> Modified: trunk/docs/reference/src/main/docbook/en-US/content/connectors/file_system.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/connectors/file_system.xml 2010-01-10 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/connectors/file_system.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -34,14 +34,14 @@ This connector exposes an area of the local file system as a graph of "nt:file" and "nt:folder" nodes. The connector can be configured so that the workspace name is either a path to the directory on the file system that represents the root of that workspace <emphasis>or</emphasis> the name of subdirectory within a root directory (see the <code>workspaceRootPath</code> property below). Each - connector can define whether it allows new workspaces can be created, but if so the names of the new workspaces + connector can define whether it allows new workspaces to be created, but if so the names of the new workspaces must represent valid paths to existing directories. <note> <para> The file nodes returned by this connector will have a primary type of <code>nt:file</code> and a child node named <code>jcr:content</code>. The <code>jcr:content</code> node will have a primary type of <code>dna:resource</code>. The <code>dna:resource</code> node type is equivalent to the built-in <code>nt:resource</code> node type in all ways except one: it does not extend <code>mix:referenceable</code>. This is because - DNA cannot assign a persistent UUID to the files in the file system or guarantee that no other process will not move or delete the files outside of DNA. + DNA cannot assign a persistent UUID to the files in the file system or guarantee that no other process will move or delete the files outside of DNA. The <code>mix:referenceable</code> node type cannot be implemented if either of these conditions cannot be met. Additional properties (including mixin types) can be added by setting the <code>customPropertiesFactory</code> property to point to an implementation of @@ -65,29 +65,23 @@ </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> + <entry>cachePolicy</entry> + <entry>Optional property that, if used, defines the cache policy for this repository source. When not used, this source will not define a specific + duration for caching information.</entry> </row> <row> - <entry>updatesAllowed</entry> - <entry>Determines whether the content in the file system can be updated ("true"), or if the content may only be read ("false"). - The default value is "false" to avoid unintentional security vulnerabilities.</entry> + <entry>creatingWorkspaceAllowed</entry> + <entry>Optional property that defines whether clients can create additional workspaces. The default value is "true". + </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.</entry> - </row> - <row> <entry>defaultWorkspaceName</entry> <entry>Optional property that is initialized to <code>"default"</code> and which defines the name for the workspace that will be used by default if none is specified.</entry> </row> <row> - <entry>creatingWorkspaceAllowed</entry> - <entry>Optional property that defines whether clients can create additional workspaces. The default value is "true". - </entry> + <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>predefinedWorkspaceNames</entry> @@ -103,9 +97,14 @@ <row> <entry>rootNodeUuid</entry> <entry>Optional property that, if used, specifies the UUID that should be used for the root node of each workspace. If no value is - specified, a random UUID is generated each time that the repository is started.</entry> + specified, a default UUID is used.</entry> </row> <row> + <entry>updatesAllowed</entry> + <entry>Determines whether the content in the file system can be updated ("true"), or if the content may only be read ("false"). + The default value is "false" to avoid unintentional security vulnerabilities.</entry> + </row> + <row> <entry>workspaceRootPath</entry> <entry> <para>Optional property that, if used, specifies a path on the local file system to the root of all workspaces. The source will will Modified: trunk/docs/reference/src/main/docbook/en-US/content/connectors/in_memory.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/connectors/in_memory.xml 2010-01-10 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/connectors/in_memory.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -52,15 +52,26 @@ </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> + <entry>defaultCachePolicy</entry> + <entry>Optional property that, if used, defines the default for how long this information provided by this source may to be + cached by other, higher-level components. The default value of null implies that this source does not define a specific + duration for caching information provided by this repository source.</entry> </row> <row> + <entry>defaultWorkspaceName</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>jndiName</entry> <entry>Optional property that, if used, specifies the name in JNDI where an &InMemoryRepository; instance can be found. This is an advanced property that is infrequently used.</entry> </row> <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> @@ -70,17 +81,6 @@ <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>defaultCachePolicy</entry> - <entry>Optional property that, if used, defines the default for how long this information provided by this source may to be - cached by other, higher-level components. The default value of null implies that this source does not define a specific - duration for caching information provided by this repository source.</entry> - </row> - <row> - <entry>defaultWorkspaceName</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> </tbody> </tgroup> </table> Modified: trunk/docs/reference/src/main/docbook/en-US/content/connectors/infinispan.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/connectors/infinispan.xml 2010-01-10 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/connectors/infinispan.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -33,8 +33,8 @@ <para> The Infinispan repository connector allows a <ulink url="http://www.jboss.org/infinispan/">Infinispan</ulink> instance to be used as a JBoss DNA (and thus JCR) repository. This provides a way for the content in a repository to be stored in an - effective, scalable, and distributed data grid. Like other connectors, this can be paired with other repository sources - to provide a local or <link linkend="federation-connector">federated</link> repository. + effective, scalable, and distributed data grid, + and can be <link linkend="federation-connector">federated</link> with other repository sources to provide a distributed repository. </para> <para> The &InfinispanSource; class provides a number of JavaBean properties that control its behavior: @@ -52,10 +52,6 @@ </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>cacheManagerJndiName</entry> <entry>Optional property that, if used, specifies the name in JNDI where an existing Infinispan Cache Manager instance can be found. That factory would then be used if needed to create an Infinispan Cache instance. If no value is provided, then the @@ -78,6 +74,10 @@ if none is specified.</entry> </row> <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>predefinedWorkspaceNames</entry> <entry>Optional property that defines the names of the workspaces that exist and that are available for use without having to create them.</entry> </row> Modified: trunk/docs/reference/src/main/docbook/en-US/content/connectors/jboss_cache.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/connectors/jboss_cache.xml 2010-01-10 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/connectors/jboss_cache.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -33,8 +33,7 @@ <para> The JBoss Cache repository connector allows a <ulink url="http://www.jboss.org/jbosscache/">JBoss Cache</ulink> instance to be used as a JBoss DNA (and thus JCR) repository. This provides a repository that is an effective, scalable, and distributed cache, - and is often paired with other repository sources to provide a local or <link linkend="federation-connector">federated</link> - repository. + and can be <link linkend="federation-connector">federated</link> with other repository sources to provide a distributed repository. </para> <para> The &JBossCacheSource; class provides a number of JavaBean properties that control its behavior: @@ -52,8 +51,9 @@ </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> + <entry>cacheConfigurationName</entry> + <entry>Optional property that, if used, specifies the name of the configuration that is supplied to the cache factory + when creating a new JBoss Cache instance.</entry> </row> <row> <entry>cacheFactoryJndiName</entry> @@ -62,11 +62,6 @@ JBoss Cache <code>DefaultCacheFactory</code> class is used.</entry> </row> <row> - <entry>cacheConfigurationName</entry> - <entry>Optional property that, if used, specifies the name of the configuration that is supplied to the cache factory - when creating a new JBoss Cache instance.</entry> - </row> - <row> <entry>cacheJndiName</entry> <entry>Optional property that, if used, specifies the name in JNDI where an existing JBoss Cache instance can be found. This should be used if your application already has a cache that is used, or if you need to configure the cache in @@ -88,6 +83,10 @@ if none is specified.</entry> </row> <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>predefinedWorkspaceNames</entry> <entry>Optional property that defines the names of the workspaces that exist and that are available for use without having to create them.</entry> </row> @@ -102,15 +101,15 @@ specified, a random UUID is generated each time that the repository is started.</entry> </row> <row> - <entry>uuidPropertyName</entry> - <entry>Optional property that, if used, defines the property that should be used to find the UUID value for each node - in the cache. "<code>dna:uuid</code>" is the default.</entry> - </row> - <row> <entry>updatesAllowed</entry> <entry>Determines whether the content in the connector is can be updated ("true"), or if the content may only be read ("false"). The default value is "true".</entry> </row> + <row> + <entry>uuidPropertyName</entry> + <entry>Optional property that, if used, defines the property that should be used to find the UUID value for each node + in the cache. "<code>dna:uuid</code>" is the default.</entry> + </row> </tbody> </tgroup> 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 2010-01-10 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/connectors/jdbc_metadata.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -72,58 +72,50 @@ </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> + <entry>cachePolicy</entry> + <entry>Optional property that, if used, defines the cache policy to use for this repository source. When not used, this source will not define a specific + duration for caching information. + </entry> </row> <row> - <entry>rootNodeUuid</entry> - <entry>Optional property that, if used, defines the UUID of the root node in the 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>defaultCatalogName</entry> <entry> - The name of the JDBC driver class. - This is not required if the DataSource is found in JNDI, but is required otherwise. + 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>driverClassloaderName</entry> + <entry>defaultSchemaName</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. + 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>url</entry> + <entry>driverClassloaderName</entry> <entry> - The URL that should be used when creating JDBC connections using the JDBC driver class. + 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>username</entry> + <entry>driverClassName</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. + 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>password</entry> + <entry>idleTimeInSecondsBeforeTestingConnections</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. + 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> @@ -134,13 +126,6 @@ </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. @@ -156,20 +141,38 @@ </entry> </row> <row> - <entry>numberOfConnectionsToAcquireAsNeeded</entry> + <entry>metadataCollectorClassName</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". + 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> <row> - <entry>idleTimeInSecondsBeforeTestingConnections</entry> + <entry>minimumConnectionsInPool</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). + The minimum number of connections that will be kept in the connection pool. + The default is "0". </entry> </row> <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>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>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>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. @@ -177,34 +180,29 @@ </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>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>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> + <entry>rootNodeUuid</entry> + <entry>Optional property that, if used, defines the UUID of the root node in the repository. If not used, + then a new UUID is generated.</entry> </row> <row> - <entry>defaultSchemaName</entry> + <entry>url</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". + 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>metadataCollectorClassName</entry> + <entry>username</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. + 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> </tbody> 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 2010-01-10 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/connectors/jdbc_storage.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -52,28 +52,41 @@ </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> + <entry>autoGenerateSchema</entry> + <entry> + Sets the Hibernate setting dictating what it does with the database schema upon first connection. Valid values are as + follows (though the value is not checked): + <itemizedlist> + <listitem><para>"<code>create</code>" - Create the database schema objects when the &EntityManagerFactory; is created (actually + when Hibernate's SessionFactory is created by the entity manager factory). If a file named "import.sql" exists in + the root of the class path (e.g., '/import.sql') Hibernate will read and execute the SQL statements in this file after it + has created the database objects. Note that Hibernate first delete all tables, constraints, or any other database object + that is going to be created in the process of building the schema.</para></listitem> + <listitem><para>"<code>create-drop</code>" - Same as "<code>create</code>", except that the schema will be dropped after the + &EntityManagerFactory; is closed.</para></listitem> + <listitem><para>"<code>update</code>" - Attempt to update the database structure to the current mapping (but does not read and invoke + the SQL statements from "import.sql"). <emphasis>Use with caution.</emphasis></para></listitem> + <listitem><para>"<code>validate</code>" - Validates the existing schema with the current entities configuration, but does not make any + changes to the schema (and does not read and invoke the SQL statements from "import.sql"). This is often the proper setting + to use in production, and thus this is the default value.</para></listitem> + </itemizedlist> + </entry> </row> <row> - <entry>updatesAllowed</entry> - <entry>Determines whether the content in the database is can be updated ("true"), or if the content may only be read ("false"). - The default value is "true".</entry> + <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>rootNodeUuid</entry> - <entry>Optional property that, if used, defines the UUID of the root node in the 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>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 "false" value for the "creatingWorkspaceAllowed" property to allow only the use of only predefined workspaces. + <entry>compressData</entry> + <entry> + An advanced boolean property that dictates whether large binary and string values should be stored in a compressed form. + This is enabled by default. Setting this value only affects how new records are stored; records can always be read + regardless of the value of this setting. + The default value is "true". </entry> </row> <row> @@ -95,13 +108,6 @@ </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. @@ -109,24 +115,26 @@ </entry> </row> <row> - <entry>url</entry> + <entry>driverClassName</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. + 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>username</entry> + <entry>idleTimeInSecondsBeforeTestingConnections</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. + 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>password</entry> + <entry>largeValueSizeInBytes</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. + An advanced boolean property that controls the size of property values at which they are considered to be "large values". + Depending upon the model, large property values may be stored in a centralized area and keyed by a secure hash + of the value. This is an space and performance optimization that stores each unique large value only once. + The default value is "1024" bytes, or 1 kilobyte. </entry> </row> <row> @@ -137,13 +145,6 @@ </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. @@ -159,6 +160,34 @@ </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>model</entry> + <entry> + An advanced property that dictates the type of storage schema that is used. Currently, the only supported values are "Basic" and "Simple". + The Basic model supports a read-only mode (q.v., the "updatesAllowed" property) and database-level + enforcement of referential integrity (q.v., the "referentialIntegrityEnforced" property above), but does not fully support all JCR functions. + As a result, the Simple model is now the default model, but DNA repositories that were created under the Basic model will continue to use + the "Basic" model regardless of the value of this property. Repositories can be converted from the Basic model to the Simple model by exporting + them to an XML file as a system view through the JCR interface and then importing them into a new repository created with the model property set + to "Simple". + </entry> + </row> + <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>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>numberOfConnectionsToAcquireAsNeeded</entry> <entry> The number of connections that should be added to the pool when there are not enough to be used. @@ -166,13 +195,19 @@ </entry> </row> <row> - <entry>idleTimeInSecondsBeforeTestingConnections</entry> + <entry>password</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). + 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>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 "false" value for the "creatingWorkspaceAllowed" property to allow only the use of only predefined workspaces. + </entry> + </row> + <row> <entry>referentialIntegrityEnforced (Basic Model Only)</entry> <entry> An advanced boolean property that dictates whether the database's referential integrity should be enabled, or false if this checking @@ -183,71 +218,36 @@ </entry> </row> <row> - <entry>largeValueSizeInBytes</entry> - <entry> - An advanced boolean property that controls the size of property values at which they are considered to be "large values". - Depending upon the model, large property values may be stored in a centralized area and keyed by a secure hash - of the value. This is an space and performance optimization that stores each unique large value only once. - The default value is "1024" bytes, or 1 kilobyte. + <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>compressData</entry> - <entry> - An advanced boolean property that dictates whether large binary and string values should be stored in a compressed form. - This is enabled by default. Setting this value only affects how new records are stored; records can always be read - regardless of the value of this setting. - The default value is "true". - </entry> + <entry>rootNodeUuid</entry> + <entry>Optional property that, if used, defines the UUID of the root node in the repository. If not used, + then a new UUID is generated.</entry> </row> <row> - <entry>model</entry> - <entry> - An advanced property that dictates the type of storage schema that is used. Currently, the only supported values are "Basic" and "Simple". - The Basic model supports a read-only mode (q.v., the "updatesAllowed" property) and database-level - enforcement of referential integrity (q.v., the "referentialIntegrityEnforced" property above), but does not fully support all JCR functions. - As a result, the Simple model is now the default model, but DNA repositories that were created under the Basic model will continue to use - the "Basic" model regardless of the value of this property. Repositories can be converted from the Basic model to the Simple model by exporting - them to an XML file as a system view through the JCR interface and then importing them into a new repository created with the model property set - to "Simple". - </entry> + <entry>updatesAllowed</entry> + <entry>Determines whether the content in the database is can be updated ("true"), or if the content may only be read ("false"). + The default value is "true".</entry> </row> <row> - <entry>autoGenerateSchema</entry> + <entry>url</entry> <entry> - Sets the Hibernate setting dictating what it does with the database schema upon first connection. Valid values are as - follows (though the value is not checked): - <itemizedlist> - <listitem><para>"<code>create</code>" - Create the database schema objects when the &EntityManagerFactory; is created (actually - when Hibernate's SessionFactory is created by the entity manager factory). If a file named "import.sql" exists in - the root of the class path (e.g., '/import.sql') Hibernate will read and execute the SQL statements in this file after it - has created the database objects. Note that Hibernate first delete all tables, constraints, or any other database object - that is going to be created in the process of building the schema.</para></listitem> - <listitem><para>"<code>create-drop</code>" - Same as "<code>create</code>", except that the schema will be dropped after the - &EntityManagerFactory; is closed.</para></listitem> - <listitem><para>"<code>update</code>" - Attempt to update the database structure to the current mapping (but does not read and invoke - the SQL statements from "import.sql"). <emphasis>Use with caution.</emphasis></para></listitem> - <listitem><para>"<code>validate</code>" - Validates the existing schema with the current entities configuration, but does not make any - changes to the schema (and does not read and invoke the SQL statements from "import.sql"). This is often the proper setting - to use in production, and thus this is the default value.</para></listitem> - </itemizedlist> + 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>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>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>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> </tbody> </tgroup> </table> Modified: trunk/docs/reference/src/main/docbook/en-US/content/connectors/subversion.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/connectors/subversion.xml 2010-01-10 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/connectors/subversion.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -31,7 +31,7 @@ <chapter id="subversion-connector"> <title>Subversion Connector</title> <para> - This connector provides read-only access to the directories and folders within a Subversion repository, providing that content in + This connector provides read and write access to the directories and folders within a Subversion repository, providing that content in the form of <code>nt:file</code> and <code>nt:folder</code> nodes. This source considers a workspace name to be the path to the directory on the repository's root directory location that represents the root of that workspace (e.g., "trunk" or "branches"). @@ -53,22 +53,27 @@ </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> + <entry>cachePolicy</entry> + <entry>Optional property that, if used, defines the cache policy to use for caching information in the repository. When not used, this source will not define a specific + duration for caching information.</entry> </row> <row> - <entry>repositoryRootURL</entry> - <entry> - Required property that should be set with the URL to the Subversion repository. + <entry>creatingWorkspaceAllowed</entry> + <entry>Optional property that defines whether clients can create additional workspaces. The default value is "true". </entry> </row> <row> - <entry>username</entry> - <entry> - The username that should be used to establish a connection to the repository. + <entry>defaultWorkspaceName</entry> + <entry>Optional property that, if used, specifies the name of the workspace to use when no workspace name is specified in an operation. + Each workspace name is treated as a path relative to the SVN repository being exposed (e.g., a workspace name of "trunk" will map + to the URL "http://acme.com/repo/trunk" if the repository root URL is "http://acme.com/repo/"). </entry> </row> <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>password</entry> <entry> The password that should be used to establish a connection to the repository. This is not required if the URL represents an @@ -76,22 +81,17 @@ </entry> </row> <row> - <entry>directoryForDefaultWorkspace</entry> - <entry>Optional property that, if used, specifies the relative path of the directory in the repository that should be - exposed as the default workspace. - Each workspace name is the URL of the portion of the SVN repository being exposed (e.g., "http://acme.com/repo/trunk"). - </entry> - </row> - <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. - Each workspace name is the URL of the portion of the SVN repository being exposed (e.g., "http://acme.com/repo/trunk"). - This can be coupled with a "fase" value for the "creatingWorkspaceAllowed" property to allow only the use of only predefined workspaces. + Each workspace name is treated as a path relative to the SVN repository being exposed (e.g., a workspace name of "trunk" will map + to the URL "http://acme.com/repo/trunk" if the repository root URL is "http://acme.com/repo/"). + This can be coupled with a "false" value for the "creatingWorkspaceAllowed" property to allow only the use of predefined workspaces. </entry> </row> <row> - <entry>creatingWorkspaceAllowed</entry> - <entry>Optional property that defines whether clients can create additional workspaces. The default value is "true". + <entry>repositoryRootURL</entry> + <entry> + Required property that should be set with the URL to the Subversion repository. </entry> </row> <row> @@ -100,10 +100,10 @@ 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.</entry> + <entry>username</entry> + <entry> + The username that should be used to establish a connection to the repository. + </entry> </row> </tbody> </tgroup> @@ -118,8 +118,8 @@ .usingClass(SVNRepositorySource.class) .setDescription("The DNA SVN repository (anonymous access)") .setProperty("repositoryRootUrl", "http://anonsvn.jboss.org/repos/dna"); - .setProperty("directoryForDefaultWorkspace", "http://anonsvn.jboss.org/repos/dna/trunk"); - .setProperty("predefinedWorkspaceNames", new String[] {"http://anonsvn.jboss.org/repos/dna/trunk }); + .setProperty("defaultWorkspaceName", "trunk"); + .setProperty("predefinedWorkspaceNames", new String[] {"trunk }); ]]></programlisting> <para> Another way to configure the Subversion connector is to create &JcrConfiguration; instance and load an XML configuration file that contains a repository source that @@ -145,8 +145,8 @@ dna:classname="org.jboss.dna.graph.connector.svn.SVNRepositorySource" dna:description="The DNA SVN repository (anonymous access)" dna:repositoryRootUrl="http://anonsvn.jboss.org/repos/dna" - dna:directoryForDefaultWorkspace="http://anonsvn.jboss.org/repos/dna... - dna:predefinedWorkspaceNames="http://anonsvn.jboss.org/repos/dna/tru... + dna:defaultWorkspaceName="trunk" + dna:predefinedWorkspaceNames="trunk" dna:defaultWorkspaceName="default"/> </dna:sources> 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 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/core/connector.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -40,7 +40,7 @@ would break or have to change. And copying the information means that we'd have to continually synchronize the changes. This not only is a lot of work, but it often makes it difficult to know whether information is accurate and "the master" data. </para> - <para>JBoss DNA lets us leave information where it, yet access it through the JCR API as if it were in one big repository. + <para>JBoss DNA lets us leave information where it is, yet access it through the JCR API as if it were in one big repository. One major benefit is that existing applications that use the information in the original locations don't break, since they can keep using the information. But now our JCR clients can also access all the information, too. And if our federating JBoss DNA repository is configured to allow updates, JCR client applications can change the information in the repository and JBoss DNA will propagate @@ -83,7 +83,7 @@ <para>a repository that accesses existing JDBC databases to project the schema structure as read-only repository content</para> </listitem> <listitem> - <para>a repository that accesses a file systems to present the files and directory structure as (updatable) repository content</para> + <para>a repository that accesses a file system to present its files and directory structure as (updatable) repository content</para> </listitem> <listitem> <para>a repository that accesses an SVN repository to present the files and directory structure as (updatable) repository content</para> @@ -163,9 +163,9 @@ </para> </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 + <para>As an example, consider if we wanted JBoss DNA to give us access through JCR to the information contained in a 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;, + That connector would contain a <code>JdbcAccessSource</code> 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. 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. @@ -179,17 +179,17 @@ </para> </note> <para> - Our new connector would also have a <code>JdbcRepositoryConnection</code> Java class that implements the + Our new connector might also have a <code>JdbcAccessConnection</code> Java class that implements the &RepositoryConnection; interface. This class would probably wrap a JDBC database connection, and would implement the <code>execute(...)</code> method such that the nodes exposed by the connector - describe the database schema of the database. For example, the connector might represent each database table + describe the database tables and their contents. For example, the connector might represent each database table as a node with the table's name, with properties that describe the table (e.g., the description, whether it's a - temporary table), and with child nodes that represent each of the columns, keys and constraints. + temporary table), and with child nodes that represent rows in the table. </para> <para> - To use our connector in an application that uses JBoss DNA, we need to create an instance of the - &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; + To use our connector in an application that uses JBoss DNA, we would need to create an instance of the + <code>JdbcAccessSource</code> 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 <code>JdbcAccessSource</code> 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> @@ -279,8 +279,7 @@ and would like to help create it, please <link linkend="preface">join the community</link>. </para> <para>In lieu of a Maven archetype, you may find it easier to start with a small existing connector project. - The <emphasis role="strong">dna-connector-filesystem</emphasis> project is small, but it may be tough to separate - the stuff that every connector needs from the extra code and data structures that manage the content. + The <emphasis role="strong">dna-connector-filesystem</emphasis> project is small and provides good example of implementing a path-based repository. See the subversion repository: <ulink url="&Subversion;trunk/extensions/dna-connector-filesystem/">&Subversion;trunk/extensions/dna-connector-filesystem/</ulink> </para> </note> @@ -442,8 +441,14 @@ In summary, a connector has total control over whether and for how long the information it provides is cached. </para> + <note> + <para> + At this time, JBoss DNA does not yet take advantage of the connector's cache policies. + However, it is anticipated that this will change. + </para> + </note> </sect3> - <sect3 id="repository_source_jndi"> + <sect3 id="repository_source_jndi"> <title>Leveraging JNDI</title> <para> Sometimes it is necessary (or easier) for a &RepositorySource; implementation to look up an object in JNDI. @@ -516,9 +521,8 @@ <programlisting> /** * A connection to a repository source. - * <p> + * * These connections need not support concurrent operations by multiple threads. - * </p> */ @NotThreadSafe public interface &RepositoryConnection; { @@ -574,18 +578,12 @@ }</programlisting> <para> While most of these methods are straightforward, a few warrant additional information. - The <code>ping(...)</code> allows DNA to check the connection to see if it is + The <code>ping(...)</code> method allows DNA to check the connection to see if it is alive. This method can be used in a variety of situations, ranging from verifying that a &RepositorySource;'s JavaBean properties are correct to ensuring that a connection is still alive before returning the connection from a connection pool. </para> <para> - If the connector is able to publish events, then - DNA hasn't yet defined the event mechanism, so connectors don't have any methods to invoke on the &RepositorySourceListener;. - This will be defined in the next release, so feel free to manage the listeners now. Note that by default the &RepositorySourceCapabilities; returns - <code>false</code> for <code>supportsEvents()</code>. - </para> - <para> The most important method on this interface, though, is the <code>execute(...)</code> method, which serves as the mechanism by which the component using the connector access and manipulates the content exposed by the connector. The first parameter to this method is the &ExecutionContext;, which contains the information about environment @@ -599,11 +597,6 @@ where the connector places the results (or the error, if one occurs). </para> <para> - Although there are over a dozen different kinds of requests, we do anticipate adding more in future releases. - For example, DNA will likely support searching repository content in sources through an additional subclass of &Request;. - Getting the version history for a node will likely be another kind of request added in an upcoming release. - </para> - <para> A connector is technically free to implement the <code>execute(...)</code> method in any way, as long as the semantics are maintained. But as discussed in the <link linkend="graph-request-processors">previous chapter</link>, JBoss DNA provides a &RequestProcessor; class that can simplify writing your own connector and at the @@ -628,7 +621,7 @@ Also, make sure your &RequestProcessor; is properly <link linkend="connector_events">broadcasting the changes</link> made during execution. The &RequestProcessor; class has a <code>recordChange(&ChangeRequest;)</code> that can be called from each of the <code>process(...)</code> methods that take a &ChangeRequest;. The &RequestProcessor; enqueues these requests, and when the &RequestProcessor; is - closed, the default implementation is to send a &Change; to the &Observer; supplied into the constructor. + closed, the default implementation is to send a &Changes; to the &Observer; supplied into the constructor. </para> <para> Then, in your connector's <code>execute(&ExecutionContext;, &Request;)</code> method, instantiate your &RequestProcessor; subclass Modified: trunk/docs/reference/src/main/docbook/en-US/content/core/execution_context.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/core/execution_context.xml 2010-01-10 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/core/execution_context.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -37,7 +37,7 @@ and allows for a great deal of flexibility and customization in how the components are configured. </para> <para> - The approach that JBoss DNA takes is simple: a simple POJO that represents the everything about the environment + The approach that JBoss DNA takes is simple: a simple POJO that represents everything about the environment in which components operate. Called &ExecutionContext;, it contains references to most of the essential facilities, including: security (authentication and authorization); namespace registry; name factories; factories for properties and property values; logging; and access to class loaders (given a classpath). @@ -182,7 +182,7 @@ &ExecutionContext; myAppContext = context.with(mySecurityContext); </programlisting> <para> - These &ExecutionContext; then represent the authenticated user in any component that uses the context. + These &ExecutionContext;s then represent the authenticated user in any component that uses the context. </para> <sect2 id="jaas_security"> <title>JAAS</title> @@ -302,7 +302,7 @@ &ExecutionContext; servletContext = context.with(securityContext); </programlisting> <para> - We'll see later in the <link linkend="jcr">JCR chapter</link> how this can be use to obtain a JCR &Session; for + We'll see later in the <link linkend="jcr">JCR chapter</link> how this can be used to obtain a JCR &Session; for the authenticated user. </para> </sect2> @@ -411,7 +411,7 @@ </programlisting> <para> JBoss DNA actually uses several implementations of &NamespaceRegistry;, but you can even implement your own - and create &ExecutionContext;s that uses it: + and create &ExecutionContext;s that use it: </para> <programlisting> &NamespaceRegistry; myRegistry = ... @@ -419,7 +419,7 @@ </programlisting> </sect1> <sect1 id="class_loader_factory"> - <title>Class loaders</title> + <title>Class Loaders</title> <para> JBoss DNA is designed around extensions: sequencers, connectors, MIME type detectors, and class loader factories. The core part of JBoss DNA is relatively small and has few dependencies, while many of the "interesting" components Modified: trunk/docs/reference/src/main/docbook/en-US/content/core/graph.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/core/graph.xml 2010-01-10 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/core/graph.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -57,7 +57,7 @@ names are a very important concept. </para> <para> - JBoss DNA names consist of a local part and are qualified with a namespaces. The local part can consist of + JBoss DNA names consist of a local part that is qualified with a namespace. The local part can consist of any character, and the namespace is identified by a URI. Namespaces were introduced in the <link linkend="execution-context">previous chapter</link> and are managed by the &ExecutionContext;'s <link linkend="namespace-registry">namespace registry</link>. Namespaces help reduce the risk of @@ -102,7 +102,7 @@ </para> <para> The factory for creating &Name; objects is called &NameFactory; and is available within the &ExecutionContext;, - via the <code>getValueFactories()</code> method. But before we see that, let's first discuss how names are represented as strings. + via the <code>getValueFactories()</code> method. </para> <para> We'll see how names are used later on, but one more point to make: &Name; is both serializable and comparable, @@ -351,7 +351,7 @@ </para> </sect1> <sect1 id="graph-value-factories"> - <title>Values and value factories</title> + <title>Values and Value Factories</title> <para> JBoss DNA properties can hold a variety of value object types: strings, names, paths, URIs, booleans, longs, doubles, decimals, binary content, dates, UUIDs, references to other nodes, @@ -707,6 +707,11 @@ "&amp;amp;", '&amp;lt;', '&amp;gt;', '&amp;quot;', and '&amp;#039;'. </para> </listitem> + <listitem> + <para>The &FileNameEncoder; escapes characters that are not allowed in file names on Linux, OS X, or Windows XP. + Unsafe characters are escaped as described in the &UrlEncoder;. + </para> + </listitem> </itemizedlist> All of these classes also implement the &TextDecoder; interface, which defines a method that <emphasis>decodes</emphasis> an encoded string using the opposite transformation. @@ -728,7 +733,7 @@ <para>the &Path; to the node; or</para> </listitem> <listitem> - <para>one or more <emphasis>identification properties</emphasis> that are likely source=specific + <para>one or more <emphasis>identification properties</emphasis> that are likely source-specific and that are represented with &Property; objects; or</para> </listitem> <listitem> @@ -804,7 +809,7 @@ The next few subsections describe how to use a &Graph; instance. </para> <sect2 id="graph-api-workspaces"> - <title>Using workspaces</title> + <title>Using Workspaces</title> <para> JBoss DNA graphs have the notion of <emphasis>workspaces</emphasis> that provide different views of the content. Some graphs may have one workspace, while others may have multiple workspaces. Some graphs will allow a client to create new workspaces or destroy @@ -880,7 +885,7 @@ </programlisting> </sect2> <sect2 id="graph_api_nodes"> - <title>Working with nodes</title> + <title>Working with Nodes</title> <para> Now let's switch to working with nodes. This first example returns a map of properties (keyed by property name) for a node at a specific &Path;: @@ -1280,7 +1285,7 @@ </table> <para> Although there are over a dozen different kinds of requests, we do anticipate adding more in future releases. - For example, DNA will likely support searching repository content in sources through an additional subclass of &Request;. + For example, DNA has recently added support for searching repository content in sources through an additional subclass of &Request;. Getting the version history for a node will likely be another kind of request added in an upcoming release. </para> <para> @@ -1320,7 +1325,7 @@ </para> <para> Many event frameworks define the listeners and sources as interfaces. While this is often useful, it requires - the implementations properly address the thread-safe semantics of managing and calling the listeners. + that the implementations properly address the thread-safe semantics of managing and calling the listeners. The JBoss DNA observation framework uses abstract or concrete classes to minimize the effort required for implementing &ChangeObserver; or &Observable;. These abstract classes provide implementations for a number of utility methods (such as the <code>unregister()</code> method on &ChangeObserver;) that @@ -1391,8 +1396,8 @@ </sect2> <para> As we'll see in the <link linkend="connector-framework">next chapter</link>, each connector is responsible for propagating - the &ChangeRequest; objects to the connector's &Observer;. But that's not the only use of &Observers;. - We'll also see later how the <link linkend="sequencing-framework">sequencing system</link> uses &Observers; to monitor + the &ChangeRequest; objects to the connector's &Observer;. But that's not the only use of &Observer;s. + We'll also see later how the <link linkend="sequencing-framework">sequencing system</link> uses &Observer;s to monitor for changes in the graph content to determine which, if any, sequencers should be run. And, the <link linkend="jcr">JCR implementation</link> also uses the observation framework to propagate those changes to JCR clients. Modified: trunk/docs/reference/src/main/docbook/en-US/content/core/sequencing.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/core/sequencing.xml 2010-01-10 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/core/sequencing.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -35,7 +35,7 @@ service definitions, policy files, images, media, documents, presentations, application components, reusable libraries, configuration files, application installations, databases schemas, management scripts, and so on. Unlocking the information buried within all of those files is what JBoss DNA sequencing is all about. - As files are loaded into the repository, you JBoss DNA can automatically sequence these files to extract + As files are loaded into the repository, you JBoss DNA instance can automatically sequence these files to extract from their content meaningful information that can be stored in the repository, where it can then be searched, accessed, and analyzed using the JCR API. </para> @@ -222,11 +222,11 @@ </row> </thead> <tbody> - <row><entry>/a/(b|c|d)</entry><entry>Match children of the top level node "<code>a</code>" that are named "<code>a</code>", - "<code>b</code>" or "<code>c</code>". None of the nodes may have same-name-sibling indexes.</entry></row> + <row><entry>/a/(b|c|d)</entry><entry>Match children of the top level node "<code>a</code>" that are named "<code>b</code>", + "<code>c</code>" or "<code>d</code>". None of the nodes may have same-name-sibling indexes.</entry></row> <row><entry>/a/b[c/d]</entry><entry>Match node "<code>b</code>" child of the top level node "<code>a</code>", when node "<code>b</code>" has a child named "<code>c</code>", and "<code>c</code>" has a child named "<code>d</code>". - Node "<code>b</code>" is the selected node, while nodes "<code>b</code>" and "<code>b</code>" are used as criteria but are not + Node "<code>b</code>" is the selected node, while nodes "<code>c</code>" and "<code>d</code>" are used as criteria but are not selected.</entry></row> <row><entry>/a(/(b|c|d|)/e)[f/g/@something]</entry><entry>Match node "<code>/a/b/e</code>", "<code>/a/c/e</code>", "<code>/a/d/e</code>", or "<code>/a/e</code>" when they also have a child "<code>f</code>" that itself has a child "<code>g</code>" with property @@ -258,7 +258,7 @@ </para> </sect1> <sect1 id="sequencer-library"> - <title>Out-of-the-box sequencers</title> + <title>Out-of-the-box Sequencers</title> <para> A number of sequencers are already available in JBoss DNA, and are outlined in detail <link linkend="provied-sequencers-part">later in the document</link>. @@ -267,8 +267,8 @@ </para> </sect1> <sect1 id="custom-sequencers"> - <title>Creating custom sequencers</title> - <para>The current release of JBoss DNA comes with six sequencers. However, it's very easy to create your own + <title>Creating Custom Sequencers</title> + <para>The current release of JBoss DNA comes with eleven sequencers. However, it's very easy to create your own sequencers and to then configure JBoss DNA to use them in your own application. </para> <para> Modified: trunk/docs/reference/src/main/docbook/en-US/content/developers/testing.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/developers/testing.xml 2010-01-10 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/developers/testing.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -33,7 +33,7 @@ <para> The JBoss DNA project uses automated testing to verify that the software is doing what it's supposed to and not doing what it shouldn't do. These automated tests are run continuously and also act as regression tests, - ensuring that we known if any problems we find and fix reappear later. All of our tests are executed as part of + ensuring that we know if any problems we find and fix reappear later. All of our tests are executed as part of our <link linkend="maven">Maven</link> build process, and the entire build process (including the tests) is automatically run using <link linkend="hudson">Hudson</link> continuous integration system. </para> @@ -51,7 +51,7 @@ they may rely upon the file resources included in the project, but these tests should require no external resources (like databases or servers). Note that our unit tests are run during the "test" phase of the standard <ulink url="http://maven.apache.org/guides/introduction/introduction-to-the... lifecycle</ulink>. - This means that they are executed against the raw .class files created during complication. + This means that they are executed against the raw .class files created during compilation. </para> <para> Developers are expected to run all of the JBoss DNA unit tests in their local environment before committing changes to SVN. @@ -138,7 +138,7 @@ behavior. </para> <para> - JBoss DNA has implemented all of the JCR Level 1 and Level 2 features, along with the optional locking and observation + JBoss DNA has implemented almost all of the JCR Level 1 and Level 2 features, along with the optional locking and observation features. The only optional feature not implemented is versioning, and that will be coming soon. </para> <para> Modified: trunk/docs/reference/src/main/docbook/en-US/content/developers/tools.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/developers/tools.xml 2010-01-10 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/developers/tools.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -114,8 +114,8 @@ Why do we build using JDK 5 and not 6? The main reason is that if we were to use JDK 6, then JBoss DNA couldn't really be used in any applications or projects that still used JDK 5. Plus, anybody using JDK 6 can still use JBoss DNA. However, considering that the end-of-life for Java 5 is - <ulink url="http://java.sun.com/products/archive/eol.policy.html">O... 2009</ulink>, we may be switching to - Java 6 sometime in 2009. + <ulink url="http://java.sun.com/products/archive/eol.policy.html">O... 2009</ulink>, we will likely be switching to + Java 6 sometime in 2010. </para> </note> <para> @@ -152,7 +152,7 @@ <ulink url="http://www.jboss.org">JBoss.org</ulink>. Although you can view the <ulink url="&Subversion;trunk/">trunk</ulink> of the Subversion repository directly (or using <ulink url="&Fisheye;trunk">FishEye</ulink>) through your browser, - it order to get more than just a few files of the latest version of the source code, you probably want + in order to get more than just a few files of the latest version of the source code, you probably want to have an SVN client installed. Several IDE's have SVN support included (or available as plugins), but having the command-line SVN client is recommended. See <ulink url="http://subversion.tigris.org/">http://subversion.tigris... for downloads and instructions for your @@ -352,7 +352,7 @@ "<code>oracle9i</code>", "<code>oracle10g</code>", "<code>oracle11g</code>", "<code>db2v8</code>", "<code>db2v9</code>", "<code>sybase15</code>", and - "<code>mysql2005</code>". + "<code>mssql2005</code>". The database connection information for these database profiles are in the parent "pom.xml" file, and most of these are configured to use database instances within the JBoss Quality Assurance lab and are accessible only to Red Hat employees. However, feel free to add your own profiles @@ -420,10 +420,8 @@ <title>Eclipse IDE</title> <para>Many of the JBoss DNA committers use the Eclipse IDE, and all project files required by Eclipse are committed in SVN, making it pretty easy to get an Eclipse workspace running with all of the JBoss DNA projects. - Many of the JBoss DNA committers use the Eclipse IDE, and all project files required by Eclipse are committed in SVN, making - it pretty easy to get an Eclipse workspace running with all of the JBoss DNA projects. </para> - <para>We're using the latest released version of Eclipse (3.4, called "Ganymede"), + <para>We're using the latest released version of Eclipse, available from <ulink url="http://www.eclipse.org/">Eclipse.org</ulink>;. Simply follow the instructions for your platform. </para> <para> @@ -497,7 +495,7 @@ <sect2 id="build-all-artifacts-and-assemblies"> <title>Building all artifacts and assemblies</title> <para> - By default, the project's Maven build process is does <emphasis>not</emphasis> build the documentation, JavaDocs, or assemblies. + By default, the project's Maven build process does <emphasis>not</emphasis> build the documentation, JavaDocs, or assemblies. These take extra time, and most of our builds don't require them. So the first step of releasing JBoss DNA is to use Maven to build all of regular artifacts (e.g., JARs) and these extra documents and assemblies. </para> @@ -615,10 +613,9 @@ <sect1> <title>Summary</title> <para> - In this chapter, we described the various aspects of developing code for the JBoss DNA project. Before we start talking - about some of the details of JBoss DNA repositories, connectors, and sequencers, we'll first talk about - some very ubiquitous information: how does JBoss DNA load all of the extension classes? - This is the topic of the <link linkend="classloaders">next chapter</link>. + In this chapter, we described the various aspects of developing code for the JBoss DNA project. + Next, we must discuss the testing practices for JBoss DNA project. + This is the topic of the <link linkend="testing">next chapter</link>. </para> </sect1> </chapter> Modified: trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml 2010-01-10 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -74,7 +74,7 @@ </para> <para> But these large and complex use cases aren't the only way to use a JBoss DNA repository. You could use an embedded JBoss DNA repository - to manage configuration information for an application, or you could use JBoss DNA just provide a JCR interface on top of a few non-JCR systems. + to manage configuration information for an application, or you could use JBoss DNA just to provide a JCR interface on top of a few non-JCR systems. </para> <para> The point is that JBoss DNA can be used in many different ways, ranging from the very tiny embedded repository to a large and distributed @@ -102,7 +102,7 @@ <para> What we want is <emphasis><link linkend="dna-connector-federation">federation</link></emphasis>. We can connect to these back-end systems to dynamically access the content and project it into a single, unified - repository. We can also cache it for faster access, as long as the cache can be invalidated based upon time or event. + repository. We can cache it for faster access, as long as the cache can be invalidated based upon time or event. But we also need to maintain a clear picture of where all the bits come from, so users can be sure they're looking at the right information. And we need to make it as easy as possible to write new connectors, since there are a lot of systems out there that have information we want to federate. @@ -145,8 +145,8 @@ </para> <para> Another technique built into the Java language is - <emphasis>Java serialization</emphasis> - , which is capable of persisting the state of an object graph so that it can be read back in at a later time. However, Java + <emphasis>Java serialization</emphasis>, + which is capable of persisting the state of an object graph so that it can be read back in at a later time. However, Java serialization can quickly become tricky if the classes are changed, and so it's beneficial usually when the information is persisted for a very short period of time. For example, serialization is sometimes used to send an object graph from one process to another. Using serialization for longer-term storage of information is more risky. @@ -552,8 +552,8 @@ and <link linkend="subversion-connector">SVN connector</link> were reworked to support reads and updates, and they both offer a preview of an optional caching system. The <link linkend="jdbc-storage-connector">JPA storage connector</link> was dramatically improved and is significantly faster, more capable, and more efficient. - The new <link linkend="jdbc-metadata-connector">JDBC metadata connector</link> is a technology preview of a connector - that provides read-only access to the schema information of relational databases through JDBC. + The new <link linkend="jdbc-metadata-connector">JDBC metadata connector</link> provides read-only access to the schema + information of relational databases through JDBC. </para> <para> JBoss DNA 0.7 includes a number of new and improved sequencers. The new <link linkend="text-sequencer">text sequencer</link> @@ -561,7 +561,7 @@ is capable of parsing a number of DDL dialects to extract the more important DDL statements. The <link linkend="cnd-sequencer">CND sequencer</link> was rewritten and dramatically simplified to perform better, fix a number of known issues, and eliminate a dependency on a third-party library. There is also a new <link linkend="java-class-sequencer">Java class file sequencer</link> that operates on Java class - files and produces output that is very similar to the <link linkend="java-source-sequencer">Java source file sequencer</link>, + files and produces output that is comparable to the <link linkend="java-source-sequencer">Java source file sequencer</link>, and that can be used in conjunction with the <link linkend="zip-file-sequencer">ZIP file sequencer</link> to extract the Java metadata from JARs, WARs, and EAR files. </para> @@ -571,7 +571,7 @@ <ulink url="http://jbossdna.blogspot.com/2009/09/running-tests-against-diff... all of the tests against a variety of databases</ulink>, making it very easy to test against DBMSes that JBoss DNA doesn't directly test against. A new DDL generation utility was also introduced that produces the DDL for the database used by the JPA connector. - And JCR repositories now support the use of <link linkend="jcr-guess-access">anonymous users</link>, and this is + And JCR repositories now support the use of <link linkend="jcr-guess-access">anonymous users</link> - this is enabled by default but can easily be changed for production purposes. </para> </sect1> 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 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/jcr/configuration.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -140,7 +140,7 @@ Each of these approaches has their obvious advantages, so the choice of which one to use is entirely up to you. </para> <sect2 id="loading_from_file"> - <title>Loading from a configuration file</title> + <title>Loading from a Configuration File</title> <para> Loading the JBoss DNA configuration from a file is actually very simple: </para> @@ -217,7 +217,7 @@ ]]></programlisting> </sect2> <sect2 id="loading_from_repository"> - <title>Loading from a configuration repository</title> + <title>Loading from a Configuration Repository</title> <para> Loading the JBoss DNA configuration from an existing repository is also pretty straightforward. Simply create and configure the &RepositorySource; instance to point to the desired repository, and then call the <code>loadFrom(&RepositorySource; source)</code> @@ -246,7 +246,7 @@ </para> </sect2> <sect2 id="programmatic_configuration"> - <title>Programmatic configuration</title> + <title>Programmatic Configuration</title> <para> Defining the configuration programmatically is not terribly complicated, and it for obvious reasons results in more verbose Java code. But this approach is very useful and often the easiest approach when the configuration must change or is a reflection of other @@ -257,7 +257,7 @@ components, especially when using an IDE with code completion. Here are several examples: </para> <sect3 id="programmatically_configuring_sources"> - <title>Repository sources</title> + <title>Repository Sources</title> <para>Each repository source definition must include the name of the &RepositorySource; class as well as each bean property that should be set on the object: </para> @@ -328,7 +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.) + where the "$1" value is captured as the name of the parent node. (The capture groups work the same way 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> @@ -341,7 +341,7 @@ </note> </sect3> <sect3 id="programmatically_configuring_mime_type_detectors"> - <title>MIME type detectors</title> + <title>MIME Type Detectors</title> <para>Each defined MIME type detector must specify the name of the &MimeTypeDetector; implementation class as well as any other bean properties required by the implementation.</para> <programlisting role="JAVA"><![CDATA[ @@ -513,8 +513,8 @@ 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.) + Moving the security folder into the <code>conf</code> directory does not allow those files + to be visible to the JSP page.) </para> <note> <para> 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 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -134,7 +134,7 @@ </para> </sect2> <sect2 id="jcr-sessions-custom"> - <title>Using Custom security</title> + <title>Using Custom Security</title> <para> Not all applications can or want to use JAAS for their authentication system, so JBoss DNA provides a way to integrate your own custom security provider. The first step is to provide a custom implementation of &SecurityContext; that integrates with your application security, allowing @@ -151,10 +151,6 @@ </programlisting> Once the &Session; is obtained, the repository content can be accessed and modified like any other JCR repository. </para> - <para> - At this time, no roles are required to connect to any workspace, but restrictions on workspace connections will likely be added to JBoss DNA in the near future. - Please see the <link linkend="dna_jcr_security">JCR Security section</link> for more details on how access is controlled. - </para> </sect2> <sect2 id="jcr-sessions-servlet"> <title>Using HTTP Servlet security</title> @@ -214,7 +210,7 @@ <sect2> <title>Optional Features</title> <para> - JBoss DNA does currently supports the optional JCR locking and observation features (though there still are + JBoss DNA does currently support the optional JCR locking and observation features (though there still are a few known issues with our implementation of observation). <note> <para> @@ -236,13 +232,13 @@ </para> <para> JBoss DNA has extended the set of JCR-defined actions ("add_node", "set_property", "remove", and "read") with additional actions ("register_type", - "register_namespace", and "unlock_any"). The register_type and register_namespace permissions restrict the ability to register (and unregister) types and namespaces, respectively. + "register_namespace", and "unlock_any"). The register_type and register_namespace permissions restrict the ability to register (and unregister) node types and namespaces, respectively. The unlock_any permission grants the user the ability to unlock any locked node or branch (as opposed to users without that permission who can only unlock nodes or branches that they have locked themselves or for which they hold the lock token). Permissions to perform these actions are aggregated in roles that can be assigned to users. </para> <para> - JBoss DNA currently defines three roles: <code>READONLY</code>, <code>READWRITE</code>, and <code>ADMIN</code>. If the &Credentials; passed into + JBoss DNA currently defines three roles: <code>readonly</code>, <code>readwrite</code>, and <code>admin</code>. If the &Credentials; passed into <code>Session.login(...)</code> (or the &Subject; from the &AccessControlContext;, if one of the no-credential <code>login</code> methods were used) have any of these roles, the session will have the corresponding access to all workspaces within the repository. The mapping from the roles to the actions that they allow is provided below. for any values of <code>path</code>. @@ -257,9 +253,9 @@ <thead> <row> <entry>Action Name</entry> - <entry>READONLY</entry> - <entry>READWRITE</entry> - <entry>ADMIN</entry> + <entry>readonly</entry> + <entry>readwrite</entry> + <entry>admin</entry> </row> </thead> <tbody> @@ -331,25 +327,25 @@ <tbody> <row> <entry>ROLE_NAME</entry> - <entry><code>READONLY</code>, <code>ADMIN</code></entry> + <entry><code>readonly</code>, <code>admin</code></entry> <entry>Grants the named role to the assigned user on every workspace in any repository on the DNA server.</entry> </row> <row> <entry>ROLE_NAME.REPOSITORY_NAME</entry> - <entry><code>READONLY.dna_repo</code>, <code>ADMIN.localRepository</code></entry> + <entry><code>readonly.dna_repo</code>, <code>admin.localRepository</code></entry> <entry>Grants the named role to the assigned user on every workspace in the named repository on the DNA server.</entry> </row> <row> <entry>ROLE_NAME.REPOSITORY_NAME.WORKSPACE_NAME</entry> - <entry><code>READONLY.dna_repo.jsmith</code>, <code>ADMIN.localRepository.default</code></entry> + <entry><code>readonly.dna_repo.jsmith</code>, <code>admin.localRepository.default</code></entry> <entry>Grants the named role to the assigned user on the named workspace in the named repository on the DNA server.</entry> </row> </tbody> </tgroup> </table> <para> - It is also possible to grant more than one role to the same user. For example, the user jsmith could be granted the roles READ_ONLY.production, READ_WRITE.production.jsmith, - and READ_WRITE.staging to allow read-only access to any workspace on a production repository, read/write access to a personal workspace on the same production repository, + It is also possible to grant more than one role to the same user. For example, the user jsmith could be granted the roles readonly.production, readwrite.production.jsmith, + and readwrite.staging to allow read-only access to any workspace on a production repository, read/write access to a personal workspace on the same production repository, and read/write access to any workspace in a staging repository. </para> <para> @@ -382,7 +378,7 @@ </note> </para> <para> - Although the JSR-283 specification is not yet final, it does provide a useful means of programmatically defining JCR node types. JBoss DNA supports a comparable + The JSR-283 specification provides a useful means of programmatically defining JCR node types. JBoss DNA supports a comparable node type definition API that implements the functionality from the specification, albeit with interfaces in the <code>org.jboss.dna.jcr.nodetype</code> package. The intent is to deprecate these classes and replace their usage with the JSR-283 equivalents when JBoss DNA fully supports the JSR-283 final adopted specification in a future release. @@ -450,14 +446,24 @@ &JcrNodeTypeManager; nodeTypeManager = (JcrNodeTypeManager) workspace.getNodeTypeManager(); nodeTypeManager.registerNodeTypes(nodeTypeSource); </programlisting> + The &CndNodeTypeSource; class actually implements the &JcrNodeTypeSource; interface, so other implementations can actually be defined. For more information, see the JavaDoc for &JcrNodeTypeSource;. - <note> - <para> JBoss DNA does not yet support a simple means of unregistering types at this time, so be careful before registering types outside of a - sandboxed environment. - </para> - </note> + </para> + <para> + JBoss DNA now supports a simple means of unregistering types, although it is not possible to unregister types that are + currently being used by nodes or as required primary types or supertypes of other types. Unused node types can be unregistered + with the following code: +<programlisting> +String unusedNodeTypeName = ...; +&Session; session = ... ; +// Obtain the DNA-specific node type manager ... +&Workspace; workspace = session.getWorkspace(); +&JcrNodeTypeManager; nodeTypeManager = (JcrNodeTypeManager) workspace.getNodeTypeManager(); +nodeTypeManager.unregisterNodeType(Collections.singleton(unusedNodeTypeName)); +</programlisting> + </para> </sect2> </sect1> 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 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/jcr/query_and_search.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -33,12 +33,12 @@ <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 + but 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 + JBoss DNA now supports this query feature, including the required XPath language and two other languages not + defined in the <ulink url="&JSR170;">JCR 1.0</ulink> 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"> @@ -46,7 +46,7 @@ <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: + and reconstituting queries that were stored on &Node;s. Thus, querying a repository generally follows this pattern: </para> <programlisting role="JAVA"><![CDATA[ // Obtain the query manager for the session ... @@ -101,7 +101,7 @@ 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. + A 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 @@ -229,7 +229,7 @@ <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. + predicate tests on any other location steps are optional. </para> <para> JBoss DNA does support using attribute tests on the last location step to specify @@ -536,14 +536,14 @@ <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. + of discrete 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. + Support for the <code>BETWEEN</code> clause to more easily and concisely supply a range of discrete 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> Modified: trunk/docs/reference/src/main/docbook/en-US/content/jcr/rest_service.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/jcr/rest_service.xml 2010-01-10 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/jcr/rest_service.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -73,7 +73,7 @@ <entry>Returns a list of available operations within the workspace</entry> <entry>GET</entry> </row> - <row> + <row>` <entry>/resources/{repositoryName}/{workspaceName}/item/{path}</entry> <entry>Accesses the item (node or property) at the path</entry> <entry>ALL</entry> @@ -271,6 +271,7 @@ The DNA REST server is deployed as a WAR and configured mostly through its web configuration file (web.xml). Here is an example web configuration that is used for integration testing of the DNA REST server along with an explanation of its parts. + </para> <programlisting role="XML"><![CDATA[ <?xml version="1.0"?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" @@ -278,11 +279,13 @@ <web-app> <display-name>JBoss DNA JCR RESTful Interface</display-name> ]]></programlisting> + <para> This first section is largely boilerplate and should look familiar to anyone who has deployed a servlet-based application before. The display-name can be customized, of course. </para> <para> The next stanza configures the <link linkend="jcr_rest_spi">repository provider</link>. + </para> <programlisting role="XML"><![CDATA[ <!-- This parameter provides the fully-qualified name of a class that implements @@ -294,6 +297,7 @@ <param-value>org.jboss.dna.web.jcr.rest.spi.DnaJcrRepositoryProvider</param-value> </context-param> ]]></programlisting> + <para> As noted above, this parameter informs the &DnaJcrDeployer; of the specific repository provider in use. Unless you are using the JBoss DNA REST server to connect to a different JCR implementation, this should never change. @@ -301,6 +305,7 @@ <para> Next we configure the DNA &JcrEngine; itself. + </para> <programlisting role="XML"><![CDATA[ <!-- This parameter, specific to the DnaJcrRepositoryProvider implementation, specifies @@ -313,6 +318,7 @@ <param-value>/configRepository.xml</param-value> </context-param> ]]></programlisting> + <para> If you are not familiar with the file format for a &JcrEngine; configuration file, you can build one programatically with the &JcrConfiguration; class and call <code>save(...)</code> instead of <code>build()</code> to output the configuration file that equates to the configuration. @@ -320,6 +326,7 @@ <para> This is followed by a bit of RESTEasy and JAX-RS boilerplate. + </para> <programlisting role="XML"><![CDATA[ <!-- This parameter defines the JAX-RS application class, which is really just a metadata class @@ -356,11 +363,13 @@ </servlet-mapping> ]]></programlisting> + <para> In general, this part of the web configuration file should not be modified. </para> <para> Finally, security must be configured for the REST server. + </para> <programlisting role="XML"><![CDATA[ <!-- The JBoss DNA REST implementation leverages the HTTP credentials to for authentication and authorization @@ -401,6 +410,7 @@ </web-app> ]]></programlisting> + <para> As noted above, the REST server will not function properly unless security is configured. All authorization methods supported by the Servlet specification are supported by JBoss DNA and can be used interchangeable, as long as authenticated users have the connect role listed above. @@ -418,10 +428,11 @@ <para> If you are using Maven to build your projects, the WAR can be built from a POM. Here is a portion of the POM used to build the JBoss DNA REST Server integration subproject. + </para> <programlisting role='XML'><![CDATA[ <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> +xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <artifactId>dna</artifactId> @@ -457,6 +468,7 @@ </project> ]]></programlisting> + <para> If you use this approach, make sure that web configuration file is in the <code>/src/main/webapp/WEB-INF</code> directory. </para> @@ -470,42 +482,45 @@ | + log4j.properties (Optional) + /lib | + activation-1.1.jar - | + antlr-runtime-3.1.3.jar | + commons-codec-1.2.jar | + commons-httpclient-3.1.jar | + commons-logging-1.0.4.jar - | + dna-cnd-0.6.jar - | + dna-common-0.6.jar - | + dna-connector-federation-0.6.jar - | + dna-graph-0.6.jar - | + dna-jcr-0.6.jar - | + dna-repository-0.6.jar - | + dna-web-jcr-rest-0.6.jar - | + FastInfoset-1.2.2.jar - | + google-collect-snapshot-20080530.jar + | + dna-cnd-0.7.jar + | + dna-common-0.7.jar + | + dna-graph-0.7.jar + | + dna-jcr-0.7.jar + | + dna-repository-0.7.jar + | + dna-search-lucene-0.7.jar + | + dna-web-jcr-rest-0.7.jar + | + google-collections-1.0-rc3.jar | + hamcrest-core-1.1.jar + | + httpclient-4.0.jar + | + httpcore-4.0.1.jar + | + jakarta-regexp-1.4.jar | + javassist-3.6.0.GA.jar | + jaxb-api-2.1.jar - | + jaxb-impl-2.1.9.jar - | + jaxrs-api-1.1-RC2.jar + | + jaxb-impl-2.1.12.jar + | + jaxrs-api-1.2.1-GA.jar | + jcip-annotations-1.0.jar + | + jcl-over-slf4j-1.5.8.jar | + jcr-1.0.1.jar - | + jettison-1.0.1.jar + | + jettison-1.1.jar | + joda-time-1.4.jar | + jsr250-api-1.0.jar | + junit-dep-4.4.jar - | + resteasy-client-1.0-beta-8.jar - | + resteasy-common-1.0-beta-8.jar - | + resteasy-jaxb-provider-1.1-RC2.jar - | + resteasy-jaxrs-1.1-RC2.jar + | + lucene-analyzers-3.0.0.jar + | + lucene-core-3.0.0.jar + | + lucene-regex-3.0.0.jar + | + lucene-snowball-3.0.0.jar + | + resteasy-jaxb-provider-1.2.1-GA.jar + | + resteasy-jettison-provider-1.2.1-GA.jar | + scannotation-1.0.2.jar | + servlet-api-2.5.jar | + sjsxp-1.0.1.jar - | + slf4j-api-1.4.3.jar - | + slf4j-log4j12-1.4.3.jar - | + slf4j-simple-1.5.2.jar + | + slf4j-api-1.5.8.jar + | + slf4j-log4j12-1.5.8.jar + | + slf4j-simple-1.5.8.jar | + stax-api-1.0-2.jar - | + webserver-1.3.3.jar + web.xml </programlisting> @@ -634,8 +649,8 @@ ]]></programlisting> </para> <para> - Results of successfully executing the above code is a JCR folder node (<code>nt:folder</code>) for each segment of the - workspace path (a node is created if it doesn't already exist). Also, a JCR file node (a node with primary type <code>nt:file</code>) is + Successfully executing the above code results in the creation a JCR folder node (<code>nt:folder</code>) for each segment of the + workspace path (if the folder didn't already exist). Also, a JCR file node (a node with primary type <code>nt:file</code>) is created or updated under the last folder node and the file contents are encoded and uploaded into a child node of that file node. </para> </sect1> Modified: trunk/docs/reference/src/main/docbook/en-US/content/sequencers/compact_node_types.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/sequencers/compact_node_types.xml 2010-01-10 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/sequencers/compact_node_types.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -38,7 +38,8 @@ <para> This sequencer can be added to the repository configuration like so: -<programlisting role="JAVA"><![CDATA[ + </para> + <programlisting role="JAVA"><![CDATA[ JcrConfiguration config = ... config.sequencer("CND Sequencer") @@ -48,5 +49,4 @@ .sequencingFrom("//(*.cnd[*])/jcr:content[@jcr:data]") .andOutputtingTo("/nodeTypes/$1"); ]]></programlisting> - </para> </chapter> \ No newline at end of file Modified: trunk/docs/reference/src/main/docbook/en-US/content/sequencers/ddl.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/sequencers/ddl.xml 2010-01-10 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/sequencers/ddl.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -37,7 +37,7 @@ to their grammar, and thus require dialect-specific additions to the graph structure. </para> <para> - The sequencer is designed to behave as smart as possible with as little configuration. Thus, the sequencer + The sequencer is designed to behave as intelligently as possible with as little configuration. Thus, the sequencer automatically determines the dialect used by a given DDL stream. This can be tricky, of course, since most dialects are very similar and the distinguishing features of a dialect may only be apparent in some of the statements. </para> Modified: trunk/docs/reference/src/main/docbook/en-US/content/sequencers/java_class.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/sequencers/java_class.xml 2010-01-10 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/content/sequencers/java_class.xml 2010-01-10 23:32:54 UTC (rev 1588) @@ -106,7 +106,7 @@ <class:annotation jcr:name="AnnotationNameN"/> </class:method> </class:methods> - <class:fields jcr:name="class:field"> + <class:fields jcr:name="class:fields"> <class:field jcr:name="fieldName"> <class:annotation jcr:name="AnnotationName1"/> ... Modified: trunk/docs/reference/src/main/docbook/en-US/custom.dtd =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/custom.dtd 2010-01-10 20:35:10 UTC (rev 1587) +++ trunk/docs/reference/src/main/docbook/en-US/custom.dtd 2010-01-10 23:32:54 UTC (rev 1588) @@ -92,6 +92,7 @@ <!ENTITY UrlEncoder "<ulink url='&API;common/text/Jsr283Encoder.html'><classname>UrlEncoder</classname></ulink>"> <!ENTITY XmlNameEncoder "<ulink url='&API;common/text/Jsr283Encoder.html'><classname>XmlNameEncoder</classname></ulink>"> <!ENTITY XmlValueEncoder "<ulink url='&API;common/text/XmlValueEncoder.html'><classname>XmlValueEncoder</classname></ulink>"> +<!ENTITY FileNameEncoder "<ulink url='&API;common/text/FileNameEncoder.html'><classname>FileNameEncoder</classname></ulink>"> <!ENTITY Problem "<ulink url='&API;common/collection/Problem.html'><interface>Problem</interface></ulink>"> <!ENTITY Problems "<ulink url='&API;common/collection/Problems.html'><interface>Problems</interface></ulink>"> @@ -172,12 +173,13 @@ <!ENTITY MimeTypeDetector "<ulink url='&API;graph/mimetype/MimeTypeDetector.html'><interface>MimeTypeDetector</interface></ulink>"> <!ENTITY MockSequencerOutput "<ulink url='&API;graph/sequencer/MockSequencerOutput.html'><interface>MockSequencerOutput</interface></ulink>"> <!ENTITY MockSequencerContext "<ulink url='&API;graph/sequencer/MockSequencerContext.html'><interface>MockSequencerContext</interface></ulink>"> -<!ENTITY Observer "<ulink url='&API;graph/observer/Observer.html'><interface>Observer</interface></ulink>"> -<!ENTITY Observable "<ulink url='&API;graph/observer/Observable.html'><interface>Observable</interface></ulink>"> -<!ENTITY ChangeObserver "<ulink url='&API;graph/observer/ChangeObserver.html'><classname>ChangeObserver</classname></ulink>"> -<!ENTITY NetChangeObserver "<ulink url='&API;graph/observer/NetChangeObserver.html'><classname>NetChangeObserver</classname></ulink>"> -<!ENTITY ChangeObservers "<ulink url='&API;graph/observer/ChangeObservers.html'><classname>ChangeObservers</classname></ulink>"> -<!ENTITY Changes "<ulink url='&API;graph/observer/Changes.html'><classname>Changes</classname></ulink>"> +<!ENTITY Observer "<ulink url='&API;graph/observe/Observer.html'><interface>Observer</interface></ulink>"> +<!ENTITY Observable "<ulink url='&API;graph/observe/Observable.html'><interface>Observable</interface></ulink>"> +<!ENTITY ChangeObserver "<ulink url='&API;graph/observe/ChangeObserver.html'><classname>ChangeObserver</classname></ulink>"> +<!ENTITY NetChange "<ulink url='&API;graph/observe/NetChange.html'><classname>NetChange</classname></ulink>"> +<!ENTITY NetChangeObserver "<ulink url='&API;graph/observe/NetChangeObserver.html'><classname>NetChangeObserver</classname></ulink>"> +<!ENTITY ChangeObservers "<ulink url='&API;graph/observe/ChangeObservers.html'><classname>ChangeObservers</classname></ulink>"> +<!ENTITY Changes "<ulink url='&API;graph/observe/Changes.html'><classname>Changes</classname></ulink>"> <!ENTITY SearchEngine "<ulink url='&API;graph/search/SearchEngine.html'><interface>SearchEngine</interface></ulink>"> <!-- Types in dna-repository -->