You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jackrabbit.apache.org by th...@apache.org on 2018/11/09 09:44:20 UTC
svn commit: r1846222 [11/22] - in /jackrabbit/site/live/oak/docs: ./
architecture/ coldstandby/ features/ nodestore/ nodestore/document/
nodestore/segment/ oak-mongo-js/ oak_api/ plugins/ query/ security/
security/accesscontrol/ security/authentication...
Modified: jackrabbit/site/live/oak/docs/query/query-troubleshooting.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/query/query-troubleshooting.html?rev=1846222&r1=1846221&r2=1846222&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/query/query-troubleshooting.html (original)
+++ jackrabbit/site/live/oak/docs/query/query-troubleshooting.html Fri Nov 9 09:44:19 2018
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 at 2018-09-19
+ | Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2018-04-05
| Rendered using Apache Maven Fluido Skin 1.6
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20180919" />
+ <meta name="Date-Revision-yyyymmdd" content="20180405" />
<meta http-equiv="Content-Language" content="en" />
<title>Jackrabbit Oak – Query Troubleshooting</title>
<link rel="stylesheet" href="../css/apache-maven-fluido-1.6.min.css" />
@@ -52,7 +52,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Main APIs <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="http://www.day.com/specs/jcr/2.0/index.html" title="JCR API">JCR API</a></li>
- <li><a href="https://jackrabbit.apache.org/jcr/jcr-api.html" title="Jackrabbit API">Jackrabbit API</a></li>
<li><a href="../oak_api/overview.html" title="Oak API">Oak API</a></li>
</ul>
</li>
@@ -67,12 +66,7 @@
<li><a href="../nodestore/compositens.html" title="Composite NodeStore">Composite NodeStore</a></li>
</ul>
</li>
- <li class="dropdown-submenu">
-<a href="../plugins/blobstore.html" title="Blob Storage">Blob Storage</a>
- <ul class="dropdown-menu">
- <li><a href="../features/direct-binary-access.html" title="Direct Binary Access">Direct Binary Access</a></li>
- </ul>
- </li>
+ <li><a href="../plugins/blobstore.html" title="Blob Storage">Blob Storage</a></li>
<li class="dropdown-submenu">
<a href="../query/query.html" title="Query">Query</a>
<ul class="dropdown-menu">
@@ -142,7 +136,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2018-09-19<span class="divider">|</span>
+ <li id="publishDate">Last Published: 2018-04-05<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 1.10-SNAPSHOT</li>
</ul>
@@ -161,14 +155,12 @@
<li><a href="../architecture/nodestate.html" title="The Node State Model"><span class="none"></span>The Node State Model</a> </li>
<li class="nav-header">Main APIs</li>
<li><a href="http://www.day.com/specs/jcr/2.0/index.html" class="externalLink" title="JCR API"><span class="none"></span>JCR API</a> </li>
- <li><a href="https://jackrabbit.apache.org/jcr/jcr-api.html" class="externalLink" title="Jackrabbit API"><span class="none"></span>Jackrabbit API</a> </li>
<li><a href="../oak_api/overview.html" title="Oak API"><span class="none"></span>Oak API</a> </li>
<li class="nav-header">Features and Plugins</li>
<li><a href="../nodestore/overview.html" title="Node Storage"><span class="icon-chevron-down"></span>Node Storage</a>
<ul class="nav nav-list">
<li><a href="../nodestore/documentmk.html" title="Document NodeStore"><span class="icon-chevron-down"></span>Document NodeStore</a>
<ul class="nav nav-list">
- <li><a href="../nodestore/document/mongo-document-store.html" title="MongoDB DocumentStore"><span class="none"></span>MongoDB DocumentStore</a> </li>
<li><a href="../nodestore/document/node-bundling.html" title="Node Bundling"><span class="none"></span>Node Bundling</a> </li>
<li><a href="../nodestore/document/secondary-store.html" title="Secondary Store"><span class="none"></span>Secondary Store</a> </li>
<li><a href="../nodestore/persistent-cache.html" title="Persistent Cache"><span class="none"></span>Persistent Cache</a> </li>
@@ -179,11 +171,7 @@
<li><a href="../nodestore/compositens.html" title="Composite NodeStore"><span class="none"></span>Composite NodeStore</a> </li>
</ul>
</li>
- <li><a href="../plugins/blobstore.html" title="Blob Storage"><span class="icon-chevron-down"></span>Blob Storage</a>
- <ul class="nav nav-list">
- <li><a href="../features/direct-binary-access.html" title="Direct Binary Access"><span class="none"></span>Direct Binary Access</a> </li>
- </ul>
- </li>
+ <li><a href="../plugins/blobstore.html" title="Blob Storage"><span class="none"></span>Blob Storage</a> </li>
<li><a href="../query/query.html" title="Query"><span class="icon-chevron-down"></span>Query</a>
<ul class="nav nav-list">
<li><a href="../query/query-engine.html" title="Query Engine"><span class="none"></span>Query Engine</a> </li>
@@ -252,98 +240,83 @@
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.
- -->
-<div class="section">
+ --><div class="section">
<h2><a name="Query_Troubleshooting"></a>Query Troubleshooting</h2>
<div class="section">
<h3><a name="Slow_Queries"></a>Slow Queries</h3>
<p>The first step in query troubleshooting is often to detect a query is slow, or traverses many nodes. Queries that traverse many nodes are logged as follows:</p>
-<div>
-<div>
-<pre class="source">*WARN* org.apache.jackrabbit.oak.plugins.index.Cursors$TraversingCursor
+<div class="source">
+<div class="source"><pre class="prettyprint">*WARN* org.apache.jackrabbit.oak.plugins.index.Cursors$TraversingCursor
Traversed 22000 nodes with filter Filter(query=
select * from [nt:base] where isdescendantnode('/etc') and lower([jcr:title]) like '%coat%');
consider creating an index or changing the query
</pre></div></div>
-
<p>To get good performance, queries should not traverse more than about 1000 nodes (specially for queries that are run often).</p>
<div class="section">
<h4><a name="Potentially_Slow_Queries"></a>Potentially Slow Queries</h4>
<p>In addition to avoiding queries that traverse many nodes, it makes sense to avoid queries that don’t use an index. Such queries might be fast (and only traverse few nodes) with a small repository, but with a large repository they are typically slow as well. Therefore, it makes sense to detect such queries as soon as possible (in a developer environment), even before the code that runs those queries is tested with a larger repository. Oak will detect such queries and log them as follows (with log level INFO for Oak 1.6.x, and WARN for Oak 1.8.x):</p>
-<div>
-<div>
-<pre class="source">*INFO* org.apache.jackrabbit.oak.query.QueryImpl Traversal query (query without index):
+<div class="source">
+<div class="source"><pre class="prettyprint">*INFO* org.apache.jackrabbit.oak.query.QueryImpl Traversal query (query without index):
select * from [nt:base] where isdescendantnode('/etc') and lower([jcr:title]) like '%coat%';
consider creating an index
-</pre></div></div>
-</div>
+</pre></div></div></div>
<div class="section">
<h4><a name="Query_Plan"></a>Query Plan</h4>
<p>To understand why the query is slow, the first step is commonly to get the query execution plan. To do this, the query can be executed using <tt>explain select ...</tt>. For the above case, the plan is:</p>
-<div>
-<div>
-<pre class="source">[nt:base] as [nt:base] /* traverse "/etc//*"
+<div class="source">
+<div class="source"><pre class="prettyprint">[nt:base] as [nt:base] /* traverse "/etc//*"
where (isdescendantnode([nt:base], [/etc])) and (lower([nt:base].[jcr:title]) like '%coat%') */
</pre></div></div>
-
<p>That means, all nodes below <tt>/etc</tt> are traversed.</p></div>
<div class="section">
<h4><a name="Making_the_Query_More_Specific"></a>Making the Query More Specific</h4>
<p>In order to make the query faster, try to add more constraints, or make constraints tighter. This will usually require some knowledge about the expected results. For example, if the path restriction is more specific, then less nodes need to be read. This is also true if an index is used. Also, if possible use a more specific node type. To understand if a nodetype or mixin is indexed, consult the nodetype index at <tt>/oak:index/nodetype</tt>, property <tt>declaringNodeTypes</tt>. But even if this is not the case, the nodetype should be as specific as possible. Assuming the query is changed to this:</p>
-<div>
-<div>
-<pre class="source">select * from [acme:Product]
+<div class="source">
+<div class="source"><pre class="prettyprint">select * from [acme:Product]
where isdescendantnode('/etc/commerce')
and lower([jcr:title]) like '%coat%')
and [commerceType] = 'product'
</pre></div></div>
-
<p>The only <i>relevant</i> change was to improve the path restriction. But in this case, it already was enough to make the traversal warning go away.</p></div>
<div class="section">
<h4><a name="Queries_Without_Index"></a>Queries Without Index</h4>
<p>After changing the query, there is still a message in the log file that complains the query doesn’t use an index, as described above:</p>
-<div>
-<div>
-<pre class="source">*INFO* org.apache.jackrabbit.oak.query.QueryImpl
+<div class="source">
+<div class="source"><pre class="prettyprint">*INFO* org.apache.jackrabbit.oak.query.QueryImpl
Traversal query (query without index):
select * from [acme:Product] where isdescendantnode('/etc/commerce')
and lower([jcr:title]) like '%coat%'
and [commerceType] = 'product'; consider creating an index
</pre></div></div>
-
<p>The query plan of the index didn’t change, so still nodes are traversed. In this case, there are relatively few nodes because it’s an almost empty development repository, so no traversal warning is logged. But for production, there might be a lot more nodes under <tt>/etc/commerce</tt>, so it makes sense to continue optimization.</p></div>
<div class="section">
<h4><a name="Where_Traversal_is_OK"></a>Where Traversal is OK</h4>
<p>If it is known from the data model that a query will never traverse many nodes, then no index is needed. This is a corner case, and only applies to queries that traverse a fixed number of (for example) configuration nodes, or if the number of descendant nodes is guaranteed to be very low by using a certain nodetype that only allows for a fixed number of child nodes. If this is the case, then the query can be changed to say traversal is fine. To mark such queries, append <tt>option(traversal ok)</tt> to the query. This feature should only be used for those rare corner cases.</p>
-<div>
-<div>
-<pre class="source">select * from [nt:base]
+<div class="source">
+<div class="source"><pre class="prettyprint">select * from [nt:base]
where isdescendantnode('/etc/commerce')
and lower([jcr:title]) like '%coat%'
and [commerceType] = 'product'
option(traversal ok)
-</pre></div></div>
-</div>
+</pre></div></div></div>
<div class="section">
<h4><a name="aEstimating_Node_Counts"></a> Estimating Node Counts</h4>
<p>To find out how many nodes are in a certain path, you can use the JMX bean <tt>NodeCounter</tt>, which can estimate the node count. Example: run <tt>getEstimatedChildNodeCounts</tt> with <tt>p1=/</tt> and <tt>p2=2</tt> might give you:</p>
-<div>
-<div>
-<pre class="source">/: 2522208,
+<div class="source">
+<div class="source"><pre class="prettyprint">/: 2522208,
...
/etc: 1521504,
/etc/commerce: 29216,
/etc/images: 1231232,
...
</pre></div></div>
-
<p>So in this case, there are still many nodes below <tt>/etc/commerce</tt> in the production repository. Also note that the number of nodes can grow over time.</p></div>
<div class="section">
<h4><a name="aPrevent_Running_Traversal_Queries"></a> Prevent Running Traversal Queries</h4>
@@ -351,31 +324,37 @@ option(traversal ok)
<div class="section">
<h4><a name="Using_a_Different_or_New_Index"></a>Using a Different or New Index</h4>
<p>There are multiple options:</p>
-<ul>
-<li>Consider creating an index for <tt>jcr:title</tt>. But for <tt>like '%..%'</tt> conditions, this is not of much help, because all nodes with that property will need to be read. Also, using <tt>lower</tt> will make the index less effective. So, this only makes sense if there are very few nodes with this property expected to be in the system.</li>
-<li>If there are very few nodes with that nodetype, consider adding <tt>acme:Product</tt> to the nodetype index. This requires reindexing. The query could then use the nodetype index, and within this nodetype, just traverse below <tt>/etc/commerce</tt>. The <tt>NodeCounter</tt> can also help understand how many <tt>acme:Product</tt> nodes are in the repository, if this nodetype is indexed. To find out, run <tt>getEstimatedChildNodeCounts</tt> with <tt>p1=/oak:index/nodetype</tt> and <tt>p2=2</tt>.</li>
-<li>If the query needs to return added nodes immediately (synchronously; that is without delay), consider creating a <a href="./property-index.html">property index</a>. Note that Lucene indexes are asynchronous, and new nodes may not appear in the result for a few seconds.</li>
-<li>To ensure there is only one node matching the result in the repository, consider creating a unique <a href="./property-index.html">property index</a>.</li>
-<li>Consider using a fulltext index, that is: change the query from using <tt>lower([jcr:title]) like '%...%'</tt> to using <tt>contains([jcr:title], '...')</tt>. Possibly combine this with adding the property <tt>commerceType</tt> to the fulltext index.</li>
+<ul>
+
+<li>Consider creating an index for <tt>jcr:title</tt>. But for <tt>like '%..%'</tt> conditions, this is not of much help, because all nodes with that property will need to be read. Also, using <tt>lower</tt> will make the index less effective. So, this only makes sense if there are very few nodes with this property expected to be in the system.</li>
+
+<li>If there are very few nodes with that nodetype, consider adding <tt>acme:Product</tt> to the nodetype index. This requires reindexing. The query could then use the nodetype index, and within this nodetype, just traverse below <tt>/etc/commerce</tt>. The <tt>NodeCounter</tt> can also help understand how many <tt>acme:Product</tt> nodes are in the repository, if this nodetype is indexed. To find out, run <tt>getEstimatedChildNodeCounts</tt> with <tt>p1=/oak:index/nodetype</tt> and <tt>p2=2</tt>.</li>
+
+<li>If the query needs to return added nodes immediately (synchronously; that is without delay), consider creating a <a href="./property-index.html">property index</a>. Note that Lucene indexes are asynchronous, and new nodes may not appear in the result for a few seconds.</li>
+
+<li>To ensure there is only one node matching the result in the repository, consider creating a unique <a href="./property-index.html">property index</a>.</li>
+
+<li>Consider using a fulltext index, that is: change the query from using <tt>lower([jcr:title]) like '%...%'</tt> to using <tt>contains([jcr:title], '...')</tt>. Possibly combine this with adding the property <tt>commerceType</tt> to the fulltext index.</li>
</ul>
<p>The last plan is possibly the best solution for this case.</p></div>
<div class="section">
<h4><a name="Index_Definition_Generator"></a>Index Definition Generator</h4>
<p>In case you need to modify or create a Lucene property index, you can use the <a class="externalLink" href="http://oakutils.appspot.com/generate/index">Oak Index Definition Generator</a> tool.</p>
<p>As the tool doesn’t know your index configuration, it will always suggest to create a new index; it might be better to extend an existing index. However, note that:</p>
-<ul>
+<ul>
+
<li>Changing an existing index requires reindexing that index.</li>
-<li>If an out-of-the-box index is modified, you will need to merge those modifications when migrating to newer software. It is best to add documentation to the index definition to simplify merging, for example in the form of “info” properties.</li>
+
+<li>If an out-of-the-box index is modified, you will need to merge those modifications when migrating to newer software. It is best to add documentation to the index definition to simplify merging, for example in the form of “info” properties.</li>
</ul></div>
<div class="section">
<h4><a name="Verification"></a>Verification</h4>
<p>After changing the query, and possibly the index, run the <tt>explain select</tt> again, and verify the right plan is used, in this case that might be, for the query:</p>
-<div>
-<div>
-<pre class="source">select * from [acme:Product]
+<div class="source">
+<div class="source"><pre class="prettyprint">select * from [acme:Product]
where isdescendantnode('/etc/commerce')
and contains([jcr:title], 'Coat')
and [commerceType] = 'product'
@@ -383,15 +362,13 @@ and [commerceType] = 'product'
[nt:unstructured] as [acme:Product] /* lucene:lucene(/oak:index/lucene)
full:jcr:title:coat ft:(jcr:title:"Coat")
</pre></div></div>
-
<p>So in this case, only the fulltext restriction of the query was used by the index, but this might already be sufficient. If it is not, then the fulltext index might be changed to also index <tt>commerceType</tt>, or possibly to use <tt>evaluatePathRestrictions</tt>.</p></div>
<div class="section">
<h4><a name="Queries_With_Many_OR_or_UNION_Conditions"></a>Queries With Many OR or UNION Conditions</h4>
<p>Queries that contain many “or” conditions, or with many “union” subqueries, can be slow as they have to read a lot of data. Example query:</p>
-<div>
-<div>
-<pre class="source">/jcr:root/content/(a|b|c|d|e)//element(*, cq:Page)[
+<div class="source">
+<div class="source"><pre class="prettyprint">/jcr:root/content/(a|b|c|d|e)//element(*, cq:Page)[
jcr:contains(@jcr:title, 'some text')
or jcr:contains(jcr:content/@keywords, 'some text')
or jcr:contains(jcr:content/@cq:tags, 'some text')
@@ -399,46 +376,36 @@ or jcr:contains(jcr:content/@team, 'some
or jcr:contains(jcr:content/@topics, 'some text')
or jcr:contains(jcr:content/@jcr:description, 'some text')]
</pre></div></div>
-
<p>This query will be internally converted into 5 subqueries, due to the “union” clause (a|b|c|d|e). Then, each of the 5 subqueries will run 6 subqueries: one for each jcr:contains condition. So, the index will be contacted 30 times.</p>
<p>To avoid this overhead, the index could be changed (or a new index created) to do aggregation on the required properties (here: jcr:title, jcr:content/keywords,…). This will simplify the query to:</p>
-<div>
-<div>
-<pre class="source">/jcr:root/content/(a|b|c|d|e)//element(*, cq:Page)[jcr:contains(., 'some text')]
+<div class="source">
+<div class="source"><pre class="prettyprint">/jcr:root/content/(a|b|c|d|e)//element(*, cq:Page)[jcr:contains(., 'some text')]
</pre></div></div>
-
<p>This should resolve most problems. To further speed up the query by avoiding to running 5 subqueries, it might be better to use a less specific path constraint, but instead use a different way to filter results, such as:</p>
-<div>
-<div>
-<pre class="source">/jcr:root/content//element(*, cq:Page)[jcr:contains(., 'some text') and @category='x']
-</pre></div></div>
-</div>
+<div class="source">
+<div class="source"><pre class="prettyprint">/jcr:root/content//element(*, cq:Page)[jcr:contains(., 'some text') and @category='x']
+</pre></div></div></div>
<div class="section">
<h4><a name="Ordering_by_Score_Combined_With_OR__UNION_Conditions"></a>Ordering by Score Combined With OR / UNION Conditions</h4>
<p>Queries that expect results to be sorted by score (“order by @jcr:score descending”), and use “union” or “or” conditions, may not return the result in the expected order, depending on the index(es) used. Example:</p>
-<div>
-<div>
-<pre class="source">/jcr:root/conent/products/(indoor|outdoor)//*[jcr:contains(., 'test')]
+<div class="source">
+<div class="source"><pre class="prettyprint">/jcr:root/conent/products/(indoor|outdoor)//*[jcr:contains(., 'test')]
order by @jcr:score descending
</pre></div></div>
-
<p>Here, the query is converted to a “union”, and the result of both subqueries is combined. If the score for each subquery is not comparable (which is often the case for Lucene indexes), then the order of the results may not match the expected order. Instead of using path restrictions as above, it is most likely better to use a an additional condition in the query, and index that:</p>
-<div>
-<div>
-<pre class="source">/jcr:root/content/products//*[jcr:contains(., 'test') and
+<div class="source">
+<div class="source"><pre class="prettyprint">/jcr:root/content/products//*[jcr:contains(., 'test') and
(@productTag='indoor' or @productTag='outdoor')]
order by @jcr:score descending
</pre></div></div>
-
<p>If this is not possible, then try to avoid using “union”, and use an “or” condition as follows. This will only work for SQL-2 queries however:</p>
-<div>
-<div>
-<pre class="source">select * from [nt:base] as a where contains(*, 'test') and issamenode(a, '/content') and
+<div class="source">
+<div class="source"><pre class="prettyprint">select * from [nt:base] as a where contains(*, 'test') and issamenode(a, '/content') and
([jcr:path] like '/content/x800/%' or [jcr:path] like '/content/y900/%')
order by [jcr:score] desc
</pre></div></div></div></div></div>
Modified: jackrabbit/site/live/oak/docs/query/query.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/query/query.html?rev=1846222&r1=1846221&r2=1846222&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/query/query.html (original)
+++ jackrabbit/site/live/oak/docs/query/query.html Fri Nov 9 09:44:19 2018
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 at 2018-09-19
+ | Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2018-02-21
| Rendered using Apache Maven Fluido Skin 1.6
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20180919" />
+ <meta name="Date-Revision-yyyymmdd" content="20180221" />
<meta http-equiv="Content-Language" content="en" />
<title>Jackrabbit Oak – Oak Query</title>
<link rel="stylesheet" href="../css/apache-maven-fluido-1.6.min.css" />
@@ -52,7 +52,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Main APIs <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="http://www.day.com/specs/jcr/2.0/index.html" title="JCR API">JCR API</a></li>
- <li><a href="https://jackrabbit.apache.org/jcr/jcr-api.html" title="Jackrabbit API">Jackrabbit API</a></li>
<li><a href="../oak_api/overview.html" title="Oak API">Oak API</a></li>
</ul>
</li>
@@ -67,12 +66,7 @@
<li><a href="../nodestore/compositens.html" title="Composite NodeStore">Composite NodeStore</a></li>
</ul>
</li>
- <li class="dropdown-submenu">
-<a href="../plugins/blobstore.html" title="Blob Storage">Blob Storage</a>
- <ul class="dropdown-menu">
- <li><a href="../features/direct-binary-access.html" title="Direct Binary Access">Direct Binary Access</a></li>
- </ul>
- </li>
+ <li><a href="../plugins/blobstore.html" title="Blob Storage">Blob Storage</a></li>
<li class="dropdown-submenu">
<a href="../query/query.html" title="Query">Query</a>
<ul class="dropdown-menu">
@@ -142,7 +136,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2018-09-19<span class="divider">|</span>
+ <li id="publishDate">Last Published: 2018-02-21<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 1.10-SNAPSHOT</li>
</ul>
@@ -161,14 +155,12 @@
<li><a href="../architecture/nodestate.html" title="The Node State Model"><span class="none"></span>The Node State Model</a> </li>
<li class="nav-header">Main APIs</li>
<li><a href="http://www.day.com/specs/jcr/2.0/index.html" class="externalLink" title="JCR API"><span class="none"></span>JCR API</a> </li>
- <li><a href="https://jackrabbit.apache.org/jcr/jcr-api.html" class="externalLink" title="Jackrabbit API"><span class="none"></span>Jackrabbit API</a> </li>
<li><a href="../oak_api/overview.html" title="Oak API"><span class="none"></span>Oak API</a> </li>
<li class="nav-header">Features and Plugins</li>
<li><a href="../nodestore/overview.html" title="Node Storage"><span class="icon-chevron-down"></span>Node Storage</a>
<ul class="nav nav-list">
<li><a href="../nodestore/documentmk.html" title="Document NodeStore"><span class="icon-chevron-down"></span>Document NodeStore</a>
<ul class="nav nav-list">
- <li><a href="../nodestore/document/mongo-document-store.html" title="MongoDB DocumentStore"><span class="none"></span>MongoDB DocumentStore</a> </li>
<li><a href="../nodestore/document/node-bundling.html" title="Node Bundling"><span class="none"></span>Node Bundling</a> </li>
<li><a href="../nodestore/document/secondary-store.html" title="Secondary Store"><span class="none"></span>Secondary Store</a> </li>
<li><a href="../nodestore/persistent-cache.html" title="Persistent Cache"><span class="none"></span>Persistent Cache</a> </li>
@@ -179,11 +171,7 @@
<li><a href="../nodestore/compositens.html" title="Composite NodeStore"><span class="none"></span>Composite NodeStore</a> </li>
</ul>
</li>
- <li><a href="../plugins/blobstore.html" title="Blob Storage"><span class="icon-chevron-down"></span>Blob Storage</a>
- <ul class="nav nav-list">
- <li><a href="../features/direct-binary-access.html" title="Direct Binary Access"><span class="none"></span>Direct Binary Access</a> </li>
- </ul>
- </li>
+ <li><a href="../plugins/blobstore.html" title="Blob Storage"><span class="none"></span>Blob Storage</a> </li>
<li class="active"><a href="#"><span class="icon-chevron-down"></span>Query</a>
<ul class="nav nav-list">
@@ -252,38 +240,49 @@
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.
- -->
-<div class="section">
+ --><div class="section">
<h2><a name="Oak_Query"></a>Oak Query</h2>
<p>Oak does not index as much content by default as does Jackrabbit 2. You need to create custom indexes when necessary, much like in traditional RDBMSs. If there is no index for a specific query, then the repository will be traversed. That is, the query will still work but probably be very slow.</p>
-<ul>
+<ul>
+
<li><a href="./query-engine.html">The Query Engine</a></li>
+
<li><a href="./grammar-xpath.html">XPath Grammar</a></li>
+
<li><a href="./query-sql2.html">SQL-2 Grammar</a></li>
+
<li><a href="./query-troubleshooting.html">Troubleshooting</a></li>
+
<li><a href="./flags.html">Flags</a></li>
</ul>
<div class="section">
<h3><a name="Indexes"></a>Indexes</h3>
<p>There are 3 main types of indexes available in Oak. For other type (eg: nodetype) please refer to the <a href="./query-engine.html">query engine</a> documentation page.</p>
-<ul>
+<ul>
+
<li><a href="./lucene.html">Lucene</a></li>
+
<li><a href="./solr.html">Solr</a></li>
+
<li><a href="./property-index.html">Property</a></li>
</ul>
<p>For more details on how indexing works (for all index types):</p>
-<ul>
+<ul>
+
<li><a href="indexing.html">Indexing</a></li>
+
<li><a href="indexing.html#Reindexing">Reindexing</a></li>
</ul></div>
<div class="section">
<h3><a name="Customisations"></a>Customisations</h3>
-<ul>
+<ul>
+
<li><a href="./ootb-index-change.html">Change Out-Of-The-Box Index Definitions</a></li>
+
<li><a href="./search-mt.html">Machine Translation for Search</a></li>
</ul></div></div>
</div>
Modified: jackrabbit/site/live/oak/docs/query/search-mt.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/query/search-mt.html?rev=1846222&r1=1846221&r2=1846222&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/query/search-mt.html (original)
+++ jackrabbit/site/live/oak/docs/query/search-mt.html Fri Nov 9 09:44:19 2018
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 at 2018-09-19
+ | Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2018-02-21
| Rendered using Apache Maven Fluido Skin 1.6
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20180919" />
+ <meta name="Date-Revision-yyyymmdd" content="20180221" />
<meta http-equiv="Content-Language" content="en" />
<title>Jackrabbit Oak – Machine Translation for Search</title>
<link rel="stylesheet" href="../css/apache-maven-fluido-1.6.min.css" />
@@ -52,7 +52,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Main APIs <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="http://www.day.com/specs/jcr/2.0/index.html" title="JCR API">JCR API</a></li>
- <li><a href="https://jackrabbit.apache.org/jcr/jcr-api.html" title="Jackrabbit API">Jackrabbit API</a></li>
<li><a href="../oak_api/overview.html" title="Oak API">Oak API</a></li>
</ul>
</li>
@@ -67,12 +66,7 @@
<li><a href="../nodestore/compositens.html" title="Composite NodeStore">Composite NodeStore</a></li>
</ul>
</li>
- <li class="dropdown-submenu">
-<a href="../plugins/blobstore.html" title="Blob Storage">Blob Storage</a>
- <ul class="dropdown-menu">
- <li><a href="../features/direct-binary-access.html" title="Direct Binary Access">Direct Binary Access</a></li>
- </ul>
- </li>
+ <li><a href="../plugins/blobstore.html" title="Blob Storage">Blob Storage</a></li>
<li class="dropdown-submenu">
<a href="../query/query.html" title="Query">Query</a>
<ul class="dropdown-menu">
@@ -142,7 +136,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2018-09-19<span class="divider">|</span>
+ <li id="publishDate">Last Published: 2018-02-21<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 1.10-SNAPSHOT</li>
</ul>
@@ -161,14 +155,12 @@
<li><a href="../architecture/nodestate.html" title="The Node State Model"><span class="none"></span>The Node State Model</a> </li>
<li class="nav-header">Main APIs</li>
<li><a href="http://www.day.com/specs/jcr/2.0/index.html" class="externalLink" title="JCR API"><span class="none"></span>JCR API</a> </li>
- <li><a href="https://jackrabbit.apache.org/jcr/jcr-api.html" class="externalLink" title="Jackrabbit API"><span class="none"></span>Jackrabbit API</a> </li>
<li><a href="../oak_api/overview.html" title="Oak API"><span class="none"></span>Oak API</a> </li>
<li class="nav-header">Features and Plugins</li>
<li><a href="../nodestore/overview.html" title="Node Storage"><span class="icon-chevron-down"></span>Node Storage</a>
<ul class="nav nav-list">
<li><a href="../nodestore/documentmk.html" title="Document NodeStore"><span class="icon-chevron-down"></span>Document NodeStore</a>
<ul class="nav nav-list">
- <li><a href="../nodestore/document/mongo-document-store.html" title="MongoDB DocumentStore"><span class="none"></span>MongoDB DocumentStore</a> </li>
<li><a href="../nodestore/document/node-bundling.html" title="Node Bundling"><span class="none"></span>Node Bundling</a> </li>
<li><a href="../nodestore/document/secondary-store.html" title="Secondary Store"><span class="none"></span>Secondary Store</a> </li>
<li><a href="../nodestore/persistent-cache.html" title="Persistent Cache"><span class="none"></span>Persistent Cache</a> </li>
@@ -179,11 +171,7 @@
<li><a href="../nodestore/compositens.html" title="Composite NodeStore"><span class="none"></span>Composite NodeStore</a> </li>
</ul>
</li>
- <li><a href="../plugins/blobstore.html" title="Blob Storage"><span class="icon-chevron-down"></span>Blob Storage</a>
- <ul class="nav nav-list">
- <li><a href="../features/direct-binary-access.html" title="Direct Binary Access"><span class="none"></span>Direct Binary Access</a> </li>
- </ul>
- </li>
+ <li><a href="../plugins/blobstore.html" title="Blob Storage"><span class="none"></span>Blob Storage</a> </li>
<li><a href="../query/query.html" title="Query"><span class="icon-chevron-down"></span>Query</a>
<ul class="nav nav-list">
<li><a href="../query/query-engine.html" title="Query Engine"><span class="none"></span>Query Engine</a> </li>
@@ -251,23 +239,24 @@
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.
- -->
-<div class="section">
+ --><div class="section">
<h2><a name="Machine_Translation_for_Search"></a>Machine Translation for Search</h2>
-<ul>
+<ul>
+
<li><a href="#qtmtl">Query time MT for Lucene indexes</a>
+
<ul>
-
+
<li><a href="#joshua">Apache Joshua</a>
+
<ul>
-
+
<li><a href="#languagepacks">Language Packs</a></li>
-</ul>
-</li>
+ </ul></li>
+
<li><a href="#setup">Setup</a></li>
-</ul>
-</li>
+ </ul></li>
</ul>
<p>Oak supports CLIR (Cross Language Information Retrieval) by using <i>Machine Translation</i> to decorate search queries. Such an extension is provided within the <i>oak-search-mt</i> bundle.</p>
<div class="section">
@@ -286,10 +275,13 @@
<div class="section">
<h4><a name="Setup"></a><a name="setup"></a> Setup</h4>
<p>Multiple <i>MTFulltextQueryTermsProvider</i> can be configured (for different language pairs) by using <i>MTFulltextQueryTermsProviderFactory</i> OSGi configuration factory. In order to instantiate a <i>MTFulltextQueryTermsProviderFactory</i> the following properties need to be configured:</p>
-<ul>
+<ul>
+
<li><i>path.to.config</i> -> the path to the <i>joshua.config</i> configuration file (e.g. of a downloaded language pack)</li>
+
<li><i>node.types</i> -> the list of node types for which query time MT expansion should be done</li>
+
<li><i>min.score</i> -> the minimum score (between 0 and 1) for a translated sentence / token to be used while expanding the query (this is used to filter out low quality translations)</li>
</ul></div></div></div>
</div>
Modified: jackrabbit/site/live/oak/docs/query/solr.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/query/solr.html?rev=1846222&r1=1846221&r2=1846222&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/query/solr.html (original)
+++ jackrabbit/site/live/oak/docs/query/solr.html Fri Nov 9 09:44:19 2018
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 at 2018-09-19
+ | Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2018-02-21
| Rendered using Apache Maven Fluido Skin 1.6
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20180919" />
+ <meta name="Date-Revision-yyyymmdd" content="20180221" />
<meta http-equiv="Content-Language" content="en" />
<title>Jackrabbit Oak – Solr Index</title>
<link rel="stylesheet" href="../css/apache-maven-fluido-1.6.min.css" />
@@ -52,7 +52,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Main APIs <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="http://www.day.com/specs/jcr/2.0/index.html" title="JCR API">JCR API</a></li>
- <li><a href="https://jackrabbit.apache.org/jcr/jcr-api.html" title="Jackrabbit API">Jackrabbit API</a></li>
<li><a href="../oak_api/overview.html" title="Oak API">Oak API</a></li>
</ul>
</li>
@@ -67,12 +66,7 @@
<li><a href="../nodestore/compositens.html" title="Composite NodeStore">Composite NodeStore</a></li>
</ul>
</li>
- <li class="dropdown-submenu">
-<a href="../plugins/blobstore.html" title="Blob Storage">Blob Storage</a>
- <ul class="dropdown-menu">
- <li><a href="../features/direct-binary-access.html" title="Direct Binary Access">Direct Binary Access</a></li>
- </ul>
- </li>
+ <li><a href="../plugins/blobstore.html" title="Blob Storage">Blob Storage</a></li>
<li class="dropdown-submenu">
<a href="../query/query.html" title="Query">Query</a>
<ul class="dropdown-menu">
@@ -142,7 +136,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2018-09-19<span class="divider">|</span>
+ <li id="publishDate">Last Published: 2018-02-21<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 1.10-SNAPSHOT</li>
</ul>
@@ -161,14 +155,12 @@
<li><a href="../architecture/nodestate.html" title="The Node State Model"><span class="none"></span>The Node State Model</a> </li>
<li class="nav-header">Main APIs</li>
<li><a href="http://www.day.com/specs/jcr/2.0/index.html" class="externalLink" title="JCR API"><span class="none"></span>JCR API</a> </li>
- <li><a href="https://jackrabbit.apache.org/jcr/jcr-api.html" class="externalLink" title="Jackrabbit API"><span class="none"></span>Jackrabbit API</a> </li>
<li><a href="../oak_api/overview.html" title="Oak API"><span class="none"></span>Oak API</a> </li>
<li class="nav-header">Features and Plugins</li>
<li><a href="../nodestore/overview.html" title="Node Storage"><span class="icon-chevron-down"></span>Node Storage</a>
<ul class="nav nav-list">
<li><a href="../nodestore/documentmk.html" title="Document NodeStore"><span class="icon-chevron-down"></span>Document NodeStore</a>
<ul class="nav nav-list">
- <li><a href="../nodestore/document/mongo-document-store.html" title="MongoDB DocumentStore"><span class="none"></span>MongoDB DocumentStore</a> </li>
<li><a href="../nodestore/document/node-bundling.html" title="Node Bundling"><span class="none"></span>Node Bundling</a> </li>
<li><a href="../nodestore/document/secondary-store.html" title="Secondary Store"><span class="none"></span>Secondary Store</a> </li>
<li><a href="../nodestore/persistent-cache.html" title="Persistent Cache"><span class="none"></span>Persistent Cache</a> </li>
@@ -179,11 +171,7 @@
<li><a href="../nodestore/compositens.html" title="Composite NodeStore"><span class="none"></span>Composite NodeStore</a> </li>
</ul>
</li>
- <li><a href="../plugins/blobstore.html" title="Blob Storage"><span class="icon-chevron-down"></span>Blob Storage</a>
- <ul class="nav nav-list">
- <li><a href="../features/direct-binary-access.html" title="Direct Binary Access"><span class="none"></span>Direct Binary Access</a> </li>
- </ul>
- </li>
+ <li><a href="../plugins/blobstore.html" title="Blob Storage"><span class="none"></span>Blob Storage</a> </li>
<li><a href="../query/query.html" title="Query"><span class="icon-chevron-down"></span>Query</a>
<ul class="nav nav-list">
<li><a href="../query/query-engine.html" title="Query Engine"><span class="none"></span>Query Engine</a> </li>
@@ -252,35 +240,35 @@
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.
- -->
-<div class="section">
+ --><div class="section">
<h2><a name="Solr_Index"></a>Solr Index</h2>
<p>The Solr index is mainly meant for full-text search (the ‘contains’ type of queries):</p>
-<div>
-<div>
-<pre class="source">//*[jcr:contains(., 'text')]
+<div class="source">
+<div class="source"><pre class="prettyprint">//*[jcr:contains(., 'text')]
</pre></div></div>
-
<p>but is also able to search by path and property restrictions. Primary type restriction support is also provided by it’s not recommended as it’s usually much better to use the <a href="query.html#The_Node_Type_Index">node type index</a> for such kind of queries.</p>
<p>Even if it’s not just a full-text index, it’s recommended to use it asynchronously (see <tt>Oak#withAsyncIndexing</tt>) because, in most production scenarios, it’ll be a ‘remote’ index and therefore network latency / errors would have less impact on the repository performance.</p>
<p>The index definition node for a Solr-based index:</p>
-<ul>
+<ul>
+
<li>must be of type <tt>oak:QueryIndexDefinition</tt></li>
+
<li>must have the <tt>type</tt> property set to <b><tt>solr</tt></b></li>
+
<li>must contain the <tt>async</tt> property set to the value <tt>async</tt>, this is what sends the index update process to a background thread.</li>
</ul>
<p><i>Optionally</i> one can add</p>
-<ul>
+<ul>
+
<li>the <tt>reindex</tt> flag which when set to <tt>true</tt>, triggers a full content re-index.</li>
</ul>
<p>Example:</p>
-<div>
-<div>
-<pre class="source">{
+<div class="source">
+<div class="source"><pre class="prettyprint">{
NodeBuilder index = root.child("oak:index");
index.child("solr")
.setProperty("jcr:primaryType", "oak:QueryIndexDefinition", Type.NAME)
@@ -289,14 +277,15 @@
.setProperty("reindex", true);
}
</pre></div></div>
-
<p>The Oak Solr index creates one document in the Solr index for each node in the repository, each of such documents has usually at least a field for each property associated with the related node. Indexing of properties can be done by name: e.g. property ‘jcr:title’ of a node is written into a field ‘jcr:title’ of the corresponding Solr document in the index, or by type: e.g. properties ‘jcr:data’ and ‘binary_content’ of type <i>binary</i> are written into a field ‘binary_data’ that’s responsible for the indexing of all fields having that type and thus properly configured for hosting such type of data.</p>
<div class="section">
<h3><a name="Configuring_the_Solr_index"></a>Configuring the Solr index</h3>
-<p>Besides the index definition parameters mentioned above, a number of additional parameters can be defined in Oak Solr index configuration. Such a configuration is composed by:</p>
-<ul>
+<p>Besides the index definition parameters mentioned above, a number of additional parameters can be defined in Oak Solr index configuration. Such a configuration is composed by:</p>
+<ul>
+
<li>the search / indexing configuration (see <a class="externalLink" href="http://jackrabbit.apache.org/oak/docs/apidocs/org/apache/jackrabbit/oak/plugins/index/solr/configuration/OakSolrConfiguration.html">OakSolrConfiguration</a>)</li>
+
<li>the Solr server configuration (see <a class="externalLink" href="http://jackrabbit.apache.org/oak/docs/apidocs/org/apache/jackrabbit/oak/plugins/index/solr/configuration/SolrServerConfiguration.html">SolrServerConfiguration</a>)</li>
</ul></div>
<div class="section">
@@ -327,20 +316,20 @@
<h4><a name="Descendant_path_field"></a>Descendant path field</h4>
<p>The name of the field to be used for searching for nodes descendants of a certain node.</p>
<p>Default is ‘path_des’.</p>
-<p>E.g. The Solr query to find all the descendant nodes of /a/b would be ‘path_des:/a/b’.</p></div>
+<p>E.g. The Solr query to find all the descendant nodes of /a/b would be ‘path_des:\/a\/b’.</p></div>
<div class="section">
<h4><a name="Children_path_field"></a>Children path field</h4>
<p>The name of the field to be used for searching for child nodes of a certain node.</p>
<p>Default is ‘path_child’.</p>
-<p>E.g. The Solr query to find all the child nodes of /a/b would be ‘path_child:/a/b’.</p></div>
+<p>E.g. The Solr query to find all the child nodes of /a/b would be ‘path_child:\/a\/b’.</p></div>
<div class="section">
<h4><a name="Parent_path_field"></a>Parent path field</h4>
<p>The name of the field to be used for searching for parent node of a certain node.</p>
<p>Default is ‘path_anc’.</p>
-<p>E.g. The Solr query to find the parent node of /a/b would be ‘path_anc:/a/b’.</p></div>
+<p>E.g. The Solr query to find the parent node of /a/b would be ‘path_anc:\/a\/b’.</p></div>
<div class="section">
<h4><a name="Property_restriction_fields"></a>Property restriction fields</h4>
-<p>The (optional) mapping of property names into Solr fields, so that a mapping jcr:title=foo is defined each node having the property jcr:title will have its correspondant Solr document having a property foo indexed with the value of the jcr:title property.</p>
+<p>The (optional) mapping of property names into Solr fields, so that a mapping jcr:title=foo is defined each node having the property jcr:title will have its correspondant Solr document having a property foo indexed with the value of the jcr:title property.</p>
<p>Default is no mapping, therefore the default mechanism of mapping property names to field names is performed.</p></div>
<div class="section">
<h4><a name="Used_properties"></a>Used properties</h4>
@@ -350,7 +339,7 @@
<div class="section">
<h4><a name="aIgnored_properties"></a> Ignored properties</h4>
<p>A blacklist of properties to be ignored while indexing and searching by the Solr index.</p>
-<p>Such a blacklist makes sense (it will be taken into account by the Solr index) only if the <a href="#Used_properties">Used properties</a> option doesn’t have any value.</p>
+<p>Such a blacklist makes sense (it will be taken into account by the Solr index) only if the <a href="#Used_properties">Used properties</a> option doesn’t have any value.</p>
<p>Default is the following array: <i>(“rep:members”, “rep:authorizableId”, “jcr:uuid”, “rep:principalName”, “rep:password”}</i>.</p></div>
<div class="section">
<h4><a name="Commit_policy"></a>Commit policy</h4>
@@ -363,11 +352,11 @@
<div class="section">
<h4><a name="Rows"></a>Rows</h4>
<p>The number of documents per ‘page’ to be fetched for each query.</p>
-<p>Default is <i>Integer.MAX_VALUE</i> (was <i>50</i> in Oak 1.0).</p></div>
+<p>Default is _Integer.MAX<i>VALUE</i> (was <i>50</i> in Oak 1.0).</p></div>
<div class="section">
<h4><a name="Collapse_jcr:content_nodes"></a>Collapse <i>jcr:content</i> nodes</h4>
<p><tt>@since 1.3.4, 1.2.4, 1.0.18</tt></p>
-<p>Whether the <a class="externalLink" href="https://cwiki.apache.org/confluence/display/solr/Collapse+and+Expand+Results">Collapsing query parser</a> should be used when searching in order to collapse nodes that are descendants of ‘jcr:content’ nodes into the ‘jcr:content’ node only. E.g. if normal query results would include ‘/a/jcr:content’ and ‘/a/jcr:content/b/’, with this option enabled only ‘/a/jcr:content’ would be returned by Solr using the Collapsing query parser. This feature requires an additional field to be indexed, therefore if this is turned on, reindexing should be triggered in order to make it work properly.</p></div>
+<p>Whether the <a class="externalLink" href="https://cwiki.apache.org/confluence/display/solr/Collapse+and+Expand+Results">Collapsing query parser</a> should be used when searching in order to collapse nodes that are descendants of ‘jcr:content’ nodes into the ‘jcr:content’ node only. E.g. if normal query results would include ‘/a/jcr:content’ and ‘/a/jcr:content/b/’, with this option enabled only ‘/a/jcr:content’ would be returned by Solr using the Collapsing query parser. This feature requires an additional field to be indexed, therefore if this is turned on, reindexing should be triggered in order to make it work properly. </p></div>
<div class="section">
<h4><a name="Collapsed_path_field"></a>Collapsed path field</h4>
<p><tt>@since 1.3.4, 1.2.4, 1.0.18</tt></p>
@@ -377,13 +366,17 @@
<p>TBD</p></div></div>
<div class="section">
<h4><a name="Setting_up_the_Solr_server"></a>Setting up the Solr server</h4>
-<p>For the Solr index to work Oak needs to be able to communicate with a Solr instance / cluster. Apache Solr supports multiple deployment architectures:</p>
-<ul>
+<p>For the Solr index to work Oak needs to be able to communicate with a Solr instance / cluster. Apache Solr supports multiple deployment architectures: </p>
+<ul>
+
<li>embedded Solr instance running in the same JVM the client runs into</li>
+
<li>single remote instance</li>
+
<li>master / slave architecture, eventually with multiple shards and replicas</li>
-<li>SolrCloud cluster, with Zookeeper instance(s) to control a dynamic, resilient set of Solr servers for high availability and fault tolerance</li>
+
+<li>SolrCloud cluster, with Zookeeper instance(s) to control a dynamic, resilient set of Solr servers for high availability and fault tolerance</li>
</ul>
<p>The Oak Solr index can be configured to either use an ‘embedded Solr server’ or a ‘remote Solr server’ (being able to connect to a single remote instance or to a SolrCloud cluster via Zookeeper).</p>
<div class="section">
@@ -391,20 +384,23 @@
<p>Depending on the use case, different Solr server deployments are recommended.</p>
<div class="section">
<h6><a name="Embedded_Solr_server"></a>Embedded Solr server</h6>
-<p>The embedded Solr server is recommended for developing and testing the Solr index for an Oak repository. With that an in-memory Solr instance is started in the same JVM of the Oak repository, without HTTP bindings (for security purposes as it’d allow HTTP access to repository data independently of ACLs). Configuring an embedded Solr server mainly consists of providing the path to a standard <a class="externalLink" href="https://wiki.apache.org/solr/SolrTerminology">Solr home dir</a> (<i>solr.home.path</i> Oak property) to be used to start Solr; this path can be either relative or absolute, if such a path would not exist then the default configuration provided with <i>oak-solr-core</i> artifact would be put in the given path. To start an embedded Solr server with a custom configuration (e.g. different schema.xml / solrconfig.xml than the default ones) the (modified) Solr home files would have to be put in a dedicated directory, according to Solr home structure, so that the
solr.home.path property can be pointed to that directory.</p></div>
+<p>The embedded Solr server is recommended for developing and testing the Solr index for an Oak repository. With that an in-memory Solr instance is started in the same JVM of the Oak repository, without HTTP bindings (for security purposes as it’d allow HTTP access to repository data independently of ACLs). Configuring an embedded Solr server mainly consists of providing the path to a standard <a class="externalLink" href="https://wiki.apache.org/solr/SolrTerminology">Solr home dir</a> (<i>solr.home.path</i> Oak property) to be used to start Solr; this path can be either relative or absolute, if such a path would not exist then the default configuration provided with <i>oak-solr-core</i> artifact would be put in the given path. To start an embedded Solr server with a custom configuration (e.g. different schema.xml / solrconfig.xml than the default ones) the (modified) Solr home files would have to be put in a dedicated directory, according to Solr home structure, so that th
e solr.home.path property can be pointed to that directory.</p></div>
<div class="section">
<h6><a name="Single_remote_Solr_server"></a>Single remote Solr server</h6>
-<p>A single (remote) Solr instance is the simplest possible setup for using the Oak Solr index in a production environment. Oak will communicate to such a Solr server through Solr’s HTTP APIs (via <a class="externalLink" href="http://wiki.apache.org/solr/Solrj">SolrJ</a> client). Configuring a single remote Solr instance consists of providing the URL to connect to in order to reach the [Solr core] (<a class="externalLink" href="https://wiki.apache.org/solr/SolrTerminology">https://wiki.apache.org/solr/SolrTerminology</a>) that will host the Solr index for the Oak repository via the <i>solr.http.url</i> property which will have to contain such a URL (e.g. <i><a class="externalLink" href="http://10.10.1.101:8983/solr/oak">http://10.10.1.101:8983/solr/oak</a></i>). All the configuration and tuning of Solr, other than what’s described on this page, will have to be performed on the Solr side; <a class="externalLink" href="http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oa
k-solr-core/src/main/resources/solr/">sample Solr configuration</a> files (schema.xml, solrconfig.xml, etc.) to start with can be found in <i>oak-solr-core</i> artifact.</p></div>
+<p>A single (remote) Solr instance is the simplest possible setup for using the Oak Solr index in a production environment. Oak will communicate to such a Solr server through Solr’s HTTP APIs (via <a class="externalLink" href="http://wiki.apache.org/solr/Solrj">SolrJ</a> client). Configuring a single remote Solr instance consists of providing the URL to connect to in order to reach the <a class="externalLink" href="https://wiki.apache.org/solr/SolrTerminology">Solr core</a> that will host the Solr index for the Oak repository via the <i>solr.http.url</i> property which will have to contain such a URL (e.g. _<a class="externalLink" href="http://10.10.1.101:8983/solr/oak_)">http://10.10.1.101:8983/solr/oak_)</a>. All the configuration and tuning of Solr, other than what’s described on this page, will have to be performed on the Solr side; <a class="externalLink" href="http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-solr-core/src/main/resources/solr/">sample Solr c
onfiguration</a> files (schema.xml, solrconfig.xml, etc.) to start with can be found in <i>oak-solr-core</i> artifact.</p></div>
<div class="section">
<h6><a name="SolrCloud_cluster"></a>SolrCloud cluster</h6>
-<p>A <a class="externalLink" href="https://cwiki.apache.org/confluence/display/solr/SolrCloud">SolrCloud</a> cluster is the recommended setup for an Oak Solr index in production as it provides a scalable and fault tolerant architecture. In order to configure a SolrCloud cluster the host of the Zookeeper instance / ensemble managing the Solr servers has to be provided in the <i>solr.zk.host</i> property (e.g. <i>10.1.1.108:9983</i>) since the SolrJ client for SolrCloud communicates directly with Zookeeper. The <a class="externalLink" href="https://wiki.apache.org/solr/SolrTerminology">Solr collection</a> to be used within Oak is named <i>oak</i>, having a replication factor of 2 and using 2 shards; this means in the default setup the SolrCloud cluster would have to be composed by at least 4 Solr servers as the index will be split into 2 shards and each shard will have 2 replicas. SolrCloud also allows the hot deploy of configuration files to be used for a certain collection so while
setting up the collection to be used for Oak with the needed files before starting the cluster, configuration files can also be uploaded from a local directory, this is controlled by the <i>solr.conf.dir</i> property of the ‘Oak Solr remote server configuration’. For a detailed description of how SolrCloud works see the <a class="externalLink" href="https://cwiki.apache.org/confluence/display/solr/SolrCloud">Solr reference guide</a>.</p></div></div>
+<p>A <a class="externalLink" href="https://cwiki.apache.org/confluence/display/solr/SolrCloud">SolrCloud</a> cluster is the recommended setup for an Oak Solr index in production as it provides a scalable and fault tolerant architecture. In order to configure a SolrCloud cluster the host of the Zookeeper instance / ensemble managing the Solr servers has to be provided in the <i>solr.zk.host</i> property (e.g. <i>10.1.1.108:9983</i>) since the SolrJ client for SolrCloud communicates directly with Zookeeper. The <a class="externalLink" href="https://wiki.apache.org/solr/SolrTerminology">Solr collection</a> to be used within Oak is named <i>oak</i>, having a replication factor of 2 and using 2 shards; this means in the default setup the SolrCloud cluster would have to be composed by at least 4 Solr servers as the index will be split into 2 shards and each shard will have 2 replicas. SolrCloud also allows the hot deploy of configuration files to be used for a certain collection so whil
e setting up the collection to be used for Oak with the needed files before starting the cluster, configuration files can also be uploaded from a local directory, this is controlled by the <i>solr.conf.dir</i> property of the ‘Oak Solr remote server configuration’. For a detailed description of how SolrCloud works see the <a class="externalLink" href="https://cwiki.apache.org/confluence/display/solr/SolrCloud">Solr reference guide</a>.</p></div></div>
<div class="section">
<h5><a name="OSGi_environment"></a>OSGi environment</h5>
<p>Create an index definition for the Solr index, as described <a href="#Solr_index">above</a>. Once the query index definition node has been created, access OSGi ConfigurationAdmin via e.g. Apache Felix WebConsole:</p>
-<ol style="list-style-type: decimal">
+<ol style="list-style-type: decimal">
+
<li>find the ‘Oak Solr indexing / search configuration’ item and eventually change configuration properties as needed</li>
-<li>find either the ‘Oak Solr embedded server configuration’ or ‘Oak Solr remote server configuration’ items depending on the chosen Solr architecture and eventually change configuration properties as needed</li>
+
+<li>find either the ‘Oak Solr embedded server configuration’ or ‘Oak Solr remote server configuration’ items depending on the chosen Solr architecture and eventually change configuration properties as needed</li>
+
<li>find the ‘Oak Solr server provider’ item and select the chosen provider (‘remote’ or ‘embedded’)</li>
</ol></div></div>
<div class="section">
@@ -412,7 +408,7 @@
<div class="section">
<h5><a name="Aggregation"></a>Aggregation</h5>
<p><tt>@since Oak 1.1.4, 1.0.13</tt></p>
-<p>Solr index supports query time aggregation, that can be enabled in OSGi by setting <tt>SolrQueryIndexProviderService</tt> service property <tt>query.aggregation</tt> to true.</p></div>
+<p>Solr index supports query time aggregation, that can be enabled in OSGi by setting <tt>SolrQueryIndexProviderService</tt> service property <tt>query.aggregation</tt> to true. </p></div>
<div class="section">
<h5><a name="Suggestions"></a>Suggestions</h5>
<p><tt>@since Oak 1.1.17, 1.0.15</tt></p>
@@ -428,26 +424,21 @@
<p><tt>@since Oak 1.3.14</tt></p>
<p>In order to enable proper usage of facets in Solr index the following dynamic field needs to be added to the <i>schema.xml</i></p>
-<div>
-<div>
-<pre class="source"> <dynamicField name="*_facet" type="string" indexed="false" stored="false" docValues="true" multiValued="true"/>
+<div class="source">
+<div class="source"><pre class="prettyprint"> <dynamicField name="*_facet" type="string" indexed="false" stored="false" docValues="true" multiValued="true"/>
</pre></div></div>
-
<p>with dedicated <i>copyFields</i> for specific properties.</p>
-<div>
-<div>
-<pre class="source"> <copyField source="jcr:primaryType" dest="jcr:primaryType_facet"/> <!-- facet on jcr:primaryType field/property -->
-</pre></div></div>
-</div>
+<div class="source">
+<div class="source"><pre class="prettyprint"> <copyField source="jcr:primaryType" dest="jcr:primaryType_facet"/> <!-- facet on jcr:primaryType field/property -->
+</pre></div></div></div>
<div class="section">
<h4><a name="Persisted_configuration"></a>Persisted configuration</h4>
<p><tt>@since Oak 1.4.0</tt></p>
-<p>It’s possible to create (multiple) Solr indexes via persisted configuration. A persisted Oak Solr index is created whenever an index definition with <i>type = solr</i> has a child node named <i>server</i> and such a child node has the <i>solrServerType</i> property set (to either <i>embedded</i> or <i>remote</i>). If no such child node exists, an Oak Solr index will be only created upon explicit registration of a [SolrServerProvider] e.g. via OSGi. All the <a class="externalLink" href="http://jackrabbit.apache.org/oak/docs/apidocs/org/apache/jackrabbit/oak/plugins/index/solr/configuration/OakSolrConfiguration.html">OakSolrConfiguration</a> and <a class="externalLink" href="http://jackrabbit.apache.org/oak/docs/apidocs/org/apache/jackrabbit/oak/plugins/index/solr/configuration/SolrServerConfiguration.html">SolrServerConfiguration</a> properties are exposed and configurable, see also <a class="externalLink" href="https://github.com/apache/jackrabbit-oak/blob/trunk/oak-solr-c
ore/src/main/java/org/apache/jackrabbit/oak/plugins/index/solr/configuration/nodestate/OakSolrNodeStateConfiguration.java#L245">OakSolrNodeStateConfiguration#Properties</a> and <a class="externalLink" href="https://github.com/apache/jackrabbit-oak/blob/trunk/oak-solr-core/src/main/java/org/apache/jackrabbit/oak/plugins/index/solr/configuration/nodestate/NodeStateSolrServerConfigurationProvider.java#L94">NodeStateSolrServerConfigurationProvider#Properties</a></p>
+<p>It’s possible to create (multiple) Solr indexes via persisted configuration. A persisted Oak Solr index is created whenever an index definition with <i>type = solr</i> has a child node named <i>server</i> and such a child node has the <i>solrServerType</i> property set (to either <i>embedded</i> or <i>remote</i>). If no such child node exists, an Oak Solr index will be only created upon explicit registration of a [SolrServerProvider] e.g. via OSGi. All the <a class="externalLink" href="http://jackrabbit.apache.org/oak/docs/apidocs/org/apache/jackrabbit/oak/plugins/index/solr/configuration/OakSolrConfiguration.html">OakSolrConfiguration</a> and <a class="externalLink" href="http://jackrabbit.apache.org/oak/docs/apidocs/org/apache/jackrabbit/oak/plugins/index/solr/configuration/SolrServerConfiguration.html">SolrServerConfiguration</a> properties are exposed and configurable, see also <a class="externalLink" href="https://github.com/apache/jackrabbit-oak/blob/trunk/oak-sol
r-core/src/main/java/org/apache/jackrabbit/oak/plugins/index/solr/configuration/nodestate/OakSolrNodeStateConfiguration.java#L245">OakSolrNodeStateConfiguration#Properties</a> and <a class="externalLink" href="https://github.com/apache/jackrabbit-oak/blob/trunk/oak-solr-core/src/main/java/org/apache/jackrabbit/oak/plugins/index/solr/configuration/nodestate/NodeStateSolrServerConfigurationProvider.java#L94">NodeStateSolrServerConfigurationProvider#Properties</a></p>
-<div>
-<div>
-<pre class="source">/oak:index/solrRemote
+<div class="source">
+<div class="source"><pre class="prettyprint">/oak:index/solrRemote
- jcr:primaryType = "oak:QueryIndexDefinition"
- type = "solr"
- async = "async"
@@ -456,20 +447,23 @@
- solrServerType = "remote"
- httpUrl = "http://localhost:8983/solr/oak"
</pre></div></div>
-
<p>If such configurations exists in the repository the <a class="externalLink" href="http://jackrabbit.apache.org/oak/docs/apidocs/org/apache/jackrabbit/oak/plugins/index/solr/configuration/nodestate/NodeStateSolrServersObserver.html">NodeStateSolrServersObserver</a> should be registered too (e.g. via <a class="externalLink" href="http://jackrabbit.apache.org/oak/docs/apidocs/org/apache/jackrabbit/oak/plugins/index/solr/osgi/NodeStateSolrServersObserverService.html">NodeStateSolrServersObserverService</a> OSGi service).</p></div>
<div class="section">
<h4><a name="Notes"></a>Notes</h4>
<p>As of Oak version 1.0.0:</p>
-<ul>
+<ul>
+
<li>Solr index doesn’t support search using relative properties, see <a class="externalLink" href="https://issues.apache.org/jira/browse/OAK-1835">OAK-1835</a>.</li>
+
<li>Lucene can only be used for full-text queries, Solr can be used for full-text search <i>and</i> for JCR queries involving path, property and primary type restrictions.</li>
</ul>
<p>As of Oak version 1.2.0:</p>
-<ul>
+<ul>
+
<li>Solr index doesn’t support index time aggregation, but only query time aggregation</li>
+
<li>Lucene and Solr can be both used for full text, property and path restrictions</li>
</ul></div></div></div>
</div>
Modified: jackrabbit/site/live/oak/docs/release-schedule.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/release-schedule.html?rev=1846222&r1=1846221&r2=1846222&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/release-schedule.html (original)
+++ jackrabbit/site/live/oak/docs/release-schedule.html Fri Nov 9 09:44:19 2018
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 at 2018-09-19
+ | Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2018-04-27
| Rendered using Apache Maven Fluido Skin 1.6
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20180919" />
+ <meta name="Date-Revision-yyyymmdd" content="20180427" />
<meta http-equiv="Content-Language" content="en" />
<title>Jackrabbit Oak – Release Schedule</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.6.min.css" />
@@ -52,7 +52,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Main APIs <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="http://www.day.com/specs/jcr/2.0/index.html" title="JCR API">JCR API</a></li>
- <li><a href="https://jackrabbit.apache.org/jcr/jcr-api.html" title="Jackrabbit API">Jackrabbit API</a></li>
<li><a href="oak_api/overview.html" title="Oak API">Oak API</a></li>
</ul>
</li>
@@ -67,12 +66,7 @@
<li><a href="nodestore/compositens.html" title="Composite NodeStore">Composite NodeStore</a></li>
</ul>
</li>
- <li class="dropdown-submenu">
-<a href="plugins/blobstore.html" title="Blob Storage">Blob Storage</a>
- <ul class="dropdown-menu">
- <li><a href="features/direct-binary-access.html" title="Direct Binary Access">Direct Binary Access</a></li>
- </ul>
- </li>
+ <li><a href="plugins/blobstore.html" title="Blob Storage">Blob Storage</a></li>
<li class="dropdown-submenu">
<a href="query/query.html" title="Query">Query</a>
<ul class="dropdown-menu">
@@ -142,7 +136,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2018-09-19<span class="divider">|</span>
+ <li id="publishDate">Last Published: 2018-04-27<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 1.10-SNAPSHOT</li>
</ul>
@@ -161,14 +155,12 @@
<li><a href="architecture/nodestate.html" title="The Node State Model"><span class="none"></span>The Node State Model</a> </li>
<li class="nav-header">Main APIs</li>
<li><a href="http://www.day.com/specs/jcr/2.0/index.html" class="externalLink" title="JCR API"><span class="none"></span>JCR API</a> </li>
- <li><a href="https://jackrabbit.apache.org/jcr/jcr-api.html" class="externalLink" title="Jackrabbit API"><span class="none"></span>Jackrabbit API</a> </li>
<li><a href="oak_api/overview.html" title="Oak API"><span class="none"></span>Oak API</a> </li>
<li class="nav-header">Features and Plugins</li>
<li><a href="nodestore/overview.html" title="Node Storage"><span class="icon-chevron-down"></span>Node Storage</a>
<ul class="nav nav-list">
<li><a href="nodestore/documentmk.html" title="Document NodeStore"><span class="icon-chevron-down"></span>Document NodeStore</a>
<ul class="nav nav-list">
- <li><a href="nodestore/document/mongo-document-store.html" title="MongoDB DocumentStore"><span class="none"></span>MongoDB DocumentStore</a> </li>
<li><a href="nodestore/document/node-bundling.html" title="Node Bundling"><span class="none"></span>Node Bundling</a> </li>
<li><a href="nodestore/document/secondary-store.html" title="Secondary Store"><span class="none"></span>Secondary Store</a> </li>
<li><a href="nodestore/persistent-cache.html" title="Persistent Cache"><span class="none"></span>Persistent Cache</a> </li>
@@ -179,11 +171,7 @@
<li><a href="nodestore/compositens.html" title="Composite NodeStore"><span class="none"></span>Composite NodeStore</a> </li>
</ul>
</li>
- <li><a href="plugins/blobstore.html" title="Blob Storage"><span class="icon-chevron-down"></span>Blob Storage</a>
- <ul class="nav nav-list">
- <li><a href="features/direct-binary-access.html" title="Direct Binary Access"><span class="none"></span>Direct Binary Access</a> </li>
- </ul>
- </li>
+ <li><a href="plugins/blobstore.html" title="Blob Storage"><span class="none"></span>Blob Storage</a> </li>
<li><a href="query/query.html" title="Query"><span class="icon-chevron-down"></span>Query</a>
<ul class="nav nav-list">
<li><a href="query/query-engine.html" title="Query Engine"><span class="none"></span>Query Engine</a> </li>
@@ -252,16 +240,21 @@
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.
- -->
-<h1>Release Schedule</h1>
+ --><h1>Release Schedule</h1>
<p>Here is the frequency where the team <b>aim</b> to cut new releases. As we strive for quality rather than frequency the date may slip according to needs.</p>
-<ul>
+<ul>
+
<li>Trunk: every 2 weeks (2 / month, ~26 /year)</li>
+
<li>1.8: every 4 weeks (1 / month, ~12 / year)</li>
+
<li>1.6: every 8 weeks (1 / other month, ~6 / year)</li>
+
<li>1.4: every 13 weeks (1 / quarter, ~4 / year)</li>
+
<li>1.2: every 13 weeks (1 / quarter, ~4 / year)</li>
+
<li>1.0: every 26 weeks (~2 / year)</li>
</ul>
</div>
Modified: jackrabbit/site/live/oak/docs/security/accesscontrol.html
URL: http://svn.apache.org/viewvc/jackrabbit/site/live/oak/docs/security/accesscontrol.html?rev=1846222&r1=1846221&r2=1846222&view=diff
==============================================================================
--- jackrabbit/site/live/oak/docs/security/accesscontrol.html (original)
+++ jackrabbit/site/live/oak/docs/security/accesscontrol.html Fri Nov 9 09:44:19 2018
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 at 2018-09-19
+ | Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2018-02-21
| Rendered using Apache Maven Fluido Skin 1.6
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20180919" />
+ <meta name="Date-Revision-yyyymmdd" content="20180221" />
<meta http-equiv="Content-Language" content="en" />
<title>Jackrabbit Oak – Access Control Management</title>
<link rel="stylesheet" href="../css/apache-maven-fluido-1.6.min.css" />
@@ -52,7 +52,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Main APIs <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="http://www.day.com/specs/jcr/2.0/index.html" title="JCR API">JCR API</a></li>
- <li><a href="https://jackrabbit.apache.org/jcr/jcr-api.html" title="Jackrabbit API">Jackrabbit API</a></li>
<li><a href="../oak_api/overview.html" title="Oak API">Oak API</a></li>
</ul>
</li>
@@ -67,12 +66,7 @@
<li><a href="../nodestore/compositens.html" title="Composite NodeStore">Composite NodeStore</a></li>
</ul>
</li>
- <li class="dropdown-submenu">
-<a href="../plugins/blobstore.html" title="Blob Storage">Blob Storage</a>
- <ul class="dropdown-menu">
- <li><a href="../features/direct-binary-access.html" title="Direct Binary Access">Direct Binary Access</a></li>
- </ul>
- </li>
+ <li><a href="../plugins/blobstore.html" title="Blob Storage">Blob Storage</a></li>
<li class="dropdown-submenu">
<a href="../query/query.html" title="Query">Query</a>
<ul class="dropdown-menu">
@@ -142,7 +136,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2018-09-19<span class="divider">|</span>
+ <li id="publishDate">Last Published: 2018-02-21<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 1.10-SNAPSHOT</li>
</ul>
@@ -161,14 +155,12 @@
<li><a href="../architecture/nodestate.html" title="The Node State Model"><span class="none"></span>The Node State Model</a> </li>
<li class="nav-header">Main APIs</li>
<li><a href="http://www.day.com/specs/jcr/2.0/index.html" class="externalLink" title="JCR API"><span class="none"></span>JCR API</a> </li>
- <li><a href="https://jackrabbit.apache.org/jcr/jcr-api.html" class="externalLink" title="Jackrabbit API"><span class="none"></span>Jackrabbit API</a> </li>
<li><a href="../oak_api/overview.html" title="Oak API"><span class="none"></span>Oak API</a> </li>
<li class="nav-header">Features and Plugins</li>
<li><a href="../nodestore/overview.html" title="Node Storage"><span class="icon-chevron-down"></span>Node Storage</a>
<ul class="nav nav-list">
<li><a href="../nodestore/documentmk.html" title="Document NodeStore"><span class="icon-chevron-down"></span>Document NodeStore</a>
<ul class="nav nav-list">
- <li><a href="../nodestore/document/mongo-document-store.html" title="MongoDB DocumentStore"><span class="none"></span>MongoDB DocumentStore</a> </li>
<li><a href="../nodestore/document/node-bundling.html" title="Node Bundling"><span class="none"></span>Node Bundling</a> </li>
<li><a href="../nodestore/document/secondary-store.html" title="Secondary Store"><span class="none"></span>Secondary Store</a> </li>
<li><a href="../nodestore/persistent-cache.html" title="Persistent Cache"><span class="none"></span>Persistent Cache</a> </li>
@@ -179,11 +171,7 @@
<li><a href="../nodestore/compositens.html" title="Composite NodeStore"><span class="none"></span>Composite NodeStore</a> </li>
</ul>
</li>
- <li><a href="../plugins/blobstore.html" title="Blob Storage"><span class="icon-chevron-down"></span>Blob Storage</a>
- <ul class="nav nav-list">
- <li><a href="../features/direct-binary-access.html" title="Direct Binary Access"><span class="none"></span>Direct Binary Access</a> </li>
- </ul>
- </li>
+ <li><a href="../plugins/blobstore.html" title="Blob Storage"><span class="none"></span>Blob Storage</a> </li>
<li><a href="../query/query.html" title="Query"><span class="icon-chevron-down"></span>Query</a>
<ul class="nav nav-list">
<li><a href="../query/query-engine.html" title="Query Engine"><span class="none"></span>Query Engine</a> </li>
@@ -251,148 +239,179 @@
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.
--->
-<div class="section">
+--><div class="section">
<h2><a name="Access_Control_Management"></a>Access Control Management</h2>
<div class="section">
<h3><a name="General"></a>General</h3>
-<p>This section covers fundamental concepts of the access control related APIs provided by JCR and Jackrabbit as well as the extensions points defined by Oak.</p>
+<p>This section covers fundamental concepts of the access control related APIs provided by JCR and Jackrabbit as well as the extensions points defined by Oak. </p>
<p>If you are already familiar with the API and looking for examples you may directly read <a href="accesscontrol/editing.html">Using the Access Control Management API</a> for a comprehensive list of method calls as well as examples that may be used to edit the access control content of the repository.</p>
-<a name="jcr_api"></a>
-### JCR API
-
+<p><a name="jcr_api"></a></p></div>
+<div class="section">
+<h3><a name="JCR_API"></a>JCR API</h3>
<p>Access Control Management is an optional feature defined by <a class="externalLink" href="http://www.day.com/specs/jcr/2.0/16_Access_Control_Management.html">JSR 283</a> consisting of</p>
-<blockquote>
+<blockquote>
<p>• Privilege discovery: Determining the privileges that a user has in relation to a node.</p>
<p>• Assigning access control policies: Setting the privileges that a user has in relation to a node using access control policies specific to the implementation.</p>
</blockquote>
<p>Whether or not a given implementation supports access control management is defined by the <tt>Repository.OPTION_ACCESS_CONTROL_SUPPORTED</tt> descriptor.</p>
<p>Since Oak comes with a dedicated <a href="privilege.html">privilege management</a> this section focuses on reading and editing access control information. The main interfaces defined by JSR 283 are:</p>
-<ul>
+<ul>
+
<li><tt>AccessControlManager</tt>: Main entry point for access control related operations</li>
+
<li><tt>AccessControlPolicy</tt>: Marker interface for any kind of policies defined by the implementation.
+
<ul>
-
+
<li><tt>AccessControlList</tt>: mutable policy that may have a list of entries.</li>
+
<li><tt>NamedAccessControlPolicy</tt>: opaque immutable policy with a JCR name.</li>
-</ul>
-</li>
+ </ul></li>
+
<li><tt>AccessControlEntry</tt>: association of privilege(s) with a given principal bound to a given node by the <tt>AccessControlList</tt>.</li>
</ul>
<p>The JCR access control management has the following characteristics:</p>
-<ul>
+<ul>
+
<li><i>path-based</i>: policies are bound to nodes; a given node may have multiple policies; the <tt>null</tt> path identifies repository level policies.</li>
+
<li><i>transient</i>: access control related modifications are always transient</li>
+
<li><i>binding</i>: policies are decoupled from the repository; in order to bind a policy to a node or apply modifications made to an existing policy <tt>AccessControlManager.setPolicy</tt> must be called.</li>
+
<li><i>effect</i>: policies bound to a given node only take effect upon <tt>Session.save()</tt>. Access to properties is defined by the their parent node.</li>
+
<li><i>scope</i>: a given policy may not only affect the node it is bound to but may have an effect on accessibility of items elsewhere in the workspace.</li>
</ul>
-<a name="jackrabbit_api"></a>
-### Jackrabbit API
-
+<p><a name="jackrabbit_api"></a></p></div>
+<div class="section">
+<h3><a name="Jackrabbit_API"></a>Jackrabbit API</h3>
<p>The Jackrabbit API defines various access control related extensions to the JCR API in order to cover common needs such as for example:</p>
-<ul>
+<ul>
+
<li><i>deny access</i>: access control entries can be defined to deny privileges at a given path (JCR only defines allowing access control entries)</li>
+
<li><i>restrictions</i>: limit the effect of a given access control entry by the mean of restrictions</li>
+
<li><i>convenience</i>:
+
<ul>
-
+
<li>reordering of access control entries in a access control list</li>
+
<li>retrieve the path of the node a given policy is (or can be) bound to</li>
-</ul>
-</li>
+ </ul></li>
+
<li><i>principal-based</i>:
+
<ul>
-
+
<li>principal-based access control management API (in contrast to the path-based default specified by JSR 283)</li>
+
<li>privilege discovery for a set of principals</li>
-</ul>
-</li>
+ </ul></li>
</ul>
<p>The following interfaces and extensions are defined:</p>
-<ul>
+<ul>
+
<li><tt>JackrabbitAccessControlManager</tt></li>
+
<li><tt>JackrabbitAccessControlPolicy</tt></li>
+
<li><tt>JackrabbitAccessControlList</tt></li>
+
<li><tt>JackrabbitAccessControlEntry</tt></li>
</ul>
-<a name="api_extensions"></a>
-### API Extensions
-
+<p><a name="api_extensions"></a></p></div>
+<div class="section">
+<h3><a name="API_Extensions"></a>API Extensions</h3>
<p>Oak defines the following interfaces extending the access control management API:</p>
-<ul>
-<li><tt>PolicyOwner</tt>: Interface to improve pluggability of the access control management and allows to termine if a giving manager handles a given policy.</li>
+<ul>
+
+<li><tt>PolicyOwner</tt>: Interface to improve pluggability of the access control management and allows to termine if a giving manager handles a given policy.</li>
+
<li><tt>AccessControlConstants</tt>: Constants related to access control management.</li>
</ul>
<p>In addition it provides some access control related base classes in <tt>org.apache.jackrabbit.oak.spi.security.authorization.accesscontrol</tt> that may be used for a custom implementation:</p>
-<ul>
+<ul>
+
<li><tt>AbstractAccessControlList</tt>: abstract base implementation of the <tt>JackrabbitAccessControlList</tt> interface
+
<ul>
-
+
<li><tt>ImmutableACL</tt>: immutable subclass of <tt>AbstractAccessControlList</tt></li>
+
<li><tt>ACE</tt>: abstract subclass that implements common methods of a mutable access control list.</li>
-</ul>
-</li>
+ </ul></li>
</ul>
<div class="section">
<h4><a name="Restriction_Management"></a>Restriction Management</h4>
<p>Oak 1.0 defines a dedicated restriction management API. See <a href="authorization/restriction.html">Restriction Management</a> for details and further information regarding extensibility and pluggability.</p>
-<a name="utilities"></a>
-### Utilities
-
+<p><a name="utilities"></a></p></div></div>
+<div class="section">
+<h3><a name="Utilities"></a>Utilities</h3>
<p>The jcr-commons module present with Jackrabbit provide some access control related utilities that simplify the creation of new policies and entries such as for example:</p>
-<ul>
+<ul>
+
<li><tt>AccessControlUtils.getAccessControlList(Session, String)</tt></li>
+
<li><tt>AccessControlUtils.getAccessControlList(AccessControlManager, String)</tt></li>
+
<li><tt>AccessControlUtils.addAccessControlEntry(Session, String, Principal, String[], boolean)</tt></li>
</ul>
<p>See <a class="externalLink" href="http://svn.apache.org/repos/asf/jackrabbit/trunk/jackrabbit-jcr-commons/src/main/java/org/apache/jackrabbit/commons/jackrabbit/authorization/AccessControlUtils.java">org.apache.jackrabbit.commons.jackrabbit.authorization.AccessControlUtils</a> for the complete list of methods.</p>
<div class="section">
+<div class="section">
<h5><a name="Examples"></a>Examples</h5>
-<div>
-<div>
-<pre class="source">String path = node.getPath();
+<div class="source">
+<div class="source"><pre class="prettyprint">String path = node.getPath();
JackrabbitAccessControlList acl = AccessControlUtils.getAccessControlList(session, path);
acl.addEntry(principal, privileges, true);
acMgr.setPolicy(path, acl);
session.save();
</pre></div></div>
-<a name="default_implementation"></a>
-### Characteristics of the Default Implementation
-
-<p>The behavior of the default access control implementation is described in sections <a href="accesscontrol/default.html">Access Control Management: The Default Implementation</a><br />
-and <a href="authorization/restriction.html">Restriction Management</a>.</p>
-<a name="configuration"></a>
-### Configuration
-
+<p><a name="default_implementation"></a></p></div></div></div>
+<div class="section">
+<h3><a name="Characteristics_of_the_Default_Implementation"></a>Characteristics of the Default Implementation</h3>
+<p>The behavior of the default access control implementation is described in sections <a href="accesscontrol/default.html">Access Control Management: The Default Implementation</a><br />and <a href="authorization/restriction.html">Restriction Management</a>.</p>
+<p><a name="configuration"></a></p></div>
+<div class="section">
+<h3><a name="Configuration"></a>Configuration</h3>
<p>The configuration of the access control management implementation is handled within the <a href="/oak/docs/apidocs/org/apache/jackrabbit/oak/spi/security/authorization/AuthorizationConfiguration.html">AuthorizationConfiguration</a>, which is used for all authorization related matters. This class provides the following two access control related methods:</p>
-<ul>
+<ul>
+
<li><tt>getAccessControlManager</tt>: get a new ac manager instance.</li>
+
<li><tt>getRestrictionProvider</tt>: get a new instance of the restriction provider.</li>
-</ul></div></div>
+</ul>
<div class="section">
<h4><a name="Configuration_Parameters"></a>Configuration Parameters</h4>
<p>The supported configuration options of the default implementation are described in the corresponding <a href="accesscontrol/default.html#configuration">section</a>.</p>
-<a name="further_reading"></a>
-### Further Reading
+<p><a name="further_reading"></a></p></div></div>
+<div class="section">
+<h3><a name="Further_Reading"></a>Further Reading</h3>
<ul>
-
+
<li><a href="accesscontrol/differences.html">Differences wrt Jackrabbit 2.x</a></li>
+
<li><a href="accesscontrol/default.html">Access Control Management: The Default Implementation</a></li>
+
<li><a href="accesscontrol/editing.html">Using the Access Control Management API</a></li>
+
<li><a href="authorization/restriction.html">Restriction Management</a></li>
-</ul><!-- hidden references --></div></div></div>
+</ul>
+<!-- hidden references --></div></div>
</div>
</div>
</div>