/*
    * Licensed to the Apache Software Foundation (ASF) under one or more
    * contributor license agreements.  See the NOTICE file distributed with
    * this work for additional information regarding copyright ownership.
    * The ASF licenses this file to You 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
    *
    *      http://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.apache.commons.collections4;
  
  import org.apache.commons.collections4.bag.CollectionBag;
  import org.apache.commons.collections4.bag.HashBag;
  import org.apache.commons.collections4.bag.PredicatedBag;
  import org.apache.commons.collections4.bag.PredicatedSortedBag;
  import org.apache.commons.collections4.bag.SynchronizedBag;
  import org.apache.commons.collections4.bag.SynchronizedSortedBag;
  import org.apache.commons.collections4.bag.TransformedBag;
  import org.apache.commons.collections4.bag.TransformedSortedBag;
  import org.apache.commons.collections4.bag.TreeBag;
  import org.apache.commons.collections4.bag.UnmodifiableBag;
  import org.apache.commons.collections4.bag.UnmodifiableSortedBag;
  
  /**
   * Provides utility methods and decorators for {@link Bag} and {@link SortedBag} instances.
   *
   * @since 2.1
   */
  public class BagUtils {
  
      /**
       * An empty unmodifiable bag.
       */
      @SuppressWarnings("rawtypes") // OK, empty bag is compatible with any type
      public static final Bag EMPTY_BAG = UnmodifiableBag.unmodifiableBag(new HashBag<>());
  
      /**
       * An empty unmodifiable sorted bag.
       */
      @SuppressWarnings("rawtypes") // OK, empty bag is compatible with any type
      public static final Bag EMPTY_SORTED_BAG =
              UnmodifiableSortedBag.unmodifiableSortedBag(new TreeBag<>());
  
      /**
       * Returns a bag that complies to the Collection contract, backed by the given bag.
       *
       * @param <E> the element type
       * @param bag the bag to decorate, must not be null
       * @return a Bag that complies to the Collection contract
       * @throws NullPointerException if bag is null
       * @since 4.0
       */
      public static <E> Bag<E> collectionBag(final Bag<E> bag) {
          return CollectionBag.collectionBag(bag);
      }
  
      /**
       * Gets an empty {@code Bag}.
       *
       * @param <E> the element type
       * @return an empty Bag
       */
      @SuppressWarnings("unchecked") // OK, empty bag is compatible with any type
      public static <E> Bag<E> emptyBag() {
          return EMPTY_BAG;
      }
  
      /**
       * Gets an empty {@code SortedBag}.
       *
       * @param <E> the element type
       * @return an empty sorted Bag
       */
      @SuppressWarnings("unchecked") // OK, empty bag is compatible with any type
      public static <E> SortedBag<E> emptySortedBag() {
          return (SortedBag<E>) EMPTY_SORTED_BAG;
      }
  
      /**
       * Returns a predicated (validating) bag backed by the given bag.
       * <p>
       * Only objects that pass the test in the given predicate can be added to
       * the bag. Trying to add an invalid object results in an
       * IllegalArgumentException. It is important not to use the original bag
       * after invoking this method, as it is a backdoor for adding invalid
       * objects.
       * </p>
       *
       * @param <E> the element type
       * @param bag the bag to predicate, must not be null
       * @param predicate the predicate for the bag, must not be null
       * @return a predicated bag backed by the given bag
      * @throws NullPointerException if the Bag or Predicate is null
      */
     public static <E> Bag<E> predicatedBag(final Bag<E> bag, final Predicate<? super E> predicate) {
         return PredicatedBag.predicatedBag(bag, predicate);
     }
 
     /**
      * Returns a predicated (validating) sorted bag backed by the given sorted
      * bag.
      * <p>
      * Only objects that pass the test in the given predicate can be added to
      * the bag. Trying to add an invalid object results in an
      * IllegalArgumentException. It is important not to use the original bag
      * after invoking this method, as it is a backdoor for adding invalid
      * objects.
      * </p>
      *
      * @param <E> the element type
      * @param bag the sorted bag to predicate, must not be null
      * @param predicate the predicate for the bag, must not be null
      * @return a predicated bag backed by the given bag
      * @throws NullPointerException if the SortedBag or Predicate is null
      */
     public static <E> SortedBag<E> predicatedSortedBag(final SortedBag<E> bag,
             final Predicate<? super E> predicate) {
         return PredicatedSortedBag.predicatedSortedBag(bag, predicate);
     }
 
     /**
      * Returns a synchronized (thread-safe) bag backed by the given bag. In
      * order to guarantee serial access, it is critical that all access to the
      * backing bag is accomplished through the returned bag.
      * <p>
      * It is imperative that the user manually synchronize on the returned bag
      * when iterating over it:
      * </p>
      *
      * <pre>
      * Bag bag = BagUtils.synchronizedBag(new HashBag());
      * ...
      * synchronized(bag) {
      *     Iterator i = bag.iterator(); // Must be in synchronized block
      *     while (i.hasNext())
      *         foo(i.next());
      *     }
      * }
      * </pre>
      *
      * Failure to follow this advice may result in non-deterministic behavior.
      *
      * @param <E> the element type
      * @param bag the bag to synchronize, must not be null
      * @return a synchronized bag backed by that bag
      * @throws NullPointerException if the Bag is null
      */
     public static <E> Bag<E> synchronizedBag(final Bag<E> bag) {
         return SynchronizedBag.synchronizedBag(bag);
     }
 
     /**
      * Returns a synchronized (thread-safe) sorted bag backed by the given
      * sorted bag. In order to guarantee serial access, it is critical that all
      * access to the backing bag is accomplished through the returned bag.
      * <p>
      * It is imperative that the user manually synchronize on the returned bag
      * when iterating over it:
      * </p>
      *
      * <pre>
      * SortedBag bag = BagUtils.synchronizedSortedBag(new TreeBag());
      * ...
      * synchronized(bag) {
      *     Iterator i = bag.iterator(); // Must be in synchronized block
      *     while (i.hasNext())
      *         foo(i.next());
      *     }
      * }
      * </pre>
      *
      * Failure to follow this advice may result in non-deterministic behavior.
      *
      * @param <E> the element type
      * @param bag the bag to synchronize, must not be null
      * @return a synchronized bag backed by that bag
      * @throws NullPointerException if the SortedBag is null
      */
     public static <E> SortedBag<E> synchronizedSortedBag(final SortedBag<E> bag) {
         return SynchronizedSortedBag.synchronizedSortedBag(bag);
     }
 
     /**
      * Returns a transformed bag backed by the given bag.
      * <p>
      * Each object is passed through the transformer as it is added to the Bag.
      * It is important not to use the original bag after invoking this method,
      * as it is a backdoor for adding untransformed objects.
      * </p>
      * <p>
      * Existing entries in the specified bag will not be transformed.
      * If you want that behavior, see {@link TransformedBag#transformedBag(Bag, Transformer)}.
      * </p>
      *
      * @param <E> the element type
      * @param bag the bag to predicate, must not be null
      * @param transformer the transformer for the bag, must not be null
      * @return a transformed bag backed by the given bag
      * @throws NullPointerException if the Bag or Transformer is null
      */
     public static <E> Bag<E> transformingBag(final Bag<E> bag, final Transformer<? super E, ? extends E> transformer) {
         return TransformedBag.transformingBag(bag, transformer);
     }
 
     /**
      * Returns a transformed sorted bag backed by the given bag.
      * <p>
      * Each object is passed through the transformer as it is added to the Bag.
      * It is important not to use the original bag after invoking this method,
      * as it is a backdoor for adding untransformed objects.
      * </p>
      * <p>
      * Existing entries in the specified bag will not be transformed.
      * If you want that behavior, see
      * {@link TransformedSortedBag#transformedSortedBag(SortedBag, Transformer)}.
      * </p>
      *
      * @param <E> the element type
      * @param bag the bag to predicate, must not be null
      * @param transformer the transformer for the bag, must not be null
      * @return a transformed bag backed by the given bag
      * @throws NullPointerException if the Bag or Transformer is null
      */
     public static <E> SortedBag<E> transformingSortedBag(final SortedBag<E> bag,
                                                          final Transformer<? super E, ? extends E> transformer) {
         return TransformedSortedBag.transformingSortedBag(bag, transformer);
     }
 
     /**
      * Returns an unmodifiable view of the given bag. Any modification attempts
      * to the returned bag will raise an {@link UnsupportedOperationException}.
      *
      * @param <E> the element type
      * @param bag the bag whose unmodifiable view is to be returned, must not be null
      * @return an unmodifiable view of that bag
      * @throws NullPointerException if the Bag is null
      */
     public static <E> Bag<E> unmodifiableBag(final Bag<? extends E> bag) {
         return UnmodifiableBag.unmodifiableBag(bag);
     }
 
     /**
      * Returns an unmodifiable view of the given sorted bag. Any modification
      * attempts to the returned bag will raise an
      * {@link UnsupportedOperationException}.
      *
      * @param <E> the element type
      * @param bag the bag whose unmodifiable view is to be returned, must not be null
      * @return an unmodifiable view of that bag
      * @throws NullPointerException if the SortedBag is null
      */
     public static <E> SortedBag<E> unmodifiableSortedBag(final SortedBag<E> bag) {
         return UnmodifiableSortedBag.unmodifiableSortedBag(bag);
     }
 
     /**
      * Don't allow instances.
      */
     private BagUtils() {
         // empty
     }
 
 }