View Javadoc

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *     http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   */
    17
    18  /*
    19   * Query.java
    20   *
    21   */
    22
    23  package javax.jdo;
    24  import java.io.Serializable;
    25  import java.util.Collection;
    26  import java.util.Map;
    27
    28  /** The <code>Query</code> interface allows applications to obtain persistent
    29   * instances, values, and aggregate data
    30   * from the data store.
    31   *
    32   * The {@link PersistenceManager} is the factory for <code>Query</code>
    33   * instances.  There may be many <code>Query</code> instances associated with a
    34   * <code>PersistenceManager</code>.  Multiple queries might be executed
    35   * simultaneously by different threads, but the implementation might choose to
    36   * execute them serially.  In either case, the implementation must be thread
    37   * safe.
    38   *
    39   * <P>There are three required elements in a <code>Query</code>: the class of
    40   * the results, the candidate collection of instances, and the filter.
    41   *
    42   * <P>There are optional elements: parameter declarations, variable
    43   * declarations, import statements, ordering and grouping specifications,
    44   * result and result class, the range of results,
    45   * and flags indicating whether the query result
    46   * is unique and whether the query can be modified.
    47   * <P>The query namespace is modeled after methods in Java:
    48   * <ul>
    49   * <li><code>setClass</code> corresponds to the class definition
    50   * <li><code>declareParameters</code> corresponds to formal parameters of a
    51   * method
    52   * <li><code>declareVariables</code> corresponds to local variables of a method
    53   * <li><code>setFilter</code> and <code>setOrdering</code> correspond to the
    54   * method body
    55   * </ul>
    56   * <P>There are two namespaces in queries. Type names have their own
    57   * namespace that is separate from the namespace for fields, variables
    58   * and parameters.
    59   * <P>The method <code>setClass</code> introduces the name of the candidate
    60   * class in the type namespace. The method <code>declareImports</code>
    61   * introduces the names of the imported class or interface types in the type
    62   * namespace. Imported type names must be unique. When used (e.g. in a parameter
    63   * declaration, cast expression, etc.) a type name must be the name of the
    64   * candidate class, the name of a class or interface imported by method
    65   * <code>declareImports</code>, or denote a class or interface from the same
    66   * package as the candidate class.
    67   * <P>The method <code>setClass</code> introduces the names of the candidate
    68   * class fields.
    69   * <P>The method <code>declareParameters</code> introduces the names of the
    70   * parameters. A name introduced by <code>declareParameters</code> hides the
    71   * name of a candidate class field of the same name. Parameter names must be
    72   * unique.
    73   * <P>The method <code>declareVariables</code> introduces the names of the
    74   * variables.  A name introduced by <code>declareVariables</code> hides the name
    75   * of a candidate class field if equal. Variable names must be unique and must
    76   * not conflict with parameter names.
    77   * <P>The result of the query by default is a list of result class instances,
    78   * but might be specified via <code>setResult</code>. The class of the result
    79   * by default is the candidate class, but might be specified via
    80   * <code>setResultClass</code>.
    81   * <P>A hidden field may be accessed using the 'this' qualifier:
    82   * <code>this.fieldName</code>.
    83   * <P>The <code>Query</code> interface provides methods which execute the query
    84   * based on the parameters given. They return a single instance or a
    85   * <code>List</code> of result class instances which the
    86   * user can iterate to get results. The signature
    87   * of the <code>execute</code> methods specifies that they return an
    88   * <code>Object</code> which must be cast to the appropriate result by the user.
    89   * <P>Any parameters passed to the <code>execute</code> methods are used only
    90   * for this execution, and are not remembered for future execution.
    91   * @version 2.1
    92   */
    93
    94  public interface Query extends Serializable {
    95
    96      /**
    97       * The string constant used as the first argument to
    98       * {@link PersistenceManager#newQuery(String,Object)} to identify that the
    99       * created query should obey the JDOQL syntax and semantic rules.
    100      * <p>This is the default query language used when creating a query with any
    101      * of the other {@link PersistenceManager#newQuery} methods, except
    102      * {@link PersistenceManager#newQuery(Object)}, which uses the query
    103      * language of the compiled query template object passed to that method.</p>
    104      * @since 2.0
    105      */
    106     String JDOQL = "javax.jdo.query.JDOQL";
    107
    108     /**
    109      * The string constant used as the first argument to {@link
    110      * PersistenceManager#newQuery(String,Object)} to identify that
    111      * the created query should use SQL semantics. This is only
    112      * meaningful for relational JDO implementations.
    113      * <p>If this is used, the <code>Object</code> argument to the
    114      * {@link PersistenceManager#newQuery(String,Object)} method
    115      * should be a <code>String</code> containing a SQL
    116      * <code>SELECT</code> statement.</p>
    117      * @since 2.0
    118      */
    119     String SQL = "javax.jdo.query.SQL";
    120
    121     /** Set the class of the candidate instances of the query.
    122      * <P>The class specifies the class
    123      * of the candidates of the query.  Elements of the candidate collection
    124      * that are of the specified class are filtered before being
    125      * put into the result <code>Collection</code>.
    126      *
    127      * @param cls the <code>Class</code> of the candidate instances.
    128      */
    129     void setClass(Class cls);
    130
    131     /** Set the candidate <code>Extent</code> to query.
    132      * @param pcs the candidate <code>Extent</code>.
    133      */
    134     void setCandidates(Extent pcs);
    135
    136     /** Set the candidate <code>Collection</code> to query.
    137      * @param pcs the candidate <code>Collection</code>.
    138      */
    139     void setCandidates(Collection pcs);
    140
    141     /** Set the filter for the query.
    142      *
    143      * <P>The filter specification is a <code>String</code> containing a Boolean
    144      * expression that is to be evaluated for each of the instances
    145      * in the candidate collection. If the filter is not specified,
    146      * then it defaults to "true", which has the effect of filtering
    147      * the input <code>Collection</code> only for class type.
    148      * <P>An element of the candidate collection is returned in the result if:
    149      * <ul><li>it is assignment compatible to the candidate <code>Class</code>
    150      * of the <code>Query</code>; and
    151      * <li>for all variables there exists a value for which the filter
    152      * expression evaluates to <code>true</code>.
    153      * </ul>
    154      * <P>The user may denote uniqueness in the filter expression by
    155      * explicitly declaring an expression (for example, <code>e1 != e2</code>).
    156      * <P>Rules for constructing valid expressions follow the Java
    157      * language, except for these differences:
    158      * <ul>
    159      * <li>Equality and ordering comparisons between primitives and instances
    160      * of wrapper classes are valid.
    161      * <li>Equality and ordering comparisons of <code>Date</code> fields and
    162      * <code>Date</code> parameters are valid.
    163      * <li>White space (non-printing characters space, tab, carriage
    164      * return, and line feed) is a separator and is otherwise ignored.
    165      * <li>The assignment operators <code>=</code>, <code>+=</code>, etc. and
    166      * pre- and post-increment and -decrement are not supported. Therefore,
    167      * there are no side effects from evaluation of any expressions.
    168      * <li>Methods, including object construction, are not supported, except
    169      * for <code>Collection.contains(Object o)</code>,
    170      * <code>Collection.isEmpty()</code>,
    171      * <code>String.startsWith(String s)</code>, and
    172      * <code>String.endsWith(String e)</code>.  Implementations might choose to
    173      * support non-mutating method calls as non-standard extensions.
    174      * <li>Navigation through a <code>null</code>-valued field, which would
    175      * throw <code>NullPointerException</code>, is treated as if the filter
    176      * expression returned <code>false</code> for the evaluation of the current
    177      * set of variable values. Other values for variables might still qualify
    178      * the candidate instance for inclusion in the result set.
    179      * <li>Navigation through multi-valued fields (<code>Collection</code>
    180      * types) is specified using a variable declaration and the
    181      * <code>Collection.contains(Object o)</code> method.
    182      * </ul>
    183      * <P>Identifiers in the expression are considered to be in the name
    184      * space of the specified class, with the addition of declared imports,
    185      * parameters and variables. As in the Java language, <code>this</code> is a
    186      * reserved word which means the element of the collection being evaluated.
    187      * <P>Navigation through single-valued fields is specified by the Java
    188      * language syntax of <code>field_name.field_name....field_name</code>.
    189      * <P>A JDO implementation is allowed to reorder the filter expression
    190      * for optimization purposes.
    191      * @param filter the query filter.
    192      */
    193     void setFilter(String filter);
    194
    195     /** Set the import statements to be used to identify the fully qualified
    196      * name of variables or parameters.  Parameters and unbound variables might
    197      * come from a different class from the candidate class, and the names
    198      * need to be declared in an import statement to eliminate ambiguity.
    199      * Import statements are specified as a <code>String</code> with
    200      * semicolon-separated statements.
    201      * <P>The <code>String</code> parameter to this method follows the syntax of
    202      * the import statement of the Java language.
    203      * @param imports import statements separated by semicolons.
    204      */
    205     void declareImports(String imports);
    206
    207     /** Declare the list of parameters query execution.
    208      *
    209      * The parameter declaration is a <code>String</code> containing one or more
    210      * query parameter declarations separated with commas. Each parameter named
    211      * in the parameter declaration must be bound to a value when
    212      * the query is executed.
    213      * <P>The <code>String</code> parameter to this method follows the syntax
    214      * for formal parameters in the Java language.
    215      * @param parameters the list of parameters separated by commas.
    216      */
    217     void declareParameters(String parameters);
    218
    219     /** Declare the unbound variables to be used in the query. Variables
    220      * might be used in the filter, and these variables must be declared
    221      * with their type. The unbound variable declaration is a
    222      * <code>String</code> containing one or more unbound variable declarations
    223      * separated with semicolons. It follows the syntax for local variables in
    224      * the Java language.
    225      * @param variables the variables separated by semicolons.
    226      */
    227     void declareVariables(String variables);
    228
    229     /** Set the ordering specification for the result <code>Collection</code>.
    230      * The ordering specification is a <code>String</code> containing one or
    231      * more ordering declarations separated by commas.
    232      *
    233      * <P>Each ordering declaration is the name of the field on which
    234      * to order the results followed by one of the following words:
    235      * "<code>ascending</code>" or "<code>descending</code>".
    236      *
    237      *<P>The field must be declared in the candidate class or must be
    238      * a navigation expression starting with a field in the candidate class.
    239      *
    240      *<P>Valid field types are primitive types except <code>boolean</code>;
    241      * wrapper types except <code>Boolean</code>; <code>BigDecimal</code>;
    242      * <code>BigInteger</code>; <code>String</code>; and <code>Date</code>.
    243      * @param ordering the ordering specification.
    244      */
    245     void setOrdering(String ordering);
    246
    247     /** Set the ignoreCache option.  The default value for this option was
    248      * set by the <code>PersistenceManagerFactory</code> or the
    249      * <code>PersistenceManager</code> used to create this <code>Query</code>.
    250      *
    251      * The ignoreCache option setting specifies whether the query should execute
    252      * entirely in the back end, instead of in the cache.  If this flag is set
    253      * to <code>true</code>, an implementation might be able to optimize the
    254      * query execution by ignoring changed values in the cache.  For optimistic
    255      * transactions, this can dramatically improve query response times.
    256      * @param ignoreCache the setting of the ignoreCache option.
    257      */
    258     void setIgnoreCache(boolean ignoreCache);
    259
    260     /** Get the ignoreCache option setting.
    261      * @return the ignoreCache option setting.
    262      * @see #setIgnoreCache
    263      */
    264     boolean getIgnoreCache();
    265
    266     /** Verify the elements of the query and provide a hint to the query to
    267      * prepare and optimize an execution plan.
    268      */
    269     void compile();
    270
    271     /** Execute the query and return the filtered Collection.
    272      * <P>Cancellation of the query using cancel() will result in JDOQueryInterruptedException
    273      * being thrown here
    274      * @return the filtered <code>Collection</code>.
    275      * @see #executeWithArray(Object[] parameters)
    276      */
    277     Object execute();
    278
    279     /** Execute the query and return the filtered <code>Collection</code>.
    280      * <P>Cancellation of the query using cancel() will result in JDOQueryInterruptedException
    281      * being thrown here
    282      * @return the filtered <code>Collection</code>.
    283      * @see #executeWithArray(Object[] parameters)
    284      * @param p1 the value of the first parameter declared.
    285      */
    286     Object execute(Object p1);
    287
    288     /** Execute the query and return the filtered <code>Collection</code>.
    289      * <P>Cancellation of the query using cancel() will result in JDOQueryInterruptedException
    290      * being thrown here
    291      * @return the filtered <code>Collection</code>.
    292      * @see #executeWithArray(Object[] parameters)
    293      * @param p1 the value of the first parameter declared.
    294      * @param p2 the value of the second parameter declared.
    295      */
    296     Object execute(Object p1, Object p2);
    297
    298     /** Execute the query and return the filtered <code>Collection</code>.
    299      * <P>Cancellation of the query using cancel() will result in JDOQueryInterruptedException
    300      * being thrown here
    301      * @return the filtered <code>Collection</code>.
    302      * @see #executeWithArray(Object[] parameters)
    303      * @param p1 the value of the first parameter declared.
    304      * @param p2 the value of the second parameter declared.
    305      * @param p3 the value of the third parameter declared.
    306      */
    307     Object execute(Object p1, Object p2, Object p3);
    308
    309     /** Execute the query and return the filtered <code>Collection</code>.  The
    310      * query is executed with the parameters set by the <code>Map</code> values.
    311      * Each <code>Map</code> entry consists of a key which is the name of the
    312      * parameter in the <code>declareParameters</code> method, and a value which
    313      * is the value used in the <code>execute</code> method.  The keys in the
    314      * <code>Map</code> and the declared parameters must exactly match or a
    315      * <code>JDOUserException</code> is thrown.
    316      * <P>Cancellation of the query using cancel() will result in JDOQueryInterruptedException
    317      * being thrown here
    318      * @return the filtered <code>Collection</code>.
    319      * @see #executeWithArray(Object[] parameters)
    320      * @param parameters the <code>Map</code> containing all of the parameters.
    321      */
    322     Object executeWithMap (Map parameters);
    323
    324     /** Execute the query and return the filtered <code>Collection</code>.
    325      *
    326      * <P>The execution of the query obtains the values of the parameters and
    327      * matches them against the declared parameters in order.  The names
    328      * of the declared parameters are ignored.  The type of
    329      * the declared parameters must match the type of the passed parameters,
    330      * except that the passed parameters might need to be unwrapped to get
    331      * their primitive values.
    332      *
    333      * <P>The filter, import, declared parameters, declared variables, and
    334      * ordering statements are verified for consistency.
    335      *
    336      * <P>Each element in the candidate <code>Collection</code> is examined to
    337      * see that it is assignment compatible to the <code>Class</code> of the
    338      * query.  It is then evaluated by the Boolean expression of the filter.
    339      * The element passes the filter if there exist unique values for all
    340      * variables for which the filter expression evaluates to <code>true</code>.
    341      * <P>Cancellation of the query using cancel() will result in JDOQueryInterruptedException
    342      * being thrown here
    343      * @return the filtered <code>Collection</code>.
    344      * @param parameters the <code>Object</code> array with all of the
    345      * parameters.
    346      */
    347     Object executeWithArray (Object... parameters);
    348
    349     /** Get the <code>PersistenceManager</code> associated with this
    350      * <code>Query</code>.
    351      *
    352      * <P>If this <code>Query</code> was restored from a serialized form, it has
    353      * no <code>PersistenceManager</code>, and this method returns
    354      * <code>null</code>.
    355      * @return the <code>PersistenceManager</code> associated with this
    356      * <code>Query</code>.
    357      */
    358     PersistenceManager getPersistenceManager();
    359
    360     /** Close a query result and release any resources associated with it.  The
    361      * parameter is the return from <code>execute(...)</code> and might have
    362      * iterators open on it.  Iterators associated with the query result are
    363      * invalidated: they return <code>false</code>  to <code>hasNext()</code>
    364      * and throw <code>NoSuchElementException</code> to <code>next()</code>.
    365      * @param queryResult the result of <code>execute(...)</code> on this
    366      * <code>Query</code> instance.
    367      */
    368     void close (Object queryResult);
    369
    370     /** Close all query results associated with this <code>Query</code>
    371      * instance, and release all resources associated with them.  The query
    372      * results might have iterators open on them.  Iterators associated with the
    373      * query results are invalidated:
    374      * they return <code>false</code> to <code>hasNext()</code> and throw
    375      * <code>NoSuchElementException</code> to <code>next()</code>.
    376      */
    377     void closeAll ();
    378
    379     /**
    380      * Set the grouping expressions, optionally including a "having"
    381      * clause. When grouping is specified, each result expression
    382      * must either be an expression contained in the grouping, or an
    383      * aggregate evaluated once per group.
    384      *
    385      * @param	group	a comma-delimited list of expressions, optionally
    386      * followed by the "having" keyword and a boolean expression
    387      * @since	2.0
    388      */
    389     void setGrouping (String group);
    390
    391     /**
    392      * Specify that only the first result of the query should be
    393      * returned, rather than a collection. The execute method will
    394      * return null if the query result size is 0.
    395      * @since 2.0
    396      * @param unique if true, only one element is returned
    397      */
    398     void setUnique (boolean unique);
    399
    400     /**
    401      * Specifies what type of data this query should return. If this
    402      * is unset or set to <code>null</code>, this query returns
    403      * instances of the query's candidate class. If set, this query
    404      * will return expressions, including field values (projections) and
    405      * aggregate function results.
    406      * @param data a comma-delimited list of expressions
    407      * (fields, functions on fields, or aggregate functions)
    408      * to return from this query
    409      * @since 2.0
    410      */
    411     void setResult (String data);
    412
    413     /**
    414      * Specify the type of object in which to return each element of
    415      * the result of invoking {@link #execute} or one of its siblings.
    416      * If the result is not set or set to null, the result class defaults
    417      * to the candidate class of the query. If the result consists of one
    418      * expression, the result class defaults to the type of that expression.
    419      * If the result consists of more than one expression, the result class
    420      * defaults to Object[].
    421      * The result class may be specified to be one of the java.lang classes
    422      * Character, Boolean, Byte, Short, Integer, Long, Float, Double, String,
    423      * or Object[]; or one of the java.math classes BigInteger or BigDecimal;
    424      * or the java.util class Date; or one of the java.sql classes Date,
    425      * Time, or Timestamp; or a user-defined class.
    426      * <P>If there are multiple result expressions, the result class
    427      * must be able to hold all elements of the result specification
    428      * or a JDOUserException is thrown.
    429      *<P>If there is only one result expression, the result class must be
    430      * assignable from the type of the result expression or must be able
    431      * to hold all elements of the result specification. A single value
    432      * must be able to be coerced into the specified result class
    433      * (treating wrapper classes as equivalent to their unwrapped
    434      * primitive types) or by matching. If the result class does not satisfy
    435      * these conditions, a JDOUserException is thrown.
    436      *<P>A constructor of a result class specified in the setResult method
    437      * will be used if the results specification matches the parameters
    438      * of the constructor by position and type. If more than one constructor
    439      * satisfies the requirements, the JDO implementation chooses one of them.
    440      * If no constructor satisfies the results requirements, or if the result
    441      * class is specified via the setResultClass method, the following
    442      * requirements apply:
    443      * <ul>
    444      * <li>A user-defined result class must have a no-args constructor and
    445      * one or more public <code>set</code> or <code>put</code> methods or
    446      * fields.
    447      * <li>Each result expression must match one of:
    448      * <ul>
    449      * <li>a public field that matches the name of the result expression
    450      * and is of the type (treating wrapper types equivalent to primitive
    451      * types) of the result expression;
    452      * <li>or if no public field matches the name and type, a public
    453      * <code>set</code method that returns void and matches the name of the
    454      * result expression and takes a single parameter which is the
    455      * exact type of the result expression;
    456      * <li>or if neither of the above applies,a public method must be found
    457      * with the signature <code>void put(Object, Object)</code>.
    458      * During processing of the results,
    459      * the first argument is the name of the result expression and
    460      * the second argument is the value from the query result.
    461      * </ul>
    462      * </ul>
    463      * Portable result classes do not invoke any persistence behavior
    464      * during their no-args constructor or <code>set</code methods.
    465      * @param cls the result class
    466      * @since 2.0
    467      */
    468     void setResultClass (Class cls);
    469
    470     /**
    471      * Set the range of results to return. The execution of the query is
    472      * modified to return only a subset of results. If the filter would
    473      * normally return 100 instances, and fromIncl is set to 50, and
    474      * toExcl is set to 70, then the first 50 results that would have
    475      * been returned are skipped, the next 20 results are returned and the
    476      * remaining 30 results are ignored. An implementation should execute
    477      * the query such that the range algorithm is done at the data store.
    478      * @param fromIncl 0-based inclusive start index
    479      * @param toExcl 0-based exclusive end index, or
    480      *     {@link Long#MAX_VALUE} for no limit.
    481      * @since 2.0
    482      */
    483     void setRange (long fromIncl, long toExcl);
    484
    485     /**
    486      * Set the range of results to return. The parameter is a String
    487      * containing a comma-separated fromIncl and toExcl. The fromIncl and
    488      * toExcl can be either String representations of long values, or can
    489      * be parameters identified with a leading ":". For example,
    490      * <code>setRange("50, 70");</code> or
    491      * <code>setRange(":from, :to");</code> or
    492      * <code>setRange("50, :to");</code>.
    493      * The execution of the query is
    494      * modified to return only a subset of results. If the filter would
    495      * normally return 100 instances, and fromIncl is set to 50, and
    496      * toExcl is set to 70, then the first 50 results that would have
    497      * been returned are skipped, the next 20 results are returned and the
    498      * remaining 30 results are ignored. An implementation should execute
    499      * the query such that the range algorithm is done at the data store.
    500      * @param fromInclToExcl comma-separated fromIncl and toExcl values
    501      * @see #setRange(long, long)
    502      * @since 2.0
    503      */
    504     void setRange (String fromInclToExcl);
    505
    506     /**
    507      * Add a vendor-specific extension to this query. The key and value
    508      * are not standard.
    509      * An implementation must ignore keys that are not recognized.
    510      * @param key the key of the extension
    511      * @param value the value of the extension
    512      * @since 2.0
    513      */
    514     void addExtension (String key, Object value);
    515
    516     /**
    517      * Set multiple extensions, or use null to clear all extensions.
    518      * Map keys and values are not standard.
    519      * An implementation must ignore entries that are not recognized.
    520      * @param extensions the map of extensions
    521      * @see #addExtension
    522      * @since 2.0
    523      */
    524     void setExtensions (Map extensions);
    525
    526     /**
    527      * Returns the <code>FetchPlan</code> used by this
    528      * <code>Query</code>. Modifications of the returned fetch plan will not
    529      * cause this query's owning <code>PersistenceManager</code>'s
    530      * <code>FetchPlan</code> to be modified.
    531      * @since 2.0
    532      * @return the fetch plan used by this query
    533      */
    534     FetchPlan getFetchPlan ();
    535
    536     /**
    537      * Deletes all the instances of the candidate class that pass the
    538      * filter.
    539      * @see #deletePersistentAll()
    540      * @param parameters for the query
    541      * @return the number of instances of the candidate class that were deleted
    542      * @since 2.0
    543      */
    544     long deletePersistentAll (Object... parameters);
    545
    546     /**
    547      * Deletes all the instances of the candidate class that pass the
    548      * filter.
    549      * @see #deletePersistentAll()
    550      * @param parameters for the query
    551      * @return the number of instances of the candidate class that were deleted
    552      * @since 2.0
    553      */
    554     long deletePersistentAll (Map parameters);
    555
    556     /**
    557      * Deletes all the instances of the candidate class that pass the
    558      * filter. Returns the number of instances of the candidate
    559      * class that were deleted, specifically not including the number
    560      * of dependent and embedded instances.
    561      * <P>Dirty instances of affected classes in the cache are first
    562      * flushed to the datastore. Instances in the cache or brought into
    563      * the cache as a result of executing one of the
    564      * <code>deletePersistentAll</code>
    565      * methods undergo life cycle changes as if <code>deletePersistent</code>
    566      * were called on them.
    567      * <P>Specifically, if the class of deleted instances implements the
    568      * delete callback interface, the corresponding callback methods
    569      * are called on the deleted instances. Similarly, if there are
    570      * lifecycle listeners registered for delete events on affected
    571      * classes, the listener is called for each appropriate deleted instance.
    572      * <P>Before returning control to the application, instances of affected
    573      * classes in the cache are refreshed to reflect whether they were
    574      * deleted from the datastore.
    575      *
    576      * @return the number of instances of the candidate class that were deleted
    577      * @since 2.0
    578      */
    579     long deletePersistentAll ();
    580
    581     /**
    582      * The unmodifiable flag, when set, disallows further
    583      * modification of the query, except for specifying the range,
    584      * result class, and ignoreCache option.
    585      * The unmodifiable flag can also be set in metadata.
    586      * @since 2.0
    587       */
    588     void setUnmodifiable();
    589
    590     /**
    591      * The unmodifiable flag, when set, disallows further
    592      * modification of the query, except for specifying the range,
    593      * result class, and ignoreCache option.
    594      * @return the current setting of the flag
    595      * @since 2.0
    596       */
    597     boolean isUnmodifiable();
    598
    599     /**
    600      * Add a subquery to this query.
    601      * @param sub the subquery to add to this Query
    602      * @param variableDeclaration the name of the variable in the outer query
    603      * to bind the results of the subquery
    604      * @param candidateCollectionExpression the candidate collection
    605      * of the subquery as an expression using terms of the outer query
    606      * @see #addSubquery(Query sub, String variableDeclaration,
    607      *    String candidateCollectionExpression, String... parameters)
    608      * @since 2.1
    609      */
    610     void addSubquery
    611         (Query sub, String variableDeclaration,
    612             String candidateCollectionExpression);
    613
    614     /**
    615      * Add a subquery to this query.
    616      * The String version of the method binds the named expression
    617      * to the parameter implictly or explicitly declared in the
    618      * subquery.
    619      * @param sub the subquery to add to this Query
    620      * @param variableDeclaration the name of the variable
    621      * to be used in this Query
    622      * @param candidateCollectionExpression the candidate collection
    623      * to apply to the subquery
    624      * @param parameter the expression from the outer query to bind
    625      * the parameter in the subquery
    626      * @see #addSubquery(Query sub, String variableDeclaration,
    627      *    String candidateCollectionExpression, String... parameters)
    628      * @since 2.1
    629      */
    630     void addSubquery
    631         (Query sub, String variableDeclaration,
    632          String candidateCollectionExpression, String parameter);
    633
    634     /**
    635      * Add a subquery to this query.
    636      * A subquery is composed as a Query and subsequently attached
    637      * to a different query (the outer query) by calling this method.
    638      * The query parameter instance is unmodified as a result of the
    639      * addSubquery or subsequent execution of the outer query.
    640      * Only some of the query parts are copied for use as the subquery.
    641      * The parts copied include the candidate class, filter, parameter
    642      * declarations, variable declarations, imports, ordering specification,
    643      * uniqueness, result specification, and grouping specification.
    644      * The association with a PersistenceManager, the candidate collection
    645      * or extent, result class, and range limits are not used.
    646      * The String parameters are trimmed of white space.
    647      * The variableDeclaration parameter is the name of the variable
    648      * containing the results of the subquery execution. If the same value
    649      * of variableDeclaration is used to add multiple subqueries, the
    650      * subquery replaces the previous subquery for the same named variable.
    651      * If the subquery parameter is null, the variable is unset,
    652      * effectively making the variable named in the variableDeclaration
    653      * unbound. If the trimmed value is the empty String, or the parameter
    654      * is null, then JDOUserException is thrown.
    655      * The candidateCollectionExpression is the expression from the
    656      * outer query that represents the candidates over which the subquery
    657      * is evaluated. If the trimmed value is the empty String, or the
    658      * parameter is null, then the candidate collection is the extent
    659      * of the candidate class.
    660      * The String... version of the method binds the named expressions in
    661      * turn to parameters in the order in which they are declared in the
    662      * subquery, or in the order they are found in the filter if not
    663      * explicitly declared in the subquery.
    664      * @param sub the subquery to add to this Query
    665      * @param variableDeclaration the name of the variable in the outer query
    666      * to bind the results of the subquery
    667      * @param candidateCollectionExpression the candidate collection
    668      * of the subquery as an expression using terms of the outer query
    669      * @param parameters the expressions from the outer query to bind
    670      * the parameters in the subquery
    671      * @since 2.1
    672      */
    673     void addSubquery
    674         (Query sub, String variableDeclaration,
    675          String candidateCollectionExpression, String... parameters);
    676
    677     /**
    678      * Add a subquery to this query.
    679      * The Map version of the method treats the key of each map entry as
    680      * the name of  the parameter in the subquery, with or without the
    681      * leading ":", and the value as the name of the expression in the
    682      * outer query. If the trimmed expression is the empty String for
    683      * either the parameter or the value of the String[], or for any
    684      * map key or value, that expression is ignored.
    685      * @param sub the subquery to add to this Query
    686      * @param variableDeclaration the name of the variable
    687      * to be used in this Query
    688      * @param candidateCollectionExpression the candidate collection
    689      * to apply to the subquery
    690      * @param parameters the expressions from the outer query to bind
    691      * the parameter in the subquery
    692      * @see #addSubquery(Query sub, String variableDeclaration,
    693      *    String candidateCollectionExpression, String... parameters)
    694      * @since 2.1
    695      */
    696     void addSubquery
    697         (Query sub, String variableDeclaration,
    698          String candidateCollectionExpression, Map parameters);
    699
    700     /**
    701      * Specify a timeout interval (milliseconds) for any read operations
    702      * associated with this query. To unset the explicit timeout for this
    703      * query, specify null. For no timeout, specify 0.
    704      * If the datastore granularity is larger than milliseconds, the
    705      * timeout value will be rounded up to the nearest supported datastore
    706      * value.
    707      * If a read operation hasn't completed within this interval, executeXXX
    708      * will throw a JDODatastoreException.
    709      * If multiple datastore operations are required to complete the query,
    710      * the timeout value applies to each of them individually.
    711      * If the datastore and JDO implementation support timeouts, then
    712      * javax.jdo.option.DatastoreTimeout is returned by
    713      * PersistenceManagerFactory.supportedOptions().
    714      * If timeouts are not supported,this method will throw
    715      * JDOUnsupportedOptionException.
    716      * @since 3.0
    717      * @param interval the timeout interval (milliseconds)
    718      */
    719     void setDatastoreReadTimeoutMillis(Integer interval);
    720
    721     /** Get the effective timeout setting for read operations.
    722      * If the timeout has not been set on this query explicitly, the effective
    723      * datastore read timeout value from the persistence manager is returned.
    724      * @see #setDatastoreReadTimeoutMillis(Integer)
    725      * @see PersistenceManager#setDatastoreReadTimeoutMillis(Integer)
    726      * @return the effective timeout setting (milliseconds).
    727      * @since 3.0
    728      */
    729     Integer getDatastoreReadTimeoutMillis();
    730
    731     /**
    732      * Specify a timeout interval (milliseconds) for any write operations
    733      * associated with this query. To unset the explicit timeout for this
    734      * query, specify null. For no timeout, specify 0.
    735      * If the datastore granularity is larger than milliseconds, the
    736      * timeout value will be rounded up to the nearest supported datastore
    737      * value.
    738      * If a write operation hasn't completed within this interval, deleteXXX
    739      * will throw a JDODatastoreException.
    740      * If multiple datastore operations are required to complete the query,
    741      * the timeout value applies to each of them individually.
    742      * If the datastore and JDO implementation support timeouts, then
    743      * javax.jdo.option.DatastoreTimeout is returned by
    744      * PersistenceManagerFactory.supportedOptions().
    745      * If timeouts are not supported,this method will throw
    746      * JDOUnsupportedOptionException.
    747      * @since 3.0
    748      * @param interval the timeout interval (milliseconds)
    749      */
    750     void setDatastoreWriteTimeoutMillis(Integer interval);
    751
    752     /** Get the effective timeout setting for write operations.
    753      * If the timeout has not been set on this query explicitly, the effective
    754      * datastore write timeout value from the persistence manager is returned.
    755      * @see #setDatastoreWriteTimeoutMillis(Integer)
    756      * @see PersistenceManager#setDatastoreWriteTimeoutMillis(Integer)
    757      * @return the effective timeout setting (milliseconds).
    758      * @since 3.0
    759      */
    760     Integer getDatastoreWriteTimeoutMillis();
    761
    762     /**
    763      * Method to cancel any executing queries.
    764      * If the underlying datastore doesn't support cancellation of queries this will
    765      * throw JDOUnsupportedOptionException.
    766      * If the cancellation fails (e.g in the underlying datastore) then this will throw
    767      * a JDOException.
    768      * @since 3.0
    769      */
    770     void cancelAll();
    771
    772     /**
    773      * Method to cancel an executing query in the specified thread.
    774      * If the underlying datastore doesn't support cancellation of queries this will
    775      * throw JDOUnsupportedOptionException.
    776      * If the cancellation fails (e.g in the underlying datastore) then this will throw
    777      * a JDOException.
    778      * @since 3.0
    779      */
    780     void cancel(Thread thread);
    781
    782     /**
    783      * If <code>true</code>, a lock will be applied to all objects read in this
    784      * query.
    785      * <P>If <code>false</code> then retrieved objects will not be locked.
    786      * If null will fallback to the value for metadata for the class in question.
    787      * @param serialize the value of the serializeRead property
    788      * @since 3.0
    789      */
    790     void setSerializeRead(Boolean serialize);
    791
    792     /**
    793      * Return the current value of the serializeRead property.
    794      * @return the value of the serializeRead property
    795      * @since 3.0
    796      */
    797     Boolean getSerializeRead();
    798 }