com.sk89q.worldguard.protection

Class FlagValueCalculator

java.lang.Object

com.sk89q.worldguard.protection.FlagValueCalculator

public class FlagValueCalculator
extends java.lang.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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	FlagValueCalculator.Result Describes the membership result from getMembership(RegionAssociable).

Constructor Summary

Constructors

Constructor and Description
FlagValueCalculator(java.util.List<ProtectedRegion> regions, ProtectedRegion globalRegion) Create a new instance.

Method Summary

Modifier and Type	Method and Description
<V> V	getEffectiveFlag(ProtectedRegion region, Flag<V> flag, RegionAssociable subject) Get a region's state flag, checking parent regions until a value for the flag can be found (if one even exists).
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 regions, or whether the region is not a member of all regions.
int	getPriority(ProtectedRegion region) Get the effective priority of a region, overriding a region's priority when appropriate (i.e.
<V> java.util.Collection<V>	queryAllValues(RegionAssociable subject, Flag<V> flag) Get the effective values for a flag, returning a collection of all values.
StateFlag.State	queryState(RegionAssociable subject, StateFlag... flags) Get the effective value for a list of state flags.
StateFlag.State	queryState(RegionAssociable subject, StateFlag flag) Get the effective value for a list of state flags.
<V> V	queryValue(RegionAssociable subject, Flag<V> flag) Get the effective value for a flag.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FlagValueCalculator

public FlagValueCalculator(java.util.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 Detail

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 regions, or whether the region is not a member of all regions.

A region is "counted" if it doesn't have the Flags.PASSTHROUGH flag set to ALLOW. (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

queryAllValues

public <V> java.util.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