edu.uci.isr.xarch
Interface IXArchImplementation

All Known Implementing Classes:

DOMBasedXArchImplementation

public interface IXArchImplementation

This interface is implemented by classes that are entrypoint classes for an xArch-based data binding library. The primary purpose of implementations of this interface is to serve as a factory objects for top-level document objects (IXArch objects) and to provide implementations for implementation-dependent utility methods that don't fit anywhere else. The Apigen-generated data binding library is DOM-based, and this interface is implemented by the DOMBasedXArchImplementation class. Other data binding library implementations will have different implementations of this interface.

Author:

Eric M. Dashofy edashofy@ics.uci.edu

Method Summary

IXArch	cloneXArch(IXArch xArch) Clones a document.
IXArch	cloneXArch(IXArch xArch, Object params) Clones a document, allowing the user to pass some parameters to the implementation.
IXArchContext	createContext(IXArch xArch, String contextType) Creates a context object that can be used for creating, recontextualizing, and promoting elements in that context (XML namespace).
IXArch	createXArch() Create a new xArch-based document.
IXArch	createXArch(Object params) Create a new xArch-based document, allowing some creation parameters to be passed to the implementation.
boolean	isContainedIn(IXArch xArch, IXArchElement elt) Determines if a given IXArchElement is contained (a child of) a given IXArch.
IXArch	parse(Object documentSource) Parses a document from a given source.
String	serialize(IXArch xArch, Object params) Serializes a document into a string format.

Method Detail

createXArch

public IXArch createXArch()

Create a new xArch-based document.

Returns:

Top-level data binding IXArch corresponding to a newly created document.

createXArch

public IXArch createXArch(Object params)

Create a new xArch-based document, allowing some creation parameters to be passed to the implementation. Allowable parameters are implementation-dependent.

Parameters:

params - Object containing parameters to use when creating the new document.

Returns:

Top-level data binding IXArch corresponding to a newly created document.

createContext

public IXArchContext createContext(IXArch xArch,
                                   String contextType)

Creates a context object that can be used for creating, recontextualizing, and promoting elements in that context (XML namespace).

Parameters:

xArch - The top-level element in the document in which the context should be created.

contextType - The name of the context to create. If the context object desired is, say, TypesContext then the contextType parameter will be "types".

Returns:

A new context object implementing the the given type interface. The resulting object must be typecast to the appropriate interface. If the context object desired was, say, TypesContext then the result must be typcast to the ITypesContext interface.

cloneXArch

public IXArch cloneXArch(IXArch xArch)

Clones a document.

Parameters:

xArch - The top-level element of the document to clone.

Returns:

A new top-level element corresponding to the cloned document.

cloneXArch

public IXArch cloneXArch(IXArch xArch,
                         Object params)

Clones a document, allowing the user to pass some parameters to the implementation. The acceptable parameters are implementation-dependent.

Parameters:

xArch - The top-level element of the document to clone.

params - Parameters to use when cloning.

Returns:

A new top-level element corresponding to the cloned document.

isContainedIn

public boolean isContainedIn(IXArch xArch,
                             IXArchElement elt)

Determines if a given IXArchElement is contained (a child of) a given IXArch.

Parameters:

xArch - IXArch to check for the element.

elt - Element to check for parentage.

Returns:

true if the element is attached, false otherwise.

parse

public IXArch parse(Object documentSource)
             throws XArchParseException

Parses a document from a given source. The types of source that are acceptable to this function are implementation-dependent (e.g., Files, Strings, Readers, InputStreams, etc.). This method should throw a java.lang.IllegalArgumentException if the source type is invalid, and a XArchParseException if the source type is valid, but the parsing failed.

Parameters:

documentSource - The source from which to parse a document into a set of data bindings. The acceptable source types are implementation-dependent.

Returns:

IXArch corresponding to the top-level element of the parsed document.

Throws:

IllegalArgumentException - if the type of source is invalid.

XArchParseException - if the source is valid but the parsing fails.

serialize

public String serialize(IXArch xArch,
                        Object params)
                 throws XArchSerializeException

Serializes a document into a string format. Errors are reported via an XArchSerializeException.

Parameters:

xArch - Object corresponding to the top-level element of the document to be serialized.

params - Object containing data about how to serialize the document. Object types accepted here are implementation-dependent. If the type of the params object is unrecognized, this method should throw a java.lang.IllegalArgumentException. Some implementations may recognize a null parameter.

Returns:

The given document encoded as a string.

Throws:

XArchSerializeException - if there was an error during serialization.