Package jmri.jmrit

Class XmlFile

    • 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 find
      protected 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 an InputStream 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.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • 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

      • 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 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
        java.io.FileNotFoundException - if file not found
        java.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 failed
        java.io.FileNotFoundException - if file not found
        java.io.IOException
      • rootFromInputStream

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