org.opennms.bb.dp.discovery.utils
Class DiscIcebergParser

java.lang.Object
  |
  +--org.opennms.bb.common.utils.BBParser
        |
        +--org.opennms.bb.dp.discovery.utils.DiscIcebergParser

public final class DiscIcebergParser
extends BBParser

The DiscIcebergParser class is used to parse the XML configuration file defined by the pollers.dtd. The information is parsed and the resulting data can be extracted from the instance.

Version:
$Revision: 1.8 $
Author:
Sowmya, OpenNMS

Inner Class Summary
private  class DiscIcebergParser.Parameter
          The parameter class is used by the parser to represent a classic parameter block in the XML file.
 
Inner classes inherited from class org.opennms.bb.common.utils.BBParser
BBParser.BBErrorHandler
 
Field Summary
private  String DEFAULT
           
private  String ERANGE
           
private  String FROM
           
private  String IRANGE
           
private  long m_defaultRetries
          Global default values - take the minimum since this is discovery
private  long m_defaultTimeout
           
private  List m_excRanges
          Data collected for the poller - the ranges to exclude
private  List m_incRanges
          Data collected for the poller - the ranges to include
private  List m_packages
          packages to be read - this info.
private  long m_packDefRetries
          default values (note that these will get overwritten for each 'rangeDef' block in each package that is to be considered)
private  long m_packDefTimeout
           
private  boolean m_readPackage
          if the current package being read is to be considered, this is flagged to true
private  List m_specifics
          Data collected for the poller - the specifics to include
private  String PACKAGENAME
           
private  String PARM
           
private  String PARM_NAME
           
private  String PARM_TYPE
           
private  String PARM_VALUE
           
private  String PARMS
           
private  String RANGES
           
private  String RETRIES
           
private  String SPECIFIC
           
private  String SPECIP
           
private  String TAKE_DEFAULT_VALUE
           
private  String TIMEOUT
           
private  String TO
           
private  String URL
           
private  String URLNAME
           
 
Fields inherited from class org.opennms.bb.common.utils.BBParser
ATTRIB_VALUE_PAIR_ERR, ATTRIB_VALUE_PAIR_ERR_STR, EXCEPTION, m_curElement, m_errNum, m_exceptionMsg, m_inpSource, m_parser, NULL_VALUE_ERR, NULL_VALUE_ERR_STR
 
Constructor Summary
DiscIcebergParser(List packages)
          Creates the new parser that can be used to disassemble an XML file corresponding to the packages.dtd as defined by the OpenNMS specifications.
 
Method Summary
private static String convertIntToIP(String intAddress)
          This method is used to convert a long value into an IPv4 dotted decimal string address.
private static long convertTimeToLong(String valueToConvert)
          Converts the passed time string to a time value that is measured in milliseconds.
 long getDefaultRetries()
          Returns the global value for the minimum number of retries for all the packages.
 long getDefaultTimeout()
          Returns the global value for the minimum amount of time to wait between retries.
 List getExcludeRanges()
          Returns the list of IP Address ranges that should not be included when polling the network.
 List getIncludeRanges()
          Returns the list of IP Address Ranges that are to be included when polling the network.
 List getSpecifics()
          Returns the list of specific IP Addresses that should attempt to be contacted by disocvery.
protected  boolean processDefaultElement(org.w3c.dom.Node defNode)
          This method is used to handle the range defaults section of the document.
protected  boolean processDefaultParms(org.w3c.dom.Node parmsNode)
          This method is used to process the default parameters for all the ranges.
protected  boolean processElement(org.w3c.dom.Element el, boolean isRoot)
          This method override the method in the base class that is the default target for processing elements in the DOM tree.
protected  boolean processExcRange(org.w3c.dom.Node rangesNode)
          This method is used to process an excluded range in the XML configuration file.
protected  boolean processExcRangeParms(org.w3c.dom.Node tabNode)
          This method is designed to process the individual parm blocks for an excluded range address.
protected  boolean processIncRange(org.w3c.dom.Node rangesNode)
          This method is used to process the list of IP address ranges that should be included in the addresses used to discover the network.
protected  boolean processIncRangeParms(org.w3c.dom.Node tabNode)
          This method is used to process a parm block that contains range information for inclusion into the discovery process.
protected  DiscIcebergParser.Parameter processParm(org.w3c.dom.Node parmsNode)
          This method is used to process the DTDs parameter block.
protected  boolean processParmName(org.w3c.dom.Node parmNameNode, DiscIcebergParser.Parameter parm)
          This method process the parameter <name> element of the parameter block in the DTD.
