com.holonplatform.vaadin.components.ValueHolder Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of holon-vaadin Show documentation
Holon Vaadin integration
There is a newer version: 5.4.0
/*
 * Copyright 2000-2017 Holon TDCN.
 * 
 * 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.holonplatform.vaadin.components;

import java.io.Serializable;
import java.util.Objects;
import java.util.Optional;

import com.vaadin.shared.Registration;
import com.vaadin.shared.ui.ValueChangeMode;

/**
 * Represents an object which holds a value and provide methods to handle such value.
 * 
 * @param  Value type
 * 
 * @since 5.0.0
 */
public interface ValueHolder extends Serializable {

	/**
	 * Sets the value of this value holder.
	 * @param value the value to set
	 * @throws IllegalArgumentException if the value is not valid
	 */
	void setValue(V value);

	/**
	 * Gets the current value of this value holder.
	 * @return the current value
	 */
	V getValue();

	/**
	 * Get the current value of this value holder, if available (i.e. not null).
	 * @return Optional current value
	 */
	default Optional getValueIfPresent() {
		return Optional.ofNullable(getValue());
	}

	/**
	 * Returns the value that represents an empty value.
	 * @return the value that represents an empty value (null by default)
	 */
	default V getEmptyValue() {
		return null;
	}

	/**
	 * Returns whether this value holder is considered to be empty, according to its current value.
	 * 
	 * By default this is an equality check between current value and empty value.
	 * 
	 * @return true if considered empty, false if not
	 */
	default boolean isEmpty() {
		return Objects.equals(getValue(), getEmptyValue());
	}

	/**
	 * Clears this value holder.
	 * 
	 * By default, resets the value to the empty one.
	 * 
	 */
	default void clear() {
		setValue(getEmptyValue());
	}

	/**
	 * Gets the current value of this value holder as an {@link Optional}, which will be empty if the value holder is
	 * considered to be empty.
	 * @return the current optional value
	 */
	default Optional getOptionalValue() {
		return isEmpty() ? Optional.empty() : Optional.ofNullable(getValue());
	}

	// Value change handling

	/**
	 * Adds a value change listener, called when the value changes.
	 * @param listener the value change listener to add (not null)
	 * @return a registration for the listener, which provides the remove operation
	 */
	public Registration addValueChangeListener(ValueChangeListener listener);

	/**
	 * A listener for {@link ValueHolder} value change events.
	 * @param  Value type
	 */
	@FunctionalInterface
	public interface ValueChangeListener extends Serializable {

		/**
		 * Invoked when this listener receives a value change event from an {@link ValueHolder} source to which it has
		 * been added.
		 * @param event the value change event
		 */
		void valueChange(ValueChangeEvent event);

	}

	/**
	 * A {@link ValueChangeListener} event.
	 * @param  Value type
	 */
	public interface ValueChangeEvent extends Serializable {

		/**
		 * Returns whether this event was triggered by user interaction, on the client side, or programmatically, on the
		 * server side.
		 * @return true if this event originates from the client, false otherwise.
		 * @since 5.0.5
		 */
		boolean isUserOriginated();

		/**
		 * Get the source of this value change event.
		 * @return the {@link ValueHolder} source
		 */
		ValueHolder getSource();

		/**
		 * Returns the value of the source before this value change event occurred.
		 * @return the old value
		 */
		V getOldValue();

		/**
		 * Returns the new value that triggered this value change event.
		 * @return the new value
		 */
		V getValue();

	}

	/**
	 * Declares that the {@link ValueChangeMode} handling may be supported and provides methods to configure it.
	 */
	public interface MaySupportValueChangeMode {

		/**
		 * Gets whether the {@link ValueChangeMode} is supported for this component.
		 * @return true if the {@link ValueChangeMode} is supported, false otherwise
		 */
		boolean isValueChangeModeSupported();

		/**
		 * Sets the mode how value change events are triggered.
		 * 
		 * If {@link ValueChangeMode} is not supported, this method has no effect.
		 * 
		 * @param valueChangeMode the value change mode to set (not null)
		 * @see #isValueChangeModeSupported()
		 */
		void setValueChangeMode(ValueChangeMode valueChangeMode);

		/**
		 * Get the mode how value change events are triggered.
		 * 
		 * If {@link ValueChangeMode} is not supported, {@link ValueChangeMode#BLUR} is returned.
		 * 
		 * @return the value change mode
		 * @see #isValueChangeModeSupported()
		 */
		ValueChangeMode getValueChangeMode();

		/**
		 * Sets how often value change events are triggered when the {@link ValueChangeMode} is set to either
		 * {@link ValueChangeMode#LAZY} or {@link ValueChangeMode#TIMEOUT}.
		 * 
		 * If {@link ValueChangeMode} is not supported, this method has no effect.
		 * 
		 * @param valueChangeTimeout the timeout in milliseconds, (greater or equal to 0)
		 * @see #isValueChangeModeSupported()
		 */
		void setValueChangeTimeout(int valueChangeTimeout);

		/**
		 * Returns the currently set timeout, in milliseconds, for how often {@link ValueChangeEvent}s are triggered if
		 * the current {@link ValueChangeMode} is set to either {@link ValueChangeMode#LAZY} or
		 * {@link ValueChangeMode#TIMEOUT}.
		 * 
		 * If {@link ValueChangeMode} is not supported, this method always returns -1.
		 * 
		 * @return the timeout in milliseconds of how often value change events are triggered.
		 * @see #isValueChangeModeSupported()
		 */
		int getValueChangeTimeout();

	}

}