001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common Development
008: * and Distribution License("CDDL") (collectively, the "License"). You
009: * may not use this file except in compliance with the License. You can obtain
010: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
011: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
012: * language governing permissions and limitations under the License.
013: *
014: * When distributing the software, include this License Header Notice in each
015: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
016: * Sun designates this particular file as subject to the "Classpath" exception
017: * as provided by Sun in the GPL Version 2 section of the License file that
018: * accompanied this code. If applicable, add the following below the License
019: * Header, with the fields enclosed by brackets [] replaced by your own
020: * identifying information: "Portions Copyrighted [year]
021: * [name of copyright owner]"
022: *
023: * Contributor(s):
024: *
025: * If you wish your version of this file to be governed by only the CDDL or
026: * only the GPL Version 2, indicate your decision by adding "[Contributor]
027: * elects to include this software in this distribution under the [CDDL or GPL
028: * Version 2] license." If you don't indicate a single choice of license, a
029: * recipient has the option to distribute your version of this file under
030: * either the CDDL, the GPL Version 2 or to extend the choice of license to
031: * its licensees as provided above. However, if you add GPL Version 2 code
032: * and therefore, elected the GPL Version 2 license, then the option applies
033: * only if the new code is made subject to such option by the copyright
034: * holder.
035: */
036:
037: package com.sun.xml.bind.v2.runtime.property;
038:
039: import java.io.IOException;
040:
041: import javax.xml.bind.JAXBContext;
042: import javax.xml.bind.JAXBElement;
043: import javax.xml.stream.XMLStreamException;
044:
045: import com.sun.xml.bind.api.AccessorException;
046: import com.sun.xml.bind.v2.model.core.ID;
047: import com.sun.xml.bind.v2.model.core.PropertyInfo;
048: import com.sun.xml.bind.v2.model.core.PropertyKind;
049: import com.sun.xml.bind.v2.runtime.JaxBeanInfo;
050: import com.sun.xml.bind.v2.runtime.XMLSerializer;
051: import com.sun.xml.bind.v2.runtime.reflect.Accessor;
052:
053: import org.xml.sax.SAXException;
054:
055: /**
056: * A JAXB property that constitutes a JAXB-bound bean.
057: *
058: * @author Kohsuke Kawaguchi (kohsuke.kawaguchi@sun.com)
059: */
060: public interface Property<BeanT> extends StructureLoaderBuilder {
061:
062: // // is this method necessary? --> probably not
063: // RuntimePropertyInfo owner();
064:
065: /**
066: * Resets the property value on the given object.
067: *
068: * <p>
069: * ... for example by setting 0 or null.
070: */
071: void reset(BeanT o) throws AccessorException;
072:
073: /**
074: * @see JaxBeanInfo#serializeBody(Object, XMLSerializer)
075: *
076: * @param outerPeer
077: * used when this property is expected to print out an element
078: * and that should be associated with this outer peer. normally null.
079: * this is only used for {@link JaxBeanInfo} for {@link JAXBElement}s.
080: * @throws AccessorException
081: * If thrown, caught by the caller and reported.
082: */
083: public void serializeBody(BeanT beanT, XMLSerializer target,
084: Object outerPeer) throws SAXException, AccessorException,
085: IOException, XMLStreamException;
086:
087: /**
088: * @see JaxBeanInfo#serializeURIs(Object, XMLSerializer)
089: */
090: public void serializeURIs(BeanT beanT, XMLSerializer target)
091: throws SAXException, AccessorException;
092:
093: /**
094: * Returns true if
095: * {@link #serializeURIs(Object,XMLSerializer)} performs some meaningful action.
096: */
097: public boolean hasSerializeURIAction();
098:
099: // /**
100: // * Builds the unmarshaller.
101: // *
102: // * @param grammar
103: // * the context object to which this property ultimately belongs to.
104: // * a property will only belong to one grammar, but to reduce the memory footprint
105: // * we don't keep that information stored in {@link Property}, and instead we
106: // * just pass the value as a parameter when needed.
107: // */
108: // Unmarshaller.Handler createUnmarshallerHandler(JAXBContextImpl grammar, Unmarshaller.Handler tail);
109:
110: /**
111: * Gets the value of the property.
112: *
113: * This method is only used when the corresponding {@link PropertyInfo#id()} is {@link ID#ID},
114: * and therefore the return type is fixed to {@link String}.
115: */
116: String getIdValue(BeanT bean) throws AccessorException,
117: SAXException;
118:
119: /**
120: * Gets the Kind of property
121: * @return
122: * always non-null.
123: */
124: PropertyKind getKind();
125:
126: // UGLY HACK to support JAX-WS
127: // if other clients want to access those functionalities,
128: // we should design a better model
129: /**
130: * If this property is mapped to the specified element,
131: * return an accessor to it.
132: *
133: * @return
134: * null if the property is not mapped to the specified element.
135: */
136: Accessor getElementPropertyAccessor(String nsUri, String localName);
137:
138: /**
139: * Called at the end of the {@link JAXBContext} initialization phase
140: * to clean up any unnecessary references.
141: */
142: void wrapUp();
143: }
|