/*
* Copyright 2015-2020 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.domain;
import lombok.AccessLevel;
import lombok.NonNull;
import lombok.RequiredArgsConstructor;
import lombok.Value;
import java.util.Optional;
import org.springframework.util.Assert;
Simple value object to work with ranges and boundaries.
Author: Oliver Gierke, Mark Paluch Since: 1.10
/**
* Simple value object to work with ranges and boundaries.
*
* @author Oliver Gierke
* @author Mark Paluch
* @since 1.10
*/
@Value
@RequiredArgsConstructor(access = AccessLevel.PRIVATE)
public class Range<T extends Comparable<T>> {
private final static Range<?> UNBOUNDED = Range.of(Bound.unbounded(), Bound.UNBOUNDED);
The lower bound of the range.
/**
* The lower bound of the range.
*/
private final @NonNull Bound<T> lowerBound;
The upper bound of the range.
/**
* The upper bound of the range.
*/
private final @NonNull Bound<T> upperBound;
Returns an unbounded Range
. Returns: Since: 2.0
/**
* Returns an unbounded {@link Range}.
*
* @return
* @since 2.0
*/
@SuppressWarnings("unchecked")
public static <T extends Comparable<T>> Range<T> unbounded() {
return (Range<T>) UNBOUNDED;
}
Creates a new Range
with inclusive bounds for both values. Params: - from – must not be null.
- to – must not be null.
Type parameters: - <T> –
Returns: Since: 2.2
/**
* Creates a new {@link Range} with inclusive bounds for both values.
*
* @param <T>
* @param from must not be {@literal null}.
* @param to must not be {@literal null}.
* @return
* @since 2.2
*/
public static <T extends Comparable<T>> Range<T> closed(T from, T to) {
return new Range<>(Bound.inclusive(from), Bound.inclusive(to));
}
Creates a new Range
with inclusive bounds for both values. Params: - from – must not be null.
- to – must not be null.
Type parameters: - <T> –
Returns: Since: 2.2
/**
* Creates a new {@link Range} with inclusive bounds for both values.
*
* @param <T>
* @param from must not be {@literal null}.
* @param to must not be {@literal null}.
* @return
* @since 2.2
*/
public static <T extends Comparable<T>> Range<T> open(T from, T to) {
return new Range<>(Bound.exclusive(from), Bound.exclusive(to));
}
Creates a new left-open Range
, i.e. left exclusive, right inclusive. Params: - from – must not be null.
- to – must not be null.
Type parameters: - <T> –
Returns: Since: 2.2
/**
* Creates a new left-open {@link Range}, i.e. left exclusive, right inclusive.
*
* @param <T>
* @param from must not be {@literal null}.
* @param to must not be {@literal null}.
* @return
* @since 2.2
*/
public static <T extends Comparable<T>> Range<T> leftOpen(T from, T to) {
return new Range<>(Bound.exclusive(from), Bound.inclusive(to));
}
Creates a new right-open Range
, i.e. left inclusive, right exclusive. Params: - from – must not be null.
- to – must not be null.
Type parameters: - <T> –
Returns: Since: 2.2
/**
* Creates a new right-open {@link Range}, i.e. left inclusive, right exclusive.
*
* @param <T>
* @param from must not be {@literal null}.
* @param to must not be {@literal null}.
* @return
* @since 2.2
*/
public static <T extends Comparable<T>> Range<T> rightOpen(T from, T to) {
return new Range<>(Bound.inclusive(from), Bound.exclusive(to));
}
Creates a left-unbounded Range
(the left bound set to Bound.unbounded()
) with the given right bound. Params: - to – the right
Bound
, must not be null.
Type parameters: - <T> –
Returns: Since: 2.2
/**
* Creates a left-unbounded {@link Range} (the left bound set to {@link Bound#unbounded()}) with the given right
* bound.
*
* @param <T>
* @param to the right {@link Bound}, must not be {@literal null}.
* @return
* @since 2.2
*/
public static <T extends Comparable<T>> Range<T> leftUnbounded(Bound<T> to) {
return new Range<>(Bound.unbounded(), to);
}
Creates a right-unbounded Range
(the right bound set to Bound.unbounded()
) with the given left bound. Params: - from – the left
Bound
, must not be null.
Type parameters: - <T> –
Returns: Since: 2.2
/**
* Creates a right-unbounded {@link Range} (the right bound set to {@link Bound#unbounded()}) with the given left
* bound.
*
* @param <T>
* @param from the left {@link Bound}, must not be {@literal null}.
* @return
* @since 2.2
*/
public static <T extends Comparable<T>> Range<T> rightUnbounded(Bound<T> from) {
return new Range<>(from, Bound.unbounded());
}
Create a RangeBuilder
given the lower Bound
. Params: - lower – must not be null.
Returns: Since: 2.0
/**
* Create a {@link RangeBuilder} given the lower {@link Bound}.
*
* @param lower must not be {@literal null}.
* @return
* @since 2.0
*/
public static <T extends Comparable<T>> RangeBuilder<T> from(Bound<T> lower) {
Assert.notNull(lower, "Lower bound must not be null!");
return new RangeBuilder<>(lower);
}
Creates a new Range
with the given lower and upper bound. Prefer from(Bound<Z#0-T#31>)
for a more builder style API. Params: - lowerBound – must not be null.
- upperBound – must not be null.
See Also: Since: 2.0
/**
* Creates a new {@link Range} with the given lower and upper bound. Prefer {@link #from(Bound)} for a more builder
* style API.
*
* @param lowerBound must not be {@literal null}.
* @param upperBound must not be {@literal null}.
* @since 2.0
* @see #from(Bound)
*/
public static <T extends Comparable<T>> Range<T> of(Bound<T> lowerBound, Bound<T> upperBound) {
return new Range<>(lowerBound, upperBound);
}
Creates a new Range with the given value as sole member.
Params: - value – must not be null.
Type parameters: - <T> –
Returns:
/**
* Creates a new Range with the given value as sole member.
*
* @param <T>
* @param value must not be {@literal null}.
* @return
*/
public static <T extends Comparable<T>> Range<T> just(T value) {
return Range.closed(value, value);
}
Returns whether the Range
contains the given value. Params: - value – must not be null.
Returns:
/**
* Returns whether the {@link Range} contains the given value.
*
* @param value must not be {@literal null}.
* @return
*/
public boolean contains(T value) {
Assert.notNull(value, "Reference value must not be null!");
boolean greaterThanLowerBound = lowerBound.getValue() //
.map(it -> lowerBound.isInclusive() ? it.compareTo(value) <= 0 : it.compareTo(value) < 0) //
.orElse(true);
boolean lessThanUpperBound = upperBound.getValue() //
.map(it -> upperBound.isInclusive() ? it.compareTo(value) >= 0 : it.compareTo(value) > 0) //
.orElse(true);
return greaterThanLowerBound && lessThanUpperBound;
}
/*
* (non-Javadoc)
* @see java.lang.Object#toString()
*/
@Override
public String toString() {
return String.format("%s-%s", lowerBound.toPrefixString(), upperBound.toSuffixString());
}
Value object representing a boundary. A boundary can either be unbounded
, including its value
or its value
. Author: Mark Paluch Since: 2.0 @soundtrack Mohamed Ragab - Excelsior Sessions (March 2017)
/**
* Value object representing a boundary. A boundary can either be {@link #unbounded() unbounded},
* {@link #inclusive(Comparable) including its value} or {@link #exclusive(Comparable) its value}.
*
* @author Mark Paluch
* @since 2.0
* @soundtrack Mohamed Ragab - Excelsior Sessions (March 2017)
*/
@Value
@RequiredArgsConstructor(access = AccessLevel.PRIVATE)
public static class Bound<T extends Comparable<T>> {
@SuppressWarnings({ "rawtypes", "unchecked" }) //
private static final Bound<?> UNBOUNDED = new Bound(Optional.empty(), true);
private final Optional<T> value;
private final boolean inclusive;
Creates an unbounded Bound
. /**
* Creates an unbounded {@link Bound}.
*/
@SuppressWarnings("unchecked")
public static <T extends Comparable<T>> Bound<T> unbounded() {
return (Bound<T>) UNBOUNDED;
}
Returns whether this boundary is bounded.
Returns:
/**
* Returns whether this boundary is bounded.
*
* @return
*/
public boolean isBounded() {
return value.isPresent();
}
Creates a boundary including value
. Params: - value – must not be null.
Returns:
/**
* Creates a boundary including {@code value}.
*
* @param value must not be {@literal null}.
* @return
*/
public static <T extends Comparable<T>> Bound<T> inclusive(T value) {
Assert.notNull(value, "Value must not be null!");
return new Bound<>(Optional.of(value), true);
}
Creates a boundary including value
. Params: - value – must not be null.
Returns:
/**
* Creates a boundary including {@code value}.
*
* @param value must not be {@literal null}.
* @return
*/
public static Bound<Integer> inclusive(int value) {
return inclusive((Integer) value);
}
Creates a boundary including value
. Params: - value – must not be null.
Returns:
/**
* Creates a boundary including {@code value}.
*
* @param value must not be {@literal null}.
* @return
*/
public static Bound<Long> inclusive(long value) {
return inclusive((Long) value);
}
Creates a boundary including value
. Params: - value – must not be null.
Returns:
/**
* Creates a boundary including {@code value}.
*
* @param value must not be {@literal null}.
* @return
*/
public static Bound<Float> inclusive(float value) {
return inclusive((Float) value);
}
Creates a boundary including value
. Params: - value – must not be null.
Returns:
/**
* Creates a boundary including {@code value}.
*
* @param value must not be {@literal null}.
* @return
*/
public static Bound<Double> inclusive(double value) {
return inclusive((Double) value);
}
Creates a boundary excluding value
. Params: - value – must not be null.
Returns:
/**
* Creates a boundary excluding {@code value}.
*
* @param value must not be {@literal null}.
* @return
*/
public static <T extends Comparable<T>> Bound<T> exclusive(T value) {
Assert.notNull(value, "Value must not be null!");
return new Bound<>(Optional.of(value), false);
}
Creates a boundary excluding value
. Params: - value – must not be null.
Returns:
/**
* Creates a boundary excluding {@code value}.
*
* @param value must not be {@literal null}.
* @return
*/
public static Bound<Integer> exclusive(int value) {
return exclusive((Integer) value);
}
Creates a boundary excluding value
. Params: - value – must not be null.
Returns:
/**
* Creates a boundary excluding {@code value}.
*
* @param value must not be {@literal null}.
* @return
*/
public static Bound<Long> exclusive(long value) {
return exclusive((Long) value);
}
Creates a boundary excluding value
. Params: - value – must not be null.
Returns:
/**
* Creates a boundary excluding {@code value}.
*
* @param value must not be {@literal null}.
* @return
*/
public static Bound<Float> exclusive(float value) {
return exclusive((Float) value);
}
Creates a boundary excluding value
. Params: - value – must not be null.
Returns:
/**
* Creates a boundary excluding {@code value}.
*
* @param value must not be {@literal null}.
* @return
*/
public static Bound<Double> exclusive(double value) {
return exclusive((Double) value);
}
String toPrefixString() {
return getValue() //
.map(Object::toString) //
.map(it -> isInclusive() ? "[".concat(it) : "(".concat(it)) //
.orElse("unbounded");
}
String toSuffixString() {
return getValue() //
.map(Object::toString) //
.map(it -> isInclusive() ? it.concat("]") : it.concat(")")) //
.orElse("unbounded");
}
/*
* (non-Javadoc)
* @see java.lang.Object#toString()
*/
@Override
public String toString() {
return value.map(Object::toString).orElse("unbounded");
}
}
Builder for Range
allowing to specify the upper boundary. Author: Mark Paluch Since: 2.0 @soundtrack Aly and Fila - Future Sound Of Egypt 493
/**
* Builder for {@link Range} allowing to specify the upper boundary.
*
* @author Mark Paluch
* @since 2.0
* @soundtrack Aly and Fila - Future Sound Of Egypt 493
*/
public static class RangeBuilder<T extends Comparable<T>> {
private final Bound<T> lower;
RangeBuilder(Bound<T> lower) {
this.lower = lower;
}
Params: - upper – must not be null.
Returns:
/**
* Create a {@link Range} given the upper {@link Bound}.
*
* @param upper must not be {@literal null}.
* @return
*/
public Range<T> to(Bound<T> upper) {
Assert.notNull(upper, "Upper bound must not be null!");
return new Range<>(lower, upper);
}
}
}