gov.nist.antd.optical
Class Lambda

java.lang.Object
  |
  +--gov.nist.antd.optical.Lambda
All Implemented Interfaces:
FailureInformation, FailureInformation2, LambdaInterface

public class Lambda
extends java.lang.Object
implements LambdaInterface, FailureInformation2

The lambda used in a fiber. The behaviour of the lambda changed to the version 1.6 in the following way:
The Lambda has two internal failure attributes, emitterFailure and receiverFailure. This ailure attributes replace the attribute failure. This had to be done to be complient with SSF and multiple timelines. The Lambda can't change the role of emitter and receiver in the using ONIC anymore. The setup has to be done in advance and is by default: host2 of the fiber is the receiving host and the attribute receiverFailure is assigned to this entity.
the following attributes are only allowed to be accessed by the emitter host:

 reserved   -> boolean isReserved()   - setReserved(boolean)
 available  -> boolean isAvailable()  - setAvailable(boolean)
 protection -> boolean isProtection() - setProtection(boolean)
 
All these attributes are only for usage by the sender, the node with the physical laser diode. Therefore the framework does not check the timeline.
The timeline critical attribute is the attribute failure. To be backwards compatible with GLASS 1.0 the access methods are still available but they request only the value of the emitter and set the value of both sides. This can result in a timeline conflikt. If the framework recognizes such a failure the methods throw an TopologyException. This is declared as program bug.

Each Lambda can be configured in the following way:

Lambda [
   id                            # Must be unique in the fiber.
   control                       # INdicates the usage, ctrl or data
   wavelength                     # Value in nm
   bandwidth                      # Value in Gps
   failure                       
   pair           
   receiver                # Indicates the lambdas direction
   snr                            # Signal to noise ratio
   protection     
   protectionMode 
 ]
 

The settings for: receiver, pair, failure, protection, protectionMode, and snr are optional.

This class was developed at the National Institute of Standards and
 Technology by employees of the Federal Government in the course of
 their official duties. Pursuant to title 17 Section 105 of the United
 States Code this software is not subject to copyright protection and
 is in the public domain.
 NIST assumes no responsibility whatsoever for its use by other parties,
 and makes no guarantees, expressed or implied, about its quality,
 reliability, or any other characteristic.
 
We would appreciate acknowledgement if the software is used.
NIST ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" CONDITION AND DISCLAIM ANY LIABILITY OF ANY KIND FOR ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.

Version:
2.2

 VERSION CONTROL
 -----------------------------------------------------------------------------
 Name - YYYY/MM/DD - VERSION - ACTION
borchert - 2001/05/29 - 1.0 - Source created.
borchert - 2001/09/27 - 1.1 - Added FAILURE and CHANGE event.
borchert - 2001/10/05 - Added the attribute reserved.
borchert - 2001/10/26 - 1.2 - Add the interface FailureInformation.
borchert - 2001/10/30 - 1.3 - Add the failure notification for the ONIC.
borchert - 2001/10/31 - Added the check of the ONICS in the method isDepthFailure().
borchert - 2001/11/06 - 1.4 - Fixed bug in isDepthFailure. Changed the order of ONICs.
rouil - 2002/02/14 - Complete documentation
borchert - 2002/03/04 - 1.5 - Moved interface Failureinformation into package gov.nist.antf.ssf borchert - 2002/09/25 - 2.0 - The failure attribute depends on the requesting node and it's timeline. The Attribute is changed to emitterFailure and receiverFailure. - Fixed access of deprecated methods. borchert - 2002/09/28 - Add methods isReceiverOf(ONIC) and isEmitterOf(ONIC). - Changed the implemented interface from FailureInformation to FailureInformation2 borchert - 2002/10/01 - The method isFailure only returns the internal failure value. The method isDepthFailure considders the onic and peer information if nexessary. rouil - 2002/10/01 - Changed method setReceiver from private to protected because it can be called from fiber. borchert - 2002/10/02 - Fixed bug in method isFailure(Entity). borchert - 2002/10/08 - Changed toString() output. borchert - 2002/10/11 - Added method getReceiver(). borchert - 2002/10/16 - Updated failure attributes to be the same as in Fiber and Link. borchert - 2002/10/18 - Removed private method notifyONIC(). borchert - 2002/10/24 - Fixed a bug in setWavelength(double). klink - 2002/11/08 - 2.1 - Added method isReceiver(ProtocolGraph), deprecated method isReceiverOf(ONIC) klink - 2002/11/14 - 2.2 - Added method isEmitter(ProtocolGraph), deprecated method isEmitterOf(ONIC) borchert - 2002/11/14 - The WARNING messages will be printed out only once. borchert - 2002/11/18 - Changed error text in method setWavelength(..).

