1 salcianu 1.1.2.1 // Relation.java, created Tue Jan 11 14:52:48 2000 by salcianu
2 cananian 1.1.2.3 // Copyright (C) 2000 Alexandru SALCIANU <salcianu@retezat.lcs.mit.edu>
3 salcianu 1.1.2.1 // Licensed under the terms of the GNU GPL; see COPYING for details.
4 salcianu 1.1.2.1 package harpoon.Util.DataStructs;
5 salcianu 1.1.2.1
6 salcianu 1.1.2.1 import java.util.Collection;
7 salcianu 1.1.2.1 import java.util.Set;
8 salcianu 1.3 import java.util.Map;
9 salcianu 1.1.2.1
10 salcianu 1.1.2.1 import harpoon.Util.PredicateWrapper;
11 salcianu 1.1.2.1
12 salcianu 1.1.2.1 /**
13 salcianu 1.1.2.1 * <code>Relation</code> is a mathematical relation, accepting one to many
14 salcianu 1.1.2.1 * and many to one mappings.
15 salcianu 1.1.2.1 *
16 cananian 1.6 * <p>It is similar to <code>net.cscott.jutil.MultiMap</code> but it is intended
17 salcianu 1.1.2.1 * to be simpler and better tailored for the implementation of the Pointer
18 salcianu 1.1.2.1 * Analysis algorithm.
19 salcianu 1.1.2.1 *
20 cananian 1.1.2.3 * @author Alexandru SALCIANU <salcianu@retezat.lcs.mit.edu>
21 cananian 1.6 * @version $Id: Relation.java,v 1.6 2004/02/08 01:56:57 cananian Exp $
22 salcianu 1.1.2.1 */
23 salcianu 1.1.2.1 public interface Relation {
24 salcianu 1.1.2.1
25 salcianu 1.1.2.1 /** Adds the pair <code><key, value></code> to the relation.
26 salcianu 1.1.2.1 Returns <code>true</code> if the new relation is bigger. */
27 salcianu 1.1.2.1 public boolean add(Object key, Object value);
28 salcianu 1.1.2.1
29 salcianu 1.1.2.1
30 salcianu 1.1.2.1 /** Adds a relation from <code>key</code> to each element of the set
31 salcianu 1.1.2.1 <code>values</code>. <code>values</code> should not contain
32 salcianu 1.1.2.1 duplicated elements.
33 salcianu 1.1.2.1 Returns <code>true</code> if the new relation is bigger. */
34 salcianu 1.1.2.1 public boolean addAll(Object key, Collection values);
35 salcianu 1.1.2.1
36 salcianu 1.1.2.1
37 salcianu 1.1.2.1 /** Removes the relation between <code>key</code> and
38 salcianu 1.1.2.1 <code>value</code>. */
39 salcianu 1.1.2.1 public void remove(Object key, Object value);
40 salcianu 1.1.2.1
41 salcianu 1.1.2.1
42 salcianu 1.1.2.1 /** Removes the relation between <code>key</code> and
43 salcianu 1.1.2.1 any element from <code>values</code>. */
44 salcianu 1.1.2.1 public void removeAll(Object key, Collection values);
45 salcianu 1.1.2.1
46 salcianu 1.1.2.1
47 salcianu 1.1.2.1 /** Removes all the relations attached to <code>key</code>. */
48 salcianu 1.1.2.1 public void removeKey(Object key);
49 salcianu 1.1.2.1
50 salcianu 1.1.2.1
51 salcianu 1.1.2.1 /** Removes all the keys that satisfy <code>predicate.check()</code>. */
52 salcianu 1.1.2.1 public void removeKeys(PredicateWrapper predicate);
53 salcianu 1.1.2.1
54 salcianu 1.1.2.1
55 salcianu 1.1.2.1 /** Removes all the values that satisfy <code>predicate.check()</code>. */
56 salcianu 1.1.2.1 public void removeValues(PredicateWrapper predicate);
57 salcianu 1.1.2.1
58 salcianu 1.1.2.1
59 salcianu 1.1.2.1 /** Removes all the relations involving at least one object that
60 salcianu 1.1.2.1 satisfy <code>predicate.check()</code>. */
61 salcianu 1.1.2.1 public void removeObjects(PredicateWrapper predicate);
62 salcianu 1.1.2.1
63 salcianu 1.1.2.1
64 salcianu 1.1.2.1 /** Checks the existence of the relation <code><key,value></code>. */
65 salcianu 1.1.2.1 public boolean contains(Object key, Object value);
66 salcianu 1.1.2.1
67 salcianu 1.1.2.1
68 salcianu 1.1.2.1 /** Checks the existence of the <code>key</code> key in this relation. */
69 salcianu 1.1.2.1 public boolean containsKey(Object key);
70 salcianu 1.1.2.1
71 salcianu 1.1.2.1
72 salcianu 1.1.2.1 /** Tests if this relation is empty or not. */
73 salcianu 1.1.2.1 public boolean isEmpty();
74 salcianu 1.1.2.1
75 salcianu 1.1.2.1
76 salcianu 1.1.2.1 /** Returns the image of <code>key</code> through this relation.
77 salcianu 1.1.2.1 The returned collection is guarranted not to contain duplicates.
78 salcianu 1.1.2.1 Can return <code>null</code> if no value is attached to key.
79 salcianu 1.1.2.1 If the result is non-null, additions and removals on the returned
80 salcianu 1.1.2.1 collection take effect on the relation. */
81 salcianu 1.1.2.1 public Set getValues(Object key);
82 salcianu 1.1.2.1
83 salcianu 1.1.2.1
84 salcianu 1.1.2.1 /** Returns all the keys appearing in this relation. The result is
85 salcianu 1.1.2.1 guaranted not to contain duplicates. */
86 salcianu 1.1.2.1 public Set keys();
87 salcianu 1.1.2.1
88 salcianu 1.1.2.1
89 salcianu 1.1.2.1 /** Returns all the values appearing in this relation. */
90 salcianu 1.1.2.1 public Set values();
91 salcianu 1.1.2.1
92 salcianu 1.1.2.1
93 salcianu 1.4 /** Combines <code>this</code> relation with relation
94 salcianu 1.4 <code>rel</code>. A <code>null</code> parameter is considered
95 salcianu 1.4 to be an empty relation.
96 salcianu 1.4
97 salcianu 1.4 @return <code>true</code> iff <code>this</code> relation has
98 salcianu 1.4 changed. */
99 salcianu 1.4 public boolean union(Relation rel);
100 salcianu 1.1.2.1
101 salcianu 1.1.2.1
102 salcianu 1.1.2.1 /** Checks the equality of two relations */
103 salcianu 1.1.2.1 public boolean equals(Object o);
104 salcianu 1.1.2.1
105 salcianu 1.1.2.1
106 salcianu 1.1.2.1 /** Returns the subrelation of this relation that contains
107 salcianu 1.1.2.1 only the keys that appear in <code>selected_keys</code>. */
108 salcianu 1.1.2.1 public Relation select(Collection selected_keys);
109 salcianu 1.1.2.1
110 salcianu 1.1.2.1
111 salcianu 1.1.2.1 /** Visits all the entries <code><key,value></code> of
112 salcianu 1.1.2.1 <code>this</code> relation and calls <code>visitor.visit</code>
113 salcianu 1.1.2.1 on each of them. */
114 salcianu 1.1.2.1 public void forAllEntries(RelationEntryVisitor visitor);
115 salcianu 1.1.2.1
116 salcianu 1.1.2.1
117 salcianu 1.1.2.1 /** Clones this relation. */
118 salcianu 1.1.2.1 public Object clone();
119 salcianu 1.1.2.2
120 salcianu 1.1.2.2
121 salcianu 1.1.2.2 /** Revert <code>this</code> relation and store the result into
122 salcianu 1.3 the relation <code>result</code>. <a,b> appears in the
123 salcianu 1.3 reverse relation iff <b,a> appears in <code>this</code>
124 salcianu 1.5 relation. Returns the new relation (ie,
125 salcianu 1.3 <code>result</code>). */
126 salcianu 1.3 public Relation revert(Relation result);
127 salcianu 1.3
128 salcianu 1.3 /** Convert <code>this</code> relation through the mapping
129 salcianu 1.3 <code>map</code>. The converted mapping contains all pairs
130 salcianu 1.3 <code>(a,b)</code> such that there exists <code>c,d</code>
131 salcianu 1.3 such that <code>(c,d)</code> appears in <code>this</code>
132 salcianu 1.3 mapping, and map maps c to a and d to b. If an object is not
133 salcianu 1.3 mapped to anything by <code>map</code>, it will be mapped to
134 salcianu 1.3 itself by default. The result is stored in
135 salcianu 1.3 <code>result</code>. Returns the converted mapping (ie,
136 salcianu 1.3 result). */
137 salcianu 1.3 public Relation convert(Map map, Relation result);
138 salcianu 1.1.2.1 }