You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@turbine.apache.org by ju...@apache.org on 2002/02/27 21:05:00 UTC
cvs commit: jakarta-turbine-maven/src/java/org/apache/maven/jrcs/rcs Archive.java BranchNode.java Node.java TrunkNode.java
juanco 02/02/27 12:05:00
Modified: src/java/org/apache/maven/jrcs/rcs Archive.java
BranchNode.java Node.java TrunkNode.java
Log:
Added complete javadoc comments to Node. Removed unused methods and renamed those with ambiguous names.
Revision Changes Path
1.15 +2 -2 jakarta-turbine-maven/src/java/org/apache/maven/jrcs/rcs/Archive.java
Index: Archive.java
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/src/java/org/apache/maven/jrcs/rcs/Archive.java,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- Archive.java 27 Feb 2002 16:49:48 -0000 1.14
+++ Archive.java 27 Feb 2002 20:05:00 -0000 1.15
@@ -82,7 +82,7 @@
* This class is NOT thread safe.
*
* @author <a href="mailto:juanco@suigeneris.org">Juanco Anez</a>
- * @version $Id: Archive.java,v 1.14 2002/02/27 16:49:48 juanco Exp $
+ * @version $Id: Archive.java,v 1.15 2002/02/27 20:05:00 juanco Exp $
*/
public class Archive
extends ToString
@@ -669,7 +669,7 @@
while (n != null)
{
n.toText(s, EOL);
- n = n.getNext();
+ n = n.getRCSNext();
}
}
1.6 +10 -3 jakarta-turbine-maven/src/java/org/apache/maven/jrcs/rcs/BranchNode.java
Index: BranchNode.java
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/src/java/org/apache/maven/jrcs/rcs/BranchNode.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- BranchNode.java 27 Feb 2002 16:49:48 -0000 1.5
+++ BranchNode.java 27 Feb 2002 20:05:00 -0000 1.6
@@ -59,11 +59,18 @@
* Represents a branch node in a version control archive.
* This class is NOT thread safe.
*
+ * <p>A {@linkplain BranchNode BranchNode} stores the deltas between the previous revision
+ * and the current revision; that is, when the deltas are applied
+ * to the previous revision, the text of the current revision is obtained.
+ * The {@linkplain Node._rcsnext rcsnext} field of a BranchNode points to
+ * the next revision in the branch.
+ * </p>
+ *
* @see Node
* @see Archive
*
* @author <a href="mailto:juanco@suigeneris.org">Juanco Anez</a>
- * @version $Id: BranchNode.java,v 1.5 2002/02/27 16:49:48 juanco Exp $
+ * @version $Id: BranchNode.java,v 1.6 2002/02/27 20:05:00 juanco Exp $
*/
class BranchNode
extends Node
@@ -84,9 +91,9 @@
public BranchNode getLeafNode()
{
BranchNode result = this;
- while (result.getNext() != null)
+ while (result.getRCSNext() != null)
{
- result = (BranchNode) result.getNext();
+ result = (BranchNode) result.getRCSNext();
}
return result;
}
1.6 +261 -19 jakarta-turbine-maven/src/java/org/apache/maven/jrcs/rcs/Node.java
Index: Node.java
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/src/java/org/apache/maven/jrcs/rcs/Node.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- Node.java 27 Feb 2002 16:49:48 -0000 1.5
+++ Node.java 27 Feb 2002 20:05:00 -0000 1.6
@@ -75,9 +75,12 @@
import org.apache.maven.jrcs.diff.Diff;
import org.apache.maven.jrcs.diff.Revision;
import org.apache.maven.jrcs.util.ToString;
+import org.apache.maven.jrcs.diff.PatchFailedException;
/**
* Ancestor to all nodes in a version control Archive.
+ * <p>Nodes store the deltas between two revisions of the text.</p>
+ *
* This class is NOT thread safe.
*
* @see TrunkNode
@@ -85,13 +88,16 @@
* @see Archive
*
* @author <a href="mailto:juanco@suigeneris.org">Juanco Anez</a>
- * @version $Id: Node.java,v 1.5 2002/02/27 16:49:48 juanco Exp $
+ * @version $Id: Node.java,v 1.6 2002/02/27 20:05:00 juanco Exp $
*/
abstract class Node
extends ToString
implements Comparable
{
+ /**
+ * The version number for this node.
+ */
public final Version version;
protected Date _date = new Date();
protected String _author = System.getProperty("user.name");
@@ -117,6 +123,10 @@
protected static final DateFormat dateFormat2K = new SimpleDateFormat("yyyy.MM.dd.HH.mm.ss");
+ /**
+ * Creates a copy of a node. Only used internally.
+ * @param other The node to copy.
+ */
protected Node(Node other)
{
this(other.version, null);
@@ -127,36 +137,60 @@
this._locker = other._locker;
}
- protected Node(Version vernum, Node _rcsnext)
+ /**
+ * Creates a node with the given version number.
+ * @param vernum The version number for the node.
+ * @param rcsnext The next node in the RCS logical hierarchy.
+ */
+ protected Node(Version vernum, Node rcsnext)
{
if (vernum == null)
{
throw new IllegalArgumentException(vernum.toString());
}
this.version = (Version) vernum.clone();
- this.setRCSNext(_rcsnext);
+ this.setRCSNext(rcsnext);
}
- static Node newNode(Version vernum, Node _rcsnext)
+ /**
+ * Creates a new node of the adequate type for the given version number.
+ * @param vernum The version number for the node.
+ * @param rcsnext The next node in the RCS logical hierarchy.
+ * @return The newly created node.
+ */
+ static Node newNode(Version vernum, Node rcsnext)
throws InvalidVersionNumberException
{
if (vernum.isTrunk())
{
- return new TrunkNode(vernum, (TrunkNode) _rcsnext);
+ return new TrunkNode(vernum, (TrunkNode) rcsnext);
}
else
{
- return new BranchNode(vernum, (BranchNode) _rcsnext);
+ return new BranchNode(vernum, (BranchNode) rcsnext);
}
}
+ /**
+ * Creates a new node of the adequate type for the given version number.
+ * @param vernum The version number for the node.
+ * @param rcsnext The next node in the RCS logical hierarchy.
+ * @return The newly created node.
+ */
static Node newNode(Version vernum)
throws InvalidVersionNumberException
{
return newNode(vernum, null);
}
+
+ /**
+ * Compares the version number of this node to that of another node.
+ * @param other The node to compare two.
+ * @return 0 if versions are equal, 1 if this version greather than the other,
+ * and -1 otherwise.
+ */
public int compareTo(Object other)
{
if (other == this)
@@ -173,11 +207,24 @@
}
}
+
+ /**
+ * Returns true if the node is a "ghost" node.
+ * Ghost nodes have no associated text ot deltas. CVS uses
+ * them to mark certain points in the node hierarchy.
+ */
protected boolean isGhost()
{
return version.isGhost() || _text == null;
}
+ /**
+ * Retrieve the branch node identified with
+ * the given numer.
+ * @param no The branch number.
+ * @return The branch node.
+ * @see BranchNode
+ */
protected BranchNode getBranch(int no)
{
if (_branches == null)
@@ -195,6 +242,11 @@
}
}
+
+ /**
+ * Return the root node of the node hierarchy.
+ * @return The root node.
+ */
protected Node root()
{
Node result = this;
@@ -205,16 +257,33 @@
return result;
}
+ /**
+ * Set the locker.
+ * @param user A symbol that identifies the locker.
+ */
protected void setLocker(String user)
{
_locker = user.intern();
}
+ /**
+ * Set the author of the node's revision.
+ * @param user A symbol that identifies the author.
+ */
protected void setAuthor(String user)
{
_author = user.intern();
}
+
+ /**
+ * Set the date of the node's revision.
+ * @param value an array of 6 integers, corresponding to the
+ * year, month, day, hour, minute, and second of this revision.<br>
+ * If the year has two digits, it is interpreted as belonging to the 20th
+ * century.<br>
+ * The month is a number from 1 to 12.
+ */
protected void setDate(int[] value)
{
this._date = new GregorianCalendar(value[0] + (value[0] <= 99 ? 1900 : 0),
@@ -222,36 +291,83 @@
value[3], value[4], value[5]).getTime();
}
+ /**
+ * Sets the state of the node's revision.
+ * @param value A symbol that identifies the state. The most commonly
+ * used value is Exp.
+ */
protected void setState(String value)
{
_state = value;
}
+ /**
+ * Sets the next node in the RCS logical hierarchy.
+ * In the RCS hierarchy, a {@linkplain TrunkNode TrunkNode} points
+ * to the previous revision, while a {@linkplain BranchNode BranchNode}
+ * points to the next revision.
+ * @param node The next node in the RCS logical hierarchy.
+ */
protected void setRCSNext(Node node)
{
_rcsnext = node;
}
+ /**
+ * Sets the log message for the node's revision.
+ * The log message is usually used to explain why the revision took place.
+ * @param value The message.
+ */
protected void setLog(String value)
{
_log = value;
}
+ /**
+ * Sets the text for the node's revision.
+ * <p>For archives containing binary information, the text is an image
+ * of the revision contents.</p>
+ * <p>For ASCII archives, the text contains the delta between the
+ * current revision and the next revision in the RCS logical hierarchy.
+ * The deltas are codified in a format similar to the one used by Unix diff.</p>
+ * <p> The passed string is converted to an array of objects
+ * befored being stored as the revision's text</p>
+ * @param value The revision's text.
+ * @see ArchiveParser
+ */
protected void setText(String value)
{
this._text = org.apache.maven.jrcs.diff.Diff.stringToArray(value);
}
+ /**
+ * Sets the text for the node's revision.
+ * <p>For archives containing binary information, the text is an image
+ * of the revision contents.</p>
+ * <p>For ASCII archives, the text contains the delta between the
+ * current revision and the next revision in the RCS logical hierarchy.
+ * The deltas are codified in a format similar to the one used by Unix diff.
+ * @param value The revision's text.
+ * @see ArchiveParser
+ */
protected void setText(Object[] value)
{
this._text = Arrays.asList(value).toArray();
}
+ /**
+ * Adds a branch node to the current node.
+ * @param node The branch node.
+ * @throws InvalidVersionNumberException if the version number
+ * is not a valid branch version number for the current node
+ */
protected void addBranch(BranchNode node)
+ throws InvalidVersionNumberException
{
- if (node.version.isLessThan(this.version))
+ if (node.version.isLessThan(this.version)
+ || node.version.size() != (this.version.size()+2))
{
- throw new IllegalArgumentException();
+ throw new InvalidVersionNumberException("version must be grater");
}
int branchno = node.version.at(this.version.size());
@@ -263,11 +379,23 @@
node._parent = this;
}
+
+ /**
+ * Returns the version number that should correspond to
+ * the revision folowing this node.
+ * @return The next version number.
+ */
protected Version nextVersion()
{
return this.version.next();
}
+
+ /**
+ * Returns the version number that should correspond to a newly
+ * created branch of this node.
+ * @return the new branch's version number.
+ */
protected Version newBranchVersion()
{
Version result = new Version(this.version);
@@ -283,22 +411,47 @@
return result;
}
- protected String getRevision(Version vernum)
- {
- return null;
- }
-
- protected Node getNext()
+
+ /**
+ * Return the next node in the RCS logical hierarchy.
+ * @return the next node
+ */
+ protected Node getRCSNext()
{
return _rcsnext;
}
+
+ /**
+ * Returns the path from the current node to the node
+ * identified by the given version.
+ * @param vernum The version number of the last node in the path.
+ * @return The path
+ * @throws NodeNotFoundException if a node with the given version number
+ * doesn't exist, or is not reachable following the RCS-next chain
+ * from this node.
+ * @see Path
+ */
protected Path pathTo(Version vernum)
throws NodeNotFoundException
{
return pathTo(vernum, false);
}
+ /**
+ * Returns the path from the current node to the node
+ * identified by the given version.
+ * @param vernum The version number of the last node in the path.
+ * @param soft If true, no error is thrown if a node with the given
+ * version doesn't exist. Use soft=true to find a apth to where a new
+ * node should be added.
+ * @return The path
+ * @throws NodeNotFoundException if a node with the given version number
+ * is not reachable following the RCS-next chain from this node.
+ * If soft=false the exception is also thrown if a node with the given
+ * version number doesn't exist.
+ * @see Path
+ */
protected Path pathTo(Version vernum, boolean soft)
throws NodeNotFoundException
{
@@ -315,22 +468,65 @@
}
+ /**
+ * Returns the next node in the path from the current node to the node
+ * identified by the given version.
+ * @param vernum The version number of the last node in the path.
+ * @param soft If true, no error is thrown if a node with the given
+ * version doesn't exist. Use soft=true to find a apth to where a new
+ * node should be added.
+ * @return The path
+ * @throws NodeNotFoundException if a node with the given version number
+ * is not reachable following the RCS-next chain from this node.
+ * If soft=false the exception is also thrown if a node with the given
+ * version number doesn't exist.
+ * @see Path
+ */
protected abstract Node nextInPathTo(Version vernum, boolean soft)
throws NodeNotFoundException;
+
+ /**
+ * Returns the Node with the version number that corresponds to
+ * the revision to be obtained after the deltas in the current node
+ * are applied.
+ * <p>For a {@linkplain BranchNode BranchNode} the deltaRevision is the
+ * current revision; that is, after the deltas are applied, the text for
+ * the current revision is obtained.</p>
+ * <p>For a {@linkplain TrunkNode TrunkNode} the deltaRevision is the
+ * next revision; that is, after the deltas are applied, the text obtained
+ * corresponds to the next revision in the chain.</p>
+ * @return The node for the delta revision.
+ */
protected abstract Node deltaRevision();
+
+ /**
+ * Apply the deltas in the current node to the given text.
+ * @param original the text to be patched
+ * @throws InvalidFileFormatException if the deltas cannot be parsed.
+ * @throws PatchFailedException if the diff engine determines that
+ * the deltas cannot apply to the given text.
+ */
protected void patch(List original)
throws InvalidFileFormatException,
- NodeNotFoundException,
- org.apache.maven.jrcs.diff.PatchFailedException
+ PatchFailedException
{
patch(original, false);
}
+ /**
+ * Apply the deltas in the current node to the given text.
+ * @param original the text to be patched
+ * @param annotate set to true to have each text line be a
+ * {@linkplain Line Line} object that identifies the revision in which
+ * the line was changed or added.
+ * @throws InvalidFileFormatException if the deltas cannot be parsed.
+ * @throws PatchFailedException if the diff engine determines that
+ * the deltas cannot apply to the given text.
+ */
protected void patch(List original, boolean annotate)
throws InvalidFileFormatException,
- NodeNotFoundException,
org.apache.maven.jrcs.diff.PatchFailedException
{
Revision revision = new Revision();
@@ -372,11 +568,26 @@
revision.applyTo(original);
}
+
+ /**
+ * Conver the current node and all of its branches
+ * to their RCS string representation and
+ * add it to the given StringBuffer.
+ * @param s The string buffer to add the node's image to.
+ */
public void toString(StringBuffer s)
{
toString(s, "\n");
}
+ /**
+ * Conver the current node and all of its branches
+ * to their RCS string representation and
+ * add it to the given StringBuffer using the given marker as
+ * line separator.
+ * @param s The string buffer to add the node's image to.
+ * @param EOL The line separator to use.
+ */
public void toString(StringBuffer s, String EOL)
{
String EOI = ";" + EOL;
@@ -433,13 +644,24 @@
}
+ /**
+ * Conver the urrent node to its RCS string representation.
+ * @return The string representation
+ */
protected String toText()
{
final StringBuffer s = new StringBuffer();
- toText(s, "\n");
+ toText(s, Archive.RCS_NEWLINE);
return s.toString();
}
+ /**
+ * Conver the urrent node to its RCS string representation and
+ * add it to the given StringBuffer using the given marker as
+ * line separator.
+ * @param s The string buffer to add the node's image to.
+ * @param EOL The line separator to use.
+ */
protected void toText(StringBuffer s, String EOL)
{
s.append(EOL + EOL);
@@ -471,21 +693,41 @@
}
}
+ /**
+ * Return a list with the lines of the node's text.
+ * @return The list
+ */
protected List getTextLines()
{
return getTextLines(new LinkedList());
}
+ /**
+ * Return a list with a subset of the lines of the node's text.
+ * @param from The offset of the first line to retrieve.
+ * @param to The offset of the line after the last one to retrieve.
+ * @return The list
+ */
protected List getTextLines(int from, int to)
{
return getTextLines(new LinkedList(), from, to);
}
- protected List getTextLines(List lines)
+ /**
+ * Add a subset of the lines of the node's text to the given list.
+ * @return The given list after the additions have been made.
+ */
+ protected List getTextLines(List lines)
{
return getTextLines(lines, 0, _text.length);
}
+ /**
+ * Add a subset of the lines of the node's text to the given list.
+ * @param from The offset of the first line to retrieve.
+ * @param to The offset of the line after the last one to retrieve.
+ * @return The given list after the additions have been made.
+ */
protected List getTextLines(List lines, int from, int to)
{
for (int i = from; i < to; i++)
1.6 +8 -1 jakarta-turbine-maven/src/java/org/apache/maven/jrcs/rcs/TrunkNode.java
Index: TrunkNode.java
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/src/java/org/apache/maven/jrcs/rcs/TrunkNode.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- TrunkNode.java 27 Feb 2002 16:49:49 -0000 1.5
+++ TrunkNode.java 27 Feb 2002 20:05:00 -0000 1.6
@@ -59,13 +59,20 @@
/**
* Represents a node on the trunk or main branch of a version control Archive.
+ *
+ * <p>A {@linkplain TrunkNode TrunkNode} stores the deltas between the node's
+ * revision and the previous revision;
+ * that is, when the deltas are applied to the current revision, the
+ * text of the previous revision is obtained.
+ * The {@linkplain Node._rcsnext rcsnext} field of a TrunkNode
+ * points to the node corresponding to the previous revision.</p>
* This class is NOT thread safe.
*
* @see Node
* @see Archive
*
* @author <a href="mailto:juanco@suigeneris.org">Juanco Anez</a>
- * @version $Id: TrunkNode.java,v 1.5 2002/02/27 16:49:49 juanco Exp $
+ * @version $Id: TrunkNode.java,v 1.6 2002/02/27 20:05:00 juanco Exp $
*/
class TrunkNode
extends Node
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>