XML files and resource bundles

The main tools configuration section, ToolsGeneralConfig, is in the WebSphere Commerce configuration file. It contains many different variables to configure the tools. This file is issued only for system configuration and is not meant for properties specific to any one implementation.

The properties defined here are:


Property	Description
XMLPath	Path to look for XML files.
DTDPath	Path to look for DTD files.
XMLCacheSize	Number of XML files to cache at any given time.
developmentMode	This is either True or False. If this is true, XML files (.xml) and resource bundles (.properties) are reloaded if their timestamps have changed since the last time they were loaded.
resourceBundlePath	If the developmentMode is set to true, this is the path used to locate .properties files. If the developmentMode is false, this is ignored, and the instance class path is used.

For implementation specific properties, there is a configuration file called resources.xml in the commerce/xml/tools/component directory. This file defines the resource bundles and XML files used throughout your code. The resources.xml file for each implementation is defined in the instance.xml file as follows: <resourceConfig file="component/resources.xml"/>

Each file defines a namespace for the elements it defines so that there are no collisions in naming objects. Every element is referred to by the namespace it is located in and by its own name, separated by a period. For example, common.resources. Every resources.xml file has a <resource> element. This element requires a property called nameSpace. The value of this property is some unique name which describes the group of resources you define. In your code, a resource is scoped by the name space. In order to refer to a resource, use the string namespace.resource_name in your code. The following is an example resources.xml file:


<?xml version="1.0" encoding="UTF-8"?>
<!-- This is the configuration file for the common objects that are available in the runtime model -->
<resourceConfig> 
  <resource nameSpace="common"> 
      <!-- resource bundle file mappings --> 
          <resourceBundle name="resources" bundle="com.ibm.commerce.tools.properties.CommonStrings"/>
          <resourceBundle name="WizardTabNames" bundle="com.ibm.commerce.tools.properties.WizardTabNames"/>
      <!-- Resource XML file mappings --> 
          <resourceXML name="currencyMap" file="common/currencyMap.xml" /> 
          <resourceXML name="UIPropertyConfig" file="common/UIProperties.xml" /> 
  </resource> 
</resourceConfig>

NL Enablement

All NL sensitive data is separated into property files (in the form of Java Resource Bundles) to eliminate the JSP and XML files containing NL sensitive data. Based on the locale of the current session (default locale based on the installed language is used if not specified) the utility class will retrieve the appropriate resource bundle to be used in the display file.

Also, special care must be taken encoding NLV characters when posted directly in a URL call. Sometimes NVPs are not encoded correctly and possible data corruption can occur. To avoid this problem, programmers should comply with the following rule.

When setting a URL (if it may contain double-byte characters) always use the top.setContent() method. Do not use window.location.replace() or location.href=myURL. Another advantage of top.setContent() is that it triggers the Tools User Interface Center to display the progress indicator properly. Call the method as follows: top.setContent( String PanelName, String ViewCommand, Boolean addToBreadCrumbTrail, String urlParameter);

For example: var urlPara = new Object(); urlPara.XMLFile = "my.xml"; urlPara.Search = "japanese"; top.setContent("My Link", "MyViewCommand", true, urlPara)

In this way, those URL parameters are submitted to the servlet in a hidden form format.

Resource Bundles

All messages listed in the WebSphere Commerce documentation use the logging and message subsystem. All other text that is not placed in an ECException object and does not need any additional descriptions (field labels, for example) use the resource bundle classes provided by the Tools Framework. To allow for easy modification of fields, these classes access .properties files only. Some of the features provided by these classes are:

When the developmentMode attribute is true, modified .properties files are automatically reloaded.
XML configuration

To create and use a resource bundle:

Create a .property file and place it in the following directory:
- workspace_dir/wc/properties/com/ibm/wcs/tools/component/properties
- WC_eardir/properties/com/ibm/wcs/tools/component/properties
Where component is the name of the component you are using.
Add the following line to commerce/properties/component/resources.xml <resourceBundle name="name" bundle="com.ibm.commerce.tools.properties.filename_with_no_extension" /> Where name is the name you want to use to refer to the bundle throughout your code and filename_with_no_extension is the filename for your .properties file without the .properties extension.
Multiple resource bundle files are allowed to map to one resource bundle handle, as shown in the following example:
```
<resourceBundle name="name">
   <bundle="com.ibm.commerce.tools.properties.common" />
   <bundle="com.ibm.commerce.tools.properties.sample" />
</resourceBundle>
```
If there are duplicate keys, previously defined keys will be overwritten by later ones.

To use a resource string in your code, refer to the steps in XMLParsing. Keep in mind that when developmentMode is set to true, the path where the framework looks for the resource bundles is set by the resourceBundlePath variable in the instance_name .xml file. It is currently set to the commerce/properties and commerce/classes directories.

XML Parsing

The framework contains a set of utility classes to read and write XML files and strings. When reading XML files and strings, these parsers turn the XML data into a hashtable. When writing XML files and strings, these parsers turn a hashtable into the XML file or string. Some of the current features of these utilities are:

Caching
Auto-reload upon modification (only available in development mode)
Manual reload (by calling ResourceDirectory.initializeInstDirectory() method)

To create and use an XML file:

Create an XML file and place it in the following directory:
- WC_installdir/xml/tools/component
- WC_eardir/xml/tools/component
Add the following line to
- WC_installdir/xml/tools/componentnamecomponent/resources.xml
- WC_eardir/xml/tools/componentcomponentname/resources.xml
<XML name="name" file="path name" /> where name is the name you want to use to refer to the XML file throughout your code, path name is the relative path name for your XML file (common/common.xml, for example), and componentname is the name of the component you are using.

Note: In the instance.xml file, the path that the framework searches to find the XML files is set by the XMLPath variable, the number of XML files cached is specified by the XMLCacheSize, and the path the framework searches to find the DTD files is set by the DTDPath variable.

To use an XML file in your code:

Retrieve your XML file with the following command: Hashtable myResource = (Hashtable) com.ibm.commerce.tools.util.ResourceDirectory.lookup(String resourceName) where resourceName is namespace.resource_name.
Use one of the following commands to retrieve required information from the hashtable. Which one you use depends on the type of element required. Refer to the following commands: String resource = (String)myResource.get("resource_key"); Vector resource = (Vector)myResource.get("resource_key"); String resource = (Hashtable)myResource.get("resource_key");
where resource_key is the key used to access the required element in the table.

The other XML utility classes do not need any configuration. They can be used directly. The following table describes these other classes:


Class	Function
XMLStringReader	Turns XML strings into hashtables
XMLFileWriter	Writes a hashtable out to an XML file
XMLUtil.get(Hashtable tree, String path)	Takes an XML hashtable and a path and returns the object at the end of that path. This allows users to retrieve nested elements without having to manually traverse the DOM tree.