/*
 * Licensed to the Apache Software Foundation (ASF) under one or more contributor license
 * agreements. See the NOTICE file distributed with this work for additional information regarding
 * copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance with the License. You may obtain a
 * copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License
 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing permissions and limitations under
 * the License.
 */

package org.apache.geode.cache;

/**
 * Defines common statistics information for both region and entries. All of these methods may throw
 * a CacheClosedException, RegionDestroyedException or an EntryDestroyedException.
 *
 *
 *
 * @see Region#getStatistics
 * @see Region.Entry#getStatistics
 * @since GemFire 2.0
 */

public interface CacheStatistics {
  /**
   * For an entry, returns the time that the entry's value was last modified; for a region, the last
   * time any of the region's entries' values or the values in subregions' entries were modified.
   * The modification may have been initiated locally or it may have been an update distributed from
   * another cache. It may also have been a new value provided by a loader. The modification time on
   * a region is propagated upward to parent regions, transitively, to the root region.
   * <p>
   * The number is expressed as the number of milliseconds since January 1, 1970. The granularity
   * may be as course as 100ms, so the accuracy may be off by up to 50ms.
   * <p>
   * Entry and subregion creation will update the modification time on a region, but
   * <code>destroy</code>, <code>destroyRegion</code>, <code>invalidate</code>, and
   * <code>invalidateRegion</code> do not update the modification time.
   *
   * @return the last modification time of the region or the entry; returns 0 if entry is invalid or
   *         modification time is uninitialized.
   * @see Region#put(Object, Object)
   * @see Region#get(Object)
   * @see Region#create(Object, Object)
   * @see Region#createSubregion
   */
  long getLastModifiedTime();

  /**
   * For an entry, returns the last time it was accessed via <code>Region.get</code>; for a region,
   * the last time any of its entries or the entries of its subregions were accessed with
   * <code>Region.get</code>. Any modifications will also update the lastAccessedTime, so
   * <code>lastAccessedTime</code> is always <code>>= lastModifiedTime</code>. The
   * <code>lastAccessedTime</code> on a region is propagated upward to parent regions, transitively,
   * to the the root region.
   * <p>
   * The number is expressed as the number of milliseconds since January 1, 1970. The granularity
   * may be as course as 100ms, so the accuracy may be off by up to 50ms.
   *
   * @return the last access time of the region or the entry's value; returns 0 if entry is invalid
   *         or access time is uninitialized.
   * @see Region#get(Object)
   * @see #getLastModifiedTime
   * @throws StatisticsDisabledException if statistics are not available
   */
  long getLastAccessedTime() throws StatisticsDisabledException;

  /**
   * Returns the number of times that {@link Region#get(Object) Region.get} on the region or the
   * entry was called and there was no value found locally. Unlike <code>lastAccessedTime</code>,
   * the miss count is not propagated to parent regions. Note that remote operations such as a "net
   * search" do not effect the miss count.
   *
   * @return the number of cache misses on the region or the entry.
   * @throws StatisticsDisabledException if statistics are not available
   */
  long getMissCount() throws StatisticsDisabledException;

  /**
   * Returns the number of hits for this region or entry. The number of hits is defined as the
   * number of times when the {@link Region#get(Object) Region.get} finds a value locally. Unlike
   * <code>lastAccessedTime</code>, the hit count is not propagated to parent regions. Note that
   * remote operations such as a "net search" do not effect the hit count.
   *
   * @return the number of hits for this region or entry.
   * @throws StatisticsDisabledException if statistics are not available
   */
  long getHitCount() throws StatisticsDisabledException;

  /**
   * Return the hit ratio, a convenience method defined as the ratio of hits to the number of calls
   * to {@link Region#get(Object) Region.get}. If there have been zero calls to
   * <code>Region.get</code>, then zero is returned.
   * <p>
   * The hit ratio is equivalent to:
   *
   * <pre>
   * long hitCount = getHitCount();
   * long total = hitCount + getMissCount();
   * return total == 0L ? 0.0f : ((float) hitCount / total);
   * </pre>
   *
   * @throws StatisticsDisabledException if statistics are not available
   * @return the hit ratio as a float
   */
  float getHitRatio() throws StatisticsDisabledException;


  /**
   * Reset the missCount and hitCount to zero for this entry.
   *
   * @throws StatisticsDisabledException if statistics are not available
   */
  void resetCounts() throws StatisticsDisabledException;
}