001: /*
002: * Primitive Collections for Java.
003: * Copyright (C) 2002, 2003 Søren Bak
004: *
005: * This library is free software; you can redistribute it and/or
006: * modify it under the terms of the GNU Lesser General Public
007: * License as published by the Free Software Foundation; either
008: * version 2.1 of the License, or (at your option) any later version.
009: *
010: * This library is distributed in the hope that it will be useful,
011: * but WITHOUT ANY WARRANTY; without even the implied warranty of
012: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013: * Lesser General Public License for more details.
014: *
015: * You should have received a copy of the GNU Lesser General Public
016: * License along with this library; if not, write to the Free Software
017: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
018: */
019: package bak.pcj.adapter;
020:
021: import bak.pcj.Adapter;
022: import bak.pcj.AbstractCharCollection;
023: import bak.pcj.CharIterator;
024: import bak.pcj.util.Exceptions;
025: import java.util.Collection;
026: import java.util.AbstractCollection;
027: import java.util.Iterator;
028:
029: /**
030: * This class represents adaptions of Java Collections Framework
031: * collections to primitive collections of char values.
032: * The adapter is implemented as a wrapper around the collection.
033: * Thus, changes to the underlying collection are reflected by this
034: * collection and vice versa.
035: *
036: * <p>
037: * Adapters from JCF collections to primitive collections will
038: * fail if the JCF collection contains <tt>null</tt> values or
039: * values of the wrong class. However, adapters are not fast
040: * failing in the case that the underlying collection should
041: * contain illegal values. To implement fast failure would require
042: * every operation to check every element of the underlying
043: * collection before doing anything. Instead validation methods
044: * are provided. They can be called using the assertion facility
045: * in the client code:
046: * <pre>
047: * CollectionToCharCollectionAdapter s;
048: * ...
049: * <b>assert</b> s.validate();
050: * </pre>
051: * or by letting the adapter throw an exception on illegal values:
052: * <pre>
053: * CollectionToCharCollectionAdapter s;
054: * ...
055: * s.evalidate(); // Throws an exception on illegal values
056: * </pre>
057: * Either way, validation must be invoked directly by the client
058: * code.
059: *
060: * @author Søren Bak
061: * @version 1.2 20-08-2003 23:18
062: * @since 1.0
063: */
064: public class CollectionToCharCollectionAdapter extends
065: AbstractCharCollection {
066:
067: /** The underlying collection. */
068: protected Collection collection;
069:
070: /**
071: * Creates a new adaption of a collection to a collection of char
072: * values.
073: *
074: * @param collection
075: * the underlying collection. This collection must
076: * consist of values of class
077: * {@link Character Character}. Otherwise a
078: * {@link ClassCastException ClassCastException}
079: * will be thrown by some methods.
080: *
081: * @throws NullPointerException
082: * if <tt>collection</tt> is <tt>null</tt>.
083: */
084: public CollectionToCharCollectionAdapter(Collection collection) {
085: this (collection, false);
086: }
087:
088: /**
089: * Creates a new adaption of a collection to a collection of char
090: * values. The collection to adapt is optionally validated.
091: *
092: * @param collection
093: * the underlying collection. This collection must
094: * consist of values of class
095: * {@link Character Character}. Otherwise a
096: * {@link ClassCastException ClassCastException}
097: * will be thrown by some methods.
098: *
099: * @param validate
100: * indicates whether <tt>collection</tt> should
101: * be checked for illegal values.
102: *
103: * @throws NullPointerException
104: * if <tt>collection</tt> is <tt>null</tt>.
105: *
106: * @throws IllegalStateException
107: * if <tt>validate</tt> is <tt>true</tt> and
108: * <tt>collection</tt> contains a <tt>null</tt> value
109: * or a value that is not of class
110: * {@link Character Character}.
111: */
112: public CollectionToCharCollectionAdapter(Collection collection,
113: boolean validate) {
114: super ();
115: if (collection == null)
116: Exceptions.nullArgument("collection");
117: this .collection = collection;
118: if (validate)
119: evalidate();
120: }
121:
122: public boolean add(char v) {
123: return collection.add(new Character(v));
124: }
125:
126: public void clear() {
127: collection.clear();
128: }
129:
130: public boolean contains(char v) {
131: return collection.contains(new Character(v));
132: }
133:
134: public int hashCode() {
135: return collection.hashCode();
136: }
137:
138: public CharIterator iterator() {
139: return new IteratorToCharIteratorAdapter(collection.iterator());
140: }
141:
142: public boolean remove(char v) {
143: return collection.remove(new Character(v));
144: }
145:
146: public int size() {
147: return collection.size();
148: }
149:
150: /**
151: * Indicates whether the underlying collection is valid for
152: * this adapter. For the underlying collection to be valid, it
153: * can only contain {@link Character Character} values and no <tt>null</tt>
154: * values.
155: *
156: * @return <tt>true</tt> if the underlying collection is
157: * valid; returns <tt>false</tt> otherwise.
158: */
159: public boolean validate() {
160: return Adapter.isCharAdaptable(collection);
161: }
162:
163: /**
164: * Validates the collection underlying this adapter and throws
165: * an exception if it is invalid. For the underlying collection
166: * to be valid, it can only contain {@link Character Character}
167: * values and no <tt>null</tt> values.
168: *
169: * @throws IllegalStateException
170: * if the underlying collection is invalid.
171: */
172: public void evalidate() {
173: if (!validate())
174: Exceptions.cannotAdapt("collection");
175: }
176:
177: }
|