Author:
borchert
, klink , rouil

Field Summary
private  boolean available
          Indicates if the Lambda is available.
private  double bandwidth
          This value represents the bandwidth of this lambda.
private  boolean control
          Indicates if this lambda is used for the control plane.
private  com.renesys.raceway.SSF.Entity emitterHost
          The sending Host.
private  ONIC emitterONIC
          The emitting ONIC.
static double ERR
          Constante value for the precision in computing the wavelength.
private  java.util.Hashtable failureTable
          This hashtable contains the failure of the emitter and receiver.
private  Fiber fiber
          The fiber the lambda is asigned to.
static byte HOST1
          Constant value that specify the receiver host HOST1.
static byte HOST2
          Constant value that specify the receiver host HOST1.
private  int id
          The id of the lambda.
protected  boolean inConfiguration
          Indicator if the class is in the configuration mode (true).
private  Lambda pair
          The pair lambda assiociated to this lambda.
private static boolean PRN_DEPFAIL
          Will be set to false after the warning first print of isDephFauilure().
private static boolean PRN_ISFAIL
          Will be set to false after the warning first print of isFauilure().
private static boolean PRN_SETFAIL
          Will be set to false after the warning first print of isFauilure().
private  boolean protection
          Indicates if this Lambda is used as a protection for an other Lambda.
private  int protectionMode
          The mode of Protection ProtectionMode.NEVER, ProtectionMode.ONLY, or ProtectionMode.SHARED
private  byte receiver
          The Entity that used the Lambda as receiver (default is HOST2).
private  com.renesys.raceway.SSF.Entity receiverHost
          The receiving Host.
private  ONIC receiverONIC
          The receiving ONIC.
private  boolean reserved
          Indicates if the Lambda is already reserved for later use.
private  double snr
          This attribute contains the signal to noise ratio.
private  double wavelength
          The wavelength.
 
Constructor Summary
Lambda(Fiber fiber)
          Constructs a lambda.
Lambda(Fiber fiber, int id)
          Constructs a lambda.
 
Method Summary
 boolean checkData()
          This method checks the data of the object.
 boolean compareCharacteristics(Lambda otherLambda)
          Compare the attribute wavelength of two lambda's.
 void config(com.renesys.raceway.DML.Configuration cfg)
          Configure the Fiber.
protected  void configureBandwidth(java.lang.String value)
          Configures the bandwidth from the DML
private  void configureControl(java.lang.String value)
          Configures the control status.
private  void configureID(java.lang.String value)
          Configures the id.
protected  void configurePair(java.lang.String value)
          Configures the pairing.
protected  void configureWaveLength(java.lang.String value)
          Configures the wavelength.
 double getBandwidth()
          Get the bandwidth of this lambda.
 Fiber getFiber()
          Get the Fiber this lambda is assigned.
 int getID()
          Get the id of this lambda.
 Lambda getPair()
          Get the pair lambda attached to this lambda.
 int getProtectionMode()
          Returns the protection mode of the lambda.
 byte getReceiver()
          Returns the registered receiver value.
 double getSNR()
          Get the value of the signal to noise ratio.
 double getWavelength()
          Get the value of the wavelength.
