jakarta.faces.component.EditableValueHolder Maven / Gradle / Ivy
/*
* 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.event.ValueChangeEvent;
import jakarta.faces.event.ValueChangeListener;
import jakarta.faces.render.Renderer;
import jakarta.faces.validator.Validator;
/**
*
* EditableValueHolder is an extension of
* ValueHolder that describes additional features supported by editable components, including {@link ValueChangeEvent}s
* and {@link Validator}s.
*/
public interface EditableValueHolder extends ValueHolder {
/**
*
* Return the submittedValue value of this component. This method should only be used by the encodeBegin()
* and/or encodeEnd() methods of this component, or its corresponding {@link Renderer}.
* The action taken based on whether the value is null, empty, or
* non-null is determined based on the value of the
* jakarta.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULLcontext-param.
*
*
* @return the submitted value.
*/
Object getSubmittedValue();
/**
*
* Convenience method to reset this component's value to the un-initialized state.
*
*
* @since 2.0
*/
void resetValue();
/**
*
* Set the submittedValue value of this component. This method should only be used by the decode() and
* validate() method of this component, or its corresponding {@link Renderer}.
* The action taken based on whether the value is null, empty, or
* non-null is determined based on the value of the
* jakarta.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULLcontext-param.
*
*
* @param submittedValue The new submitted value
*/
void setSubmittedValue(Object submittedValue);
/**
* Return the "local value set" state for this component. Calls to setValue() automatically reset this
* property to true.
*
* @return true if the local value is set, false otherwise.
*/
boolean isLocalValueSet();
/**
* Sets the "local value set" state for this component.
*
* @param localValueSet the "local value set" boolean.
*/
void setLocalValueSet(boolean localValueSet);
/**
*
* Return a flag indicating whether the local value of this component is valid (no conversion error has occurred).
*
*
* @return true if valid, false otherwise.
*/
boolean isValid();
/**
*
* Set a flag indicating whether the local value of this component is valid (no conversion error has occurred).
*
*
* @param valid The new valid flag
*/
void setValid(boolean valid);
/**
*
* Return the "required field" state for this component.
*
*
* @return true if required, false otherwise.
*/
boolean isRequired();
/**
*
* Set the "required field" state for this component.
*
*
* @param required The new "required field" state
*/
void setRequired(boolean required);
/**
*
* Return the "immediate" state for this component.
*
*
* @return true if is immediate, false otherwise.
*/
boolean isImmediate();
/**
*
* Set the "immediate" state for this component. When set to true, the component's value will be converted and validated
* immediately in the Apply Request Values phase, and {@link ValueChangeEvent}s will be delivered in that phase
* as well. The default value for this property must be false.
*
*
* @param immediate The new "immediate" state
*/
void setImmediate(boolean immediate);
/**
*
* Add a {@link Validator} instance to the set associated with this component.
*
*
* @param validator The {@link Validator} to add
*
* @throws NullPointerException if validator is null
*/
void addValidator(Validator validator);
/**
*
* Return the set of registered {@link Validator}s for this component instance. If there are no registered validators, a
* zero-length array is returned.
*
*
* @return the validators, or a zero-length array.
*/
Validator[] getValidators();
/**
*
* Remove a {@link Validator} instance from the set associated with this component, if it was previously associated.
* Otherwise, do nothing.
*
*
* @param validator The {@link Validator} to remove
*/
void removeValidator(Validator validator);
/**
*
* Add a new {@link ValueChangeListener} to the set of listeners interested in being notified when
* {@link ValueChangeEvent}s occur.
*
*
* @param listener The {@link ValueChangeListener} to be added
*
* @throws NullPointerException if listener is null
*/
void addValueChangeListener(ValueChangeListener listener);
/**
*
* Return the set of registered {@link ValueChangeListener}s for this component instance. If there are no registered
* listeners, a zero-length array is returned.
*
*
* @return the value change listeners, or a zero-length array.
*/
ValueChangeListener[] getValueChangeListeners();
/**
*
* Remove an existing {@link ValueChangeListener} (if any) from the set of listeners interested in being notified when
* {@link ValueChangeEvent}s occur.
*
*
* @param listener The {@link ValueChangeListener} to be removed
*
* @throws NullPointerException if listener is null
*/
void removeValueChangeListener(ValueChangeListener listener);
}