com.guiseframework
Interface GuiseSession

All Superinterfaces:

com.globalmentor.text.CollatorFactory, com.globalmentor.config.ConfigurationManaged, com.globalmentor.beans.PropertyBindable

All Known Implementing Classes:

AbstractGuiseSession, DefaultGuiseSession

public interface GuiseSession
extends com.globalmentor.beans.PropertyBindable, com.globalmentor.text.CollatorFactory, com.globalmentor.config.ConfigurationManaged

Represents a session with a user. A Swing-based client application may have only one session, while a web server application will likely have multiple sessions.

Author:

Garret Wilson

Field Summary

static java.lang.String	INPUT_STRATEGY_PROPERTY The input strategy bound property.
static java.lang.String	LOCALE_PROPERTY The locale bound property.
static java.lang.String	ORIENTATION_PROPERTY The orientation bound property.
static java.lang.String	PRINCIPAL_PROPERTY The principal (e.g.
static java.lang.String	THEME_URI_PROPERTY The theme URI bound property.
static java.lang.String	TIME_ZONE_PROPERTY The time zone bound property.

Method Summary

void	beginModalNavigation(ModalNavigationPanel<?> modalNavigationPanel, ModalNavigation modalNavigation) Begins modal interaction for a particular modal panel.
void	clearRequestedNavigation() Removes any requests for navigation.
Component	createBusyComponent() Creates a component to indicate Guise busy status.
com.globalmentor.net.URIPath	createTempPublicResource(java.lang.String baseName, java.lang.String extension) Creates a temporary resource available at a public application navigation path but with access restricted to this session.
java.lang.String	dereferenceString(java.lang.String string) Dereferences a string by replacing any string references with a string from the resources.
java.net.URI	dereferenceURI(java.net.URI uri, java.lang.String... suffixes) Dereferences a URI by looking up any references from the resources if necessary.
void	destroy() Called when the session is destroyed.
boolean	endModalNavigation(ModalNavigationPanel<?> modalNavigationPanel) Ends modal interaction for a particular modal panel.
void	fireNavigated(java.net.URI referrerURI) Fires a NavigationEvent to all NavigationListeners in the session application frame hierarchy.
ActionPrototype	getAboutApplicationActionPrototype()
GuiseApplication	getApplication()
ApplicationFrame	getApplicationFrame()
Bookmark	getBookmark() Reports the current bookmark relative to the current navigation path.
java.lang.Boolean	getBooleanResource(java.lang.String resourceKey) Retrieves a Boolean resource from the resource bundle.
java.lang.Boolean	getBooleanResource(java.lang.String resourceKey, java.lang.Boolean defaultValue) Retrieves a Boolean resource from the resource bundle, using a specified default if no such resource is available.
Breadcrumb	getBreadcrumb(com.globalmentor.net.URIPath navigationPath) Retrieves a breadcrumb for a particular navigation path.
java.util.List<Breadcrumb>	getBreadcrumbs(com.globalmentor.net.URIPath navigationPath) Retrieves breadcrumbs for all the segments of a particular navigation path.
java.text.Collator	getCollatorInstance() Retrieves an instance of a collator appropriate for the current locale.
Color	getColorResource(java.lang.String resourceKey) Retrieves a Color resource from the resource bundle.
Color	getColorResource(java.lang.String resourceKey, Color defaultValue) Retrieves a Color resource from the resource bundle, using a specified default if no such resource is available.
java.net.URI	getDepictionRootURI() Reports the current depiction root URI of the session.
java.net.URI	getDepictionURI(com.globalmentor.net.URIPath navigationPath, java.lang.String... suffixes) Determines the URI to use for depiction based upon a navigation path.
java.net.URI	getDepictionURI(java.net.URI navigationURI, java.lang.String... suffixes) Determines the URI to use for depiction based upon a navigation URI.
Component	getDestinationComponent(ComponentDestination destination) Retrieves the component bound to the given destination.
InputStrategy	getInputStrategy()
java.lang.Integer	getIntegerResource(java.lang.String resourceKey) Retrieves an Integer resource from the resource bundle.
java.lang.Integer	getIntegerResource(java.lang.String resourceKey, java.lang.Integer defaultValue) Retrieves an Integer resource from the resource bundle, using a specified default if no such resource is available.
java.util.Locale	getLocale()
java.io.Writer	getLogWriter()
ModalNavigation	getModalNavigation()
Component	getNavigationComponent(com.globalmentor.net.URIPath path) Retrieves the component bound to the given application context-relative path.
com.globalmentor.net.URIPath	getNavigationPath() Reports the navigation path relative to the application context path.
Orientation	getOrientation()
Platform	getPlatform()
com.globalmentor.urf.URFResource	getPreferences(java.lang.Class<?> objectClass) Retrieves the saved preference properties for a given class.
java.security.Principal	getPrincipal()
Navigation	getRequestedNavigation()
<T> T	getResource(java.lang.String resourceKey) Retrieves an object resource from the resource bundle.
<T> T	getResource(java.lang.String resourceKey, T defaultValue) Retrieves an object resource from the resource bundle, using a specified default if no such resource is available.
java.util.ResourceBundle	getResourceBundle() Retrieves a resource bundle to be used by this session.
java.lang.String	getStringResource(java.lang.String resourceKey) Retrieves a string resource from the resource bundle.
java.lang.String	getStringResource(java.lang.String resourceKey, java.lang.String defaultValue) Retrieves a string resource from the resource bundle, using a specified default if no such resource is available.
Theme	getTheme() Returns the current session theme.
java.net.URI	getThemeURI()
java.util.TimeZone	getTimeZone()
java.net.URI	getURIResource(java.lang.String resourceKey) Retrieves a URI resource from the resource bundle.
java.net.URI	getURIResource(java.lang.String resourceKey, java.net.URI defaultValue) Retrieves a URI resource from the resource bundle, using a specified default if no such resource is available.
java.util.UUID	getUUID()
void	initialize() Called when the session is initialized.
void	initializeComponent(Component component) Initializes a component, optionally with a description in a TURF resource file.
void	initializeComponent(Component component, java.io.InputStream descriptionInputStream) Initializes a component from the contents of an URF description input stream.
void	initializeComponentFromResource(Component component, java.lang.String resourceKey) Initializes a component with a description in a TURF resource file.
boolean	input(Input input) Processes input such as a keystroke, a mouse click, or a command.
boolean	isModalNavigation()
void	log(InformationLevel level, java.lang.String subject, java.lang.String predicate, java.lang.String object, java.util.Map<?,?> parameters, java.lang.CharSequence comment) Logs the given session-related information.
void	log(java.lang.String subject, java.lang.String predicate, java.lang.String object, java.util.Map<?,?> parameters, java.lang.CharSequence comment) Logs the given session-related information with a default log level of InformationLevel.LOG.
void	navigate(java.net.URI uri) Requests navigation to the specified URI.
void	navigate(com.globalmentor.net.URIPath path) Requests navigation to the specified path.
void	navigate(com.globalmentor.net.URIPath path, Bookmark bookmark) Requests navigation to the specified path and bookmark.
void	navigate(com.globalmentor.net.URIPath path, Bookmark bookmark, java.lang.String viewportID) Requests navigation to the specified path and bookmark in an identified viewport.
void	navigate(com.globalmentor.net.URIPath path, java.lang.String viewportID) Requests navigation to the specified path in an identified viewport.
void	navigate(java.net.URI uri, java.lang.String viewportID) Requests navigation to the specified URI in an identified viewport.
void	navigateModal(java.net.URI uri, ModalNavigationListener modalListener) Requests modal navigation to the specified URI.
void	navigateModal(com.globalmentor.net.URIPath path, Bookmark bookmark, ModalNavigationListener modalListener) Requests modal navigation to the specified path and bookmark.
void	navigateModal(com.globalmentor.net.URIPath path, ModalNavigationListener modalListener) Requests modal navigation to the specified path.
void	notify(Notification... notifications) Notifies the user of one or more notifications to be presented in sequence.
void	notify(java.lang.Runnable afterNotify, Notification... notifications) Notifies the user of one or more notifications to be presented in sequence, with optional logic to be executed after all notifications have taken place.
void	notify(java.lang.Runnable afterNotify, java.lang.Throwable... errors) Notifies the user of the given error in sequence, with optional logic to be executed after notification takes place.
void	notify(java.lang.Throwable... errors) Notifies the user of the given errors in sequence.
Component	releaseDestinationComponent(ComponentDestination destination) Releases the component bound to the given destination.
java.util.Locale	requestLocale(java.util.List<java.util.Locale> requestedLocales) Requests that the locale be changed to one of the given locales.
java.net.URI	resolveURI(java.net.URI uri, java.lang.String... suffixes) Resolves a URI against the application base path, looking up the URI from the resources if necessary.
void	setBookmark(Bookmark bookmark) Changes the bookmark of the current navigation path.
void	setDepictionRootURI(java.net.URI depictionRootURI) Sets the depiction root URI of the session.
void	setInputStrategy(InputStrategy newInputStrategy) Sets the strategy for processing input.
void	setLocale(java.util.Locale newLocale) Sets the current session locale.
void	setLogWriter(java.io.Writer logWriter) Sets the log writer.
void	setNavigation(com.globalmentor.net.URIPath navigationPath, Bookmark bookmark, java.net.URI referrerURI) Sets the new navigation path and bookmark, firing a navigation event if appropriate.
void	setNavigationPath(com.globalmentor.net.URIPath navigationPath) Changes the navigation path of the session.
void	setOrientation(Orientation newOrientation) Sets the default orientation.
void	setPreferences(java.lang.Class<?> objectClass, com.globalmentor.urf.URFResource preferences) Saves preference properties for a given class.
void	setPrincipal(java.security.Principal newPrincipal) Sets the current principal (e.g.
void	setThemeURI(java.net.URI newThemeURI) Sets the URI of the session theme.
void	setTimeZone(java.util.TimeZone newTimeZone) Sets the current session time zone.

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

INPUT_STRATEGY_PROPERTY

static final java.lang.String INPUT_STRATEGY_PROPERTY

The input strategy bound property.

LOCALE_PROPERTY

static final java.lang.String LOCALE_PROPERTY

The locale bound property.

ORIENTATION_PROPERTY

static final java.lang.String ORIENTATION_PROPERTY

The orientation bound property.

PRINCIPAL_PROPERTY

static final java.lang.String PRINCIPAL_PROPERTY

The principal (e.g. user) bound property.

THEME_URI_PROPERTY

static final java.lang.String THEME_URI_PROPERTY

The theme URI bound property.

TIME_ZONE_PROPERTY

static final java.lang.String TIME_ZONE_PROPERTY

The time zone bound property.

Method Detail

getUUID

java.util.UUID getUUID()

Returns:

The unique identifier of this session.

getApplication

GuiseApplication getApplication()

Returns:

The Guise application to which this session belongs.

getLogWriter

java.io.Writer getLogWriter()

Returns:

The writer for writing to the log file, which may not be thread-safe.

setLogWriter

void setLogWriter(java.io.Writer logWriter)

Sets the log writer.

Parameters:

logWriter - The writer for writing to the log file, which may not be thread-safe.

Throws:

java.lang.NullPointerException - if the given log writer is null.

getPreferences

com.globalmentor.urf.URFResource getPreferences(java.lang.Class<?> objectClass)
                                                throws java.io.IOException

Retrieves the saved preference properties for a given class.

Parameters:

objectClass - The class for which preference properties should be returned.

Returns:

The saved preference properties for the given class.

Throws:

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

java.io.IOException - if there was an error retrieving preferences.

setPreferences

void setPreferences(java.lang.Class<?> objectClass,
                    com.globalmentor.urf.URFResource preferences)
                    throws java.io.IOException

Saves preference properties for a given class.

Parameters:

objectClass - The class for which preference properties should be saved.

preferences - The preferences to save for the given class.

Throws:

java.lang.NullPointerException - if the given class and/or preferences is null.

java.io.IOException - if there was an error storing preferences.

getDepictionRootURI

java.net.URI getDepictionRootURI()

Reports the current depiction root URI of the session. The depiction root URI is an absolute plain root URI. The session depiction root URI may be different for different sessions, and may not be equal to the application navigation base path resolved to the container's base URI.

Returns:

The depiction root URI currently representing the Guise session.

setDepictionRootURI

void setDepictionRootURI(java.net.URI depictionRootURI)

Sets the depiction root URI of the session. The depiction root URI is an absolute plain root URI.

Parameters:

depictionRootURI - The new depiction root URI of the session.

Throws:

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

java.lang.IllegalArgumentException - if the provided URI specifies a query and/or fragment.

java.lang.IllegalArgumentException - if the provided URI is not absolute.

java.lang.IllegalArgumentException - if the provided URI is not a root URI.

getDepictionURI

java.net.URI getDepictionURI(com.globalmentor.net.URIPath navigationPath,
                             java.lang.String... suffixes)

Determines the URI to use for depiction based upon a navigation path. The path will first be dereferenced for the current session and then resolved to the application base path. The resulting URI may not be absolute, but can be made absolute by resolving it against the depiction root URI.

Parameters:

navigationPath - The navigation path, which may be absolute or relative to the application.

suffixes - The suffixes, if any, to append to a resource key in a URI reference.

Returns:

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

See Also:

dereferenceURI(URI, String...), getDepictionRootURI(), GuiseApplication.getDepictionURI(URI, URIPath)

getDepictionURI

java.net.URI getDepictionURI(java.net.URI navigationURI,
                             java.lang.String... suffixes)

Determines the URI to use for depiction based upon a navigation URI. The URI will first be dereferenced for the current session and then resolved to the application base path. The resulting URI may not be absolute, but can be made absolute by resolving it against the depiction root URI.

Parameters:

navigationURI - The navigation URI, which may be absolute or have an absolute path or a path relative to the application.

suffixes - The suffixes, if any, to append to a resource key in a URI reference.

Returns:

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

See Also:

dereferenceURI(URI, String...), getDepictionRootURI(), GuiseApplication.getDepictionURI(URI, URI)

getApplicationFrame

ApplicationFrame getApplicationFrame()

Returns:

The application frame.

getPlatform

Platform getPlatform()

Returns:

The platform on which Guise objects are depicted.

getInputStrategy

InputStrategy getInputStrategy()

Returns:

The strategy for processing input.

setInputStrategy

void setInputStrategy(InputStrategy newInputStrategy)

Sets the strategy for processing input. A default input strategy is installed that, if replaced, should be set as the parent of the new input strategy. To handle new types of input, a new input strategy should create the appropriate InputEvent and dispatch it via the application frame; if the event is not consumed, it should be passed to the parent input strategy. This is a bound property.

Parameters:

newInputStrategy - The new strategy for processing input.

Throws:

java.lang.NullPointerException - if the given input strategy is null.

See Also:

INPUT_STRATEGY_PROPERTY, getApplicationFrame(), Component.dispatchInputEvent(InputEvent)

getTimeZone

java.util.TimeZone getTimeZone()

Returns:

The current session time zone.

setTimeZone

void setTimeZone(java.util.TimeZone newTimeZone)

Sets the current session time zone. This is a bound property.

Parameters:

newTimeZone - The new session time zone.

Throws:

java.lang.NullPointerException - if the given time zone is null.

See Also:

TIME_ZONE_PROPERTY

getLocale

java.util.Locale getLocale()

Returns:

The current session locale.

setLocale

void setLocale(java.util.Locale newLocale)

Sets the current session locale. The default orientation will be updated if needed to reflect the new locale. This is a bound property.

Parameters:

newLocale - The new session locale.

Throws:

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

See Also:

LOCALE_PROPERTY, setOrientation(Orientation)

requestLocale

java.util.Locale requestLocale(java.util.List<java.util.Locale> requestedLocales)

Requests that the locale be changed to one of the given locales. Each of the locales in the list are examined in order, and the first one supported by the application is used. A requested locale is accepted if a more general locale is supported. (i.e. en-US is accepted if en is supported.)

Parameters:

requestedLocales - The locales requested, in order of preference.

Returns:

The accepted locale (which may be a variation of this locale), or null if none of the given locales are supported by the application.

See Also:

GuiseApplication#getSupportedLocales(), setLocale(Locale)

getOrientation

Orientation getOrientation()

Returns:

The default internationalization orientation of components for this session.

setOrientation

void setOrientation(Orientation newOrientation)

Sets the default orientation. This is a bound property

Parameters:

newOrientation - The new default internationalization orientation of components for this session.

Throws:

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

See Also:

ORIENTATION_PROPERTY

initializeComponent

void initializeComponent(Component component)

Initializes a component, optionally with a description in a TURF resource file. This method first tries to load a PLOOP URF description of the component in a TURF file with the same name as the class file in the same directory, with an .turf extension. That is, for the class MyComponent.class this method first tries to load MyComponent.turf from the same directory. If this is successful, the component is initialized from this URF description. This implementation calls initializeComponent(Component, InputStream). The component's Component.initialize() is called whether there is an URF description. This method synchronizes on #getDocumentBuilder().

Parameters:

component - The component to initialize.

Throws:

java.util.MissingResourceException - if no resource could be found associated with the given key.

java.lang.IllegalArgumentException - if the URF description does not provide a resource description of the same type as the specified component.

java.lang.IllegalStateException - if the given component has already been initialized, or there was some other problem initializing the component.

See Also:

Component.initialize(), PLOOP

initializeComponentFromResource

void initializeComponentFromResource(Component component,
                                     java.lang.String resourceKey)
                                     throws com.globalmentor.util.DataException,
                                            java.lang.reflect.InvocationTargetException

Initializes a component with a description in a TURF resource file. This method calls Component.initialize() after initializing the component from the description. This implementation calls initializeComponent(Component, InputStream). This method synchronizes on #getDocumentBuilder().

Parameters:

component - The component to initialize.

resourceKey - The key to a TURF description resource file.

Throws:

java.util.MissingResourceException - if no resource could be found associated with the given key.

java.lang.IllegalArgumentException - if the URF description does not provide a resource description of the same type as the specified component.

java.lang.IllegalStateException - if the given component has already been initialized.

com.globalmentor.util.DataException - if the data was incorrect for component initialization.

java.lang.reflect.InvocationTargetException - if a given resource indicates a Java class the constructor of which throws an exception.

See Also:

Component.initialize()

initializeComponent

void initializeComponent(Component component,
                         java.io.InputStream descriptionInputStream)
                         throws java.io.IOException,
                                com.globalmentor.util.DataException,
                                java.lang.reflect.InvocationTargetException

Initializes a component from the contents of an URF description input stream. This method calls Component.initialize() after initializing the component from the description. This method synchronizes on #getDocumentBuilder().

Parameters:

component - The component to initialize.

descriptionInputStream - The input stream containing an URF description.

Throws:

java.lang.IllegalArgumentException - if the URF description does not provide a resource description of the same type as the specified component.

java.lang.IllegalStateException - if the given component has already been initialized.

java.io.IOException - if there is an error reading from the input stream.

com.globalmentor.util.DataException - if the data was incorrect for component initialization.

java.lang.reflect.InvocationTargetException - if a given resource indicates a Java class the constructor of which throws an exception.

See Also:

Component.initialize()

getResourceBundle

java.util.ResourceBundle getResourceBundle()
                                           throws java.util.MissingResourceException

Retrieves a resource bundle to be used by this session. One of the getXXXResource() should be used in preference to using this method directly. If this session does not yet have a resource bundle, one will be created based upon the current theme and locale. The returned resource bundle should only be used temporarily and should not be saved, as the resource bundle may change if the session locale or the application resource bundle base name changes. 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 default by Guise.

Returns:

The resource bundle containing the resources for this session, based upon the locale.

Throws:

java.util.MissingResourceException - if no resource bundle for the application's specified base name can be found or there was an error loading a resource bundle.

See Also:

GuiseApplication.loadResourceBundle(Theme, Locale), getTheme(), getLocale(), getStringResource(String), getStringResource(String, String), getBooleanResource(String), getBooleanResource(String, Boolean), getIntegerResource(String), getIntegerResource(String, Integer), getURIResource(String), getURIResource(String, URI)

getResource

<T> T getResource(java.lang.String resourceKey)
              throws java.util.MissingResourceException

Retrieves an object resource from the resource bundle. Every resource access method should eventually call this method. This is a preferred convenience method for accessing the resources in the session's resource bundle. This method involves an implicit cast that will throw a class cast exception after the method ends if the resource is not of the expected type.

Parameters:

resourceKey - The key of the resource to retrieve.

Returns:

The resource associated with the specified resource key.

Throws:

java.lang.NullPointerException - if the provided resource key is null.

java.util.MissingResourceException - if no resource could be found associated with the given key.

See Also:

getResourceBundle(), getResource(String, Object)

getResource

<T> T getResource(java.lang.String resourceKey,
                  T defaultValue)
              throws java.util.MissingResourceException

Retrieves an object resource from the resource bundle, using a specified default if no such resource is available. This is a preferred convenience method for accessing the resources in the session's resource bundle. This method involves an implicit cast that will throw a class cast exception after the method ends if the resource is not of the expected type.

Parameters:

resourceKey - The key of the resource to retrieve.

defaultValue - The default value to use if there is no resource associated with the given key.

Returns:

The resource associated with the specified resource key or the default if none is available.

Throws:

java.lang.NullPointerException - if the provided resource key is null.

java.util.MissingResourceException

See Also:

getResourceBundle(), getResource(String)

getStringResource

java.lang.String getStringResource(java.lang.String resourceKey)
                                   throws java.util.MissingResourceException

Retrieves a string resource from the resource bundle. If the resource cannot be found in the resource bundle, it will be loaded from the application's resources, if possible, treating the resource key as a locale-sensitive resource path in the application resource area. This is a preferred convenience method for accessing the resources in the session's resource bundle.

Parameters:

resourceKey - The key of the resource to retrieve, or a relative path to the resource in the application's resource area.

Returns:

The resource associated with the specified resource key.

Throws:

java.lang.NullPointerException - if the provided resource key is null.

java.util.MissingResourceException - if no resource could be found associated with the given key.

java.lang.ClassCastException - if the resource associated with the given key is not an instance of String.

See Also:

getResourceBundle(), getStringResource(String, String)

getStringResource

java.lang.String getStringResource(java.lang.String resourceKey,
                                   java.lang.String defaultValue)
                                   throws java.util.MissingResourceException

Retrieves a string resource from the resource bundle, using a specified default if no such resource is available. If the resource cannot be found in the resource bundle, it will be loaded from the application's resources, if possible, treating the resource key as a locale-sensitive resource path in the application resource area. This is a preferred convenience method for accessing the resources in the session's resource bundle.

Parameters:

resourceKey - The key of the resource to retrieve, or a relative path to the resource in the application's resource area.

defaultValue - The default value to use if there is no resource associated with the given key.

Returns:

The resource associated with the specified resource key or the default if none is available.

Throws:

java.lang.NullPointerException - if the provided resource key is null.

java.lang.ClassCastException - if the resource associated with the given key is not an instance of String.

java.util.MissingResourceException

See Also:

getResourceBundle(), getStringResource(String)

getBooleanResource

java.lang.Boolean getBooleanResource(java.lang.String resourceKey)
                                     throws java.util.MissingResourceException

Retrieves a Boolean resource from the resource bundle. If the given resource is a string, it will be interpreted according to the Boolean.valueOf(java.lang.String) rules. This is a preferred convenience method for accessing the resources in the session's resource bundle.

Parameters:

resourceKey - The key of the resource to retrieve.

Returns:

The resource associated with the specified resource key.

Throws:

java.lang.NullPointerException - if the provided resource key is null.

java.util.MissingResourceException - if no resource could be found associated with the given key.

java.lang.ClassCastException - if the resource associated with the given key is not an instance of String or Boolean object.

See Also:

getResourceBundle(), getBooleanResource(String, Boolean)

getBooleanResource

java.lang.Boolean getBooleanResource(java.lang.String resourceKey,
                                     java.lang.Boolean defaultValue)
                                     throws java.util.MissingResourceException

Retrieves a Boolean resource from the resource bundle, using a specified default if no such resource is available. If the given resource is a string, it will be interpreted according to the Boolean.valueOf(java.lang.String) rules. This is a preferred convenience method for accessing the resources in the session's resource bundle.

Parameters:

resourceKey - The key of the resource to retrieve.

defaultValue - The default value to use if there is no resource associated with the given key.

Returns:

The resource associated with the specified resource key or the default if none is available.

Throws:

java.lang.NullPointerException - if the provided resource key is null.

java.lang.ClassCastException - if the resource associated with the given key is not an instance of String or Boolean object.

java.util.MissingResourceException

See Also:

getResourceBundle(), getBooleanResource(String)

getColorResource

Color getColorResource(java.lang.String resourceKey)
                       throws java.util.MissingResourceException

Retrieves a Color resource from the resource bundle. If the given resource is a string, it will be resolved and converted to a color using AbstractModeledColor.valueOf(CharSequence). This is a preferred convenience method for accessing the resources in the session's resource bundle.

Parameters:

resourceKey - The key of the resource to retrieve.

Returns:

The resource associated with the specified resource key.

Throws:

java.lang.NullPointerException - if the provided resource key is null.

java.util.MissingResourceException - if no resource could be found associated with the given key.

java.lang.ClassCastException - if the resource associated with the given key is not an instance of String or Color.

java.lang.IllegalArgumentException - if a string is provided that is not a valid color.

See Also:

getResourceBundle(), getColorResource(String, Color), AbstractModeledColor.valueOf(CharSequence)

getColorResource

Color getColorResource(java.lang.String resourceKey,
                       Color defaultValue)
                       throws java.util.MissingResourceException

Retrieves a Color resource from the resource bundle, using a specified default if no such resource is available. If the given resource is a string, it will be resolved and converted to a color using AbstractModeledColor.valueOf(CharSequence). This is a preferred convenience method for accessing the resources in the session's resource bundle.

Parameters:

resourceKey - The key of the resource to retrieve.

defaultValue - The default value to use if there is no resource associated with the given key.

Returns:

The resource associated with the specified resource key or the default if none is available.

Throws:

java.lang.NullPointerException - if the provided resource key is null.

java.lang.ClassCastException - if the resource associated with the given key is not an instance of String or Color.

java.util.MissingResourceException

See Also:

getResourceBundle(), getColorResource(String), AbstractModeledColor.valueOf(CharSequence)

getIntegerResource

java.lang.Integer getIntegerResource(java.lang.String resourceKey)
                                     throws java.util.MissingResourceException

Retrieves an Integer resource from the resource bundle. If the given resource is a string, it will be interpreted according to the Integer.valueOf(java.lang.String) rules. This is a preferred convenience method for accessing the resources in the session's resource bundle.

Parameters:

resourceKey - The key of the resource to retrieve.

Returns:

The resource associated with the specified resource key.

Throws:

java.lang.NullPointerException - if the provided resource key is null.

java.util.MissingResourceException - if no resource could be found associated with the given key.

java.lang.ClassCastException - if the resource associated with the given key is not an instance of String or Integer.

java.lang.NumberFormatException - if the resource key identifies a string that is not a valid integer.

See Also:

getResourceBundle(), getIntegerResource(String, Integer)

getIntegerResource

java.lang.Integer getIntegerResource(java.lang.String resourceKey,
                                     java.lang.Integer defaultValue)
                                     throws java.util.MissingResourceException

Retrieves an Integer resource from the resource bundle, using a specified default if no such resource is available. If the given resource is a string, it will be interpreted according to the Integer.valueOf(java.lang.String) rules. This is a preferred convenience method for accessing the resources in the session's resource bundle.

Parameters:

resourceKey - The key of the resource to retrieve.

defaultValue - The default value to use if there is no resource associated with the given key.

Returns:

The resource associated with the specified resource key or the default if none is available.

Throws:

java.lang.NullPointerException - if the provided resource key is null.

java.lang.ClassCastException - if the resource associated with the given key is not an instance of String or Integer.

java.util.MissingResourceException

See Also:

getResourceBundle(), getIntegerResource(String)

getURIResource

java.net.URI getURIResource(java.lang.String resourceKey)
                            throws java.util.MissingResourceException

Retrieves a URI resource from the resource bundle. If the given resource is a string, it will be converted to a URI. This is a preferred convenience method for accessing the resources in the session's resource bundle.

Parameters:

resourceKey - The key of the resource to retrieve.

Returns:

The resource associated with the specified resource key.

Throws:

java.lang.NullPointerException - if the provided resource key is null.

java.util.MissingResourceException - if no resource could be found associated with the given key.

java.lang.ClassCastException - if the resource associated with the given key is not an instance of String or URI object.

java.lang.IllegalArgumentException - if a string is provided that is not a valid URI.

See Also:

getResourceBundle(), getURIResource(String, URI)

getURIResource

java.net.URI getURIResource(java.lang.String resourceKey,
                            java.net.URI defaultValue)
                            throws java.util.MissingResourceException

Retrieves a URI resource from the resource bundle, using a specified default if no such resource is available. If the given resource is a string, it will be converted to a URI. This is a preferred convenience method for accessing the resources in the session's resource bundle.

Parameters:

resourceKey - The key of the resource to retrieve.

defaultValue - The default value to use if there is no resource associated with the given key.

Returns:

The resource associated with the specified resource key or the default if none is available.

Throws:

java.lang.NullPointerException - if the provided resource key is null.

java.lang.ClassCastException - if the resource associated with the given key is not an instance of String or URI object.

java.util.MissingResourceException

See Also:

getResourceBundle(), getURIResource(String)

getCollatorInstance

java.text.Collator getCollatorInstance()

Retrieves an instance of a collator appropriate for the current locale. The returned collator instance performs collations based upon the current locale.

Specified by:

getCollatorInstance in interface com.globalmentor.text.CollatorFactory

Returns:

An instance of a collator appropriate for the current locale.

See Also:

getLocale()

getPrincipal

java.security.Principal getPrincipal()

Returns:

The current principal (e.g. logged-in user), or null if there is no principal authenticated for this session.

setPrincipal

void setPrincipal(java.security.Principal newPrincipal)

Sets the current principal (e.g. logged-in user). This is a bound property.

Parameters:

newPrincipal - The new principal, or null if there should be no associated principal (e.g. the user should be logged off).

See Also:

PRINCIPAL_PROPERTY

getTheme

Theme getTheme()
               throws java.io.IOException

Returns the current session theme. If this session's theme has not yet been loaded, this method loads the theme.

Returns:

The current session theme.

Throws:

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

See Also:

getThemeURI()

getThemeURI

java.net.URI getThemeURI()

Returns:

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

setThemeURI

void setThemeURI(java.net.URI newThemeURI)

Sets the URI of the session theme. The current theme, if any, will be released and loaded the next time getTheme() is called. This is a bound property.

Parameters:

newThemeURI - The URI of the new session theme.

Throws:

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

See Also:

THEME_URI_PROPERTY, getTheme()

getAboutApplicationActionPrototype

ActionPrototype getAboutApplicationActionPrototype()

Returns:

The action prototype for presenting application information.

getDestinationComponent

Component getDestinationComponent(ComponentDestination destination)

Retrieves the component bound to the given destination. If a component has already been created and cached, it will be be returned; otherwise, one will be created and cached.

Parameters:

destination - The destination for which a component should be returned.

Returns:

The component bound to the given destination.

Throws:

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

java.lang.IllegalStateException - if the component class bound to the destination does not provide appropriate constructors, is an interface, is abstract, or throws an exception during instantiation.

releaseDestinationComponent

Component releaseDestinationComponent(ComponentDestination destination)

Releases the component bound to the given destination.

Parameters:

destination - The destination for which any bound component should be released.

Returns:

The component previously bound to the given destination, or null if no component was bound to the given destination.

Throws:

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

getNavigationComponent

Component getNavigationComponent(com.globalmentor.net.URIPath path)

Retrieves the component bound to the given application context-relative path. This is a convenience method that retrieves the component associated with the component destination for the given navigation path. This method calls GuiseApplication#getDestination(String). This method calls getDestinationComponent(ComponentDestination).

Parameters:

path - The application context-relative path within the Guise container context.

Returns:

The component bound to the given path.

Throws:

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

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

java.lang.IllegalArgumentException - if no component is appropriate to associated the given navigation path (i.e. the given navigation path is not associated with a component destination).

java.lang.IllegalStateException - if the component class bound to the path does not provide appropriate constructors, is an interface, is abstract, or throws an exception during instantiation.

See Also:

ComponentDestination

isModalNavigation

boolean isModalNavigation()

Returns:

Whether the session is in a modal navigation state.

getModalNavigation

ModalNavigation getModalNavigation()

Returns:

The current modal navigation state, or null if there are no modal navigations.

beginModalNavigation

void beginModalNavigation(ModalNavigationPanel<?> modalNavigationPanel,
                          ModalNavigation modalNavigation)

Begins modal interaction for a particular modal panel. The modal navigation is pushed onto the stack, and an event is fired to the modal listener of the modal navigation.

Parameters:

modalNavigationPanel - The panel for which modal navigation state should begin.

modalNavigation - The state of modal navigation.

endModalNavigation

boolean endModalNavigation(ModalNavigationPanel<?> modalNavigationPanel)

Ends modal interaction for a particular modal panel. The panel is released from the cache so that new navigation will create a new modal panel. This method is called by modal panels and should seldom if ever be called directly. If the current modal state corresponds to the current navigation state, the current modal state is removed, the modal state's event is fired, and modal state is handed to the previous modal state, if any. Otherwise, navigation is transferred to the modal panel's referring URI, if any. If the given modal panel is not the panel at the current navigation path, the modal state is not changed, although navigation and releasal will still occur.

Parameters:

modalNavigationPanel - The panel for which modal navigation state should be ended.

Returns:

true if modality actually ended for the given panel.

See Also:

Frame#getReferrerURI(), #releaseDestinationComponent(String)

getNavigationPath

com.globalmentor.net.URIPath getNavigationPath()

Reports the navigation path relative to the application context path.

Returns:

The path representing the current navigation location of the Guise application.

Throws:

java.lang.IllegalStateException - if this message has been called before the navigation path has been initialized.

setNavigationPath

void setNavigationPath(com.globalmentor.net.URIPath navigationPath)

Changes the navigation path of the session. This method does not actually cause navigation to occur. If the given navigation path is the same as the current navigation path, no action occurs.

Parameters:

navigationPath - The navigation path relative to the application context path.

Throws:

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

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

java.lang.IllegalArgumentException - if the navigation path is not recognized (e.g. there is no destination associated with the navigation path).

See Also:

navigate(URIPath), navigate(URI), navigateModal(URIPath, ModalNavigationListener), navigateModal(URI, ModalNavigationListener)

getBookmark

Bookmark getBookmark()

Reports the current bookmark relative to the current navigation path.

Returns:

The bookmark relative to the current navigation path, or null if there is no bookmark specified.

setBookmark

void setBookmark(Bookmark bookmark)

Changes the bookmark of the current navigation path. This method does not necessarily cause navigation to occur, but instead "publishes" the bookmark to indicate that it is representative of the current state of the current navigation.

Parameters:

bookmark - The bookmark relative to the current navigation path, or null if there should be no bookmark.

setNavigation

void setNavigation(com.globalmentor.net.URIPath navigationPath,
                   Bookmark bookmark,
                   java.net.URI referrerURI)

Sets the new navigation path and bookmark, firing a navigation event if appropriate. If the navigation path and/or bookmark has changed, this method fires an event to all NavigationListeners in the component hierarchy, with the session as the source of the NavigationEvent. This method calls setNavigationPath(URIPath) and setBookmark(Bookmark).

Parameters:

navigationPath - The navigation path relative to the application context path.

bookmark - The bookmark for which navigation should occur at this navigation path, or null if there is no bookmark involved in navigation.

referrerURI - The URI of the referring navigation panel or other entity with no query or fragment, or null if no referring URI is known.

Throws:

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

See Also:

setNavigationPath(URIPath), setBookmark(Bookmark), getApplicationFrame()

fireNavigated

void fireNavigated(java.net.URI referrerURI)

Fires a NavigationEvent to all NavigationListeners in the session application frame hierarchy.

Parameters:

referrerURI - The URI of the referring navigation panel or other entity with no query or fragment, or null if no referring URI is known.

See Also:

getNavigationPath(), getBookmark(), getApplicationFrame(), NavigationListener, NavigationEvent

getRequestedNavigation

Navigation getRequestedNavigation()

Returns:

The requested navigation, or null if no navigation has been requested.

clearRequestedNavigation

void clearRequestedNavigation()

Removes any requests for navigation.

navigate

void navigate(com.globalmentor.net.URIPath path)

Requests navigation to the specified path. The session need not perform navigation immediately or ever, and may postpone or deny navigation at some later point. Later requested navigation before navigation occurs will override this request.

Parameters:

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

Throws:

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

See Also:

navigate(URI)

navigate

void navigate(com.globalmentor.net.URIPath path,
              java.lang.String viewportID)

Requests navigation to the specified path in an identified viewport. The session need not perform navigation immediately or ever, and may postpone or deny navigation at some later point. Later requested navigation before navigation occurs will override this request.

Parameters:

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

viewportID - The ID of the viewport in which navigation should occur, or null if navigation should occur in the current viewport.

Throws:

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

See Also:

navigate(URI, String)

navigate

void navigate(com.globalmentor.net.URIPath path,
              Bookmark bookmark)

Requests navigation to the specified path and bookmark. The session need not perform navigation immediately or ever, and may postpone or deny navigation at some later point. Later requested navigation before navigation occurs will override this request.

Parameters:

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

bookmark - The bookmark at the given path, or null if no bookmark should be included in the navigation.

Throws:

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

See Also:

navigate(URI)

navigate

void navigate(com.globalmentor.net.URIPath path,
              Bookmark bookmark,
              java.lang.String viewportID)

Requests navigation to the specified path and bookmark in an identified viewport. The session need not perform navigation immediately or ever, and may postpone or deny navigation at some later point. Later requested navigation before navigation occurs will override this request.

Parameters:

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

bookmark - The bookmark at the given path, or null if no bookmark should be included in the navigation.

viewportID - The ID of the viewport in which navigation should occur, or null if navigation should occur in the current viewport.

Throws:

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

See Also:

navigate(URI, String)

navigate

void navigate(java.net.URI uri)

Requests navigation to the specified URI. The session need not perform navigation immediately or ever, and may postpone or deny navigation at some later point. Later requested navigation before navigation occurs will override this request.

Parameters:

uri - Either a relative or absolute path, or an absolute URI.

Throws:

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

navigate

void navigate(java.net.URI uri,
              java.lang.String viewportID)

Requests navigation to the specified URI in an identified viewport. The session need not perform navigation immediately or ever, and may postpone or deny navigation at some later point. Later requested navigation before navigation occurs will override this request.

Parameters:

uri - Either a relative or absolute path, or an absolute URI.

viewportID - The ID of the viewport in which navigation should occur, or null if navigation should occur in the current viewport.

Throws:

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

navigateModal

void navigateModal(com.globalmentor.net.URIPath path,
                   ModalNavigationListener modalListener)

Requests modal navigation to the specified path. The session need not perform navigation immediately or ever, and may postpone or deny navigation at some later point. Later requested navigation before navigation occurs will override this request.

Parameters:

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

modalListener - The listener to respond to the end of modal interaction.

Throws:

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

See Also:

navigateModal(URI, ModalNavigationListener)

navigateModal

void navigateModal(com.globalmentor.net.URIPath path,
                   Bookmark bookmark,
                   ModalNavigationListener modalListener)

Requests modal navigation to the specified path and bookmark. The session need not perform navigation immediately or ever, and may postpone or deny navigation at some later point. Later requested navigation before navigation occurs will override this request.

Parameters:

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

bookmark - The bookmark at the given path, or null if no bookmark should be included in the navigation.

modalListener - The listener to respond to the end of modal interaction.

Throws:

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

See Also:

navigateModal(URI, ModalNavigationListener)

navigateModal

void navigateModal(java.net.URI uri,
                   ModalNavigationListener modalListener)

Requests modal navigation to the specified URI. The session need not perform navigation immediately or ever, and may postpone or deny navigation at some later point. Later requested navigation before navigation occurs will override this request.

Parameters:

uri - Either a relative or absolute path, or an absolute URI.

modalListener - The listener to respond to the end of modal interaction.

Throws:

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

getBreadcrumb

Breadcrumb getBreadcrumb(com.globalmentor.net.URIPath navigationPath)

Retrieves a breadcrumb for a particular navigation path.

Parameters:

navigationPath - The navigation path which a breadcrumb should be returned.

Returns:

A breadcrumb for the given navigation URI.

Throws:

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

getBreadcrumbs

java.util.List<Breadcrumb> getBreadcrumbs(com.globalmentor.net.URIPath navigationPath)

Retrieves breadcrumbs for all the segments of a particular navigation path. This method delegates to getBreadcrumb(URIPath) to create each segment breadcrumb.

Parameters:

navigationPath - The navigation path which breadcrumbs should be returned.

Returns:

A list of breadcrumbs for the given navigation URI.

Throws:

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

initialize

void initialize()

Called when the session is initialized.

Throws:

java.lang.IllegalStateException - if the session is already initialized.

See Also:

destroy()

destroy

void destroy()

Called when the session is destroyed.

Throws:

java.lang.IllegalStateException - if the session has not yet been initialized or has already been destroyed.

See Also:

initialize()

createTempPublicResource

com.globalmentor.net.URIPath createTempPublicResource(java.lang.String baseName,
                                                      java.lang.String extension)
                                                      throws java.io.IOException

Creates a temporary resource available at a public application navigation path but with access restricted to this session. The file will be created in the application's temporary file directory. If the resource is restricted to the current Guise session, the resource will be deleted when the current Guise session ends. This is a convenience method that delegates to GuiseApplication.createTempAsset(String, String, GuiseSession).

Parameters:

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

extension - The extension to use for the temporary file.

Returns:

A public application navigation path that can be used to access the resource only from this session.

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.io.IOException - if there is a problem creating the public resource.

See Also:

GuiseApplication.createTempAsset(String, String, GuiseSession), GuiseApplication.getTempDirectory()

createBusyComponent

Component createBusyComponent()

Creates a component to indicate Guise busy status.

Returns:

A component to indicate Guise busy status.

See Also:

Theme.GLYPH_BUSY

input

boolean input(Input input)

Processes input such as a keystroke, a mouse click, or a command. A new InputEvent will be created and dispatched via the application frame. If an input event is still not consumed after dispatching, its input is processed by the installed input strategy, if any.

Parameters:

input - The input to process.

Returns:

true if the input was consumed and should not be processed further.

Throws:

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

java.lang.IllegalArgumentException - if input was given that this session does not know how to process.

See Also:

getApplicationFrame(), Component.dispatchInputEvent(InputEvent), getInputStrategy(), InputStrategy.input(Input), InputEvent.isConsumed()

log

void log(java.lang.String subject,
         java.lang.String predicate,
         java.lang.String object,
         java.util.Map<?,?> parameters,
         java.lang.CharSequence comment)

Logs the given session-related information with a default log level of InformationLevel.LOG. This is a convenience method that delegates to log(InformationLevel, String, String, String, Map, CharSequence).

Parameters:

subject - The log subject identification, or null if there is no related subject.

predicate - The log predicate identification, or null if there is no related predicate.

object - The log object identification, or null if there is no related object.

parameters - The map of log parameters, or null if there are no parameters.

comment - The log comment, or null if there is no log comment.

Throws:

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

log

void log(InformationLevel level,
         java.lang.String subject,
         java.lang.String predicate,
         java.lang.String object,
         java.util.Map<?,?> parameters,
         java.lang.CharSequence comment)

Logs the given session-related information.

Parameters:

level - The log information level.

subject - The log subject identification, or null if there is no related subject.

predicate - The log predicate identification, or null if there is no related predicate.

object - The log object identification, or null if there is no related object.

parameters - The map of log parameters, or null if there are no parameters.

comment - The log comment, or null if there is no log comment.

Throws:

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

notify

void notify(Notification... notifications)

Notifies the user of one or more notifications to be presented in sequence. The notification's label and/or icon, if specified, will be used as the dialog title and icon, respectively; if either is not specified, a label and/or icon based upon the notification's severity will be used. If the selected option to any notification is fatal, the remaining notifications will not be performed. The absence of an option selection is considered fatal only if a fatal option was presented for a given notification. This is a convenience method that delegates to notify(Runnable, Notification...).

Parameters:

notifications - One or more notification informations to relay.

Throws:

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

java.lang.IllegalArgumentException - if no notifications are given.

notify

void notify(java.lang.Runnable afterNotify,
            Notification... notifications)

Notifies the user of one or more notifications to be presented in sequence, with optional logic to be executed after all notifications have taken place. The notification's label and/or icon, if specified, will be used as the dialog title and icon, respectively; if either is not specified, a label and/or icon based upon the notification's severity will be used. If the selected option to any notification is fatal, the remaining notifications and the specified logic, if any, will not be performed. The absence of an option selection is considered fatal only if a fatal option was presented for a given notification.

Parameters:

notifications - One or more notification informations to relay.

afterNotify - The code that executes after notification has taken place, or null if no action should be taken after notification.

Throws:

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

java.lang.IllegalArgumentException - if no notifications are given.

notify

void notify(java.lang.Throwable... errors)

Notifies the user of the given errors in sequence. If the selected option to any notification is fatal, the remaining notifications will not be performed. The absence of an option selection is considered fatal only if a fatal option was presented for a given notification. This is a convenience method that delegates to notify(Runnable, Throwable...).

Parameters:

errors - The errors with which to notify the user.

Throws:

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

java.lang.IllegalArgumentException - if no errors are given.

notify

void notify(java.lang.Runnable afterNotify,
            java.lang.Throwable... errors)

Notifies the user of the given error in sequence, with optional logic to be executed after notification takes place. If the selected option to any notification is fatal, the remaining notifications and the specified logic, if any, will not be performed. The absence of an option selection is considered fatal only if a fatal option was presented for a given notification. This is a convenience method that delegates to notify(Runnable, Notification...).

Parameters:

error - The error with which to notify the user.

afterNotify - The code that executes after notification has taken place, or null if no action should be taken after notification.

Throws:

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

java.lang.IllegalArgumentException - if no errors are given.

dereferenceString

java.lang.String dereferenceString(java.lang.String string)
                                   throws java.util.MissingResourceException

Dereferences a string by replacing any string references with a string from the resources. A string reference begins with the Start of String (SOS) control character (U+0098) and ends with a String Terminator (ST) control character (U+009C). The string between these delimiters will be used to look up a string resource using getStringResource(String). Strings retrieved from resources will be recursively dereferenced.

String references appearing between an SOS/ST pair that that begin with the character will be considered string values and, after they are recursively dereferenced, will be applied as formatting arguments to the remaining dereferenced text using MessageFormat.format(String, Object...).

Parameters:

string - The string to be dereferenced.

Returns:

The dereferenced string with any string references replaced with the appropriate string from the resources.

Throws:

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

java.lang.IllegalArgumentException - if a string reference has no ending String Terminator control character (U+009C).

java.util.MissingResourceException - if no resource could be found associated with a string reference.

java.lang.ClassCastException - if the resource associated with a string reference is not an instance of String.

See Also:

Resources.createStringResourceReference(String), Resources.createStringValueReference(String), getStringResource(String)

dereferenceURI

java.net.URI dereferenceURI(java.net.URI uri,
                            java.lang.String... suffixes)
                            throws java.util.MissingResourceException

Dereferences a URI by looking up any references from the resources if necessary. If the URI has the scheme, its scheme-specific part will be used to look up the actual URI using getURIResource(String). If suffixes are given, they will be appended to the resource key in order, separated by '.'. If no resource is associated with that resource key, a resource will be retrieved using the unadorned resource key. URIs retrieved from resources will be recursively dereferenced without suffixes.

Parameters:

uri - The URI to be dereferenced.

suffixes - The suffixes, if any, to append to a resource key in a URI reference.

Returns:

The URI dereferenced from the resources.

Throws:

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

java.util.MissingResourceException - if no resource could be found associated with a string reference.

See Also:

Resources.createURIResourceReference(String), getURIResource(String)

resolveURI

java.net.URI resolveURI(java.net.URI uri,
                        java.lang.String... suffixes)
                        throws java.util.MissingResourceException

Resolves a URI against the application base path, looking up the URI from the resources if necessary. The URI will be dereferenced before it is resolved. 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 "relative/path" will yield "/path/to/application/relative/path", while resolving "/absolute/path" will yield "/absolute/path". Resolving "http://example.com/path" will yield "http://example.com/path".

Parameters:

uri - The URI to be resolved.

suffixes - The suffixes, if any, to append to a resource key in a URI reference.

Returns:

The uri resolved against resources the application base path.

Throws:

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

java.util.MissingResourceException - if no resource could be found associated with a string reference.

See Also:

dereferenceURI(URI, String...), GuiseApplication.resolveURI(URI)