* The UI is the server side entry point for various client side features that * are not represented as components added to a layout, e.g notifications, sub * windows, and executing javascript in the browser. *
** When a new UI instance is needed, typically because the user opens a URL in a * browser window which points to e.g. {@link VaadinServlet}, all * {@link UIProvider}s registered to the current {@link VaadinServiceSession} * are queried for the UI class that should be used. The selection is by defaylt * based on the {@value VaadinServiceSession#UI_PARAMETER} parameter from * web.xml. *
** After a UI has been created by the application, it is initialized using * {@link #init(VaadinRequest)}. This method is intended to be overridden by the * developer to add components to the user interface and initialize * non-component functionality. The component hierarchy must be initialized by * passing a {@link Component} with the main layout or other content of the view * to {@link #setContent(Component)} or to the constructor of the UI. *
* * @see #init(VaadinRequest) * @see UIProvider * * @since 7.0 */ public abstract class UI extends AbstractSingleComponentContainer implements Action.Container, Action.Notifier, LegacyComponent { /** * Event fired when a UI is removed from the application. */ public static class CleanupEvent extends Event { private static final String CLEANUP_EVENT_IDENTIFIER = "uiCleanup"; public CleanupEvent(UI source) { super(source); } public UI getUI() { return (UI) getSource(); } } /** * Interface for listening {@link UI.CleanupEvent UI cleanup events}. * */ public interface CleanupListener extends EventListener { public static final Method cleanupMethod = ReflectTools.findMethod( CleanupListener.class, "cleanup", CleanupEvent.class); /** * Called when a CleanupListener is notified of a CleanupEvent. * {@link UI#getCurrent()} returnsevent.getUI() within
* this method.
*
* @param event
* The close event that was fired.
*/
public void cleanup(CleanupEvent event);
}
/**
* The application to which this UI belongs
*/
private VaadinServiceSession session;
/**
* List of windows in this UI.
*/
private final LinkedHashSet* The method will return {@code null} if the component is not currently * attached to an application. *
* ** Getting a null value is often a problem in constructors of regular * components and in the initializers of custom composite components. A * standard workaround is to use {@link VaadinServiceSession#getCurrent()} * to retrieve the application instance that the current request relates to. * Another way is to move the problematic initialization to * {@link #attach()}, as described in the documentation of the method. *
* * @return the parent application of the component ornull.
* @see #attach()
*/
@Override
public VaadinServiceSession getSession() {
return session;
}
@Override
public void paintContent(PaintTarget target) throws PaintException {
page.paintContent(target);
if (scrollIntoView != null) {
target.addAttribute("scrollTo", scrollIntoView);
scrollIntoView = null;
}
if (pendingFocus != null) {
// ensure focused component is still attached to this main window
if (pendingFocus.getUI() == this
|| (pendingFocus.getUI() != null && pendingFocus.getUI()
.getParent() == this)) {
target.addAttribute("focused", pendingFocus);
}
pendingFocus = null;
}
if (actionManager != null) {
actionManager.paintActions(null, target);
}
if (isResizeLazy()) {
target.addAttribute(UIConstants.RESIZE_LAZY, true);
}
}
/**
* Fire a click event to all click listeners.
*
* @param object
* The raw "value" of the variable change from the client side.
*/
private void fireClick(Mapnull application.
* * This method is mainly intended for internal use by the framework. *
* * @param session * the application to set * * @throws IllegalStateException * if the application has already been set * * @see #getSession() */ public void setSession(VaadinServiceSession session) { if ((session == null) == (this.session == null)) { throw new IllegalStateException( "VaadinServiceSession has already been set. Old session: " + getSessionDetails(this.session) + ". New session: " + getSessionDetails(session) + "."); } else { if (session == null) { detach(); } this.session = session; } if (session != null) { attach(); } } private static String getSessionDetails(VaadinServiceSession session) { if (session == null) { return null; } else { return session.toString() + " for " + session.getService().getServiceName(); } } /** * Gets the id of the UI, used to identify this UI within its application * when processing requests. The UI id should be present in every request to * the server that originates from this UI. * {@link VaadinService#findUI(VaadinRequest)} uses this id to find the * route to which the request belongs. * * @return */ public int getUIId() { return uiId; } /** * Adds a window as a subwindow inside this UI. To open a new browser window * or tab, you should instead use a {@link UIProvider}. * * @param window * @throws IllegalArgumentException * if the window is already added to an application * @throws NullPointerException * if the givenWindow is null.
*/
public void addWindow(Window window) throws IllegalArgumentException,
NullPointerException {
if (window == null) {
throw new NullPointerException("Argument must not be null");
}
if (window.getUI() != null && window.getUI().getSession() != null) {
throw new IllegalArgumentException(
"Window is already attached to an application.");
}
attachWindow(window);
}
/**
* Helper method to attach a window.
*
* @param w
* the window to add
*/
private void attachWindow(Window w) {
windows.add(w);
w.setParent(this);
markAsDirty();
}
/**
* Remove the given subwindow from this UI.
*
* Since Vaadin 6.5, {@link Window.CloseListener}s are called also when
* explicitly removing a window by calling this method.
*
* Since Vaadin 6.5, returns a boolean indicating if the window was removed
* or not.
*
* @param window
* Window to be removed.
* @return true if the subwindow was removed, false otherwise
*/
public boolean removeWindow(Window window) {
if (!windows.remove(window)) {
// Window window is not a subwindow of this UI.
return false;
}
window.setParent(null);
window.fireClose();
markAsDirty();
return true;
}
/**
* Gets all the windows added to this UI.
*
* @return an unmodifiable collection of windows
*/
public Collection* The {@link VaadinRequest} can be used to get information about the * request that caused this UI to be created. *
* * @param request * the Vaadin request that caused this UI to be created */ protected abstract void init(VaadinRequest request); /** * Sets the thread local for the current UI. This method is used by the * framework to set the current application whenever a new request is * processed and it is cleared when the request has been processed. ** The application developer can also use this method to define the current * UI outside the normal request handling, e.g. when initiating custom * background threads. *
* * @param uI * the UI to register as the current UI * * @see #getCurrent() * @see ThreadLocal */ public static void setCurrent(UI ui) { CurrentInstance.setInheritable(UI.class, ui); } /** * Gets the currently used UI. The current UI is automatically defined when * processing requests to the server. In other cases, (e.g. from background * threads), the current UI is not automatically defined. * * @return the current UI instance if available, otherwisenull
*
* @see #setCurrent(UI)
*/
public static UI getCurrent() {
return CurrentInstance.get(UI.class);
}
public void setScrollTop(int scrollTop) {
throw new RuntimeException("Not yet implemented");
}
@Override
protected ActionManager getActionManager() {
if (actionManager == null) {
actionManager = new ActionManager(this);
}
return actionManager;
}
@Override
public
* Default value: false
*
* @param resizeLazy
* true to use a delay before recalculating sizes, false to
* calculate immediately.
*/
public void setResizeLazy(boolean resizeLazy) {
this.resizeLazy = resizeLazy;
markAsDirty();
}
/**
* Checks whether lazy resize is enabled.
*
* @return true if lazy resize is enabled, false
* if lazy resize is not enabled
*/
public boolean isResizeLazy() {
return resizeLazy;
}
/**
* Add a click listener to the UI. The listener is called whenever the user
* clicks inside the UI. Also when the click targets a component inside the
* UI, provided the targeted component does not prevent the click event from
* propagating.
*
* Use {@link #removeListener(ClickListener)} to remove the listener.
*
* @param listener
* The listener to add
*/
public void addClickListener(ClickListener listener) {
addListener(EventId.CLICK_EVENT_IDENTIFIER, ClickEvent.class, listener,
ClickListener.clickMethod);
}
/**
* Adds a cleanup listener to the UI. Cleanup listeners are invoked when the
* UI is removed from the session due to UI or session expiration.
*
* @param listener
* The CleanupListener that should be added.
*/
public void addCleanupListener(CleanupListener listener) {
addListener(CleanupEvent.CLEANUP_EVENT_IDENTIFIER, CleanupEvent.class,
listener, CleanupListener.cleanupMethod);
}
/**
* @deprecated Since 7.0, replaced by
* {@link #addClickListener(ClickListener)}
**/
@Deprecated
public void addListener(ClickListener listener) {
addClickListener(listener);
}
/**
* Remove a click listener from the UI. The listener should earlier have
* been added using {@link #addListener(ClickListener)}.
*
* @param listener
* The listener to remove
*/
public void removeClickListener(ClickListener listener) {
removeListener(EventId.CLICK_EVENT_IDENTIFIER, ClickEvent.class,
listener);
}
/**
* Removes a cleanup listener from the UI, if previously added with
* {@link #addCleanupListener(CleanupListener)}.
*
* @param listener
* The CleanupListener that should be removed
*/
public void removeCleanupListener(CleanupListener listener) {
removeListener(CleanupEvent.CLEANUP_EVENT_IDENTIFIER,
CleanupEvent.class, listener);
}
/**
* @deprecated Since 7.0, replaced by
* {@link #removeClickListener(ClickListener)}
**/
@Deprecated
public void removeListener(ClickListener listener) {
removeClickListener(listener);
}
@Override
public boolean isConnectorEnabled() {
// TODO How can a UI be invisible? What does it mean?
return isVisible() && isEnabled();
}
public ConnectorTracker getConnectorTracker() {
return connectorTracker;
}
public Page getPage() {
return page;
}
/**
* Returns the navigator attached to this UI or null if there is no
* navigator.
*
* @return
*/
public Navigator getNavigator() {
return navigator;
}
/**
* For internal use only.
*
* @param navigator
*/
public void setNavigator(Navigator navigator) {
this.navigator = navigator;
}
/**
* Setting the caption of a UI is not supported. To set the title of the
* HTML page, use Page.setTitle
*
* @deprecated as of 7.0.0, use {@link Page#setTitle(String)}
*/
@Override
@Deprecated
public void setCaption(String caption) {
throw new UnsupportedOperationException(
"You can not set the title of a UI. To set the title of the HTML page, use Page.setTitle");
}
/**
* Shows a notification message on the middle of the UI. The message
* automatically disappears ("humanized message").
*
* Care should be taken to to avoid XSS vulnerabilities as the caption is
* rendered as html.
*
* @see #showNotification(Notification)
* @see Notification
*
* @param caption
* The message
*
* @deprecated As of 7.0, use Notification.show instead but be aware that
* Notification.show does not allow HTML.
*/
@Deprecated
public void showNotification(String caption) {
Notification notification = new Notification(caption);
notification.setHtmlContentAllowed(true);// Backwards compatibility
getPage().showNotification(notification);
}
/**
* Shows a notification message the UI. The position and behavior of the
* message depends on the type, which is one of the basic types defined in
* {@link Notification}, for instance Notification.TYPE_WARNING_MESSAGE.
*
* Care should be taken to to avoid XSS vulnerabilities as the caption is
* rendered as html.
*
* @see #showNotification(Notification)
* @see Notification
*
* @param caption
* The message
* @param type
* The message type
*
* @deprecated As of 7.0, use Notification.show instead but be aware that
* Notification.show does not allow HTML.
*/
@Deprecated
public void showNotification(String caption, Notification.Type type) {
Notification notification = new Notification(caption, type);
notification.setHtmlContentAllowed(true);// Backwards compatibility
getPage().showNotification(notification);
}
/**
* Shows a notification consisting of a bigger caption and a smaller
* description on the middle of the UI. The message automatically disappears
* ("humanized message").
*
* Care should be taken to to avoid XSS vulnerabilities as the caption and
* description are rendered as html.
*
* @see #showNotification(Notification)
* @see Notification
*
* @param caption
* The caption of the message
* @param description
* The message description
*
* @deprecated As of 7.0, use new Notification(...).show(Page) instead but
* be aware that HTML by default not allowed.
*/
@Deprecated
public void showNotification(String caption, String description) {
Notification notification = new Notification(caption, description);
notification.setHtmlContentAllowed(true);// Backwards compatibility
getPage().showNotification(notification);
}
/**
* Shows a notification consisting of a bigger caption and a smaller
* description. The position and behavior of the message depends on the
* type, which is one of the basic types defined in {@link Notification} ,
* for instance Notification.TYPE_WARNING_MESSAGE.
*
* Care should be taken to to avoid XSS vulnerabilities as the caption and
* description are rendered as html.
*
* @see #showNotification(Notification)
* @see Notification
*
* @param caption
* The caption of the message
* @param description
* The message description
* @param type
* The message type
*
* @deprecated As of 7.0, use new Notification(...).show(Page) instead but
* be aware that HTML by default not allowed.
*/
@Deprecated
public void showNotification(String caption, String description,
Notification.Type type) {
Notification notification = new Notification(caption, description, type);
notification.setHtmlContentAllowed(true);// Backwards compatibility
getPage().showNotification(notification);
}
/**
* Shows a notification consisting of a bigger caption and a smaller
* description. The position and behavior of the message depends on the
* type, which is one of the basic types defined in {@link Notification} ,
* for instance Notification.TYPE_WARNING_MESSAGE.
*
* Care should be taken to avoid XSS vulnerabilities if html content is
* allowed.
*
* @see #showNotification(Notification)
* @see Notification
*
* @param caption
* The message caption
* @param description
* The message description
* @param type
* The type of message
* @param htmlContentAllowed
* Whether html in the caption and description should be
* displayed as html or as plain text
*
* @deprecated As of 7.0, use new Notification(...).show(Page).
*/
@Deprecated
public void showNotification(String caption, String description,
Notification.Type type, boolean htmlContentAllowed) {
getPage()
.showNotification(
new Notification(caption, description, type,
htmlContentAllowed));
}
/**
* Shows a notification message.
*
* @see Notification
* @see #showNotification(String)
* @see #showNotification(String, int)
* @see #showNotification(String, String)
* @see #showNotification(String, String, int)
*
* @param notification
* The notification message to show
*
* @deprecated As of 7.0, use Notification.show instead
*/
@Deprecated
public void showNotification(Notification notification) {
getPage().showNotification(notification);
}
/**
* Returns the timestamp (milliseconds since the epoch) of the last received
* heartbeat for this UI.
*
* @see #heartbeat()
* @see VaadinServiceSession#cleanupInactiveUIs()
*
* @return The time the last heartbeat request occurred.
*/
public long getLastHeartbeatTime() {
return lastHeartbeat;
}
/**
* Returns the timestamp (milliseconds since the epoch) of the last received
* UIDL request for this UI.
*
* @return
*/
public long getLastUidlRequestTime() {
return lastUidlRequest;
}
/**
* Sets the last heartbeat request timestamp for this UI. Called by the
* framework whenever the application receives a valid heartbeat request for
* this UI.
*/
public void setLastHeartbeatTime(long lastHeartbeat) {
this.lastHeartbeat = lastHeartbeat;
}
/**
* Sets the last UIDL request timestamp for this UI. Called by the framework
* whenever the application receives a valid UIDL request for this UI.
*/
public void setLastUidlRequestTime(long lastUidlRequest) {
this.lastUidlRequest = lastUidlRequest;
}
/**
* Gets the theme that was used when the UI was initialized.
*
* @return the theme name
*/
public String getTheme() {
return theme;
}
}