kirk.io.sdl
Class ESDLReader

java.lang.Object
  extended bykirk.io.sdl.ESDLReader

public class ESDLReader
extends Object

This class is able to read ESDL files into SDLDocuments. To make things as easy as possible, all you have to do is:

SDLDocument sdldocument = ESDLReader.readESDL(<InputStream>); (when reading from an InputStream)
or
SDLDocument sdldocument = ESDLReader.readESDLFile(<filename>); (when reading from a file).

This also means you cannot instantiate this class yourself. If for some reason you need to do this, extend this class. The constructor is protected. Note that the ESDL data must be encoded with UTF-16.

Version:
1
Author:
Berend "Kirk" Wouda
See Also:
SDLDocument

Field Summary
protected  int position
          The position in the file.
protected  BufferedReader reader
          The Reader the ESDL document is read from.
 
Constructor Summary
protected ESDLReader(InputStream in)
          Constructs a new ESDLReader with the given input source to read from.
 
Method Summary
protected  boolean checkEndTag(String tagname)
          Reads characters from the current position in the reader until as many as the length of the end tag of the given tag name are read.
protected  boolean checkStartTag(String tagname)
          Reads characters from the current position in the reader until as many as the length of the start tag of the given tag name are read.
 void finalize()
          The finalize method.
protected  ESDLReadException getException(String error)
          Returns an ESDLReadException with the given message, and some other information, like the place it happened in the file.
protected  char read()
          Reads and return the next character in the stream.
protected  SDLDataElement readDataElement()
          Reads the data element at the current position in the file, and the contained value.
protected  SDLElement readElement()
          Reads the element at the current position in the file, and the contained value.
static SDLDocument readESDL(InputStream in)
          Reads the given ESDL source into an ESDL document, and returns that.
protected  SDLDocument readESDLDocument()
          Reads the ESDL document from the given source and returns it as an SDLDocument object.
static SDLDocument readESDLFile(String filename)
          Reads the given ESDL file into an ESDL document, and returns that.
protected  SDLNormalElement readNormalElement()
          Reads the normal element at the current position in the file, and the contained value.
private  String readTagValue(String name)
          Return the value inbetween the tag pair (start and end tag) with the given name.
protected  void skipWhiteSpaceAndComments()
          This method is especially for ESDL.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

reader

protected BufferedReader reader
The Reader the ESDL document is read from.


position

protected int position
The position in the file. This is used to indicate where errors are in an SDL description.

Constructor Detail

ESDLReader

protected ESDLReader(InputStream in)
              throws IOException
Constructs a new ESDLReader with the given input source to read from. If you wish to read from a file for example, supply a new FileInputStream("filename"). The input source should provide raw byte data, which is converted to characters using UTF-16 encoding.

Parameters:
in - The InputStream to be read from.
Throws:
IOException - When an IO exception occurs. Mmmyeah.
Method Detail

readESDLDocument

protected SDLDocument readESDLDocument()
                                throws IOException,
                                       ESDLReadException
Reads the ESDL document from the given source and returns it as an SDLDocument object.

Returns:
An SDLDocument tree with all the ESDL data from the file.
Throws:
IOException - When IO errors occur (duh).
SDLReadException - When the ESDL is not correct.
ESDLReadException

readElement

protected SDLElement readElement()
                          throws IOException,
                                 ESDLReadException
Reads the element at the current position in the file, and the contained value. Then it returns it as an SDLElement. The current position in the file has to be followed by <element> or <data>, or those with whitespace and/or comments before it.

Returns:
The element at the current file position.
Throws:
IOException - When IO errors occur (duh).
SDLReadException - When the ESDL is not correct.
ESDLReadException

readNormalElement

protected SDLNormalElement readNormalElement()
                                      throws IOException,
                                             ESDLReadException
Reads the normal element at the current position in the file, and the contained value. Then it returns it as an SDLDNormalElement. The current position in the file has NOT to be followed by <element>. This has already been made sure in readElement(). There may be whitespace and/or comment at the current position as well. This method will only read until the end of the value. readElement() will then check for the end tag.

