001: /*
002: Copyright (c) 2002-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.runtime;
030:
031: /**
032: * Binding factory interface definition. This interface is implemented by
033: * the binding factory class generated by each binding definition. All binding
034: * factory instances are guaranteed to be threadsafe and reusable.
035: *
036: * @author Dennis M. Sosnoski
037: * @version 1.0
038: */
039: public interface IBindingFactory {
040: /** Current binary version number. This is a byte-ordered value, allowing
041: for two levels of major and two levels of minor version. */
042: public static final int CURRENT_VERSION_NUMBER = 0x00020000;
043:
044: /** Current distribution file name. This is filled in by the Ant build
045: process to match the current distribution. */
046: public static final String CURRENT_VERSION_NAME = "@distrib@";
047:
048: /** Mask for portions of version number that effect compatibility. */
049: public static final int COMPATIBLE_VERSION_MASK = 0xFFFF0000;
050:
051: /**
052: * Create marshalling context instance.
053: *
054: * @return created marshalling context instance
055: * @throws JiBXException if error creating context
056: * @throws UnsupportedOperationException if marshalling not supported
057: * by binding
058: */
059: public IMarshallingContext createMarshallingContext()
060: throws JiBXException;
061:
062: /**
063: * Create unmarshalling context instance.
064: *
065: * @return created unmarshalling context instance
066: * @throws JiBXException if error creating context
067: * @throws UnsupportedOperationException if unmarshalling not supported
068: * by binding
069: */
070: public IUnmarshallingContext createUnmarshallingContext()
071: throws JiBXException;
072:
073: /**
074: * Get version number for binding compiler used.
075: *
076: * @return version number of code used to compile binding
077: */
078: public int getCompilerVersion();
079:
080: /**
081: * Get distribution name for binding compiler used.
082: *
083: * @return name of distribution for binding compiler
084: */
085: public String getCompilerDistribution();
086:
087: /**
088: * Get namespaces defined in mapping. The returned array is indexed by the
089: * namespace index number used when marshalling.
090: *
091: * @return array of namespaces defined in binding (<code>null</code> if not
092: * an output binding)
093: */
094: public String[] getNamespaces();
095:
096: /**
097: * Get initial prefixes for namespaces defined in mapping. The returned
098: * array is indexed by the namespace index number used when marshalling.
099: * Note that these are only the first prefixes associated with each
100: * namespace; it's possible to reuse the namespace in the binding with a
101: * different prefix.
102: *
103: * @return array of prefixes for namespaces defined in binding
104: * (<code>null</code> if not an output binding)
105: */
106: public String[] getPrefixes();
107:
108: /**
109: * Get mapped class names (or type names, in the case of abstract mappings).
110: * Returns array of fully-qualified class and/or type names, ordered by
111: * index number of the class.
112: *
113: * @return array of class names
114: */
115: public String[] getMappedClasses();
116:
117: /**
118: * Get namespaces of elements corresponding to mapped classes. The returned
119: * array uses the same ordering as the result of the {@link
120: * #getMappedClasses} call. Entries in the array are <code>null</code> if
121: * there is no element for a class or the element is in the default
122: * namespace.
123: *
124: * @return array of element namespaces
125: */
126: public String[] getElementNamespaces();
127:
128: /**
129: * Get names of elements corresponding to mapped classes. The returned array
130: * uses the same ordering as the result of the {@link #getMappedClasses}
131: * call. Entries in the array are <code>null</code> if there is no element
132: * for a class.
133: *
134: * @return array of element names
135: */
136: public String[] getElementNames();
137:
138: /**
139: * Get mapped class index from type name for abstract non-base mappings
140: * included in the binding. This is intended to allow identifying and using
141: * abstract mappings (basically type mappings) at runtime. The method is
142: * only returns a non-negative result if the "force-classes" option is used
143: * for the binding definition (since otherwise no marshaller/unmarshaller
144: * classes are created for abstract non-base mappings).
145: *
146: * @param type fully-qualified class or type name
147: * @return mapping index for type, or <code>-1</code> if type is not an
148: * abstract non-base mapping
149: */
150: public int getTypeIndex(String type);
151: }
|