#5707

Committed 02 Aug 2026 12:45AM UTC coverage: 0.106% (-99.9%) from 100.0%

Build # #5707

Build Type

push

github

Committed by

ben-manes

Commit Message

fix wikibench trace reader after overly strict audit fixes

Coverage Stats

0 of 4235 branches covered (0.0%)

9 of 8528 relevant lines covered (0.11%)

0.0 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

0.0

/caffeine/src/main/java/com/github/benmanes/caffeine/cache/Expiry.java

/*
 * Copyright 2017 Ben Manes. All Rights Reserved.
 *
 * Licensed 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 com.github.benmanes.caffeine.cache;

import static com.github.benmanes.caffeine.cache.Caffeine.toNanosSaturated;
import static java.util.Objects.requireNonNull;

import java.io.Serializable;
import java.time.Duration;
import java.util.function.BiFunction;

import org.jspecify.annotations.NullMarked;

import com.google.errorprone.annotations.CanIgnoreReturnValue;

/**
 * Calculates when cache entries expire. A single expiration time is retained so that the lifetime
 * of an entry may be extended or reduced by subsequent evaluations.
 * <p>
 * Usage example:
 * {@snippet class=com.github.benmanes.caffeine.cache.Snippets region=expiry lang=java}
 *
 * @param <K> the type of keys
 * @param <V> the type of values
 * @author ben.manes@gmail.com (Ben Manes)
 */
@NullMarked
@SuppressWarnings({"JavadocDeclaration", "JavadocReference"})
public interface Expiry<K, V> {

  /**
   * Specifies that the entry should be automatically removed from the cache once the duration has
   * elapsed after the entry's creation. To indicate no expiration, an entry may be given an
   * excessively long period, such as {@link Long#MAX_VALUE}.
   * <p>
   * <b>Note:</b> The {@code currentTime} is supplied by the configured {@link Ticker} and by
   * default does not relate to system or wall-clock time. When calculating the duration based on a
   * timestamp, the current time should be obtained independently.
   *
   * @param key the key associated with this entry
   * @param value the value associated with this entry
   * @param currentTime the ticker's current time, in nanoseconds
   * @return the length of time before the entry expires, in nanoseconds
   */
  long expireAfterCreate(K key, V value, long currentTime);

  /**
   * Specifies that the entry should be automatically removed from the cache once the duration has
   * elapsed after the replacement of its value. To indicate no expiration, an entry may be given an
   * excessively long period, such as {@link Long#MAX_VALUE}. The {@code currentDuration} may be
   * returned to not modify the expiration time.
   * <p>
   * <b>Note:</b> The {@code currentTime} is supplied by the configured {@link Ticker} and by
   * default does not relate to system or wall-clock time. When calculating the duration based on a
   * timestamp, the current time should be obtained independently.
   *
   * @param key the key associated with this entry
   * @param value the new value associated with this entry
   * @param currentTime the ticker's current time, in nanoseconds
   * @param currentDuration the entry's current duration, in nanoseconds
   * @return the length of time before the entry expires, in nanoseconds
   */
  long expireAfterUpdate(K key, V value, long currentTime, long currentDuration);

  /**
   * Specifies that the entry should be automatically removed from the cache once the duration has
   * elapsed after its last read. To indicate no expiration, an entry may be given an excessively
   * long period, such as {@link Long#MAX_VALUE}. The {@code currentDuration} may be returned to not
   * modify the expiration time.
   * <p>
   * <b>Note:</b> The {@code currentTime} is supplied by the configured {@link Ticker} and by
   * default does not relate to system or wall-clock time. When calculating the duration based on a
   * timestamp, the current time should be obtained independently.
   *
   * @param key the key associated with this entry
   * @param value the value associated with this entry
   * @param currentTime the ticker's current time, in nanoseconds
   * @param currentDuration the entry's current duration, in nanoseconds
   * @return the length of time before the entry expires, in nanoseconds
   */
  long expireAfterRead(K key, V value, long currentTime, long currentDuration);

  /**
   * Returns an {@code Expiry} that specifies that the entry should be automatically removed from
   * the cache once the duration has elapsed after the entry's creation. The expiration time is
   * not modified when the entry is updated or read.
   * {@snippet class=com.github.benmanes.caffeine.cache.Snippets region=expiry_creating lang=java}
   *
   * @param <K> the key type
   * @param <V> the value type
   * @param function the function used to calculate the length of time after an entry is created
   *        before it should be automatically removed
   * @return an {@code Expiry} instance with the specified expiry function
   */
  static <K, V> Expiry<K, V> creating(BiFunction<K, V, Duration> function) {
    return new ExpiryAfterCreate<>(function);
  }

