Package jmri.profile

Class Profile

  • All Implemented Interfaces:
    java.lang.Comparable<Profile>
    Direct Known Subclasses:
    NullProfile

    public class Profile
    extends java.lang.Object
    implements java.lang.Comparable<Profile>
    A JMRI application profile. Profiles allow a JMRI application to load completely separate set of preferences at each launch without relying on host OS-specific tricks to ensure this happens. It is recommended that profile directory names end in ".jmri" so that supporting iOS and macOS applications could potentially treat a JMRI profile as a single file, instead of as a directory structure. This would allow an application subject to mandatory security controls in iOS, and an application sandbox on macOS to request permission from the user to access the entire profile once, instead of needing to request permission to access each file individually. This would also allow a profile to be opened by double clicking on it, and to have a unique icon within the iOS Files app and macOS Finder. Note that JMRI itself is not currently capable of supporting opening a profile by double clicking on it, even if other applications on the same computer can.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String CONFIG  
      static java.lang.String CONFIG_FILENAME
      "ProfileConfig.xml" may be present in older profiles
      static java.lang.String EXTENSION
      The filename extension for JMRI profile directories.
      protected static java.lang.String ID  
      protected static java.lang.String NAME  
      protected static java.lang.String PATH  
      static java.lang.String PROFILE  
      static java.lang.String PROPERTIES  
      static java.lang.String SHARED_CONFIG  
      static java.lang.String SHARED_PROPERTIES  
      static java.lang.String SHARED_UI_CONFIG  
      static java.lang.String UI_CONFIG  
      static java.lang.String UI_CONFIG_FILENAME
      "UserPrefsProfileConfig.xml" may be present in older profiles
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        Profile​(java.io.File path)
      Create a Profile object given just a path to it.
      protected Profile​(java.io.File path, boolean isReadable)
      Create a Profile object given just a path to it.
      protected Profile​(java.io.File path, java.lang.String id, boolean isReadable)
      Create a Profile object given just a path to it.
        Profile​(java.lang.String name, java.lang.String id, java.io.File path)
      Create a Profile object and a profile in storage.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int compareTo​(Profile o)  
      static boolean containsProfile​(java.io.File path)
      Test if the given path or subdirectories contains a Profile.
      boolean equals​(java.lang.Object obj)
      This tests for equal ID values
      java.lang.String getId()  
      java.lang.String getName()  
      java.io.File getPath()  
      java.lang.String getUniqueId()
      Return the uniqueness portion of the Profile Id.
      int hashCode()  
      static boolean inProfile​(java.io.File path)
      Test if the given path is within a directory that is a Profile.
      boolean isComplete()
      Test if the profile is complete.
      static boolean isProfile​(java.io.File path)
      Test if the given path is a Profile.
      protected void save()  
      void setName​(java.lang.String name)
      Set the name for this profile.
      protected void setNameInConstructor​(java.lang.String name)
      Set the name for this profile while constructing the profile.
      java.lang.String toString()  
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • Profile

        public Profile​(@Nonnull
                       java.io.File path)
                throws java.io.IOException
        Create a Profile object given just a path to it. The Profile must exist in storage on the computer.
        Parameters:
        path - The Profile's directory
        Throws:
        java.io.IOException - If unable to read the Profile from path
      • Profile

        public Profile​(@Nonnull
                       java.lang.String name,
                       @Nonnull
                       java.lang.String id,
                       @Nonnull
                       java.io.File path)
                throws java.io.IOException
        Create a Profile object and a profile in storage. A Profile cannot exist in storage on the computer at the path given. Since this is a new profile, the id must match the last element in the path.

        This is the only time the id can be set on a Profile, as the id becomes a read-only property of the Profile. The ProfileManager will only load a single profile with a given id.

        Parameters:
        name - Name of the profile. Will not be used to enforce uniqueness constraints.
        id - Id of the profile. Will be prepended to a random String to enforce uniqueness constraints.
        path - Location to store the profile; ".jmri" will be appended to this path if needed.
        Throws:
        java.io.IOException - If unable to create the profile at path
        java.lang.IllegalArgumentException - If a profile already exists at or within path
      • Profile

        protected Profile​(@Nonnull
                          java.io.File path,
                          boolean isReadable)
                   throws java.io.IOException
        Create a Profile object given just a path to it. If isReadable is true, the Profile must exist in storage on the computer. Generates a random id for the profile.

        This method exists purely to support subclasses.

        Parameters:
        path - The Profile's directory
        isReadable - True if the profile has storage. See NullProfile for a Profile subclass where this is not true.
        Throws:
        java.io.IOException - If the profile's preferences cannot be read.
      • Profile

        protected Profile​(@Nonnull
                          java.io.File path,
                          @Nonnull
                          java.lang.String id,
                          boolean isReadable)
                   throws java.io.IOException
        Create a Profile object given just a path to it. If isReadable is true, the Profile must exist in storage on the computer.

        This method exists purely to support subclasses.

        Parameters:
        path - The Profile's directory
        id - The Profile's id
        isReadable - True if the profile has storage. See NullProfile for a Profile subclass where this is not true.
        Throws:
        java.io.IOException - If the profile's preferences cannot be read.
    • Method Detail

      • save

        protected final void save()
      • getName

        public java.lang.String getName()
        Returns:
        the name
      • setName

        public void setName​(java.lang.String name)
        Set the name for this profile.

        Overriding classing must use setNameInConstructor(java.lang.String) to set the name in a constructor since this method passes this Profile object to an object excepting a completely constructed Profile.

        Parameters:
        name - the new name
      • setNameInConstructor

        protected final void setNameInConstructor​(java.lang.String name)
        Set the name for this profile while constructing the profile.

        Overriding classing must use this method to set the name in a constructor since setName(java.lang.String) passes this Profile object to an object expecting a completely constructed Profile.

        Parameters:
        name - the new name
      • getId

        @Nonnull
        public java.lang.String getId()
        Returns:
        the id
      • getPath

        public java.io.File getPath()
        Returns:
        the path
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • equals

        public boolean equals​(java.lang.Object obj)
        This tests for equal ID values
        Overrides:
        equals in class java.lang.Object
      • isComplete

        public boolean isComplete()
        Test if the profile is complete. A profile is considered complete if it can be instantiated using Profile(java.io.File) and has a profile.properties file within its "profile" directory.
        Returns:
        true if profile.properties exists where expected.
      • getUniqueId

        public java.lang.String getUniqueId()
        Return the uniqueness portion of the Profile Id.

        This portion of the Id is automatically generated when the profile is created.

        Returns:
        An eight-character String of alphanumeric characters.
      • containsProfile

        public static boolean containsProfile​(java.io.File path)
        Test if the given path or subdirectories contains a Profile.
        Parameters:
        path - Path to test.
        Returns:
        true if path or subdirectories contains a Profile.
        Since:
        3.9.4
      • inProfile

        public static boolean inProfile​(java.io.File path)
        Test if the given path is within a directory that is a Profile.
        Parameters:
        path - Path to test.
        Returns:
        true if path or parent directories is a Profile.
        Since:
        3.9.4
      • isProfile

        public static boolean isProfile​(java.io.File path)
        Test if the given path is a Profile.
        Parameters:
        path - Path to test.
        Returns:
        true if path is a Profile.
        Since:
        3.9.4
      • compareTo

        public int compareTo​(Profile o)
        Specified by:
        compareTo in interface java.lang.Comparable<Profile>