Package com.sk89q.worldguard.protection

Class FlagValueCalculator

java.lang.Object
com.sk89q.worldguard.protection.FlagValueCalculator
public class FlagValueCalculator extends Object
Calculates the value of a flag given a list of regions and an optional global region.

Since there may be multiple overlapping regions, regions with differing priorities, regions with inheritance, flags with region groups assigned to them, and much more, the task of calculating the "effective" value of a flag is far from trivial. This class abstracts away the difficult with a number of methods for performing these calculations.

  • Constructor Details

    • FlagValueCalculator

      public FlagValueCalculator​(List<ProtectedRegion> regions, @Nullable ProtectedRegion globalRegion)
      Create a new instance.
      Parameters:
      regions - a list of applicable regions that must be sorted according to NormativeOrders
      globalRegion - an optional global region (null to not use one)

  • Method Details

    • getMembership

      public FlagValueCalculator.Result getMembership​(RegionAssociable subject)
      Return the membership status of the given subject, indicating whether there are no (counted) regions in the list of regions, whether the subject is a member of all (counted) regions, or whether the subject is not a member of all (counted) regions.

      A region is "counted" if it doesn't have the Flags.PASSTHROUGH flag set to ALLOW and if there isn't another "counted" region with a higher priority. (The explicit purpose of the PASSTHROUGH flag is to have the region be skipped over in this check.)

      This method is mostly for internal use. It's not particularly useful.

      Parameters:
      subject - the subject
      Returns:
      the membership result

    • queryState

      @Nullable public StateFlag.State queryState​(@Nullable RegionAssociable subject, StateFlag... flags)
      Get the effective value for a list of state flags. The rules of states is observed here; that is, DENY overrides ALLOW, and ALLOW overrides NONE.

      A subject can be provided that is used to determine whether the value of a flag on a particular region should be used. For example, if a flag's region group is set to RegionGroup.MEMBERS and the given subject is not a member, then the region would be skipped when querying that flag. If null is provided for the subject, then only flags that use RegionGroup.ALL, RegionGroup.NON_MEMBERS, etc. will apply.

      Parameters:
      subject - an optional subject, which would be used to determine the region group to apply
      flags - a list of flags to check
      Returns:
      a state

    • queryState

      @Nullable public StateFlag.State queryState​(@Nullable RegionAssociable subject, StateFlag flag)
      Get the effective value for a list of state flags. The rules of states is observed here; that is, DENY overrides ALLOW, and ALLOW overrides NONE.

      This method is the same as queryState(RegionAssociable, StateFlag...).

      Parameters:
      subject - an optional subject, which would be used to determine the region group to apply
      flag - a flag to check
      Returns:
      a state

    • queryValue

      @Nullable public <V> V queryValue​(@Nullable RegionAssociable subject, Flag<V> flag)
      Get the effective value for a flag. If there are multiple values (for example, if there are multiple regions with the same priority but with different farewell messages set, there would be multiple completing values), then the selected (or "winning") value will depend on the flag type.

      Only some flag types actually have a strategy for picking the "best value." For most types, the actual value that is chosen to be returned is undefined (it could be any value). As of writing, the only type of flag that can consistently return the same 'best' value is StateFlag.

      A subject can be provided that is used to determine whether the value of a flag on a particular region should be used. For example, if a flag's region group is set to RegionGroup.MEMBERS and the given subject is not a member, then the region would be skipped when querying that flag. If null is provided for the subject, then only flags that use RegionGroup.ALL, RegionGroup.NON_MEMBERS, etc. will apply.

      Parameters:
      subject - an optional subject, which would be used to determine the region group to apply
      flag - the flag
      Returns:
      a value, which could be null

    • queryMapValue

      @Nullable public <V,​ K> V queryMapValue​(@Nullable RegionAssociable subject, MapFlag<K,​V> flag, K key, Flag<V> fallback)
      Get the effective value for a key in a MapFlag. If there are multiple values (for example, if there are multiple regions with the same priority but with different farewell messages set, there would be multiple completing values), then the selected (or "winning") value will be undefined.

      A subject can be provided that is used to determine whether the value of a flag on a particular region should be used. For example, if a flag's region group is set to RegionGroup.MEMBERS and the given subject is not a member, then the region would be skipped when querying that flag. If null is provided for the subject, then only flags that use RegionGroup.ALL, RegionGroup.NON_MEMBERS, etc. will apply.

      Parameters:
      subject - an optional subject, which would be used to determine the region group to apply
      flag - the flag of type MapFlag
      key - the key for the map flag
      Returns:
      a value, which could be null

    • queryAllValues

      public <V> Collection<V> queryAllValues​(@Nullable RegionAssociable subject, Flag<V> flag)
      Get the effective values for a flag, returning a collection of all values. It is up to the caller to determine which value, if any, from the collection will be used.

      A subject can be provided that is used to determine whether the value of a flag on a particular region should be used. For example, if a flag's region group is set to RegionGroup.MEMBERS and the given subject is not a member, then the region would be skipped when querying that flag. If null is provided for the subject, then only flags that use RegionGroup.ALL, RegionGroup.NON_MEMBERS, etc. will apply.

      Parameters:
      subject - an optional subject, which would be used to determine the region group to apply
      flag - the flag
      Returns:
      a collection of values

    • getPriority

      public int getPriority​(ProtectedRegion region)
      Get the effective priority of a region, overriding a region's priority when appropriate (i.e. with the global region).
      Parameters:
      region - the region
      Returns:
      the priority

    • getEffectiveFlag

      public <V> V getEffectiveFlag​(ProtectedRegion region, Flag<V> flag, @Nullable RegionAssociable subject)
      Get a region's state flag, checking parent regions until a value for the flag can be found (if one even exists).
      Parameters:
      region - the region
      flag - the flag
      subject - an subject object
      Returns:
      the value