Java Desktop System Configuration Manager Release 1.1 Developer Guide

Chapter 2 Templates

Configuration Manager templates provide information about the location of every configuration setting in the configuration repository. Templates also provide information about their visual representation in the GUI of the Configuration Manager. Templates are XML files that conform to a document type definition (DTD) file.


Tip –

If you are not familiar with XML, the following link provides a short introduction:http://java.sun.com/webservices/docs/1.0/tutorial/doc/IntroXML.html


Using XML allows you to create definitions for managing configurations settings that are independent of the GUI rendering engine, the operating system, and the programming language. The GUI is rendered based on the semantic dependencies of the elements specified in the template. Due to its generality, the Configuration Manager template format does not provide solutions for every possible GUI design request. For instance, exact positioning on the screen is not supported.

This chapter contains information about the typical development cycle for templates. Beginning with a currently existing configuration dialog of a desktop application, you will learn how to create a simple template for that dialog. You will also learn how to make that file available to the Configuration Manager, so that the file is displayed in the Content Area.

The “Hello world!” Template

ProcedureCreating the “Hello world!” template

Before You Begin

Assume that you want to make the proxy configuration settings of StarOffice available to the Configuration Manager.

Options-Internet-Proxy

The following template provides a first implementation of the GUI:


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE apt:template SYSTEM "policytemplate.dtd">
<apt:template>
  <category apt:name="StarOffice" apt:label="StarOffice">
    <category apt:name="Internet" apt:label="Internet">
      <page apt:name="Proxy" apt:label="Proxy">
        <section apt:name="Settings" apt:label="Settings">
          <property apt:name="ProxyServer" apt:label="Proxy Server"
                    apt:dataPath="org.openoffice.Inet/Settings/ooInetProxyType"
                    oor:type="xs:int">
            <visual apt:type="radioButtons"/>
            <constraints>
              <enumeration oor:value="0" apt:label="None"/>
              <enumeration oor:value="2" apt:label="Manual"/>
            </constraints>
          </property>
          <property apt:name="HTTPProxy" apt:label="HTTP Proxy"
                    apt:dataPath="org.openoffice.Inet/Settings/ooInetHTTPProxyName"
                    oor:type="xs:string"/>
          <property apt:name="HTTPPort" apt:label="HTTP Port"
                    apt:dataPath="org.openoffice.Inet/Settings/ooInetHTTPProxyPort"
                    oor:type="xs:int"/>
          <property apt:name="FTPProxy" apt:label="FTP Proxy"
                    apt:dataPath="org.openoffice.Inet/Settings/ooInetFTPProxyName"
                    oor:type="xs:string"/>
          <property apt:name="FTPPort" apt:label="FTP Port"
                    apt:dataPath="org.openoffice.Inet/Settings/ooInetFTPProxyPort"
                    oor:type="xs:int"/>
          <property apt:name="NoProxyFor" apt:label="No Proxy For"
                    apt:dataPath="org.openoffice.Inet/Settings/ooInetNoProxy"
                    oor:type="xs:string"/>
        </section>
      </page>
    </category>
  </category>
</apt:template>

The following steps are necessary to announce the new template to the Configuration Manager:

Steps
  1. Login as root to the machine on which you installed the Configuration Manager.

  2. Create a directory that is called HelloWorld/templates/StarOffice/Internet/Proxy under/usr/share/webconsole/apoc/packages.

  3. Create a file called proxy.xml with the XML template content that was listed previously. Copy the file to the Proxy directory.

  4. Grant the user “noaccess” read/execute permission to the Proxy directory.

  5. Grant the user "noaccess" read access to the proxy.xml file.

  6. Execute /usr/sbin/smreg add -a /usr/share/webconsole/apoc.

  7. Restart the webserver with the /usr/sbin/smcwebserver restart command.

    After you log in to the Configuration Manager, you should see a new top-level category that is called "StarOffice". Browsing down that category displays the "Proxy" page that you defined with the template that you created.

    Figure 2–1 Proxy page

    Proxy page

Explaining the “Hello world!” Template

The first two lines of the template are initial XML definitions. The third line contains the root element of the template called apt:template, which encloses the whole definition of the policy made in a template file.

The next four lines contain the main template structure elements. By nesting apt:category elements, you create the nodes of the configuration policy tree. The configuration policy tree represents the visual hierarchy of the policies in the GUI of the Configuration Manager (see Trees). If you specify an apt:name attribute, the attribute is used to uniquely designate that element. The apt:label attribute specifies the displayed text as a category in the GUI. If you do not specify the apt:label attribute, the displayed text is defined by the apt:name attribute. Therefore, always specify an apt:label element, because this element is used for localization. See Localization.

Every apt:category element must contain one or more apt:category elements or an apt:page element. The apt:page element represents a leaf in the configuration policy tree. The “Proxy” page that was shown previously is an example of a leaf. The Configuration Manager renders a page as a single HTML page that has to be divided in at least one apt:section. An apt:section element renders all its child elements in a table with a table heading. Using more than one section enables you to group settings on one page.

The apt:section element contains apt:property elements, which represent the configuration settings. The "Hello, world!" template contains six properties: ProxyServer, HTTPProxy, HTTPPort, FTPProxy, FTPPort, and NoProxyFor. Every property contains an apt:dataPath attribute. This attribute is required and specifies the data location in the configuration tree. The configuration tree in turn represents the hierarchy of the configuration settings as it is stored in the configuration repository. See Trees for more information.

The oor:type attribute defines the data type of the configuration setting in the configuration repository. ProxyServer, HTTPPort, and FTPPort are of type xs:int, the other properties are of type xs:string. Integer and string types are displayed as edit fields by default.