  /**
   * Returns an {@code Expiry} that specifies that the entry should be automatically removed from
   * the cache once the duration has elapsed after the entry's creation or replacement of its value.
   * The expiration time is not modified when the entry is read.
   * {@snippet class=com.github.benmanes.caffeine.cache.Snippets region=expiry_writing lang=java}
   *
   * @param <K> the key type
   * @param <V> the value type
   * @param function the function used to calculate the length of time after an entry is created
   *        or updated that it should be automatically removed
   * @return an {@code Expiry} instance with the specified expiry function
   */
  static <K, V> Expiry<K, V> writing(BiFunction<K, V, Duration> function) {
    return new ExpiryAfterWrite<>(function);
  }

  /**
   * Returns an {@code Expiry} that specifies that the entry should be automatically removed from
   * the cache once the duration has elapsed after the entry's creation, replacement of its value,
   * or after it was last read.
   * {@snippet class=com.github.benmanes.caffeine.cache.Snippets region=expiry_accessing lang=java}
   *
   * @param <K> the key type
   * @param <V> the value type
   * @param function the function used to calculate the length of time after an entry last accessed
   *        that it should be automatically removed
   * @return an {@code Expiry} instance with the specified expiry function
   */
  static <K, V> Expiry<K, V> accessing(BiFunction<K, V, Duration> function) {
    return new ExpiryAfterAccess<>(function);
  }
}

final class ExpiryAfterCreate<K, V> implements Expiry<K, V>, Serializable {
  private static final long serialVersionUID = 1L;

  @SuppressWarnings("serial")
  final BiFunction<K, V, Duration> function;

  public ExpiryAfterCreate(BiFunction<K, V, Duration> calculator) {
    this.function = requireNonNull(calculator);
  }
  @Override public long expireAfterCreate(K key, V value, long currentTime) {
    return toNanosSaturated(function.apply(key, value));
  }
  @CanIgnoreReturnValue
  @Override public long expireAfterUpdate(K key, V value, long currentTime, long currentDuration) {
    return currentDuration;
  }
  @CanIgnoreReturnValue
  @Override public long expireAfterRead(K key, V value, long currentTime, long currentDuration) {
    return currentDuration;
  }
}

final class ExpiryAfterWrite<K, V> implements Expiry<K, V>, Serializable {
  private static final long serialVersionUID = 1L;

  @SuppressWarnings("serial")
  final BiFunction<K, V, Duration> function;

  public ExpiryAfterWrite(BiFunction<K, V, Duration> calculator) {
    this.function = requireNonNull(calculator);
  }
  @Override public long expireAfterCreate(K key, V value, long currentTime) {
    return toNanosSaturated(function.apply(key, value));
  }
  @Override public long expireAfterUpdate(K key, V value, long currentTime, long currentDuration) {
    return toNanosSaturated(function.apply(key, value));
  }
  @CanIgnoreReturnValue
  @Override public long expireAfterRead(K key, V value, long currentTime, long currentDuration) {
    return currentDuration;
  }
}

final class ExpiryAfterAccess<K, V> implements Expiry<K, V>, Serializable {
  private static final long serialVersionUID = 1L;

  @SuppressWarnings("serial")
  final BiFunction<K, V, Duration> function;

  public ExpiryAfterAccess(BiFunction<K, V, Duration> calculator) {
    this.function = requireNonNull(calculator);
  }
  @Override public long expireAfterCreate(K key, V value, long currentTime) {
    return toNanosSaturated(function.apply(key, value));
  }
  @Override public long expireAfterUpdate(K key, V value, long currentTime, long currentDuration) {
    return toNanosSaturated(function.apply(key, value));
  }
  @Override public long expireAfterRead(K key, V value, long currentTime, long currentDuration) {
    return toNanosSaturated(function.apply(key, value));
  }
}