Returns:
The normal element at the current file position.
Throws:
IOException - When IO errors occur (duh).
ESDLReadException - When the ESDL is not correct.

readDataElement

protected SDLDataElement readDataElement()
                                  throws IOException,
                                         ESDLReadException
Reads the data element at the current position in the file, and the contained value. Then it returns it as an SDLDataElement. The current position in the file has NOT to be followed by <data>. This has already been made sure in readElement(). There may be whitespace and/or comment at the current position as well. This method will only read until the end of the value. readElement() will then check for the end tag.

Returns:
The data element at the current file position.
Throws:
IOException - When IO errors occur (duh).
ESDLReadException - When the ESDL is not correct.

readTagValue

private String readTagValue(String name)
                     throws IOException,
                            ESDLReadException
Return the value inbetween the tag pair (start and end tag) with the given name. Whitespace and comments may precede the start tag of the given tag pair.

Parameters:
name - The name of the tag.
Returns:
The value of the tag pair.
Throws:
IOException - When IO errors occur (duh).
ESDLReadException - When the ESDL is not correct.

skipWhiteSpaceAndComments

protected void skipWhiteSpaceAndComments()
                                  throws IOException,
                                         ESDLReadException
This method is especially for ESDL. It skips all the comment and whitespace found at the current file position, until it encounters a non-whitespace character that is not part of comment.

Throws:
IOException - When IO errors occur (duh).
ESDLReadException - When comments are not correctly constructed.

checkStartTag

protected boolean checkStartTag(String tagname)
                         throws IOException,
                                ESDLReadException
Reads characters from the current position in the reader until as many as the length of the start tag of the given tag name are read. Then, this string is compared to the start tag of the given tag name and returned is whether it is the same. If it is the same, the stream position will be advanced to the point after the read tag.

Parameters:
tagname - The tag name that the start tag that should be read of.
Returns:
Whether the given tag was read.
Throws:
IOException - When IO errors occur (duh).
ESDLReadException - When the end of the stream is reached during reading.

checkEndTag

protected boolean checkEndTag(String tagname)
                       throws IOException,
                              ESDLReadException
Reads characters from the current position in the reader until as many as the length of the end tag of the given tag name are read. Then, this string is compared to the end tag of the given tag name and returned is whether it is the same. If it is the same, the stream position will be advanced to the point after the read tag.

Parameters:
tagname - The tag name that the end tag that should be read of.
Returns:
Whether the given tag was read.
Throws:
IOException - When IO errors occur (duh).
ESDLReadException - When the end of the stream is reached during reading.

read

protected char read()
             throws IOException,
                    ESDLReadException
Reads and return the next character in the stream.

Returns:
The next character in the stream.
Throws:
IOException - When IO errors occur (duh).
ESDLReadException - When an end of file is reached.

getException

protected ESDLReadException getException(String error)
Returns an ESDLReadException with the given message, and some other information, like the place it happened in the file.

Parameters:
error - The error that occured.
Returns:
The ESDLReadException that signifies the given error.

finalize

public void finalize()
The finalize method. It closes the stream.

See Also:
Object.finalize()

readESDLFile

public static SDLDocument readESDLFile(String filename)
                                throws IOException,
                                       ESDLReadException
Reads the given ESDL file into an ESDL document, and returns that. The data must have been encoded with UTF-16.

Parameters:
filename - The ESDL file to be read.
Returns:
The SDLDocument that was constructed from the data in the file.
Throws:
IOException - When IO errors occur.
ESDLReadException - When the file is not a correct SDL file.

readESDL

public static SDLDocument readESDL(InputStream in)
                            throws IOException,
                                   ESDLReadException
Reads the given ESDL source into an ESDL document, and returns that. The data must have been encoded with UTF-16.

Parameters:
in - The InputStream that provides the ESDL to be read.
Returns:
The SDLDocument that was constructed from the data from the source.
Throws:
IOException - When IO errors occur.
ESDLReadException - When the data does not make up a correct ESDL file.