Package jmri.jmrit

Class XmlFile

java.lang.Object

jmri.jmrit.XmlFile

Direct Known Subclasses:

AbstractWiThrottlePreferences.AbstractWiThrottlePreferencesXml, BlockValueFile, CbusEventTableXmlFile, CbusNodeBackupFile, ConfigXmlManager, ConsistFile, DecoderFile, DecoderIndexFile, DefaultCatalogTreeManagerXml, DefaultIdTagManagerXml, DefaultSignalSystemManager.AspectFile, Digitrax7thGenAccyRoutesXML.DigitraxRoutesXmlFile, ExportCars, ExportEngines, ExportLocations, ExportRoutes, ExportSchedules, ExportTimetable, ExportTrainLineups, ExportTrains, LoadXmlThrottlesLayoutAction.ThrottlePrefs, LocoFile, NameFile, NceConsistRoster, OlcbEventNameStoreXml, OlcbNodeGroupStoreXml, OperationsXml, OptionsFile, PollingFile, PositionFile, RollingStockLogger, Roster, ThrottlesPreferences.ThrottlesPrefsXml, TimeTableXml.TimeTableXmlFile, TrainInfoFile, TrainLogger, VSDecoderPreferences.VSDecoderPrefsXml, VSDGeoFile, WarrantPreferences.WarrantPreferencesXml

public class XmlFile
extends java.lang.Object

Handle common aspects of XML files.

JMRI needs to be able to operate offline, so it needs to store resources locally. At the same time, we want XML files to be transportable, and to have their schema and stylesheets accessible via the web (for browser rendering). Further, our code assumes that default values for attributes will be provided, and it's necessary to read the schema for that to work.

We implement this using our own EntityResolver, the JmriLocalEntityResolver class.

When reading a file, validation is controlled heirarchically:

• There's a global default
• Which can be overridden on a particular XmlFile object
• Finally, the static call to create a builder can be invoked with a validation specification.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	XmlFile.Validate	Specify validation operations on input.

Field Summary

Fields

Modifier and Type	Field	Description
(package private) static java.lang.String	defaultDtdLocation
java.lang.String	dtdLocation
static java.lang.String	xsltLocation	Define root part of URL for XSLT style page processing instructions.

Constructor Summary

Constructors

Constructor	Description
XmlFile()

Method Summary

Modifier and Type	Method	Description
static void	addDefaultInfo(org.jdom2.Element root)	Add default information to the XML before writing it out.
java.lang.String	backupFileName(java.lang.String name)	Return the name of a new, unique backup file.
protected boolean	checkFile(java.lang.String name)	Check if a file of the given name exists.
java.lang.String	createFileNameWithDate(java.lang.String name)
static void	dumpElement(org.jdom2.Element name)	Diagnostic printout of as much as we can find
protected java.io.File	findFile(java.lang.String name)	Get a File object for a name.
static org.jdom2.input.SAXBuilder	getBuilder(XmlFile.Validate validate)
static java.lang.String	getDefaultDtdLocation()	Get the default standard location for DTDs in new XML documents.
static XmlFile.Validate	getDefaultValidate()	Whether to, by global default, validate the file being read.
java.lang.String	getDtdLocation()	Get the location for DTDs in this XML document.
java.lang.String	getProcessingInstructionHRef()	Get the value of the attribute 'href' of the process instruction of the last loaded document.
java.lang.String	getProcessingInstructionType()	Get the value of the attribute 'type' of the process instruction of the last loaded document.
protected org.jdom2.Element	getRoot(java.io.InputStream stream)	Get the root element from an XML document in a stream.
XmlFile.Validate	getValidate()	Whether to verify the DTD of this XML file when read.
void	makeBackupFile(java.lang.String name)	Move original file to a backup.
boolean	makeBackupFile(java.lang.String directory, java.io.File file)	Move original file to backup directory.
static org.jdom2.Document	newDocument(org.jdom2.Element root)	Create the Document object to store a particular root Element, without a DocType DTD (e.g. for using a schema)
static org.jdom2.Document	newDocument(org.jdom2.Element root, java.lang.String dtd)	Create the Document object to store a particular root Element.
(package private) org.jdom2.Document	processInstructions(org.jdom2.Document doc)	Execute the Processing Instructions in the file.
(package private) org.jdom2.Document	processOneInstruction(org.jdom2.ProcessingInstruction p, org.jdom2.Document doc)
void	revertBackupFile(java.lang.String name)	Revert to original file from backup.
org.jdom2.Element	rootFromFile(java.io.File file)	Read a File as XML, and return the root object.
org.jdom2.Element	rootFromInputStream(java.io.InputStream stream)	Read an InputStream as XML, and return the root object.
org.jdom2.Element	rootFromName(java.lang.String name)	Read the contents of an XML file from its filename.
org.jdom2.Element	rootFromURL(java.net.URL url)	Read a URL as XML, and return the root object.
static void	setDefaultDtdLocation(java.lang.String v)
static void	setDefaultValidate(XmlFile.Validate v)
void	setDtdLocation(java.lang.String v)
void	setValidate(XmlFile.Validate v)
static javax.swing.JFileChooser	userFileChooser()	Provide a JFileChooser initialized to the default user location, and with a default filter.
static javax.swing.JFileChooser	userFileChooser(java.lang.String filter, java.lang.String... suffix)	Provide a JFileChooser initialized to the default user location, and with a default filter.
void	writeXML(java.io.File file, org.jdom2.Document doc)	Write a File as XML.
static java.lang.String	xmlDir()	Define the location of XML files within the distribution directory.

