From: James Moger Date: Sat, 2 Jul 2011 01:17:28 +0000 (-0400) Subject: Documentation. Added JavaDoc comments. X-Git-Tag: v0.5.2~28 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=d9f68798555e5ba8b4f7ddecf4a8cabbe9bb161a;p=gitblit.git Documentation. Added JavaDoc comments. --- diff --git a/src/com/gitblit/models/AnnotatedLine.java b/src/com/gitblit/models/AnnotatedLine.java index 3d124765..69b55bcd 100644 --- a/src/com/gitblit/models/AnnotatedLine.java +++ b/src/com/gitblit/models/AnnotatedLine.java @@ -20,6 +20,13 @@ import java.util.Date; import org.eclipse.jgit.revwalk.RevCommit; +/** + * AnnotatedLine is a serializable model class that represents a the most recent + * author, date, and commit id of a line in a source file. + * + * @author James Moger + * + */ public class AnnotatedLine implements Serializable { private static final long serialVersionUID = 1L; diff --git a/src/com/gitblit/models/GitNote.java b/src/com/gitblit/models/GitNote.java index 3b66d89f..c333a881 100644 --- a/src/com/gitblit/models/GitNote.java +++ b/src/com/gitblit/models/GitNote.java @@ -17,12 +17,20 @@ package com.gitblit.models; import java.io.Serializable; +/** + * GitNote is a serializable model class that represents a git note. This class + * retains an instance of the RefModel which contains the commit in which this + * git note was created. + * + * @author James Moger + * + */ public class GitNote implements Serializable { private static final long serialVersionUID = 1L; - public String content; - public RefModel notesRef; + public final String content; + public final RefModel notesRef; public GitNote(RefModel notesRef, String text) { this.notesRef = notesRef; diff --git a/src/com/gitblit/models/Metric.java b/src/com/gitblit/models/Metric.java index 9ff270ad..e7c49a45 100644 --- a/src/com/gitblit/models/Metric.java +++ b/src/com/gitblit/models/Metric.java @@ -17,11 +17,18 @@ package com.gitblit.models; import java.io.Serializable; +/** + * Metric is a serializable model class that encapsulates metrics for some given + * type. + * + * @author James Moger + * + */ public class Metric implements Serializable { private static final long serialVersionUID = 1L; - public String name; + public final String name; public double count; public double tag; public int duration; diff --git a/src/com/gitblit/models/PathModel.java b/src/com/gitblit/models/PathModel.java index 08415317..c78b300c 100644 --- a/src/com/gitblit/models/PathModel.java +++ b/src/com/gitblit/models/PathModel.java @@ -20,6 +20,13 @@ import java.io.Serializable; import org.eclipse.jgit.diff.DiffEntry.ChangeType; import org.eclipse.jgit.lib.FileMode; +/** + * PathModel is a serializable model class that represents a file or a folder, + * including all its metadata and associated commit id. + * + * @author James Moger + * + */ public class PathModel implements Serializable, Comparable { private static final long serialVersionUID = 1L; @@ -71,6 +78,13 @@ public class PathModel implements Serializable, Comparable { return 1; } + /** + * PathChangeModel is a serializable class that represents a file changed in + * a commit. + * + * @author James Moger + * + */ public static class PathChangeModel extends PathModel { private static final long serialVersionUID = 1L; diff --git a/src/com/gitblit/models/RefModel.java b/src/com/gitblit/models/RefModel.java index 92c394c1..fab5fc1f 100644 --- a/src/com/gitblit/models/RefModel.java +++ b/src/com/gitblit/models/RefModel.java @@ -25,6 +25,13 @@ import org.eclipse.jgit.revwalk.RevCommit; import org.eclipse.jgit.revwalk.RevObject; import org.eclipse.jgit.revwalk.RevTag; +/** + * RefModel is a serializable model class that represents a tag or branch and + * includes the referenced object. + * + * @author James Moger + * + */ public class RefModel implements Serializable, Comparable { private static final long serialVersionUID = 1L; diff --git a/src/com/gitblit/models/RepositoryModel.java b/src/com/gitblit/models/RepositoryModel.java index 97ae5184..38637378 100644 --- a/src/com/gitblit/models/RepositoryModel.java +++ b/src/com/gitblit/models/RepositoryModel.java @@ -20,6 +20,13 @@ import java.util.Date; import com.gitblit.Constants.AccessRestrictionType; +/** + * RepositoryModel is a serializable model class that represents a Gitblit + * repository including its configuration settings and access restriction. + * + * @author James Moger + * + */ public class RepositoryModel implements Serializable { private static final long serialVersionUID = 1L; diff --git a/src/com/gitblit/models/TicketModel.java b/src/com/gitblit/models/TicketModel.java index d86a073d..b8043c6c 100644 --- a/src/com/gitblit/models/TicketModel.java +++ b/src/com/gitblit/models/TicketModel.java @@ -21,6 +21,12 @@ import java.util.ArrayList; import java.util.Date; import java.util.List; +/** + * TicketModel is a serializable model class that represents a Ticgit ticket. + * + * @author James Moger + * + */ public class TicketModel implements Serializable, Comparable { private static final long serialVersionUID = 1L; @@ -50,6 +56,32 @@ public class TicketModel implements Serializable, Comparable { } } + @Override + public int hashCode() { + return id.hashCode(); + } + + @Override + public boolean equals(Object o) { + if (o instanceof TicketModel) { + TicketModel other = (TicketModel) o; + return id.equals(other.id); + } + return super.equals(o); + } + + @Override + public int compareTo(TicketModel o) { + return date.compareTo(o.date); + } + + /** + * Comment is a serializable model class that represents a Ticgit ticket + * comment. + * + * @author James Moger + * + */ public static class Comment implements Serializable, Comparable { private static final long serialVersionUID = 1L; @@ -84,23 +116,4 @@ public class TicketModel implements Serializable, Comparable { return date.compareTo(o.date); } } - - @Override - public int hashCode() { - return id.hashCode(); - } - - @Override - public boolean equals(Object o) { - if (o instanceof TicketModel) { - TicketModel other = (TicketModel) o; - return id.equals(other.id); - } - return super.equals(o); - } - - @Override - public int compareTo(TicketModel o) { - return date.compareTo(o.date); - } } diff --git a/src/com/gitblit/models/UserModel.java b/src/com/gitblit/models/UserModel.java index fd355fbb..aeeecf4b 100644 --- a/src/com/gitblit/models/UserModel.java +++ b/src/com/gitblit/models/UserModel.java @@ -20,6 +20,14 @@ import java.security.Principal; import java.util.ArrayList; import java.util.List; +/** + * UserModel is a serializable model class that represents a user and the user's + * restricted repository memberships. Instances of UserModels are also used as + * servlet user principals. + * + * @author James Moger + * + */ public class UserModel implements Principal, Serializable { private static final long serialVersionUID = 1L; diff --git a/src/com/gitblit/utils/ByteFormat.java b/src/com/gitblit/utils/ByteFormat.java index ea198de0..f4c05cd5 100644 --- a/src/com/gitblit/utils/ByteFormat.java +++ b/src/com/gitblit/utils/ByteFormat.java @@ -20,6 +20,13 @@ import java.text.FieldPosition; import java.text.Format; import java.text.ParsePosition; +/** + * ByteFormat is a formatter which takes numbers and returns filesizes in bytes, + * kilobytes, megabytes, or gigabytes. + * + * @author James Moger + * + */ public class ByteFormat extends Format { private static final long serialVersionUID = 1L; diff --git a/src/com/gitblit/utils/DiffUtils.java b/src/com/gitblit/utils/DiffUtils.java index c1401f96..beeb5323 100644 --- a/src/com/gitblit/utils/DiffUtils.java +++ b/src/com/gitblit/utils/DiffUtils.java @@ -30,13 +30,20 @@ import org.eclipse.jgit.lib.Repository; import org.eclipse.jgit.revwalk.RevCommit; import org.eclipse.jgit.revwalk.RevTree; import org.eclipse.jgit.revwalk.RevWalk; -import org.eclipse.jgit.treewalk.TreeWalk; -import org.eclipse.jgit.treewalk.filter.TreeFilter; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import com.gitblit.models.AnnotatedLine; +/** + * DiffUtils is a class of utility methods related to diff, patch, and blame. + * + * The diff methods support pluggable diff output types like Gitblit, Gitweb, + * and Plain. + * + * @author James Moger + * + */ public class DiffUtils { private static final Logger LOGGER = LoggerFactory.getLogger(DiffUtils.class); @@ -54,43 +61,67 @@ public class DiffUtils { } } - public static String getCommitDiff(Repository r, RevCommit commit, DiffOutputType outputType) { - return getDiff(r, null, commit, null, outputType); + /** + * Returns the complete diff of the specified commit compared to its primary + * parent. + * + * @param repository + * @param commit + * @param outputType + * @return the diff as a string + */ + public static String getCommitDiff(Repository repository, RevCommit commit, + DiffOutputType outputType) { + return getDiff(repository, null, commit, null, outputType); } - public static String getDiff(Repository r, RevCommit commit, String path, + /** + * Returns the diff for the specified file or folder from the specified + * commit compared to its primary parent. + * + * @param repository + * @param commit + * @param path + * @param outputType + * @return the diff as a string + */ + public static String getDiff(Repository repository, RevCommit commit, String path, DiffOutputType outputType) { - return getDiff(r, null, commit, path, outputType); + return getDiff(repository, null, commit, path, outputType); } - public static String getDiff(Repository r, RevCommit baseCommit, RevCommit commit, + /** + * Returns the complete diff between the two specified commits. + * + * @param repository + * @param baseCommit + * @param commit + * @param outputType + * @return the diff as a string + */ + public static String getDiff(Repository repository, RevCommit baseCommit, RevCommit commit, DiffOutputType outputType) { - return getDiff(r, baseCommit, commit, null, outputType); + return getDiff(repository, baseCommit, commit, null, outputType); } - public static String getDiff(Repository r, RevCommit baseCommit, RevCommit commit, String path, - DiffOutputType outputType) { + /** + * Returns the diff between two commits for the specified file. + * + * @param repository + * @param baseCommit + * if base commit is null the diff is to the primary parent of + * the commit. + * @param commit + * @param path + * if the path is specified, the diff is restricted to that file + * or folder. if unspecified, the diff is for the entire commit. + * @param outputType + * @return the diff as a string + */ + public static String getDiff(Repository repository, RevCommit baseCommit, RevCommit commit, + String path, DiffOutputType outputType) { String diff = null; try { - RevTree baseTree; - if (baseCommit == null) { - final RevWalk rw = new RevWalk(r); - RevCommit parent = rw.parseCommit(commit.getParent(0).getId()); - rw.dispose(); - baseTree = parent.getTree(); - } else { - baseTree = baseCommit.getTree(); - } - - RevTree commitTree = commit.getTree(); - - final TreeWalk walk = new TreeWalk(r); - walk.reset(); - walk.setRecursive(true); - walk.addTree(baseTree); - walk.addTree(commitTree); - walk.setFilter(TreeFilter.ANY_DIFF); - final ByteArrayOutputStream os = new ByteArrayOutputStream(); RawTextComparator cmp = RawTextComparator.DEFAULT; DiffFormatter df; @@ -106,9 +137,21 @@ public class DiffUtils { df = new DiffFormatter(os); break; } - df.setRepository(r); + df.setRepository(repository); df.setDiffComparator(cmp); df.setDetectRenames(true); + + RevTree commitTree = commit.getTree(); + RevTree baseTree; + if (baseCommit == null) { + final RevWalk rw = new RevWalk(repository); + RevCommit parent = rw.parseCommit(commit.getParent(0).getId()); + rw.dispose(); + baseTree = parent.getTree(); + } else { + baseTree = baseCommit.getTree(); + } + List diffEntries = df.scan(baseTree, commitTree); if (path != null && path.length() > 0) { for (DiffEntry diffEntry : diffEntries) { @@ -133,33 +176,42 @@ public class DiffUtils { return diff; } - public static String getCommitPatch(Repository r, RevCommit baseCommit, RevCommit commit, - String path) { + /** + * Returns the diff between the two commits for the specified file or folder + * formatted as a patch. + * + * @param repository + * @param baseCommit + * if base commit is unspecified, the patch is generated against + * the primary parent of the specified commit. + * @param commit + * @param path + * if path is specified, the patch is generated only for the + * specified file or folder. if unspecified, the patch is + * generated for the entire diff between the two commits. + * @return patch as a string + */ + public static String getCommitPatch(Repository repository, RevCommit baseCommit, + RevCommit commit, String path) { String diff = null; try { + final ByteArrayOutputStream os = new ByteArrayOutputStream(); + RawTextComparator cmp = RawTextComparator.DEFAULT; + PatchFormatter df = new PatchFormatter(os); + df.setRepository(repository); + df.setDiffComparator(cmp); + df.setDetectRenames(true); + + RevTree commitTree = commit.getTree(); RevTree baseTree; if (baseCommit == null) { - final RevWalk rw = new RevWalk(r); + final RevWalk rw = new RevWalk(repository); RevCommit parent = rw.parseCommit(commit.getParent(0).getId()); baseTree = parent.getTree(); } else { baseTree = baseCommit.getTree(); } - RevTree commitTree = commit.getTree(); - - final TreeWalk walk = new TreeWalk(r); - walk.reset(); - walk.setRecursive(true); - walk.addTree(baseTree); - walk.addTree(commitTree); - walk.setFilter(TreeFilter.ANY_DIFF); - final ByteArrayOutputStream os = new ByteArrayOutputStream(); - RawTextComparator cmp = RawTextComparator.DEFAULT; - PatchFormatter df = new PatchFormatter(os); - df.setRepository(r); - df.setDiffComparator(cmp); - df.setDetectRenames(true); List diffEntries = df.scan(baseTree, commitTree); if (path != null && path.length() > 0) { for (DiffEntry diffEntry : diffEntries) { @@ -179,15 +231,24 @@ public class DiffUtils { return diff; } - public static List blame(Repository r, String blobPath, String objectId) { + /** + * Returns the list of lines in the specified source file annotated with the + * source commit metadata. + * + * @param repository + * @param blobPath + * @param objectId + * @return list of annotated lines + */ + public static List blame(Repository repository, String blobPath, String objectId) { List lines = new ArrayList(); try { if (StringUtils.isEmpty(objectId)) { objectId = Constants.HEAD; } - BlameCommand blameCommand = new BlameCommand(r); + BlameCommand blameCommand = new BlameCommand(repository); blameCommand.setFilePath(blobPath); - blameCommand.setStartCommit(r.resolve(objectId)); + blameCommand.setStartCommit(repository.resolve(objectId)); BlameResult blameResult = blameCommand.call(); RawText rawText = blameResult.getResultContents(); int length = rawText.size(); diff --git a/src/com/gitblit/utils/FileUtils.java b/src/com/gitblit/utils/FileUtils.java index 3cfe6894..468b2a80 100644 --- a/src/com/gitblit/utils/FileUtils.java +++ b/src/com/gitblit/utils/FileUtils.java @@ -34,7 +34,7 @@ public class FileUtils { * * @param file * @param lineEnding - * @return + * @return the string content of the file */ public static String readContent(File file, String lineEnding) { StringBuilder sb = new StringBuilder(); diff --git a/src/com/gitblit/utils/GitBlitDiffFormatter.java b/src/com/gitblit/utils/GitBlitDiffFormatter.java index 14413612..0e393fef 100644 --- a/src/com/gitblit/utils/GitBlitDiffFormatter.java +++ b/src/com/gitblit/utils/GitBlitDiffFormatter.java @@ -21,6 +21,12 @@ import java.io.OutputStream; import org.eclipse.jgit.diff.RawText; +/** + * Generates an html snippet of a diff in Gitblit's style. + * + * @author James Moger + * + */ public class GitBlitDiffFormatter extends GitWebDiffFormatter { private final OutputStream os; diff --git a/src/com/gitblit/utils/GitWebDiffFormatter.java b/src/com/gitblit/utils/GitWebDiffFormatter.java index b998259b..00ea121c 100644 --- a/src/com/gitblit/utils/GitWebDiffFormatter.java +++ b/src/com/gitblit/utils/GitWebDiffFormatter.java @@ -24,6 +24,12 @@ import java.io.OutputStream; import org.eclipse.jgit.diff.DiffFormatter; import org.eclipse.jgit.diff.RawText; +/** + * Returns an html snippet of the diff in the standard Gitweb style. + * + * @author James Moger + * + */ public class GitWebDiffFormatter extends DiffFormatter { private final OutputStream os; diff --git a/src/com/gitblit/utils/MarkdownUtils.java b/src/com/gitblit/utils/MarkdownUtils.java index 697fa99b..c7c1f9fe 100644 --- a/src/com/gitblit/utils/MarkdownUtils.java +++ b/src/com/gitblit/utils/MarkdownUtils.java @@ -23,8 +23,21 @@ import java.io.StringWriter; import org.tautua.markdownpapers.Markdown; import org.tautua.markdownpapers.parser.ParseException; +/** + * Utility methods for transforming raw markdown text to html. + * + * @author James Moger + * + */ public class MarkdownUtils { + /** + * Returns the html version of the markdown source text. + * + * @param markdown + * @return html version of markdown text + * @throws java.text.ParseException + */ public static String transformMarkdown(String markdown) throws java.text.ParseException { try { return transformMarkdown(new StringReader(markdown)); @@ -33,6 +46,14 @@ public class MarkdownUtils { } } + /** + * Returns the html version of the markdown source reader. The reader is + * closed regardless of success or failure. + * + * @param markdownReader + * @return html version of the markdown text + * @throws java.text.ParseException + */ public static String transformMarkdown(Reader markdownReader) throws java.text.ParseException { // Read raw markdown content and transform it to html StringWriter writer = new StringWriter(); diff --git a/src/com/gitblit/utils/MetricUtils.java b/src/com/gitblit/utils/MetricUtils.java index 85ef89f1..acdacc4d 100644 --- a/src/com/gitblit/utils/MetricUtils.java +++ b/src/com/gitblit/utils/MetricUtils.java @@ -35,33 +35,58 @@ import org.slf4j.LoggerFactory; import com.gitblit.models.Metric; import com.gitblit.models.RefModel; +/** + * Utility class for collecting metrics on a branch, tag, or other ref within + * the repository. + * + * @author James Moger + * + */ public class MetricUtils { private static final Logger LOGGER = LoggerFactory.getLogger(MetricUtils.class); - public static List getDateMetrics(Repository r, String objectId, boolean includeTotal, - String format) { + /** + * Returns the list of metrics for the specified commit reference, branch, + * or tag within the repository. If includeTotal is true, the total of all + * the metrics will be included as the first element in the returned list. + * + * If the dateformat is unspecified an attempt is made to determine an + * appropriate date format by determining the time difference between the + * first commit on the branch and the most recent commit. This assumes that + * the commits are linear. + * + * @param repository + * @param objectId + * if null or empty, HEAD is assumed. + * @param includeTotal + * @param dateFormat + * @return list of metrics + */ + public static List getDateMetrics(Repository repository, String objectId, + boolean includeTotal, String dateFormat) { Metric total = new Metric("TOTAL"); final Map metricMap = new HashMap(); if (StringUtils.isEmpty(objectId)) { objectId = Constants.HEAD; } - if (JGitUtils.hasCommits(r)) { - final List tags = JGitUtils.getTags(r, true, -1); + if (JGitUtils.hasCommits(repository)) { + final List tags = JGitUtils.getTags(repository, true, -1); final Map tagMap = new HashMap(); for (RefModel tag : tags) { tagMap.put(tag.getReferencedObjectId(), tag); } + RevWalk revWalk = null; try { - RevWalk walk = new RevWalk(r); - ObjectId object = r.resolve(objectId); - RevCommit lastCommit = walk.parseCommit(object); - walk.markStart(lastCommit); + revWalk = new RevWalk(repository); + ObjectId object = repository.resolve(objectId); + RevCommit lastCommit = revWalk.parseCommit(object); + revWalk.markStart(lastCommit); DateFormat df; - if (StringUtils.isEmpty(format)) { + if (StringUtils.isEmpty(dateFormat)) { // dynamically determine date format - RevCommit firstCommit = JGitUtils.getFirstCommit(r, Constants.HEAD); + RevCommit firstCommit = JGitUtils.getFirstCommit(repository, Constants.HEAD); int diffDays = (lastCommit.getCommitTime() - firstCommit.getCommitTime()) / (60 * 60 * 24); total.duration = diffDays; @@ -74,10 +99,10 @@ public class MetricUtils { } } else { // use specified date format - df = new SimpleDateFormat(format); + df = new SimpleDateFormat(dateFormat); } - Iterable revlog = walk; + Iterable revlog = revWalk; for (RevCommit rev : revlog) { Date d = JGitUtils.getCommitDate(rev); String p = df.format(d); @@ -94,6 +119,10 @@ public class MetricUtils { } } catch (Throwable t) { LOGGER.error("Failed to mine log history for date metrics", t); + } finally { + if (revWalk != null) { + revWalk.dispose(); + } } } List keys = new ArrayList(metricMap.keySet()); @@ -108,22 +137,33 @@ public class MetricUtils { return metrics; } - public static List getAuthorMetrics(Repository r, String objectId, boolean byEmail) { + /** + * Returns a list of author metrics for the specified repository. + * + * @param repository + * @param objectId + * if null or empty, HEAD is assumed. + * @param byEmailAddress + * group metrics by author email address otherwise by author name + * @return list of metrics + */ + public static List getAuthorMetrics(Repository repository, String objectId, + boolean byEmailAddress) { final Map metricMap = new HashMap(); if (StringUtils.isEmpty(objectId)) { objectId = Constants.HEAD; } - if (JGitUtils.hasCommits(r)) { + if (JGitUtils.hasCommits(repository)) { try { - RevWalk walk = new RevWalk(r); - ObjectId object = r.resolve(objectId); + RevWalk walk = new RevWalk(repository); + ObjectId object = repository.resolve(objectId); RevCommit lastCommit = walk.parseCommit(object); walk.markStart(lastCommit); Iterable revlog = walk; for (RevCommit rev : revlog) { String p; - if (byEmail) { + if (byEmailAddress) { p = rev.getAuthorIdent().getEmailAddress().toLowerCase(); if (StringUtils.isEmpty(p)) { p = rev.getAuthorIdent().getName().toLowerCase(); diff --git a/src/com/gitblit/utils/PatchFormatter.java b/src/com/gitblit/utils/PatchFormatter.java index daa15aae..92559561 100644 --- a/src/com/gitblit/utils/PatchFormatter.java +++ b/src/com/gitblit/utils/PatchFormatter.java @@ -30,6 +30,12 @@ import org.eclipse.jgit.revwalk.RevCommit; import com.gitblit.Constants; +/** + * A diff formatter that outputs standard patch content. + * + * @author James Moger + * + */ public class PatchFormatter extends DiffFormatter { private final OutputStream os; diff --git a/src/com/gitblit/utils/StringUtils.java b/src/com/gitblit/utils/StringUtils.java index 219699fc..bb1928a2 100644 --- a/src/com/gitblit/utils/StringUtils.java +++ b/src/com/gitblit/utils/StringUtils.java @@ -22,18 +22,44 @@ import java.util.ArrayList; import java.util.List; import java.util.regex.PatternSyntaxException; +/** + * Utility class of string functions. + * + * @author James Moger + * + */ public class StringUtils { public static final String MD5_TYPE = "MD5:"; + /** + * Returns true if the string is null or empty. + * + * @param value + * @return true if string is null or empty + */ public static boolean isEmpty(String value) { return value == null || value.trim().length() == 0; } + /** + * Replaces carriage returns and line feeds with html line breaks. + * + * @param string + * @return plain text with html line breaks + */ public static String breakLinesForHtml(String string) { return string.replace("\r\n", "
").replace("\r", "
").replace("\n", "
"); } + /** + * Prepare text for html presentation. Replace sensitive characters with + * html entities. + * + * @param inStr + * @param changeSpace + * @return plain text escaped for html + */ public static String escapeForHtml(String inStr, boolean changeSpace) { StringBuffer retStr = new StringBuffer(); int i = 0; @@ -58,11 +84,23 @@ public class StringUtils { return retStr.toString(); } + /** + * Decode html entities back into plain text characters. + * + * @param inStr + * @return returns plain text from html + */ public static String decodeFromHtml(String inStr) { return inStr.replace("&", "&").replace("<", "<").replace(">", ">") .replace(""", "\"").replace(" ", " "); } + /** + * Encodes a url parameter by escaping troublesome characters. + * + * @param inStr + * @return properly escaped url + */ public static String encodeURL(String inStr) { StringBuffer retStr = new StringBuffer(); int i = 0; @@ -79,10 +117,24 @@ public class StringUtils { return retStr.toString(); } + /** + * Flatten the list of strings into a single string with a space separator. + * + * @param values + * @return flattened list + */ public static String flattenStrings(List values) { return flattenStrings(values, " "); } + /** + * Flatten the list of strings into a single string with the specified + * separator. + * + * @param values + * @param separator + * @return flattened list + */ public static String flattenStrings(List values, String separator) { StringBuilder sb = new StringBuilder(); for (String value : values) { @@ -91,6 +143,15 @@ public class StringUtils { return sb.toString().trim(); } + /** + * Returns a string trimmed to a maximum length with trailing ellipses. If + * the string length is shorter than the max, the original string is + * returned. + * + * @param value + * @param max + * @return trimmed string + */ public static String trimString(String value, int max) { if (value.length() <= max) { return value; @@ -98,10 +159,25 @@ public class StringUtils { return value.substring(0, max - 3) + "..."; } + /** + * Returns a trimmed shortlog message. + * + * @param string + * @return trimmed shortlog message + */ public static String trimShortLog(String string) { return trimString(string, 60); } + /** + * Left pad a string with the specified character, if the string length is + * less than the specified length. + * + * @param input + * @param length + * @param pad + * @return left-padded string + */ public static String leftPad(String input, int length, char pad) { if (input.length() < length) { StringBuilder sb = new StringBuilder(); @@ -114,6 +190,15 @@ public class StringUtils { return input; } + /** + * Right pad a string with the specified character, if the string length is + * less then the specified length. + * + * @param input + * @param length + * @param pad + * @return right-padded string + */ public static String rightPad(String input, int length, char pad) { if (input.length() < length) { StringBuilder sb = new StringBuilder(); @@ -126,6 +211,12 @@ public class StringUtils { return input; } + /** + * Calculates the SHA1 of the string. + * + * @param text + * @return sha1 of the string + */ public static String getSHA1(String text) { try { byte[] bytes = text.getBytes("iso-8859-1"); @@ -135,6 +226,12 @@ public class StringUtils { } } + /** + * Calculates the SHA1 of the byte array. + * + * @param bytes + * @return sha1 of the byte array + */ public static String getSHA1(byte[] bytes) { try { MessageDigest md = MessageDigest.getInstance("SHA-1"); @@ -146,6 +243,12 @@ public class StringUtils { } } + /** + * Calculates the MD5 of the string. + * + * @param string + * @return md5 of the string + */ public static String getMD5(String string) { try { MessageDigest md = MessageDigest.getInstance("MD5"); @@ -160,6 +263,12 @@ public class StringUtils { } } + /** + * Returns the hex representation of the byte array. + * + * @param bytes + * @return byte array as hex string + */ private static String toHex(byte[] bytes) { StringBuilder sb = new StringBuilder(bytes.length * 2); for (int i = 0; i < bytes.length; i++) { @@ -171,6 +280,13 @@ public class StringUtils { return sb.toString(); } + /** + * Returns the root path of the specified path. Returns a blank string if + * there is no root path. + * + * @param path + * @return root path or blank + */ public static String getRootPath(String path) { if (path.indexOf('/') > -1) { return path.substring(0, path.lastIndexOf('/')); @@ -178,6 +294,14 @@ public class StringUtils { return ""; } + /** + * Returns the path remainder after subtracting the basePath from the + * fullPath. + * + * @param basePath + * @param fullPath + * @return the relative path + */ public static String getRelativePath(String basePath, String fullPath) { String relativePath = fullPath.substring(basePath.length()).replace('\\', '/'); if (relativePath.charAt(0) == '/') { @@ -186,10 +310,23 @@ public class StringUtils { return relativePath; } + /** + * Splits the space-separated string into a list of strings. + * + * @param value + * @return list of strings + */ public static List getStringsFromValue(String value) { return getStringsFromValue(value, " "); } + /** + * Splits the string into a list of string by the specified separator. + * + * @param value + * @param separator + * @return list of strings + */ public static List getStringsFromValue(String value, String separator) { List strings = new ArrayList(); try { diff --git a/src/com/gitblit/utils/SyndicationUtils.java b/src/com/gitblit/utils/SyndicationUtils.java index 80a1b288..fb40dd56 100644 --- a/src/com/gitblit/utils/SyndicationUtils.java +++ b/src/com/gitblit/utils/SyndicationUtils.java @@ -35,8 +35,26 @@ import com.sun.syndication.feed.synd.SyndImageImpl; import com.sun.syndication.io.FeedException; import com.sun.syndication.io.SyndFeedOutput; +/** + * Utility class for RSS feeds. + * + * @author James Moger + * + */ public class SyndicationUtils { + /** + * Outputs an RSS feed of the list of commits to the outputstream. + * + * @param hostUrl + * @param title + * @param description + * @param repository + * @param commits + * @param os + * @throws IOException + * @throws FeedException + */ public static void toRSS(String hostUrl, String title, String description, String repository, List commits, OutputStream os) throws IOException, FeedException { diff --git a/src/com/gitblit/utils/TicgitUtils.java b/src/com/gitblit/utils/TicgitUtils.java index 48e8558c..87a2b3ae 100644 --- a/src/com/gitblit/utils/TicgitUtils.java +++ b/src/com/gitblit/utils/TicgitUtils.java @@ -30,15 +30,28 @@ import com.gitblit.models.RefModel; import com.gitblit.models.TicketModel; import com.gitblit.models.TicketModel.Comment; +/** + * Utility class for reading Ticgit issues. + * + * @author James Moger + * + */ public class TicgitUtils { static final Logger LOGGER = LoggerFactory.getLogger(TicgitUtils.class); - public static RefModel getTicketsBranch(Repository r) { + /** + * Returns a RefModel for the Ticgit branch in the repository. If the branch + * can not be found, null is returned. + * + * @param repository + * @return a refmodel for the ticgit branch or null + */ + public static RefModel getTicketsBranch(Repository repository) { RefModel ticgitBranch = null; try { // search for ticgit branch in local heads - for (RefModel ref : JGitUtils.getLocalBranches(r, false, -1)) { + for (RefModel ref : JGitUtils.getLocalBranches(repository, false, -1)) { if (ref.displayName.endsWith("ticgit")) { ticgitBranch = ref; break; @@ -47,7 +60,7 @@ public class TicgitUtils { // search for ticgit branch in remote heads if (ticgitBranch == null) { - for (RefModel ref : JGitUtils.getRemoteBranches(r, false, -1)) { + for (RefModel ref : JGitUtils.getRemoteBranches(repository, false, -1)) { if (ref.displayName.endsWith("ticgit")) { ticgitBranch = ref; break; @@ -60,19 +73,25 @@ public class TicgitUtils { return ticgitBranch; } - public static List getTickets(Repository r) { - RefModel ticgitBranch = getTicketsBranch(r); + /** + * Returns a list of all tickets in the ticgit branch of the repository. + * + * @param repository + * @return list of tickets + */ + public static List getTickets(Repository repository) { + RefModel ticgitBranch = getTicketsBranch(repository); if (ticgitBranch == null) { return null; } RevCommit commit = (RevCommit) ticgitBranch.referencedObject; - List paths = JGitUtils.getFilesInPath(r, null, commit); + List paths = JGitUtils.getFilesInPath(repository, null, commit); List tickets = new ArrayList(); for (PathModel ticketFolder : paths) { if (ticketFolder.isTree()) { try { TicketModel t = new TicketModel(ticketFolder.name); - readTicketContents(r, ticgitBranch, t); + loadTicketContents(repository, ticgitBranch, t); tickets.add(t); } catch (Throwable t) { LOGGER.error("Failed to get a ticket!", t); @@ -84,12 +103,20 @@ public class TicgitUtils { return tickets; } - public static TicketModel getTicket(Repository r, String ticketFolder) { - RefModel ticketsBranch = getTicketsBranch(r); + /** + * Returns a TicketModel for the specified ticgit ticket. Returns null if + * the ticket does not exist or some other error occurs. + * + * @param repository + * @param ticketFolder + * @return a ticket + */ + public static TicketModel getTicket(Repository repository, String ticketFolder) { + RefModel ticketsBranch = getTicketsBranch(repository); if (ticketsBranch != null) { try { TicketModel ticket = new TicketModel(ticketFolder); - readTicketContents(r, ticketsBranch, ticket); + loadTicketContents(repository, ticketsBranch, ticket); return ticket; } catch (Throwable t) { LOGGER.error("Failed to get ticket " + ticketFolder, t); @@ -98,11 +125,20 @@ public class TicgitUtils { return null; } - private static void readTicketContents(Repository r, RefModel ticketsBranch, TicketModel ticket) { + /** + * Loads the contents of the ticket. + * + * @param repository + * @param ticketsBranch + * @param ticket + */ + private static void loadTicketContents(Repository repository, RefModel ticketsBranch, + TicketModel ticket) { RevCommit commit = (RevCommit) ticketsBranch.referencedObject; - List ticketFiles = JGitUtils.getFilesInPath(r, ticket.name, commit); + List ticketFiles = JGitUtils.getFilesInPath(repository, ticket.name, commit); for (PathModel file : ticketFiles) { - String content = JGitUtils.getStringContent(r, commit.getTree(), file.path).trim(); + String content = JGitUtils.getStringContent(repository, commit.getTree(), file.path) + .trim(); if (file.name.equals("TICKET_ID")) { ticket.id = content; } else if (file.name.equals("TITLE")) { diff --git a/src/com/gitblit/utils/TimeUtils.java b/src/com/gitblit/utils/TimeUtils.java index dcb60ab0..ad814636 100644 --- a/src/com/gitblit/utils/TimeUtils.java +++ b/src/com/gitblit/utils/TimeUtils.java @@ -18,6 +18,12 @@ package com.gitblit.utils; import java.util.Calendar; import java.util.Date; +/** + * Utility class of time functions. + * + * @author James Moger + * + */ public class TimeUtils { public static final long MIN = 1000 * 60L; @@ -29,10 +35,22 @@ public class TimeUtils { public static final long ONEYEAR = ONEDAY * 365L; + /** + * Returns true if date is today. + * + * @param date + * @return true if date is today + */ public static boolean isToday(Date date) { return (System.currentTimeMillis() - date.getTime()) < ONEDAY; } + /** + * Returns true if date is yesterday. + * + * @param date + * @return true if date is yesterday + */ public static boolean isYesterday(Date date) { Calendar cal = Calendar.getInstance(); cal.setTime(date); @@ -40,6 +58,13 @@ public class TimeUtils { return (System.currentTimeMillis() - cal.getTimeInMillis()) < ONEDAY; } + /** + * Returns the string representation of the duration as days, months and/or + * years. + * + * @param days + * @return duration as string in days, months, and/or years + */ public static String duration(int days) { if (days <= 60) { return days + (days > 1 ? " days" : " day"); @@ -69,6 +94,15 @@ public class TimeUtils { } } + /** + * Returns the number of minutes ago between the start time and the end + * time. + * + * @param date + * @param endTime + * @param roundup + * @return difference in minutes + */ public static int minutesAgo(Date date, long endTime, boolean roundup) { long diff = endTime - date.getTime(); int mins = (int) (diff / MIN); @@ -78,10 +112,24 @@ public class TimeUtils { return mins; } + /** + * Return the difference in minutes between now and the date. + * + * @param date + * @param roundup + * @return minutes ago + */ public static int minutesAgo(Date date, boolean roundup) { return minutesAgo(date, System.currentTimeMillis(), roundup); } + /** + * Return the difference in hours between now and the date. + * + * @param date + * @param roundup + * @return hours ago + */ public static int hoursAgo(Date date, boolean roundup) { long diff = System.currentTimeMillis() - date.getTime(); int hours = (int) (diff / ONEHOUR); @@ -91,6 +139,13 @@ public class TimeUtils { return hours; } + /** + * Return the difference in days between now and the date. + * + * @param date + * @param roundup + * @return days ago + */ public static int daysAgo(Date date, boolean roundup) { long diff = System.currentTimeMillis() - date.getTime(); int days = (int) (diff / ONEDAY); @@ -100,14 +155,35 @@ public class TimeUtils { return days; } + /** + * Returns the string representation of the duration between now and the + * date. + * + * @param date + * @return duration as a string + */ public static String timeAgo(Date date) { return timeAgo(date, false); } + /** + * Returns the CSS class for the date based on its age from Now. + * + * @param date + * @return the css class + */ public static String timeAgoCss(Date date) { return timeAgo(date, true); } + /** + * Returns the string representation of the duration OR the css class for + * the duration. + * + * @param date + * @param css + * @return the string representation of the duration OR the css class + */ private static String timeAgo(Date date, boolean css) { String ago = null; if (isToday(date) || isYesterday(date)) {