com.guiseframework
Class AbstractGuiseApplication

java.lang.Object
  com.globalmentor.beans.BoundPropertyObject
      com.guiseframework.AbstractGuiseApplication

All Implemented Interfaces:

com.globalmentor.beans.PropertyBindable, com.globalmentor.beans.PropertyConstrainable, com.globalmentor.config.ConfigurationManaged, com.globalmentor.net.Resource, GuiseApplication

Direct Known Subclasses:

DefaultGuiseApplication, DemoApplication

public abstract class AbstractGuiseApplication
extends com.globalmentor.beans.BoundPropertyObject
implements GuiseApplication

An abstract base class for a Guise application. This implementation only works with Guise containers that descend from AbstractGuiseContainer.

Author:

Garret Wilson

Field Summary

Fields inherited from class com.globalmentor.beans.BoundPropertyObject

NO_PROPERTY_CHANGE_LISTENERS, NO_VETOABLE_CHANGE_LISTENERS

Fields inherited from interface com.guiseframework.GuiseApplication

ENVIRONMENT_PROPERTY, GUISE_ASSETS_AUDIO_PATH, GUISE_ASSETS_BASE_PATH, GUISE_ASSETS_CABS_PATH, GUISE_ASSETS_DOCUMENTS_PATH, GUISE_ASSETS_DTD_PATH, GUISE_ASSETS_FLASH_PATH, GUISE_ASSETS_JAVASCRIPT_PATH, GUISE_ASSETS_TEMP_BASE_PATH, GUISE_ASSETS_THEMES_PATH, GUISE_BASIC_THEME_BASE_PATH, GUISE_BASIC_THEME_PATH, GUISE_RESERVED_BASE_PATH, GUISE_ROOT_THEME_BASE_PATH, GUISE_ROOT_THEME_CURSORS_PATH, GUISE_ROOT_THEME_PATH, LOCALES_PROPERTY, RESOURCE_BUNDLE_BASE_NAME_PROPERTY, STYLE_URI_PROPERTY, THEME_URI_PROPERTY, THEMED_PROPERTY

Fields inherited from interface com.globalmentor.net.Resource

URI_PROPERTY_NAME

Constructor Summary

AbstractGuiseApplication(java.net.URI uri)
URI constructor.

Method Summary

