Xitrum Framework Documentation

You can visualize the project's dependency structure using Graphviz.

1. Generate the .dot file using SBT:

sbt dependencyDot

2. Convert the generated target/dependencies-compile.dot file into a PNG image:

dot -Tpng dependencies-compile.dot > deps.png

After publishing a new version, tag it in the repository using the following sequence:

git tag <new version number>
git push origin <new version number>

When developing, you can publish the current project to your local Ivy/SBT cache.

To publish for the specific scalaVersion defined in build.sbt:

sbt publishLocal

To publish for all crossScalaVersions defined in the project:

sbt "+ publishLocal"

To clear all locally published Xitrum artifacts from your cache, use:

find ~/.ivy2 -name *xitrum* -exec rm -rf {} \;

OptVar[+A] is an abstract class used to manage optional variables within an Action context. It provides a way to get, set, and remove values associated with a unique key (derived from the class name).

Key Behaviors:

• Type Safety & Recovery: If a value stored in the session does not match the expected type A (a ClassCastException scenario), OptVar will log a warning, clear the existing value to prevent the user from being stuck in a broken state, and then throw the exception. This is designed to allow users to recover (e.g., by clearing cookies) rather than being permanently stuck with an incompatible session variable.
• Action Requirement: Almost all methods require an implicit Action parameter to manage the underlying data storage and logging.

The ViewRenderer uses a stateful approach to compose views and layouts. When you call renderView, the following lifecycle occurs:

1. The template specified by the URI is rendered.
2. The resulting string is assigned to the renderedView variable.
3. The layout method is called. The layout method typically accesses renderedView to wrap the content in a common HTML structure (like a base template).

If you need to bypass the layout, use renderViewNoLayout. If you need to provide a specific layout for a single request, use renderView with a custom layout function: renderView(() => myLayout, uri).

Xitrum provides a built-in web interface for visualizing metrics. By default, it is available at the following endpoint:

GET xitrum/metrics/viewer

Security

Access to this endpoint requires a valid api_key passed as a query parameter: ?api_key=<YOUR_API_KEY>

Features

• NodeMetrics Status: Visualizes Heap Memory (Committed, Used, Max) and CPU (Processors, Load Average) using tables and D3.js graphs.
• Application Metrics: Displays Histograms (Count, Min, Max, Mean) from the application registry.
• Focus Mode: If the focusAction parameter is provided in the query string, the viewer renders a simplified focusHtml layout designed for a specific metric key.

The SockJS implementation uses the following constants to manage connection stability and resource usage:

• TIMEOUT_HEARTBEAT: Set to 25.seconds. The server must send a heartbeat frame (h) at this interval to keep the connection alive.
• CHUNKED_RESPONSE_LIMIT: To prevent memory issues and force client garbage collection/reconnection, chunked transports are closed after a certain amount of data is sent.
  • In production mode: 128 * 1024 bytes.
  • In development mode: 4 * 1024 bytes.

These values are controlled by the global Config.productionMode setting.

When creating controllers that participate in the SockJS ecosystem, extend SockJsAction. This provides access to protocol-specific requirements like cookie handling and path prefix management.

Example of a basic SockJS greeting implementation:

@GET("")
class Greeting extends SockJsAction {
  def nLastTokensToRemoveFromPathInfo = 0

  def execute(): Unit = {
    respondText("Welcome to SockJS!\n")
  }
}