Permalink
Browse files

Rename Located classes, and update some JavaDoc.

  • Loading branch information...
1 parent 6bead51 commit fd75f3c9a83b2e44b66c24b5c597b7724ee0aef5 @rolfl rolfl committed Feb 29, 2012
@@ -55,32 +55,47 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
package org.jdom2.located;
/**
- * Implemntations of this class know about their location. In XML terms this
- * is the line and column (on that line) at which the content starts.
+ * Implementations of this class know about their location (line an column).
+ * <p>
+ * While it would seem intuitive that this represents the location where the
+ * content starts, in fact, if the data is populated by a SAX parser the line
+ * and column values represent the <strong>end</strong> of the SAX
+ * <strong>event</strong>.
+ * <p>
+ * SAX parsers may vary, but it typically means the
+ * character after the last character for Text and CDATA values, the character
+ * after EntityRef, Comment, and ProcessingInstruction data, and the character
+ * after the opening tag for Element content. For DocType content, it appears
+ * that Xerces is inconsistent in the location, with the location being set at
+ * what appears to be the start of the internal subset data (if any).
+ * <p>
+ * Finally, remember that the column value counts characters, and thus, if you
+ * have tab-indented values, the tab counts as a single character (regardless of
+ * how much it indents).
*
* @author Rolf Lear
*
*/
public interface Located {
/**
- * Get the starting line number
- * @return the starting line number
+ * Get the line number
+ * @return the line number
*/
public int getLine();
/**
- * Get the starting column (character on the line).
- * @return the starting column
+ * Get the column (character on the line).
+ * @return the column
*/
public int getColumn();
/**
- * Set the starting line number
- * @param line the starting line.
+ * Set the line number
+ * @param line the line.
*/
public void setLine(int line);
/**
- * Set the starting column (character on the line).
- * @param col The starting column
+ * Set the column (character on the line).
+ * @param col The column
*/
public void setColumn(int col);
}
@@ -67,18 +67,18 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
*
* @author Rolf Lear
*/
-public class LCDATA extends CDATA implements Located {
+public class LocatedCDATA extends CDATA implements Located {
/**
- * This constructor creates a new <code>LCDATA</code> node, with the
+ * This constructor creates a new <code>LocatedCDATA</code> node, with the
* supplied string value as it's character content.
*
* @param str the node's character content.
* @throws IllegalDataException if <code>str</code> contains an
* illegal character such as a vertical tab (as determined
* by {@link org.jdom2.Verifier#checkCharacterData})
*/
- public LCDATA(String str) {
+ public LocatedCDATA(String str) {
super(str);
}
@@ -62,14 +62,14 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
*
* @author Rolf Lear
*/
-public class LComment extends Comment implements Located {
+public class LocatedComment extends Comment implements Located {
/**
* This creates the comment with the supplied text.
*
* @param text <code>String</code> content of comment.
*/
- public LComment(String text) {
+ public LocatedComment(String text) {
super(text);
}
@@ -64,7 +64,7 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
*
* @author Rolf Lear
*/
-public class LDocType extends DocType implements Located {
+public class LocatedDocType extends DocType implements Located {
/**
* This will create the <code>DocType</code> with
@@ -82,7 +82,7 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* @throws IllegalNameException if the given root element name is not a
* legal XML element name.
*/
- public LDocType(String elementName, String publicID, String systemID) {
+ public LocatedDocType(String elementName, String publicID, String systemID) {
super(elementName, publicID, systemID);
}
@@ -100,7 +100,7 @@ public LDocType(String elementName, String publicID, String systemID) {
* @throws IllegalNameException if the given root element name is not a
* legal XML element name.
*/
- public LDocType(String elementName, String systemID) {
+ public LocatedDocType(String elementName, String systemID) {
super(elementName, systemID);
}
@@ -113,7 +113,7 @@ public LDocType(String elementName, String systemID) {
* @throws IllegalNameException if the given root element name is not a
* legal XML element name.
*/
- public LDocType(String elementName) {
+ public LocatedDocType(String elementName) {
super(elementName);
}
@@ -64,7 +64,7 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* @author Rolf Lear
*
*/
-public class LElement extends Element implements Located {
+public class LocatedElement extends Element implements Located {
/**
* Creates a new element with the supplied (local) name and namespace. If
@@ -75,7 +75,7 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* @throws IllegalNameException if the given name is illegal as an element
* name
*/
- public LElement(final String name, final Namespace namespace) {
+ public LocatedElement(final String name, final Namespace namespace) {
super(name, namespace);
}
@@ -86,7 +86,7 @@ public LElement(final String name, final Namespace namespace) {
* @throws IllegalNameException if the given name is illegal as an element
* name.
*/
- public LElement(final String name) {
+ public LocatedElement(final String name) {
super(name);
}
@@ -101,7 +101,7 @@ public LElement(final String name) {
* name or the given URI is illegal as a
* namespace URI
*/
- public LElement(final String name, final String uri) {
+ public LocatedElement(final String name, final String uri) {
super(name, uri);
}
@@ -117,7 +117,7 @@ public LElement(final String name, final String uri) {
* namespace prefix, or the given URI is
* illegal as a namespace URI
*/
- public LElement(final String name, final String prefix, final String uri) {
+ public LocatedElement(final String name, final String prefix, final String uri) {
super(name, prefix, uri);
}
@@ -64,7 +64,7 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
*
* @author Rolf Lear
*/
-public class LEntityRef extends EntityRef implements Located {
+public class LocatedEntityRef extends EntityRef implements Located {
/**
* This will create a new <code>EntityRef</code> with the supplied name.
@@ -73,7 +73,7 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* @throws IllegalNameException if the given name is not a legal
* XML name.
*/
- public LEntityRef(String name) {
+ public LocatedEntityRef(String name) {
super(name);
}
@@ -88,7 +88,7 @@ public LEntityRef(String name) {
* @throws IllegalDataException if the given system ID is not a legal
* system literal.
*/
- public LEntityRef(String name, String systemID) {
+ public LocatedEntityRef(String name, String systemID) {
super(name, systemID);
}
@@ -105,7 +105,7 @@ public LEntityRef(String name, String systemID) {
* @throws IllegalNameException if the given name is not a legal
* XML name.
*/
- public LEntityRef(String name, String publicID, String systemID) {
+ public LocatedEntityRef(String name, String publicID, String systemID) {
super(name, publicID, systemID);
}
@@ -83,23 +83,23 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
@Override
public CDATA cdata(int line, int col, String text) {
- final LCDATA ret = new LCDATA(text);
+ final LocatedCDATA ret = new LocatedCDATA(text);
ret.setLine(line);
ret.setColumn(col);
return ret;
}
@Override
public Text text(int line, int col, String text) {
- final LText ret = new LText(text);
+ final LocatedText ret = new LocatedText(text);
ret.setLine(line);
ret.setColumn(col);
return ret;
}
@Override
public Comment comment(int line, int col, String text) {
- final LComment ret = new LComment(text);
+ final LocatedComment ret = new LocatedComment(text);
ret.setLine(line);
ret.setColumn(col);
return ret;
@@ -108,7 +108,7 @@ public Comment comment(int line, int col, String text) {
@Override
public DocType docType(int line, int col, String elementName,
String publicID, String systemID) {
- final LDocType ret = new LDocType(elementName, publicID, systemID);
+ final LocatedDocType ret = new LocatedDocType(elementName, publicID, systemID);
ret.setLine(line);
ret.setColumn(col);
return ret;
@@ -117,39 +117,39 @@ public DocType docType(int line, int col, String elementName,
@Override
public DocType docType(int line, int col, String elementName,
String systemID) {
- final LDocType ret = new LDocType(elementName, systemID);
+ final LocatedDocType ret = new LocatedDocType(elementName, systemID);
ret.setLine(line);
ret.setColumn(col);
return ret;
}
@Override
public DocType docType(int line, int col, String elementName) {
- final LDocType ret = new LDocType(elementName);
+ final LocatedDocType ret = new LocatedDocType(elementName);
ret.setLine(line);
ret.setColumn(col);
return ret;
}
@Override
public Element element(int line, int col, String name, Namespace namespace) {
- final LElement ret = new LElement(name, namespace);
+ final LocatedElement ret = new LocatedElement(name, namespace);
ret.setLine(line);
ret.setColumn(col);
return ret;
}
@Override
public Element element(int line, int col, String name) {
- final LElement ret = new LElement(name);
+ final LocatedElement ret = new LocatedElement(name);
ret.setLine(line);
ret.setColumn(col);
return ret;
}
@Override
public Element element(int line, int col, String name, String uri) {
- final LElement ret = new LElement(name, uri);
+ final LocatedElement ret = new LocatedElement(name, uri);
ret.setLine(line);
ret.setColumn(col);
return ret;
@@ -158,7 +158,7 @@ public Element element(int line, int col, String name, String uri) {
@Override
public Element element(int line, int col, String name, String prefix,
String uri) {
- final LElement ret = new LElement(name, prefix, uri);
+ final LocatedElement ret = new LocatedElement(name, prefix, uri);
ret.setLine(line);
ret.setColumn(col);
return ret;
@@ -167,7 +167,7 @@ public Element element(int line, int col, String name, String prefix,
@Override
public ProcessingInstruction processingInstruction(int line, int col,
String target) {
- final LProcessingInstruction ret = new LProcessingInstruction(target);
+ final LocatedProcessingInstruction ret = new LocatedProcessingInstruction(target);
ret.setLine(line);
ret.setColumn(col);
return ret;
@@ -176,7 +176,7 @@ public ProcessingInstruction processingInstruction(int line, int col,
@Override
public ProcessingInstruction processingInstruction(int line, int col,
String target, Map<String, String> data) {
- final LProcessingInstruction ret = new LProcessingInstruction(target, data);
+ final LocatedProcessingInstruction ret = new LocatedProcessingInstruction(target, data);
ret.setLine(line);
ret.setColumn(col);
return ret;
@@ -185,15 +185,15 @@ public ProcessingInstruction processingInstruction(int line, int col,
@Override
public ProcessingInstruction processingInstruction(int line, int col,
String target, String data) {
- final LProcessingInstruction ret = new LProcessingInstruction(target, data);
+ final LocatedProcessingInstruction ret = new LocatedProcessingInstruction(target, data);
ret.setLine(line);
ret.setColumn(col);
return ret;
}
@Override
public EntityRef entityRef(int line, int col, String name) {
- final LEntityRef ret = new LEntityRef(name);
+ final LocatedEntityRef ret = new LocatedEntityRef(name);
ret.setLine(line);
ret.setColumn(col);
return ret;
@@ -202,15 +202,15 @@ public EntityRef entityRef(int line, int col, String name) {
@Override
public EntityRef entityRef(int line, int col, String name, String publicID,
String systemID) {
- final LEntityRef ret = new LEntityRef(name, publicID, systemID);
+ final LocatedEntityRef ret = new LocatedEntityRef(name, publicID, systemID);
ret.setLine(line);
ret.setColumn(col);
return ret;
}
@Override
public EntityRef entityRef(int line, int col, String name, String systemID) {
- final LEntityRef ret = new LEntityRef(name, systemID);
+ final LocatedEntityRef ret = new LocatedEntityRef(name, systemID);
ret.setLine(line);
ret.setColumn(col);
return ret;
@@ -67,7 +67,7 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
*
* @author Rolf Lear
*/
-public class LProcessingInstruction extends ProcessingInstruction implements
+public class LocatedProcessingInstruction extends ProcessingInstruction implements
Located {
/**
@@ -78,7 +78,7 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* @throws IllegalTargetException if the given target is illegal
* as a processing instruction name.
*/
- public LProcessingInstruction(String target) {
+ public LocatedProcessingInstruction(String target) {
super(target);
}
@@ -92,7 +92,7 @@ public LProcessingInstruction(String target) {
* @throws IllegalTargetException if the given target is illegal
* as a processing instruction name.
*/
- public LProcessingInstruction(String target, Map<String,String> data) {
+ public LocatedProcessingInstruction(String target, Map<String,String> data) {
super(target, data);
}
@@ -105,7 +105,7 @@ public LProcessingInstruction(String target, Map<String,String> data) {
* @throws IllegalTargetException if the given target is illegal
* as a processing instruction name.
*/
- public LProcessingInstruction(String target, String data) {
+ public LocatedProcessingInstruction(String target, String data) {
super(target, data);
}
Oops, something went wrong.

0 comments on commit fd75f3c

Please sign in to comment.