void	addDestination(Destination destination) Registers a destination so that it can be matched against one or more paths.
void	addDestination(Destination destination, boolean priority) Registers a destination so that it can be matched against one or more paths.
void	checkInstalled() Checks to ensure that this application is installed.
void	checkNotInstalled() Checks to ensure that this application is not installed.
ApplicationFrame	createApplicationFrame() Creates a frame for the application.
GuiseSession	createSession(Platform platform) Creates a new session for the application on the given platform.
com.globalmentor.net.URIPath	createTempAsset(java.lang.String baseName, java.lang.String extension, GuiseSession restrictionSession) Creates a temporary asset available at an application navigation path.
java.net.URL	getAssetURL(com.globalmentor.net.URIPath path, GuiseSession guiseSession) Returns a URL to the asset at the given path.
com.globalmentor.net.URIPath	getBasePath() Reports the base path of the application.
java.net.URI	getBaseURI() Reports the base URI where the application is installed.
<C extends com.globalmentor.config.Configuration> C	getConfiguration(java.lang.Class<C> configurationClass) Returns the configuration for the given configuration type.
GuiseContainer	getContainer()
java.lang.String	getDCSID()
java.net.URI	getDepictionURI(java.net.URI depictionRootURI, java.net.URI navigationURI) Determines the depiction URI based upon a navigation URI.
java.net.URI	getDepictionURI(java.net.URI depictionRootURI, com.globalmentor.net.URIPath navigationPath) Determines the depiction URI based upon a navigation path.
Destination	getDestination(com.globalmentor.net.URIPath path) Determines the destination associated with the given application context-relative path.
java.lang.Iterable<Destination>	getDestinations() Returns an iterable of destinations.
Environment	getEnvironment()
java.io.File	getHomeDirectory() Returns the home directory shared by all sessions of this application.
java.io.InputStream	getInputStream(java.net.URI uri) Retrieves an input stream to the entity at the given URI.
java.io.InputStream	getInputStream(com.globalmentor.net.URIPath path) Retrieves an input stream to the entity at the given path.
java.lang.String	getLocaleResourcePath(java.lang.String resourceBasePath, java.util.Locale locale) Determines the locale-sensitive path of the given resource path.
java.util.List<java.util.Locale>	getLocales()
java.io.File	getLogDirectory() Returns the log directory shared by all sessions of this application.
java.io.Writer	getLogWriter(java.lang.String baseFilename, com.globalmentor.io.IOOperation<java.io.Writer> initializer, com.globalmentor.io.IOOperation<java.io.Writer> uninitializer) Retrieves a writer suitable for recording log information for the application.
java.util.Map<?,?>	getMailProperties() Returns the properties of the mail manager.
java.util.Queue<Message>	getMailSendQueue() Retrieves the queue used to send mail.
Session	getMailSession() Retrieves the current mail session.
com.globalmentor.net.URIPath	getNavigationPath(java.net.URI depictionURI) Determines the logical navigation path based upon a requested depiction URI.
java.io.OutputStream	getOutputStream(java.net.URI uri) Retrieves an output stream to the entity at the given URI.
java.io.OutputStream	getOutputStream(com.globalmentor.net.URIPath path) Retrieves an output stream to the entity at the given path.
protected char[]	getPassword(java.security.Principal principal) Looks up the corresponding password for the given principal.
protected java.security.Principal	getPrincipal(java.lang.String id) Looks up a principal from the given ID.
protected java.lang.String	getRealm(com.globalmentor.net.URIPath applicationPath) Determines the realm applicable for the resource indicated by the given application path.
java.lang.String	getResourceBundleBaseName()
java.io.InputStream	getResourceInputStream(java.lang.String resourcePath) Retrieves an input stream to the resource at the given path.
com.globalmentor.io.IO<Resources>	getResourcesIO()
GuiseSession	getSession(java.util.UUID uuid) Retrieves a Guise session for the given UUID.
java.net.URI	getStyleURI()
java.util.Set<java.util.Locale>	getSupportedLocales()
java.io.File	getTempDirectory() Returns the temprary directory shared by all sessions of this application.
com.globalmentor.io.IO<Theme>	getThemeIO()
java.net.URI	getThemeURI()
java.net.URI	getURI() Returns the application identifier URI.
boolean	hasAsset(com.globalmentor.net.URIPath path) Determines whether this application has an asset at the given path.
boolean	hasDestination(com.globalmentor.net.URIPath path) Determines if there is a destination associated with the given appplication context-relative path.
boolean	hasResource(java.lang.String resourcePath) Determines if the application has a resource available stored at the given resource path.
void	install(AbstractGuiseContainer container, java.net.URI baseURI, java.io.File homeDirectory, java.io.File logDirectory, java.io.File tempDirectory) Installs the application into the given container at the given base URI.
protected boolean	isAuthorized(com.globalmentor.net.URIPath applicationPath, java.security.Principal principal, java.lang.String realm) Checks whether the given principal is authorized to access the resouce at the given application path.
boolean	isInstalled()
boolean	isThemed()
java.util.Properties	loadProperties(java.lang.String propertiesPath) Loads properties from a file in the home directory.
java.util.ResourceBundle	loadResourceBundle(Theme theme, java.util.Locale locale) Retrieves a resource bundle for the given theme in the given locale.
protected java.util.ResourceBundle	loadResourceBundle(Theme theme, java.util.Locale locale, java.util.ResourceBundle parentResourceBundle) Retrieves a resource bundle from this theme and its resolving parents, if any.
protected java.util.ResourceBundle	loadResourceBundle(java.net.URI resourceBundleURI, java.util.ResourceBundle parentResourceBundle) Loads a resource bundle from the given URI.
Theme	loadTheme(java.net.URI themeURI) Loads a theme from the given URI.
void	registerSession(GuiseSession guiseSession) Registers a session with this application.
com.globalmentor.net.URIPath	relativizePath(com.globalmentor.net.URIPath path) Changes an absolute path to an application-relative path.
com.globalmentor.net.URIPath	relativizeURI(java.net.URI uri) Changes a URI to an application-relative path.
protected <C extends com.globalmentor.config.Configuration> C	removeConfiguration(java.lang.Class<C> configurationClass) Removes a configuration of the given type.
com.globalmentor.net.URIPath	resolvePath(com.globalmentor.net.URIPath path) Resolves a relative or absolute path against the application base path.
java.net.URI	resolveURI(java.net.URI uri) Resolves a URI against the application base path.
void	setBaseURI(java.net.URI baseURI) Sets the base URI of the application.
protected <C extends com.globalmentor.config.Configuration> C	setConfiguration(C configuration) Sets the given configuration, associating it with its class.
protected <C extends com.globalmentor.config.Configuration> C	setConfiguration(java.lang.Class<C> configurationClass, C configuration) Sets the given configuration.
protected void	setConfigurations(com.globalmentor.config.Configuration... configurations) Sets the given configurations, associating them with their respective classes.
void	setDCSID(java.lang.String dcsID) Sets the Data Collection Server log identifier.
void	setDestinations(java.util.List<Destination> destinations) Associates multiple destinations with application context-relative paths or path patterns.
void	setEnvironment(Environment newEnvironment) Sets the application local environment.
void	setLocales(java.util.List<java.util.Locale> newLocales) Sets the list of supported locales.
void	setLogLevel(com.globalmentor.log.Log.Level level) Sets the log level that will be logged.
void	setMailProperties(java.util.Map<?,?> mailProperties) Sets properties of the mail manager.
void	setResourceBundleBaseName(java.lang.String newResourceBundleBaseName) Changes the resource bundle base name.
void	setStyleURI(java.net.URI newStyle) Sets the URI of the style of the application.
void	setThemed(boolean newThemed) Sets whether the application applies themes.
void	setThemeURI(java.net.URI newThemeURI) Sets the URI of the application theme.
void	uninstall(GuiseContainer container) Uninstalls the application from the given container.
void	unregisterSession(GuiseSession guiseSession) Unregisters a session from this application.

Methods inherited from class com.globalmentor.beans.BoundPropertyObject

addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, addVetoableChangeListener, createPostponedPropertyChangeEvent, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, getForwardPropertyChangeListener, getPropertyChangeListeners, getPropertyChangeListeners, getPropertyChangeSupport, getRepeatPropertyChangeListener, getRepeatVetoableChangeListener, getVetoableChangeListeners, getVetoableChangeListeners, getVetoableChangeSupport, hasPropertyChangeListeners, hasVetoableChangeListeners, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, removeVetoableChangeListener

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.globalmentor.beans.PropertyBindable

addPropertyChangeListener, addPropertyChangeListener, getPropertyChangeListeners, getPropertyChangeListeners, hasPropertyChangeListeners, removePropertyChangeListener, removePropertyChangeListener

Constructor Detail

AbstractGuiseApplication

public AbstractGuiseApplication(java.net.URI uri)

URI constructor. The URI identifier may or may not be the URI at which the application can be accessed This implementation sets the locale to the JVM default.

Parameters:

uri - The URI for the application, or null if there is no identifier is not known.

Method Detail

getResourcesIO

public com.globalmentor.io.IO<Resources> getResourcesIO()

Specified by:

getResourcesIO in interface GuiseApplication

Returns:

I/O for loading resources.

getThemeIO

public com.globalmentor.io.IO<Theme> getThemeIO()

Specified by:

getThemeIO in interface GuiseApplication

Returns:

I/O for loading themes.

setConfigurations

protected void setConfigurations(com.globalmentor.config.Configuration... configurations)

Sets the given configurations, associating them with their respective classes.

Parameters:

