Author: rhauch Date: 2009-06-09 00:32:58 -0400 (Tue, 09 Jun 2009) New Revision: 1004 Modified: trunk/docs/reference/src/main/docbook/en-US/content/connectors/federation.xml trunk/docs/reference/src/main/docbook/en-US/content/connectors/in_memory.xml trunk/docs/reference/src/main/docbook/en-US/content/connectors/jboss_cache.xml trunk/docs/reference/src/main/docbook/en-US/content/core/connector.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/sequencers/compact_node_types.xml trunk/docs/reference/src/main/docbook/en-US/content/sequencers/image.xml trunk/docs/reference/src/main/docbook/en-US/content/sequencers/java_source.xml trunk/docs/reference/src/main/docbook/en-US/content/sequencers/microsoft_office.xml trunk/docs/reference/src/main/docbook/en-US/content/sequencers/mp3.xml trunk/docs/reference/src/main/docbook/en-US/content/sequencers/xml.xml trunk/docs/reference/src/main/docbook/en-US/content/sequencers/zip.xml trunk/docs/reference/src/main/docbook/en-US/custom.dtd Log: Completed (pending editing/reviews) the chapter on the graph model. 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 2009-06-09 03:30:56 UTC (rev 1003) +++ trunk/docs/reference/src/main/docbook/en-US/content/connectors/federation.xml 2009-06-09 04:32:58 UTC (rev 1004) @@ -30,8 +30,160 @@ ]> <chapter id="federation-connector"> <title>Federation Connector</title> - <para> - blah blah - </para> + <para> + The federated repository source provides a unified repository consisting of information that is dynamically federated from multiple other + &RepositorySource; instances. This is a very powerful repository source that appears to be a single repository, when in + fact the content is stored and managed in multiple other systems. Each &FederatedRepositorySource; is typically configured + with the name of another &RepositorySource; that should be used as the local, unified cache of the federated content. + The configuration also contains the names of the other &RepositorySource; instances that are to be federated along with + the &Projection; definition describing where in the unified repository the content is to appear. + </para> + <figure id="dna-connector-federation-image"> + <title>Federating multiple sources using the Federated Repository Connector</title> + <graphic align="center" scale="100" fileref="dna-connector-federation.png"/> + </figure> + <para> The federation connector works by effectively building up a single graph by querying each source and merging or + unifying the responses. This information is cached, which improves performance, reduces the number of (potentially + expensive) remote calls, reduces the load on the sources, and helps mitigate problems with source availability. As + clients interact with the repository, this cache is consulted first. When the requested portion of the graph (or + "subgraph") is contained completely in the cache, it is retuned immediately. However, if any part of the requested + subgraph is not in the cache, each source is consulted for their contributions to that subgraph, and any results are + cached.</para> + <para> This basic flow makes it possible for the federated repository to build up a local cache of the integrated graph + (or at least the portions that are used by clients). In fact, the federated repository caches information in a manner + that is similar to that of the Domain Name System (DNS). As sources are consulted for their contributions, the source + also specifies whether it is the authoritative source for this information (some sources that are themselves federated + may not be the information's authority), whether the information may be modified, the time-to-live (TTL) value (the time + after which the cached information should be refreshed), and the expiration time (the time after which the cached + information is no longer valid). In effect, the source has complete control over how the information it contributes is + cached and used.</para> + <para> + The federated repository also needs to incorporate <emphasis>negative caching</emphasis>, which is storage of the knowledge + that something does <emphasis>not</emphasis> exist. Sources can be configured to contribute information + only below certain paths (e.g., <code>/A/B/C</code>), and the federation engine can take advantage of this by never + consulting that source for contributions to information on other paths. However, below that path, any negative responses + must also be cached (with appropriate TTL and expiry parameters) to prevent the exclusion of that source (in case the source + has information to contribute at a later time) or the frequent checking with the source. + </para> + <para> + The federated repository uses other &RepositorySource;s that are to be federated and a &RepositorySource; that is to be used as the + cache of the unified contents. These are configured in another &RepositorySource; that is treated as a configuration repository. + The &FederatedRepositorySource; class uses JavaBean properties to define the name of the configuration repository and + the path to the "<code>dna:federation</code>" node in that configuration repository containing the information about the + cache and federated sources. This graph structure that is expected at this location is as follows: + </para> + <programlisting><![CDATA[<!-- Define the federation configuration. --> +<dna:federatedRepository xmlns:dna="http://www.jboss.org/dna" + xmlns:jcr="http://www.jcp.org/jcr/1.0" + dna:timeToCache="100000" > + <dna:workspaces> + <dna:workspace jcr:name="default"> + <!-- Define how the content in the 'Cache' source is to map to the federated cache --> + <dna:cache dna:sourceName="Cache" dna:workspaceName="default" dna:projectionRules="/a => /" /> + + <!-- Define how the content in the two sources maps to the federated/unified repository. + This example puts the 'Cars' and 'Aircraft' content underneath '/vehicles', but the + 'Configuration' content (which is defined by this file) will appear under '/'. --> + <dna:projections> + <dna:projection jcr:name="Cars" dna:projectionRules="/Vehicles => /" /> + <dna:projection jcr:name="Aircraft" dna:projectionRules="/Vehicles => /" /> + <dna:projection jcr:name="Configuration" dna:projectionRules="/ => /" /> + </dna:projections> + </dna:workspace> + </dna:workspaces> +</dna:federatedRepository> +]]></programlisting> + <note> + <para> + 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 + works. + </para> + </note> + <para> + Notice that there is a cache projection and three source projections, and each projection defines + one or more <emphasis>projection rules</emphasis> that are of the form: + </para> + <programlisting>pathInFederatedRepository =&gt; pathInSourceRepository</programlisting> + <para> + So, a projection rule <code>/Vehicles =&gt; /</code> projects the entire contents of the source so that + it appears in the federated repository under the "<code>/Vehicles</code>" node. + </para> + <para> + The &FederatedRepositorySource; class provides a number of JavaBean properties that control its behavior: + </para> + <table frame='all'> + <title>&FederatedRepositorySource; properties</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*"/> + <colspec colname='c2' colwidth="1*"/> + <thead> + <row> + <entry>Property</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>name</entry> + <entry>The name of the repository source, which is used by the &RepositoryService; when obtaining a &RepositoryConnection; by name.</entry> + </row> + <row> + <entry>repositoryName</entry> + <entry>The name for the federated repository.</entry> + </row> + <row> + <entry>configurationSourceName</entry> + <entry>The name of the &RepositorySource; that should be used as the configuration repository, and in which is defined + how this federated repository is to be set up and configured. + This name is supplied to the &RepositoryConnectionFactory; that is provided to this instance when added to the + &RepositoryLibrary;.</entry> + </row> + <row> + <entry>configurationWorkspaceName</entry> + <entry>The name of the workspace in the configuration &RepositorySource; with the content defining + how this federated repository is to be set up and configured.</entry> + </row> + <row> + <entry>configurationSourcePath</entry> + <entry>The path to the node in the configuration repository below which a "dna:federation" node exists with the + graph structure describing how this federated repository is to be configured.</entry> + </row> + <row> + <entry>securityDomain</entry> + <entry>Optional property that, if used, specifies the name of the JAAS application context that should be used + to establish the <link linkend="execution-contenxt">execution context</link> for this repository. + This should correspond to the JAAS login configuration located within the JAAS login configuration file, + and should be used only if a "<code>username</code>" property is defined.</entry> + </row> + <row> + <entry>username</entry> + <entry>Optional property that, if used, defines the name of the JAAS subject that should be used + to establish the <link linkend="execution-contenxt">execution context</link> for this repository. + This should be used if a "<code>securityDomain</code>" property is defined.</entry> + </row> + <row> + <entry>password</entry> + <entry>Optional property that, if used, defines the password of the JAAS subject that should be used + to establish the <link linkend="execution-contenxt">execution context</link> for this repository. + If the password is not provided but values for the "<code>securityDomain</code>" and "<code>username</code>" properties are, + then authentication will use the default JAAS callback handlers.</entry> + </row> + <row> + <entry>retryLimit</entry> + <entry>Optional property that, if used, defines the number of times that any single operation on a &RepositoryConnection; to this source should be retried + following a communication failure. The default value is '0'.</entry> + </row> + <row> + <entry>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> + </tbody> + </tgroup> + </table> </chapter> 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 2009-06-09 03:30:56 UTC (rev 1003) +++ trunk/docs/reference/src/main/docbook/en-US/content/connectors/in_memory.xml 2009-06-09 04:32:58 UTC (rev 1004) @@ -31,7 +31,56 @@ <chapter id="in-memory-connector"> <title>In-Memory Connector</title> <para> - blah blah + The in-memory repository connector is a simple connector that creates a transient, in-memory repository. + This repository is used as a very simple in-memory cache or as a standalone transient repository. </para> + <para> + The &InMemoryRepositorySource; class provides a number of JavaBean properties that control its behavior: + </para> + <table frame='all'> + <title>&InMemoryRepositorySource; properties</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*"/> + <colspec colname='c2' colwidth="1*"/> + <thead> + <row> + <entry>Property</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>name</entry> + <entry>The name of the repository source, which is used by the &RepositoryService; when obtaining a &RepositoryConnection; by name.</entry> + </row> + <row> + <entry>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>rootNodeUuid</entry> + <entry>Optional property that, if used, defines the UUID of the root node in the in-memory repository. If not used, + then a new UUID is generated.</entry> + </row> + <row> + <entry>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>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> </chapter> 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 2009-06-09 03:30:56 UTC (rev 1003) +++ trunk/docs/reference/src/main/docbook/en-US/content/connectors/jboss_cache.xml 2009-06-09 04:32:58 UTC (rev 1004) @@ -31,7 +31,78 @@ <chapter id="jboss-cache-connector"> <title>JBoss Cache Connector</title> <para> - blah blah + 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. </para> + <para> + The &JBossCacheSource; class provides a number of JavaBean properties that control its behavior: + </para> + <table frame='all'> + <title>&JBossCacheSource; properties</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*"/> + <colspec colname='c2' colwidth="1*"/> + <thead> + <row> + <entry>Property</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>name</entry> + <entry>The name of the repository source, which is used by the &RepositoryService; when obtaining a &RepositoryConnection; by name.</entry> + </row> + <row> + <entry>cacheFactoryJndiName</entry> + <entry>Optional property that, if used, specifies the name in JNDI where an existing JBoss Cache Factory instance can be found. + That factory would then be used if needed to create a JBoss Cache instance. If no value is provided, then the + 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 + a special way.</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>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>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>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 defines the names of the workspaces that exist and that are available for use without having to create them.</entry> + </row> + <row> + <entry>creatingWorkspacesAllowed</entry> + <entry>Optional property that is by default 'true' that defines whether clients can create new workspaces.</entry> + </row> + </tbody> + </tgroup> + </table> </chapter> 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 2009-06-09 03:30:56 UTC (rev 1003) +++ trunk/docs/reference/src/main/docbook/en-US/content/core/connector.xml 2009-06-09 04:32:58 UTC (rev 1004) @@ -169,7 +169,7 @@ </sect1> <sect1 id="repository-workspaces"> <title>Workspaces</title> - <para>The previous section talked about how connector expose their information through the graph language of JBoss DNA. + <para>The <link linkend="graph-api-workspaces">previous chapter</link> talked about how connector expose their information through the graph language of JBoss DNA. This is true, except that we didn't dive into too much of the detail. JBoss DNA graphs have the notion of <emphasis>workspaces</emphasis> in which the content appears, and its very easy for clients using the graph to switch between workspaces. In fact, workspaces differ from each other in that they provide different views of the same information. @@ -277,300 +277,11 @@ <sect1 id="connector-library"> <title>Out-of-the-box repository connectors</title> <para> - A number of repository connectors are already available in JBoss DNA, and are outlined in the following sections. + A number of repository connectors are already available in JBoss DNA, and are outlined in detail + <link linkend="provied-connectors-part">later in the document</link>. Note that we do want to build <ulink url="https://jira.jboss.org/jira/secure/IssueNavigator.jspa?reset=tr... connectors</ulink> in the upcoming releases. </para> - <sect2 id="dna-connector-inmemory"> - <title>In-memory connector</title> - <para> - The in-memory repository connector is a simple connector that creates a transient, in-memory repository. - This repository is used as a very simple in-memory cache or as a standalone transient repository. - </para> - <para> - The &InMemoryRepositorySource; class provides a number of JavaBean properties that control its behavior: - </para> - <table frame='all'> - <title>&InMemoryRepositorySource; properties</title> - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth="1*"/> - <colspec colname='c2' colwidth="1*"/> - <thead> - <row> - <entry>Property</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>name</entry> - <entry>The name of the repository source, which is used by the &RepositoryService; when obtaining a &RepositoryConnection; by name.</entry> - </row> - <row> - <entry>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>rootNodeUuid</entry> - <entry>Optional property that, if used, defines the UUID of the root node in the in-memory repository. If not used, - then a new UUID is generated.</entry> - </row> - <row> - <entry>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>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> - </sect2> - <sect2 id="dna-connector-jbosscache"> - <title>JBoss Cache connector</title> - <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="dna-connector-federation">federated</link> - repository. - </para> - <para> - The &JBossCacheSource; class provides a number of JavaBean properties that control its behavior: - </para> - <table frame='all'> - <title>&JBossCacheSource; properties</title> - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth="1*"/> - <colspec colname='c2' colwidth="1*"/> - <thead> - <row> - <entry>Property</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>name</entry> - <entry>The name of the repository source, which is used by the &RepositoryService; when obtaining a &RepositoryConnection; by name.</entry> - </row> - <row> - <entry>cacheFactoryJndiName</entry> - <entry>Optional property that, if used, specifies the name in JNDI where an existing JBoss Cache Factory instance can be found. - That factory would then be used if needed to create a JBoss Cache instance. If no value is provided, then the - 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 - a special way.</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>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>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>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 defines the names of the workspaces that exist and that are available for use without having to create them.</entry> - </row> - <row> - <entry>creatingWorkspacesAllowed</entry> - <entry>Optional property that is by default 'true' that defines whether clients can create new workspaces.</entry> - </row> - </tbody> - </tgroup> - </table> - </sect2> - <sect2 id="dna-connector-federation"> - <title>Federating connector</title> - <para> - The federated repository source provides a unified repository consisting of information that is dynamically federated from multiple other - &RepositorySource; instances. This is a very powerful repository source that appears to be a single repository, when in - fact the content is stored and managed in multiple other systems. Each &FederatedRepositorySource; is typically configured - with the name of another &RepositorySource; that should be used as the local, unified cache of the federated content. - The configuration also contains the names of the other &RepositorySource; instances that are to be federated along with - the &Projection; definition describing where in the unified repository the content is to appear. - </para> - <figure id="dna-connector-federation-image"> - <title>Federating multiple sources using the Federated Repository Connector</title> - <graphic align="center" scale="100" fileref="dna-connector-federation.png"/> - </figure> - <para> The federation connector works by effectively building up a single graph by querying each source and merging or - unifying the responses. This information is cached, which improves performance, reduces the number of (potentially - expensive) remote calls, reduces the load on the sources, and helps mitigate problems with source availability. As - clients interact with the repository, this cache is consulted first. When the requested portion of the graph (or - "subgraph") is contained completely in the cache, it is retuned immediately. However, if any part of the requested - subgraph is not in the cache, each source is consulted for their contributions to that subgraph, and any results are - cached.</para> - <para> This basic flow makes it possible for the federated repository to build up a local cache of the integrated graph - (or at least the portions that are used by clients). In fact, the federated repository caches information in a manner - that is similar to that of the Domain Name System (DNS). As sources are consulted for their contributions, the source - also specifies whether it is the authoritative source for this information (some sources that are themselves federated - may not be the information's authority), whether the information may be modified, the time-to-live (TTL) value (the time - after which the cached information should be refreshed), and the expiration time (the time after which the cached - information is no longer valid). In effect, the source has complete control over how the information it contributes is - cached and used.</para> - <para> - The federated repository also needs to incorporate <emphasis>negative caching</emphasis>, which is storage of the knowledge - that something does <emphasis>not</emphasis> exist. Sources can be configured to contribute information - only below certain paths (e.g., <code>/A/B/C</code>), and the federation engine can take advantage of this by never - consulting that source for contributions to information on other paths. However, below that path, any negative responses - must also be cached (with appropriate TTL and expiry parameters) to prevent the exclusion of that source (in case the source - has information to contribute at a later time) or the frequent checking with the source. - </para> - <para> - The federated repository uses other &RepositorySource;s that are to be federated and a &RepositorySource; that is to be used as the - cache of the unified contents. These are configured in another &RepositorySource; that is treated as a configuration repository. - The &FederatedRepositorySource; class uses JavaBean properties to define the name of the configuration repository and - the path to the "<code>dna:federation</code>" node in that configuration repository containing the information about the - cache and federated sources. This graph structure that is expected at this location is as follows: - </para> - <programlisting><![CDATA[<!-- Define the federation configuration. --> -<dna:federatedRepository xmlns:dna="http://www.jboss.org/dna" - xmlns:jcr="http://www.jcp.org/jcr/1.0" - dna:timeToCache="100000" > - <dna:workspaces> - <dna:workspace jcr:name="default"> - <!-- Define how the content in the 'Cache' source is to map to the federated cache --> - <dna:cache dna:sourceName="Cache" dna:workspaceName="default" dna:projectionRules="/a => /" /> - - <!-- Define how the content in the two sources maps to the federated/unified repository. - This example puts the 'Cars' and 'Aircraft' content underneath '/vehicles', but the - 'Configuration' content (which is defined by this file) will appear under '/'. --> - <dna:projections> - <dna:projection jcr:name="Cars" dna:projectionRules="/Vehicles => /" /> - <dna:projection jcr:name="Aircraft" dna:projectionRules="/Vehicles => /" /> - <dna:projection jcr:name="Configuration" dna:projectionRules="/ => /" /> - </dna:projections> - </dna:workspace> - </dna:workspaces> -</dna:federatedRepository> -]]></programlisting> - <note> - <para> - 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 - works. - </para> - </note> - <para> - Notice that there is a cache projection and three source projections, and each projection defines - one or more <emphasis>projection rules</emphasis> that are of the form: - </para> - <programlisting>pathInFederatedRepository =&gt; pathInSourceRepository</programlisting> - <para> - So, a projection rule <code>/Vehicles =&gt; /</code> projects the entire contents of the source so that - it appears in the federated repository under the "<code>/Vehicles</code>" node. - </para> - <para> - The &FederatedRepositorySource; class provides a number of JavaBean properties that control its behavior: - </para> - <table frame='all'> - <title>&FederatedRepositorySource; properties</title> - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth="1*"/> - <colspec colname='c2' colwidth="1*"/> - <thead> - <row> - <entry>Property</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>name</entry> - <entry>The name of the repository source, which is used by the &RepositoryService; when obtaining a &RepositoryConnection; by name.</entry> - </row> - <row> - <entry>repositoryName</entry> - <entry>The name for the federated repository.</entry> - </row> - <row> - <entry>configurationSourceName</entry> - <entry>The name of the &RepositorySource; that should be used as the configuration repository, and in which is defined - how this federated repository is to be set up and configured. - This name is supplied to the &RepositoryConnectionFactory; that is provided to this instance when added to the - &RepositoryLibrary;.</entry> - </row> - <row> - <entry>configurationWorkspaceName</entry> - <entry>The name of the workspace in the configuration &RepositorySource; with the content defining - how this federated repository is to be set up and configured.</entry> - </row> - <row> - <entry>configurationSourcePath</entry> - <entry>The path to the node in the configuration repository below which a "dna:federation" node exists with the - graph structure describing how this federated repository is to be configured.</entry> - </row> - <row> - <entry>securityDomain</entry> - <entry>Optional property that, if used, specifies the name of the JAAS application context that should be used - to establish the <link linkend="execution-contenxt">execution context</link> for this repository. - This should correspond to the JAAS login configuration located within the JAAS login configuration file, - and should be used only if a "<code>username</code>" property is defined.</entry> - </row> - <row> - <entry>username</entry> - <entry>Optional property that, if used, defines the name of the JAAS subject that should be used - to establish the <link linkend="execution-contenxt">execution context</link> for this repository. - This should be used if a "<code>securityDomain</code>" property is defined.</entry> - </row> - <row> - <entry>password</entry> - <entry>Optional property that, if used, defines the password of the JAAS subject that should be used - to establish the <link linkend="execution-contenxt">execution context</link> for this repository. - If the password is not provided but values for the "<code>securityDomain</code>" and "<code>username</code>" properties are, - then authentication will use the default JAAS callback handlers.</entry> - </row> - <row> - <entry>retryLimit</entry> - <entry>Optional property that, if used, defines the number of times that any single operation on a &RepositoryConnection; to this source should be retried - following a communication failure. The default value is '0'.</entry> - </row> - <row> - <entry>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> - </tbody> - </tgroup> - </table> - </sect2> </sect1> <sect1 id="custom-connectors"> <title>Writing custom connectors</title> @@ -1288,174 +999,6 @@ </para> </sect2> </sect1> - <sect1 id="dna_graph_api"> - <title>Graph API for using connectors</title> - <para> - So far we've talked about repositories, repository connectors, and how connectors respond to the different kinds of requests. - Normally you'd code to the JCR API and use our JCR implementation. However, what does your code look like if you want - to use the connectors directly, without using our JCR implementation? After all, you may be a contributor to JBoss DNA, - or you may want to take advantage of our connectors without all the overhead of JCR. - </para> - <para> - One option, of course, is to explicitly create the different requests and pass them to the connector's <code>execute(...)</code> method. - While this is the most efficient approach (and one taken in some key DNA components), you probably want something that - is much less verbose and much easier to use. This is where the DNA graph API comes in. - </para> - <para> - JBoss DNA's <emphasis>Graph API</emphasis> was designed as a lightweight public API for working with graph information, - and it insulates components from the underlying requests and interacting with connectors. - The &Graph; class is the primary class in API, and each instance represents a single, independent - view of the graph of content from a single connector. &Graph; instances return snapshots of state, and those snapshots - never change after they're retrieved. To obtain a &Graph; instance, use the static <code>create(...)</code> - method, supplying the name of the source, a &RepositoryConnectionFactory; from which a &RepositoryConnection; can be obtained, - and the &ExecutionContext;. - </para> - <para> - The &Graph; class basically represents an <ulink url="http://www.martinfowler.com/bliki/DomainSpecificLanguage.html&q... domain specific language (DSL)</ulink>, - designed to be easy to use in an application. - The Graph API makes extensive use of interfaces and method chaining, so that methods return a concise interface that has only those - methods that make sense at that point. In fact, this should be really easy if your IDE has code completion. - Just remember that under the covers, a &Graph; is just building &Request; objects, submitting them to the connector, - and then exposing the results. - </para> - <sect2 id="dna_graph_api_workspaces"> - <title>Using workspaces</title> - <para> - Let's look at some examples of how the Graph API works. This first example shows how to obtain the names of the available workspaces: - </para> - <programlisting> -&Set;&lt;&String;> workspaceNames = graph.getWorkspaces(); -</programlisting> - <para>Once you know the name of the workspace, you can specify that the graph should use it: - </para> - <programlisting> -graph.useWorkspace("myWorkspace"); -</programlisting> - <para> - From this point forward, all requests will apply to the workspace named "myWorkspace". At any time, you can use a different workspace, - which will affect all subsequent requests made using the graph. Of course, creating a new workspace is just as easy: - </para> - <programlisting> -graph.createWorkspace().named("newWorkspace"); -</programlisting> - <para>This will attempt to create a workspace named "newWorkspace", which will fail if that workspace already exists. You may - want to create a new workspace with a name that should be altered if the name you supply is already used. The following code shows - how you can do this: - </para> - <programlisting> -graph.createWorkspace().namedSomethingLike("newWorkspace"); -</programlisting> - <para>If there is no existing workspace named "newWorkspace", a new one will be created with this name. However, if "newWorkspace" already - exists, this call will create a workspace with a name that is some alteration of the supplied name. - </para> - <para> - You can also clone workspaces, too: - </para> - <programlisting> -graph.createWorkspace().clonedFrom("original").named("something"); -</programlisting> - <para> - or - </para> - <programlisting> -graph.createWorkspace().clonedFrom("original").namedSomethingLike("something"); -</programlisting> - <para> - As you can see, it's very easy to specify which workspace you want to use or to create new workspaces. You can also find out which workspace - the graph is currently using: - </para> - <programlisting> -&String; current = graph.getCurrentWorkspaceName(); -</programlisting> - <para>or, if you want, you can get more information about the workspace: - </para> - <programlisting> -&Workspace; current = graph.getCurrentWorkspace(); -&String; name = current.getName(); -&Location; rootLocation = current.getRoot(); -</programlisting> - </sect2> - <sect2 id="dna_graph_api_nodes"> - <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;: - </para> - <programlisting> -&Path; path = ... -Map&lt;&Name;,&Property;> propertiesByName = graph.getPropertiesByName().on(path); -</programlisting> - <para> - This next example shows how the graph can be used to obtain and loop over the properties of a node: - </para> - <programlisting> -&Path; path = ... -for ( &Property; property : graph.getProperties().on(path) ) { - ... -} -</programlisting> - <para> - Likewise, the next example shows how the graph can be used to obtain and loop over the children of a node: - </para> - <programlisting> -&Path; path = ... -for ( &Location; child : graph.getChildren().of(path) ) { - &Path; childPath = child.getPath(); - ... -} -</programlisting> - <para> - Notice that the examples pass a &Path; instance to the <code>on(...)</code> and <code>of(...)</code> methods. Many - of the Graph API methods take a variety of parameter types, including String, &Path;s, &Location;s, &UUID;, or &Property; parameters. - This should make it easy to use in many different situations. - </para> - <para> - Of course, changing content is more interesting and offers more interesting possibilities. Here are a few examples: - </para> - <programlisting> -&Path; path = ... -&Location; location = ... -&Property; idProp1 = ... -&Property; idProp2 = ... -&UUID; uuid = ... -graph.move(path).into(idProp1, idProp2); -graph.copy(path).into(location); -graph.delete(uuid); -graph.delete(idProp1,idProp2); -</programlisting> - <para> - The methods shown above work immediately, as soon as each request is built. However, there is another way to use - the &Graph; object, and that is in a <emphasis>batch</emphasis> mode. Simply create a &GraphBatch; object using the - <code>batch()</code> method, create the requests on that batch object, and then execute all of the commands on the - batch by calling its <code>execute()</code> method. That <code>execute()</code> method returns a &Results; interface - that can be used to read the node information retrieved by the batched requests. - </para> - <para> - Method chaining works really well with the batch mode, since multiple commands can be assembled together very easily: - </para> - <programlisting> -&Path; path = ... -String path2 = ... -&Location; location = ... -&Property; idProp1 = ... -&Property; idProp2 = ... -&UUID; uuid = ... -graph.batch().move(path).into(idProp1, idProp2).and().copy(path2).into(location).and().delete(uuid).execute(); -&Results; results = graph.batch().read(path2). - and().readChildren().of(idProp1,idProp2). - and().readSugraphOfDepth(3).at(uuid2). - execute(); -for ( &Location; child : results.getNode(path2) ) { - ... -} -</programlisting> - <para> - Of course, this section provided just a hint of the Graph API. - The &Graph; interface is actually quite complete and offers a full-featured approach for reading and updating a graph. - For more information, see the &Graph; JavaDocs. - </para> - </sect2> - </sect1> <sect1> <title>Summary</title> <para> 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 2009-06-09 03:30:56 UTC (rev 1003) +++ trunk/docs/reference/src/main/docbook/en-US/content/core/graph.xml 2009-06-09 04:32:58 UTC (rev 1004) @@ -715,17 +715,252 @@ as required. </para> </sect1> + <sect1 id="graph-location"> + <title>Locations</title> + <para> + In addition to &Path; objects, nodes can be identified by one or more <emphasis>identification properties</emphasis>. + These really are just &Property; instances with names that have a special meaning + (usually to <link linkend="connector-framework">connectors</link>). + JBoss DNA also defines a &Location; class that encapsulates: + <itemizedlist> + <listitem> + <para>the &Path; to the node; or</para> + </listitem> + <listitem> + <para>one or more <emphasis>identification properties</emphasis> that are likely source=specific + and that are represented with &Property; objects; or</para> + </listitem> + <listitem> + <para>a combination of both.</para> + </listitem> + </itemizedlist> + So, when a client knows the path and/or the identification properties, they can create a &Location; object + and then use that to identify the node. &Location; is a class that can be instantiated through factory + methods on the class: + </para> + <programlisting> +public abstract class &Location; implements &Iterable;&lt;&Property;>, Comparable&lt;&Location;> { + + public static &Location; create( &Path; path ) { ... } + public static &Location; create( &UUID; uuid ) { ... } + public static &Location; create( &Path; path, &UUID; uuid ) { ... } + public static &Location; create( &Path; path, &Property; idProperty ) { ... } + public static &Location; create( &Path; path, &Property; firstIdProperty, + &Property;... remainingIdProperties ) { ... } + public static &Location; create( &Path; path, &Iterable;&lt;&Property; idProperties ) { ... } + public static &Location; create( &Property; idProperty ) { ... } + public static &Location; create( &Property; firstIdProperty, + &Property;... remainingIdProperties ) { ... } + public static &Location; create( &Iterable;&lt;&Property;> idProperties ) { ... } + public static &Location; create( &List;&lt;&Property;> idProperties ) { ... } + ... +} </programlisting> + <para> + Like many of the other classes and interfaces, &Location; is immutable and cannot be changed once created. + However, there are methods on the class to create a copy of the &Location; object with a different &Path;, + a different &UUID;, or different identification properties: + </para> + <programlisting> +public abstract class &Location; implements &Iterable;&lt;&Property;>, Comparable&lt;&Location;> { + ... + public &Location; with( &Property; newIdProperty ); + public &Location; with( &Path; newPath ); + public &Location; with( &UUID; uuid ); + ... +} </programlisting> + <para> + One more thing about locations: we'll see later in the next chapter how they are used to make requests + to the <link linkend="connector-framework">connectors</link>. When creating the requests, clients usually have an + incomplete location (e.g., a path but no identification properties). When processing the requests, connectors + provide an <emphasis>actual</emphasis> location that contains the path <emphasis>and</emphasis> all identification properties. + If actual &Location; objects are then reused in subsequent requests by the client, the connectors will have the benefit of having + both the path and identification properties and may be able to more efficiently locate the identified node. + </para> + </sect1> <sect1 id="graph-api"> <title>Graph API</title> <para> - + JBoss DNA's <emphasis>Graph API</emphasis> was designed as a lightweight public API for working with graph information. + The &Graph; class is the primary class in API, and each instance represents a single, independent + view of a single graph. &Graph; instances don't maintain state, so every request (or batch of requests) operate against + the underlying graph and the return <emphasis>immutable snapshots</emphasis> of the requested state at the time + the request was made. </para> - </sect1> - <sect1 id="graph-requests"> - <title>Request Model</title> <para> - + There are several ways to obtain a &Graph; instance, as we'll see in later chapters. For the time being, the important + thing to understand is what a &Graph; instance represents and how it interacts with the underlying content to return + representations of portions of that underlying graph content. </para> + <para> + The &Graph; class basically represents an <ulink url="http://www.martinfowler.com/bliki/DomainSpecificLanguage.html&q... domain specific language (DSL)</ulink>, + designed to be easy to use in an application. + The Graph API makes extensive use of interfaces and method chaining, so that methods return a concise interface that has only those + methods that make sense at that point. In fact, this should be really easy if your IDE has code completion. + Just remember that under the covers, a &Graph; is just building &Request; objects, submitting them to the connector, + and then exposing the results. + </para> + <para> + The next few subsections describe how to use a &Graph; instance. + </para> + <sect2 id="graph-api-workspaces"> + <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 + existing workspaces, while other graphs will not allow adding or removing workspaces. Some graphs may have workspaces may show the same (or very + similar) content, while other graphs may have workspaces that each contain completely independent content. + </para> + <para> + The &Graph; object is always bound to a workspace, which initially is the <emphasis>default workspace</emphasis>. To find out + what the name of the default workspace is, simply ask for the current workspace after creating the &Graph;: + </para> + <programlisting> +&Workspace; current = graph.getCurrentWorkspace(); +</programlisting> + <para> + To obtain the list of workspaces available in a graph, simply ask for them: + </para> + <programlisting> +&Set;&lt;&String;> workspaceNames = graph.getWorkspaces(); +</programlisting> + <para>Once you know the name of a particular workspace, you can specify that the graph should use it: + </para> + <programlisting> +graph.useWorkspace("myWorkspace"); +</programlisting> + <para> + From this point forward, all requests will apply to the workspace named "myWorkspace". At any time, you can use a different workspace, + which will affect all subsequent requests made using the graph. To go back to the default workspace, simply supply a null name: + </para> + <programlisting> +graph.useWorkspace(null); +</programlisting> + <para> + Of course, creating a new workspace is just as easy: + </para> + <programlisting> +graph.createWorkspace().named("newWorkspace"); +</programlisting> + <para>This will attempt to create a workspace named "newWorkspace", which will fail if that workspace already exists. You may + want to create a new workspace with a name that should be altered if the name you supply is already used. The following code shows + how you can do this: + </para> + <programlisting> +graph.createWorkspace().namedSomethingLike("newWorkspace"); +</programlisting> + <para>If there is no existing workspace named "newWorkspace", a new one will be created with this name. However, if "newWorkspace" already + exists, this call will create a workspace with a name that is some alteration of the supplied name. + </para> + <para> + You can also clone workspaces, too: + </para> + <programlisting> +graph.createWorkspace().clonedFrom("original").named("something"); +</programlisting> + <para> + or + </para> + <programlisting> +graph.createWorkspace().clonedFrom("original").namedSomethingLike("something"); +</programlisting> + <para> + As you can see, it's very easy to specify which workspace you want to use or to create new workspaces. You can also find out which workspace + the graph is currently using: + </para> + <programlisting> +&String; current = graph.getCurrentWorkspaceName(); +</programlisting> + <para>or, if you want, you can get more information about the workspace: + </para> + <programlisting> +&Workspace; current = graph.getCurrentWorkspace(); +&String; name = current.getName(); +&Location; rootLocation = current.getRoot(); +</programlisting> + </sect2> + <sect2 id="graph_api_nodes"> + <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;: + </para> + <programlisting> +&Path; path = ... +Map&lt;&Name;,&Property;> propertiesByName = graph.getPropertiesByName().on(path); +</programlisting> + <para> + This next example shows how the graph can be used to obtain and loop over the properties of a node: + </para> + <programlisting> +&Path; path = ... +for ( &Property; property : graph.getProperties().on(path) ) { + ... +} +</programlisting> + <para> + Likewise, the next example shows how the graph can be used to obtain and loop over the children of a node: + </para> + <programlisting> +&Path; path = ... +for ( &Location; child : graph.getChildren().of(path) ) { + &Path; childPath = child.getPath(); + ... +} +</programlisting> + <para> + Notice that the examples pass a &Path; instance to the <code>on(...)</code> and <code>of(...)</code> methods. Many + of the Graph API methods take a variety of parameter types, including String, &Path;s, &Location;s, &UUID;, or &Property; parameters. + This should make it easy to use in many different situations. + </para> + <para> + Of course, changing content is more interesting and offers more interesting possibilities. Here are a few examples: + </para> + <programlisting> +&Path; path = ... +&Location; location = ... +&Property; idProp1 = ... +&Property; idProp2 = ... +&UUID; uuid = ... +graph.move(path).into(idProp1, idProp2); +graph.copy(path).into(location); +graph.delete(uuid); +graph.delete(idProp1,idProp2); +</programlisting> + <para> + The methods shown above work immediately, as soon as each request is built. However, there is another way to use + the &Graph; object, and that is in a <emphasis>batch</emphasis> mode. Simply create a &GraphBatch; object using the + <code>batch()</code> method, create the requests on that batch object, and then execute all of the commands on the + batch by calling its <code>execute()</code> method. That <code>execute()</code> method returns a &Results; interface + that can be used to read the node information retrieved by the batched requests. + </para> + <para> + Method chaining works really well with the batch mode, since multiple commands can be assembled together very easily: + </para> + <programlisting> +&Path; path = ... +String path2 = ... +&Location; location = ... +&Property; idProp1 = ... +&Property; idProp2 = ... +&UUID; uuid = ... +graph.batch().move(path).into(idProp1, idProp2) + .and().copy(path2).into(location) + .and().delete(uuid) + .execute(); +&Results; results = graph.batch().read(path2) + .and().readChildren().of(idProp1,idProp2) + .and().readSugraphOfDepth(3).at(uuid2) + .execute(); +for ( &Location; child : results.getNode(path2) ) { + ... +} +</programlisting> + <para> + Of course, this section provided just a hint of the Graph API. + The &Graph; interface is actually quite complete and offers a full-featured approach for reading and updating a graph. + For more information, see the &Graph; JavaDocs. + </para> + </sect2> </sect1> <sect1> <title>Summary</title> 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 2009-06-09 03:30:56 UTC (rev 1003) +++ trunk/docs/reference/src/main/docbook/en-US/content/core/sequencing.xml 2009-06-09 04:32:58 UTC (rev 1004) @@ -29,7 +29,7 @@ %CustomDTD; ]> <chapter id="sequencing_framework"> - <title>Sequencing content</title> + <title>Sequencing framework</title> <para>As we've mentioned before, JBoss DNA is able to work with existing JCR repositories. Your client applications make changes to the information in those repositories, and JBoss DNA automatically uses its sequencers to extract additional information from the uploaded files.</para> @@ -253,207 +253,14 @@ This filename is then used in the output path, which is where the sequenced content is placed.</para> </sect2> </sect1> - <sect1 id="sequencers"> - <title>JBoss DNA Sequencers</title> + <sect1 id="sequencer-library"> + <title>Out-of-the-box sequencers</title> <para> - JBoss DNA includes a number of sequencers "out of the box". These sequencers can be used within your application to sequence - a variety of common file formats. To use them, the only thing you have to do is define the appropriate sequencer configurations - and include the appropriate JAR files. + 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>. + Note that we do want to build <ulink url="https://jira.jboss.org/jira/secure/IssueNavigator.jspa?reset=tr... sequencers</ulink> + in the upcoming releases. </para> - <sect2 id="dna-sequencer-images"> - <title>Image sequencer</title> - <para> - A sequencer that extracts metadata from JPEG, GIF, BMP, PCX, PNG, IFF, RAS, PBM, PGM, PPM and PSD image files. - This sequencer extracts the file format, image resolution, number of bits per pixel and optionally number of images, comments - and physical resolution, and then writes this information into the repository using the following structure: - </para> - <itemizedlist> - <listitem> - <para> - <emphasis role="strong">image:metadata</emphasis> node of type <code>image:metadata</code> - </para> - </listitem> - <listitem> - <itemizedlist> - <listitem> - <para><emphasis role="strong">jcr:mimeType</emphasis> - optional string property for the mime type of the image</para> - </listitem> - <listitem> - <para><emphasis role="strong">jcr:encoding</emphasis> - optional string property for the encoding of the image</para> - </listitem> - <listitem> - <para><emphasis role="strong">image:formatName</emphasis> - string property for the name of the format</para> - </listitem> - <listitem> - <para><emphasis role="strong">image:width</emphasis> - optional integer property for the image's width in pixels</para> - </listitem> - <listitem> - <para><emphasis role="strong">image:height</emphasis> - optional integer property for the image's height in pixles</para> - </listitem> - <listitem> - <para><emphasis role="strong">image:bitsPerPixel</emphasis> - optional integer property for the number of bits per pixel</para> - </listitem> - <listitem> - <para><emphasis role="strong">image:progressive</emphasis> - optional boolean property specifying whether the image is stored in a progressive - (i.e., interlaced) form</para> - </listitem> - <listitem> - <para><emphasis role="strong">image:numberOfImages</emphasis> - optional integer property for the number of images stored in the file; defaults - to 1</para> - </listitem> - <listitem> - <para><emphasis role="strong">image:physicalWidthDpi</emphasis> - optional integer property for the physical width of the image in dots per inch</para> - </listitem> - <listitem> - <para><emphasis role="strong">image:physicalHeightDpi</emphasis> - optional integer property for the physical height of the image in dots per - inch</para> - </listitem> - <listitem> - <para><emphasis role="strong">image:physicalWidthInches</emphasis> - optional double property for the physical width of the image in inches</para> - </listitem> - <listitem> - <para><emphasis role="strong">image:physicalHeightInches</emphasis> - optional double property for the physical height of the image in inches</para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - <para> - This structure could be extended in the future to add EXIF and IPTC metadata as child nodes. For example, EXIF metadata is - structured as tags in directories, where the directories form something like namespaces, and which are used by different camera - vendors to store custom metadata. This structure could be mapped with each directory (e.g. "EXIF" or "Nikon Makernote" or - "IPTC") as the name of a child node, with the EXIF tags values stored as either properties or child nodes. - </para> - <para> - To use this sequencer, simply include the <code>dna-sequencer-images</code> JAR - in your application and configure the Sequencing Service to use this sequencer using something similar to: - </para> - <programlisting> -String name = "Image Sequencer"; -String desc = "Sequences image files to extract the characteristics of the image"; -String classname = "org.jboss.dna.sequencer.images.ImageMetadataSequencer"; -String[] classpath = null; // Use the current classpath -String[] pathExpressions = {"//(*.(jpg|jpeg|gif|bmp|pcx|png|iff|ras|pbm|pgm|ppm|psd)[*])/jcr:content[@jcr:data] =&gt; /images/$1"}; -&SequencerConfig; sequencerConfig = new &SequencerConfig;(name, desc, classname, - classpath, pathExpressions); -sequencingService.addSequencer(sequencerConfig); -</programlisting> - </sect2> - <sect2 id="dna-sequencer-msoffice"> - <title>Microsoft Office document sequencer</title> - <para> - This sequencer is included in JBoss DNA and processes Microsoft Office documents, including Word documents, Excel spreadsheets, - and PowerPoint presentations. With documents, the sequencer extracts the internal structure based on Heading styles. - With presentations, the sequencer extracts the slides, titles, text and slide thumbnails. - With spreadsheets, the sequencer extracts the names of the sheets. And, the sequencer extracts for all the files the - general file information, including the name of the author, title, keywords, subject, comments, and various dates. - </para> - <para> - To use this sequencer, simply include the <code>dna-sequencer-msoffice</code> JAR and all of the - <ulink url="http://poi.apache.org/">POI</ulink> JARs - in your application and configure the Sequencing Service to use this sequencer using something similar to: - </para> - <programlisting> -String name = "Microsoft Office Document Sequencer"; -String desc = "Sequences MS Office documents, including spreadsheets and presentations"; -String classname = "org.jboss.dna.sequencer.msoffice.MSOfficeMetadataSequencer"; -String[] classpath = null; // Use the current classpath -String[] pathExpressions = {"//(*.(doc|docx|ppt|pps|xls)[*])/jcr:content[@jcr:data] =&gt; /msoffice/$1"}; -&SequencerConfig; sequencerConfig = new &SequencerConfig;(name, desc, classname, - classpath, pathExpressions); -sequencingService.addSequencer(sequencerConfig); -</programlisting> - </sect2> - <sect2 id="dna-sequencer-zip"> - <title>ZIP archive sequencer</title> - <para> - The ZIP file sequencer is included in JBoss DNA and extracts the files and folders contained in the ZIP archive file, - extracting the files and folders into the repository using JCR's <code>nt:file</code> and <code>nt:folder</code> node types. - </para> - <para> - To use this sequencer, simply include the <code>dna-sequencer-zip</code> JAR - in your application and configure the Sequencing Service to use this sequencer using something similar to: - </para> - <programlisting> -String name = "ZIP Sequencer"; -String desc = "Sequences ZIP archives to extract the files and folders"; -String classname = "org.jboss.dna.sequencer.zip.ZipSequencer"; -String[] pathExpressions = {"//(*.zip[*])/jcr:content[@jcr:data] =&gt; /zips/$1"}; -&SequencerConfig; sequencerConfig = new &SequencerConfig;(name, desc, classname, - classpath, pathExpressions); -this.sequencingService.addSequencer(sequencerConfig); -</programlisting> - </sect2> - <sect2 id="dna-sequencer-java"> - <title>Java source sequencer</title> - <para> - One of the sequencers that included in JBoss DNA is the <emphasis role="strong">dna-sequencer-java</emphasis> subproject. - This sequencer parses Java source code added to the repository and extracts the basic structure of the classes and enumerations - defined in the code. - This structure includes: the package structures, class declarations, class and member attribute declarations, - class and member method declarations with signature (but not implementation logic), enumerations with each enumeration literal value, - annotations, and JavaDoc information for all of the above. - After extracting this information from the source code, the sequencer then writes this structure into the repository, - where it can be further processed, analyzed, searched, navigated, or referenced. - </para> - <para> - To use this sequencer, simply include the <code>dna-sequencer-java</code> JAR (plus all of the JARs that it is dependent upon) - in your application and configure the Sequencing Service to use this sequencer using something similar to: - </para> - <programlisting> -String name = "Java Sequencer"; -String desc = "Sequences java files to extract the characteristics of the Java source"; -String classname = "org.jboss.dna.sequencer.java.JavaMetadataSequencer"; -String[] classpath = null; // Use the current classpath -String[] pathExpressions = {"//(*.java[*])/jcr:content[@jcr:data] =&gt; /java/$1"}; -&SequencerConfig; sequencerConfig = new &SequencerConfig;(name, desc, classname, - classpath, pathExpressions); -this.sequencingService.addSequencer(sequencerConfig); -</programlisting> - </sect2> - <sect2 id="dna-sequencer-mp3"> - <title>MP3 audio file sequencer</title> - <para> - Another sequencer that is included in JBoss DNA is the <emphasis role="strong">dna-sequencer-mp3</emphasis> sequencer project. - This sequencer processes MP3 audio files added to a repository and extracts the <ulink url="http://www.id3.org/">ID3</ulink> - metadata for the file, including the track's title, author, album name, year, and comment. - After extracting this information from the audio files, the sequencer then writes this structure into the repository, - where it can be further processed, analyzed, searched, navigated, or referenced. - </para> - <para> - To use this sequencer, simply include the <code>dna-sequencer-mp3</code> JAR and the <ulink url="http://www.jthink.net/jaudiotagger/">JAudioTagger</u... - library in your application and configure the Sequencing Service to use this sequencer using something similar to: - </para> - <programlisting> -String name = "MP3 Sequencer"; -String desc = "Sequences MP3 files to extract the ID3 tags of the audio file"; -String classname = "org.jboss.dna.sequencer.mp3.Mp3MetadataSequencer"; -String[] pathExpressions = {"//(*.mp3[*])/jcr:content[@jcr:data] =&gt; /mp3s/$1"}; -&SequencerConfig; sequencerConfig = new &SequencerConfig;(name, desc, classname, - classpath, pathExpressions); -this.sequencingService.addSequencer(sequencerConfig); -</programlisting> - </sect2> - <sect2 id="dna-sequencer-cnd"> - <title>JCR Compact Node Definition (CND) file sequencer</title> - <para> - This sequencer processes JCR Compact Node Definition (CND) files - to extract the node definitions with their property definitions, and inserts these into the repository using JCR standard notation. - </para> - </sect2> - <sect2 id="dna-sequencer-jbpm-jpdl"> - <title>jBPM JPDL file sequencer</title> - <para> - This sequencer is incomplete and is not currently usable. The purpose is to sequence jBPM JPDL files to identify metadata - about processes, their actors, and their dependencies. - </para> - </sect2> - <sect2 id="dna-sequencer-xml"> - <title>XML file sequencer</title> - <para> - This sequencer stores the structure and data of an XML file into the repository. - </para> - </sect2> - </sect1> <sect1 id="custom-sequencers"> <title>Creating custom sequencers</title> 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 2009-06-09 03:30:56 UTC (rev 1003) +++ trunk/docs/reference/src/main/docbook/en-US/content/sequencers/compact_node_types.xml 2009-06-09 04:32:58 UTC (rev 1004) @@ -31,6 +31,7 @@ <chapter id="cnd-sequencer"> <title>Compact Node Type (CND) Sequencer</title> <para> - blah blah + This sequencer processes JCR Compact Node Definition (CND) files + to extract the node definitions with their property definitions, and inserts these into the repository using JCR standard notation. </para> </chapter> \ No newline at end of file Modified: trunk/docs/reference/src/main/docbook/en-US/content/sequencers/image.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/sequencers/image.xml 2009-06-09 03:30:56 UTC (rev 1003) +++ trunk/docs/reference/src/main/docbook/en-US/content/sequencers/image.xml 2009-06-09 04:32:58 UTC (rev 1004) @@ -30,7 +30,79 @@ ]> <chapter id="image-sequencer"> <title>Image Sequencer</title> - <para> - blah blah - </para> + <para> + The &ImageMetadataSequencer; sequencer extracts metadata from JPEG, GIF, BMP, PCX, PNG, IFF, RAS, PBM, PGM, PPM and PSD image files. + This sequencer extracts the file format, image resolution, number of bits per pixel and optionally number of images, comments + and physical resolution, and then writes this information into the repository using the following structure: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis role="strong">image:metadata</emphasis> node of type <code>image:metadata</code> + </para> + </listitem> + <listitem> + <itemizedlist> + <listitem> + <para><emphasis role="strong">jcr:mimeType</emphasis> - optional string property for the mime type of the image</para> + </listitem> + <listitem> + <para><emphasis role="strong">jcr:encoding</emphasis> - optional string property for the encoding of the image</para> + </listitem> + <listitem> + <para><emphasis role="strong">image:formatName</emphasis> - string property for the name of the format</para> + </listitem> + <listitem> + <para><emphasis role="strong">image:width</emphasis> - optional integer property for the image's width in pixels</para> + </listitem> + <listitem> + <para><emphasis role="strong">image:height</emphasis> - optional integer property for the image's height in pixles</para> + </listitem> + <listitem> + <para><emphasis role="strong">image:bitsPerPixel</emphasis> - optional integer property for the number of bits per pixel</para> + </listitem> + <listitem> + <para><emphasis role="strong">image:progressive</emphasis> - optional boolean property specifying whether the image is stored in a progressive + (i.e., interlaced) form</para> + </listitem> + <listitem> + <para><emphasis role="strong">image:numberOfImages</emphasis> - optional integer property for the number of images stored in the file; defaults + to 1</para> + </listitem> + <listitem> + <para><emphasis role="strong">image:physicalWidthDpi</emphasis> - optional integer property for the physical width of the image in dots per inch</para> + </listitem> + <listitem> + <para><emphasis role="strong">image:physicalHeightDpi</emphasis> - optional integer property for the physical height of the image in dots per + inch</para> + </listitem> + <listitem> + <para><emphasis role="strong">image:physicalWidthInches</emphasis> - optional double property for the physical width of the image in inches</para> + </listitem> + <listitem> + <para><emphasis role="strong">image:physicalHeightInches</emphasis> - optional double property for the physical height of the image in inches</para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + <para> + This structure could be extended in the future to add EXIF and IPTC metadata as child nodes. For example, EXIF metadata is + structured as tags in directories, where the directories form something like namespaces, and which are used by different camera + vendors to store custom metadata. This structure could be mapped with each directory (e.g. "EXIF" or "Nikon Makernote" or + "IPTC") as the name of a child node, with the EXIF tags values stored as either properties or child nodes. + </para> + <para> + To use this sequencer, simply include the <code>dna-sequencer-images</code> JAR + in your application and configure the Sequencing Service to use this sequencer using something similar to: + </para> + <programlisting> +String name = "Image Sequencer"; +String desc = "Sequences image files to extract the characteristics of the image"; +String classname = "org.jboss.dna.sequencer.images.ImageMetadataSequencer"; +String[] classpath = null; // Use the current classpath +String[] pathExpressions = {"//(*.(jpg|jpeg|gif|bmp|pcx|png|iff|ras|pbm|pgm|ppm|psd)[*])/jcr:content[@jcr:data] =&gt; /images/$1"}; +&SequencerConfig; sequencerConfig = new &SequencerConfig;(name, desc, classname, + classpath, pathExpressions); +sequencingService.addSequencer(sequencerConfig); +</programlisting> </chapter> \ No newline at end of file Modified: trunk/docs/reference/src/main/docbook/en-US/content/sequencers/java_source.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/sequencers/java_source.xml 2009-06-09 03:30:56 UTC (rev 1003) +++ trunk/docs/reference/src/main/docbook/en-US/content/sequencers/java_source.xml 2009-06-09 04:32:58 UTC (rev 1004) @@ -30,7 +30,28 @@ ]> <chapter id="java-source-sequencer"> <title>Java Source File Sequencer</title> - <para> - blah blah - </para> + <para> + One of the sequencers that included in JBoss DNA is the <emphasis role="strong">dna-sequencer-java</emphasis> subproject. + This sequencer parses Java source code added to the repository and extracts the basic structure of the classes and enumerations + defined in the code. + This structure includes: the package structures, class declarations, class and member attribute declarations, + class and member method declarations with signature (but not implementation logic), enumerations with each enumeration literal value, + annotations, and JavaDoc information for all of the above. + After extracting this information from the source code, the sequencer then writes this structure into the repository, + where it can be further processed, analyzed, searched, navigated, or referenced. + </para> + <para> + To use this sequencer, simply include the <code>dna-sequencer-java</code> JAR (plus all of the JARs that it is dependent upon) + in your application and configure the Sequencing Service to use this sequencer using something similar to: + </para> + <programlisting> +String name = "Java Sequencer"; +String desc = "Sequences java files to extract the characteristics of the Java source"; +String classname = "org.jboss.dna.sequencer.java.JavaMetadataSequencer"; +String[] classpath = null; // Use the current classpath +String[] pathExpressions = {"//(*.java[*])/jcr:content[@jcr:data] =&gt; /java/$1"}; +&SequencerConfig; sequencerConfig = new &SequencerConfig;(name, desc, classname, + classpath, pathExpressions); +this.sequencingService.addSequencer(sequencerConfig); +</programlisting> </chapter> \ No newline at end of file Modified: trunk/docs/reference/src/main/docbook/en-US/content/sequencers/microsoft_office.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/sequencers/microsoft_office.xml 2009-06-09 03:30:56 UTC (rev 1003) +++ trunk/docs/reference/src/main/docbook/en-US/content/sequencers/microsoft_office.xml 2009-06-09 04:32:58 UTC (rev 1004) @@ -30,7 +30,26 @@ ]> <chapter id="msoffice-sequencer"> <title><trademark class='registered'>Microsoft Office</trademark> Document Sequencer</title> - <para> - blah blah - </para> + <para> + This sequencer is included in JBoss DNA and processes Microsoft Office documents, including Word documents, Excel spreadsheets, + and PowerPoint presentations. With documents, the sequencer extracts the internal structure based on Heading styles. + With presentations, the sequencer extracts the slides, titles, text and slide thumbnails. + With spreadsheets, the sequencer extracts the names of the sheets. And, the sequencer extracts for all the files the + general file information, including the name of the author, title, keywords, subject, comments, and various dates. + </para> +<para> + To use this sequencer, simply include the <code>dna-sequencer-msoffice</code> JAR and all of the + <ulink url="http://poi.apache.org/">POI</ulink> JARs + in your application and configure the Sequencing Service to use this sequencer using something similar to: + </para> + <programlisting> +String name = "Microsoft Office Document Sequencer"; +String desc = "Sequences MS Office documents, including spreadsheets and presentations"; +String classname = "org.jboss.dna.sequencer.msoffice.MSOfficeMetadataSequencer"; +String[] classpath = null; // Use the current classpath +String[] pathExpressions = {"//(*.(doc|docx|ppt|pps|xls)[*])/jcr:content[@jcr:data] =&gt; /msoffice/$1"}; +&SequencerConfig; sequencerConfig = new &SequencerConfig;(name, desc, classname, + classpath, pathExpressions); +sequencingService.addSequencer(sequencerConfig); +</programlisting> </chapter> \ No newline at end of file Modified: trunk/docs/reference/src/main/docbook/en-US/content/sequencers/mp3.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/sequencers/mp3.xml 2009-06-09 03:30:56 UTC (rev 1003) +++ trunk/docs/reference/src/main/docbook/en-US/content/sequencers/mp3.xml 2009-06-09 04:32:58 UTC (rev 1004) @@ -30,7 +30,24 @@ ]> <chapter id="mp3-sequencer"> <title>MP3 Sequencer</title> - <para> - blah blah - </para> + <para> + Another sequencer that is included in JBoss DNA is the <emphasis role="strong">dna-sequencer-mp3</emphasis> sequencer project. + This sequencer processes MP3 audio files added to a repository and extracts the <ulink url="http://www.id3.org/">ID3</ulink> + metadata for the file, including the track's title, author, album name, year, and comment. + After extracting this information from the audio files, the sequencer then writes this structure into the repository, + where it can be further processed, analyzed, searched, navigated, or referenced. + </para> + <para> + To use this sequencer, simply include the <code>dna-sequencer-mp3</code> JAR and the <ulink url="http://www.jthink.net/jaudiotagger/">JAudioTagger</u... + library in your application and configure the Sequencing Service to use this sequencer using something similar to: + </para> + <programlisting> + String name = "MP3 Sequencer"; + String desc = "Sequences MP3 files to extract the ID3 tags of the audio file"; + String classname = "org.jboss.dna.sequencer.mp3.Mp3MetadataSequencer"; + String[] pathExpressions = {"//(*.mp3[*])/jcr:content[@jcr:data] =&gt; /mp3s/$1"}; + &SequencerConfig; sequencerConfig = new &SequencerConfig;(name, desc, classname, + classpath, pathExpressions); + this.sequencingService.addSequencer(sequencerConfig); + </programlisting> </chapter> \ No newline at end of file Modified: trunk/docs/reference/src/main/docbook/en-US/content/sequencers/xml.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/sequencers/xml.xml 2009-06-09 03:30:56 UTC (rev 1003) +++ trunk/docs/reference/src/main/docbook/en-US/content/sequencers/xml.xml 2009-06-09 04:32:58 UTC (rev 1004) @@ -31,6 +31,6 @@ <chapter id="xml-sequencer"> <title>XML Document Sequencer</title> <para> - blah blah + This sequencer stores the structure and data of an XML file into the repository. </para> </chapter> \ No newline at end of file Modified: trunk/docs/reference/src/main/docbook/en-US/content/sequencers/zip.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/sequencers/zip.xml 2009-06-09 03:30:56 UTC (rev 1003) +++ trunk/docs/reference/src/main/docbook/en-US/content/sequencers/zip.xml 2009-06-09 04:32:58 UTC (rev 1004) @@ -30,7 +30,21 @@ ]> <chapter id="zip-file-sequencer"> <title>ZIP File Sequencer</title> - <para> - blah blah - </para> + <para> + The ZIP file sequencer is included in JBoss DNA and extracts the files and folders contained in the ZIP archive file, + extracting the files and folders into the repository using JCR's <code>nt:file</code> and <code>nt:folder</code> node types. + </para> + <para> + To use this sequencer, simply include the <code>dna-sequencer-zip</code> JAR + in your application and configure the Sequencing Service to use this sequencer using something similar to: + </para> + <programlisting> +String name = "ZIP Sequencer"; +String desc = "Sequences ZIP archives to extract the files and folders"; +String classname = "org.jboss.dna.sequencer.zip.ZipSequencer"; +String[] pathExpressions = {"//(*.zip[*])/jcr:content[@jcr:data] =&gt; /zips/$1"}; +&SequencerConfig; sequencerConfig = new &SequencerConfig;(name, desc, classname, + classpath, pathExpressions); +this.sequencingService.addSequencer(sequencerConfig); +</programlisting> </chapter> \ No newline at end of file Modified: trunk/docs/reference/src/main/docbook/en-US/custom.dtd =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/custom.dtd 2009-06-09 03:30:56 UTC (rev 1003) +++ trunk/docs/reference/src/main/docbook/en-US/custom.dtd 2009-06-09 04:32:58 UTC (rev 1004) @@ -53,6 +53,9 @@ <!ENTITY Serializable "<ulink url='&Java;java/io/Serializable.html'><interface>Serializable</interface></ulink>"> <!ENTITY Iterator "<ulink url='&Java;java/util/Iterator.html'><interface>Iterator</interface></ulink>"> <!ENTITY Iteratable "<ulink url='&Java;java/util/Iteratable.html'><interface>Iteratable</interface></ulink>"> +<!ENTITY Set "<ulink url='&Java;java/util/Set.html'><interface>Set</interface></ulink>"> +<!ENTITY Map "<ulink url='&Java;java/util/Map.html'><interface>Map</interface></ulink>"> +<!ENTITY List "<ulink url='&Java;java/util/List.html'><interface>List</interface></ulink>"> <!ENTITY BigDecimal "<ulink url='&Java;java/math/BigDecimal.html'><classname>BigDecimal</classname></ulink>"> <!ENTITY Calendar "<ulink url='&Java;java/util/Calendar.html'><classname>Calendar</classname></ulink>"> <!ENTITY Date "<ulink url='&Java;java/util/Date.html'><classname>Date</classname></ulink>">