Package jmri.jmrit

Class XmlFile

    • 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
    • Constructor Detail

    • Method Detail

      • rootFromName

        public Element rootFromName​(java.lang.String name)
                             throws 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:
        JDOMException - only when all methods have failed
        java.io.FileNotFoundException - if file not found
        java.io.IOException
      • rootFromFile

        public Element rootFromFile​(java.io.File file)
                             throws 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:
        JDOMException - only when all methods have failed
        java.io.FileNotFoundException - if file not found
        java.io.IOException
      • rootFromInputStream

        public Element rootFromInputStream​(java.io.InputStream stream)
                                    throws 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:
        JDOMException - only when all methods have failed
        java.io.FileNotFoundException - if file not found
        java.io.IOException
      • rootFromURL

        public Element rootFromURL​(java.net.URL url)
                            throws 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:
        JDOMException - only when all methods have failed
        java.io.FileNotFoundException - if file not found
        java.io.IOException
      • getRoot

        protected Element getRoot​(java.io.InputStream stream)
                           throws 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:
        JDOMException - if the XML document is invalid
        java.io.IOException - if the input cannot be read
      • writeXML

        public void writeXML​(java.io.File file,
                             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 found
        java.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 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
                                       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
      • processInstructions

        Document processInstructions​(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
      • newDocument

        public static Document newDocument​(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 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 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
      • 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
      • 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
      • getDtdLocation

        public java.lang.String getDtdLocation()
        Get the location for DTDs in this XML document.
        Returns:
        the DTD location
      • 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