001/*
002 *  Copyright 2001-2010 Stephen Colebourne
003 *
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package org.joda.primitives;
017
018/**
019 * Interface that is shared between Collection and Map implementations.
020 * 
021 * @author Stephen Colebourne
022 * @version $Id: PrimitiveCollectable.java,v 1.4 2006/03/27 22:42:11 scolebourne Exp $
023 * @since 1.0
024 */
025public interface PrimitiveCollectable<E> {
026
027    // Mandatory operations
028    //-----------------------------------------------------------------------
029    /**
030     * Gets the number of elements in this collection/map.
031     * <p>
032     * If this collection contains more than <code>Integer.MAX_VALUE</code>
033     * elements, <code>Integer.MAX_VALUE</code> is returned.
034     * 
035     * @return the size of the collection/map
036     */
037    int size();
038
039    /**
040     * Checks whether the collection/map currently has no elements.
041     *
042     * @return <code>true</code> if has a size of zero
043     */
044    boolean isEmpty();
045
046    /**
047     * Optimizes the implementation after initialization.
048     * <p>
049     * The exact nature of the optimization is undefined and is implementation specific.
050     * A standard optimization is to trim the internal storage array to the size.
051     * An implementation may choose to do nothing, but it should NOT throw an
052     * UnsupportedOperationException.
053     */
054    void optimize();
055
056    /**
057     * Checks whether the collection/map can currently be modified.
058     *
059     * @return <code>true</code> if the collection/map allows some kind of modification
060     */
061    boolean isModifiable();
062
063    /**
064     * Clones the object, returning an independent copy.
065     * <p>
066     * If the implementation is immutable, the object may be returned unaltered.
067     * 
068     * @return a newly cloned object, not null
069     */
070    Object clone();
071
072    // Optional operations
073    //-----------------------------------------------------------------------
074    /**
075     * Clears the collection/map of all elements (optional operation).
076     * <p>
077     * The collection/map will have a zero size after this method completes.
078     * This method is optional, throwing an UnsupportedOperationException if the
079     * collection/map cannot be cleared.
080     *
081     * @throws UnsupportedOperationException if method not supported by this collection
082     */
083    void clear();
084
085}