Package muntjac :: Module application :: Class Application
[hide private]
[frames] | no frames]

Class Application

source code

                      object --+    
                               |    
terminal.uri_handler.IUriHandler --+
                                   |
                      object --+   |
                               |   |
     terminal.terminal.ITerminal --+
                                   |
                      object --+   |
                               |   |
terminal.terminal.IErrorListener --+
                                   |
                                  Application

Base class required for all Muntjac applications. This class provides all the basic services required by Muntjac. These services allow external discovery and manipulation of the user, com.vaadin.ui.Window windows and themes, and starting and stopping the application.

As mentioned, all Muntjac applications must inherit this class. However, this is almost all of what one needs to do to create a fully functional application. The only thing a class inheriting the Application needs to do is implement the init method where it creates the windows it needs to perform its function. Note that all applications must have at least one window: the main window. The first unnamed window constructed by an application automatically becomes the main window which behaves just like other windows with one exception: when accessing windows using URLs the main window corresponds to the application URL whereas other windows correspond to a URL gotten by catenating the window's name to the application URL.

See the class muntjac.demo.HelloWorld for a simple example of a fully working application.

Window access. Application provides methods to list, add and remove the windows it contains.

Execution control. This class includes method to start and finish the execution of the application. Being finished means basically that no windows will be available from the application anymore.

Theme selection. The theme selection process allows a theme to be specified at three different levels. When a window's theme needs to be found out, the window itself is queried for a preferred theme. If the window does not prefer a specific theme, the application containing the window is queried. If neither the application prefers a theme, the default theme for the terminal is used. The terminal always defines a default theme.


Authors:
Vaadin Ltd., Richard Lincoln

Version: 1.1.2

Instance Methods [hide private]
 
__init__(self)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature
source code
 
getWindow(self, name)
Gets a window by name.
source code
 
addWindow(self, window)
Adds a new window to the application.
source code
 
_fireWindowAttachEvent(self, window)
Send information to all listeners about new Windows associated with this application.
source code
 
removeWindow(self, window)
Removes the specified window from the application.
source code
 
_fireWindowDetachEvent(self, window) source code
 
getUser(self)
Gets the user of the application.
source code
 
setUser(self, user)
Sets the user of the application instance.
source code
 
getURL(self)
Gets the URL of the application.
source code
 
close(self)
Ends the Application.
source code
 
start(self, applicationUrl, applicationProperties, context)
Starts the application on the given URL.
source code
 
isRunning(self)
Tests if the application is running or if it has been finished.
source code
 
getWindows(self)
Gets the set of windows contained by the application.
source code
 
init(self)
Main initializer of the application.
source code
 
getTheme(self)
Gets the application's theme.
source code
 
setTheme(self, theme)
Sets the application's theme.
source code
 
getMainWindow(self)
Gets the mainWindow of the application.
source code
 
setMainWindow(self, mainWindow)
Sets the mainWindow.
source code
 
getPropertyNames(self)
Returns an enumeration of all the names in this application.
source code
 
getProperty(self, name)
Searches for the property with the specified name in this application.
source code
 
addResource(self, resource)
Adds new resource to the application.
source code
 
removeResource(self, resource)
Removes the resource from the application.
source code
 
getRelativeLocation(self, resource)
Gets the relative uri of the resource.
source code
 
handleURI(self, context, relativeUri)
Application URI handling hub.
source code
 
getLocale(self)
Gets the default locale for this application.
source code
 
setLocale(self, locale)
Sets the default locale for this application.
source code
 
addListener(self, listener, iface=None)
Adds the user change/window attach/window detach listener.
source code
 
addCallback(self, callback, eventType=None, *args) source code
 
removeListener(self, listener, iface=None)
Removes the user change/window attach/window detach listener.
source code
 
removeCallback(self, callback, eventType=None) source code
 
getLogoutURL(self)
Returns the URL user is redirected to on application close.
source code
 
setLogoutURL(self, logoutURL)
Sets the URL user is redirected to on application close.
source code
 
terminalError(self, event)
Invoked by the terminal on any exception that occurs in application and is thrown by the setVariable to the terminal.
source code
 
getContext(self)
Gets the application context.
source code
 
getVersion(self)
Override this method to return correct version number of your Application.
source code
 
getErrorHandler(self)
Gets the application error handler.
source code
 
setErrorHandler(self, errorHandler)
Sets the application error handler.
source code

Inherited from terminal.terminal.ITerminal: getDefaultTheme, getScreenHeight, getScreenWidth

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Class Methods [hide private]
 
getSystemMessages(cls)
Gets the SystemMessages for this application.
source code
Class Variables [hide private]
  _DEFAULT_SYSTEM_MESSAGES = SystemMessages()
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self)
(Constructor)

source code 

x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Overrides: object.__init__
(inherited documentation)

getWindow(self, name)

source code 

Gets a window by name. Returns None if the application is not running or it does not contain a window corresponding to the name.

