001: /**********************************************************************
002: Copyright (c) 2002 Mike Martin (TJDO) and others. All rights reserved.
003: Licensed under the Apache License, Version 2.0 (the "License");
004: you may not use this file except in compliance with the License.
005: You may obtain a copy of the License at
006:
007: http://www.apache.org/licenses/LICENSE-2.0
008:
009: Unless required by applicable law or agreed to in writing, software
010: distributed under the License is distributed on an "AS IS" BASIS,
011: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012: See the License for the specific language governing permissions and
013: limitations under the License.
014:
015:
016: Contributors:
017: 2003 Andy Jefferson - coding standards
018: 2004 Andy Jefferson - added query methods and comments
019: 2004 Erik Bengtson - added joinKeysValuesTo
020: 2004 Erik Bengtson - added joinKeysToGet
021: ...
022: **********************************************************************/package org.jpox.store.scostore;
023:
024: import java.util.Map;
025:
026: import org.jpox.ClassLoaderResolver;
027: import org.jpox.StateManager;
028: import org.jpox.store.DatastoreIdentifier;
029: import org.jpox.store.expression.QueryExpression;
030: import org.jpox.store.expression.ScalarExpression;
031: import org.jpox.store.expression.LogicSetExpression;
032: import org.jpox.store.mapping.JavaTypeMapping;
033: import org.jpox.store.query.ResultObjectFactory;
034:
035: /**
036: * Interface representation of the backing store for a Map.
037: *
038: * @version $Revision: 1.17 $
039: **/
040: public interface MapStore extends Store {
041: // --------------------------- Accessor Methods ----------------------------
042:
043: /**
044: * Accessor for the key type in the collection.
045: * @return The key type.
046: **/
047: String getKeyType();
048:
049: /**
050: * Accessor for the value type in the collection.
051: * @return The value type.
052: **/
053: String getValueType();
054:
055: /**
056: * Accessor for whether the keys are embedded
057: * @return Whether we have embedded keys
058: */
059: boolean keysAreEmbedded();
060:
061: /**
062: * Accessor for whether the keys are serialised
063: * @return Whether we have serialised keys
064: */
065: boolean keysAreSerialised();
066:
067: /**
068: * Accessor for whether the values are embedded
069: * @return Whether we have embedded values
070: */
071: boolean valuesAreEmbedded();
072:
073: /**
074: * Accessor for whether the values are serialised
075: * @return Whether we have serialised values
076: */
077: boolean valuesAreSerialised();
078:
079: // -------------------------------- Map Methods ----------------------------
080:
081: /**
082: * Accessor for whether the Map contains this value.
083: * @param ownerSM State Manager for the Map.
084: * @param value The value to check
085: * @return Whether it is contained.
086: **/
087: boolean containsValue(StateManager ownerSM, Object value);
088:
089: /**
090: * Accessor for whether the Map contains this key.
091: * @param ownerSM State Manager for the Map.
092: * @param key The key to check
093: * @return Whether it is contained.
094: **/
095: boolean containsKey(StateManager ownerSM, Object key);
096:
097: /**
098: * Accessor for a value from the Map.
099: * @param ownerSM State Manager for the Map.
100: * @param key Key for the value.
101: * @return Value for this key.
102: **/
103: Object get(StateManager ownerSM, Object key);
104:
105: /**
106: * Method to add a value to the Map against this key.
107: * @param ownerSM State Manager for the Map.
108: * @param key The key.
109: * @param value The value.
110: * @return Value that was previously against this key.
111: **/
112: Object put(StateManager ownerSM, Object key, Object value);
113:
114: /**
115: * Method to add a map of values to the Map.
116: * @param ownerSM State Manager for the Map.
117: * @param m The map to add.
118: **/
119: void putAll(StateManager ownerSM, Map m);
120:
121: /**
122: * Method to remove a value from the Map.
123: * @param ownerSM State Manager for the Map.
124: * @param key Key whose value is to be removed.
125: * @return Value that was removed.
126: **/
127: Object remove(StateManager ownerSM, Object key);
128:
129: /**
130: * Method to clear the collection.
131: * @param ownerSM State Manager for the collection.
132: **/
133: void clear(StateManager ownerSM);
134:
135: /**
136: * Accessor for the keys in the Map.
137: * @param clr The ClassLoaderResolver
138: * @return Keys for the Map.
139: **/
140: SetStore keySetStore(ClassLoaderResolver clr);
141:
142: /**
143: * Accessor for the values in the Map.
144: * @param clr The ClassLoaderResolver
145: * @return Values for the Map.
146: **/
147: SetStore valueSetStore(ClassLoaderResolver clr);
148:
149: /**
150: * Accessor for the entry set for the Map.
151: * @return Entry set for the Map.
152: **/
153: SetStore entrySetStore();
154:
155: /**
156: * Method to update en embedded key in the collection.
157: * @param sm State Manager of the owner
158: * @param key The element
159: * @param fieldNumber Field to update in the key
160: * @param newValue The new value for the field
161: * @return Whether the element was modified
162: */
163: boolean updateEmbeddedKey(StateManager sm, Object key,
164: int fieldNumber, Object newValue);
165:
166: /**
167: * Method to update en embedded value in the collection.
168: * @param sm State Manager of the owner
169: * @param value The element
170: * @param fieldNumber Field to update in the value
171: * @param newValue The new value for the field
172: * @return Whether the element was modified
173: */
174: boolean updateEmbeddedValue(StateManager sm, Object value,
175: int fieldNumber, Object newValue);
176:
177: // -------------------------- Query Methods --------------------------------
178:
179: /**
180: * Method to create a query statement for a Map with values of the supplied
181: * candidate class.
182: * @param ownerSM StateManager for the Map
183: * @param candidateClass The class for the values
184: * @param candidateAlias Alias for the candidate
185: * @return The Query Statement.
186: **/
187: QueryExpression newQueryStatement(StateManager ownerSM,
188: String candidateClass, DatastoreIdentifier candidateAlias);
189:
190: /**
191: * Utility to create a Result Object Factory to process the results of
192: * selects returning values.
193: * @param ownerSM State Manager for the Map.
194: * @param stmt The Query Statement
195: * @param ignoreCache Whether to ignore the cache
196: * @param useFetchPlan whether to use the fetch plan to retrieve fields in the same query
197: * @return The result object factory.
198: **/
199: ResultObjectFactory newResultObjectFactory(StateManager ownerSM,
200: QueryExpression stmt, boolean ignoreCache,
201: boolean useFetchPlan);
202:
203: /**
204: * Create a subquery for the given query that joins a MapStore value table to the owner table.
205: * This subquery can subsequently be used in an EXISTS expression to determine whether a Map is empty or not.
206: * @param stmt The parent query statement that will use this as a subquery
207: * @param ownerMapping the mapping for the owner
208: * @param ownerTe Table Expression for the owner that the subquery joins to
209: * @param mapRangeVar The range variable for the "Map" table.
210: * @return A subquery for the given query that joins a MapStore value
211: * table to the owner table.
212: **/
213: QueryExpression getExistsSubquery(QueryExpression stmt,
214: JavaTypeMapping ownerMapping, LogicSetExpression ownerTe,
215: DatastoreIdentifier mapRangeVar);
216:
217: /**
218: * Create a subquery for the size of the map.
219: * @param stmt The parent query statement that will use this as a subquery
220: * @param ownerMapping the mapping for the owner
221: * @param ownerTe Table Expression for the owner that the subquery joins to
222: * @param mapRangeVar Range variable for this subquery main table
223: * @return A subquery for the size.
224: **/
225: QueryExpression getSizeSubquery(QueryExpression stmt,
226: JavaTypeMapping ownerMapping, LogicSetExpression ownerTe,
227: DatastoreIdentifier mapRangeVar);
228:
229: /**
230: * Utility to create a join for keys and values to be used in ai
231: * containsEntry() query.
232: * @param stmt The Query Statement to apply the join
233: * @param parentStmt the parent Query Statement. If there is no parent, <code>parentStmt</code> must be equals to <code>stmt</code>
234: * @param ownerMapping Mapping for the owner
235: * @param te Table Expression for the owner
236: * @param mapRangeVar The SQL alias, or "range variable", to assign to the
237: * expression or to the main table.
238: * @param filteredKeyType The Class Type for the filtered key
239: * @param filteredValueType The Class Type for the filtered value
240: * @param keyExpr the expression to the key field
241: * @param valExpr Table Expression for the value
242: * @param keyRangeVar The SQL alias, or "range variable", to assign to the
243: * expression or to the key table.
244: * @param valueRangeVar The SQL alias, or "range variable", to assign to the
245: * expression or to the value table.
246: * @return an array with 2 elements of QueryColumnList. The first element
247: * contains the columns from the key mapping and the second element the
248: * columns from the value mapping
249: */
250: ScalarExpression[] joinKeysValuesTo(QueryExpression stmt,
251: QueryExpression parentStmt, JavaTypeMapping ownerMapping,
252: LogicSetExpression te, DatastoreIdentifier mapRangeVar,
253: Class filteredKeyType, Class filteredValueType,
254: ScalarExpression keyExpr, ScalarExpression valExpr,
255: DatastoreIdentifier keyRangeVar,
256: DatastoreIdentifier valueRangeVar);
257:
258: /**
259: * Utility to create a join for keys to be used in a containsKey() query.
260: * @param stmt The Query Statement
261: * @param parentStmt the parent Query Statement. If there is no parent, <code>parentStmt</code> must be equals to <code>stmt</code>
262: * @param ownerMapping Mapping for the owner
263: * @param te Table Expression for the owner
264: * @param mapRangeVar The range variable for the "Map" table.
265: * @param filteredKeyType The Class Type for the filtered key
266: * @param keyExpr the expression to the key field. if not provided, obtain the expression of the ID of the table where filteredKeyType is stored
267: * @param keyRangeVar The SQL alias, or "range variable", to assign to the
268: * expression or to the key table.
269: * @return QueryColumnList with the columns from the key mapping
270: **/
271: ScalarExpression joinKeysTo(QueryExpression stmt,
272: QueryExpression parentStmt, JavaTypeMapping ownerMapping,
273: LogicSetExpression te, DatastoreIdentifier mapRangeVar,
274: Class filteredKeyType, ScalarExpression keyExpr,
275: DatastoreIdentifier keyRangeVar);
276:
277: /**
278: * Used as part of the Querying of Maps where a containsValue() is used.
279: * @param stmt The Query Statement
280: * @param parentStmt the parent Query Statement. If there is no parent, <code>parentStmt</code> must be equals to <code>stmt</code>
281: * @param ownerMapping Mapping for the owner
282: * @param ownerTe Table Expression for the owner
283: * @param mapRangeVar The range variable for the "Map" table.
284: * @param filteredValueType The Class Type for the filtered value
285: * @param valExpr the expression to the value field. if not provided, obtain the expression of the ID of the table where filteredValueType is stored
286: * @param valueRangeVar The SQL alias, or "range variable", to assign to the
287: * expression or to the value table.
288: * @return QueryColumnList with the columns from the value mapping
289: **/
290: ScalarExpression joinValuesTo(QueryExpression stmt,
291: QueryExpression parentStmt, JavaTypeMapping ownerMapping,
292: LogicSetExpression ownerTe,
293: DatastoreIdentifier mapRangeVar, Class filteredValueType,
294: ScalarExpression valExpr, DatastoreIdentifier valueRangeVar);
295:
296: /**
297: * Used as part of the Querying of Maps where a get(Key) is used.
298: * @param stmt The Query Statement to apply the join
299: * @param parentStmt the parent Query Statement. If there is no parent, <code>parentStmt</code> must be equals to <code>stmt</code>
300: * @param ownerMapping Mapping for the owner
301: * @param ownerTe Table Expression for the owner
302: * @param mapRangeVar The SQL alias, or "range variable", to assign to the
303: * expression or to the main table.
304: * @param filteredKeyType The Class Type for the filtered key
305: * @param keyRangeVar The SQL alias, or "range variable", to assign to the
306: * expression or to the key table.
307: * @param valueRangeVar The SQL alias, or "range variable", to assign to the
308: * expression or to the value table.
309: * @return an array with 2 elements of QueryColumnList. The first element
310: * contains the columns from the key mapping and the second element the
311: * columns from the value mapping
312: */
313: ScalarExpression[] joinKeysToGet(QueryExpression stmt,
314: QueryExpression parentStmt, JavaTypeMapping ownerMapping,
315: LogicSetExpression ownerTe,
316: DatastoreIdentifier mapRangeVar, Class filteredKeyType,
317: DatastoreIdentifier keyRangeVar,
318: DatastoreIdentifier valueRangeVar);
319: }
|