org.apache.commons.jrcs.rcs
Class Archive

java.lang.Object
  extended by org.apache.commons.jrcs.util.ToString
      extended by org.apache.commons.jrcs.rcs.Archive

public class Archive
extends ToString

Handling of RCS/CVS style version control archives.

JRCS is a library that knows how to manipulate the archive files produced by the RCS and CVS version control systems. JRCS is not intended to replace neither tool. JRCS was written to be able create archive analysis tools that can do things like identify hot spots in the source code, measure the contributions by each developer, or assess how bugs make it in.

The reasons why JRCS has the ability do do check-ins and save archives is API symmetry, and to simplify the writing of unit tests.

CAVEAT UTILITOR: Do not make modifications to your archives with JRCS. There needs to be an important amount of additional testing before it's safe to do that.

The rcs package implements the archive handling functionality. The entry point to the library is class Archive.

The diff package implements the differencing engine that JRCS uses. The engine has the power of Unix diff, is simple to understand, and can be used independently of the archive handling functionality. The entry point to the differencing engine is class Diff.

Within this library, the word text means a unit of information subject to version control. The word revision means a particular version of a text. Each revision has a version number associated to it. Version numbers are dot-separated lists of numbers. Version numbers with an odd number of dots indicate revisions, while those with an even number of dots (including zero dots) designate branches.

Revisions of a text are represented as Object[] because the diff engine is capable of handling more than plain text. In fact, arrays of any type that implements hashCode() and equals() correctly can be subject to differencing and version control using this library.

To create an empty archive use:

   Archive archive = new Archive();
 

To read an archive from the file system, use:

   Archive archive = new Archive("/path/to/archive,v");
 

You can also initialize archives from streams.

To retreive a revision from an archive use:

   String versionNumber = "1.2";
   Object[] text = archive.getRevision(versionNumber);
 

You can also retreive revisions in such a way that each item is annotated with the version number of the revision in which it was last changed or added. To retrieve annotated text use:

   String versionNumber = "1.2";
   Line[] text = archive.getRevision(versionNumber);
   for(int i = 0; i < text.length(); i++)
       System.out.println(text[i].revision.version);
 

This class is NOT thread safe.

Version:
$Id: Archive.java 69 2003-10-13 08:00:44Z rdonkin $
Author:
Juanco Anez
See Also:
org.apache.commons.jrcs.diff

Field Summary
protected  Version branch
           
protected  java.lang.String comment
           
protected  java.lang.String desc
           
protected  java.lang.String expand
           
protected  java.lang.String filename
           
protected  org.apache.commons.jrcs.rcs.TrunkNode head
           
protected  java.util.Set locked
           
protected  java.util.Map nodes
           
protected  org.apache.commons.jrcs.rcs.Phrases phrases
           
static java.lang.String RCS_NEWLINE
           
protected  boolean strictLocking
           
protected  java.util.Map symbols
           
protected  java.util.Set users
           
 
Constructor Summary
Archive(java.lang.Object[] text, java.lang.String desc)
          Creates a new archive and sets the text of the initial revision.
Archive(java.lang.Object[] text, java.lang.String desc, java.lang.String vernum)
          Creates a new archive with the specified initial version number and sets the text of the initial revision.
Archive(java.lang.Object[] text, java.lang.String desc, Version vernum)
          Creates a new archive with the specified initial version number and sets the text of the initial revision.
Archive(java.lang.String path)
          Load an archive from an a file given by name.
Archive(java.lang.String fname, java.io.InputStream input)
          Load an archive from an input stream.
 
