<?xml version="1.0" encoding="UTF-8"?>
<!--
  ~ ModeShape (http://www.modeshape.org)
  ~
  ~ 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.
  ~
  ~ ModeShape is free software. Unless otherwise indicated, all code in ModeShape
  ~ 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.
  ~
  ~ ModeShape 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 3 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 ModeShape
	      in your application.</para>
	    </listitem>
	  </itemizedlist>
	  It's that simple.
	  </para>
	    <para>The first step is to create the Maven 3 project that you can use to compile your code and build the JARs.
	    Maven 3 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 3, but then you'll
	    have to get the required libraries and manage the compiling and building process yourself.</para>
	    <note>
	      <para>ModeShape 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">modeshape-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 Git repository: 
					<ulink url="&GitRepository;/tree/modeshape-&versionNumber;/extensions/modeshape-mimetype-detector-aperture/">&GitRepository;/tree/modeshape-&versionNumber;/extensions/modeshape-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 3 documentation</ulink>.  
	    Once you've done that, just add the dependencies in your project's <code>pom.xml</code> dependencies section:</para>
	  	<programlisting language="XML" role="XML"><![CDATA[<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-common</artifactId>
  <version>2.5.0.Beta-1</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-graph</artifactId>
  <version>2.5.0.Beta-1</version>
</dependency>
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-api</artifactId>
  <version>1.8.4</version>
</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 language="XML" role="XML"><![CDATA[<dependency>
  <groupId>junit</groupId>
  <artifactId>junit</artifactId>
  <version>4.8</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.8.4</version>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>log4j</groupId>
  <artifactId>log4j</artifactId>
  <version>1.2.16</version>
  <scope>test</scope>
</dependency>
]]></programlisting>
			<para>
				After you've created the project, simply implement the &MimeTypeDetector; interface.  And testing should be
				quite straightforward, as 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>
