logexpr Expressions

The logexpr expression allows for easy logging. While it can also evaluate to a string (usually the message being logged), its primary purpose is to generate a log entry. It is represented in the xfMap document with the <logexpr> element, and it has the following general form:

<logexpr expr=’the expression to be logged’
           return=’the expression to return’
           severity=’[inform|warn|error]’
           limit=’maximum number of log messages’
           frequency=’number of hits before a message is logged’
           suppress-limit-warning=’[true|false]’>
  		<arg name=”expr”> ...</arg>
  		<arg name=”return”>...</arg>
  </logexpr>

Note: The logexpr expression supports positional arguments for backwards compatibility, but named arguments are recommended.

The logexpr expression takes the following form when using positional arguments:

<logexpr expr=’the expression to be logged’
          return=’the expression to return’
          severity=’[inform|warn|error]’
          limit=’maximum number of log messages’
          frequency=’number of hits before a message is logged’
          suppress-limit-warning=’[true|false]’>
 		<arg> <!-- The expression to be logged --> </arg>
 		<arg> <!-- some expression to return --> </arg>
 </logexpr>

When using positional arguments, the order of the two arguments cannot be changed and in order to specify return as an arg, expr must also be specified.

The expression string (i.e., the expr attribute) specifies a string to enter in the log. The return attribute specifies a value to evaluate to, and the severity attribute determines the type of log message entered into the log. All these attributes are optional, and both expr and return attributes can be specified by the two arguments. If any argument is specified, then both expr and return will be ignored. It is not possible to mix-and-match these attributes and arguments.

If no return value is specified (in either argument or attribute), then the expression evaluates to the message entered in the log. In cases where the logexpr is being used solely in order to enter a log message, the return attribute or argument must be specified to be the empty string.

The severity attribute is optional, and defaults to ‘inform’ if it is not specified.

The limit attribute is optional. This attribute determines the maximum number of log messages to display. After this number of messages have been logged, additional log messages resulting from the logexpr expression are suppressed. Notification of this event is provided in the form of a single log message stating that further log messages will be suppressed. If the limit attribute is left unspecified, then no limit is set.

If the suppress-limit-warning attribute is specified and set to true, then no notification will be provided when the logexpr expression has logged its maximum number of log messages as provided in the limit attribute.

The frequency attribute is optional can be used to control how often messages are logged. The value of this attribute specifies the number of times a logexpr is activated before a message is logged. If both frequency and limit attributes are specified, it is only when a message is logged that the limit count is incremented.

Example

items.xml

<?xml version="1.0" encoding="UTF-8"?>
<items>
   <item1>
      <key>key 1</key>
   </item1>
   <item2>
      <key>2</key>
   </item2>
   <item3>
      <key>5.002</key>
   </item3>
</items>

items.xmp

<?xml version="1.0" encoding="UTF-8"?>
 <xfmap> 
    <feature-map>
       <mapping match="items">
          <feature-type><literal expr="keys"/></feature-type>
       </mapping>
    </feature-map> 
 
    <feature-content-map>
       <mapping match="item1">
          <attributes>
             <attribute>
 <!-- Here we log ‘found item 1’ but evaluates to the empty string. This shows its use as a ‘side effect’ of logging, 
rather than for the string value it will evaluate to -->
                <name><literal expr="item-1"/><logexpr expr="found item 1" return="" severity="inform"/></name>
                <value><extract expr="./key"/></value>
             </attribute>
          </attributes>
       </mapping>
 
       <mapping match="item2">
          <attributes>
             <attribute>
           <!-- Notice that the log message becomes part of the name -->
                <name><literal expr="item"/><logexpr expr="two found" severity="warn"/></name>
                <value><extract expr="./key"/></value>
             </attribute>
          </attributes>
       </mapping>
 
       <mapping match="item3">
          <attributes>
             <attribute>
                <name><literal expr="item3"/></name>
                <value><extract expr="./key"/>
                      <logexpr severity="inform">
                         <arg name="expr"><literal expr="item 3's key was found with value "/><extract expr="./key"/></arg>
                         <arg name="return"><literal expr=" : key5 expected"/></arg>
                      </logexpr>
                </value>
             </attribute>
          </attributes>
       </mapping>
    </feature-content-map>
 </xfmap>

      Messages Logged
===================================================================
...|INFORM|found item 1
...|WARN  |two found
...|INFORM|item 3's key was found with value 5.002
====================================================================

Features Constructed
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
...|INFORM|Feature Type: `keys'
...|INFORM|Attribute(string): `item-1' has value `key 1'
...|INFORM|Attribute(string): `item3' has value `5.002: key5 expected'
...|INFORM|Attribute(string): `itemtwo found' has value `2'
...|INFORM|Attribute(string): `xml_type' has value `xml_no_geom'
...|INFORM|Geometry Type: Unknown (0)
===================================================================	

===================================================================