A2uiCoreSurfaceModel

public final class A2uiCoreSurfaceModel implements A2uiSurfaceModel

The root domain model for a single active surface.

It acts as the owner of that surface's A2uiCoreDataModel and A2uiCoreComponentRegistry, managing updates to these registries and propagating user actions and validation/runtime errors.

Summary

Public constructors
A2uiCoreSurfaceModel(
    @NonNull String id,
    @NonNull A2uiCoreCatalog catalog,
    @NonNull A2uiCoreDataModel dataModel,
    @NonNull A2uiCoreComponentRegistry componentRegistry,
    @NonNull Function1<@NonNull A2uiUserAction, Unit> onDispatchAction,
    @NonNull Function1<@NonNull A2uiClientErrorMessage, Unit> onDispatchError,
    @NonNull Map<@NonNull String, Object> theme,
    boolean shouldSendDataModel,
    @NonNull Function0<@NonNull Long> timeProvider
)

Public methods
final void
dispatchAction(
    @NonNull String componentId,
    @NonNull Map<@NonNull String, Object> actionDefinition
)

Dispatches a user action from this surface to the registered action handler callback.
final void
dispatchError(@NonNull A2uiException exception, String componentId)

Reports a rendering or evaluation failure to the component registry and dispatches the error to the registered error handler callback.
boolean
equals(Object other)
final Object
evaluatePayload(
    @NonNull String componentId,
    @NonNull A2uiCoreValueResolver valueResolver,
    @NonNull A2uiDataPath dataPath,
    Object payload
)

Evaluates a dynamic payload for a specific component.
final @NonNull A2uiCoreCatalog

The catalog used in this surface.
final @NonNull A2uiCoreComponentRegistry

The component registry backing this surface.
final @NonNull A2uiCoreDataModel

The storage model for this surface's data tree.
@NonNull String

The unique identifier of this surface.
@NonNull T
<T extends Object> getOrCreateFunctionScopedCache(
    @NonNull String componentId,
    @NonNull A2uiFunctionDefinition functionDefinition,
    @NonNull Function0<@NonNull T> factory
)

Gets or creates a component-scoped cache for functionDefinition.
final @NonNull Map<@NonNull String, Object>

An optional map of theme-specific overrides for this surface.
int
final boolean

If true, indicates the data model of this surface should be appended as metadata to outgoing messages to the server.
@NonNull String

Public constructors

A2uiCoreSurfaceModel

public A2uiCoreSurfaceModel(
    @NonNull String id,
    @NonNull A2uiCoreCatalog catalog,
    @NonNull A2uiCoreDataModel dataModel,
    @NonNull A2uiCoreComponentRegistry componentRegistry,
    @NonNull Function1<@NonNull A2uiUserAction, Unit> onDispatchAction,
    @NonNull Function1<@NonNull A2uiClientErrorMessage, Unit> onDispatchError,
    @NonNull Map<@NonNull String, Object> theme,
    boolean shouldSendDataModel,
    @NonNull Function0<@NonNull Long> timeProvider
)
Parameters
@NonNull String id

The unique identifier of this surface.
@NonNull A2uiCoreCatalog catalog

The catalog used in this surface.
@NonNull A2uiCoreDataModel dataModel

The storage model for this surface's data tree.
@NonNull A2uiCoreComponentRegistry componentRegistry

The component registry backing this surface.
@NonNull Function1<@NonNull A2uiUserAction, Unit> onDispatchAction

Callback to handle user actions dispatched from this surface.
@NonNull Function1<@NonNull A2uiClientErrorMessage, Unit> onDispatchError

Callback to handle errors dispatched from this surface.
@NonNull Map<@NonNull String, Object> theme

An optional map of theme-specific overrides for this surface.
boolean shouldSendDataModel

If true, indicates the data model of this surface should be appended as metadata to outgoing messages to the server.
@NonNull Function0<@NonNull Long> timeProvider

Provider that returns the current epoch time in milliseconds.

Public methods

dispatchAction

public final void dispatchAction(
    @NonNull String componentId,
    @NonNull Map<@NonNull String, Object> actionDefinition
)

Dispatches a user action from this surface to the registered action handler callback.

Parameters
@NonNull String componentId

The unique identifier of the component that was interacted with.
@NonNull Map<@NonNull String, Object> actionDefinition

A map containing details about the action (e.g., name, context).

dispatchError

Added in 1.0.0-alpha01
public final void dispatchError(@NonNull A2uiException exception, String componentId)

Reports a rendering or evaluation failure to the component registry and dispatches the error to the registered error handler callback.

Note: The componentId is exclusively used to mark the error on the local component registry for local UI error boundary rendering. It is not appended or injected into the exception context or path sent to the server. Callers must ensure the exception itself is initialized with all the relevant information, including the component id if relevant.

Parameters
@NonNull A2uiException exception

The exception describing the failure.
String componentId

The unique identifier of the component that encountered the error. Null if the error is surface-level.

equals

public boolean equals(Object other)

evaluatePayload

Added in 1.0.0-alpha01
public final Object evaluatePayload(
    @NonNull String componentId,
    @NonNull A2uiCoreValueResolver valueResolver,
    @NonNull A2uiDataPath dataPath,
    Object payload
)

Evaluates a dynamic payload for a specific component.

Parameters
@NonNull String componentId

unique identifier of the UI component
@NonNull A2uiCoreValueResolver valueResolver

resolver to retrieve values from the data model
@NonNull A2uiDataPath dataPath

base path used to resolve relative paths
Object payload

payload to evaluate
Returns
Object

evaluated result, or null if evaluation fails

getCatalog

Added in 1.0.0-alpha01
public final @NonNull A2uiCoreCatalog getCatalog()

The catalog used in this surface.

getComponentRegistry

Added in 1.0.0-alpha01
public final @NonNull A2uiCoreComponentRegistry getComponentRegistry()

The component registry backing this surface.

getDataModel

Added in 1.0.0-alpha01
public final @NonNull A2uiCoreDataModel getDataModel()

The storage model for this surface's data tree.

getId

Added in 1.0.0-alpha01
public @NonNull String getId()

The unique identifier of this surface.

getOrCreateFunctionScopedCache

Added in 1.0.0-alpha01
public @NonNull T <T extends Object> getOrCreateFunctionScopedCache(
    @NonNull String componentId,
    @NonNull A2uiFunctionDefinition functionDefinition,
    @NonNull Function0<@NonNull T> factory
)

Gets or creates a component-scoped cache for functionDefinition.

Each component and functionDefinition pair gets a separate cache that persists across function invocations and data model updates. Ideal for storing the results of heavy operations that do not rely on data model values (e.g., static metadata, parsed templates, compiled regexes, etc.).

Warning: The cache does not refresh upon data model changes. Caching values that are based on the data model will result in a stale cache.

Parameters
@NonNull String componentId

unique identifier of the component
@NonNull A2uiFunctionDefinition functionDefinition

definition identifying the cache
@NonNull Function0<@NonNull T> factory

factory function to create the cache if missing
Returns
@NonNull T

cache instance

getTheme

Added in 1.0.0-alpha01
public final @NonNull Map<@NonNull String, Object> getTheme()

An optional map of theme-specific overrides for this surface.

hashCode

public int hashCode()

shouldSendDataModel

Added in 1.0.0-alpha01
public final boolean shouldSendDataModel()

If true, indicates the data model of this surface should be appended as metadata to outgoing messages to the server.

toString

public @NonNull String toString()