01: /*
02: Copyright (c) 2002,2003, Dennis M. Sosnoski.
03: All rights reserved.
04:
05: Redistribution and use in source and binary forms, with or without modification,
06: are permitted provided that the following conditions are met:
07:
08: * Redistributions of source code must retain the above copyright notice, this
09: list of conditions and the following disclaimer.
10: * Redistributions in binary form must reproduce the above copyright notice,
11: this list of conditions and the following disclaimer in the documentation
12: and/or other materials provided with the distribution.
13: * Neither the name of JiBX nor the names of its contributors may be used
14: to endorse or promote products derived from this software without specific
15: prior written permission.
16:
17: THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
18: ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
19: WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
20: DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
21: ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
22: (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
23: LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
24: ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25: (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
26: SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27: */
28:
29: package org.jibx.runtime;
30:
31: /**
32: * Unmarshaller interface definition. This interface must be implemented
33: * by the handler for unmarshalling an object.
34: *
35: * Instances of classes implementing this interface must be serially
36: * reusable, meaning they can store state information while in the process
37: * of unmarshalling an object but must reset all state when called to
38: * unmarshal another object after the first one is done (even if the first
39: * object throws an exception during unmarshalling).
40: *
41: * The JiBX framework will only create one instance of an unmarshaller class
42: * for each mapped class using that unmarshaller. Generally the unmarshaller
43: * instance will not be called recursively, but this may happen in cases where
44: * the binding definition includes recursive mappings and the unmarshaller
45: * uses other unmarshallers (as opposed to handling all children directly).
46: *
47: * @author Dennis M. Sosnoski
48: * @version 1.0
49: */
50:
51: public interface IUnmarshaller {
52: /**
53: * Check if instance present in XML. This method can be called when the
54: * unmarshalling context is positioned at or just before the start of the
55: * data corresponding to an instance of this mapping. It verifies that the
56: * expected data is present.
57: *
58: * @param ctx unmarshalling context
59: * @return <code>true</code> if expected parse data found,
60: * <code>false</code> if not
61: * @throws JiBXException on error in unmarshalling process
62: */
63:
64: public boolean isPresent(IUnmarshallingContext ctx)
65: throws JiBXException;
66:
67: /**
68: * Unmarshal instance of handled class. This method call is responsible
69: * for all handling of the unmarshalling of an object from XML text,
70: * including creating the instance of the handled class if an instance is
71: * not supplied. When it is called the unmarshalling context is always
72: * positioned at or just before the start tag corresponding to the start of
73: * the class data.
74: *
75: * @param obj object to be unmarshalled (may be <code>null</code>)
76: * @param ctx unmarshalling context
77: * @return unmarshalled object (may be <code>null</code>)
78: * @throws JiBXException on error in unmarshalling process
79: */
80:
81: public Object unmarshal(Object obj, IUnmarshallingContext ctx)
82: throws JiBXException;
83: }
|