Package com.vaadin.flow.server.communication

Class AbstractRpcInvocationEvent

java.lang.Object

java.util.EventObject

com.vaadin.flow.server.communication.AbstractRpcInvocationEvent

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

RpcInvocationEndedEvent, RpcInvocationEvent, RpcInvocationFailedEvent, RpcInvocationStartedEvent

public abstract class AbstractRpcInvocationEvent
extends EventObject

Describes which client-to-server RPC invocation (a DOM event, a synchronized property update, a @ClientCallable/template event handler, a server-side navigation, a return channel message, and so on) an event fired through the service event bus is about.

A client request can carry several invocations, and one event of each type is fired per invocation. Listeners are added for the concrete event types RpcInvocationStartedEvent, RpcInvocationFailedEvent and RpcInvocationEndedEvent, since the event bus dispatches events by their exact type.

Being reported does not mean the invocation had an effect: an RPC targeting a node that is detached, disabled or inert is reported and only then discarded unhandled by the handler it is routed to. A property synchronization is the exception, since its events are tied to the change event described below and are absent entirely when the update is discarded.

The started, (optional) failed and ended events of one invocation are fired on the same thread, in that order, with the ended event always fired after the started one regardless of outcome, so a listener may keep state in a ThreadLocal. The ended event carries what such state is most often kept for, the duration and the error of the invocation, so a listener that only needs those can listen to the ended event alone. Within the handling of one request the events do not nest: those of one invocation are all fired before those of the next. Requests belonging to different sessions are handled concurrently, however, so a listener on the service event bus must expect invocations of several sessions to be in flight on several threads at once.

Synchronized property updates (mSync) deserve a few remarks, because they are handled in two steps: the value of every synchronized property in the request is applied to the state tree first, and only then are the corresponding property change events fired, so that application code sees a fully updated tree.

• The events surround the second step, the property change event, since that is the step that runs application code. When the update produces no change event they therefore surround no work: this is the case when the value was already the one the client sent, when a model filter rejects the update, and when the property is bound to a signal through Element.bindProperty, whose write callback runs in the first step instead.
• The first step can fail on its own, when the property is not synchronized at all or a signal bound to it rejects the write. There is then no change event to surround, so the events are fired at that point instead, with a RpcInvocationFailedEvent carrying the failure. Refusing a value the client should not have sent aborts the request, so unlike a failure of the application code an invocation runs, the remaining invocations of the request are not handled and the client is sent an internal error.
• Because the first step is completed for the whole request up front, all property updates in a request are reported before any other invocation it carries, even those the client sent earlier in the request.

Since:

25.3

See Also:

• Serialized Form

Field Summary

Fields inherited from class java.util.EventObject

source

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AbstractRpcInvocationEvent(UI ui, String type, int nodeId, String name)	Creates a new event.

Method Summary

Modifier and Type	Method	Description
Optional<Component>	getComponent()	Gets the component the invocation targets, so that an observer can attribute the invocation to a Button or a Grid rather than only to a node id.
String	getName()	Gets a human-readable identifier for the invocation, such as the DOM event name, the name of the synchronized property for mSync, the invoked @ClientCallable/template method name, or the navigation location.
int	getNodeId()	Gets the id of the StateNode the invocation targets.
String	getType()	Gets the protocol-level invocation type, for example event, mSync, publishedEventHandler, navigation or channel.
UI	getUI()	Gets the UI the invocation is handled against.

Methods inherited from class java.util.EventObject

getSource, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

AbstractRpcInvocationEvent

protected AbstractRpcInvocationEvent(UI ui,
 String type,
 int nodeId,
 String name)

Creates a new event.

Parameters:

ui - the UI the invocation is handled against, not null

type - the protocol-level invocation type (for example event, mSync, publishedEventHandler, navigation, channel), not null

nodeId - the id of the targeted StateNode, or -1 if the invocation does not target a node

name - a human-readable identifier for the invocation (the DOM event name, the synchronized property name, the invoked method name, the navigation location, ...), or null if none applies

Method Details

getUI

public UI getUI()

Gets the UI the invocation is handled against.

Returns:

the UI, not null

getType

public String getType()

Gets the protocol-level invocation type, for example event, mSync, publishedEventHandler, navigation or channel.

Returns:

the invocation type, not null

getNodeId

public int getNodeId()

Gets the id of the StateNode the invocation targets.

Returns:

the node id, or -1 if the invocation does not target a node

getComponent

public Optional<Component> getComponent()

Gets the component the invocation targets, so that an observer can attribute the invocation to a Button or a Grid rather than only to a node id.

The component is looked up in the state tree of the UI each time this method is called, so call it from the listener, while the request is being handled. The result reflects the tree at that moment: when the invocation detaches the component it targets, for example a button that closes the dialog it is in, the component is found for the started event but not for the ended one.

Returns:

the component, or an empty optional if the invocation does not target a node, the node is no longer in the UI, or the node is not the element of a component

getName

public String getName()

Gets a human-readable identifier for the invocation, such as the DOM event name, the name of the synchronized property for mSync, the invoked @ClientCallable/template method name, or the navigation location.

The name never carries the data of the invocation, only its identity: for a property synchronization it is the property name, not the value sent from the client.

Returns:

the invocation name, or null if none applies