com.h3c.of.sw

Class AbstractDefReader

java.lang.Object

com.h3c.of.sw.AbstractDefReader

public abstract class AbstractDefReader
extends Object

Abstract base class for parsing text-based definition files.

A definition file is a free format text file where lines beginning with the # symbol are treated as comments and ignored, as are blank lines. All other lines are treated as input and converted to "logical" lines. There will be one logical line per real (non-comment) line, except in the case where the backslash character is used to indicate line continuation. For example:

 1   # a comment
 2
 3   some input line
 4   another input line \
 5      continued on the next line
 6
 7   # another comment
 8   last line
 

In this example, the parsed definition will consist of 3 logical lines:

 [3] some input line
 [4-5] another input line continued on the next line
 [8] last line
 

The line numbers from the source file are indicated in square brackets.

As the file is processed, subclasses have the opportunity to further validate each logical line by overriding the parseLogicalLine(com.h3c.of.sw.AbstractDefReader.LogicalLine) method. The implementation should return null if the line is acceptable, or a short string describing why it is not. These "errors" are collected and reported to the user in a single ValidationException, indicating the line numbers at which the errors occurred.

The following example accepts only lines of the form "key: some value":

 private static final Pattern RE_KV = Pattern.compile("(\\w+):\\s+(.*)");

 @Override
 protected String parseLogicalLine(LogicalLine line) {
    return RE_KV.matcher(line.getText()).matches()
            ? null : "invalid format: \"" + line.getText() + "\"";
 }
 

If we used this implementation to try and parse the example file above, the following exception would be thrown:

 com.h3c.util.ValidationException: Failed to parse sample.def
   Line 3: invalid format: "some input line"
   Line 4-5: invalid format: "another input line continued on the next line"
   Line 8: invalid format: "last line"
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AbstractDefReader.Line Represents a single line of text from the definition file.
static class	AbstractDefReader.LogicalLine Represents a logical (non-comment) line from the definition file; possibly an aggregate of several lines.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractDefReader(String path) Constructs the definition file reader by reading in the specified text file, and parsing it into logical lines.

Method Summary

Methods

Modifier and Type	Method and Description
List<String>	debugLines() Returns a list of strings representing each of the logical lines, used by AbstractDefn.toDebugString().
List<AbstractDefReader.LogicalLine>	getLines() Returns an unmodifiable view of the logical lines.
String	getPath() Returns the definition file path.
protected void	initStorage() Subclasses may override this method to initialize their data model before the parsing actually starts.
protected void	parseDefinition(String[] lines) Parses the definition file, creating a model of the logical lines.
protected abstract String	parseLogicalLine(AbstractDefReader.LogicalLine line) This method is invoked once for every logical line in the definition file.
String	toDebugString() Returns a multi-line string representation of the definition file.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractDefReader

protected AbstractDefReader(String path)

Constructs the definition file reader by reading in the specified text file, and parsing it into logical lines.

Parameters:

path - the path of the file

Method Detail

parseDefinition

protected void parseDefinition(String[] lines)

Parses the definition file, creating a model of the logical lines.

Parameters:

lines - the lines of the file

initStorage

protected void initStorage()

Subclasses may override this method to initialize their data model before the parsing actually starts. For example, if each logical line is going to be converted into a "Command", the List<Command> field in which to store the commands should be initialized from this method.

This default implementation does nothing.

parseLogicalLine

protected abstract String parseLogicalLine(AbstractDefReader.LogicalLine line)

This method is invoked once for every logical line in the definition file. Note that comments and blank lines are ignored, and continuation lines are joined into a single logical line. If all is well, the method should return null; if there is a parse error, a short string describing the error should be returned.

Parameters:

line - the line to parse

Returns:

null if all is well, a short error description if not

toString

public String toString()

Overrides:

toString in class Object

toDebugString

public String toDebugString()

Returns a multi-line string representation of the definition file.

Returns:

a multi-line string representation

getLines

public List<AbstractDefReader.LogicalLine> getLines()

Returns an unmodifiable view of the logical lines.

Returns:

the logical lines

debugLines

public List<String> debugLines()

Returns a list of strings representing each of the logical lines, used by AbstractDefn.toDebugString().

Returns:

a list of strings, one per logical line

getPath

public String getPath()

Returns the definition file path.

Returns:

the path