Custom Path Variables

From Apache OpenOffice Wiki
Jump to: navigation, search



Syntax

The path substitution service supports the definition and usage of user-defined path variables. The variable names must use this syntax:

 variable ::= "$(" letter { letter | digit } ")"
 letter ::= "A"-"Z"|"a"-"z"
 digit ::= "0"-"9"

The user-defined variables must be defined in the configuration branch org.openoffice.Office.Substitution. Apache OpenOffice employs a rule-based system to evaluate which definition of a user-defined variable is chosen. The following sections describe the different parts of this rule-based system and the configuration settings that are required for defining new path variables.

Environment Values

To bind a specific value to a user-defined path variable, the path substitution service uses environment values. The path substitution service chooses a variable definition based on the values of these environment parameters. The following table describes which parameters can be used:

Environment parameters
Host This value can be a host name or an IP address , depending on the network configuration (DNS server available). A host name is case-insensitive and can also use the asterisk (*) wildcard to represent match zero or more characters.
YPDomain The yellow pages domain or NIS domain. The value is case-insensitive and can use the asterisk (*) wildcard to represent match zero or more characters.
DNSDomain The domain name service. The value is case-insensitive and can use the asterisk (*) wildcard to represent match zero or more characters.
NTDomain Windows NT domain. The value is case-insensitive and can use the asterisk (*) wildcard to represent match zero or more characters.
OS The operating system parameter supports the following values:
  • WINDOWS (all windows versions including Win9x, WinME, and WinXP)
  • UNIX (includes LINUX and SOLARIS)
  • SOLARIS
  • LINUX

Rules

The user can define the mapping of environment parameter values to variable values. Each definition is called a rule and all rules for a particular variable are the rule set. You can only have one environment parameter value for each rule.

The following example rules specify that the user-defined variable called devdoc is bound to the directory s:\develop\documentation if Apache OpenOffice is running under Windows. The second rule binds devdoc to /net/develop/documentation if Apache OpenOffice is running under Solaris.

 Variable name=devdoc
 Environment parameter=OS
 Value=file:///s:/develop/documentation
 
 Variable name=devdoc
 Environment parameter=SOLARIS
 Value=file:///net/develop/documentation

Analyzing User-Defined Rules

Apache OpenOffice uses matching rules to find the active rule inside a provided rule set.

  1. Tries to match with the Host environment parameter. If more than one rule matches - this can be possible if you use the asterisk (*) wildcard character - the first matching rule is applied.
  2. Tries to match with the different Domain parameters. There is no predefined order for the domain parameters - the first matching rule is applied.
  3. Try to match with the OS parameter. The specialized values have a higher priority than generic ones, for example, LINUX has a higher priority than UNIX.

The illustration below shows the analyzing and matching of user-defined rules.

Process of the rule set analyzing

The analyzing and matching process is done whenever a rule set has changed. Afterwards the values of the user-defined path variables are set and can be retrieved using the interface com.sun.star.util.XStringSubstitution.

Configuration

The path substitution service uses the org.openoffice.Office.Substitution configuration branch for the rule set definitions, which adhere to this schema:

<?xml version='1.0' encoding='UTF-8'?>
  <oor:component-schema oor:name="Substitution" oor:package="org.openoffice.Office" xml:lang="en-US" xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <templates>
          <group oor:name="SharePointMapping">
              <prop oor:name="Directory" oor:type="xs:string" oor:nillable="false"/>
              <group oor:name="Environment">
                  <prop oor:name="OS" oor:type="xs:string"/>
                  <prop oor:name="Host" oor:type="xs:string"/>
                  <prop oor:name="DNSDomain" oor:type="xs:string"/>
                  <prop oor:name="YPDomain" oor:type="xs:string"/>
                  <prop oor:name="NTDomain" oor:type="xs:string"/>
              </group>
          </group>
          <set oor:name="SharePoint" oor:node-type="SharePointMapping"/>
      </templates>
      <component>
          <set oor:name="SharePoints" oor:node-type="SharePoint"/>
      </component>
  </oor:component-schema>

The SharePoints set is the root container that store the definition of the different user-defined path variables. The SharePoint set uses nodes of type SharePoint which defines a single user-defined path variable.

Properties of the SharePoint set nodes
oor:component-data String. The name of the user-defined path variable. It must be unique inside the SharePoints set.

The name must meet the requirements for path variable names, see Path Variables. The preceding characters "$(" and the succeeding ")" must be omitted, for example, the node string for the path variable $(devdoc) must be devdoc.

A SharePoint set is a container for the different rules, called SharePointMapping in the configuration.

Properties of the SharePointMapping group
oor:component-data String - must be unique inside the SharePoint set, but with no additional meaning for user-defined path variables. Use a consecutive numbering scheme - even numbers are permitted.
Directory String - must be set and contain a valid and encoded file URL that represents the value of the user-defined path variable for the rule.
Environment Group - contains a set of properties that define the environment parameter that this rule must match. You can only use one environment in a rule.
OS The operating system. The following values are supported:
  • WINDOWS = Matches all Windows OS from Win 98 and higher.
  • LINUX = Matches all supported Linux systems.
  • SOLARIS = Matches all supported Solaris systems.
  • UNIX = Matches all supported Unix systems (Linux,Solaris)
Host The host name or IP address. The name or address can include the asterisk (*) wildcard to match with zero or more characters. For example, dev*.local.de refers to all systems where the host name starts with "dev" and ends with ".local.de"
DNSDomain The domain name service. The value is case-insensitive and can use the asterisk (*) wildcard for zero or more characters.
YPDomain The yellow pages domain or NIS domain. The value is case-insensitive and can use the asterisk (*) wildcard for zero or more characters.
NTDomain Windows NT domain. The value is case-insensitive and can use the asterisk (*) wildcard for zero or more characters.

The following example uses two rules to map a Windows and Unix specific path to the user-defined path variable MyDocuments.

  <?xml version="1.0" encoding="utf-8"?>
  <oor:component-data oor:name="Substitution" oor:context="org.openoffice.Office"
  xsi:schemaLocation="http://openoffice.org/2001/registry component-update.xsd" 
  xmlns:xs="http://www.w3.org/2001/XMLSchema" 
  xmlns:oor="http://openoffice.org/2001/registry" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <node oor:name="SharePoints">
          <node oor:name="MyDocuments" oor:op="replace">
              <node oor:name="1" oor:op="replace">
                  <prop oor:name="Directory"><value>file:///H:/documents</value></prop>
                  <node oor:name="Environment">
                      <prop oor:name="OS"><value>Windows</value></prop>
                  </node>
              </node>
              <node oor:name="2" oor:op="replace">
                  <prop oor:name="Directory"><value>file:///net/home/user/documents</value></prop>
                  <node oor:name="Environment">
                      <prop oor:name="OS"><value>UNIX</value></prop>
                  </node> 
              </node>
          </node>
      </node>
  </oor:component-data>
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages