001: /*
002: * GeoTools - OpenSource mapping toolkit
003: * http://geotools.org
004: * (C) 2002-2006, GeoTools Project Managment Committee (PMC)
005: *
006: * This library is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU Lesser General Public
008: * License as published by the Free Software Foundation;
009: * version 2.1 of the License.
010: *
011: * This library is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * Lesser General Public License for more details.
015: */
016: package org.geotools.xml;
017:
018: import java.util.List;
019:
020: import javax.xml.namespace.QName;
021:
022: import org.picocontainer.MutablePicoContainer;
023: import org.w3c.dom.Document;
024: import org.w3c.dom.Element;
025:
026: /**
027: * A strategy for parsing elements in an instance document which are of
028: * complex type.
029: *
030: * <p>
031: * Complex types contain child elements, and attributes. A complex strategy
032: * has the ability to
033: * <p>
034: *
035: * @author Justin Deoliveira,Refractions Research Inc.,jdeolive@refractions.net
036: *
037: */
038: public interface ComplexBinding extends Binding {
039: /**
040: * Initializes the context to be used while parsing child elements of the
041: * complex type.
042: *
043: * <p>
044: * This method is called when the leading edge of the associated element is
045: * reached. It is used to create context in which child elements will be
046: * parsed in. The context is in the form of a pico container. For types that
047: * do not need to create context for children this method should do nothing.
048: * </p>
049: *
050: * @param instance The element being parsed.
051: * @param node The node in the parse tree representing the element being
052: * parsed. It is important to note that at the time this method is called
053: * the node contains no child element nodes, only child attribute nodes.
054: * @param context The container to be used as context for child strategies.
055: *
056: */
057: // void initialize(ElementInstance instance, Node node,
058: // MutablePicoContainer context);
059: /**
060: * Initializes the context for a child element.
061: * <p>
062: * This method is called on the leading edge of a child element. It is used
063: * to create context for the binding of a child element. It is important to
064: * note that each time this method is called, the <param>node</param> parse
065: * tree will contain different, ie child nodes for those previous elements
066: * parsed.
067: * </p>
068: *
069: * @param childinstance The child element instance
070: * @param node The parse node for the parent element.
071: * @param context the context in which the child element will be parsed.
072: */
073: void initializeChildContext(ElementInstance childInstance,
074: Node node, MutablePicoContainer context);
075:
076: /**
077: * Parses a complex element from an instance document into an object
078: * representation.
079: *
080: * <p>
081: * This method is called when the trailing edge of the associated element is
082: * reached.
083: * </p>
084: *
085: * @param instance The element being parsed.
086: * @param node The node in the parse tree representing the element being
087: * parsed.
088: * @param value The result of the parse from another strategy in the type
089: * hierarchy. Could be null if this is the first strategy being executed.
090: *
091: * @return The parsed object, or null if the component could not be parsed.
092: *
093: * @throws Exception Strategy objects should not attempt to handle any exceptions.
094: */
095: Object parse(ElementInstance instance, Node node, Object value)
096: throws Exception;
097:
098: /**
099: * Performs the encoding of the object into its xml representation.
100: *
101: * <p>
102: * Complex objects are encoded as elements in a document. The <param>value</param>
103: * parameter is the encoded element, created by the parent binding. For the
104: * first binding in the execution chain this is just an empty element ( no
105: * children or attributes ). The binding has the choice to return <param>value</param>
106: * or to create a new element to return.
107: * </p>
108: *
109: * <p>
110: * This method may choose to create child elements and attributes for the element.
111: * Or as an alternative return the object values for these contructs in
112: * {@link #getProperty(Object, QName)}.
113: * </p>
114: *
115: * @param object The object being encoded.
116: * @param document The document containing the encoded element.
117: * @param value The object as encoded by the parent binding.
118: *
119: * @return The element for the objcet being encoded, or <code>null</code>
120: *
121: */
122: Element encode(Object object, Document document, Element value)
123: throws Exception;
124:
125: /**
126: * Returns a property of a particular object which corresponds to the
127: * specified name.
128: *
129: * </p>
130: * <p>This method should just return null in the event that the object being
131: * encoded is an leaf in its object model.</p>
132: *
133: * <p>
134: * For multi-values properties ( maxOccurs > 0 ), this method may return an
135: * instance of {@link java.util.Collection}, {@link java.util.Iterator}, or
136: * an array.
137: * </p>
138: *
139: * @param object The object being encoded.
140: * @param name The name of the property to obtain.
141: *
142: * @return The value of the property, or <code>null</code>.
143: */
144: Object getProperty(Object object, QName name) throws Exception;
145:
146: /**
147: * Returns a list of properties of the specified object.
148: * <p>
149: * The return list contains a set of {@link QName}, {@link Object} tuples,
150: * each as a two element object array.
151: * </p>
152: * <p>
153: * This method should only be implemented in the case where the encoder
154: * can not determine what the properties of the object are from the schema.
155: * </p>
156: * <p>
157: * An example would be an object which corresponds to an element in the
158: * schema which has a the type <code>xs:anyType</code>. Since the content
159: * of this type can be anything the schema has no way to determine what
160: * the properties are. So in this case this method must specify the
161: * properties manually as a set of name, object tuples.
162: * </p>
163: * <p>
164: * In the case of a multi-valued property, this method must return a tuple
165: * for each instance of the property, and not a list, iterator, or array
166: * containing all of the instances.
167: * </p>
168: * @param object the object being encoded.
169: *
170: * @return A list of the properties for the object.
171: *
172: */
173: List/*Object[QName,Object]*/getProperties(Object object)
174: throws Exception;
175: }
|