WApplication (JWt Javadoc API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

eu.webtoolkit.jwt
Class WApplication

java.lang.Object
  eu.webtoolkit.jwt.WObject
      eu.webtoolkit.jwt.WApplication

public class WApplication
extends WObject
extends WObject

Represents an application instance for a single session.

Each user session of your application has a corresponding WApplication instance. You need to create a new instance and return it as the result of WtServlet.createApplication(WEnvironment). The instance is the main entry point to session information, and holds a reference to the getRoot() of the widget tree.

The recipe for a JWt web application, which allocates new WApplication instances for every user visiting the application is thus:

 public class HelloServlet extends WtServlet {
        public HelloServlet() {
                super();
        }
 
        public WApplication createApplication(WEnvironment env) {
                // In practice, you will specialize WApplication and simply
                // return a new instance.
                WApplication app = new WApplication(env);
                app.getRoot().addWidget(new WText("Hello world."));
                return app;
        }
 }

Throughout the session, the instance is available through the static method getInstance(), which uses thread-specific storage to keep track of the current session. The application may be quited either using the method quit(), or because of a timeout after the user has closed the window, but not because the user does not interact: keep-alive messages in the background will keep the session around as long as the user has the page opened.

The WApplication object provides access to session-wide settings, including:

circumstancial information through getEnvironment(), which gives details about the user, start-up arguments, and user agent capabilities.
the application title with setTitle().
inline and external style sheets using getStyleSheet() and useStyleSheet().
inline and external JavaScript using doJavaScript() and require().
the top-level widget in getRoot(), representing the entire browser window, or multiple top-level widgets using bindWidget() when deployed in WidgetSet mode to manage a number of widgets within a 3rd party page.
definition of cookies using setCookie() to persist information across sessions, which may be read using WEnvironment#getCookie() in a future session.
management of the internal path (that enables browser history and bookmarks) using getBookmarkUrl() and related methods.
support for server-initiated updates with enableUpdates()

localization information and message resources bundles, with setLocale() and setLocalizedStrings()

Nested Class Summary
`static class`	`WApplication.AjaxMethod` Enumeration that indicates the method for dynamic (AJAX-alike) updates ((deprecated).
`static class`	`WApplication.UpdateLock` A synchronization lock for manipulating and updating the application and its widgets outside of the event loop.

Constructor Summary
`WApplication(WEnvironment env)` Creates a new application instance.

Method Summary
`void`	`addAutoJavaScript(java.lang.String javascript)` Adds JavaScript statements that should be run continuously.
`void`	`addMetaHeader(MetaHeaderType type, java.lang.String name, java.lang.CharSequence content)` Adds an HTML meta header.
`void`	`addMetaHeader(MetaHeaderType type, java.lang.String name, java.lang.CharSequence content, java.lang.String lang)` Adds an HTML meta header.
`void`	`addMetaHeader(java.lang.String name, java.lang.CharSequence content)` Adds an HTML meta header.
`void`	`addMetaHeader(java.lang.String name, java.lang.CharSequence content, java.lang.String lang)` Adds an HTML meta header.
`void`	`attachThread()` Attach an auxiliary thread to this application.
`void`	`attachThread(boolean attach)` Attach an auxiliary thread to this application.
`void`	`bindWidget(WWidget widget, java.lang.String domId)` Binds a top-level widget for a WidgetSet deployment.
`void`	`declareJavaScriptFunction(java.lang.String name, java.lang.String function)` Declares an application-wide JavaScript function.
`void`	`destroy()` Destroys the application session.
`void`	`doJavaScript(java.lang.String javascript)` Executes some JavaScript code.
`void`	`doJavaScript(java.lang.String javascript, boolean afterLoaded)` Executes some JavaScript code.
`protected void`	`enableAjax()` Progresses to an Ajax-enabled user interface.
`void`	`enableUpdates()` Enables server-initiated updates.
`void`	`enableUpdates(boolean enabled)` Enables server-initiated updates.
`WWidget`	`findWidget(java.lang.String name)` Finds a widget by name.
`WApplication.AjaxMethod`	`getAjaxMethod()` Returns the Ajax communication method (deprecated).
`java.lang.String`	`getBodyClass()` Returns the style class set for the entire page <body>.
`java.lang.String`	`getBookmarkUrl()` Returns a URL for the current session.
`java.lang.String`	`getBookmarkUrl(java.lang.String internalPath)` Returns a URL for the current session.
`WStdLocalizedStrings`	`getBuiltinLocalizedStrings()`
`WString`	`getCloseMessage()` Returns the close message.
`java.lang.String`	`getCssTheme()` Returns the theme.
`WEnvironment`	`getEnvironment()` Returns the environment information.
`java.lang.String`	`getHtmlClass()` Returns the style class set for the entire page <html>.
`static WApplication`	`getInstance()` Returns the current application instance.
`java.lang.String`	`getInternalPath()` Returns a URL for the current session.
`java.lang.String`	`getInternalPathNextPart(java.lang.String path)` Returns a URL for the current session.
`java.lang.String`	`getJavaScriptClass()` Returns the name of the application JavaScript class.
`LayoutDirection`	`getLayoutDirection()` Returns the layout direction.
`WLoadingIndicator`	`getLoadingIndicator()` Returns the loading indicator.
`java.util.Locale`	`getLocale()` Returns the current locale.
`WLocalizedStrings`	`getLocalizedStrings()` Returns the resource object that provides localized strings.
`long`	`getMaximumRequestSize()` Returns the current maximum size of a request to the application.
`static java.lang.String`	`getResourcesUrl()` Returns the URL at which the resources are deployed.
`WContainerWidget`	`getRoot()` Returns the root container.
`java.lang.String`	`getSessionId()` Returns the unique identifier for the current session.
`WCssStyleSheet`	`getStyleSheet()` Returns a reference to the inline style sheet.
`WString`	`getTitle()` Returns the window title.
`WApplication.UpdateLock`	`getUpdateLock()` Grabs and returns the lock for manipulating widgets outside the event loop.
`EventSignal`	`globalEnterPressed()` Event signal emitted when enter was pressed.
`EventSignal`	`globalEscapePressed()` Event signal emitted when escape was pressed.
`EventSignal1<WKeyEvent>`	`globalKeyPressed()` Event signal emitted when a "character" was entered.
`EventSignal1<WKeyEvent>`	`globalKeyWentDown()` Event signal emitted when a keyboard key is pushed down.
`EventSignal1<WKeyEvent>`	`globalKeyWentUp()` Event signal emitted when a keyboard key is released.
`Signal1<java.lang.String>`	`internalPathChanged()` Signal which indicates that the user changes the internal path.
`boolean`	`internalPathMatches(java.lang.String path)` Checks if the internal path matches a given path.
`java.lang.String`	`internalSubPath(java.lang.String path)` Returns a URL for the current session.
`protected boolean`	`isExposed(WWidget w)` Returns whether a widget is exposed in the interface.
`boolean`	`isQuited()` Returns whether the application is quited.
`boolean`	`isUpdatesEnabled()` Returns whether server-initiated updates are enabled.
`void`	`loadJavaScript(java.lang.String jsFile, eu.webtoolkit.jwt.WJavaScriptPreamble preamble)`
`java.lang.String`	`makeAbsoluteUrl(java.lang.String url)` Makes an absolute URL.
`protected void`	`notify(WEvent e)` Notifies an event to the application.
`static boolean`	`pathMatches(java.lang.String path, java.lang.String query)`
`void`	`processEvents()` Processes UI events.
`void`	`quit()` Quits the application.
`static java.lang.String`	`readConfigurationProperty(java.lang.String name, java.lang.String value)` Reads a configuration property.
`void`	`redirect(java.lang.String url)` Redirects the application to another location.
`void`	`refresh()` Refreshes the application.
`void`	`removeCookie(java.lang.String name)`
`void`	`removeCookie(java.lang.String name, java.lang.String domain)`
`void`	`removeCookie(java.lang.String name, java.lang.String domain, java.lang.String path)`
`void`	`removeMetaHeader(MetaHeaderType type)` Removes one or all meta headers.
`void`	`removeMetaHeader(MetaHeaderType type, java.lang.String name)` Removes one or all meta headers.
`Signal1<java.lang.Integer>`	`requestTooLarge()` Signal which indicates that too a large request was received.
`boolean`	`require(java.lang.String uri)` Loads a JavaScript library.
`boolean`	`require(java.lang.String uri, java.lang.String symbol)` Loads a JavaScript library.
`java.lang.String`	`resolveRelativeUrl(java.lang.String url)` "Resolves" a relative URL taking into account internal paths.
`void`	`setAjaxMethod(WApplication.AjaxMethod method)` Deprecated. this setting is no longer needed.
`void`	`setBodyClass(java.lang.String styleClass)` Sets a style class to the entire page <body>.
`void`	`setConfirmCloseMessage(java.lang.CharSequence message)` Sets the message for the user to confirm closing of the application window/tab.
`void`	`setCookie(java.lang.String name, java.lang.String value, int maxAge)` Sets a new cookie.
`void`	`setCookie(java.lang.String name, java.lang.String value, int maxAge, java.lang.String domain)` Sets a new cookie.
`void`	`setCookie(java.lang.String name, java.lang.String value, int maxAge, java.lang.String domain, java.lang.String path)` Sets a new cookie.
`void`	`setCookie(java.lang.String name, java.lang.String value, int maxAge, java.lang.String domain, java.lang.String path, boolean secure)` Sets a new cookie.
`void`	`setCookie(java.lang.String name, java.lang.String value, WDate expires)`
`void`	`setCookie(java.lang.String name, java.lang.String value, WDate expires, java.lang.String domain)`
`void`	`setCookie(java.lang.String name, java.lang.String value, WDate expires, java.lang.String domain, java.lang.String path)`
`void`	`setCookie(java.lang.String name, java.lang.String value, WDate expires, java.lang.String domain, java.lang.String path, boolean secure)`
`void`	`setCssTheme(java.lang.String theme)` Sets the theme.
`void`	`setFocus(java.lang.String id, int selectionStart, int selectionEnd)`
`void`	`setHtmlClass(java.lang.String styleClass)` Sets a style class to the entire page <html>.
`void`	`setInternalPath(java.lang.String path)` Changes the internal path.
`void`	`setInternalPath(java.lang.String path, boolean emitChange)` Changes the internal path.
`void`	`setJavaScriptClass(java.lang.String javaScriptClass)` Sets the name of the application JavaScript class.
`void`	`setLayoutDirection(LayoutDirection direction)` Sets the layout direction.
`void`	`setLoadingIndicator(WLoadingIndicator indicator)` Sets the loading indicator.
`void`	`setLocale(java.util.Locale locale)` Changes the locale.
`void`	`setLocalizedStrings(WLocalizedStrings translator)` Sets the resource object that provides localized strings.
`void`	`setTitle(java.lang.CharSequence title)` Sets the window title.
`void`	`setTwoPhaseRenderingThreshold(int bytes)` Changes the threshold for two-phase rendering.
`void`	`triggerUpdate()` Propagates server-initiated updates.
`protected void`	`unload()` Handles a browser unload event.
`java.lang.String`	`url()` Returns a URL for the current session.
`java.lang.String`	`url(java.lang.String internalPath)` Returns a URL for the current session.
`void`	`useStyleSheet(java.lang.String uri)` Adds an external style sheet.
`void`	`useStyleSheet(java.lang.String uri, java.lang.String condition)` Adds an external style sheet, constrained with conditions.
`void`	`useStyleSheet(java.lang.String uri, java.lang.String condition, java.lang.String media)` Adds an external style sheet, constrained with conditions.

Methods inherited from class eu.webtoolkit.jwt.WObject
`getId, getObjectName, remove, setObjectName, tr`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

WApplication

public WApplication(WEnvironment env)

Creates a new application instance.

The environment provides information on the initial request, user agent, and deployment-related information.

Method Detail

getInstance

public static WApplication getInstance()

Returns the current application instance.

This method uses thread-specific storage to fetch the current session.

getEnvironment

public WEnvironment getEnvironment()

Returns the environment information.

This method returns the environment object that was used when constructing the application. The environment provides information on the initial request, user agent, and deployment-related information.

See Also:: url(String internalPath), getSessionId()

getRoot

public WContainerWidget getRoot()

Returns the root container.

This is the top-level widget container of the application, and corresponds to entire browser window. The user interface of your application is represented by the content of this container.

The getRoot() widget is only defined when the application manages the entire window. When deployed as a WidgetSet application, there is no root() container, and null is returned. Instead, use bindWidget() to bind one or more root widgets to existing HTML <div> (or other) elements on the page.

findWidget

public WWidget findWidget(java.lang.String name)

Finds a widget by name.

This finds a widget in the application's widget hierarchy. It does not only consider widgets in the getRoot() , but also widgets that are placed outside this root, such as in dialogs, or other "roots" such as all the bound widgets in a widgetset application.

See Also:: WObject.setObjectName(String name), WWidget.find(String name)

getStyleSheet

public WCssStyleSheet getStyleSheet()

Returns a reference to the inline style sheet.

Widgets may allow configuration of their look and feel through style classes. These may be defined in this inline stylesheet, or in external style sheets.

It is usually preferable to use external stylesheets (and consider more accessible). Still, the internal stylesheet has as benefit that style rules may be dynamically updated, and it is easier to manage logistically.

See Also:: useStyleSheet(String uri), WWidget.setStyleClass(String styleClass)

useStyleSheet

public void useStyleSheet(java.lang.String uri)

Adds an external style sheet.

Widgets may allow configuration of their look and feel through style classes. These may be defined in an inline stylesheet, or in external style sheets.

The url indicates a relative or absolute URL to the stylesheet.

External stylesheets are inserted after the internal style sheet, and can therefore override default styles set by widgets in the internal style sheet.

See Also:: getStyleSheet(), WWidget.setStyleClass(String styleClass)

useStyleSheet

public void useStyleSheet(java.lang.String uri,
                          java.lang.String condition,
                          java.lang.String media)

Adds an external style sheet, constrained with conditions.

If not empty, condition is a string that is used to apply the stylesheet to specific versions of IE. Only a limited subset of the IE conditional comments syntax is supported (since these are in fact interpreted server-side instead of client-side). Examples are:

"IE gte 6": only for IE version 6 or later.
"!IE gte 6": only for IE versions prior to IE6.
"IE lte 7": only for IE versions prior to IE7.

The media indicates the CSS media to which this stylesheet applies. This may be a comma separated list of media. The default value is "all" indicating all media.

The url indicates a relative or absolute URL to the stylesheet.

See Also:: useStyleSheet(String uri)

useStyleSheet

public final void useStyleSheet(java.lang.String uri,
                                java.lang.String condition)

Adds an external style sheet, constrained with conditions.

Calls useStyleSheet(uri, condition, "all")

setCssTheme

public void setCssTheme(java.lang.String theme)

Sets the theme.

The theme provides the look and feel of several built-in widgets, using CSS style rules. Rules for each theme are defined in the resources/themes/theme/ folder.

The default theme is "default". When setting "", the external style sheets related to the theme are not loaded.

getCssTheme

public java.lang.String getCssTheme()

Returns the theme.

See Also:: setCssTheme(String theme)

setLayoutDirection

public void setLayoutDirection(LayoutDirection direction)

Sets the layout direction.

The default direction is LeftToRight.

This sets the language text direction, which by itself sets the default text alignment and reverse the column orders of <table> elements.

In addition, JWt will take this setting into account in WTextEdit, WTableView and WTreeView (so that columns are reverted), and swap the behaviour of WWidget#setFloatSide() and WWidget#setOffsets() for RightToLeft languages. Note that CSS settings themselves are not affected by this setting, and thus for example "float: right" will move a box to the right, irrespective of the layout direction.

The library sets "Wt-ltr" or "Wt-rtl" as style classes for the document body. You may use this if to override certain style rules for a Right-to-Left document.

For example:

 body        .sidebar { float: right; }
    body.Wt-rtl .sidebar { float: left; }

Note: The layout direction can be set only at application startup and does not have the effect of rerendering the entire UI.

getLayoutDirection

public LayoutDirection getLayoutDirection()

Returns the layout direction.

See Also:: setLayoutDirection(LayoutDirection direction)

setBodyClass

public void setBodyClass(java.lang.String styleClass)

Sets a style class to the entire page <body>.

See Also:: setHtmlClass(String styleClass)

getBodyClass

public java.lang.String getBodyClass()

Returns the style class set for the entire page <body>.

See Also:: setBodyClass(String styleClass)

setHtmlClass

public void setHtmlClass(java.lang.String styleClass)

Sets a style class to the entire page <html>.

See Also:: setBodyClass(String styleClass)

getHtmlClass

public java.lang.String getHtmlClass()

Returns the style class set for the entire page <html>.

See Also:: setHtmlClass(String styleClass)

setTitle

public void setTitle(java.lang.CharSequence title)

Sets the window title.

Sets the browser window title to title.

The default title is "".

See Also:: getTitle()

getTitle

public WString getTitle()

Returns the window title.

See Also:: setTitle(CharSequence title)

getCloseMessage

public WString getCloseMessage()

Returns the close message.

See Also:: setConfirmCloseMessage(CharSequence message)

getLocalizedStrings

public WLocalizedStrings getLocalizedStrings()

Returns the resource object that provides localized strings.

This returns the object previously set using setLocalizedStrings().

WString#tr() is used to create localized strings, whose localized translation is looked up through this object, using a key.

See Also:: WString.tr(String key)

getBuiltinLocalizedStrings

public WStdLocalizedStrings getBuiltinLocalizedStrings()

setLocalizedStrings

public void setLocalizedStrings(WLocalizedStrings translator)

Sets the resource object that provides localized strings.

The translator resolves localized strings within the current application locale.

See Also:: getLocalizedStrings(), WString.tr(String key)

setLocale

public void setLocale(java.util.Locale locale)

Changes the locale.

The locale is used by the localized strings resource to resolve localized strings.

By passing an empty locale, the default locale is chosen.

When the locale is changed, refresh() is called, which will resolve the strings of the current user-interface in the new locale.

At construction, the locale is copied from the environment ( WEnvironment#getLocale()), and this is the locale that was configured by the user in his browser preferences, and passed using an HTTP request header.

See Also:: getLocalizedStrings(), WString.tr(String key)

getLocale

public java.util.Locale getLocale()

Returns the current locale.

refresh

public void refresh()

Refreshes the application.

This lets the application to refresh its data, including strings from message-resource bundles. This done by propagating WWidget#refresh() through the widget hierarchy.

This method is also called when the user hits the refresh (or reload) button, if this can be caught within the current session.

The reload button may only be caught when cookies for session tracking are configured in the servlet container.

See Also:: WWidget.refresh()

bindWidget

public void bindWidget(WWidget widget,
                       java.lang.String domId)

Binds a top-level widget for a WidgetSet deployment.

This method binds a widget to an existing element with DOM id domId on the page. The element type should correspond with the widget type (e.g. it should be a <div> for a WContainerWidget, or a <table> for a WTable).

See Also:: getRoot(), EntryPointType.WidgetSet

url

public java.lang.String url(java.lang.String internalPath)

Returns a URL for the current session.

Returns the (relative) URL for this application session (including the session ID if necessary). The URL includes the full application path, and is expanded by the browser into a full URL.

For example, for an application deployed at

 http://www.mydomain.com/stuff/app.wt

this method might return "/stuff/app.wt?wtd=AbCdEf". Additional query parameters can be appended in the form of "&param1=value&param2=value".

To obtain a URL that is suitable for bookmarking the current application state, to be used across sessions, use getBookmarkUrl() instead.

See Also:: redirect(String url), WEnvironment.getHostName(), WEnvironment.getUrlScheme(), getBookmarkUrl()

url

public final java.lang.String url()

Returns a URL for the current session.

Returns url("")

makeAbsoluteUrl

public java.lang.String makeAbsoluteUrl(java.lang.String url)

Makes an absolute URL.

Returns an absolute URL for a given (relative url) by including the schema, hostname, and deployment path.

If url is "", then the absolute base URL is returned. This is the absolute URL at which the application is deployed, up to the last '/'.

This is not used in the library, except when a public URL is needed, e.g. for inclusion in an email.

You may want to reimplement this method when the application is hosted behind a reverse proxy or when in general the returned URL is wrong.

resolveRelativeUrl

public java.lang.String resolveRelativeUrl(java.lang.String url)

"Resolves" a relative URL taking into account internal paths.

Using HTML5 History API or in a plain HTML session (without ugly internal paths), the internal path is present as a full part of the URL. This has a consequence that relative URLs, if not dealt with, would be resolved against the last 'folder' name of the internal path, rather than against the application deployment path (which is what you probably want).

When using a widgetset mode deployment, or when configuring a baseURL property in the configuration, this method will make an absolute URL so that the property is fetched from the right server.

Otherwise, this method will fixup a relative URL so that it resolves correctly against the base path of an application. This does not necessarily mean that the URL is resolved into an absolute URL. In fact, JWt will simply prepend a sequence of "../" path elements to correct for the internal path. When passed an absolute URL (i.e. starting with '/'), the url is returned unchanged.

For URLs passed to the JWt API (and of which the library knows it is represents a URL) this method is called internally by the library. But it may be useful for URLs which are set e.g. inside a WTemplate.

getBookmarkUrl

public java.lang.String getBookmarkUrl()

Returns a URL for the current session.

Returns the (relative) URL for this application session (including the session ID if necessary). The URL includes the full application path, and is expanded by the browser into a full URL.

For example, for an application deployed at

 http://www.mydomain.com/stuff/app.wt

this method might return "/stuff/app.wt?wtd=AbCdEf". Additional query parameters can be appended in the form of "&param1=value&param2=value".

To obtain a URL that is suitable for bookmarking the current application state, to be used across sessions, use getBookmarkUrl() instead.

See Also:: redirect(String url), WEnvironment.getHostName(), WEnvironment.getUrlScheme(), getBookmarkUrl()

getBookmarkUrl

public java.lang.String getBookmarkUrl(java.lang.String internalPath)

Returns a URL for the current session.

Returns the (relative) URL for this application session (including the session ID if necessary). The URL includes the full application path, and is expanded by the browser into a full URL.

For example, for an application deployed at

 http://www.mydomain.com/stuff/app.wt

this method might return "/stuff/app.wt?wtd=AbCdEf". Additional query parameters can be appended in the form of "&param1=value&param2=value".

To obtain a URL that is suitable for bookmarking the current application state, to be used across sessions, use getBookmarkUrl() instead.

See Also:: redirect(String url), WEnvironment.getHostName(), WEnvironment.getUrlScheme(), getBookmarkUrl()

setInternalPath

public void setInternalPath(java.lang.String path,
                            boolean emitChange)

Changes the internal path.

A JWt application may manage multiple virtual paths. The virtual path is appended to the application URL. Depending on the situation, the path is directly appended to the application URL or it is appended using a name anchor (#).

For example, for an application deployed at:

 http://www.mydomain.com/stuff/app.wt

for which an internalPath "/project/z3cbc/details/" is set, the two forms for the application URL are:

in an AJAX session (HTML5):

 http://www.mydomain.com/stuff/app.wt/project/z3cbc/details/

in an AJAX session (HTML4):

 http://www.mydomain.com/stuff/app.wt#/project/z3cbc/details/

in a plain HTML session:

 http://www.mydomain.com/stuff/app.wt/project/z3cbc/details/

Note, since JWt 3.1.9, the actual form of the URL no longer affects relative URL resolution, since now JWt includes an HTML meta base tag which points to the deployment path, regardless of the current internal path. This does break deployments behind a reverse proxy which changes paths.

When the internal path is changed, an entry is added to the browser history. When the user navigates back and forward through this history (using the browser back/forward buttons), an internalPathChanged() event is emitted. You should listen to this signal to switch the application to the corresponding state. When emitChange is true, this signal is also emitted by setting the path.

A url that includes the internal path may be obtained using getBookmarkUrl().

The internalPath must start with a '/'. In this way, you can still use normal anchors in your HTML. Internal path changes initiated in the browser to paths that do not start with a '/' are ignored.

See Also:: getBookmarkUrl(), getBookmarkUrl(), internalPathChanged()

setInternalPath

public final void setInternalPath(java.lang.String path)

Changes the internal path.

Calls setInternalPath(path, false)

getInternalPath

public java.lang.String getInternalPath()

Returns a URL for the current session.

Returns the (relative) URL for this application session (including the session ID if necessary). The URL includes the full application path, and is expanded by the browser into a full URL.

For example, for an application deployed at

 http://www.mydomain.com/stuff/app.wt

this method might return "/stuff/app.wt?wtd=AbCdEf". Additional query parameters can be appended in the form of "&param1=value&param2=value".

To obtain a URL that is suitable for bookmarking the current application state, to be used across sessions, use getBookmarkUrl() instead.

See Also:: redirect(String url), WEnvironment.getHostName(), WEnvironment.getUrlScheme(), getBookmarkUrl()

getInternalPathNextPart

public java.lang.String getInternalPathNextPart(java.lang.String path)

Returns a URL for the current session.

Returns the (relative) URL for this application session (including the session ID if necessary). The URL includes the full application path, and is expanded by the browser into a full URL.

For example, for an application deployed at

 http://www.mydomain.com/stuff/app.wt

this method might return "/stuff/app.wt?wtd=AbCdEf". Additional query parameters can be appended in the form of "&param1=value&param2=value".

To obtain a URL that is suitable for bookmarking the current application state, to be used across sessions, use getBookmarkUrl() instead.

See Also:: redirect(String url), WEnvironment.getHostName(), WEnvironment.getUrlScheme(), getBookmarkUrl()

internalSubPath

public java.lang.String internalSubPath(java.lang.String path)

Returns a URL for the current session.

Returns the (relative) URL for this application session (including the session ID if necessary). The URL includes the full application path, and is expanded by the browser into a full URL.

For example, for an application deployed at

 http://www.mydomain.com/stuff/app.wt

this method might return "/stuff/app.wt?wtd=AbCdEf". Additional query parameters can be appended in the form of "&param1=value&param2=value".

To obtain a URL that is suitable for bookmarking the current application state, to be used across sessions, use getBookmarkUrl() instead.

See Also:: redirect(String url), WEnvironment.getHostName(), WEnvironment.getUrlScheme(), getBookmarkUrl()

internalPathMatches

public boolean internalPathMatches(java.lang.String path)

Checks if the internal path matches a given path.

Returns whether the current getBookmarkUrl() starts with path (or is equal to path). You will typically use this method within a slot conneted to the internalPathChanged() signal, to check that an internal path change affects the widget. It may also be useful before changing path using getBookmarkUrl() if you do not intend to remove sub paths when the current internal path already matches path.

The path must start with a '/'.

See Also:: getBookmarkUrl(), getBookmarkUrl()

internalPathChanged

public Signal1<java.lang.String> internalPathChanged()

Signal which indicates that the user changes the internal path.

This signal indicates a change to the internal path, which is usually triggered by the user using the browser back/forward buttons.

The argument contains the new internal path.

See Also:: getBookmarkUrl()

redirect

public void redirect(java.lang.String url)

Redirects the application to another location.

The client will be redirected to a new location identified by url. Use this in conjunction with quit() if you want to the application to be terminated as well.

Calling redirect() does not imply quit() since it may be useful to switch between a non-secure and secure (SSL) transport connection.

getResourcesUrl

public static java.lang.String getResourcesUrl()

Returns the URL at which the resources are deployed.

getSessionId

public java.lang.String getSessionId()

Returns the unique identifier for the current session.

The session id is a string that uniquely identifies the current session. Note that the actual contents has no particular meaning and client applications should in no way try to interpret its value.

enableUpdates

public void enableUpdates(boolean enabled)

Enables server-initiated updates.

By default, updates to the user interface are possible only at startup, during any event (in a slot), or at regular time points using WTimer. This is the normal JWt event loop.

In some cases, one may want to modify the user interface from a second thread, outside the event loop. While this may be worked around by the WTimer, in some cases, there are bandwidth and processing overheads associated which may be unnecessary, and which create a trade-off with time resolution of the updates.

When enabled is true, this enables "server push" (what is called 'comet' in AJAX terminology). Widgets may then be modified, created or deleted outside of the event loop (e.g. in response to execution of another thread), and these changes are propagated by calling triggerUpdate().

Note that you need to grab the application's update lock to avoid concurrency problems, whenever you modify the application's state from another thread.

An example of how to modify the widget tree outside the event loop and propagate changes is:

 // You need to have a reference to the application whose state
    // you are about to manipulate.
    WApplication app = ...;
   
    // Grab the application lock
    WApplication.UpdateLock lock = app.getUpdateLock();
   
    try {
      // We now have exclusive access to the application:
      // we can safely modify the widget tree for example.
      app.getRoot().addWidget(new WText("Something happened!"));
   
      // Push the changes to the browser
      app.triggerUpdate();
    } finally {
      lock.release();
    }

This works only if your servlet container supports the Servlet 3.0 API. If you try to invoke this function on a servlet container with no such support, an exception will be thrown.

Note: This works only if JavaScript is available on the client.

See Also:: triggerUpdate()

enableUpdates

public final void enableUpdates()

Enables server-initiated updates.

Calls enableUpdates(true)

isUpdatesEnabled

public boolean isUpdatesEnabled()

Returns whether server-initiated updates are enabled.

See Also:: enableUpdates(boolean enabled)

triggerUpdate

public void triggerUpdate()

Propagates server-initiated updates.

This propagate changes made to the user interface outside of the main event loop, e.g. from another thread or from within WServer::post(). This call only has an effect after updates have been enabled (from within the normal event loop), using enableUpdates().

See Also:: enableUpdates(boolean enabled)

getUpdateLock

public WApplication.UpdateLock getUpdateLock()

Grabs and returns the lock for manipulating widgets outside the event loop.

You need to keep this lock in scope while manipulating widgets outside of the event loop. In normal cases, inside the JWt event loop, you do not need to care about it.

See Also:: enableUpdates(boolean enabled), triggerUpdate()

attachThread

public void attachThread(boolean attach)

Attach an auxiliary thread to this application.

In a multi-threaded environment, getInstance() uses thread-local data to retrieve the application object that corresponds to the session currently being handled by the thread. This is set automatically by the library whenever an event is delivered to the application, or when you use the WApplication.UpdateLock to modify the application from an auxiliary thread outside the normal event loop.

When you want to manipulate the widget tree inside the main event loop, but from within an auxiliary thread, then you cannot use the WApplication.UpdateLock since this will create an immediate dead lock. Instead, you may attach the auxiliary thread to the application, by calling this method from the auxiliary thread, and in this way you can modify the application from within that thread without needing the update lock.

Calling attachThread() with attach = false, detaches the current thread.

attachThread

public final void attachThread()

Attach an auxiliary thread to this application.

Calls attachThread(true)

doJavaScript

public void doJavaScript(java.lang.String javascript,
                         boolean afterLoaded)

Executes some JavaScript code.

This method may be used to call some custom javaScript code as part of an event response.

This function does not wait until the JavaScript is run, but returns immediately. The JavaScript will be run after the normal event handling, unless afterLoaded is set to false.

See Also:: addAutoJavaScript(String javascript), declareJavaScriptFunction(String name, String function)

doJavaScript

public final void doJavaScript(java.lang.String javascript)

Executes some JavaScript code.

Calls doJavaScript(javascript, true)

addAutoJavaScript

public void addAutoJavaScript(java.lang.String javascript)

Adds JavaScript statements that should be run continuously.

This is an internal method.

It is used by for example layout managers to adjust the layout whenever the DOM tree is manipulated.

See Also:: doJavaScript(String javascript, boolean afterLoaded)

declareJavaScriptFunction

public void declareJavaScriptFunction(java.lang.String name,
                                      java.lang.String function)

Declares an application-wide JavaScript function.

This is an internal method.

require

public boolean require(java.lang.String uri,
                       java.lang.String symbol)

Loads a JavaScript library.

Loads a JavaScript library located at the URL url. JWt keeps track of libraries (with the same URL) that already have been loaded, and will load a library only once. In addition, you may provide a symbol which if already defined will also indicate that the library was already loaded (possibly outside of JWt when in WidgetSet mode).

This method returns true only when the library is loaded for the first time.

JavaScript libraries may be loaded at any point in time. Any JavaScript code is deferred until the library is loaded, except for JavaScript that was defined to load before, passing false as second parameter to doJavaScript().

require

public final boolean require(java.lang.String uri)

Loads a JavaScript library.

Returns require(uri, "")

setJavaScriptClass

public void setJavaScriptClass(java.lang.String javaScriptClass)

Sets the name of the application JavaScript class.

This should be called right after construction of the application, and changing the JavaScript class is only supported for WidgetSet mode applications. The className should be a valid JavaScript identifier, and should also be unique in a single page.

getJavaScriptClass

public java.lang.String getJavaScriptClass()

Returns the name of the application JavaScript class.

This JavaScript class encapsulates all JavaScript methods specific to this application instance. The method is foreseen to allow multiple applications to run simultaneously on the same page in Wt::WidgtSet mode, without interfering.

processEvents

public void processEvents()

Processes UI events.

You may call this method during a long operation to:

propagate widget changes to the client.
process UI events.

This method starts a recursive event loop, blocking the current thread, and resumes when all pending user interface events have been processed.

Because a thread is blocked, this may affect your application scalability.

readConfigurationProperty

public static java.lang.String readConfigurationProperty(java.lang.String name,
                                                         java.lang.String value)

Reads a configuration property.

Tries to read a configured value for the property name. If no value was configured, the default value is returned.

setAjaxMethod

public void setAjaxMethod(WApplication.AjaxMethod method)

Deprecated. this setting is no longer needed.

Sets the Ajax communication method (deprecated).

This method has no effect.

Since JWt 3.1.8, a communication method that works is detected at run time. For widget set mode, cross-domain Ajax is chosen if available.

getAjaxMethod

public WApplication.AjaxMethod getAjaxMethod()

Returns the Ajax communication method (deprecated).

See Also:: setAjaxMethod(WApplication.AjaxMethod method)

destroy

public void destroy()

Destroys the application session.

The application is destroyed when the session is invalidated. You should put here any logic which is needed to cleanup the application session.

The default implementation does nothing.

setTwoPhaseRenderingThreshold

public void setTwoPhaseRenderingThreshold(int bytes)

Changes the threshold for two-phase rendering.

This changes the threshold for the size of a JavaScript response (in bytes) to render invisible changes in one go. If the bandwidth for rendering the invisible changes exceed the threshold, they will be fetched in a second communication, after the visible changes have been rendered.

The value is a trade-off: setting it smaller will always use two-phase rendering, increasing the total render time but reducing the latency for the visible changes. Setting it too large will increase the latency to render the visible changes, since first also all invisible changes need to be computed and received in the browser.

setCookie

public void setCookie(java.lang.String name,
                      java.lang.String value,
                      int maxAge,
                      java.lang.String domain,
                      java.lang.String path,
                      boolean secure)

Sets a new cookie.

Use cookies to transfer information across different sessions (e.g. a user name). In a subsequent session you will be able to read this cookie using WEnvironment#getCookie(). You cannot use a cookie to store information in the current session.

The name must be a valid cookie name (of type 'token': no special characters or separators, see RFC2616 page 16). The value may be anything. Specify the maximum age (in seconds) after which the client must discard the cookie. To delete a cookie, use a value of '0'.

By default the cookie only applies to the application deployment path ( WEnvironment#getDeploymentPath() ) in the current domain. To set a proper value for domain, see also RFC2109.

See Also:: WEnvironment.supportsCookies(), WEnvironment.getCookie(String cookieNname)

setCookie

public final void setCookie(java.lang.String name,
                            java.lang.String value,
                            int maxAge)

Sets a new cookie.

Calls setCookie(name, value, maxAge, "", "", false)

setCookie

public final void setCookie(java.lang.String name,
                            java.lang.String value,
                            int maxAge,
                            java.lang.String domain)

Sets a new cookie.

Calls setCookie(name, value, maxAge, domain, "", false)

setCookie

public final void setCookie(java.lang.String name,
                            java.lang.String value,
                            int maxAge,
                            java.lang.String domain,
                            java.lang.String path)

Sets a new cookie.

Calls setCookie(name, value, maxAge, domain, path, false)

setCookie

public void setCookie(java.lang.String name,
                      java.lang.String value,
                      WDate expires,
                      java.lang.String domain,
                      java.lang.String path,
                      boolean secure)

setCookie

public final void setCookie(java.lang.String name,
                            java.lang.String value,
                            WDate expires)

setCookie

public final void setCookie(java.lang.String name,
                            java.lang.String value,
                            WDate expires,
                            java.lang.String domain)

setCookie

public final void setCookie(java.lang.String name,
                            java.lang.String value,
                            WDate expires,
                            java.lang.String domain,
                            java.lang.String path)

removeCookie

public void removeCookie(java.lang.String name,
                         java.lang.String domain,
                         java.lang.String path)

removeCookie

public final void removeCookie(java.lang.String name)

removeCookie

public final void removeCookie(java.lang.String name,
                               java.lang.String domain)

addMetaHeader

public void addMetaHeader(java.lang.String name,
                          java.lang.CharSequence content,
                          java.lang.String lang)

Adds an HTML meta header.

A meta header can only be added in the following situations:

when a plain HTML session is used (including when the user agent is a bot), you can add meta headers at any time.

or, when DOCREFprogressive bootstrap is used, you can set meta headers for any type of session, from within the application constructor (which corresponds to the initial request).

but never for a EntryPointType.WidgetSet mode application since then the application is hosted within a foreign HTML page.

When a header was previously set for the same name, its contents is replaced.

These situations coincide with WEnvironment#hasAjax() returning false (see getEnvironment()).

addMetaHeader

public final void addMetaHeader(java.lang.String name,
                                java.lang.CharSequence content)

Adds an HTML meta header.

Calls addMetaHeader(name, content, "")

addMetaHeader

public void addMetaHeader(MetaHeaderType type,
                          java.lang.String name,
                          java.lang.CharSequence content,
                          java.lang.String lang)

Adds an HTML meta header.

This overloaded method allows to define both "name" meta headers, relating to document properties as well as "http-equiv" meta headers, which define HTTP headers.

See Also:: removeMetaHeader(MetaHeaderType type, String name)

addMetaHeader

public final void addMetaHeader(MetaHeaderType type,
                                java.lang.String name,
                                java.lang.CharSequence content)

Adds an HTML meta header.

Calls addMetaHeader(type, name, content, "")

removeMetaHeader

public void removeMetaHeader(MetaHeaderType type,
                             java.lang.String name)

Removes one or all meta headers.

Removes the meta header with given type and name (if it is present). If name is empty, all meta headers of the given type are removed.

See Also:: addMetaHeader(String name, CharSequence content, String lang)

removeMetaHeader

public final void removeMetaHeader(MetaHeaderType type)

Removes one or all meta headers.

Calls removeMetaHeader(type, "")

setLoadingIndicator

public void setLoadingIndicator(WLoadingIndicator indicator)

Sets the loading indicator.

The loading indicator is shown to indicate that a response from the server is pending or JavaScript is being evaluated.

The default loading indicator is a WDefaultLoadingIndicator.

When setting a new loading indicator, the previous one is deleted.

getLoadingIndicator

public WLoadingIndicator getLoadingIndicator()

Returns the loading indicator.

See Also:: setLoadingIndicator(WLoadingIndicator indicator)

quit

public void quit()

Quits the application.

The method returns immediately, but has as effect that the application will be terminated after the current event is completed.

The current widget tree (including any modifications still pending and applied during the current event handling) will still be rendered, after which the application is terminated.

You might want to make sure no more events can be received from the user, by not having anything clickable, for example by displaying only text. Even better is to redirect() the user to another, static, page in conjunction with quit().

See Also:: redirect(String url)

isQuited

public boolean isQuited()

Returns whether the application is quited.

See Also:: quit()

getMaximumRequestSize

public long getMaximumRequestSize()

Returns the current maximum size of a request to the application.

The returned value is the maximum request size in bytes.

See Also:: requestTooLarge()

requestTooLarge

public Signal1<java.lang.Integer> requestTooLarge()

Signal which indicates that too a large request was received.

The integer parameter is the request size that was received in bytes.

globalKeyWentDown

public EventSignal1<WKeyEvent> globalKeyWentDown()

Event signal emitted when a keyboard key is pushed down.

The application receives key events when no widget currently has focus. Otherwise, key events are handled by the widget in focus, and its ancestors.

See Also:: WInteractWidget.keyWentDown()

globalKeyPressed

public EventSignal1<WKeyEvent> globalKeyPressed()

Event signal emitted when a "character" was entered.

The application receives key events when no widget currently has focus. Otherwise, key events are handled by the widget in focus, and its ancestors.

See Also:: WInteractWidget.keyPressed()

globalKeyWentUp

public EventSignal1<WKeyEvent> globalKeyWentUp()

Event signal emitted when a keyboard key is released.

The application receives key events when no widget currently has focus. Otherwise, key events are handled by the widget in focus, and its ancestors.

See Also:: WInteractWidget.keyWentUp()

globalEnterPressed

public EventSignal globalEnterPressed()

Event signal emitted when enter was pressed.

The application receives key events when no widget currently has focus. Otherwise, key events are handled by the widget in focus, and its ancestors.

See Also:: WInteractWidget.enterPressed()

globalEscapePressed

public EventSignal globalEscapePressed()

Event signal emitted when escape was pressed.

The application receives key events when no widget currently has focus. Otherwise, key events are handled by the widget in focus, and its ancestors.

See Also:: WInteractWidget.escapePressed()

setFocus

public void setFocus(java.lang.String id,
                     int selectionStart,
                     int selectionEnd)

loadJavaScript

public void loadJavaScript(java.lang.String jsFile,
                           eu.webtoolkit.jwt.WJavaScriptPreamble preamble)

setConfirmCloseMessage

public void setConfirmCloseMessage(java.lang.CharSequence message)

Sets the message for the user to confirm closing of the application window/tab.

If the message is empty, then the user may navigate away from the page without confirmation.

Otherwise the user will be prompted with a browser-specific dialog asking him to confirm leaving the page. This message is added to the page.

See Also:: unload()

pathMatches

public static boolean pathMatches(java.lang.String path,
                                  java.lang.String query)

notify

protected void notify(WEvent e)
               throws java.io.IOException

Notifies an event to the application.

This method is called by the event loop for propagating an event to the application. It provides a single point of entry for events to the application, besides the application constructor.

You may want to reimplement this method for two reasons:

for having a single point for exception handling: while you may want to catch recoverable exceptions in a more appropriate place, general (usually fatal) exceptions may be caught here. You will in probably also want to catch the same exceptions in the application constructor in the same way.
you want to manage resource usage during requests. For example, at the end of request handling, you want to return a database session back to the pool. Since notify() is also used for rendering right after the application is created, this will also clean up resources after application construction.

In either case, you will need to call the base class implementation of notify(), as otherwise no events will be delivered to your application.

The following shows a generic template for reimplementhing this method for both managing request resources and generic exception handling.

 void notify(WEvent event) {
        // Grab resources for during request handling
        try {
                super.notify(event);
        } catch (MyException exception) {
                // handle this exception in a central place
        }
        // Free resources used during request handling
 }

Note that any uncaught exception throw during event handling terminates the session.

Throws:: java.io.IOException

isExposed

protected boolean isExposed(WWidget w)

Returns whether a widget is exposed in the interface.

The default implementation simply returns true, unless a modal dialog is active, in which case it returns true only for widgets that are inside the dialog.

You may want to reimplement this method if you wish to disallow events from certain widgets even when they are inserted in the widget hierachy.

enableAjax

protected void enableAjax()

Progresses to an Ajax-enabled user interface.

This method is called when the progressive bootstrap method is used, and support for AJAX has been detected. The default behavior will propagate the WWidget#enableAjax() method through the widget hierarchy.

You may want to reimplement this method if you want to make changes to the user-interface when AJAX is enabled. You should always call the base implementation.

See Also:: WWidget.enableAjax()

unload

protected void unload()

Handles a browser unload event.

The browser unloads the application when the user navigates away or when he closes the window or tab.

When reload-is-new-session is set to true, then the default implementation of this method terminates this session by calling quit(), otherwise the session is scheduled to expire within seconds (since it may be a refresh).

You may want to reimplement this if you want to keep the application running until it times out (as was the behaviour before JWt 3.1.6).

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

eu.webtoolkit.jwt Class WApplication

WApplication

getInstance

getEnvironment

getRoot

findWidget

getStyleSheet

useStyleSheet

useStyleSheet

useStyleSheet

setCssTheme

getCssTheme

setLayoutDirection

getLayoutDirection

setBodyClass

getBodyClass

setHtmlClass

getHtmlClass

setTitle

getTitle

getCloseMessage

getLocalizedStrings

getBuiltinLocalizedStrings

setLocalizedStrings

setLocale

getLocale

refresh

bindWidget

url

url

makeAbsoluteUrl

resolveRelativeUrl

getBookmarkUrl

getBookmarkUrl

setInternalPath

setInternalPath

getInternalPath

getInternalPathNextPart

internalSubPath

internalPathMatches

internalPathChanged

redirect

getResourcesUrl

getSessionId

enableUpdates

enableUpdates

isUpdatesEnabled

triggerUpdate

getUpdateLock

attachThread

attachThread

doJavaScript

doJavaScript

addAutoJavaScript

declareJavaScriptFunction

require

require

setJavaScriptClass

getJavaScriptClass

processEvents

readConfigurationProperty

setAjaxMethod

getAjaxMethod

destroy

setTwoPhaseRenderingThreshold

setCookie

setCookie

setCookie

setCookie

setCookie

setCookie

setCookie

setCookie

removeCookie

removeCookie

removeCookie

addMetaHeader

addMetaHeader

addMetaHeader

addMetaHeader

eu.webtoolkit.jwt
Class WApplication