Advanced Features That Are Simple To Use

Introduction

The preceding chapter made reference to a number of advanced features that are described in this chapter. These features are not advanced in the sense of "difficult", but in the sense of "more powerful." They are intended to make the framework easier and more natural to use.

There are several important advanced features:

1. Changing ownership of children
2. Handling element IDs
3. Generating efficient object-access methods using NMTOKEN declarations.
4. Forwarding attributes using NMTOKENS

Entity handling, which is a really advanced topic, but required to deal with binary data and useful for a variety of other tasks, is dealt with separately in the next chapter.

Ownership of Children

As mentioned in the previous chapter, XMLElements by default own their children. This lets the framework manage the application tree in a natural and efficient manner. When an element is deleted, its entire sub-tree is deleted with it. This is not always what we would like to happen -- in particular, there may be cases when we would like to preserve part of the element's content for use somewhere else in the tree. In this case, the best way to preserve the sub-tree is to use the swapChild() method to exchange the head of the sub-tree of interest with a null pointer, as follows:

int nIndexToSave = 5; XMLElement *pSubTreeToSave = 0; pElement->swapChild(nIndexToSave,pSubTreeToSave);

If you want to preserve the entire contents of the element, all you have to do is call setOwnsChildren(false) on it, and this will leave all of the children in place. A memory leak checker would be a good thing to have around if you start doing this very often.

Note that children are distinct from members: by default all objects own their pointer members, and will delete them when their destructor is called. If this is not the desired behaviour, simply set the pointers to null in the user destructor preamble block to prevent their deletion. Calling setOwnsChildren(false) does not have any affect on the handling of pointer members.

ID and IDREF Attributes

XML documents are trees, not graphs. They cannot contain loops, and this means that they should not contain the same pointer twice. An example is shown in Figure 4.1 of what happens when a tree contains the same pointer in more than one location.

===========================================================
Figure 4.1 -- Making a Tree a Graph
===========================================================

		   Root
	 	    |
    	-------------------------
	|	|	 	|
        |     Child2          Child4
        |       |         
     Child1-----|
	
===========================================================

I must emphasize that although structures like this will not occur unless you explictly create them, the NPF does not prevent them from occuring. If you do explicitly create loops, however, bad things will happen.

There is a real problem here, though, which is that conceptually we often want to have "the same thing" appearing in multiple places in a document/application, and it is not satisfactory to have multiple copies of something around when what we really want is multiple references to it. Fortunately, XML has a mechanism for handling just this situation: ID and IDREF attributes.

An element may have at most one attribute with type ID. An example of a declaration with and ID attribute is shown in Figure 4.2. In this case, the name of the attribute does not affect its C++ type, because ID and IDREF attributes are both mapped to strings, but I have given it an "str" prefix for consistency.

===========================================================
Figure 4.2 -- An Attribute with Type ID
===========================================================

<!ELEMENT person EMPTY>
<!ATTLIST person
strID ID #REQUIRED>
	
===========================================================

Elements with IDs also have a getID() method generated. This over-rides the method in the base class, which returns an empty string, and allows the framework to access the ID regardless of what you call it. You can use either getID() or the generated get method to get the ID -- it does not matter which.

ID handling is the reason behind the dummy constructor that gets generated for every element as well. The element factory uses these dummy constructors as a way of preventing registration of elements with IDs during startup. This is necessary because the factory uses a static map to store a pointer to each derived class it knows about, and there is no way to tell this static map to wait until the static map used by the registration mechanism is available before registering the new elements. There are many other ways of getting this result, but using a dummy constructor was the fastest and easiest to implement.

IDREFs are identical to IDs in their handling rules: and IDREF is just a reference to an ID. An element can have any number of attributes of type IDREF, and the generated code for each of them allows simple access to the underlying element. For each IDREF attribute, the framework generates a method to get the element pointed to by that IDREF value. Because there is no way of knowing what type that element may be, it has to be returned as a pointer to an XMLElement and cast to the correct type. An example is shown in Figure 4.3.

===========================================================
Figure 4.3 -- Code Generated for IDREF Attribute
===========================================================
<!ELEMENT client EMPTY>
<!ATTLIST client
strServer IDREF #REQUIRED>
	
XMLElement* getServerElement() 
	{return XMLElement::getElement(m_strServer);}
===========================================================

Using this mechanism, it is possible to have your documents as deeply intertwined as the Gordian Knot itself, all the while retaining a basic underlying tree structure that is simple to manage and maintain.

NMTOKEN Declarations for Type-Safe Child Access

Perhaps the most powerful advanced feature is the use of NMTOKEN declarations to generate type-safe access methods for specific children. This mechanism is really more powerful than it needs to be, but ensures that developers are not significantly inconvenienced by the framework's generic typing.

The problem is this: most classes have a pretty well defined structure. They contain a known number of known types, which may as well be put in a known order. The XML declaration for such a class might look like:

	<!ELEMENT person (address, job, payrollData)>

The way to do this is provided by the NMTOKEN attribute type in XML. A NMTOKEN (pronounced "name token") is a collection of name characters. It is just like a name except that it does not have to start with a letter -- it can start with a number or other allowed name character as well. Why and how such a token type ever got defined is one of the mysteries of SGML that we needn't go into here. What matters is that it provides a convenient syntax for declaring "mapped attributes" -- that is, attributes that are in fact mapped to specific children of the element.