The visual element is used to instruct the Configuration Manager how to display the property. Without specifying this element, the property ProxyServer would have been rendered using an edit field instead of a radio button group.


Tip –

The GUI of the Configuration Manager deviates from the original StarOffice GUI by rendering the two possible integer values as a radio button group instead of using a drop-down list. For visualizing a dual value, improved usability is achieved using radio buttons instead of a drop-down list. An example, for instance, is one click compared with two clicks for changing a value.


The constraints element, in combination with the enumeration sub-element, is used to specify the number of radio buttons rendered and the integer values stored in the back end, depending on which radio button is selected. The apt:label attribute specifies the string rendered on the GUI for every radio button.

Localization

It is important to localize all strings that are defined in a template. Localized strings are retrieved from resource files. The resImport sub-element of the apt:template element is used to bind one or more resource files to a template. You need to specify the fully qualified path to the resource and its base name, for example:

<apt:template>
<resImport
  apt:packagePath="com.sun.star.apoc.policies.resource.staroffice"/>

The resource key to be used is defined by providing the name of the key as value of the apt:label attribute, e.g.

<property apt:name="HTTPProxy" apt:label="SO.internet.proxy.name"
          apt:dataPath="org.openoffice.Inet/Settings/ooInetHTTPProxyName"
          oor:type="xs:string">

The Configuration Manager searches every resource file bound to a template for the key specified in the apt:label attribute first. If no key is found, the value of the apt:label attribute is displayed. If a key is found, the corresponding value is retrieved from the resource file and is displayed.

The resource file from which the string is retrieved is determined in a similar way to the mechanism defined for Java: the package path specified in the resImport element and the languages selected in the web browser determine the selected resource file. For example, if en_US is the language for web pages selected in the browser, and the package path specified in the resImport element is com.sun.star.apoc.policies.resource.staroffice, the Configuration Manager searches the following files in the given order for the resource key:

./res/com/sun/star/apoc/policies/resource/staroffice_en_US.properties

./res/com/sun/star/apoc/policies/resource/staroffice_en.properties

./res/com/sun/star/apoc/policies/resource/staroffice.properties

The Configuration Manager searches the files in the local policy package first (see The Policy Package Format). If they are not found, all other packages are searched. This enables strings that are already localized in other packages to be reused, especially for category names.

See the API specification of the Java ResourceBundle for more details on resource recovery.


Tip –

All applications of the Java Web Console determine the language during the login. To force any application to use a new language, you must log out. Then log in again after you have changed the language for web pages in your browser.


The online help should also be localized. The Configuration Manager chooses the HTML file according to the same rules that are applied to the resource files, except that only the local policy package is searched for the help file. For example, if you specify /StarOffice/Internet/Proxy as the path to the HTML file, and en_US in your browser, the Configuration Manager displays the online help file ./web/StarOffice/Internet/Proxy_en_US.html.

The Policy Package Format

Templates are embedded into a deployment container, which is similar to a "package" in the JavaTM programming language. A package can also contain optional files, such as resource files for GUI localization, HTML files for online help, and arbitrary support files.

The Configuration Manager uses a special directory and a file name format to access the templates and all necessary optional files. This directory and file name structure is called the policy package format.

All policy packages are located in a unique subdirectory below the /usr/share/webconsole/apoc/packages directory. For the "Hello, world!" example, HelloWorld was chosen, resulting in a /usr/share/webconsole/apoc/packages/HelloWorld directory.


Tip –

Use the product name and product version of the software for which you are installing the package. This ensures a unique package directory. For instance, HelloWorld3.1 is a better choice than HelloWorld.


Below the specific package directory, which should not be confused with the packages directory, the following subdirectories are allowed:

templates 

The templates subdirectory must contain all templates of the policy package. Files that have the postfix .xml are considered to be templates. The name of the file must correlate with the value of the apt:name attribute of the page element. Templates can be organized in any way, although they should be located in the same directory hierarchy, as specified by their category hierarchy.

classes 

The classes subdirectory must contain all class files of the policy package. Files that have the postfix .class are considered to be Java class files. The name of the file has to correlate with the name of the class defined in that file. The files have to be located in the same directory hierarchy as specified by their package hierarchy.

web 

The web subdirectory must contain all HTML help files of the policy package and must contain images referenced by the policy package. Files that have the postfix .html are considered to be HTML files. Correlate the name of the HTML file with the name of the template using the HTML file. Locate HTML files in the same directory hierarchy as the template using the HTML file.

res 

The res subdirectory must contain all resource files of the policy package. Files that have the postfix .properties are considered to be Java-compliant resource files. You can correlate the names and paths of the resource file with the names and paths of the template files that use them. You can also specify one directory hierarchy containing one resource file for all templates.

lib 

The lib subdirectory must contain all library files of the policy package. Files that have the postfix .jar are considered to be libraries. Libraries are automatically loaded by the Configuration Manager's class loader. Their content is accessed by using the root directory in the jar file as the root directory for absolute paths. The typical use for library files is to act as a container for class or resource files , and for directories that are normally located in the classes and res directories.

Other file types have no special meaning to the Configuration Manager. Nevertheless, the files types can be placed in the classes or web directories, if they are needed by class or HTML files.

To further illustrate the package format, Figure 2–2 shows a mature HelloWorld package:

Figure 2–2 HelloWorld Package

HelloWorld Package

The deployment of packages is completely up to the developer of the package, as long as you follow the rules defined previously in this chapter. You can provide a collection of files with instructions about how to copy the files to the correct locations, or you can provide a zip file, or you can use the deployment mechanisms provided by the operating systems, such as .pkg files for SolarisTM or .rpm files for Linux. The last method is recommended, as the enhanced means for maintaining and removing software offered by the corresponding operating system provide better support for the end user.