Package com.ultikits.ultitools.annotations.command

Annotation Interface UsageLimit

@Target({METHOD,TYPE}) @Retention(RUNTIME) public @interface UsageLimit
Marks a @CmdMapping method as subject to a concurrency lock, enforced by UsageLockValidator.

UsageLimit.LimitType.SENDER serialises invocations per sender: while one invocation from a given sender is in flight, a second invocation of the SAME mapping from the SAME sender is rejected; a different sender is unaffected. UsageLimit.LimitType.ALL serialises invocations server-wide: while any one invocation is in flight, every OTHER sender's invocation of the same mapping is rejected, regardless of who is invoking it.

Acquisition is the gate (GEN-09 / D-02, acquire-as-you-validate): the lock is taken inside validation itself, so a failed acquisition is an ordinary validation rejection -- the mapped method is never invoked. An ALL-scope lock is released only by the sender that acquired it; no other sender's completion can free it (Pitfall 5 / T-05-03).

ContainConsole() defaults to true as of 6.3.0 -- a console sender is subject to this limit unless a mapping opts out explicitly.

A mapping -- or the executor class itself -- carrying this annotation with UsageLimit.LimitType.SENDER or UsageLimit.LimitType.ALL whose chain omits UsageLockValidator is refused at plugin load, naming the offending class and, when known, the offending mapping method (SILENT-11 / D-01, D-04); UsageLimit.LimitType.NONE is exempt since it declares no limit to enforce. No opt-out exists for this refusal: Phase 3 D-08's module-granularity isolation is the accepted escape hatch -- the offending module alone fails to load, every other module still starts.

As of 6.3.0 this annotation may also be applied at the class level, for the load-time check above. That is the ONLY thing class-level placement does: UsageLockValidator itself still reads @UsageLimit per @CmdMapping method, not from the declaring class, so a class-level annotation with no annotated mapping method loads successfully (once UsageLockValidator is present) but locks nothing -- disclosed here rather than silently accepted. Put the annotation on the mapping method itself to actually enforce a lock.

See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    UsageLimit.LimitType
     

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    UsageLimit.LimitType
    value
     

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    ContainConsole
    Whether a console sender is subject to this limit, the same as a player sender.

  • Element Details

    • value

      UsageLimit.LimitType value
      Returns:
      the concurrency scope this limit enforces -- see UsageLimit.LimitType

    • ContainConsole

      boolean ContainConsole
      Whether a console sender is subject to this limit, the same as a player sender. Defaults to true as of 6.3.0 -- a console sender is included unless a mapping opts out explicitly.
      Returns:
      whether to contain console
      Default:
      true