1	/*
2	* Copyright 2017 Ben Manes. All Rights Reserved.
3	*
4	* Licensed under the Apache License, Version 2.0 (the "License");
5	* you may not use this file except in compliance with the License.
6	* You may obtain a copy of the License at
7	*
8	* http://www.apache.org/licenses/LICENSE-2.0
9	*
10	* Unless required by applicable law or agreed to in writing, software
11	* distributed under the License is distributed on an "AS IS" BASIS,
12	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13	* See the License for the specific language governing permissions and
14	* limitations under the License.
15	*/
16	package com.github.benmanes.caffeine.cache;
17
18	import static com.github.benmanes.caffeine.cache.Caffeine.toNanosSaturated;
19	import static java.util.Objects.requireNonNull;
20
21	import java.io.Serializable;
22	import java.time.Duration;
23	import java.util.function.BiFunction;
24
25	import org.jspecify.annotations.NullMarked;
26
27	import com.google.errorprone.annotations.CanIgnoreReturnValue;
28
29	/**
30	* Calculates when cache entries expire. A single expiration time is retained so that the lifetime
31	* of an entry may be extended or reduced by subsequent evaluations.
32	* <p>
33	* Usage example:
34	* {@snippet class=com.github.benmanes.caffeine.cache.Snippets region=expiry lang=java}
35	*
36	* @param <K> the type of keys
37	* @param <V> the type of values
38	* @author ben.manes@gmail.com (Ben Manes)
39	*/
40	@NullMarked
41	@SuppressWarnings({"JavadocDeclaration", "JavadocReference"})
42	public interface Expiry<K, V> {
43
44	/**
45	* Specifies that the entry should be automatically removed from the cache once the duration has
46	* elapsed after the entry's creation. To indicate no expiration, an entry may be given an
47	* excessively long period, such as {@link Long#MAX_VALUE}.
48	* <p>
49	* <b>Note:</b> The {@code currentTime} is supplied by the configured {@link Ticker} and by
50	* default does not relate to system or wall-clock time. When calculating the duration based on a
51	* timestamp, the current time should be obtained independently.
52	*
53	* @param key the key associated with this entry
54	* @param value the value associated with this entry
55	* @param currentTime the ticker's current time, in nanoseconds
56	* @return the length of time before the entry expires, in nanoseconds
57	*/
58	long expireAfterCreate(K key, V value, long currentTime);
59
60	/**
61	* Specifies that the entry should be automatically removed from the cache once the duration has
62	* elapsed after the replacement of its value. To indicate no expiration, an entry may be given an
63	* excessively long period, such as {@link Long#MAX_VALUE}. The {@code currentDuration} may be
64	* returned to not modify the expiration time.
65	* <p>
66	* <b>Note:</b> The {@code currentTime} is supplied by the configured {@link Ticker} and by
67	* default does not relate to system or wall-clock time. When calculating the duration based on a
68	* timestamp, the current time should be obtained independently.
69	*
70	* @param key the key associated with this entry
71	* @param value the new value associated with this entry
72	* @param currentTime the ticker's current time, in nanoseconds
73	* @param currentDuration the entry's current duration, in nanoseconds
74	* @return the length of time before the entry expires, in nanoseconds
75	*/
76	long expireAfterUpdate(K key, V value, long currentTime, long currentDuration);
77
78	/**
79	* Specifies that the entry should be automatically removed from the cache once the duration has
80	* elapsed after its last read. To indicate no expiration, an entry may be given an excessively
81	* long period, such as {@link Long#MAX_VALUE}. The {@code currentDuration} may be returned to not
82	* modify the expiration time.
83	* <p>
84	* <b>Note:</b> The {@code currentTime} is supplied by the configured {@link Ticker} and by
85	* default does not relate to system or wall-clock time. When calculating the duration based on a
86	* timestamp, the current time should be obtained independently.
87	*
88	* @param key the key associated with this entry
89	* @param value the value associated with this entry
90	* @param currentTime the ticker's current time, in nanoseconds
91	* @param currentDuration the entry's current duration, in nanoseconds
92	* @return the length of time before the entry expires, in nanoseconds
93	*/
94	long expireAfterRead(K key, V value, long currentTime, long currentDuration);
95
96	/**
97	* Returns an {@code Expiry} that specifies that the entry should be automatically removed from
98	* the cache once the duration has elapsed after the entry's creation. The expiration time is
99	* not modified when the entry is updated or read.
100	* {@snippet class=com.github.benmanes.caffeine.cache.Snippets region=expiry_creating lang=java}
101	*
102	* @param <K> the key type
103	* @param <V> the value type
104	* @param function the function used to calculate the length of time after an entry is created
105	* before it should be automatically removed
106	* @return an {@code Expiry} instance with the specified expiry function
107	*/
108	static <K, V> Expiry<K, V> creating(BiFunction<K, V, Duration> function) {
109	return new ExpiryAfterCreate<>(function);	×
110	}
111
112	/**
113	* Returns an {@code Expiry} that specifies that the entry should be automatically removed from
114	* the cache once the duration has elapsed after the entry's creation or replacement of its value.
115	* The expiration time is not modified when the entry is read.
116	* {@snippet class=com.github.benmanes.caffeine.cache.Snippets region=expiry_writing lang=java}
117	*
118	* @param <K> the key type
119	* @param <V> the value type
120	* @param function the function used to calculate the length of time after an entry is created
121	* or updated that it should be automatically removed
122	* @return an {@code Expiry} instance with the specified expiry function
123	*/
124	static <K, V> Expiry<K, V> writing(BiFunction<K, V, Duration> function) {
125	return new ExpiryAfterWrite<>(function);	×
126	}
127
128	/**
129	* Returns an {@code Expiry} that specifies that the entry should be automatically removed from
130	* the cache once the duration has elapsed after the entry's creation, replacement of its value,
131	* or after it was last read.
132	* {@snippet class=com.github.benmanes.caffeine.cache.Snippets region=expiry_accessing lang=java}
133	*
134	* @param <K> the key type
135	* @param <V> the value type
136	* @param function the function used to calculate the length of time after an entry last accessed
137	* that it should be automatically removed
138	* @return an {@code Expiry} instance with the specified expiry function
139	*/
140	static <K, V> Expiry<K, V> accessing(BiFunction<K, V, Duration> function) {
141	return new ExpiryAfterAccess<>(function);	×
142	}
143	}
144
145	final class ExpiryAfterCreate<K, V> implements Expiry<K, V>, Serializable {
146	private static final long serialVersionUID = 1L;
147
148	@SuppressWarnings("serial")
149	final BiFunction<K, V, Duration> function;
150
151	public ExpiryAfterCreate(BiFunction<K, V, Duration> calculator) {	×
152	this.function = requireNonNull(calculator);	×
153	}	×
154	@Override public long expireAfterCreate(K key, V value, long currentTime) {
155	return toNanosSaturated(function.apply(key, value));	×
156	}
157	@CanIgnoreReturnValue
158	@Override public long expireAfterUpdate(K key, V value, long currentTime, long currentDuration) {
159	return currentDuration;	×
160	}
161	@CanIgnoreReturnValue
162	@Override public long expireAfterRead(K key, V value, long currentTime, long currentDuration) {
163	return currentDuration;	×
164	}
165	}
166
167	final class ExpiryAfterWrite<K, V> implements Expiry<K, V>, Serializable {
168	private static final long serialVersionUID = 1L;
169
170	@SuppressWarnings("serial")
171	final BiFunction<K, V, Duration> function;
172
173	public ExpiryAfterWrite(BiFunction<K, V, Duration> calculator) {	×
174	this.function = requireNonNull(calculator);	×
175	}	×
176	@Override public long expireAfterCreate(K key, V value, long currentTime) {
177	return toNanosSaturated(function.apply(key, value));	×
178	}
179	@Override public long expireAfterUpdate(K key, V value, long currentTime, long currentDuration) {
180	return toNanosSaturated(function.apply(key, value));	×
181	}
182	@CanIgnoreReturnValue
183	@Override public long expireAfterRead(K key, V value, long currentTime, long currentDuration) {
184	return currentDuration;	×
185	}
186	}
187
188	final class ExpiryAfterAccess<K, V> implements Expiry<K, V>, Serializable {
189	private static final long serialVersionUID = 1L;
190
191	@SuppressWarnings("serial")
192	final BiFunction<K, V, Duration> function;
193
194	public ExpiryAfterAccess(BiFunction<K, V, Duration> calculator) {	×
195	this.function = requireNonNull(calculator);	×
196	}	×
197	@Override public long expireAfterCreate(K key, V value, long currentTime) {
198	return toNanosSaturated(function.apply(key, value));	×
199	}
200	@Override public long expireAfterUpdate(K key, V value, long currentTime, long currentDuration) {
201	return toNanosSaturated(function.apply(key, value));	×
202	}
203	@Override public long expireAfterRead(K key, V value, long currentTime, long currentDuration) {
204	return toNanosSaturated(function.apply(key, value));	×
205	}
206	}

ben-manes / caffeine / #5707

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous