How Do Perspective Modules Message All Active Sessions?

A completed module process reaches only the session whose UUID was supplied to findSession. Perspective provides no single module API that broadcasts a UserScopeMessageEvent to every active session. Choose either project-level messaging for UI work or controlled per-session fan-out when the event must originate inside the module.

Available Messaging Approaches

Before anything else, confirm whether the module must post UserScopeMessageEvent directly. If the finished process merely needs to trigger session UI logic, keep that logic in the Perspective project and route a project message through system.util.sendMessage. That function can send to clients under the Gateway or to a project within the Gateway. The project-side utility can then call system.perspective.sendMessage for the required session-scope changes.

Recommended Architecture

Use the project-level route for component and property updates. It separates module processing from Perspective view structure and keeps session behavior in project resources. Define one message contract containing the completion state and the data that the receiving handler needs. Do not pass module objects or mutable Java state across that boundary.

1. Define a message type for the process-complete event and a payload with stable, serializable fields.
2. Configure a Gateway project message handler to receive the module notification.
3. Have that handler call system.perspective.sendMessage with the project and session routing required by the application.
4. Add a Perspective message handler that matches the message type and performs the component or property update.
5. Test one active session first. Do not move on until the handler receives the expected payload and changes only its intended targets.
6. Open multiple sessions and confirm that the selected routing reaches each intended session once.

Use direct fan-out only when the Java module specifically requires access to each session event manager. There is no separate broadcast primitive; broadcasting means taking a snapshot of the active sessions and submitting one event to each session queue.

Direct Module Fan-Out Procedure

PerspectiveSessionMonitor.getSessionInfos() supplies a list of PerspectiveSessionInfo objects, but the wrapper has no public ID accessor. Two extraction methods are possible: encode each object with PerspectiveSessionInfo.SimplifiedGsonEncoder and read its JSON id member, or access the ID field reflectively. Prefer the encoder approach because the ID representation is already used for Perspective JSON encoding and the compatibility dependency can be isolated in one adapter.

gson = PerspectiveModule.createPerspectiveCompatibleGson(b -> {
    b.registerTypeHierarchyAdapter(
        PerspectiveSessionInfo.class,
        new PerspectiveSessionInfo.SimplifiedGsonEncoder());
});

1. Create the compatible Gson instance once during module initialization. Do not rebuild it for every completion event.
2. Call getSessionInfos() when the process completes and treat the returned list as a point-in-time snapshot.
3. Encode each PerspectiveSessionInfo, read the id member, and convert it to the UUID type accepted by findSession. Reject a missing or malformed ID and log that entry without stopping the remaining deliveries.
4. Call findSession immediately before delivery. A session can close after enumeration, so an empty result is a normal race rather than a reason to abort the broadcast.
5. Create the UserScopeMessageEvent and submit its post operation through that session's queue.
6. Record the snapshot count, resolved-session count, queued count, and skipped count. Do not report success until every enumerated entry has reached one of those outcomes.

public void sendPerspectiveSessionMessage(
        UUID sessionId, String messageType, PyDictionary payload) {
    var session = perspectiveContext.getSessionMonitor().findSession(sessionId);
    if (session.isEmpty()) {
        log.error(
            "No active Perspective session with id {} found. Message of type {} not sent.",
            sessionId, messageType);
        return;
    }
    var message = new UserScopeMessageEvent(messageType, payload);
    session.get().queue().submit(
        () -> session.get().getEventManager().post(message));
}

Delivery Mechanism

findSession resolves one live session from one UUID. The session queue is the execution boundary: submitting the task prevents the module's process-completion thread from directly posting into session state. The event manager then dispatches the event inside that session.

Enumeration and delivery are not atomic. A session may disappear between getSessionInfos() and findSession, while a new session may open after the snapshot and receive nothing. If every future session also needs the completed state, store the process result separately and have sessions read it during startup; a transient broadcast alone cannot provide late-join behavior.

Do not mutate a shared PyDictionary after queue submission. Multiple asynchronous queue tasks may observe the same object. Build the payload completely before fan-out or create a separate payload instance for each queued event when any receiver could modify it.

Verification Checks

1. Start with one session and compare the extracted UUID with the UUID already proven by the single-session method.
2. Open a second session and run one completion event. Confirm one handler invocation in each session.
3. Close one session during repeated testing. Confirm that an empty findSession result is logged and the remaining sessions still receive the event.
4. Open a session after the event. Confirm that it receives the state through the application's startup-state path if late joiners are required.

Recurring Failure Modes

Reflection avoids JSON conversion but couples the module directly to a non-public field name and runtime-access rules. If reflection is retained, isolate it behind one function and fail the compatibility test during module startup rather than discovering the problem after a process completes.

FAQ