Methods inherited from class java.lang.Object

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

Field Detail

xsltLocation

public static final java.lang.String xsltLocation

Define root part of URL for XSLT style page processing instructions.

See the XSLT versioning discussion.

Things that have been tried here:

/xml/XSLT/

(Note leading slash) Works if there's a copy of the xml directory at the root of whatever served the XML file, e.g. the JMRI web site or a local computer running a server. Doesn't work for e.g. yahoo groups files.

http://jmri.org/xml/XSLT/

Works well for files on the JMRI.org web server, but only that.

See Also:

Constant Field Values

defaultDtdLocation

static java.lang.String defaultDtdLocation

dtdLocation

public java.lang.String dtdLocation

Constructor Detail

XmlFile

public XmlFile()

Method Detail

getProcessingInstructionHRef

public java.lang.String getProcessingInstructionHRef()

Get the value of the attribute 'href' of the process instruction of the last loaded document.

Returns:

the value of the attribute 'href' or null

getProcessingInstructionType

public java.lang.String getProcessingInstructionType()

Get the value of the attribute 'type' of the process instruction of the last loaded document.

Returns:

the value of the attribute 'type' or null

rootFromName

public org.jdom2.Element rootFromName(java.lang.String name)
                               throws org.jdom2.JDOMException,
                                      java.io.IOException

Read the contents of an XML file from its filename. The name is expanded by the findFile(java.lang.String) routine. If the file is not found, attempts to read the XML file from a JAR resource.

Parameters:

name - Filename, as needed by findFile(java.lang.String)

Returns:

null if not found, else root element of located file

Throws:

org.jdom2.JDOMException - only when all methods have failed

java.io.FileNotFoundException - if file not found

java.io.IOException - when needed

rootFromFile

public org.jdom2.Element rootFromFile(java.io.File file)
                               throws org.jdom2.JDOMException,
                                      java.io.IOException

Read a File as XML, and return the root object.

Exceptions are only thrown when local recovery is impossible.

Parameters:

file - File to be parsed. A FileNotFoundException is thrown if it doesn't exist.

Returns:

root element from the file. This should never be null, as an exception should be thrown if anything goes wrong.

Throws:

org.jdom2.JDOMException - only when all methods have failed

java.io.FileNotFoundException - if file not found

java.io.IOException - when needed

rootFromInputStream

public org.jdom2.Element rootFromInputStream(java.io.InputStream stream)
                                      throws org.jdom2.JDOMException,
                                             java.io.IOException

Read an InputStream as XML, and return the root object.

Exceptions are only thrown when local recovery is impossible.

Parameters:

stream - InputStream to be parsed.

Returns:

root element from the file. This should never be null, as an exception should be thrown if anything goes wrong.

Throws:

org.jdom2.JDOMException - only when all methods have failed

java.io.FileNotFoundException - if file not found

java.io.IOException - when needed

rootFromURL

public org.jdom2.Element rootFromURL(java.net.URL url)
                              throws org.jdom2.JDOMException,
                                     java.io.IOException

Read a URL as XML, and return the root object.

Exceptions are only thrown when local recovery is impossible.

Parameters:

url - URL locating the data file

Returns:

root element from the file. This should never be null, as an exception should be thrown if anything goes wrong.

Throws:

org.jdom2.JDOMException - only when all methods have failed

java.io.FileNotFoundException - if file not found

java.io.IOException - when needed

getRoot

protected org.jdom2.Element getRoot(java.io.InputStream stream)
                             throws org.jdom2.JDOMException,
                                    java.io.IOException

Get the root element from an XML document in a stream.

Parameters:

stream - input containing the XML document

Returns:

the root element of the XML document

Throws:

org.jdom2.JDOMException - if the XML document is invalid

java.io.IOException - if the input cannot be read

writeXML

public void writeXML(java.io.File file,
                     org.jdom2.Document doc)
              throws java.io.IOException,
                     java.io.FileNotFoundException

Write a File as XML.

Parameters:

file - File to be created.

doc - Document to be written out. This should never be null.

Throws:

java.io.IOException - when an IO error occurs

java.io.FileNotFoundException - if file not found

checkFile

protected boolean checkFile(java.lang.String name)

Check if a file of the given name exists. This uses the same search order as findFile(java.lang.String)

Parameters:

name - file name, either absolute or relative

Returns:

true if the file exists in a searched place

findFile

protected java.io.File findFile(java.lang.String name)

Get a File object for a name. This is here to implement the search rule:

1. Look in user preferences directory, located by FileUtil.getUserFilesPath()
2. Look in current working directory (usually the JMRI distribution directory)
3. Look in program directory, located by FileUtil.getProgramPath()
4. Look in XML directory, located by xmlDir()
5. Check for absolute name.

