001: /*
002: * GeoTools - OpenSource mapping toolkit
003: * http://geotools.org
004: * (C) 2003-2007, Geotools Project Managment Committee (PMC)
005: * (C) 2001, Institut de Recherche pour le Développement
006: *
007: * This library is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU Lesser General Public
009: * License as published by the Free Software Foundation; either
010: * version 2.1 of the License, or (at your option) any later version.
011: *
012: * This library is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: */
017: package org.geotools.util;
018:
019: import java.util.Set;
020:
021: /**
022: * A canonical set of objects, used to optimize memory use.
023: * The operation of this set is similar in spirit to the {@link String#intern} method.
024: * The following example shows a convenient way to use {@code CanonicalSet} as an
025: * internal pool of immutable objects.
026: *
027: * <blockquote><pre>
028: * public Foo create(String definition) {
029: * Foo created = new Foo(definition);
030: * return (Foo) canonicalSet.unique(created);
031: * }
032: * </pre></blockquote>
033: *
034: * The {@code CanonicalSet} has a {@link #get} method that is not part of the {@link Set}
035: * interface. This {@code get} method retrieves an entry from this set that is equals to
036: * the supplied object. The {@link #unique} method combines a {@code get} followed by a
037: * {@code put} operation if the specified object was not in the set.
038: * <p>
039: * The set of objects is held by weak references as explained in {@link WeakHashSet}.
040: * The {@code CanonicalSet} class is thread-safe.
041: *
042: * @since 2.4
043: * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/library/metadata/src/main/java/org/geotools/util/CanonicalSet.java $
044: * @version $Id: CanonicalSet.java 25949 2007-06-20 16:07:37Z desruisseaux $
045: * @author Martin Desruisseaux
046: * @author Jody Garnett
047: */
048: public class CanonicalSet extends WeakHashSet {
049: /**
050: * Constructs a {@code CanonicalSet}.
051: */
052: public CanonicalSet() {
053: }
054:
055: /**
056: * Returns an object equals to the specified object, if present. If
057: * this set doesn't contains any object equals to {@code object},
058: * then this method returns {@code null}.
059: *
060: * @see #unique(Object)
061: */
062: public synchronized Object get(final Object object) {
063: return intern(object, GET);
064: }
065:
066: /**
067: * Returns an object equals to {@code object} if such an object already exist in this
068: * {@code CanonicalSet}. Otherwise, adds {@code object} to this {@code CanonicalSet}.
069: * This method is equivalents to the following code:
070: *
071: * <blockquote><pre>
072: * if (object != null) {
073: * Object current = get(object);
074: * if (current != null) {
075: * return current;
076: * } else {
077: * add(object);
078: * }
079: * }
080: * return object;
081: * </pre></blockquote>
082: */
083: public synchronized Object unique(final Object object) {
084: return intern(object, INTERN);
085: }
086:
087: /**
088: * Iteratively call {@link #unique(Object)} for an array of objects.
089: * This method is equivalents to the following code:
090: *
091: * <blockquote><pre>
092: * for (int i=0; i<objects.length; i++) {
093: * objects[i] = unique(objects[i]);
094: * }
095: * </pre></blockquote>
096: */
097: public synchronized void uniques(final Object[] objects) {
098: for (int i = 0; i < objects.length; i++) {
099: objects[i] = intern(objects[i], INTERN);
100: }
101: }
102: }
|