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.el.MethodBinding;
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);
// -------------------------------------------------------------- Deprecated methods
/**
*
* If {@link #setValidator} was not previously called for this instance, this method must return null. If
* it was called, this method must return the exact MethodBinding instance that was passed to
* {@link #setValidator}.
*
*
*
* This method will be called during the Process Validations or Apply Request Values phases (depending
* on the value of the immediate property).
*
*
* @return the validator as a method binding.
* @deprecated {@link #getValidators} should be used instead.
*/
@Deprecated
MethodBinding getValidator();
/**
*
* Wrap the argument validatorBinding in an implementation of {@link jakarta.faces.validator.Validator} and
* store it in the internal data structure that backs the {@link #getValidators} method, taking care to over-write any
* instance that was stored by a previous call to setValidator.
*
*
*
* The argument method will be called during the Process Validations or Apply Request Values phases
* (depending on the value of the immediate property).
*
*
*
* Any method referenced by such an expression must be public, with a return type of void, and accept
* parameters of type {@link jakarta.faces.context.FacesContext}, {@link UIComponent}, and Object.
*
*
* @param validatorBinding The new MethodBinding instance
*
* @deprecated Use {@link #addValidator} instead, obtaining the argument {@link Validator} by creating an instance of
* {@link jakarta.faces.validator.MethodExpressionValidator}.
*/
@Deprecated
void setValidator(MethodBinding validatorBinding);
/**
*
* If {@link #setValueChangeListener} was not previously called for this instance, this method must return
* null. If it was called, this method must return the exact MethodBinding instance that was
* passed to {@link #setValueChangeListener}.
*
*
* @return the value change listener.
* @deprecated Use {@link #getValueChangeListeners} instead.
*/
@Deprecated
MethodBinding getValueChangeListener();
/**
*
* Wrap the argument valueChangeMethod in an implementation of {@link ValueChangeListener} and store it in
* the internal data structure that backs the {@link #getValueChangeListeners} method, taking care to over-write any
* instance that was stored by a previous call to setValueChangeListener.
*
*
*
* This argument method will be called during the Process Validations or Apply Request Values phases
* (depending on the value of the immediate property).
*
*
*
* Any method referenced by such an expression must be public, with a return type of void, and accept a
* parameter of type {@link jakarta.faces.event.ValueChangeEvent}.
*
*
* @param valueChangeMethod The new method binding instance
*
* @deprecated Use {@link #addValueChangeListener} instead, obtaining the argument {@link ValueChangeListener} by
* creating an instance of {@link jakarta.faces.event.MethodExpressionValueChangeListener}.
*/
@Deprecated
void setValueChangeListener(MethodBinding valueChangeMethod);
}