001: /*
002: Copyright (c) 2003-2005, Dennis M. Sosnoski
003: All rights reserved.
004:
005: Redistribution and use in source and binary forms, with or without modification,
006: are permitted provided that the following conditions are met:
007:
008: * Redistributions of source code must retain the above copyright notice, this
009: list of conditions and the following disclaimer.
010: * Redistributions in binary form must reproduce the above copyright notice,
011: this list of conditions and the following disclaimer in the documentation
012: and/or other materials provided with the distribution.
013: * Neither the name of JiBX nor the names of its contributors may be used
014: to endorse or promote products derived from this software without specific
015: prior written permission.
016:
017: THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
018: ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
019: WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
020: DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
021: ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
022: (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
023: LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
024: ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
025: (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
026: SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
027: */
028:
029: package org.jibx.binding.def;
030:
031: import org.jibx.binding.classes.ContextMethodBuilder;
032: import org.jibx.runtime.JiBXException;
033:
034: /**
035: * Child component (attribute or content) interface definition. This interface
036: * provides the basic hooks for generating code from the binding definition.
037: *
038: * @author Dennis M. Sosnoski
039: * @version 1.0
040: */
041:
042: public interface IComponent {
043: /**
044: * Check if component is an optional item.
045: *
046: * @return <code>true</code> if optional, <code>false</code> if required
047: */
048: public boolean isOptional();
049:
050: /**
051: * Check if component defines one or more attribute values of the
052: * containing element.
053: *
054: * @return <code>true</code> if one or more attribute values defined for
055: * containing element, <code>false</code> if not
056: */
057: public boolean hasAttribute();
058:
059: /**
060: * Generate code to test for attribute present. This generates code that
061: * tests if a child is present as determined by attributes of the containing
062: * start tag. It leaves the result of the test (zero if missing, nonzero if
063: * present) on the stack. This call is only valid if this component has one
064: * or more attributes for the containing element.
065: *
066: * @param mb method builder
067: * @throws JiBXException if configuration error
068: */
069: public void genAttrPresentTest(ContextMethodBuilder mb)
070: throws JiBXException;
071:
072: /**
073: * Generate attribute unmarshalling code. This is called within the code
074: * generation for the unmarshaller of the class associated with the
075: * containing element. It needs to generate the necessary code for handling
076: * the unmarshalling operation, leaving the unmarshalled object
077: * reference on the stack.
078: *
079: * @param mb method builder
080: * @throws JiBXException if error in configuration
081: */
082: public void genAttributeUnmarshal(ContextMethodBuilder mb)
083: throws JiBXException;
084:
085: /**
086: * Generate attribute marshalling code. This is called within the code
087: * generation for the marshaller of the class associated with the
088: * containing element. It needs to generate the necessary code for handling
089: * the marshalling operation, consuming the marshalled object
090: * reference from the stack.
091: *
092: * @param mb method builder
093: * @throws JiBXException if error in configuration
094: */
095: public void genAttributeMarshal(ContextMethodBuilder mb)
096: throws JiBXException;
097:
098: /**
099: * Check if component defines one or more elements or text values as
100: * children of the containing element. This method is only valid after the
101: * call to {@link #setLinkages()}.
102: *
103: * @return <code>true</code> if one or more content values defined
104: * for containing element, <code>false</code> if not
105: */
106: public boolean hasContent();
107:
108: /**
109: * Generate code to test for content present. This generates code that
110: * tests if a required element is present, leaving the result of the test
111: * (zero if missing, nonzero if present) on the stack. This call is only
112: * valid if this component has one or more content components for the
113: * containing element.
114: *
115: * @param mb method builder
116: * @throws JiBXException if configuration error
117: */
118: public void genContentPresentTest(ContextMethodBuilder mb)
119: throws JiBXException;
120:
121: /**
122: * Generate element or text unmarshalling code. This is called within the
123: * code generation for the unmarshaller of the class associated with the
124: * containing element. It needs to generate the necessary code for
125: * handling the unmarshalling operation, leaving the unmarshalled object
126: * reference on the stack.
127: *
128: * @param mb method builder
129: * @throws JiBXException if error in configuration
130: */
131: public void genContentUnmarshal(ContextMethodBuilder mb)
132: throws JiBXException;
133:
134: /**
135: * Generate element or text marshalling code. This is called within the
136: * code generation for the marshaller of the class associated with the
137: * containing element. It needs to generate the necessary code for
138: * handling the marshalling operation, consuming the marshalled object
139: * reference from the stack.
140: *
141: * @param mb method builder
142: * @throws JiBXException if error in configuration
143: */
144: public void genContentMarshal(ContextMethodBuilder mb)
145: throws JiBXException;
146:
147: /**
148: * Generate code to create new instance of object. This is called within the
149: * code generation for the unmarshaller of the class associated with the
150: * containing element. It needs to generate the necessary code for creating
151: * an instance of the object to be unmarshalled, leaving the object
152: * reference on the stack.
153: *
154: * @param mb method builder
155: * @throws JiBXException if error in configuration
156: */
157: public void genNewInstance(ContextMethodBuilder mb)
158: throws JiBXException;
159:
160: /**
161: * Get type expected by component.
162: *
163: * @return fully qualified class name of expected type
164: */
165: public String getType();
166:
167: /**
168: * Check if component defines an ID value for instances of context object.
169: *
170: * @return <code>true</code> if ID value defined for instances,
171: * <code>false</code> if not
172: */
173: public boolean hasId();
174:
175: /**
176: * Generate code to load ID value of instance to stack. The generated code
177: * should assume that the top of the stack is the reference for the
178: * containing object. It must consume this and leave the actual ID value
179: * on the stack (as a <code>String</code>).
180: *
181: * @param mb method builder
182: * @throws JiBXException if configuration error
183: */
184: public void genLoadId(ContextMethodBuilder mb) throws JiBXException;
185:
186: /**
187: * Get element wrapper name. If the component defines an element as the
188: * container for content, this returns the name information for that
189: * element.
190: *
191: * @return component element name, <code>null</code> if no wrapper element
192: */
193: public NameDefinition getWrapperName();
194:
195: /**
196: * Establish and validate linkages between binding components. This is
197: * called after the basic binding structures have been set up. All linkages
198: * between components must be resolved by this method, in order to prevent
199: * problems due to the order of definitions between components. This implies
200: * that each component must in turn call the same method for each child
201: * component. None of the other method calls defined by this interface are
202: * valid until after this call.
203: *
204: * @throws JiBXException if error in configuration
205: */
206: public void setLinkages() throws JiBXException;
207:
208: // DEBUG
209: public void print(int depth);
210: }
|