Unlike HttpAction, which handles traditional HTTP requests, or AjaxAction, which sends asynchronous HTTP requests, WebsocketAction communicates with the server through a persistent WebSocket connection.

This makes it useful for interactive applications, real-time interfaces, collaborative systems, and operations that need immediate communication between the browser and server.

A WebsocketAction can receive parameters, execute application logic, and send instructions back to the browser through WebsocketContext.

Overview

A WebsocketAction is a Java class that extends WebsocketAction and implements the perform() method.

The perform() method receives a WebsocketContext representing the current WebSocket interaction.

The following example sends a WebSocket request when a button is clicked. The server responds by updating part of the interface without reloading the page.

CODE

BasicLayout layout = new BasicLayout(BasicLayout.Direction.VERTICAL);
layout.setRelativeWidth(100);
layout.setGap(10);

Button button = new Button("Send WebSocket request");
button.onClick(new WebsocketActionUpdate());

layout.add(button);
layout.add(new Text("Waiting for WebSocket action..."))
        .setId(WebsocketActionUpdate.RESULT_ID);

RESULT

The button invokes WebsocketActionUpdate, which is executed on the server through the existing WebSocket connection.

When the action finishes, the server sends a PushAction.UpdateElement instruction to replace the result component in the browser.

The rest of the page remains unchanged.

Implementing the WebSocket action

The example above uses two Java classes.

The GUI class, WebsocketActionOverview, creates the button and the component that will receive updates.

The action class, WebsocketActionUpdate, performs the server-side operation.

The server action is located in:

CODE

org.jdancewebsite.web.pub.actions.ws.examples.WebsocketActionUpdate

Its implementation follows this pattern:

CODE

public class WebsocketActionUpdate extends WebsocketAction{

    public static final String RESULT_ID = "websocketActionResult";

    @Override
    public void perform(WebsocketContext context) throws Exception{
        Text result = new Text("Updated through WebSocket!");

        context.sendClientAction(
                new PushAction.UpdateElement(RESULT_ID,result)
        );
    }
}

PushAction.UpdateElement identifies an existing component using its ID and replaces it with newly rendered content.

This provides a straightforward way to update small parts of a user interface without navigating away from the current page.

Passing parameters

WebsocketAction also supports parameters.

These are supplied when the action is created and retrieved in the server-side perform() method.

CODE

Button button = new Button("Update item");

button.onClick(
        new WebsocketActionUpdate()
                .addParameter("itemId","123")
);

Inside the action, the parameter can be retrieved using getParameter().

CODE

@Override
public void perform(WebsocketContext context) throws Exception{
    String itemId = getParameter("itemId");

    if(itemId==null || itemId.isBlank()){
        return;
    }

    // Execute application logic.
}

This is useful when an action needs to identify a particular record, operation, or user-selected value.

As with other server-side actions, received parameters should be validated before they are used.

Opening a modal dialog

WebsocketAction can send more than simple element updates.

For example, it can open a modal dialog by sending PushAction.OpenModalDialog to the browser.

The following example creates a button that opens a server-generated dialog through WebSocket.

CODE

Button button = new Button("Open WebSocket dialog");

button.onClick(
        new WebsocketActionOpenDialog()
                .addParameter("message","Hello from WebSocket")
);

RESULT

When the button is clicked, WebsocketActionOpenDialog executes on the server.

The action constructs a dialog using ordinary JDance components and sends it to the browser.

Implementing the dialog action

The dialog action is located in:

CODE

org.jdancewebsite.web.pub.actions.ws.examples.WebsocketActionOpenDialog

The server-side implementation can look like this:

CODE

public class WebsocketActionOpenDialog extends WebsocketAction{

    @Override
    public void perform(WebsocketContext context) throws Exception{
        String message = getParameter("message");

        BasicLayout dialog = new BasicLayout(BasicLayout.Direction.VERTICAL);
        dialog.setWidth(280);
        dialog.setGap(10);
        dialog.setPadding(16);

        dialog.add(new Text("WebSocket dialog"));
        dialog.add(new Text(message!=null ? message : ""));

        Button close = new Button("Close");
        close.onClick("JDance.closeModalDialog()");
        dialog.add(close);

        context.sendClientAction(
                new PushAction.OpenModalDialog(dialog)
        );
    }
}

The dialog is generated on the server and delivered through the WebSocket connection.

This allows the application to respond to user interaction with a complete JDance component rather than only returning a text message.

Accessing the WebSocket context

WebsocketContext provides information about the current WebSocket interaction and methods for communicating with the connected browser.

Your applications can also use information from the WebSocket handshake when they need to identify a user session.

For example:

CODE

context.getHandshakeRequest().getHeaders();

The handshake headers may be used by an application's own session-handling code.

Authentication and authorization remain the application's responsibility. A connected WebSocket client should not automatically be assumed to have permission to perform every operation.

Broadcasting updates

WebsocketContext.sendClientAction() sends instructions to the client associated with the current action.

An application can also use its own WebSocket connection manager to broadcast messages to multiple clients.

For example, when a project member is added, the application might update the current browser and notify other connected users viewing the same project.

Your existing AddJobMemberWS and AddTaskMemberWS actions demonstrate this general approach.

They modify server-side data and then invoke application-specific broadcast logic to refresh relevant dashboards.

The broadcasting mechanism is separate from WebsocketAction itself and depends on how the application manages its WebSocket connections.

WebsocketAction vs AjaxAction

Both WebsocketAction and AjaxAction can execute server-side logic without reloading the page.

AjaxAction communicates through HTTP, while WebsocketAction uses an established WebSocket connection.

Both can send PushAction instructions to the browser.

WebsocketAction is especially useful for applications that already maintain WebSocket connections, need frequent interactions, or support real-time updates between multiple connected users.

Full API reference

This page demonstrates the basic use of WebsocketAction, including element updates, parameters, modal dialogs, WebsocketContext, and server-side communication.

For the complete API reference and additional configuration options, visit https://doc.jdance.org.