1 package org.apache.maven.api; 2 3 /* 4 * Licensed to the Apache Software Foundation (ASF) under one 5 * or more contributor license agreements. See the NOTICE file 6 * distributed with this work for additional information 7 * regarding copyright ownership. The ASF licenses this file 8 * to you under the Apache License, Version 2.0 (the 9 * "License"); you may not use this file except in compliance 10 * with the License. You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, 15 * software distributed under the License is distributed on an 16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17 * KIND, either express or implied. See the License for the 18 * specific language governing permissions and limitations 19 * under the License. 20 */ 21 22 import org.apache.maven.api.annotations.Experimental; 23 import org.apache.maven.api.annotations.Nonnull; 24 import org.apache.maven.api.annotations.Nullable; 25 import org.apache.maven.api.annotations.Provider; 26 import org.apache.maven.api.annotations.ThreadSafe; 27 28 import java.util.function.Supplier; 29 30 /** 31 * A container for data that is specific to a session. 32 * All components may use this storage to associate arbitrary data with a session. 33 * <p> 34 * Unlike a cache, this session data is not subject to purging. For this same reason, session data should also not be 35 * abused as a cache (i.e. for storing values that can be re-calculated) to avoid memory exhaustion. 36 * <p> 37 * <strong>Note:</strong> Actual implementations must be thread-safe. 38 * 39 * @see Session#getData() 40 * @since 4.0 41 */ 42 @Experimental 43 @ThreadSafe @Provider 44 public interface SessionData 45 { 46 47 /** 48 * Associates the specified session data with the given key. 49 * 50 * @param key The key under which to store the session data, must not be {@code null}. 51 * @param value The data to associate with the key, may be {@code null} to remove the mapping. 52 */ 53 void set( @Nonnull Object key, @Nullable Object value ); 54 55 /** 56 * Associates the specified session data with the given key if the key is currently mapped to the given value. This 57 * method provides an atomic compare-and-update of some key's value. 58 * 59 * @param key The key under which to store the session data, must not be {@code null}. 60 * @param oldValue The expected data currently associated with the key, may be {@code null}. 61 * @param newValue The data to associate with the key, may be {@code null} to remove the mapping. 62 * @return {@code true} if the key mapping was successfully updated from the old value to the new value, 63 * {@code false} if the current key mapping didn't match the expected value and was not updated. 64 */ 65 boolean set( @Nonnull Object key, @Nullable Object oldValue, @Nullable Object newValue ); 66 67 /** 68 * Gets the session data associated with the specified key. 69 * 70 * @param key The key for which to retrieve the session data, must not be {@code null}. 71 * @return The session data associated with the key or {@code null} if none. 72 */ 73 @Nullable 74 Object get( @Nonnull Object key ); 75 76 /** 77 * Retrieve of compute the data associated with the specified key. 78 * 79 * @param key The key for which to retrieve the session data, must not be {@code null}. 80 * @param supplier The supplier will compute the new value. 81 * @return The session data associated with the key. 82 */ 83 @Nullable 84 Object computeIfAbsent( @Nonnull Object key, @Nonnull Supplier<Object> supplier ); 85 86 }