diff --git a/hibernate-core/src/main/java/org/hibernate/stat/CacheRegionStatistics.java b/hibernate-core/src/main/java/org/hibernate/stat/CacheRegionStatistics.java index eebb576532..99e23b134e 100644 --- a/hibernate-core/src/main/java/org/hibernate/stat/CacheRegionStatistics.java +++ b/hibernate-core/src/main/java/org/hibernate/stat/CacheRegionStatistics.java @@ -9,7 +9,7 @@ package org.hibernate.stat; import java.io.Serializable; /** - * Second level cache statistics of a specific region + * Second-level cache statistics of a specific region. * * @author Gavin King */ @@ -43,7 +43,7 @@ public interface CacheRegionStatistics extends Serializable { /** * The number of elements currently in memory within the cache provider. - * + *
* This is an optional value contingent upon the underlying cache provider * providing extended stats support via * {@link org.hibernate.cache.spi.ExtendedStatisticsSupport}. If the provider @@ -54,7 +54,7 @@ public interface CacheRegionStatistics extends Serializable { /** * The number of elements currently stored to disk within the cache provider. - * + *
* This is an optional value contingent upon the underlying cache provider * providing extended stats support via * {@link org.hibernate.cache.spi.ExtendedStatisticsSupport}. If the provider @@ -65,7 +65,7 @@ public interface CacheRegionStatistics extends Serializable { /** * The size that the in-memory elements take up within the cache provider. - * + *
* This is an optional value contingent upon the underlying cache provider * providing extended stats support via * {@link org.hibernate.cache.spi.ExtendedStatisticsSupport}. If the provider diff --git a/hibernate-core/src/main/java/org/hibernate/stat/CollectionStatistics.java b/hibernate-core/src/main/java/org/hibernate/stat/CollectionStatistics.java index d2a7b85fe7..a8fa305f70 100644 --- a/hibernate-core/src/main/java/org/hibernate/stat/CollectionStatistics.java +++ b/hibernate-core/src/main/java/org/hibernate/stat/CollectionStatistics.java @@ -9,7 +9,7 @@ package org.hibernate.stat; import java.io.Serializable; /** - * Collection related statistics + * Collection-related statistics. * * @author Gavin King * @author Steve Ebersole diff --git a/hibernate-core/src/main/java/org/hibernate/stat/EntityStatistics.java b/hibernate-core/src/main/java/org/hibernate/stat/EntityStatistics.java index ae8456ea23..4a340ef109 100644 --- a/hibernate-core/src/main/java/org/hibernate/stat/EntityStatistics.java +++ b/hibernate-core/src/main/java/org/hibernate/stat/EntityStatistics.java @@ -9,7 +9,7 @@ package org.hibernate.stat; import java.io.Serializable; /** - * Entity related statistics + * Entity-related statistics. * * @author Gavin King * @author Steve Ebersole diff --git a/hibernate-core/src/main/java/org/hibernate/stat/NaturalIdStatistics.java b/hibernate-core/src/main/java/org/hibernate/stat/NaturalIdStatistics.java index 7e086b49f9..b839284aa6 100644 --- a/hibernate-core/src/main/java/org/hibernate/stat/NaturalIdStatistics.java +++ b/hibernate-core/src/main/java/org/hibernate/stat/NaturalIdStatistics.java @@ -9,12 +9,13 @@ package org.hibernate.stat; import java.io.Serializable; /** - * Statistics pertaining to the execution of the "natural id resolution" query. + * Statistics pertaining to the execution of queries which resolve a natural + * id lookup against the database. * * @apiNote The natural-id resolution data is allowed to be stored in the - * second level cache, and if so stored will have available caching stats as - * well available via {@link Statistics#getDomainDataRegionStatistics} using the - * configured region name + * second-level cache, and if so stored will have available caching stats as + * well available via {@link Statistics#getDomainDataRegionStatistics} using + * the configured region name * * todo (6.0) : consider a means to get the cache Region statistics for: * 1) an entity by name diff --git a/hibernate-core/src/main/java/org/hibernate/stat/QueryStatistics.java b/hibernate-core/src/main/java/org/hibernate/stat/QueryStatistics.java index 9402c13a88..5bb396e5c0 100644 --- a/hibernate-core/src/main/java/org/hibernate/stat/QueryStatistics.java +++ b/hibernate-core/src/main/java/org/hibernate/stat/QueryStatistics.java @@ -9,9 +9,11 @@ package org.hibernate.stat; import java.io.Serializable; /** - * Query statistics (HQL and SQL) - *
- * Note that for a cached query, the cache miss is equals to the db count + * Statistics relating to a particular query written in HQL or SQL. + *+ * Note that for a cached query, the number of cache missed is the + * same as the number of queries actually executed against the + * database. * * @author Gavin King * @author Steve Ebersole @@ -23,7 +25,8 @@ public interface QueryStatistics extends Serializable { long getExecutionCount(); /** - * How many ResultSet rows have been processed for this query ? + * How many {@link java.sql.ResultSet} rows have been processed + * for this query */ long getExecutionRowCount(); @@ -43,7 +46,8 @@ public interface QueryStatistics extends Serializable { long getExecutionMinTime(); /** - * How long, cumulatively, have all executions of this query taken? + * How long, cumulatively, have all executions of this query + * taken? */ long getExecutionTotalTime(); @@ -77,7 +81,8 @@ public interface QueryStatistics extends Serializable { long getCachePutCount(); /** - * The number of query plans successfully fetched from the cache. + * The number of query plans successfully fetched from the + * cache. */ default long getPlanCacheHitCount() { //For backward compatibility @@ -93,7 +98,8 @@ public interface QueryStatistics extends Serializable { } /** - * The overall time spent to compile the plan for this particular query. + * The overall time spent to compile the plan for this + * particular query. */ default long getPlanCompilationTotalMicroseconds() { //For backward compatibility diff --git a/hibernate-core/src/main/java/org/hibernate/stat/SessionStatistics.java b/hibernate-core/src/main/java/org/hibernate/stat/SessionStatistics.java index 94473e2926..a56e54e92a 100644 --- a/hibernate-core/src/main/java/org/hibernate/stat/SessionStatistics.java +++ b/hibernate-core/src/main/java/org/hibernate/stat/SessionStatistics.java @@ -9,28 +9,29 @@ package org.hibernate.stat; import java.util.Set; /** - * Information about the first-level (session) cache - * for a particular session instance + * Information about the first-level (session) cache for a particular + * instance of {@link org.hibernate.Session}. + * * @author Gavin King */ public interface SessionStatistics { /** - * Get the number of entity instances associated with the session + * The number of entity instances associated with the session. */ int getEntityCount(); /** - * Get the number of collection instances associated with the session + * The number of collection instances associated with the session. */ int getCollectionCount(); /** - * Get the set of all {@code EntityKey}s - * @see org.hibernate.engine.spi.EntityKey + * The set of all {@link org.hibernate.engine.spi.EntityKey}s + * currently held within the persistence context. */ Set> getEntityKeys(); /** - * Get the set of all {@code CollectionKey}s - * @see org.hibernate.engine.spi.CollectionKey + * The set of all {@link org.hibernate.engine.spi.CollectionKey}s + * currently held within the persistence context. */ Set> getCollectionKeys(); diff --git a/hibernate-core/src/main/java/org/hibernate/stat/Statistics.java b/hibernate-core/src/main/java/org/hibernate/stat/Statistics.java index 8cc8dc1dd2..2e1d7bc79e 100644 --- a/hibernate-core/src/main/java/org/hibernate/stat/Statistics.java +++ b/hibernate-core/src/main/java/org/hibernate/stat/Statistics.java @@ -6,373 +6,400 @@ */ package org.hibernate.stat; -import javax.management.MXBean; +import java.time.Instant; /** - * Exposes statistics for a particular {@link org.hibernate.SessionFactory}. Beware of milliseconds metrics, they - * are dependent of the JVM precision: you may then encounter a 10 ms approximation depending on you OS platform. - * Please refer to the JVM documentation for more information. + * Exposes statistics collected from all sessions belonging to a + * particular {@link org.hibernate.SessionFactory}. + *
+ * Collection of statistics is enabled if the configuration property + * {@link org.hibernate.cfg.AvailableSettings#GENERATE_STATISTICS} is + * set to {@code true}. It may be dynamically enabled or disabled at + * runtime by calling {@link #setStatisticsEnabled(boolean)}. * * @author Emmanuel Bernard */ -@MXBean public interface Statistics { + /** + * The default value of the configuration property + * {@link org.hibernate.cfg.AvailableSettings#QUERY_STATISTICS_MAX_SIZE}. + */ int DEFAULT_QUERY_STATISTICS_MAX_SIZE = 5000; /** - * Are statistics enabled + * Is collection of statistics enabled? */ boolean isStatisticsEnabled(); /** - * Enable statistics logs (this is a dynamic parameter) + * Enable or disable statistics collection. */ - void setStatisticsEnabled(boolean b); + void setStatisticsEnabled(boolean enabled); + /** - * reset all statistics + * Reset all statistics. */ void clear(); /** - * log in info level the main statistics + * Log the main statistics at level {@code INFO}. */ void logSummary(); /** - * find entity statistics per name + * Obtain the statistics for the entity with the given name. * - * @param entityName entity name - * @return EntityStatistics object + * @param entityName the entity name */ EntityStatistics getEntityStatistics(String entityName); /** - * Get collection statistics per role + * Obtain the statistics for the collection with the given role. * - * @param role collection role - * @return CollectionStatistics + * @param role the collection role */ CollectionStatistics getCollectionStatistics(String role); /** - * Natural id resolution query statistics for an entity type + * Obtain the natural id resolution statistics for the entity + * type with the given name. * - * @param entityName The entity name that is the root of the hierarchy containing the - * natural id - * @return NaturalIdCacheStatistics + * @param entityName The entity name that is the root of the + * hierarchy containing the natural id */ NaturalIdStatistics getNaturalIdStatistics(String entityName); /** - * Query statistics from query string (HQL or SQL) + * Obtain the query statistics for the given query string. * - * @param queryString query string - * @return QueryStatistics + * @param queryString the query string, written in HQL or SQL */ QueryStatistics getQueryStatistics(String queryString); /** - * Second-level cache statistics per domain data (entity, collection, natural-id) region + * Obtain the second-level cache statistics for the given cache + * region. * * @param regionName The unqualified region name * - * @return The stats for the named region, or {@code null} if the second level cache is - * not enabled + * @return the statistics for the named region, or {@code null} + * if the second-level cache is not enabled * - * @throws IllegalArgumentException if the region name could not be resolved + * @throws IllegalArgumentException if there is no region with the given name */ CacheRegionStatistics getDomainDataRegionStatistics(String regionName); /** - * Second-level cache statistics per query region + * Obtain the second-level cache statistics for the given query + * cache region. * * @param regionName The unqualified region name * - * @return Stats for the named region, or {@code null} if (1) query result caching is - * not enabled or (2) no query region exists with that name + * @return the statistics for the named region, or {@code null} + * if either query result caching is not enabled, or no + * query cache region exists with the given name */ CacheRegionStatistics getQueryRegionStatistics(String regionName); /** - * Get statistics for either a domain-data or query-result region - this - * method checks both, preferring domain data region if one. Think of it - * as a cascading check to:
+ * This method checks both, preferring the domain data region if + * there is one. Think of it as a cascading check to:
+ * The actual number of connections used may be much smaller, assuming + * that a connection pool is in use. */ long getConnectCount(); /** - * Global number of cacheable entities/collections successfully retrieved from the cache + * The global number of cacheable entities and collections successfully + * retrieved from the cache. */ long getSecondLevelCacheHitCount(); /** - * Global number of cacheable entities/collections not found in the cache and loaded from the database. + * The global number of cacheable entities collections not found in the + * cache and loaded from the database. */ long getSecondLevelCacheMissCount(); /** - * Global number of cacheable entities/collections put in the cache + * The global number of cacheable entities and collections put in the + * cache. */ long getSecondLevelCachePutCount(); /** - * Global number of sessions closed + * The global number of sessions closed. */ long getSessionCloseCount(); /** - * Global number of sessions opened + * The global number of sessions opened. */ long getSessionOpenCount(); /** - * Global number of collections loaded + * The global number of collections loaded. */ long getCollectionLoadCount(); /** - * Global number of collections fetched + * The global number of collections fetched. */ long getCollectionFetchCount(); /** - * Global number of collections updated + * The global number of collections updated. */ long getCollectionUpdateCount(); /** - * Global number of collections removed + * The global number of collections removed. */ //even on inverse="true" long getCollectionRemoveCount(); /** - * Global number of collections recreated + * The global number of collections recreated */ long getCollectionRecreateCount(); /** - * The milliseconds (JVM standard {@link System#currentTimeMillis()}) - * since the initial creation of this Statistics - * instance or the last time {@link #clear()} was called. - * - * @apiNote This time(stamp) is + * The {@link Instant} at which this instance of {@code Statistics} + * was created, or since the last time {@link #clear()} was called. */ + Instant getStart(); + + /** + * The {@linkplain Instant#toEpochMilli()} milliseconds}) since the + * initial creation of this instance, or since the last time + * {@link #clear()} was called. + * + * @deprecated use {@link #getStart()} + */ + @Deprecated(since = "6.0") long getStartTime(); /** - * Get all executed query strings. - * - * The maximum number of queries tracked by the Hibernate statistics is given by the {@code hibernate.statistics.query_max_size} property. + * All executed query strings. + *
+ * The maximum number of queries tracked by the Hibernate statistics
+ * is determined by the configuration property
+ * {@link org.hibernate.cfg.AvailableSettings#QUERY_STATISTICS_MAX_SIZE}.
*/
String[] getQueries();
/**
- * Get the names of all entities
+ * The names of all entities.
*/
String[] getEntityNames();
/**
- * Get the names of all collection roles
+ * The names of all collection roles.
*/
String[] getCollectionRoleNames();
/**
- * Get all second-level cache region names. Note: for backwards
- * compatibility this method returns just the names of regions
- * storing domain data, not query result regions
+ * All second-level cache region names. For backwards compatibility,
+ * this method returns just the names of regions storing domain data,
+ * not query result cache regions.
*/
String[] getSecondLevelCacheRegionNames();
/**
- * The number of transactions we know to have been successful
+ * The number of transactions we know to have been successful.
*/
long getSuccessfulTransactionCount();
/**
- * The number of transactions we know to have completed
+ * The number of transactions we know to have completed.
*/
long getTransactionCount();
/**
- * The number of prepared statements that were acquired
+ * The number of prepared statements that were acquired.
*/
long getPrepareStatementCount();
/**
- * The number of prepared statements that were released
+ * The number of prepared statements that were released.
*/
long getCloseStatementCount();
/**
- * The number of Hibernate {@code StaleObjectStateException}s or JPA {@code OptimisticLockException}s
- * that occurred.
+ * The number of Hibernate {@code StaleObjectStateException}s or JPA
+ * {@code OptimisticLockException}s that have occurred.
*/
long getOptimisticFailureCount();
/**
- * Second-level cache statistics per region
+ * Second-level cache statistics per region.
*
* @param regionName qualified region name
*
- * @return SecondLevelCacheStatistics or {@code null} if the second level cache is not enabled
+ * @return the statistics object, or {@code null} if the second-level
+ * cache is not enabled
*
- * @throws IllegalArgumentException if the region name could not be resolved
+ * @throws IllegalArgumentException if there is no region with the given name
*
- * @deprecated (since 5.3) Use {@link #getDomainDataRegionStatistics} instead
+ * @deprecated Use {@link #getDomainDataRegionStatistics}
*/
- @Deprecated
+ @Deprecated(since = "5.3")
SecondLevelCacheStatistics getSecondLevelCacheStatistics(String regionName);
/**
- * Natural id cache statistics per region
+ * Natural id cache statistics per region.
*
* @param regionName region name
* @return NaturalIdCacheStatistics
*
- * @deprecated (since 5.3) Use {@link #getNaturalIdStatistics} or
- * {@link #getDomainDataRegionStatistics} instead depending on need
+ * @deprecated Use {@link #getNaturalIdStatistics} or
+ * {@link #getDomainDataRegionStatistics}
*/
- @Deprecated
+ @Deprecated(since = "5.3")
NaturalIdCacheStatistics getNaturalIdCacheStatistics(String regionName);
/**
- * Get the global number of query plans successfully retrieved from cache
+ * The global number of query plans successfully retrieved from cache.
*/
default long getQueryPlanCacheHitCount() {
//For backward compatibility
@@ -380,7 +407,7 @@ public interface Statistics {
}
/**
- * Get the global number of query plans lookups *not* found in cache
+ * The global number of query plans lookups not found in cache.
*/
default long getQueryPlanCacheMissCount() {
//For backward compatibility
diff --git a/hibernate-core/src/main/java/org/hibernate/stat/internal/StatisticsImpl.java b/hibernate-core/src/main/java/org/hibernate/stat/internal/StatisticsImpl.java
index cff35078a6..7b20a42267 100644
--- a/hibernate-core/src/main/java/org/hibernate/stat/internal/StatisticsImpl.java
+++ b/hibernate-core/src/main/java/org/hibernate/stat/internal/StatisticsImpl.java
@@ -6,6 +6,7 @@
*/
package org.hibernate.stat.internal;
+import java.time.Instant;
import java.util.Objects;
import java.util.concurrent.atomic.AtomicLong;
import java.util.concurrent.atomic.LongAdder;
@@ -32,7 +33,6 @@ import static org.hibernate.internal.CoreLogging.messageLogger;
* @author Alex Snaps
* @author Sanne Grinovero
*/
-@SuppressWarnings({ "unchecked" })
public class StatisticsImpl implements StatisticsImplementor, Service {
private static final CoreMessageLogger LOG = messageLogger( StatisticsImpl.class );
@@ -44,7 +44,7 @@ public class StatisticsImpl implements StatisticsImplementor, Service {
private final boolean queryCacheEnabled;
private volatile boolean isStatisticsEnabled;
- private volatile long startTime;
+ private volatile Instant startTime;
private final LongAdder sessionOpenCount = new LongAdder();
private final LongAdder sessionCloseCount = new LongAdder();
@@ -96,9 +96,9 @@ public class StatisticsImpl implements StatisticsImplementor, Service {
private final LongAdder optimisticFailureCount = new LongAdder();
- private final StatsNamedContainer