All windows can be referenced by their names in url http://host:port/foo/bar/ where http://host:port/foo/ is the application url as returned by getURL() and bar is the name of the window.

One should note that this method can, as a side effect create new windows if needed by the application. This can be achieved by overriding the default implementation.

If for some reason user opens another window with same url that is already open, name is modified by adding "_12345678" postfix to the name, where 12345678 is a random number. One can decide to create another window-object for those windows (recommended) or to discard the postfix. If the user has two browser windows pointing to the same window-object on server, synchronization errors are likely to occur.

If no browser-level windowing is used, all defaults are fine and this method can be left as is. In case browser-level windows are needed, it is recommended to create new window-objects on this method from their names if the super.getWindow() does not find existing windows. See below for implementation example:

       # If we already have the requested window, use it
       w = super(Application, self).getWindow(name)
       if w == None:
           # If no window found, create it
           w = Window(name)
           # set windows name to the one requested
           w.setName(name)
           # add it to this application
           addWindow(w)
           # ensure use of window specific url
           w.open( ExternalResource(w.getURL()) )
           # add some content
           w.addComponent( Label("Test window") )

       return w

Note that all returned Window objects must be added to this application instance.

The method should return null if the window does not exists (and is not created as a side-effect) or if the application is not running anymore.

Parameters:
  • name - the name of the window.
Returns:
the window associated with the given URI or None

addWindow(self, window)

source code 

Adds a new window to the application.

This implicitly invokes the Window.setApplication method.

Note that all application-level windows can be accessed by their names in url http://host:port/foo/bar/ where http://host:port/foo/ is the application url as returned by getURL() and bar is the name of the window. Also note that not all windows should be added to application - one can also add windows inside other windows - these windows show as smaller windows inside those windows.

Parameters:
  • window - the new Window to add. If the name of the window is None, an unique name is automatically given for the window.
Raises:
  • ValueError - if a window with the same name as the new window already exists in the application.
  • ValueError - if the given Window is None.

removeWindow(self, window)

source code 

Removes the specified window from the application.

Removing the main window of the Application also sets the main window to null. One must another window to be the main window after this with setMainWindow.

Note that removing window from the application does not close the browser window - the window is only removed from the server-side.

Parameters:
  • window - the window to be removed.

getUser(self)

source code 

Gets the user of the application.

Muntjac doesn't define of use user object in any way - it only provides this getter and setter methods for convenience. The user is any object that has been stored to the application with setUser.

Returns:
the user of the application.

setUser(self, user)

source code 

Sets the user of the application instance. An application instance may have a user associated to it. This can be set in login procedure or application initialization.

A component performing the user login procedure can assign the user property of the application and make the user object available to other components of the application.

Muntjac doesn't define of use user object in any way - it only provides getter and setter methods for convenience. The user reference stored to the application can be read with getUser.

Parameters:
  • user - the new user.

getURL(self)

source code 

Gets the URL of the application.

This is the URL what can be entered to a browser window to start the application. Navigating to the application URL shows the main window ( getMainWindow) of the application. Note that the main window can also be shown by navigating to the window url (Window.getURL).

Returns:
the application's URL.

close(self)

source code 

Ends the Application.

In effect this will cause the application stop returning any windows when asked. When the application is closed, its state is removed from the session and the browser window is redirected to the application logout url set with setLogoutURL. If the logout url has not been set, the browser window is reloaded and the application is restarted.

start(self, applicationUrl, applicationProperties, context)

source code 

Starts the application on the given URL.

This method is called by Muntjac framework when a user navigates to the application. After this call the application corresponds to the given URL and it will return windows when asked for them. There is no need to call this method directly.

Application properties are defined by servlet configuration.

Parameters:
  • applicationUrl - the URL the application should respond to.
  • applicationProperties - the Application properties as specified by the servlet configuration.
  • context - the context application will be running in.

isRunning(self)

source code 

Tests if the application is running or if it has been finished.

Application starts running when its start method has been called and stops when the close is called.

Returns:
True if the application is running, False if not.

getWindows(self)

source code 

Gets the set of windows contained by the application.

Note that the returned set of windows can not be modified.

Returns:
the collection of windows.

init(self)

source code 

Main initializer of the application. The init method is called by the framework when the application is started, and it should perform whatever initialization operations the application needs, such as creating windows and adding components to them.

getTheme(self)

source code 

Gets the application's theme. The application's theme is the default theme used by all the windows in it that do not explicitly specify a theme. If the application theme is not explicitly set, the None is returned.

Returns:
the name of the application's theme.

setTheme(self, theme)

source code 

Sets the application's theme.

Note that this theme can be overridden in the the application level windows with Window.setTheme. Setting theme to be None selects the default theme. For the available theme names, see the contents of the VAADIN/themes directory.

Parameters:
  • theme - the new theme for this application.

getMainWindow(self)

source code 

Gets the mainWindow of the application.

The main window is the window attached to the application URL (getURL) and thus which is show by default to the user.

Note that each application must have at least one main window.

Returns:
the main window.

setMainWindow(self, mainWindow)

