1 /**
2 * Redistribution and use of this software and associated documentation
3 * ("Software"), with or without modification, are permitted provided
4 * that the following conditions are met:
5 *
6 * 1. Redistributions of source code must retain copyright
7 * statements and notices. Redistributions must also contain a
8 * copy of this document.
9 *
10 * 2. Redistributions in binary form must reproduce the
11 * above copyright notice, this list of conditions and the
12 * following disclaimer in the documentation and/or other
13 * materials provided with the distribution.
14 *
15 * 3. The name "Exolab" must not be used to endorse or promote
16 * products derived from this Software without prior written
17 * permission of Intalio, Inc. For written permission,
18 * please contact info@exolab.org.
19 *
20 * 4. Products derived from this Software may not be called "Exolab"
21 * nor may "Exolab" appear in their names without prior written
22 * permission of Intalio, Inc. Exolab is a registered
23 * trademark of Intalio, Inc.
24 *
25 * 5. Due credit should be given to the Exolab Project
26 * (http://www.exolab.org/).
27 *
28 * THIS SOFTWARE IS PROVIDED BY INTALIO, INC. AND CONTRIBUTORS
29 * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
30 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
31 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
32 * INTALIO, INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
33 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
34 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
35 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
36 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
37 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
38 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
39 * OF THE POSSIBILITY OF SUCH DAMAGE.
40 *
41 * Copyright 1999 (C) Intalio, Inc. All Rights Reserved.
42 *
43 * $Id$
44 */
45
46 package org.exolab.castor.mapping;
47
48 import java.util.Enumeration;
49
50 /**
51 * Collection handler for adding/listing elements of a collection. A collection
52 * field will use this handler to add elements when it's value is set, and to
53 * enumerate then when it's value is retrieved. A collection handler is
54 * instantiated only once, must be thread safe and not use any synchronization.
55 *
56 * @author <a href="arkin@intalio.com">Assaf Arkin</a>
57 * @version $Revision$ $Date: 2003-03-03 00:05:44 -0700 (Mon, 03 Mar
58 * 2003) $
59 */
60 public interface CollectionHandler<T> {
61
62 /**
63 * Add an object to the collection. A collection may not allow the same
64 * object to be added more than once. The collection is provided as a
65 * parameter and is returned as the return value if the returned collection
66 * is a different object. That way the handler can create a new collection or
67 * change the collection as necessary (e.g. when resizing an array).
68 *
69 * @param collection
70 * The collection, null if no collection has been created yet
71 * @param object
72 * The object to add to the collection
73 * @return The collection with the new object if a different instance than
74 * the <tt>collection</tt> parameter, null otherwise
75 * @throws ClassCastException
76 * The collection handler does not support collections of this
77 * type
78 */
79 public Object add(Object collection, T object) throws ClassCastException;
80
81 /**
82 * Returns an enumeration of all the elements in the collection.
83 *
84 * @param collection
85 * The collection
86 * @return An enumeration of all the elements in the collection
87 * @throws ClassCastException
88 * The collection handler does not support collections of this
89 * type
90 */
91 public Enumeration<T> elements(Object collection) throws ClassCastException;
92
93 /**
94 * Returns the number of elements in the collection.
95 *
96 * @param collection
97 * The collection
98 * @return Number of elements in the collection
99 * @throws ClassCastException
100 * The collection handler does not support collections of this
101 * type
102 */
103 public int size(Object collection) throws ClassCastException;
104
105 /**
106 * Clears the collection of any objects. The collection is provided as a
107 * parameter and is returned as the return value if the returned collection
108 * is a different object. That way the handler can create a new collection or
109 * change the collection as necessary (e.g. when resizing an array).
110 *
111 * @param collection
112 * The collection, null if no collection has been created yet
113 * @return The empty collection if a different instance than the
114 * <tt>collection</tt> parameter, null otherwise
115 * @throws ClassCastException
116 * The collection handler does not support collections of this
117 * type
118 */
119 public Object clear(Object collection) throws ClassCastException;
120
121 }