jmri.jmrit
Class XmlFile

java.lang.Object
  jmri.jmrit.XmlFile

Direct Known Subclasses:

BlockValueFile, CarManagerXml, ConfigXmlManager, DecoderFile, DecoderIndexFile, EngineManagerXml, LocationManagerXml, NameFile, NceConsistRoster, OperationsXml, PollingFile, PositionFile, Roster, RouteManagerXml, TrainManagerXml, XmlConfig

public abstract class XmlFile
extends Object

Handle common aspects of XML files.

JMRI needs to be able to operate offline, so it needs to store DTDs locally. At the same time, we want XML files to be transportable, and to have their DTDs 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 DTD for that to work.

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

Author:

Bob Jacobsen Copyright (C) 2001, 2002, 2007

Field Summary

static String	dtdLocation Specify a standard prefix for DTDs in new XML documents
static String	xsltLocation Define root part of URL for XSLT style page processing instructions.

Constructor Summary

XmlFile()

Method Summary

static void	addDefaultInfo(org.jdom.Element root) Add default information to the XML before writing it out.
String	backupFileName(String name) Return the name of a new, unique backup file.
protected boolean	checkFile(String name) Check if a file of the given name exists.
static void	dumpElement(org.jdom.Element name) Diagnostic printout of as much as we can find
static void	ensurePrefsPresent(String name) Ensure that a subdirectory is present; if not, create it.
protected File	findFile(String name) Return a File object for a name.
protected org.jdom.Element	getRootViaURI(boolean verify, InputStream stream) Find the DTD via a URI and get the root element.
void	makeBackupFile(String name) Move original file to a backup.
static org.jdom.Document	newDocument(org.jdom.Element root, String dtd) Create the Document object to store a particular root Element.
static String	prefsDir() Define the location of the preferences directory.
protected void	reportError1(File file, Exception e)
protected void	reportError2(File file, Exception e)
void	revertBackupFile(String name) Revert to original file from backup.
org.jdom.Element	rootFromFile(File file) Read a File as XML, and return the root object.
org.jdom.Element	rootFromName(String name) Read the contents of an XML file from its filename.
static JFileChooser	userFileChooser()
static JFileChooser	userFileChooser(String filter)
static JFileChooser	userFileChooser(String filter, String suffix1)
static JFileChooser	userFileChooser(String filter, String suffix1, String suffix2) Provide a JFileChooser initialized to the default user location, and with a default filter.
static String	userFileLocationDefault() Provide default initial location for JFileChoosers to user files
void	writeXML(File file, org.jdom.Document doc) Write a File as XML.
static 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 String xsltLocation

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

See the XSLT versioning discussion

See Also:

Constant Field Values

dtdLocation

public static final String dtdLocation

Specify a standard prefix for DTDs in new XML documents

See Also:

Constant Field Values

Constructor Detail

XmlFile

public XmlFile()

Method Detail

rootFromName

public org.jdom.Element rootFromName(String name)
                              throws org.jdom.JDOMException,
                                     IOException

Read the contents of an XML file from its filename. The name is expanded by the findFile(java.lang.String) routine.

Parameters:

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

Returns:

null if not found, else root element of located file

Throws:

org.jdom.JDOMException

FileNotFoundException

IOException

rootFromFile

public org.jdom.Element rootFromFile(File file)
                              throws org.jdom.JDOMException,
                                     IOException

Read a File as XML, and return the root object. Multiple methods are tried to locate the DTD needed to do this. 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.jdom.JDOMException - only when all methods have failed

FileNotFoundException

IOException

reportError1

protected void reportError1(File file,
                            Exception e)

reportError2

protected void reportError2(File file,
                            Exception e)

getRootViaURI

protected org.jdom.Element getRootViaURI(boolean verify,
                                         InputStream stream)
                                  throws org.jdom.JDOMException,
                                         IOException

Find the DTD via a URI and get the root element.

Throws:

org.jdom.JDOMException

IOException

writeXML

public void writeXML(File file,
                     org.jdom.Document doc)
              throws org.jdom.JDOMException,
                     IOException,
                     FileNotFoundException

Write a File as XML.

Parameters:

file - File to be created.

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

Throws:

org.jdom.JDOMException

FileNotFoundException

IOException

checkFile

protected boolean checkFile(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 File findFile(String name)

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

1. Check for absolute name.
2. If not found look in user preferences directory, located by prefsDir()
3. If still not found, look in distribution directory, located by xmlDir()

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(org.jdom.Element name)

Diagnostic printout of as much as we can find

Parameters:

name - Element to print, should not be null

makeBackupFile

public void makeBackupFile(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.

revertBackupFile

public void revertBackupFile(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 String backupFileName(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

ensurePrefsPresent

public static void ensurePrefsPresent(String name)

Ensure that a subdirectory is present; if not, create it.

Parameters:

name - Complete pathname of directory to be checked/created.

newDocument

public static org.jdom.Document newDocument(org.jdom.Element root,
                                            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

addDefaultInfo

public static void addDefaultInfo(org.jdom.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 String xmlDir()

Define the location of XML files within the distribution directory.

Because the programs runtime working directory is also the distribution directory, we just use a relative file name.

prefsDir

public static String prefsDir()

Define the location of the preferences directory. This is system-specific ( "{user.home}" is used to represent the directory pointed to by the user.home system property):

If the system property jmri.prefsdir is present, it's used as a path name

Linux

{user.home}/.jmri/

Windows

{user.home}\JMRI

MacOS "Classic"

{user.home}:JMRI

MacOS X

{user.home}/Library/Preferences/JMRI

Other

In the JMRI folder/directory in the folder/directory referenced by {user.home}

Returns:

Pathname in local form, with a terminating separator

userFileLocationDefault

public static String userFileLocationDefault()

Provide default initial location for JFileChoosers to user files

userFileChooser

public static JFileChooser userFileChooser(String filter,
                                           String suffix1,
                                           String suffix2)

Provide a JFileChooser initialized to the default user location, and with a default filter.

Parameters:

filter - Title for the filter, may not be null

suffix1 - An allowed suffix, or null

suffix2 - A second allowed suffix, or null. If both arguments are null, no specific filtering is done.

userFileChooser

public static JFileChooser userFileChooser()

userFileChooser

public static JFileChooser userFileChooser(String filter)

userFileChooser

public static JFileChooser userFileChooser(String filter,
                                           String suffix1)