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

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

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

import com.holonplatform.vaadin7.Registration;

/**
 * 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();

	/**
	 * 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());
	}

	/**
	 * 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 {

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

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

	}

}