001: /*
002: * Copyright 2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package com.sun.xml.internal.bind.v2.runtime;
027:
028: import java.io.IOException;
029:
030: import javax.xml.bind.annotation.XmlValue;
031: import javax.xml.datatype.XMLGregorianCalendar;
032: import javax.xml.namespace.QName;
033: import javax.xml.stream.XMLStreamException;
034:
035: import com.sun.istack.internal.NotNull;
036: import com.sun.xml.internal.bind.api.AccessorException;
037: import com.sun.xml.internal.bind.v2.model.runtime.RuntimePropertyInfo;
038: import com.sun.xml.internal.bind.v2.runtime.reflect.opt.OptimizedTransducedAccessorFactory;
039:
040: import org.xml.sax.SAXException;
041:
042: /**
043: * Responsible for converting a Java object to a lexical representation
044: * and vice versa.
045: *
046: * <p>
047: * An implementation of this interface hides how this conversion happens.
048: *
049: * <p>
050: * {@link Transducer}s are immutable.
051: *
052: * @author Kohsuke Kawaguchi (kk@kohsuke.org)
053: */
054: public interface Transducer<ValueT> {
055:
056: /**
057: * If this {@link Transducer} is the default transducer for the <code>ValueT</code>,
058: * this method returns true.
059: *
060: * Used exclusively by {@link OptimizedTransducedAccessorFactory#get(RuntimePropertyInfo)}
061: */
062: boolean isDefault();
063:
064: /**
065: * If true, this {@link Transducer} doesn't declare any namespace,
066: * and therefore {@link #declareNamespace(Object, XMLSerializer)} is no-op.
067: *
068: * It also means that the {@link #parse(CharSequence)} method
069: * won't use the context parameter.
070: */
071: boolean useNamespace();
072:
073: /**
074: * Declares the namespace URIs used in the given value to {@code w}.
075: *
076: * @param o
077: * never be null.
078: * @param w
079: * may be null if {@code !{@link #useNamespace()}}.
080: */
081: void declareNamespace(ValueT o, XMLSerializer w)
082: throws AccessorException;
083:
084: /**
085: * Converts the given value to its lexical representation.
086: *
087: * @param o
088: * never be null.
089: * @return
090: * always non-null valid lexical representation.
091: */
092: @NotNull
093: CharSequence print(@NotNull
094: ValueT o) throws AccessorException;
095:
096: /**
097: * Converts the lexical representation to a value object.
098: *
099: * @param lexical
100: * never be null.
101: * @throws AccessorException
102: * if the transducer is used to parse an user bean that uses {@link XmlValue},
103: * then this exception may occur when it tries to set the leaf value to the bean.
104: * @throws SAXException
105: * if the lexical form is incorrect, the error should be reported
106: * and SAXException may thrown (or it can return null to recover.)
107: */
108: ValueT parse(CharSequence lexical) throws AccessorException,
109: SAXException;
110:
111: /**
112: * Sends the result of the {@link #print(Object)} operation
113: * to one of the {@link XMLSerializer#text(String, String)} method,
114: * but with the best representation of the value, not necessarily String.
115: */
116: void writeText(XMLSerializer w, ValueT o, String fieldName)
117: throws IOException, SAXException, XMLStreamException,
118: AccessorException;
119:
120: /**
121: * Sends the result of the {@link #print(Object)} operation
122: * to one of the {@link XMLSerializer#leafElement(Name, String, String)} method.
123: * but with the best representation of the value, not necessarily String.
124: */
125: void writeLeafElement(XMLSerializer w, Name tagName, @NotNull
126: ValueT o, String fieldName) throws IOException, SAXException,
127: XMLStreamException, AccessorException;
128:
129: /**
130: * Transducers implicitly work against a single XML type,
131: * but sometimes (most notably {@link XMLGregorianCalendar},
132: * an instance may choose different XML types.
133: *
134: * @return
135: * return non-null from this method allows transducers
136: * to specify the type it wants to marshal to.
137: * Most of the time this method returns null, in which case
138: * the implicitly associated type will be used.
139: */
140: QName getTypeName(@NotNull
141: ValueT instance);
142: }
|