Package org.webswing.toolkit.api

Interface WebswingApi

  • public interface WebswingApi
    Webswing API used by Swing application for easy integration.

    • Method Detail

      • getPrimaryUser

        WebswingUser getPrimaryUser()
        Return the user of connected web session. Note:if user disconnects/closes browser, this method will return null.
        Returns:
        user or null if session is disconnected.

      • getMirrorViewUser

        WebswingUser getMirrorViewUser()
        Return the user of connected mirror view web session. (Admin console - view session) Note: if admin disconnects/closes browser, this method will return null.
        Returns:
        user or null if mirror view session is disconnected.

      • primaryUserHasRole

        Boolean primaryUserHasRole​(String role)
                    throws WebswingApiException
        Check if connected web session user has role defined. If no user is connected null is returned.
        Parameters:
        role - name of role
        Returns:
        True if user has the role, false if not. Null if no user is connected
        Throws:
        WebswingApiException - if communication with server fails.

      • primaryUserIsPermitted

        Boolean primaryUserIsPermitted​(String permission)
                        throws WebswingApiException
        Check if connected web session user has permission defined. If no user is connected null is returned.
        Parameters:
        permission - name of permission
        Returns:
        True if user has the permission, false if not. Null if no user is connected
        Throws:
        WebswingApiException - if communication with server fails.

      • addUserConnectionListener

        void addUserConnectionListener​(WebswingUserListener listener)
        Add listener to receive notifications when user (primary/mirror view) connects or disconnects from session
        Parameters:
        listener - listener to add

      • removeUserConnectionListener

        void removeUserConnectionListener​(WebswingUserListener listener)
        Remove user listener
        Parameters:
        listener - listener to remove

      • notifyShutdown

        void notifyShutdown​(int forceKillTimeout)
        When swing application exit and shutdown process takes longer time to process, invoking this method will notify user (web session) the application has finished, and disconnect the user from the session. Swing Application process is removed from running sessions list even though the process might still be running.
        Parameters:
        forceKillTimeout - how long (in Ms) to wait for process to finish. After this time the process is forcefully terminated.

      • addShutdownListener

        void addShutdownListener​(WebswingShutdownListener listener)
        Add listener that is triggered when Webswing requests swing application to exit. If there is no explicit shutdown listener Webswing use default shutdown procedure (send window closing event to all windows). Otherwise listeners are fired. It is expected the result of listener execution will exit the swing process. Otherwise the swing process will be forcefully terminated after defined timeout (system property "webswing.waitForExit", default: 30000)
        Parameters:
        listener - listener to add

      • removeShutdownListener

        void removeShutdownListener​(WebswingShutdownListener listener)
        Remove shutdown listener
        Parameters:
        listener - listener to remove

      • getWebswingVersion

        String getWebswingVersion()
        Returns:
        the Webswing version in 'git describe' format

      • setUrlState

        void setUrlState​(WebswingUrlState state,
                 boolean fireChangeEvent)
        Sets the hash Fragment of users browser URL to represent the current state of the swing application. Intended for use in combination with WebswingUrlStateChangeListener and/or getUrlState()
        Parameters:
        state - state object url is generated from
        fireChangeEvent - if true, invoking this method will trigger url change event

      • getUrlState

        WebswingUrlState getUrlState()
        Returns:
        current user's URL state (parsed hash fragment of URL) or null if no user is connected.

      • removeUrlStateChangeListener

        void removeUrlStateChangeListener​(WebswingUrlStateChangeListener listener)
        Register a URL state change listener
        Parameters:
        listener - the listener

      • addUrlStateChangeListener

        void addUrlStateChangeListener​(WebswingUrlStateChangeListener listener)
        Remove URL state change listener
        Parameters:
        listener - the listener

      • resetInactivityTimeout

        void resetInactivityTimeout()
        Reset session timeout to prevent automatic termination. Useful if a long running operation has to finish even if user disconnects or is inactive for longer timeframe. Note: Reset needs to be called in periods shorter than configured session timeout. ("webswing.sessionTimeoutSec" system property) Note2: This method has no effect if session timeout is set to 0

      • getBrowserClipboard

        BrowserTransferable getBrowserClipboard()
        Clipboard data received from browser after CTRL+V key events (browser security allows access to clipboard only in these events).
        Typically used for customized clipboard integration, while the built-in integration is disabled in configuration ("allowLocalClipboard" is false).
        Example use case:
        1.Create new context menu item "Paste from browser", that will open a modal dialog asking user to press CTRL+V.
        2.Listen for CTRL+V keystroke. When received, call this method to get the clipboard content.
        Returns:
        Latest clipboard content received from browser

      • getBrowserClipboard

        BrowserTransferable getBrowserClipboard​(PasteRequestContext ctx)
        Request user to paste from browser clipboard by showing built-in html modal dialog. This method will block EDT thread (by showing a invisible modal JDialog) until response received from user.
        Typically used for customized clipboard integration, while the built-in integration is disabled in configuration ("allowLocalClipboard" is false).
        Parameters:
        ctx - request context
        Returns:
        User submited clipboard content received from browser (null if cancelled)

      • sendClipboard

        void sendClipboard​(WebswingClipboardData content)
        Sends the specified data to browser.
        A toolbar will appear in browser displaying the data. User can click or press CTRL+C to store the content to local clipboard.
        Typically used for customized clipboard integration, while the built-in integration is disabled in configuration ("allowLocalClipboard" is false).
        Parameters:
        content - clipboard data to be sent to browser

      • sendClipboard

        void sendClipboard()
        Sends the current Swing clipboard content to browser.
        A toolbar will appear in browser displaying the data. User can click or press CTRL+C to store the content to local clipboard.
        Typically used for customized clipboard integration, while the built-in integration is disabled in configuration ("allowLocalClipboard" is false).

      • addBrowserActionListener

        void addBrowserActionListener​(WebActionListener listener)
        Adds a WebswingBrowserActionListener to listen to javascript browser initiated events.
        Parameters:
        listener - The listener to add

      • removeBrowserActionListener

        void removeBrowserActionListener​(WebActionListener listener)
        Removed a WebswingBrowserActionListener.
        Parameters:
        listener - The listener to remove

      • sendActionEvent

        void sendActionEvent​(String actionName,
                     String data,
                     byte[] binaryData)
        Sends an action event with optional data to the browser.
        Parameters:
        actionName - name of action to be sent
        data - string encoded data
        binaryData - binary data

      • sendActionEvent

        void sendActionEvent​(WebWindow webWindow,
                     String actionName,
                     String data,
                     byte[] binaryData)
        Sends an action event to a WebWindow, with optional data to the browser.
        Parameters:
        webWindow - window to recieve the action
        actionName - name of action to be sent
        data - string encoded data
        binaryData - binary data

      • createHtmlPanel

        HtmlPanel createHtmlPanel()
        Creates an HtmlPanel component. Compositing window manager must be enabled in config.
        Throws:
        IllegalArgumentException - if isCompositingWindowManager() returns false

      • createHtmlPanelForWebContainerComponent

        HtmlPanel createHtmlPanelForWebContainerComponent​(Container webContainer,
                                                  JComponent componentParentOfHtmlPanel)
        Creates an HtmlPanel component which is a part of given component and has a container parent. Use this method to create an HtmlPanel inside a WebContainer parent container. This is required for web container to correctly compute z-order of its child component canvases. Compositing window manager must be enabled in config.
        Throws:
        IllegalArgumentException - if isCompositingWindowManager() returns false

      • registerWebContainer

        void registerWebContainer​(Container container)
        Registers given container to be a parent web container and all of its child components will be rendered into separate canvases. Compositing window manager must be enabled in config.
        Throws:
        IllegalArgumentException - if isCompositingWindowManager() returns false

      • isCompositingWindowManager

        boolean isCompositingWindowManager()
        Is compositing window manager enabled?

      • isDockingEnabled

        boolean isDockingEnabled​(Window window)
        Is docking enabled for window? Compositing window manager and docking mode in config must be enabled.

      • toggleWindowDock

        void toggleWindowDock​(Window window)
        Toggle the dock state of a window. Compositing window manager must be enabled in config. Window must be allowed to change the dock state according to config.
        Throws:
        IllegalArgumentException - if isCompositingWindowManager() or isDockingEnabled(window) returns false

      • toggleWindowDock

        void toggleWindowDock​(Window window,
                      boolean undocked)
        Toggle the dock state of a window. Compositing window manager must be enabled in config. Window must be allowed to change the dock state according to config.
        Throws:
        IllegalArgumentException - if isCompositingWindowManager() or isDockingEnabled(window) returns false

      • isUndocked

        boolean isUndocked​(Window window)
        Check whether window is in undocked state. Compositing window manager must be enabled in config.
        Throws:
        IllegalArgumentException - if isCompositingWindowManager() returns false

      • isTouchMode

        boolean isTouchMode()
        Is touch mode active?

      • registerCustomFileChooser

        void registerCustomFileChooser​(JFileChooser fileChooser,
                               Window parent)
        Register JFileChooser that should show Webswing integration toolbar if embedded in custom window. Transparent mode is not available in case of custom window.
        Parameters:
        fileChooser - instance of file chooser
        parent - custom window that contains this filechooser