001: /**********************************************************************
002: Copyright (c) 2004 Andy Jefferson 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: ...
018: **********************************************************************/package org.jpox.store.scostore;
019:
020: import java.util.Collection;
021: import java.util.Iterator;
022:
023: import org.jpox.StateManager;
024: import org.jpox.store.DatastoreIdentifier;
025: import org.jpox.store.expression.QueryExpression;
026: import org.jpox.store.expression.ScalarExpression;
027: import org.jpox.store.expression.LogicSetExpression;
028: import org.jpox.store.mapping.JavaTypeMapping;
029: import org.jpox.store.query.ResultObjectFactory;
030:
031: /**
032: * Interface representation of the backing store for a Collection.
033: *
034: * @version $Revision: 1.17 $
035: **/
036: public interface CollectionStore extends Store {
037: // --------------------------- Accessor Methods ----------------------------
038:
039: /**
040: * Accessor for the element type in the collection.
041: * @return The element type.
042: **/
043: String getElementType();
044:
045: /**
046: * Accessor for whether the store utilises an order mapping.
047: * An order mapping is used to allow for ordering of elements or to allow duplicates.
048: * @return Whether it uses an order mapping.
049: */
050: boolean hasOrderMapping();
051:
052: /**
053: * Method to update en embedded element in the collection.
054: * @param sm State Manager of the owner
055: * @param element The element
056: * @param fieldNumber Field to update in the element
057: * @param value The new value for the field
058: * @return Whether the element was modified
059: */
060: boolean updateEmbeddedElement(StateManager sm, Object element,
061: int fieldNumber, Object value);
062:
063: // -------------------------- Collection Methods ---------------------------
064:
065: /**
066: * Accessor for an iterator for the collection.
067: * @param sm State Manager for the collection.
068: * @return Iterator for the collection.
069: **/
070: Iterator iterator(StateManager sm);
071:
072: /**
073: * Accessor for the size of the collection.
074: * @param sm State Manager for the collection.
075: * @return The size of the collection.
076: **/
077: int size(StateManager sm);
078:
079: /**
080: * Method to check if an element exists in the collection.
081: * @param sm State Manager for the collection.
082: * @param element Element to check
083: * @return Whether the element exists in the collection.
084: **/
085: boolean contains(StateManager sm, Object element);
086:
087: /**
088: * Method to add an element to the collection.
089: * @param sm State Manager for the collection.
090: * @param element Element to add
091: * @param size Current size of the collection if known. -1 if not known
092: * @return Whether the element was added ok
093: */
094: boolean add(StateManager sm, Object element, int size);
095:
096: /**
097: * Method to add a collection of elements to the collection.
098: * @param sm State Manager for the collection.
099: * @param elements Elements to add
100: * @param size Current size of collection (if known). -1 if not known
101: * @return Whether the elements were added ok
102: */
103: boolean addAll(StateManager sm, Collection elements, int size);
104:
105: /**
106: * Method to remove an element from the collection.
107: * @param sm State Manager for the collection.
108: * @param element Element to remove
109: * @param size Current size of collection if known. -1 if not known
110: * @param allowDependentField Whether to allow any cascading delete actions to be fired from this removal
111: * @return Whether the element was removed ok
112: */
113: boolean remove(StateManager sm, Object element, int size,
114: boolean allowDependentField);
115:
116: /**
117: * Method to remove a collection of elements from the collection.
118: * @param sm State Manager for the collection.
119: * @param elements Element to remove
120: * @param size Current size of collection if known. -1 if not known
121: * @return Whether the elements were removed ok
122: */
123: boolean removeAll(StateManager sm, Collection elements, int size);
124:
125: /**
126: * Method to clear the collection.
127: * @param sm State Manager for the collection.
128: **/
129: void clear(StateManager sm);
130:
131: // -------------------------- Query Methods --------------------------------
132:
133: /**
134: * Method to return a new Query Statement containing the candidate class.
135: * @param sm State Manager for the collection.
136: * @param candidateClass Class of the elements.
137: * @param candidateAlias Alias for the candidate
138: * @return The Query Statement.
139: **/
140: QueryExpression newQueryStatement(StateManager sm,
141: String candidateClass, DatastoreIdentifier candidateAlias);
142:
143: /**
144: * Method to return an object factory for processing query statements.
145: * @param sm State Manager for the collection.
146: * @param stmt The Query Statement.
147: * @param ignoreCache Whether to ignore the cache.
148: * @param useFetchPlan whether to use the fetch plan to retrieve fields in the same query
149: * @return The Persistent object factory.
150: **/
151: ResultObjectFactory newResultObjectFactory(StateManager sm,
152: QueryExpression stmt, boolean ignoreCache,
153: boolean useFetchPlan);
154:
155: /**
156: * Create a subquery for the given query that selects elements, joining to the owner table.
157: * This subquery can subsequently be used in an EXISTS expression to determine whether a Collection is empty.
158: * @param parentStmt Parent query statement for this subquery
159: * @param ownerMapping Id mapping for the owner
160: * @param ownerTableExpr Table Expression for the owner that the subquery joins to
161: * @param existsTableAlias Alias for this subquery main table
162: * @return Subquery returning the existence of elements
163: */
164: QueryExpression getExistsSubquery(QueryExpression parentStmt,
165: JavaTypeMapping ownerMapping,
166: LogicSetExpression ownerTableExpr,
167: DatastoreIdentifier existsTableAlias);
168:
169: /**
170: * Create a subquery for the size of the collection.
171: * @param parentStmt Parent query statement for this subquery
172: * @param ownerMapping Id mapping for the owner
173: * @param ownerTableExpr Table Expression for the owner in the parent statement that the subquery joins to
174: * @param sizeTableAlias Alias for this subquery main table
175: * @return Subquery returning the size
176: */
177: QueryExpression getSizeSubquery(QueryExpression parentStmt,
178: JavaTypeMapping ownerMapping,
179: LogicSetExpression ownerTableExpr,
180: DatastoreIdentifier sizeTableAlias);
181:
182: /**
183: * Method used in queries when contains() has been invoked.
184: * @param stmt The Query Statement
185: * @param parentStmt the parent Query Statement. If there is no parent, "parentStmt" must be equals to "stmt".
186: * @param ownerMapping the mapping for the owner
187: * @param ownerTableExpr Table Expression for the owner
188: * @param collectionTableAlias Alias for the "Collection" table.
189: * @param filteredElementType The Class Type for the filtered element
190: * @param elementExpr The Expression for the element
191: * @param elementTableAlias The SQL alias to assign to the element table expression
192: * @param existsQuery Whether this is joining for an EXISTS query
193: * @return expression to the join
194: **/
195: ScalarExpression joinElementsTo(QueryExpression stmt,
196: QueryExpression parentStmt, JavaTypeMapping ownerMapping,
197: LogicSetExpression ownerTableExpr,
198: DatastoreIdentifier collectionTableAlias,
199: Class filteredElementType, ScalarExpression elementExpr,
200: DatastoreIdentifier elementTableAlias, boolean existsQuery);
201: }
|