configurations - The configurations to set.

setConfiguration

protected <C extends com.globalmentor.config.Configuration> C setConfiguration(C configuration)

Sets the given configuration, associating it with its class.

Type Parameters:

C - The type of configuration being set.

Parameters:

configuration - The configuration to set.

Returns:

The configuration previously associated with the same class, or null if there was no previous configuration for that class.

Throws:

java.lang.NullPointerException - if the given configuration is null.

setConfiguration

protected <C extends com.globalmentor.config.Configuration> C setConfiguration(java.lang.Class<C> configurationClass,
                                                                               C configuration)

Sets the given configuration.

Type Parameters:

C - The type of configuration being set.

Parameters:

configurationClass - The class with which to associate the configuration.

configuration - The configuration to set.

Returns:

The configuration previously associated with the given class, or null if there was no previous configuration for that class.

getConfiguration

public <C extends com.globalmentor.config.Configuration> C getConfiguration(java.lang.Class<C> configurationClass)

Returns the configuration for the given configuration type.

Specified by:

getConfiguration in interface com.globalmentor.config.ConfigurationManaged

Type Parameters:

C - The type of configuration to retrieve.

Parameters:

configurationClass - The class of configuration to retrieve.

Returns:

The configuration associated with the given class, or null if there was no configuration for that class.

removeConfiguration

protected <C extends com.globalmentor.config.Configuration> C removeConfiguration(java.lang.Class<C> configurationClass)

Removes a configuration of the given type. If no configuration is associated with the specified type, no action occurs.

Type Parameters:

C - The type of configuration being removed.

Parameters:

configurationClass - The class with which the configuration is associated.

Returns:

The configuration previously associated with the given class, or null if there was no previous configuration for that class.

getURI

public java.net.URI getURI()

Returns the application identifier URI. This URI may be but is not guaranteed to be the URI at which the application can be accessed.

Specified by:

getURI in interface com.globalmentor.net.Resource

Returns:

The application identifier URI, or null if the identifier is not known.

getContainer

public GuiseContainer getContainer()

Specified by:

getContainer in interface GuiseApplication

Returns:

The Guise container into which this application is installed, or null if the application is not yet installed.

getEnvironment

public Environment getEnvironment()

Specified by:

getEnvironment in interface GuiseApplication

Returns:

The application local environment.

setEnvironment

public void setEnvironment(Environment newEnvironment)

Sets the application local environment. This method will not normally be called directly from applications. This is a bound property.

Specified by:

setEnvironment in interface GuiseApplication

Parameters:

newEnvironment - The new application local environment.

Throws:

java.lang.NullPointerException - if the given environment is null.

See Also:

GuiseApplication.ENVIRONMENT_PROPERTY

getMailProperties

public java.util.Map<?,?> getMailProperties()

Returns the properties of the mail manager. This method is guaranteed to return a non-null value after the application is installed.

Specified by:

getMailProperties in interface GuiseApplication

Returns:

The properties of the mail manager.

Throws:

com.globalmentor.config.ConfigurationException - if the application is installed into a container but the mail properties has not been configured.

setMailProperties

public void setMailProperties(java.util.Map<?,?> mailProperties)

Sets properties of the mail manager.

Specified by:

setMailProperties in interface GuiseApplication

Parameters:

mailProperties - The new properties of the mail manager

Throws:

java.lang.NullPointerException - if the given properties is null.

java.lang.IllegalStateException - if the application has already been installed into a container.

getMailSession

public Session getMailSession()

Retrieves the current mail session.

Specified by:

getMailSession in interface GuiseApplication

Returns:

This application's mail session.

Throws:

java.lang.IllegalStateException - if the application has not yet been installed into a container.

com.globalmentor.config.ConfigurationException - if mail has not been configured for this application.

getMailSendQueue

public java.util.Queue<Message> getMailSendQueue()

Retrieves the queue used to send mail. Mail added to this queue will be sent use the application's configured mail protocols.

Specified by:

getMailSendQueue in interface GuiseApplication

Returns:

The queue used for to send mail.

Throws:

java.lang.IllegalStateException - if the application has not yet been installed into a container.

com.globalmentor.config.ConfigurationException - if mail has not been configured for this application.

isThemed

public boolean isThemed()

Specified by:

isThemed in interface GuiseApplication

Returns:

Whether the application applies themes.

setThemed

public void setThemed(boolean newThemed)

Sets whether the application applies themes. This is a bound property of type Boolean.

Specified by:

setThemed in interface GuiseApplication

Parameters:

newThemed - true if the application should apply themes, else false.

See Also:

GuiseApplication.THEMED_PROPERTY

getNavigationPath

public com.globalmentor.net.URIPath getNavigationPath(java.net.URI depictionURI)

Determines the logical navigation path based upon a requested depiction URI. This method must preserve paths beginning with . This version returns the relative path to the application unmodified.

Specified by:

getNavigationPath in interface GuiseApplication

Parameters:

depictionURI - The plain absolute depiction URI.

Returns:

The application-relative logical navigation path.

Throws:

java.lang.NullPointerException - if the given depiction URI is null.

See Also:

GuiseApplication.GUISE_RESERVED_BASE_PATH

getDepictionURI

public final java.net.URI getDepictionURI(java.net.URI depictionRootURI,
                                          com.globalmentor.net.URIPath navigationPath)

Determines the depiction URI based upon a navigation path.

The requested navigation path is allowed to be in three forms:

• An absolute path, such as /full/path/file.ext, which is typically resolved to the root depiction URI.
• A path relative to the application, such as path/file.ext, which is typically transformed if needed based upon hosts configured for sub-paths.

This implementation delegates to getDepictionURI(URI, URI).

Specified by:

getDepictionURI in interface GuiseApplication

Parameters:

depictionRootURI - The plain, absolute, root URI depiction currently in use.

navigationPath - The logical navigation path, either relative to the application, or absolute to the host.

Returns:

A URI suitable for depiction, resolved to the application base path.

getDepictionURI

