001: //$Id: StatelessSession.java 9705 2006-03-28 19:59:31Z steve.ebersole@jboss.com $
002: package org.hibernate;
003:
004: import java.io.Serializable;
005: import java.sql.Connection;
006:
007: /**
008: * A command-oriented API for performing bulk operations
009: * against a database.<br>
010: * <br>
011: * A stateless session does not implement a first-level cache nor
012: * interact with any second-level cache, nor does it implement
013: * transactional write-behind or automatic dirty checking, nor do
014: * operations cascade to associated instances. Collections are
015: * ignored by a stateless session. Operations performed via a
016: * stateless session bypass Hibernate's event model and
017: * interceptors. Stateless sessions are vulnerable to data
018: * aliasing effects, due to the lack of a first-level cache.<br>
019: * <br>
020: * For certain kinds of transactions, a stateless session may
021: * perform slightly faster than a stateful session.
022: *
023: * @author Gavin King
024: */
025: public interface StatelessSession extends Serializable {
026: /**
027: * Close the stateless session and release the JDBC connection.
028: */
029: public void close();
030:
031: /**
032: * Insert a row.
033: *
034: * @param entity a new transient instance
035: */
036: public Serializable insert(Object entity);
037:
038: /**
039: * Insert a row.
040: *
041: * @param entityName The entityName for the entity to be inserted
042: * @param entity a new transient instance
043: * @return the identifier of the instance
044: */
045: public Serializable insert(String entityName, Object entity);
046:
047: /**
048: * Update a row.
049: *
050: * @param entity a detached entity instance
051: */
052: public void update(Object entity);
053:
054: /**
055: * Update a row.
056: *
057: * @param entityName The entityName for the entity to be updated
058: * @param entity a detached entity instance
059: */
060: public void update(String entityName, Object entity);
061:
062: /**
063: * Delete a row.
064: *
065: * @param entity a detached entity instance
066: */
067: public void delete(Object entity);
068:
069: /**
070: * Delete a row.
071: *
072: * @param entityName The entityName for the entity to be deleted
073: * @param entity a detached entity instance
074: */
075: public void delete(String entityName, Object entity);
076:
077: /**
078: * Retrieve a row.
079: *
080: * @return a detached entity instance
081: */
082: public Object get(String entityName, Serializable id);
083:
084: /**
085: * Retrieve a row.
086: *
087: * @return a detached entity instance
088: */
089: public Object get(Class entityClass, Serializable id);
090:
091: /**
092: * Retrieve a row, obtaining the specified lock mode.
093: *
094: * @return a detached entity instance
095: */
096: public Object get(String entityName, Serializable id,
097: LockMode lockMode);
098:
099: /**
100: * Retrieve a row, obtaining the specified lock mode.
101: *
102: * @return a detached entity instance
103: */
104: public Object get(Class entityClass, Serializable id,
105: LockMode lockMode);
106:
107: /**
108: * Refresh the entity instance state from the database.
109: *
110: * @param entity The entity to be refreshed.
111: */
112: public void refresh(Object entity);
113:
114: /**
115: * Refresh the entity instance state from the database.
116: *
117: * @param entityName The entityName for the entity to be refreshed.
118: * @param entity The entity to be refreshed.
119: */
120: public void refresh(String entityName, Object entity);
121:
122: /**
123: * Refresh the entity instance state from the database.
124: *
125: * @param entity The entity to be refreshed.
126: * @param lockMode The LockMode to be applied.
127: */
128: public void refresh(Object entity, LockMode lockMode);
129:
130: /**
131: * Refresh the entity instance state from the database.
132: *
133: * @param entityName The entityName for the entity to be refreshed.
134: * @param entity The entity to be refreshed.
135: * @param lockMode The LockMode to be applied.
136: */
137: public void refresh(String entityName, Object entity,
138: LockMode lockMode);
139:
140: /**
141: * Create a new instance of <tt>Query</tt> for the given HQL query string.
142: * Entities returned by the query are detached.
143: */
144: public Query createQuery(String queryString);
145:
146: /**
147: * Obtain an instance of <tt>Query</tt> for a named query string defined in
148: * the mapping file. Entities returned by the query are detached.
149: */
150: public Query getNamedQuery(String queryName);
151:
152: /**
153: * Create a new <tt>Criteria</tt> instance, for the given entity class,
154: * or a superclass of an entity class. Entities returned by the query are
155: * detached.
156: *
157: * @param persistentClass a class, which is persistent, or has persistent subclasses
158: * @return Criteria
159: */
160: public Criteria createCriteria(Class persistentClass);
161:
162: /**
163: * Create a new <tt>Criteria</tt> instance, for the given entity class,
164: * or a superclass of an entity class, with the given alias.
165: * Entities returned by the query are detached.
166: *
167: * @param persistentClass a class, which is persistent, or has persistent subclasses
168: * @return Criteria
169: */
170: public Criteria createCriteria(Class persistentClass, String alias);
171:
172: /**
173: * Create a new <tt>Criteria</tt> instance, for the given entity name.
174: * Entities returned by the query are detached.
175: *
176: * @param entityName
177: * @return Criteria
178: */
179: public Criteria createCriteria(String entityName);
180:
181: /**
182: * Create a new <tt>Criteria</tt> instance, for the given entity name,
183: * with the given alias. Entities returned by the query are detached.
184: *
185: * @param entityName
186: * @return Criteria
187: */
188: public Criteria createCriteria(String entityName, String alias);
189:
190: /**
191: * Create a new instance of <tt>SQLQuery</tt> for the given SQL query string.
192: * Entities returned by the query are detached.
193: *
194: * @param queryString a SQL query
195: * @return SQLQuery
196: * @throws HibernateException
197: */
198: public SQLQuery createSQLQuery(String queryString)
199: throws HibernateException;
200:
201: /**
202: * Begin a Hibernate transaction.
203: */
204: public Transaction beginTransaction();
205:
206: /**
207: * Get the current Hibernate transaction.
208: */
209: public Transaction getTransaction();
210:
211: /**
212: * Returns the current JDBC connection associated with this
213: * instance.<br>
214: * <br>
215: * If the session is using aggressive connection release (as in a
216: * CMT environment), it is the application's responsibility to
217: * close the connection returned by this call. Otherwise, the
218: * application should not close the connection.
219: */
220: public Connection connection();
221: }
|