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

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&lt;?> clazz ) {...} - - /** - * Return a logger associated with this context. This logger records only those activities within the - * context and provide a way to capture the context-specific activities. All log messages are also - * sent to the system logger, so classes that log via this mechanism should <i>not</i> also - * {@link Logger#getLogger(Class) obtain a system logger}. - * @param name the name for the logger - * @return the logger, named after <code>clazz</code>; never null - */ - 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> -@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&lt;?> clazz ) {...} + + /** + * Return a logger associated with this context. This logger records only those activities within the + * context and provide a way to capture the context-specific activities. All log messages are also + * sent to the system logger, so classes that log via this mechanism should <i>not</i> also + * {@link Logger#getLogger(Class) obtain a system logger}. + * @param name the name for the logger + * @return the logger, named after <code>clazz</code>; never null + */ + 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> +@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&lt;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&lt;&Namespace;> getNamespaces(); +} +</programlisting> + <para> + This interfaces exposes &Namespace; objects that are immutable: + </para> +<programlisting> +@Immutable +interface &Namespace; extends Comparable&lt;&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> +@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; -@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_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 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_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 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>