Parameters:

name - Filename perhaps containing subdirectory information (e.g. "decoders/Mine.xml")

Returns:

null if file found, otherwise the located File

dumpElement

public static void dumpElement(@Nonnull
                               org.jdom2.Element name)

Diagnostic printout of as much as we can find

Parameters:

name - Element to print, should not be null

makeBackupFile

public void makeBackupFile(java.lang.String name)

Move original file to a backup. Use this before writing out a new version of the file.

Parameters:

name - Last part of file pathname i.e. subdir/name, without the pathname for either the xml or preferences directory.

makeBackupFile

public boolean makeBackupFile(java.lang.String directory,
                              java.io.File file)

Move original file to backup directory.

Parameters:

directory - the backup directory to use.

file - the file to be backed up. The file name will have the current date embedded in the backup name.

Returns:

true if successful.

revertBackupFile

public void revertBackupFile(java.lang.String name)

Revert to original file from backup. Use this for testing backup files.

Parameters:

name - Last part of file pathname i.e. subdir/name, without the pathname for either the xml or preferences directory.

backupFileName

public java.lang.String backupFileName(java.lang.String name)

Return the name of a new, unique backup file. This is here so it can be overridden during tests. File to be backed-up must be within the preferences directory tree.

Parameters:

name - Filename without preference path information, e.g. "decoders/Mine.xml".

Returns:

Complete filename, including path information into preferences directory

createFileNameWithDate

public java.lang.String createFileNameWithDate(java.lang.String name)

processInstructions

org.jdom2.Document processInstructions(org.jdom2.Document doc)

Execute the Processing Instructions in the file.

JMRI only knows about certain ones; the others will be ignored.

Parameters:

doc - the document containing processing instructions

Returns:

the processed document

processOneInstruction

org.jdom2.Document processOneInstruction(org.jdom2.ProcessingInstruction p,
                                         org.jdom2.Document doc)
                                  throws org.jdom2.transform.XSLTransformException,
                                         org.jdom2.JDOMException,
                                         java.io.IOException

Throws:

org.jdom2.transform.XSLTransformException

org.jdom2.JDOMException

java.io.IOException

newDocument

public static org.jdom2.Document newDocument(org.jdom2.Element root,
                                             java.lang.String dtd)

Create the Document object to store a particular root Element.

Parameters:

root - Root element of the final document

dtd - name of an external DTD

Returns:

new Document, with root installed

newDocument

public static org.jdom2.Document newDocument(org.jdom2.Element root)

Create the Document object to store a particular root Element, without a DocType DTD (e.g. for using a schema)

Parameters:

root - Root element of the final document

Returns:

new Document, with root installed

addDefaultInfo

public static void addDefaultInfo(org.jdom2.Element root)

Add default information to the XML before writing it out.

Currently, this is identification information as an XML comment. This includes:

• The JMRI version used
• Date of writing
• A CVS id string, in case the file gets checked in or out

It may be necessary to extend this to check whether the info is already present, e.g. if re-writing a file.

Parameters:

root - The root element of the document that will be written.

xmlDir

public static java.lang.String xmlDir()

Define the location of XML files within the distribution directory.

Use FileUtil.getProgramPath() since the current working directory is not guaranteed to be the JMRI distribution directory if jmri.jar is referenced by an external Java application.

Returns:

the XML directory that ships with JMRI.

getDefaultValidate

public static XmlFile.Validate getDefaultValidate()

Whether to, by global default, validate the file being read. Public so it can be set by scripting and for debugging.

Returns:

the default level of validation to apply to a file

setDefaultValidate

public static void setDefaultValidate(XmlFile.Validate v)

getValidate

public XmlFile.Validate getValidate()

Whether to verify the DTD of this XML file when read.

Returns:

the level of validation to apply to a file

setValidate

public void setValidate(XmlFile.Validate v)

getDefaultDtdLocation

public static java.lang.String getDefaultDtdLocation()

Get the default standard location for DTDs in new XML documents. Public so it can be set by scripting and for debug.

Returns:

the default DTD location

setDefaultDtdLocation

public static void setDefaultDtdLocation(java.lang.String v)

getDtdLocation

public java.lang.String getDtdLocation()

Get the location for DTDs in this XML document.

Returns:

the DTD location

setDtdLocation

public void setDtdLocation(java.lang.String v)

userFileChooser

public static javax.swing.JFileChooser userFileChooser(java.lang.String filter,
                                                       java.lang.String... suffix)

Provide a JFileChooser initialized to the default user location, and with a default filter. This filter excludes .zip and .jar archives.

Parameters:

filter - Title for the filter, may not be null

suffix - Allowed file extensions, if empty all extensions are allowed except .zip and .jar; include an empty String to allow files without an extension if specifying other extensions.

Returns:

a file chooser

userFileChooser

public static javax.swing.JFileChooser userFileChooser()

Provide a JFileChooser initialized to the default user location, and with a default filter. This filter excludes .zip and .jar archives.

Returns:

a file chooser

getBuilder

public static org.jdom2.input.SAXBuilder getBuilder(XmlFile.Validate validate)