org.springframework.data.util.Optionals Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of spring-data-commons Show documentation
There is a newer version: 3.4.0
/*
 * Copyright 2016-2024 the original author or authors.
 *
 * 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
 *
 *      https://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 org.springframework.data.util;

import java.util.Arrays;
import java.util.Iterator;
import java.util.Optional;
import java.util.function.BiConsumer;
import java.util.function.BiFunction;
import java.util.function.Consumer;
import java.util.function.Function;
import java.util.function.Supplier;
import java.util.stream.Stream;

import org.springframework.util.Assert;

/**
 * Utility methods to work with {@link Optional}s.
 *
 * @author Oliver Gierke
 * @author Christoph Strobl
 */
public interface Optionals {

	/**
	 * Returns whether any of the given {@link Optional}s is present.
	 *
	 * @param optionals must not be {@literal null}.
	 * @return
	 */
	public static boolean isAnyPresent(Optional... optionals) {

		Assert.notNull(optionals, "Optionals must not be null");

		return Arrays.stream(optionals).anyMatch(Optional::isPresent);
	}

	/**
	 * Turns the given {@link Optional} into a one-element {@link Stream} or an empty one if not present.
	 *
	 * @param optionals must not be {@literal null}.
	 * @return
	 */
	@SafeVarargs
	public static  Stream toStream(Optional... optionals) {

		Assert.notNull(optionals, "Optional must not be null");

		return Arrays.asList(optionals).stream().flatMap(it -> it.map(Stream::of).orElseGet(Stream::empty));
	}

	/**
	 * Applies the given function to the elements of the source and returns the first non-empty result.
	 *
	 * @param source must not be {@literal null}.
	 * @param function must not be {@literal null}.
	 * @return
	 */
	public static  Optional firstNonEmpty(Iterable source, Function> function) {

		Assert.notNull(source, "Source must not be null");
		Assert.notNull(function, "Function must not be null");

		return Streamable.of(source).stream()//
				.map(function::apply)//
				.filter(Optional::isPresent)//
				.findFirst().orElseGet(Optional::empty);
	}

	/**
	 * Applies the given function to the elements of the source and returns the first non-empty result.
	 *
	 * @param source must not be {@literal null}.
	 * @param function must not be {@literal null}.
	 * @return
	 */
	public static  T firstNonEmpty(Iterable source, Function function, T defaultValue) {

		Assert.notNull(source, "Source must not be null");
		Assert.notNull(function, "Function must not be null");

		return Streamable.of(source).stream()//
				.map(function::apply)//
				.filter(it -> !it.equals(defaultValue))//
				.findFirst().orElse(defaultValue);
	}

	/**
	 * Invokes the given {@link Supplier}s for {@link Optional} results one by one and returns the first non-empty one.
	 *
	 * @param suppliers must not be {@literal null}.
	 * @return
	 */
	@SafeVarargs
	public static  Optional firstNonEmpty(Supplier>... suppliers) {

		Assert.notNull(suppliers, "Suppliers must not be null");

		return firstNonEmpty(Streamable.of(suppliers));
	}

	/**
	 * Invokes the given {@link Supplier}s for {@link Optional} results one by one and returns the first non-empty one.
	 *
	 * @param suppliers must not be {@literal null}.
	 * @return
	 */
	public static  Optional firstNonEmpty(Iterable>> suppliers) {

		Assert.notNull(suppliers, "Suppliers must not be null");

		return Streamable.of(suppliers).stream()//
				.map(Supplier::get)//
				.filter(Optional::isPresent)//
				.findFirst().orElse(Optional.empty());
	}

	/**
	 * Returns the next element of the given {@link Iterator} or {@link Optional#empty()} in case there is no next
	 * element.
	 *
	 * @param iterator must not be {@literal null}.
	 * @return
	 */
	public static  Optional next(Iterator iterator) {

		Assert.notNull(iterator, "Iterator must not be null");

		return iterator.hasNext() ? Optional.of(iterator.next()) : Optional.empty();
	}

	/**
	 * Returns a {@link Pair} if both {@link Optional} instances have values or {@link Optional#empty()} if one or both
	 * are missing.
	 *
	 * @param left
	 * @param right
	 * @return
	 */
	public static  Optional> withBoth(Optional left, Optional right) {
		return left.flatMap(l -> right.map(r -> Pair.of(l, r)));
	}

	/**
	 * Invokes the given {@link BiConsumer} if all given {@link Optional} are present.
	 *
	 * @param left must not be {@literal null}.
	 * @param right must not be {@literal null}.
	 * @param consumer must not be {@literal null}.
	 */
	public static  void ifAllPresent(Optional left, Optional right, BiConsumer consumer) {

		Assert.notNull(left, "Optional must not be null");
		Assert.notNull(right, "Optional must not be null");
		Assert.notNull(consumer, "Consumer must not be null");

		mapIfAllPresent(left, right, (l, r) -> {
			consumer.accept(l, r);
			return null;
		});
	}

	/**
	 * Maps the values contained in the given {@link Optional} if both of them are present.
	 *
	 * @param left must not be {@literal null}.
	 * @param right must not be {@literal null}.
	 * @param function must not be {@literal null}.
	 * @return
	 */
	public static  Optional mapIfAllPresent(Optional left, Optional right,
			BiFunction function) {

		Assert.notNull(left, "Optional must not be null");
		Assert.notNull(right, "Optional must not be null");
		Assert.notNull(function, "BiFunction must not be null");

		return left.flatMap(l -> right.map(r -> function.apply(l, r)));
	}

	/**
	 * Invokes the given {@link Consumer} if the {@link Optional} is present or the {@link Runnable} if not.
	 *
	 * @param optional must not be {@literal null}.
	 * @param consumer must not be {@literal null}.
	 * @param runnable must not be {@literal null}.
	 */
	public static  void ifPresentOrElse(Optional optional, Consumer consumer, Runnable runnable) {

		Assert.notNull(optional, "Optional must not be null");
		Assert.notNull(consumer, "Consumer must not be null");
		Assert.notNull(runnable, "Runnable must not be null");

		if (optional.isPresent()) {
			optional.ifPresent(consumer);
		} else {
			runnable.run();
		}
	}
}