Package com.isode.dsapi.profile

Class IsodeBindProfiles

java.lang.Object
com.isode.dsapi.profile.IsodeBindProfiles
public class IsodeBindProfiles extends Object
This class contains definitions and methods to allow applications to access the "isode-wide" bind profile file. This file replaces the "sodium-bindprofile.xml" file which was previously used by Sodium and other applications.

Applications should use loadIsodeBindProfiles(String, PostUpgradeCallback) to get a reference to the Isode bindprofile file. The class can work with an existing sodium bindprofile file if necessary, so that it is possible to cater for situations where customers are not yet ready to move away from the sodium bindprofile setup (e.g. if they're sharing the file with older versions of Isode).

Since:
14.6

  • Field Details

    • localPathsErrors

      public static final String localPathsErrors
      This variable contains a String with information about any error that has occurred when attempting to derive platform-specific pathnames. If no errors have occurred it will be null.

  • Constructor Details

    • IsodeBindProfiles

      public IsodeBindProfiles()

  • Method Details

    • loadIsodeBindProfiles

      public static BindProfileList loadIsodeBindProfiles(String bindProfilePassphrase, IsodeBindProfiles.PostUpgradeCallback postUpgradeCallback) throws EncryptionException, SAXException, IOException
      Open the Isode bind profiles file, upgrading from an old Sodium bindprofiles file if necessary. Loading a bindProfileList is allowed only once (except in test mode) and any attempt to load it again will throw a RuntimeException unless it has been unloaded using the method unloadIsodeBindProfiles().

      Therefore, loading of BindprofileList should be done only once and if it needs to be reloaded then it should be unloaded before by calling unloadIsodeBindProfiles(). If this function is called multiple times, it should be called as follows: 

          if (getBindProfileList() == null) {
        loadIsodeBindProfiles(...);
    }

      The method does the following:

      1. if the BindProfileList has already been populated, throw a RuntimeException - done.
      2. if "current" version of profiles files exists, load it and return reference - done.
      3. check if any of the older versions of profile files exist. If not, create a new empty file of the "current" version, load it and return reference - done
      4. find the most recent "previous" version of a bind profile file, and create a new "current" file by upgrading that one, after which the old one is renamed
      5. if postUpgradeCallback is non-null, call it so user can be informed of what's happened
      6. return a reference to the upgraded file
      7. done
      Parameters:
      bindProfilePassphrase - the passphrase to be used to protect the file. This should be specified as null only if the existing file is not passphrase protected, and/or the new file to be created is not to be passphrase protected.
      postUpgradeCallback - a PostUpgradeCallback object which can be told about an upgrade (if one happened). This may be null.
      Returns:
      a reference to either sodium-bindprofiles or isode-bindprofiles, will never be null
      Throws:
      EncryptionException - if bindProfilePassphrase is the wrong passphrase.
      SAXException - if an error occurs when attempting to parse the contents of a bind profile file. The exception text will contain the name of the file which caused the problem.
      IOException - if an error occurred when attempting to create a new isode-bindprofiles file, or if it is not possible to locate the Isode directory. The exception text will contain the name of the file, and information about whether it was trying to create a new file or upgrade it from an old one. If it was an upgrade that failed, then the old sodium file will be left unchanged.
      See Also:

    • loadIsodeBindProfiles

      public static BindProfileList loadIsodeBindProfiles() throws IOException, SAXException
      Open the Isode bind profiles file in read-only mode, without decrypting any passwords. No upgrade from "old" BindProfile file versions will be done. Loading a bindProfileList is allowed only once (except in test mode) and any attempt to load it again will throw a RuntimeException unless it has been unloaded using the method unloadIsodeBindProfiles().

      Therefore , loading of BindprofileList should be done only once and if it needs to be reloaded then it should be unloaded before by calling unloadIsodeBindProfiles(). If this function is called multiple times, it should be called as follows: 

          if (getBindProfileList() == null) {
        loadIsodeBindProfiles(...);
    }

      The method does the following:

      1. if the BindProfileList has already been populated, throw a RuntimeException - done.
      2. if "current" version of profiles files exists, load it and return reference - done.
      3. check if any of the older versions of profile files exist. If so, open the "most recent" one and return reference - done
      4. return null - done.
      Returns:
      a reference to the most recent profile file version, or null if none exists.
      Throws:
      IOException - if it is not possible to locate the Isode directory.
      SAXException - if an error occurs when attempting to parse the contents of a bind profile file. The exception text will contain the name of the file which caused the problem.
      See Also:

    • setTestingMode

      public static void setTestingMode()
      This method is for testing only. It provides a way for the unit-tests to test the functionality of the class without requiring that "real" bind profile files exist. Calling this method sets the testingMode flag, which means that every filename that the class uses will have a suffix of "-test" added to it.

      E.g. instead of /home/nh/.isode/isode-bindprofiles.xml it will use /home/nh/.isode/isode-bindprofiles.xml-test

      This method always throws a UnsupportedOperationException, which should be caught by test code, but should cause any other application to break.

    • getIsodeBindProfileFilename

      public static String getIsodeBindProfileFilename()
      Return the file path and name of the "current" isode-bindprofiles file
      Returns:
      the filename for "current" (i.e. most recent version) of the isode-bindprofiles file

    • getProfileFilenames

      public static String[] getProfileFilenames()
      Returns an array of the filenames that have been used for bind profiles, with the "current" filename as the first element of the list, and successively older versions in subsequent positions. The Strings in the array are correctly adjusted in the case of a "test" environment

      This method is intended to be used by unit testing code.

      Returns:
      an array of filenames
      Since:
      15.0

    • getCurrentBindProfileFilename

      public static String getCurrentBindProfileFilename()
      Returns the file path and name of whatever file will currently exists which contains bind profiles.

      This provides a way to find out which file would be read if you use loadIsodeBindProfiles(String, PostUpgradeCallback)

      The value returned will be determined as follows:

      1. if the "current" file exists, return its name - done.
      2. if any of the "older" files exist, return the most recent one - done.
      3. return null
      Returns:
      the filename for the currently existing bindprofiles, or null if there isn't one

    • getArchivedBindProfileFilename

      public static String getArchivedBindProfileFilename()
      If a bindprofilefile is "upgraded", then the old file is "archived". This method returns the name of the archive file, in the event that an upgrade has occurred
      Returns:
      the name of the archived file, or null if no upgrade has occurred.
      Since:
      15.0

    • getBindProfileList

      public static BindProfileList getBindProfileList()
      Get the Bind Profile List that has been loaded
      Returns:
      bind profile list or null if there is none or the functions loadIsodeBindProfiles(String, PostUpgradeCallback) or loadIsodeBindProfiles() have not been called to populate it or if there was an error while loading the BindProfileList
      Since:
      14.6

    • unloadIsodeBindProfiles

      public static void unloadIsodeBindProfiles()
      Discard any existing reference to the Isode Bind Profile List. This method may be used if a caller has previously used loadIsodeBindProfiles(String, PostUpgradeCallback) or loadIsodeBindProfiles() to load the bind profiles, but there is a risk that another application has accessed or updated the file in the meantime. Calling this method drops the reference to the file without making any changes to it, and allows the caller to re-load the file by calling loadIsodeBindProfiles() or loadIsodeBindProfiles(String, PostUpgradeCallback) again.
      Since:
      14.6