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: /**
019: * A strategy for parsing components in an instance document which are of
020: * simple type.
021: *
022: * <p>
023: * Simple types can be manifested in elements and in attributes. Simple type
024: * strategies must be capable of parsing simple values regardless of the form.
025: * </p>
026: *
027: * <p>
028: * Strategy objects must declare how they relate to other strategy objects in
029: * the type hierarchy of the type they parse. To allow strategy objects which
030: * relate through a type hiearchy to communicate, a value is passed along to
031: * strategies as they are executed. As an example, consider the strategies for
032: * <b>integer</b> and <b>decimal</b>.
033: * </p>
034: *
035: * <pre>
036: * <code>
037: * class DecimalStrategy implements Strategy {
038: * ...
039: *
040: * int getExecutionMode() {
041: * return OVERRIDE;
042: * }
043: *
044: * Object parse(InstanceComponent instance, Object value)
045: * throws Exception {
046: *
047: * BigDecimal decimal = new BigDecimal(instance.getText());
048: * return decimal;
049: * }
050: * ...
051: * }
052: *
053: * class IntegerStrategy implements Strategy {
054: * ...
055: * int getExecutionMode() {
056: * return AFTER;
057: * }
058: *
059: * Object parse(InstanceComponent instance, Object value)
060: * throws Exception {
061: *
062: * BigDecimal decimal = (BigDecimal)value;
063: * return decimal.toBigInteger();
064: * }
065: * ...
066: * }
067: * </code>
068: * </pre>
069: *
070: * <p>
071: * In the above example, the decimal strategy is at the top of the hierarchy as
072: * it declares its execution mode as {@link org.geotools.xml.Binding#OVERRIDE}.
073: * Therefore it must process the raw text of the instance being parsed, and transform
074: * it into the specific object, in this case an object of type BigDecimal.
075: * </p>
076: * <p>
077: * The integer strategy extends the decimal strategy as it declares its
078: * execution mode as {@link org.geotools.xml.Binding#AFTER}. Therefore
079: * the integer strategy has access to the result of the decimal strategy,
080: * and can simply transform the result of the decimal strategy into its
081: * specific type. In this case an object of type BigInteger.
082: * </p>
083: *
084: * @author Justin Deoliveira,Refractions Research Inc.,jdeolive@refractions.net
085: *
086: */
087: public interface SimpleBinding extends Binding {
088: /**
089: * Parses an instance component (element or attribute) into an object
090: * representation.
091: *
092: * @param instance The component being parsed.
093: * @param value The result of the parse from another strategy in the type
094: * hierarchy. Could be null if this is the first strategy being executed.
095: *
096: * @return The parsed object, or null if the component could not be parsed.
097: *
098: * @throws Strategy objects should not attempt to handle any exceptions.
099: */
100: Object parse(InstanceComponent instance, Object value)
101: throws Exception;
102:
103: /**
104: * Performs the encoding of the object as a String.
105: *
106: * @param object The object being encoded, never null.
107: * @param value The string returned from another binding in the type
108: * hierachy, which could be null.
109: *
110: * @return A String representing the object.
111: */
112: String encode(Object object, String value) throws Exception;
113: }
|