Contents
Previous
Next
| UIX Developer's Guide |
Contents |
Previous |
Next |
This chapter discusses the Configuration API, which is used for managing configuration information for all parts of a UIX application. The chapter contains the following sections:
The Configuration API is UIX's mechanism for passing global
configuration information to all parts of the UIX framework.
Configuration information consists of three types of information:
URLs, file system paths, and a number of other properties. Both URLs
and paths are used to indicate the location of UIX resources, such as
images or style sheets used by the UIX framework. All configuration
information is accessed via instances of the
Configuration class, which is an immutable base class.
The Configuration API also provides a companion mutable subclass,
ConfigurationImpl, which applications can use to override
default configuration values.
Configuration objects can be created from Java, but
it's much easier to use the uix-config.xml file in your
WEB-INF directory, which provides a simple XML format for
creating configurations.
Configuration objects are passed throughout the UIX
framework via the various project-specific contexts, such as the
Controller's BajaContext, the Components'
RenderingContext, the Images' ImageContext,
and so forth. Unlike the other context objects, which are created to
service a single HTTP request and are released upon completion of the
response, Configuration objects exist for the lifetime of
the application. This allows the application to perform configuration
initialization once, and then reuse a single
Configuration object (or a small number of
Configuration objects) to service all requests.
The UIX framework makes use of a variety of resource files, such as images and style sheets, which are required to be installed on a web server for use by UIX-generated web pages. In many cases, web applications require that application-specific resources be installed in a particular standard directory. For example, an application may require that its images be installed in the "/images" directory. The problem with this approach is that it introduces the potential for resource file name collisions between different applications. Imagine two different applications which refer to "/images/logo.gif" or "styles.css". These two applications would not be able to co-exist on a single web server. The UIX framework avoids such resource file name collisions in two ways. First, the UIX framework partitions off its own resources by placing them in default resource directories under "/cabo". Second, the UIX framework allows default resource locations to be overridden via the Configuration API.
The following table lists the name, default location, and contents for
each of the UIX resource directories. The names are specified using
the directory constants defined in the Configuration
class. The default locations are specified as relative URLs.
| Java Name | XML Element | Default Location | Contents |
|---|---|---|---|
| BASE_DIRECTORY | <base-directory> | /cabo/ | Contains all of the other UIX resource directories |
| IMAGES_DIRECTORY | <images-directory> | /cabo/images/ | Contains static images used by UIX Components |
| STYLES_DIRECTORY | <styles-directory> | /cabo/styles/ | Contains XML Style Sheet documents used by UIX |
| JSLIBS_DIRECTORY | <jslibs-directory> | /cabo/jsLibs/ | Contains JavaScript library files used internally by UIX |
| JSPS_DIRECTORY | <jsps-directory> | /cabo/jsps/ | Contains JSP files used internally by UIX |
| IMAGES_CACHE_DIRECTORY | <images-cache-directory> | /cabo/images/cache/ | Contains application-specific images which are dynamically generated by UIX |
| STYLES_CACHE_DIRECTORY | <styles-cache-directory> | /cabo/styles/cache/ | Contains Cascading Style Sheet files which are dynamically generated by UIX |
The UIX resource directory structure is hierarchical. Changing the location of a parent directory also causes the location of child directories to be moved. For example, changing the IMAGES_DIRECTORY will implicitly change IMAGES_CACHE_DIRECTORY, and changing BASE_DIRECTORY will implicitly change all other directories.
All of the default locations defined above can be modified by using
a ConfigurationImpl instance which has been configured
with application-specific values or by adding elements to
WEB-INF/uix-config.xml.
uix-config.xmlUIX makes it easy to set up configuration objects with a single XML
file. This file must be stored in a uix-config.xml file
in your WEB-INF directory. This is the same
WEB-INF directory where web.xml lists
servlets and file mappings. (This directory only exists for Java
Servlet 2.1 or later.)
The WEB-INF/uix-config.xml file always begins (and ends)
with the same element, <configurations>. Inside
that element it contains a series of elements that will configure UIX.
<?xml version="1.0" encoding="ISO-8859-1"?>
<configurations xmlns="http://xmlns.oracle.com/uix/config">
<!-- A series of properties global to your application -->
<application-configuration>
<uix-path>c:\yourDirectory\uixFiles\</uix-path>
<check-modified>true</check-modified>
<ui-extensions>
<template-library>templates/library.uit</template-library>
</ui-extensions>
</application-configuration>
<!-- A set of default properties -->
<default-configuration>
<base-path>
<context-uri>uixInst</context-uri>
</base-path>
<help-provider>
<ohw-servlet-url>http://yourserver.com/ohw</ohw-servlet-url>
</help-provider>
</default-configuration>
<!-- An alternate configuration that disables accessibility features -->
<configuration name="noADA">
<accessibility-mode>inaccessible</accessibility-mode>
</configuration>
<!-- And another configuration that maxes out accessibility features -->
<configuration name="maxADA">
<accessibility-mode>screenReader</accessibility-mode>
<style-sheet-name>myBigStyleSheet.xss</style-sheet-name>
</configuration>
</configurations>
We'll shortly talk about all of the elements you can use in a configuration file, but a quick run-through of this example should give you a lay of the land.
Each uix-config.xml file contains three sections, each
of which is optional:
<application-configuration> section
defines properties that will be global to an entire web application.
<default-configuration> section
defines properties that will be used as defaults - but can be overridden.
<configuration> elements
let you define named overrides of the
<default-configuration>.
In our example, <application-configuration> has
informed UIX that it should search for its .uix files in the
"c:\yourDirectory\uixFiles\" directory. (This doesn't affect where
UIX looks for images, Javascript libraries, etc. - just the UIX
files). We've also asked that UIX pay attention to when files are
modified so it can drop the cached version and reload the file; this
makes debugging much easier, but carries a small performance hit.
Finally, we've registered a single template library, which means UIX
users won't need to manually import the library on each page.
Next, the <default-configuration> sets up two
more properties. First, it changes <base-path>,
which is the root directory where UIX installables live. Then, it
points UIX at an instance of the Oracle Help for the Web (OHW)
servlet; with just these few lines, all your UIX pages will support
context-sensitive help! (Oracle Help for the Web is a powerful
web-based help solution that is available for free from Oracle. Visit
the Oracle Technology Network (http://otn.oracle.com) for
a more information.)
Finally, we add two named <configuration>
options to adjust the level of accessibility support. One option
disables accessibility features, and the other enhances accessibility
from its default. These configurations would let us tailor our output
to the specific user, though it's still up to an application to decide
which user gets which setting (with a preferences page, for example).
Both of these <configuration> choices also inherit
both of the values set in <default-configuration>,
so there's no need to re-specify the OHW server or the base path.
The <application-configuration> element supports
several children. The order of these children does matter. They
must be included in the order they're described here.
Redefines where UIX will search for .uix and .uit files. (This doesn't affect where UIX looks for images, Javascript libraries, etc. - just the UIX pages and templates). By default, UIX will look for these files in the root of your web application. You can use an absolute path or a path relative to your web application.
Example:
<uix-path>c:\somePath\file.uix</uix-path>
Affects whether dynamically generated images will have file modification dates checked or ignored. Also used to decide whether to check that files in the image cache still exist. Defaults to "true", but can be set to "false" to slightly improve performance.
Example:
<check-images-modified>false</check-images-modified>
Affects whether dynamically generated style sheet files will have file modification dates checked or ignored. Also used to decide whether to check that files in the style sheet cache still exist. Defaults to "true", but can be set to "false" to slightly improve performance.
Example:
<check-styles-modified>falselt;/check-styles-modified>
Affects whether uiXML file modification dates should be checked or ignored. The only legal values are "true" and "false". It's easier to develop with this set to "true", but this is less efficient in deployed applications.
Example:
<check-modified>true</check-modified>
The <display-parse-errors> element affects how UIX will respond to problems parsing UIX files. When set to "true", UIX will display a cleanly formatted error page. When set to "false", it will log any errors encountered but display whatever portions of the page successfully parsed.
Example:
<display-parse-errors>false</display-parse-errors>
The <lenient-date-formats> element affects whether date formatting should be lenient. This can also be set from Java code using oracle.cabo.share.nls.MutableDateFormatContext@setLenient. When leniency is activated, date fields will allow some formats that do not exactly match the requested server-side format (but have an unambiguous interpretation). While client-side code will attempt to fix up fields, server-side code should never rely on this, and must accept the same set of formats. Consequently, this feature defaults off at this time. (Note that this definition of leniency does not match the java.text.DateFormat definition, which allows out-of-range days of the month.)
Example:
<lenient-date-formats>false</lenient-date-formats>
The <debug-indent-output> element affects how UIX will display its output. When set to "true", output will automatically be "pretty printed". This value is only referred to when UIX is in "debug" mode.
Example:
<debug-indent-output>false</debug-indent-output>
The <debug-flush-on-end-element> element affects whether output should automatically be flushed every time an element ends. This can make debugging easier, as exceptions can be more obviously associated with the location of the problem, but slows performance. whether output should be pretty-printed. This is only used in debug mode, when it defaults to false.
Example:
<debug-flush-on-end-element>true</debug-flush-on-end-element>
The <debug-log-to-console> element affects whether logged information should be sent to the console as well as the standard servlet log. This is only used in debug mode, when it defaults to true.
Example:
<debug-log-to-console>true</debug-log-to-console>
The <debug-log-request-parameters> element affects whether the parameters for each request should be logged. This is only used in debug mode, when it defaults to true.
Example:
<debug-log-request-parameters>true</debug-log-request-parameters>
The <debug-log-request-timing> element affects whether timing information for each request should be logged. This is only used in debug mode, when it defaults to false.
Example:
<debug-log-request-timing>true</debug-log-request-parameters>
The <debug-partial-responses> element is used to enable partial page rendering debugging. Partial page events can be difficult to debug because they are sent through a hidden iframe, which makes it difficult to view the contents of a partial page response. When <debug-partial-responses> is set to "true", the iframe is displayed at the top of the page, which makes it possible to see the content that is returned for a particular partial page event. This value is only referred to when UIX is in "debug" mode.
Example:
<debug-partial-responses>true</debug-partial-responses>
The <ui-extensions> element allows the automatic registration
of both UIExtension implementations and template libraries. It
contains a series of <extension-class> elements followed by a
series of <template-library> elements. These in turn define
UIExtension implementations and .uit template libraries
that should be made available without forcing clients to explicitly
register the libraries. A quick word of caution: template libraries
loaded here only get loaded once. If you need to change those
libraries, you'll need to restart your UIX application before those
changes are applied. So you'll only want to use this convenience once
you're fairly sure your templates are ready for prime time. For
more information about extensions, see Extending
UIX, and for more information about templates, see
UIX Includes and Templating
Example:
<ui-extensions> <extension-class>oracle.cabo.data.jbo.ui.JboUIExtension</extension-class> <template-library>templates/firstLibrary.uit</template-library> <template-library>templates/secondLibrary.uit</template-library> </ui-extensions>
The <disable-installables-versioning> element controls whether version identifiers are included in UIX installable resource file names. UIX installable resource files such as JavaScript libraries and style sheets may be modified between UIX releases. In order to ensure that browsers pick up the latest versions of these files after upgrading to a new version of UIX, UIX automatically inserts version identifiers in the names of any files which may have changed. Clients can disable this feature by setting the <disable-installables-versioning> to true. However, clients that disable UIX installable file versioning are encouraged to use some other mechanism (such as changing the base URI for the installable files or for the entire web application) to ensure that browsers pick up new versions of these files when upgrading UIX.
Example:
<disable-installables-versioning>true</disable-installables-versioning>
UIX offers several features that can be turned on while debugging, but should not be used when deploying an application (unless you need to debug problems on a deployed application). To turn on "debug mode" in UIX, set the "debug" attribute of <application-configuration> to "true":
Example:
<application-configuration debug="true"> <debug-indent-output>true</debug-indent-output> </application-configuration>
All the elements whose name starts with "debug-" are considered debug-mode-only settings, and will be ignored unless debugging is explicitly turned on. This lets developers pick a set of debugging features and rapidly turn them on and off.
In addition to features that can be individually turned on and off, UIX will enable some functionality automatically when in debug mode:
The <default-configuration> and
<configuration> elements support several children.
The order of these children does not matter, but if you include a
<default-configuration>, it must come before all
<configuration> elements.
A configuration file can set any of seven different UIX resource directories; these directories are listed and described above in UIX Resource Files, and the use of these elements is described below in Modifying UIX Resource Locations.
The look-and-feel element defines the name of the preferred look-and-feel.
Example:
<look-and-feel>blaf</look-and-feel>
The style-sheet-name element defines the name of the XSS stylesheet that should be used. This style sheet will be searched for in the STYLES_DIRECTORY. For more information on XSS, see the Customization chapter.
Example:
<style-sheet-name>blaf.xss</style-sheet-name>
The accessibility-mode element defines what level of accessibility support should be generated. Acceptable values are "default" (the default, of course), "inaccessible", which turns off accessibility features but improves page size, and "screenReader", which enhances accessibility to optimize usability with screen readers (but may degrade appearance in standard browsers). For more information about UIX accessibility, see the Accessibility chapter.
Example:
<accessibility-mode>inaccessible</accessibility-mode>
The image-servlet-url element contains the URL to a UIX ImageServlet server. This server will be used for all dynamic generation of images (instead of attempting to generate images locally). For more information on the ImageServlet, see the X Server Configuration for Image Generation chapter.
Example:
<image-servlet-url>http://www.example.org/uix/ImageServlet<image-servlet-url/>
The headless element defines whether headless rendering should be used. When set to "true", UIX will not attempt to dynamically generate images. This can be used to prevent UIX from attempting to connect to an X Server to generate images on a UNIX platform, though a much better alternative is upgrading to JDK 1.4 and avoiding the issue altogether. For more information on dynamic image generation, see the Image Generation chapter.
Example:
<headless>false<headless/>
The disable-content-compression element defines whether UIX should attempt to compress output by, for example, substituting shortened style names. (This does not refer to gzip'ing the output.) This feature is on by default, but it can make debugging more difficult.
Example:
<disable-content-compression>false<disable-content-compression/>
The help-provider element allows configuration of a help provider. The only supported syntax at this time is a contained <ohw-servlet-url> element. The ohw-servlet-url must contain an URL that points to an installation of Oracle Help for the Web (OHW). Once you've set this property, all uiXML and UIX Java pages have access to two data providers - "ui:helpTopics" and "ui:helpSystem" - that make adding context-sensitive help incredibly easy.
Example:
<help-provider> <ohw-servlet-url>http://www.example.org:8888/ohw</ohw-servlet-url> <help-provider/> <!-- Then, in a uiXML page: --> <link text="Show me some help on topic 'Foo'" data:destination="Foo@ui:helpTopics"/>
UIX includes built-in translations to many languages. However, this can lead to some strange results if your application doesn't support quite as many languages. Users may see content provided by your application in one language but content provided directly by UIX in another! The <supported-locales> element lets you notify UIX exactly which locales are supported.
<supported-locales> always starts with a single <default-locale> element. The <default-locale> element contains an ISO locale defintion (e.g, "en", "ja-JP"). This locale will be used if the locale requested by the user does not match any supported locale. After the default is specified, you may optionally include any number of <supported-locale> elements.
Example:
<supported-locales> <default-locale>en</default-locale> <supported-locale>fr</default-locale> <supported-locale>fr-CA</default-locale> <supported-locale>zh-CN</default-locale> <supported-locale>zh-TW</default-locale> <supported-locales/>
Configuration
Applications may use the default configuration by simply not
specifying a Configuration instance at render time.
Alternatively, an application may use a single application-specific
Configuration instance for all page renders, or it may
choose from a small number of instances on a per-render basis. For
example, a different Configuration instance may be used
depending on the target content type (HTML vs. WML) or to provide
custom configurations for different customers in a hosted application
environment.
When using the UIX Controller, a
Configuration can be specified for each request by
overriding the UIXPageBroker.getConfigurationName method.
protected String getConfigurationName(
BajaContext context,
Page page)
{
if (_doIWantMyOtherConfig(...))
return "MyOtherConfig";
return "MyConfig";
}
For developers not using the UIX Controller,
once the Configuration instance has been configured and
registered - either in uix-config.xml or in Java , it can be used
at render time by calling setConfiguration() on the UIX
Components RenderingContext. UIX Components's
BaseRenderingContext provides two overloads of
setConfiguration(): one which takes the
Configuration instance, and another which takes the
Configuration name.
ConfigurationImpl Instances
Applications which need to override the default configuration values
from Java can do so by creating their own
ConfigurationImpl instances. Creating a configuration
involves a three step process:
ConfigurationImpl instance
These steps are performed one time only. The following
example demonstrates how to create and register application-specific
ConfigurationImpl instance.
// Create the ConfigurationImpl instance, specifying a unique name
ConfigurationImpl config = new ConfigurationImpl("iProductConfig");
// Configure the instance with application-specific values
config.putRelativeURI(Configuration.BASE_DIRECTORY, "/iProduct/cabo/");
ServletContext context = _getAServletContext();
// Register the instance
config.register(context);
Every ConfigurationImpl instance must have a unique name
and must be registered by calling the
Configuration.register(ServletContext) method. (UIX also
supports registering configurations globally with a
register() method, but this is deprecated.) These
requirements are necessary to allow configuration settings to survive
round trips to and from the browser when UIX's private JSPs are used.
Although the default location of the UIX resource files protects against name collisions with resource files from other applications, it may be useful to move the UIX resources to some other location altogether. For example, in environments where multiple UIX applications may be installed, it may be useful for each application to have its own copy of the UIX resources. That way, if one application upgrades to a new version of UIX, the UIX resource files used by other applications would not be affected. (This is particularly important for applications which are not partitioned by some other means, for example, applications which are not installed into their own Servlet context.)
The simplest way to modify the UIX resource directory locations is to
use the ConfigurationImpl.putRelativeURI() method or
<context-uri> XML element. This method takes the key constant
of the directory to move, and the new relative URL for the directory.
The following code demonstrates how to move a single resource
directory.
<!-- in XML -->
<jsps-directory>
<context-uri>/iProduct/cabo/jsps/</context-uri>
<jsps-directory>
// In Java:
config.putRelativeURI(Configuration.JSPS_DIRECTORY, "/iProduct/cabo/jsps/");
As a result of this change, UIX Components will generate URLs of the form "<context path>/iProduct/cabo/jsps/" when referring to the UIX Components JSP files. The application is required to have the UIX Components JSPs installed in the corresponding directory on the file system.
The UIX resource directory structure is hierarchical. Changing the location of a parent directory also causes the location of child directories to be moved. For example, the following code changes both the IMAGES_DIRECTORY and the child IMAGES_CACHE_DIRECTORY.
<!-- in XML: -->
<images-directory>
<context-uri>/iProduct/images/</context-uri>
</images-directory>
// In Java:
config.putRelativeURI(Configuration.IMAGES_DIRECTORY, "/iProduct/images/");
As a result, the UIX Components images should be installed in the directory corresponding to "/iProduct/images/". If the IMAGES_CACHE_DIRECTORY is not explicitly specified, UIX Dynamic Images-generated images are created in the the subdirectory corresponding to "/iProduct/images/cache".
Similarly, all of the UIX resource directories can be moved with a
single call to putRelativeURI() by modifying the
BASE_DIRECTORY value (or using the <base-directory>
element).
All of the previous examples make use of relative URLs, which are
resolved relative to the context path of the Servlet. An alternate
approach is to use ConfigurationImpl.putFullURIAndPath(),
or both of the <full-uri> and <full-path> elements to
specify absolute locations. Absolute locations can be useful for
sharing UIX resources across machines or for offloading work to other
web servers. For example, the following sample demonstrates how to
configure UIX to allow the images to be served by a secondary web
server.
<!-- in XML -->
<images-directory>
<full-path>/net/images/private/httpd/htdocs/cabo/images/</full-path>
<full-uri>http://images.example.com/cabo/images/</full-uri>
</images-directory>
// In Java:
// The full URI to the images directory on the image server
String fullURI = "http://images.example.com/cabo/images/";
// The full file system path to the auto-mounted images directory
String fullPath = "/net/images/private/httpd/htdocs/cabo/images/";
config.putFullURIAndPath(config.IMAGES_DIRECTORY, fullURI, fullPath);
Using this configuration, all URLs refering to UIX Components images will start with the URL "http://images.example.com/cabo/images/", and thus will be served by the web server at images.example.com. Offloading the work of serving up image files to a second web server reduces the amount of work that needs to be done by the primary server, and can result in improved response times. However, keep in mind that longer URLs can result in larger page sizes, as the full URL must be generated for each image referenced by UIX Components.
Applications should never use hardcoded absolute file system paths, as the actual paths may vary from machine to machine. File system paths should be configurable at deployment time. This can be achieved by allowing the paths to be specified as part of the installation process. Or, full paths can be retrieved from a configuration file (like uix-config.xml) or via Servlet initialization parameters.
Another case in which a custom configuration with full URLs/paths may be necessary is when the application's JSP files and the UIX resources are located in a aliased directory on an Apache web server. Apache allows URLs to be aliased to directories outside of the web server's document root. For example, the following entry in the Apache httpd.conf configuration file creates an alias for the URL "/HTML/".
Alias /HTML/ "/private/html/"As a result of this alias, any URLs starting with "/HTML/" will be translated to paths under the "/private/html/" directory. In order to move the UIX resources into the aliased directory, under "/private/html/cabo", the following configuration should be sufficient:
<!-- In XML: -->
<base-directory>
<context-uri>/HTML/cabo/</context-uri>
</base-directory>
// In Java:
config.putRelativeURI(Configuration.BASE_DIRECTORY, "/HTML/cabo/");
In the case where "/HTML/" is not aliased, this configuration will work correctly. However, when "/HTML/" is aliased as described above, this configuration does not produce the desired results. Apache's aliasing mechanism affects the way file system paths are reported by the servlet engine. So, although any HTML generated by UIX Components will contain the correct URLs, starting with "/HTML/cabo/", images and style sheets which are dynamically generated by UIX are not created in the correct locations on the file system. For example, in this particular case, the IMAGES_CACHE_DIRECTORY, which should be created at "/private/html/cabo/images/cache", is actually created at "/private/html/HTML/cabo/images/cache". The end result is that the URLs for generated images and style sheets do not match the locations in the aliased directory, and broken images and missing styles result.
This problem can be avoided by configuring UIX with the actual
full path of the aliased UIX resource location. The following
call to putFullURIAndPath() shows the required configuration
for this particular case.
<!-- in XML -->
<base-directory>
<full-uri>/HTML/cabo/>/full-uri>
<full-path>/private/html/cabo/</full-path>
</base-directory>
// In Java:
config.putFullURIAndPath(Configuration.BASE_DIRECTORY,
"/HTML/cabo/",
"/private/html/cabo/");
When using this full URL configuration instead of the relative URL
configuration proposed above, UIX will correctly place dynamically
generated resources in the aliased directory under "/private/html/cabo/".
Of course, the full path "/private/html/cabo/" should not be hardcoded,
as the actual path may vary from machine to machine. Instead, the
full path of the aliased directory can be derived dynamically using the
Servlet API's ServletContext.getRealPath().
getRealPath() translates URLs to file system paths.
The following code, when called from a JSP in the aliased "/private/html/"
directory, will produce the correct configuration:
// The call to getRealPath("/") will return the root directory of the
// alias, which is "/private/html".
String realPath = servletContext.getRealPath("/");
config.putFullURIAndPath(Configuration.BASE_DIRECTORY,
"/HTML/cabo/",
realPath + "/cabo/");