bcds.phison.io
Class ZoneMap<V,E>

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

public class ZoneMap<V,E>
extends java.lang.Object

Reads and writes a zone map (.zmap) file. A zone map is essentially a cluster of nodes and their links that share some common attributes.

A "zone" is simply an id that tie together (currently) three reliability-related data: node availability, link mean-time-to-failure (float, in unit of 1 KM) and link time-to-repair (float).

After zones are defined, nodes and links can be asssigned to them. An example of a .zmap file is:

 # Zone definition and assignment for topology metro.sgf
 
 @zone_types
 # type          node avail      fiber MTBF(1km) fiber MTTR
 default         0.99994         5500000         9
 flooding        0.99970         2500000         15
 other=flooding

 # artificially "bad" values
 construction    0.99980         2410000         16
 
 @node_assignment
 construction    24
 flooding       5 18 0
 heat           29 2 25 1
 other          31 15 34

 @link_assignment
 flooding       0-7 "Lavapies"-"Retiro" 1-3
 

This is a line-oriented file format, divided into sections which start with @section_name.

• A zone definition of the form id=some_other_id is used to introduce different zones without really caring for the zone attributes. For example, this can be used by a clustering algorithm to save its output, which can later be read by other classes.
• Zone id is an arbitrary string. It must be unique within the file.
• Nodes and links can only be assigned to a single zone.
• Nodes can be referenced by id or label. Labels must be enclosed in double quotes.
• If a node or link is left unassigned, it is automatically put into a zone called "default". This zone must exist in a .zmap file.
• Links are always treated as bidirectional, that is, if 1-3 is assigned to a zone "x", so does (automatically) the link 3-1. Explicitly giving the two directions is an error.
• This class does not enforce any zone membership policy on inter-zone links. Thus, the two end nodes of a link and the link itself can be in three separate zones.

NOTES

• The use of @ to start a section is unfortunate; it should be changed to a more "classical" [section_name] style and thus take advantage of other classes.
• The fixed fields in the zone_types should be changed to a "tag" style used with .dtypes files.

Author:

Juan Segovia S.

Field Summary

static java.lang.String

DEFAULT_ZONE Id of the default zone.

Constructor Summary

ZoneMap(SimGraph<V,E> g)
Creates a ZoneMap and automatically assign all nodes and links to a default "perfect" zone.

ZoneMap(java.lang.String fname, SimGraph<V,E> g, java.util.Map<java.lang.String,java.lang.String> label_to_id, java.util.Map<java.lang.String,V> id_to_node)
Creates a ZoneMap that will be populated from the contents of the file fname.

Method Summary

ZoneInfo<V,E>	getDefaultZone() Returns the default zone.
java.lang.String	getDefaultZoneId() Returns the id of the default zone.
ZoneInfo<V,E>	getLinkZone(E e) Returns the ZoneInfo to which the link e belongs.
ZoneInfo<V,E>	getNodeZone(V v) Returns the ZoneInfo to which the node v belongs.
java.util.Map<java.lang.String,ZoneInfo<V,E>>	getZonesMap() Returns an unmodifiable view to the internal map used to hold the zones (and the elements in them).
ZoneInfo<V,E>	newDefaultZone() Returns a new ZoneInfo instance with the default zone id and "perfect" reliability data.
void	read() 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	register(ZoneInfo<V,E> zinf) Registers a given zone, whose id zinf.id.
void	reset() Reinitializes internal data structures.
void	setInputStream(java.io.Reader ips) Changes the input stream to ips.
void	setLinkZone(E e, java.lang.String id) Assigns the link e to the zone identified by id.
void	setNodeZone(V v, java.lang.String id)
void	unregister(java.lang.String id) Moves all nodes and links assigned to the zone with the given id to the default zone and then removes it.
void	write(java.lang.String fname, java.lang.String headerComment) Writes a zonemap file.
void	write(java.io.Writer out, java.lang.String headerComment) Writes a zonemap file to the given Writer object out.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_ZONE

public static final java.lang.String DEFAULT_ZONE

Id of the default zone. Value="default".

See Also:

Constant Field Values

Constructor Detail

ZoneMap

public ZoneMap(java.lang.String fname,
               SimGraph<V,E> g,
               java.util.Map<java.lang.String,java.lang.String> label_to_id,
               java.util.Map<java.lang.String,V> id_to_node)

Creates a ZoneMap that will be populated from the contents of the file fname.

Parameters:

fname - the file containing the zone map to read. stdin is represented by "-". Must not be null.

g - a non-null topology to which nodes and links in the file refer.

label_to_id - must provide an id for any node referenced in the file by label.

id_to_node - must provide a reference to a node in g for any node referenced in the file.

Throws:

AnyException - wrapping an IOException if an IO error occurs in the instantiation of the DataFileReader object. a call to the DataFileReader constructor.

ZoneMap

public ZoneMap(SimGraph<V,E> g)

Creates a ZoneMap and automatically assign all nodes and links to a default "perfect" zone. That automatically inserted zone is called "default". It is perfect in the sense that node availability=1.0, fiber MTTR=0, etc.

As the maps "label to id" and "id to node" are set to null, read() cannot succeed on this instance (a NullPointerException will be thrown).

Method Detail

setInputStream

public void setInputStream(java.io.Reader ips)
                    throws java.io.IOException

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.

reset

public void reset()

Reinitializes internal data structures. All existing zones and assignments are lost, including the default zone.

getDefaultZoneId

public java.lang.String getDefaultZoneId()

Returns the id of the default zone.

getDefaultZone

public ZoneInfo<V,E> getDefaultZone()

Returns the default zone.

newDefaultZone

public ZoneInfo<V,E> newDefaultZone()

Returns a new ZoneInfo instance with the default zone id and "perfect" reliability data.

getZonesMap

public java.util.Map<java.lang.String,ZoneInfo<V,E>> getZonesMap()

Returns an unmodifiable view to the internal map used to hold the zones (and the elements in them). This map is an instance TreeMap so that it is kept sorted by zone id.

getNodeZone

public ZoneInfo<V,E> getNodeZone(V v)

Returns the ZoneInfo to which the node v belongs.

setNodeZone

public void setNodeZone(V v,
                        java.lang.String id)

getLinkZone

public ZoneInfo<V,E> getLinkZone(E e)

Returns the ZoneInfo to which the link e belongs.

setLinkZone

public void setLinkZone(E e,
                        java.lang.String id)

Assigns the link e to the zone identified by id.

Throws:

java.lang.IllegalArgumentException - if the given zone does not exist.

register

public void register(ZoneInfo<V,E> zinf)

Registers a given zone, whose id zinf.id. If there was already a zone registered with that id, it is replaced.

unregister

public void unregister(java.lang.String id)

Moves all nodes and links assigned to the zone with the given id to the default zone and then removes it. Any attempt to remove the default zone is silently ignored.

Throws:

java.lang.IllegalArgumentException - if the given zone does not exist.

read

public void read()

Reads the file in full and saves the data into internal variables so that they can be retrieved later through calls to other methods. Any existing zones and assignments are removed before performing the read.

write

public void write(java.lang.String fname,
                  java.lang.String headerComment)

Writes a zonemap file. If fname is "-", the output goes to stdout.

write

public void write(java.io.Writer out,
                  java.lang.String headerComment)

Writes a zonemap file to the given Writer object out.