com.guiseframework
Interface GuiseApplication

All Superinterfaces:

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

All Known Implementing Classes:

AbstractGuiseApplication, DefaultGuiseApplication, DemoApplication

public interface GuiseApplication
extends com.globalmentor.net.Resource, com.globalmentor.beans.PropertyBindable, com.globalmentor.config.ConfigurationManaged

An application running Guise. To enable mail-related functionality, mail must be configured using setMailProperties(Map).

Author:

Garret Wilson

Field Summary

static java.lang.String	ENVIRONMENT_PROPERTY The environment bound property.
static com.globalmentor.net.URIPath	GUISE_ASSETS_AUDIO_PATH The base path of audio assets, relative to the application.
static com.globalmentor.net.URIPath	GUISE_ASSETS_BASE_PATH The base path to access all Guise assets.
static com.globalmentor.net.URIPath	GUISE_ASSETS_CABS_PATH The base path of CAB assets, relative to the application.
static com.globalmentor.net.URIPath	GUISE_ASSETS_DOCUMENTS_PATH The base path of document assets, relative to the application.
static com.globalmentor.net.URIPath	GUISE_ASSETS_DTD_PATH The base path of DTD assets, relative to the application.
static com.globalmentor.net.URIPath	GUISE_ASSETS_FLASH_PATH The base path of Flash assets, relative to the application.
static com.globalmentor.net.URIPath	GUISE_ASSETS_JAVASCRIPT_PATH The base path of JavaScript assets, relative to the application.
static com.globalmentor.net.URIPath	GUISE_ASSETS_TEMP_BASE_PATH The base path to access all Guise temporary assets.
static com.globalmentor.net.URIPath	GUISE_ASSETS_THEMES_PATH The base path of theme assets, relative to the application.
static com.globalmentor.net.URIPath	GUISE_BASIC_THEME_BASE_PATH The base path of the basic Guise theme, relative to the application.
static com.globalmentor.net.URIPath	GUISE_BASIC_THEME_PATH The path of the basic Guise theme, relative to the application.
static com.globalmentor.net.URIPath	GUISE_RESERVED_BASE_PATH The base path reserved for exclusive Guise use.
static com.globalmentor.net.URIPath	GUISE_ROOT_THEME_BASE_PATH The base path of the default Guise theme, relative to the application.
static com.globalmentor.net.URIPath	GUISE_ROOT_THEME_CURSORS_PATH The base path of the default Guise theme cursors, relative to the application.
static com.globalmentor.net.URIPath	GUISE_ROOT_THEME_PATH The path of the root Guise theme, relative to the application.
static java.lang.String	LOCALES_PROPERTY The locales bound property.
static java.lang.String	RESOURCE_BUNDLE_BASE_NAME_PROPERTY The resource bundle base name bound property.
static java.lang.String	STYLE_URI_PROPERTY The style URI bound property.
static java.lang.String	THEME_URI_PROPERTY The theme URI bound property.
static java.lang.String	THEMED_PROPERTY The bound property of whether this application applies themes.

Fields inherited from interface com.globalmentor.net.Resource

URI_PROPERTY_NAME

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.
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.
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.
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.io.File	getTempDirectory() Returns the temprary directory shared by all sessions of this application.
com.globalmentor.io.IO<Theme>	getThemeIO()
java.net.URI	getThemeURI()
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.
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.
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.
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	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 interface com.globalmentor.net.Resource

getURI

Methods inherited from interface com.globalmentor.beans.PropertyBindable

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

Methods inherited from interface com.globalmentor.config.ConfigurationManaged

getConfiguration

Field Detail

ENVIRONMENT_PROPERTY

static final java.lang.String ENVIRONMENT_PROPERTY

The environment bound property.

LOCALES_PROPERTY

static final java.lang.String LOCALES_PROPERTY

The locales bound property.

RESOURCE_BUNDLE_BASE_NAME_PROPERTY

