[dna-commits] DNA SVN: r540 - in trunk: dna-graph/src/main/java/org/jboss/dna/graph/connectors and 10 other directories.

Author: rhauch Date: 2008-09-24 17:49:27 -0400 (Wed, 24 Sep 2008) New Revision: 540 Added: trunk/docs/reference/src/main/docbook/en-US/content/development_tools.xml trunk/docs/reference/src/main/docbook/en-US/content/environment.xml trunk/docs/reference/src/main/docbook/en-US/custom.dtd trunk/docs/reference/src/main/docbook/en-US/images/dna-connectors-0.2.png trunk/docs/reference/src/main/docbook/en-US/images/dna-connectors-future.png trunk/docs/reference/src/main/docbook/en-US/images/dnajcr-and-connector.png trunk/docs/reference/src/main/docbook/xslt/ trunk/docs/reference/src/main/docbook/xslt/eclipse.xslt trunk/docs/reference/src/main/docbook/xslt/pdf.xslt trunk/docs/reference/src/main/docbook/xslt/xhtml-single.xslt trunk/docs/reference/src/main/docbook/xslt/xhtml.xslt Removed: trunk/docs/reference/src/main/docbook/en-US/content/development_environment.xml trunk/docs/reference/src/main/docbook/en-US/content/security.xml Modified: trunk/dna-graph/src/main/java/org/jboss/dna/graph/ExecutionContext.java trunk/dna-graph/src/main/java/org/jboss/dna/graph/ExecutionContexts.java trunk/dna-graph/src/main/java/org/jboss/dna/graph/connectors/BasicExecutionContext.java trunk/dna-repository/src/main/java/org/jboss/dna/repository/RepositoryService.java trunk/dna-repository/src/main/java/org/jboss/dna/repository/sequencers/SequencingService.java trunk/dna-repository/src/test/java/org/jboss/dna/repository/RepositoryServiceTest.java trunk/docs/examples/gettingstarted/repositories/src/main/java/org/jboss/example/dna/repository/RepositoryClient.java trunk/docs/gettingstarted/src/main/docbook/en-US/content/custom_sequencers.xml trunk/docs/gettingstarted/src/main/docbook/en-US/content/future.xml trunk/docs/gettingstarted/src/main/docbook/en-US/content/understanding_dna.xml trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna_for_sequencing.xml trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna_repositories.xml trunk/docs/reference/src/main/docbook/en-US/content/author_group.xml trunk/docs/reference/src/main/docbook/en-US/content/classloaders.xml trunk/docs/reference/src/main/docbook/en-US/content/configuration.xml trunk/docs/reference/src/main/docbook/en-US/content/future.xml trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml trunk/docs/reference/src/main/docbook/en-US/content/jcr.xml trunk/docs/reference/src/main/docbook/en-US/content/legal_notice.xml trunk/docs/reference/src/main/docbook/en-US/content/mimetypes.xml trunk/docs/reference/src/main/docbook/en-US/content/preface.xml trunk/docs/reference/src/main/docbook/en-US/content/repositories.xml trunk/docs/reference/src/main/docbook/en-US/content/sequencing.xml trunk/docs/reference/src/main/docbook/en-US/content/testing.xml trunk/docs/reference/src/main/docbook/en-US/master.xml Log: DNA-71 Document development tools and environment https://jira.jboss.org/jira/browse/DNA-71 Added quite a bit of content to the Reference Guide, and also corrected a few minor things in the code. Modified: trunk/dna-graph/src/main/java/org/jboss/dna/graph/ExecutionContext.java =================================================================== --- trunk/dna-graph/src/main/java/org/jboss/dna/graph/ExecutionContext.java 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/dna-graph/src/main/java/org/jboss/dna/graph/ExecutionContext.java 2008-09-24 21:49:27 UTC (rev 540) @@ -24,6 +24,7 @@ import java.security.AccessControlContext; import javax.security.auth.Subject; import javax.security.auth.login.LoginContext; +import org.jboss.dna.common.component.ClassLoaderFactory; import org.jboss.dna.common.util.Logger; import org.jboss.dna.graph.properties.NamespaceRegistry; import org.jboss.dna.graph.properties.Property; @@ -31,10 +32,16 @@ import org.jboss.dna.graph.properties.ValueFactories; /** + * An ExecutionContext is a representation of the environment or context in which a component or operation is operating. Some + * components require this context to be passed into individual methods, allowing the context to vary with each method invocation. + * Other components require the context to be provided before it's used, and will use that context for all its operations (until + * it is given a different one). + * * @author Randall Hauch * @author John Verhaeg + * @see ExecutionContextFactory */ -public interface ExecutionContext { +public interface ExecutionContext extends ClassLoaderFactory { /** * @return the access control context; may be <code>null</code> Modified: trunk/dna-graph/src/main/java/org/jboss/dna/graph/ExecutionContexts.java =================================================================== --- trunk/dna-graph/src/main/java/org/jboss/dna/graph/ExecutionContexts.java 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/dna-graph/src/main/java/org/jboss/dna/graph/ExecutionContexts.java 2008-09-24 21:49:27 UTC (rev 540) @@ -150,6 +150,15 @@ /** * {@inheritDoc} * + * @see org.jboss.dna.common.component.ClassLoaderFactory#getClassLoader(java.lang.String[]) + */ + public ClassLoader getClassLoader( String... classpath ) { + return this.delegate.getClassLoader(classpath); + } + + /** + * {@inheritDoc} + * * @see org.jboss.dna.graph.ExecutionContext#getAccessControlContext() */ public AccessControlContext getAccessControlContext() { Modified: trunk/dna-graph/src/main/java/org/jboss/dna/graph/connectors/BasicExecutionContext.java =================================================================== --- trunk/dna-graph/src/main/java/org/jboss/dna/graph/connectors/BasicExecutionContext.java 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/dna-graph/src/main/java/org/jboss/dna/graph/connectors/BasicExecutionContext.java 2008-09-24 21:49:27 UTC (rev 540) @@ -25,6 +25,8 @@ import java.security.AccessController; import javax.security.auth.Subject; import javax.security.auth.login.LoginContext; +import org.jboss.dna.common.component.ClassLoaderFactory; +import org.jboss.dna.common.component.StandardClassLoaderFactory; import org.jboss.dna.common.util.CheckArg; import org.jboss.dna.common.util.Logger; import org.jboss.dna.graph.ExecutionContext; @@ -41,6 +43,7 @@ */ public class BasicExecutionContext implements ExecutionContext { + private final ClassLoaderFactory classLoaderFactory; private final LoginContext loginContext; private final AccessControlContext accessControlContext; private final Subject subject; @@ -110,11 +113,21 @@ this.namespaceRegistry = namespaceRegistry; this.valueFactories = valueFactories != null ? valueFactories : new StandardValueFactories(this.namespaceRegistry); this.propertyFactory = propertyFactory != null ? propertyFactory : new BasicPropertyFactory(this.valueFactories); + this.classLoaderFactory = new StandardClassLoaderFactory(); } /** * {@inheritDoc} * + * @see org.jboss.dna.common.component.ClassLoaderFactory#getClassLoader(java.lang.String[]) + */ + public ClassLoader getClassLoader( String... classpath ) { + return this.classLoaderFactory.getClassLoader(classpath); + } + + /** + * {@inheritDoc} + * * @see org.jboss.dna.graph.ExecutionContext#getAccessControlContext() */ public AccessControlContext getAccessControlContext() { Modified: trunk/dna-repository/src/main/java/org/jboss/dna/repository/RepositoryService.java =================================================================== --- trunk/dna-repository/src/main/java/org/jboss/dna/repository/RepositoryService.java 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/dna-repository/src/main/java/org/jboss/dna/repository/RepositoryService.java 2008-09-24 21:49:27 UTC (rev 540) @@ -29,8 +29,6 @@ import net.jcip.annotations.ThreadSafe; import org.jboss.dna.common.collection.Problems; import org.jboss.dna.common.collection.SimpleProblems; -import org.jboss.dna.common.component.ClassLoaderFactory; -import org.jboss.dna.common.component.StandardClassLoaderFactory; import org.jboss.dna.common.util.CheckArg; import org.jboss.dna.common.util.Reflection; import org.jboss.dna.connector.federation.FederationException; @@ -99,7 +97,6 @@ } } - private final ClassLoaderFactory classLoaderFactory; private final ExecutionContext context; private final RepositoryLibrary sources; private final String configurationSourceName; @@ -114,17 +111,12 @@ * @param sources the source manager * @param configurationSourceName the name of the {@link RepositorySource} that is the configuration repository * @param context the execution context in which this service should run - * @param classLoaderFactory the class loader factory used to instantiate {@link RepositorySource} instances; may be null if - * this instance should use a default factory that attempts to load classes first from the - * {@link Thread#getContextClassLoader() thread's current context class loader} and then from the class loader that - * loaded this class. * @throws IllegalArgumentException if the bootstrap source is null or the execution context is null */ public RepositoryService( RepositoryLibrary sources, String configurationSourceName, - ExecutionContext context, - ClassLoaderFactory classLoaderFactory ) { - this(sources, configurationSourceName, null, context, classLoaderFactory); + ExecutionContext context ) { + this(sources, configurationSourceName, null, context); } /** @@ -136,17 +128,12 @@ * @param pathToConfigurationRoot the path of the node in the configuration source repository that should be treated by this * service as the root of the service's configuration; if null, then "/dna:system" is used * @param context the execution context in which this service should run - * @param classLoaderFactory the class loader factory used to instantiate {@link RepositorySource} instances; may be null if - * this instance should use a default factory that attempts to load classes first from the - * {@link Thread#getContextClassLoader() thread's current context class loader} and then from the class loader that - * loaded this class. * @throws IllegalArgumentException if the bootstrap source is null or the execution context is null */ public RepositoryService( RepositoryLibrary sources, String configurationSourceName, Path pathToConfigurationRoot, - ExecutionContext context, - ClassLoaderFactory classLoaderFactory ) { + ExecutionContext context ) { CheckArg.isNotNull(configurationSourceName, "configurationSourceName"); CheckArg.isNotNull(sources, "sources"); CheckArg.isNotNull(context, "context"); @@ -155,7 +142,6 @@ this.pathToConfigurationRoot = pathToConfigurationRoot; this.configurationSourceName = configurationSourceName; this.context = context; - this.classLoaderFactory = classLoaderFactory != null ? classLoaderFactory : new StandardClassLoaderFactory(); } /** @@ -186,13 +172,6 @@ return context; } - /** - * @return classLoaderFactory - */ - public ClassLoaderFactory getClassLoaderFactory() { - return this.classLoaderFactory; - } - public String getJndiName() { // TODO return null; @@ -279,7 +258,7 @@ // Create the instance ... String classname = stringFactory.create(classnameProperty.getValues().next()); String[] classpath = classpathProperty == null ? new String[] {} : stringFactory.create(classpathProperty.getValuesAsArray()); - ClassLoader classLoader = this.classLoaderFactory.getClassLoader(classpath); + ClassLoader classLoader = context.getClassLoader(classpath); RepositorySource source = null; try { Class<?> sourceClass = classLoader.loadClass(classname); Modified: trunk/dna-repository/src/main/java/org/jboss/dna/repository/sequencers/SequencingService.java =================================================================== --- trunk/dna-repository/src/main/java/org/jboss/dna/repository/sequencers/SequencingService.java 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/dna-repository/src/main/java/org/jboss/dna/repository/sequencers/SequencingService.java 2008-09-24 21:49:27 UTC (rev 540) @@ -249,30 +249,6 @@ } /** - * Get the class loader factory that should be used to load sequencers. By default, this service uses a factory that will - * return either the {@link Thread#getContextClassLoader() current thread's context class loader} (if not null) or the class - * loader that loaded this class. - * - * @return the class loader factory; never null - * @see #setClassLoaderFactory(ClassLoaderFactory) - */ - public ClassLoaderFactory getClassLoaderFactory() { - return this.sequencerLibrary.getClassLoaderFactory(); - } - - /** - * Set the Maven Repository that should be used to load the sequencer classes. By default, this service uses a class loader - * factory that will return either the {@link Thread#getContextClassLoader() current thread's context class loader} (if not - * null) or the class loader that loaded this class. - * - * @param classLoaderFactory the class loader factory reference, or null if the default class loader factory should be used. - * @see #getClassLoaderFactory() - */ - public void setClassLoaderFactory( ClassLoaderFactory classLoaderFactory ) { - this.sequencerLibrary.setClassLoaderFactory(classLoaderFactory != null ? classLoaderFactory : DEFAULT_CLASSLOADER_FACTORY); - } - - /** * Add the configuration for a sequencer, or update any existing one that represents the * {@link SequencerConfig#equals(Object) same configuration} * @@ -331,6 +307,7 @@ throw new IllegalStateException(RepositoryI18n.unableToChangeExecutionContextWhileRunning.text()); } this.executionContext = executionContext; + this.sequencerLibrary.setClassLoaderFactory(executionContext); } /** @@ -630,6 +607,15 @@ /** * {@inheritDoc} * + * @see org.jboss.dna.common.component.ClassLoaderFactory#getClassLoader(java.lang.String[]) + */ + public ClassLoader getClassLoader( String... classpath ) { + return delegate.getClassLoader(classpath); + } + + /** + * {@inheritDoc} + * * @see org.jboss.dna.graph.ExecutionContext#getAccessControlContext() */ public AccessControlContext getAccessControlContext() { Modified: trunk/dna-repository/src/test/java/org/jboss/dna/repository/RepositoryServiceTest.java =================================================================== --- trunk/dna-repository/src/test/java/org/jboss/dna/repository/RepositoryServiceTest.java 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/dna-repository/src/test/java/org/jboss/dna/repository/RepositoryServiceTest.java 2008-09-24 21:49:27 UTC (rev 540) @@ -28,13 +28,11 @@ import static org.hamcrest.core.IsSame.sameInstance; import static org.junit.Assert.assertThat; import static org.junit.matchers.JUnitMatchers.hasItems; -import static org.mockito.Mockito.mock; import static org.mockito.Mockito.stub; import static org.mockito.Mockito.times; import static org.mockito.Mockito.verify; import static org.mockito.Mockito.verifyNoMoreInteractions; import java.util.concurrent.TimeUnit; -import org.jboss.dna.common.component.ClassLoaderFactory; import org.jboss.dna.common.util.Logger; import org.jboss.dna.connector.federation.FederationException; import org.jboss.dna.graph.DnaLexicon; @@ -80,7 +78,7 @@ configRepositoryConnection = configRepositorySource.getConnection(); stub(sources.createConnection(configSourceName)).toReturn(configRepositoryConnection); root = context.getValueFactories().getPathFactory().createRootPath(); - service = new RepositoryService(sources, configSourceName, context, null); + service = new RepositoryService(sources, configSourceName, context); } @After @@ -109,19 +107,6 @@ } @Test - public void shouldHaveNonNullClassLoaderFactoryAfterInstantiatingWithNullClassLoaderFactoryReference() { - assertThat(service.getClassLoaderFactory(), is(notNullValue())); - } - - @Test - public void shouldHaveNonNullClassLoaderFactoryAfterInstantiatingWithClassLoaderFactoryReference() { - ClassLoaderFactory classLoaderFactory = mock(ClassLoaderFactory.class); - service = new RepositoryService(sources, configSourceName, context, classLoaderFactory); - assertThat(service.getClassLoaderFactory(), is(notNullValue())); - assertThat(service.getClassLoaderFactory(), is(sameInstance(classLoaderFactory))); - } - - @Test public void shouldHaveNullJndiNameAfterInstantiation() { assertThat(service.getJndiName(), is(nullValue())); } @@ -153,7 +138,7 @@ sources.addSource(configRepositorySource); assertThat(sources.getSources(), hasItems((RepositorySource)configRepositorySource)); assertThat(sources.getSources().size(), is(1)); - service = new RepositoryService(sources, configSourceName, root, context, null); + service = new RepositoryService(sources, configSourceName, root, context); // Set up the configuration repository to contain 3 sources ... final String className = SimpleRepositorySource.class.getName(); Modified: trunk/docs/examples/gettingstarted/repositories/src/main/java/org/jboss/example/dna/repository/RepositoryClient.java =================================================================== --- trunk/docs/examples/gettingstarted/repositories/src/main/java/org/jboss/example/dna/repository/RepositoryClient.java 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/docs/examples/gettingstarted/repositories/src/main/java/org/jboss/example/dna/repository/RepositoryClient.java 2008-09-24 21:49:27 UTC (rev 540) @@ -39,8 +39,6 @@ import javax.security.auth.login.LoginContext; import javax.security.auth.login.LoginException; import net.jcip.annotations.Immutable; -import org.jboss.dna.common.component.ClassLoaderFactory; -import org.jboss.dna.common.component.StandardClassLoaderFactory; import org.jboss.dna.common.text.NoOpEncoder; import org.jboss.dna.common.util.CheckArg; import org.jboss.dna.connector.inmemory.InMemoryRepositorySource; @@ -86,7 +84,6 @@ DNA; } - private ClassLoaderFactory classLoaderFactory; private RepositoryLibrary sources; private ExecutionContextFactory contextFactory; private RepositoryService repositoryService; @@ -131,9 +128,6 @@ public void startRepositories() throws IOException, NamingException { if (repositoryService != null) return; // already started - // Create the class loader factory, which for this example will simply use this class' class loader... - classLoaderFactory = new StandardClassLoaderFactory(); - // Create the factory for execution contexts. contextFactory = new BasicExecutionContextFactory(); @@ -157,7 +151,7 @@ importer.importXml(location + "/configRepository.xml").into(configSource.getName()); // Now instantiate the Repository Service ... - repositoryService = new RepositoryService(sources, configSource.getName(), context, classLoaderFactory); + repositoryService = new RepositoryService(sources, configSource.getName(), context); repositoryService.getAdministrator().start(); // Now import the conten for two of the other in-memory repositories ... Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/custom_sequencers.xml =================================================================== --- trunk/docs/gettingstarted/src/main/docbook/en-US/content/custom_sequencers.xml 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/custom_sequencers.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -25,8 +25,7 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <chapter id="custom_sequencers"> <title>Creating custom sequencers</title> - <para>The current release of JBoss DNA comes with two sequencers: one that extracts metadata from a variety of image file formats, - and another that extracts some of the ID3 metadata from MP3 audio files. However, it's very easy to create your own + <para>The current release of JBoss DNA comes with six 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/gettingstarted/src/main/docbook/en-US/content/future.xml =================================================================== --- trunk/docs/gettingstarted/src/main/docbook/en-US/content/future.xml 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/future.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -31,11 +31,6 @@ <ulink url="http://jira.jboss.org/jira/browse/DNA?report=com.atlassian.jira...;. Or, check out <ulink url="http://jira.jboss.org/jira/secure/IssueNavigator.jspa?reset=tru... for the list of sequencers we've thought of. If you think of one that's not there, please add it to JIRA! </para> - <para>The next release will focus on creating the <link linkend="federation">federation engine</link> and connectors - for several popular and ubiquitous systems. The 0.2 release will likely only federate information in a read-only manner, - but updates will soon follow. Also, during the early part of the next release, the JBoss DNA project will switch to use JDK 6. - Java 5 is being end-of-lifed, so we want to move to a supported JDK. However, a number of JBoss projects and products continue to - require Java 5, so our next release will most likely use JDK 6 with Java 5 compatibility.</para> <para>Other components on our roadmap include a web user interface, a REST-ful server, and a view system that allows domain-specific views of information in the repository. These components are farther out on our roadmap, and at this time have not been targeted to a particular release. If any of these are of interest to you, please <link linkend="preface">get involved</link> Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/understanding_dna.xml =================================================================== --- trunk/docs/gettingstarted/src/main/docbook/en-US/content/understanding_dna.xml 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/understanding_dna.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -332,95 +332,111 @@ registries, file systems, services, etc. The purpose of the federation engine is to allow applications to use the JCR API to access that information as if it were all stored in a single JCR repository, but to really leave the information where it is.</para> - <para>Why not just move the information into a JCR repository? Most likely there are existing applications that rely upon - that information being where it is. If we were to move it, then all those applications would break. Or they'd have to be - changed to use JCR. If the information is being used, the most practical thing is to leave it where it is.</para> - <para> - Then why not just copy the information into a JCR repository? Actually, there are times when it's perfectly reasonable to - make a copy of the data. Perhaps the system managing the existing information cannot handle the additional load of more - clients. Or, perhaps the information doesn't change, or it does change and we want snapshots that don't change. But more - likely, the data - <emphasis>does</emphasis> - change. So if applications are to use the most current information and we make copies of the data, we have to keep the - copies synchronized with the master. That's generally a lot of work. - </para> - <para>The JBoss DNA federation engine lets us leave the information where it is, yet lets client applications use the JCR - API to access all the information without caring where the information really exists. If the underlying information - changes, client applications using JCR observation will be notified of the changes. If a JBoss DNA federated repository is + <para>Why not just copy or move the information into a JCR repository? Moving it is probably pretty difficult, since most + likely there are existing applications that rely upon that information being where it is. All of those applications + 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 creates issues with knowing which information is accurate. + </para> + <para>The JBoss DNA allows lets us leave the information where it is, yet provide access to that information through + the JCR API. The first benefit is that any existing applications that already use that information can keep using it. + Plus, if the underlying information changes, all the client applications see the correct information. JCR clients + even get the benefit of using JCR observation to be notified of the changes. And if a JBoss DNA repository is configured to allow updates, client applications can change the information in the repository and JBoss DNA will propagate those changes down to the original source.</para> <sect2 id="federation_connectors"> <title>Connecting to information sources</title> <para> - The JBoss DNA federation engine will use connectors to interact with different information sources to get at the content - in those systems. Some ideas for connectors include: - <itemizedlist> - <listitem> - <para> - <emphasis role="strong">JCR Repository Connector</emphasis> - - Connect to and interact with other JCR repositories. - </para> - </listitem> - <listitem> - <para> - <emphasis role="strong">File System Connector</emphasis> - - Expose the files and directories on a file system through JCR. - </para> - </listitem> - <listitem> - <para> - <emphasis role="strong">Maven 2 Repository Connector</emphasis> - - Access and expose the contents of a Maven 2 repository (either on the local file system or via HTTP) through - JCR. - </para> - </listitem> - <listitem> - <para> - <emphasis role="strong">JDBC Metadata Connector</emphasis> - - Connect to relational databases via JDBC and expose their schema as content in a repository. - </para> - </listitem> - <listitem> - <para> - <emphasis role="strong">UDDI Connector</emphasis> - - Interact with UDDI registries to integrate their content into a repository. - </para> - </listitem> - <listitem> - <para> - <emphasis role="strong">SVN Connector</emphasis> - - Interact with Subversion software configuration management (SCM) repositories to expose the managed resources - through JCR. Consider using the - <ulink url="http://svnkit.com/">SVNkit</ulink> - (dual license) library for an API into Subversion. - </para> - </listitem> - <listitem> - <para> - <emphasis role="strong">CVS Connector</emphasis> - - Interact with CVS software configuration management (SCM) repositories to expose the managed resources through - JCR. - </para> - </listitem> - <listitem> - <para> - <emphasis role="strong">JDBC Storage Connector</emphasis> - - Store and access information in a relational database. Also useful for persisting information in the federated - repository not stored elsewhere. - </para> - </listitem> - <listitem> - <para> - <emphasis role="strong">Distributed Database Connector</emphasis> - - Store and access information in a - <ulink url="http://www.hypertable.org/">Hypertable</ulink> - or - <ulink url="http://hadoop.apache.org/hbase/">HBase</ulink> - distributed databases. Also useful for persisting information in the federated repository not stored elsewhere. - </para> - </listitem> - </itemizedlist> - </para> + JBoss DNA uses connectors to interact with different information sources to get at the content + in those systems. Some ideas for connectors include:</para> + <itemizedlist> + <listitem> + <para> + <emphasis role="strong">In-Memory Connector</emphasis> + - Creates a transient, in-memory repository. + </para> + </listitem> + <listitem> + <para> + <emphasis role="strong">JBoss Cache Connector</emphasis> + - Uses a JBoss Cache instance as a repository. JBoss Cache is a powerful cache capable of persisting the information + and being clustered for concurrent use by multiple processes. + </para> + </listitem> + <listitem> + <para> + <emphasis role="strong">Federation Connector</emphasis> + - Creates a single repository by accessing and federating the information in multiple other repository sources. + This is a powerful connector that is discussed in more detail in the <link linkend="federated_repositories">next section</link>. + </para> + </listitem> + </itemizedlist> + <para>There are also a number of connectors that are planned:</para> + <itemizedlist> + <listitem> + <para> + <emphasis role="strong">JCR Repository Connector</emphasis> + - Connect to and interact with other JCR repositories. + </para> + </listitem> + <listitem> + <para> + <emphasis role="strong">File System Connector</emphasis> + - Expose the files and directories on a file system through JCR. + </para> + </listitem> + <listitem> + <para> + <emphasis role="strong">Maven 2 Repository Connector</emphasis> + - Access and expose the contents of a Maven 2 repository (either on the local file system or via HTTP) through + JCR. + </para> + </listitem> + <listitem> + <para> + <emphasis role="strong">JDBC Metadata Connector</emphasis> + - Connect to relational databases via JDBC and expose their schema as content in a repository. + </para> + </listitem> + <listitem> + <para> + <emphasis role="strong">UDDI Connector</emphasis> + - Interact with UDDI registries to integrate their content into a repository. + </para> + </listitem> + <listitem> + <para> + <emphasis role="strong">SVN Connector</emphasis> + - Interact with Subversion software configuration management (SCM) repositories to expose the managed resources + through JCR. Consider using the + <ulink url="http://svnkit.com/">SVNkit</ulink> + (dual license) library for an API into Subversion. + </para> + </listitem> + <listitem> + <para> + <emphasis role="strong">CVS Connector</emphasis> + - Interact with CVS software configuration management (SCM) repositories to expose the managed resources through + JCR. + </para> + </listitem> + <listitem> + <para> + <emphasis role="strong">JDBC Storage Connector</emphasis> + - Store and access information in a relational database. Also useful for persisting information in the federated + repository not stored elsewhere. + </para> + </listitem> + <listitem> + <para> + <emphasis role="strong">Distributed Database Connector</emphasis> + - Store and access information in a + <ulink url="http://www.hypertable.org/">Hypertable</ulink> + or + <ulink url="http://hadoop.apache.org/hbase/">HBase</ulink> + distributed databases. Also useful for persisting information in the federated repository not stored elsewhere. + </para> + </listitem> + </itemizedlist> <para> If the connectors allow the information they contribute to be updated, they must provide an <code>XAResource</code> @@ -436,9 +452,9 @@ And of course, sources can be added or removed without having to stop and restart the federated repository. </para> </sect2> - <sect2 id="federation_graph"> - <title>Building the unified graph</title> - <para> The federation engine works by effectively building up a single graph by querying each source and merging or + <sect2 id="federated_repositories"> + <title>Federated repositories</title> + <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 Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna_for_sequencing.xml =================================================================== --- trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna_for_sequencing.xml 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna_for_sequencing.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -51,11 +51,6 @@ and is how JBoss DNA knows about your JCR repositories and how to connect to them. More on this a bit later.</para> </listitem> <listitem> - <para>An optional <emphasis>factory for class loaders</emphasis> used to load sequencers. If no factory is supplied, - the service uses the current thread's context class loader (or if that is null, the class loader that loaded the - sequencing service class).</para> - </listitem> - <listitem> <para>An <code>java.util.concurrent.ExecutorService</code> used to execute the sequencing activites. If none is supplied, a new single-threaded executor is created by calling <code>Executors.newSingleThreadExecutor()</code>. (This can easily be changed by subclassing and overriding the <code>SequencerService.createDefaultExecutorService()</code> method.)</para> @@ -84,14 +79,14 @@ <para>Here's an example of how to instantiate and configure the SequencingService:</para> <programlisting role="JAVA"><![CDATA[ SimpleSessionFactory sessionFactory = new SimpleSessionFactory(); -sessionFactory.registerRepository("Main Repository", this.repository); +sessionFactory.registerRepository("Repository", this.repository); Credentials credentials = new SimpleCredentials("jsmith", "secret".toCharArray()); -sessionFactory.registerCredentials("Main Repository/Workspace1", credentials); -ExecutionContext executionContext = new SimpleExecutionContext(sessionFactory); +sessionFactory.registerCredentials("Repository/Workspace1", credentials); +JcrExecutionContext context = new BasicJcrExecutionContext(sessionFactory,"Repository/Workspace1"); // Create the sequencing service, passing in the execution context ... SequencingService sequencingService = new SequencingService(); -sequencingService.setExecutionContext(executionContext); +sequencingService.setExecutionContext(context); ]]></programlisting> <para>After the sequencing service is created and configured, it must be started. The SequencingService has an <emphasis>administration object</emphasis> (that is an instance of <code>ServiceAdministrator</code>) @@ -117,8 +112,8 @@ classpath, pathExpressions); sequencingService.addSequencer(imageSequencerConfig); -name = "Mp3 Sequencer"; -desc = "Sequences mp3 files to extract the id3 tags of the audio file"; +name = "MP3 Sequencer"; +desc = "Sequences MP3 files to extract the ID3 tags from the audio file"; classname = "org.jboss.dna.sequencer.mp3.Mp3MetadataSequencer"; pathExpressions = {"//(*.mp3[*])/jcr:content[@jcr:data] =&gt; /mp3s/$1"}; SequencerConfig mp3SequencerConfig = new SequencerConfig(name, desc, classname, @@ -134,7 +129,7 @@ this.sequencingService.addSequencer(javaSequencerConfig); ]]></programlisting> <para>Each configuration defines several things, including the name, description, and sequencer implementation class. - The configuration also defines the classpath information, which can be passed to the class loader factory to get + The configuration also defines the classpath information, which can be passed to the <code>ExecutionContext</code> to get a Java classloader with which the sequencer class can be loaded. (If no classpath information is provided, as is done in the code above, the application class loader is used.) The configuration also specifies the path expressions that identify the nodes that should be sequenced with the sequencer and where to store the output generated by the sequencer. Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna_repositories.xml =================================================================== --- trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna_repositories.xml 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna_repositories.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -64,7 +64,7 @@ <sect1 id="repository_service"> <title>Configuring the Repository Service</title> <para>The JBoss DNA <emphasis>repository service</emphasis> is the component that manages the <emphasis>repositories</emphasis> - and connections to them. The service reads it's configuration from a <code>RepositorySource</code> instance (i.e., the + and connections to them. The service reads its configuration from a <code>RepositorySource</code> instance (i.e., the "configuration repository") and automatically sets up the repositories given the <code>RepositorySource</code> instances found in the configuration repository.</para> <note> @@ -77,15 +77,10 @@ <para>To set up the repository service, we need to first set up a few other objects: <itemizedlist> <listitem> - <para>A <emphasis>factory for class loaders</emphasis> used to load the classes that make up the connectors. - If no factory is supplied, the service uses the current thread's context class loader (or if that is null, - the class loader that loaded the <code>RepositoryService</code> class).</para> - </listitem> - <listitem> <para>A <emphasis>factory for execution contexts</emphasis>. Execution contexts define the context (or environment) in which the service runs and in which operations against repositories are performed. <code>ExecutionContext</code> instances can be created using JAAS application contexts, meaning that they contain the information about the subject - that the software represents. Execution contexts also provides access to the all of the factories and utilities + that the software represents. Execution contexts also provide access to the all of the factories and utilities used throughout the services and components, and it is through this mechanism that you can inject your own behavior. For example, if your application already had a notion of namespaces, you could override the execution context's <code>NamespaceRegistry</code> to use the namespaces defined in your application.</para> @@ -104,15 +99,12 @@ </itemizedlist> With these components in place, we can then instantiate the <code>RepositoryService</code> and start it (using its <code>ServiceAdministrator</code>). During startup, the service reads the configuration repository and loads any - defined <code>RepositorySource</code> instances into the repository library, using the class loader factory to obtain - class loaders that it can use to load the actual <code>RepositorySource</code> implementation classes. + defined <code>RepositorySource</code> instances into the repository library, using the class loader factory + (available in the <code>ExecutionContext</code>) to obtain. </para> <para>Here's sample code that shows how to set up and start the repository service. You can see something similar in the example application in the <code>startRepositories()</code> method of the <code>org.jboss.example.dna.repository.RepositoryClient</code> class.</para> <programlisting role="JAVA"><![CDATA[ - // Create the class loader factory, which for this example will simply use this class' class loader... - ClassLoaderFactory classLoaderFactory = new StandardClassLoaderFactory(); - // Create the factory for execution contexts. ExecutionContextFactory contextFactory = new BasicExecutionContextFactory(); @@ -130,9 +122,8 @@ sources.addSource(configSource); // Now instantiate the Repository Service ... - RepositoryService repositoryService = new RepositoryService(sources, configSource.getName(), - context, classLoaderFactory); - repositoryService.getAdministrator().start(); + RepositoryService service = new RepositoryService(sources, configSource.getName(), context); + service.getAdministrator().start(); ]]></programlisting> <para>After startup completes, the repositories are ready to be used. The client application obtains the list of repositories and presents them to the user. When the user selects one, the client application starts navigating that repository Modified: trunk/docs/reference/src/main/docbook/en-US/content/author_group.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/author_group.xml 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/docs/reference/src/main/docbook/en-US/content/author_group.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -22,7 +22,10 @@ ~ 51 Franklin Street, Fifth Floor ~ Boston, MA 02110-1301 USA --> -<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../custom.dtd"> +%CustomDTD; +]> <authorgroup> <corpauthor>Randall M. Hauch</corpauthor> </authorgroup> \ No newline at end of file Modified: trunk/docs/reference/src/main/docbook/en-US/content/classloaders.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/classloaders.xml 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/docs/reference/src/main/docbook/en-US/content/classloaders.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -22,12 +22,89 @@ ~ 51 Franklin Street, Fifth Floor ~ Boston, MA 02110-1301 USA --> -<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../custom.dtd"> +%CustomDTD; +]> <chapter id="classloaders"> <title>Class loaders</title> - <para></para> + <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 all of the "interesting" components + are extensions that plug into and are used by different parts of the core. The core doesn't really care what + the extensions do or what external libraries they require, as long as the extension fulfills its end of the + extension contract. + </para> + <para> + This means that you only need the core modules of JBoss DNA on the application classpath, while the extensions + do not have to be on the application classpath. And because the core modules of JBoss DNA have few dependencies, + the risk of JBoss DNA libraries conflicting with the application's are lower. Extensions, on the other hand, + will likely have a lot of unique dependencies. By separating the core of JBoss DNA from the class loaders used + to load the extensions, your application is isolated from the extensions and their dependencies. Of course, + you can put all the JARs on the application classpath, too. (This is what the examples in the &GettingStarted; document do.) + </para> + <para> + This design also allows you to select only those extensions that are interesting and useful for your application. + Not every application needs all of the JBoss DNA functionality. + Some applications may only need JBoss DNA sequencing, and specifically just a few types of sequencers. + Other applications may not need sequencing but do want to use JBoss DNA federation capabilities. + </para> + <para> + Finally, the use of these formal extensions also makes it easier for you to write your own customized extensions. + You may have proprietary file formats that you want to sequence. Or, you may have a non-JCR repository system that you + want to access via JCR and maybe even federate with information from other sources. Since extensions do + only one thing (e.g., be a sequencer, or a connector, etc.), its easier to develop those customizations. + </para> + <sect1 id="dna-classloader-factory"> + <title>Class loader factory</title> + <para> + JBoss DNA loads all of the extension classes using class loaders returned by a <emphasis>class loader factory</emphasis>. + Each time JBoss DNA wants to load a class, it needs the name of the class and an optional "class loader name". + The meaning of the names is dependent upon the implementation of the class loader factory. For example, the + <link linkend="dna-maven-classloader">Maven class loader factory</link> expects the names to be + <ulink url="http://maven.apache.org/pom.html#Maven_Coordinates">Maven coordinates</ulink>. Either way, + the class loader factory implementation uses the name to create and return a &ClassLoader; + instance that can be used to load the class. Of course, if no name is provided, then a JBoss DNA service + just uses its class loader to load the class. (This is why putting all the extension jars on the classpath works.) + </para> + <para> + The class loader factory interface is pretty simple: + </para> + <programlisting> +public interface &ClassLoaderFactory; { + + /** + * Get a class loader given the supplied classpath. The meaning of the classpath is implementation-dependent. + * @param classpath the classpath to use + * @return the class loader; may not be null + */ + &ClassLoader; getClassLoader( String... classpath ); +} +</programlisting> + <para>In the <link linkend="environment">next chapter</link> we'll describe an &ExecutionContext; interface that is + supplied to each of the JBoss DNA core services. This context interface actually extends the &ClassLoaderFactory; + interface, so setting up an &ExecutionContext; implicitly sets up the class loader factory.</para> + </sect1> + <sect1 id="dna-standard-classloader"> + <title>Standard class loader factory</title> + <para>JBoss DNA includes and uses as a default a standard class loader factory that just loads the classes using the Thread's current context + class loader (if there is one), or a delegate class loader that defaults to the class loader that loaded + the &StandardClassLoaderFactory; class. The class ignores any class loader names that are supplied. + </para> + </sect1> <sect1 id="dna-maven-classloader"> - <title>Maven Repository class loader</title> - <para></para> + <title>Maven Repository class loader factory</title> + <para> + The <code>dna-classloader-maven</code> project has a class loader factory implementation that parses the names into + <ulink url="http://maven.apache.org/pom.html#Maven_Coordinates">Maven coordinates</ulink>, then uses those coordinates + to look up artifacts in a Maven 2 repository. The artifact's POM file is used to determine the dependencies, + which is done transitively to obtain the complete dependency graph. The resulting class loader has access + to these artifacts in dependency order. + </para> + <para> + This class loader is also able to use a JCR repository that contains the equivalent contents of a Maven repository. + However, JBoss DNA doesn't currently have any tooling to help populate that repository, so this component may be + of limited use right now. + </para> </sect1> </chapter> Modified: trunk/docs/reference/src/main/docbook/en-US/content/configuration.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/configuration.xml 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/docs/reference/src/main/docbook/en-US/content/configuration.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -22,13 +22,17 @@ ~ 51 Franklin Street, Fifth Floor ~ Boston, MA 02110-1301 USA --> -<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../custom.dtd"> +%CustomDTD; +]> <chapter id="configuration"> <title>Configuration</title> - <para> - Discuss how to configure JBoss DNA and how configuration repositories are used to bootstrap the various services and - components. Describe how the next release will focus on making this easier and will detail configuration using the - <ulink url="http://www.jboss.org/jbossmc/">JBoss Microcontainer</ulink> - . - </para> + <para> + Configuring JBoss DNA services is a bit more manual than is ideal. JBoss DNA currently consists of classes that uses dependency + injection to allow a great deal of flexibility in how it can be configured and customized. But this flexibility + makes it more difficult for you to configure. We understand this, and will soon provide a much easier way to set up + and manage JBoss DNA. Current plans are to use the <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink> + along with a configuration repository. + </para> </chapter> Deleted: trunk/docs/reference/src/main/docbook/en-US/content/development_environment.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/development_environment.xml 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/docs/reference/src/main/docbook/en-US/content/development_environment.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -1,294 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- - ~ JBoss, Home of Professional Open Source. - ~ - ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as - ~ indicated by the @author tags or express copyright attribution - ~ statements applied by the authors. All third-party contributions are - ~ distributed under license by Red Hat Middleware LLC. - ~ - ~ This copyrighted material is made available to anyone wishing to use, modify, - ~ copy, or redistribute it subject to the terms and conditions of the GNU - ~ Lesser General Public License, as published by the Free Software Foundation. - ~ - ~ This program is distributed in the hope that it will be useful, - ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY - ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License - ~ for more details. - ~ - ~ You should have received a copy of the GNU Lesser General Public License - ~ along with this distribution; if not, write to: - ~ Free Software Foundation, Inc. - ~ 51 Franklin Street, Fifth Floor - ~ Boston, MA 02110-1301 USA - --> -<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="development-environment"> - <title>Developer environment and tooling</title> - <para> - The JBoss DNA project uses <link linkend="maven">Maven</link> as its primary build tool, <link linkend="svn">Subversion</link> - for its source code repository, <link linkend="jira">JIRA</link> for the issue management and bug tracking system, - and <link linkend="hudson">Hudson</link> for the continuous integration system. We do not stipulate a specific integrated - development environment (IDE), although most of us use <link linkend="eclipse">Eclipse</link> and rely upon the code formatting - and compile preferences to ensure no warnings or errors. - </para> - <para> - The rest of this chapter talks in more detail about these different tools and how to set them up. - </para> - <sect1 id="jdk"> - <title>JDK</title> - <para> - Currently, JBoss DNA is developed and built using <ulink url="http://java.sun.com/javase/downloads/index_jdk5.jsp">JDK 5</ulink>, - so if you're a contributor, you should have that installed and should use it before committing any changes. Note that you - should be able to use the <ulink url="http://java.sun.com/javase/downloads/index.jsp">latest JDK</ulink> (which is currently - JDK 6). - </para> - <para> - 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 in the coming months. - </para> - <para> - When installing, simply follow the procedure for your particular platform. On most platforms, this should set the - <code>JAVA_HOME</code> environment variable. But if you run into any problems, first check that this environment - variable was set to the correct location, and then check that you're running the version you expect by running - the following command: - </para> - <programlisting role="XML"><![CDATA[ java -version ]]></programlisting> - <para> - If you don't see the correct version, double-check your installation. - </para> - </sect1> - <sect1 id="svn"> - <title>Subversion</title> - <para>JBoss DNA uses Subversion as its source code management system, and specifically the instance at - <ulink url="http://www.jboss.org">JBoss.org</ulink>. Although you can view the - <ulink url="http://anonsvn.jboss.org/repos/dna/trunk/">trunk</ul... of the Subversion repository - (or using <ulink url="http://fisheye.jboss.org/browse/DNA/trunk">FishEye</...>) through your browser, - it 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 - particular platform. - </para> - <para> - Here are some useful URLs for the JBoss DNA Subversion: - </para> - <table frame='all'> - <title>SVN URLs for JBoss DNA</title> - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth="1*"/> - <colspec colname='c2' colwidth="1*"/> - <thead> - <row> - <entry>Repository</entry> - <entry>URL</entry> - </row> - </thead> - <tbody> - <row> - <entry>Anonymous Access URL</entry> - <entry><ulink url="http://anonsvn.jboss.org/repos/dna/trunk">http://anonsv... - </row> - <row> - <entry>Secure Developer Access URL</entry> - <entry><ulink url="https://svn.jboss.org/repos/dna/trunk/">https://svn.jbo... - </row> - <row> - <entry>FishEye Code Browser</entry> - <entry><ulink url="http://fisheye.jboss.org/browse/DNA/trunk">http://fishe... - </row> - </tbody> - </tgroup> - </table> - </sect1> - <sect1 id="maven"> - <title>Maven</title> - <para>JBoss DNA uses Maven 2 for its build system, as is this example. Using Maven 2 has several advantages, including - the ability to manage dependencies. If a library is needed, Maven automatically finds and downloads that library, plus - everything that library needs. This means that it's very easy to build the examples - or even create a maven project that - depends on the JBoss DNA JARs.</para> - <para> - To use Maven with JBoss DNA, you'll need to have <link linkend="jdk">JDK 5 or 6</link> and Maven 2.0.9 (or higher).</para> - <para> - Maven can be downloaded from <ulink url="http://maven.apache.org/">http://maven.apache.org/</...;, and is installed by unzipping the - <code>maven-2.0.7-bin.zip</code> file to a convenient location on your local disk. Simply add <code>$MAVEN_HOME/bin</code> - to your path and add the following profile to your <code>~/.m2/settings.xml</code> file: - </para> - <programlisting role="XML"><![CDATA[ -<settings> - <profiles> - <profile> - <id>jboss.repository</id> - <activation> - <property> - <name>!jboss.repository.off</name> - </property> - </activation> - <repositories> - <repository> - <id>snapshots.jboss.org</id> - <url>http://snapshots.jboss.org/maven2</url> - <snapshots> - <enabled>true</enabled> - </snapshots> - </repository> - <repository> - <id>repository.jboss.org</id> - <url>http://repository.jboss.org/maven2</url> - <snapshots> - <enabled>false</enabled> - </snapshots> - </repository> - </repositories> - <pluginRepositories> - <pluginRepository> - <id>repository.jboss.org</id> - <url>http://repository.jboss.org/maven2</url> - <snapshots> - <enabled>false</enabled> - </snapshots> - </pluginRepository> - <pluginRepository> - <id>snapshots.jboss.org</id> - <url>http://snapshots.jboss.org/maven2</url> - <snapshots> - <enabled>true</enabled> - </snapshots> - </pluginRepository> - </pluginRepositories> - </profile> - </profiles> -</settings> -]]></programlisting> - <para>This profile informs Maven of the two JBoss repositories (<ulink url="http://repository.jboss.org/maven2">snapshots</ulink... - and <ulink url="http://snapshots.jboss.org/maven2">releases</ulink>) that contain all of the JARs for JBoss DNA and all dependent libraries. - </para> - <note> - <para> - It is a policy of the project that the <emphasis>source code and JARs</emphasis> for <emphasis>all</emphasis> dependencies - <emphasis>must</emphasis> be loaded into the JBoss repository. This is so that the project can always be built - and that all source code is always available. - </para> - <para> - For more information about the JBoss Maven repository, see the <ulink url="http://wiki.jboss.org/wiki/Maven">JBoss.org Wiki</ulink>. - </para> - </note> - <para> - There are just a few commands that are useful for building JBoss DNA (and it's <link linkend="modules">subprojects</link>). - Usually, these are issued while at the top level of the code (usually just below <code>trunk/</code>), although issuing - them inside a subproject just applies to that subproject. - </para> - <table frame='all'> - <title>Useful Maven commands</title> - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth="1*"/> - <colspec colname='c2' colwidth="1*"/> - <thead> - <row> - <entry>Command</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry><code>mvn clean</code></entry> - <entry>Clean up all built artifacts (e.g., the <code>target/</code> directory in each project)</entry> - </row> - <row> - <entry><code>mvn clean install</code></entry> - <entry>Clean up all built artifacts, then compile, run the unit tests, and install the resulting JAR artifact(s) - into your local Maven repository (e.g, usually <code>~/.m2/repository</code>). - </entry> - </row> - </tbody> - </tgroup> - </table> - </sect1> - <sect1 id="hudson"> - <title>Continuous integration with Hudson</title> - <para>JBoss DNA's continuous integration is done with several Hudson jobs on <ulink url="http://www.jboss.org">JBoss.org</ulink>. - These jobs run periodically and basically run the Maven build process. Any build failures or test failures are reported, - as are basic statistics and history for each job. - </para> - <table frame='all'> - <title>Continuous integration jobs</title> - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth="1*"/> - <colspec colname='c2' colwidth="1*"/> - <thead> - <row> - <entry>Job</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry><ulink url="http://hudson.jboss.org/hudson/job/DNA%20continuous%20on%20JDK1... on JDK 5</ulink></entry> - <entry>Continuous build that runs after changes are committed to SVN. SVN is polled every 15 minutes.</entry> - </row> - <row> - <entry><ulink url="http://hudson.jboss.org/hudson/job/DNA%20nightly%20integration%... on JDK 5</ulink></entry> - <entry>Build that runs every night (about 2 a.m. EDT), regardless of whether changes have been committed to SVN - since the previous night.</entry> - </row> - </tbody> - </tgroup> - </table> - </sect1> - <sect1 id="eclipse"> - <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"), - available from <ulink url="http://www.eclipse.org/">Eclipse.org</ulink>;. Simply follow the instructions for your platform. - </para> - <para> - After Eclipse is installed, create a new workspace. Before importing the JBoss DNA projects, import (via "File->Import->Preferences") - the subset of the Eclipse preferences by importing the <code>eclipse-preferences.epf</code> file (located under <code>trunk</code>). - Then, open the Eclipse preferences and open the "Java->Code Style-> Formatter" preference page, and press the "Import" button and - choose the <code>eclipse-code-formatter-profile.xml</code> file (located under <code>trunk</code>). This will load the code - formatting preferences for the JBoss DNA project. - </para> - <para> - Then install Eclipse plugins for SVN and Maven. (Remember, you will have to restart Eclipse after installing them.) - We use the following plugins: - </para> - <table frame='all'> - <title>Continuous integration jobs</title> - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth="1*"/> - <colspec colname='c2' colwidth="1*"/> - <thead> - <row> - <entry>Eclipse Plugin Site</entry> - <entry>Update Site URL</entry> - </row> - </thead> - <tbody> - <row> - <entry>Subversive SVN Client</entry> - <entry> - <ulink url="http://www.polarion.org/projects/subversive/download/eclipse/2.... - <ulink url="http://www.polarion.org/projects/subversive/download/integratio... - </entry> - </row> - <row> - <entry>Maven Integration for Eclipse</entry> - <entry><ulink url="http://m2eclipse.sonatype.org/update/">http://m2eclipse... - </row> - </tbody> - </tgroup> - </table> - <para> - After you check out the JBoss DNA codebase, you can import the JBoss DNA Maven projects into Eclipse as Eclipse projects. - To do this, go to "File->Import->Existing Projects", navigate to the <code>trunk/</code> folder in the import wizard, - and then check each of the <link linkend="modules">subprojects</link> that you want to have in your workspace. - </para> - </sect1> -</chapter> Copied: trunk/docs/reference/src/main/docbook/en-US/content/development_tools.xml (from rev 539, trunk/docs/reference/src/main/docbook/en-US/content/development_environment.xml) =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/development_tools.xml (rev 0) +++ trunk/docs/reference/src/main/docbook/en-US/content/development_tools.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -0,0 +1,297 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ~ JBoss, Home of Professional Open Source. + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program is distributed in the hope that it will be useful, + ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License + ~ for more details. + ~ + ~ You should have received a copy of the GNU Lesser General Public License + ~ along with this distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../custom.dtd"> +%CustomDTD; +]> +<chapter id="development-tools"> + <title>Developer tools</title> + <para> + The JBoss DNA project uses <link linkend="maven">Maven</link> as its primary build tool, <link linkend="svn">Subversion</link> + for its source code repository, <link linkend="jira">JIRA</link> for the issue management and bug tracking system, + and <link linkend="hudson">Hudson</link> for the continuous integration system. We do not stipulate a specific integrated + development environment (IDE), although most of us use <link linkend="eclipse">Eclipse</link> and rely upon the code formatting + and compile preferences to ensure no warnings or errors. + </para> + <para> + The rest of this chapter talks in more detail about these different tools and how to set them up. + </para> + <sect1 id="jdk"> + <title>JDK</title> + <para> + Currently, JBoss DNA is developed and built using <ulink url="http://java.sun.com/javase/downloads/index_jdk5.jsp">JDK 5</ulink>, + so if you're a contributor, you should have that installed and should use it before committing any changes. Note that you + should be able to use the <ulink url="http://java.sun.com/javase/downloads/index.jsp">latest JDK</ulink> (which is currently + JDK 6). + </para> + <para> + 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 in the coming months. + </para> + <para> + When installing, simply follow the procedure for your particular platform. On most platforms, this should set the + <code>JAVA_HOME</code> environment variable. But if you run into any problems, first check that this environment + variable was set to the correct location, and then check that you're running the version you expect by running + the following command: + </para> + <programlisting role="XML"><![CDATA[ java -version ]]></programlisting> + <para> + If you don't see the correct version, double-check your installation. + </para> + </sect1> + <sect1 id="svn"> + <title>Subversion</title> + <para>JBoss DNA uses Subversion as its source code management system, and specifically the instance at + <ulink url="http://www.jboss.org">JBoss.org</ulink>. Although you can view the + <ulink url="&Subversion;trunk/">trunk</ulink> of the Subversion repository + (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 + 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 + particular platform. + </para> + <para> + Here are some useful URLs for the JBoss DNA Subversion: + </para> + <table frame='all'> + <title>SVN URLs for JBoss DNA</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*"/> + <colspec colname='c2' colwidth="1*"/> + <thead> + <row> + <entry>Repository</entry> + <entry>URL</entry> + </row> + </thead> + <tbody> + <row> + <entry>Anonymous Access URL</entry> + <entry><ulink url="&Subversion;trunk/">&Subversion;trunk/</ulink></entry> + </row> + <row> + <entry>Secure Developer Access URL</entry> + <entry><ulink url="&Fisheye;trunk/">&Fisheye;trunk/</ulink></entry> + </row> + <row> + <entry>FishEye Code Browser</entry> + <entry><ulink url="&SecureSubversion;trunk/">&SecureSubversion;trunk/</ulink></entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> + <sect1 id="maven"> + <title>Maven</title> + <para>JBoss DNA uses Maven 2 for its build system, as is this example. Using Maven 2 has several advantages, including + the ability to manage dependencies. If a library is needed, Maven automatically finds and downloads that library, plus + everything that library needs. This means that it's very easy to build the examples - or even create a maven project that + depends on the JBoss DNA JARs.</para> + <para> + To use Maven with JBoss DNA, you'll need to have <link linkend="jdk">JDK 5 or 6</link> and Maven 2.0.9 (or higher).</para> + <para> + Maven can be downloaded from <ulink url="http://maven.apache.org/">http://maven.apache.org/</...;, and is installed by unzipping the + <code>maven-2.0.7-bin.zip</code> file to a convenient location on your local disk. Simply add <code>$MAVEN_HOME/bin</code> + to your path and add the following profile to your <code>~/.m2/settings.xml</code> file: + </para> + <programlisting role="XML"><![CDATA[ +<settings> + <profiles> + <profile> + <id>jboss.repository</id> + <activation> + <property> + <name>!jboss.repository.off</name> + </property> + </activation> + <repositories> + <repository> + <id>snapshots.jboss.org</id> + <url>http://snapshots.jboss.org/maven2</url> + <snapshots> + <enabled>true</enabled> + </snapshots> + </repository> + <repository> + <id>repository.jboss.org</id> + <url>http://repository.jboss.org/maven2</url> + <snapshots> + <enabled>false</enabled> + </snapshots> + </repository> + </repositories> + <pluginRepositories> + <pluginRepository> + <id>repository.jboss.org</id> + <url>http://repository.jboss.org/maven2</url> + <snapshots> + <enabled>false</enabled> + </snapshots> + </pluginRepository> + <pluginRepository> + <id>snapshots.jboss.org</id> + <url>http://snapshots.jboss.org/maven2</url> + <snapshots> + <enabled>true</enabled> + </snapshots> + </pluginRepository> + </pluginRepositories> + </profile> + </profiles> +</settings> +]]></programlisting> + <para>This profile informs Maven of the two JBoss repositories (<ulink url="http://repository.jboss.org/maven2">snapshots</ulink... + and <ulink url="http://snapshots.jboss.org/maven2">releases</ulink>) that contain all of the JARs for JBoss DNA and all dependent libraries. + </para> + <note> + <para> + It is a policy of the project that the <emphasis>source code and JARs</emphasis> for <emphasis>all</emphasis> dependencies + <emphasis>must</emphasis> be loaded into the JBoss repository. This is so that the project can always be built + and that all source code is always available. + </para> + <para> + For more information about the JBoss Maven repository, see the <ulink url="http://wiki.jboss.org/wiki/Maven">JBoss.org Wiki</ulink>. + </para> + </note> + <para> + There are just a few commands that are useful for building JBoss DNA (and it's <link linkend="modules">subprojects</link>). + Usually, these are issued while at the top level of the code (usually just below <code>trunk/</code>), although issuing + them inside a subproject just applies to that subproject. + </para> + <table frame='all'> + <title>Useful Maven commands</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*"/> + <colspec colname='c2' colwidth="1*"/> + <thead> + <row> + <entry>Command</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><code>mvn clean</code></entry> + <entry>Clean up all built artifacts (e.g., the <code>target/</code> directory in each project)</entry> + </row> + <row> + <entry><code>mvn clean install</code></entry> + <entry>Clean up all built artifacts, then compile, run the unit tests, and install the resulting JAR artifact(s) + into your local Maven repository (e.g, usually <code>~/.m2/repository</code>). + </entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> + <sect1 id="hudson"> + <title>Continuous integration with Hudson</title> + <para>JBoss DNA's continuous integration is done with several Hudson jobs on <ulink url="http://www.jboss.org">JBoss.org</ulink>. + These jobs run periodically and basically run the Maven build process. Any build failures or test failures are reported, + as are basic statistics and history for each job. + </para> + <table frame='all'> + <title>Continuous integration jobs</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*"/> + <colspec colname='c2' colwidth="1*"/> + <thead> + <row> + <entry>Job</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><ulink url="http://hudson.jboss.org/hudson/job/DNA%20continuous%20on%20JDK1... on JDK 5</ulink></entry> + <entry>Continuous build that runs after changes are committed to SVN. SVN is polled every 15 minutes.</entry> + </row> + <row> + <entry><ulink url="http://hudson.jboss.org/hudson/job/DNA%20nightly%20integration%... on JDK 5</ulink></entry> + <entry>Build that runs every night (about 2 a.m. EDT), regardless of whether changes have been committed to SVN + since the previous night.</entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> + <sect1 id="eclipse"> + <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"), + available from <ulink url="http://www.eclipse.org/">Eclipse.org</ulink>;. Simply follow the instructions for your platform. + </para> + <para> + After Eclipse is installed, create a new workspace. Before importing the JBoss DNA projects, import (via "File->Import->Preferences") + the subset of the Eclipse preferences by importing the <code>eclipse-preferences.epf</code> file (located under <code>trunk</code>). + Then, open the Eclipse preferences and open the "Java->Code Style-> Formatter" preference page, and press the "Import" button and + choose the <code>eclipse-code-formatter-profile.xml</code> file (located under <code>trunk</code>). This will load the code + formatting preferences for the JBoss DNA project. + </para> + <para> + Then install Eclipse plugins for SVN and Maven. (Remember, you will have to restart Eclipse after installing them.) + We use the following plugins: + </para> + <table frame='all'> + <title>Continuous integration jobs</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*"/> + <colspec colname='c2' colwidth="1*"/> + <thead> + <row> + <entry>Eclipse Plugins</entry> + <entry>Update Site URLs</entry> + </row> + </thead> + <tbody> + <row> + <entry>Subversive SVN Client</entry> + <entry> + <ulink url="http://www.polarion.org/projects/subversive/download/eclipse/2.... + <ulink url="http://www.polarion.org/projects/subversive/download/integratio... + </entry> + </row> + <row> + <entry>Maven Integration for Eclipse</entry> + <entry><ulink url="http://m2eclipse.sonatype.org/update/">http://m2eclipse... + </row> + </tbody> + </tgroup> + </table> + <para> + After you check out the JBoss DNA codebase, you can import the JBoss DNA Maven projects into Eclipse as Eclipse projects. + To do this, go to "File->Import->Existing Projects", navigate to the <code>trunk/</code> folder in the import wizard, + and then check each of the <link linkend="modules">subprojects</link> that you want to have in your workspace. + </para> + </sect1> +</chapter> Added: trunk/docs/reference/src/main/docbook/en-US/content/environment.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/environment.xml (rev 0) +++ trunk/docs/reference/src/main/docbook/en-US/content/environment.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -0,0 +1,233 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ~ JBoss, Home of Professional Open Source. + ~ + ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ indicated by the @author tags or express copyright attribution + ~ statements applied by the authors. All third-party contributions are + ~ distributed under license by Red Hat Middleware LLC. + ~ + ~ This copyrighted material is made available to anyone wishing to use, modify, + ~ copy, or redistribute it subject to the terms and conditions of the GNU + ~ Lesser General Public License, as published by the Free Software Foundation. + ~ + ~ This program is distributed in the hope that it will be useful, + ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License + ~ for more details. + ~ + ~ You should have received a copy of the GNU Lesser General Public License + ~ along with this distribution; if not, write to: + ~ Free Software Foundation, Inc. + ~ 51 Franklin Street, Fifth Floor + ~ Boston, MA 02110-1301 USA + --> +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../custom.dtd"> +%CustomDTD; +]> +<chapter id="environment"> + <title>Environment</title> + <para> + The various components of JBoss DNA are designed as plain old Java objects, or POJOs. And rather than making assumptions + about their environment, each component instead requires that any external dependencies necessary for it to operate + must be supplied to it. This pattern is known as Dependency Injection, and it allows the components to be simpler + and allows for a great deal of flexibility and customization in how the components are configured. + And, JBoss DNA will soon provide a higher-level component that leverages the + <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink> to automatically assemble and wire together + all the lower-level components. + </para> + <sect1 id="security"> + <title>Security</title> + <para> + JBoss DNA uses the + <ulink url="http://java.sun.com/javase/technologies/security/">Java Authentication and Authorization Service (JAAS)</ulink> + for its security mechanism. Not only is this the standard approach for authenticating and authorizing in Java, but + it also enables JBoss DNA to integrate existing security systems. + </para> + <para> + There are quite a few JAAS providers available, but one of the best and most powerful providers is + <ulink url="http://www.jboss.org/jbosssecurity/">JBoss Security</ulink>, which is the open source + security framework used by JBoss. JBoss Security offers a number of JAAS login modules, including: + <itemizedlist> + <listitem> + <para> + <emphasis role="strong">User-Roles Login Module</emphasis> + is a simple + <code>javax.security.auth.login.LoginContext</code> + implementation that uses usernames and passwords stored in a properties file. + </para> + </listitem> + <listitem> + <para> + <emphasis role="strong">Client Login Module</emphasis> + prompts the user for their username and password. + </para> + </listitem> + <listitem> + <para> + <emphasis role="strong">Database Server Login Module</emphasis> + uses a JDBC database to authenticate principals and associate them with roles. + </para> + </listitem> + <listitem> + <para> + <emphasis role="strong">LDAP Login Module</emphasis> + uses an LDAP directory to authenticate principals. Two implementations are available. + </para> + </listitem> + <listitem> + <para> + <emphasis role="strong">Certificate Login Module</emphasis> + authenticates using X509 certificates, obtaining roles from either property files or a JDBC database. + </para> + </listitem> + <listitem> + <para> + <emphasis role="strong">Operating System Login Module</emphasis> + authenticates using the operating system's mechanism. + </para> + </listitem> + </itemizedlist> + and many others. Plus, JBoss Security also provides other capabilities, such as using XACML policies or using federated single sign-on. + For more detail, see the <ulink url="http://www.jboss.org/jbosssecurity/">JBoss Security</ulink> project. + </para> + <sect2 id="authentication"> + <title>Authenticating with JAAS</title> + <para> + JBoss DNA defers to JAAS to authenticate clients creating repository connections (known as JCR Sessions if using the JCR API), + and generally expects the client application to obtain the JAAS &LoginContext; or &AppControlContext;. + These are then passed to JBoss DNA, which merely verifies that authentication has been done. + </para> + <para> + As we'll see in the <link linkend="execution-context">next section</link>, JBoss DNA has the notion of an &ExecutionContext; + that can be created using JAAS login or access control contexts. These execution contexts therefore contain information + about the subject. + </para> + <para> + We'll also see in the <link linkend="jcr">chapter on JCR</link> how JAAS can be used for authentication when + JCR Sessions are created. + </para> + </sect2> + <sect2 id="authorization"> + <title>Authorization with JAAS</title> + <para> + JBoss DNA does not currently use any of the authorization features of JAAS. However, in future releases where authorization + is supported, JBoss DNA will rely upon JAAS authorization just as it currently does for authentication. + </para> + </sect2> + </sect1> + <sect1 id="execution-context"> + <title>Execution contexts</title> + <para> + One of the objects that must be supplied to many JBoss DNA components is an &ExecutionContext;. Some components + require this context to be passed into individual methods, allowing the context to vary with each method invocation. + Other components require the context to be provided before it's used, and will use that context for all its operations + (until it is given a different one). + </para> + <para> + What does an &ExecutionContext; represent? Quite simply, it's the set of objects that define the environment + or context in which the method or component is currently operating. It includes a way for recording and reporting + errors and problems. It includes the ability to <link linkend="classloaders">create class loaders</link> + given a classpath of class loader names. It also includes information about the current <link linkend="security">user</link>. + It includes access to factories that can be used to create and convert property values. And it includes factories + for working with namespaces and fully-qualified names. In fact, as JBoss DNA evolves, more things may need to be + added. Here is what the &ExecutionContext; interface looks like: + </para> + <programlisting> +public interface &ExecutionContext; extends &ClassLoaderFactory; { + + /** + * Get the factories that should be used to create values for {@link Property properties}. + * @return the property value factory; never null + */ + &ValueFactories; getValueFactories(); + + /** + * Get the namespace registry for this context. + * @return the namespace registry; never null + */ + &NamespaceRegistry; getNamespaceRegistry(); + + /** + * Get the factory for creating {@link Property} objects. + * @return the property factory; never null + */ + &PropertyFactory; getPropertyFactory(); + + /** + * Get the current JAAS access control context. + * @return the access control context; may be <code>null</code> + */ + &AccessControlContext; getAccessControlContext(); + + /** + * Get the current JAAS login context. + * @return the login context; may be <code>null</code> + */ + &LoginContext; getLoginContext(); + + /** + * Get the JAAS subject for which this context was created. + * @return the subject; never null + */ + &Subject; getSubject(); + + /** + * Return a logger associated with this context. This logger records only those activities within the + * context and provide a way to capture the context-specific activities. All log messages are also + * sent to the system logger, so classes that log via this mechanism should <i>not</i> also + * {@link Logger#getLogger(Class) obtain a system logger}. + * @param clazz the class that is doing the logging + * @return the logger, named after <code>clazz</code>; never null + */ + &Logger; getLogger( Class&lt;?> clazz ); + + /** + * Return a logger associated with this context. This logger records only those activities within the + * context and provide a way to capture the context-specific activities. All log messages are also + * sent to the system logger, so classes that log via this mechanism should <i>not</i> also + * {@link Logger#getLogger(Class) obtain a system logger}. + * @param name the name for the logger + * @return the logger, named after <code>clazz</code>; never null + */ + &Logger; getLogger( String name ); +} +</programlisting> + <para> + Notice that &ExecutionContext; extends the &ClassLoaderFactory; interface described in the + <link linkend="classloaders">previous chapter</link>. + </para> + <para> + The fact that so many of the JBoss DNA components take &ExecutionContext; instances gives us some interesting possibilities. + For example, one execution context instance can be used as the highest-level (or "application-level") context for all of the services + (e.g., &RepositoryService;, &SequencingService;, etc.). + Then, an execution context could be created for each user that will be performing operations, and that user's context can + be passed around to not only provide security information about the user but also to allow the activities being performed + to be recorded for user feedback, monitoring and/or auditing purposes. + </para> + <para> + While execution contexts may sound complicated, they're actually very simple to use. In fact, JBoss DNA provides an factory interface + for creating &ExecutionContext; instances. Not surprisingly it's called &ExecutionContextFactory; + and it has methods for creating contexts using <link linkend="security">JAAS</link> login or access control contexts. + JBoss DNA even provides a &BasicExecutionContextFactory; implementation that can be created using its no-arg + constructor. + </para> + <para> + The following code fragment shows how easy it is to create various execution contexts: + </para> + <programlisting> +&ExecutionContextFactory; factory = new &BasicExecutionContextFactory;(); +&ExecutionContext; context1 = factory.create(); + +// Create a context for a user, authenticating using JAAS ... +&CallbackHandler; callbackHandler = ... +&LoginContext; loginContext = new LoginContext("username",callbackHandler); +&ExecutionContext; context2 = factory.create(loginContext); +</programlisting> + <para> + These contexts (or the context factory) can then be passed to the various components as needed. + </para> + </sect1> +</chapter> + Modified: trunk/docs/reference/src/main/docbook/en-US/content/future.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/future.xml 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/docs/reference/src/main/docbook/en-US/content/future.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -22,20 +22,18 @@ ~ 51 Franklin Street, Fifth Floor ~ Boston, MA 02110-1301 USA --> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../custom.dtd"> +%CustomDTD; +]> <chapter id="future"> <title>Looking to the future</title> <para>What's next for JBoss DNA? Well, the sequencing system is just the beginning. With this release, the sequencing system is stable enough so that more <link linkend="sequencers">sequencers</link> can be developed and used within your own applications. If you're interested in getting involved with the JBoss DNA project, consider picking up one of the sequencers on our - <ulink url="http://jira.jboss.org/jira/browse/DNA?report=com.atlassian.jira...;. + <ulink url="&JIRA;?report=com.atlassian.jira.plugin.system.project:roadmap-panel">roadmap</ulink>. Or, check out <ulink url="http://jira.jboss.org/jira/secure/IssueNavigator.jspa?reset=tru... for the list of sequencers we've thought of. If you think of one that's not there, please add it to JIRA! </para> - <para>The next release will focus on creating the <link linkend="federation">federation engine</link> and connectors - for several popular and ubiquitous systems. The 0.2 release will likely only federate information in a read-only manner, - but updates will soon follow. Also, during the early part of the next release, the JBoss DNA project will switch to use JDK 6. - Java 5 is being end-of-lifed, so we want to move to a supported JDK. However, a number of JBoss projects and products continue to - require Java 5, so our next release will most likely use JDK 6 with Java 5 compatibility.</para> <para>Other components on our roadmap include a web user interface, a REST-ful server, and a view system that allows domain-specific views of information in the repository. These components are farther out on our roadmap, and at this time have not been targeted to a particular release. If any of these are of interest to you, please <link linkend="preface">get involved</link> Modified: trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -22,7 +22,10 @@ ~ 51 Franklin Street, Fifth Floor ~ Boston, MA 02110-1301 USA --> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../custom.dtd"> +%CustomDTD; +]> <chapter id="introduction"> <title>Introduction to JBoss DNA</title> <para> @@ -31,7 +34,7 @@ regular JCR repository that they search, navigate, version, and listen for changes. But under the covers, JBoss DNA gets its content by federating multiple back-end systems (like databases, services, other repositories, etc.), allowing those systems to continue "owning" the information but ensuring the unified repository stays up-to-date - and in sync. + and in sync. JBoss DNA also analyzes the content you put into the repository and turns it into information you can use more effectively. </para> <para> This document goes into detail about JBoss DNA and its capabilities, features, architecture, components, extension points, @@ -151,12 +154,12 @@ transactions, and observation. Because of this, content repositories are used by content management systems (CMS), document management systems (DMS), and other applications that manage electronic files (e.g., documents, images, multi-media, web content, etc.) and metadata associated with them (e.g., author, date, status, security information, etc.). The - <ulink url="http://www.jcp.org/en/jsr/detail?id=170">Content Repository for Java technology API</ulink> + <ulink url="&JSR170;">Content Repository for Java technology API</ulink> provides a standard Java API for working with content repositories. Abbreviated "JCR", this API was developed as part of the Java Community Process under - <ulink url="http://www.jcp.org/en/jsr/detail?id=170">JSR-170</ul... + <ulink url="&JSR170;">JSR-170</ulink> and is being revised under - <ulink url="http://www.jcp.org/en/jsr/detail?id=283">JSR-283</ul... + <ulink url="&JSR283;">JSR-283</ulink> . </para> <para> @@ -179,17 +182,17 @@ <title>Project roadmap</title> <para> The roadmap for JBoss DNA is managed in the project's - <ulink url="https://jira.jboss.org/jira/browse/DNA">JIRA instance</ulink> + <ulink url="&JIRA;">JIRA instance</ulink> . The roadmap shows the different tasks, requirements, issues and other activities that have been targeted to each of the upcoming releases. (The - <ulink url="https://jira.jboss.org/jira/browse/DNA?report=com.atlassian.jir... report</ulink> + <ulink url="&JIRA;?report=com.atlassian.jira.plugin.system.project:roadmap-panel">roadmap report</ulink> always shows the next three releases.) </para> <para> By convention, JIRA issues not immediately targeted to a release will be reviewed periodically to determine the appropriate release where they can be targeted. Any issue that is reviewed and that does not fit in a known release will be targeted to the - <ulink url="https://jira.jboss.org/jira/browse/DNA?report=com.atlassian.jir... Releases</ulink> + <ulink url="&JIRA;?report=com.atlassian.jira.plugin.system.project:roadmap-panel">Future Releases</ulink> bucket. </para> <para> @@ -209,7 +212,7 @@ <itemizedlist> <listitem> <para> - <emphasis role="strong"><ulink url="http://en.wikipedia.org/wiki/Agile_software_development"&g... software development</ulink></emphasis> + <emphasis role="strong"><ulink url="&Wikipedia;Agile_software_development">Agile software development</ulink></emphasis> includes those software methodologies (e.g., Scrum) that promote development iterations and open collaboration. While the JBoss DNA project doesn't follow these closely, we do emphasize the importance of always having running software and using running software as a measure of progress. The JBoss DNA project also wants to move to more frequent @@ -218,7 +221,7 @@ </listitem> <listitem> <para> - <emphasis role="strong"><ulink url="http://en.wikipedia.org/wiki/Test-driven_development">T... development (TDD)</ulink></emphasis> + <emphasis role="strong"><ulink url="&Wikipedia;Test-driven_development">Test-driven development (TDD)</ulink></emphasis> techniques encourage first writing test cases for new features and functionality, then changing the code to add the new features and functionality, and finally the code is refactored to clean-up and address any duplication or inconsistencies. </para> @@ -239,8 +242,8 @@ </listitem> <listitem> <para> - <emphasis role="strong"><ulink url="http://en.wikipedia.org/wiki/Lean_software_development">... software development</ulink></emphasis> - is an adaptation of <ulink url="http://en.wikipedia.org/wiki/Lean_manufacturing">lean manufacturing techniques</ulink>, + <emphasis role="strong"><ulink url="&Wikipedia;Lean_software_development">Lean software development</ulink></emphasis> + is an adaptation of <ulink url="&Wikipedia;Lean_manufacturing">lean manufacturing techniques</ulink>, where emphasis is placed on eliminating waste (e.g., defects, unnecessary complexity, unnecessary code/functionality/features), delivering as fast as passible, deferring irrevocable decisions as much as possible, continuous learning (continuously adapting and improving the process), empowering the team (or community, in our case), @@ -427,7 +430,7 @@ Each of these modules is a Maven project with a group ID of <code>org.jboss.dna</code> . All of these projects correspond to artifacts in the - <ulink url="http://repository.jboss.com/maven2/">JBoss Maven 2 Repository</ulink> + <ulink url="&JBossMaven;">JBoss Maven 2 Repository</ulink> . </para> </sect1> Modified: trunk/docs/reference/src/main/docbook/en-US/content/jcr.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/jcr.xml 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/docs/reference/src/main/docbook/en-US/content/jcr.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -22,7 +22,10 @@ ~ 51 Franklin Street, Fifth Floor ~ Boston, MA 02110-1301 USA --> -<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../custom.dtd"> +%CustomDTD; +]> <chapter id="jcr"> <title>Content Repositories for Java (JCR)</title> <para></para> @@ -34,5 +37,44 @@ <title>Creating JCR sessions</title> <para>Discuss how to obtain JCR sessions and how the credentials work. Also discuss that sessions should be created, used, and closed.</para> + <para>But how does JAAS authentication work with the JCR API and the JBoss DNA JCR implementation? + In JCR, a &Session; represents our connection. So after we create a &JcrRepository; instance, + we just have to call one of the <code>login(...)</code> methods: + </para> + <programlisting role="JAVA"><![CDATA[ +JcrRepository jcrRepository = new JcrRepository(contextFactory, sources); +Session session = jcrRepository.login(sourceName); + ]]></programlisting> + <para>Now, this code doesn't do any authentication; it essentially trusts the caller has the appropriate privileges. + Normally, your application will need to authenticate the user, so let's look at how that's done. + </para> + <para>The JCR API defines a &Credentials; marker interface, an instance of which can be passed to the + <code>&Session;.login(...)</code> method. Rather than provide a concrete implementation of this interface, JBoss DNA + allows you to pass any implementation of &Credentials; that also has one of the following methods: + <itemizedlist> + <listitem> + <para><code>getLoginContext()</code> that returns a &LoginContext; instance.</para> + </listitem> + <listitem> + <para><code>getAccessControlContext()</code> that returns a &AccessControlContext; instance.</para> + </listitem> + </itemizedlist> + This way, your application can obtain the JAAS &LoginContext; or &AccessControlContext; however it wants, + and then merely passes that into DNA through the JCR &Credentials;. No interfaces or classes specific to JBoss DNA are required. + </para> + <para> + The following code shows how this is done, using an anonymous inner class for the &Credentials; implementation. + </para> + <programlisting> +&CallbackHandler; callbackHandler = // as needed by your app, according to JAAS +final &LoginContext; loginContext = new &LoginContext;("MyAppContextName",callbackHandler); + +// Now pass to JBoss DNA to create a JCR Session ... +&Credentials; credentials = new &Credentials;() { +public &LoginContext; getLoginContext() { return loginContext; } +}; +&JcrRepository; jcrRepository = new &JcrRepository;(contextFactory, sources); +&Session; session = jcrRepository.login(credentials, sourceName); +</programlisting> </sect1> </chapter> Modified: trunk/docs/reference/src/main/docbook/en-US/content/legal_notice.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/legal_notice.xml 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/docs/reference/src/main/docbook/en-US/content/legal_notice.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -22,7 +22,10 @@ ~ 51 Franklin Street, Fifth Floor ~ Boston, MA 02110-1301 USA --> -<!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../custom.dtd"> +%CustomDTD; +]> <legalnotice id="Legal_Notice"> <title>Legal Notice</title> <para> Modified: trunk/docs/reference/src/main/docbook/en-US/content/mimetypes.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/mimetypes.xml 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/docs/reference/src/main/docbook/en-US/content/mimetypes.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -22,7 +22,10 @@ ~ 51 Franklin Street, Fifth Floor ~ Boston, MA 02110-1301 USA --> -<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../custom.dtd"> +%CustomDTD; +]> <chapter id="mimetypes"> <title>MIME types</title> <para></para> Modified: trunk/docs/reference/src/main/docbook/en-US/content/preface.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/preface.xml 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/docs/reference/src/main/docbook/en-US/content/preface.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -22,22 +22,23 @@ ~ 51 Franklin Street, Fifth Floor ~ Boston, MA 02110-1301 USA --> -<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../custom.dtd"> +%CustomDTD; +]> <preface id="preface"> <title>Target audience</title> <para> This guide is for the developers of JBoss DNA and those users that want to have a better understanding of how JBoss DNA - works or how to extend the functionality. For a higher-level introduction to JBoss DNA, see the - <ulink url="http://www.jboss.org/file-access/default/members/dna/freezone/d... Started</ulink> - document. + works or how to extend the functionality. For a higher-level introduction to JBoss DNA, see the &GettingStarted; document. </para> <para> If you have any questions or comments, please feel free to contact JBoss DNA's - <ulink url="mailto:dna-users@jboss.org">user mailing list</ulink> or use the - <ulink url="http://www.jboss.com/index.html?module=bb&amp;op=viewforum&... forums</ulink>. - If you'd like to get involved on the project, join the <ulink url="http://www.jboss.org/dna/lists.html">mailing lists</ulink>, - <ulink url="http://www.jboss.org/dna/subversion.html">download the code</ulink> and get it building, and visit our - <ulink url="http://jira.jboss.org/jira/browse/DNA">JIRA issue management system</ulink>. + <ulink url="&MailTo;">user mailing list</ulink> or use the + <ulink url="&Forums;">user forums</ulink>. + If you'd like to get involved on the project, join the <ulink url="&Home;lists.html">mailing lists</ulink>, + <ulink url="&Home;subversion.html">download the code</ulink> and get it building, and visit our + <ulink url="&JIRA;">JIRA issue management system</ulink>. If there's something in particular you're interested in, talk with the community - there may be others interested in the same thing. </para> Modified: trunk/docs/reference/src/main/docbook/en-US/content/repositories.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/repositories.xml 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/docs/reference/src/main/docbook/en-US/content/repositories.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -22,15 +22,200 @@ ~ 51 Franklin Street, Fifth Floor ~ Boston, MA 02110-1301 USA --> -<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../custom.dtd"> +%CustomDTD; +]> <chapter id="repositories"> <title>Repositories</title> <para></para> + <para>There is a lot of information stored in many of different places: databases, repositories, SCM systems, + registries, file systems, services, etc. The purpose of the federation engine is to allow applications to use the JCR API + to access that information as if it were all stored in a single JCR repository, but to really leave the information where + it is.</para> + <para>Why not just copy or move the information into a JCR repository? Moving it is probably pretty difficult, since most + likely there are existing applications that rely upon that information being where it is. All of those applications + 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 creates issues with knowing which information is accurate. + </para> + <para>The JBoss DNA allows lets us leave information where it is, yet provide access to it through the JCR API. + The first benefit is that any existing applications that already use that information can keep using it. + Plus, if the underlying information changes, all the client applications see the correct information. JCR clients + even get the benefit of using JCR observation to be notified of the changes. And if a JBoss DNA repository is + configured to allow updates, client applications can change the information in the repository and JBoss DNA will propagate + those changes down to the original source.</para> + <sect1 id="connectors"> + <title>Repository connectors</title> + <para>As we've mentioned above, one of the capabilities of JBoss DNA is to provide access through + <ulink url="&JSR170;">JCR</ulink> to different kinds of repositories and storage systems. + Your applications work with the JCR API, but through JBoss DNA are able to accesses the content from where the information + exists - not just a single purpose-built repository. This is fundamentally what makes JBoss DNA different.</para> + <para>How does JBoss DNA do this? At the heart of JBoss DNA and it's JCR implementation is a simple graph-based connector + system. Essentially, the JBoss DNA JCR implementation makes use of a single repository source, from which all the + content is accessed. + <figure id="dnajcr-and-connector"> + <title>JBoss DNA's JCR implementation delegates to a repository source</title> + <graphic align="center" scale="100" fileref="dnajcr-and-connector.png"/> + </figure> + That single repository source could be an in-memory repository, a JBoss Cache instance, or a federated repository. + <figure id="dna-connectors-0.2"> + <title>JBoss DNA can put JCR on top of multiple kinds of systems</title> + <graphic align="center" scale="100" fileref="dna-connectors-0.2.png"/> + </figure> + And the JBoss DNA project has plans to create other connectors, too. For instance, we're going to build a connector + to other JCR repositories. And another to a file system, so that the files and directories on an area of the file system + can be accessed through JCR. Of course, if we don't have a connector to suit your needs, you can write your own. + <figure id="dna-connectors-future"> + <title>Future JBoss DNA connectors</title> + <graphic align="center" scale="100" fileref="dna-connectors-future.png"/> + </figure> + </para> + <para>Before we go further, let's define some terminology regarding connectors.</para> + <itemizedlist> + <listitem> + <para> + A <emphasis role="strong">connector</emphasis> is the runnable code packaged in one or more JAR files that + contains implementations of several interfaces (described below). A Java developer <emphasis>writes</emphasis> + a connector to a type of source, such as a particular database management system, LDAP directory, source code + management system, etc. It is then packaged into one or more JAR files (including dependent JARs) and deployed + for use in applications that use JBoss DNA repositories. + </para> + </listitem> + <listitem> + <para> + The description of a particular source system is called a <emphasis role="strong">repository source</emphasis>. + A connector contains a JavaBean class that implements the &RepositorySource; interface, with JavaBean properties for + all of the connector-specific properties required to fully describe a system. Applications that use JBoss DNA + create an instance that describes each external source that a repository is to access. + </para> + </listitem> + <listitem> + <para> + A repository source instance is then used to establish <emphasis role="strong">connections</emphasis> to + that source. A connector provides an implementation of the &RepositoryConnection; interface, which + defines methods for interacting with the external system. In particular, the <code>execute(...)</code> method + takes an <code>ExecutionContext</code> instance and one or more <code>GraphCommand</code> objects describing the + operations that are to be executed against the graph of information the connector is exposing. + Examples of commands include getting a node, moving a node, creating a node, changing a node, and deleting a node. + And, if the repository source is able to participate in JTA/JTS distributed transactions, then the + &RepositoryConnection; must implement the <code>getXaResource()</code> method by returning + a valid <code>javax.transaction.xa.XAResource</code> object that can be used by the transaction monitor. + </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 + relational databases. We first have to develop a connector that allows us to interact with relational databases using JDBC. + That connector would contain a <code>JdbcRepositorySource</code> Java class that implements &RepositorySource;, + and that has all of the various JavaBean properties for setting the name of the driver class, URL, username, password, + and other properties. (Or we might have a JavaBean property that defines the JNDI name where we can find a JDBC + <code>DataSource</code> instance pointing to our JDBC database.) + </para> + <para> + That connector would also have a <code>JdbcRepositoryConnection</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 + as a node wit 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. + </para> + <para> + To use the connector, we need to create an instance of the <classname>JdbcRepositorySource</classname> for each database instance + that we want to access. If we have 3 MySQL databases, 9 Oracle databases, and 4 PostgreSQL databases, then we'd need + to create a total of 16 <classname>JdbcRepositorySource</classname> instances, each with the properties describing a single database instance. + Those sources are then available for use by the JBoss DNA components, including <link linkend="jcr">JCR</link>. + </para> + <para> + So, we've so far learned what a repository connector is and how they're used to create &RepositorySource; instances. + In the <link linkend="repository-service">next section</link>, we'll show how these source instances can be configured, + managed, and their connections pooled. + </para> + </sect1> <sect1 id="repository-service"> <title>Repository Service</title> - <para></para> + <para>The JBoss DNA &RepositoryService; is the component that manages the <emphasis>repository sources</emphasis> + and the connections to them. &RepositorySource; instances can be programmatically added to the service, but + the service can actually read its configuration from a configuration repository (which is represented by a + &RepositorySource; instance that's usually added programmatically to the service). The service connects to + the configuration repository and automatically sets up the repositories given the &RepositorySource; instances + found in the configuration repository. It also transparently maintains for each source a pool of reusable connections. + </para> + <para> + To use a repository, then, involves simply asking the &RepositoryService; for a &RepositoryConnection; + to the repository given the repository's name. If a source exists with that name, the service checks out a connection from + the pool and returns it. The resulting connection is actually a wrapper around the underlying pooled connection - when + the returned connection is closed, it returns the underlying connection to the pool. + </para> + <para>To instantiate the &RepositoryService;, we need to first have a few other objects: + <itemizedlist> + <listitem> + <para> + A &ExecutionContextFactory; instance, as discussed <link linkend="execution-context">earlier</link>. + </para> + </listitem> + <listitem> + <para> + A &RepositoryLibrary; instance that manages the list of &RepositorySource; instances, + properly injects the execution contexts into each repository source, and provides a configurable pool of connections + for each source. + </para> + </listitem> + <listitem> + <para> + A <emphasis>configuration repository</emphasis> that contains descriptions of all of the repository sources + as well as any information those sources need. Because this is a regular repository, this could be a simple + repository with content loaded from an XML file (as in this example). Or it could be a shared + central repository with information about all of the JBoss DNA processes across your company. + </para> + </listitem> + </itemizedlist> + With these components in place, we can then instantiate the &RepositoryService; and start it (using its + &ServiceAdministrator;). During startup, the service reads the configuration repository and loads any + defined &RepositorySource; instances into the repository library, using the class loader factory + (available in the &ExecutionContext;) to obtain. + </para> + <para> + Here's sample code that shows how to set up and start the repository service. You can see something similar + in the example application in the <code>startRepositories()</code> method of the + <code>org.jboss.example.dna.repository.RepositoryClient</code> class. + </para> + <programlisting> + // Create the factory for execution contexts, and create one ... + &ExecutionContextFactory; contextFactory = new &BasicExecutionContextFactory;(); + &ExecutionContext; context = contextFactory.create(); + + // Create the library for the RepositorySource instances ... + &RepositoryLibrary; sources = new &RepositoryLibrary;(contextFactory); + + // Load into the source manager the repository source for the configuration repository ... + &InMemoryRepositorySource; configSource = new &InMemoryRepositorySource;(); + configSource.setName("Configuration"); + sources.addSource(configSource); + + // Now instantiate the Repository Service ... + &RepositoryService; service = new &RepositoryService;(sources, configSource.getName(), context); + service.getAdministrator().start(); + </programlisting> + + <para>After startup completes, the repositories are ready to be used. The client application obtains the list of repositories + and presents them to the user. When the user selects one, the client application starts navigating that repository + starting at its root node (e.g., the "/" path). As you type a command to list the contents of the current node or to + "change directories" to a different node, the client application obtains the information for the node using a simple + procedure: + <orderedlist> + <listitem> + <para>Get a connection to the repository.</para> + </listitem> + <listitem> + <para>Using the connection, find the current node and read its properties and children, putting the information + into a simple Java plain old Java object (POJO).</para> + </listitem> + <listitem> + <para>Close the connection to the repository (in a finally block to ensure it always happens).</para> + </listitem> + </orderedlist> + </para> </sect1> - <sect1 id="connectors"> + <sect1 id="connector-library"> <title>Repository connectors and sources</title> <para></para> <sect2 id="dna-connector-inmemory"> Deleted: trunk/docs/reference/src/main/docbook/en-US/content/security.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/security.xml 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/docs/reference/src/main/docbook/en-US/content/security.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -1,91 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- - ~ JBoss, Home of Professional Open Source. - ~ - ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as - ~ indicated by the @author tags or express copyright attribution - ~ statements applied by the authors. All third-party contributions are - ~ distributed under license by Red Hat Middleware LLC. - ~ - ~ This copyrighted material is made available to anyone wishing to use, modify, - ~ copy, or redistribute it subject to the terms and conditions of the GNU - ~ Lesser General Public License, as published by the Free Software Foundation. - ~ - ~ This program is distributed in the hope that it will be useful, - ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY - ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License - ~ for more details. - ~ - ~ You should have received a copy of the GNU Lesser General Public License - ~ along with this distribution; if not, write to: - ~ Free Software Foundation, Inc. - ~ 51 Franklin Street, Fifth Floor - ~ Boston, MA 02110-1301 USA - --> -<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="security"> - <title>Security</title> - <para> - JBoss DNA uses the - <ulink url="http://java.sun.com/javase/technologies/security/">Java Authentication and Authorization Service (JAAS)</ulink> - for its security mechanism. This offers the greatest flexibility and power for integrating JBoss DNA into other - applications. - </para> - <sect1 id="jboss-security"> - <title>JBoss Security</title> - <para> - The - <ulink url="http://www.jboss.org/jbosssecurity/">JBoss Security</ulink> - provides one of the best and most powerful implementations of the JAAS specification - plus it's open source. JBoss - Security offers a number of login modules, including: - <itemizedlist> - <listitem> - <para> - <emphasis role="strong">User-Roles Login Module</emphasis> - is a simple - <code>javax.security.auth.login.LoginContext</code> - implementation that uses usernames and passwords stored in a properties file. - </para> - </listitem> - <listitem> - <para> - <emphasis role="strong">Client Login Module</emphasis> - prompts the user for their username and password. - </para> - </listitem> - <listitem> - <para> - <emphasis role="strong">Database Server Login Module</emphasis> - uses a JDBC database to authenticate principals and associate them with roles. - </para> - </listitem> - <listitem> - <para> - <emphasis role="strong">LDAP Login Module</emphasis> - uses an LDAP directory to authenticate principals. Two implementations are available. - </para> - </listitem> - <listitem> - <para> - <emphasis role="strong">Certificate Login Module</emphasis> - authenticates using X509 certificates, obtaining roles from either property files or a JDBC database. - </para> - </listitem> - <listitem> - <para> - <emphasis role="strong">Operating System Login Module</emphasis> - authenticates using the operating system's mechanism. - </para> - </listitem> - </itemizedlist> - and many others. - </para> - <para> - JBoss Security also provides other capabilities, such as using XACML policies or using federated single sign-on. For more - detail, see the - <ulink url="http://www.jboss.org/jbosssecurity/">JBoss Security</ulink> - project. - </para> - </sect1> -</chapter> - Modified: trunk/docs/reference/src/main/docbook/en-US/content/sequencing.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/sequencing.xml 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/docs/reference/src/main/docbook/en-US/content/sequencing.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -22,49 +22,800 @@ ~ 51 Franklin Street, Fifth Floor ~ Boston, MA 02110-1301 USA --> -<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../custom.dtd"> +%CustomDTD; +]> <chapter id="sequencing"> <title>Sequencing content</title> - <para></para> + <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> + <para> + This chapter discusses the sequencing features of JBoss DNA and the components that are involved. + </para> <sect1 id="sequencing-service"> <title>Sequencing Service</title> - <para></para> + <para>The JBoss DNA <emphasis>sequencing service</emphasis> is the component that manages the <emphasis>sequencers</emphasis>, + reacting to changes in JCR repositories and then running the appropriate sequencers. + This involves processing the changes on a node, determining which (if any) sequencers should be run on that node, + and for each sequencer constructing the execution environment, calling the sequencer, and saving the information + generated by the sequencer.</para> + <note> + <para>Configuring JBoss DNA services is a bit more manual than is ideal. As you'll see, JBoss DNA uses dependency + injection to allow a great deal of flexibility in how it can be configured and customized. But this flexibility + makes it more difficult for you to use. We understand this, and will soon provide a much easier way to set up + and manage JBoss DNA. Current plans are to use the <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink> + along with a configuration repository.</para> + </note> + <para>To set up the sequencing service, an instance is created, and dependent components are injected into + the object. This includes among other things: + <itemizedlist> + <listitem> + <para>An <emphasis>execution context</emphasis> that defines the context in which the service runs, including + a factory for JCR sessions given names of the repository and workspace. This factory must be configured, + and is how JBoss DNA knows about your JCR repositories and how to connect to them. More on this a bit later.</para> + </listitem> + <listitem> + <para>An optional <emphasis>factory for class loaders</emphasis> used to load sequencers. If no factory is supplied, + the service uses the current thread's context class loader (or if that is null, the class loader that loaded the + sequencing service class).</para> + </listitem> + <listitem> + <para>An &ExecutorService; used to execute the sequencing activites. If none + is supplied, a new single-threaded executor is created by calling <code>Executors.newSingleThreadExecutor()</code>. + (This can easily be changed by subclassing and overriding the <code>SequencerService.createDefaultExecutorService()</code> method.)</para> + </listitem> + <listitem> + <para>Filters for sequencers and events. By default, all sequencers are considered for "node added", "property added" + and "property changed" events.</para> + </listitem> + </itemizedlist> + </para> + <para>As mentioned above, the &ExecutionContext; provides access to a &SessionFactory; that is used + by JBoss DNA to establish sessions to your JCR repositories. Two implementations are available: + <itemizedlist> + <listitem> + <para>The &JndiSessionFactory;> looks up JCR &Repository; instances in JNDI using + names that are supplied when creating sessions. This implementation also has methods to set the + JCR &Credentials; for a given workspace name.</para> + </listitem> + <listitem> + <para>The &SimpleSessionFactory; has methods to register the JCR &Repository; instances + with names, as well as methods to set the JCR &Credentials; for a given workspace name.</para> + </listitem> + </itemizedlist> + You can use the &BasicJcrExecutionContext; implementation of &JcrExecutionContext; and supply + a &SessionFactory; instance, or you can provide your own implementation.</para> + <para>Here's an example of how to instantiate and configure the &SequencingService;:</para> + <programlisting> +&SimpleSessionFactory; sessionFactory = new &SimpleSessionFactory;(); +sessionFactory.registerRepository("Main Repository", this.repository); +&Credentials; credentials = new &SimpleCredentials;("jsmith", "secret".toCharArray()); +sessionFactory.registerCredentials("Main Repository/Workspace1", credentials); +ExecutionContext executionContext = new &BasicJcrExecutionContext;(sessionFactory); + +// Create the sequencing service, passing in the execution context ... +&SequencingService; sequencingService = new &SequencingService;(); +sequencingService.setExecutionContext(executionContext); +</programlisting> + <para>After the sequencing service is created and configured, it must be started. The &SequencingService; + has an <emphasis>administration object</emphasis> (that is an instance of &ServiceAdministrator;) + with <code>start()</code>, <code>pause()</code>, and <code>shutdown()</code> methods. The latter method will + close the queue for sequencing, but will allow sequencing operations already running to complete normally. + To wait until all sequencing operations have completed, simply call the <code>awaitTermination</code> method + and pass it the maximum amount of time you want to wait.</para> + <programlisting> +sequencingService.getAdministrator().start(); +</programlisting> + <para>The JBoss DNA services are utilizing resources and threads that must be released before your application is ready to shut down. + The safe way to do this is to simply obtain the &ServiceAdministrator; for each service (via the <code>getServiceAdministrator()</code> method) + and call <code>shutdown()</code>. As previously mentioned, the shutdown method will simply prevent new work from being processed + and will not wait for existing work to be completed. If you want to wait until the service completes all its work, you must wait + until the service terminates. Here's an example that shows how this is done:</para> + <programlisting> +// Shut down the service and wait until it's all shut down ... +sequencingService.getAdministrator().shutdown(); +sequencingService.getAdministrator().awaitTermination(5, TimeUnit.SECONDS); + +// Shut down the observation service ... +observationService.getAdministrator().shutdown(); +observationService.getAdministrator().awaitTermination(5, TimeUnit.SECONDS); +</programlisting> </sect1> + <sect1 id="sequencer-configuration"> + <title>Sequencer Configurations</title> + <para>The sequencing service must also be configured with the sequencers that it will use. This is done using the + <code>addSequencer(SequencerConfig)</code> method and passing a &SequencerConfig; instance that + you create. Here's the code that defines 3 sequencer configurations: 1 that places image metadata into + "<code><![CDATA[/images/<filename>]]></code>", another that places MP3 metadata into "<code><![CDATA[/mp3s/<filename>]]></code>", + and a third that places a structure that represents the classes, methods, and attributes found within Java source into + "<code><![CDATA[/java/<filename>]]></code>".</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)[*])/jcr:content[@jcr:data] => /images/$1"}; +&SequencerConfig; imageSequencerConfig = new &SequencerConfig;(name, desc, classname, + classpath, pathExpressions); +sequencingService.addSequencer(imageSequencerConfig); + +name = "MP3 Sequencer"; +desc = "Sequences MP3 files to extract the ID3 tags from the audio file"; +classname = "org.jboss.dna.sequencer.mp3.Mp3MetadataSequencer"; +pathExpressions = {"//(*.mp3[*])/jcr:content[@jcr:data] =&gt; /mp3s/$1"}; +&SequencerConfig; mp3SequencerConfig = new &SequencerConfig;(name, desc, classname, + classpath, pathExpressions); +sequencingService.addSequencer(mp3SequencerConfig); + +name = "Java Sequencer"; +desc = "Sequences java files to extract the characteristics of the Java source"; +classname = "org.jboss.dna.sequencer.java.JavaMetadataSequencer"; +pathExpressions = {"//(*.java[*])/jcr:content[@jcr:data] => /java/$1"}; +&SequencerConfig; javaSequencerConfig = new &SequencerConfig;(name, desc, classname, + classpath, pathExpressions); +this.sequencingService.addSequencer(javaSequencerConfig); +</programlisting> + <para>Each configuration defines several things, including the name, description, and sequencer implementation class. + The configuration also defines the classpath information, which can be passed to the &ClassLoaderFactory; to get + a Java &ClassLoader; with which the sequencer class can be loaded. (If no classpath information is provided, as is done + in the code above, the application class loader is used.) The configuration also specifies the path expressions that + identify the nodes that should be sequenced with the sequencer and where to store the output generated by the sequencer. + Path expressions are pretty straightforward but are quite powerful, so before we go any further with the example, + let's dive into path expressions in more detail.</para> + <sect2 id="path_expressions"> + <title>Path Expressions</title> + <para>Path expressions consist of two parts: a selection criteria (or an input path) and an output path:</para> + <programlisting><![CDATA[ inputPath => outputPath ]]></programlisting> + <para>The <emphasis>inputPath</emphasis> part defines an expression for the path of a node that is to be sequenced. + Input paths consist of '<code>/</code>' separated segments, where each segment represents a pattern for a single node's + name (including the same-name-sibling indexes) and '<code>@</code>' signifies a property name.</para> + <para>Let's first look at some simple examples:</para> + <table frame='all'> + <title>Simple Input Path Examples</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*"/> + <colspec colname='c2' colwidth="1*"/> + <thead> + <row> + <entry>Input Path</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row><entry>/a/b</entry><entry>Match node "<code>b</code>" that is a child of the top level node "<code>a</code>". Neither node + may have any same-name-sibilings.</entry></row> + <row><entry>/a/*</entry><entry>Match any child node of the top level node "<code>a</code>".</entry></row> + <row><entry>/a/*.txt</entry><entry>Match any child node of the top level node "<code>a</code>" that also has a name ending in "<code>.txt</code>".</entry></row> + <row><entry>/a/*.txt</entry><entry>Match any child node of the top level node "<code>a</code>" that also has a name ending in "<code>.txt</code>".</entry></row> + <row><entry>/a/b@c</entry><entry>Match the property "<code>c</code>" of node "<code>/a/b</code>".</entry></row> + <row><entry>/a/b[2]</entry><entry>The second child named "<code>b</code>" below the top level node "<code>a</code>".</entry></row> + <row><entry>/a/b[2,3,4]</entry><entry>The second, third or fourth child named "<code>b</code>" below the top level node "<code>a</code>".</entry></row> + <row><entry>/a/b[*]</entry><entry>Any (and every) child named "<code>b</code>" below the top level node "<code>a</code>".</entry></row> + <row><entry>//a/b</entry><entry>Any node named "<code>b</code>" that exists below a node named "<code>a</code>", regardless + of where node "<code>a</code>" occurs. Again, neither node may have any same-name-sibilings.</entry></row> + </tbody> + </tgroup> + </table> + <para>With these simple examples, you can probably discern the most important rules. First, the '<code>*</code>' is a wildcard character + that matches any character or sequence of characters in a node's name (or index if appearing in between square brackets), and + can be used in conjunction with other characters (e.g., "<code>*.txt</code>").</para> + <para>Second, square brackets (i.e., '<code>[</code>' and '<code>]</code>') are used to match a node's same-name-sibiling index. + You can put a single non-negative number or a comma-separated list of non-negative numbers. Use '0' to match a node that has no + same-name-sibilings, or any positive number to match the specific same-name-sibling.</para> + <para>Third, combining two delimiters (e.g., "<code>//</code>") matches any sequence of nodes, regardless of what their names are + or how many nodes. Often used with other patterns to identify nodes at any level matching other patterns. + Three or more sequential slash characters are treated as two.</para> + <para>Many input paths can be created using just these simple rules. However, input paths can be more complicated. Here are some + more examples:</para> + <table frame='all'> + <title>More Complex Input Path Examples</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth="1*"/> + <colspec colname='c2' colwidth="1*"/> + <thead> + <row> + <entry>Input Path</entry> + <entry>Description</entry> + </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 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 + 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 + "<code>something</code>". None of the nodes may have same-name-sibling indexes.</entry></row> + </tbody> + </tgroup> + </table> + <para>These examples show a few more advanced rules. Parentheses (i.e., '<code>(</code>' and '<code>)</code>') can be used + to define a set of options for names, as shown in the first and third rules. Whatever part of the selected node's path + appears between the parentheses is captured for use within the output path. Thus, the first input path in the previous table + would match node "<code>/a/b</code>", and "b" would be captured and could be used within the output path using "<code>$1</code>", + where the number used in the output path identifies the parentheses.</para> + <para>Square brackets can also be used to specify criteria on a node's properties or children. Whatever appears in between the square + brackets does not appear in the selected node.</para> + <para>Let's go back to the previous code fragment and look at the first path expression:</para> + <programlisting><![CDATA[ //(*.(jpg|jpeg|gif|bmp|pcx|png)[*])/jcr:content[@jcr:data] => /images/$1 ]]></programlisting> + <para>This matches a node named "<code>jcr:content</code>" with property "<code>jcr:data</code>" but no siblings with the same name, + and that is a child of a node whose name ends with "<code>.jpg</code>", "<code>.jpeg</code>", "<code>.gif</code>", "<code>.bmp</code>", "<code>.pcx</code>", + or "<code>.png</code>" that may have any same-name-sibling index. These nodes can appear at any level in the repository. + Note how the input path capture the filename (the segment containing the file extension), including any same-name-sibling index. + 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> - <para></para> + <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. + </para> <sect2 id="dna-sequencer-images"> <title>Image sequencer</title> - <para></para> + <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></para> + <para> + This sequencer is included in JBoss DNA and processes Microsoft Office documents, including Excel spreadsheets + and PowerPoint presentations. 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> + <note> + <para> + Currently, Word documents are not supported. For more information and the latest status, see + <ulink url="&JIRA;-153">DNA-153</ulink>. + </para> + </note> + <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></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> </sect2> <sect2 id="dna-sequencer-java"> <title>Java source sequencer</title> - <para>The JBoss DNA makes somes extensions available to clients and one of these extensions is the <emphasis role="strong">dna-sequence-java</emphasis>, - the sequencer tool for java source. - The Java source sequencer sequences any kind of java source with "*.java" extension and extras meaningful informations from this - file. The tool may have the ability to sequence any type of java compilation units (class declaration, interface declaration, - and enum declaration), that are stored in a content repository. + <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 = "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-mp3"> <title>MP3 audio file sequencer</title> - <para></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 = "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-cnd"> <title>JCR Compact Node Definition (CND) file sequencer</title> - <para></para> + <para> + This sequencer is incomplete and is not currently usable. The purpose is to sequence JCR Compact Node Definition (CND) files + to extract the node definitions with their property definitions, and inserting these into the repository using JCR standard notation. + </para> </sect2> </sect1> <sect1 id="custom-sequencers"> - <title>Writing custom sequencers</title> - <para></para> + <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 + sequencers and to then configure JBoss DNA to use them in your own application. + </para> + <para> + Creating a custom sequencer involves the following steps: + <itemizedlist> + <listitem> + <para>Create a Maven 2 project for your sequencer;</para> + </listitem> + <listitem> + <para>Implement the &StreamSequencer; interface with your own implementation, and create unit tests to verify + the functionality and expected behavior;</para> + </listitem> + <listitem> + <para>Add the sequencer configuration to the JBoss DNA &SequencingService; in your application + as described in the <link linkend="using_dna">previous chapter</link>; and</para> + </listitem> + <listitem> + <para>Deploy the JAR file with your implementation (as well as any dependencies), and make them available to JBoss DNA + in your application.</para> + </listitem> + </itemizedlist> + It's that simple. + </para> + <sect2 id="custom_sequencer_project"> + <title>Creating the Maven 2 project</title> + <para>The first step is to create the Maven 2 project that you can use to compile your code and build the JARs. + Maven 2 automates a lot of the work, and since you're already <link linkend="maven">set up to use Maven</link>, + using Maven for your project will save you a lot of time and effort. Of course, you don't have to use Maven 2, but then you'll + have to get the required libraries and manage the compiling and building process yourself.</para> + <note> + <para>JBoss DNA may provide in the future a Maven archetype for creating sequencer projects. If you'd find this useful + and would like to help create it, please <link linkend="preface">join the community</link>.</para> + </note> + <note> + <para>The <emphasis role="strong">dna-sequencer-images</emphasis> project is a small, self-contained sequencer implementation that + has only the minimal dependencies. Starting with this project's source and modifying it to suit your needs may be the easiest way to get started. + See the subversion repository: <ulink url="&Subversion;trunk/extensions/dna-sequencer-images/">&Subversion;trunk/sequencers/dna-sequencer-images/</ulink> + </para> + </note> + <para>You can create your Maven project any way you'd like. For examples, see the <ulink url="http://maven.apache.org/guides/getting-started/index.html#How_d... 2 documentation</ulink>. + Once you've done that, just add the dependencies in your project's <code>pom.xml</code> dependencies section:</para> + <programlisting role="XML"><![CDATA[ +<dependency> + <groupId>org.jboss.dna</groupId> + <artifactId>dna-common</artifactId> + <version>0.1</version> +</dependency> +<dependency> + <groupId>org.jboss.dna</groupId> + <artifactId>dna-graph</artifactId> + <version>0.1</version> +</dependency> +<dependency> + <groupId>org.slf4j</groupId> + <artifactId>slf4j-api</artifactId> +</dependency> + ]]></programlisting> + <para>These are minimum dependencies required for compiling a sequencer. Of course, you'll have to add + other dependencies that your sequencer needs.</para> + <para>As for testing, you probably will want to add more dependencies, such as those listed here:</para> + <programlisting role="XML"><![CDATA[ +<dependency> + <groupId>junit</groupId> + <artifactId>junit</artifactId> + <version>4.4</version> + <scope>test</scope> +</dependency> +<dependency> + <groupId>org.hamcrest</groupId> + <artifactId>hamcrest-library</artifactId> + <version>1.1</version> + <scope>test</scope> +</dependency> +<!-- Logging with Log4J --> +<dependency> + <groupId>org.slf4j</groupId> + <artifactId>slf4j-log4j12</artifactId> + <version>1.4.3</version> + <scope>test</scope> +</dependency> +<dependency> + <groupId>log4j</groupId> + <artifactId>log4j</artifactId> + <version>1.2.14</version> + <scope>test</scope> +</dependency> + ]]></programlisting> + <para>Testing JBoss DNA sequencers does not require a JCR repository or the JBoss DNA services. (For more detail, + see the <link linkend="testing_custom_sequencers">testing section</link>.) However, if you want to do + integration testing with a JCR repository and the JBoss DNA services, you'll need additional dependencies for these libraries.</para> + <programlisting role="XML"><![CDATA[ +<dependency> + <groupId>org.jboss.dna</groupId> + <artifactId>dna-repository</artifactId> + <version>0.1</version> + <scope>test</scope> +</dependency> +<!-- Java Content Repository API --> +<dependency> + <groupId>javax.jcr</groupId> + <artifactId>jcr</artifactId> + <version>1.0.1</version> + <scope>test</scope> +</dependency> +<!-- Apache Jackrabbit (JCR Implementation) --> +<dependency> + <groupId>org.apache.jackrabbit</groupId> + <artifactId>jackrabbit-api</artifactId> + <version>1.3.3</version> + <scope>test</scope> + <!-- Exclude these since they are included in JDK 1.5 --> + <exclusions> + <exclusion> + <groupId>xml-apis</groupId> + <artifactId>xml-apis</artifactId> + </exclusion> + <exclusion> + <groupId>xerces</groupId> + <artifactId>xercesImpl</artifactId> + </exclusion> + </exclusions> +</dependency> +<dependency> + <groupId>org.apache.jackrabbit</groupId> + <artifactId>jackrabbit-core</artifactId> + <version>1.3.3</version> + <scope>test</scope> + <!-- Exclude these since they are included in JDK 1.5 --> + <exclusions> + <exclusion> + <groupId>xml-apis</groupId> + <artifactId>xml-apis</artifactId> + </exclusion> + <exclusion> + <groupId>xerces</groupId> + <artifactId>xercesImpl</artifactId> + </exclusion> + </exclusions> +</dependency> + ]]></programlisting> + <para>At this point, your project should be set up correctly, and you're ready to move on to + <link linkend="custom_sequencer_implementation">writing the Java implementation</link> for your sequencer.</para> + </sect2> + <sect2 id="custom_sequencer_implementation"> + <title>Implementing the StreamSequencer interface</title> + <para>After creating the project and setting up the dependencies, the next step is to create a Java class that implements + the &StreamSequencer; interface. This interface is very straightforward and involves a single method:</para> + <programlisting> +public interface &StreamSequencer; { + + /** + * Sequence the data found in the supplied stream, placing the output + * information into the supplied map. + * + * @param stream the stream with the data to be sequenced; never null + * @param output the output from the sequencing operation; never null + * @param progressMonitor the progress monitor that should be kept + * updated with the sequencer's progress and that should be + * frequently consulted as to whether this operation has been cancelled. + */ + void sequence( &InputStream; stream, &SequencerOutput; output, &ProgressMonitor; progressMonitor ); +</programlisting> + <para>The job of a stream sequencer is to process the data in the supplied stream, and place into the &SequencerOutput; + any information that is to go into the JCR repository. JBoss DNA figures out when your sequencer should be called + (of course, using the sequencing configuration you'll add in a bit), and then makes sure the generated information + is saved in the correct place in the repository. + </para> + <para>The &SequencerOutput; class is fairly easy to use. There are basically two methods you need to call. + One method sets the property values, while the other sets references to other nodes in the repository. Use these + methods to describe the properties of the nodes you want to create, using relative paths for the nodes and + valid JCR property names for properties and references. JBoss DNA will ensure that nodes are created or updated + whenever they're needed.</para> + <programlisting> +public interface &SequencerOutput; { + + /** + * Set the supplied property on the supplied node. The allowable + * values are any of the following: + * - primitives (which will be autoboxed) + * - String instances + * - String arrays + * - byte arrays + * - InputStream instances + * - Calendar instances + * + * @param nodePath the path to the node containing the property; + * may not be null + * @param property the name of the property to be set + * @param values the value(s) for the property; may be empty if + * any existing property is to be removed + */ + void setProperty( String nodePath, String property, Object... values ); + + /** + * Set the supplied reference on the supplied node. + * + * @param nodePath the path to the node containing the property; + * may not be null + * @param property the name of the property to be set + * @param paths the paths to the referenced property, which may be + * absolute paths or relative to the sequencer output node; + * may be empty if any existing property is to be removed + */ + void setReference( String nodePath, String property, String... paths ); +} +</programlisting> + <para>JBoss DNA will create nodes of type <code>nt:unstructured</code> unless you specify the value for the + <code>jcr:primaryType</code> property. You can also specify the values for the <code>jcr:mixinTypes</code> property + if you want to add mixins to any node.</para> + <para>For a complete example of a sequencer, let's look at the &ImageMetadataSequencer; + implementation:</para> + <programlisting> +public class &ImageMetadataSequencer; implements &StreamSequencer; { + + public static final String METADATA_NODE = "image:metadata"; + public static final String IMAGE_PRIMARY_TYPE = "jcr:primaryType"; + public static final String IMAGE_MIXINS = "jcr:mixinTypes"; + public static final String IMAGE_MIME_TYPE = "jcr:mimeType"; + public static final String IMAGE_ENCODING = "jcr:encoding"; + public static final String IMAGE_FORMAT_NAME = "image:formatName"; + public static final String IMAGE_WIDTH = "image:width"; + public static final String IMAGE_HEIGHT = "image:height"; + public static final String IMAGE_BITS_PER_PIXEL = "image:bitsPerPixel"; + public static final String IMAGE_PROGRESSIVE = "image:progressive"; + public static final String IMAGE_NUMBER_OF_IMAGES = "image:numberOfImages"; + public static final String IMAGE_PHYSICAL_WIDTH_DPI = "image:physicalWidthDpi"; + public static final String IMAGE_PHYSICAL_HEIGHT_DPI = "image:physicalHeightDpi"; + public static final String IMAGE_PHYSICAL_WIDTH_INCHES = "image:physicalWidthInches"; + public static final String IMAGE_PHYSICAL_HEIGHT_INCHES = "image:physicalHeightInches"; + + /** + * {@inheritDoc} + */ + public void sequence( &InputStream; stream, &SequencerOutput; output, + &ProgressMonitor; progressMonitor ) { + progressMonitor.beginTask(10, &ImageSequencerI18n;.sequencerTaskName); + + &ImageMetadata; metadata = new &ImageMetadata;(); + metadata.setInput(stream); + metadata.setDetermineImageNumber(true); + metadata.setCollectComments(true); + + // Process the image stream and extract the metadata ... + if (!metadata.check()) { + metadata = null; + } + progressMonitor.worked(5); + if (progressMonitor.isCancelled()) return; + + // Generate the output graph if we found useful metadata ... + if (metadata != null) { + // Place the image metadata into the output map ... + output.setProperty(METADATA_NODE, IMAGE_PRIMARY_TYPE, "image:metadata"); + // output.psetProperty(METADATA_NODE, IMAGE_MIXINS, ""); + output.setProperty(METADATA_NODE, IMAGE_MIME_TYPE, metadata.getMimeType()); + // output.setProperty(METADATA_NODE, IMAGE_ENCODING, ""); + output.setProperty(METADATA_NODE, IMAGE_FORMAT_NAME, metadata.getFormatName()); + output.setProperty(METADATA_NODE, IMAGE_WIDTH, metadata.getWidth()); + output.setProperty(METADATA_NODE, IMAGE_HEIGHT, metadata.getHeight()); + output.setProperty(METADATA_NODE, IMAGE_BITS_PER_PIXEL, metadata.getBitsPerPixel()); + output.setProperty(METADATA_NODE, IMAGE_PROGRESSIVE, metadata.isProgressive()); + output.setProperty(METADATA_NODE, IMAGE_NUMBER_OF_IMAGES, metadata.getNumberOfImages()); + output.setProperty(METADATA_NODE, IMAGE_PHYSICAL_WIDTH_DPI, metadata.getPhysicalWidthDpi()); + output.setProperty(METADATA_NODE, IMAGE_PHYSICAL_HEIGHT_DPI, metadata.getPhysicalHeightDpi()); + output.setProperty(METADATA_NODE, IMAGE_PHYSICAL_WIDTH_INCHES, metadata.getPhysicalWidthInch()); + output.setProperty(METADATA_NODE, IMAGE_PHYSICAL_HEIGHT_INCHES, metadata.getPhysicalHeightInch()); + } + + progressMonitor.done(); + } +} +</programlisting> + <para> + Notice how the image metadata is extracted and the output graph is generated. A single node is created with the name <code>image:metadata</code> + and with the <code>image:metadata</code> node type. No mixins are defined for the node, but several properties are set on the node + using the values obtained from the image metadata. After this method returns, the constructed graph will be saved to the repository + in all of the places defined by its configuration. (This is why only relative paths are used in the sequencer.) + </para> + <para>Also note how the progress monitor is used. Reporting progress through the supplied &ProgressMonitor;> is very easy, and it ensures that JBoss DNA + can accurately monitor and report the status of sequencing activities to the users. At the beginning of the operation, call + <code>beginTask(...)</code> with a meaningful message describing + the operation and a total for the amount of work that will be done by this sequencer. Then perform the sequencing work, + periodically reporting work by specifying the incremental amount of work with the <code>worked(double)</code> method, or + by creating a subtask with the <code>createSubtask(double)</code> method and reporting work against that subtask + monitor. + </para> + <para>Your method should periodically use the &ProgressMonitor;'s <code>isCancelled()</code> method to check whether the operation has been + cancelled.. If this method returns true, the implementation should abort all work as + soon as possible and close any resources that were acquired or opened. + </para> + <para> + Finally, when your sequencing operation is completed, it should call <code>done()</code> on the progress monitor. + </para> + </sect2> + <sect2 id="testing_custom_sequencers"> + <title>Testing custom sequencers</title> + <para>The sequencing framework was designed to make testing sequencers much easier. In particular, the + &StreamSequencer; interface does not make use of the JCR API. So instead of requiring a fully-configured + JCR repository and JBoss DNA system, unit tests for a sequencer can focus on testing that the content is + processed correctly and the desired output graph is generated.</para> + <note> + <para>For a complete example of a sequencer unit test, see the <code>ImageMetadataSequencerTest</code> unit test + in the <code>org.jboss.dna.sequencer.images</code> package of the <code>dna-sequencers-image</code> project. + </para> + </note> + <para>The following code fragment shows one way of testing a sequencer, using JUnit 4.4 assertions and + some of the classes made available by JBoss DNA. Of course, + this example code does not do any error handling and does not make all the assertions a real test would.</para> + <programlisting> +&StreamSequencer; sequencer = new &ImageMetadataSequencer;(); +MockSequencerOutput output = new MockSequencerOutput(); +&ProgressMonitor; progress = new &SimpleProgressMonitor;("Test activity"); +&InputStream; stream = null; +try { + stream = this.getClass().getClassLoader().getResource("caution.gif").openStream(); + sequencer.sequence(stream,output,progress); // writes to 'output' + assertThat(output.getPropertyValues("image:metadata", "jcr:primaryType"), + is(new Object[] {"image:metadata"})); + assertThat(output.getPropertyValues("image:metadata", "jcr:mimeType"), + is(new Object[] {"image/gif"})); + // ... make more assertions here + assertThat(output.hasReferences(), is(false)); +} finally { + stream.close(); +} +</programlisting> + <para>It's also useful to test that a sequencer produces no output for something it should not understand:</para> + <programlisting> +&Sequencer; sequencer = new &ImageMetadataSequencer;(); +MockSequencerOutput output = new MockSequencerOutput(); +&ProgressMonitor; progress = new &SimpleProgressMonitor;("Test activity"); +&InputStream; stream = null; +try { + stream = this.getClass().getClassLoader().getResource("caution.pict").openStream(); + sequencer.sequence(stream,output,progress); // writes to 'output' + assertThat(output.hasProperties(), is(false)); + assertThat(output.hasReferences(), is(false)); +} finally { + stream.close(); +} +</programlisting> + <para>These are just two simple tests that show ways of testing a sequencer. Some tests may get quite involved, + especially if a lot of output data is produced. + </para> + <para>It may also be useful to create some integration tests + that <link linkend="using_dna">configure JBoss DNA</link> to use a custom sequencer, and to then upload + content using the JCR API, verifying that the custom sequencer did run. However, remember that JBoss DNA + runs sequencers asynchronously in the background, and you must synchronize your tests to ensure that the + sequencers have a chance to run before checking the results. (One way of doing this (although, granted, not always reliable) is to wait for a second + after uploading your content, shutdown the &SequencingService; and await its termination, + and then check that the sequencer output has been saved to the JCR repository. For an example of this technique, + see the <code>SequencingClientTest</code> unit test in the example application.) + </para> + </sect2> + <sect2 id="deploying_custom_sequencers"> + <title>Deploying custom sequencers</title> + <para>The first step of deploying a sequencer consists of adding/changing the sequencer configuration (e.g., &SequencerConfig;) + in the &SequencingService;. This was covered in the <link linkend="sequencing_service">previous chapter</link>. + </para> + <para> + The second step is to make the sequencer implementation available to JBoss DNA. At this time, the JAR containing + your new sequencer, as well as any JARs that your sequencer depends on, should be placed on your application classpath.</para> + <note> + <para>A future goal of JBoss DNA is to allow sequencers, connectors, and other extensions to be easily deployed into + a runtime repository. This process will not only be much simpler, but it will also provide JBoss DNA + with the information necessary to update configurations and create the appropriate class loaders for each extension. + Having separate class loaders for each extension helps prevent the pollution of the common classpath, + facilitates an isolated runtime environment to eliminate any dependency conflicts, and may potentially + enable hot redeployment of newer extension versions. + </para> + </note> + </sect2> </sect1> </chapter> Modified: trunk/docs/reference/src/main/docbook/en-US/content/testing.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/testing.xml 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/docs/reference/src/main/docbook/en-US/content/testing.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -22,7 +22,10 @@ ~ 51 Franklin Street, Fifth Floor ~ Boston, MA 02110-1301 USA --> -<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % CustomDTD SYSTEM "../custom.dtd"> +%CustomDTD; +]> <chapter id="testing"> <title>Testing</title> <para></para> Added: trunk/docs/reference/src/main/docbook/en-US/custom.dtd =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/custom.dtd (rev 0) +++ trunk/docs/reference/src/main/docbook/en-US/custom.dtd 2008-09-24 21:49:27 UTC (rev 540) @@ -0,0 +1,90 @@ +<!ENTITY versionNumber "0.3"> +<!ENTITY copyrightYear "2008"> +<!ENTITY copyrightHolder "Red Hat Middleware, LLC."> + +<!-- Frequently used URLs --> + +<!ENTITY Home "http://www.jboss.org/dna/"> +<!ENTITY Downloads "&Home;downloads.html"> +<!ENTITY Community "&Home;community.html"> +<!ENTITY DocHome "http://www.jboss.org/file-access/default/members/dna/freezone/"> +<!ENTITY API "&DocHome;api/&versionNumber;/org/jboss/dna/"> +<!ENTITY JIRA "http://jira.jboss.org/jira/browse/DNA"> +<!ENTITY Subversion "http://anonsvn.jboss.org/repos/dna/"> +<!ENTITY Fisheye "http://fisheye.jboss.org/browse/DNA/"> +<!ENTITY SecureSubversion "https://svn.jboss.org/repos/dna/"> +<!ENTITY Forums "http://www.jboss.com/index.html?module=bb&amp;op=viewforum&amp;f=272"> +<!ENTITY JSR170 "http://www.jcp.org/en/jsr/detail?id=170"> +<!ENTITY JSR283 "http://www.jcp.org/en/jsr/detail?id=283"> +<!ENTITY MailTo "mailto:dna-users@jboss.org"> +<!ENTITY Wikipedia "http://en.wikipedia.org/wiki/"> +<!ENTITY JBossMaven "http://repository.jboss.com/maven2/"> + +<!ENTITY Java "http://java.sun.com/j2se/1.5.0/docs/api/"> + +<!ENTITY GettingStarted "<ulink url='&DocHome;docs/&versionNumber;/manuals/gettingstarted/html/index.html'>Getting Started</ulink>"> + +<!-- Types in JRE --> + +<!ENTITY InputStream "<ulink url='&Java;java/io/InputStream.html'><interface>InputStream</interface></ulink>"> +<!ENTITY ClassLoader "<ulink url='&Java;java/lang/ClassLoader.html'><interface>ClassLoader</interface></ulink>"> +<!ENTITY AccessControlContext "<ulink url='&Java;java/security/AccessController.html'><classname>AccessControlContext</classname></ulink>"> +<!ENTITY LoginContext "<ulink url='&Java;javax/security/auth/login/LoginContext.html'><classname>LoginContext</classname></ulink>"> +<!ENTITY Subject "<ulink url='&Java;javax/security/auth/Subject.html'><classname>Subject</classname></ulink>"> +<!ENTITY CallbackHandler "<ulink url='&Java;javax/security/auth/callback/CallbackHandler.html'><interface>CallbackHandler</interface></ulink>"> +<!ENTITY ExecutorService "<ulink url='&Java;java/util/concurrent/ExecutorService.html'><interface>ExecutorService</interface></ulink>"> + +<!-- Types in JCR API --> + +<!ENTITY Repository "<interface>Repository</interface>"> +<!ENTITY Session "<interface>Session</interface>"> +<!ENTITY Credentials "<interface>Credentials</interface>"> + +<!-- Types in dna-common --> + +<!ENTITY Logger "<ulink url='&API;common/util/Logger.html'><interface>Logger</interface></ulink>"> +<!ENTITY ProgressMonitor "<ulink url='&API;common/monitor/ProgressMonitor.html'><interface>ProgressMonitor</interface></ulink>"> +<!ENTITY SimpleProgressMonitor "<ulink url='&API;common/monitor/SimpleProgressMonitor.html'><classname>SimpleProgressMonitor</classname></ulink>"> +<!ENTITY ClassLoaderFactory "<ulink url='&API;common/component/ClassLoaderFactory.html'><interface>ClassLoaderFactory</interface></ulink>"> +<!ENTITY StandardClassLoaderFactory "<ulink url='&API;common/component/ClassLoaderFactory.html'><classname>StandardClassLoaderFactory</classname></ulink>"> + +<!-- Types in dna-graph --> + +<!ENTITY ExecutionContext "<ulink url='&API;graph/ExecutionContext.html'><interface>ExecutionContext</interface></ulink>"> +<!ENTITY ExecutionContextFactory "<ulink url='&API;graph/ExecutionContextFactory.html'><interface>ExecutionContextFactory</interface></ulink>"> +<!ENTITY BasicExecutionContext "<ulink url='&API;graph/BasicExecutionContext.html'><classname>BasicExecutionContext</classname></ulink>"> +<!ENTITY BasicExecutionContextFactory "<ulink url='&API;graph/BasicExecutionContextFactory.html'><classname>BasicExecutionContextFactory</classname></ulink>"> +<!ENTITY ValueFactories "<ulink url='&API;graph/properties/ValueFactories.html'><interface>ValueFactories</interface></ulink>"> +<!ENTITY NamespaceRegistry "<ulink url='&API;graph/properties/NamespaceRegistry.html'><interface>NamespaceRegistry</interface></ulink>"> +<!ENTITY PropertyFactory "<ulink url='&API;graph/properties/PropertyFactory.html'><interface>PropertyFactory</interface></ulink>"> +<!ENTITY RepositorySource "<ulink url='&API;graph/connectors/RepositorySource.html'><interface>RepositorySource</interface></ulink>"> +<!ENTITY RepositoryConnection "<ulink url='&API;graph/connectors/RepositoryConnection.html'><interface>RepositoryConnection</interface></ulink>"> +<!ENTITY StreamSequencer "<ulink url='&API;graph/sequencers/StreamSequencer.html'><interface>StreamSequencer</interface></ulink>"> +<!ENTITY SequencerOutput "<ulink url='&API;graph/sequencers/SequencerOutput.html'><interface>SequencerOutput</interface></ulink>"> + +<!-- Types in dna-repository --> + +<!ENTITY RepositoryLibrary "<ulink url='&API;repository/RepositoryLibrary.html'><classname>RepositoryLibrary</classname></ulink>"> +<!ENTITY RepositoryService "<ulink url='&API;repository/RepositoryService.html'><classname>RepositoryService</classname></ulink>"> +<!ENTITY SequencingService "<ulink url='&API;repository/sequencers/SequencingService.html'><classname>SequencingService</classname></ulink>"> +<!ENTITY ServiceAdministrator "<ulink url='&API;repository/services/ServiceAdministrator.html'><interface>ServiceAdministrator</interface></ulink>"> +<!ENTITY SequencerConfig "<ulink url='&API;repository/sequencers/SequencerConfig.html'><classname>SequencerConfig</classname></ulink>"> +<!ENTITY SessionFactory "<ulink url='&API;repository/util/SessionFactory.html'><interface>SessionFactory</interface></ulink>"> +<!ENTITY JndiSessionFactory "<ulink url='&API;repository/util/JndiSessionFactory.html'><classname>JndiSessionFactory</classname></ulink>"> +<!ENTITY SimpleSessionFactory "<ulink url='&API;repository/util/SimpleSessionFactory.html'><classname>SimpleSessionFactory</classname></ulink>"> +<!ENTITY JcrExecutionContext "<ulink url='&API;repository/util/JcrExecutionContext.html'><interface>JcrExecutionContext</interface></ulink>"> +<!ENTITY BasicJcrExecutionContext "<ulink url='&API;repository/util/BasicJcrExecutionContext.html'><classname>BasicJcrExecutionContext</classname></ulink>"> + +<!-- Types in dna-jcr --> + +<!ENTITY JcrRepository "<ulink url='&API;jcr/JcrRepository.html'><classname>JcrRepository</classname></ulink>"> +<!ENTITY JcrSession "<ulink url='&API;jcr/JcrSession.html'><classname>JcrSession</classname></ulink>"> + +<!-- Types in extensions/ --> + +<!ENTITY InMemoryRepositorySource "<ulink url='&API;connector/inmemory/InMemoryRepositorySource.html'><classname>InMemoryRepositorySource</classname></ulink>"> +<!ENTITY FederatedRepositorySource "<ulink url='&API;connector/federated/FederatedRepositorySource.html'><classname>FederatedRepositorySource</classname></ulink>"> +<!ENTITY ImageMetadataSequencer "<ulink url='&API;sequencer/image/ImageMetadataSequencer.html'><classname>ImageMetadataSequencer</classname></ulink>"> +<!ENTITY ImageMetadata "<ulink url='&API;sequencer/image/ImageMetadata.html'><classname>ImageMetadata</classname></ulink>"> +<!ENTITY ImageSequencerI18n "<ulink url='&API;sequencer/image/ImageSequencerI18n.html'><classname>ImageSequencerI18n</classname></ulink>"> + Added: trunk/docs/reference/src/main/docbook/en-US/images/dna-connectors-0.2.png =================================================================== (Binary files differ) Property changes on: trunk/docs/reference/src/main/docbook/en-US/images/dna-connectors-0.2.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/docs/reference/src/main/docbook/en-US/images/dna-connectors-future.png =================================================================== (Binary files differ) Property changes on: trunk/docs/reference/src/main/docbook/en-US/images/dna-connectors-future.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/docs/reference/src/main/docbook/en-US/images/dnajcr-and-connector.png =================================================================== (Binary files differ) Property changes on: trunk/docs/reference/src/main/docbook/en-US/images/dnajcr-and-connector.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Modified: trunk/docs/reference/src/main/docbook/en-US/master.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/master.xml 2008-09-22 22:58:15 UTC (rev 539) +++ trunk/docs/reference/src/main/docbook/en-US/master.xml 2008-09-24 21:49:27 UTC (rev 540) @@ -23,9 +23,8 @@ ~ Boston, MA 02110-1301 USA --> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -<!ENTITY versionNumber "0.3"> -<!ENTITY copyrightYear "2008"> -<!ENTITY copyrightHolder "Red Hat Middleware, LLC."> +<!ENTITY % CustomDTD SYSTEM "custom.dtd"> +%CustomDTD; ]> <book lang="en"> <bookinfo> @@ -51,14 +50,14 @@ </bookinfo> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/preface.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/introduction.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/development_environment.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/development_tools.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/classloaders.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/security.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/repositories.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/jcr.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/sequencing.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/mimetypes.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/configuration.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/testing.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/environment.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/repositories.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/jcr.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/sequencing.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/mimetypes.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/configuration.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/testing.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/future.xml"/> </book> Added: trunk/docs/reference/src/main/docbook/xslt/eclipse.xslt =================================================================== --- trunk/docs/reference/src/main/docbook/xslt/eclipse.xslt (rev 0) +++ trunk/docs/reference/src/main/docbook/xslt/eclipse.xslt 2008-09-24 21:49:27 UTC (rev 540) @@ -0,0 +1,10 @@ +<?xml version="1.0"?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> + <xsl:import href="classpath:/xslt/org/jboss/eclipse.xsl" /> + + <xsl:param name="siteHref" select="'http://www.jboss.org/dna/'"/> + <xsl:param name="docHref" select="'http://www.jboss.org/dna/documentation.html'"/... + <xsl:param name="siteLinkText" select="'JBoss DNA - Unified Metadata Repository Framework and Tools'"/> + + <xsl:param name="callout.defaultcolumn">1</xsl:param> +</xsl:stylesheet> Added: trunk/docs/reference/src/main/docbook/xslt/pdf.xslt =================================================================== --- trunk/docs/reference/src/main/docbook/xslt/pdf.xslt (rev 0) +++ trunk/docs/reference/src/main/docbook/xslt/pdf.xslt 2008-09-24 21:49:27 UTC (rev 540) @@ -0,0 +1,98 @@ +<?xml version="1.0" encoding="UTF-8"?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:fo="http://www.w3.org/1999/XSL/Format" + version="1.0"> + + <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.72.0/fo/docbook.x... /> + <xsl:import href="classpath:/xslt/org/jboss/pdf.xsl" /> + + <!-- Override the default font settings --> + <xsl:param name="body.font.family" select="'Times New Roman, serif'" /> + <xsl:param name="monospace.font.family" select="'DejaVu Sans Mono, monospace'" /> + <xsl:param name="sans.font.family" select="'Arial, sans-serif'" /> + <xsl:param name="title.font.family" select="$body.font.family" /> + + <xsl:param name="programlisting.font" select="$monospace.font.family" /> + <xsl:param name="programlisting.font.size" select="'75%'" /> + + <!-- Remove the blank pages between the chapters --> + <xsl:param name="double.sided" select="0" /> + + <!-- Use SVG for callout images instead of PNG --> + <xsl:param name="callout.graphics" select="1" /> + <xsl:param name="callout.graphics.extension" select="'.svg'" /> + + <!-- Hide URL --> + <xsl:param name="ulink.show" select="0"/> + + <!-- Don't use italic font for links --> + <xsl:attribute-set name="xref.properties"> + <xsl:attribute name="font-style">normal</xsl:attribute> + </xsl:attribute-set> + + <!-- Decrease the link font size in the program listing --> + + <xsl:attribute-set name="monospace.properties"> + <xsl:attribute name="font-size">1em</xsl:attribute> + <xsl:attribute name="font-family"> + <xsl:value-of select="$monospace.font.family"/> + </xsl:attribute> + </xsl:attribute-set> + + <!-- Add some spacing between callout listing items --> + <xsl:template match="callout"> + + <xsl:variable name="id"><xsl:call-template name="object.id"/></xsl:variable> + <fo:list-item id="{$id}" space-before="1em"> + <fo:list-item-label end-indent="label-end()"> + <fo:block> + <xsl:call-template name="callout.arearefs"> + <xsl:with-param name="arearefs" select="@arearefs"/> + </xsl:call-template> + </fo:block> + </fo:list-item-label> + + <fo:list-item-body start-indent="body-start()"> + <fo:block padding-top="0.2em"> + <xsl:apply-templates/> + </fo:block> + </fo:list-item-body> + </fo:list-item> + </xsl:template> + + <!-- Slight baseline-shift for callouts in the program listing --> + <xsl:template name="callout-bug"> + + <xsl:param name="conum" select='1'/> + <xsl:choose> + <xsl:when test="$conum &lt;= $callout.graphics.number.limit"> + <xsl:variable name="filename" + select="concat($callout.graphics.path, $conum, + $callout.graphics.extension)"/> + + <fo:external-graphic content-width="{$callout.icon.size}" + width="{$callout.icon.size}" + padding="0.0em" margin="0.0em" + baseline-shift="-0.375em"> + <xsl:attribute name="src"> + <xsl:choose> + <xsl:when test="$passivetex.extensions != 0 + or $fop.extensions != 0 + or $arbortext.extensions != 0"> + + <xsl:value-of select="$filename"/> + </xsl:when> + <xsl:otherwise> + <xsl:text>url(</xsl:text> + <xsl:value-of select="$filename"/> + <xsl:text>)</xsl:text> + </xsl:otherwise> + </xsl:choose> + + </xsl:attribute> + </fo:external-graphic> + </xsl:when> + </xsl:choose> + </xsl:template> +</xsl:stylesheet> + Added: trunk/docs/reference/src/main/docbook/xslt/xhtml-single.xslt =================================================================== --- trunk/docs/reference/src/main/docbook/xslt/xhtml-single.xslt (rev 0) +++ trunk/docs/reference/src/main/docbook/xslt/xhtml-single.xslt 2008-09-24 21:49:27 UTC (rev 540) @@ -0,0 +1,10 @@ +<?xml version="1.0"?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> + <xsl:import href="classpath:/xslt/org/jboss/xhtml-single.xsl" /> + + <xsl:param name="siteHref" select="'http://www.jboss.org/dna/'"/> + <xsl:param name="docHref" select="'http://www.jboss.org/dna/documentation.html'"/... + <xsl:param name="siteLinkText" select="'JBoss DNA - Unified Metadata Repository Framework and Tools'"/> + + <xsl:param name="callout.defaultcolumn">1</xsl:param> +</xsl:stylesheet> Added: trunk/docs/reference/src/main/docbook/xslt/xhtml.xslt =================================================================== --- trunk/docs/reference/src/main/docbook/xslt/xhtml.xslt (rev 0) +++ trunk/docs/reference/src/main/docbook/xslt/xhtml.xslt 2008-09-24 21:49:27 UTC (rev 540) @@ -0,0 +1,10 @@ +<?xml version="1.0"?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> + <xsl:import href="classpath:/xslt/org/jboss/xhtml.xsl" /> + + <xsl:param name="siteHref" select="'http://www.jboss.org/dna/'"/> + <xsl:param name="docHref" select="'http://www.jboss.org/dna/documentation.html'"/... + <xsl:param name="siteLinkText" select="'JBoss DNA - Unified Metadata Repository Framework and Tools'"/> + + <xsl:param name="callout.defaultcolumn">1</xsl:param> +</xsl:stylesheet>