1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.collections4;
18
19 import java.util.LinkedList;
20 import java.util.Queue;
21
22 import org.apache.commons.collections4.queue.PredicatedQueue;
23 import org.apache.commons.collections4.queue.SynchronizedQueue;
24 import org.apache.commons.collections4.queue.TransformedQueue;
25 import org.apache.commons.collections4.queue.UnmodifiableQueue;
26
27 /**
28 * Provides utility methods and decorators for {@link Queue} instances.
29 *
30 * @since 4.0
31 */
32 public class QueueUtils {
33
34 /**
35 * An empty unmodifiable queue.
36 */
37 @SuppressWarnings("rawtypes") // OK, empty queue is compatible with any type
38 public static final Queue EMPTY_QUEUE = UnmodifiableQueue.unmodifiableQueue(new LinkedList<>());
39
40 /**
41 * Gets an empty {@code Queue}.
42 *
43 * @param <E> the type of the elements in the queue
44 * @return an empty {@link Queue}
45 */
46 @SuppressWarnings("unchecked") // OK, empty queue is compatible with any type
47 public static <E> Queue<E> emptyQueue() {
48 return EMPTY_QUEUE;
49 }
50
51 /**
52 * Returns a predicated (validating) queue backed by the given queue.
53 * <p>
54 * Only objects that pass the test in the given predicate can be added to the queue.
55 * Trying to add an invalid object results in an IllegalArgumentException.
56 * It is important not to use the original queue after invoking this method,
57 * as it is a backdoor for adding invalid objects.
58 * </p>
59 *
60 * @param <E> the type of the elements in the queue
61 * @param queue the queue to predicate, must not be null
62 * @param predicate the predicate used to evaluate new elements, must not be null
63 * @return a predicated queue
64 * @throws NullPointerException if the queue or predicate is null
65 */
66 public static <E> Queue<E> predicatedQueue(final Queue<E> queue, final Predicate<? super E> predicate) {
67 return PredicatedQueue.predicatedQueue(queue, predicate);
68 }
69
70 /**
71 * Returns a synchronized (thread-safe) queue backed by the given queue.
72 * In order to guarantee serial access, it is critical that all access to the
73 * backing queue is accomplished through the returned queue.
74 * <p>
75 * It is imperative that the user manually synchronize on the returned queue
76 * when iterating over it:
77 * </p>
78 * <pre>
79 * Queue queue = QueueUtils.synchronizedQueue(new CircularFifoQueue());
80 * ...
81 * synchronized(queue) {
82 * Iterator i = queue.iterator(); // Must be in synchronized block
83 * while (i.hasNext())
84 * foo(i.next());
85 * }
86 * }
87 * </pre>
88 * <p>
89 * Failure to follow this advice may result in non-deterministic behavior.
90 * </p>
91 *
92 * @param <E> the element type
93 * @param queue the queue to synchronize, must not be null
94 * @return a synchronized queue backed by that queue
95 * @throws NullPointerException if the queue is null
96 * @since 4.2
97 */
98 public static <E> Queue<E> synchronizedQueue(final Queue<E> queue) {
99 return SynchronizedQueue.synchronizedQueue(queue);
100 }
101
102 /**
103 * Returns a transformed queue backed by the given queue.
104 * <p>
105 * Each object is passed through the transformer as it is added to the
106 * Queue. It is important not to use the original queue after invoking this
107 * method, as it is a backdoor for adding untransformed objects.
108 * </p>
109 * <p>
110 * Existing entries in the specified queue will not be transformed.
111 * If you want that behavior, see {@link TransformedQueue#transformedQueue}.
112 * </p>
113 *
114 * @param <E> the type of the elements in the queue
115 * @param queue the queue to predicate, must not be null
116 * @param transformer the transformer for the queue, must not be null
117 * @return a transformed queue backed by the given queue
118 * @throws NullPointerException if the queue or transformer is null
119 */
120 public static <E> Queue<E> transformingQueue(final Queue<E> queue, final Transformer<? super E, ? extends E> transformer) {
121 return TransformedQueue.transformingQueue(queue, transformer);
122 }
123
124 /**
125 * Returns an unmodifiable queue backed by the given queue.
126 *
127 * @param <E> the type of the elements in the queue
128 * @param queue the queue to make unmodifiable, must not be null
129 * @return an unmodifiable queue backed by that queue
130 * @throws NullPointerException if the queue is null
131 */
132 public static <E> Queue<E> unmodifiableQueue(final Queue<? extends E> queue) {
133 return UnmodifiableQueue.unmodifiableQueue(queue);
134 }
135
136 /**
137 * Don't allow instances.
138 */
139 private QueueUtils() {
140 // empty
141 }
142 }