public java.net.URI getDepictionURI(java.net.URI depictionRootURI,
                                    java.net.URI navigationURI)

Determines the depiction URI based upon a navigation URI.

The requested navigation URI is allowed to be in three forms:

• An absolute URI, such as http://www.cnn.com/, which is typically returned unmodified.
• A relative URI with an absolute path, such as /full/path/file.ext, which is typically resolved to the root depiction URI.
• A relative URI with a path relative to the application, such as path/file.ext, which is typically transformed if needed based upon hosts configured for sub-paths.

This version resolves the navigation URI to the base path, but otherwise returns the navigation URI unmodified.

Specified by:

getDepictionURI in interface GuiseApplication

Parameters:

depictionRootURI - The plain, absolute, root URI depiction currently in use.

navigationURI - The logical navigation URI, either absolute, relative to the application, or absolute to the host.

Returns:

A URI suitable for depiction, resolved to the application base path.

createSession

public GuiseSession createSession(Platform platform)

Creates a new session for the application on the given platform. This version creates and returns a default session.

Specified by:

createSession in interface GuiseApplication

Parameters:

platform - The platform on which this session's objects are depicted.

Returns:

A new session for the application

Throws:

java.lang.NullPointerException - if the given platform is null.

registerSession

public void registerSession(GuiseSession guiseSession)

Registers a session with this application. The Guise session has not yet been initialized when this method is called.

Specified by:

registerSession in interface GuiseApplication

Parameters:

guiseSession - The Guise session to register with this Guise application.

Throws:

java.lang.IllegalStateException - if the given session has alreaady been registered with this application.

unregisterSession

public void unregisterSession(GuiseSession guiseSession)

Unregisters a session from this application. The Guise session has already been uninitialized when this method is called.

Specified by:

unregisterSession in interface GuiseApplication

Parameters:

guiseSession - The Guise session to unregister from this Guise application.

Throws:

java.lang.IllegalStateException - if the given session is not registered with this application.

getSession

public GuiseSession getSession(java.util.UUID uuid)

Retrieves a Guise session for the given UUID.

Specified by:

getSession in interface GuiseApplication

Parameters:

uuid - The UUID of the Guise session to retrieve.

Returns:

The Guise session associated with the given UUID, or null if no Guise session is associated with the given UUID.

Throws:

java.lang.NullPointerException - if the given UUID is null.

createApplicationFrame

public ApplicationFrame createApplicationFrame()

Creates a frame for the application. This implementation returns a default application frame.

Specified by:

createApplicationFrame in interface GuiseApplication

Returns:

A new frame for the application.

getBaseURI

public java.net.URI getBaseURI()

Reports the base URI where the application is installed. The base URI is an absolute URI that ends with the base path, which ends with a slash ('/').

Returns:

The base URI representing the Guise application, or null if no application base URI has been specified and the application is not yet installed.

See Also:

getBasePath()

setBaseURI

public void setBaseURI(java.net.URI baseURI)

Sets the base URI of the application. The base path is also set.

Parameters:

