Package com.sk89q.worldguard.protection.regions

Class RegionQuery

java.lang.Object
com.sk89q.worldguard.protection.regions.RegionQuery
public class RegionQuery extends Object
This object allows easy spatial queries involving region data for the purpose of implementing protection / region flag checks.

Results may be cached for brief amounts of time. If you want to get data for the purposes of changing it, use of this class is not recommended. Some of the return values of the methods may be simulated to reduce boilerplate code related to implementing protection, meaning that false data is returned.

  • Constructor Details

    • RegionQuery

      public RegionQuery​(QueryCache cache)
      Create a new instance.
      Parameters:
      cache - the query cache

  • Method Details

    • getApplicableRegions

      public ApplicableRegionSet getApplicableRegions​(com.sk89q.worldedit.util.Location location)
      Query for regions containing the given location.

      An instance of RegionResultSet will always be returned, even if regions are disabled or region data failed to load. An appropriate "virtual" set will be returned in such a case (for example, if regions are disabled, the returned set would permit all activities).

      Parameters:
      location - the location
      Returns:
      a region set

    • testBuild

      public boolean testBuild​(com.sk89q.worldedit.util.Location location, LocalPlayer player, StateFlag... flag)
      Returns true if the BUILD flag allows the action in the location, but it can be overridden by a list of other flags. The BUILD flag will not override the other flags, but the other flags can override BUILD. If neither BUILD or any of the flags permit the action, then false will be returned.

      Use this method when checking flags that are related to build protection. For example, lighting fire in a region should not be permitted unless the player is a member of the region or the LIGHTER flag allows it. However, the LIGHTER flag should be able to allow lighting fires even if BUILD is set to DENY.

      How this method works (BUILD can be overridden by other flags but not the other way around) is inconsistent, but it's required for legacy reasons.

      This method does not check the region bypass permission. That must be done by the calling code.

      Parameters:
      location - the location
      player - an optional player, which would be used to determine the region group to apply
      flag - the flag
      Returns:
      true if the result was ALLOW
      See Also:
      RegionResultSet.queryValue(RegionAssociable, Flag)

    • testBuild

      public boolean testBuild​(com.sk89q.worldedit.util.Location location, RegionAssociable associable, StateFlag... flag)
      Returns true if the BUILD flag allows the action in the location, but it can be overridden by a list of other flags. The BUILD flag will not override the other flags, but the other flags can override BUILD. If neither BUILD or any of the flags permit the action, then false will be returned.

      Use this method when checking flags that are related to build protection. For example, lighting fire in a region should not be permitted unless the player is a member of the region or the LIGHTER flag allows it. However, the LIGHTER flag should be able to allow lighting fires even if BUILD is set to DENY.

      How this method works (BUILD can be overridden by other flags but not the other way around) is inconsistent, but it's required for legacy reasons.

      This method does not check the region bypass permission. That must be done by the calling code.

      Parameters:
      location - the location
      associable - an optional associable
      flag - the flag
      Returns:
      true if the result was ALLOW
      See Also:
      RegionResultSet.queryValue(RegionAssociable, Flag)

    • testBuild

      public <K> boolean testBuild​(com.sk89q.worldedit.util.Location location, RegionAssociable associable, MapFlag<K,​StateFlag.State> mapFlag, K key, @Nullable StateFlag fallback, StateFlag... flag)
      Returns true if the BUILD flag allows the action in the location, but it can be overridden by a list of other flags. The BUILD flag will not override the other flags, but the other flags can override BUILD. If neither BUILD or any of the flags permit the action, then false will be returned.

      Use this method when checking flags that are related to build protection. For example, lighting fire in a region should not be permitted unless the player is a member of the region or the LIGHTER flag allows it. However, the LIGHTER flag should be able to allow lighting fires even if BUILD is set to DENY.

      This method does include parameters for a MapFlag.

      How this method works (BUILD can be overridden by other flags but not the other way around) is inconsistent, but it's required for legacy reasons.

      This method does not check the region bypass permission. That must be done by the calling code.

      Parameters:
      location - the location
      associable - an optional associable
      mapFlag - the MapFlag
      key - the key for the MapFlag
      fallback - the fallback flag for MapFlag
      flag - the flags
      Returns:
      true if the result was ALLOW
      See Also:
      RegionResultSet.queryValue(RegionAssociable, Flag)

    • testState

      public boolean testState​(com.sk89q.worldedit.util.Location location, @Nullable LocalPlayer player, StateFlag... flag)
      Test whether the (effective) value for a list of state flags equals ALLOW.

      player can be non-null to satisfy region group requirements, otherwise it will be assumed that the caller that is not a member of any regions. (Flags on a region can be changed so that they only apply to certain users.) The player argument is required if the Flags.BUILD flag is in the list of flags.

      This method does not check the region bypass permission. That must be done by the calling code.

      Parameters:
      location - the location
      player - an optional player, which would be used to determine the region group to apply
      flag - the flag
      Returns:
      true if the result was ALLOW
      See Also:
      RegionResultSet.queryValue(RegionAssociable, Flag)

    • testState

      public boolean testState​(com.sk89q.worldedit.util.Location location, @Nullable RegionAssociable associable, StateFlag... flag)
      Test whether the (effective) value for a list of state flags equals ALLOW.

      player can be non-null to satisfy region group requirements, otherwise it will be assumed that the caller that is not a member of any regions. (Flags on a region can be changed so that they only apply to certain users.) The player argument is required if the Flags.BUILD flag is in the list of flags.

      This method does not check the region bypass permission. That must be done by the calling code.

      Parameters:
      location - the location
      associable - an optional associable
      flag - the flag
      Returns:
      true if the result was ALLOW
      See Also:
      RegionResultSet.queryValue(RegionAssociable, Flag)

    • queryState

      @Nullable public StateFlag.State queryState​(com.sk89q.worldedit.util.Location location, @Nullable LocalPlayer player, 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. One flag may override another.

      player can be non-null to satisfy region group requirements, otherwise it will be assumed that the caller that is not a member of any regions. (Flags on a region can be changed so that they only apply to certain users.) The player argument is required if the Flags.BUILD flag is in the list of flags.

      Parameters:
      location - the location
      player - an optional player, which would be used to determine the region groups that apply
      flags - a list of flags to check
      Returns:
      a state
      See Also:
      RegionResultSet.queryState(RegionAssociable, StateFlag...)

    • queryState

      @Nullable public StateFlag.State queryState​(com.sk89q.worldedit.util.Location location, @Nullable RegionAssociable associable, 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. One flag may override another.

      player can be non-null to satisfy region group requirements, otherwise it will be assumed that the caller that is not a member of any regions. (Flags on a region can be changed so that they only apply to certain users.) The player argument is required if the Flags.BUILD flag is in the list of flags.

      Parameters:
      location - the location
      associable - an optional associable
      flags - a list of flags to check
      Returns:
      a state
      See Also:
      RegionResultSet.queryState(RegionAssociable, StateFlag...)

    • queryValue

      @Nullable public <V> V queryValue​(com.sk89q.worldedit.util.Location location, @Nullable LocalPlayer player, Flag<V> flag)
      Get the effective value for a flag. If there are multiple values (for example, multiple overlapping regions with the same priority may have the same flag set), 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 actually has a strategy for picking a value is the StateFlag.

      player can be non-null to satisfy region group requirements, otherwise it will be assumed that the caller that is not a member of any regions. (Flags on a region can be changed so that they only apply to certain users.) The player argument is required if the Flags.BUILD flag is the flag being queried.

      Parameters:
      location - the location
      player - an optional player, which would be used to determine the region group to apply
      flag - the flag
      Returns:
      a value, which could be null
      See Also:
      RegionResultSet.queryValue(RegionAssociable, Flag)

    • queryValue

      @Nullable public <V> V queryValue​(com.sk89q.worldedit.util.Location location, @Nullable RegionAssociable associable, Flag<V> flag)
      Get the effective value for a flag. If there are multiple values (for example, multiple overlapping regions with the same priority may have the same flag set), 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 actually has a strategy for picking a value is the StateFlag.

      player can be non-null to satisfy region group requirements, otherwise it will be assumed that the caller that is not a member of any regions. (Flags on a region can be changed so that they only apply to certain users.) The player argument is required if the Flags.BUILD flag is the flag being queried.

      Parameters:
      location - the location
      associable - an optional associable
      flag - the flag
      Returns:
      a value, which could be null
      See Also:
      RegionResultSet.queryValue(RegionAssociable, Flag)

    • queryMapValue

      @Nullable public <V,​ K> V queryMapValue​(com.sk89q.worldedit.util.Location location, @Nullable RegionAssociable subject, MapFlag<K,​V> flag, K key)
      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

    • queryMapValue

      @Nullable public <V,​ K> V queryMapValue​(com.sk89q.worldedit.util.Location location, @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.

      It's possible to provide a fallback flag for the case when the key doesn't exist in the MapFlag.

      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
      fallback - the fallback flag
      Returns:
      a value, which could be null

    • queryAllValues

      public <V> Collection<V> queryAllValues​(com.sk89q.worldedit.util.Location location, @Nullable LocalPlayer player, 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.

      player can be non-null to satisfy region group requirements, otherwise it will be assumed that the caller that is not a member of any regions. (Flags on a region can be changed so that they only apply to certain users.) The player argument is required if the Flags.BUILD flag is the flag being queried.

      Parameters:
      location - the location
      player - an optional player, which would be used to determine the region group to apply
      flag - the flag
      Returns:
      a collection of values
      See Also:
      RegionResultSet.queryAllValues(RegionAssociable, Flag)

    • queryAllValues

      public <V> Collection<V> queryAllValues​(com.sk89q.worldedit.util.Location location, @Nullable RegionAssociable associable, 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.

      player can be non-null to satisfy region group requirements, otherwise it will be assumed that the caller that is not a member of any regions. (Flags on a region can be changed so that they only apply to certain users.) The player argument is required if the Flags.BUILD flag is the flag being queried.

      Parameters:
      location - the location
      associable - an optional associable
      flag - the flag
      Returns:
      a collection of values
      See Also:
      RegionResultSet.queryAllValues(RegionAssociable, Flag)