Package com.isode.dsapi.config

Class FailoverGroups

java.lang.Object
com.isode.dsapi.config.FailoverGroups
public class FailoverGroups extends Object
FailoverGroups is a class which keeps track of all application-wide information which has been discovered about failover DSAs.

This information may come from the DSAs themselves ("hard") or from local saved information ("soft") such as information read from preferences when the UI starts so that it can have some bootstrap knowledge of which groups exist, without having to connect to DSAs to find out.

Note that DSAs may report inconsistent information. E.g. two different DSAs might both claim to be the master of the same group. Or two different DSAs might say they're in the same group, but report different member lists for that group.

So a piece of information is assigned a value, depending on various factors, so that in the case of conflicting information a choice can be made about which one to use (e.g. when a "master" reports one thing and a "mirror" something else.

"Hard" information always trumps "soft": once "hard" information about a certain group appears, then any "soft" information about that group is thrown away. For example, assuming the preferences have info about groups A and B, then this information will be held by FailoverGroups until a DSA is contacted that knows about either group A or B, at which time all the "soft" info for that group will be removed in favour of whatever the DSA reports.

  • Constructor Details

    • FailoverGroups

      public FailoverGroups()

  • Method Details

    • resetGroups

      public static void resetGroups()
      Clear all accumulated information about failover groups. This is used during unit testing but may also be performed if an application has reason to believe that existing data is stale and needs to be thrown away.

    • isEmpty

      public static boolean isEmpty()
      Determine whether there is any failover information at all yet.
      Returns:
      true if there is no failover information at all (as will be the case after a call to resetGroups()); false otherwise.

    • addInfo

      public static boolean addInfo(DN dsaDN, DN groupDN, DN masterDN, Set<DN> members)
      Add info about a specific DSA, rather than parsing config stuff in the DSA itself.

      This method is called by processInfoFromDSA(DN, ConfigEntry, FailoverEntry) after it has extracted the relevant information from the entries. It is public so that it can be called by code loading stuff from Preferences, or from test code which needs to simulate the effect of calling processInfoFromDSA(DN, ConfigEntry, FailoverEntry) without having to provide "real" ConfigEntry and FailoverEntry objects. Each of the parameters below would normally come from one of those objects.

      If groupDN, masterDN and members are all null, this is assumed to mean that any information about the DSA is to be removed from FailoverGroups.

      Parameters:
      dsaDN - the DN of the member DSA which is the "source" of the info
      groupDN - what the DSA thinks the group DN is. This will normally be derived from the FailoverEntry
      masterDN - what the DSA thinks the master DN is. This will normally be derived from the ConfigEntry.
      members - what the DSA thinks are the members of the group. Normally derived from the FailoverEntry.
      Returns:
      true if this changes anything; false if the new information is entirely consistent with what was already known

    • processInfoFromDSA

      public static boolean processInfoFromDSA(DN dsaDN, ConfigEntry configEntry, FailoverEntry failoverEntry)
      Process information that's been read from a DSA and add it to our knowledge of what's going on with failover.

      A ConfigEntry contains the DN of the master, and a flag to say whether failover is enabled.

      A FailoverEntry contains, among other things, the DN of the group and a list of the members in the group.

      If configEntry and failoverEntry are both null, then this is taken to mean "an attempt to read from the DSA failed, so forget anything you previously knew".

      Parameters:
      dsaDN - the DSA who this info has come from (or not come from). Must not be null.
      configEntry - a ConfigEntry; may be null .
      failoverEntry - the FailoverEntry from the same DSA. This may be null.
      Returns:
      true if something changed as a result of processing this information; false otherwise.

    • isGroup

      public static boolean isGroup(DN groupDN)
      Determine whether a specific group DN is known about
      Parameters:
      groupDN - the DN of the group, must not be null
      Returns:
      true if this is a known group, false otherwise.
      See Also:

    • isGroupConsistent

      public static boolean isGroupConsistent(DN groupDN)
      Determine whether a specific group has consistent or inconsistent information.
      Parameters:
      groupDN - a group DN, must not be null
      Returns:
      true if groupDN represents a group which is known about and which is consistent. False for an unknown group, or for a group which has inconsistent information
      See Also:

    • getFailoverGroups

      public static Set<DN> getFailoverGroups()
      Obtain a list of all the known failover groups.
      Returns:
      a Set of DNs for each of the failover groups. The method will never return null, but will return an empty list if no failover groups are known.

    • groupContainsMember

      public static boolean groupContainsMember(DN groupDN, DN memberDN)
      Does a specific group contain a particular member?
      Parameters:
      groupDN - the group of interest. Must not be null.
      memberDN - the DN of the DSA.
      Returns:
      true if anyone has reported this DSA as being in the group (even if some people have said it isn't). False if no-one says the DSA is in the group, or if the group is unknown.

    • getAgreedMembers

      public static Set<DN> getAgreedMembers(DN groupDN)
      Get the set of members which everyone in the group agrees on
      Parameters:
      groupDN - the group DN of interest. Must not be null.
      Returns:
      a set of members that everyone agrees on. Will be an empty set if no members are agreed on by anyone, or if groupDN is not a known group. Won't return null.

    • getDisputedMembers

      public static Set<DN> getDisputedMembers(DN groupDN)
      Get the set of members which not everyone in the group agrees on
      Parameters:
      groupDN - the group DN of interest. Must not be null.
      Returns:
      a set of members that not everyone agrees on. Will be an empty set if no members are disputed, or if groupDN is not a known group. Won't return null.

    • getAllMembers

      public static Set<DN> getAllMembers(DN groupDN)
      Return a set of all the DNs of DSAs which ANYONE thinks is a member of this group (i.e. the union of agreed and disputed DSAs)
      Parameters:
      groupDN - the group DN of interest. Must not be null.
      Returns:
      a complete set of members of the group as reported by anyone. Will be an empty set if groupDN is not a known group. Won't return null.

    • getMasters

      public static Set<DN> getMasters(DN groupDN)
      Determine which DSA(s) is/are marked as being the master(s) of a specific group
      Parameters:
      groupDN - the group of interest
      Returns:
      a set of DNs which are marked as being "master" of this group. Will be an empty set if groupDN is not a known group, or if no-one thinks this group has a master. Won't return null.

    • isActualMaster

      public static boolean isActualMaster(DN groupDN, DN dsaDN)
      Determine whether a specific DSA is member of a specific group. Note that this method returns a value based on getActualMaster(DN) i.e. the DN of the actual master, which could be different from the DN of the DSA that this DSA thinks is the master (e.g. if this DSA has been removed from the group and has stale information on who the master used to be).
      Parameters:
      groupDN - the group DN. Must not be null.
      dsaDN - the DSA DN. Must not be null.
      Returns:
      true if the DSA is the master of the group, false otherwise.

    • getActualMembers

      public static Set<DN> getActualMembers(DN groupDN)
      Get a actual members of a group, even though different DSAs may be reporting different lists of members

      The actual members of the group are the ones that the actual master (getActualMaster(DN) reports. If there is no actual master, then this method returns an empty set.

      Returns:
      a Set of DNs representing the actual members of a group which will be empty if the actual members cannot be determined

    • getActualMaster

      public static DN getActualMaster(DN groupDN)
      Determine which member of the group is the actual master, even if the different DSAs are reporting different masters.

      The test used to determine this is that there must be just one DSA who claims itself as being the master. If there are no DSAs claiming to be the master, or multiple DSAs claiming to be the master, then this method returns null.

      Parameters:
      groupDN - the group of interest. Must not be null
      Returns:
      a DN of the single DSA which reports itself as being the master, or null if the number of DSAs reporting themselves as being master is zero or more than one.
      See Also:

    • getProbableMaster

      public static DN getProbableMaster(DN groupDN)
      This method returns the DSA which is most likely to be the master, in the case where there are several DSAs claiming to be the master.

      The typical situation where this happens is that a master has gone away, and while it was away, one of the other members was promoted to be the master. When the original master comes back, the group will have two masters.

      The method will return a DN of a member that

      • claims to be the master
      • is regarded as being the master by all other members (excepting members who regard themselves as the master)
      So if several DSAs claim to be the master, then this method will return the DN of the one that is universally regarded as being the master by all non-master DSAs.
      Parameters:
      groupDN - the group of interest
      Returns:
      the DN of the actual master, if there is one, or the probable master, if that can be determined, otherwise null.

    • getProbableMembers

      public static Set<DN> getProbableMembers(DN groupDN)
      Get members of a group that are reported by the "probable" master.,
      Returns:
      a Set of DNs representing the members of a group which are reported by the probable master; will be empty if the probable master cannot be determined
      See Also:

    • getGroupOfDSA

      public static DN getGroupOfDSA(DN memberDN)
      Determine which failover group (if any) a specified DSA belongs to.

      If the DSA reported itself as being member of a group, then that groupDN will be returned. Otherwise, if another DSA has reported it as being a member of a group, then THAT DN will be returned. Otherwise, null will be returned.

      Parameters:
      memberDN - the DN of the member DSA. Must not be null.
      Returns:
      the DN of the failover group to which the member belongs, or null if memberDN is not a member of any failover group.

    • isFailoverParticipant

      public static boolean isFailoverParticipant(DN dsaDN)
      Determine whether a specified DSA thinks it is part of a failover ] configuration. Note that this just says what the DSA itself thinks; it may be that other DSAs think it's a failover member but that won't affect the result of this method
      Parameters:
      dsaDN - the DSA DN
      Returns:
      true if the DSA appears to be a member of any failover group.

    • getReportedMaster

      public static DN getReportedMaster(DN memberDN)
      Determine who the master of the group is according to a specific member. I.e. "who does this member think the master is?"
      Parameters:
      memberDN - the member in question
      Returns:
      the DN of the DSA who memberDN thinks is the master. This may be null if memberDN isn't a known DSA, or if it doesn't report any master.

    • isOnline

      public static boolean isOnline(DN memberDN)
      Report online state.
      Parameters:
      memberDN - the member in question
      Returns:
      true if the failover configuration has been loaded from the given member, false otherwise.
      Since:
      16.3

    • getPresentationAddress

      public static PresentationAddress getPresentationAddress(DN dsaDN)
      Determine the presentation address (if available) of a specific DSA
      Parameters:
      dsaDN - the DN of the DSA. Must not be null
      Returns:
      a Presentation address corresponding to this DSA, if known. If no presentation address has been associated with the DSA, then the method will return null.

    • setDSAAddress

      public static void setDSAAddress(DN dsaDN, PresentationAddress pa)
      This method associates a DSA DN with its presentation address. TODO: This is a temporary fix and really there should be some application wide mechanism that maintains this mapping.

      No checking is done in this method that the specified DSA hasn't already been associated with a different PA, or that the PA hasn't already been associated with a different DSA. The method simply stores the specified mapping, overwriting any previous value for dsaDN

      Parameters:
      dsaDN - the DSA DN. Must not be null.
      pa - the presentation address. May be null, which means remove any existing mapping for dsaDN.

    • getErrors

      public static List<FailoverGroups.ErrorInfo> getErrors()
      Get a list of all the current errors
      Returns:
      a list, which will be empty (i.e. zero elements) if there are no errors. Will never return null.

    • getErrorsForGroup

      public static List<FailoverGroups.ErrorInfo> getErrorsForGroup(DN groupDN)
      Get a list of the errors relating to a specific group.
      Parameters:
      groupDN - the group of interest. Must not be null. If this is an unknown group, then an empty list will be returned.
      Returns:
      a list, which will be empty (i.e. zero elements) if there are no errors relating to the group, or the group is unknown. Will never return null.
      See Also:

    • hasConfigEntryInfo

      public static boolean hasConfigEntryInfo(DN dsaDN)
      Determine whether we have ConfigEntry info for a specific DSA
      Parameters:
      dsaDN - the DN of the DSA we're interested in
      Returns:
      true if we've got info from this DSA's ConfigEntry; false otherwise.

    • hasFailoverEntryInfo

      public static boolean hasFailoverEntryInfo(DN dsaDN)
      Determine whether we have FailoverEntry info for a specific DSA
      Parameters:
      dsaDN - the DN of the DSA we're interested in
      Returns:
      true if we've got info from this DSA's FailoverEntry; false otherwise.

    • addListener

      public static void addListener(FailoverGroups.FailoverGroupsListener listener)
      Registers a FailoverGroupsListener. When a change occurs to the contents of the maps maintained by the FailoverGroups, all registered listeners will be called.
      Parameters:
      listener - an instance of a class which implements FailoverGroupsListener. If listener is already registered, calling this method has no effect.
      See Also:

    • removeListener

      public static void removeListener(FailoverGroups.FailoverGroupsListener listener)
      Removes a registered FailoverGroupsListener.
      Parameters:
      listener - a listener to be removed. If listener is not registered, calling this method has no effect.

    • dump

      public static void dump()
      Used for debugging etc.; just dumps what we know