<?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-text-extractor">
    <title>Writing custom text extractors</title>
	  <para>
	  Creating a custom text extractor involves the following steps:
	  <itemizedlist>
	    <listitem>
	      <para>Create a Maven 3 project for your detector;</para>
	    </listitem>
	    <listitem>
	      <para>Implement the &TextExtractor; interface with your own implementation, and create unit tests to verify
	      the functionality and expected behavior; 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 via ModeShape's configuration as described <link linkend="text-extractors">earlier</link>.</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-extractor-tika</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="&GitRepository;/tree/modeshape-&versionNumber;/extensions/modeshape-extractor-tika/">&GitRepository;/tree/modeshape-&versionNumber;/extensions/modeshape-extractor-tika/</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.8-SNAPSHOT</version>
</dependency>
<dependency>
  <groupId>org.modeshape</groupId>
  <artifactId>modeshape-graph</artifactId>
  <version>2.8-SNAPSHOT</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 &TextExtractor; interface. As mentioned in the JavaDoc,
			the "supportsMimeType" method will be called by ModeShape first, and only if your implementation
			returns true for a given MIME type will the "extractFrom" method be called. The supplied &TextExtractorContext;
			object provides information about the text being processed, while the &TextExtractorOutput; is a simple
			interface that your extractor uses to record one or more strings containing the extracted text.
		</para>
		<para>
			Testing should be	quite straightforward as text extractors can simply be instantiated and called by your
			test methods, which can simply instantiate the &TextExtractorContext; class (with the correct information)
			and either mock or implement the &TextExtractorOutput; interface. Again, see the test cases in the
			<ulink url="&GitRepository;/tree/modeshape-&versionNumber;/extensions/modeshape-extractor-tika/">Tika text extractor module</ulink>
			for ideas.
  	</para>
</chapter>