protected  boolean processParmValue(org.w3c.dom.Node parmValNode, DiscIcebergParser.Parameter parm)
          Process the <value> element of the parm block and returns the information in the passed parm element.
protected  boolean processSpecific(org.w3c.dom.Node specificsNode)
          This method is used to process multiple parameter blocks that exist as childern of the passed node.
protected  boolean processSpecificParms(org.w3c.dom.Node tabNode)
          Process the parameters associated with a specific IP Address in the XML configuation file.
 
Methods inherited from class org.opennms.bb.common.utils.BBParser
getErrorMessage, getErrorNumber, parse, parse, parse, parse, processDocument, processNode, processParmValue
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait
 

Field Detail

m_packages

private List m_packages
packages to be read - this info. is in pollersXML and is passed in

m_readPackage

private boolean m_readPackage
if the current package being read is to be considered, this is flagged to true

m_incRanges

private List m_incRanges
Data collected for the poller - the ranges to include

m_excRanges

private List m_excRanges
Data collected for the poller - the ranges to exclude

m_specifics

private List m_specifics
Data collected for the poller - the specifics to include

PARMS

private final String PARMS

PARM

private final String PARM

PARM_NAME

private final String PARM_NAME

PARM_VALUE

private final String PARM_VALUE

PARM_TYPE

private final String PARM_TYPE

PACKAGENAME

private final String PACKAGENAME

DEFAULT

private final String DEFAULT

RANGES

private final String RANGES

IRANGE

private final String IRANGE

ERANGE

private final String ERANGE

SPECIFIC

private final String SPECIFIC

URL

private final String URL

FROM

private final String FROM

TO

private final String TO

SPECIP

private final String SPECIP

URLNAME

private final String URLNAME

RETRIES

private final String RETRIES

TIMEOUT

private final String TIMEOUT

TAKE_DEFAULT_VALUE

private final String TAKE_DEFAULT_VALUE

m_packDefRetries

private long m_packDefRetries
default values (note that these will get overwritten for each 'rangeDef' block in each package that is to be considered)

m_packDefTimeout

private long m_packDefTimeout

m_defaultRetries

private long m_defaultRetries
Global default values - take the minimum since this is discovery

m_defaultTimeout

private long m_defaultTimeout
Constructor Detail

DiscIcebergParser

public DiscIcebergParser(List packages)

Creates the new parser that can be used to disassemble an XML file corresponding to the packages.dtd as defined by the OpenNMS specifications. A new instance of a DOM parser is created to parse the passed file. The list of package that should be read by the parser are passed to the object on construction.

Parameters:
packages - The list of packages to be read.
Method Detail

convertIntToIP

private static String convertIntToIP(String intAddress)

This method is used to convert a long value into an IPv4 dotted decimal string address. The string returned will be in the form of "d.d.d.d", where d is a number in the range 0 to 255 inclusive.

Parameters:
intAddress - IPv4 address in decimal format (unsigned).
Returns:
The dotted decimal IPv4 address string.

convertTimeToLong

private static long convertTimeToLong(String valueToConvert)
                               throws NumberFormatException

Converts the passed time string to a time value that is measured in milliseconds. The following extension are considered when converting the string:

ExtensionConversion Value
usMicroseconds
msMilliseconds
sSeconds
mMinutes
hHours
dDays

A number entered with out any units is considered to be in milliseconds.

Parameters:
valueToConvert - The string to convert to milliseconds.
Returns:
Returns the string converted to a millisecond value.
Throws:
NumberFormatException - Thrown if the string is malformed and a number cannot be extracted from the value.

processElement

protected boolean processElement(org.w3c.dom.Element el,
                                 boolean isRoot)

This method override the method in the base class that is the default target for processing elements in the DOM tree. The method is invoked by the DOM parser to handle each element.

Overrides:
processElement in class BBParser
Parameters:
el - The DOM element to be processed.
isRoot - True if the element is a root element.
Returns:
True if the element was successfully handled.

processDefaultElement

protected boolean processDefaultElement(org.w3c.dom.Node defNode)

This method is used to handle the range defaults section of the document. This method iterates through the nodes children elements and then calls the processDefaultParms method to process the data

Parameters:
defNode - The DOM node to handle.
Returns:
Returns true if successful, false otherwise.

processDefaultParms

protected boolean processDefaultParms(org.w3c.dom.Node parmsNode)

This method is used to process the default parameters for all the ranges. The defaults are applied to all the packages that do not override with their own specific values.

Parameters:
parmsNode - The node containing the parm blocks.
Returns:
True if the node is parsed successfully, false if it fails.