Method Summary
 void addLock(java.lang.String user, Version vernum)
          Add a lock over a revison.
 void addPhrase(java.lang.String key, java.util.Collection values)
          Add a new phrase to the archive.
 Version addRevision(java.lang.Object[] text, java.lang.String log)
          Add the given revision to the active branch on the archive.
 Version addRevision(java.lang.Object[] text, java.lang.String vernum, java.lang.String log)
          Add the given revision to the the archive using the given version number.
 Version addRevision(java.lang.Object[] text, Version vernum, java.lang.String log)
          Add the given revision to the the archive using the given version number.
 void addSymbol(java.lang.String sym, Version vernum)
          Tag a given version with a symbol.
 void addUser(java.lang.String name)
          Add a user name to the list of archive users.
 Node[] changeLog()
          Return the list of nodes between the head revision and the root revision.
 Node[] changeLog(Version latest)
          Return the list of nodes between the the given revision and the root revision.
 Node[] changeLog(Version latest, Version earliest)
          Return the list of nodes between the the given two revisions.
 java.lang.Object[] doKeywords(java.lang.Object[] text, Node rev)
          Returns the given text with values added to CVS-style keywords.
 Node findNode(Version vernum)
          Return the node with the version number that matches the one provided.
 java.lang.String getDesc()
          Returns the description associated with the archive.
 java.lang.String getLog(java.lang.String vernum)
          Returns the log message associated with the given revision.
 java.lang.String getLog(Version version)
          Returns the log message associated with the given revision.
protected  Node getNode(Version vernum)
           
 java.lang.Object[] getRevision()
          Get the text belonging to the head revision.
 java.lang.Object[] getRevision(boolean annotate)
          Get the text belonging to the head revision.
 java.lang.Object[] getRevision(java.lang.String vernum)
          Get the text belonging to the revision identified by the given version number.
 java.lang.Object[] getRevision(java.lang.String vernum, boolean annotate)
          Get the text belonging to the revision identified by the given version number.
 java.lang.Object[] getRevision(Version vernum)
          Get the text belonging to the revision identified by the given version number.
 java.lang.Object[] getRevision(Version vernum, boolean annotate)
          Get the text belonging to the revision identified by the given version number.
protected  org.apache.commons.jrcs.rcs.Path getRevisionPath(Version vernum)
          Returns the path from the head node to the node identified by the given version number.
 Version getRevisionVersion()
          Return the actual revision number of the active revision.
 Version getRevisionVersion(java.lang.String vernum)
          Return the actual revision number of the node identified by the given version number.
 Version getRevisionVersion(Version vernum)
          Return the actual revision number of the node identified by the given version number.
 java.util.Map getSymbols()
          Returns a Map of the symbols (tags) associated with each revision.
protected  org.apache.commons.jrcs.rcs.BranchNode newBranchNode(Version vernum)
           
protected  Node newNode(Version vernum)
           
protected  Node newNode(Version vernum, Node prev)
           
protected  org.apache.commons.jrcs.rcs.TrunkNode newTrunkNode(Version vernum)
           
static java.lang.String quoteString(java.lang.String s)
          Quote a string.
protected static java.lang.Object[] removeKeywords(java.lang.Object[] text)
          Returns the given text removing the values of any CVS-style keywords.
 void save(java.io.OutputStream output)
          Save the archive to the provided stream.
 void save(java.lang.String path)
          Save the archive to a file and the the Archives filename accordingly.
 void setBranch(java.lang.String v)
          Set the active branch to the one identified by the given version number.
 void setBranch(Version vernum)
          Set the active branch to the one identified by the given version number.
 void setComment(java.lang.String value)
          Set the archive's comment.
 void setDesc(java.lang.String value)
          Set the archives description.
 void setExpand(java.lang.String value)
          Set the keyword expansion flag for the archive.
 void setFileName(java.lang.String path)
          Set the name of the file for this archive
protected  void setHead(Version vernum)
          Add a head node with the given version number.
 void setStrictLocking(boolean value)
          Set the strict locking flag for the archive.
 byte[] toByteArray()
          Return a text image of the archive as a char array.
 char[] toCharArray()
          Return a text image of the archive as a char array.
 java.lang.String toString(java.lang.String EOL)
          Return a text image of the archive.
 void toString(java.lang.StringBuffer s)
          Place a string image of the archive in the given StringBuffer.
 void toString(java.lang.StringBuffer s, java.lang.String EOL)
          Append a text image of the archive to the given buffer using the given token as line separator.
