Package org.spongepowered.api.service.permission

Interface SubjectProxy

All Superinterfaces:
Contextual, Subject
All Known Subinterfaces:
CommandCause, CommandContext, CommandContext.Builder
public interface SubjectProxy extends Subject
Enables an object to act as a proxy to a Subject, delegating all calls through to the actual Subject.

All default-Cause methods query the context cause from this proxy, rather than the backing subject. This allows proxy subjects to override the context causes.

  • Method Details

    • subject

      Subject subject()
      Gets the Subject this interface is a proxy for.
      Returns:
      The Subject

    • contextCause

      default Cause contextCause()
      Description copied from interface: Contextual
      Get the cause describing the current state of this subject.

      This is often not based on current game state, but rather the last known state of this subject. If a subject refers to a game object that is not active in the world, the cause may be a global cause.

      Specified by:
      contextCause in interface Contextual
      Specified by:
      contextCause in interface Subject
      Returns:
      the active cause

    • friendlyIdentifier

      default Optional<String> friendlyIdentifier()
      Description copied from interface: Contextual
      Returns the friendly identifier associated with this Contextual.

      Unlike Contextual.identifier(), this value is not guaranteed to be unique.

      If the friendly identifier is equal to the normal identifier, this method should return Optional.empty().

      Contextuals which represent a ServerPlayer or a User should return the username here, if available.

      Specified by:
      friendlyIdentifier in interface Contextual
      Returns:
      The friendly identifier for this contextual

    • containingCollection

      default SubjectCollection containingCollection()
      Description copied from interface: Subject
      Returns the subject collection this subject is a member of.
      Specified by:
      containingCollection in interface Subject
      Returns:
      The appropriate collection

    • asSubjectReference

      default SubjectReference asSubjectReference()
      Description copied from interface: Subject
      Gets a SubjectReference representing this subject.
      Specified by:
      asSubjectReference in interface Subject
      Returns:
      A subject reference representing this subject

    • associatedObject

      default Optional<?> associatedObject()
      Description copied from interface: Subject
      Get the game object that may be associated with this subject.

      This could be a player, system subject, or something else. The return value of this method should not be stored.

      Specified by:
      associatedObject in interface Subject
      Returns:
      a potential game object

    • isSubjectDataPersisted

      default boolean isSubjectDataPersisted()
      Description copied from interface: Subject
      Returns if this Subject has persistent, non-transient data.

      If true, this subject should have two distinct stores of SubjectData, and the non-transient form should be saved between sessions.

      If false, this subject will have only one store of SubjectData, which will not be persisted between sessions.

      Specified by:
      isSubjectDataPersisted in interface Subject
      Returns:
      If this Subject has persistent, non-transient data.

    • subjectData

      default SubjectData subjectData()
      Description copied from interface: Subject
      Returns the primary data backing for this Subject.

      If this Subject is not persisted, this data will not be saved between sessions.

      For subjects which are not persisted, the same store will be returned by Subject.transientSubjectData().

      Specified by:
      subjectData in interface Subject
      Returns:
      The primary data backing for this Subject

    • transientSubjectData

      default SubjectData transientSubjectData()
      Description copied from interface: Subject
      Returns the transient data backing for this Subject.

      Transient data is guaranteed to only last for the duration of the subject's session, and is not persisted.

      For subjects which are not persisted, the same store will be returned by Subject.subjectData().

      Specified by:
      transientSubjectData in interface Subject
      Returns:
      The transient data backing for this Subject

    • permissionValue

      default Tristate permissionValue(String permission, Set<Context> contexts)
      Description copied from interface: Subject
      Returns the calculated value set for a given permission.

      It is expected that this method will also account for values inherited from parent subjects, as well as permission nodes inherited implicitly from a more generic level.

      Additionally, the defaults defined the SubjectCollection that holds this subject, as well as defaults defined in PermissionService.defaults() should be considered for this lookup.

      This method is likely to be called frequently, so it is desirable that implementations cache the results to method calls.

      Specified by:
      permissionValue in interface Subject
      Parameters:
      permission - The permission to check
      contexts - The contexts to query permission value in
      Returns:
      The tristate result of the check

    • permissionValue

      default Tristate permissionValue(String permission, Cause causes)
      Description copied from interface: Subject
      Returns the calculated value set for a given permission.

      It is expected that this method will also account for values inherited from parent subjects, as well as permission nodes inherited implicitly from a more generic level.

      Additionally, the defaults defined the SubjectCollection that holds this subject, as well as defaults defined in PermissionService.defaults() should be considered for this lookup.

      This method is likely to be called frequently, so it is desirable that implementations cache the results to method calls.

      Specified by:
      permissionValue in interface Subject
      Parameters:
      permission - The permission to check
      causes - The cause to gather context from.
      Returns:
      The tristate result of the check

    • permissionValue

      default Tristate permissionValue(String permission)
      Description copied from interface: Subject
      Returns the calculated value set for a given permission.

      It is expected that this method will also account for values inherited from parent subjects, as well as permission nodes inherited implicitly from a more generic level.

      Additionally, the defaults defined the SubjectCollection that holds this subject, as well as defaults defined in PermissionService.defaults() should be considered for this lookup.

      This method is likely to be called frequently, so it is desirable that implementations cache the results to method calls.

      Specified by:
      permissionValue in interface Subject
      Parameters:
      permission - The permission to check
      Returns:
      The tristate result of the check

    • isChildOf

      default boolean isChildOf(SubjectReference parent, Set<Context> contexts)
      Description copied from interface: Subject
      Check if this subject is a child of the given parent in the given context combination, traversing inheritance.

      It is expected that this method will also account for data from distant parents, inherited from direct parent subjects.

      Additionally, the defaults defined the SubjectCollection that holds this subject, as well as defaults defined in PermissionService.defaults() should be considered for this lookup.

      Specified by:
      isChildOf in interface Subject
      Parameters:
      parent - The parent to check for inheritance
      contexts - The contexts to query inheritance in
      Returns:
      Whether this is a child of the given parent

    • isChildOf

      default boolean isChildOf(SubjectReference parent, Cause causes)
      Description copied from interface: Subject
      Check if this subject is a child of the given parent in the given context combination, traversing inheritance.

      It is expected that this method will also account for data from distant parents, inherited from direct parent subjects.

      Additionally, the defaults defined the SubjectCollection that holds this subject, as well as defaults defined in PermissionService.defaults() should be considered for this lookup.

      Specified by:
      isChildOf in interface Subject
      Parameters:
      parent - The parent to check for inheritance
      causes - The cause to gather context from.
      Returns:
      Whether this is a child of the given parent

    • isChildOf

      default boolean isChildOf(SubjectReference parent)
      Description copied from interface: Subject
      Check if this subject is a child of the given parent in the subject's current context, traversing inheritance.

      This must return the same value as Subject.isChildOf(SubjectReference, Cause) called with the phase tracker's current cause.

      Specified by:
      isChildOf in interface Subject
      Parameters:
      parent - The parent to check for inheritance
      Returns:
      Whether this is a child of the given parent

    • parents

      default List<? extends SubjectReference> parents(Set<Context> contexts)
      Description copied from interface: Subject
      Return all parents that this group has in the given context combination.

      This must include inherited values if the permissions service supports inheritance.

      Specified by:
      parents in interface Subject
      Parameters:
      contexts - The cause to gather context from.
      Returns:
      An immutable list of parents

    • parents

      default List<? extends SubjectReference> parents(Cause causes)
      Description copied from interface: Subject
      Return all parents that this group has in the given context combination.

      This must include inherited values if the permissions service supports inheritance.

      Specified by:
      parents in interface Subject
      Parameters:
      causes - The cause to gather context from.
      Returns:
      An immutable list of parents

    • parents

      default List<? extends SubjectReference> parents()
      Description copied from interface: Subject
      Return all parents that this group has in its current context combination.

      This must include inherited values if the permissions service supports inheritance.

      It must also must return the same value as Subject.parents(Cause)

      Specified by:
      parents in interface Subject
      Returns:
      An immutable list of parents

    • option

      default Optional<String> option(String key, Set<Context> contexts)
      Description copied from interface: Subject
      Gets the value of a given option in the given context.

      It is expected that this method will account for options inherited from parent subjects.

      Additionally, the default options defined by the SubjectCollection that holds this subject, as well as defaults defined in PermissionService.defaults() should be considered for this lookup.

      Specified by:
      option in interface Subject
      Parameters:
      key - The key to get an option by. Case-insensitive.
      contexts - The context set to use when calculating causes
      Returns:
      The value of the option, if any is present

    • option

      default Optional<String> option(String key, Cause cause)
      Description copied from interface: Subject
      Gets the value of a given option in the given context.

      It is expected that this method will account for options inherited from parent subjects.

      Additionally, the default options defined by the SubjectCollection that holds this subject, as well as defaults defined in PermissionService.defaults() should be considered for this lookup.

      Specified by:
      option in interface Subject
      Parameters:
      key - The key to get an option by. Case-insensitive.
      cause - The cause to gather context from.
      Returns:
      The value of the option, if any is present

    • option

      default Optional<String> option(String key)
      Description copied from interface: Subject
      Gets the value of a given option in the subject's current context.

      This must return the same value as Subject.option(String, Cause) called with the phase tracker's current cause.

      Specified by:
      option in interface Subject
      Parameters:
      key - The key to get an option by. Case-insensitive.
      Returns:
      The value of the option, if any is present

    • identifier

      default String identifier()
      Description copied from interface: Contextual
      Returns the identifier associated with this Contextual.

      The identifier of each distinct Contextual within a collection of contextuals should be unique.

      Not guaranteed to be human-readable. Use Contextual.friendlyIdentifier() for a more readable alternative.

      Specified by:
      identifier in interface Contextual
      Returns:
      The identifier for this subject

    • hasPermission

      default boolean hasPermission(String permission, Set<Context> contexts)
      Description copied from interface: Subject
      Test whether the subject is permitted to perform an action corresponding to the given permission string.

      This must return the same boolean equivalent as Subject.permissionValue(String, Cause).

      Specified by:
      hasPermission in interface Subject
      Parameters:
      permission - The permission string
      contexts - The contexts to calculate permission status in
      Returns:
      True if permission is granted

    • hasPermission

      default boolean hasPermission(String permission, Cause cause)
      Description copied from interface: Subject
      Test whether the subject is permitted to perform an action corresponding to the given permission string.

      This must return the same boolean equivalent as Subject.permissionValue(String, Cause).

      Specified by:
      hasPermission in interface Subject
      Parameters:
      permission - The permission string
      cause - The cause stack to extract context information from
      Returns:
      True if permission is granted

    • hasPermission

      default boolean hasPermission(String permission)
      Description copied from interface: Subject
      Test whether the subject is permitted to perform an action given as the given permission string.

      This must return the same value as Subject.hasPermission(String, Cause) called with the phase tracker's current cause.

      Specified by:
      hasPermission in interface Subject
      Parameters:
      permission - The permission string
      Returns:
      True if permission is granted