RestrictedAccess

@RestrictedAccess

Defines a set of rules that apply to calling this method.

If some parts of the configuration are invalid or contradictory to each other, an UnexpectedSetupException will be thrown upon trying to build() a configuration object.

Sources format

When we say "source", we mean "fully qualified class name + symbol '#' + method name". That is, sources are defined like com.mycompany.myapp.MyApplication#foo. Glob wildcards (? for exactly one any character and * for any number of any characters (including zero characters)) are also supported. That is, com.mycompany.*.foo? will match any method that starts with foo and has exactly one character after the "food" word of any class located inside package com.mycompany or its subpackages. For example, it will match com.mycompany.abc.xyz.Qwe#foo5.

Parameters

preserveThisAnnotation (default = false)

If false, the annotation will be removed after transforming the method. If true, the annotation will be kept for runtime use.

exactExpectedCallStack (default = {})

If an empty list or null, this parameter has no effect. Otherwise, it specifies exactly the only call stack the method should accept, in reverse-chronological order.

Example:

@RestrictedAccess (
        exactExpectedCallStack = {
                                       // 3. (*) Then `Util#foo` invokes this, `bar()`, method - but this must not be included here.
                "my.program.Util#bar"  // 2. Then the `main` method invokes the `foo` method of the `Util` class.
                "my.program.Main#main" // 1. The program starts here.
        }
)
private static void bar() {
    ...
}

We can define such configuration as "paranoid mode". When it's used, all other parameters (such as prohibitNativeTraces) are ignored, and must not be set (otherwise the configuration will be treated as contradictory).

prohibitReflectionTraces (default = false)

If true, any call to the method that has at least a single reflection frame in its stack trace is suspended.

prohibitNativeTraces (default = false)

If true, any call to the method that has at least a single native frame in its stack trace is suspended.

prohibitArbitraryInvocation (default = false)

If true, then the method will only accept calls where the most recent frame (the most recent caller) is in the permittedSources list.

If the permittedSources list is empty, the configuration will be treated as contradictory.

permittedSources (default = {})

Defines the list of allowed most recent callers for the method if the prohibitArbitraryInvocation option is set to true.

Example:

@RestrictedAccess (
        permittedSources = "my.app.LegitimateFooCaller#callFoo" // only this source will be allowed to call `foo()`
)
private static void foo() {
    ...
}

If prohibitArbitraryInvocation is false, the configuration will be treated as contradictory.

prohibitedSources (default: {})

Defines the list of sources that are explicitly not allowed to call this method. If prohibitArbitraryInvocation is true, and the caller of the method is both in the permittedSources and in prohibitedSources lists, the call will be suspended. That is, the "is caller prohibited" check is performed after the "is caller permitted" check.

Example:

@RestrictedAccess (
        prohibitedSources = "thirdparty.app.IllegalClass#callFoo" // this source will be explicitly forbidden from calling `foo()`
)
private static void foo() {
    ...
}