org.webswing.toolkit.api.WebswingApi Maven / Gradle / Ivy
package org.webswing.toolkit.api;
import java.awt.Container;
import java.awt.Window;
import javax.swing.JComponent;
import org.webswing.toolkit.api.action.WebActionListener;
import org.webswing.toolkit.api.action.WebWindow;
import org.webswing.toolkit.api.clipboard.BrowserTransferable;
import org.webswing.toolkit.api.clipboard.PasteRequestContext;
import org.webswing.toolkit.api.clipboard.WebswingClipboardData;
import org.webswing.toolkit.api.component.HtmlPanel;
import org.webswing.toolkit.api.lifecycle.WebswingShutdownListener;
import org.webswing.toolkit.api.security.WebswingUser;
import org.webswing.toolkit.api.security.WebswingUserListener;
import org.webswing.toolkit.api.url.WebswingUrlState;
import org.webswing.toolkit.api.url.WebswingUrlStateChangeListener;
/**
* Webswing API used by Swing application for easy integration.
*/
public interface WebswingApi {
/**
* Return the user of connected web session.
* Note:if user disconnects/closes browser, this method will return null.
*
* @return user or null if session is disconnected.
*/
public WebswingUser getPrimaryUser();
/**
* Return the user of connected mirror view web session. (Admin console - view session)
* Note: if admin disconnects/closes browser, this method will return null.
*
* @return user or null if mirror view session is disconnected.
*/
public WebswingUser getMirrorViewUser();
/**
* Check if connected web session user has role defined. If no user is connected null is returned.
* @param role name of role
* @return True if user has the role, false if not. Null if no user is connected
* @throws WebswingApiException if communication with server fails.
*/
public Boolean primaryUserHasRole(String role) throws WebswingApiException;
/**
* Check if connected web session user has permission defined. If no user is connected null is returned.
* @param permission name of permission
* @return True if user has the permission, false if not. Null if no user is connected
* @throws WebswingApiException if communication with server fails.
*/
public Boolean primaryUserIsPermitted(String permission) throws WebswingApiException;
/**
* Add listener to receive notifications when user (primary/mirror view) connects or disconnects from session
* @param listener listener to add
*/
public void addUserConnectionListener(WebswingUserListener listener);
/**
* Remove user listener
* @param listener listener to remove
*/
public void removeUserConnectionListener(WebswingUserListener listener);
/**
* 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.
*
* @param forceKillTimeout how long (in Ms) to wait for process to finish. After this time the process is forcefully terminated.
*/
public void notifyShutdown(int forceKillTimeout);
/**
* 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)
* @param listener listener to add
*/
public void addShutdownListener(WebswingShutdownListener listener);
/**
* Remove shutdown listener
* @param listener listener to remove
*/
public void removeShutdownListener(WebswingShutdownListener listener);
/**
* @return the Webswing version in 'git describe' format
*/
public String getWebswingVersion();
/**
* See {@link WebswingApi#setUrlState(WebswingUrlState, boolean)}.
* This method will not trigger url change event in {@link WebswingUrlStateChangeListener}
*
* @param state state object url is generated from
*/
public void setUrlState(WebswingUrlState state);
/**
* Sets the hash Fragment of users browser URL to represent the current state of the swing application.
* Intended for use in combination with {@link WebswingUrlStateChangeListener} and/or {@link WebswingApi#getUrlState()}
*
* @param state state object url is generated from
* @param fireChangeEvent if true, invoking this method will trigger url change event
*/
public void setUrlState(WebswingUrlState state, boolean fireChangeEvent);
/**
* @return current user's URL state (parsed hash fragment of URL) or null if no user is connected.
*/
public WebswingUrlState getUrlState();
/**
* Register a URL state change listener
* @param listener the listener
*/
public void removeUrlStateChangeListener(WebswingUrlStateChangeListener listener);
/**
* Remove URL state change listener
* @param listener the listener
*/
public void addUrlStateChangeListener(WebswingUrlStateChangeListener listener);
/**
* 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
*/
public void resetInactivityTimeout();
/**
* 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.
*
* @return Latest clipboard content received from browser
*/
public BrowserTransferable getBrowserClipboard();
/**
* 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).
*
* @param ctx request context
* @return User submited clipboard content received from browser (null if cancelled)
*/
public BrowserTransferable getBrowserClipboard(PasteRequestContext ctx);
/**
* 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).
* @param content clipboard data to be sent to browser
*/
public void sendClipboard(WebswingClipboardData content);
/**
* 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).
*/
public void sendClipboard();
/**
* Adds a WebswingBrowserActionListener to listen to javascript browser initiated events.
* @param listener The listener to add
*/
public void addBrowserActionListener(WebActionListener listener);
/**
* Removed a WebswingBrowserActionListener.
* @param listener The listener to remove
*/
public void removeBrowserActionListener(WebActionListener listener);
/**
* Sends an action event with optional data to the browser.
* @param actionName name of action to be sent
* @param data string encoded data
* @param binaryData binary data
*/
public void sendActionEvent(String actionName, String data, byte[] binaryData);
/**
* Sends an action event to a WebWindow, with optional data to the browser.
* @param webWindow window to recieve the action
* @param actionName name of action to be sent
* @param data string encoded data
* @param binaryData binary data
*/
public void sendActionEvent(WebWindow webWindow, String actionName, String data, byte[] binaryData);
/**
* Creates an HtmlPanel component.
* Compositing window manager must be enabled in config.
* @throws IllegalArgumentException if isCompositingWindowManager() returns false
*/
public HtmlPanel createHtmlPanel();
/**
* 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
*/
public HtmlPanel createHtmlPanelForWebContainerComponent(Container webContainer, JComponent componentParentOfHtmlPanel);
/**
* 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
*/
public void registerWebContainer(Container container);
/**
* Is compositing window manager enabled?
*/
public boolean isCompositingWindowManager();
/**
* Is docking enabled for window?
* Compositing window manager and docking mode in config must be enabled.
*/
public boolean isDockingEnabled(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
*/
public void toggleWindowDock(Window window);
/**
* Is touch mode active?
*/
public boolean isTouchMode();
}