Permalink
Browse files

JavaDoc and Copyright notice tidyup

  • Loading branch information...
1 parent 616443f commit 912ba897a64943957bf3ee670e21e4440622de57 @rolfl rolfl committed Mar 14, 2012
@@ -1,6 +1,6 @@
/*--
- Copyright (C) 2000-2007 Jason Hunter & Brett McLaughlin.
+ Copyright (C) 2000-2012 Jason Hunter & Brett McLaughlin.
All rights reserved.
Redistribution and use in source and binary forms, with or without
@@ -63,6 +63,14 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
/**
* An XML attribute. Methods allow the user to obtain the value of the attribute
* as well as namespace and type information.
+ * <p>
+ * <strong>JDOM 1.x Compatibility Note:</strong><br>
+ * The Attribute class in JDOM 1.x had a number of int Constants declared to
+ * represent different Attribute Types. JDOM2 has introduced an AttributeType
+ * enumeration instead. To facilitate compatibility and to simplify JDOM 1.x
+ * migrations, the replacement AttributeType enums are referenced still using
+ * the JDOM 1.x constant names. In JDOM 1.x these names referenced constant
+ * int values. In JDOM2 these names reference Enum constants.
*
* @author Brett McLaughlin
* @author Jason Hunter
@@ -81,59 +89,37 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
// Keep the old constant names for one beta cycle to help migration
- /**
- * @see AttributeType#UNDECLARED
- */
+ /** JDOM 1.x compatible reference to {@link AttributeType#UNDECLARED} */
public final static AttributeType UNDECLARED_TYPE = AttributeType.UNDECLARED;
- /**
- * @see AttributeType#CDATA
- */
+ /** JDOM 1.x compatible reference to {@link AttributeType#CDATA} */
public final static AttributeType CDATA_TYPE = AttributeType.CDATA;
- /**
- * @see AttributeType#ID
- */
+ /** JDOM 1.x compatible reference to {@link AttributeType#ID} */
public final static AttributeType ID_TYPE = AttributeType.ID;
- /**
- * @see AttributeType#IDREF
- */
+ /** JDOM 1.x compatible reference to {@link AttributeType#IDREF} */
public final static AttributeType IDREF_TYPE = AttributeType.IDREF;
- /**
- * @see AttributeType#IDREFS
- */
+ /** JDOM 1.x compatible reference to {@link AttributeType#IDREFS} */
public final static AttributeType IDREFS_TYPE = AttributeType.IDREFS;
- /**
- * @see AttributeType#ENTITY
- */
+ /** JDOM 1.x compatible reference to {@link AttributeType#ENTITY} */
public final static AttributeType ENTITY_TYPE = AttributeType.ENTITY;
- /**
- * @see AttributeType#ENTITIES
- */
+ /** JDOM 1.x compatible reference to {@link AttributeType#ENTITIES} */
public final static AttributeType ENTITIES_TYPE = AttributeType.ENTITIES;
- /**
- * @see AttributeType#NMTOKEN
- */
+ /** JDOM 1.x compatible reference to {@link AttributeType#NMTOKEN} */
public final static AttributeType NMTOKEN_TYPE = AttributeType.NMTOKEN;
- /**
- * @see AttributeType#NMTOKENS
- */
+ /** JDOM 1.x compatible reference to {@link AttributeType#NMTOKENS} */
public final static AttributeType NMTOKENS_TYPE = AttributeType.NMTOKENS;
- /**
- * @see AttributeType#NOTATION
- */
+ /** JDOM 1.x compatible reference to {@link AttributeType#NOTATION} */
public final static AttributeType NOTATION_TYPE = AttributeType.NOTATION;
- /**
- * @see AttributeType#ENUMERATION
- */
+ /** JDOM 1.x compatible reference to {@link AttributeType#ENUMERATION} */
public final static AttributeType ENUMERATED_TYPE = AttributeType.ENUMERATION;
@@ -205,7 +191,7 @@ public Attribute(final String name, final String value, final Namespace namespac
* {@link org.jdom2.Verifier#checkCharacterData}) or
* if the given attribute type is not one of the
* supported types.
- * @deprecated Use Constructor with AttributeType type, not int type.
+ * @deprecated Use {@link #Attribute(String, String, AttributeType, Namespace)}.
*/
@Deprecated
public Attribute(final String name, final String value, final int type, final Namespace namespace) {
@@ -219,7 +205,7 @@ public Attribute(final String name, final String value, final int type, final Na
*
* @param name <code>String</code> name of <code>Attribute</code>.
* @param value <code>String</code> value for new attribute.
- * @param type <code>int</code> type for new attribute.
+ * @param type <code>AttributeType</code> for new attribute.
* @param namespace <code>Namespace</code> namespace for new attribute.
* @throws IllegalNameException if the given name is illegal as an
* attribute name or if if the new namespace is the default
@@ -269,7 +255,7 @@ public Attribute(final String name, final String value) {
*
* @param name <code>String</code> name of <code>Attribute</code>.
* @param value <code>String</code> value for new attribute.
- * @param type <code>int</code> type for new attribute.
+ * @param type <code>AttributeType</code> for new attribute.
* @throws IllegalNameException if the given name is illegal as an
* attribute name.
* @throws IllegalDataException if the given attribute value is
@@ -506,10 +492,9 @@ public Attribute setValue(final String value) {
}
/**
- * This will return the actual declared type of this
- * <code>Attribute</code>.
+ * This will return the declared type of this <code>Attribute</code>.
*
- * @return <code>int</code> - type for this attribute.
+ * @return <code>AttributeType</code> - type for this attribute.
*/
public AttributeType getAttributeType() {
return type;
@@ -1,6 +1,6 @@
/*--
- Copyright (C) 2000-2007 Jason Hunter & Brett McLaughlin.
+ Copyright (C) 2000-2012 Jason Hunter & Brett McLaughlin.
All rights reserved.
Redistribution and use in source and binary forms, with or without
@@ -1,3 +1,57 @@
+/*--
+
+ Copyright (C) 2011-2012 Jason Hunter & Brett McLaughlin.
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ 1. Redistributions of source code must retain the above copyright
+ notice, this list of conditions, and the following disclaimer.
+
+ 2. Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions, and the disclaimer that follows
+ these conditions in the documentation and/or other materials
+ provided with the distribution.
+
+ 3. The name "JDOM" must not be used to endorse or promote products
+ derived from this software without prior written permission. For
+ written permission, please contact <request_AT_jdom_DOT_org>.
+
+ 4. Products derived from this software may not be called "JDOM", nor
+ may "JDOM" appear in their name, without prior written permission
+ from the JDOM Project Management <request_AT_jdom_DOT_org>.
+
+ In addition, we request (but do not require) that you include in the
+ end-user documentation provided with the redistribution and/or in the
+ software itself an acknowledgement equivalent to the following:
+ "This product includes software developed by the
+ JDOM Project (http://www.jdom.org/)."
+ Alternatively, the acknowledgment may be graphical using the logos
+ available at http://www.jdom.org/images/logos.
+
+ THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED. IN NO EVENT SHALL THE JDOM AUTHORS OR THE PROJECT
+ CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ SUCH DAMAGE.
+
+ This software consists of voluntary contributions made by many
+ individuals on behalf of the JDOM Project and was originally
+ created by Jason Hunter <jhunter_AT_jdom_DOT_org> and
+ Brett McLaughlin <brett_AT_jdom_DOT_org>. For more information
+ on the JDOM Project, please see <http://www.jdom.org/>.
+
+ */
+
package org.jdom2;
import org.xml.sax.Attributes;
@@ -1,6 +1,6 @@
/*--
- Copyright (C) 2000-2007 Jason Hunter & Brett McLaughlin.
+ Copyright (C) 2000-2012 Jason Hunter & Brett McLaughlin.
All rights reserved.
Redistribution and use in source and binary forms, with or without
@@ -66,6 +66,7 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* @author Jason Hunter
* @author Bradley S. Huffman
* @author Victor Toni
+ * @author Rolf Lear
*/
public class CDATA extends Text {
@@ -1,45 +1,99 @@
+/*--
+
+ Copyright (C) 2012 Jason Hunter & Brett McLaughlin.
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ 1. Redistributions of source code must retain the above copyright
+ notice, this list of conditions, and the following disclaimer.
+
+ 2. Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions, and the disclaimer that follows
+ these conditions in the documentation and/or other materials
+ provided with the distribution.
+
+ 3. The name "JDOM" must not be used to endorse or promote products
+ derived from this software without prior written permission. For
+ written permission, please contact <request_AT_jdom_DOT_org>.
+
+ 4. Products derived from this software may not be called "JDOM", nor
+ may "JDOM" appear in their name, without prior written permission
+ from the JDOM Project Management <request_AT_jdom_DOT_org>.
+
+ In addition, we request (but do not require) that you include in the
+ end-user documentation provided with the redistribution and/or in the
+ software itself an acknowledgement equivalent to the following:
+ "This product includes software developed by the
+ JDOM Project (http://www.jdom.org/)."
+ Alternatively, the acknowledgment may be graphical using the logos
+ available at http://www.jdom.org/images/logos.
+
+ THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED. IN NO EVENT SHALL THE JDOM AUTHORS OR THE PROJECT
+ CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ SUCH DAMAGE.
+
+ This software consists of voluntary contributions made by many
+ individuals on behalf of the JDOM Project and was originally
+ created by Jason Hunter <jhunter_AT_jdom_DOT_org> and
+ Brett McLaughlin <brett_AT_jdom_DOT_org>. For more information
+ on the JDOM Project, please see <http://www.jdom.org/>.
+
+ */
+
package org.jdom2;
/**
- * This simple class just tidies up any cloneable classes.
- * This method deals with any CloneNotSupported exceptions.
- * THis class is package private only.
+ * This simple class just tidies up any cloneable classes. This method deals
+ * with any CloneNotSupported exceptions. THis class is package private only.
+ *
* @author Rolf Lear
- *
*/
class CloneBase implements Cloneable {
-
+
/**
- * This convenience method simply deals with the irritating
- * CloneNotSupportedException, and wraps it in IllegalStateException.
- * This should never, ever, ever happen. But, it is a pain to deal with
- * ugly clone code in some classes.
+ * Return a deep clone of this instance. Even if this instance has a parent,
+ * the returned clone will not.
* <p>
- * Subclasses of this should still call super.clone() in their clone method.
- * <p>
- * Additionally, when you use the concept of 'co-variant return values' you
- * create 'bridge' methods. By way of example, because we change the return
- * type of clone() from Object to CloneBase, Java is forced to put in a
- * 'bridge' method that has an Object return type, even though we never
- * actually call it.
+ * All JDOM core classes are Cloneable, and never throw
+ * CloneNotSupportedException. Additionally all Cloneable JDOM classes
+ * return the correct type of instance from this method and there is no
+ * need to cast the result (co-variant return vaue).
* <p>
- * This has an impact on the code coverage tool Cobertura, which reports
- * that there is missed code (and there is, the bridge method). It reports
- * it as being '0' calls to the 'class' line (the class line is marked red).
- * <p>
- * By making this CloneBase code do the first level of co-variant return, it
- * is this class which is victim of the Cobertura reporting, not the
- * multiple subclasses (like Attribute, Document, Content, etc.).
+ * Subclasses of this should still call super.clone() in their clone method.
*/
@Override
protected CloneBase clone() {
+ /*
+ * Additionally, when you use the concept of 'co-variant return values'
+ * you create 'bridge' methods. By way of example, because we change the
+ * return type of clone() from Object to CloneBase, Java is forced to
+ * put in a 'bridge' method that has an Object return type, even though
+ * we never actually call it. <p> This has an impact on the code
+ * coverage tool Cobertura, which reports that there is missed code (and
+ * there is, the bridge method). It reports it as being '0' calls to the
+ * 'class' line (the class line is marked red). By making this CloneBase
+ * code do the first level of co-variant return, it is this class which
+ * is victim of the Cobertura reporting, not the multiple subclasses
+ * (like Attribute, Document, Content, etc.).
+ */
try {
- return (CloneBase)super.clone();
+ return (CloneBase) super.clone();
} catch (CloneNotSupportedException e) {
throw new IllegalStateException(String.format(
"Unable to clone class %s which should always support it.",
- this.getClass().getName()),
- e);
+ this.getClass().getName()), e);
}
}
@@ -1,6 +1,6 @@
/*--
- Copyright (C) 2000-2007 Jason Hunter & Brett McLaughlin.
+ Copyright (C) 2000-2012 Jason Hunter & Brett McLaughlin.
All rights reserved.
Redistribution and use in source and binary forms, with or without
@@ -1,6 +1,6 @@
/*--
- Copyright (C) 2007 Jason Hunter & Brett McLaughlin.
+ Copyright (C) 2007-2012 Jason Hunter & Brett McLaughlin.
All rights reserved.
Redistribution and use in source and binary forms, with or without
@@ -72,6 +72,7 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
*
* @author Bradley S. Huffman
* @author Jason Hunter
+ * @author Rolf Lear
*/
public abstract class Content extends CloneBase
implements Serializable, NamespaceAware {
@@ -238,16 +239,6 @@ public Document getDocument() {
*/
public abstract String getValue();
- /**
- * Returns a deep, unattached copy of this child and its descendants
- * detached from any parent or document.
- * <p>
- * This method can be overridden by particular Content subclasses to return
- * a specific type of Content (co-variant return type). All overriding
- * subclasses <b>must</b> call <code>super.clone()</code>;
- *
- * @return a detached deep copy of this child and descendants
- */
@Override
public Content clone() {
Content c = (Content)super.clone();
@@ -1,6 +1,6 @@
/*--
- Copyright (C) 2000-2007 Jason Hunter & Brett McLaughlin.
+ Copyright (C) 2000-2012 Jason Hunter & Brett McLaughlin.
All rights reserved.
Redistribution and use in source and binary forms, with or without
@@ -1,6 +1,6 @@
/*--
- Copyright (C) 2000-2007 Jason Hunter & Brett McLaughlin.
+ Copyright (C) 2000-2012 Jason Hunter & Brett McLaughlin.
All rights reserved.
Redistribution and use in source and binary forms, with or without
Oops, something went wrong. Retry.

0 comments on commit 912ba89

Please sign in to comment.