svn commit: r1696604 - /tika/site/src/site/apt/1.10/configuring.apt

[ni...@apache.org]

Author: nick
Date: Wed Aug 19 14:52:57 2015
New Revision: 1696604

URL: http://svn.apache.org/r1696604
Log:
TIKA-1704 Tika config docs patch from Bob Paulin, for the service loader config which just snuck into v1.10

Modified:
    tika/site/src/site/apt/1.10/configuring.apt

Modified: tika/site/src/site/apt/1.10/configuring.apt
URL: http://svn.apache.org/viewvc/tika/site/src/site/apt/1.10/configuring.apt?rev=1696604&r1=1696603&r2=1696604&view=diff
==============================================================================
--- tika/site/src/site/apt/1.10/configuring.apt (original)
+++ tika/site/src/site/apt/1.10/configuring.apt Wed Aug 19 14:52:57 2015
@@ -138,6 +138,49 @@ Configuring Tika
     At this time, there is no unified way to configure Translators.
     While the work on that is ongoing, for now you will need to review the
     {{{./api/}Tika Javadocs}} to see how individual Translators are configured.
+    
+* {Configuring the Service Loader}
+
+    Tika has a number of service provider types such as parsers, detectors, and translators.  
+    The {{{./api/org/apache/tika/config/ServiceLoader.html}org.apache.tika.config.ServiceLoader}} class provides a registry of each type of provider.  This allows Tika to create
+    implementations such as {{{./api/org/apache/tika/parser/DefaultParser.html}org.apache.tika.parser.DefaultParser}}, 
+    {{{./api/org/apache/tika/language/translate/DefaultTranslator.html}org.apache.tika.language.translate.DefaultTranslator}}, and {{{./api/org/apache/tika/detect/DefaultDetector.html}org.apache.tika.detect.DefaultDetector}} 
+    that can match the appropriate provider to an incoming piece of content.
+    
+    The ServiceLoader's registry can be populated either statically or dynamically.
+    
+    Static
+    Static loading is the default which requires no configuration.  This configuration options is used in
+    Tika deployments where the Tika JAR files reside together in the same classloader hierarchy.  The services 
+    provides are loaded from provider configuration files located within the tika-parsers JAR file at META-INF/services.
+    
+    Dynamic
+    Dynamic loading may be required if the tika service providers will reside in different classloaders such as 
+    in OSGi.  To allow a provider created in tika-config.xml to utilize dynamically loaded services you need to 
+    configure the ServiceLoader to be dynamic with the following configuration:
+    
+---
+<properties>
+  <service-loader dynamic="true"/>
+  ....
+</properties>
+---
+
+    The ServiceLoader can contains a handler to deal with errors that occur during provider initialization.  For example
+    if a class fails to initialize LoadErrorHandler deals with the exception that is thrown.
+    This handler can be configured to:
+    
+    IGNORE - (Default) Do nothing when providers fail to initialize.
+    WARN   - Log a warning when providers fail to initialize.
+    THROW  - Throw an exception when providers fail to initialize.
+
+For example to set the LoadErrorHandler to WARN then use the following configuration:
+---
+<properties>
+  <service-loader loadErrorHandler="WARN"/>
+  ....
+</properties>
+---
 
 ~~ When Translators can have their parameters configured, mention here about
 ~~ specifying which single one to use in the Tika Config XML