static java.lang.String unquoteString(java.lang.String s)
          Unquote a string quoted in RCS style.
static java.lang.String unquoteString(java.lang.String s, boolean removeExtremes)
          Unquote a string quoted in RCS style.
 
Methods inherited from class org.apache.commons.jrcs.util.ToString
arrayToString, arrayToString, stringToArray, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

RCS_NEWLINE

public static final java.lang.String RCS_NEWLINE
See Also:
Constant Field Values

head

protected org.apache.commons.jrcs.rcs.TrunkNode head

branch

protected Version branch

nodes

protected java.util.Map nodes

users

protected java.util.Set users

locked

protected java.util.Set locked

symbols

protected java.util.Map symbols

phrases

protected org.apache.commons.jrcs.rcs.Phrases phrases

desc

protected java.lang.String desc

strictLocking

protected boolean strictLocking

expand

protected java.lang.String expand

comment

protected java.lang.String comment

filename

protected java.lang.String filename
Constructor Detail

Archive

public Archive(java.lang.Object[] text,
               java.lang.String desc)
Creates a new archive and sets the text of the initial revision.

Parameters:
text - The text of the initial revision.
desc - The archives description (not the log message).

Archive

public Archive(java.lang.Object[] text,
               java.lang.String desc,
               java.lang.String vernum)
Creates a new archive with the specified initial version number and sets the text of the initial revision. The initial revision must be of the form "n.m" (i.e. a trunk revision).

Parameters:
text - The text of the initial revision.
desc - The archives description (not the log message).
vernum - The initial revision number.

Archive

public Archive(java.lang.Object[] text,
               java.lang.String desc,
               Version vernum)
Creates a new archive with the specified initial version number and sets the text of the initial revision. The initial revision must be of the form "n.m" (i.e. a trunk revision).

Parameters:
text - The text of the initial revision.
desc - The archives description (not the log message).
vernum - The initial revision number.

Archive

public Archive(java.lang.String fname,
               java.io.InputStream input)
        throws ParseException
Load an archive from an input stream. Parses the archive given by the input stream, and gives it the provided name.

Parameters:
fname - The name to give to the archive.
input - Where to read the archive from
Throws:
ParseException

Archive

public Archive(java.lang.String path)
        throws ParseException,
               java.io.FileNotFoundException
Load an archive from an a file given by name.

Parameters:
path - The path to the file wher the archive resides.
Throws:
ParseException
java.io.FileNotFoundException
Method Detail

setFileName

public void setFileName(java.lang.String path)
Set the name of the file for this archive

Parameters:
path - The full path name.

save

public void save(java.io.OutputStream output)
          throws java.io.IOException
Save the archive to the provided stream.

Parameters:
output - The stream to save the archive to.
Throws:
java.io.IOException

save

public void save(java.lang.String path)
          throws java.io.IOException
Save the archive to a file and the the Archives filename accordingly.

Parameters:
path - The file's path.
Throws:
java.io.IOException

setHead

protected void setHead(Version vernum)
                throws InvalidVersionNumberException
Add a head node with the given version number.

Parameters:
vernum - The version number to use.
Throws:
InvalidVersionNumberException

setBranch

public void setBranch(java.lang.String v)
               throws InvalidBranchVersionNumberException
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.

Parameters:
v - The version number.
Throws:
InvalidBranchVersionNumberException

setBranch

public void setBranch(Version vernum)
               throws InvalidBranchVersionNumberException
Set the active branch to the one identified by the given version number.

Parameters:
vernum - The version number.
Throws:
InvalidBranchVersionNumberException

addUser

public void addUser(java.lang.String name)
Add a user name to the list of archive users.

Parameters:
name - The user name.

addSymbol

public void addSymbol(java.lang.String sym,
                      Version vernum)
               throws InvalidVersionNumberException
