Package jmri.configurexml

Class ConfigXmlManager

java.lang.Object
jmri.jmrit.XmlFile
jmri.configurexml.ConfigXmlManager
All Implemented Interfaces:
ConfigureManager
public class ConfigXmlManager extends XmlFile implements ConfigureManager
Provides the mechanisms for storing an entire layout configuration to XML. "Layout" refers to the hardware: Specific communication systems, etc.
See Also:

  • Field Details

  • Constructor Details

  • Method Details

    • registerConfig

      public void registerConfig(Object o)
      Specified by:
      registerConfig in interface ConfigureManager

    • registerPref

      public void registerPref(Object o)
      Specified by:
      registerPref in interface ConfigureManager

    • confirmAdapterAvailable

      void confirmAdapterAvailable(Object o)
      Common check routine to confirm an adapter is available as part of registration process.

      Note: Should only be called for debugging purposes, for example, when Log4J DEBUG level is selected, to load fewer classes at startup.

      Parameters:
      o - object to confirm XML adapter exists for

    • currentClassName

      public static String currentClassName(String name)
      Handles ConfigureXml classes that have moved to a new package or been superseded.
      Parameters:
      name - name of the moved or superceded ConfigureXml class
      Returns:
      name of the ConfigureXml class in newer package or of superseding class

    • removePrefItems

      public void removePrefItems()
      Specified by:
      removePrefItems in interface ConfigureManager

    • findInstance

      public Object findInstance(Class<?> c, int index)
      Find the ith instance of an object of particular class that's been registered for storage.

      Note that the index of an object can change when other objects are stored or removed. The index is for indexing over the objects stored at a moment, not for use as an identification number.

      There may be synchronization issues associated with this, although they are expected to be rare in practice.

      Specified by:
      findInstance in interface ConfigureManager
      Parameters:
      c - Class of the desired objects
      index - a 1-based index of the object to return
      Returns:
      an object of class c or null

    • getInstanceList

      public List<Object> getInstanceList(Class<?> c)
      Returns a list of instances stored for a given class.
      Specified by:
      getInstanceList in interface ConfigureManager
      Parameters:
      c - Class of the desired objects
      Returns:
      an List of objects of class c or null

    • registerConfig

      public void registerConfig(Object o, int x)
      Specified by:
      registerConfig in interface ConfigureManager

    • registerTool

      public void registerTool(Object o)
      Specified by:
      registerTool in interface ConfigureManager

    • registerUser

      public void registerUser(Object o)
      Register an object whose state is to be tracked. It is not an error if the original object was already registered.
      Specified by:
      registerUser in interface ConfigureManager
      Parameters:
      o - The object, which must have an associated adapter class.

    • registerUserPrefs

      public void registerUserPrefs(Object o)
      Specified by:
      registerUserPrefs in interface ConfigureManager

    • deregister

      public void deregister(Object o)
      Specified by:
      deregister in interface ConfigureManager

    • adapterName

      public static String adapterName(Object o)
      Find the name of the adapter class for an object.
      Parameters:
      o - object of a configurable type
      Returns:
      class name of adapter

    • locateClassFailed

      void locateClassFailed(Throwable ex, String adapterName, Object o)
      Handle failure to load adapter class. Although only a one-liner in this class, it is a separate member to facilitate testing.
      Parameters:
      ex - the exception throw failing to load adapterName as o
      adapterName - name of the adapter class
      o - adapter object

    • initStore

      protected org.jdom2.Element initStore()

    • addPrefsStore

      protected void addPrefsStore(org.jdom2.Element root)

    • addConfigStore

      protected boolean addConfigStore(org.jdom2.Element root)

    • addToolsStore

      protected boolean addToolsStore(org.jdom2.Element root)

    • addUserStore

      protected boolean addUserStore(org.jdom2.Element root)

    • addUserPrefsStore

      protected void addUserPrefsStore(org.jdom2.Element root)

    • includeHistory

      protected void includeHistory(org.jdom2.Element root, File file)

    • finalStore

      protected boolean finalStore(org.jdom2.Element root, File file)

    • storePrefs

      public void storePrefs()
      Stores just preferences information.

      Where that information is stored is implementation-specific.

      Specified by:
      storePrefs in interface ConfigureManager

    • storePrefs

      public void storePrefs(File file)
      Stores just preferences information.
      Specified by:
      storePrefs in interface ConfigureManager
      Parameters:
      file - the to store preferences into

    • storeUserPrefs

      public void storeUserPrefs(File file)
      Stores just user preferences information.
      Specified by:
      storeUserPrefs in interface ConfigureManager
      Parameters:
      file - the file to store user preferences into

    • setPrefsLocation

      public void setPrefsLocation(File prefsFile)
      Set location for preferences file.

      File need not exist, but location must be writable when storePrefs() called.

      Parameters:
      prefsFile - new location for preferences file

    • storeConfig

      public boolean storeConfig(File file)
      Stores just configuration information.
      Specified by:
      storeConfig in interface ConfigureManager
      Parameters:
      file - Output file
      Returns:
      true if successful; false otherwise

    • storeUser

      public boolean storeUser(File file)
      Stores user and config information.
      Specified by:
      storeUser in interface ConfigureManager
      Parameters:
      file - Output file
      Returns:
      true if succeeded

    • makeBackup

      public boolean makeBackup(File file)
      Make a backup file.
      Specified by:
      makeBackup in interface ConfigureManager
      Parameters:
      file - to be backed up
      Returns:
      true if successful

    • elementFromObject

      public static org.jdom2.Element elementFromObject(Object o)
      Parameters:
      o - The object to get an XML representation of
      Returns:
      An XML element representing o

    • elementFromObject

      public static org.jdom2.Element elementFromObject(Object object, boolean shared)
      Parameters:
      object - The object to get an XML representation of
      shared - true if the XML should be shared, false if the XML should be per-node
      Returns:
      An XML element representing object

    • load

      public boolean load(File fi) throws JmriConfigureXmlException
      Load a file.

      Handles problems locally to the extent that it can, by routing them to the creationErrorEncountered method.

      Specified by:
      load in interface ConfigureManager
      Parameters:
      fi - file to load
      Returns:
      true if no problems during the load
      Throws:
      JmriConfigureXmlException - if unable to load file

    • load

      public boolean load(URL url) throws JmriConfigureXmlException
      Create the objects defined in a particular configuration file
      Specified by:
      load in interface ConfigureManager
      Parameters:
      url - Input URL
      Returns:
      true if succeeded
      Throws:
      JmriConfigureXmlException

    • load

      public boolean load(File fi, boolean registerDeferred) throws JmriConfigureXmlException
      Load a file.

      Handles problems locally to the extent that it can, by routing them to the creationErrorEncountered method.

      Specified by:
      load in interface ConfigureManager
      Parameters:
      fi - file to load
      registerDeferred - true to register objects to defer
      Returns:
      true if no problems during the load
      Throws:
      JmriConfigureXmlException - if problem during load
      Since:
      2.11.2
      See Also:

    • load

      public boolean load(URL url, boolean registerDeferred) throws JmriConfigureXmlException
      Load a file.

      Handles problems locally to the extent that it can, by routing them to the creationErrorEncountered method.

      Always processes on Swing thread

      Specified by:
      load in interface ConfigureManager
      Parameters:
      url - URL of file to load
      registerDeferred - true to register objects to defer
      Returns:
      true if no problems during the load
      Throws:
      JmriConfigureXmlException - if problem during load
      Since:
      3.3.2
      See Also:

    • setValidate

      public void setValidate(XmlFile.Validate v)
      Control the scope of validation of XML files when loading.
      Specified by:
      setValidate in interface ConfigureManager
      Overrides:
      setValidate in class XmlFile
      Parameters:
      v - the validation scope

    • getValidate

      public XmlFile.Validate getValidate()
      Whether to verify the DTD of this XML file when read.
      Specified by:
      getValidate in interface ConfigureManager
      Overrides:
      getValidate in class XmlFile
      Returns:
      the level of validation to apply to a file

    • loadDeferred

      public boolean loadDeferred(File fi)
      Create the objects defined in a particular configuration file that have been deferred until after basic GUI construction completed
      Specified by:
      loadDeferred in interface ConfigureManager
      Parameters:
      fi - Input file
      Returns:
      true if succeeded
      See Also:

    • loadDeferred

      public boolean loadDeferred(URL url)
      Create the objects defined in a particular configuration file that have been deferred until after basic GUI construction completed
      Specified by:
      loadDeferred in interface ConfigureManager
      Parameters:
      url - Input URL
      Returns:
      true if succeeded
      See Also:

    • find

      public URL find(String f)
      Find a file by looking
      • in xml/layout/ in the preferences directory, if that exists
      • in xml/layout/ in the application directory, if that exists
      • in xml/ in the preferences directory, if that exists
      • in xml/ in the application directory, if that exists
      • at top level in the application directory
      Specified by:
      find in interface ConfigureManager
      Parameters:
      f - Local filename, perhaps without path information
      Returns:
      Corresponding File object

    • locateFileFailed

      void locateFileFailed(String f)
      Report a failure to find a file. This is a separate member to ease testing.
      Parameters:
      f - Name of file not located.

    • creationErrorEncountered

      public static void creationErrorEncountered(XmlAdapter adapter, String operation, String description, String systemName, String userName, Throwable exception)
      Invoke common handling of errors that happen during the "load" process.

      Exceptions passed into this are absorbed.

      Parameters:
      adapter - Object that encountered the error (for reporting), may be null
      operation - description of the operation being attempted, may be null
      description - description of error encountered
      systemName - System name of bean being handled, may be null
      userName - used name of the bean being handled, may be null
      exception - Any exception being handled in the processing, may be null

    • storingErrorEncountered

      public static void storingErrorEncountered(XmlAdapter adapter, String operation, String description, String systemName, String userName, Throwable exception)
      Invoke common handling of errors that happen during the "store" process.

      Exceptions passed into this are absorbed.

      Parameters:
      adapter - Object that encountered the error (for reporting), may be null
      operation - description of the operation being attempted, may be null
      description - description of error encountered
      systemName - System name of bean being handled, may be null
      userName - used name of the bean being handled, may be null
      exception - Any exception being handled in the processing, may be null

    • setErrorHandler

      public static void setErrorHandler(ErrorHandler handler)

    • getLoadDeferredList

      protected List<org.jdom2.Element> getLoadDeferredList()
      Returns:
      the loadDeferredList