View Javadoc

1   package org.lcsim.event;
2   
3   import java.util.Map;
4   import java.util.Set;
5   
6   /**
7    * A relational table allows associations between objects. It is designed to 
8    * be persisted to/from LCIO files as a collection of LCRelations, but to add
9    * considerably more functionality than a raw collection of relations.
10   * 
11   * It can be set to mode 1-1, 1-n, n-1, n-m. When adding new relations they will
12   * silently replace existing relationships based on the mode.
13   *
14   * It allows weights to be associated with each relation, unless it is set to 
15   * weighting mode UNWEIGHTED.
16   *
17   * @author tonyj
18   */
19  public interface RelationalTable<F, T>
20  {
21     public enum Weighting { WEIGHTED, UNWEIGHTED };
22     public enum Mode 
23     {
24        ONE_TO_ONE, ONE_TO_MANY, MANY_TO_ONE, MANY_TO_MANY;
25     }
26     /**
27      * Add a new unweighted relation.
28      * @returns <code>true</code> if this relationship replaces an existing relationship, <code>false</code> otherwise.
29      */
30     boolean add(F from, T to);
31  
32     /**
33      * Add a new weighted relation.
34      * @returns <code>true</code> if this relationship replaces an existing relationship, <code>false</code> otherwise.
35      * @throws IllegalArgumentExeption if table in unweighted and weight is not 1
36      */
37     boolean add(F from, T to, double weight);
38  
39     /**
40      * Returns the list of <code>to</code> objects corresponding to a given <code>from</code> object.
41      * The natural ordering of the elements will be in decreasing weight.
42      */
43     Set<T> allFrom(F from);
44  
45     /**
46      * Returns the map of <code>to</code> objects in the table, with their weights.
47      * The natural ordering of the keys will be by decreasing weight.
48      */
49     Map<T, Double> allFromWithWeights(F from);
50  
51     /**
52      * Returns the list of <code>from</code> objects corresponding to a given <code>to</code> object.
53      * If the table is weighted, the returned list will be returned with the highest
54      * weighting first.
55      */
56     Set<F> allTo(T to);
57     /**
58      * Returns the map of <code>from</code> objects in the table, with their weights.
59      * The natural ordering of the keys will be by decreasing weight.
60      */
61     Map<F, Double> allToWithWeights(T to);
62  
63     /**
64      * Gets the (unique) <code>from</code> object corresponding to object <code>to</code>.
65      * @throws IllegalArgumentException if more than one to object corresponds to <code>to</code>
66      */
67     F from(T to);
68  
69     Mode getMode();
70  
71     Weighting getWeighting();
72  
73     /**
74      * Remove any relationship between <code>from</code> and <code>to</code>
75      * @return <code>true</code> if the table contained the relationship
76      */
77     boolean remove(F from, T to);
78  
79     /**
80      * Returns the total number of relationships in this table.
81      */
82     int size();
83  
84     /**
85      * Gets the (unique) <code>to</code> object corresponding to object <code>from</code>.
86      * @throws IllegalArgumentException if more than one to object corresponds to <code>from</code>
87      */
88     T to(F from);
89  
90     /**
91      * Returns the weight of the relationship between <code>from</code> and <code>to</code>
92      * Returns 0.0 if there is no relationship, and 1.0 if there is an unweighted relationship.
93      */
94     double weightFromTo(F from, T to);
95     
96  }