Tag a given version with a symbol.

Parameters:
sym - The tag.
vernum - The version to tag.
Throws:
InvalidVersionNumberException

getSymbols

public java.util.Map getSymbols()
Returns a Map of the symbols (tags) associated with each revision. The symbols are the keys and the revision numbers are the values.

Returns:
A map of symbol/revision number pairs.

addLock

public void addLock(java.lang.String user,
                    Version vernum)
             throws InvalidVersionNumberException,
                    NodeNotFoundException
Add a lock over a revison.

Parameters:
user - The user that locks the revision.
vernum - The version number of the revision to lock.
Throws:
InvalidVersionNumberException
NodeNotFoundException

setStrictLocking

public void setStrictLocking(boolean value)
Set the strict locking flag for the archive.

Parameters:
value - Indicates if strict locking should be on or off.

setExpand

public void setExpand(java.lang.String value)
Set the keyword expansion flag for the archive.

Parameters:
value - The keyword expansion value. It should be one of:
  • kv (Default) Substitue keyword and value.
  • kvl Substitute keyword, value, and locker (if any).
  • k Substitute keyword only.
  • o Preserve original string.
  • b Like o, but mark file as binary.
  • v Substitue value only.

setComment

public void setComment(java.lang.String value)
Set the archive's comment.

Parameters:
value - The comment.

setDesc

public void setDesc(java.lang.String value)
Set the archives description.

Parameters:
value - The descriptions text.

addPhrase

public void addPhrase(java.lang.String key,
                      java.util.Collection values)
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.

Parameters:
key - The phrases key.
values - The values under the key.

newNode

protected Node newNode(Version vernum)

newNode

protected Node newNode(Version vernum,
                       Node prev)
                throws InvalidVersionNumberException,
                       NodeNotFoundException
Throws:
InvalidVersionNumberException
NodeNotFoundException

newTrunkNode

protected org.apache.commons.jrcs.rcs.TrunkNode newTrunkNode(Version vernum)
                                                      throws InvalidVersionNumberException,
                                                             NodeNotFoundException
Throws:
InvalidVersionNumberException
NodeNotFoundException

newBranchNode

protected org.apache.commons.jrcs.rcs.BranchNode newBranchNode(Version vernum)
                                                        throws InvalidVersionNumberException,
                                                               NodeNotFoundException
Throws:
InvalidVersionNumberException
NodeNotFoundException

getNode

protected Node getNode(Version vernum)
                throws InvalidVersionNumberException,
                       NodeNotFoundException
Throws:
InvalidVersionNumberException
NodeNotFoundException

findNode

public Node findNode(Version vernum)
Return the node with the version number that matches the one provided. The given version number may be partial.

Parameters:
vernum - the version number to match.
Returns:
the node, or null if no match found.

toString

public void toString(java.lang.StringBuffer s)
Place a string image of the archive in the given StringBuffer.

Overrides:
toString in class ToString
Parameters:
s - Where the image shoul go.

toString

public java.lang.String toString(java.lang.String EOL)
Return a text image of the archive.

Parameters:
EOL - The token to use as line separator.
Returns:
The text image of the archive.

toCharArray

public char[] toCharArray()
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.

Returns:
The archive image.

toByteArray

public byte[] toByteArray()
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.

Returns:
The archive image.

getRevisionPath

protected org.apache.commons.jrcs.rcs.Path getRevisionPath(Version vernum)
Returns the path from the head node to the node identified by the given version number.

Parameters:
vernum - The version number that identifies the final node. Partial version numbers are OK.
Returns:
The path to the node, or null if not found.

getRevisionVersion

public Version getRevisionVersion(Version vernum)
Return the actual revision number of the node identified by the given version number.

Parameters:
vernum - The version number that identifies the node. Partial version numbers are OK.
Returns:
The actual version, or null if a node is not found.

getRevisionVersion

public Version getRevisionVersion(java.lang.String vernum)
Return the actual revision number of the node identified by the given version number.