private  boolean has2TimeLines()
          Checks the timeline of both connecton onics.
 boolean isAvailable()
          Informs if this lambda is used.
 boolean isControl()
          Indicates if the lambda is used for control.
 boolean isDepthFailure()
          Deprecated. Don't use this method anumore.
 boolean isDepthFailure(com.renesys.raceway.SSF.Entity forHost)
          Is doing the same as isFailure(Entity) excpet the fiber, link and onic will be tested too.
 boolean isEmitter(ProtocolGraph pg)
          Returns if this lambda is in the role of an emitter for this ONIC.
 boolean isEmitterOf(ONIC onic)
          Deprecated. Use isReceiver(ProtocolGraph) instead
 boolean isFailure()
          Deprecated. This method should not be used longer. It could produce a time based data integrity problem.
 boolean isFailure(com.renesys.raceway.SSF.Entity forHost)
          Returns true if is this lambda component is failed.
 boolean isProtection()
          Informs if this lambda is used as a protection lambda.
 boolean isReceiver(ProtocolGraph pg)
          Returns if this lambda is in the role of a receiver for this ONIC.
 boolean isReceiverOf(ONIC onic)
          Deprecated. Use isReceiver(ProtocolGraph) instead
 boolean isReserved()
          Informs if the lambda is already reserved.
protected  void sendMessage(short messageType)
          Deprecated. DON'T USE THIS ANYMORE
 void setAvailable(boolean available)
          Set the attribute available.
 void setBandwidth(double newBandwidth)
          Define the bandwidth for this lambda.
 void setControl(boolean control)
          Set the attribute control.
 void setFailure(boolean failure)
          Deprecated. This method should not be used longer. It could produce a time based data integrity problem.
 void setFailure(com.renesys.raceway.SSF.Entity forHost, boolean failure)
          Set the attribute for the emitterFailure and/or receiverFailure.
protected  void setFiber(Fiber newFiber)
          Set the fiber of this Lambda.
 void setID(int newID)
          Set the id for this lambda.
 void setPair(Lambda pair)
          Create a relation between two lambdas.
 void setProtection(boolean protection)
          Set the attribute protection.
 void setProtectionMode(int newMode)
          Set the protection mode.
 void setReceiver(byte newReceiver)
          This method set and initialize the Lambda-receiver.
 void setReserved(boolean reserved)
          Set the attribute reserved.
 void setSNR(double newSnr)
          Set the attribute signal to noise ratio.
 void setWavelength(double newWavelength)
          Set the wavelength value of this lambda in nm.
 java.lang.String toString()
          Textual representation of the lambda.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

PRN_DEPFAIL

private static boolean PRN_DEPFAIL
Will be set to false after the warning first print of isDephFauilure().

Since:
2.2

PRN_ISFAIL

private static boolean PRN_ISFAIL
Will be set to false after the warning first print of isFauilure().

Since:
2.2

PRN_SETFAIL

private static boolean PRN_SETFAIL
Will be set to false after the warning first print of isFauilure().

Since:
2.2

ERR

public static final double ERR
Constante value for the precision in computing the wavelength.

See Also:
Constant Field Values

HOST1

public static final byte HOST1
Constant value that specify the receiver host HOST1.

See Also:
Constant Field Values

HOST2

public static final byte HOST2
Constant value that specify the receiver host HOST1.

See Also:
Constant Field Values

available

private boolean available
Indicates if the Lambda is available. This attribute MUST be false if the Lambda has a failure at the emitter.


reserved

private boolean reserved
Indicates if the Lambda is already reserved for later use. This is usefull lambda assignment. This attribute will be used and manipulated by the class OpticalChannelSegment


control

private boolean control
Indicates if this lambda is used for the control plane.


failureTable

private java.util.Hashtable failureTable
This hashtable contains the failure of the emitter and receiver.


id

private int id
The id of the lambda. This id has to be unique at the Fiber. ID=0 for the control lambda in each fiber.


protection

private boolean protection
Indicates if this Lambda is used as a protection for an other Lambda.


protectionMode

private int protectionMode
The mode of Protection ProtectionMode.NEVER, ProtectionMode.ONLY, or ProtectionMode.SHARED


bandwidth

private double bandwidth
This value represents the bandwidth of this lambda. (Default==2.5 Gbps)


snr

private double snr
This attribute contains the signal to noise ratio. (Default==0.0)


wavelength

private double wavelength
The wavelength. (Default==0.0)


inConfiguration

protected boolean inConfiguration
Indicator if the class is in the configuration mode (true).


receiver

private byte receiver
The Entity that used the Lambda as receiver (default is HOST2).

Since:
2.0

pair

private Lambda pair
The pair lambda assiociated to this lambda.


fiber