static final java.lang.String RESOURCE_BUNDLE_BASE_NAME_PROPERTY

The resource bundle base name bound property.

STYLE_URI_PROPERTY

static final java.lang.String STYLE_URI_PROPERTY

The style URI bound property.

THEME_URI_PROPERTY

static final java.lang.String THEME_URI_PROPERTY

The theme URI bound property.

THEMED_PROPERTY

static final java.lang.String THEMED_PROPERTY

The bound property of whether this application applies themes.

GUISE_RESERVED_BASE_PATH

static final com.globalmentor.net.URIPath GUISE_RESERVED_BASE_PATH

The base path reserved for exclusive Guise use.

GUISE_ASSETS_BASE_PATH

static final com.globalmentor.net.URIPath GUISE_ASSETS_BASE_PATH

The base path to access all Guise assets.

GUISE_ASSETS_TEMP_BASE_PATH

static final com.globalmentor.net.URIPath GUISE_ASSETS_TEMP_BASE_PATH

The base path to access all Guise temporary assets.

GUISE_ASSETS_AUDIO_PATH

static final com.globalmentor.net.URIPath GUISE_ASSETS_AUDIO_PATH

The base path of audio assets, relative to the application.

GUISE_ASSETS_CABS_PATH

static final com.globalmentor.net.URIPath GUISE_ASSETS_CABS_PATH

The base path of CAB assets, relative to the application.

GUISE_ASSETS_DOCUMENTS_PATH

static final com.globalmentor.net.URIPath GUISE_ASSETS_DOCUMENTS_PATH

The base path of document assets, relative to the application.

GUISE_ASSETS_DTD_PATH

static final com.globalmentor.net.URIPath GUISE_ASSETS_DTD_PATH

The base path of DTD assets, relative to the application.

GUISE_ASSETS_FLASH_PATH

static final com.globalmentor.net.URIPath GUISE_ASSETS_FLASH_PATH

The base path of Flash assets, relative to the application.

GUISE_ASSETS_JAVASCRIPT_PATH

static final com.globalmentor.net.URIPath GUISE_ASSETS_JAVASCRIPT_PATH

The base path of JavaScript assets, relative to the application.

GUISE_ASSETS_THEMES_PATH

static final com.globalmentor.net.URIPath GUISE_ASSETS_THEMES_PATH

The base path of theme assets, relative to the application.

GUISE_ROOT_THEME_BASE_PATH

static final com.globalmentor.net.URIPath GUISE_ROOT_THEME_BASE_PATH

The base path of the default Guise theme, relative to the application.

GUISE_ROOT_THEME_PATH

static final com.globalmentor.net.URIPath GUISE_ROOT_THEME_PATH

The path of the root Guise theme, relative to the application.

GUISE_BASIC_THEME_BASE_PATH

static final com.globalmentor.net.URIPath GUISE_BASIC_THEME_BASE_PATH

The base path of the basic Guise theme, relative to the application.

GUISE_BASIC_THEME_PATH

static final com.globalmentor.net.URIPath GUISE_BASIC_THEME_PATH

The path of the basic Guise theme, relative to the application.

GUISE_ROOT_THEME_CURSORS_PATH

static final com.globalmentor.net.URIPath GUISE_ROOT_THEME_CURSORS_PATH

The base path of the default Guise theme cursors, relative to the application.

Method Detail

getResourcesIO

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

Returns:

I/O for loading resources.

getThemeIO

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

Returns:

I/O for loading themes.

getLocales

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

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

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

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

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:

LOCALES_PROPERTY

getResourceBundleBaseName

java.lang.String getResourceBundleBaseName()

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

void setResourceBundleBaseName(java.lang.String newResourceBundleBaseName)

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

Parameters:

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

See Also:

RESOURCE_BUNDLE_BASE_NAME_PROPERTY

getEnvironment

Environment getEnvironment()

Returns:

The application local environment.

setEnvironment

