com.cra.bnet.io
Class XbnFormat

java.lang.Object
  |
  +--com.cra.bnet.io.AbstractBnetFormat
        |
        +--com.cra.bnet.io.XbnFormat
All Implemented Interfaces:
BnetFormat

public class XbnFormat
extends AbstractBnetFormat

Reads and writes Bayesian networks in XBN format.

This class does not close the Reader or Writer objects provided to it.

XML files have the option of specifying a character encoding. This occurs in the first line, like:

 <?xml version="1.0" encoding="UTF-8"?>
 
If no encoding is specified, the default is UTF-8. UTF-8 has been defined as the standard encoding for XBN files.

If an instance of OutputStreamWriter or a subclass is given to the write method, its encoding will be used in the encoding="..." in the xml - otherwise the encoding is excluded. For example, if a StringWriter is used, the encoding="..." will be excluded.

Typically, you might want to use

 Writer writer = new FileWriter(file);
 Reader reader = new FileReader(file);
 
to write to and read from files. However, these classes use the system property file.encoding as their encodings. On Windows this is Cp1252 which is not UTF-8.

Therefore, the preffered method for writing to and reading from files is to use

 Writer writer = new OutputStreamWriter(new FileOutputStream(file), "UTF-8");
 Reader reader = new InputStreamReader(new FileInputStream(file), "UTF-8");
 
so the correct character encoding will be used.

If the encoding specified by the reader and the encoding specified in the XML are different, a warning is thrown to the ErrorHandler.warning method (for example, UTF-8 and UTF-16 are incompatible character encodings).

For some reason, Java uses the string "UTF8" instead of "UTF-8" - no idea why. The XML writer used by this class will always write "UTF-8" even though java uses "UTF8". The XML parser used by this class is not smart enough to know that "UTF8" and "UTF-8" are the same though, so we still get a warning. However, we attempt to ignore it - if the warning gets through, this class will need to be updated.

If a dtd is specified in the XML provided to this class by the Reader, this class uses the following algorithm to look for the dtd file:

This class supports multiple versions of the XBN format. New versions of the XBN format add new XML elements and/or attributes, but don't change or remove existing ones. The read method will automatically detect the version. The write method will always write in the current version. The current version can be obtained by using the getCurrentVersion method.


Constructor Summary
XbnFormat()
          Creates a new XbnFormat.
 
Method Summary
 int getCurrentVersion()
          Returns the current version number.
 String getDescription()
          Returns a short description of the XBN format.
 Document getDocument(BayesianNetwork network)
          Returns a DOM document that contains the specified Bayesian network in XBN format.
 String getExtension()
          Returns the XBN file extension, ie the string "xbn".
 boolean isValid(BufferedRegExpReader reader)
          Returns true if the specified reader contains XBN data.
 boolean isValidating()
          Returns true if the XML parsers should validate or false if they should not.
static BayesianNetwork read(File file)
          Returns the Bayesian network read from the specified file.
 BayesianNetwork read(Reader reader)
          Returns the Bayesian network obtained from the specified reader.
 void setValidating(boolean validating)
          Tells the XML parsers used for reading and writing to validate if the specified boolean is true or not to validate if it is false.
static boolean write(BayesianNetwork network, File file)
          Writes the specified Bayesian network to the specified file.
 boolean write(BayesianNetwork network, Writer writer)
          Writes the specified Bayesian network to the specified writer in XBN format and returns true if the Bayesian network was written successfully.
 
Methods inherited from class com.cra.bnet.io.AbstractBnetFormat
getError, setError
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XbnFormat

public XbnFormat()
Creates a new XbnFormat.

Method Detail

getDescription

public String getDescription()
Returns a short description of the XBN format.

Returns:
a short description of the XBN format.

getCurrentVersion

public int getCurrentVersion()
Returns the current version number.

Returns:
the current version number.

read

public static BayesianNetwork read(File file)
Returns the Bayesian network read from the specified file.

Parameters:
file - file containing a Bayesian network in XBN format.
Returns:
the Bayesian network read from the specified file.
Throws:
NullPointerException - if the specified file is null.
IllegalArgumentException - if file.exists() returns false.

write

public static boolean write(BayesianNetwork network,
                            File file)
Writes the specified Bayesian network to the specified file.

Parameters:
network - Bayesian network to write.
file - file to write to.
Returns:
true if the Bayesian network was written correctly.
Throws:
NullPointerException - if the specified network or file is null.

getDocument

public Document getDocument(BayesianNetwork network)
Returns a DOM document that contains the specified Bayesian network in XBN format.

Parameters:
network - Bayesian network used to produce the document.
Returns:
a DOM document that contains the specified Bayesian network in XBN format.

getExtension

public String getExtension()
Returns the XBN file extension, ie the string "xbn".

Returns:
the string "xbn".

isValid

public boolean isValid(BufferedRegExpReader reader)
Returns true if the specified reader contains XBN data.

A BufferedRegExpReader is used in this method so that any data read from it to test for validity can be buffered for later use (in the read method, for example). To use this method properly, follow this idiom (note that the BufferedRegExpReader is given to the read method, not the original Reader):

 Reader reader = ...;
 XbnFormat format = new XbnFormat;
 BufferedRegExpReader buffered = new BufferedRegExpReader(reader);
 boolean valid = format.isValid(buffered);
 if (valid)
   BayesianNetwork network = format.read(buffered);
 

Parameters:
reader - input stream that may provide a Bayesian network in XBN format.
Returns:
true if the specified reader contains XBN data and false otherwise.

isValidating

public boolean isValidating()
Returns true if the XML parsers should validate or false if they should not.

Returns:
true if the XML parsers should validate or false if they should not.

read

public BayesianNetwork read(Reader reader)
Returns the Bayesian network obtained from the specified reader. If the Bayesian network could not be read for some reason, this method will return null. Clients may then call getError to obtain a description of the problem.

Parameters:
reader - input stream that provides a Bayesian network in XBN format.
Returns:
the Bayesian network obtained from the specified reader.

setValidating

public void setValidating(boolean validating)
Tells the XML parsers used for reading and writing to validate if the specified boolean is true or not to validate if it is false.

Parameters:
validating - whether or not to validate the XML.

write

public boolean write(BayesianNetwork network,
                     Writer writer)
Writes the specified Bayesian network to the specified writer in XBN format and returns true if the Bayesian network was written successfully. If the Bayesian network could not be written for some reason, this method will return false. Clients may then call getError to obtain a description of the problem. This method always writes using the current version of the XBN format.

Parameters:
network - Bayesian network to write.
writer - output stream to write to.
Returns:
true if the Bayesian network was written successfully and false otherwise.