001: //$Id: Session.java 9652 2006-03-17 18:59:03Z steve.ebersole@jboss.com $
002: package org.hibernate.classic;
003:
004: import java.io.Serializable;
005: import java.util.Collection;
006: import java.util.Iterator;
007: import java.util.List;
008:
009: import org.hibernate.HibernateException;
010: import org.hibernate.Query;
011: import org.hibernate.type.Type;
012:
013: /**
014: * An extension of the <tt>Session</tt> API, including all
015: * deprecated methods from Hibernate2. This interface is
016: * provided to allow easier migration of existing applications.
017: * New code should use <tt>org.hibernate.Session</tt>.
018: * @author Gavin King
019: */
020: public interface Session extends org.hibernate.Session {
021:
022: /**
023: * Copy the state of the given object onto the persistent object with the same
024: * identifier. If there is no persistent instance currently associated with
025: * the session, it will be loaded. Return the persistent instance. If the
026: * given instance is unsaved or does not exist in the database, save it and
027: * return it as a newly persistent instance. Otherwise, the given instance
028: * does not become associated with the session.
029: *
030: * @deprecated use {@link org.hibernate.Session#merge(Object)}
031: *
032: * @param object a transient instance with state to be copied
033: * @return an updated persistent instance
034: */
035: public Object saveOrUpdateCopy(Object object)
036: throws HibernateException;
037:
038: /**
039: * Copy the state of the given object onto the persistent object with the
040: * given identifier. If there is no persistent instance currently associated
041: * with the session, it will be loaded. Return the persistent instance. If
042: * there is no database row with the given identifier, save the given instance
043: * and return it as a newly persistent instance. Otherwise, the given instance
044: * does not become associated with the session.
045: *
046: * @deprecated with no replacement
047: *
048: * @param object a persistent or transient instance with state to be copied
049: * @param id the identifier of the instance to copy to
050: * @return an updated persistent instance
051: */
052: public Object saveOrUpdateCopy(Object object, Serializable id)
053: throws HibernateException;
054:
055: /**
056: * Copy the state of the given object onto the persistent object with the same
057: * identifier. If there is no persistent instance currently associated with
058: * the session, it will be loaded. Return the persistent instance. If the
059: * given instance is unsaved or does not exist in the database, save it and
060: * return it as a newly persistent instance. Otherwise, the given instance
061: * does not become associated with the session.
062: *
063: * @deprecated use {@link org.hibernate.Session#merge(String, Object)}
064: *
065: * @param object a transient instance with state to be copied
066: * @return an updated persistent instance
067: */
068: public Object saveOrUpdateCopy(String entityName, Object object)
069: throws HibernateException;
070:
071: /**
072: * Copy the state of the given object onto the persistent object with the
073: * given identifier. If there is no persistent instance currently associated
074: * with the session, it will be loaded. Return the persistent instance. If
075: * there is no database row with the given identifier, save the given instance
076: * and return it as a newly persistent instance. Otherwise, the given instance
077: * does not become associated with the session.
078: *
079: * @deprecated with no replacement
080: *
081: * @param object a persistent or transient instance with state to be copied
082: * @param id the identifier of the instance to copy to
083: * @return an updated persistent instance
084: */
085: public Object saveOrUpdateCopy(String entityName, Object object,
086: Serializable id) throws HibernateException;
087:
088: /**
089: * Execute a query.
090: *
091: * @deprecated use {@link #createQuery}.{@link Query#list()}
092: *
093: * @param query a query expressed in Hibernate's query language
094: * @return a distinct list of instances (or arrays of instances)
095: * @throws HibernateException
096: */
097: public List find(String query) throws HibernateException;
098:
099: /**
100: * Execute a query with bind parameters, binding a value to a "?" parameter
101: * in the query string.
102: *
103: * @deprecated use {@link #createQuery}.setXYZ.{@link Query#list()}
104: *
105: * @param query the query string
106: * @param value a value to be bound to a "?" placeholder (JDBC IN parameter).
107: * @param type the Hibernate type of the value
108: * @see org.hibernate.Hibernate for access to <tt>Type</tt> instances
109: * @return a distinct list of instances (or arrays of instances)
110: * @throws HibernateException
111: */
112: public List find(String query, Object value, Type type)
113: throws HibernateException;
114:
115: /**
116: * Execute a query with bind parameters, binding an array of values to "?"
117: * parameters in the query string.
118: *
119: * @deprecated use {@link #createQuery}.setXYZ.{@link Query#list()}
120: *
121: * @param query the query string
122: * @param values an array of values to be bound to the "?" placeholders (JDBC IN parameters).
123: * @param types an array of Hibernate types of the values
124: * @see org.hibernate.Hibernate for access to <tt>Type</tt> instances
125: * @return a distinct list of instances
126: * @throws HibernateException
127: */
128: public List find(String query, Object[] values, Type[] types)
129: throws HibernateException;
130:
131: /**
132: * Execute a query and return the results in an iterator. If the query has multiple
133: * return values, values will be returned in an array of type <tt>Object[].</tt><br>
134: * <br>
135: * Entities returned as results are initialized on demand. The first SQL query returns
136: * identifiers only. So <tt>iterate()</tt> is usually a less efficient way to retrieve
137: * objects than <tt>find()</tt>.
138: *
139: * @deprecated use {@link #createQuery}.{@link Query#iterate}
140: *
141: * @param query the query string
142: * @return an iterator
143: * @throws HibernateException
144: */
145: public Iterator iterate(String query) throws HibernateException;
146:
147: /**
148: * Execute a query and return the results in an iterator. Write the given value to "?"
149: * in the query string. If the query has multiple return values, values will be returned
150: * in an array of type <tt>Object[]</tt>.<br>
151: * <br>
152: * Entities returned as results are initialized on demand. The first SQL query returns
153: * identifiers only. So <tt>iterate()</tt> is usually a less efficient way to retrieve
154: * objects than <tt>find()</tt>.
155: *
156: * @deprecated use {@link #createQuery}.setXYZ.{@link Query#iterate}
157: *
158: * @param query the query string
159: * @param value a value to be witten to a "?" placeholder in the query string
160: * @param type the hibernate type of value
161: * @return an iterator
162: * @throws HibernateException
163: */
164: public Iterator iterate(String query, Object value, Type type)
165: throws HibernateException;
166:
167: /**
168: * Execute a query and return the results in an iterator. Write the given values to "?"
169: * in the query string. If the query has multiple return values, values will be returned
170: * in an array of type <tt>Object[]</tt>.<br>
171: * <br>
172: * Entities returned as results are initialized on demand. The first SQL query returns
173: * identifiers only. So <tt>iterate()</tt> is usually a less efficient way to retrieve
174: * objects than <tt>find()</tt>.
175: *
176: * @deprecated use {@link #createQuery}.setXYZ.{@link Query#iterate}
177: *
178: * @param query the query string
179: * @param values a list of values to be written to "?" placeholders in the query
180: * @param types a list of Hibernate types of the values
181: * @return an iterator
182: * @throws HibernateException
183: */
184: public Iterator iterate(String query, Object[] values, Type[] types)
185: throws HibernateException;
186:
187: /**
188: * Apply a filter to a persistent collection. A filter is a Hibernate query that may refer to
189: * <tt>this</tt>, the collection element. Filters allow efficient access to very large lazy
190: * collections. (Executing the filter does not initialize the collection.)
191: *
192: * @deprecated use {@link #createFilter(Object, String)}.{@link Query#list}
193: *
194: * @param collection a persistent collection to filter
195: * @param filter a filter query string
196: * @return Collection the resulting collection
197: * @throws HibernateException
198: */
199: public Collection filter(Object collection, String filter)
200: throws HibernateException;
201:
202: /**
203: * Apply a filter to a persistent collection. A filter is a Hibernate query that may refer to
204: * <tt>this</tt>, the collection element.
205: *
206: * @deprecated use {@link #createFilter(Object, String)}.setXYZ.{@link Query#list}
207: *
208: * @param collection a persistent collection to filter
209: * @param filter a filter query string
210: * @param value a value to be witten to a "?" placeholder in the query string
211: * @param type the hibernate type of value
212: * @return Collection
213: * @throws HibernateException
214: */
215: public Collection filter(Object collection, String filter,
216: Object value, Type type) throws HibernateException;
217:
218: /**
219: * Apply a filter to a persistent collection.
220: *
221: * Bind the given parameters to "?" placeholders. A filter is a Hibernate query that
222: * may refer to <tt>this</tt>, the collection element.
223: *
224: * @deprecated use {@link #createFilter(Object, String)}.setXYZ.{@link Query#list}
225: *
226: * @param collection a persistent collection to filter
227: * @param filter a filter query string
228: * @param values a list of values to be written to "?" placeholders in the query
229: * @param types a list of Hibernate types of the values
230: * @return Collection
231: * @throws HibernateException
232: */
233: public Collection filter(Object collection, String filter,
234: Object[] values, Type[] types) throws HibernateException;
235:
236: /**
237: * Delete all objects returned by the query. Return the number of objects deleted.
238: * <p/>
239: * Note that this is very different from the delete-statement support added in HQL
240: * since 3.1. The functionality here is to actually peform the query and then iterate
241: * the results calling {@link #delete(Object)} individually.
242: *
243: * @deprecated consider using HQL delete statements
244: *
245: * @param query the query string
246: * @return the number of instances deleted
247: * @throws HibernateException
248: */
249: public int delete(String query) throws HibernateException;
250:
251: /**
252: * Delete all objects returned by the query. Return the number of objects deleted.
253: * <p/>
254: * Note that this is very different from the delete-statement support added in HQL
255: * since 3.1. The functionality here is to actually peform the query and then iterate
256: * the results calling {@link #delete(Object)} individually.
257: *
258: * @deprecated consider using HQL delete statements
259: *
260: * @param query the query string
261: * @param value a value to be witten to a "?" placeholder in the query string.
262: * @param type the hibernate type of value.
263: * @return the number of instances deleted
264: * @throws HibernateException
265: */
266: public int delete(String query, Object value, Type type)
267: throws HibernateException;
268:
269: /**
270: * Delete all objects returned by the query. Return the number of objects deleted.
271: * <p/>
272: * Note that this is very different from the delete-statement support added in HQL
273: * since 3.1. The functionality here is to actually peform the query and then iterate
274: * the results calling {@link #delete(Object)} individually.
275: *
276: * @deprecated consider using HQL delete statements
277: *
278: * @param query the query string
279: * @param values a list of values to be written to "?" placeholders in the query.
280: * @param types a list of Hibernate types of the values
281: * @return the number of instances deleted
282: * @throws HibernateException
283: */
284: public int delete(String query, Object[] values, Type[] types)
285: throws HibernateException;
286:
287: /**
288: * Create a new instance of <tt>Query</tt> for the given SQL string.
289: *
290: * @deprecated will be replaced with a more Query like interface in later release
291: *
292: * @param sql a query expressed in SQL
293: * @param returnAlias a table alias that appears inside <tt>{}</tt> in the SQL string
294: * @param returnClass the returned persistent class
295: */
296: public Query createSQLQuery(String sql, String returnAlias,
297: Class returnClass);
298:
299: /**
300: * Create a new instance of <tt>Query</tt> for the given SQL string.
301: *
302: * @deprecated will be replaced with a more Query like interface in later release
303: *
304: * @param sql a query expressed in SQL
305: * @param returnAliases an array of table aliases that appear inside <tt>{}</tt> in the SQL string
306: * @param returnClasses the returned persistent classes
307: */
308: public Query createSQLQuery(String sql, String[] returnAliases,
309: Class[] returnClasses);
310:
311: /**
312: * Persist the given transient instance, using the given identifier. This operation
313: * cascades to associated instances if the association is mapped with
314: * <tt>cascade="save-update"</tt>.
315: *
316: * @deprecated declare identifier properties for all classes
317: *
318: * @param object a transient instance of a persistent class
319: * @param id an unused valid identifier
320: * @throws HibernateException
321: */
322: public void save(Object object, Serializable id)
323: throws HibernateException;
324:
325: /**
326: * Persist the given transient instance, using the given identifier. This operation
327: * cascades to associated instances if the association is mapped with
328: * <tt>cascade="save-update"</tt>.
329: *
330: * @deprecated declare identifier properties for all classes
331: *
332: * @param object a transient instance of a persistent class
333: * @param id an unused valid identifier
334: * @throws HibernateException
335: */
336: public void save(String entityName, Object object, Serializable id)
337: throws HibernateException;
338:
339: /**
340: * Update the persistent state associated with the given identifier. An exception
341: * is thrown if there is a persistent instance with the same identifier in the
342: * current session. This operation cascades to associated instances
343: * if the association is mapped with <tt>cascade="save-update"</tt>.
344: *
345: * @deprecated declare identifier properties for all classes
346: *
347: * @param object a detached instance containing updated state
348: * @param id identifier of persistent instance
349: * @throws HibernateException
350: */
351: public void update(Object object, Serializable id)
352: throws HibernateException;
353:
354: /**
355: * Update the persistent state associated with the given identifier. An exception
356: * is thrown if there is a persistent instance with the same identifier in the
357: * current session. This operation cascades to associated instances
358: * if the association is mapped with <tt>cascade="save-update"</tt>.
359: *
360: * @deprecated declare identifier properties for all classes
361: *
362: * @param object a detached instance containing updated state
363: * @param id identifier of persistent instance
364: * @throws HibernateException
365: */
366: public void update(String entityName, Object object, Serializable id)
367: throws HibernateException;
368:
369: }
|