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 Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default java.util.Optional<?> associatedObject()
      Get the game object that may be associated with this subject.
      default SubjectReference asSubjectReference()
      Gets a SubjectReference representing this subject.
      default SubjectCollection containingCollection()
      Returns the subject collection this subject is a member of.
      default Cause contextCause()
      Get the cause describing the current state of this subject.
      default java.util.Optional<java.lang.String> friendlyIdentifier()
      Returns the friendly identifier associated with this Contextual.
      default boolean hasPermission​(java.lang.String permission)
      Test whether the subject is permitted to perform an action given as the given permission string.
      default boolean hasPermission​(java.lang.String permission, java.util.Set<Context> contexts)
      Test whether the subject is permitted to perform an action corresponding to the given permission string.
      default boolean hasPermission​(java.lang.String permission, Cause cause)
      Test whether the subject is permitted to perform an action corresponding to the given permission string.
      default java.lang.String identifier()
      Returns the identifier associated with this Contextual.
      default boolean isChildOf​(SubjectReference parent)
      Check if this subject is a child of the given parent in the subject's current context, traversing inheritance.
      default boolean isChildOf​(SubjectReference parent, java.util.Set<Context> contexts)
      Check if this subject is a child of the given parent in the given context combination, traversing inheritance.
      default boolean isChildOf​(SubjectReference parent, Cause causes)
      Check if this subject is a child of the given parent in the given context combination, traversing inheritance.
      default boolean isSubjectDataPersisted()
      Returns if this Subject has persistent, non-transient data.
      default java.util.Optional<java.lang.String> option​(java.lang.String key)
      Gets the value of a given option in the subject's current context.
      default java.util.Optional<java.lang.String> option​(java.lang.String key, java.util.Set<Context> contexts)
      Gets the value of a given option in the given context.
      default java.util.Optional<java.lang.String> option​(java.lang.String key, Cause cause)
      Gets the value of a given option in the given context.
      default java.util.List<? extends SubjectReference> parents()
      Return all parents that this group has in its current context combination.
      default java.util.List<? extends SubjectReference> parents​(java.util.Set<Context> contexts)
      Return all parents that this group has in the given context combination.
      default java.util.List<? extends SubjectReference> parents​(Cause causes)
      Return all parents that this group has in the given context combination.
      default Tristate permissionValue​(java.lang.String permission)
      Returns the calculated value set for a given permission.
      default Tristate permissionValue​(java.lang.String permission, java.util.Set<Context> contexts)
      Returns the calculated value set for a given permission.
      default Tristate permissionValue​(java.lang.String permission, Cause causes)
      Returns the calculated value set for a given permission.
      Subject subject()
      Gets the Subject this interface is a proxy for.
      default SubjectData subjectData()
      Returns the primary data backing for this Subject.
      default SubjectData transientSubjectData()
      Returns the transient data backing for this Subject.

    • Method Detail

      • 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 java.util.Optional<java.lang.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 java.util.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​(java.lang.String permission,
                                 java.util.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​(java.lang.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​(java.lang.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,
                          java.util.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 java.util.List<? extends SubjectReference> parents​(java.util.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 java.util.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 java.util.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 java.util.Optional<java.lang.String> option​(java.lang.String key,
                                                    java.util.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 java.util.Optional<java.lang.String> option​(java.lang.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 java.util.Optional<java.lang.String> option​(java.lang.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 java.lang.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​(java.lang.String permission,
                              java.util.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​(java.lang.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​(java.lang.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