javax.faces.component.EditableValueHolder Maven / Gradle / Ivy
Show all versions of javax.faces-api Show documentation
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 1997-2010 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.faces.component;
import javax.faces.event.ValueChangeEvent;
import javax.faces.event.ValueChangeListener;
import javax.faces.validator.Validator;
import javax.faces.el.MethodBinding;
import javax.faces.render.Renderer;
/**
* 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);
/**
* 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);
/**
* 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);
}