You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-commits@db.apache.org by ch...@apache.org on 2014/05/20 17:30:09 UTC
svn commit: r1596291 - in /db/derby/docs/trunk/src/tools: derbytools.ditamap
rtoolsoptlucene.dita rtoolsoptlucenecreate.dita rtoolsoptlucenedrop.dita
rtoolsoptlucenelist.dita rtoolsoptlucenequery.dita
rtoolsoptlucenesecman.dita rtoolsoptluceneupdate.dita
Author: chaase3
Date: Tue May 20 15:30:08 2014
New Revision: 1596291
URL: http://svn.apache.org/r1596291
Log:
DERBY-6564 Document the experimental, optional LuceneSupport tool.
Added 7 new topics to the Tools Guide and modified the map file.
Patches: DERBY-6564-2.diff
Added:
db/derby/docs/trunk/src/tools/rtoolsoptlucene.dita (with props)
db/derby/docs/trunk/src/tools/rtoolsoptlucenecreate.dita (with props)
db/derby/docs/trunk/src/tools/rtoolsoptlucenedrop.dita (with props)
db/derby/docs/trunk/src/tools/rtoolsoptlucenelist.dita (with props)
db/derby/docs/trunk/src/tools/rtoolsoptlucenequery.dita (with props)
db/derby/docs/trunk/src/tools/rtoolsoptlucenesecman.dita (with props)
db/derby/docs/trunk/src/tools/rtoolsoptluceneupdate.dita (with props)
Modified:
db/derby/docs/trunk/src/tools/derbytools.ditamap
Modified: db/derby/docs/trunk/src/tools/derbytools.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tools/derbytools.ditamap?rev=1596291&r1=1596290&r2=1596291&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tools/derbytools.ditamap (original)
+++ db/derby/docs/trunk/src/tools/derbytools.ditamap Tue May 20 15:30:08 2014
@@ -201,6 +201,14 @@ limitations under the License.
<topicref collection-type="family" href="ctoolsopttools.dita" navtitle="Optional tools">
<topicref href="rtoolsoptdbmetadata.dita" navtitle="Using the databaseMetaData optional tool"></topicref>
<topicref href="rtoolsoptforeignviews.dita" navtitle="Using the foreignViews optional tool"></topicref>
+<topicref collection-type="family" href="rtoolsoptlucene.dita" navtitle="Using the luceneSupport optional tool">
+<topicref href="rtoolsoptlucenecreate.dita" navtitle="Creating an index"/>
+<topicref href="rtoolsoptluceneupdate.dita" navtitle="Updating an index"/>
+<topicref href="rtoolsoptlucenequery.dita" navtitle="Querying an index"/>
+<topicref href="rtoolsoptlucenedrop.dita" navtitle="Dropping an index"/>
+<topicref href="rtoolsoptlucenelist.dita" navtitle="Listing indexes"/>
+<topicref href="rtoolsoptlucenesecman.dita" navtitle="Running the luceneSupport tool with a security manager"/>
+</topicref>
</topicref>
<topicref href="rtoolstrademderby.dita" navtitle="Trademarks"></topicref>
</map>
Added: db/derby/docs/trunk/src/tools/rtoolsoptlucene.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tools/rtoolsoptlucene.dita?rev=1596291&view=auto
==============================================================================
--- db/derby/docs/trunk/src/tools/rtoolsoptlucene.dita (added)
+++ db/derby/docs/trunk/src/tools/rtoolsoptlucene.dita Tue May 20 15:30:08 2014
@@ -0,0 +1,154 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+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.
+-->
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
+<reference id="rtoolsoptlucene" xml:lang="en-us">
+<title>Using the luceneSupport optional tool</title>
+<shortdesc>The <codeph>luceneSupport</codeph> plugin is an optional tool that
+lets you use Apache Lucene to perform full-text indexing and searching of the
+contents of <ph conref="../conrefs.dita#prod/productshortname"></ph> text
+columns.</shortdesc>
+<prolog><metadata>
+<keywords>
+<indexterm>optional tools<indexterm>luceneSupport</indexterm></indexterm>
+<indexterm>luceneSupport optional tool</indexterm>
+<indexterm>tools<indexterm>luceneSupport optional tool</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section>
+<p>The mainline API documentation for Apache Lucene at <xref format="html"
+href="https://builds.apache.org/job/Lucene-Artifacts-trunk/javadoc/"
+scope="external"/> is a useful starting point for understanding Lucene's
+capabilities.</p>
+</section>
+<section><title>Terminology</title>
+<p>The following concepts are important to an understanding of the
+<codeph>luceneSupport</codeph> plugin.</p>
+<ul>
+<li><b>Analyzer</b>: An analyzer is an implementation of
+<codeph>org.apache.lucene.analysis.Analyzer</codeph>. It extracts indexable
+terms from a block of text. The same analyzer should be used to index the text
+and to query it. An analyzer may perform language-specific tasks such as
+<i>stemming</i> and <i>filtering</i>. More information on analyzers can be found
+in the Lucene API documentation. Users can extend the existing Lucene analyzers
+or write their own custom analyzers.</li>
+<li><b>Filtering</b>: Filtering is the language-specific task of throwing away
+insignificant words such as articles and conjunctions.</li>
+<li><b>Query-parsing</b>: Query-parsing is the process of interpreting a Lucene
+query string. Lucene has its own <xref format="html"
+href="https://builds.apache.org/job/Lucene-Artifacts-trunk/javadoc/queryparser/org/apache/lucene/queryparser/classic/package-summary.html#package_description"
+scope="external">query language</xref>. By extending the default Lucene
+<codeph>QueryParser</codeph> class, users can enhance the Lucene query language
+or replace it with some other query language.</li>
+<li><b>Score</b>: The score measures how well a query matches a block of text
+(a text column value). The higher the score, the better the match. The score is
+a float value. There is no minimum or maximum value.</li>
+<li><b>Stemming</b>: Stemming is the language-specific task of reducing related
+words to their common root. For instance, an English stemmer might map all of
+the following words onto the common root "house": "house", "houses", "housed",
+and "housing".</li>
+</ul>
+</section>
+<section><title>Classpath for running the luceneSupport optional tool</title>
+<p>Before you run the <codeph>luceneSupport</codeph> optional tool, make sure
+that your classpath contains the following jar files:</p>
+<ul>
+<li><codeph>derby.jar</codeph></li>
+<li><codeph>derbyoptionaltools.jar</codeph></li>
+<li><codeph>core</codeph>: The core Lucene machinery. For Lucene 4.5.0, this is
+<codeph>lucene-core-4.5.0.jar</codeph>.</li>
+<li><codeph>analyzers-common</codeph>: The common Lucene analyzers. For
+Lucene 4.5.0, this is <codeph>lucene-analyzers-common-4.5.0.jar</codeph>.</li>
+<li><codeph>queryparser</codeph>: The basic Lucene logic for query-parsing. For
+Lucene 4.5.0, this is <codeph>lucene-queryparser-4.5.0.jar</codeph>.</li>
+</ul>
+<p>The Lucene jar files are included in the
+<ph conref="../conrefs.dita#prod/productshortname"></ph> source tree;
+alternatively, you can download them from
+<xref format="html" href="http://lucene.apache.org/" scope="external"/>.</p>
+</section>
+<section><title>Loading and unloading the luceneSupport optional tool</title>
+<p>In a database protected by SQL authorization, only the database owner can
+issue the commands which load and unload the Lucene plugin. (See
+"Database Owner" in the <i>Derby Security Guide</i> for more
+information.)</p>
+<p>Loading the plugin looks very much like loading any other optional tool. You
+call the <codeph>SYSCS_UTIL.SYSCS_REGISTER_TOOL</codeph> system procedure in
+a statement like the following:</p>
+<codeblock><b>call syscs_util.syscs_register_tool( 'luceneSupport', true );</b></codeblock>
+<p>This command creates the <codeph>LUCENESUPPORT</codeph> schema, which
+contains the following objects:</p>
+<ul>
+<li><codeph>CREATEINDEX</codeph>: A database procedure for indexing
+<ph conref="../conrefs.dita#prod/productshortname"></ph> text columns. See
+<xref href="rtoolsoptlucenecreate.dita"/> for details.</li>
+<li><codeph>UPDATEINDEX</codeph>: A database procedure for refreshing an index
+built by <codeph>CREATEINDEX</codeph>. See
+<xref href="rtoolsoptluceneupdate.dita"/> for details.</li>
+<li><codeph>DROPINDEX</codeph>: A database procedure for dropping an index built
+by <codeph>CREATEINDEX</codeph>. See <xref href="rtoolsoptlucenedrop.dita"/> for
+details.</li>
+<li><codeph>LISTINDEXES</codeph>: A table function for listing the indexes
+created by <codeph>CREATEINDEX</codeph>. See
+<xref href="rtoolsoptlucenelist.dita"/> for details.</li>
+</ul>
+<p>Removing the plugin also looks much like unloading other optional tools. Call
+the <codeph>SYSCS_UTIL.SYSCS_REGISTER_TOOL</codeph> system procedure in a
+statement like the following:</p>
+<codeblock><b>call syscs_util.syscs_register_tool( 'luceneSupport', false );</b></codeblock>
+<p>This command does the following:</p>
+<ul>
+<li><b>Drops Lucene directories</b>: Deletes the directories which were created
+to hold the Lucene indexes</li>
+<li><b>Drops schema objects</b>: Drops all schema objects created by
+<codeph>CREATEINDEX</codeph> commands</li>
+<li><b>Drops <codeph>LUCENESUPPORT</codeph></b>: Drops the
+<codeph>LUCENESUPPORT</codeph> schema and all schema objects which it
+contains</li>
+</ul>
+<p>See the <ph conref="../conrefs.dita#pub/citref"></ph> for information about
+the <codeph>SYSCS_UTIL.SYSCS_REGISTER_TOOL</codeph> system procedure.</p>
+</section>
+<section><title>Encryption and the luceneSupport tool</title>
+<p>The <codeph>luceneSupport</codeph> tool may not be used on an encrypted
+database. Users who need full-text indexing of encrypted data should store the
+database in an encrypted directory or on an encrypted device.</p>
+</section>
+<section><title>Lucene versions</title>
+<p>The <ph conref="../conrefs.dita#prod/productshortname"></ph> community has
+tested the <codeph>luceneSupport</codeph> tool against the following versions of
+Lucene. Other versions of Lucene may or may not work.</p>
+<ul>
+<li>4.5.0</li>
+<li>4.7.1</li>
+</ul>
+<p><ph conref="../conrefs.dita#prod/productshortname"></ph> cannot make any
+guarantees about the compatibility of two different versions of Lucene. Users
+should bear the following in mind:</p>
+<ul>
+<li><b>No time travel</b>: <ph conref="../conrefs.dita#prod/productshortname"></ph>
+will raise an error if you try to use an earlier version of Lucene to read an
+index created by a later version of Lucene.</li>
+<li><b>Bounce your indexes</b>: When you change versions of Lucene, it is always
+safest to call <codeph>LUCENESUPPORT.UPDATEINDEX</codeph> on all of your
+existing Lucene indexes (see <xref href="rtoolsoptluceneupdate.dita"/>).</li>
+</ul>
+</section>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/tools/rtoolsoptlucene.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/tools/rtoolsoptlucenecreate.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tools/rtoolsoptlucenecreate.dita?rev=1596291&view=auto
==============================================================================
--- db/derby/docs/trunk/src/tools/rtoolsoptlucenecreate.dita (added)
+++ db/derby/docs/trunk/src/tools/rtoolsoptlucenecreate.dita Tue May 20 15:30:08 2014
@@ -0,0 +1,237 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+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.
+-->
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
+<reference id="rtoolsoptlucenecreate" xml:lang="en-us">
+<title>Creating an index</title>
+<shortdesc>The <codeph>luceneSupport</codeph> optional tool lets you use Apache
+Lucene to perform full-text indexing and searching of the contents of
+<ph conref="../conrefs.dita#prod/productshortname"></ph> text
+columns.</shortdesc>
+<prolog><metadata>
+<keywords>
+<indexterm>luceneSupport optional tool<indexterm>creating an index</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section>
+<p>After the <codeph>luceneSupport</codeph> tool has been loaded, a user can
+index a text column in a table or view which that user owns. If SQL
+authorization is enabled, then the database owner is the only account which can
+index a text column in another user's table. The following procedure makes this
+possible:</p>
+<codeblock>LUCENESUPPORT.CREATEINDEX
+(
+ SCHEMANAME VARCHAR( 128 ),
+ TABLENAME VARCHAR( 128 ),
+ TEXTCOLUMN VARCHAR( 128 ),
+ ANALYZERMAKER VARCHAR( 32672 ),
+ KEYCOLUMNS VARCHAR( 32672 ) ...
+)</codeblock>
+<p>The procedure parameters are as follows:</p>
+<ul>
+<li><codeph>SCHEMANAME</codeph>: The SQL identifier of the schema which holds
+the table or view. This argument is case-insensitive unless you double-quote
+it.</li>
+<li><codeph>TABLENAME</codeph>: The SQL identifier of the table or view (also
+case-insensitive).</li>
+<li><codeph>TEXTCOLUMN</codeph>: The SQL identifier of the text column being
+indexed (also case-insensitive). The column must have a character datatype.</li>
+<li><codeph>ANALYZERMAKER</codeph>: If the argument is not null, this is the
+full name of a zero-argument static, public method which creates an analyzer. If
+the argument is null, the index is created via the default analyzer maker,
+<codeph>org.apache.derby.optional.api.LuceneUtils.defaultAnalyzer</codeph>. The
+default analyzer maker attempts to find a Lucene-supplied analyzer matching the
+default language of the database. Matches are found for the languages listed in
+the following table. Note that the Chinese analyzer was deprecated, so for
+Chinese, the plugin uses the <codeph>StandardAnalyzer</codeph> instead.
+<table frame="all">
+<title>Language codes supported by the Lucene plugin</title>
+<desc>This table lists the languages and corresponding language codes supported by the Lucene plugin.</desc>
+<tgroup cols="2" colsep="1" rowsep="1">
+<colspec colname="1" colnum="1" colwidth="75*"/>
+<colspec colname="2" colnum="2" colwidth="25*"/>
+<thead>
+<row valign="bottom">
+<entry colname="1">Language</entry>
+<entry colname="2">Language Code</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry colname="1">Arabic</entry>
+<entry colname="2"><codeph>ar</codeph></entry>
+</row>
+<row>
+<entry colname="1">Armenian</entry>
+<entry colname="2"><codeph>hy</codeph></entry>
+</row>
+<row>
+<entry colname="1">Basque</entry>
+<entry colname="2"><codeph>eu</codeph></entry>
+</row>
+<row>
+<entry colname="1">Brazilian</entry>
+<entry colname="2"><codeph>br</codeph></entry>
+</row>
+<row>
+<entry colname="1">Bulgarian</entry>
+<entry colname="2"><codeph>bg</codeph></entry>
+</row>
+<row>
+<entry colname="1">Catalan</entry>
+<entry colname="2"><codeph>ca</codeph></entry>
+</row>
+<row>
+<entry colname="1">Czech</entry>
+<entry colname="2"><codeph>cz</codeph></entry>
+</row>
+<row>
+<entry colname="1">Danish</entry>
+<entry colname="2"><codeph>da</codeph></entry>
+</row>
+<row>
+<entry colname="1">Dutch</entry>
+<entry colname="2"><codeph>nl</codeph></entry>
+</row>
+<row>
+<entry colname="1">English</entry>
+<entry colname="2"><codeph>en</codeph></entry>
+</row>
+<row>
+<entry colname="1">Finnish</entry>
+<entry colname="2"><codeph>fi</codeph></entry>
+</row>
+<row>
+<entry colname="1">French</entry>
+<entry colname="2"><codeph>fr</codeph></entry>
+</row>
+<row>
+<entry colname="1">Galician</entry>
+<entry colname="2"><codeph>gl</codeph></entry>
+</row>
+<row>
+<entry colname="1">German</entry>
+<entry colname="2"><codeph>de</codeph></entry>
+</row>
+<row>
+<entry colname="1">Greek</entry>
+<entry colname="2"><codeph>el</codeph></entry>
+</row>
+<row>
+<entry colname="1">Hindi</entry>
+<entry colname="2"><codeph>hi</codeph></entry>
+</row>
+<row>
+<entry colname="1">Hungarian</entry>
+<entry colname="2"><codeph>hu</codeph></entry>
+</row>
+<row>
+<entry colname="1">Indonesian</entry>
+<entry colname="2"><codeph>id</codeph></entry>
+</row>
+<row>
+<entry colname="1">Irish</entry>
+<entry colname="2"><codeph>ga</codeph></entry>
+</row>
+<row>
+<entry colname="1">Italian</entry>
+<entry colname="2"><codeph>it</codeph></entry>
+</row>
+<row>
+<entry colname="1">Latvian</entry>
+<entry colname="2"><codeph>lv</codeph></entry>
+</row>
+<row>
+<entry colname="1">Norwegian</entry>
+<entry colname="2"><codeph>no</codeph></entry>
+</row>
+<row>
+<entry colname="1">Persian</entry>
+<entry colname="2"><codeph>fa</codeph></entry>
+</row>
+<row>
+<entry colname="1">Portuguese</entry>
+<entry colname="2"><codeph>pt</codeph></entry>
+</row>
+<row>
+<entry colname="1">Romanian</entry>
+<entry colname="2"><codeph>ro</codeph></entry>
+</row>
+<row>
+<entry colname="1">Russian</entry>
+<entry colname="2"><codeph>ru</codeph></entry>
+</row>
+<row>
+<entry colname="1">Spanish</entry>
+<entry colname="2"><codeph>es</codeph></entry>
+</row>
+<row>
+<entry colname="1">Swedish</entry>
+<entry colname="2"><codeph>sv</codeph></entry>
+</row>
+<row>
+<entry colname="1">Thai</entry>
+<entry colname="2"><codeph>th</codeph></entry>
+</row>
+<row>
+<entry colname="1">Turkish</entry>
+<entry colname="2"><codeph>tr</codeph></entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+<p><ph conref="../conrefs.dita#prod/productshortname"></ph> supplies another
+utility method which instantiates the default Lucene analyzer; this utility
+method is called
+<codeph>org.apache.derby.optional.api.LuceneUtils.standardAnalyzer</codeph>, and
+it materializes an
+<codeph>org.apache.lucene.analysis.standard.StandardAnalyzer</codeph>.</p></li>
+<li><codeph>KEYCOLUMNS</codeph>: This is an optional list of SQL identifiers for
+other columns in the table or view. The values of these columns are stored in
+the text index for use in joining Lucene results back to the original data. If
+the <codeph>KEYCOLUMNS</codeph> are omitted, <codeph>TABLENAME</codeph> must
+identify a base table with a primary key; in this case, the whole primary key is
+stored in the text index for joining later.</li>
+</ul>
+<p>The keys and the text column cannot have the following names:</p>
+<ul>
+<li><codeph>DOCUMENTID</codeph></li>
+<li><codeph>SCORE</codeph></li>
+</ul>
+<p><codeph>CREATEINDEX</codeph> creates a table function named
+<codeph>$TABLENAME__$TEXTCOLUMN</codeph> in the <codeph>$SCHEMANAME</codeph>
+schema. <xref href="rtoolsoptlucenequery.dita"/> describes this table function in
+greater detail.</p>
+</section>
+<section><title>Example</title>
+<codeblock><b>-- index the POEMTEXT column of the POEMS table,
+-- using its primary key and the default, locale-sensitive analyzer
+CALL LUCENESUPPORT.CREATEINDEX( 'ruth', 'poems', 'poemText', null );
+
+-- index the POEMVIEW view, using POEMID and VERSIONSTAMP as keys
+-- and Lucene's StandardAnalyzer
+CALL LUCENESUPPORT.CREATEINDEX
+(
+ 'ruth', 'poemView', 'poemText',
+ 'org.apache.derby.optional.api.LuceneUtils.standardAnalyzer',
+ 'poemID', 'versionStamp'
+);</b></codeblock>
+</section>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/tools/rtoolsoptlucenecreate.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/tools/rtoolsoptlucenedrop.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tools/rtoolsoptlucenedrop.dita?rev=1596291&view=auto
==============================================================================
--- db/derby/docs/trunk/src/tools/rtoolsoptlucenedrop.dita (added)
+++ db/derby/docs/trunk/src/tools/rtoolsoptlucenedrop.dita Tue May 20 15:30:08 2014
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+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.
+-->
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
+<reference id="rtoolsoptlucenedrop" xml:lang="en-us">
+<title>Dropping an index</title>
+<shortdesc>A Lucene index can be dropped by the table owner.</shortdesc>
+<prolog><metadata>
+<keywords>
+<indexterm>luceneSupport optional tool<indexterm>dropping an index</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section>
+<p>If SQL authorization is enabled, the database owner is the only account which
+can drop an index on another user's table. The following procedure makes this
+possible:</p>
+<codeblock>LUCENESUPPORT.DROPINDEX
+(
+ SCHEMANAME VARCHAR( 128 ),
+ TABLENAME VARCHAR( 128 ),
+ TEXTCOLUMN VARCHAR( 128 )
+)</codeblock>
+<p>The arguments are the same as those for <codeph>CREATEINDEX</codeph>. See
+<xref href="rtoolsoptlucenecreate.dita"/> for details.</p>
+</section>
+<section><title>Example</title>
+<codeblock><b>-- drop an index
+CALL LUCENESUPPORT.DROPINDEX
+(
+ 'ruth', 'poemView', 'poemText'
+);</b></codeblock>
+</section>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/tools/rtoolsoptlucenedrop.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/tools/rtoolsoptlucenelist.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tools/rtoolsoptlucenelist.dita?rev=1596291&view=auto
==============================================================================
--- db/derby/docs/trunk/src/tools/rtoolsoptlucenelist.dita (added)
+++ db/derby/docs/trunk/src/tools/rtoolsoptlucenelist.dita Tue May 20 15:30:08 2014
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+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.
+-->
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
+<reference id="rtoolsoptlucenelist" xml:lang="en-us">
+<title>Listing indexes</title>
+<shortdesc>You can use a table function to list all Lucene indexes.</shortdesc>
+<prolog><metadata>
+<keywords>
+<indexterm>luceneSupport optional tool<indexterm>listing indexes</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section>
+<p>After the <codeph>luceneSupport</codeph> tool has been loaded, anyone can
+list the Lucene indexes by selecting from the following table function:</p>
+<codeblock>LUCENESCHEMA.LISTINDEXES()
+RETURNS TABLE
+(
+ SCHEMANAME VARCHAR( 128 ),
+ TABLENAME VARCHAR( 128 ),
+ COLUMNNAME VARCHAR( 128 ),
+ LASTUPDATED TIMESTAMP,
+ LUCENEVERSION VARCHAR( 20 ),
+ ANALYZER VARCHAR( 32672 ),
+ ANALYZYERMAKER VARCHAR( 32672 )
+)</codeblock>
+</section>
+<section><title>Example</title>
+<codeblock><b> -- list all the indexes
+ SELECT * FROM TABLE( LUCENESCHEMA.LISTINDEXES ) T;</b></codeblock>
+</section>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/tools/rtoolsoptlucenelist.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/tools/rtoolsoptlucenequery.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tools/rtoolsoptlucenequery.dita?rev=1596291&view=auto
==============================================================================
--- db/derby/docs/trunk/src/tools/rtoolsoptlucenequery.dita (added)
+++ db/derby/docs/trunk/src/tools/rtoolsoptlucenequery.dita Tue May 20 15:30:08 2014
@@ -0,0 +1,133 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+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.
+-->
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
+<reference id="rtoolsoptlucenequery" xml:lang="en-us">
+<title>Querying an index</title>
+<shortdesc>To query an index, use the table function created by
+<codeph>CREATEINDEX</codeph>.</shortdesc>
+<prolog><metadata>
+<keywords>
+<indexterm>luceneSupport optional tool<indexterm>querying an index</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section>
+<p>The table function created by <codeph>CREATEINDEX</codeph> has the following
+shape:</p>
+<codeblock>$SCHEMANAME.$TABLENAME__TEXTCOL
+(
+ QUERY VARCHAR( 32672 ),
+ QUERYPARSERMAKER VARCHAR( 32672 ),
+ WINDOWSIZE INT,
+ SCORECEILING REAL
+)
+RETURNS TABLE
+(
+ $keyColumn1 $keyColumn1datatype,
+ ...
+ $keyColumnN $keyColumnNdatatype,
+ DOCUMENTID INT,
+ SCORE REAL
+)</codeblock>
+<p>The arguments have the following meaning:</p>
+<ul>
+<li><codeph>QUERY</codeph>: This is the Lucene query text. For more information, see the
+description of the <xref format="html"
+href="https://builds.apache.org/job/Lucene-Artifacts-trunk/javadoc/queryparser/org/apache/lucene/queryparser/classic/package-summary.html#package_description"
+scope="external">Lucene query language</xref>.</li>
+<li><codeph>QUERYPARSERMAKER</codeph>: This argument provides directions for query-parsing
+the <codeph>QUERY</codeph>. If the argument is not null, it is the name of a
+public, static method with the following signature:
+<codeblock>org.apache.lucene.queryparser.classic.QueryParser $methodName
+(
+ org.apache.lucene.util.Version version,
+ java.lang.String fieldName,
+ org.apache.lucene.analysis.Analyzer analyzer
+)</codeblock>
+<p>If the argument is null, query-parsing is performed by the default Lucene
+<codeph>QueryParser</codeph>.</p></li>
+<li><codeph>WINDOWSIZE</codeph>: This is the maximum number of rows (matches) to
+return.</li>
+<li><codeph>SCORECEILING</codeph>: This causes Lucene to return only rows whose
+score is less than this number. <codeph>WINDOWSIZE</codeph> and
+<codeph>SCORECEILING</codeph> are the variables which Lucene uses to process a
+result into windows. See the example below. A value of NULL means "return the
+best WINDOWSIZE matches".</li>
+</ul>
+<p>In the returned result set, the key columns join back to the original table
+or view, and they identify which row of that table/view holds the scored text.
+The other columns in the returned result set have the following meanings:</p>
+<ul>
+<li><codeph>DOCUMENTID</codeph>: This is a Lucene-generated number which may be
+useful for debugging Lucene-related issues. This number has no meaning to
+<ph conref="../conrefs.dita#prod/productshortname"></ph> or to the end
+user.</li>
+<li><codeph>SCORE</codeph>: This value measures how well Lucene thought the
+column fit the query. A higher score means a better fit.</li>
+</ul>
+<p><ph conref="../conrefs.dita#prod/productshortname"></ph> uses the same
+analyzer to query the index that was last used to create or update the
+index.</p>
+</section>
+<section><title>Example</title>
+<codeblock><b>-- Selects the primary key and score for the best 3 matches for
+-- the text.
+select presidentID, speechID, score
+from table
+(
+ us.presidentsSpeeches__speechText
+ (
+ 'When in the course of human events',
+ null,
+ 3,
+ null
+ )
+) t;
+
+-- The last row in the previous result had score 1.0.
+-- This selects the primary key and score for the next 4 matches for the
+-- text.
+select presidentID, speechID, score
+from table
+(
+ us.presidentsSpeeches__speechText
+ (
+ 'When in the course of human events',
+ null,
+ 4,
+ 1.0
+ )
+) t;
+
+-- Selects the primary key and score for the best 100 matches, given a
+-- custom query language.
+select presidentID, speechID, score
+from table
+(
+ us.presidentsSpeeches__speechText, score
+ (
+ 'When AND course AND human AND events',
+ 'com.mytools.MyQueryLanguage.MyQueryParser.create',
+ 100,
+ null
+ )
+) t;</b></codeblock>
+</section>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/tools/rtoolsoptlucenequery.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/tools/rtoolsoptlucenesecman.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tools/rtoolsoptlucenesecman.dita?rev=1596291&view=auto
==============================================================================
--- db/derby/docs/trunk/src/tools/rtoolsoptlucenesecman.dita (added)
+++ db/derby/docs/trunk/src/tools/rtoolsoptlucenesecman.dita Tue May 20 15:30:08 2014
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+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.
+-->
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
+<reference id="rtoolsoptlucenesecman" xml:lang="en-us">
+<title>Running the luceneSupport tool with a security manager</title>
+<shortdesc>When you run the <codeph>luceneSupport</codeph> tool under a Java
+Security Manager, the security policy must grant privileges to two jar
+files.</shortdesc>
+<prolog><metadata>
+<keywords>
+<indexterm>luceneSupport optional tool<indexterm>running with a security manager</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section>
+<p>The following privileges must be granted to
+<codeph>derbyoptionaltools.jar</codeph> and to the core Lucene jar file:</p>
+<codeblock>//
+// Permissions for the optional tools (derbyoptionaltools.jar)
+//
+grant codeBase "${derby.install.url}derbyoptionaltools.jar"
+{
+ permission java.util.PropertyPermission "derby.system.home", "read";
+
+ // all databases under derby.system.home
+ permission java.io.FilePermission
+ "${derby.system.home}${/}${databaseName}${/}LUCENE",
+ "read,write,delete";
+ permission java.io.FilePermission
+ "${derby.system.home}${/}${databaseName}${/}LUCENE${/}-",
+ "read,write,delete";
+
+ permission java.io.FilePermission "${lucene.core.jar.file}", "read";
+ permission java.util.PropertyPermission "user.dir", "read";
+ permission java.lang.RuntimePermission "accessDeclaredMembers";
+ permission java.lang.RuntimePermission "accessClassInPackage.sun.misc";
+ permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
+};
+
+// Permissions for the Lucene plugin
+grant codeBase "${lucene.core.jar.file.url}"
+{
+ // permissions for file access, write access only to sandbox:
+ permission java.io.FilePermission
+ "${derby.system.home}${/}${databaseName}${/}LUCENE",
+ "read,write,delete";
+ permission java.io.FilePermission
+ "${derby.system.home}${/}${databaseName}${/}LUCENE${/}-",
+ "read,write,delete";
+
+ // Basic permissions needed for Lucene to work:
+ permission java.util.PropertyPermission "user.dir", "read";
+ permission java.util.PropertyPermission "sun.arch.data.model", "read";
+ permission java.lang.RuntimePermission "accessDeclaredMembers";
+ permission java.lang.RuntimePermission "accessClassInPackage.sun.misc";
+ permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
+};</codeblock>
+</section>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/tools/rtoolsoptlucenesecman.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/tools/rtoolsoptluceneupdate.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tools/rtoolsoptluceneupdate.dita?rev=1596291&view=auto
==============================================================================
--- db/derby/docs/trunk/src/tools/rtoolsoptluceneupdate.dita (added)
+++ db/derby/docs/trunk/src/tools/rtoolsoptluceneupdate.dita Tue May 20 15:30:08 2014
@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+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.
+-->
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
+<reference id="rtoolsoptluceneupdate" xml:lang="en-us">
+<title>Updating an index</title>
+<shortdesc>After an index has been created, a user can perform a bulk reindexing
+of the text column.</shortdesc>
+<prolog><metadata>
+<keywords>
+<indexterm>luceneSupport optional tool<indexterm>updating an index</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section>
+<p>If SQL authorization is enabled, the database owner is the only account which
+can reindex a text column in another user's table. The following procedure
+reindexes the column across the whole table:</p>
+<codeblock><b>LUCENESUPPORT.UPDATEINDEX
+(
+ SCHEMANAME VARCHAR( 128 ),
+ TABLENAME VARCHAR( 128 ),
+ TEXTCOLUMN VARCHAR( 128 ),
+ ANALYZERMAKER VARCHAR( 32672 )
+)</b></codeblock>
+<p>The first three arguments identify the column to be reindexed. The last
+argument lets you override how the text is broken into indexable terms.</p>
+<p>This release of the <codeph>luceneSupport</codeph> tool does not support the
+incremental reindexing of data. Updating the index is a bulk operation, which
+reindexes an entire data set. For this reason, this release of the
+<codeph>luceneSupport</codeph> tool is not appropriate for update-intensive
+applications where the results of full-text queries must be current. The
+<codeph>luceneSupport</codeph> tool is better suited to applications for which
+yesterday's full-text query results are good enough:</p>
+<ul>
+<li><b>Read-mostly</b>: Applications which analyze static text data</li>
+<li><b>Fuzzy</b>: Applications which can perform a bulk reindexing of the text
+data periodically (for example, once a day), and which can tolerate that amount
+of fuzziness in query results</li>
+</ul>
+</section>
+<section><title>Example</title>
+<codeblock><b>-- reindex a column using a custom analyzer
+CALL LUCENESUPPORT.UPDATEINDEX
+(
+ 'ruth', 'poemView', 'poemText',
+ 'com.mytools.MyAnalyzer.create',
+);</b></codeblock>
+</section></refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/tools/rtoolsoptluceneupdate.dita
------------------------------------------------------------------------------
svn:eol-style = native