Added @since tags.

This commit is contained in:
Arjen Poutsma
2007-08-16 22:36:40 +00:00
parent 070bfe68bf
commit 484bfd90ba
44 changed files with 89 additions and 96 deletions

View File

@@ -56,6 +56,7 @@ import org.xml.sax.helpers.XMLReaderFactory;
* methods.
*
* @author Arjen Poutsma
* @since 1.0
*/
public abstract class AbstractMarshaller implements Marshaller, Unmarshaller {

View File

@@ -15,26 +15,22 @@
*/
package org.springframework.oxm;
/**
* Base class for exception thrown when a marshalling or unmarshalling error occurs.
*
*
* @author Arjen Poutsma
* @see MarshallingFailureException
* @see UnmarshallingFailureException
* @since 1.0
*/
public abstract class GenericMarshallingFailureException extends XmlMappingException {
/**
* Constructor for <code>GenericMarshallingFailureException</code>.
*/
/** Constructor for <code>GenericMarshallingFailureException</code>. */
public GenericMarshallingFailureException(String msg) {
super(msg);
}
/**
* Constructor for <code>GenericMarshallingFailureException</code>.
*/
/** Constructor for <code>GenericMarshallingFailureException</code>. */
public GenericMarshallingFailureException(String msg, Throwable ex) {
super(msg, ex);
}

View File

@@ -27,6 +27,7 @@ import javax.xml.transform.Result;
* class must be registered with the marshaller, or have a common base class.
*
* @author Arjen Poutsma
* @since 1.0
*/
public interface Marshaller {

View File

@@ -15,13 +15,14 @@
*/
package org.springframework.oxm;
/**
* Exception thrown on marshalling failure.
*
* @author Arjen Poutsma
* @since 1.0
*/
public class MarshallingFailureException extends GenericMarshallingFailureException {
/**
* Construct a <code>MarshallingFailureException</code> with the specified detail message.
*

View File

@@ -15,17 +15,15 @@
*/
package org.springframework.oxm;
/**
* Superclass for exceptions that cannot be distinguished further.
*
* @author Arjen Poutsma
* @since 1.0
*/
public abstract class UncategorizedXmlMappingException extends XmlMappingException {
/**
* Constructor for <code>UncategorizedXmlMappingException</code>.
*/
/** Constructor for <code>UncategorizedXmlMappingException</code>. */
protected UncategorizedXmlMappingException(String msg, Throwable ex) {
super(msg, ex);
}

View File

@@ -20,11 +20,11 @@ import javax.xml.transform.Source;
/**
* Defines the contract for Object XML Mapping unmarshallers.
*
* <p>Implementations of this interface can deserialize a given XML Stream to an
* Object graph.
* <p/>
* <p>Implementations of this interface can deserialize a given XML Stream to an Object graph.
*
* @author Arjen Poutsma
* @since 1.0
*/
public interface Unmarshaller {

View File

@@ -19,19 +19,16 @@ package org.springframework.oxm;
* Exception thrown on unmarshalling failure.
*
* @author Arjen Poutsma
* @since 1.0
*/
public class UnmarshallingFailureException extends GenericMarshallingFailureException {
/**
* Constructor for <code>UnmarshallingFailureException</code>.
*/
/** Constructor for <code>UnmarshallingFailureException</code>. */
public UnmarshallingFailureException(String msg) {
super(msg);
}
/**
* Constructor for <code>UnmarshallingFailureException</code>.
*/
/** Constructor for <code>UnmarshallingFailureException</code>. */
public UnmarshallingFailureException(String msg, Throwable ex) {
super(msg, ex);
}

View File

@@ -19,19 +19,16 @@ package org.springframework.oxm;
* Exception thrown on marshalling validation failure.
*
* @author Arjen Poutsma
* @since 1.0
*/
public class ValidationFailureException extends XmlMappingException {
/**
* Constructor for <code>ValidationFailureException</code>.
*/
/** Constructor for <code>ValidationFailureException</code>. */
public ValidationFailureException(String msg) {
super(msg);
}
/**
* Constructor for <code>ValidationFailureException</code>.
*/
/** Constructor for <code>ValidationFailureException</code>. */
public ValidationFailureException(String msg, Throwable ex) {
super(msg, ex);
}

View File

@@ -21,19 +21,16 @@ import org.springframework.xml.XmlException;
* Root of the hierarchy of Object XML Mapping exceptions.
*
* @author Arjen Poutsma
* @since 1.0
*/
public abstract class XmlMappingException extends XmlException {
/**
* Constructor for <code>XmlMappingException</code>.
*/
/** Constructor for <code>XmlMappingException</code>. */
public XmlMappingException(String msg) {
super(msg);
}
/**
* Constructor for <code>XmlMappingException</code>.
*/
/** Constructor for <code>XmlMappingException</code>. */
public XmlMappingException(String msg, Throwable ex) {
super(msg, ex);
}

View File

@@ -73,6 +73,7 @@ import org.xml.sax.ext.LexicalHandler;
* @see #setTargetClass(Class)
* @see #setMappingLocation(org.springframework.core.io.Resource)
* @see #setMappingLocations(org.springframework.core.io.Resource[])
* @since 1.0
*/
public class CastorMarshaller extends AbstractMarshaller implements InitializingBean {
@@ -95,33 +96,27 @@ public class CastorMarshaller extends AbstractMarshaller implements Initializing
private boolean ignoreExtraElements = false;
/**
* Returns whether the Castor {@link Unmarshaller} should ignore attributes that do not match
* a specific field.
*/
/** Returns whether the Castor {@link Unmarshaller} should ignore attributes that do not match a specific field. */
public boolean getIgnoreExtraAttributes() {
return ignoreExtraAttributes;
}
/**
* Sets whether the Castor {@link Unmarshaller} should ignore attributes that do not match
* a specific field. Default is <code>true</code>: extra attributes are ignored.
* Sets whether the Castor {@link Unmarshaller} should ignore attributes that do not match a specific field.
* Default is <code>true</code>: extra attributes are ignored.
*/
public void setIgnoreExtraAttributes(boolean ignoreExtraAttributes) {
this.ignoreExtraAttributes = ignoreExtraAttributes;
}
/**
* Returns whether the Castor {@link Unmarshaller} should ignore elements that do not match
* a specific field.
*/
/** Returns whether the Castor {@link Unmarshaller} should ignore elements that do not match a specific field. */
public boolean getIgnoreExtraElements() {
return ignoreExtraElements;
}
/**
* Sets whether the Castor {@link Unmarshaller} should ignore elements that do not match
* a specific field. Default is <code>false</code>, extra attributes are flagged as an error.
* Sets whether the Castor {@link Unmarshaller} should ignore elements that do not match a specific field. Default
* is <code>false</code>, extra attributes are flagged as an error.
*/
public void setIgnoreExtraElements(boolean ignoreExtraElements) {
this.ignoreExtraElements = ignoreExtraElements;
@@ -346,10 +341,9 @@ public class CastorMarshaller extends AbstractMarshaller implements Initializing
/**
* Template method that allows for customizing of the given Castor {@link Unmarshaller}.
* <p/>
* Default implementation invokes {@link Unmarshaller#setValidation(boolean)},
* {@link Unmarshaller#setWhitespacePreserve(boolean)},
* {@link Unmarshaller#setIgnoreExtraAttributes(boolean)}, and {@link Unmarshaller#setIgnoreExtraElements(boolean)}
* with the properties set on this marshaller.
* Default implementation invokes {@link Unmarshaller#setValidation(boolean)}, {@link
* Unmarshaller#setWhitespacePreserve(boolean)}, {@link Unmarshaller#setIgnoreExtraAttributes(boolean)}, and {@link
* Unmarshaller#setIgnoreExtraElements(boolean)} with the properties set on this marshaller.
*/
protected void customizeUnmarshaller(Unmarshaller unmarshaller) {
unmarshaller.setValidation(isValidating());

View File

@@ -16,7 +16,6 @@
package org.springframework.oxm.castor;
import org.exolab.castor.xml.MarshalException;
import org.springframework.oxm.MarshallingFailureException;
/**
@@ -24,6 +23,7 @@ import org.springframework.oxm.MarshallingFailureException;
*
* @author Arjen Poutsma
* @see CastorUtils#convertXmlException
* @since 1.0
*/
public class CastorMarshallingFailureException extends MarshallingFailureException {

View File

@@ -20,8 +20,9 @@ import org.springframework.oxm.UncategorizedXmlMappingException;
/**
* Castor-specific subclass of <code>UncategorizedXmlMappingException</code>, for Castor exceptions that cannot be
* distinguished further.
*
*
* @author Arjen Poutsma
* @since 1.0
*/
public class CastorSystemException extends UncategorizedXmlMappingException {

View File

@@ -16,15 +16,15 @@
package org.springframework.oxm.castor;
import org.exolab.castor.xml.MarshalException;
import org.xml.sax.SAXException;
import org.springframework.oxm.UnmarshallingFailureException;
import org.xml.sax.SAXException;
/**
* Castor-specific subclass of <code>UnmarshallingFailureException</code>.
*
* @author Arjen Poutsma
* @see CastorUtils#convertXmlException
* @since 1.0
*/
public class CastorUnmarshallingFailureException extends UnmarshallingFailureException {

View File

@@ -18,13 +18,13 @@ package org.springframework.oxm.castor;
import org.exolab.castor.xml.MarshalException;
import org.exolab.castor.xml.ValidationException;
import org.exolab.castor.xml.XMLException;
import org.springframework.oxm.XmlMappingException;
/**
* Generic utility methods for working with Castor. Mainly for internal use within the framework.
*
* @author Arjen Poutsma
* @since 1.0
*/
public class CastorUtils {

View File

@@ -16,7 +16,6 @@
package org.springframework.oxm.castor;
import org.exolab.castor.xml.ValidationException;
import org.springframework.oxm.ValidationFailureException;
/**
@@ -24,6 +23,7 @@ import org.springframework.oxm.ValidationFailureException;
*
* @author Arjen Poutsma
* @see CastorUtils#convertXmlException
* @since 1.0
*/
public class CastorValidationFailureException extends ValidationFailureException {

View File

@@ -39,6 +39,7 @@ import org.springframework.oxm.XmlMappingException;
* @author Arjen Poutsma
* @see Jaxb1Marshaller
* @see Jaxb2Marshaller
* @since 1.0
*/
public abstract class AbstractJaxbMarshaller
implements org.springframework.oxm.Marshaller, org.springframework.oxm.Unmarshaller, InitializingBean {

View File

@@ -36,6 +36,7 @@ import org.springframework.util.StringUtils;
* @see #setMarshallerProperties(java.util.Map)
* @see #setUnmarshallerProperties(java.util.Map)
* @see #setValidating(boolean)
* @since 1.0
*/
public class Jaxb1Marshaller extends AbstractJaxbMarshaller implements InitializingBean {

View File

@@ -24,6 +24,7 @@ import org.springframework.oxm.MarshallingFailureException;
*
* @author Arjen Poutsma
* @see JaxbUtils#convertJaxbException
* @since 1.0
*/
public class JaxbMarshallingFailureException extends MarshallingFailureException {

View File

@@ -24,7 +24,8 @@ import org.springframework.oxm.UncategorizedXmlMappingException;
* be distinguished further.
*
* @author Arjen Poutsma
* @see JaxbUtils#convertJaxbException(javax.xml.bind.JAXBException)
* @see JaxbUtils#convertJaxbException(javax.xml.bind.JAXBException)
* @since 1.0
*/
public class JaxbSystemException extends UncategorizedXmlMappingException {

View File

@@ -24,6 +24,7 @@ import org.springframework.oxm.UnmarshallingFailureException;
* JAXB-specific subclass of <code>UnmarshallingFailureException</code>.
*
* @author Arjen Poutsma
* @since 1.0
*/
public class JaxbUnmarshallingFailureException extends UnmarshallingFailureException {

View File

@@ -27,6 +27,7 @@ import org.springframework.util.ClassUtils;
* Generic utility methods for working with JAXB. Mainly for internal use within the framework.
*
* @author Arjen Poutsma
* @since 1.0
*/
public abstract class JaxbUtils {

View File

@@ -24,6 +24,7 @@ import org.springframework.oxm.ValidationFailureException;
*
* @author Arjen Poutsma
* @see JaxbUtils#convertJaxbException
* @since 1.0
*/
public class JaxbValidationFailureException extends ValidationFailureException {

View File

@@ -71,6 +71,7 @@ import org.xml.sax.ext.LexicalHandler;
* @author Arjen Poutsma
* @see org.jibx.runtime.IMarshallingContext
* @see org.jibx.runtime.IUnmarshallingContext
* @since 1.0
*/
public class JibxMarshaller extends AbstractMarshaller implements InitializingBean {

View File

@@ -17,14 +17,14 @@
package org.springframework.oxm.jibx;
import org.jibx.runtime.JiBXException;
import org.springframework.oxm.MarshallingFailureException;
/**
* JiXB-specific subclass of <code>MarshallingFailureException</code>.
*
* @author Arjen Poutsma
* @see JibxUtils#convertJibxException(org.jibx.runtime.JiBXException, boolean)
* @see JibxUtils#convertJibxException(org.jibx.runtime.JiBXException,boolean)
* @since 1.0
*/
public class JibxMarshallingFailureException extends MarshallingFailureException {

View File

@@ -23,7 +23,8 @@ import org.springframework.oxm.UncategorizedXmlMappingException;
* be distinguished further.
*
* @author Arjen Poutsma
* @see JibxUtils#convertJibxException(org.jibx.runtime.JiBXException, boolean)
* @see JibxUtils#convertJibxException(org.jibx.runtime.JiBXException,boolean)
* @since 1.0
*/
public class JibxSystemException extends UncategorizedXmlMappingException {

View File

@@ -17,14 +17,14 @@
package org.springframework.oxm.jibx;
import org.jibx.runtime.JiBXException;
import org.springframework.oxm.UnmarshallingFailureException;
/**
* JiXB-specific subclass of <code>UnmarshallingFailureException</code>.
*
* @author Arjen Poutsma
* @see JibxUtils#convertJibxException(org.jibx.runtime.JiBXException, boolean)
* @see JibxUtils#convertJibxException(org.jibx.runtime.JiBXException,boolean)
* @since 1.0
*/
public class JibxUnmarshallingFailureException extends UnmarshallingFailureException {

View File

@@ -18,13 +18,13 @@ package org.springframework.oxm.jibx;
import org.jibx.runtime.JiBXException;
import org.jibx.runtime.ValidationException;
import org.springframework.oxm.XmlMappingException;
/**
* Generic utility methods for working with JiBX. Mainly for internal use within the framework.
*
* @author Arjen Poutsma
* @since 1.0
*/
public abstract class JibxUtils {

View File

@@ -17,14 +17,14 @@
package org.springframework.oxm.jibx;
import org.jibx.runtime.ValidationException;
import org.springframework.oxm.ValidationFailureException;
/**
* JAXB-specific subclass of <code>ValidationFailureException</code>.
*
* @author Arjen Poutsma
* @see JibxUtils#convertJibxException(org.jibx.runtime.JiBXException, boolean)
* @see JibxUtils#convertJibxException(org.jibx.runtime.JiBXException,boolean)
* @since 1.0
*/
public class JibxValidationFailureException extends ValidationFailureException {

View File

@@ -23,6 +23,7 @@ import javax.activation.DataHandler;
*
* @author Arjen Poutsma
* @see <a href="http://www.w3.org/TR/2005/REC-xop10-20050125/">XML-binary Optimized Packaging</a>
* @since 1.0
*/
public interface MimeContainer {

View File

@@ -30,6 +30,7 @@ import org.springframework.oxm.XmlMappingException;
* @see <a href="http://www.w3.org/TR/2004/WD-soap12-mtom-20040608/">SOAP Message Transmission Optimization
* Mechanism</a>
* @see <a href="http://www.w3.org/TR/2005/REC-xop10-20050125/">XML-binary Optimized Packaging</a>
* @since 1.0
*/
public interface MimeMarshaller extends Marshaller {

View File

@@ -30,6 +30,7 @@ import org.springframework.oxm.XmlMappingException;
* @see <a href="http://www.w3.org/TR/2004/WD-soap12-mtom-20040608/">SOAP Message Transmission Optimization
* Mechanism</a>
* @see <a href="http://www.w3.org/TR/2005/REC-xop10-20050125/">XML-binary Optimized Packaging</a>
* @since 1.0
*/
public interface MimeUnmarshaller extends Unmarshaller {

View File

@@ -40,6 +40,7 @@ import org.xml.sax.SAXParseException;
*
* @author Arjen Poutsma
* @see javax.xml.transform.Transformer
* @since 1.0
*/
public class MarshallingSource extends SAXSource {

View File

@@ -38,12 +38,11 @@ import org.xml.sax.ext.LexicalHandler;
/**
* Implementation of the {@link Marshaller} interface for XMLBeans. Further options can be set by setting the
* <code>xmlOptions</code> property. The {@link XmlOptionsFactoryBean} is provided to easily wire up
* {@link XmlOptions} instances.
* <code>xmlOptions</code> property. The {@link XmlOptionsFactoryBean} is provided to easily wire up {@link XmlOptions}
* instances.
* <p/>
* Unmarshalled objects can be validated by setting the <code>validating</code> property, or by calling the
* {@link #validate(XmlObject)} method directly. Invalid objects will result in an
* {@link XmlBeansValidationFailureException}.
* Unmarshalled objects can be validated by setting the <code>validating</code> property, or by calling the {@link
* #validate(XmlObject)} method directly. Invalid objects will result in an {@link XmlBeansValidationFailureException}.
* <p/>
* <strong>Note</strong> that due to the nature of XMLBeans, this marshaller requires all passed objects to be of type
* {@link XmlObject}.
@@ -52,6 +51,7 @@ import org.xml.sax.ext.LexicalHandler;
* @see #setXmlOptions(org.apache.xmlbeans.XmlOptions)
* @see XmlOptionsFactoryBean
* @see #setValidating(boolean)
* @since 1.0
*/
public class XmlBeansMarshaller extends AbstractMarshaller {

View File

@@ -16,15 +16,15 @@
package org.springframework.oxm.xmlbeans;
import org.apache.xmlbeans.XmlException;
import org.xml.sax.SAXException;
import org.springframework.oxm.MarshallingFailureException;
import org.xml.sax.SAXException;
/**
* XMLBeans-specific subclass of <code>MarshallingFailureException</code>.
*
* @author Arjen Poutsma
* @see XmlBeansUtils#convertXmlBeansException(Exception, boolean)
* @see XmlBeansUtils#convertXmlBeansException(Exception,boolean)
* @since 1.0
*/
public class XmlBeansMarshallingFailureException extends MarshallingFailureException {

View File

@@ -18,10 +18,11 @@ package org.springframework.oxm.xmlbeans;
import org.springframework.oxm.UncategorizedXmlMappingException;
/**
* XMLBeans-specific subclass of <code>UncategorizedXmlMappingException</code>, for XMLBeans exceptions that cannot
* be distinguished further.
*
* XMLBeans-specific subclass of <code>UncategorizedXmlMappingException</code>, for XMLBeans exceptions that cannot be
* distinguished further.
*
* @author Arjen Poutsma
* @since 1.0
*/
public class XmlBeansSystemException extends UncategorizedXmlMappingException {

View File

@@ -16,15 +16,15 @@
package org.springframework.oxm.xmlbeans;
import org.apache.xmlbeans.XmlException;
import org.xml.sax.SAXException;
import org.springframework.oxm.UnmarshallingFailureException;
import org.xml.sax.SAXException;
/**
* XMLBeans-specific subclass of <code>UnmarshallingFailureException</code>.
*
* @author Arjen Poutsma
* @see XmlBeansUtils#convertXmlBeansException(Exception, boolean)
* @see XmlBeansUtils#convertXmlBeansException(Exception,boolean)
* @since 1.0
*/
public class XmlBeansUnmarshallingFailureException extends UnmarshallingFailureException {

View File

@@ -17,14 +17,14 @@ package org.springframework.oxm.xmlbeans;
import org.apache.xmlbeans.XMLStreamValidationException;
import org.apache.xmlbeans.XmlException;
import org.xml.sax.SAXException;
import org.springframework.oxm.XmlMappingException;
import org.xml.sax.SAXException;
/**
* Generic utility methods for working with XMLBeans. Mainly for internal use within the framework.
*
* @author Arjen Poutsma
* @since 1.0
*/
public class XmlBeansUtils {

View File

@@ -17,7 +17,6 @@ package org.springframework.oxm.xmlbeans;
import org.apache.xmlbeans.XMLStreamValidationException;
import org.apache.xmlbeans.XmlException;
import org.springframework.oxm.ValidationFailureException;
/**
@@ -25,6 +24,7 @@ import org.springframework.oxm.ValidationFailureException;
*
* @author Arjen Poutsma
* @see org.springframework.oxm.xmlbeans.XmlBeansUtils#convertXmlBeansException
* @since 1.0
*/
public class XmlBeansValidationFailureException extends ValidationFailureException {

View File

@@ -20,7 +20,6 @@ import java.util.Iterator;
import java.util.Map;
import org.apache.xmlbeans.XmlOptions;
import org.springframework.beans.factory.FactoryBean;
import org.springframework.beans.factory.InitializingBean;
@@ -33,6 +32,7 @@ import org.springframework.beans.factory.InitializingBean;
* @see XmlOptions
* @see #setOptions(java.util.Map)
* @see XmlBeansMarshaller#setXmlOptions(org.apache.xmlbeans.XmlOptions)
* @since 1.0
*/
public class XmlOptionsFactoryBean implements FactoryBean, InitializingBean {
@@ -40,23 +40,17 @@ public class XmlOptionsFactoryBean implements FactoryBean, InitializingBean {
private Map options;
/**
* Returns the singleton <code>XmlOptions</code>.
*/
/** Returns the singleton <code>XmlOptions</code>. */
public Object getObject() throws Exception {
return xmlOptions;
}
/**
* Returns the class of <code>XmlOptions</code>.
*/
/** Returns the class of <code>XmlOptions</code>. */
public Class getObjectType() {
return XmlOptions.class;
}
/**
* Returns <code>true</code>.
*/
/** Returns <code>true</code>. */
public boolean isSingleton() {
return true;
}
@@ -65,7 +59,7 @@ public class XmlOptionsFactoryBean implements FactoryBean, InitializingBean {
* Sets options on the underlying <code>XmlOptions</code> object. The keys of the supplied map should be one of the
* string constants defined in <code>XmlOptions</code>, the values vary per option.
*
* @see XmlOptions#put(Object, Object)
* @see XmlOptions#put(Object,Object)
* @see XmlOptions#SAVE_PRETTY_PRINT
* @see XmlOptions#LOAD_STRIP_COMMENTS
*/

View File

@@ -74,6 +74,7 @@ import org.xml.sax.ext.LexicalHandler;
* @see #DEFAULT_ENCODING
* @see #setAliases(Map)
* @see #setConverters(ConverterMatcher[])
* @since 1.0
*/
public class XStreamMarshaller extends AbstractMarshaller {

View File

@@ -19,13 +19,13 @@ package org.springframework.oxm.xstream;
import com.thoughtworks.xstream.alias.CannotResolveClassException;
import com.thoughtworks.xstream.converters.ConversionException;
import com.thoughtworks.xstream.io.StreamException;
import org.springframework.oxm.MarshallingFailureException;
/**
* XStream-specific subclass of <code>MarshallingFailureException</code>.
*
* @author Arjen Poutsma
* @since 1.0
*/
public class XStreamMarshallingFailureException extends MarshallingFailureException {

View File

@@ -23,6 +23,7 @@ import org.springframework.oxm.UncategorizedXmlMappingException;
* distinguished further.
*
* @author Arjen Poutsma
* @since 1.0
*/
public class XStreamSystemException extends UncategorizedXmlMappingException {

View File

@@ -21,13 +21,13 @@ import javax.xml.stream.XMLStreamException;
import com.thoughtworks.xstream.alias.CannotResolveClassException;
import com.thoughtworks.xstream.converters.ConversionException;
import com.thoughtworks.xstream.io.StreamException;
import org.springframework.oxm.UnmarshallingFailureException;
/**
* XStream-specific subclass of <code>UnmarshallingFailureException</code>.
*
* @author Arjen Poutsma
* @since 1.0
*/
public class XStreamUnmarshallingFailureException extends UnmarshallingFailureException {

View File

@@ -19,13 +19,13 @@ package org.springframework.oxm.xstream;
import com.thoughtworks.xstream.alias.CannotResolveClassException;
import com.thoughtworks.xstream.converters.ConversionException;
import com.thoughtworks.xstream.io.StreamException;
import org.springframework.oxm.XmlMappingException;
/**
* Generic utility methods for working with XStream. Mainly for internal use within the framework.
*
* @author Arjen Poutsma
* @since 1.0
*/
public abstract class XStreamUtils {