processIncRange

protected boolean processIncRange(org.w3c.dom.Node rangesNode)

This method is used to process the list of IP address ranges that should be included in the addresses used to discover the network. The processIncRangeParms method is called repeatly to process the multiple ranges that are to be used by discovery.

Parameters:
rangesNode - The toplevel DOM node containing the inclusion ranges.
Returns:
True if successful in processing the parms, false if an error occurs.

processIncRangeParms

protected boolean processIncRangeParms(org.w3c.dom.Node tabNode)

This method is used to process a parm block that contains range information for inclusion into the discovery process. The processed information will be added to the m_incRanges list for use by the discovery process.

Parameters:
tabNode - The DOM node containing the relevant part of the tree.
Returns:
True if successful, false on error.

processExcRange

protected boolean processExcRange(org.w3c.dom.Node rangesNode)

This method is used to process an excluded range in the XML configuration file. An exclusion block will consist of one or more parm blocks that contain address ranges to exclued. The excluded ranges will be added to the m_excRanges for use by the discovery applciation.

Parameters:
rangesNode - The exclusion range nodes.
Returns:
True on success, false on error.

processExcRangeParms

protected boolean processExcRangeParms(org.w3c.dom.Node tabNode)

This method is designed to process the individual parm blocks for an excluded range address. The parm block contains a start and stop range that need to be converted to an IPAddressRange object that is added to the exclusion list.

Parameters:
tabNode - The node containing the parm block.
Returns:
True if the call is successful, false if an error occurs.

processSpecific

protected boolean processSpecific(org.w3c.dom.Node specificsNode)

This method is used to process multiple parameter blocks that exist as childern of the passed node. If a "parms" block exist then the processSpecificParms method is called to handle the DOM elements.

Parameters:
specificsNode - The DOM element representing the parent of the parms block.
Returns:
True if the parsing is succcessful, false if an error occurs.

processSpecificParms

protected boolean processSpecificParms(org.w3c.dom.Node tabNode)

Process the parameters associated with a specific IP Address in the XML configuation file. If the elements are processed correctly then a new IPPollAddress element will be added to the m_specifics list of objects.

Parameters:
tabNode - The node containing the parameter information.
Returns:
True if the subtree is processed correctly, false otherwise.

processParm

protected DiscIcebergParser.Parameter processParm(org.w3c.dom.Node parmsNode)

This method is used to process the DTDs parameter block. The parameter block consist of a name, value, and the values type as an attribute. The elements are parsed out and stored in the returned Parameter object.

Parameters:
parmsNode - The node containing the parameter information
Returns:
The Parameter object containing the parsed data on success. If an error occurs then a null is returned.

processParmName

protected boolean processParmName(org.w3c.dom.Node parmNameNode,
                                  DiscIcebergParser.Parameter parm)

This method process the parameter <name> element of the parameter block in the DTD. The value for the element is returned to the caller upon success.

Parameters:
parmNameNode - The DOM Node containing the parm name.
parm - The parameter element to store the name.
Returns:
True if the call succeeds, false if an error occurs.

processParmValue

protected boolean processParmValue(org.w3c.dom.Node parmValNode,
                                   DiscIcebergParser.Parameter parm)

Process the <value> element of the parm block and returns the information in the passed parm element. If the data is successfully extracted then a value of true is returned. If an error occurs then a false value is returned.

Parameters:
parmValNode - The node element from the DOM parser.
parm - The [in/out] element modified by the call.
Returns:
True if the call succeeds, false if an error occurs.

getIncludeRanges

public List getIncludeRanges()

Returns the list of IP Address Ranges that are to be included when polling the network.

Returns:
The list of IPAddressRange object to be included.

getExcludeRanges

public List getExcludeRanges()

Returns the list of IP Address ranges that should not be included when polling the network.

Returns:
The list of IPAddressRange objects to exclude

getSpecifics

public List getSpecifics()

Returns the list of specific IP Addresses that should attempt to be contacted by disocvery. This is a list of IPPollAddress objects.

Returns:
The list of specific IPPollAddress objects to discover.

getDefaultTimeout

public long getDefaultTimeout()

Returns the global value for the minimum amount of time to wait between retries. This value is measured in milliseconds. If no default value is found in the package specification then a value of -1 is returned by the method.

Returns:
The default timeout for discovery, in milliseconds.

getDefaultRetries

public long getDefaultRetries()

Returns the global value for the minimum number of retries for all the packages. If no retries were found in the packages then a value of -1 will be returned by the method.

Returns:
The global number of retries for discovery.