All Downloads are FREE. Search and download functionalities are using the official Maven repository.
  • Log In
  • Register

    • javax.jdo.JDOQLTypedQuery Maven / Gradle / Ivy

    Go to download

    The Java Data Objects (JDO) API is a standard interface-based Java model abstraction of persistence, developed as Java Specification Request 243 under the auspices of the Java Community Process.

    The newest version!
    /*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 * 
 *     http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software 
 * distributed under the License is distributed on an "AS IS" BASIS, 
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
 * See the License for the specific language governing permissions and 
 * limitations under the License.
 */
package javax.jdo;

import java.io.Closeable;
import java.io.Serializable;
import java.util.Collection;
import java.util.List;
import java.util.Map;

import javax.jdo.query.BooleanExpression;
import javax.jdo.query.CharacterExpression;
import javax.jdo.query.CollectionExpression;
import javax.jdo.query.DateExpression;
import javax.jdo.query.DateTimeExpression;
import javax.jdo.query.Expression;
import javax.jdo.query.IfThenElseExpression;
import javax.jdo.query.ListExpression;
import javax.jdo.query.MapExpression;
import javax.jdo.query.NumericExpression;
import javax.jdo.query.OrderExpression;
import javax.jdo.query.PersistableExpression;
import javax.jdo.query.StringExpression;
import javax.jdo.query.TimeExpression;

/**
 * Interface for a type-safe refactorable JDOQL query, using a fluent API, based around expressions.
 * Note that a JDOQLTypedQuery only supports named parameters, and the values of these parameters
 * should be set using the relevant setter methods prior to execution, and that the values for the 
 * parameters will only be retained until the subsequent query execution.
 * 
 * @param  candidate type for this query
 */
public interface JDOQLTypedQuery extends Serializable, Closeable {
    public static final String QUERY_CLASS_PREFIX = "Q";

    /**
     * Method to return an expression for the candidate of the query.
     * Cast the returned expression to the candidate "Q" type to be able to call methods on it.
     * This calls the method "Q{type}.candidate(null)"
     * The preference is to use the "Q{type}.candidate()" method for real type-safe handling.
     * @return Expression for the candidate
     */
    PersistableExpression candidate();

    /**
     * Method to return a parameter for the query.
     * Cast the returned parameter to the right type to be able to call methods on it.
     * The preference is to use the "xxxParameter(String)" methods for real type-safe handling.
     * @param name Name of the parameter
     * @param type Java type of the parameter
     * @return Expression for the parameter
     * @param 
     type for the parameter
     */
    
     Expression
     parameter(String name, Class
     type);

    /**
     * Method to return a string parameter for the query.
     * @param name Name of the parameter
     * @return StringExpression for the parameter
     */
    StringExpression stringParameter(String name);

    /**
     * Method to return a character parameter for the query.
     * @param name Name of the parameter
     * @return Expression for the parameter
     */
    CharacterExpression characterParameter(String name);

    /**
     * Method to return a numeric parameter for the query.
     * @param name Name of the parameter
     * @return NumericExpression for the parameter
     */
    NumericExpression numericParameter(String name);

    /**
     * Method to return a numeric parameter for the query.
     * @param name Name of the parameter
     * @param type Type of the numeric parameter
     * @param  Type for the numeric parameter
     * @return NumericExpression for the parameter
     */
    @SuppressWarnings("unchecked")
    default  NumericExpression numericParameter(String name, Class type) {
        return (NumericExpression)numericParameter(name);
    }

    /**
     * Method to return a date parameter for the query.
     * @param name Name of the parameter
     * @return Expression for the parameter
     */
    DateExpression dateParameter(String name);

    /**
     * Method to return a time parameter for the query.
     * @param name Name of the parameter
     * @return Expression for the parameter
     */
    TimeExpression timeParameter(String name);

    /**
     * Method to return a datetime parameter for the query.
     * @param name Name of the parameter
     * @return Expression for the parameter
     */
    DateTimeExpression datetimeParameter(String name);

    /**
     * Method to return a collection parameter for the query.
     * @param name Name of the parameter
     * @return Expression for the parameter
     */
    CollectionExpression collectionParameter(String name);

    /**
     * Method to return a collection parameter for the query.
     *
     * @param name Name of the parameter
     * @param elementType Element type of the collection parameter
     * @param  Element type for the collection parameter
     * @return Expression for the parameter
     */
    @SuppressWarnings("unchecked")
    default  CollectionExpression, E> collectionParameter(String name, Class elementType) {
        return (CollectionExpression, E>)collectionParameter(name);
    }

    /**
     * Method to return a map parameter for the query.
     * @param name Name of the parameter
     * @return Expression for the parameter
     */
    MapExpression mapParameter(String name);

