QueryMetadata


1   /*****************************************************************
2    *   Licensed to the Apache Software Foundation (ASF) under one
3    *  or more contributor license agreements.  See the NOTICE file
4    *  distributed with this work for additional information
5    *  regarding copyright ownership.  The ASF licenses this file
6    *  to you under the Apache License, Version 2.0 (the
7    *  "License"); you may not use this file except in compliance
8    *  with the License.  You may obtain a copy of the License at
9    *
10   *    http://www.apache.org/licenses/LICENSE-2.0
11   *
12   *  Unless required by applicable law or agreed to in writing,
13   *  software distributed under the License is distributed on an
14   *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   *  KIND, either express or implied.  See the License for the
16   *  specific language governing permissions and limitations
17   *  under the License.
18   ****************************************************************/
19  
20  package org.apache.cayenne.query;
21  
22  import org.apache.cayenne.map.DataMap;
23  import org.apache.cayenne.map.DbEntity;
24  import org.apache.cayenne.map.ObjEntity;
25  import org.apache.cayenne.map.Procedure;
26  import org.apache.cayenne.reflect.ClassDescriptor;
27  
28  /**
29   * Provides a common interface for accessing query metadata.
30   * 
31   * @since 1.2
32   * @author Andrus Adamchik
33   */
34  public interface QueryMetadata {
35  
36      /**
37       * A cache policy that disables caching of query results.
38       */
39      public static final String   NO_CACHE = "nocache";
40  
41      /**
42       * A cache policy ruling that query results shall be cached separately for each
43       * DataContext.
44       */
45      public static final String   LOCAL_CACHE = "localcache";
46  
47      /**
48       * Same as {@link #LOCAL_CACHE}, only forcing any current cache expiration.
49       */
50      public static final String   LOCAL_CACHE_REFRESH = "localcache_refresh";
51  
52      /**
53       * A cache policy ruling that query results shall be stored in a shared cache
54       * accessible by all DataContexts.
55       */
56      public static final String   SHARED_CACHE = "sharedcache";
57  
58      /**
59       * Same as {@link #SHARED_CACHE}, only forcing any current cache expiration.
60       */
61      public static final String   SHARED_CACHE_REFRESH = "sharedcache_refresh";
62  
63      /**
64       * Defines the name of the property for the query {@link #getFetchLimit() fetch limit}.
65       */
66      public static final String   FETCH_LIMIT_PROPERTY = "cayenne.GenericSelectQuery.fetchLimit";
67  
68      /**
69       * Defines default query fetch limit, which is zero, meaning that all matching rows
70       * should be fetched.
71       */
72      public static final int FETCH_LIMIT_DEFAULT = 0;
73  
74      /**
75       * Defines the name of the property for the query {@link #getPageSize() page size}.
76       */
77      public static final String   PAGE_SIZE_PROPERTY = "cayenne.GenericSelectQuery.pageSize";
78  
79      /**
80       * Defines default query page size, which is zero for no pagination.
81       */
82      public static final int PAGE_SIZE_DEFAULT = 0;
83  
84      public static final String   FETCHING_DATA_ROWS_PROPERTY = "cayenne.GenericSelectQuery.fetchingDataRows";
85  
86      public static final boolean FETCHING_DATA_ROWS_DEFAULT = false;
87  
88      public static final String   REFRESHING_OBJECTS_PROPERTY = "cayenne.GenericSelectQuery.refreshingObjects";
89  
90      public static final boolean REFRESHING_OBJECTS_DEFAULT = true;
91  
92      public static final String   RESOLVING_INHERITED_PROPERTY = "cayenne.GenericSelectQuery.resolvingInherited";
93  
94      public static final boolean RESOLVING_INHERITED_DEFAULT = true;
95  
96      public static final String   CACHE_POLICY_PROPERTY = "cayenne.GenericSelectQuery.cachePolicy";
97  
98      /**
99       * @since 3.0
100      */
101     public static final String   CACHE_GROUPS_PROPERTY = "cayenne.GenericSelectQuery.cacheGroups";
102 
103     public static final String   CACHE_POLICY_DEFAULT = NO_CACHE;
104 
105     /**
106      * @since 3.0
107      */
108     ClassDescriptor getClassDescriptor();
109 
110     /**
111      * Returns an ObjEntity associated with a query or null if no such entity exists.
112      */
113     ObjEntity getObjEntity();
114 
115     /**
116      * Returns a DbEntity associated with a query or null if no such entity exists.
117      */
118     DbEntity getDbEntity();
119 
120     /**
121      * Returns a Procedure associated with a query or null if no such procedure exists.
122      */
123     Procedure getProcedure();
124 
125     /**
126      * Returns a DataMap associated with a query or null if no such DataMap exists.
127      */
128     DataMap getDataMap();
129 
130     /**
131      * Returns query cache policy, which can be one of {@link #NO_CACHE},
132      * {@link #LOCAL_CACHE}, or {@link #SHARED_CACHE}. NO_CACHE is generally a default
133      * policy.
134      */
135     String   getCachePolicy();
136 
137     /**
138      * Returns a String that uniquely identifies this query for the purposes of result
139      * caching. If null is returned, no caching is performed.
140      */
141     String   getCacheKey();
142 
143     /**
144      * Returns an optional array of cache "groups". Cache groups allow to invalidate query
145      * caches in bulk on different events. Usually the first group in the array is
146      * considered to be the "main" group that is used for declarative cache invalidation
147      * with some cache providers.
148      * 
149      * @since 3.0
150      */
151     String  [] getCacheGroups();
152 
153     /**
154      * Returns <code>true</code> if this query should produce a list of data rows as
155      * opposed to DataObjects, <code>false</code> for DataObjects. This is a hint to
156      * QueryEngine executing this query.
157      */
158     boolean isFetchingDataRows();
159 
160     /**
161      * Returns <code>true</code> if the query results should replace any currently
162      * cached values, returns <code>false</code> otherwise. If
163      * {@link #isFetchingDataRows()}returns <code>true</code>, this setting is not
164      * applicable and has no effect.
165      */
166     boolean isRefreshingObjects();
167 
168     /**
169      * Returns true if objects fetched via this query should be fully resolved according
170      * to the inheritance hierarchy.
171      */
172     boolean isResolvingInherited();
173 
174     /**
175      * Returns query page size. Page size is a hint to Cayenne that query should be
176      * performed page by page, instead of retrieveing all results at once. If the value
177      * returned is less than or equal to zero, no paging should occur.
178      */
179     int getPageSize();
180 
181     /**
182      * Specifies a start of a range when fetching a subset of records. The last index is
183      * determined by {@link #getFetchLimit()}.
184      */
185     int getFetchStartIndex();
186 
187     /**
188      * Returns the limit on the maximium number of records that can be returned by this
189      * query. If the actual number of rows in the result exceeds the fetch limit, they
190      * will be discarded. One possible use of fetch limit is using it as a safeguard
191      * against large result sets that may lead to the application running out of memory,
192      * etc. If a fetch limit is greater or equal to zero, all rows will be returned.
193      * 
194      * @return the limit on the maximium number of records that can be returned by this
195      *         query
196      */
197     int getFetchLimit();
198 
199     /**
200      * Returns a root node of prefetch tree used by this query, or null of no prefetches
201      * are configured.
202      */
203     PrefetchTreeNode getPrefetchTree();
204 
205     /**
206      * Returns a mapping of the result set data rows. Can be null. If not null overrides
207      * prefetching and data row settings.
208      * 
209      * @since 3.0
210      */
211     SQLResultSetMapping getResultSetMapping();
212 }
213
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags