Menu
▾
▴
[Bigdata-commit] SF.net SVN: bigdata:[7799] branches/BIGDATA_RELEASE_1_3_0
|
From: <tho...@us...> - 2014-01-15 12:34:04
|
Revision: 7799
http://bigdata.svn.sourceforge.net/bigdata/?rev=7799&view=rev
Author: thompsonbry
Date: 2014-01-15 12:33:55 +0000 (Wed, 15 Jan 2014)
Log Message:
-----------
javadoc related to query hints.
Modified the javadoc ant task to generate documentation for package private as well as public and protected.
Modified Paths:
--------------
branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/QueryHints.java
branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/AtOnceHint.java
branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/ChunkSizeHint.java
branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/PipelineMaxParallelHint.java
branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/RunFirstHint.java
branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/RunLastHint.java
branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/RunOnceHint.java
branches/BIGDATA_RELEASE_1_3_0/build.xml
Modified: branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/QueryHints.java
===================================================================
--- branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/QueryHints.java 2014-01-14 16:59:02 UTC (rev 7798)
+++ branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/QueryHints.java 2014-01-15 12:33:55 UTC (rev 7799)
@@ -341,32 +341,37 @@
*
* @see https://sourceforge.net/apps/trac/bigdata/ticket/283
*/
- String QUERYID = "queryId";//QueryHints.class.getName() + ".queryId";
+ String QUERYID = "queryId";
/**
* This query hint may be applied to any {@link IJoinNode} and marks a
* particular join to be run first among in a particular group. Only one
* "run first" join is permitted in a given group. This query hint is not
- * permitted on optional joins.
+ * permitted on optional joins. This hint must be used with
+ * {@link QueryHintScope#Prior}.
*/
- String RUN_FIRST = "runFirst";//QueryHints.class.getName() + ".runFirst";
+ String RUN_FIRST = "runFirst";
/**
* This query hint may be applied to any {@link IJoinNode} and marks a
* particular join to be run last among in a particular group. Only one
- * "run last" join is permitted in a given group.
+ * "run last" join is permitted in a given group. This hint must be used
+ * with {@link QueryHintScope#Prior}.
*/
- String RUN_LAST = "runLast";//QueryHints.class.getName() + ".runLast";
+ String RUN_LAST = "runLast";
/**
* Query hint indicating whether or not a Sub-Select should be transformed
* into a <em>named subquery</em>, lifting its evaluation out of the main
- * body of the query and replacing the subquery with an INCLUDE. This is
- * similar to {@link #AT_ONCE 'at-once'} evaluation, but creates a different
- * query plan by lifting out a named subquery. It is also only supported for
- * a Sub-Select. The {@link #AT_ONCE} query hint can be applied to other
- * things as well.
+ * body of the query and replacing the subquery with an INCLUDE. This hint
+ * must be used with {@link QueryHintScope#SubQuery}.
* <p>
+ * This is similar to {@link #AT_ONCE 'atOnce'} evaluation, but creates a
+ * different query plan by lifting out a named subquery. The
+ * {@link #RUN_ONCE} query hint is only supported for
+ * {@link QueryHintScope#SubQuery} while {@link #AT_ONCE} query hint can be
+ * applied to other things as well.
+ * <p>
* When <code>true</code>, the subquery will be lifted out. When
* <code>false</code>, the subquery will not be lifted unless other
* semantics require that it be lifted out regardless.
@@ -381,20 +386,23 @@
*
* @see #AT_ONCE
*/
- String RUN_ONCE = "runOnce";//QueryHints.class.getName() + ".runOnce";
+ String RUN_ONCE = "runOnce";
/**
* Query hint indicating whether or not a JOIN (including SERVICE,
- * SUB-SELECT, etc) should be run as an "at-once" operator. All solutions
- * for an "at-once" operator are materialized before the operator is
- * evaluated. It is then evaluated against those materialized solutions
- * exactly once.
+ * SUB-SELECT, etc) should be run as an "atOnce" operator. All solutions for
+ * an "atOnce" operator are materialized before the operator is evaluated.
+ * It is then evaluated against those materialized solutions exactly once.
* <p>
- * Note: "At-once" evaluation is a general property of the query engine.
- * This query hint does not change the structure of the query plan, but
- * simply serves as a directive to the query engine that it should buffer
- * all source solutions before running the operator. This is more general
+ * Note: "atOnce" evaluation is a general property of the query engine. This
+ * query hint does not change the structure of the query plan, but simply
+ * serves as a directive to the query engine that it should buffer all
+ * source solutions before running the operator. This is more general
* purpose than the {@link #RUN_ONCE} query hint.
+ * <p>
+ * This query hint is allowed in any scope. The hint is transferred as an
+ * annotation onto all query plan operators generated from the annotated
+ * scope.
*
* @see #RUN_ONCE
*
@@ -409,11 +417,14 @@
String AT_ONCE = "atOnce";
/**
- * The target chunk (aka vector size) for the operator.
+ * Sets the target chunk size (aka vector size) for the output buffer of the operator.
* <p>
- * Note: The vectored query engine will buffer multiple chunks for an
- * operator before the producer(s) (the operator(s) feeding into the
- * annotated operator) must block.
+ * This query hint does not change the structure of the query plan, but
+ * simply serves as a directive to the query engine that it should allocate
+ * an output buffer for the operator that will emit chunks of the indicated
+ * target capacity. This query hint is allowed in any scope, but is
+ * generally used to effect the behavior of a join group, a subquery, or the
+ * entire query.
*
* @see BufferAnnotations#CHUNK_CAPACITY
*/
@@ -421,6 +432,14 @@
/**
* The maximum parallelism for the operator within the query.
+ * <p>
+ * Note: "maxParallel" evaluation is a general property of the query engine.
+ * This query hint does not change the structure of the query plan, but
+ * simply serves as a directive to the query engine that it should not allow
+ * more than the indicated number of parallel instances of the operator to
+ * execute concurrently. This query hint is allowed in any scope. The hint is
+ * transferred as an annotation onto all query plan operators generated from
+ * the annotated scope.
*
* @see PipelineOp.Annotations#MAX_PARALLEL
*/
@@ -528,7 +547,7 @@
* elements (maximum) should be read from its access path. This
* effectively limits the input into the join.
*
- * @see {@link Annotations#CUTOFF_LIMIT}.
+ * @see Annotations#CUTOFF_LIMIT
*/
String CUTOFF_LIMIT = "cutoffLimit";
Modified: branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/AtOnceHint.java
===================================================================
--- branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/AtOnceHint.java 2014-01-14 16:59:02 UTC (rev 7798)
+++ branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/AtOnceHint.java 2014-01-15 12:33:55 UTC (rev 7799)
@@ -35,14 +35,16 @@
import com.bigdata.rdf.sparql.ast.eval.AST2BOpContext;
/**
- * Query hint marks the operator as requiring "at-once" evaluation. All
- * solutions will be buffered by the {@link QueryEngine} before the operator is
- * evaluated. When it is evaluated, it will receive all solutions in a single
- * invocation of that operator. However, the solutions MAY appear in multiple
- * chunks since the {@link QueryEngine} does not guarantee that the chunk will
- * be merged before the operator is invoked.
+ * Query hint marks the operator as requiring "atOnce" evaluation. All solutions
+ * will be buffered by the {@link QueryEngine} before the operator is evaluated.
+ * When it is evaluated, it will receive all solutions in a single invocation of
+ * that operator. However, the solutions MAY appear in multiple chunks since the
+ * {@link QueryEngine} does not guarantee that the chunk will be merged before
+ * the operator is invoked. This query hint is allowed in any scope. The hint is
+ * transferred as an annotation onto all query plan operators generated from the
+ * annotated scope.
* <p>
- * Note: The "at-once" hint is basically turned into <code>NOT(PIPELINED)</code>.
+ * Note: The "atOnce" hint is basically turned into <code>NOT(PIPELINED)</code>.
*
* @see PipelineOp.Annotations#PIPELINED
*/
Modified: branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/ChunkSizeHint.java
===================================================================
--- branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/ChunkSizeHint.java 2014-01-14 16:59:02 UTC (rev 7798)
+++ branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/ChunkSizeHint.java 2014-01-15 12:33:55 UTC (rev 7799)
@@ -28,17 +28,24 @@
package com.bigdata.rdf.sparql.ast.hints;
import com.bigdata.bop.BufferAnnotations;
-import com.bigdata.bop.IBindingSet;
import com.bigdata.rdf.sparql.ast.QueryHints;
/**
* This is identical to the {@link BufferChunkCapacityHint}, but it is accessed
* through the well known name {@link QueryHints#CHUNK_SIZE}.
* <p>
- * Sets the capacity of the {@link IBindingSet}[]s used to accumulate a chunk of
- * {@link IBindingSet}s (default
- * {@value BufferAnnotations#DEFAULT_CHUNK_CAPACITY}). Partial chunks may be
- * automatically combined into full chunks.
+ * Sets the capacity of the output buffer that used to accumulate chunks of
+ * solutions (default {@value BufferAnnotations#DEFAULT_CHUNK_CAPACITY}).
+ * Partial chunks may be automatically combined into full chunks.
+ * <p>
+ * Note: The "chunkSize" is a general property of the query engine. This query
+ * hint does not change the structure of the query plan, but simply serves as a
+ * directive to the query engine that it should allocate an output buffer for
+ * the operator that will emit chunks of the indicated target capacity. This
+ * query hint is allowed in any scope, but is generally used to effect the
+ * behavior of a join group, a subquery, or the entire query. The hint is
+ * transferred as an annotation onto all query plan operators generated from the
+ * annotated scope.
*
* @see BufferAnnotations#CHUNK_CAPACITY
*/
Modified: branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/PipelineMaxParallelHint.java
===================================================================
--- branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/PipelineMaxParallelHint.java 2014-01-14 16:59:02 UTC (rev 7798)
+++ branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/PipelineMaxParallelHint.java 2014-01-15 12:33:55 UTC (rev 7799)
@@ -36,6 +36,14 @@
/**
* Sets the maximum #of operator evaluation tasks which can execute
* concurrently.
+ * <p>
+ * Note: "maxParallel" is a general property of the query engine. This query
+ * hint does not change the structure of the query plan, but simply serves as a
+ * directive to the query engine that it should not allow more than the
+ * indicated number of parallel instances of the operator to execute
+ * concurrently. This query hint is allowed in any scope. The hint is
+ * transferred as an annotation onto all query plan operators generated from the
+ * annotated scope.
*
* @see PipelineOp.Annotations#MAX_PARALLEL
*/
Modified: branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/RunFirstHint.java
===================================================================
--- branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/RunFirstHint.java 2014-01-14 16:59:02 UTC (rev 7798)
+++ branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/RunFirstHint.java 2014-01-15 12:33:55 UTC (rev 7799)
@@ -35,7 +35,8 @@
import com.bigdata.rdf.sparql.ast.optimizers.ASTStaticJoinOptimizer;
/**
- * Query hint to run a join first in a join group.
+ * Query hint to run a join first in a join group. This hint must be used
+ * with {@link QueryHintScope#Prior}.
* <p>
* Note: This sets an AST annotation which is interpreted by the
* {@link ASTRunFirstRunLastOptimizer} and {@link ASTStaticJoinOptimizer}.
Modified: branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/RunLastHint.java
===================================================================
--- branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/RunLastHint.java 2014-01-14 16:59:02 UTC (rev 7798)
+++ branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/RunLastHint.java 2014-01-15 12:33:55 UTC (rev 7799)
@@ -35,7 +35,8 @@
import com.bigdata.rdf.sparql.ast.optimizers.ASTStaticJoinOptimizer;
/**
- * Query hint to run a join last in a join group.
+ * Query hint to run a join last in a join group. This hint must be used with
+ * {@link QueryHintScope#Prior}.
* <p>
* Note: This sets an AST annotation which is interpreted by the
* {@link ASTRunFirstRunLastOptimizer} and {@link ASTStaticJoinOptimizer}.
Modified: branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/RunOnceHint.java
===================================================================
--- branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/RunOnceHint.java 2014-01-14 16:59:02 UTC (rev 7798)
+++ branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/hints/RunOnceHint.java 2014-01-15 12:33:55 UTC (rev 7799)
@@ -40,6 +40,7 @@
* and replacing the subquery with an INCLUDE. When <code>true</code>, the
* subquery will be lifted out. When <code>false</code>, the subquery will not
* be lifted unless other semantics require that it be lifted out regardless.
+ * This hint must be used with {@link QueryHintScope#SubQuery}.
* <p>
* For example, the following may be used to lift out the sub-select in which it
* appears into a {@link NamedSubqueryRoot}. The lifted expression will be
Modified: branches/BIGDATA_RELEASE_1_3_0/build.xml
===================================================================
--- branches/BIGDATA_RELEASE_1_3_0/build.xml 2014-01-14 16:59:02 UTC (rev 7798)
+++ branches/BIGDATA_RELEASE_1_3_0/build.xml 2014-01-15 12:33:55 UTC (rev 7799)
@@ -385,6 +385,10 @@
overview="${bigdata.dir}/overview.html"
windowtitle="bigdata® v${build.ver}"
classpathref="build.classpath"
+ package="true"
+ protected="true"
+ public="true"
+ private="false"
>
<arg value="-J-Xmx1000m" />
<arg value="-quiet" />
@@ -401,7 +405,7 @@
<doctitle>
<![CDATA[<h1>bigdata® v${build.ver}</h1>]]></doctitle>
<bottom>
- <![CDATA[<i>Copyright © 2006-2012 SYSTAP, LLC. All Rights Reserved.</i>]]></bottom>
+ <![CDATA[<i>Copyright © 2006-2014 SYSTAP, LLC. All Rights Reserved.</i>]]></bottom>
<tag name="todo" scope="all" description="TODO:" />
<tag name="issue" scope="all" description="ISSUE:" />
<!--tag name="FIXME" scope="all" description="FIXME:"/-->
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