source code 

Sets the mainWindow. If the main window is not explicitly set, the main window defaults to first created window. Setting window as a main window of this application also adds the window to this application.

Parameters:
  • mainWindow - the mainWindow to set.

getPropertyNames(self)

source code 

Returns an enumeration of all the names in this application.

See start how properties are defined.

Returns:
an enumeration of all the keys in this property list, including the keys in the default property list.

getProperty(self, name)

source code 

Searches for the property with the specified name in this application. This method returns None if the property is not found.

See start how properties are defined.

Parameters:
  • name - the name of the property.
Returns:
the value in this property list with the specified key value.

addResource(self, resource)

source code 

Adds new resource to the application. The resource can be accessed by the user of the application.

Parameters:
  • resource - the resource to add.

removeResource(self, resource)

source code 

Removes the resource from the application.

Parameters:
  • resource - the resource to remove.

getRelativeLocation(self, resource)

source code 

Gets the relative uri of the resource. This method is intended to be called only be the terminal implementation.

This method can only be called from within the processing of a UIDL request, not from a background thread.

Parameters:
  • resource - the resource to get relative location.
Returns:
the relative uri of the resource or null if called in a background thread

Deprecated: this method is intended to be used by the terminal only. It may be removed or moved in the future.

handleURI(self, context, relativeUri)

source code 

Application URI handling hub.

This method gets called by terminal. It has lots of duties like to pass uri handler to proper uri handlers registered to windows etc.

In most situations developers should NOT OVERRIDE this method. Instead developers should implement and register uri handlers to windows.

Parameters:
  • context - the base URL
  • relativeUri - a URI relative to context
Returns:
A downloadable stream or null if no stream is provided
Overrides: terminal.uri_handler.IUriHandler.handleURI

Deprecated: this method is called be the terminal implementation only and might be removed or moved in the future. Instead of overriding this method, add your IUriHandler to a top level Window (eg. getMainWindow().addUriHanler(handler) instead.

getLocale(self)

source code 

Gets the default locale for this application.

By default this is the preferred locale of the user using the application. In most cases it is read from the browser defaults.

Returns:
the locale of this application.

setLocale(self, locale)

source code 

Sets the default locale for this application.

By default this is the preferred locale of the user using the application. In most cases it is read from the browser defaults.

Parameters:
  • locale - the Locale object.

addListener(self, listener, iface=None)

source code 

Adds the user change/window attach/window detach listener.

The user change listener allows one to get notification each time setUser is called. The window attach listener is used to get notifications each time a window is attached to the application with addWindow. The window detach listener is used to get notifications each time a window is remove from the application with removeWindow.

removeListener(self, listener, iface=None)

source code 

Removes the user change/window attach/window detach listener.

Parameters:
  • listener - the listener to remove

getLogoutURL(self)

source code 

Returns the URL user is redirected to on application close. If the URL is None, the application is closed normally as defined by the application running environment.

Desktop application just closes the application window and web-application redirects the browser to application main URL.

Returns:
the URL.

setLogoutURL(self, logoutURL)

source code 

Sets the URL user is redirected to on application close. If the URL is None, the application is closed normally as defined by the application running environment: Desktop application just closes the application window and web-application redirects the browser to application main URL.

Parameters:
  • logoutURL - the logoutURL to set.

getSystemMessages(cls)
Class Method

source code 

Gets the SystemMessages for this application. SystemMessages are used to notify the user of various critical situations that can occur, such as session expiration, client/server out of sync, and internal server error.

You can customize the messages by "overriding" this method and returning CustomizedSystemMessages. To "override" this method, re-implement this method in your application (the class that extends Application). Even though overriding class methods is not possible in Python, Muntjac selects to call the static method from the subclass instead of the original getSystemMessages if such a method exists.

Returns:
the SystemMessages for this application

terminalError(self, event)

source code 

Invoked by the terminal on any exception that occurs in application and is thrown by the setVariable to the terminal. The default implementation sets the exceptions as ComponentErrors to the component that initiated the exception and prints stack trace to standard error stream.

You can safely override this method in your application in order to direct the errors to some other destination (for example log).

Parameters:
  • event - the change event.
Overrides: terminal.terminal.IErrorListener.terminalError

getContext(self)

source code 

Gets the application context.

The application context is the environment where the application is running in. The actual implementation class of may contains quite a lot more functionality than defined in the ApplicationContext interface.

By default, when you are deploying your application to a servlet container, the implementation class is WebApplicationContext - you can safely cast to this class and use the methods from there.

Returns:
the application context.

getVersion(self)

source code 

Override this method to return correct version number of your Application. Version information is delivered for example to Testing Tools test results. By default this returns a string "NONVERSIONED".

Returns:
version string

getErrorHandler(self)

source code 

Gets the application error handler.

The default error handler is the application itself.

Returns:
Application error handler

setErrorHandler(self, errorHandler)

source code 

Sets the application error handler.

The default error handler is the application itself. By overriding this, you can redirect the error messages to your selected target (log for example).