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 }