HHH-6053 - Create an interface for centralizing the contract that is shared between Session and StatelessSession

hibernate-core/src/main/java/org/hibernate/Session.java

@@ -1,10 +1,10 @@
 /*
  * Hibernate, Relational Persistence for Idiomatic Java
  *
- * Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
+ * Copyright (c) 2008-2011, Red Hat Inc. or third-party contributors as
  * indicated by the @author tags or express copyright attribution
  * statements applied by the authors.  All third-party contributions are
- * distributed under license by Red Hat Middleware LLC.
+ * distributed under license by Red Hat Inc.
  *
  * This copyrighted material is made available to anyone wishing to use, modify,
  * copy, or redistribute it subject to the terms and conditions of the GNU
@@ -20,9 +20,9 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
+
 import java.io.Serializable;
 import java.sql.Connection;
 
@@ -89,8 +89,7 @@ import org.hibernate.stat.SessionStatistics;
  * @see SessionFactory
  * @author Gavin King
  */
-public interface Session extends Serializable {
+public interface Session extends SharedSessionContract {
-
 	/**
 	 * Retrieve the entity mode in effect for this session.
 	 *
@@ -653,101 +652,16 @@ public interface Session extends Serializable {
 	public LockMode getCurrentLockMode(Object object) throws HibernateException;
 
 	/**
-	 * Begin a unit of work and return the associated <tt>Transaction</tt> object.
+	 * Create a {@link Query} instance for the given collection and filter string.  Contains an implicit {@code FROM}
-	 * If a new underlying transaction is required, begin the transaction. Otherwise
+	 * element named {@code this} which refers to the defined table for the collection elements, as well as an implicit
-	 * continue the new work in the context of the existing underlying transaction.
+	 * {@code WHERE} restriction for this particular collection instance's key value.
-	 * The class of the returned <tt>Transaction</tt> object is determined by the
-	 * property <tt>hibernate.transaction_factory</tt>.
-	 *
-	 * @return a Transaction instance
-	 * @throws HibernateException
-	 * @see Transaction
-	 */
-	public Transaction beginTransaction() throws HibernateException;
-
-	/**
-	 * Get the <tt>Transaction</tt> instance associated with this session.
-	 * The class of the returned <tt>Transaction</tt> object is determined by the
-	 * property <tt>hibernate.transaction_factory</tt>.
-	 *
-	 * @return a Transaction instance
-	 * @throws HibernateException
-	 * @see Transaction
-	 */
-	public Transaction getTransaction();
-
-	/**
-	 * Create a new <tt>Criteria</tt> instance, for the given entity class,
-	 * or a superclass of an entity class.
-	 *
-	 * @param persistentClass a class, which is persistent, or has persistent subclasses
-	 * @return Criteria
-	 */
-	public Criteria createCriteria(Class persistentClass);
-
-	/**
-	 * Create a new <tt>Criteria</tt> instance, for the given entity class,
-	 * or a superclass of an entity class, with the given alias.
-	 *
-	 * @param persistentClass a class, which is persistent, or has persistent subclasses
-	 * @return Criteria
-	 */
-	public Criteria createCriteria(Class persistentClass, String alias);
-
-	/**
-	 * Create a new <tt>Criteria</tt> instance, for the given entity name.
-	 *
-	 * @param entityName
-	 * @return Criteria
-	 */
-	public Criteria createCriteria(String entityName);
-
-	/**
-	 * Create a new <tt>Criteria</tt> instance, for the given entity name,
-	 * with the given alias.
-	 *
-	 * @param entityName
-	 * @return Criteria
-	 */
-	public Criteria createCriteria(String entityName, String alias);
-
-	/**
-	 * Create a new instance of <tt>Query</tt> for the given HQL query string.
-	 *
-	 * @param queryString a HQL query
-	 * @return Query
-	 * @throws HibernateException
-	 */
-	public Query createQuery(String queryString) throws HibernateException;
-
-	/**
-	 * Create a new instance of <tt>SQLQuery</tt> for the given SQL query string.
-	 *
-	 * @param queryString a SQL query
-	 * @return SQLQuery
-	 * @throws HibernateException
-	 */
-	public SQLQuery createSQLQuery(String queryString) throws HibernateException;
-
-	/**
-	 * Create a new instance of <tt>Query</tt> for the given collection and filter string.
 	 *
 	 * @param collection a persistent collection
-	 * @param queryString a Hibernate query
+	 * @param queryString a Hibernate query fragment.
-	 * @return Query
-	 * @throws HibernateException
-	 */
-	public Query createFilter(Object collection, String queryString) throws HibernateException;
-
-	/**
-	 * Obtain an instance of <tt>Query</tt> for a named query string defined in the
-	 * mapping file.
 	 *
-	 * @param queryName the name of a query defined externally
+	 * @return The query instance for manipulation and execution
-	 * @return Query
-	 * @throws HibernateException
 	 */
-	public Query getNamedQuery(String queryName) throws HibernateException;
+	public Query createFilter(Object collection, String queryString);
 
 	/**
 	 * Completely clear the session. Evict all loaded instances and cancel all pending

hibernate-core/src/main/java/org/hibernate/SharedSessionContract.java

@@ -0,0 +1,118 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * Copyright (c) 2011, Red Hat Inc. or third-party contributors as
+ * indicated by the @author tags or express copyright attribution
+ * statements applied by the authors.  All third-party contributions are
+ * distributed under license by Red Hat Inc.
+ *
+ * This copyrighted material is made available to anyone wishing to use, modify,
+ * copy, or redistribute it subject to the terms and conditions of the GNU
+ * Lesser General Public License, as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this distribution; if not, write to:
+ * Free Software Foundation, Inc.
+ * 51 Franklin Street, Fifth Floor
+ * Boston, MA  02110-1301  USA
+ */
+package org.hibernate;
+
+import java.io.Serializable;
+
+/**
+ * Contract methods shared between {@link Session} and {@link StatelessSession}
+ * 
+ * @author Steve Ebersole
+ */
+public interface SharedSessionContract extends Serializable {
+	/**
+	 * Begin a unit of work and return the associated {@link Transaction} object.  If a new underlying transaction is
+	 * required, begin the transaction.  Otherwise continue the new work in the context of the existing underlying
+	 * transaction.
+	 *
+	 * @return a Transaction instance
+	 *
+	 * @see #getTransaction
+	 */
+	public Transaction beginTransaction();
+
+	/**
+	 * Get the {@link Transaction} instance associated with this session.  The concrete type of the returned
+	 * {@link Transaction} object is determined by the {@code hibernate.transaction_factory} property.
+	 *
+	 * @return a Transaction instance
+	 */
+	public Transaction getTransaction();
+
+	/**
+	 * Create a {@link Query} instance for the named query string defined in the metadata.
+	 *
+	 * @param queryName the name of a query defined externally
+	 *
+	 * @return The query instance for manipulation and execution
+	 */
+	public Query getNamedQuery(String queryName);
+
+	/**
+	 * Create a {@link Query} instance for the given HQL query string.
+	 *
+	 * @param queryString The HQL query
+	 *
+	 * @return The query instance for manipulation and execution
+	 */
+	public Query createQuery(String queryString);
+
+	/**
+	 * Create a {@link SQLQuery} instance for the given SQL query string.
+	 *
+	 * @param queryString The SQL query
+	 * 
+	 * @return The query instance for manipulation and execution
+	 */
+	public SQLQuery createSQLQuery(String queryString);
+
+	/**
+	 * Create {@link Criteria} instance for the given class (entity or subclasses/implementors)
+	 *
+	 * @param persistentClass The class, which is an entity, or has entity subclasses/implementors
+	 *
+	 * @return The criteria instance for manipulation and execution
+	 */
+	public Criteria createCriteria(Class persistentClass);
+
+	/**
+	 * Create {@link Criteria} instance for the given class (entity or subclasses/implementors), using a specific
+	 * alias.
+	 *
+	 * @param persistentClass The class, which is an entity, or has entity subclasses/implementors
+	 * @param alias The alias to use
+	 *
+	 * @return The criteria instance for manipulation and execution
+	 */
+	public Criteria createCriteria(Class persistentClass, String alias);
+
+	/**
+	 * Create {@link Criteria} instance for the given entity name.
+	 *
+	 * @param entityName The entity name
+
+	 * @return The criteria instance for manipulation and execution
+	 */
+	public Criteria createCriteria(String entityName);
+
+	/**
+	 * Create {@link Criteria} instance for the given entity name, using a specific alias.
+	 *
+	 * @param entityName The entity name
+	 * @param alias The alias to use
+	 *
+	 * @return The criteria instance for manipulation and execution
+	 */
+	public Criteria createCriteria(String entityName, String alias);
+}

hibernate-core/src/main/java/org/hibernate/StatelessSession.java

@@ -1,10 +1,10 @@
 /*
  * Hibernate, Relational Persistence for Idiomatic Java
  *
- * Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
+ * Copyright (c) 2008-2011, Red Hat Inc. or third-party contributors as
  * indicated by the @author tags or express copyright attribution
  * statements applied by the authors.  All third-party contributions are
- * distributed under license by Red Hat Middleware LLC.
+ * distributed under license by Red Hat Inc.
  *
  * This copyrighted material is made available to anyone wishing to use, modify,
  * copy, or redistribute it subject to the terms and conditions of the GNU
@@ -20,9 +20,9 @@
  * Free Software Foundation, Inc.
  * 51 Franklin Street, Fifth Floor
  * Boston, MA  02110-1301  USA
- *
  */
 package org.hibernate;
+
 import java.io.Serializable;
 import java.sql.Connection;
 
@@ -42,7 +42,7 @@ import java.sql.Connection;
  *
  * @author Gavin King
  */
-public interface StatelessSession extends Serializable {
+public interface StatelessSession extends SharedSessionContract {
 	/**
 	 * Close the stateless session and release the JDBC connection.
 	 */
@@ -154,76 +154,6 @@ public interface StatelessSession extends Serializable {
 	 */
 	public void refresh(String entityName, Object entity, LockMode lockMode);
 
-	/**
-	 * Create a new instance of <tt>Query</tt> for the given HQL query string.
-	 * Entities returned by the query are detached.
-	 */
-	public Query createQuery(String queryString);
-
-	/**
-	 * Obtain an instance of <tt>Query</tt> for a named query string defined in
-	 * the mapping file. Entities returned by the query are detached.
-	 */
-	public Query getNamedQuery(String queryName);
-
-	/**
-	 * Create a new <tt>Criteria</tt> instance, for the given entity class,
-	 * or a superclass of an entity class. Entities returned by the query are
-	 * detached.
-	 *
-	 * @param persistentClass a class, which is persistent, or has persistent subclasses
-	 * @return Criteria
-	 */
-	public Criteria createCriteria(Class persistentClass);
-
-	/**
-	 * Create a new <tt>Criteria</tt> instance, for the given entity class,
-	 * or a superclass of an entity class, with the given alias.
-	 * Entities returned by the query are detached.
-	 *
-	 * @param persistentClass a class, which is persistent, or has persistent subclasses
-	 * @return Criteria
-	 */
-	public Criteria createCriteria(Class persistentClass, String alias);
-
-	/**
-	 * Create a new <tt>Criteria</tt> instance, for the given entity name.
-	 * Entities returned by the query are detached.
-	 *
-	 * @param entityName
-	 * @return Criteria
-	 */
-	public Criteria createCriteria(String entityName);
-
-	/**
-	 * Create a new <tt>Criteria</tt> instance, for the given entity name,
-	 * with the given alias. Entities returned by the query are detached.
-	 *
-	 * @param entityName
-	 * @return Criteria
-	 */
-	public Criteria createCriteria(String entityName, String alias);
-
-	/**
-	 * Create a new instance of <tt>SQLQuery</tt> for the given SQL query string.
-	 * Entities returned by the query are detached.
-	 *
-	 * @param queryString a SQL query
-	 * @return SQLQuery
-	 * @throws HibernateException
-	 */
-	public SQLQuery createSQLQuery(String queryString) throws HibernateException;
-
-	/**
-	 * Begin a Hibernate transaction.
-	 */
-	public Transaction beginTransaction();
-
-	/**
-	 * Get the current Hibernate transaction.
-	 */
-	public Transaction getTransaction();
-
 	/**
 	 * Returns the current JDBC connection associated with this
 	 * instance.<br>
@@ -232,6 +162,9 @@ public interface StatelessSession extends Serializable {
 	 * CMT environment), it is the application's responsibility to
 	 * close the connection returned by this call. Otherwise, the
 	 * application should not close the connection.
+	 *
+	 * @deprecated just missed when deprecating same method from {@link Session}
 	 */
+	@Deprecated
 	public Connection connection();
 }

hibernate-core/src/main/java/org/hibernate/impl/AbstractSessionImpl.java

@@ -34,6 +34,7 @@ import org.hibernate.Query;
 import org.hibernate.SQLQuery;
 import org.hibernate.ScrollableResults;
 import org.hibernate.SessionException;
+import org.hibernate.SharedSessionContract;
 import org.hibernate.engine.NamedQueryDefinition;
 import org.hibernate.engine.NamedSQLQueryDefinition;
 import org.hibernate.engine.QueryParameters;
@@ -53,7 +54,7 @@ import org.hibernate.jdbc.WorkExecutorVisitable;
  *
  * @author Gavin King
  */
-public abstract class AbstractSessionImpl implements Serializable, SessionImplementor, TransactionContext {
+public abstract class AbstractSessionImpl implements Serializable, SharedSessionContract, SessionImplementor, TransactionContext {
 
 	protected transient SessionFactoryImpl factory;
 	private boolean closed = false;