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/03/03 20:59:44 UTC
cvs commit: jakarta-turbine-maven/src/java/org/apache/maven/jrcs/diff AddDelta.java ChangeDelta.java Chunk.java DeleteDelta.java Delta.java Diff.java DifferentiationFailedException.java PatchFailedException.java Range.java Revision.java
juanco 02/03/03 11:59:44
Modified: src/java/org/apache/maven/jrcs/diff AddDelta.java
ChangeDelta.java Chunk.java DeleteDelta.java
Delta.java Diff.java
DifferentiationFailedException.java
PatchFailedException.java Range.java Revision.java
Log:
added more of the missing javadoc documentation
Revision Changes Path
1.5 +9 -1 jakarta-turbine-maven/src/java/org/apache/maven/jrcs/diff/AddDelta.java
Index: AddDelta.java
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/src/java/org/apache/maven/jrcs/diff/AddDelta.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- AddDelta.java 23 Feb 2002 13:39:09 -0000 1.4
+++ AddDelta.java 3 Mar 2002 19:59:44 -0000 1.5
@@ -55,7 +55,15 @@
*/
import java.util.List;
-
+/**
+ * Holds an add-delta between to revisions of a text.
+ *
+ * @version $Id: AddDelta.java,v 1.5 2002/03/03 19:59:44 juanco Exp $
+ * @author <a href="mailto:juanco@suigeneris.org">Juanco Anez</a>
+ * @see Delta
+ * @see Diff
+ * @see Chunk
+ */
public class AddDelta extends Delta
{
1.5 +9 -0 jakarta-turbine-maven/src/java/org/apache/maven/jrcs/diff/ChangeDelta.java
Index: ChangeDelta.java
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/src/java/org/apache/maven/jrcs/diff/ChangeDelta.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- ChangeDelta.java 23 Feb 2002 13:39:09 -0000 1.4
+++ ChangeDelta.java 3 Mar 2002 19:59:44 -0000 1.5
@@ -56,6 +56,15 @@
import java.util.List;
+/**
+ * Holds an change-delta between to revisions of a text.
+ *
+ * @version $Id: ChangeDelta.java,v 1.5 2002/03/03 19:59:44 juanco Exp $
+ * @author <a href="mailto:juanco@suigeneris.org">Juanco Anez</a>
+ * @see Delta
+ * @see Diff
+ * @see Chunk
+ */
public class ChangeDelta extends Delta
{
1.5 +125 -26 jakarta-turbine-maven/src/java/org/apache/maven/jrcs/diff/Chunk.java
Index: Chunk.java
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/src/java/org/apache/maven/jrcs/diff/Chunk.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- Chunk.java 23 Feb 2002 13:39:09 -0000 1.4
+++ Chunk.java 3 Mar 2002 19:59:44 -0000 1.5
@@ -61,96 +61,165 @@
import java.util.List;
/**
- * Produces the "Chunk" differences between two sequences
+ * Holds a information about a parrt of the text involved in
+ * a differencing or patching operation.
*
- * @version $Revision: 1.4 $
- * @author Juancarlo A�ez
- * @see org.apache.maven.jrcs.diff.Diff
+ * @version $Id: Chunk.java,v 1.5 2002/03/03 19:59:44 juanco Exp $
+ * @author <a href="mailto:juanco@suigeneris.org">Juanco Anez</a>
+ * @see Diff
+ * @see Delta
*/
-
public class Chunk
extends org.apache.maven.jrcs.util.ToString
{
- protected int _anchor;
+ protected int anchor;
- protected int _count;
+ protected int count;
- protected List _chunk;
+ protected List chunk;
+ /**
+ * Creates a chunk that doesn't copy the original text.
+ * @param pos the start position in the text.
+ * @param count the size of the chunk.
+ */
public Chunk(int pos, int count)
{
- this._anchor = pos;
- this._count = (count >= 0 ? count : 0);
+ this.anchor = pos;
+ this.count = (count >= 0 ? count : 0);
}
+ /**
+ * Creates a chunk and saves a copy the original chunk's text.
+ * @param iseq the original text.
+ * @param pos the start position in the text.
+ * @param count the size of the chunk.
+ */
public Chunk(Object[] iseq, int pos, int count)
{
this(pos, count);
- _chunk = slice(iseq, pos, count);
+ chunk = slice(iseq, pos, count);
}
+ /**
+ * Creates a chunk that will be displaced in the resulting text,
+ * and saves a copy the original chunk's text.
+ * @param iseq the original text.
+ * @param pos the start position in the text.
+ * @param count the size of the chunk.
+ * @param offset the position the chunk should have in the resulting text.
+ */
public Chunk(Object[] iseq, int pos, int count, int offset)
{
this(offset, count);
- _chunk = slice(iseq, pos, count);
+ chunk = slice(iseq, pos, count);
}
+ /**
+ * Creates a chunk and saves a copy the original chunk's text.
+ * @param iseq the original text.
+ * @param pos the start position in the text.
+ * @param count the size of the chunk.
+ */
public Chunk(List iseq, int pos, int count)
{
this(pos, count);
- _chunk = slice(iseq, pos, count);
+ chunk = slice(iseq, pos, count);
}
+ /**
+ * Creates a chunk that will be displaced in the resulting text,
+ * and saves a copy the original chunk's text.
+ * @param iseq the original text.
+ * @param pos the start position in the text.
+ * @param count the size of the chunk.
+ * @param offset the position the chunk should have in the resulting text.
+ */
public Chunk(List iseq, int pos, int count, int offset)
{
this(offset, count);
- _chunk = slice(iseq, pos, count);
+ chunk = slice(iseq, pos, count);
}
+ /**
+ * Returns the anchor position of the chunk.
+ * @return the anchor position.
+ */
public int anchor()
{
- return _anchor;
+ return anchor;
}
+ /**
+ * Returns the size of the chunk.
+ * @return the size.
+ */
public int size()
{
- return _count;
+ return count;
}
+ /**
+ * Returns the index of the first line of the chunk.
+ */
public int first()
{
return anchor();
}
+ /**
+ * Returns the index of the last line of the chunk.
+ */
public int last()
{
return anchor() + size() - 1;
}
+ /**
+ * Returns the <i>from</i> index of the chunk in delta terms.
+ */
public int extfrom()
{
- return _anchor + 1;
+ return anchor + 1;
}
+ /**
+ * Returns the <i>to</i> index of the chunk in delta terms.
+ */
public int extto()
{
- return _anchor + _count;
+ return anchor + count;
}
+ /**
+ * Returns a {@link Range Range} object that describes the
+ * scope covered by this chunk.
+ */
public Range range()
{
return new Range(first(), last());
}
+
+ /**
+ * Returns the text saved for this chunk.
+ * @return the text.
+ */
public List chunk()
{
- return _chunk;
+ return chunk;
}
+ /**
+ * Verifies that this chunk's saved text matches the corresponding
+ * text in the given sequence.
+ * @param target the sequence to verify against.
+ * @return true if the texts match.
+ */
public boolean verify(List target)
{
- if (_chunk == null)
+ if (chunk == null)
{
return true;
}
@@ -158,9 +227,9 @@
{
return false;
}
- for (int i = 0; i < _count; i++)
+ for (int i = 0; i < count; i++)
{
- if (!target.get(_anchor + i).equals(_chunk.get(i)))
+ if (!target.get(anchor + i).equals(chunk.get(i)))
{
return false;
}
@@ -168,6 +237,10 @@
return true;
}
+ /**
+ * Delete this chunk from he given text.
+ * @param target the text to delete from.
+ */
public void applyDelete(List target)
{
for (int i = last(); i >= first(); i--)
@@ -175,10 +248,15 @@
target.remove(i);
}
}
-
+
+ /**
+ * Add the text of this chunk to the target at the given position.
+ * @param start where to add the text.
+ * @param target the text to add to.
+ */
public void applyAdd(int start, List target)
{
- Iterator i = _chunk.iterator();
+ Iterator i = chunk.iterator();
while (i.hasNext())
{
target.add(start++, i.next());
@@ -191,11 +269,18 @@
}
+ /**
+ * Provide a string image of the chunk using the given prefix and
+ * postfix.
+ * @param s where the string image should be appended.
+ * @param prefix the text thatshould prefix each line.
+ * @param postfix the text that should end each line.
+ */
public StringBuffer toString(StringBuffer s, String prefix, String postfix)
{
- if (_chunk != null)
+ if (chunk != null)
{
- Iterator i = _chunk.iterator();
+ Iterator i = chunk.iterator();
while (i.hasNext())
{
s.append(prefix);
@@ -206,6 +291,13 @@
return s;
}
+ /**
+ * Retreives the specified part from a {@link List List}.
+ * @param seq the list to retreive a slice from.
+ * @param pos the start position.
+ * @param count the number of items in the slice.
+ * @return a {@link List List} containing the specified items.
+ */
public static List slice(List seq, int pos, int count)
{
if (count <= 0)
@@ -218,6 +310,13 @@
}
}
+ /**
+ * Retrieves a slice from an {@link Object Object} array.
+ * @param seq the list to retreive a slice from.
+ * @param pos the start position.
+ * @param count the number of items in the slice.
+ * @return a {@link List List} containing the specified items.
+ */
public static List slice(Object[] seq, int pos, int count)
{
return slice(Arrays.asList(seq), pos, count);
1.5 +9 -0 jakarta-turbine-maven/src/java/org/apache/maven/jrcs/diff/DeleteDelta.java
Index: DeleteDelta.java
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/src/java/org/apache/maven/jrcs/diff/DeleteDelta.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- DeleteDelta.java 23 Feb 2002 13:39:09 -0000 1.4
+++ DeleteDelta.java 3 Mar 2002 19:59:44 -0000 1.5
@@ -58,6 +58,15 @@
import java.util.List;
+/**
+ * Holds a delete-delta between to revisions of a text.
+ *
+ * @version $Id: DeleteDelta.java,v 1.5 2002/03/03 19:59:44 juanco Exp $
+ * @author <a href="mailto:juanco@suigeneris.org">Juanco Anez</a>
+ * @see Delta
+ * @see Diff
+ * @see Chunk
+ */
public class DeleteDelta extends Delta
{
1.5 +53 -5 jakarta-turbine-maven/src/java/org/apache/maven/jrcs/diff/Delta.java
Index: Delta.java
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/src/java/org/apache/maven/jrcs/diff/Delta.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- Delta.java 23 Feb 2002 13:39:09 -0000 1.4
+++ Delta.java 3 Mar 2002 19:59:44 -0000 1.5
@@ -57,11 +57,12 @@
import java.util.List;
/**
- * Produces the "delta" differences between two sequences
+ * Holds a "delta" difference between to revisions of a text.
*
- * @version 0.1 96/11/07
- * @author Juancarlo A�ez
- * @see org.apache.maven.jrcs.diff.Diff
+ * @version $Id: Delta.java,v 1.5 2002/03/03 19:59:44 juanco Exp $
+ * @author <a href="mailto:juanco@suigeneris.org">Juanco Anez</a>
+ * @see Diff
+ * @see Chunk
*/
public abstract class Delta
@@ -93,6 +94,12 @@
}
+ /**
+ * Returns a Delta that corresponds to the given chunks in the
+ * original and revised text respectively.
+ * @param orig the chunk in the original text.
+ * @param rev the chunk in the revised text.
+ */
public static Delta newDelta(Chunk orig, Chunk rev)
{
Class c = DeltaClass[orig.size() > 0 ? 1 : 0]
@@ -111,18 +118,28 @@
return result;
}
-
+ /**
+ * Creates an uninitialized delta.
+ */
protected Delta()
{
}
+ /**
+ * Creates a delta object with the given chunks from the original
+ * and revised texts.
+ */
protected Delta(Chunk orig, Chunk rev)
{
init(orig, rev);
}
+ /**
+ * Initializaes the delta with the given chunks from the original
+ * and revised texts.
+ */
protected void init(Chunk orig, Chunk rev)
{
original = orig;
@@ -130,8 +147,18 @@
}
+ /**
+ * Verifies that this delta can be used to patch the given text.
+ * @param target the text to patch.
+ * @throws PatchFailedException if the patch cannot be applied.
+ */
public abstract void verify(List target) throws PatchFailedException;
+ /**
+ * Applies this delta as a patch to the given text.
+ * @param target the text to patch.
+ * @throws PatchFailedException if the patch cannot be applied.
+ */
public final void patch(List target) throws PatchFailedException
{
verify(target);
@@ -145,8 +172,19 @@
}
}
+ /**
+ * Applies this delta as a patch to the given text.
+ * @param target the text to patch.
+ * @throws PatchFailedException if the patch cannot be applied.
+ */
public abstract void applyTo(List target);
+
+ /**
+ * Converts this delta into its Unix diff style string representation.
+ * @param s a {@link StringBuffer StringBuffer} to which the string
+ * representation will be appended.
+ */
public void toString(StringBuffer s)
{
original.range().toString(s);
@@ -159,8 +197,18 @@
revised.toString(s, "< ", "\n");
}
+ /**
+ * Converts this delta into its RCS style string representation.
+ * @param s a {@link StringBuffer StringBuffer} to which the string
+ * representation will be appended.
+ * @param EOL the string to use as line separator.
+ */
public abstract void toRCSString(StringBuffer s, String EOL);
+ /**
+ * Converts this delta into its RCS style string representation.
+ * @param EOL the string to use as line separator.
+ */
public String toRCSString(String EOL)
{
StringBuffer s = new StringBuffer();
1.9 +2 -2 jakarta-turbine-maven/src/java/org/apache/maven/jrcs/diff/Diff.java
Index: Diff.java
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/src/java/org/apache/maven/jrcs/diff/Diff.java,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- Diff.java 3 Mar 2002 19:12:32 -0000 1.8
+++ Diff.java 3 Mar 2002 19:59:44 -0000 1.9
@@ -81,9 +81,9 @@
* correctly can be subject to differencing using this
* library.</p>
*
- * @version $Revision: 1.8 $ $Date: 2002/03/03 19:12:32 $
+ * @version $Revision: 1.9 $ $Date: 2002/03/03 19:59:44 $
* @author <a href="mailto:juanco@suigeneris.org">Juanco Anez</a>
- * @see org.apache.maven.jrcs.diff.Delta
+ * @see Delta
*/
public class Diff
1.5 +8 -0 jakarta-turbine-maven/src/java/org/apache/maven/jrcs/diff/DifferentiationFailedException.java
Index: DifferentiationFailedException.java
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/src/java/org/apache/maven/jrcs/diff/DifferentiationFailedException.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- DifferentiationFailedException.java 23 Feb 2002 13:39:09 -0000 1.4
+++ DifferentiationFailedException.java 3 Mar 2002 19:59:44 -0000 1.5
@@ -54,6 +54,14 @@
* <http://www.apache.org/>.
*/
+/**
+ * Thrown whenever the differencing engine cannot produce the differences
+ * between two revisions of ta text.
+ *
+ * @version $Id: DifferentiationFailedException.java,v 1.5 2002/03/03 19:59:44 juanco Exp $
+ * @author <a href="mailto:juanco@suigeneris.org">Juanco Anez</a>
+ * @see Diff
+ */
public class DifferentiationFailedException extends DiffException
{
1.5 +8 -0 jakarta-turbine-maven/src/java/org/apache/maven/jrcs/diff/PatchFailedException.java
Index: PatchFailedException.java
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/src/java/org/apache/maven/jrcs/diff/PatchFailedException.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- PatchFailedException.java 23 Feb 2002 13:39:09 -0000 1.4
+++ PatchFailedException.java 3 Mar 2002 19:59:44 -0000 1.5
@@ -54,6 +54,14 @@
* <http://www.apache.org/>.
*/
+/**
+ * Thrown whenever a delta cannot be applied as a patch to a given text.
+ *
+ * @version $Id: PatchFailedException.java,v 1.5 2002/03/03 19:59:44 juanco Exp $
+ * @author <a href="mailto:juanco@suigeneris.org">Juanco Anez</a>
+ * @see Delta
+ * @see Diff
+ */
public class PatchFailedException extends DiffException
{
1.5 +5 -4 jakarta-turbine-maven/src/java/org/apache/maven/jrcs/diff/Range.java
Index: Range.java
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/src/java/org/apache/maven/jrcs/diff/Range.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- Range.java 23 Feb 2002 13:39:09 -0000 1.4
+++ Range.java 3 Mar 2002 19:59:44 -0000 1.5
@@ -57,11 +57,12 @@
import org.apache.maven.jrcs.util.ToString;
/**
- * Produces the "Range" differences between two sequences
+ * Holds a information about a range of lines in a text.
*
- * @version 0.1 96/11/07
- * @author Juancarlo A�ez
- * @see org.apache.maven.jrcs.diff.Diff
+ * @version $Id: Range.java,v 1.5 2002/03/03 19:59:44 juanco Exp $
+ * @author <a href="mailto:juanco@suigeneris.org">Juanco Anez</a>
+ * @see Diff
+ * @see Chunk
*/
public class Range
extends ToString
1.5 +64 -0 jakarta-turbine-maven/src/java/org/apache/maven/jrcs/diff/Revision.java
Index: Revision.java
===================================================================
RCS file: /home/cvs/jakarta-turbine-maven/src/java/org/apache/maven/jrcs/diff/Revision.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- Revision.java 23 Feb 2002 13:39:09 -0000 1.4
+++ Revision.java 3 Mar 2002 19:59:44 -0000 1.5
@@ -64,17 +64,35 @@
import org.apache.maven.jrcs.util.ToString;
+/**
+ * A Revision holds the series of deltas that describe the differences
+ * between to revisions of a text.
+ *
+ * @version $Id: Revision.java,v 1.5 2002/03/03 19:59:44 juanco Exp $
+ * @author <a href="mailto:juanco@suigeneris.org">Juanco Anez</a>
+ * @see Delta
+ * @see Diff
+ * @see Chunk
+ */
public class Revision
extends ToString
{
List deltas_ = new LinkedList();
+
+ /**
+ * Creates an empty Revision.
+ */
public Revision()
{
}
+ /**
+ * Adds a delta to this revision.
+ * @param delta the {@link Delta Delta} to add.
+ */
public synchronized void addDelta(Delta delta)
{
if (delta == null)
@@ -98,16 +116,32 @@
deltas_.add(delta);
}
+
+ /**
+ * Retrieves a delta from this revision by position.
+ * @param i the position of the delta to retrieve.
+ * @return the specified delta
+ */
public Delta getDelta(int i)
{
return (Delta) deltas_.get(i);
}
+ /**
+ * Returns the number of deltas in this revision.
+ */
public int size()
{
return deltas_.size();
}
+ /**
+ * Applies the series of deltas in this revision as patches to
+ * the given text.
+ * @param src the text to patch, which the method doesn't change.
+ * @return the resulting text after the patches have been applied.
+ * @throws PatchFailedException if any of the patches cannot be applied.
+ */
public Object[] patch(Object[] src) throws PatchFailedException
{
List target = new ArrayList(Arrays.asList(src));
@@ -115,6 +149,12 @@
return target.toArray();
}
+ /**
+ * Applies the series of deltas in this revision as patches to
+ * the given text.
+ * @param target the text to patch.
+ * @throws PatchFailedException if any of the patches cannot be applied.
+ */
public synchronized void applyTo(List target) throws PatchFailedException
{
ListIterator i = deltas_.listIterator(deltas_.size());
@@ -125,6 +165,11 @@
}
}
+ /**
+ * Converts this revision into its Unix diff style string representation.
+ * @param s a {@link StringBuffer StringBuffer} to which the string
+ * representation will be appended.
+ */
public synchronized void toString(StringBuffer s)
{
Iterator i = deltas_.iterator();
@@ -134,6 +179,12 @@
}
}
+ /**
+ * Converts this revision into its RCS style string representation.
+ * @param s a {@link StringBuffer StringBuffer} to which the string
+ * representation will be appended.
+ * @param EOL the string to use as line separator.
+ */
public synchronized void toRCSString(StringBuffer s, String EOL)
{
Iterator i = deltas_.iterator();
@@ -143,11 +194,20 @@
}
}
+ /**
+ * Converts this revision into its RCS style string representation.
+ * @param s a {@link StringBuffer StringBuffer} to which the string
+ * representation will be appended.
+ */
public void toRCSString(StringBuffer s)
{
toRCSString(s, Diff.NL);
}
+ /**
+ * Converts this delta into its RCS style string representation.
+ * @param EOL the string to use as line separator.
+ */
public String toRCSString(String EOL)
{
StringBuffer s = new StringBuffer();
@@ -155,6 +215,10 @@
return s.toString();
}
+ /**
+ * Converts this delta into its RCS style string representation
+ * using the default line separator.
+ */
public String toRCSString()
{
return toRCSString(Diff.NL);
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>