Understanding Oorian's Flexible Communication Model

One of Oorian's most distinctive features is its flexible communication model. Unlike frameworks that force you into a single communication pattern, Oorian lets you choose AJAX, SSE, or WebSocket on a per-page basis. Best of all, your code stays exactly the same regardless of which mode you choose—Oorian handles all the technical details behind the scenes.

The Default: AJAX + SSE

By default, all Oorian pages use AJAX_WITH_SSE mode. This combines AJAX for client-to-server communication with Server-Sent Events (SSE) for server push—giving you the best of both worlds.

Why is this the default? It provides a good balance of simplicity and real-time capability. AJAX handles user actions efficiently, while the SSE connection lets the server push updates to the browser at any time without the client having to poll. For most applications, this is exactly what you need.

The Three Communication Modes

AJAX_ONLY: Request-Response Simplicity

The simplest mode. The browser sends requests, the server responds. It's stateless from the HTTP perspective (though Oorian maintains session state) and works everywhere without special infrastructure. There's no persistent connection to maintain.

Best for: Contact forms, login pages, simple CRUD operations, and pages where server push isn't needed.

AJAX_WITH_SSE: The Best of Both Worlds

This default mode combines AJAX requests with a Server-Sent Events connection. User actions are sent via AJAX, but the server can push updates to the browser at any time through the SSE connection. It automatically reconnects if the connection drops.

Best for: Dashboards, live feeds, notifications, progress indicators, and any page that needs server push.

WEBSOCKET: Full Bidirectional

A single persistent, bidirectional connection. Both browser and server can send messages at any time with minimal overhead. This provides the lowest latency possible but requires more server resources.

Best for: Chat applications, collaborative editors, multiplayer games, real-time trading platforms.

Your Code Stays the Same

Here's what makes Oorian's approach powerful: your code doesn't change based on which communication mode you use. Whether you're using AJAX, SSE, or WebSocket, you write the same Java code. Oorian abstracts away all the technical complexity of each transport mechanism.

For example, this dashboard code works identically in any mode:

@Page("/dashboard")
public class DashboardPage extends HtmlPage
{
    private Div metricsPanel;

    // This method works the same in AJAX_ONLY, AJAX_WITH_SSE, or WEBSOCKET
    public void updateMetrics(Metrics metrics)
    {
        metricsPanel.setText(metrics.toString());
        sendUpdate();  // Push changes to browser
    }
}

The sendUpdate() method works the same way regardless of the communication mode. Event handlers, form submissions, button clicks—everything works identically. You focus on your application logic, and Oorian handles the communication layer.

This means you can start with the default AJAX_WITH_SSE mode, and if you later decide you need WebSocket for a specific page, you simply change one line—no code refactoring required.

Configuring Communication Modes

Application-Wide Default

While AJAX_WITH_SSE is Oorian's default, you can change the default for your entire application in your Application class:

@WebListener
public class MyApplication extends Application
{
    @Override
    public void contextInitialized(ServletContextEvent sce)
    {
        super.contextInitialized(sce);

        // Change the application-wide default
        setCommunicationMode(CommunicationMode.AJAX_ONLY);
    }
}

This is useful when most of your pages don't need server push. Set the application default to AJAX_ONLY, then override on specific pages that need real-time updates.

Per-Page Override

Override the default on individual pages by calling setCommunicationMode() in your page's constructor:

// Simple form page - use AJAX only (no SSE overhead)
@Page("/contact")
public class ContactPage extends HtmlPage
{
    public ContactPage()
    {
        setCommunicationMode(CommunicationMode.AJAX_ONLY);
    }
}

// Dashboard with live updates - ensure SSE is enabled
@Page("/dashboard")
public class DashboardPage extends HtmlPage
{
    public DashboardPage()
    {
        setCommunicationMode(CommunicationMode.AJAX_WITH_SSE);
    }
}

// Chat application - use WebSocket for lowest latency
@Page("/chat")
public class ChatPage extends HtmlPage
{
    public ChatPage()
    {
        setCommunicationMode(CommunicationMode.WEBSOCKET);
    }
}

Choosing a Mode: Technical Considerations

While your code stays the same across all modes, the underlying transport mechanisms have different technical characteristics. Understanding these helps you choose the right mode for each page.

When to Use AJAX_ONLY

AJAX_ONLY eliminates the persistent SSE connection, which matters in several scenarios:

• High-traffic sites: Each SSE connection consumes server resources. For sites with thousands of concurrent users where server push isn't needed, AJAX_ONLY significantly reduces server load.
• Restrictive networks: Some corporate proxies and firewalls have issues with persistent connections. AJAX_ONLY works through any network configuration.
• Mobile battery life: Persistent connections increase battery drain. AJAX_ONLY is more power-efficient for mobile users who don't need real-time updates.

When to Use AJAX_WITH_SSE

The default mode is ideal when you need server push without the complexity of full WebSocket:

• Server-initiated updates: Dashboards, notifications, progress bars, and live feeds where the server needs to push data without the client polling.
• Better proxy compatibility: SSE uses standard HTTP, which passes through proxies and firewalls more reliably than WebSocket.
• Efficient one-way push: When you only need server-to-client push (not bidirectional), SSE is more efficient than WebSocket.
• Moderate update frequency: For updates every few seconds (stock prices, metrics, notifications), SSE provides excellent performance.

When to Use WEBSOCKET

WebSocket provides the lowest latency but requires more infrastructure consideration:

• Bidirectional real-time: Chat applications, collaborative editors, and multiplayer games where both client and server send frequent messages.
• High-frequency updates: Trading platforms or real-time gaming where milliseconds matter and updates happen many times per second.
• Reduced overhead: For applications sending many small messages, WebSocket's single persistent connection has less overhead than repeated AJAX requests.

Infrastructure note: WebSocket requires WebSocket-aware load balancers and may have issues with some proxies. Ensure your deployment environment supports WebSocket before choosing this mode for production.

Mixing Modes in One Application

Here's the beauty of Oorian's approach: you're not locked into one mode for your entire application. A typical application might use:

• AJAX_ONLY for login, settings, and contact forms
• AJAX_WITH_SSE for the main dashboard with live metrics
• WEBSOCKET for the real-time chat feature

Each page chooses the right tool for the job. And because your code stays the same regardless of mode, you can easily adjust as requirements evolve. This pragmatic approach keeps your application simple where possible and powerful where needed.