Module jpro.webapi
Package com.jpro.webapi

Class WebAPI

java.lang.Object
com.jpro.webapi.WebAPI
public abstract class WebAPI extends Object

Used to interface with the browser.

JPro Documentation: JPro
JPro Link: JPro
HelloWorld: HelloWorld

The WebAPI is typically used for the following use-cases:


Example:

The webAPI is usually accessed the following way:

if(WebAPI.isBrowser()) {
    WebAPI webAPI = WebAPI.getWebAPI(stage);
    webAPI.executeScript(*javascript-code*)
 }

  • Constructor Details

    • WebAPI

      public WebAPI()

  • Method Details

    • isBrowser

      public static boolean isBrowser()
      Returns true if the implementation is for a browser. An alternative way to check isBrowser is checking the property Boolean.getBoolean("jpro.isbrowser")
      Returns:
      true if implementation for browser; false otherwise.

    • getWebAPI

      public static WebAPI getWebAPI(javafx.stage.Window window) throws RuntimeException
      Returns the WebAPI implementation interface for the platform the application is currently running on.
      Parameters:
      window - The window, which is associated with a Session.
      Returns:
      An instance of WebAPI which can be used to interface with the browser.
      Throws:
      RuntimeException - if isBrowser is false

    • getWebAPI

      public static WebAPI getWebAPI(javafx.scene.Scene scene) throws RuntimeException
      Returns the WebAPI implementation interface for the platform the application is currently running on.
      Parameters:
      scene - The scene, which is associated with a Session.
      Returns:
      An instance of WebAPI which can be used to interface with the browser.
      Throws:
      RuntimeException - if isBrowser is false

    • getWebAPI

      public static void getWebAPI(javafx.scene.Node node, WebAPIConsumer consumer)
      Returns the WebAPI implementation interface for the platform the application is currently running on.
      Parameters:
      node - A node, which gets added to a scene which is associated with a Session.
      consumer - Gets executed, when the scene of the node is set.
      Since:
      2019.1.0

    • setWebAPIImpl

      public static void setWebAPIImpl(Class<?> clazz, BiConsumer<javafx.scene.Node,WebAPIConsumer> _getWebAPIImpl, WebAPI.WebAPIStatic staticImpl)
      Internal method. Do not use.
      Parameters:
      clazz - The class of the WebAPI implementation.

    • getInstanceInfo

      public abstract InstanceInfo getInstanceInfo()
      Returns information about this running instance.
      Returns:
      an InstanceInfo object containing instance information about this session.

    • getServerName

      @Deprecated public String getServerName()
      Deprecated.
      Use getBrowserURL() instead.
      Returns the url, which was used to call this session.
      Returns:
      The name of the server on which this session is currently running.

    • getBrowserURL

      public abstract String getBrowserURL()
      Returns the URL, which was used to call this session.
      Returns:
      The URL string on which this session is currently running.

    • setCookie

      public abstract void setCookie(String key, String value)
      Sets a new cookie in the current browser session. After this method is called, the map returned by getCookies() will be updated to reflect the new cookie. The cookie will not expire unless manually removed.
      Parameters:
      key - The name of the cookie to set.
      value - The value of the cookie.

    • deleteCookie

      public abstract void deleteCookie(String key)
      Deletes a cookie from the current browser session. After this method is called, the map returned by getCookies() will be updated to reflect the removal of the cookie.
      Parameters:
      key - The name of the cookie to delete.

    • getCookies

      public abstract javafx.collections.ObservableMap<String,String> getCookies()
      Retrieves the cookies of the current browser window. The returned cookies are identical to the cookies accessible via document.cookie in the browser.
      Returns:
      An observable map of the browser window's cookies.

    • getWebsocketCookies

      public abstract Map<String,String> getWebsocketCookies()
      Retrieves the cookies associated with the WebSocket connection. The content of these cookies may differ from those retrieved by getCookies() due to different domains.
      Returns:
      A map containing the WebSocket connection's cookies.

    • isMobile

      public abstract boolean isMobile()
      Determines whether the current session is running on a mobile device (Android or iOS).
      Returns:
      true if the session is running on a mobile device, false otherwise.

    • getLanguage

      public abstract String getLanguage()
      Retrieves the preferred language of the currently hosting browser.
      Returns:
      The preferred language of the hosting browser.

    • getLanguages

      public abstract List<String> getLanguages()
      Retrieves the list of preferred languages of the currently hosting browser. The first element in the list represents the language with the highest priority.
      Returns:
      A list of preferred languages of the hosting browser.

    • getPlatformOld

      public abstract String getPlatformOld()
      Retrieves the String returned by the `navigator.platform` property. This JavaScript property is deprecated but widely supported. If it is not available, this method returns `null`. It is recommended to use `getPlatform()` and `getPlatformOld()` together for compatibility. A more elegant API is provided in the jpro-platform library.
      Returns:
      the value of the `navigator.platform` property, or `null` if unavailable.

    • getPlatform

      public abstract String getPlatform()
      Retrieves the String returned by the `navigator.userAgentData.platform` property. This JavaScript property is recommended but not widely supported. If it is not available, this method returns `null`. It is recommended to use `getPlatform()` and `getPlatformOld()` together for compatibility. A more elegant API is provided in the jpro-platform library.
      Returns:
      the value of the `navigator.userAgentData.platform` property, or `null` if unavailable.

    • getLocale

      public abstract Locale getLocale()
      Retrieves the preferred locale of the currently hosting browser.
      Returns:
      The locale of the hosting browser.

    • getTimeZone

      public abstract TimeZone getTimeZone()
      Retrieves the preferred time zone of the currently hosting browser.
      Returns:
      The time zone of the hosting browser.

    • getURLQueryParams

      public Map<String,String> getURLQueryParams()
      Retrieves all query parameters from the URL that was used to create the current session.
      Returns:
      A map containing the query parameters and their values from the session URL. If no query parameters are present, an empty map is returned.

    • getHeaders

      public abstract Map<String,List<String>> getHeaders()
      Retrieves all the headers provided to this session.
      Returns:
      A map containing all the headers for this session.

    • getBrowserSize

      public abstract javafx.geometry.Rectangle2D getBrowserSize()
      Retrieves the window size of the currently hosting browser.
      Returns:
      The size of the hosting browser window as a Rectangle2D object.

    • darkMode

      public abstract javafx.beans.property.ReadOnlyBooleanProperty darkMode()
      A boolean property that changes value when the dark mode is activated or deactivated.

    • isDarkMode

      public abstract boolean isDarkMode()
      Retrieves the current value of the property darkMode().
      Returns:
      true if dark mode is active, false otherwise.

    • devicePixelRatio

      public abstract javafx.beans.property.ReadOnlyDoubleProperty devicePixelRatio()
      Retrieves the device pixel ratio in the current browser tab. The value can change when the tab is moved to a different screen or when the browser's zoom level is adjusted.

    • getDevicePixelRatio

      public abstract double getDevicePixelRatio()
      Retrieves the current value of the device pixel ratio in the current browser tab.
      Returns:
      The current device pixel ratio as a double.

    • getInstanceID

      public abstract String getInstanceID()
      Returns the ID of the current session.
      Returns:
      an ID string which represents the current session.

    • getServer

      public abstract String getServer()
      Returns the server address used to instantiate the currently running session. It hast the form: "host:port".
      Returns:
      the server address string.

    • addInstanceCloseListener

      public abstract void addInstanceCloseListener(InstanceCloseListener listener)
      Adds a listener to this WebAPI, to get triggered as this session is closing. If this session is already closed, the listener gets triggered immediately.
      Parameters:
      listener - The listener to add.

    • removeInstanceCloseListener

      public abstract void removeInstanceCloseListener(InstanceCloseListener listener)
      Removes a listener from this WebAPI. This listener will no longer get triggered when the session gets closed.
      Parameters:
      listener - The listener to be removed.

    • loadJSFile

      public abstract void loadJSFile(URL url)
      Loads and executes the js file in the currently hosting browser. Each url is only loaded once, even when called multiple times.
      Parameters:
      url - The url of the JavaScript file, which gets loaded. The js file must be accessible from the server.

    • loadCSSFile

      public abstract void loadCSSFile(URL url)
      Loads a CSS file into the browser. Each url is only loaded once, even when called multiple times.
      Parameters:
      url - The url of the CSS file, which gets loaded. The CSS file must be accessible from the server.

    • js

      public abstract JS js()
      Returns as JS object, with which JavaScript code can be executed.
      Returns:
      a JS object, with which JavaScript code can be executed.

    • executeScript

      @Deprecated public abstract void executeScript(String code)
      Deprecated.
      Executes JavaScript code in the currently hosting browser. use JS.eval(String) instead.
      Parameters:
      code - The code to be executed.

    • executeScriptWithReturn

      public abstract String executeScriptWithReturn(String code)
      Executes Javascript code in the currently hosting browser. The execution will block until it returns.
      Parameters:
      code - The code to be executed.
      Returns:
      The return value of the code.

    • createUniqueJSName

      public abstract String createUniqueJSName()
      Creates a unique name, which can be used in JavaScript code.
      Returns:
      return an unused name, which can be used in JavaScript.

    • createUniqueJSName

      public abstract String createUniqueJSName(String prefix)
      Creates a unique name with the given prefix, which can be used in JavaScript code.
      Parameters:
      prefix - A prefix for generated name.
      Returns:
      return an unused name, which can be used in JavaScript.

    • executeScriptWithVariable

      @Deprecated public abstract JSVariable executeScriptWithVariable(String code)
      Deprecated.
      Executes Javascript code in the currently hosting browser and returns the result as a JSVariable. Use JS.eval(String) instead.
      Parameters:
      code - The JavaScript code to be executed.
      Returns:
      JSVariable, containing the result of the code.

    • executeScriptWithListener

      @Deprecated public abstract void executeScriptWithListener(String code, ScriptResultListener listener)
      Deprecated.
      Executes Javascript code in the currently hosting browser and assigns a listener to the execution result. Use JS.eval(String) instead.
      Parameters:
      code - The code which gets executed.
      listener - The listener which executed with the return value of the code.

    • executeScriptWithFuture

      @Deprecated public abstract CompletableFuture<String> executeScriptWithFuture(String code)
      Deprecated.
      Executes Javascript code in the currently hosting browser. The result will be returned as a CompletableFuture. Use JS.evalFuture(String).getString().thenAccept(listener) instead.
      Parameters:
      code - The code which gets executed.
      Returns:
      A CompletableFuture, which contains the result of the code.
      Since:
      2023.3.2

    • createPublicFile

      public abstract String createPublicFile(URL url)
      Creates a public profile for a given url.
      Parameters:
      url - The url for the resource to be profiled. The url must accessible from the server.
      Returns:
      url The url or the resource to be profiled. The url must be callable from the client.

    • downloadURL

      public abstract void downloadURL(URL url)
      Downloads content from the given url.
      Parameters:
      url - The url from where to download. The url must be accessible from the server.

    • downloadURL

      public abstract void downloadURL(URL url, Runnable cleanup)
      Downloads content from the given url.
      Parameters:
      url - The url from where to download. The url must be accessible from the server.
      cleanup - gets executed after the resource was read by the server.

    • downloadResource

      public abstract void downloadResource(String resource)
      Downloads content from the given resource url.
      Parameters:
      resource - The resource from where to download. The resource must be accessible from the server.

    • downloadResource

      public abstract void downloadResource(String resource, Runnable cleanup)
      Downloads content from the given resource url.
      Parameters:
      resource - The resource from where to download. The resource must be accessible from the server.
      cleanup - gets executed after the resource was read by the server.

    • openLocalURL

      public abstract void openLocalURL(URL url)
      Opens content from the given url.
      Parameters:
      url - The url to be opened. The url must be accessible from the server.

    • openLocalResource

      public abstract void openLocalResource(String resource)
      Opens content from the given resource url.
      Parameters:
      resource - The resource to be opened. The resource must be accessible from the server.

    • registerValue

      @Deprecated public abstract void registerValue(String name, javafx.scene.Node value)
      Deprecated.
      Writes the id of the node into the javascript-variable jpro.*name*. use getElement(Node) instead.
      Parameters:
      name - The name of the node.
      value - The node to be given an alias.

    • registerValue

      @Deprecated public abstract void registerValue(String name, String value)
      Deprecated.
      Writes the value as json into the javascript-variable jpro.*name*.
      Parameters:
      name - The name of the variable.
      value - The node in the scenegraph.

    • getElement

      public abstract JSVariable getElement(javafx.scene.Node node)
      This return a JSVariable, which reference the HTMLElement of the given node.
      Parameters:
      node - The node, which HTMLElement should be referenced.
      Returns:
      a JSVariable, which reference the HTMLElement of the given node.
      Since:
      2023.2.1

    • getHTMLViewElement

      public abstract JSVariable getHTMLViewElement(HTMLView node)
      This return a JSVariable, which reference the HTMLElement of the given HTMLView.
      Parameters:
      node - The node, which HTMLElement should be referenced.
      Returns:
      a JSVariable, which reference the HTMLElement of the given node.
      Since:
      2023.2.2

    • wrapNode

      @Experimental public abstract JSVariable wrapNode(String tag, javafx.scene.Node node)
      Wraps a node in a tag. Make sure to not change anything regarding rendering. This can be used to better confirm to the HTML standard.
      Parameters:
      tag - The tag, which should be used to wrap the node.
      node - The node, which should be wrapped.
      Returns:
      a JSVariable, which reference the HTMLElement of the given node.
      Since:
      2023.2.2

    • loadNode

      @Experimental public abstract void loadNode(javafx.scene.Node node)
      This loads the node into the browser. The node and all are children will be sent to the browser. Afterward, showing the node in the browser is very fast and no further communication with the server is needed.
      Parameters:
      node - The JavaFX node, which should be loaded.
      Since:
      2023.2.2

    • registerJavaFunction

      public abstract void registerJavaFunction(String name, WebCallback callback)
      Writes a function into the javascript-variable jpro.*name*. When this function is called, it's argument is sent to the JPro server, and used to call the callback.
      Parameters:
      name - The name of the function. It will be accessible in JavaScript with jpro.*name*.
      callback - The java function, which will get called when the JavaScript function is called.

    • registerJavaFunction

      public abstract JSVariable registerJavaFunction(WebCallback callback)
      Writes a function which can be accessed with the js-variable. When this function is called, it's argument is sent to the JPro server, and used to call the callback. It will be cleaned up, when the JSVariable is no longer referenced.
      Parameters:
      callback - The java function, which will get called when the javascript function is called.

    • registerJavaFunctionWithVariable

      public abstract JSVariable registerJavaFunctionWithVariable(Consumer<JSVariable> callback)
      Writes a function which can be accessed with the js-variable. When this function is called, the argument will be mapped to a JSVariable and sent to the JPro server and used to call the callback. The function will be cleaned up, when the JSVariable is no longer referenced.
      Parameters:
      callback - The java function, which will get called when the javascript function is called. It is called with an JSVariable.
      Returns:
      a JSVariable, which contains the function.
      Since:
      2023.3.2

    • executeJSAsync

      public abstract CompletableFuture<JSVariable> executeJSAsync(String code)
      Writes a function which contains asynchronous code and can be accessed with the JSVariable after it's finished. The JSVariable is accessible after the CompletableFuture is finished and contains the result of the code. The code should use a return statement. Otherwise, the result will be undefined.
      Parameters:
      code - The JavaScript code to be executed.
      Returns:
      a CompletableFuture, which contains the result of the code.
      Since:
      2023.3.2

    • executeJSAsyncPromise

      public abstract JSVariable executeJSAsyncPromise(String code)
      Writes a function which contains asynchronous code. The result can be accessed with the JSVariable as a js-promise. The code should use a return statement. Otherwise, the result will be undefined.
      Parameters:
      code - The JavaScript code to be executed.
      Returns:
      a JSVariable, which contains a js-promise.
      Since:
      2023.3.2

    • layoutRoot

      public abstract void layoutRoot(javafx.scene.Scene scene)
      Updates the width and height of the provided Scene. It is usually called by the root of the Scene.
      Parameters:
      scene - The scene which gets layout.

    • requestLayout

      @Deprecated public abstract void requestLayout(javafx.scene.Scene scene)
      Deprecated.
      Updates the width and height of the provided Scene. It is usually called by the root of the Scene.

      This method is deprecated. Use layoutRoot(Scene) instead.

      Parameters:
      scene - The scene which gets layout.

    • openURL

      public abstract void openURL(String url)
      Opens the given url in the current tab.
      Parameters:
      url - The url which will be opened.
      Since:
      2019.2.5

    • registerWindow

      public abstract String registerWindow(javafx.stage.Window window)
      This method returns an id, which can be used to start the specified window in a new JProTag. It's used like this <jpro-app href="/app/$id"></jpro-app>
      Parameters:
      window - The window which should be opened.
      Returns:
      The id which can be used for a jpro-tag.
      Since:
      2022.1.6

    • openURLAsTab

      public abstract void openURLAsTab(String url)
      Opens the given url in a new tab.
      Parameters:
      url - The url which will be opened.
      Since:
      2019.2.5

    • openURLAsPopup

      public abstract void openURLAsPopup(String url)
      Opens the given url in a new popup.
      Parameters:
      url - The url which will be opened.
      Since:
      2019.2.5

    • openStageAsPopup

      public abstract void openStageAsPopup(javafx.stage.Stage stage) throws IllegalStateException
      Opens the given stage in a new popup.
      Parameters:
      stage - The stage which gets opened as a popup. It's important that the owner of the Stage is null, because otherwise the stage is shown as a frame in the owner.
      Throws:
      IllegalStateException - The owner of the stage must be null.
      Since:
      2019.1.0

    • openStageAsTab

      public abstract void openStageAsTab(javafx.stage.Stage stage) throws IllegalStateException
      Opens the given stage in a new tab.
      Parameters:
      stage - The stage which gets opened as a tab. It's important that the owner of the Stage is null, because otherwise the stage is shown as a frame in the owner.
      Throws:
      IllegalStateException - The owner of the stage must be null.
      Since:
      2019.1.0

    • openStageAsTab

      public abstract void openStageAsTab(javafx.stage.Stage stage, String target) throws IllegalStateException
      Opens the given stage in a new tab. The target specifies the name of the browsing context.
      Parameters:
      stage - The stage which gets opened as a tab. It's important that the owner of the Stage is null, because otherwise the stage is shown as a frame in the owner.
      target - A string, without whitespace, specifying the name of the browsing context the stage is being loaded into. If the name doesn't identify an existing context, a new context is created and given the specified name. The special target keywords, _self, _blank, _parent, _top, and can also be used.
      Throws:
      IllegalStateException - The owner of the stage must be null.
      Since:
      2024.3.3

    • runAfterUpdate

      public abstract void runAfterUpdate(Runnable runnable)
      Parameters:
      runnable - The task which gets executed next. The runnable is executed, after the current state of the scene graph is sent to the client. This can be useful to load a page incrementally
      Since:
      2019.1.0

    • makeMultiFileUploadNode

      public abstract WebAPI.MultiFileUploader makeMultiFileUploadNode(javafx.scene.Node node)
      Returns a WebAPI.MultiFileUploader for a specific node.
      Parameters:
      node - The node which will be used for accessing files.
      Returns:
      WebAPI.FileUploader of a specific node.

    • makeFileUploadNode

      public abstract WebAPI.FileUploader makeFileUploadNode(javafx.scene.Node node)
      Returns a FileUploader for a specific node.
      Parameters:
      node - The node which will be used for accessing files.
      Returns:
      WebAPI.FileUploader of a specific node.

    • createJSFile

      public abstract WebAPI.JSFile createJSFile(String objectURL, String filename, long size)
      Creates a WebAPI.JSFile object.
      Parameters:
      objectURL - The object URL of the file.
      filename - The filename of the file.
      size - The size of the file in bytes.
      Returns:
      the WebAPI.JSFile object.

    • setLossless

      public abstract void setLossless(javafx.scene.image.Image image, boolean value)
      Sets whether the Image must be transmitted lossless. The default value is true. It must be called before the image is serialized by JPro. This is useful for optimizing the size of images. A typical use case would be to set lossless to false for a dynamically created WritableImage. Then this Image would be sent to the client in a more compressed image format.
      Since:
      2019.2.2

    • makeFileUploadNodeStatic

      public static WebAPI.FileUploader makeFileUploadNodeStatic(javafx.scene.Node node)
      Returns a FileUploader for a specific node
      Parameters:
      node - The node which will be used for accessing files.
      Returns:
      FileUploader of a specific node.

    • makeMultiFileUploadNodeStatic

      public static WebAPI.MultiFileUploader makeMultiFileUploadNodeStatic(javafx.scene.Node node)
      Returns a MultiFileUploader for a specific node
      Parameters:
      node - The node which will be used for accessing files.
      Returns:
      MultiFileUploader of a specific node.

    • setLosslessStatic

      public static void setLosslessStatic(javafx.scene.image.Image image, boolean value)
      Sets whether the Image must be transmitted lossless. The default value is true. It must be called before the image is serialized by JPro. This is useful for optimizing the size of images. A typical use case would be to set lossless to false for a dynamically created WritableImage. Then this Image would be sent to the client in a more compressed image format.
      Since:
      2022.1.0

    • createVirtualImage

      public static javafx.scene.image.Image createVirtualImage(String url, int w, int h)
      Creates a virtual image that does not allocate any memory in the RAM. When rendered in the browser, the specified resource is downloaded directly. HTTP URLs are downloaded directly by the client, whereas file resources are accessed through the JPro server.
      Parameters:
      url - The URL of the image resource.
      w - The width of the virtual image.
      h - The height of the virtual image.
      Returns:
      A virtual image object representing the specified image.
      Since:
      2022.1.0

    • createVirtualImage

      public static javafx.scene.image.Image createVirtualImage(String url, int w, int h, boolean jproServerAsProxy)
      Creates a virtual image that does not allocate any memory in the RAM. The image resource is downloaded directly when rendered in the browser. If jproServerAsProxy is true, the image URL is handled by the JPro server, allowing the server to act as a proxy. If jproServerAsProxy is false, the image URL is accessed directly by the client.
      Parameters:
      url - The URL of the image resource.
      w - The width of the virtual image.
      h - The height of the virtual image.
      jproServerAsProxy - determines whether the JPro server will act as a proxy for the URL
      Returns:
      a virtual image object representing the specified image
      Since:
      2022.1.0

    • closeInstance

      public abstract void closeInstance()
      Calling this method closes the current instance. This can be used to trigger a reconnect, to create a fresh instance.

    • getServerInfo

      public static ServerInfo getServerInfo()
      Returns information about the current running server.
      Returns:
      an ServerInfo object containing server information about this session.