juanco 02/02/26 19:37:16 Modified: src/java/org/apache/maven/jrcs/rcs Archive.java Log: added javadoc comments Revision Changes Path 1.12 +260 -7 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.11 retrieving revision 1.12 diff -u -r1.11 -r1.12 --- Archive.java 27 Feb 2002 02:33:26 -0000 1.11 +++ Archive.java 27 Feb 2002 03:37:16 -0000 1.12 @@ -76,6 +76,12 @@ import org.apache.maven.jrcs.diff.DiffException; import org.apache.maven.jrcs.util.ToString; + +/** + * Handling of RCS/CVS version control archives. + * This class is NOT thread safe. + * @author <a href="mailto:[EMAIL PROTECTED]";>Juanco Anez</a> + */ public class Archive extends ToString { @@ -177,17 +183,30 @@ { } - public void setFileName(String name) + /** + * Set the name of the file for this archive + * @param path The full path name. + */ + public void setFileName(String path) { - this.filename = name; + this.filename = path; } + /** + * Save the archive to the provided stream. + * @param output The stream to save the archive to. + */ public void save(OutputStream output) throws IOException { new OutputStreamWriter(output).write(toCharArray()); } + /** + * Save the archive to a file and the the Archives filename + * accordingly. + * @param path The file's path. + */ public void save(String path) throws IOException { @@ -203,6 +222,11 @@ } } + + /** + * Add a head node with the given version number. + * @param vernum The version number to use. + */ protected void setHead(Version vernum) throws InvalidVersionNumberException { if (head != null) @@ -213,11 +237,22 @@ nodes.put(vernum, head); } + + /** + * Set the active branch to the one identified by the given version number. + * Incomplete version numbers of the form "1" or "2.1.3" are accepted. + * @param v The version number. + */ public void setBranch(String v) throws InvalidBranchVersionNumberException { setBranch(new Version(v)); } + + /** + * Set the active branch to the one identified by the given version number. + * @param vernum The version number. + */ public void setBranch(Version vernum) throws InvalidBranchVersionNumberException { if (!vernum.isBranch()) @@ -231,16 +266,31 @@ branch = vernum; } + /** Add a user name to the list of archive users. + * @param name The user name. + */ public void addUser(String name) { users.add(name); } + /** + * Tag a given version with a symbol. + * @param sym The tag. + * @param vernum The version to tag. + */ public void addSymbol(String sym, Version vernum) throws InvalidVersionNumberException { + //@TODO: verify if the symbol is valid, i.e., an identifier. symbols.put(sym, vernum); } + + /** + * Add a lock over a revison. + * @param user The user that locks the revision. + * @param vernum The version number of the revision to lock. + */ public void addLock(String user, Version vernum) throws InvalidVersionNumberException, NodeNotFoundException @@ -258,31 +308,71 @@ } } + + /** + * Set the strict locking flag for the archive. + * @param value Indicates if strict locking should be on or off. + */ public void setStrictLocking(boolean value) { strictLocking = value; } + + /** + * Set the keyword expansion flag for the archive. + * @param value The keyword expansion value. It should be one of: + * <ul> + * <li> kv (Default) Substitue keyword and value. + * <li> kvl Substitue keyword, value, and locker (if any). + * <li> k Substitue keyword only. + * <li> o Preserve original string. + * <li> b Like o, but mark file as binary. + * <li> v Substitue value only. + * </ul> + */ public void setExpand(String value) { expand = value; } + + /** + * Set the archive's comment. + * @param value The comment. + */ public void setComment(String value) { comment = value; } + + /** + * Set the archives description. + * @param value The descriptions text. + */ public void setDesc(String value) { desc = value; } + /** + * Add a new phrase to the archive. + * Phrases are used to provide for extensions of the archive format. + * Each phrase has a key and a list of values associated with it. + * @param key The phrases key. + * @param values The values under the key. + */ public void addPhrase(String key, Collection values) { phrases.put(key, values); } + /** + * Get the archive node associated with a version number. + * @param vernum The version number. + * @return The node, if found. + */ protected Node getNode(Version vernum) throws InvalidVersionNumberException, NodeNotFoundException @@ -362,11 +452,22 @@ return node; } + + /** + * Place a string image of the archive in the given StringBuffer. + * @param s Where the image shoul go. + */ public void toString(StringBuffer s) { toString(s, RCS_NEWLINE); } + + /** + * Return a text image of the archive. + * @param EOL The token to use as line separator. + * @return The text image of the archive. + */ public String toString(String EOL) { StringBuffer s = new StringBuffer(); @@ -374,11 +475,25 @@ return s.toString(); } + /** + * Return a text image of the archive as a char array. + * This is useful for writing the archive to a file without + * having the characters be interpreted by the writer. + * @return The archive image. + */ public char[] toCharArray() { return toString(Archive.RCS_NEWLINE).toCharArray(); } + + /** + * Returns the path from the head node to the node identified + * by the given version number. + * @param vernum The version number that identifies the final node. + * Partial version numbers are OK. + * @return The path to the node, or null if not found. + */ protected Path getRevisionPath(Version vernum) { if (head == null) @@ -405,17 +520,39 @@ } } + /** + * Return the actual revision number of the node identified + * by the given version number. + * @param vernum The version number that identifies the node. + * Partial version numbers are OK. + * @return The actual version, or null if a node is not found. + */ public Version getRevisionVersion(Version vernum) { Path path = getRevisionPath(vernum); return (path == null ? null : path.last().version); } + /** + * Return the actual revision number of the node identified + * by the given version number. + * @param vernum The version number that identifies the node. + * Partial version numbers are OK. + * @return The actual version, or null if a node is not found. + */ public Version getRevisionVersion(String v) { return getRevisionVersion(new Version(v)); } + /** + * Return the actual revision number of the active revision. + * The revision will be the tip of the branch identified as + * active, or the head revision of the trunk if no branch is set + * as active. + * @return The version number of the active revision, or null if + * there is none. + */ public Version getRevisionVersion() { if (branch != null) @@ -432,6 +569,12 @@ } } + /** + * Append a text image of the archive to the given buffer using + * the given token as line separator. + * @param s where to append the image. + * @param EOL the line separator. + */ public void toString(StringBuffer s, String EOL) { String EOI = ";" + EOL; @@ -528,6 +671,13 @@ } } + /** + * Quote a string. + * RCS strings are quoted using @. Any @ in the original + * string is doubled to @@. + * @param s the string to quote. + * @return The string quoted in RCS style. + */ static public String quoteString(String s) { //!!! use org.apache.maven.jrcs.RegExp here !!! @@ -544,11 +694,23 @@ return new String(result); } + /** + * Unquote a 8string quoted in RCS style. + * @param s the quoted string. + * @return s the string unquoted. + */ static public String unquoteString(String s) { return unquoteString(s, true); } + /** + * Unquote a 8string quoted in RCS style. + * @param s the quoted string. + * @param removeExtremes Determines if the enclosing @ quotes + * should be removed. + * @return s the string unquoted. + */ static public String unquoteString(String s, boolean removeExtremes) { //!!! use org.apache.maven.jrcs.RegExp here !!! @@ -573,6 +735,10 @@ return new String(result); } + /** + * Get the text belonging to the head revision. + * @return The text of the head revision + */ public Object[] getRevision() throws InvalidFileFormatException, DiffException, @@ -581,6 +747,13 @@ return getRevision(false); } + /** + * Get the text belonging to the head revision. + * Set annotate to true to have the lines be annotated with the + * number of the revision in which they were added or changed. + * @param annotate set to true to have the text be annotated + * @return The text of the head revision + */ public Object[] getRevision(boolean annotate) throws InvalidFileFormatException, DiffException, @@ -600,6 +773,13 @@ } } + /** + * Get the text belonging to the revision identified by the + * given version number. + * Partial version numbers are OK. + * @param v the version number. + * @return The text of the revision if found. + */ public Object[] getRevision(String v) throws InvalidFileFormatException, PatchFailedException, @@ -609,6 +789,16 @@ return getRevision(v, false); } + /** + * Get the text belonging to the revision identified by the + * given version number. + * Partial version numbers are OK. + * Set annotate to true to have the lines be annotated with the + * number of the revision in which they were added or changed. + * @param v the version number. + * @param annotate set to true to have the text be annotated + * @return The text of the revision if found. + */ public Object[] getRevision(String v, boolean annotate) throws InvalidVersionNumberException, NodeNotFoundException, @@ -618,6 +808,13 @@ return getRevision(new Version(v), annotate); } + /** + * Get the text belonging to the revision identified by the + * given version number. + * Partial version numbers are OK. + * @param vernum the version number. + * @return The text of the revision if found. + */ public Object[] getRevision(Version vernum) throws InvalidFileFormatException, PatchFailedException, @@ -626,6 +823,16 @@ return getRevision(vernum, false); } + /** + * Get the text belonging to the revision identified by the + * given version number. + * Partial version numbers are OK. + * Set annotate to true to have the lines be annotated with the + * number of the revision in which they were added or changed. + * @param vernum the version number. + * @param annotate set to true to have the text be annotated + * @return The text of the revision if found. + */ public Object[] getRevision(Version vernum, boolean annotate) throws InvalidFileFormatException, PatchFailedException, @@ -643,6 +850,12 @@ return doKeywords(lines.toArray(), revisionFound); } + /** + * Add the given revision to the active branch on the archive. + * @param text the text of the revision. + * @param log the log: a short note explaining what the revision is. + * @return The version number assigned to the revision. + */ public Version addRevision(Object[] text, String log) throws InvalidFileFormatException, DiffException, @@ -659,6 +872,18 @@ } } + /** + * Add the given revision to the the archive using the given version + * number. + * The version number may be partial. If so, the rules used by RCS/CVS + * are used to decide which branch the revision should be added to. A + * new branch may be created if required. + * @param text the text of the revision. + * @param vernum is the version number wanted, or, if partial, identifies + * the target branch. + * @param log the log: a short note explaining what the revision is. + * @return The version number assigned to the revision. + */ public Version addRevision(Object[] text, String vernum, String log) throws InvalidFileFormatException, DiffException, @@ -668,6 +893,18 @@ return addRevision(text, new Version(vernum), log); } + /** + * Add the given revision to the the archive using the given version + * number. + * The version number may be partial. If so, the rules used by RCS/CVS + * are used to decide which branch the revision should be added to. A + * new branch may be created if required. + * @param text the text of the revision. + * @param vernum is the version number wanted, or, if partial, identifies + * the target branch. + * @param log the log: a short note explaining what the revision is. + * @return The version number assigned to the revision. + */ public Version addRevision(Object[] text, Version vernum, String log) throws InvalidFileFormatException, DiffException, @@ -676,7 +913,7 @@ { if (head == null) { - throw new IllegalStateException("no _head node"); + throw new IllegalStateException("no head node"); } Path path = head.pathTo(vernum, true); @@ -749,9 +986,21 @@ return newNode.version; } + + /** + * Returns the given text with values added to CVS-style keywords. + * @param text the text on which substitutions will be applied. + * @param rev a node that identifies the revision to which the + * given text belongs. + * @return the text with substitutions performed. + */ public Object[] doKeywords(Object[] text, Node rev) throws PatchFailedException { + + //!!! this is used specifically for the way + //!!! in which the keyword replacer works. Should be moved there. + //!!! Write a Format.format(Object[], Node rev) instead. Object[] revisionInfo = new Object[]{ filename, new File(filename).getName(), @@ -765,20 +1014,24 @@ Object[] result = new Object[text.length]; for (int i = 0; i < text.length; i++) { - String s = text[i].toString(); - result[i] = FORMATTER.format(s, revisionInfo); + result[i] = FORMATTER.format(text[i].toString(), revisionInfo); } return result; } + /** + * Returns the given text removing the values of any CVS-style + * keywords. + * @param text the text on which substitutions will be applied. + * @return the text with substitutions performed. + */ protected static Object[] removeKeywords(Object[] text) throws PatchFailedException { Object[] result = new Object[text.length]; for (int i = 0; i < text.length; i++) { - String s = text[i].toString(); - result[i] = FORMATTER.reset(s); + result[i] = FORMATTER.reset(text[i].toString()); } return result; }
-- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