    /**
     * Method to return a map parameter for the query.
     * @param name Name of the parameter
     * @param keyType Key type of the map parameter
     * @param valueType Value type of the map parameter
     * @param  Key type for the map parameter
     * @param  Value type for the map parameter
     * @return Expression for the parameter
     */
    @SuppressWarnings("unchecked")
    default  MapExpression, K, V> mapParameter(String name, Class keyType, Class valueType) {
        return (MapExpression, K, V>)mapParameter(name);
    }

    /**
     * Method to return a list parameter for the query.
     * @param name Name of the parameter
     * @return Expression for the parameter
     */
    ListExpression listParameter(String name);

    /**
     * Method to return a list parameter for the query.
     * @param name Name of the parameter
     * @param elementType Element type of the list parameter
     * @param  Element type for the list parameter
     * @return Expression for the parameter
     */
    @SuppressWarnings("unchecked")
    default  ListExpression, E> listParameter(String name, Class elementType) {
        return (ListExpression, E>)listParameter(name);
    }

    /**
     * Method to return a variable for this query.
     * Cast the returned variable to the right type to be able to call methods on it.
     * @param name Name of the variable
     * @param type Type of the variable
     * @return Expression for the variable
     * @param  type for the variable
     */
     Expression variable(String name, Class type);

    /**
     * Method to set the candidates to use over which we are querying.
     * If no candidates are set then the query is performed on the datastore.
     * @param candidates The candidates
     * @return The query
     */
    JDOQLTypedQuery setCandidates(Collection candidates);

    /**
     * Method to remove subclasses (of the candidate) from the query
     * @return The query
     */
    JDOQLTypedQuery excludeSubclasses();

    /**
     * Method to include subclasses (of the candidate) to the query
     * @return The query
     */
    JDOQLTypedQuery includeSubclasses();

    /**
     * Method to set the filter of the query.
     * @param expr Filter expression
     * @return The query
     */
    JDOQLTypedQuery filter(BooleanExpression expr);

    /**
     * Method to return an "IF (...) ... ELSE ..." expression for use in this query.
     * @param type The type returned by the IfElse.
     * @param cond The if condition
     * @param thenValueExpr Expression for value to return when the if expression is met
     * @param elseValueExpr Expression for value to return when the if expression is not met
     * @param  type for the IfThenElseExpression
     * @return The IfThenElse expression
     */
     IfThenElseExpression ifThenElse(Class type, BooleanExpression cond,
                                           Expression thenValueExpr, Expression elseValueExpr);

    /**
     * Method to return an "IF (...) ... ELSE ..." expression for use in this query.
     * @param cond The if condition
     * @param thenValue Value to return when the if expression is met
     * @param elseValueExpr Expression to return when the if expression is not met
     * @param  type for the IfThenElseExpression
     * @return The IfThenElse expression
     */
     IfThenElseExpression ifThenElse(BooleanExpression cond, V thenValue, Expression elseValueExpr);

    /**
     * Method to return an "IF (...) ... ELSE ..." expression for use in this query.
     * @param cond The if condition
     * @param thenValueExpr Expression to return when the if expression is met
     * @param elseValue Value to return when the if expression is not met
     * @param  type for the IfThenElseExpression
     * @return The IfThenElse expression
     */
     IfThenElseExpression ifThenElse(BooleanExpression cond, Expression thenValueExpr, V elseValue);

    /**
     * Method to return an "IF (...) ... ELSE ..." expression for use in this query.
     * @param cond The if condition
     * @param thenValue Value to return when the if expression is met
     * @param elseValue Value to return when the if expression is not met
     * @param  type for the IfThenElseExpression
     * @return The IfThenElse expression
     */
     IfThenElseExpression ifThenElse(BooleanExpression cond, V thenValue, V elseValue);

    /**
     * Method to return an "IF (...) ... ELSE ..." expression for use in this query.
     * @param type The type returned by the IfElse.
     * @param cond The if condition
     * @param thenValueExpr Expression for value to return when the if expression is met
     * @param  type for the IfThenElseExpression
     * @return The IfThenElse expression
     */
     IfThenElseExpression ifThen(Class type, BooleanExpression cond, Expression thenValueExpr);

    /**
     * Method to return an "IF (...) ... ELSE ..." expression for use in this query.
     * @param cond The if condition
     * @param thenValue Value to return when the if expression is met
     * @param  type for the IfThenElseExpression
     * @return The IfThenElse expression
     */
     IfThenElseExpression ifThen(BooleanExpression cond, V thenValue);

    /**
     * Method to set the grouping(s) for the query.
     * @param exprs Grouping expression(s)
     * @return The query
     */
    JDOQLTypedQuery groupBy(Expression... exprs);

    /**
     * Method to set the having clause of the query.
     * @param expr Having expression
     * @return The query
     */
    JDOQLTypedQuery having(Expression expr);

    /**
     * Method to set the ordering of the query.
     * @param orderExprs Ordering expression(s)
     * @return The query
     */
    JDOQLTypedQuery orderBy(OrderExpression... orderExprs);

    /**
     * Method to set the result of the query.
     * @param distinct Whether results are distinct
     * @param exprs The result expressions
     * @return The query
     */
    JDOQLTypedQuery result(boolean distinct, Expression... exprs);

    /**
     * Method to set the range of any required results, using expressions.
     * @param lowerInclExpr The position of the first result (inclusive)
     * @param upperExclExpr The position of the last result (exclusive)
     * @return The query
     */
    JDOQLTypedQuery range(NumericExpression lowerInclExpr, NumericExpression upperExclExpr);

    /**
     * Method to set the range of any required results, using long values.
     * @param lowerIncl The position of the first result (inclusive)
     * @param upperExcl The position of the last result (exclusive)
     * @return The query
     */
    JDOQLTypedQuery range(long lowerIncl, long upperExcl);

    /**
     * Method to set the range of any required results, using parameters (expressions).
     * @param paramLowerInclExpr Expression for a parameter defining the position of the first result (inclusive)
     * @param paramUpperExclExpr Expression for a parameter defining the position of the last result (exclusive)
     * @return The query
     */
    JDOQLTypedQuery range(Expression paramLowerInclExpr, Expression paramUpperExclExpr);

    /**
     * Method to return a subquery for use in this query using the same candidate class as this query.
     * To obtain the expression for the subquery to link it back to this query, call "result(...)" on the subquery.
     * @param candidateAlias Alias for the candidate
     * @return The subquery
     */
    JDOQLTypedSubquery subquery(String candidateAlias);

    /**
     * Method to return a subquery for use in this query.
     * To obtain the expression for the subquery to link it back to this query, call "result(...)" on the subquery.
     * @param candidate Candidate for the subquery
     * @param candidateAlias Alias for the candidate
     * @return The subquery
     * @param  Candidate type for subquery
     */
     JDOQLTypedSubquery subquery(Class candidate, String candidateAlias);

    /**
     * Method to return a correlated subquery for use in this query.
     * The candidate collection of the subquery is defined using a collection relationship of the outer query.
     * To obtain the expression for the subquery to link it back to this query, call "result(...)" on the subquery.
     * @param candidateCollection Expression defining the candidate collection for the subquery
     * @param candidate Candidate for the subquery
     * @param candidateAlias Alias for the candidate
     * @return The subquery
     * @param  Candidate type for subquery
     */
     JDOQLTypedSubquery subquery(CollectionExpression, E> candidateCollection, Class candidate, String candidateAlias);

    /**
     * Method to set the named parameters on this query prior to execution.
     * All parameter values specified in this method will only be retained until the subsequent query execution.
     * @param namedParamMap The map of parameter values keyed by their names.
     * @return This query
     */
    JDOQLTypedQuery setParameters(Map namedParamMap);

    /**
     * Method to set a parameter value for the specified (parameter) expression when executing the query.
     * All parameter values specified in this method will only be retained until the subsequent query execution.
     * @param paramExpr Expression defining the parameter
     * @param value The value
     * @return The query
     */
    JDOQLTypedQuery setParameter(Expression paramExpr, Object value);

    /**
     * Method to set the value for a named parameter for use when executing the query.
     * All parameter values specified in this method will only be retained until the subsequent query execution.
     * @param paramName Parameter name
     * @param value The value
     * @return The query
     */
    JDOQLTypedQuery setParameter(String paramName, Object value);

    /**
     * Method to execute the query where there are (potentially) multiple rows and we are returning the candidate type.
     * Any parameters required should be set prior to calling this method, using one of the setParameter methods.
     * 
    Calling this method with a result being specified will result in JDOUserException being thrown.
     * @return The results
     */
    List executeList();

    /**
     * Method to execute the query where there is a single row and we are returning the candidate type.
     * Any parameters required should be set prior to calling this method, using one of the setParameter methods.
     * 
    Calling this method with a result being specified will result in JDOUserException being thrown.
     * @return The result
     */
    T executeUnique();

    /**
     * Method to execute the query where there are (potentially) multiple rows and we are returning either the result type.
     * Any parameters required should be set prior to calling this method, using one of the setParameters methods.
     * 
    Calling this method with no result being specified will result in JDOUserException being thrown.
     * @param resultCls Result class
     * @return The results
     * @param  result type
     */
     List executeResultList(Class resultCls);

    /**
     * Method to execute the query where there is a single row and we are returning either the result type.
     * Any parameters required should be set prior to calling this method, using one of the setParameter methods.
     * 
    Calling this method with no result being specified will result in JDOUserException being thrown.
     * @param resultCls Result class
     * @return The result
     * @param  result type
     */
     R executeResultUnique(Class resultCls);

