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

Go to download
/*
 * Copyright (c) 1997, 2020 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 jakarta.faces.context.FacesContext;
import jakarta.faces.convert.Converter;

/**
 * 
 * UIOutput is a {@link UIComponent} that has a
 * value, optionally retrieved from a model tier bean via a value expression, that is displayed to the user. The user
 * cannot directly modify the rendered value; it is for display purposes only.
 * 
 *
 * 
 * During the Render Response phase of the request processing lifecycle, the current value of this component
 * must be converted to a String (if it is not already), according to the following rules:
 * 
 * 
 * If the current value is not null, and is not already a String, locate a
 * {@link Converter} (if any) to use for the conversion, as follows:
 * 
 * If getConverter() returns a non-null {@link Converter}, use that one, otherwise
 * If Application.createConverter(Class), passing the current value's class, returns a non-null
 * {@link Converter}, use that one.
 * 
 * 
 * If the current value is not null and a {@link Converter} was located, call its
 * getAsString() method to perform the conversion.
 * If the current value is not null but no {@link Converter} was located, call toString()
 * on the current value to perform the conversion.
 * 
 *
 * 
 * By default, the rendererType property must be set to "jakarta.faces.Text". This value can
 * be changed by calling the setRendererType() method.
 * 
 */
public class UIOutput extends UIComponentBase implements ValueHolder {

    // ------------------------------------------------------ Manifest Constants

    /**
     * 
     * The standard component type for this component.
     * 
     */
    public static final String COMPONENT_TYPE = "jakarta.faces.Output";

    /**
     * 
     * The standard component family for this component.
     * 
     */
    public static final String COMPONENT_FAMILY = "jakarta.faces.Output";

    private static final String FORCE_FULL_CONVERTER_STATE = "com.sun.faces.component.UIOutput.forceFullConverterState";

    enum PropertyKeys {
        value, converter
    }

    private Converter converter;

    // ------------------------------------------------------------ Constructors

    /**
     * 
     * Create a new {@link UIOutput} instance with default property values.
     * 
     */
    public UIOutput() {
        super();
        setRendererType("jakarta.faces.Text");
    }

    // -------------------------------------------------------------- Properties

    @Override
    public String getFamily() {
        return COMPONENT_FAMILY;
    }

    // --------------------------------------- EditableValueHolder Properties

    @Override
    public Converter getConverter() {

        if (converter != null) {
            return converter;
        }

        return (Converter) getStateHelper().eval(PropertyKeys.converter);
    }

    @Override
    public void setConverter(Converter converter) {

        clearInitialState();
        // we don't push the converter to the StateHelper
        // if it's been explicitly set (i.e. it's not a ValueExpression
        // reference
        this.converter = converter;
    }

    @Override
    public Object getLocalValue() {
        return getStateHelper().get(PropertyKeys.value);
    }

    /**
     * 
     * Return the value property.
     * 
     *
     * @since 2.2
     */
    @Override
    public Object getValue() {
        return getStateHelper().eval(PropertyKeys.value);
    }

    @Override
    public void setValue(Object value) {
        getStateHelper().put(PropertyKeys.value, value);
    }

    /**
     * 
     * Convenience method to reset this component's value to the un-initialized state.
     * 
     *
     * @since 2.2
     */
    public void resetValue() {
        getStateHelper().remove(PropertyKeys.value);
    }

    /**
     * 
     * In addition to the actions taken in {@link UIComponentBase} when {@link PartialStateHolder#markInitialState()} is
     * called, check if the installed {@link Converter} is a PartialStateHolder and if it is, call
     * {@link jakarta.faces.component.PartialStateHolder#markInitialState()} on it.
     * 
     */
    @Override
    public void markInitialState() {
        super.markInitialState();

        Converter c = getConverter();
        if (c instanceof PartialStateHolder) {
            ((PartialStateHolder) c).markInitialState();
        }
    }

    @Override
    public void clearInitialState() {
        if (initialStateMarked()) {
            super.clearInitialState();

            Converter c = getConverter();
            if (c != null && c instanceof PartialStateHolder) {
                ((PartialStateHolder) c).clearInitialState();
            }
        }
    }

    @Override
    public Object saveState(FacesContext context) {
        if (context == null) {
            throw new NullPointerException();
        }

        Object converterState = null;
        if (converter != null) {
            if (!initialStateMarked() || getAttributes().containsKey(FORCE_FULL_CONVERTER_STATE)) {
                /*
                 * Check if our parent component has its initial state marked and we know we don't. That means we are not using the same
                 * state saving algorithm. So we are going to ALWAYS force to do FSS for the converter.
                 */
                if (getParent() != null && getParent().initialStateMarked()) {
                    getAttributes().put(FORCE_FULL_CONVERTER_STATE, true);
                    if (converter instanceof PartialStateHolder) {
                        PartialStateHolder partialStateHolder = (PartialStateHolder) converter;
                        partialStateHolder.clearInitialState();
                    }
                }

                converterState = saveAttachedState(context, converter);
            } else {
                if (converter instanceof StateHolder) {
                    StateHolder stateHolder = (StateHolder) converter;
                    if (!stateHolder.isTransient()) {
                        converterState = ((StateHolder) converter).saveState(context);
                    }
                }
            }
        }

        Object[] values = (Object[]) super.saveState(context);

        if (converterState != null || values != null) {
            return new Object[] { values, converterState };
        }

        return values;
    }

    @Override
    public void restoreState(FacesContext context, Object state) {

        if (context == null) {
            throw new NullPointerException();
        }

        if (state == null) {
            return;
        }

        Object[] values = (Object[]) state;
        super.restoreState(context, values[0]);
        Object converterState = values[1];
        if (converterState instanceof StateHolderSaver) {
            // this means full state was saved and as such
            // overwrite any existing converter with the saved
            // converter
            converter = (Converter) restoreAttachedState(context, converterState);
        } else {
            // apply any saved state to the existing converter
            if (converterState != null && converter instanceof StateHolder) {
                ((StateHolder) converter).restoreState(context, converterState);
            }
        }
    }
}