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
,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
All Methods Static Methods Instance Methods Concrete Methods 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 findprotected 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 anInputStream
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.
-
-
-
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 thefindFile(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 byfindFile(java.lang.String)
- Returns:
- null if not found, else root element of located file
- Throws:
org.jdom2.JDOMException
- only when all methods have failedjava.io.FileNotFoundException
- if file not foundjava.io.IOException
-
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 failedjava.io.FileNotFoundException
- if file not foundjava.io.IOException
-
rootFromInputStream
public org.jdom2.Element rootFromInputStream(java.io.InputStream stream) throws org.jdom2.JDOMException, java.io.IOException
Read anInputStream
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 failedjava.io.FileNotFoundException
- if file not foundjava.io.IOException
-
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 failedjava.io.FileNotFoundException
- if file not foundjava.io.IOException
-
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 invalidjava.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.FileNotFoundException
- if file not foundjava.io.IOException
-
checkFile
protected boolean checkFile(java.lang.String name)
Check if a file of the given name exists. This uses the same search order asfindFile(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:- Look in user preferences directory, located by
FileUtil.getUserFilesPath()
- Look in current working directory (usually the JMRI distribution directory)
- Look in program directory, located by
FileUtil.getProgramPath()
- Look in XML directory, located by
xmlDir()
- 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
- Look in user preferences directory, located by
-
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 documentdtd
- 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 nullsuffix
- 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)
-
-