universal-root.xml

<?xml version='1.0' encoding='UTF-8'?>
<?xml-model  	
			title		=	'' 	
			type		=	'application/xml' 	
			schematypens=	'http://relaxng.org/ns/structure/1.0' 
			href		=	'http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng' 	
?>
<section
	xmlns="http://docbook.org/ns/docbook" 
	xmlns:xi="http://www.w3.org/2001/XInclude"
	xmlns:xl="http://www.w3.org/1999/xlink" 
	version="5.0"
	
	role="pattern">
	
	<info>
		<title>Universal Root</title>
		
		<abstract>
			<para>Provide a single root element that contains an option of multiple elements. Often used
				for different transaction types within a single document type.</para>
		</abstract>
	</info>


	<section>
		<title>Problem</title>
		<para>There are several different types of document that need to be processed. Providing a
			single root element allows for all of the different types of document to be defined by a
			single DTD. When a processor receives this document, it will know which type of document
			to expect by inspecting the child element of the root element.</para>
	</section>

	<section>
		<title>Context</title>
		<para>Universal Root is useful when a system has several different, but related, document
			types to be processed. A transactional processor would be an example of such a
			system.</para>
	</section>

	<section>
		<title>Forces</title>
		<para>Having multiple, distinct document types can increase the maintenance burden of a
			system. Document types that may be related, but are declared in separate files can start
			to stray from commonalities that can be taken advantage of.</para>
	</section>

	<section>
		<title>Solution</title>
		<para>Create a document type that has a single root element.</para>
	</section>

	<section>
		<title>Examples</title>

		<programlisting language="dtd"><![CDATA[
<!ELEMENT Transaction
(AddAddress | RemoveAddress | UpdateAddress)>

<!ELEMENT AddAddress
(AddressBookEntry)>

<!ELEMENT RemoveAddress
(AddressID)>

<!ELEMENT UpdateAddress
(AddressID, AddressBookEntry)>


<Transaction>
<AddAddress>
<AddressBookEntry> ... </AddressBookEntry>
</AddAddress>
</Transaction>
		]]></programlisting>

		<para>In this example an online address book application is being developed. There are
			several transactions that can take place, like adding new entries, deleting entries,
			updating entries.</para>
	</section>

	<section>
		<title>Discussion</title>

		<para>This allows a way for several related types of documents to be grouped into a single
			document type structure. A processing system will always know which DTD to expect, but
			can still handle the documents differently based on the first nested element type. This
			makes sharing common definitions between the different document easy.</para>
		<para>This is also a way that multiple XML document can be gathered into a single larger
			document. For example a log file might consist of several fragments, for example:</para>

		<programlisting language="xml"><![CDATA[
<Log>
	<Time>Jan 15, 1999 10:58AM</Time>
	<Event>Startup</Event>
</Log>
<Log>
	<Time>Jan 15, 1999 11:02AM</Time>
	<Event>Message Received from Bob</Event>
</Log>
…
		]]></programlisting>


		<para>Since there is no root element in the file it cannot be processed &quot;as is&quot;.
			To process this, one can prepend a start tag, for example &quot;&lt;LogFile&gt;&quot;,
			in front of the file, and append the end tag &quot;&lt;/LogFile&gt;&quot; to the end of
			the file to be able to process it as a single XML document.</para>
	</section>

	<section>
		<title>Related Patterns</title>
		<para><link xl:href="/patterns/doc-roots/multi-root.xml">Multi Root Document Types</link> and <link xl:href="/patterns/doc-roots/multi-doc-types.xml">Multiple Document Types</link> are alternatives to this
			pattern.</para>
	</section>

	<section>
		<title>Known Uses</title>
		<para>…</para>
	</section>
</section>