jmri.jmrit
Class XmlFile

java.lang.Object
  jmri.jmrit.XmlFile

Direct Known Subclasses:

AbstractMiniServerPreferences.AbstractMiniServerPreferencesXml, AbstractWiThrottlePreferences.AbstractWiThrottlePreferencesXml, Backup, BlockValueFile, ConfigXmlManager, ConsistFile, DecoderFile, DecoderIndexFile, DefaultCatalogTreeManagerXml, DefaultUserMessagePreferences, ExportCars, ExportEngines, NameFile, NceConsistRoster, OperationsXml, OptionsFile, PollingFile, PositionFile, RollingStockLogger, Roster, TrainInfoFile, TrainLogger, 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(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.
String	createFileNameWithDate(String name)
static void	dumpElement(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.
static SAXBuilder	getBuilder(boolean verify)
protected Element	getRootViaURI(boolean verify, InputStream stream) Find the DTD via a URI and get the root element.
static boolean	getVerify()
void	makeBackupFile(String name) Move original file to a backup.
boolean	makeBackupFile(String directory, File file) Move original file to backup directory.
static Document	newDocument(Element root) Create the Document object to store a particular root Element, without a DocType DTD (e.g. for using a schema)
static Document	newDocument(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(String name, Exception e)
protected void	reportError2(String name, Exception e)
static String	resourcesDir()
void	revertBackupFile(String name) Revert to original file from backup.
Element	rootFromFile(File file) Read a File as XML, and return the root object.
Element	rootFromName(String name) Read the contents of an XML file from its filename.
Element	rootFromURL(URL url) Read a URL as XML, and return the root object.
static String	scriptsDir()
static void	setScriptsFileLocationDefault(String scriptDir) Provide default initial location for JFileChoosers to user files
static void	setUserFileLocationDefault(String userDir)
static void	setVerify(boolean v)
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, 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.

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

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 Element rootFromName(String name)
                     throws 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:

JDOMException

FileNotFoundException

IOException

rootFromFile

public Element rootFromFile(File file)
                     throws 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:

JDOMException - only when all methods have failed

FileNotFoundException

IOException

rootFromURL

public Element rootFromURL(URL url)
                    throws JDOMException,
                           IOException

Read a URL 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:

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:

JDOMException - only when all methods have failed

FileNotFoundException

IOException

reportError1

protected void reportError1(String name,
                            Exception e)

reportError2

protected void reportError2(String name,
                            Exception e)

getRootViaURI

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

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

Throws:

JDOMException

IOException

writeXML

public void writeXML(File file,
                     Document doc)
              throws 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:

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(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.

makeBackupFile

public boolean makeBackupFile(String directory,
                              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(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

createFileNameWithDate

public String createFileNameWithDate(String name)

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 Document newDocument(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

newDocument

public static Document newDocument(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(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.

setUserFileLocationDefault

public static void setUserFileLocationDefault(String userDir)

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

resourcesDir

public static String resourcesDir()

getVerify

public static boolean getVerify()

setVerify

public static void setVerify(boolean v)

userFileLocationDefault

public static String userFileLocationDefault()

Provide default initial location for JFileChoosers to user files

scriptsDir

public static String scriptsDir()

setScriptsFileLocationDefault

public static void setScriptsFileLocationDefault(String scriptDir)

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)

getBuilder

public static SAXBuilder getBuilder(boolean verify)