Class RegionQuery
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.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic enum
Options for constructing a region set viagetApplicableRegions(Location, QueryOption)
for example. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptiongetApplicableRegions
(com.sk89q.worldedit.util.Location location) Query for regions containing the given location.getApplicableRegions
(com.sk89q.worldedit.util.Location location, RegionQuery.QueryOption option) Query for regions containing the given location.<V> Collection
<V> queryAllValues
(com.sk89q.worldedit.util.Location location, LocalPlayer player, Flag<V> flag) Get the effective values for a flag, returning a collection of all values.<V> Collection
<V> queryAllValues
(com.sk89q.worldedit.util.Location location, RegionAssociable associable, Flag<V> flag) Get the effective values for a flag, returning a collection of all values.<V,
K> V queryMapValue
(com.sk89q.worldedit.util.Location location, RegionAssociable subject, MapFlag<K, V> flag, K key) Get the effective value for a key in aMapFlag
.<V,
K> V queryMapValue
(com.sk89q.worldedit.util.Location location, RegionAssociable subject, MapFlag<K, V> flag, K key, Flag<V> fallback) Get the effective value for a key in aMapFlag
.queryState
(com.sk89q.worldedit.util.Location location, LocalPlayer player, StateFlag... flags) Get the (effective) value for a list of state flags.queryState
(com.sk89q.worldedit.util.Location location, RegionAssociable associable, StateFlag... flags) Get the (effective) value for a list of state flags.<V> V
queryValue
(com.sk89q.worldedit.util.Location location, LocalPlayer player, Flag<V> flag) Get the effective value for a flag.<V> V
queryValue
(com.sk89q.worldedit.util.Location location, RegionAssociable associable, Flag<V> flag) Get the effective value for a flag.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.<K> boolean
testBuild
(com.sk89q.worldedit.util.Location location, RegionAssociable associable, MapFlag<K, StateFlag.State> mapFlag, K key, 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.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.boolean
testState
(com.sk89q.worldedit.util.Location location, LocalPlayer player, StateFlag... flag) Test whether the (effective) value for a list of state flags equalsALLOW
.boolean
testState
(com.sk89q.worldedit.util.Location location, RegionAssociable associable, StateFlag... flag) Test whether the (effective) value for a list of state flags equalsALLOW
.
-
Constructor Details
-
RegionQuery
Create a new instance.- Parameters:
cache
- the query cache
-
-
Method Details
-
getApplicableRegions
Query for regions containing the given location.RegionQuery.QueryOption.COMPUTE_PARENTS
is used.An instance of
ApplicableRegionSet
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
-
getApplicableRegions
public ApplicableRegionSet getApplicableRegions(com.sk89q.worldedit.util.Location location, RegionQuery.QueryOption option) Query for regions containing the given location.An instance of
ApplicableRegionSet
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 locationoption
- the option- 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 locationplayer
- an optional player, which would be used to determine the region group to applyflag
- the flag- Returns:
- true if the result was
ALLOW
- See Also:
-
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 locationassociable
- an optional associableflag
- the flag- Returns:
- true if the result was
ALLOW
- See Also:
-
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 locationassociable
- an optional associablemapFlag
- the MapFlagkey
- the key for the MapFlagfallback
- the fallback flag for MapFlagflag
- the flags- Returns:
- true if the result was
ALLOW
- See Also:
-
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 equalsALLOW
.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 theFlags.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 locationplayer
- an optional player, which would be used to determine the region group to applyflag
- the flag- Returns:
- true if the result was
ALLOW
- See Also:
-
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 equalsALLOW
.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 theFlags.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 locationassociable
- an optional associableflag
- the flag- Returns:
- true if the result was
ALLOW
- See Also:
-
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
overridesALLOW
, andALLOW
overridesNONE
. 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 theFlags.BUILD
flag is in the list of flags.- Parameters:
location
- the locationplayer
- an optional player, which would be used to determine the region groups that applyflags
- a list of flags to check- Returns:
- a state
- See Also:
-
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
overridesALLOW
, andALLOW
overridesNONE
. 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 theFlags.BUILD
flag is in the list of flags.- Parameters:
location
- the locationassociable
- an optional associableflags
- a list of flags to check- Returns:
- a state
- See Also:
-
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 theFlags.BUILD
flag is the flag being queried.- Parameters:
location
- the locationplayer
- an optional player, which would be used to determine the region group to applyflag
- the flag- Returns:
- a value, which could be
null
- See Also:
-
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 theFlags.BUILD
flag is the flag being queried.- Parameters:
location
- the locationassociable
- an optional associableflag
- the flag- Returns:
- a value, which could be
null
- See Also:
-
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 aMapFlag
. 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. Ifnull
is provided for the subject, then only flags that useRegionGroup.ALL
,RegionGroup.NON_MEMBERS
, etc. will apply.- Parameters:
subject
- an optional subject, which would be used to determine the region group to applyflag
- the flag of typeMapFlag
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 aMapFlag
. 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. Ifnull
is provided for the subject, then only flags that useRegionGroup.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 applyflag
- the flag of typeMapFlag
key
- the key for the map flagfallback
- 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 theFlags.BUILD
flag is the flag being queried.- Parameters:
location
- the locationplayer
- an optional player, which would be used to determine the region group to applyflag
- the flag- Returns:
- a collection of values
- See Also:
-
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 theFlags.BUILD
flag is the flag being queried.- Parameters:
location
- the locationassociable
- an optional associableflag
- the flag- Returns:
- a collection of values
- See Also:
-