|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.apache.commons.jrcs.util.ToString
org.apache.commons.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.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
|
private static KeywordsFormat |
FORMATTER
|
protected TrunkNode |
head
|
protected java.util.Set |
locked
|
protected java.util.Map |
nodes
|
protected Phrases |
phrases
|
static java.lang.String |
RCS_NEWLINE
|
(package private) Lines |
revLines
|
protected boolean |
strictLocking
|
protected java.util.Map |
symbols
|
protected java.util.Set |
users
|
Constructor Summary | |
---|---|
Archive()
Create an unitialized Archive. |
|
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 text,
java.lang.String desc)
Creates a new archive and sets the text of the initial revision. |
|
Archive(java.lang.String 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.String 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. |
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. |
Node[] |
getRevisionNodes()
|
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. |
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. |
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, stringToArraya, stringToArrayold, toString |
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 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
Lines revLines
private static final KeywordsFormat FORMATTER
Constructor Detail |
---|
public Archive(java.lang.String text, java.lang.String desc)
text
- The text of the initial revision.desc
- The archives description (not the log message).public Archive(java.lang.String 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.String 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.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
Archive()
ArchiveParser
Method Detail |
---|
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 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 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 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 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)
s
- the quoted string.
public static java.lang.String unquoteString(java.lang.String s, boolean removeExtremes)
s
- the quoted string.removeExtremes
- Determines if the enclosing @ quotes
should be removed.
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, 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(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 Node[] getRevisionNodes()
public 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) throws PatchFailedException
text
- the text on which substitutions will be applied.rev
- a node that identifies the revision to which the
given text belongs.
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
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |