net.openmarkup
Interface ObjectRealizer


public interface ObjectRealizer

An object realizer enables a new method of developing rich, dynamically composable, data-driven applications by describing their composition and configuration declaratively in XML documents. While the JAXP API operates at the level of parsers and document builders, ObjectRealizer operates at a higher level, providing services for realizing object graphs from DOM trees.

Object realization is a process by which software objects are created, configured, and processed according to a machine-readable description of those objects. It includes post-instantiation tasks, such as configuring an object with additional attributes or properties, connecting it with other objects to create complex object compositions, or otherwise manipulating an object according to control information embedded in the object description.

In other words, object realization is the process that transforms a declarative description of a collection of objects into a real object composition. Because the object description is declarative, not imperative, it differs from a script or a program, in the sense that the exact sequence of steps necessary to realize an object is not specified in the object description.

The object realization process begins with an object realizer enlisting the help of an XML parser and document builder to build a DOM tree whose nodes implement the Realizable interface. Nodes in the DOM tree are the run-time representation of elements that describe objects of interest in the source XML document. The goal of an ObjectRealizer is to faithfully realize these objects to match their description.

The realized object's class is usually specified by the ElementType of the element that is used to describe the object. If the object's class is not specified by the element type, an object realizer may choose a predefined default class for that element type. The object's class may also be specified explicitly in the object description itself on a per-element basis.

Once an object has been created by instantiating the object's class, additional attributes specified in the description must be applied to the object. An implementation of the AttributeApplier interface can be used to apply the value of a specific attribute type to a target element type. An AttributeApplier must be bound to an attribute type using an AttributeHandler and registered with an ElementType before it can be used by an object realizer to apply the value of an attribute to an element.

In order to faithfully realize an object according to an element's description, the element's children, if any, must also be actively assimilated into their parent. An implementation of the ElementAssimilator interface can be used to assimilate specific types of child elements into specific types of parent elements. An ElementAssimilator must be bound to the ElementType of the child element using an ElementHandler and registered with the ElementType of the parent element before it can be used by an object realizer to assimilate one element into another.

Author:
Ramesh Gupta

Method Summary
 void add(Vocabulary vocabulary)
          Adds the specified vocabulary to this ObjectRealizer.
 URL getDefaultBaseURL()
           
 Realizable getElement(String uriString)
          Returns the element representing the object description identified by the specified uriString.
 Realizable getElement(URL url)
          Returns the element representing the object description identified by the specified URL.
 Realizable getElement(URL baseURL, String uriString)
          Same as getElement(String) except that the specified uriString is resolved against the specified baseURL to locate the document containing the object description.
 Object getObject(String uriString)
          Returns the object realized from the object description identified by the specified uriString.
 Object getObject(URL url)
          Returns the object realized from the object description identified by the specified URL.
 Object getObject(URL baseURL, String uriString)
          Same as getObject(String) except that the specified uriString is resolved against the specified baseURL to locate the document containing the object description.
 void setDefaultBaseURL(URL baseURL)
           
 

Method Detail

add

public void add(Vocabulary vocabulary)
Adds the specified vocabulary to this ObjectRealizer.

Parameters:
vocabulary -

getObject

public Object getObject(URL url)
                 throws Exception
Returns the object realized from the object description identified by the specified URL. The object must be described in a markup language that is understood by this ObjectRealizer.

Parameters:
url - locator for the object description
Returns:
the object realized from the object description identified by the specified URL
Throws:
Exception - if an error is encountered fetching the object.

getObject

public Object getObject(String uriString)
                 throws Exception
Returns the object realized from the object description identified by the specified uriString. The object must be described in a markup language that is understood by this ObjectRealizer.

Parameters:
uriString - URI that identifies an object description
Returns:
the object realized from the object description identified by the specified uriString
Throws:
Exception - if an error is encountered fetching the object.

getObject

public Object getObject(URL baseURL,
                        String uriString)
                 throws Exception
Same as getObject(String) except that the specified uriString is resolved against the specified baseURL to locate the document containing the object description. Once the document is located, the base URL specified here may be superseded by the document's own baseURL specified through the xml:base attribute in the document.

Parameters:
baseURL - the URL against which the specified uriString is resolved to locate the document containing the object description
uriString - URI that identifies an object description
Returns:
the object realized from the object description identified by the specified uriString as resolved by the specified baseURL
Throws:
Exception - if an error is encountered fetching the object.

getElement

public Realizable getElement(URL url)
                      throws UnknownElementTypeException
Returns the element representing the object description identified by the specified URL. Throws UnknownElementTypeException if the object description is not understood by this ObjectRealizer.

Parameters:
url - locator for the element
Returns:
the element identified by the specified URL
Throws:
UnknownElementTypeException - if the element type is not understood by this ObjectRealizer

getElement

public Realizable getElement(String uriString)
                      throws UnknownElementTypeException
Returns the element representing the object description identified by the specified uriString. Throws UnknownElementTypeException if the object description is not understood by this ObjectRealizer.

Parameters:
uriString - URI that identifies an element
Returns:
the element identified by the specified uriString
Throws:
UnknownElementTypeException - if the element type is not understood by this ObjectRealizer

getElement

public Realizable getElement(URL baseURL,
                             String uriString)
                      throws UnknownElementTypeException
Same as getElement(String) except that the specified uriString is resolved against the specified baseURL to locate the document containing the object description. Once the document is located, the base URL specified here may be superseded by the document's own baseURL specified through the xml:base attribute in the document.

Parameters:
baseURL - the URL against which the specified uriString is resolved to locate the document containing the element
uriString - URI that identifies an element
Returns:
the element identified by the specified uriString as resolved by the specified baseURL
Throws:
UnknownElementTypeException

setDefaultBaseURL

public void setDefaultBaseURL(URL baseURL)

getDefaultBaseURL

public URL getDefaultBaseURL()


Copyright 2003-2004 eNode, Inc. All rights reserved.