private Fiber fiber
The fiber the lambda is asigned to.


emitterHost

private com.renesys.raceway.SSF.Entity emitterHost
The sending Host. (This will be set by the method setReceiver(...).

Since:
2.0

receiverHost

private com.renesys.raceway.SSF.Entity receiverHost
The receiving Host. (This will be set by the method setReceiver(...).

Since:
2.0

emitterONIC

private ONIC emitterONIC
The emitting ONIC. (This will be set by the method setReceiver(...)). This attribute is needed to determine the lambdas deep failure caused by ONIC failrue.

Since:
2.0

receiverONIC

private ONIC receiverONIC
The receiving ONIC. (This will be set by the method initReceiver(...)). This attribute is needed to determine the lambdas deep failure caused by the failing peer onic.

Since:
2.0
Constructor Detail

Lambda

public Lambda(Fiber fiber)
       throws DataIntegrityException
Constructs a lambda. The fiber must be a valid instance.

Parameters:
fiber - The fiber that contains this lambda.
Throws:
DataIntegrityException - The Lambda could not be created for the link.

Lambda

public Lambda(Fiber fiber,
              int id)
       throws DataIntegrityException
Constructs a lambda. The fiber must be a valid instance.

Parameters:
fiber - The fiber that contains this lambda.
id - The id of the lambda. This id must be unique in the fiber.
Throws:
DataIntegrityException - The Lambda could not be created for the link.
Method Detail

compareCharacteristics

public boolean compareCharacteristics(Lambda otherLambda)
Compare the attribute wavelength of two lambda's. The characteristics that are compared are
wavelength, protection, and signalType

Parameters:
otherLambda - The second lambda.
Returns:
True if there is no differences.

getFiber

public Fiber getFiber()
Get the Fiber this lambda is assigned.

Returns:
Attribute fiber.

getID

public int getID()
Get the id of this lambda.

Specified by:
getID in interface LambdaInterface
Returns:
The attribute ID.

getPair

public Lambda getPair()
Get the pair lambda attached to this lambda.

Returns:
Lambda The attribute Pair.

getBandwidth

public double getBandwidth()
Get the bandwidth of this lambda.

Returns:
the bandwidth

getSNR

public double getSNR()
Get the value of the signal to noise ratio.

Returns:
The attribute snr.

getWavelength

public double getWavelength()
Get the value of the wavelength.

Returns:
The attribute wavelength.

isAvailable

public boolean isAvailable()
Informs if this lambda is used.

Returns:
True if the lambda is not used and as no failure.

isReserved

public boolean isReserved()
Informs if the lambda is already reserved. This result of this method will not be affected by the availability of the lambda.

Returns:
true if the lambda is reserved, otherwise false.

isControl

public boolean isControl()
Indicates if the lambda is used for control.

Returns:
true if the lambda is a control lambda.

isProtection

public boolean isProtection()
Informs if this lambda is used as a protection lambda.

Returns:
The attribute protection.

getProtectionMode

public int getProtectionMode()
Returns the protection mode of the lambda.

Returns:
The int that indicates the mode.

setAvailable

public void setAvailable(boolean available)
Set the attribute available.

Parameters:
available - True if the lambda is not used.

setReserved

public void setReserved(boolean reserved)
Set the attribute reserved.

Parameters:
reserved - True if the lambda is reserved.

setControl

public void setControl(boolean control)
Set the attribute control.

Parameters:
control - True if this lambda is used by control plane.

setID

public void setID(int newID)
           throws DuplicateIDException
Set the id for this lambda.

Parameters:
newID - The new id.
Throws:
DuplicateIDException - The ID is already used in the fiber.

setPair

public void setPair(Lambda pair)
             throws DataIntegrityException
Create a relation between two lambdas.

Parameters:
pair - The lambda attached to this one.
Throws:
DataIntegrityException - If the dataintegrity is not given.

setProtection

public void setProtection(boolean protection)
Set the attribute protection.

Parameters:
protection - The new status.

setProtectionMode

public void setProtectionMode(int newMode)
                       throws IllegalDataException,
                              DataIntegrityException
Set the protection mode.

Parameters:
newMode - the protection mode.
Throws:
IllegalDataExcetion - The given mode is not known.
DataIntegrityException - The given mode and the protection value is invalid (i.e. ProtectionMode.NEVER and isProtection()==true.
IllegalDataException

setBandwidth

public void setBandwidth(double newBandwidth)
Define the bandwidth for this lambda.

Parameters:
newBandwidth - The new bandwidth.

setSNR

public void setSNR(double newSnr)
Set the attribute signal to noise ratio.

Parameters:
newSnr - The new value.

setWavelength

public void setWavelength(double newWavelength)
                   throws IllegalDataException,
                          DataIntegrityException
Set the wavelength value of this lambda in nm.

Parameters:
newWavelength - The value of the wavelength.
Throws:
IllegalDataException
DataIntegrityException

isFailure

public boolean isFailure()
                  throws TimelineException
Deprecated. This method should not be used longer. It could produce a time based data integrity problem.

Returns true if is this lambda component is failed.

Specified by:
isFailure in interface FailureInformation
Returns:
True if the lambda is failed.
Throws:
TimelineException - Will be thrown if the timeline of both ONICS is different.
See Also:
isFailure(Entity)

isFailure

public boolean isFailure(com.renesys.raceway.SSF.Entity forHost)
                  throws TopologyException
Returns true if is this lambda component is failed. Depending on the role of the lambda the result can be different. If the lambda is an emitter the return value will be the value of the emitter itself, is the lambda a receiver, it returns the light status of the lambda. The peer onic won't be considered in this failure checkup. If the given entity is not the receiverHost and the timeline of receiver and emitter is the same the result will be the emitter failure value.

Specified by:
isFailure in interface FailureInformation2
Parameters:
forHost - The host the failure has to be set for.
Returns:
True if the lambda is failed.
Throws:
TopologyException - Will be thrown when no information for the given host/entity is found.
Since:
2.0

isDepthFailure

public boolean isDepthFailure()
Deprecated. Don't use this method anumore.

Informs if lambda or one of the related components (fiber, link, and ONICS) are failed. This method is not compatible with multiple timelines. This method checks the following:
- regular failure of lambda.
- regular failure of fiber (fibercut)
- regular failure of the link - no depthfailure necessary.
- regualr failure of the emitter side ONIC.

Returns:
True if the lambda, the related fiber, or the related link failed.
Throws:
TimelineException - Will be thrown if the timeline of both ONICS is different.
See Also:
isDepthFailure(Entity)

isDepthFailure

public boolean isDepthFailure(com.renesys.raceway.SSF.Entity forHost)
Is doing the same as isFailure(Entity) excpet the fiber, link and onic will be tested too. This method checks the following:
- regular failure of lambda.
- regular failure of fiber (fibercut)
- regular failure of the link - no depthfailure necessary.
- regular failure of the ONICS. In case the lambda is in the role of a receiver the stored failure information of the peer onic will be checked as well. (Loss of light cause by the emitter sides onic.

Returns:
True if the lambda, the related fiber, or the related link failed.
Throws:
TopologyException - Will be thrown if the timeline of both ONICS is different.
Since:
2.0

setFailure

public void setFailure(boolean failure)
                throws TimelineException
Deprecated. This method should not be used longer. It could produce a time based data integrity problem.

Set the attributes emitterFailure and receiverFailure.

Parameters:
failure - The new failure value.
Throws:
TimelineException - If both ONICS are in a different timeline.
See Also:
setFailure(Entity,boolean)

setFailure

public void setFailure(com.renesys.raceway.SSF.Entity forHost,
                       boolean failure)
Set the attribute for the emitterFailure and/or receiverFailure.

Parameters:
failure - The new failure value.

toString

public java.lang.String toString()
Textual representation of the lambda.

Overrides:
toString in class java.lang.Object
Returns:
The textual representation as String.

setFiber

protected void setFiber(Fiber newFiber)
                 throws DataIntegrityException
Set the fiber of this Lambda.

Parameters:
newFiber - The fiber the lambda is assigned to.
Throws:
DataIntegrityException - will be thrown, if the data integrity is not given anymore.

checkData

public boolean checkData()
                  throws DataIntegrityException
This method checks the data of the object.

Returns:
true If the data are not complete.
Throws:
DataIntegrityException - This exception will be thrown only in the case that stored data are damaging the data integrity.

config

public void config(com.renesys.raceway.DML.Configuration cfg)
            throws com.renesys.raceway.DML.configException
Configure the Fiber.

Parameters:
cfg - The configuration object.
Throws:
com.renesys.raceway.DML.configException - an Configuration Exception occured

configureID

private void configureID(java.lang.String value)
                  throws com.renesys.raceway.DML.configException,
                         DataIntegrityException
Configures the id.

Parameters:
value - the id value.
Throws:
com.renesys.raceway.DML.configException - an configException occured.
DataIntegrityException - an DataIntegrityException occured.

configureControl

private void configureControl(java.lang.String value)
                       throws com.renesys.raceway.DML.configException,
                              DataIntegrityException
Configures the control status.

Parameters:
value - the control value.
Throws:
com.renesys.raceway.DML.configException - an configException occured.
DataIntegrityException - an DataIntegrityException occured.

configureWaveLength

protected void configureWaveLength(java.lang.String value)
                            throws DataIntegrityException
Configures the wavelength.

Parameters:
value - the wavelength value.
Throws:
DataIntegrityException - an DataIntegrityException occured.

configurePair

protected void configurePair(java.lang.String value)
                      throws com.renesys.raceway.DML.configException,
                             DataIntegrityException
Configures the pairing.

Parameters:
value - the pair value.
Throws:
com.renesys.raceway.DML.configException - an configException occured.
DataIntegrityException - an DataIntegrityException occured.

configureBandwidth

protected void configureBandwidth(java.lang.String value)
                           throws IllegalDataException
Configures the bandwidth from the DML

Parameters:
value - the string representing the bandwidth from the DML
Throws:
IllegalDataException - thrown if value is not a valid bandwidth

sendMessage

protected void sendMessage(short messageType)
Deprecated. DON'T USE THIS ANYMORE

Checks if the Eventhandler has receivers and this object is not in the configuration mode, this message will send the specified event.

Parameters:
messageType - the type of the message. The types are specified in the class gov.nist.antd.optical.event.monitor.EventHandler.

setReceiver

public void setReceiver(byte newReceiver)
This method set and initialize the Lambda-receiver. It initializes the failure for both, receiver and emitter with the initial value assigned to the link.

Parameters:
newReceiver - Set the receiver value.

has2TimeLines

private boolean has2TimeLines()
Checks the timeline of both connecton onics. Additional verbose description.

Returns:
true if both connecting ONICS are in a different timeline, otherwise fasle.

isReceiverOf

public boolean isReceiverOf(ONIC onic)
                     throws TopologyException
Deprecated. Use isReceiver(ProtocolGraph) instead

Returns if this lambda is in the role of a receiver for this ONIC.

Parameters:
onic - The ONIC that has to be checked.
Returns:
True if the lambda is a receiver of this ONIC.
Throws:
TopologyException - If the ONIC is unknown to the lambda.

isReceiver

public boolean isReceiver(ProtocolGraph pg)
                   throws TopologyException
Returns if this lambda is in the role of a receiver for this ONIC.

Parameters:
pg - The ProtocolGraph that has to be checked.
Returns:
True if the lambda is a receiver of this ONIC.
Throws:
TopologyException - If the ONIC is unknown to the lambda.
Since:
2.1

isEmitterOf

public boolean isEmitterOf(ONIC onic)
                    throws TopologyException
Deprecated. Use isReceiver(ProtocolGraph) instead

Returns if this lambda is in the role of an emitter for this ONIC.

Parameters:
onic - The ONIC that has to be checked.
Returns:
True if the lambda is an emitter of this ONIC.
Throws:
TopologyException - If the ONIC is unknown to the lambda.

isEmitter

public boolean isEmitter(ProtocolGraph pg)
                  throws TopologyException
Returns if this lambda is in the role of an emitter for this ONIC.

Parameters:
pg - The ProtocolGraph that has to be checked.
Returns:
True if the lambda is an emitter of this ONIC.
Throws:
TopologyException - If the ONIC is unknown to the lambda.

getReceiver

public byte getReceiver()
Returns the registered receiver value. The value can be Lambda.HOST1, Lambda.HOST2.

Since:
2.0