1 /*
2 * Copyright 2015-2020 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.springframework.data.util;
17
18 import static java.util.stream.Collectors.*;
19
20 import java.util.Collections;
21 import java.util.Iterator;
22 import java.util.List;
23 import java.util.Set;
24 import java.util.Spliterator;
25 import java.util.Spliterators;
26 import java.util.Spliterators.AbstractSpliterator;
27 import java.util.function.BiFunction;
28 import java.util.function.Consumer;
29 import java.util.function.Function;
30 import java.util.stream.Collector;
31 import java.util.stream.Stream;
32 import java.util.stream.StreamSupport;
33
34 import org.springframework.lang.Nullable;
35 import org.springframework.util.Assert;
36 import org.springframework.util.MultiValueMap;
37
38 /**
39 * Spring Data specific Java {@link Stream} utility methods and classes.
40 *
41 * @author Thomas Darimont
42 * @author Oliver Gierke
43 * @since 1.10
44 */
45 public interface StreamUtils {
46
47 /**
48 * Returns a {@link Stream} backed by the given {@link Iterator}
49 *
50 * @param iterator must not be {@literal null}.
51 * @return
52 */
53 public static <T> Stream<T> createStreamFromIterator(Iterator<T> iterator) {
54
55 Spliterator<T> spliterator = Spliterators.spliteratorUnknownSize(iterator, Spliterator.NONNULL);
56 return StreamSupport.stream(spliterator, false);
57 }
58
59 /**
60 * Returns a {@link Stream} backed by the given {@link CloseableIterator} and forwarding calls to
61 * {@link Stream#close()} to the iterator.
62 *
63 * @param iterator must not be {@literal null}.
64 * @return
65 * @since 2.0
66 */
67 public static <T> Stream<T> createStreamFromIterator(CloseableIterator<T> iterator) {
68
69 Assert.notNull(iterator, "Iterator must not be null!");
70
71 return createStreamFromIterator((Iterator<T>) iterator).onClose(() -> iterator.close());
72 }
73
74 /**
75 * Returns a {@link Collector} to create an unmodifiable {@link List}.
76 *
77 * @return will never be {@literal null}.
78 */
79 public static <T> Collector<T, ?, List<T>> toUnmodifiableList() {
80 return collectingAndThen(toList(), Collections::unmodifiableList);
81 }
82
83 /**
84 * Returns a {@link Collector} to create an unmodifiable {@link Set}.
85 *
86 * @return will never be {@literal null}.
87 */
88 public static <T> Collector<T, ?, Set<T>> toUnmodifiableSet() {
89 return collectingAndThen(toSet(), Collections::unmodifiableSet);
90 }
91
92 /**
93 * Returns a {@link Collector} to create a {@link MultiValueMap}.
94 *
95 * @param keyFunction {@link Function} to create a key from an element of the {@link java.util.stream.Stream}
96 * @param valueFunction {@link Function} to create a value from an element of the {@link java.util.stream.Stream}
97 */
98 public static <T, K, V> Collector<T, MultiValueMap<K, V>, MultiValueMap<K, V>> toMultiMap(Function<T, K> keyFunction,
99 Function<T, V> valueFunction) {
100 return MultiValueMapCollector.of(keyFunction, valueFunction);
101 }
102
103 /**
104 * Creates a new {@link Stream} for the given value returning an empty {@link Stream} if the value is {@literal null}.
105 *
106 * @param source can be {@literal null}.
107 * @return a new {@link Stream} for the given value returning an empty {@link Stream} if the value is {@literal null}.
108 * @since 2.0.6
109 */
110 public static <T> Stream<T> fromNullable(@Nullable T source) {
111 return source == null ? Stream.empty() : Stream.of(source);
112 }
113
114 /**
115 * Zips the given {@link Stream}s using the given {@link BiFunction}. The resulting {@link Stream} will have the
116 * length of the shorter of the two, abbreviating the zipping when the shorter of the two {@link Stream}s is
117 * exhausted.
118 *
119 * @param left must not be {@literal null}.
120 * @param right must not be {@literal null}.
121 * @param combiner must not be {@literal null}.
122 * @return
123 * @since 2.1
124 */
125 public static <L, R, T> Stream<T> zip(Stream<L> left, Stream<R> right, BiFunction<L, R, T> combiner) {
126
127 Assert.notNull(left, "Left stream must not be null!");
128 Assert.notNull(right, "Right must not be null!");
129 Assert.notNull(combiner, "Combiner must not be null!");
130
131 Spliterator<L> lefts = left.spliterator();
132 Spliterator<R> rights = right.spliterator();
133
134 long size = Long.min(lefts.estimateSize(), rights.estimateSize());
135 int characteristics = lefts.characteristics() & rights.characteristics();
136 boolean parallel = left.isParallel() || right.isParallel();
137
138 return StreamSupport.stream(new AbstractSpliterator<T>(size, characteristics) {
139
140 @Override
141 @SuppressWarnings("null")
142 public boolean tryAdvance(Consumer<? super T> action) {
143 return lefts.tryAdvance(left -> rights.tryAdvance(right -> action.accept(combiner.apply(left, right))));
144 }
145
146 }, parallel);
147 }
148 }
149