Parameters:
vernum - The version number that identifies the node. Partial version numbers are OK.
Returns:
The actual version, or null if a node is not found.

getRevisionVersion

public Version getRevisionVersion()
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.

Returns:
The version number of the active revision, or null if there is none.

toString

public void toString(java.lang.StringBuffer s,
                     java.lang.String EOL)
Append a text image of the archive to the given buffer using the given token as line separator.

Parameters:
s - where to append the image.
EOL - the line separator.

quoteString

public static java.lang.String quoteString(java.lang.String s)
Quote a string. RCS strings are quoted using @. Any @ in the original string is doubled to @@.

Parameters:
s - the string to quote.
Returns:
The string quoted in RCS style.

unquoteString

public static java.lang.String unquoteString(java.lang.String s)
Unquote a string quoted in RCS style.

Parameters:
s - the quoted string.
Returns:
s the string unquoted.

unquoteString

public static java.lang.String unquoteString(java.lang.String s,
                                             boolean removeExtremes)
Unquote a string quoted in RCS style.

Parameters:
s - the quoted string.
removeExtremes - Determines if the enclosing @ quotes should be removed.
Returns:
s the string unquoted.

getRevision

public java.lang.Object[] getRevision()
                               throws InvalidFileFormatException,
                                      PatchFailedException,
                                      NodeNotFoundException
Get the text belonging to the head revision.

Returns:
The text of the head revision
Throws:
NodeNotFoundException - if the revision could not be found.
InvalidFileFormatException - if any of the deltas cannot be parsed.
PatchFailedException - if any of the deltas could not be applied

getRevision

public java.lang.Object[] getRevision(boolean annotate)
                               throws InvalidFileFormatException,
                                      PatchFailedException,
                                      NodeNotFoundException
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.

Parameters:
annotate - set to true to have the text be annotated
Returns:
The text of the head revision
Throws:
NodeNotFoundException - if the revision could not be found.
InvalidFileFormatException - if any of the deltas cannot be parsed.
PatchFailedException - if any of the deltas could not be applied to produce a new revision.

getRevision

public java.lang.Object[] getRevision(java.lang.String vernum)
                               throws InvalidFileFormatException,
                                      PatchFailedException,
                                      InvalidVersionNumberException,
                                      NodeNotFoundException
Get the text belonging to the revision identified by the given version number. Partial version numbers are OK.

Parameters:
vernum - the version number.
Returns:
The text of the revision if found.
Throws:
InvalidVersionNumberException - if the version number cannot be parsed.
NodeNotFoundException - if the revision could not be found.
InvalidFileFormatException - if any of the deltas cannot be parsed.
PatchFailedException - if any of the deltas could not be applied

getRevision

public java.lang.Object[] getRevision(java.lang.String vernum,
                                      boolean annotate)
                               throws InvalidVersionNumberException,
                                      NodeNotFoundException,
                                      InvalidFileFormatException,
                                      PatchFailedException
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.

Parameters:
vernum - the version number.
annotate - set to true to have the text be annotated
Returns:
The text of the revision if found.
Throws:
InvalidVersionNumberException - if the version number cannot be parsed.
NodeNotFoundException - if the revision could not be found.
InvalidFileFormatException - if any of the deltas cannot be parsed.
PatchFailedException - if any of the deltas could not be applied

getRevision

public java.lang.Object[] getRevision(Version vernum)
                               throws InvalidFileFormatException,
                                      PatchFailedException,
                                      NodeNotFoundException
Get the text belonging to the revision identified by the given version number. Partial version numbers are OK.

Parameters:
vernum - the version number.
Returns:
The text of the revision if found.
Throws:
NodeNotFoundException - if the revision could not be found.
InvalidFileFormatException - if any of the deltas cannot be parsed.
PatchFailedException - if any of the deltas could not be applied

getRevision

public java.lang.Object[] getRevision(Version vernum,
                                      boolean annotate)
                               throws InvalidFileFormatException,
                                      PatchFailedException,
                                      NodeNotFoundException
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.

