third-party/net.sf.jung2/src/main/java/edu/uci/ics/jung/algorithms/matrix/MatrixElementOperations.java

   1 /*
   2 * Copyright (c) 2003, the JUNG Project and the Regents of the University
   3 * of California
   4 * All rights reserved.
   5 *
   6 * This software is open-source under the BSD license; see either
   7 * "license.txt" or
   8 * http://jung.sourceforge.net/license.txt for a description.
   9 */
  10 package edu.uci.ics.jung.algorithms.matrix;
  11
  12 import java.util.Map;
  13
  14
  15 /**
  16  * An interface for specifying the behavior of graph/matrix operations
  17  * for a particular element type.
  18  * <P>
  19  * Graph/matrix multiplication requires the definition of two operations:
  20  * <p>
  21  * <ol>
  22  * <li>
  23  * Calculating an aggregate property of paths of length 2 between two
  24  * vertices v1 and v2 (analogous to element multiplication in matrix
  25  * arithmetic); this is handled by computePathData().
  26  * </li>
  27  * <li>
  28  * Aggregating the properties of all such paths, and assigning the result to
  29  * a new edge in the output graph (analogous to element addition in matrix
  30  * arithmetic); this is handled by mergePaths().
  31  * </li>
  32  * </ol>
  33  * <p>
  34  * Together, computePathData() and mergePaths() specify how the equivalent of
  35  * the vector inner (dot) product is to function.
  36  * <p>
  37  * For instance, to implement the equivalent of standard matrix multiplication
  38  * on two graphs, computePathData() should return the products of the
  39  * weights of a two-edge path, and mergePaths() should add
  40  * the output of computePathData() to an existing edge (or possibly create such
  41  * an edge if none exists).
  42  *
  43  * @author Joshua O'Madadhain
  44  */
  45 public interface MatrixElementOperations<E>
  46 {
  47     /**
  48      * If either e or pathData is null, the effect of mergePaths() is
  49      * implementation-dependent.
  50      *
  51      * @param e         (possibly) existing edge in the output graph which
  52      *                                  represents a path in the input graph(s)
  53      *
  54      * @param pathData  data (which represents another path with the same source
  55      * and destination as e in the input graphs) which is to be merged into e
  56      */
  57     public void mergePaths(E e, Object pathData);
  58
  59     /**
  60      * If either e1 or e2 is null, the Object reference returned should be null.
  61      *
  62      * @param e1 first edge from 2-edge path in input graph(s)
  63      * @param e2 second edge from 2-edge path in input graph(s)
  64      * @return aggregation of data from the edges of the 2-edge path
  65      * (from source of e1 to destination of e2) comprised of (e1, e2)
  66      */
  67     public Number computePathData(E e1, E e2);
  68
  69     /**
  70      * Returns a map from edges to values.
  71      */
  72     public Map<E,Number> getEdgeData();
  73 }