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

  • Field Details

    • 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:

    • defaultDtdLocation

      static String defaultDtdLocation

    • dtdLocation

      public String dtdLocation

  • Constructor Details

  • Method Details

    • getProcessingInstructionHRef

      public 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 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(String name) throws org.jdom2.JDOMException, 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
      FileNotFoundException - if file not found
      IOException - when needed

    • rootFromFile

      public org.jdom2.Element rootFromFile(File file) throws org.jdom2.JDOMException, 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
      FileNotFoundException - if file not found
      IOException - when needed

    • rootFromInputStream

      public org.jdom2.Element rootFromInputStream(InputStream stream) throws org.jdom2.JDOMException, 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
      FileNotFoundException - if file not found
      IOException - when needed

    • rootFromURL

      public org.jdom2.Element rootFromURL(URL url) throws org.jdom2.JDOMException, 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
      FileNotFoundException - if file not found
      IOException - when needed

    • getRoot

      protected org.jdom2.Element getRoot(InputStream stream) throws org.jdom2.JDOMException, 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
      IOException - if the input cannot be read

    • writeXML

      public void writeXML(File file, org.jdom2.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:
      IOException - when an IO error occurs
      FileNotFoundException - if file not found

    • 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)
      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(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)

    • 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, IOException
      Throws:
      org.jdom2.transform.XSLTransformException
      org.jdom2.JDOMException
      IOException

    • newDocument

      public static org.jdom2.Document newDocument(org.jdom2.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 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 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 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(String v)

    • getDtdLocation

      public String getDtdLocation()
      Get the location for DTDs in this XML document.
      Returns:
      the DTD location

    • setDtdLocation

      public void setDtdLocation(String v)

    • userFileChooser

      public static JFileChooser userFileChooser(String filter, 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 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)