com.torchmind.observable.Observable Maven / Gradle / Ivy
Show all versions of observables Show documentation
/*
* Copyright 2017 Johannes Donath
* and other copyright owners as documented in the project's IP log.
*
* 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.torchmind.observable;
import java.util.function.Consumer;
import javax.annotation.Nonnull;
/**
* Represents a property of a complex (or possibly wrapped) type which is capable of inheriting its
* value from another property as well as notifying third parties of property changes.
*
* @author Johannes Donath
*/
public interface Observable extends ReadOnlyObservable {
/**
* Converts this observable into a standard Java consumer.
*/
@Nonnull
default Consumer asConsumer() {
return this::set;
}
/**
* Updates the internal value of this observable using the passed value.
*
* @throws IllegalArgumentException when the backing invalidation listener deems the passed value
* to be invalid.
* @throws IllegalStateException when a unidirectional binding prevents the caller from changing
* this observable value.
*/
void set(V value);
/**
* Evaluates whether this observable is in a valid state.
*
* This method returns true as long as no prior call to {@link #set(Object)}} has changed the
* validity and will return back to true when all heirs and listeners have been notified of this
* change.
*/
boolean isValid();
/**
* Binds the value of this observable to the value of the supplied observable (e.g. it makes
* this observable a heir to the value of the provided observable) through a unidirectional
* binding.
*
* When this method is called, the observable will automatically be invalidated to take over
* its new value. Access to {@link #set(Object)} will be prevented until {@link #unbind()} is
* called.
*
* @throws IllegalStateException when this method is currently part of another binding.
*/
void bindTo(@Nonnull ReadOnlyObservable observable);
/**
* Enables sharing of the very same value on this and the supplied observable.
*
* When this method is called, the observable will automatically be invalidated to take over
* its new value (as dictated by the newly bound property).
*
* @throws IllegalStateException when this method is currently part of another unidirectional
* binding.
*/
void bindBidirectionallyTo(@Nonnull Observable observable);
/**
* Evaluates whether this observable is bound to another observable either uni- or
* bidirectionally.
*/
boolean isBound();
/**
* Evaluates whether this observable is bound to the supplied observable (e.g. it is a heir of the
* supplied observable).
*/
boolean isBoundTo(@Nonnull ReadOnlyObservable observable);
/**
* Evaluates whether this observable is bound to the supplied observable bidirectionally.
*/
boolean isBoundBidirectionallyTo(@Nonnull Observable observable);
/**
* Evaluates whether this observable is bound to one or more observables using a bidirectional (
* e.g. shared value) binding.
*/
boolean isBoundBidirectionally();
/**
* Removes a unidirectional binding from this observable.
*
* When this method is called, the last known value is retained for this observable and access
* to {@link #set(Object)} will be restored.
*
* @throws IllegalStateException when no unidirectional binding is present.
*/
void unbind();
/**
* Unbinds this binding from all bidirectional and unidirectional bindings.
*
* When this method is called, the last known value is retained for this observable and access
* to {@link #set(Object)} will be restored (if previously unavailable).
*
* @throws IllegalStateException when no bindings are present.
*/
void unbindAll();
/**
* Unbinds a specific bidirectional relation from this observable.
*
* When this method is called, the last known value is retained for this observable even when
* the last bidirectional binding is removed.
*
* @throws IllegalStateException when no matching binding is present.
*/
void unbindBidirectional(@Nonnull Observable observable);
}