bcds.phison.io
Class GraphReader<V extends GraphIONode,E>

java.lang.Object
  bcds.phison.io.GraphReader<V,E>

Direct Known Subclasses:

GraphMLReader, SgfGraphReader

public abstract class GraphReader<V extends GraphIONode,E>
extends java.lang.Object

Base class for all topology file readers; it defines both an interface and useful methods and data for derived classes. For a SimGraph to be readable, its nodes must implement GraphIONode. The actual reading of the data stream is performed through DataFileReader, thus, if the stream is compressed (GZIP), it is decompressed transparently on the fly.

The following code shows the typical steps required to read a graph, independently of the format (the example assumes a .sgf file):

    Map<Link, Integer> cap;                                   // 1
    Map<Link, Integer> cost;                                  // 2
    Map<SimplePair<Node, Node>, Float> traffic;               // 3

    g = new SimpleGraph<Node, Link>(Node.class, Link.class));    // 5
    rd = new SgfGraphReader<Node, Link>("mygraph.sgf", g);    // 6

    cap = Utils.newHashMap();                                 // 8
    cost = Utils.newHashMap();                                // 9
    trf = Utils.newHashMap();                                 // 10

    rd.markEdgeAttr("capacity", cap, Integer.class)           // 12
      .markEdgeAttr("cost", cost, Integer.class)              // 13
      .markNodePairAttr("traffic", trf, Double.class)         // 14
      .run();                                                 // 15
 

Line 5 creates a new graph of the given node and link types (to save some typing, you can equally call GraphUtil.newGraph(java.lang.Class, java.lang.Class)).

Line 6 instantiates a SGF reader (a better, more general alternative is to use GraphUtil.createGraphReader(java.lang.String, bcds.phison.SimGraph), which instantiates the appropriate reader based on the file name extension).

Lines 8-10 create the maps to hold the desired attributes. Lines 12-14 "mark" which attributes we are interested in, and line 15 finally does the actual reading. Note that the chaning of calls is not mandatory; you can also do

   rd.markEdgeAttr(...);
   rd.markEdgeAttr(...);
   rd.run();
 

if you prefer so. The important thing to remember is that there can only be one call to run(). If the attributes such as cost or capacity are not needed, lines 9-11 can be omitted, so that a simple call to rd.run() will suffice for having the graph, that is, the nodes and links that define it.

Exceptions thrown. If opening the topology or reading it fails (the file does not exist, there is an format or semantic error, etc.), unchecked exceptions are thrown. An IOException is wrapped into an AnyException. Commonly, BadFormatException is thrown upon encountering problems during reading. See the description of the classes that implement this interface for details.

Author:

Juan Segovia S.

Constructor Summary

GraphReader(java.lang.String fname, SimGraph<V,E> g)
Creates a GraphReader so that a later call to run() will populate the graph g from the file named fname.

Method Summary

java.util.Map<java.lang.String,V>	getIdToNodeMap() Returns a reference to the internal map that associates ids to node references.
V	getNode(java.lang.String id) Returns a reference to a node with key = id, or null if no such node exits.
<VT> GraphReader<V,E>	markEdgeAttr(java.lang.String name, java.util.Map<E,VT> h, java.lang.Class<VT> value_class) Register that a given edge attribute must be read by run().
<VT> GraphReader<V,E>	markNodePairAttr(java.lang.String name, java.util.Map<SimplePair<V,V>,VT> h, java.lang.Class<VT> value_class) Register interest in a node-pair attribute, for example "traffic".
void	raiseBadFormatEx(java.lang.String fmt, java.lang.Object... args) Throws an exception with a given message.
abstract void	run() Do the actual reading.
void	setInputStream(java.io.Reader ips) Changes the input stream to ips.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GraphReader

public GraphReader(java.lang.String fname,
                   SimGraph<V,E> g)

Creates a GraphReader so that a later call to run() will populate the graph g from the file named fname.

Throws:

IOException - as a consequence of instantiating a DataFileReader.

Method Detail

setInputStream

public void setInputStream(java.io.Reader ips)

Changes the input stream to ips. The interal DataFileReader object created in the constructor is replace with a new one pointing to ips.

Throws:

IOException - when the DataFileReader constructor detects any error.

markEdgeAttr

public <VT> GraphReader<V,E> markEdgeAttr(java.lang.String name,
                                          java.util.Map<E,VT> h,
                                          java.lang.Class<VT> value_class)

Register that a given edge attribute must be read by run().

Parameters:

name - name of the attribute that must be read, for example "cost".

h - the map where the values are to be put. The key is the edge.

value_class - the class of the values to be read, for example Integer.class. Each value read is instantiated through a constructor of the form value_class(String).

Throws:

java.lang.RuntimeException - if the same attribute is marked more than once.

markNodePairAttr

public <VT> GraphReader<V,E> markNodePairAttr(java.lang.String name,
                                              java.util.Map<SimplePair<V,V>,VT> h,
                                              java.lang.Class<VT> value_class)

Register interest in a node-pair attribute, for example "traffic". The parameters and exceptions are the same as in markEdgeAttr(String, Map, Class).

getNode

public V getNode(java.lang.String id)

Returns a reference to a node with key = id, or null if no such node exits. This must be called after a successfull read.

raiseBadFormatEx

public void raiseBadFormatEx(java.lang.String fmt,
                             java.lang.Object... args)
                      throws BadFormatException

Throws an exception with a given message. Append the current line number to the message.

Throws:

BadFormatException

getIdToNodeMap

public java.util.Map<java.lang.String,V> getIdToNodeMap()

Returns a reference to the internal map that associates ids to node references. Is valid only after a successful read.

run

public abstract void run()

Do the actual reading. Beware that besides the list of exceptions shown below, derived classes may throw other exceptions, among them NumberFormatException and RuntimeException.

Throws:

BadFormatException - the file does not conform to the format expected by the parser.

AnyException - wrapping an IOException an I/O error occurrs while reading the file.