Interface Introspection

All Known Implementing Classes:

IntrospectionImpl

public sealed interface Introspection
permits IntrospectionImpl

The introspection api provides read-only access to JDA-Commands property system and allows subscribing to FrameworkEvents in the frameworks interaction execution process.

To access the api, you can either

• use JDACommands.introspection() or Event.introspection()
• use accessScoped() that will return the current instance of this scope

When accessing trough accessScoped(), you have to pay attention where you do so. An Introspection instance is set in most but not in all places, to know where you can use it take a look at the IntrospectionAccess annotation on user implementable methods provided by the framework.

Inside of interaction controller methods (the ones having ComponentEvent, CommandEvent etc. as a parameter and are defined inside a class annotated with Interaction ) the Introspection instance is always set with the stage Stage.INTERACTION, providing access to all Propertys.

Stage and Properties access

The Property API allows accessing all public components and configuration options of JDA-Commands. It can be used to retrieve framework services like MessageResolver, config options like Property.GLOBAL_REPLY_CONFIG or context dependent information like InvocationContext.

Please note that access is read-only, you can't set the value of a Property after starting the framework.

Based on the location (in code) where you access this api, the available Properties may very. To know what property is accessible, take a look at currentStage() and compare it to Property.stage(). A hint on the current stage is also provided by IntrospectionAccess.value().

FrameworkEvents

Sometimes it's convenient to execute some custom code at some point during runtime based on events inside the framework.

An example can be found inside the guice extension, were we use a RuntimeCloseEvent to remove the interaction controller instances inside the cache at the end of a conversation.

To subscribe to a FrameworkEvent you use subscribe(Class, Subscriber) which returns a Subscription allowing you to "unsubscribe" from this event later. If an FrameworkEvent is fired by JDA-Commands all Subscribers of that event are called.

It's important to know that the events are published by multiple threads perhaps concurrently, thus Subscribers may be also called concurrently. They have to be written with threadsafety in mind!

Implementation Note:

Internally accessScoped() uses ScopedValues. For further clarification on how this works with Threads take a look there.

Method Summary

Modifier and Type	Method	Description
static boolean	accessible()	Checks whether an Introspection instance can be access by accessScoped()
static Introspection	accessScoped()	Gets the current Introspection instance of this scope if set.
Stage	currentStage()	Returns the current Stage of this introspection instance.
<T> T	get(Property<T> property)	Gets the value of a property.
static <T> T	scopedGet(Property<T> property)	Shorthand for Introspection.access().get(Property).
<T extends FrameworkEvent> Subscription	subscribe(Class<T> event, Subscriber<T> subscriber)	Subscribes to specific FrameworkEvent allowing you to execute custom logic at multiple points during runtime.

Method Details

accessible

static boolean accessible()

Checks whether an Introspection instance can be access by accessScoped()

Returns:

true when you can use accessScoped(), false when not.

See Also:

• ScopedValue.isBound()

accessScoped

static Introspection accessScoped()

Gets the current Introspection instance of this scope if set. For further information on when this is available take a look at the class docs.

The available properties are based on the Stage of the current instance, you can check the currently available stage via currentStage().

Throws:

NoSuchElementException - if no Introspection instance is set

See Also:

• ScopedValue.get()

scopedGet

static <T> T scopedGet(Property<T> property)

Shorthand for Introspection.access().get(Property).

This method is scope dependent, see accessScoped().

Parameters:

property - the requested Property

Returns:

the property's value

Throws:

NoSuchElementException - if no Introspection instance is set

See Also:

• accessScoped()
• get(Property)

currentStage

Stage currentStage()

Returns the current Stage of this introspection instance. To know which properties are available take a look at the docs of Stage and Property.

Returns:

the current Stage

get

<T> T get(Property<T> property)

Gets the value of a property. At that point practically all properties should be resolved and caches, you can expect nearly instant access time.

To exactly know what this does take a look at PropertyProvider and PropertyProvider.Context.get(Property).

Parameters:

property - the requested Property

Returns:

the property's value

subscribe

<T extends FrameworkEvent> Subscription subscribe(Class<T> event,
 Subscriber<T> subscriber)

Subscribes to specific FrameworkEvent allowing you to execute custom logic at multiple points during runtime.

Parameters:

event - the concrete class of FrameworkEvent, e.g. RuntimeCloseEvent.class

subscriber - the Subscriber holding the logic to be executed

Returns:

the Subscription instance as a unique reference to your subscription, allowing you to later cancel it.