Chapter 16 XML Backend

16.1 Introduction

This chapter introduces the XML representation supported by Babel. Here we describe the motivation for having an XML backend and the basic structure of a conformant XML file. To illustrate, a few of the SIDL symbol XML files will be presented.

Details regarding the layout of XML files can be obtained by referring to the Document Type Definition (DTD) provided in Appendix C. For more on the type repositories, refer to[XML Repositories in Section 6.2.

16.2 Purpose

The XML backend is a key feature of Babel. It provides the basis upon which the symbol, or type, repository depends. SIDL files should be translated into their XML representations and stored in the type repository. This is the case for the SIDL interfaces and classes that are provided as part of the Babel toolkit.

16.3 Basic Structure

Each generated XML file specifies the interfaces for a given SIDL Symbol in an expanded textual representation. Although the structure of a given file depends upon the type of symbol it contains, the basic layout consists of a set of common elements followed by symbol-specific elements.

Common Elements

The common elements are prolog, document type, name, metadata, and comment. These elements, which are described below, are followed by symbol-specific information.

Prolog.: The prolog simply identifies the XML version and encoding scheme associated with the file.
Document Type.: The document type declaration states the document contains a Symbol and it identifies the associated DTD (i. e., sidl.dtd).
Name.: The symbol name is the first element within the symbol tag pair and it identifies the name and version of the SIDL symbol that is described in the file.
Metadata.: The metadata element identifies the date the XML file was generated¹ along with a set of three key-value pair entries. The first, source-url, identifies the URL of the SIDL file that was used to generate the XML file. The second, source-line, identifies the line within the SIDL file at which the symbol was first detected. Finally, babel-version identifies the version of Babel that was used to generate the XML file.
Comment.: The comment tag is used to save off any comment that is associated with the symbol.

Packages

In addition to the common elements, packages retain elements and attributes associated with SIDL packages. These include whether or not the package is final along with a list of the symbols contained within the package. The list of symbols consists of the tuple: name, type, and version.

For example, the XML representation of the toplevel SIDL package (i. e., sidl) is:

XML

Interfaces

Similarly, the XML for interface symbols contain the common elements. In addition, they retain elements and attributes associated with SIDL interfaces. These include any extensions, parent interfaces it implements, and its methods. Method information includes its name, communication mode, short name, name extension (for languages that don’t support method overloading), comment, return type, argument list, and exception list.

For example, the XML representation of sidl.BaseInterface is:

XML

<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Symbol PUBLIC "-//CCA//sidl Symbol DTD v1.1//EN" "/babel/share/repository/sidl.dtd"> <Symbol> <SymbolName name="sidl.BaseInterface" version="0.9.12" /> <Metadata date="20051208 10:47:28 PST"> <MetadataEntry key="source-url" value="file:/babel/runtime/sidl/sidl.sidl" /> <MetadataEntry key="babel-version" value="0.10.51" /> <MetadataEntry key="xml-url" value="/babel/share/repository/sidl.BaseInterface-v0.9.12.xml" /> <MetadataEntry key="source-line" value="46" /> </Metadata> <Comment>Every interface in <code>sidl</code>implicitly inherits from <code>BaseInterface</code>, and it is implemented by <code>BaseClass</code>below.</Comment> <Interface> <ExtendsBlock /> <AllParentInterfaces /> <MethodsBlock> <Method communication="normal" copy="false" definition="abstract" extension="" shortname="addRef"> <Comment> Add one to the intrinsic reference count in the underlying object. Object in <code>sidl</code>have an intrinsic reference count. Objects continue to exist as long as the reference count is positive. Clients should call this method whenever they create another ongoing reference to an object or interface. This does not have a return value because there is no language independent type that can refer to an interface or a class. </Comment> <Type type="void" /> <ArgumentList /> <ThrowsList /> <ImplicitThrowsList> <SymbolName name="sidl.RuntimeException" version="0.9.12" /> </ImplicitThrowsList> </Method> <Method communication="normal" copy="false" definition="abstract" extension="" shortname="deleteRef"> <Comment>Decrease by one the intrinsic reference count in the underlying object, and delete the object if the reference is non-positive. Objects in <code>sidl</code>have an intrinsic reference count. Clients should call this method whenever they remove a reference to an object or interface.</Comment> <Type type="void" /> <ArgumentList /> <ThrowsList /> <ImplicitThrowsList> <SymbolName name="sidl.RuntimeException" version="0.9.12" /> </ImplicitThrowsList> </Method> <Method communication="normal" copy="false" definition="abstract" extension="" shortname="isSame"> <Comment>Return true if and only if <code>obj</code>refers to the same object as this object.</Comment> <Type type="boolean" /> <ArgumentList> <Argument copy="false" mode="in" name="iobj"> <Type type="symbol"> <SymbolName name="sidl.BaseInterface" version="0.9.12" /> </Type> </Argument> </ArgumentList> <ThrowsList /> <ImplicitThrowsList> <SymbolName name="sidl.RuntimeException" version="0.9.12" /> </ImplicitThrowsList> </Method> <Method communication="normal" copy="false" definition="abstract" extension="" shortname="isType"> <Comment>Return whether this object is an instance of the specified type. The string name must be the <code>sidl</code>type name. This routine will return <code>true</code>if and only if a cast to the string type name would succeed.</Comment> <Type type="boolean" /> <ArgumentList> <Argument copy="false" mode="in" name="name"> <Type type="string" /> </Argument> </ArgumentList> <ThrowsList /> <ImplicitThrowsList> <SymbolName name="sidl.RuntimeException" version="0.9.12" /> </ImplicitThrowsList> </Method> <Method communication="normal" copy="false" definition="abstract" extension="" shortname="getClassInfo"> <Comment>Return the meta-data about the class implementing this interface.</Comment> <Type type="symbol"> <SymbolName name="sidl.ClassInfo" version="0.9.12" /> </Type> <ArgumentList /> <ThrowsList /> <ImplicitThrowsList> <SymbolName name="sidl.RuntimeException" version="0.9.12" /> </ImplicitThrowsList> </Method> </MethodsBlock> </Interface> </Symbol>

Classes

Class definitions are almost identical to that of interfaces except for additional attributes. The additional attribute, which include whether or not the class is final. Recall that Babel/SIDL supports only single inheritance of classes; therefore, only a single class will appear in the extends block. If one does not appear in the original SIDL file, by default the class will extend sidl.Baseclase.

For example, the XML representation of sidl.BaseClass is:

XML

<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Symbol PUBLIC "-//CCA//sidl Symbol DTD v1.1//EN" "/babel/share/repository/sidl.dtd"> <Symbol> <SymbolName name="sidl.BaseClass" version="0.9.12" /> <Metadata date="20051208 10:47:28 PST"> <MetadataEntry key="source-url" value="file:/babel/runtime/sidl/sidl.sidl" /> <MetadataEntry key="babel-version" value="0.10.51" /> <MetadataEntry key="xml-url" value="/babel/share/repository/sidl.BaseClass-v0.9.12.xml" /> <MetadataEntry key="source-line" value="97" /> </Metadata> <Comment>Every class implicitly inherits from <code>BaseClass</code>. This class implements the methods in <code>BaseInterface</code>.</Comment> <Class abstract="false"> <Extends /> <ImplementsBlock> <SymbolName name="sidl.BaseInterface" version="0.9.12" /> </ImplementsBlock> <AllParentClasses /> <AllParentInterfaces> <SymbolName name="sidl.BaseInterface" version="0.9.12" /> </AllParentInterfaces> <MethodsBlock> <Method communication="normal" copy="false" definition="final" extension="" shortname="addRef"> <Comment> Add one to the intrinsic reference count in the underlying object. Object in <code>sidl</code>have an intrinsic reference count. Objects continue to exist as long as the reference count is positive. Clients should call this method whenever they create another ongoing reference to an object or interface. This does not have a return value because there is no language independent type that can refer to an interface or a class. </Comment> <Type type="void" /> <ArgumentList /> <ThrowsList /> <ImplicitThrowsList> <SymbolName name="sidl.RuntimeException" version="0.9.12" /> </ImplicitThrowsList> </Method> <Method communication="normal" copy="false" definition="final" extension="" shortname="deleteRef"> <Comment>Decrease by one the intrinsic reference count in the underlying object, and delete the object if the reference is non-positive. Objects in <code>sidl</code>have an intrinsic reference count. Clients should call this method whenever they remove a reference to an object or interface.</Comment> <Type type="void" /> <ArgumentList /> <ThrowsList /> <ImplicitThrowsList> <SymbolName name="sidl.RuntimeException" version="0.9.12" /> </ImplicitThrowsList> </Method> <Method communication="normal" copy="false" definition="final" extension="" shortname="isSame"> <Comment>Return true if and only if <code>obj</code>refers to the same object as this object.</Comment> <Type type="boolean" /> <ArgumentList> <Argument copy="false" mode="in" name="iobj"> <Type type="symbol"> <SymbolName name="sidl.BaseInterface" version="0.9.12" /> </Type> </Argument> </ArgumentList> <ThrowsList /> <ImplicitThrowsList> <SymbolName name="sidl.RuntimeException" version="0.9.12" /> </ImplicitThrowsList> </Method> <Method communication="normal" copy="false" definition="normal" extension="" shortname="isType"> <Comment>Return whether this object is an instance of the specified type. The string name must be the <code>sidl</code>type name. This routine will return <code>true</code>if and only if a cast to the string type name would succeed.</Comment> <Type type="boolean" /> <ArgumentList> <Argument copy="false" mode="in" name="name"> <Type type="string" /> </Argument> </ArgumentList> <ThrowsList /> <ImplicitThrowsList> <SymbolName name="sidl.RuntimeException" version="0.9.12" /> </ImplicitThrowsList> </Method> <Method communication="normal" copy="false" definition="final" extension="" shortname="getClassInfo"> <Comment>Return the meta-data about the class implementing this interface.</Comment> <Type type="symbol"> <SymbolName name="sidl.ClassInfo" version="0.9.12" /> </Type> <ArgumentList /> <ThrowsList /> <ImplicitThrowsList> <SymbolName name="sidl.RuntimeException" version="0.9.12" /> </ImplicitThrowsList> </Method> </MethodsBlock> </Class> </Symbol>

16.4 Command Line Options

XML must be generated from a SIDL file. The Babel command line is as follows ²:

% babel --exclude-external --text=XML file.sidl

or simply

% babel -E -tXML file.sidl

In both cases, the use of the default repository is assumed for resolving symbols. In addition, the output will appear in the default output directory.

1: Assuming the “--suppress-timestamp” option was not used.
2: For information on additional command line options, refer to Section 4.2.