kirk.io.sdl
Class SDLReader

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

public class SDLReader
extends Object

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

SDLDocument sdldocument = SDLReader.readSDL(<InputStream>); (when reading from an InputStream)
or
SDLDocument sdldocument = SDLReader.readSDLFile(<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 SDL 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 SDL document is read from.
 
Constructor Summary
protected SDLReader(InputStream in)
          Constructs a new SDLReader 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.
protected  void close()
          Closes the underlying stream.
 void finalize()
          The finalize method.
protected  SDLReadException getException(String error)
          Returns an SDLReadException 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.
protected  SDLNormalElement readNormalElement()
          Reads the normal element at the current position in the file, and the contained value.
static SDLDocument readSDL(InputStream in)
          Reads the given SDL source into an SDL document, and returns that.
protected  SDLDocument readSDLDocument()
          Reads the SDL document from the given source and returns it as an SDLDocument object.
static SDLDocument readSDLFile(String filename)
          Reads the given SDL file into an SDL document, and returns that.
protected  String readTagValue(String name)
          Return the value inbetween the tag pair (start and end tag) with the given name.
 
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 SDL 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

SDLReader

protected SDLReader(InputStream in)
             throws IOException
Constructs a new SDLReader 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

readSDLDocument

protected SDLDocument readSDLDocument()
                               throws IOException,
                                      SDLReadException
Reads the SDL document from the given source and returns it as an SDLDocument object.

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

readElement

protected SDLElement readElement()
                          throws IOException,
                                 SDLReadException
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>.

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

readNormalElement

protected SDLNormalElement readNormalElement()
                                      throws IOException,
                                             SDLReadException
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(). 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).
SDLReadException - When the SDL is not correct.

readDataElement

protected SDLDataElement readDataElement()
                                  throws IOException,
                                         SDLReadException
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(). 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).
SDLReadException - When the SDL is not correct.

readTagValue

protected String readTagValue(String name)
                       throws IOException,
                              SDLReadException
Return the value inbetween the tag pair (start and end tag) with the given name. The start tag of the given tag pair must be at the position in the file.

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

checkStartTag

protected boolean checkStartTag(String tagname)
                         throws IOException,
                                SDLReadException
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).
SDLReadException - When the end of the stream is reached during reading.

checkEndTag

protected boolean checkEndTag(String tagname)
                       throws IOException,
                              SDLReadException
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).
SDLReadException - When the end of the stream is reached during reading.

read

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

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

getException

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

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

finalize

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

See Also:
Object.finalize()

close

protected void close()
              throws IOException
Closes the underlying stream.

Throws:
IOException - When IO errors occur.

readSDL

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

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

readSDLFile

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

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