jakarta.faces.component.StateHelper Maven / Gradle / Ivy

/*
 * Copyright (c) 1997, 2021 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0, which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * This Source Code may also be made available under the following Secondary
 * Licenses when the conditions for such availability set forth in the
 * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
 * version 2 with the GNU Classpath Exception, which is available at
 * https://www.gnu.org/software/classpath/license.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 */

package jakarta.faces.component;

import java.io.Serializable;
import java.util.function.Supplier;

/**
 * 
 * Define a Map-like contract that makes it easier for components to implement {@link PartialStateHolder}.
 * Each {@link UIComponent} in the view will return an implementation of this interface from its
 * {@link UIComponent#getStateHelper} method.
 * 
 *
 * @since 2.0
 */
public interface StateHelper extends StateHolder {

    /**
     * 
     * Return the previously stored value and store the specified key/value pair. This is intended to store data that would
     * otherwise reside in an instance variable on the component.
     * 
     *
     * @param key the key for the value
     * @param value the value
     * @return the previously stored value
     * @since 2.0
     */
    Object put(Serializable key, Object value);

    /**
     * 
     * Remove the key/value pair from the helper, returning the value previously stored under this key.
     * 
     *
     * @param key the key to remove
     * @return the removed value.
     * @since 2.0
     */
    Object remove(Serializable key);

    /**
     * 
     * Store the specified mapKey/value in a Map that is internal to the helper, and
     * return the previously stored value. The Map will then be associated with key.
     * 
     *
     * 
     *
     * 
     * It's important to note for delta tracking that any modifications to the internal Map be made through
     * this method or {@link StateHelper#remove(java.io.Serializable, Object)}.
     * 
     *
     * 
     *
     * @param key the key of the map itself
     * @param mapKey the key within the internal map
     * @param value the value for the key in the internal map
     * @return the value.
     * @since 2.0
     */
    Object put(Serializable key, String mapKey, Object value);

    /**
     * 
     * Return the value currently associated with the specified key if any.
     * 
     *
     * @param key the key for which the value should be returned.
     * @return the value.
     * @since 2.0
     */
    Object get(Serializable key);

    /**
     * 
     * Attempts to find a value associated with the specified key, using the value expression collection from the component
     * if no such value is found.
     * 
     *
     * @param key the name of the value in the internal map, or the name of a value expression in the components value
     * expression collection.
     *
     * @return the evaluated value.
     * @since 2.0
     */
    Object eval(Serializable key);

    /**
     * 
     * Performs the same logic as {@link #eval(java.io.Serializable)} } but if no value is found, this will return the
     * specified defaultValue
     * 
     *
     * @param key the key for which the value should be returned.
     * @param defaultValue the value to return if no value is found in the call to eval().
     * @return the evaluated value.
     * @since 2.0
     */
    Object eval(Serializable key, Object defaultValue);

    /**
     * 
     * Performs the same logic as {@link #eval(java.io.Serializable)} } but if no value is found, this will return the
     * return-value of the defaultValueSupplier
     * 
     *
     * @param key the key for which the value should be returned.
     * @param defaultValueSupplier the supplier used to evaluate the default value if no value is found in the call to eval().
     * @return the evaluated value.
     * @since 4.0
     */
    Object eval(Serializable key, Supplier