#5173

Committed 29 Dec 2025 05:27AM UTC coverage: 0.0% (-100.0%) from 100.0%

Build # #5173

Build Type

push

github

Committed by

ben-manes

Commit Message

speed up development ci build

Run Details

0 of 3838 branches covered (0.0%)

0 of 7869 relevant lines covered (0.0%)

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	*
101	* {@snippet class=com.github.benmanes.caffeine.cache.Snippets region=expiry_creating lang=java}
102	*
103	* @param <K> the key type
104	* @param <V> the value type
105	* @param function the function used to calculate the length of time after an entry is created
106	* before it should be automatically removed
107	* @return an {@code Expiry} instance with the specified expiry function
108	*/
109	static <K, V> Expiry<K, V> creating(BiFunction<K, V, Duration> function) {
110	return new ExpiryAfterCreate<>(function);	×
111	}
112
113	/**
114	* Returns an {@code Expiry} that specifies that the entry should be automatically removed from
115	* the cache once the duration has elapsed after the entry's creation or replacement of its value.
116	* The expiration time is not modified when the entry is read.
117	*
118	* {@snippet class=com.github.benmanes.caffeine.cache.Snippets region=expiry_writing lang=java}
119	*
120	* @param <K> the key type
121	* @param <V> the value type
122	* @param function the function used to calculate the length of time after an entry is created
123	* or updated that it should be automatically removed
124	* @return an {@code Expiry} instance with the specified expiry function
125	*/
126	static <K, V> Expiry<K, V> writing(BiFunction<K, V, Duration> function) {
127	return new ExpiryAfterWrite<>(function);	×
128	}
129
130	/**
131	* Returns an {@code Expiry} that specifies that the entry should be automatically removed from
132	* the cache once the duration has elapsed after the entry's creation, replacement of its value,
133	* or after it was last read.
134	*
135	* {@snippet class=com.github.benmanes.caffeine.cache.Snippets region=expiry_accessing lang=java}
136	*
137	* @param <K> the key type
138	* @param <V> the value type
139	* @param function the function used to calculate the length of time after an entry last accessed
140	* that it should be automatically removed
141	* @return an {@code Expiry} instance with the specified expiry function
142	*/
143	static <K, V> Expiry<K, V> accessing(BiFunction<K, V, Duration> function) {
144	return new ExpiryAfterAccess<>(function);	×
145	}
146	}
147
148	final class ExpiryAfterCreate<K, V> implements Expiry<K, V>, Serializable {
149	private static final long serialVersionUID = 1L;
150
151	@SuppressWarnings("serial")
152	final BiFunction<K, V, Duration> function;
153
154	public ExpiryAfterCreate(BiFunction<K, V, Duration> calculator) {	×
155	this.function = requireNonNull(calculator);	×
156	}	×
157	@Override public long expireAfterCreate(K key, V value, long currentTime) {
158	return toNanosSaturated(function.apply(key, value));	×
159	}
160	@CanIgnoreReturnValue
161	@Override public long expireAfterUpdate(K key, V value, long currentTime, long currentDuration) {
162	return currentDuration;	×
163	}
164	@CanIgnoreReturnValue
165	@Override public long expireAfterRead(K key, V value, long currentTime, long currentDuration) {
166	return currentDuration;	×
167	}
168	}
169
170	final class ExpiryAfterWrite<K, V> implements Expiry<K, V>, Serializable {
171	private static final long serialVersionUID = 1L;
172
173	@SuppressWarnings("serial")
174	final BiFunction<K, V, Duration> function;
175
176	public ExpiryAfterWrite(BiFunction<K, V, Duration> calculator) {	×
177	this.function = requireNonNull(calculator);	×
178	}	×
179	@Override public long expireAfterCreate(K key, V value, long currentTime) {
180	return toNanosSaturated(function.apply(key, value));	×
181	}
182	@Override public long expireAfterUpdate(K key, V value, long currentTime, long currentDuration) {
183	return toNanosSaturated(function.apply(key, value));	×
184	}
185	@CanIgnoreReturnValue
186	@Override public long expireAfterRead(K key, V value, long currentTime, long currentDuration) {
187	return currentDuration;	×
188	}
189	}
190
191	final class ExpiryAfterAccess<K, V> implements Expiry<K, V>, Serializable {
192	private static final long serialVersionUID = 1L;
193
194	@SuppressWarnings("serial")
195	final BiFunction<K, V, Duration> function;
196
197	public ExpiryAfterAccess(BiFunction<K, V, Duration> calculator) {	×
198	this.function = requireNonNull(calculator);	×
199	}	×
200	@Override public long expireAfterCreate(K key, V value, long currentTime) {
201	return toNanosSaturated(function.apply(key, value));	×
202	}
203	@Override public long expireAfterUpdate(K key, V value, long currentTime, long currentDuration) {
204	return toNanosSaturated(function.apply(key, value));	×
205	}
206	@Override public long expireAfterRead(K key, V value, long currentTime, long currentDuration) {
207	return toNanosSaturated(function.apply(key, value));	×
208	}
209	}

ben-manes / caffeine / #5173

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