    /**
     * Method to execute the query where there are (potentially) multiple rows and we have a result defined but no result class.
     * Any parameters required should be set prior to calling this method, using one of the setParameter methods.
     * 
    Calling this method with no result being specified will result in JDOUserException being thrown.
     * @return The results
     */
    List executeResultList();

    /**
     * Method to execute the query where there is a single row and we have a result defined but no result class.
     * Any parameters required should be set prior to calling this method, using one of the setParameters methods.
     * 
    Calling this method with no result being specified will result in JDOUserException being thrown.
     * @return The results
     */
    Object executeResultUnique();

    /**
     * Method to execute the query deleting the affected instances.
     * Any parameters required should be set prior to calling this method, using one of the setParameter methods.
     * @return The number of objects deleted
     */
    long deletePersistentAll();

    /**
     * Get the effective timeout setting for read operations.
     * If the timeout has not been set on this query explicitly, the effective
     * datastore read timeout value from the persistence manager is returned.
     * @see PersistenceManager#setDatastoreReadTimeoutMillis(Integer)
     * @return the effective timeout setting (milliseconds).
     */
    Integer getDatastoreReadTimeoutMillis();

    /**
     * Set the datastore read timeout (millis).
     * @param interval The interval
     * @return This query
     */
    JDOQLTypedQuery datastoreReadTimeoutMillis(Integer interval);

    /**
     * Get the effective timeout setting for write operations. 
     * If the timeout has not been set on this query explicitly, the effective
     * datastore write timeout value from the persistence manager is returned.
     * @see PersistenceManager#setDatastoreWriteTimeoutMillis(Integer)
     * @return the effective timeout setting (milliseconds).
     */
    Integer getDatastoreWriteTimeoutMillis();

    /**
     * Set the datastore write timeout (millis).
     * @param interval The interval
     * @return This query
     */
    JDOQLTypedQuery datastoreWriteTimeoutMillis(Integer interval);

    /**
     * Return the current value of the serializeRead property.
     * @return the value of the serializeRead property
     */
    Boolean getSerializeRead();

    /**
     * Set whether we to lock all objects read by this query.
     * @param serialize Whether to lock
     * @return This query
     */
    JDOQLTypedQuery serializeRead(Boolean serialize);

    /**
     * The unmodifiable flag, when set, disallows further modification of the query, 
     * except for specifying the range, result class, and ignoreCache option.
     * @return the current setting of the flag
     */
    boolean isUnmodifiable();

    /**
     * Set to make this query unmodifiable hereafter.
     * @return This query
     */
    JDOQLTypedQuery unmodifiable();
    
    /**
     * Get the ignoreCache option setting.
     * @return the ignoreCache option setting.
     */
    boolean getIgnoreCache();

    /**
     * Set whether we to ignore the cache with this query.
     * @param flag Whether to ignore the cache
     * @return This query
     */
    JDOQLTypedQuery ignoreCache(boolean flag);

    /**
     * Specify an extension for this query.
     * @param key The extension key
     * @param value The extension value
     * @return This query
     */
    JDOQLTypedQuery extension(String key, Object value);

    /**
     * Specify a map of extensions for this query.
     * @param values The extension map of keys and values
     * @return This query
     */
    JDOQLTypedQuery extensions(Map values);

    /**
     * Save the query, as it is currently defined, as a named query under the specified name.
     * If a named query already exists under this name (either defined in metadata, or previously saved)
     * then it will be overwritten.
     * @param name Name to save it under.
     * @return This query
     */
    JDOQLTypedQuery saveAsNamedQuery(String name);

    /**
     * Accessor for the PersistenceManager for this query
     * @return The PersistenceManager
     */
    PersistenceManager getPersistenceManager();

    /**
     * Accessor for the FetchPlan for this query
     * @return The FetchPlan
     */
    FetchPlan getFetchPlan();

    /**
     * Method to cancel any executing queries.
     * If the underlying datastore doesn't support cancellation of queries this will throw JDOUnsupportedOptionException.
     * If the cancellation fails (e.g in the underlying datastore) then this will throw a JDOException.
     */
    void cancelAll();

    /**
     * Method to cancel an executing query in the specified thread.
     * If the underlying datastore doesn't support cancellation of queries this will throw JDOUnsupportedOptionException.
     * If the cancellation fails (e.g in the underlying datastore) then this will throw a JDOException.
     * @param thread The thread to cancel
     */
    void cancel(Thread thread);

    /**
     * Method to close the specified query result.
     * @param result The result
     */
    void close(Object result);

    /**
     * Method to close all query results from this query.
     */
    void closeAll();

    /**
     * Method to return the equivalent String form of this query (if applicable for the query language).
     * @return The single-string form of this query
     */
    String toString();
}
    
    
    
    

    




    
    
    © 2015 - 2025 Weber Informatics LLC | Privacy Policy