[dna-commits] DNA SVN: r999 - in trunk/docs/reference/src/main/docbook/en-US: content and 2 other directories.
dna-commits at lists.jboss.org
dna-commits at lists.jboss.org
Mon Jun 8 15:59:00 EDT 2009
Author: rhauch
Date: 2009-06-08 15:58:59 -0400 (Mon, 08 Jun 2009)
New Revision: 999
Added:
trunk/docs/reference/src/main/docbook/en-US/content/core/execution_context.xml
trunk/docs/reference/src/main/docbook/en-US/content/mime_type_detectors/
trunk/docs/reference/src/main/docbook/en-US/content/mime_type_detectors/aperture.xml
trunk/docs/reference/src/main/docbook/en-US/content/mime_type_detectors/custom_detectors.xml
Removed:
trunk/docs/reference/src/main/docbook/en-US/content/core/classloaders.xml
trunk/docs/reference/src/main/docbook/en-US/content/core/environment.xml
trunk/docs/reference/src/main/docbook/en-US/content/core/mimetypes.xml
Modified:
trunk/docs/reference/src/main/docbook/en-US/custom.dtd
trunk/docs/reference/src/main/docbook/en-US/master.xml
Log:
Added more detail to the Execution Context chapter, and broke out the MIME type detector content into this chapter and a new document part focused on MIME type detectors.
Deleted: trunk/docs/reference/src/main/docbook/en-US/content/core/classloaders.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/core/classloaders.xml 2009-06-08 16:12:59 UTC (rev 998)
+++ trunk/docs/reference/src/main/docbook/en-US/content/core/classloaders.xml 2009-06-08 19:58:59 UTC (rev 999)
@@ -1,121 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- ~ JBoss DNA (http://www.jboss.org/dna)
- ~
- ~ See the COPYRIGHT.txt file distributed with this work for information
- ~ regarding copyright ownership. Some portions may be licensed
- ~ to Red Hat, Inc. under one or more contributor license agreements.
- ~ See the AUTHORS.txt file in the distribution for a full listing of
- ~ individual contributors.
- ~
- ~ JBoss DNA is free software. Unless otherwise indicated, all code in JBoss DNA
- ~ is licensed to you under the terms of the GNU Lesser General Public License as
- ~ published by the Free Software Foundation; either version 2.1 of
- ~ the License, or (at your option) any later version.
- ~
- ~ JBoss DNA 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="classloaders">
- <title>Class loaders</title>
- <para>
- JBoss DNA is designed around extensions: sequencers, connectors, MIME type detectors, and class loader factories.
- The core part of JBoss DNA is relatively small and has few dependencies, while 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 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>
- <sect1>
- <title>Summary</title>
- <para>
- In this chapter, we described the framework used by JBoss DNA to load extension classes, like implementations
- of repositories, sequencers, MIME type detectors, and other components.
- <link linkend="environment">Next</link>, we cover how JBoss security works and how the various components
- of JBoss DNA can access this security information as well as information about the environment in which the component is running.
- </para>
- </sect1>
-</chapter>
Deleted: trunk/docs/reference/src/main/docbook/en-US/content/core/environment.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/core/environment.xml 2009-06-08 16:12:59 UTC (rev 998)
+++ trunk/docs/reference/src/main/docbook/en-US/content/core/environment.xml 2009-06-08 19:58:59 UTC (rev 999)
@@ -1,310 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- ~ JBoss DNA (http://www.jboss.org/dna)
- ~
- ~ See the COPYRIGHT.txt file distributed with this work for information
- ~ regarding copyright ownership. Some portions may be licensed
- ~ to Red Hat, Inc. under one or more contributor license agreements.
- ~ See the AUTHORS.txt file in the distribution for a full listing of
- ~ individual contributors.
- ~
- ~ JBoss DNA is free software. Unless otherwise indicated, all code in JBoss DNA
- ~ is licensed to you under the terms of the GNU Lesser General Public License as
- ~ published by the Free Software Foundation; either version 2.1 of
- ~ the License, or (at your option) any later version.
- ~
- ~ JBoss DNA 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="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 class &ExecutionContext; implements &ClassLoaderFactory; {
-
- /**
- * Get the factories that should be used to create values for {@link Property properties}.
- * @return the property value factory; never null
- */
- public &ValueFactories; getValueFactories() {...}
-
- /**
- * Get the namespace registry for this context.
- * @return the namespace registry; never null
- */
- public &NamespaceRegistry; getNamespaceRegistry() {...}
-
- /**
- * Get the factory for creating {@link Property} objects.
- * @return the property factory; never null
- */
- public &PropertyFactory; getPropertyFactory() {...}
-
- /**
- * Get the security context for this environment.
- * @return the security context; never <code>null</code>
- */
- public &SecurityContext; getSecurityContext() {...}
-
- /**
- * 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
- */
- public &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
- */
- public &Logger; getLogger( String name ) {...}
-
- ...
-}
-</programlisting>
- <para>
- Notice that &ExecutionContext; implements the &ClassLoaderFactory; interface described in the
- <link linkend="classloaders">previous chapter</link>, meaning it can be used to create other contexts. These other methods are not shown,
- but can be used to create create subcontexts with different <link linkend="security">security contexts</link>,
- with different namespace registry, or with different combinations of components.
- </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>
- The following code fragment shows how easy it is to create various execution contexts:
- </para>
- <programlisting>
-&ExecutionContext; context1 = new &ExecutionContext;();
-String jaasRealm = ...;
-
-// Create a context for a user, authenticating using a JAAS LoginContext...
-char[] password = "password".toCharArray();
-&SecurityContext; securityContext = new JaasSecurityContext(jaasRealm, "username", password);
-&ExecutionContext; context2 = context1.with(securityContext);
-
-// Create a context for the same user, authenticating using JAAS, and using a different callback handler ...
-&CallbackHandler; callbackHandler = ...
-&ExecutionContext; context3 = context1.with(new JaasSecurityContext(jaasRealm, callbackHandler);
-
-// Create a context that uses a provided &SecurityContext; (see the <link linkend="security">next section</link>)...
-&SecurityContext; mySecurityContext = ...
-&ExecutionContext; context4 = context1.with(mySecurityContext);
-</programlisting>
- <para>
- These contexts can then be passed to the various components as needed.
- </para>
- </sect1>
- <sect1 id="security">
- <title>Security</title>
- <para>
- JBoss DNA uses a simple abstraction layer to isolate it from the security infrastructure used within an application.
- The &SecurityContext; interface is defined as follows:
- </para>
- <programlisting>
-public interface &SecurityContext; {
-
- /**
- * Get the name of the authenticated user.
- * @return the authenticated user's name
- */
- &String; getUserName();
-
- /**
- * Determine whether the authenticated user has the given role.
- * @param roleName the name of the role to check
- * @return true if the user has the role and is logged in; false otherwise
- */
- boolean hasRole( String roleName );
-
- /**
- * Logs the user out of the authentication mechanism.
- * For some authentication mechanisms, this will be implemented as a no-op.
- */
- void logout();
-}
-</programlisting>
- <para>
- As noted below, this security context is made available through the &ExecutionContext; described above.
- </para>
- <sect2 id="jaas_security">
- <title>JAAS</title>
- <para>
- One such implementation is the &JaasSecurityContext;, which delegates any authentication or authorization requests to a
- <ulink url="http://java.sun.com/javase/technologies/security/">Java Authentication and Authorization Service (JAAS)</ulink>
- provider. This is the standard approach for authenticating and authorizing in Java, and is the default mechanism
- used by the &JcrEngine;.
- </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>, 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>
- <sect2 id="web_security">
- <title>Web application security</title>
- <para>
- If JBoss DNA is being used within a web application, then it is probably desirable to reuse the security infrastructure
- of the application server. This can be accomplished by implementing the &SecurityContext; interface with an implementation
- that delegates to the <interface>HttpServletRequest</interface>. Then, for each request, create a &SecurityContextCredentials;
- instance around your &SecurityContext;, and use that credentials to obtain a JCR &Session;.
- </para>
- <para>
- Here is an example of the &SecurityContext; implementation that uses the servlet request:
- </para>
- <programlisting>
- at Immutable
-public class ServletSecurityContext implements &SecurityContext; {
-
- private final String userName;
- private final HttpServletRequest request;
-
- /**
- * Create a {@link ServletSecurityContext} with the supplied
- * {@link HttpServletRequest servlet information}.
- *
- * @param request the servlet request; may not be null
- */
- public ServletSecurityContext( HttpServletRequest request ) {
- this.request = request;
- this.userName = request.getUserPrincipal() != null ? request.getUserPrincipal().getName() : null;
- }
-
- /**
- * Get the name of the authenticated user.
- * @return the authenticated user's name
- */
- public &String; getUserName() {
- return userName;
- }
-
- /**
- * Determine whether the authenticated user has the given role.
- * @param roleName the name of the role to check
- * @return true if the user has the role and is logged in; false otherwise
- */
- boolean hasRole( String roleName ) {
- request.isUserInRole(roleName);
- }
-
- /**
- * Logs the user out of the authentication mechanism.
- * For some authentication mechanisms, this will be implemented as a no-op.
- */
- public void logout() {
- }
-}</programlisting>
- <para>
- Then use this to create a &Session;:
- </para>
- <programlisting>
-HttpServletRequest request = ...
-&Repository; repository = engine.getRepository("my repository");
-&SecurityContext; securityContext = new ServletSecurityContext(httpServletRequest);
-SecurityContextCredentials credentials = new SecurityContextCredentials(securityContext);
-&Session; session = repository.login(credentials, workspaceName);
-</programlisting>
- </sect2>
- </sect1>
- <sect1>
- <title>Summary</title>
- <para>
- In this chapter, we covered security and environment topics as used throughout JBoss DNA.
- The <link linkend="repositories">next chapter</link> will cover JBoss DNA repositories, including the connector framework,
- how DNA's JCR implementation works with connectors, what connectors are available (and how to use them),
- and how to write your own connector.
- </para>
- </sect1>
-</chapter>
-
Added: trunk/docs/reference/src/main/docbook/en-US/content/core/execution_context.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/core/execution_context.xml (rev 0)
+++ trunk/docs/reference/src/main/docbook/en-US/content/core/execution_context.xml 2009-06-08 19:58:59 UTC (rev 999)
@@ -0,0 +1,578 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ JBoss DNA (http://www.jboss.org/dna)
+ ~
+ ~ See the COPYRIGHT.txt file distributed with this work for information
+ ~ regarding copyright ownership. Some portions may be licensed
+ ~ to Red Hat, Inc. under one or more contributor license agreements.
+ ~ See the AUTHORS.txt file in the distribution for a full listing of
+ ~ individual contributors.
+ ~
+ ~ JBoss DNA is free software. Unless otherwise indicated, all code in JBoss DNA
+ ~ is licensed to you under the terms of the GNU Lesser General Public License as
+ ~ published by the Free Software Foundation; either version 2.1 of
+ ~ the License, or (at your option) any later version.
+ ~
+ ~ JBoss DNA 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="execution_context">
+ <title>Execution Context</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.
+ </para>
+ <para>
+ The approach that JBoss DNA takes is simple: a simple POJO that represents the everything about the environment
+ in which components operate. Called &ExecutionContext;, it contains references to most of the essential
+ facilities, including: security (authentication and authorization); namespace registry; name factories; factories
+ for properties and property values; logging; and access to class loaders (given a classpath).
+ Most of the JBoss DNA components require an &ExecutionContext; and thus have access to all these facilities.
+ </para>
+ <para>
+ The &ExecutionContext; is a concrete class that is instantiated with the no-argument constructor:
+ </para>
+ <programlisting>
+public class &ExecutionContext; implements &ClassLoaderFactory; {
+
+ /**
+ * Create an instance of an execution context, with default implementations for all components.
+ */
+ public &ExecutionContext;() { ... }
+
+ /**
+ * Get the factories that should be used to create values for {@link Property properties}.
+ * @return the property value factory; never null
+ */
+ public &ValueFactories; getValueFactories() {...}
+
+ /**
+ * Get the namespace registry for this context.
+ * @return the namespace registry; never null
+ */
+ public &NamespaceRegistry; getNamespaceRegistry() {...}
+
+ /**
+ * Get the factory for creating {@link Property} objects.
+ * @return the property factory; never null
+ */
+ public &PropertyFactory; getPropertyFactory() {...}
+
+ /**
+ * Get the security context for this environment.
+ * @return the security context; never <code>null</code>
+ */
+ public &SecurityContext; getSecurityContext() {...}
+
+ /**
+ * 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
+ */
+ public &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
+ */
+ public &Logger; getLogger( String name ) {...}
+
+ ...
+}
+</programlisting>
+ <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>
+ As mentioned above, the starting point is to create a default execution context, which will have all the default components:
+ </para>
+<programlisting>
+&ExecutionContext; context = new &ExecutionContext;();
+</programlisting>
+ <para>
+ Once you have this top-level context, you can start creating <emphasis>subcontexts</emphasis> with different components,
+ and different security contexts. (Of course, you can create a subcontext from any &ExceutionContext; instance.)
+ To create a subcontext, simply use one of the <code>with(...)</code> methods on the parent context. We'll show examples
+ later on in this chapter.
+ </para>
+ <sect1 id="security">
+ <title>Security</title>
+ <para>
+ JBoss DNA uses a simple abstraction layer to isolate it from the security infrastructure used within an application.
+ A &SecurityContext; represents the context of an authenticated user, and is defined as an interface:
+ </para>
+ <programlisting>
+public interface &SecurityContext; {
+
+ /**
+ * Get the name of the authenticated user.
+ * @return the authenticated user's name
+ */
+ String getUserName();
+
+ /**
+ * Determine whether the authenticated user has the given role.
+ * @param roleName the name of the role to check
+ * @return true if the user has the role and is logged in; false otherwise
+ */
+ boolean hasRole( String roleName );
+
+ /**
+ * Logs the user out of the authentication mechanism.
+ * For some authentication mechanisms, this will be implemented as a no-op.
+ */
+ void logout();
+}
+</programlisting>
+ <para>
+ Every &ExecutionContext; has a &SecurityContext; instance, though the top-level (default) execution context does not represent
+ an authenticated user. But you can create a subcontext for a user authenticated via JAAS:
+ </para>
+<programlisting>
+&ExecutionContext; context = ...
+String username = ...
+char[] password = ...
+String jaasRealm = ...
+&SecurityContext; securityContext = new JaasSecurityContext(jaasRealm, username, password);
+&ExecutionContext; userContext = context.with(securityContext);
+</programlisting>
+ <para>
+ In the case of JAAS, you might not have the password but would rather prompt the user. In that case, simply create
+ a subcontext with a different security context:
+ </para>
+<programlisting>
+&ExecutionContext; context = ...
+String jaasRealm = ...
+&CallbackHandler; callbackHandler = ...
+&ExecutionContext; userContext = context.with(new JaasSecurityContext(jaasRealm, callbackHandler);
+</programlisting>
+ <para>
+ Of course if your application has a non-JAAS authentication and authorization system, you can simply provide your own implementation
+ of &SecurityContext;:
+ </para>
+<programlisting>
+&ExecutionContext; context = ...
+&SecurityContext; mySecurityContext = ...
+&ExecutionContext; myAppContext = context.with(mySecurityContext);
+</programlisting>
+ <para>
+ These &ExecutionContext; then represent the authenticated user in any component that uses the context.
+ </para>
+ <sect2 id="jaas_security">
+ <title>JAAS</title>
+ <para>
+ One of the &SecurityContext; implementations provided by JBoss DNA is the &JaasSecurityContext;, which delegates any authentication
+ or authorization requests to a <ulink url="http://java.sun.com/javase/technologies/security/">Java Authentication and Authorization Service (JAAS)</ulink>
+ provider. This is the standard approach for authenticating and authorizing in Java.
+ </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>, 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>
+ <sect2 id="web_security">
+ <title>Web application security</title>
+ <para>
+ If JBoss DNA is being used within a web application, then it is probably desirable to reuse the security infrastructure
+ of the application server. This can be accomplished by implementing the &SecurityContext; interface with an implementation
+ that delegates to the <interface>HttpServletRequest</interface>. Then, for each request, create a &SecurityContextCredentials;
+ instance around your &SecurityContext;, and use that credentials to obtain a JCR &Session;.
+ </para>
+ <para>
+ Here is an example of the &SecurityContext; implementation that uses the servlet request:
+ </para>
+ <programlisting>
+ at Immutable
+public class ServletSecurityContext implements &SecurityContext; {
+
+ private final String userName;
+ private final HttpServletRequest request;
+
+ /**
+ * Create a {@link ServletSecurityContext} with the supplied
+ * {@link HttpServletRequest servlet information}.
+ *
+ * @param request the servlet request; may not be null
+ */
+ public ServletSecurityContext( HttpServletRequest request ) {
+ this.request = request;
+ this.userName = request.getUserPrincipal() != null ? request.getUserPrincipal().getName() : null;
+ }
+
+ /**
+ * Get the name of the authenticated user.
+ * @return the authenticated user's name
+ */
+ public String getUserName() {
+ return userName;
+ }
+
+ /**
+ * Determine whether the authenticated user has the given role.
+ * @param roleName the name of the role to check
+ * @return true if the user has the role and is logged in; false otherwise
+ */
+ boolean hasRole( String roleName ) {
+ request.isUserInRole(roleName);
+ }
+
+ /**
+ * Logs the user out of the authentication mechanism.
+ * For some authentication mechanisms, this will be implemented as a no-op.
+ */
+ public void logout() {
+ }
+}</programlisting>
+ <para>
+ Then use this to create a &Session;:
+ </para>
+<programlisting>
+HttpServletRequest request = ...
+&Repository; repository = engine.getRepository("my repository");
+&SecurityContext; securityContext = new ServletSecurityContext(httpServletRequest);
+&ExecutionContext; servletContext = context.with(securityContext);
+</programlisting>
+ <para>
+ We'll see later in the <link linkend="jcr">JCR chapter</link> how this can be use to obtain a JCR &Session; for
+ the authenticated user.
+ </para>
+ </sect2>
+ </sect1>
+ <sect1 id="namespace_registry">
+ <title>Namespace Registry</title>
+ <para>
+ As we saw earlier, every &ExecutionContext; has a registry of namespaces. Namespaces are used throughout the graph API
+ (as we'll see soon), and the prefix associated with each namespace makes for more readable string representations.
+ The namespace registry tracks all of these namespaces and prefixes, and allows registrations to be added, modified, or
+ removed. The interface for the &NamespaceRegistry; shows how these operations are done:
+ </para>
+ <programlisting>
+public interface &NamespaceRegistry; {
+
+ /**
+ * Return the namespace URI that is currently mapped to the empty prefix.
+ * @return the namespace URI that represents the default namespace,
+ * or null if there is no default namespace
+ */
+ String getDefaultNamespaceUri();
+
+ /**
+ * Get the namespace URI for the supplied prefix.
+ * @param prefix the namespace prefix
+ * @return the namespace URI for the supplied prefix, or null if there is no
+ * namespace currently registered to use that prefix
+ * @throws IllegalArgumentException if the prefix is null
+ */
+ String getNamespaceForPrefix( String prefix );
+
+ /**
+ * Return the prefix used for the supplied namespace URI.
+ * @param namespaceUri the namespace URI
+ * @param generateIfMissing true if the namespace URI has not already been registered and the
+ * method should auto-register the namespace with a generated prefix, or false if the
+ * method should never auto-register the namespace
+ * @return the prefix currently being used for the namespace, or "null" if the namespace has
+ * not been registered and "generateIfMissing" is "false"
+ * @throws IllegalArgumentException if the namespace URI is null
+ * @see #isRegisteredNamespaceUri(String)
+ */
+ String getPrefixForNamespaceUri( String namespaceUri, boolean generateIfMissing );
+
+ /**
+ * Return whether there is a registered prefix for the supplied namespace URI.
+ * @param namespaceUri the namespace URI
+ * @return true if the supplied namespace has been registered with a prefix, or false otherwise
+ * @throws IllegalArgumentException if the namespace URI is null
+ */
+ boolean isRegisteredNamespaceUri( String namespaceUri );
+
+ /**
+ * Register a new namespace using the supplied prefix, returning the namespace URI previously
+ * registered under that prefix.
+ * @param prefix the prefix for the namespace, or null if a namesapce prefix should be generated
+ * automatically
+ * @param namespaceUri the namespace URI
+ * @return the namespace URI that was previously registered with the supplied prefix, or null if the
+ * prefix was not previously bound to a namespace URI
+ * @throws IllegalArgumentException if the namespace URI is null
+ */
+ String register( String prefix, String namespaceUri );
+
+ /**
+ * Unregister the namespace with the supplied URI.
+ * @param namespaceUri the namespace URI
+ * @return true if the namespace was removed, or false if the namespace was not registered
+ * @throws IllegalArgumentException if the namespace URI is null
+ * @throws NamespaceException if there is a problem unregistering the namespace
+ */
+ boolean unregister( String namespaceUri );
+
+ /**
+ * Obtain the set of namespaces that are registered.
+ * @return the set of namespace URIs; never null
+ */
+ Set<String> getRegisteredNamespaceUris();
+
+ /**
+ * Obtain a snapshot of all of the {@link Namespace namespaces} registered at the time this method
+ * is called. The resulting set is immutable, and will not reflect changes made to the registry.
+ * @return an immutable set of &Namespace; objects reflecting a snapshot of the registry; never null
+ */
+ Set<&Namespace;> getNamespaces();
+}
+</programlisting>
+ <para>
+ This interfaces exposes &Namespace; objects that are immutable:
+ </para>
+<programlisting>
+ at Immutable
+interface &Namespace; extends Comparable<&Namespace;> {
+ /**
+ * Get the prefix for the namespace
+ * @return the prefix; never null but possibly the empty string
+ */
+ String getPrefix();
+
+ /**
+ * Get the URI for the namespace
+ * @return the namespace URI; never null but possibly the empty string
+ */
+ String getNamespaceUri();
+}
+</programlisting>
+ <para>
+ JBoss DNA actually uses several implementations of &NamespaceRegistry;, but you can even implement your own
+ and create &ExecutionContext;s that uses it:
+ </para>
+<programlisting>
+&NamespaceRegistry; myRegistry = ...
+&ExecutionContext; contextWithMyRegistry = context.with(myRegistry);
+</programlisting>
+ </sect1>
+ <sect1 id="class_loader_factory">
+ <title>Class loaders</title>
+ <para>
+ JBoss DNA is designed around extensions: sequencers, connectors, MIME type detectors, and class loader factories.
+ The core part of JBoss DNA is relatively small and has few dependencies, while many of the "interesting" components
+ are extensions that plug into and are used by different parts of the core or by layers above (such as the
+ <link linkend="jcr">JCR implementation</link>). 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.
+ </para>
+ <note>
+ <para>Of course, you can put all the JARs on the application classpath, too.
+ This is what the examples in the &GettingStarted; document do.
+ </para>
+ </note>
+ <para>
+ But in this case, how does JBoss DNA load all the extension classes? You may have noticed earlier that
+ &ExecutionContext; implements the &ClassLoaderFactory; interface with a single method:
+ </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>
+ This means that any component that has a reference to an &ExecutionContext; has the ability to create a
+ class loader with a supplied class path. As we'll see later, the connectors and sequencers are all
+ defined with a class and optional class path. This is where that class path comes in.
+ </para>
+ <para>
+ The actual meaning of the class path, however, is a function of the implementation. JBoss DNA uses
+ a &StandardClassLoaderFactory; that just loads the classes using the Thread's current context
+ class loader (or, if there is none, delegates to the class loader that loaded the &StandardClassLoaderFactory; class).
+ Of course, it's possible to implement other &ClassLoaderFactory; with other implementations.
+ Then, just create a subcontext with your implementation:
+ </para>
+<programlisting>
+&ClassLoaderFactory; myClassLoaderFactory = ...
+&ExecutionContext; contextWithMyClassLoaderFactories = context.with(myClassLoaderFactory);
+</programlisting>
+ <note>
+ <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 not ready for use, however, since there is no tooling to help populate the repository.
+ </para>
+ </note>
+ </sect1>
+ <sect1 id="mime-type-detectors">
+ <title>Property factory and value factories</title>
+ <para>
+ JBoss DNA often needs the ability to determine the MIME type for some binary content. When uploading content into
+ a repository, we may want to add the MIME type as metadata. Or, we may want to make some processing decisions
+ based upon the MIME type. So, JBoss DNA created a small pluggable framework for determining the MIME type by using
+ the name of the file (e.g., extensions) and/or by reading the actual content.
+ </para>
+ <para>
+ JBoss DNA defines a &MimeTypeDetector; interface that abstracts the implementation that actually determines
+ the MIME type given the name and content.
+ If the detector is able to determine the MIME type, it simply returns
+ it as a string. If not, it merely returns null. Note, however, that a detector must be thread-safe.
+ Here is the interface:
+ </para>
+ <programlisting>
+ at ThreadSafe
+public interface &MimeTypeDetector; {
+
+ /**
+ * Returns the MIME-type of a data source, using its supplied content and/or its supplied name,
+ * depending upon the implementation. If the MIME-type cannot be determined, either a "default"
+ * MIME-type or <code>null</code> may be returned, where the former will prevent earlier
+ * registered MIME-type detectors from being consulted.
+ *
+ * @param name The name of the data source; may be <code>null</code>.
+ * @param content The content of the data source; may be <code>null</code>.
+ * @return The MIME-type of the data source, or optionally <code>null</code>
+ * if the MIME-type could not be determined.
+ * @throws &IOException; If an error occurs reading the supplied content.
+ */
+ &String; mimeTypeOf( &String; name, &InputStream; content ) throws &IOException;;
+}</programlisting>
+ <para>
+ To use a detector, simply invoke the method and supply the name of the content (e.g., the name of the file, with the extension)
+ and the &InputStream; to the actual binary content. The result is a &String; containing the
+ <ulink url="http://www.iana.org/assignments/media-types/">MIME type</ulink>
+ (e.g., "text/plain") or null if the MIME type cannot be determined. Note that the name or &InputStream; may be
+ null, making this a very versatile utility.
+ </para>
+ <para>
+ Once again, you can obtain a &MimeTypeDetector; from the &ExecutionContext;. JBoss DNA provides and uses by
+ default an implementation that uses only the name (the content is ignored), looking at the name's extension
+ and looking for a match in a small listing (loaded from the <code>org/jboss/dna/graph/mime.types</code> loaded from the classpath).
+ You can add extensions by copying this file, adding or correcting the entries, and then placing your updated file in the
+ expected location on the classpath.
+ </para>
+ <para>
+ Of course, you can always use a different &MimeTypeDetector; by creating a subcontext and supplying your implementation:
+ </para>
+<programlisting>
+&MimeTypeDetector; myDetector = ...
+&ExecutionContext; contextWithMyDetector = context.with(myDetector);
+</programlisting>
+ </sect1>
+ <sect1>
+ <title>Property factory and value factories</title>
+ <para>
+ Two other components are made available by the &ExecutionContext;. The &PropertyFactory; is an interface
+ that can be used to create &Property; instances, which are used throughout the graph API. The &ValueFactories;
+ interface provides access to a number of different factories for different kinds of property values.
+ These will be discussed in much more detail in the next chapter. But like the other components that
+ are in an &ExecutionContext;, you can create subcontexts with different implementations:
+ </para>
+<programlisting>
+&PropertyFactory; myPropertyFactory = ...
+&ExecutionContext; contextWithMyPropertyFactory = context.with(myPropertyFactory);
+</programlisting>
+ <para>and</para>
+<programlisting>
+&ValueFactories; myValueFactories = ...
+&ExecutionContext; contextWithMyValueFactories = context.with(myValueFactories);
+</programlisting>
+ <para>
+ Of course, implementing your own factories is a pretty advanced topic, and it will likely be something you do not
+ need to do in your application.
+ </para>
+ </sect1>
+ <sect1>
+ <title>Summary</title>
+ <para>
+ In this chapter, we introduced the &ExecutionContext; as a representation of the environment in which many of the
+ JBoss DNA components operate. &ExecutionContext; provides a very simple but powerful way to inject commonly-needed
+ facilities throughout the system.
+ </para>
+ <para>
+ In the <link linkend="graph-api">next chapter</link>, we'll dive into Graph API and will introduce the notion of
+ nodes, paths, names, and properties, that are so essential and used throughout JBoss DNA.
+ </para>
+ </sect1>
+</chapter>
+
Property changes on: trunk/docs/reference/src/main/docbook/en-US/content/core/execution_context.xml
___________________________________________________________________
Name: svn:keywords
+ Id Revision
Name: svn:eol-style
+ LF
Deleted: trunk/docs/reference/src/main/docbook/en-US/content/core/mimetypes.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/core/mimetypes.xml 2009-06-08 16:12:59 UTC (rev 998)
+++ trunk/docs/reference/src/main/docbook/en-US/content/core/mimetypes.xml 2009-06-08 19:58:59 UTC (rev 999)
@@ -1,204 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- ~ JBoss DNA (http://www.jboss.org/dna)
- ~
- ~ See the COPYRIGHT.txt file distributed with this work for information
- ~ regarding copyright ownership. Some portions may be licensed
- ~ to Red Hat, Inc. under one or more contributor license agreements.
- ~ See the AUTHORS.txt file in the distribution for a full listing of
- ~ individual contributors.
- ~
- ~ JBoss DNA is free software. Unless otherwise indicated, all code in JBoss DNA
- ~ is licensed to you under the terms of the GNU Lesser General Public License as
- ~ published by the Free Software Foundation; either version 2.1 of
- ~ the License, or (at your option) any later version.
- ~
- ~ JBoss DNA 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="mimetypes">
- <title>MIME types</title>
- <para>
- JBoss DNA often needs the ability to determine the MIME type for some binary content. When uploading content into
- a repository, we may want to add the MIME type as metadata. Or, we may want to make some processing decisions
- based upon the MIME type. So, JBoss DNA created a small pluggable framework for determining the MIME type by using
- the name of the file (e.g., extensions) and/or by reading the actual content. Technically, the framework
- delegates this to one or more extensions. And we've provided one extension that does a very good job at
- determining the MIME type from a large variety of file types. But if that isn't sufficient, you can always
- incorporate your own detector into JBoss DNA.
- </para>
- <para>
- To use this system, you simply invoke a static method and supply the name of the content (e.g., the name of the file, with the extension)
- and the &InputStream; to the actual binary content:
- </para>
- <programlisting>&MimeType;.of(name,content)</programlisting>
- <para>
- The result is a &String; containing the <ulink url="http://www.iana.org/assignments/media-types/">MIME type</ulink>
- (e.g., "text/plain") or null if the MIME type cannot be determined. Note that the name or &InputStream; may be
- null, making this a very versatile utility.
- </para>
- <sect1 id="detectors">
- <title>JBoss DNA MIME type detectors</title>
- <para>
- The principle component in this framework is the concept of a <emphasis role="strong">detector</emphasis>.
- A detector attempts to determine the MIME type using the name of the content (e.g., the file name)
- and the actual content itself. If the detector is able to determine the MIME type, it simply returns
- it as a string. If not, it merely returns null. Note, however, that a detector must be thread-safe.
- </para>
- <para>
- Here is the interface:
- </para>
- <programlisting>
-package org.jboss.dna.graph.mimetype;
- at ThreadSafe
-public interface &MimeTypeDetector; {
-
- /**
- * Returns the MIME-type of a data source, using its supplied content and/or
- * its supplied name, depending upon the implementation. If the MIME-type
- * cannot be determined, either a "default" MIME-type or <code>null</code> may
- * be returned, where the former will prevent earlier registered MIME-type
- * detectors from being consulted.
- *
- * @param name The name of the data source; may be <code>null</code>.
- * @param content The content of the data source; may be <code>null</code>.
- * @return The MIME-type of the data source, or optionally <code>null</code>
- * if the MIME-type could not be determined.
- * @throws &IOException; If an error occurs reading the supplied content.
- */
- &String; mimeTypeOf( &String; name,
- &InputStream; content ) throws &IOException;;
-}</programlisting>
- <para>
- Detectors can be added to the &MimeType; class using the <code>addDetector(&MimeTypeDetectorConfig; config)</code>
- method, where the &MimeTypeDetectorConfig; defines the name of the detector class, the name of the
- <link linkend="classloaders">class loader</link>, a name, and a description. It is also possible
- to set the &ClassLoaderFactory; that the &MimeType; singleton will use.
- </para>
- <para>
- We'll next look at the MIME type detectors that are provided out by JBoss DNA out of the box, and how to write your own.
- </para>
- <sect2 id="dna-mimetype-detector-aperture">
- <title>Aperture MIME type detector</title>
- <para>
- The &ApertureMimeTypeDetector; class is an implementation of &MimeTypeDetector; that uses the
- <ulink url="http://aperture.sourceforge.net/">Aperture</ulink> open-source library, which
- is a very capable utility for determining the MIME type for a wide range of file types,
- using both the file name and the actual content.
- </para>
- </sect2>
- </sect1>
- <sect1 id="custom-detectors">
- <title>Writing custom detectors</title>
- <para>
- Creating a custom detector involves the following steps:
- <itemizedlist>
- <listitem>
- <para>Create a Maven 2 project for your detector;</para>
- </listitem>
- <listitem>
- <para>Implement the &MimeTypeDetector; interface with your own implementation, and create unit tests to verify
- the functionality and expected behavior;</para>
- </listitem>
- <listitem>
- <para>Add a &MimeTypeDetectorConfig; to the &MimeType; class in your application
- as described <link linkend="detectors">earlier</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_detector_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 detector 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-mimetype-detector-aperture</emphasis> project is a small, self-contained detector implementation that
- that you can use to help you get going. 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-mimetype-detector-aperture/">&Subversion;trunk/sequencers/dna-mimetype-detector-aperture/</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_do_I_make_my_first_Maven_project">Maven 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 detector. 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>
- After you've created the project, simply implement the &MimeTypeDetector; interface. And testing should be
- quite straightforward, MIME type detectors don't require any other components. In your tests,
- simply instantiate your &MimeTypeDetector; implementation, supply various combinations of names and/or &InputStream;s,
- and verify the output is what you expect.
- </para>
- <para>
- To use in your application, create a &MimeTypeDetectorConfig; object with the name, description, and class information
- for your detector, and add to the &MimeType; class using the <code>addDetector(&MimeTypeDetectorConfig; config)</code> method.
- Then, just use the &MimeType; class.
- </para>
- </sect2>
- </sect1>
-</chapter>
Added: trunk/docs/reference/src/main/docbook/en-US/content/mime_type_detectors/aperture.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/mime_type_detectors/aperture.xml (rev 0)
+++ trunk/docs/reference/src/main/docbook/en-US/content/mime_type_detectors/aperture.xml 2009-06-08 19:58:59 UTC (rev 999)
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ JBoss DNA (http://www.jboss.org/dna)
+ ~
+ ~ See the COPYRIGHT.txt file distributed with this work for information
+ ~ regarding copyright ownership. Some portions may be licensed
+ ~ to Red Hat, Inc. under one or more contributor license agreements.
+ ~ See the AUTHORS.txt file in the distribution for a full listing of
+ ~ individual contributors.
+ ~
+ ~ JBoss DNA is free software. Unless otherwise indicated, all code in JBoss DNA
+ ~ is licensed to you under the terms of the GNU Lesser General Public License as
+ ~ published by the Free Software Foundation; either version 2.1 of
+ ~ the License, or (at your option) any later version.
+ ~
+ ~ JBoss DNA 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="aperture-mimetype-detector">
+ <title>Aperture MIME type detector</title>
+ <para>
+ The &ApertureMimeTypeDetector; class is an implementation of &MimeTypeDetector; that uses the
+ <ulink url="http://aperture.sourceforge.net/">Aperture</ulink> open-source library, which
+ is a very capable utility for determining the MIME type for a wide range of file types,
+ using both the file name and the actual content.
+ </para>
+ <para>
+ To use, simply include the <code>dna-mime-type-detector-aperture.jar</code> file on the classpath
+ and create a new &ExecutionContext; subcontext with it:
+ </para>
+<programlisting>
+&MimeTypeDetector; myDetector = new ApertureMimeTypeDetector();
+&ExecutionContext; contextWithMyDetector = context.with(myDetector);
+</programlisting>
+</chapter>
Property changes on: trunk/docs/reference/src/main/docbook/en-US/content/mime_type_detectors/aperture.xml
___________________________________________________________________
Name: svn:keywords
+ Id Revision
Name: svn:eol-style
+ LF
Added: trunk/docs/reference/src/main/docbook/en-US/content/mime_type_detectors/custom_detectors.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/mime_type_detectors/custom_detectors.xml (rev 0)
+++ trunk/docs/reference/src/main/docbook/en-US/content/mime_type_detectors/custom_detectors.xml 2009-06-08 19:58:59 UTC (rev 999)
@@ -0,0 +1,128 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ JBoss DNA (http://www.jboss.org/dna)
+ ~
+ ~ See the COPYRIGHT.txt file distributed with this work for information
+ ~ regarding copyright ownership. Some portions may be licensed
+ ~ to Red Hat, Inc. under one or more contributor license agreements.
+ ~ See the AUTHORS.txt file in the distribution for a full listing of
+ ~ individual contributors.
+ ~
+ ~ JBoss DNA is free software. Unless otherwise indicated, all code in JBoss DNA
+ ~ is licensed to you under the terms of the GNU Lesser General Public License as
+ ~ published by the Free Software Foundation; either version 2.1 of
+ ~ the License, or (at your option) any later version.
+ ~
+ ~ JBoss DNA 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="custom-mimetype-detector">
+ <title>Writing custom detectors</title>
+ <para>
+ Creating a custom detector involves the following steps:
+ <itemizedlist>
+ <listitem>
+ <para>Create a Maven 2 project for your detector;</para>
+ </listitem>
+ <listitem>
+ <para>Implement the &MimeTypeDetector; interface with your own implementation, and create unit tests to verify
+ the functionality and expected behavior;</para>
+ </listitem>
+ <listitem>
+ <para>Add a &MimeTypeDetectorConfig; to the &MimeType; class in your application
+ as described <link linkend="detectors">earlier</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>
+ <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 detector 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-mimetype-detector-aperture</emphasis> project is a small, self-contained detector implementation that
+ that you can use to help you get going. 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-mimetype-detector-aperture/">&Subversion;trunk/sequencers/dna-mimetype-detector-aperture/</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_do_I_make_my_first_Maven_project">Maven 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 detector. 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>
+ After you've created the project, simply implement the &MimeTypeDetector; interface. And testing should be
+ quite straightforward, MIME type detectors don't require any other components. In your tests,
+ simply instantiate your &MimeTypeDetector; implementation, supply various combinations of names and/or &InputStream;s,
+ and verify the output is what you expect.
+ </para>
+ <para>
+ To use in your application, create a &MimeTypeDetectorConfig; object with the name, description, and class information
+ for your detector, and add to the &MimeType; class using the <code>addDetector(&MimeTypeDetectorConfig; config)</code> method.
+ Then, just use the &MimeType; class.
+ </para>
+</chapter>
Property changes on: trunk/docs/reference/src/main/docbook/en-US/content/mime_type_detectors/custom_detectors.xml
___________________________________________________________________
Name: svn:keywords
+ Id Revision
Name: svn:eol-style
+ LF
Modified: trunk/docs/reference/src/main/docbook/en-US/custom.dtd
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/custom.dtd 2009-06-08 16:12:59 UTC (rev 998)
+++ trunk/docs/reference/src/main/docbook/en-US/custom.dtd 2009-06-08 19:58:59 UTC (rev 999)
@@ -78,6 +78,7 @@
<!ENTITY Property "<ulink url='&API;graph/property/Property.html'><interface>Property</interface></ulink>">
<!ENTITY ValueFactories "<ulink url='&API;graph/property/ValueFactories.html'><interface>ValueFactories</interface></ulink>">
<!ENTITY NamespaceRegistry "<ulink url='&API;graph/property/NamespaceRegistry.html'><interface>NamespaceRegistry</interface></ulink>">
+<!ENTITY Namespace "<ulink url='&API;graph/property/NamespaceRegistry.Namespaces.html'><interface>Namespace</interface></ulink>">
<!ENTITY PropertyFactory "<ulink url='&API;graph/property/PropertyFactory.html'><interface>PropertyFactory</interface></ulink>">
<!ENTITY PathNotFoundException "<ulink url='&API;graph/property/PathNotFoundException.html'><classname>PathNotFoundException</classname></ulink>">
<!ENTITY RepositorySource "<ulink url='&API;graph/connector/RepositorySource.html'><interface>RepositorySource</interface></ulink>">
Modified: trunk/docs/reference/src/main/docbook/en-US/master.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/master.xml 2009-06-08 16:12:59 UTC (rev 998)
+++ trunk/docs/reference/src/main/docbook/en-US/master.xml 2009-06-08 19:58:59 UTC (rev 999)
@@ -81,11 +81,9 @@
JCR-related components are covered in the <link linkend="jcr-part">next part</link>.
</para>
</partintro>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/core/classloaders.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/core/environment.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/core/execution_context.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/core/connector.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/core/sequencing.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/core/mimetypes.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/core/configuration.xml"/>
</part>
<part id="jcr-part">
@@ -135,5 +133,17 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/sequencers/image.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/sequencers/mp3.xml"/>
</part>
+ <part id="provied-mime-type-detectors-part">
+ <title>Provided MIME type detectors</title>
+ <partintro>
+ <para>
+ The JBoss DNA project provides a number of <link linkend="mime-type-detectors">MIME type detectors</link> out-of-the-box.
+ These are ready to be used by simply including them in the classpath and
+ <link linkend="mime-type-detectors">setting up the &ExecutionContext;</link> appropriately.
+ </para>
+ </partintro>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/mime_type_detectors/aperture.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/mime_type_detectors/custom_detectors.xml"/>
+ </part>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/future.xml"/>
</book>
More information about the dna-commits
mailing list