123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310 |
- /*
- * Copyright 2000-2018 Vaadin Ltd.
- *
- * Licensed under the Apache License, Version 2.0 (the "License"); you may not
- * use this file except in compliance with the License. You may obtain a copy of
- * the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
- * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
- * License for the specific language governing permissions and limitations under
- * the License.
- */
- package com.vaadin.data;
-
- import java.io.Serializable;
- import java.lang.reflect.Method;
- import java.util.EventObject;
- import java.util.Objects;
- import java.util.Optional;
-
- import com.vaadin.event.HasUserOriginated;
- import com.vaadin.event.SerializableEventListener;
- import com.vaadin.shared.Registration;
- import com.vaadin.ui.Component;
- import com.vaadin.util.ReflectTools;
-
- /**
- * A generic interface for field components and other user interface objects
- * that have a user-editable value. Emits change events whenever the value is
- * changed, either by the user or programmatically.
- *
- * @author Vaadin Ltd.
- *
- * @param <V>
- * the value type
- *
- * @since 8.0
- */
- public interface HasValue<V> extends Serializable {
-
- /**
- * An event fired when the value of a {@code HasValue} changes.
- *
- * @param <V>
- * the value type
- */
- public class ValueChangeEvent<V> extends EventObject
- implements HasUserOriginated {
-
- private final boolean userOriginated;
- private final Component component;
-
- private final V oldValue;
- private final V value;
-
- /**
- * Creates a new {@code ValueChange} event containing the current value
- * of the given value-bearing source component.
- *
- * @param <COMPONENT>
- * the type of the source component
- * @param component
- * the source component bearing the value, not null
- * @param oldValue
- * the previous value held by the source of this event
- * @param userOriginated
- * {@code true} if this event originates from the client,
- * {@code false} otherwise.
- */
- public <COMPONENT extends Component & HasValue<V>> ValueChangeEvent(
- COMPONENT component, V oldValue, boolean userOriginated) {
- this(component, component, oldValue, userOriginated);
- }
-
- /**
- * Creates a new {@code ValueChange} event containing the given value,
- * originating from the given source component.
- *
- * @param component
- * the component, not null
- * @param hasValue
- * the HasValue instance bearing the value, not null
- * @param oldValue
- * the previous value held by the source of this event
- * @param userOriginated
- * {@code true} if this event originates from the client,
- * {@code false} otherwise.
- */
-
- public ValueChangeEvent(Component component, HasValue<V> hasValue,
- V oldValue, boolean userOriginated) {
- super(hasValue);
- this.userOriginated = userOriginated;
- this.component = component;
- this.oldValue = oldValue;
- value = hasValue.getValue();
- }
-
- /**
- * Returns the value of the source before this value change event
- * occurred.
- *
- * @return the value previously held by the source of this event
- */
- public V getOldValue() {
- return oldValue;
- }
-
- /**
- * Returns the new value that triggered this value change event.
- *
- * @return the new value
- */
- public V getValue() {
- return value;
- }
-
- @Override
- public boolean isUserOriginated() {
- return userOriginated;
- }
-
- /**
- * Returns the component.
- *
- * @return the component, not null
- */
- public Component getComponent() {
- return component;
- }
-
- @SuppressWarnings("unchecked")
- @Override
- public HasValue<V> getSource() {
- return (HasValue<V>) super.getSource();
- }
- }
-
- /**
- * A listener for value change events.
- *
- * @param <V>
- * the value type
- *
- * @see ValueChangeEvent
- * @see Registration
- */
- @FunctionalInterface
- public interface ValueChangeListener<V> extends SerializableEventListener {
-
- /** For internal use only. Might be removed in the future. */
- @Deprecated
- public static final Method VALUE_CHANGE_METHOD = ReflectTools
- .findMethod(ValueChangeListener.class, "valueChange",
- ValueChangeEvent.class);
-
- /**
- * Invoked when this listener receives a value change event from an
- * event source to which it has been added.
- *
- * @param event
- * the received event, not null
- */
- public void valueChange(ValueChangeEvent<V> event);
- }
-
- /**
- * Sets the value of this object. If the new value is not equal to
- * {@code getValue()}, fires a value change event. May throw
- * {@code IllegalArgumentException} if the value is not acceptable.
- * <p>
- * <i>Implementation note:</i> the implementing class should document
- * whether null values are accepted or not.
- *
- * @param value
- * the new value
- * @throws IllegalArgumentException
- * if the value is invalid
- */
- public void setValue(V value);
-
- /**
- * Returns the current value of this object.
- * <p>
- * <i>Implementation note:</i> the implementing class should document
- * whether null values may be returned or not.
- *
- * @return the current value
- */
- public V getValue();
-
- /**
- * Adds a value change listener. The listener is called when the value of
- * this {@code HasValue} is changed either by the user or programmatically.
- *
- * @param listener
- * the value change listener, not null
- * @return a registration for the listener
- */
- public Registration addValueChangeListener(ValueChangeListener<V> listener);
-
- /**
- * Returns the value that represents an empty value.
- * <p>
- * By default {@link HasValue} is expected to support {@code null} as empty
- * values. Specific implementations might not support this.
- *
- * @return empty value
- * @see Binder#bind(HasValue, ValueProvider, com.vaadin.server.Setter)
- * Binder#bind(HasValue, ValueProvider, Setter)
- */
- public default V getEmptyValue() {
- return null;
- }
-
- /**
- * Returns the current value of this object, wrapped in an {@code Optional}.
- * <p>
- * The {@code Optional} will be empty if the value is {@code null} or
- * {@code isEmpty()} returns {@code true}.
- *
- * @return the current value, wrapped in an {@code Optional}
- */
- public default Optional<V> getOptionalValue() {
- return isEmpty() ? Optional.empty() : Optional.ofNullable(getValue());
- }
-
- /**
- * Returns whether this {@code HasValue} is considered to be empty.
- * <p>
- * By default this is an equality check between current value and empty
- * value.
- *
- * @return {@code true} if considered empty; {@code false} if not
- */
- public default boolean isEmpty() {
- return Objects.equals(getValue(), getEmptyValue());
- }
-
- /**
- * Sets the required indicator visible or not.
- * <p>
- * If set visible, it is visually indicated in the user interface.
- *
- * @param requiredIndicatorVisible
- * <code>true</code> to make the required indicator visible,
- * <code>false</code> if not
- */
- public void setRequiredIndicatorVisible(boolean requiredIndicatorVisible);
-
- /**
- * Checks whether the required indicator is visible.
- *
- * @return <code>true</code> if visible, <code>false</code> if not
- */
- public boolean isRequiredIndicatorVisible();
-
- /**
- * Sets the read-only mode of this {@code HasValue} to given mode. The user
- * can't change the value when in read-only mode.
- * <p>
- * A {@code HasValue} with a visual component in read-only mode typically
- * looks visually different to signal to the user that the value cannot be
- * edited.
- *
- * @param readOnly
- * a boolean value specifying whether the component is put
- * read-only mode or not
- */
- public void setReadOnly(boolean readOnly);
-
- /**
- * Returns whether this {@code HasValue} is in read-only mode or not.
- *
- * @return {@code false} if the user can modify the value, {@code true} if
- * not.
- */
- public boolean isReadOnly();
-
- /**
- * Resets the value to the empty one.
- * <p>
- * This is just a shorthand for resetting the value, see the methods
- * {@link #setValue(Object)} and {@link #getEmptyValue()}.
- *
- * @see #setValue(Object)
- * @see #getEmptyValue()
- */
- public default void clear() {
- setValue(getEmptyValue());
- }
-
- /**
- * Returns a validator that checks the internal state of the HasValue. This
- * should be overridden for components with internal value conversion or
- * validation, e.g. when the user is providing a string that has to be
- * parsed into a date. An invalid input from user will be exposed to a
- * {@link Binder} and can be seen as a validation failure.
- *
- * @since 8.1
- * @return internal state validator
- * @see Binder#validate()
- */
- public default Validator<V> getDefaultValidator() {
- return Validator.alwaysPass();
- }
- }
|