bcds.phison.io
Class IEPReader<V>

java.lang.Object
  bcds.phison.io.IEPReader<V>

public class IEPReader<V>
extends java.lang.Object

Ingress/Egress Pairs (IEP) Reader. An IEP file defines a subset of nodes of a given topology that act as source nodes for traffic, as destination or as both. For example, an IEP can be used to instruct gentraf to generate traffic between some designated nodes only.

An IEP file is a text file; each line must conform to one of the following formats:

• i node
• e node
• pair node node

where:

• "i" identifies an "ingress" node, "e" an egress node, and "pair" a specific ingress/egress pair.
• A "node" can be either an integer identifying a node (its id) or a "node label" (a node's long name, in double quotes). Node labes are always converted to lower case before comparing, thus, case does not matter.

  The meaning of "pair" is that traffic is allowed only between the given pair. The nodes included in a pair are additionally treated as if they appeared in a separate "i" and "e" definition.

  On a single line both nodes must use the same identification style (either id or label).

The file is read through DataFileReader, thus the comment indicator is #. Anything that follows this caracter (if it is unquoted) up to the end of line is discarded on input.

EXAMPLE

    i "Copenhagen"
    i 17
    i "Amsterdam"
 
    e 5
    e "Rome"
    e "Athens
    pair 5 11
    pair "Berlin" "Paris"
 

This class supports two styles of reading (both styles are exemplified in main):

• "manual", by successive calls to next() to read line by line, and
• a full read(Set, Set), which reads the input to completion before returning.

Author:

Juan Segovia S.

Constructor Summary

IEPReader(java.lang.String fname, java.util.Map<java.lang.String,java.lang.String> label_to_id, java.util.Map<java.lang.String,V> id_to_node)
Creates an IEPReader, prepares the internal reader object and saves the parameters label_to_id and id_to_node for future use.

Method Summary

SimplePair<java.lang.Integer,java.lang.Integer>	getNodes() Returns the nodes that has just been read with next().
void	getPairs(java.util.Set<SimplePair<V,V>> ps) The set of ingres-egress pairs is returned in the parameter ps, which must be non-null.
java.lang.String	getType() Returns the type of the line that has just been read.
java.lang.String	next() Reads a new line and returns the type of this new record.
void	read(java.util.Set<V> ingress_set, java.util.Set<V> egress_set) Reads the file in full and saves the data into internal variables so that they can be retrieved later through calls to other methods.
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

IEPReader

public IEPReader(java.lang.String fname,
                 java.util.Map<java.lang.String,java.lang.String> label_to_id,
                 java.util.Map<java.lang.String,V> id_to_node)

Creates an IEPReader, prepares the internal reader object and saves the parameters label_to_id and id_to_node for future use.

Parameters:

fname - the name of the file to be read (remember that "-" means stdin).

label_to_id - a map to associate labels to node ids.

id_to_node - a map to associate node id to node reference. If a topology has been read through GraphReader or one of its derived classes, this map is returned by GraphReader.getIdToNodeMap().

Throws:

AnyException - wrapping an IOException if any IO error is found while instantiating the DataFileReader object.

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:

java.io.IOException - when the DataFileReader constructor detects any error.

getType

public java.lang.String getType()

Returns the type of the line that has just been read. The type is a lowercase string, as follows: "i", "e" or "pair".

getNodes

public SimplePair<java.lang.Integer,java.lang.Integer> getNodes()

Returns the nodes that has just been read with next(). The second element of the pair is valid only if the corresponding line is of type "pair".

getPairs

public void getPairs(java.util.Set<SimplePair<V,V>> ps)

The set of ingres-egress pairs is returned in the parameter ps, which must be non-null. The previous content of ps is left untouched before adding the pairs.

This method must be called after a successful read(java.util.Set, java.util.Set).

next

public java.lang.String next()

Reads a new line and returns the type of this new record. See also getType().

Throws:

BadFormatException - with "cause" an instance of when the file does not conform to the expected format (syntax error) or when the data cannot be successfully read (node id is not integer, node cannot be found in translation maps).

read

public void read(java.util.Set<V> ingress_set,
                 java.util.Set<V> egress_set)

Reads the file in full and saves the data into internal variables so that they can be retrieved later through calls to other methods.

Parameters:

ingress_set - a non-null set which will contain the ingress nodes (type "i").

egress_set - a non-null set which will contain the egress nodes (type "e").

The node pairs can be retrieved with getPairs(java.util.Set>).

No check for duplicity is done as the destination containers are all sets (even the pairs go into a Set).

Throws:

BadFormatException - if a node cannot be found in the node maps.

AnyException - if any IOException occurs.