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

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jakarta.faces Show documentation
EE4J Compatible Implementation for Jakarta Faces API
The newest version!
/*
 * 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