Intents

The Intents API is accessible through io.intents().

To find all registered intents, use the all() method:

io.intents().all();

To raise an Intent, use the raise() method:

io.intents().raise("ShowChart");

The raise() method accepts an Intent name as a String or an IntentRequest instance as an argument.

Targeting Intent Handlers

When raising an Intent, optionally target one or more IntentHandler instances using the withTarget() method of the IntentRequest builder:

Intent intent = io.intents().all()
        .toCompletableFuture().join()
        .get("ShowChart");

IntentHandler intentHandler = intent.getHandlers().get(0);

IntentRequest intentRequest =
        IntentRequest.intent(intent.getName())
                .withTarget(IntentTarget.application(intentHandler.getApplicationName()))
                .build();

io.intents().raise(intentRequest);

The IntentTarget can be created using one of the following factory methods:

The default value for the Intent request target is startNew() when an Intent handler app is available. If the Intent has only been registered dynamically, the default value is reuse().

Passing Initial Context

To pass initial context to the Intent handler, use the withContext() method of the IntentRequest builder. Pass the context type as a first String argument and the context data as a second generic type argument:

Map<String, Object> contextData =
        Collections.singletonMap("data",
                Collections.singletonMap("RIC", "MSFT"));

Map<String, Object> options = new LinkedHashMap<>();
options.put("width", 300);
options.put("height", 200);

io.intents().raise(
        IntentRequest.intent("ShowChart")
                .withTarget(IntentTarget.startNew())
                .withContext(
                        // Context type.
                        "Instrument",
                        contextData)
                .withOptions(options)
                .build()
);

The withOptions() method of the IntentRequest builder is used to pass custom app startup options to the Intent handler. It accepts a Map<String,Object> value as an argument.

Handling Context Updates

To handle the context data passed when an Intent is raised and targeted at your app, use the addIntentListener() method. Pass the intent name as a first String argument and an IntentContextHandler as a second:

io.intents().addIntentListener("ShowChart", context -> {
    context.getType().ifPresent(contextType -> {
        switch (contextType) {
            case "Instrument": {
                Map<String, Object> data = context.getData();
                // App-specific logic for handling the new context data.
                break;
            }
        }
    });
    // Optionally return a result to the caller.
    return Collections.emptyMap();
});

To register an Intent at runtime, use addIntentListener() method. Pass an IntentListenerRequest as a first argument and an IntentContextHandler as a second:

IntentListenerRequest<Map<String, Object>> intent =
        IntentListenerRequest.intent("ShowChart", ReifiedType.OBJECT_MAP)
                .withContextTypes(Collections.singletonList("Instrument"))
                .withDisplayName("Instrument Chart")
                .build();

io.intents().addIntentListener(intent, (context) -> {
    context.getType().ifPresent(contextType -> {
        switch (contextType) {
            case "Instrument": {
                Map<String, Object> data = context.getData();
                // App-specific logic for handling the new context data.
                break;
            }
        }
    });
    // Optionally return a result to the caller.
    return Collections.emptyMap();
});

⚠️ Note that when you register an Intent only at runtime (the Intent isn't defined in the app definition file), your app must be running in order to handle the Intent. If your app isn't running when this Intent is raised, it won't be available as a possible Intent handler.