Rocket Science » BuilderAPI Rocket Science Index »

What is the BuilderAPI?

       XML documents contain data in a structured format. The BuilderAPI defines a set of functions intended to facilitate retrieval and processing of data in XML format. The BuilderAPI complements the existing XML parsing and description APIs, SAX and DOM, by providing access paths to information without requiring any knowledge of the document structure or internal representation.

Naming Conventions

      The builder code includes the following items: blocks, elements, element text (also known as element value), attributes and attribute values. Additionally, the BuilderAPI allows for the retrieval of values from the options, relates and env array, as well as global definitions [1].

BuilderAPI Tokens:		BuilderAPI Options:
Block Element Attribute Value Option Env Relates Global Cookie		get set

      The set operation will be restricted to the Cookies, Options, and Relates tokens.

      Functions using list syntax have an 's' appended to the function name. For each token "Token", where Token is one element out of the capitalized list above, there are corresponding getTokenCount and a getToken functions. The getTokenCount function requires all items needed to identify a set of return values as arguments. The getToken function has an additional index as argument. The getTokens functions have the same arguments as getTokenCount functions.

Accessor and Utility Functions

      The getRange and getIndex functions are used to access ranges and subelements of a list. As arguments, these functions take lists as returned by getTokens functions and additional arguments specifying a range or index.

      The addRange function generates a single list from two lists. The getCount function determines the size of an available list.

Indexed and List Functions

      For each indexed function there is a corresponding list function. Essentially, it is up to the developer to choose between list or indexed functions. Typically, one approach will be a better match with a target language. For example, Tcl or Lisp are list oriented and will match up better with the list function approach and hence the list functions become the focus of development efforts

Indexed and List Functions Compared
Indexed Functions	List Functions
a=getIndex(getElements(args),I)	a=getElement(args,I)
a=getElements(args)	for (I=0; I>>getElementCount(args);I++) {addRange(a,getElement(args,I)))}
a=getCount(getElements(args))	a=getElementCount(args)

BuilderAPI and DOM

      Builder operation and DOM (Document Object Model) interfacing are fundamentally different because they serve fundamentally different purposes. The DOM defines numerous "generator" functions which modify documents being accessed, or create new documents. The builder is designed to protect the underlying documents and for that reason the builder is not allowed to modify the documents it is accessing. Therefore, a substantial subset of the DOM is not relevant to the BuilderAPI.

      The set of accessors defined by the DOM is very small. It is mainly comprised of tree walking structures and a single all-purpose retrieval function getElementByTagName. Because this function can only retrieve elements its usability is limited. To retrieve attributes the whole tree structure must be walked to determine whether a specific attribute exists or not.

      The BuilderAPI, conversely, provides functions to search an XML data structure for specific elements or attributes by name, or even attributes by values. The developer interested in XML contents is freed from having to know how to walk a tree - one simple call will retrieve all instances of a specific piece of data.

BuilderAPI Functions

      The three tables below enumerate the set of API functions. They follow the syntax described above and indicate the function name, followed by the argument count in parentheses.

      The first table lists API functions for Block, Element, and Attribute in both the Index and List Access form, along with the getValue function. Note that the arguments of index access retrieval functions such as getElement are the same as the arguments of the indexed count functions or the list access functions, with the addition of the index argument.

      Block retrieval functions do not have arguments other than the potential index. The first two arguments o the Element and Attribute retrieval functions are, respectively, an element name and a path to an element or an attribute. Blocks are considered to be elements for the purposes of retrieval.

      The getValue function has one argument, either an element or an attribute as returned by a getElement or getAttribute call.

Pure API Functions

Block

Element

SubElement

Element Text

Attribute

Attribute Value

Index Access

getBlockCount(0), getBlock(1)

getElementCount(2), getElement(3)

getSubElementCount(2), getSubElement(3)

getAttributeCount(2), getAttribute(3)

List Access

getBlocks(0)

getElements(2)

getSubElements(2)

getAttributes(2)

Common

getValue(1)

getValue(1)

      The second table lists the BuilderAPI's Global Data Accessors, which include the Global, Option, Env, Relates and Cookie tokens associated with the 'get' and 'set' operations.

      Global data retrieval functions (the 'get' functions) indicate the array element to be retrieved. Because the relates array is two dimensional (relation type and block index), getRelates has two arguments. No dependency on the block index is given for any of the other arrays.

      Global data write-accessors (the 'set' operator) have the same arguments as read-accessors, with the addition of an additional, final argument, the value to be stored in the global array.

Global Data Accessors
		Global		Option		Env		Relates		Cookie
get		getGlobal(1)		getOption(1)		getEnv(1)		getRelates(2)		getCookie(1)
set		setGlobal(2)		setOption(2)				setRelates(3)

Utility Functions
		getIndex		getRange		getCount		addRange		getParent

Footnote 1An example of such a global definition would be MaxHits, the maximum number of hits to be displayed on a single page. Back to text ^

 Copyright © 2000 Invisible Worlds. All Rights Reserved.

contact | about | site map | home