baseURI - The base URI where the application is installed, which must be an absolute URI with an absolute collection path (e.g. http://www.example.com/path/).

Throws:

java.lang.NullPointerException - if the given base URI is null.

java.lang.IllegalArgumentException - if the given URI is not absolute or the path of which is not absolute or not a collection.

java.lang.IllegalStateException - if the application is already installed.

See Also:

getBasePath()

getBasePath

public com.globalmentor.net.URIPath getBasePath()

Reports the base path of the application. The base path is an absolute path that ends with a slash ('/'), indicating the base path of the navigation panels.

Specified by:

getBasePath in interface GuiseApplication

Returns:

The base path representing the Guise application, or null if no application base URI has been specified and the application is not yet installed.

getHomeDirectory

public java.io.File getHomeDirectory()

Returns the home directory shared by all sessions of this application. This value is not available before the application is installed.

Specified by:

getHomeDirectory in interface GuiseApplication

Returns:

The home directory of the application.

Throws:

java.lang.IllegalStateException - if the application has not yet been installed into a container.

getLogDirectory

public java.io.File getLogDirectory()

Returns the log directory shared by all sessions of this application. This value is not available before the application is installed.

Specified by:

getLogDirectory in interface GuiseApplication

Returns:

The log directory of the application.

Throws:

java.lang.IllegalStateException - if the application has not yet been installed into a container.

getTempDirectory

public java.io.File getTempDirectory()

Returns the temprary directory shared by all sessions of this application. This value is not available before the application is installed.

Specified by:

getTempDirectory in interface GuiseApplication

Returns:

The temporary directory of the application.

Throws:

java.lang.IllegalStateException - if the application has not yet been installed into a container.

getLogWriter

public java.io.Writer getLogWriter(java.lang.String baseFilename,
                                   com.globalmentor.io.IOOperation<java.io.Writer> initializer,
                                   com.globalmentor.io.IOOperation<java.io.Writer> uninitializer)
                            throws java.io.IOException

Retrieves a writer suitable for recording log information for the application. This implementation returns an asynchronous writer that does not block for information to be written when receiving information. The given base filename is appended with a representation of the current date. If a log writer for the same date is available, it is returned; otherwise, a new log writer is created. If the current date is a different day than that used for the current log writer for a given base filename, a new writer is created for the current date.

Specified by:

getLogWriter in interface GuiseApplication

Parameters:

baseFilename - The base filename (e.g. "base.log") that will be used in generating a log file for the current date (e.g. "base 2003-02-01.log").

initializer - The encapsulation of any initialization that should be performed on any new writer, or null if no initialization is requested.

uninitializer - The encapsulation of any uninitialization that should be performed on any new writer, or null if no uninitialization is requested.

Throws:

java.io.IOException

See Also:

GuiseApplication.getLogDirectory()

isInstalled

public boolean isInstalled()

Specified by:

isInstalled in interface GuiseApplication

Returns:

Whether this application has been installed into a container at some base path.

See Also:

getContainer(), getBasePath()

checkInstalled

public void checkInstalled()

Checks to ensure that this application is installed.

Specified by:

checkInstalled in interface GuiseApplication

Throws:

java.lang.IllegalStateException - if the application is not installed.

See Also:

isInstalled()

checkNotInstalled

public void checkNotInstalled()

Checks to ensure that this application is not installed.

Throws:

java.lang.IllegalStateException - if the application is installed.

See Also:

isInstalled()

install

public void install(AbstractGuiseContainer container,
                    java.net.URI baseURI,
                    java.io.File homeDirectory,
                    java.io.File logDirectory,
                    java.io.File tempDirectory)

Installs the application into the given container at the given base URI. This method is called by GuiseContainer and should not be called directly by applications. This implementation configures logging. Mail is enabled if mail properties have been configured using setMailProperties(Map).

Specified by:

install in interface GuiseApplication

Parameters:

container - The Guise container into which the application is being installed.

baseURI - The base URI at which the application is being installed.

homeDirectory - The home directory of the application.

logDirectory - The log directory of the application.

tempDirectory - The temporary directory of the application.

Throws:

java.lang.NullPointerException - if the container, base URI, home directory, log directory, and/or temporary directory is null.

java.lang.IllegalArgumentException - if the given base URI is not absolute or the path of which is not absolute or not a collection.

java.lang.IllegalArgumentException - if the context path is not absolute and does not end with a slash ('/') character.

java.lang.IllegalStateException - if the application is already installed.

uninstall

public void uninstall(GuiseContainer container)

Uninstalls the application from the given container. All log writers are closed. This method is called by GuiseContainer and should not be called directly by applications.

Specified by:

uninstall in interface GuiseApplication

Parameters:

container - The Guise container into which the application is being installed.

Throws:

java.lang.IllegalStateException - if the application is not installed or is installed into another container.

getDCSID

public java.lang.String getDCSID()

Specified by:

getDCSID in interface GuiseApplication

Returns:

The identifier for logging to a Data Collection System such as WebTrends, or null if no DCS ID is known.

setDCSID

public void setDCSID(java.lang.String dcsID)

Sets the Data Collection Server log identifier.

Specified by:

setDCSID in interface GuiseApplication

Parameters:

dcsID - The identifier for logging to a Data Collection System such as WebTrends, or null if no DCS ID is known.

getLocales

public java.util.List<java.util.Locale> getLocales()

Specified by:

getLocales in interface GuiseApplication

Returns:

The read-only non-empty list of locales supported by the application, with the first locale the default used if a new session cannot determine the users's preferred locale.

setLocales

public void setLocales(java.util.List<java.util.Locale> newLocales)

Sets the list of supported locales. This is a bound property.

Specified by:

setLocales in interface GuiseApplication

Parameters:

newLocales - The new supported application locales.

Throws:

java.lang.NullPointerException - if the given list of locales is null.

java.lang.IllegalArgumentException - if the given list of locales is empty.

See Also:

GuiseApplication.LOCALES_PROPERTY

getSupportedLocales

public java.util.Set<java.util.Locale> getSupportedLocales()

Returns:

The thread-safe set of locales supported by this application.

getResourceBundleBaseName

public java.lang.String getResourceBundleBaseName()

Specified by:

getResourceBundleBaseName in interface GuiseApplication

Returns:

The base name of the resource bundle to use for this application, or null if no custom resource bundle is specified for this application..

setResourceBundleBaseName

public void setResourceBundleBaseName(java.lang.String newResourceBundleBaseName)

Changes the resource bundle base name. This is a bound property.

Specified by:

setResourceBundleBaseName in interface GuiseApplication

Parameters:

newResourceBundleBaseName - The new base name of the resource bundle, or null if no custom resource bundle is specified for this application.

See Also:

GuiseApplication.RESOURCE_BUNDLE_BASE_NAME_PROPERTY

getStyleURI

public java.net.URI getStyleURI()

Specified by:

getStyleURI in interface GuiseApplication

Returns:

The absolute or application-relative URI of the application style, or null if the default style should be used.

setStyleURI

public void setStyleURI(java.net.URI newStyle)

Sets the URI of the style of the application. This is a bound property.

Specified by:

setStyleURI in interface GuiseApplication

Parameters:

newStyle - The URI of the application style, or null if the default style should be used.

See Also:

GuiseApplication.STYLE_URI_PROPERTY

getThemeURI

public java.net.URI getThemeURI()

Specified by:

getThemeURI in interface GuiseApplication

Returns:

The URI of the application theme, to be resolved against the application base path.

setThemeURI

public void setThemeURI(java.net.URI newThemeURI)

Sets the URI of the application theme. This is a bound property.

Specified by:

setThemeURI in interface GuiseApplication

Parameters:

newThemeURI - The URI of the new application theme.

Throws:

java.lang.NullPointerException - if the given theme URI is null.

See Also:

GuiseApplication.THEME_URI_PROPERTY

setLogLevel

public void setLogLevel(com.globalmentor.log.Log.Level level)

Sets the log level that will be logged. Any log information at or above the given level will be logged.

Specified by:

setLogLevel in interface GuiseApplication

Parameters:

level - The minimum level to be logged.

Throws:

java.lang.NullPointerException - if the given level is null.

addDestination

public void addDestination(Destination destination)

Registers a destination so that it can be matched against one or more paths. Any existing destinations for the path or path pattern is replaced. Existing destinations will take priority if a path matches multiple destination path patterns.

Specified by:

addDestination in interface GuiseApplication

Parameters:

destination - The description of the destination at the appplication context-relative path or path pattern.

Throws:

java.lang.NullPointerException - if the destination is null.

addDestination

public void addDestination(Destination destination,
                           boolean priority)

Registers a destination so that it can be matched against one or more paths. Any existing destinations for the path or path pattern is replaced.

Specified by:

addDestination in interface GuiseApplication

Parameters:

destination - The description of the destination at the appplication context-relative path or path pattern.

priority - Whether this destination takes priority over other destinations when there are multiple matches; if this destination has no path pattern, this parameter is ignored.

Throws:

java.lang.NullPointerException - if the destination is null.

setDestinations

public void setDestinations(java.util.List<Destination> destinations)

Associates multiple destinations with application context-relative paths or path patterns. All destinations are first cleared. Any existing destinations for the given context-relative paths are replaced.

Specified by:

setDestinations in interface GuiseApplication

Parameters:

destinations - The destinations to set.

getDestination

public Destination getDestination(com.globalmentor.net.URIPath path)

Determines the destination associated with the given application context-relative path. This method first checks for a destination that matches the exact path as given; if no matching path is found, all destinations with path patterns are searched for a match.

Specified by:

getDestination in interface GuiseApplication

Parameters:

path - The address for which a destination should be retrieved.

Returns:

The destination associated with the given path, or null if no destination is associated with the path.

Throws:

java.lang.IllegalArgumentException - if the provided path is absolute.

getDestinations

public java.lang.Iterable<Destination> getDestinations()

Returns an iterable of destinations. Any changes to the iterable will not necessarily be reflected in the destinations available to the application.

Specified by:

getDestinations in interface GuiseApplication

Returns:

An iterable to the application's destinations.

hasDestination

public boolean hasDestination(com.globalmentor.net.URIPath path)

Determines if there is a destination associated with the given appplication context-relative path. This method first checks for a destination that matches the exact path as given; if no matching path is found, all destinations with path patterns are searched for a match.

Specified by:

hasDestination in interface GuiseApplication

Parameters:

path - The appplication context-relative path.

Returns:

true if there is destination associated with the given path, or false if no destination is associated with the given path.

Throws:

java.lang.NullPointerException - if the path is null.

java.lang.IllegalArgumentException - if the provided path is absolute.

resolvePath

public com.globalmentor.net.URIPath resolvePath(com.globalmentor.net.URIPath path)

Resolves a relative or absolute path against the application base path. Relative paths will be resolved relative to the application base path. Absolute paths will be be considered already resolved. For an application base path "/path/to/application/", resolving "relative/path" will yield "/path/to/application/relative/path", while resolving "/absolute/path" will yield "/absolute/path".

Specified by:

resolvePath in interface GuiseApplication

Parameters:

path - The path to be resolved.

Returns:

The path resolved against the application base path.

Throws:

java.lang.NullPointerException - if the given path is null.

java.lang.IllegalArgumentException - if the provided path specifies a URI scheme (i.e. the URI is absolute) and/or authority (in which case resolveURI(URI) should be used instead).

See Also:

getBasePath(), resolveURI(URI)

resolveURI

public java.net.URI resolveURI(java.net.URI uri)

Resolves a URI against the application base path. Relative paths and scheme URIs with relative paths will be resolved relative to the application base path. Absolute paths will be considered already resolved, as will absolute URIs. For an application base path "/path/to/application/", resolving "path:relative/path" or "relative/path" will yield "/path/to/application/relative/path", while resolving "path:/absolute/path" or "/absolute/path" will yield "/absolute/path". Resolving "http://example.com/path" will yield "http://example.com/path".

Specified by:

resolveURI in interface GuiseApplication

Parameters:

uri - The URI to be resolved.

Returns:

The URI resolved against the application base path.

Throws:

java.lang.NullPointerException - if the given URI is null.

See Also:

getBasePath(), resolvePath(URIPath)

relativizePath

public com.globalmentor.net.URIPath relativizePath(com.globalmentor.net.URIPath path)

Changes an absolute path to an application-relative path. For an application base path "/path/to/application/", relativizing "/path/to/application/relative/path" will yield "relative/path"

Specified by:

relativizePath in interface GuiseApplication

Parameters:

path - The path to be relativized.

Returns:

The path relativized to the application base path.

Throws:

java.lang.NullPointerException - if the given path is null.

java.lang.IllegalArgumentException - if the provided path specifies a URI scheme (i.e. the URI is absolute) and/or authority (in which case resolveURI(URI) should be used instead).

See Also:

getBasePath(), relativizeURI(URI)

relativizeURI

public com.globalmentor.net.URIPath relativizeURI(java.net.URI uri)

Changes a URI to an application-relative path. For an application base path "/path/to/application/", relativizing "http://www.example.com/path/to/application/relative/path" will yield "relative/path"

Specified by:

relativizeURI in interface GuiseApplication

Parameters:

uri - The URI to be relativized.

Returns:

The URI path relativized to the application base path.

Throws:

java.lang.NullPointerException - if the given URI is null.

See Also:

getBasePath(), #relativizePath(String)

getLocaleResourcePath

public java.lang.String getLocaleResourcePath(java.lang.String resourceBasePath,
                                              java.util.Locale locale)

Determines the locale-sensitive path of the given resource path. Based upon the provided locale, candidate resource paths are checked in the following order:

1. resourceBasePath + "_" + language + "_" + country + "_" + variant
2. resourceBasePath + "_" + language + "_" + country
3. resourceBasePath + "_" + language

Specified by:

getLocaleResourcePath in interface GuiseApplication

Parameters:

resourceBasePath - An application-relative base path to a resource in the application resource storage area.

locale - The locale to use in generating candidate resource names.

Returns:

The locale-sensitive path to an existing resource based upon the given locale, or null if no resource exists at the given resource base path or any of its locale candidates.

Throws:

java.lang.NullPointerException - if the given resource base path and/or locale is null.

java.lang.IllegalArgumentException - if the given resource path is absolute.

java.lang.IllegalArgumentException - if the given path is not a valid path.

See Also:

hasResource(String)

hasResource

public boolean hasResource(java.lang.String resourcePath)

Determines if the application has a resource available stored at the given resource path. The provided path is first normalized. This implementation uses package access to delegate to AbstractGuiseContainer.hasResource(String).

Specified by:

hasResource in interface GuiseApplication

Parameters:

resourcePath - An application-relative path to a resource in the application resource storage area.

Returns:

true if a resource exists at the given resource path.

Throws:

java.lang.IllegalArgumentException - if the given resource path is absolute.

java.lang.IllegalArgumentException - if the given path is not a valid path.

getResourceInputStream

public java.io.InputStream getResourceInputStream(java.lang.String resourcePath)

Retrieves an input stream to the resource at the given path. The provided path is first normalized. This implementation uses package access to delegate to AbstractGuiseContainer.getResourceInputStream(String).

Specified by:

getResourceInputStream in interface GuiseApplication

Parameters:

resourcePath - An application-relative path to a resource in the application resource storage area.

Returns:

An input stream to the resource at the given resource path, or null if no resource exists at the given resource path.

Throws:

java.lang.IllegalArgumentException - if the given resource path is absolute.

java.lang.IllegalArgumentException - if the given path is not a valid path.

getInputStream

public java.io.InputStream getInputStream(java.net.URI uri)
                                   throws java.io.IOException

Retrieves an input stream to the entity at the given URI. The URI is first resolved to the application base path. If the URI represents one of this application's public resources, this implementation will return an input stream directly from that resource if possible rather than issuing a separate server request. This method supports read access to temporary public resources.

Specified by:

getInputStream in interface GuiseApplication

Parameters:

uri - A URI to the entity; either absolute or relative to the application.

Returns:

An input stream to the entity at the given resource URI, or null if no entity exists at the given resource path.

Throws:

java.lang.NullPointerException - if the given URI is null.

java.lang.IllegalStateException - if a Guise public temporary resource was requested that requires a particular Guise session, and the request was not made from the required session.

java.io.IOException - if there was an error connecting to the entity at the given URI.

See Also:

resolveURI(URI)

getInputStream

public java.io.InputStream getInputStream(com.globalmentor.net.URIPath path)
                                   throws java.io.IOException

Retrieves an input stream to the entity at the given path. If the URI represents one of this application's public resources, this implementation will return an input stream directly from that resource if possible rather than issuing a separate server request. This method supports read access to temporary public resources.

Specified by:

getInputStream in interface GuiseApplication

Parameters:

path - A path that is either relative to the application context path or is absolute.

Returns:

An input stream to the entity at the given resource path, or null if no entity exists at the given resource path.

Throws:

java.lang.NullPointerException - if the given path is null.

java.lang.IllegalArgumentException - if the provided path specifies a URI scheme (i.e. the URI is absolute) and/or authority (in which case getInputStream(URI) should be used instead).

java.lang.IllegalStateException - if a Guise public temporary resource was requested that requires a particular Guise session, and the request was not made from the required session.

java.io.IOException - if there was an error connecting to the entity at the given path.

See Also:

getInputStream(URI)

getOutputStream

public java.io.OutputStream getOutputStream(java.net.URI uri)
                                     throws java.io.IOException

Retrieves an output stream to the entity at the given URI. The URI is first resolved to the application base path. This method supports write access to temporary public resources. Write access to resources other than Guise public temporary files is currently unsupported.

Specified by:

getOutputStream in interface GuiseApplication

Parameters:

uri - A URI to the entity; either absolute or relative to the application.

Returns:

An output stream to the entity at the given resource URI.

Throws:

java.lang.NullPointerException - if the given URI is null.

java.lang.IllegalStateException - if a Guise public temporary resource was requested that requires a particular Guise session, and the request was not made from the required session.

java.io.FileNotFoundException - if a URI to a temporary file was passed before the file was created using #createTempAsset(String, String, boolean).

java.io.IOException - if there was an error connecting to the entity at the given URI.

See Also:

resolveURI(URI), #createTempAsset(String, String, boolean)

getOutputStream

public java.io.OutputStream getOutputStream(com.globalmentor.net.URIPath path)
                                     throws java.io.IOException

Retrieves an output stream to the entity at the given path. This method supports write access to temporary public resources. Write access to resources other than Guise public temporary files is currently unsupported.

Specified by:

getOutputStream in interface GuiseApplication

Parameters:

path - A path that is either relative to the application context path or is absolute.

Returns:

An output stream to the entity at the given resource path.

Throws:

java.lang.NullPointerException - if the given path is null.

java.lang.IllegalStateException - if a Guise public temporary resource was requested that requires a particular Guise session, and the request was not made from the required session.

java.lang.IllegalArgumentException - if the provided path specifies a URI scheme (i.e. the URI is absolute) and/or authority (in which case getOutputStream(URI) should be used instead).

java.io.FileNotFoundException - if a path to a temporary file was passed before the file was created using #createTempAsset(String, String, boolean).

java.io.IOException - if there was an error connecting to the entity at the given URI.

See Also:

getOutputStream(URI), #createTempAsset(String, String, boolean)

createTempAsset

public com.globalmentor.net.URIPath createTempAsset(java.lang.String baseName,
                                                    java.lang.String extension,
                                                    GuiseSession restrictionSession)
                                             throws java.io.IOException

Creates a temporary asset available at an application navigation path. The file will be created in the application's temporary file directory. If the asset is restricted to the current Guise session, the asset will be deleted when the current Guise session ends.

Specified by:

createTempAsset in interface GuiseApplication

Parameters:

baseName - The base filename to be used in generating the filename.

extension - The extension to use for the temporary file.

restrictionSession - The Guise session to which access access to the temporary file should be restricted, or null if there should be no access restriction.

Returns:

An application navigation path that can be used to access the asset.

Throws:

java.lang.NullPointerException - if the given base name and/or extension is null.

java.lang.IllegalArgumentException - if the base name is the empty string.

java.lang.IllegalStateException - if the given restriction session is not registered with this application.

java.io.IOException - if there is a problem creating the asset.

See Also:

getTempDirectory(), hasAsset(URIPath)

hasAsset

public boolean hasAsset(com.globalmentor.net.URIPath path)
                 throws java.io.IOException

Determines whether this application has an asset at the given path. The path is first normalized. This method supports Guise assets and temporary application assets.

Specified by:

hasAsset in interface GuiseApplication

Parameters:

path - The application-relative path of the asset.

Returns:

true if an asset exists at the given path.

Throws:

java.io.IOException - if there was an error accessing the asset.

See Also:

#createTempAsset(String, String, boolean), Guise.hasAsset(String)

getAssetURL

public java.net.URL getAssetURL(com.globalmentor.net.URIPath path,
                                GuiseSession guiseSession)
                         throws java.io.IOException

Returns a URL to the asset at the given path. The path is first normalized. This method supports Guise assets and temporary application assets. The returned URL represents internal access to the asset and should normally not be presented to users.

Specified by:

getAssetURL in interface GuiseApplication

Parameters:

path - The application-relative path of the asset.

session - The Guise session requesting the asset, or null if there is no session associated with the request.

Returns:

A URL to the asset, or null if there is no such asset.

Throws:

java.lang.IllegalStateException - if an asset was requested that requires a particular Guise session different from the given Guise session.

java.io.IOException - if there was an error accessing the asset.

See Also:

#createTempAsset(String, String, boolean), Guise.getAssetURL(String)

loadResourceBundle

public java.util.ResourceBundle loadResourceBundle(Theme theme,
                                                   java.util.Locale locale)
                                            throws java.io.IOException

Retrieves a resource bundle for the given theme in the given locale. The resource bundle retrieved will allow hierarchical resolution in the following priority:

1. Any resource defined by the application.
2. Any resource defined by the theme.
3. Any resource defined by a parent theme, including the default theme.
4. Any resource defined by default by Guise.

Specified by:

loadResourceBundle in interface GuiseApplication

Parameters:

theme - The current theme in effect.

locale - The locale for which resources should be retrieved.

Returns:

A resolving resource bundle based upon the locale.

Throws:

java.io.IOException - if there was an error loading a resource bundle.

See Also:

getResourceBundleBaseName()

loadResourceBundle

protected java.util.ResourceBundle loadResourceBundle(Theme theme,
                                                      java.util.Locale locale,
                                                      java.util.ResourceBundle parentResourceBundle)
                                               throws java.io.IOException

Retrieves a resource bundle from this theme and its resolving parents, if any. If multiple resource bundles are specified in this theme, they will be chained in no particular order. For each resource that provides both a reference URI and local definitions, the resources at the reference URI will be used as the resolving parent of the local definitions. If the theme does not specify a resource bundle, the given parent resource bundle will be returned.

Parameters:

theme - The theme for which to load resources.

locale - The locale for which resources should be retrieved.

parentResourceBundle - The resource bundle to serve as the parent, or null if there is no parent resource bundle.

Returns:

The resource bundle for the theme, with parent resource bundles loaded, or the parent resource bundle if the theme specifies no resources.

Throws:

java.io.IOException - if there was an error loading a resource bundle.

loadResourceBundle

protected java.util.ResourceBundle loadResourceBundle(java.net.URI resourceBundleURI,
                                                      java.util.ResourceBundle parentResourceBundle)
                                               throws java.io.IOException

Loads a resource bundle from the given URI.

Parameters:

resourceBundleURI - The URI of the resource bundle to load.

parentResourceBundle - The resource bundle to serve as the parent, or null if there is no parent resource bundle.

Returns:

The loaded resource bundle.

Throws:

java.io.IOException - if there was an error loading the resource bundle.

loadTheme

public Theme loadTheme(java.net.URI themeURI)
                throws java.io.IOException

Loads a theme from the given URI. All relative URIs are considered relative to the application. If the theme specifies no parent theme, the default parent theme will be assigned unless the theme is the default theme.

Specified by:

loadTheme in interface GuiseApplication

Parameters:

themeURI - The URI of the theme to load.

Returns:

A loaded theme with resolving parents loaded as well.

Throws:

java.lang.NullPointerException - if the given theme URI is null.

java.io.IOException - if there is an error loading the theme or one of its parents.

loadProperties

public java.util.Properties loadProperties(java.lang.String propertiesPath)
                                    throws java.io.IOException

Loads properties from a file in the home directory. The properties can be stored in XML or in the traditional properties format.

Specified by:

loadProperties in interface GuiseApplication

Parameters:

propertiesPath - The path to the properties file, relative to the application home directory.

Returns:

The properties loaded from the file at the given path.

Throws:

java.lang.NullPointerException - if the given properties path is null.

java.lang.IllegalArgumentException - if the type of properties file is not recognized.

java.io.IOException - if there is an error loading the properties.

See Also:

getHomeDirectory()

getPrincipal

protected java.security.Principal getPrincipal(java.lang.String id)

Looks up a principal from the given ID. This version returns null.

Parameters:

id - The ID of the principal.

Returns:

The principal corresponding to the given ID, or null if no principal could be determined.

getPassword

protected char[] getPassword(java.security.Principal principal)

Looks up the corresponding password for the given principal. This version returns null.

Parameters:

principal - The principal for which a password should be returned.

Returns:

The password associated with the given principal, or null if no password is associated with the given principal.

getRealm

protected java.lang.String getRealm(com.globalmentor.net.URIPath applicationPath)

Determines the realm applicable for the resource indicated by the given application path. This version returns the application base path as the realm for all application paths.

Parameters:

applicationPath - The relative path of the resource requested.

Returns:

The realm appropriate for the resource, or null if the given resource is not in a known realm.

isAuthorized

protected boolean isAuthorized(com.globalmentor.net.URIPath applicationPath,
                               java.security.Principal principal,
                               java.lang.String realm)

Checks whether the given principal is authorized to access the resouce at the given application path. This version authorized any principal accessing any application path.

Parameters:

applicationPath - The relative path of the resource requested.

principal - The principal requesting authentication, or null if the principal is not known.

realm - The realm with which the resource is associated, or null if the realm is not known.

Returns:

true if the given principal is authorized to access the resource represented by the given application path.