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] => /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<?> 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&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] => /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]
=> /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]
=> /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] =>
/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] =>
/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] =>
/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&op=viewforum&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 <= $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>