com.vaadin.server.AbstractJavaScriptExtension Maven / Gradle / Ivy
/*
* Vaadin Framework 7
*
* Copyright (C) 2000-2024 Vaadin Ltd
*
* This program is available under Vaadin Commercial License and Service Terms.
*
* See for the full
* license.
*/
package com.vaadin.server;
import com.vaadin.shared.JavaScriptExtensionState;
import com.vaadin.shared.communication.ServerRpc;
import com.vaadin.ui.JavaScriptFunction;
import elemental.json.Json;
import elemental.json.JsonValue;
/**
* Base class for Extensions with all client-side logic implemented using
* JavaScript.
*
* When a new JavaScript extension is initialized in the browser, the framework
* will look for a globally defined JavaScript function that will initialize the
* extension. The name of the initialization function is formed by replacing .
* with _ in the name of the server-side class. If no such function is defined,
* each super class is used in turn until a match is found. The framework will
* thus first attempt with com_example_MyExtension for the
* server-side
* com.example.MyExtension extends AbstractJavaScriptExtension
* class. If MyExtension instead extends com.example.SuperExtension
* , then com_example_SuperExtension will also be attempted if
* com_example_MyExtension has not been defined.
*
*
* The initialization function will be called with this pointing to
* a connector wrapper object providing integration to Vaadin. Please note that
* in JavaScript, this is not necessarily defined inside callback
* functions and it might therefore be necessary to assign the reference to a
* separate variable, e.g. var self = this;. The following
* functions are provided by the connector wrapper object:
*
* getConnectorId() - returns a string with the id of the
* connector.getParentId([connectorId]) - returns a string with the id of
* the connector's parent. If connectorId is provided, the id of
* the parent of the corresponding connector with the passed id is returned
* instead.getElement([connectorId]) - returns the DOM Element that is
* the root of a connector's widget. null is returned if the
* connector can not be found or if the connector doesn't have a widget. If
* connectorId is not provided, the connector id of the current
* connector will be used.getState() - returns an object corresponding to the shared
* state defined on the server. The scheme for conversion between Java and
* JavaScript types is described bellow.registerRpc([name, ] rpcObject) - registers the
* rpcObject as a RPC handler. rpcObject should be an
* object with field containing functions for all eligible RPC functions. If
* name is provided, the RPC handler will only used for RPC calls
* for the RPC interface with the same fully qualified Java name. If no
* name is provided, the RPC handler will be used for all incoming
* RPC invocations where the RPC method name is defined as a function field in
* the handler. The scheme for conversion between Java types in the RPC
* interface definition and the JavaScript values passed as arguments to the
* handler functions is described bellow.getRpcProxy([name]) - returns an RPC proxy object. If
* name is provided, the proxy object will contain functions for
* all methods in the RPC interface with the same fully qualified name, provided
* a RPC handler has been registered by the server-side code. If no
* name is provided, the returned RPC proxy object will contain
* functions for all methods in all RPC interfaces registered for the connector
* on the server. If the same method name is present in multiple registered RPC
* interfaces, the corresponding function in the RPC proxy object will throw an
* exception when called. The scheme for conversion between Java types in the
* RPC interface and the JavaScript values that should be passed to the
* functions is described bellow.translateVaadinUri(uri) - Translates a Vaadin URI to a URL
* that can be used in the browser. This is just way of accessing
* {@link com.vaadin.client.ApplicationConnection#translateVaadinUri(String)}
* The connector wrapper also supports these special functions:
*
* onStateChange - If the JavaScript code assigns a function to
* the field, that function is called whenever the contents of the shared state
* is changed.onUnregister - If the JavaScript code assigns a function to
* the field, that function is called when the connector has been
* unregistered.- Any field name corresponding to a call to
* {@link #addFunction(String, JavaScriptFunction)} on the server will
* automatically be present as a function that triggers the registered function
* on the server.
* - Any field name referred to using {@link #callFunction(String, Object...)}
* on the server will be called if a function has been assigned to the
* field.
*
*
*
* Values in the Shared State and in RPC calls are converted between Java and
* JavaScript using the following conventions:
*
* - Primitive Java numbers (byte, char, int, long, float, double) and their
* boxed types (Byte, Character, Integer, Long, Float, Double) are represented
* by JavaScript numbers.
* - The primitive Java boolean and the boxed Boolean are represented by
* JavaScript booleans.
* - Java Strings are represented by JavaScript strings.
* - Java Dates are represented by JavaScript numbers containing the timestamp
*
* - List, Set and all arrays in Java are represented by JavaScript
* arrays.
* - Map<String, ?> in Java is represented by JavaScript object with
* fields corresponding to the map keys.
* - Any other Java Map is represented by a JavaScript array containing two
* arrays, the first contains the keys and the second contains the values in the
* same order.
* - A Java Bean is represented by a JavaScript object with fields
* corresponding to the bean's properties.
* - A Java Connector is represented by a JavaScript string containing the
* connector's id.
* - A pluggable serialization mechanism is provided for types not described
* here. Please refer to the documentation for specific types for serialization
* information.
*
*
* @author Vaadin Ltd
* @since 7.0.0
*/
public abstract class AbstractJavaScriptExtension extends AbstractExtension {
private JavaScriptCallbackHelper callbackHelper = new JavaScriptCallbackHelper(
this);
/**
* Creates a new JavasScript extension instance without extending any
* connector.
*/
public AbstractJavaScriptExtension() {
// Empty default constructor
}
/**
* Creates a new JavaScript extension extending the provided connector.
*
* @since 7.4
*
* @param target
* the connector to extend
*/
public AbstractJavaScriptExtension(AbstractClientConnector target) {
this();
extend(target);
}
@Override
protected void registerRpc(T implementation,
Class rpcInterfaceType) {
super.registerRpc(implementation, rpcInterfaceType);
callbackHelper.registerRpc(rpcInterfaceType);
}
/**
* Register a {@link JavaScriptFunction} that can be called from the
* JavaScript using the provided name. A JavaScript function with the
* provided name will be added to the connector wrapper object (initially
* available as this). Calling that JavaScript function will
* cause the call method in the registered {@link JavaScriptFunction} to be
* invoked with the same arguments.
*
* @param functionName
* the name that should be used for client-side callback
* @param function
* the {@link JavaScriptFunction} object that will be invoked
* when the JavaScript function is called
*/
protected void addFunction(String functionName,
JavaScriptFunction function) {
callbackHelper.registerCallback(functionName, function);
}
/**
* Invoke a named function that the connector JavaScript has added to the
* JavaScript connector wrapper object. The arguments can be any boxed
* primitive type, String, {@link JsonValue} or arrays of any other
* supported type. Complex types (e.g. List, Set, Map, Connector or any
* JavaBean type) must be explicitly serialized to a {@link JsonValue}
* before sending. This can be done either with
* {@link JsonCodec#encode(Object, JsonValue, java.lang.reflect.Type, com.vaadin.ui.ConnectorTracker)}
* or using the factory methods in {@link Json}.
*
* @param name
* the name of the function
* @param arguments
* function arguments
*/
protected void callFunction(String name, Object... arguments) {
callbackHelper.invokeCallback(name, arguments);
}
@Override
protected JavaScriptExtensionState getState() {
return (JavaScriptExtensionState) super.getState();
}
}