001: /*
002: * JacORB - a free Java ORB
003: *
004: * Copyright (C) 1999-2004 Gerald Brose
005: *
006: * This library is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU Library General Public
008: * License as published by the Free Software Foundation; either
009: * version 2 of the License, or (at your option) any later version.
010: *
011: * This library is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * Library General Public License for more details.
015: *
016: * You should have received a copy of the GNU Library General Public
017: * License along with this library; if not, write to the Free
018: * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
019: *
020: */
021:
022: package org.jacorb.notification.util;
023:
024: /**
025: * An Object that maps String Keys to Values.<br>
026: * A WildcardMap cannot contain duplicate keys.
027: * Each Key has exactly one Entry associated. A Key can contain the Wildcard Character '*' which
028: * matches zero or more characters. The WildcardMap supports two semantics of accessing
029: * the entries. The first way is to ignore the special meaning of the Wildcard character and to just
030: * return the entries as they were inserted. <br>
031: * This way you could put some entries in a WildcardMap and fetch them again using the Operation
032: * {@link #getNoExpansion(Object) getNoExpansion()}:
033: *
034: * <pre>
035: * WildcardMap wc = new WildcardMap();
036: * wc.put("abc", new Integer(1));
037: * wc.put("a*", new Integer(2));
038: * wc.getNoExpansion("abc") => 1
039: * wc.getNoExpansion("a*") => 2
040: * wc.getNoExpansion("xyz") => null
041: * </pre>
042: *
043: * This behaviour is similiar to a {@link java.util.Map Map}.<br>
044: * The other way using the WildcardMap is to use the Operation {@link #getWithExpansion(Object)
045: * getWithExpansion()}. This Operations matches the requested Key to all contained Keys. If the Key
046: * of an Entry contains the Wildcard Character '*' it is matched as expected by the semantic of '*'.
047: * The Operations returns an array of all matching entries:
048: *
049: * <pre>
050: * wc.getWithExpansion("abc") => [1,2]
051: * wc.getWithExpansion("a") => [2]
052: * wc.getWithExpansion("abcd") => [2]
053: * wc.getWithExpansion("xyz") => []
054: * </pre>
055: *
056: * @author Alphonse Bendt
057: * @version $Id: WildcardMap.java,v 1.16 2005/08/21 13:38:40 alphonse.bendt Exp $
058: */
059: public interface WildcardMap {
060: /**
061: * clear this map
062: */
063: void clear();
064:
065: /**
066: * remove the specified key from this Map.
067: */
068: Object remove(Object key);
069:
070: /**
071: * The operation <code>put</code> associates the specified value with the specified key in
072: * this map. The String representation of the Key {@link java.lang.Object#toString() toString()}
073: * is used. If the map previously contained a mapping for this key, the old value is replaced by
074: * the specified value.
075: *
076: * @param key
077: * key with which String representation the specified value is to be associated.
078: * @param value
079: * value to be associated with the specified key.
080: * @return previous value associated with specified key, or null if there was no mapping for
081: * key.
082: */
083: Object put(Object key, Object value);
084:
085: /**
086: * Returns the value to which this map maps the specified key. Returns null if the map contains
087: * no mapping for this key.
088: *
089: * @param key
090: * key whose associated value is to be returned
091: * @return the value to which this map maps the specified key, or null if the map contains no
092: * mapping for this key.
093: */
094: Object getNoExpansion(Object key);
095:
096: /**
097: * Returns the value to which this map maps the specified key. Additionaly return all Values
098: * which keys contain a Wildcard and match the requested key. Returns null if the map contains
099: * no mapping for this key.
100: *
101: * @param key
102: * key whose associated value is to be returned
103: * @return an Array of all Matching entries or null if no matching entry could be found.
104: */
105: Object[] getWithExpansion(Object key);
106: }
|