001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.collections4;
018
019import java.util.LinkedList;
020import java.util.Queue;
021
022import org.apache.commons.collections4.queue.PredicatedQueue;
023import org.apache.commons.collections4.queue.TransformedQueue;
024import org.apache.commons.collections4.queue.UnmodifiableQueue;
025
026/**
027 * Provides utility methods and decorators for {@link Queue} instances.
028 *
029 * @since 4.0
030 * @version $Id: QueueUtils.html 972421 2015-11-14 20:00:04Z tn $
031 */
032public class QueueUtils {
033
034    /**
035     * An empty unmodifiable queue.
036     */
037    @SuppressWarnings("rawtypes") // OK, empty queue is compatible with any type
038    public static final Queue EMPTY_QUEUE = UnmodifiableQueue.unmodifiableQueue(new LinkedList<Object>());
039
040    /**
041     * <code>QueueUtils</code> should not normally be instantiated.
042     */
043    private QueueUtils() {}
044
045    //-----------------------------------------------------------------------
046
047    /**
048     * Returns an unmodifiable queue backed by the given queue.
049     *
050     * @param <E> the type of the elements in the queue
051     * @param queue  the queue to make unmodifiable, must not be null
052     * @return an unmodifiable queue backed by that queue
053     * @throws IllegalArgumentException  if the Queue is null
054     */
055    public static <E> Queue<E> unmodifiableQueue(final Queue<? extends E> queue) {
056        return UnmodifiableQueue.unmodifiableQueue(queue);
057    }
058
059    /**
060     * Returns a predicated (validating) queue backed by the given queue.
061     * <p>
062     * Only objects that pass the test in the given predicate can be added to the queue.
063     * Trying to add an invalid object results in an IllegalArgumentException.
064     * It is important not to use the original queue after invoking this method,
065     * as it is a backdoor for adding invalid objects.
066     *
067     * @param <E> the type of the elements in the queue
068     * @param queue  the queue to predicate, must not be null
069     * @param predicate  the predicate used to evaluate new elements, must not be null
070     * @return a predicated queue
071     * @throws IllegalArgumentException  if the Queue or Predicate is null
072     */
073    public static <E> Queue<E> predicatedQueue(final Queue<E> queue, final Predicate<? super E> predicate) {
074        return PredicatedQueue.predicatedQueue(queue, predicate);
075    }
076
077    /**
078     * Returns a transformed queue backed by the given queue.
079     * <p>
080     * Each object is passed through the transformer as it is added to the
081     * Queue. It is important not to use the original queue after invoking this
082     * method, as it is a backdoor for adding untransformed objects.
083     * <p>
084     * Existing entries in the specified queue will not be transformed.
085     * If you want that behaviour, see {@link TransformedQueue#transformedQueue}.
086     *
087     * @param <E> the type of the elements in the queue
088     * @param queue  the queue to predicate, must not be null
089     * @param transformer  the transformer for the queue, must not be null
090     * @return a transformed queue backed by the given queue
091     * @throws IllegalArgumentException  if the Queue or Transformer is null
092     */
093    public static <E> Queue<E> transformingQueue(final Queue<E> queue,
094                                                 final Transformer<? super E, ? extends E> transformer) {
095        return TransformedQueue.transformingQueue(queue, transformer);
096    }
097
098    /**
099     * Get an empty <code>Queue</code>.
100     *
101     * @param <E> the type of the elements in the queue
102     * @return an empty {@link Queue}
103     */
104    @SuppressWarnings("unchecked") // OK, empty queue is compatible with any type
105    public static <E> Queue<E> emptyQueue() {
106        return (Queue<E>) EMPTY_QUEUE;
107    }
108}