For the person element declared above, the attribute list might look like:

	<!ATTLIST person
	strID ID #REQUIRED
	Address NMTOKEN "0"
	Job NMTOKEN "1"
	Payroll NMTOKEN "2">

	<!ELEMENT job (location, position, level)>

	<!ATTLIST person
	strID ID #REQUIRED
	Address NMTOKEN "0"
	Job NMTOKEN "1"
	Payroll NMTOKEN "2"
	Level NMTOKEN "1.2">

An example of the code generated from NMTOKEN declarations is shown in Figure 4.4. As well as the accessor method there are several other methods that should be understood as well.

	
===========================================================
Figure 4.4 -- Partial Code Generated for NMTOKEN Attribute
===========================================================
<!ELEMENT person (address, job, payrollData)>
<!ATTLIST person
Job NMTOKEN "1">

class person : virtual public XMLElement
{
public:
...
  job* getJob() 
  {
	if (m_bDirtyCache) remapAll();
        return m_pJob;
  }
...
protected:
  job*        m_pJob;
};
===========================================================

===========================================================
Figure 4.5 -- Example of remapAll() Method
===========================================================
void person::remapAll()
{
        m_pJob = dynamic_cast<job*>(getMappedChild("1"));
	assert(m_pJob != 0);

        m_bDirtyCache = false;
}
===========================================================

The init() method is called automatically by the framework as required, and should not have to be called by user.

Forwarding Attributes with NMTOKENS

Suppose you want to use the NPF with a pre-existing class library, and want to wrap some of the classes in that library with NPF classes to take advantage of the serialization framework. For example, the VTK 3D visualization library contains a camera class that has a position, a point that it is aimed toward, and an "up" vector that defines the camera orientation. It would be convenient to be able to create an NPF camera element that represented these things so that the VTK camera state could be serialized along with the rest of the application.

The NMTOKENS attribute type is used to signal this kind of mapping the the code-generator. In XML, NMTOKENS consist of one or more NMTOKEN attributes, but in this case we are over-loading it with a different meaning. An example of a NMTOKENS attribute delaration is:

 <!ELEMENT test EMPTY>
 <!ATTLIST test
  fX NMTOKENS "0">

        float getX(){
          //##NPF_GET_fX##
          return 0;
          //##NPF_GET_fX##
        };
        void setPoint(float fX){
          //##NPF_SET_pfPoint##

          //##NPF_SET_pfPoint##
        };

Note that unlike ordinary pointer members, NMTOKENS pointer members are not shared across serialization. That is, like pointers in containers, if two objects have NMTOKEN pointer members that are shared between them, after serialization they will have unshared pointers that point to the same value at different locations. For this reason, NMTOKENS pointer members should not generally be used.

REQUIRED, IMPLIED and FIXED Attributes

XML allows attributes to be declared as required, implied or fixed. A required attribute must exist for the document to parse, and implied attribute is ignored or otherwise defaulted if it is not given, and a fixed attribute can only have the value given in the DTD -- it is like a C++ "const" value, and the framework generates const members to represent fixed attributes.

Required and implied attributes are treated identically unless they are pointers. A required attribute that is held as a pointer must be initialized before the object is serialized.

Default and Allowed Values

If a default value is given for an attribute, it is used as an initializer for that attribute in the constructor. If a list of allowed values is given, an enum is created for it, and the member variable is given the enum type. If the variable has a numeric type the enumerated values are made to approximate the given values as closely as possible, although they are given the names of the numbers in this case.

The values in the allowed value list must not be quoted, and may not contain spaces. The default value must be quoted, and may not contain spaces. This is a feature of the current XML draft specification.

Private, Protected and Virtual Bases

The element naming syntax supports inheritance using a special naming convention to identify the type of inhertiance. The most common case, public non-virtual inheritance, is supported by just giving the name of the base class separated by a dot from the element in question:

<!ELEMENT base.derived EMPTY>

class derived : public base { ... };

Table 1: Syntax for Describing Inheritance in Element Names
==========================================================================
Access	 Virtual?     Syntax			Code
--------------------------------------------------------------------------
public	    no	   base.derived	    class derived : public base
protected   no	   base..derived    class derived : protected base
private	    no	   base...derived   class derived : private base
public	    yes	   base,derived	    class derived : virtual public base
protected   yes	   base,,derived    class derived : virtual protected base
private	    yes	   base,,,derived   class derived : virtual private base
==========================================================================

Modified DTD

A number of mentions have been made to the modified DTD. This section briefly reviews the changes that get made to the DTD. The first point is that the name of the modified DTD is the same as the original, but with the letters XG pre-pended. This name must not be changed, as it is the one used by the framework when validating output is generated.

The main modifications to the DTD are the changes related to container classes, in which the container class is given the correct content model and the leaf nodes for the containers are generated. Other changes include the stripping out of NMTOKEN attributes from the attribute lists, as they are not "real" attributes in the XML sense when used by the framework. The final area of change is in the naming of classes with explicitly specified bases: as mentioned above, the names of the base classes are stripped out, as each derived class serializes itself using its name alone.

DTD Structure

The next chapter is all about entities, but there is a special kind of entity that does not fit in with the rest: this is the parameter entity, which is a way of breaking a DTD up in to reuseable fragments. Parameter entity handling in the NPF is sharply limited, but still provides enough power to allow for a high level of design reuse.

A parameter entity is declared as follows:

<!ENTITY % entityName SYSTEM "filename">

Summary

This chapter has continued the introduction of the NPF in more detail, with a wide range of powerful features that can be used to represent more complex programming structures. The next chapter will cover the only genuinely difficult aspect of the NPF: entities.