Package com.sun.jdo.api.persistence.support

Interface Query

  • All Superinterfaces:
    Serializable
    All Known Implementing Classes:
    QueryImpl
    public interface Query
extends Serializable
    The Query interface allows applications to obtain persistent instances from the data store. The @link PersistenceManager is the factory for Query instances. There may be many Query instances associated with a PersistenceManager. Multiple queries might be executed simultaneously by different threads, but the implementation might choose to execute them serially. In either case, the implementation must be thread safe.

    There are three required elements in a Query: the class of the candidate instances, the candidate collection of instances, and the filter.

    There are optional elements: parameter declarations, variable declarations, import statements, and an ordering specification.

    Version:
    0.1
    Author:
    Craig Russell

    • Method Detail

      • setClass

        void setClass​(Class cls)
        Set the class of the candidate instances of the query.

        The class is a PersistenceCapable class which specifies the class of the candidates of the query. Elements of the candidate collection that are of the specified class are filtered before being put into the result Collection.

        Parameters:
        cls - the Class of the candidate instances.

      • setCandidates

        void setCandidates​(Collection pcs)
        Set the candidate Collection to query.
        Parameters:
        pcs - the Candidate collection.

      • setFilter

        void setFilter​(String filter)
        Set the filter for the query. The filter is a Java-like boolean expression used to select elements of the candidate Collection.
        Parameters:
        filter - the query filter.

      • declareImports

        void declareImports​(String imports)
        Set the import statements to be used to identify the package name of variables or parameters.
        Parameters:
        imports - import statements separated by semicolons.

      • declareParameters

        void declareParameters​(String parameters)
        Set the parameter list for query execution. The types and names of execution parameters are specified as a String separated by commas, similar to formal method declarations.
        Parameters:
        parameters - the list of parameters separated by commas.

      • declareVariables

        void declareVariables​(String variables)
        Declare the unbound variables to be used in the query.
        Parameters:
        variables - the variables separated by semicolons.

      • setOrdering

        void setOrdering​(String ordering)
        Bind the ordering declarations to the query instance. The ordering consists of one or more ordering declarations separated by commas. Each ordering declaration is the name of the field in the name scope of the candidate class followed by one of the following words: ascending or descending.
        Parameters:
        ordering - the ordering declarations separated by comma.

      • setResult

        void setResult​(String result)
        Set the result of the query.

        The query result is an optional keyword distinct followed by a Java expression, which tells what values are to be returned by the JDO query. If the result is not specified, then it defaults to "distinct this", which has the effect of returning the elements of the candidates that match the filter.

      • setPrefetchEnabled

        void setPrefetchEnabled​(boolean prefetchEnabled)
        Sets the prefetchEnabled option. The prefetchEnabled option specifies whether prefetch of relationship fields should be enabled for this query. The prefetch is enabled by default if such fields are part of DFG. A user needs to explicitely disable prefetch for any particular query if the related instances will not be used in this transaction.
        Parameters:
        prefetchEnabled - the setting of the prefetchEnabled option.

      • setIgnoreCache

        void setIgnoreCache​(boolean ignoreCache)
        Set the ignoreCache option. The ignoreCache option setting specifies whether the query should execute entirely in the back end, instead of in the cache.
        Parameters:
        ignoreCache - the setting of the ignoreCache option.

      • getIgnoreCache

        boolean getIgnoreCache()
        Get the ignoreCache option setting.
        Returns:
        the ignoreCache option setting.
        See Also:
        setIgnoreCache(boolean)

      • compile

        void compile()
        Verify the elements of the query and provide a hint to the query to prepare and optimize an execution plan.

      • execute

        Object execute()
        Execute the query and return the filtered Collection.
        Returns:
        the filtered Collection.
        See Also:
        (Object[] parameters)

      • execute

        Object execute​(Object p1)
        Execute the query and return the filtered Collection.
        Parameters:
        p1 - the value of the first parameter declared.
        Returns:
        the filtered Collection.
        See Also:
        (Object[] parameters)

      • execute

        Object execute​(Object p1,
               Object p2)
        Execute the query and return the filtered Collection.
        Parameters:
        p1 - the value of the first parameter declared.
        p2 - the value of the second parameter declared.
        Returns:
        the filtered Collection.
        See Also:
        (Object[] parameters)

      • execute

        Object execute​(Object p1,
               Object p2,
               Object p3)
        Execute the query and return the filtered Collection.
        Parameters:
        p1 - the value of the first parameter declared.
        p2 - the value of the second parameter declared.
        p3 - the value of the third parameter declared.
        Returns:
        the filtered Collection.
        See Also:
        (Object[] parameters)

      • executeWithMap

        Object executeWithMap​(Map parameters)
        Execute the query and return the filtered Collection.
        Parameters:
        parameters - the Map containing all of the parameters.
        Returns:
        the filtered Collection.
        See Also:
        (Object[] parameters)

      • executeWithArray

        Object executeWithArray​(Object[] parameters)
        Execute the query and return the filtered Collection.

        The execution of the query obtains the values of the parameters and matches them against the declared parameters in order. The type of the declared parameters must match the type of the passed parameters, except that the passed parameters might need to be unwrapped to get their primitive values.

        The filter, import, declared parameters, declared variables, and ordering statements are verified for consistency.

        Each element in the candidate Collection is examined to see that it is assignment compatible to the Class of the query. It is then evaluated by the boolean expression of the filter. The element passes the filter if there exist unique values for all variables for which the filter expression evaluates to true.

        Parameters:
        parameters - the Object array with all of the parameters.
        Returns:
        the filtered Collection.

      • getPersistenceManager

        PersistenceManager getPersistenceManager()
        Get the PersistenceManager associated with this Query.

        If this Query has no PersistenceManager return null.

        Returns:
        the PersistenceManager associated with this Query.