oracle.cabo.share.config
Class Configuration

java.lang.Object
  |
  +--oracle.cabo.share.config.Configuration

Direct Known Subclasses:

ConfigurationImpl, Customization

public abstract class Configuration

extends java.lang.Object

The Configuration class and its default implementation, ConfigurationImpl, are responsible for providing UIX URLs and file paths to all of the UIX projects. It also provides APIs for retrieving generic object properties. By localizing all this information in a single object not connected to the UIX Components RenderingContext or any other per-request object, we allow clients to configure UIX in a single location in a client's code using a unified API.

Before developers consider using this API, they should consider using the WEB-INF/uix-config.xml file, which provides a simple XML format for configuring UIX.

This class is immutable; clients use the ConfigurationImpl class to set the properties. In general, we expect clients will maintain one or a small set of Configuration objects in a central code location (e.g., one for HTML, another for WML), and reuse these configuration objects across requests.

Each Configuration object must have a unique name, and must be registered (with the register() method). This is critical for allowing UIX JSPs launched by a page to execute with the same Configuration. It also provides a convenience for clients, who can retrieve a configuration simply by calling the static getConfiguration() method.

UIX directory structure:

The default UIX configuration uses the following directory structure, relative to the context path.

   /cabo             (empty)
     |
     +-- /images     (static UIX Components images)
     |   |
     |   +-- /cache  (UIX-generated images)
     |
     +-- /styles     (BLAF.xss)
     |   |
     |   +-- /cache  (UIX-generated stylesheets)
     |
     +-- /jsLibs     (UIX Components Javascript libraries)
     |
     +-- /jsps       (UIX Components JSPs)
 

This hierarchy can be modified at any point; subdirectories, if left defaulted, will continue from their parents. For example, setting the "/images" directory to "/foo" will result in UIX generating its images into "/foo/cache". (Clients should be careful when setting the /jsps directory - see the documentation for the JSPS_DIRECTORY constant.)

Full path vs. context path:

By default, UIX uses a "context URI" and "context path" for all URIs and filesystem and paths. Clients can register either full paths, in which case they must provide both a full URL and a full filesystem path, or context-relative URLs, in which case they need only provide a partial URL.

For clients running against the Servlet 2.2 API, the context URI is the path prefix associated with the ServletContext that this servlet is a part of; see section 5.4 of the Servlet specification. The context path is the path to the directory on the local file system for that ServletContext. For example, in Tomcat, each subdirectory of "\webapps" corresponds to a ServletContext.

For clients using Servlet 2.0 or 2.1, the context URI is "/", and the context path will be the filesystem directory containing the webserver root.

Examples:

The UIX Components images and UIX Dynamic Image caches are being installed on "d:\OA_MEDIA\", and at the URL "/media/". All other properties default off of the default configuration supplied by uix-config.xml.

     ApplicationConfiguration appConfig =
       ApplicationConfiguration.getInstance(servletContext);
     ConfigurationImpl config =
       new ConfigurationImpl("OAConfig", appConfig.getDefault());
     config.putFullURIAndPath(config.IMAGES_DIRECTORY,
                              "/media/",
                              "d:\OA_MEDIA\");
     config.register(servletContext);
 

The UIX Components JSPs will be installed alongside the rest of the application. All other properties default off of the default configuration supplied by uix-config.xml:

     ApplicationConfiguration appConfig =
       ApplicationConfiguration.getInstance(servletContext);
     ConfigurationImpl config =
       new ConfigurationImpl("OAConfig", appConfig.getDefault());
     config.putRelativeURI(config.JSPS_DIRECTORY, "");
     config.register(servletContext);
 

See Also:

ConfigurationImpl

Field Summary

static java.lang.Object	ACCESSIBILITY_MODE This is the key to use to get at the current accessibility mode.
static java.lang.Object	BASE_DIRECTORY Key for the base UIX directory.
static java.lang.Object	DISABLE_CONTENT_COMPRESSION Disables optimizations that are normally performed by the UIX Renderers to reduce content size.
static java.lang.Object	HEADLESS Key for enabled headless rendering.
static java.lang.Object	HELP_PROVIDER Key for the HelpProvider property.
static java.lang.Object	IMAGE_SERVLET_URL Key used to specify the URL location of the ImageServlet to use for image generation.
static java.lang.Object	IMAGE_TYPE_MANAGER Key for the ImageTypeManager property.
static java.lang.Object	IMAGES_CACHE_DIRECTORY Key for the UIX image cache directory.
static java.lang.Object	IMAGES_DIRECTORY Key for the UIX images directory.
static java.lang.Object	JSLIBS_DIRECTORY Key for the UIX jsLibs directory.
static java.lang.Object	JSPS_DIRECTORY Key for the UIX JSP directory.
static java.lang.Object	LOOK_AND_FEEL Key for the LookAndFeel property.
static java.lang.Object	LOOK_AND_FEEL_MANAGER Key for the LookAndFeelManager property.
static java.lang.Object	RENDERER_MANAGER Key for the RendererManager property.
static java.lang.Object	STYLE_SHEET_NAME Key for the XSS style sheet name property.
static java.lang.Object	STYLES_CACHE_DIRECTORY Key for the UIX styles cache directory.
static java.lang.Object	STYLES_DIRECTORY Key for the UIX styles directory.
static java.lang.Object	TECATE_SERVLET_URL Deprecated. Use IMAGE_SERVLET_URL
static java.lang.Object	TRANSLATION_LOCALE_MAPPER Key for the Translation Locale Mapper property.
static java.lang.Object	USER_STYLE_SHEET Key for the UserStyleSheetProperty.
static java.lang.Object	XML_PROVIDER Key for the XMLProvider property.

Constructor Summary

Configuration(java.lang.String name)
Create a Configuration with a name.

Method Summary

static Configuration	getConfiguration(javax.servlet.ServletContext context, java.lang.String name) Returns the configuration registered with the given name.
static Configuration	getConfiguration(java.lang.String name) Deprecated. since 2.1.6; use getConfiguration(ServletContext, String)
java.lang.String	getName() Return the name of this Configuration.
abstract java.lang.String	getPath(java.lang.Object key, java.lang.String contextPath) Return a path for a UIX directory.
abstract java.lang.Object	getProperty(java.lang.Object key) Return a registered property.
abstract java.lang.String	getURI(java.lang.Object key, java.lang.String contextURI) Return a URI for a UIX directory.
abstract boolean	isDebug() Returns whether the configuration is in debug mode.
void	register() Deprecated. since 2.1.6; use register(ServletContext)
void	register(javax.servlet.ServletContext context) Registers a Configuration within a web application.
void	unregister() Unregisters a Configuration.
void	unregister(javax.servlet.ServletContext context) Unregisters a Configuration.

Methods inherited from class java.lang.Object

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

Field Detail

BASE_DIRECTORY

public static final java.lang.Object BASE_DIRECTORY

Key for the base UIX directory.

IMAGES_DIRECTORY

public static final java.lang.Object IMAGES_DIRECTORY

Key for the UIX images directory.

IMAGES_CACHE_DIRECTORY

public static final java.lang.Object IMAGES_CACHE_DIRECTORY

Key for the UIX image cache directory.

STYLES_DIRECTORY

public static final java.lang.Object STYLES_DIRECTORY

Key for the UIX styles directory.

STYLES_CACHE_DIRECTORY

public static final java.lang.Object STYLES_CACHE_DIRECTORY

Key for the UIX styles cache directory.

JSLIBS_DIRECTORY

public static final java.lang.Object JSLIBS_DIRECTORY

Key for the UIX jsLibs directory.

JSPS_DIRECTORY

public static final java.lang.Object JSPS_DIRECTORY

Key for the UIX JSP directory. Clients must be careful when setting this parameter. When the JSPs are executed, they will attempt to use the same Configuration as the page that launched them. However, if the JSPs were launched onto a different machine, that configuration may not be available. Even if launched onto the same machine, any context-relative directories will be resolved relative to the new JSP - not the original page. Consequently, if clients set this directory to a full path/URI, they should generally set all directories to full paths.

LOOK_AND_FEEL

public static final java.lang.Object LOOK_AND_FEEL

Key for the LookAndFeel property. The LookAndFeel name stored in this key is used to help determine the default LookAndFeel instance to use.

See Also:

LookAndFeel

LOOK_AND_FEEL_MANAGER

public static final java.lang.Object LOOK_AND_FEEL_MANAGER

Key for the LookAndFeelManager property. The LookAndFeelManager instance stored under this key is used to choose the LookAndFeel to use.

See Also:

LookAndFeelManager

STYLE_SHEET_NAME

public static final java.lang.Object STYLE_SHEET_NAME

Key for the XSS style sheet name property. Any value registered here will be used as the default stylesheet for all UIX projects. The stylesheet will be looked for in the directory specified by the STYLES_DIRECTORY key.

RENDERER_MANAGER

public static final java.lang.Object RENDERER_MANAGER

Key for the RendererManager property. Any UIX Components RendererManager stored at this key will be used by UIX Components's ServletRenderingContext if none is explicitly attached.

TRANSLATION_LOCALE_MAPPER

public static final java.lang.Object TRANSLATION_LOCALE_MAPPER

Key for the Translation Locale Mapper property. If a oracle.bali.share.nls.LocaleMapper instance is set on with this property, it should be used to determine the Locale to be used for translations based on the Locale used for internationalization.

XML_PROVIDER

public static final java.lang.Object XML_PROVIDER

Key for the XMLProvider property. UIX projects will use the String, Class, or XMLProvider instance registered with this property.

HELP_PROVIDER

public static final java.lang.Object HELP_PROVIDER

Key for the HelpProvider property. UIX projects will use the HelpProvider instance registered with this property for context sensitive help. The registered HelpProvider instance is automatically stored on the UIX Component's RenderingContext. See the HelpProvider interface for more information.

IMAGE_TYPE_MANAGER

public static final java.lang.Object IMAGE_TYPE_MANAGER

Key for the ImageTypeManager property. The ImageTypeManager stored at this key will be used by UIX Dynamic Images to obtain image type information used for image generation.

HEADLESS

public static final java.lang.Object HEADLESS

Key for enabled headless rendering. The value is a Boolean object. If set to Boolean.TRUE, UIX Components will avoid any rendering which requires graphical capabilities. This means, for example, that existing cached images will be used, but new images will not be dynamically generated. Enabling headless rendering might cause a slight degradation of the UI, as elements which are best implemented as images could instead be rendered as HTML links or using table-based constructs.

IMAGE_SERVLET_URL

public static final java.lang.Object IMAGE_SERVLET_URL

Key used to specify the URL location of the ImageServlet to use for image generation.

TECATE_SERVLET_URL

public static final java.lang.Object TECATE_SERVLET_URL

Deprecated. Use IMAGE_SERVLET_URL

Key used to specify the URL location of the ImageServlet to use for image generation.

USER_STYLE_SHEET

public static final java.lang.Object USER_STYLE_SHEET

Key for the UserStyleSheetProperty. The styles defined by the UserStyleSheet instance stored are merged with styles defined by the UIX Styles StyleProvider when generating a new style sheet.

See Also:

UserStyleSheet, StyleProvider

ACCESSIBILITY_MODE

public static final java.lang.Object ACCESSIBILITY_MODE

This is the key to use to get at the current accessibility mode.

See Also:

AccessibilityMode

DISABLE_CONTENT_COMPRESSION

public static final java.lang.Object DISABLE_CONTENT_COMPRESSION

Disables optimizations that are normally performed by the UIX Renderers to reduce content size.

This Boolean property controls whether or not UIX Renderer implementations should attempt to reduce the size of generated content, for example, by compressing style class names. These optimizations are enabled by default. In general, clients should not need to disable these optimizations. However, clients that want to disable this functionality for testing or debugging purposes can do so by setting this property to Boolean.TRUE.

Constructor Detail

Configuration

public Configuration(java.lang.String name)

Create a Configuration with a name. The name must be non-null. The Configuration must be registered (with the register() method) before it is used.

See Also:

register()

Method Detail

getConfiguration

public static Configuration getConfiguration(java.lang.String name)

Deprecated. since 2.1.6; use getConfiguration(ServletContext, String)

Returns the configuration registered globally with the given name.

getConfiguration

public static Configuration getConfiguration(javax.servlet.ServletContext context,
                                             java.lang.String name)

Returns the configuration registered with the given name.

register

public void register()

Deprecated. since 2.1.6; use register(ServletContext)

Globally registers a Configuration. Configurations must be registered before they are used.

register

public void register(javax.servlet.ServletContext context)

Registers a Configuration within a web application. Configurations must be registered before they are used.

unregister

public void unregister()

Unregisters a Configuration. In general, Configuration instances exist for the life time of the application and do not need to be unregistered. However, Customization instances may be registered for the life time of the user session, and should be unregistered after the user has logged out, or when the session expires.

unregister

public void unregister(javax.servlet.ServletContext context)

Unregisters a Configuration. In general, Configuration instances exist for the life time of the application and do not need to be unregistered. However, Customization instances may be registered for the life time of the user session, and should be unregistered after the user has logged out, or when the session expires.

getName

public java.lang.String getName()

Return the name of this Configuration. While this name is generally non-null, the default configuration has a null name.

getURI

public abstract java.lang.String getURI(java.lang.Object key,
                                        java.lang.String contextURI)

Return a URI for a UIX directory.

Parameters:

key - the key used to identify the directory

contextURI - the current contextURI; this will be preprended to the returned URI if this directory is registered as (or defaulting to) context-relative. This path must not be terminated with a separator ("/").

Returns:

a URI, which will always be terminated with a separator

Throws:

DirectoryUnavailableException - if the directory is unavailable

getPath

public abstract java.lang.String getPath(java.lang.Object key,
                                         java.lang.String contextPath)

Return a path for a UIX directory.

Parameters:

key - the key used to identify the directory

contextPath - the current context path; this will be preprended to the returned path if this directory is registered as (or defaulting to) context-relative.

Returns:

a full file system path, which will always be terminated with the appropriate separator for the file system

Throws:

DirectoryUnavailableException - if the directory is unavailable

getProperty

public abstract java.lang.Object getProperty(java.lang.Object key)

Return a registered property.

Parameters:

key - the key used to identify the property

Returns:

the registered object, or null if no object was registered.

isDebug

public abstract boolean isDebug()

Returns whether the configuration is in debug mode.