svn commit: r1424093 - in /opennlp/trunk/opennlp-docs/src/docbkx: extension.xml opennlp.xml

[jo...@apache.org]

Author: joern
Date: Wed Dec 19 20:37:53 2012
New Revision: 1424093

URL: http://svn.apache.org/viewvc?rev=1424093&view=rev
Log:
OPENNLP-435 Added short section about extension to documentation.

Added:
    opennlp/trunk/opennlp-docs/src/docbkx/extension.xml   (with props)
Modified:
    opennlp/trunk/opennlp-docs/src/docbkx/opennlp.xml

Added: opennlp/trunk/opennlp-docs/src/docbkx/extension.xml
URL: http://svn.apache.org/viewvc/opennlp/trunk/opennlp-docs/src/docbkx/extension.xml?rev=1424093&view=auto
==============================================================================
--- opennlp/trunk/opennlp-docs/src/docbkx/extension.xml (added)
+++ opennlp/trunk/opennlp-docs/src/docbkx/extension.xml Wed Dec 19 20:37:53 2012
@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
+]>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+<chapter id="tools.extension">
+<title>Extending OpenNLP</title>
+<para>
+In OpenNLP extension can be used to add new functionality and to
+heavily customize an existing component. Most components define
+a factory class which can be implemented to customize the creation
+of it. And some components allow to add new feature generators.
+</para>
+
+<section id="tools.extension.writing">
+	<title>Writing an extension</title>
+	<para>
+	In many places it is possible to pass in an extension class name to customize
+	some aspect of OpenNLP. The implementation class needs to implement the specified
+	interface and should have a public no-argument constructor.
+	</para>
+</section>
+
+<section id="tools.extension.osgi">
+	<title>Running in an OSGi container</title>
+	<para>
+	The traditional way of loading an extension via Class.forName does not work
+	in an OSGi environment because the class paths of the OpenNLP Tools and extension
+	bundle are isolated. OSGi uses services to provide functionality from one bundle
+	to another. The extension bundle must register its extensions as services so that
+	the OpenNLP tools bundle can use them.
+	The following code illustrates how that can be done:
+				<programlisting language="java">
+				<![CDATA[
+Dictionary<String, String> props = new Hashtable<String, String>();
+props.put(ExtensionServiceKeys.ID, "org.test.SuperTokenizer");
+context.registerService(Tokenizer.class.getName(), new org.test.SuperTokenizer(), props);]]>
+		</programlisting>
+	The service OpenNLP is looking for might not be (yet) available. In this case OpenNLP
+	waits until a timeout is reached. If loading the extension fails an ExtensionNotLoadedException
+	is thrown. This exception is also thrown when the thread is interrupted while it is waiting for the
+	extension, the interrupted flag will be set again and the calling code has a chance to handle it.
+	</para>
+</section>
+</chapter>
\ No newline at end of file

Propchange: opennlp/trunk/opennlp-docs/src/docbkx/extension.xml
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Modified: opennlp/trunk/opennlp-docs/src/docbkx/opennlp.xml
URL: http://svn.apache.org/viewvc/opennlp/trunk/opennlp-docs/src/docbkx/opennlp.xml?rev=1424093&r1=1424092&r2=1424093&view=diff
==============================================================================
--- opennlp/trunk/opennlp-docs/src/docbkx/opennlp.xml (original)
+++ opennlp/trunk/opennlp-docs/src/docbkx/opennlp.xml Wed Dec 19 20:37:53 2012
@@ -84,6 +84,7 @@ under the License.
 	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="./chunker.xml" />
 	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="./parser.xml" />
 	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="./coref.xml" />
+	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="./extension.xml" />	
 	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="./corpora.xml" />
 	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="./machine-learning.xml" />
 	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="./uima-integration.xml" />