3.3 The Copy Feature

In processing XML, it is occasionally useful to copy elements from within the same file. For example, in filtering XML profiles, it is common to have the same sequence of elements on multiple meta-classes. Rather than manually copying the sequence of elements, it is better to have a single source for these elements. JeeWiz provides the 'copy' feature to do this in a single file.

3.3.1  Basic Functions of The 'Copy' Feature

The second step is to copy the element at the appropriate point in the XML, using the <copy> element. The source element for the copy (marked with 'id') is identified by using a 'ref' attribute whose value is the same as the 'id' value on the source:

<copy ref="firstID"/>

When the copy element is seen, the engine replaces the copy element with the source element (with the 'id' attribute removed). In other words, the 'copy' element above is replaced by

<source name="myName" />

3.3.2  Details

1. The "namespace" for copying is a single model (i.e. specification). In other words, when you are identifying source elements or referencing them for copies, the 'id's are only known within a single model, as defined in the previous section.
   
   This means that trying to reference copy elements from an additional specification will not work.
2. The value of the 'id' attribute must be unique across the model. There is no required format for the value of the 'id' attribute.
3. Order is important. The copy source element must be defined physically (and completely read in) before references to it can be made. This is because the copy feature is actioned as the XML is read in.
   
   The implication of an element needing to be completely read in before references can be made is that a node with an 'id' attribute cannot be copied by any nested elements, because the nesting element will not have been completely read in when nested elements are read.
4. A reference to an unknown 'id' is a fatal error and will halt the build. However, the 'ref' attribute only has special meaning on the copy element; on other elements, it can have any value.
5. The default action of the copy feature is to copy the complete tree of the source element - including any nested elements - as if they were XML source.
   
   There are two important details to highlight. One is that the children of the source element can copied (i.e. omitting the source element itself) by specifying the attribute 'children="true"'. This value is case-sensitive (only 'true' has any effect).
   
   The other detail is the implication of copying as if the copied elements 'were XML source' which is that model objects will be created according to the appropriate meta-class for the current context. For example, if the copy source element is a 'method' and it is copied beneath a JeeWiz class ('jwclass') element, the resulting model object will be an instance of the object model's Method meta-class. But if the same source is copied beneath a random parent, it will result in the default meta-class type (the 'ExtraBuildComponent').
6. All attributes on the copy element are discarded (i.e. they are not added into the copied elements). This includes the 'children' attribute.
7. The source in a copy can itself include copy elements. Because of the ordering requirement noted above, copy elements are automatically resolved before the copy can be referenced.
8. The copy feature is implemented during XML read-in, which means that it is also available from patterns.
   
   However, transforms that use patterns should take care when using the 'copy' feature on elements that fire patterns. Because this is just the source for a copy, it is probably not intended to affect the final output of the transform. Firing patterns on such an object will probably be incorrect.
9. This section has described the 'copy' element tag and the 'id' and 'ref' attributes. These names can be overridden in the build.properties file.

Copyright (c) 2001-2008 New Technology/enterprise Ltd.