javadoc improvements to Sessionfactory, Filter, FilterDefinition
This commit is contained in:
Gavin King
parent
c6eb826bd6
commit
5c4ab4eaf6
|
|
@ -5,13 +5,23 @@
|
|||
* See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
|
||||
*/
|
||||
package org.hibernate;
|
||||
|
||||
import java.util.Collection;
|
||||
|
||||
import org.hibernate.engine.spi.FilterDefinition;
|
||||
|
||||
/**
|
||||
* Type definition of Filter. Filter defines the user's view into enabled dynamic filters,
|
||||
* allowing them to set filter parameter values.
|
||||
* Allows control over an enabled filter at runtime. In particular, allows
|
||||
* {@linkplain #setParameter(String, Object) arguments} to be assigned to
|
||||
* parameters declared by the filter.
|
||||
* <p>
|
||||
* A filter may be defined using {@link org.hibernate.annotations.FilterDef}
|
||||
* and {@link org.hibernate.annotations.Filter}, and must be explicitly
|
||||
* enabled at runtime by calling {@link Session#enableFilter(String)}.
|
||||
*
|
||||
* @see org.hibernate.annotations.FilterDef
|
||||
* @see Session#enableFilter(String)
|
||||
* @see FilterDefinition
|
||||
*
|
||||
* @author Steve Ebersole
|
||||
*/
|
||||
|
|
@ -25,8 +35,8 @@ public interface Filter {
|
|||
String getName();
|
||||
|
||||
/**
|
||||
* Get the filter definition containing additional information about the
|
||||
* filter (such as default-condition and expected parameter names/types).
|
||||
* Get the associated {@link FilterDefinition definition} of
|
||||
* this named filter.
|
||||
*
|
||||
* @return The filter definition
|
||||
*/
|
||||
|
|
@ -63,8 +73,8 @@ public interface Filter {
|
|||
Filter setParameterList(String name, Object[] values);
|
||||
|
||||
/**
|
||||
* Perform validation of the filter state. This is used to verify the
|
||||
* state of the filter after its enablement and before its use.
|
||||
* Perform validation of the filter state. This is used to verify
|
||||
* the state of the filter after its enablement and before its use.
|
||||
*
|
||||
* @throws HibernateException If the state is not currently valid.
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ import org.hibernate.resource.jdbc.spi.PhysicalConnectionHandlingMode;
|
|||
import org.hibernate.resource.jdbc.spi.StatementInspector;
|
||||
|
||||
/**
|
||||
* Represents a consolidation of all session creation options into a builder style delegate.
|
||||
* Allows creation of a new {@link Session} with specific options.
|
||||
*
|
||||
* @author Steve Ebersole
|
||||
*/
|
||||
|
|
@ -37,18 +37,18 @@ public interface SessionBuilder<T extends SessionBuilder> {
|
|||
/**
|
||||
* Signifies that no {@link Interceptor} should be used.
|
||||
* <p/>
|
||||
* By default the {@link Interceptor} associated with the {@link SessionFactory} is passed to the
|
||||
* {@link Session} whenever we open one without the user having specified a specific interceptor to
|
||||
* use.
|
||||
* By default, if no {@code Interceptor} is explicitly specified, the
|
||||
* {@code Interceptor} associated with the {@link SessionFactory} is
|
||||
* inherited by the new {@link Session}.
|
||||
* <p/>
|
||||
* Calling {@link #interceptor(Interceptor)} with null has the same net effect.
|
||||
* Calling {@link #interceptor(Interceptor)} with null has the same effect.
|
||||
*
|
||||
* @return {@code this}, for method chaining
|
||||
*/
|
||||
T noInterceptor();
|
||||
|
||||
/**
|
||||
* Applies a specific StatementInspector to the session options.
|
||||
* Applies the given {@link StatementInspector} to the session.
|
||||
*
|
||||
* @param statementInspector The StatementInspector to use.
|
||||
*
|
||||
|
|
@ -66,7 +66,8 @@ public interface SessionBuilder<T extends SessionBuilder> {
|
|||
T connection(Connection connection);
|
||||
|
||||
/**
|
||||
* Signifies that the connection release mode from the original session should be used to create the new session.
|
||||
* Signifies that the connection release mode from the original session
|
||||
* should be used to create the new session.
|
||||
*
|
||||
* @param mode The connection handling mode to use.
|
||||
*
|
||||
|
|
@ -116,7 +117,8 @@ public interface SessionBuilder<T extends SessionBuilder> {
|
|||
T tenantIdentifier(String tenantIdentifier);
|
||||
|
||||
/**
|
||||
* Apply one or more SessionEventListener instances to the listeners for the Session to be built.
|
||||
* Add one or more {@link SessionEventListener} instances to the list of
|
||||
* listeners for the new session to be built.
|
||||
*
|
||||
* @param listeners The listeners to incorporate into the built Session
|
||||
*
|
||||
|
|
@ -125,8 +127,8 @@ public interface SessionBuilder<T extends SessionBuilder> {
|
|||
T eventListeners(SessionEventListener... listeners);
|
||||
|
||||
/**
|
||||
* Remove all listeners intended for the built Session currently held here, including any auto-apply ones; in other
|
||||
* words, start with a clean slate.
|
||||
* Remove all listeners intended for the built session currently held here,
|
||||
* including any auto-apply ones; in other words, start with a clean slate.
|
||||
*
|
||||
* {@code this}, for method chaining
|
||||
*/
|
||||
|
|
@ -143,8 +145,8 @@ public interface SessionBuilder<T extends SessionBuilder> {
|
|||
*
|
||||
* @see jakarta.persistence.PersistenceContextType
|
||||
*
|
||||
* @deprecated Only integrations can specify autoClosing behavior of individual sessions. See
|
||||
* {@link org.hibernate.engine.spi.SessionOwner}
|
||||
* @deprecated Only integrations can specify autoClosing behavior of
|
||||
* individual sessions. See {@link org.hibernate.engine.spi.SessionOwner}.
|
||||
*/
|
||||
@Deprecated
|
||||
T autoClose(boolean autoClose);
|
||||
|
|
@ -162,7 +164,8 @@ public interface SessionBuilder<T extends SessionBuilder> {
|
|||
T connectionReleaseMode(ConnectionReleaseMode connectionReleaseMode);
|
||||
|
||||
/**
|
||||
* Should the session be automatically flushed during the "before completion" phase of transaction handling.
|
||||
* Should the session be automatically flushed during the "before completion"
|
||||
* phase of transaction handling.
|
||||
*
|
||||
* @param flushBeforeCompletion Should the session be automatically flushed
|
||||
*
|
||||
|
|
|
|||
|
|
@ -68,7 +68,8 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
|
|||
SessionFactoryOptions getSessionFactoryOptions();
|
||||
|
||||
/**
|
||||
* Obtain a {@link Session} builder.
|
||||
* Obtain a {@linkplain SessionBuilder session builder} for creating
|
||||
* new {@link Session}s with certain customized options.
|
||||
*
|
||||
* @return The session builder
|
||||
*/
|
||||
|
|
@ -77,9 +78,9 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
|
|||
/**
|
||||
* Open a {@link Session}.
|
||||
* <p/>
|
||||
* JDBC {@link Connection connection(s} will be obtained from the
|
||||
* configured {@link org.hibernate.engine.jdbc.connections.spi.ConnectionProvider} as needed
|
||||
* to perform requested work.
|
||||
* Any JDBC {@link Connection connection} will be obtained lazily from the
|
||||
* {@link org.hibernate.engine.jdbc.connections.spi.ConnectionProvider}
|
||||
* as needed to perform requested work.
|
||||
*
|
||||
* @return The created session.
|
||||
*
|
||||
|
|
@ -88,14 +89,21 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
|
|||
Session openSession() throws HibernateException;
|
||||
|
||||
/**
|
||||
* Obtains the current session. The definition of what exactly "current"
|
||||
* means controlled by the {@link org.hibernate.context.spi.CurrentSessionContext} impl configured
|
||||
* for use.
|
||||
* <p/>
|
||||
* Note that for backwards compatibility, if a {@link org.hibernate.context.spi.CurrentSessionContext}
|
||||
* is not configured but JTA is configured this will default to the
|
||||
* {@link org.hibernate.context.internal.JTASessionContext}
|
||||
* impl.
|
||||
* Obtains the <em>current session</em>, an instance of {@link Session}
|
||||
* implicitly associated with some context. For example, the session
|
||||
* might be associated with the current thread, or with the current
|
||||
* JTA transaction.
|
||||
* <p>
|
||||
* The context used for scoping the current session (that is, the
|
||||
* definition of what precisely "current" means here) is determined
|
||||
* by an implementation of
|
||||
* {@link org.hibernate.context.spi.CurrentSessionContext}. An
|
||||
* implementation may be selected using the configuration property
|
||||
* {@value org.hibernate.cfg.AvailableSettings#CURRENT_SESSION_CONTEXT_CLASS}.
|
||||
* <p>
|
||||
* If no {@link org.hibernate.context.spi.CurrentSessionContext} is
|
||||
* explicitly configured, but JTA is configured, then
|
||||
* {@link org.hibernate.context.internal.JTASessionContext} is used.
|
||||
*
|
||||
* @return The current session.
|
||||
*
|
||||
|
|
@ -137,7 +145,8 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
|
|||
}
|
||||
|
||||
/**
|
||||
* Open a Session and perform a action using it within the bounds of a transaction
|
||||
* Open a {@link Session} and perform an action using the session
|
||||
* within the bounds of a transaction.
|
||||
*/
|
||||
default void inTransaction(Consumer<Session> action) {
|
||||
inSession(
|
||||
|
|
@ -148,7 +157,8 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
|
|||
action.accept( session );
|
||||
|
||||
if ( !txn.isActive() ) {
|
||||
throw new TransactionManagementException( "Execution of action caused managed transaction to be completed" );
|
||||
throw new TransactionManagementException(
|
||||
"Execution of action caused managed transaction to be completed" );
|
||||
}
|
||||
}
|
||||
catch (RuntimeException e) {
|
||||
|
|
@ -180,7 +190,7 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
|
|||
}
|
||||
|
||||
/**
|
||||
* Open a Session and perform a action using it
|
||||
* Open a Session and perform an action using it.
|
||||
*/
|
||||
default <R> R fromSession(Function<Session,R> action) {
|
||||
try (Session session = openSession()) {
|
||||
|
|
@ -189,7 +199,8 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
|
|||
}
|
||||
|
||||
/**
|
||||
* Open a Session and perform a action using it within the bounds of a transaction
|
||||
* Open a {@link Session} and perform an action using the session
|
||||
* within the bounds of a transaction.
|
||||
*/
|
||||
default <R> R fromTransaction(Function<Session,R> action) {
|
||||
return fromSession(
|
||||
|
|
@ -199,7 +210,8 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
|
|||
R result = action.apply( session );
|
||||
|
||||
if ( !txn.isActive() ) {
|
||||
throw new TransactionManagementException( "Execution of action caused managed transaction to be completed" );
|
||||
throw new TransactionManagementException(
|
||||
"Execution of action caused managed transaction to be completed" );
|
||||
}
|
||||
|
||||
// action completed with no errors - attempt to commit the transaction allowing
|
||||
|
|
@ -227,19 +239,19 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
|
|||
}
|
||||
|
||||
/**
|
||||
* Retrieve the statistics for this factory.
|
||||
* Retrieve the {@linkplain Statistics statistics} for this factory.
|
||||
*
|
||||
* @return The statistics.
|
||||
*/
|
||||
Statistics getStatistics();
|
||||
|
||||
/**
|
||||
* Destroy this {@code SessionFactory} and release all resources (caches,
|
||||
* connection pools, etc).
|
||||
* Destroy this {@code SessionFactory} and release all its resources,
|
||||
* including caches and connection pools.
|
||||
* <p/>
|
||||
* It is the responsibility of the application to ensure that there are no
|
||||
* open {@linkplain Session sessions} before calling this method as the impact
|
||||
* on those {@linkplain Session sessions} is indeterminate.
|
||||
* It is the responsibility of the application to ensure that there are
|
||||
* no open {@linkplain Session sessions} before calling this method as
|
||||
* the impact on those {@linkplain Session sessions} is indeterminate.
|
||||
* <p/>
|
||||
* No-ops if already {@linkplain #isClosed() closed}.
|
||||
*
|
||||
|
|
@ -263,14 +275,14 @@ public interface SessionFactory extends EntityManagerFactory, Referenceable, Ser
|
|||
Cache getCache();
|
||||
|
||||
/**
|
||||
* Get all EntityGraphs registered for a particular entity type
|
||||
* Return all {@link EntityGraph}s registered for the given entity type.
|
||||
*
|
||||
* @see #addNamedEntityGraph
|
||||
*/
|
||||
<T> List<EntityGraph<? super T>> findEntityGraphsByType(Class<T> entityClass);
|
||||
|
||||
/**
|
||||
* Obtain a set of the names of all filters defined on this SessionFactory.
|
||||
* Obtain the set of names of all {@link FilterDefinition defined filters}.
|
||||
*
|
||||
* @return The set of filter names.
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -14,8 +14,14 @@ import java.util.Set;
|
|||
import org.hibernate.type.Type;
|
||||
|
||||
/**
|
||||
* A FilterDefinition defines the global attributes of a dynamic filter. This
|
||||
* information includes its name as well as its defined parameters (name and type).
|
||||
* Represents the definition of a {@link org.hibernate.Filter filter}.
|
||||
* This information includes the {@linkplain #filterName name} of the
|
||||
* filter, along with the {@linkplain #parameterTypes name and type}
|
||||
* of every parameter of the filter. A filter may optionally have a
|
||||
* {@linkplain #defaultFilterCondition default condition}.
|
||||
*
|
||||
* @see org.hibernate.annotations.FilterDef
|
||||
* @see org.hibernate.Filter
|
||||
*
|
||||
* @author Steve Ebersole
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in New Issue