/*
 * 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.dev.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;


/**
 * <p><strong class="changed_modified_2_0
 * changed_modified_2_0_rev_a">EditableValueHolder</strong> 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 {

    /**
     * <p>Return the submittedValue value of this component.  This
     * method should only be used by the <code>encodeBegin()</code>
     * and/or <code>encodeEnd()</code> methods of this component, or its
     * corresponding {@link Renderer}.  <span
     * class="changed_modified_2_0_rev_a">The action taken based on
     * whether the value is <code>null</code>, empty, or
     * non-<code>null</code> is determined based on the value of the
     * <code>javax.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL</code>context-param.</span></p>
     */
    public Object getSubmittedValue();

    /**
     * <p class="changed_added_2_0">Convenience method to reset this
     * component's value to the un-initialized state.</p>
     *
     * @since 2.0
     */

    public void resetValue();


    /**
     * <p>Set the submittedValue value of this component.  This method
     * should only be used by the <code>decode()</code> and
     * <code>validate()</code> method of this component, or its
     * corresponding {@link Renderer}.  <span
     * class="changed_modified_2_0_rev_a">The action taken based on
     * whether the value is <code>null</code>, empty, or
     * non-<code>null</code> is determined based on the value of the
     * <code>javax.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL</code>context-param.</span></p>

     * @param submittedValue The new submitted value
     */
    public void setSubmittedValue(Object submittedValue);

    /**
     * Return the "local value set" state for this component.
     * Calls to <code>setValue()</code> automatically reset
     * this property to <code>true</code>.
     */
    public boolean isLocalValueSet();

    /**
     * Sets the "local value set" state for this component.
     */
    public void setLocalValueSet(boolean localValueSet);



    /**
     * <p>Return a flag indicating whether the local value of this component
     * is valid (no conversion error has occurred).</p>
     */
    public boolean isValid();


    /**
     * <p>Set a flag indicating whether the local value of this component
     * is valid (no conversion error has occurred).</p>
     *
     * @param valid The new valid flag
     */
    public void setValid(boolean valid);


    /**
     * <p>Return the "required field" state for this component.</p>
     */
    public boolean isRequired();

    /**
     * <p>Set the "required field" state for this component.</p>
     *
     * @param required The new "required field" state
     */
    public void setRequired(boolean required);

    /**
     * <p>Return the "immediate" state for this component.</p>
     */
    public boolean isImmediate();

    /**
     * <p>Set the "immediate" state for this component.  When
     * set to true, the component's value will be converted
     * and validated immediately in the <em>Apply Request Values</em>
     * phase, and {@link ValueChangeEvent}s will be delivered
     * in that phase as well.  The default value for this
     * property must be <code>false</code>.</p>
     *
     * @param immediate The new "immediate" state
     */
    public void setImmediate(boolean immediate);

    /**
     * <p>If {@link #setValidator} was not previously called for this
     * instance, this method must return <code>null</code>.  If it was
     * called, this method must return the exact
     * <code>MethodBinding</code> instance that was passed to {@link
     * #setValidator}.</p>
     *
     * <p>This method will be called during the <em>Process
     * Validations</em> or <em>Apply Request Values</em> phases
     * (depending on the value of the <code>immediate</code>
     * property). </p>
     *
     * @deprecated {@link #getValidators} should be used instead.
     */
    public MethodBinding getValidator();

    /**
     * <p>Wrap the argument <code>validatorBinding</code> 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 <code>setValidator</code>.
     * </p>
     *
     * <p>The argument method will be called during the <em>Process
     * Validations</em> or <em>Apply Request Values</em> phases
     * (depending on the value of the <code>immediate</code>
     * property). </p>
     *
     * <p>Any method referenced by such an expression must be public,
     * with a return type of <code>void</code>, and accept parameters of
     * type {@link javax.faces.context.FacesContext}, {@link
     * UIComponent}, and <code>Object</code>.</p>
     *
     * @param validatorBinding The new <code>MethodBinding</code> 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);

    /**
     * <p>If {@link #setValueChangeListener} was not previously called
     * for this instance, this method must return <code>null</code>.  If
     * it was called, this method must return the exact
     * <code>MethodBinding</code> instance that was passed to {@link
     * #setValueChangeListener}.</p>
     *
     * @deprecated Use {@link #getValueChangeListeners} instead.
     */
    public MethodBinding getValueChangeListener();

    /**
     * <p>Wrap the argument <code>valueChangeMethod</code> 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
     * <code>setValueChangeListener</code>.</p>
     *
     * <p>This argument method will be called during the <em>Process
     * Validations</em> or <em>Apply Request Values</em> phases
     * (depending on the value of the <code>immediate</code>
     * property). </p>
     *
     * <p>Any method referenced by such an expression must be public,
     * with a return type of <code>void</code>, and accept a parameter
     * of type {@link javax.faces.event.ValueChangeEvent}.</p>
     *
     * @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);

    /**
     * <p>Add a {@link
     * Validator} instance to the set associated with this
     * component.</p>
     *
     * @param validator The {@link Validator} to add
     *
     * @throws NullPointerException if <code>validator</code>
     *  is null
     */
    public void addValidator(Validator validator);

    /**
     * <p>Return the set of registered {@link Validator}s for this
     * component instance.  If there are no registered validators,
     * a zero-length array is returned.</p>
     */
    public Validator[] getValidators();

    /**
     * <p>Remove a {@link Validator} instance from the set associated with
     * this component, if it was previously associated.
     * Otherwise, do nothing.</p>
     *
     * @param validator The {@link Validator} to remove
     */
    public void removeValidator(Validator validator);

    /**
     * <p>Add a new {@link ValueChangeListener} to the set of listeners
     * interested in being notified when {@link ValueChangeEvent}s occur.</p>
     *
     * @param listener The {@link ValueChangeListener} to be added
     *
     * @throws NullPointerException if <code>listener</code>
     *  is <code>null</code>
     */
    public void addValueChangeListener(ValueChangeListener listener);

    /**
     * <p>Return the set of registered {@link ValueChangeListener}s for this
     * component instance.  If there are no registered listeners,
     * a zero-length array is returned.</p>
     */
    public ValueChangeListener[] getValueChangeListeners();

    /**
     * <p>Remove an existing {@link ValueChangeListener} (if any) from the
     * set of listeners interested in being notified when
     * {@link ValueChangeEvent}s occur.</p>
     *
     * @param listener The {@link ValueChangeListener} to be removed
     *
     * @throws NullPointerException if <code>listener</code>
     *  is <code>null</code>
     */
    public void removeValueChangeListener(ValueChangeListener listener);
}