javax.faces.component.EditableValueHolder Maven / Gradle / Ivy
Show all versions of jakarta.faces Show documentation
/*
* Copyright (c) 1997, 2018 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 javax.faces.component;
import javax.faces.el.MethodBinding;
import javax.faces.event.ValueChangeEvent;
import javax.faces.event.ValueChangeListener;
import javax.faces.render.Renderer;
import javax.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
* javax.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULLcontext-param.
*
*
* @return the submitted value.
*/
public Object getSubmittedValue();
/**
*
* Convenience method to reset this component's value to the un-initialized state.
*
*
* @since 2.0
*/
public 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
* javax.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULLcontext-param.
*
*
* @param submittedValue The new submitted value
*/
public 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.
*/
public boolean isLocalValueSet();
/**
* Sets the "local value set" state for this component.
*
* @param localValueSet the "local value set" boolean.
*/
public 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.
*/
public 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
*/
public void setValid(boolean valid);
/**
*
* Return the "required field" state for this component.
*
*
* @return true if required, false otherwise.
*/
public boolean isRequired();
/**
*
* Set the "required field" state for this component.
*
*
* @param required The new "required field" state
*/
public void setRequired(boolean required);
/**
*
* Return the "immediate" state for this component.
*
*
* @return true if is immediate, false otherwise.
*/
public 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
*/
public 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
*/
public 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.
*/
public 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
*/
public 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
*/
public 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.
*/
public 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
*/
public 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.
*/
public MethodBinding getValidator();
/**
*
* Wrap the argument validatorBinding in an implementation of
* {@link javax.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 javax.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 javax.faces.validator.MethodExpressionValidator}.
*/
public 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.
*/
public 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 javax.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 javax.faces.event.MethodExpressionValueChangeListener}.
*/
public void setValueChangeListener(MethodBinding valueChangeMethod);
}