1 /*
2 * Copyright 2001-2010 Stephen Colebourne
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.joda.primitives;
17
18 /**
19 * Interface that is shared between Collection and Map implementations.
20 *
21 * @author Stephen Colebourne
22 * @version $Id: PrimitiveCollectable.java,v 1.4 2006/03/27 22:42:11 scolebourne Exp $
23 * @since 1.0
24 */
25 public interface PrimitiveCollectable<E> {
26
27 // Mandatory operations
28 //-----------------------------------------------------------------------
29 /**
30 * Gets the number of elements in this collection/map.
31 * <p>
32 * If this collection contains more than <code>Integer.MAX_VALUE</code>
33 * elements, <code>Integer.MAX_VALUE</code> is returned.
34 *
35 * @return the size of the collection/map
36 */
37 int size();
38
39 /**
40 * Checks whether the collection/map currently has no elements.
41 *
42 * @return <code>true</code> if has a size of zero
43 */
44 boolean isEmpty();
45
46 /**
47 * Optimizes the implementation after initialization.
48 * <p>
49 * The exact nature of the optimization is undefined and is implementation specific.
50 * A standard optimization is to trim the internal storage array to the size.
51 * An implementation may choose to do nothing, but it should NOT throw an
52 * UnsupportedOperationException.
53 */
54 void optimize();
55
56 /**
57 * Checks whether the collection/map can currently be modified.
58 *
59 * @return <code>true</code> if the collection/map allows some kind of modification
60 */
61 boolean isModifiable();
62
63 /**
64 * Clones the object, returning an independent copy.
65 * <p>
66 * If the implementation is immutable, the object may be returned unaltered.
67 *
68 * @return a newly cloned object, not null
69 */
70 Object clone();
71
72 // Optional operations
73 //-----------------------------------------------------------------------
74 /**
75 * Clears the collection/map of all elements (optional operation).
76 * <p>
77 * The collection/map will have a zero size after this method completes.
78 * This method is optional, throwing an UnsupportedOperationException if the
79 * collection/map cannot be cleared.
80 *
81 * @throws UnsupportedOperationException if method not supported by this collection
82 */
83 void clear();
84
85 }