void setEnvironment(Environment newEnvironment)

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

Parameters:

newEnvironment - The new application local environment.

Throws:

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

See Also:

ENVIRONMENT_PROPERTY

setLogLevel

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.

Parameters:

level - The minimum level to be logged.

Throws:

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

getMailProperties

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.

Returns:

The properties of the mail manager.

Throws:

java.lang.IllegalStateException - if the application is installed into a container but the mail properties has not been configured.

setMailProperties

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

Sets properties of the mail manager.

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

Session getMailSession()

Retrieves the current mail session.

Returns:

This application's mail session.

Throws:

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

java.lang.IllegalStateException - if mail has not been configured for this application.

getMailSendQueue

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.

Returns:

The queue used for to send mail.

Throws:

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

java.lang.IllegalStateException - if mail has not been configured for this application.

isThemed

boolean isThemed()

Returns:

Whether the application applies themes.

setThemed

void setThemed(boolean newThemed)

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

Parameters:

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

See Also:

THEMED_PROPERTY

getStyleURI

java.net.URI getStyleURI()

Returns:

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

setStyleURI

void setStyleURI(java.net.URI newStyle)

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

Parameters:

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

See Also:

STYLE_URI_PROPERTY

getThemeURI

java.net.URI getThemeURI()

Returns:

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

setThemeURI

void setThemeURI(java.net.URI newThemeURI)

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

Parameters:

newThemeURI - The URI of the new application theme.

Throws:

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

See Also:

THEME_URI_PROPERTY

getDCSID

java.lang.String getDCSID()

Returns:

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

setDCSID

void setDCSID(java.lang.String dcsID)

Sets the Data Collection Server log identifier.

Parameters:

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

getNavigationPath

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 .

Parameters:

depictionURI - The plain absolute depict URI.

Returns:

The application-relative logical navigation path.

Throws:

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

See Also:

GUISE_RESERVED_BASE_PATH

getDepictionURI

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.

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.

Throws:

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

getDepictionURI

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.

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.

Throws:

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

addDestination

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.

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

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.

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

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.

Parameters:

destinations - The destinations to set.

getDestination

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.

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

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.

Returns:

An iterable to the application's destinations.

hasDestination

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.

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.

getContainer

GuiseContainer getContainer()

Returns:

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

createSession

GuiseSession createSession(Platform platform)

Creates a new session for the application on the given platform.

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

void registerSession(GuiseSession guiseSession)

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

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

void unregisterSession(GuiseSession guiseSession)

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

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

GuiseSession getSession(java.util.UUID uuid)

Retrieves a Guise session for the given UUID.

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

ApplicationFrame createApplicationFrame()

Creates a frame for the application.

Returns:

A new frame for the application.

getBasePath

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.

Returns:

The base path representing the Guise application, or null if the application is not yet installed.

getHomeDirectory

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.

Returns:

The home directory of the application.

Throws:

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

getLogDirectory

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.

Returns:

The log directory of the application.

Throws:

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

getTempDirectory

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.

Returns:

The temporary directory of the application.

Throws:

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

getLogWriter

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. 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.

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:

getLogDirectory()

isInstalled

boolean isInstalled()

Returns:

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

See Also:

getContainer(), getBasePath()

checkInstalled

void checkInstalled()

Checks to ensure that this application is installed.

Throws:

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

See Also:

isInstalled()

install

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.

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.IllegalStateException - if the application is already installed.

uninstall

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.

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.

resolvePath

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 path "/path/to/application/", resolving "relative/path" will yield "/path/to/application/relative/path", while resolving "/absolute/path" will yield "/absolute/path".

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

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".

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

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"

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

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"

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(URIPath)

getLocaleResourcePath

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

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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.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.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 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

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.

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 temporary asset.

See Also:

getTempDirectory(), hasAsset(URIPath)

hasAsset

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.

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

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.

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

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.

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()

loadTheme

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.

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

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.

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()