Parameters:
vernum - the version number.
annotate - set to true to have the text be annotated
Returns:
The text of the revision if found.
Throws:
NodeNotFoundException - if the revision could not be found.
InvalidFileFormatException - if any of the deltas cannot be parsed.
PatchFailedException - if any of the deltas could not be applied

addRevision

public Version addRevision(java.lang.Object[] text,
                           java.lang.String log)
                    throws InvalidFileFormatException,
                           DiffException,
                           InvalidVersionNumberException,
                           NodeNotFoundException
Add the given revision to the active branch on the archive.

Parameters:
text - the text of the revision.
log - the log: a short note explaining what the revision is.
Returns:
The version number assigned to the revision.
Throws:
InvalidFileFormatException
DiffException
InvalidVersionNumberException
NodeNotFoundException

addRevision

public Version addRevision(java.lang.Object[] text,
                           java.lang.String vernum,
                           java.lang.String log)
                    throws InvalidFileFormatException,
                           DiffException,
                           InvalidVersionNumberException,
                           NodeNotFoundException
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.

Parameters:
text - the text of the revision.
vernum - is the version number wanted, or, if partial, identifies the target branch.
log - the log: a short note explaining what the revision is.
Returns:
The version number assigned to the revision.
Throws:
InvalidFileFormatException
DiffException
InvalidVersionNumberException
NodeNotFoundException

addRevision

public Version addRevision(java.lang.Object[] text,
                           Version vernum,
                           java.lang.String log)
                    throws InvalidFileFormatException,
                           DiffException,
                           NodeNotFoundException,
                           InvalidVersionNumberException
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.

Parameters:
text - the text of the revision.
vernum - is the version number wanted, or, if partial, identifies the target branch.
log - the log: a short note explaining what the revision is.
Returns:
The version number assigned to the revision.
Throws:
InvalidFileFormatException
DiffException
NodeNotFoundException
InvalidVersionNumberException

doKeywords

public java.lang.Object[] doKeywords(java.lang.Object[] text,
                                     Node rev)
                              throws PatchFailedException
Returns the given text with values added to CVS-style keywords.

Parameters:
text - the text on which substitutions will be applied.
rev - a node that identifies the revision to which the given text belongs.
Returns:
the text with substitutions performed.
Throws:
PatchFailedException

removeKeywords

protected static java.lang.Object[] removeKeywords(java.lang.Object[] text)
                                            throws PatchFailedException
Returns the given text removing the values of any CVS-style keywords.

Parameters:
text - the text on which substitutions will be applied.
Returns:
the text with substitutions performed.
Throws:
PatchFailedException

changeLog

public Node[] changeLog()
Return the list of nodes between the head revision and the root revision.


changeLog

public Node[] changeLog(Version latest)
Return the list of nodes between the the given revision and the root revision.

Parameters:
latest - the version of the last revision in the log.

changeLog

public Node[] changeLog(Version latest,
                        Version earliest)
Return the list of nodes between the the given two revisions.

Parameters:
latest - the version of the last revision in the log.
earliest - the version of the first revision in the log.

getDesc

public java.lang.String getDesc()
Returns the description associated with the archive.

Returns:
the description

getLog

public java.lang.String getLog(Version version)
                        throws NodeNotFoundException
Returns the log message associated with the given revision.

Parameters:
version - - the version to get the log message for
Returns:
the log message for the version.
Throws:
- - if the version does not exist for the archive.
NodeNotFoundException

getLog

public java.lang.String getLog(java.lang.String vernum)
                        throws InvalidVersionNumberException,
                               NodeNotFoundException
Returns the log message associated with the given revision.

Parameters:
version - - the version to get the log message for
Returns:
the log message for the version.
Throws:
- - if the version does not exist for the archive.
InvalidVersionNumberException
NodeNotFoundException


Copyright © 2002-2011 Apache Software Foundation. All Rights Reserved.