org.apache.commons.collections4.BagUtils Maven / Gradle / Ivy
Show all versions of commons-collections4 Show documentation
/*
* 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<>());
/**
* Instantiation of BagUtils is not intended or required.
*/
private BagUtils() {}
//-----------------------------------------------------------------------
/**
* 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.
*
* It is imperative that the user manually synchronize on the returned bag
* when iterating over it:
*
*
* Bag bag = BagUtils.synchronizedBag(new HashBag());
* ...
* synchronized(bag) {
* Iterator i = bag.iterator(); // Must be in synchronized block
* while (i.hasNext())
* foo(i.next());
* }
* }
*
*
* Failure to follow this advice may result in non-deterministic behavior.
*
* @param 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 Bag synchronizedBag(final Bag bag) {
return SynchronizedBag.synchronizedBag(bag);
}
/**
* Returns an unmodifiable view of the given bag. Any modification attempts
* to the returned bag will raise an {@link UnsupportedOperationException}.
*
* @param 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 Bag unmodifiableBag(final Bag bag) {
return UnmodifiableBag.unmodifiableBag(bag);
}
/**
* Returns a predicated (validating) bag backed by the given bag.
*
* 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.
*
* @param 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 Bag predicatedBag(final Bag bag, final Predicate predicate) {
return PredicatedBag.predicatedBag(bag, predicate);
}
/**
* Returns a transformed bag backed by the given bag.
*
* 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.
*
* Existing entries in the specified bag will not be transformed.
* If you want that behaviour, see {@link TransformedBag#transformedBag(Bag, Transformer)}.
*
* @param 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 Bag transformingBag(final Bag bag, final Transformer transformer) {
return TransformedBag.transformingBag(bag, transformer);
}
/**
* Returns a bag that complies to the Collection contract, backed by the given bag.
*
* @param 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 Bag collectionBag(final Bag bag) {
return CollectionBag.collectionBag(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.
*
* It is imperative that the user manually synchronize on the returned bag
* when iterating over it:
*
*
* SortedBag bag = BagUtils.synchronizedSortedBag(new TreeBag());
* ...
* synchronized(bag) {
* Iterator i = bag.iterator(); // Must be in synchronized block
* while (i.hasNext())
* foo(i.next());
* }
* }
*
*
* Failure to follow this advice may result in non-deterministic behavior.
*
* @param 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 SortedBag synchronizedSortedBag(final SortedBag bag) {
return SynchronizedSortedBag.synchronizedSortedBag(bag);
}
/**
* Returns an unmodifiable view of the given sorted bag. Any modification
* attempts to the returned bag will raise an
* {@link UnsupportedOperationException}.
*
* @param 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 SortedBag unmodifiableSortedBag(final SortedBag bag) {
return UnmodifiableSortedBag.unmodifiableSortedBag(bag);
}
/**
* Returns a predicated (validating) sorted bag backed by the given sorted
* bag.
*
* 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.
*
* @param 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 SortedBag predicatedSortedBag(final SortedBag bag,
final Predicate predicate) {
return PredicatedSortedBag.predicatedSortedBag(bag, predicate);
}
/**
* Returns a transformed sorted bag backed by the given bag.
*
* 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.
*
* Existing entries in the specified bag will not be transformed.
* If you want that behaviour, see
* {@link TransformedSortedBag#transformedSortedBag(SortedBag, Transformer)}.
*
* @param 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 SortedBag transformingSortedBag(final SortedBag bag,
final Transformer transformer) {
return TransformedSortedBag.transformingSortedBag(bag, transformer);
}
/**
* Get an empty Bag.
*
* @param the element type
* @return an empty Bag
*/
@SuppressWarnings("unchecked") // OK, empty bag is compatible with any type
public static Bag emptyBag() {
return EMPTY_BAG;
}
/**
* Get an empty SortedBag.
*
* @param the element type
* @return an empty sorted Bag
*/
@SuppressWarnings("unchecked") // OK, empty bag is compatible with any type
public static SortedBag emptySortedBag() {
return (SortedBag) EMPTY_SORTED_BAG;
}
}