|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.suigeneris.jrcs.util.ToString
org.suigeneris.jrcs.rcs.Archive
public class Archive
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.
org.suigeneris.jrcs.diff
Field Summary | |
---|---|
protected Version |
branch
|
protected java.lang.String |
comment
|
protected java.lang.String |
desc
|
static java.lang.String |
EXP_Binary
|
static java.lang.String |
EXP_KeywordAndValue
|
static java.lang.String |
EXP_KeywordOnly
|
static java.lang.String |
EXP_KeywordValueAndLocker
|
static java.lang.String |
EXP_PreserveOriginal
|
static java.lang.String |
EXP_ValueOnly
|
protected java.lang.String |
expand
|
protected java.lang.String |
filename
|
protected TrunkNode |
head
|
protected java.util.Set |
locked
|
protected java.util.Map |
nodes
|
protected Phrases |
phrases
|
static java.lang.String |
RCS_NEWLINE
|
static char |
RCS_NEWLINE_CHAR
|
protected boolean |
strictLocking
|
protected java.util.Map |
symbols
|
protected java.util.Set |
users
|
Constructor Summary | |
---|---|
Archive()
Create an unitialized Archive. |
|
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. |
|
Archive(java.lang.String fname,
java.io.Reader reader)
Load an archive from an Reader. |
|
Archive(java.net.URL url)
Load an archive from an a file given by name. |
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,
java.lang.String vernum)
Tag a given version with a symbol. |
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,
java.lang.String expansion)
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 |
getExpand()
Get the expansin flag. |
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)
|
protected Phrases |
getPhrases()
|
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(java.lang.String vernum,
java.lang.String expansion)
Get the text belonging to the revision identified by the given version number. |
java.lang.Object[] |
getRevision(java.lang.String vernum,
java.lang.String expansion,
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. |
java.lang.Object[] |
getRevision(Version vernum,
java.lang.String expansion,
boolean annotate)
Get the text belonging to the revision identified by the given version number. |
protected 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. |
boolean |
isBinary()
Determine if expansion is set to binary. |
boolean |
isValidSymbol(java.lang.String sym)
|
protected BranchNode |
newBranchNode(Version vernum)
|
protected Node |
newNode(Version vernum)
|
protected Node |
newNode(Version vernum,
Node prev)
|
protected TrunkNode |
newTrunkNode(Version vernum)
|
static java.lang.String |
quoteString(java.lang.String s)
Quote a string. |
void |
Remove()
Removes the tip revision from the archive. |
void |
Remove(java.lang.String vernum)
Removes the revision identified by the provided version string. |
void |
Remove(Version version)
Removes the revision identified by the given Version |
protected static java.lang.Object[] |
removeKeywords(java.lang.Object[] text)
Returns the given text removing the values of any CVS-style keywords. |
private void |
removeNode(Node node)
Removes a node from the archive. |
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(char eol)
Return a text image of the archive. |
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. |
Version |
version(java.lang.String vernum)
Retrieves a Version object from a numeric version string or a
symbolic name. |
Methods inherited from class org.suigeneris.jrcs.util.ToString |
---|
arrayToString, arrayToString, stringToArray, stringToArray, toString, toStringOfChars |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final java.lang.String EXP_KeywordAndValue
public static final java.lang.String EXP_KeywordValueAndLocker
public static final java.lang.String EXP_KeywordOnly
public static final java.lang.String EXP_PreserveOriginal
public static final java.lang.String EXP_Binary
public static final java.lang.String EXP_ValueOnly
public static final char RCS_NEWLINE_CHAR
public static final java.lang.String RCS_NEWLINE
protected TrunkNode head
protected Version branch
protected java.util.Map nodes
protected java.util.Set users
protected java.util.Set locked
protected java.util.Map symbols
protected Phrases phrases
protected java.lang.String desc
protected boolean strictLocking
protected java.lang.String expand
protected java.lang.String comment
protected java.lang.String filename
Constructor Detail |
---|
public Archive(java.lang.Object[] text, java.lang.String desc)
text
- The text of the initial revision.desc
- The archives description (not the log message).public Archive(java.lang.Object[] text, java.lang.String desc, java.lang.String vernum)
text
- The text of the initial revision.desc
- The archives description (not the log message).vernum
- The initial revision number.public Archive(java.lang.Object[] text, java.lang.String desc, Version vernum)
text
- The text of the initial revision.desc
- The archives description (not the log message).vernum
- The initial revision number.public Archive(java.lang.String fname, java.io.Reader reader) throws ParseException
fname
- The name to give to the archive.reader
- Where to read the archive from
ParseException
public Archive(java.lang.String fname, java.io.InputStream input) throws ParseException
fname
- The name to give to the archive.input
- Where to read the archive from
ParseException
public Archive(java.lang.String path) throws ParseException, java.io.FileNotFoundException
path
- The path to the file wher the archive resides.
ParseException
java.io.FileNotFoundException
public Archive(java.net.URL url) throws ParseException, java.io.IOException
path
- The path to the file wher the archive resides.
ParseException
java.io.IOException
Archive()
ArchiveParser
Method Detail |
---|
public Version version(java.lang.String vernum) throws InvalidVersionNumberException
Version
object from a numeric version string or a
symbolic name. Symbolic names must have been previously defined using
addSymbol
.
vernum
- a numeric version identifier or a symbolic name.
Version
object
InvalidVersionNumberException
public void setFileName(java.lang.String path)
path
- The full path name.public void save(java.io.OutputStream output) throws java.io.IOException
output
- The stream to save the archive to.
java.io.IOException
public void save(java.lang.String path) throws java.io.IOException
path
- The file's path.
java.io.IOException
protected void setHead(Version vernum) throws InvalidVersionNumberException
vernum
- The version number to use.
InvalidVersionNumberException
public void setBranch(java.lang.String v) throws InvalidBranchVersionNumberException
v
- The version number.
InvalidBranchVersionNumberException
public void setBranch(Version vernum) throws InvalidBranchVersionNumberException
vernum
- The version number.
InvalidBranchVersionNumberException
public void addUser(java.lang.String name)
name
- The user name.public boolean isValidSymbol(java.lang.String sym)
public void addSymbol(java.lang.String sym, java.lang.String vernum)
sym
- The tag.vernum
- The version to tag.public void addSymbol(java.lang.String sym, Version vernum) throws InvalidVersionNumberException
sym
- The tag.vernum
- The version to tag.
InvalidVersionNumberException
public java.util.Map getSymbols()
public void addLock(java.lang.String user, Version vernum) throws InvalidVersionNumberException, NodeNotFoundException
user
- The user that locks the revision.vernum
- The version number of the revision to lock.
InvalidVersionNumberException
NodeNotFoundException
public void setStrictLocking(boolean value)
value
- Indicates if strict locking should be on or off.public void setExpand(java.lang.String value)
value
- The keyword expansion value. It should be one of:
public java.lang.String getExpand()
setExpand(java.lang.String)
public boolean isBinary()
true
if expansion is set to binary.public void setComment(java.lang.String value)
value
- The comment.public void setDesc(java.lang.String value)
value
- The descriptions text.public void addPhrase(java.lang.String key, java.util.Collection values)
key
- The phrases key.values
- The values under the key.protected Phrases getPhrases()
protected Node newNode(Version vernum)
protected Node newNode(Version vernum, Node prev) throws InvalidVersionNumberException, NodeNotFoundException
InvalidVersionNumberException
NodeNotFoundException
protected TrunkNode newTrunkNode(Version vernum) throws InvalidVersionNumberException, NodeNotFoundException
InvalidVersionNumberException
NodeNotFoundException
protected BranchNode newBranchNode(Version vernum) throws InvalidVersionNumberException, NodeNotFoundException
InvalidVersionNumberException
NodeNotFoundException
protected Node getNode(Version vernum) throws InvalidVersionNumberException, NodeNotFoundException
InvalidVersionNumberException
NodeNotFoundException
public Node findNode(Version vernum)
vernum
- the version number to match.
public void toString(java.lang.StringBuffer s)
toString
in class ToString
s
- Where the image shoul go.public java.lang.String toString(java.lang.String eol)
eol
- The token to use as line separator.
public java.lang.String toString(char eol)
EOL
- The token to use as line separator.
public char[] toCharArray()
public byte[] toByteArray()
protected Path getRevisionPath(Version vernum)
vernum
- The version number that identifies the final node. Partial
version numbers are OK.
public Version getRevisionVersion(Version vernum)
vernum
- The version number that identifies the node. Partial version
numbers are OK.
public Version getRevisionVersion(java.lang.String vernum)
vernum
- The version number that identifies the node. Partial version
numbers are OK.
public Version getRevisionVersion()
public void toString(java.lang.StringBuffer s, java.lang.String EOL)
s
- where to append the image.EOL
- the line separator.public static java.lang.String quoteString(java.lang.String s)
s
- the string to quote.
public static java.lang.String unquoteString(java.lang.String s) throws ParseException
s
- the quoted string.
ParseException
public static java.lang.String unquoteString(java.lang.String s, boolean removeExtremes) throws ParseException
s
- the quoted string.removeExtremes
- Determines if the enclosing @ quotes should be removed.
ParseException
public java.lang.Object[] getRevision() throws InvalidFileFormatException, PatchFailedException, NodeNotFoundException
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 appliedpublic java.lang.Object[] getRevision(boolean annotate) throws InvalidFileFormatException, PatchFailedException, NodeNotFoundException
annotate
- set to true to have the text be annotated
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.public java.lang.Object[] getRevision(java.lang.String vernum) throws InvalidFileFormatException, PatchFailedException, InvalidVersionNumberException, NodeNotFoundException
vernum
- the version number.
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 appliedpublic java.lang.Object[] getRevision(java.lang.String vernum, java.lang.String expansion) throws InvalidFileFormatException, PatchFailedException, InvalidVersionNumberException, NodeNotFoundException
vernum
- the version number.expansion
- the desired keyword expansion mode
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 appliedpublic java.lang.Object[] getRevision(java.lang.String vernum, boolean annotate) throws InvalidVersionNumberException, NodeNotFoundException, InvalidFileFormatException, PatchFailedException
vernum
- the version number.annotate
- set to true to have the text be annotated
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 appliedpublic java.lang.Object[] getRevision(java.lang.String vernum, java.lang.String expansion, boolean annotate) throws InvalidVersionNumberException, NodeNotFoundException, InvalidFileFormatException, PatchFailedException
vernum
- the version number.expansion
- the desired keyword expansion modeannotate
- set to true to have the text be annotated
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 appliedpublic java.lang.Object[] getRevision(Version vernum) throws InvalidFileFormatException, PatchFailedException, NodeNotFoundException
vernum
- the version number.
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 appliedpublic java.lang.Object[] getRevision(Version vernum, boolean annotate) throws InvalidFileFormatException, PatchFailedException, NodeNotFoundException
vernum
- the version number.annotate
- set to true to have the text be annotated
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 appliedpublic java.lang.Object[] getRevision(Version vernum, java.lang.String expansion, boolean annotate) throws InvalidFileFormatException, PatchFailedException, NodeNotFoundException
vernum
- the version number.expansion
- the desired keyword expansion modeannotate
- set to true to have the text be annotated
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 appliedpublic Version addRevision(java.lang.Object[] text, java.lang.String log) throws InvalidFileFormatException, DiffException, InvalidVersionNumberException, NodeNotFoundException
text
- the text of the revision.log
- the log: a short note explaining what the revision is.
InvalidFileFormatException
DiffException
InvalidVersionNumberException
NodeNotFoundException
public Version addRevision(java.lang.Object[] text, java.lang.String vernum, java.lang.String log) throws InvalidFileFormatException, DiffException, InvalidVersionNumberException, NodeNotFoundException
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.
InvalidFileFormatException
DiffException
InvalidVersionNumberException
NodeNotFoundException
public Version addRevision(java.lang.Object[] text, Version vernum, java.lang.String log) throws InvalidFileFormatException, DiffException, NodeNotFoundException, InvalidVersionNumberException
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.
InvalidFileFormatException
DiffException
NodeNotFoundException
InvalidVersionNumberException
public java.lang.Object[] doKeywords(java.lang.Object[] text, Node rev, java.lang.String expansion) throws PatchFailedException
text
- the text on which substitutions will be applied.rev
- a node that identifies the revision to which the given text
belongs.expansion
-
PatchFailedException
protected static java.lang.Object[] removeKeywords(java.lang.Object[] text) throws PatchFailedException
text
- the text on which substitutions will be applied.
PatchFailedException
public Node[] changeLog()
public Node[] changeLog(Version latest)
latest
- the version of the last revision in the log.public Node[] changeLog(Version latest, Version earliest)
latest
- the version of the last revision in the log.earliest
- the version of the first revision in the log.public java.lang.String getDesc()
public java.lang.String getLog(Version version) throws NodeNotFoundException
version
- -
the version to get the log message for
-
- if the version does not exist for the archive.
NodeNotFoundException
public java.lang.String getLog(java.lang.String vernum) throws InvalidVersionNumberException, NodeNotFoundException
version
- -
the version to get the log message for
-
- if the version does not exist for the archive.
InvalidVersionNumberException
NodeNotFoundException
public void Remove() throws NodeNotFoundException, InvalidFileFormatException, PatchFailedException, DifferentiationFailedException
NodeNotFoundException
InvalidFileFormatException
PatchFailedException
DifferentiationFailedException
public void Remove(java.lang.String vernum) throws NodeNotFoundException, InvalidFileFormatException, PatchFailedException, InvalidVersionNumberException, DifferentiationFailedException
vernum
- the version string
NodeNotFoundException
InvalidFileFormatException
PatchFailedException
InvalidVersionNumberException
DifferentiationFailedException
public void Remove(Version version) throws NodeNotFoundException, InvalidFileFormatException, PatchFailedException, DifferentiationFailedException
Version
version
- the version object
NodeNotFoundException
InvalidFileFormatException
PatchFailedException
DifferentiationFailedException
private void removeNode(Node node) throws NodeNotFoundException, InvalidFileFormatException, PatchFailedException, DifferentiationFailedException
node
- the node to remove.
NodeNotFoundException
InvalidFileFormatException
PatchFailedException
DifferentiationFailedException
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |