Server extensions are also useful in the area of derived fields. A derived field is an information element that is not stored within a document, but is computed when the document is retrieved. This is usually done to avoid redundant data within a document, and in cases when the value of a document node depends on the environment.

In XQuery, derived values can be generated by using constructors in the return clause. The remainder of this section describes how to deal with derived elements using X-Query.

A typical example is a person's age. We can store a person's date of birth in a document, but we cannot store his or her age because it changes over time. However, with server extensions we can define an age element in a document that describes a person, for example in jazzMusician. When such a document is retrieved, we must compute the value of this element by subtracting the date of birth from the current date.

Because we rely on values from other document nodes – here birthDate – during the computation of a derived field, we must make use of a callback function. There are three types of callback functions: XML, ODBC and System. It is the XML callback functions that we need, because we want to query Tamino for the birthDate element.

Here is the complete code for the server extension. The callback code is highlighted.

//      encyclopedia_jazzMusician.java: 
//         Implementation of server extension encyclopedia_jazzMusician: 

package tamino.SXS.jazz.encyclopedia.jazzMusician;
import com.softwareag.ino.sxs.*;
import java.util.Date;
import java.text.SimpleDateFormat; 
// Javadoc comments.
/**
 * All extensions for jazz database
 * @author Berthold Daum
 * @version 1.0
 */ 
public class encyclopedia_jazzMusician extends ASXJBase {
  /**
   * The default constructor
   * (No other constructor allowed.)
   */ 
        public encyclopedia_jazzMusician () {
        } 
        /**
         * compute age from birth date (map-out function)
         * @param object_id parameter
         * @param element_id parameter
         * @param document parameter
         */ 
  public void computeAge (int object_id, 
                          int element_id, 
                          StringBuffer document) 
              throws java.lang.Exception
  {
    // create query string for callback
    String xmlQuery = 
           "jazzMusician[@ino:id='"+object_id+"']/birthDate";
    // create new string buffer for call back results
    StringBuffer response = new StringBuffer(1024);
    // callback: XQL query
    int ret = SxsXMLXql ("encyclopedia", xmlQuery, response);
    // Here we dive deep into the rather complex error 
    // handling for server extensions callbacks.
    if (ret != 0) 
      {
        // identify the callback error
        int msgNo = SxsGetMsgNo (); 
        switch (msgNo) {
        case INO_ERROR:
          StringBuffer msgBuf = new StringBuffer ( );
          // Get the Tamino Server message number
          int inoMsgNo = SxsGetInoMsgNo ( );
          // Get the Tamino Server messageline
          ret = SxsXMLGetMessage (msgBuf);
           throw (new Exception("INO_ERROR: "
                                     +inoMsgNo+" "+msgBuf));
        default:
        // Get the SXS message corresponding to callback error
          String msg = SxsGetMsgText ();
          throw (new Exception("SXS Error: "+msgNo+" "+msg));  
        } 
      }  // error handling done, now the real logic
      // Remember, we had obtained the birthDate in "response"
      // Convert into string
      String  docstr = response.toString();
      // We have to isolate the value of the birthDate 
      //  element from the Tamino response string.
      // Could be properly done with SAX, 
      // but to be brief we do it by hand. 
      int t = docstr.indexOf("<birthDate", 0);
      // we have to scan for tag begin and end separately
      // because the tag includes attributes (ino:id).
      int b = docstr.indexOf('>',t+10)+1;
      // Find end of element
      int e = docstr.indexOf("</birthDate>", b);
      // Convert content into Date format
      SimpleDateFormat df = 
              new SimpleDateFormat ( "yyyy-MM-dd" );
      Date d1 = df.parse(docstr.substring(b,e-1));
      // Now extract years and months
      // These methods are deprecated, but we use them anyway.
      int y1 = d1.getYear();
      int m1 = d1.getMonth();
      Date d2 = new Date();
      int y2 = d2.getYear();
      int m2 = d2.getMonth();
      // Compute age
      int age = y2-y1;
      // Adjust age, if we are still 
      //   before this year's birthday
      if ((m1 > m2) || 
           ((m1 == m2) && (d1.getDate() > d2.getDate()) ))
                   age--;
      // Now pack into appropriate tags
      docstr = "<age>"+age+"</age>";
      // Write element to result buffer
      document.replace (0, docstr.length(), docstr); 
  // To delete computeAge, remove it here and from Install.xml.
  }
}

After the usual process – compilation, packing, and installation – we can use this server extension. First, we must define an element <age> in the corresponding jazzMusician schema:

The resulting schema fragment looks like this:

<xs:element name = "age" type = "xs:short">
  <xs:annotation>
    <xs:appinfo>
      <tsd:elementInfo>
        <tsd:physXNode>
          <tsd:mapXTension>
            <tsd:onCompose>
              encyclopedia_jazzMusician.computeAge
            </tsd:onCompose>
          </tsd:mapXTension>
        </tsd:physXNode>
      </tsd:elementInfo>
    </xs:appinfo>
  </xs:annotation>
</xs:element>

After making this schema known to the database, we can store jazzMusician document instances. These instances must include dummy <age> elements:

<age>0</age>

If we did not supply such elements (if we had defined minOccurs="0" in the element declaration), the computeAge server extension would not be called when the document is retrieved, and no age would be computed and displayed.

When we now query jazzMusician documents, the current age of each jazz musician is displayed. For example, the following query issued in October 2004:

jazzMusician[@ID="ColtraneJohn"]

results in:

<jazzMusician ino:id="1" type="instrumentalist"
              ID="ColtraneJohn">
  <name>
    <first>John</first> 
    <last>Coltrane</last> 
  </name>
  <birthDate>1926-09-23</birthDate> 
  <age>78</age> 
</jazzMusician>

The same query issued in October 2002 results in an age of 76.

The derived field can also be used in queries:

jazzMusician[age > 70]

However, because we cannot index derived fields, search criteria involving derived fields are always processed in the post-processing phase of a query (see From Schema to Tamino::Efficient Queries).