-
Notifications
You must be signed in to change notification settings - Fork 18
Configuration Properties
Mark Reeves edited this page Jan 4, 2018
·
19 revisions
The WComponents library is configured using the Apache Configuration API. This allows developers to programmatically integrate the WComponents configuration with whatever mechanism is used to configure their applications.
- The default WComponents configuration
- Integrating WComponents configuration with your application's using the Config class
- Testing
- Example properties file
- Factory parameters
- Complete list of configuration options
The default configuration provided with the WComponents library is enough to run a simple application without any additional debugging.
Direct use of the internal configuration mechanism is discouraged as the implementation may change without notice. This configuration mechanism does prove useful during development though as it provides a quick way to test WComponents configuration options.
The internal configuration searches for property files in the working directory and the classpath (including within jars). The property files are loaded in 3 stages since loading order is classpath dependent:
-
WComponents Internal properties
Internal properties are first loaded from the "wcomponents.properties" files. Applications should not place any WComponents properties in files with this name as they may be overridden by the internal properties depending on the loading order.
-
Application properties
The next set of properties files which are loaded are application properties from files named "wcomponents-app.properties". Applications wishing to configure WComponents using the internal configuration mechanism should place their WComponents properties in these files.
-
Developer/environment properties
The last properties which are loaded are local/developer properties from files named "local_app.properties". Only environment-specific properties should be placed in these files; for example port numbers or LDE properties.
The util.Config class uses the java ServiceLoader API to look for additional configuration on instantiation. In order to add your own custom configuration class to the WComponents Config, you will need to do the following:
import com.github.bordertech.wcomponents.util.ConfigurationLoader;
public class MyConfigBridge implements ConfigurationLoader
{
/** {@inheritDoc}. */
public Configuration getConfiguration()
{
return MyConfig.getInstance();
}
}The JAR file must contain the file META-INF/services/com.github.bordertech.wcomponents.util.ConfigurationLoader with the following content:
com.mypackage.MyConfigBridge
If you are using Maven to build your project, create the service file at src/main/resources/META-INF/services/ and it will be correctly included in the JAR.
The auto-service project https://github.com/google/auto/tree/master/service has an annotation to auto-generate the correct file.
The following methods in the Config class are useful for unit testing:
-
reset()- will restore the default WComponents internal configuration. -
copyConfiguration(Configuration)- will perform a deep-copy of the given configuration. This is useful when you need to create a backup copy of the current configuration before modifying it for a particular test.
Configuration parameters can be read from the current configuration as follows:
Config.getInstance().getString("someParameter");The WComponents distribution includes a file named "example_local_app.properties". This file contains example configuration settings which are useful for developers. It can be easily modified and for use with the default internal configuration during development .
The WComponents library uses a generic Factory class to instantiate implementations of different interfaces. The factory uses the configuration to map interfaces to implementations.
The factory parameters keys are all prefixed with bordertech.wcomponents.factory.impl., with the rest of the key being the fully qualified name of the interface. The value of the parameter must be the fully qualified name of the implementing class. For example, to use the "com.myapp.MyLookupTable" implementation for the com.github.bordertech.wcomponents.util.LookupTable interface, you would set:
bordertech.wcomponents.factory.impl.com.github.bordertech.wcomponents.util.LookupTable = com.myapp.MyLookupTable
The complete list of configuration options can be found in the class ConfigurationProperties in wcomponents-core.
| Parameter key | Description | Default value |
|---|---|---|
| bordertech.wcomponents.servlet.support.path | The URL relative path to the WServlet which provides support services in a portlet environment. | null |
| bordertech.wcomponents.theme.content.path | The URL relative path to the web content for the theme. This is only necessary when deploying themes in a web-app separate to those provided by WComponents. eg bordertech.wcomponents.theme.content.path=/themes/html/${bordertech.wcomponents.theme.name}. If the path is not set or blank, then the theme resources are loaded via the application servlet. To use the application servlet, the servlet mapping must include a wildcard (eg /myapp/*). |
/theme/ |
| bordertech.wcomponents.theme.name | This parameter controls which theme is used. | wcomponents-theme |
| bordertech.wcomponents.application.icon.url | The URL for the application icon. | null |
| Parameter key | Description | Default value |
|---|---|---|
| bordertech.wcomponents.i18n.baseName | This configuration parameter is used to set the resource bundle base name for applications which have been internationalised. | null |
| bordertech.wcomponents.integrity.terminate.mode | This flag controls whether the integrity issues will result in an exception ('true') or logged warning ('false'). See the Integrity class for more detail. | false |
| bordertech.wcomponents.logout.url | The logout URL controls where the user's browser will be directed to when the Request.logout() method is called. | null |
| bordertech.wcomponents.servlet.handleErrorWithFatalErrorPageFactory | This flag controls whether the error page factory is used to display error pages. A value of 'false' indicates that the default error handling should be used, and 'true' will delegate the error handling to an instance of the FatalErrorPageFactory. | false |
| com.github.bordertech.wcomponents.servlet.WServlet.handleErrorWithFatalErrorPageFactory | Deprecated old format of parameter bordertech.wcomponents.servlet.handleErrorWithFatalErrorPageFactory | false |
| bordertech.wcomponents.servlet.subsessions.enabled | This flag controls whether to allow users to have multiple sub-sessions per user session. Some browsers share browser session cookies between windows and tabs, which leads to multiple windows/tabs operating off the same HTTP session instance on the server. Turning on this option lets WComponents try to differentiate between different windows/tabs and offer each one a different "sub-session". NOTE: This feature should be considered experimental as it has not been thoroughly tested. NOTE: This feature will not work in a Portal environment. | false |
| bordertech.wcomponents.stickyFocus | This flag controls whether keyboard focus should be remembered between requests. This should be set to false in a portlet environment, otherwise multiple portlets will be trying to set focus. | false |
| bordertech.wcomponents.terminateSessionOnError | This flag controls whether the user session should be terminated if there is an unhandled error. Setting the value to 'true' will invalidate the user session on error. | false |
| bordertech.wcomponents.UIManager.renderer.* | These parameters can be used to override the default renderers for components. For example, an alternative layout for a "com.foo.Bar" component could be configured by: borderTech.wcomponents.UIManager.renderer.com.foo.Bar = com.foo.x.BarRenderer
|
n/a |
| bordertech.wcomponents.velocity.macroLibrary | This setting allows developers to create velocity macro libraries. The value should be the path(s) to the library .vm file(s). | null |
| bordertech.wcomponents.wrongStep.redirect.url | The URL to redirect to when a step error occurs. The default behaviour is to ignore the request and notify the application of the step error. Setting a URL will cause the user to be redirected to the provided URL. | null |
| bordertech.wcomponents.factory.impl.com.github.wcomponents.util.LookupTable | Controls which lookup table is used. This must be set to the fully qualified name of a class which implements the LookupTable interface. | null |
| bordertech.wcomponents.factory.impl.com.github.wcomponents.FatalErrorPageFactory | Controls which FatalErrorFactory is used. This must be set to the fully qualified name of a class which implements the FatalErrorPageFactory interface. | The default error factory |
| bordertech.wcomponents.timoutWarning.timeoutPeriod | Sets the default TIMEOUT interval, being the time in seconds before the application session will time out so that the user may be warned when this is imminent. The default of 0 uses the http session timeout. | 0 |
| bordertech.wcomponents.timoutWarning.warningPeriod | Sets the default WARNING interval, being the time in seconds before a timeout period is reached in which the user is warned that their session is about to timeout. | 300 |
| Parameter key | Description | Default value |
|---|---|---|
| bordertech.wcomponents.dataListCaching.enabled | Globally enables/disables client-side caching of data lists. Set this parameter to 'true' to enable client-side caching. | false |
| bordertech.wcomponents.velocity.cacheTemplates.enabled | This flag controls whether velocity templates are cached. Setting the flag to 'false' disables template caching. | true |
| bordertech.wcomponents.whitespaceFilter.enabled | The white space filter removes HTML comments and redundant white space from the XML output. Setting this parameter to 'false' will disable the filter. This is useful for development, as it makes the XML page source easier to read. | true |
| bordertech.wcomponents.check.duplicate.ids.enabled | This flag controls if component ids should be checked for duplicates. As verifying requires extra resources and memory, this can be disabled if required. Projects are encouraged to at least have this set true in non-production environments. | true |
| Parameter key | Description | Default value |
|---|---|---|
| bordertech.wcomponents.debug.enabled | Set this to 'true' to enable debugging features in WComponents. | false |
| bordertech.wcomponents.debug.clientSide.enabled | Set this parameter to 'true' in order to visualise the structural breakdown of the application and/or to undertake client-side debugging. | false |
| bordertech.wcomponents.debug.validateXML.enabled | Set this to 'true' to enable validation of XML output. The debug flag must also be true. | false |
| bordertech.wcomponents.developer.clusterEmulation.enabled | Simulates what would happen if the UIContext was serialized due to clustering of servers. The UIContext is serialized/deserialized after each request if this parameter is set to 'true'. | false |
| bordertech.wcomponents.developer.errorHandling.enabled | Set this to true to enable "developer friendly" errors (e.g. inclusion of stack-traces). This should not be turned on in production environments. | false |
| bordertech.wcomponents.developer.UIContextDump.enabled | Setting this flag to true will dump the UIContext contents to the log after each render. This can be useful when trying to reduce application session memory usage. | false |
| bordertech.wcomponents.test.selenium.browsers | If using the MultiBrowserRunner to run Selenium tests in multiple browsers, this parameter must be set to the browsers to use. | null |
| bordertech.wcomponents.test.selenium.runParallel | Setting this flag to 'true' will enable Selenium tests using different browsers to run in parallel. | false |
| bordertech.wcomponents.velocity.debugLayout | If this flag is set to 'true', markers will be added to the XML output to indicate the start and end of velocity templates. | false |
| bordertech.wcomponents.velocity.fileTemplatesDir | If this setting is non-null, velocity templates will be loaded from the given directory. This is good for developers, who can point into their source tree directly. Templates will not be cached in this case. | null |
| Parameter key | Description | Default value |
|---|---|---|
| bordertech.wcomponents.lde.component.to.launch | Set this to the fully qualified name of the WComponents class which you want to run in the LDE. | null |
| bordertech.wcomponents.lde.devToolkit.enabled | Setting this flag to 'true' adds a developer toolkit to the UI. | false |
| bordertech.wcomponents.lde.server.port | Use this parameter to change the port on which the LDE is run. You may wish to use different port numbers for different projects, so that multiple LDE instances can be run simultaneously. | 8080 |
| bordertech.wcomponents.lde.server.realm.file | If you are using security constraints in your web.xml, you will need a Jetty HashUserRealm properties file. This parameter should be set to the path of the properties file. The format for each line in the properties file should be: <username>:<password>[,<rolename> ...] For example: steve:stevespassword,admin,user | null |
| bordertech.wcomponents.lde.session.inactive.interval | The LDE session timeout interval, in seconds. If this is set to zero, the default Jetty session timeout is used. | 0 |
| bordertech.wcomponents.lde.session.loadPersisted | If set to 'true', new sessions will be loaded from a previously serialized session. This can be set independently from the "persist" parameter, to take a snapshot of an application and always start in the same state. The usual long-term serialization restrictions still apply, e.g. changing classes' serial version ids. | false |
| bordertech.wcomponents.lde.session.persist | If set to 'true', the session will be serialized after each request. | false |
| bordertech.wcomponents.lde.show.memory.profile | Sets this flag to 'true' display the memory profile in the LDE. | false |
| bordertech.wcomponents.lde.shutdown.enabled | Setting this to 'true' enables remote shutdown of the LDE, and is used by the LDE shut down any other instance when a new LDE is started. | false |
| bordertech.wcomponents.lde.theme.dir | This parameter allows developers to configure the LDE to use an external theme. It should be set to the filesystem directory containing the theme. | null |
| bordertech.wcomponents.lde.webdocs.dir | This parameter allows the developer to configure the LDE to use a different set of servlets (defined in a web.xml) and additional static web content. | null |
| bordertech.wcomponents.lde.resource.dir | This parameter allows the developer to configure the LDE to load additional static web content. | null |
| Parameter key | Description | Default value |
|---|---|---|
| bordertech.wcomponents.test.selenium.pageReadyTimeout | Use this parameter to change the maximum number of seconds Selenium will wait for the WComponent page to be ready, including Ajax. | 10 |
| bordertech.wcomponents.test.selenium.pageReadyPollInterval | Use this parameter to change the number of milliseconds between poll attempts for the 'page ready' check | 50 |
| bordertech.wcomponents.test.selenium.implicitWait | Use this parameter to change the the number of seconds to wait for a component to appear on the page if it was not found. | 5 |
| bordertech.wcomponents.test.selenium.screenWidth | Use this parameter to change the width of the screen in pixels | 1920 |
| bordertech.wcomponents.test.selenium.screenHeight | Use this parameter to change the height of the screen in pixels | 1080 |
| bordertech.wcomponents.test.selenium.driverTypes | Used by the JUnit MultiBrowserRunner to configure which WebDriver types to run the annotate test against. | com.github.bordertech.wcomponents.test.selenium.driver.PhantomJSWebDriverType |
| bordertech.wcomponents.test.selenium.runParallel | Used by the JUnit MultiBrowserRunner to configure whether different WebDriver types should test in parallel | false |
| bordertech.wcomponents.test.selenium.launchServer | Used by the WComponentSeleniumTestCase to determine whether to launch the LDE during start-up. Configurable on a per-test basis by appending the test class name to the end of the parameter, e.g.: bordertech.wcomponents.test.selenium.launchServer.com.site.MyTest = true | false |
| bordertech.wcomponents.test.selenium.serverUrl | Used by the WComponentSeleniumTestCase to configure a non-LDE URL during start-up. Will be ignored if launchServer is set to true. Configurable on a per-test basis by appending the test class name to the end of the parameter, e.g.: bordertech.wcomponents.test.selenium.serverUrl.com.site.MyTest = http://localhost/app | null |
| bordertech.wcomponents.test.selenium.webdriver | Used by ParameterizedWebDriverType to set which WebDriver implementation to use. Configurable on a per-test basis by appending the test class name to the end of the parameter, e.g.: bordertech.wcomponents.test.selenium.webdriver.com.site.MyTest = com.openqa.selenium.phantomjs.PhantomJSDriver | com.openqa.selenium.phantomjs.PhantomJSDriver |
| bordertech.wcomponents.test.selenium.systemProperties | Configures a list of system properties to be set prior to creating the WebDriver. | null |
| bordertech.wcomponents.test.selenium.{0}.capabilities | This parameter allows specific capabilities to be set for each WebDriverType. The parameter {0} is equal to the String returned by WebDriverType.getDriverTypeName() | null |
| Parameter key | Description | Default value |
|---|---|---|
| bordertech.wcomponents.version | The current version of WComponents in use. | n/a |
| bordertech.wcomponents.mimeType.* | These parameters are for file-suffix to mime-type mapping for e.g. serving up static content using the theme servlet. For example, the value of the bordertech.wcomponents.mimeType.css parameter is used to determine the mime-type for CSS files. The value of the parameter bordertech.wcomponents.mimeType.defaultMimeType is used when there is no explicit mapping. |
n/a |
| bordertech.wcomponents.parameters.useSystemProperties | This flag allows system properties to be merged at the end of the loading parameters process. | false |
| bordertech.wcomponents.parameters.dump.console | This flag allows parameters to be dumped to the console after being loaded. | false |
| bordertech.wcomponents.parameters.system.* | Parameters with this prefix will be dumped into the System parameters. Not for general use | n/a |
| bordertech.wcomponents.bean.logic.correct | This flag allows bean containers, with a bean property set, to pass the correct bean value to its child bean components. Defaults to "false" for backward compatibility and is an "opt in". This parameter is deprecated and will be removed in a future release and the correct logic always used. Projects are encouraged to set as true. | false |