WildcardMap


1   /*
2    *        JacORB - a free Java ORB
3    *
4    *   Copyright (C) 1999-2004 Gerald Brose
5    *
6    *   This library is free software; you can redistribute it and/or
7    *   modify it under the terms of the GNU Library General Public
8    *   License as published by the Free Software Foundation; either
9    *   version 2 of the License, or (at your option) any later version.
10   *
11   *   This library is distributed in the hope that it will be useful,
12   *   but WITHOUT ANY WARRANTY; without even the implied warranty of
13   *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14   *   Library General Public License for more details.
15   *
16   *   You should have received a copy of the GNU Library General Public
17   *   License along with this library; if not, write to the Free
18   *   Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
19   *
20   */
21  
22  package org.jacorb.notification.util;
23  
24  /**
25   * An Object that maps String Keys to Values.<br> 
26   * A WildcardMap cannot contain duplicate keys.
27   * Each Key has exactly one Entry associated. A Key can contain the Wildcard Character '*' which
28   * matches zero or more characters. The WildcardMap supports two semantics of accessing
29   * the entries. The first way is to ignore the special meaning of the Wildcard character and to just
30   * return the entries as they were inserted. <br>
31   * This way you could put some entries in a WildcardMap and fetch them again using the Operation
32   * {@link #getNoExpansion(Object) getNoExpansion()}:
33   * 
34   * <pre> 
35   *   WildcardMap wc = new WildcardMap();
36   *   wc.put(&quot;abc&quot;, new Integer(1));
37   *   wc.put(&quot;a*&quot;, new Integer(2));
38   *   wc.getNoExpansion(&quot;abc&quot;) =&gt; 1
39   *   wc.getNoExpansion(&quot;a*&quot;) =&gt; 2
40   *   wc.getNoExpansion(&quot;xyz&quot;) =&gt; null
41   * </pre>
42   * 
43   * This behaviour is similiar to a {@link java.util.Map Map}.<br>
44   * The other way using the WildcardMap is to use the Operation {@link#getWithExpansion(Object)
45   * getWithExpansion()}. This Operations matches the requested Key to all contained Keys. If the Key
46   * of an Entry contains the Wildcard Character '*' it is matched as expected by the semantic of '*'.
47   * The Operations returns an array of all matching entries:
48   * 
49   * <pre>
50   *   wc.getWithExpansion(&quot;abc&quot;) =&gt; [1,2]
51   *   wc.getWithExpansion(&quot;a&quot;) =&gt; [2]
52   *   wc.getWithExpansion(&quot;abcd&quot;) =&gt; [2]
53   *   wc.getWithExpansion(&quot;xyz&quot;) =&gt; []
54   * </pre>
55   * 
56   * @author Alphonse Bendt
57   * @version $Id: WildcardMap.java,v 1.15 2005/02/14 00:13:05 alphonse.bendt Exp $
58   */
59  public interface WildcardMap
60  {
61      /**
62       * clear this map
63       */
64      void clear();
65  
66      /**
67       * remove the specified key from this Map.
68       */
69      Object   remove(Object   key);
70  
71      /**
72       * The operation <code>put</code> associates the specified value with the specified key in
73       * this map. The String representation of the Key {@link java.lang.Object#toString() toString()}
74       * is used. If the map previously contained a mapping for this key, the old value is replaced by
75       * the specified value.
76       * 
77       * @param key
78       *            key with which String representation the specified value is to be associated.
79       * @param value
80       *            value to be associated with the specified key.
81       * @return previous value associated with specified key, or null if there was no mapping for
82       *         key.
83       */
84      Object   put(Object   key, Object   value);
85  
86      /**
87       * Returns the value to which this map maps the specified key. Returns null if the map contains
88       * no mapping for this key.
89       * 
90       * @param key
91       *            key whose associated value is to be returned
92       * @return the value to which this map maps the specified key, or null if the map contains no
93       *         mapping for this key.
94       */
95      Object   getNoExpansion(Object   key);
96  
97      /**
98       * Returns the value to which this map maps the specified key. Additionaly return all Values
99       * which keys contain a Wildcard and match the requested key. Returns null if the map contains
100      * no mapping for this key.
101      * 
102      * @param key
103      *            key whose associated value is to be returned
104      * @return an Array of all Matching entries or null if no matching entry could be found.
105      */
106     Object  [] getWithExpansion(Object   key);
107 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags