Added camel-lucene docs to Gitbook
Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/0ff88495 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/0ff88495 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/0ff88495 Branch: refs/heads/master Commit: 0ff884956a559e459bdee5d44a99f4ab15ec581f Parents: 9aa27a3 Author: Andrea Cosentino <[email protected]> Authored: Thu May 5 14:05:11 2016 +0200 Committer: Andrea Cosentino <[email protected]> Committed: Thu May 5 14:05:11 2016 +0200 ---------------------------------------------------------------------- .../camel-lucene/src/main/docs/lucene.adoc | 238 +++++++++++++++++++ docs/user-manual/en/SUMMARY.md | 1 + 2 files changed, 239 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/0ff88495/components/camel-lucene/src/main/docs/lucene.adoc ---------------------------------------------------------------------- diff --git a/components/camel-lucene/src/main/docs/lucene.adoc b/components/camel-lucene/src/main/docs/lucene.adoc new file mode 100644 index 0000000..f27e07e --- /dev/null +++ b/components/camel-lucene/src/main/docs/lucene.adoc @@ -0,0 +1,238 @@ +[[Lucene-LuceneIndexerandSearchComponent]] +Lucene (Indexer and Search) Component +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +*Available as of Camel 2.2* + +The *lucene* component is based on the Apache Lucene project. Apache +Lucene is a powerful high-performance, full-featured text search engine +library written entirely in Java. For more details about Lucene, please +see the following links + +* http://lucene.apache.org/java/docs/[http://lucene.apache.org/java/docs/] +* http://lucene.apache.org/java/docs/features.html[http://lucene.apache.org/java/docs/features.html] + +The lucene component in camel facilitates integration and utilization of +Lucene endpoints in enterprise integration patterns and scenarios. The +lucene component does the following + +* builds a searchable index of documents when payloads are sent to the +Lucene Endpoint +* facilitates performing of indexed searches in Camel + +This component only supports producer endpoints. + +Maven users will need to add the following dependency to their `pom.xml` +for this component: + +[source,xml] +------------------------------------------------------------ +<dependency> + <groupId>org.apache.camel</groupId> + <artifactId>camel-lucene</artifactId> + <version>x.x.x</version> + <!-- use the same version as your Camel core version --> +</dependency> +------------------------------------------------------------ + +[[Lucene-URIformat]] +URI format +^^^^^^^^^^ + +[source,java] +------------------------------------ +lucene:searcherName:insert[?options] +lucene:searcherName:query[?options] +------------------------------------ + +You can append query options to the URI in the following format, +`?option=value&option=value&...` + +[[Lucene-InsertOptions]] +Insert Options +^^^^^^^^^^^^^^ + + +// component options: START +The Lucene component supports 1 options which are listed below. + + + +[width="100%",cols="2s,1m,8",options="header"] +|======================================================================= +| Name | Java Type | Description +| config | LuceneConfiguration | To use a shared lucene configuration +|======================================================================= +// component options: END + + + +// endpoint options: START +The Lucene component supports 8 endpoint options which are listed below: + +[width="100%",cols="2s,1,1m,1m,5",options="header"] +|======================================================================= +| Name | Group | Default | Java Type | Description +| host | producer | | String | *Required* The URL to the lucene server +| operation | producer | | LuceneOperation | *Required* Operation to do such as insert or query. +| analyzer | producer | | Analyzer | An Analyzer builds TokenStreams which analyze text. It thus represents a policy for extracting index terms from text. The value for analyzer can be any class that extends the abstract class org.apache.lucene.analysis.Analyzer. Lucene also offers a rich set of analyzers out of the box +| indexDir | producer | | File | A file system directory in which index files are created upon analysis of the document by the specified analyzer +| maxHits | producer | | int | An integer value that limits the result set of the search operation +| srcDir | producer | | File | An optional directory containing files to be used to be analyzed and added to the index at producer startup. +| exchangePattern | advanced | InOnly | ExchangePattern | Sets the default exchange pattern when creating an exchange +| synchronous | advanced | false | boolean | Sets whether synchronous processing should be strictly used or Camel is allowed to use asynchronous processing (if supported). +|======================================================================= +// endpoint options: END + + +[[Lucene-Sending/ReceivingMessagestoFromthecache]] +Sending/Receiving Messages to/from the cache +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +[[Lucene-MessageHeaders]] +Message Headers ++++++++++++++++ + +[width="100%",cols="10%,90%",options="header",] +|======================================================================= +|Header |Description + +|`QUERY` |The Lucene Query to performed on the index. The query may include +wildcards and phrases + +|`RETURN_LUCENE_DOCS` | *Camel 2.15:* Set this header to true to include the actual Lucene +documentation when returning hit information. +|======================================================================= + +[[Lucene-LuceneProducers]] +Lucene Producers +++++++++++++++++ + +This component supports 2 producer endpoints. + +*insert* - The insert producer builds a searchable index by analyzing +the body in incoming exchanges and associating it with a token +("content"). +*query* - The query producer performs searches on a pre-created index. +The query uses the searchable index to perform score & relevance based +searches. Queries are sent via the incoming exchange contains a header +property name called 'QUERY'. The value of the header property 'QUERY' +is a Lucene Query. For more details on how to create Lucene Queries +check out http://lucene.apache.org/java/3_0_0/queryparsersyntax.html[http://lucene.apache.org/java/3_0_0/queryparsersyntax.html] + +[[Lucene-LuceneProcessor]] +Lucene Processor +++++++++++++++++ + +There is a processor called LuceneQueryProcessor available to perform +queries against lucene without the need to create a producer. + +[[Lucene-LuceneUsageSamples]] +Lucene Usage Samples +^^^^^^^^^^^^^^^^^^^^ + +[[Lucene-Example1:CreatingaLuceneindex]] +Example 1: Creating a Lucene index +++++++++++++++++++++++++++++++++++ + +[source,java] +------------------------------------------------------------------------------------ +RouteBuilder builder = new RouteBuilder() { + public void configure() { + from("direct:start"). + to("lucene:whitespaceQuotesIndex:insert? + analyzer=#whitespaceAnalyzer&indexDir=#whitespace&srcDir=#load_dir"). + to("mock:result"); + } +}; +------------------------------------------------------------------------------------ + +[[Lucene-Example2:LoadingpropertiesintotheJNDIregistryintheCamelContext]] +Example 2: Loading properties into the JNDI registry in the Camel Context ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +[source,java] +----------------------------------------------------------------- +@Override +protected JndiRegistry createRegistry() throws Exception { + JndiRegistry registry = + new JndiRegistry(createJndiContext()); + registry.bind("whitespace", new File("./whitespaceIndexDir")); + registry.bind("load_dir", + new File("src/test/resources/sources")); + registry.bind("whitespaceAnalyzer", + new WhitespaceAnalyzer()); + return registry; +} +... +CamelContext context = new DefaultCamelContext(createRegistry()); +----------------------------------------------------------------- + +[[Lucene-Example2:PerformingsearchesusingaQueryProducer]] +Example 2: Performing searches using a Query Producer ++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +[source,java] +---------------------------------------------------------------------------------------------------- +RouteBuilder builder = new RouteBuilder() { + public void configure() { + from("direct:start"). + setHeader("QUERY", constant("Seinfeld")). + to("lucene:searchIndex:query? + analyzer=#whitespaceAnalyzer&indexDir=#whitespace&maxHits=20"). + to("direct:next"); + + from("direct:next").process(new Processor() { + public void process(Exchange exchange) throws Exception { + Hits hits = exchange.getIn().getBody(Hits.class); + printResults(hits); + } + + private void printResults(Hits hits) { + LOG.debug("Number of hits: " + hits.getNumberOfHits()); + for (int i = 0; i < hits.getNumberOfHits(); i++) { + LOG.debug("Hit " + i + " Index Location:" + hits.getHit().get(i).getHitLocation()); + LOG.debug("Hit " + i + " Score:" + hits.getHit().get(i).getScore()); + LOG.debug("Hit " + i + " Data:" + hits.getHit().get(i).getData()); + } + } + }).to("mock:searchResult"); + } +}; +---------------------------------------------------------------------------------------------------- + +[[Lucene-Example3:PerformingsearchesusingaQueryProcessor]] +Example 3: Performing searches using a Query Processor +++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +[source,java] +------------------------------------------------------------------------------------------------------- +RouteBuilder builder = new RouteBuilder() { + public void configure() { + try { + from("direct:start"). + setHeader("QUERY", constant("Rodney Dangerfield")). + process(new LuceneQueryProcessor("target/stdindexDir", analyzer, null, 20)). + to("direct:next"); + } catch (Exception e) { + e.printStackTrace(); + } + + from("direct:next").process(new Processor() { + public void process(Exchange exchange) throws Exception { + Hits hits = exchange.getIn().getBody(Hits.class); + printResults(hits); + } + + private void printResults(Hits hits) { + LOG.debug("Number of hits: " + hits.getNumberOfHits()); + for (int i = 0; i < hits.getNumberOfHits(); i++) { + LOG.debug("Hit " + i + " Index Location:" + hits.getHit().get(i).getHitLocation()); + LOG.debug("Hit " + i + " Score:" + hits.getHit().get(i).getScore()); + LOG.debug("Hit " + i + " Data:" + hits.getHit().get(i).getData()); + } + } + }).to("mock:searchResult"); + } +}; +------------------------------------------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/0ff88495/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 5cad8b7..370cac5 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -183,6 +183,7 @@ * [Kura](kura.adoc) * [LDAP](ldap.adoc) * [LevelDB](leveldb.adoc) + * [Lucene](lucene.adoc) * [Metrics](metrics.adoc) * [Mock](mock.adoc) * [NATS](nats.adoc)
