diff options
Diffstat (limited to 'org.eclipse.jgit/src/org')
689 files changed, 13353 insertions, 5168 deletions
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/annotations/Nullable.java b/org.eclipse.jgit/src/org/eclipse/jgit/annotations/Nullable.java index 7b9156710f..f8a7a366d4 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/annotations/Nullable.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/annotations/Nullable.java @@ -89,7 +89,6 @@ import java.lang.annotation.Target; * @see <a href= * "http://types.cs.washington.edu/checker-framework/current/checker-framework-manual.html#faq-array-syntax-meaning"> * The checker-framework manual</a> - * * @since 4.2 */ @Documented diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/AddCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/AddCommand.java index 1ed79449ef..f0408ab3d4 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/AddCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/AddCommand.java @@ -91,8 +91,10 @@ public class AddCommand extends GitCommand<DirCache> { private boolean update = false; /** + * Constructor for AddCommand * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ public AddCommand(Repository repo) { super(repo); @@ -119,7 +121,10 @@ public class AddCommand extends GitCommand<DirCache> { /** * Allow clients to provide their own implementation of a FileTreeIterator + * * @param f + * a {@link org.eclipse.jgit.treewalk.WorkingTreeIterator} + * object. * @return {@code this} */ public AddCommand setWorkingTreeIterator(WorkingTreeIterator f) { @@ -128,11 +133,11 @@ public class AddCommand extends GitCommand<DirCache> { } /** + * {@inheritDoc} + * <p> * Executes the {@code Add} command. Each instance of this class should only * be used for one invocation of the command. Don't call this method twice * on an instance. - * - * @return the DirCache after Add */ @Override public DirCache call() throws GitAPIException, NoFilepatternException { @@ -260,17 +265,18 @@ public class AddCommand extends GitCommand<DirCache> { } /** + * Set whether to only match against already tracked files + * * @param update * If set to true, the command only matches {@code filepattern} * against already tracked files in the index rather than the * working tree. That means that it will never stage new files, * but that it will stage modified new contents of tracked files * and that it will remove files from the index if the - * corresponding files in the working tree have been removed. - * In contrast to the git command line a {@code filepattern} must - * exist also if update is set to true as there is no - * concept of a working directory here. - * + * corresponding files in the working tree have been removed. In + * contrast to the git command line a {@code filepattern} must + * exist also if update is set to true as there is no concept of + * a working directory here. * @return {@code this} */ public AddCommand setUpdate(boolean update) { @@ -279,7 +285,9 @@ public class AddCommand extends GitCommand<DirCache> { } /** - * @return is the parameter update is set + * Whether to only match against already tracked files + * + * @return whether to only match against already tracked files */ public boolean isUpdate() { return update; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/AddNoteCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/AddNoteCommand.java index fa88fb78ee..f80c8c76ed 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/AddNoteCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/AddNoteCommand.java @@ -75,12 +75,16 @@ public class AddNoteCommand extends GitCommand<Note> { private String notesRef = Constants.R_NOTES_COMMITS; /** + * Constructor for AddNoteCommand + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected AddNoteCommand(Repository repo) { super(repo); } + /** {@inheritDoc} */ @Override public Note call() throws GitAPIException { checkCallable(); @@ -108,6 +112,7 @@ public class AddNoteCommand extends GitCommand<Note> { * has a note, the existing note will be replaced. * * @param id + * a {@link org.eclipse.jgit.revwalk.RevObject} * @return {@code this} */ public AddNoteCommand setObjectId(RevObject id) { @@ -117,6 +122,8 @@ public class AddNoteCommand extends GitCommand<Note> { } /** + * Set the notes message + * * @param message * the notes message used when adding a note * @return {@code this} @@ -152,12 +159,13 @@ public class AddNoteCommand extends GitCommand<Note> { } /** + * Set name of a {@code Ref} to read notes from + * * @param notesRef * the ref to read notes from. Note, the default value of - * {@link Constants#R_NOTES_COMMITS} will be used if nothing is - * set + * {@link org.eclipse.jgit.lib.Constants#R_NOTES_COMMITS} will be + * used if nothing is set * @return {@code this} - * * @see Constants#R_NOTES_COMMITS */ public AddNoteCommand setNotesRef(String notesRef) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/ApplyCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/ApplyCommand.java index ba5673d977..cfc55d8cc6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/ApplyCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/ApplyCommand.java @@ -87,6 +87,8 @@ public class ApplyCommand extends GitCommand<ApplyResult> { } /** + * Set patch + * * @param in * the patch to apply * @return this instance @@ -98,16 +100,13 @@ public class ApplyCommand extends GitCommand<ApplyResult> { } /** + * {@inheritDoc} + * <p> * Executes the {@code ApplyCommand} command with all the options and * parameters collected by the setter methods (e.g. * {@link #setPatch(InputStream)} of this class. Each instance of this class * should only be used for one invocation of the command. Don't call this * method twice on an instance. - * - * @return an {@link ApplyResult} object representing the command result - * @throws GitAPIException - * @throws PatchFormatException - * @throws PatchApplyException */ @Override public ApplyResult call() throws GitAPIException, PatchFormatException, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/ApplyResult.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/ApplyResult.java index 2ef6650e91..60561fce58 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/ApplyResult.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/ApplyResult.java @@ -47,7 +47,7 @@ import java.util.ArrayList; import java.util.List; /** - * Encapsulates the result of a {@link ApplyCommand} + * Encapsulates the result of a {@link org.eclipse.jgit.api.ApplyCommand} * * @since 2.0 */ @@ -56,6 +56,8 @@ public class ApplyResult { private List<File> updatedFiles = new ArrayList<>(); /** + * Add updated file + * * @param f * an updated file * @return this instance @@ -67,6 +69,8 @@ public class ApplyResult { } /** + * Get updated files + * * @return updated files */ public List<File> getUpdatedFiles() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/ArchiveCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/ArchiveCommand.java index 7ea8e73b36..c29ed0e22d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/ArchiveCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/ArchiveCommand.java @@ -70,19 +70,16 @@ import org.eclipse.jgit.treewalk.filter.PathFilterGroup; /** * Create an archive of files from a named tree. * <p> - * Examples (<code>git</code> is a {@link Git} instance): + * Examples (<code>git</code> is a {@link org.eclipse.jgit.api.Git} instance): * <p> * Create a tarball from HEAD: * * <pre> * ArchiveCommand.registerFormat("tar", new TarFormat()); * try { - * git.archive() - * .setTree(db.resolve("HEAD")) - * .setOutputStream(out) - * .call(); + * git.archive().setTree(db.resolve("HEAD")).setOutputStream(out).call(); * } finally { - * ArchiveCommand.unregisterFormat("tar"); + * ArchiveCommand.unregisterFormat("tar"); * } * </pre> * <p> @@ -103,7 +100,6 @@ import org.eclipse.jgit.treewalk.filter.PathFilterGroup; * * @see <a href="http://git-htmldocs.googlecode.com/git/git-archive.html" >Git * documentation about archive</a> - * * @since 3.1 */ public class ArchiveCommand extends GitCommand<OutputStream> { @@ -383,7 +379,10 @@ public class ArchiveCommand extends GitCommand<OutputStream> { private String suffix; /** + * Constructor for ArchiveCommand + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ public ArchiveCommand(Repository repo) { super(repo); @@ -440,9 +439,7 @@ public class ArchiveCommand extends GitCommand<OutputStream> { } } - /** - * @return the stream to which the archive has been written - */ + /** {@inheritDoc} */ @Override public OutputStream call() throws GitAPIException { checkCallable(); @@ -456,6 +453,8 @@ public class ArchiveCommand extends GitCommand<OutputStream> { } /** + * Set the tag, commit, or tree object to produce an archive for + * * @param tree * the tag, commit, or tree object to produce an archive for * @return this @@ -470,6 +469,8 @@ public class ArchiveCommand extends GitCommand<OutputStream> { } /** + * Set string prefixed to filenames in archive + * * @param prefix * string prefixed to filenames in archive (e.g., "master/"). * null means to not use any leading prefix. @@ -502,8 +503,10 @@ public class ArchiveCommand extends GitCommand<OutputStream> { } /** + * Set output stream + * * @param out - * the stream to which to write the archive + * the stream to which to write the archive * @return this */ public ArchiveCommand setOutputStream(OutputStream out) { @@ -512,10 +515,11 @@ public class ArchiveCommand extends GitCommand<OutputStream> { } /** + * Set archive format + * * @param fmt - * archive format (e.g., "tar" or "zip"). - * null means to choose automatically based on - * the archive filename. + * archive format (e.g., "tar" or "zip"). null means to choose + * automatically based on the archive filename. * @return this */ public ArchiveCommand setFormat(String fmt) { @@ -524,6 +528,8 @@ public class ArchiveCommand extends GitCommand<OutputStream> { } /** + * Set archive format options + * * @param options * archive format options (e.g., level=9 for zip compression). * @return this diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/BlameCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/BlameCommand.java index b1c81ff154..f7576e9e9b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/BlameCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/BlameCommand.java @@ -69,7 +69,8 @@ import org.eclipse.jgit.util.IO; import org.eclipse.jgit.util.io.AutoLFInputStream; /** - * Blame command for building a {@link BlameResult} for a file path. + * Blame command for building a {@link org.eclipse.jgit.blame.BlameResult} for a + * file path. */ public class BlameCommand extends GitCommand<BlameResult> { @@ -86,7 +87,10 @@ public class BlameCommand extends GitCommand<BlameResult> { private Boolean followFileRenames; /** + * Constructor for BlameCommand + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ public BlameCommand(Repository repo) { super(repo); @@ -108,6 +112,7 @@ public class BlameCommand extends GitCommand<BlameResult> { * Set diff algorithm * * @param diffAlgorithm + * a {@link org.eclipse.jgit.diff.DiffAlgorithm} object. * @return this command */ public BlameCommand setDiffAlgorithm(DiffAlgorithm diffAlgorithm) { @@ -119,6 +124,7 @@ public class BlameCommand extends GitCommand<BlameResult> { * Set raw text comparator * * @param textComparator + * a {@link org.eclipse.jgit.diff.RawTextComparator} * @return this command */ public BlameCommand setTextComparator(RawTextComparator textComparator) { @@ -130,6 +136,7 @@ public class BlameCommand extends GitCommand<BlameResult> { * Set start commit id * * @param commit + * id of a commit * @return this command */ public BlameCommand setStartCommit(AnyObjectId commit) { @@ -164,7 +171,7 @@ public class BlameCommand extends GitCommand<BlameResult> { * most recent commit to stop traversal at. Usually an active * branch tip, tag, or HEAD. * @return {@code this} - * @throws IOException + * @throws java.io.IOException * the repository cannot be read. */ public BlameCommand reverse(AnyObjectId start, AnyObjectId end) @@ -182,7 +189,7 @@ public class BlameCommand extends GitCommand<BlameResult> { * most recent commits to stop traversal at. Usually an active * branch tip, tag, or HEAD. * @return {@code this} - * @throws IOException + * @throws java.io.IOException * the repository cannot be read. */ public BlameCommand reverse(AnyObjectId start, Collection<ObjectId> end) @@ -193,10 +200,10 @@ public class BlameCommand extends GitCommand<BlameResult> { } /** + * {@inheritDoc} + * <p> * Generate a list of lines with information about when the lines were * introduced into the file path. - * - * @return list of lines */ @Override public BlameResult call() throws GitAPIException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/CheckoutCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/CheckoutCommand.java index 6b20da3ede..aa9939edd3 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/CheckoutCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/CheckoutCommand.java @@ -43,6 +43,8 @@ */ package org.eclipse.jgit.api; +import static org.eclipse.jgit.treewalk.TreeWalk.OperationType.CHECKOUT_OP; + import java.io.IOException; import java.text.MessageFormat; import java.util.ArrayList; @@ -89,7 +91,7 @@ import org.eclipse.jgit.treewalk.filter.PathFilterGroup; /** * Checkout a branch to the working tree. * <p> - * Examples (<code>git</code> is a {@link Git} instance): + * Examples (<code>git</code> is a {@link org.eclipse.jgit.api.Git} instance): * <p> * Check out an existing branch: * @@ -124,9 +126,9 @@ import org.eclipse.jgit.treewalk.filter.PathFilterGroup; * .setStartPoint("origin/stable").call(); * </pre> * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-checkout.html" - * >Git documentation about Checkout</a> + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-checkout.html" >Git + * documentation about Checkout</a> */ public class CheckoutCommand extends GitCommand<Ref> { @@ -181,26 +183,17 @@ public class CheckoutCommand extends GitCommand<Ref> { private Set<String> actuallyModifiedPaths; /** + * Constructor for CheckoutCommand + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected CheckoutCommand(Repository repo) { super(repo); this.paths = new LinkedList<>(); } - /** - * @throws RefAlreadyExistsException - * when trying to create (without force) a branch with a name - * that already exists - * @throws RefNotFoundException - * if the start point or branch can not be found - * @throws InvalidRefNameException - * if the provided name is <code>null</code> or otherwise - * invalid - * @throws CheckoutConflictException - * if the checkout results in a conflict - * @return the newly created branch - */ + /** {@inheritDoc} */ @Override public Ref call() throws GitAPIException, RefAlreadyExistsException, RefNotFoundException, InvalidRefNameException, @@ -416,11 +409,12 @@ public class CheckoutCommand extends GitCommand<Ref> { /** * Checkout paths into index and working directory, firing a - * {@link WorkingTreeModifiedEvent} if the working tree was modified. + * {@link org.eclipse.jgit.events.WorkingTreeModifiedEvent} if the working + * tree was modified. * * @return this instance - * @throws IOException - * @throws RefNotFoundException + * @throws java.io.IOException + * @throws org.eclipse.jgit.api.errors.RefNotFoundException */ protected CheckoutCommand checkoutPaths() throws IOException, RefNotFoundException { @@ -468,7 +462,8 @@ public class CheckoutCommand extends GitCommand<Ref> { if (path.equals(previousPath)) continue; - final EolStreamType eolStreamType = treeWalk.getEolStreamType(); + final EolStreamType eolStreamType = treeWalk + .getEolStreamType(CHECKOUT_OP); final String filterCommand = treeWalk .getFilterCommand(Constants.ATTR_FILTER_TYPE_SMUDGE); editor.add(new PathEdit(path) { @@ -508,7 +503,8 @@ public class CheckoutCommand extends GitCommand<Ref> { while (treeWalk.next()) { final ObjectId blobId = treeWalk.getObjectId(0); final FileMode mode = treeWalk.getFileMode(0); - final EolStreamType eolStreamType = treeWalk.getEolStreamType(); + final EolStreamType eolStreamType = treeWalk + .getEolStreamType(CHECKOUT_OP); final String filterCommand = treeWalk .getFilterCommand(Constants.ATTR_FILTER_TYPE_SMUDGE); final String path = treeWalk.getPathString(); @@ -735,6 +731,8 @@ public class CheckoutCommand extends GitCommand<Ref> { } /** + * Get the result, never <code>null</code> + * * @return the result, never <code>null</code> */ public CheckoutResult getResult() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/CheckoutResult.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/CheckoutResult.java index 2186eb4b5a..16f4685bc4 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/CheckoutResult.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/CheckoutResult.java @@ -46,8 +46,7 @@ import java.util.ArrayList; import java.util.List; /** - * Encapsulates the result of a {@link CheckoutCommand} - * + * Encapsulates the result of a {@link org.eclipse.jgit.api.CheckoutCommand} */ public class CheckoutResult { @@ -168,6 +167,8 @@ public class CheckoutResult { } /** + * Get status + * * @return the status */ public Status getStatus() { @@ -175,33 +176,44 @@ public class CheckoutResult { } /** + * Get list of file that created a checkout conflict + * * @return the list of files that created a checkout conflict, or an empty - * list if {@link #getStatus()} is not {@link Status#CONFLICTS}; + * list if {@link #getStatus()} is not + * {@link org.eclipse.jgit.api.CheckoutResult.Status#CONFLICTS}; */ public List<String> getConflictList() { return conflictList; } /** + * Get the list of files that could not be deleted during checkout + * * @return the list of files that could not be deleted during checkout, or * an empty list if {@link #getStatus()} is not - * {@link Status#NONDELETED}; + * {@link org.eclipse.jgit.api.CheckoutResult.Status#NONDELETED}; */ public List<String> getUndeletedList() { return undeletedList; } /** + * Get the list of files that where modified during checkout + * * @return the list of files that where modified during checkout, or an - * empty list if {@link #getStatus()} is not {@link Status#OK} + * empty list if {@link #getStatus()} is not + * {@link org.eclipse.jgit.api.CheckoutResult.Status#OK} */ public List<String> getModifiedList() { return modifiedList; } /** + * Get the list of files that where removed during checkout + * * @return the list of files that where removed during checkout, or an empty - * list if {@link #getStatus()} is not {@link Status#OK} + * list if {@link #getStatus()} is not + * {@link org.eclipse.jgit.api.CheckoutResult.Status#OK} */ public List<String> getRemovedList() { return removedList; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/CherryPickCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/CherryPickCommand.java index eed7b2a254..771798a50d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/CherryPickCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/CherryPickCommand.java @@ -96,25 +96,22 @@ public class CherryPickCommand extends GitCommand<CherryPickResult> { private boolean noCommit = false; /** + * Constructor for CherryPickCommand + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected CherryPickCommand(Repository repo) { super(repo); } /** + * {@inheritDoc} + * <p> * Executes the {@code Cherry-Pick} command with all the options and * parameters collected by the setter methods (e.g. {@link #include(Ref)} of * this class. Each instance of this class should only be used for one * invocation of the command. Don't call this method twice on an instance. - * - * @return the result of the cherry-pick - * @throws GitAPIException - * @throws WrongRepositoryStateException - * @throws ConcurrentRefUpdateException - * @throws UnmergedPathsException - * @throws NoMessageException - * @throws NoHeadException */ @Override public CherryPickResult call() throws GitAPIException, NoMessageException, @@ -224,6 +221,8 @@ public class CherryPickCommand extends GitCommand<CherryPickResult> { } /** + * Include a reference to a commit + * * @param commit * a reference to a commit which is cherry-picked to the current * head @@ -236,6 +235,8 @@ public class CherryPickCommand extends GitCommand<CherryPickResult> { } /** + * Include a commit + * * @param commit * the Id of a commit which is cherry-picked to the current head * @return {@code this} @@ -245,6 +246,8 @@ public class CherryPickCommand extends GitCommand<CherryPickResult> { } /** + * Include a commit + * * @param name * a name given to the commit * @param commit @@ -257,6 +260,8 @@ public class CherryPickCommand extends GitCommand<CherryPickResult> { } /** + * Set the name that should be used in the "OURS" place for conflict markers + * * @param ourCommitName * the name that should be used in the "OURS" place for conflict * markers @@ -284,6 +289,8 @@ public class CherryPickCommand extends GitCommand<CherryPickResult> { } /** + * Set the {@code MergeStrategy} + * * @param strategy * The merge strategy to use during this Cherry-pick. * @return {@code this} @@ -295,6 +302,8 @@ public class CherryPickCommand extends GitCommand<CherryPickResult> { } /** + * Set the (1-based) parent number to diff against + * * @param mainlineParentNumber * the (1-based) parent number to diff against. This allows * cherry-picking of merges. @@ -332,6 +341,7 @@ public class CherryPickCommand extends GitCommand<CherryPickResult> { return headName; } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/CherryPickResult.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/CherryPickResult.java index b121291fca..ff55aebd91 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/CherryPickResult.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/CherryPickResult.java @@ -46,12 +46,11 @@ import java.util.List; import java.util.Map; import org.eclipse.jgit.lib.Ref; -import org.eclipse.jgit.merge.ResolveMerger; import org.eclipse.jgit.merge.ResolveMerger.MergeFailureReason; import org.eclipse.jgit.revwalk.RevCommit; /** - * Encapsulates the result of a {@link CherryPickCommand}. + * Encapsulates the result of a {@link org.eclipse.jgit.api.CherryPickCommand}. */ public class CherryPickResult { @@ -91,6 +90,8 @@ public class CherryPickResult { private final Map<String, MergeFailureReason> failingPaths; /** + * Constructor for CherryPickResult + * * @param newHead * commit the head points at after this cherry-pick * @param cherryPickedRefs @@ -104,9 +105,12 @@ public class CherryPickResult { } /** + * Constructor for CherryPickResult + * * @param failingPaths * list of paths causing this cherry-pick to fail (see - * {@link ResolveMerger#getFailingPaths()} for details) + * {@link org.eclipse.jgit.merge.ResolveMerger#getFailingPaths()} + * for details) */ public CherryPickResult(Map<String, MergeFailureReason> failingPaths) { this.status = CherryPickStatus.FAILED; @@ -130,6 +134,8 @@ public class CherryPickResult { CherryPickStatus.CONFLICTING); /** + * Get status + * * @return the status this cherry-pick resulted in */ public CherryPickStatus getStatus() { @@ -137,28 +143,34 @@ public class CherryPickResult { } /** + * Get the new head after this cherry-pick + * * @return the commit the head points at after this cherry-pick, * <code>null</code> if {@link #getStatus} is not - * {@link CherryPickStatus#OK} + * {@link org.eclipse.jgit.api.CherryPickResult.CherryPickStatus#OK} */ public RevCommit getNewHead() { return newHead; } /** + * Get the cherry-picked {@code Ref}s + * * @return the list of successfully cherry-picked <code>Ref</code>'s, * <code>null</code> if {@link #getStatus} is not - * {@link CherryPickStatus#OK} + * {@link org.eclipse.jgit.api.CherryPickResult.CherryPickStatus#OK} */ public List<Ref> getCherryPickedRefs() { return cherryPickedRefs; } /** + * Get the list of paths causing this cherry-pick to fail + * * @return the list of paths causing this cherry-pick to fail (see - * {@link ResolveMerger#getFailingPaths()} for details), - * <code>null</code> if {@link #getStatus} is not - * {@link CherryPickStatus#FAILED} + * {@link org.eclipse.jgit.merge.ResolveMerger#getFailingPaths()} + * for details), <code>null</code> if {@link #getStatus} is not + * {@link org.eclipse.jgit.api.CherryPickResult.CherryPickStatus#FAILED} */ public Map<String, MergeFailureReason> getFailingPaths() { return failingPaths; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/CleanCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/CleanCommand.java index e41a03b81a..c81425067c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/CleanCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/CleanCommand.java @@ -79,21 +79,22 @@ public class CleanCommand extends GitCommand<Set<String>> { private boolean force = false; /** + * Constructor for CleanCommand + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected CleanCommand(Repository repo) { super(repo); } /** + * {@inheritDoc} + * <p> * Executes the {@code clean} command with all the options and parameters * collected by the setter methods of this class. Each instance of this * class should only be used for one invocation of the command (means: one * call to {@link #call()}) - * - * @return a set of strings representing each file cleaned. - * @throws GitAPIException - * @throws NoWorkTreeException */ @Override public Set<String> call() throws NoWorkTreeException, GitAPIException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/CloneCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/CloneCommand.java index bde8e63d1d..6d3afc619a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/CloneCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/CloneCommand.java @@ -77,8 +77,8 @@ import org.eclipse.jgit.transport.RefSpec; import org.eclipse.jgit.transport.RemoteConfig; import org.eclipse.jgit.transport.TagOpt; import org.eclipse.jgit.transport.URIish; -import org.eclipse.jgit.util.FS; import org.eclipse.jgit.util.FileUtils; +import org.eclipse.jgit.util.FS; /** * Clone a repository into a new working directory @@ -96,6 +96,8 @@ public class CloneCommand extends TransportCommand<CloneCommand, Git> { private boolean bare; + private FS fs; + private String remote = Constants.DEFAULT_REMOTE_NAME; private String branch = Constants.HEAD; @@ -168,6 +170,8 @@ public class CloneCommand extends TransportCommand<CloneCommand, Git> { } /** + * {@inheritDoc} + * <p> * Executes the {@code Clone} command. * * The Git instance returned by this command needs to be closed by the @@ -175,11 +179,6 @@ public class CloneCommand extends TransportCommand<CloneCommand, Git> { * instance. It is recommended to call this method as soon as you don't need * a reference to this {@link Git} instance and the underlying * {@link Repository} instance anymore. - * - * @return the newly created {@code Git} object with associated repository - * @throws InvalidRemoteException - * @throws org.eclipse.jgit.api.errors.TransportException - * @throws GitAPIException */ @Override public Git call() throws GitAPIException, InvalidRemoteException, @@ -263,6 +262,9 @@ public class CloneCommand extends TransportCommand<CloneCommand, Git> { private Repository init() throws GitAPIException { InitCommand command = Git.init(); command.setBare(bare); + if (fs != null) { + command.setFs(fs); + } if (directory != null) { command.setDirectory(directory); } @@ -451,9 +453,11 @@ public class CloneCommand extends TransportCommand<CloneCommand, Git> { } /** + * Set the URI to clone from + * * @param uri - * the URI to clone from, or {@code null} to unset the URI. - * The URI must be set before {@link #call} is called. + * the URI to clone from, or {@code null} to unset the URI. The + * URI must be set before {@link #call} is called. * @return this instance */ public CloneCommand setURI(String uri) { @@ -466,12 +470,11 @@ public class CloneCommand extends TransportCommand<CloneCommand, Git> { * directory isn't set, a name associated with the source uri will be used. * * @see URIish#getHumanishName() - * * @param directory * the directory to clone to, or {@code null} if the directory * name should be taken from the source uri * @return this instance - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * if the combination of directory, gitDir and bare is illegal. * E.g. if for a non-bare repository directory and gitDir point * to the same directory of if for a bare repository both @@ -484,11 +487,13 @@ public class CloneCommand extends TransportCommand<CloneCommand, Git> { } /** + * Set the repository meta directory (.git) + * * @param gitDir * the repository meta directory, or {@code null} to choose one * automatically at clone time * @return this instance - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * if the combination of directory, gitDir and bare is illegal. * E.g. if for a non-bare repository directory and gitDir point * to the same directory of if for a bare repository both @@ -502,10 +507,12 @@ public class CloneCommand extends TransportCommand<CloneCommand, Git> { } /** + * Set whether the cloned repository shall be bare + * * @param bare * whether the cloned repository is bare or not * @return this instance - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * if the combination of directory, gitDir and bare is illegal. * E.g. if for a non-bare repository directory and gitDir point * to the same directory of if for a bare repository both @@ -518,6 +525,20 @@ public class CloneCommand extends TransportCommand<CloneCommand, Git> { } /** + * Set the file system abstraction to be used for repositories created by + * this command. + * + * @param fs + * the abstraction. + * @return {@code this} (for chaining calls). + * @since 4.10 + */ + public CloneCommand setFs(FS fs) { + this.fs = fs; + return this; + } + + /** * The remote name used to keep track of the upstream repository for the * clone operation. If no remote name is set, the default value of * <code>Constants.DEFAULT_REMOTE_NAME</code> will be used. @@ -537,13 +558,15 @@ public class CloneCommand extends TransportCommand<CloneCommand, Git> { } /** + * Set the initial branch + * * @param branch * the initial branch to check out when cloning the repository. * Can be specified as ref name (<code>refs/heads/master</code>), - * branch name (<code>master</code>) or tag name (<code>v1.2.3</code>). - * The default is to use the branch pointed to by the cloned - * repository's HEAD and can be requested by passing {@code null} - * or <code>HEAD</code>. + * branch name (<code>master</code>) or tag name + * (<code>v1.2.3</code>). The default is to use the branch + * pointed to by the cloned repository's HEAD and can be + * requested by passing {@code null} or <code>HEAD</code>. * @return this instance */ public CloneCommand setBranch(String branch) { @@ -559,8 +582,8 @@ public class CloneCommand extends TransportCommand<CloneCommand, Git> { * this is set to <code>NullProgressMonitor</code> * * @see NullProgressMonitor - * * @param monitor + * a {@link org.eclipse.jgit.lib.ProgressMonitor} * @return {@code this} */ public CloneCommand setProgressMonitor(ProgressMonitor monitor) { @@ -572,6 +595,8 @@ public class CloneCommand extends TransportCommand<CloneCommand, Git> { } /** + * Set whether all branches have to be fetched + * * @param cloneAllBranches * true when all branches have to be fetched (indicates wildcard * in created fetch refspec), false otherwise. @@ -583,6 +608,8 @@ public class CloneCommand extends TransportCommand<CloneCommand, Git> { } /** + * Set whether to clone submodules + * * @param cloneSubmodules * true to initialize and update submodules. Ignored when * {@link #setBare(boolean)} is set to true. @@ -594,6 +621,8 @@ public class CloneCommand extends TransportCommand<CloneCommand, Git> { } /** + * Set branches to clone + * * @param branchesToClone * collection of branches to clone. Ignored when allSelected is * true. Must be specified as full ref names (e.g. @@ -606,6 +635,8 @@ public class CloneCommand extends TransportCommand<CloneCommand, Git> { } /** + * Set whether to skip checking out a branch + * * @param noCheckout * if set to <code>true</code> no branch will be checked out * after the clone. This enhances performance of the clone @@ -681,10 +712,11 @@ public class CloneCommand extends TransportCommand<CloneCommand, Git> { } private void deleteChildren(File file) throws IOException { - if (!FS.DETECTED.isDirectory(file)) { + File[] files = file.listFiles(); + if (files == null) { return; } - for (File child : file.listFiles()) { + for (File child : files) { FileUtils.delete(child, FileUtils.RECURSIVE | FileUtils.SKIP_MISSING | FileUtils.IGNORE_ERRORS); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/CommitCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/CommitCommand.java index e29fc05463..8a89ba1611 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/CommitCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/CommitCommand.java @@ -140,33 +140,22 @@ public class CommitCommand extends GitCommand<RevCommit> { private Boolean allowEmpty; /** + * Constructor for CommitCommand + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected CommitCommand(Repository repo) { super(repo); } /** + * {@inheritDoc} + * <p> * Executes the {@code commit} command with all the options and parameters * collected by the setter methods of this class. Each instance of this * class should only be used for one invocation of the command (means: one * call to {@link #call()}) - * - * @return a {@link RevCommit} object representing the successful commit. - * @throws NoHeadException - * when called on a git repo without a HEAD reference - * @throws NoMessageException - * when called without specifying a commit message - * @throws UnmergedPathsException - * when the current index contained unmerged paths (conflicts) - * @throws ConcurrentRefUpdateException - * when HEAD or branch ref is updated concurrently by someone - * else - * @throws WrongRepositoryStateException - * when repository is not in the right state for committing - * @throws AbortedByHookException - * if there are either pre-commit or commit-msg hooks present in - * the repository and one of them rejects the commit. */ @Override public RevCommit call() throws GitAPIException, NoHeadException, @@ -602,6 +591,8 @@ public class CommitCommand extends GitCommand<RevCommit> { } /** + * Set the commit message + * * @param message * the commit message used for the {@code commit} * @return {@code this} @@ -613,6 +604,8 @@ public class CommitCommand extends GitCommand<RevCommit> { } /** + * Set whether to allow to create an empty commit + * * @param allowEmpty * whether it should be allowed to create a commit which has the * same tree as it's sole predecessor (a commit which doesn't @@ -623,8 +616,9 @@ public class CommitCommand extends GitCommand<RevCommit> { * <p> * By default when creating a commit containing only specified * paths an attempt to create an empty commit leads to a - * {@link JGitInternalException}. By setting this flag to - * <code>true</code> this exception will not be thrown. + * {@link org.eclipse.jgit.api.errors.JGitInternalException}. By + * setting this flag to <code>true</code> this exception will not + * be thrown. * @return {@code this} * @since 4.2 */ @@ -634,6 +628,8 @@ public class CommitCommand extends GitCommand<RevCommit> { } /** + * Get the commit message + * * @return the commit message used for the <code>commit</code> */ public String getMessage() { @@ -673,10 +669,12 @@ public class CommitCommand extends GitCommand<RevCommit> { } /** + * Get the committer + * * @return the committer used for the {@code commit}. If no committer was * specified {@code null} is returned and the default - * {@link PersonIdent} of this repo is used during execution of the - * command + * {@link org.eclipse.jgit.lib.PersonIdent} of this repo is used + * during execution of the command */ public PersonIdent getCommitter() { return committer; @@ -715,10 +713,12 @@ public class CommitCommand extends GitCommand<RevCommit> { } /** + * Get the author + * * @return the author used for the {@code commit}. If no author was * specified {@code null} is returned and the default - * {@link PersonIdent} of this repo is used during execution of the - * command + * {@link org.eclipse.jgit.lib.PersonIdent} of this repo is used + * during execution of the command */ public PersonIdent getAuthor() { return author; @@ -730,6 +730,8 @@ public class CommitCommand extends GitCommand<RevCommit> { * not affected. This corresponds to the parameter -a on the command line. * * @param all + * whether to auto-stage all files that have been modified and + * deleted * @return {@code this} * @throws JGitInternalException * in case of an illegal combination of arguments/ options @@ -745,11 +747,12 @@ public class CommitCommand extends GitCommand<RevCommit> { } /** - * Used to amend the tip of the current branch. If set to true, the previous - * commit will be amended. This is equivalent to --amend on the command - * line. + * Used to amend the tip of the current branch. If set to {@code true}, the + * previous commit will be amended. This is equivalent to --amend on the + * command line. * * @param amend + * whether to ammend the tip of the current branch * @return {@code this} */ public CommitCommand setAmend(boolean amend) { @@ -790,7 +793,7 @@ public class CommitCommand extends GitCommand<RevCommit> { * will be replaced by the change id. * * @param insertChangeId - * + * whether to insert a change id * @return {@code this} */ public CommitCommand setInsertChangeId(boolean insertChangeId) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/CreateBranchCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/CreateBranchCommand.java index 39420d0ee8..29baf4cd63 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/CreateBranchCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/CreateBranchCommand.java @@ -103,23 +103,16 @@ public class CreateBranchCommand extends GitCommand<Ref> { } /** + * Constructor for CreateBranchCommand + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected CreateBranchCommand(Repository repo) { super(repo); } - /** - * @throws RefAlreadyExistsException - * when trying to create (without force) a branch with a name - * that already exists - * @throws RefNotFoundException - * if the start point can not be found - * @throws InvalidRefNameException - * if the provided name is <code>null</code> or otherwise - * invalid - * @return the newly created branch - */ + /** {@inheritDoc} */ @Override public Ref call() throws GitAPIException, RefAlreadyExistsException, RefNotFoundException, InvalidRefNameException { @@ -297,6 +290,8 @@ public class CreateBranchCommand extends GitCommand<Ref> { } /** + * Set the name of the new branch + * * @param name * the name of the new branch * @return this instance @@ -308,6 +303,8 @@ public class CreateBranchCommand extends GitCommand<Ref> { } /** + * Set whether to create the branch forcefully + * * @param force * if <code>true</code> and the branch with the given name * already exists, the start-point of an existing branch will be @@ -322,6 +319,8 @@ public class CreateBranchCommand extends GitCommand<Ref> { } /** + * Set the start point + * * @param startPoint * corresponds to the start-point option; if <code>null</code>, * the current HEAD will be used @@ -335,6 +334,8 @@ public class CreateBranchCommand extends GitCommand<Ref> { } /** + * Set the start point + * * @param startPoint * corresponds to the start-point option; if <code>null</code>, * the current HEAD will be used @@ -348,6 +349,8 @@ public class CreateBranchCommand extends GitCommand<Ref> { } /** + * Set the upstream mode + * * @param mode * corresponds to the --track/--no-track/--set-upstream options; * may be <code>null</code> diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/DeleteBranchCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/DeleteBranchCommand.java index d7e7e5c294..31e7281d64 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/DeleteBranchCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/DeleteBranchCommand.java @@ -84,19 +84,16 @@ public class DeleteBranchCommand extends GitCommand<List<String>> { private boolean force; /** + * Constructor for DeleteBranchCommand + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected DeleteBranchCommand(Repository repo) { super(repo); } - /** - * @throws NotMergedException - * when trying to delete a branch which has not been merged into - * the currently checked out branch without force - * @throws CannotDeleteCurrentBranchException - * @return the list with the (full) names of the deleted branches - */ + /** {@inheritDoc} */ @Override public List<String> call() throws GitAPIException, NotMergedException, CannotDeleteCurrentBranchException { @@ -181,6 +178,8 @@ public class DeleteBranchCommand extends GitCommand<List<String>> { } /** + * Set the names of the branches to delete + * * @param branchnames * the names of the branches to delete; if not set, this will do * nothing; invalid branch names will simply be ignored @@ -195,6 +194,8 @@ public class DeleteBranchCommand extends GitCommand<List<String>> { } /** + * Set whether to forcefully delete branches + * * @param force * <code>true</code> corresponds to the -D option, * <code>false</code> to the -d option (default) <br> diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/DeleteTagCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/DeleteTagCommand.java index 77e3539996..63a090cafc 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/DeleteTagCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/DeleteTagCommand.java @@ -71,15 +71,16 @@ public class DeleteTagCommand extends GitCommand<List<String>> { private final Set<String> tags = new HashSet<>(); /** + * Constructor for DeleteTagCommand + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected DeleteTagCommand(Repository repo) { super(repo); } - /** - * @return the list with the full names of the deleted tags - */ + /** {@inheritDoc} */ @Override public List<String> call() throws GitAPIException { checkCallable(); @@ -124,6 +125,8 @@ public class DeleteTagCommand extends GitCommand<List<String>> { } /** + * Set names of the tags to delete + * * @param tags * the names of the tags to delete; if not set, this will do * nothing; invalid tag names will simply be ignored diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/DescribeCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/DescribeCommand.java index 68b1bd9e29..01fe4aa9ee 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/DescribeCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/DescribeCommand.java @@ -104,8 +104,10 @@ public class DescribeCommand extends GitCommand<String> { private List<IMatcher> matchers = new ArrayList<>(); /** + * Constructor for DescribeCommand. * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected DescribeCommand(Repository repo) { super(repo); @@ -123,7 +125,7 @@ public class DescribeCommand extends GitCommand<String> { * the supplied commit does not exist. * @throws IncorrectObjectTypeException * the supplied id is not a commit or an annotated tag. - * @throws IOException + * @throws java.io.IOException * a pack file or loose object could not be read. */ public DescribeCommand setTarget(ObjectId target) throws IOException { @@ -135,14 +137,15 @@ public class DescribeCommand extends GitCommand<String> { * Sets the commit to be described. * * @param rev - * Commit ID, tag, branch, ref, etc. - * See {@link Repository#resolve(String)} for allowed syntax. + * Commit ID, tag, branch, ref, etc. See + * {@link org.eclipse.jgit.lib.Repository#resolve(String)} for + * allowed syntax. * @return {@code this} * @throws IncorrectObjectTypeException * the supplied id is not a commit or an annotated tag. - * @throws RefNotFoundException - * the given rev didn't resolve to any object. - * @throws IOException + * @throws org.eclipse.jgit.api.errors.RefNotFoundException + * the given rev didn't resolve to any object. + * @throws java.io.IOException * a pack file or loose object could not be read. */ public DescribeCommand setTarget(String rev) throws IOException, @@ -160,7 +163,6 @@ public class DescribeCommand extends GitCommand<String> { * @param longDesc * <code>true</code> if always the long format should be used. * @return {@code this} - * * @see <a * href="https://www.kernel.org/pub/software/scm/git/docs/git-describe.html" * >Git documentation about describe</a> @@ -180,15 +182,17 @@ public class DescribeCommand extends GitCommand<String> { } /** - * Sets one or more {@code glob(7)} patterns that tags must match to be considered. - * If multiple patterns are provided, tags only need match one of them. + * Sets one or more {@code glob(7)} patterns that tags must match to be + * considered. If multiple patterns are provided, tags only need match one + * of them. * - * @param patterns the {@code glob(7)} pattern or patterns + * @param patterns + * the {@code glob(7)} pattern or patterns * @return {@code this} - * @throws InvalidPatternException if the pattern passed in was invalid. - * - * @see <a - * href="https://www.kernel.org/pub/software/scm/git/docs/git-describe.html" + * @throws org.eclipse.jgit.errors.InvalidPatternException + * if the pattern passed in was invalid. + * @see <a href= + * "https://www.kernel.org/pub/software/scm/git/docs/git-describe.html" * >Git documentation about describe</a> * @since 4.9 */ @@ -229,16 +233,10 @@ public class DescribeCommand extends GitCommand<String> { } /** + * {@inheritDoc} + * <p> * Describes the specified commit. Target defaults to HEAD if no commit was * set explicitly. - * - * @return if there's a tag that points to the commit being described, this - * tag name is returned. Otherwise additional suffix is added to the - * nearest tag, just like git-describe(1). - * <p> - * If none of the ancestors of the commit being described has any - * tags at all, then this method returns null, indicating that - * there's no way to describe this tag. */ @Override public String call() throws GitAPIException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/DiffCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/DiffCommand.java index b137fc53c9..4c6f351142 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/DiffCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/DiffCommand.java @@ -95,19 +95,22 @@ public class DiffCommand extends GitCommand<List<DiffEntry>> { private ProgressMonitor monitor = NullProgressMonitor.INSTANCE; /** + * Constructor for DiffCommand + * * @param repo + * a {@link org.eclipse.jgit.lib.Repository} object. */ protected DiffCommand(Repository repo) { super(repo); } /** + * {@inheritDoc} + * <p> * Executes the {@code Diff} command with all the options and parameters * collected by the setter methods (e.g. {@link #setCached(boolean)} of this * class. Each instance of this class should only be used for one invocation * of the command. Don't call this method twice on an instance. - * - * @return a DiffEntry for each path which is different */ @Override public List<DiffEntry> call() throws GitAPIException { @@ -162,9 +165,10 @@ public class DiffCommand extends GitCommand<List<DiffEntry>> { } /** + * Whether to view the changes staged for the next commit * * @param cached - * whether to view the changes you staged for the next commit + * whether to view the changes staged for the next commit * @return this instance */ public DiffCommand setCached(boolean cached) { @@ -173,6 +177,8 @@ public class DiffCommand extends GitCommand<List<DiffEntry>> { } /** + * Set path filter + * * @param pathFilter * parameter, used to limit the diff to the named path * @return this instance @@ -183,6 +189,8 @@ public class DiffCommand extends GitCommand<List<DiffEntry>> { } /** + * Set old tree + * * @param oldTree * the previous state * @return this instance @@ -193,6 +201,8 @@ public class DiffCommand extends GitCommand<List<DiffEntry>> { } /** + * Set new tree + * * @param newTree * the updated state * @return this instance @@ -203,6 +213,8 @@ public class DiffCommand extends GitCommand<List<DiffEntry>> { } /** + * Set whether to return only names and status of changed files + * * @param showNameAndStatusOnly * whether to return only names and status of changed files * @return this instance @@ -213,6 +225,8 @@ public class DiffCommand extends GitCommand<List<DiffEntry>> { } /** + * Set output stream + * * @param out * the stream to write line data * @return this instance @@ -263,7 +277,6 @@ public class DiffCommand extends GitCommand<List<DiffEntry>> { * is set to <code>NullProgressMonitor</code> * * @see NullProgressMonitor - * * @param monitor * a progress monitor * @return this instance diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/FetchCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/FetchCommand.java index 5270283edd..b2c28dab0c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/FetchCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/FetchCommand.java @@ -122,7 +122,10 @@ public class FetchCommand extends TransportCommand<FetchCommand, FetchResult> { } /** + * Constructor for FetchCommand. + * * @param repo + * a {@link org.eclipse.jgit.lib.Repository} object. */ protected FetchCommand(Repository repo) { super(repo); @@ -210,17 +213,12 @@ public class FetchCommand extends TransportCommand<FetchCommand, FetchResult> { } /** - * Executes the {@code fetch} command with all the options and parameters + * {@inheritDoc} + * <p> + * Execute the {@code fetch} command with all the options and parameters * collected by the setter methods of this class. Each instance of this * class should only be used for one invocation of the command (means: one * call to {@link #call()}) - * - * @return a {@link FetchResult} object representing the successful fetch - * result - * @throws InvalidRemoteException - * when called with an invalid remote uri - * @throws org.eclipse.jgit.api.errors.TransportException - * when an error occurs during transport */ @Override public FetchResult call() throws GitAPIException, InvalidRemoteException, @@ -288,6 +286,7 @@ public class FetchCommand extends TransportCommand<FetchCommand, FetchResult> { * * @see Constants#DEFAULT_REMOTE_NAME * @param remote + * name of a remote * @return {@code this} */ public FetchCommand setRemote(String remote) { @@ -297,6 +296,8 @@ public class FetchCommand extends TransportCommand<FetchCommand, FetchResult> { } /** + * Get the remote + * * @return the remote used for the remote operation */ public String getRemote() { @@ -304,6 +305,8 @@ public class FetchCommand extends TransportCommand<FetchCommand, FetchResult> { } /** + * Get timeout + * * @return the timeout used for the fetch operation */ public int getTimeout() { @@ -311,16 +314,19 @@ public class FetchCommand extends TransportCommand<FetchCommand, FetchResult> { } /** - * @return whether to check received objects checked for validity + * Whether to check received objects for validity + * + * @return whether to check received objects for validity */ public boolean isCheckFetchedObjects() { return checkFetchedObjects; } /** - * If set to true, objects received will be checked for validity + * If set to {@code true}, objects received will be checked for validity * * @param checkFetchedObjects + * whether to check objects for validity * @return {@code this} */ public FetchCommand setCheckFetchedObjects(boolean checkFetchedObjects) { @@ -330,7 +336,9 @@ public class FetchCommand extends TransportCommand<FetchCommand, FetchResult> { } /** - * @return whether or not to remove refs which no longer exist in the source + * Whether to remove refs which no longer exist in the source + * + * @return whether to remove refs which no longer exist in the source */ public boolean isRemoveDeletedRefs() { if (removeDeletedRefs != null) @@ -347,9 +355,11 @@ public class FetchCommand extends TransportCommand<FetchCommand, FetchResult> { } /** - * If set to true, refs are removed which no longer exist in the source + * If set to {@code true}, refs are removed which no longer exist in the + * source * * @param removeDeletedRefs + * whether to remove deleted {@code Ref}s * @return {@code this} */ public FetchCommand setRemoveDeletedRefs(boolean removeDeletedRefs) { @@ -359,6 +369,8 @@ public class FetchCommand extends TransportCommand<FetchCommand, FetchResult> { } /** + * Get progress monitor + * * @return the progress monitor for the fetch operation */ public ProgressMonitor getProgressMonitor() { @@ -370,8 +382,8 @@ public class FetchCommand extends TransportCommand<FetchCommand, FetchResult> { * this is set to <code>NullProgressMonitor</code> * * @see NullProgressMonitor - * * @param monitor + * a {@link org.eclipse.jgit.lib.ProgressMonitor} * @return {@code this} */ public FetchCommand setProgressMonitor(ProgressMonitor monitor) { @@ -384,6 +396,8 @@ public class FetchCommand extends TransportCommand<FetchCommand, FetchResult> { } /** + * Get list of {@code RefSpec}s + * * @return the ref specs */ public List<RefSpec> getRefSpecs() { @@ -394,6 +408,7 @@ public class FetchCommand extends TransportCommand<FetchCommand, FetchResult> { * The ref specs to be used in the fetch operation * * @param specs + * String representation of {@code RefSpec}s * @return {@code this} * @since 4.9 */ @@ -406,6 +421,7 @@ public class FetchCommand extends TransportCommand<FetchCommand, FetchResult> { * The ref specs to be used in the fetch operation * * @param specs + * one or multiple {@link org.eclipse.jgit.transport.RefSpec}s * @return {@code this} */ public FetchCommand setRefSpecs(RefSpec... specs) { @@ -416,6 +432,7 @@ public class FetchCommand extends TransportCommand<FetchCommand, FetchResult> { * The ref specs to be used in the fetch operation * * @param specs + * list of {@link org.eclipse.jgit.transport.RefSpec}s * @return {@code this} */ public FetchCommand setRefSpecs(List<RefSpec> specs) { @@ -426,6 +443,8 @@ public class FetchCommand extends TransportCommand<FetchCommand, FetchResult> { } /** + * Whether to do a dry run + * * @return the dry run preference for the fetch operation */ public boolean isDryRun() { @@ -436,6 +455,7 @@ public class FetchCommand extends TransportCommand<FetchCommand, FetchResult> { * Sets whether the fetch operation should be a dry run * * @param dryRun + * whether to do a dry run * @return {@code this} */ public FetchCommand setDryRun(boolean dryRun) { @@ -445,6 +465,8 @@ public class FetchCommand extends TransportCommand<FetchCommand, FetchResult> { } /** + * Get thin-pack preference + * * @return the thin-pack preference for fetch operation */ public boolean isThin() { @@ -457,6 +479,7 @@ public class FetchCommand extends TransportCommand<FetchCommand, FetchResult> { * Default setting is Transport.DEFAULT_FETCH_THIN * * @param thin + * the thin-pack preference * @return {@code this} */ public FetchCommand setThin(boolean thin) { @@ -469,6 +492,7 @@ public class FetchCommand extends TransportCommand<FetchCommand, FetchResult> { * Sets the specification of annotated tag behavior during fetch * * @param tagOpt + * the {@link org.eclipse.jgit.transport.TagOpt} * @return {@code this} */ public FetchCommand setTagOpt(TagOpt tagOpt) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/GarbageCollectCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/GarbageCollectCommand.java index 0f38db53ba..7ea277157d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/GarbageCollectCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/GarbageCollectCommand.java @@ -61,7 +61,6 @@ import org.eclipse.jgit.lib.ProgressMonitor; import org.eclipse.jgit.lib.Repository; import org.eclipse.jgit.lib.StoredConfig; import org.eclipse.jgit.storage.pack.PackConfig; -import org.eclipse.jgit.util.GitDateParser; /** * A class used to execute a {@code gc} command. It has setters for all @@ -97,7 +96,10 @@ public class GarbageCollectCommand extends GitCommand<Properties> { private PackConfig pconfig; /** + * Constructor for GarbageCollectCommand. + * * @param repo + * a {@link org.eclipse.jgit.lib.Repository} object. */ protected GarbageCollectCommand(Repository repo) { super(repo); @@ -105,6 +107,8 @@ public class GarbageCollectCommand extends GitCommand<Properties> { } /** + * Set progress monitor + * * @param monitor * a progress monitor * @return this instance @@ -118,8 +122,8 @@ public class GarbageCollectCommand extends GitCommand<Properties> { * During gc() or prune() each unreferenced, loose object which has been * created or modified after <code>expire</code> will not be pruned. Only * older objects may be pruned. If set to null then every object is a - * candidate for pruning. Use {@link GitDateParser} to parse time formats - * used by git gc. + * candidate for pruning. Use {@link org.eclipse.jgit.util.GitDateParser} to + * parse time formats used by git gc. * * @param expire * minimal age of objects to be pruned. @@ -191,6 +195,7 @@ public class GarbageCollectCommand extends GitCommand<Properties> { return this; } + /** {@inheritDoc} */ @Override public Properties call() throws GitAPIException { checkCallable(); @@ -229,7 +234,7 @@ public class GarbageCollectCommand extends GitCommand<Properties> { * Computes and returns the repository statistics. * * @return the repository statistics - * @throws GitAPIException + * @throws org.eclipse.jgit.api.errors.GitAPIException * thrown if the repository statistics cannot be computed * @since 3.0 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/Git.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/Git.java index 96995693a3..400a7dfe48 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/Git.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/Git.java @@ -89,25 +89,30 @@ public class Git implements AutoCloseable { private final boolean closeRepo; /** + * Open repository + * * @param dir * the repository to open. May be either the GIT_DIR, or the * working tree directory that contains {@code .git}. - * @return a {@link Git} object for the existing git repository - * @throws IOException + * @return a {@link org.eclipse.jgit.api.Git} object for the existing git + * repository + * @throws java.io.IOException */ public static Git open(File dir) throws IOException { return open(dir, FS.DETECTED); } /** + * Open repository + * * @param dir * the repository to open. May be either the GIT_DIR, or the * working tree directory that contains {@code .git}. * @param fs * filesystem abstraction to use when accessing the repository. - * @return a {@link Git} object for the existing git repository. Closing this - * instance will close the repo. - * @throws IOException + * @return a {@link org.eclipse.jgit.api.Git} object for the existing git + * repository. Closing this instance will close the repo. + * @throws java.io.IOException */ public static Git open(File dir, FS fs) throws IOException { RepositoryCache.FileKey key; @@ -119,31 +124,36 @@ public class Git implements AutoCloseable { } /** + * Wrap repository + * * @param repo * the git repository this class is interacting with; * {@code null} is not allowed. - * @return a {@link Git} object for the existing git repository. The caller is - * responsible for closing the repository; {@link #close()} on this - * instance does not close the repo. + * @return a {@link org.eclipse.jgit.api.Git} object for the existing git + * repository. The caller is responsible for closing the repository; + * {@link #close()} on this instance does not close the repo. */ public static Git wrap(Repository repo) { return new Git(repo); } /** - * Frees resources associated with this instance. + * {@inheritDoc} * <p> - * If the repository was opened by a static factory method in this class, then - * this method calls {@link Repository#close()} on the underlying repository - * instance. (Whether this actually releases underlying resources, such as - * file handles, may vary; see {@link Repository} for more details.) + * Free resources associated with this instance. * <p> - * If the repository was created by a caller and passed into {@link - * #Git(Repository)} or a static factory method in this class, then this - * method does not call close on the underlying repository. + * If the repository was opened by a static factory method in this class, + * then this method calls {@link Repository#close()} on the underlying + * repository instance. (Whether this actually releases underlying + * resources, such as file handles, may vary; see {@link Repository} for + * more details.) * <p> - * In all cases, after calling this method you should not use this {@link Git} - * instance anymore. + * If the repository was created by a caller and passed into + * {@link #Git(Repository)} or a static factory method in this class, then + * this method does not call close on the underlying repository. + * <p> + * In all cases, after calling this method you should not use this + * {@link Git} instance anymore. * * @since 3.2 */ @@ -154,23 +164,23 @@ public class Git implements AutoCloseable { } /** - * Returns a command object to execute a {@code clone} command + * Return a command object to execute a {@code clone} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-clone.html" + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-clone.html" * >Git documentation about clone</a> - * @return a {@link CloneCommand} used to collect all optional parameters - * and to finally execute the {@code clone} command + * @return a {@link org.eclipse.jgit.api.CloneCommand} used to collect all + * optional parameters and to finally execute the {@code clone} + * command */ public static CloneCommand cloneRepository() { return new CloneCommand(); } /** - * Returns a command to list remote branches/tags without a local - * repository. + * Return a command to list remote branches/tags without a local repository. * - * @return a {@link LsRemoteCommand} + * @return a {@link org.eclipse.jgit.api.LsRemoteCommand} * @since 3.1 */ public static LsRemoteCommand lsRemoteRepository() { @@ -178,24 +188,25 @@ public class Git implements AutoCloseable { } /** - * Returns a command object to execute a {@code init} command + * Return a command object to execute a {@code init} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-init.html" - * >Git documentation about init</a> - * @return a {@link InitCommand} used to collect all optional parameters and - * to finally execute the {@code init} command + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-init.html" >Git + * documentation about init</a> + * @return a {@link org.eclipse.jgit.api.InitCommand} used to collect all + * optional parameters and to finally execute the {@code init} + * command */ public static InitCommand init() { return new InitCommand(); } /** - * Constructs a new {@link Git} object which can interact with the specified - * git repository. + * Construct a new {@link org.eclipse.jgit.api.Git} object which can + * interact with the specified git repository. * <p> - * All command classes returned by methods of this class will always interact - * with this git repository. + * All command classes returned by methods of this class will always + * interact with this git repository. * <p> * The caller is responsible for closing the repository; {@link #close()} on * this instance does not close the repo. @@ -216,75 +227,78 @@ public class Git implements AutoCloseable { } /** - * Returns a command object to execute a {@code Commit} command + * Return a command object to execute a {@code Commit} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-commit.html" + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-commit.html" * >Git documentation about Commit</a> - * @return a {@link CommitCommand} used to collect all optional parameters - * and to finally execute the {@code Commit} command + * @return a {@link org.eclipse.jgit.api.CommitCommand} used to collect all + * optional parameters and to finally execute the {@code Commit} + * command */ public CommitCommand commit() { return new CommitCommand(repo); } /** - * Returns a command object to execute a {@code Log} command + * Return a command object to execute a {@code Log} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-log.html" - * >Git documentation about Log</a> - * @return a {@link LogCommand} used to collect all optional parameters and - * to finally execute the {@code Log} command + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-log.html" >Git + * documentation about Log</a> + * @return a {@link org.eclipse.jgit.api.LogCommand} used to collect all + * optional parameters and to finally execute the {@code Log} + * command */ public LogCommand log() { return new LogCommand(repo); } /** - * Returns a command object to execute a {@code Merge} command + * Return a command object to execute a {@code Merge} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-merge.html" + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-merge.html" * >Git documentation about Merge</a> - * @return a {@link MergeCommand} used to collect all optional parameters - * and to finally execute the {@code Merge} command + * @return a {@link org.eclipse.jgit.api.MergeCommand} used to collect all + * optional parameters and to finally execute the {@code Merge} + * command */ public MergeCommand merge() { return new MergeCommand(repo); } /** - * Returns a command object to execute a {@code Pull} command + * Return a command object to execute a {@code Pull} command * - * @return a {@link PullCommand} + * @return a {@link org.eclipse.jgit.api.PullCommand} */ public PullCommand pull() { return new PullCommand(repo); } /** - * Returns a command object used to create branches + * Return a command object used to create branches * - * @return a {@link CreateBranchCommand} + * @return a {@link org.eclipse.jgit.api.CreateBranchCommand} */ public CreateBranchCommand branchCreate() { return new CreateBranchCommand(repo); } /** - * Returns a command object used to delete branches + * Return a command object used to delete branches * - * @return a {@link DeleteBranchCommand} + * @return a {@link org.eclipse.jgit.api.DeleteBranchCommand} */ public DeleteBranchCommand branchDelete() { return new DeleteBranchCommand(repo); } /** - * Returns a command object used to list branches + * Return a command object used to list branches * - * @return a {@link ListBranchCommand} + * @return a {@link org.eclipse.jgit.api.ListBranchCommand} */ public ListBranchCommand branchList() { return new ListBranchCommand(repo); @@ -292,170 +306,180 @@ public class Git implements AutoCloseable { /** * - * Returns a command object used to list tags + * Return a command object used to list tags * - * @return a {@link ListTagCommand} + * @return a {@link org.eclipse.jgit.api.ListTagCommand} */ public ListTagCommand tagList() { return new ListTagCommand(repo); } /** - * Returns a command object used to rename branches + * Return a command object used to rename branches * - * @return a {@link RenameBranchCommand} + * @return a {@link org.eclipse.jgit.api.RenameBranchCommand} */ public RenameBranchCommand branchRename() { return new RenameBranchCommand(repo); } /** - * Returns a command object to execute a {@code Add} command + * Return a command object to execute a {@code Add} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-add.html" - * >Git documentation about Add</a> - * @return a {@link AddCommand} used to collect all optional parameters and - * to finally execute the {@code Add} command + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-add.html" >Git + * documentation about Add</a> + * @return a {@link org.eclipse.jgit.api.AddCommand} used to collect all + * optional parameters and to finally execute the {@code Add} + * command */ public AddCommand add() { return new AddCommand(repo); } /** - * Returns a command object to execute a {@code Tag} command + * Return a command object to execute a {@code Tag} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-tag.html" - * >Git documentation about Tag</a> - * @return a {@link TagCommand} used to collect all optional parameters and - * to finally execute the {@code Tag} command + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-tag.html" >Git + * documentation about Tag</a> + * @return a {@link org.eclipse.jgit.api.TagCommand} used to collect all + * optional parameters and to finally execute the {@code Tag} + * command */ public TagCommand tag() { return new TagCommand(repo); } /** - * Returns a command object to execute a {@code Fetch} command + * Return a command object to execute a {@code Fetch} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-fetch.html" + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-fetch.html" * >Git documentation about Fetch</a> - * @return a {@link FetchCommand} used to collect all optional parameters - * and to finally execute the {@code Fetch} command + * @return a {@link org.eclipse.jgit.api.FetchCommand} used to collect all + * optional parameters and to finally execute the {@code Fetch} + * command */ public FetchCommand fetch() { return new FetchCommand(repo); } /** - * Returns a command object to execute a {@code Push} command + * Return a command object to execute a {@code Push} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-push.html" - * >Git documentation about Push</a> - * @return a {@link PushCommand} used to collect all optional parameters and - * to finally execute the {@code Push} command + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-push.html" >Git + * documentation about Push</a> + * @return a {@link org.eclipse.jgit.api.PushCommand} used to collect all + * optional parameters and to finally execute the {@code Push} + * command */ public PushCommand push() { return new PushCommand(repo); } /** - * Returns a command object to execute a {@code cherry-pick} command + * Return a command object to execute a {@code cherry-pick} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-cherry-pick.html" + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-cherry-pick.html" * >Git documentation about cherry-pick</a> - * @return a {@link CherryPickCommand} used to collect all optional - * parameters and to finally execute the {@code cherry-pick} command + * @return a {@link org.eclipse.jgit.api.CherryPickCommand} used to collect + * all optional parameters and to finally execute the + * {@code cherry-pick} command */ public CherryPickCommand cherryPick() { return new CherryPickCommand(repo); } /** - * Returns a command object to execute a {@code revert} command + * Return a command object to execute a {@code revert} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-revert.html" + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-revert.html" * >Git documentation about reverting changes</a> - * @return a {@link RevertCommand} used to collect all optional parameters - * and to finally execute the {@code cherry-pick} command + * @return a {@link org.eclipse.jgit.api.RevertCommand} used to collect all + * optional parameters and to finally execute the + * {@code cherry-pick} command */ public RevertCommand revert() { return new RevertCommand(repo); } /** - * Returns a command object to execute a {@code Rebase} command + * Return a command object to execute a {@code Rebase} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html" + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html" * >Git documentation about rebase</a> - * @return a {@link RebaseCommand} used to collect all optional parameters - * and to finally execute the {@code rebase} command + * @return a {@link org.eclipse.jgit.api.RebaseCommand} used to collect all + * optional parameters and to finally execute the {@code rebase} + * command */ public RebaseCommand rebase() { return new RebaseCommand(repo); } /** - * Returns a command object to execute a {@code rm} command + * Return a command object to execute a {@code rm} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-rm.html" - * >Git documentation about rm</a> - * @return a {@link RmCommand} used to collect all optional parameters and - * to finally execute the {@code rm} command + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-rm.html" >Git + * documentation about rm</a> + * @return a {@link org.eclipse.jgit.api.RmCommand} used to collect all + * optional parameters and to finally execute the {@code rm} command */ public RmCommand rm() { return new RmCommand(repo); } /** - * Returns a command object to execute a {@code checkout} command + * Return a command object to execute a {@code checkout} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-checkout.html" + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-checkout.html" * >Git documentation about checkout</a> - * @return a {@link CheckoutCommand} used to collect all optional parameters - * and to finally execute the {@code checkout} command + * @return a {@link org.eclipse.jgit.api.CheckoutCommand} used to collect + * all optional parameters and to finally execute the + * {@code checkout} command */ public CheckoutCommand checkout() { return new CheckoutCommand(repo); } /** - * Returns a command object to execute a {@code reset} command + * Return a command object to execute a {@code reset} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-reset.html" + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-reset.html" * >Git documentation about reset</a> - * @return a {@link ResetCommand} used to collect all optional parameters - * and to finally execute the {@code reset} command + * @return a {@link org.eclipse.jgit.api.ResetCommand} used to collect all + * optional parameters and to finally execute the {@code reset} + * command */ public ResetCommand reset() { return new ResetCommand(repo); } /** - * Returns a command object to execute a {@code status} command + * Return a command object to execute a {@code status} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-status.html" + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-status.html" * >Git documentation about status</a> - * @return a {@link StatusCommand} used to collect all optional parameters - * and to finally execute the {@code status} command + * @return a {@link org.eclipse.jgit.api.StatusCommand} used to collect all + * optional parameters and to finally execute the {@code status} + * command */ public StatusCommand status() { return new StatusCommand(repo); } /** - * Returns a command to create an archive from a tree + * Return a command to create an archive from a tree * - * @return a {@link ArchiveCommand} + * @return a {@link org.eclipse.jgit.api.ArchiveCommand} * @since 3.1 */ public ArchiveCommand archive() { @@ -463,179 +487,196 @@ public class Git implements AutoCloseable { } /** - * Returns a command to add notes to an object + * Return a command to add notes to an object * - * @return a {@link AddNoteCommand} + * @return a {@link org.eclipse.jgit.api.AddNoteCommand} */ public AddNoteCommand notesAdd() { return new AddNoteCommand(repo); } /** - * Returns a command to remove notes on an object + * Return a command to remove notes on an object * - * @return a {@link RemoveNoteCommand} + * @return a {@link org.eclipse.jgit.api.RemoveNoteCommand} */ public RemoveNoteCommand notesRemove() { return new RemoveNoteCommand(repo); } /** - * Returns a command to list all notes + * Return a command to list all notes * - * @return a {@link ListNotesCommand} + * @return a {@link org.eclipse.jgit.api.ListNotesCommand} */ public ListNotesCommand notesList() { return new ListNotesCommand(repo); } /** - * Returns a command to show notes on an object + * Return a command to show notes on an object * - * @return a {@link ShowNoteCommand} + * @return a {@link org.eclipse.jgit.api.ShowNoteCommand} */ public ShowNoteCommand notesShow() { return new ShowNoteCommand(repo); } /** - * Returns a command object to execute a {@code ls-remote} command + * Return a command object to execute a {@code ls-remote} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-ls-remote.html" + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-ls-remote.html" * >Git documentation about ls-remote</a> - * @return a {@link LsRemoteCommand} used to collect all optional parameters - * and to finally execute the {@code status} command + * @return a {@link org.eclipse.jgit.api.LsRemoteCommand} used to collect + * all optional parameters and to finally execute the {@code status} + * command */ public LsRemoteCommand lsRemote() { return new LsRemoteCommand(repo); } /** - * Returns a command object to execute a {@code clean} command + * Return a command object to execute a {@code clean} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-clean.html" + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-clean.html" * >Git documentation about Clean</a> - * @return a {@link CleanCommand} used to collect all optional parameters - * and to finally execute the {@code clean} command + * @return a {@link org.eclipse.jgit.api.CleanCommand} used to collect all + * optional parameters and to finally execute the {@code clean} + * command */ public CleanCommand clean() { return new CleanCommand(repo); } /** - * Returns a command object to execute a {@code blame} command + * Return a command object to execute a {@code blame} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-blame.html" + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-blame.html" * >Git documentation about Blame</a> - * @return a {@link BlameCommand} used to collect all optional parameters - * and to finally execute the {@code blame} command + * @return a {@link org.eclipse.jgit.api.BlameCommand} used to collect all + * optional parameters and to finally execute the {@code blame} + * command */ public BlameCommand blame() { return new BlameCommand(repo); } /** - * Returns a command object to execute a {@code reflog} command + * Return a command object to execute a {@code reflog} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-reflog.html" + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-reflog.html" * >Git documentation about reflog</a> - * @return a {@link ReflogCommand} used to collect all optional parameters - * and to finally execute the {@code reflog} command + * @return a {@link org.eclipse.jgit.api.ReflogCommand} used to collect all + * optional parameters and to finally execute the {@code reflog} + * command */ public ReflogCommand reflog() { return new ReflogCommand(repo); } /** - * Returns a command object to execute a {@code diff} command + * Return a command object to execute a {@code diff} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-diff.html" - * >Git documentation about diff</a> - * @return a {@link DiffCommand} used to collect all optional parameters and - * to finally execute the {@code diff} command + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-diff.html" >Git + * documentation about diff</a> + * @return a {@link org.eclipse.jgit.api.DiffCommand} used to collect all + * optional parameters and to finally execute the {@code diff} + * command */ public DiffCommand diff() { return new DiffCommand(repo); } /** - * Returns a command object used to delete tags + * Return a command object used to delete tags * - * @return a {@link DeleteTagCommand} + * @return a {@link org.eclipse.jgit.api.DeleteTagCommand} */ public DeleteTagCommand tagDelete() { return new DeleteTagCommand(repo); } /** - * Returns a command object to execute a {@code submodule add} command + * Return a command object to execute a {@code submodule add} command * - * @return a {@link SubmoduleAddCommand} used to add a new submodule to a - * parent repository + * @return a {@link org.eclipse.jgit.api.SubmoduleAddCommand} used to add a + * new submodule to a parent repository */ public SubmoduleAddCommand submoduleAdd() { return new SubmoduleAddCommand(repo); } /** - * Returns a command object to execute a {@code submodule init} command + * Return a command object to execute a {@code submodule init} command * - * @return a {@link SubmoduleInitCommand} used to initialize the - * repository's config with settings from the .gitmodules file in - * the working tree + * @return a {@link org.eclipse.jgit.api.SubmoduleInitCommand} used to + * initialize the repository's config with settings from the + * .gitmodules file in the working tree */ public SubmoduleInitCommand submoduleInit() { return new SubmoduleInitCommand(repo); } /** + * Returns a command object to execute a {@code submodule deinit} command + * + * @return a {@link org.eclipse.jgit.api.SubmoduleDeinitCommand} used to + * remove a submodule's working tree manifestation + * @since 4.10 + */ + public SubmoduleDeinitCommand submoduleDeinit() { + return new SubmoduleDeinitCommand(repo); + } + + /** * Returns a command object to execute a {@code submodule status} command * - * @return a {@link SubmoduleStatusCommand} used to report the status of a - * repository's configured submodules + * @return a {@link org.eclipse.jgit.api.SubmoduleStatusCommand} used to + * report the status of a repository's configured submodules */ public SubmoduleStatusCommand submoduleStatus() { return new SubmoduleStatusCommand(repo); } /** - * Returns a command object to execute a {@code submodule sync} command + * Return a command object to execute a {@code submodule sync} command * - * @return a {@link SubmoduleSyncCommand} used to update the URL of a - * submodule from the parent repository's .gitmodules file + * @return a {@link org.eclipse.jgit.api.SubmoduleSyncCommand} used to + * update the URL of a submodule from the parent repository's + * .gitmodules file */ public SubmoduleSyncCommand submoduleSync() { return new SubmoduleSyncCommand(repo); } /** - * Returns a command object to execute a {@code submodule update} command + * Return a command object to execute a {@code submodule update} command * - * @return a {@link SubmoduleUpdateCommand} used to update the submodules in - * a repository to the configured revision + * @return a {@link org.eclipse.jgit.api.SubmoduleUpdateCommand} used to + * update the submodules in a repository to the configured revision */ public SubmoduleUpdateCommand submoduleUpdate() { return new SubmoduleUpdateCommand(repo); } /** - * Returns a command object used to list stashed commits + * Return a command object used to list stashed commits * - * @return a {@link StashListCommand} + * @return a {@link org.eclipse.jgit.api.StashListCommand} */ public StashListCommand stashList() { return new StashListCommand(repo); } /** - * Returns a command object used to create a stashed commit + * Return a command object used to create a stashed commit * - * @return a {@link StashCreateCommand} + * @return a {@link org.eclipse.jgit.api.StashCreateCommand} * @since 2.0 */ public StashCreateCommand stashCreate() { @@ -643,9 +684,9 @@ public class Git implements AutoCloseable { } /** - * Returns a command object used to apply a stashed commit + * Returs a command object used to apply a stashed commit * - * @return a {@link StashApplyCommand} + * @return a {@link org.eclipse.jgit.api.StashApplyCommand} * @since 2.0 */ public StashApplyCommand stashApply() { @@ -653,9 +694,9 @@ public class Git implements AutoCloseable { } /** - * Returns a command object used to drop a stashed commit + * Return a command object used to drop a stashed commit * - * @return a {@link StashDropCommand} + * @return a {@link org.eclipse.jgit.api.StashDropCommand} * @since 2.0 */ public StashDropCommand stashDrop() { @@ -663,14 +704,14 @@ public class Git implements AutoCloseable { } /** - * Returns a command object to execute a {@code apply} command + * Return a command object to execute a {@code apply} command * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-apply.html" + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-apply.html" * >Git documentation about apply</a> - * - * @return a {@link ApplyCommand} used to collect all optional parameters - * and to finally execute the {@code apply} command + * @return a {@link org.eclipse.jgit.api.ApplyCommand} used to collect all + * optional parameters and to finally execute the {@code apply} + * command * @since 2.0 */ public ApplyCommand apply() { @@ -678,14 +719,14 @@ public class Git implements AutoCloseable { } /** - * Returns a command object to execute a {@code gc} command - * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-gc.html" - * >Git documentation about gc</a> + * Return a command object to execute a {@code gc} command * - * @return a {@link GarbageCollectCommand} used to collect all optional - * parameters and to finally execute the {@code gc} command + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-gc.html" >Git + * documentation about gc</a> + * @return a {@link org.eclipse.jgit.api.GarbageCollectCommand} used to + * collect all optional parameters and to finally execute the + * {@code gc} command * @since 2.2 */ public GarbageCollectCommand gc() { @@ -693,9 +734,9 @@ public class Git implements AutoCloseable { } /** - * Returns a command object to find human-readable names of revisions. + * Return a command object to find human-readable names of revisions. * - * @return a {@link NameRevCommand}. + * @return a {@link org.eclipse.jgit.api.NameRevCommand}. * @since 3.0 */ public NameRevCommand nameRev() { @@ -703,10 +744,10 @@ public class Git implements AutoCloseable { } /** - * Returns a command object to come up with a short name that describes a + * Return a command object to come up with a short name that describes a * commit in terms of the nearest git tag. * - * @return a {@link DescribeCommand}. + * @return a {@link org.eclipse.jgit.api.DescribeCommand}. * @since 3.2 */ public DescribeCommand describe() { @@ -716,7 +757,7 @@ public class Git implements AutoCloseable { /** * Return a command used to list the available remotes. * - * @return a {@link RemoteListCommand} + * @return a {@link org.eclipse.jgit.api.RemoteListCommand} * @since 4.2 */ public RemoteListCommand remoteList() { @@ -726,7 +767,7 @@ public class Git implements AutoCloseable { /** * Return a command used to add a new remote. * - * @return a {@link RemoteAddCommand} + * @return a {@link org.eclipse.jgit.api.RemoteAddCommand} * @since 4.2 */ public RemoteAddCommand remoteAdd() { @@ -736,7 +777,7 @@ public class Git implements AutoCloseable { /** * Return a command used to remove an existing remote. * - * @return a {@link RemoteRemoveCommand} + * @return a {@link org.eclipse.jgit.api.RemoteRemoveCommand} * @since 4.2 */ public RemoteRemoveCommand remoteRemove() { @@ -746,7 +787,7 @@ public class Git implements AutoCloseable { /** * Return a command used to change the URL of an existing remote. * - * @return a {@link RemoteSetUrlCommand} + * @return a {@link org.eclipse.jgit.api.RemoteSetUrlCommand} * @since 4.2 */ public RemoteSetUrlCommand remoteSetUrl() { @@ -754,6 +795,8 @@ public class Git implements AutoCloseable { } /** + * Get repository + * * @return the git repository this class is interacting with; see * {@link #close()} for notes on closing this repository. */ @@ -761,6 +804,7 @@ public class Git implements AutoCloseable { return repo; } + /** {@inheritDoc} */ @Override public String toString() { return "Git[" + repo + "]"; //$NON-NLS-1$//$NON-NLS-2$ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/GitCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/GitCommand.java index 2a23408b53..ee7d75cf95 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/GitCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/GitCommand.java @@ -48,18 +48,20 @@ import org.eclipse.jgit.lib.Repository; /** * Common superclass of all commands in the package {@code org.eclipse.jgit.api} * <p> - * This class ensures that all commands fulfill the {@link Callable} interface. - * It also has a property {@link #repo} holding a reference to the git - * {@link Repository} this command should work with. + * This class ensures that all commands fulfill the + * {@link java.util.concurrent.Callable} interface. It also has a property + * {@link #repo} holding a reference to the git + * {@link org.eclipse.jgit.lib.Repository} this command should work with. * <p> * Finally this class stores a state telling whether it is allowed to call - * {@link #call()} on this instance. Instances of {@link GitCommand} can only be - * used for one single successful call to {@link #call()}. Afterwards this - * instance may not be used anymore to set/modify any properties or to call - * {@link #call()} again. This is achieved by setting the {@link #callable} - * property to false after the successful execution of {@link #call()} and to - * check the state (by calling {@link #checkCallable()}) before setting of - * properties and inside {@link #call()}. + * {@link #call()} on this instance. Instances of + * {@link org.eclipse.jgit.api.GitCommand} can only be used for one single + * successful call to {@link #call()}. Afterwards this instance may not be used + * anymore to set/modify any properties or to call {@link #call()} again. This + * is achieved by setting the {@link #callable} property to false after the + * successful execution of {@link #call()} and to check the state (by calling + * {@link #checkCallable()}) before setting of properties and inside + * {@link #call()}. * * @param <T> * the return type which is expected from {@link #call()} @@ -78,14 +80,18 @@ public abstract class GitCommand<T> implements Callable<T> { * Creates a new command which interacts with a single repository * * @param repo - * the {@link Repository} this command should interact with + * the {@link org.eclipse.jgit.lib.Repository} this command + * should interact with */ protected GitCommand(Repository repo) { this.repo = repo; } /** - * @return the {@link Repository} this command is interacting with + * Get repository this command is working on + * + * @return the {@link org.eclipse.jgit.lib.Repository} this command is + * interacting with */ public Repository getRepository() { return repo; @@ -106,9 +112,9 @@ public abstract class GitCommand<T> implements Callable<T> { /** * Checks that the property {@link #callable} is {@code true}. If not then - * an {@link IllegalStateException} is thrown + * an {@link java.lang.IllegalStateException} is thrown * - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * when this method is called and the property {@link #callable} * is {@code false} */ @@ -120,11 +126,9 @@ public abstract class GitCommand<T> implements Callable<T> { } /** - * Executes the command - * - * @return T a result. Each command has its own return type - * @throws GitAPIException - * or subclass thereof when an error occurs + * {@inheritDoc} + * <p> + * Execute the command */ @Override public abstract T call() throws GitAPIException; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/InitCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/InitCommand.java index 649484cf62..f10bcdfcde 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/InitCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/InitCommand.java @@ -53,6 +53,7 @@ import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.lib.Repository; import org.eclipse.jgit.lib.RepositoryBuilder; +import org.eclipse.jgit.util.FS; import org.eclipse.jgit.util.SystemReader; /** @@ -68,10 +69,12 @@ public class InitCommand implements Callable<Git> { private boolean bare; + private FS fs; + /** + * {@inheritDoc} + * <p> * Executes the {@code Init} command. - * - * @return the newly created {@code Git} object with associated repository */ @Override public Git call() throws GitAPIException { @@ -79,6 +82,9 @@ public class InitCommand implements Callable<Git> { RepositoryBuilder builder = new RepositoryBuilder(); if (bare) builder.setBare(); + if (fs != null) { + builder.setFS(fs); + } builder.readEnvironment(); if (gitDir != null) builder.setGitDir(gitDir); @@ -127,7 +133,7 @@ public class InitCommand implements Callable<Git> { * @param directory * the directory to init to * @return this instance - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * if the combination of directory, gitDir and bare is illegal. * E.g. if for a non-bare repository directory and gitDir point * to the same directory of if for a bare repository both @@ -141,10 +147,12 @@ public class InitCommand implements Callable<Git> { } /** + * Set the repository meta directory (.git) + * * @param gitDir * the repository meta directory * @return this instance - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * if the combination of directory, gitDir and bare is illegal. * E.g. if for a non-bare repository directory and gitDir point * to the same directory of if for a bare repository both @@ -176,9 +184,11 @@ public class InitCommand implements Callable<Git> { } /** + * Set whether the repository is bare or not + * * @param bare * whether the repository is bare or not - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * if the combination of directory, gitDir and bare is illegal. * E.g. if for a non-bare repository directory and gitDir point * to the same directory of if for a bare repository both @@ -190,4 +200,18 @@ public class InitCommand implements Callable<Git> { this.bare = bare; return this; } + + /** + * Set the file system abstraction to be used for repositories created by + * this command. + * + * @param fs + * the abstraction. + * @return {@code this} (for chaining calls). + * @since 4.10 + */ + public InitCommand setFs(FS fs) { + this.fs = fs; + return this; + } } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/ListBranchCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/ListBranchCommand.java index 961eeaadd4..cdae782c6c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/ListBranchCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/ListBranchCommand.java @@ -95,12 +95,16 @@ public class ListBranchCommand extends GitCommand<List<Ref>> { } /** + * Constructor for ListBranchCommand. + * * @param repo + * a {@link org.eclipse.jgit.lib.Repository} object. */ protected ListBranchCommand(Repository repo) { super(repo); } + /** {@inheritDoc} */ @Override public List<Ref> call() throws GitAPIException { checkCallable(); @@ -154,6 +158,8 @@ public class ListBranchCommand extends GitCommand<List<Ref>> { } /** + * Set the list mode + * * @param listMode * optional: corresponds to the -r/-a options; by default, only * local branches will be listed diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/ListNotesCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/ListNotesCommand.java index 476c10bdbc..41691fbfc4 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/ListNotesCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/ListNotesCommand.java @@ -68,15 +68,16 @@ public class ListNotesCommand extends GitCommand<List<Note>> { private String notesRef = Constants.R_NOTES_COMMITS; /** + * Constructor for ListNotesCommand. + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected ListNotesCommand(Repository repo) { super(repo); } - /** - * @return the requested notes - */ + /** {@inheritDoc} */ @Override public List<Note> call() throws GitAPIException { checkCallable(); @@ -101,12 +102,14 @@ public class ListNotesCommand extends GitCommand<List<Note>> { } /** + * Set the {@code Ref} to read notes from + * * @param notesRef - * the ref to read notes from. Note, the default value of - * {@link Constants#R_NOTES_COMMITS} will be used if nothing is - * set + * the name of the {@code Ref} to read notes from. Note, the + * default value of + * {@link org.eclipse.jgit.lib.Constants#R_NOTES_COMMITS} will be + * used if nothing is set * @return {@code this} - * * @see Constants#R_NOTES_COMMITS */ public ListNotesCommand setNotesRef(String notesRef) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/ListTagCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/ListTagCommand.java index d649a53db1..9161211d7f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/ListTagCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/ListTagCommand.java @@ -65,15 +65,16 @@ import org.eclipse.jgit.revwalk.RevWalk; public class ListTagCommand extends GitCommand<List<Ref>> { /** + * Constructor for ListTagCommand. + * * @param repo + * a {@link org.eclipse.jgit.lib.Repository} object. */ protected ListTagCommand(Repository repo) { super(repo); } - /** - * @return the tags available - */ + /** {@inheritDoc} */ @Override public List<Ref> call() throws GitAPIException { checkCallable(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/LogCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/LogCommand.java index f8fe95a88a..fd6c1fa1be 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/LogCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/LogCommand.java @@ -78,7 +78,7 @@ import org.eclipse.jgit.treewalk.filter.TreeFilter; * to finally execute the command. Each instance of this class should only be * used for one invocation of the command (means: one call to {@link #call()}) * <p> - * Examples (<code>git</code> is a {@link Git} instance): + * Examples (<code>git</code> is a {@link org.eclipse.jgit.api.Git} instance): * <p> * Get newest 10 commits, starting from the current branch: * @@ -114,7 +114,10 @@ public class LogCommand extends GitCommand<Iterable<RevCommit>> { private int skip = -1; /** + * Constructor for LogCommand. + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected LogCommand(Repository repo) { super(repo); @@ -122,15 +125,13 @@ public class LogCommand extends GitCommand<Iterable<RevCommit>> { } /** + * {@inheritDoc} + * <p> * Executes the {@code Log} command with all the options and parameters * collected by the setter methods (e.g. {@link #add(AnyObjectId)}, * {@link #not(AnyObjectId)}, ..) of this class. Each instance of this class * should only be used for one invocation of the command. Don't call this * method twice on an instance. - * - * @return an iteration over RevCommits - * @throws NoHeadException - * of the references ref cannot be resolved */ @Override public Iterable<RevCommit> call() throws GitAPIException, NoHeadException { @@ -174,23 +175,26 @@ public class LogCommand extends GitCommand<Iterable<RevCommit>> { * * @see RevWalk#markStart(RevCommit) * @param start + * the id of the commit to start from * @return {@code this} - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the commit supplied is not available from the object * database. This usually indicates the supplied commit is * invalid, but the reference was constructed during an earlier - * invocation to {@link RevWalk#lookupCommit(AnyObjectId)}. - * @throws IncorrectObjectTypeException + * invocation to + * {@link org.eclipse.jgit.revwalk.RevWalk#lookupCommit(AnyObjectId)}. + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the object was not parsed yet and it was discovered during * parsing that it is not actually a commit. This usually * indicates the caller supplied a non-commit SHA-1 to - * {@link RevWalk#lookupCommit(AnyObjectId)}. + * {@link org.eclipse.jgit.revwalk.RevWalk#lookupCommit(AnyObjectId)}. * @throws JGitInternalException * a low-level exception of JGit has occurred. The original * exception can be retrieved by calling - * {@link Exception#getCause()}. Expect only + * {@link java.lang.Exception#getCause()}. Expect only * {@code IOException's} to be wrapped. Subclasses of - * {@link IOException} (e.g. {@link MissingObjectException}) are + * {@link java.io.IOException} (e.g. + * {@link org.eclipse.jgit.errors.MissingObjectException}) are * typically not wrapped here but thrown as original exception */ public LogCommand add(AnyObjectId start) throws MissingObjectException, @@ -202,23 +206,26 @@ public class LogCommand extends GitCommand<Iterable<RevCommit>> { * Same as {@code --not start}, or {@code ^start} * * @param start + * a {@link org.eclipse.jgit.lib.AnyObjectId} * @return {@code this} - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the commit supplied is not available from the object * database. This usually indicates the supplied commit is * invalid, but the reference was constructed during an earlier - * invocation to {@link RevWalk#lookupCommit(AnyObjectId)}. - * @throws IncorrectObjectTypeException + * invocation to + * {@link org.eclipse.jgit.revwalk.RevWalk#lookupCommit(AnyObjectId)}. + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the object was not parsed yet and it was discovered during * parsing that it is not actually a commit. This usually * indicates the caller supplied a non-commit SHA-1 to - * {@link RevWalk#lookupCommit(AnyObjectId)}. + * {@link org.eclipse.jgit.revwalk.RevWalk#lookupCommit(AnyObjectId)}. * @throws JGitInternalException * a low-level exception of JGit has occurred. The original * exception can be retrieved by calling - * {@link Exception#getCause()}. Expect only + * {@link java.lang.Exception#getCause()}. Expect only * {@code IOException's} to be wrapped. Subclasses of - * {@link IOException} (e.g. {@link MissingObjectException}) are + * {@link java.io.IOException} (e.g. + * {@link org.eclipse.jgit.errors.MissingObjectException}) are * typically not wrapped here but thrown as original exception */ public LogCommand not(AnyObjectId start) throws MissingObjectException, @@ -230,24 +237,28 @@ public class LogCommand extends GitCommand<Iterable<RevCommit>> { * Adds the range {@code since..until} * * @param since + * a {@link org.eclipse.jgit.lib.AnyObjectId} object. * @param until + * a {@link org.eclipse.jgit.lib.AnyObjectId} object. * @return {@code this} - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the commit supplied is not available from the object * database. This usually indicates the supplied commit is * invalid, but the reference was constructed during an earlier - * invocation to {@link RevWalk#lookupCommit(AnyObjectId)}. - * @throws IncorrectObjectTypeException + * invocation to + * {@link org.eclipse.jgit.revwalk.RevWalk#lookupCommit(AnyObjectId)}. + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the object was not parsed yet and it was discovered during * parsing that it is not actually a commit. This usually * indicates the caller supplied a non-commit SHA-1 to - * {@link RevWalk#lookupCommit(AnyObjectId)}. + * {@link org.eclipse.jgit.revwalk.RevWalk#lookupCommit(AnyObjectId)}. * @throws JGitInternalException * a low-level exception of JGit has occurred. The original * exception can be retrieved by calling - * {@link Exception#getCause()}. Expect only + * {@link java.lang.Exception#getCause()}. Expect only * {@code IOException's} to be wrapped. Subclasses of - * {@link IOException} (e.g. {@link MissingObjectException}) are + * {@link java.io.IOException} (e.g. + * {@link org.eclipse.jgit.errors.MissingObjectException}) are * typically not wrapped here but thrown as original exception */ public LogCommand addRange(AnyObjectId since, AnyObjectId until) @@ -260,7 +271,7 @@ public class LogCommand extends GitCommand<Iterable<RevCommit>> { * * @see #add(AnyObjectId) * @return {@code this} - * @throws IOException + * @throws java.io.IOException * the references could not be accessed */ public LogCommand all() throws IOException { @@ -354,8 +365,7 @@ public class LogCommand extends GitCommand<Iterable<RevCommit>> { /** - * Sets a filter for the <code>LogCommand</code>. - * + * Set a filter for the <code>LogCommand</code>. * * @param aFilter * the filter that this instance of <code>LogCommand</code> diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/LsRemoteCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/LsRemoteCommand.java index 5157a411fd..3dcc3a5582 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/LsRemoteCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/LsRemoteCommand.java @@ -83,6 +83,8 @@ public class LsRemoteCommand extends private String uploadPack; /** + * Constructor for LsRemoteCommand + * * @param repo * local repository or null for operation without local * repository @@ -98,6 +100,7 @@ public class LsRemoteCommand extends * * @see Constants#DEFAULT_REMOTE_NAME * @param remote + * a {@link java.lang.String} object. * @return {@code this} */ public LsRemoteCommand setRemote(String remote) { @@ -110,6 +113,7 @@ public class LsRemoteCommand extends * Include refs/heads in references results * * @param heads + * whether to include refs/heads * @return {@code this} */ public LsRemoteCommand setHeads(boolean heads) { @@ -121,6 +125,7 @@ public class LsRemoteCommand extends * Include refs/tags in references results * * @param tags + * whether to include tags * @return {@code this} */ public LsRemoteCommand setTags(boolean tags) { @@ -132,6 +137,8 @@ public class LsRemoteCommand extends * The full path of git-upload-pack on the remote host * * @param uploadPack + * the full path of executable providing the git-upload-pack + * service on remote host * @return {@code this} */ public LsRemoteCommand setUploadPack(String uploadPack) { @@ -140,18 +147,12 @@ public class LsRemoteCommand extends } /** - * Executes the {@code LsRemote} command with all the options and parameters + * {@inheritDoc} + * <p> + * Execute the {@code LsRemote} command with all the options and parameters * collected by the setter methods (e.g. {@link #setHeads(boolean)}) of this * class. Each instance of this class should only be used for one invocation * of the command. Don't call this method twice on an instance. - * - * @return a collection of references in the remote repository - * @throws GitAPIException - * or subclass thereof when an error occurs - * @throws InvalidRemoteException - * when called with an invalid remote uri - * @throws org.eclipse.jgit.api.errors.TransportException - * for errors that occurs during transport */ @Override public Collection<Ref> call() throws GitAPIException, @@ -164,9 +165,9 @@ public class LsRemoteCommand extends * Same as {@link #call()}, but return Map instead of Collection. * * @return a map from names to references in the remote repository - * @throws GitAPIException + * @throws org.eclipse.jgit.api.errors.GitAPIException * or subclass thereof when an error occurs - * @throws InvalidRemoteException + * @throws org.eclipse.jgit.api.errors.InvalidRemoteException * when called with an invalid remote uri * @throws org.eclipse.jgit.api.errors.TransportException * for errors that occurs during transport diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/MergeCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/MergeCommand.java index 75460fbd14..44ff18fcc4 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/MergeCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/MergeCommand.java @@ -211,19 +211,22 @@ public class MergeCommand extends GitCommand<MergeResult> { private Boolean commit; /** + * Constructor for MergeCommand. + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected MergeCommand(Repository repo) { super(repo); } /** - * Executes the {@code Merge} command with all the options and parameters + * {@inheritDoc} + * <p> + * Execute the {@code Merge} command with all the options and parameters * collected by the setter methods (e.g. {@link #include(Ref)}) of this * class. Each instance of this class should only be used for one invocation * of the command. Don't call this method twice on an instance. - * - * @return the result of the merge */ @Override @SuppressWarnings("boxing") @@ -492,9 +495,10 @@ public class MergeCommand extends GitCommand<MergeResult> { } /** + * Set merge strategy * * @param mergeStrategy - * the {@link MergeStrategy} to be used + * the {@link org.eclipse.jgit.merge.MergeStrategy} to be used * @return {@code this} */ public MergeCommand setStrategy(MergeStrategy mergeStrategy) { @@ -504,6 +508,8 @@ public class MergeCommand extends GitCommand<MergeResult> { } /** + * Reference to a commit to be merged with the current head + * * @param aCommit * a reference to a commit which is merged with the current head * @return {@code this} @@ -515,6 +521,8 @@ public class MergeCommand extends GitCommand<MergeResult> { } /** + * Id of a commit which is to be merged with the current head + * * @param aCommit * the Id of a commit which is merged with the current head * @return {@code this} @@ -524,8 +532,10 @@ public class MergeCommand extends GitCommand<MergeResult> { } /** + * Include a commit + * * @param name - * a name given to the commit + * a name of a {@code Ref} pointing to the commit * @param aCommit * the Id of a commit which is merged with the current head * @return {@code this} @@ -541,9 +551,10 @@ public class MergeCommand extends GitCommand<MergeResult> { * HEAD. Otherwise, perform the merge and commit the result. * <p> * In case the merge was successful but this flag was set to - * <code>true</code> a {@link MergeResult} with status - * {@link MergeStatus#MERGED_SQUASHED} or - * {@link MergeStatus#FAST_FORWARD_SQUASHED} is returned. + * <code>true</code> a {@link org.eclipse.jgit.api.MergeResult} with status + * {@link org.eclipse.jgit.api.MergeResult.MergeStatus#MERGED_SQUASHED} or + * {@link org.eclipse.jgit.api.MergeResult.MergeStatus#FAST_FORWARD_SQUASHED} + * is returned. * * @param squash * whether to squash commits or not @@ -582,9 +593,11 @@ public class MergeCommand extends GitCommand<MergeResult> { * <code>true</code> if this command should commit (this is the * default behavior). <code>false</code> if this command should * not commit. In case the merge was successful but this flag was - * set to <code>false</code> a {@link MergeResult} with type - * {@link MergeResult} with status - * {@link MergeStatus#MERGED_NOT_COMMITTED} is returned + * set to <code>false</code> a + * {@link org.eclipse.jgit.api.MergeResult} with type + * {@link org.eclipse.jgit.api.MergeResult} with status + * {@link org.eclipse.jgit.api.MergeResult.MergeStatus#MERGED_NOT_COMMITTED} + * is returned * @return {@code this} * @since 3.0 */ @@ -612,7 +625,6 @@ public class MergeCommand extends GitCommand<MergeResult> { * is set to <code>NullProgressMonitor</code> * * @see NullProgressMonitor - * * @param monitor * A progress monitor * @return this instance diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/MergeResult.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/MergeResult.java index c487ef6509..765b3209d2 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/MergeResult.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/MergeResult.java @@ -53,11 +53,10 @@ import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.merge.MergeChunk; import org.eclipse.jgit.merge.MergeChunk.ConflictState; import org.eclipse.jgit.merge.MergeStrategy; -import org.eclipse.jgit.merge.ResolveMerger; import org.eclipse.jgit.merge.ResolveMerger.MergeFailureReason; /** - * Encapsulates the result of a {@link MergeCommand}. + * Encapsulates the result of a {@link org.eclipse.jgit.api.MergeCommand}. */ public class MergeResult { @@ -249,6 +248,8 @@ public class MergeResult { private List<String> checkoutConflicts; /** + * Constructor for MergeResult. + * * @param newHead * the object the head points at after the merge * @param base @@ -260,10 +261,10 @@ public class MergeResult { * @param mergeStatus * the status the merge resulted in * @param mergeStrategy - * the used {@link MergeStrategy} + * the used {@link org.eclipse.jgit.merge.MergeStrategy} * @param lowLevelResults * merge results as returned by - * {@link ResolveMerger#getMergeResults()} + * {@link org.eclipse.jgit.merge.ResolveMerger#getMergeResults()} * @since 2.0 */ public MergeResult(ObjectId newHead, ObjectId base, @@ -275,6 +276,8 @@ public class MergeResult { } /** + * Constructor for MergeResult. + * * @param newHead * the object the head points at after the merge * @param base @@ -286,9 +289,10 @@ public class MergeResult { * @param mergeStatus * the status the merge resulted in * @param mergeStrategy - * the used {@link MergeStrategy} + * the used {@link org.eclipse.jgit.merge.MergeStrategy} * @param lowLevelResults - * merge results as returned by {@link ResolveMerger#getMergeResults()} + * merge results as returned by + * {@link org.eclipse.jgit.merge.ResolveMerger#getMergeResults()} * @param description * a user friendly description of the merge result */ @@ -302,6 +306,8 @@ public class MergeResult { } /** + * Constructor for MergeResult. + * * @param newHead * the object the head points at after the merge * @param base @@ -313,13 +319,13 @@ public class MergeResult { * @param mergeStatus * the status the merge resulted in * @param mergeStrategy - * the used {@link MergeStrategy} + * the used {@link org.eclipse.jgit.merge.MergeStrategy} * @param lowLevelResults * merge results as returned by - * {@link ResolveMerger#getMergeResults()} + * {@link org.eclipse.jgit.merge.ResolveMerger#getMergeResults()} * @param failingPaths * list of paths causing this merge to fail as returned by - * {@link ResolveMerger#getFailingPaths()} + * {@link org.eclipse.jgit.merge.ResolveMerger#getFailingPaths()} * @param description * a user friendly description of the merge result */ @@ -354,6 +360,8 @@ public class MergeResult { } /** + * Get the object the head points at after the merge + * * @return the object the head points at after the merge */ public ObjectId getNewHead() { @@ -361,6 +369,8 @@ public class MergeResult { } /** + * Get the merge status + * * @return the status the merge resulted in */ public MergeStatus getMergeStatus() { @@ -368,6 +378,8 @@ public class MergeResult { } /** + * Get the commits which have been merged + * * @return all the commits which have been merged together */ public ObjectId[] getMergedCommits() { @@ -375,6 +387,8 @@ public class MergeResult { } /** + * Get the common base + * * @return base the common base which was used to produce a content-merge. * May be <code>null</code> if the merge-result was produced without * computing a common base @@ -383,6 +397,7 @@ public class MergeResult { return base; } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { @@ -402,6 +417,8 @@ public class MergeResult { } /** + * Set conflicts + * * @param conflicts * the conflicts to set */ @@ -410,7 +427,10 @@ public class MergeResult { } /** + * Add a conflict + * * @param path + * path of the file to add a conflict for * @param conflictingRanges * the conflicts to set */ @@ -421,8 +441,12 @@ public class MergeResult { } /** + * Add a conflict + * * @param path + * path of the file to add a conflict for * @param lowLevelResult + * a {@link org.eclipse.jgit.merge.MergeResult} */ public void addConflict(String path, org.eclipse.jgit.merge.MergeResult<?> lowLevelResult) { if (!lowLevelResult.containsConflicts()) @@ -462,9 +486,10 @@ public class MergeResult { /** * Returns information about the conflicts which occurred during a - * {@link MergeCommand}. The returned value maps the path of a conflicting - * file to a two-dimensional int-array of line-numbers telling where in the - * file conflict markers for which merged commit can be found. + * {@link org.eclipse.jgit.api.MergeCommand}. The returned value maps the + * path of a conflicting file to a two-dimensional int-array of line-numbers + * telling where in the file conflict markers for which merged commit can be + * found. * <p> * If the returned value contains a mapping "path"->[x][y]=z then this * means @@ -505,7 +530,7 @@ public class MergeResult { /** * Returns a list of paths causing this merge to fail as returned by - * {@link ResolveMerger#getFailingPaths()} + * {@link org.eclipse.jgit.merge.ResolveMerger#getFailingPaths()} * * @return the list of paths causing this merge to fail or <code>null</code> * if no failure occurred diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/NameRevCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/NameRevCommand.java index 2a86fabede..a9d9759a74 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/NameRevCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/NameRevCommand.java @@ -57,7 +57,6 @@ import org.eclipse.jgit.lib.AnyObjectId; import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.lib.Ref; -import org.eclipse.jgit.lib.RefDatabase; import org.eclipse.jgit.lib.Repository; import org.eclipse.jgit.revwalk.FIFORevQueue; import org.eclipse.jgit.revwalk.RevCommit; @@ -120,6 +119,7 @@ public class NameRevCommand extends GitCommand<Map<ObjectId, String>> { * Create a new name-rev command. * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected NameRevCommand(Repository repo) { super(repo); @@ -134,6 +134,7 @@ public class NameRevCommand extends GitCommand<Map<ObjectId, String>> { }; } + /** {@inheritDoc} */ @Override public Map<ObjectId, String> call() throws GitAPIException { try { @@ -199,13 +200,13 @@ public class NameRevCommand extends GitCommand<Map<ObjectId, String>> { * @param id * object ID to add. * @return {@code this} - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the object supplied is not available from the object * database. - * @throws JGitInternalException + * @throws org.eclipse.jgit.api.errors.JGitInternalException * a low-level exception of JGit has occurred. The original * exception can be retrieved by calling - * {@link Exception#getCause()}. + * {@link java.lang.Exception#getCause()}. */ public NameRevCommand add(ObjectId id) throws MissingObjectException, JGitInternalException { @@ -227,13 +228,13 @@ public class NameRevCommand extends GitCommand<Map<ObjectId, String>> { * @param ids * object IDs to add. * @return {@code this} - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the object supplied is not available from the object * database. - * @throws JGitInternalException + * @throws org.eclipse.jgit.api.errors.JGitInternalException * a low-level exception of JGit has occurred. The original * exception can be retrieved by calling - * {@link Exception#getCause()}. + * {@link java.lang.Exception#getCause()}. */ public NameRevCommand add(Iterable<ObjectId> ids) throws MissingObjectException, JGitInternalException { @@ -250,7 +251,8 @@ public class NameRevCommand extends GitCommand<Map<ObjectId, String>> { * prefix added by {@link #addPrefix(String)}. * * @param prefix - * prefix to add; see {@link RefDatabase#getRefs(String)} + * prefix to add; see + * {@link org.eclipse.jgit.lib.RefDatabase#getRefs(String)} * @return {@code this} */ public NameRevCommand addPrefix(String prefix) { @@ -260,8 +262,8 @@ public class NameRevCommand extends GitCommand<Map<ObjectId, String>> { } /** - * Add all annotated tags under {@code refs/tags/} to the set that all results - * must match. + * Add all annotated tags under {@code refs/tags/} to the set that all + * results must match. * <p> * Calls {@link #addRef(Ref)}; see that method for a note on matching * priority. @@ -270,7 +272,7 @@ public class NameRevCommand extends GitCommand<Map<ObjectId, String>> { * @throws JGitInternalException * a low-level exception of JGit has occurred. The original * exception can be retrieved by calling - * {@link Exception#getCause()}. + * {@link java.lang.Exception#getCause()}. */ public NameRevCommand addAnnotatedTags() { checkCallable(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/PullCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/PullCommand.java index aa97996dfc..f0ad29db49 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/PullCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/PullCommand.java @@ -52,7 +52,6 @@ import org.eclipse.jgit.api.MergeCommand.FastForwardMode; import org.eclipse.jgit.api.MergeCommand.FastForwardMode.Merge; import org.eclipse.jgit.api.RebaseCommand.Operation; import org.eclipse.jgit.api.errors.CanceledException; -import org.eclipse.jgit.api.errors.DetachedHeadException; import org.eclipse.jgit.api.errors.GitAPIException; import org.eclipse.jgit.api.errors.InvalidConfigurationException; import org.eclipse.jgit.api.errors.InvalidRemoteException; @@ -104,13 +103,18 @@ public class PullCommand extends TransportCommand<PullCommand, PullResult> { private FetchRecurseSubmodulesMode submoduleRecurseMode = null; /** + * Constructor for PullCommand. + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected PullCommand(Repository repo) { super(repo); } /** + * Set progress monitor + * * @param monitor * a progress monitor * @return this instance @@ -139,6 +143,7 @@ public class PullCommand extends TransportCommand<PullCommand, PullResult> { * branch.[name].rebase and branch.autosetuprebase. * * @param useRebase + * whether to use rebase after fetching * @return {@code this} */ public PullCommand setRebase(boolean useRebase) { @@ -149,7 +154,8 @@ public class PullCommand extends TransportCommand<PullCommand, PullResult> { } /** - * Sets the {@link BranchRebaseMode} to use after fetching. + * Sets the {@link org.eclipse.jgit.lib.BranchConfig.BranchRebaseMode} to + * use after fetching. * * <dl> * <dt>BranchRebaseMode.REBASE</dt> @@ -176,7 +182,8 @@ public class PullCommand extends TransportCommand<PullCommand, PullResult> { * {@code pull.rebase}. * * @param rebaseMode - * the {@link BranchRebaseMode} to use + * the {@link org.eclipse.jgit.lib.BranchConfig.BranchRebaseMode} + * to use * @return {@code this} * @since 4.5 */ @@ -187,23 +194,13 @@ public class PullCommand extends TransportCommand<PullCommand, PullResult> { } /** - * Executes the {@code Pull} command with all the options and parameters + * {@inheritDoc} + * <p> + * Execute the {@code Pull} command with all the options and parameters * collected by the setter methods (e.g. * {@link #setProgressMonitor(ProgressMonitor)}) of this class. Each * instance of this class should only be used for one invocation of the * command. Don't call this method twice on an instance. - * - * @return the result of the pull - * @throws WrongRepositoryStateException - * @throws InvalidConfigurationException - * @throws DetachedHeadException - * @throws InvalidRemoteException - * @throws CanceledException - * @throws RefNotFoundException - * @throws RefNotAdvertisedException - * @throws NoHeadException - * @throws org.eclipse.jgit.api.errors.TransportException - * @throws GitAPIException */ @Override public PullResult call() throws GitAPIException, @@ -370,6 +367,7 @@ public class PullCommand extends TransportCommand<PullCommand, PullResult> { * * @see Constants#DEFAULT_REMOTE_NAME * @param remote + * name of the remote to pull from * @return {@code this} * @since 3.3 */ @@ -386,6 +384,7 @@ public class PullCommand extends TransportCommand<PullCommand, PullResult> { * the current branch is used. * * @param remoteBranchName + * remote branch name to be used for pull operation * @return {@code this} * @since 3.3 */ @@ -396,6 +395,8 @@ public class PullCommand extends TransportCommand<PullCommand, PullResult> { } /** + * Get the remote name used for pull operation + * * @return the remote used for the pull operation if it was set explicitly * @since 3.3 */ @@ -404,6 +405,8 @@ public class PullCommand extends TransportCommand<PullCommand, PullResult> { } /** + * Get the remote branch name for the pull operation + * * @return the remote branch name used for the pull operation if it was set * explicitly * @since 3.3 @@ -413,6 +416,8 @@ public class PullCommand extends TransportCommand<PullCommand, PullResult> { } /** + * Set the @{code MergeStrategy} + * * @param strategy * The merge strategy to use during this pull operation. * @return {@code this} @@ -424,9 +429,10 @@ public class PullCommand extends TransportCommand<PullCommand, PullResult> { } /** - * Sets the specification of annotated tag behavior during fetch + * Set the specification of annotated tag behavior during fetch * * @param tagOpt + * the {@link org.eclipse.jgit.transport.TagOpt} * @return {@code this} * @since 4.7 */ @@ -437,8 +443,8 @@ public class PullCommand extends TransportCommand<PullCommand, PullResult> { } /** - * Sets the fast forward mode. It is used if pull is configured to do a - * merge as opposed to rebase. If non-{@code null} takes precedence over the + * Set the fast forward mode. It is used if pull is configured to do a merge + * as opposed to rebase. If non-{@code null} takes precedence over the * fast-forward mode configured in git config. * * @param fastForwardMode @@ -461,6 +467,9 @@ public class PullCommand extends TransportCommand<PullCommand, PullResult> { * Set the mode to be used for recursing into submodules. * * @param recurse + * the + * {@link org.eclipse.jgit.lib.SubmoduleConfig.FetchRecurseSubmodulesMode} + * to be used for recursing into submodules * @return {@code this} * @since 4.7 * @see FetchCommand#setRecurseSubmodules(FetchRecurseSubmodulesMode) @@ -475,13 +484,14 @@ public class PullCommand extends TransportCommand<PullCommand, PullResult> { * Reads the rebase mode to use for a pull command from the repository * configuration. This is the value defined for the configurations * {@code branch.[branchName].rebase}, or,if not set, {@code pull.rebase}. - * If neither is set, yields {@link BranchRebaseMode#NONE}. + * If neither is set, yields + * {@link org.eclipse.jgit.lib.BranchConfig.BranchRebaseMode#NONE}. * * @param branchName * name of the local branch * @param config - * the {@link Config} to read the value from - * @return the {@link BranchRebaseMode} + * the {@link org.eclipse.jgit.lib.Config} to read the value from + * @return the {@link org.eclipse.jgit.lib.BranchConfig.BranchRebaseMode} * @since 4.5 */ public static BranchRebaseMode getRebaseMode(String branchName, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/PullResult.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/PullResult.java index c1eb89db7f..7210088341 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/PullResult.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/PullResult.java @@ -45,7 +45,7 @@ package org.eclipse.jgit.api; import org.eclipse.jgit.transport.FetchResult; /** - * Encapsulates the result of a {@link PullCommand} + * Encapsulates the result of a {@link org.eclipse.jgit.api.PullCommand} */ public class PullResult { private final FetchResult fetchResult; @@ -73,6 +73,8 @@ public class PullResult { } /** + * Get fetch result + * * @return the fetch result, or <code>null</code> */ public FetchResult getFetchResult() { @@ -80,6 +82,8 @@ public class PullResult { } /** + * Get merge result + * * @return the merge result, or <code>null</code> */ public MergeResult getMergeResult() { @@ -87,6 +91,8 @@ public class PullResult { } /** + * Get rebase result + * * @return the rebase result, or <code>null</code> */ public RebaseResult getRebaseResult() { @@ -94,6 +100,8 @@ public class PullResult { } /** + * Get name of the remote configuration from which fetch was tried + * * @return the name of the remote configuration from which fetch was tried, * or <code>null</code> */ @@ -102,6 +110,8 @@ public class PullResult { } /** + * Whether the pull was successful + * * @return whether the pull was successful */ public boolean isSuccessful() { @@ -112,6 +122,7 @@ public class PullResult { return true; } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/PushCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/PushCommand.java index bf88842618..19bdd35778 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/PushCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/PushCommand.java @@ -105,7 +105,12 @@ public class PushCommand extends private List<String> pushOptions; /** + * <p> + * Constructor for PushCommand. + * </p> + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected PushCommand(Repository repo) { super(repo); @@ -114,17 +119,12 @@ public class PushCommand extends } /** - * Executes the {@code push} command with all the options and parameters + * {@inheritDoc} + * <p> + * Execute the {@code push} command with all the options and parameters * collected by the setter methods of this class. Each instance of this * class should only be used for one invocation of the command (means: one * call to {@link #call()}) - * - * @return an iteration over {@link PushResult} objects - * @throws InvalidRemoteException - * when called with an invalid remote uri - * @throws org.eclipse.jgit.api.errors.TransportException - * when an error occurs with the transport - * @throws GitAPIException */ @Override public Iterable<PushResult> call() throws GitAPIException, @@ -209,6 +209,7 @@ public class PushCommand extends * * @see Constants#DEFAULT_REMOTE_NAME * @param remote + * the remote name * @return {@code this} */ public PushCommand setRemote(String remote) { @@ -218,6 +219,8 @@ public class PushCommand extends } /** + * Get remote name + * * @return the remote used for the remote operation */ public String getRemote() { @@ -231,6 +234,8 @@ public class PushCommand extends * * @see RemoteConfig#DEFAULT_RECEIVE_PACK * @param receivePack + * name of the remote executable providing the receive-pack + * service * @return {@code this} */ public PushCommand setReceivePack(String receivePack) { @@ -240,6 +245,8 @@ public class PushCommand extends } /** + * Get the name of the remote executable providing the receive-pack service + * * @return the receive-pack used for the remote operation */ public String getReceivePack() { @@ -247,6 +254,8 @@ public class PushCommand extends } /** + * Get timeout used for push operation + * * @return the timeout used for the push operation */ public int getTimeout() { @@ -254,6 +263,8 @@ public class PushCommand extends } /** + * Get the progress monitor + * * @return the progress monitor for the push operation */ public ProgressMonitor getProgressMonitor() { @@ -265,8 +276,8 @@ public class PushCommand extends * is set to <code>NullProgressMonitor</code> * * @see NullProgressMonitor - * * @param monitor + * a {@link org.eclipse.jgit.lib.ProgressMonitor} * @return {@code this} */ public PushCommand setProgressMonitor(ProgressMonitor monitor) { @@ -279,7 +290,9 @@ public class PushCommand extends } /** - * @return the ref lease specs + * Get the <code>RefLeaseSpec</code>s. + * + * @return the <code>RefLeaseSpec</code>s * @since 4.7 */ public List<RefLeaseSpec> getRefLeaseSpecs() { @@ -287,10 +300,11 @@ public class PushCommand extends } /** - * The ref lease specs to be used in the push operation, - * for a force-with-lease push operation. + * The ref lease specs to be used in the push operation, for a + * force-with-lease push operation. * * @param specs + * a {@link org.eclipse.jgit.transport.RefLeaseSpec} object. * @return {@code this} * @since 4.7 */ @@ -299,10 +313,11 @@ public class PushCommand extends } /** - * The ref lease specs to be used in the push operation, - * for a force-with-lease push operation. + * The ref lease specs to be used in the push operation, for a + * force-with-lease push operation. * * @param specs + * list of {@code RefLeaseSpec}s * @return {@code this} * @since 4.7 */ @@ -316,6 +331,8 @@ public class PushCommand extends } /** + * Get {@code RefSpec}s. + * * @return the ref specs */ public List<RefSpec> getRefSpecs() { @@ -325,7 +342,7 @@ public class PushCommand extends /** * The ref specs to be used in the push operation * - * @param specs + * @param specs a {@link org.eclipse.jgit.transport.RefSpec} object. * @return {@code this} */ public PushCommand setRefSpecs(RefSpec... specs) { @@ -339,6 +356,7 @@ public class PushCommand extends * The ref specs to be used in the push operation * * @param specs + * list of {@link org.eclipse.jgit.transport.RefSpec}s * @return {@code this} */ public PushCommand setRefSpecs(List<RefSpec> specs) { @@ -408,6 +426,8 @@ public class PushCommand extends } /** + * Whether to run the push operation as a dry run + * * @return the dry run preference for the push operation */ public boolean isDryRun() { @@ -417,7 +437,7 @@ public class PushCommand extends /** * Sets whether the push operation should be a dry run * - * @param dryRun + * @param dryRun a boolean. * @return {@code this} */ public PushCommand setDryRun(boolean dryRun) { @@ -427,6 +447,8 @@ public class PushCommand extends } /** + * Get the thin-pack preference + * * @return the thin-pack preference for push operation */ public boolean isThin() { @@ -434,11 +456,12 @@ public class PushCommand extends } /** - * Sets the thin-pack preference for push operation. + * Set the thin-pack preference for push operation. * * Default setting is Transport.DEFAULT_PUSH_THIN * * @param thin + * the thin-pack preference value * @return {@code this} */ public PushCommand setThin(boolean thin) { @@ -448,6 +471,9 @@ public class PushCommand extends } /** + * Whether this push should be executed atomically (all references updated, + * or none) + * * @return true if all-or-nothing behavior is requested. * @since 4.2 */ @@ -461,6 +487,7 @@ public class PushCommand extends * Default setting is false. * * @param atomic + * whether to run the push atomically * @return {@code this} * @since 4.2 */ @@ -471,6 +498,8 @@ public class PushCommand extends } /** + * Whether to push forcefully + * * @return the force preference for push operation */ public boolean isForce() { @@ -481,6 +510,7 @@ public class PushCommand extends * Sets the force preference for push operation. * * @param force + * whether to push forcefully * @return {@code this} */ public PushCommand setForce(boolean force) { @@ -493,6 +523,7 @@ public class PushCommand extends * Sets the output stream to write sideband messages to * * @param out + * an {@link java.io.OutputStream} * @return {@code this} * @since 3.0 */ @@ -502,6 +533,8 @@ public class PushCommand extends } /** + * Get push options + * * @return the option strings associated with the push operation * @since 4.5 */ @@ -510,9 +543,10 @@ public class PushCommand extends } /** - * Sets the option strings associated with the push operation. + * Set the option strings associated with the push operation. * * @param pushOptions + * a {@link java.util.List} of push option strings * @return {@code this} * @since 4.5 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/RebaseCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/RebaseCommand.java index 955c50b376..b86a2fdf8e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/RebaseCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/RebaseCommand.java @@ -238,7 +238,12 @@ public class RebaseCommand extends GitCommand<RebaseResult> { private boolean preserveMerges = false; /** + * <p> + * Constructor for RebaseCommand. + * </p> + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected RebaseCommand(Repository repo) { super(repo); @@ -247,16 +252,12 @@ public class RebaseCommand extends GitCommand<RebaseResult> { } /** + * {@inheritDoc} + * <p> * Executes the {@code Rebase} command with all the options and parameters * collected by the setter methods of this class. Each instance of this * class should only be used for one invocation of the command. Don't call * this method twice on an instance. - * - * @return an object describing the result of this command - * @throws GitAPIException - * @throws WrongRepositoryStateException - * @throws NoHeadException - * @throws RefNotFoundException */ @Override public RebaseResult call() throws GitAPIException, NoHeadException, @@ -1228,12 +1229,14 @@ public class RebaseCommand extends GitCommand<RebaseResult> { } /** - * checks if we can fast-forward and returns the new head if it is possible + * Check if we can fast-forward and returns the new head if it is possible * * @param newCommit + * a {@link org.eclipse.jgit.revwalk.RevCommit} object to check + * if we can fast-forward to. * @return the new head, or null - * @throws IOException - * @throws GitAPIException + * @throws java.io.IOException + * @throws org.eclipse.jgit.api.errors.GitAPIException */ public RevCommit tryFastForward(RevCommit newCommit) throws IOException, GitAPIException { @@ -1436,6 +1439,8 @@ public class RebaseCommand extends GitCommand<RebaseResult> { /** + * Set upstream {@code RevCommit} + * * @param upstream * the upstream commit * @return {@code this} @@ -1447,6 +1452,8 @@ public class RebaseCommand extends GitCommand<RebaseResult> { } /** + * Set the upstream commit + * * @param upstream * id of the upstream commit * @return {@code this} @@ -1464,10 +1471,12 @@ public class RebaseCommand extends GitCommand<RebaseResult> { } /** + * Set the upstream branch + * * @param upstream - * the upstream branch + * the name of the upstream branch * @return {@code this} - * @throws RefNotFoundException + * @throws org.eclipse.jgit.api.errors.RefNotFoundException */ public RebaseCommand setUpstream(String upstream) throws RefNotFoundException { @@ -1502,6 +1511,8 @@ public class RebaseCommand extends GitCommand<RebaseResult> { } /** + * Set the operation to execute during rebase + * * @param operation * the operation to perform * @return {@code this} @@ -1512,6 +1523,8 @@ public class RebaseCommand extends GitCommand<RebaseResult> { } /** + * Set progress monitor + * * @param monitor * a progress monitor * @return this instance @@ -1525,15 +1538,18 @@ public class RebaseCommand extends GitCommand<RebaseResult> { } /** - * Enables interactive rebase + * Enable interactive rebase * <p> * Does not stop after initialization of interactive rebase. This is * equivalent to - * {@link RebaseCommand#runInteractively(InteractiveHandler, boolean) + * {@link org.eclipse.jgit.api.RebaseCommand#runInteractively(InteractiveHandler, boolean) * runInteractively(handler, false)}; * </p> * * @param handler + * the + * {@link org.eclipse.jgit.api.RebaseCommand.InteractiveHandler} + * to use * @return this */ public RebaseCommand runInteractively(InteractiveHandler handler) { @@ -1541,14 +1557,17 @@ public class RebaseCommand extends GitCommand<RebaseResult> { } /** - * Enables interactive rebase + * Enable interactive rebase * <p> * If stopAfterRebaseInteractiveInitialization is {@code true} the rebase * stops after initialization of interactive rebase returning - * {@link RebaseResult#INTERACTIVE_PREPARED_RESULT} + * {@link org.eclipse.jgit.api.RebaseResult#INTERACTIVE_PREPARED_RESULT} * </p> * * @param handler + * the + * {@link org.eclipse.jgit.api.RebaseCommand.InteractiveHandler} + * to use * @param stopAfterRebaseInteractiveInitialization * if {@code true} the rebase stops after initialization * @return this instance @@ -1562,6 +1581,8 @@ public class RebaseCommand extends GitCommand<RebaseResult> { } /** + * Set the <code>MergeStrategy</code>. + * * @param strategy * The merge strategy to use during this rebase operation. * @return {@code this} @@ -1573,9 +1594,11 @@ public class RebaseCommand extends GitCommand<RebaseResult> { } /** + * Whether to preserve merges during rebase + * * @param preserve - * True to re-create merges during rebase. Defaults to false, a - * flattening rebase. + * {@code true} to re-create merges during rebase. Defaults to + * {@code false}, a flattening rebase. * @return {@code this} * @since 3.5 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/RebaseResult.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/RebaseResult.java index 92c1347ab2..bad6a7c718 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/RebaseResult.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/RebaseResult.java @@ -45,12 +45,11 @@ package org.eclipse.jgit.api; import java.util.List; import java.util.Map; -import org.eclipse.jgit.merge.ResolveMerger; import org.eclipse.jgit.merge.ResolveMerger.MergeFailureReason; import org.eclipse.jgit.revwalk.RevCommit; /** - * The result of a {@link RebaseCommand} execution + * The result of a {@link org.eclipse.jgit.api.RebaseCommand} execution */ public class RebaseResult { /** @@ -279,6 +278,8 @@ public class RebaseResult { } /** + * Get the status + * * @return the overall status */ public Status getStatus() { @@ -286,33 +287,46 @@ public class RebaseResult { } /** - * @return the current commit if status is {@link Status#STOPPED}, otherwise - * <code>null</code> + * Get the current commit if status is + * {@link org.eclipse.jgit.api.RebaseResult.Status#STOPPED}, otherwise + * <code>null</code> + * + * @return the current commit if status is + * {@link org.eclipse.jgit.api.RebaseResult.Status#STOPPED}, + * otherwise <code>null</code> */ public RevCommit getCurrentCommit() { return currentCommit; } /** + * Get the list of paths causing this rebase to fail + * * @return the list of paths causing this rebase to fail (see - * {@link ResolveMerger#getFailingPaths()} for details) if status is - * {@link Status#FAILED}, otherwise <code>null</code> + * {@link org.eclipse.jgit.merge.ResolveMerger#getFailingPaths()} + * for details) if status is + * {@link org.eclipse.jgit.api.RebaseResult.Status#FAILED}, + * otherwise <code>null</code> */ public Map<String, MergeFailureReason> getFailingPaths() { return failingPaths; } /** - * @return the list of conflicts if status is {@link Status#CONFLICTS} + * Get the list of conflicts + * + * @return the list of conflicts if status is + * {@link org.eclipse.jgit.api.RebaseResult.Status#CONFLICTS} */ public List<String> getConflicts() { return conflicts; } /** - * @return the list of uncommitted changes if status is - * {@link Status#UNCOMMITTED_CHANGES} + * <p>Getter for the field <code>uncommittedChanges</code>.</p> * + * @return the list of uncommitted changes if status is + * {@link org.eclipse.jgit.api.RebaseResult.Status#UNCOMMITTED_CHANGES} * @since 3.2 */ public List<String> getUncommittedChanges() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/ReflogCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/ReflogCommand.java index 394bea5b62..bf3163aaaf 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/ReflogCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/ReflogCommand.java @@ -67,7 +67,10 @@ public class ReflogCommand extends GitCommand<Collection<ReflogEntry>> { private String ref = Constants.HEAD; /** + * Constructor for ReflogCommand. + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ public ReflogCommand(Repository repo) { super(repo); @@ -78,6 +81,7 @@ public class ReflogCommand extends GitCommand<Collection<ReflogEntry>> { * value of HEAD will be used. * * @param ref + * the name of the {@code Ref} to log * @return {@code this} */ public ReflogCommand setRef(String ref) { @@ -87,10 +91,9 @@ public class ReflogCommand extends GitCommand<Collection<ReflogEntry>> { } /** + * {@inheritDoc} + * <p> * Run the reflog command - * - * @throws GitAPIException - * @throws InvalidRefNameException */ @Override public Collection<ReflogEntry> call() throws GitAPIException, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/RemoteAddCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/RemoteAddCommand.java index 679566903f..c43c5c6f98 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/RemoteAddCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/RemoteAddCommand.java @@ -63,7 +63,6 @@ import org.eclipse.jgit.transport.URIish; * @see <a href= * "http://www.kernel.org/pub/software/scm/git/docs/git-remote.html" > Git * documentation about Remote</a> - * * @since 4.2 */ public class RemoteAddCommand extends GitCommand<RemoteConfig> { @@ -73,7 +72,10 @@ public class RemoteAddCommand extends GitCommand<RemoteConfig> { private URIish uri; /** + * Constructor for RemoteAddCommand. + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected RemoteAddCommand(Repository repo) { super(repo); @@ -100,10 +102,10 @@ public class RemoteAddCommand extends GitCommand<RemoteConfig> { } /** + * {@inheritDoc} + * <p> * Executes the {@code remote add} command with all the options and * parameters collected by the setter methods of this class. - * - * @return the {@link RemoteConfig} object of the added remote */ @Override public RemoteConfig call() throws GitAPIException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/RemoteListCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/RemoteListCommand.java index f778eaa28c..f96651f894 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/RemoteListCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/RemoteListCommand.java @@ -59,23 +59,27 @@ import org.eclipse.jgit.transport.RemoteConfig; * @see <a href= * "http://www.kernel.org/pub/software/scm/git/docs/git-remote.html" > Git * documentation about Remote</a> - * * @since 4.2 */ public class RemoteListCommand extends GitCommand<List<RemoteConfig>> { /** + * <p> + * Constructor for RemoteListCommand. + * </p> + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected RemoteListCommand(Repository repo) { super(repo); } /** + * {@inheritDoc} + * <p> * Executes the {@code remote} command with all the options and parameters * collected by the setter methods of this class. - * - * @return a list of {@link RemoteConfig} objects. */ @Override public List<RemoteConfig> call() throws GitAPIException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/RemoteRemoveCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/RemoteRemoveCommand.java index 5782bf61b5..7a5885cfda 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/RemoteRemoveCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/RemoteRemoveCommand.java @@ -61,7 +61,6 @@ import org.eclipse.jgit.transport.RemoteConfig; * @see <a href= * "http://www.kernel.org/pub/software/scm/git/docs/git-remote.html" > Git * documentation about Remote</a> - * * @since 4.2 */ public class RemoteRemoveCommand extends GitCommand<RemoteConfig> { @@ -69,7 +68,12 @@ public class RemoteRemoveCommand extends GitCommand<RemoteConfig> { private String name; /** + * <p> + * Constructor for RemoteRemoveCommand. + * </p> + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected RemoteRemoveCommand(Repository repo) { super(repo); @@ -86,10 +90,10 @@ public class RemoteRemoveCommand extends GitCommand<RemoteConfig> { } /** + * {@inheritDoc} + * <p> * Executes the {@code remote} command with all the options and parameters * collected by the setter methods of this class. - * - * @return the {@link RemoteConfig} object of the removed remote */ @Override public RemoteConfig call() throws GitAPIException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/RemoteSetUrlCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/RemoteSetUrlCommand.java index 6bd2ac7993..d7b7a31bd6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/RemoteSetUrlCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/RemoteSetUrlCommand.java @@ -62,7 +62,6 @@ import org.eclipse.jgit.transport.URIish; * @see <a href= * "http://www.kernel.org/pub/software/scm/git/docs/git-remote.html" > Git * documentation about Remote</a> - * * @since 4.2 */ public class RemoteSetUrlCommand extends GitCommand<RemoteConfig> { @@ -74,7 +73,12 @@ public class RemoteSetUrlCommand extends GitCommand<RemoteConfig> { private boolean push; /** + * <p> + * Constructor for RemoteSetUrlCommand. + * </p> + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected RemoteSetUrlCommand(Repository repo) { super(repo); @@ -112,10 +116,10 @@ public class RemoteSetUrlCommand extends GitCommand<RemoteConfig> { } /** + * {@inheritDoc} + * <p> * Executes the {@code remote} command with all the options and parameters * collected by the setter methods of this class. - * - * @return the {@link RemoteConfig} object of the modified remote */ @Override public RemoteConfig call() throws GitAPIException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/RemoveNoteCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/RemoveNoteCommand.java index fd8aac75bd..baae8248f3 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/RemoveNoteCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/RemoveNoteCommand.java @@ -73,12 +73,18 @@ public class RemoveNoteCommand extends GitCommand<Note> { private String notesRef = Constants.R_NOTES_COMMITS; /** + * <p> + * Constructor for RemoveNoteCommand. + * </p> + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected RemoveNoteCommand(Repository repo) { super(repo); } + /** {@inheritDoc} */ @Override public Note call() throws GitAPIException { checkCallable(); @@ -105,6 +111,8 @@ public class RemoveNoteCommand extends GitCommand<Note> { * Sets the object id of object you want to remove a note * * @param id + * the {@link org.eclipse.jgit.revwalk.RevObject} to remove a + * note from. * @return {@code this} */ public RemoveNoteCommand setObjectId(RevObject id) { @@ -138,12 +146,13 @@ public class RemoveNoteCommand extends GitCommand<Note> { } /** + * Set the name of the <code>Ref</code> to remove a note from. + * * @param notesRef - * the ref to read notes from. Note, the default value of - * {@link Constants#R_NOTES_COMMITS} will be used if nothing is - * set + * the {@code Ref} to read notes from. Note, the default value of + * {@link org.eclipse.jgit.lib.Constants#R_NOTES_COMMITS} will be + * used if nothing is set * @return {@code this} - * * @see Constants#R_NOTES_COMMITS */ public RemoveNoteCommand setNotesRef(String notesRef) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/RenameBranchCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/RenameBranchCommand.java index ce3a29f36c..24d9dd4015 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/RenameBranchCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/RenameBranchCommand.java @@ -77,25 +77,18 @@ public class RenameBranchCommand extends GitCommand<Ref> { private String newName; /** + * <p> + * Constructor for RenameBranchCommand. + * </p> + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected RenameBranchCommand(Repository repo) { super(repo); } - /** - * @throws RefNotFoundException - * if the old branch can not be found (branch with provided old - * name does not exist or old name resolves to a tag) - * @throws InvalidRefNameException - * if the provided new name is <code>null</code> or otherwise - * invalid - * @throws RefAlreadyExistsException - * if a branch with the new name already exists - * @throws DetachedHeadException - * if rename is tried without specifying the old name and HEAD - * is detached - */ + /** {@inheritDoc} */ @Override public Ref call() throws GitAPIException, RefNotFoundException, InvalidRefNameException, RefAlreadyExistsException, DetachedHeadException { @@ -198,6 +191,8 @@ public class RenameBranchCommand extends GitCommand<Ref> { } /** + * Set the new name of the branch + * * @param newName * the new name * @return this instance @@ -209,6 +204,8 @@ public class RenameBranchCommand extends GitCommand<Ref> { } /** + * Set the old name of the branch + * * @param oldName * the name of the branch to rename; if not set, the currently * checked out branch (if any) will be renamed diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/ResetCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/ResetCommand.java index c5222c2d5f..86a69b019d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/ResetCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/ResetCommand.java @@ -126,20 +126,23 @@ public class ResetCommand extends GitCommand<Ref> { private boolean isReflogDisabled; /** + * <p> + * Constructor for ResetCommand. + * </p> * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ public ResetCommand(Repository repo) { super(repo); } /** + * {@inheritDoc} + * <p> * Executes the {@code Reset} command. Each instance of this class should * only be used for one invocation of the command. Don't call this method * twice on an instance. - * - * @return the Ref after reset - * @throws GitAPIException */ @Override public Ref call() throws GitAPIException, CheckoutConflictException { @@ -258,6 +261,8 @@ public class ResetCommand extends GitCommand<Ref> { } /** + * Set the name of the <code>Ref</code> to reset to + * * @param ref * the ref to reset to, defaults to HEAD if not specified * @return this instance @@ -268,6 +273,8 @@ public class ResetCommand extends GitCommand<Ref> { } /** + * Set the reset mode + * * @param mode * the mode of the reset command * @return this instance @@ -282,6 +289,8 @@ public class ResetCommand extends GitCommand<Ref> { } /** + * Repository relative path of file or directory to reset + * * @param path * repository-relative path of file/directory to reset (with * <code>/</code> as separator) @@ -297,6 +306,8 @@ public class ResetCommand extends GitCommand<Ref> { } /** + * Whether to disable reflog + * * @param disable * if {@code true} disables writing a reflog entry for this reset * command @@ -309,6 +320,8 @@ public class ResetCommand extends GitCommand<Ref> { } /** + * Whether reflog is disabled + * * @return {@code true} if writing reflog is disabled for this reset command * @since 4.5 */ @@ -433,6 +446,7 @@ public class ResetCommand extends GitCommand<Ref> { repo.writeMergeCommitMsg(null); } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/RevertCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/RevertCommand.java index c3152a93b4..fa0d4c4882 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/RevertCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/RevertCommand.java @@ -98,27 +98,24 @@ public class RevertCommand extends GitCommand<RevCommit> { private MergeStrategy strategy = MergeStrategy.RECURSIVE; /** + * <p> + * Constructor for RevertCommand. + * </p> + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected RevertCommand(Repository repo) { super(repo); } /** + * {@inheritDoc} + * <p> * Executes the {@code revert} command with all the options and parameters * collected by the setter methods (e.g. {@link #include(Ref)} of this * class. Each instance of this class should only be used for one invocation * of the command. Don't call this method twice on an instance. - * - * @return on success the {@link RevCommit} pointed to by the new HEAD is - * returned. If a failure occurred during revert <code>null</code> - * is returned. The list of successfully reverted {@link Ref}'s can - * be obtained by calling {@link #getRevertedRefs()} - * @throws GitAPIException - * @throws WrongRepositoryStateException - * @throws ConcurrentRefUpdateException - * @throws UnmergedPathsException - * @throws NoMessageException */ @Override public RevCommit call() throws NoMessageException, UnmergedPathsException, @@ -227,9 +224,10 @@ public class RevertCommand extends GitCommand<RevCommit> { } /** + * Include a {@code Ref} to a commit to be reverted + * * @param commit - * a reference to a commit which is reverted into the current - * head + * a reference to a commit to be reverted into the current head * @return {@code this} */ public RevertCommand include(Ref commit) { @@ -239,8 +237,10 @@ public class RevertCommand extends GitCommand<RevCommit> { } /** + * Include a commit to be reverted + * * @param commit - * the Id of a commit which is reverted into the current head + * the Id of a commit to be reverted into the current head * @return {@code this} */ public RevertCommand include(AnyObjectId commit) { @@ -248,8 +248,10 @@ public class RevertCommand extends GitCommand<RevCommit> { } /** + * Include a commit to be reverted + * * @param name - * a name given to the commit + * name of a {@code Ref} referring to the commit * @param commit * the Id of a commit which is reverted into the current head * @return {@code this} @@ -260,6 +262,8 @@ public class RevertCommand extends GitCommand<RevCommit> { } /** + * Set the name to be used in the "OURS" place for conflict markers + * * @param ourCommitName * the name that should be used in the "OURS" place for conflict * markers @@ -280,16 +284,20 @@ public class RevertCommand extends GitCommand<RevCommit> { } /** - * @return the list of successfully reverted {@link Ref}'s. Never - * <code>null</code> but maybe an empty list if no commit was - * successfully cherry-picked + * Get the list of successfully reverted {@link org.eclipse.jgit.lib.Ref}'s. + * + * @return the list of successfully reverted + * {@link org.eclipse.jgit.lib.Ref}'s. Never <code>null</code> but + * maybe an empty list if no commit was successfully cherry-picked */ public List<Ref> getRevertedRefs() { return revertedRefs; } /** - * @return the result of the merge failure, <code>null</code> if no merge + * Get the result of a merge failure + * + * @return the result of a merge failure, <code>null</code> if no merge * failure occurred during the revert */ public MergeResult getFailingResult() { @@ -297,6 +305,8 @@ public class RevertCommand extends GitCommand<RevCommit> { } /** + * Get unmerged paths + * * @return the unmerged paths, will be null if no merge conflicts */ public List<String> getUnmergedPaths() { @@ -304,8 +314,10 @@ public class RevertCommand extends GitCommand<RevCommit> { } /** + * Set the merge strategy to use for this revert command + * * @param strategy - * The merge strategy to use during this revert command. + * The merge strategy to use for this revert command. * @return {@code this} * @since 3.4 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/RmCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/RmCommand.java index 48c23f59c2..088aa15e57 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/RmCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/RmCommand.java @@ -72,7 +72,7 @@ import org.eclipse.jgit.treewalk.filter.PathFilterGroup; * class should only be used for one invocation of the command (means: one call * to {@link #call()}). * <p> - * Examples (<code>git</code> is a {@link Git} instance): + * Examples (<code>git</code> is a {@link org.eclipse.jgit.api.Git} instance): * <p> * Remove file "test.txt" from both index and working directory: * @@ -97,8 +97,10 @@ public class RmCommand extends GitCommand<DirCache> { private boolean cached = false; /** + * Constructor for RmCommand. * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ public RmCommand(Repository repo) { super(repo); @@ -106,6 +108,8 @@ public class RmCommand extends GitCommand<DirCache> { } /** + * Add file name pattern of files to be removed + * * @param filepattern * repository-relative path of file to remove (with * <code>/</code> as separator) @@ -121,8 +125,9 @@ public class RmCommand extends GitCommand<DirCache> { * Only remove the specified files from the index. * * @param cached - * true if files should only be removed from index, false if - * files should also be deleted from the working directory + * {@code true} if files should only be removed from index, + * {@code false} if files should also be deleted from the working + * directory * @return {@code this} * @since 2.2 */ @@ -133,11 +138,11 @@ public class RmCommand extends GitCommand<DirCache> { } /** + * {@inheritDoc} + * <p> * Executes the {@code Rm} command. Each instance of this class should only * be used for one invocation of the command. Don't call this method twice * on an instance. - * - * @return the DirCache after Rm */ @Override public DirCache call() throws GitAPIException, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/ShowNoteCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/ShowNoteCommand.java index dbff4636e7..eb81d20a55 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/ShowNoteCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/ShowNoteCommand.java @@ -68,12 +68,16 @@ public class ShowNoteCommand extends GitCommand<Note> { private String notesRef = Constants.R_NOTES_COMMITS; /** + * Constructor for ShowNoteCommand. + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ protected ShowNoteCommand(Repository repo) { super(repo); } + /** {@inheritDoc} */ @Override public Note call() throws GitAPIException { checkCallable(); @@ -96,6 +100,8 @@ public class ShowNoteCommand extends GitCommand<Note> { * Sets the object id of object you want a note on * * @param id + * the {@link org.eclipse.jgit.revwalk.RevObject} to show notes + * for. * @return {@code this} */ public ShowNoteCommand setObjectId(RevObject id) { @@ -105,12 +111,13 @@ public class ShowNoteCommand extends GitCommand<Note> { } /** + * Set the {@code Ref} to read notes from. + * * @param notesRef * the ref to read notes from. Note, the default value of - * {@link Constants#R_NOTES_COMMITS} will be used if nothing is - * set + * {@link org.eclipse.jgit.lib.Constants#R_NOTES_COMMITS} will be + * used if nothing is set * @return {@code this} - * * @see Constants#R_NOTES_COMMITS */ public ShowNoteCommand setNotesRef(String notesRef) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/StashApplyCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/StashApplyCommand.java index b56fb2519b..5f7928d4d8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/StashApplyCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/StashApplyCommand.java @@ -42,6 +42,8 @@ */ package org.eclipse.jgit.api; +import static org.eclipse.jgit.treewalk.TreeWalk.OperationType.CHECKOUT_OP; + import java.io.IOException; import java.text.MessageFormat; import java.util.HashSet; @@ -86,7 +88,6 @@ import org.eclipse.jgit.treewalk.TreeWalk; * * @see <a href="http://www.kernel.org/pub/software/scm/git/docs/git-stash.html" * >Git documentation about Stash</a> - * * @since 2.0 */ public class StashApplyCommand extends GitCommand<ObjectId> { @@ -107,6 +108,8 @@ public class StashApplyCommand extends GitCommand<ObjectId> { * Create command to apply the changes of a stashed commit * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} to apply the stash + * to */ public StashApplyCommand(final Repository repo) { super(repo); @@ -119,6 +122,7 @@ public class StashApplyCommand extends GitCommand<ObjectId> { * unspecified * * @param stashRef + * name of the stash {@code Ref} to apply * @return {@code this} */ public StashApplyCommand setStashRef(final String stashRef) { @@ -127,7 +131,10 @@ public class StashApplyCommand extends GitCommand<ObjectId> { } /** + * Whether to ignore the repository state when applying the stash + * * @param willIgnoreRepositoryState + * whether to ignore the repository state when applying the stash * @return {@code this} * @since 3.2 */ @@ -152,14 +159,9 @@ public class StashApplyCommand extends GitCommand<ObjectId> { } /** + * {@inheritDoc} + * <p> * Apply the changes in a stashed commit to the working directory and index - * - * @return id of stashed commit that was applied TODO: Does anyone depend on - * this, or could we make it more like Merge/CherryPick/Revert? - * @throws GitAPIException - * @throws WrongRepositoryStateException - * @throws NoHeadException - * @throws StashApplyFailureException */ @Override public ObjectId call() throws GitAPIException, @@ -271,6 +273,8 @@ public class StashApplyCommand extends GitCommand<ObjectId> { } /** + * Whether to restore the index state + * * @param applyIndex * true (default) if the command should restore the index state */ @@ -279,6 +283,8 @@ public class StashApplyCommand extends GitCommand<ObjectId> { } /** + * Set the <code>MergeStrategy</code> to use. + * * @param strategy * The merge strategy to use in order to merge during this * command execution. @@ -291,6 +297,8 @@ public class StashApplyCommand extends GitCommand<ObjectId> { } /** + * Whether the command should restore untracked files + * * @param applyUntracked * true (default) if the command should restore untracked files * @since 3.4 @@ -355,7 +363,8 @@ public class StashApplyCommand extends GitCommand<ObjectId> { // Not in commit, don't create untracked continue; - final EolStreamType eolStreamType = walk.getEolStreamType(); + final EolStreamType eolStreamType = walk + .getEolStreamType(CHECKOUT_OP); final DirCacheEntry entry = new DirCacheEntry(walk.getRawPath()); entry.setFileMode(cIter.getEntryFileMode()); entry.setObjectIdFromRaw(cIter.idBuffer(), cIter.idOffset()); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/StashCreateCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/StashCreateCommand.java index 77a7fffb70..3495ff8a9d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/StashCreateCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/StashCreateCommand.java @@ -115,6 +115,7 @@ public class StashCreateCommand extends GitCommand<RevCommit> { * Create a command to stash changes in the working directory and index * * @param repo + * a {@link org.eclipse.jgit.lib.Repository} object. */ public StashCreateCommand(Repository repo) { super(repo); @@ -128,6 +129,7 @@ public class StashCreateCommand extends GitCommand<RevCommit> { * id, and short commit message when used. * * @param message + * the stash message * @return {@code this} */ public StashCreateCommand setIndexMessage(String message) { @@ -142,6 +144,7 @@ public class StashCreateCommand extends GitCommand<RevCommit> { * id, and short commit message when used. * * @param message + * the working directory message * @return {@code this} */ public StashCreateCommand setWorkingDirectoryMessage(String message) { @@ -153,6 +156,8 @@ public class StashCreateCommand extends GitCommand<RevCommit> { * Set the person to use as the author and committer in the commits made * * @param person + * the {@link org.eclipse.jgit.lib.PersonIdent} of the person who + * creates the stash. * @return {@code this} */ public StashCreateCommand setPerson(PersonIdent person) { @@ -161,12 +166,13 @@ public class StashCreateCommand extends GitCommand<RevCommit> { } /** - * Set the reference to update with the stashed commit id - * If null, no reference is updated + * Set the reference to update with the stashed commit id If null, no + * reference is updated * <p> - * This value defaults to {@link Constants#R_STASH} + * This value defaults to {@link org.eclipse.jgit.lib.Constants#R_STASH} * * @param ref + * the name of the {@code Ref} to update * @return {@code this} */ public StashCreateCommand setRef(String ref) { @@ -178,6 +184,7 @@ public class StashCreateCommand extends GitCommand<RevCommit> { * Whether to include untracked files in the stash. * * @param includeUntracked + * whether to include untracked files in the stash * @return {@code this} * @since 3.4 */ @@ -232,11 +239,10 @@ public class StashCreateCommand extends GitCommand<RevCommit> { } /** + * {@inheritDoc} + * <p> * Stash the contents on the working directory and index in separate commits * and reset to the current HEAD commit. - * - * @return stashed commit or null if no changes to stash - * @throws GitAPIException */ @Override public RevCommit call() throws GitAPIException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/StashDropCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/StashDropCommand.java index 85e7b3d298..cd8f8e6c96 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/StashDropCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/StashDropCommand.java @@ -84,7 +84,10 @@ public class StashDropCommand extends GitCommand<ObjectId> { private boolean all; /** + * Constructor for StashDropCommand. + * * @param repo + * a {@link org.eclipse.jgit.lib.Repository} object. */ public StashDropCommand(Repository repo) { super(repo); @@ -101,6 +104,7 @@ public class StashDropCommand extends GitCommand<ObjectId> { * unspecified * * @param stashRef + * the 0-based index of the stash reference * @return {@code this} */ public StashDropCommand setStashRef(final int stashRef) { @@ -112,11 +116,12 @@ public class StashDropCommand extends GitCommand<ObjectId> { } /** - * Set wheter drop all stashed commits + * Set whether to drop all stashed commits * * @param all - * true to drop all stashed commits, false to drop only the - * stashed commit set via calling {@link #setStashRef(int)} + * {@code true} to drop all stashed commits, {@code false} to + * drop only the stashed commit set via calling + * {@link #setStashRef(int)} * @return {@code this} */ public StashDropCommand setAll(final boolean all) { @@ -173,11 +178,10 @@ public class StashDropCommand extends GitCommand<ObjectId> { } /** + * {@inheritDoc} + * <p> * Drop the configured entry from the stash reflog and return value of the * stash reference after the drop occurs - * - * @return commit id of stash reference or null if no more stashed changes - * @throws GitAPIException */ @Override public ObjectId call() throws GitAPIException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/StashListCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/StashListCommand.java index 8420dd228e..6451b709f0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/StashListCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/StashListCommand.java @@ -70,12 +70,13 @@ public class StashListCommand extends GitCommand<Collection<RevCommit>> { /** * Create a new stash list command * - * @param repo + * @param repo a {@link org.eclipse.jgit.lib.Repository} object. */ public StashListCommand(final Repository repo) { super(repo); } + /** {@inheritDoc} */ @Override public Collection<RevCommit> call() throws GitAPIException, InvalidRefNameException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/Status.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/Status.java index 5b7c73b472..909a745782 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/Status.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/Status.java @@ -70,7 +70,10 @@ public class Status { private final boolean hasUncommittedChanges; /** + * Constructor for Status. + * * @param diff + * the {@link org.eclipse.jgit.lib.IndexDiff} having the status */ public Status(IndexDiff diff) { super(); @@ -86,16 +89,20 @@ public class Status { } /** - * @return true if no differences exist between the working-tree, the index, - * and the current HEAD, false if differences do exist + * Whether the status is clean + * + * @return {@code true} if no differences exist between the working-tree, + * the index, and the current HEAD, {@code false} if differences do + * exist */ public boolean isClean() { return clean; } /** - * @return true if any tracked file is changed + * Whether there are uncommitted changes * + * @return {@code true} if any tracked file is changed * @since 3.2 */ public boolean hasUncommittedChanges() { @@ -103,14 +110,18 @@ public class Status { } /** + * Get files added to the index + * * @return list of files added to the index, not in HEAD (e.g. what you get - * if you call 'git add ...' on a newly created file) + * if you call {@code git add ...} on a newly created file) */ public Set<String> getAdded() { return Collections.unmodifiableSet(diff.getAdded()); } /** + * Get changed files from HEAD to index + * * @return list of files changed from HEAD to index (e.g. what you get if * you modify an existing file and call 'git add ...' on it) */ @@ -119,6 +130,8 @@ public class Status { } /** + * Get removed files + * * @return list of files removed from index, but in HEAD (e.g. what you get * if you call 'git rm ...' on a existing file) */ @@ -127,6 +140,8 @@ public class Status { } /** + * Get missing files + * * @return list of files in index, but not filesystem (e.g. what you get if * you call 'rm ...' on a existing file) */ @@ -135,6 +150,8 @@ public class Status { } /** + * Get modified files relative to the index + * * @return list of files modified on disk relative to the index (e.g. what * you get if you modify an existing file without adding it to the * index) @@ -144,6 +161,8 @@ public class Status { } /** + * Get untracked files + * * @return list of files that are not ignored, and not in the index. (e.g. * what you get if you create a new file without adding it to the * index) @@ -153,6 +172,8 @@ public class Status { } /** + * Get untracked folders + * * @return set of directories that are not ignored, and not in the index. */ public Set<String> getUntrackedFolders() { @@ -160,6 +181,8 @@ public class Status { } /** + * Get conflicting files + * * @return list of files that are in conflict. (e.g what you get if you * modify file that was modified by someone else in the meantime) */ @@ -168,7 +191,10 @@ public class Status { } /** - * @return a map from conflicting path to its {@link StageState}. + * Get StageState of conflicting files + * + * @return a map from conflicting path to its + * {@link org.eclipse.jgit.lib.IndexDiff.StageState}. * @since 3.0 */ public Map<String, StageState> getConflictingStageState() { @@ -176,6 +202,8 @@ public class Status { } /** + * Get ignored files which are not in the index + * * @return set of files and folders that are ignored and not in the index. */ public Set<String> getIgnoredNotInIndex() { @@ -183,9 +211,11 @@ public class Status { } /** + * Get uncommitted changes, i.e. all files changed in the index or working + * tree + * * @return set of files and folders that are known to the repo and changed * either in the index or in the working tree. - * * @since 3.2 */ public Set<String> getUncommittedChanges() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/StatusCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/StatusCommand.java index 8f7804a003..98c5520e75 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/StatusCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/StatusCommand.java @@ -64,9 +64,9 @@ import org.eclipse.jgit.treewalk.filter.PathFilterGroup; * to finally execute the command. Each instance of this class should only be * used for one invocation of the command (means: one call to {@link #call()}) * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-status.html" - * >Git documentation about Status</a> + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-status.html" >Git + * documentation about Status</a> */ public class StatusCommand extends GitCommand<Status> { private WorkingTreeIterator workingTreeIt; @@ -76,14 +76,21 @@ public class StatusCommand extends GitCommand<Status> { private IgnoreSubmoduleMode ignoreSubmoduleMode = null; /** + * Constructor for StatusCommand. + * * @param repo + * a {@link org.eclipse.jgit.lib.Repository} object. */ protected StatusCommand(Repository repo) { super(repo); } /** + * Whether to ignore submodules + * * @param mode + * the + * {@link org.eclipse.jgit.submodule.SubmoduleWalk.IgnoreSubmoduleMode} * @return {@code this} * @since 3.6 */ @@ -126,13 +133,12 @@ public class StatusCommand extends GitCommand<Status> { } /** + * {@inheritDoc} + * <p> * Executes the {@code Status} command with all the options and parameters * collected by the setter methods of this class. Each instance of this * class should only be used for one invocation of the command. Don't call * this method twice on an instance. - * - * @return a {@link Status} object telling about each path where working - * tree, index or HEAD differ from each other. */ @Override public Status call() throws GitAPIException, NoWorkTreeException { @@ -157,8 +163,9 @@ public class StatusCommand extends GitCommand<Status> { } /** - * To set the {@link WorkingTreeIterator} which should be used. If this - * method is not called a standard {@link FileTreeIterator} is used. + * To set the {@link org.eclipse.jgit.treewalk.WorkingTreeIterator} which + * should be used. If this method is not called a standard + * {@link org.eclipse.jgit.treewalk.FileTreeIterator} is used. * * @param workingTreeIt * a working tree iterator @@ -170,10 +177,11 @@ public class StatusCommand extends GitCommand<Status> { } /** - * To set the {@link ProgressMonitor} which contains callback methods to - * inform you about the progress of this command. + * To set the {@link org.eclipse.jgit.lib.ProgressMonitor} which contains + * callback methods to inform you about the progress of this command. * * @param progressMonitor + * a {@link org.eclipse.jgit.lib.ProgressMonitor} object. * @return {@code this} * @since 3.1 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleAddCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleAddCommand.java index 0519d454ea..1aa050f560 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleAddCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleAddCommand.java @@ -69,8 +69,8 @@ import org.eclipse.jgit.treewalk.filter.TreeFilter; * .gitmodules file and the repository config file, and also add the submodule * and .gitmodules file to the index. * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-submodule.html" + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-submodule.html" * >Git documentation about submodules</a> */ public class SubmoduleAddCommand extends @@ -83,7 +83,10 @@ public class SubmoduleAddCommand extends private ProgressMonitor monitor; /** + * Constructor for SubmoduleAddCommand. + * * @param repo + * a {@link org.eclipse.jgit.lib.Repository} object. */ public SubmoduleAddCommand(final Repository repo) { super(repo); @@ -105,6 +108,7 @@ public class SubmoduleAddCommand extends * Set URI to clone submodule from * * @param uri + * a {@link java.lang.String} object. * @return this command */ public SubmoduleAddCommand setURI(final String uri) { @@ -118,6 +122,7 @@ public class SubmoduleAddCommand extends * * @see NullProgressMonitor * @param monitor + * a {@link org.eclipse.jgit.lib.ProgressMonitor} object. * @return this command */ public SubmoduleAddCommand setProgressMonitor(final ProgressMonitor monitor) { @@ -129,7 +134,7 @@ public class SubmoduleAddCommand extends * Is the configured already a submodule in the index? * * @return true if submodule exists in index, false otherwise - * @throws IOException + * @throws java.io.IOException */ protected boolean submoduleExists() throws IOException { TreeFilter filter = PathFilter.create(path); @@ -139,15 +144,14 @@ public class SubmoduleAddCommand extends } /** + * {@inheritDoc} + * <p> * Executes the {@code SubmoduleAddCommand} * * The {@code Repository} instance returned by this command needs to be * closed by the caller to free resources held by the {@code Repository} * instance. It is recommended to call this method as soon as you don't need * a reference to this {@code Repository} instance anymore. - * - * @return the newly created {@link Repository} - * @throws GitAPIException */ @Override public Repository call() throws GitAPIException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleDeinitCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleDeinitCommand.java new file mode 100644 index 0000000000..569a8e3596 --- /dev/null +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleDeinitCommand.java @@ -0,0 +1,319 @@ +/* + * Copyright (C) 2017, Two Sigma Open Source + * and other copyright owners as documented in the project's IP log. + * + * This program and the accompanying materials are made available + * under the terms of the Eclipse Distribution License v1.0 which + * accompanies this distribution, is reproduced below, and is + * available at http://www.eclipse.org/org/documents/edl-v10.php + * + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or + * without modification, are permitted provided that the following + * conditions are met: + * + * - Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * - Redistributions in binary form must reproduce the above + * copyright notice, this list of conditions and the following + * disclaimer in the documentation and/or other materials provided + * with the distribution. + * + * - Neither the name of the Eclipse Foundation, Inc. nor the + * names of its contributors may be used to endorse or promote + * products derived from this software without specific prior + * written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND + * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, + * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER + * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF + * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ +package org.eclipse.jgit.api; + +import static org.eclipse.jgit.util.FileUtils.RECURSIVE; + +import java.io.File; +import java.io.IOException; +import java.text.MessageFormat; +import java.util.ArrayList; +import java.util.Collection; +import java.util.Collections; +import java.util.List; + +import org.eclipse.jgit.api.errors.GitAPIException; +import org.eclipse.jgit.api.errors.JGitInternalException; +import org.eclipse.jgit.api.errors.NoHeadException; +import org.eclipse.jgit.internal.JGitText; +import org.eclipse.jgit.lib.ConfigConstants; +import org.eclipse.jgit.lib.ObjectId; +import org.eclipse.jgit.lib.Ref; +import org.eclipse.jgit.lib.Repository; +import org.eclipse.jgit.lib.StoredConfig; +import org.eclipse.jgit.revwalk.RevCommit; +import org.eclipse.jgit.revwalk.RevTree; +import org.eclipse.jgit.revwalk.RevWalk; +import org.eclipse.jgit.submodule.SubmoduleWalk; +import org.eclipse.jgit.treewalk.filter.PathFilter; +import org.eclipse.jgit.treewalk.filter.PathFilterGroup; +import org.eclipse.jgit.treewalk.filter.TreeFilter; +import org.eclipse.jgit.util.FileUtils; + +/** + * A class used to execute a submodule deinit command. + * <p> + * This will remove the module(s) from the working tree, but won't affect + * .git/modules. + * + * @since 4.10 + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-submodule.html" + * >Git documentation about submodules</a> + */ +public class SubmoduleDeinitCommand + extends GitCommand<Collection<SubmoduleDeinitResult>> { + + private final Collection<String> paths; + + private boolean force; + + /** + * Constructor of SubmoduleDeinitCommand + * + * @param repo + */ + public SubmoduleDeinitCommand(Repository repo) { + super(repo); + paths = new ArrayList<>(); + } + + /** + * {@inheritDoc} + * <p> + * + * @return the set of repositories successfully deinitialized. + * @throws NoSuchSubmoduleException + * if any of the submodules which we might want to deinitialize + * don't exist + */ + @Override + public Collection<SubmoduleDeinitResult> call() throws GitAPIException { + checkCallable(); + try { + if (paths.isEmpty()) { + return Collections.emptyList(); + } + for (String path : paths) { + if (!submoduleExists(path)) { + throw new NoSuchSubmoduleException(path); + } + } + List<SubmoduleDeinitResult> results = new ArrayList<>(paths.size()); + try (RevWalk revWalk = new RevWalk(repo); + SubmoduleWalk generator = SubmoduleWalk.forIndex(repo)) { + generator.setFilter(PathFilterGroup.createFromStrings(paths)); + StoredConfig config = repo.getConfig(); + while (generator.next()) { + String path = generator.getPath(); + String name = generator.getModuleName(); + SubmoduleDeinitStatus status = checkDirty(revWalk, path); + switch (status) { + case SUCCESS: + deinit(path); + break; + case ALREADY_DEINITIALIZED: + break; + case DIRTY: + if (force) { + deinit(path); + status = SubmoduleDeinitStatus.FORCED; + } + break; + default: + throw new JGitInternalException(MessageFormat.format( + JGitText.get().unexpectedSubmoduleStatus, + status)); + } + + config.unsetSection( + ConfigConstants.CONFIG_SUBMODULE_SECTION, name); + results.add(new SubmoduleDeinitResult(path, status)); + } + } + return results; + } catch (IOException e) { + throw new JGitInternalException(e.getMessage(), e); + } + } + + /** + * Recursively delete the *contents* of path, but leave path as an empty + * directory + * + * @param path + * the path to clean + * @throws IOException + */ + private void deinit(String path) throws IOException { + File dir = new File(repo.getWorkTree(), path); + if (!dir.isDirectory()) { + throw new JGitInternalException(MessageFormat.format( + JGitText.get().expectedDirectoryNotSubmodule, path)); + } + final File[] ls = dir.listFiles(); + if (ls != null) { + for (int i = 0; i < ls.length; i++) { + FileUtils.delete(ls[i], RECURSIVE); + } + } + } + + /** + * Check if a submodule is dirty. A submodule is dirty if there are local + * changes to the submodule relative to its HEAD, including untracked files. + * It is also dirty if the HEAD of the submodule does not match the value in + * the parent repo's index or HEAD. + * + * @param revWalk + * @param path + * @return status of the command + * @throws GitAPIException + * @throws IOException + */ + private SubmoduleDeinitStatus checkDirty(RevWalk revWalk, String path) + throws GitAPIException, IOException { + Ref head = repo.exactRef("HEAD"); //$NON-NLS-1$ + if (head == null) { + throw new NoHeadException( + JGitText.get().invalidRepositoryStateNoHead); + } + RevCommit headCommit = revWalk.parseCommit(head.getObjectId()); + RevTree tree = headCommit.getTree(); + + ObjectId submoduleHead; + try (SubmoduleWalk w = SubmoduleWalk.forPath(repo, tree, path)) { + submoduleHead = w.getHead(); + if (submoduleHead == null) { + // The submodule is not checked out. + return SubmoduleDeinitStatus.ALREADY_DEINITIALIZED; + } + if (!submoduleHead.equals(w.getObjectId())) { + // The submodule's current HEAD doesn't match the value in the + // outer repo's HEAD. + return SubmoduleDeinitStatus.DIRTY; + } + } + + try (SubmoduleWalk w = SubmoduleWalk.forIndex(repo)) { + if (!w.next()) { + // The submodule does not exist in the index (shouldn't happen + // since we check this earlier) + return SubmoduleDeinitStatus.DIRTY; + } + if (!submoduleHead.equals(w.getObjectId())) { + // The submodule's current HEAD doesn't match the value in the + // outer repo's index. + return SubmoduleDeinitStatus.DIRTY; + } + + Repository submoduleRepo = w.getRepository(); + + Status status = Git.wrap(submoduleRepo).status().call(); + return status.isClean() ? SubmoduleDeinitStatus.SUCCESS + : SubmoduleDeinitStatus.DIRTY; + } + } + + /** + * Check if this path is a submodule by checking the index, which is what + * git submodule deinit checks. + * + * @param path + * path of the submodule + * + * @return {@code true} if path exists and is a submodule in index, + * {@code false} otherwise + * @throws IOException + */ + private boolean submoduleExists(String path) throws IOException { + TreeFilter filter = PathFilter.create(path); + try (SubmoduleWalk w = SubmoduleWalk.forIndex(repo)) { + return w.setFilter(filter).next(); + } + } + + /** + * Add repository-relative submodule path to deinitialize + * + * @param path + * (with <code>/</code> as separator) + * @return this command + */ + public SubmoduleDeinitCommand addPath(String path) { + paths.add(path); + return this; + } + + /** + * If {@code true}, call() will deinitialize modules with local changes; + * else it will refuse to do so. + * + * @param force + * @return {@code this} + */ + public SubmoduleDeinitCommand setForce(boolean force) { + this.force = force; + return this; + } + + /** + * The user tried to deinitialize a submodule that doesn't exist in the + * index. + */ + public static class NoSuchSubmoduleException extends GitAPIException { + private static final long serialVersionUID = 1L; + + /** + * Constructor of NoSuchSubmoduleException + * + * @param path + * path of non-existing submodule + */ + public NoSuchSubmoduleException(String path) { + super(MessageFormat.format(JGitText.get().noSuchSubmodule, path)); + } + } + + /** + * The effect of a submodule deinit command for a given path + */ + public enum SubmoduleDeinitStatus { + /** + * The submodule was not initialized in the first place + */ + ALREADY_DEINITIALIZED, + /** + * The submodule was deinitialized + */ + SUCCESS, + /** + * The submodule had local changes, but was deinitialized successfully + */ + FORCED, + /** + * The submodule had local changes and force was false + */ + DIRTY, + } +} diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleDeinitResult.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleDeinitResult.java new file mode 100644 index 0000000000..5a9cbc1025 --- /dev/null +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleDeinitResult.java @@ -0,0 +1,105 @@ +/* + * Copyright (C) 2017, Two Sigma Open Source + * and other copyright owners as documented in the project's IP log. + * + * This program and the accompanying materials are made available + * under the terms of the Eclipse Distribution License v1.0 which + * accompanies this distribution, is reproduced below, and is + * available at http://www.eclipse.org/org/documents/edl-v10.php + * + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or + * without modification, are permitted provided that the following + * conditions are met: + * + * - Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * - Redistributions in binary form must reproduce the above + * copyright notice, this list of conditions and the following + * disclaimer in the documentation and/or other materials provided + * with the distribution. + * + * - Neither the name of the Eclipse Foundation, Inc. nor the + * names of its contributors may be used to endorse or promote + * products derived from this software without specific prior + * written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND + * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, + * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER + * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF + * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ +package org.eclipse.jgit.api; + +/** + * The result of a submodule deinit command for a particular path + * + * @since 4.10 + */ +public class SubmoduleDeinitResult { + private String path; + + private SubmoduleDeinitCommand.SubmoduleDeinitStatus status; + + /** + * Constructor for SubmoduleDeinitResult + * + * @param path + * path of the submodule + * @param status + */ + public SubmoduleDeinitResult(String path, + SubmoduleDeinitCommand.SubmoduleDeinitStatus status) { + this.path = path; + this.status = status; + } + + /** + * Get the path of the submodule + * + * @return path of the submodule + */ + public String getPath() { + return path; + } + + /** + * Set the path of the submodule + * + * @param path + * path of the submodule + */ + public void setPath(String path) { + this.path = path; + } + + /** + * Get the status of the command + * + * @return the status of the command + */ + public SubmoduleDeinitCommand.SubmoduleDeinitStatus getStatus() { + return status; + } + + /** + * Set the status of the command + * + * @param status + * the status of the command + */ + public void setStatus(SubmoduleDeinitCommand.SubmoduleDeinitStatus status) { + this.status = status; + } +} diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleInitCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleInitCommand.java index 4c5e317cb1..6af27d704c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleInitCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleInitCommand.java @@ -63,8 +63,8 @@ import org.eclipse.jgit.treewalk.filter.PathFilterGroup; * .gitmodules file to a repository's config file for each submodule not * currently present in the repository's config file. * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-submodule.html" + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-submodule.html" * >Git documentation about submodules</a> */ public class SubmoduleInitCommand extends GitCommand<Collection<String>> { @@ -72,7 +72,10 @@ public class SubmoduleInitCommand extends GitCommand<Collection<String>> { private final Collection<String> paths; /** + * Constructor for SubmoduleInitCommand. + * * @param repo + * a {@link org.eclipse.jgit.lib.Repository} object. */ public SubmoduleInitCommand(final Repository repo) { super(repo); @@ -91,6 +94,7 @@ public class SubmoduleInitCommand extends GitCommand<Collection<String>> { return this; } + /** {@inheritDoc} */ @Override public Collection<String> call() throws GitAPIException { checkCallable(); @@ -106,16 +110,17 @@ public class SubmoduleInitCommand extends GitCommand<Collection<String>> { continue; String path = generator.getPath(); + String name = generator.getModuleName(); // Copy 'url' and 'update' fields from .gitmodules to config // file String url = generator.getRemoteUrl(); String update = generator.getModulesUpdate(); if (url != null) config.setString(ConfigConstants.CONFIG_SUBMODULE_SECTION, - path, ConfigConstants.CONFIG_KEY_URL, url); + name, ConfigConstants.CONFIG_KEY_URL, url); if (update != null) config.setString(ConfigConstants.CONFIG_SUBMODULE_SECTION, - path, ConfigConstants.CONFIG_KEY_UPDATE, update); + name, ConfigConstants.CONFIG_KEY_UPDATE, update); if (url != null || update != null) initialized.add(path); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleStatusCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleStatusCommand.java index 8b27e4c41f..97ae668078 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleStatusCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleStatusCommand.java @@ -62,8 +62,8 @@ import org.eclipse.jgit.treewalk.filter.PathFilterGroup; /** * A class used to execute a submodule status command. * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-submodule.html" + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-submodule.html" * >Git documentation about submodules</a> */ public class SubmoduleStatusCommand extends @@ -72,7 +72,10 @@ public class SubmoduleStatusCommand extends private final Collection<String> paths; /** + * Constructor for SubmoduleStatusCommand. + * * @param repo + * a {@link org.eclipse.jgit.lib.Repository} object. */ public SubmoduleStatusCommand(final Repository repo) { super(repo); @@ -91,6 +94,7 @@ public class SubmoduleStatusCommand extends return this; } + /** {@inheritDoc} */ @Override public Map<String, SubmoduleStatus> call() throws GitAPIException { checkCallable(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleSyncCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleSyncCommand.java index b5c0b1564f..d22d820c32 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleSyncCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleSyncCommand.java @@ -65,8 +65,8 @@ import org.eclipse.jgit.treewalk.filter.PathFilterGroup; * This will set the remote URL in a submodule's repository to the current value * in the .gitmodules file. * - * @see <a - * href="http://www.kernel.org/pub/software/scm/git/docs/git-submodule.html" + * @see <a href= + * "http://www.kernel.org/pub/software/scm/git/docs/git-submodule.html" * >Git documentation about submodules</a> */ public class SubmoduleSyncCommand extends GitCommand<Map<String, String>> { @@ -74,7 +74,10 @@ public class SubmoduleSyncCommand extends GitCommand<Map<String, String>> { private final Collection<String> paths; /** + * Constructor for SubmoduleSyncCommand. + * * @param repo + * a {@link org.eclipse.jgit.lib.Repository} object. */ public SubmoduleSyncCommand(final Repository repo) { super(repo); @@ -97,8 +100,9 @@ public class SubmoduleSyncCommand extends GitCommand<Map<String, String>> { * Get branch that HEAD currently points to * * @param subRepo + * a {@link org.eclipse.jgit.lib.Repository} object. * @return shortened branch name, null on failures - * @throws IOException + * @throws java.io.IOException */ protected String getHeadBranch(final Repository subRepo) throws IOException { Ref head = subRepo.exactRef(Constants.HEAD); @@ -108,6 +112,7 @@ public class SubmoduleSyncCommand extends GitCommand<Map<String, String>> { return null; } + /** {@inheritDoc} */ @Override public Map<String, String> call() throws GitAPIException { checkCallable(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleUpdateCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleUpdateCommand.java index 4faaac2dbc..4b4e18c134 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleUpdateCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/SubmoduleUpdateCommand.java @@ -96,7 +96,12 @@ public class SubmoduleUpdateCommand extends private boolean fetch = false; /** + * <p> + * Constructor for SubmoduleUpdateCommand. + * </p> + * * @param repo + * a {@link org.eclipse.jgit.lib.Repository} object. */ public SubmoduleUpdateCommand(final Repository repo) { super(repo); @@ -109,6 +114,7 @@ public class SubmoduleUpdateCommand extends * * @see NullProgressMonitor * @param monitor + * a {@link org.eclipse.jgit.lib.ProgressMonitor} object. * @return this command */ public SubmoduleUpdateCommand setProgressMonitor( @@ -122,6 +128,7 @@ public class SubmoduleUpdateCommand extends * is set to <code>false</code> * * @param fetch + * whether to fetch the submodules before we update them * @return this command * @since 4.9 */ @@ -143,18 +150,9 @@ public class SubmoduleUpdateCommand extends } /** - * Execute the SubmoduleUpdateCommand command. + * {@inheritDoc} * - * @return a collection of updated submodule paths - * @throws ConcurrentRefUpdateException - * @throws CheckoutConflictException - * @throws InvalidMergeHeadsException - * @throws InvalidConfigurationException - * @throws NoHeadException - * @throws NoMessageException - * @throws RefNotFoundException - * @throws WrongRepositoryStateException - * @throws GitAPIException + * Execute the SubmoduleUpdateCommand command. */ @Override public Collection<String> call() throws InvalidConfigurationException, @@ -252,6 +250,8 @@ public class SubmoduleUpdateCommand extends } /** + * Setter for the field <code>strategy</code>. + * * @param strategy * The merge strategy to use during this update operation. * @return {@code this} diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/TagCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/TagCommand.java index bdbb8620d6..c29b753fc5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/TagCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/TagCommand.java @@ -68,7 +68,7 @@ import org.eclipse.jgit.revwalk.RevWalk; /** * Create/update an annotated tag object or a simple unannotated tag * <p> - * Examples (<code>git</code> is a {@link Git} instance): + * Examples (<code>git</code> is a {@link org.eclipse.jgit.api.Git} instance): * <p> * Create a new tag for the current commit: * @@ -104,21 +104,22 @@ public class TagCommand extends GitCommand<Ref> { private boolean annotated = true; /** - * @param repo + * <p>Constructor for TagCommand.</p> + * + * @param repo a {@link org.eclipse.jgit.lib.Repository} object. */ protected TagCommand(Repository repo) { super(repo); } /** + * {@inheritDoc} + * <p> * Executes the {@code tag} command with all the options and parameters * collected by the setter methods of this class. Each instance of this * class should only be used for one invocation of the command (means: one * call to {@link #call()}) * - * @return a {@link Ref} a ref pointing to a tag - * @throws NoHeadException - * when called on a git repo without a HEAD reference * @since 2.0 */ @Override @@ -226,6 +227,8 @@ public class TagCommand extends GitCommand<Ref> { } /** + * Set the tag <code>name</code>. + * * @param name * the tag name used for the {@code tag} * @return {@code this} @@ -237,6 +240,8 @@ public class TagCommand extends GitCommand<Ref> { } /** + * Get the tag <code>name</code>. + * * @return the tag name used for the <code>tag</code> */ public String getName() { @@ -244,6 +249,8 @@ public class TagCommand extends GitCommand<Ref> { } /** + * Get the tag <code>message</code>. + * * @return the tag message used for the <code>tag</code> */ public String getMessage() { @@ -251,6 +258,8 @@ public class TagCommand extends GitCommand<Ref> { } /** + * Set the tag <code>message</code>. + * * @param message * the tag message used for the {@code tag} * @return {@code this} @@ -262,6 +271,8 @@ public class TagCommand extends GitCommand<Ref> { } /** + * Whether this tag is signed + * * @return whether the tag is signed */ public boolean isSigned() { @@ -273,6 +284,7 @@ public class TagCommand extends GitCommand<Ref> { * corresponds to the parameter -s on the command line. * * @param signed + * a boolean. * @return {@code this} */ public TagCommand setSigned(boolean signed) { @@ -285,6 +297,7 @@ public class TagCommand extends GitCommand<Ref> { * created from the info in the repository. * * @param tagger + * a {@link org.eclipse.jgit.lib.PersonIdent} object. * @return {@code this} */ public TagCommand setTagger(PersonIdent tagger) { @@ -293,6 +306,8 @@ public class TagCommand extends GitCommand<Ref> { } /** + * Get the <code>tagger</code> who created the tag. + * * @return the tagger of the tag */ public PersonIdent getTagger() { @@ -300,6 +315,8 @@ public class TagCommand extends GitCommand<Ref> { } /** + * Get the tag's object id + * * @return the object id of the tag */ public RevObject getObjectId() { @@ -311,6 +328,7 @@ public class TagCommand extends GitCommand<Ref> { * pointed to from HEAD will be used. * * @param id + * a {@link org.eclipse.jgit.revwalk.RevObject} object. * @return {@code this} */ public TagCommand setObjectId(RevObject id) { @@ -319,6 +337,8 @@ public class TagCommand extends GitCommand<Ref> { } /** + * Whether this is a forced update + * * @return is this a force update */ public boolean isForceUpdate() { @@ -330,6 +350,7 @@ public class TagCommand extends GitCommand<Ref> { * corresponds to the parameter -f on the command line. * * @param forceUpdate + * whether this is a forced update * @return {@code this} */ public TagCommand setForceUpdate(boolean forceUpdate) { @@ -338,7 +359,10 @@ public class TagCommand extends GitCommand<Ref> { } /** + * Configure this tag to be created as an annotated tag + * * @param annotated + * whether this shall be an annotated tag * @return {@code this} * @since 3.0 */ @@ -348,6 +372,8 @@ public class TagCommand extends GitCommand<Ref> { } /** + * Whether this will create an annotated command + * * @return true if this command will create an annotated tag (default is * true) * @since 3.0 diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/TransportCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/TransportCommand.java index 1541df5d39..9c915377d0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/TransportCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/TransportCommand.java @@ -47,11 +47,12 @@ import org.eclipse.jgit.transport.CredentialsProvider; import org.eclipse.jgit.transport.Transport; /** - * Base class for commands that use a {@link Transport} during execution. + * Base class for commands that use a + * {@link org.eclipse.jgit.transport.Transport} during execution. * <p> * This class provides standard configuration of a transport for options such as - * a {@link CredentialsProvider}, a timeout, and a - * {@link TransportConfigCallback}. + * a {@link org.eclipse.jgit.transport.CredentialsProvider}, a timeout, and a + * {@link org.eclipse.jgit.api.TransportConfigCallback}. * * @param <C> * @param <T> @@ -75,7 +76,9 @@ public abstract class TransportCommand<C extends GitCommand, T> extends protected TransportConfigCallback transportConfigCallback; /** - * @param repo + * <p>Constructor for TransportCommand.</p> + * + * @param repo a {@link org.eclipse.jgit.lib.Repository} object. */ protected TransportCommand(final Repository repo) { super(repo); @@ -83,8 +86,11 @@ public abstract class TransportCommand<C extends GitCommand, T> extends } /** + * Set the <code>credentialsProvider</code>. + * * @param credentialsProvider - * the {@link CredentialsProvider} to use + * the {@link org.eclipse.jgit.transport.CredentialsProvider} to + * use * @return {@code this} */ public C setCredentialsProvider( @@ -94,6 +100,8 @@ public abstract class TransportCommand<C extends GitCommand, T> extends } /** + * Set <code>timeout</code>. + * * @param timeout * the timeout (in seconds) used for the transport step * @return {@code this} @@ -104,12 +112,15 @@ public abstract class TransportCommand<C extends GitCommand, T> extends } /** + * Set the <code>TransportConfigCallback</code>. + * * @param transportConfigCallback * if set, the callback will be invoked after the - * {@link Transport} has created, but before the - * {@link Transport} is used. The callback can use this - * opportunity to set additional type-specific configuration on - * the {@link Transport} instance. + * {@link org.eclipse.jgit.transport.Transport} has created, but + * before the {@link org.eclipse.jgit.transport.Transport} is + * used. The callback can use this opportunity to set additional + * type-specific configuration on the + * {@link org.eclipse.jgit.transport.Transport} instance. * @return {@code this} */ public C setTransportConfigCallback( @@ -118,7 +129,11 @@ public abstract class TransportCommand<C extends GitCommand, T> extends return self(); } - /** @return {@code this} */ + /** + * Return this command cast to {@code C} + * + * @return {@code this} cast to {@code C} + */ @SuppressWarnings("unchecked") protected final C self() { return (C) this; @@ -129,6 +144,7 @@ public abstract class TransportCommand<C extends GitCommand, T> extends * callback * * @param transport + * a {@link org.eclipse.jgit.transport.Transport} object. * @return {@code this} */ protected C configure(final Transport transport) { @@ -145,6 +161,7 @@ public abstract class TransportCommand<C extends GitCommand, T> extends * {@code this} command * * @param childCommand + * a {@link org.eclipse.jgit.api.TransportCommand} object. * @return {@code this} */ protected C configure(final TransportCommand childCommand) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/TransportConfigCallback.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/TransportConfigCallback.java index 4faadbadd7..f60926c562 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/TransportConfigCallback.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/TransportConfigCallback.java @@ -64,7 +64,9 @@ public interface TransportConfigCallback { /** * Add any additional transport-specific configuration required. + * * @param transport + * a {@link org.eclipse.jgit.transport.Transport} object. */ public void configure(Transport transport); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/AbortedByHookException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/AbortedByHookException.java index 995611ef0a..db6440b55f 100755 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/AbortedByHookException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/AbortedByHookException.java @@ -67,6 +67,8 @@ public class AbortedByHookException extends GitAPIException { private final int returnCode; /** + * Constructor for AbortedByHookException + * * @param message * The error details. * @param hookName @@ -83,6 +85,8 @@ public class AbortedByHookException extends GitAPIException { } /** + * Get hook name + * * @return the type of the hook that interrupted the git command. */ public String getHookName() { @@ -90,12 +94,15 @@ public class AbortedByHookException extends GitAPIException { } /** + * Get return code + * * @return the hook process result. */ public int getReturnCode() { return returnCode; } + /** {@inheritDoc} */ @Override public String getMessage() { return MessageFormat.format(JGitText.get().commandRejectedByHook, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/CanceledException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/CanceledException.java index 3ad2597831..5f831e420c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/CanceledException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/CanceledException.java @@ -45,7 +45,9 @@ public class CanceledException extends GitAPIException { private static final long serialVersionUID = 1L; /** - * @param message + * <p>Constructor for CanceledException.</p> + * + * @param message a {@link java.lang.String} object. */ public CanceledException(String message) { super(message); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/CannotDeleteCurrentBranchException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/CannotDeleteCurrentBranchException.java index 76d773229d..65e05a1737 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/CannotDeleteCurrentBranchException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/CannotDeleteCurrentBranchException.java @@ -44,8 +44,10 @@ public class CannotDeleteCurrentBranchException extends GitAPIException { private static final long serialVersionUID = 1L; /** + * Constructor for CannotDeleteCurrentBranchException + * * @param message - * the message + * error message */ public CannotDeleteCurrentBranchException(String message) { super(message); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/CheckoutConflictException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/CheckoutConflictException.java index 7df35c925c..3b71373b6e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/CheckoutConflictException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/CheckoutConflictException.java @@ -53,7 +53,6 @@ public class CheckoutConflictException extends GitAPIException { * * @param conflictingPaths * list of conflicting paths - * * @param e * a {@link org.eclipse.jgit.errors.CheckoutConflictException} * exception @@ -82,7 +81,11 @@ public class CheckoutConflictException extends GitAPIException { this.conflictingPaths = conflictingPaths; } - /** @return all the paths where unresolved conflicts have been detected */ + /** + * Get conflicting paths + * + * @return all the paths where unresolved conflicts have been detected + */ public List<String> getConflictingPaths() { return conflictingPaths; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/ConcurrentRefUpdateException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/ConcurrentRefUpdateException.java index b5e87f1f5c..514d65e158 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/ConcurrentRefUpdateException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/ConcurrentRefUpdateException.java @@ -55,10 +55,16 @@ public class ConcurrentRefUpdateException extends GitAPIException { private Ref ref; /** + * Constructor for ConcurrentRefUpdateException. + * * @param message + * error message * @param ref + * a {@link org.eclipse.jgit.lib.Ref} * @param rc + * a {@link org.eclipse.jgit.lib.RefUpdate.Result} * @param cause + * a {@link java.lang.Throwable} */ public ConcurrentRefUpdateException(String message, Ref ref, RefUpdate.Result rc, Throwable cause) { @@ -69,9 +75,14 @@ public class ConcurrentRefUpdateException extends GitAPIException { } /** + * Constructor for ConcurrentRefUpdateException. + * * @param message + * error message * @param ref + * a {@link org.eclipse.jgit.lib.Ref} * @param rc + * a {@link org.eclipse.jgit.lib.RefUpdate.Result} */ public ConcurrentRefUpdateException(String message, Ref ref, RefUpdate.Result rc) { @@ -82,15 +93,21 @@ public class ConcurrentRefUpdateException extends GitAPIException { } /** - * @return the {@link Ref} which was tried to by updated + * Get <code>Ref</code> + * + * @return the {@link org.eclipse.jgit.lib.Ref} which was tried to by + * updated */ public Ref getRef() { return ref; } /** - * @return the result which was returned by {@link RefUpdate#update()} and - * which caused this error + * Get result + * + * @return the result which was returned by + * {@link org.eclipse.jgit.lib.RefUpdate#update()} and which caused + * this error */ public RefUpdate.Result getResult() { return rc; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/DetachedHeadException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/DetachedHeadException.java index 01b1f3147c..30b585318c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/DetachedHeadException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/DetachedHeadException.java @@ -55,15 +55,22 @@ public class DetachedHeadException extends GitAPIException { } /** + * Constructor for DetachedHeadException. + * * @param message + * error message * @param cause + * a {@link java.lang.Throwable} object. */ public DetachedHeadException(String message, Throwable cause) { super(message, cause); } /** + * Constructor for DetachedHeadException. + * * @param message + * error message */ public DetachedHeadException(String message) { super(message); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/EmtpyCommitException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/EmtpyCommitException.java index b3cc1bfcf2..ea0e7183c6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/EmtpyCommitException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/EmtpyCommitException.java @@ -42,19 +42,26 @@ package org.eclipse.jgit.api.errors; * * @since 4.2 */ -public class EmtpyCommitException extends GitAPIException { +public class EmtpyCommitException extends GitAPIException { // TODO: Correct spelling of this class name in 5.0 private static final long serialVersionUID = 1L; /** + * Constructor for EmtpyCommitException + * * @param message + * error message * @param cause + * a {@link java.lang.Throwable} */ public EmtpyCommitException(String message, Throwable cause) { super(message, cause); } /** + * Constructor for EmtpyCommitException. + * * @param message + * error message */ public EmtpyCommitException(String message) { super(message); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/FilterFailedException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/FilterFailedException.java index fbc30ef162..f07e79f6a0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/FilterFailedException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/FilterFailedException.java @@ -106,6 +106,8 @@ public class FilterFailedException extends GitAPIException { } /** + * Get filter command + * * @return the filterCommand */ public String getFilterCommand() { @@ -113,6 +115,8 @@ public class FilterFailedException extends GitAPIException { } /** + * Get path + * * @return the path of the file processed by the filter command */ public String getPath() { @@ -120,6 +124,8 @@ public class FilterFailedException extends GitAPIException { } /** + * Get output + * * @return the output generated by the filter command. Might be truncated to * limit memory consumption. */ @@ -128,6 +134,8 @@ public class FilterFailedException extends GitAPIException { } /** + * Get error + * * @return the error output returned by the filter command */ public String getError() { @@ -135,6 +143,8 @@ public class FilterFailedException extends GitAPIException { } /** + * Get return code + * * @return the return code returned by the filter command */ public int getReturnCode() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/GitAPIException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/GitAPIException.java index b251c7ddf2..a2d6996f87 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/GitAPIException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/GitAPIException.java @@ -40,7 +40,6 @@ package org.eclipse.jgit.api.errors; /** * Superclass of all exceptions thrown by the API classes in * {@code org.eclipse.jgit.api} - * */ public abstract class GitAPIException extends Exception { private static final long serialVersionUID = 1L; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidConfigurationException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidConfigurationException.java index cb89e469b5..e99bfb1604 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidConfigurationException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidConfigurationException.java @@ -45,15 +45,22 @@ public class InvalidConfigurationException extends GitAPIException { private static final long serialVersionUID = 1L; /** + * Constructor for InvalidConfigurationException + * * @param message + * error message * @param cause + * a {@link java.lang.Throwable} */ public InvalidConfigurationException(String message, Throwable cause) { super(message, cause); } /** + * Constructor for InvalidConfigurationException. + * * @param message + * error message */ public InvalidConfigurationException(String message) { super(message); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidMergeHeadsException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidMergeHeadsException.java index c8edb5720f..9fbdce5b5e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidMergeHeadsException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidMergeHeadsException.java @@ -47,7 +47,10 @@ public class InvalidMergeHeadsException extends GitAPIException { private static final long serialVersionUID = 1L; /** + * Constructor for InvalidMergeHeadsException. + * * @param msg + * error message */ public InvalidMergeHeadsException(String msg) { super(msg); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidRebaseStepException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidRebaseStepException.java index ef89a98c9c..1f03286d9a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidRebaseStepException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidRebaseStepException.java @@ -45,16 +45,24 @@ package org.eclipse.jgit.api.errors; */ public class InvalidRebaseStepException extends GitAPIException { private static final long serialVersionUID = 1L; + /** + * Constructor for InvalidRebaseStepException. + * * @param msg + * error message */ public InvalidRebaseStepException(String msg) { super(msg); } /** + * Constructor for InvalidRebaseStepException. + * * @param msg + * error message * @param cause + * a {@link java.lang.Throwable} */ public InvalidRebaseStepException(String msg, Throwable cause) { super(msg, cause); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidRefNameException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidRefNameException.java index 287713c82c..552c1480be 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidRefNameException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidRefNameException.java @@ -44,15 +44,22 @@ public class InvalidRefNameException extends GitAPIException { private static final long serialVersionUID = 1L; /** + * Constructor for InvalidRefNameException + * * @param msg + * error message */ public InvalidRefNameException(String msg) { super(msg); } /** + * Constructor for InvalidRefNameException. + * * @param msg + * error message * @param cause + * a {@link java.lang.Throwable} */ public InvalidRefNameException(String msg, Throwable cause) { super(msg, cause); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidRemoteException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidRemoteException.java index 3f059b79c7..4db5022f46 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidRemoteException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidRemoteException.java @@ -44,15 +44,22 @@ public class InvalidRemoteException extends GitAPIException { private static final long serialVersionUID = 1L; /** - * @param msg message describing the invalid remote. + * Constructor for InvalidRemoteException + * + * @param msg + * message describing the invalid remote. */ public InvalidRemoteException(String msg) { super(msg); } /** - * @param msg message describing the invalid remote. - * @param cause why the remote is invalid. + * Constructor for InvalidRemoteException + * + * @param msg + * message describing the invalid remote. + * @param cause + * why the remote is invalid. */ public InvalidRemoteException(String msg, Throwable cause) { super(msg, cause); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidTagNameException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidTagNameException.java index 1779c45e2c..72ba0c3a4b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidTagNameException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/InvalidTagNameException.java @@ -45,7 +45,10 @@ public class InvalidTagNameException extends GitAPIException { private static final long serialVersionUID = 1L; /** + * Constructor for InvalidTagNameException. + * * @param msg + * error message */ public InvalidTagNameException(String msg) { super(msg); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/JGitInternalException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/JGitInternalException.java index ca562005ff..57d8a13d10 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/JGitInternalException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/JGitInternalException.java @@ -63,7 +63,9 @@ public class JGitInternalException extends RuntimeException { * Construct an exception for low-level internal exceptions * * @param message + * error message * @param cause + * a {@link java.lang.Throwable} */ public JGitInternalException(String message, Throwable cause) { super(message, cause); @@ -73,6 +75,7 @@ public class JGitInternalException extends RuntimeException { * Construct an exception for low-level internal exceptions * * @param message + * error message */ public JGitInternalException(String message) { super(message); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/MultipleParentsNotAllowedException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/MultipleParentsNotAllowedException.java index c71cc049d6..506727283f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/MultipleParentsNotAllowedException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/MultipleParentsNotAllowedException.java @@ -49,15 +49,22 @@ public class MultipleParentsNotAllowedException extends GitAPIException { private static final long serialVersionUID = 1L; /** + * Constructor for MultipleParentsNotAllowedException. + * * @param message + * error message * @param cause + * a {@link java.lang.Throwable} */ public MultipleParentsNotAllowedException(String message, Throwable cause) { super(message, cause); } /** + * Constructor for MultipleParentsNotAllowedException. + * * @param message + * error message */ public MultipleParentsNotAllowedException(String message) { super(message); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/NoFilepatternException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/NoFilepatternException.java index 1130c256f5..893bf65c2d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/NoFilepatternException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/NoFilepatternException.java @@ -48,15 +48,22 @@ public class NoFilepatternException extends GitAPIException { private static final long serialVersionUID = 1L; /** + * Constructor for NoFilepatternException. + * * @param message + * error message * @param cause + * a {@link java.lang.Throwable} */ public NoFilepatternException(String message, Throwable cause) { super(message, cause); } /** + * Constructor for NoFilepatternException. + * * @param message + * error message */ public NoFilepatternException(String message) { super(message); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/NoHeadException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/NoHeadException.java index 50c4dc96b3..43dbc41392 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/NoHeadException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/NoHeadException.java @@ -45,15 +45,22 @@ public class NoHeadException extends GitAPIException { private static final long serialVersionUID = 1L; /** + * Constructor for NoHeadException + * * @param message + * error message * @param cause + * a {@link java.lang.Throwable} */ public NoHeadException(String message, Throwable cause) { super(message, cause); } /** + * Constructor for NoHeadException + * * @param message + * error message */ public NoHeadException(String message) { super(message); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/NoMessageException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/NoMessageException.java index b7d8dc8db3..fa6e791854 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/NoMessageException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/NoMessageException.java @@ -47,15 +47,22 @@ public class NoMessageException extends GitAPIException { private static final long serialVersionUID = 1L; /** + * Constructor for NoMessageException + * * @param message + * error message * @param cause + * a {@link java.lang.Throwable} */ public NoMessageException(String message, Throwable cause) { super(message, cause); } /** + * Constructor for NoMessageException + * * @param message + * error message */ public NoMessageException(String message) { super(message); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/PatchApplyException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/PatchApplyException.java index 4329860cd3..6957dca2ed 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/PatchApplyException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/PatchApplyException.java @@ -46,21 +46,27 @@ package org.eclipse.jgit.api.errors; * Exception thrown when applying a patch fails * * @since 2.0 - * */ public class PatchApplyException extends GitAPIException { private static final long serialVersionUID = 1L; /** + * Constructor for PatchApplyException + * * @param message + * error message * @param cause + * a {@link java.lang.Throwable} */ public PatchApplyException(String message, Throwable cause) { super(message, cause); } /** + * Constructor for PatchApplyException + * * @param message + * error message */ public PatchApplyException(String message) { super(message); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/PatchFormatException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/PatchFormatException.java index 02ab423366..e10b8b436e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/PatchFormatException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/PatchFormatException.java @@ -52,7 +52,6 @@ import org.eclipse.jgit.patch.FormatError; * Exception thrown when applying a patch fails due to an invalid format * * @since 2.0 - * */ public class PatchFormatException extends GitAPIException { private static final long serialVersionUID = 1L; @@ -60,7 +59,10 @@ public class PatchFormatException extends GitAPIException { private List<FormatError> errors; /** + * Constructor for PatchFormatException + * * @param errors + * a {@link java.util.List} of {@link FormatError}s */ public PatchFormatException(List<FormatError> errors) { super(MessageFormat.format(JGitText.get().patchFormatException, errors)); @@ -68,6 +70,8 @@ public class PatchFormatException extends GitAPIException { } /** + * Get list of errors + * * @return all the errors where unresolved conflicts have been detected */ public List<FormatError> getErrors() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/RefAlreadyExistsException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/RefAlreadyExistsException.java index 837028ce32..7e39361eff 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/RefAlreadyExistsException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/RefAlreadyExistsException.java @@ -37,17 +37,18 @@ */ package org.eclipse.jgit.api.errors; -import org.eclipse.jgit.lib.Ref; - /** - * Thrown when trying to create a {@link Ref} with the same name as an existing - * one + * Thrown when trying to create a {@link org.eclipse.jgit.lib.Ref} with the same + * name as an existing one */ public class RefAlreadyExistsException extends GitAPIException { private static final long serialVersionUID = 1L; /** + * Constructor for RefAlreadyExistsException + * * @param message + * error message */ public RefAlreadyExistsException(String message) { super(message); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/RefNotAdvertisedException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/RefNotAdvertisedException.java index 2bd8477659..b52cd58e8d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/RefNotAdvertisedException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/RefNotAdvertisedException.java @@ -46,7 +46,10 @@ public class RefNotAdvertisedException extends GitAPIException { private static final long serialVersionUID = 1L; /** + * Constructor for RefNotAdvertisedException + * * @param message + * error message */ public RefNotAdvertisedException(String message) { super(message); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/RefNotFoundException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/RefNotFoundException.java index b9f2a5617d..406fa45833 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/RefNotFoundException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/RefNotFoundException.java @@ -44,8 +44,12 @@ public class RefNotFoundException extends GitAPIException { private static final long serialVersionUID = 1L; /** + * Constructor for RefNotFoundException + * * @param message + * error message * @param cause + * a {@link java.lang.Throwable} * @since 4.1 */ public RefNotFoundException(String message, Throwable cause) { @@ -53,7 +57,10 @@ public class RefNotFoundException extends GitAPIException { } /** + * Constructor for RefNotFoundException + * * @param message + * error message */ public RefNotFoundException(String message) { super(message); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/StashApplyFailureException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/StashApplyFailureException.java index 222c1db2bb..517b512664 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/StashApplyFailureException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/StashApplyFailureException.java @@ -8,8 +8,12 @@ public class StashApplyFailureException extends GitAPIException { private static final long serialVersionUID = 1L; /** + * Constructor for StashApplyFailureException + * * @param message + * error message * @param cause + * a {@link java.lang.Throwable} * @since 4.1 */ public StashApplyFailureException(String message, Throwable cause) { @@ -20,6 +24,7 @@ public class StashApplyFailureException extends GitAPIException { * Create a StashApplyFailedException * * @param message + * error message */ public StashApplyFailureException(final String message) { super(message); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/TooLargeObjectInPackException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/TooLargeObjectInPackException.java index b841f57f1e..ceaa6b2470 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/TooLargeObjectInPackException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/TooLargeObjectInPackException.java @@ -47,6 +47,8 @@ public class TooLargeObjectInPackException extends TransportException { private static final long serialVersionUID = 1L; /** + * Constructor for TooLargeObjectInPackException + * * @param msg * message describing the transport failure. */ @@ -55,6 +57,8 @@ public class TooLargeObjectInPackException extends TransportException { } /** + * Constructor for TooLargeObjectInPackException + * * @param msg * message describing the transport exception. * @param cause diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/TooLargePackException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/TooLargePackException.java index 3833054da8..462b70118d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/TooLargePackException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/TooLargePackException.java @@ -46,6 +46,8 @@ public class TooLargePackException extends TransportException { private static final long serialVersionUID = 1L; /** + * Constructor for TooLargePackException + * * @param msg * message describing the transport failure. */ @@ -54,6 +56,8 @@ public class TooLargePackException extends TransportException { } /** + * Constructor for TooLargePackException + * * @param msg * message describing the transport exception. * @param cause diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/TransportException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/TransportException.java index 9f0e2fb25d..5569928f30 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/TransportException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/TransportException.java @@ -44,6 +44,8 @@ public class TransportException extends GitAPIException { private static final long serialVersionUID = 1L; /** + * Constructor for TransportException + * * @param msg * message describing the transport failure. */ @@ -52,6 +54,8 @@ public class TransportException extends GitAPIException { } /** + * Constructor for TransportException + * * @param msg * message describing the transport exception. * @param cause diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/UnmergedPathsException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/UnmergedPathsException.java index 082f94c65d..9d6318e424 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/UnmergedPathsException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/UnmergedPathsException.java @@ -63,8 +63,12 @@ public class UnmergedPathsException extends GitAPIException { } /** + * Constructor for UnmergedPathsException + * * @param message + * the message * @param cause + * a {@link java.lang.Throwable} * @since 4.1 */ public UnmergedPathsException(String message, Throwable cause) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/WrongRepositoryStateException.java b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/WrongRepositoryStateException.java index dd2b3998ea..4b5871149e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/WrongRepositoryStateException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/api/errors/WrongRepositoryStateException.java @@ -46,15 +46,22 @@ public class WrongRepositoryStateException extends GitAPIException { private static final long serialVersionUID = 1L; /** + * Constructor for WrongRepositoryStateException. + * * @param message + * error message * @param cause + * a {@link java.lang.Throwable} */ public WrongRepositoryStateException(String message, Throwable cause) { super(message, cause); } /** + * Constructor for WrongRepositoryStateException. + * * @param message + * error message */ public WrongRepositoryStateException(String message) { super(message); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/attributes/Attribute.java b/org.eclipse.jgit/src/org/eclipse/jgit/attributes/Attribute.java index c256b738b5..f1df0da453 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/attributes/Attribute.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/attributes/Attribute.java @@ -47,15 +47,17 @@ package org.eclipse.jgit.attributes; * <p> * According to the man page, an attribute can have the following states: * <ul> - * <li>Set - represented by {@link State#SET}</li> - * <li>Unset - represented by {@link State#UNSET}</li> - * <li>Set to a value - represented by {@link State#CUSTOM}</li> + * <li>Set - represented by + * {@link org.eclipse.jgit.attributes.Attribute.State#SET}</li> + * <li>Unset - represented by + * {@link org.eclipse.jgit.attributes.Attribute.State#UNSET}</li> + * <li>Set to a value - represented by + * {@link org.eclipse.jgit.attributes.Attribute.State#CUSTOM}</li> * <li>Unspecified - used to revert an attribute . This is crucial in order to * mark an attribute as unspecified in the attributes map and thus preventing * following (with lower priority) nodes from setting the attribute to a value * at all</li> * </ul> - * </p> * * @since 3.7 */ @@ -93,10 +95,11 @@ public final class Attribute { * @param key * the attribute key. Should not be <code>null</code>. * @param state - * the attribute state. It should be either {@link State#SET} or - * {@link State#UNSET}. In order to create a custom value - * attribute prefer the use of {@link #Attribute(String, String)} - * constructor. + * the attribute state. It should be either + * {@link org.eclipse.jgit.attributes.Attribute.State#SET} or + * {@link org.eclipse.jgit.attributes.Attribute.State#UNSET}. In + * order to create a custom value attribute prefer the use of + * {@link #Attribute(String, String)} constructor. */ public Attribute(String key, State state) { this(key, state, null); @@ -127,6 +130,7 @@ public final class Attribute { this(key, State.CUSTOM, value); } + /** {@inheritDoc} */ @Override public boolean equals(Object obj) { if (this == obj) @@ -147,6 +151,8 @@ public final class Attribute { } /** + * Get key + * * @return the attribute key (never returns <code>null</code>) */ public String getKey() { @@ -154,7 +160,7 @@ public final class Attribute { } /** - * Returns the state. + * Return the state. * * @return the state (never returns <code>null</code>) */ @@ -163,12 +169,15 @@ public final class Attribute { } /** + * Get value + * * @return the attribute value (may be <code>null</code>) */ public String getValue() { return value; } + /** {@inheritDoc} */ @Override public int hashCode() { final int prime = 31; @@ -179,6 +188,7 @@ public final class Attribute { return result; } + /** {@inheritDoc} */ @Override public String toString() { switch (state) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/attributes/Attributes.java b/org.eclipse.jgit/src/org/eclipse/jgit/attributes/Attributes.java index d3826b3d9c..125ee5961a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/attributes/Attributes.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/attributes/Attributes.java @@ -53,7 +53,6 @@ import org.eclipse.jgit.lib.Constants; /** * Represents a set of attributes for a path - * <p> * * @since 4.2 */ @@ -64,6 +63,7 @@ public final class Attributes { * Creates a new instance * * @param attributes + * a {@link org.eclipse.jgit.attributes.Attribute} */ public Attributes(Attribute... attributes) { if (attributes != null) { @@ -74,6 +74,8 @@ public final class Attributes { } /** + * Whether the set of attributes is empty + * * @return true if the set does not contain any attributes */ public boolean isEmpty() { @@ -81,7 +83,10 @@ public final class Attributes { } /** + * Get the attribute with the given key + * * @param key + * a {@link java.lang.String} object. * @return the attribute or null */ public Attribute get(String key) { @@ -89,6 +94,8 @@ public final class Attributes { } /** + * Get all attributes + * * @return all attributes */ public Collection<Attribute> getAll() { @@ -96,32 +103,42 @@ public final class Attributes { } /** + * Put an attribute + * * @param a + * an {@link org.eclipse.jgit.attributes.Attribute} */ public void put(Attribute a) { map.put(a.getKey(), a); } /** + * Remove attribute with given key + * * @param key + * an attribute name */ public void remove(String key) { map.remove(key); } /** + * Whether there is an attribute with this key + * * @param key - * @return true if the {@link Attributes} contains this key + * key of an attribute + * @return true if the {@link org.eclipse.jgit.attributes.Attributes} + * contains this key */ public boolean containsKey(String key) { return map.containsKey(key); } /** - * Returns the state. + * Return the state. * * @param key - * + * key of an attribute * @return the state (never returns <code>null</code>) */ public Attribute.State getState(String key) { @@ -130,41 +147,63 @@ public final class Attributes { } /** + * Whether the attribute is set + * * @param key - * @return true if the key is {@link State#SET}, false in all other cases + * a {@link java.lang.String} object. + * @return true if the key is + * {@link org.eclipse.jgit.attributes.Attribute.State#SET}, false in + * all other cases */ public boolean isSet(String key) { return (getState(key) == State.SET); } /** + * Whether the attribute is unset + * * @param key - * @return true if the key is {@link State#UNSET}, false in all other cases + * a {@link java.lang.String} object. + * @return true if the key is + * {@link org.eclipse.jgit.attributes.Attribute.State#UNSET}, false + * in all other cases */ public boolean isUnset(String key) { return (getState(key) == State.UNSET); } /** + * Whether the attribute with the given key is unspecified + * * @param key - * @return true if the key is {@link State#UNSPECIFIED}, false in all other - * cases + * a {@link java.lang.String} object. + * @return true if the key is + * {@link org.eclipse.jgit.attributes.Attribute.State#UNSPECIFIED}, + * false in all other cases */ public boolean isUnspecified(String key) { return (getState(key) == State.UNSPECIFIED); } /** + * Is this a custom attribute + * * @param key - * @return true if the key is {@link State#CUSTOM}, false in all other cases - * see {@link #getValue(String)} for the value of the key + * a {@link java.lang.String} object. + * @return true if the key is + * {@link org.eclipse.jgit.attributes.Attribute.State#CUSTOM}, false + * in all other cases see {@link #getValue(String)} for the value of + * the key */ public boolean isCustom(String key) { return (getState(key) == State.CUSTOM); } /** + * Get attribute value + * * @param key + * an attribute key * @return the attribute value (may be <code>null</code>) */ public String getValue(String key) { @@ -192,6 +231,7 @@ public final class Attributes { return true; } + /** {@inheritDoc} */ @Override public String toString() { StringBuilder buf = new StringBuilder(); @@ -206,11 +246,13 @@ public final class Attributes { return buf.toString(); } + /** {@inheritDoc} */ @Override public int hashCode() { return map.hashCode(); } + /** {@inheritDoc} */ @Override public boolean equals(Object obj) { if (this == obj) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesHandler.java b/org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesHandler.java index 8d928e3749..638dd827ed 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesHandler.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesHandler.java @@ -61,7 +61,8 @@ import org.eclipse.jgit.treewalk.WorkingTreeIterator; * The attributes handler knows how to retrieve, parse and merge attributes from * the various gitattributes files. Furthermore it collects and expands macro * expressions. The method {@link #getAttributes()} yields the ready processed - * attributes for the current path represented by the {@link TreeWalk} + * attributes for the current path represented by the + * {@link org.eclipse.jgit.treewalk.TreeWalk} * <p> * The implementation is based on the specifications in * http://git-scm.com/docs/gitattributes @@ -90,11 +91,13 @@ public class AttributesHandler { private final Map<String, List<Attribute>> expansions = new HashMap<>(); /** - * Create an {@link AttributesHandler} with default rules as well as merged - * rules from global, info and worktree root attributes + * Create an {@link org.eclipse.jgit.attributes.AttributesHandler} with + * default rules as well as merged rules from global, info and worktree root + * attributes * * @param treeWalk - * @throws IOException + * a {@link org.eclipse.jgit.treewalk.TreeWalk} + * @throws java.io.IOException */ public AttributesHandler(TreeWalk treeWalk) throws IOException { this.treeWalk = treeWalk; @@ -129,11 +132,12 @@ public class AttributesHandler { } /** - * see {@link TreeWalk#getAttributes()} + * See {@link org.eclipse.jgit.treewalk.TreeWalk#getAttributes()} * - * @return the {@link Attributes} for the current path represented by the - * {@link TreeWalk} - * @throws IOException + * @return the {@link org.eclipse.jgit.attributes.Attributes} for the + * current path represented by the + * {@link org.eclipse.jgit.treewalk.TreeWalk} + * @throws java.io.IOException */ public Attributes getAttributes() throws IOException { String entryPath = treeWalk.getPathString(); @@ -282,7 +286,10 @@ public class AttributesHandler { } /** + * Expand a macro + * * @param attr + * a {@link org.eclipse.jgit.attributes.Attribute} * @param result * contains the (recursive) expanded and merged macro attributes * including the attribute iself diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesNode.java b/org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesNode.java index 13aeaee7dc..62bf9f2737 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesNode.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesNode.java @@ -63,7 +63,9 @@ public class AttributesNode { /** The rules that have been parsed into this node. */ private final List<AttributesRule> rules; - /** Create an empty ignore node with no rules. */ + /** + * Create an empty ignore node with no rules. + */ public AttributesNode() { rules = new ArrayList<>(); } @@ -73,7 +75,7 @@ public class AttributesNode { * * @param rules * list of rules. - **/ + */ public AttributesNode(List<AttributesRule> rules) { this.rules = rules; } @@ -84,7 +86,7 @@ public class AttributesNode { * @param in * input stream holding the standard ignore format. The caller is * responsible for closing the stream. - * @throws IOException + * @throws java.io.IOException * Error thrown when reading an ignore file. */ public void parse(InputStream in) throws IOException { @@ -116,7 +118,11 @@ public class AttributesNode { return new BufferedReader(new InputStreamReader(in, Constants.CHARSET)); } - /** @return list of all ignore rules held by this node. */ + /** + * Getter for the field <code>rules</code>. + * + * @return list of all ignore rules held by this node + */ public List<AttributesRule> getRules() { return Collections.unmodifiableList(rules); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesNodeProvider.java b/org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesNodeProvider.java index 6f2ebad677..f1d7d7be0e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesNodeProvider.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesNodeProvider.java @@ -47,32 +47,32 @@ import java.io.IOException; import org.eclipse.jgit.lib.CoreConfig; /** - * An interface used to retrieve the global and info {@link AttributesNode}s. + * An interface used to retrieve the global and info + * {@link org.eclipse.jgit.attributes.AttributesNode}s. * * @since 4.2 - * */ public interface AttributesNodeProvider { /** - * Retrieve the {@link AttributesNode} that holds the information located - * in $GIT_DIR/info/attributes file. + * Retrieve the {@link org.eclipse.jgit.attributes.AttributesNode} that + * holds the information located in $GIT_DIR/info/attributes file. * - * @return the {@link AttributesNode} that holds the information located in - * $GIT_DIR/info/attributes file. - * @throws IOException + * @return the {@link org.eclipse.jgit.attributes.AttributesNode} that holds + * the information located in $GIT_DIR/info/attributes file. + * @throws java.io.IOException * if an error is raised while parsing the attributes file */ public AttributesNode getInfoAttributesNode() throws IOException; /** - * Retrieve the {@link AttributesNode} that holds the information located - * in the global gitattributes file. + * Retrieve the {@link org.eclipse.jgit.attributes.AttributesNode} that + * holds the information located in the global gitattributes file. * - * @return the {@link AttributesNode} that holds the information located in - * the global gitattributes file. - * @throws IOException - * IOException if an error is raised while parsing the + * @return the {@link org.eclipse.jgit.attributes.AttributesNode} that holds + * the information located in the global gitattributes file. + * @throws java.io.IOException + * java.io.IOException if an error is raised while parsing the * attributes file * @see CoreConfig#getAttributesFile() */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesProvider.java b/org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesProvider.java index 1037f697d4..1545e3523d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesProvider.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesProvider.java @@ -49,6 +49,8 @@ package org.eclipse.jgit.attributes; */ public interface AttributesProvider { /** + * Get attributes + * * @return the currently active attributes */ public Attributes getAttributes(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesRule.java b/org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesRule.java index 3cf5de8be5..a91d8c282f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesRule.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/attributes/AttributesRule.java @@ -57,7 +57,7 @@ import org.eclipse.jgit.ignore.internal.PathMatcher; /** * A single attributes rule corresponding to one line in a .gitattributes file. * - * Inspiration from: {@link FastIgnoreRule} + * Inspiration from: {@link org.eclipse.jgit.ignore.FastIgnoreRule} * * @since 3.7 */ @@ -162,7 +162,9 @@ public class AttributesRule { } /** - * @return True if the pattern should match directories only + * Whether to match directories only + * + * @return {@code true} if the pattern should match directories only * @since 4.3 */ public boolean isDirOnly() { @@ -170,7 +172,7 @@ public class AttributesRule { } /** - * Returns the attributes. + * Return the attributes. * * @return an unmodifiable list of attributes (never returns * <code>null</code>) @@ -180,6 +182,8 @@ public class AttributesRule { } /** + * Whether the pattern is only a file name and not a path + * * @return <code>true</code> if the pattern is just a file name and not a * path */ @@ -188,6 +192,8 @@ public class AttributesRule { } /** + * Get the pattern + * * @return The blob pattern to be used as a matcher (never returns * <code>null</code>) */ @@ -214,6 +220,7 @@ public class AttributesRule { return match; } + /** {@inheritDoc} */ @Override public String toString() { StringBuilder sb = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/attributes/FilterCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/attributes/FilterCommand.java index 10be58880c..aae00764f6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/attributes/FilterCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/attributes/FilterCommand.java @@ -50,7 +50,7 @@ import java.io.OutputStream; * An abstraction for JGit's builtin implementations for hooks and filters. * Instead of spawning an external processes to start a filter/hook and to pump * data from/to stdin/stdout these builtin commmands may be used. They are - * constructed by {@link FilterCommandFactory}. + * constructed by {@link org.eclipse.jgit.attributes.FilterCommandFactory}. * * @since 4.6 */ @@ -66,10 +66,12 @@ public abstract class FilterCommand { protected OutputStream out; /** + * Constructor for FilterCommand + * * @param in - * The {@link InputStream} this command should read from + * The {@link java.io.InputStream} this command should read from * @param out - * The {@link OutputStream} this command should write to + * The {@link java.io.OutputStream} this command should write to */ public FilterCommand(InputStream in, OutputStream out) { this.in = in; @@ -80,15 +82,15 @@ public abstract class FilterCommand { * Execute the command. The command is supposed to read data from * {@link #in} and to write the result to {@link #out}. It returns the * number of bytes it read from {@link #in}. It should be called in a loop - * until it returns -1 signaling that the {@link InputStream} is completely - * processed. + * until it returns -1 signaling that the {@link java.io.InputStream} is + * completely processed. * - * @return the number of bytes read from the {@link InputStream} or -1. -1 - * means that the {@link InputStream} is completely processed. - * @throws IOException - * when {@link IOException} occured while reading from + * @return the number of bytes read from the {@link java.io.InputStream} or + * -1. -1 means that the {@link java.io.InputStream} is completely + * processed. + * @throws java.io.IOException + * when {@link java.io.IOException} occured while reading from * {@link #in} or writing to {@link #out} - * */ public abstract int run() throws IOException; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/attributes/FilterCommandFactory.java b/org.eclipse.jgit/src/org/eclipse/jgit/attributes/FilterCommandFactory.java index 6b973da35f..11b76b0d90 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/attributes/FilterCommandFactory.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/attributes/FilterCommandFactory.java @@ -49,23 +49,25 @@ import java.io.OutputStream; import org.eclipse.jgit.lib.Repository; /** - * The factory responsible for creating instances of {@link FilterCommand}. + * The factory responsible for creating instances of + * {@link org.eclipse.jgit.attributes.FilterCommand}. * * @since 4.6 */ public interface FilterCommandFactory { /** - * Create a new {@link FilterCommand}. + * Create a new {@link org.eclipse.jgit.attributes.FilterCommand}. * * @param db * the repository this command should work on * @param in - * the {@link InputStream} this command should read from + * the {@link java.io.InputStream} this command should read from * @param out - * the {@link OutputStream} this command should write to - * @return the created {@link FilterCommand} - * @throws IOException - * thrown when the command constructor throws an IOException + * the {@link java.io.OutputStream} this command should write to + * @return the created {@link org.eclipse.jgit.attributes.FilterCommand} + * @throws java.io.IOException + * thrown when the command constructor throws an + * java.io.IOException */ public FilterCommand create(Repository db, InputStream in, OutputStream out) throws IOException; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/attributes/FilterCommandRegistry.java b/org.eclipse.jgit/src/org/eclipse/jgit/attributes/FilterCommandRegistry.java index 3fbaedb051..7e511a8312 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/attributes/FilterCommandRegistry.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/attributes/FilterCommandRegistry.java @@ -59,17 +59,20 @@ public class FilterCommandRegistry { private static ConcurrentHashMap<String, FilterCommandFactory> filterCommandRegistry = new ConcurrentHashMap<>(); /** - * Registers a {@link FilterCommandFactory} responsible for creating - * {@link FilterCommand}s for a certain command name. If the factory f1 is - * registered for the name "jgit://builtin/x" then a call to - * <code>getCommand("jgit://builtin/x", ...)</code> will call - * <code>f1(...)</code> to create a new instance of {@link FilterCommand} + * Register a {@link org.eclipse.jgit.attributes.FilterCommandFactory} + * responsible for creating + * {@link org.eclipse.jgit.attributes.FilterCommand}s for a certain command + * name. If the factory f1 is registered for the name "jgit://builtin/x" + * then a call to <code>getCommand("jgit://builtin/x", ...)</code> will call + * <code>f1(...)</code> to create a new instance of + * {@link org.eclipse.jgit.attributes.FilterCommand} * * @param filterCommandName * the command name for which this factory is registered * @param factory - * the factory responsible for creating {@link FilterCommand}s - * for the specified name + * the factory responsible for creating + * {@link org.eclipse.jgit.attributes.FilterCommand}s for the + * specified name * @return the previous factory associated with <tt>commandName</tt>, or * <tt>null</tt> if there was no mapping for <tt>commandName</tt> */ @@ -79,8 +82,8 @@ public class FilterCommandRegistry { } /** - * Unregisters the {@link FilterCommandFactory} registered for the given - * command name + * Unregister the {@link org.eclipse.jgit.attributes.FilterCommandFactory} + * registered for the given command name * * @param filterCommandName * the FilterCommandFactory's filter command name @@ -92,8 +95,9 @@ public class FilterCommandRegistry { } /** - * Checks whether any {@link FilterCommandFactory} is registered for a given - * command name + * Check whether any + * {@link org.eclipse.jgit.attributes.FilterCommandFactory} is registered + * for a given command name * * @param filterCommandName * the name for which the registry should be checked @@ -104,7 +108,10 @@ public class FilterCommandRegistry { } /** - * @return Set of commandNames for which a {@link FilterCommandFactory} is + * Get registered filter commands + * + * @return Set of commandNames for which a + * {@link org.eclipse.jgit.attributes.FilterCommandFactory} is * registered */ public static Set<String> getRegisteredFilterCommands() { @@ -112,23 +119,26 @@ public class FilterCommandRegistry { } /** - * Creates a new {@link FilterCommand} for the given name. A factory must be - * registered for the name in advance. + * Create a new {@link org.eclipse.jgit.attributes.FilterCommand} for the + * given name. A factory must be registered for the name in advance. * * @param filterCommandName - * The name for which a new {@link FilterCommand} should be + * The name for which a new + * {@link org.eclipse.jgit.attributes.FilterCommand} should be * created * @param db * the repository this command should work on * @param in - * the {@link InputStream} this {@link FilterCommand} should read + * the {@link java.io.InputStream} this + * {@link org.eclipse.jgit.attributes.FilterCommand} should read * from * @param out - * the {@link OutputStream} this {@link FilterCommand} should - * write to + * the {@link java.io.OutputStream} this + * {@link org.eclipse.jgit.attributes.FilterCommand} should write + * to * @return the command if a command could be created or <code>null</code> if * there was no factory registered for that name - * @throws IOException + * @throws java.io.IOException */ public static FilterCommand createFilterCommand(String filterCommandName, Repository db, InputStream in, OutputStream out) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/blame/BlameGenerator.java b/org.eclipse.jgit/src/org/eclipse/jgit/blame/BlameGenerator.java index 4ad58c3850..e2411d6043 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/blame/BlameGenerator.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/blame/BlameGenerator.java @@ -88,8 +88,10 @@ import org.eclipse.jgit.treewalk.filter.TreeFilter; * <p> * Applications that want more incremental update behavior may use either the * raw {@link #next()} streaming approach supported by this class, or construct - * a {@link BlameResult} using {@link BlameResult#create(BlameGenerator)} and - * incrementally construct the result with {@link BlameResult#computeNext()}. + * a {@link org.eclipse.jgit.blame.BlameResult} using + * {@link org.eclipse.jgit.blame.BlameResult#create(BlameGenerator)} and + * incrementally construct the result with + * {@link org.eclipse.jgit.blame.BlameResult#computeNext()}. * <p> * This class is not thread-safe. * <p> @@ -186,12 +188,20 @@ public class BlameGenerator implements AutoCloseable { treeWalk.setRecursive(true); } - /** @return repository being scanned for revision history. */ + /** + * Get repository + * + * @return repository being scanned for revision history + */ public Repository getRepository() { return repository; } - /** @return path file path being processed. */ + /** + * Get result path + * + * @return path file path being processed + */ public String getResultPath() { return resultPath.getPath(); } @@ -200,6 +210,7 @@ public class BlameGenerator implements AutoCloseable { * Difference algorithm to use when comparing revisions. * * @param algorithm + * a {@link org.eclipse.jgit.diff.DiffAlgorithm} * @return {@code this} */ public BlameGenerator setDiffAlgorithm(DiffAlgorithm algorithm) { @@ -211,6 +222,7 @@ public class BlameGenerator implements AutoCloseable { * Text comparator to use when comparing revisions. * * @param comparator + * a {@link org.eclipse.jgit.diff.RawTextComparator} * @return {@code this} */ public BlameGenerator setTextComparator(RawTextComparator comparator) { @@ -255,15 +267,15 @@ public class BlameGenerator implements AutoCloseable { * <p> * Candidates should be pushed in history order from oldest-to-newest. * Applications should push the starting commit first, then the index - * revision (if the index is interesting), and finally the working tree - * copy (if the working tree is interesting). + * revision (if the index is interesting), and finally the working tree copy + * (if the working tree is interesting). * * @param description * description of the blob revision, such as "Working Tree". * @param contents * contents of the file. * @return {@code this} - * @throws IOException + * @throws java.io.IOException * the repository cannot be read. */ public BlameGenerator push(String description, byte[] contents) @@ -284,7 +296,7 @@ public class BlameGenerator implements AutoCloseable { * @param contents * contents of the file. * @return {@code this} - * @throws IOException + * @throws java.io.IOException * the repository cannot be read. */ public BlameGenerator push(String description, RawText contents) @@ -312,7 +324,7 @@ public class BlameGenerator implements AutoCloseable { * @param id * may be a commit or a blob. * @return {@code this} - * @throws IOException + * @throws java.io.IOException * the repository cannot be read. */ public BlameGenerator push(String description, AnyObjectId id) @@ -357,8 +369,8 @@ public class BlameGenerator implements AutoCloseable { * each of these is a descendant commit that removed the line, typically * this occurs when the same deletion appears in multiple side branches such * as due to a cherry-pick. Applications relying on reverse should use - * {@link BlameResult} as it filters these duplicate sources and only - * remembers the first (oldest) deletion. + * {@link org.eclipse.jgit.blame.BlameResult} as it filters these duplicate + * sources and only remembers the first (oldest) deletion. * * @param start * oldest commit to traverse from. The result file will be loaded @@ -367,7 +379,7 @@ public class BlameGenerator implements AutoCloseable { * most recent commit to stop traversal at. Usually an active * branch tip, tag, or HEAD. * @return {@code this} - * @throws IOException + * @throws java.io.IOException * the repository cannot be read. */ public BlameGenerator reverse(AnyObjectId start, AnyObjectId end) @@ -389,8 +401,8 @@ public class BlameGenerator implements AutoCloseable { * each of these is a descendant commit that removed the line, typically * this occurs when the same deletion appears in multiple side branches such * as due to a cherry-pick. Applications relying on reverse should use - * {@link BlameResult} as it filters these duplicate sources and only - * remembers the first (oldest) deletion. + * {@link org.eclipse.jgit.blame.BlameResult} as it filters these duplicate + * sources and only remembers the first (oldest) deletion. * * @param start * oldest commit to traverse from. The result file will be loaded @@ -399,7 +411,7 @@ public class BlameGenerator implements AutoCloseable { * most recent commits to stop traversal at. Usually an active * branch tip, tag, or HEAD. * @return {@code this} - * @throws IOException + * @throws java.io.IOException * the repository cannot be read. */ public BlameGenerator reverse(AnyObjectId start, @@ -443,7 +455,7 @@ public class BlameGenerator implements AutoCloseable { * Execute the generator in a blocking fashion until all data is ready. * * @return the complete result. Null if no file exists for the given path. - * @throws IOException + * @throws java.io.IOException * the repository cannot be read. */ public BlameResult computeBlameResult() throws IOException { @@ -464,7 +476,7 @@ public class BlameGenerator implements AutoCloseable { * and {@link #getResultStart()}, {@link #getResultEnd()} methods * can be used to inspect the region found. False if there are no * more regions to describe. - * @throws IOException + * @throws java.io.IOException * repository cannot be read. */ public boolean next() throws IOException { @@ -842,28 +854,47 @@ public class BlameGenerator implements AutoCloseable { return outCandidate.sourceCommit; } - /** @return current author being blamed. */ + /** + * Get source author + * + * @return current author being blamed + */ public PersonIdent getSourceAuthor() { return outCandidate.getAuthor(); } - /** @return current committer being blamed. */ + /** + * Get source committer + * + * @return current committer being blamed + */ public PersonIdent getSourceCommitter() { RevCommit c = getSourceCommit(); return c != null ? c.getCommitterIdent() : null; } - /** @return path of the file being blamed. */ + /** + * Get source path + * + * @return path of the file being blamed + */ public String getSourcePath() { return outCandidate.sourcePath.getPath(); } - /** @return rename score if a rename occurred in {@link #getSourceCommit}. */ + /** + * Get rename score + * + * @return rename score if a rename occurred in {@link #getSourceCommit} + */ public int getRenameScore() { return outCandidate.renameScore; } /** + * Get first line of the source data that has been blamed for the current + * region + * * @return first line of the source data that has been blamed for the * current region. This is line number of where the region was added * during {@link #getSourceCommit()} in file @@ -874,6 +905,9 @@ public class BlameGenerator implements AutoCloseable { } /** + * Get one past the range of the source data that has been blamed for the + * current region + * * @return one past the range of the source data that has been blamed for * the current region. This is line number of where the region was * added during {@link #getSourceCommit()} in file @@ -885,6 +919,9 @@ public class BlameGenerator implements AutoCloseable { } /** + * Get first line of the result that {@link #getSourceCommit()} has been + * blamed for providing + * * @return first line of the result that {@link #getSourceCommit()} has been * blamed for providing. Line numbers use 0 based indexing. */ @@ -893,6 +930,9 @@ public class BlameGenerator implements AutoCloseable { } /** + * Get one past the range of the result that {@link #getSourceCommit()} has + * been blamed for providing + * * @return one past the range of the result that {@link #getSourceCommit()} * has been blamed for providing. Line numbers use 0 based indexing. * Because a source cannot be blamed for an empty region of the @@ -905,6 +945,9 @@ public class BlameGenerator implements AutoCloseable { } /** + * Get number of lines in the current region being blamed to + * {@link #getSourceCommit()} + * * @return number of lines in the current region being blamed to * {@link #getSourceCommit()}. This is always the value of the * expression {@code getResultEnd() - getResultStart()}, but also @@ -915,6 +958,9 @@ public class BlameGenerator implements AutoCloseable { } /** + * Get complete contents of the source file blamed for the current output + * region + * * @return complete contents of the source file blamed for the current * output region. This is the contents of {@link #getSourcePath()} * within {@link #getSourceCommit()}. The source contents is @@ -926,13 +972,15 @@ public class BlameGenerator implements AutoCloseable { } /** + * Get complete file contents of the result file blame is annotating + * * @return complete file contents of the result file blame is annotating. * This value is accessible only after being configured and only * immediately before the first call to {@link #next()}. Returns * null if the path does not exist. - * @throws IOException + * @throws java.io.IOException * repository cannot be read. - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * {@link #next()} has already been invoked. */ public RawText getResultContents() throws IOException { @@ -940,6 +988,8 @@ public class BlameGenerator implements AutoCloseable { } /** + * {@inheritDoc} + * <p> * Release the current blame session. * * @since 4.0 diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/blame/BlameResult.java b/org.eclipse.jgit/src/org/eclipse/jgit/blame/BlameResult.java index e34db38fde..5fb77501fa 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/blame/BlameResult.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/blame/BlameResult.java @@ -78,7 +78,7 @@ public class BlameResult { * the generator the result will consume records from. * @return the new result object. null if the generator cannot find the path * it starts from. - * @throws IOException + * @throws java.io.IOException * the repository cannot be read. */ public static BlameResult create(BlameGenerator gen) throws IOException { @@ -123,17 +123,27 @@ public class BlameResult { sourcePaths = new String[cnt]; } - /** @return path of the file this result annotates. */ + /** + * Get result path + * + * @return path of the file this result annotates + */ public String getResultPath() { return resultPath; } - /** @return contents of the result file, available for display. */ + /** + * Get result contents + * + * @return contents of the result file, available for display + */ public RawText getResultContents() { return resultContents; } - /** Throw away the {@link #getResultContents()}. */ + /** + * Throw away the {@link #getResultContents()}. + */ public void discardResultContents() { resultContents = null; } @@ -227,7 +237,7 @@ public class BlameResult { /** * Compute all pending information. * - * @throws IOException + * @throws java.io.IOException * the repository cannot be read. */ public void computeAll() throws IOException { @@ -252,7 +262,7 @@ public class BlameResult { * to determine how many lines of the result were computed. * * @return index that is now available. -1 if no more are available. - * @throws IOException + * @throws java.io.IOException * the repository cannot be read. */ public int computeNext() throws IOException { @@ -271,7 +281,11 @@ public class BlameResult { } } - /** @return length of the last segment found by {@link #computeNext()}. */ + /** + * Get last length + * + * @return length of the last segment found by {@link #computeNext()} + */ public int lastLength() { return lastLength; } @@ -283,7 +297,7 @@ public class BlameResult { * first index to examine (inclusive). * @param end * end index (exclusive). - * @throws IOException + * @throws java.io.IOException * the repository cannot be read. */ public void computeRange(int start, int end) throws IOException { @@ -322,6 +336,7 @@ public class BlameResult { } } + /** {@inheritDoc} */ @Override public String toString() { StringBuilder r = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/blame/Candidate.java b/org.eclipse.jgit/src/org/eclipse/jgit/blame/Candidate.java index 72d8abe1fc..855ef78252 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/blame/Candidate.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/blame/Candidate.java @@ -325,6 +325,7 @@ class Candidate { } } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/blame/Region.java b/org.eclipse.jgit/src/org/eclipse/jgit/blame/Region.java index 9ea346b894..18281f021d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/blame/Region.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/blame/Region.java @@ -116,6 +116,7 @@ class Region { return head; } + /** {@inheritDoc} */ @Override public String toString() { StringBuilder buf = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/blame/ReverseWalk.java b/org.eclipse.jgit/src/org/eclipse/jgit/blame/ReverseWalk.java index 5b59804cf1..2eb313f603 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/blame/ReverseWalk.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/blame/ReverseWalk.java @@ -57,6 +57,7 @@ final class ReverseWalk extends RevWalk { super(repo); } + /** {@inheritDoc} */ @Override public ReverseCommit next() throws MissingObjectException, IncorrectObjectTypeException, IOException { @@ -68,6 +69,7 @@ final class ReverseWalk extends RevWalk { return c; } + /** {@inheritDoc} */ @Override protected RevCommit createCommit(AnyObjectId id) { return new ReverseCommit(id); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/ContentSource.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/ContentSource.java index 444ab1cb83..5ede3ea6d4 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/ContentSource.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/ContentSource.java @@ -55,13 +55,13 @@ import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.lib.ObjectLoader; import org.eclipse.jgit.lib.ObjectReader; import org.eclipse.jgit.lib.ObjectStream; -import org.eclipse.jgit.treewalk.FileTreeIterator; import org.eclipse.jgit.treewalk.TreeWalk; import org.eclipse.jgit.treewalk.WorkingTreeIterator; import org.eclipse.jgit.treewalk.filter.PathFilter; /** - * Supplies the content of a file for {@link DiffFormatter}. + * Supplies the content of a file for + * {@link org.eclipse.jgit.diff.DiffFormatter}. * <p> * A content source is not thread-safe. Sources may contain state, including * information about the last ObjectLoader they returned. Callers must be @@ -83,8 +83,9 @@ public abstract class ContentSource { /** * Construct a content source for a working directory. * - * If the iterator is a {@link FileTreeIterator} an optimized version is - * used that doesn't require seeking through a TreeWalk. + * If the iterator is a {@link org.eclipse.jgit.treewalk.FileTreeIterator} + * an optimized version is used that doesn't require seeking through a + * TreeWalk. * * @param iterator * the iterator to obtain source files through. @@ -102,7 +103,7 @@ public abstract class ContentSource { * @param id * blob id of the file, if known. * @return the size in bytes. - * @throws IOException + * @throws java.io.IOException * the file cannot be accessed. */ public abstract long size(String path, ObjectId id) throws IOException; @@ -117,7 +118,7 @@ public abstract class ContentSource { * @return a loader that can supply the content of the file. The loader must * be used before another loader can be obtained from this same * source. - * @throws IOException + * @throws java.io.IOException * the file cannot be accessed. */ public abstract ObjectLoader open(String path, ObjectId id) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/DiffAlgorithm.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/DiffAlgorithm.java index 5f01366c47..19eb39d93c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/DiffAlgorithm.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/DiffAlgorithm.java @@ -44,7 +44,8 @@ package org.eclipse.jgit.diff; /** - * Compares two {@link Sequence}s to create an {@link EditList} of changes. + * Compares two {@link org.eclipse.jgit.diff.Sequence}s to create an + * {@link org.eclipse.jgit.diff.EditList} of changes. * <p> * An algorithm's {@code diff} method must be callable from concurrent threads * without data collisions. This permits some algorithms to use a singleton @@ -69,6 +70,8 @@ public abstract class DiffAlgorithm { } /** + * Get diff algorithm + * * @param alg * the diff algorithm for which an implementation should be * returned @@ -88,18 +91,18 @@ public abstract class DiffAlgorithm { /** * Compare two sequences and identify a list of edits between them. * - * @param <S> - * type of sequence being compared. * @param cmp * the comparator supplying the element equivalence function. * @param a * the first (also known as old or pre-image) sequence. Edits * returned by this algorithm will reference indexes using the - * 'A' side: {@link Edit#getBeginA()}, {@link Edit#getEndA()}. + * 'A' side: {@link org.eclipse.jgit.diff.Edit#getBeginA()}, + * {@link org.eclipse.jgit.diff.Edit#getEndA()}. * @param b * the second (also known as new or post-image) sequence. Edits * returned by this algorithm will reference indexes using the - * 'B' side: {@link Edit#getBeginB()}, {@link Edit#getEndB()}. + * 'B' side: {@link org.eclipse.jgit.diff.Edit#getBeginB()}, + * {@link org.eclipse.jgit.diff.Edit#getEndB()}. * @return a modifiable edit list comparing the two sequences. If empty, the * sequences are identical according to {@code cmp}'s rules. The * result list is never null. @@ -244,20 +247,21 @@ public abstract class DiffAlgorithm { * proven to have no common starting or ending elements. The expected * elimination of common starting and ending elements is automatically * performed by the {@link #diff(SequenceComparator, Sequence, Sequence)} - * method, which invokes this method using {@link Subsequence}s. + * method, which invokes this method using + * {@link org.eclipse.jgit.diff.Subsequence}s. * - * @param <S> - * type of sequence being compared. * @param cmp * the comparator supplying the element equivalence function. * @param a * the first (also known as old or pre-image) sequence. Edits * returned by this algorithm will reference indexes using the - * 'A' side: {@link Edit#getBeginA()}, {@link Edit#getEndA()}. + * 'A' side: {@link org.eclipse.jgit.diff.Edit#getBeginA()}, + * {@link org.eclipse.jgit.diff.Edit#getEndA()}. * @param b * the second (also known as new or post-image) sequence. Edits * returned by this algorithm will reference indexes using the - * 'B' side: {@link Edit#getBeginB()}, {@link Edit#getEndB()}. + * 'B' side: {@link org.eclipse.jgit.diff.Edit#getBeginB()}, + * {@link org.eclipse.jgit.diff.Edit#getEndB()}. * @return a modifiable edit list comparing the two sequences. */ public abstract <S extends Sequence> EditList diffNonCommon( diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/DiffConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/DiffConfig.java index ee709495e5..063cefffa6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/DiffConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/DiffConfig.java @@ -51,7 +51,9 @@ import org.eclipse.jgit.lib.Config.SectionParser; import org.eclipse.jgit.lib.ConfigConstants; import org.eclipse.jgit.util.StringUtils; -/** Keeps track of diff related configuration options. */ +/** + * Keeps track of diff related configuration options. + */ public class DiffConfig { /** Key for {@link Config#get(SectionParser)}. */ public static final Config.SectionParser<DiffConfig> KEY = DiffConfig::new; @@ -83,22 +85,38 @@ public class DiffConfig { ConfigConstants.CONFIG_KEY_RENAMELIMIT, 200); } - /** @return true if the prefix "a/" and "b/" should be suppressed. */ + /** + * If prefix should be suppressed + * + * @return true if the prefix "a/" and "b/" should be suppressed + */ public boolean isNoPrefix() { return noPrefix; } - /** @return true if rename detection is enabled by default. */ + /** + * If rename detection is enabled + * + * @return true if rename detection is enabled by default + */ public boolean isRenameDetectionEnabled() { return renameDetectionType != RenameDetectionType.FALSE; } - /** @return type of rename detection to perform. */ + /** + * Get the rename detection type + * + * @return type of rename detection to perform + */ public RenameDetectionType getRenameDetectionType() { return renameDetectionType; } - /** @return limit on number of paths to perform inexact rename detection. */ + /** + * Get the rename limit + * + * @return limit on number of paths to perform inexact rename detection + */ public int getRenameLimit() { return renameLimit; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/DiffEntry.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/DiffEntry.java index 5eb1942629..0f5ea76519 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/DiffEntry.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/DiffEntry.java @@ -58,7 +58,9 @@ import org.eclipse.jgit.treewalk.TreeWalk; import org.eclipse.jgit.treewalk.filter.TreeFilter; import org.eclipse.jgit.treewalk.filter.TreeFilterMarker; -/** A value class representing a change to a file */ +/** + * A value class representing a change to a file + */ public class DiffEntry { /** Magical SHA1 used for file adds or deletes */ static final AbbreviatedObjectId A_ZERO = AbbreviatedObjectId @@ -107,9 +109,9 @@ public class DiffEntry { * @param walk * the TreeWalk to walk through. Must have exactly two trees. * @return headers describing the changed files. - * @throws IOException + * @throws java.io.IOException * the repository cannot be accessed. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * When given TreeWalk doesn't have exactly two trees. */ public static List<DiffEntry> scan(TreeWalk walk) throws IOException { @@ -127,9 +129,9 @@ public class DiffEntry { * @param includeTrees * include tree objects. * @return headers describing the changed files. - * @throws IOException + * @throws java.io.IOException * the repository cannot be accessed. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * when {@code includeTrees} is true and given TreeWalk is * recursive. Or when given TreeWalk doesn't have exactly two * trees @@ -155,9 +157,9 @@ public class DiffEntry { * queried through {{@link #isMarked(int)} (with the index from * this passed array). * @return headers describing the changed files. - * @throws IOException + * @throws java.io.IOException * the repository cannot be accessed. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * when {@code includeTrees} is true and given TreeWalk is * recursive. Or when given TreeWalk doesn't have exactly two * trees @@ -392,12 +394,20 @@ public class DiffEntry { return side == Side.OLD ? getOldPath() : getNewPath(); } - /** @return the old file mode, if described in the patch */ + /** + * Get the old file mode + * + * @return the old file mode, if described in the patch + */ public FileMode getOldMode() { return oldMode; } - /** @return the new file mode, if described in the patch */ + /** + * Get the new file mode + * + * @return the new file mode, if described in the patch + */ public FileMode getNewMode() { return newMode; } @@ -413,15 +423,22 @@ public class DiffEntry { return side == Side.OLD ? getOldMode() : getNewMode(); } - /** @return the type of change this patch makes on {@link #getNewPath()} */ + /** + * Get the change type + * + * @return the type of change this patch makes on {@link #getNewPath()} + */ public ChangeType getChangeType() { return changeType; } /** + * Get similarity score + * * @return similarity score between {@link #getOldPath()} and * {@link #getNewPath()} if {@link #getChangeType()} is - * {@link ChangeType#COPY} or {@link ChangeType#RENAME}. + * {@link org.eclipse.jgit.diff.DiffEntry.ChangeType#COPY} or + * {@link org.eclipse.jgit.diff.DiffEntry.ChangeType#RENAME}. */ public int getScore() { return score; @@ -466,10 +483,9 @@ public class DiffEntry { * * @param index * the index of the tree filter to check for (must be between 0 - * and {@link Integer#SIZE}). - * - * @return true, if the tree filter matched; false if not + * and {@link java.lang.Integer#SIZE}). * @since 2.3 + * @return a boolean. */ public boolean isMarked(int index) { return (treeFilterMarks & (1L << index)) != 0; @@ -498,6 +514,7 @@ public class DiffEntry { return side == Side.OLD ? getOldId() : getNewId(); } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/DiffFormatter.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/DiffFormatter.java index fa7cc0df87..bf9a27bdc9 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/DiffFormatter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/DiffFormatter.java @@ -66,9 +66,9 @@ import org.eclipse.jgit.diff.DiffAlgorithm.SupportedAlgorithm; import org.eclipse.jgit.diff.DiffEntry.ChangeType; import org.eclipse.jgit.dircache.DirCacheIterator; import org.eclipse.jgit.errors.AmbiguousObjectException; +import org.eclipse.jgit.errors.BinaryBlobException; import org.eclipse.jgit.errors.CorruptObjectException; import org.eclipse.jgit.errors.IncorrectObjectTypeException; -import org.eclipse.jgit.errors.LargeObjectException; import org.eclipse.jgit.errors.MissingObjectException; import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.lib.AbbreviatedObjectId; @@ -84,7 +84,6 @@ import org.eclipse.jgit.lib.ProgressMonitor; import org.eclipse.jgit.lib.Repository; import org.eclipse.jgit.patch.FileHeader; import org.eclipse.jgit.patch.FileHeader.PatchType; -import org.eclipse.jgit.patch.HunkHeader; import org.eclipse.jgit.revwalk.FollowFilter; import org.eclipse.jgit.revwalk.RevTree; import org.eclipse.jgit.revwalk.RevWalk; @@ -100,7 +99,6 @@ import org.eclipse.jgit.treewalk.filter.NotIgnoredFilter; import org.eclipse.jgit.treewalk.filter.PathFilter; import org.eclipse.jgit.treewalk.filter.TreeFilter; import org.eclipse.jgit.util.QuotedString; -import org.eclipse.jgit.util.io.DisabledOutputStream; /** * Format a Git style patch script. @@ -113,9 +111,6 @@ public class DiffFormatter implements AutoCloseable { /** Magic return content indicating it is empty or no content present. */ private static final byte[] EMPTY = new byte[] {}; - /** Magic return indicating the content is binary. */ - private static final byte[] BINARY = new byte[] {}; - private final OutputStream out; private ObjectReader reader; @@ -158,7 +153,11 @@ public class DiffFormatter implements AutoCloseable { this.out = out; } - /** @return the stream we are outputting data to. */ + /** + * Get output stream + * + * @return the stream we are outputting data to + */ protected OutputStream getOutputStream() { return out; } @@ -327,7 +326,11 @@ public class DiffFormatter implements AutoCloseable { return this.newPrefix; } - /** @return true if rename detection is enabled. */ + /** + * Get if rename detection is enabled + * + * @return true if rename detection is enabled + */ public boolean isDetectRenames() { return renameDetector != null; } @@ -351,7 +354,11 @@ public class DiffFormatter implements AutoCloseable { renameDetector = null; } - /** @return the rename detector if rename detection is enabled. */ + /** + * Get rename detector + * + * @return the rename detector if rename detection is enabled + */ public RenameDetector getRenameDetector() { return renameDetector; } @@ -369,9 +376,10 @@ public class DiffFormatter implements AutoCloseable { /** * Set the filter to produce only specific paths. * - * If the filter is an instance of {@link FollowFilter}, the filter path - * will be updated during successive scan or format invocations. The updated - * path can be obtained from {@link #getPathFilter()}. + * If the filter is an instance of + * {@link org.eclipse.jgit.revwalk.FollowFilter}, the filter path will be + * updated during successive scan or format invocations. The updated path + * can be obtained from {@link #getPathFilter()}. * * @param filter * the tree filter to apply. @@ -380,7 +388,11 @@ public class DiffFormatter implements AutoCloseable { pathFilter = filter != null ? filter : TreeFilter.ALL; } - /** @return the current path filter. */ + /** + * Get path filter + * + * @return the current path filter + */ public TreeFilter getPathFilter() { return pathFilter; } @@ -388,7 +400,7 @@ public class DiffFormatter implements AutoCloseable { /** * Flush the underlying output stream of this formatter. * - * @throws IOException + * @throws java.io.IOException * the stream's own flush method threw an exception. */ public void flush() throws IOException { @@ -396,6 +408,8 @@ public class DiffFormatter implements AutoCloseable { } /** + * {@inheritDoc} + * <p> * Release the internal ObjectReader state. * * @since 4.0 @@ -412,8 +426,8 @@ public class DiffFormatter implements AutoCloseable { * * No output is created, instead only the file paths that are different are * returned. Callers may choose to format these paths themselves, or convert - * them into {@link FileHeader} instances with a complete edit list by - * calling {@link #toFileHeader(DiffEntry)}. + * them into {@link org.eclipse.jgit.patch.FileHeader} instances with a + * complete edit list by calling {@link #toFileHeader(DiffEntry)}. * <p> * Either side may be null to indicate that the tree has beed added or * removed. The diff will be computed against nothing. @@ -423,7 +437,7 @@ public class DiffFormatter implements AutoCloseable { * @param b * the new (or updated) side or null * @return the paths that are different. - * @throws IOException + * @throws java.io.IOException * trees cannot be read or file contents cannot be read. */ public List<DiffEntry> scan(AnyObjectId a, AnyObjectId b) @@ -442,8 +456,8 @@ public class DiffFormatter implements AutoCloseable { * * No output is created, instead only the file paths that are different are * returned. Callers may choose to format these paths themselves, or convert - * them into {@link FileHeader} instances with a complete edit list by - * calling {@link #toFileHeader(DiffEntry)}. + * them into {@link org.eclipse.jgit.patch.FileHeader} instances with a + * complete edit list by calling {@link #toFileHeader(DiffEntry)}. * <p> * Either side may be null to indicate that the tree has beed added or * removed. The diff will be computed against nothing. @@ -453,7 +467,7 @@ public class DiffFormatter implements AutoCloseable { * @param b * the new (or updated) side or null * @return the paths that are different. - * @throws IOException + * @throws java.io.IOException * trees cannot be read or file contents cannot be read. */ public List<DiffEntry> scan(RevTree a, RevTree b) throws IOException { @@ -479,15 +493,15 @@ public class DiffFormatter implements AutoCloseable { * * No output is created, instead only the file paths that are different are * returned. Callers may choose to format these paths themselves, or convert - * them into {@link FileHeader} instances with a complete edit list by - * calling {@link #toFileHeader(DiffEntry)}. + * them into {@link org.eclipse.jgit.patch.FileHeader} instances with a + * complete edit list by calling {@link #toFileHeader(DiffEntry)}. * * @param a * the old (or previous) side. * @param b * the new (or updated) side. * @return the paths that are different. - * @throws IOException + * @throws java.io.IOException * trees cannot be read or file contents cannot be read. */ public List<DiffEntry> scan(AbstractTreeIterator a, AbstractTreeIterator b) @@ -599,7 +613,7 @@ public class DiffFormatter implements AutoCloseable { * the old (or previous) side or null * @param b * the new (or updated) side or null - * @throws IOException + * @throws java.io.IOException * trees cannot be read, file contents cannot be read, or the * patch cannot be output. */ @@ -621,7 +635,7 @@ public class DiffFormatter implements AutoCloseable { * the old (or previous) side or null * @param b * the new (or updated) side or null - * @throws IOException + * @throws java.io.IOException * trees cannot be read, file contents cannot be read, or the * patch cannot be output. */ @@ -642,7 +656,7 @@ public class DiffFormatter implements AutoCloseable { * the old (or previous) side or null * @param b * the new (or updated) side or null - * @throws IOException + * @throws java.io.IOException * trees cannot be read, file contents cannot be read, or the * patch cannot be output. */ @@ -658,7 +672,7 @@ public class DiffFormatter implements AutoCloseable { * * @param entries * entries describing the affected files. - * @throws IOException + * @throws java.io.IOException * a file's content cannot be read, or the output stream cannot * be written to. */ @@ -672,7 +686,7 @@ public class DiffFormatter implements AutoCloseable { * * @param ent * the entry to be formatted. - * @throws IOException + * @throws java.io.IOException * a file's content cannot be read, or the output stream cannot * be written to. */ @@ -715,11 +729,13 @@ public class DiffFormatter implements AutoCloseable { * existing file header containing the header lines to copy. * @param a * text source for the pre-image version of the content. This - * must match the content of {@link FileHeader#getOldId()}. + * must match the content of + * {@link org.eclipse.jgit.patch.FileHeader#getOldId()}. * @param b * text source for the post-image version of the content. This - * must match the content of {@link FileHeader#getNewId()}. - * @throws IOException + * must match the content of + * {@link org.eclipse.jgit.patch.FileHeader#getNewId()}. + * @throws java.io.IOException * writing to the supplied stream failed. */ public void format(final FileHeader head, final RawText a, final RawText b) @@ -746,7 +762,7 @@ public class DiffFormatter implements AutoCloseable { * the text A which was compared * @param b * the text B which was compared - * @throws IOException + * @throws java.io.IOException */ public void format(final EditList edits, final RawText a, final RawText b) throws IOException { @@ -794,7 +810,7 @@ public class DiffFormatter implements AutoCloseable { * RawText for accessing raw data * @param line * the line number within text - * @throws IOException + * @throws java.io.IOException */ protected void writeContextLine(final RawText text, final int line) throws IOException { @@ -812,7 +828,7 @@ public class DiffFormatter implements AutoCloseable { * RawText for accessing raw data * @param line * the line number within text - * @throws IOException + * @throws java.io.IOException */ protected void writeAddedLine(final RawText text, final int line) throws IOException { @@ -826,7 +842,7 @@ public class DiffFormatter implements AutoCloseable { * RawText for accessing raw data * @param line * the line number within text - * @throws IOException + * @throws java.io.IOException */ protected void writeRemovedLine(final RawText text, final int line) throws IOException { @@ -844,7 +860,7 @@ public class DiffFormatter implements AutoCloseable { * within second source * @param bEndLine * within second source - * @throws IOException + * @throws java.io.IOException */ protected void writeHunkHeader(int aStartLine, int aEndLine, int bStartLine, int bEndLine) throws IOException { @@ -897,7 +913,7 @@ public class DiffFormatter implements AutoCloseable { * the text object to obtain the line from. * @param cur * line number to output. - * @throws IOException + * @throws java.io.IOException * the stream threw an exception while writing to it. */ protected void writeLine(final char prefix, final RawText text, @@ -908,24 +924,26 @@ public class DiffFormatter implements AutoCloseable { } /** - * Creates a {@link FileHeader} representing the given {@link DiffEntry} + * Creates a {@link org.eclipse.jgit.patch.FileHeader} representing the + * given {@link org.eclipse.jgit.diff.DiffEntry} * <p> * This method does not use the OutputStream associated with this * DiffFormatter instance. It is therefore safe to instantiate this - * DiffFormatter instance with a {@link DisabledOutputStream} if this method - * is the only one that will be used. + * DiffFormatter instance with a + * {@link org.eclipse.jgit.util.io.DisabledOutputStream} if this method is + * the only one that will be used. * * @param ent * the DiffEntry to create the FileHeader for * @return a FileHeader representing the DiffEntry. The FileHeader's buffer * will contain only the header of the diff output. It will also - * contain one {@link HunkHeader}. - * @throws IOException + * contain one {@link org.eclipse.jgit.patch.HunkHeader}. + * @throws java.io.IOException * the stream threw an exception while writing to it, or one of * the blobs referenced by the DiffEntry could not be read. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * one of the blobs referenced by the DiffEntry is corrupt. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * one of the blobs referenced by the DiffEntry is missing. */ public FileHeader toFileHeader(DiffEntry ent) throws IOException, @@ -954,47 +972,50 @@ public class DiffFormatter implements AutoCloseable { // Content not changed (e.g. only mode, pure rename) editList = new EditList(); type = PatchType.UNIFIED; + res.header = new FileHeader(buf.toByteArray(), editList, type); + return res; + } - } else { - assertHaveReader(); - - byte[] aRaw, bRaw; + assertHaveReader(); - if (ent.getOldMode() == GITLINK || ent.getNewMode() == GITLINK) { - aRaw = writeGitLinkText(ent.getOldId()); - bRaw = writeGitLinkText(ent.getNewId()); - } else { + RawText aRaw = null; + RawText bRaw = null; + if (ent.getOldMode() == GITLINK || ent.getNewMode() == GITLINK) { + aRaw = new RawText(writeGitLinkText(ent.getOldId())); + bRaw = new RawText(writeGitLinkText(ent.getNewId())); + } else { + try { aRaw = open(OLD, ent); bRaw = open(NEW, ent); - } - - if (aRaw == BINARY || bRaw == BINARY // - || RawText.isBinary(aRaw) || RawText.isBinary(bRaw)) { + } catch (BinaryBlobException e) { + // Do nothing; we check for null below. formatOldNewPaths(buf, ent); buf.write(encodeASCII("Binary files differ\n")); //$NON-NLS-1$ editList = new EditList(); type = PatchType.BINARY; + res.header = new FileHeader(buf.toByteArray(), editList, type); + return res; + } + } - } else { - res.a = new RawText(aRaw); - res.b = new RawText(bRaw); - editList = diff(res.a, res.b); - type = PatchType.UNIFIED; - - switch (ent.getChangeType()) { - case RENAME: - case COPY: - if (!editList.isEmpty()) - formatOldNewPaths(buf, ent); - break; + res.a = aRaw; + res.b = bRaw; + editList = diff(res.a, res.b); + type = PatchType.UNIFIED; - default: + switch (ent.getChangeType()) { + case RENAME: + case COPY: + if (!editList.isEmpty()) formatOldNewPaths(buf, ent); - break; - } - } + break; + + default: + formatOldNewPaths(buf, ent); + break; } + res.header = new FileHeader(buf.toByteArray(), editList, type); return res; } @@ -1009,13 +1030,13 @@ public class DiffFormatter implements AutoCloseable { } } - private byte[] open(DiffEntry.Side side, DiffEntry entry) - throws IOException { + private RawText open(DiffEntry.Side side, DiffEntry entry) + throws IOException, BinaryBlobException { if (entry.getMode(side) == FileMode.MISSING) - return EMPTY; + return RawText.EMPTY_TEXT; if (entry.getMode(side).getObjectType() != Constants.OBJ_BLOB) - return EMPTY; + return RawText.EMPTY_TEXT; AbbreviatedObjectId id = entry.getId(side); if (!id.isComplete()) { @@ -1036,23 +1057,8 @@ public class DiffFormatter implements AutoCloseable { throw new AmbiguousObjectException(id, ids); } - try { - ObjectLoader ldr = source.open(side, entry); - return ldr.getBytes(binaryFileThreshold); - - } catch (LargeObjectException.ExceedsLimit overLimit) { - return BINARY; - - } catch (LargeObjectException.ExceedsByteArrayLimit overLimit) { - return BINARY; - - } catch (LargeObjectException.OutOfMemory tooBig) { - return BINARY; - - } catch (LargeObjectException tooBig) { - tooBig.setObjectId(id.toObjectId()); - throw tooBig; - } + ObjectLoader ldr = source.open(side, entry); + return RawText.load(ldr, binaryFileThreshold); } /** @@ -1061,12 +1067,12 @@ public class DiffFormatter implements AutoCloseable { * @param o * The stream the formatter will write the first header line to * @param type - * The {@link ChangeType} + * The {@link org.eclipse.jgit.diff.DiffEntry.ChangeType} * @param oldPath * old path to the file * @param newPath * new path to the file - * @throws IOException + * @throws java.io.IOException * the stream threw an exception while writing to it. */ protected void formatGitDiffFirstHeaderLine(ByteArrayOutputStream o, @@ -1151,11 +1157,13 @@ public class DiffFormatter implements AutoCloseable { } /** + * Format index line + * * @param o * the stream the formatter will write line data to * @param ent * the DiffEntry to create the FileHeader for - * @throws IOException + * @throws java.io.IOException * writing to the supplied stream failed. */ protected void formatIndexLine(OutputStream o, DiffEntry ent) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/Edit.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/Edit.java index a2e167fd20..775d11a46b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/Edit.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/Edit.java @@ -118,7 +118,11 @@ public class Edit { endB = be; } - /** @return the type of this region */ + /** + * Get type + * + * @return the type of this region + */ public final Type getType() { if (beginA < endA) { if (beginB < endB) @@ -134,37 +138,66 @@ public class Edit { } } - /** @return true if the edit is empty (lengths of both a and b is zero). */ + /** + * Whether edit is empty + * + * @return {@code true} if the edit is empty (lengths of both a and b is + * zero) + */ public final boolean isEmpty() { return beginA == endA && beginB == endB; } - /** @return start point in sequence A. */ + /** + * Get start point in sequence A + * + * @return start point in sequence A + */ public final int getBeginA() { return beginA; } - /** @return end point in sequence A. */ + /** + * Get end point in sequence A + * + * @return end point in sequence A + */ public final int getEndA() { return endA; } - /** @return start point in sequence B. */ + /** + * Get start point in sequence B + * + * @return start point in sequence B + */ public final int getBeginB() { return beginB; } - /** @return end point in sequence B. */ + /** + * Get end point in sequence B + * + * @return end point in sequence B + */ public final int getEndB() { return endB; } - /** @return length of the region in A. */ + /** + * Get length of the region in A + * + * @return length of the region in A + */ public final int getLengthA() { return endA - beginA; } - /** @return length of the region in B. */ + /** + * Get length of the region in B + * + * @return return length of the region in B + */ public final int getLengthB() { return endB - beginB; } @@ -210,17 +243,23 @@ public class Edit { return new Edit(cut.endA, endA, cut.endB, endB); } - /** Increase {@link #getEndA()} by 1. */ + /** + * Increase {@link #getEndA()} by 1. + */ public void extendA() { endA++; } - /** Increase {@link #getEndB()} by 1. */ + /** + * Increase {@link #getEndB()} by 1. + */ public void extendB() { endB++; } - /** Swap A and B, so the edit goes the other direction. */ + /** + * Swap A and B, so the edit goes the other direction. + */ public void swap() { final int sBegin = beginA; final int sEnd = endA; @@ -232,11 +271,13 @@ public class Edit { endB = sEnd; } + /** {@inheritDoc} */ @Override public int hashCode() { return beginA ^ endA; } + /** {@inheritDoc} */ @Override public boolean equals(final Object o) { if (o instanceof Edit) { @@ -247,6 +288,7 @@ public class Edit { return false; } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/EditList.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/EditList.java index 14f7b4293f..617e0d860f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/EditList.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/EditList.java @@ -45,7 +45,9 @@ package org.eclipse.jgit.diff; import java.util.ArrayList; -/** Specialized list of {@link Edit}s in a document. */ +/** + * Specialized list of {@link org.eclipse.jgit.diff.Edit}s in a document. + */ public class EditList extends ArrayList<Edit> { private static final long serialVersionUID = 1L; @@ -62,7 +64,9 @@ public class EditList extends ArrayList<Edit> { return res; } - /** Create a new, empty edit list. */ + /** + * Create a new, empty edit list. + */ public EditList() { super(16); } @@ -78,6 +82,7 @@ public class EditList extends ArrayList<Edit> { super(capacity); } + /** {@inheritDoc} */ @Override public String toString() { return "EditList" + super.toString(); //$NON-NLS-1$ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/HashedSequence.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/HashedSequence.java index cb1def620f..04921200c2 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/HashedSequence.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/HashedSequence.java @@ -44,13 +44,15 @@ package org.eclipse.jgit.diff; /** - * Wraps a {@link Sequence} to assign hash codes to elements. + * Wraps a {@link org.eclipse.jgit.diff.Sequence} to assign hash codes to + * elements. * <p> * This sequence acts as a proxy for the real sequence, caching element hash * codes so they don't need to be recomputed each time. Sequences of this type - * must be used with a {@link HashedSequenceComparator}. + * must be used with a {@link org.eclipse.jgit.diff.HashedSequenceComparator}. * <p> - * To construct an instance of this type use {@link HashedSequencePair}. + * To construct an instance of this type use + * {@link org.eclipse.jgit.diff.HashedSequencePair}. * * @param <S> * the base sequence type. @@ -65,6 +67,7 @@ public final class HashedSequence<S extends Sequence> extends Sequence { this.hashes = hashes; } + /** {@inheritDoc} */ @Override public int size() { return base.size(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/HashedSequenceComparator.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/HashedSequenceComparator.java index 1ca7fdd9d4..bd9618e0bf 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/HashedSequenceComparator.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/HashedSequenceComparator.java @@ -44,13 +44,16 @@ package org.eclipse.jgit.diff; /** - * Wrap another comparator for use with {@link HashedSequence}. + * Wrap another comparator for use with + * {@link org.eclipse.jgit.diff.HashedSequence}. * <p> * This comparator acts as a proxy for the real comparator, evaluating the * cached hash code before testing the underlying comparator's equality. - * Comparators of this type must be used with a {@link HashedSequence}. + * Comparators of this type must be used with a + * {@link org.eclipse.jgit.diff.HashedSequence}. * <p> - * To construct an instance of this type use {@link HashedSequencePair}. + * To construct an instance of this type use + * {@link org.eclipse.jgit.diff.HashedSequencePair}. * * @param <S> * the base sequence type. @@ -63,6 +66,7 @@ public final class HashedSequenceComparator<S extends Sequence> extends this.cmp = cmp; } + /** {@inheritDoc} */ @Override public boolean equals(HashedSequence<S> a, int ai, // HashedSequence<S> b, int bi) { @@ -70,6 +74,7 @@ public final class HashedSequenceComparator<S extends Sequence> extends && cmp.equals(a.base, ai, b.base, bi); } + /** {@inheritDoc} */ @Override public int hash(HashedSequence<S> seq, int ptr) { return seq.hashes[ptr]; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/HashedSequencePair.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/HashedSequencePair.java index bf6d967c50..8d120155ac 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/HashedSequencePair.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/HashedSequencePair.java @@ -44,7 +44,8 @@ package org.eclipse.jgit.diff; /** - * Wraps two {@link Sequence} instances to cache their element hash codes. + * Wraps two {@link org.eclipse.jgit.diff.Sequence} instances to cache their + * element hash codes. * <p> * This pair wraps two sequences that contain cached hash codes for the input * sequences. @@ -79,19 +80,31 @@ public class HashedSequencePair<S extends Sequence> { this.baseB = b; } - /** @return obtain a comparator that uses the cached hash codes. */ + /** + * Get comparator + * + * @return obtain a comparator that uses the cached hash codes + */ public HashedSequenceComparator<S> getComparator() { return new HashedSequenceComparator<>(cmp); } - /** @return wrapper around A that includes cached hash codes. */ + /** + * Get A + * + * @return wrapper around A that includes cached hash codes + */ public HashedSequence<S> getA() { if (cachedA == null) cachedA = wrap(baseA); return cachedA; } - /** @return wrapper around B that includes cached hash codes. */ + /** + * Get B + * + * @return wrapper around B that includes cached hash codes + */ public HashedSequence<S> getB() { if (cachedB == null) cachedB = wrap(baseB); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/HistogramDiff.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/HistogramDiff.java index 4ef58455a7..c1c6e9a6eb 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/HistogramDiff.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/HistogramDiff.java @@ -85,8 +85,9 @@ import java.util.List; * So long as {@link #setMaxChainLength(int)} is a small constant (such as 64), * the algorithm runs in O(N * D) time, where N is the sum of the input lengths * and D is the number of edits in the resulting EditList. If the supplied - * {@link SequenceComparator} has a good hash function, this implementation - * typically out-performs {@link MyersDiff}, even though its theoretical running + * {@link org.eclipse.jgit.diff.SequenceComparator} has a good hash function, + * this implementation typically out-performs + * {@link org.eclipse.jgit.diff.MyersDiff}, even though its theoretical running * time is the same. * <p> * This implementation has an internal limitation that prevents it from handling @@ -130,6 +131,7 @@ public class HistogramDiff extends LowLevelDiffAlgorithm { maxChainLength = maxLen; } + /** {@inheritDoc} */ @Override public <S extends Sequence> void diffNonCommon(EditList edits, HashedSequenceComparator<S> cmp, HashedSequence<S> a, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/LowLevelDiffAlgorithm.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/LowLevelDiffAlgorithm.java index 55ceec8012..9e5ff25558 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/LowLevelDiffAlgorithm.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/LowLevelDiffAlgorithm.java @@ -43,8 +43,11 @@ package org.eclipse.jgit.diff; -/** Compares two sequences primarily based upon hash codes. */ +/** + * Compares two sequences primarily based upon hash codes. + */ public abstract class LowLevelDiffAlgorithm extends DiffAlgorithm { + /** {@inheritDoc} */ @Override public <S extends Sequence> EditList diffNonCommon( SequenceComparator<? super S> cmp, S a, S b) { @@ -67,10 +70,9 @@ public abstract class LowLevelDiffAlgorithm extends DiffAlgorithm { * proven to have no common starting or ending elements. The expected * elimination of common starting and ending elements is automatically * performed by the {@link #diff(SequenceComparator, Sequence, Sequence)} - * method, which invokes this method using {@link Subsequence}s. + * method, which invokes this method using + * {@link org.eclipse.jgit.diff.Subsequence}s. * - * @param <S> - * type of sequence being compared. * @param edits * result list to append the region's edits onto. * @param cmp @@ -78,11 +80,13 @@ public abstract class LowLevelDiffAlgorithm extends DiffAlgorithm { * @param a * the first (also known as old or pre-image) sequence. Edits * returned by this algorithm will reference indexes using the - * 'A' side: {@link Edit#getBeginA()}, {@link Edit#getEndA()}. + * 'A' side: {@link org.eclipse.jgit.diff.Edit#getBeginA()}, + * {@link org.eclipse.jgit.diff.Edit#getEndA()}. * @param b * the second (also known as new or post-image) sequence. Edits * returned by this algorithm will reference indexes using the - * 'B' side: {@link Edit#getBeginB()}, {@link Edit#getEndB()}. + * 'B' side: {@link org.eclipse.jgit.diff.Edit#getBeginB()}, + * {@link org.eclipse.jgit.diff.Edit#getEndB()}. * @param region * the region being compared within the two sequences. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/MyersDiff.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/MyersDiff.java index a3860de04c..646f264e09 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/MyersDiff.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/MyersDiff.java @@ -557,7 +557,10 @@ if (k < beginK || k > endK) } /** - * @param args two filenames specifying the contents to be diffed + * Main method + * + * @param args + * two filenames specifying the contents to be diffed */ public static void main(String[] args) { if (args.length != 2) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/PatchIdDiffFormatter.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/PatchIdDiffFormatter.java index 146b910401..7f6aa9ab05 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/PatchIdDiffFormatter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/PatchIdDiffFormatter.java @@ -58,7 +58,9 @@ public class PatchIdDiffFormatter extends DiffFormatter { private final MessageDigest digest; - /** Initialize a formatter to compute a patch id. */ + /** + * Initialize a formatter to compute a patch id. + */ public PatchIdDiffFormatter() { super(new DigestOutputStream(NullOutputStream.INSTANCE, Constants.newMessageDigest())); @@ -74,12 +76,14 @@ public class PatchIdDiffFormatter extends DiffFormatter { return ObjectId.fromRaw(digest.digest()); } + /** {@inheritDoc} */ @Override protected void writeHunkHeader(int aStartLine, int aEndLine, int bStartLine, int bEndLine) throws IOException { // The hunk header is not taken into account for patch id calculation } + /** {@inheritDoc} */ @Override protected void formatIndexLine(OutputStream o, DiffEntry ent) throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/RawText.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/RawText.java index 5bfee753a6..7be1659105 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/RawText.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/RawText.java @@ -44,11 +44,15 @@ package org.eclipse.jgit.diff; +import java.io.EOFException; import java.io.File; import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; +import org.eclipse.jgit.errors.BinaryBlobException; +import org.eclipse.jgit.errors.LargeObjectException; +import org.eclipse.jgit.lib.ObjectLoader; import org.eclipse.jgit.util.IO; import org.eclipse.jgit.util.IntList; import org.eclipse.jgit.util.RawParseUtils; @@ -66,7 +70,7 @@ import org.eclipse.jgit.util.RawParseUtils; * they are converting from "line number" to "element index". */ public class RawText extends Sequence { - /** A Rawtext of length 0 */ + /** A RawText of length 0 */ public static final RawText EMPTY_TEXT = new RawText(new byte[0]); /** Number of bytes to check for heuristics in {@link #isBinary(byte[])} */ @@ -99,7 +103,7 @@ public class RawText extends Sequence { * * @param file * the text file. - * @throws IOException + * @throws java.io.IOException * if Exceptions occur while reading the file */ public RawText(File file) throws IOException { @@ -107,6 +111,7 @@ public class RawText extends Sequence { } /** @return total number of items in the sequence. */ + /** {@inheritDoc} */ @Override public int size() { // The line map is always 2 entries larger than the number of lines in @@ -131,7 +136,7 @@ public class RawText extends Sequence { * @param i * index of the line to extract. Note this is 0-based, so line * number 1 is actually index 0. - * @throws IOException + * @throws java.io.IOException * the stream write operation failed. */ public void writeLine(final OutputStream out, final int i) @@ -240,7 +245,7 @@ public class RawText extends Sequence { * @param raw * input stream containing the raw file content. * @return true if raw is likely to be a binary file, false otherwise - * @throws IOException + * @throws java.io.IOException * if input stream could not be read */ public static boolean isBinary(InputStream raw) throws IOException { @@ -295,4 +300,68 @@ public class RawText extends Sequence { else return "\n"; //$NON-NLS-1$ } + + /** + * Read a blob object into RawText, or throw BinaryBlobException if the blob + * is binary. + * + * @param ldr + * the ObjectLoader for the blob + * @param threshold + * if the blob is larger than this size, it is always assumed to + * be binary. + * @since 4.10 + * @return the RawText representing the blob. + * @throws org.eclipse.jgit.errors.BinaryBlobException + * if the blob contains binary data. + * @throws java.io.IOException + * if the input could not be read. + */ + public static RawText load(ObjectLoader ldr, int threshold) throws IOException, BinaryBlobException { + long sz = ldr.getSize(); + + if (sz > threshold) { + throw new BinaryBlobException(); + } + + if (sz <= FIRST_FEW_BYTES) { + byte[] data = ldr.getCachedBytes(FIRST_FEW_BYTES); + if (isBinary(data)) { + throw new BinaryBlobException(); + } + return new RawText(data); + } + + byte[] head = new byte[FIRST_FEW_BYTES]; + try (InputStream stream = ldr.openStream()) { + int off = 0; + int left = head.length; + while (left > 0) { + int n = stream.read(head, off, left); + if (n < 0) { + throw new EOFException(); + } + left -= n; + + while (n > 0) { + if (head[off] == '\0') { + throw new BinaryBlobException(); + } + off++; + n--; + } + } + + byte data[]; + try { + data = new byte[(int)sz]; + } catch (OutOfMemoryError e) { + throw new LargeObjectException.OutOfMemory(e); + } + + System.arraycopy(head, 0, data, 0, head.length); + IO.readFully(stream, data, off, (int) (sz-off)); + return new RawText(data); + } + } } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/RawTextComparator.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/RawTextComparator.java index 2793fa2e8c..ed2eebb858 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/RawTextComparator.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/RawTextComparator.java @@ -50,7 +50,9 @@ import static org.eclipse.jgit.util.RawCharUtil.trimTrailingWhitespace; import org.eclipse.jgit.util.IntList; -/** Equivalence function for {@link RawText}. */ +/** + * Equivalence function for {@link org.eclipse.jgit.diff.RawText}. + */ public abstract class RawTextComparator extends SequenceComparator<RawText> { /** No special treatment. */ public static final RawTextComparator DEFAULT = new RawTextComparator() { @@ -134,7 +136,9 @@ public abstract class RawTextComparator extends SequenceComparator<RawText> { } }; - /** Ignores leading whitespace. */ + /** + * Ignore leading whitespace. + **/ public static final RawTextComparator WS_IGNORE_LEADING = new RawTextComparator() { @Override public boolean equals(RawText a, int ai, RawText b, int bi) { @@ -262,6 +266,7 @@ public abstract class RawTextComparator extends SequenceComparator<RawText> { return hashRegion(seq.content, begin, end); } + /** {@inheritDoc} */ @Override public Edit reduceCommonStartEnd(RawText a, RawText b, Edit e) { // This is a faster exact match based form that tries to improve diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/RenameDetector.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/RenameDetector.java index d899429c3b..7bb217d04d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/RenameDetector.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/RenameDetector.java @@ -65,7 +65,9 @@ import org.eclipse.jgit.lib.ObjectReader; import org.eclipse.jgit.lib.ProgressMonitor; import org.eclipse.jgit.lib.Repository; -/** Detect and resolve object renames. */ +/** + * Detect and resolve object renames. + */ public class RenameDetector { private static final int EXACT_RENAME_SCORE = 100; @@ -156,6 +158,8 @@ public class RenameDetector { } /** + * Get rename score + * * @return minimum score required to pair an add/delete as a rename. The * score ranges are within the bounds of (0, 100). */ @@ -173,7 +177,7 @@ public class RenameDetector { * * @param score * new rename score, must be within [0, 100]. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * the score was not within [0, 100]. */ public void setRenameScore(int score) { @@ -184,6 +188,8 @@ public class RenameDetector { } /** + * Get break score + * * @return the similarity score required to keep modified file pairs * together. Any modify pairs that score below this will be broken * apart into separate add/deletes. Values less than or equal to @@ -195,6 +201,8 @@ public class RenameDetector { } /** + * Set break score + * * @param breakScore * the similarity score required to keep modified file pairs * together. Any modify pairs that score below this will be @@ -206,7 +214,11 @@ public class RenameDetector { this.breakScore = breakScore; } - /** @return limit on number of paths to perform inexact rename detection. */ + /** + * Get rename limit + * + * @return limit on number of paths to perform inexact rename detection + */ public int getRenameLimit() { return renameLimit; } @@ -250,7 +262,7 @@ public class RenameDetector { * * @param entriesToAdd * one or more entries to add. - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * if {@code getEntries} was already invoked. */ public void addAll(Collection<DiffEntry> entriesToAdd) { @@ -290,7 +302,7 @@ public class RenameDetector { * * @param entry * to add. - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * if {@code getEntries} was already invoked. */ public void add(DiffEntry entry) { @@ -302,9 +314,9 @@ public class RenameDetector { * <p> * This convenience function runs without a progress monitor. * - * @return an unmodifiable list of {@link DiffEntry}s representing all files - * that have been changed. - * @throws IOException + * @return an unmodifiable list of {@link org.eclipse.jgit.diff.DiffEntry}s + * representing all files that have been changed. + * @throws java.io.IOException * file contents cannot be read from the repository. */ public List<DiffEntry> compute() throws IOException { @@ -316,9 +328,9 @@ public class RenameDetector { * * @param pm * report progress during the detection phases. - * @return an unmodifiable list of {@link DiffEntry}s representing all files - * that have been changed. - * @throws IOException + * @return an unmodifiable list of {@link org.eclipse.jgit.diff.DiffEntry}s + * representing all files that have been changed. + * @throws java.io.IOException * file contents cannot be read from the repository. */ public List<DiffEntry> compute(ProgressMonitor pm) throws IOException { @@ -339,9 +351,9 @@ public class RenameDetector { * reader to obtain objects from the repository with. * @param pm * report progress during the detection phases. - * @return an unmodifiable list of {@link DiffEntry}s representing all files - * that have been changed. - * @throws IOException + * @return an unmodifiable list of {@link org.eclipse.jgit.diff.DiffEntry}s + * representing all files that have been changed. + * @throws java.io.IOException * file contents cannot be read from the repository. */ public List<DiffEntry> compute(ObjectReader reader, ProgressMonitor pm) @@ -357,9 +369,9 @@ public class RenameDetector { * reader to obtain objects from the repository with. * @param pm * report progress during the detection phases. - * @return an unmodifiable list of {@link DiffEntry}s representing all files - * that have been changed. - * @throws IOException + * @return an unmodifiable list of {@link org.eclipse.jgit.diff.DiffEntry}s + * representing all files that have been changed. + * @throws java.io.IOException * file contents cannot be read from the repository. */ public List<DiffEntry> compute(ContentSource.Pair reader, ProgressMonitor pm) @@ -393,7 +405,9 @@ public class RenameDetector { return Collections.unmodifiableList(entries); } - /** Reset this rename detector for another rename detection pass. */ + /** + * Reset this rename detector for another rename detection pass. + */ public void reset() { entries = new ArrayList<>(); deleted = new ArrayList<>(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/Sequence.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/Sequence.java index 53ab2f96ea..c475132c2b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/Sequence.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/Sequence.java @@ -52,13 +52,19 @@ package org.eclipse.jgit.diff; * Unlike a List, the members of the sequence are not directly obtainable. * <p> * Implementations of Sequence are primarily intended for use in content - * difference detection algorithms, to produce an {@link EditList} of - * {@link Edit} instances describing how two Sequence instances differ. + * difference detection algorithms, to produce an + * {@link org.eclipse.jgit.diff.EditList} of {@link org.eclipse.jgit.diff.Edit} + * instances describing how two Sequence instances differ. * <p> * To be compared against another Sequence of the same type, a supporting - * {@link SequenceComparator} must also be supplied. + * {@link org.eclipse.jgit.diff.SequenceComparator} must also be supplied. */ public abstract class Sequence { /** @return total number of items in the sequence. */ + /** + * Get size + * + * @return size + */ public abstract int size(); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/SequenceComparator.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/SequenceComparator.java index cc38d4b5c0..ccd0055585 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/SequenceComparator.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/SequenceComparator.java @@ -44,7 +44,8 @@ package org.eclipse.jgit.diff; /** - * Equivalence function for a {@link Sequence} compared by difference algorithm. + * Equivalence function for a {@link org.eclipse.jgit.diff.Sequence} compared by + * difference algorithm. * <p> * Difference algorithms can use a comparator to compare portions of two * sequences and discover the minimal edits required to transform from one diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/SimilarityIndex.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/SimilarityIndex.java index 1c40d7fcbf..8b4d2ec8fc 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/SimilarityIndex.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/SimilarityIndex.java @@ -56,8 +56,9 @@ import org.eclipse.jgit.lib.ObjectStream; * Index structure of lines/blocks in one file. * <p> * This structure can be used to compute an approximation of the similarity - * between two files. The index is used by {@link SimilarityRenameDetector} to - * compute scores between files. + * between two files. The index is used by + * {@link org.eclipse.jgit.diff.SimilarityRenameDetector} to compute scores + * between files. * <p> * To save space in memory, this index uses a space efficient encoding which * will not exceed 1 MiB per instance. The index starts out at a smaller size @@ -114,9 +115,9 @@ public class SimilarityIndex { * @param obj * the object to hash * @return similarity index for this object - * @throws IOException + * @throws java.io.IOException * file contents cannot be read from the repository. - * @throws TableFullException + * @throws org.eclipse.jgit.diff.SimilarityIndex.TableFullException * object hashing overflowed the storage capacity of the * SimilarityIndex. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/Subsequence.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/Subsequence.java index 50ca613cca..aa10f6c9ba 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/Subsequence.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/Subsequence.java @@ -44,11 +44,12 @@ package org.eclipse.jgit.diff; /** - * Wraps a {@link Sequence} to have a narrower range of elements. + * Wraps a {@link org.eclipse.jgit.diff.Sequence} to have a narrower range of + * elements. * <p> * This sequence acts as a proxy for the real sequence, translating element * indexes on the fly by adding {@code begin} to them. Sequences of this type - * must be used with a {@link SubsequenceComparator}. + * must be used with a {@link org.eclipse.jgit.diff.SubsequenceComparator}. * * @param <S> * the base sequence type. @@ -57,8 +58,6 @@ public final class Subsequence<S extends Sequence> extends Sequence { /** * Construct a subsequence around the A region/base sequence. * - * @param <S> - * the base sequence type. * @param a * the A sequence. * @param region @@ -72,8 +71,6 @@ public final class Subsequence<S extends Sequence> extends Sequence { /** * Construct a subsequence around the B region/base sequence. * - * @param <S> - * the base sequence type. * @param b * the B sequence. * @param region @@ -87,8 +84,6 @@ public final class Subsequence<S extends Sequence> extends Sequence { /** * Adjust the Edit to reflect positions in the base sequence. * - * @param <S> - * the base sequence type. * @param e * edit to adjust in-place. Prior to invocation the indexes are * in terms of the two subsequences; after invocation the indexes @@ -110,8 +105,6 @@ public final class Subsequence<S extends Sequence> extends Sequence { /** * Adjust the Edits to reflect positions in the base sequence. * - * @param <S> - * the base sequence type. * @param edits * edits to adjust in-place. Prior to invocation the indexes are * in terms of the two subsequences; after invocation the indexes @@ -156,6 +149,7 @@ public final class Subsequence<S extends Sequence> extends Sequence { this.size = end - begin; } + /** {@inheritDoc} */ @Override public int size() { return size; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/diff/SubsequenceComparator.java b/org.eclipse.jgit/src/org/eclipse/jgit/diff/SubsequenceComparator.java index dff2a429e1..9b3889b305 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/diff/SubsequenceComparator.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/diff/SubsequenceComparator.java @@ -44,11 +44,13 @@ package org.eclipse.jgit.diff; /** - * Wrap another comparator for use with {@link Subsequence}. + * Wrap another comparator for use with + * {@link org.eclipse.jgit.diff.Subsequence}. * <p> * This comparator acts as a proxy for the real comparator, translating element * indexes on the fly by adding the subsequence's begin offset to them. - * Comparators of this type must be used with a {@link Subsequence}. + * Comparators of this type must be used with a + * {@link org.eclipse.jgit.diff.Subsequence}. * * @param <S> * the base sequence type. @@ -67,11 +69,13 @@ public final class SubsequenceComparator<S extends Sequence> extends this.cmp = cmp; } + /** {@inheritDoc} */ @Override public boolean equals(Subsequence<S> a, int ai, Subsequence<S> b, int bi) { return cmp.equals(a.base, ai + a.begin, b.base, bi + b.begin); } + /** {@inheritDoc} */ @Override public int hash(Subsequence<S> seq, int ptr) { return cmp.hash(seq.base, ptr + seq.begin); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/BaseDirCacheEditor.java b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/BaseDirCacheEditor.java index 0fbc1f8acf..0228f4d3cc 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/BaseDirCacheEditor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/BaseDirCacheEditor.java @@ -91,6 +91,8 @@ abstract class BaseDirCacheEditor { } /** + * Get the {@code DirCache} + * * @return the cache we will update on {@link #finish()}. */ public DirCache getDirCache() { @@ -152,7 +154,8 @@ abstract class BaseDirCacheEditor { } /** - * Finish this builder and update the destination {@link DirCache}. + * Finish this builder and update the destination + * {@link org.eclipse.jgit.dircache.DirCache}. * <p> * When this method completes this builder instance is no longer usable by * the calling application. A new builder must be created to make additional @@ -263,9 +266,9 @@ abstract class BaseDirCacheEditor { * @return true if the commit was successful and the file contains the new * data; false if the commit failed and the file remains with the * old data. - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * the lock is not held. - * @throws IOException + * @throws java.io.IOException * the output file could not be created. The caller no longer * holds the lock. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCache.java b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCache.java index ce52fedcb3..cc431dbdf2 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCache.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCache.java @@ -158,7 +158,7 @@ public class DirCache { * tree to read. Must identify a tree, not a tree-ish. * @return a new cache which has no backing store file, but contains the * contents of {@code treeId}. - * @throws IOException + * @throws java.io.IOException * one or more trees not available from the ObjectReader. * @since 4.2 */ @@ -182,9 +182,9 @@ public class DirCache { * repository containing the index to read * @return a cache representing the contents of the specified index file (if * it exists) or an empty cache if the file does not exist. - * @throws IOException + * @throws java.io.IOException * the index file is present but could not be read. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the index file is using a format or extension that this * library does not support. */ @@ -209,9 +209,9 @@ public class DirCache { * certain file system operations. * @return a cache representing the contents of the specified index file (if * it exists) or an empty cache if the file does not exist. - * @throws IOException + * @throws java.io.IOException * the index file is present but could not be read. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the index file is using a format or extension that this * library does not support. */ @@ -237,10 +237,10 @@ public class DirCache { * certain file system operations. * @return a cache representing the contents of the specified index file (if * it exists) or an empty cache if the file does not exist. - * @throws IOException + * @throws java.io.IOException * the index file is present but could not be read, or the lock * could not be obtained. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the index file is using a format or extension that this * library does not support. */ @@ -280,10 +280,10 @@ public class DirCache { * listener to be informed when DirCache is committed * @return a cache representing the contents of the specified index file (if * it exists) or an empty cache if the file does not exist. - * @throws IOException + * @throws java.io.IOException * the index file is present but could not be read, or the lock * could not be obtained. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the index file is using a format or extension that this * library does not support. * @since 2.0 @@ -314,10 +314,10 @@ public class DirCache { * listener to be informed when DirCache is committed * @return a cache representing the contents of the specified index file (if * it exists) or an empty cache if the file does not exist. - * @throws IOException + * @throws java.io.IOException * the index file is present but could not be read, or the lock * could not be obtained. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the index file is using a format or extension that this * library does not support. */ @@ -381,7 +381,8 @@ public class DirCache { * Create a new builder to update this cache. * <p> * Callers should add all entries to the builder, then use - * {@link DirCacheBuilder#finish()} to update this instance. + * {@link org.eclipse.jgit.dircache.DirCacheBuilder#finish()} to update this + * instance. * * @return a new builder instance for this cache. */ @@ -393,7 +394,8 @@ public class DirCache { * Create a new editor to recreate this cache. * <p> * Callers should add commands to the editor, then use - * {@link DirCacheEditor#finish()} to update this instance. + * {@link org.eclipse.jgit.dircache.DirCacheEditor#finish()} to update this + * instance. * * @return a new builder instance for this cache. */ @@ -414,10 +416,10 @@ public class DirCache { * the last time we consulted it. A missing index file will be treated as * though it were present but had no file entries in it. * - * @throws IOException + * @throws java.io.IOException * the index file is present but could not be read. This * DirCache instance may not be populated correctly. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the index file is using a format or extension that this * library does not support. */ @@ -456,8 +458,10 @@ public class DirCache { } /** - * @return true if the memory state differs from the index file - * @throws IOException + * Whether the memory state differs from the index file + * + * @return {@code true} if the memory state differs from the index file + * @throws java.io.IOException */ public boolean isOutdated() throws IOException { if (liveFile == null || !liveFile.exists()) @@ -465,7 +469,9 @@ public class DirCache { return snapshot == null || snapshot.isModified(liveFile); } - /** Empty this index, removing all entries. */ + /** + * Empty this index, removing all entries. + */ public void clear() { snapshot = null; sortedEntries = NO_ENTRIES; @@ -601,7 +607,7 @@ public class DirCache { * * @return true if the lock is now held by the caller; false if it is held * by someone else. - * @throws IOException + * @throws java.io.IOException * the output file could not be created. The caller does not * hold the lock. */ @@ -628,7 +634,7 @@ public class DirCache { * Once written the lock is closed and must be either committed with * {@link #commit()} or rolled back with {@link #unlock()}. * - * @throws IOException + * @throws java.io.IOException * the output file could not be created. The caller no longer * holds the lock. */ @@ -655,8 +661,12 @@ public class DirCache { final DigestOutputStream dos = new DigestOutputStream(os, foot); boolean extended = false; - for (int i = 0; i < entryCnt; i++) - extended |= sortedEntries[i].isExtended(); + for (int i = 0; i < entryCnt; i++) { + if (sortedEntries[i].isExtended()) { + extended = true; + break; + } + } // Write the header. // @@ -726,7 +736,7 @@ public class DirCache { * @return true if the commit was successful and the file contains the new * data; false if the commit failed and the file remains with the * old data. - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * the lock is not held. */ public boolean commit() { @@ -953,13 +963,13 @@ public class DirCache { * responsible for flushing the inserter before trying to use the * returned tree identity. * @return identity for the root tree. - * @throws UnmergedPathException + * @throws org.eclipse.jgit.errors.UnmergedPathException * one or more paths contain higher-order stages (stage > 0), * which cannot be stored in a tree object. - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * one or more paths contain an invalid mode which should never * appear in a tree object. - * @throws IOException + * @throws java.io.IOException * an unexpected error occurred writing to the object store. */ public ObjectId writeTree(final ObjectInserter ow) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheBuildIterator.java b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheBuildIterator.java index c10e416082..6e3682a3e2 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheBuildIterator.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheBuildIterator.java @@ -54,12 +54,14 @@ import org.eclipse.jgit.lib.ObjectReader; import org.eclipse.jgit.treewalk.AbstractTreeIterator; /** - * Iterate and update a {@link DirCache} as part of a <code>TreeWalk</code>. + * Iterate and update a {@link org.eclipse.jgit.dircache.DirCache} as part of a + * <code>TreeWalk</code>. * <p> - * Like {@link DirCacheIterator} this iterator allows a DirCache to be used in - * parallel with other sorts of iterators in a TreeWalk. However any entry which - * appears in the source DirCache and which is skipped by the TreeFilter is - * automatically copied into {@link DirCacheBuilder}, thus retaining it in the + * Like {@link org.eclipse.jgit.dircache.DirCacheIterator} this iterator allows + * a DirCache to be used in parallel with other sorts of iterators in a + * TreeWalk. However any entry which appears in the source DirCache and which is + * skipped by the TreeFilter is automatically copied into + * {@link org.eclipse.jgit.dircache.DirCacheBuilder}, thus retaining it in the * newly updated index. * <p> * This iterator is suitable for update processes, or even a simple delete @@ -105,6 +107,7 @@ public class DirCacheBuildIterator extends DirCacheIterator { builder = p.builder; } + /** {@inheritDoc} */ @Override public AbstractTreeIterator createSubtreeIterator(final ObjectReader reader) throws IncorrectObjectTypeException, IOException { @@ -114,6 +117,7 @@ public class DirCacheBuildIterator extends DirCacheIterator { return new DirCacheBuildIterator(this, currentSubtree); } + /** {@inheritDoc} */ @Override public void skip() throws CorruptObjectException { if (currentSubtree != null) @@ -123,6 +127,7 @@ public class DirCacheBuildIterator extends DirCacheIterator { next(1); } + /** {@inheritDoc} */ @Override public void stopWalk() { final int cur = ptr; @@ -131,6 +136,7 @@ public class DirCacheBuildIterator extends DirCacheIterator { builder.keep(cur, cnt - cur); } + /** {@inheritDoc} */ @Override protected boolean needsStopWalk() { return ptr < cache.getEntryCount(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheBuilder.java b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheBuilder.java index 676a6ab9c4..2ff7bb9aea 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheBuilder.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheBuilder.java @@ -57,7 +57,8 @@ import org.eclipse.jgit.lib.ObjectReader; import org.eclipse.jgit.treewalk.CanonicalTreeParser; /** - * Updates a {@link DirCache} by adding individual {@link DirCacheEntry}s. + * Updates a {@link org.eclipse.jgit.dircache.DirCache} by adding individual + * {@link org.eclipse.jgit.dircache.DirCacheEntry}s. * <p> * A builder always starts from a clean slate and appends in every single * <code>DirCacheEntry</code> which the final updated index must have to reflect @@ -98,7 +99,7 @@ public class DirCacheBuilder extends BaseDirCacheEditor { * * @param newEntry * the new entry to add. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * If the FileMode of the entry was not set by the caller. */ public void add(final DirCacheEntry newEntry) { @@ -161,7 +162,7 @@ public class DirCacheBuilder extends BaseDirCacheEditor { * under <code>pathPrefix</code>. The ObjectId must be that of a * tree; the caller is responsible for dereferencing a tag or * commit (if necessary). - * @throws IOException + * @throws java.io.IOException * a tree cannot be read to iterate through its entries. */ public void addTree(byte[] pathPrefix, int stage, ObjectReader reader, @@ -218,6 +219,7 @@ public class DirCacheBuilder extends BaseDirCacheEditor { return e; } + /** {@inheritDoc} */ @Override public void finish() { if (!sorted) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheCheckout.java b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheCheckout.java index a6ab9c8921..d41a1f57fb 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheCheckout.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheCheckout.java @@ -42,6 +42,8 @@ package org.eclipse.jgit.dircache; +import static org.eclipse.jgit.treewalk.TreeWalk.OperationType.CHECKOUT_OP; + import java.io.File; import java.io.FileOutputStream; import java.io.IOException; @@ -157,6 +159,8 @@ public class DirCacheCheckout { private boolean performingCheckout; /** + * Get list of updated paths and smudgeFilterCommands + * * @return a list of updated paths and smudgeFilterCommands */ public Map<String, CheckoutMetadata> getUpdated() { @@ -164,6 +168,8 @@ public class DirCacheCheckout { } /** + * Get a list of conflicts created by this checkout + * * @return a list of conflicts created by this checkout */ public List<String> getConflicts() { @@ -171,19 +177,24 @@ public class DirCacheCheckout { } /** + * Get list of paths of files which couldn't be deleted during last call to + * {@link #checkout()} + * * @return a list of paths (relative to the start of the working tree) of * files which couldn't be deleted during last call to * {@link #checkout()} . {@link #checkout()} detected that these * files should be deleted but the deletion in the filesystem failed * (e.g. because a file was locked). To have a consistent state of * the working tree these files have to be deleted by the callers of - * {@link DirCacheCheckout}. + * {@link org.eclipse.jgit.dircache.DirCacheCheckout}. */ public List<String> getToBeDeleted() { return toBeDeleted; } /** + * Get list of all files removed by this checkout + * * @return a list of all files removed by this checkout */ public List<String> getRemoved() { @@ -204,7 +215,7 @@ public class DirCacheCheckout { * the id of the tree we want to fast-forward to * @param workingTree * an iterator over the repositories Working Tree - * @throws IOException + * @throws java.io.IOException */ public DirCacheCheckout(Repository repo, ObjectId headCommitTree, DirCache dc, ObjectId mergeCommitTree, WorkingTreeIterator workingTree) @@ -220,7 +231,8 @@ public class DirCacheCheckout { /** * Constructs a DirCacheCeckout for merging and checking out two trees (HEAD * and mergeCommitTree) and the index. As iterator over the working tree - * this constructor creates a standard {@link FileTreeIterator} + * this constructor creates a standard + * {@link org.eclipse.jgit.treewalk.FileTreeIterator} * * @param repo * the repository in which we do the checkout @@ -230,7 +242,7 @@ public class DirCacheCheckout { * the (already locked) Dircache for this repo * @param mergeCommitTree * the id of the tree we want to fast-forward to - * @throws IOException + * @throws java.io.IOException */ public DirCacheCheckout(Repository repo, ObjectId headCommitTree, DirCache dc, ObjectId mergeCommitTree) throws IOException { @@ -249,7 +261,7 @@ public class DirCacheCheckout { * the id of the tree we want to fast-forward to * @param workingTree * an iterator over the repositories Working Tree - * @throws IOException + * @throws java.io.IOException */ public DirCacheCheckout(Repository repo, DirCache dc, ObjectId mergeCommitTree, WorkingTreeIterator workingTree) @@ -260,7 +272,7 @@ public class DirCacheCheckout { /** * Constructs a DirCacheCeckout for checking out one tree, merging with the * index. As iterator over the working tree this constructor creates a - * standard {@link FileTreeIterator} + * standard {@link org.eclipse.jgit.treewalk.FileTreeIterator} * * @param repo * the repository in which we do the checkout @@ -268,7 +280,7 @@ public class DirCacheCheckout { * the (already locked) Dircache for this repo * @param mergeCommitTree * the id of the tree of the - * @throws IOException + * @throws java.io.IOException */ public DirCacheCheckout(Repository repo, DirCache dc, ObjectId mergeCommitTree) throws IOException { @@ -279,8 +291,8 @@ public class DirCacheCheckout { * Scan head, index and merge tree. Used during normal checkout or merge * operations. * - * @throws CorruptObjectException - * @throws IOException + * @throws org.eclipse.jgit.errors.CorruptObjectException + * @throws java.io.IOException */ public void preScanTwoTrees() throws CorruptObjectException, IOException { removed.clear(); @@ -316,10 +328,10 @@ public class DirCacheCheckout { * Scan index and merge tree (no HEAD). Used e.g. for initial checkout when * there is no head yet. * - * @throws MissingObjectException - * @throws IncorrectObjectTypeException - * @throws CorruptObjectException - * @throws IOException + * @throws org.eclipse.jgit.errors.MissingObjectException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.CorruptObjectException + * @throws java.io.IOException */ public void prescanOneTree() throws MissingObjectException, IncorrectObjectTypeException, @@ -437,7 +449,8 @@ public class DirCacheCheckout { } /** - * Execute this checkout. A {@link WorkingTreeModifiedEvent} is fired if the + * Execute this checkout. A + * {@link org.eclipse.jgit.events.WorkingTreeModifiedEvent} is fired if the * working tree was modified; even if the checkout fails. * * @return <code>false</code> if this method could not delete all the files @@ -447,8 +460,7 @@ public class DirCacheCheckout { * Although <code>false</code> is returned the checkout was * successful and the working tree was updated for all other files. * <code>true</code> is returned when no such problem occurred - * - * @throws IOException + * @throws java.io.IOException */ public boolean checkout() throws IOException { try { @@ -1148,7 +1160,8 @@ public class DirCacheCheckout { private void update(String path, ObjectId mId, FileMode mode) throws IOException { if (!FileMode.TREE.equals(mode)) { - updated.put(path, new CheckoutMetadata(walk.getEolStreamType(), + updated.put(path, new CheckoutMetadata( + walk.getEolStreamType(CHECKOUT_OP), walk.getFilterCommand(Constants.ATTR_FILTER_TYPE_SMUDGE))); DirCacheEntry entry = new DirCacheEntry(path, DirCacheEntry.STAGE_0); @@ -1160,10 +1173,12 @@ public class DirCacheCheckout { /** * If <code>true</code>, will scan first to see if it's possible to check - * out, otherwise throw {@link CheckoutConflictException}. If + * out, otherwise throw + * {@link org.eclipse.jgit.errors.CheckoutConflictException}. If * <code>false</code>, it will silently deal with the problem. * * @param failOnConflict + * a boolean. */ public void setFailOnConflict(boolean failOnConflict) { this.failOnConflict = failOnConflict; @@ -1283,8 +1298,8 @@ public class DirCacheCheckout { * <p> * <b>Note:</b> if the entry path on local file system exists as a non-empty * directory, and the target entry type is a link or file, the checkout will - * fail with {@link IOException} since existing non-empty directory cannot - * be renamed to file or link without deleting it recursively. + * fail with {@link java.io.IOException} since existing non-empty directory + * cannot be renamed to file or link without deleting it recursively. * </p> * * <p> @@ -1299,7 +1314,7 @@ public class DirCacheCheckout { * the entry containing new mode and content * @param or * object reader to use for checkout - * @throws IOException + * @throws java.io.IOException * @since 3.6 */ public static void checkoutEntry(Repository repo, DirCacheEntry entry, @@ -1341,8 +1356,7 @@ public class DirCacheCheckout { * checked out</li> * <li>eolStreamType used for stream conversion</li> * </ul> - * - * @throws IOException + * @throws java.io.IOException * @since 4.2 */ public static void checkoutEntry(Repository repo, DirCacheEntry entry, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheEditor.java b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheEditor.java index 22bedcf91b..30e3a3cf12 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheEditor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheEditor.java @@ -60,14 +60,16 @@ import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.util.Paths; /** - * Updates a {@link DirCache} by supplying discrete edit commands. + * Updates a {@link org.eclipse.jgit.dircache.DirCache} by supplying discrete + * edit commands. * <p> - * An editor updates a DirCache by taking a list of {@link PathEdit} commands - * and executing them against the entries of the destination cache to produce a - * new cache. This edit style allows applications to insert a few commands and - * then have the editor compute the proper entry indexes necessary to perform an + * An editor updates a DirCache by taking a list of + * {@link org.eclipse.jgit.dircache.DirCacheEditor.PathEdit} commands and + * executing them against the entries of the destination cache to produce a new + * cache. This edit style allows applications to insert a few commands and then + * have the editor compute the proper entry indexes necessary to perform an * efficient in-order update of the index records. This can be easier to use - * than {@link DirCacheBuilder}. + * than {@link org.eclipse.jgit.dircache.DirCacheBuilder}. * <p> * * @see DirCacheBuilder @@ -113,6 +115,7 @@ public class DirCacheEditor extends BaseDirCacheEditor { edits.add(edit); } + /** {@inheritDoc} */ @Override public boolean commit() throws IOException { if (edits.isEmpty()) { @@ -124,6 +127,7 @@ public class DirCacheEditor extends BaseDirCacheEditor { return super.commit(); } + /** {@inheritDoc} */ @Override public void finish() { if (!edits.isEmpty()) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheEntry.java b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheEntry.java index 4ebf2e0d71..7c03c64946 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheEntry.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheEntry.java @@ -68,7 +68,8 @@ import org.eclipse.jgit.util.NB; import org.eclipse.jgit.util.SystemReader; /** - * A single file (or stage of a file) in a {@link DirCache}. + * A single file (or stage of a file) in a + * {@link org.eclipse.jgit.dircache.DirCache}. * <p> * An entry represents exactly one stage of a file. If a file path is unmerged * then multiple DirCacheEntry instances may appear for the same path name. @@ -221,7 +222,7 @@ public class DirCacheEntry { * * @param newPath * name of the cache entry. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * If the path starts or ends with "/", or contains "//" either * "\0". These sequences are not permitted in a git tree object * or DirCache file. @@ -237,7 +238,7 @@ public class DirCacheEntry { * name of the cache entry. * @param stage * the stage index of the new entry. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * If the path starts or ends with "/", or contains "//" either * "\0". These sequences are not permitted in a git tree object * or DirCache file. Or if {@code stage} is outside of the @@ -252,7 +253,7 @@ public class DirCacheEntry { * * @param newPath * name of the cache entry, in the standard encoding. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * If the path starts or ends with "/", or contains "//" either * "\0". These sequences are not permitted in a git tree object * or DirCache file. @@ -268,7 +269,7 @@ public class DirCacheEntry { * name of the cache entry, in the standard encoding. * @param stage * the stage index of the new entry. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * If the path starts or ends with "/", or contains "//" either * "\0". These sequences are not permitted in a git tree object * or DirCache file. Or if {@code stage} is outside of the @@ -378,8 +379,9 @@ public class DirCacheEntry { /** * Check whether this entry has been smudged or not * <p> - * If a blob has length 0 we know his id see {@link Constants#EMPTY_BLOB_ID}. If an entry - * has length 0 and an ID different from the one for empty blob we know this + * If a blob has length 0 we know its id, see + * {@link org.eclipse.jgit.lib.Constants#EMPTY_BLOB_ID}. If an entry has + * length 0 and an ID different from the one for empty blob we know this * entry was smudged. * * @return <code>true</code> if the entry is smudged, <code>false</code> @@ -426,7 +428,9 @@ public class DirCacheEntry { } /** - * @return true if this entry should be checked for changes + * Whether this entry should be checked for changes + * + * @return {@code true} if this entry should be checked for changes */ public boolean isUpdateNeeded() { return (inCoreFlags & UPDATE_NEEDED) != 0; @@ -436,6 +440,7 @@ public class DirCacheEntry { * Set whether this entry must be checked for changes * * @param updateNeeded + * whether this entry must be checked for changes */ public void setUpdateNeeded(boolean updateNeeded) { if (updateNeeded) @@ -484,7 +489,7 @@ public class DirCacheEntry { } /** - * Obtain the raw {@link FileMode} bits for this entry. + * Obtain the raw {@link org.eclipse.jgit.lib.FileMode} bits for this entry. * * @return mode bits for the entry. * @see FileMode#fromBits(int) @@ -494,7 +499,7 @@ public class DirCacheEntry { } /** - * Obtain the {@link FileMode} for this entry. + * Obtain the {@link org.eclipse.jgit.lib.FileMode} for this entry. * * @return the file mode singleton for this entry. */ @@ -507,10 +512,11 @@ public class DirCacheEntry { * * @param mode * the new mode constant. - * @throws IllegalArgumentException - * If {@code mode} is {@link FileMode#MISSING}, - * {@link FileMode#TREE}, or any other type code not permitted - * in a tree object. + * @throws java.lang.IllegalArgumentException + * If {@code mode} is + * {@link org.eclipse.jgit.lib.FileMode#MISSING}, + * {@link org.eclipse.jgit.lib.FileMode#TREE}, or any other type + * code not permitted in a tree object. */ public void setFileMode(final FileMode mode) { switch (mode.getBits() & FileMode.TYPE_MASK) { @@ -629,7 +635,8 @@ public class DirCacheEntry { * * @param id * new object identifier for the entry. May be - * {@link ObjectId#zeroId()} to remove the current identifier. + * {@link org.eclipse.jgit.lib.ObjectId#zeroId()} to remove the + * current identifier. */ public void setObjectId(final AnyObjectId id) { id.copyRawTo(idBuffer(), idOffset()); @@ -676,6 +683,8 @@ public class DirCacheEntry { } /** + * {@inheritDoc} + * <p> * Use for debugging only ! */ @SuppressWarnings("nls") diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheIterator.java b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheIterator.java index ad93f7213f..68521d3981 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheIterator.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheIterator.java @@ -61,7 +61,8 @@ import org.eclipse.jgit.treewalk.EmptyTreeIterator; import org.eclipse.jgit.util.RawParseUtils; /** - * Iterate a {@link DirCache} as part of a <code>TreeWalk</code>. + * Iterate a {@link org.eclipse.jgit.dircache.DirCache} as part of a + * <code>TreeWalk</code>. * <p> * This is an iterator to adapt a loaded <code>DirCache</code> instance (such as * read from an existing <code>.git/index</code> file) to the tree structure @@ -134,6 +135,7 @@ public class DirCacheIterator extends AbstractTreeIterator { parseEntry(); } + /** {@inheritDoc} */ @Override public AbstractTreeIterator createSubtreeIterator(final ObjectReader reader) throws IncorrectObjectTypeException, IOException { @@ -143,6 +145,7 @@ public class DirCacheIterator extends AbstractTreeIterator { return new DirCacheIterator(this, currentSubtree); } + /** {@inheritDoc} */ @Override public EmptyTreeIterator createEmptyTreeIterator() { final byte[] n = new byte[Math.max(pathLen + 1, DEFAULT_PATH_SIZE)]; @@ -151,6 +154,7 @@ public class DirCacheIterator extends AbstractTreeIterator { return new EmptyTreeIterator(this, n, pathLen + 1); } + /** {@inheritDoc} */ @Override public boolean hasId() { if (currentSubtree != null) @@ -158,6 +162,7 @@ public class DirCacheIterator extends AbstractTreeIterator { return currentEntry != null; } + /** {@inheritDoc} */ @Override public byte[] idBuffer() { if (currentSubtree != null) @@ -167,6 +172,7 @@ public class DirCacheIterator extends AbstractTreeIterator { return zeroid; } + /** {@inheritDoc} */ @Override public int idOffset() { if (currentSubtree != null) @@ -176,6 +182,7 @@ public class DirCacheIterator extends AbstractTreeIterator { return 0; } + /** {@inheritDoc} */ @Override public void reset() { if (!first()) { @@ -188,16 +195,19 @@ public class DirCacheIterator extends AbstractTreeIterator { } } + /** {@inheritDoc} */ @Override public boolean first() { return ptr == treeStart; } + /** {@inheritDoc} */ @Override public boolean eof() { return ptr == treeEnd; } + /** {@inheritDoc} */ @Override public void next(int delta) { while (--delta >= 0) { @@ -211,6 +221,7 @@ public class DirCacheIterator extends AbstractTreeIterator { } } + /** {@inheritDoc} */ @Override public void back(int delta) { while (--delta >= 0) { @@ -282,12 +293,15 @@ public class DirCacheIterator extends AbstractTreeIterator { } /** - * Retrieves the {@link AttributesNode} for the current entry. + * Retrieves the {@link org.eclipse.jgit.attributes.AttributesNode} for the + * current entry. * * @param reader - * {@link ObjectReader} used to parse the .gitattributes entry. - * @return {@link AttributesNode} for the current entry. - * @throws IOException + * {@link org.eclipse.jgit.lib.ObjectReader} used to parse the + * .gitattributes entry. + * @return {@link org.eclipse.jgit.attributes.AttributesNode} for the + * current entry. + * @throws java.io.IOException * @since 3.7 */ public AttributesNode getEntryAttributesNode(ObjectReader reader) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheTree.java b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheTree.java index a06f9d3f4f..dc825d4dc7 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheTree.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheTree.java @@ -62,13 +62,14 @@ import org.eclipse.jgit.util.MutableInteger; import org.eclipse.jgit.util.RawParseUtils; /** - * Single tree record from the 'TREE' {@link DirCache} extension. + * Single tree record from the 'TREE' {@link org.eclipse.jgit.dircache.DirCache} + * extension. * <p> * A valid cache tree record contains the object id of a tree object and the - * total number of {@link DirCacheEntry} instances (counted recursively) from - * the DirCache contained within the tree. This information facilitates faster - * traversal of the index and quicker generation of tree objects prior to - * creating a new commit. + * total number of {@link org.eclipse.jgit.dircache.DirCacheEntry} instances + * (counted recursively) from the DirCache contained within the tree. This + * information facilitates faster traversal of the index and quicker generation + * of tree objects prior to creating a new commit. * <p> * An invalid cache tree record indicates a known subtree whose file entries * have changed in ways that cause the tree to no longer have a known object id. @@ -205,10 +206,11 @@ public class DirCacheTree { /** * Determine if this cache is currently valid. * <p> - * A valid cache tree knows how many {@link DirCacheEntry} instances from - * the parent {@link DirCache} reside within this tree (recursively - * enumerated). It also knows the object id of the tree, as the tree should - * be readily available from the repository's object database. + * A valid cache tree knows how many + * {@link org.eclipse.jgit.dircache.DirCacheEntry} instances from the parent + * {@link org.eclipse.jgit.dircache.DirCache} reside within this tree + * (recursively enumerated). It also knows the object id of the tree, as the + * tree should be readily available from the repository's object database. * * @return true if this tree is knows key details about itself; false if the * tree needs to be regenerated. @@ -563,6 +565,7 @@ public class DirCacheTree { return -1; } + /** {@inheritDoc} */ @Override public String toString() { return getNameString(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/InvalidPathException.java b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/InvalidPathException.java index 50d1c4ca38..7e81b8b037 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/InvalidPathException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/InvalidPathException.java @@ -57,7 +57,10 @@ public class InvalidPathException extends IllegalArgumentException { private static final long serialVersionUID = 1L; /** + * Constructor for InvalidPathException + * * @param path + * the invalid path */ public InvalidPathException(String path) { this(JGitText.get().invalidPath, path); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/AmbiguousObjectException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/AmbiguousObjectException.java index 93d57f01ae..389ec45d19 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/AmbiguousObjectException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/AmbiguousObjectException.java @@ -51,7 +51,9 @@ import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.lib.AbbreviatedObjectId; import org.eclipse.jgit.lib.ObjectId; -/** An {@link AbbreviatedObjectId} cannot be extended. */ +/** + * An {@link org.eclipse.jgit.lib.AbbreviatedObjectId} cannot be extended. + */ public class AmbiguousObjectException extends IOException { private static final long serialVersionUID = 1L; @@ -76,12 +78,20 @@ public class AmbiguousObjectException extends IOException { this.candidates = candidates; } - /** @return the AbbreviatedObjectId that has more than one result. */ + /** + * Get the {@code AbbreviatedObjectId} that has more than one result + * + * @return the {@code AbbreviatedObjectId} that has more than one result + */ public AbbreviatedObjectId getAbbreviatedObjectId() { return missing; } - /** @return the matching candidates (or at least a subset of them). */ + /** + * Get the matching candidates (or at least a subset of them) + * + * @return the matching candidates (or at least a subset of them) + */ public Collection<ObjectId> getCandidates() { return candidates; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/BinaryBlobException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/BinaryBlobException.java new file mode 100644 index 0000000000..a345fe4d59 --- /dev/null +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/BinaryBlobException.java @@ -0,0 +1,58 @@ +/* + * Copyright (C) 2017 Google Inc. + * and other copyright owners as documented in the project's IP log. + * + * This program and the accompanying materials are made available + * under the terms of the Eclipse Distribution License v1.0 which + * accompanies this distribution, is reproduced below, and is + * available at http://www.eclipse.org/org/documents/edl-v10.php + * + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or + * without modification, are permitted provided that the following + * conditions are met: + * + * - Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * - Redistributions in binary form must reproduce the above + * copyright notice, this list of conditions and the following + * disclaimer in the documentation and/or other materials provided + * with the distribution. + * + * - Neither the name of the Eclipse Foundation, Inc. nor the + * names of its contributors may be used to endorse or promote + * products derived from this software without specific prior + * written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND + * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, + * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER + * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF + * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ +package org.eclipse.jgit.errors; + +/** + * BinaryBlobException is used to signal that binary data was found + * in a context that requires text (eg. for generating textual diffs). + * + * @since 4.10 + */ +public class BinaryBlobException extends Exception { + private static final long serialVersionUID = 1L; + + /** + * Construct a BinaryBlobException. + */ + public BinaryBlobException() {} +} diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/CancelledException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/CancelledException.java index c2833a1614..d7c553cf63 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/CancelledException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/CancelledException.java @@ -54,7 +54,10 @@ public class CancelledException extends IOException { private static final long serialVersionUID = 1L; /** + * Constructor for CancelledException + * * @param message + * error message */ public CancelledException(String message) { super(message); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/CheckoutConflictException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/CheckoutConflictException.java index b6010b6983..9b7b618e41 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/CheckoutConflictException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/CheckoutConflictException.java @@ -62,6 +62,7 @@ public class CheckoutConflictException extends IOException { * Construct a CheckoutConflictException for the specified file * * @param file + * relative path of a file */ public CheckoutConflictException(String file) { super(MessageFormat.format(JGitText.get().checkoutConflictWithFile, file)); @@ -72,6 +73,7 @@ public class CheckoutConflictException extends IOException { * Construct a CheckoutConflictException for the specified set of files * * @param files + * an array of relative file paths */ public CheckoutConflictException(String[] files) { super(MessageFormat.format(JGitText.get().checkoutConflictWithFiles, buildList(files))); @@ -79,6 +81,8 @@ public class CheckoutConflictException extends IOException { } /** + * Get the relative paths of the conflicting files + * * @return the relative paths of the conflicting files (relative to the * working directory root). * @since 4.4 diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/CommandFailedException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/CommandFailedException.java index 93749f5e43..5df41c2835 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/CommandFailedException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/CommandFailedException.java @@ -54,6 +54,8 @@ public class CommandFailedException extends Exception { private int returnCode; /** + * Constructor for CommandFailedException + * * @param returnCode * return code returned by the command * @param message @@ -65,6 +67,8 @@ public class CommandFailedException extends Exception { } /** + * Constructor for CommandFailedException + * * @param returnCode * return code returned by the command * @param message @@ -79,6 +83,8 @@ public class CommandFailedException extends Exception { } /** + * Get return code returned by the command + * * @return return code returned by the command */ public int getReturnCode() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/CompoundException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/CompoundException.java index 3a7b2c66d1..62ff990883 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/CompoundException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/CompoundException.java @@ -50,7 +50,9 @@ import java.util.List; import org.eclipse.jgit.internal.JGitText; -/** An exception detailing multiple reasons for failure. */ +/** + * An exception detailing multiple reasons for failure. + */ public class CompoundException extends Exception { private static final long serialVersionUID = 1L; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/ConfigInvalidException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/ConfigInvalidException.java index 43fb4bcf8b..a7e1d02b49 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/ConfigInvalidException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/ConfigInvalidException.java @@ -43,7 +43,9 @@ package org.eclipse.jgit.errors; -/** Indicates a text string is not a valid Git style configuration. */ +/** + * Indicates a text string is not a valid Git style configuration. + */ public class ConfigInvalidException extends Exception { private static final long serialVersionUID = 1L; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/CorruptObjectException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/CorruptObjectException.java index e4db40b889..4b503a302d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/CorruptObjectException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/CorruptObjectException.java @@ -86,7 +86,9 @@ public class CorruptObjectException extends IOException { * object id * * @param id + * a {@link org.eclipse.jgit.lib.AnyObjectId} * @param why + * error message */ public CorruptObjectException(AnyObjectId id, String why) { super(MessageFormat.format(JGitText.get().objectIsCorrupt, id.name(), why)); @@ -97,7 +99,9 @@ public class CorruptObjectException extends IOException { * object id * * @param id + * a {@link org.eclipse.jgit.lib.ObjectId} * @param why + * error message */ public CorruptObjectException(ObjectId id, String why) { super(MessageFormat.format(JGitText.get().objectIsCorrupt, id.name(), why)); @@ -108,6 +112,7 @@ public class CorruptObjectException extends IOException { * with a specific object id. * * @param why + * error message */ public CorruptObjectException(String why) { super(why); @@ -129,7 +134,8 @@ public class CorruptObjectException extends IOException { } /** - * Specific error condition identified by {@link ObjectChecker}. + * Specific error condition identified by + * {@link org.eclipse.jgit.lib.ObjectChecker}. * * @return error condition or null. * @since 4.2 diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/DiffInterruptedException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/DiffInterruptedException.java index 5f9ce351ad..1df8773137 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/DiffInterruptedException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/DiffInterruptedException.java @@ -53,8 +53,12 @@ public class DiffInterruptedException extends RuntimeException { private static final long serialVersionUID = 1L; /** + * Constructor for DiffInterruptedException + * * @param message + * error message * @param cause + * a {@link java.lang.Throwable} * @since 4.1 */ public DiffInterruptedException(String message, Throwable cause) { @@ -62,14 +66,19 @@ public class DiffInterruptedException extends RuntimeException { } /** + * Constructor for DiffInterruptedException + * * @param message + * error message * @since 4.1 */ public DiffInterruptedException(String message) { super(message); } - /** Indicates that the thread computing a diff was interrupted. */ + /** + * Indicates that the thread computing a diff was interrupted. + */ public DiffInterruptedException() { super(); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/DirCacheNameConflictException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/DirCacheNameConflictException.java index 5f67e3439b..4d08dfd812 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/DirCacheNameConflictException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/DirCacheNameConflictException.java @@ -68,12 +68,20 @@ public class DirCacheNameConflictException extends IllegalStateException { this.path2 = path2; } - /** @return one of the paths that has a conflict. */ + /** + * Get one of the paths that has a conflict + * + * @return one of the paths that has a conflict + */ public String getPath1() { return path1; } - /** @return another path that has a conflict. */ + /** + * Get another path that has a conflict + * + * @return another path that has a conflict + */ public String getPath2() { return path2; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/IllegalTodoFileModification.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/IllegalTodoFileModification.java index dae150ce0a..a6471217e1 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/IllegalTodoFileModification.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/IllegalTodoFileModification.java @@ -51,7 +51,10 @@ public class IllegalTodoFileModification extends Exception { private static final long serialVersionUID = 1L; /** + * Constructor for IllegalTodoFileModification + * * @param msg + * error message */ public IllegalTodoFileModification(final String msg) { super(msg); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/InvalidObjectIdException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/InvalidObjectIdException.java index 390545ffaf..4abbf1e2c9 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/InvalidObjectIdException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/InvalidObjectIdException.java @@ -69,8 +69,10 @@ public class InvalidObjectIdException extends IllegalArgumentException { } /** - * @param id the invalid id. + * Constructor for InvalidObjectIdException * + * @param id + * the invalid id. * @since 4.1 */ public InvalidObjectIdException(String id) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/InvalidPatternException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/InvalidPatternException.java index 18e78ffe76..949c4ff88b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/InvalidPatternException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/InvalidPatternException.java @@ -47,7 +47,6 @@ package org.eclipse.jgit.errors; /** * Thrown when a pattern passed in an argument was wrong. - * */ public class InvalidPatternException extends Exception { private static final long serialVersionUID = 1L; @@ -55,6 +54,8 @@ public class InvalidPatternException extends Exception { private final String pattern; /** + * Constructor for InvalidPatternException + * * @param message * explains what was wrong with the pattern. * @param pattern @@ -66,6 +67,25 @@ public class InvalidPatternException extends Exception { } /** + * Constructor for InvalidPatternException + * + * @param message + * explains what was wrong with the pattern. + * @param pattern + * the invalid pattern. + * @param cause + * the cause. + * @since 4.10 + */ + public InvalidPatternException(String message, String pattern, + Throwable cause) { + this(message, pattern); + initCause(cause); + } + + /** + * Get the invalid pattern + * * @return the invalid pattern. */ public String getPattern() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/LargeObjectException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/LargeObjectException.java index a69bdc481d..dfdf50d35d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/LargeObjectException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/LargeObjectException.java @@ -49,18 +49,33 @@ import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.lib.AnyObjectId; import org.eclipse.jgit.lib.ObjectId; -/** An object is too big to load into memory as a single byte array. */ +/** + * An object is too big to load into memory as a single byte array. + */ public class LargeObjectException extends RuntimeException { private static final long serialVersionUID = 1L; private ObjectId objectId; - /** Create a large object exception, where the object isn't known. */ + /** + * Create a large object exception, where the object isn't known. + */ public LargeObjectException() { // Do nothing. } /** + * Create a large object exception, where the object isn't known. + * + * @param cause + * the cause + * @since 4.10 + */ + public LargeObjectException(Throwable cause) { + initCause(cause); + } + + /** * Create a large object exception, naming the object that is too big. * * @param id @@ -71,12 +86,20 @@ public class LargeObjectException extends RuntimeException { setObjectId(id); } - /** @return identity of the object that is too large; may be null. */ + /** + * Get identity of the object that is too large; may be null + * + * @return identity of the object that is too large; may be null + */ public ObjectId getObjectId() { return objectId; } - /** @return either the hex encoded name of the object, or 'unknown object'. */ + /** + * Get the hex encoded name of the object, or 'unknown object' + * + * @return either the hex encoded name of the object, or 'unknown object' + */ protected String getObjectName() { if (getObjectId() != null) return getObjectId().name(); @@ -94,6 +117,7 @@ public class LargeObjectException extends RuntimeException { objectId = id.copy(); } + /** {@inheritDoc} */ @Override public String getMessage() { return MessageFormat.format(JGitText.get().largeObjectException, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/LockFailedException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/LockFailedException.java index 0142e17635..bf958bd333 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/LockFailedException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/LockFailedException.java @@ -57,12 +57,15 @@ public class LockFailedException extends IOException { private File file; /** + * Constructor for LockFailedException + * * @param file * file that could not be locked * @param message * exception message * @param cause - * cause, for later retrieval by {@link Throwable#getCause()} + * cause, for later retrieval by + * {@link java.lang.Throwable#getCause()} * @since 4.1 */ public LockFailedException(File file, String message, Throwable cause) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/MissingObjectException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/MissingObjectException.java index d1157c4e3d..f6aa092db4 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/MissingObjectException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/MissingObjectException.java @@ -100,7 +100,11 @@ public class MissingObjectException extends IOException { missing = null; } - /** @return the ObjectId that was not found. */ + /** + * Get the ObjectId that was not found + * + * @return the ObjectId that was not found + */ public ObjectId getObjectId() { return missing; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/NoClosingBracketException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/NoClosingBracketException.java index 6601591f0f..1f79c5d465 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/NoClosingBracketException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/NoClosingBracketException.java @@ -58,6 +58,8 @@ public class NoClosingBracketException extends InvalidPatternException { private static final long serialVersionUID = 1L; /** + * Constructor for NoClosingBracketException + * * @param indexOfOpeningBracket * the position of the [ character which has no ] character. * @param openingBracket diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/NoMergeBaseException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/NoMergeBaseException.java index 0c419d759a..97214b0ede 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/NoMergeBaseException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/NoMergeBaseException.java @@ -118,6 +118,8 @@ public class NoMergeBaseException extends IOException { } /** + * Get the reason why no merge base could be found + * * @return the reason why no merge base could be found */ public MergeBaseFailureReason getReason() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/NoWorkTreeException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/NoWorkTreeException.java index 6f61806b22..82ed7efc86 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/NoWorkTreeException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/NoWorkTreeException.java @@ -44,15 +44,17 @@ package org.eclipse.jgit.errors; import org.eclipse.jgit.internal.JGitText; -import org.eclipse.jgit.lib.Repository; /** - * Indicates a {@link Repository} has no working directory, and is thus bare. + * Indicates a {@link org.eclipse.jgit.lib.Repository} has no working directory, + * and is thus bare. */ public class NoWorkTreeException extends IllegalStateException { private static final long serialVersionUID = 1L; - /** Creates an exception indicating there is no work tree for a repository. */ + /** + * Creates an exception indicating there is no work tree for a repository. + */ public NoWorkTreeException() { super(JGitText.get().bareRepositoryNoWorkdirAndIndex); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/PackInvalidException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/PackInvalidException.java index 8c216c3d41..9886e15dda 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/PackInvalidException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/PackInvalidException.java @@ -49,7 +49,9 @@ import java.text.MessageFormat; import org.eclipse.jgit.internal.JGitText; -/** Thrown when a PackFile previously failed and is known to be unusable */ +/** + * Thrown when a PackFile previously failed and is known to be unusable + */ public class PackInvalidException extends IOException { private static final long serialVersionUID = 1L; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/PackMismatchException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/PackMismatchException.java index b82846530d..5b9a4b93b9 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/PackMismatchException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/PackMismatchException.java @@ -45,7 +45,9 @@ package org.eclipse.jgit.errors; import java.io.IOException; -/** Thrown when a PackFile no longer matches the PackIndex. */ +/** + * Thrown when a PackFile no longer matches the PackIndex. + */ public class PackMismatchException extends IOException { private static final long serialVersionUID = 1L; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/RepositoryNotFoundException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/RepositoryNotFoundException.java index 33429d6e64..aabb46ad42 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/RepositoryNotFoundException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/RepositoryNotFoundException.java @@ -48,7 +48,9 @@ import java.text.MessageFormat; import org.eclipse.jgit.internal.JGitText; -/** Indicates a local repository does not exist. */ +/** + * Indicates a local repository does not exist. + */ public class RepositoryNotFoundException extends TransportException { private static final long serialVersionUID = 1L; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/RevWalkException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/RevWalkException.java index 757a45b6d2..82654e8bd0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/RevWalkException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/RevWalkException.java @@ -45,16 +45,16 @@ package org.eclipse.jgit.errors; import org.eclipse.jgit.internal.JGitText; -import org.eclipse.jgit.revwalk.RevWalk; /** - * Indicates a checked exception was thrown inside of {@link RevWalk}. + * Indicates a checked exception was thrown inside of + * {@link org.eclipse.jgit.revwalk.RevWalk}. * <p> * Usually this exception is thrown from the Iterator created around a RevWalk * instance, as the Iterator API does not allow checked exceptions to be thrown - * from hasNext() or next(). The {@link Exception#getCause()} of this exception - * is the original checked exception that we really wanted to throw back to the - * application for handling and recovery. + * from hasNext() or next(). The {@link java.lang.Exception#getCause()} of this + * exception is the original checked exception that we really wanted to throw + * back to the application for handling and recovery. */ public class RevWalkException extends RuntimeException { private static final long serialVersionUID = 1L; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/RevisionSyntaxException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/RevisionSyntaxException.java index a039c7d14e..be3ca1b1e6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/RevisionSyntaxException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/RevisionSyntaxException.java @@ -77,6 +77,7 @@ public class RevisionSyntaxException extends IllegalArgumentException { this.revstr = revstr; } + /** {@inheritDoc} */ @Override public String toString() { return super.toString() + ":" + revstr; //$NON-NLS-1$ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/StoredObjectRepresentationNotAvailableException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/StoredObjectRepresentationNotAvailableException.java index 0bd035b5dd..8fa14c7d38 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/StoredObjectRepresentationNotAvailableException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/StoredObjectRepresentationNotAvailableException.java @@ -45,8 +45,10 @@ package org.eclipse.jgit.errors; import org.eclipse.jgit.internal.storage.pack.ObjectToPack; -/** A previously selected representation is no longer available. */ -public class StoredObjectRepresentationNotAvailableException extends Exception { +/** + * A previously selected representation is no longer available. + */ +public class StoredObjectRepresentationNotAvailableException extends Exception { //TODO remove unused ObjectToPack in 5.0 private static final long serialVersionUID = 1L; /** @@ -54,9 +56,28 @@ public class StoredObjectRepresentationNotAvailableException extends Exception { * * @param otp * the object whose current representation is no longer present. + * @deprecated use + * {@link #StoredObjectRepresentationNotAvailableException(ObjectToPack, Throwable)} + * instead. * @since 3.0 */ + @Deprecated public StoredObjectRepresentationNotAvailableException(ObjectToPack otp) { // Do nothing. } + + /** + * Construct an error for an object. + * + * @param otp + * the object whose current representation is no longer present. + * @param cause + * cause + * @since 4.10 + */ + public StoredObjectRepresentationNotAvailableException(ObjectToPack otp, + Throwable cause) { + super(cause); + // Do nothing. + } } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/TooLargeObjectInPackException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/TooLargeObjectInPackException.java index ece76ed287..fb413d82de 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/TooLargeObjectInPackException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/TooLargeObjectInPackException.java @@ -48,7 +48,9 @@ import java.text.MessageFormat; import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.transport.URIish; -/** Thrown when PackParser finds an object larger than a predefined limit */ +/** + * Thrown when PackParser finds an object larger than a predefined limit + */ public class TooLargeObjectInPackException extends TransportException { private static final long serialVersionUID = 1L; @@ -72,7 +74,9 @@ public class TooLargeObjectInPackException extends TransportException { * too large object is known. * * @param objectSize + * a long. * @param maxObjectSizeLimit + * a long. */ public TooLargeObjectInPackException(long objectSize, long maxObjectSizeLimit) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/TranslationBundleException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/TranslationBundleException.java index dc5f7a43cf..70760f36bf 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/TranslationBundleException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/TranslationBundleException.java @@ -43,7 +43,6 @@ package org.eclipse.jgit.errors; import java.util.Locale; -import java.util.ResourceBundle; /** * Common base class for all translation bundle related exceptions. @@ -55,7 +54,8 @@ public abstract class TranslationBundleException extends RuntimeException { private final Locale locale; /** - * To construct an instance of {@link TranslationBundleException} + * Construct an instance of + * {@link org.eclipse.jgit.errors.TranslationBundleException} * * @param message * exception message @@ -65,7 +65,7 @@ public abstract class TranslationBundleException extends RuntimeException { * locale for which the exception occurred * @param cause * original exception that caused this exception. Usually thrown - * from the {@link ResourceBundle} class. + * from the {@link java.util.ResourceBundle} class. */ protected TranslationBundleException(String message, Class bundleClass, Locale locale, Exception cause) { super(message, cause); @@ -74,6 +74,8 @@ public abstract class TranslationBundleException extends RuntimeException { } /** + * Get bundle class + * * @return bundle class for which the exception occurred */ final public Class getBundleClass() { @@ -81,6 +83,8 @@ public abstract class TranslationBundleException extends RuntimeException { } /** + * Get locale for which the exception occurred + * * @return locale for which the exception occurred */ final public Locale getLocale() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/TranslationBundleLoadingException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/TranslationBundleLoadingException.java index 6cb332d483..4033ee17d9 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/TranslationBundleLoadingException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/TranslationBundleLoadingException.java @@ -43,7 +43,6 @@ package org.eclipse.jgit.errors; import java.util.Locale; -import java.util.ResourceBundle; /** * This exception will be thrown when a translation bundle loading @@ -53,8 +52,9 @@ public class TranslationBundleLoadingException extends TranslationBundleExceptio private static final long serialVersionUID = 1L; /** - * Construct a {@link TranslationBundleLoadingException} for the specified - * bundle class and locale. + * Construct a + * {@link org.eclipse.jgit.errors.TranslationBundleLoadingException} for the + * specified bundle class and locale. * * @param bundleClass * the bundle class for which the loading failed @@ -62,7 +62,8 @@ public class TranslationBundleLoadingException extends TranslationBundleExceptio * the locale for which the loading failed * @param cause * the original exception thrown from the - * {@link ResourceBundle#getBundle(String, Locale)} method. + * {@link java.util.ResourceBundle#getBundle(String, Locale)} + * method. */ public TranslationBundleLoadingException(Class bundleClass, Locale locale, Exception cause) { super("Loading of translation bundle failed for [" //$NON-NLS-1$ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/TranslationStringMissingException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/TranslationStringMissingException.java index 05c38424ec..d30c1be082 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/TranslationStringMissingException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/TranslationStringMissingException.java @@ -43,7 +43,6 @@ package org.eclipse.jgit.errors; import java.util.Locale; -import java.util.ResourceBundle; /** * This exception will be thrown when a translation string for a translation @@ -55,8 +54,9 @@ public class TranslationStringMissingException extends TranslationBundleExceptio private final String key; /** - * Construct a {@link TranslationStringMissingException} for the specified - * bundle class, locale and translation key + * Construct a + * {@link org.eclipse.jgit.errors.TranslationStringMissingException} for the + * specified bundle class, locale and translation key * * @param bundleClass * the bundle class for which a translation string was missing @@ -66,7 +66,7 @@ public class TranslationStringMissingException extends TranslationBundleExceptio * the key of the missing translation string * @param cause * the original exception thrown from the - * {@link ResourceBundle#getString(String)} method. + * {@link java.util.ResourceBundle#getString(String)} method. */ public TranslationStringMissingException(Class bundleClass, Locale locale, String key, Exception cause) { super("Translation missing for [" + bundleClass.getName() + ", " //$NON-NLS-1$ //$NON-NLS-2$ @@ -76,6 +76,8 @@ public class TranslationStringMissingException extends TranslationBundleExceptio } /** + * Get the key of the missing translation string + * * @return the key of the missing translation string */ public String getKey() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/UnmergedPathException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/UnmergedPathException.java index 3dbfb5f957..4fc534b944 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/UnmergedPathException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/UnmergedPathException.java @@ -68,7 +68,11 @@ public class UnmergedPathException extends IOException { entry = dce; } - /** @return the first non-zero stage of the unmerged path */ + /** + * Get the first non-zero stage of the unmerged path + * + * @return the first non-zero stage of the unmerged path + */ public DirCacheEntry getDirCacheEntry() { return entry; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/UnpackException.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/UnpackException.java index a9b01138ca..0e0ff580cb 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/UnpackException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/UnpackException.java @@ -47,7 +47,9 @@ import java.io.IOException; import org.eclipse.jgit.internal.JGitText; -/** Indicates a ReceivePack failure while scanning the pack stream. */ +/** + * Indicates a ReceivePack failure while scanning the pack stream. + */ public class UnpackException extends IOException { private static final long serialVersionUID = 1L; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/errors/UnsupportedCredentialItem.java b/org.eclipse.jgit/src/org/eclipse/jgit/errors/UnsupportedCredentialItem.java index daba576ca4..88c2ef6238 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/errors/UnsupportedCredentialItem.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/errors/UnsupportedCredentialItem.java @@ -43,13 +43,12 @@ */ package org.eclipse.jgit.errors; -import org.eclipse.jgit.transport.CredentialItem; -import org.eclipse.jgit.transport.CredentialsProvider; import org.eclipse.jgit.transport.URIish; /** - * An exception thrown when a {@link CredentialItem} is requested from a - * {@link CredentialsProvider} which is not supported by this provider. + * An exception thrown when a {@link org.eclipse.jgit.transport.CredentialItem} + * is requested from a {@link org.eclipse.jgit.transport.CredentialsProvider} + * which is not supported by this provider. */ public class UnsupportedCredentialItem extends RuntimeException { private static final long serialVersionUID = 1L; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/events/ConfigChangedEvent.java b/org.eclipse.jgit/src/org/eclipse/jgit/events/ConfigChangedEvent.java index 79598eacb3..69f6ff82ce 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/events/ConfigChangedEvent.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/events/ConfigChangedEvent.java @@ -43,13 +43,17 @@ package org.eclipse.jgit.events; -/** Describes a change to one or more keys in the configuration. */ +/** + * Describes a change to one or more keys in the configuration. + */ public class ConfigChangedEvent extends RepositoryEvent<ConfigChangedListener> { + /** {@inheritDoc} */ @Override public Class<ConfigChangedListener> getListenerType() { return ConfigChangedListener.class; } + /** {@inheritDoc} */ @Override public void dispatch(ConfigChangedListener listener) { listener.onConfigChanged(this); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/events/ConfigChangedListener.java b/org.eclipse.jgit/src/org/eclipse/jgit/events/ConfigChangedListener.java index 322cf7f6d6..34fe90a58d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/events/ConfigChangedListener.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/events/ConfigChangedListener.java @@ -43,7 +43,9 @@ package org.eclipse.jgit.events; -/** Receives {@link ConfigChangedEvent}s. */ +/** + * Receives {@link org.eclipse.jgit.events.ConfigChangedEvent}s. + */ public interface ConfigChangedListener extends RepositoryListener { /** * Invoked when any change is made to the configuration. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/events/IndexChangedEvent.java b/org.eclipse.jgit/src/org/eclipse/jgit/events/IndexChangedEvent.java index a54288ee9e..647ec8a20c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/events/IndexChangedEvent.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/events/IndexChangedEvent.java @@ -43,13 +43,17 @@ package org.eclipse.jgit.events; -/** Describes a change to one or more paths in the index file. */ +/** + * Describes a change to one or more paths in the index file. + */ public class IndexChangedEvent extends RepositoryEvent<IndexChangedListener> { + /** {@inheritDoc} */ @Override public Class<IndexChangedListener> getListenerType() { return IndexChangedListener.class; } + /** {@inheritDoc} */ @Override public void dispatch(IndexChangedListener listener) { listener.onIndexChanged(this); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/events/IndexChangedListener.java b/org.eclipse.jgit/src/org/eclipse/jgit/events/IndexChangedListener.java index d41ef74ee9..682cea563a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/events/IndexChangedListener.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/events/IndexChangedListener.java @@ -43,7 +43,9 @@ package org.eclipse.jgit.events; -/** Receives {@link IndexChangedEvent}s. */ +/** + * Receives {@link org.eclipse.jgit.events.IndexChangedEvent}s. + */ public interface IndexChangedListener extends RepositoryListener { /** * Invoked when any change is made to the index. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/events/ListenerHandle.java b/org.eclipse.jgit/src/org/eclipse/jgit/events/ListenerHandle.java index d8cd756d99..dcd5374073 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/events/ListenerHandle.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/events/ListenerHandle.java @@ -43,7 +43,9 @@ package org.eclipse.jgit.events; -/** Tracks a previously registered {@link RepositoryListener}. */ +/** + * Tracks a previously registered {@link org.eclipse.jgit.events.RepositoryListener}. + */ public class ListenerHandle { private final ListenerList parent; @@ -59,11 +61,14 @@ public class ListenerHandle { this.listener = listener; } - /** Remove the listener and stop receiving events. */ + /** + * Remove the listener and stop receiving events. + */ public void remove() { parent.remove(this); } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/events/ListenerList.java b/org.eclipse.jgit/src/org/eclipse/jgit/events/ListenerList.java index cea03db2ec..9be1c96e91 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/events/ListenerList.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/events/ListenerList.java @@ -48,12 +48,14 @@ import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentMap; import java.util.concurrent.CopyOnWriteArrayList; -/** Manages a thread-safe list of {@link RepositoryListener}s. */ +/** + * Manages a thread-safe list of {@link org.eclipse.jgit.events.RepositoryListener}s. + */ public class ListenerList { private final ConcurrentMap<Class<? extends RepositoryListener>, CopyOnWriteArrayList<ListenerHandle>> lists = new ConcurrentHashMap<>(); /** - * Register a {@link WorkingTreeModifiedListener}. + * Register a {@link org.eclipse.jgit.events.WorkingTreeModifiedListener}. * * @param listener * the listener implementation. @@ -102,8 +104,6 @@ public class ListenerList { /** * Add a listener to the list. * - * @param <T> - * the type of listener being registered. * @param type * type of listener being registered. * @param listener diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/events/RefsChangedEvent.java b/org.eclipse.jgit/src/org/eclipse/jgit/events/RefsChangedEvent.java index 36af3f8b77..f1923afc20 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/events/RefsChangedEvent.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/events/RefsChangedEvent.java @@ -43,13 +43,17 @@ package org.eclipse.jgit.events; -/** Describes a change to one or more references of a repository. */ +/** + * Describes a change to one or more references of a repository. + */ public class RefsChangedEvent extends RepositoryEvent<RefsChangedListener> { + /** {@inheritDoc} */ @Override public Class<RefsChangedListener> getListenerType() { return RefsChangedListener.class; } + /** {@inheritDoc} */ @Override public void dispatch(RefsChangedListener listener) { listener.onRefsChanged(this); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/events/RefsChangedListener.java b/org.eclipse.jgit/src/org/eclipse/jgit/events/RefsChangedListener.java index 9c0f4ed588..f3cdad12e5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/events/RefsChangedListener.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/events/RefsChangedListener.java @@ -43,7 +43,9 @@ package org.eclipse.jgit.events; -/** Receives {@link RefsChangedEvent}s. */ +/** + * Receives {@link org.eclipse.jgit.events.RefsChangedEvent}s. + */ public interface RefsChangedListener extends RepositoryListener { /** * Invoked when any reference changes. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/events/RepositoryEvent.java b/org.eclipse.jgit/src/org/eclipse/jgit/events/RepositoryEvent.java index 1b7d28c333..576b21ba61 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/events/RepositoryEvent.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/events/RepositoryEvent.java @@ -59,7 +59,8 @@ public abstract class RepositoryEvent<T extends RepositoryListener> { * Set the repository this event occurred on. * <p> * This method should only be invoked once on each event object, and is - * automatically set by {@link Repository#fireEvent(RepositoryEvent)}. + * automatically set by + * {@link org.eclipse.jgit.lib.Repository#fireEvent(RepositoryEvent)}. * * @param r * the repository. @@ -69,12 +70,20 @@ public abstract class RepositoryEvent<T extends RepositoryListener> { repository = r; } - /** @return the repository that was changed. */ + /** + * Get the repository that was changed + * + * @return the repository that was changed + */ public Repository getRepository() { return repository; } - /** @return type of listener this event dispatches to. */ + /** + * Get type of listener this event dispatches to + * + * @return type of listener this event dispatches to + */ public abstract Class<T> getListenerType(); /** @@ -85,6 +94,7 @@ public abstract class RepositoryEvent<T extends RepositoryListener> { */ public abstract void dispatch(T listener); + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/events/RepositoryListener.java b/org.eclipse.jgit/src/org/eclipse/jgit/events/RepositoryListener.java index 4f951e5f87..a2cf0cc664 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/events/RepositoryListener.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/events/RepositoryListener.java @@ -43,7 +43,9 @@ package org.eclipse.jgit.events; -/** A listener can register for event delivery. */ +/** + * A listener can register for event delivery. + */ public interface RepositoryListener { // Empty marker interface; see extensions for actual methods. } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/events/WorkingTreeModifiedEvent.java b/org.eclipse.jgit/src/org/eclipse/jgit/events/WorkingTreeModifiedEvent.java index 6517823db2..9fbcc4dd50 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/events/WorkingTreeModifiedEvent.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/events/WorkingTreeModifiedEvent.java @@ -48,8 +48,9 @@ import java.util.Collections; import org.eclipse.jgit.annotations.NonNull; /** - * A {@link RepositoryEvent} describing changes to the working tree. It is fired - * whenever a {@link org.eclipse.jgit.dircache.DirCacheCheckout} modifies + * A {@link org.eclipse.jgit.events.RepositoryEvent} describing changes to the + * working tree. It is fired whenever a + * {@link org.eclipse.jgit.dircache.DirCacheCheckout} modifies * (adds/deletes/updates) files in the working tree. * * @since 4.9 @@ -62,8 +63,8 @@ public class WorkingTreeModifiedEvent private Collection<String> deleted; /** - * Creates a new {@link WorkingTreeModifiedEvent} with the given - * collections. + * Creates a new {@link org.eclipse.jgit.events.WorkingTreeModifiedEvent} + * with the given collections. * * @param modified * repository-relative paths that were added or updated @@ -88,8 +89,8 @@ public class WorkingTreeModifiedEvent } /** - * Retrieves the {@link Collection} of repository-relative paths of files - * that were modified (added or updated). + * Retrieves the {@link java.util.Collection} of repository-relative paths + * of files that were modified (added or updated). * * @return the set */ @@ -103,8 +104,8 @@ public class WorkingTreeModifiedEvent } /** - * Retrieves the {@link Collection} of repository-relative paths of files - * that were deleted. + * Retrieves the {@link java.util.Collection} of repository-relative paths + * of files that were deleted. * * @return the set */ @@ -117,11 +118,13 @@ public class WorkingTreeModifiedEvent return result; } + /** {@inheritDoc} */ @Override public Class<WorkingTreeModifiedListener> getListenerType() { return WorkingTreeModifiedListener.class; } + /** {@inheritDoc} */ @Override public void dispatch(WorkingTreeModifiedListener listener) { listener.onWorkingTreeModified(this); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/events/WorkingTreeModifiedListener.java b/org.eclipse.jgit/src/org/eclipse/jgit/events/WorkingTreeModifiedListener.java index 402a900226..728ce26a2c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/events/WorkingTreeModifiedListener.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/events/WorkingTreeModifiedListener.java @@ -44,8 +44,8 @@ package org.eclipse.jgit.events; /** - * Receives {@link WorkingTreeModifiedEvent}s, which are fired whenever a - * {@link org.eclipse.jgit.dircache.DirCacheCheckout} modifies + * Receives {@link org.eclipse.jgit.events.WorkingTreeModifiedEvent}s, which are + * fired whenever a {@link org.eclipse.jgit.dircache.DirCacheCheckout} modifies * (adds/deletes/updates) files in the working tree. * * @since 4.9 @@ -56,6 +56,8 @@ public interface WorkingTreeModifiedListener extends RepositoryListener { * Respond to working tree modifications. * * @param event + * a {@link org.eclipse.jgit.events.WorkingTreeModifiedEvent} + * object. */ void onWorkingTreeModified(WorkingTreeModifiedEvent event); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/AbstractHead.java b/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/AbstractHead.java index 10c84c4ecc..60669bb955 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/AbstractHead.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/AbstractHead.java @@ -53,6 +53,13 @@ abstract class AbstractHead implements Head { private final boolean star; + /** + * Whether the char matches + * + * @param c + * a char. + * @return whether the char matches + */ protected abstract boolean matches(char c); AbstractHead(boolean star) { @@ -60,9 +67,11 @@ abstract class AbstractHead implements Head { } /** + * Set {@link org.eclipse.jgit.fnmatch.Head}s which will not be modified. * * @param newHeads - * a list of {@link Head}s which will not be modified. + * a list of {@link org.eclipse.jgit.fnmatch.Head}s which will + * not be modified. */ public final void setNewHeads(List<Head> newHeads) { if (this.newHeads != null) @@ -70,6 +79,7 @@ abstract class AbstractHead implements Head { this.newHeads = newHeads; } + /** {@inheritDoc} */ @Override public List<Head> getNextHeads(char c) { if (matches(c)) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/CharacterHead.java b/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/CharacterHead.java index 6211b246f8..98aee0eef2 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/CharacterHead.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/CharacterHead.java @@ -47,16 +47,24 @@ package org.eclipse.jgit.fnmatch; final class CharacterHead extends AbstractHead { private final char expectedCharacter; + /** + * Constructor for CharacterHead + * + * @param expectedCharacter + * expected {@code char} + */ protected CharacterHead(final char expectedCharacter) { super(false); this.expectedCharacter = expectedCharacter; } + /** {@inheritDoc} */ @Override protected final boolean matches(final char c) { return c == expectedCharacter; } + /** {@inheritDoc} */ @Override public String toString() { return String.valueOf(expectedCharacter); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/FileNameMatcher.java b/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/FileNameMatcher.java index 856d74e997..56630395b2 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/FileNameMatcher.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/FileNameMatcher.java @@ -126,12 +126,14 @@ public class FileNameMatcher { } /** + * Constructor for FileNameMatcher + * * @param patternString * must contain a pattern which fnmatch would accept. * @param invalidWildgetCharacter * if this parameter isn't null then this character will not * match at wildcards(* and ? are wildcards). - * @throws InvalidPatternException + * @throws org.eclipse.jgit.errors.InvalidPatternException * if the patternString contains a invalid fnmatch pattern. */ public FileNameMatcher(final String patternString, @@ -141,11 +143,13 @@ public class FileNameMatcher { } /** - * A Copy Constructor which creates a new {@link FileNameMatcher} with the - * same state and reset point like <code>other</code>. + * A Copy Constructor which creates a new + * {@link org.eclipse.jgit.fnmatch.FileNameMatcher} with the same state and + * reset point like <code>other</code>. * * @param other - * another {@link FileNameMatcher} instance. + * another {@link org.eclipse.jgit.fnmatch.FileNameMatcher} + * instance. */ public FileNameMatcher(FileNameMatcher other) { this(other.headsStartValue, other.heads); @@ -347,6 +351,7 @@ public class FileNameMatcher { } /** + * Append to the string which is matched against the patterns of this class * * @param stringToMatch * extends the string which is matched against the patterns of @@ -369,10 +374,13 @@ public class FileNameMatcher { } /** + * Create a {@link org.eclipse.jgit.fnmatch.FileNameMatcher} instance which + * uses the same pattern like this matcher, but has the current state of + * this matcher as reset and start point * - * @return a {@link FileNameMatcher} instance which uses the same pattern - * like this matcher, but has the current state of this matcher as - * reset and start point. + * @return a {@link org.eclipse.jgit.fnmatch.FileNameMatcher} instance which + * uses the same pattern like this matcher, but has the current + * state of this matcher as reset and start point. */ public FileNameMatcher createMatcherForSuffix() { final List<Head> copyOfHeads = new ArrayList<>(heads.size()); @@ -381,8 +389,9 @@ public class FileNameMatcher { } /** + * Whether the matcher matches * - * @return true, if the string currently being matched does match. + * @return whether the matcher matches */ public boolean isMatch() { if (heads.isEmpty()) @@ -400,9 +409,9 @@ public class FileNameMatcher { } /** + * Whether a match can be appended * - * @return false, if the string being matched will not match when the string - * gets extended. + * @return a boolean. */ public boolean canAppendMatch() { for (int i = 0; i < heads.size(); i++) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/GroupHead.java b/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/GroupHead.java index 5c18756786..965d90085f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/GroupHead.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/GroupHead.java @@ -130,6 +130,7 @@ final class GroupHead extends AbstractHead { } } + /** {@inheritDoc} */ @Override protected final boolean matches(final char c) { for (CharacterPattern pattern : characterClasses) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/Head.java b/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/Head.java index 3de18a7357..49839f8e6e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/Head.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/Head.java @@ -48,6 +48,7 @@ import java.util.List; interface Head { /** + * Get the character which decides which heads are returned * * @param c * the character which decides which heads are returned. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/LastHead.java b/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/LastHead.java index f9ddd9e65e..726d1f2f8e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/LastHead.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/LastHead.java @@ -56,6 +56,7 @@ final class LastHead implements Head { // defined because of javadoc and visibility modifier. } + /** {@inheritDoc} */ @Override public List<Head> getNextHeads(char c) { return FileNameMatcher.EMPTY_HEAD_LIST; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/RestrictedWildCardHead.java b/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/RestrictedWildCardHead.java index 4a0a03df25..c132e28156 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/RestrictedWildCardHead.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/RestrictedWildCardHead.java @@ -52,11 +52,13 @@ final class RestrictedWildCardHead extends AbstractHead { this.excludedCharacter = excludedCharacter; } + /** {@inheritDoc} */ @Override protected final boolean matches(final char c) { return c != excludedCharacter; } + /** {@inheritDoc} */ @Override public String toString() { return isStar() ? "*" : "?"; //$NON-NLS-1$ //$NON-NLS-2$ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/WildCardHead.java b/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/WildCardHead.java index b5173d97d0..c806e23134 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/WildCardHead.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/fnmatch/WildCardHead.java @@ -49,6 +49,7 @@ final class WildCardHead extends AbstractHead { super(star); } + /** {@inheritDoc} */ @Override protected final boolean matches(final char c) { return true; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/gitrepo/ManifestParser.java b/org.eclipse.jgit/src/org/eclipse/jgit/gitrepo/ManifestParser.java index ddc6addbc3..929ffac114 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/gitrepo/ManifestParser.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/gitrepo/ManifestParser.java @@ -113,12 +113,22 @@ public class ManifestParser extends DefaultHandler { } /** + * Constructor for ManifestParser + * * @param includedReader + * a + * {@link org.eclipse.jgit.gitrepo.ManifestParser.IncludedFileReader} + * object. * @param filename + * a {@link java.lang.String} object. * @param defaultBranch + * a {@link java.lang.String} object. * @param baseUrl + * a {@link java.lang.String} object. * @param groups + * a {@link java.lang.String} object. * @param rootRepo + * a {@link org.eclipse.jgit.lib.Repository} object. */ public ManifestParser(IncludedFileReader includedReader, String filename, String defaultBranch, String baseUrl, String groups, @@ -153,7 +163,8 @@ public class ManifestParser extends DefaultHandler { * Read the xml file. * * @param inputStream - * @throws IOException + * a {@link java.io.InputStream} object. + * @throws java.io.IOException */ public void read(InputStream inputStream) throws IOException { xmlInRead++; @@ -167,13 +178,11 @@ public class ManifestParser extends DefaultHandler { try { xr.parse(new InputSource(inputStream)); } catch (SAXException e) { - IOException error = new IOException( - RepoText.get().errorParsingManifestFile); - error.initCause(e); - throw error; + throw new IOException(RepoText.get().errorParsingManifestFile, e); } } + /** {@inheritDoc} */ @Override public void startElement( String uri, @@ -246,6 +255,7 @@ public class ManifestParser extends DefaultHandler { } } + /** {@inheritDoc} */ @Override public void endElement( String uri, @@ -257,6 +267,7 @@ public class ManifestParser extends DefaultHandler { } } + /** {@inheritDoc} */ @Override public void endDocument() throws SAXException { xmlInRead--; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/gitrepo/RepoCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/gitrepo/RepoCommand.java index 219babdf95..c7bc1b6aa3 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/gitrepo/RepoCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/gitrepo/RepoCommand.java @@ -232,7 +232,10 @@ public class RepoCommand extends GitCommand<RevCommit> { } /** + * Constructor for RepoCommand + * * @param repo + * the {@link org.eclipse.jgit.lib.Repository} */ public RepoCommand(Repository repo) { super(repo); @@ -258,7 +261,7 @@ public class RepoCommand extends GitCommand<RevCommit> { * Setting inputStream will ignore the path set. It will be closed in * {@link #call}. * - * @param inputStream + * @param inputStream a {@link java.io.InputStream} object. * @return this command * @since 3.5 */ @@ -271,10 +274,11 @@ public class RepoCommand extends GitCommand<RevCommit> { * Set base URI of the paths inside the XML. This is typically the name of * the directory holding the manifest repository, eg. for * https://android.googlesource.com/platform/manifest, this should be - * /platform (if you would run this on android.googlesource.com) - * or https://android.googlesource.com/platform elsewhere. + * /platform (if you would run this on android.googlesource.com) or + * https://android.googlesource.com/platform elsewhere. * * @param uri + * the base URI * @return this command */ public RepoCommand setURI(String uri) { @@ -319,6 +323,7 @@ public class RepoCommand extends GitCommand<RevCommit> { * revision specified in project, this branch will be used. * * @param branch + * a branch name * @return this command */ public RepoCommand setBranch(String branch) { @@ -336,6 +341,7 @@ public class RepoCommand extends GitCommand<RevCommit> { * ignored. * * @param branch + * branch name * @return this command * @since 4.1 */ @@ -404,6 +410,7 @@ public class RepoCommand extends GitCommand<RevCommit> { * * @see org.eclipse.jgit.lib.NullProgressMonitor * @param monitor + * a {@link org.eclipse.jgit.lib.ProgressMonitor} * @return this command */ public RepoCommand setProgressMonitor(final ProgressMonitor monitor) { @@ -438,6 +445,7 @@ public class RepoCommand extends GitCommand<RevCommit> { * ignored. * * @param author + * the author's {@link org.eclipse.jgit.lib.PersonIdent} * @return this command */ public RepoCommand setAuthor(final PersonIdent author) { @@ -451,6 +459,8 @@ public class RepoCommand extends GitCommand<RevCommit> { * This is only used in bare repositories. * * @param callback + * a {@link org.eclipse.jgit.gitrepo.RepoCommand.RemoteReader} + * object. * @return this command */ public RepoCommand setRemoteReader(final RemoteReader callback) { @@ -462,6 +472,9 @@ public class RepoCommand extends GitCommand<RevCommit> { * Set the IncludedFileReader callback. * * @param reader + * a + * {@link org.eclipse.jgit.gitrepo.ManifestParser.IncludedFileReader} + * object. * @return this command * @since 4.0 */ @@ -470,6 +483,7 @@ public class RepoCommand extends GitCommand<RevCommit> { return this; } + /** {@inheritDoc} */ @Override public RevCommit call() throws GitAPIException { try { @@ -534,8 +548,7 @@ public class RepoCommand extends GitCommand<RevCommit> { String path = proj.getPath(); String nameUri = proj.getName(); ObjectId objectId; - if (ObjectId.isId(proj.getRevision()) - && !ignoreRemoteFailures) { + if (ObjectId.isId(proj.getRevision())) { objectId = ObjectId.fromString(proj.getRevision()); } else { objectId = callback.sha1(nameUri, proj.getRevision()); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/gitrepo/RepoProject.java b/org.eclipse.jgit/src/org/eclipse/jgit/gitrepo/RepoProject.java index 00cd38d69e..e827612d23 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/gitrepo/RepoProject.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/gitrepo/RepoProject.java @@ -169,6 +169,8 @@ public class RepoProject implements Comparable<RepoProject> { } /** + * Constructor for RepoProject + * * @param name * the relative path to the {@code remote} * @param path @@ -203,6 +205,8 @@ public class RepoProject implements Comparable<RepoProject> { } /** + * Constructor for RepoProject + * * @param name * the relative path to the {@code remote} * @param path @@ -225,6 +229,7 @@ public class RepoProject implements Comparable<RepoProject> { * Set the url of the sub repo. * * @param url + * project url * @return this for chaining. */ public RepoProject setUrl(String url) { @@ -250,6 +255,7 @@ public class RepoProject implements Comparable<RepoProject> { * Set the default revision for the sub repo. * * @param defaultRevision + * the name of the default revision * @return this for chaining. */ public RepoProject setDefaultRevision(String defaultRevision) { @@ -325,6 +331,7 @@ public class RepoProject implements Comparable<RepoProject> { * Test whether this sub repo belongs to a specified group. * * @param group + * a group * @return true if {@code group} is present. */ public boolean inGroup(String group) { @@ -365,7 +372,7 @@ public class RepoProject implements Comparable<RepoProject> { /** * Add a copy file configuration. * - * @param copyfile + * @param copyfile a {@link org.eclipse.jgit.gitrepo.RepoProject.CopyFile} object. */ public void addCopyFile(CopyFile copyfile) { copyfiles.add(copyfile); @@ -375,6 +382,8 @@ public class RepoProject implements Comparable<RepoProject> { * Add a bunch of copyfile configurations. * * @param copyFiles + * a collection of + * {@link org.eclipse.jgit.gitrepo.RepoProject.CopyFile} objects */ public void addCopyFiles(Collection<CopyFile> copyFiles) { this.copyfiles.addAll(copyFiles); @@ -392,7 +401,7 @@ public class RepoProject implements Comparable<RepoProject> { /** * Add a link file configuration. * - * @param linkfile + * @param linkfile a {@link org.eclipse.jgit.gitrepo.RepoProject.LinkFile} object. * @since 4.8 */ public void addLinkFile(LinkFile linkfile) { @@ -403,6 +412,7 @@ public class RepoProject implements Comparable<RepoProject> { * Add a bunch of linkfile configurations. * * @param linkFiles + * a collection of {@link LinkFile}s * @since 4.8 */ public void addLinkFiles(Collection<LinkFile> linkFiles) { @@ -448,6 +458,7 @@ public class RepoProject implements Comparable<RepoProject> { return thatPath.startsWith(getPathWithSlash()); } + /** {@inheritDoc} */ @Override public boolean equals(Object o) { if (o instanceof RepoProject) { @@ -457,11 +468,13 @@ public class RepoProject implements Comparable<RepoProject> { return false; } + /** {@inheritDoc} */ @Override public int hashCode() { return this.getPathWithSlash().hashCode(); } + /** {@inheritDoc} */ @Override public int compareTo(RepoProject that) { return this.getPathWithSlash().compareTo(that.getPathWithSlash()); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/gitrepo/internal/RepoText.java b/org.eclipse.jgit/src/org/eclipse/jgit/gitrepo/internal/RepoText.java index 02a2565bdd..ccafff667f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/gitrepo/internal/RepoText.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/gitrepo/internal/RepoText.java @@ -52,6 +52,8 @@ import org.eclipse.jgit.nls.TranslationBundle; public class RepoText extends TranslationBundle { /** + * Get an instance of this translation bundle + * * @return an instance of this translation bundle */ public static RepoText get() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/hooks/CommitMsgHook.java b/org.eclipse.jgit/src/org/eclipse/jgit/hooks/CommitMsgHook.java index fa1707575a..f33168d814 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/hooks/CommitMsgHook.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/hooks/CommitMsgHook.java @@ -71,6 +71,8 @@ public class CommitMsgHook extends GitHook<String> { private String commitMessage; /** + * Constructor for CommitMsgHook + * * @param repo * The repository * @param outputStream @@ -81,6 +83,7 @@ public class CommitMsgHook extends GitHook<String> { super(repo, outputStream); } + /** {@inheritDoc} */ @Override public String call() throws IOException, AbortedByHookException { if (commitMessage == null) { @@ -103,12 +106,15 @@ public class CommitMsgHook extends GitHook<String> { return getCommitEditMessageFilePath() != null && commitMessage != null; } + /** {@inheritDoc} */ @Override public String getHookName() { return NAME; } /** + * {@inheritDoc} + * * This hook receives one parameter, which is the path to the file holding * the current commit-msg, relative to the repository's work tree. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/hooks/GitHook.java b/org.eclipse.jgit/src/org/eclipse/jgit/hooks/GitHook.java index b684dd6232..fb015c9166 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/hooks/GitHook.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/hooks/GitHook.java @@ -79,7 +79,10 @@ abstract class GitHook<T> implements Callable<T> { protected final PrintStream outputStream; /** + * Constructor for GitHook + * * @param repo + * a {@link org.eclipse.jgit.lib.Repository} object. * @param outputStream * The output stream the hook must use. {@code null} is allowed, * in which case the hook will use {@code System.out}. @@ -90,23 +93,23 @@ abstract class GitHook<T> implements Callable<T> { } /** + * {@inheritDoc} + * <p> * Run the hook. - * - * @throws IOException - * if IO goes wrong. - * @throws AbortedByHookException - * If the hook has been run and a returned an exit code - * different from zero. */ @Override public abstract T call() throws IOException, AbortedByHookException; /** + * Get name of the hook + * * @return The name of the hook, which must not be {@code null}. */ public abstract String getHookName(); /** + * Get the repository + * * @return The repository. */ protected Repository getRepository() { @@ -135,6 +138,8 @@ abstract class GitHook<T> implements Callable<T> { } /** + * Get output stream + * * @return The output stream the hook must use. Never {@code null}, * {@code System.out} is returned by default. */ @@ -145,7 +150,7 @@ abstract class GitHook<T> implements Callable<T> { /** * Runs the hook, without performing any validity checks. * - * @throws AbortedByHookException + * @throws org.eclipse.jgit.api.errors.AbortedByHookException * If the underlying hook script exited with non-zero. */ protected void doRun() throws AbortedByHookException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/hooks/Hooks.java b/org.eclipse.jgit/src/org/eclipse/jgit/hooks/Hooks.java index 46e8840579..87db36b251 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/hooks/Hooks.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/hooks/Hooks.java @@ -54,7 +54,10 @@ import org.eclipse.jgit.lib.Repository; public class Hooks { /** + * Create pre-commit hook for the given repository + * * @param repo + * a {@link org.eclipse.jgit.lib.Repository} object. * @param outputStream * The output stream, or {@code null} to use {@code System.out} * @return The pre-commit hook for the given repository. @@ -65,7 +68,10 @@ public class Hooks { } /** + * Create post-commit hook for the given repository + * * @param repo + * a {@link org.eclipse.jgit.lib.Repository} object. * @param outputStream * The output stream, or {@code null} to use {@code System.out} * @return The post-commit hook for the given repository. @@ -77,7 +83,10 @@ public class Hooks { } /** + * Create commit-msg hook for the given repository + * * @param repo + * a {@link org.eclipse.jgit.lib.Repository} object. * @param outputStream * The output stream, or {@code null} to use {@code System.out} * @return The commit-msg hook for the given repository. @@ -88,7 +97,10 @@ public class Hooks { } /** + * Create pre-push hook for the given repository + * * @param repo + * a {@link org.eclipse.jgit.lib.Repository} object. * @param outputStream * The output stream, or {@code null} to use {@code System.out} * @return The pre-push hook for the given repository. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/hooks/PostCommitHook.java b/org.eclipse.jgit/src/org/eclipse/jgit/hooks/PostCommitHook.java index 70679e0094..24bad16ecb 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/hooks/PostCommitHook.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/hooks/PostCommitHook.java @@ -60,6 +60,8 @@ public class PostCommitHook extends GitHook<Void> { public static final String NAME = "post-commit"; //$NON-NLS-1$ /** + * Constructor for PostCommitHook + * * @param repo * The repository * @param outputStream @@ -70,12 +72,14 @@ public class PostCommitHook extends GitHook<Void> { super(repo, outputStream); } + /** {@inheritDoc} */ @Override public Void call() throws IOException, AbortedByHookException { doRun(); return null; } + /** {@inheritDoc} */ @Override public String getHookName() { return NAME; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/hooks/PreCommitHook.java b/org.eclipse.jgit/src/org/eclipse/jgit/hooks/PreCommitHook.java index 1ab32e0c2b..0d9290da3e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/hooks/PreCommitHook.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/hooks/PreCommitHook.java @@ -60,6 +60,8 @@ public class PreCommitHook extends GitHook<Void> { public static final String NAME = "pre-commit"; //$NON-NLS-1$ /** + * Constructor for PreCommitHook + * * @param repo * The repository * @param outputStream @@ -70,12 +72,14 @@ public class PreCommitHook extends GitHook<Void> { super(repo, outputStream); } + /** {@inheritDoc} */ @Override public Void call() throws IOException, AbortedByHookException { doRun(); return null; } + /** {@inheritDoc} */ @Override public String getHookName() { return NAME; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/hooks/PrePushHook.java b/org.eclipse.jgit/src/org/eclipse/jgit/hooks/PrePushHook.java index a501fee901..f974eb7927 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/hooks/PrePushHook.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/hooks/PrePushHook.java @@ -72,6 +72,8 @@ public class PrePushHook extends GitHook<String> { private String refs; /** + * Constructor for PrePushHook + * * @param repo * The repository * @param outputStream @@ -82,11 +84,13 @@ public class PrePushHook extends GitHook<String> { super(repo, outputStream); } + /** {@inheritDoc} */ @Override protected String getStdinArgs() { return refs; } + /** {@inheritDoc} */ @Override public String call() throws IOException, AbortedByHookException { if (canRun()) { @@ -102,12 +106,15 @@ public class PrePushHook extends GitHook<String> { return true; } + /** {@inheritDoc} */ @Override public String getHookName() { return NAME; } /** + * {@inheritDoc} + * <p> * This hook receives two parameters, which is the name and the location of * the remote repository. */ @@ -120,21 +127,30 @@ public class PrePushHook extends GitHook<String> { } /** + * Set remote name + * * @param name + * remote name */ public void setRemoteName(String name) { remoteName = name; } /** + * Set remote location + * * @param location + * a remote location */ public void setRemoteLocation(String location) { remoteLocation = location; } /** + * Set Refs + * * @param toRefs + * a collection of {@code RemoteRefUpdate}s */ public void setRefs(Collection<RemoteRefUpdate> toRefs) { StringBuilder b = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/FastIgnoreRule.java b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/FastIgnoreRule.java index 7298a082c7..460f0ed4b1 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/FastIgnoreRule.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/FastIgnoreRule.java @@ -55,7 +55,7 @@ import org.slf4j.LoggerFactory; /** * "Fast" (compared with IgnoreRule) git ignore rule implementation supporting - * also double star <code>**<code> pattern. + * also double star {@code **} pattern. * <p> * This class is immutable and thread safe. * @@ -77,6 +77,7 @@ public class FastIgnoreRule { private final boolean dirOnly; /** + * Constructor for FastIgnoreRule * * @param pattern * ignore pattern as described in <a href= @@ -160,15 +161,18 @@ public class FastIgnoreRule { } /** - * @return True if the pattern is just a file name and not a path + * Whether the pattern is just a file name and not a path + * + * @return {@code true} if the pattern is just a file name and not a path */ public boolean getNameOnly() { return !(matcher instanceof PathMatcher); } /** + * Whether the pattern should match directories only * - * @return True if the pattern should match directories only + * @return {@code true} if the pattern should match directories only */ public boolean dirOnly() { return dirOnly; @@ -193,13 +197,17 @@ public class FastIgnoreRule { } /** - * @return true if the rule never matches (comment line or broken pattern) + * Whether the rule never matches + * + * @return {@code true} if the rule never matches (comment line or broken + * pattern) * @since 4.1 */ public boolean isEmpty() { return matcher == NO_MATCH; } + /** {@inheritDoc} */ @Override public String toString() { StringBuilder sb = new StringBuilder(); @@ -212,6 +220,7 @@ public class FastIgnoreRule { } + /** {@inheritDoc} */ @Override public int hashCode() { final int prime = 31; @@ -222,6 +231,7 @@ public class FastIgnoreRule { return result; } + /** {@inheritDoc} */ @Override public boolean equals(Object obj) { if (this == obj) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/IgnoreNode.java b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/IgnoreNode.java index 6314c63d2e..1ad60101e7 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/IgnoreNode.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/IgnoreNode.java @@ -81,7 +81,9 @@ public class IgnoreNode { /** The rules that have been parsed into this node. */ private final List<FastIgnoreRule> rules; - /** Create an empty ignore node with no rules. */ + /** + * Create an empty ignore node with no rules. + */ public IgnoreNode() { rules = new ArrayList<>(); } @@ -91,7 +93,7 @@ public class IgnoreNode { * * @param rules * list of rules. - **/ + */ public IgnoreNode(List<FastIgnoreRule> rules) { this.rules = rules; } @@ -102,7 +104,7 @@ public class IgnoreNode { * @param in * input stream holding the standard ignore format. The caller is * responsible for closing the stream. - * @throws IOException + * @throws java.io.IOException * Error thrown when reading an ignore file. */ public void parse(InputStream in) throws IOException { @@ -122,7 +124,11 @@ public class IgnoreNode { return new BufferedReader(new InputStreamReader(in, Constants.CHARSET)); } - /** @return list of all ignore rules held by this node. */ + /** + * Get list of all ignore rules held by this node + * + * @return list of all ignore rules held by this node + */ public List<FastIgnoreRule> getRules() { return Collections.unmodifiableList(rules); } @@ -194,6 +200,7 @@ public class IgnoreNode { return MatchResult.CHECK_PARENT; } + /** {@inheritDoc} */ @Override public String toString() { return rules.toString(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/AbstractMatcher.java b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/AbstractMatcher.java index 64c2a74554..8e8e5717a3 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/AbstractMatcher.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/AbstractMatcher.java @@ -64,16 +64,19 @@ public abstract class AbstractMatcher implements IMatcher { this.dirOnly = dirOnly; } + /** {@inheritDoc} */ @Override public String toString() { return pattern; } + /** {@inheritDoc} */ @Override public int hashCode() { return pattern.hashCode(); } + /** {@inheritDoc} */ @Override public boolean equals(Object obj) { if (this == obj) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/IMatcher.java b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/IMatcher.java index 5b184cb19f..dbf06385c5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/IMatcher.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/IMatcher.java @@ -74,9 +74,10 @@ public interface IMatcher { * with a slash) * @param pathMatch * {@code true} if the match is for the full path: prefix-only - * matches are not allowed, and {@link NameMatcher}s must match - * only the last component (if they can -- they may not, if they - * are anchored at the beginning) + * matches are not allowed, and + * {@link org.eclipse.jgit.ignore.internal.NameMatcher}s must + * match only the last component (if they can -- they may not, if + * they are anchored at the beginning) * @return true if this matcher pattern matches given string */ boolean matches(String path, boolean assumeDirectory, boolean pathMatch); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/LeadingAsteriskMatcher.java b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/LeadingAsteriskMatcher.java index cc0fe937b4..2bae8f229f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/LeadingAsteriskMatcher.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/LeadingAsteriskMatcher.java @@ -55,6 +55,7 @@ public class LeadingAsteriskMatcher extends NameMatcher { "Pattern must have leading asterisk: " + pattern); //$NON-NLS-1$ } + /** {@inheritDoc} */ @Override public boolean matches(String segment, int startIncl, int endExcl, boolean assumeDirectory) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/NameMatcher.java b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/NameMatcher.java index 9667837a41..6a4b2b8677 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/NameMatcher.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/NameMatcher.java @@ -71,6 +71,7 @@ public class NameMatcher extends AbstractMatcher { } } + /** {@inheritDoc} */ @Override public boolean matches(String path, boolean assumeDirectory, boolean pathMatch) { @@ -120,6 +121,7 @@ public class NameMatcher extends AbstractMatcher { return false; } + /** {@inheritDoc} */ @Override public boolean matches(String segment, int startIncl, int endExcl, boolean assumeDirectory) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/PathMatcher.java b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/PathMatcher.java index 9b3a2aac78..50e78ae751 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/PathMatcher.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/PathMatcher.java @@ -105,14 +105,17 @@ public class PathMatcher extends AbstractMatcher { } /** + * Create path matcher * * @param pattern + * a pattern * @param pathSeparator * if this parameter isn't null then this character will not * match at wildcards(* and ? are wildcards). * @param dirOnly + * a boolean. * @return never null - * @throws InvalidPatternException + * @throws org.eclipse.jgit.errors.InvalidPatternException */ public static IMatcher createPathMatcher(String pattern, Character pathSeparator, boolean dirOnly) @@ -170,6 +173,7 @@ public class PathMatcher extends AbstractMatcher { } } + /** {@inheritDoc} */ @Override public boolean matches(String path, boolean assumeDirectory, boolean pathMatch) { @@ -212,6 +216,7 @@ public class PathMatcher extends AbstractMatcher { return false; } + /** {@inheritDoc} */ @Override public boolean matches(String segment, int startIncl, int endExcl, boolean assumeDirectory) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/Strings.java b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/Strings.java index 800cdb9952..9b255b41c3 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/Strings.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/Strings.java @@ -56,8 +56,8 @@ import org.eclipse.jgit.ignore.FastIgnoreRule; import org.eclipse.jgit.internal.JGitText; /** - * Various {@link String} related utility methods, written mostly to avoid - * generation of new String objects (e.g. via splitting Strings etc). + * Various {@link java.lang.String} related utility methods, written mostly to + * avoid generation of new String objects (e.g. via splitting Strings etc). */ public class Strings { @@ -67,6 +67,8 @@ public class Strings { } /** + * Strip trailing characters + * * @param pattern * non null * @param c @@ -87,6 +89,8 @@ public class Strings { } /** + * Strip trailing whitespace characters + * * @param pattern * non null * @return new string with all trailing whitespace removed @@ -105,10 +109,12 @@ public class Strings { } /** + * Check if pattern is a directory pattern ending with a path separator + * * @param pattern * non null - * @return true if the last character, which is not whitespace, is a path - * separator + * @return {@code true} if the last character, which is not whitespace, is a + * path separator */ public static boolean isDirectoryPattern(String pattern) { for (int i = pattern.length() - 1; i >= 0; i--) { @@ -439,12 +445,10 @@ public class Strings { try { return Pattern.compile(sb.toString()); } catch (PatternSyntaxException e) { - InvalidPatternException patternException = new InvalidPatternException( + throw new InvalidPatternException( MessageFormat.format(JGitText.get().invalidIgnoreRule, pattern), - pattern); - patternException.initCause(e); - throw patternException; + pattern, e); } } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/TrailingAsteriskMatcher.java b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/TrailingAsteriskMatcher.java index 2e148f4a6f..7df42b76cf 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/TrailingAsteriskMatcher.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/TrailingAsteriskMatcher.java @@ -55,6 +55,7 @@ public class TrailingAsteriskMatcher extends NameMatcher { "Pattern must have trailing asterisk: " + pattern); //$NON-NLS-1$ } + /** {@inheritDoc} */ @Override public boolean matches(String segment, int startIncl, int endExcl, boolean assumeDirectory) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/WildCardMatcher.java b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/WildCardMatcher.java index f64050f83c..ca8c581d4b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/WildCardMatcher.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/WildCardMatcher.java @@ -50,7 +50,7 @@ import org.eclipse.jgit.errors.InvalidPatternException; /** * Matcher built from path segments containing wildcards. This matcher converts - * glob wildcards to Java {@link Pattern}'s. + * glob wildcards to Java {@link java.util.regex.Pattern}'s. * <p> * This class is immutable and thread safe. */ @@ -64,6 +64,7 @@ public class WildCardMatcher extends NameMatcher { p = convertGlob(subPattern); } + /** {@inheritDoc} */ @Override public boolean matches(String segment, int startIncl, int endExcl, boolean assumeDirectory) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/WildMatcher.java b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/WildMatcher.java index 363b3cee84..ba8015cc09 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/WildMatcher.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/ignore/internal/WildMatcher.java @@ -61,12 +61,14 @@ public final class WildMatcher extends AbstractMatcher { super(WILDMATCH, false); } + /** {@inheritDoc} */ @Override public final boolean matches(String path, boolean assumeDirectory, boolean pathMatch) { return true; } + /** {@inheritDoc} */ @Override public final boolean matches(String segment, int startIncl, int endExcl, boolean assumeDirectory) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/JGitText.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/JGitText.java index b990f0a9a1..24bc7b5c98 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/JGitText.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/JGitText.java @@ -53,6 +53,8 @@ import org.eclipse.jgit.nls.TranslationBundle; public class JGitText extends TranslationBundle { /** + * Get an instance of this translation bundle + * * @return an instance of this translation bundle */ public static JGitText get() { @@ -81,6 +83,7 @@ public class JGitText extends TranslationBundle { /***/ public String atLeastTwoFiltersNeeded; /***/ public String atomicPushNotSupported; /***/ public String atomicRefUpdatesNotSupported; + /***/ public String atomicSymRefNotSupported; /***/ public String authenticationNotSupported; /***/ public String badBase64InputCharacterAt; /***/ public String badEntryDelimiter; @@ -100,6 +103,7 @@ public class JGitText extends TranslationBundle { /***/ public String blobNotFound; /***/ public String blobNotFoundForPath; /***/ public String blockSizeNotPowerOf2; + /***/ public String bothRefTargetsMustNotBeNull; /***/ public String branchNameInvalid; /***/ public String buildingBitmaps; /***/ public String cachedPacksPreventsIndexCreation; @@ -189,6 +193,9 @@ public class JGitText extends TranslationBundle { /***/ public String commitOnRepoWithoutHEADCurrentlyNotSupported; /***/ public String commitAmendOnInitialNotPossible; /***/ public String compressingObjects; + /***/ public String configSubsectionContainsNewline; + /***/ public String configSubsectionContainsNullByte; + /***/ public String configValueContainsNullByte; /***/ public String configHandleIsStale; /***/ public String connectionFailed; /***/ public String connectionTimeOut; @@ -343,6 +350,7 @@ public class JGitText extends TranslationBundle { /***/ public String expectedACKNAKGot; /***/ public String expectedBooleanStringValue; /***/ public String expectedCharacterEncodingGuesses; + /***/ public String expectedDirectoryNotSubmodule; /***/ public String expectedEOFReceived; /***/ public String expectedGot; /***/ public String expectedLessThanGot; @@ -499,6 +507,7 @@ public class JGitText extends TranslationBundle { /***/ public String months; /***/ public String monthsAgo; /***/ public String multipleMergeBasesFor; + /***/ public String nameMustNotBeNullOrEmpty; /***/ public String need2Arguments; /***/ public String needPackOut; /***/ public String needsAtLeastOneEntry; @@ -514,6 +523,7 @@ public class JGitText extends TranslationBundle { /***/ public String noMergeHeadSpecified; /***/ public String nonBareLinkFilesNotSupported; /***/ public String noSuchRef; + /***/ public String noSuchSubmodule; /***/ public String notABoolean; /***/ public String notABundle; /***/ public String notADIRCFile; @@ -757,6 +767,7 @@ public class JGitText extends TranslationBundle { /***/ public String unexpectedRefReport; /***/ public String unexpectedReportLine; /***/ public String unexpectedReportLine2; + /***/ public String unexpectedSubmoduleStatus; /***/ public String unknownOrUnsupportedCommand; /***/ public String unknownDIRCVersion; /***/ public String unknownHost; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/fsck/FsckError.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/fsck/FsckError.java index 588ed9bf8a..131b0048ae 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/fsck/FsckError.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/fsck/FsckError.java @@ -51,7 +51,9 @@ import org.eclipse.jgit.errors.CorruptPackIndexException.ErrorType; import org.eclipse.jgit.lib.ObjectChecker; import org.eclipse.jgit.lib.ObjectId; -/** Holds all fsck errors of a git repository. */ +/** + * Holds all fsck errors of a git repository. + */ public class FsckError { /** Represents a corrupt object. */ public static class CorruptObject { @@ -130,22 +132,38 @@ public class FsckError { private final Set<String> nonCommitHeads = new HashSet<>(); - /** @return corrupt objects from all pack files. */ + /** + * Get corrupt objects from all pack files + * + * @return corrupt objects from all pack files + */ public Set<CorruptObject> getCorruptObjects() { return corruptObjects; } - /** @return missing objects that should present in pack files. */ + /** + * Get missing objects that should present in pack files + * + * @return missing objects that should present in pack files + */ public Set<ObjectId> getMissingObjects() { return missingObjects; } - /** @return corrupt index files associated with the packs. */ + /** + * Get corrupt index files associated with the packs + * + * @return corrupt index files associated with the packs + */ public Set<CorruptIndex> getCorruptIndices() { return corruptIndices; } - /** @return refs/heads/* point to non-commit object. */ + /** + * Get refs/heads/* which point to non-commit object + * + * @return refs/heads/* which point to non-commit object + */ public Set<String> getNonCommitHeads() { return nonCommitHeads; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/fsck/FsckPackParser.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/fsck/FsckPackParser.java index 3a678a72df..5397ba4798 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/fsck/FsckPackParser.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/fsck/FsckPackParser.java @@ -62,13 +62,14 @@ import org.eclipse.jgit.internal.storage.dfs.ReadableChannel; import org.eclipse.jgit.internal.storage.file.PackIndex; import org.eclipse.jgit.internal.storage.file.PackIndex.MutableEntry; import org.eclipse.jgit.lib.AnyObjectId; -import org.eclipse.jgit.lib.ObjectChecker; import org.eclipse.jgit.lib.ObjectDatabase; import org.eclipse.jgit.lib.ObjectIdOwnerMap; import org.eclipse.jgit.transport.PackParser; import org.eclipse.jgit.transport.PackedObjectInfo; -/** A read-only pack parser for object validity checking. */ +/** + * A read-only pack parser for object validity checking. + */ public class FsckPackParser extends PackParser { private final CRC32 crc; @@ -83,6 +84,8 @@ public class FsckPackParser extends PackParser { private int blockSize; /** + * Constructor for FsckPackParser + * * @param db * the object database which stores repository's data. * @param channel @@ -96,6 +99,7 @@ public class FsckPackParser extends PackParser { this.blockSize = channel.blockSize() > 0 ? channel.blockSize() : 65536; } + /** {@inheritDoc} */ @Override protected void onPackHeader(long objCnt) throws IOException { if (expectedObjectCount >= 0) { @@ -107,41 +111,48 @@ public class FsckPackParser extends PackParser { } } + /** {@inheritDoc} */ @Override protected void onBeginWholeObject(long streamPosition, int type, long inflatedSize) throws IOException { crc.reset(); } + /** {@inheritDoc} */ @Override protected void onObjectHeader(Source src, byte[] raw, int pos, int len) throws IOException { crc.update(raw, pos, len); } + /** {@inheritDoc} */ @Override protected void onObjectData(Source src, byte[] raw, int pos, int len) throws IOException { crc.update(raw, pos, len); } + /** {@inheritDoc} */ @Override protected void onEndWholeObject(PackedObjectInfo info) throws IOException { info.setCRC((int) crc.getValue()); } + /** {@inheritDoc} */ @Override protected void onBeginOfsDelta(long deltaStreamPosition, long baseStreamPosition, long inflatedSize) throws IOException { crc.reset(); } + /** {@inheritDoc} */ @Override protected void onBeginRefDelta(long deltaStreamPosition, AnyObjectId baseId, long inflatedSize) throws IOException { crc.reset(); } + /** {@inheritDoc} */ @Override protected UnresolvedDelta onEndDelta() throws IOException { UnresolvedDelta delta = new UnresolvedDelta(); @@ -149,12 +160,14 @@ public class FsckPackParser extends PackParser { return delta; } + /** {@inheritDoc} */ @Override protected void onInflatedObjectData(PackedObjectInfo obj, int typeCode, byte[] data) throws IOException { // FsckPackParser ignores this event. } + /** {@inheritDoc} */ @Override protected void verifySafeObject(final AnyObjectId id, final int type, final byte[] data) { @@ -170,11 +183,13 @@ public class FsckPackParser extends PackParser { } } + /** {@inheritDoc} */ @Override protected void onPackFooter(byte[] hash) throws IOException { // Do nothing. } + /** {@inheritDoc} */ @Override protected boolean onAppendBase(int typeCode, byte[] data, PackedObjectInfo info) throws IOException { @@ -182,11 +197,13 @@ public class FsckPackParser extends PackParser { return false; } + /** {@inheritDoc} */ @Override protected void onEndThinPack() throws IOException { // Do nothing. } + /** {@inheritDoc} */ @Override protected ObjectTypeAndSize seekDatabase(PackedObjectInfo obj, ObjectTypeAndSize info) throws IOException { @@ -195,6 +212,7 @@ public class FsckPackParser extends PackParser { return readObjectHeader(info); } + /** {@inheritDoc} */ @Override protected ObjectTypeAndSize seekDatabase(UnresolvedDelta delta, ObjectTypeAndSize info) throws IOException { @@ -203,6 +221,7 @@ public class FsckPackParser extends PackParser { return readObjectHeader(info); } + /** {@inheritDoc} */ @Override protected int readDatabase(byte[] dst, int pos, int cnt) throws IOException { @@ -247,11 +266,13 @@ public class FsckPackParser extends PackParser { return buf.array(); } + /** {@inheritDoc} */ @Override protected boolean checkCRC(int oldCRC) { return oldCRC == (int) crc.getValue(); } + /** {@inheritDoc} */ @Override protected void onStoreStream(byte[] raw, int pos, int len) throws IOException { @@ -259,7 +280,11 @@ public class FsckPackParser extends PackParser { } /** - * @return corrupt objects that reported by {@link ObjectChecker}. + * Get corrupt objects reported by + * {@link org.eclipse.jgit.lib.ObjectChecker} + * + * @return corrupt objects that are reported by + * {@link org.eclipse.jgit.lib.ObjectChecker}. */ public Set<CorruptObject> getCorruptObjects() { return corruptObjects; @@ -270,7 +295,7 @@ public class FsckPackParser extends PackParser { * * @param idx * index file associate with the pack - * @throws CorruptPackIndexException + * @throws org.eclipse.jgit.errors.CorruptPackIndexException * when the index file is corrupt. */ public void verifyIndex(PackIndex idx) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchConstants.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchConstants.java index 171c059db1..168ab8c26d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchConstants.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchConstants.java @@ -45,7 +45,9 @@ package org.eclipse.jgit.internal.ketch; import org.eclipse.jgit.revwalk.FooterKey; -/** Frequently used constants in a Ketch system. */ +/** + * Frequently used constants in a Ketch system. + */ public class KetchConstants { /** * Default reference namespace holding {@link #ACCEPTED} and diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchLeader.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchLeader.java index 3bcd6bcb24..bc5ba3926b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchLeader.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchLeader.java @@ -69,11 +69,15 @@ import org.slf4j.LoggerFactory; /** * A leader managing consensus across remote followers. * <p> - * A leader instance starts up in {@link State#CANDIDATE} and tries to begin a - * new term by sending an {@link ElectionRound} to all replicas. Its term starts - * if a majority of replicas have accepted this leader instance for the term. + * A leader instance starts up in + * {@link org.eclipse.jgit.internal.ketch.KetchLeader.State#CANDIDATE} and tries + * to begin a new term by sending an + * {@link org.eclipse.jgit.internal.ketch.ElectionRound} to all replicas. Its + * term starts if a majority of replicas have accepted this leader instance for + * the term. * <p> - * Once elected by a majority the instance enters {@link State#LEADER} and runs + * Once elected by a majority the instance enters + * {@link org.eclipse.jgit.internal.ketch.KetchLeader.State#LEADER} and runs * proposals offered to {@link #queueProposal(Proposal)}. This continues until * the leader is timed out for inactivity, or is deposed by a competing leader * gaining its own majority. @@ -81,36 +85,42 @@ import org.slf4j.LoggerFactory; * Once timed out or deposed this {@code KetchLeader} instance should be * discarded, and a new instance takes over. * <p> - * Each leader instance coordinates a group of {@link KetchReplica}s. Replica - * instances are owned by the leader instance and must be discarded when the - * leader is discarded. + * Each leader instance coordinates a group of + * {@link org.eclipse.jgit.internal.ketch.KetchReplica}s. Replica instances are + * owned by the leader instance and must be discarded when the leader is + * discarded. * <p> * In Ketch all push requests are issued through the leader. The steps are as - * follows (see {@link KetchPreReceive} for an example): + * follows (see {@link org.eclipse.jgit.internal.ketch.KetchPreReceive} for an + * example): * <ul> - * <li>Create a {@link Proposal} with the + * <li>Create a {@link org.eclipse.jgit.internal.ketch.Proposal} with the * {@link org.eclipse.jgit.transport.ReceiveCommand}s that represent the push. * <li>Invoke {@link #queueProposal(Proposal)} on the leader instance. - * <li>Wait for consensus with {@link Proposal#await()}. - * <li>To examine the status of the push, check {@link Proposal#getCommands()}, - * looking at + * <li>Wait for consensus with + * {@link org.eclipse.jgit.internal.ketch.Proposal#await()}. + * <li>To examine the status of the push, check + * {@link org.eclipse.jgit.internal.ketch.Proposal#getCommands()}, looking at * {@link org.eclipse.jgit.internal.storage.reftree.Command#getResult()}. * </ul> * <p> * The leader gains consensus by first pushing the needed objects and a - * {@link RefTree} representing the desired target repository state to the - * {@code refs/txn/accepted} branch on each of the replicas. Once a majority has - * succeeded, the leader commits the state by either pushing the - * {@code refs/txn/accepted} value to {@code refs/txn/committed} (for - * Ketch-aware replicas) or by pushing updates to {@code refs/heads/master}, - * etc. for stock Git replicas. + * {@link org.eclipse.jgit.internal.storage.reftree.RefTree} representing the + * desired target repository state to the {@code refs/txn/accepted} branch on + * each of the replicas. Once a majority has succeeded, the leader commits the + * state by either pushing the {@code refs/txn/accepted} value to + * {@code refs/txn/committed} (for Ketch-aware replicas) or by pushing updates + * to {@code refs/heads/master}, etc. for stock Git replicas. * <p> * Internally, the actual transport to replicas is performed on background - * threads via the {@link KetchSystem}'s executor service. For performance, the - * {@link KetchLeader}, {@link KetchReplica} and {@link Proposal} objects share - * some state, and may invoke each other's methods on different threads. This - * access is protected by the leader's {@link #lock} object. Care must be taken - * to prevent concurrent access by correctly obtaining the leader's lock. + * threads via the {@link org.eclipse.jgit.internal.ketch.KetchSystem}'s + * executor service. For performance, the + * {@link org.eclipse.jgit.internal.ketch.KetchLeader}, + * {@link org.eclipse.jgit.internal.ketch.KetchReplica} and + * {@link org.eclipse.jgit.internal.ketch.Proposal} objects share some state, + * and may invoke each other's methods on different threads. This access is + * protected by the leader's {@link #lock} object. Care must be taken to prevent + * concurrent access by correctly obtaining the leader's lock. */ public abstract class KetchLeader { private static final Logger log = LoggerFactory.getLogger(KetchLeader.class); @@ -295,7 +305,7 @@ public abstract class KetchLeader { * The caller will close the repository. * * @return opened repository for use by the leader thread. - * @throws IOException + * @throws java.io.IOException * cannot reopen the repository for the leader. */ protected abstract Repository openRepository() throws IOException; @@ -307,16 +317,17 @@ public abstract class KetchLeader { * checked to look for risks of conflicts, and then submitted into the queue * for distribution as soon as possible. * <p> - * Callers must use {@link Proposal#await()} to see if the proposal is done. + * Callers must use {@link org.eclipse.jgit.internal.ketch.Proposal#await()} + * to see if the proposal is done. * * @param proposal * the proposed reference updates to queue for consideration. * Once execution is complete the individual reference result * fields will be populated with the outcome. - * @throws InterruptedException + * @throws java.lang.InterruptedException * current thread was interrupted. The proposal may have been * aborted if it was not yet queued for execution. - * @throws IOException + * @throws java.io.IOException * unrecoverable error preventing proposals from being attempted * by this leader. */ @@ -577,7 +588,11 @@ public abstract class KetchLeader { } } - /** @return snapshot this leader. */ + /** + * Snapshot this leader + * + * @return snapshot of this leader + */ public LeaderSnapshot snapshot() { lock.lock(); try { @@ -599,7 +614,9 @@ public abstract class KetchLeader { } } - /** Gracefully shutdown this leader and cancel outstanding operations. */ + /** + * Gracefully shutdown this leader and cancel outstanding operations. + */ public void shutdown() { lock.lock(); try { @@ -617,6 +634,7 @@ public abstract class KetchLeader { } } + /** {@inheritDoc} */ @Override public String toString() { return snapshot().toString(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchLeaderCache.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchLeaderCache.java index ba033c1a42..de0da4f32f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchLeaderCache.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchLeaderCache.java @@ -82,7 +82,7 @@ public class KetchLeaderCache { * @param repo * repository to get the leader for. * @return the leader instance for the repository. - * @throws URISyntaxException + * @throws java.net.URISyntaxException * remote configuration contains an invalid URL. */ public KetchLeader get(Repository repo) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchPreReceive.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchPreReceive.java index 1b4307f3fb..53d286539d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchPreReceive.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchPreReceive.java @@ -64,9 +64,10 @@ import org.slf4j.LoggerFactory; /** * PreReceiveHook for handling push traffic in a Ketch system. * <p> - * Install an instance on {@link ReceivePack} to capture the commands and other - * connection state and relay them through the {@link KetchLeader}, allowing the - * leader to gain consensus about the new reference state. + * Install an instance on {@link org.eclipse.jgit.transport.ReceivePack} to + * capture the commands and other connection state and relay them through the + * {@link org.eclipse.jgit.internal.ketch.KetchLeader}, allowing the leader to + * gain consensus about the new reference state. */ public class KetchPreReceive implements PreReceiveHook { private static final Logger log = LoggerFactory.getLogger(KetchPreReceive.class); @@ -74,7 +75,8 @@ public class KetchPreReceive implements PreReceiveHook { private final KetchLeader leader; /** - * Construct a hook executing updates through a {@link KetchLeader}. + * Construct a hook executing updates through a + * {@link org.eclipse.jgit.internal.ketch.KetchLeader}. * * @param leader * leader for this repository. @@ -83,6 +85,7 @@ public class KetchPreReceive implements PreReceiveHook { this.leader = leader; } + /** {@inheritDoc} */ @Override public void onPreReceive(ReceivePack rp, Collection<ReceiveCommand> cmds) { cmds = ReceiveCommand.filter(cmds, NOT_ATTEMPTED); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchReplica.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchReplica.java index a30bbb260a..a0176d7d2e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchReplica.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchReplica.java @@ -82,26 +82,32 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** - * A Ketch replica, either {@link LocalReplica} or {@link RemoteGitReplica}. + * A Ketch replica, either {@link org.eclipse.jgit.internal.ketch.LocalReplica} + * or {@link org.eclipse.jgit.internal.ketch.RemoteGitReplica}. * <p> * Replicas can be either a stock Git replica, or a Ketch-aware replica. * <p> * A stock Git replica has no special knowledge of Ketch and simply stores * objects and references. Ketch communicates with the stock Git replica using - * the Git push wire protocol. The {@link KetchLeader} commits an agreed upon + * the Git push wire protocol. The + * {@link org.eclipse.jgit.internal.ketch.KetchLeader} commits an agreed upon * state by pushing all references to the Git replica, for example * {@code "refs/heads/master"} is pushed during commit. Stock Git replicas use - * {@link CommitMethod#ALL_REFS} to record the final state. + * {@link org.eclipse.jgit.internal.ketch.KetchReplica.CommitMethod#ALL_REFS} to + * record the final state. * <p> * Ketch-aware replicas understand the {@code RefTree} sent during the proposal * and during commit are able to update their own reference space to match the * state represented by the {@code RefTree}. Ketch-aware replicas typically use * a {@link org.eclipse.jgit.internal.storage.reftree.RefTreeDatabase} and - * {@link CommitMethod#TXN_COMMITTED} to record the final state. + * {@link org.eclipse.jgit.internal.ketch.KetchReplica.CommitMethod#TXN_COMMITTED} + * to record the final state. * <p> - * KetchReplica instances are tightly coupled with a single {@link KetchLeader}. - * Some state may be accessed by the leader thread and uses the leader's own - * {@link KetchLeader#lock} to protect shared data. + * KetchReplica instances are tightly coupled with a single + * {@link org.eclipse.jgit.internal.ketch.KetchLeader}. Some state may be + * accessed by the leader thread and uses the leader's own + * {@link org.eclipse.jgit.internal.ketch.KetchLeader#lock} to protect shared + * data. */ public abstract class KetchReplica { static final Logger log = LoggerFactory.getLogger(KetchReplica.class); @@ -223,37 +229,65 @@ public abstract class KetchReplica { this.queued = new ArrayList<>(4); } - /** @return system configuration. */ + /** + * Get system configuration. + * + * @return system configuration. + */ public KetchSystem getSystem() { return getLeader().getSystem(); } - /** @return leader instance this replica follows. */ + /** + * Get leader instance this replica follows. + * + * @return leader instance this replica follows. + */ public KetchLeader getLeader() { return leader; } - /** @return unique-ish name for debugging. */ + /** + * Get unique-ish name for debugging. + * + * @return unique-ish name for debugging. + */ public String getName() { return replicaName; } - /** @return description of this replica for error/debug logging purposes. */ + /** + * Get description of this replica for error/debug logging purposes. + * + * @return description of this replica for error/debug logging purposes. + */ protected String describeForLog() { return getName(); } - /** @return how the replica participates in this Ketch system. */ + /** + * Get how the replica participates in this Ketch system. + * + * @return how the replica participates in this Ketch system. + */ public Participation getParticipation() { return participation; } - /** @return how Ketch will commit to the repository. */ + /** + * Get how Ketch will commit to the repository. + * + * @return how Ketch will commit to the repository. + */ public CommitMethod getCommitMethod() { return commitMethod; } - /** @return when Ketch will commit to the repository. */ + /** + * Get when Ketch will commit to the repository. + * + * @return when Ketch will commit to the repository. + */ public CommitSpeed getCommitSpeed() { return commitSpeed; } @@ -264,7 +298,8 @@ public abstract class KetchReplica { * Default implementation cancels any scheduled retry. Subclasses may add * additional logic before or after calling {@code super.shutdown()}. * <p> - * Called with {@link KetchLeader#lock} held by caller. + * Called with {@link org.eclipse.jgit.internal.ketch.KetchLeader#lock} held + * by caller. */ protected void shutdown() { Future<?> f = retryFuture; @@ -541,8 +576,8 @@ public abstract class KetchReplica { /** * Begin executing a single push. * <p> - * This method must move processing onto another thread. - * Called with {@link KetchLeader#lock} held by caller. + * This method must move processing onto another thread. Called with + * {@link org.eclipse.jgit.internal.ketch.KetchLeader#lock} held by caller. * * @param req * the request to send to the replica. @@ -666,20 +701,21 @@ public abstract class KetchReplica { /** * Fetch objects from the remote using the calling thread. * <p> - * Called without {@link KetchLeader#lock}. + * Called without {@link org.eclipse.jgit.internal.ketch.KetchLeader#lock}. * * @param repo * local repository to fetch objects into. * @param req * the request to fetch from a replica. - * @throws IOException + * @throws java.io.IOException * communication with the replica was not possible. */ protected abstract void blockingFetch(Repository repo, ReplicaFetchRequest req) throws IOException; /** - * Build a list of commands to commit {@link CommitMethod#ALL_REFS}. + * Build a list of commands to commit + * {@link org.eclipse.jgit.internal.ketch.KetchReplica.CommitMethod#ALL_REFS}. * * @param git * local leader repository to read committed state from. @@ -689,7 +725,7 @@ public abstract class KetchReplica { * @param committed * state being pushed to {@code refs/txn/committed}. * @return commands to update during commit. - * @throws IOException + * @throws java.io.IOException * cannot read the committed state. */ protected Collection<ReceiveCommand> prepareCommit(Repository git, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchSystem.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchSystem.java index 33f526e52c..1908d6c98a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchSystem.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchSystem.java @@ -81,12 +81,17 @@ import org.slf4j.LoggerFactory; * Full scale installations are expected to subclass and override methods to * provide consistent configuration across all managed repositories. * <p> - * Servers should configure their own {@link ScheduledExecutorService}. + * Servers should configure their own + * {@link java.util.concurrent.ScheduledExecutorService}. */ public class KetchSystem { private static final Random RNG = new Random(); - /** @return default executor, one thread per available processor. */ + /** + * Get default executor, one thread per available processor. + * + * @return default executor, one thread per available processor. + */ public static ScheduledExecutorService defaultExecutor() { return DefaultExecutorHolder.I; } @@ -98,7 +103,9 @@ public class KetchSystem { private final String txnCommitted; private final String txnStage; - /** Create a default system with a thread pool of 1 thread per CPU. */ + /** + * Create a default system with a thread pool of 1 thread per CPU. + */ public KetchSystem() { this(defaultExecutor(), new MonotonicSystemClock(), DEFAULT_TXN_NAMESPACE); } @@ -125,17 +132,29 @@ public class KetchSystem { this.txnStage = txnNamespace + STAGE; } - /** @return executor to perform background operations. */ + /** + * Get executor to perform background operations. + * + * @return executor to perform background operations. + */ public ScheduledExecutorService getExecutor() { return executor; } - /** @return clock to obtain timestamps from. */ + /** + * Get clock to obtain timestamps from. + * + * @return clock to obtain timestamps from. + */ public MonotonicClock getClock() { return clock; } /** + * Get how long the leader will wait for the {@link #getClock()}'s + * {@code ProposedTimestamp} used in commits proposed to the RefTree graph + * ({@link #getTxnAccepted()}) + * * @return how long the leader will wait for the {@link #getClock()}'s * {@code ProposedTimestamp} used in commits proposed to the RefTree * graph ({@link #getTxnAccepted()}). Defaults to 5 seconds. @@ -145,8 +164,12 @@ public class KetchSystem { } /** - * @return true if elections should require monotonically increasing commit - * timestamps. This requires a very good {@link MonotonicClock}. + * Whether elections should require monotonically increasing commit + * timestamps + * + * @return {@code true} if elections should require monotonically increasing + * commit timestamps. This requires a very good + * {@link org.eclipse.jgit.util.time.MonotonicClock}. */ public boolean requireMonotonicLeaderElections() { return false; @@ -161,22 +184,36 @@ public class KetchSystem { return txnNamespace; } - /** @return name of the accepted RefTree graph. */ + /** + * Get name of the accepted RefTree graph. + * + * @return name of the accepted RefTree graph. + */ public String getTxnAccepted() { return txnAccepted; } - /** @return name of the committed RefTree graph. */ + /** + * Get name of the committed RefTree graph. + * + * @return name of the committed RefTree graph. + */ public String getTxnCommitted() { return txnCommitted; } - /** @return prefix for staged objects, e.g. {@code "refs/txn/stage/"}. */ + /** + * Get prefix for staged objects, e.g. {@code "refs/txn/stage/"}. + * + * @return prefix for staged objects, e.g. {@code "refs/txn/stage/"}. + */ public String getTxnStage() { return txnStage; } /** + * Create new committer {@code PersonIdent} for ketch system + * * @param time * timestamp for the committer. * @return identity line for the committer header of a RefTreeGraph. @@ -220,7 +257,7 @@ public class KetchSystem { * @param repo * local repository stored by the leader. * @return leader instance. - * @throws URISyntaxException + * @throws java.net.URISyntaxException * a follower configuration contains an unsupported URI. */ public KetchLeader createLeader(final Repository repo) @@ -246,7 +283,7 @@ public class KetchSystem { * @param repo * repository to get the replicas of. * @return collection of replicas for the specified repository. - * @throws URISyntaxException + * @throws java.net.URISyntaxException * a configured URI is invalid. */ protected List<KetchReplica> createReplicas(KetchLeader leader, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchText.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchText.java index b6c3bc92c5..fa34a88cf9 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchText.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/KetchText.java @@ -46,9 +46,15 @@ package org.eclipse.jgit.internal.ketch; import org.eclipse.jgit.nls.NLS; import org.eclipse.jgit.nls.TranslationBundle; -/** Translation bundle for the Ketch implementation. */ +/** + * Translation bundle for the Ketch implementation. + */ public class KetchText extends TranslationBundle { - /** @return instance of this translation bundle. */ + /** + * Get an instance of this translation bundle. + * + * @return instance of this translation bundle. + */ public static KetchText get() { return NLS.getBundleFor(KetchText.class); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LagCheck.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LagCheck.java index 757c19ac94..c09d872f0a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LagCheck.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LagCheck.java @@ -86,6 +86,7 @@ class LagCheck implements AutoCloseable { rw.setRetainBody(false); } + /** {@inheritDoc} */ @Override public void close() { if (rw != null) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LeaderSnapshot.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LeaderSnapshot.java index 28a49df97a..4c8bd06001 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LeaderSnapshot.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LeaderSnapshot.java @@ -53,7 +53,9 @@ import java.util.List; import org.eclipse.jgit.annotations.Nullable; import org.eclipse.jgit.lib.ObjectId; -/** A snapshot of a leader and its view of the world. */ +/** + * A snapshot of a leader and its view of the world. + */ public class LeaderSnapshot { final List<ReplicaSnapshot> replicas = new ArrayList<>(); KetchLeader.State state; @@ -65,17 +67,28 @@ public class LeaderSnapshot { LeaderSnapshot() { } - /** @return unmodifiable view of configured replicas. */ + /** + * Get unmodifiable view of configured replicas. + * + * @return unmodifiable view of configured replicas. + */ public Collection<ReplicaSnapshot> getReplicas() { return Collections.unmodifiableList(replicas); } - /** @return current state of the leader. */ + /** + * Get current state of the leader. + * + * @return current state of the leader. + */ public KetchLeader.State getState() { return state; } /** + * Whether the leader is not running a round to reach consensus, and has no + * rounds queued. + * * @return {@code true} if the leader is not running a round to reach * consensus, and has no rounds queued. */ @@ -84,14 +97,19 @@ public class LeaderSnapshot { } /** + * Get term of this leader + * * @return term of this leader. Valid only if {@link #getState()} is - * currently {@link KetchLeader.State#LEADER}. + * currently + * {@link org.eclipse.jgit.internal.ketch.KetchLeader.State#LEADER}. */ public long getTerm() { return term; } /** + * Get end of the leader's log + * * @return end of the leader's log; null if leader hasn't started up enough * to begin its own election. */ @@ -101,6 +119,9 @@ public class LeaderSnapshot { } /** + * Get state the leader knows is committed on a majority of participant + * replicas + * * @return state the leader knows is committed on a majority of participant * replicas. Null until the leader instance has committed a log * index within its own term. @@ -110,6 +131,7 @@ public class LeaderSnapshot { return committedIndex; } + /** {@inheritDoc} */ @Override public String toString() { StringBuilder s = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LocalReplica.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LocalReplica.java index 907eecbef4..9c37a90cee 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LocalReplica.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LocalReplica.java @@ -67,7 +67,10 @@ import org.eclipse.jgit.transport.ReceiveCommand; import org.eclipse.jgit.util.time.MonotonicClock; import org.eclipse.jgit.util.time.ProposedTimestamp; -/** Ketch replica running on the same system as the {@link KetchLeader}. */ +/** + * Ketch replica running on the same system as the + * {@link org.eclipse.jgit.internal.ketch.KetchLeader}. + */ public class LocalReplica extends KetchReplica { /** * Configure a local replica. @@ -83,6 +86,7 @@ public class LocalReplica extends KetchReplica { super(leader, name, cfg); } + /** {@inheritDoc} */ @Override protected String describeForLog() { return String.format("%s (leader)", getName()); //$NON-NLS-1$ @@ -116,6 +120,7 @@ public class LocalReplica extends KetchReplica { getSystem().getTxnCommitted())); } + /** {@inheritDoc} */ @Override protected void startPush(final ReplicaPushRequest req) { getSystem().getExecutor().execute(new Runnable() { @@ -137,6 +142,7 @@ public class LocalReplica extends KetchReplica { }); } + /** {@inheritDoc} */ @Override protected void blockingFetch(Repository repo, ReplicaFetchRequest req) throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LogIndex.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LogIndex.java index 350c8ed62e..eb600bb41e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LogIndex.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/LogIndex.java @@ -54,17 +54,18 @@ import org.eclipse.jgit.lib.ObjectId; * LogIndex provides a performance optimization for Ketch, the same information * can be obtained from {@link org.eclipse.jgit.revwalk.RevWalk}. * <p> - * Index values are only valid within a single {@link KetchLeader} instance - * after it has won an election. By restricting scope to a single leader new - * leaders do not need to traverse the entire history to determine the next - * {@code index} for new proposals. This differs from Raft, where leader - * election uses the log index and the term number to determine which replica - * holds a sufficiently up-to-date log. Since Ketch uses Git objects for storage - * of its replicated log, it keeps the term number as Raft does but uses - * standard Git operations to imply the log index. + * Index values are only valid within a single + * {@link org.eclipse.jgit.internal.ketch.KetchLeader} instance after it has won + * an election. By restricting scope to a single leader new leaders do not need + * to traverse the entire history to determine the next {@code index} for new + * proposals. This differs from Raft, where leader election uses the log index + * and the term number to determine which replica holds a sufficiently + * up-to-date log. Since Ketch uses Git objects for storage of its replicated + * log, it keeps the term number as Raft does but uses standard Git operations + * to imply the log index. * <p> - * {@link Round#runAsync(AnyObjectId)} bumps the index as each new round is - * constructed. + * {@link org.eclipse.jgit.internal.ketch.Round#runAsync(AnyObjectId)} bumps the + * index as each new round is constructed. */ public class LogIndex extends ObjectId { static LogIndex unknown(AnyObjectId id) { @@ -82,7 +83,11 @@ public class LogIndex extends ObjectId { return new LogIndex(id, index + 1); } - /** @return index provided by the current leader instance. */ + /** + * Get index provided by the current leader instance. + * + * @return index provided by the current leader instance. + */ public long getIndex() { return index; } @@ -103,6 +108,9 @@ public class LogIndex extends ObjectId { } /** + * Create string suitable for debug logging containing the log index and + * abbreviated ObjectId. + * * @return string suitable for debug logging containing the log index and * abbreviated ObjectId. */ @@ -111,6 +119,7 @@ public class LogIndex extends ObjectId { return String.format("%5d/%s", index, abbreviate(6).name()); //$NON-NLS-1$ } + /** {@inheritDoc} */ @SuppressWarnings("boxing") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/Proposal.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/Proposal.java index 12d3f4c9c8..db2ad23012 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/Proposal.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/Proposal.java @@ -78,10 +78,11 @@ import org.eclipse.jgit.util.time.ProposedTimestamp; * area under the {@code refs/txn/stage/} namespace. If the proposal succeeds * then the changes are durable and the leader can commit the proposal. * <p> - * Proposals are executed by {@link KetchLeader#queueProposal(Proposal)}, which - * runs them asynchronously in the background. Proposals are thread-safe futures - * allowing callers to {@link #await()} for results or be notified by callback - * using {@link #addListener(Runnable)}. + * Proposals are executed by + * {@link org.eclipse.jgit.internal.ketch.KetchLeader#queueProposal(Proposal)}, + * which runs them asynchronously in the background. Proposals are thread-safe + * futures allowing callers to {@link #await()} for results or be notified by + * callback using {@link #addListener(Runnable)}. */ public class Proposal { /** Current state of the proposal. */ @@ -146,9 +147,9 @@ public class Proposal { * walker to assist in preparing commands. * @param cmds * list of pending commands. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * newId of a command is not found locally. - * @throws IOException + * @throws java.io.IOException * local objects cannot be accessed. */ public Proposal(RevWalk rw, Collection<ReceiveCommand> cmds) @@ -166,12 +167,20 @@ public class Proposal { return Collections.unmodifiableList(commands); } - /** @return commands from this proposal. */ + /** + * Get commands from this proposal. + * + * @return commands from this proposal. + */ public Collection<Command> getCommands() { return commands; } - /** @return optional author of the proposal. */ + /** + * Get optional author of the proposal. + * + * @return optional author of the proposal. + */ @Nullable public PersonIdent getAuthor() { return author; @@ -189,7 +198,11 @@ public class Proposal { return this; } - /** @return optional message for the commit log of the RefTree. */ + /** + * Get optional message for the commit log of the RefTree. + * + * @return optional message for the commit log of the RefTree. + */ @Nullable public String getMessage() { return message; @@ -207,7 +220,11 @@ public class Proposal { return this; } - /** @return optional certificate signing the references. */ + /** + * Get optional certificate signing the references. + * + * @return optional certificate signing the references. + */ @Nullable public PushCertificate getPushCertificate() { return pushCert; @@ -226,6 +243,8 @@ public class Proposal { } /** + * Get timestamps that Ketch must block for. + * * @return timestamps that Ketch must block for. These may have been used as * commit times inside the objects involved in the proposal. */ @@ -240,6 +259,7 @@ public class Proposal { * Request the proposal to wait for the affected timestamps to resolve. * * @param ts + * a {@link org.eclipse.jgit.util.time.ProposedTimestamp} object. * @return {@code this}. */ public Proposal addProposedTimestamp(ProposedTimestamp ts) { @@ -253,9 +273,11 @@ public class Proposal { /** * Add a callback to be invoked when the proposal is done. * <p> - * A proposal is done when it has entered either {@link State#EXECUTED} or - * {@link State#ABORTED} state. If the proposal is already done - * {@code callback.run()} is immediately invoked on the caller's thread. + * A proposal is done when it has entered either + * {@link org.eclipse.jgit.internal.ketch.Proposal.State#EXECUTED} or + * {@link org.eclipse.jgit.internal.ketch.Proposal.State#ABORTED} state. If + * the proposal is already done {@code callback.run()} is immediately + * invoked on the caller's thread. * * @param callback * method to run after the proposal is done. The callback may be @@ -291,12 +313,18 @@ public class Proposal { notifyState(ABORTED); } - /** @return read the current state of the proposal. */ + /** + * Read the current state of the proposal. + * + * @return read the current state of the proposal. + */ public State getState() { return state.get(); } /** + * Whether the proposal was attempted + * * @return {@code true} if the proposal was attempted. A true value does not * mean consensus was reached, only that the proposal was considered * and will not be making any more progress beyond its current @@ -309,7 +337,7 @@ public class Proposal { /** * Wait for the proposal to be attempted and {@link #isDone()} to be true. * - * @throws InterruptedException + * @throws java.lang.InterruptedException * caller was interrupted before proposal executed. */ public void await() throws InterruptedException { @@ -328,7 +356,7 @@ public class Proposal { * @param unit * unit describing the wait time. * @return true if the proposal is done; false if the method timed out. - * @throws InterruptedException + * @throws java.lang.InterruptedException * caller was interrupted before proposal executed. */ public boolean await(long wait, TimeUnit unit) throws InterruptedException { @@ -351,7 +379,7 @@ public class Proposal { * @param unit * unit describing the wait time. * @return true if the proposal exited the state; false on time out. - * @throws InterruptedException + * @throws java.lang.InterruptedException * caller was interrupted before proposal executed. */ public boolean awaitStateChange(State notIn, long wait, TimeUnit unit) @@ -378,6 +406,7 @@ public class Proposal { } } + /** {@inheritDoc} */ @Override public String toString() { StringBuilder s = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/RemoteGitReplica.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/RemoteGitReplica.java index a0ac60809c..674da1fc68 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/RemoteGitReplica.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/RemoteGitReplica.java @@ -80,7 +80,8 @@ import org.eclipse.jgit.transport.URIish; /** * Representation of a Git repository on a remote replica system. * <p> - * {@link KetchLeader} will contact the replica using the Git wire protocol. + * {@link org.eclipse.jgit.internal.ketch.KetchLeader} will contact the replica + * using the Git wire protocol. * <p> * The remote replica may be fully Ketch-aware, or a standard Git server. */ @@ -110,22 +111,32 @@ public class RemoteGitReplica extends KetchReplica { this.remoteConfig = rc; } - /** @return URI to contact the remote peer repository. */ + /** + * Get URI to contact the remote peer repository. + * + * @return URI to contact the remote peer repository. + */ public URIish getURI() { return uri; } - /** @return optional configuration describing how to contact the peer. */ + /** + * Get optional configuration describing how to contact the peer. + * + * @return optional configuration describing how to contact the peer. + */ @Nullable protected RemoteConfig getRemoteConfig() { return remoteConfig; } + /** {@inheritDoc} */ @Override protected String describeForLog() { return String.format("%s @ %s", getName(), getURI()); //$NON-NLS-1$ } + /** {@inheritDoc} */ @Override protected void startPush(final ReplicaPushRequest req) { getSystem().getExecutor().execute(new Runnable() { @@ -240,6 +251,7 @@ public class RemoteGitReplica extends KetchReplica { ReceiveCommand.abort(tmp); } + /** {@inheritDoc} */ @Override protected void blockingFetch(Repository repo, ReplicaFetchRequest req) throws NotSupportedException, TransportException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaConfig.java index e16e63aa7e..84261f1acb 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaConfig.java @@ -65,7 +65,9 @@ import org.eclipse.jgit.internal.ketch.KetchReplica.CommitSpeed; import org.eclipse.jgit.internal.ketch.KetchReplica.Participation; import org.eclipse.jgit.lib.Config; -/** Configures a {@link KetchReplica}. */ +/** + * Configures a {@link org.eclipse.jgit.internal.ketch.KetchReplica}. + */ public class ReplicaConfig { /** * Read a configuration from a config block. @@ -86,17 +88,29 @@ public class ReplicaConfig { private long minRetry = SECONDS.toMillis(5); private long maxRetry = MINUTES.toMillis(1); - /** @return participation of the replica in the system. */ + /** + * Get participation of the replica in the system. + * + * @return participation of the replica in the system. + */ public Participation getParticipation() { return participation; } - /** @return how Ketch should apply committed changes. */ + /** + * Get how Ketch should apply committed changes. + * + * @return how Ketch should apply committed changes. + */ public CommitMethod getCommitMethod() { return commitMethod; } - /** @return how quickly should Ketch commit. */ + /** + * Get how quickly should Ketch commit. + * + * @return how quickly should Ketch commit. + */ public CommitSpeed getCommitSpeed() { return commitSpeed; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaFetchRequest.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaFetchRequest.java index 201d9e9743..11c5b618dc 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaFetchRequest.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaFetchRequest.java @@ -50,7 +50,9 @@ import org.eclipse.jgit.annotations.Nullable; import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.lib.Ref; -/** A fetch request to obtain objects from a replica, and its result. */ +/** + * A fetch request to obtain objects from a replica, and its result. + */ public class ReplicaFetchRequest { private final Set<String> wantRefs; private final Set<ObjectId> wantObjects; @@ -70,23 +72,37 @@ public class ReplicaFetchRequest { this.wantObjects = wantObjects; } - /** @return references to be fetched. */ + /** + * Get references to be fetched. + * + * @return references to be fetched. + */ public Set<String> getWantRefs() { return wantRefs; } - /** @return objects to be fetched. */ + /** + * Get objects to be fetched. + * + * @return objects to be fetched. + */ public Set<ObjectId> getWantObjects() { return wantObjects; } - /** @return remote references, usually from the advertisement. */ + /** + * Get remote references, usually from the advertisement. + * + * @return remote references, usually from the advertisement. + */ @Nullable public Map<String, Ref> getRefs() { return refs; } /** + * Set references observed from the replica. + * * @param refs * references observed from the replica. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaPushRequest.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaPushRequest.java index 691b1424f4..603288ebcb 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaPushRequest.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaPushRequest.java @@ -54,8 +54,8 @@ import org.eclipse.jgit.transport.ReceiveCommand; /** * A push request sending objects to a replica, and its result. * <p> - * Implementors of {@link KetchReplica} must populate the command result fields, - * {@link #setRefs(Map)}, and call one of + * Implementors of {@link org.eclipse.jgit.internal.ketch.KetchReplica} must + * populate the command result fields, {@link #setRefs(Map)}, and call one of * {@link #setException(Repository, Throwable)} or {@link #done(Repository)} to * finish processing. */ @@ -80,18 +80,28 @@ public class ReplicaPushRequest { this.commands = commands; } - /** @return commands to be executed, and their results. */ + /** + * Get commands to be executed, and their results. + * + * @return commands to be executed, and their results. + */ public Collection<ReceiveCommand> getCommands() { return commands; } - /** @return remote references, usually from the advertisement. */ + /** + * Get remote references, usually from the advertisement. + * + * @return remote references, usually from the advertisement. + */ @Nullable public Map<String, Ref> getRefs() { return refs; } /** + * Set references observed from the replica. + * * @param refs * references observed from the replica. */ @@ -99,7 +109,11 @@ public class ReplicaPushRequest { this.refs = refs; } - /** @return exception thrown, if any. */ + /** + * Get exception thrown, if any. + * + * @return exception thrown, if any. + */ @Nullable public Throwable getException() { return exception; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaSnapshot.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaSnapshot.java index 8c3de027d2..263be77bf6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaSnapshot.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/ReplicaSnapshot.java @@ -65,31 +65,50 @@ public class ReplicaSnapshot { this.replica = replica; } - /** @return the replica this snapshot describes the state of. */ + /** + * Get the replica this snapshot describes the state of + * + * @return the replica this snapshot describes the state of + */ public KetchReplica getReplica() { return replica; } - /** @return current state of the replica. */ + /** + * Get current state of the replica + * + * @return current state of the replica + */ public KetchReplica.State getState() { return state; } - /** @return last known Git commit at {@code refs/txn/accepted}. */ + /** + * Get last known Git commit at {@code refs/txn/accepted} + * + * @return last known Git commit at {@code refs/txn/accepted} + */ @Nullable public ObjectId getAccepted() { return accepted; } - /** @return last known Git commit at {@code refs/txn/committed}. */ + /** + * Get last known Git commit at {@code refs/txn/committed} + * + * @return last known Git commit at {@code refs/txn/committed} + */ @Nullable public ObjectId getCommitted() { return committed; } /** - * @return if {@link #getState()} == {@link KetchReplica.State#OFFLINE} an - * optional human-readable message from the transport system + * Get error message + * + * @return if {@link #getState()} == + * {@link org.eclipse.jgit.internal.ketch.KetchReplica.State#OFFLINE} + * an optional human-readable message from the transport system * explaining the failure. */ @Nullable @@ -98,6 +117,9 @@ public class ReplicaSnapshot { } /** + * Get when the leader will retry communication with the offline or lagging + * replica + * * @return time (usually in the future) when the leader will retry * communication with the offline or lagging replica; null if no * retry is scheduled or necessary. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/StageBuilder.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/StageBuilder.java index 61871a494f..ae82dced21 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/StageBuilder.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/ketch/StageBuilder.java @@ -66,7 +66,9 @@ import org.eclipse.jgit.treewalk.EmptyTreeIterator; import org.eclipse.jgit.treewalk.TreeWalk; import org.eclipse.jgit.treewalk.filter.TreeFilter; -/** Constructs a set of commands to stage content during a proposal. */ +/** + * Constructs a set of commands to stage content during a proposal. + */ public class StageBuilder { /** * Acceptable number of references to send in a single stage transaction. @@ -119,14 +121,15 @@ public class StageBuilder { * from. * @param oldTree * accepted RefTree on the replica ({@code refs/txn/accepted}). - * Use {@link ObjectId#zeroId()} if the remote does not have any - * ref tree, e.g. a new replica catching up. + * Use {@link org.eclipse.jgit.lib.ObjectId#zeroId()} if the + * remote does not have any ref tree, e.g. a new replica catching + * up. * @param newTree * RefTree being sent to the replica. The trees will be compared. * @return list of commands to create {@code "refs/txn/stage/..."} * references on replicas anchoring new objects into the repository * while a transaction gains consensus. - * @throws IOException + * @throws java.io.IOException * {@code git} cannot be accessed to compare {@code oldTree} and * {@code newTree} to build the object set. */ @@ -172,7 +175,7 @@ public class StageBuilder { * @return list of commands to create {@code "refs/txn/stage/..."} * references on replicas anchoring {@code newObjs} into the * repository while a transaction gains consensus. - * @throws IOException + * @throws java.io.IOException * {@code git} cannot be accessed to perform minification of * {@code newObjs}. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/revwalk/AddToBitmapFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/revwalk/AddToBitmapFilter.java new file mode 100644 index 0000000000..468d93046a --- /dev/null +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/revwalk/AddToBitmapFilter.java @@ -0,0 +1,108 @@ +/* + * Copyright (C) 2017, Google Inc. + * and other copyright owners as documented in the project's IP log. + * + * This program and the accompanying materials are made available + * under the terms of the Eclipse Distribution License v1.0 which + * accompanies this distribution, is reproduced below, and is + * available at http://www.eclipse.org/org/documents/edl-v10.php + * + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or + * without modification, are permitted provided that the following + * conditions are met: + * + * - Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * - Redistributions in binary form must reproduce the above + * copyright notice, this list of conditions and the following + * disclaimer in the documentation and/or other materials provided + * with the distribution. + * + * - Neither the name of the Eclipse Foundation, Inc. nor the + * names of its contributors may be used to endorse or promote + * products derived from this software without specific prior + * written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND + * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, + * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER + * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF + * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +package org.eclipse.jgit.internal.revwalk; + +import org.eclipse.jgit.lib.BitmapIndex.Bitmap; +import org.eclipse.jgit.lib.BitmapIndex.BitmapBuilder; +import org.eclipse.jgit.lib.Constants; +import org.eclipse.jgit.revwalk.filter.RevFilter; +import org.eclipse.jgit.revwalk.RevWalk; +import org.eclipse.jgit.revwalk.RevCommit; +import org.eclipse.jgit.revwalk.RevFlag; + +/** + * A RevFilter that adds the visited commits to {@code bitmap} as a side + * effect. + * <p> + * When the walk hits a commit that is part of {@code bitmap}'s + * BitmapIndex, that entire bitmap is ORed into {@code bitmap} and the + * commit and its parents are marked as SEEN so that the walk does not + * have to visit its ancestors. This ensures the walk is very short if + * there is good bitmap coverage. + */ +public class AddToBitmapFilter extends RevFilter { + private final BitmapBuilder bitmap; + + /** + * Create a filter that adds visited commits to the given bitmap. + * + * @param bitmap bitmap to write visited commits to + */ + public AddToBitmapFilter(BitmapBuilder bitmap) { + this.bitmap = bitmap; + } + + /** {@inheritDoc} */ + @Override + public final boolean include(RevWalk walker, RevCommit cmit) { + Bitmap visitedBitmap; + + if (bitmap.contains(cmit)) { + // already included + } else if ((visitedBitmap = bitmap.getBitmapIndex() + .getBitmap(cmit)) != null) { + bitmap.or(visitedBitmap); + } else { + bitmap.addObject(cmit, Constants.OBJ_COMMIT); + return true; + } + + for (RevCommit p : cmit.getParents()) { + p.add(RevFlag.SEEN); + } + return false; + } + + /** {@inheritDoc} */ + @Override + public final RevFilter clone() { + throw new UnsupportedOperationException(); + } + + /** {@inheritDoc} */ + @Override + public final boolean requiresCommitBody() { + return false; + } +} diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/revwalk/AddUnseenToBitmapFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/revwalk/AddUnseenToBitmapFilter.java new file mode 100644 index 0000000000..a52c6a26ae --- /dev/null +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/revwalk/AddUnseenToBitmapFilter.java @@ -0,0 +1,116 @@ +/* + * Copyright (C) 2017, Google Inc. + * and other copyright owners as documented in the project's IP log. + * + * This program and the accompanying materials are made available + * under the terms of the Eclipse Distribution License v1.0 which + * accompanies this distribution, is reproduced below, and is + * available at http://www.eclipse.org/org/documents/edl-v10.php + * + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or + * without modification, are permitted provided that the following + * conditions are met: + * + * - Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * - Redistributions in binary form must reproduce the above + * copyright notice, this list of conditions and the following + * disclaimer in the documentation and/or other materials provided + * with the distribution. + * + * - Neither the name of the Eclipse Foundation, Inc. nor the + * names of its contributors may be used to endorse or promote + * products derived from this software without specific prior + * written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND + * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, + * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER + * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF + * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +package org.eclipse.jgit.internal.revwalk; + +import org.eclipse.jgit.lib.BitmapIndex.Bitmap; +import org.eclipse.jgit.lib.BitmapIndex.BitmapBuilder; +import org.eclipse.jgit.lib.Constants; +import org.eclipse.jgit.revwalk.filter.RevFilter; +import org.eclipse.jgit.revwalk.RevWalk; +import org.eclipse.jgit.revwalk.RevCommit; +import org.eclipse.jgit.revwalk.RevFlag; + +/** + * A RevFilter that adds the visited commits to {@code bitmap} as a side + * effect. + * <p> + * When the walk hits a commit that is part of {@code bitmap}'s + * BitmapIndex, that entire bitmap is ORed into {@code bitmap} and the + * commit and its parents are marked as SEEN so that the walk does not + * have to visit its ancestors. This ensures the walk is very short if + * there is good bitmap coverage. + * <p> + * Commits named in {@code seen} are considered already seen. If one is + * encountered, that commit and its parents will be marked with the SEEN + * flag to prevent the walk from visiting its ancestors. + */ +public class AddUnseenToBitmapFilter extends RevFilter { + private final BitmapBuilder seen; + private final BitmapBuilder bitmap; + + /** + * Create a filter that adds visited commits to the given bitmap, but does not walk + * through the objects in {@code seen}. + * + * @param seen objects that are already seen + * @param bitmap bitmap to write visited commits to + */ + public AddUnseenToBitmapFilter(BitmapBuilder seen, BitmapBuilder bitmap) { + this.seen = seen; + this.bitmap = bitmap; + } + + /** {@inheritDoc} */ + @Override + public final boolean include(RevWalk walker, RevCommit cmit) { + Bitmap visitedBitmap; + + if (seen.contains(cmit) || bitmap.contains(cmit)) { + // already seen or included + } else if ((visitedBitmap = bitmap.getBitmapIndex() + .getBitmap(cmit)) != null) { + bitmap.or(visitedBitmap); + } else { + bitmap.addObject(cmit, Constants.OBJ_COMMIT); + return true; + } + + for (RevCommit p : cmit.getParents()) { + p.add(RevFlag.SEEN); + } + return false; + } + + /** {@inheritDoc} */ + @Override + public final RevFilter clone() { + throw new UnsupportedOperationException(); + } + + /** {@inheritDoc} */ + @Override + public final boolean requiresCommitBody() { + return false; + } +} diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/BeforeDfsPackIndexLoadedEvent.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/BeforeDfsPackIndexLoadedEvent.java index 75ccb07915..10d8e894de 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/BeforeDfsPackIndexLoadedEvent.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/BeforeDfsPackIndexLoadedEvent.java @@ -46,10 +46,10 @@ package org.eclipse.jgit.internal.storage.dfs; import org.eclipse.jgit.events.RepositoryEvent; /** - * Describes the {@link DfsPackFile} just before its index is loaded. Currently, - * DfsPackFile directly dispatches the event on - * {@link org.eclipse.jgit.lib.Repository#getGlobalListenerList}. Which means - * the call to {@link #getRepository} will always return null. + * Describes the {@link org.eclipse.jgit.internal.storage.dfs.DfsPackFile} just + * before its index is loaded. Currently, DfsPackFile directly dispatches the + * event on {@link org.eclipse.jgit.lib.Repository#getGlobalListenerList}. Which + * means the call to {@link #getRepository} will always return null. */ public class BeforeDfsPackIndexLoadedEvent extends RepositoryEvent<BeforeDfsPackIndexLoadedListener> { @@ -65,16 +65,22 @@ public class BeforeDfsPackIndexLoadedEvent this.pack = pack; } - /** @return the PackFile containing the index that will be loaded. */ + /** + * Get the PackFile containing the index that will be loaded. + * + * @return the PackFile containing the index that will be loaded. + */ public DfsPackFile getPackFile() { return pack; } + /** {@inheritDoc} */ @Override public Class<BeforeDfsPackIndexLoadedListener> getListenerType() { return BeforeDfsPackIndexLoadedListener.class; } + /** {@inheritDoc} */ @Override public void dispatch(BeforeDfsPackIndexLoadedListener listener) { listener.onBeforeDfsPackIndexLoaded(this); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/BeforeDfsPackIndexLoadedListener.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/BeforeDfsPackIndexLoadedListener.java index 9f7f350833..517e42be9c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/BeforeDfsPackIndexLoadedListener.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/BeforeDfsPackIndexLoadedListener.java @@ -46,7 +46,8 @@ package org.eclipse.jgit.internal.storage.dfs; import org.eclipse.jgit.events.RepositoryListener; /** - * Receives {@link BeforeDfsPackIndexLoadedEvent}s. + * Receives + * {@link org.eclipse.jgit.internal.storage.dfs.BeforeDfsPackIndexLoadedEvent}s. */ public interface BeforeDfsPackIndexLoadedListener extends RepositoryListener { /** diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsBlockCache.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsBlockCache.java index 45202b5b08..14dc80fc97 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsBlockCache.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsBlockCache.java @@ -46,14 +46,19 @@ package org.eclipse.jgit.internal.storage.dfs; import java.io.IOException; import java.util.concurrent.atomic.AtomicLong; +import java.util.concurrent.atomic.AtomicReference; import java.util.concurrent.atomic.AtomicReferenceArray; import java.util.concurrent.locks.ReentrantLock; +import java.util.stream.LongStream; import org.eclipse.jgit.annotations.Nullable; import org.eclipse.jgit.internal.JGitText; +import org.eclipse.jgit.internal.storage.pack.PackExt; /** - * Caches slices of a {@link BlockBasedFile} in memory for faster read access. + * Caches slices of a + * {@link org.eclipse.jgit.internal.storage.dfs.BlockBasedFile} in memory for + * faster read access. * <p> * The DfsBlockCache serves as a Java based "buffer cache", loading segments of * a BlockBasedFile into the JVM heap prior to use. As JGit often wants to do @@ -61,8 +66,8 @@ import org.eclipse.jgit.internal.JGitText; * these tiny reads into larger block-sized IO operations. * <p> * Whenever a cache miss occurs, loading is invoked by exactly one thread for - * the given <code>(DfsPackKey,position)</code> key tuple. This is ensured by an - * array of locks, with the tuple hashed to a lock instance. + * the given <code>(DfsStreamKey,position)</code> key tuple. This is ensured by + * an array of locks, with the tuple hashed to a lock instance. * <p> * Its too expensive during object access to be accurate with a least recently * used (LRU) algorithm. Strictly ordering every read is a lot of overhead that @@ -100,7 +105,7 @@ public final class DfsBlockCache { * * @param cfg * the new window cache configuration. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * the cache configuration contains one or more invalid * settings, usually too low of a limit. */ @@ -108,7 +113,11 @@ public final class DfsBlockCache { cache = new DfsBlockCache(cfg); } - /** @return the currently active DfsBlockCache. */ + /** + * Get the currently active DfsBlockCache. + * + * @return the currently active DfsBlockCache. + */ public static DfsBlockCache getInstance() { return cache; } @@ -143,14 +152,27 @@ public final class DfsBlockCache { /** As {@link #blockSize} is a power of 2, bits to shift for a / blockSize. */ private final int blockSizeShift; - /** Number of times a block was found in the cache. */ - private final AtomicLong statHit; + /** + * Number of times a block was found in the cache, per pack file extension. + */ + private final AtomicReference<AtomicLong[]> statHit; + + /** + * Number of times a block was not found, and had to be loaded, per pack + * file extension. + */ + private final AtomicReference<AtomicLong[]> statMiss; - /** Number of times a block was not found, and had to be loaded. */ - private final AtomicLong statMiss; + /** + * Number of blocks evicted due to cache being full, per pack file + * extension. + */ + private final AtomicReference<AtomicLong[]> statEvict; - /** Number of blocks evicted due to cache being full. */ - private volatile long statEvict; + /** + * Number of bytes currently loaded in the cache, per pack file extension. + */ + private final AtomicReference<AtomicLong[]> liveBytes; /** Protects the clock and its related data. */ private final ReentrantLock clockLock; @@ -158,9 +180,6 @@ public final class DfsBlockCache { /** Current position of the clock. */ private Ref clockHand; - /** Number of bytes currently loaded in the cache. */ - private volatile long liveBytes; - @SuppressWarnings("unchecked") private DfsBlockCache(final DfsBlockCacheConfig cfg) { tableSize = tableSize(cfg); @@ -180,56 +199,127 @@ public final class DfsBlockCache { clockLock = new ReentrantLock(true /* fair */); String none = ""; //$NON-NLS-1$ clockHand = new Ref<>( - DfsStreamKey.of(new DfsRepositoryDescription(none), none), + DfsStreamKey.of(new DfsRepositoryDescription(none), none, null), -1, 0, null); clockHand.next = clockHand; - statHit = new AtomicLong(); - statMiss = new AtomicLong(); + statHit = new AtomicReference<>(newCounters()); + statMiss = new AtomicReference<>(newCounters()); + statEvict = new AtomicReference<>(newCounters()); + liveBytes = new AtomicReference<>(newCounters()); } boolean shouldCopyThroughCache(long length) { return length <= maxStreamThroughCache; } - /** @return total number of bytes in the cache. */ - public long getCurrentSize() { - return liveBytes; + /** + * Get total number of bytes in the cache, per pack file extension. + * + * @return total number of bytes in the cache, per pack file extension. + */ + public long[] getCurrentSize() { + return getStatVals(liveBytes); } - /** @return 0..100, defining how full the cache is. */ + /** + * Get 0..100, defining how full the cache is. + * + * @return 0..100, defining how full the cache is. + */ public long getFillPercentage() { - return getCurrentSize() * 100 / maxBytes; + return LongStream.of(getCurrentSize()).sum() * 100 / maxBytes; } - /** @return number of requests for items in the cache. */ - public long getHitCount() { - return statHit.get(); + /** + * Get number of requests for items in the cache, per pack file extension. + * + * @return number of requests for items in the cache, per pack file + * extension. + */ + public long[] getHitCount() { + return getStatVals(statHit); } - /** @return number of requests for items not in the cache. */ - public long getMissCount() { - return statMiss.get(); + /** + * Get number of requests for items not in the cache, per pack file + * extension. + * + * @return number of requests for items not in the cache, per pack file + * extension. + */ + public long[] getMissCount() { + return getStatVals(statMiss); } - /** @return total number of requests (hit + miss). */ - public long getTotalRequestCount() { - return getHitCount() + getMissCount(); + /** + * Get total number of requests (hit + miss), per pack file extension. + * + * @return total number of requests (hit + miss), per pack file extension. + */ + public long[] getTotalRequestCount() { + AtomicLong[] hit = statHit.get(); + AtomicLong[] miss = statMiss.get(); + long[] cnt = new long[Math.max(hit.length, miss.length)]; + for (int i = 0; i < hit.length; i++) { + cnt[i] += hit[i].get(); + } + for (int i = 0; i < miss.length; i++) { + cnt[i] += miss[i].get(); + } + return cnt; } - /** @return 0..100, defining number of cache hits. */ - public long getHitRatio() { - long hits = statHit.get(); - long miss = statMiss.get(); - long total = hits + miss; - if (total == 0) - return 0; - return hits * 100 / total; + /** + * Get hit ratios + * + * @return hit ratios + */ + public long[] getHitRatio() { + AtomicLong[] hit = statHit.get(); + AtomicLong[] miss = statMiss.get(); + long[] ratio = new long[Math.max(hit.length, miss.length)]; + for (int i = 0; i < ratio.length; i++) { + if (i >= hit.length) { + ratio[i] = 0; + } else if (i >= miss.length) { + ratio[i] = 100; + } else { + long hitVal = hit[i].get(); + long missVal = miss[i].get(); + long total = hitVal + missVal; + ratio[i] = total == 0 ? 0 : hitVal * 100 / total; + } + } + return ratio; } - /** @return number of evictions performed due to cache being full. */ - public long getEvictions() { - return statEvict; + /** + * Get number of evictions performed due to cache being full, per pack file + * extension. + * + * @return number of evictions performed due to cache being full, per pack + * file extension. + */ + public long[] getEvictions() { + return getStatVals(statEvict); + } + + /** + * Quickly check if the cache contains block 0 of the given stream. + * <p> + * This can be useful for sophisticated pre-read algorithms to quickly + * determine if a file is likely already in cache, especially small + * reftables which may be smaller than a typical DFS block size. + * + * @param key + * the file to check. + * @return true if block 0 (the first block) is in the cache. + */ + public boolean hasBlock0(DfsStreamKey key) { + HashEntry e1 = table.get(slot(key, 0)); + DfsBlock v = scan(e1, key, 0); + return v != null && v.contains(key, 0); } private int hash(int packHash, long off) { @@ -276,11 +366,11 @@ public final class DfsBlockCache { DfsBlock v = scan(e1, key, position); if (v != null && v.contains(key, requestedPosition)) { ctx.stats.blockCacheHit++; - statHit.incrementAndGet(); + getStat(statHit, key).incrementAndGet(); return v; } - reserveSpace(blockSize); + reserveSpace(blockSize, key); ReentrantLock regionLock = lockFor(key, position); regionLock.lock(); try { @@ -289,20 +379,20 @@ public final class DfsBlockCache { v = scan(e2, key, position); if (v != null) { ctx.stats.blockCacheHit++; - statHit.incrementAndGet(); - creditSpace(blockSize); + getStat(statHit, key).incrementAndGet(); + creditSpace(blockSize, key); return v; } } - statMiss.incrementAndGet(); + getStat(statMiss, key).incrementAndGet(); boolean credit = true; try { v = file.readOneBlock(requestedPosition, ctx, fileChannel); credit = false; } finally { if (credit) - creditSpace(blockSize); + creditSpace(blockSize, key); } if (position != v.start) { // The file discovered its blockSize and adjusted. @@ -332,10 +422,10 @@ public final class DfsBlockCache { } @SuppressWarnings("unchecked") - private void reserveSpace(int reserve) { + private void reserveSpace(int reserve, DfsStreamKey key) { clockLock.lock(); try { - long live = liveBytes + reserve; + long live = LongStream.of(getCurrentSize()).sum() + reserve; if (maxBytes < live) { Ref prev = clockHand; Ref hand = clockHand.next; @@ -358,28 +448,33 @@ public final class DfsBlockCache { dead.next = null; dead.value = null; live -= dead.size; - statEvict++; + getStat(liveBytes, dead.key).addAndGet(-dead.size); + getStat(statEvict, dead.key).incrementAndGet(); } while (maxBytes < live); clockHand = prev; } - liveBytes = live; + getStat(liveBytes, key).addAndGet(reserve); } finally { clockLock.unlock(); } } - private void creditSpace(int credit) { + private void creditSpace(int credit, DfsStreamKey key) { clockLock.lock(); - liveBytes -= credit; - clockLock.unlock(); + try { + getStat(liveBytes, key).addAndGet(-credit); + } finally { + clockLock.unlock(); + } } @SuppressWarnings("unchecked") private void addToClock(Ref ref, int credit) { clockLock.lock(); try { - if (credit != 0) - liveBytes -= credit; + if (credit != 0) { + getStat(liveBytes, ref.key).addAndGet(-credit); + } Ref ptr = clockHand; ref.next = ptr.next; ptr.next = ref; @@ -404,7 +499,7 @@ public final class DfsBlockCache { if (ref != null) return ref; - reserveSpace(size); + reserveSpace(size, key); ReentrantLock regionLock = lockFor(key, pos); regionLock.lock(); try { @@ -412,7 +507,7 @@ public final class DfsBlockCache { if (e2 != e1) { ref = scanRef(e2, key, pos); if (ref != null) { - creditSpace(size); + creditSpace(size, key); return ref; } } @@ -440,9 +535,9 @@ public final class DfsBlockCache { <T> T get(DfsStreamKey key, long position) { T val = (T) scan(table.get(slot(key, position)), key, position); if (val == null) - statMiss.incrementAndGet(); + getStat(statMiss, key).incrementAndGet(); else - statHit.incrementAndGet(); + getStat(statHit, key).incrementAndGet(); return val; } @@ -454,9 +549,9 @@ public final class DfsBlockCache { <T> Ref<T> getRef(DfsStreamKey key) { Ref<T> r = scanRef(table.get(slot(key, 0)), key, 0); if (r != null) - statHit.incrementAndGet(); + getStat(statHit, key).incrementAndGet(); else - statMiss.incrementAndGet(); + getStat(statMiss, key).incrementAndGet(); return r; } @@ -478,6 +573,43 @@ public final class DfsBlockCache { return loadLocks[(hash(key.hash, position) >>> 1) % loadLocks.length]; } + private static AtomicLong[] newCounters() { + AtomicLong[] ret = new AtomicLong[PackExt.values().length]; + for (int i = 0; i < ret.length; i++) { + ret[i] = new AtomicLong(); + } + return ret; + } + + private static AtomicLong getStat(AtomicReference<AtomicLong[]> stats, + DfsStreamKey key) { + int pos = key.packExtPos; + while (true) { + AtomicLong[] vals = stats.get(); + if (pos < vals.length) { + return vals[pos]; + } + AtomicLong[] expect = vals; + vals = new AtomicLong[Math.max(pos + 1, PackExt.values().length)]; + System.arraycopy(expect, 0, vals, 0, expect.length); + for (int i = expect.length; i < vals.length; i++) { + vals[i] = new AtomicLong(); + } + if (stats.compareAndSet(expect, vals)) { + return vals[pos]; + } + } + } + + private static long[] getStatVals(AtomicReference<AtomicLong[]> stat) { + AtomicLong[] stats = stat.get(); + long[] cnt = new long[stats.length]; + for (int i = 0; i < stats.length; i++) { + cnt[i] = stats[i].get(); + } + return cnt; + } + private static HashEntry clean(HashEntry top) { while (top != null && top.ref.next == null) top = top.next; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsBlockCacheConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsBlockCacheConfig.java index feadedbc88..e558a81c09 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsBlockCacheConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsBlockCacheConfig.java @@ -55,7 +55,10 @@ import java.text.MessageFormat; import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.lib.Config; -/** Configuration parameters for {@link DfsBlockCache}. */ +/** + * Configuration parameters for + * {@link org.eclipse.jgit.internal.storage.dfs.DfsBlockCache}. + */ public class DfsBlockCacheConfig { /** 1024 (number of bytes in one kibibyte/kilobyte) */ public static final int KB = 1024; @@ -68,7 +71,9 @@ public class DfsBlockCacheConfig { private double streamRatio; private int concurrencyLevel; - /** Create a default configuration. */ + /** + * Create a default configuration. + */ public DfsBlockCacheConfig() { setBlockLimit(32 * MB); setBlockSize(64 * KB); @@ -77,6 +82,9 @@ public class DfsBlockCacheConfig { } /** + * Get maximum number bytes of heap memory to dedicate to caching pack file + * data. + * * @return maximum number bytes of heap memory to dedicate to caching pack * file data. <b>Default is 32 MB.</b> */ @@ -85,6 +93,9 @@ public class DfsBlockCacheConfig { } /** + * Set maximum number bytes of heap memory to dedicate to caching pack file + * data. + * * @param newLimit * maximum number bytes of heap memory to dedicate to caching * pack file data. @@ -96,6 +107,9 @@ public class DfsBlockCacheConfig { } /** + * Get size in bytes of a single window mapped or read in from the pack + * file. + * * @return size in bytes of a single window mapped or read in from the pack * file. <b>Default is 64 KB.</b> */ @@ -104,6 +118,8 @@ public class DfsBlockCacheConfig { } /** + * Set size in bytes of a single window read in from the pack file. + * * @param newSize * size in bytes of a single window read in from the pack file. * The value must be a power of 2. @@ -120,6 +136,8 @@ public class DfsBlockCacheConfig { } /** + * Get the estimated number of threads concurrently accessing the cache. + * * @return the estimated number of threads concurrently accessing the cache. * <b>Default is 32.</b> */ @@ -128,6 +146,8 @@ public class DfsBlockCacheConfig { } /** + * Set the estimated number of threads concurrently accessing the cache. + * * @param newConcurrencyLevel * the estimated number of threads concurrently accessing the * cache. @@ -140,6 +160,9 @@ public class DfsBlockCacheConfig { } /** + * Get highest percentage of {@link #getBlockLimit()} a single pack can + * occupy while being copied by the pack reuse strategy. + * * @return highest percentage of {@link #getBlockLimit()} a single pack can * occupy while being copied by the pack reuse strategy. <b>Default * is 0.30, or 30%</b>. @@ -149,6 +172,8 @@ public class DfsBlockCacheConfig { } /** + * Set percentage of cache to occupy with a copied pack. + * * @param ratio * percentage of cache to occupy with a copied pack. * @return {@code this} diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsCachedPack.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsCachedPack.java index a5308f617e..3605236e56 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsCachedPack.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsCachedPack.java @@ -50,7 +50,9 @@ import org.eclipse.jgit.internal.storage.pack.ObjectToPack; import org.eclipse.jgit.internal.storage.pack.PackOutputStream; import org.eclipse.jgit.internal.storage.pack.StoredObjectRepresentation; -/** A DfsPackFile available for reuse as-is. */ +/** + * A DfsPackFile available for reuse as-is. + */ public class DfsCachedPack extends CachedPack { private final DfsPackFile pack; @@ -58,21 +60,28 @@ public class DfsCachedPack extends CachedPack { this.pack = pack; } - /** @return the description of the pack. */ + /** + * Get the description of the pack. + * + * @return the description of the pack. + */ public DfsPackDescription getPackDescription() { return pack.getPackDescription(); } + /** {@inheritDoc} */ @Override public long getObjectCount() throws IOException { return getPackDescription().getObjectCount(); } + /** {@inheritDoc} */ @Override public long getDeltaCount() throws IOException { return getPackDescription().getDeltaCount(); } + /** {@inheritDoc} */ @Override public boolean hasObject(ObjectToPack obj, StoredObjectRepresentation rep) { return ((DfsObjectRepresentation) rep).pack == pack; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsConfig.java index 696595c472..3e2963af97 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsConfig.java @@ -49,11 +49,13 @@ import org.eclipse.jgit.errors.ConfigInvalidException; import org.eclipse.jgit.lib.StoredConfig; final class DfsConfig extends StoredConfig { + /** {@inheritDoc} */ @Override public void load() throws IOException, ConfigInvalidException { clear(); } + /** {@inheritDoc} */ @Override public void save() throws IOException { // TODO actually store this configuration. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsFsck.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsFsck.java index 75eade2273..985393c5e2 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsFsck.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsFsck.java @@ -55,19 +55,24 @@ import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.internal.fsck.FsckError; import org.eclipse.jgit.internal.fsck.FsckError.CorruptIndex; import org.eclipse.jgit.internal.fsck.FsckPackParser; +import org.eclipse.jgit.internal.storage.dfs.DfsObjDatabase.PackSource; import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.lib.NullProgressMonitor; import org.eclipse.jgit.lib.ObjectChecker; +import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.lib.ProgressMonitor; import org.eclipse.jgit.lib.Ref; import org.eclipse.jgit.revwalk.ObjectWalk; import org.eclipse.jgit.revwalk.RevObject; -/** Verify the validity and connectivity of a DFS repository. */ +/** + * Verify the validity and connectivity of a DFS repository. + */ public class DfsFsck { private final DfsRepository repo; private final DfsObjDatabase objdb; private ObjectChecker objChecker = new ObjectChecker(); + private boolean connectivityOnly; /** * Initialize DFS fsck. @@ -87,7 +92,7 @@ public class DfsFsck { * @param pm * callback to provide progress feedback during the check. * @return all errors about the repository. - * @throws IOException + * @throws java.io.IOException * if encounters IO errors during the process. */ public FsckError check(ProgressMonitor pm) throws IOException { @@ -96,7 +101,9 @@ public class DfsFsck { } FsckError errors = new FsckError(); - checkPacks(pm, errors); + if (!connectivityOnly) { + checkPacks(pm, errors); + } checkConnectivity(pm, errors); return errors; } @@ -106,6 +113,10 @@ public class DfsFsck { try (DfsReader ctx = objdb.newReader()) { for (DfsPackFile pack : objdb.getPacks()) { DfsPackDescription packDesc = pack.getPackDescription(); + if (packDesc.getPackSource() + == PackSource.UNREACHABLE_GARBAGE) { + continue; + } try (ReadableChannel rc = objdb.openFile(packDesc, PACK)) { verifyPack(pm, errors, ctx, pack, rc); } catch (MissingObjectException e) { @@ -136,19 +147,24 @@ public class DfsFsck { pm.beginTask(JGitText.get().countingObjects, ProgressMonitor.UNKNOWN); try (ObjectWalk ow = new ObjectWalk(repo)) { for (Ref r : repo.getAllRefs().values()) { + ObjectId objectId = r.getObjectId(); + if (objectId == null) { + // skip unborn branch + continue; + } RevObject tip; try { - tip = ow.parseAny(r.getObjectId()); + tip = ow.parseAny(objectId); if (r.getLeaf().getName().startsWith(Constants.R_HEADS) && tip.getType() != Constants.OBJ_COMMIT) { // heads should only point to a commit object errors.getNonCommitHeads().add(r.getLeaf().getName()); } + ow.markStart(tip); } catch (MissingObjectException e) { errors.getMissingObjects().add(e.getObjectId()); continue; } - ow.markStart(tip); } try { ow.checkConnectivity(); @@ -169,4 +185,17 @@ public class DfsFsck { public void setObjectChecker(ObjectChecker objChecker) { this.objChecker = objChecker; } + + /** + * Whether fsck should bypass object validity and integrity checks and only + * check connectivity. + * + * @param connectivityOnly + * whether fsck should bypass object validity and integrity + * checks and only check connectivity. The default is + * {@code false}, meaning to run all checks. + */ + public void setConnectivityOnly(boolean connectivityOnly) { + this.connectivityOnly = connectivityOnly; + } } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsGarbageCollector.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsGarbageCollector.java index 304a93128f..69989a451e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsGarbageCollector.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsGarbageCollector.java @@ -93,7 +93,9 @@ import org.eclipse.jgit.storage.pack.PackStatistics; import org.eclipse.jgit.util.SystemReader; import org.eclipse.jgit.util.io.CountingOutputStream; -/** Repack and garbage collect a repository. */ +/** + * Repack and garbage collect a repository. + */ public class DfsGarbageCollector { private final DfsRepository repo; private final RefDatabase refdb; @@ -108,6 +110,7 @@ public class DfsGarbageCollector { private PackConfig packConfig; private ReftableConfig reftableConfig; private boolean convertToReftable = true; + private boolean includeDeletes; private long reftableInitialMinUpdateIndex = 1; private long reftableInitialMaxUpdateIndex = 1; @@ -146,12 +149,18 @@ public class DfsGarbageCollector { packConfig.setIndexVersion(2); } - /** @return configuration used to generate the new pack file. */ + /** + * Get configuration used to generate the new pack file. + * + * @return configuration used to generate the new pack file. + */ public PackConfig getPackConfig() { return packConfig; } /** + * Set the new configuration to use when creating the pack file. + * * @param newConfig * the new configuration to use when creating the pack file. * @return {@code this} @@ -162,6 +171,8 @@ public class DfsGarbageCollector { } /** + * Set configuration to write a reftable. + * * @param cfg * configuration to write a reftable. Reftable writing is * disabled (default) when {@code cfg} is {@code null}. @@ -173,11 +184,14 @@ public class DfsGarbageCollector { } /** + * Whether the garbage collector should convert references to reftable. + * * @param convert - * if true, {@link #setReftableConfig(ReftableConfig)} has been - * set non-null, and a GC reftable doesn't yet exist, the garbage - * collector will make one by scanning the existing references, - * and writing a new reftable. Default is {@code true}. + * if {@code true}, {@link #setReftableConfig(ReftableConfig)} + * has been set non-null, and a GC reftable doesn't yet exist, + * the garbage collector will make one by scanning the existing + * references, and writing a new reftable. Default is + * {@code true}. * @return {@code this} */ public DfsGarbageCollector setConvertToReftable(boolean convert) { @@ -186,13 +200,29 @@ public class DfsGarbageCollector { } /** + * Whether the garbage collector will include tombstones for deleted + * references in the reftable. + * + * @param include + * if {@code true}, the garbage collector will include tombstones + * for deleted references in the reftable. Default is + * {@code false}. + * @return {@code this} + */ + public DfsGarbageCollector setIncludeDeletes(boolean include) { + includeDeletes = include; + return this; + } + + /** * Set minUpdateIndex for the initial reftable created during conversion. * * @param u * minUpdateIndex for the initial reftable created by scanning - * {@link DfsRefDatabase#getRefs(String)}. Ignored unless caller - * has also set {@link #setReftableConfig(ReftableConfig)}. - * Defaults to {@code 1}. Must be {@code u >= 0}. + * {@link org.eclipse.jgit.internal.storage.dfs.DfsRefDatabase#getRefs(String)}. + * Ignored unless caller has also set + * {@link #setReftableConfig(ReftableConfig)}. Defaults to + * {@code 1}. Must be {@code u >= 0}. * @return {@code this} */ public DfsGarbageCollector setReftableInitialMinUpdateIndex(long u) { @@ -205,9 +235,10 @@ public class DfsGarbageCollector { * * @param u * maxUpdateIndex for the initial reftable created by scanning - * {@link DfsRefDatabase#getRefs(String)}. Ignored unless caller - * has also set {@link #setReftableConfig(ReftableConfig)}. - * Defaults to {@code 1}. Must be {@code u >= 0}. + * {@link org.eclipse.jgit.internal.storage.dfs.DfsRefDatabase#getRefs(String)}. + * Ignored unless caller has also set + * {@link #setReftableConfig(ReftableConfig)}. Defaults to + * {@code 1}. Must be {@code u >= 0}. * @return {@code this} */ public DfsGarbageCollector setReftableInitialMaxUpdateIndex(long u) { @@ -215,7 +246,12 @@ public class DfsGarbageCollector { return this; } - /** @return garbage packs smaller than this size will be repacked. */ + /** + * Get coalesce garbage limit + * + * @return coalesce garbage limit, packs smaller than this size will be + * repacked. + */ public long getCoalesceGarbageLimit() { return coalesceGarbageLimit; } @@ -232,7 +268,8 @@ public class DfsGarbageCollector { * reading and copying the objects. * <p> * If limit is set to 0 the UNREACHABLE_GARBAGE coalesce is disabled.<br> - * If limit is set to {@link Long#MAX_VALUE}, everything is coalesced. + * If limit is set to {@link java.lang.Long#MAX_VALUE}, everything is + * coalesced. * <p> * Keeping unreachable garbage prevents race conditions with repository * changes that may suddenly need an object whose only copy was stored in @@ -248,9 +285,11 @@ public class DfsGarbageCollector { } /** + * Get time to live for garbage packs. + * * @return garbage packs older than this limit (in milliseconds) will be * pruned as part of the garbage collection process if the value is - * > 0, otherwise garbage packs are retained. + * > 0, otherwise garbage packs are retained. */ public long getGarbageTtlMillis() { return garbageTtlMillis; @@ -288,7 +327,7 @@ public class DfsGarbageCollector { * @return true if the repack was successful without race conditions. False * if a race condition was detected and the repack should be run * again later. - * @throws IOException + * @throws java.io.IOException * a new pack cannot be created. */ public boolean pack(ProgressMonitor pm) throws IOException { @@ -476,17 +515,31 @@ public class DfsGarbageCollector { return cal.getTimeInMillis(); } - /** @return all of the source packs that fed into this compaction. */ + /** + * Get all of the source packs that fed into this compaction. + * + * @return all of the source packs that fed into this compaction. + */ public Set<DfsPackDescription> getSourcePacks() { return toPrune(); } - /** @return new packs created by this compaction. */ + /** + * Get new packs created by this compaction. + * + * @return new packs created by this compaction. + */ public List<DfsPackDescription> getNewPacks() { return newPackDesc; } - /** @return statistics corresponding to the {@link #getNewPacks()}. */ + /** + * Get statistics corresponding to the {@link #getNewPacks()}. + * <p> + * The elements can be null if the stat is not available for the pack file. + * + * @return statistics corresponding to the {@link #getNewPacks()}. + */ public List<PackStatistics> getNewPackStatistics() { return newPackStats; } @@ -637,7 +690,6 @@ public class DfsGarbageCollector { ProgressMonitor pm, long estimatedPackSize) throws IOException { DfsPackDescription pack = repo.getObjectDatabase().newPack(source, estimatedPackSize); - newPackDesc.add(pack); if (source == GC && reftableConfig != null) { writeReftable(pack); @@ -671,6 +723,7 @@ public class DfsGarbageCollector { PackStatistics stats = pw.getStatistics(); pack.setPackStats(stats); pack.setLastModified(startTimeMillis); + newPackDesc.add(pack); newPackStats.add(stats); newPackObj.add(pw.getObjectSet()); return pack; @@ -680,6 +733,7 @@ public class DfsGarbageCollector { if (reftableConfig != null) { DfsPackDescription pack = objdb.newPack(GC); newPackDesc.add(pack); + newPackStats.add(null); writeReftable(pack); } } @@ -693,7 +747,7 @@ public class DfsGarbageCollector { try (ReftableStack stack = ReftableStack.open(ctx, reftablesBefore)) { ReftableCompactor compact = new ReftableCompactor(); compact.addAll(stack.readers()); - compact.setIncludeDeletes(false); + compact.setIncludeDeletes(includeDeletes); compactReftable(pack, compact); } } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsInserter.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsInserter.java index 19e86522c6..eb0a527c5f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsInserter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsInserter.java @@ -92,7 +92,9 @@ import org.eclipse.jgit.util.TemporaryBuffer; import org.eclipse.jgit.util.io.CountingOutputStream; import org.eclipse.jgit.util.sha1.SHA1; -/** Inserts objects into the DFS. */ +/** + * Inserts objects into the DFS. + */ public class DfsInserter extends ObjectInserter { /** Always produce version 2 indexes, to get CRC data. */ private static final int INDEX_VERSION = 2; @@ -121,9 +123,12 @@ public class DfsInserter extends ObjectInserter { } /** + * Check existence + * * @param check - * if false, will write out possibly-duplicate objects without - * first checking whether they exist in the repo; default is true. + * if {@code false}, will write out possibly-duplicate objects + * without first checking whether they exist in the repo; default + * is true. */ public void checkExisting(boolean check) { checkExisting = check; @@ -133,16 +138,19 @@ public class DfsInserter extends ObjectInserter { this.compression = compression; } + /** {@inheritDoc} */ @Override public DfsPackParser newPackParser(InputStream in) throws IOException { return new DfsPackParser(db, this, in); } + /** {@inheritDoc} */ @Override public ObjectReader newReader() { return new Reader(); } + /** {@inheritDoc} */ @Override public ObjectId insert(int type, byte[] data, int off, int len) throws IOException { @@ -159,6 +167,7 @@ public class DfsInserter extends ObjectInserter { return endObject(id, offset); } + /** {@inheritDoc} */ @Override public ObjectId insert(int type, long len, InputStream in) throws IOException { @@ -201,6 +210,7 @@ public class DfsInserter extends ObjectInserter { return buf; } + /** {@inheritDoc} */ @Override public void flush() throws IOException { if (packDsc == null) @@ -228,6 +238,7 @@ public class DfsInserter extends ObjectInserter { clear(); } + /** {@inheritDoc} */ @Override public void close() { if (packOut != null) { @@ -605,17 +616,22 @@ public class DfsInserter extends ObjectInserter { try { return packOut.inflate(ctx, zpos, sz); } catch (DataFormatException dfe) { - CorruptObjectException coe = new CorruptObjectException( + throw new CorruptObjectException( MessageFormat.format( JGitText.get().objectAtHasBadZlibStream, Long.valueOf(obj.getOffset()), - packDsc.getFileName(PackExt.PACK))); - coe.initCause(dfe); - throw coe; + packDsc.getFileName(PackExt.PACK)), + dfe); } } @Override + public boolean has(AnyObjectId objectId) throws IOException { + return (objectMap != null && objectMap.contains(objectId)) + || ctx.has(objectId); + } + + @Override public Set<ObjectId> getShallowCommits() throws IOException { return ctx.getShallowCommits(); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsObjDatabase.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsObjDatabase.java index 9439822016..42b1a479d8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsObjDatabase.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsObjDatabase.java @@ -52,6 +52,7 @@ import java.util.Comparator; import java.util.HashMap; import java.util.List; import java.util.Map; +import java.util.Set; import java.util.concurrent.atomic.AtomicReference; import org.eclipse.jgit.internal.storage.pack.PackExt; @@ -60,7 +61,11 @@ import org.eclipse.jgit.lib.ObjectDatabase; import org.eclipse.jgit.lib.ObjectInserter; import org.eclipse.jgit.lib.ObjectReader; -/** Manages objects stored in {@link DfsPackFile} on a storage system. */ +/** + * Manages objects stored in + * {@link org.eclipse.jgit.internal.storage.dfs.DfsPackFile} on a storage + * system. + */ public abstract class DfsObjDatabase extends ObjectDatabase { private static final PackList NO_PACKS = new PackList( new DfsPackFile[0], @@ -156,7 +161,6 @@ public abstract class DfsObjDatabase extends ObjectDatabase { * * @param repository * repository owning this object database. - * * @param options * how readers should access the object database. */ @@ -167,16 +171,22 @@ public abstract class DfsObjDatabase extends ObjectDatabase { this.readerOptions = options; } - /** @return configured reader options, such as read-ahead. */ + /** + * Get configured reader options, such as read-ahead. + * + * @return configured reader options, such as read-ahead. + */ public DfsReaderOptions getReaderOptions() { return readerOptions; } + /** {@inheritDoc} */ @Override public DfsReader newReader() { return new DfsReader(this); } + /** {@inheritDoc} */ @Override public ObjectInserter newInserter() { return new DfsInserter(this); @@ -187,7 +197,7 @@ public abstract class DfsObjDatabase extends ObjectDatabase { * * @return list of available packs. The returned array is shared with the * implementation and must not be modified by the caller. - * @throws IOException + * @throws java.io.IOException * the pack list cannot be initialized. */ public DfsPackFile[] getPacks() throws IOException { @@ -199,7 +209,7 @@ public abstract class DfsObjDatabase extends ObjectDatabase { * * @return list of available reftables. The returned array is shared with * the implementation and must not be modified by the caller. - * @throws IOException + * @throws java.io.IOException * the pack list cannot be initialized. */ public DfsReftable[] getReftables() throws IOException { @@ -212,14 +222,18 @@ public abstract class DfsObjDatabase extends ObjectDatabase { * @return list of available packs, with some additional metadata. The * returned array is shared with the implementation and must not be * modified by the caller. - * @throws IOException + * @throws java.io.IOException * the pack list cannot be initialized. */ public PackList getPackList() throws IOException { return scanPacks(NO_PACKS); } - /** @return repository owning this object database. */ + /** + * Get repository owning this object database. + * + * @return repository owning this object database. + */ protected DfsRepository getRepository() { return repository; } @@ -266,7 +280,7 @@ public abstract class DfsObjDatabase extends ObjectDatabase { * @param avoidUnreachableObjects * if true, ignore objects that are unreachable. * @return true if the specified object is stored in this database. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public boolean has(AnyObjectId objectId, boolean avoidUnreachableObjects) @@ -284,7 +298,7 @@ public abstract class DfsObjDatabase extends ObjectDatabase { * where the pack stream is created. * @return a unique name for the pack file. Must not collide with any other * pack file name in the same DFS. - * @throws IOException + * @throws java.io.IOException * a new unique pack description cannot be generated. */ protected abstract DfsPackDescription newPack(PackSource source) @@ -298,7 +312,8 @@ public abstract class DfsObjDatabase extends ObjectDatabase { * {@code newPack(source).setEstimatedPackSize(estimatedPackSize)}. But the * clients can override this method to use the given * {@code estomatedPackSize} value more efficiently in the process of - * creating a new {@link DfsPackDescription} object. + * creating a new + * {@link org.eclipse.jgit.internal.storage.dfs.DfsPackDescription} object. * * @param source * where the pack stream is created. @@ -306,7 +321,7 @@ public abstract class DfsObjDatabase extends ObjectDatabase { * the estimated size of the pack. * @return a unique name for the pack file. Must not collide with any other * pack file name in the same DFS. - * @throws IOException + * @throws java.io.IOException * a new unique pack description cannot be generated. */ protected DfsPackDescription newPack(PackSource source, @@ -337,7 +352,7 @@ public abstract class DfsObjDatabase extends ObjectDatabase { * description of the new packs. * @param replaces * if not null, list of packs to remove. - * @throws IOException + * @throws java.io.IOException * the packs cannot be committed. On failure a rollback must * also be attempted by the caller. */ @@ -351,12 +366,11 @@ public abstract class DfsObjDatabase extends ObjectDatabase { * Implementation of pack commit. * * @see #commitPack(Collection, Collection) - * * @param desc * description of the new packs. * @param replaces * if not null, list of packs to remove. - * @throws IOException + * @throws java.io.IOException * the packs cannot be committed. */ protected abstract void commitPackImpl(Collection<DfsPackDescription> desc, @@ -387,7 +401,7 @@ public abstract class DfsObjDatabase extends ObjectDatabase { * DfsPackDescription objects. * * @return available packs. May be empty if there are no packs. - * @throws IOException + * @throws java.io.IOException * the packs cannot be listed and the object database is not * functional to the caller. */ @@ -404,9 +418,9 @@ public abstract class DfsObjDatabase extends ObjectDatabase { * @param ext * file extension that will be read i.e "pack" or "idx". * @return channel to read the file. - * @throws FileNotFoundException + * @throws java.io.FileNotFoundException * the file does not exist. - * @throws IOException + * @throws java.io.IOException * the file cannot be opened. */ protected abstract ReadableChannel openFile( @@ -423,7 +437,7 @@ public abstract class DfsObjDatabase extends ObjectDatabase { * @param ext * file extension that will be written i.e "pack" or "idx". * @return channel to write the file. - * @throws IOException + * @throws java.io.IOException * the file cannot be opened. */ protected abstract DfsOutputStream writeFile( @@ -445,8 +459,9 @@ public abstract class DfsObjDatabase extends ObjectDatabase { // add, as the pack was already committed via commitPack(). // If this is the case return without changing the list. for (DfsPackFile p : o.packs) { - if (p == newPack) + if (p.key.equals(newPack.key)) { return; + } } } @@ -457,6 +472,31 @@ public abstract class DfsObjDatabase extends ObjectDatabase { } while (!packList.compareAndSet(o, n)); } + void addReftable(DfsPackDescription add, Set<DfsPackDescription> remove) + throws IOException { + PackList o, n; + do { + o = packList.get(); + if (o == NO_PACKS) { + o = scanPacks(o); + for (DfsReftable t : o.reftables) { + if (t.getPackDescription().equals(add)) { + return; + } + } + } + + List<DfsReftable> tables = new ArrayList<>(1 + o.reftables.length); + for (DfsReftable t : o.reftables) { + if (!remove.contains(t.getPackDescription())) { + tables.add(t); + } + } + tables.add(new DfsReftable(add)); + n = new PackListImpl(o.packs, tables.toArray(new DfsReftable[0])); + } while (!packList.compareAndSet(o, n)); + } + PackList scanPacks(final PackList original) throws IOException { PackList o, n; synchronized (packList) { @@ -538,7 +578,11 @@ public abstract class DfsObjDatabase extends ObjectDatabase { return forReuse; } - /** @return comparator to sort {@link DfsReftable} by priority. */ + /** + * Get comparator to sort {@link DfsReftable} by priority. + * + * @return comparator to sort {@link DfsReftable} by priority. + */ protected Comparator<DfsReftable> reftableComparator() { return (fa, fb) -> { DfsPackDescription a = fa.getPackDescription(); @@ -566,11 +610,14 @@ public abstract class DfsObjDatabase extends ObjectDatabase { return s != null ? s.category : 0; } - /** Clears the cached list of packs, forcing them to be scanned again. */ + /** + * Clears the cached list of packs, forcing them to be scanned again. + */ protected void clearCache() { packList.set(NO_PACKS); } + /** {@inheritDoc} */ @Override public void close() { packList.set(NO_PACKS); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsObjectRepresentation.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsObjectRepresentation.java index ddcfff6082..1e388fdcdd 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsObjectRepresentation.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsObjectRepresentation.java @@ -57,21 +57,25 @@ class DfsObjectRepresentation extends StoredObjectRepresentation { this.pack = pack; } + /** {@inheritDoc} */ @Override public int getFormat() { return format; } + /** {@inheritDoc} */ @Override public int getWeight() { return (int) Math.min(length, Integer.MAX_VALUE); } + /** {@inheritDoc} */ @Override public ObjectId getDeltaBase() { return baseId; } + /** {@inheritDoc} */ @Override public boolean wasDeltaAttempted() { switch (pack.getPackDescription().getPackSource()) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsObjectToPack.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsObjectToPack.java index ff270bf974..3a04d70dbb 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsObjectToPack.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsObjectToPack.java @@ -72,12 +72,14 @@ class DfsObjectToPack extends ObjectToPack { setExtendedFlag(FLAG_FOUND); } + /** {@inheritDoc} */ @Override protected void clearReuseAsIs() { super.clearReuseAsIs(); pack = null; } + /** {@inheritDoc} */ @Override public void select(StoredObjectRepresentation ref) { DfsObjectRepresentation ptr = (DfsObjectRepresentation) ref; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsOutputStream.java index ef3173e87d..c28657039e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsOutputStream.java @@ -72,11 +72,13 @@ public abstract class DfsOutputStream extends OutputStream { return 0; } + /** {@inheritDoc} */ @Override public void write(int b) throws IOException { write(new byte[] { (byte) b }); } + /** {@inheritDoc} */ @Override public abstract void write(byte[] buf, int off, int len) throws IOException; @@ -91,7 +93,7 @@ public abstract class DfsOutputStream extends OutputStream { * buffer to populate. Up to {@code buf.remaining()} bytes will * be read from {@code position}. * @return number of bytes actually read. - * @throws IOException + * @throws java.io.IOException * reading is not supported, or the read cannot be performed due * to DFS errors. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPackCompactor.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPackCompactor.java index 99663eb738..ab7633281c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPackCompactor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPackCompactor.java @@ -126,6 +126,8 @@ public class DfsPackCompactor { } /** + * Set configuration to write a reftable. + * * @param cfg * configuration to write a reftable. Reftable compacting is * disabled (default) when {@code cfg} is {@code null}. @@ -172,7 +174,7 @@ public class DfsPackCompactor { * ones are omitted. * * @return {@code this} - * @throws IOException + * @throws java.io.IOException * existing packs cannot be read. */ public DfsPackCompactor autoAdd() throws IOException { @@ -215,7 +217,7 @@ public class DfsPackCompactor { * @param pack * objects to not include. * @return {@code this}. - * @throws IOException + * @throws java.io.IOException * pack index cannot be loaded. */ public DfsPackCompactor exclude(DfsPackFile pack) throws IOException { @@ -232,7 +234,7 @@ public class DfsPackCompactor { * @param pm * progress monitor to receive updates on as packing may take a * while, depending on the size of the repository. - * @throws IOException + * @throws java.io.IOException * the packs cannot be compacted. */ public void compact(ProgressMonitor pm) throws IOException { @@ -331,7 +333,11 @@ public class DfsPackCompactor { } } - /** @return all of the source packs that fed into this compaction. */ + /** + * Get all of the source packs that fed into this compaction. + * + * @return all of the source packs that fed into this compaction. + */ public Collection<DfsPackDescription> getSourcePacks() { Set<DfsPackDescription> src = new HashSet<>(); for (DfsPackFile pack : srcPacks) { @@ -343,16 +349,26 @@ public class DfsPackCompactor { return src; } - /** @return new packs created by this compaction. */ + /** + * Get new packs created by this compaction. + * + * @return new packs created by this compaction. + */ public List<DfsPackDescription> getNewPacks() { return outDesc != null ? Collections.singletonList(outDesc) : Collections.emptyList(); } - /** @return statistics corresponding to the {@link #getNewPacks()}. */ + /** + * Get statistics corresponding to the {@link #getNewPacks()}. + * May be null if statistics are not available. + * + * @return statistics corresponding to the {@link #getNewPacks()}. + * + */ public List<PackStatistics> getNewPackStatistics() { - return newStats != null + return outDesc != null ? Collections.singletonList(newStats) : Collections.emptyList(); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPackDescription.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPackDescription.java index e865e6b542..45eb7b0e1a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPackDescription.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPackDescription.java @@ -104,7 +104,11 @@ public class DfsPackDescription implements Comparable<DfsPackDescription> { blockSizeMap = new int[extCnt]; } - /** @return description of the repository. */ + /** + * Get description of the repository. + * + * @return description of the repository. + */ public DfsRepositoryDescription getRepositoryDescription() { return repoDesc; } @@ -120,15 +124,19 @@ public class DfsPackDescription implements Comparable<DfsPackDescription> { } /** + * Whether the pack file extension is known to exist. + * * @param ext * the file extension - * @return whether the pack file extensions is known to exist. + * @return whether the pack file extension is known to exist. */ public boolean hasFileExt(PackExt ext) { return (extensions & ext.getBit()) != 0; } /** + * Get file name + * * @param ext * the file extension * @return name of the file. @@ -138,20 +146,29 @@ public class DfsPackDescription implements Comparable<DfsPackDescription> { } /** + * Get cache key for use by the block cache. + * * @param ext * the file extension. * @return cache key for use by the block cache. */ public DfsStreamKey getStreamKey(PackExt ext) { - return DfsStreamKey.of(getRepositoryDescription(), getFileName(ext)); + return DfsStreamKey.of(getRepositoryDescription(), getFileName(ext), + ext); } - /** @return the source of the pack. */ + /** + * Get the source of the pack. + * + * @return the source of the pack. + */ public PackSource getPackSource() { return packSource; } /** + * Set the source of the pack. + * * @param source * the source of the pack. * @return {@code this} @@ -161,12 +178,18 @@ public class DfsPackDescription implements Comparable<DfsPackDescription> { return this; } - /** @return time the pack was created, in milliseconds. */ + /** + * Get time the pack was created, in milliseconds. + * + * @return time the pack was created, in milliseconds. + */ public long getLastModified() { return lastModified; } /** + * Set time the pack was created, in milliseconds. + * * @param timeMillis * time the pack was created, in milliseconds. 0 if not known. * @return {@code this} @@ -176,14 +199,20 @@ public class DfsPackDescription implements Comparable<DfsPackDescription> { return this; } - /** @return minUpdateIndex for the reftable, if present. */ + /** + * Get minUpdateIndex for the reftable, if present. + * + * @return minUpdateIndex for the reftable, if present. + */ public long getMinUpdateIndex() { return minUpdateIndex; } /** + * Set minUpdateIndex for the reftable. + * * @param min - * minUpdateIndex for the reftable, or 0. + * minUpdateIndex for the reftable. * @return {@code this} */ public DfsPackDescription setMinUpdateIndex(long min) { @@ -191,14 +220,20 @@ public class DfsPackDescription implements Comparable<DfsPackDescription> { return this; } - /** @return maxUpdateIndex for the reftable, if present. */ + /** + * Get maxUpdateIndex for the reftable, if present. + * + * @return maxUpdateIndex for the reftable, if present. + */ public long getMaxUpdateIndex() { return maxUpdateIndex; } /** + * Set maxUpdateIndex for the reftable. + * * @param max - * maxUpdateIndex for the reftable, or 0. + * maxUpdateIndex for the reftable. * @return {@code this} */ public DfsPackDescription setMaxUpdateIndex(long max) { @@ -207,6 +242,8 @@ public class DfsPackDescription implements Comparable<DfsPackDescription> { } /** + * Set size of the file in bytes. + * * @param ext * the file extension. * @param bytes @@ -224,6 +261,8 @@ public class DfsPackDescription implements Comparable<DfsPackDescription> { } /** + * Get size of the file, in bytes. + * * @param ext * the file extension. * @return size of the file, in bytes. If 0 the file size is not yet known. @@ -234,6 +273,8 @@ public class DfsPackDescription implements Comparable<DfsPackDescription> { } /** + * Get blockSize of the file, in bytes. + * * @param ext * the file extension. * @return blockSize of the file, in bytes. If 0 the blockSize size is not @@ -245,6 +286,8 @@ public class DfsPackDescription implements Comparable<DfsPackDescription> { } /** + * Set blockSize of the file, in bytes. + * * @param ext * the file extension. * @param blockSize @@ -262,6 +305,8 @@ public class DfsPackDescription implements Comparable<DfsPackDescription> { } /** + * Set estimated size of the .pack file in bytes. + * * @param estimatedPackSize * estimated size of the .pack file in bytes. If 0 the pack file * size is unknown. @@ -273,6 +318,8 @@ public class DfsPackDescription implements Comparable<DfsPackDescription> { } /** + * Get estimated size of the .pack file in bytes. + * * @return estimated size of the .pack file in bytes. If 0 the pack file * size is unknown. */ @@ -280,12 +327,18 @@ public class DfsPackDescription implements Comparable<DfsPackDescription> { return estimatedPackSize; } - /** @return number of objects in the pack. */ + /** + * Get number of objects in the pack. + * + * @return number of objects in the pack. + */ public long getObjectCount() { return objectCount; } /** + * Set number of objects in the pack. + * * @param cnt * number of objects in the pack. * @return {@code this} @@ -295,12 +348,18 @@ public class DfsPackDescription implements Comparable<DfsPackDescription> { return this; } - /** @return number of delta compressed objects in the pack. */ + /** + * Get number of delta compressed objects in the pack. + * + * @return number of delta compressed objects in the pack. + */ public long getDeltaCount() { return deltaCount; } /** + * Set number of delta compressed objects in the pack. + * * @param cnt * number of delta compressed objects in the pack. * @return {@code this} @@ -311,6 +370,8 @@ public class DfsPackDescription implements Comparable<DfsPackDescription> { } /** + * Get statistics from PackWriter, if the pack was built with it. + * * @return statistics from PackWriter, if the pack was built with it. * Generally this is only available for packs created by * DfsGarbageCollector or DfsPackCompactor, and only when the pack @@ -328,7 +389,11 @@ public class DfsPackDescription implements Comparable<DfsPackDescription> { return this; } - /** @return stats from the sibling reftable, if created. */ + /** + * Get stats from the sibling reftable, if created. + * + * @return stats from the sibling reftable, if created. + */ public ReftableWriter.Stats getReftableStats() { return refStats; } @@ -352,12 +417,18 @@ public class DfsPackDescription implements Comparable<DfsPackDescription> { return this; } - /** @return the version of the index file written. */ + /** + * Get the version of the index file written. + * + * @return the version of the index file written. + */ public int getIndexVersion() { return indexVersion; } /** + * Set the version of the index file written. + * * @param version * the version of the index file written. * @return {@code this} @@ -367,11 +438,13 @@ public class DfsPackDescription implements Comparable<DfsPackDescription> { return this; } + /** {@inheritDoc} */ @Override public int hashCode() { return packName.hashCode(); } + /** {@inheritDoc} */ @Override public boolean equals(Object b) { if (b instanceof DfsPackDescription) { @@ -383,15 +456,14 @@ public class DfsPackDescription implements Comparable<DfsPackDescription> { } /** + * {@inheritDoc} + * <p> * Sort packs according to the optimal lookup ordering. * <p> * This method tries to position packs in the order readers should examine * them when looking for objects by SHA-1. The default tries to sort packs * with more recent modification dates before older packs, and packs with * fewer objects before packs with more objects. - * - * @param b - * the other pack. */ @Override public int compareTo(DfsPackDescription b) { @@ -437,6 +509,7 @@ public class DfsPackDescription implements Comparable<DfsPackDescription> { } } + /** {@inheritDoc} */ @Override public String toString() { return getFileName(PackExt.PACK); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPackFile.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPackFile.java index dfb41e204f..7e360421ac 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPackFile.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPackFile.java @@ -133,12 +133,18 @@ public final class DfsPackFile extends BlockBasedFile { length = sz > 0 ? sz : -1; } - /** @return description that was originally used to configure this pack file. */ + /** + * Get description that was originally used to configure this pack file. + * + * @return description that was originally used to configure this pack file. + */ public DfsPackDescription getPackDescription() { return desc; } /** + * Whether the pack index file is loaded and cached in memory. + * * @return whether the pack index file is loaded and cached in memory. */ public boolean isIndexLoaded() { @@ -160,7 +166,7 @@ public final class DfsPackFile extends BlockBasedFile { * reader context to support reading from the backing store if * the index is not already loaded in memory. * @return the PackIndex. - * @throws IOException + * @throws java.io.IOException * the pack index is not available, or is corrupt. */ public PackIndex getPackIndex(DfsReader ctx) throws IOException { @@ -350,7 +356,7 @@ public final class DfsPackFile extends BlockBasedFile { * @param id * object to be located. * @return true if the object exists in this pack; false if it does not. - * @throws IOException + * @throws java.io.IOException * the pack index is not available, or is corrupt. */ public boolean hasObject(DfsReader ctx, AnyObjectId id) throws IOException { @@ -533,10 +539,8 @@ public final class DfsPackFile extends BlockBasedFile { try { readFully(src.offset, buf, 0, 20, ctx); } catch (IOException ioError) { - StoredObjectRepresentationNotAvailableException gone; - gone = new StoredObjectRepresentationNotAvailableException(src); - gone.initCause(ioError); - throw gone; + throw new StoredObjectRepresentationNotAvailableException(src, + ioError); } int c = buf[0] & 0xff; final int typeCode = (c >> 4) & 7; @@ -653,19 +657,15 @@ public final class DfsPackFile extends BlockBasedFile { CorruptObjectException corruptObject = new CorruptObjectException( MessageFormat.format( JGitText.get().objectAtHasBadZlibStream, - Long.valueOf(src.offset), getFileName())); - corruptObject.initCause(dataFormat); + Long.valueOf(src.offset), getFileName()), + dataFormat); - StoredObjectRepresentationNotAvailableException gone; - gone = new StoredObjectRepresentationNotAvailableException(src); - gone.initCause(corruptObject); - throw gone; + throw new StoredObjectRepresentationNotAvailableException(src, + corruptObject); } catch (IOException ioError) { - StoredObjectRepresentationNotAvailableException gone; - gone = new StoredObjectRepresentationNotAvailableException(src); - gone.initCause(ioError); - throw gone; + throw new StoredObjectRepresentationNotAvailableException(src, + ioError); } if (quickCopy != null) { @@ -866,12 +866,11 @@ public final class DfsPackFile extends BlockBasedFile { return new ObjectLoader.SmallObject(type, data); } catch (DataFormatException dfe) { - CorruptObjectException coe = new CorruptObjectException( + throw new CorruptObjectException( MessageFormat.format( JGitText.get().objectAtHasBadZlibStream, Long.valueOf(pos), - getFileName())); - coe.initCause(dfe); - throw coe; + getFileName()), + dfe); } } @@ -1014,12 +1013,11 @@ public final class DfsPackFile extends BlockBasedFile { try { return BinaryDelta.getResultSize(getDeltaHeader(ctx, deltaAt)); } catch (DataFormatException dfe) { - CorruptObjectException coe = new CorruptObjectException( + throw new CorruptObjectException( MessageFormat.format( JGitText.get().objectAtHasBadZlibStream, Long.valueOf(pos), - getFileName())); - coe.initCause(dfe); - throw coe; + getFileName()), + dfe); } } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPackParser.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPackParser.java index fd99db1e28..3a30d7daf5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPackParser.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPackParser.java @@ -63,7 +63,9 @@ import org.eclipse.jgit.lib.ProgressMonitor; import org.eclipse.jgit.transport.PackParser; import org.eclipse.jgit.transport.PackedObjectInfo; -/** Parses a pack stream into the DFS, by creating a new pack and index. */ +/** + * Parses a pack stream into the DFS, by creating a new pack and index. + */ public class DfsPackParser extends PackParser { private final DfsObjDatabase objdb; @@ -132,6 +134,7 @@ public class DfsPackParser extends PackParser { this.packDigest = Constants.newMessageDigest(); } + /** {@inheritDoc} */ @Override public PackLock parse(ProgressMonitor receiving, ProgressMonitor resolving) throws IOException { @@ -193,11 +196,16 @@ public class DfsPackParser extends PackParser { } } - /** @return description of the imported pack, if one was made. */ + /** + * Get description of the imported pack, if one was made. + * + * @return description of the imported pack, if one was made. + */ public DfsPackDescription getPackDescription() { return packDsc; } + /** {@inheritDoc} */ @Override protected void onPackHeader(long objectCount) throws IOException { if (objectCount == 0) { @@ -219,29 +227,34 @@ public class DfsPackParser extends PackParser { currBuf = new byte[blockSize]; } + /** {@inheritDoc} */ @Override protected void onBeginWholeObject(long streamPosition, int type, long inflatedSize) throws IOException { crc.reset(); } + /** {@inheritDoc} */ @Override protected void onEndWholeObject(PackedObjectInfo info) throws IOException { info.setCRC((int) crc.getValue()); } + /** {@inheritDoc} */ @Override protected void onBeginOfsDelta(long streamPosition, long baseStreamPosition, long inflatedSize) throws IOException { crc.reset(); } + /** {@inheritDoc} */ @Override protected void onBeginRefDelta(long streamPosition, AnyObjectId baseId, long inflatedSize) throws IOException { crc.reset(); } + /** {@inheritDoc} */ @Override protected UnresolvedDelta onEndDelta() throws IOException { UnresolvedDelta delta = new UnresolvedDelta(); @@ -249,24 +262,28 @@ public class DfsPackParser extends PackParser { return delta; } + /** {@inheritDoc} */ @Override protected void onInflatedObjectData(PackedObjectInfo obj, int typeCode, byte[] data) throws IOException { // DfsPackParser ignores this event. } + /** {@inheritDoc} */ @Override protected void onObjectHeader(Source src, byte[] raw, int pos, int len) throws IOException { crc.update(raw, pos, len); } + /** {@inheritDoc} */ @Override protected void onObjectData(Source src, byte[] raw, int pos, int len) throws IOException { crc.update(raw, pos, len); } + /** {@inheritDoc} */ @Override protected void onStoreStream(byte[] raw, int pos, int len) throws IOException { @@ -313,6 +330,7 @@ public class DfsPackParser extends PackParser { return v; } + /** {@inheritDoc} */ @Override protected void onPackFooter(byte[] hash) throws IOException { // The base class will validate the original hash matches @@ -322,6 +340,7 @@ public class DfsPackParser extends PackParser { packHash = hash; } + /** {@inheritDoc} */ @Override protected ObjectTypeAndSize seekDatabase(PackedObjectInfo obj, ObjectTypeAndSize info) throws IOException { @@ -330,6 +349,7 @@ public class DfsPackParser extends PackParser { return readObjectHeader(info); } + /** {@inheritDoc} */ @Override protected ObjectTypeAndSize seekDatabase(UnresolvedDelta delta, ObjectTypeAndSize info) throws IOException { @@ -338,6 +358,7 @@ public class DfsPackParser extends PackParser { return readObjectHeader(info); } + /** {@inheritDoc} */ @Override protected int readDatabase(byte[] dst, int pos, int cnt) throws IOException { if (cnt == 0) @@ -393,11 +414,13 @@ public class DfsPackParser extends PackParser { return (pos / blockSize) * blockSize; } + /** {@inheritDoc} */ @Override protected boolean checkCRC(int oldCRC) { return oldCRC == (int) crc.getValue(); } + /** {@inheritDoc} */ @Override protected boolean onAppendBase(final int typeCode, final byte[] data, final PackedObjectInfo info) throws IOException { @@ -437,6 +460,7 @@ public class DfsPackParser extends PackParser { return true; } + /** {@inheritDoc} */ @Override protected void onEndThinPack() throws IOException { // Normally when a thin pack is closed the pack header gets diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPacksChangedEvent.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPacksChangedEvent.java index 14d67c057f..d9fc71f4ef 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPacksChangedEvent.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPacksChangedEvent.java @@ -45,14 +45,19 @@ package org.eclipse.jgit.internal.storage.dfs; import org.eclipse.jgit.events.RepositoryEvent; -/** Describes a change to the list of packs in a {@link DfsRepository}. */ +/** + * Describes a change to the list of packs in a + * {@link org.eclipse.jgit.internal.storage.dfs.DfsRepository}. + */ public class DfsPacksChangedEvent extends RepositoryEvent<DfsPacksChangedListener> { + /** {@inheritDoc} */ @Override public Class<DfsPacksChangedListener> getListenerType() { return DfsPacksChangedListener.class; } + /** {@inheritDoc} */ @Override public void dispatch(DfsPacksChangedListener listener) { listener.onPacksChanged(this); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPacksChangedListener.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPacksChangedListener.java index 324626cbad..3ea82137c3 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPacksChangedListener.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsPacksChangedListener.java @@ -45,7 +45,9 @@ package org.eclipse.jgit.internal.storage.dfs; import org.eclipse.jgit.events.RepositoryListener; -/** Receives {@link DfsPacksChangedEvent}s. */ +/** + * Receives {@link org.eclipse.jgit.internal.storage.dfs.DfsPacksChangedEvent}s. + */ public interface DfsPacksChangedListener extends RepositoryListener { /** * Invoked when all packs in a repository are listed. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsReader.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsReader.java index 3c8422077b..27a7992c9e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsReader.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsReader.java @@ -92,8 +92,8 @@ import org.eclipse.jgit.util.BlockList; /** * Reader to access repository content through. * <p> - * See the base {@link ObjectReader} documentation for details. Notably, a - * reader is not thread safe. + * See the base {@link org.eclipse.jgit.lib.ObjectReader} documentation for + * details. Notably, a reader is not thread safe. */ public class DfsReader extends ObjectReader implements ObjectReuseAsIs { private static final int MAX_RESOLVE_MATCHES = 256; @@ -133,16 +133,19 @@ public class DfsReader extends ObjectReader implements ObjectReuseAsIs { return baseCache; } + /** {@inheritDoc} */ @Override public ObjectReader newReader() { return db.newReader(); } + /** {@inheritDoc} */ @Override public void setAvoidUnreachableObjects(boolean avoid) { avoidUnreachable = avoid; } + /** {@inheritDoc} */ @Override public BitmapIndex getBitmapIndex() throws IOException { for (DfsPackFile pack : db.getPacks()) { @@ -153,6 +156,7 @@ public class DfsReader extends ObjectReader implements ObjectReuseAsIs { return null; } + /** {@inheritDoc} */ @Override public Collection<CachedPack> getCachedPacksAndUpdate( BitmapBuilder needBitmap) throws IOException { @@ -165,6 +169,7 @@ public class DfsReader extends ObjectReader implements ObjectReuseAsIs { return Collections.emptyList(); } + /** {@inheritDoc} */ @Override public Collection<ObjectId> resolve(AbbreviatedObjectId id) throws IOException { @@ -193,6 +198,7 @@ public class DfsReader extends ObjectReader implements ObjectReuseAsIs { } } + /** {@inheritDoc} */ @Override public boolean has(AnyObjectId objectId) throws IOException { if (last != null @@ -222,6 +228,7 @@ public class DfsReader extends ObjectReader implements ObjectReuseAsIs { return false; } + /** {@inheritDoc} */ @Override public ObjectLoader open(AnyObjectId objectId, int typeHint) throws MissingObjectException, IncorrectObjectTypeException, @@ -276,6 +283,7 @@ public class DfsReader extends ObjectReader implements ObjectReuseAsIs { return null; } + /** {@inheritDoc} */ @Override public Set<ObjectId> getShallowCommits() { return Collections.emptySet(); @@ -385,6 +393,7 @@ public class DfsReader extends ObjectReader implements ObjectReuseAsIs { return avoidUnreachable && pack.isGarbage(); } + /** {@inheritDoc} */ @Override public <T extends ObjectId> AsyncObjectLoaderQueue<T> open( Iterable<T> objectIds, final boolean reportMissing) { @@ -444,6 +453,7 @@ public class DfsReader extends ObjectReader implements ObjectReuseAsIs { }; } + /** {@inheritDoc} */ @Override public <T extends ObjectId> AsyncObjectSizeQueue<T> getObjectSize( Iterable<T> objectIds, final boolean reportMissing) { @@ -505,6 +515,7 @@ public class DfsReader extends ObjectReader implements ObjectReuseAsIs { }; } + /** {@inheritDoc} */ @Override public long getObjectSize(AnyObjectId objectId, int typeHint) throws MissingObjectException, IncorrectObjectTypeException, @@ -550,6 +561,7 @@ public class DfsReader extends ObjectReader implements ObjectReuseAsIs { return -1; } + /** {@inheritDoc} */ @Override public DfsObjectToPack newObjectToPack(AnyObjectId objectId, int type) { return new DfsObjectToPack(objectId, type); @@ -631,6 +643,7 @@ public class DfsReader extends ObjectReader implements ObjectReuseAsIs { return tmp; } + /** {@inheritDoc} */ @Override public void copyObjectAsIs(PackOutputStream out, ObjectToPack otp, boolean validate) throws IOException, @@ -639,6 +652,7 @@ public class DfsReader extends ObjectReader implements ObjectReuseAsIs { src.pack.copyAsIs(out, src, validate, this); } + /** {@inheritDoc} */ @Override public void writeObjects(PackOutputStream out, List<ObjectToPack> list) throws IOException { @@ -646,6 +660,7 @@ public class DfsReader extends ObjectReader implements ObjectReuseAsIs { out.writeObject(otp); } + /** {@inheritDoc} */ @Override public void copyPackAsIs(PackOutputStream out, CachedPack pack) throws IOException { @@ -771,12 +786,20 @@ public class DfsReader extends ObjectReader implements ObjectReuseAsIs { block = null; } - /** @return IO statistics accumulated by this reader. */ + /** + * Get IO statistics accumulated by this reader. + * + * @return IO statistics accumulated by this reader. + */ public DfsReaderIoStats getIoStats() { return new DfsReaderIoStats(stats); } - /** Release the current window cursor. */ + /** + * {@inheritDoc} + * <p> + * Release the current window cursor. + */ @Override public void close() { last = null; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsReaderIoStats.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsReaderIoStats.java index 9a174c81d0..cf925c914d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsReaderIoStats.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsReaderIoStats.java @@ -43,7 +43,9 @@ package org.eclipse.jgit.internal.storage.dfs; -/** IO statistics for a {@link DfsReader}. */ +/** + * IO statistics for a {@link org.eclipse.jgit.internal.storage.dfs.DfsReader}. + */ public class DfsReaderIoStats { /** POJO to accumulate IO statistics. */ public static class Accumulator { @@ -87,52 +89,92 @@ public class DfsReaderIoStats { this.stats = stats; } - /** @return number of times the reader explicitly called scanPacks. */ + /** + * Get number of times the reader explicitly called scanPacks. + * + * @return number of times the reader explicitly called scanPacks. + */ public long getScanPacks() { return stats.scanPacks; } - /** @return total number of complete pack indexes read into memory. */ + /** + * Get total number of complete pack indexes read into memory. + * + * @return total number of complete pack indexes read into memory. + */ public long getReadPackIndexCount() { return stats.readIdx; } - /** @return total number of complete bitmap indexes read into memory. */ + /** + * Get total number of complete bitmap indexes read into memory. + * + * @return total number of complete bitmap indexes read into memory. + */ public long getReadBitmapIndexCount() { return stats.readBitmap; } - /** @return total number of bytes read from indexes. */ + /** + * Get total number of bytes read from indexes. + * + * @return total number of bytes read from indexes. + */ public long getReadIndexBytes() { return stats.readIdxBytes; } - /** @return total microseconds spent reading pack or bitmap indexes. */ + /** + * Get total microseconds spent reading pack or bitmap indexes. + * + * @return total microseconds spent reading pack or bitmap indexes. + */ public long getReadIndexMicros() { return stats.readIdxMicros; } - /** @return total number of block cache hits. */ + /** + * Get total number of block cache hits. + * + * @return total number of block cache hits. + */ public long getBlockCacheHits() { return stats.blockCacheHit; } - /** @return total number of discrete blocks read from pack file(s). */ + /** + * Get total number of discrete blocks read from pack file(s). + * + * @return total number of discrete blocks read from pack file(s). + */ public long getReadBlocksCount() { return stats.readBlock; } - /** @return total number of compressed bytes read as block sized units. */ + /** + * Get total number of compressed bytes read as block sized units. + * + * @return total number of compressed bytes read as block sized units. + */ public long getReadBlocksBytes() { return stats.readBlockBytes; } - /** @return total microseconds spent reading blocks. */ + /** + * Get total microseconds spent reading blocks. + * + * @return total microseconds spent reading blocks. + */ public long getReadBlocksMicros() { return stats.readBlockMicros; } - /** @return total number of bytes decompressed. */ + /** + * Get total number of bytes decompressed. + * + * @return total number of bytes decompressed. + */ public long getInflatedBytes() { return stats.inflatedBytes; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsReaderOptions.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsReaderOptions.java index d07c13d0b0..bf14d18e32 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsReaderOptions.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsReaderOptions.java @@ -52,7 +52,9 @@ import static org.eclipse.jgit.lib.ConfigConstants.CONFIG_KEY_STREAM_FILE_TRESHO import org.eclipse.jgit.lib.Config; import org.eclipse.jgit.storage.pack.PackConfig; -/** Options controlling how objects are read from a DFS stored repository. */ +/** + * Options controlling how objects are read from a DFS stored repository. + */ public class DfsReaderOptions { /** 1024 (number of bytes in one kibibyte/kilobyte) */ public static final int KiB = 1024; @@ -65,13 +67,19 @@ public class DfsReaderOptions { private int streamPackBufferSize; - /** Create a default reader configuration. */ + /** + * Create a default reader configuration. + */ public DfsReaderOptions() { setDeltaBaseCacheLimit(10 * MiB); setStreamFileThreshold(PackConfig.DEFAULT_BIG_FILE_THRESHOLD); } - /** @return maximum number of bytes to hold in per-reader DeltaBaseCache. */ + /** + * Get maximum number of bytes to hold in per-reader DeltaBaseCache. + * + * @return maximum number of bytes to hold in per-reader DeltaBaseCache. + */ public int getDeltaBaseCacheLimit() { return deltaBaseCacheLimit; } @@ -88,12 +96,18 @@ public class DfsReaderOptions { return this; } - /** @return the size threshold beyond which objects must be streamed. */ + /** + * Get the size threshold beyond which objects must be streamed. + * + * @return the size threshold beyond which objects must be streamed. + */ public int getStreamFileThreshold() { return streamFileThreshold; } /** + * Set new byte limit for objects that must be streamed. + * * @param newLimit * new byte limit for objects that must be streamed. Objects * smaller than this size can be obtained as a contiguous byte @@ -107,6 +121,9 @@ public class DfsReaderOptions { } /** + * Get number of bytes to use for buffering when streaming a pack file + * during copying. + * * @return number of bytes to use for buffering when streaming a pack file * during copying. If 0 the block size of the pack is used. */ @@ -115,6 +132,9 @@ public class DfsReaderOptions { } /** + * Set new buffer size in bytes for buffers used when streaming pack files + * during copying. + * * @param bufsz * new buffer size in bytes for buffers used when streaming pack * files during copying. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRefDatabase.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRefDatabase.java index b41c18b6c2..a884346842 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRefDatabase.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRefDatabase.java @@ -64,7 +64,10 @@ import org.eclipse.jgit.revwalk.RevWalk; import org.eclipse.jgit.util.RefList; import org.eclipse.jgit.util.RefMap; -/** */ +/** + * Abstract DfsRefDatabase class. + * + */ public abstract class DfsRefDatabase extends RefDatabase { private final DfsRepository repository; @@ -81,7 +84,11 @@ public abstract class DfsRefDatabase extends RefDatabase { this.cache = new AtomicReference<>(); } - /** @return the repository the database holds the references of. */ + /** + * Get the repository the database holds the references of. + * + * @return the repository the database holds the references of. + */ protected DfsRepository getRepository() { return repository; } @@ -90,6 +97,7 @@ public abstract class DfsRefDatabase extends RefDatabase { return 0 < read().size(); } + /** {@inheritDoc} */ @Override public Ref exactRef(String name) throws IOException { RefCache curr = read(); @@ -97,6 +105,7 @@ public abstract class DfsRefDatabase extends RefDatabase { return ref != null ? resolve(ref, 0, curr.ids) : null; } + /** {@inheritDoc} */ @Override public Ref getRef(String needle) throws IOException { RefCache curr = read(); @@ -110,11 +119,13 @@ public abstract class DfsRefDatabase extends RefDatabase { return null; } + /** {@inheritDoc} */ @Override public List<Ref> getAdditionalRefs() { return Collections.emptyList(); } + /** {@inheritDoc} */ @Override public Map<String, Ref> getRefs(String prefix) throws IOException { RefCache curr = read(); @@ -161,6 +172,7 @@ public abstract class DfsRefDatabase extends RefDatabase { return new SymbolicRef(ref.getName(), dst); } + /** {@inheritDoc} */ @Override public Ref peel(Ref ref) throws IOException { final Ref oldLeaf = ref.getLeaf(); @@ -180,7 +192,7 @@ public abstract class DfsRefDatabase extends RefDatabase { return recreate(ref, newLeaf); } - private Ref doPeel(final Ref leaf) throws MissingObjectException, + Ref doPeel(Ref leaf) throws MissingObjectException, IOException { try (RevWalk rw = new RevWalk(repository)) { RevObject obj = rw.parseAny(leaf.getObjectId()); @@ -199,7 +211,7 @@ public abstract class DfsRefDatabase extends RefDatabase { } } - private static Ref recreate(Ref old, Ref leaf) { + static Ref recreate(Ref old, Ref leaf) { if (old.isSymbolic()) { Ref dst = recreate(old.getTarget(), leaf); return new SymbolicRef(old.getName(), dst); @@ -207,6 +219,7 @@ public abstract class DfsRefDatabase extends RefDatabase { return leaf; } + /** {@inheritDoc} */ @Override public RefUpdate newUpdate(String refName, boolean detach) throws IOException { @@ -223,6 +236,7 @@ public abstract class DfsRefDatabase extends RefDatabase { return update; } + /** {@inheritDoc} */ @Override public RefRename newRename(String fromName, String toName) throws IOException { @@ -231,6 +245,7 @@ public abstract class DfsRefDatabase extends RefDatabase { return new DfsRefRename(src, dst); } + /** {@inheritDoc} */ @Override public boolean isNameConflicting(String refName) throws IOException { RefList<Ref> all = read().ids; @@ -252,16 +267,19 @@ public abstract class DfsRefDatabase extends RefDatabase { return false; } + /** {@inheritDoc} */ @Override public void create() { // Nothing to do. } + /** {@inheritDoc} */ @Override public void refresh() { clearCache(); } + /** {@inheritDoc} */ @Override public void close() { clearCache(); @@ -304,7 +322,7 @@ public abstract class DfsRefDatabase extends RefDatabase { * Read all known references in the repository. * * @return all current references of the repository. - * @throws IOException + * @throws java.io.IOException * references cannot be accessed. */ protected abstract RefCache scanAllRefs() throws IOException; @@ -329,7 +347,7 @@ public abstract class DfsRefDatabase extends RefDatabase { * @param newRef * new reference to store. * @return true if the put was successful; false otherwise. - * @throws IOException + * @throws java.io.IOException * the reference cannot be put due to a system error. */ protected abstract boolean compareAndPut(Ref oldRef, Ref newRef) @@ -341,7 +359,7 @@ public abstract class DfsRefDatabase extends RefDatabase { * @param oldRef * the old reference information that was previously read. * @return true if the remove was successful; false otherwise. - * @throws IOException + * @throws java.io.IOException * the reference could not be removed due to a system error. */ protected abstract boolean compareAndRemove(Ref oldRef) throws IOException; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRefRename.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRefRename.java index d9c2bc7467..65ef366d47 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRefRename.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRefRename.java @@ -55,6 +55,7 @@ final class DfsRefRename extends RefRename { super(src, dst); } + /** {@inheritDoc} */ @Override protected Result doRename() throws IOException { // TODO Correctly handle renaming foo/bar to foo. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRefUpdate.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRefUpdate.java index 1f26fe35ff..de65c68f95 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRefUpdate.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRefUpdate.java @@ -66,16 +66,19 @@ final class DfsRefUpdate extends RefUpdate { this.refdb = refdb; } + /** {@inheritDoc} */ @Override protected DfsRefDatabase getRefDatabase() { return refdb; } + /** {@inheritDoc} */ @Override protected DfsRepository getRepository() { return refdb.getRepository(); } + /** {@inheritDoc} */ @Override protected boolean tryLock(boolean deref) throws IOException { dstRef = getRef(); @@ -90,11 +93,13 @@ final class DfsRefUpdate extends RefUpdate { return true; } + /** {@inheritDoc} */ @Override protected void unlock() { // No state is held while "locked". } + /** {@inheritDoc} */ @Override public Result update(RevWalk walk) throws IOException { try { @@ -105,6 +110,7 @@ final class DfsRefUpdate extends RefUpdate { } } + /** {@inheritDoc} */ @Override protected Result doUpdate(Result desiredResult) throws IOException { ObjectIdRef newRef; @@ -129,6 +135,7 @@ final class DfsRefUpdate extends RefUpdate { return Result.LOCK_FAILURE; } + /** {@inheritDoc} */ @Override protected Result doDelete(Result desiredResult) throws IOException { if (getRefDatabase().compareAndRemove(dstRef)) { @@ -138,6 +145,7 @@ final class DfsRefUpdate extends RefUpdate { return Result.LOCK_FAILURE; } + /** {@inheritDoc} */ @Override protected Result doLink(String target) throws IOException { final SymbolicRef newRef = new SymbolicRef( diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsReftable.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsReftable.java index 5a8ea92a84..7502471b0c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsReftable.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsReftable.java @@ -51,7 +51,9 @@ import java.nio.ByteBuffer; import org.eclipse.jgit.internal.storage.io.BlockSource; import org.eclipse.jgit.internal.storage.reftable.ReftableReader; -/** A reftable stored in {@link DfsBlockCache}. */ +/** + * A reftable stored in {@link org.eclipse.jgit.internal.storage.dfs.DfsBlockCache}. + */ public class DfsReftable extends BlockBasedFile { /** * Construct a reader for an existing reftable. @@ -83,7 +85,11 @@ public class DfsReftable extends BlockBasedFile { length = sz > 0 ? sz : -1; } - /** @return description that was originally used to configure this file. */ + /** + * Get description that was originally used to configure this file. + * + * @return description that was originally used to configure this file. + */ public DfsPackDescription getPackDescription() { return desc; } @@ -96,7 +102,7 @@ public class DfsReftable extends BlockBasedFile { * @param ctx * reader to access the DFS storage. * @return cursor to read the table; caller must close. - * @throws IOException + * @throws java.io.IOException * table cannot be opened. */ public ReftableReader open(DfsReader ctx) throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsReftableDatabase.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsReftableDatabase.java new file mode 100644 index 0000000000..9c844ebe06 --- /dev/null +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsReftableDatabase.java @@ -0,0 +1,390 @@ +/* + * Copyright (C) 2017, Google Inc. + * and other copyright owners as documented in the project's IP log. + * + * This program and the accompanying materials are made available + * under the terms of the Eclipse Distribution License v1.0 which + * accompanies this distribution, is reproduced below, and is + * available at http://www.eclipse.org/org/documents/edl-v10.php + * + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or + * without modification, are permitted provided that the following + * conditions are met: + * + * - Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * - Redistributions in binary form must reproduce the above + * copyright notice, this list of conditions and the following + * disclaimer in the documentation and/or other materials provided + * with the distribution. + * + * - Neither the name of the Eclipse Foundation, Inc. nor the + * names of its contributors may be used to endorse or promote + * products derived from this software without specific prior + * written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND + * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, + * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER + * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF + * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +package org.eclipse.jgit.internal.storage.dfs; + +import java.io.IOException; +import java.util.Arrays; +import java.util.Map; +import java.util.concurrent.locks.ReentrantLock; + +import org.eclipse.jgit.annotations.Nullable; +import org.eclipse.jgit.internal.storage.reftable.MergedReftable; +import org.eclipse.jgit.internal.storage.reftable.RefCursor; +import org.eclipse.jgit.internal.storage.reftable.Reftable; +import org.eclipse.jgit.internal.storage.reftable.ReftableConfig; +import org.eclipse.jgit.lib.BatchRefUpdate; +import org.eclipse.jgit.lib.NullProgressMonitor; +import org.eclipse.jgit.lib.ObjectId; +import org.eclipse.jgit.lib.Ref; +import org.eclipse.jgit.revwalk.RevWalk; +import org.eclipse.jgit.transport.ReceiveCommand; +import org.eclipse.jgit.util.RefList; +import org.eclipse.jgit.util.RefMap; + +/** + * A {@link org.eclipse.jgit.internal.storage.dfs.DfsRefDatabase} that uses + * reftable for storage. + * <p> + * A {@code DfsRefDatabase} instance is thread-safe. + * <p> + * Implementors may wish to use + * {@link org.eclipse.jgit.internal.storage.dfs.DfsPackDescription#getMaxUpdateIndex()} + * as the primary key identifier for a + * {@link org.eclipse.jgit.internal.storage.pack.PackExt#REFTABLE} only pack + * description, ensuring that when there are competing transactions one wins, + * and one will fail. + */ +public class DfsReftableDatabase extends DfsRefDatabase { + private final ReentrantLock lock = new ReentrantLock(true); + + private DfsReader ctx; + + private ReftableStack tableStack; + + private MergedReftable mergedTables; + + /** + * Initialize the reference database for a repository. + * + * @param repo + * the repository this database instance manages references for. + */ + protected DfsReftableDatabase(DfsRepository repo) { + super(repo); + } + + /** {@inheritDoc} */ + @Override + public boolean performsAtomicTransactions() { + return true; + } + + /** {@inheritDoc} */ + @Override + public BatchRefUpdate newBatchUpdate() { + DfsObjDatabase odb = getRepository().getObjectDatabase(); + return new ReftableBatchRefUpdate(this, odb); + } + + /** + * Get configuration to write new reftables with. + * + * @return configuration to write new reftables with. + */ + public ReftableConfig getReftableConfig() { + return new ReftableConfig(getRepository().getConfig()); + } + + /** + * Get the lock protecting this instance's state. + * + * @return the lock protecting this instance's state. + */ + protected ReentrantLock getLock() { + return lock; + } + + /** + * Whether to compact reftable instead of extending the stack depth. + * + * @return {@code true} if commit of a new small reftable should try to + * replace a prior small reftable by performing a compaction, + * instead of extending the stack depth. + */ + protected boolean compactDuringCommit() { + return true; + } + + /** + * Obtain a handle to the merged reader. + * + * @return (possibly cached) handle to the merged reader. + * @throws java.io.IOException + * if tables cannot be opened. + */ + protected Reftable reader() throws IOException { + lock.lock(); + try { + if (mergedTables == null) { + mergedTables = new MergedReftable(stack().readers()); + } + return mergedTables; + } finally { + lock.unlock(); + } + } + + /** + * Obtain a handle to the stack of reftables. + * + * @return (possibly cached) handle to the stack. + * @throws java.io.IOException + * if tables cannot be opened. + */ + protected ReftableStack stack() throws IOException { + lock.lock(); + try { + if (tableStack == null) { + DfsObjDatabase odb = getRepository().getObjectDatabase(); + if (ctx == null) { + ctx = odb.newReader(); + } + tableStack = ReftableStack.open(ctx, + Arrays.asList(odb.getReftables())); + } + return tableStack; + } finally { + lock.unlock(); + } + } + + /** {@inheritDoc} */ + @Override + public boolean isNameConflicting(String refName) throws IOException { + lock.lock(); + try { + Reftable table = reader(); + + // Cannot be nested within an existing reference. + int lastSlash = refName.lastIndexOf('/'); + while (0 < lastSlash) { + if (table.hasRef(refName.substring(0, lastSlash))) { + return true; + } + lastSlash = refName.lastIndexOf('/', lastSlash - 1); + } + + // Cannot be the container of an existing reference. + return table.hasRef(refName + '/'); + } finally { + lock.unlock(); + } + } + + /** {@inheritDoc} */ + @Override + public Ref exactRef(String name) throws IOException { + lock.lock(); + try { + Reftable table = reader(); + Ref ref = table.exactRef(name); + if (ref != null && ref.isSymbolic()) { + return table.resolve(ref); + } + return ref; + } finally { + lock.unlock(); + } + } + + /** {@inheritDoc} */ + @Override + public Ref getRef(String needle) throws IOException { + for (String prefix : SEARCH_PATH) { + Ref ref = exactRef(prefix + needle); + if (ref != null) { + return ref; + } + } + return null; + } + + /** {@inheritDoc} */ + @Override + public Map<String, Ref> getRefs(String prefix) throws IOException { + RefList.Builder<Ref> all = new RefList.Builder<>(); + lock.lock(); + try { + Reftable table = reader(); + try (RefCursor rc = ALL.equals(prefix) ? table.allRefs() + : table.seekRef(prefix)) { + while (rc.next()) { + Ref ref = table.resolve(rc.getRef()); + if (ref != null) { + all.add(ref); + } + } + } + } finally { + lock.unlock(); + } + + RefList<Ref> none = RefList.emptyList(); + return new RefMap(prefix, all.toRefList(), none, none); + } + + /** {@inheritDoc} */ + @Override + public Ref peel(Ref ref) throws IOException { + Ref oldLeaf = ref.getLeaf(); + if (oldLeaf.isPeeled() || oldLeaf.getObjectId() == null) { + return ref; + } + return recreate(ref, doPeel(oldLeaf)); + } + + @Override + boolean exists() throws IOException { + DfsObjDatabase odb = getRepository().getObjectDatabase(); + return odb.getReftables().length > 0; + } + + @Override + void clearCache() { + lock.lock(); + try { + if (tableStack != null) { + tableStack.close(); + tableStack = null; + } + if (ctx != null) { + ctx.close(); + ctx = null; + } + mergedTables = null; + } finally { + lock.unlock(); + } + } + + /** {@inheritDoc} */ + @Override + protected boolean compareAndPut(Ref oldRef, @Nullable Ref newRef) + throws IOException { + ReceiveCommand cmd = toCommand(oldRef, newRef); + try (RevWalk rw = new RevWalk(getRepository())) { + newBatchUpdate().setAllowNonFastForwards(true).addCommand(cmd) + .execute(rw, NullProgressMonitor.INSTANCE); + } + switch (cmd.getResult()) { + case OK: + return true; + case REJECTED_OTHER_REASON: + throw new IOException(cmd.getMessage()); + case LOCK_FAILURE: + default: + return false; + } + } + + private static ReceiveCommand toCommand(Ref oldRef, Ref newRef) { + ObjectId oldId = toId(oldRef); + ObjectId newId = toId(newRef); + String name = toName(oldRef, newRef); + + if (oldRef != null && oldRef.isSymbolic()) { + if (newRef != null) { + if (newRef.isSymbolic()) { + return ReceiveCommand.link(oldRef.getTarget().getName(), + newRef.getTarget().getName(), name); + } else { + return ReceiveCommand.unlink(oldRef.getTarget().getName(), + newId, name); + } + } else { + return ReceiveCommand.unlink(oldRef.getTarget().getName(), + ObjectId.zeroId(), name); + } + } + + if (newRef != null && newRef.isSymbolic()) { + if (oldRef != null) { + if (oldRef.isSymbolic()) { + return ReceiveCommand.link(oldRef.getTarget().getName(), + newRef.getTarget().getName(), name); + } else { + return ReceiveCommand.link(oldId, + newRef.getTarget().getName(), name); + } + } else { + return ReceiveCommand.link(ObjectId.zeroId(), + newRef.getTarget().getName(), name); + } + } + + return new ReceiveCommand(oldId, newId, name); + } + + private static ObjectId toId(Ref ref) { + if (ref != null) { + ObjectId id = ref.getObjectId(); + if (id != null) { + return id; + } + } + return ObjectId.zeroId(); + } + + private static String toName(Ref oldRef, Ref newRef) { + return oldRef != null ? oldRef.getName() : newRef.getName(); + } + + /** {@inheritDoc} */ + @Override + protected boolean compareAndRemove(Ref oldRef) throws IOException { + return compareAndPut(oldRef, null); + } + + /** {@inheritDoc} */ + @Override + protected RefCache scanAllRefs() throws IOException { + throw new UnsupportedOperationException(); + } + + @Override + void stored(Ref ref) { + // Unnecessary; ReftableBatchRefUpdate calls clearCache(). + } + + @Override + void removed(String refName) { + // Unnecessary; ReftableBatchRefUpdate calls clearCache(). + } + + /** {@inheritDoc} */ + @Override + protected void cachePeeledState(Ref oldLeaf, Ref newLeaf) { + // Do not cache peeled state in reftable. + } +} diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRepository.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRepository.java index a5dd514709..197681658e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRepository.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRepository.java @@ -58,7 +58,9 @@ import org.eclipse.jgit.lib.ReflogReader; import org.eclipse.jgit.lib.Repository; import org.eclipse.jgit.lib.StoredConfig; -/** A Git repository on a DFS. */ +/** + * A Git repository on a DFS. + */ public abstract class DfsRepository extends Repository { private final DfsConfig config; @@ -76,10 +78,15 @@ public abstract class DfsRepository extends Repository { this.description = builder.getRepositoryDescription(); } + /** {@inheritDoc} */ @Override public abstract DfsObjDatabase getObjectDatabase(); - /** @return a description of this repository. */ + /** + * Get the description of this repository. + * + * @return the description of this repository. + */ public DfsRepositoryDescription getDescription() { return description; } @@ -88,7 +95,7 @@ public abstract class DfsRepository extends Repository { * Check if the repository already exists. * * @return true if the repository exists; false if it is new. - * @throws IOException + * @throws java.io.IOException * the repository cannot be checked. */ public boolean exists() throws IOException { @@ -98,6 +105,7 @@ public abstract class DfsRepository extends Repository { return true; } + /** {@inheritDoc} */ @Override public void create(boolean bare) throws IOException { if (exists()) @@ -110,28 +118,33 @@ public abstract class DfsRepository extends Repository { throw new IOException(result.name()); } + /** {@inheritDoc} */ @Override public StoredConfig getConfig() { return config; } + /** {@inheritDoc} */ @Override public void scanForRepoChanges() throws IOException { getRefDatabase().refresh(); getObjectDatabase().clearCache(); } + /** {@inheritDoc} */ @Override public void notifyIndexChanged() { // Do not send notifications. // There is no index, as there is no working tree. } + /** {@inheritDoc} */ @Override public ReflogReader getReflogReader(String refName) throws IOException { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public AttributesNodeProvider createAttributesNodeProvider() { // TODO Check if the implementation used in FileRepository can be used diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRepositoryBuilder.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRepositoryBuilder.java index 77e060a564..2b67fd9e26 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRepositoryBuilder.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRepositoryBuilder.java @@ -50,7 +50,7 @@ import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.lib.BaseRepositoryBuilder; /** - * Constructs a {@link DfsRepository}. + * Constructs a {@link org.eclipse.jgit.internal.storage.dfs.DfsRepository}. * * @param <B> * type of the builder class. @@ -63,7 +63,11 @@ public abstract class DfsRepositoryBuilder<B extends DfsRepositoryBuilder, R ext private DfsRepositoryDescription repoDesc; - /** @return options used by readers accessing the repository. */ + /** + * Get options used by readers accessing the repository. + * + * @return options used by readers accessing the repository. + */ public DfsReaderOptions getReaderOptions() { return readerOptions; } @@ -80,7 +84,11 @@ public abstract class DfsRepositoryBuilder<B extends DfsRepositoryBuilder, R ext return self(); } - /** @return a description of the repository. */ + /** + * Get the description of the repository. + * + * @return the description of the repository. + */ public DfsRepositoryDescription getRepositoryDescription() { return repoDesc; } @@ -97,6 +105,7 @@ public abstract class DfsRepositoryBuilder<B extends DfsRepositoryBuilder, R ext return self(); } + /** {@inheritDoc} */ @Override public B setup() throws IllegalArgumentException, IOException { super.setup(); @@ -108,24 +117,20 @@ public abstract class DfsRepositoryBuilder<B extends DfsRepositoryBuilder, R ext } /** + * {@inheritDoc} + * <p> * Create a repository matching the configuration in this builder. * <p> * If an option was not set, the build method will try to default the option * based on other options. If insufficient information is available, an * exception is thrown to the caller. - * - * @return a repository matching this configuration. - * @throws IllegalArgumentException - * insufficient parameters were set. - * @throws IOException - * the repository could not be accessed to configure the rest of - * the builder's parameters. */ @Override public abstract R build() throws IOException; // We don't support local file IO and thus shouldn't permit these to set. + /** {@inheritDoc} */ @Override public B setGitDir(File gitDir) { if (gitDir != null) @@ -133,6 +138,7 @@ public abstract class DfsRepositoryBuilder<B extends DfsRepositoryBuilder, R ext return self(); } + /** {@inheritDoc} */ @Override public B setObjectDirectory(File objectDirectory) { if (objectDirectory != null) @@ -140,12 +146,14 @@ public abstract class DfsRepositoryBuilder<B extends DfsRepositoryBuilder, R ext return self(); } + /** {@inheritDoc} */ @Override public B addAlternateObjectDirectory(File other) { throw new UnsupportedOperationException( JGitText.get().unsupportedAlternates); } + /** {@inheritDoc} */ @Override public B setWorkTree(File workTree) { if (workTree != null) @@ -153,6 +161,7 @@ public abstract class DfsRepositoryBuilder<B extends DfsRepositoryBuilder, R ext return self(); } + /** {@inheritDoc} */ @Override public B setIndexFile(File indexFile) { if (indexFile != null) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRepositoryDescription.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRepositoryDescription.java index 8afad0eea0..5e6c7e103d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRepositoryDescription.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsRepositoryDescription.java @@ -43,11 +43,15 @@ package org.eclipse.jgit.internal.storage.dfs; -/** A description of a Git repository on a DFS. */ +/** + * A description of a Git repository on a DFS. + */ public class DfsRepositoryDescription { private final String repositoryName; - /** Initialize a new, empty repository description. */ + /** + * Initialize a new, empty repository description. + */ public DfsRepositoryDescription() { this(null); } @@ -62,11 +66,16 @@ public class DfsRepositoryDescription { this.repositoryName = repositoryName; } - /** @return the name of the repository. */ + /** + * Get the name of the repository. + * + * @return the name of the repository. + */ public String getRepositoryName() { return repositoryName; } + /** {@inheritDoc} */ @Override public int hashCode() { if (getRepositoryName() != null) @@ -74,6 +83,7 @@ public class DfsRepositoryDescription { return System.identityHashCode(this); } + /** {@inheritDoc} */ @Override public boolean equals(Object b) { if (b instanceof DfsRepositoryDescription){ @@ -84,6 +94,7 @@ public class DfsRepositoryDescription { return false; } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsStreamKey.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsStreamKey.java index 54a74899ea..8793d83126 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsStreamKey.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsStreamKey.java @@ -47,39 +47,59 @@ import static java.nio.charset.StandardCharsets.UTF_8; import java.util.Arrays; -/** Key used by {@link DfsBlockCache} to disambiguate streams. */ +import org.eclipse.jgit.annotations.Nullable; +import org.eclipse.jgit.internal.storage.pack.PackExt; + +/** + * Key used by {@link org.eclipse.jgit.internal.storage.dfs.DfsBlockCache} to disambiguate streams. + */ public abstract class DfsStreamKey { /** + * Create a {@code DfsStreamKey} + * * @param repo * description of the containing repository. * @param name * compute the key from a string name. + * @param ext + * pack file extension, or {@code null}. * @return key for {@code name} */ - public static DfsStreamKey of(DfsRepositoryDescription repo, String name) { - return new ByteArrayDfsStreamKey(repo, name.getBytes(UTF_8)); + public static DfsStreamKey of(DfsRepositoryDescription repo, String name, + @Nullable PackExt ext) { + return new ByteArrayDfsStreamKey(repo, name.getBytes(UTF_8), ext); } final int hash; + final int packExtPos; + /** + * Constructor for DfsStreamKey. + * * @param hash * hash of the other identifying components of the key. + * @param ext + * pack file extension, or {@code null}. */ - protected DfsStreamKey(int hash) { + protected DfsStreamKey(int hash, @Nullable PackExt ext) { // Multiply by 31 here so we can more directly combine with another // value without doing the multiply there. this.hash = hash * 31; + this.packExtPos = ext == null ? 0 : ext.getPosition(); } + /** {@inheritDoc} */ @Override public int hashCode() { return hash; } + /** {@inheritDoc} */ @Override public abstract boolean equals(Object o); + /** {@inheritDoc} */ @SuppressWarnings("boxing") @Override public String toString() { @@ -88,10 +108,12 @@ public abstract class DfsStreamKey { private static final class ByteArrayDfsStreamKey extends DfsStreamKey { private final DfsRepositoryDescription repo; + private final byte[] name; - ByteArrayDfsStreamKey(DfsRepositoryDescription repo, byte[] name) { - super(repo.hashCode() * 31 + Arrays.hashCode(name)); + ByteArrayDfsStreamKey(DfsRepositoryDescription repo, byte[] name, + @Nullable PackExt ext) { + super(repo.hashCode() * 31 + Arrays.hashCode(name), ext); this.repo = repo; this.name = name; } @@ -100,8 +122,7 @@ public abstract class DfsStreamKey { public boolean equals(Object o) { if (o instanceof ByteArrayDfsStreamKey) { ByteArrayDfsStreamKey k = (ByteArrayDfsStreamKey) o; - return hash == k.hash - && repo.equals(k.repo) + return hash == k.hash && repo.equals(k.repo) && Arrays.equals(name, k.name); } return false; @@ -112,7 +133,7 @@ public abstract class DfsStreamKey { private final DfsStreamKey idxKey; ForReverseIndex(DfsStreamKey idxKey) { - super(idxKey.hash + 1); + super(idxKey.hash + 1, null); this.idxKey = idxKey; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsText.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsText.java index dedcab04d8..9327bd10ac 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsText.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/DfsText.java @@ -46,9 +46,15 @@ package org.eclipse.jgit.internal.storage.dfs; import org.eclipse.jgit.nls.NLS; import org.eclipse.jgit.nls.TranslationBundle; -/** Translation bundle for the DFS storage implementation. */ +/** + * Translation bundle for the DFS storage implementation. + */ public class DfsText extends TranslationBundle { - /** @return instance of this translation bundle */ + /** + * Get an instance of this translation bundle. + * + * @return instance of this translation bundle. + */ public static DfsText get() { return NLS.getBundleFor(DfsText.class); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/InMemoryRepository.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/InMemoryRepository.java index 1e31878b39..662c3fef81 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/InMemoryRepository.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/InMemoryRepository.java @@ -6,30 +6,13 @@ import java.io.IOException; import java.nio.ByteBuffer; import java.util.ArrayList; import java.util.Collection; -import java.util.HashMap; import java.util.List; -import java.util.Map; -import java.util.Objects; -import java.util.concurrent.ConcurrentHashMap; -import java.util.concurrent.ConcurrentMap; import java.util.concurrent.atomic.AtomicInteger; -import java.util.concurrent.locks.ReadWriteLock; -import java.util.concurrent.locks.ReentrantReadWriteLock; import org.eclipse.jgit.annotations.Nullable; import org.eclipse.jgit.internal.storage.pack.PackExt; -import org.eclipse.jgit.lib.BatchRefUpdate; -import org.eclipse.jgit.lib.ObjectId; -import org.eclipse.jgit.lib.ObjectIdRef; -import org.eclipse.jgit.lib.ProgressMonitor; -import org.eclipse.jgit.lib.Ref; -import org.eclipse.jgit.lib.Ref.Storage; +import org.eclipse.jgit.internal.storage.reftable.ReftableConfig; import org.eclipse.jgit.lib.RefDatabase; -import org.eclipse.jgit.revwalk.RevObject; -import org.eclipse.jgit.revwalk.RevTag; -import org.eclipse.jgit.revwalk.RevWalk; -import org.eclipse.jgit.transport.ReceiveCommand; -import org.eclipse.jgit.util.RefList; /** * Git repository stored entirely in the local process memory. @@ -54,9 +37,8 @@ public class InMemoryRepository extends DfsRepository { static final AtomicInteger packId = new AtomicInteger(); private final MemObjDatabase objdb; - private final RefDatabase refdb; + private final MemRefDatabase refdb; private String gitwebDescription; - private boolean performsAtomicTransactions = true; /** * Initialize a new in-memory repository. @@ -74,11 +56,13 @@ public class InMemoryRepository extends DfsRepository { refdb = new MemRefDatabase(); } + /** {@inheritDoc} */ @Override public MemObjDatabase getObjectDatabase() { return objdb; } + /** {@inheritDoc} */ @Override public RefDatabase getRefDatabase() { return refdb; @@ -90,17 +74,20 @@ public class InMemoryRepository extends DfsRepository { * Useful for testing atomic support enabled or disabled. * * @param atomic + * whether to use atomic reference transaction support */ public void setPerformsAtomicTransactions(boolean atomic) { - performsAtomicTransactions = atomic; + refdb.performsAtomicTransactions = atomic; } + /** {@inheritDoc} */ @Override @Nullable public String getGitwebDescription() { return gitwebDescription; } + /** {@inheritDoc} */ @Override public void setGitwebDescription(@Nullable String d) { gitwebDescription = d; @@ -148,6 +135,7 @@ public class InMemoryRepository extends DfsRepository { if (replace != null) n.removeAll(replace); packs = n; + clearCache(); } @Override @@ -159,37 +147,43 @@ public class InMemoryRepository extends DfsRepository { protected ReadableChannel openFile(DfsPackDescription desc, PackExt ext) throws FileNotFoundException, IOException { MemPack memPack = (MemPack) desc; - byte[] file = memPack.fileMap.get(ext); + byte[] file = memPack.get(ext); if (file == null) throw new FileNotFoundException(desc.getFileName(ext)); return new ByteArrayReadableChannel(file, blockSize); } @Override - protected DfsOutputStream writeFile( - DfsPackDescription desc, final PackExt ext) throws IOException { - final MemPack memPack = (MemPack) desc; + protected DfsOutputStream writeFile(DfsPackDescription desc, + PackExt ext) throws IOException { + MemPack memPack = (MemPack) desc; return new Out() { @Override public void flush() { - memPack.fileMap.put(ext, getData()); + memPack.put(ext, getData()); } }; } } private static class MemPack extends DfsPackDescription { - final Map<PackExt, byte[]> - fileMap = new HashMap<>(); + final byte[][] fileMap = new byte[PackExt.values().length][]; MemPack(String name, DfsRepositoryDescription repoDesc) { super(repoDesc, name); } + + void put(PackExt ext, byte[] data) { + fileMap[ext.getPosition()] = data; + } + + byte[] get(PackExt ext) { + return fileMap[ext.getPosition()]; + } } private abstract static class Out extends DfsOutputStream { private final ByteArrayOutputStream dst = new ByteArrayOutputStream(); - private byte[] data; @Override @@ -221,7 +215,6 @@ public class InMemoryRepository extends DfsRepository { public void close() { flush(); } - } private static class ByteArrayReadableChannel implements ReadableChannel { @@ -281,193 +274,27 @@ public class InMemoryRepository extends DfsRepository { } } - /** - * A ref database storing all refs in-memory. - * <p> - * This class is protected (and not private) to facilitate testing using - * subclasses of InMemoryRepository. - */ - protected class MemRefDatabase extends DfsRefDatabase { - private final ConcurrentMap<String, Ref> refs = new ConcurrentHashMap<>(); - private final ReadWriteLock lock = new ReentrantReadWriteLock(true /* fair */); + /** DfsRefDatabase used by InMemoryRepository. */ + protected class MemRefDatabase extends DfsReftableDatabase { + boolean performsAtomicTransactions = true; - /** - * Initialize a new in-memory ref database. - */ + /** Initialize a new in-memory ref database. */ protected MemRefDatabase() { super(InMemoryRepository.this); } @Override - public boolean performsAtomicTransactions() { - return performsAtomicTransactions; - } - - @Override - public BatchRefUpdate newBatchUpdate() { - return new BatchRefUpdate(this) { - @Override - public void execute(RevWalk walk, ProgressMonitor monitor) - throws IOException { - if (performsAtomicTransactions() && isAtomic()) { - try { - lock.writeLock().lock(); - batch(getCommands()); - } finally { - lock.writeLock().unlock(); - } - } else { - super.execute(walk, monitor); - } - } - }; - } - - @Override - protected RefCache scanAllRefs() throws IOException { - RefList.Builder<Ref> ids = new RefList.Builder<>(); - RefList.Builder<Ref> sym = new RefList.Builder<>(); - try { - lock.readLock().lock(); - for (Ref ref : refs.values()) { - if (ref.isSymbolic()) - sym.add(ref); - ids.add(ref); - } - } finally { - lock.readLock().unlock(); - } - ids.sort(); - sym.sort(); - objdb.getCurrentPackList().markDirty(); - return new RefCache(ids.toRefList(), sym.toRefList()); - } - - private void batch(List<ReceiveCommand> cmds) { - // Validate that the target exists in a new RevWalk, as the RevWalk - // from the RefUpdate might be reading back unflushed objects. - Map<ObjectId, ObjectId> peeled = new HashMap<>(); - try (RevWalk rw = new RevWalk(getRepository())) { - for (ReceiveCommand c : cmds) { - if (c.getResult() != ReceiveCommand.Result.NOT_ATTEMPTED) { - ReceiveCommand.abort(cmds); - return; - } - - if (!ObjectId.zeroId().equals(c.getNewId())) { - try { - RevObject o = rw.parseAny(c.getNewId()); - if (o instanceof RevTag) { - peeled.put(o, rw.peel(o).copy()); - } - } catch (IOException e) { - c.setResult(ReceiveCommand.Result.REJECTED_MISSING_OBJECT); - ReceiveCommand.abort(cmds); - return; - } - } - } - } - - // Check all references conform to expected old value. - for (ReceiveCommand c : cmds) { - Ref r = refs.get(c.getRefName()); - if (r == null) { - if (c.getType() != ReceiveCommand.Type.CREATE) { - c.setResult(ReceiveCommand.Result.LOCK_FAILURE); - ReceiveCommand.abort(cmds); - return; - } - } else { - ObjectId objectId = r.getObjectId(); - if (r.isSymbolic() || objectId == null - || !objectId.equals(c.getOldId())) { - c.setResult(ReceiveCommand.Result.LOCK_FAILURE); - ReceiveCommand.abort(cmds); - return; - } - } - } - - // Write references. - for (ReceiveCommand c : cmds) { - if (c.getType() == ReceiveCommand.Type.DELETE) { - refs.remove(c.getRefName()); - c.setResult(ReceiveCommand.Result.OK); - continue; - } - - ObjectId p = peeled.get(c.getNewId()); - Ref r; - if (p != null) { - r = new ObjectIdRef.PeeledTag(Storage.PACKED, - c.getRefName(), c.getNewId(), p); - } else { - r = new ObjectIdRef.PeeledNonTag(Storage.PACKED, - c.getRefName(), c.getNewId()); - } - refs.put(r.getName(), r); - c.setResult(ReceiveCommand.Result.OK); - } - clearCache(); - } - - @Override - protected boolean compareAndPut(Ref oldRef, Ref newRef) - throws IOException { - try { - lock.writeLock().lock(); - ObjectId id = newRef.getObjectId(); - if (id != null) { - try (RevWalk rw = new RevWalk(getRepository())) { - // Validate that the target exists in a new RevWalk, as the RevWalk - // from the RefUpdate might be reading back unflushed objects. - rw.parseAny(id); - } - } - String name = newRef.getName(); - if (oldRef == null) - return refs.putIfAbsent(name, newRef) == null; - - Ref cur = refs.get(name); - if (cur != null) { - if (eq(cur, oldRef)) - return refs.replace(name, cur, newRef); - } - - if (oldRef.getStorage() == Storage.NEW) - return refs.putIfAbsent(name, newRef) == null; - - return false; - } finally { - lock.writeLock().unlock(); - } + public ReftableConfig getReftableConfig() { + ReftableConfig cfg = new ReftableConfig(); + cfg.setAlignBlocks(false); + cfg.setIndexObjects(false); + cfg.fromConfig(getRepository().getConfig()); + return cfg; } @Override - protected boolean compareAndRemove(Ref oldRef) throws IOException { - try { - lock.writeLock().lock(); - String name = oldRef.getName(); - Ref cur = refs.get(name); - if (cur != null && eq(cur, oldRef)) - return refs.remove(name, cur); - else - return false; - } finally { - lock.writeLock().unlock(); - } - } - - private boolean eq(Ref a, Ref b) { - if (!Objects.equals(a.getName(), b.getName())) - return false; - if (a.isSymbolic() != b.isSymbolic()) - return false; - if (a.isSymbolic()) - return Objects.equals(a.getTarget().getName(), b.getTarget().getName()); - else - return Objects.equals(a.getObjectId(), b.getObjectId()); + public boolean performsAtomicTransactions() { + return performsAtomicTransactions; } } } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/LargePackedWholeObject.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/LargePackedWholeObject.java index 73a93e6575..fa2c5291c6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/LargePackedWholeObject.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/LargePackedWholeObject.java @@ -77,26 +77,31 @@ final class LargePackedWholeObject extends ObjectLoader { this.db = db; } + /** {@inheritDoc} */ @Override public int getType() { return type; } + /** {@inheritDoc} */ @Override public long getSize() { return size; } + /** {@inheritDoc} */ @Override public boolean isLarge() { return true; } + /** {@inheritDoc} */ @Override public byte[] getCachedBytes() throws LargeObjectException { throw new LargeObjectException(); } + /** {@inheritDoc} */ @Override public ObjectStream openStream() throws MissingObjectException, IOException { DfsReader ctx = db.newReader(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/PackInputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/PackInputStream.java index bb8445bcd2..d88011c3ae 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/PackInputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/PackInputStream.java @@ -64,6 +64,7 @@ final class PackInputStream extends InputStream { ctx.pin(pack, pos); } + /** {@inheritDoc} */ @Override public int read(byte[] b, int off, int len) throws IOException { int n = ctx.copy(pack, pos, b, off, len); @@ -71,6 +72,7 @@ final class PackInputStream extends InputStream { return n; } + /** {@inheritDoc} */ @Override public int read() throws IOException { byte[] buf = new byte[1]; @@ -78,6 +80,7 @@ final class PackInputStream extends InputStream { return n == 1 ? buf[0] & 0xff : -1; } + /** {@inheritDoc} */ @Override public void close() { ctx.close(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/ReadableChannel.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/ReadableChannel.java index 240d552aad..9b98250884 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/ReadableChannel.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/ReadableChannel.java @@ -46,13 +46,15 @@ package org.eclipse.jgit.internal.storage.dfs; import java.io.IOException; import java.nio.channels.ReadableByteChannel; -/** Readable random access byte channel from a file. */ +/** + * Readable random access byte channel from a file. + */ public interface ReadableChannel extends ReadableByteChannel { /** * Get the current position of the channel. * * @return r current offset. - * @throws IOException + * @throws java.io.IOException * the channel's current position cannot be obtained. */ public long position() throws IOException; @@ -63,7 +65,7 @@ public interface ReadableChannel extends ReadableByteChannel { * @param newPosition * position to move the channel to. The next read will start from * here. This should be a multiple of the {@link #blockSize()}. - * @throws IOException + * @throws java.io.IOException * the position cannot be updated. This may be because the * channel only supports block aligned IO and the current * position is not block aligned. @@ -78,7 +80,7 @@ public interface ReadableChannel extends ReadableByteChannel { * read has been completed, the underlying file size should be available. * * @return r total size of the channel; -1 if not yet available. - * @throws IOException + * @throws java.io.IOException * the size cannot be determined. */ public long size() throws IOException; @@ -92,9 +94,10 @@ public interface ReadableChannel extends ReadableByteChannel { * <p> * Channels should not recommend large block sizes. Sizes up to 1-4 MiB may * be reasonable, but sizes above that may be horribly inefficient. The - * {@link DfsBlockCache} favors the alignment suggested by the channel - * rather than the configured size under the assumption that reads are very - * expensive and the channel knows what size is best to access it with. + * {@link org.eclipse.jgit.internal.storage.dfs.DfsBlockCache} favors the + * alignment suggested by the channel rather than the configured size under + * the assumption that reads are very expensive and the channel knows what + * size is best to access it with. * * @return recommended alignment size for randomly positioned reads. Does * not need to be a power of 2. @@ -125,7 +128,7 @@ public interface ReadableChannel extends ReadableByteChannel { * * @param bufferSize * requested size of the read ahead buffer, in bytes. - * @throws IOException + * @throws java.io.IOException * if the read ahead cannot be adjusted. */ public void setReadAheadBytes(int bufferSize) throws IOException; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/ReftableBatchRefUpdate.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/ReftableBatchRefUpdate.java new file mode 100644 index 0000000000..e0c056a450 --- /dev/null +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/ReftableBatchRefUpdate.java @@ -0,0 +1,465 @@ +/* + * Copyright (C) 2017, Google Inc. + * and other copyright owners as documented in the project's IP log. + * + * This program and the accompanying materials are made available + * under the terms of the Eclipse Distribution License v1.0 which + * accompanies this distribution, is reproduced below, and is + * available at http://www.eclipse.org/org/documents/edl-v10.php + * + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or + * without modification, are permitted provided that the following + * conditions are met: + * + * - Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * - Redistributions in binary form must reproduce the above + * copyright notice, this list of conditions and the following + * disclaimer in the documentation and/or other materials provided + * with the distribution. + * + * - Neither the name of the Eclipse Foundation, Inc. nor the + * names of its contributors may be used to endorse or promote + * products derived from this software without specific prior + * written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND + * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, + * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER + * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF + * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +package org.eclipse.jgit.internal.storage.dfs; + +import static org.eclipse.jgit.internal.storage.pack.PackExt.REFTABLE; +import static org.eclipse.jgit.lib.Ref.Storage.NEW; +import static org.eclipse.jgit.lib.Ref.Storage.PACKED; +import static org.eclipse.jgit.transport.ReceiveCommand.Result.LOCK_FAILURE; +import static org.eclipse.jgit.transport.ReceiveCommand.Result.NOT_ATTEMPTED; +import static org.eclipse.jgit.transport.ReceiveCommand.Result.OK; +import static org.eclipse.jgit.transport.ReceiveCommand.Result.REJECTED_MISSING_OBJECT; +import static org.eclipse.jgit.transport.ReceiveCommand.Result.REJECTED_NONFASTFORWARD; +import static org.eclipse.jgit.transport.ReceiveCommand.Type.UPDATE_NONFASTFORWARD; + +import java.io.ByteArrayOutputStream; +import java.io.IOException; +import java.io.OutputStream; +import java.util.ArrayList; +import java.util.Collections; +import java.util.HashMap; +import java.util.HashSet; +import java.util.List; +import java.util.Map; +import java.util.Set; +import java.util.concurrent.locks.ReentrantLock; + +import org.eclipse.jgit.annotations.Nullable; +import org.eclipse.jgit.errors.MissingObjectException; +import org.eclipse.jgit.internal.storage.dfs.DfsObjDatabase.PackSource; +import org.eclipse.jgit.internal.storage.io.BlockSource; +import org.eclipse.jgit.internal.storage.pack.PackExt; +import org.eclipse.jgit.internal.storage.reftable.RefCursor; +import org.eclipse.jgit.internal.storage.reftable.Reftable; +import org.eclipse.jgit.internal.storage.reftable.ReftableCompactor; +import org.eclipse.jgit.internal.storage.reftable.ReftableConfig; +import org.eclipse.jgit.internal.storage.reftable.ReftableReader; +import org.eclipse.jgit.internal.storage.reftable.ReftableWriter; +import org.eclipse.jgit.lib.AnyObjectId; +import org.eclipse.jgit.lib.BatchRefUpdate; +import org.eclipse.jgit.lib.ObjectId; +import org.eclipse.jgit.lib.ObjectIdRef; +import org.eclipse.jgit.lib.PersonIdent; +import org.eclipse.jgit.lib.ProgressMonitor; +import org.eclipse.jgit.lib.Ref; +import org.eclipse.jgit.lib.ReflogEntry; +import org.eclipse.jgit.lib.SymbolicRef; +import org.eclipse.jgit.revwalk.RevObject; +import org.eclipse.jgit.revwalk.RevTag; +import org.eclipse.jgit.revwalk.RevWalk; +import org.eclipse.jgit.transport.ReceiveCommand; + +/** + * {@link org.eclipse.jgit.lib.BatchRefUpdate} for + * {@link org.eclipse.jgit.internal.storage.dfs.DfsReftableDatabase}. + */ +public class ReftableBatchRefUpdate extends BatchRefUpdate { + private static final int AVG_BYTES = 36; + + private final DfsReftableDatabase refdb; + + private final DfsObjDatabase odb; + + private final ReentrantLock lock; + + private final ReftableConfig reftableConfig; + + /** + * Initialize batch update. + * + * @param refdb + * database the update will modify. + * @param odb + * object database to store the reftable. + */ + protected ReftableBatchRefUpdate(DfsReftableDatabase refdb, + DfsObjDatabase odb) { + super(refdb); + this.refdb = refdb; + this.odb = odb; + lock = refdb.getLock(); + reftableConfig = refdb.getReftableConfig(); + } + + /** {@inheritDoc} */ + @Override + public void execute(RevWalk rw, ProgressMonitor pm, List<String> options) { + List<ReceiveCommand> pending = getPending(); + if (pending.isEmpty()) { + return; + } + if (options != null) { + setPushOptions(options); + } + try { + if (!checkObjectExistence(rw, pending)) { + return; + } + if (!checkNonFastForwards(rw, pending)) { + return; + } + + lock.lock(); + try { + Reftable table = refdb.reader(); + if (!checkExpected(table, pending)) { + return; + } + if (!checkConflicting(pending)) { + return; + } + if (!blockUntilTimestamps(MAX_WAIT)) { + return; + } + applyUpdates(rw, pending); + for (ReceiveCommand cmd : pending) { + cmd.setResult(OK); + } + } finally { + lock.unlock(); + } + } catch (IOException e) { + pending.get(0).setResult(LOCK_FAILURE, "io error"); //$NON-NLS-1$ + ReceiveCommand.abort(pending); + } + } + + private List<ReceiveCommand> getPending() { + return ReceiveCommand.filter(getCommands(), NOT_ATTEMPTED); + } + + private boolean checkObjectExistence(RevWalk rw, + List<ReceiveCommand> pending) throws IOException { + for (ReceiveCommand cmd : pending) { + try { + if (!cmd.getNewId().equals(ObjectId.zeroId())) { + rw.parseAny(cmd.getNewId()); + } + } catch (MissingObjectException e) { + // ReceiveCommand#setResult(Result) converts REJECTED to + // REJECTED_NONFASTFORWARD, even though that result is also + // used for a missing object. Eagerly handle this case so we + // can set the right result. + cmd.setResult(REJECTED_MISSING_OBJECT); + ReceiveCommand.abort(pending); + return false; + } + } + return true; + } + + private boolean checkNonFastForwards(RevWalk rw, + List<ReceiveCommand> pending) throws IOException { + if (isAllowNonFastForwards()) { + return true; + } + for (ReceiveCommand cmd : pending) { + cmd.updateType(rw); + if (cmd.getType() == UPDATE_NONFASTFORWARD) { + cmd.setResult(REJECTED_NONFASTFORWARD); + ReceiveCommand.abort(pending); + return false; + } + } + return true; + } + + private boolean checkConflicting(List<ReceiveCommand> pending) + throws IOException { + Set<String> names = new HashSet<>(); + for (ReceiveCommand cmd : pending) { + names.add(cmd.getRefName()); + } + + boolean ok = true; + for (ReceiveCommand cmd : pending) { + String name = cmd.getRefName(); + if (refdb.isNameConflicting(name)) { + cmd.setResult(LOCK_FAILURE); + ok = false; + } else { + int s = name.lastIndexOf('/'); + while (0 < s) { + if (names.contains(name.substring(0, s))) { + cmd.setResult(LOCK_FAILURE); + ok = false; + break; + } + s = name.lastIndexOf('/', s - 1); + } + } + } + if (!ok && isAtomic()) { + ReceiveCommand.abort(pending); + return false; + } + return ok; + } + + private boolean checkExpected(Reftable table, List<ReceiveCommand> pending) + throws IOException { + for (ReceiveCommand cmd : pending) { + Ref ref; + try (RefCursor rc = table.seekRef(cmd.getRefName())) { + ref = rc.next() ? rc.getRef() : null; + } + if (!matchOld(cmd, ref)) { + cmd.setResult(LOCK_FAILURE); + if (isAtomic()) { + ReceiveCommand.abort(pending); + return false; + } + } + } + return true; + } + + private static boolean matchOld(ReceiveCommand cmd, @Nullable Ref ref) { + if (ref == null) { + return AnyObjectId.equals(ObjectId.zeroId(), cmd.getOldId()) + && cmd.getOldSymref() == null; + } else if (ref.isSymbolic()) { + return ref.getTarget().getName().equals(cmd.getOldSymref()); + } + ObjectId id = ref.getObjectId(); + if (id == null) { + id = ObjectId.zeroId(); + } + return cmd.getOldId().equals(id); + } + + private void applyUpdates(RevWalk rw, List<ReceiveCommand> pending) + throws IOException { + List<Ref> newRefs = toNewRefs(rw, pending); + long updateIndex = nextUpdateIndex(); + Set<DfsPackDescription> prune = Collections.emptySet(); + DfsPackDescription pack = odb.newPack(PackSource.INSERT); + try (DfsOutputStream out = odb.writeFile(pack, REFTABLE)) { + ReftableConfig cfg = DfsPackCompactor + .configureReftable(reftableConfig, out); + + ReftableWriter.Stats stats; + if (refdb.compactDuringCommit() + && newRefs.size() * AVG_BYTES <= cfg.getRefBlockSize() + && canCompactTopOfStack(cfg)) { + ByteArrayOutputStream tmp = new ByteArrayOutputStream(); + write(tmp, cfg, updateIndex, newRefs, pending); + stats = compactTopOfStack(out, cfg, tmp.toByteArray()); + prune = toPruneTopOfStack(); + } else { + stats = write(out, cfg, updateIndex, newRefs, pending); + } + pack.addFileExt(REFTABLE); + pack.setReftableStats(stats); + } + + odb.commitPack(Collections.singleton(pack), prune); + odb.addReftable(pack, prune); + refdb.clearCache(); + } + + private ReftableWriter.Stats write(OutputStream os, ReftableConfig cfg, + long updateIndex, List<Ref> newRefs, List<ReceiveCommand> pending) + throws IOException { + ReftableWriter writer = new ReftableWriter(cfg) + .setMinUpdateIndex(updateIndex).setMaxUpdateIndex(updateIndex) + .begin(os).sortAndWriteRefs(newRefs); + if (!isRefLogDisabled()) { + writeLog(writer, updateIndex, pending); + } + writer.finish(); + return writer.getStats(); + } + + private void writeLog(ReftableWriter writer, long updateIndex, + List<ReceiveCommand> pending) throws IOException { + Map<String, ReceiveCommand> cmds = new HashMap<>(); + List<String> byName = new ArrayList<>(pending.size()); + for (ReceiveCommand cmd : pending) { + cmds.put(cmd.getRefName(), cmd); + byName.add(cmd.getRefName()); + } + Collections.sort(byName); + + PersonIdent ident = getRefLogIdent(); + if (ident == null) { + ident = new PersonIdent(refdb.getRepository()); + } + for (String name : byName) { + ReceiveCommand cmd = cmds.get(name); + if (isRefLogDisabled(cmd)) { + continue; + } + String msg = getRefLogMessage(cmd); + if (isRefLogIncludingResult(cmd)) { + String strResult = toResultString(cmd); + if (strResult != null) { + msg = msg.isEmpty() ? strResult : msg + ": " + strResult; //$NON-NLS-1$ + } + } + writer.writeLog(name, updateIndex, ident, cmd.getOldId(), + cmd.getNewId(), msg); + } + } + + private String toResultString(ReceiveCommand cmd) { + switch (cmd.getType()) { + case CREATE: + return ReflogEntry.PREFIX_CREATED; + case UPDATE: + // Match the behavior of a single RefUpdate. In that case, setting + // the force bit completely bypasses the potentially expensive + // isMergedInto check, by design, so the reflog message may be + // inaccurate. + // + // Similarly, this class bypasses the isMergedInto checks when the + // force bit is set, meaning we can't actually distinguish between + // UPDATE and UPDATE_NONFASTFORWARD when isAllowNonFastForwards() + // returns true. + return isAllowNonFastForwards() ? ReflogEntry.PREFIX_FORCED_UPDATE + : ReflogEntry.PREFIX_FAST_FORWARD; + case UPDATE_NONFASTFORWARD: + return ReflogEntry.PREFIX_FORCED_UPDATE; + default: + return null; + } + } + + private static List<Ref> toNewRefs(RevWalk rw, List<ReceiveCommand> pending) + throws IOException { + List<Ref> refs = new ArrayList<>(pending.size()); + for (ReceiveCommand cmd : pending) { + String name = cmd.getRefName(); + ObjectId newId = cmd.getNewId(); + String newSymref = cmd.getNewSymref(); + if (AnyObjectId.equals(ObjectId.zeroId(), newId) + && newSymref == null) { + refs.add(new ObjectIdRef.Unpeeled(NEW, name, null)); + continue; + } else if (newSymref != null) { + refs.add(new SymbolicRef(name, + new ObjectIdRef.Unpeeled(NEW, newSymref, null))); + continue; + } + + RevObject obj = rw.parseAny(newId); + RevObject peel = null; + if (obj instanceof RevTag) { + peel = rw.peel(obj); + } + if (peel != null) { + refs.add(new ObjectIdRef.PeeledTag(PACKED, name, newId, + peel.copy())); + } else { + refs.add(new ObjectIdRef.PeeledNonTag(PACKED, name, newId)); + } + } + return refs; + } + + private long nextUpdateIndex() throws IOException { + long updateIndex = 0; + for (Reftable r : refdb.stack().readers()) { + if (r instanceof ReftableReader) { + updateIndex = Math.max(updateIndex, + ((ReftableReader) r).maxUpdateIndex()); + } + } + return updateIndex + 1; + } + + private boolean canCompactTopOfStack(ReftableConfig cfg) + throws IOException { + ReftableStack stack = refdb.stack(); + List<Reftable> readers = stack.readers(); + if (readers.isEmpty()) { + return false; + } + + int lastIdx = readers.size() - 1; + DfsReftable last = stack.files().get(lastIdx); + DfsPackDescription desc = last.getPackDescription(); + if (desc.getPackSource() != PackSource.INSERT + || !packOnlyContainsReftable(desc)) { + return false; + } + + Reftable table = readers.get(lastIdx); + int bs = cfg.getRefBlockSize(); + return table instanceof ReftableReader + && ((ReftableReader) table).size() <= 3 * bs; + } + + private ReftableWriter.Stats compactTopOfStack(OutputStream out, + ReftableConfig cfg, byte[] newTable) throws IOException { + List<Reftable> stack = refdb.stack().readers(); + Reftable last = stack.get(stack.size() - 1); + + List<Reftable> tables = new ArrayList<>(2); + tables.add(last); + tables.add(new ReftableReader(BlockSource.from(newTable))); + + ReftableCompactor compactor = new ReftableCompactor(); + compactor.setConfig(cfg); + compactor.setIncludeDeletes(true); + compactor.addAll(tables); + compactor.compact(out); + return compactor.getStats(); + } + + private Set<DfsPackDescription> toPruneTopOfStack() throws IOException { + List<DfsReftable> stack = refdb.stack().files(); + DfsReftable last = stack.get(stack.size() - 1); + return Collections.singleton(last.getPackDescription()); + } + + private boolean packOnlyContainsReftable(DfsPackDescription desc) { + for (PackExt ext : PackExt.values()) { + if (ext != REFTABLE && desc.hasFileExt(ext)) { + return false; + } + } + return true; + } +} diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/ReftableStack.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/ReftableStack.java index 8d1cc989da..50ba0e0f38 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/ReftableStack.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/dfs/ReftableStack.java @@ -50,7 +50,10 @@ import java.util.List; import org.eclipse.jgit.internal.storage.reftable.Reftable; -/** Tracks multiple open {@link Reftable} instances. */ +/** + * Tracks multiple open + * {@link org.eclipse.jgit.internal.storage.reftable.Reftable} instances. + */ public class ReftableStack implements AutoCloseable { /** * Opens a stack of tables for reading. @@ -58,18 +61,19 @@ public class ReftableStack implements AutoCloseable { * @param ctx * context to read the tables with. This {@code ctx} will be * retained by the stack and each of the table readers. - * @param tables + * @param files * the tables to open. * @return stack reference to close the tables. - * @throws IOException + * @throws java.io.IOException * a table could not be opened */ - public static ReftableStack open(DfsReader ctx, List<DfsReftable> tables) + public static ReftableStack open(DfsReader ctx, List<DfsReftable> files) throws IOException { - ReftableStack stack = new ReftableStack(tables.size()); + ReftableStack stack = new ReftableStack(files.size()); boolean close = true; try { - for (DfsReftable t : tables) { + for (DfsReftable t : files) { + stack.files.add(t); stack.tables.add(t.open(ctx)); } close = false; @@ -81,13 +85,27 @@ public class ReftableStack implements AutoCloseable { } } + private final List<DfsReftable> files; private final List<Reftable> tables; private ReftableStack(int tableCnt) { + this.files = new ArrayList<>(tableCnt); this.tables = new ArrayList<>(tableCnt); } /** + * Get unmodifiable list of DfsRefatble files + * + * @return unmodifiable list of DfsRefatble files, in the same order the + * files were passed to {@link #open(DfsReader, List)}. + */ + public List<DfsReftable> files() { + return Collections.unmodifiableList(files); + } + + /** + * Get unmodifiable list of tables + * * @return unmodifiable list of tables, in the same order the files were * passed to {@link #open(DfsReader, List)}. */ @@ -95,6 +113,7 @@ public class ReftableStack implements AutoCloseable { return Collections.unmodifiableList(tables); } + /** {@inheritDoc} */ @Override public void close() { for (Reftable t : tables) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/BasePackBitmapIndex.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/BasePackBitmapIndex.java index b78ff2abf9..407061fa16 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/BasePackBitmapIndex.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/BasePackBitmapIndex.java @@ -58,6 +58,7 @@ abstract class BasePackBitmapIndex extends PackBitmapIndex { this.bitmaps = bitmaps; } + /** {@inheritDoc} */ @Override public EWAHCompressedBitmap getBitmap(AnyObjectId objectId) { StoredBitmap sb = bitmaps.get(objectId); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/BitmapIndexImpl.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/BitmapIndexImpl.java index 88eef4ce86..6ade4386ac 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/BitmapIndexImpl.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/BitmapIndexImpl.java @@ -59,7 +59,9 @@ import org.eclipse.jgit.util.BlockList; import com.googlecode.javaewah.EWAHCompressedBitmap; import com.googlecode.javaewah.IntIterator; -/** A compressed bitmap representation of the entire object graph. */ +/** + * A compressed bitmap representation of the entire object graph. + */ public class BitmapIndexImpl implements BitmapIndex { private static final int EXTRA_BITS = 10 * 1024; @@ -85,6 +87,7 @@ public class BitmapIndexImpl implements BitmapIndex { return packIndex; } + /** {@inheritDoc} */ @Override public CompressedBitmap getBitmap(AnyObjectId objectId) { EWAHCompressedBitmap compressed = packIndex.getBitmap(objectId); @@ -93,6 +96,7 @@ public class BitmapIndexImpl implements BitmapIndex { return new CompressedBitmap(compressed, this); } + /** {@inheritDoc} */ @Override public CompressedBitmapBuilder newBitmapBuilder() { return new CompressedBitmapBuilder(this); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ByteArrayWindow.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ByteArrayWindow.java index dc720bc62d..338df4a8e1 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ByteArrayWindow.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ByteArrayWindow.java @@ -63,6 +63,7 @@ final class ByteArrayWindow extends ByteWindow { array = b; } + /** {@inheritDoc} */ @Override protected int copy(final int p, final byte[] b, final int o, int n) { n = Math.min(array.length - p, n); @@ -70,6 +71,7 @@ final class ByteArrayWindow extends ByteWindow { return n; } + /** {@inheritDoc} */ @Override protected int setInput(final int pos, final Inflater inf) throws DataFormatException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ByteBufferWindow.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ByteBufferWindow.java index 05ddd69b36..4dcf133e08 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ByteBufferWindow.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ByteBufferWindow.java @@ -65,6 +65,7 @@ final class ByteBufferWindow extends ByteWindow { buffer = b; } + /** {@inheritDoc} */ @Override protected int copy(final int p, final byte[] b, final int o, int n) { final ByteBuffer s = buffer.slice(); @@ -89,6 +90,7 @@ final class ByteBufferWindow extends ByteWindow { } } + /** {@inheritDoc} */ @Override protected int setInput(final int pos, final Inflater inf) throws DataFormatException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ByteWindow.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ByteWindow.java index e774a14643..7963ceac47 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ByteWindow.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ByteWindow.java @@ -66,6 +66,16 @@ abstract class ByteWindow { protected final long end; + /** + * Constructor for ByteWindow. + * + * @param p + * a {@link org.eclipse.jgit.internal.storage.file.PackFile}. + * @param s + * where the byte window starts in the pack file + * @param n + * size of the byte window + */ protected ByteWindow(final PackFile p, final long s, final int n) { pack = p; start = s; @@ -127,6 +137,17 @@ abstract class ByteWindow { return setInput((int) (pos - start), inf); } + /** + * Set the input + * + * @param pos + * position + * @param inf + * an {@link java.util.zip.Inflater} object. + * @return size of the byte window + * @throws java.util.zip.DataFormatException + * if any. + */ protected abstract int setInput(int pos, Inflater inf) throws DataFormatException; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/CachedObjectDirectory.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/CachedObjectDirectory.java index ae8260a997..e810ae0e27 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/CachedObjectDirectory.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/CachedObjectDirectory.java @@ -117,11 +117,13 @@ class CachedObjectDirectory extends FileObjectDatabase { return m; } + /** {@inheritDoc} */ @Override public void close() { // Don't close anything. } + /** {@inheritDoc} */ @Override public ObjectDatabase newCachedDatabase() { return this; @@ -177,6 +179,7 @@ class CachedObjectDirectory extends FileObjectDatabase { wrapped.resolve(matches, id); } + /** {@inheritDoc} */ @Override public boolean has(final AnyObjectId objectId) throws IOException { return has(objectId, null); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/CheckoutEntryImpl.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/CheckoutEntryImpl.java index 2eacb7a793..05cabba83b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/CheckoutEntryImpl.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/CheckoutEntryImpl.java @@ -65,11 +65,13 @@ public class CheckoutEntryImpl implements CheckoutEntry { to = comment.substring(p2 + " to ".length(), p3); //$NON-NLS-1$ } + /** {@inheritDoc} */ @Override public String getFromBranch() { return from; } + /** {@inheritDoc} */ @Override public String getToBranch() { return to; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/FileObjectDatabase.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/FileObjectDatabase.java index 3afc050ba6..1f6b20aacf 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/FileObjectDatabase.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/FileObjectDatabase.java @@ -64,11 +64,13 @@ abstract class FileObjectDatabase extends ObjectDatabase { INSERTED, EXISTS_PACKED, EXISTS_LOOSE, FAILURE; } + /** {@inheritDoc} */ @Override public ObjectReader newReader() { return new WindowCursor(this); } + /** {@inheritDoc} */ @Override public ObjectDirectoryInserter newInserter() { return new ObjectDirectoryInserter(this, getConfig()); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/FileRepository.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/FileRepository.java index 646feac8cf..9e2fb55de0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/FileRepository.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/FileRepository.java @@ -116,7 +116,6 @@ import org.eclipse.jgit.util.SystemReader; * This class is thread-safe. * <p> * This implementation only handles a subtly undocumented subset of git features. - * */ public class FileRepository extends Repository { private static final String UNNAMED = "Unnamed repository; edit this file to name it for gitweb."; //$NON-NLS-1$ @@ -133,8 +132,9 @@ public class FileRepository extends Repository { * <p> * The work tree, object directory, alternate object directories and index * file locations are deduced from the given git directory and the default - * rules by running {@link FileRepositoryBuilder}. This constructor is the - * same as saying: + * rules by running + * {@link org.eclipse.jgit.storage.file.FileRepositoryBuilder}. This + * constructor is the same as saying: * * <pre> * new FileRepositoryBuilder().setGitDir(gitDir).build() @@ -142,7 +142,7 @@ public class FileRepository extends Repository { * * @param gitDir * GIT_DIR (the location of the repository metadata). - * @throws IOException + * @throws java.io.IOException * the repository appears to already exist but cannot be * accessed. * @see FileRepositoryBuilder @@ -156,7 +156,7 @@ public class FileRepository extends Repository { * * @param gitDir * GIT_DIR (the location of the repository metadata). - * @throws IOException + * @throws java.io.IOException * the repository appears to already exist but cannot be * accessed. * @see FileRepositoryBuilder @@ -170,7 +170,7 @@ public class FileRepository extends Repository { * * @param options * description of the repository's important paths. - * @throws IOException + * @throws java.io.IOException * the user configuration file or repository configuration file * cannot be accessed. */ @@ -247,46 +247,38 @@ public class FileRepository extends Repository { private void loadSystemConfig() throws IOException { try { systemConfig.load(); - } catch (ConfigInvalidException e1) { - IOException e2 = new IOException(MessageFormat.format(JGitText + } catch (ConfigInvalidException e) { + throw new IOException(MessageFormat.format(JGitText .get().systemConfigFileInvalid, systemConfig.getFile() - .getAbsolutePath(), e1)); - e2.initCause(e1); - throw e2; + .getAbsolutePath(), + e), e); } } private void loadUserConfig() throws IOException { try { userConfig.load(); - } catch (ConfigInvalidException e1) { - IOException e2 = new IOException(MessageFormat.format(JGitText + } catch (ConfigInvalidException e) { + throw new IOException(MessageFormat.format(JGitText .get().userConfigFileInvalid, userConfig.getFile() - .getAbsolutePath(), e1)); - e2.initCause(e1); - throw e2; + .getAbsolutePath(), + e), e); } } private void loadRepoConfig() throws IOException { try { repoConfig.load(); - } catch (ConfigInvalidException e1) { - IOException e2 = new IOException(JGitText.get().unknownRepositoryFormat); - e2.initCause(e1); - throw e2; + } catch (ConfigInvalidException e) { + throw new IOException(JGitText.get().unknownRepositoryFormat, e); } } /** + * {@inheritDoc} + * <p> * Create a new Git repository initializing the necessary files and * directories. - * - * @param bare - * if true, a bare repository is created. - * - * @throws IOException - * in case of IO problem */ @Override public void create(boolean bare) throws IOException { @@ -380,25 +372,27 @@ public class FileRepository extends Repository { } /** + * Get the directory containing the objects owned by this repository + * * @return the directory containing the objects owned by this repository. */ public File getObjectsDirectory() { return objectDatabase.getDirectory(); } - /** @return the object database storing this repository's data. */ + /** {@inheritDoc} */ @Override public ObjectDirectory getObjectDatabase() { return objectDatabase; } - /** @return the reference database which stores the reference namespace. */ + /** {@inheritDoc} */ @Override public RefDatabase getRefDatabase() { return refs; } - /** @return the configuration of this repository. */ + /** {@inheritDoc} */ @Override public FileBasedConfig getConfig() { if (systemConfig.isOutdated()) { @@ -425,6 +419,7 @@ public class FileRepository extends Repository { return repoConfig; } + /** {@inheritDoc} */ @Override @Nullable public String getGitwebDescription() throws IOException { @@ -443,6 +438,7 @@ public class FileRepository extends Repository { return d; } + /** {@inheritDoc} */ @Override public void setGitwebDescription(@Nullable String description) throws IOException { @@ -479,14 +475,14 @@ public class FileRepository extends Repository { } /** + * {@inheritDoc} + * <p> * Objects known to exist but not expressed by {@link #getAllRefs()}. * <p> * When a repository borrows objects from another repository, it can * advertise that it safely has that other repository's references, without - * exposing any other details about the other repository. This may help - * a client trying to push changes avoid pushing more than it needs to. - * - * @return unmodifiable collection of other known objects. + * exposing any other details about the other repository. This may help a + * client trying to push changes avoid pushing more than it needs to. */ @Override public Set<ObjectId> getAdditionalHaves() { @@ -531,7 +527,7 @@ public class FileRepository extends Repository { * * @param pack * path of the pack file to open. - * @throws IOException + * @throws java.io.IOException * index file could not be opened, read, or is not recognized as * a Git pack file index. */ @@ -539,6 +535,7 @@ public class FileRepository extends Repository { objectDatabase.openPack(pack); } + /** {@inheritDoc} */ @Override public void scanForRepoChanges() throws IOException { getRefDatabase().getRefs(ALL); // This will look for changes to refs @@ -557,18 +554,14 @@ public class FileRepository extends Repository { notifyIndexChanged(); } + /** {@inheritDoc} */ @Override public void notifyIndexChanged() { snapshot = FileSnapshot.save(getIndexFile()); fireEvent(new IndexChangedEvent()); } - /** - * @param refName - * @return a {@link ReflogReader} for the supplied refname, or null if the - * named ref does not exist. - * @throws IOException the ref could not be accessed. - */ + /** {@inheritDoc} */ @Override public ReflogReader getReflogReader(String refName) throws IOException { Ref ref = findRef(refName); @@ -577,6 +570,7 @@ public class FileRepository extends Repository { return null; } + /** {@inheritDoc} */ @Override public AttributesNodeProvider createAttributesNodeProvider() { return new AttributesNodeProviderImpl(this); @@ -642,6 +636,7 @@ public class FileRepository extends Repository { ConfigConstants.CONFIG_KEY_AUTODETACH, true); } + /** {@inheritDoc} */ @Override public void autoGC(ProgressMonitor monitor) { GC gc = new GC(this); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/FileSnapshot.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/FileSnapshot.java index 97f3b573d0..2165aa2b76 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/FileSnapshot.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/FileSnapshot.java @@ -121,7 +121,6 @@ public class FileSnapshot { * * @param modified * the last modification time of the file - * * @return the snapshot. */ public static FileSnapshot save(long modified) { @@ -145,6 +144,8 @@ public class FileSnapshot { } /** + * Get time of last snapshot update + * * @return time of last snapshot update */ public long lastModified() { @@ -208,6 +209,7 @@ public class FileSnapshot { return lastModified == other.lastModified; } + /** {@inheritDoc} */ @Override public boolean equals(Object other) { if (other instanceof FileSnapshot) @@ -215,6 +217,7 @@ public class FileSnapshot { return false; } + /** {@inheritDoc} */ @Override public int hashCode() { // This is pretty pointless, but override hashCode to ensure that @@ -223,6 +226,7 @@ public class FileSnapshot { return (int) lastModified; } + /** {@inheritDoc} */ @Override public String toString() { if (this == DIRTY) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/GC.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/GC.java index 9300f022b7..a69485a393 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/GC.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/GC.java @@ -58,7 +58,6 @@ import java.nio.file.DirectoryNotEmptyException; import java.nio.file.DirectoryStream; import java.nio.file.Files; import java.nio.file.Path; -import java.nio.file.Paths; import java.nio.file.StandardCopyOption; import java.text.MessageFormat; import java.text.ParseException; @@ -123,8 +122,10 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** - * A garbage collector for git {@link FileRepository}. Instances of this class - * are not thread-safe. Don't use the same instance from multiple threads. + * A garbage collector for git + * {@link org.eclipse.jgit.internal.storage.file.FileRepository}. Instances of + * this class are not thread-safe. Don't use the same instance from multiple + * threads. * * This class started as a copy of DfsGarbageCollector from Shawn O. Pearce * adapted to FileRepositories. @@ -217,7 +218,8 @@ public class GC { } /** - * Runs a garbage collector on a {@link FileRepository}. It will + * Runs a garbage collector on a + * {@link org.eclipse.jgit.internal.storage.file.FileRepository}. It will * <ul> * <li>pack loose references into packed-refs</li> * <li>repack all reachable objects into new pack files and delete the old @@ -234,9 +236,11 @@ public class GC { * return immediately. In this case, errors will not be reported except in * gc.log. * - * @return the collection of {@link PackFile}'s which are newly created - * @throws IOException - * @throws ParseException + * @return the collection of + * {@link org.eclipse.jgit.internal.storage.file.PackFile}'s which + * are newly created + * @throws java.io.IOException + * @throws java.text.ParseException * If the configuration parameter "gc.pruneexpire" couldn't be * parsed */ @@ -460,7 +464,7 @@ public class GC { * which can be found in packs. If certain objects can't be pruned (e.g. * because the filesystem delete operation fails) this is silently ignored. * - * @throws IOException + * @throws java.io.IOException */ public void prunePacked() throws IOException { ObjectDirectory objdb = repo.getObjectDatabase(); @@ -518,9 +522,8 @@ public class GC { * * @param objectsToKeep * a set of objects which should explicitly not be pruned - * - * @throws IOException - * @throws ParseException + * @throws java.io.IOException + * @throws java.text.ParseException * If the configuration parameter "gc.pruneexpire" couldn't be * parsed */ @@ -767,7 +770,7 @@ public class GC { /** * Packs all non-symbolic, loose refs into packed-refs. * - * @throws IOException + * @throws java.io.IOException */ public void packRefs() throws IOException { Collection<Ref> refs = repo.getRefDatabase().getRefs(Constants.R_REFS).values(); @@ -795,10 +798,10 @@ public class GC { * repacked. All old pack files which existed before are deleted. * * @return a collection of the newly created pack files - * @throws IOException + * @throws java.io.IOException * when during reading of refs, index, packfiles, objects, * reflog-entries or during writing to the packfiles - * {@link IOException} occurs + * {@link java.io.IOException} occurs */ public Collection<PackFile> repack() throws IOException { Collection<PackFile> toBeDeleted = repo.getObjectDatabase().getPacks(); @@ -964,8 +967,7 @@ public class GC { * </p> */ private void deleteOrphans() { - Path packDir = Paths.get(repo.getObjectsDirectory().getAbsolutePath(), - "pack"); //$NON-NLS-1$ + Path packDir = repo.getObjectDatabase().getPackDirectory().toPath(); List<String> fileNames = null; try (Stream<Path> files = Files.list(packDir)) { fileNames = files.map(path -> path.getFileName().toString()) @@ -989,7 +991,7 @@ public class GC { } else { if (base == null || !n.startsWith(base)) { try { - Files.delete(new File(packDir.toFile(), n).toPath()); + Files.delete(FileUtils.toPath(new File(packDir.toFile(), n))); } catch (IOException e) { LOG.error(e.getMessage(), e); } @@ -999,8 +1001,7 @@ public class GC { } private void deleteTempPacksIdx() { - Path packDir = Paths.get(repo.getObjectsDirectory().getAbsolutePath(), - "pack"); //$NON-NLS-1$ + Path packDir = repo.getObjectDatabase().getPackDirectory().toPath(); Instant threshold = Instant.now().minus(1, ChronoUnit.DAYS); try (DirectoryStream<Path> stream = Files.newDirectoryStream(packDir, "gc_*_tmp")) { //$NON-NLS-1$ @@ -1175,7 +1176,7 @@ public class GC { // create temporary files String id = pw.computeName().getName(); - File packdir = new File(repo.getObjectsDirectory(), "pack"); //$NON-NLS-1$ + File packdir = repo.getObjectDatabase().getPackDirectory(); tmpPack = File.createTempFile("gc_", ".pack_tmp", packdir); //$NON-NLS-1$ //$NON-NLS-2$ final String tmpBase = tmpPack.getName() .substring(0, tmpPack.getName().lastIndexOf('.')); @@ -1275,7 +1276,7 @@ public class GC { } private File nameFor(String name, String ext) { - File packdir = new File(repo.getObjectsDirectory(), "pack"); //$NON-NLS-1$ + File packdir = repo.getObjectDatabase().getPackDirectory(); return new File(packdir, "pack-" + name + ext); //$NON-NLS-1$ } @@ -1351,7 +1352,7 @@ public class GC { * Returns information about objects and pack files for a FileRepository. * * @return information about objects and pack files for a FileRepository - * @throws IOException + * @throws java.io.IOException */ public RepoStatistics getStatistics() throws IOException { RepoStatistics ret = new RepoStatistics(); @@ -1396,7 +1397,7 @@ public class GC { /** * Set the progress monitor used for garbage collection methods. * - * @param pm + * @param pm a {@link org.eclipse.jgit.lib.ProgressMonitor} object. * @return this */ public GC setProgressMonitor(ProgressMonitor pm) { @@ -1438,7 +1439,8 @@ public class GC { * "git gc --aggressive" * * @param pconfig - * the {@link PackConfig} used when writing packs + * the {@link org.eclipse.jgit.storage.pack.PackConfig} used when + * writing packs */ public void setPackConfig(PackConfig pconfig) { this.pconfig = pconfig; @@ -1482,7 +1484,7 @@ public class GC { * it exits without performing any work. Some JGit commands run * {@code gc --auto} after performing operations that could create many * loose objects. - * <p/> + * <p> * Housekeeping is required if there are too many loose objects or too many * packs in the repository. If the number of loose objects exceeds the value * of the gc.auto option JGit GC consolidates all existing packs into a @@ -1490,13 +1492,13 @@ public class GC { * combine all loose objects into a single pack using {@code repack -d -l}. * Setting the value of {@code gc.auto} to 0 disables automatic packing of * loose objects. - * <p/> + * <p> * If the number of packs exceeds the value of {@code gc.autoPackLimit}, * then existing packs (except those marked with a .keep file) are * consolidated into a single pack by using the {@code -A} option of repack. * Setting {@code gc.autoPackLimit} to 0 disables automatic consolidation of * packs. - * <p/> + * <p> * Like git the following jgit commands run auto gc: * <ul> * <li>fetch</li> diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/GcLog.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/GcLog.java index e5fc0c5bad..82458c1acf 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/GcLog.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/GcLog.java @@ -55,6 +55,7 @@ import java.time.Instant; import org.eclipse.jgit.api.errors.JGitInternalException; import org.eclipse.jgit.lib.ConfigConstants; +import org.eclipse.jgit.util.FileUtils; import org.eclipse.jgit.util.GitDateParser; import org.eclipse.jgit.util.SystemReader; @@ -102,7 +103,7 @@ class GcLog { private boolean autoGcBlockedByOldLockFile() { try { - FileTime lastModified = Files.getLastModifiedTime(logFile.toPath()); + FileTime lastModified = Files.getLastModifiedTime(FileUtils.toPath(logFile)); if (lastModified.toInstant().compareTo(getLogExpiry()) > 0) { // There is an existing log file, which is too recent to ignore return true; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/GlobalAttributesNode.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/GlobalAttributesNode.java index 454d3bff69..2f5de049fe 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/GlobalAttributesNode.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/GlobalAttributesNode.java @@ -51,20 +51,27 @@ import org.eclipse.jgit.lib.CoreConfig; import org.eclipse.jgit.lib.Repository; import org.eclipse.jgit.util.FS; -/** Attribute node loaded from global system-wide file. */ +/** + * Attribute node loaded from global system-wide file. + */ public class GlobalAttributesNode extends AttributesNode { final Repository repository; /** + * Constructor for GlobalAttributesNode. + * * @param repository + * the {@link org.eclipse.jgit.lib.Repository}. */ public GlobalAttributesNode(Repository repository) { this.repository = repository; } /** + * Load the attributes node + * * @return the attributes node - * @throws IOException + * @throws java.io.IOException */ public AttributesNode load() throws IOException { AttributesNode r = new AttributesNode(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/InfoAttributesNode.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/InfoAttributesNode.java index 3f82e2a20d..cd09374157 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/InfoAttributesNode.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/InfoAttributesNode.java @@ -51,20 +51,27 @@ import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.lib.Repository; import org.eclipse.jgit.util.FS; -/** Attribute node loaded from the $GIT_DIR/info/attributes file. */ +/** + * Attribute node loaded from the $GIT_DIR/info/attributes file. + */ public class InfoAttributesNode extends AttributesNode { final Repository repository; /** + * Constructor for InfoAttributesNode. + * * @param repository + * the {@link org.eclipse.jgit.lib.Repository}. */ public InfoAttributesNode(Repository repository) { this.repository = repository; } /** + * Load the attributes node + * * @return the attributes node - * @throws IOException + * @throws java.io.IOException */ public AttributesNode load() throws IOException { AttributesNode r = new AttributesNode(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LargePackedWholeObject.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LargePackedWholeObject.java index 4d6e4dd583..8c42aaa2b7 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LargePackedWholeObject.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LargePackedWholeObject.java @@ -77,32 +77,35 @@ class LargePackedWholeObject extends ObjectLoader { this.db = db; } + /** {@inheritDoc} */ @Override public int getType() { return type; } + /** {@inheritDoc} */ @Override public long getSize() { return size; } + /** {@inheritDoc} */ @Override public boolean isLarge() { return true; } + /** {@inheritDoc} */ @Override public byte[] getCachedBytes() throws LargeObjectException { try { throw new LargeObjectException(getObjectId()); } catch (IOException cannotObtainId) { - LargeObjectException err = new LargeObjectException(); - err.initCause(cannotObtainId); - throw err; + throw new LargeObjectException(cannotObtainId); } } + /** {@inheritDoc} */ @Override public ObjectStream openStream() throws MissingObjectException, IOException { WindowCursor wc = new WindowCursor(db); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LazyObjectIdSetFile.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LazyObjectIdSetFile.java index 1e2617c0e3..3d0e9c7189 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LazyObjectIdSetFile.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LazyObjectIdSetFile.java @@ -57,7 +57,9 @@ import org.eclipse.jgit.lib.MutableObjectId; import org.eclipse.jgit.lib.ObjectIdOwnerMap; import org.eclipse.jgit.lib.ObjectIdSet; -/** Lazily loads a set of ObjectIds, one per line. */ +/** + * Lazily loads a set of ObjectIds, one per line. + */ public class LazyObjectIdSetFile implements ObjectIdSet { private final File src; private ObjectIdOwnerMap<Entry> set; @@ -72,6 +74,7 @@ public class LazyObjectIdSetFile implements ObjectIdSet { this.src = src; } + /** {@inheritDoc} */ @Override public boolean contains(AnyObjectId objectId) { if (set == null) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LocalCachedPack.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LocalCachedPack.java index fd9dcdafad..289d89d698 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LocalCachedPack.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LocalCachedPack.java @@ -71,6 +71,7 @@ class LocalCachedPack extends CachedPack { this.packs = packs.toArray(new PackFile[packs.size()]); } + /** {@inheritDoc} */ @Override public long getObjectCount() throws IOException { long cnt = 0; @@ -85,6 +86,7 @@ class LocalCachedPack extends CachedPack { pack.copyPackAsIs(out, wc); } + /** {@inheritDoc} */ @Override public boolean hasObject(ObjectToPack obj, StoredObjectRepresentation rep) { try { @@ -118,7 +120,7 @@ class LocalCachedPack extends CachedPack { } private String getPackFilePath(String packName) { - final File packDir = new File(odb.getDirectory(), "pack"); //$NON-NLS-1$ + final File packDir = odb.getPackDirectory(); return new File(packDir, "pack-" + packName + ".pack").getPath(); //$NON-NLS-1$ //$NON-NLS-2$ } } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LocalObjectRepresentation.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LocalObjectRepresentation.java index a42e6797d5..35f97735c6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LocalObjectRepresentation.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LocalObjectRepresentation.java @@ -92,11 +92,13 @@ class LocalObjectRepresentation extends StoredObjectRepresentation { private ObjectId baseId; + /** {@inheritDoc} */ @Override public int getWeight() { return (int) Math.min(length, Integer.MAX_VALUE); } + /** {@inheritDoc} */ @Override public ObjectId getDeltaBase() { if (baseId == null && getFormat() == PACK_DELTA) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LocalObjectToPack.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LocalObjectToPack.java index fafe1321e3..55eeb95ce5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LocalObjectToPack.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LocalObjectToPack.java @@ -62,12 +62,14 @@ class LocalObjectToPack extends ObjectToPack { super(src, type); } + /** {@inheritDoc} */ @Override protected void clearReuseAsIs() { super.clearReuseAsIs(); pack = null; } + /** {@inheritDoc} */ @Override public void select(StoredObjectRepresentation ref) { LocalObjectRepresentation ptr = (LocalObjectRepresentation) ref; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LockFile.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LockFile.java index 56f42b3761..b38278595a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LockFile.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/LockFile.java @@ -59,7 +59,6 @@ import java.nio.channels.FileChannel; import java.nio.file.StandardCopyOption; import java.text.MessageFormat; -import org.eclipse.jgit.errors.LockFailedException; import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.lib.ObjectId; @@ -86,10 +85,12 @@ public class LockFile { * Unlock the given file. * <p> * This method can be used for recovering from a thrown - * {@link LockFailedException} . This method does not validate that the lock - * is or is not currently held before attempting to unlock it. + * {@link org.eclipse.jgit.errors.LockFailedException} . This method does + * not validate that the lock is or is not currently held before attempting + * to unlock it. * * @param file + * a {@link java.io.File} object. * @return true if unlocked, false if unlocking failed */ public static boolean unlock(final File file) { @@ -146,7 +147,9 @@ public class LockFile { * @param fs * the file system abstraction which will be necessary to perform * certain file system operations. - * @deprecated use {@link LockFile#LockFile(File)} instead + * @deprecated use + * {@link org.eclipse.jgit.internal.storage.file.LockFile#LockFile(File)} + * instead */ @Deprecated public LockFile(final File f, final FS fs) { @@ -170,7 +173,7 @@ public class LockFile { * * @return true if the lock is now held by the caller; false if it is held * by someone else. - * @throws IOException + * @throws java.io.IOException * the temporary output file could not be created. The caller * does not hold the lock. */ @@ -196,7 +199,7 @@ public class LockFile { * * @return true if the lock is now held by the caller; false if it is held * by someone else. - * @throws IOException + * @throws java.io.IOException * the temporary output file could not be created. The caller * does not hold the lock. */ @@ -217,12 +220,12 @@ public class LockFile { * This method does nothing if the current file does not exist, or exists * but is empty. * - * @throws IOException + * @throws java.io.IOException * the temporary file could not be written, or a read error * occurred while reading from the current file. The lock is * released before throwing the underlying IO exception to the * caller. - * @throws RuntimeException + * @throws java.lang.RuntimeException * the temporary file could not be written. The lock is released * before throwing the underlying exception to the caller. */ @@ -275,10 +278,10 @@ public class LockFile { * @param id * the id to store in the file. The id will be written in hex, * followed by a sole LF. - * @throws IOException + * @throws java.io.IOException * the temporary file could not be written. The lock is released * before throwing the underlying IO exception to the caller. - * @throws RuntimeException + * @throws java.lang.RuntimeException * the temporary file could not be written. The lock is released * before throwing the underlying exception to the caller. */ @@ -296,10 +299,10 @@ public class LockFile { * the bytes to store in the temporary file. No additional bytes * are added, so if the file must end with an LF it must appear * at the end of the byte array. - * @throws IOException + * @throws java.io.IOException * the temporary file could not be written. The lock is released * before throwing the underlying IO exception to the caller. - * @throws RuntimeException + * @throws java.lang.RuntimeException * the temporary file could not be written. The lock is released * before throwing the underlying exception to the caller. */ @@ -405,7 +408,8 @@ public class LockFile { } /** - * Request that {@link #commit()} remember the {@link FileSnapshot}. + * Request that {@link #commit()} remember the + * {@link org.eclipse.jgit.internal.storage.file.FileSnapshot}. * * @param on * true if the commit method must remember the FileSnapshot. @@ -431,7 +435,7 @@ public class LockFile { * method sleeps until it can force the new lock file's modification date to * be later than the target file. * - * @throws InterruptedException + * @throws java.lang.InterruptedException * the thread was interrupted before the last modified date of * the lock file was different from the last modified date of * the target file. @@ -454,7 +458,7 @@ public class LockFile { * @return true if the commit was successful and the file contains the new * data; false if the commit failed and the file remains with the * old data. - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * the lock is not held. */ public boolean commit() { @@ -496,7 +500,11 @@ public class LockFile { return commitSnapshot.lastModified(); } - /** @return get the {@link FileSnapshot} just before commit. */ + /** + * Get the {@link FileSnapshot} just before commit. + * + * @return get the {@link FileSnapshot} just before commit. + */ public FileSnapshot getCommitSnapshot() { return commitSnapshot; } @@ -540,6 +548,7 @@ public class LockFile { } } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ObjectDirectory.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ObjectDirectory.java index 153c7dd925..3e2fd82ce0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ObjectDirectory.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ObjectDirectory.java @@ -91,12 +91,12 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** - * Traditional file system based {@link ObjectDatabase}. + * Traditional file system based {@link org.eclipse.jgit.lib.ObjectDatabase}. * <p> * This is the classical object database representation for a Git repository, * where objects are stored loose by hashing them into directories by their - * {@link ObjectId}, or are stored in compressed containers known as - * {@link PackFile}s. + * {@link org.eclipse.jgit.lib.ObjectId}, or are stored in compressed containers + * known as {@link org.eclipse.jgit.internal.storage.file.PackFile}s. * <p> * Optionally an object database can reference one or more alternates; other * ObjectDatabase instances that are searched in addition to the current @@ -161,7 +161,7 @@ public class ObjectDirectory extends FileObjectDatabase { * @param shallowFile * file which contains IDs of shallow commits, null if shallow * commits handling should be turned off - * @throws IOException + * @throws java.io.IOException * an alternate object cannot be opened. */ public ObjectDirectory(final Config cfg, final File dir, @@ -188,26 +188,38 @@ public class ObjectDirectory extends FileObjectDatabase { } } - /** - * @return the location of the <code>objects</code> directory. - */ + /** {@inheritDoc} */ @Override public final File getDirectory() { return objects; } /** + * <p>Getter for the field <code>packDirectory</code>.</p> + * + * @return the location of the <code>pack</code> directory. + * @since 4.10 + */ + public final File getPackDirectory() { + return packDirectory; + } + + /** + * <p>Getter for the field <code>preservedDirectory</code>.</p> + * * @return the location of the <code>preserved</code> directory. */ public final File getPreservedDirectory() { return preservedDirectory; } + /** {@inheritDoc} */ @Override public boolean exists() { return fs.exists(objects); } + /** {@inheritDoc} */ @Override public void create() throws IOException { FileUtils.mkdirs(objects); @@ -215,6 +227,7 @@ public class ObjectDirectory extends FileObjectDatabase { FileUtils.mkdir(packDirectory); } + /** {@inheritDoc} */ @Override public ObjectDirectoryInserter newInserter() { return new ObjectDirectoryInserter(this, config); @@ -230,6 +243,7 @@ public class ObjectDirectory extends FileObjectDatabase { return new PackInserter(this); } + /** {@inheritDoc} */ @Override public void close() { unpackedObjectCache.clear(); @@ -248,13 +262,7 @@ public class ObjectDirectory extends FileObjectDatabase { } } - /** - * @return unmodifiable collection of all known pack files local to this - * directory. Most recent packs are presented first. Packs most - * likely to contain more recent objects appear before packs - * containing objects referenced by commits further back in the - * history of the repository. - */ + /** {@inheritDoc} */ @Override public Collection<PackFile> getPacks() { PackList list = packList.get(); @@ -265,14 +273,9 @@ public class ObjectDirectory extends FileObjectDatabase { } /** + * {@inheritDoc} + * <p> * Add a single existing pack to the list of available pack files. - * - * @param pack - * path of the pack file to open. - * @return the pack that was opened and added to the database. - * @throws IOException - * index file could not be opened, read, or is not recognized as - * a Git pack file index. */ @Override public PackFile openPack(final File pack) @@ -299,11 +302,13 @@ public class ObjectDirectory extends FileObjectDatabase { return res; } + /** {@inheritDoc} */ @Override public String toString() { return "ObjectDirectory[" + getDirectory() + "]"; //$NON-NLS-1$ //$NON-NLS-2$ } + /** {@inheritDoc} */ @Override public boolean has(AnyObjectId objectId) { return unpackedObjectCache.isUnpacked(objectId) @@ -715,7 +720,7 @@ public class ObjectDirectory extends FileObjectDatabase { return InsertLooseObjectResult.EXISTS_LOOSE; } try { - Files.move(tmp.toPath(), dst.toPath(), + Files.move(FileUtils.toPath(tmp), FileUtils.toPath(dst), StandardCopyOption.ATOMIC_MOVE); dst.setReadOnly(); unpackedObjectCache.add(id); @@ -732,7 +737,7 @@ public class ObjectDirectory extends FileObjectDatabase { // FileUtils.mkdir(dst.getParentFile(), true); try { - Files.move(tmp.toPath(), dst.toPath(), + Files.move(FileUtils.toPath(tmp), FileUtils.toPath(dst), StandardCopyOption.ATOMIC_MOVE); dst.setReadOnly(); unpackedObjectCache.add(id); @@ -1058,11 +1063,9 @@ public class ObjectDirectory extends FileObjectDatabase { } /** + * {@inheritDoc} + * <p> * Compute the location of a loose object file. - * - * @param objectId - * identity of the loose object to map to the directory. - * @return location of the object, if it were to exist as a loose object. */ @Override public File fileFor(AnyObjectId objectId) { @@ -1147,6 +1150,7 @@ public class ObjectDirectory extends FileObjectDatabase { } } + /** {@inheritDoc} */ @Override public ObjectDatabase newCachedDatabase() { return newCachedFileObjectDatabase(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ObjectDirectoryInserter.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ObjectDirectoryInserter.java index aa435bf67c..e06f72167e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ObjectDirectoryInserter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ObjectDirectoryInserter.java @@ -83,6 +83,7 @@ class ObjectDirectoryInserter extends ObjectInserter { config = cfg.get(WriteConfig.KEY); } + /** {@inheritDoc} */ @Override public ObjectId insert(int type, byte[] data, int off, int len) throws IOException { @@ -114,6 +115,7 @@ class ObjectDirectoryInserter extends ObjectInserter { } } + /** {@inheritDoc} */ @Override public ObjectId insert(final int type, long len, final InputStream is) throws IOException { @@ -166,21 +168,25 @@ class ObjectDirectoryInserter extends ObjectInserter { .format(JGitText.get().unableToCreateNewObject, dst)); } + /** {@inheritDoc} */ @Override public PackParser newPackParser(InputStream in) throws IOException { return new ObjectDirectoryPackParser(db, in); } + /** {@inheritDoc} */ @Override public ObjectReader newReader() { return new WindowCursor(db, this); } + /** {@inheritDoc} */ @Override public void flush() throws IOException { // Do nothing. Loose objects are immediately visible. } + /** {@inheritDoc} */ @Override public void close() { if (deflate != null) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ObjectDirectoryPackParser.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ObjectDirectoryPackParser.java index 2e6c245ea1..5dcba6001a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ObjectDirectoryPackParser.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ObjectDirectoryPackParser.java @@ -64,7 +64,6 @@ import org.eclipse.jgit.lib.AnyObjectId; import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.lib.CoreConfig; import org.eclipse.jgit.lib.ObjectId; -import org.eclipse.jgit.lib.ObjectInserter; import org.eclipse.jgit.lib.ProgressMonitor; import org.eclipse.jgit.transport.PackParser; import org.eclipse.jgit.transport.PackedObjectInfo; @@ -72,10 +71,11 @@ import org.eclipse.jgit.util.FileUtils; import org.eclipse.jgit.util.NB; /** - * Consumes a pack stream and stores as a pack file in {@link ObjectDirectory}. + * Consumes a pack stream and stores as a pack file in + * {@link org.eclipse.jgit.internal.storage.file.ObjectDirectory}. * <p> * To obtain an instance of a parser, applications should use - * {@link ObjectInserter#newPackParser(InputStream)}. + * {@link org.eclipse.jgit.lib.ObjectInserter#newPackParser(InputStream)}. */ public class ObjectDirectoryPackParser extends PackParser { private final FileObjectDatabase db; @@ -158,7 +158,7 @@ public class ObjectDirectoryPackParser extends PackParser { } /** - * Get the imported {@link PackFile}. + * Get the imported {@link org.eclipse.jgit.internal.storage.file.PackFile}. * <p> * This method is supplied only to support testing; applications shouldn't * be using it directly to access the imported data. @@ -169,6 +169,7 @@ public class ObjectDirectoryPackParser extends PackParser { return newPack; } + /** {@inheritDoc} */ @Override public long getPackSize() { if (newPack == null) @@ -184,6 +185,7 @@ public class ObjectDirectoryPackParser extends PackParser { return size; } + /** {@inheritDoc} */ @Override public PackLock parse(ProgressMonitor receiving, ProgressMonitor resolving) throws IOException { @@ -218,34 +220,40 @@ public class ObjectDirectoryPackParser extends PackParser { } } + /** {@inheritDoc} */ @Override protected void onPackHeader(long objectCount) throws IOException { // Ignored, the count is not required. } + /** {@inheritDoc} */ @Override protected void onBeginWholeObject(long streamPosition, int type, long inflatedSize) throws IOException { crc.reset(); } + /** {@inheritDoc} */ @Override protected void onEndWholeObject(PackedObjectInfo info) throws IOException { info.setCRC((int) crc.getValue()); } + /** {@inheritDoc} */ @Override protected void onBeginOfsDelta(long streamPosition, long baseStreamPosition, long inflatedSize) throws IOException { crc.reset(); } + /** {@inheritDoc} */ @Override protected void onBeginRefDelta(long streamPosition, AnyObjectId baseId, long inflatedSize) throws IOException { crc.reset(); } + /** {@inheritDoc} */ @Override protected UnresolvedDelta onEndDelta() throws IOException { UnresolvedDelta delta = new UnresolvedDelta(); @@ -253,30 +261,35 @@ public class ObjectDirectoryPackParser extends PackParser { return delta; } + /** {@inheritDoc} */ @Override protected void onInflatedObjectData(PackedObjectInfo obj, int typeCode, byte[] data) throws IOException { // ObjectDirectory ignores this event. } + /** {@inheritDoc} */ @Override protected void onObjectHeader(Source src, byte[] raw, int pos, int len) throws IOException { crc.update(raw, pos, len); } + /** {@inheritDoc} */ @Override protected void onObjectData(Source src, byte[] raw, int pos, int len) throws IOException { crc.update(raw, pos, len); } + /** {@inheritDoc} */ @Override protected void onStoreStream(byte[] raw, int pos, int len) throws IOException { out.write(raw, pos, len); } + /** {@inheritDoc} */ @Override protected void onPackFooter(byte[] hash) throws IOException { packEnd = out.getFilePointer(); @@ -285,6 +298,7 @@ public class ObjectDirectoryPackParser extends PackParser { packHash = hash; } + /** {@inheritDoc} */ @Override protected ObjectTypeAndSize seekDatabase(UnresolvedDelta delta, ObjectTypeAndSize info) throws IOException { @@ -293,6 +307,7 @@ public class ObjectDirectoryPackParser extends PackParser { return readObjectHeader(info); } + /** {@inheritDoc} */ @Override protected ObjectTypeAndSize seekDatabase(PackedObjectInfo obj, ObjectTypeAndSize info) throws IOException { @@ -301,11 +316,13 @@ public class ObjectDirectoryPackParser extends PackParser { return readObjectHeader(info); } + /** {@inheritDoc} */ @Override protected int readDatabase(byte[] dst, int pos, int cnt) throws IOException { return out.read(dst, pos, cnt); } + /** {@inheritDoc} */ @Override protected boolean checkCRC(int oldCRC) { return oldCRC == (int) crc.getValue(); @@ -323,6 +340,7 @@ public class ObjectDirectoryPackParser extends PackParser { tmpPack.deleteOnExit(); } + /** {@inheritDoc} */ @Override protected boolean onAppendBase(final int typeCode, final byte[] data, final PackedObjectInfo info) throws IOException { @@ -365,6 +383,7 @@ public class ObjectDirectoryPackParser extends PackParser { return true; } + /** {@inheritDoc} */ @Override protected void onEndThinPack() throws IOException { final byte[] buf = buffer(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackBitmapIndex.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackBitmapIndex.java index 7fb8e6d644..21a1c7fcb3 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackBitmapIndex.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackBitmapIndex.java @@ -58,11 +58,11 @@ import com.googlecode.javaewah.EWAHCompressedBitmap; /** * Logical representation of the bitmap data stored in the pack index. - * {@link ObjectId}s are encoded as a single integer in the range [0, - * {@link #getObjectCount()}). Compressed bitmaps are available at certain - * {@code ObjectId}s, which represent all of the objects reachable from that - * {@code ObjectId} (include the {@code ObjectId} itself). The meaning of the - * positions in the bitmaps can be decoded using {@link #getObject(int)} and + * {@link org.eclipse.jgit.lib.ObjectId}s are encoded as a single integer in the + * range [0, {@link #getObjectCount()}). Compressed bitmaps are available at + * certain {@code ObjectId}s, which represent all of the objects reachable from + * that {@code ObjectId} (include the {@code ObjectId} itself). The meaning of + * the positions in the bitmaps can be decoded using {@link #getObject(int)} and * {@link #ofObjectType(EWAHCompressedBitmap, int)}. Furthermore, * {@link #findPosition(AnyObjectId)} can be used to build other bitmaps that a * compatible with the encoded bitmaps available from the index. @@ -85,7 +85,7 @@ public abstract class PackBitmapIndex { * @param reverseIndex * the pack reverse index for the corresponding pack file. * @return a copy of the index in-memory. - * @throws IOException + * @throws java.io.IOException * the stream cannot be read. * @throws CorruptObjectException * the stream does not contain a valid pack bitmap index. @@ -97,12 +97,10 @@ public abstract class PackBitmapIndex { try { return read(fd, packIndex, reverseIndex); } catch (IOException ioe) { - final String path = idxFile.getAbsolutePath(); - final IOException err; - err = new IOException(MessageFormat.format( - JGitText.get().unreadablePackIndex, path)); - err.initCause(ioe); - throw err; + throw new IOException(MessageFormat + .format(JGitText.get().unreadablePackIndex, + idxFile.getAbsolutePath()), + ioe); } finally { try { fd.close(); @@ -128,7 +126,7 @@ public abstract class PackBitmapIndex { * @param reverseIndex * the pack reverse index for the corresponding pack file. * @return a copy of the index in-memory. - * @throws IOException + * @throws java.io.IOException * the stream cannot be read. * @throws CorruptObjectException * the stream does not contain a valid pack bitmap index. @@ -157,7 +155,7 @@ public abstract class PackBitmapIndex { * @param position * the id for which the object will be found. * @return the ObjectId. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * when the item is not found. */ public abstract ObjectId getObject(int position) throws IllegalArgumentException; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackBitmapIndexBuilder.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackBitmapIndexBuilder.java index bfd60fc535..70eb10ea8f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackBitmapIndexBuilder.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackBitmapIndexBuilder.java @@ -64,7 +64,8 @@ import org.eclipse.jgit.util.BlockList; import com.googlecode.javaewah.EWAHCompressedBitmap; /** - * Helper for constructing {@link PackBitmapIndex}es. + * Helper for constructing + * {@link org.eclipse.jgit.internal.storage.file.PackBitmapIndex}es. */ public class PackBitmapIndexBuilder extends BasePackBitmapIndex { private static final int MAX_XOR_OFFSET_SEARCH = 10; @@ -145,7 +146,11 @@ public class PackBitmapIndexBuilder extends BasePackBitmapIndex { } } - /** @return set of objects included in the pack. */ + /** + * Get set of objects included in the pack. + * + * @return set of objects included in the pack. + */ public ObjectIdOwnerMap<ObjectIdOwnerMap.Entry> getObjectSet() { ObjectIdOwnerMap<ObjectIdOwnerMap.Entry> r = new ObjectIdOwnerMap<>(); for (PositionEntry e : byOffset) { @@ -197,6 +202,7 @@ public class PackBitmapIndexBuilder extends BasePackBitmapIndex { byAddOrder.add(result); } + /** {@inheritDoc} */ @Override public EWAHCompressedBitmap ofObjectType( EWAHCompressedBitmap bitmap, int type) { @@ -213,6 +219,7 @@ public class PackBitmapIndexBuilder extends BasePackBitmapIndex { throw new IllegalArgumentException(); } + /** {@inheritDoc} */ @Override public int findPosition(AnyObjectId objectId) { PositionEntry entry = positionEntries.get(objectId); @@ -221,6 +228,7 @@ public class PackBitmapIndexBuilder extends BasePackBitmapIndex { return entry.offsetPosition; } + /** {@inheritDoc} */ @Override public ObjectId getObject(int position) throws IllegalArgumentException { ObjectId objectId = byOffset.get(position); @@ -229,48 +237,76 @@ public class PackBitmapIndexBuilder extends BasePackBitmapIndex { return objectId; } - /** @return the commit object bitmap. */ + /** + * Get the commit object bitmap. + * + * @return the commit object bitmap. + */ public EWAHCompressedBitmap getCommits() { return commits; } - /** @return the tree object bitmap. */ + /** + * Get the tree object bitmap. + * + * @return the tree object bitmap. + */ public EWAHCompressedBitmap getTrees() { return trees; } - /** @return the blob object bitmap. */ + /** + * Get the blob object bitmap. + * + * @return the blob object bitmap. + */ public EWAHCompressedBitmap getBlobs() { return blobs; } - /** @return the tag object bitmap. */ + /** + * Get the tag object bitmap. + * + * @return the tag object bitmap. + */ public EWAHCompressedBitmap getTags() { return tags; } - /** @return the index storage options. */ + /** + * Get the index storage options. + * + * @return the index storage options. + */ public int getOptions() { return PackBitmapIndexV1.OPT_FULL; } + /** {@inheritDoc} */ @Override public int getBitmapCount() { return getBitmaps().size(); } - /** Removes all the bitmaps entries added. */ + /** + * Remove all the bitmaps entries added. + */ public void clearBitmaps() { byAddOrder.clear(); getBitmaps().clear(); } + /** {@inheritDoc} */ @Override public int getObjectCount() { return byOffset.size(); } - /** @return an iterator over the xor compressed entries. */ + /** + * Get an iterator over the xor compressed entries. + * + * @return an iterator over the xor compressed entries. + */ public Iterable<StoredEntry> getCompressedBitmaps() { // Add order is from oldest to newest. The reverse add order is the // output order. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackBitmapIndexRemapper.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackBitmapIndexRemapper.java index 9a8c2752dd..c04c90f22f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackBitmapIndexRemapper.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackBitmapIndexRemapper.java @@ -116,27 +116,32 @@ public class PackBitmapIndexRemapper extends PackBitmapIndex oldPackIndex.getObject(pos)); } + /** {@inheritDoc} */ @Override public int findPosition(AnyObjectId objectId) { return newPackIndex.findPosition(objectId); } + /** {@inheritDoc} */ @Override public ObjectId getObject(int position) throws IllegalArgumentException { return newPackIndex.getObject(position); } + /** {@inheritDoc} */ @Override public int getObjectCount() { return newPackIndex.getObjectCount(); } + /** {@inheritDoc} */ @Override public EWAHCompressedBitmap ofObjectType( EWAHCompressedBitmap bitmap, int type) { return newPackIndex.ofObjectType(bitmap, type); } + /** {@inheritDoc} */ @Override public Iterator<Entry> iterator() { if (oldPackIndex == null) @@ -173,6 +178,7 @@ public class PackBitmapIndexRemapper extends PackBitmapIndex }; } + /** {@inheritDoc} */ @Override public EWAHCompressedBitmap getBitmap(AnyObjectId objectId) { EWAHCompressedBitmap bitmap = newPackIndex.getBitmap(objectId); @@ -214,6 +220,7 @@ public class PackBitmapIndexRemapper extends PackBitmapIndex } } + /** {@inheritDoc} */ @Override public int getBitmapCount() { // The count is only useful for the end index, not the remapper. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackBitmapIndexV1.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackBitmapIndexV1.java index 9d2c70b4c6..b172ca4afe 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackBitmapIndexV1.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackBitmapIndexV1.java @@ -175,6 +175,7 @@ class PackBitmapIndexV1 extends BasePackBitmapIndex { } } + /** {@inheritDoc} */ @Override public int findPosition(AnyObjectId objectId) { long offset = packIndex.findOffset(objectId); @@ -183,6 +184,7 @@ class PackBitmapIndexV1 extends BasePackBitmapIndex { return reverseIndex.findPostion(offset); } + /** {@inheritDoc} */ @Override public ObjectId getObject(int position) throws IllegalArgumentException { ObjectId objectId = reverseIndex.findObjectByPosition(position); @@ -191,11 +193,13 @@ class PackBitmapIndexV1 extends BasePackBitmapIndex { return objectId; } + /** {@inheritDoc} */ @Override public int getObjectCount() { return (int) packIndex.getObjectCount(); } + /** {@inheritDoc} */ @Override public EWAHCompressedBitmap ofObjectType( EWAHCompressedBitmap bitmap, int type) { @@ -212,11 +216,13 @@ class PackBitmapIndexV1 extends BasePackBitmapIndex { throw new IllegalArgumentException(); } + /** {@inheritDoc} */ @Override public int getBitmapCount() { return bitmaps.size(); } + /** {@inheritDoc} */ @Override public boolean equals(Object o) { // TODO(cranger): compare the pack checksum? @@ -225,6 +231,7 @@ class PackBitmapIndexV1 extends BasePackBitmapIndex { return false; } + /** {@inheritDoc} */ @Override public int hashCode() { return getPackIndex().hashCode(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackBitmapIndexWriterV1.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackBitmapIndexWriterV1.java index f8f02e95e3..d0c84da78b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackBitmapIndexWriterV1.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackBitmapIndexWriterV1.java @@ -89,7 +89,7 @@ public class PackBitmapIndexWriterV1 { * @param packDataChecksum * checksum signature of the entire pack data content. This is * traditionally the last 20 bytes of the pack file's own stream. - * @throws IOException + * @throws java.io.IOException * an error occurred while writing to the output stream, or this * index format cannot store the object data supplied. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackFile.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackFile.java index 0611d3e859..d5219c7a05 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackFile.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackFile.java @@ -201,20 +201,30 @@ public class PackFile implements Iterable<PackIndex.MutableEntry> { return loadedIdx; } - /** @return the File object which locates this pack on disk. */ + /** + * Get the File object which locates this pack on disk. + * + * @return the File object which locates this pack on disk. + */ public File getPackFile() { return packFile; } /** + * Get the index for this pack file. + * * @return the index for this pack file. - * @throws IOException + * @throws java.io.IOException */ public PackIndex getIndex() throws IOException { return idx(); } - /** @return name extracted from {@code pack-*.pack} pattern. */ + /** + * Get name extracted from {@code pack-*.pack} pattern. + * + * @return name extracted from {@code pack-*.pack} pattern. + */ public String getPackName() { String name = packName; if (name == null) { @@ -238,7 +248,7 @@ public class PackFile implements Iterable<PackIndex.MutableEntry> { * @param id * the object to look for. Must not be null. * @return true if the object is in this pack; false otherwise. - * @throws IOException + * @throws java.io.IOException * the index file cannot be loaded into memory. */ public boolean hasObject(final AnyObjectId id) throws IOException { @@ -292,6 +302,8 @@ public class PackFile implements Iterable<PackIndex.MutableEntry> { } /** + * {@inheritDoc} + * <p> * Provide iterator over entries in associated pack index, that should also * exist in this pack file. Objects returned by such iterator are mutable * during iteration. @@ -299,8 +311,6 @@ public class PackFile implements Iterable<PackIndex.MutableEntry> { * Iterator returns objects in SHA-1 lexicographical order. * </p> * - * @return iterator over entries of associated pack index - * * @see PackIndex#iterator() */ @Override @@ -505,19 +515,15 @@ public class PackFile implements Iterable<PackIndex.MutableEntry> { CorruptObjectException corruptObject = new CorruptObjectException( MessageFormat.format( JGitText.get().objectAtHasBadZlibStream, - Long.valueOf(src.offset), getPackFile())); - corruptObject.initCause(dataFormat); + Long.valueOf(src.offset), getPackFile()), + dataFormat); - StoredObjectRepresentationNotAvailableException gone; - gone = new StoredObjectRepresentationNotAvailableException(src); - gone.initCause(corruptObject); - throw gone; + throw new StoredObjectRepresentationNotAvailableException(src, + corruptObject); } catch (IOException ioError) { - StoredObjectRepresentationNotAvailableException gone; - gone = new StoredObjectRepresentationNotAvailableException(src); - gone.initCause(ioError); - throw gone; + throw new StoredObjectRepresentationNotAvailableException(src, + ioError); } if (quickCopy != null) { @@ -602,11 +608,8 @@ public class PackFile implements Iterable<PackIndex.MutableEntry> { try { doOpen(); } catch (IOException thisPackNotValid) { - StoredObjectRepresentationNotAvailableException gone; - - gone = new StoredObjectRepresentationNotAvailableException(otp); - gone.initCause(thisPackNotValid); - throw gone; + throw new StoredObjectRepresentationNotAvailableException(otp, + thisPackNotValid); } } } @@ -892,12 +895,11 @@ public class PackFile implements Iterable<PackIndex.MutableEntry> { return new ObjectLoader.SmallObject(type, data); } catch (DataFormatException dfe) { - CorruptObjectException coe = new CorruptObjectException( + throw new CorruptObjectException( MessageFormat.format( JGitText.get().objectAtHasBadZlibStream, - Long.valueOf(pos), getPackFile())); - coe.initCause(dfe); - throw coe; + Long.valueOf(pos), getPackFile()), + dfe); } } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndex.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndex.java index 2252778db0..acfd9c4719 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndex.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndex.java @@ -66,7 +66,8 @@ import org.eclipse.jgit.util.IO; import org.eclipse.jgit.util.NB; /** - * Access path to locate objects by {@link ObjectId} in a {@link PackFile}. + * Access path to locate objects by {@link org.eclipse.jgit.lib.ObjectId} in a + * {@link org.eclipse.jgit.internal.storage.file.PackFile}. * <p> * Indexes are strictly redundant information in that we can rebuild all of the * data held in the index file from the on disk representation of the pack file @@ -89,7 +90,7 @@ public abstract class PackIndex * @return access implementation for the requested file. * @throws FileNotFoundException * the file does not exist. - * @throws IOException + * @throws java.io.IOException * the file exists but could not be read due to security errors, * unrecognized data version, or unexpected data corruption. */ @@ -98,11 +99,10 @@ public abstract class PackIndex try { return read(fd); } catch (IOException ioe) { - final String path = idxFile.getAbsolutePath(); - final IOException err; - err = new IOException(MessageFormat.format(JGitText.get().unreadablePackIndex, path)); - err.initCause(ioe); - throw err; + throw new IOException(MessageFormat + .format(JGitText.get().unreadablePackIndex, + idxFile.getAbsolutePath()), + ioe); } finally { try { fd.close(); @@ -124,9 +124,9 @@ public abstract class PackIndex * buffered as some small IOs are performed against the stream. * The caller is responsible for closing the stream. * @return a copy of the index in-memory. - * @throws IOException + * @throws java.io.IOException * the stream cannot be read. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the stream does not contain a valid pack index. */ public static PackIndex read(InputStream fd) throws IOException, @@ -167,12 +167,15 @@ public abstract class PackIndex return findOffset(id) != -1; } + /** {@inheritDoc} */ @Override public boolean contains(AnyObjectId id) { return findOffset(id) != -1; } /** + * {@inheritDoc} + * <p> * Provide iterator that gives access to index entries. Note, that iterator * returns reference to mutable object, the same reference in each call - * for performance reason. If client needs immutable objects, it must copy @@ -180,8 +183,6 @@ public abstract class PackIndex * <p> * Iterator returns objects in SHA-1 lexicographical order. * </p> - * - * @return iterator over pack index entries */ @Override public abstract Iterator<MutableEntry> iterator(); @@ -218,7 +219,8 @@ public abstract class PackIndex * @param nthPosition * position within the traversal of {@link #iterator()} that the * caller needs the object for. The first returned - * {@link MutableEntry} is 0, the second is 1, etc. + * {@link org.eclipse.jgit.internal.storage.file.PackIndex.MutableEntry} + * is 0, the second is 1, etc. * @return the ObjectId for the corresponding entry. */ public abstract ObjectId getObjectId(long nthPosition); @@ -239,8 +241,10 @@ public abstract class PackIndex * @param nthPosition * unsigned 32 bit position within the traversal of * {@link #iterator()} that the caller needs the object for. The - * first returned {@link MutableEntry} is 0, the second is 1, - * etc. Positions past 2**31-1 are negative, but still valid. + * first returned + * {@link org.eclipse.jgit.internal.storage.file.PackIndex.MutableEntry} + * is 0, the second is 1, etc. Positions past 2**31-1 are + * negative, but still valid. * @return the ObjectId for the corresponding entry. */ public final ObjectId getObjectId(final int nthPosition) { @@ -282,9 +286,9 @@ public abstract class PackIndex * @param objId * id of object to look for * @return CRC32 checksum of specified object (at 32 less significant bits) - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * when requested ObjectId was not found in this index - * @throws UnsupportedOperationException + * @throws java.lang.UnsupportedOperationException * when this index doesn't support CRC32 checksum */ public abstract long findCRC32(AnyObjectId objId) @@ -308,7 +312,7 @@ public abstract class PackIndex * @param matchLimit * maximum number of results to return. At most this many * ObjectIds should be added to matches before returning. - * @throws IOException + * @throws java.io.IOException * the index cannot be read. */ public abstract void resolve(Set<ObjectId> matches, AbbreviatedObjectId id, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndexV1.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndexV1.java index 8a08456246..8ea31e4fa0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndexV1.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndexV1.java @@ -103,11 +103,13 @@ class PackIndexV1 extends PackIndex { IO.readFully(fd, packChecksum, 0, packChecksum.length); } + /** {@inheritDoc} */ @Override public long getObjectCount() { return objectCnt; } + /** {@inheritDoc} */ @Override public long getOffset64Count() { long n64 = 0; @@ -140,6 +142,7 @@ class PackIndexV1 extends PackIndex { return (int) (nthPosition - base); } + /** {@inheritDoc} */ @Override public ObjectId getObjectId(final long nthPosition) { final int levelOne = findLevelOne(nthPosition); @@ -156,6 +159,7 @@ class PackIndexV1 extends PackIndex { return NB.decodeUInt32(idxdata[levelOne], p); } + /** {@inheritDoc} */ @Override public long findOffset(final AnyObjectId objId) { final int levelOne = objId.getFirstByte(); @@ -182,21 +186,25 @@ class PackIndexV1 extends PackIndex { return -1; } + /** {@inheritDoc} */ @Override public long findCRC32(AnyObjectId objId) { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public boolean hasCRC32Support() { return false; } + /** {@inheritDoc} */ @Override public Iterator<MutableEntry> iterator() { return new IndexV1Iterator(); } + /** {@inheritDoc} */ @Override public void resolve(Set<ObjectId> matches, AbbreviatedObjectId id, int matchLimit) throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndexV2.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndexV2.java index 5c2986a04e..9f6201f9a7 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndexV2.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndexV2.java @@ -164,11 +164,13 @@ class PackIndexV2 extends PackIndex { IO.readFully(fd, packChecksum, 0, packChecksum.length); } + /** {@inheritDoc} */ @Override public long getObjectCount() { return objectCnt; } + /** {@inheritDoc} */ @Override public long getOffset64Count() { return offset64.length / 8; @@ -196,6 +198,7 @@ class PackIndexV2 extends PackIndex { return (int) (nthPosition - base); } + /** {@inheritDoc} */ @Override public ObjectId getObjectId(final long nthPosition) { final int levelOne = findLevelOne(nthPosition); @@ -204,6 +207,7 @@ class PackIndexV2 extends PackIndex { return ObjectId.fromRaw(names[levelOne], p4 + p); // p * 5 } + /** {@inheritDoc} */ @Override public long getOffset(final long nthPosition) { final int levelOne = findLevelOne(nthPosition); @@ -211,6 +215,7 @@ class PackIndexV2 extends PackIndex { return getOffset(levelOne, levelTwo); } + /** {@inheritDoc} */ @Override public long findOffset(final AnyObjectId objId) { final int levelOne = objId.getFirstByte(); @@ -227,6 +232,7 @@ class PackIndexV2 extends PackIndex { return p; } + /** {@inheritDoc} */ @Override public long findCRC32(AnyObjectId objId) throws MissingObjectException { final int levelOne = objId.getFirstByte(); @@ -236,16 +242,19 @@ class PackIndexV2 extends PackIndex { return NB.decodeUInt32(crc32[levelOne], levelTwo << 2); } + /** {@inheritDoc} */ @Override public boolean hasCRC32Support() { return true; } + /** {@inheritDoc} */ @Override public Iterator<MutableEntry> iterator() { return new EntriesIteratorV2(); } + /** {@inheritDoc} */ @Override public void resolve(Set<ObjectId> matches, AbbreviatedObjectId id, int matchLimit) throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndexWriter.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndexWriter.java index 51539112e7..b92f7b207c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndexWriter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndexWriter.java @@ -53,16 +53,16 @@ import java.util.List; import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.lib.Constants; -import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.transport.PackedObjectInfo; import org.eclipse.jgit.util.NB; /** - * Creates a table of contents to support random access by {@link PackFile}. + * Creates a table of contents to support random access by + * {@link org.eclipse.jgit.internal.storage.file.PackFile}. * <p> - * Pack index files (the <code>.idx</code> suffix in a pack file pair) - * provides random access to any object in the pack by associating an ObjectId - * to the byte offset within the pack where the object's data can be read. + * Pack index files (the <code>.idx</code> suffix in a pack file pair) provides + * random access to any object in the pack by associating an ObjectId to the + * byte offset within the pack where the object's data can be read. */ public abstract class PackIndexWriter { /** Magic constant indicating post-version 1 format. */ @@ -90,7 +90,7 @@ public abstract class PackIndexWriter { * will be examined until a format can be conclusively selected. * @return a new writer to output an index file of the requested format to * the supplied stream. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * no recognized pack index version can support the supplied * objects. This is likely a bug in the implementation. * @see #oldestPossibleFormat(List) @@ -117,7 +117,7 @@ public abstract class PackIndexWriter { * the objects the caller needs to store in the index. Entries * will be examined until a format can be conclusively selected. * @return the index format. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * no recognized pack index version can support the supplied * objects. This is likely a bug in the implementation. */ @@ -143,7 +143,7 @@ public abstract class PackIndexWriter { * this formatted version will be written. * @return a new writer to output an index file of the requested format to * the supplied stream. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * the version requested is not supported by this * implementation. */ @@ -195,12 +195,13 @@ public abstract class PackIndexWriter { * * @param toStore * sorted list of objects to store in the index. The caller must - * have previously sorted the list using {@link PackedObjectInfo}'s - * native {@link Comparable} implementation. + * have previously sorted the list using + * {@link org.eclipse.jgit.transport.PackedObjectInfo}'s native + * {@link java.lang.Comparable} implementation. * @param packDataChecksum * checksum signature of the entire pack data content. This is * traditionally the last 20 bytes of the pack file's own stream. - * @throws IOException + * @throws java.io.IOException * an error occurred while writing to the output stream, or this * index format cannot store the object data supplied. */ @@ -230,7 +231,7 @@ public abstract class PackIndexWriter { * the {@link #entries} collection may be iterated over more than once if * necessary. Implementors therefore have complete control over the data. * - * @throws IOException + * @throws java.io.IOException * an error occurred while writing to the output stream, or this * index format cannot store the object data supplied. */ @@ -246,7 +247,7 @@ public abstract class PackIndexWriter { * * @param version * version number of this index format being written. - * @throws IOException + * @throws java.io.IOException * an error occurred while writing to the output stream. */ protected void writeTOC(final int version) throws IOException { @@ -260,10 +261,10 @@ public abstract class PackIndexWriter { * <p> * The fan-out table is 4 KB in size, holding 256 32-bit unsigned integer * counts. Each count represents the number of objects within this index - * whose {@link ObjectId#getFirstByte()} matches the count's position in the - * fan-out table. + * whose {@link org.eclipse.jgit.lib.ObjectId#getFirstByte()} matches the + * count's position in the fan-out table. * - * @throws IOException + * @throws java.io.IOException * an error occurred while writing to the output stream. */ protected void writeFanOutTable() throws IOException { @@ -288,7 +289,7 @@ public abstract class PackIndexWriter { * the pack data checksum above.</li> * </ol> * - * @throws IOException + * @throws java.io.IOException * an error occurred while writing to the output stream. */ protected void writeChecksumFooter() throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndexWriterV1.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndexWriterV1.java index 6017b997ea..f220e7a6c6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndexWriterV1.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndexWriterV1.java @@ -68,6 +68,7 @@ class PackIndexWriterV1 extends PackIndexWriter { super(dst); } + /** {@inheritDoc} */ @Override protected void writeImpl() throws IOException { writeFanOutTable(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndexWriterV2.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndexWriterV2.java index 770549d693..a18ccaf9ea 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndexWriterV2.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackIndexWriterV2.java @@ -63,6 +63,7 @@ class PackIndexWriterV2 extends PackIndexWriter { super(dst); } + /** {@inheritDoc} */ @Override protected void writeImpl() throws IOException { writeTOC(2); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackInputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackInputStream.java index 962f765aae..8a4104aea8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackInputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackInputStream.java @@ -64,6 +64,7 @@ class PackInputStream extends InputStream { wc.pin(pack, pos); } + /** {@inheritDoc} */ @Override public int read(byte[] b, int off, int len) throws IOException { int n = wc.copy(pack, pos, b, off, len); @@ -71,6 +72,7 @@ class PackInputStream extends InputStream { return n; } + /** {@inheritDoc} */ @Override public int read() throws IOException { byte[] buf = new byte[1]; @@ -78,6 +80,7 @@ class PackInputStream extends InputStream { return n == 1 ? buf[0] & 0xff : -1; } + /** {@inheritDoc} */ @Override public void close() { wc.close(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackInserter.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackInserter.java index ff959e8c95..7ff269694b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackInserter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackInserter.java @@ -120,15 +120,20 @@ public class PackInserter extends ObjectInserter { } /** + * Whether to check if objects exist in the repo + * * @param check - * if false, will write out possibly-duplicate objects without - * first checking whether they exist in the repo; default is true. + * if {@code false}, will write out possibly-duplicate objects + * without first checking whether they exist in the repo; default + * is true. */ public void checkExisting(boolean check) { checkExisting = check; } /** + * Set compression level for zlib deflater. + * * @param compression * compression level for zlib deflater. */ @@ -140,6 +145,7 @@ public class PackInserter extends ObjectInserter { return buffer().length; } + /** {@inheritDoc} */ @Override public ObjectId insert(int type, byte[] data, int off, int len) throws IOException { @@ -158,6 +164,7 @@ public class PackInserter extends ObjectInserter { return endObject(id, offset); } + /** {@inheritDoc} */ @Override public ObjectId insert(int type, long len, InputStream in) throws IOException { @@ -231,16 +238,19 @@ public class PackInserter extends ObjectInserter { return 12; } + /** {@inheritDoc} */ @Override public PackParser newPackParser(InputStream in) { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public ObjectReader newReader() { return new Reader(); } + /** {@inheritDoc} */ @Override public void flush() throws IOException { if (tmpPack == null) { @@ -262,8 +272,7 @@ public class PackInserter extends ObjectInserter { File tmpIdx = idxFor(tmpPack); writePackIndex(tmpIdx, packHash, objectList); - File realPack = new File( - new File(db.getDirectory(), "pack"), //$NON-NLS-1$ + File realPack = new File(db.getPackDirectory(), "pack-" + computeName(objectList).name() + ".pack"); //$NON-NLS-1$ //$NON-NLS-2$ db.closeAllPackHandles(realPack); tmpPack.setReadOnly(); @@ -310,6 +319,7 @@ public class PackInserter extends ObjectInserter { return ObjectId.fromRaw(md.digest()); } + /** {@inheritDoc} */ @Override public void close() { try { @@ -613,13 +623,12 @@ public class PackInserter extends ObjectInserter { try { return packOut.inflate(zpos, sz); } catch (DataFormatException dfe) { - CorruptObjectException coe = new CorruptObjectException( + throw new CorruptObjectException( MessageFormat.format( JGitText.get().objectAtHasBadZlibStream, Long.valueOf(obj.getOffset()), - tmpPack.getAbsolutePath())); - coe.initCause(dfe); - throw coe; + tmpPack.getAbsolutePath()), + dfe); } } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackLock.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackLock.java index a433dec545..82f0da1c8c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackLock.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackLock.java @@ -50,7 +50,10 @@ import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.util.FS; import org.eclipse.jgit.util.FileUtils; -/** Keeps track of a {@link PackFile}'s associated <code>.keep</code> file. */ +/** + * Keeps track of a {@link org.eclipse.jgit.internal.storage.file.PackFile}'s + * associated <code>.keep</code> file. + */ public class PackLock { private final File keepFile; @@ -74,7 +77,7 @@ public class PackLock { * @param msg * message to store in the file. * @return true if the keep file was successfully written; false otherwise. - * @throws IOException + * @throws java.io.IOException * the keep file could not be written. */ public boolean lock(String msg) throws IOException { @@ -92,7 +95,7 @@ public class PackLock { /** * Remove the <code>.keep</code> file that holds this pack in place. * - * @throws IOException + * @throws java.io.IOException * if deletion of .keep file failed */ public void unlock() throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackReverseIndex.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackReverseIndex.java index fe9f700925..944af26dc5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackReverseIndex.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackReverseIndex.java @@ -174,7 +174,7 @@ public class PackReverseIndex { * offset). * @return offset of the next object in a pack or maxOffset if provided * offset was the last one. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * when there is no object with the provided offset. */ public long findNextOffset(final long offset, final long maxOffset) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackedBatchRefUpdate.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackedBatchRefUpdate.java index c1f5476496..200c63c17a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackedBatchRefUpdate.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/PackedBatchRefUpdate.java @@ -47,6 +47,7 @@ import static java.util.stream.Collectors.toList; import static org.eclipse.jgit.transport.ReceiveCommand.Result.LOCK_FAILURE; import static org.eclipse.jgit.transport.ReceiveCommand.Result.NOT_ATTEMPTED; import static org.eclipse.jgit.transport.ReceiveCommand.Result.REJECTED_NONFASTFORWARD; +import static org.eclipse.jgit.transport.ReceiveCommand.Result.REJECTED_OTHER_REASON; import java.io.IOException; import java.text.MessageFormat; @@ -124,6 +125,7 @@ class PackedBatchRefUpdate extends BatchRefUpdate { this.refdb = refdb; } + /** {@inheritDoc} */ @Override public void execute(RevWalk walk, ProgressMonitor monitor, List<String> options) throws IOException { @@ -142,6 +144,12 @@ class PackedBatchRefUpdate extends BatchRefUpdate { super.execute(walk, monitor, options); return; } + if (containsSymrefs(pending)) { + // packed-refs file cannot store symrefs + reject(pending.get(0), REJECTED_OTHER_REASON, + JGitText.get().atomicSymRefNotSupported, pending); + return; + } // Required implementation details copied from super.execute. if (!blockUntilTimestamps(MAX_WAIT)) { @@ -217,6 +225,15 @@ class PackedBatchRefUpdate extends BatchRefUpdate { writeReflog(pending); } + private static boolean containsSymrefs(List<ReceiveCommand> commands) { + for (ReceiveCommand cmd : commands) { + if (cmd.getOldSymref() != null || cmd.getNewSymref() != null) { + return true; + } + } + return false; + } + private boolean checkConflictingNames(List<ReceiveCommand> commands) throws IOException { Set<String> takenNames = new HashSet<>(); @@ -518,7 +535,12 @@ class PackedBatchRefUpdate extends BatchRefUpdate { private static void reject(ReceiveCommand cmd, ReceiveCommand.Result result, List<ReceiveCommand> commands) { - cmd.setResult(result); + reject(cmd, result, null, commands); + } + + private static void reject(ReceiveCommand cmd, ReceiveCommand.Result result, + String why, List<ReceiveCommand> commands) { + cmd.setResult(result, why); for (ReceiveCommand c2 : commands) { if (c2.getResult() == ReceiveCommand.Result.OK) { // Undo OK status so ReceiveCommand#abort aborts it. Assumes this method diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/RefDirectory.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/RefDirectory.java index d3d01aac60..9d51f4b1de 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/RefDirectory.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/RefDirectory.java @@ -112,14 +112,14 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** - * Traditional file system based {@link RefDatabase}. + * Traditional file system based {@link org.eclipse.jgit.lib.RefDatabase}. * <p> * This is the classical reference database representation for a Git repository. * References are stored in two formats: loose, and packed. * <p> * Loose references are stored as individual files within the {@code refs/} * directory. The file name matches the reference name and the file contents is - * the current {@link ObjectId} in string form. + * the current {@link org.eclipse.jgit.lib.ObjectId} in string form. * <p> * Packed references are stored in a single text file named {@code packed-refs}. * In the packed format, each reference is stored on its own line. This file @@ -244,6 +244,7 @@ public class RefDirectory extends RefDatabase { return new File(logsDir, name); } + /** {@inheritDoc} */ @Override public void create() throws IOException { FileUtils.mkdir(refsDir); @@ -252,6 +253,7 @@ public class RefDirectory extends RefDatabase { newLogWriter(false).create(); } + /** {@inheritDoc} */ @Override public void close() { clearReferences(); @@ -262,12 +264,14 @@ public class RefDirectory extends RefDatabase { packedRefs.set(NO_PACKED_REFS); } + /** {@inheritDoc} */ @Override public void refresh() { super.refresh(); clearReferences(); } + /** {@inheritDoc} */ @Override public boolean isNameConflicting(String name) throws IOException { RefList<Ref> packed = getPackedRefs(); @@ -313,6 +317,7 @@ public class RefDirectory extends RefDatabase { return loose; } + /** {@inheritDoc} */ @Override public Ref exactRef(String name) throws IOException { RefList<Ref> packed = getPackedRefs(); @@ -337,6 +342,7 @@ public class RefDirectory extends RefDatabase { return ref; } + /** {@inheritDoc} */ @Override public Ref getRef(final String needle) throws IOException { final RefList<Ref> packed = getPackedRefs(); @@ -361,6 +367,7 @@ public class RefDirectory extends RefDatabase { return ref; } + /** {@inheritDoc} */ @Override public Map<String, Ref> getRefs(String prefix) throws IOException { final RefList<LooseRef> oldLoose = looseRefs.get(); @@ -400,6 +407,7 @@ public class RefDirectory extends RefDatabase { return new RefMap(prefix, packed, upcast(loose), symbolic.toRefList()); } + /** {@inheritDoc} */ @Override public List<Ref> getAdditionalRefs() throws IOException { List<Ref> ret = new LinkedList<>(); @@ -534,6 +542,7 @@ public class RefDirectory extends RefDatabase { } } + /** {@inheritDoc} */ @Override public Ref peel(final Ref ref) throws IOException { final Ref leaf = ref.getLeaf(); @@ -585,6 +594,7 @@ public class RefDirectory extends RefDatabase { fireRefsChanged(); } + /** {@inheritDoc} */ @Override public RefDirectoryUpdate newUpdate(String name, boolean detach) throws IOException { @@ -604,6 +614,7 @@ public class RefDirectory extends RefDatabase { return refDirUpdate; } + /** {@inheritDoc} */ @Override public RefDirectoryRename newRename(String fromName, String toName) throws IOException { @@ -612,11 +623,13 @@ public class RefDirectory extends RefDatabase { return new RefDirectoryRename(from, to); } + /** {@inheritDoc} */ @Override public PackedBatchRefUpdate newBatchUpdate() { return new PackedBatchRefUpdate(this); } + /** {@inheritDoc} */ @Override public boolean performsAtomicTransactions() { return true; @@ -696,7 +709,7 @@ public class RefDirectory extends RefDatabase { * * @param refs * the refs to be added. Must be fully qualified. - * @throws IOException + * @throws java.io.IOException */ public void pack(List<String> refs) throws IOException { pack(refs, Collections.emptyMap()); @@ -1172,10 +1185,8 @@ public class RefDirectory extends RefDatabase { n--; String content = RawParseUtils.decode(buf, 0, n); - IOException ioException = new IOException(MessageFormat.format(JGitText.get().notARef, - name, content)); - ioException.initCause(notRef); - throw ioException; + throw new IOException(MessageFormat.format(JGitText.get().notARef, + name, content), notRef); } return new LooseUnpeeled(otherSnapshot, name, id); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/RefDirectoryRename.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/RefDirectoryRename.java index 09456c85c6..202e51f6c8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/RefDirectoryRename.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/RefDirectoryRename.java @@ -95,6 +95,7 @@ class RefDirectoryRename extends RefRename { refdb = src.getRefDatabase(); } + /** {@inheritDoc} */ @Override protected Result doRename() throws IOException { if (source.getRef().isSymbolic()) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/RefDirectoryUpdate.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/RefDirectoryUpdate.java index 7ab30faf10..4d6b245705 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/RefDirectoryUpdate.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/RefDirectoryUpdate.java @@ -65,16 +65,19 @@ class RefDirectoryUpdate extends RefUpdate { database = r; } + /** {@inheritDoc} */ @Override protected RefDirectory getRefDatabase() { return database; } + /** {@inheritDoc} */ @Override protected Repository getRepository() { return database.getRepository(); } + /** {@inheritDoc} */ @Override protected boolean tryLock(boolean deref) throws IOException { shouldDeref = deref; @@ -92,6 +95,7 @@ class RefDirectoryUpdate extends RefUpdate { } } + /** {@inheritDoc} */ @Override protected void unlock() { if (lock != null) { @@ -100,6 +104,7 @@ class RefDirectoryUpdate extends RefUpdate { } } + /** {@inheritDoc} */ @Override protected Result doUpdate(final Result status) throws IOException { WriteConfig wc = database.getRepository().getConfig() @@ -141,6 +146,7 @@ class RefDirectoryUpdate extends RefUpdate { } } + /** {@inheritDoc} */ @Override protected Result doDelete(final Result status) throws IOException { if (getRef().getStorage() != Ref.Storage.NEW) @@ -148,6 +154,7 @@ class RefDirectoryUpdate extends RefUpdate { return status; } + /** {@inheritDoc} */ @Override protected Result doLink(final String target) throws IOException { WriteConfig wc = database.getRepository().getConfig() diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ReflogEntryImpl.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ReflogEntryImpl.java index 8723a8b384..08a14b28d2 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ReflogEntryImpl.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ReflogEntryImpl.java @@ -93,6 +93,7 @@ public class ReflogEntryImpl implements Serializable, ReflogEntry { /* (non-Javadoc) * @see org.eclipse.jgit.internal.storage.file.ReflogEntry#getOldId() */ + /** {@inheritDoc} */ @Override public ObjectId getOldId() { return oldId; @@ -101,6 +102,7 @@ public class ReflogEntryImpl implements Serializable, ReflogEntry { /* (non-Javadoc) * @see org.eclipse.jgit.internal.storage.file.ReflogEntry#getNewId() */ + /** {@inheritDoc} */ @Override public ObjectId getNewId() { return newId; @@ -109,6 +111,7 @@ public class ReflogEntryImpl implements Serializable, ReflogEntry { /* (non-Javadoc) * @see org.eclipse.jgit.internal.storage.file.ReflogEntry#getWho() */ + /** {@inheritDoc} */ @Override public PersonIdent getWho() { return who; @@ -117,11 +120,13 @@ public class ReflogEntryImpl implements Serializable, ReflogEntry { /* (non-Javadoc) * @see org.eclipse.jgit.internal.storage.file.ReflogEntry#getComment() */ + /** {@inheritDoc} */ @Override public String getComment() { return comment; } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { @@ -132,6 +137,7 @@ public class ReflogEntryImpl implements Serializable, ReflogEntry { /* (non-Javadoc) * @see org.eclipse.jgit.internal.storage.file.ReflogEntry#parseCheckout() */ + /** {@inheritDoc} */ @Override public CheckoutEntry parseCheckout() { if (getComment().startsWith(CheckoutEntryImpl.CHECKOUT_MOVING_FROM)) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ReflogReaderImpl.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ReflogReaderImpl.java index c3702fecab..e95e1c203e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ReflogReaderImpl.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ReflogReaderImpl.java @@ -74,6 +74,7 @@ class ReflogReaderImpl implements ReflogReader { /* (non-Javadoc) * @see org.eclipse.jgit.internal.storage.file.ReflogReaader#getLastEntry() */ + /** {@inheritDoc} */ @Override public ReflogEntry getLastEntry() throws IOException { return getReverseEntry(0); @@ -82,6 +83,7 @@ class ReflogReaderImpl implements ReflogReader { /* (non-Javadoc) * @see org.eclipse.jgit.internal.storage.file.ReflogReaader#getReverseEntries() */ + /** {@inheritDoc} */ @Override public List<ReflogEntry> getReverseEntries() throws IOException { return getReverseEntries(Integer.MAX_VALUE); @@ -90,6 +92,7 @@ class ReflogReaderImpl implements ReflogReader { /* (non-Javadoc) * @see org.eclipse.jgit.internal.storage.file.ReflogReaader#getReverseEntry(int) */ + /** {@inheritDoc} */ @Override public ReflogEntry getReverseEntry(int number) throws IOException { if (number < 0) @@ -119,6 +122,7 @@ class ReflogReaderImpl implements ReflogReader { /* (non-Javadoc) * @see org.eclipse.jgit.internal.storage.file.ReflogReaader#getReverseEntries(int) */ + /** {@inheritDoc} */ @Override public List<ReflogEntry> getReverseEntries(int max) throws IOException { final byte[] log; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ReflogWriter.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ReflogWriter.java index f0bb9c519e..fd6b427935 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ReflogWriter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/ReflogWriter.java @@ -96,6 +96,8 @@ public class ReflogWriter { * Create writer for ref directory. * * @param refdb + * a {@link org.eclipse.jgit.internal.storage.file.RefDirectory} + * object. */ public ReflogWriter(RefDirectory refdb) { this(refdb, false); @@ -105,6 +107,8 @@ public class ReflogWriter { * Create writer for ref directory. * * @param refdb + * a {@link org.eclipse.jgit.internal.storage.file.RefDirectory} + * object. * @param forceWrite * true to write to disk all entries logged, false to respect the * repository's config and current log file status. @@ -117,7 +121,7 @@ public class ReflogWriter { /** * Create the log directories. * - * @throws IOException + * @throws java.io.IOException * @return this writer. */ public ReflogWriter create() throws IOException { @@ -132,9 +136,11 @@ public class ReflogWriter { * Write the given entry to the ref's log. * * @param refName + * a {@link java.lang.String} object. * @param entry + * a {@link org.eclipse.jgit.lib.ReflogEntry} object. * @return this writer - * @throws IOException + * @throws java.io.IOException */ public ReflogWriter log(String refName, ReflogEntry entry) throws IOException { @@ -146,12 +152,17 @@ public class ReflogWriter { * Write the given entry information to the ref's log * * @param refName + * ref name * @param oldId + * old object id * @param newId + * new object id * @param ident + * a {@link org.eclipse.jgit.lib.PersonIdent} * @param message + * reflog message * @return this writer - * @throws IOException + * @throws java.io.IOException */ public ReflogWriter log(String refName, ObjectId oldId, ObjectId newId, PersonIdent ident, String message) throws IOException { @@ -163,10 +174,13 @@ public class ReflogWriter { * Write the given ref update to the ref's log. * * @param update + * a {@link org.eclipse.jgit.lib.RefUpdate} * @param msg + * reflog message * @param deref + * whether to dereference symbolic refs * @return this writer - * @throws IOException + * @throws java.io.IOException */ public ReflogWriter log(RefUpdate update, String msg, boolean deref) throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/SimpleDataInput.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/SimpleDataInput.java index 452636dcab..3b815b5c17 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/SimpleDataInput.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/SimpleDataInput.java @@ -64,83 +64,105 @@ class SimpleDataInput implements DataInput { this.fd = fd; } + /** {@inheritDoc} */ @Override public int readInt() throws IOException { readFully(buf, 0, 4); return NB.decodeInt32(buf, 0); } + /** {@inheritDoc} */ @Override public long readLong() throws IOException { readFully(buf, 0, 8); return NB.decodeInt64(buf, 0); } + /** + * Read unsigned int + * + * @return a long. + * @throws java.io.IOException + * if any. + */ public long readUnsignedInt() throws IOException { readFully(buf, 0, 4); return NB.decodeUInt32(buf, 0); } + /** {@inheritDoc} */ @Override public void readFully(byte[] b) throws IOException { readFully(b, 0, b.length); } + /** {@inheritDoc} */ @Override public void readFully(byte[] b, int off, int len) throws IOException { IO.readFully(fd, b, off, len); } + /** {@inheritDoc} */ @Override public int skipBytes(int n) throws IOException { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public boolean readBoolean() throws IOException { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public byte readByte() throws IOException { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public int readUnsignedByte() throws IOException { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public short readShort() throws IOException { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public int readUnsignedShort() throws IOException { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public char readChar() throws IOException { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public float readFloat() throws IOException { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public double readDouble() throws IOException { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public String readLine() throws IOException { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public String readUTF() throws IOException { throw new UnsupportedOperationException(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/SimpleDataOutput.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/SimpleDataOutput.java index 5fe0429246..7825b841e9 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/SimpleDataOutput.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/SimpleDataOutput.java @@ -64,74 +64,88 @@ class SimpleDataOutput implements DataOutput { this.fd = fd; } + /** {@inheritDoc} */ @Override public void writeShort(int v) throws IOException { NB.encodeInt16(buf, 0, v); fd.write(buf, 0, 2); } + /** {@inheritDoc} */ @Override public void writeInt(int v) throws IOException { NB.encodeInt32(buf, 0, v); fd.write(buf, 0, 4); } + /** {@inheritDoc} */ @Override public void writeLong(long v) throws IOException { NB.encodeInt64(buf, 0, v); fd.write(buf, 0, 8); } + /** {@inheritDoc} */ @Override public void write(int b) throws IOException { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public void write(byte[] b) throws IOException { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public void write(byte[] b, int off, int len) throws IOException { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public void writeBoolean(boolean v) throws IOException { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public void writeByte(int v) throws IOException { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public void writeChar(int v) throws IOException { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public void writeFloat(float v) throws IOException { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public void writeDouble(double v) throws IOException { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public void writeBytes(String s) throws IOException { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public void writeChars(String s) throws IOException { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public void writeUTF(String s) throws IOException { throw new UnsupportedOperationException(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/UnpackedObject.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/UnpackedObject.java index a02743720d..adb05e4d99 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/UnpackedObject.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/UnpackedObject.java @@ -86,7 +86,7 @@ public class UnpackedObject { * expected ObjectId of the object, used only for error reporting * in exceptions. * @return loader to read the inflated contents. - * @throws IOException + * @throws java.io.IOException * the object cannot be parsed. */ public static ObjectLoader parse(byte[] raw, AnyObjectId id) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/WindowCache.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/WindowCache.java index 61960068be..213cacab8c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/WindowCache.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/WindowCache.java @@ -57,7 +57,8 @@ import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.storage.file.WindowCacheConfig; /** - * Caches slices of a {@link PackFile} in memory for faster read access. + * Caches slices of a {@link org.eclipse.jgit.internal.storage.file.PackFile} in + * memory for faster read access. * <p> * The WindowCache serves as a Java based "buffer cache", loading segments of a * PackFile into the JVM heap prior to use. As JGit often wants to do reads of @@ -111,8 +112,9 @@ import org.eclipse.jgit.storage.file.WindowCacheConfig; * {@link #createRef(PackFile, long, ByteWindow)} methods, and matching * decrements during {@link #clear(Ref)}. Implementors may need to override * {@link #createRef(PackFile, long, ByteWindow)} in order to embed additional - * accounting information into an implementation specific {@link Ref} subclass, - * as the cached entity may have already been evicted by the JRE's garbage + * accounting information into an implementation specific + * {@link org.eclipse.jgit.internal.storage.file.WindowCache.Ref} subclass, as + * the cached entity may have already been evicted by the JRE's garbage * collector. * <p> * To maintain higher concurrency workloads, during eviction only one thread @@ -150,7 +152,7 @@ public class WindowCache { * @deprecated use {@code cfg.install()} to avoid internal reference. * @param cfg * the new window cache configuration. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * the cache configuration contains one or more invalid * settings, usually too low of a limit. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/WindowCursor.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/WindowCursor.java index 83b236ed96..569bfe895f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/WindowCursor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/file/WindowCursor.java @@ -110,11 +110,13 @@ final class WindowCursor extends ObjectReader implements ObjectReuseAsIs { return baseCache; } + /** {@inheritDoc} */ @Override public ObjectReader newReader() { return new WindowCursor(db); } + /** {@inheritDoc} */ @Override public BitmapIndex getBitmapIndex() throws IOException { for (PackFile pack : db.getPacks()) { @@ -125,6 +127,7 @@ final class WindowCursor extends ObjectReader implements ObjectReuseAsIs { return null; } + /** {@inheritDoc} */ @Override public Collection<CachedPack> getCachedPacksAndUpdate( BitmapBuilder needBitmap) throws IOException { @@ -137,6 +140,7 @@ final class WindowCursor extends ObjectReader implements ObjectReuseAsIs { return Collections.emptyList(); } + /** {@inheritDoc} */ @Override public Collection<ObjectId> resolve(AbbreviatedObjectId id) throws IOException { @@ -147,11 +151,13 @@ final class WindowCursor extends ObjectReader implements ObjectReuseAsIs { return matches; } + /** {@inheritDoc} */ @Override public boolean has(AnyObjectId objectId) throws IOException { return db.has(objectId); } + /** {@inheritDoc} */ @Override public ObjectLoader open(AnyObjectId objectId, int typeHint) throws MissingObjectException, IncorrectObjectTypeException, @@ -168,11 +174,13 @@ final class WindowCursor extends ObjectReader implements ObjectReuseAsIs { return ldr; } + /** {@inheritDoc} */ @Override public Set<ObjectId> getShallowCommits() throws IOException { return db.getShallowCommits(); } + /** {@inheritDoc} */ @Override public long getObjectSize(AnyObjectId objectId, int typeHint) throws MissingObjectException, IncorrectObjectTypeException, @@ -187,11 +195,13 @@ final class WindowCursor extends ObjectReader implements ObjectReuseAsIs { return sz; } + /** {@inheritDoc} */ @Override public LocalObjectToPack newObjectToPack(AnyObjectId objectId, int type) { return new LocalObjectToPack(objectId, type); } + /** {@inheritDoc} */ @Override public void selectObjectRepresentation(PackWriter packer, ProgressMonitor monitor, Iterable<ObjectToPack> objects) @@ -202,6 +212,7 @@ final class WindowCursor extends ObjectReader implements ObjectReuseAsIs { } } + /** {@inheritDoc} */ @Override public void copyObjectAsIs(PackOutputStream out, ObjectToPack otp, boolean validate) throws IOException, @@ -210,6 +221,7 @@ final class WindowCursor extends ObjectReader implements ObjectReuseAsIs { src.pack.copyAsIs(out, src, validate, this); } + /** {@inheritDoc} */ @Override public void writeObjects(PackOutputStream out, List<ObjectToPack> list) throws IOException { @@ -253,6 +265,7 @@ final class WindowCursor extends ObjectReader implements ObjectReuseAsIs { return cnt - need; } + /** {@inheritDoc} */ @Override public void copyPackAsIs(PackOutputStream out, CachedPack pack) throws IOException { @@ -348,13 +361,18 @@ final class WindowCursor extends ObjectReader implements ObjectReuseAsIs { } } + /** {@inheritDoc} */ @Override @Nullable public ObjectInserter getCreatedFromInserter() { return createdFromInserter; } - /** Release the current window cursor. */ + /** + * {@inheritDoc} + * <p> + * Release the current window cursor. + */ @Override public void close() { window = null; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/io/BlockSource.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/io/BlockSource.java index 0a5f9c1a72..56772983ba 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/io/BlockSource.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/io/BlockSource.java @@ -153,7 +153,7 @@ public abstract class BlockSource implements AutoCloseable { * @param blockSize * size to read. * @return buffer containing the block content. - * @throws IOException + * @throws java.io.IOException * if block cannot be read. */ public abstract ByteBuffer read(long position, int blockSize) @@ -163,7 +163,7 @@ public abstract class BlockSource implements AutoCloseable { * Determine the size of the file. * * @return total number of bytes in the file. - * @throws IOException + * @throws java.io.IOException * if size cannot be obtained. */ public abstract long size() throws IOException; @@ -180,6 +180,7 @@ public abstract class BlockSource implements AutoCloseable { // Do nothing by default. } + /** {@inheritDoc} */ @Override public abstract void close(); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/CachedPack.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/CachedPack.java index 6498ea35d0..81f40558ef 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/CachedPack.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/CachedPack.java @@ -45,13 +45,17 @@ package org.eclipse.jgit.internal.storage.pack; import java.io.IOException; -/** Describes a pack file {@link ObjectReuseAsIs} can append onto a stream. */ +/** + * Describes a pack file + * {@link org.eclipse.jgit.internal.storage.pack.ObjectReuseAsIs} can append + * onto a stream. + */ public abstract class CachedPack { /** * Get the number of objects in this pack. * * @return the total object count for the pack. - * @throws IOException + * @throws java.io.IOException * if the object count cannot be read. */ public abstract long getObjectCount() throws IOException; @@ -70,7 +74,7 @@ public abstract class CachedPack { * * @return the number of deltas; 0 if the number is not known or there are * no deltas. - * @throws IOException + * @throws java.io.IOException * if the delta count cannot be read. */ public long getDeltaCount() throws IOException { @@ -88,15 +92,16 @@ public abstract class CachedPack { * only and using its internal state to decide if this object is within this * pack. Implementors should ensure a representation from this cached pack * is tested as part of - * {@link ObjectReuseAsIs#selectObjectRepresentation(PackWriter, org.eclipse.jgit.lib.ProgressMonitor, Iterable)} + * {@link org.eclipse.jgit.internal.storage.pack.ObjectReuseAsIs#selectObjectRepresentation(PackWriter, org.eclipse.jgit.lib.ProgressMonitor, Iterable)} * , ensuring this method would eventually return true if the object would * be included by this cached pack. * * @param obj * the object being packed. Can be used as an ObjectId. * @param rep - * representation from the {@link ObjectReuseAsIs} instance that - * originally supplied this CachedPack. + * representation from the + * {@link org.eclipse.jgit.internal.storage.pack.ObjectReuseAsIs} + * instance that originally supplied this CachedPack. * @return true if this pack contains this object. */ public abstract boolean hasObject(ObjectToPack obj, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaEncoder.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaEncoder.java index cccbc5903e..343faf4df4 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaEncoder.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaEncoder.java @@ -48,7 +48,10 @@ import java.io.OutputStream; import org.eclipse.jgit.lib.Constants; -/** Encodes an instruction stream for {@link BinaryDelta}. */ +/** + * Encodes an instruction stream for + * {@link org.eclipse.jgit.internal.storage.pack.BinaryDelta}. + */ public class DeltaEncoder { /** * Maximum number of bytes to be copied in pack v2 format. @@ -91,7 +94,7 @@ public class DeltaEncoder { * @param resultSize * size of the resulting object, after applying this instruction * stream to the base object, in bytes. - * @throws IOException + * @throws java.io.IOException * the output buffer cannot store the instruction stream's * header with the size fields. */ @@ -114,7 +117,7 @@ public class DeltaEncoder { * maximum number of bytes to write to the out buffer declaring * the stream is over limit and should be discarded. May be 0 to * specify an infinite limit. - * @throws IOException + * @throws java.io.IOException * the output buffer cannot store the instruction stream's * header with the size fields. */ @@ -138,7 +141,11 @@ public class DeltaEncoder { out.write(buf, 0, p); } - /** @return current size of the delta stream, in bytes. */ + /** + * Get current size of the delta stream, in bytes. + * + * @return current size of the delta stream, in bytes. + */ public int getSize() { return size; } @@ -150,7 +157,7 @@ public class DeltaEncoder { * the string to insert. * @return true if the insert fits within the limit; false if the insert * would cause the instruction stream to exceed the limit. - * @throws IOException + * @throws java.io.IOException * the instruction buffer can't store the instructions. */ public boolean insert(String text) throws IOException { @@ -164,7 +171,7 @@ public class DeltaEncoder { * the binary to insert. * @return true if the insert fits within the limit; false if the insert * would cause the instruction stream to exceed the limit. - * @throws IOException + * @throws java.io.IOException * the instruction buffer can't store the instructions. */ public boolean insert(byte[] text) throws IOException { @@ -182,7 +189,7 @@ public class DeltaEncoder { * number of bytes to insert. * @return true if the insert fits within the limit; false if the insert * would cause the instruction stream to exceed the limit. - * @throws IOException + * @throws java.io.IOException * the instruction buffer can't store the instructions. */ public boolean insert(byte[] text, int off, int cnt) @@ -217,7 +224,7 @@ public class DeltaEncoder { * number of bytes to copy. * @return true if the copy fits within the limit; false if the copy * would cause the instruction stream to exceed the limit. - * @throws IOException + * @throws java.io.IOException * the instruction buffer cannot store the instructions. */ public boolean copy(long offset, int cnt) throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaIndex.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaIndex.java index 0f22de08e0..6f3e2accad 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaIndex.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaIndex.java @@ -51,8 +51,9 @@ import java.io.OutputStream; * <p> * The index can be passed a result buffer, and output an instruction sequence * that transforms the source buffer used by the index into the result buffer. - * The instruction sequence can be executed by {@link BinaryDelta} to recreate - * the result buffer. + * The instruction sequence can be executed by + * {@link org.eclipse.jgit.internal.storage.pack.BinaryDelta} to recreate the + * result buffer. * <p> * An index stores the entire contents of the source buffer, but also a table of * block identities mapped to locations where the block appears in the source @@ -191,7 +192,11 @@ public class DeltaIndex { } } - /** @return size of the source buffer this index has scanned. */ + /** + * Get size of the source buffer this index has scanned. + * + * @return size of the source buffer this index has scanned. + */ public long getSourceSize() { return src.length; } @@ -244,7 +249,7 @@ public class DeltaIndex { * the desired result buffer. The generated instructions will * recreate this buffer when applied to the source buffer stored * within this index. - * @throws IOException + * @throws java.io.IOException * the output stream refused to write the instructions. */ public void encode(OutputStream out, byte[] res) throws IOException { @@ -274,7 +279,7 @@ public class DeltaIndex { * @return true if the delta is smaller than deltaSizeLimit; false if the * encoder aborted because the encoded delta instructions would be * longer than deltaSizeLimit bytes. - * @throws IOException + * @throws java.io.IOException * the output stream refused to write the instructions. */ public boolean encode(OutputStream out, byte[] res, int deltaSizeLimit) @@ -421,6 +426,7 @@ public class DeltaIndex { return start - resPtr; } + /** {@inheritDoc} */ @Override @SuppressWarnings("nls") public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaTask.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaTask.java index 0c4e4448d8..0347644324 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaTask.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/DeltaTask.java @@ -292,6 +292,7 @@ final class DeltaTask implements Callable<Object> { slices.add(s); } + /** {@inheritDoc} */ @Override public Object call() throws Exception { or = block.templateReader.newReader(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/ObjectReuseAsIs.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/ObjectReuseAsIs.java index 2e5d59960e..f759e23ef4 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/ObjectReuseAsIs.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/ObjectReuseAsIs.java @@ -51,26 +51,27 @@ import org.eclipse.jgit.errors.MissingObjectException; import org.eclipse.jgit.errors.StoredObjectRepresentationNotAvailableException; import org.eclipse.jgit.lib.AnyObjectId; import org.eclipse.jgit.lib.BitmapIndex.BitmapBuilder; -import org.eclipse.jgit.lib.ObjectReader; import org.eclipse.jgit.lib.ProgressMonitor; /** - * Extension of {@link ObjectReader} that supports reusing objects in packs. + * Extension of {@link org.eclipse.jgit.lib.ObjectReader} that supports reusing + * objects in packs. * <p> * {@code ObjectReader} implementations may also optionally implement this - * interface to support {@link PackWriter} with a means of copying an object - * that is already in pack encoding format directly into the output stream, - * without incurring decompression and recompression overheads. + * interface to support + * {@link org.eclipse.jgit.internal.storage.pack.PackWriter} with a means of + * copying an object that is already in pack encoding format directly into the + * output stream, without incurring decompression and recompression overheads. */ public interface ObjectReuseAsIs { /** * Allocate a new {@code PackWriter} state structure for an object. * <p> - * {@link PackWriter} allocates these objects to keep track of the - * per-object state, and how to load the objects efficiently into the - * generated stream. Implementers may subclass this type with additional - * object state, such as to remember what file and offset contains the - * object's pack encoded data. + * {@link org.eclipse.jgit.internal.storage.pack.PackWriter} allocates these + * objects to keep track of the per-object state, and how to load the + * objects efficiently into the generated stream. Implementers may subclass + * this type with additional object state, such as to remember what file and + * offset contains the object's pack encoded data. * * @param objectId * the id of the object that will be packed. @@ -85,15 +86,16 @@ public interface ObjectReuseAsIs { * <p> * Implementations should iterate through all available representations of * an object, and pass them in turn to the PackWriter though - * {@link PackWriter#select(ObjectToPack, StoredObjectRepresentation)} so - * the writer can select the most suitable representation to reuse into the - * output stream. + * {@link org.eclipse.jgit.internal.storage.pack.PackWriter#select(ObjectToPack, StoredObjectRepresentation)} + * so the writer can select the most suitable representation to reuse into + * the output stream. * <p> - * If the implementation returns CachedPack from {@link #getCachedPacksAndUpdate(BitmapBuilder)} - * it must consider the representation of any object that is stored in any - * of the offered CachedPacks. PackWriter relies on this behavior to prune - * duplicate objects out of the pack stream when it selects a CachedPack and - * the object was also reached through the thin-pack enumeration. + * If the implementation returns CachedPack from + * {@link #getCachedPacksAndUpdate(BitmapBuilder)} it must consider the + * representation of any object that is stored in any of the offered + * CachedPacks. PackWriter relies on this behavior to prune duplicate + * objects out of the pack stream when it selects a CachedPack and the + * object was also reached through the thin-pack enumeration. * <p> * The implementation may choose to consider multiple objects at once on * concurrent threads, but must evaluate all representations of an object @@ -106,10 +108,10 @@ public interface ObjectReuseAsIs { * once for each item in the iteration when selection is done. * @param objects * the objects that are being packed. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * there is no representation available for the object, as it is * no longer in the repository. Packing will abort. - * @throws IOException + * @throws java.io.IOException * the repository cannot be accessed. Packing will abort. */ public void selectObjectRepresentation(PackWriter packer, @@ -136,7 +138,9 @@ public interface ObjectReuseAsIs { * format to reach a delta base that is later in the stream. It may also * reduce data locality for the reader, slowing down data access. * - * Invoking {@link PackOutputStream#writeObject(ObjectToPack)} will cause + * Invoking + * {@link org.eclipse.jgit.internal.storage.pack.PackOutputStream#writeObject(ObjectToPack)} + * will cause * {@link #copyObjectAsIs(PackOutputStream, ObjectToPack, boolean)} to be * invoked recursively on {@code this} if the current object is scheduled * for reuse. @@ -147,7 +151,7 @@ public interface ObjectReuseAsIs { * the list of objects to write. Objects should be written in * approximately this order. Implementors may resort the list * elements in-place during writing if desired. - * @throws IOException + * @throws java.io.IOException * the stream cannot be written to, or one or more required * objects cannot be accessed from the object database. */ @@ -186,13 +190,13 @@ public interface ObjectReuseAsIs { * corrupt before being reused. If false, validation may be * skipped as it will be performed elsewhere in the processing * pipeline. - * @throws StoredObjectRepresentationNotAvailableException + * @throws org.eclipse.jgit.errors.StoredObjectRepresentationNotAvailableException * the previously selected representation is no longer * available. If thrown before {@code out.writeHeader} the pack * writer will try to find another representation, and write * that one instead. If throw after {@code out.writeHeader}, * packing will abort. - * @throws IOException + * @throws java.io.IOException * the stream's write method threw an exception. Packing will * abort. */ @@ -209,7 +213,7 @@ public interface ObjectReuseAsIs { * stream to append the pack onto. * @param pack * the cached pack to send. - * @throws IOException + * @throws java.io.IOException * the pack cannot be read, or stream did not accept a write. */ public abstract void copyPackAsIs(PackOutputStream out, CachedPack pack) @@ -225,7 +229,7 @@ public interface ObjectReuseAsIs { * @param needBitmap * the bitmap that contains all of the objects the client wants. * @return the available cached packs. - * @throws IOException + * @throws java.io.IOException * the cached packs cannot be listed from the repository. * Callers may choose to ignore this and continue as-if there * were no cached packs. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/ObjectToPack.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/ObjectToPack.java index bc7a603c4a..e8c75107b9 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/ObjectToPack.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/ObjectToPack.java @@ -50,7 +50,8 @@ import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.transport.PackedObjectInfo; /** - * Per-object state used by {@link PackWriter}. + * Per-object state used by + * {@link org.eclipse.jgit.internal.storage.pack.PackWriter}. * <p> * {@code PackWriter} uses this class to track the things it needs to include in * the newly generated pack file, and how to efficiently obtain the raw data for @@ -108,19 +109,25 @@ public class ObjectToPack extends PackedObjectInfo { } /** + * Get delta base object id if object is going to be packed in delta + * representation + * * @return delta base object id if object is going to be packed in delta - * representation; null otherwise - if going to be packed as a - * whole object. + * representation; null otherwise - if going to be packed as a whole + * object. */ public final ObjectId getDeltaBaseId() { return deltaBase; } /** + * Get delta base object to pack if object is going to be packed in delta + * representation and delta is specified as object to pack + * * @return delta base object to pack if object is going to be packed in - * delta representation and delta is specified as object to - * pack; null otherwise - if going to be packed as a whole - * object or delta base is specified only as id. + * delta representation and delta is specified as object to pack; + * null otherwise - if going to be packed as a whole object or delta + * base is specified only as id. */ public final ObjectToPack getDeltaBase() { if (deltaBase instanceof ObjectToPack) @@ -164,8 +171,9 @@ public class ObjectToPack extends PackedObjectInfo { } /** - * @return true if object is going to be written as delta; false - * otherwise. + * Whether object is going to be written as delta + * + * @return true if object is going to be written as delta; false otherwise. */ public final boolean isDeltaRepresentation() { return deltaBase != null; @@ -181,7 +189,7 @@ public class ObjectToPack extends PackedObjectInfo { return 1 < getOffset(); // markWantWrite sets 1. } - /** @return the type of this object. */ + /** {@inheritDoc} */ @Override public final int getType() { return (flags >> TYPE_SHIFT) & 0x7; @@ -216,6 +224,9 @@ public class ObjectToPack extends PackedObjectInfo { } /** + * Whether an existing representation was selected to be reused as-is into + * the pack stream. + * * @return true if an existing representation was selected to be reused * as-is into the pack stream. */ @@ -266,7 +277,11 @@ public class ObjectToPack extends PackedObjectInfo { flags &= ~DELTA_ATTEMPTED; } - /** @return the extended flags on this object, in the range [0x0, 0xf]. */ + /** + * Get the extended flags on this object, in the range [0x0, 0xf]. + * + * @return the extended flags on this object, in the range [0x0, 0xf]. + */ protected final int getExtendedFlags() { return (flags >>> EXT_SHIFT) & EXT_MASK; } @@ -363,9 +378,10 @@ public class ObjectToPack extends PackedObjectInfo { * Remember a specific representation for reuse at a later time. * <p> * Implementers should remember the representation chosen, so it can be - * reused at a later time. {@link PackWriter} may invoke this method - * multiple times for the same object, each time saving the current best - * representation found. + * reused at a later time. + * {@link org.eclipse.jgit.internal.storage.pack.PackWriter} may invoke this + * method multiple times for the same object, each time saving the current + * best representation found. * * @param ref * the object representation. @@ -374,6 +390,7 @@ public class ObjectToPack extends PackedObjectInfo { // Empty by default. } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackExt.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackExt.java index e8bbf78a15..292fd368cd 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackExt.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackExt.java @@ -43,7 +43,9 @@ package org.eclipse.jgit.internal.storage.pack; -/** A pack file extension. */ +/** + * A pack file extension. + */ public class PackExt { private static volatile PackExt[] VALUES = new PackExt[] {}; @@ -62,7 +64,11 @@ public class PackExt { /** A reftable file. */ public static final PackExt REFTABLE = newPackExt("ref"); //$NON-NLS-1$ - /** @return all of the PackExt values. */ + /** + * Get all of the PackExt values. + * + * @return all of the PackExt values. + */ public static PackExt[] values() { return VALUES; } @@ -102,21 +108,34 @@ public class PackExt { this.pos = pos; } - /** @return the file extension. */ + /** + * Get the file extension. + * + * @return the file extension. + */ public String getExtension() { return ext; } - /** @return the position of the extension in the values array. */ + /** + * Get the position of the extension in the values array. + * + * @return the position of the extension in the values array. + */ public int getPosition() { return pos; } - /** @return the bit mask of the extension e.g {@code 1 << getPosition()}. */ + /** + * Get the bit mask of the extension e.g {@code 1 << getPosition()}. + * + * @return the bit mask of the extension e.g {@code 1 << getPosition()}. + */ public int getBit() { return 1 << getPosition(); } + /** {@inheritDoc} */ @Override public String toString() { return String.format("PackExt[%s, bit=0x%s]", getExtension(), //$NON-NLS-1$ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackOutputStream.java index 59166e6206..fd9c1a00d3 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackOutputStream.java @@ -57,7 +57,10 @@ import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.lib.ProgressMonitor; import org.eclipse.jgit.util.NB; -/** Custom output stream to support {@link PackWriter}. */ +/** + * Custom output stream to support + * {@link org.eclipse.jgit.internal.storage.pack.PackWriter}. + */ public final class PackOutputStream extends OutputStream { private static final int BYTES_TO_WRITE_BEFORE_CANCEL_CHECK = 128 * 1024; @@ -84,7 +87,8 @@ public final class PackOutputStream extends OutputStream { * <p> * This constructor is exposed to support debugging the JGit library only. * Application or storage level code should not create a PackOutputStream, - * instead use {@link PackWriter}, and let the writer create the stream. + * instead use {@link org.eclipse.jgit.internal.storage.pack.PackWriter}, + * and let the writer create the stream. * * @param writeMonitor * monitor to update on object output progress. @@ -101,6 +105,7 @@ public final class PackOutputStream extends OutputStream { this.checkCancelAt = BYTES_TO_WRITE_BEFORE_CANCEL_CHECK; } + /** {@inheritDoc} */ @Override public final void write(final int b) throws IOException { count++; @@ -108,6 +113,7 @@ public final class PackOutputStream extends OutputStream { md.update((byte) b); } + /** {@inheritDoc} */ @Override public final void write(final byte[] b, int off, int len) throws IOException { @@ -131,6 +137,7 @@ public final class PackOutputStream extends OutputStream { } } + /** {@inheritDoc} */ @Override public void flush() throws IOException { out.flush(); @@ -154,7 +161,7 @@ public final class PackOutputStream extends OutputStream { * * @param otp * the object to write. - * @throws IOException + * @throws java.io.IOException * the object cannot be read from the object reader, or the * output stream is no longer accepting output. Caller must * examine the type of exception and possibly its message to @@ -177,7 +184,7 @@ public final class PackOutputStream extends OutputStream { * in whole object format, this is the same as the object size. * For an object that is in a delta format, this is the size of * the inflated delta instruction stream. - * @throws IOException + * @throws java.io.IOException * the underlying stream refused to accept the header. */ public final void writeHeader(ObjectToPack otp, long rawLength) @@ -224,7 +231,11 @@ public final class PackOutputStream extends OutputStream { return n; } - /** @return a temporary buffer writers can use to copy data with. */ + /** + * Get a temporary buffer writers can use to copy data with. + * + * @return a temporary buffer writers can use to copy data with. + */ public final byte[] getCopyBuffer() { return copyBuffer; } @@ -233,7 +244,11 @@ public final class PackOutputStream extends OutputStream { writeMonitor.update(1); } - /** @return total number of bytes written since stream start. */ + /** + * Get total number of bytes written since stream start. + * + * @return total number of bytes written since stream start. + */ public final long length() { return count; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackWriter.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackWriter.java index 7271560e3c..71d10ac45d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackWriter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackWriter.java @@ -107,6 +107,7 @@ import org.eclipse.jgit.lib.ProgressMonitor; import org.eclipse.jgit.lib.Repository; import org.eclipse.jgit.lib.ThreadSafeProgressMonitor; import org.eclipse.jgit.revwalk.AsyncRevObjectQueue; +import org.eclipse.jgit.revwalk.BitmapWalker; import org.eclipse.jgit.revwalk.DepthWalk; import org.eclipse.jgit.revwalk.ObjectWalk; import org.eclipse.jgit.revwalk.RevCommit; @@ -134,8 +135,8 @@ import org.eclipse.jgit.util.TemporaryBuffer; * <li>(usually) by providing sets of interesting and uninteresting objects in * repository - all interesting objects and their ancestors except uninteresting * objects and their ancestors will be included in pack, or</li> - * <li>by providing iterator of {@link RevObject} specifying exact list and - * order of objects in pack</li> + * <li>by providing iterator of {@link org.eclipse.jgit.revwalk.RevObject} + * specifying exact list and order of objects in pack</li> * </ul> * <p> * Typical usage consists of creating an instance, configuring options, @@ -148,10 +149,11 @@ import org.eclipse.jgit.util.TemporaryBuffer; * followed by {@link #writeBitmapIndex(OutputStream)}. * </p> * <p> - * Class provide set of configurable options and {@link ProgressMonitor} - * support, as operations may take a long time for big repositories. Deltas - * searching algorithm is <b>NOT IMPLEMENTED</b> yet - this implementation - * relies only on deltas and objects reuse. + * Class provide set of configurable options and + * {@link org.eclipse.jgit.lib.ProgressMonitor} support, as operations may take + * a long time for big repositories. Deltas searching algorithm is <b>NOT + * IMPLEMENTED</b> yet - this implementation relies only on deltas and objects + * reuse. * </p> * <p> * This class is not thread safe. It is intended to be used in one thread as a @@ -209,7 +211,11 @@ public class PackWriter implements AutoCloseable { } }; - /** @return all allocated, non-released PackWriters instances. */ + /** + * Get all allocated, non-released PackWriters instances. + * + * @return all allocated, non-released PackWriters instances. + */ public static Iterable<PackWriter> getInstances() { return instancesIterable; } @@ -373,7 +379,6 @@ public class PackWriter implements AutoCloseable { * * @param callback * the callback to set - * * @return this object for chaining. */ public PackWriter setObjectCountCallback(ObjectCountCallback callback) { @@ -465,12 +470,19 @@ public class PackWriter implements AutoCloseable { reuseValidate = validate; } - /** @return true if this writer is producing a thin pack. */ + /** + * Whether this writer is producing a thin pack. + * + * @return true if this writer is producing a thin pack. + */ public boolean isThin() { return thin; } /** + * Whether writer may pack objects with delta base object not within set of + * objects to pack + * * @param packthin * a boolean indicating whether writer may pack objects with * delta base object not within set of objects to pack, but @@ -482,16 +494,23 @@ public class PackWriter implements AutoCloseable { thin = packthin; } - /** @return true to reuse cached packs. If true index creation isn't available. */ + /** + * Whether to reuse cached packs. + * + * @return {@code true} to reuse cached packs. If true index creation isn't + * available. + */ public boolean isUseCachedPacks() { return useCachedPacks; } /** + * Whether to use cached packs + * * @param useCached - * if set to true and a cached pack is present, it will be - * appended onto the end of a thin-pack, reducing the amount of - * working set space and CPU used by PackWriter. Enabling this + * if set to {@code true} and a cached pack is present, it will + * be appended onto the end of a thin-pack, reducing the amount + * of working set space and CPU used by PackWriter. Enabling this * feature prevents PackWriter from creating an index for the * newly created pack, so its only suitable for writing to a * network client, where the client will make the index. @@ -500,12 +519,18 @@ public class PackWriter implements AutoCloseable { useCachedPacks = useCached; } - /** @return true to use bitmaps for ObjectWalks, if available. */ + /** + * Whether to use bitmaps + * + * @return {@code true} to use bitmaps for ObjectWalks, if available. + */ public boolean isUseBitmaps() { return useBitmaps; } /** + * Whether to use bitmaps + * * @param useBitmaps * if set to true, bitmaps will be used when preparing a pack. */ @@ -513,23 +538,33 @@ public class PackWriter implements AutoCloseable { this.useBitmaps = useBitmaps; } - /** @return true if the index file cannot be created by this PackWriter. */ + /** + * Whether the index file cannot be created by this PackWriter. + * + * @return {@code true} if the index file cannot be created by this + * PackWriter. + */ public boolean isIndexDisabled() { return indexDisabled || !cachedPacks.isEmpty(); } /** + * Whether to disable creation of the index file. + * * @param noIndex - * true to disable creation of the index file. + * {@code true} to disable creation of the index file. */ public void setIndexDisabled(boolean noIndex) { this.indexDisabled = noIndex; } /** - * @return true to ignore objects that are uninteresting and also not found - * on local disk; false to throw a {@link MissingObjectException} - * out of {@link #preparePack(ProgressMonitor, Set, Set)} if an + * Whether to ignore missing uninteresting objects + * + * @return {@code true} to ignore objects that are uninteresting and also + * not found on local disk; false to throw a + * {@link org.eclipse.jgit.errors.MissingObjectException} out of + * {@link #preparePack(ProgressMonitor, Set, Set)} if an * uninteresting object is not in the source repository. By default, * true, permitting gracefully ignoring of uninteresting objects. */ @@ -538,11 +573,13 @@ public class PackWriter implements AutoCloseable { } /** + * Whether writer should ignore non existing uninteresting objects + * * @param ignore - * true if writer should ignore non existing uninteresting - * objects during construction set of objects to pack; false - * otherwise - non existing uninteresting objects may cause - * {@link MissingObjectException} + * {@code true} if writer should ignore non existing + * uninteresting objects during construction set of objects to + * pack; false otherwise - non existing uninteresting objects may + * cause {@link org.eclipse.jgit.errors.MissingObjectException} */ public void setIgnoreMissingUninteresting(final boolean ignore) { ignoreMissingUninteresting = ignore; @@ -585,7 +622,7 @@ public class PackWriter implements AutoCloseable { * Returns objects number in a pack file that was created by this writer. * * @return number of objects in pack. - * @throws IOException + * @throws java.io.IOException * a cached pack cannot supply its object count. */ public long getObjectCount() throws IOException { @@ -612,7 +649,7 @@ public class PackWriter implements AutoCloseable { * been invoked and completed successfully. * * @return set of objects in pack. - * @throws IOException + * @throws java.io.IOException * a cached pack cannot supply its object ids. */ public ObjectIdOwnerMap<ObjectIdOwnerMap.Entry> getObjectSet() @@ -671,12 +708,14 @@ public class PackWriter implements AutoCloseable { * @param objectsSource * iterator of object to store in a pack; order of objects within * each type is important, ordering by type is not needed; - * allowed types for objects are {@link Constants#OBJ_COMMIT}, - * {@link Constants#OBJ_TREE}, {@link Constants#OBJ_BLOB} and - * {@link Constants#OBJ_TAG}; objects returned by iterator may be - * later reused by caller as object id and type are internally - * copied in each iteration. - * @throws IOException + * allowed types for objects are + * {@link org.eclipse.jgit.lib.Constants#OBJ_COMMIT}, + * {@link org.eclipse.jgit.lib.Constants#OBJ_TREE}, + * {@link org.eclipse.jgit.lib.Constants#OBJ_BLOB} and + * {@link org.eclipse.jgit.lib.Constants#OBJ_TAG}; objects + * returned by iterator may be later reused by caller as object + * id and type are internally copied in each iteration. + * @throws java.io.IOException * when some I/O problem occur during reading objects. */ public void preparePack(@NonNull Iterator<RevObject> objectsSource) @@ -692,10 +731,10 @@ public class PackWriter implements AutoCloseable { * Basing on these 2 sets, another set of objects to put in a pack file is * created: this set consists of all objects reachable (ancestors) from * interesting objects, except uninteresting objects and their ancestors. - * This method uses class {@link ObjectWalk} extensively to find out that - * appropriate set of output objects and their optimal order in output pack. - * Order is consistent with general git in-pack rules: sort by object type, - * recency, path and delta-base first. + * This method uses class {@link org.eclipse.jgit.revwalk.ObjectWalk} + * extensively to find out that appropriate set of output objects and their + * optimal order in output pack. Order is consistent with general git + * in-pack rules: sort by object type, recency, path and delta-base first. * </p> * * @param countingMonitor @@ -708,7 +747,7 @@ public class PackWriter implements AutoCloseable { * points of graph traversal). Pass {@link #NONE} if all objects * reachable from {@code want} are desired, such as when serving * a clone. - * @throws IOException + * @throws java.io.IOException * when some I/O problem occur during reading objects. */ public void preparePack(ProgressMonitor countingMonitor, @@ -743,7 +782,7 @@ public class PackWriter implements AutoCloseable { * {@code shallow} commits and earlier generations will be * included in the pack if requested by {@code want}. Must not be * {@code null}. - * @throws IOException + * @throws java.io.IOException * an I/O problem occurred while reading objects. */ public void preparePack(ProgressMonitor countingMonitor, @@ -782,7 +821,7 @@ public class PackWriter implements AutoCloseable { * @param noBitmaps * collection of objects to be excluded from bitmap commit * selection. - * @throws IOException + * @throws java.io.IOException * an I/O problem occurred while reading objects. */ public void preparePack(ProgressMonitor countingMonitor, @@ -807,10 +846,10 @@ public class PackWriter implements AutoCloseable { * Basing on these 2 sets, another set of objects to put in a pack file is * created: this set consists of all objects reachable (ancestors) from * interesting objects, except uninteresting objects and their ancestors. - * This method uses class {@link ObjectWalk} extensively to find out that - * appropriate set of output objects and their optimal order in output pack. - * Order is consistent with general git in-pack rules: sort by object type, - * recency, path and delta-base first. + * This method uses class {@link org.eclipse.jgit.revwalk.ObjectWalk} + * extensively to find out that appropriate set of output objects and their + * optimal order in output pack. Order is consistent with general git + * in-pack rules: sort by object type, recency, path and delta-base first. * </p> * * @param countingMonitor @@ -828,7 +867,7 @@ public class PackWriter implements AutoCloseable { * @param noBitmaps * collection of objects to be excluded from bitmap commit * selection. - * @throws IOException + * @throws java.io.IOException * when some I/O problem occur during reading objects. */ public void preparePack(ProgressMonitor countingMonitor, @@ -852,7 +891,7 @@ public class PackWriter implements AutoCloseable { * @param id * the object to test the existence of. * @return true if the object will appear in the output pack file. - * @throws IOException + * @throws java.io.IOException * a cached pack cannot be examined. */ public boolean willInclude(final AnyObjectId id) throws IOException { @@ -919,7 +958,7 @@ public class PackWriter implements AutoCloseable { * @param indexStream * output for the index data. Caller is responsible for closing * this stream. - * @throws IOException + * @throws java.io.IOException * the index data could not be written to the supplied stream. */ public void writeIndex(final OutputStream indexStream) throws IOException { @@ -941,7 +980,7 @@ public class PackWriter implements AutoCloseable { * @param bitmapIndexStream * output for the bitmap index data. Caller is responsible for * closing this stream. - * @throws IOException + * @throws java.io.IOException * the index data could not be written to the supplied stream. */ public void writeBitmapIndex(final OutputStream bitmapIndexStream) @@ -1026,13 +1065,13 @@ public class PackWriter implements AutoCloseable { * @param packStream * output stream of pack data. The stream should be buffered by * the caller. The caller is responsible for closing the stream. - * @throws IOException + * @throws java.io.IOException * an error occurred reading a local object's data to include in * the pack, or writing compressed object data to the output * stream. * @throws WriteAbortedException - * the write operation is aborted by {@link ObjectCountCallback} - * . + * the write operation is aborted by + * {@link org.eclipse.jgit.transport.ObjectCountCallback} . */ public void writePack(ProgressMonitor compressMonitor, ProgressMonitor writeMonitor, OutputStream packStream) @@ -1121,6 +1160,9 @@ public class PackWriter implements AutoCloseable { } /** + * Get statistics of what this PackWriter did in order to create the final + * pack stream. + * * @return description of what this PackWriter did in order to create the * final pack stream. This should only be invoked after the calls to * create the pack/index/bitmap have completed. @@ -1129,12 +1171,18 @@ public class PackWriter implements AutoCloseable { return new PackStatistics(stats); } - /** @return snapshot of the current state of this PackWriter. */ + /** + * Get snapshot of the current state of this PackWriter. + * + * @return snapshot of the current state of this PackWriter. + */ public State getState() { return state.snapshot(); } /** + * {@inheritDoc} + * <p> * Release all resources used by this writer. */ @Override @@ -1483,9 +1531,7 @@ public class PackWriter implements AutoCloseable { if (err instanceof IOException) throw (IOException) err; - IOException fail = new IOException(err.getMessage()); - fail.initCause(err); - throw fail; + throw new IOException(err.getMessage(), err); } endPhase(monitor); } @@ -1714,7 +1760,7 @@ public class PackWriter implements AutoCloseable { if (!shallowPack && useBitmaps) { BitmapIndex bitmapIndex = reader.getBitmapIndex(); if (bitmapIndex != null) { - PackWriterBitmapWalker bitmapWalker = new PackWriterBitmapWalker( + BitmapWalker bitmapWalker = new BitmapWalker( walker, bitmapIndex, countingMonitor); findObjectsToPackUsingBitmaps(bitmapWalker, want, have); endPhase(countingMonitor); @@ -1917,7 +1963,7 @@ public class PackWriter implements AutoCloseable { } private void findObjectsToPackUsingBitmaps( - PackWriterBitmapWalker bitmapWalker, Set<? extends ObjectId> want, + BitmapWalker bitmapWalker, Set<? extends ObjectId> want, Set<? extends ObjectId> have) throws MissingObjectException, IncorrectObjectTypeException, IOException { @@ -1971,7 +2017,7 @@ public class PackWriter implements AutoCloseable { * * @param object * the object to add. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the object is an unsupported type. */ public void addObject(final RevObject object) @@ -2013,9 +2059,9 @@ public class PackWriter implements AutoCloseable { /** * Select an object representation for this writer. * <p> - * An {@link ObjectReader} implementation should invoke this method once for - * each representation available for an object, to allow the writer to find - * the most suitable one for the output. + * An {@link org.eclipse.jgit.lib.ObjectReader} implementation should invoke + * this method once for each representation available for an object, to + * allow the writer to find the most suitable one for the output. * * @param otp * the object being packed. @@ -2096,7 +2142,7 @@ public class PackWriter implements AutoCloseable { * @param pm * progress monitor to report bitmap building work. * @return whether a bitmap index may be written. - * @throws IOException + * @throws java.io.IOException * when some I/O problem occur during reading objects. */ public boolean prepareBitmapIndex(ProgressMonitor pm) throws IOException { @@ -2123,7 +2169,7 @@ public class PackWriter implements AutoCloseable { beginPhase(PackingPhase.BUILDING_BITMAPS, pm, selectedCommits.size()); - PackWriterBitmapWalker walker = bitmapPreparer.newBitmapWalker(); + BitmapWalker walker = bitmapPreparer.newBitmapWalker(); AnyObjectId last = null; for (PackWriterBitmapPreparer.BitmapCommit cmit : selectedCommits) { if (!cmit.isReuseWalker()) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackWriterBitmapPreparer.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackWriterBitmapPreparer.java index 8bedddb935..38d3458cf9 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackWriterBitmapPreparer.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackWriterBitmapPreparer.java @@ -59,18 +59,19 @@ import java.util.Set; import org.eclipse.jgit.errors.IncorrectObjectTypeException; import org.eclipse.jgit.errors.MissingObjectException; import org.eclipse.jgit.internal.JGitText; +import org.eclipse.jgit.internal.revwalk.AddUnseenToBitmapFilter; import org.eclipse.jgit.internal.storage.file.BitmapIndexImpl; import org.eclipse.jgit.internal.storage.file.BitmapIndexImpl.CompressedBitmap; import org.eclipse.jgit.internal.storage.file.PackBitmapIndex; import org.eclipse.jgit.internal.storage.file.PackBitmapIndexBuilder; import org.eclipse.jgit.internal.storage.file.PackBitmapIndexRemapper; -import org.eclipse.jgit.internal.storage.pack.PackWriterBitmapWalker.AddUnseenToBitmapFilter; import org.eclipse.jgit.lib.AnyObjectId; import org.eclipse.jgit.lib.BitmapIndex.BitmapBuilder; import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.lib.ObjectReader; import org.eclipse.jgit.lib.ProgressMonitor; +import org.eclipse.jgit.revwalk.BitmapWalker; import org.eclipse.jgit.revwalk.ObjectWalk; import org.eclipse.jgit.revwalk.RevCommit; import org.eclipse.jgit.revwalk.RevObject; @@ -508,8 +509,8 @@ class PackWriterBitmapPreparer { return Math.max(next, recentCommitSpan); } - PackWriterBitmapWalker newBitmapWalker() { - return new PackWriterBitmapWalker( + BitmapWalker newBitmapWalker() { + return new BitmapWalker( new ObjectWalk(reader), bitmapIndex, null); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/StoredObjectRepresentation.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/StoredObjectRepresentation.java index c48b1bbff0..23778201cf 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/StoredObjectRepresentation.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/StoredObjectRepresentation.java @@ -46,7 +46,9 @@ package org.eclipse.jgit.internal.storage.pack; import org.eclipse.jgit.lib.ObjectId; /** - * An object representation {@link PackWriter} can consider for packing. + * An object representation + * {@link org.eclipse.jgit.internal.storage.pack.PackWriter} can consider for + * packing. */ public class StoredObjectRepresentation { /** Special unknown value for {@link #getWeight()}. */ @@ -62,6 +64,8 @@ public class StoredObjectRepresentation { public static final int FORMAT_OTHER = 2; /** + * Get relative size of this object's packed form. + * * @return relative size of this object's packed form. The special value * {@link #WEIGHT_UNKNOWN} can be returned to indicate the * implementation doesn't know, or cannot supply the weight up @@ -72,6 +76,8 @@ public class StoredObjectRepresentation { } /** + * Get the storage format type + * * @return the storage format type, which must be one of * {@link #PACK_DELTA}, {@link #PACK_WHOLE}, or * {@link #FORMAT_OTHER}. @@ -81,6 +87,9 @@ public class StoredObjectRepresentation { } /** + * Get identity of the object this delta applies to in order to recover the + * original object content. + * * @return identity of the object this delta applies to in order to recover * the original object content. This method should only be called if * {@link #getFormat()} returned {@link #PACK_DELTA}. @@ -90,6 +99,9 @@ public class StoredObjectRepresentation { } /** + * Whether the current representation of the object has had delta + * compression attempted on it. + * * @return whether the current representation of the object has had delta * compression attempted on it. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/BlockSizeTooSmallException.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/BlockSizeTooSmallException.java index cb0f988b23..991306e0a6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/BlockSizeTooSmallException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/BlockSizeTooSmallException.java @@ -45,7 +45,10 @@ package org.eclipse.jgit.internal.storage.reftable; import java.io.IOException; -/** Thrown if {@link ReftableWriter} cannot fit a reference. */ +/** + * Thrown if {@link org.eclipse.jgit.internal.storage.reftable.ReftableWriter} + * cannot fit a reference. + */ public class BlockSizeTooSmallException extends IOException { private static final long serialVersionUID = 1L; @@ -55,7 +58,11 @@ public class BlockSizeTooSmallException extends IOException { minBlockSize = b; } - /** @return minimum block size in bytes reftable requires to write a ref. */ + /** + * Get minimum block size in bytes reftable requires to write a ref. + * + * @return minimum block size in bytes reftable requires to write a ref. + */ public int getMinimumBlockSize() { return minBlockSize; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/EmptyLogCursor.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/EmptyLogCursor.java index d7745891a5..de5baa1c18 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/EmptyLogCursor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/EmptyLogCursor.java @@ -49,26 +49,31 @@ import org.eclipse.jgit.lib.ReflogEntry; /** Empty {@link LogCursor} with no results. */ class EmptyLogCursor extends LogCursor { + /** {@inheritDoc} */ @Override public boolean next() throws IOException { return false; } + /** {@inheritDoc} */ @Override public String getRefName() { return null; } + /** {@inheritDoc} */ @Override public long getUpdateIndex() { return 0; } + /** {@inheritDoc} */ @Override public ReflogEntry getReflogEntry() { return null; } + /** {@inheritDoc} */ @Override public void close() { // Do nothing. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/LogCursor.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/LogCursor.java index c19968c098..486fd28984 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/LogCursor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/LogCursor.java @@ -47,26 +47,42 @@ import java.io.IOException; import org.eclipse.jgit.lib.ReflogEntry; -/** Iterator over logs inside a {@link Reftable}. */ +/** + * Iterator over logs inside a + * {@link org.eclipse.jgit.internal.storage.reftable.Reftable}. + */ public abstract class LogCursor implements AutoCloseable { /** * Check if another log record is available. * * @return {@code true} if there is another result. - * @throws IOException + * @throws java.io.IOException * logs cannot be read. */ public abstract boolean next() throws IOException; - /** @return name of the current reference. */ + /** + * Get name of the current reference. + * + * @return name of the current reference. + */ public abstract String getRefName(); - /** @return identifier of the transaction that created the log record. */ + /** + * Get identifier of the transaction that created the log record. + * + * @return identifier of the transaction that created the log record. + */ public abstract long getUpdateIndex(); - /** @return current log entry. */ + /** + * Get current log entry. + * + * @return current log entry. + */ public abstract ReflogEntry getReflogEntry(); + /** {@inheritDoc} */ @Override public abstract void close(); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/MergedReftable.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/MergedReftable.java index 9fc6ae2bb4..baebde2b48 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/MergedReftable.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/MergedReftable.java @@ -54,8 +54,10 @@ import org.eclipse.jgit.lib.ReflogEntry; /** * Merges multiple reference tables together. * <p> - * A {@link MergedReftable} merge-joins multiple {@link ReftableReader} on the - * fly. Tables higher/later in the stack shadow lower/earlier tables, hiding + * A {@link org.eclipse.jgit.internal.storage.reftable.MergedReftable} + * merge-joins multiple + * {@link org.eclipse.jgit.internal.storage.reftable.ReftableReader} on the fly. + * Tables higher/later in the stack shadow lower/earlier tables, hiding * references that been updated/replaced. * <p> * By default deleted references are skipped and not returned to the caller. @@ -89,6 +91,7 @@ public class MergedReftable extends Reftable { } } + /** {@inheritDoc} */ @Override public RefCursor allRefs() throws IOException { MergedRefCursor m = new MergedRefCursor(); @@ -98,6 +101,7 @@ public class MergedReftable extends Reftable { return m; } + /** {@inheritDoc} */ @Override public RefCursor seekRef(String name) throws IOException { MergedRefCursor m = new MergedRefCursor(); @@ -107,6 +111,7 @@ public class MergedReftable extends Reftable { return m; } + /** {@inheritDoc} */ @Override public RefCursor byObjectId(AnyObjectId name) throws IOException { MergedRefCursor m = new MergedRefCursor(); @@ -116,6 +121,7 @@ public class MergedReftable extends Reftable { return m; } + /** {@inheritDoc} */ @Override public LogCursor allLogs() throws IOException { MergedLogCursor m = new MergedLogCursor(); @@ -125,6 +131,7 @@ public class MergedReftable extends Reftable { return m; } + /** {@inheritDoc} */ @Override public LogCursor seekLog(String refName, long updateIdx) throws IOException { @@ -135,6 +142,7 @@ public class MergedReftable extends Reftable { return m; } + /** {@inheritDoc} */ @Override public void close() throws IOException { for (Reftable t : tables) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/RefCursor.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/RefCursor.java index d8e9c609f0..5d4af30a91 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/RefCursor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/RefCursor.java @@ -47,29 +47,45 @@ import java.io.IOException; import org.eclipse.jgit.lib.Ref; -/** Iterator over references inside a {@link Reftable}. */ +/** + * Iterator over references inside a + * {@link org.eclipse.jgit.internal.storage.reftable.Reftable}. + */ public abstract class RefCursor implements AutoCloseable { /** * Check if another reference is available. * * @return {@code true} if there is another result. - * @throws IOException + * @throws java.io.IOException * references cannot be read. */ public abstract boolean next() throws IOException; - /** @return reference at the current position. */ + /** + * Get reference at the current position. + * + * @return reference at the current position. + */ public abstract Ref getRef(); - /** @return updateIndex that last modified the current reference, */ + /** + * Get updateIndex that last modified the current reference. + * + * @return updateIndex that last modified the current reference. + */ public abstract long getUpdateIndex(); - /** @return {@code true} if the current reference was deleted. */ + /** + * Whether the current reference was deleted. + * + * @return {@code true} if the current reference was deleted. + */ public boolean wasDeleted() { Ref r = getRef(); return r.getStorage() == Ref.Storage.NEW && r.getObjectId() == null; } + /** {@inheritDoc} */ @Override public abstract void close(); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/Reftable.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/Reftable.java index 1189ed3b96..510c1a14e0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/Reftable.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/Reftable.java @@ -55,9 +55,13 @@ import org.eclipse.jgit.lib.AnyObjectId; import org.eclipse.jgit.lib.Ref; import org.eclipse.jgit.lib.SymbolicRef; -/** Abstract table of references. */ +/** + * Abstract table of references. + */ public abstract class Reftable implements AutoCloseable { /** + * References to convert into a reftable + * * @param refs * references to convert into a reftable; may be empty. * @return a reader for the supplied references. @@ -83,6 +87,8 @@ public abstract class Reftable implements AutoCloseable { protected boolean includeDeletes; /** + * Whether deleted references will be returned. + * * @param deletes * if {@code true} deleted references will be returned. If * {@code false} (default behavior), deleted references will be @@ -96,7 +102,7 @@ public abstract class Reftable implements AutoCloseable { * Seek to the first reference, to iterate in order. * * @return cursor to iterate. - * @throws IOException + * @throws java.io.IOException * if references cannot be read. */ public abstract RefCursor allRefs() throws IOException; @@ -115,7 +121,7 @@ public abstract class Reftable implements AutoCloseable { * @param refName * reference name or subtree to find. * @return cursor to iterate; empty cursor if no references match. - * @throws IOException + * @throws java.io.IOException * if references cannot be read. */ public abstract RefCursor seekRef(String refName) throws IOException; @@ -126,7 +132,7 @@ public abstract class Reftable implements AutoCloseable { * @param id * object to find. * @return cursor to iterate; empty cursor if no references match. - * @throws IOException + * @throws java.io.IOException * if references cannot be read. */ public abstract RefCursor byObjectId(AnyObjectId id) throws IOException; @@ -135,7 +141,7 @@ public abstract class Reftable implements AutoCloseable { * Seek reader to read log records. * * @return cursor to iterate; empty cursor if no logs are present. - * @throws IOException + * @throws java.io.IOException * if logs cannot be read. */ public abstract LogCursor allLogs() throws IOException; @@ -146,7 +152,7 @@ public abstract class Reftable implements AutoCloseable { * @param refName * exact name of the reference whose log to read. * @return cursor to iterate; empty cursor if no logs match. - * @throws IOException + * @throws java.io.IOException * if logs cannot be read. */ public LogCursor seekLog(String refName) throws IOException { @@ -162,7 +168,7 @@ public abstract class Reftable implements AutoCloseable { * most recent index to return first in the log cursor. Log * records at or before {@code updateIndex} will be returned. * @return cursor to iterate; empty cursor if no logs match. - * @throws IOException + * @throws java.io.IOException * if logs cannot be read. */ public abstract LogCursor seekLog(String refName, long updateIndex) @@ -174,7 +180,7 @@ public abstract class Reftable implements AutoCloseable { * @param refName * reference name to find. * @return the reference, or {@code null} if not found. - * @throws IOException + * @throws java.io.IOException * if references cannot be read. */ @Nullable @@ -196,7 +202,7 @@ public abstract class Reftable implements AutoCloseable { * reference name or subtree to find. * @return {@code true} if the reference exists, or at least one reference * exists in the subtree. - * @throws IOException + * @throws java.io.IOException * if references cannot be read. */ public boolean hasRef(String refName) throws IOException { @@ -212,7 +218,7 @@ public abstract class Reftable implements AutoCloseable { * ObjectId to find. * @return {@code true} if any reference exists directly referencing * {@code id}, or a annotated tag that peels to {@code id}. - * @throws IOException + * @throws java.io.IOException * if references cannot be read. */ public boolean hasId(AnyObjectId id) throws IOException { @@ -227,7 +233,7 @@ public abstract class Reftable implements AutoCloseable { * @param symref * reference to resolve. * @return resolved {@code symref}, or {@code null}. - * @throws IOException + * @throws java.io.IOException * if references cannot be read. */ @Nullable @@ -257,6 +263,7 @@ public abstract class Reftable implements AutoCloseable { return new SymbolicRef(ref.getName(), dst); } + /** {@inheritDoc} */ @Override public abstract void close() throws IOException; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableCompactor.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableCompactor.java index c22157784c..ed73a9efbd 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableCompactor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableCompactor.java @@ -74,12 +74,14 @@ public class ReftableCompactor { private long compactBytesLimit; private long bytesToCompact; private boolean includeDeletes; - private long minUpdateIndex; + private long minUpdateIndex = -1; private long maxUpdateIndex; private long oldestReflogTimeMillis; private Stats stats; /** + * Set configuration for the reftable. + * * @param cfg * configuration for the reftable. * @return {@code this} @@ -90,6 +92,8 @@ public class ReftableCompactor { } /** + * Set limit on number of bytes from source tables to compact. + * * @param bytes * limit on number of bytes from source tables to compact. * @return {@code this} @@ -100,6 +104,9 @@ public class ReftableCompactor { } /** + * Whether to include deletions in the output, which may be necessary for + * partial compaction. + * * @param deletes * {@code true} to include deletions in the output, which may be * necessary for partial compaction. @@ -111,6 +118,9 @@ public class ReftableCompactor { } /** + * Set the minimum update index for log entries that appear in the compacted + * reftable. + * * @param min * the minimum update index for log entries that appear in the * compacted reftable. This should be 1 higher than the prior @@ -124,6 +134,9 @@ public class ReftableCompactor { } /** + * Set the maximum update index for log entries that appear in the compacted + * reftable. + * * @param max * the maximum update index for log entries that appear in the * compacted reftable. This should be at least 1 higher than the @@ -137,6 +150,8 @@ public class ReftableCompactor { } /** + * Set oldest reflog time to preserve. + * * @param timeMillis * oldest log time to preserve. Entries whose timestamps are * {@code >= timeMillis} will be copied into the output file. Log @@ -159,7 +174,7 @@ public class ReftableCompactor { * tables to compact. Tables should be ordered oldest first/most * recent last so that the more recent tables can shadow the * older results. Caller is responsible for closing the readers. - * @throws IOException + * @throws java.io.IOException * update indexes of a reader cannot be accessed. */ public void addAll(List<? extends Reftable> readers) throws IOException { @@ -184,7 +199,7 @@ public class ReftableCompactor { * responsible for closing the reader. * @return {@code true} if the compactor accepted this table; {@code false} * if the compactor has reached its limit. - * @throws IOException + * @throws java.io.IOException * if size of {@code reader}, or its update indexes cannot be read. */ public boolean tryAddFirst(ReftableReader reader) throws IOException { @@ -199,7 +214,7 @@ public class ReftableCompactor { } private void adjustUpdateIndexes(ReftableReader reader) throws IOException { - if (minUpdateIndex == 0) { + if (minUpdateIndex == -1) { minUpdateIndex = reader.minUpdateIndex(); } else { minUpdateIndex = Math.min(minUpdateIndex, reader.minUpdateIndex()); @@ -213,14 +228,14 @@ public class ReftableCompactor { * @param out * stream to write the compacted tables to. Caller is responsible * for closing {@code out}. - * @throws IOException + * @throws java.io.IOException * if tables cannot be read, or cannot be written. */ public void compact(OutputStream out) throws IOException { MergedReftable mr = new MergedReftable(new ArrayList<>(tables)); mr.setIncludeDeletes(includeDeletes); - writer.setMinUpdateIndex(minUpdateIndex); + writer.setMinUpdateIndex(Math.max(minUpdateIndex, 0)); writer.setMaxUpdateIndex(maxUpdateIndex); writer.begin(out); mergeRefs(mr); @@ -229,7 +244,11 @@ public class ReftableCompactor { stats = writer.getStats(); } - /** @return statistics of the last written reftable. */ + /** + * Get statistics of the last written reftable. + * + * @return statistics of the last written reftable. + */ public Stats getStats() { return stats; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableConfig.java index f7a1fbe2af..66c113d1ec 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableConfig.java @@ -48,7 +48,9 @@ import static org.eclipse.jgit.internal.storage.reftable.ReftableConstants.MAX_B import org.eclipse.jgit.lib.Config; import org.eclipse.jgit.lib.Repository; -/** Configuration used by a reftable writer when constructing the stream. */ +/** + * Configuration used by a reftable writer when constructing the stream. + */ public class ReftableConfig { private int refBlockSize = 4 << 10; private int logBlockSize; @@ -57,7 +59,9 @@ public class ReftableConfig { private boolean alignBlocks = true; private boolean indexObjects = true; - /** Create a default configuration. */ + /** + * Create a default configuration. + */ public ReftableConfig() { } @@ -74,7 +78,8 @@ public class ReftableConfig { } /** - * Create a configuration honoring settings in a {@link Config}. + * Create a configuration honoring settings in a + * {@link org.eclipse.jgit.lib.Config}. * * @param cfg * the source to read settings from. The source is not retained @@ -100,12 +105,18 @@ public class ReftableConfig { this.indexObjects = cfg.indexObjects; } - /** @return desired output block size for references, in bytes */ + /** + * Get desired output block size for references, in bytes. + * + * @return desired output block size for references, in bytes. + */ public int getRefBlockSize() { return refBlockSize; } /** + * Set desired output block size for references, in bytes. + * * @param szBytes * desired output block size for references, in bytes. */ @@ -117,6 +128,8 @@ public class ReftableConfig { } /** + * Get desired output block size for log entries, in bytes. + * * @return desired output block size for log entries, in bytes. If 0 the * writer will default to {@code 2 * getRefBlockSize()}. */ @@ -125,6 +138,8 @@ public class ReftableConfig { } /** + * Set desired output block size for log entries, in bytes. + * * @param szBytes * desired output block size for log entries, in bytes. If 0 will * default to {@code 2 * getRefBlockSize()}. @@ -136,12 +151,18 @@ public class ReftableConfig { logBlockSize = Math.max(0, szBytes); } - /** @return number of references between binary search markers. */ + /** + * Get number of references between binary search markers. + * + * @return number of references between binary search markers. + */ public int getRestartInterval() { return restartInterval; } /** + * <p>Setter for the field <code>restartInterval</code>.</p> + * * @param interval * number of references between binary search markers. If * {@code interval} is 0 (default), the writer will select a @@ -151,12 +172,18 @@ public class ReftableConfig { restartInterval = Math.max(0, interval); } - /** @return maximum depth of the index; 0 for unlimited. */ + /** + * Get maximum depth of the index; 0 for unlimited. + * + * @return maximum depth of the index; 0 for unlimited. + */ public int getMaxIndexLevels() { return maxIndexLevels; } /** + * Set maximum number of levels to use in indexes. + * * @param levels * maximum number of levels to use in indexes. Lower levels of * the index respect {@link #getRefBlockSize()}, and the highest @@ -166,12 +193,19 @@ public class ReftableConfig { maxIndexLevels = Math.max(0, levels); } - /** @return {@code true} if the writer should align blocks. */ + /** + * Whether the writer should align blocks. + * + * @return {@code true} if the writer should align blocks. + */ public boolean isAlignBlocks() { return alignBlocks; } /** + * Whether blocks are written aligned to multiples of + * {@link #getRefBlockSize()}. + * * @param align * if {@code true} blocks are written aligned to multiples of * {@link #getRefBlockSize()}. May increase file size due to NUL @@ -181,12 +215,19 @@ public class ReftableConfig { alignBlocks = align; } - /** @return {@code true} if the writer should index object to ref. */ + /** + * Whether the writer should index object to ref. + * + * @return {@code true} if the writer should index object to ref. + */ public boolean isIndexObjects() { return indexObjects; } /** + * Whether the reftable may include additional storage to efficiently map + * from {@code ObjectId} to reference names. + * * @param index * if {@code true} the reftable may include additional storage to * efficiently map from {@code ObjectId} to reference names. By diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableOutputStream.java index a24619b2c5..1fc43c9fac 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableOutputStream.java @@ -92,12 +92,14 @@ class ReftableOutputStream extends OutputStream { blockSize = bs; } + /** {@inheritDoc} */ @Override public void write(int b) { ensureBytesAvailableInBlockBuf(1); blockBuf[cur++] = (byte) b; } + /** {@inheritDoc} */ @Override public void write(byte[] b, int off, int cnt) { ensureBytesAvailableInBlockBuf(cnt); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableReader.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableReader.java index 407a77c7d3..74877192f6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableReader.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableReader.java @@ -112,10 +112,13 @@ public class ReftableReader extends Reftable { } /** + * Get the block size in bytes chosen for this file by the writer. + * * @return the block size in bytes chosen for this file by the writer. Most - * reads from the {@link BlockSource} will be aligned to the block - * size. - * @throws IOException + * reads from the + * {@link org.eclipse.jgit.internal.storage.io.BlockSource} will be + * aligned to the block size. + * @throws java.io.IOException * file cannot be read. */ public int blockSize() throws IOException { @@ -126,10 +129,13 @@ public class ReftableReader extends Reftable { } /** + * Get the minimum update index for log entries that appear in this + * reftable. + * * @return the minimum update index for log entries that appear in this * reftable. This should be 1 higher than the prior reftable's * {@code maxUpdateIndex} if this table is used in a stack. - * @throws IOException + * @throws java.io.IOException * file cannot be read. */ public long minUpdateIndex() throws IOException { @@ -140,10 +146,13 @@ public class ReftableReader extends Reftable { } /** + * Get the maximum update index for log entries that appear in this + * reftable. + * * @return the maximum update index for log entries that appear in this * reftable. This should be 1 higher than the prior reftable's * {@code maxUpdateIndex} if this table is used in a stack. - * @throws IOException + * @throws java.io.IOException * file cannot be read. */ public long maxUpdateIndex() throws IOException { @@ -153,6 +162,7 @@ public class ReftableReader extends Reftable { return maxUpdateIndex; } + /** {@inheritDoc} */ @Override public RefCursor allRefs() throws IOException { if (blockSize == -1) { @@ -167,6 +177,7 @@ public class ReftableReader extends Reftable { return i; } + /** {@inheritDoc} */ @Override public RefCursor seekRef(String refName) throws IOException { initRefIndex(); @@ -179,6 +190,7 @@ public class ReftableReader extends Reftable { return i; } + /** {@inheritDoc} */ @Override public RefCursor byObjectId(AnyObjectId id) throws IOException { initObjIndex(); @@ -191,6 +203,7 @@ public class ReftableReader extends Reftable { return i; } + /** {@inheritDoc} */ @Override public LogCursor allLogs() throws IOException { initLogIndex(); @@ -203,6 +216,7 @@ public class ReftableReader extends Reftable { return new EmptyLogCursor(); } + /** {@inheritDoc} */ @Override public LogCursor seekLog(String refName, long updateIndex) throws IOException { @@ -437,13 +451,14 @@ public class ReftableReader extends Reftable { * Get size of the reftable, in bytes. * * @return size of the reftable, in bytes. - * @throws IOException + * @throws java.io.IOException * size cannot be obtained. */ public long size() throws IOException { return src.size(); } + /** {@inheritDoc} */ @Override public void close() throws IOException { src.close(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableWriter.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableWriter.java index 0ac2445fc0..f8b9ffd176 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableWriter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftable/ReftableWriter.java @@ -89,7 +89,9 @@ import org.eclipse.jgit.util.NB; * Writes a reftable formatted file. * <p> * A reftable can be written in a streaming fashion, provided the caller sorts - * all references. A {@link ReftableWriter} is single-use, and not thread-safe. + * all references. A + * {@link org.eclipse.jgit.internal.storage.reftable.ReftableWriter} is + * single-use, and not thread-safe. */ public class ReftableWriter { private ReftableConfig config; @@ -113,7 +115,9 @@ public class ReftableWriter { private int objIdLen; private Stats stats; - /** Initialize a writer with a default configuration. */ + /** + * Initialize a writer with a default configuration. + */ public ReftableWriter() { this(new ReftableConfig()); } @@ -129,6 +133,8 @@ public class ReftableWriter { } /** + * Set configuration for the writer. + * * @param cfg * configuration for the writer. * @return {@code this} @@ -139,6 +145,9 @@ public class ReftableWriter { } /** + * Set the minimum update index for log entries that appear in this + * reftable. + * * @param min * the minimum update index for log entries that appear in this * reftable. This should be 1 higher than the prior reftable's @@ -151,6 +160,9 @@ public class ReftableWriter { } /** + * Set the maximum update index for log entries that appear in this + * reftable. + * * @param max * the maximum update index for log entries that appear in this * reftable. This should be at least 1 higher than the prior @@ -170,7 +182,7 @@ public class ReftableWriter { * stream to write the table to. Caller is responsible for * closing the stream after invoking {@link #finish()}. * @return {@code this} - * @throws IOException + * @throws java.io.IOException * if reftable header cannot be written. */ public ReftableWriter begin(OutputStream os) throws IOException { @@ -208,7 +220,7 @@ public class ReftableWriter { * @param refsToPack * references to sort and write. * @return {@code this} - * @throws IOException + * @throws java.io.IOException * if reftable cannot be written. */ public ReftableWriter sortAndWriteRefs(Collection<Ref> refsToPack) @@ -232,7 +244,7 @@ public class ReftableWriter { * * @param ref * the reference to store. - * @throws IOException + * @throws java.io.IOException * if reftable cannot be written. */ public void writeRef(Ref ref) throws IOException { @@ -249,7 +261,7 @@ public class ReftableWriter { * @param updateIndex * the updateIndex that modified this reference. Must be * {@code >= minUpdateIndex} for this file. - * @throws IOException + * @throws java.io.IOException * if reftable cannot be written. */ public void writeRef(Ref ref, long updateIndex) throws IOException { @@ -295,12 +307,14 @@ public class ReftableWriter { * @param who * committer of the reflog entry. * @param oldId - * prior id; pass {@link ObjectId#zeroId()} for creations. + * prior id; pass {@link org.eclipse.jgit.lib.ObjectId#zeroId()} + * for creations. * @param newId - * new id; pass {@link ObjectId#zeroId()} for deletions. + * new id; pass {@link org.eclipse.jgit.lib.ObjectId#zeroId()} + * for deletions. * @param message * optional message (may be null). - * @throws IOException + * @throws java.io.IOException * if reftable cannot be written. */ public void writeLog(String ref, long updateIndex, PersonIdent who, @@ -327,7 +341,7 @@ public class ReftableWriter { * the ref to delete (hide) a reflog entry from. * @param updateIndex * the update index that must be hidden. - * @throws IOException + * @throws java.io.IOException * if reftable cannot be written. */ public void deleteLog(String ref, long updateIndex) throws IOException { @@ -345,10 +359,14 @@ public class ReftableWriter { } /** + * Get an estimate of the current size in bytes of the reftable + * * @return an estimate of the current size in bytes of the reftable, if it * was finished right now. Estimate is only accurate if - * {@link ReftableConfig#setIndexObjects(boolean)} is {@code false} - * and {@link ReftableConfig#setMaxIndexLevels(int)} is {@code 1}. + * {@link org.eclipse.jgit.internal.storage.reftable.ReftableConfig#setIndexObjects(boolean)} + * is {@code false} and + * {@link org.eclipse.jgit.internal.storage.reftable.ReftableConfig#setMaxIndexLevels(int)} + * is {@code 1}. */ public long estimateTotalBytes() { long bytes = out.size(); @@ -381,7 +399,7 @@ public class ReftableWriter { * Finish writing the reftable by writing its trailer. * * @return {@code this} - * @throws IOException + * @throws java.io.IOException * if reftable cannot be written. */ public ReftableWriter finish() throws IOException { @@ -480,7 +498,11 @@ public class ReftableWriter { return s != null && s.idx != null ? s.idx.rootPosition : 0; } - /** @return statistics of the last written reftable. */ + /** + * Get statistics of the last written reftable. + * + * @return statistics of the last written reftable. + */ public Stats getStats() { return stats; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/AlwaysFailUpdate.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/AlwaysFailUpdate.java index 12ef8734c4..9d673e5e21 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/AlwaysFailUpdate.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/AlwaysFailUpdate.java @@ -61,36 +61,43 @@ class AlwaysFailUpdate extends RefUpdate { setCheckConflicting(false); } + /** {@inheritDoc} */ @Override protected RefDatabase getRefDatabase() { return refdb; } + /** {@inheritDoc} */ @Override protected Repository getRepository() { return refdb.getRepository(); } + /** {@inheritDoc} */ @Override protected boolean tryLock(boolean deref) throws IOException { return false; } + /** {@inheritDoc} */ @Override protected void unlock() { // No locks are held here. } + /** {@inheritDoc} */ @Override protected Result doUpdate(Result desiredResult) { return Result.LOCK_FAILURE; } + /** {@inheritDoc} */ @Override protected Result doDelete(Result desiredResult) { return Result.LOCK_FAILURE; } + /** {@inheritDoc} */ @Override protected Result doLink(String target) { return Result.LOCK_FAILURE; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/Command.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/Command.java index dd08375f21..11837fd75d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/Command.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/Command.java @@ -61,6 +61,7 @@ import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.lib.ObjectIdRef; import org.eclipse.jgit.lib.ObjectInserter; import org.eclipse.jgit.lib.Ref; +import org.eclipse.jgit.lib.SymbolicRef; import org.eclipse.jgit.revwalk.RevObject; import org.eclipse.jgit.revwalk.RevTag; import org.eclipse.jgit.revwalk.RevWalk; @@ -68,25 +69,31 @@ import org.eclipse.jgit.transport.ReceiveCommand; import org.eclipse.jgit.transport.ReceiveCommand.Result; /** - * Command to create, update or delete an entry inside a {@link RefTree}. + * Command to create, update or delete an entry inside a + * {@link org.eclipse.jgit.internal.storage.reftree.RefTree}. * <p> - * Unlike {@link ReceiveCommand} (which can only update a reference to an - * {@link ObjectId}), a RefTree Command can also create, modify or delete - * symbolic references to a target reference. + * Unlike {@link org.eclipse.jgit.transport.ReceiveCommand} (which can only + * update a reference to an {@link org.eclipse.jgit.lib.ObjectId}), a RefTree + * Command can also create, modify or delete symbolic references to a target + * reference. * <p> * RefTree Commands may wrap a {@code ReceiveCommand} to allow callers to * process an existing ReceiveCommand against a RefTree. * <p> - * Commands should be passed into {@link RefTree#apply(java.util.Collection)} + * Commands should be passed into + * {@link org.eclipse.jgit.internal.storage.reftree.RefTree#apply(java.util.Collection)} * for processing. */ public class Command { /** * Set unprocessed commands as failed due to transaction aborted. * <p> - * If a command is still {@link Result#NOT_ATTEMPTED} it will be set to - * {@link Result#REJECTED_OTHER_REASON}. If {@code why} is non-null its - * contents will be used as the message for the first command status. + * If a command is still + * {@link org.eclipse.jgit.transport.ReceiveCommand.Result#NOT_ATTEMPTED} it + * will be set to + * {@link org.eclipse.jgit.transport.ReceiveCommand.Result#REJECTED_OTHER_REASON}. + * If {@code why} is non-null its contents will be used as the message for + * the first command status. * * @param commands * commands to mark as failed. @@ -146,21 +153,27 @@ public class Command { * walk instance to peel the {@code newId}. * @param cmd * command received from a push client. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * {@code oldId} or {@code newId} is missing. - * @throws IOException + * @throws java.io.IOException * {@code oldId} or {@code newId} cannot be peeled. */ public Command(RevWalk rw, ReceiveCommand cmd) throws MissingObjectException, IOException { - this.oldRef = toRef(rw, cmd.getOldId(), cmd.getRefName(), false); - this.newRef = toRef(rw, cmd.getNewId(), cmd.getRefName(), true); + this.oldRef = toRef(rw, cmd.getOldId(), cmd.getOldSymref(), + cmd.getRefName(), false); + this.newRef = toRef(rw, cmd.getNewId(), cmd.getNewSymref(), + cmd.getRefName(), true); this.cmd = cmd; } - static Ref toRef(RevWalk rw, ObjectId id, String name, - boolean mustExist) throws MissingObjectException, IOException { - if (ObjectId.zeroId().equals(id)) { + static Ref toRef(RevWalk rw, ObjectId id, @Nullable String target, + String name, boolean mustExist) + throws MissingObjectException, IOException { + if (target != null) { + return new SymbolicRef(name, + new ObjectIdRef.Unpeeled(NETWORK, target, id)); + } else if (ObjectId.zeroId().equals(id)) { return null; } @@ -179,7 +192,11 @@ public class Command { } } - /** @return name of the reference affected by this command. */ + /** + * Get name of the reference affected by this command. + * + * @return name of the reference affected by this command. + */ public String getRefName() { if (cmd != null) { return cmd.getRefName(); @@ -215,12 +232,20 @@ public class Command { } } - /** @return result of executing this command. */ + /** + * Get result of executing this command. + * + * @return result of executing this command. + */ public Result getResult() { return cmd != null ? cmd.getResult() : result; } - /** @return optional message explaining command failure. */ + /** + * Get optional message explaining command failure. + * + * @return optional message explaining command failure. + */ @Nullable public String getMessage() { return cmd != null ? cmd.getMessage() : null; @@ -246,6 +271,7 @@ public class Command { return newRef; } + /** {@inheritDoc} */ @Override public String toString() { StringBuilder s = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTree.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTree.java index 85690c8ca5..e9aa110419 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTree.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTree.java @@ -74,7 +74,6 @@ import org.eclipse.jgit.errors.DirCacheNameConflictException; import org.eclipse.jgit.errors.IncorrectObjectTypeException; import org.eclipse.jgit.errors.MissingObjectException; import org.eclipse.jgit.internal.JGitText; -import org.eclipse.jgit.lib.FileMode; import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.lib.ObjectIdRef; import org.eclipse.jgit.lib.ObjectInserter; @@ -92,11 +91,13 @@ import org.eclipse.jgit.util.RawParseUtils; * default reference {@code "refs/heads/master"} is stored at path * {@code "heads/master"} in a {@code RefTree}. * <p> - * Normal references are stored as {@link FileMode#GITLINK} tree entries. The - * ObjectId in the tree entry is the ObjectId the reference refers to. + * Normal references are stored as {@link org.eclipse.jgit.lib.FileMode#GITLINK} + * tree entries. The ObjectId in the tree entry is the ObjectId the reference + * refers to. * <p> - * Symbolic references are stored as {@link FileMode#SYMLINK} entries, with the - * blob storing the name of the target reference. + * Symbolic references are stored as + * {@link org.eclipse.jgit.lib.FileMode#SYMLINK} entries, with the blob storing + * the name of the target reference. * <p> * Annotated tags also store the peeled object using a {@code GITLINK} entry * with the suffix <code>" ^"</code> (space carrot), for example @@ -127,13 +128,13 @@ public class RefTree { * @param tree * the tree to read. * @return the ref tree read from the commit. - * @throws IOException + * @throws java.io.IOException * the repository cannot be accessed through the reader. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * a tree object is corrupt and cannot be read. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * a tree object wasn't actually a tree. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * a reference tree object doesn't exist. */ public static RefTree read(ObjectReader reader, RevTree tree) @@ -152,9 +153,10 @@ public class RefTree { /** * Read one reference. * <p> - * References are always returned peeled ({@link Ref#isPeeled()} is true). - * If the reference points to an annotated tag, the returned reference will - * be peeled and contain {@link Ref#getPeeledObjectId()}. + * References are always returned peeled + * ({@link org.eclipse.jgit.lib.Ref#isPeeled()} is true). If the reference + * points to an annotated tag, the returned reference will be peeled and + * contain {@link org.eclipse.jgit.lib.Ref#getPeeledObjectId()}. * <p> * If the reference is a symbolic reference and the chain depth is less than * {@link org.eclipse.jgit.lib.RefDatabase#MAX_SYMBOLIC_REF_DEPTH} the @@ -166,7 +168,7 @@ public class RefTree { * @param name * name of the reference to read. * @return the reference; null if it does not exist. - * @throws IOException + * @throws java.io.IOException * cannot read a symbolic reference target. */ @Nullable @@ -378,7 +380,7 @@ public class RefTree { * Caller is responsible for flushing the inserter before trying * to read the objects, or exposing them through a reference. * @return the top level tree. - * @throws IOException + * @throws java.io.IOException * a tree could not be written. */ public ObjectId writeTree(ObjectInserter inserter) throws IOException { @@ -391,7 +393,11 @@ public class RefTree { return contents.writeTree(inserter); } - /** @return a deep copy of this RefTree. */ + /** + * Create a deep copy of this RefTree. + * + * @return a deep copy of this RefTree. + */ public RefTree copy() { RefTree r = new RefTree(DirCache.newInCore()); DirCacheBuilder b = r.contents.builder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTreeBatch.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTreeBatch.java index 1cccd79810..da98e3fadd 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTreeBatch.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTreeBatch.java @@ -87,6 +87,7 @@ class RefTreeBatch extends BatchRefUpdate { this.refdb = refdb; } + /** {@inheritDoc} */ @Override public void execute(RevWalk rw, ProgressMonitor monitor) throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTreeDatabase.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTreeDatabase.java index df93ce88af..183468fa35 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTreeDatabase.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTreeDatabase.java @@ -74,13 +74,15 @@ import org.eclipse.jgit.util.RefList; import org.eclipse.jgit.util.RefMap; /** - * Reference database backed by a {@link RefTree}. + * Reference database backed by a + * {@link org.eclipse.jgit.internal.storage.reftree.RefTree}. * <p> * The storage for RefTreeDatabase has two parts. The main part is a native Git * tree object stored under the {@code refs/txn} namespace. To avoid cycles, * references to {@code refs/txn} are not stored in that tree object, but - * instead in a "bootstrap" layer, which is a separate {@link RefDatabase} such - * as {@link org.eclipse.jgit.internal.storage.file.RefDirectory} using local + * instead in a "bootstrap" layer, which is a separate + * {@link org.eclipse.jgit.lib.RefDatabase} such as + * {@link org.eclipse.jgit.internal.storage.file.RefDirectory} using local * reference files inside of {@code $GIT_DIR/refs}. */ public class RefTreeDatabase extends RefDatabase { @@ -99,7 +101,8 @@ public class RefTreeDatabase extends RefDatabase { * the repository using references in this database. * @param bootstrap * bootstrap reference database storing the references that - * anchor the {@link RefTree}. + * anchor the + * {@link org.eclipse.jgit.internal.storage.reftree.RefTree}. */ public RefTreeDatabase(Repository repo, RefDatabase bootstrap) { Config cfg = repo.getConfig(); @@ -121,7 +124,8 @@ public class RefTreeDatabase extends RefDatabase { * the repository using references in this database. * @param bootstrap * bootstrap reference database storing the references that - * anchor the {@link RefTree}. + * anchor the + * {@link org.eclipse.jgit.internal.storage.reftree.RefTree}. * @param txnCommitted * name of the bootstrap reference holding the committed RefTree. */ @@ -146,6 +150,8 @@ public class RefTreeDatabase extends RefDatabase { } /** + * Get the bootstrap reference database + * * @return the bootstrap reference database, which must be used to access * {@link #getTxnCommitted()}, {@link #getTxnNamespace()}. */ @@ -153,41 +159,52 @@ public class RefTreeDatabase extends RefDatabase { return bootstrap; } - /** @return name of bootstrap reference anchoring committed RefTree. */ + /** + * Get name of bootstrap reference anchoring committed RefTree. + * + * @return name of bootstrap reference anchoring committed RefTree. + */ public String getTxnCommitted() { return txnCommitted; } /** - * @return namespace used by bootstrap layer, e.g. {@code refs/txn/}. - * Always ends in {@code '/'}. + * Get namespace used by bootstrap layer. + * + * @return namespace used by bootstrap layer, e.g. {@code refs/txn/}. Always + * ends in {@code '/'}. */ @Nullable public String getTxnNamespace() { return txnNamespace; } + /** {@inheritDoc} */ @Override public void create() throws IOException { bootstrap.create(); } + /** {@inheritDoc} */ @Override public boolean performsAtomicTransactions() { return true; } + /** {@inheritDoc} */ @Override public void refresh() { bootstrap.refresh(); } + /** {@inheritDoc} */ @Override public void close() { refs = null; bootstrap.close(); } + /** {@inheritDoc} */ @Override public Ref getRef(String name) throws IOException { String[] needle = new String[SEARCH_PATH.length]; @@ -197,6 +214,7 @@ public class RefTreeDatabase extends RefDatabase { return firstExactRef(needle); } + /** {@inheritDoc} */ @Override public Ref exactRef(String name) throws IOException { if (!repo.isBare() && name.indexOf('/') < 0 && !HEAD.equals(name)) { @@ -235,6 +253,7 @@ public class RefTreeDatabase extends RefDatabase { return ""; //$NON-NLS-1$ } + /** {@inheritDoc} */ @Override public Map<String, Ref> getRefs(String prefix) throws IOException { if (!prefix.isEmpty() && prefix.charAt(prefix.length() - 1) != '/') { @@ -258,6 +277,7 @@ public class RefTreeDatabase extends RefDatabase { : ObjectId.zeroId(); } + /** {@inheritDoc} */ @Override public List<Ref> getAdditionalRefs() throws IOException { Collection<Ref> txnRefs; @@ -279,6 +299,7 @@ public class RefTreeDatabase extends RefDatabase { return all; } + /** {@inheritDoc} */ @Override public Ref peel(Ref ref) throws IOException { Ref i = ref.getLeaf(); @@ -306,17 +327,20 @@ public class RefTreeDatabase extends RefDatabase { return leaf; } + /** {@inheritDoc} */ @Override public boolean isNameConflicting(String name) throws IOException { return conflictsWithBootstrap(name) || !getConflictingNames(name).isEmpty(); } + /** {@inheritDoc} */ @Override public BatchRefUpdate newBatchUpdate() { return new RefTreeBatch(this); } + /** {@inheritDoc} */ @Override public RefUpdate newUpdate(String name, boolean detach) throws IOException { if (!repo.isBare() && name.indexOf('/') < 0 && !HEAD.equals(name)) { @@ -343,6 +367,7 @@ public class RefTreeDatabase extends RefDatabase { return u; } + /** {@inheritDoc} */ @Override public RefRename newRename(String fromName, String toName) throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTreeNames.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTreeNames.java index c53d6deb21..080304dfb4 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTreeNames.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTreeNames.java @@ -45,7 +45,9 @@ package org.eclipse.jgit.internal.storage.reftree; import org.eclipse.jgit.lib.RefDatabase; -/** Magic reference name logic for RefTrees. */ +/** + * Magic reference name logic for RefTrees. + */ public class RefTreeNames { /** * Suffix used on a {@link RefTreeDatabase#getTxnNamespace()} for user data. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTreeRename.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTreeRename.java index 5fd7ecdd79..4faf96bf4b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTreeRename.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTreeRename.java @@ -69,6 +69,7 @@ class RefTreeRename extends RefRename { this.refdb = refdb; } + /** {@inheritDoc} */ @Override protected Result doRename() throws IOException { try (RevWalk rw = new RevWalk(refdb.getRepository())) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTreeUpdate.java b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTreeUpdate.java index 8829c1156a..dda2be40bb 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTreeUpdate.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/reftree/RefTreeUpdate.java @@ -76,16 +76,19 @@ class RefTreeUpdate extends RefUpdate { setCheckConflicting(false); // Done automatically by doUpdate. } + /** {@inheritDoc} */ @Override protected RefDatabase getRefDatabase() { return refdb; } + /** {@inheritDoc} */ @Override protected Repository getRepository() { return refdb.getRepository(); } + /** {@inheritDoc} */ @Override protected boolean tryLock(boolean deref) throws IOException { rw = new RevWalk(getRepository()); @@ -100,6 +103,7 @@ class RefTreeUpdate extends RefUpdate { return true; } + /** {@inheritDoc} */ @Override protected void unlock() { batch = null; @@ -109,6 +113,7 @@ class RefTreeUpdate extends RefUpdate { } } + /** {@inheritDoc} */ @Override protected Result doUpdate(Result desiredResult) throws IOException { return run(newRef(getName(), getNewObjectId()), desiredResult); @@ -124,11 +129,13 @@ class RefTreeUpdate extends RefUpdate { return new ObjectIdRef.PeeledNonTag(LOOSE, name, id); } + /** {@inheritDoc} */ @Override protected Result doDelete(Result desiredResult) throws IOException { return run(null, desiredResult); } + /** {@inheritDoc} */ @Override protected Result doLink(String target) throws IOException { Ref dst = new ObjectIdRef.Unpeeled(NEW, target, null); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/AbbreviatedObjectId.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/AbbreviatedObjectId.java index 0567051a90..425f7f689a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/AbbreviatedObjectId.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/AbbreviatedObjectId.java @@ -52,7 +52,7 @@ import org.eclipse.jgit.util.NB; import org.eclipse.jgit.util.RawParseUtils; /** - * A prefix abbreviation of an {@link ObjectId}. + * A prefix abbreviation of an {@link org.eclipse.jgit.lib.ObjectId}. * <p> * Sometimes Git produces abbreviated SHA-1 strings, using sufficient leading * digits from the ObjectId name to still be unique within the repository the @@ -109,13 +109,14 @@ public final class AbbreviatedObjectId implements Serializable { } /** - * Convert an AbbreviatedObjectId from an {@link AnyObjectId}. + * Convert an AbbreviatedObjectId from an + * {@link org.eclipse.jgit.lib.AnyObjectId}. * <p> * This method copies over all bits of the Id, and is therefore complete * (see {@link #isComplete()}). * * @param id - * the {@link ObjectId} to convert from. + * the {@link org.eclipse.jgit.lib.ObjectId} to convert from. * @return the converted object id. */ public static final AbbreviatedObjectId fromObjectId(AnyObjectId id) { @@ -205,17 +206,29 @@ public final class AbbreviatedObjectId implements Serializable { w5 = new_5; } - /** @return number of hex digits appearing in this id */ + /** + * Get number of hex digits appearing in this id. + * + * @return number of hex digits appearing in this id. + */ public int length() { return nibbles; } - /** @return true if this ObjectId is actually a complete id. */ + /** + * Whether this ObjectId is actually a complete id. + * + * @return true if this ObjectId is actually a complete id. + */ public boolean isComplete() { return length() == Constants.OBJECT_ID_STRING_LENGTH; } - /** @return a complete ObjectId; null if {@link #isComplete()} is false */ + /** + * A complete ObjectId; null if {@link #isComplete()} is false + * + * @return a complete ObjectId; null if {@link #isComplete()} is false + */ public ObjectId toObjectId() { return isComplete() ? new ObjectId(w1, w2, w3, w4, w5) : null; } @@ -325,7 +338,11 @@ public final class AbbreviatedObjectId implements Serializable { return NB.compareUInt32(w5, mask(5, bs[p + 4])); } - /** @return value for a fan-out style map, only valid of length >= 2. */ + /** + * Get value for a fan-out style map, only valid of length >= 2. + * + * @return value for a fan-out style map, only valid of length >= 2. + */ public final int getFirstByte() { return w1 >>> 24; } @@ -334,11 +351,13 @@ public final class AbbreviatedObjectId implements Serializable { return mask(nibbles, word, v); } + /** {@inheritDoc} */ @Override public int hashCode() { return w1; } + /** {@inheritDoc} */ @Override public boolean equals(final Object o) { if (o instanceof AbbreviatedObjectId) { @@ -350,6 +369,8 @@ public final class AbbreviatedObjectId implements Serializable { } /** + * Get string form of the abbreviation, in lower case hexadecimal. + * * @return string form of the abbreviation, in lower case hexadecimal. */ public final String name() { @@ -375,6 +396,7 @@ public final class AbbreviatedObjectId implements Serializable { return new String(b, 0, nibbles); } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/AnyObjectId.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/AnyObjectId.java index f964bf2b4f..58477657f6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/AnyObjectId.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/AnyObjectId.java @@ -53,9 +53,9 @@ import org.eclipse.jgit.util.NB; /** * A (possibly mutable) SHA-1 abstraction. * <p> - * If this is an instance of {@link MutableObjectId} the concept of equality - * with this instance can alter at any time, if this instance is modified to - * represent a different object name. + * If this is an instance of {@link org.eclipse.jgit.lib.MutableObjectId} the + * concept of equality with this instance can alter at any time, if this + * instance is modified to represent a different object name. */ public abstract class AnyObjectId implements Comparable<AnyObjectId> { @@ -117,14 +117,16 @@ public abstract class AnyObjectId implements Comparable<AnyObjectId> { * * @param index * index of the byte to obtain from the raw form of the ObjectId. - * Must be in range [0, {@link Constants#OBJECT_ID_LENGTH}). + * Must be in range [0, + * {@link org.eclipse.jgit.lib.Constants#OBJECT_ID_LENGTH}). * @return the value of the requested byte at {@code index}. Returned values * are unsigned and thus are in the range [0,255] rather than the * signed byte range of [-128, 127]. - * @throws ArrayIndexOutOfBoundsException + * @throws java.lang.ArrayIndexOutOfBoundsException * {@code index} is less than 0, equal to - * {@link Constants#OBJECT_ID_LENGTH}, or greater than - * {@link Constants#OBJECT_ID_LENGTH}. + * {@link org.eclipse.jgit.lib.Constants#OBJECT_ID_LENGTH}, or + * greater than + * {@link org.eclipse.jgit.lib.Constants#OBJECT_ID_LENGTH}. */ public final int getByte(int index) { int w; @@ -152,12 +154,9 @@ public abstract class AnyObjectId implements Comparable<AnyObjectId> { } /** + * {@inheritDoc} + * <p> * Compare this ObjectId to another and obtain a sort ordering. - * - * @param other - * the other id to compare to. Must not be null. - * @return < 0 if this id comes before other; 0 if this id is equal to - * other; > 0 if this id comes after other. */ @Override public final int compareTo(final AnyObjectId other) { @@ -262,6 +261,7 @@ public abstract class AnyObjectId implements Comparable<AnyObjectId> { return abbr.prefixCompare(this) == 0; } + /** {@inheritDoc} */ @Override public final int hashCode() { return w2; @@ -278,6 +278,7 @@ public abstract class AnyObjectId implements Comparable<AnyObjectId> { return other != null ? equals(this, other) : false; } + /** {@inheritDoc} */ @Override public final boolean equals(final Object o) { if (o instanceof AnyObjectId) @@ -337,7 +338,7 @@ public abstract class AnyObjectId implements Comparable<AnyObjectId> { * * @param w * the stream to write to. - * @throws IOException + * @throws java.io.IOException * the stream writing failed. */ public void copyRawTo(final OutputStream w) throws IOException { @@ -361,7 +362,7 @@ public abstract class AnyObjectId implements Comparable<AnyObjectId> { * * @param w * the stream to copy to. - * @throws IOException + * @throws java.io.IOException * the stream writing failed. */ public void copyTo(final OutputStream w) throws IOException { @@ -422,7 +423,7 @@ public abstract class AnyObjectId implements Comparable<AnyObjectId> { * * @param w * the stream to copy to. - * @throws IOException + * @throws java.io.IOException * the stream writing failed. */ public void copyTo(final Writer w) throws IOException { @@ -438,7 +439,7 @@ public abstract class AnyObjectId implements Comparable<AnyObjectId> { * of object id (40 characters or larger). * @param w * the stream to copy to. - * @throws IOException + * @throws java.io.IOException * the stream writing failed. */ public void copyTo(final char[] tmp, final Writer w) throws IOException { @@ -488,6 +489,7 @@ public abstract class AnyObjectId implements Comparable<AnyObjectId> { dst[o--] = '0'; } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { @@ -495,6 +497,8 @@ public abstract class AnyObjectId implements Comparable<AnyObjectId> { } /** + * <p>name.</p> + * * @return string form of the SHA-1, in lower case hexadecimal. */ public final String name() { @@ -502,6 +506,8 @@ public abstract class AnyObjectId implements Comparable<AnyObjectId> { } /** + * Get string form of the SHA-1, in lower case hexadecimal. + * * @return string form of the SHA-1, in lower case hexadecimal. */ public final String getName() { @@ -511,9 +517,11 @@ public abstract class AnyObjectId implements Comparable<AnyObjectId> { /** * Return an abbreviation (prefix) of this object SHA-1. * <p> - * This implementation does not guarantee uniqueness. Callers should - * instead use {@link ObjectReader#abbreviate(AnyObjectId, int)} to obtain a - * unique abbreviation within the scope of a particular object database. + * This implementation does not guarantee uniqueness. Callers should instead + * use + * {@link org.eclipse.jgit.lib.ObjectReader#abbreviate(AnyObjectId, int)} to + * obtain a unique abbreviation within the scope of a particular object + * database. * * @param len * length of the abbreviated string. @@ -532,8 +540,8 @@ public abstract class AnyObjectId implements Comparable<AnyObjectId> { * Obtain an immutable copy of this current object name value. * <p> * Only returns <code>this</code> if this instance is an unsubclassed - * instance of {@link ObjectId}; otherwise a new instance is returned - * holding the same value. + * instance of {@link org.eclipse.jgit.lib.ObjectId}; otherwise a new + * instance is returned holding the same value. * <p> * This method is useful to shed any additional memory that may be tied to * the subclass, yet retain the unique identity of the object id for future diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncObjectLoaderQueue.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncObjectLoaderQueue.java index a3732eaacd..b4ea0e907f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncObjectLoaderQueue.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncObjectLoaderQueue.java @@ -63,30 +63,37 @@ public interface AsyncObjectLoaderQueue<T extends ObjectId> extends * Position this queue onto the next available result. * * Even if this method returns true, {@link #open()} may still throw - * {@link MissingObjectException} if the underlying object database was - * concurrently modified and the current object is no longer available. + * {@link org.eclipse.jgit.errors.MissingObjectException} if the underlying + * object database was concurrently modified and the current object is no + * longer available. * * @return true if there is a result available; false if the queue has * finished its input iteration. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the object does not exist. If the implementation is retaining * the application's objects {@link #getCurrent()} will be the * current object that is missing. There may be more results * still available, so the caller should continue invoking next * to examine another result. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public boolean next() throws MissingObjectException, IOException; /** + * Get the current object, null if the implementation lost track. + * * @return the current object, null if the implementation lost track. * Implementations may for performance reasons discard the caller's * ObjectId and provider their own through {@link #getObjectId()}. */ public T getCurrent(); - /** @return the ObjectId of the current object. Never null. */ + /** + * Get the ObjectId of the current object. Never null. + * + * @return the ObjectId of the current object. Never null. + */ public ObjectId getObjectId(); /** @@ -105,7 +112,7 @@ public interface AsyncObjectLoaderQueue<T extends ObjectId> extends * current object that is missing. There may be more results * still available, so the caller should continue invoking next * to examine another result. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public ObjectLoader open() throws IOException; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncObjectSizeQueue.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncObjectSizeQueue.java index c9667242a4..03efcd295e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncObjectSizeQueue.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncObjectSizeQueue.java @@ -64,27 +64,37 @@ public interface AsyncObjectSizeQueue<T extends ObjectId> extends * * @return true if there is a result available; false if the queue has * finished its input iteration. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the object does not exist. If the implementation is retaining * the application's objects {@link #getCurrent()} will be the * current object that is missing. There may be more results * still available, so the caller should continue invoking next * to examine another result. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public boolean next() throws MissingObjectException, IOException; /** + * <p>getCurrent.</p> + * * @return the current object, null if the implementation lost track. * Implementations may for performance reasons discard the caller's * ObjectId and provider their own through {@link #getObjectId()}. */ public T getCurrent(); - /** @return the ObjectId of the current object. Never null. */ + /** + * Get the ObjectId of the current object. Never null. + * + * @return the ObjectId of the current object. Never null. + */ public ObjectId getObjectId(); - /** @return the size of the current object. */ + /** + * Get the size of the current object. + * + * @return the size of the current object. + */ public long getSize(); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncOperation.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncOperation.java index fb73dc1c5d..00555b0907 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncOperation.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncOperation.java @@ -70,6 +70,8 @@ public interface AsyncOperation { */ public boolean cancel(boolean mayInterruptIfRunning); - /** Release resources used by the operation, including cancellation. */ + /** + * Release resources used by the operation, including cancellation. + */ public void release(); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BaseRepositoryBuilder.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BaseRepositoryBuilder.java index 825c1f704a..2c7c6cb060 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BaseRepositoryBuilder.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BaseRepositoryBuilder.java @@ -160,7 +160,11 @@ public class BaseRepositoryBuilder<B extends BaseRepositoryBuilder, R extends Re return self(); } - /** @return the file system abstraction, or null if not set. */ + /** + * Get the file system abstraction, or null if not set. + * + * @return the file system abstraction, or null if not set. + */ public FS getFS() { return fs; } @@ -182,7 +186,11 @@ public class BaseRepositoryBuilder<B extends BaseRepositoryBuilder, R extends Re return self(); } - /** @return the meta data directory; null if not set. */ + /** + * Get the meta data directory; null if not set. + * + * @return the meta data directory; null if not set. + */ public File getGitDir() { return gitDir; } @@ -200,7 +208,11 @@ public class BaseRepositoryBuilder<B extends BaseRepositoryBuilder, R extends Re return self(); } - /** @return the object directory; null if not set. */ + /** + * Get the object directory; null if not set. + * + * @return the object directory; null if not set. + */ public File getObjectDirectory() { return objectDirectory; } @@ -262,7 +274,11 @@ public class BaseRepositoryBuilder<B extends BaseRepositoryBuilder, R extends Re return self(); } - /** @return ordered array of alternate directories; null if non were set. */ + /** + * Get ordered array of alternate directories; null if non were set. + * + * @return ordered array of alternate directories; null if non were set. + */ public File[] getAlternateObjectDirectories() { final List<File> alts = alternateObjectDirectories; if (alts == null) @@ -285,7 +301,11 @@ public class BaseRepositoryBuilder<B extends BaseRepositoryBuilder, R extends Re return self(); } - /** @return true if this repository was forced bare by {@link #setBare()}. */ + /** + * Whether this repository was forced bare by {@link #setBare()}. + * + * @return true if this repository was forced bare by {@link #setBare()}. + */ public boolean isBare() { return bare; } @@ -303,7 +323,11 @@ public class BaseRepositoryBuilder<B extends BaseRepositoryBuilder, R extends Re return self(); } - /** @return true if the repository must exist before being opened. */ + /** + * Whether the repository must exist before being opened. + * + * @return true if the repository must exist before being opened. + */ public boolean isMustExist() { return mustExist; } @@ -320,7 +344,11 @@ public class BaseRepositoryBuilder<B extends BaseRepositoryBuilder, R extends Re return self(); } - /** @return the work tree directory, or null if not set. */ + /** + * Get the work tree directory, or null if not set. + * + * @return the work tree directory, or null if not set. + */ public File getWorkTree() { return workTree; } @@ -341,7 +369,11 @@ public class BaseRepositoryBuilder<B extends BaseRepositoryBuilder, R extends Re return self(); } - /** @return the index file location, or null if not set. */ + /** + * Get the index file location, or null if not set. + * + * @return the index file location, or null if not set. + */ public File getIndexFile() { return indexFile; } @@ -544,10 +576,10 @@ public class BaseRepositoryBuilder<B extends BaseRepositoryBuilder, R extends Re * exception is thrown to the caller. * * @return {@code this} - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * insufficient parameters were set, or some parameters are * incompatible with one another. - * @throws IOException + * @throws java.io.IOException * the repository could not be accessed to configure the rest of * the builder's parameters. */ @@ -569,9 +601,9 @@ public class BaseRepositoryBuilder<B extends BaseRepositoryBuilder, R extends Re * @return a repository matching this configuration. The caller is * responsible to close the repository instance when it is no longer * needed. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * insufficient parameters were set. - * @throws IOException + * @throws java.io.IOException * the repository could not be accessed to configure the rest of * the builder's parameters. */ @@ -583,7 +615,9 @@ public class BaseRepositoryBuilder<B extends BaseRepositoryBuilder, R extends Re return repo; } - /** Require either {@code gitDir} or {@code workTree} to be set. */ + /** + * Require either {@code gitDir} or {@code workTree} to be set. + */ protected void requireGitDirOrWorkTree() { if (getGitDir() == null && getWorkTree() == null) throw new IllegalArgumentException( @@ -593,7 +627,7 @@ public class BaseRepositoryBuilder<B extends BaseRepositoryBuilder, R extends Re /** * Perform standard gitDir initialization. * - * @throws IOException + * @throws java.io.IOException * the repository could not be accessed */ protected void setupGitDir() throws IOException { @@ -615,7 +649,7 @@ public class BaseRepositoryBuilder<B extends BaseRepositoryBuilder, R extends Re * end after the repository has been identified and its configuration is * available for inspection. * - * @throws IOException + * @throws java.io.IOException * the repository configuration could not be read. */ protected void setupWorkTree() throws IOException { @@ -642,7 +676,7 @@ public class BaseRepositoryBuilder<B extends BaseRepositoryBuilder, R extends Re /** * Configure the internal implementation details of the repository. * - * @throws IOException + * @throws java.io.IOException * the repository could not be accessed */ protected void setupInternals() throws IOException { @@ -654,7 +688,7 @@ public class BaseRepositoryBuilder<B extends BaseRepositoryBuilder, R extends Re * Get the cached repository configuration, loading if not yet available. * * @return the configuration of the repository. - * @throws IOException + * @throws java.io.IOException * the configuration is not available, or is badly formed. */ protected Config getConfig() throws IOException { @@ -670,7 +704,7 @@ public class BaseRepositoryBuilder<B extends BaseRepositoryBuilder, R extends Re * empty configuration if gitDir was not set. * * @return the repository's configuration. - * @throws IOException + * @throws java.io.IOException * the configuration is not available. */ protected Config loadConfig() throws IOException { @@ -728,12 +762,20 @@ public class BaseRepositoryBuilder<B extends BaseRepositoryBuilder, R extends Re return null; } - /** @return the configured FS, or {@link FS#DETECTED}. */ + /** + * Get the configured FS, or {@link FS#DETECTED}. + * + * @return the configured FS, or {@link FS#DETECTED}. + */ protected FS safeFS() { return getFS() != null ? getFS() : FS.DETECTED; } - /** @return {@code this} */ + /** + * Get this object + * + * @return {@code this} + */ @SuppressWarnings("unchecked") protected final B self() { return (B) this; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BatchRefUpdate.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BatchRefUpdate.java index bcf9065dd2..6919f7ef0f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BatchRefUpdate.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BatchRefUpdate.java @@ -135,6 +135,9 @@ public class BatchRefUpdate { } /** + * Whether the batch update will permit a non-fast-forward update to an + * existing reference. + * * @return true if the batch update will permit a non-fast-forward update to * an existing reference. */ @@ -154,7 +157,11 @@ public class BatchRefUpdate { return this; } - /** @return identity of the user making the change in the reflog. */ + /** + * Get identity of the user making the change in the reflog. + * + * @return identity of the user making the change in the reflog. + */ public PersonIdent getRefLogIdent() { return refLogIdent; } @@ -193,7 +200,8 @@ public class BatchRefUpdate { * such as fast-forward or force-update. * <p> * Describes the default for commands in this batch that do not override it - * with {@link ReceiveCommand#setRefLogMessage(String, boolean)}. + * with + * {@link org.eclipse.jgit.transport.ReceiveCommand#setRefLogMessage(String, boolean)}. * * @return true if the message should include the result. */ @@ -204,21 +212,23 @@ public class BatchRefUpdate { /** * Set the message to include in the reflog. * <p> - * Repository implementations may limit which reflogs are written by default, - * based on the project configuration. If a repo is not configured to write - * logs for this ref by default, setting the message alone may have no effect. - * To indicate that the repo should write logs for this update in spite of - * configured defaults, use {@link #setForceRefLog(boolean)}. + * Repository implementations may limit which reflogs are written by + * default, based on the project configuration. If a repo is not configured + * to write logs for this ref by default, setting the message alone may have + * no effect. To indicate that the repo should write logs for this update in + * spite of configured defaults, use {@link #setForceRefLog(boolean)}. * <p> * Describes the default for commands in this batch that do not override it - * with {@link ReceiveCommand#setRefLogMessage(String, boolean)}. + * with + * {@link org.eclipse.jgit.transport.ReceiveCommand#setRefLogMessage(String, boolean)}. * * @param msg - * the message to describe this change. If null and appendStatus is - * false, the reflog will not be updated. + * the message to describe this change. If null and appendStatus + * is false, the reflog will not be updated. * @param appendStatus * true if the status of the ref change (fast-forward or - * forced-update) should be appended to the user supplied message. + * forced-update) should be appended to the user supplied + * message. * @return {@code this}. */ public BatchRefUpdate setRefLogMessage(String msg, boolean appendStatus) { @@ -286,12 +296,15 @@ public class BatchRefUpdate { * {@code REJECTED_OTHER_REASON}. * <p> * This method only works if the underlying ref database supports atomic - * transactions, i.e. {@link RefDatabase#performsAtomicTransactions()} returns - * true. Calling this method with true if the underlying ref database does not - * support atomic transactions will cause all commands to fail with {@code + * transactions, i.e. + * {@link org.eclipse.jgit.lib.RefDatabase#performsAtomicTransactions()} + * returns true. Calling this method with true if the underlying ref + * database does not support atomic transactions will cause all commands to + * fail with {@code * REJECTED_OTHER_REASON}. * - * @param atomic whether updates should be atomic. + * @param atomic + * whether updates should be atomic. * @return {@code this} * @since 4.4 */ @@ -301,6 +314,8 @@ public class BatchRefUpdate { } /** + * Whether updates should be atomic. + * * @return atomic whether updates should be atomic. * @since 4.4 */ @@ -335,7 +350,11 @@ public class BatchRefUpdate { return pushCert; } - /** @return commands this update will process. */ + /** + * Get commands this update will process. + * + * @return commands this update will process. + */ public List<ReceiveCommand> getCommands() { return Collections.unmodifiableList(commands); } @@ -401,6 +420,8 @@ public class BatchRefUpdate { } /** + * Get list of timestamps the batch must wait for. + * * @return list of timestamps the batch must wait for. * @since 4.6 */ @@ -415,6 +436,7 @@ public class BatchRefUpdate { * Request the batch to wait for the affected timestamps to resolve. * * @param ts + * a {@link org.eclipse.jgit.util.time.ProposedTimestamp} object. * @return {@code this}. * @since 4.6 */ @@ -434,7 +456,7 @@ public class BatchRefUpdate { * <p> * Implementations must respect the atomicity requirements of the underlying * database as described in {@link #setAtomic(boolean)} and - * {@link RefDatabase#performsAtomicTransactions()}. + * {@link org.eclipse.jgit.lib.RefDatabase#performsAtomicTransactions()}. * * @param walk * a RevWalk to parse tags in case the storage system wants to @@ -443,7 +465,7 @@ public class BatchRefUpdate { * progress monitor to receive update status on. * @param options * a list of option strings; set null to execute without - * @throws IOException + * @throws java.io.IOException * the database is unable to accept the update. Individual * command status must be tested to determine if there is a * partial failure, or a total failure. @@ -601,7 +623,7 @@ public class BatchRefUpdate { * store them pre-peeled, a common performance optimization. * @param monitor * progress monitor to receive update status on. - * @throws IOException + * @throws java.io.IOException * the database is unable to accept the update. Individual * command status must be tested to determine if there is a * partial failure, or a total failure. @@ -658,7 +680,7 @@ public class BatchRefUpdate { * @param cmd * specific command the update should be created to copy. * @return a single reference update command. - * @throws IOException + * @throws java.io.IOException * the reference database cannot make a new update object for * the given reference. */ @@ -746,6 +768,7 @@ public class BatchRefUpdate { : isForceRefLog(); } + /** {@inheritDoc} */ @Override public String toString() { StringBuilder r = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BatchingProgressMonitor.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BatchingProgressMonitor.java index a75293d6cb..4eb7b7fb78 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BatchingProgressMonitor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BatchingProgressMonitor.java @@ -48,7 +48,9 @@ import java.util.concurrent.TimeUnit; import org.eclipse.jgit.lib.internal.WorkQueue; -/** ProgressMonitor that batches update events. */ +/** + * ProgressMonitor that batches update events. + */ public abstract class BatchingProgressMonitor implements ProgressMonitor { private long delayStartTime; @@ -70,11 +72,13 @@ public abstract class BatchingProgressMonitor implements ProgressMonitor { delayStartUnit = unit; } + /** {@inheritDoc} */ @Override public void start(int totalTasks) { // Ignore the number of tasks. } + /** {@inheritDoc} */ @Override public void beginTask(String title, int work) { endTask(); @@ -83,12 +87,14 @@ public abstract class BatchingProgressMonitor implements ProgressMonitor { task.delay(delayStartTime, delayStartUnit); } + /** {@inheritDoc} */ @Override public void update(int completed) { if (task != null) task.update(this, completed); } + /** {@inheritDoc} */ @Override public void endTask() { if (task != null) { @@ -97,6 +103,7 @@ public abstract class BatchingProgressMonitor implements ProgressMonitor { } } + /** {@inheritDoc} */ @Override public boolean isCancelled() { return false; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BitmapIndex.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BitmapIndex.java index 00f42a49a5..fc354db113 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BitmapIndex.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BitmapIndex.java @@ -63,7 +63,11 @@ public interface BitmapIndex { */ Bitmap getBitmap(AnyObjectId objectId); - /** @return a new {@code BitmapBuilder} based on the values in the index. */ + /** + * Create a new {@code BitmapBuilder} based on the values in the index. + * + * @return a new {@code BitmapBuilder} based on the values in the index. + */ BitmapBuilder newBitmapBuilder(); /** diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BitmapObject.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BitmapObject.java index 4e0dc2cda1..f2917dc888 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BitmapObject.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BitmapObject.java @@ -50,7 +50,7 @@ package org.eclipse.jgit.lib; */ public abstract class BitmapObject { /** - * Get Git object type. See {@link Constants}. + * Get Git object type. See {@link org.eclipse.jgit.lib.Constants}. * * @return object type */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BlobBasedConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BlobBasedConfig.java index 8958ce7e85..3ff92dc739 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BlobBasedConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BlobBasedConfig.java @@ -73,7 +73,7 @@ public class BlobBasedConfig extends Config { * the base configuration file * @param blob * the byte array, should be UTF-8 encoded text. - * @throws ConfigInvalidException + * @throws org.eclipse.jgit.errors.ConfigInvalidException * the byte array is not a valid configuration format. */ public BlobBasedConfig(Config base, final byte[] blob) @@ -98,9 +98,9 @@ public class BlobBasedConfig extends Config { * the repository * @param objectId * the object identifier - * @throws IOException + * @throws java.io.IOException * the blob cannot be read from the repository. - * @throws ConfigInvalidException + * @throws org.eclipse.jgit.errors.ConfigInvalidException * the blob is not a valid configuration format. */ public BlobBasedConfig(Config base, Repository db, AnyObjectId objectId) @@ -134,11 +134,11 @@ public class BlobBasedConfig extends Config { * the tree (or commit) that contains the object * @param path * the path within the tree - * @throws FileNotFoundException + * @throws java.io.FileNotFoundException * the path does not exist in the commit's tree. - * @throws IOException + * @throws java.io.IOException * the tree and/or blob cannot be accessed. - * @throws ConfigInvalidException + * @throws org.eclipse.jgit.errors.ConfigInvalidException * the blob is not a valid configuration format. */ public BlobBasedConfig(Config base, Repository db, AnyObjectId treeish, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BlobObjectChecker.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BlobObjectChecker.java index 0fe63ae5b4..3fa3168327 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BlobObjectChecker.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BlobObjectChecker.java @@ -85,7 +85,7 @@ public interface BlobObjectChecker { * * @param id * identity of the object being checked. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * if any error was detected. */ void endBlob(AnyObjectId id) throws CorruptObjectException; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BranchConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BranchConfig.java index f1b7fb2172..596da0349c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BranchConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BranchConfig.java @@ -113,6 +113,8 @@ public class BranchConfig { } /** + * Get the full tracking branch name + * * @return the full tracking branch name or <code>null</code> if it could * not be determined */ @@ -129,6 +131,8 @@ public class BranchConfig { } /** + * Get the full remote-tracking branch name + * * @return the full remote-tracking branch name or {@code null} if it could * not be determined. If you also want local tracked branches use * {@link #getTrackingBranch()} instead. @@ -143,6 +147,9 @@ public class BranchConfig { } /** + * Whether the "remote" setting points to the local repository (with + * {@value #LOCAL_REPOSITORY}) + * * @return {@code true} if the "remote" setting points to the local * repository (with {@value #LOCAL_REPOSITORY}), false otherwise * @since 3.5 @@ -152,6 +159,8 @@ public class BranchConfig { } /** + * Get the remote this branch is configured to fetch from/push to + * * @return the remote this branch is configured to fetch from/push to, or * {@code null} if not defined * @since 3.5 @@ -162,6 +171,8 @@ public class BranchConfig { } /** + * Get the name of the upstream branch as it is called on the remote + * * @return the name of the upstream branch as it is called on the remote, or * {@code null} if not defined * @since 3.5 @@ -172,6 +183,8 @@ public class BranchConfig { } /** + * Whether the branch is configured to be rebased + * * @return {@code true} if the branch is configured to be rebased * @since 3.5 */ @@ -182,7 +195,7 @@ public class BranchConfig { /** * Retrieves the config value of branch.[name].rebase. * - * @return the {@link BranchRebaseMode} + * @return the {@link org.eclipse.jgit.lib.BranchConfig.BranchRebaseMode} * @since 4.5 */ public BranchRebaseMode getRebaseMode() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BranchTrackingStatus.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BranchTrackingStatus.java index d4fccf9070..ac1529f990 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/BranchTrackingStatus.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/BranchTrackingStatus.java @@ -65,7 +65,7 @@ public class BranchTrackingStatus { * @param branchName * the local branch * @return the tracking status, or null if it is not known - * @throws IOException + * @throws java.io.IOException */ public static BranchTrackingStatus of(Repository repository, String branchName) throws IOException { @@ -119,6 +119,8 @@ public class BranchTrackingStatus { } /** + * Get full remote-tracking branch name + * * @return full remote-tracking branch name */ public String getRemoteTrackingBranch() { @@ -126,6 +128,9 @@ public class BranchTrackingStatus { } /** + * Get number of commits that the local branch is ahead of the + * remote-tracking branch + * * @return number of commits that the local branch is ahead of the * remote-tracking branch */ @@ -134,6 +139,9 @@ public class BranchTrackingStatus { } /** + * Get number of commits that the local branch is behind of the + * remote-tracking branch + * * @return number of commits that the local branch is behind of the * remote-tracking branch */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/CheckoutEntry.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/CheckoutEntry.java index 34d0b14adf..cfc0cc86d1 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/CheckoutEntry.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/CheckoutEntry.java @@ -8,11 +8,15 @@ package org.eclipse.jgit.lib; public interface CheckoutEntry { /** + * Get the name of the branch before checkout + * * @return the name of the branch before checkout */ public abstract String getFromBranch(); /** + * Get the name of the branch after checkout + * * @return the name of the branch after checkout */ public abstract String getToBranch(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/CommitBuilder.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/CommitBuilder.java index c5c488dac3..2217fde049 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/CommitBuilder.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/CommitBuilder.java @@ -88,13 +88,19 @@ public class CommitBuilder { private Charset encoding; - /** Initialize an empty commit. */ + /** + * Initialize an empty commit. + */ public CommitBuilder() { parentIds = EMPTY_OBJECTID_LIST; encoding = Constants.CHARSET; } - /** @return id of the root tree listing this commit's snapshot. */ + /** + * Get id of the root tree listing this commit's snapshot. + * + * @return id of the root tree listing this commit's snapshot. + */ public ObjectId getTreeId() { return treeId; } @@ -109,7 +115,11 @@ public class CommitBuilder { treeId = id.copy(); } - /** @return the author of this commit (who wrote it). */ + /** + * Get the author of this commit (who wrote it). + * + * @return the author of this commit (who wrote it). + */ public PersonIdent getAuthor() { return author; } @@ -124,7 +134,11 @@ public class CommitBuilder { author = newAuthor; } - /** @return the committer and commit time for this object. */ + /** + * Get the committer and commit time for this object. + * + * @return the committer and commit time for this object. + */ public PersonIdent getCommitter() { return committer; } @@ -139,7 +153,11 @@ public class CommitBuilder { committer = newCommitter; } - /** @return the ancestors of this commit. Never null. */ + /** + * Get the ancestors of this commit. + * + * @return the ancestors of this commit. Never null. + */ public ObjectId[] getParentIds() { return parentIds; } @@ -210,7 +228,11 @@ public class CommitBuilder { } } - /** @return the complete commit message. */ + /** + * Get the complete commit message. + * + * @return the complete commit message. + */ public String getMessage() { return message; } @@ -229,7 +251,8 @@ public class CommitBuilder { * Set the encoding for the commit information * * @param encodingName - * the encoding name. See {@link Charset#forName(String)}. + * the encoding name. See + * {@link java.nio.charset.Charset#forName(String)}. */ public void setEncoding(String encodingName) { encoding = Charset.forName(encodingName); @@ -245,7 +268,11 @@ public class CommitBuilder { encoding = enc; } - /** @return the encoding that should be used for the commit message text. */ + /** + * Get the encoding that should be used for the commit message text. + * + * @return the encoding that should be used for the commit message text. + */ public Charset getEncoding() { return encoding; } @@ -255,7 +282,7 @@ public class CommitBuilder { * * @return this object in the canonical commit format, suitable for storage * in a repository. - * @throws UnsupportedEncodingException + * @throws java.io.UnsupportedEncodingException * the encoding specified by {@link #getEncoding()} is not * supported by this Java runtime. */ @@ -314,7 +341,7 @@ public class CommitBuilder { * * @return this object in the canonical commit format, suitable for storage * in a repository. - * @throws UnsupportedEncodingException + * @throws java.io.UnsupportedEncodingException * the encoding specified by {@link #getEncoding()} is not * supported by this Java runtime. */ @@ -322,6 +349,7 @@ public class CommitBuilder { return build(); } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Config.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Config.java index b0f5c2cf4e..a6313f0cc5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Config.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Config.java @@ -60,6 +60,7 @@ import java.util.Set; import java.util.concurrent.TimeUnit; import java.util.concurrent.atomic.AtomicReference; +import org.eclipse.jgit.annotations.Nullable; import org.eclipse.jgit.errors.ConfigInvalidException; import org.eclipse.jgit.events.ConfigChangedEvent; import org.eclipse.jgit.events.ConfigChangedListener; @@ -67,6 +68,7 @@ import org.eclipse.jgit.events.ListenerHandle; import org.eclipse.jgit.events.ListenerList; import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.transport.RefSpec; +import org.eclipse.jgit.util.RawParseUtils; /** * Git style {@code .config}, {@code .gitconfig}, {@code .gitmodules} file. @@ -106,7 +108,9 @@ public class Config { */ static final String MAGIC_EMPTY_VALUE = new String(); - /** Create a configuration with no default fallback. */ + /** + * Create a configuration with no default fallback. + */ public Config() { this(null); } @@ -124,8 +128,8 @@ public class Config { } /** - * Globally sets a {@link TypedConfigGetter} that is subsequently used to - * read typed values from all git configs. + * Globally sets a {@link org.eclipse.jgit.lib.TypedConfigGetter} that is + * subsequently used to read typed values from all git configs. * * @param getter * to use; if {@code null} use the default getter. @@ -142,54 +146,96 @@ public class Config { * the value to escape * @return the escaped value */ - private static String escapeValue(final String x) { - boolean inquote = false; - int lineStart = 0; - final StringBuilder r = new StringBuilder(x.length()); + static String escapeValue(String x) { + if (x.isEmpty()) { + return ""; //$NON-NLS-1$ + } + + boolean needQuote = x.charAt(0) == ' ' || x.charAt(x.length() - 1) == ' '; + StringBuilder r = new StringBuilder(x.length()); for (int k = 0; k < x.length(); k++) { - final char c = x.charAt(k); + char c = x.charAt(k); + // git-config(1) lists the limited set of supported escape sequences, but + // the documentation is otherwise not especially normative. In particular, + // which ones of these produce and/or require escaping and/or quoting + // around them is not documented and was discovered by trial and error. + // In summary: + // + // * Quotes are only required if there is leading/trailing whitespace or a + // comment character. + // * Bytes that have a supported escape sequence are escaped, except for + // \b for some reason which isn't. + // * Needing an escape sequence is not sufficient reason to quote the + // value. switch (c) { + case '\0': + // Unix command line calling convention cannot pass a '\0' as an + // argument, so there is no equivalent way in C git to store a null byte + // in a config value. + throw new IllegalArgumentException( + JGitText.get().configValueContainsNullByte); + case '\n': - if (inquote) { - r.append('"'); - inquote = false; - } - r.append("\\n\\\n"); //$NON-NLS-1$ - lineStart = r.length(); + r.append('\\').append('n'); break; case '\t': - r.append("\\t"); //$NON-NLS-1$ + r.append('\\').append('t'); break; case '\b': - r.append("\\b"); //$NON-NLS-1$ + // Doesn't match `git config foo.bar $'x\by'`, which doesn't escape the + // \x08, but since both escaped and unescaped forms are readable, we'll + // prefer internal consistency here. + r.append('\\').append('b'); break; case '\\': - r.append("\\\\"); //$NON-NLS-1$ + r.append('\\').append('\\'); break; case '"': - r.append("\\\""); //$NON-NLS-1$ + r.append('\\').append('"'); break; - case ';': case '#': - if (!inquote) { - r.insert(lineStart, '"'); - inquote = true; - } + case ';': + needQuote = true; r.append(c); break; - case ' ': - if (!inquote && r.length() > 0 - && r.charAt(r.length() - 1) == ' ') { - r.insert(lineStart, '"'); - inquote = true; - } - r.append(' '); + default: + r.append(c); + break; + } + } + + return needQuote ? '"' + r.toString() + '"' : r.toString(); + } + + static String escapeSubsection(String x) { + if (x.isEmpty()) { + return "\"\""; //$NON-NLS-1$ + } + + StringBuilder r = new StringBuilder(x.length() + 2).append('"'); + for (int k = 0; k < x.length(); k++) { + char c = x.charAt(k); + + // git-config(1) lists the limited set of supported escape sequences + // (which is even more limited for subsection names than for values). + switch (c) { + case '\0': + throw new IllegalArgumentException( + JGitText.get().configSubsectionContainsNullByte); + + case '\n': + throw new IllegalArgumentException( + JGitText.get().configSubsectionContainsNewline); + + case '\\': + case '"': + r.append('\\').append(c); break; default: @@ -197,10 +243,8 @@ public class Config { break; } } - if (inquote) { - r.append('"'); - } - return r.toString(); + + return r.append('"').toString(); } /** @@ -312,8 +356,6 @@ public class Config { /** * Parse an enumeration from the configuration. * - * @param <T> - * type of the enumeration object. * @param section * section the key is grouped within. * @param subsection @@ -346,8 +388,6 @@ public class Config { /** * Parse an enumeration from the configuration. * - * @param <T> - * type of the enumeration object. * @param all * all possible values in the enumeration which should be * recognized. Typically {@code EnumType.values()}. @@ -443,7 +483,8 @@ public class Config { } /** - * Parse a list of {@link RefSpec}s from the configuration. + * Parse a list of {@link org.eclipse.jgit.transport.RefSpec}s from the + * configuration. * * @param section * section the key is in. @@ -451,7 +492,8 @@ public class Config { * subsection the key is in, or null if not in a subsection. * @param name * the key name. - * @return a possibly empty list of {@link RefSpec}s + * @return a possibly empty list of + * {@link org.eclipse.jgit.transport.RefSpec}s * @since 4.9 */ public List<RefSpec> getRefSpecs(String section, String subsection, @@ -460,6 +502,9 @@ public class Config { } /** + * Get set of all subsections of specified section within this configuration + * and its base configuration + * * @param section * section to search for. * @return set of all subsections of specified section within this @@ -473,16 +518,20 @@ public class Config { } /** - * @return the sections defined in this {@link Config}. The set's iterator - * returns sections in the order they are declared by the - * configuration starting from this instance and progressing through - * the base. + * Get the sections defined in this {@link org.eclipse.jgit.lib.Config}. + * + * @return the sections defined in this {@link org.eclipse.jgit.lib.Config}. + * The set's iterator returns sections in the order they are + * declared by the configuration starting from this instance and + * progressing through the base. */ public Set<String> getSections() { return getState().getSections(); } /** + * Get the list of names defined for this section + * * @param section * the section * @return the list of names defined for this section @@ -492,6 +541,8 @@ public class Config { } /** + * Get the list of names defined for this subsection + * * @param section * the section * @param subsection @@ -503,6 +554,8 @@ public class Config { } /** + * Get the list of names defined for this section + * * @param section * the section * @param recursive @@ -516,6 +569,8 @@ public class Config { } /** + * Get the list of names defined for this section + * * @param section * the section * @param subsection @@ -572,7 +627,8 @@ public class Config { * Adds a listener to be notified about changes. * <p> * Clients are supposed to remove the listeners after they are done with - * them using the {@link ListenerHandle#remove()} method + * them using the {@link org.eclipse.jgit.events.ListenerHandle#remove()} + * method * * @param listener * the listener @@ -727,8 +783,6 @@ public class Config { * name = value * </pre> * - * @param <T> - * type of the enumeration object. * @param section * section name, e.g "branch" * @param subsection @@ -948,6 +1002,8 @@ public class Config { } /** + * Get this configuration, formatted as a Git style text file. + * * @return this configuration, formatted as a Git style text file. */ public String toText() { @@ -997,7 +1053,7 @@ public class Config { * * @param text * Git style text file listing configuration properties. - * @throws ConfigInvalidException + * @throws org.eclipse.jgit.errors.ConfigInvalidException * the text supplied is not formatted correctly. No changes were * made to {@code this}. */ @@ -1050,7 +1106,7 @@ public class Config { e.section = readSectionName(in); input = in.read(); if ('"' == input) { - e.subsection = readValue(in, true, '"'); + e.subsection = readSubsectionName(in); input = in.read(); } if (']' != input) @@ -1067,7 +1123,11 @@ public class Config { e.name = e.name.substring(0, e.name.length() - 1); e.value = MAGIC_EMPTY_VALUE; } else - e.value = readValue(in, false, -1); + e.value = readValue(in); + + if (e.section.equals("include")) { //$NON-NLS-1$ + addIncludedConfig(newEntries, e, depth); + } } else throw new ConfigInvalidException(JGitText.get().invalidLineInConfigFile); } @@ -1075,6 +1135,45 @@ public class Config { return newEntries; } + /** + * Read the included config from the specified (possibly) relative path + * + * @param relPath + * possibly relative path to the included config, as specified in + * this config + * @return the read bytes, or null if the included config should be ignored + * @throws org.eclipse.jgit.errors.ConfigInvalidException + * if something went wrong while reading the config + * @since 4.10 + */ + @Nullable + protected byte[] readIncludedConfig(String relPath) + throws ConfigInvalidException { + return null; + } + + private void addIncludedConfig(final List<ConfigLine> newEntries, + ConfigLine line, int depth) throws ConfigInvalidException { + if (!line.name.equals("path") || //$NON-NLS-1$ + line.value == null || line.value.equals(MAGIC_EMPTY_VALUE)) { + throw new ConfigInvalidException( + JGitText.get().invalidLineInConfigFile); + } + byte[] bytes = readIncludedConfig(line.value); + if (bytes == null) { + return; + } + + String decoded; + if (isUtf8(bytes)) { + decoded = RawParseUtils.decode(RawParseUtils.UTF8_CHARSET, bytes, 3, + bytes.length); + } else { + decoded = RawParseUtils.decode(bytes); + } + newEntries.addAll(fromTextRecurse(decoded, depth + 1)); + } + private ConfigSnapshot newState() { return new ConfigSnapshot(Collections.<ConfigLine> emptyList(), getBaseState()); @@ -1191,10 +1290,9 @@ public class Config { return name.toString(); } - private static String readValue(final StringReader in, boolean quote, - final int eol) throws ConfigInvalidException { - final StringBuilder value = new StringBuilder(); - boolean space = false; + private static String readSubsectionName(StringReader in) + throws ConfigInvalidException { + StringBuilder r = new StringBuilder(); for (;;) { int c = in.read(); if (c < 0) { @@ -1202,30 +1300,81 @@ public class Config { } if ('\n' == c) { - if (quote) - throw new ConfigInvalidException(JGitText.get().newlineInQuotesNotAllowed); + throw new ConfigInvalidException( + JGitText.get().newlineInQuotesNotAllowed); + } + if ('\\' == c) { + c = in.read(); + switch (c) { + case -1: + throw new ConfigInvalidException(JGitText.get().endOfFileInEscape); + + case '\\': + case '"': + r.append((char) c); + continue; + + default: + // C git simply drops backslashes if the escape sequence is not + // recognized. + r.append((char) c); + continue; + } + } + if ('"' == c) { + break; + } + + r.append((char) c); + } + return r.toString(); + } + + private static String readValue(final StringReader in) + throws ConfigInvalidException { + StringBuilder value = new StringBuilder(); + StringBuilder trailingSpaces = null; + boolean quote = false; + boolean inLeadingSpace = true; + + for (;;) { + int c = in.read(); + if (c < 0) { + break; + } + if ('\n' == c) { + if (quote) { + throw new ConfigInvalidException( + JGitText.get().newlineInQuotesNotAllowed); + } in.reset(); break; } - if (eol == c) + if (!quote && (';' == c || '#' == c)) { + if (trailingSpaces != null) { + trailingSpaces.setLength(0); + } + in.reset(); break; + } - if (!quote) { - if (Character.isWhitespace((char) c)) { - space = true; + char cc = (char) c; + if (Character.isWhitespace(cc)) { + if (inLeadingSpace) { continue; } - if (';' == c || '#' == c) { - in.reset(); - break; + if (trailingSpaces == null) { + trailingSpaces = new StringBuilder(); + } + trailingSpaces.append(cc); + continue; + } else { + inLeadingSpace = false; + if (trailingSpaces != null) { + value.append(trailingSpaces); + trailingSpaces.setLength(0); } - } - - if (space) { - if (value.length() > 0) - value.append(' '); - space = false; } if ('\\' == c) { @@ -1262,7 +1411,7 @@ public class Config { continue; } - value.append((char) c); + value.append(cc); } return value.length() > 0 ? value.toString() : null; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ConfigLine.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ConfigLine.java index 8a49bdb4f3..d5f1d8f085 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ConfigLine.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ConfigLine.java @@ -112,6 +112,7 @@ class ConfigLine { return a.equals(b); } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Constants.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Constants.java index 5bfccda15c..dad5871dcf 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Constants.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Constants.java @@ -55,7 +55,9 @@ import org.eclipse.jgit.errors.CorruptObjectException; import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.util.MutableInteger; -/** Misc. constants used throughout JGit. */ +/** + * Misc. constants used throughout JGit. + */ @SuppressWarnings("nls") public final class Constants { /** Hash function used natively by Git for all objects. */ @@ -446,7 +448,7 @@ public final class Constants { * Create a new digest function for objects. * * @return a new digest object. - * @throws RuntimeException + * @throws java.lang.RuntimeException * this Java virtual machine does not support the required hash * function. Very unlikely given that JGit uses a hash function * that is in the Java reference specification. @@ -524,7 +526,7 @@ public final class Constants { * <code>endMark</code> when the parse is successful. * @return a type code constant (one of {@link #OBJ_BLOB}, * {@link #OBJ_COMMIT}, {@link #OBJ_TAG}, {@link #OBJ_TREE}. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * there is no valid type identified by <code>typeString</code>. */ public static int decodeTypeString(final AnyObjectId id, @@ -602,7 +604,7 @@ public final class Constants { * 127 (outside of 7-bit ASCII). * @return a byte array of the same length as the input string, holding the * same characters, in the same order. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * the input string contains one or more characters outside of * the 7-bit ASCII character space. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/CoreConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/CoreConfig.java index fdbbe39393..32a894f795 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/CoreConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/CoreConfig.java @@ -180,6 +180,8 @@ public class CoreConfig { } /** + * Get the compression level to use when storing loose objects + * * @return The compression level to use when storing loose objects */ public int getCompression() { @@ -187,6 +189,8 @@ public class CoreConfig { } /** + * Get the preferred pack index file format; 0 for oldest possible. + * * @return the preferred pack index file format; 0 for oldest possible. */ public int getPackIndexVersion() { @@ -194,6 +198,8 @@ public class CoreConfig { } /** + * Whether to log all refUpdates + * * @return whether to log all refUpdates */ public boolean isLogAllRefUpdates() { @@ -201,6 +207,8 @@ public class CoreConfig { } /** + * Get path of excludesfile + * * @return path of excludesfile */ public String getExcludesFile() { @@ -208,6 +216,8 @@ public class CoreConfig { } /** + * Get path of attributesfile + * * @return path of attributesfile * @since 3.7 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/DefaultTypedConfigGetter.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/DefaultTypedConfigGetter.java index fd37747601..68f881dd1e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/DefaultTypedConfigGetter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/DefaultTypedConfigGetter.java @@ -57,13 +57,14 @@ import org.eclipse.jgit.transport.RefSpec; import org.eclipse.jgit.util.StringUtils; /** - * An {@link TypedConfigGetter} that throws {@link IllegalArgumentException} on - * invalid values. + * An {@link org.eclipse.jgit.lib.TypedConfigGetter} that throws + * {@link java.lang.IllegalArgumentException} on invalid values. * * @since 4.9 */ public class DefaultTypedConfigGetter implements TypedConfigGetter { + /** {@inheritDoc} */ @Override public boolean getBoolean(Config config, String section, String subsection, String name, boolean defaultValue) { @@ -82,6 +83,7 @@ public class DefaultTypedConfigGetter implements TypedConfigGetter { } } + /** {@inheritDoc} */ @Override public <T extends Enum<?>> T getEnum(Config config, T[] all, String section, String subsection, String name, T defaultValue) { @@ -139,6 +141,7 @@ public class DefaultTypedConfigGetter implements TypedConfigGetter { } } + /** {@inheritDoc} */ @Override public int getInt(Config config, String section, String subsection, String name, int defaultValue) { @@ -150,6 +153,7 @@ public class DefaultTypedConfigGetter implements TypedConfigGetter { .format(JGitText.get().integerValueOutOfRange, section, name)); } + /** {@inheritDoc} */ @Override public long getLong(Config config, String section, String subsection, String name, long defaultValue) { @@ -187,6 +191,7 @@ public class DefaultTypedConfigGetter implements TypedConfigGetter { } } + /** {@inheritDoc} */ @Override public long getTimeUnit(Config config, String section, String subsection, String name, long defaultValue, TimeUnit wantUnit) { @@ -286,6 +291,7 @@ public class DefaultTypedConfigGetter implements TypedConfigGetter { section, name, valueString)); } + /** {@inheritDoc} */ @Override public @NonNull List<RefSpec> getRefSpecs(Config config, String section, String subsection, String name) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/EmptyProgressMonitor.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/EmptyProgressMonitor.java index c236c35f3c..8ae90c6652 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/EmptyProgressMonitor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/EmptyProgressMonitor.java @@ -51,26 +51,31 @@ package org.eclipse.jgit.lib; */ public abstract class EmptyProgressMonitor implements ProgressMonitor { + /** {@inheritDoc} */ @Override public void start(int totalTasks) { // empty } + /** {@inheritDoc} */ @Override public void beginTask(String title, int totalWork) { // empty } + /** {@inheritDoc} */ @Override public void update(int completed) { // empty } + /** {@inheritDoc} */ @Override public void endTask() { // empty } + /** {@inheritDoc} */ @Override public boolean isCancelled() { return false; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/FileMode.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/FileMode.java index edbc709f48..7852371648 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/FileMode.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/FileMode.java @@ -82,7 +82,9 @@ public abstract class FileMode { /** Bit pattern for {@link #TYPE_MASK} matching {@link #MISSING}. */ public static final int TYPE_MISSING = 0000000; - /** Mode indicating an entry is a tree (aka directory). */ + /** + * Mode indicating an entry is a tree (aka directory). + */ public static final FileMode TREE = new FileMode(TYPE_TREE, Constants.OBJ_TREE) { @Override @@ -197,9 +199,11 @@ public abstract class FileMode { } /** - * Test a file mode for equality with this {@link FileMode} object. + * Test a file mode for equality with this + * {@link org.eclipse.jgit.lib.FileMode} object. * * @param modebits + * a int. * @return true if the mode bits represent the same mode as this object */ public abstract boolean equals(final int modebits); @@ -215,7 +219,7 @@ public abstract class FileMode { * * @param os * stream to copy the mode to. - * @throws IOException + * @throws java.io.IOException * the stream encountered an error during the copy. */ public void copyTo(final OutputStream os) throws IOException { @@ -240,6 +244,8 @@ public abstract class FileMode { } /** + * Copy the number of bytes written by {@link #copyTo(OutputStream)}. + * * @return the number of bytes written by {@link #copyTo(OutputStream)}. */ public int copyToLength() { @@ -249,7 +255,7 @@ public abstract class FileMode { /** * Get the object type that should appear for this type of mode. * <p> - * See the object type constants in {@link Constants}. + * See the object type constants in {@link org.eclipse.jgit.lib.Constants}. * * @return one of the well known object type constants. */ @@ -257,13 +263,19 @@ public abstract class FileMode { return objectType; } - /** Format this mode as an octal string (for debugging only). */ + /** + * {@inheritDoc} + * <p> + * Format this mode as an octal string (for debugging only). + */ @Override public String toString() { return Integer.toOctalString(modeBits); } /** + * Get the mode bits as an integer. + * * @return The mode bits as an integer. */ public int getBits() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/IndexDiff.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/IndexDiff.java index ea573a48d7..87086cbde0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/IndexDiff.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/IndexDiff.java @@ -285,12 +285,13 @@ public class IndexDiff { * Construct an IndexDiff * * @param repository + * a {@link org.eclipse.jgit.lib.Repository} object. * @param revstr - * symbolic name e.g. HEAD - * An EmptyTreeIterator is used if <code>revstr</code> cannot be resolved. + * symbolic name e.g. HEAD An EmptyTreeIterator is used if + * <code>revstr</code> cannot be resolved. * @param workingTreeIterator * iterator for working directory - * @throws IOException + * @throws java.io.IOException */ public IndexDiff(Repository repository, String revstr, WorkingTreeIterator workingTreeIterator) throws IOException { @@ -301,11 +302,12 @@ public class IndexDiff { * Construct an Indexdiff * * @param repository + * a {@link org.eclipse.jgit.lib.Repository} object. * @param objectId * tree id. If null, an EmptyTreeIterator is used. * @param workingTreeIterator * iterator for working directory - * @throws IOException + * @throws java.io.IOException */ public IndexDiff(Repository repository, ObjectId objectId, WorkingTreeIterator workingTreeIterator) throws IOException { @@ -321,6 +323,8 @@ public class IndexDiff { } /** + * Defines how modifications in submodules are treated + * * @param mode * defines how modifications in submodules are treated * @since 3.6 @@ -336,7 +340,8 @@ public class IndexDiff { public interface WorkingTreeIteratorFactory { /** * @param repo - * @return a WorkingTreeIterator for repo + * the repository + * @return working tree iterator */ public WorkingTreeIterator getWorkingTreeIterator(Repository repo); } @@ -363,6 +368,7 @@ public class IndexDiff { * files. * * @param filter + * a {@link org.eclipse.jgit.treewalk.filter.TreeFilter} object. */ public void setFilter(TreeFilter filter) { this.filter = filter; @@ -374,7 +380,7 @@ public class IndexDiff { * monitor is required. * * @return if anything is different between index, tree, and workdir - * @throws IOException + * @throws java.io.IOException */ public boolean diff() throws IOException { return diff(null, 0, 0, ""); //$NON-NLS-1$ @@ -396,10 +402,9 @@ public class IndexDiff { * number or estimated files in the working tree * @param estIndexSize * number of estimated entries in the cache - * @param title - * + * @param title a {@link java.lang.String} object. * @return if anything is different between index, tree, and workdir - * @throws IOException + * @throws java.io.IOException */ public boolean diff(final ProgressMonitor monitor, int estWorkTreeSize, int estIndexSize, final String title) @@ -533,11 +538,9 @@ public class IndexDiff { .equals(localIgnoreSubmoduleMode)) continue; } catch (ConfigInvalidException e) { - IOException e1 = new IOException(MessageFormat.format( + throw new IOException(MessageFormat.format( JGitText.get().invalidIgnoreParamSubmodule, - smw.getPath())); - e1.initCause(e); - throw e1; + smw.getPath()), e); } Repository subRepo = smw.getRepository(); if (subRepo != null) { @@ -621,6 +624,8 @@ public class IndexDiff { } /** + * Get list of files added to the index, not in the tree + * * @return list of files added to the index, not in the tree */ public Set<String> getAdded() { @@ -628,6 +633,8 @@ public class IndexDiff { } /** + * Get list of files changed from tree to index + * * @return list of files changed from tree to index */ public Set<String> getChanged() { @@ -635,6 +642,8 @@ public class IndexDiff { } /** + * Get list of files removed from index, but in tree + * * @return list of files removed from index, but in tree */ public Set<String> getRemoved() { @@ -642,6 +651,8 @@ public class IndexDiff { } /** + * Get list of files in index, but not filesystem + * * @return list of files in index, but not filesystem */ public Set<String> getMissing() { @@ -649,6 +660,8 @@ public class IndexDiff { } /** + * Get list of files modified on disk relative to the index + * * @return list of files modified on disk relative to the index */ public Set<String> getModified() { @@ -656,6 +669,8 @@ public class IndexDiff { } /** + * Get list of files that are not ignored, and not in the index. + * * @return list of files that are not ignored, and not in the index. */ public Set<String> getUntracked() { @@ -663,6 +678,9 @@ public class IndexDiff { } /** + * Get list of files that are in conflict, corresponds to the keys of + * {@link #getConflictingStageStates()} + * * @return list of files that are in conflict, corresponds to the keys of * {@link #getConflictingStageStates()} */ @@ -671,8 +689,11 @@ public class IndexDiff { } /** + * Get the map from each path of {@link #getConflicting()} to its + * corresponding {@link org.eclipse.jgit.lib.IndexDiff.StageState} + * * @return the map from each path of {@link #getConflicting()} to its - * corresponding {@link StageState} + * corresponding {@link org.eclipse.jgit.lib.IndexDiff.StageState} * @since 3.0 */ public Map<String, StageState> getConflictingStageStates() { @@ -693,6 +714,8 @@ public class IndexDiff { } /** + * Get list of files with the flag assume-unchanged + * * @return list of files with the flag assume-unchanged */ public Set<String> getAssumeUnchanged() { @@ -707,6 +730,8 @@ public class IndexDiff { } /** + * Get list of folders containing only untracked files/folders + * * @return list of folders containing only untracked files/folders */ public Set<String> getUntrackedFolders() { @@ -717,7 +742,7 @@ public class IndexDiff { /** * Get the file mode of the given path in the index * - * @param path + * @param path a {@link java.lang.String} object. * @return file mode */ public FileMode getIndexMode(final String path) { @@ -729,7 +754,7 @@ public class IndexDiff { * Get the list of paths that IndexDiff has detected to differ and have the * given file mode * - * @param mode + * @param mode a {@link org.eclipse.jgit.lib.FileMode} object. * @return the list of paths that IndexDiff has detected to differ and have * the given file mode * @since 3.6 diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/InflaterCache.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/InflaterCache.java index f9517a0a2e..a97721c732 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/InflaterCache.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/InflaterCache.java @@ -46,7 +46,9 @@ package org.eclipse.jgit.lib; import java.util.zip.Inflater; -/** Creates zlib based inflaters as necessary for object decompression. */ +/** + * Creates zlib based inflaters as necessary for object decompression. + */ public class InflaterCache { private static final int SZ = 4; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/MutableObjectId.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/MutableObjectId.java index 4b14d121e0..e492af94b9 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/MutableObjectId.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/MutableObjectId.java @@ -79,15 +79,17 @@ public class MutableObjectId extends AnyObjectId { * * @param index * index of the byte to set in the raw form of the ObjectId. Must - * be in range [0, {@link Constants#OBJECT_ID_LENGTH}). + * be in range [0, + * {@link org.eclipse.jgit.lib.Constants#OBJECT_ID_LENGTH}). * @param value * the value of the specified byte at {@code index}. Values are * unsigned and thus are in the range [0,255] rather than the * signed byte range of [-128, 127]. - * @throws ArrayIndexOutOfBoundsException + * @throws java.lang.ArrayIndexOutOfBoundsException * {@code index} is less than 0, equal to - * {@link Constants#OBJECT_ID_LENGTH}, or greater than - * {@link Constants#OBJECT_ID_LENGTH}. + * {@link org.eclipse.jgit.lib.Constants#OBJECT_ID_LENGTH}, or + * greater than + * {@link org.eclipse.jgit.lib.Constants#OBJECT_ID_LENGTH}. */ public void setByte(int index, int value) { switch (index >> 2) { @@ -128,7 +130,9 @@ public class MutableObjectId extends AnyObjectId { } } - /** Make this id match {@link ObjectId#zeroId()}. */ + /** + * Make this id match {@link org.eclipse.jgit.lib.ObjectId#zeroId()}. + */ public void clear() { w1 = 0; w2 = 0; @@ -198,7 +202,6 @@ public class MutableObjectId extends AnyObjectId { * must be available within this integers array. * @param p * position to read the first integer of data from. - * */ public void fromRaw(final int[] ints, final int p) { w1 = ints[p]; @@ -212,10 +215,15 @@ public class MutableObjectId extends AnyObjectId { * Convert an ObjectId from binary representation expressed in integers. * * @param a + * an int. * @param b + * an int. * @param c + * an int. * @param d + * an int. * @param e + * an int. * @since 4.7 */ public void set(int a, int b, int c, int d, int e) { @@ -265,6 +273,7 @@ public class MutableObjectId extends AnyObjectId { } } + /** {@inheritDoc} */ @Override public ObjectId toObjectId() { return new ObjectId(this); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/NullProgressMonitor.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/NullProgressMonitor.java index 497beb033a..37fcd7850f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/NullProgressMonitor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/NullProgressMonitor.java @@ -56,26 +56,31 @@ public class NullProgressMonitor implements ProgressMonitor { // Do not let others instantiate } + /** {@inheritDoc} */ @Override public void start(int totalTasks) { // Do not report. } + /** {@inheritDoc} */ @Override public void beginTask(String title, int totalWork) { // Do not report. } + /** {@inheritDoc} */ @Override public void update(int completed) { // Do not report. } + /** {@inheritDoc} */ @Override public boolean isCancelled() { return false; } + /** {@inheritDoc} */ @Override public void endTask() { // Do not report. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectChecker.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectChecker.java index 19c5c7eb45..a6d2c3f22c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectChecker.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectChecker.java @@ -317,12 +317,12 @@ public class ObjectChecker { * * @param objType * type of the object. Must be a valid object type code in - * {@link Constants}. + * {@link org.eclipse.jgit.lib.Constants}. * @param raw * the raw data which comprises the object. This should be in the * canonical format (that is the format used to generate the * ObjectId of the object). The array is never modified. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * if an error is identified. */ public void check(int objType, byte[] raw) @@ -337,12 +337,12 @@ public class ObjectChecker { * identify of the object being checked. * @param objType * type of the object. Must be a valid object type code in - * {@link Constants}. + * {@link org.eclipse.jgit.lib.Constants}. * @param raw * the raw data which comprises the object. This should be in the * canonical format (that is the format used to generate the * ObjectId of the object). The array is never modified. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * if an error is identified. * @since 4.2 */ @@ -449,7 +449,7 @@ public class ObjectChecker { * * @param raw * the commit data. The array is never modified. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * if any error was detected. */ public void checkCommit(byte[] raw) throws CorruptObjectException { @@ -463,7 +463,7 @@ public class ObjectChecker { * identity of the object being checked. * @param raw * the commit data. The array is never modified. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * if any error was detected. * @since 4.2 */ @@ -503,7 +503,7 @@ public class ObjectChecker { * * @param raw * the tag data. The array is never modified. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * if any error was detected. */ public void checkTag(byte[] raw) throws CorruptObjectException { @@ -517,7 +517,7 @@ public class ObjectChecker { * identity of the object being checked. * @param raw * the tag data. The array is never modified. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * if any error was detected. * @since 4.2 */ @@ -593,7 +593,7 @@ public class ObjectChecker { * * @param raw * the raw tree data. The array is never modified. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * if any error was detected. */ public void checkTree(byte[] raw) throws CorruptObjectException { @@ -607,7 +607,7 @@ public class ObjectChecker { * identity of the object being checked. * @param raw * the raw tree data. The array is never modified. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * if any error was detected. * @since 4.2 */ @@ -739,11 +739,13 @@ public class ObjectChecker { /** * Check tree path entry for validity. * <p> - * Unlike {@link #checkPathSegment(byte[], int, int)}, this version - * scans a multi-directory path string such as {@code "src/main.c"}. + * Unlike {@link #checkPathSegment(byte[], int, int)}, this version scans a + * multi-directory path string such as {@code "src/main.c"}. * - * @param path path string to scan. - * @throws CorruptObjectException path is invalid. + * @param path + * path string to scan. + * @throws org.eclipse.jgit.errors.CorruptObjectException + * path is invalid. * @since 3.6 */ public void checkPath(String path) throws CorruptObjectException { @@ -754,13 +756,17 @@ public class ObjectChecker { /** * Check tree path entry for validity. * <p> - * Unlike {@link #checkPathSegment(byte[], int, int)}, this version - * scans a multi-directory path string such as {@code "src/main.c"}. + * Unlike {@link #checkPathSegment(byte[], int, int)}, this version scans a + * multi-directory path string such as {@code "src/main.c"}. * - * @param raw buffer to scan. - * @param ptr offset to first byte of the name. - * @param end offset to one past last byte of name. - * @throws CorruptObjectException path is invalid. + * @param raw + * buffer to scan. + * @param ptr + * offset to first byte of the name. + * @param end + * offset to one past last byte of name. + * @throws org.eclipse.jgit.errors.CorruptObjectException + * path is invalid. * @since 3.6 */ public void checkPath(byte[] raw, int ptr, int end) @@ -778,10 +784,14 @@ public class ObjectChecker { /** * Check tree path entry for validity. * - * @param raw buffer to scan. - * @param ptr offset to first byte of the name. - * @param end offset to one past last byte of name. - * @throws CorruptObjectException name is invalid. + * @param raw + * buffer to scan. + * @param ptr + * offset to first byte of the name. + * @param end + * offset to one past last byte of name. + * @throws org.eclipse.jgit.errors.CorruptObjectException + * name is invalid. * @since 3.4 */ public void checkPathSegment(byte[] raw, int ptr, int end) @@ -1073,7 +1083,7 @@ public class ObjectChecker { } /** - * Create a new {@link BlobObjectChecker}. + * Create a new {@link org.eclipse.jgit.lib.BlobObjectChecker}. * * @return new BlobObjectChecker or null if it's not provided. * @since 4.9 @@ -1086,12 +1096,13 @@ public class ObjectChecker { /** * Check a blob for errors. * - * <p>This may not be called from PackParser in some cases. Use {@link - * #newBlobObjectChecker} instead. + * <p> + * This may not be called from PackParser in some cases. Use + * {@link #newBlobObjectChecker} instead. * * @param raw * the blob data. The array is never modified. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * if any error was detected. */ public void checkBlob(final byte[] raw) throws CorruptObjectException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectDatabase.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectDatabase.java index 2abd6dae61..bbef51da20 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectDatabase.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectDatabase.java @@ -52,10 +52,12 @@ import org.eclipse.jgit.errors.MissingObjectException; * Abstraction of arbitrary object storage. * <p> * An object database stores one or more Git objects, indexed by their unique - * {@link ObjectId}. + * {@link org.eclipse.jgit.lib.ObjectId}. */ public abstract class ObjectDatabase { - /** Initialize a new database instance for access. */ + /** + * Initialize a new database instance for access. + */ protected ObjectDatabase() { // Protected to force extension. } @@ -73,7 +75,7 @@ public abstract class ObjectDatabase { /** * Initialize a new object database at this location. * - * @throws IOException + * @throws java.io.IOException * the database could not be created. */ public void create() throws IOException { @@ -116,7 +118,7 @@ public abstract class ObjectDatabase { * @param objectId * identity of the object to test for existence of. * @return true if the specified object is stored in this database. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public boolean has(final AnyObjectId objectId) throws IOException { @@ -133,10 +135,10 @@ public abstract class ObjectDatabase { * * @param objectId * identity of the object to open. - * @return a {@link ObjectLoader} for accessing the object. + * @return a {@link org.eclipse.jgit.lib.ObjectLoader} for accessing the object. * @throws MissingObjectException * the object does not exist. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public ObjectLoader open(final AnyObjectId objectId) @@ -154,16 +156,17 @@ public abstract class ObjectDatabase { * identity of the object to open. * @param typeHint * hint about the type of object being requested, e.g. - * {@link Constants#OBJ_BLOB}; {@link ObjectReader#OBJ_ANY} if - * the object type is not known, or does not matter to the - * caller. - * @return a {@link ObjectLoader} for accessing the object. - * @throws MissingObjectException + * {@link org.eclipse.jgit.lib.Constants#OBJ_BLOB}; + * {@link org.eclipse.jgit.lib.ObjectReader#OBJ_ANY} if the + * object type is not known, or does not matter to the caller. + * @return a {@link org.eclipse.jgit.lib.ObjectLoader} for accessing the + * object. + * @throws org.eclipse.jgit.errors.MissingObjectException * the object does not exist. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * typeHint was not OBJ_ANY, and the object's actual type does * not match typeHint. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public ObjectLoader open(AnyObjectId objectId, int typeHint) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectId.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectId.java index 991f03f82e..0e85545531 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectId.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectId.java @@ -252,10 +252,15 @@ public class ObjectId extends AnyObjectId implements Serializable { * Construct an ObjectId from 160 bits provided in 5 words. * * @param new_1 + * an int * @param new_2 + * an int * @param new_3 + * an int * @param new_4 + * an int * @param new_5 + * an int * @since 4.7 */ public ObjectId(int new_1, int new_2, int new_3, int new_4, int new_5) { @@ -284,6 +289,7 @@ public class ObjectId extends AnyObjectId implements Serializable { w5 = src.w5; } + /** {@inheritDoc} */ @Override public ObjectId toObjectId() { return this; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdOwnerMap.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdOwnerMap.java index 95cb976372..03a430cab6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdOwnerMap.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdOwnerMap.java @@ -48,10 +48,12 @@ import java.util.Iterator; import java.util.NoSuchElementException; /** - * Fast, efficient map for {@link ObjectId} subclasses in only one map. + * Fast, efficient map for {@link org.eclipse.jgit.lib.ObjectId} subclasses in + * only one map. * <p> * To use this map type, applications must have their entry value type extend - * from {@link ObjectIdOwnerMap.Entry}, which itself extends from ObjectId. + * from {@link org.eclipse.jgit.lib.ObjectIdOwnerMap.Entry}, which itself + * extends from ObjectId. * <p> * Object instances may only be stored in <b>ONE</b> ObjectIdOwnerMap. This * restriction exists because the map stores internal map state within each @@ -59,10 +61,11 @@ import java.util.NoSuchElementException; * could corrupt one or both map's internal state. * <p> * If an object instance must be in more than one map, applications may use - * ObjectIdOwnerMap for one of the maps, and {@link ObjectIdSubclassMap} for the - * other map(s). It is encouraged to use ObjectIdOwnerMap for the map that is - * accessed most often, as this implementation runs faster than the more general - * ObjectIdSubclassMap implementation. + * ObjectIdOwnerMap for one of the maps, and + * {@link org.eclipse.jgit.lib.ObjectIdSubclassMap} for the other map(s). It is + * encouraged to use ObjectIdOwnerMap for the map that is accessed most often, + * as this implementation runs faster than the more general ObjectIdSubclassMap + * implementation. * * @param <V> * type of subclass of ObjectId that will be stored in the map. @@ -97,7 +100,9 @@ public class ObjectIdOwnerMap<V extends ObjectIdOwnerMap.Entry> /** Low bit mask to index into {@link #directory}, {@code 2^bits-1}. */ private int mask; - /** Create an empty map. */ + /** + * Create an empty map. + */ @SuppressWarnings("unchecked") public ObjectIdOwnerMap() { bits = 0; @@ -108,7 +113,9 @@ public class ObjectIdOwnerMap<V extends ObjectIdOwnerMap.Entry> directory[0] = newSegment(); } - /** Remove all entries from this map. */ + /** + * Remove all entries from this map. + */ public void clear() { size = 0; @@ -137,11 +144,9 @@ public class ObjectIdOwnerMap<V extends ObjectIdOwnerMap.Entry> } /** + * {@inheritDoc} + * <p> * Returns true if this map contains the specified object. - * - * @param toFind - * object to find. - * @return true if the mapping exists for this object; false otherwise. */ @Override public boolean contains(final AnyObjectId toFind) { @@ -157,8 +162,6 @@ public class ObjectIdOwnerMap<V extends ObjectIdOwnerMap.Entry> * * @param newValue * the object to store. - * @param <Q> - * type of instance to store. */ public <Q extends V> void add(final Q newValue) { if (++size == grow) @@ -189,8 +192,6 @@ public class ObjectIdOwnerMap<V extends ObjectIdOwnerMap.Entry> * @return {@code newValue} if stored, or the prior value already stored and * that would have been returned had the caller used * {@code get(newValue)} first. - * @param <Q> - * type of instance to store. */ @SuppressWarnings("unchecked") public <Q extends V> V addIfAbsent(final Q newValue) { @@ -210,16 +211,25 @@ public class ObjectIdOwnerMap<V extends ObjectIdOwnerMap.Entry> return newValue; } - /** @return number of objects in this map. */ + /** + * Get number of objects in this map. + * + * @return number of objects in this map. + */ public int size() { return size; } - /** @return true if {@link #size()} is 0. */ + /** + * Whether this map is empty + * + * @return true if {@link #size()} is 0. + */ public boolean isEmpty() { return size == 0; } + /** {@inheritDoc} */ @Override public Iterator<V> iterator() { return new Iterator<V>() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdRef.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdRef.java index 636716bcb3..22aaa3ad73 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdRef.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdRef.java @@ -47,7 +47,10 @@ package org.eclipse.jgit.lib; import org.eclipse.jgit.annotations.NonNull; import org.eclipse.jgit.annotations.Nullable; -/** A {@link Ref} that points directly at an {@link ObjectId}. */ +/** + * A {@link org.eclipse.jgit.lib.Ref} that points directly at an + * {@link org.eclipse.jgit.lib.ObjectId}. + */ public abstract class ObjectIdRef implements Ref { /** Any reference whose peeled value is not yet known. */ public static class Unpeeled extends ObjectIdRef { @@ -167,41 +170,48 @@ public abstract class ObjectIdRef implements Ref { this.objectId = id; } + /** {@inheritDoc} */ @Override @NonNull public String getName() { return name; } + /** {@inheritDoc} */ @Override public boolean isSymbolic() { return false; } + /** {@inheritDoc} */ @Override @NonNull public Ref getLeaf() { return this; } + /** {@inheritDoc} */ @Override @NonNull public Ref getTarget() { return this; } + /** {@inheritDoc} */ @Override @Nullable public ObjectId getObjectId() { return objectId; } + /** {@inheritDoc} */ @Override @NonNull public Storage getStorage() { return storage; } + /** {@inheritDoc} */ @NonNull @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdSet.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdSet.java index 0b5848463c..51bd9029a0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdSet.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdSet.java @@ -48,7 +48,8 @@ package org.eclipse.jgit.lib; * <p> * Usually backed by a read-only data structure such as * {@link org.eclipse.jgit.internal.storage.file.PackIndex}. Mutable types like - * {@link ObjectIdOwnerMap} also implement the interface by checking keys. + * {@link org.eclipse.jgit.lib.ObjectIdOwnerMap} also implement the interface by + * checking keys. * * @since 4.2 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdSubclassMap.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdSubclassMap.java index 43fc7bfb97..001aa9cdd6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdSubclassMap.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdSubclassMap.java @@ -49,13 +49,15 @@ import java.util.Iterator; import java.util.NoSuchElementException; /** - * Fast, efficient map specifically for {@link ObjectId} subclasses. + * Fast, efficient map specifically for {@link org.eclipse.jgit.lib.ObjectId} + * subclasses. * <p> * This map provides an efficient translation from any ObjectId instance to a * cached subclass of ObjectId that has the same value. * <p> - * If object instances are stored in only one map, {@link ObjectIdOwnerMap} is a - * more efficient implementation. + * If object instances are stored in only one map, + * {@link org.eclipse.jgit.lib.ObjectIdOwnerMap} is a more efficient + * implementation. * * @param <V> * type of subclass of ObjectId that will be stored in the map. @@ -72,12 +74,16 @@ public class ObjectIdSubclassMap<V extends ObjectId> V[] table; - /** Create an empty map. */ + /** + * Create an empty map. + */ public ObjectIdSubclassMap() { initTable(INITIAL_TABLE_SIZE); } - /** Remove all entries from this map. */ + /** + * Remove all entries from this map. + */ public void clear() { size = 0; initTable(INITIAL_TABLE_SIZE); @@ -105,11 +111,9 @@ public class ObjectIdSubclassMap<V extends ObjectId> } /** + * {@inheritDoc} + * <p> * Returns true if this map contains the specified object. - * - * @param toFind - * object to find. - * @return true if the mapping exists for this object; false otherwise. */ @Override public boolean contains(final AnyObjectId toFind) { @@ -126,8 +130,6 @@ public class ObjectIdSubclassMap<V extends ObjectId> * * @param newValue * the object to store. - * @param <Q> - * type of instance to store. */ public <Q extends V> void add(final Q newValue) { if (++size == grow) @@ -152,8 +154,6 @@ public class ObjectIdSubclassMap<V extends ObjectId> * @return {@code newValue} if stored, or the prior value already stored and * that would have been returned had the caller used * {@code get(newValue)} first. - * @param <Q> - * type of instance to store. */ public <Q extends V> V addIfAbsent(final Q newValue) { final int msk = mask; @@ -177,17 +177,24 @@ public class ObjectIdSubclassMap<V extends ObjectId> } /** + * Get number of objects in map + * * @return number of objects in map */ public int size() { return size; } - /** @return true if {@link #size()} is 0. */ + /** + * Whether {@link #size()} is 0. + * + * @return true if {@link #size()} is 0. + */ public boolean isEmpty() { return size == 0; } + /** {@inheritDoc} */ @Override public Iterator<V> iterator() { return new Iterator<V>() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectInserter.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectInserter.java index b2ffbe6f6f..40522ba244 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectInserter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectInserter.java @@ -182,7 +182,9 @@ public abstract class ObjectInserter implements AutoCloseable { /** Temporary working buffer for streaming data through. */ private byte[] tempBuffer; - /** Create a new inserter for a database. */ + /** + * Create a new inserter for a database. + */ protected ObjectInserter() { } @@ -218,6 +220,8 @@ public abstract class ObjectInserter implements AutoCloseable { } /** + * Compute digest to help compute an ObjectId + * * @return digest to help compute an ObjectId * @since 4.7 */ @@ -272,7 +276,7 @@ public abstract class ObjectInserter implements AutoCloseable { * stream providing the object content. The caller is responsible * for closing the stream. * @return the name of the object. - * @throws IOException + * @throws java.io.IOException * the source stream could not be read. */ public ObjectId idFor(int objectType, long length, InputStream in) @@ -297,6 +301,7 @@ public abstract class ObjectInserter implements AutoCloseable { * Compute the ObjectId for the given tree without inserting it. * * @param formatter + * a {@link org.eclipse.jgit.lib.TreeFormatter} object. * @return the computed ObjectId */ public ObjectId idFor(TreeFormatter formatter) { @@ -309,7 +314,7 @@ public abstract class ObjectInserter implements AutoCloseable { * @param formatter * the formatter containing the proposed tree's data. * @return the name of the tree object. - * @throws IOException + * @throws java.io.IOException * the object could not be stored. */ public final ObjectId insert(TreeFormatter formatter) throws IOException { @@ -325,7 +330,7 @@ public abstract class ObjectInserter implements AutoCloseable { * @param builder * the builder containing the proposed commit's data. * @return the name of the commit object. - * @throws IOException + * @throws java.io.IOException * the object could not be stored. */ public final ObjectId insert(CommitBuilder builder) throws IOException { @@ -338,7 +343,7 @@ public abstract class ObjectInserter implements AutoCloseable { * @param builder * the builder containing the proposed tag's data. * @return the name of the tag object. - * @throws IOException + * @throws java.io.IOException * the object could not be stored. */ public final ObjectId insert(TagBuilder builder) throws IOException { @@ -353,7 +358,7 @@ public abstract class ObjectInserter implements AutoCloseable { * @param data * complete content of the object. * @return the name of the object. - * @throws IOException + * @throws java.io.IOException * the object could not be stored. */ public ObjectId insert(final int type, final byte[] data) @@ -373,7 +378,7 @@ public abstract class ObjectInserter implements AutoCloseable { * @param len * number of bytes to copy from {@code data}. * @return the name of the object. - * @throws IOException + * @throws java.io.IOException * the object could not be stored. */ public ObjectId insert(int type, byte[] data, int off, int len) @@ -392,7 +397,7 @@ public abstract class ObjectInserter implements AutoCloseable { * stream providing the object content. The caller is responsible * for closing the stream. * @return the name of the object. - * @throws IOException + * @throws java.io.IOException * the object could not be stored, or the source stream could * not be read. */ @@ -406,7 +411,7 @@ public abstract class ObjectInserter implements AutoCloseable { * the input stream. The stream is not closed by the parser, and * must instead be closed by the caller once parsing is complete. * @return the pack parser. - * @throws IOException + * @throws java.io.IOException * the parser instance, which can be configured and then used to * parse objects into the ObjectDatabase. */ @@ -443,13 +448,15 @@ public abstract class ObjectInserter implements AutoCloseable { * The flush may take some period of time to make the objects available to * other threads. * - * @throws IOException + * @throws java.io.IOException * the flush could not be completed; objects inserted thus far * are in an indeterminate state. */ public abstract void flush() throws IOException; /** + * {@inheritDoc} + * <p> * Release any resources used by this inserter. * <p> * An inserter that has been released can be used again, but may need to be diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectLoader.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectLoader.java index b2cc29426e..432f5a6cd9 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectLoader.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectLoader.java @@ -61,16 +61,23 @@ import org.eclipse.jgit.util.IO; */ public abstract class ObjectLoader { /** - * @return Git in pack object type, see {@link Constants}. + * Get Git in pack object type + * + * @return Git in pack object type, see + * {@link org.eclipse.jgit.lib.Constants}. */ public abstract int getType(); /** + * Get size of object in bytes + * * @return size of object in bytes */ public abstract long getSize(); /** + * Whether this object is too large to obtain as a byte array. + * * @return true if this object is too large to obtain as a byte array. * Objects over a certain threshold should be accessed only by their * {@link #openStream()} to prevent overflowing the JVM heap. @@ -91,7 +98,7 @@ public abstract class ObjectLoader { * be modified by the caller. * * @return the bytes of this object. - * @throws LargeObjectException + * @throws org.eclipse.jgit.errors.LargeObjectException * if the object won't fit into a byte array, because * {@link #isLarge()} returns true. Callers should use * {@link #openStream()} instead to access the contents. @@ -113,16 +120,18 @@ public abstract class ObjectLoader { * * @param sizeLimit * maximum number of bytes to return. If the object is larger - * than this limit, {@link LargeObjectException} will be thrown. + * than this limit, + * {@link org.eclipse.jgit.errors.LargeObjectException} will be + * thrown. * @return the bytes of this object. - * @throws LargeObjectException + * @throws org.eclipse.jgit.errors.LargeObjectException * if the object is bigger than {@code sizeLimit}, or if - * {@link OutOfMemoryError} occurs during allocation of the - * result array. Callers should use {@link #openStream()} + * {@link java.lang.OutOfMemoryError} occurs during allocation + * of the result array. Callers should use {@link #openStream()} * instead to access the contents. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the object is large, and it no longer exists. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public final byte[] getBytes(int sizeLimit) throws LargeObjectException, @@ -144,7 +153,7 @@ public abstract class ObjectLoader { * Changes (if made) will affect the cache but not the repository itself. * * @return the cached bytes of this object. Do not modify it. - * @throws LargeObjectException + * @throws org.eclipse.jgit.errors.LargeObjectException * if the object won't fit into a byte array, because * {@link #isLarge()} returns true. Callers should use * {@link #openStream()} instead to access the contents. @@ -167,16 +176,17 @@ public abstract class ObjectLoader { * @param sizeLimit * maximum number of bytes to return. If the object size is * larger than this limit and {@link #isLarge()} is true, - * {@link LargeObjectException} will be thrown. + * {@link org.eclipse.jgit.errors.LargeObjectException} will be + * thrown. * @return the cached bytes of this object. Do not modify it. - * @throws LargeObjectException + * @throws org.eclipse.jgit.errors.LargeObjectException * if the object is bigger than {@code sizeLimit}, or if - * {@link OutOfMemoryError} occurs during allocation of the - * result array. Callers should use {@link #openStream()} + * {@link java.lang.OutOfMemoryError} occurs during allocation + * of the result array. Callers should use {@link #openStream()} * instead to access the contents. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the object is large, and it no longer exists. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public byte[] getCachedBytes(int sizeLimit) throws LargeObjectException, @@ -213,9 +223,9 @@ public abstract class ObjectLoader { * @return a stream of this object's data. Caller must close the stream when * through with it. The returned stream is buffered with a * reasonable buffer size. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the object no longer exists. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public abstract ObjectStream openStream() throws MissingObjectException, @@ -236,9 +246,9 @@ public abstract class ObjectLoader { * stream to receive the complete copy of this object's data. * Caller is responsible for flushing or closing this stream * after this method returns. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the object no longer exists. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed, or the stream cannot be * written to. */ @@ -323,4 +333,42 @@ public abstract class ObjectLoader { return new ObjectStream.SmallStream(this); } } + + /** + * Wraps a delegate ObjectLoader. + * + * @since 4.10 + */ + public static abstract class Filter extends ObjectLoader { + /** + * @return delegate ObjectLoader to handle all processing. + * @since 4.10 + */ + protected abstract ObjectLoader delegate(); + + @Override + public int getType() { + return delegate().getType(); + } + + @Override + public long getSize() { + return delegate().getSize(); + } + + @Override + public boolean isLarge() { + return delegate().isLarge(); + } + + @Override + public byte[] getCachedBytes() { + return delegate().getCachedBytes(); + } + + @Override + public ObjectStream openStream() throws IOException { + return delegate().openStream(); + } + } } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectReader.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectReader.java index f39f291899..700b9dbe85 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectReader.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectReader.java @@ -53,13 +53,13 @@ import java.util.Set; import org.eclipse.jgit.annotations.Nullable; import org.eclipse.jgit.errors.IncorrectObjectTypeException; import org.eclipse.jgit.errors.MissingObjectException; -import org.eclipse.jgit.internal.storage.pack.ObjectReuseAsIs; /** - * Reads an {@link ObjectDatabase} for a single thread. + * Reads an {@link org.eclipse.jgit.lib.ObjectDatabase} for a single thread. * <p> * Readers that can support efficient reuse of pack encoded objects should also - * implement the companion interface {@link ObjectReuseAsIs}. + * implement the companion interface + * {@link org.eclipse.jgit.internal.storage.pack.ObjectReuseAsIs}. */ public abstract class ObjectReader implements AutoCloseable { /** Type hint indicating the caller doesn't know the type. */ @@ -95,7 +95,7 @@ public abstract class ObjectReader implements AutoCloseable { * @param objectId * object identity that needs to be abbreviated. * @return SHA-1 abbreviation. - * @throws IOException + * @throws java.io.IOException * the object store cannot be read. */ public AbbreviatedObjectId abbreviate(AnyObjectId objectId) @@ -122,7 +122,7 @@ public abstract class ObjectReader implements AutoCloseable { * [2, {@value Constants#OBJECT_ID_STRING_LENGTH}]. * @return SHA-1 abbreviation. If no matching objects exist in the * repository, the abbreviation will match the minimum length. - * @throws IOException + * @throws java.io.IOException * the object store cannot be read. */ public AbbreviatedObjectId abbreviate(AnyObjectId objectId, int len) @@ -174,7 +174,7 @@ public abstract class ObjectReader implements AutoCloseable { * abbreviated id to resolve to a complete identity. The * abbreviation must have a length of at least 2. * @return candidates that begin with the abbreviated identity. - * @throws IOException + * @throws java.io.IOException * the object store cannot be read. */ public abstract Collection<ObjectId> resolve(AbbreviatedObjectId id) @@ -186,7 +186,7 @@ public abstract class ObjectReader implements AutoCloseable { * @param objectId * identity of the object to test for existence of. * @return true if the specified object is stored in this database. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public boolean has(AnyObjectId objectId) throws IOException { @@ -200,13 +200,14 @@ public abstract class ObjectReader implements AutoCloseable { * identity of the object to test for existence of. * @param typeHint * hint about the type of object being requested, e.g. - * {@link Constants#OBJ_BLOB}; {@link #OBJ_ANY} if the object - * type is not known, or does not matter to the caller. + * {@link org.eclipse.jgit.lib.Constants#OBJ_BLOB}; + * {@link #OBJ_ANY} if the object type is not known, or does not + * matter to the caller. * @return true if the specified object is stored in this database. * @throws IncorrectObjectTypeException * typeHint was not OBJ_ANY, and the object's actual type does * not match typeHint. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public boolean has(AnyObjectId objectId, int typeHint) throws IOException { @@ -223,10 +224,11 @@ public abstract class ObjectReader implements AutoCloseable { * * @param objectId * identity of the object to open. - * @return a {@link ObjectLoader} for accessing the object. - * @throws MissingObjectException + * @return a {@link org.eclipse.jgit.lib.ObjectLoader} for accessing the + * object. + * @throws org.eclipse.jgit.errors.MissingObjectException * the object does not exist. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public ObjectLoader open(AnyObjectId objectId) @@ -241,15 +243,17 @@ public abstract class ObjectReader implements AutoCloseable { * identity of the object to open. * @param typeHint * hint about the type of object being requested, e.g. - * {@link Constants#OBJ_BLOB}; {@link #OBJ_ANY} if the object - * type is not known, or does not matter to the caller. - * @return a {@link ObjectLoader} for accessing the object. - * @throws MissingObjectException + * {@link org.eclipse.jgit.lib.Constants#OBJ_BLOB}; + * {@link #OBJ_ANY} if the object type is not known, or does not + * matter to the caller. + * @return a {@link org.eclipse.jgit.lib.ObjectLoader} for accessing the + * object. + * @throws org.eclipse.jgit.errors.MissingObjectException * the object does not exist. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * typeHint was not OBJ_ANY, and the object's actual type does * not match typeHint. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public abstract ObjectLoader open(AnyObjectId objectId, int typeHint) @@ -260,15 +264,13 @@ public abstract class ObjectReader implements AutoCloseable { * Returns IDs for those commits which should be considered as shallow. * * @return IDs of shallow commits - * @throws IOException + * @throws java.io.IOException */ public abstract Set<ObjectId> getShallowCommits() throws IOException; /** * Asynchronous object opening. * - * @param <T> - * type of identifier being supplied. * @param objectIds * objects to open from the object store. The supplied collection * must not be modified until the queue has finished. @@ -335,15 +337,16 @@ public abstract class ObjectReader implements AutoCloseable { * identity of the object to open. * @param typeHint * hint about the type of object being requested, e.g. - * {@link Constants#OBJ_BLOB}; {@link #OBJ_ANY} if the object - * type is not known, or does not matter to the caller. + * {@link org.eclipse.jgit.lib.Constants#OBJ_BLOB}; + * {@link #OBJ_ANY} if the object type is not known, or does not + * matter to the caller. * @return size of object in bytes. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the object does not exist. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * typeHint was not OBJ_ANY, and the object's actual type does * not match typeHint. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public long getObjectSize(AnyObjectId objectId, int typeHint) @@ -355,8 +358,6 @@ public abstract class ObjectReader implements AutoCloseable { /** * Asynchronous object size lookup. * - * @param <T> - * type of identifier being supplied. * @param objectIds * objects to get the size of from the object store. The supplied * collection must not be modified until the queue has finished. @@ -433,7 +434,7 @@ public abstract class ObjectReader implements AutoCloseable { * An index that can be used to speed up ObjectWalks. * * @return the index or null if one does not exist. - * @throws IOException + * @throws java.io.IOException * when the index fails to load * @since 3.0 */ @@ -442,9 +443,12 @@ public abstract class ObjectReader implements AutoCloseable { } /** - * @return the {@link ObjectInserter} from which this reader was created - * using {@code inserter.newReader()}, or null if this reader was not - * created from an inserter. + * Get the {@link org.eclipse.jgit.lib.ObjectInserter} from which this + * reader was created using {@code inserter.newReader()} + * + * @return the {@link org.eclipse.jgit.lib.ObjectInserter} from which this + * reader was created using {@code inserter.newReader()}, or null if + * this reader was not created from an inserter. * @since 4.4 */ @Nullable @@ -453,6 +457,8 @@ public abstract class ObjectReader implements AutoCloseable { } /** + * {@inheritDoc} + * <p> * Release any resources used by this reader. * <p> * A reader that has been released can be used again, but may need to be diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectStream.java index 4b3fe6af57..ad123c4a3a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectStream.java @@ -46,12 +46,22 @@ package org.eclipse.jgit.lib; import java.io.IOException; import java.io.InputStream; -/** Stream of data coming from an object loaded by {@link ObjectLoader}. */ +/** + * Stream of data coming from an object loaded by {@link org.eclipse.jgit.lib.ObjectLoader}. + */ public abstract class ObjectStream extends InputStream { - /** @return Git object type, see {@link Constants}. */ + /** + * Get Git object type, see {@link Constants}. + * + * @return Git object type, see {@link Constants}. + */ public abstract int getType(); - /** @return total size of object in bytes */ + /** + * Get total size of object in bytes + * + * @return total size of object in bytes + */ public abstract long getSize(); /** diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/PersonIdent.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/PersonIdent.java index 45757e42f5..18a11f0015 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/PersonIdent.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/PersonIdent.java @@ -65,6 +65,8 @@ public class PersonIdent implements Serializable { private static final long serialVersionUID = 1L; /** + * Get timezone object for the given offset. + * * @param tzOffset * timezone offset as in {@link #getTimeZoneOffset()}. * @return time zone object for the given offset. @@ -163,38 +165,45 @@ public class PersonIdent implements Serializable { * This new PersonIdent gets the info from the default committer as available * from the configuration. * - * @param repo + * @param repo a {@link org.eclipse.jgit.lib.Repository} object. */ public PersonIdent(final Repository repo) { this(repo.getConfig().get(UserConfig.KEY)); } /** - * Copy a {@link PersonIdent}. + * Copy a {@link org.eclipse.jgit.lib.PersonIdent}. * * @param pi - * Original {@link PersonIdent} + * Original {@link org.eclipse.jgit.lib.PersonIdent} */ public PersonIdent(final PersonIdent pi) { this(pi.getName(), pi.getEmailAddress()); } /** - * Construct a new {@link PersonIdent} with current time. + * Construct a new {@link org.eclipse.jgit.lib.PersonIdent} with current + * time. * * @param aName + * a {@link java.lang.String} object. * @param aEmailAddress + * a {@link java.lang.String} object. */ public PersonIdent(final String aName, final String aEmailAddress) { this(aName, aEmailAddress, SystemReader.getInstance().getCurrentTime()); } /** - * Construct a new {@link PersonIdent} with current time. + * Construct a new {@link org.eclipse.jgit.lib.PersonIdent} with current + * time. * * @param aName + * a {@link java.lang.String} object. * @param aEmailAddress + * a {@link java.lang.String} object. * @param when + * a {@link org.eclipse.jgit.util.time.ProposedTimestamp} object. * @since 4.6 */ public PersonIdent(String aName, String aEmailAddress, @@ -206,7 +215,7 @@ public class PersonIdent implements Serializable { * Copy a PersonIdent, but alter the clone's time stamp * * @param pi - * original {@link PersonIdent} + * original {@link org.eclipse.jgit.lib.PersonIdent} * @param when * local time * @param tz @@ -217,10 +226,11 @@ public class PersonIdent implements Serializable { } /** - * Copy a {@link PersonIdent}, but alter the clone's time stamp + * Copy a {@link org.eclipse.jgit.lib.PersonIdent}, but alter the clone's + * time stamp * * @param pi - * original {@link PersonIdent} + * original {@link org.eclipse.jgit.lib.PersonIdent} * @param aWhen * local time */ @@ -231,8 +241,8 @@ public class PersonIdent implements Serializable { /** * Construct a PersonIdent from simple data * - * @param aName - * @param aEmailAddress + * @param aName a {@link java.lang.String} object. + * @param aEmailAddress a {@link java.lang.String} object. * @param aWhen * local time stamp * @param aTZ @@ -248,7 +258,7 @@ public class PersonIdent implements Serializable { * Copy a PersonIdent, but alter the clone's time stamp * * @param pi - * original {@link PersonIdent} + * original {@link org.eclipse.jgit.lib.PersonIdent} * @param aWhen * local time stamp * @param aTZ @@ -269,7 +279,7 @@ public class PersonIdent implements Serializable { } /** - * Construct a {@link PersonIdent}. + * Construct a {@link org.eclipse.jgit.lib.PersonIdent}. * <p> * Whitespace in the name and email is preserved for the lifetime of this * object, but are trimmed by {@link #toExternalString()}. This means that @@ -277,7 +287,9 @@ public class PersonIdent implements Serializable { * equivalent instance. * * @param aName + * a {@link java.lang.String} object. * @param aEmailAddress + * a {@link java.lang.String} object. * @param aWhen * local time stamp * @param aTZ @@ -298,6 +310,8 @@ public class PersonIdent implements Serializable { } /** + * Get name of person + * * @return Name of person */ public String getName() { @@ -305,6 +319,8 @@ public class PersonIdent implements Serializable { } /** + * Get email address of person + * * @return email address of person */ public String getEmailAddress() { @@ -312,6 +328,8 @@ public class PersonIdent implements Serializable { } /** + * Get timestamp + * * @return timestamp */ public Date getWhen() { @@ -319,6 +337,8 @@ public class PersonIdent implements Serializable { } /** + * Get this person's declared time zone + * * @return this person's declared time zone; null if time zone is unknown. */ public TimeZone getTimeZone() { @@ -326,6 +346,8 @@ public class PersonIdent implements Serializable { } /** + * Get this person's declared time zone as minutes east of UTC. + * * @return this person's declared time zone as minutes east of UTC. If the * timezone is to the west of UTC it is negative. */ @@ -334,6 +356,8 @@ public class PersonIdent implements Serializable { } /** + * {@inheritDoc} + * <p> * Hashcode is based only on the email address and timestamp. */ @Override @@ -344,6 +368,7 @@ public class PersonIdent implements Serializable { return hc; } + /** {@inheritDoc} */ @Override public boolean equals(final Object o) { if (o instanceof PersonIdent) { @@ -372,6 +397,7 @@ public class PersonIdent implements Serializable { return r.toString(); } + /** {@inheritDoc} */ @Override @SuppressWarnings("nls") public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ProgressMonitor.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ProgressMonitor.java index 7748140e2c..d81ee45c9e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ProgressMonitor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ProgressMonitor.java @@ -44,7 +44,9 @@ package org.eclipse.jgit.lib; -/** A progress reporting interface. */ +/** + * A progress reporting interface. + */ public interface ProgressMonitor { /** Constant indicating the total work units cannot be predicted. */ public static final int UNKNOWN = 0; @@ -85,7 +87,9 @@ public interface ProgressMonitor { */ void update(int completed); - /** Finish the current task, so the next can begin. */ + /** + * Finish the current task, so the next can begin. + */ void endTask(); /** diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RebaseTodoFile.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RebaseTodoFile.java index c4923a359e..06b4b227c8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RebaseTodoFile.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RebaseTodoFile.java @@ -67,7 +67,10 @@ public class RebaseTodoFile { private Repository repo; /** + * Constructor for RebaseTodoFile. + * * @param repo + * a {@link org.eclipse.jgit.lib.Repository} object. */ public RebaseTodoFile(Repository repo) { this.repo = repo; @@ -84,7 +87,7 @@ public class RebaseTodoFile { * @param includeComments * <code>true</code> if also comments should be reported * @return the list of steps - * @throws IOException + * @throws java.io.IOException */ public List<RebaseTodoLine> readRebaseTodo(String path, boolean includeComments) throws IOException { @@ -214,7 +217,7 @@ public class RebaseTodoFile { * the steps to be written * @param append * whether to append to an existing file or to write a new file - * @throws IOException + * @throws java.io.IOException */ public void writeRebaseTodoFile(String path, List<RebaseTodoLine> steps, boolean append) throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RebaseTodoLine.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RebaseTodoLine.java index 9af8d76910..4e235b05c0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RebaseTodoLine.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RebaseTodoLine.java @@ -142,8 +142,11 @@ public class RebaseTodoLine { * Create a new non-comment line * * @param action + * a {@link org.eclipse.jgit.lib.RebaseTodoLine.Action} object. * @param commit + * a {@link org.eclipse.jgit.lib.AbbreviatedObjectId} object. * @param shortMessage + * a {@link java.lang.String} object. */ public RebaseTodoLine(Action action, AbbreviatedObjectId commit, String shortMessage) { @@ -154,6 +157,8 @@ public class RebaseTodoLine { } /** + * Get rebase action type + * * @return rebase action type */ public Action getAction() { @@ -167,7 +172,8 @@ public class RebaseTodoLine { * non-comment. * * @param newAction - * @throws IllegalTodoFileModification + * a {@link org.eclipse.jgit.lib.RebaseTodoLine.Action} object. + * @throws org.eclipse.jgit.errors.IllegalTodoFileModification * on attempt to set a non-comment action on a line which was a * comment line before. */ @@ -193,7 +199,7 @@ public class RebaseTodoLine { /** * <p> * Set a comment for this line that is used if this line's - * {@link RebaseTodoLine#action} is a {@link Action#COMMENT} + * {@link org.eclipse.jgit.lib.RebaseTodoLine#action} is a {@link org.eclipse.jgit.lib.RebaseTodoLine.Action#COMMENT} * </p> * It's allowed to unset the comment by calling * <code>setComment(null)</code> <br> @@ -230,6 +236,8 @@ public class RebaseTodoLine { } /** + * Get abbreviated commit SHA-1 of commit that action will be performed on + * * @return abbreviated commit SHA-1 of commit that action will be performed * on */ @@ -238,6 +246,9 @@ public class RebaseTodoLine { } /** + * Get the first line of the commit message of the commit the action will be + * performed on. + * * @return the first line of the commit message of the commit the action * will be performed on. */ @@ -246,13 +257,18 @@ public class RebaseTodoLine { } /** + * Set short message + * * @param shortMessage + * a short message. */ public void setShortMessage(String shortMessage) { this.shortMessage = shortMessage; } /** + * Get a comment + * * @return a comment. If the line is a comment line then the comment is * returned. Lines starting with # or blank lines or lines * containing only spaces and tabs are considered as comment lines. @@ -262,6 +278,7 @@ public class RebaseTodoLine { return comment; } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Ref.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Ref.java index a78a90fe58..395bb323de 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Ref.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Ref.java @@ -47,7 +47,8 @@ import org.eclipse.jgit.annotations.NonNull; import org.eclipse.jgit.annotations.Nullable; /** - * Pairing of a name and the {@link ObjectId} it currently has. + * Pairing of a name and the {@link org.eclipse.jgit.lib.ObjectId} it currently + * has. * <p> * A ref in Git is (more or less) a variable that holds a single object * identifier. The object identifier can be any valid Git object (blob, tree, @@ -135,9 +136,10 @@ public interface Ref { /** * Test if this reference is a symbolic reference. * <p> - * A symbolic reference does not have its own {@link ObjectId} value, but - * instead points to another {@code Ref} in the same database and always - * uses that other reference's value as its own. + * A symbolic reference does not have its own + * {@link org.eclipse.jgit.lib.ObjectId} value, but instead points to + * another {@code Ref} in the same database and always uses that other + * reference's value as its own. * * @return true if this is a symbolic reference; false if this reference * contains its own ObjectId. @@ -199,7 +201,9 @@ public interface Ref { public abstract ObjectId getPeeledObjectId(); /** - * @return whether the Ref represents a peeled tag + * Whether the Ref represents a peeled tag. + * + * @return whether the Ref represents a peeled tag. */ public abstract boolean isPeeled(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefComparator.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefComparator.java index 95e338685a..43d2f3766c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefComparator.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefComparator.java @@ -60,6 +60,7 @@ public class RefComparator implements Comparator<Ref> { /** Singleton instance of RefComparator */ public static final RefComparator INSTANCE = new RefComparator(); + /** {@inheritDoc} */ @Override public int compare(final Ref o1, final Ref o2) { return compareTo(o1, o2); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefDatabase.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefDatabase.java index 59a104b60f..557bdb994f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefDatabase.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefDatabase.java @@ -55,11 +55,13 @@ import org.eclipse.jgit.annotations.NonNull; import org.eclipse.jgit.annotations.Nullable; /** - * Abstraction of name to {@link ObjectId} mapping. + * Abstraction of name to {@link org.eclipse.jgit.lib.ObjectId} mapping. * <p> - * A reference database stores a mapping of reference names to {@link ObjectId}. - * Every {@link Repository} has a single reference database, mapping names to - * the tips of the object graph contained by the {@link ObjectDatabase}. + * A reference database stores a mapping of reference names to + * {@link org.eclipse.jgit.lib.ObjectId}. Every + * {@link org.eclipse.jgit.lib.Repository} has a single reference database, + * mapping names to the tips of the object graph contained by the + * {@link org.eclipse.jgit.lib.ObjectDatabase}. */ public abstract class RefDatabase { /** @@ -93,12 +95,14 @@ public abstract class RefDatabase { /** * Initialize a new reference database at this location. * - * @throws IOException + * @throws java.io.IOException * the database could not be created. */ public abstract void create() throws IOException; - /** Close any resources held by this database. */ + /** + * Close any resources held by this database. + */ public abstract void close(); /** @@ -118,7 +122,7 @@ public abstract class RefDatabase { * proposed name. * @return true if the name overlaps with an existing reference; false if * using this name right now would be safe. - * @throws IOException + * @throws java.io.IOException * the database could not be read to check for conflicts. * @see #getConflictingNames(String) */ @@ -133,7 +137,7 @@ public abstract class RefDatabase { * @return a collection of full names of existing refs which would conflict * with the passed ref name; empty collection when there are no * conflicts - * @throws IOException + * @throws java.io.IOException * @since 2.3 * @see #isNameConflicting(String) */ @@ -167,12 +171,13 @@ public abstract class RefDatabase { * the name of the reference. * @param detach * if {@code true} and {@code name} is currently a - * {@link SymbolicRef}, the update will replace it with an - * {@link ObjectIdRef}. Otherwise, the update will recursively - * traverse {@link SymbolicRef}s and operate on the leaf - * {@link ObjectIdRef}. + * {@link org.eclipse.jgit.lib.SymbolicRef}, the update will + * replace it with an {@link org.eclipse.jgit.lib.ObjectIdRef}. + * Otherwise, the update will recursively traverse + * {@link org.eclipse.jgit.lib.SymbolicRef}s and operate on the + * leaf {@link org.eclipse.jgit.lib.ObjectIdRef}. * @return a new update for the requested name; never null. - * @throws IOException + * @throws java.io.IOException * the reference space cannot be accessed. */ @NonNull @@ -187,7 +192,7 @@ public abstract class RefDatabase { * @param toName * name of reference to rename to * @return an update command that knows how to rename a branch to another. - * @throws IOException + * @throws java.io.IOException * the reference space cannot be accessed. */ @NonNull @@ -210,20 +215,21 @@ public abstract class RefDatabase { * Whether the database is capable of performing batch updates as atomic * transactions. * <p> - * If true, by default {@link BatchRefUpdate} instances will perform updates - * atomically, meaning either all updates will succeed, or all updates will - * fail. It is still possible to turn off this behavior on a per-batch basis - * by calling {@code update.setAtomic(false)}. + * If true, by default {@link org.eclipse.jgit.lib.BatchRefUpdate} instances + * will perform updates atomically, meaning either all updates will succeed, + * or all updates will fail. It is still possible to turn off this behavior + * on a per-batch basis by calling {@code update.setAtomic(false)}. * <p> - * If false, {@link BatchRefUpdate} instances will never perform updates - * atomically, and calling {@code update.setAtomic(true)} will cause the - * entire batch to fail with {@code REJECTED_OTHER_REASON}. + * If false, {@link org.eclipse.jgit.lib.BatchRefUpdate} instances will + * never perform updates atomically, and calling + * {@code update.setAtomic(true)} will cause the entire batch to fail with + * {@code REJECTED_OTHER_REASON}. * <p> * This definition of atomicity is stronger than what is provided by * {@link org.eclipse.jgit.transport.ReceivePack}. {@code ReceivePack} will * attempt to reject all commands if it knows in advance some commands may - * fail, even if the storage layer does not support atomic transactions. Here, - * atomicity applies even in the case of unforeseeable errors. + * fail, even if the storage layer does not support atomic transactions. + * Here, atomicity applies even in the case of unforeseeable errors. * * @return whether transactions are atomic by default. * @since 3.6 @@ -246,7 +252,7 @@ public abstract class RefDatabase { * the name of the reference. May be a short name which must be * searched for using the standard {@link #SEARCH_PATH}. * @return the reference (if it exists); else {@code null}. - * @throws IOException + * @throws java.io.IOException * the reference space cannot be accessed. */ @Nullable @@ -261,7 +267,7 @@ public abstract class RefDatabase { * @param name * the unabbreviated name of the reference. * @return the reference (if it exists); else {@code null}. - * @throws IOException + * @throws java.io.IOException * the reference space cannot be accessed. * @since 4.1 */ @@ -285,7 +291,7 @@ public abstract class RefDatabase { * the unabbreviated names of references to look up. * @return modifiable map describing any refs that exist among the ref * ref names supplied. The map can be an unsorted map. - * @throws IOException + * @throws java.io.IOException * the reference space cannot be accessed. * @since 4.1 */ @@ -310,7 +316,7 @@ public abstract class RefDatabase { * @param refs * the unabbreviated names of references to look up. * @return the first named reference that exists (if any); else {@code null}. - * @throws IOException + * @throws java.io.IOException * the reference space cannot be accessed. * @since 4.1 */ @@ -335,7 +341,7 @@ public abstract class RefDatabase { * @return modifiable map that is a complete snapshot of the current * reference namespace, with {@code prefix} removed from the start * of each key. The map can be an unsorted map. - * @throws IOException + * @throws java.io.IOException * the reference space cannot be accessed. */ @NonNull @@ -350,7 +356,7 @@ public abstract class RefDatabase { * and {@link #exactRef(String)}. * * @return a list of additional refs - * @throws IOException + * @throws java.io.IOException * the reference space cannot be accessed. */ @NonNull @@ -360,10 +366,11 @@ public abstract class RefDatabase { * Peel a possibly unpeeled reference by traversing the annotated tags. * <p> * If the reference cannot be peeled (as it does not refer to an annotated - * tag) the peeled id stays null, but {@link Ref#isPeeled()} will be true. + * tag) the peeled id stays null, but + * {@link org.eclipse.jgit.lib.Ref#isPeeled()} will be true. * <p> - * Implementors should check {@link Ref#isPeeled()} before performing any - * additional work effort. + * Implementors should check {@link org.eclipse.jgit.lib.Ref#isPeeled()} + * before performing any additional work effort. * * @param ref * The reference to peel @@ -371,7 +378,7 @@ public abstract class RefDatabase { * Ref object representing the same data as Ref, but isPeeled() will * be true and getPeeledObjectId() will contain the peeled object * (or {@code null}). - * @throws IOException + * @throws java.io.IOException * the reference space or object space cannot be accessed. */ @NonNull diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefRename.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefRename.java index 59f852b8c7..3d22bb0fc5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefRename.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefRename.java @@ -86,7 +86,11 @@ public abstract class RefRename { + Repository.shortenRefName(destination.getName())); } - /** @return identity of the user making the change in the reflog. */ + /** + * Get identity of the user making the change in the reflog. + * + * @return identity of the user making the change in the reflog. + */ public PersonIdent getRefLogIdent() { return destination.getRefLogIdent(); } @@ -130,12 +134,16 @@ public abstract class RefRename { destination.setRefLogMessage(msg, false); } - /** Don't record this rename in the ref's associated reflog. */ + /** + * Don't record this rename in the ref's associated reflog. + */ public void disableRefLog() { destination.setRefLogMessage("", false); //$NON-NLS-1$ } /** + * Get result of rename operation + * * @return result of rename operation */ public Result getResult() { @@ -143,8 +151,10 @@ public abstract class RefRename { } /** + * Rename + * * @return the result of the new ref update - * @throws IOException + * @throws java.io.IOException */ public Result rename() throws IOException { try { @@ -157,15 +167,20 @@ public abstract class RefRename { } /** + * Do the actual rename + * * @return the result of the rename operation. - * @throws IOException + * @throws java.io.IOException */ protected abstract Result doRename() throws IOException; /** + * Whether the {@code Constants#HEAD} reference needs to be linked to the + * new destination name. + * * @return true if the {@code Constants#HEAD} reference needs to be linked * to the new destination name. - * @throws IOException + * @throws java.io.IOException * the current value of {@code HEAD} cannot be read. */ protected boolean needToUpdateHEAD() throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefUpdate.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefUpdate.java index 766b21da0e..06a7576db1 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefUpdate.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefUpdate.java @@ -233,10 +233,18 @@ public abstract class RefUpdate { refLogMessage = ""; //$NON-NLS-1$ } - /** @return the reference database this update modifies. */ + /** + * Get the reference database this update modifies. + * + * @return the reference database this update modifies. + */ protected abstract RefDatabase getRefDatabase(); - /** @return the repository storing the database's objects. */ + /** + * Get the repository storing the database's objects. + * + * @return the repository storing the database's objects. + */ protected abstract Repository getRepository(); /** @@ -251,33 +259,44 @@ public abstract class RefUpdate { * current reference. * @return true if the lock was acquired and the reference is likely * protected from concurrent modification; false if it failed. - * @throws IOException + * @throws java.io.IOException * the lock couldn't be taken due to an unexpected storage * failure, and not because of a concurrent update. */ protected abstract boolean tryLock(boolean deref) throws IOException; - /** Releases the lock taken by {@link #tryLock} if it succeeded. */ + /** + * Releases the lock taken by {@link #tryLock} if it succeeded. + */ protected abstract void unlock(); /** + * Do update + * * @param desiredResult + * a {@link org.eclipse.jgit.lib.RefUpdate.Result} object. * @return {@code result} - * @throws IOException + * @throws java.io.IOException */ protected abstract Result doUpdate(Result desiredResult) throws IOException; /** + * Do delete + * * @param desiredResult + * a {@link org.eclipse.jgit.lib.RefUpdate.Result} object. * @return {@code result} - * @throws IOException + * @throws java.io.IOException */ protected abstract Result doDelete(Result desiredResult) throws IOException; /** + * Do link + * * @param target - * @return {@link Result#NEW} on success. - * @throws IOException + * a {@link java.lang.String} object. + * @return {@link org.eclipse.jgit.lib.RefUpdate.Result#NEW} on success. + * @throws java.io.IOException */ protected abstract Result doLink(String target) throws IOException; @@ -290,7 +309,11 @@ public abstract class RefUpdate { return getRef().getName(); } - /** @return the reference this update will create or modify. */ + /** + * Get the reference this update will create or modify. + * + * @return the reference this update will create or modify. + */ public Ref getRef() { return ref; } @@ -332,21 +355,27 @@ public abstract class RefUpdate { } /** + * Get the expected value of the ref after the lock is taken, but before + * update occurs. + * * @return the expected value of the ref after the lock is taken, but before * update occurs. Null to avoid the compare and swap test. Use - * {@link ObjectId#zeroId()} to indicate expectation of a - * non-existant ref. + * {@link org.eclipse.jgit.lib.ObjectId#zeroId()} to indicate + * expectation of a non-existant ref. */ public ObjectId getExpectedOldObjectId() { return expValue; } /** + * Set the expected value of the ref after the lock is taken, but before + * update occurs. + * * @param id * the expected value of the ref after the lock is taken, but * before update occurs. Null to avoid the compare and swap test. - * Use {@link ObjectId#zeroId()} to indicate expectation of a - * non-existant ref. + * Use {@link org.eclipse.jgit.lib.ObjectId#zeroId()} to indicate + * expectation of a non-existant ref. */ public void setExpectedOldObjectId(final AnyObjectId id) { expValue = id != null ? id.toObjectId() : null; @@ -371,7 +400,11 @@ public abstract class RefUpdate { force = b; } - /** @return identity of the user making the change in the reflog. */ + /** + * Get identity of the user making the change in the reflog. + * + * @return identity of the user making the change in the reflog. + */ public PersonIdent getRefLogIdent() { return refLogIdent; } @@ -402,7 +435,11 @@ public abstract class RefUpdate { return refLogMessage; } - /** @return {@code true} if the ref log message should show the result. */ + /** + * Whether the ref log message should show the result. + * + * @return {@code true} if the ref log message should show the result. + */ protected boolean isRefLogIncludingResult() { return refLogIncludeResult; } @@ -436,7 +473,9 @@ public abstract class RefUpdate { } } - /** Don't record this update in the ref's associated reflog. */ + /** + * Don't record this update in the ref's associated reflog. + */ public void disableRefLog() { refLogMessage = null; refLogIncludeResult = false; @@ -535,7 +574,7 @@ public abstract class RefUpdate { * the merge test is performed. * * @return the result status of the update. - * @throws IOException + * @throws java.io.IOException * an unexpected IO error occurred while writing changes. */ public Result forceUpdate() throws IOException { @@ -555,7 +594,7 @@ public abstract class RefUpdate { * </pre> * * @return the result status of the update. - * @throws IOException + * @throws java.io.IOException * an unexpected IO error occurred while writing changes. */ public Result update() throws IOException { @@ -573,7 +612,7 @@ public abstract class RefUpdate { * a RevWalk instance this update command can borrow to perform * the merge test. The walk will be reset to perform the test. * @return the result status of the update. - * @throws IOException + * @throws java.io.IOException * an unexpected IO error occurred while writing changes. */ public Result update(final RevWalk walk) throws IOException { @@ -603,7 +642,7 @@ public abstract class RefUpdate { * </pre> * * @return the result status of the delete. - * @throws IOException + * @throws java.io.IOException */ public Result delete() throws IOException { try (RevWalk rw = new RevWalk(getRepository())) { @@ -618,7 +657,7 @@ public abstract class RefUpdate { * a RevWalk instance this delete command can borrow to perform * the merge test. The walk will be reset to perform the test. * @return the result status of the delete. - * @throws IOException + * @throws java.io.IOException */ public Result delete(final RevWalk walk) throws IOException { final String myName = detachingSymbolicRef @@ -656,8 +695,9 @@ public abstract class RefUpdate { * @param target * name of the new target for this reference. The new target name * must be absolute, so it must begin with {@code refs/}. - * @return {@link Result#NEW} or {@link Result#FORCED} on success. - * @throws IOException + * @return {@link org.eclipse.jgit.lib.RefUpdate.Result#NEW} or + * {@link org.eclipse.jgit.lib.RefUpdate.Result#FORCED} on success. + * @throws java.io.IOException */ public Result link(String target) throws IOException { if (!target.startsWith(Constants.R_REFS)) @@ -751,6 +791,7 @@ public abstract class RefUpdate { * are checked explicitly. * * @param check + * whether to enable the check for conflicting ref names. * @since 3.0 */ public void setCheckConflicting(boolean check) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefWriter.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefWriter.java index 3a02b22813..90a0350dd7 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefWriter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RefWriter.java @@ -56,8 +56,8 @@ import org.eclipse.jgit.util.RefList; import org.eclipse.jgit.util.RefMap; /** - * Writes out refs to the {@link Constants#INFO_REFS} and - * {@link Constants#PACKED_REFS} files. + * Writes out refs to the {@link org.eclipse.jgit.lib.Constants#INFO_REFS} and + * {@link org.eclipse.jgit.lib.Constants#PACKED_REFS} files. * * This class is abstract as the writing of the files must be handled by the * caller. This is because it is used by transport classes as well. @@ -67,6 +67,8 @@ public abstract class RefWriter { private final Collection<Ref> refs; /** + * <p>Constructor for RefWriter.</p> + * * @param refs * the complete set of references. This should have been computed * by applying updates to the advertised refs already discovered. @@ -76,6 +78,8 @@ public abstract class RefWriter { } /** + * <p>Constructor for RefWriter.</p> + * * @param refs * the complete set of references. This should have been computed * by applying updates to the advertised refs already discovered. @@ -88,6 +92,8 @@ public abstract class RefWriter { } /** + * <p>Constructor for RefWriter.</p> + * * @param refs * the complete set of references. This should have been computed * by applying updates to the advertised refs already discovered. @@ -97,13 +103,13 @@ public abstract class RefWriter { } /** - * Rebuild the {@link Constants#INFO_REFS}. + * Rebuild the {@link org.eclipse.jgit.lib.Constants#INFO_REFS}. * <p> - * This method rebuilds the contents of the {@link Constants#INFO_REFS} file - * to match the passed list of references. - * + * This method rebuilds the contents of the + * {@link org.eclipse.jgit.lib.Constants#INFO_REFS} file to match the passed + * list of references. * - * @throws IOException + * @throws java.io.IOException * writing is not supported, or attempting to write the file * failed, possibly due to permissions or remote disk full, etc. */ @@ -142,13 +148,14 @@ public abstract class RefWriter { } /** - * Rebuild the {@link Constants#PACKED_REFS} file. + * Rebuild the {@link org.eclipse.jgit.lib.Constants#PACKED_REFS} file. * <p> - * This method rebuilds the contents of the {@link Constants#PACKED_REFS} - * file to match the passed list of references, including only those refs - * that have a storage type of {@link Ref.Storage#PACKED}. + * This method rebuilds the contents of the + * {@link org.eclipse.jgit.lib.Constants#PACKED_REFS} file to match the + * passed list of references, including only those refs that have a storage + * type of {@link org.eclipse.jgit.lib.Ref.Storage#PACKED}. * - * @throws IOException + * @throws java.io.IOException * writing is not supported, or attempting to write the file * failed, possibly due to permissions or remote disk full, etc. */ @@ -203,7 +210,7 @@ public abstract class RefWriter { * path to ref file. * @param content * byte content of file to be written. - * @throws IOException + * @throws java.io.IOException */ protected abstract void writeFile(String file, byte[] content) throws IOException; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ReflogEntry.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ReflogEntry.java index afa6521d67..51f2ea0ab7 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ReflogEntry.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ReflogEntry.java @@ -83,28 +83,39 @@ public interface ReflogEntry { public static final String PREFIX_FORCED_UPDATE = "forced-update"; //$NON-NLS-1$ /** + * Get the commit id before the change + * * @return the commit id before the change */ public abstract ObjectId getOldId(); /** + * Get the commit id after the change + * * @return the commit id after the change */ public abstract ObjectId getNewId(); /** + * Get user performing the change + * * @return user performing the change */ public abstract PersonIdent getWho(); /** + * Get textual description of the change + * * @return textual description of the change */ public abstract String getComment(); /** - * @return a {@link CheckoutEntry} with parsed information about a branch - * switch, or null if the entry is not a checkout + * Parse checkout + * + * @return a {@link org.eclipse.jgit.lib.CheckoutEntry} with parsed + * information about a branch switch, or null if the entry is not a + * checkout */ public abstract CheckoutEntry parseCheckout(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ReflogReader.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ReflogReader.java index d3f25369bd..f97b07e08c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ReflogReader.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ReflogReader.java @@ -57,13 +57,15 @@ public interface ReflogReader { * Get the last entry in the reflog * * @return the latest reflog entry, or null if no log - * @throws IOException + * @throws java.io.IOException */ public abstract ReflogEntry getLastEntry() throws IOException; /** + * Get all reflog entries in reverse order + * * @return all reflog entries in reverse order - * @throws IOException + * @throws java.io.IOException */ public abstract List<ReflogEntry> getReverseEntries() throws IOException; @@ -71,17 +73,19 @@ public interface ReflogReader { * Get specific entry in the reflog relative to the last entry which is * considered entry zero. * - * @param number + * @param number a int. * @return reflog entry or null if not found - * @throws IOException + * @throws java.io.IOException */ public abstract ReflogEntry getReverseEntry(int number) throws IOException; /** + * Get all reflog entries in reverse order + * * @param max * max number of entries to read * @return all reflog entries in reverse order - * @throws IOException + * @throws java.io.IOException */ public abstract List<ReflogEntry> getReverseEntries(int max) throws IOException; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java index fdf59667f5..fae7f1cb76 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java @@ -85,7 +85,6 @@ import org.eclipse.jgit.events.IndexChangedListener; import org.eclipse.jgit.events.ListenerList; import org.eclipse.jgit.events.RepositoryEvent; import org.eclipse.jgit.internal.JGitText; -import org.eclipse.jgit.internal.storage.file.GC; import org.eclipse.jgit.revwalk.RevBlob; import org.eclipse.jgit.revwalk.RevCommit; import org.eclipse.jgit.revwalk.RevObject; @@ -108,9 +107,9 @@ import org.slf4j.LoggerFactory; * A repository holds all objects and refs used for managing source code (could * be any type of file, but source code is what SCM's are typically used for). * <p> - * The thread-safety of a {@link Repository} very much depends on the concrete - * implementation. Applications working with a generic {@code Repository} type - * must not assume the instance is thread-safe. + * The thread-safety of a {@link org.eclipse.jgit.lib.Repository} very much + * depends on the concrete implementation. Applications working with a generic + * {@code Repository} type must not assume the instance is thread-safe. * <ul> * <li>{@code FileRepository} is thread-safe. * <li>{@code DfsRepository} thread-safety is determined by its subclass. @@ -131,7 +130,11 @@ public abstract class Repository implements AutoCloseable { "(^|/)(aux|com[1-9]|con|lpt[1-9]|nul|prn)(\\.[^/]*)?", //$NON-NLS-1$ Pattern.CASE_INSENSITIVE); - /** @return the global listener list observing all events in this JVM. */ + /** + * Get the global listener list observing all events in this JVM. + * + * @return the global listener list observing all events in this JVM. + */ public static ListenerList getGlobalListenerList() { return globalListeners; } @@ -168,7 +171,11 @@ public abstract class Repository implements AutoCloseable { indexFile = options.getIndexFile(); } - /** @return listeners observing only events on this repository. */ + /** + * Get listeners observing only events on this repository. + * + * @return listeners observing only events on this repository. + */ @NonNull public ListenerList getListenerList() { return myListeners; @@ -195,7 +202,7 @@ public abstract class Repository implements AutoCloseable { * Repository with working tree is created using this method. This method is * the same as {@code create(false)}. * - * @throws IOException + * @throws java.io.IOException * @see #create(boolean) */ public void create() throws IOException { @@ -209,12 +216,14 @@ public abstract class Repository implements AutoCloseable { * @param bare * if true, a bare repository (a repository without a working * directory) is created. - * @throws IOException + * @throws java.io.IOException * in case of IO problem */ public abstract void create(boolean bare) throws IOException; /** + * Get local metadata directory + * * @return local metadata directory; {@code null} if repository isn't local. */ /* @@ -229,44 +238,64 @@ public abstract class Repository implements AutoCloseable { } /** + * Get the object database which stores this repository's data. + * * @return the object database which stores this repository's data. */ @NonNull public abstract ObjectDatabase getObjectDatabase(); - /** @return a new inserter to create objects in {@link #getObjectDatabase()} */ + /** + * Create a new inserter to create objects in {@link #getObjectDatabase()}. + * + * @return a new inserter to create objects in {@link #getObjectDatabase()}. + */ @NonNull public ObjectInserter newObjectInserter() { return getObjectDatabase().newInserter(); } - /** @return a new reader to read objects from {@link #getObjectDatabase()} */ + /** + * Create a new reader to read objects from {@link #getObjectDatabase()}. + * + * @return a new reader to read objects from {@link #getObjectDatabase()}. + */ @NonNull public ObjectReader newObjectReader() { return getObjectDatabase().newReader(); } - /** @return the reference database which stores the reference namespace. */ + /** + * Get the reference database which stores the reference namespace. + * + * @return the reference database which stores the reference namespace. + */ @NonNull public abstract RefDatabase getRefDatabase(); /** - * @return the configuration of this repository + * Get the configuration of this repository. + * + * @return the configuration of this repository. */ @NonNull public abstract StoredConfig getConfig(); /** - * @return a new {@link AttributesNodeProvider}. This - * {@link AttributesNodeProvider} is lazy loaded only once. It means - * that it will not be updated after loading. Prefer creating new - * instance for each use. + * Create a new {@link org.eclipse.jgit.attributes.AttributesNodeProvider}. + * + * @return a new {@link org.eclipse.jgit.attributes.AttributesNodeProvider}. + * This {@link org.eclipse.jgit.attributes.AttributesNodeProvider} + * is lazy loaded only once. It means that it will not be updated + * after loading. Prefer creating new instance for each use. * @since 4.2 */ @NonNull public abstract AttributesNodeProvider createAttributesNodeProvider(); /** + * Get the used file system abstraction. + * * @return the used file system abstraction, or or {@code null} if * repository isn't local. */ @@ -282,7 +311,11 @@ public abstract class Repository implements AutoCloseable { } /** + * Whether the specified object is stored in this repo or any of the known + * shared repositories. + * * @param objectId + * a {@link org.eclipse.jgit.lib.AnyObjectId} object. * @return true if the specified object is stored in this repo or any of the * known shared repositories. */ @@ -303,10 +336,11 @@ public abstract class Repository implements AutoCloseable { * * @param objectId * identity of the object to open. - * @return a {@link ObjectLoader} for accessing the object. - * @throws MissingObjectException + * @return a {@link org.eclipse.jgit.lib.ObjectLoader} for accessing the + * object. + * @throws org.eclipse.jgit.errors.MissingObjectException * the object does not exist. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ @NonNull @@ -325,16 +359,17 @@ public abstract class Repository implements AutoCloseable { * identity of the object to open. * @param typeHint * hint about the type of object being requested, e.g. - * {@link Constants#OBJ_BLOB}; {@link ObjectReader#OBJ_ANY} if - * the object type is not known, or does not matter to the - * caller. - * @return a {@link ObjectLoader} for accessing the object. - * @throws MissingObjectException + * {@link org.eclipse.jgit.lib.Constants#OBJ_BLOB}; + * {@link org.eclipse.jgit.lib.ObjectReader#OBJ_ANY} if the + * object type is not known, or does not matter to the caller. + * @return a {@link org.eclipse.jgit.lib.ObjectLoader} for accessing the + * object. + * @throws org.eclipse.jgit.errors.MissingObjectException * the object does not exist. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * typeHint was not OBJ_ANY, and the object's actual type does * not match typeHint. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ @NonNull @@ -352,7 +387,7 @@ public abstract class Repository implements AutoCloseable { * @return an update command. The caller must finish populating this command * and then invoke one of the update methods to actually make a * change. - * @throws IOException + * @throws java.io.IOException * a symbolic ref was passed in and could not be resolved back * to the base ref, as the symbolic ref could not be read. */ @@ -371,7 +406,7 @@ public abstract class Repository implements AutoCloseable { * @return an update command. The caller must finish populating this command * and then invoke one of the update methods to actually make a * change. - * @throws IOException + * @throws java.io.IOException * a symbolic ref was passed in and could not be resolved back * to the base ref, as the symbolic ref could not be read. */ @@ -388,9 +423,8 @@ public abstract class Repository implements AutoCloseable { * @param toRef * name of ref to rename to * @return an update command that knows how to rename a branch to another. - * @throws IOException + * @throws java.io.IOException * the rename could not be performed. - * */ @NonNull public RefRename renameRef(final String fromRef, final String toRef) throws IOException { @@ -434,17 +468,17 @@ public abstract class Repository implements AutoCloseable { * A git object references expression * @return an ObjectId or {@code null} if revstr can't be resolved to any * ObjectId - * @throws AmbiguousObjectException + * @throws org.eclipse.jgit.errors.AmbiguousObjectException * {@code revstr} contains an abbreviated ObjectId and this * repository contains more than one object which match to the * input abbreviation. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the id parsed does not meet the type required to finish * applying the operators in the expression. - * @throws RevisionSyntaxException + * @throws org.eclipse.jgit.errors.RevisionSyntaxException * the expression is not supported by this implementation, or * does not meet the standard syntax. - * @throws IOException + * @throws java.io.IOException * on serious errors */ @Nullable @@ -468,11 +502,11 @@ public abstract class Repository implements AutoCloseable { * Thus this method can be used to process an expression to a method that * expects a branch or revision id. * - * @param revstr + * @param revstr a {@link java.lang.String} object. * @return object id or ref name from resolved expression or {@code null} if * given expression cannot be resolved - * @throws AmbiguousObjectException - * @throws IOException + * @throws org.eclipse.jgit.errors.AmbiguousObjectException + * @throws java.io.IOException */ @Nullable public String simplify(final String revstr) @@ -891,12 +925,18 @@ public abstract class Repository implements AutoCloseable { } } - /** Increment the use counter by one, requiring a matched {@link #close()}. */ + /** + * Increment the use counter by one, requiring a matched {@link #close()}. + */ public void incrementOpen() { useCnt.incrementAndGet(); } - /** Decrement the use count, and maybe close resources. */ + /** + * {@inheritDoc} + * <p> + * Decrement the use count, and maybe close resources. + */ @Override public void close() { int newCount = useCnt.decrementAndGet(); @@ -932,6 +972,7 @@ public abstract class Repository implements AutoCloseable { getRefDatabase().close(); } + /** {@inheritDoc} */ @Override @NonNull public String toString() { @@ -961,7 +1002,7 @@ public abstract class Repository implements AutoCloseable { * an ObjectId in hex format if the current branch is detached, or * {@code null} if the repository is corrupt and has no HEAD * reference. - * @throws IOException + * @throws java.io.IOException */ @Nullable public String getFullBranch() throws IOException { @@ -989,7 +1030,7 @@ public abstract class Repository implements AutoCloseable { * @return name of current branch (for example {@code master}), an ObjectId * in hex format if the current branch is detached, or {@code null} * if the repository is corrupt and has no HEAD reference. - * @throws IOException + * @throws java.io.IOException */ @Nullable public String getBranch() throws IOException { @@ -1022,7 +1063,7 @@ public abstract class Repository implements AutoCloseable { * "master" which is is automatically expanded to * "refs/heads/master" if "refs/heads/master" already exists. * @return the Ref with the given name, or {@code null} if it does not exist - * @throws IOException + * @throws java.io.IOException * @deprecated Use {@link #exactRef(String)} or {@link #findRef(String)} * instead. */ @@ -1040,7 +1081,7 @@ public abstract class Repository implements AutoCloseable { * form; e.g., "master" is not automatically expanded to * "refs/heads/master". * @return the Ref with the given name, or {@code null} if it does not exist - * @throws IOException + * @throws java.io.IOException * @since 4.2 */ @Nullable @@ -1056,7 +1097,7 @@ public abstract class Repository implements AutoCloseable { * "master" which is is automatically expanded to * "refs/heads/master" if "refs/heads/master" already exists. * @return the Ref with the given name, or {@code null} if it does not exist - * @throws IOException + * @throws java.io.IOException * @since 4.2 */ @Nullable @@ -1065,6 +1106,8 @@ public abstract class Repository implements AutoCloseable { } /** + * Get mutable map of all known refs + * * @return mutable map of all known refs (heads, tags, remotes). */ @NonNull @@ -1077,6 +1120,8 @@ public abstract class Repository implements AutoCloseable { } /** + * Get mutable map of all tags + * * @return mutable map of all tags; key is short tag name ("v1.0") and value * of the entry contains the ref with the full tag name * ("refs/tags/v1.0"). @@ -1094,7 +1139,8 @@ public abstract class Repository implements AutoCloseable { * Peel a possibly unpeeled reference to an annotated tag. * <p> * If the ref cannot be peeled (as it does not refer to an annotated tag) - * the peeled id stays null, but {@link Ref#isPeeled()} will be true. + * the peeled id stays null, but {@link org.eclipse.jgit.lib.Ref#isPeeled()} + * will be true. * * @param ref * The ref to peel @@ -1116,6 +1162,8 @@ public abstract class Repository implements AutoCloseable { } /** + * Get a map with all objects referenced by a peeled ref. + * * @return a map with all objects referenced by a peeled ref. */ @NonNull @@ -1143,9 +1191,11 @@ public abstract class Repository implements AutoCloseable { } /** + * Get the index file location or {@code null} if repository isn't local. + * * @return the index file location or {@code null} if repository isn't * local. - * @throws NoWorkTreeException + * @throws org.eclipse.jgit.errors.NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. */ @@ -1165,11 +1215,11 @@ public abstract class Repository implements AutoCloseable { * @param id * name of the commit object. * @return reference to the commit object. Never null. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the supplied commit does not exist. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the supplied id is not a commit or an annotated tag. - * @throws IOException + * @throws java.io.IOException * a pack file or loose object could not be read. * @since 4.8 */ @@ -1192,12 +1242,12 @@ public abstract class Repository implements AutoCloseable { * * @return a cache representing the contents of the specified index file (if * it exists) or an empty cache if the file does not exist. - * @throws NoWorkTreeException + * @throws org.eclipse.jgit.errors.NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. - * @throws IOException + * @throws java.io.IOException * the index file is present but could not be read. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the index file is using a format or extension that this * library does not support. */ @@ -1216,13 +1266,13 @@ public abstract class Repository implements AutoCloseable { * * @return a cache representing the contents of the specified index file (if * it exists) or an empty cache if the file does not exist. - * @throws NoWorkTreeException + * @throws org.eclipse.jgit.errors.NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. - * @throws IOException + * @throws java.io.IOException * the index file is present but could not be read, or the lock * could not be obtained. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the index file is using a format or extension that this * library does not support. */ @@ -1241,7 +1291,9 @@ public abstract class Repository implements AutoCloseable { } /** - * @return an important state + * Get the repository state + * + * @return the repository state */ @NonNull public RepositoryState getRepositoryState() { @@ -1322,8 +1374,7 @@ public abstract class Repository implements AutoCloseable { * * For portability reasons '\' is excluded * - * @param refName - * + * @param refName a {@link java.lang.String} object. * @return true if refName is a valid ref name */ public static boolean isValidRefName(final String refName) { @@ -1384,10 +1435,10 @@ public abstract class Repository implements AutoCloseable { * Normalizes the passed branch name into a possible valid branch name. The * validity of the returned name should be checked by a subsequent call to * {@link #isValidRefName(String)}. - * <p/> + * <p> * Future implementations of this method could be more restrictive or more * lenient about the validity of specific characters in the returned name. - * <p/> + * <p> * The current implementation returns the trimmed input string if this is * already a valid branch name. Otherwise it returns a trimmed string with * special characters not allowed by {@link #isValidRefName(String)} @@ -1396,7 +1447,6 @@ public abstract class Repository implements AutoCloseable { * * @param name * to normalize - * * @return The normalized name or an empty String if it is {@code null} or * empty. * @since 4.7 @@ -1503,6 +1553,8 @@ public abstract class Repository implements AutoCloseable { } /** + * Whether this repository is bare + * * @return true if this is bare, which implies it has no working directory. */ public boolean isBare() { @@ -1510,9 +1562,12 @@ public abstract class Repository implements AutoCloseable { } /** + * Get the root directory of the working tree, where files are checked out + * for viewing and editing. + * * @return the root directory of the working tree, where files are checked * out for viewing and editing. - * @throws NoWorkTreeException + * @throws org.eclipse.jgit.errors.NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. */ @@ -1526,7 +1581,7 @@ public abstract class Repository implements AutoCloseable { /** * Force a scan for changed refs. * - * @throws IOException + * @throws java.io.IOException */ public abstract void scanForRepoChanges() throws IOException; @@ -1536,8 +1591,10 @@ public abstract class Repository implements AutoCloseable { public abstract void notifyIndexChanged(); /** - * @param refName + * Get a shortened more user friendly ref name * + * @param refName + * a {@link java.lang.String} object. * @return a more user friendly ref name */ @NonNull @@ -1552,7 +1609,10 @@ public abstract class Repository implements AutoCloseable { } /** + * Get a shortened more user friendly remote tracking branch name + * * @param refName + * a {@link java.lang.String} object. * @return the remote branch name part of <code>refName</code>, i.e. without * the <code>refs/remotes/<remote></code> prefix, if * <code>refName</code> represents a remote tracking branch; @@ -1570,7 +1630,10 @@ public abstract class Repository implements AutoCloseable { } /** + * Get remote name + * * @param refName + * a {@link java.lang.String} object. * @return the remote name part of <code>refName</code>, i.e. without the * <code>refs/remotes/<remote></code> prefix, if * <code>refName</code> represents a remote tracking branch; @@ -1591,7 +1654,7 @@ public abstract class Repository implements AutoCloseable { * Read the {@code GIT_DIR/description} file for gitweb. * * @return description text; null if no description has been configured. - * @throws IOException + * @throws java.io.IOException * description cannot be accessed. * @since 4.6 */ @@ -1605,7 +1668,7 @@ public abstract class Repository implements AutoCloseable { * * @param description * new description; null to clear the description. - * @throws IOException + * @throws java.io.IOException * description cannot be persisted. * @since 4.6 */ @@ -1615,10 +1678,13 @@ public abstract class Repository implements AutoCloseable { } /** + * Get the reflog reader + * * @param refName - * @return a {@link ReflogReader} for the supplied refname, or {@code null} - * if the named ref does not exist. - * @throws IOException + * a {@link java.lang.String} object. + * @return a {@link org.eclipse.jgit.lib.ReflogReader} for the supplied + * refname, or {@code null} if the named ref does not exist. + * @throws java.io.IOException * the ref could not be accessed. * @since 3.0 */ @@ -1633,8 +1699,8 @@ public abstract class Repository implements AutoCloseable { * * @return a String containing the content of the MERGE_MSG file or * {@code null} if this file doesn't exist - * @throws IOException - * @throws NoWorkTreeException + * @throws java.io.IOException + * @throws org.eclipse.jgit.errors.NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. */ @@ -1652,8 +1718,7 @@ public abstract class Repository implements AutoCloseable { * @param msg * the message which should be written or <code>null</code> to * delete the file - * - * @throws IOException + * @throws java.io.IOException */ public void writeMergeCommitMsg(String msg) throws IOException { File mergeMsgFile = new File(gitDir, Constants.MERGE_MSG); @@ -1667,8 +1732,8 @@ public abstract class Repository implements AutoCloseable { * * @return a String containing the content of the COMMIT_EDITMSG file or * {@code null} if this file doesn't exist - * @throws IOException - * @throws NoWorkTreeException + * @throws java.io.IOException + * @throws org.eclipse.jgit.errors.NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. * @since 4.0 @@ -1686,8 +1751,7 @@ public abstract class Repository implements AutoCloseable { * @param msg * the message which should be written or {@code null} to delete * the file - * - * @throws IOException + * @throws java.io.IOException * @since 4.0 */ public void writeCommitEditMsg(String msg) throws IOException { @@ -1703,8 +1767,8 @@ public abstract class Repository implements AutoCloseable { * @return a list of commits which IDs are listed in the MERGE_HEAD file or * {@code null} if this file doesn't exist. Also if the file exists * but is empty {@code null} will be returned - * @throws IOException - * @throws NoWorkTreeException + * @throws java.io.IOException + * @throws org.eclipse.jgit.errors.NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. */ @@ -1735,7 +1799,7 @@ public abstract class Repository implements AutoCloseable { * @param heads * a list of commits which IDs should be written to * $GIT_DIR/MERGE_HEAD or <code>null</code> to delete the file - * @throws IOException + * @throws java.io.IOException */ public void writeMergeHeads(List<? extends ObjectId> heads) throws IOException { writeHeadsFile(heads, Constants.MERGE_HEAD); @@ -1747,8 +1811,8 @@ public abstract class Repository implements AutoCloseable { * @return object id from CHERRY_PICK_HEAD file or {@code null} if this file * doesn't exist. Also if the file exists but is empty {@code null} * will be returned - * @throws IOException - * @throws NoWorkTreeException + * @throws java.io.IOException + * @throws org.eclipse.jgit.errors.NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. */ @@ -1771,8 +1835,8 @@ public abstract class Repository implements AutoCloseable { * @return object id from REVERT_HEAD file or {@code null} if this file * doesn't exist. Also if the file exists but is empty {@code null} * will be returned - * @throws IOException - * @throws NoWorkTreeException + * @throws java.io.IOException + * @throws org.eclipse.jgit.errors.NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. */ @@ -1794,7 +1858,7 @@ public abstract class Repository implements AutoCloseable { * @param head * an object id of the cherry commit or <code>null</code> to * delete the file - * @throws IOException + * @throws java.io.IOException */ public void writeCherryPickHead(ObjectId head) throws IOException { List<ObjectId> heads = (head != null) ? Collections.singletonList(head) @@ -1809,7 +1873,7 @@ public abstract class Repository implements AutoCloseable { * @param head * an object id of the revert commit or <code>null</code> to * delete the file - * @throws IOException + * @throws java.io.IOException */ public void writeRevertHead(ObjectId head) throws IOException { List<ObjectId> heads = (head != null) ? Collections.singletonList(head) @@ -1823,7 +1887,7 @@ public abstract class Repository implements AutoCloseable { * @param head * an object id of the original HEAD commit or <code>null</code> * to delete the file - * @throws IOException + * @throws java.io.IOException */ public void writeOrigHead(ObjectId head) throws IOException { List<ObjectId> heads = head != null ? Collections.singletonList(head) @@ -1837,8 +1901,8 @@ public abstract class Repository implements AutoCloseable { * @return object id from ORIG_HEAD file or {@code null} if this file * doesn't exist. Also if the file exists but is empty {@code null} * will be returned - * @throws IOException - * @throws NoWorkTreeException + * @throws java.io.IOException + * @throws org.eclipse.jgit.errors.NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. */ @@ -1858,7 +1922,7 @@ public abstract class Repository implements AutoCloseable { * * @return a String containing the content of the SQUASH_MSG file or * {@code null} if this file doesn't exist - * @throws IOException + * @throws java.io.IOException * @throws NoWorkTreeException * if this is bare, which implies it has no working directory. * See {@link #isBare()}. @@ -1877,8 +1941,7 @@ public abstract class Repository implements AutoCloseable { * @param msg * the message which should be written or <code>null</code> to * delete the file - * - * @throws IOException + * @throws java.io.IOException */ public void writeSquashCommitMsg(String msg) throws IOException { File squashMsgFile = new File(gitDir, Constants.SQUASH_MSG); @@ -1974,7 +2037,7 @@ public abstract class Repository implements AutoCloseable { * @param includeComments * <code>true</code> if also comments should be reported * @return the list of steps - * @throws IOException + * @throws java.io.IOException * @since 3.2 */ @NonNull @@ -1994,7 +2057,7 @@ public abstract class Repository implements AutoCloseable { * the steps to be written * @param append * whether to append to an existing file or to write a new file - * @throws IOException + * @throws java.io.IOException * @since 3.2 */ public void writeRebaseTodoFile(String path, List<RebaseTodoLine> steps, @@ -2004,6 +2067,8 @@ public abstract class Repository implements AutoCloseable { } /** + * Get the names of all known remotes + * * @return the names of all known remotes * @since 3.4 */ @@ -2018,9 +2083,10 @@ public abstract class Repository implements AutoCloseable { * collection; if not, exit without performing any work. Some JGit commands * run autoGC after performing operations that could create many loose * objects. - * <p/> + * <p> * Currently this option is supported for repositories of type - * {@code FileRepository} only. See {@link GC#setAuto(boolean)} for + * {@code FileRepository} only. See + * {@link org.eclipse.jgit.internal.storage.file.GC#setAuto(boolean)} for * configuration details. * * @param monitor diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryBuilder.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryBuilder.java index 95be2d1f0d..65196a8083 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryBuilder.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryBuilder.java @@ -46,7 +46,7 @@ package org.eclipse.jgit.lib; import java.io.File; /** - * Base class to support constructing a {@link Repository}. + * Base class to support constructing a {@link org.eclipse.jgit.lib.Repository}. * <p> * Applications must set one of {@link #setGitDir(File)} or * {@link #setWorkTree(File)}, or use {@link #readEnvironment()} or diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryCache.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryCache.java index 53e9fe3c53..ce7ce8cd87 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryCache.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryCache.java @@ -62,26 +62,30 @@ import org.eclipse.jgit.util.RawParseUtils; import org.slf4j.Logger; import org.slf4j.LoggerFactory; -/** Cache of active {@link Repository} instances. */ +/** + * Cache of active {@link org.eclipse.jgit.lib.Repository} instances. + */ public class RepositoryCache { - private static final RepositoryCache cache = new RepositoryCache(); - private final static Logger LOG = LoggerFactory .getLogger(RepositoryCache.class); + private static final RepositoryCache cache = new RepositoryCache(); + /** * Open an existing repository, reusing a cached instance if possible. * <p> * When done with the repository, the caller must call - * {@link Repository#close()} to decrement the repository's usage counter. + * {@link org.eclipse.jgit.lib.Repository#close()} to decrement the + * repository's usage counter. * * @param location - * where the local repository is. Typically a {@link FileKey}. + * where the local repository is. Typically a + * {@link org.eclipse.jgit.lib.RepositoryCache.FileKey}. * @return the repository instance requested; caller must close when done. - * @throws IOException + * @throws java.io.IOException * the repository could not be read (likely its core.version * property is not supported). - * @throws RepositoryNotFoundException + * @throws org.eclipse.jgit.errors.RepositoryNotFoundException * there is no repository at the given location. */ public static Repository open(final Key location) throws IOException, @@ -93,16 +97,18 @@ public class RepositoryCache { * Open a repository, reusing a cached instance if possible. * <p> * When done with the repository, the caller must call - * {@link Repository#close()} to decrement the repository's usage counter. + * {@link org.eclipse.jgit.lib.Repository#close()} to decrement the + * repository's usage counter. * * @param location - * where the local repository is. Typically a {@link FileKey}. + * where the local repository is. Typically a + * {@link org.eclipse.jgit.lib.RepositoryCache.FileKey}. * @param mustExist * If true, and the repository is not found, throws {@code * RepositoryNotFoundException}. If false, a repository instance * is created and registered anyway. * @return the repository instance requested; caller must close when done. - * @throws IOException + * @throws java.io.IOException * the repository could not be read (likely its core.version * property is not supported). * @throws RepositoryNotFoundException @@ -118,9 +124,10 @@ public class RepositoryCache { * Register one repository into the cache. * <p> * During registration the cache automatically increments the usage counter, - * permitting it to retain the reference. A {@link FileKey} for the - * repository's {@link Repository#getDirectory()} is used to index the - * repository in the cache. + * permitting it to retain the reference. A + * {@link org.eclipse.jgit.lib.RepositoryCache.FileKey} for the repository's + * {@link org.eclipse.jgit.lib.Repository#getDirectory()} is used to index + * the repository in the cache. * <p> * If another repository already is registered in the cache at this * location, the other instance is closed. @@ -156,8 +163,8 @@ public class RepositoryCache { * <p> * Removes a repository from the cache, if it is still registered here. This * method will not close the repository, only remove it from the cache. See - * {@link RepositoryCache#close(Repository)} to remove and close the - * repository. + * {@link org.eclipse.jgit.lib.RepositoryCache#close(Repository)} to remove + * and close the repository. * * @param db * repository to unregister. @@ -174,8 +181,8 @@ public class RepositoryCache { * <p> * Removes a repository from the cache, if it is still registered here. This * method will not close the repository, only remove it from the cache. See - * {@link RepositoryCache#close(Repository)} to remove and close the - * repository. + * {@link org.eclipse.jgit.lib.RepositoryCache#close(Repository)} to remove + * and close the repository. * * @param location * location of the repository to remove. @@ -186,6 +193,8 @@ public class RepositoryCache { } /** + * Get the locations of all repositories registered in the cache. + * * @return the locations of all repositories registered in the cache. * @since 4.1 */ @@ -202,7 +211,9 @@ public class RepositoryCache { return cache.cacheMap.get(key) == repo; } - /** Unregister all repositories from the cache. */ + /** + * Unregister all repositories from the cache. + */ public static void clear() { cache.clearAll(); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryCacheConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryCacheConfig.java index 28cdaae443..3680dee4ef 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryCacheConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryCacheConfig.java @@ -68,23 +68,32 @@ public class RepositoryCacheConfig { private long cleanupDelayMillis; - /** Create a default configuration. */ + /** + * Create a default configuration. + */ public RepositoryCacheConfig() { expireAfterMillis = TimeUnit.HOURS.toMillis(1); cleanupDelayMillis = AUTO_CLEANUP_DELAY; } /** - * @return the time an unused repository should expired and be evicted from - * the RepositoryCache in milliseconds. <b>Default is 1 hour.</b> + * Get the time an unused repository should be expired and be evicted from + * the RepositoryCache in milliseconds. + * + * @return the time an unused repository should be expired and be evicted + * from the RepositoryCache in milliseconds. <b>Default is 1 + * hour.</b> */ public long getExpireAfter() { return expireAfterMillis; } /** + * Set the time an unused repository should be expired and be evicted from + * the RepositoryCache in milliseconds. + * * @param expireAfterMillis - * the time an unused repository should expired and be evicted + * the time an unused repository should be expired and be evicted * from the RepositoryCache in milliseconds. */ public void setExpireAfter(long expireAfterMillis) { @@ -92,6 +101,9 @@ public class RepositoryCacheConfig { } /** + * Get the delay between the periodic cleanup of expired repository in + * milliseconds. + * * @return the delay between the periodic cleanup of expired repository in * milliseconds. <b>Default is minimum of 1/10 of expireAfterMillis * and 10 minutes</b> @@ -105,6 +117,9 @@ public class RepositoryCacheConfig { } /** + * Set the delay between the periodic cleanup of expired repository in + * milliseconds. + * * @param cleanupDelayMillis * the delay between the periodic cleanup of expired repository * in milliseconds. Set it to {@link #AUTO_CLEANUP_DELAY} to diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryState.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryState.java index 9b7234b3af..c5d81b3d25 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryState.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryState.java @@ -381,7 +381,9 @@ public enum RepositoryState { }; /** - * @return true if changing HEAD is sane. + * Whether checkout can be done. + * + * @return whether checkout can be done. */ public abstract boolean canCheckout(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/StoredConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/StoredConfig.java index 344d520680..42ab891990 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/StoredConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/StoredConfig.java @@ -51,7 +51,9 @@ import org.eclipse.jgit.errors.ConfigInvalidException; * Persistent configuration that can be stored and loaded from a location. */ public abstract class StoredConfig extends Config { - /** Create a configuration with no default fallback. */ + /** + * Create a configuration with no default fallback. + */ public StoredConfig() { super(); } @@ -73,9 +75,9 @@ public abstract class StoredConfig extends Config { * If the configuration does not exist, this configuration is cleared, and * thus behaves the same as though the backing store exists, but is empty. * - * @throws IOException + * @throws java.io.IOException * the configuration could not be read (but does exist). - * @throws ConfigInvalidException + * @throws org.eclipse.jgit.errors.ConfigInvalidException * the configuration is not properly formatted. */ public abstract void load() throws IOException, ConfigInvalidException; @@ -83,11 +85,12 @@ public abstract class StoredConfig extends Config { /** * Save the configuration to the persistent store. * - * @throws IOException + * @throws java.io.IOException * the configuration could not be written. */ public abstract void save() throws IOException; + /** {@inheritDoc} */ @Override public void clear() { super.clear(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/SymbolicRef.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/SymbolicRef.java index 71d5cd7ac1..d4b83b0128 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/SymbolicRef.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/SymbolicRef.java @@ -47,7 +47,8 @@ import org.eclipse.jgit.annotations.NonNull; import org.eclipse.jgit.annotations.Nullable; /** - * A reference that indirectly points at another {@link Ref}. + * A reference that indirectly points at another + * {@link org.eclipse.jgit.lib.Ref}. * <p> * A symbolic reference always derives its current value from the target * reference. @@ -70,17 +71,20 @@ public class SymbolicRef implements Ref { this.target = target; } + /** {@inheritDoc} */ @Override @NonNull public String getName() { return name; } + /** {@inheritDoc} */ @Override public boolean isSymbolic() { return true; } + /** {@inheritDoc} */ @Override @NonNull public Ref getLeaf() { @@ -90,35 +94,41 @@ public class SymbolicRef implements Ref { return dst; } + /** {@inheritDoc} */ @Override @NonNull public Ref getTarget() { return target; } + /** {@inheritDoc} */ @Override @Nullable public ObjectId getObjectId() { return getLeaf().getObjectId(); } + /** {@inheritDoc} */ @Override @NonNull public Storage getStorage() { return Storage.LOOSE; } + /** {@inheritDoc} */ @Override @Nullable public ObjectId getPeeledObjectId() { return getLeaf().getPeeledObjectId(); } + /** {@inheritDoc} */ @Override public boolean isPeeled() { return getLeaf().isPeeled(); } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/TagBuilder.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/TagBuilder.java index 3490a5bc99..90ef5c779f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/TagBuilder.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/TagBuilder.java @@ -72,12 +72,20 @@ public class TagBuilder { private String message; - /** @return the type of object this tag refers to. */ + /** + * Get the type of object this tag refers to. + * + * @return the type of object this tag refers to. + */ public int getObjectType() { return type; } - /** @return the object this tag refers to. */ + /** + * Get the object this tag refers to. + * + * @return the object this tag refers to. + */ public ObjectId getObjectId() { return object; } @@ -105,7 +113,11 @@ public class TagBuilder { setObjectId(obj, obj.getType()); } - /** @return short name of the tag (no {@code refs/tags/} prefix). */ + /** + * Get short name of the tag (no {@code refs/tags/} prefix). + * + * @return short name of the tag (no {@code refs/tags/} prefix). + */ public String getTag() { return tag; } @@ -122,7 +134,11 @@ public class TagBuilder { this.tag = shortName; } - /** @return creator of this tag. May be null. */ + /** + * Get creator of this tag. + * + * @return creator of this tag. May be null. + */ public PersonIdent getTagger() { return tagger; } @@ -137,7 +153,11 @@ public class TagBuilder { tagger = taggerIdent; } - /** @return the complete commit message. */ + /** + * Get the complete commit message. + * + * @return the complete commit message. + */ public String getMessage() { return message; } @@ -203,6 +223,7 @@ public class TagBuilder { return build(); } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/TextProgressMonitor.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/TextProgressMonitor.java index c31c3c6939..936ce3dcc8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/TextProgressMonitor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/TextProgressMonitor.java @@ -51,13 +51,17 @@ import java.io.OutputStreamWriter; import java.io.PrintWriter; import java.io.Writer; -/** A simple progress reporter printing on a stream. */ +/** + * A simple progress reporter printing on a stream. + */ public class TextProgressMonitor extends BatchingProgressMonitor { private final Writer out; private boolean write; - /** Initialize a new progress monitor. */ + /** + * Initialize a new progress monitor. + */ public TextProgressMonitor() { this(new PrintWriter(new OutputStreamWriter(System.err, UTF_8))); } @@ -73,6 +77,7 @@ public class TextProgressMonitor extends BatchingProgressMonitor { this.write = true; } + /** {@inheritDoc} */ @Override protected void onUpdate(String taskName, int workCurr) { StringBuilder s = new StringBuilder(); @@ -80,6 +85,7 @@ public class TextProgressMonitor extends BatchingProgressMonitor { send(s); } + /** {@inheritDoc} */ @Override protected void onEndTask(String taskName, int workCurr) { StringBuilder s = new StringBuilder(); @@ -97,6 +103,7 @@ public class TextProgressMonitor extends BatchingProgressMonitor { s.append(workCurr); } + /** {@inheritDoc} */ @Override protected void onUpdate(String taskName, int cmp, int totalWork, int pcnt) { StringBuilder s = new StringBuilder(); @@ -104,6 +111,7 @@ public class TextProgressMonitor extends BatchingProgressMonitor { send(s); } + /** {@inheritDoc} */ @Override protected void onEndTask(String taskName, int cmp, int totalWork, int pcnt) { StringBuilder s = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ThreadSafeProgressMonitor.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ThreadSafeProgressMonitor.java index 5824a55ff1..7e7d45dbf3 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ThreadSafeProgressMonitor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ThreadSafeProgressMonitor.java @@ -48,7 +48,8 @@ import java.util.concurrent.atomic.AtomicInteger; import java.util.concurrent.locks.ReentrantLock; /** - * Wrapper around the general {@link ProgressMonitor} to make it thread safe. + * Wrapper around the general {@link org.eclipse.jgit.lib.ProgressMonitor} to + * make it thread safe. * * Updates to the underlying ProgressMonitor are made only from the thread that * allocated this wrapper. Callers are responsible for ensuring the allocating @@ -87,6 +88,7 @@ public class ThreadSafeProgressMonitor implements ProgressMonitor { this.process = new Semaphore(0); } + /** {@inheritDoc} */ @Override public void start(int totalTasks) { if (!isMainThread()) @@ -94,6 +96,7 @@ public class ThreadSafeProgressMonitor implements ProgressMonitor { pm.start(totalTasks); } + /** {@inheritDoc} */ @Override public void beginTask(String title, int totalWork) { if (!isMainThread()) @@ -101,7 +104,9 @@ public class ThreadSafeProgressMonitor implements ProgressMonitor { pm.beginTask(title, totalWork); } - /** Notify the monitor a worker is starting. */ + /** + * Notify the monitor a worker is starting. + */ public void startWorker() { startWorkers(1); } @@ -116,7 +121,9 @@ public class ThreadSafeProgressMonitor implements ProgressMonitor { workers.addAndGet(count); } - /** Notify the monitor a worker is finished. */ + /** + * Notify the monitor a worker is finished. + */ public void endWorker() { if (workers.decrementAndGet() == 0) process.release(); @@ -139,7 +146,7 @@ public class ThreadSafeProgressMonitor implements ProgressMonitor { * This method can only be invoked by the same thread that allocated this * ThreadSafeProgressMonior. * - * @throws InterruptedException + * @throws java.lang.InterruptedException * if the main thread is interrupted while waiting for * completion of workers. */ @@ -158,12 +165,14 @@ public class ThreadSafeProgressMonitor implements ProgressMonitor { pm.update(cnt); } + /** {@inheritDoc} */ @Override public void update(int completed) { if (0 == pendingUpdates.getAndAdd(completed)) process.release(); } + /** {@inheritDoc} */ @Override public boolean isCancelled() { lock.lock(); @@ -174,6 +183,7 @@ public class ThreadSafeProgressMonitor implements ProgressMonitor { } } + /** {@inheritDoc} */ @Override public void endTask() { if (!isMainThread()) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/TreeFormatter.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/TreeFormatter.java index 777ce94aa0..0d78d5900c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/TreeFormatter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/TreeFormatter.java @@ -94,7 +94,9 @@ public class TreeFormatter { private TemporaryBuffer.Heap overflowBuffer; - /** Create an empty formatter with a default buffer size. */ + /** + * Create an empty formatter with a default buffer size. + */ public TreeFormatter() { this(8192); } @@ -112,7 +114,7 @@ public class TreeFormatter { } /** - * Add a link to a submodule commit, mode is {@link FileMode#GITLINK}. + * Add a link to a submodule commit, mode is {@link org.eclipse.jgit.lib.FileMode#GITLINK}. * * @param name * name of the entry. @@ -124,7 +126,7 @@ public class TreeFormatter { } /** - * Add a subtree, mode is {@link FileMode#TREE}. + * Add a subtree, mode is {@link org.eclipse.jgit.lib.FileMode#TREE}. * * @param name * name of the entry. @@ -136,7 +138,7 @@ public class TreeFormatter { } /** - * Add a regular file, mode is {@link FileMode#REGULAR_FILE}. + * Add a regular file, mode is {@link org.eclipse.jgit.lib.FileMode#REGULAR_FILE}. * * @param name * name of the entry. @@ -307,7 +309,7 @@ public class TreeFormatter { * @param ins * the inserter to store the tree. * @return computed ObjectId of the tree - * @throws IOException + * @throws java.io.IOException * the tree could not be stored. */ public ObjectId insertTo(ObjectInserter ins) throws IOException { @@ -321,7 +323,7 @@ public class TreeFormatter { /** * Compute the ObjectId for this tree * - * @param ins + * @param ins a {@link org.eclipse.jgit.lib.ObjectInserter} object. * @return ObjectId for this tree */ public ObjectId computeId(ObjectInserter ins) { @@ -343,7 +345,8 @@ public class TreeFormatter { * This method is not efficient, as it needs to create a copy of the * internal buffer in order to supply an array of the correct size to the * caller. If the buffer is just to pass to an ObjectInserter, consider - * using {@link ObjectInserter#insert(TreeFormatter)} instead. + * using {@link org.eclipse.jgit.lib.ObjectInserter#insert(TreeFormatter)} + * instead. * * @return a copy of this formatter's buffer. */ @@ -362,6 +365,7 @@ public class TreeFormatter { } } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/TypedConfigGetter.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/TypedConfigGetter.java index 594edef665..aca2ad2eb8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/TypedConfigGetter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/TypedConfigGetter.java @@ -50,15 +50,15 @@ import org.eclipse.jgit.annotations.NonNull; import org.eclipse.jgit.transport.RefSpec; /** - * Something that knows how to convert plain strings from a git {@link Config} - * to typed values. + * Something that knows how to convert plain strings from a git + * {@link org.eclipse.jgit.lib.Config} to typed values. * * @since 4.9 */ public interface TypedConfigGetter { /** - * Get a boolean value from a git {@link Config}. + * Get a boolean value from a git {@link org.eclipse.jgit.lib.Config}. * * @param config * to get the value from @@ -77,10 +77,8 @@ public interface TypedConfigGetter { String name, boolean defaultValue); /** - * Parse an enumeration from a git {@link Config}. + * Parse an enumeration from a git {@link org.eclipse.jgit.lib.Config}. * - * @param <T> - * type of the enumeration object. * @param config * to get the value from * @param all @@ -100,7 +98,7 @@ public interface TypedConfigGetter { String subsection, String name, T defaultValue); /** - * Obtain an integer value from a git {@link Config}. + * Obtain an integer value from a git {@link org.eclipse.jgit.lib.Config}. * * @param config * to get the value from @@ -118,7 +116,7 @@ public interface TypedConfigGetter { int defaultValue); /** - * Obtain a long value from a git {@link Config}. + * Obtain a long value from a git {@link org.eclipse.jgit.lib.Config}. * * @param config * to get the value from @@ -137,7 +135,7 @@ public interface TypedConfigGetter { /** * Parse a numerical time unit, such as "1 minute", from a git - * {@link Config}. + * {@link org.eclipse.jgit.lib.Config}. * * @param config * to get the value from @@ -161,7 +159,8 @@ public interface TypedConfigGetter { /** - * Parse a list of {@link RefSpec}s from a git {@link Config}. + * Parse a list of {@link org.eclipse.jgit.transport.RefSpec}s from a git + * {@link org.eclipse.jgit.lib.Config}. * * @param config * to get the list from @@ -171,7 +170,8 @@ public interface TypedConfigGetter { * subsection the key is in, or null if not in a subsection. * @param name * the key name. - * @return a possibly empty list of {@link RefSpec}s + * @return a possibly empty list of + * {@link org.eclipse.jgit.transport.RefSpec}s */ @NonNull List<RefSpec> getRefSpecs(Config config, String section, String subsection, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/UserConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/UserConfig.java index 102a4518f6..1a3c6f6bd5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/UserConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/UserConfig.java @@ -48,7 +48,9 @@ package org.eclipse.jgit.lib; import org.eclipse.jgit.lib.Config.SectionParser; import org.eclipse.jgit.util.SystemReader; -/** The standard "user" configuration parameters. */ +/** + * The standard "user" configuration parameters. + */ public class UserConfig { /** Key for {@link Config#get(SectionParser)}. */ public static final Config.SectionParser<UserConfig> KEY = UserConfig::new; @@ -94,6 +96,8 @@ public class UserConfig { } /** + * Get the author name as defined in the git variables and configurations. + * * @return the author name as defined in the git variables and * configurations. If no name could be found, try to use the system * user name instead. @@ -103,6 +107,9 @@ public class UserConfig { } /** + * Get the committer name as defined in the git variables and + * configurations. + * * @return the committer name as defined in the git variables and * configurations. If no name could be found, try to use the system * user name instead. @@ -112,26 +119,31 @@ public class UserConfig { } /** - * @return the author email as defined in git variables and - * configurations. If no email could be found, try to - * propose one default with the user name and the - * host name. + * Get the author email as defined in git variables and configurations. + * + * @return the author email as defined in git variables and configurations. + * If no email could be found, try to propose one default with the + * user name and the host name. */ public String getAuthorEmail() { return authorEmail; } /** + * Get the committer email as defined in git variables and configurations. + * * @return the committer email as defined in git variables and - * configurations. If no email could be found, try to - * propose one default with the user name and the - * host name. + * configurations. If no email could be found, try to propose one + * default with the user name and the host name. */ public String getCommitterEmail() { return committerEmail; } /** + * Whether the author name was not explicitly configured but constructed + * from information the system has about the logged on user + * * @return true if the author name was not explicitly configured but * constructed from information the system has about the logged on * user @@ -141,6 +153,9 @@ public class UserConfig { } /** + * Whether the author email was not explicitly configured but constructed + * from information the system has about the logged on user + * * @return true if the author email was not explicitly configured but * constructed from information the system has about the logged on * user @@ -150,6 +165,9 @@ public class UserConfig { } /** + * Whether the committer name was not explicitly configured but constructed + * from information the system has about the logged on user + * * @return true if the committer name was not explicitly configured but * constructed from information the system has about the logged on * user @@ -159,6 +177,9 @@ public class UserConfig { } /** + * Whether the author email was not explicitly configured but constructed + * from information the system has about the logged on user + * * @return true if the author email was not explicitly configured but * constructed from information the system has about the logged on * user diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/internal/WorkQueue.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/internal/WorkQueue.java index 3303f47722..8f8aad52d7 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/internal/WorkQueue.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/internal/WorkQueue.java @@ -71,6 +71,7 @@ public class WorkQueue { public Thread newThread(Runnable taskBody) { Thread thr = baseFactory.newThread(taskBody); thr.setName("JGit-WorkQueue"); //$NON-NLS-1$ + thr.setContextClassLoader(null); thr.setDaemon(true); return thr; } @@ -95,6 +96,8 @@ public class WorkQueue { } /** + * Get the WorkQueue's executor + * * @return the WorkQueue's executor */ public static ScheduledThreadPoolExecutor getExecutor() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/merge/EolAwareOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/merge/EolAwareOutputStream.java index 1ddac18e56..e44970abff 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/merge/EolAwareOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/merge/EolAwareOutputStream.java @@ -79,12 +79,14 @@ class EolAwareOutputStream extends OutputStream { return bol; } + /** {@inheritDoc} */ @Override public void write(int val) throws IOException { out.write(val); bol = (val == '\n'); } + /** {@inheritDoc} */ @Override public void write(byte[] buf, int pos, int cnt) throws IOException { if (cnt > 0) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeAlgorithm.java b/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeAlgorithm.java index 04c65effb8..dd42e43841 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeAlgorithm.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeAlgorithm.java @@ -57,14 +57,15 @@ import org.eclipse.jgit.merge.MergeChunk.ConflictState; /** * Provides the merge algorithm which does a three-way merge on content provided - * as RawText. By default {@link HistogramDiff} is used as diff algorithm. + * as RawText. By default {@link org.eclipse.jgit.diff.HistogramDiff} is used as + * diff algorithm. */ public final class MergeAlgorithm { private final DiffAlgorithm diffAlg; /** - * Creates a new MergeAlgorithm which uses {@link HistogramDiff} as diff - * algorithm + * Creates a new MergeAlgorithm which uses + * {@link org.eclipse.jgit.diff.HistogramDiff} as diff algorithm */ public MergeAlgorithm() { this(new HistogramDiff()); @@ -88,8 +89,6 @@ public final class MergeAlgorithm { /** * Does the three way merge between a common base and two sequences. * - * @param <S> - * type of sequence. * @param cmp comparison method for this execution. * @param base the common base sequence * @param ours the first sequence to be merged diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeChunk.java b/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeChunk.java index 72857ffb30..3867eea443 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeChunk.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeChunk.java @@ -97,7 +97,8 @@ public class MergeChunk { * merge result. All elements between begin (including begin) and * this element are added. * @param conflictState - * the state of this chunk. See {@link ConflictState} + * the state of this chunk. See + * {@link org.eclipse.jgit.merge.MergeChunk.ConflictState} */ protected MergeChunk(int sequenceIndex, int begin, int end, ConflictState conflictState) { @@ -108,7 +109,9 @@ public class MergeChunk { } /** - * @return the index of the sequence to which sequence this chunks belongs + * Get the index of the sequence to which this sequence chunks belongs to. + * + * @return the index of the sequence to which this sequence chunks belongs * to. Same as in {@link org.eclipse.jgit.merge.MergeResult#add} */ public int getSequenceIndex() { @@ -116,6 +119,9 @@ public class MergeChunk { } /** + * Get the first element from the specified sequence which should be + * included in the merge result. + * * @return the first element from the specified sequence which should be * included in the merge result. Indexes start with 0. */ @@ -124,17 +130,22 @@ public class MergeChunk { } /** - * @return the end of the range of this chunk. The element this index - * points to is the first element which not added to the merge - * result. All elements between begin (including begin) and this - * element are added. + * Get the end of the range of this chunk. + * + * @return the end of the range of this chunk. The element this index points + * to is the first element which not added to the merge result. All + * elements between begin (including begin) and this element are + * added. */ public int getEnd() { return end; } /** - * @return the state of this chunk. See {@link ConflictState} + * Get the state of this chunk. + * + * @return the state of this chunk. See + * {@link org.eclipse.jgit.merge.MergeChunk.ConflictState} */ public ConflictState getConflictState() { return conflictState; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeConfig.java index d059391826..cdbe3cd26c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeConfig.java @@ -58,7 +58,10 @@ import org.eclipse.jgit.lib.Repository; public class MergeConfig { /** + * Get merge configuration for the current branch of the repository + * * @param repo + * a {@link org.eclipse.jgit.lib.Repository} object. * @return merge configuration for the current branch of the repository */ public static MergeConfig getConfigForCurrentBranch(Repository repo) { @@ -74,10 +77,14 @@ public class MergeConfig { } /** + * Get a parser for use with + * {@link org.eclipse.jgit.lib.Config#get(SectionParser)} + * * @param branch * short branch name to get the configuration for, as returned - * e.g. by {@link Repository#getBranch()} - * @return a parser for use with {@link Config#get(SectionParser)} + * e.g. by {@link org.eclipse.jgit.lib.Repository#getBranch()} + * @return a parser for use with + * {@link org.eclipse.jgit.lib.Config#get(SectionParser)} */ public static final SectionParser<MergeConfig> getParser( final String branch) { @@ -104,6 +111,8 @@ public class MergeConfig { } /** + * Get the fast forward mode configured for this branch + * * @return the fast forward mode configured for this branch */ public FastForwardMode getFastForwardMode() { @@ -111,6 +120,9 @@ public class MergeConfig { } /** + * Whether merges into this branch are configured to be squash merges, false + * otherwise + * * @return true if merges into this branch are configured to be squash * merges, false otherwise */ @@ -119,8 +131,10 @@ public class MergeConfig { } /** - * @return false if --no-commit is configured for this branch, true - * otherwise (event if --squash is configured) + * Whether {@code --no-commit} option is not set. + * + * @return {@code false} if --no-commit is configured for this branch, + * {@code true} otherwise (even if --squash is configured) */ public boolean isCommit() { return commit; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeFormatter.java b/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeFormatter.java index 43876a6227..036917e62a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeFormatter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeFormatter.java @@ -55,11 +55,12 @@ import org.eclipse.jgit.diff.RawText; */ public class MergeFormatter { /** - * Formats the results of a merge of {@link RawText} objects in a Git - * conformant way. This method also assumes that the {@link RawText} objects - * being merged are line oriented files which use LF as delimiter. This - * method will also use LF to separate chunks and conflict metadata, - * therefore it fits only to texts that are LF-separated lines. + * Formats the results of a merge of {@link org.eclipse.jgit.diff.RawText} + * objects in a Git conformant way. This method also assumes that the + * {@link org.eclipse.jgit.diff.RawText} objects being merged are line + * oriented files which use LF as delimiter. This method will also use LF to + * separate chunks and conflict metadata, therefore it fits only to texts + * that are LF-separated lines. * * @param out * the outputstream where to write the textual presentation @@ -67,13 +68,13 @@ public class MergeFormatter { * the merge result which should be presented * @param seqName * When a conflict is reported each conflicting range will get a - * name. This name is following the "<<<<<<< " or ">>>>>>> " - * conflict markers. The names for the sequences are given in - * this list + * name. This name is following the "<<<<<<< + * " or ">>>>>>> " conflict markers. The + * names for the sequences are given in this list * @param charsetName * the name of the characterSet used when writing conflict * metadata - * @throws IOException + * @throws java.io.IOException */ public void formatMerge(OutputStream out, MergeResult<RawText> res, List<String> seqName, String charsetName) throws IOException { @@ -81,13 +82,14 @@ public class MergeFormatter { } /** - * Formats the results of a merge of exactly two {@link RawText} objects in - * a Git conformant way. This convenience method accepts the names for the - * three sequences (base and the two merged sequences) as explicit - * parameters and doesn't require the caller to specify a List + * Formats the results of a merge of exactly two + * {@link org.eclipse.jgit.diff.RawText} objects in a Git conformant way. + * This convenience method accepts the names for the three sequences (base + * and the two merged sequences) as explicit parameters and doesn't require + * the caller to specify a List * * @param out - * the {@link OutputStream} where to write the textual + * the {@link java.io.OutputStream} where to write the textual * presentation * @param res * the merge result which should be presented @@ -100,7 +102,7 @@ public class MergeFormatter { * @param charsetName * the name of the characterSet used when writing conflict * metadata - * @throws IOException + * @throws java.io.IOException */ @SuppressWarnings("unchecked") public void formatMerge(OutputStream out, MergeResult res, String baseName, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeResult.java b/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeResult.java index ff3c8ab172..062d86f8a2 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeResult.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeResult.java @@ -51,14 +51,14 @@ import org.eclipse.jgit.merge.MergeChunk.ConflictState; import org.eclipse.jgit.util.IntList; /** - * The result of merging a number of {@link Sequence} objects. These sequences - * have one common predecessor sequence. The result of a merge is a list of - * MergeChunks. Each MergeChunk contains either a range (a subsequence) from - * one of the merged sequences, a range from the common predecessor or a - * conflicting range from one of the merged sequences. A conflict will be - * reported as multiple chunks, one for each conflicting range. The first chunk - * for a conflict is marked specially to distinguish the border between two - * consecutive conflicts. + * The result of merging a number of {@link org.eclipse.jgit.diff.Sequence} + * objects. These sequences have one common predecessor sequence. The result of + * a merge is a list of MergeChunks. Each MergeChunk contains either a range (a + * subsequence) from one of the merged sequences, a range from the common + * predecessor or a conflicting range from one of the merged sequences. A + * conflict will be reported as multiple chunks, one for each conflicting range. + * The first chunk for a conflict is marked specially to distinguish the border + * between two consecutive conflicts. * <p> * This class does not know anything about how to present the merge result to * the end-user. MergeFormatters have to be used to construct something human @@ -80,7 +80,8 @@ public class MergeResult<S extends Sequence> implements Iterable<MergeChunk> { * @param sequences * contains the common predecessor sequence at position 0 * followed by the merged sequences. This list should not be - * modified anymore during the lifetime of this {@link MergeResult}. + * modified anymore during the lifetime of this + * {@link org.eclipse.jgit.merge.MergeResult}. */ public MergeResult(List<S> sequences) { this.sequences = sequences; @@ -129,10 +130,7 @@ public class MergeResult<S extends Sequence> implements Iterable<MergeChunk> { static final ConflictState[] states = ConflictState.values(); - /** - * @return an iterator over the MergeChunks. The iterator does not support - * the remove operation - */ + /** {@inheritDoc} */ @Override public Iterator<MergeChunk> iterator() { return new Iterator<MergeChunk>() { @@ -160,6 +158,8 @@ public class MergeResult<S extends Sequence> implements Iterable<MergeChunk> { } /** + * Whether this merge result contains conflicts + * * @return true if this merge result contains conflicts */ public boolean containsConflicts() { @@ -173,6 +173,8 @@ public class MergeResult<S extends Sequence> implements Iterable<MergeChunk> { * markers!) as new conflict-free content * * @param containsConflicts + * whether this merge should be seen as containing a conflict or + * not. * @since 3.5 */ protected void setContainsConflicts(boolean containsConflicts) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeStrategy.java b/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeStrategy.java index af3d5ca078..520ea6e74a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeStrategy.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/merge/MergeStrategy.java @@ -97,7 +97,7 @@ public abstract class MergeStrategy { * * @param imp * the strategy to register. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * a strategy by the same name has already been registered. */ public static void register(final MergeStrategy imp) { @@ -111,7 +111,7 @@ public abstract class MergeStrategy { * name the strategy can be looked up under. * @param imp * the strategy to register. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * a strategy by the same name has already been registered. */ public static synchronized void register(final String name, @@ -146,7 +146,11 @@ public abstract class MergeStrategy { return r; } - /** @return default name of this strategy implementation. */ + /** + * Get default name of this strategy implementation. + * + * @return default name of this strategy implementation. + */ public abstract String getName(); /** diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/merge/Merger.java b/org.eclipse.jgit/src/org/eclipse/jgit/merge/Merger.java index 0c4488c984..cd19d696a8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/merge/Merger.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/merge/Merger.java @@ -68,7 +68,8 @@ import org.eclipse.jgit.treewalk.AbstractTreeIterator; import org.eclipse.jgit.treewalk.CanonicalTreeParser; /** - * Instance of a specific {@link MergeStrategy} for a single {@link Repository}. + * Instance of a specific {@link org.eclipse.jgit.merge.MergeStrategy} for a + * single {@link org.eclipse.jgit.lib.Repository}. */ public abstract class Merger { /** @@ -138,6 +139,8 @@ public abstract class Merger { } /** + * Get the repository this merger operates on. + * * @return the repository this merger operates on. */ @Nullable @@ -146,8 +149,10 @@ public abstract class Merger { } /** + * Get non-null repository instance + * * @return non-null repository instance - * @throws NullPointerException + * @throws java.lang.NullPointerException * if the merger was constructed without a repository. * @since 4.8 */ @@ -159,8 +164,11 @@ public abstract class Merger { } /** - * @return an object writer to create objects, writing objects to {@link - * #getRepository()} (if a repository was provided). + * Get an object writer to create objects, writing objects to + * {@link #getRepository()} + * + * @return an object writer to create objects, writing objects to + * {@link #getRepository()} (if a repository was provided). */ public ObjectInserter getObjectInserter() { return inserter; @@ -203,7 +211,7 @@ public abstract class Merger { * @throws IncorrectObjectTypeException * one of the input objects is not a commit, but the strategy * requires it to be a commit. - * @throws IOException + * @throws java.io.IOException * one or more sources could not be read, or outputs could not * be written to the Repository. */ @@ -231,7 +239,7 @@ public abstract class Merger { * @throws IncorrectObjectTypeException * one of the input objects is not a commit, but the strategy * requires it to be a commit. - * @throws IOException + * @throws java.io.IOException * one or more sources could not be read, or outputs could not * be written to the Repository. */ @@ -267,6 +275,8 @@ public abstract class Merger { } /** + * Get the ID of the commit that was used as merge base for merging + * * @return the ID of the commit that was used as merge base for merging, or * null if no merge base was used or it was set manually * @since 3.2 @@ -281,9 +291,9 @@ public abstract class Merger { * @param b * the second commit in {@link #sourceObjects}. * @return the merge base of two commits - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * one of the input objects is not a commit. - * @throws IOException + * @throws java.io.IOException * objects are missing or multiple merge bases were found. * @since 3.0 */ @@ -313,9 +323,9 @@ public abstract class Merger { * @param treeId * the tree to scan; must be a tree (not a treeish). * @return an iterator for the tree. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the input object is not a tree. - * @throws IOException + * @throws java.io.IOException * the tree object is not found or cannot be read. */ protected AbstractTreeIterator openTree(final AnyObjectId treeId) @@ -336,13 +346,15 @@ public abstract class Merger { * @throws IncorrectObjectTypeException * one of the input objects is not a commit, but the strategy * requires it to be a commit. - * @throws IOException + * @throws java.io.IOException * one or more sources could not be read, or outputs could not * be written to the Repository. */ protected abstract boolean mergeImpl() throws IOException; /** + * Get resulting tree. + * * @return resulting tree, if {@link #merge(AnyObjectId[])} returned true. */ public abstract ObjectId getResultTreeId(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/merge/RecursiveMerger.java b/org.eclipse.jgit/src/org/eclipse/jgit/merge/RecursiveMerger.java index 1375cd3ea2..a621a0500a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/merge/RecursiveMerger.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/merge/RecursiveMerger.java @@ -83,6 +83,7 @@ import org.eclipse.jgit.treewalk.WorkingTreeIterator; * - uses "Lists" instead of Arrays for chained types * * - recursively merges the merge bases together to compute a usable base + * * @since 3.0 */ public class RecursiveMerger extends ResolveMerger { @@ -97,7 +98,9 @@ public class RecursiveMerger extends ResolveMerger { * inCore * * @param local + * a {@link org.eclipse.jgit.lib.Repository} object. * @param inCore + * a boolean. */ protected RecursiveMerger(Repository local, boolean inCore) { super(local, inCore); @@ -106,7 +109,7 @@ public class RecursiveMerger extends ResolveMerger { /** * Normal recursive merge, implies not inCore * - * @param local + * @param local a {@link org.eclipse.jgit.lib.Repository} object. */ protected RecursiveMerger(Repository local) { this(local, false); @@ -116,7 +119,9 @@ public class RecursiveMerger extends ResolveMerger { * Normal recursive merge, implies inCore. * * @param inserter + * an {@link org.eclipse.jgit.lib.ObjectInserter} object. * @param config + * the repository configuration * @since 4.8 */ protected RecursiveMerger(ObjectInserter inserter, Config config) { @@ -124,12 +129,11 @@ public class RecursiveMerger extends ResolveMerger { } /** + * {@inheritDoc} + * <p> * Get a single base commit for two given commits. If the two source commits * have more than one base commit recursively merge the base commits * together until you end up with a single base commit. - * - * @throws IOException - * @throws IncorrectObjectTypeException */ @Override protected RevCommit getBaseCommit(RevCommit a, RevCommit b) @@ -151,7 +155,7 @@ public class RecursiveMerger extends ResolveMerger { * @return the merge base of two commits. If a criss-cross merge required a * synthetic merge base this commit is visible only the merger's * RevWalk and will not be in the repository. - * @throws IOException + * @throws java.io.IOException * @throws IncorrectObjectTypeException * one of the input objects is not a commit. * @throws NoMergeBaseException diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/merge/ResolveMerger.java b/org.eclipse.jgit/src/org/eclipse/jgit/merge/ResolveMerger.java index 246121bf3a..6d43f09c98 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/merge/ResolveMerger.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/merge/ResolveMerger.java @@ -79,6 +79,7 @@ import org.eclipse.jgit.dircache.DirCacheBuildIterator; import org.eclipse.jgit.dircache.DirCacheBuilder; import org.eclipse.jgit.dircache.DirCacheCheckout; import org.eclipse.jgit.dircache.DirCacheEntry; +import org.eclipse.jgit.errors.BinaryBlobException; import org.eclipse.jgit.errors.CorruptObjectException; import org.eclipse.jgit.errors.IncorrectObjectTypeException; import org.eclipse.jgit.errors.IndexWriteException; @@ -89,9 +90,11 @@ import org.eclipse.jgit.lib.ConfigConstants; import org.eclipse.jgit.lib.FileMode; import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.lib.ObjectInserter; +import org.eclipse.jgit.lib.ObjectLoader; import org.eclipse.jgit.lib.ObjectReader; import org.eclipse.jgit.lib.Repository; import org.eclipse.jgit.revwalk.RevTree; +import org.eclipse.jgit.storage.pack.PackConfig; import org.eclipse.jgit.treewalk.AbstractTreeIterator; import org.eclipse.jgit.treewalk.CanonicalTreeParser; import org.eclipse.jgit.treewalk.NameConflictTreeWalk; @@ -296,8 +299,12 @@ public class ResolveMerger extends ThreeWayMerger { } /** + * Constructor for ResolveMerger. + * * @param local + * the {@link org.eclipse.jgit.lib.Repository}. * @param inCore + * a boolean. */ protected ResolveMerger(Repository local, boolean inCore) { super(local); @@ -316,15 +323,22 @@ public class ResolveMerger extends ThreeWayMerger { } /** + * Constructor for ResolveMerger. + * * @param local + * the {@link org.eclipse.jgit.lib.Repository}. */ protected ResolveMerger(Repository local) { this(local, false); } /** + * Constructor for ResolveMerger. + * * @param inserter + * an {@link org.eclipse.jgit.lib.ObjectInserter} object. * @param config + * the repository configuration * @since 4.8 */ protected ResolveMerger(ObjectInserter inserter, Config config) { @@ -336,6 +350,7 @@ public class ResolveMerger extends ThreeWayMerger { dircache = DirCache.newInCore(); } + /** {@inheritDoc} */ @Override protected boolean mergeImpl() throws IOException { if (implicitDirCache) @@ -376,9 +391,9 @@ public class ResolveMerger extends ThreeWayMerger { * contained only stage 0. In case if inCore operation just clear the * history of modified files. * - * @throws IOException - * @throws CorruptObjectException - * @throws NoWorkTreeException + * @throws java.io.IOException + * @throws org.eclipse.jgit.errors.CorruptObjectException + * @throws org.eclipse.jgit.errors.NoWorkTreeException * @since 3.4 */ protected void cleanUp() throws NoWorkTreeException, @@ -479,16 +494,15 @@ public class ResolveMerger extends ThreeWayMerger { * the file in the working tree * @param ignoreConflicts * see - * {@link ResolveMerger#mergeTrees(AbstractTreeIterator, RevTree, RevTree, boolean)} + * {@link org.eclipse.jgit.merge.ResolveMerger#mergeTrees(AbstractTreeIterator, RevTree, RevTree, boolean)} * @return <code>false</code> if the merge will fail because the index entry * didn't match ours or the working-dir file was dirty and a * conflict occurred - * @throws MissingObjectException - * @throws IncorrectObjectTypeException - * @throws CorruptObjectException - * @throws IOException + * @throws org.eclipse.jgit.errors.MissingObjectException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.CorruptObjectException + * @throws java.io.IOException * @since 3.5 - * @deprecated */ @Deprecated protected boolean processEntry(CanonicalTreeParser base, @@ -535,16 +549,16 @@ public class ResolveMerger extends ThreeWayMerger { * the file in the working tree * @param ignoreConflicts * see - * {@link ResolveMerger#mergeTrees(AbstractTreeIterator, RevTree, RevTree, boolean)} + * {@link org.eclipse.jgit.merge.ResolveMerger#mergeTrees(AbstractTreeIterator, RevTree, RevTree, boolean)} * @param attributes * the attributes defined for this entry * @return <code>false</code> if the merge will fail because the index entry * didn't match ours or the working-dir file was dirty and a * conflict occurred - * @throws MissingObjectException - * @throws IncorrectObjectTypeException - * @throws CorruptObjectException - * @throws IOException + * @throws org.eclipse.jgit.errors.MissingObjectException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.CorruptObjectException + * @throws java.io.IOException * @since 4.9 */ protected boolean processEntry(CanonicalTreeParser base, @@ -723,6 +737,7 @@ public class ResolveMerger extends ThreeWayMerger { // OURS or THEIRS has been deleted if (((modeO != 0 && !tw.idEqual(T_BASE, T_OURS)) || (modeT != 0 && !tw .idEqual(T_BASE, T_THEIRS)))) { + MergeResult<RawText> result = contentMerge(base, ours, theirs); add(tw.getRawPath(), base, DirCacheEntry.STAGE_1, 0, 0); add(tw.getRawPath(), ours, DirCacheEntry.STAGE_2, 0, 0); @@ -743,8 +758,7 @@ public class ResolveMerger extends ThreeWayMerger { unmergedPaths.add(tw.getPathString()); // generate a MergeResult for the deleted file - mergeResults.put(tw.getPathString(), - contentMerge(base, ours, theirs)); + mergeResults.put(tw.getPathString(), result); } } return true; @@ -765,12 +779,22 @@ public class ResolveMerger extends ThreeWayMerger { private MergeResult<RawText> contentMerge(CanonicalTreeParser base, CanonicalTreeParser ours, CanonicalTreeParser theirs) throws IOException { - RawText baseText = base == null ? RawText.EMPTY_TEXT : getRawText( + RawText baseText; + RawText ourText; + RawText theirsText; + + try { + baseText = base == null ? RawText.EMPTY_TEXT : getRawText( base.getEntryObjectId(), reader); - RawText ourText = ours == null ? RawText.EMPTY_TEXT : getRawText( + ourText = ours == null ? RawText.EMPTY_TEXT : getRawText( ours.getEntryObjectId(), reader); - RawText theirsText = theirs == null ? RawText.EMPTY_TEXT : getRawText( + theirsText = theirs == null ? RawText.EMPTY_TEXT : getRawText( theirs.getEntryObjectId(), reader); + } catch (BinaryBlobException e) { + MergeResult<RawText> r = new MergeResult<>(Collections.<RawText>emptyList()); + r.setContainsConflicts(true); + return r; + } return (mergeAlgorithm.merge(RawTextComparator.DEFAULT, baseText, ourText, theirsText)); } @@ -947,10 +971,13 @@ public class ResolveMerger extends ThreeWayMerger { } private static RawText getRawText(ObjectId id, ObjectReader reader) - throws IOException { + throws IOException, BinaryBlobException { if (id.equals(ObjectId.zeroId())) return new RawText(new byte[] {}); - return new RawText(reader.open(id, OBJ_BLOB).getCachedBytes()); + + ObjectLoader loader = reader.open(id, OBJ_BLOB); + int threshold = PackConfig.DEFAULT_BIG_FILE_THRESHOLD; + return RawText.load(loader, threshold); } private static boolean nonTree(final int mode) { @@ -961,12 +988,15 @@ public class ResolveMerger extends ThreeWayMerger { return FileMode.GITLINK.equals(mode); } + /** {@inheritDoc} */ @Override public ObjectId getResultTreeId() { return (resultTree == null) ? null : resultTree.toObjectId(); } /** + * Set the names of the commits as they would appear in conflict markers + * * @param commitNames * the names of the commits as they would appear in conflict * markers @@ -976,6 +1006,8 @@ public class ResolveMerger extends ThreeWayMerger { } /** + * Get the names of the commits as they would appear in conflict markers. + * * @return the names of the commits as they would appear in conflict * markers. */ @@ -984,17 +1016,22 @@ public class ResolveMerger extends ThreeWayMerger { } /** - * @return the paths with conflicts. This is a subset of the files listed - * by {@link #getModifiedFiles()} + * Get the paths with conflicts. This is a subset of the files listed by + * {@link #getModifiedFiles()} + * + * @return the paths with conflicts. This is a subset of the files listed by + * {@link #getModifiedFiles()} */ public List<String> getUnmergedPaths() { return unmergedPaths; } /** - * @return the paths of files which have been modified by this merge. A - * file will be modified if a content-merge works on this path or if - * the merge algorithm decides to take the theirs-version. This is a + * Get the paths of files which have been modified by this merge. + * + * @return the paths of files which have been modified by this merge. A file + * will be modified if a content-merge works on this path or if the + * merge algorithm decides to take the theirs-version. This is a * superset of the files listed by {@link #getUnmergedPaths()}. */ public List<String> getModifiedFiles() { @@ -1002,6 +1039,10 @@ public class ResolveMerger extends ThreeWayMerger { } /** + * Get a map which maps the paths of files which have to be checked out + * because the merge created new fully-merged content for this file into the + * index. + * * @return a map which maps the paths of files which have to be checked out * because the merge created new fully-merged content for this file * into the index. This means: the merge wrote a new stage 0 entry @@ -1012,6 +1053,8 @@ public class ResolveMerger extends ThreeWayMerger { } /** + * Get the mergeResults + * * @return the mergeResults */ public Map<String, MergeResult<? extends Sequence>> getMergeResults() { @@ -1019,6 +1062,9 @@ public class ResolveMerger extends ThreeWayMerger { } /** + * Get list of paths causing this merge to fail (not stopped because of a + * conflict). + * * @return lists paths causing this merge to fail (not stopped because of a * conflict). <code>null</code> is returned if this merge didn't * fail. @@ -1043,10 +1089,10 @@ public class ResolveMerger extends ThreeWayMerger { * not set explicitly and if this merger doesn't work in-core, this merger * will implicitly get and lock a default DirCache. If the DirCache is * explicitly set the caller is responsible to lock it in advance. Finally - * the merger will call {@link DirCache#commit()} which requires that the - * DirCache is locked. If the {@link #mergeImpl()} returns without throwing - * an exception the lock will be released. In case of exceptions the caller - * is responsible to release the lock. + * the merger will call {@link org.eclipse.jgit.dircache.DirCache#commit()} + * which requires that the DirCache is locked. If the {@link #mergeImpl()} + * returns without throwing an exception the lock will be released. In case + * of exceptions the caller is responsible to release the lock. * * @param dc * the DirCache to set @@ -1076,8 +1122,12 @@ public class ResolveMerger extends ThreeWayMerger { * The resolve conflict way of three way merging * * @param baseTree + * a {@link org.eclipse.jgit.treewalk.AbstractTreeIterator} + * object. * @param headTree + * a {@link org.eclipse.jgit.revwalk.RevTree} object. * @param mergeTree + * a {@link org.eclipse.jgit.revwalk.RevTree} object. * @param ignoreConflicts * Controls what to do in case a content-merge is done and a * conflict is detected. The default setting for this should be @@ -1094,11 +1144,11 @@ public class ResolveMerger extends ThreeWayMerger { * other stages are filled. Means: there is no conflict on that * path but the new content (including conflict markers) is * stored as successful merge result. This is needed in the - * context of {@link RecursiveMerger} where when determining - * merge bases we don't want to deal with content-merge - * conflicts. + * context of {@link org.eclipse.jgit.merge.RecursiveMerger} + * where when determining merge bases we don't want to deal with + * content-merge conflicts. * @return whether the trees merged cleanly - * @throws IOException + * @throws java.io.IOException * @since 3.5 */ protected boolean mergeTrees(AbstractTreeIterator baseTree, @@ -1161,9 +1211,9 @@ public class ResolveMerger extends ThreeWayMerger { * The walk to iterate over. * @param ignoreConflicts * see - * {@link ResolveMerger#mergeTrees(AbstractTreeIterator, RevTree, RevTree, boolean)} + * {@link org.eclipse.jgit.merge.ResolveMerger#mergeTrees(AbstractTreeIterator, RevTree, RevTree, boolean)} * @return Whether the trees merged cleanly. - * @throws IOException + * @throws java.io.IOException * @since 3.5 */ protected boolean mergeTreeWalk(TreeWalk treeWalk, boolean ignoreConflicts) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/merge/StrategyOneSided.java b/org.eclipse.jgit/src/org/eclipse/jgit/merge/StrategyOneSided.java index 2224dbc448..979685c409 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/merge/StrategyOneSided.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/merge/StrategyOneSided.java @@ -76,21 +76,25 @@ public class StrategyOneSided extends MergeStrategy { treeIndex = index; } + /** {@inheritDoc} */ @Override public String getName() { return strategyName; } + /** {@inheritDoc} */ @Override public Merger newMerger(final Repository db) { return new OneSide(db, treeIndex); } + /** {@inheritDoc} */ @Override public Merger newMerger(final Repository db, boolean inCore) { return new OneSide(db, treeIndex); } + /** {@inheritDoc} */ @Override public Merger newMerger(final ObjectInserter inserter, final Config config) { return new OneSide(inserter, treeIndex); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/merge/StrategyRecursive.java b/org.eclipse.jgit/src/org/eclipse/jgit/merge/StrategyRecursive.java index 56128dd93e..716b136d60 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/merge/StrategyRecursive.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/merge/StrategyRecursive.java @@ -54,21 +54,25 @@ import org.eclipse.jgit.lib.Repository; */ public class StrategyRecursive extends StrategyResolve { + /** {@inheritDoc} */ @Override public ThreeWayMerger newMerger(Repository db) { return new RecursiveMerger(db, false); } + /** {@inheritDoc} */ @Override public ThreeWayMerger newMerger(Repository db, boolean inCore) { return new RecursiveMerger(db, inCore); } + /** {@inheritDoc} */ @Override public ThreeWayMerger newMerger(ObjectInserter inserter, Config config) { return new RecursiveMerger(inserter, config); } + /** {@inheritDoc} */ @Override public String getName() { return "recursive"; //$NON-NLS-1$ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/merge/StrategyResolve.java b/org.eclipse.jgit/src/org/eclipse/jgit/merge/StrategyResolve.java index 17044b53ae..e836719633 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/merge/StrategyResolve.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/merge/StrategyResolve.java @@ -52,24 +52,25 @@ import org.eclipse.jgit.lib.Repository; */ public class StrategyResolve extends ThreeWayMergeStrategy { + /** {@inheritDoc} */ @Override public ThreeWayMerger newMerger(Repository db) { return new ResolveMerger(db, false); } + /** {@inheritDoc} */ @Override public ThreeWayMerger newMerger(Repository db, boolean inCore) { return new ResolveMerger(db, inCore); } - /** - * @since 4.8 - */ + /** {@inheritDoc} */ @Override public ThreeWayMerger newMerger(ObjectInserter inserter, Config config) { return new ResolveMerger(inserter, config); } + /** {@inheritDoc} */ @Override public String getName() { return "resolve"; //$NON-NLS-1$ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/merge/StrategySimpleTwoWayInCore.java b/org.eclipse.jgit/src/org/eclipse/jgit/merge/StrategySimpleTwoWayInCore.java index cd427bd8fb..5739d58b39 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/merge/StrategySimpleTwoWayInCore.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/merge/StrategySimpleTwoWayInCore.java @@ -69,30 +69,33 @@ import org.eclipse.jgit.treewalk.NameConflictTreeWalk; * file contents. */ public class StrategySimpleTwoWayInCore extends ThreeWayMergeStrategy { - /** Create a new instance of the strategy. */ + /** + * Create a new instance of the strategy. + */ protected StrategySimpleTwoWayInCore() { // } + /** {@inheritDoc} */ @Override public String getName() { return "simple-two-way-in-core"; //$NON-NLS-1$ } + /** {@inheritDoc} */ @Override public ThreeWayMerger newMerger(final Repository db) { return new InCoreMerger(db); } + /** {@inheritDoc} */ @Override public ThreeWayMerger newMerger(Repository db, boolean inCore) { // This class is always inCore, so ignore the parameter return newMerger(db); } - /** - * @since 4.8 - */ + /** {@inheritDoc} */ @Override public ThreeWayMerger newMerger(ObjectInserter inserter, Config config) { return new InCoreMerger(inserter); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/merge/ThreeWayMergeStrategy.java b/org.eclipse.jgit/src/org/eclipse/jgit/merge/ThreeWayMergeStrategy.java index c71590bb13..7d185ec0d5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/merge/ThreeWayMergeStrategy.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/merge/ThreeWayMergeStrategy.java @@ -45,11 +45,15 @@ package org.eclipse.jgit.merge; import org.eclipse.jgit.lib.Repository; -/** A merge strategy to merge 2 trees, using a common base ancestor tree. */ +/** + * A merge strategy to merge 2 trees, using a common base ancestor tree. + */ public abstract class ThreeWayMergeStrategy extends MergeStrategy { + /** {@inheritDoc} */ @Override public abstract ThreeWayMerger newMerger(Repository db); + /** {@inheritDoc} */ @Override public abstract ThreeWayMerger newMerger(Repository db, boolean inCore); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/merge/ThreeWayMerger.java b/org.eclipse.jgit/src/org/eclipse/jgit/merge/ThreeWayMerger.java index b3ef0fb3e4..3f28820092 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/merge/ThreeWayMerger.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/merge/ThreeWayMerger.java @@ -57,7 +57,9 @@ import org.eclipse.jgit.revwalk.RevTree; import org.eclipse.jgit.treewalk.AbstractTreeIterator; import org.eclipse.jgit.treewalk.EmptyTreeIterator; -/** A merge of 2 trees, using a common base ancestor tree. */ +/** + * A merge of 2 trees, using a common base ancestor tree. + */ public abstract class ThreeWayMerger extends Merger { private RevTree baseTree; @@ -103,11 +105,11 @@ public abstract class ThreeWayMerger extends Merger { * common base treeish; null to automatically compute the common * base from the input commits during * {@link #merge(AnyObjectId...)}. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the object is not a treeish. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the object does not exist. - * @throws IOException + * @throws java.io.IOException * the object could not be read. */ public void setBase(final AnyObjectId id) throws MissingObjectException, @@ -119,6 +121,7 @@ public abstract class ThreeWayMerger extends Merger { } } + /** {@inheritDoc} */ @Override public boolean merge(final AnyObjectId... tips) throws IOException { if (tips.length != 2) @@ -126,6 +129,7 @@ public abstract class ThreeWayMerger extends Merger { return super.merge(tips); } + /** {@inheritDoc} */ @Override public ObjectId getBaseCommitId() { return baseCommitId; @@ -136,7 +140,7 @@ public abstract class ThreeWayMerger extends Merger { * * @return an iterator over the caller-specified merge base, or the natural * merge base of the two input commits. - * @throws IOException + * @throws java.io.IOException */ protected AbstractTreeIterator mergeBase() throws IOException { if (baseTree != null) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/nls/NLS.java b/org.eclipse.jgit/src/org/eclipse/jgit/nls/NLS.java index 5e7beed1e5..89a87af9eb 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/nls/NLS.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/nls/NLS.java @@ -68,15 +68,13 @@ import org.eclipse.jgit.errors.TranslationStringMissingException; * </pre> */ public class NLS { - /** The root locale constant. It is defined here because the Locale.ROOT is not defined in Java 5 */ + /** + * The root locale constant. It is defined here because the Locale.ROOT is + * not defined in Java 5 + */ public static final Locale ROOT_LOCALE = new Locale("", "", ""); //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$ - private static final InheritableThreadLocal<NLS> local = new InheritableThreadLocal<NLS>() { - @Override - protected NLS initialValue() { - return new NLS(Locale.getDefault()); - } - }; + private static final InheritableThreadLocal<NLS> local = new InheritableThreadLocal<>(); /** * Sets the locale for the calling thread. @@ -96,27 +94,43 @@ public class NLS { /** * Sets the JVM default locale as the locale for the calling thread. * <p> - * Semantically this is equivalent to <code>NLS.setLocale(Locale.getDefault())</code>. + * Semantically this is equivalent to + * <code>NLS.setLocale(Locale.getDefault())</code>. */ public static void useJVMDefaultLocale() { - local.set(new NLS(Locale.getDefault())); + useJVMDefaultInternal(); + } + + // TODO(ms): change signature of public useJVMDefaultLocale() in 5.0 to get + // rid of this internal method + private static NLS useJVMDefaultInternal() { + NLS b = new NLS(Locale.getDefault()); + local.set(b); + return b; } /** * Returns an instance of the translation bundle of the required type. All * public String fields of the bundle instance will get their values - * injected as described in the {@link TranslationBundle}. + * injected as described in the + * {@link org.eclipse.jgit.nls.TranslationBundle}. * - * @param <T> - * required bundle type * @param type * required bundle type * @return an instance of the required bundle type - * @exception TranslationBundleLoadingException see {@link TranslationBundleLoadingException} - * @exception TranslationStringMissingException see {@link TranslationStringMissingException} + * @exception TranslationBundleLoadingException + * see + * {@link org.eclipse.jgit.errors.TranslationBundleLoadingException} + * @exception TranslationStringMissingException + * see + * {@link org.eclipse.jgit.errors.TranslationStringMissingException} */ public static <T extends TranslationBundle> T getBundleFor(Class<T> type) { - return local.get().get(type); + NLS b = local.get(); + if (b == null) { + b = useJVMDefaultInternal(); + } + return b.get(type); } final private Locale locale; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/nls/TranslationBundle.java b/org.eclipse.jgit/src/org/eclipse/jgit/nls/TranslationBundle.java index bde69c0eec..cdd7be266f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/nls/TranslationBundle.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/nls/TranslationBundle.java @@ -92,21 +92,22 @@ import org.eclipse.jgit.errors.TranslationStringMissingException; * </pre> * * The translated text is automatically injected into the public String fields - * according to the locale set with {@link NLS#setLocale(Locale)}. However, the - * {@link NLS#setLocale(Locale)} method defines only prefered locale which will - * be honored only if it is supported by the provided resource bundle property - * files. Basically, this class will use - * {@link ResourceBundle#getBundle(String, Locale)} method to load a resource - * bundle. See the documentation of this method for a detailed explanation of - * resource bundle loading strategy. After a bundle is created the - * {@link #effectiveLocale()} method can be used to determine whether the bundle - * really corresponds to the requested locale or is a fallback. + * according to the locale set with + * {@link org.eclipse.jgit.nls.NLS#setLocale(Locale)}. However, the + * {@link org.eclipse.jgit.nls.NLS#setLocale(Locale)} method defines only + * prefered locale which will be honored only if it is supported by the provided + * resource bundle property files. Basically, this class will use + * {@link java.util.ResourceBundle#getBundle(String, Locale)} method to load a + * resource bundle. See the documentation of this method for a detailed + * explanation of resource bundle loading strategy. After a bundle is created + * the {@link #effectiveLocale()} method can be used to determine whether the + * bundle really corresponds to the requested locale or is a fallback. * * <p> * To load a String from a resource bundle property file this class uses the - * {@link ResourceBundle#getString(String)}. This method can throw the - * {@link MissingResourceException} and this class is not making any effort to - * catch and/or translate this exception. + * {@link java.util.ResourceBundle#getString(String)}. This method can throw the + * {@link java.util.MissingResourceException} and this class is not making any + * effort to catch and/or translate this exception. * * <p> * To define a concrete translation bundle one has to: @@ -125,15 +126,20 @@ public abstract class TranslationBundle { private ResourceBundle resourceBundle; /** - * @return the locale locale used for loading the resource bundle from which - * the field values were taken + * Get the locale used for loading the resource bundle from which the field + * values were taken. + * + * @return the locale used for loading the resource bundle from which the + * field values were taken. */ public Locale effectiveLocale() { return effectiveLocale; } /** - * @return the resource bundle on which this translation bundle is based + * Get the resource bundle on which this translation bundle is based. + * + * @return the resource bundle on which this translation bundle is based. */ public ResourceBundle resourceBundle() { return resourceBundle; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/notes/DefaultNoteMerger.java b/org.eclipse.jgit/src/org/eclipse/jgit/notes/DefaultNoteMerger.java index 2e7327ca32..87bd4b55b1 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/notes/DefaultNoteMerger.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/notes/DefaultNoteMerger.java @@ -53,7 +53,7 @@ import org.eclipse.jgit.lib.ObjectReader; import org.eclipse.jgit.util.io.UnionInputStream; /** - * Default implementation of the {@link NoteMerger}. + * Default implementation of the {@link org.eclipse.jgit.notes.NoteMerger}. * <p> * If ours and theirs are both non-null, which means they are either both edits * or both adds, then this merger will simply join the content of ours and @@ -67,6 +67,7 @@ import org.eclipse.jgit.util.io.UnionInputStream; */ public class DefaultNoteMerger implements NoteMerger { + /** {@inheritDoc} */ @Override public Note merge(Note base, Note ours, Note theirs, ObjectReader reader, ObjectInserter inserter) throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/notes/Note.java b/org.eclipse.jgit/src/org/eclipse/jgit/notes/Note.java index 41e9bbeef8..7cf40ddf95 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/notes/Note.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/notes/Note.java @@ -46,7 +46,9 @@ package org.eclipse.jgit.notes; import org.eclipse.jgit.lib.AnyObjectId; import org.eclipse.jgit.lib.ObjectId; -/** In-memory representation of a single note attached to one object. */ +/** + * In-memory representation of a single note attached to one object. + */ public class Note extends ObjectId { private ObjectId data; @@ -63,7 +65,11 @@ public class Note extends ObjectId { data = noteData; } - /** @return the note content */ + /** + * Get the note content. + * + * @return the note content. + */ public ObjectId getData() { return data; } @@ -72,6 +78,7 @@ public class Note extends ObjectId { data = newData; } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMap.java b/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMap.java index 44c59260e8..cbef61338f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMap.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMap.java @@ -63,10 +63,11 @@ import org.eclipse.jgit.revwalk.RevTree; /** * Index of notes from a note branch. * - * This class is not thread-safe, and relies on an {@link ObjectReader} that it - * borrows/shares with the caller. The reader can be used during any call, and - * is not released by this class. The caller should arrange for releasing the - * shared {@code ObjectReader} at the proper times. + * This class is not thread-safe, and relies on an + * {@link org.eclipse.jgit.lib.ObjectReader} that it borrows/shares with the + * caller. The reader can be used during any call, and is not released by this + * class. The caller should arrange for releasing the shared + * {@code ObjectReader} at the proper times. */ public class NoteMap implements Iterable<Note> { /** @@ -81,10 +82,11 @@ public class NoteMap implements Iterable<Note> { } /** - * Shorten the note ref name by trimming off the {@link Constants#R_NOTES} - * prefix if it exists. + * Shorten the note ref name by trimming off the + * {@link org.eclipse.jgit.lib.Constants#R_NOTES} prefix if it exists. * * @param noteRefName + * a {@link java.lang.String} object. * @return a more user friendly note name */ public static String shortenRefName(String noteRefName) { @@ -103,13 +105,13 @@ public class NoteMap implements Iterable<Note> { * @param commit * the revision of the note branch to read. * @return the note map read from the commit. - * @throws IOException + * @throws java.io.IOException * the repository cannot be accessed through the reader. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * a tree object is corrupt and cannot be read. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * a tree object wasn't actually a tree. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * a reference tree object doesn't exist. */ public static NoteMap read(ObjectReader reader, RevCommit commit) @@ -128,13 +130,13 @@ public class NoteMap implements Iterable<Note> { * @param tree * the note tree to read. * @return the note map read from the tree. - * @throws IOException + * @throws java.io.IOException * the repository cannot be accessed through the reader. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * a tree object is corrupt and cannot be read. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * a tree object wasn't actually a tree. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * a reference tree object doesn't exist. */ public static NoteMap read(ObjectReader reader, RevTree tree) @@ -153,13 +155,13 @@ public class NoteMap implements Iterable<Note> { * @param treeId * the note tree to read. * @return the note map read from the tree. - * @throws IOException + * @throws java.io.IOException * the repository cannot be accessed through the reader. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * a tree object is corrupt and cannot be read. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * a tree object wasn't actually a tree. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * a reference tree object doesn't exist. */ public static NoteMap readTree(ObjectReader reader, ObjectId treeId) @@ -197,10 +199,7 @@ public class NoteMap implements Iterable<Note> { this.reader = reader; } - /** - * @return an iterator that iterates over notes of this NoteMap. Non note - * entries are ignored by this iterator. - */ + /** {@inheritDoc} */ @Override public Iterator<Note> iterator() { try { @@ -216,7 +215,7 @@ public class NoteMap implements Iterable<Note> { * @param id * the object to look for. * @return the note's blob ObjectId, or null if no note exists. - * @throws IOException + * @throws java.io.IOException * a portion of the note space is not accessible. */ public ObjectId get(AnyObjectId id) throws IOException { @@ -230,7 +229,7 @@ public class NoteMap implements Iterable<Note> { * @param id * the object to look for. * @return the note for the given object id, or null if no note exists. - * @throws IOException + * @throws java.io.IOException * a portion of the note space is not accessible. */ public Note getNote(AnyObjectId id) throws IOException { @@ -243,7 +242,7 @@ public class NoteMap implements Iterable<Note> { * @param id * the object to look for. * @return true if a note exists; false if there is no note. - * @throws IOException + * @throws java.io.IOException * a portion of the note space is not accessible. */ public boolean contains(AnyObjectId id) throws IOException { @@ -269,11 +268,11 @@ public class NoteMap implements Iterable<Note> { * larger than this limit, LargeObjectException will be thrown. * @return if a note is defined for {@code id}, the note content. If no note * is defined, null. - * @throws LargeObjectException + * @throws org.eclipse.jgit.errors.LargeObjectException * the note data is larger than {@code sizeLimit}. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the note's blob does not exist in the repository. - * @throws IOException + * @throws java.io.IOException * the note's blob cannot be read from the repository */ public byte[] getCachedBytes(AnyObjectId id, int sizeLimit) @@ -306,7 +305,7 @@ public class NoteMap implements Iterable<Note> { * data to associate with the note. This must be the ObjectId of * a blob that already exists in the repository. If null the note * will be deleted, if present. - * @throws IOException + * @throws java.io.IOException * a portion of the note space is not accessible. */ public void set(AnyObjectId noteOn, ObjectId noteData) throws IOException { @@ -337,7 +336,7 @@ public class NoteMap implements Iterable<Note> { * inserter to write the encoded {@code noteData} out as a blob. * The caller must ensure the inserter is flushed before the * updated note map is made available for reading. - * @throws IOException + * @throws java.io.IOException * the note data could not be stored in the repository. */ public void set(AnyObjectId noteOn, String noteData, ObjectInserter ins) @@ -361,7 +360,7 @@ public class NoteMap implements Iterable<Note> { * * @param noteOn * the object to remove the note from. - * @throws IOException + * @throws java.io.IOException * a portion of the note space is not accessible. */ public void remove(AnyObjectId noteOn) throws IOException { @@ -376,7 +375,7 @@ public class NoteMap implements Iterable<Note> { * Caller is responsible for flushing the inserter before trying * to read the objects, or exposing them through a reference. * @return the top level tree. - * @throws IOException + * @throws java.io.IOException * a tree could not be written. */ public ObjectId writeTree(ObjectInserter inserter) throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMapMerger.java b/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMapMerger.java index 19ec1a13db..325ff4f268 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMapMerger.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMapMerger.java @@ -56,14 +56,13 @@ import org.eclipse.jgit.lib.Repository; import org.eclipse.jgit.merge.MergeStrategy; import org.eclipse.jgit.merge.Merger; import org.eclipse.jgit.merge.ThreeWayMerger; -import org.eclipse.jgit.treewalk.AbstractTreeIterator; -import org.eclipse.jgit.treewalk.TreeWalk; /** * Three-way note tree merge. * <p> - * Direct implementation of NoteMap merger without using {@link TreeWalk} and - * {@link AbstractTreeIterator} + * Direct implementation of NoteMap merger without using + * {@link org.eclipse.jgit.treewalk.TreeWalk} and + * {@link org.eclipse.jgit.treewalk.AbstractTreeIterator} */ public class NoteMapMerger { private static final FanoutBucket EMPTY_FANOUT = new FanoutBucket(0); @@ -83,8 +82,9 @@ public class NoteMapMerger { private final MutableObjectId objectIdPrefix; /** - * Constructs a NoteMapMerger with custom {@link NoteMerger} and custom - * {@link MergeStrategy}. + * Constructs a NoteMapMerger with custom + * {@link org.eclipse.jgit.notes.NoteMerger} and custom + * {@link org.eclipse.jgit.merge.MergeStrategy}. * * @param db * Git repository @@ -104,9 +104,10 @@ public class NoteMapMerger { } /** - * Constructs a NoteMapMerger with {@link DefaultNoteMerger} as the merger - * for notes and the {@link MergeStrategy#RESOLVE} as the strategy for - * resolving conflicts on non-notes + * Constructs a NoteMapMerger with + * {@link org.eclipse.jgit.notes.DefaultNoteMerger} as the merger for notes + * and the {@link org.eclipse.jgit.merge.MergeStrategy#RESOLVE} as the + * strategy for resolving conflicts on non-notes * * @param db * Git repository @@ -125,7 +126,7 @@ public class NoteMapMerger { * @param theirs * theirs version of the note tree * @return merge result as a new NoteMap - * @throws IOException + * @throws java.io.IOException */ public NoteMap merge(NoteMap base, NoteMap ours, NoteMap theirs) throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMerger.java b/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMerger.java index c70211df9e..8df4998a8c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMerger.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/notes/NoteMerger.java @@ -72,13 +72,13 @@ public interface NoteMerger { * @param inserter * the object inserter that must be used to insert Git objects * @return the merge result - * @throws NotesMergeConflictException + * @throws org.eclipse.jgit.notes.NotesMergeConflictException * in case there was a merge conflict which this note merger * couldn't resolve - * @throws IOException - * in case the reader or the inserter would throw an IOException - * the implementor will most likely want to propagate it as it - * can't do much to recover from it + * @throws java.io.IOException + * in case the reader or the inserter would throw an + * java.io.IOException the implementor will most likely want to + * propagate it as it can't do much to recover from it */ Note merge(Note base, Note ours, Note their, ObjectReader reader, ObjectInserter inserter) throws NotesMergeConflictException, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/notes/NotesMergeConflictException.java b/org.eclipse.jgit/src/org/eclipse/jgit/notes/NotesMergeConflictException.java index 94fba0fc61..796f1d1d89 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/notes/NotesMergeConflictException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/notes/NotesMergeConflictException.java @@ -49,8 +49,9 @@ import java.text.MessageFormat; import org.eclipse.jgit.internal.JGitText; /** - * This exception will be thrown from the {@link NoteMerger} when a conflict on - * Notes content is found during merge. + * This exception will be thrown from the + * {@link org.eclipse.jgit.notes.NoteMerger} when a conflict on Notes content is + * found during merge. */ public class NotesMergeConflictException extends IOException { private static final long serialVersionUID = 1L; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/patch/BinaryHunk.java b/org.eclipse.jgit/src/org/eclipse/jgit/patch/BinaryHunk.java index d0a6b1f318..079d6f6d67 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/patch/BinaryHunk.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/patch/BinaryHunk.java @@ -49,7 +49,9 @@ import static org.eclipse.jgit.util.RawParseUtils.match; import static org.eclipse.jgit.util.RawParseUtils.nextLF; import static org.eclipse.jgit.util.RawParseUtils.parseBase10; -/** Part of a "GIT binary patch" to describe the pre-image or post-image */ +/** + * Part of a "GIT binary patch" to describe the pre-image or post-image + */ public class BinaryHunk { private static final byte[] LITERAL = encodeASCII("literal "); //$NON-NLS-1$ @@ -83,32 +85,56 @@ public class BinaryHunk { startOffset = offset; } - /** @return header for the file this hunk applies to */ + /** + * Get header for the file this hunk applies to. + * + * @return header for the file this hunk applies to. + */ public FileHeader getFileHeader() { return file; } - /** @return the byte array holding this hunk's patch script. */ + /** + * Get the byte array holding this hunk's patch script. + * + * @return the byte array holding this hunk's patch script. + */ public byte[] getBuffer() { return file.buf; } - /** @return offset the start of this hunk in {@link #getBuffer()}. */ + /** + * Get offset the start of this hunk in {@link #getBuffer()}. + * + * @return offset the start of this hunk in {@link #getBuffer()}. + */ public int getStartOffset() { return startOffset; } - /** @return offset one past the end of the hunk in {@link #getBuffer()}. */ + /** + * Get offset one past the end of the hunk in {@link #getBuffer()}. + * + * @return offset one past the end of the hunk in {@link #getBuffer()}. + */ public int getEndOffset() { return endOffset; } - /** @return type of this binary hunk */ + /** + * Get type of this binary hunk. + * + * @return type of this binary hunk. + */ public Type getType() { return type; } - /** @return inflated size of this hunk's data */ + /** + * Get inflated size of this hunk's data. + * + * @return inflated size of this hunk's data. + */ public int getSize() { return length; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/patch/CombinedFileHeader.java b/org.eclipse.jgit/src/org/eclipse/jgit/patch/CombinedFileHeader.java index 2c8f34e7cd..1afb53da8e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/patch/CombinedFileHeader.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/patch/CombinedFileHeader.java @@ -73,19 +73,29 @@ public class CombinedFileHeader extends FileHeader { super(b, offset); } + /** {@inheritDoc} */ @Override @SuppressWarnings("unchecked") public List<? extends CombinedHunkHeader> getHunks() { return (List<CombinedHunkHeader>) super.getHunks(); } - /** @return number of ancestor revisions mentioned in this diff. */ + /** + * {@inheritDoc} + * <p> + * + * @return number of ancestor revisions mentioned in this diff. + */ @Override public int getParentCount() { return oldIds.length; } - /** @return get the file mode of the first parent. */ + /** + * {@inheritDoc} + * <p> + * @return get the file mode of the first parent. + */ @Override public FileMode getOldMode() { return getOldMode(0); @@ -102,7 +112,12 @@ public class CombinedFileHeader extends FileHeader { return oldModes[nthParent]; } - /** @return get the object id of the first parent. */ + /** + * {@inheritDoc} + * <p> + * + * @return get the object id of the first parent. + */ @Override public AbbreviatedObjectId getOldId() { return getOldId(0); @@ -119,6 +134,7 @@ public class CombinedFileHeader extends FileHeader { return oldIds[nthParent]; } + /** {@inheritDoc} */ @Override public String getScriptText(final Charset ocs, final Charset ncs) { final Charset[] cs = new Charset[getParentCount() + 1]; @@ -128,15 +144,9 @@ public class CombinedFileHeader extends FileHeader { } /** + * {@inheritDoc} + * <p> * Convert the patch script for this file into a string. - * - * @param charsetGuess - * optional array to suggest the character set to use when - * decoding each file's line. If supplied the array must have a - * length of <code>{@link #getParentCount()} + 1</code> - * representing the old revision character sets and the new - * revision character set. - * @return the patch script, as a Unicode string. */ @Override public String getScriptText(final Charset[] charsetGuess) { @@ -179,6 +189,7 @@ public class CombinedFileHeader extends FileHeader { return ptr; } + /** {@inheritDoc} */ @Override protected void parseIndexLine(int ptr, final int eol) { // "index $asha1,$bsha1..$csha1" @@ -200,6 +211,7 @@ public class CombinedFileHeader extends FileHeader { oldModes = new FileMode[oldIds.length]; } + /** {@inheritDoc} */ @Override protected void parseNewFileMode(final int ptr, final int eol) { for (int i = 0; i < oldModes.length; i++) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/patch/CombinedHunkHeader.java b/org.eclipse.jgit/src/org/eclipse/jgit/patch/CombinedHunkHeader.java index ed79787291..bbf802317d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/patch/CombinedHunkHeader.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/patch/CombinedHunkHeader.java @@ -54,7 +54,9 @@ import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.lib.AbbreviatedObjectId; import org.eclipse.jgit.util.MutableInteger; -/** Hunk header for a hunk appearing in a "diff --cc" style patch. */ +/** + * Hunk header for a hunk appearing in a "diff --cc" style patch. + */ public class CombinedHunkHeader extends HunkHeader { private static abstract class CombinedOldImage extends OldImage { int nContext; @@ -76,11 +78,13 @@ public class CombinedHunkHeader extends HunkHeader { } } + /** {@inheritDoc} */ @Override public CombinedFileHeader getFileHeader() { return (CombinedFileHeader) super.getFileHeader(); } + /** {@inheritDoc} */ @Override public OldImage getOldImage() { return getOldImage(0); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/patch/FileHeader.java b/org.eclipse.jgit/src/org/eclipse/jgit/patch/FileHeader.java index eb28a0e2a3..5cfbbb2d88 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/patch/FileHeader.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/patch/FileHeader.java @@ -69,7 +69,9 @@ import org.eclipse.jgit.util.QuotedString; import org.eclipse.jgit.util.RawParseUtils; import org.eclipse.jgit.util.TemporaryBuffer; -/** Patch header describing an action for a single file path. */ +/** + * Patch header describing an action for a single file path. + */ public class FileHeader extends DiffEntry { private static final byte[] OLD_MODE = encodeASCII("old mode "); //$NON-NLS-1$ @@ -164,17 +166,30 @@ public class FileHeader extends DiffEntry { return 1; } - /** @return the byte array holding this file's patch script. */ + /** + * Get the byte array holding this file's patch script. + * + * @return the byte array holding this file's patch script. + */ public byte[] getBuffer() { return buf; } - /** @return offset the start of this file's script in {@link #getBuffer()}. */ + /** + * Get offset of the start of this file's script in {@link #getBuffer()}. + * + * @return offset of the start of this file's script in + * {@link #getBuffer()}. + */ public int getStartOffset() { return startOffset; } - /** @return offset one past the end of the file script. */ + /** + * Get offset one past the end of the file script. + * + * @return offset one past the end of the file script. + */ public int getEndOffset() { return endOffset; } @@ -182,8 +197,9 @@ public class FileHeader extends DiffEntry { /** * Convert the patch script for this file into a string. * <p> - * The default character encoding ({@link Constants#CHARSET}) is assumed for - * both the old and new files. + * The default character encoding + * ({@link org.eclipse.jgit.lib.Constants#CHARSET}) is assumed for both the + * old and new files. * * @return the patch script, as a Unicode string. */ @@ -284,17 +300,29 @@ public class FileHeader extends DiffEntry { } } - /** @return style of patch used to modify this file */ + /** + * Get style of patch used to modify this file. + * + * @return style of patch used to modify this file. + */ public PatchType getPatchType() { return patchType; } - /** @return true if this patch modifies metadata about a file */ + /** + * Whether this patch modifies metadata about a file + * + * @return {@code true} if this patch modifies metadata about a file . + */ public boolean hasMetaDataChanges() { return changeType != ChangeType.MODIFY || newMode != oldMode; } - /** @return hunks altering this file; in order of appearance in patch */ + /** + * Get hunks altering this file; in order of appearance in patch + * + * @return hunks altering this file; in order of appearance in patch. + */ public List<? extends HunkHeader> getHunks() { if (hunks == null) return Collections.emptyList(); @@ -313,17 +341,33 @@ public class FileHeader extends DiffEntry { return new HunkHeader(this, offset); } - /** @return if a {@link PatchType#GIT_BINARY}, the new-image delta/literal */ + /** + * Get the new-image delta/literal if this is a + * {@link PatchType#GIT_BINARY}. + * + * @return the new-image delta/literal if this is a + * {@link PatchType#GIT_BINARY}. + */ public BinaryHunk getForwardBinaryHunk() { return forwardBinaryHunk; } - /** @return if a {@link PatchType#GIT_BINARY}, the old-image delta/literal */ + /** + * Get the old-image delta/literal if this is a + * {@link PatchType#GIT_BINARY}. + * + * @return the old-image delta/literal if this is a + * {@link PatchType#GIT_BINARY}. + */ public BinaryHunk getReverseBinaryHunk() { return reverseBinaryHunk; } - /** @return a list describing the content edits performed on this file. */ + /** + * Convert to a list describing the content edits performed on this file. + * + * @return a list describing the content edits performed on this file. + */ public EditList toEditList() { final EditList r = new EditList(); for (final HunkHeader hunk : hunks) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/patch/FormatError.java b/org.eclipse.jgit/src/org/eclipse/jgit/patch/FormatError.java index 767cb24306..1dd24d732e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/patch/FormatError.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/patch/FormatError.java @@ -48,7 +48,9 @@ import java.util.Locale; import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.util.RawParseUtils; -/** An error in a patch script */ +/** + * An error in a patch script + */ public class FormatError { /** Classification of an error. */ public static enum Severity { @@ -75,32 +77,53 @@ public class FormatError { message = msg; } - /** @return the severity of the error. */ + /** + * Get the severity of the error. + * + * @return the severity of the error. + */ public Severity getSeverity() { return severity; } - /** @return a message describing the error. */ + /** + * Get a message describing the error. + * + * @return a message describing the error. + */ public String getMessage() { return message; } - /** @return the byte buffer holding the patch script. */ + /** + * Get the byte buffer holding the patch script. + * + * @return the byte buffer holding the patch script. + */ public byte[] getBuffer() { return buf; } - /** @return byte offset within {@link #getBuffer()} where the error is */ + /** + * Get byte offset within {@link #getBuffer()} where the error is. + * + * @return byte offset within {@link #getBuffer()} where the error is. + */ public int getOffset() { return offset; } - /** @return line of the patch script the error appears on. */ + /** + * Get line of the patch script the error appears on. + * + * @return line of the patch script the error appears on. + */ public String getLineText() { final int eol = RawParseUtils.nextLF(buf, offset); return RawParseUtils.decode(Constants.CHARSET, buf, offset, eol); } + /** {@inheritDoc} */ @Override public String toString() { final StringBuilder r = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/patch/HunkHeader.java b/org.eclipse.jgit/src/org/eclipse/jgit/patch/HunkHeader.java index d72b9bb83a..d022d47833 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/patch/HunkHeader.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/patch/HunkHeader.java @@ -57,7 +57,9 @@ import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.lib.AbbreviatedObjectId; import org.eclipse.jgit.util.MutableInteger; -/** Hunk header describing the layout of a single block of lines */ +/** + * Hunk header describing the layout of a single block of lines + */ public class HunkHeader { /** Details about an old image of the file. */ public abstract static class OldImage { @@ -148,47 +150,83 @@ public class HunkHeader { } } - /** @return header for the file this hunk applies to */ + /** + * Get header for the file this hunk applies to. + * + * @return header for the file this hunk applies to. + */ public FileHeader getFileHeader() { return file; } - /** @return the byte array holding this hunk's patch script. */ + /** + * Get the byte array holding this hunk's patch script. + * + * @return the byte array holding this hunk's patch script. + */ public byte[] getBuffer() { return file.buf; } - /** @return offset the start of this hunk in {@link #getBuffer()}. */ + /** + * Get offset of the start of this hunk in {@link #getBuffer()}. + * + * @return offset of the start of this hunk in {@link #getBuffer()}. + */ public int getStartOffset() { return startOffset; } - /** @return offset one past the end of the hunk in {@link #getBuffer()}. */ + /** + * Get offset one past the end of the hunk in {@link #getBuffer()}. + * + * @return offset one past the end of the hunk in {@link #getBuffer()}. + */ public int getEndOffset() { return endOffset; } - /** @return information about the old image mentioned in this hunk. */ + /** + * Get information about the old image mentioned in this hunk. + * + * @return information about the old image mentioned in this hunk. + */ public OldImage getOldImage() { return old; } - /** @return first line number in the post-image file where the hunk starts */ + /** + * Get first line number in the post-image file where the hunk starts. + * + * @return first line number in the post-image file where the hunk starts. + */ public int getNewStartLine() { return newStartLine; } - /** @return Total number of post-image lines this hunk covers */ + /** + * Get total number of post-image lines this hunk covers. + * + * @return total number of post-image lines this hunk covers. + */ public int getNewLineCount() { return newLineCount; } - /** @return total number of lines of context appearing in this hunk */ + /** + * Get total number of lines of context appearing in this hunk. + * + * @return total number of lines of context appearing in this hunk. + */ public int getLinesContext() { return nContext; } - /** @return a list describing the content edits performed within the hunk. */ + /** + * Convert to a list describing the content edits performed within the hunk. + * + * @return a list describing the content edits performed within the hunk. + */ public EditList toEditList() { if (editList == null) { editList = new EditList(); @@ -404,6 +442,7 @@ public class HunkHeader { offsets[fileIdx] = end < 0 ? s.length() : end + 1; } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/patch/Patch.java b/org.eclipse.jgit/src/org/eclipse/jgit/patch/Patch.java index 10ac449d12..05fab92e8b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/patch/Patch.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/patch/Patch.java @@ -58,7 +58,10 @@ import java.util.List; import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.util.TemporaryBuffer; -/** A parsed collection of {@link FileHeader}s from a unified diff patch file */ +/** + * A parsed collection of {@link org.eclipse.jgit.patch.FileHeader}s from a + * unified diff patch file + */ public class Patch { static final byte[] DIFF_GIT = encodeASCII("diff --git "); //$NON-NLS-1$ @@ -81,7 +84,9 @@ public class Patch { /** Formatting errors, if any were identified. */ private final List<FormatError> errors; - /** Create an empty patch. */ + /** + * Create an empty patch. + */ public Patch() { files = new ArrayList<>(); errors = new ArrayList<>(0); @@ -100,7 +105,11 @@ public class Patch { files.add(fh); } - /** @return list of files described in the patch, in occurrence order. */ + /** + * Get list of files described in the patch, in occurrence order. + * + * @return list of files described in the patch, in occurrence order. + */ public List<? extends FileHeader> getFiles() { return files; } @@ -115,7 +124,11 @@ public class Patch { errors.add(err); } - /** @return collection of formatting errors, if any. */ + /** + * Get collection of formatting errors. + * + * @return collection of formatting errors, if any. + */ public List<FormatError> getErrors() { return errors; } @@ -130,7 +143,7 @@ public class Patch { * @param is * the stream to read the patch data from. The stream is read * until EOF is reached. - * @throws IOException + * @throws java.io.IOException * there was an error reading from the input stream. */ public void parse(final InputStream is) throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotCommit.java b/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotCommit.java index 98bcd1accf..091bf683ac 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotCommit.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotCommit.java @@ -149,7 +149,7 @@ public class PlotCommit<L extends PlotLane> extends RevCommit { * child index to obtain. Must be in the range 0 through * {@link #getChildCount()}-1. * @return the specified child. - * @throws ArrayIndexOutOfBoundsException + * @throws java.lang.ArrayIndexOutOfBoundsException * an invalid child index was specified. */ public final PlotCommit getChild(final int nth) { @@ -186,7 +186,7 @@ public class PlotCommit<L extends PlotLane> extends RevCommit { * ref index to obtain. Must be in the range 0 through * {@link #getRefCount()}-1. * @return the specified ref. - * @throws ArrayIndexOutOfBoundsException + * @throws java.lang.ArrayIndexOutOfBoundsException * an invalid ref index was specified. */ public final Ref getRef(final int nth) { @@ -203,6 +203,7 @@ public class PlotCommit<L extends PlotLane> extends RevCommit { return (L) lane; } + /** {@inheritDoc} */ @Override public void reset() { forkingOffLanes = NO_LANES; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotCommitList.java b/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotCommitList.java index a8eb86e232..6a0ba66ba1 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotCommitList.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotCommitList.java @@ -57,13 +57,13 @@ import org.eclipse.jgit.revwalk.RevCommitList; import org.eclipse.jgit.revwalk.RevWalk; /** - * An ordered list of {@link PlotCommit} subclasses. + * An ordered list of {@link org.eclipse.jgit.revplot.PlotCommit} subclasses. * <p> * Commits are allocated into lanes as they enter the list, based upon their * connections between descendant (child) commits and ancestor (parent) commits. * <p> - * The source of the list must be a {@link PlotWalk} and {@link #fillTo(int)} - * must be used to populate the list. + * The source of the list must be a {@link org.eclipse.jgit.revplot.PlotWalk} + * and {@link #fillTo(int)} must be used to populate the list. * * @param <L> * type of lane used by the application. @@ -82,6 +82,7 @@ public class PlotCommitList<L extends PlotLane> extends private final HashMap<PlotLane, Integer> laneLength = new HashMap<>( 32); + /** {@inheritDoc} */ @Override public void clear() { super.clear(); @@ -91,6 +92,7 @@ public class PlotCommitList<L extends PlotLane> extends laneLength.clear(); } + /** {@inheritDoc} */ @Override public void source(final RevWalk w) { if (!(w instanceof PlotWalk)) @@ -122,6 +124,7 @@ public class PlotCommitList<L extends PlotLane> extends result.add((L) p); } + /** {@inheritDoc} */ @Override protected void enter(final int index, final PlotCommit<L> currCommit) { setupChildren(currCommit); @@ -395,7 +398,11 @@ public class PlotCommitList<L extends PlotLane> extends } /** - * @return a new Lane appropriate for this particular PlotList. + * Create a new {@link PlotLane} appropriate for this particular + * {@link PlotCommitList}. + * + * @return a new {@link PlotLane} appropriate for this particular + * {@link PlotCommitList}. */ @SuppressWarnings("unchecked") protected L createLane() { @@ -407,6 +414,7 @@ public class PlotCommitList<L extends PlotLane> extends * is no longer needed. * * @param lane + * a lane */ protected void recycleLane(final L lane) { // Nothing. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotWalk.java b/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotWalk.java index be1f07a38c..8ba8d6e4ca 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotWalk.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotWalk.java @@ -70,11 +70,14 @@ import org.eclipse.jgit.revwalk.RevSort; import org.eclipse.jgit.revwalk.RevTag; import org.eclipse.jgit.revwalk.RevWalk; -/** Specialized RevWalk for visualization of a commit graph. */ +/** + * Specialized RevWalk for visualization of a commit graph. + */ public class PlotWalk extends RevWalk { private Map<AnyObjectId, Set<Ref>> reverseRefMap; + /** {@inheritDoc} */ @Override public void dispose() { super.dispose(); @@ -98,8 +101,7 @@ public class PlotWalk extends RevWalk { * * @param refs * additional refs - * - * @throws IOException + * @throws java.io.IOException */ public void addAdditionalRefs(Iterable<Ref> refs) throws IOException { for (Ref ref : refs) { @@ -114,6 +116,7 @@ public class PlotWalk extends RevWalk { } } + /** {@inheritDoc} */ @Override public void sort(final RevSort s, final boolean use) { if (s == RevSort.TOPO && !use) @@ -121,11 +124,13 @@ public class PlotWalk extends RevWalk { super.sort(s, use); } + /** {@inheritDoc} */ @Override protected RevCommit createCommit(final AnyObjectId id) { return new PlotCommit(id); } + /** {@inheritDoc} */ @Override public RevCommit next() throws MissingObjectException, IncorrectObjectTypeException, IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/AbstractRevQueue.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/AbstractRevQueue.java index 4923d0f741..b948adb42e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/AbstractRevQueue.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/AbstractRevQueue.java @@ -103,14 +103,16 @@ abstract class AbstractRevQueue extends Generator { } /** + * {@inheritDoc} + * <p> * Remove the first commit from the queue. - * - * @return the first commit of this queue. */ @Override public abstract RevCommit next(); - /** Remove all entries from this queue. */ + /** + * Remove all entries from this queue. + */ public abstract void clear(); abstract boolean everbodyHasFlag(int f); @@ -122,6 +124,14 @@ abstract class AbstractRevQueue extends Generator { return outputType; } + /** + * Describe this queue + * + * @param s + * a StringBuilder + * @param c + * a {@link org.eclipse.jgit.revwalk.RevCommit} + */ protected static void describe(final StringBuilder s, final RevCommit c) { s.append(c.toString()); s.append('\n'); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/AsyncRevObjectQueue.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/AsyncRevObjectQueue.java index 1c0438a5ed..d263184622 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/AsyncRevObjectQueue.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/AsyncRevObjectQueue.java @@ -59,11 +59,11 @@ public interface AsyncRevObjectQueue extends AsyncOperation { * Obtain the next object. * * @return the object; null if there are no more objects remaining. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the object does not exist. There may be more objects * remaining in the iteration, the application should call * {@link #next()} again. - * @throws IOException + * @throws java.io.IOException * the object store cannot be accessed. */ public RevObject next() throws MissingObjectException, IOException; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackWriterBitmapWalker.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/BitmapWalker.java index a5c3b71eb2..b07de5f1f6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/internal/storage/pack/PackWriterBitmapWalker.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/BitmapWalker.java @@ -41,29 +41,30 @@ * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ -package org.eclipse.jgit.internal.storage.pack; +package org.eclipse.jgit.revwalk; import java.io.IOException; import java.util.Arrays; import org.eclipse.jgit.errors.IncorrectObjectTypeException; import org.eclipse.jgit.errors.MissingObjectException; +import org.eclipse.jgit.internal.revwalk.AddToBitmapFilter; +import org.eclipse.jgit.internal.revwalk.AddUnseenToBitmapFilter; +import org.eclipse.jgit.lib.AnyObjectId; import org.eclipse.jgit.lib.BitmapIndex; import org.eclipse.jgit.lib.BitmapIndex.Bitmap; import org.eclipse.jgit.lib.BitmapIndex.BitmapBuilder; -import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.lib.NullProgressMonitor; import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.lib.ProgressMonitor; -import org.eclipse.jgit.revwalk.ObjectWalk; -import org.eclipse.jgit.revwalk.RevCommit; -import org.eclipse.jgit.revwalk.RevFlag; -import org.eclipse.jgit.revwalk.RevObject; -import org.eclipse.jgit.revwalk.RevWalk; -import org.eclipse.jgit.revwalk.filter.RevFilter; +import org.eclipse.jgit.revwalk.filter.ObjectFilter; -/** Helper class for PackWriter to do ObjectWalks with pack index bitmaps. */ -final class PackWriterBitmapWalker { +/** + * Helper class to do ObjectWalks with pack index bitmaps. + * + * @since 4.10 + */ +public final class BitmapWalker { private final ObjectWalk walker; @@ -73,18 +74,58 @@ final class PackWriterBitmapWalker { private long countOfBitmapIndexMisses; - PackWriterBitmapWalker( + /** + * Create a BitmapWalker. + * + * @param walker walker to use when traversing the object graph. + * @param bitmapIndex index to obtain bitmaps from. + * @param pm progress monitor to report progress on. + */ + public BitmapWalker( ObjectWalk walker, BitmapIndex bitmapIndex, ProgressMonitor pm) { this.walker = walker; this.bitmapIndex = bitmapIndex; this.pm = (pm == null) ? NullProgressMonitor.INSTANCE : pm; } - long getCountOfBitmapIndexMisses() { + /** + * Return the number of objects that had to be walked because they were not covered by a + * bitmap. + * + * @return the number of objects that had to be walked because they were not covered by a + * bitmap. + */ + public long getCountOfBitmapIndexMisses() { return countOfBitmapIndexMisses; } - BitmapBuilder findObjects(Iterable<? extends ObjectId> start, BitmapBuilder seen, + /** + * Return, as a bitmap, the objects reachable from the objects in start. + * + * @param start + * the objects to start the object traversal from. + * @param seen + * the objects to skip if encountered during traversal. + * @param ignoreMissing + * true to ignore missing objects, false otherwise. + * @return as a bitmap, the objects reachable from the objects in start. + * @throws org.eclipse.jgit.errors.MissingObjectException + * the object supplied is not available from the object + * database. This usually indicates the supplied object is + * invalid, but the reference was constructed during an earlier + * invocation to + * {@link org.eclipse.jgit.revwalk.RevWalk#lookupAny(AnyObjectId, int)}. + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException + * the object was not parsed yet and it was discovered during + * parsing that it is not actually the type of the instance + * passed in. This usually indicates the caller used the wrong + * type in a + * {@link org.eclipse.jgit.revwalk.RevWalk#lookupAny(AnyObjectId, int)} + * call. + * @throws java.io.IOException + * a pack file or loose object could not be read. + */ + public BitmapBuilder findObjects(Iterable<? extends ObjectId> start, BitmapBuilder seen, boolean ignoreMissing) throws MissingObjectException, IncorrectObjectTypeException, IOException { @@ -167,6 +208,7 @@ final class PackWriterBitmapWalker { walker.setRevFilter( new AddUnseenToBitmapFilter(seen, bitmapResult)); } + walker.setObjectFilter(new BitmapObjectFilter(bitmapResult)); while (walker.next() != null) { // Iterate through all of the commits. The BitmapRevFilter does @@ -193,104 +235,20 @@ final class PackWriterBitmapWalker { } /** - * A RevFilter that adds the visited commits to {@code bitmap} as a side - * effect. - * <p> - * When the walk hits a commit that is part of {@code bitmap}'s - * BitmapIndex, that entire bitmap is ORed into {@code bitmap} and the - * commit and its parents are marked as SEEN so that the walk does not - * have to visit its ancestors. This ensures the walk is very short if - * there is good bitmap coverage. + * Filter that excludes objects already in the given bitmap. */ - static class AddToBitmapFilter extends RevFilter { + static class BitmapObjectFilter extends ObjectFilter { private final BitmapBuilder bitmap; - AddToBitmapFilter(BitmapBuilder bitmap) { + BitmapObjectFilter(BitmapBuilder bitmap) { this.bitmap = bitmap; } @Override - public final boolean include(RevWalk walker, RevCommit cmit) { - Bitmap visitedBitmap; - - if (bitmap.contains(cmit)) { - // already included - } else if ((visitedBitmap = bitmap.getBitmapIndex() - .getBitmap(cmit)) != null) { - bitmap.or(visitedBitmap); - } else { - bitmap.addObject(cmit, Constants.OBJ_COMMIT); - return true; - } - - for (RevCommit p : cmit.getParents()) { - p.add(RevFlag.SEEN); - } - return false; - } - - @Override - public final RevFilter clone() { - throw new UnsupportedOperationException(); - } - - @Override - public final boolean requiresCommitBody() { - return false; - } - } - - /** - * A RevFilter that adds the visited commits to {@code bitmap} as a side - * effect. - * <p> - * When the walk hits a commit that is part of {@code bitmap}'s - * BitmapIndex, that entire bitmap is ORed into {@code bitmap} and the - * commit and its parents are marked as SEEN so that the walk does not - * have to visit its ancestors. This ensures the walk is very short if - * there is good bitmap coverage. - * <p> - * Commits named in {@code seen} are considered already seen. If one is - * encountered, that commit and its parents will be marked with the SEEN - * flag to prevent the walk from visiting its ancestors. - */ - static class AddUnseenToBitmapFilter extends RevFilter { - private final BitmapBuilder seen; - private final BitmapBuilder bitmap; - - AddUnseenToBitmapFilter(BitmapBuilder seen, BitmapBuilder bitmapResult) { - this.seen = seen; - this.bitmap = bitmapResult; - } - - @Override - public final boolean include(RevWalk walker, RevCommit cmit) { - Bitmap visitedBitmap; - - if (seen.contains(cmit) || bitmap.contains(cmit)) { - // already seen or included - } else if ((visitedBitmap = bitmap.getBitmapIndex() - .getBitmap(cmit)) != null) { - bitmap.or(visitedBitmap); - } else { - bitmap.addObject(cmit, Constants.OBJ_COMMIT); - return true; - } - - for (RevCommit p : cmit.getParents()) { - p.add(RevFlag.SEEN); - } - return false; - } - - @Override - public final RevFilter clone() { - throw new UnsupportedOperationException(); - } - - @Override - public final boolean requiresCommitBody() { - return false; + public final boolean include(ObjectWalk walker, AnyObjectId objid) + throws MissingObjectException, IncorrectObjectTypeException, + IOException { + return !bitmap.contains(objid); } } } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/BlockRevQueue.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/BlockRevQueue.java index db5379e507..74a3511088 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/BlockRevQueue.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/BlockRevQueue.java @@ -51,7 +51,9 @@ import org.eclipse.jgit.errors.MissingObjectException; abstract class BlockRevQueue extends AbstractRevQueue { protected BlockFreeList free; - /** Create an empty revision queue. */ + /** + * Create an empty revision queue. + */ protected BlockRevQueue() { free = new BlockFreeList(); } @@ -70,6 +72,8 @@ abstract class BlockRevQueue extends AbstractRevQueue { } /** + * {@inheritDoc} + * <p> * Reconfigure this queue to share the same free list as another. * <p> * Multiple revision queues can be connected to the same free list, making @@ -79,9 +83,6 @@ abstract class BlockRevQueue extends AbstractRevQueue { * <p> * Free lists are not thread-safe. Applications must ensure that all queues * sharing the same free list are doing so from only a single thread. - * - * @param q - * the other queue we will steal entries from. */ @Override public void shareFreeList(final BlockRevQueue q) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/DateRevQueue.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/DateRevQueue.java index cd7c074cce..c993fe50a9 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/DateRevQueue.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/DateRevQueue.java @@ -49,7 +49,9 @@ import java.io.IOException; import org.eclipse.jgit.errors.IncorrectObjectTypeException; import org.eclipse.jgit.errors.MissingObjectException; -/** A queue of commits sorted by commit time order. */ +/** + * A queue of commits sorted by commit time order. + */ public class DateRevQueue extends AbstractRevQueue { private static final int REBUILD_INDEX_COUNT = 1000; @@ -67,7 +69,9 @@ public class DateRevQueue extends AbstractRevQueue { private int last = -1; - /** Create an empty date queue. */ + /** + * Create an empty date queue. + */ public DateRevQueue() { super(); } @@ -82,6 +86,7 @@ public class DateRevQueue extends AbstractRevQueue { } } + /** {@inheritDoc} */ @Override public void add(final RevCommit c) { sinceLastIndex++; @@ -127,6 +132,7 @@ public class DateRevQueue extends AbstractRevQueue { } } + /** {@inheritDoc} */ @Override public RevCommit next() { final Entry q = head; @@ -163,6 +169,7 @@ public class DateRevQueue extends AbstractRevQueue { return head != null ? head.commit : null; } + /** {@inheritDoc} */ @Override public void clear() { head = null; @@ -196,6 +203,7 @@ public class DateRevQueue extends AbstractRevQueue { return outputType | SORT_COMMIT_TIME_DESC; } + /** {@inheritDoc} */ @Override public String toString() { final StringBuilder s = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/DepthWalk.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/DepthWalk.java index f932593e82..06a5272b98 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/DepthWalk.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/DepthWalk.java @@ -52,15 +52,30 @@ import org.eclipse.jgit.lib.AnyObjectId; import org.eclipse.jgit.lib.ObjectReader; import org.eclipse.jgit.lib.Repository; -/** Interface for revision walkers that perform depth filtering. */ +/** + * Interface for revision walkers that perform depth filtering. + */ public interface DepthWalk { - /** @return Depth to filter to. */ + /** + * Get depth to filter to. + * + * @return Depth to filter to. + */ public int getDepth(); /** @return flag marking commits that should become unshallow. */ + /** + * Get flag marking commits that should become unshallow. + * + * @return flag marking commits that should become unshallow. + */ public RevFlag getUnshallowFlag(); - /** @return flag marking commits that are interesting again. */ + /** + * Get flag marking commits that are interesting again. + * + * @return flag marking commits that are interesting again. + */ public RevFlag getReinterestingFlag(); /** RevCommit with a depth (in commits) from a root. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FIFORevQueue.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FIFORevQueue.java index 14156042c8..63b7990600 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FIFORevQueue.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FIFORevQueue.java @@ -48,13 +48,17 @@ import java.io.IOException; import org.eclipse.jgit.errors.IncorrectObjectTypeException; import org.eclipse.jgit.errors.MissingObjectException; -/** A queue of commits in FIFO order. */ +/** + * A queue of commits in FIFO order. + */ public class FIFORevQueue extends BlockRevQueue { private Block head; private Block tail; - /** Create an empty FIFO queue. */ + /** + * Create an empty FIFO queue. + */ public FIFORevQueue() { super(); } @@ -64,6 +68,7 @@ public class FIFORevQueue extends BlockRevQueue { super(s); } + /** {@inheritDoc} */ @Override public void add(final RevCommit c) { Block b = tail; @@ -108,6 +113,7 @@ public class FIFORevQueue extends BlockRevQueue { head = b; } + /** {@inheritDoc} */ @Override public RevCommit next() { final Block b = head; @@ -124,6 +130,7 @@ public class FIFORevQueue extends BlockRevQueue { return c; } + /** {@inheritDoc} */ @Override public void clear() { head = null; @@ -159,6 +166,7 @@ public class FIFORevQueue extends BlockRevQueue { } } + /** {@inheritDoc} */ @Override public String toString() { final StringBuilder s = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FollowFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FollowFilter.java index 9928286dcd..2da97c891b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FollowFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FollowFilter.java @@ -59,7 +59,8 @@ import org.eclipse.jgit.treewalk.filter.TreeFilter; * triggers rename detection so that the path node is updated to include a prior * file name as the RevWalk traverses history. * - * The renames found will be reported to a {@link RenameCallback} if one is set. + * The renames found will be reported to a + * {@link org.eclipse.jgit.revwalk.RenameCallback} if one is set. * <p> * Results with this filter are unpredictable if the path being followed is a * subdirectory. @@ -81,7 +82,7 @@ public class FollowFilter extends TreeFilter { * @param cfg * diff config specifying rename detection options. * @return a new filter for the requested path. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * the path supplied was the empty string. * @since 3.0 */ @@ -100,10 +101,16 @@ public class FollowFilter extends TreeFilter { } /** @return the path this filter matches. */ + /** + * Get the path this filter matches. + * + * @return the path this filter matches. + */ public String getPath() { return path.getPath(); } + /** {@inheritDoc} */ @Override public boolean include(final TreeWalk walker) throws MissingObjectException, IncorrectObjectTypeException, @@ -111,16 +118,19 @@ public class FollowFilter extends TreeFilter { return path.include(walker) && ANY_DIFF.include(walker); } + /** {@inheritDoc} */ @Override public boolean shouldBeRecursive() { return path.shouldBeRecursive() || ANY_DIFF.shouldBeRecursive(); } + /** {@inheritDoc} */ @Override public TreeFilter clone() { return new FollowFilter(path.clone(), cfg); } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { @@ -130,6 +140,8 @@ public class FollowFilter extends TreeFilter { } /** + * Get the callback to which renames are reported. + * * @return the callback to which renames are reported, or <code>null</code> * if none */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FooterKey.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FooterKey.java index 36965f4996..360be298e3 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FooterKey.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FooterKey.java @@ -47,7 +47,9 @@ import java.util.Locale; import org.eclipse.jgit.lib.Constants; -/** Case insensitive key for a {@link FooterLine}. */ +/** + * Case insensitive key for a {@link org.eclipse.jgit.revwalk.FooterLine}. + */ public final class FooterKey { /** Standard {@code Signed-off-by} */ public static final FooterKey SIGNED_OFF_BY = new FooterKey("Signed-off-by"); //$NON-NLS-1$ @@ -73,11 +75,16 @@ public final class FooterKey { raw = Constants.encode(keyName.toLowerCase(Locale.ROOT)); } - /** @return name of this footer line. */ + /** + * Get name of this footer line. + * + * @return name of this footer line. + */ public String getName() { return name; } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FooterLine.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FooterLine.java index b061d6ae13..074ce8275c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FooterLine.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/FooterLine.java @@ -80,6 +80,8 @@ public final class FooterLine { } /** + * Whether keys match + * * @param key * key to test this line's key name against. * @return true if {@code key.getName().equalsIgnorecase(getKey())}. @@ -101,6 +103,8 @@ public final class FooterLine { } /** + * Get key name of this footer. + * * @return key name of this footer; that is the text before the ":" on the * line footer's line. The text is decoded according to the commit's * specified (or assumed) character encoding. @@ -110,6 +114,8 @@ public final class FooterLine { } /** + * Get value of this footer. + * * @return value of this footer; that is the text after the ":" and any * leading whitespace has been skipped. May be the empty string if * the footer has no value (line ended with ":"). The text is @@ -144,6 +150,7 @@ public final class FooterLine { return RawParseUtils.decode(enc, buffer, lt, gt - 1); } + /** {@inheritDoc} */ @Override public String toString() { return getKey() + ": " + getValue(); //$NON-NLS-1$ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/LIFORevQueue.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/LIFORevQueue.java index f9da5b17ba..f734b693ef 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/LIFORevQueue.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/LIFORevQueue.java @@ -49,11 +49,15 @@ import java.io.IOException; import org.eclipse.jgit.errors.IncorrectObjectTypeException; import org.eclipse.jgit.errors.MissingObjectException; -/** A queue of commits in LIFO order. */ +/** + * A queue of commits in LIFO order. + */ public class LIFORevQueue extends BlockRevQueue { private Block head; - /** Create an empty LIFO queue. */ + /** + * Create an empty LIFO queue. + */ public LIFORevQueue() { super(); } @@ -63,6 +67,7 @@ public class LIFORevQueue extends BlockRevQueue { super(s); } + /** {@inheritDoc} */ @Override public void add(final RevCommit c) { Block b = head; @@ -75,6 +80,7 @@ public class LIFORevQueue extends BlockRevQueue { b.unpop(c); } + /** {@inheritDoc} */ @Override public RevCommit next() { final Block b = head; @@ -89,6 +95,7 @@ public class LIFORevQueue extends BlockRevQueue { return c; } + /** {@inheritDoc} */ @Override public void clear() { head = null; @@ -115,6 +122,7 @@ public class LIFORevQueue extends BlockRevQueue { return false; } + /** {@inheritDoc} */ @Override public String toString() { final StringBuilder s = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/ObjectWalk.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/ObjectWalk.java index 58689981b5..25c3e1224e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/ObjectWalk.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/ObjectWalk.java @@ -76,8 +76,9 @@ import org.eclipse.jgit.util.RawParseUtils; * scheduled for inclusion in the results of {@link #nextObject()}, returning * each object exactly once. Objects are sorted and returned according to the * the commits that reference them and the order they appear within a tree. - * Ordering can be affected by changing the {@link RevSort} used to order the - * commits that are returned first. + * Ordering can be affected by changing the + * {@link org.eclipse.jgit.revwalk.RevSort} used to order the commits that are + * returned first. */ public class ObjectWalk extends RevWalk { private static final int ID_SZ = 20; @@ -142,34 +143,39 @@ public class ObjectWalk extends RevWalk { /** * Mark an object or commit to start graph traversal from. * <p> - * Callers are encouraged to use {@link RevWalk#parseAny(AnyObjectId)} - * instead of {@link RevWalk#lookupAny(AnyObjectId, int)}, as this method - * requires the object to be parsed before it can be added as a root for the - * traversal. + * Callers are encouraged to use + * {@link org.eclipse.jgit.revwalk.RevWalk#parseAny(AnyObjectId)} instead of + * {@link org.eclipse.jgit.revwalk.RevWalk#lookupAny(AnyObjectId, int)}, as + * this method requires the object to be parsed before it can be added as a + * root for the traversal. * <p> * The method will automatically parse an unparsed object, but error * handling may be more difficult for the application to explain why a * RevObject is not actually valid. The object pool of this walker would * also be 'poisoned' by the invalid RevObject. * <p> - * This method will automatically call {@link RevWalk#markStart(RevCommit)} - * if passed RevCommit instance, or a RevTag that directly (or indirectly) - * references a RevCommit. + * This method will automatically call + * {@link org.eclipse.jgit.revwalk.RevWalk#markStart(RevCommit)} if passed + * RevCommit instance, or a RevTag that directly (or indirectly) references + * a RevCommit. * * @param o * the object to start traversing from. The object passed must be * from this same revision walker. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the object supplied is not available from the object * database. This usually indicates the supplied object is * invalid, but the reference was constructed during an earlier - * invocation to {@link RevWalk#lookupAny(AnyObjectId, int)}. - * @throws IncorrectObjectTypeException + * invocation to + * {@link org.eclipse.jgit.revwalk.RevWalk#lookupAny(AnyObjectId, int)}. + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the object was not parsed yet and it was discovered during * parsing that it is not actually the type of the instance * passed in. This usually indicates the caller used the wrong - * type in a {@link RevWalk#lookupAny(AnyObjectId, int)} call. - * @throws IOException + * type in a + * {@link org.eclipse.jgit.revwalk.RevWalk#lookupAny(AnyObjectId, int)} + * call. + * @throws java.io.IOException * a pack file or loose object could not be read. */ public void markStart(RevObject o) throws MissingObjectException, @@ -193,33 +199,38 @@ public class ObjectWalk extends RevWalk { * reachable chain, back until the merge base of an uninteresting commit and * an otherwise interesting commit. * <p> - * Callers are encouraged to use {@link RevWalk#parseAny(AnyObjectId)} - * instead of {@link RevWalk#lookupAny(AnyObjectId, int)}, as this method - * requires the object to be parsed before it can be added as a root for the - * traversal. + * Callers are encouraged to use + * {@link org.eclipse.jgit.revwalk.RevWalk#parseAny(AnyObjectId)} instead of + * {@link org.eclipse.jgit.revwalk.RevWalk#lookupAny(AnyObjectId, int)}, as + * this method requires the object to be parsed before it can be added as a + * root for the traversal. * <p> * The method will automatically parse an unparsed object, but error * handling may be more difficult for the application to explain why a * RevObject is not actually valid. The object pool of this walker would * also be 'poisoned' by the invalid RevObject. * <p> - * This method will automatically call {@link RevWalk#markStart(RevCommit)} - * if passed RevCommit instance, or a RevTag that directly (or indirectly) - * references a RevCommit. + * This method will automatically call + * {@link org.eclipse.jgit.revwalk.RevWalk#markStart(RevCommit)} if passed + * RevCommit instance, or a RevTag that directly (or indirectly) references + * a RevCommit. * * @param o * the object to start traversing from. The object passed must be - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the object supplied is not available from the object * database. This usually indicates the supplied object is * invalid, but the reference was constructed during an earlier - * invocation to {@link RevWalk#lookupAny(AnyObjectId, int)}. - * @throws IncorrectObjectTypeException + * invocation to + * {@link org.eclipse.jgit.revwalk.RevWalk#lookupAny(AnyObjectId, int)}. + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the object was not parsed yet and it was discovered during * parsing that it is not actually the type of the instance * passed in. This usually indicates the caller used the wrong - * type in a {@link RevWalk#lookupAny(AnyObjectId, int)} call. - * @throws IOException + * type in a + * {@link org.eclipse.jgit.revwalk.RevWalk#lookupAny(AnyObjectId, int)} + * call. + * @throws java.io.IOException * a pack file or loose object could not be read. */ public void markUninteresting(RevObject o) throws MissingObjectException, @@ -243,12 +254,14 @@ public class ObjectWalk extends RevWalk { addObject(o); } + /** {@inheritDoc} */ @Override public void sort(RevSort s) { super.sort(s); boundary = hasRevSort(RevSort.BOUNDARY); } + /** {@inheritDoc} */ @Override public void sort(RevSort s, boolean use) { super.sort(s, use); @@ -259,7 +272,6 @@ public class ObjectWalk extends RevWalk { * Get the currently configured object filter. * * @return the current filter. Never null as a filter is always needed. - * * @since 4.0 */ public ObjectFilter getObjectFilter() { @@ -267,9 +279,9 @@ public class ObjectWalk extends RevWalk { } /** - * Set the object filter for this walker. This filter affects the objects - * visited by {@link #nextObject()}. It does not affect the commits - * listed by {@link #next()}. + * Set the object filter for this walker. This filter affects the objects + * visited by {@link #nextObject()}. It does not affect the commits listed + * by {@link #next()}. * <p> * If the filter returns false for an object, then that object is skipped * and objects reachable from it are not enqueued to be walked recursively. @@ -277,9 +289,9 @@ public class ObjectWalk extends RevWalk { * are known to be uninteresting. * * @param newFilter - * the new filter. If null the special {@link ObjectFilter#ALL} + * the new filter. If null the special + * {@link org.eclipse.jgit.revwalk.filter.ObjectFilter#ALL} * filter will be used instead, as it matches every object. - * * @since 4.0 */ public void setObjectFilter(ObjectFilter newFilter) { @@ -287,6 +299,7 @@ public class ObjectWalk extends RevWalk { objectFilter = newFilter != null ? newFilter : ObjectFilter.ALL; } + /** {@inheritDoc} */ @Override public RevCommit next() throws MissingObjectException, IncorrectObjectTypeException, IOException { @@ -316,14 +329,14 @@ public class ObjectWalk extends RevWalk { * Pop the next most recent object. * * @return next most recent object; null if traversal is over. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * one or or more of the next objects are not available from the * object database, but were thought to be candidates for * traversal. This usually indicates a broken link. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * one or or more of the objects in a tree do not match the type * indicated. - * @throws IOException + * @throws java.io.IOException * a pack file or loose object could not be read. */ public RevObject nextObject() throws MissingObjectException, @@ -520,14 +533,14 @@ public class ObjectWalk extends RevWalk { * exception if there is a connectivity problem. The exception message * provides some detail about the connectivity failure. * - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * one or or more of the next objects are not available from the * object database, but were thought to be candidates for * traversal. This usually indicates a broken link. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * one or or more of the objects in a tree do not match the type * indicated. - * @throws IOException + * @throws java.io.IOException * a pack file or loose object could not be read. */ public void checkConnectivity() throws MissingObjectException, @@ -618,14 +631,22 @@ public class ObjectWalk extends RevWalk { return hash; } - /** @return the internal buffer holding the current path. */ + /** + * Get the internal buffer holding the current path. + * + * @return the internal buffer holding the current path. + */ public byte[] getPathBuffer() { if (pathLen == 0) pathLen = updatePathBuf(currVisit); return pathBuf; } - /** @return length of the path in {@link #getPathBuffer()}. */ + /** + * Get length of the path in {@link #getPathBuffer()}. + * + * @return length of the path in {@link #getPathBuffer()}. + */ public int getPathLength() { if (pathLen == 0) pathLen = updatePathBuf(currVisit); @@ -667,6 +688,7 @@ public class ObjectWalk extends RevWalk { pathBuf = newBuf; } + /** {@inheritDoc} */ @Override public void dispose() { super.dispose(); @@ -675,6 +697,7 @@ public class ObjectWalk extends RevWalk { freeVisit = null; } + /** {@inheritDoc} */ @Override protected void reset(final int retainFlags) { super.reset(retainFlags); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RenameCallback.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RenameCallback.java index 377835534e..7754f18e9a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RenameCallback.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RenameCallback.java @@ -46,8 +46,9 @@ import org.eclipse.jgit.diff.DiffEntry; /** * An instance of this class can be used in conjunction with a - * {@link FollowFilter}. Whenever a rename has been detected during a revision - * walk, it will be reported here. + * {@link org.eclipse.jgit.revwalk.FollowFilter}. Whenever a rename has been + * detected during a revision walk, it will be reported here. + * * @see FollowFilter#setRenameCallback(RenameCallback) */ public abstract class RenameCallback { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevBlob.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevBlob.java index 4245fcab94..d3529292e6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevBlob.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevBlob.java @@ -52,7 +52,9 @@ import org.eclipse.jgit.errors.MissingObjectException; import org.eclipse.jgit.lib.AnyObjectId; import org.eclipse.jgit.lib.Constants; -/** A binary file, or a symbolic link. */ +/** + * A binary file, or a symbolic link. + */ public class RevBlob extends RevObject { /** * Create a new blob reference. @@ -64,6 +66,7 @@ public class RevBlob extends RevObject { super(id); } + /** {@inheritDoc} */ @Override public final int getType() { return Constants.OBJ_BLOB; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevCommit.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevCommit.java index c641a13311..9db146706f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevCommit.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevCommit.java @@ -66,7 +66,9 @@ import org.eclipse.jgit.lib.PersonIdent; import org.eclipse.jgit.util.RawParseUtils; import org.eclipse.jgit.util.StringUtils; -/** A commit reference to a commit in the DAG. */ +/** + * A commit reference to a commit in the DAG. + */ public class RevCommit extends RevObject { private static final int STACK_DEPTH = 500; @@ -79,7 +81,8 @@ public class RevCommit extends RevObject { * will not have their headers loaded. * * Applications are discouraged from using this API. Callers usually need - * more than one commit. Use {@link RevWalk#parseCommit(AnyObjectId)} to + * more than one commit. Use + * {@link org.eclipse.jgit.revwalk.RevWalk#parseCommit(AnyObjectId)} to * obtain a RevCommit from an existing repository. * * @param raw @@ -115,7 +118,7 @@ public class RevCommit extends RevObject { * modified by the caller. * @return the parsed commit, in an isolated revision pool that is not * available to the caller. - * @throws IOException + * @throws java.io.IOException * in case of RevWalk initialization fails */ public static RevCommit parse(RevWalk rw, byte[] raw) throws IOException { @@ -220,6 +223,7 @@ public class RevCommit extends RevObject { flags |= PARSED; } + /** {@inheritDoc} */ @Override public final int getType() { return Constants.OBJ_COMMIT; @@ -315,7 +319,7 @@ public class RevCommit extends RevObject { /** * Time from the "committer " line of the buffer. * - * @return time, expressed as seconds since the epoch. + * @return commit time */ public final int getCommitTime() { return commitTime; @@ -346,7 +350,7 @@ public class RevCommit extends RevObject { * parent index to obtain. Must be in the range 0 through * {@link #getParentCount()}-1. * @return the specified parent. - * @throws ArrayIndexOutOfBoundsException + * @throws java.lang.ArrayIndexOutOfBoundsException * an invalid parent index was specified. */ public final RevCommit getParent(final int nth) { @@ -394,9 +398,10 @@ public class RevCommit extends RevObject { * should cache the return value for as long as necessary to use all * information from it. * <p> - * RevFilter implementations should try to use {@link RawParseUtils} to scan - * the {@link #getRawBuffer()} instead, as this will allow faster evaluation - * of commits. + * RevFilter implementations should try to use + * {@link org.eclipse.jgit.util.RawParseUtils} to scan the + * {@link #getRawBuffer()} instead, as this will allow faster evaluation of + * commits. * * @return identity of the author (name, email) and the time the commit was * made by the author; null if no author line was found. @@ -420,9 +425,10 @@ public class RevCommit extends RevObject { * should cache the return value for as long as necessary to use all * information from it. * <p> - * RevFilter implementations should try to use {@link RawParseUtils} to scan - * the {@link #getRawBuffer()} instead, as this will allow faster evaluation - * of commits. + * RevFilter implementations should try to use + * {@link org.eclipse.jgit.util.RawParseUtils} to scan the + * {@link #getRawBuffer()} instead, as this will allow faster evaluation of + * commits. * * @return identity of the committer (name, email) and the time the commit * was made by the committer; null if no committer line was found. @@ -654,7 +660,7 @@ public class RevCommit extends RevObject { * time in {@link #getCommitTime()}. Accessing other properties such as * {@link #getAuthorIdent()}, {@link #getCommitterIdent()} or either message * function requires reloading the buffer by invoking - * {@link RevWalk#parseBody(RevObject)}. + * {@link org.eclipse.jgit.revwalk.RevWalk#parseBody(RevObject)}. * * @since 4.0 */ @@ -662,6 +668,7 @@ public class RevCommit extends RevObject { buffer = null; } + /** {@inheritDoc} */ @Override public String toString() { final StringBuilder s = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevCommitList.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevCommitList.java index 64f99bbd28..38cf3f510a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevCommitList.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevCommitList.java @@ -50,7 +50,7 @@ import org.eclipse.jgit.errors.MissingObjectException; import org.eclipse.jgit.revwalk.filter.RevFilter; /** - * An ordered list of {@link RevCommit} subclasses. + * An ordered list of {@link org.eclipse.jgit.revwalk.RevCommit} subclasses. * * @param <E> * type of subclass of RevCommit the list is storing. @@ -58,6 +58,7 @@ import org.eclipse.jgit.revwalk.filter.RevFilter; public class RevCommitList<E extends RevCommit> extends RevObjectList<E> { private RevWalk walker; + /** {@inheritDoc} */ @Override public void clear() { super.clear(); @@ -77,15 +78,15 @@ public class RevCommitList<E extends RevCommit> extends RevObjectList<E> { * @param flag * the flag to apply (or remove). Applications are responsible * for allocating this flag from the source RevWalk. - * @throws IOException + * @throws java.io.IOException * revision filter needed to read additional objects, but an * error occurred while reading the pack files or loose objects * of the repository. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * revision filter needed to read additional objects, but an * object was not of the correct type. Repository corruption may * have occurred. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * revision filter needed to read additional objects, but an * object that should be present was not found. Repository * corruption may have occurred. @@ -117,15 +118,15 @@ public class RevCommitList<E extends RevCommit> extends RevObjectList<E> { * last commit within the list to end testing at, exclusive. If * smaller than or equal to <code>rangeBegin</code> then no * commits will be tested. - * @throws IOException + * @throws java.io.IOException * revision filter needed to read additional objects, but an * error occurred while reading the pack files or loose objects * of the repository. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * revision filter needed to read additional objects, but an * object was not of the correct type. Repository corruption may * have occurred. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * revision filter needed to read additional objects, but an * object that should be present was not found. Repository * corruption may have occurred. @@ -290,12 +291,12 @@ public class RevCommitList<E extends RevCommit> extends RevObjectList<E> { * @param highMark * number of commits the caller wants this list to contain when * the fill operation is complete. - * @throws IOException - * see {@link RevWalk#next()} - * @throws IncorrectObjectTypeException - * see {@link RevWalk#next()} - * @throws MissingObjectException - * see {@link RevWalk#next()} + * @throws java.io.IOException + * see {@link org.eclipse.jgit.revwalk.RevWalk#next()} + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException + * see {@link org.eclipse.jgit.revwalk.RevWalk#next()} + * @throws org.eclipse.jgit.errors.MissingObjectException + * see {@link org.eclipse.jgit.revwalk.RevWalk#next()} */ @SuppressWarnings("unchecked") public void fillTo(final int highMark) throws MissingObjectException, @@ -355,12 +356,12 @@ public class RevCommitList<E extends RevCommit> extends RevObjectList<E> { * contain when the fill operation is complete. If highMark is 0 * the walk is pumped until the specified commit or the end of * the walk is reached. - * @throws IOException - * see {@link RevWalk#next()} - * @throws IncorrectObjectTypeException - * see {@link RevWalk#next()} - * @throws MissingObjectException - * see {@link RevWalk#next()} + * @throws java.io.IOException + * see {@link org.eclipse.jgit.revwalk.RevWalk#next()} + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException + * see {@link org.eclipse.jgit.revwalk.RevWalk#next()} + * @throws org.eclipse.jgit.errors.MissingObjectException + * see {@link org.eclipse.jgit.revwalk.RevWalk#next()} */ @SuppressWarnings("unchecked") public void fillTo(final RevCommit commitToLoad, int highMark) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevFlag.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevFlag.java index dae52f85db..1e79867425 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevFlag.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevFlag.java @@ -48,9 +48,10 @@ import java.text.MessageFormat; import org.eclipse.jgit.internal.JGitText; /** - * Application level mark bit for {@link RevObject}s. + * Application level mark bit for {@link org.eclipse.jgit.revwalk.RevObject}s. * <p> - * To create a flag use {@link RevWalk#newFlag(String)}. + * To create a flag use + * {@link org.eclipse.jgit.revwalk.RevWalk#newFlag(String)}. */ public class RevFlag { /** @@ -99,6 +100,7 @@ public class RevFlag { return walker; } + /** {@inheritDoc} */ @Override public String toString() { return name; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevFlagSet.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevFlagSet.java index bb699e08c4..9740d1417d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevFlagSet.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevFlagSet.java @@ -50,7 +50,8 @@ import java.util.Iterator; import java.util.List; /** - * Multiple application level mark bits for {@link RevObject}s. + * Multiple application level mark bits for + * {@link org.eclipse.jgit.revwalk.RevObject}s. * * @see RevFlag */ @@ -59,7 +60,9 @@ public class RevFlagSet extends AbstractSet<RevFlag> { private final List<RevFlag> active; - /** Create an empty set of flags. */ + /** + * Create an empty set of flags. + */ public RevFlagSet() { active = new ArrayList<>(); } @@ -86,6 +89,7 @@ public class RevFlagSet extends AbstractSet<RevFlag> { addAll(s); } + /** {@inheritDoc} */ @Override public boolean contains(final Object o) { if (o instanceof RevFlag) @@ -93,6 +97,7 @@ public class RevFlagSet extends AbstractSet<RevFlag> { return false; } + /** {@inheritDoc} */ @Override public boolean containsAll(final Collection<?> c) { if (c instanceof RevFlagSet) { @@ -102,6 +107,7 @@ public class RevFlagSet extends AbstractSet<RevFlag> { return super.containsAll(c); } + /** {@inheritDoc} */ @Override public boolean add(final RevFlag flag) { if ((mask & flag.mask) != 0) @@ -114,6 +120,7 @@ public class RevFlagSet extends AbstractSet<RevFlag> { return true; } + /** {@inheritDoc} */ @Override public boolean remove(final Object o) { final RevFlag flag = (RevFlag) o; @@ -126,6 +133,7 @@ public class RevFlagSet extends AbstractSet<RevFlag> { return true; } + /** {@inheritDoc} */ @Override public Iterator<RevFlag> iterator() { final Iterator<RevFlag> i = active.iterator(); @@ -150,6 +158,7 @@ public class RevFlagSet extends AbstractSet<RevFlag> { }; } + /** {@inheritDoc} */ @Override public int size() { return active.size(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevObject.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevObject.java index 7561927dff..4a88105d10 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevObject.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevObject.java @@ -52,7 +52,9 @@ import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.lib.ObjectIdOwnerMap; -/** Base object type accessed during revision walking. */ +/** + * Base object type accessed during revision walking. + */ public abstract class RevObject extends ObjectIdOwnerMap.Entry { static final int PARSED = 1; @@ -69,7 +71,7 @@ public abstract class RevObject extends ObjectIdOwnerMap.Entry { IncorrectObjectTypeException, IOException; /** - * Get Git object type. See {@link Constants}. + * Get Git object type. See {@link org.eclipse.jgit.lib.Constants}. * * @return object type */ @@ -163,6 +165,7 @@ public abstract class RevObject extends ObjectIdOwnerMap.Entry { flags &= ~set.mask; } + /** {@inheritDoc} */ @Override public String toString() { final StringBuilder s = new StringBuilder(); @@ -175,6 +178,8 @@ public abstract class RevObject extends ObjectIdOwnerMap.Entry { } /** + * Append a debug description of core RevFlags to a buffer. + * * @param s * buffer to append a debug description of core RevFlags onto. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevObjectList.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevObjectList.java index 95986782cd..2bb4427181 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevObjectList.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevObjectList.java @@ -51,7 +51,7 @@ import java.util.AbstractList; import org.eclipse.jgit.internal.JGitText; /** - * An ordered list of {@link RevObject} subclasses. + * An ordered list of {@link org.eclipse.jgit.revwalk.RevObject} subclasses. * * @param <E> * type of subclass of RevObject the list is storing. @@ -73,11 +73,14 @@ public class RevObjectList<E extends RevObject> extends AbstractList<E> { /** Current number of elements in the list. */ protected int size = 0; - /** Create an empty object list. */ + /** + * Create an empty object list. + */ public RevObjectList() { // Initialized above. } + /** {@inheritDoc} */ @Override public void add(final int index, final E element) { if (index != size) @@ -88,6 +91,7 @@ public class RevObjectList<E extends RevObject> extends AbstractList<E> { size++; } + /** {@inheritDoc} */ @Override @SuppressWarnings("unchecked") public E set(int index, E element) { @@ -109,6 +113,7 @@ public class RevObjectList<E extends RevObject> extends AbstractList<E> { return (E) old; } + /** {@inheritDoc} */ @Override @SuppressWarnings("unchecked") public E get(int index) { @@ -123,11 +128,13 @@ public class RevObjectList<E extends RevObject> extends AbstractList<E> { return s != null ? (E) s.contents[index] : null; } + /** {@inheritDoc} */ @Override public int size() { return size; } + /** {@inheritDoc} */ @Override public void clear() { contents = new Block(0); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevSort.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevSort.java index 238af12fdb..a3b31a1922 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevSort.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevSort.java @@ -44,7 +44,10 @@ package org.eclipse.jgit.revwalk; -/** Sorting strategies supported by {@link RevWalk} and {@link ObjectWalk}. */ +/** + * Sorting strategies supported by {@link org.eclipse.jgit.revwalk.RevWalk} and + * {@link org.eclipse.jgit.revwalk.ObjectWalk}. + */ public enum RevSort { /** * No specific sorting is requested. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevTag.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevTag.java index 81a54bf7ea..d74837e860 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevTag.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevTag.java @@ -64,7 +64,9 @@ import org.eclipse.jgit.util.MutableInteger; import org.eclipse.jgit.util.RawParseUtils; import org.eclipse.jgit.util.StringUtils; -/** An annotated tag. */ +/** + * An annotated tag. + */ public class RevTag extends RevObject { /** * Parse an annotated tag from its canonical format. @@ -75,14 +77,15 @@ public class RevTag extends RevObject { * not have its headers loaded. * * Applications are discouraged from using this API. Callers usually need - * more than one object. Use {@link RevWalk#parseTag(AnyObjectId)} to obtain + * more than one object. Use + * {@link org.eclipse.jgit.revwalk.RevWalk#parseTag(AnyObjectId)} to obtain * a RevTag from an existing repository. * * @param raw * the canonical formatted tag to be parsed. * @return the parsed tag, in an isolated revision pool that is not * available to the caller. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the tag contains a malformed header that cannot be handled. */ public static RevTag parse(byte[] raw) throws CorruptObjectException { @@ -109,7 +112,7 @@ public class RevTag extends RevObject { * modified by the caller. * @return the parsed tag, in an isolated revision pool that is not * available to the caller. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the tag contains a malformed header that cannot be handled. */ public static RevTag parse(RevWalk rw, byte[] raw) @@ -173,6 +176,7 @@ public class RevTag extends RevObject { flags |= PARSED; } + /** {@inheritDoc} */ @Override public final int getType() { return Constants.OBJ_TAG; @@ -261,12 +265,15 @@ public class RevTag extends RevObject { * Get a reference to the object this tag was placed on. * <p> * Note that the returned object has only been looked up (see - * {@link RevWalk#lookupAny(AnyObjectId, int)}. To access the contents it - * needs to be parsed, see {@link RevWalk#parseHeaders(RevObject)} and - * {@link RevWalk#parseBody(RevObject)}. + * {@link org.eclipse.jgit.revwalk.RevWalk#lookupAny(AnyObjectId, int)}. To + * access the contents it needs to be parsed, see + * {@link org.eclipse.jgit.revwalk.RevWalk#parseHeaders(RevObject)} and + * {@link org.eclipse.jgit.revwalk.RevWalk#parseBody(RevObject)}. * <p> - * As an alternative, use {@link RevWalk#peel(RevObject)} and pass this - * {@link RevTag} to peel it until the first non-tag object. + * As an alternative, use + * {@link org.eclipse.jgit.revwalk.RevWalk#peel(RevObject)} and pass this + * {@link org.eclipse.jgit.revwalk.RevTag} to peel it until the first + * non-tag object. * * @return object this tag refers to (only looked up, not parsed) */ @@ -290,7 +297,7 @@ public class RevTag extends RevObject { * only the {@link #getObject()} pointer and {@link #getTagName()}. * Accessing other properties such as {@link #getTaggerIdent()} or either * message function requires reloading the buffer by invoking - * {@link RevWalk#parseBody(RevObject)}. + * {@link org.eclipse.jgit.revwalk.RevWalk#parseBody(RevObject)}. * * @since 4.0 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevTree.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevTree.java index d37040903e..92b81a17d6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevTree.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevTree.java @@ -52,7 +52,9 @@ import org.eclipse.jgit.errors.MissingObjectException; import org.eclipse.jgit.lib.AnyObjectId; import org.eclipse.jgit.lib.Constants; -/** A reference to a tree of subtrees/files. */ +/** + * A reference to a tree of subtrees/files. + */ public class RevTree extends RevObject { /** * Create a new tree reference. @@ -64,6 +66,7 @@ public class RevTree extends RevObject { super(id); } + /** {@inheritDoc} */ @Override public final int getType() { return Constants.OBJ_TREE; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevWalk.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevWalk.java index 320f05f440..5568241b67 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevWalk.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevWalk.java @@ -84,10 +84,12 @@ import org.eclipse.jgit.treewalk.filter.TreeFilter; * usage of a RevWalk instance to a single thread, or implement their own * synchronization at a higher level. * <p> - * Multiple simultaneous RevWalk instances per {@link Repository} are permitted, - * even from concurrent threads. Equality of {@link RevCommit}s from two - * different RevWalk instances is never true, even if their {@link ObjectId}s - * are equal (and thus they describe the same commit). + * Multiple simultaneous RevWalk instances per + * {@link org.eclipse.jgit.lib.Repository} are permitted, even from concurrent + * threads. Equality of {@link org.eclipse.jgit.revwalk.RevCommit}s from two + * different RevWalk instances is never true, even if their + * {@link org.eclipse.jgit.lib.ObjectId}s are equal (and thus they describe the + * same commit). * <p> * The offered iterator is over the list of RevCommits described by the * configuration of this instance. Applications should restrict themselves to @@ -236,12 +238,18 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { this.closeReader = closeReader; } - /** @return the reader this walker is using to load objects. */ + /** + * Get the reader this walker is using to load objects. + * + * @return the reader this walker is using to load objects. + */ public ObjectReader getObjectReader() { return reader; } /** + * {@inheritDoc} + * <p> * Release any resources used by this walker's reader. * <p> * A walker that has been released can be used again, but may need to be @@ -272,17 +280,17 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { * @param c * the commit to start traversing from. The commit passed must be * from this same revision walker. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the commit supplied is not available from the object * database. This usually indicates the supplied commit is * invalid, but the reference was constructed during an earlier * invocation to {@link #lookupCommit(AnyObjectId)}. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the object was not parsed yet and it was discovered during * parsing that it is not actually a commit. This usually * indicates the caller supplied a non-commit SHA-1 to * {@link #lookupCommit(AnyObjectId)}. - * @throws IOException + * @throws java.io.IOException * a pack file or loose object could not be read. */ public void markStart(final RevCommit c) throws MissingObjectException, @@ -302,17 +310,17 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { * @param list * commits to start traversing from. The commits passed must be * from this same revision walker. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * one of the commits supplied is not available from the object * database. This usually indicates the supplied commit is * invalid, but the reference was constructed during an earlier * invocation to {@link #lookupCommit(AnyObjectId)}. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the object was not parsed yet and it was discovered during * parsing that it is not actually a commit. This usually * indicates the caller supplied a non-commit SHA-1 to * {@link #lookupCommit(AnyObjectId)}. - * @throws IOException + * @throws java.io.IOException * a pack file or loose object could not be read. */ public void markStart(final Collection<RevCommit> list) @@ -342,17 +350,17 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { * @param c * the commit to start traversing from. The commit passed must be * from this same revision walker. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the commit supplied is not available from the object * database. This usually indicates the supplied commit is * invalid, but the reference was constructed during an earlier * invocation to {@link #lookupCommit(AnyObjectId)}. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the object was not parsed yet and it was discovered during * parsing that it is not actually a commit. This usually * indicates the caller supplied a non-commit SHA-1 to * {@link #lookupCommit(AnyObjectId)}. - * @throws IOException + * @throws java.io.IOException * a pack file or loose object could not be read. */ public void markUninteresting(final RevCommit c) @@ -383,14 +391,14 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { * @return true if there is a path directly from <code>tip</code> to * <code>base</code> (and thus <code>base</code> is fully merged * into <code>tip</code>); false otherwise. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * one or or more of the next commit's parents are not available * from the object database, but were thought to be candidates * for traversal. This usually indicates a broken link. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * one or or more of the next commit's parents are not actually * commit objects. - * @throws IOException + * @throws java.io.IOException * a pack file or loose object could not be read. */ public boolean isMergedInto(final RevCommit base, final RevCommit tip) @@ -420,14 +428,14 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { * Pop the next most recent commit. * * @return next most recent commit; null if traversal is over. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * one or or more of the next commit's parents are not available * from the object database, but were thought to be candidates * for traversal. This usually indicates a broken link. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * one or or more of the next commit's parents are not actually * commit objects. - * @throws IOException + * @throws java.io.IOException * a pack file or loose object could not be read. */ public RevCommit next() throws MissingObjectException, @@ -439,7 +447,8 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { * Obtain the sort types applied to the commits returned. * * @return the sorting strategies employed. At least one strategy is always - * used, but that strategy may be {@link RevSort#NONE}. + * used, but that strategy may be + * {@link org.eclipse.jgit.revwalk.RevSort#NONE}. */ public EnumSet<RevSort> getRevSort() { return sorting.clone(); @@ -475,8 +484,9 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { * Add or remove a sorting strategy for the returned commits. * <p> * Multiple strategies can be applied at once, in which case some strategies - * may take precedence over others. As an example, {@link RevSort#TOPO} must - * take precedence over {@link RevSort#COMMIT_TIME_DESC}, otherwise it + * may take precedence over others. As an example, + * {@link org.eclipse.jgit.revwalk.RevSort#TOPO} must take precedence over + * {@link org.eclipse.jgit.revwalk.RevSort#COMMIT_TIME_DESC}, otherwise it * cannot enforce its ordering. * * @param s @@ -518,12 +528,14 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { * Note that filters are not thread-safe and may not be shared by concurrent * RevWalk instances. Every RevWalk must be supplied its own unique filter, * unless the filter implementation specifically states it is (and always - * will be) thread-safe. Callers may use {@link RevFilter#clone()} to create - * a unique filter tree for this RevWalk instance. + * will be) thread-safe. Callers may use + * {@link org.eclipse.jgit.revwalk.filter.RevFilter#clone()} to create a + * unique filter tree for this RevWalk instance. * * @param newFilter - * the new filter. If null the special {@link RevFilter#ALL} - * filter will be used instead, as it matches every commit. + * the new filter. If null the special + * {@link org.eclipse.jgit.revwalk.filter.RevFilter#ALL} filter + * will be used instead, as it matches every commit. * @see org.eclipse.jgit.revwalk.filter.AndRevFilter * @see org.eclipse.jgit.revwalk.filter.OrRevFilter */ @@ -536,7 +548,9 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { * Get the tree filter used to simplify commits by modified paths. * * @return the current filter. Never null as a filter is always needed. If - * no filter is being applied {@link TreeFilter#ALL} is returned. + * no filter is being applied + * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#ALL} is + * returned. */ public TreeFilter getTreeFilter() { return treeFilter; @@ -545,20 +559,23 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { /** * Set the tree filter used to simplify commits by modified paths. * <p> - * If null or {@link TreeFilter#ALL} the path limiter is removed. Commits - * will not be simplified. + * If null or {@link org.eclipse.jgit.treewalk.filter.TreeFilter#ALL} the + * path limiter is removed. Commits will not be simplified. * <p> - * If non-null and not {@link TreeFilter#ALL} then the tree filter will be - * installed. Commits will have their ancestry simplified to hide commits that - * do not contain tree entries matched by the filter, unless - * {@code setRewriteParents(false)} is called. + * If non-null and not + * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#ALL} then the tree + * filter will be installed. Commits will have their ancestry simplified to + * hide commits that do not contain tree entries matched by the filter, + * unless {@code setRewriteParents(false)} is called. * <p> * Usually callers should be inserting a filter graph including - * {@link TreeFilter#ANY_DIFF} along with one or more - * {@link org.eclipse.jgit.treewalk.filter.PathFilter} instances. + * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#ANY_DIFF} along with + * one or more {@link org.eclipse.jgit.treewalk.filter.PathFilter} + * instances. * * @param newFilter - * new filter. If null the special {@link TreeFilter#ALL} filter + * new filter. If null the special + * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#ALL} filter * will be used instead, as it matches everything. * @see org.eclipse.jgit.treewalk.filter.PathFilter */ @@ -571,9 +588,9 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { * Set whether to rewrite parent pointers when filtering by modified paths. * <p> * By default, when {@link #setTreeFilter(TreeFilter)} is called with non- - * null and non-{@link TreeFilter#ALL} filter, commits will have their - * ancestry simplified and parents rewritten to hide commits that do not match - * the filter. + * null and non-{@link org.eclipse.jgit.treewalk.filter.TreeFilter#ALL} + * filter, commits will have their ancestry simplified and parents rewritten + * to hide commits that do not match the filter. * <p> * This behavior can be bypassed by passing false to this method. * @@ -596,8 +613,8 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { * care and would prefer to discard the body of a commit as early as * possible, to reduce memory usage. * <p> - * True by default on {@link RevWalk} and false by default for - * {@link ObjectWalk}. + * True by default on {@link org.eclipse.jgit.revwalk.RevWalk} and false by + * default for {@link org.eclipse.jgit.revwalk.ObjectWalk}. * * @return true if the body should be retained; false it is discarded. */ @@ -608,14 +625,15 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { /** * Set whether or not the body of a commit or tag is retained. * <p> - * If a body of a commit or tag is not retained, the application must - * call {@link #parseBody(RevObject)} before the body can be safely - * accessed through the type specific access methods. + * If a body of a commit or tag is not retained, the application must call + * {@link #parseBody(RevObject)} before the body can be safely accessed + * through the type specific access methods. * <p> - * True by default on {@link RevWalk} and false by default for - * {@link ObjectWalk}. + * True by default on {@link org.eclipse.jgit.revwalk.RevWalk} and false by + * default for {@link org.eclipse.jgit.revwalk.ObjectWalk}. * - * @param retain true to retain bodies; false to discard them early. + * @param retain + * true to retain bodies; false to discard them early. */ public void setRetainBody(final boolean retain) { retainBody = retain; @@ -759,11 +777,11 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { * @param id * name of the commit object. * @return reference to the commit object. Never null. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the supplied commit does not exist. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the supplied id is not a commit or an annotated tag. - * @throws IOException + * @throws java.io.IOException * a pack file or loose object could not be read. */ public RevCommit parseCommit(final AnyObjectId id) @@ -786,11 +804,11 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { * name of the tree object, or a commit or annotated tag that may * reference a tree. * @return reference to the tree object. Never null. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the supplied tree does not exist. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the supplied id is not a tree, a commit or an annotated tag. - * @throws IOException + * @throws java.io.IOException * a pack file or loose object could not be read. */ public RevTree parseTree(final AnyObjectId id) @@ -820,11 +838,11 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { * @param id * name of the tag object. * @return reference to the tag object. Never null. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the supplied tag does not exist. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the supplied id is not a tag or an annotated tag. - * @throws IOException + * @throws java.io.IOException * a pack file or loose object could not be read. */ public RevTag parseTag(final AnyObjectId id) throws MissingObjectException, @@ -847,9 +865,9 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { * @param id * name of the object. * @return reference to the object. Never null. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the supplied does not exist. - * @throws IOException + * @throws java.io.IOException * a pack file or loose object could not be read. */ public RevObject parseAny(final AnyObjectId id) @@ -916,8 +934,6 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { /** * Asynchronous object parsing. * - * @param <T> - * any ObjectId type. * @param objectIds * objects to open from the object store. The supplied collection * must not be modified until the queue has finished. @@ -1007,9 +1023,9 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { * * @param obj * the object the caller needs to be parsed. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the supplied does not exist. - * @throws IOException + * @throws java.io.IOException * a pack file or loose object could not be read. */ public void parseHeaders(final RevObject obj) @@ -1026,9 +1042,9 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { * * @param obj * the object the caller needs to be parsed. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the supplied does not exist. - * @throws IOException + * @throws java.io.IOException * a pack file or loose object could not be read. */ public void parseBody(final RevObject obj) @@ -1044,9 +1060,9 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { * @return If {@code obj} is not an annotated tag, {@code obj}. Otherwise * the first non-tag object that {@code obj} references. The * returned object's headers have been parsed. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * a referenced object cannot be found. - * @throws IOException + * @throws java.io.IOException * a pack file or loose object could not be read. */ public RevObject peel(RevObject obj) throws MissingObjectException, @@ -1069,7 +1085,7 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { * @param name * description of the flag, primarily useful for debugging. * @return newly constructed flag instance. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * too many flags have been reserved on this revision walker. */ public RevFlag newFlag(final String name) { @@ -1308,6 +1324,8 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { } /** + * {@inheritDoc} + * <p> * Returns an Iterator over the commits of this walker. * <p> * The returned iterator is only useful for one walk. If this RevWalk gets @@ -1316,10 +1334,9 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { * Applications must not use both the Iterator and the {@link #next()} API * at the same time. Pick one API and use that for the entire walk. * <p> - * If a checked exception is thrown during the walk (see {@link #next()}) - * it is rethrown from the Iterator as a {@link RevWalkException}. + * If a checked exception is thrown during the walk (see {@link #next()}) it + * is rethrown from the Iterator as a {@link RevWalkException}. * - * @return an iterator over this walker's commits. * @see RevWalkException */ @Override @@ -1365,7 +1382,9 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { }; } - /** Throws an exception if we have started producing output. */ + /** + * Throws an exception if we have started producing output. + */ protected void assertNotStarted() { if (isNotStarted()) return; @@ -1377,7 +1396,8 @@ public class RevWalk implements Iterable<RevCommit>, AutoCloseable { } /** - * Create and return an {@link ObjectWalk} using the same objects. + * Create and return an {@link org.eclipse.jgit.revwalk.ObjectWalk} using + * the same objects. * <p> * Prior to using this method, the caller must reset this RevWalk to clean * any flags that were used during the last traversal. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevWalkUtils.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevWalkUtils.java index e751d7714c..f1252a4c4b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevWalkUtils.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevWalkUtils.java @@ -53,7 +53,7 @@ import org.eclipse.jgit.errors.MissingObjectException; import org.eclipse.jgit.lib.Ref; /** - * Utility methods for {@link RevWalk}. + * Utility methods for {@link org.eclipse.jgit.revwalk.RevWalk}. */ public final class RevWalkUtils { @@ -67,9 +67,10 @@ public final class RevWalkUtils { * other words, count the number of commits that are in <code>start</code>, * but not in <code>end</code>. * <p> - * Note that this method calls {@link RevWalk#reset()} at the beginning. - * Also note that the existing rev filter on the walk is left as-is, so be - * sure to set the right rev filter before calling this method. + * Note that this method calls + * {@link org.eclipse.jgit.revwalk.RevWalk#reset()} at the beginning. Also + * note that the existing rev filter on the walk is left as-is, so be sure + * to set the right rev filter before calling this method. * * @param walk * the rev walk to use @@ -78,11 +79,10 @@ public final class RevWalkUtils { * @param end * the commit where counting should end, or null if counting * should be done until there are no more commits - * * @return the number of commits - * @throws MissingObjectException - * @throws IncorrectObjectTypeException - * @throws IOException + * @throws org.eclipse.jgit.errors.MissingObjectException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException + * @throws java.io.IOException */ public static int count(final RevWalk walk, final RevCommit start, final RevCommit end) throws MissingObjectException, @@ -96,9 +96,10 @@ public final class RevWalkUtils { * Find of commits that are in <code>start</code>, but not in * <code>end</code>. * <p> - * Note that this method calls {@link RevWalk#reset()} at the beginning. - * Also note that the existing rev filter on the walk is left as-is, so be - * sure to set the right rev filter before calling this method. + * Note that this method calls + * {@link org.eclipse.jgit.revwalk.RevWalk#reset()} at the beginning. Also + * note that the existing rev filter on the walk is left as-is, so be sure + * to set the right rev filter before calling this method. * * @param walk * the rev walk to use @@ -108,9 +109,9 @@ public final class RevWalkUtils { * the commit where counting should end, or null if counting * should be done until there are no more commits * @return the commits found - * @throws MissingObjectException - * @throws IncorrectObjectTypeException - * @throws IOException + * @throws org.eclipse.jgit.errors.MissingObjectException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException + * @throws java.io.IOException */ public static List<RevCommit> find(final RevWalk walk, final RevCommit start, final RevCommit end) @@ -131,7 +132,8 @@ public final class RevWalkUtils { * Find the list of branches a given commit is reachable from when following * parent.s * <p> - * Note that this method calls {@link RevWalk#reset()} at the beginning. + * Note that this method calls + * {@link org.eclipse.jgit.revwalk.RevWalk#reset()} at the beginning. * <p> * In order to improve performance this method assumes clock skew among * committers is never larger than 24 hours. @@ -143,9 +145,9 @@ public final class RevWalkUtils { * @param refs * the set of branches we want to see reachability from * @return the list of branches a given commit is reachable from - * @throws MissingObjectException - * @throws IncorrectObjectTypeException - * @throws IOException + * @throws org.eclipse.jgit.errors.MissingObjectException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException + * @throws java.io.IOException */ public static List<Ref> findBranchesReachableFrom(RevCommit commit, RevWalk revWalk, Collection<Ref> refs) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/TreeRevFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/TreeRevFilter.java index b2c0fcdf73..99c5d59a11 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/TreeRevFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/TreeRevFilter.java @@ -60,10 +60,12 @@ import org.eclipse.jgit.treewalk.TreeWalk; import org.eclipse.jgit.treewalk.filter.TreeFilter; /** - * Filter applying a {@link TreeFilter} against changed paths in each commit. + * Filter applying a {@link org.eclipse.jgit.treewalk.filter.TreeFilter} against + * changed paths in each commit. * <p> * Each commit is differenced concurrently against all of its parents to look - * for tree entries that are interesting to the {@link TreeFilter}. + * for tree entries that are interesting to the + * {@link org.eclipse.jgit.treewalk.filter.TreeFilter}. * * @since 3.5 */ @@ -76,14 +78,15 @@ public class TreeRevFilter extends RevFilter { private final TreeWalk pathFilter; /** - * Create a {@link RevFilter} from a {@link TreeFilter}. + * Create a {@link org.eclipse.jgit.revwalk.filter.RevFilter} from a + * {@link org.eclipse.jgit.treewalk.filter.TreeFilter}. * * @param walker * walker used for reading trees. * @param t - * filter to compare against any changed paths in each commit. If a - * {@link FollowFilter}, will be replaced with a new filter - * following new paths after a rename. + * filter to compare against any changed paths in each commit. If + * a {@link org.eclipse.jgit.revwalk.FollowFilter}, will be + * replaced with a new filter following new paths after a rename. * @since 3.5 */ public TreeRevFilter(final RevWalk walker, final TreeFilter t) { @@ -121,11 +124,13 @@ public class TreeRevFilter extends RevFilter { this.rewriteFlag = rewriteFlag; } + /** {@inheritDoc} */ @Override public RevFilter clone() { throw new UnsupportedOperationException(); } + /** {@inheritDoc} */ @Override public boolean include(final RevWalk walker, final RevCommit c) throws StopWalkException, MissingObjectException, @@ -260,6 +265,7 @@ public class TreeRevFilter extends RevFilter { return false; } + /** {@inheritDoc} */ @Override public boolean requiresCommitBody() { return false; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/AndRevFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/AndRevFilter.java index 4a91493dc0..0019e0c283 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/AndRevFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/AndRevFilter.java @@ -57,9 +57,10 @@ import org.eclipse.jgit.revwalk.RevWalk; * Includes a commit only if all subfilters include the same commit. * <p> * Classic shortcut behavior is used, so evaluation of the - * {@link RevFilter#include(RevWalk, RevCommit)} method stops as soon as a false - * result is obtained. Applications can improve filtering performance by placing - * faster filters that are more likely to reject a result earlier in the list. + * {@link org.eclipse.jgit.revwalk.filter.RevFilter#include(RevWalk, RevCommit)} + * method stops as soon as a false result is obtained. Applications can improve + * filtering performance by placing faster filters that are more likely to + * reject a result earlier in the list. */ public abstract class AndRevFilter extends RevFilter { /** diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/AuthorRevFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/AuthorRevFilter.java index ef0064b238..e00feaf9a0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/AuthorRevFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/AuthorRevFilter.java @@ -50,7 +50,9 @@ import org.eclipse.jgit.revwalk.RevCommit; import org.eclipse.jgit.util.RawCharSequence; import org.eclipse.jgit.util.RawParseUtils; -/** Matches only commits whose author name matches the pattern. */ +/** + * Matches only commits whose author name matches the pattern. + */ public class AuthorRevFilter { /** * Create a new author filter. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/CommitTimeRevFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/CommitTimeRevFilter.java index 5bf9366ded..9f4f10f3ae 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/CommitTimeRevFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/CommitTimeRevFilter.java @@ -53,7 +53,9 @@ import org.eclipse.jgit.errors.StopWalkException; import org.eclipse.jgit.revwalk.RevCommit; import org.eclipse.jgit.revwalk.RevWalk; -/** Selects commits based upon the commit time field. */ +/** + * Selects commits based upon the commit time field. + */ public abstract class CommitTimeRevFilter extends RevFilter { /** * Create a new filter to select commits before a given date/time. @@ -129,11 +131,13 @@ public abstract class CommitTimeRevFilter extends RevFilter { when = (int) (ts / 1000); } + /** {@inheritDoc} */ @Override public RevFilter clone() { return this; } + /** {@inheritDoc} */ @Override public boolean requiresCommitBody() { return false; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/CommitterRevFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/CommitterRevFilter.java index eedfef215c..4a1b3a6c7f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/CommitterRevFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/CommitterRevFilter.java @@ -50,7 +50,9 @@ import org.eclipse.jgit.revwalk.RevCommit; import org.eclipse.jgit.util.RawCharSequence; import org.eclipse.jgit.util.RawParseUtils; -/** Matches only commits whose committer name matches the pattern. */ +/** + * Matches only commits whose committer name matches the pattern. + */ public class CommitterRevFilter { /** * Create a new committer filter. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/MaxCountRevFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/MaxCountRevFilter.java index 38b0da5286..02c6670758 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/MaxCountRevFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/MaxCountRevFilter.java @@ -79,6 +79,7 @@ public class MaxCountRevFilter extends RevFilter { this.maxCount = maxCount; } + /** {@inheritDoc} */ @Override public boolean include(RevWalk walker, RevCommit cmit) throws StopWalkException, MissingObjectException, @@ -89,6 +90,7 @@ public class MaxCountRevFilter extends RevFilter { return true; } + /** {@inheritDoc} */ @Override public RevFilter clone() { return new MaxCountRevFilter(maxCount); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/MessageRevFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/MessageRevFilter.java index a7cc5bdc10..f1f4065480 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/MessageRevFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/MessageRevFilter.java @@ -50,7 +50,9 @@ import org.eclipse.jgit.revwalk.RevCommit; import org.eclipse.jgit.util.RawCharSequence; import org.eclipse.jgit.util.RawParseUtils; -/** Matches only commits whose message matches the pattern. */ +/** + * Matches only commits whose message matches the pattern. + */ public class MessageRevFilter { /** * Create a message filter. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/NotRevFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/NotRevFilter.java index d3388021ba..84b7f6b7b6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/NotRevFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/NotRevFilter.java @@ -50,7 +50,9 @@ import org.eclipse.jgit.errors.MissingObjectException; import org.eclipse.jgit.revwalk.RevCommit; import org.eclipse.jgit.revwalk.RevWalk; -/** Includes a commit only if the subfilter does not include the commit. */ +/** + * Includes a commit only if the subfilter does not include the commit. + */ public class NotRevFilter extends RevFilter { /** * Create a filter that negates the result of another filter. @@ -69,11 +71,13 @@ public class NotRevFilter extends RevFilter { a = one; } + /** {@inheritDoc} */ @Override public RevFilter negate() { return a; } + /** {@inheritDoc} */ @Override public boolean include(final RevWalk walker, final RevCommit c) throws MissingObjectException, IncorrectObjectTypeException, @@ -81,16 +85,19 @@ public class NotRevFilter extends RevFilter { return !a.include(walker, c); } + /** {@inheritDoc} */ @Override public boolean requiresCommitBody() { return a.requiresCommitBody(); } + /** {@inheritDoc} */ @Override public RevFilter clone() { return new NotRevFilter(a.clone()); } + /** {@inheritDoc} */ @Override public String toString() { return "NOT " + a.toString(); //$NON-NLS-1$ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/ObjectFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/ObjectFilter.java index 2ad273d9ec..777e4e01c5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/ObjectFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/ObjectFilter.java @@ -54,7 +54,8 @@ import org.eclipse.jgit.revwalk.ObjectWalk; * Selects interesting objects when walking. * <p> * Applications should install the filter on an ObjectWalk by - * {@link ObjectWalk#setObjectFilter(ObjectFilter)} prior to starting traversal. + * {@link org.eclipse.jgit.revwalk.ObjectWalk#setObjectFilter(ObjectFilter)} + * prior to starting traversal. * * @since 4.0 */ @@ -77,13 +78,13 @@ public abstract class ObjectFilter { * @param objid * the object currently being tested. * @return {@code true} if the named object should be included in the walk. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * an object the filter needed to consult to determine its * answer was missing - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * an object the filter needed to consult to determine its * answer was of the wrong type - * @throws IOException + * @throws java.io.IOException * an object the filter needed to consult to determine its * answer could not be read. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/OrRevFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/OrRevFilter.java index 4c7b3bf47e..a14764a82d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/OrRevFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/OrRevFilter.java @@ -57,9 +57,10 @@ import org.eclipse.jgit.revwalk.RevWalk; * Includes a commit if any subfilters include the same commit. * <p> * Classic shortcut behavior is used, so evaluation of the - * {@link RevFilter#include(RevWalk, RevCommit)} method stops as soon as a true - * result is obtained. Applications can improve filtering performance by placing - * faster filters that are more likely to accept a result earlier in the list. + * {@link org.eclipse.jgit.revwalk.filter.RevFilter#include(RevWalk, RevCommit)} + * method stops as soon as a true result is obtained. Applications can improve + * filtering performance by placing faster filters that are more likely to + * accept a result earlier in the list. */ public abstract class OrRevFilter extends RevFilter { /** diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/PatternMatchRevFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/PatternMatchRevFilter.java index 1dd4555e5a..edce224a6e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/PatternMatchRevFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/PatternMatchRevFilter.java @@ -54,9 +54,10 @@ import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.revwalk.RevCommit; import org.eclipse.jgit.revwalk.RevWalk; -import org.eclipse.jgit.util.RawCharSequence; -/** Abstract filter that searches text using extended regular expressions. */ +/** + * Abstract filter that searches text using extended regular expressions. + */ public abstract class PatternMatchRevFilter extends RevFilter { /** * Encode a string pattern for faster matching on byte arrays. @@ -69,7 +70,7 @@ public abstract class PatternMatchRevFilter extends RevFilter { * original pattern string supplied by the user or the * application. * @return same pattern, but re-encoded to match our funny raw UTF-8 - * character sequence {@link RawCharSequence}. + * character sequence {@link org.eclipse.jgit.util.RawCharSequence}. */ protected static final String forceToRaw(final String patternText) { final byte[] b = Constants.encode(patternText); @@ -97,7 +98,8 @@ public abstract class PatternMatchRevFilter extends RevFilter { * should {@link #forceToRaw(String)} be applied to the pattern * before compiling it? * @param flags - * flags from {@link Pattern} to control how matching performs. + * flags from {@link java.util.regex.Pattern} to control how + * matching performs. */ protected PatternMatchRevFilter(String pattern, final boolean innerString, final boolean rawEncoding, final int flags) { @@ -124,6 +126,7 @@ public abstract class PatternMatchRevFilter extends RevFilter { return patternText; } + /** {@inheritDoc} */ @Override public boolean include(final RevWalk walker, final RevCommit cmit) throws MissingObjectException, IncorrectObjectTypeException, @@ -131,6 +134,7 @@ public abstract class PatternMatchRevFilter extends RevFilter { return compiledPattern.reset(text(cmit)).matches(); } + /** {@inheritDoc} */ @Override public boolean requiresCommitBody() { return true; @@ -145,6 +149,7 @@ public abstract class PatternMatchRevFilter extends RevFilter { */ protected abstract CharSequence text(RevCommit cmit); + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/RevFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/RevFilter.java index 6b90d29f1c..9068c57517 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/RevFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/RevFilter.java @@ -61,7 +61,8 @@ import org.eclipse.jgit.revwalk.RevWalk; * <code>OrRevFilter</code> to create complex boolean expressions. * <p> * Applications should install the filter on a RevWalk by - * {@link RevWalk#setRevFilter(RevFilter)} prior to starting traversal. + * {@link org.eclipse.jgit.revwalk.RevWalk#setRevFilter(RevFilter)} prior to + * starting traversal. * <p> * Unless specifically noted otherwise a RevFilter implementation is not thread * safe and may not be shared by different RevWalk instances at the same time. @@ -73,9 +74,12 @@ import org.eclipse.jgit.revwalk.RevWalk; * <p> * <b>Message filters:</b> * <ul> - * <li>Author name/email: {@link AuthorRevFilter}</li> - * <li>Committer name/email: {@link CommitterRevFilter}</li> - * <li>Message body: {@link MessageRevFilter}</li> + * <li>Author name/email: + * {@link org.eclipse.jgit.revwalk.filter.AuthorRevFilter}</li> + * <li>Committer name/email: + * {@link org.eclipse.jgit.revwalk.filter.CommitterRevFilter}</li> + * <li>Message body: + * {@link org.eclipse.jgit.revwalk.filter.MessageRevFilter}</li> * </ul> * * <p> @@ -88,9 +92,9 @@ import org.eclipse.jgit.revwalk.RevWalk; * <p> * <b>Boolean modifiers:</b> * <ul> - * <li>AND: {@link AndRevFilter}</li> - * <li>OR: {@link OrRevFilter}</li> - * <li>NOT: {@link NotRevFilter}</li> + * <li>AND: {@link org.eclipse.jgit.revwalk.filter.AndRevFilter}</li> + * <li>OR: {@link org.eclipse.jgit.revwalk.filter.OrRevFilter}</li> + * <li>NOT: {@link org.eclipse.jgit.revwalk.filter.NotRevFilter}</li> * </ul> */ public abstract class RevFilter { @@ -241,7 +245,11 @@ public abstract class RevFilter { return NotRevFilter.create(this); } - /** @return true if the filter needs the commit body to be parsed. */ + /** + * Whether the filter needs the commit body to be parsed. + * + * @return true if the filter needs the commit body to be parsed. + */ public boolean requiresCommitBody() { // Assume true to be backward compatible with prior behavior. return true; @@ -258,19 +266,19 @@ public abstract class RevFilter { * returns true from {@link #requiresCommitBody()}. * @return true to include this commit in the results; false to have this * commit be omitted entirely from the results. - * @throws StopWalkException + * @throws org.eclipse.jgit.errors.StopWalkException * the filter knows for certain that no additional commits can * ever match, and the current commit doesn't match either. The * walk is halted and no more results are provided. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * an object the filter needs to consult to determine its answer * does not exist in the Git repository the walker is operating * on. Filtering this commit is impossible without the object. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * an object the filter needed to consult was not of the * expected object type. This usually indicates a corrupt * repository, as an object link is referencing the wrong type. - * @throws IOException + * @throws java.io.IOException * a loose object or pack file could not be read to obtain data * necessary for the filter to make its decision. */ @@ -279,16 +287,17 @@ public abstract class RevFilter { IncorrectObjectTypeException, IOException; /** + * {@inheritDoc} + * <p> * Clone this revision filter, including its parameters. * <p> * This is a deep clone. If this filter embeds objects or other filters it * must also clone those, to ensure the instances do not share mutable data. - * - * @return another copy of this filter, suitable for another thread. */ @Override public abstract RevFilter clone(); + /** {@inheritDoc} */ @Override public String toString() { String n = getClass().getName(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/RevFlagFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/RevFlagFilter.java index 1fbf74617e..8225e4d3e7 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/RevFlagFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/RevFlagFilter.java @@ -52,7 +52,9 @@ import org.eclipse.jgit.revwalk.RevFlag; import org.eclipse.jgit.revwalk.RevFlagSet; import org.eclipse.jgit.revwalk.RevWalk; -/** Matches only commits with some/all RevFlags already set. */ +/** + * Matches only commits with some/all RevFlags already set. + */ public abstract class RevFlagFilter extends RevFilter { /** * Create a new filter that tests for a single flag. @@ -123,11 +125,13 @@ public abstract class RevFlagFilter extends RevFilter { flags = m; } + /** {@inheritDoc} */ @Override public RevFilter clone() { return this; } + /** {@inheritDoc} */ @Override public String toString() { return super.toString() + flags; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/SkipRevFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/SkipRevFilter.java index 51dd2ed812..79af5a3d4b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/SkipRevFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/SkipRevFilter.java @@ -78,6 +78,7 @@ public class SkipRevFilter extends RevFilter { this.skip = skip; } + /** {@inheritDoc} */ @Override public boolean include(RevWalk walker, RevCommit cmit) throws StopWalkException, MissingObjectException, @@ -87,6 +88,7 @@ public class SkipRevFilter extends RevFilter { return true; } + /** {@inheritDoc} */ @Override public RevFilter clone() { return new SkipRevFilter(skip); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/SubStringRevFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/SubStringRevFilter.java index ce3a022293..3e6b1480e2 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/SubStringRevFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revwalk/filter/SubStringRevFilter.java @@ -52,7 +52,9 @@ import org.eclipse.jgit.revwalk.RevWalk; import org.eclipse.jgit.util.RawCharSequence; import org.eclipse.jgit.util.RawSubStringPattern; -/** Abstract filter that searches text using only substring search. */ +/** + * Abstract filter that searches text using only substring search. + */ public abstract class SubStringRevFilter extends RevFilter { /** * Can this string be safely handled by a substring filter? @@ -60,7 +62,8 @@ public abstract class SubStringRevFilter extends RevFilter { * @param pattern * the pattern text proposed by the user. * @return true if a substring filter can perform this pattern match; false - * if {@link PatternMatchRevFilter} must be used instead. + * if {@link org.eclipse.jgit.revwalk.filter.PatternMatchRevFilter} + * must be used instead. */ public static boolean safe(final String pattern) { for (int i = 0; i < pattern.length(); i++) { @@ -97,6 +100,7 @@ public abstract class SubStringRevFilter extends RevFilter { pattern = new RawSubStringPattern(patternText); } + /** {@inheritDoc} */ @Override public boolean include(final RevWalk walker, final RevCommit cmit) throws MissingObjectException, IncorrectObjectTypeException, @@ -104,6 +108,7 @@ public abstract class SubStringRevFilter extends RevFilter { return pattern.match(text(cmit)) >= 0; } + /** {@inheritDoc} */ @Override public boolean requiresCommitBody() { return true; @@ -118,11 +123,13 @@ public abstract class SubStringRevFilter extends RevFilter { */ protected abstract RawCharSequence text(RevCommit cmit); + /** {@inheritDoc} */ @Override public RevFilter clone() { return this; // Typically we are actually thread-safe. } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/FileBasedConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/FileBasedConfig.java index b2689797be..3f064e3341 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/FileBasedConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/FileBasedConfig.java @@ -55,6 +55,7 @@ import java.io.FileNotFoundException; import java.io.IOException; import java.text.MessageFormat; +import org.eclipse.jgit.annotations.Nullable; import org.eclipse.jgit.errors.ConfigInvalidException; import org.eclipse.jgit.errors.LockFailedException; import org.eclipse.jgit.internal.JGitText; @@ -80,6 +81,8 @@ public class FileBasedConfig extends StoredConfig { private final File configFile; + private final FS fs; + private boolean utf8Bom; private volatile FileSnapshot snapshot; @@ -113,31 +116,34 @@ public class FileBasedConfig extends StoredConfig { public FileBasedConfig(Config base, File cfgLocation, FS fs) { super(base); configFile = cfgLocation; + this.fs = fs; this.snapshot = FileSnapshot.DIRTY; this.hash = ObjectId.zeroId(); } + /** {@inheritDoc} */ @Override protected boolean notifyUponTransientChanges() { // we will notify listeners upon save() return false; } - /** @return location of the configuration file on disk */ + /** + * Get location of the configuration file on disk + * + * @return location of the configuration file on disk + */ public final File getFile() { return configFile; } /** + * {@inheritDoc} + * <p> * Load the configuration as a Git text style configuration file. * <p> * If the file does not exist, this configuration is cleared, and thus * behaves the same as though the file exists, but is empty. - * - * @throws IOException - * the file could not be read (but does exist). - * @throws ConfigInvalidException - * the file is not a properly formatted configuration file. */ @Override public void load() throws IOException, ConfigInvalidException { @@ -197,6 +203,8 @@ public class FileBasedConfig extends StoredConfig { } /** + * {@inheritDoc} + * <p> * Save the configuration as a Git text style configuration file. * <p> * <b>Warning:</b> Although this method uses the traditional Git file @@ -204,9 +212,6 @@ public class FileBasedConfig extends StoredConfig { * configuration file, it does not ensure that the file has not been * modified since the last read, which means updates performed by other * objects accessing the same backing file may be lost. - * - * @throws IOException - * the file could not be written. */ @Override public void save() throws IOException { @@ -240,6 +245,7 @@ public class FileBasedConfig extends StoredConfig { fireConfigChangedEvent(); } + /** {@inheritDoc} */ @Override public void clear() { hash = hash(new byte[0]); @@ -250,6 +256,7 @@ public class FileBasedConfig extends StoredConfig { return ObjectId.fromRaw(Constants.newMessageDigest().digest(rawText)); } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { @@ -257,10 +264,40 @@ public class FileBasedConfig extends StoredConfig { } /** + * Whether the currently loaded configuration file is outdated + * * @return returns true if the currently loaded configuration file is older - * than the file on disk + * than the file on disk */ public boolean isOutdated() { return snapshot.isModified(getFile()); } + + /** + * {@inheritDoc} + * + * @since 4.10 + */ + @Override + @Nullable + protected byte[] readIncludedConfig(String relPath) + throws ConfigInvalidException { + final File file; + if (relPath.startsWith("~/")) { //$NON-NLS-1$ + file = fs.resolve(fs.userHome(), relPath.substring(2)); + } else { + file = fs.resolve(configFile.getParentFile(), relPath); + } + + if (!file.exists()) { + return null; + } + + try { + return IO.readFully(file); + } catch (IOException ioe) { + throw new ConfigInvalidException(MessageFormat + .format(JGitText.get().cannotReadFile, relPath), ioe); + } + } } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/FileRepositoryBuilder.java b/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/FileRepositoryBuilder.java index 944fb4f5ea..3e45bd5ce8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/FileRepositoryBuilder.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/FileRepositoryBuilder.java @@ -52,7 +52,7 @@ import org.eclipse.jgit.lib.BaseRepositoryBuilder; import org.eclipse.jgit.lib.Repository; /** - * Constructs a {@link FileRepository}. + * Constructs a {@link org.eclipse.jgit.internal.storage.file.FileRepository}. * <p> * Applications must set one of {@link #setGitDir(File)} or * {@link #setWorkTree(File)}, or use {@link #readEnvironment()} or @@ -73,18 +73,14 @@ import org.eclipse.jgit.lib.Repository; public class FileRepositoryBuilder extends BaseRepositoryBuilder<FileRepositoryBuilder, Repository> { /** + * {@inheritDoc} + * <p> * Create a repository matching the configuration in this builder. * <p> * If an option was not set, the build method will try to default the option * based on other options. If insufficient information is available, an * exception is thrown to the caller. * - * @return a repository matching this configuration. - * @throws IllegalArgumentException - * insufficient parameters were set. - * @throws IOException - * the repository could not be accessed to configure the rest of - * the builder's parameters. * @since 3.0 */ @Override @@ -96,12 +92,13 @@ public class FileRepositoryBuilder extends } /** - * Convenience factory method to construct a {@link FileRepository}. + * Convenience factory method to construct a + * {@link org.eclipse.jgit.internal.storage.file.FileRepository}. * * @param gitDir * {@code GIT_DIR}, the repository meta directory. * @return a repository matching this configuration. - * @throws IOException + * @throws java.io.IOException * the repository could not be accessed to configure the rest of * the builder's parameters. * @since 3.0 diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/WindowCacheConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/WindowCacheConfig.java index 4205fc4e80..19fc63e00b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/WindowCacheConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/storage/file/WindowCacheConfig.java @@ -47,7 +47,9 @@ import org.eclipse.jgit.internal.storage.file.WindowCache; import org.eclipse.jgit.lib.Config; import org.eclipse.jgit.storage.pack.PackConfig; -/** Configuration parameters for JVM-wide buffer cache used by JGit. */ +/** + * Configuration parameters for JVM-wide buffer cache used by JGit. + */ public class WindowCacheConfig { /** 1024 (number of bytes in one kibibyte/kilobyte) */ public static final int KB = 1024; @@ -67,7 +69,9 @@ public class WindowCacheConfig { private int streamFileThreshold; - /** Create a default configuration. */ + /** + * Create a default configuration. + */ public WindowCacheConfig() { packedGitOpenFiles = 128; packedGitLimit = 10 * MB; @@ -78,6 +82,8 @@ public class WindowCacheConfig { } /** + * Get maximum number of streams to open at a time. + * * @return maximum number of streams to open at a time. Open packs count * against the process limits. <b>Default is 128.</b> */ @@ -86,6 +92,8 @@ public class WindowCacheConfig { } /** + * Set maximum number of streams to open at a time. + * * @param fdLimit * maximum number of streams to open at a time. Open packs count * against the process limits @@ -95,6 +103,9 @@ public class WindowCacheConfig { } /** + * Get maximum number bytes of heap memory to dedicate to caching pack file + * data. + * * @return maximum number bytes of heap memory to dedicate to caching pack * file data. <b>Default is 10 MB.</b> */ @@ -103,6 +114,9 @@ public class WindowCacheConfig { } /** + * Set maximum number bytes of heap memory to dedicate to caching pack file + * data. + * * @param newLimit * maximum number bytes of heap memory to dedicate to caching * pack file data. @@ -112,6 +126,9 @@ public class WindowCacheConfig { } /** + * Get size in bytes of a single window mapped or read in from the pack + * file. + * * @return size in bytes of a single window mapped or read in from the pack * file. <b>Default is 8 KB.</b> */ @@ -120,6 +137,8 @@ public class WindowCacheConfig { } /** + * Set size in bytes of a single window read in from the pack file. + * * @param newSize * size in bytes of a single window read in from the pack file. */ @@ -128,25 +147,32 @@ public class WindowCacheConfig { } /** - * @return true enables use of Java NIO virtual memory mapping for windows; - * false reads entire window into a byte[] with standard read calls. - * <b>Default false.</b> + * Whether to use Java NIO virtual memory mapping for windows + * + * @return {@code true} enables use of Java NIO virtual memory mapping for + * windows; false reads entire window into a byte[] with standard + * read calls. <b>Default false.</b> */ public boolean isPackedGitMMAP() { return packedGitMMAP; } /** + * Set whether to enable use of Java NIO virtual memory mapping for windows + * * @param usemmap - * true enables use of Java NIO virtual memory mapping for - * windows; false reads entire window into a byte[] with standard - * read calls. + * {@code true} enables use of Java NIO virtual memory mapping + * for windows; false reads entire window into a byte[] with + * standard read calls. */ public void setPackedGitMMAP(final boolean usemmap) { packedGitMMAP = usemmap; } /** + * Get maximum number of bytes to cache in delta base cache for inflated, + * recently accessed objects, without delta chains. + * * @return maximum number of bytes to cache in delta base cache for * inflated, recently accessed objects, without delta chains. * <b>Default 10 MB.</b> @@ -156,6 +182,9 @@ public class WindowCacheConfig { } /** + * Set maximum number of bytes to cache in delta base cache for inflated, + * recently accessed objects, without delta chains. + * * @param newLimit * maximum number of bytes to cache in delta base cache for * inflated, recently accessed objects, without delta chains. @@ -164,12 +193,18 @@ public class WindowCacheConfig { deltaBaseCacheLimit = newLimit; } - /** @return the size threshold beyond which objects must be streamed. */ + /** + * Get the size threshold beyond which objects must be streamed. + * + * @return the size threshold beyond which objects must be streamed. + */ public int getStreamFileThreshold() { return streamFileThreshold; } /** + * Set new byte limit for objects that must be streamed. + * * @param newLimit * new byte limit for objects that must be streamed. Objects * smaller than this size can be obtained as a contiguous byte diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/storage/pack/PackConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/storage/pack/PackConfig.java index 4f2374ff7b..484cde29ee 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/storage/pack/PackConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/storage/pack/PackConfig.java @@ -262,7 +262,9 @@ public class PackConfig { private boolean singlePack; - /** Create a default configuration. */ + /** + * Create a default configuration. + */ public PackConfig() { // Fields are initialized to defaults. } @@ -280,7 +282,8 @@ public class PackConfig { } /** - * Create a configuration honoring settings in a {@link Config}. + * Create a configuration honoring settings in a + * {@link org.eclipse.jgit.lib.Config}. * * @param cfg * the source to read settings from. The source is not retained @@ -531,6 +534,9 @@ public class PackConfig { } /** + * Whether existing delta chains should be cut at + * {@link #getMaxDeltaDepth()}. + * * @return true if existing delta chains should be cut at * {@link #getMaxDeltaDepth()}. Default is false, allowing existing * chains to be of any length. @@ -558,9 +564,11 @@ public class PackConfig { } /** + * Whether all of refs/* should be packed in a single pack. + * * @return true if all of refs/* should be packed in a single pack. Default - * is false, packing a separate GC_REST pack for references outside - * of refs/heads/* and refs/tags/*. + * is false, packing a separate GC_REST pack for references outside + * of refs/heads/* and refs/tags/*. * @since 4.9 */ public boolean getSinglePack() { @@ -785,7 +793,11 @@ public class PackConfig { this.threads = threads; } - /** @return the preferred thread pool to execute delta search on. */ + /** + * Get the preferred thread pool to execute delta search on. + * + * @return the preferred thread pool to execute delta search on. + */ public Executor getExecutor() { return executor; } @@ -1073,6 +1085,7 @@ public class PackConfig { getBitmapInactiveBranchAgeInDays())); } + /** {@inheritDoc} */ @Override public String toString() { final StringBuilder b = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/storage/pack/PackStatistics.java b/org.eclipse.jgit/src/org/eclipse/jgit/storage/pack/PackStatistics.java index a811fe3cde..68cffd5b38 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/storage/pack/PackStatistics.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/storage/pack/PackStatistics.java @@ -254,7 +254,8 @@ public class PackStatistics { private Accumulator statistics; /** - * Creates a new {@link PackStatistics} object from the accumulator. + * Creates a new {@link org.eclipse.jgit.storage.pack.PackStatistics} object + * from the accumulator. * * @param accumulator * the accumulator of the statistics @@ -270,6 +271,8 @@ public class PackStatistics { } /** + * Get unmodifiable collection of objects to be included in the pack. + * * @return unmodifiable collection of objects to be included in the pack. * May be {@code null} if the pack was hand-crafted in a unit test. */ @@ -278,6 +281,9 @@ public class PackStatistics { } /** + * Get unmodifiable collection of objects that should be excluded from the + * pack + * * @return unmodifiable collection of objects that should be excluded from * the pack, as the peer that will receive the pack already has * these objects. @@ -287,6 +293,9 @@ public class PackStatistics { } /** + * Get unmodifiable collection of objects that were shallow commits on the + * client. + * * @return unmodifiable collection of objects that were shallow commits on * the client. */ @@ -295,6 +304,8 @@ public class PackStatistics { } /** + * Get unmodifiable list of the cached packs that were reused in the output + * * @return unmodifiable list of the cached packs that were reused in the * output, if any were selected for reuse. */ @@ -302,12 +313,19 @@ public class PackStatistics { return statistics.reusedPacks; } - /** @return unmodifiable collection of the root commits of the history. */ + /** + * Get unmodifiable collection of the root commits of the history. + * + * @return unmodifiable collection of the root commits of the history. + */ public Set<ObjectId> getRootCommits() { return statistics.rootCommits; } /** + * Get number of objects in the output pack that went through the delta + * search process in order to find a potential delta base. + * * @return number of objects in the output pack that went through the delta * search process in order to find a potential delta base. */ @@ -316,6 +334,9 @@ public class PackStatistics { } /** + * Get number of objects in the output pack that went through delta base + * search and found a suitable base. + * * @return number of objects in the output pack that went through delta base * search and found a suitable base. This is a subset of * {@link #getDeltaSearchNonEdgeObjects()}. @@ -325,6 +346,8 @@ public class PackStatistics { } /** + * Get total number of objects output. + * * @return total number of objects output. This total includes the value of * {@link #getTotalDeltas()}. */ @@ -333,6 +356,9 @@ public class PackStatistics { } /** + * Get the count of objects that needed to be discovered through an object + * walk because they were not found in bitmap indices. + * * @return the count of objects that needed to be discovered through an * object walk because they were not found in bitmap indices. * Returns -1 if no bitmap indices were found. @@ -342,6 +368,8 @@ public class PackStatistics { } /** + * Get total number of deltas output. + * * @return total number of deltas output. This may be lower than the actual * number of deltas if a cached pack was reused. */ @@ -350,6 +378,9 @@ public class PackStatistics { } /** + * Get number of objects whose existing representation was reused in the + * output. + * * @return number of objects whose existing representation was reused in the * output. This count includes {@link #getReusedDeltas()}. */ @@ -358,6 +389,9 @@ public class PackStatistics { } /** + * Get number of deltas whose existing representation was reused in the + * output. + * * @return number of deltas whose existing representation was reused in the * output, as their base object was also output or was assumed * present for a thin pack. This may be lower than the actual number @@ -368,6 +402,8 @@ public class PackStatistics { } /** + * Get total number of bytes written. + * * @return total number of bytes written. This size includes the pack * header, trailer, thin pack, and reused cached pack(s). */ @@ -376,6 +412,8 @@ public class PackStatistics { } /** + * Get size of the thin pack in bytes. + * * @return size of the thin pack in bytes, if a thin pack was generated. A * thin pack is created when the client already has objects and some * deltas are created against those objects, or if a cached pack is @@ -387,6 +425,8 @@ public class PackStatistics { } /** + * Get information about this type of object in the pack. + * * @param typeCode * object type code, e.g. OBJ_COMMIT or OBJ_TREE. * @return information about this type of object in the pack. @@ -395,17 +435,28 @@ public class PackStatistics { return new ObjectType(statistics.objectTypes[typeCode]); } - /** @return true if the resulting pack file was a shallow pack. */ + /** + * Whether the resulting pack file was a shallow pack. + * + * @return {@code true} if the resulting pack file was a shallow pack. + */ public boolean isShallow() { return statistics.depth > 0; } - /** @return depth (in commits) the pack includes if shallow. */ + /** + * Get depth (in commits) the pack includes if shallow. + * + * @return depth (in commits) the pack includes if shallow. + */ public int getDepth() { return statistics.depth; } /** + * Get time in milliseconds spent enumerating the objects that need to be + * included in the output. + * * @return time in milliseconds spent enumerating the objects that need to * be included in the output. This time includes any restarts that * occur when a cached pack is selected for reuse. @@ -415,6 +466,9 @@ public class PackStatistics { } /** + * Get time in milliseconds spent matching existing representations against + * objects that will be transmitted. + * * @return time in milliseconds spent matching existing representations * against objects that will be transmitted, or that the client can * be assumed to already have. @@ -424,6 +478,9 @@ public class PackStatistics { } /** + * Get time in milliseconds spent finding the sizes of all objects that will + * enter the delta compression search window. + * * @return time in milliseconds spent finding the sizes of all objects that * will enter the delta compression search window. The sizes need to * be known to better match similar objects together and improve @@ -434,6 +491,8 @@ public class PackStatistics { } /** + * Get time in milliseconds spent on delta compression. + * * @return time in milliseconds spent on delta compression. This is observed * wall-clock time and does not accurately track CPU time used when * multiple threads were used to perform the delta compression. @@ -443,6 +502,9 @@ public class PackStatistics { } /** + * Get time in milliseconds spent writing the pack output, from start of + * header until end of trailer. + * * @return time in milliseconds spent writing the pack output, from start of * header until end of trailer. The transfer speed can be * approximated by dividing {@link #getTotalBytes()} by this value. @@ -451,7 +513,11 @@ public class PackStatistics { return statistics.timeWriting; } - /** @return total time spent processing this pack. */ + /** + * Get total time spent processing this pack. + * + * @return total time spent processing this pack. + */ public long getTimeTotal() { return statistics.timeCounting + statistics.timeSearchingForReuse + statistics.timeSearchingForSizes + statistics.timeCompressing @@ -459,14 +525,20 @@ public class PackStatistics { } /** - * @return get the average output speed in terms of bytes-per-second. + * Get the average output speed in terms of bytes-per-second. + * + * @return the average output speed in terms of bytes-per-second. * {@code getTotalBytes() / (getTimeWriting() / 1000.0)}. */ public double getTransferRate() { return getTotalBytes() / (getTimeWriting() / 1000.0); } - /** @return formatted message string for display to clients. */ + /** + * Get formatted message string for display to clients. + * + * @return formatted message string for display to clients. + */ public String getMessage() { return MessageFormat.format(JGitText.get().packWriterStatistics, Long.valueOf(statistics.totalObjects), @@ -475,7 +547,11 @@ public class PackStatistics { Long.valueOf(statistics.reusedDeltas)); } - /** @return a map containing ObjectType statistics. */ + /** + * Get a map containing ObjectType statistics. + * + * @return a map containing ObjectType statistics. + */ public Map<Integer, ObjectType> getObjectTypes() { HashMap<Integer, ObjectType> map = new HashMap<>(); map.put(Integer.valueOf(OBJ_BLOB), new ObjectType( diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/submodule/SubmoduleStatus.java b/org.eclipse.jgit/src/org/eclipse/jgit/submodule/SubmoduleStatus.java index 2298f4b17c..884f2ac7fc 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/submodule/SubmoduleStatus.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/submodule/SubmoduleStatus.java @@ -61,8 +61,12 @@ public class SubmoduleStatus { * Create submodule status * * @param type + * a {@link org.eclipse.jgit.submodule.SubmoduleStatusType} + * object. * @param path + * submodule path * @param indexId + * an {@link org.eclipse.jgit.lib.ObjectId} object. */ public SubmoduleStatus(final SubmoduleStatusType type, final String path, final ObjectId indexId) { @@ -73,9 +77,14 @@ public class SubmoduleStatus { * Create submodule status * * @param type + * a {@link org.eclipse.jgit.submodule.SubmoduleStatusType} + * object. * @param path + * submodule path * @param indexId + * index id * @param headId + * head id */ public SubmoduleStatus(final SubmoduleStatusType type, final String path, final ObjectId indexId, final ObjectId headId) { @@ -86,6 +95,8 @@ public class SubmoduleStatus { } /** + * Get type + * * @return type */ public SubmoduleStatusType getType() { @@ -93,13 +104,17 @@ public class SubmoduleStatus { } /** - * @return path + * Get submodule path + * + * @return path submodule path */ public String getPath() { return path; } /** + * Get index object id + * * @return index object id */ public ObjectId getIndexId() { @@ -107,6 +122,8 @@ public class SubmoduleStatus { } /** + * Get HEAD object id + * * @return HEAD object id */ public ObjectId getHeadId() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/submodule/SubmoduleWalk.java b/org.eclipse.jgit/src/org/eclipse/jgit/submodule/SubmoduleWalk.java index 56784f7a76..2314cf10df 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/submodule/SubmoduleWalk.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/submodule/SubmoduleWalk.java @@ -81,7 +81,7 @@ import org.eclipse.jgit.util.FS; public class SubmoduleWalk implements AutoCloseable { /** - * The values for the config param submodule.<name>.ignore + * The values for the config parameter submodule.<name>.ignore * * @since 3.6 */ @@ -114,8 +114,9 @@ public class SubmoduleWalk implements AutoCloseable { * The {@code .gitmodules} file is read from the index. * * @param repository + * a {@link org.eclipse.jgit.lib.Repository} object. * @return generator over submodule index entries - * @throws IOException + * @throws java.io.IOException */ public static SubmoduleWalk forIndex(Repository repository) throws IOException { @@ -135,12 +136,14 @@ public class SubmoduleWalk implements AutoCloseable { * path * * @param repository + * a {@link org.eclipse.jgit.lib.Repository} object. * @param treeId - * the root of a tree containing both a submodule at the given path - * and .gitmodules at the root. + * the root of a tree containing both a submodule at the given + * path and .gitmodules at the root. * @param path + * a {@link java.lang.String} object. * @return generator at given path, null if no submodule at given path - * @throws IOException + * @throws java.io.IOException */ public static SubmoduleWalk forPath(Repository repository, AnyObjectId treeId, String path) throws IOException { @@ -166,12 +169,14 @@ public class SubmoduleWalk implements AutoCloseable { * path * * @param repository + * a {@link org.eclipse.jgit.lib.Repository} object. * @param iterator - * the root of a tree containing both a submodule at the given path - * and .gitmodules at the root. + * the root of a tree containing both a submodule at the given + * path and .gitmodules at the root. * @param path + * a {@link java.lang.String} object. * @return generator at given path, null if no submodule at given path - * @throws IOException + * @throws java.io.IOException */ public static SubmoduleWalk forPath(Repository repository, AbstractTreeIterator iterator, String path) throws IOException { @@ -196,7 +201,9 @@ public class SubmoduleWalk implements AutoCloseable { * Get submodule directory * * @param parent + * the {@link org.eclipse.jgit.lib.Repository}. * @param path + * submodule path * @return directory */ public static File getSubmoduleDirectory(final Repository parent, @@ -208,25 +215,47 @@ public class SubmoduleWalk implements AutoCloseable { * Get submodule repository * * @param parent + * the {@link org.eclipse.jgit.lib.Repository}. * @param path + * submodule path * @return repository or null if repository doesn't exist - * @throws IOException + * @throws java.io.IOException */ public static Repository getSubmoduleRepository(final Repository parent, final String path) throws IOException { - return getSubmoduleRepository(parent.getWorkTree(), path); + return getSubmoduleRepository(parent.getWorkTree(), path, + parent.getFS()); } /** * Get submodule repository at path * * @param parent + * the parent * @param path + * submodule path * @return repository or null if repository doesn't exist - * @throws IOException + * @throws java.io.IOException */ public static Repository getSubmoduleRepository(final File parent, final String path) throws IOException { + return getSubmoduleRepository(parent, path, FS.DETECTED); + } + + /** + * Get submodule repository at path, using the specified file system + * abstraction + * + * @param parent + * @param path + * @param fs + * the file system abstraction to be used + * @return repository or null if repository doesn't exist + * @throws IOException + * @since 4.10 + */ + public static Repository getSubmoduleRepository(final File parent, + final String path, FS fs) throws IOException { File subWorkTree = new File(parent, path); if (!subWorkTree.isDirectory()) return null; @@ -234,7 +263,7 @@ public class SubmoduleWalk implements AutoCloseable { try { return new RepositoryBuilder() // .setMustExist(true) // - .setFS(FS.DETECTED) // + .setFS(fs) // .setWorkTree(workTree) // .build(); } catch (RepositoryNotFoundException e) { @@ -257,7 +286,7 @@ public class SubmoduleWalk implements AutoCloseable { * @param url * absolute or relative URL of the submodule repository * @return resolved URL - * @throws IOException + * @throws java.io.IOException */ public static String getSubmoduleRemoteUrl(final Repository parent, final String url) throws IOException { @@ -337,7 +366,8 @@ public class SubmoduleWalk implements AutoCloseable { * Create submodule generator * * @param repository - * @throws IOException + * the {@link org.eclipse.jgit.lib.Repository}. + * @throws java.io.IOException */ public SubmoduleWalk(final Repository repository) throws IOException { this.repository = repository; @@ -394,7 +424,7 @@ public class SubmoduleWalk implements AutoCloseable { * @param id * ID of a tree containing .gitmodules * @return this generator - * @throws IOException + * @throws java.io.IOException */ public SubmoduleWalk setRootTree(final AnyObjectId id) throws IOException { final CanonicalTreeParser p = new CanonicalTreeParser(); @@ -414,8 +444,9 @@ public class SubmoduleWalk implements AutoCloseable { * If no submodule config is found, loads an empty config. * * @return this generator - * @throws IOException if an error occurred, or if the repository is bare - * @throws ConfigInvalidException + * @throws java.io.IOException + * if an error occurred, or if the repository is bare + * @throws org.eclipse.jgit.errors.ConfigInvalidException */ public SubmoduleWalk loadModulesConfig() throws IOException, ConfigInvalidException { if (rootTree == null) { @@ -483,8 +514,8 @@ public class SubmoduleWalk implements AutoCloseable { * @return <code>true</code> if the working tree contains a .gitmodules file, * <code>false</code> otherwise. Always returns <code>false</code> * for bare repositories. - * @throws IOException - * @throws CorruptObjectException + * @throws java.io.IOException + * @throws CorruptObjectException if any. * @since 3.6 */ public static boolean containsGitModulesFile(Repository repository) @@ -512,6 +543,7 @@ public class SubmoduleWalk implements AutoCloseable { * Set tree filter * * @param filter + * a {@link org.eclipse.jgit.treewalk.filter.TreeFilter} object. * @return this generator */ public SubmoduleWalk setFilter(TreeFilter filter) { @@ -523,8 +555,10 @@ public class SubmoduleWalk implements AutoCloseable { * Set the tree iterator used for finding submodule entries * * @param iterator + * an {@link org.eclipse.jgit.treewalk.AbstractTreeIterator} + * object. * @return this generator - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException */ public SubmoduleWalk setTree(final AbstractTreeIterator iterator) throws CorruptObjectException { @@ -536,10 +570,13 @@ public class SubmoduleWalk implements AutoCloseable { * Set the tree used for finding submodule entries * * @param treeId + * an {@link org.eclipse.jgit.lib.AnyObjectId} object. * @return this generator - * @throws IOException + * @throws java.io.IOException * @throws IncorrectObjectTypeException + * if any. * @throws MissingObjectException + * if any. */ public SubmoduleWalk setTree(final AnyObjectId treeId) throws IOException { walk.addTree(treeId); @@ -575,7 +612,7 @@ public class SubmoduleWalk implements AutoCloseable { * {@link #getObjectId()} and {@link #getPath()}. * * @return true if entry found, false otherwise - * @throws IOException + * @throws java.io.IOException */ public boolean next() throws IOException { while (walk.next()) { @@ -598,6 +635,15 @@ public class SubmoduleWalk implements AutoCloseable { } /** + * The module name for the current submodule entry (used for the section name of .git/config) + * @since 4.10 + * @return name + */ + public String getModuleName() { + return getModuleName(path); + } + + /** * Get object id of current submodule entry * * @return object id @@ -611,13 +657,13 @@ public class SubmoduleWalk implements AutoCloseable { * the .gitmodules file in the current repository's working tree. * * @return configured path - * @throws ConfigInvalidException - * @throws IOException + * @throws org.eclipse.jgit.errors.ConfigInvalidException + * @throws java.io.IOException */ public String getModulesPath() throws IOException, ConfigInvalidException { lazyLoadModulesConfig(); return modulesConfig.getString(ConfigConstants.CONFIG_SUBMODULE_SECTION, - getModuleName(path), ConfigConstants.CONFIG_KEY_PATH); + getModuleName(), ConfigConstants.CONFIG_KEY_PATH); } /** @@ -625,16 +671,12 @@ public class SubmoduleWalk implements AutoCloseable { * from the repository's config. * * @return configured URL - * @throws ConfigInvalidException - * @throws IOException + * @throws org.eclipse.jgit.errors.ConfigInvalidException + * @throws java.io.IOException */ public String getConfigUrl() throws IOException, ConfigInvalidException { - // SubmoduleInitCommand copies the submodules.*.url and - // submodules.*.update values from .gitmodules to the config, and - // does so using the path defined in .gitmodules as the subsection - // name. So no path-to-name translation is necessary here. return repoConfig.getString(ConfigConstants.CONFIG_SUBMODULE_SECTION, - path, ConfigConstants.CONFIG_KEY_URL); + getModuleName(), ConfigConstants.CONFIG_KEY_URL); } /** @@ -642,13 +684,13 @@ public class SubmoduleWalk implements AutoCloseable { * from the .gitmodules file in the current repository's working tree. * * @return configured URL - * @throws ConfigInvalidException - * @throws IOException + * @throws org.eclipse.jgit.errors.ConfigInvalidException + * @throws java.io.IOException */ public String getModulesUrl() throws IOException, ConfigInvalidException { lazyLoadModulesConfig(); return modulesConfig.getString(ConfigConstants.CONFIG_SUBMODULE_SECTION, - getModuleName(path), ConfigConstants.CONFIG_KEY_URL); + getModuleName(), ConfigConstants.CONFIG_KEY_URL); } /** @@ -656,12 +698,12 @@ public class SubmoduleWalk implements AutoCloseable { * from the repository's config. * * @return update value - * @throws ConfigInvalidException - * @throws IOException + * @throws org.eclipse.jgit.errors.ConfigInvalidException + * @throws java.io.IOException */ public String getConfigUpdate() throws IOException, ConfigInvalidException { return repoConfig.getString(ConfigConstants.CONFIG_SUBMODULE_SECTION, - path, ConfigConstants.CONFIG_KEY_UPDATE); + getModuleName(), ConfigConstants.CONFIG_KEY_UPDATE); } /** @@ -669,13 +711,13 @@ public class SubmoduleWalk implements AutoCloseable { * from the .gitmodules file in the current repository's working tree. * * @return update value - * @throws ConfigInvalidException - * @throws IOException + * @throws org.eclipse.jgit.errors.ConfigInvalidException + * @throws java.io.IOException */ public String getModulesUpdate() throws IOException, ConfigInvalidException { lazyLoadModulesConfig(); return modulesConfig.getString(ConfigConstants.CONFIG_SUBMODULE_SECTION, - getModuleName(path), ConfigConstants.CONFIG_KEY_UPDATE); + getModuleName(), ConfigConstants.CONFIG_KEY_UPDATE); } /** @@ -683,15 +725,15 @@ public class SubmoduleWalk implements AutoCloseable { * value from the .gitmodules file in the current repository's working tree. * * @return ignore value - * @throws ConfigInvalidException - * @throws IOException + * @throws org.eclipse.jgit.errors.ConfigInvalidException + * @throws java.io.IOException * @since 3.6 */ public IgnoreSubmoduleMode getModulesIgnore() throws IOException, ConfigInvalidException { lazyLoadModulesConfig(); return modulesConfig.getEnum(IgnoreSubmoduleMode.values(), - ConfigConstants.CONFIG_SUBMODULE_SECTION, getModuleName(path), + ConfigConstants.CONFIG_SUBMODULE_SECTION, getModuleName(), ConfigConstants.CONFIG_KEY_IGNORE, IgnoreSubmoduleMode.NONE); } @@ -699,7 +741,7 @@ public class SubmoduleWalk implements AutoCloseable { * Get repository for current submodule entry * * @return repository or null if non-existent - * @throws IOException + * @throws java.io.IOException */ public Repository getRepository() throws IOException { return getSubmoduleRepository(repository, path); @@ -709,7 +751,7 @@ public class SubmoduleWalk implements AutoCloseable { * Get commit id that HEAD points to in the current submodule's repository * * @return object id of HEAD reference - * @throws IOException + * @throws java.io.IOException */ public ObjectId getHead() throws IOException { Repository subRepo = getRepository(); @@ -726,7 +768,7 @@ public class SubmoduleWalk implements AutoCloseable { * Get ref that HEAD points to in the current submodule's repository * * @return ref name, null on failures - * @throws IOException + * @throws java.io.IOException */ public String getHeadRef() throws IOException { Repository subRepo = getRepository(); @@ -747,8 +789,8 @@ public class SubmoduleWalk implements AutoCloseable { * URL * * @return resolved remote URL - * @throws IOException - * @throws ConfigInvalidException + * @throws java.io.IOException + * @throws org.eclipse.jgit.errors.ConfigInvalidException */ public String getRemoteUrl() throws IOException, ConfigInvalidException { String url = getModulesUrl(); @@ -756,6 +798,8 @@ public class SubmoduleWalk implements AutoCloseable { } /** + * {@inheritDoc} + * <p> * Release any resources used by this walker's reader. * * @since 4.0 diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/AbstractAdvertiseRefsHook.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/AbstractAdvertiseRefsHook.java index 6f1369458c..4bf0d2692a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/AbstractAdvertiseRefsHook.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/AbstractAdvertiseRefsHook.java @@ -51,12 +51,13 @@ import org.eclipse.jgit.lib.Repository; import org.eclipse.jgit.revwalk.RevWalk; /** - * Implementation of {@link AdvertiseRefsHook} that advertises the same refs for + * Implementation of {@link org.eclipse.jgit.transport.AdvertiseRefsHook} that advertises the same refs for * upload-pack and receive-pack. * * @since 2.0 */ public abstract class AbstractAdvertiseRefsHook implements AdvertiseRefsHook { + /** {@inheritDoc} */ @Override public void advertiseRefs(UploadPack uploadPack) throws ServiceMayNotContinueException { @@ -64,6 +65,7 @@ public abstract class AbstractAdvertiseRefsHook implements AdvertiseRefsHook { uploadPack.getRepository(), uploadPack.getRevWalk())); } + /** {@inheritDoc} */ @Override public void advertiseRefs(BaseReceivePack receivePack) throws ServiceMayNotContinueException { @@ -82,7 +84,7 @@ public abstract class AbstractAdvertiseRefsHook implements AdvertiseRefsHook { * @param revWalk * open rev walk on the repository. * @return set of refs to advertise. - * @throws ServiceMayNotContinueException + * @throws org.eclipse.jgit.transport.ServiceMayNotContinueException * abort; the message will be sent to the user. */ protected abstract Map<String, Ref> getAdvertisedRefs( @@ -97,8 +99,8 @@ public abstract class AbstractAdvertiseRefsHook implements AdvertiseRefsHook { * @param revWalk * open rev walk on the repository. * @return set of additional haves; see - * {@link ReceivePack#getAdvertisedObjects()}. - * @throws ServiceMayNotContinueException + * {@link org.eclipse.jgit.transport.ReceivePack#getAdvertisedObjects()}. + * @throws org.eclipse.jgit.transport.ServiceMayNotContinueException * abort; the message will be sent to the user. */ protected Set<ObjectId> getAdvertisedHaves( diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/AdvertiseRefsHook.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/AdvertiseRefsHook.java index 96d7c240c3..ed05c733f3 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/AdvertiseRefsHook.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/AdvertiseRefsHook.java @@ -70,10 +70,11 @@ public interface AdvertiseRefsHook { /** * Advertise refs for upload-pack. * - * @param uploadPack instance on which to call - * {@link UploadPack#setAdvertisedRefs(java.util.Map)} + * @param uploadPack + * instance on which to call + * {@link org.eclipse.jgit.transport.UploadPack#setAdvertisedRefs(java.util.Map)} * if necessary. - * @throws ServiceMayNotContinueException + * @throws org.eclipse.jgit.transport.ServiceMayNotContinueException * abort; the message will be sent to the user. */ public void advertiseRefs(UploadPack uploadPack) @@ -82,10 +83,11 @@ public interface AdvertiseRefsHook { /** * Advertise refs for receive-pack. * - * @param receivePack instance on which to call - * {@link BaseReceivePack#setAdvertisedRefs(java.util.Map,java.util.Set)} + * @param receivePack + * instance on which to call + * {@link org.eclipse.jgit.transport.BaseReceivePack#setAdvertisedRefs(java.util.Map,java.util.Set)} * if necessary. - * @throws ServiceMayNotContinueException + * @throws org.eclipse.jgit.transport.ServiceMayNotContinueException * abort; the message will be sent to the user. */ public void advertiseRefs(BaseReceivePack receivePack) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/AdvertiseRefsHookChain.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/AdvertiseRefsHookChain.java index 22ea5cba9a..4ef3e1a974 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/AdvertiseRefsHookChain.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/AdvertiseRefsHookChain.java @@ -46,13 +46,14 @@ package org.eclipse.jgit.transport; import java.util.List; /** - * {@link AdvertiseRefsHook} that delegates to a list of other hooks. + * {@link org.eclipse.jgit.transport.AdvertiseRefsHook} that delegates to a list + * of other hooks. * <p> * Hooks are run in the order passed to the constructor. A hook may inspect or * modify the results of the previous hooks in the chain by calling - * {@link UploadPack#getAdvertisedRefs()}, or - * {@link BaseReceivePack#getAdvertisedRefs()} or - * {@link BaseReceivePack#getAdvertisedObjects()}. + * {@link org.eclipse.jgit.transport.UploadPack#getAdvertisedRefs()}, or + * {@link org.eclipse.jgit.transport.BaseReceivePack#getAdvertisedRefs()} or + * {@link org.eclipse.jgit.transport.BaseReceivePack#getAdvertisedObjects()}. */ public class AdvertiseRefsHookChain implements AdvertiseRefsHook { private final AdvertiseRefsHook[] hooks; @@ -79,6 +80,7 @@ public class AdvertiseRefsHookChain implements AdvertiseRefsHook { return new AdvertiseRefsHookChain(newHooks, i); } + /** {@inheritDoc} */ @Override public void advertiseRefs(BaseReceivePack rp) throws ServiceMayNotContinueException { @@ -86,6 +88,7 @@ public class AdvertiseRefsHookChain implements AdvertiseRefsHook { hooks[i].advertiseRefs(rp); } + /** {@inheritDoc} */ @Override public void advertiseRefs(UploadPack rp) throws ServiceMayNotContinueException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/AmazonS3.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/AmazonS3.java index 64cb4ddba8..fee71eb362 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/AmazonS3.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/AmazonS3.java @@ -43,6 +43,8 @@ package org.eclipse.jgit.transport; +import static java.nio.charset.StandardCharsets.UTF_8; + import java.io.ByteArrayOutputStream; import java.io.File; import java.io.FileInputStream; @@ -229,7 +231,6 @@ public class AmazonS3 { * * @param props * connection properties. - * */ public AmazonS3(final Properties props) { domain = props.getProperty(Keys.DOMAIN, "s3.amazonaws.com"); //$NON-NLS-1$ @@ -279,7 +280,7 @@ public class AmazonS3 { * @return connection to stream the content of the object. The request * properties of the connection may not be modified by the caller as * the request parameters have already been signed. - * @throws IOException + * @throws java.io.IOException * sending the request was not possible. */ public URLConnection get(final String bucket, final String key) @@ -308,7 +309,7 @@ public class AmazonS3 { * @param u * connection previously created by {@link #get(String, String)}}. * @return stream to read plain text from. - * @throws IOException + * @throws java.io.IOException * decryption could not be configured. */ public InputStream decrypt(final URLConnection u) throws IOException { @@ -331,7 +332,7 @@ public class AmazonS3 { * @return list of keys starting with <code>prefix</code>, after removing * <code>prefix</code> (or <code>prefix + "/"</code>)from all * of them. - * @throws IOException + * @throws java.io.IOException * sending the request was not possible, or the response XML * document could not be parsed properly. */ @@ -355,7 +356,7 @@ public class AmazonS3 { * name of the bucket storing the object. * @param key * key of the object within its bucket. - * @throws IOException + * @throws java.io.IOException * deletion failed due to communications error. */ public void delete(final String bucket, final String key) @@ -392,7 +393,7 @@ public class AmazonS3 { * @param data * new data content for the object. Must not be null. Zero length * array will create a zero length object. - * @throws IOException + * @throws java.io.IOException * creation/updating failed due to communications error. */ public void put(final String bucket, final String key, final byte[] data) @@ -461,7 +462,7 @@ public class AmazonS3 { * @param monitorTask * (optional) task name to display during the close method. * @return a stream which accepts the new data, and transmits once closed. - * @throws IOException + * @throws java.io.IOException * if encryption was enabled it could not be configured. */ public OutputStream beginPut(final String bucket, final String key, @@ -642,7 +643,7 @@ public class AmazonS3 { try { final Mac m = Mac.getInstance(HMAC); m.init(privateKey); - sec = Base64.encodeBytes(m.doFinal(s.toString().getBytes("UTF-8"))); //$NON-NLS-1$ + sec = Base64.encodeBytes(m.doFinal(s.toString().getBytes(UTF_8))); } catch (NoSuchAlgorithmException e) { throw new IOException(MessageFormat.format(JGitText.get().noHMACsupport, HMAC, e.getMessage())); } catch (InvalidKeyException e) { @@ -705,10 +706,10 @@ public class AmazonS3 { try { xr.parse(new InputSource(in)); } catch (SAXException parsingError) { - final IOException p; - p = new IOException(MessageFormat.format(JGitText.get().errorListing, prefix)); - p.initCause(parsingError); - throw p; + throw new IOException( + MessageFormat.format( + JGitText.get().errorListing, prefix), + parsingError); } finally { in.close(); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/BaseConnection.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/BaseConnection.java index 69028fab31..c8d1d229b5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/BaseConnection.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/BaseConnection.java @@ -71,31 +71,34 @@ public abstract class BaseConnection implements Connection { private Writer messageWriter; + /** {@inheritDoc} */ @Override public Map<String, Ref> getRefsMap() { return advertisedRefs; } + /** {@inheritDoc} */ @Override public final Collection<Ref> getRefs() { return advertisedRefs.values(); } + /** {@inheritDoc} */ @Override public final Ref getRef(final String name) { return advertisedRefs.get(name); } + /** {@inheritDoc} */ @Override public String getMessages() { return messageWriter != null ? messageWriter.toString() : ""; //$NON-NLS-1$ } /** - * User agent advertised by the remote server. + * {@inheritDoc} * - * @return agent (version of Git) running on the remote server. Null if the - * server does not advertise this version. + * User agent advertised by the remote server. * @since 4.0 */ @Override @@ -114,6 +117,7 @@ public abstract class BaseConnection implements Connection { peerUserAgent = agent; } + /** {@inheritDoc} */ @Override public abstract void close(); @@ -136,7 +140,7 @@ public abstract class BaseConnection implements Connection { * Helper method for ensuring one-operation per connection. Check whether * operation was already marked as started, and mark it as started. * - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * if operation was already marked as started. */ protected void markStartedOperation() throws TransportException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/BaseFetchConnection.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/BaseFetchConnection.java index 41b8c2d765..6f460251c0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/BaseFetchConnection.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/BaseFetchConnection.java @@ -64,6 +64,7 @@ import org.eclipse.jgit.lib.Ref; */ abstract class BaseFetchConnection extends BaseConnection implements FetchConnection { + /** {@inheritDoc} */ @Override public final void fetch(final ProgressMonitor monitor, final Collection<Ref> want, final Set<ObjectId> have) @@ -71,6 +72,7 @@ abstract class BaseFetchConnection extends BaseConnection implements fetch(monitor, want, have, null); } + /** {@inheritDoc} */ @Override public final void fetch(final ProgressMonitor monitor, final Collection<Ref> want, final Set<ObjectId> have, @@ -80,6 +82,8 @@ abstract class BaseFetchConnection extends BaseConnection implements } /** + * {@inheritDoc} + * * Default implementation of {@link FetchConnection#didFetchIncludeTags()} - * returning false. */ @@ -98,7 +102,7 @@ abstract class BaseFetchConnection extends BaseConnection implements * as in {@link #fetch(ProgressMonitor, Collection, Set)} * @param have * as in {@link #fetch(ProgressMonitor, Collection, Set)} - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * as in {@link #fetch(ProgressMonitor, Collection, Set)}, but * implementation doesn't have to care about multiple * {@link #fetch(ProgressMonitor, Collection, Set)} calls, as it diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/BasePackConnection.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/BasePackConnection.java index c69544930d..e9227e33a3 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/BasePackConnection.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/BasePackConnection.java @@ -170,9 +170,9 @@ abstract class BasePackConnection extends BaseConnection { * <p> * If any errors occur, this connection is automatically closed by invoking * {@link #close()} and the exception is wrapped (if necessary) and thrown - * as a {@link TransportException}. + * as a {@link org.eclipse.jgit.errors.TransportException}. * - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * the reference list could not be scanned. */ protected void readAdvertisedRefs() throws TransportException { @@ -267,10 +267,26 @@ abstract class BasePackConnection extends BaseConnection { return new NoRemoteRepositoryException(uri, JGitText.get().notFound); } + /** + * Whether this option is supported + * + * @param option + * option string + * @return whether this option is supported + */ protected boolean isCapableOf(final String option) { return remoteCapablities.contains(option); } + /** + * Request capability + * + * @param b + * buffer + * @param option + * option we want + * @return {@code true} if the requested option is supported + */ protected boolean wantCapability(final StringBuilder b, final String option) { if (!isCapableOf(option)) return false; @@ -279,6 +295,12 @@ abstract class BasePackConnection extends BaseConnection { return true; } + /** + * Add user agent capability + * + * @param b + * a {@link java.lang.StringBuilder} object. + */ protected void addUserAgentCapability(StringBuilder b) { String a = UserAgent.get(); if (a != null && UserAgent.hasAgent(remoteCapablities)) { @@ -286,6 +308,7 @@ abstract class BasePackConnection extends BaseConnection { } } + /** {@inheritDoc} */ @Override public String getPeerUserAgent() { return UserAgent.getAgent(remoteCapablities, super.getPeerUserAgent()); @@ -295,6 +318,7 @@ abstract class BasePackConnection extends BaseConnection { return new PackProtocolException(uri, MessageFormat.format(JGitText.get().duplicateAdvertisementsOf, name)); } + /** {@inheritDoc} */ @Override public void close() { if (out != null) { @@ -334,7 +358,9 @@ abstract class BasePackConnection extends BaseConnection { } } - /** Tell the peer we are disconnecting, if it cares to know. */ + /** + * Tell the peer we are disconnecting, if it cares to know. + */ protected void endOut() { if (outNeedsEnd && out != null) { try { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/BasePackFetchConnection.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/BasePackFetchConnection.java index 61c4c4b172..19d8abe9e0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/BasePackFetchConnection.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/BasePackFetchConnection.java @@ -94,10 +94,10 @@ import org.eclipse.jgit.util.TemporaryBuffer; * easily wrapped up into a local process pipe, anonymous TCP socket, or a * command executed through an SSH tunnel. * <p> - * If {@link BasePackConnection#statelessRPC} is {@code true}, this connection - * can be tunneled over a request-response style RPC system like HTTP. The RPC - * call boundary is determined by this class switching from writing to the - * OutputStream to reading from the InputStream. + * If {@link org.eclipse.jgit.transport.BasePackConnection#statelessRPC} is + * {@code true}, this connection can be tunneled over a request-response style + * RPC system like HTTP. The RPC call boundary is determined by this class + * switching from writing to the OutputStream to reading from the InputStream. * <p> * Concrete implementations should just call * {@link #init(java.io.InputStream, java.io.OutputStream)} and @@ -285,6 +285,7 @@ public abstract class BasePackFetchConnection extends BasePackConnection } } + /** {@inheritDoc} */ @Override public final void fetch(final ProgressMonitor monitor, final Collection<Ref> want, final Set<ObjectId> have) @@ -292,9 +293,7 @@ public abstract class BasePackFetchConnection extends BasePackConnection fetch(monitor, want, have, null); } - /** - * @since 3.0 - */ + /** {@inheritDoc} */ @Override public final void fetch(final ProgressMonitor monitor, final Collection<Ref> want, final Set<ObjectId> have, @@ -303,21 +302,25 @@ public abstract class BasePackFetchConnection extends BasePackConnection doFetch(monitor, want, have, outputStream); } + /** {@inheritDoc} */ @Override public boolean didFetchIncludeTags() { return false; } + /** {@inheritDoc} */ @Override public boolean didFetchTestConnectivity() { return false; } + /** {@inheritDoc} */ @Override public void setPackLockMessage(final String message) { lockMessage = message; } + /** {@inheritDoc} */ @Override public Collection<PackLock> getPackLocks() { if (packLock != null) @@ -330,7 +333,7 @@ public abstract class BasePackFetchConnection extends BasePackConnection * * @param monitor * progress monitor to receive status updates. If the monitor is - * the {@link NullProgressMonitor#INSTANCE}, then the no-progress + * the {@link org.eclipse.jgit.lib.NullProgressMonitor#INSTANCE}, then the no-progress * option enabled. * @param want * the advertised remote references the caller wants to fetch. @@ -340,7 +343,7 @@ public abstract class BasePackFetchConnection extends BasePackConnection * destination repository's references. * @param outputStream * ouputStream to write sideband messages to - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * if any exception occurs. * @since 3.0 */ @@ -380,6 +383,7 @@ public abstract class BasePackFetchConnection extends BasePackConnection } } + /** {@inheritDoc} */ @Override public void close() { if (walk != null) @@ -776,7 +780,7 @@ public abstract class BasePackFetchConnection extends BasePackConnection /** * Notification event delivered just before the pack is received from the - * network. This event can be used by RPC such as {@link TransportHttp} to + * network. This event can be used by RPC such as {@link org.eclipse.jgit.transport.TransportHttp} to * disable its request magic and ensure the pack stream is read correctly. * * @since 2.0 diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/BasePackPushConnection.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/BasePackPushConnection.java index 679ea0c8fd..ee6f29ed0a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/BasePackPushConnection.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/BasePackPushConnection.java @@ -81,7 +81,8 @@ import org.eclipse.jgit.transport.RemoteRefUpdate.Status; * easily wrapped up into a local process pipe, anonymous TCP socket, or a * command executed through an SSH tunnel. * <p> - * This implementation honors {@link Transport#isPushThin()} option. + * This implementation honors + * {@link org.eclipse.jgit.transport.Transport#isPushThin()} option. * <p> * Concrete implementations should just call * {@link #init(java.io.InputStream, java.io.OutputStream)} and @@ -152,6 +153,7 @@ public abstract class BasePackPushConnection extends BasePackConnection implemen pushOptions = transport.getPushOptions(); } + /** {@inheritDoc} */ @Override public void push(final ProgressMonitor monitor, final Map<String, RemoteRefUpdate> refUpdates) @@ -159,9 +161,7 @@ public abstract class BasePackPushConnection extends BasePackConnection implemen push(monitor, refUpdates, null); } - /** - * @since 3.0 - */ + /** {@inheritDoc} */ @Override public void push(final ProgressMonitor monitor, final Map<String, RemoteRefUpdate> refUpdates, OutputStream outputStream) @@ -170,6 +170,7 @@ public abstract class BasePackPushConnection extends BasePackConnection implemen doPush(monitor, refUpdates, outputStream); } + /** {@inheritDoc} */ @Override protected TransportException noRepository() { // Sadly we cannot tell the "invalid URI" case from "push not allowed". @@ -202,7 +203,7 @@ public abstract class BasePackPushConnection extends BasePackConnection implemen * update commands to be applied to the remote repository. * @param outputStream * output stream to write sideband messages to - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * if any exception occurs. * @since 3.0 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/BaseReceivePack.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/BaseReceivePack.java index 44abcd598b..e97f71a488 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/BaseReceivePack.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/BaseReceivePack.java @@ -405,15 +405,27 @@ public abstract class BaseReceivePack { } } - /** @return the process name used for pack lock messages. */ + /** + * Get the process name used for pack lock messages. + * + * @return the process name used for pack lock messages. + */ protected abstract String getLockMessageProcessName(); - /** @return the repository this receive completes into. */ + /** + * Get the repository this receive completes into. + * + * @return the repository this receive completes into. + */ public final Repository getRepository() { return db; } - /** @return the RevWalk instance used by this connection. */ + /** + * Get the RevWalk instance used by this connection. + * + * @return the RevWalk instance used by this connection. + */ public final RevWalk getRevWalk() { return walk; } @@ -431,14 +443,15 @@ public abstract class BaseReceivePack { /** * Set the refs advertised by this ReceivePack. * <p> - * Intended to be called from a {@link PreReceiveHook}. + * Intended to be called from a + * {@link org.eclipse.jgit.transport.PreReceiveHook}. * * @param allRefs * explicit set of references to claim as advertised by this - * ReceivePack instance. This overrides any references that - * may exist in the source repository. The map is passed - * to the configured {@link #getRefFilter()}. If null, assumes - * all refs were advertised. + * ReceivePack instance. This overrides any references that may + * exist in the source repository. The map is passed to the + * configured {@link #getRefFilter()}. If null, assumes all refs + * were advertised. * @param additionalHaves * explicit set of additional haves to claim as advertised. If * null, assumes the default set of additional haves from the @@ -475,6 +488,9 @@ public abstract class BaseReceivePack { } /** + * Whether this instance will validate all referenced, but not supplied by + * the client, objects are reachable from another reference. + * * @return true if this instance will validate all referenced, but not * supplied by the client, objects are reachable from another * reference. @@ -493,8 +509,9 @@ public abstract class BaseReceivePack { * This feature is useful when the application doesn't trust the client to * not provide a forged SHA-1 reference to an object, in an attempt to * access parts of the DAG that they aren't allowed to see and which have - * been hidden from them via the configured {@link AdvertiseRefsHook} or - * {@link RefFilter}. + * been hidden from them via the configured + * {@link org.eclipse.jgit.transport.AdvertiseRefsHook} or + * {@link org.eclipse.jgit.transport.RefFilter}. * <p> * Enabling this feature may imply at least some, if not all, of the same * functionality performed by {@link #setCheckReceivedObjects(boolean)}. @@ -508,6 +525,9 @@ public abstract class BaseReceivePack { } /** + * Whether this class expects a bi-directional pipe opened between the + * client and itself. + * * @return true if this class expects a bi-directional pipe opened between * the client and itself. The default is true. */ @@ -516,6 +536,10 @@ public abstract class BaseReceivePack { } /** + * Whether this class will assume the socket is a fully bidirectional pipe + * between the two peers and takes advantage of that by first transmitting + * the known refs, then waiting to read commands. + * * @param twoWay * if true, this class will assume the socket is a fully * bidirectional pipe between the two peers and takes advantage @@ -528,32 +552,44 @@ public abstract class BaseReceivePack { biDirectionalPipe = twoWay; } - /** @return true if there is data expected after the pack footer. */ + /** + * Whether there is data expected after the pack footer. + * + * @return {@code true} if there is data expected after the pack footer. + */ public boolean isExpectDataAfterPackFooter() { return expectDataAfterPackFooter; } /** + * Whether there is additional data in InputStream after pack. + * * @param e - * true if there is additional data in InputStream after pack. + * {@code true} if there is additional data in InputStream after + * pack. */ public void setExpectDataAfterPackFooter(boolean e) { expectDataAfterPackFooter = e; } /** - * @return true if this instance will verify received objects are formatted - * correctly. Validating objects requires more CPU time on this side - * of the connection. + * Whether this instance will verify received objects are formatted + * correctly. + * + * @return {@code true} if this instance will verify received objects are + * formatted correctly. Validating objects requires more CPU time on + * this side of the connection. */ public boolean isCheckReceivedObjects() { return objectChecker != null; } /** + * Whether to enable checking received objects + * * @param check - * true to enable checking received objects; false to assume all - * received objects are valid. + * {@code true} to enable checking received objects; false to + * assume all received objects are valid. * @see #setObjectChecker(ObjectChecker) */ public void setCheckReceivedObjects(final boolean check) { @@ -564,42 +600,59 @@ public abstract class BaseReceivePack { } /** - * @param impl if non-null the object checking instance to verify each - * received object with; null to disable object checking. + * Set the object checking instance to verify each received object with + * + * @param impl + * if non-null the object checking instance to verify each + * received object with; null to disable object checking. * @since 3.4 */ public void setObjectChecker(ObjectChecker impl) { objectChecker = impl; } - /** @return true if the client can request refs to be created. */ + /** + * Whether the client can request refs to be created. + * + * @return {@code true} if the client can request refs to be created. + */ public boolean isAllowCreates() { return allowCreates; } /** + * Whether to permit create ref commands to be processed. + * * @param canCreate - * true to permit create ref commands to be processed. + * {@code true} to permit create ref commands to be processed. */ public void setAllowCreates(final boolean canCreate) { allowCreates = canCreate; } - /** @return true if the client can request refs to be deleted. */ + /** + * Whether the client can request refs to be deleted. + * + * @return {@code true} if the client can request refs to be deleted. + */ public boolean isAllowDeletes() { return allowAnyDeletes; } /** + * Whether to permit delete ref commands to be processed. + * * @param canDelete - * true to permit delete ref commands to be processed. + * {@code true} to permit delete ref commands to be processed. */ public void setAllowDeletes(final boolean canDelete) { allowAnyDeletes = canDelete; } /** - * @return true if the client can delete from {@code refs/heads/}. + * Whether the client can delete from {@code refs/heads/}. + * + * @return {@code true} if the client can delete from {@code refs/heads/}. * @since 3.6 */ public boolean isAllowBranchDeletes() { @@ -607,8 +660,11 @@ public abstract class BaseReceivePack { } /** + * Configure whether to permit deletion of branches from the + * {@code refs/heads/} namespace. + * * @param canDelete - * true to permit deletion of branches from the + * {@code true} to permit deletion of branches from the * {@code refs/heads/} namespace. * @since 3.6 */ @@ -617,25 +673,34 @@ public abstract class BaseReceivePack { } /** - * @return true if the client can request non-fast-forward updates of a ref, - * possibly making objects unreachable. + * Whether the client can request non-fast-forward updates of a ref, + * possibly making objects unreachable. + * + * @return {@code true} if the client can request non-fast-forward updates + * of a ref, possibly making objects unreachable. */ public boolean isAllowNonFastForwards() { return allowNonFastForwards; } /** + * Configure whether to permit the client to ask for non-fast-forward + * updates of an existing ref. + * * @param canRewind - * true to permit the client to ask for non-fast-forward updates - * of an existing ref. + * {@code true} to permit the client to ask for non-fast-forward + * updates of an existing ref. */ public void setAllowNonFastForwards(final boolean canRewind) { allowNonFastForwards = canRewind; } /** - * @return true if the client's commands should be performed as a single - * atomic transaction. + * Whether the client's commands should be performed as a single atomic + * transaction. + * + * @return {@code true} if the client's commands should be performed as a + * single atomic transaction. * @since 4.4 */ public boolean isAtomic() { @@ -643,16 +708,23 @@ public abstract class BaseReceivePack { } /** + * Configure whether to perform the client's commands as a single atomic + * transaction. + * * @param atomic - * true to perform the client's commands as a single atomic - * transaction. + * {@code true} to perform the client's commands as a single + * atomic transaction. * @since 4.4 */ public void setAtomic(boolean atomic) { this.atomic = atomic; } - /** @return identity of the user making the changes in the reflog. */ + /** + * Get identity of the user making the changes in the reflog. + * + * @return identity of the user making the changes in the reflog. + */ public PersonIdent getRefLogIdent() { return refLogIdent; } @@ -673,12 +745,20 @@ public abstract class BaseReceivePack { refLogIdent = pi; } - /** @return the hook used while advertising the refs to the client */ + /** + * Get the hook used while advertising the refs to the client + * + * @return the hook used while advertising the refs to the client + */ public AdvertiseRefsHook getAdvertiseRefsHook() { return advertiseRefsHook; } - /** @return the filter used while advertising the refs to the client */ + /** + * Get the filter used while advertising the refs to the client + * + * @return the filter used while advertising the refs to the client + */ public RefFilter getRefFilter() { return refFilter; } @@ -686,12 +766,14 @@ public abstract class BaseReceivePack { /** * Set the hook used while advertising the refs to the client. * <p> - * If the {@link AdvertiseRefsHook} chooses to call - * {@link #setAdvertisedRefs(Map,Set)}, only refs set by this hook - * <em>and</em> selected by the {@link RefFilter} will be shown to the client. - * Clients may still attempt to create or update a reference not advertised by - * the configured {@link AdvertiseRefsHook}. These attempts should be rejected - * by a matching {@link PreReceiveHook}. + * If the {@link org.eclipse.jgit.transport.AdvertiseRefsHook} chooses to + * call {@link #setAdvertisedRefs(Map,Set)}, only refs set by this hook + * <em>and</em> selected by the {@link org.eclipse.jgit.transport.RefFilter} + * will be shown to the client. Clients may still attempt to create or + * update a reference not advertised by the configured + * {@link org.eclipse.jgit.transport.AdvertiseRefsHook}. These attempts + * should be rejected by a matching + * {@link org.eclipse.jgit.transport.PreReceiveHook}. * * @param advertiseRefsHook * the hook; may be null to show all refs. @@ -706,9 +788,9 @@ public abstract class BaseReceivePack { /** * Set the filter used while advertising the refs to the client. * <p> - * Only refs allowed by this filter will be shown to the client. - * The filter is run against the refs specified by the - * {@link AdvertiseRefsHook} (if applicable). + * Only refs allowed by this filter will be shown to the client. The filter + * is run against the refs specified by the + * {@link org.eclipse.jgit.transport.AdvertiseRefsHook} (if applicable). * * @param refFilter * the filter; may be null to show all refs. @@ -717,7 +799,11 @@ public abstract class BaseReceivePack { this.refFilter = refFilter != null ? refFilter : RefFilter.DEFAULT; } - /** @return timeout (in seconds) before aborting an IO operation. */ + /** + * Get timeout (in seconds) before aborting an IO operation. + * + * @return timeout (in seconds) before aborting an IO operation. + */ public int getTimeout() { return timeout; } @@ -786,7 +872,6 @@ public abstract class BaseReceivePack { * * @param limit * the pack size limit, in bytes - * * @since 3.3 */ public void setMaxPackSizeLimit(final long limit) { @@ -801,7 +886,7 @@ public abstract class BaseReceivePack { * * @return true if the client has advertised a side-band capability, false * otherwise. - * @throws RequestNotYetReadException + * @throws org.eclipse.jgit.transport.RequestNotYetReadException * if the client's request has not yet been read from the wire, so * we do not know if they expect side-band. Note that the client * may have already written the request, it just has not been @@ -813,6 +898,8 @@ public abstract class BaseReceivePack { } /** + * Whether clients may request avoiding noisy progress messages. + * * @return true if clients may request avoiding noisy progress messages. * @since 4.0 */ @@ -835,6 +922,8 @@ public abstract class BaseReceivePack { } /** + * Whether the server supports receiving push options. + * * @return true if the server supports receiving push options. * @since 4.5 */ @@ -857,7 +946,7 @@ public abstract class BaseReceivePack { * True if the client wants less verbose output. * * @return true if the client has requested the server to be less verbose. - * @throws RequestNotYetReadException + * @throws org.eclipse.jgit.transport.RequestNotYetReadException * if the client's request has not yet been read from the wire, * so we do not know if they expect side-band. Note that the * client may have already written the request, it just has not @@ -908,7 +997,11 @@ public abstract class BaseReceivePack { return UserAgent.getAgent(enabledCapabilities, userAgent); } - /** @return all of the command received by the current request. */ + /** + * Get all of the command received by the current request. + * + * @return all of the command received by the current request. + */ public List<ReceiveCommand> getAllCommands() { return Collections.unmodifiableList(commands); } @@ -926,11 +1019,13 @@ public abstract class BaseReceivePack { * message will be discarded, with no other indication to the caller or to * the client. * <p> - * {@link PreReceiveHook}s should always try to use - * {@link ReceiveCommand#setResult(Result, String)} with a result status of - * {@link Result#REJECTED_OTHER_REASON} to indicate any reasons for - * rejecting an update. Messages attached to a command are much more likely - * to be returned to the client. + * {@link org.eclipse.jgit.transport.PreReceiveHook}s should always try to + * use + * {@link org.eclipse.jgit.transport.ReceiveCommand#setResult(Result, String)} + * with a result status of + * {@link org.eclipse.jgit.transport.ReceiveCommand.Result#REJECTED_OTHER_REASON} + * to indicate any reasons for rejecting an update. Messages attached to a + * command are much more likely to be returned to the client. * * @param what * string describing the problem identified by the hook. The @@ -973,7 +1068,11 @@ public abstract class BaseReceivePack { msgOutWrapper.write(Constants.encode(what + "\n")); //$NON-NLS-1$ } - /** @return an underlying stream for sending messages to the client. */ + /** + * Get an underlying stream for sending messages to the client. + * + * @return an underlying stream for sending messages to the client. + */ public OutputStream getMessageOutputStream() { return msgOutWrapper; } @@ -984,7 +1083,7 @@ public abstract class BaseReceivePack { * This can only be called if the pack is already received. * * @return the size of the received pack including index size - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * if called before the pack has been received * @since 3.3 */ @@ -1006,12 +1105,20 @@ public abstract class BaseReceivePack { return clientShallowCommits; } - /** @return true if any commands to be executed have been read. */ + /** + * Whether any commands to be executed have been read. + * + * @return {@code true} if any commands to be executed have been read. + */ protected boolean hasCommands() { return !commands.isEmpty(); } - /** @return true if an error occurred that should be advertised. */ + /** + * Whether an error occurred that should be advertised. + * + * @return true if an error occurred that should be advertised. + */ protected boolean hasError() { return advertiseError != null; } @@ -1059,7 +1166,11 @@ public abstract class BaseReceivePack { commands = new ArrayList<>(); } - /** @return advertised refs, or the default if not explicitly advertised. */ + /** + * Get advertised refs, or the default if not explicitly advertised. + * + * @return advertised refs, or the default if not explicitly advertised. + */ protected Map<String, Ref> getAdvertisedOrDefaultRefs() { if (refs == null) setAdvertisedRefs(null, null); @@ -1069,7 +1180,7 @@ public abstract class BaseReceivePack { /** * Receive a pack from the stream and check connectivity if necessary. * - * @throws IOException + * @throws java.io.IOException * an error occurred during unpacking or connectivity checking. */ protected void receivePackAndCheckConnectivity() throws IOException { @@ -1082,7 +1193,7 @@ public abstract class BaseReceivePack { /** * Unlock the pack written by this object. * - * @throws IOException + * @throws java.io.IOException * the pack could not be unlocked. */ protected void unlockPack() throws IOException { @@ -1097,9 +1208,9 @@ public abstract class BaseReceivePack { * * @param adv * the advertisement formatter. - * @throws IOException + * @throws java.io.IOException * the formatter failed to write an advertisement. - * @throws ServiceMayNotContinueException + * @throws org.eclipse.jgit.transport.ServiceMayNotContinueException * the hook denied advertisement. */ public void sendAdvertisedRefs(final RefAdvertiser adv) @@ -1160,7 +1271,7 @@ public abstract class BaseReceivePack { /** * Receive a list of commands from the input. * - * @throws IOException + * @throws java.io.IOException */ protected void recvCommands() throws IOException { PacketLineIn pck = maxCommandBytes > 0 @@ -1289,7 +1400,9 @@ public abstract class BaseReceivePack { // Do nothing by default. } - /** Enable capabilities based on a previously read capabilities line. */ + /** + * Enable capabilities based on a previously read capabilities line. + */ protected void enableCapabilities() { sideBand = isCapabilityEnabled(CAPABILITY_SIDE_BAND_64K); quiet = allowQuiet && isCapabilityEnabled(CAPABILITY_QUIET); @@ -1321,7 +1434,11 @@ public abstract class BaseReceivePack { throw new RequestNotYetReadException(); } - /** @return true if a pack is expected based on the list of commands. */ + /** + * Whether a pack is expected based on the list of commands. + * + * @return {@code true} if a pack is expected based on the list of commands. + */ protected boolean needPack() { for (final ReceiveCommand cmd : commands) { if (cmd.getType() != ReceiveCommand.Type.DELETE) @@ -1475,7 +1592,9 @@ public abstract class BaseReceivePack { } } - /** Validate the command list. */ + /** + * Validate the command list. + */ protected void validateCommands() { for (final ReceiveCommand cmd : commands) { final Ref ref = cmd.getRef(); @@ -1612,6 +1731,8 @@ public abstract class BaseReceivePack { } /** + * Whether any commands have been rejected so far. + * * @return if any commands have been rejected so far. * @since 3.6 */ @@ -1625,6 +1746,7 @@ public abstract class BaseReceivePack { /** * Set the result to fail for any command that was not processed yet. + * * @since 3.6 */ protected void failPendingCommands() { @@ -1643,7 +1765,9 @@ public abstract class BaseReceivePack { return ReceiveCommand.filter(commands, want); } - /** Execute commands to update references. */ + /** + * Execute commands to update references. + */ protected void executeCommands() { List<ReceiveCommand> toApply = filterCommands(Result.NOT_ATTEMPTED); if (toApply.isEmpty()) @@ -1683,7 +1807,7 @@ public abstract class BaseReceivePack { * an error that occurred during unpacking, or {@code null} * @param out * the reporter for sending the status strings. - * @throws IOException + * @throws java.io.IOException * an error occurred writing the status report. */ protected void sendStatusReport(final boolean forClient, @@ -1770,7 +1894,7 @@ public abstract class BaseReceivePack { /** * Close and flush (if necessary) the underlying streams. * - * @throws IOException + * @throws java.io.IOException */ protected void close() throws IOException { if (sideBand) { @@ -1802,7 +1926,7 @@ public abstract class BaseReceivePack { /** * Release any resources used by this object. * - * @throws IOException + * @throws java.io.IOException * the pack could not be unlocked. */ protected void release() throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/BundleFetchConnection.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/BundleFetchConnection.java index f37ba01034..39efabf5d8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/BundleFetchConnection.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/BundleFetchConnection.java @@ -180,11 +180,13 @@ class BundleFetchConnection extends BaseFetchConnection { return line.toString(); } + /** {@inheritDoc} */ @Override public boolean didFetchTestConnectivity() { return false; } + /** {@inheritDoc} */ @Override protected void doFetch(final ProgressMonitor monitor, final Collection<Ref> want, final Set<ObjectId> have) @@ -208,11 +210,13 @@ class BundleFetchConnection extends BaseFetchConnection { } } + /** {@inheritDoc} */ @Override public void setPackLockMessage(final String message) { lockMessage = message; } + /** {@inheritDoc} */ @Override public Collection<PackLock> getPackLocks() { if (packLock != null) @@ -290,6 +294,7 @@ class BundleFetchConnection extends BaseFetchConnection { } } + /** {@inheritDoc} */ @Override public void close() { if (bin != null) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/BundleWriter.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/BundleWriter.java index 0920f21563..35ac7792e6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/BundleWriter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/BundleWriter.java @@ -70,7 +70,7 @@ import org.eclipse.jgit.storage.pack.PackConfig; * <p> * Bundles generated by this class can be later read in from a file URI using * the bundle transport, or from an application controlled buffer by the more - * generic {@link TransportBundleStream}. + * generic {@link org.eclipse.jgit.transport.TransportBundleStream}. * <p> * Applications creating bundles need to call one or more <code>include</code> * calls to reflect which objects should be available as refs in the bundle for @@ -208,13 +208,10 @@ public class BundleWriter { * the stream the bundle is written to. The stream should be * buffered by the caller. The caller is responsible for closing * the stream. - * @throws IOException + * @throws java.io.IOException * an error occurred reading a local object's data to include in * the bundle, or writing compressed object data to the output * stream. - * @throws WriteAbortedException - * the write operation is aborted by - * {@link ObjectCountCallback}. */ public void writeBundle(ProgressMonitor monitor, OutputStream os) throws IOException { @@ -270,17 +267,16 @@ public class BundleWriter { } /** - * Set the {@link ObjectCountCallback}. + * Set the {@link org.eclipse.jgit.transport.ObjectCountCallback}. * <p> * It should be set before calling * {@link #writeBundle(ProgressMonitor, OutputStream)}. * <p> * This callback will be passed on to - * {@link PackWriter#setObjectCountCallback}. + * {@link org.eclipse.jgit.internal.storage.pack.PackWriter#setObjectCountCallback}. * * @param callback * the callback to set - * * @return this object for chaining. * @since 4.1 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/ChainingCredentialsProvider.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/ChainingCredentialsProvider.java index 8cb3d604cf..9f05d5a548 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/ChainingCredentialsProvider.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/ChainingCredentialsProvider.java @@ -72,11 +72,7 @@ public class ChainingCredentialsProvider extends CredentialsProvider { Arrays.asList(providers)); } - /** - * @return {@code true} if any of the credential providers in the list is - * interactive, otherwise {@code false} - * @see org.eclipse.jgit.transport.CredentialsProvider#isInteractive() - */ + /** {@inheritDoc} */ @Override public boolean isInteractive() { for (CredentialsProvider p : credentialProviders) @@ -85,11 +81,7 @@ public class ChainingCredentialsProvider extends CredentialsProvider { return false; } - /** - * @return {@code true} if any of the credential providers in the list - * supports the requested items, otherwise {@code false} - * @see org.eclipse.jgit.transport.CredentialsProvider#supports(org.eclipse.jgit.transport.CredentialItem[]) - */ + /** {@inheritDoc} */ @Override public boolean supports(CredentialItem... items) { for (CredentialsProvider p : credentialProviders) @@ -99,11 +91,11 @@ public class ChainingCredentialsProvider extends CredentialsProvider { } /** + * {@inheritDoc} + * <p> * Populates the credential items with the credentials provided by the first * credential provider in the list which populates them with non-null values * - * @return {@code true} if any of the credential providers in the list - * supports the requested items, otherwise {@code false} * @see org.eclipse.jgit.transport.CredentialsProvider#supports(org.eclipse.jgit.transport.CredentialItem[]) */ @Override diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/Connection.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/Connection.java index 9a272a4fdd..bcc5110e73 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/Connection.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/Connection.java @@ -98,6 +98,8 @@ public interface Connection extends AutoCloseable { public Ref getRef(final String name); /** + * {@inheritDoc} + * <p> * Close any resources used by this connection. * <p> * If the remote repository is contacted by a network socket this method diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/CredentialItem.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/CredentialItem.java index 88e075adc9..3a74f1d9e1 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/CredentialItem.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/CredentialItem.java @@ -48,14 +48,19 @@ import java.util.Arrays; import org.eclipse.jgit.internal.JGitText; /** - * A credential requested from a {@link CredentialsProvider}. + * A credential requested from a + * {@link org.eclipse.jgit.transport.CredentialsProvider}. * * Most users should work with the specialized subclasses: * <ul> - * <li>{@link Username} for usernames</li> - * <li>{@link Password} for passwords</li> - * <li>{@link StringType} for other general string information</li> - * <li>{@link CharArrayType} for other general secret information</li> + * <li>{@link org.eclipse.jgit.transport.CredentialItem.Username} for + * usernames</li> + * <li>{@link org.eclipse.jgit.transport.CredentialItem.Password} for + * passwords</li> + * <li>{@link org.eclipse.jgit.transport.CredentialItem.StringType} for other + * general string information</li> + * <li>{@link org.eclipse.jgit.transport.CredentialItem.CharArrayType} for other + * general secret information</li> * </ul> * * This class is not thread-safe. Applications should construct their own @@ -83,17 +88,27 @@ public abstract class CredentialItem { this.valueSecure = maskValue; } - /** @return prompt to display to the user. */ + /** + * Get prompt to display to the user. + * + * @return prompt to display to the user. + */ public String getPromptText() { return promptText; } - /** @return true if the value should be masked when entered. */ + /** + * Whether the value should be masked when entered. + * + * @return true if the value should be masked when entered. + */ public boolean isValueSecure() { return valueSecure; } - /** Clear the stored value, destroying it as much as possible. */ + /** + * Clear the stored value, destroying it as much as possible. + */ public abstract void clear(); /** diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/CredentialsProvider.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/CredentialsProvider.java index 4800f6826f..8115946204 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/CredentialsProvider.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/CredentialsProvider.java @@ -52,9 +52,10 @@ import org.eclipse.jgit.errors.UnsupportedCredentialItem; * Provide credentials for use in connecting to Git repositories. * * Implementors are strongly encouraged to support at least the minimal - * {@link CredentialItem.Username} and {@link CredentialItem.Password} items. - * More sophisticated implementors may implement additional types, such as - * {@link CredentialItem.StringType}. + * {@link org.eclipse.jgit.transport.CredentialItem.Username} and + * {@link org.eclipse.jgit.transport.CredentialItem.Password} items. More + * sophisticated implementors may implement additional types, such as + * {@link org.eclipse.jgit.transport.CredentialItem.StringType}. * * CredentialItems are usually presented in bulk, allowing implementors to * combine them into a single UI widget and streamline the authentication @@ -65,7 +66,11 @@ import org.eclipse.jgit.errors.UnsupportedCredentialItem; public abstract class CredentialsProvider { private static volatile CredentialsProvider defaultProvider; - /** @return the default credentials provider, or null. */ + /** + * Get the default credentials provider, or null. + * + * @return the default credentials provider, or null. + */ public static CredentialsProvider getDefault() { return defaultProvider; } @@ -81,6 +86,8 @@ public abstract class CredentialsProvider { } /** + * Whether any of the passed items is null + * * @param items * credential items to check * @return {@code true} if any of the passed items is null, {@code false} @@ -106,12 +113,14 @@ public abstract class CredentialsProvider { public abstract boolean isInteractive(); /** - * Check if the provider can supply the necessary {@link CredentialItem}s. + * Check if the provider can supply the necessary + * {@link org.eclipse.jgit.transport.CredentialItem}s. * * @param items * the items the application requires to complete authentication. - * @return {@code true} if this {@link CredentialsProvider} supports all of - * the items supplied. + * @return {@code true} if this + * {@link org.eclipse.jgit.transport.CredentialsProvider} supports + * all of the items supplied. */ public abstract boolean supports(CredentialItem... items); @@ -125,7 +134,7 @@ public abstract class CredentialsProvider { * @return {@code true} if the request was successful and values were * supplied; {@code false} if the user canceled the request and did * not supply all requested values. - * @throws UnsupportedCredentialItem + * @throws org.eclipse.jgit.errors.UnsupportedCredentialItem * if one of the items supplied is not supported. */ public abstract boolean get(URIish uri, CredentialItem... items) @@ -141,7 +150,7 @@ public abstract class CredentialsProvider { * @return {@code true} if the request was successful and values were * supplied; {@code false} if the user canceled the request and did * not supply all requested values. - * @throws UnsupportedCredentialItem + * @throws org.eclipse.jgit.errors.UnsupportedCredentialItem * if one of the items supplied is not supported. */ public boolean get(URIish uri, List<CredentialItem> items) @@ -153,6 +162,7 @@ public abstract class CredentialsProvider { * Reset the credentials provider for the given URI * * @param uri + * a {@link org.eclipse.jgit.transport.URIish} object. */ public void reset(URIish uri) { // default does nothing diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/CredentialsProviderUserInfo.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/CredentialsProviderUserInfo.java index 83586350be..d901021788 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/CredentialsProviderUserInfo.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/CredentialsProviderUserInfo.java @@ -51,7 +51,10 @@ import com.jcraft.jsch.Session; import com.jcraft.jsch.UIKeyboardInteractive; import com.jcraft.jsch.UserInfo; -/** A JSch {@link UserInfo} adapter for a {@link CredentialsProvider}. */ +/** + * A JSch {@link com.jcraft.jsch.UserInfo} adapter for a + * {@link org.eclipse.jgit.transport.CredentialsProvider}. + */ public class CredentialsProviderUserInfo implements UserInfo, UIKeyboardInteractive { private final URIish uri; @@ -85,16 +88,19 @@ public class CredentialsProviderUserInfo implements UserInfo, return uri; } + /** {@inheritDoc} */ @Override public String getPassword() { return password; } + /** {@inheritDoc} */ @Override public String getPassphrase() { return passphrase; } + /** {@inheritDoc} */ @Override public boolean promptPassphrase(String msg) { CredentialItem.StringType v = newPrompt(msg); @@ -107,6 +113,7 @@ public class CredentialsProviderUserInfo implements UserInfo, } } + /** {@inheritDoc} */ @Override public boolean promptPassword(String msg) { CredentialItem.Password p = new CredentialItem.Password(msg); @@ -123,17 +130,20 @@ public class CredentialsProviderUserInfo implements UserInfo, return new CredentialItem.StringType(msg, true); } + /** {@inheritDoc} */ @Override public boolean promptYesNo(String msg) { CredentialItem.YesNoType v = new CredentialItem.YesNoType(msg); return provider.get(uri, v) && v.getValue(); } + /** {@inheritDoc} */ @Override public void showMessage(String msg) { provider.get(uri, new CredentialItem.InformationalMessage(msg)); } + /** {@inheritDoc} */ @Override public String[] promptKeyboardInteractive(String destination, String name, String instruction, String[] prompt, boolean[] echo) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/Daemon.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/Daemon.java index 896b10a4ec..2fc5eb2b51 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/Daemon.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/Daemon.java @@ -65,7 +65,9 @@ import org.eclipse.jgit.transport.resolver.ServiceNotAuthorizedException; import org.eclipse.jgit.transport.resolver.ServiceNotEnabledException; import org.eclipse.jgit.transport.resolver.UploadPackFactory; -/** Basic daemon for the anonymous <code>git://</code> transport protocol. */ +/** + * Basic daemon for the anonymous <code>git://</code> transport protocol. + */ public class Daemon { /** 9418: IANA assigned port number for Git. */ public static final int DEFAULT_PORT = 9418; @@ -90,7 +92,9 @@ public class Daemon { volatile ReceivePackFactory<DaemonClient> receivePackFactory; - /** Configure a daemon to listen on any available network port. */ + /** + * Configure a daemon to listen on any available network port. + */ public Daemon() { this(null); } @@ -175,7 +179,11 @@ public class Daemon { } }; } - /** @return the address connections are received on. */ + /** + * Get the address connections are received on. + * + * @return the address connections are received on. + */ public synchronized InetSocketAddress getAddress() { return myAddress; } @@ -199,7 +207,11 @@ public class Daemon { return null; } - /** @return timeout (in seconds) before aborting an IO operation. */ + /** + * Get timeout (in seconds) before aborting an IO operation. + * + * @return timeout (in seconds) before aborting an IO operation. + */ public int getTimeout() { return timeout; } @@ -216,7 +228,11 @@ public class Daemon { timeout = seconds; } - /** @return configuration controlling packing, may be null. */ + /** + * Get configuration controlling packing, may be null. + * + * @return configuration controlling packing, may be null. + */ public PackConfig getPackConfig() { return packConfig; } @@ -333,9 +349,9 @@ public class Daemon { /** * Start this daemon on a background thread. * - * @throws IOException + * @throws java.io.IOException * the server socket could not be opened. - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * the daemon is already running. */ public synchronized void start() throws IOException { @@ -359,7 +375,11 @@ public class Daemon { acceptThread = null; } - /** @return true if this daemon is receiving connections. */ + /** + * Whether this daemon is receiving connections. + * + * @return {@code true} if this daemon is receiving connections. + */ public synchronized boolean isRunning() { return acceptThread != null && acceptThread.isRunning(); } @@ -376,9 +396,8 @@ public class Daemon { /** * Stops this daemon and waits until it's acceptor thread has finished. * - * @throws InterruptedException + * @throws java.lang.InterruptedException * if waiting for the acceptor thread is interrupted - * * @since 4.9 */ public void stopAndWait() throws InterruptedException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/DaemonClient.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/DaemonClient.java index 23e3379f91..a9731ac3a4 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/DaemonClient.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/DaemonClient.java @@ -54,7 +54,9 @@ import java.net.Socket; import org.eclipse.jgit.transport.resolver.ServiceNotAuthorizedException; import org.eclipse.jgit.transport.resolver.ServiceNotEnabledException; -/** Active network client of {@link Daemon}. */ +/** + * Active network client of {@link org.eclipse.jgit.transport.Daemon}. + */ public class DaemonClient { private final Daemon daemon; @@ -72,22 +74,38 @@ public class DaemonClient { peer = ia; } - /** @return the daemon which spawned this client. */ + /** + * Get the daemon which spawned this client. + * + * @return the daemon which spawned this client. + */ public Daemon getDaemon() { return daemon; } - /** @return Internet address of the remote client. */ + /** + * Get Internet address of the remote client. + * + * @return Internet address of the remote client. + */ public InetAddress getRemoteAddress() { return peer; } - /** @return input stream to read from the connected client. */ + /** + * Get input stream to read from the connected client. + * + * @return input stream to read from the connected client. + */ public InputStream getInputStream() { return rawIn; } - /** @return output stream to send data to the connected client. */ + /** + * Get output stream to send data to the connected client. + * + * @return output stream to send data to the connected client. + */ public OutputStream getOutputStream() { return rawOut; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/DaemonService.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/DaemonService.java index 566153a333..e0ec7751b9 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/DaemonService.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/DaemonService.java @@ -52,7 +52,10 @@ import org.eclipse.jgit.lib.Repository; import org.eclipse.jgit.transport.resolver.ServiceNotAuthorizedException; import org.eclipse.jgit.transport.resolver.ServiceNotEnabledException; -/** A service exposed by {@link Daemon} over anonymous <code>git://</code>. */ +/** + * A service exposed by {@link org.eclipse.jgit.transport.Daemon} over anonymous + * <code>git://</code>. + */ public abstract class DaemonService { private final String command; @@ -77,34 +80,55 @@ public abstract class DaemonService { } } - /** @return is this service enabled for invocation? */ + /** + * Whether this service is enabled for invocation. + * + * @return whether this service is enabled for invocation. + */ public boolean isEnabled() { return enabled; } /** + * Set if it is allowed to use this service + * * @param on - * true to allow this service to be used; false to deny it. + * {@code true} to allow this service to be used; {@code false} + * to deny it. */ public void setEnabled(final boolean on) { enabled = on; } /** @return can this service be configured in the repository config file? */ + /** + * Whether this service can be configured in the repository config file + * + * @return whether this service can be configured in the repository config + * file + */ public boolean isOverridable() { return overridable; } /** + * Whether to permit repositories to override this service's enabled state + * with the <code>daemon.servicename</code> config setting. + * * @param on - * true to permit repositories to override this service's enabled - * state with the <code>daemon.servicename</code> config setting. + * {@code true} to permit repositories to override this service's + * enabled state with the <code>daemon.servicename</code> config + * setting. */ public void setOverridable(final boolean on) { overridable = on; } - /** @return name of the command requested by clients. */ + /** + * Get name of the command requested by clients. + * + * @return name of the command requested by clients. + */ public String getCommandName() { return command; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/DefaultSshSessionFactory.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/DefaultSshSessionFactory.java index 23fd7e39c5..a749fbcaf0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/DefaultSshSessionFactory.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/DefaultSshSessionFactory.java @@ -59,6 +59,7 @@ import com.jcraft.jsch.Session; * connection will immediately fail. */ class DefaultSshSessionFactory extends JschConfigSessionFactory { + /** {@inheritDoc} */ @Override protected void configure(final OpenSshConfig.Host hc, final Session session) { // No additional configuration required. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/FetchConnection.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/FetchConnection.java index 2d042400f6..f0c45d5fb6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/FetchConnection.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/FetchConnection.java @@ -64,9 +64,9 @@ import org.eclipse.jgit.lib.Ref; * one-way object transfer service to copy objects from the remote repository * into this local repository. * <p> - * Instances of a FetchConnection must be created by a {@link Transport} that - * implements a specific object transfer protocol that both sides of the - * connection understand. + * Instances of a FetchConnection must be created by a + * {@link org.eclipse.jgit.transport.Transport} that implements a specific + * object transfer protocol that both sides of the connection understand. * <p> * FetchConnection instances are not thread safe and may be accessed by only one * thread at a time. @@ -78,7 +78,7 @@ public interface FetchConnection extends Connection { * Fetch objects we don't have but that are reachable from advertised refs. * <p> * Only one call per connection is allowed. Subsequent calls will result in - * {@link TransportException}. + * {@link org.eclipse.jgit.errors.TransportException}. * </p> * <p> * Implementations are free to use network connections as necessary to @@ -87,7 +87,8 @@ public interface FetchConnection extends Connection { * avoid replacing/overwriting/duplicating an object already available in * the local destination repository. Locally available objects and packs * should always be preferred over remotely available objects and packs. - * {@link Transport#isFetchThin()} should be honored if applicable. + * {@link org.eclipse.jgit.transport.Transport#isFetchThin()} should be + * honored if applicable. * </p> * * @param monitor @@ -103,7 +104,7 @@ public interface FetchConnection extends Connection { * repository, especially if they aren't yet reachable by the ref * database. Connections should take this set as an addition to * what is reachable through all Refs, not in replace of it. - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * objects could not be copied due to a network failure, * protocol error, or error on remote side, or connection was * already used for fetch. @@ -116,7 +117,7 @@ public interface FetchConnection extends Connection { * Fetch objects we don't have but that are reachable from advertised refs. * <p> * Only one call per connection is allowed. Subsequent calls will result in - * {@link TransportException}. + * {@link org.eclipse.jgit.errors.TransportException}. * </p> * <p> * Implementations are free to use network connections as necessary to @@ -125,7 +126,8 @@ public interface FetchConnection extends Connection { * avoid replacing/overwriting/duplicating an object already available in * the local destination repository. Locally available objects and packs * should always be preferred over remotely available objects and packs. - * {@link Transport#isFetchThin()} should be honored if applicable. + * {@link org.eclipse.jgit.transport.Transport#isFetchThin()} should be + * honored if applicable. * </p> * * @param monitor @@ -143,7 +145,7 @@ public interface FetchConnection extends Connection { * what is reachable through all Refs, not in replace of it. * @param out * OutputStream to write sideband messages to - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * objects could not be copied due to a network failure, * protocol error, or error on remote side, or connection was * already used for fetch. @@ -157,11 +159,12 @@ public interface FetchConnection extends Connection { * Did the last {@link #fetch(ProgressMonitor, Collection, Set)} get tags? * <p> * Some Git aware transports are able to implicitly grab an annotated tag if - * {@link TagOpt#AUTO_FOLLOW} or {@link TagOpt#FETCH_TAGS} was selected and - * the object the tag peels to (references) was transferred as part of the - * last {@link #fetch(ProgressMonitor, Collection, Set)} call. If it is - * possible for such tags to have been included in the transfer this method - * returns true, allowing the caller to attempt tag discovery. + * {@link org.eclipse.jgit.transport.TagOpt#AUTO_FOLLOW} or + * {@link org.eclipse.jgit.transport.TagOpt#FETCH_TAGS} was selected and the + * object the tag peels to (references) was transferred as part of the last + * {@link #fetch(ProgressMonitor, Collection, Set)} call. If it is possible + * for such tags to have been included in the transfer this method returns + * true, allowing the caller to attempt tag discovery. * <p> * By returning only true/false (and not the actual list of tags obtained) * the transport itself does not need to be aware of whether or not tags diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/HMACSHA1NonceGenerator.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/HMACSHA1NonceGenerator.java index d43be8974c..6c26b7026a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/HMACSHA1NonceGenerator.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/HMACSHA1NonceGenerator.java @@ -42,8 +42,10 @@ */ package org.eclipse.jgit.transport; +import static java.nio.charset.StandardCharsets.ISO_8859_1; +import static java.nio.charset.StandardCharsets.UTF_8; + import java.io.File; -import java.io.UnsupportedEncodingException; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; @@ -64,12 +66,15 @@ public class HMACSHA1NonceGenerator implements NonceGenerator { private Mac mac; /** + * Constructor for HMACSHA1NonceGenerator. + * * @param seed - * @throws IllegalStateException + * seed the generator + * @throws java.lang.IllegalStateException */ public HMACSHA1NonceGenerator(String seed) throws IllegalStateException { try { - byte[] keyBytes = seed.getBytes("ISO-8859-1"); //$NON-NLS-1$ + byte[] keyBytes = seed.getBytes(ISO_8859_1); SecretKeySpec signingKey = new SecretKeySpec(keyBytes, "HmacSHA1"); //$NON-NLS-1$ mac = Mac.getInstance("HmacSHA1"); //$NON-NLS-1$ mac.init(signingKey); @@ -77,11 +82,10 @@ public class HMACSHA1NonceGenerator implements NonceGenerator { throw new IllegalStateException(e); } catch (NoSuchAlgorithmException e) { throw new IllegalStateException(e); - } catch (UnsupportedEncodingException e) { - throw new IllegalStateException(e); } } + /** {@inheritDoc} */ @Override public synchronized String createNonce(Repository repo, long timestamp) throws IllegalStateException { @@ -98,15 +102,11 @@ public class HMACSHA1NonceGenerator implements NonceGenerator { } String input = path + ":" + String.valueOf(timestamp); //$NON-NLS-1$ - byte[] rawHmac; - try { - rawHmac = mac.doFinal(input.getBytes("UTF-8")); //$NON-NLS-1$ - } catch (UnsupportedEncodingException e) { - throw new IllegalStateException(e); - } + byte[] rawHmac = mac.doFinal(input.getBytes(UTF_8)); return Long.toString(timestamp) + "-" + toHex(rawHmac); //$NON-NLS-1$ } + /** {@inheritDoc} */ @Override public NonceStatus verify(String received, String sent, Repository db, boolean allowSlop, int slop) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/HttpAuthMethod.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/HttpAuthMethod.java index c97daa958f..c40d9635de 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/HttpAuthMethod.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/HttpAuthMethod.java @@ -43,11 +43,11 @@ package org.eclipse.jgit.transport; +import static java.nio.charset.StandardCharsets.UTF_8; import static org.eclipse.jgit.util.HttpSupport.HDR_AUTHORIZATION; import static org.eclipse.jgit.util.HttpSupport.HDR_WWW_AUTHENTICATE; import java.io.IOException; -import java.io.UnsupportedEncodingException; import java.net.URL; import java.security.MessageDigest; import java.security.NoSuchAlgorithmException; @@ -204,6 +204,12 @@ abstract class HttpAuthMethod { protected final Type type; + /** + * Constructor for HttpAuthMethod. + * + * @param type + * authentication method type + */ protected HttpAuthMethod(Type type) { this.type = type; } @@ -309,7 +315,7 @@ abstract class HttpAuthMethod { @Override void configureRequest(final HttpConnection conn) throws IOException { String ident = user + ":" + pass; //$NON-NLS-1$ - String enc = Base64.encodeBytes(ident.getBytes("UTF-8")); //$NON-NLS-1$ + String enc = Base64.encodeBytes(ident.getBytes(UTF_8)); conn.setRequestProperty(HDR_AUTHORIZATION, type.getSchemeName() + " " + enc); //$NON-NLS-1$ } @@ -423,25 +429,17 @@ abstract class HttpAuthMethod { } private static String H(String data) { - try { - MessageDigest md = newMD5(); - md.update(data.getBytes("UTF-8")); //$NON-NLS-1$ - return LHEX(md.digest()); - } catch (UnsupportedEncodingException e) { - throw new RuntimeException("UTF-8 encoding not available", e); //$NON-NLS-1$ - } + MessageDigest md = newMD5(); + md.update(data.getBytes(UTF_8)); + return LHEX(md.digest()); } private static String KD(String secret, String data) { - try { - MessageDigest md = newMD5(); - md.update(secret.getBytes("UTF-8")); //$NON-NLS-1$ - md.update((byte) ':'); - md.update(data.getBytes("UTF-8")); //$NON-NLS-1$ - return LHEX(md.digest()); - } catch (UnsupportedEncodingException e) { - throw new RuntimeException("UTF-8 encoding not available", e); //$NON-NLS-1$ - } + MessageDigest md = newMD5(); + md.update(secret.getBytes(UTF_8)); + md.update((byte) ':'); + md.update(data.getBytes(UTF_8)); + return LHEX(md.digest()); } private static MessageDigest newMD5() { @@ -557,9 +555,7 @@ abstract class HttpAuthMethod { conn.setRequestProperty(HDR_AUTHORIZATION, getType().getSchemeName() + " " + Base64.encodeBytes(token)); //$NON-NLS-1$ } catch (GSSException e) { - IOException ioe = new IOException(); - ioe.initCause(e); - throw ioe; + throw new IOException(e); } } } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/HttpConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/HttpConfig.java index db59a54a27..101ce35685 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/HttpConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/HttpConfig.java @@ -61,10 +61,10 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** - * A representation of the "http.*" config values in a git {@link Config}. git - * provides for setting values for specific URLs through "http.<url>.* - * subsections. git always considers only the initial original URL for such - * settings, not any redirected URL. + * A representation of the "http.*" config values in a git + * {@link org.eclipse.jgit.lib.Config}. git provides for setting values for + * specific URLs through "http.<url>.*" subsections. git always considers + * only the initial original URL for such settings, not any redirected URL. * * @since 4.9 */ @@ -154,6 +154,8 @@ public class HttpConfig { private int maxRedirects; /** + * Get the "http.postBuffer" setting + * * @return the value of the "http.postBuffer" setting */ public int getPostBuffer() { @@ -161,6 +163,8 @@ public class HttpConfig { } /** + * Get the "http.sslVerify" setting + * * @return the value of the "http.sslVerify" setting */ public boolean isSslVerify() { @@ -168,6 +172,8 @@ public class HttpConfig { } /** + * Get the "http.followRedirects" setting + * * @return the value of the "http.followRedirects" setting */ public HttpRedirectMode getFollowRedirects() { @@ -175,6 +181,8 @@ public class HttpConfig { } /** + * Get the "http.maxRedirects" setting + * * @return the value of the "http.maxRedirects" setting */ public int getMaxRedirects() { @@ -182,10 +190,11 @@ public class HttpConfig { } /** - * Creates a new {@link HttpConfig} tailored to the given {@link URIish}. + * Creates a new {@link org.eclipse.jgit.transport.HttpConfig} tailored to + * the given {@link org.eclipse.jgit.transport.URIish}. * * @param config - * to read the {@link HttpConfig} from + * to read the {@link org.eclipse.jgit.transport.HttpConfig} from * @param uri * to get the configuration values for */ @@ -194,8 +203,8 @@ public class HttpConfig { } /** - * Creates a {@link HttpConfig} that reads values solely from the user - * config. + * Creates a {@link org.eclipse.jgit.transport.HttpConfig} that reads values + * solely from the user config. * * @param uri * to get the configuration values for diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/HttpTransport.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/HttpTransport.java index 006e846328..d1141868fd 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/HttpTransport.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/HttpTransport.java @@ -62,7 +62,11 @@ public abstract class HttpTransport extends Transport { protected static HttpConnectionFactory connectionFactory = new JDKHttpConnectionFactory(); /** - * @return the {@link HttpConnectionFactory} used to create new connections + * Get the {@link org.eclipse.jgit.transport.http.HttpConnectionFactory} + * used to create new connections + * + * @return the {@link org.eclipse.jgit.transport.http.HttpConnectionFactory} + * used to create new connections * @since 3.3 */ public static HttpConnectionFactory getConnectionFactory() { @@ -70,10 +74,11 @@ public abstract class HttpTransport extends Transport { } /** - * Set the {@link HttpConnectionFactory} to be used to create new - * connections + * Set the {@link org.eclipse.jgit.transport.http.HttpConnectionFactory} to + * be used to create new connections * * @param cf + * connection factory * @since 3.3 */ public static void setConnectionFactory(HttpConnectionFactory cf) { @@ -98,7 +103,7 @@ public abstract class HttpTransport extends Transport { /** * Create a minimal HTTP transport instance not tied to a single repository. * - * @param uri + * @param uri a {@link org.eclipse.jgit.transport.URIish} object. */ protected HttpTransport(URIish uri) { super(uri); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/InternalFetchConnection.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/InternalFetchConnection.java index bea8d60ecd..9fb9062fbb 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/InternalFetchConnection.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/InternalFetchConnection.java @@ -57,6 +57,21 @@ import org.eclipse.jgit.transport.resolver.UploadPackFactory; class InternalFetchConnection<C> extends BasePackFetchConnection { private Thread worker; + /** + * Constructor for InternalFetchConnection. + * + * @param transport + * a {@link org.eclipse.jgit.transport.PackTransport} + * @param uploadPackFactory + * a + * {@link org.eclipse.jgit.transport.resolver.UploadPackFactory} + * @param req + * request + * @param remote + * the remote {@link org.eclipse.jgit.lib.Repository} + * @throws org.eclipse.jgit.errors.TransportException + * if any. + */ public InternalFetchConnection(PackTransport transport, final UploadPackFactory<C> uploadPackFactory, final C req, final Repository remote) throws TransportException { @@ -125,6 +140,7 @@ class InternalFetchConnection<C> extends BasePackFetchConnection { readAdvertisedRefs(); } + /** {@inheritDoc} */ @Override public void close() { super.close(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/InternalPushConnection.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/InternalPushConnection.java index 8a1884e5fc..732be63dc1 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/InternalPushConnection.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/InternalPushConnection.java @@ -57,6 +57,21 @@ import org.eclipse.jgit.transport.resolver.ServiceNotEnabledException; class InternalPushConnection<C> extends BasePackPushConnection { private Thread worker; + /** + * Constructor for InternalPushConnection. + * + * @param transport + * a {@link org.eclipse.jgit.transport.PackTransport} + * @param receivePackFactory + * a + * {@link org.eclipse.jgit.transport.resolver.ReceivePackFactory} + * @param req + * a request + * @param remote + * the {@link org.eclipse.jgit.lib.Repository} + * @throws org.eclipse.jgit.errors.TransportException + * if any. + */ public InternalPushConnection(PackTransport transport, final ReceivePackFactory<C> receivePackFactory, final C req, final Repository remote) throws TransportException { @@ -115,6 +130,7 @@ class InternalPushConnection<C> extends BasePackPushConnection { readAdvertisedRefs(); } + /** {@inheritDoc} */ @Override public void close() { super.close(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/JschConfigSessionFactory.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/JschConfigSessionFactory.java index 0cc40f37d1..c38182741d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/JschConfigSessionFactory.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/JschConfigSessionFactory.java @@ -73,7 +73,6 @@ import com.jcraft.jsch.ConfigRepository; import com.jcraft.jsch.JSch; import com.jcraft.jsch.JSchException; import com.jcraft.jsch.Session; -import com.jcraft.jsch.UserInfo; /** * The base session factory that loads known hosts and private keys from @@ -84,8 +83,8 @@ import com.jcraft.jsch.UserInfo; * used by C Git. * <p> * The factory does not provide UI behavior. Override the method - * {@link #configure(org.eclipse.jgit.transport.OpenSshConfig.Host, Session)} - * to supply appropriate {@link UserInfo} to the session. + * {@link #configure(org.eclipse.jgit.transport.OpenSshConfig.Host, Session)} to + * supply appropriate {@link com.jcraft.jsch.UserInfo} to the session. */ public abstract class JschConfigSessionFactory extends SshSessionFactory { @@ -106,6 +105,7 @@ public abstract class JschConfigSessionFactory extends SshSessionFactory { private OpenSshConfig config; + /** {@inheritDoc} */ @Override public synchronized RemoteSession getSession(URIish uri, CredentialsProvider credentialsProvider, FS fs, int tms) @@ -263,7 +263,7 @@ public abstract class JschConfigSessionFactory extends SshSessionFactory { * the file system abstraction which will be necessary to * perform certain file system operations. * @return new session instance, but otherwise unconfigured. - * @throws JSchException + * @throws com.jcraft.jsch.JSchException * the session could not be created. */ protected Session createSession(final OpenSshConfig.Host hc, @@ -287,7 +287,8 @@ public abstract class JschConfigSessionFactory extends SshSessionFactory { /** * Provide additional configuration for the session based on the host - * information. This method could be used to supply {@link UserInfo}. + * information. This method could be used to supply + * {@link com.jcraft.jsch.UserInfo}. * * @param hc * host configuration @@ -305,7 +306,7 @@ public abstract class JschConfigSessionFactory extends SshSessionFactory { * the file system abstraction which will be necessary to * perform certain file system operations. * @return the JSch instance to use. - * @throws JSchException + * @throws com.jcraft.jsch.JSchException * the user configuration could not be created. */ protected JSch getJSch(final OpenSshConfig.Host hc, FS fs) throws JSchException { @@ -339,11 +340,13 @@ public abstract class JschConfigSessionFactory extends SshSessionFactory { } /** + * Create default instance of jsch + * * @param fs - * the file system abstraction which will be necessary to - * perform certain file system operations. + * the file system abstraction which will be necessary to perform + * certain file system operations. * @return the new default JSch implementation. - * @throws JSchException + * @throws com.jcraft.jsch.JSchException * known host keys cannot be loaded. */ protected JSch createDefaultJSch(FS fs) throws JSchException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/JschSession.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/JschSession.java index a8cc032006..081d05748c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/JschSession.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/JschSession.java @@ -66,8 +66,8 @@ import com.jcraft.jsch.Session; * Run remote commands using Jsch. * <p> * This class is the default session implementation using Jsch. Note that - * {@link JschConfigSessionFactory} is used to create the actual session passed - * to the constructor. + * {@link org.eclipse.jgit.transport.JschConfigSessionFactory} is used to create + * the actual session passed to the constructor. */ public class JschSession implements RemoteSession { final Session sock; @@ -87,11 +87,13 @@ public class JschSession implements RemoteSession { this.uri = uri; } + /** {@inheritDoc} */ @Override public Process exec(String command, int timeout) throws IOException { return new JschProcess(command, timeout); } + /** {@inheritDoc} */ @Override public void disconnect() { if (sock.isConnected()) @@ -99,12 +101,13 @@ public class JschSession implements RemoteSession { } /** - * A kludge to allow {@link TransportSftp} to get an Sftp channel from Jsch. - * Ideally, this method would be generic, which would require implementing - * generic Sftp channel operations in the RemoteSession class. + * A kludge to allow {@link org.eclipse.jgit.transport.TransportSftp} to get + * an Sftp channel from Jsch. Ideally, this method would be generic, which + * would require implementing generic Sftp channel operations in the + * RemoteSession class. * * @return a channel suitable for Sftp operations. - * @throws JSchException + * @throws com.jcraft.jsch.JSchException * on problems getting the channel. */ public Channel getSftpChannel() throws JSchException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/NetRC.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/NetRC.java index 5727b034b3..e3f287bef8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/NetRC.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/NetRC.java @@ -143,7 +143,9 @@ public class NetRC { COMMAND, MACHINE, LOGIN, PASSWORD, DEFAULT, ACCOUNT, MACDEF } - /** */ + /** + * <p>Constructor for NetRC.</p> + */ public NetRC() { netrc = getDefaultFile(); if (netrc != null) @@ -151,6 +153,8 @@ public class NetRC { } /** + * <p>Constructor for NetRC.</p> + * * @param netrc * the .netrc file */ @@ -176,6 +180,7 @@ public class NetRC { * Get entry by host name * * @param host + * the host name * @return entry associated with host name or null */ public NetRCEntry getEntry(String host) { @@ -194,6 +199,8 @@ public class NetRC { } /** + * Get all entries collected from .netrc file + * * @return all entries collected from .netrc file */ public Collection<NetRCEntry> getEntries() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/NetRCCredentialsProvider.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/NetRCCredentialsProvider.java index 4037545e9d..6531b17e23 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/NetRCCredentialsProvider.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/NetRCCredentialsProvider.java @@ -54,7 +54,9 @@ public class NetRCCredentialsProvider extends CredentialsProvider { NetRC netrc = new NetRC(); - /** */ + /** + * <p>Constructor for NetRCCredentialsProvider.</p> + */ public NetRCCredentialsProvider() { } @@ -65,6 +67,7 @@ public class NetRCCredentialsProvider extends CredentialsProvider { CredentialsProvider.setDefault(new NetRCCredentialsProvider()); } + /** {@inheritDoc} */ @Override public boolean supports(CredentialItem... items) { for (CredentialItem i : items) { @@ -78,6 +81,7 @@ public class NetRCCredentialsProvider extends CredentialsProvider { return true; } + /** {@inheritDoc} */ @Override public boolean get(URIish uri, CredentialItem... items) throws UnsupportedCredentialItem { @@ -108,6 +112,7 @@ public class NetRCCredentialsProvider extends CredentialsProvider { return !isAnyNull(items); } + /** {@inheritDoc} */ @Override public boolean isInteractive() { return false; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/NonceGenerator.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/NonceGenerator.java index d1ea089068..51fe9070c0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/NonceGenerator.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/NonceGenerator.java @@ -55,6 +55,8 @@ import org.eclipse.jgit.transport.PushCertificate.NonceStatus; public interface NonceGenerator { /** + * Create nonce to be signed by the pusher + * * @param db * The repository which should be used to obtain a unique String * such that the pusher cannot forge nonces by pushing to another @@ -62,12 +64,14 @@ public interface NonceGenerator { * @param timestamp * The current time in seconds. * @return The nonce to be signed by the pusher - * @throws IllegalStateException + * @throws java.lang.IllegalStateException */ public String createNonce(Repository db, long timestamp) throws IllegalStateException; /** + * Verify trustworthiness of the received nonce. + * * @param received * The nonce which was received from the server * @param sent @@ -76,7 +80,6 @@ public interface NonceGenerator { * The repository which should be used to obtain a unique String * such that the pusher cannot forge nonces by pushing to another * repository at the same time as well and reusing the nonce. - * * @param allowSlop * If the receiving backend is is able to generate slop. This is * the case for serving via http protocol using more than one @@ -85,7 +88,6 @@ public interface NonceGenerator { * @param slop * If `allowSlop` is true, this specifies the number of seconds * which we allow as slop. - * * @return a NonceStatus indicating the trustworthiness of the received * nonce. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/ObjectCountCallback.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/ObjectCountCallback.java index cf81adbcd0..3856bb2204 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/ObjectCountCallback.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/ObjectCountCallback.java @@ -45,7 +45,6 @@ package org.eclipse.jgit.transport; import java.io.OutputStream; -import org.eclipse.jgit.internal.storage.pack.PackWriter; import org.eclipse.jgit.lib.ProgressMonitor; /** @@ -55,19 +54,20 @@ import org.eclipse.jgit.lib.ProgressMonitor; */ public interface ObjectCountCallback { /** - * Invoked when the {@link PackWriter} has counted the objects to be - * written to pack. + * Invoked when the + * {@link org.eclipse.jgit.internal.storage.pack.PackWriter} has counted the + * objects to be written to pack. * <p> - * An {@code ObjectCountCallback} can use this information to decide - * whether the - * {@link PackWriter#writePack(ProgressMonitor, ProgressMonitor, OutputStream)} + * An {@code ObjectCountCallback} can use this information to decide whether + * the + * {@link org.eclipse.jgit.internal.storage.pack.PackWriter#writePack(ProgressMonitor, ProgressMonitor, OutputStream)} * operation should be aborted. * <p> * This callback will be called exactly once. * * @param objectCount * the count of the objects. - * @throws WriteAbortedException + * @throws org.eclipse.jgit.transport.WriteAbortedException * to indicate that the write operation should be aborted. */ void setObjectCount(long objectCount) throws WriteAbortedException; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/OpenSshConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/OpenSshConfig.java index b5d5099239..4660c40d98 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/OpenSshConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/OpenSshConfig.java @@ -84,9 +84,11 @@ import com.jcraft.jsch.ConfigRepository; * </ul> * <p> * Therefore implement our own parser to read an OpenSSH configuration file. It - * makes the critical options available to {@link SshSessionFactory} via - * {@link Host} objects returned by {@link #lookup(String)}, and implements a - * fully conforming {@link ConfigRepository} providing + * makes the critical options available to + * {@link org.eclipse.jgit.transport.SshSessionFactory} via + * {@link org.eclipse.jgit.transport.OpenSshConfig.Host} objects returned by + * {@link #lookup(String)}, and implements a fully conforming + * {@link com.jcraft.jsch.ConfigRepository} providing * {@link com.jcraft.jsch.ConfigRepository.Config}s via * {@link #getConfig(String)}. * </p> @@ -103,7 +105,7 @@ import com.jcraft.jsch.ConfigRepository; * ConfigRepository OTOH treats all option values as plain strings, so any * validation must happen in Jsch outside of the parser. Thus this parser does * not validate option values, except for a few options when constructing a - * {@link Host} object. + * {@link org.eclipse.jgit.transport.OpenSshConfig.Host} object. * </p> * <p> * This config does %-substitutions for the following tokens: @@ -960,12 +962,11 @@ public class OpenSshConfig implements ConfigRepository { } /** + * {@inheritDoc} + * <p> * Retrieves the full {@link com.jcraft.jsch.ConfigRepository.Config Config} * for the given host name. Should be called only by Jsch and tests. * - * @param hostName - * to get the config for - * @return the configuration for the host * @since 4.9 */ @Override @@ -974,6 +975,7 @@ public class OpenSshConfig implements ConfigRepository { return host.getConfig(); } + /** {@inheritDoc} */ @Override @SuppressWarnings("nls") public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PackParser.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PackParser.java index 833d2114cf..af5a0b7c98 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PackParser.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PackParser.java @@ -76,7 +76,6 @@ import org.eclipse.jgit.lib.ObjectDatabase; import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.lib.ObjectIdOwnerMap; import org.eclipse.jgit.lib.ObjectIdSubclassMap; -import org.eclipse.jgit.lib.ObjectInserter; import org.eclipse.jgit.lib.ObjectLoader; import org.eclipse.jgit.lib.ObjectReader; import org.eclipse.jgit.lib.ObjectStream; @@ -88,14 +87,16 @@ import org.eclipse.jgit.util.NB; import org.eclipse.jgit.util.sha1.SHA1; /** - * Parses a pack stream and imports it for an {@link ObjectInserter}. + * Parses a pack stream and imports it for an + * {@link org.eclipse.jgit.lib.ObjectInserter}. * <p> * Applications can acquire an instance of a parser from ObjectInserter's - * {@link ObjectInserter#newPackParser(InputStream)} method. + * {@link org.eclipse.jgit.lib.ObjectInserter#newPackParser(InputStream)} + * method. * <p> - * Implementations of {@link ObjectInserter} should subclass this type and - * provide their own logic for the various {@code on*()} event methods declared - * to be abstract. + * Implementations of {@link org.eclipse.jgit.lib.ObjectInserter} should + * subclass this type and provide their own logic for the various {@code on*()} + * event methods declared to be abstract. */ public abstract class PackParser { /** Size of the internal stream buffer. */ @@ -213,7 +214,11 @@ public abstract class PackParser { checkObjectCollisions = true; } - /** @return true if a thin pack (missing base objects) is permitted. */ + /** + * Whether a thin pack (missing base objects) is permitted. + * + * @return {@code true} if a thin pack (missing base objects) is permitted. + */ public boolean isAllowThin() { return allowThin; } @@ -232,6 +237,8 @@ public abstract class PackParser { } /** + * Whether received objects are verified to prevent collisions. + * * @return if true received objects are verified to prevent collisions. * @since 4.1 */ @@ -300,7 +307,11 @@ public abstract class PackParser { this.needBaseObjectIds = b; } - /** @return true if the EOF should be read from the input after the footer. */ + /** + * Whether the EOF should be read from the input after the footer. + * + * @return true if the EOF should be read from the input after the footer. + */ public boolean isCheckEofAfterPackFooter() { return checkEofAfterPackFooter; } @@ -315,12 +326,18 @@ public abstract class PackParser { checkEofAfterPackFooter = b; } - /** @return true if there is data expected after the pack footer. */ + /** + * Whether there is data expected after the pack footer. + * + * @return true if there is data expected after the pack footer. + */ public boolean isExpectDataAfterPackFooter() { return expectDataAfterPackFooter; } /** + * Set if there is additional data in InputStream after pack. + * * @param e * true if there is additional data in InputStream after pack. * This requires the InputStream to support the mark and reset @@ -330,14 +347,22 @@ public abstract class PackParser { expectDataAfterPackFooter = e; } - /** @return the new objects that were sent by the user */ + /** + * Get the new objects that were sent by the user + * + * @return the new objects that were sent by the user + */ public ObjectIdSubclassMap<ObjectId> getNewObjectIds() { if (newObjectIds != null) return newObjectIds; return new ObjectIdSubclassMap<>(); } - /** @return set of objects the incoming pack assumed for delta purposes */ + /** + * Get set of objects the incoming pack assumed for delta purposes + * + * @return set of objects the incoming pack assumed for delta purposes + */ public ObjectIdSubclassMap<ObjectId> getBaseObjectIds() { if (baseObjectIds != null) return baseObjectIds; @@ -378,7 +403,11 @@ public abstract class PackParser { setObjectChecker(on ? new ObjectChecker() : null); } - /** @return the message to record with the pack lock. */ + /** + * Get the message to record with the pack lock. + * + * @return the message to record with the pack lock. + */ public String getLockMessage() { return lockMessage; } @@ -420,7 +449,7 @@ public abstract class PackParser { return entryCount; } - /*** + /** * Get the information about the requested object. * <p> * The object information is only available after @@ -477,7 +506,7 @@ public abstract class PackParser { * <p> * This should only be called after pack parsing is finished. * - * @return {@link ReceivedPackStatistics} + * @return {@link org.eclipse.jgit.transport.ReceivedPackStatistics} * @since 4.6 */ public ReceivedPackStatistics getReceivedPackStatistics() { @@ -489,10 +518,10 @@ public abstract class PackParser { * * @param progress * callback to provide progress feedback during parsing. If null, - * {@link NullProgressMonitor} will be used. + * {@link org.eclipse.jgit.lib.NullProgressMonitor} will be used. * @return the pack lock, if one was requested by setting * {@link #setLockMessage(String)}. - * @throws IOException + * @throws java.io.IOException * the stream is malformed, or contains corrupt objects. * @since 3.0 */ @@ -505,13 +534,13 @@ public abstract class PackParser { * * @param receiving * receives progress feedback during the initial receiving - * objects phase. If null, {@link NullProgressMonitor} will be - * used. + * objects phase. If null, + * {@link org.eclipse.jgit.lib.NullProgressMonitor} will be used. * @param resolving * receives progress feedback during the resolving objects phase. * @return the pack lock, if one was requested by setting * {@link #setLockMessage(String)}. - * @throws IOException + * @throws java.io.IOException * the stream is malformed, or contains corrupt objects. * @since 3.0 */ @@ -701,7 +730,7 @@ public abstract class PackParser { private final void checkIfTooLarge(int typeCode, long size) throws IOException { - if (0 < maxObjectSizeLimit && maxObjectSizeLimit < size) + if (0 < maxObjectSizeLimit && maxObjectSizeLimit < size) { switch (typeCode) { case Constants.OBJ_COMMIT: case Constants.OBJ_TREE: @@ -711,13 +740,17 @@ public abstract class PackParser { case Constants.OBJ_OFS_DELTA: case Constants.OBJ_REF_DELTA: - throw new TooLargeObjectInPackException(maxObjectSizeLimit); + throw new TooLargeObjectInPackException(size, maxObjectSizeLimit); default: throw new IOException(MessageFormat.format( JGitText.get().unknownObjectType, Integer.valueOf(typeCode))); } + } + if (size > Integer.MAX_VALUE - 8) { + throw new TooLargeObjectInPackException(size, Integer.MAX_VALUE - 8); + } } /** @@ -733,7 +766,7 @@ public abstract class PackParser { * @param info * the info object to populate. * @return {@code info}, after populating. - * @throws IOException + * @throws java.io.IOException * the size cannot be read. */ protected ObjectTypeAndSize readObjectHeader(ObjectTypeAndSize info) @@ -1093,9 +1126,8 @@ public abstract class PackParser { * the type of the object. * @param data * raw content of the object. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * @since 4.9 - * */ protected void verifySafeObject(final AnyObjectId id, final int type, final byte[] data) throws CorruptObjectException { @@ -1261,7 +1293,11 @@ public abstract class PackParser { bOffset = 0; } - /** @return a temporary byte array for use by the caller. */ + /** + * Get a temporary byte array for use by the caller. + * + * @return a temporary byte array for use by the caller. + */ protected byte[] buffer() { return tempBuffer; } @@ -1298,7 +1334,7 @@ public abstract class PackParser { * If external implementation wants to overwrite the expectedObjectCount, * they should call this method during {@link #onPackHeader(long)}. * - * @param expectedObjectCount + * @param expectedObjectCount a long. * @since 4.9 */ protected void setExpectedObjectCount(long expectedObjectCount) { @@ -1323,7 +1359,7 @@ public abstract class PackParser { * first offset within the buffer that is valid. * @param len * number of bytes in the buffer that are valid. - * @throws IOException + * @throws java.io.IOException * the stream cannot be archived. */ protected abstract void onStoreStream(byte[] raw, int pos, int len) @@ -1343,7 +1379,7 @@ public abstract class PackParser { * first offset within buffer that is valid. * @param len * number of bytes in buffer that are valid. - * @throws IOException + * @throws java.io.IOException * the stream cannot be archived. */ protected abstract void onObjectHeader(Source src, byte[] raw, int pos, @@ -1366,7 +1402,7 @@ public abstract class PackParser { * first offset within buffer that is valid. * @param len * number of bytes in buffer that are valid. - * @throws IOException + * @throws java.io.IOException * the stream cannot be archived. */ protected abstract void onObjectData(Source src, byte[] raw, int pos, @@ -1381,7 +1417,7 @@ public abstract class PackParser { * the type of the object. * @param data * inflated data for the object. - * @throws IOException + * @throws java.io.IOException * the object cannot be archived. */ protected abstract void onInflatedObjectData(PackedObjectInfo obj, @@ -1392,7 +1428,7 @@ public abstract class PackParser { * * @param objCnt * number of objects expected in the stream. - * @throws IOException + * @throws java.io.IOException * the implementation refuses to work with this many objects. */ protected abstract void onPackHeader(long objCnt) throws IOException; @@ -1403,7 +1439,7 @@ public abstract class PackParser { * @param hash * the trailing 20 bytes of the pack, this is a SHA-1 checksum of * all of the pack data. - * @throws IOException + * @throws java.io.IOException * the stream cannot be archived. */ protected abstract void onPackFooter(byte[] hash) throws IOException; @@ -1426,7 +1462,7 @@ public abstract class PackParser { * @return true if the {@code info} should be included in the object list * returned by {@link #getSortedObjectList(Comparator)}, false if it * should not be included. - * @throws IOException + * @throws java.io.IOException * the base could not be included into the pack. */ protected abstract boolean onAppendBase(int typeCode, byte[] data, @@ -1439,7 +1475,7 @@ public abstract class PackParser { * external from the pack. The event is called after all of those deltas * have been resolved. * - * @throws IOException + * @throws java.io.IOException * the pack cannot be archived. */ protected abstract void onEndThinPack() throws IOException; @@ -1456,7 +1492,7 @@ public abstract class PackParser { * @param info * object to populate with type and size. * @return the {@code info} object. - * @throws IOException + * @throws java.io.IOException * the database cannot reposition to this location. */ protected abstract ObjectTypeAndSize seekDatabase(PackedObjectInfo obj, @@ -1474,7 +1510,7 @@ public abstract class PackParser { * @param info * object to populate with type and size. * @return the {@code info} object. - * @throws IOException + * @throws java.io.IOException * the database cannot reposition to this location. */ protected abstract ObjectTypeAndSize seekDatabase(UnresolvedDelta delta, @@ -1491,7 +1527,7 @@ public abstract class PackParser { * ideal target number of bytes to read. Actual read length may * be shorter. * @return number of bytes stored. - * @throws IOException + * @throws java.io.IOException * the database cannot be accessed. */ protected abstract int readDatabase(byte[] dst, int pos, int cnt) @@ -1521,13 +1557,15 @@ public abstract class PackParser { * @param streamPosition * position of this object in the incoming stream. * @param type - * type of the object; one of {@link Constants#OBJ_COMMIT}, - * {@link Constants#OBJ_TREE}, {@link Constants#OBJ_BLOB}, or - * {@link Constants#OBJ_TAG}. + * type of the object; one of + * {@link org.eclipse.jgit.lib.Constants#OBJ_COMMIT}, + * {@link org.eclipse.jgit.lib.Constants#OBJ_TREE}, + * {@link org.eclipse.jgit.lib.Constants#OBJ_BLOB}, or + * {@link org.eclipse.jgit.lib.Constants#OBJ_TAG}. * @param inflatedSize * size of the object when fully inflated. The size stored within * the pack may be larger or smaller, and is not yet known. - * @throws IOException + * @throws java.io.IOException * the object cannot be recorded. */ protected abstract void onBeginWholeObject(long streamPosition, int type, @@ -1538,7 +1576,7 @@ public abstract class PackParser { * *@param info * object information. - * @throws IOException + * @throws java.io.IOException * the object cannot be recorded. */ protected abstract void onEndWholeObject(PackedObjectInfo info) @@ -1557,7 +1595,7 @@ public abstract class PackParser { * @param inflatedSize * size of the delta when fully inflated. The size stored within * the pack may be larger or smaller, and is not yet known. - * @throws IOException + * @throws java.io.IOException * the object cannot be recorded. */ protected abstract void onBeginOfsDelta(long deltaStreamPosition, @@ -1575,7 +1613,7 @@ public abstract class PackParser { * @param inflatedSize * size of the delta when fully inflated. The size stored within * the pack may be larger or smaller, and is not yet known. - * @throws IOException + * @throws java.io.IOException * the object cannot be recorded. */ protected abstract void onBeginRefDelta(long deltaStreamPosition, @@ -1586,7 +1624,7 @@ public abstract class PackParser { * *@return object information that must be populated with at least the * offset. - * @throws IOException + * @throws java.io.IOException * the object cannot be recorded. */ protected UnresolvedDelta onEndDelta() throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PackedObjectInfo.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PackedObjectInfo.java index 381c22893b..80fc0b42ad 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PackedObjectInfo.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PackedObjectInfo.java @@ -80,6 +80,8 @@ public class PackedObjectInfo extends ObjectIdOwnerMap.Entry { } /** + * Get offset in pack when object has been already written + * * @return offset in pack when object has been already written, or 0 if it * has not been written yet */ @@ -98,6 +100,8 @@ public class PackedObjectInfo extends ObjectIdOwnerMap.Entry { } /** + * Get the 32 bit CRC checksum for the packed data. + * * @return the 32 bit CRC checksum for the packed data. */ public int getCRC() { @@ -117,6 +121,8 @@ public class PackedObjectInfo extends ObjectIdOwnerMap.Entry { } /** + * Get the object type. + * * @return the object type. The default type is OBJ_BAD, which is considered * as unknown or invalid type. * @since 4.9 diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PacketLineIn.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PacketLineIn.java index e70925693b..87064e122b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PacketLineIn.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PacketLineIn.java @@ -148,7 +148,7 @@ public class PacketLineIn { * * @return the string. {@link #END} if the string was the magic flush * packet. - * @throws IOException + * @throws java.io.IOException * the stream cannot be read. */ public String readString() throws IOException { @@ -186,7 +186,7 @@ public class PacketLineIn { * * @return the string. {@link #END} if the string was the magic flush * packet. - * @throws IOException + * @throws java.io.IOException * the stream cannot be read. */ public String readStringRaw() throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PacketLineOut.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PacketLineOut.java index a6bd342851..48bdd01f55 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PacketLineOut.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PacketLineOut.java @@ -100,7 +100,7 @@ public class PacketLineOut { * * @param s * string to write. - * @throws IOException + * @throws java.io.IOException * the packet could not be written, the stream is corrupted as * the packet may have been only partially written. */ @@ -114,7 +114,7 @@ public class PacketLineOut { * @param packet * the packet to write; the length of the packet is equal to the * size of the byte array. - * @throws IOException + * @throws java.io.IOException * the packet could not be written, the stream is corrupted as * the packet may have been only partially written. */ @@ -131,7 +131,7 @@ public class PacketLineOut { * first index within {@code buf}. * @param len * number of bytes to write. - * @throws IOException + * @throws java.io.IOException * the packet could not be written, the stream is corrupted as * the packet may have been only partially written. * @since 4.5 @@ -155,7 +155,7 @@ public class PacketLineOut { * Implicitly performs a flush on the underlying OutputStream to ensure the * peer will receive all data written thus far. * - * @throws IOException + * @throws java.io.IOException * the end marker could not be written, the stream is corrupted * as the end marker may have been only partially written. */ @@ -173,7 +173,7 @@ public class PacketLineOut { * Performs a flush on the underlying OutputStream to ensure the peer will * receive all data written thus far. * - * @throws IOException + * @throws java.io.IOException * the underlying stream failed to flush. */ public void flush() throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PostReceiveHook.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PostReceiveHook.java index 8e395018cd..5cbb6f5dfb 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PostReceiveHook.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PostReceiveHook.java @@ -46,11 +46,13 @@ package org.eclipse.jgit.transport; import java.util.Collection; /** - * Hook invoked by {@link ReceivePack} after all updates are executed. + * Hook invoked by {@link org.eclipse.jgit.transport.ReceivePack} after all + * updates are executed. * <p> * The hook is called after all commands have been processed. Only commands with - * a status of {@link ReceiveCommand.Result#OK} are passed into the hook. To get - * all commands within the hook, see {@link ReceivePack#getAllCommands()}. + * a status of {@link org.eclipse.jgit.transport.ReceiveCommand.Result#OK} are + * passed into the hook. To get all commands within the hook, see + * {@link org.eclipse.jgit.transport.ReceivePack#getAllCommands()}. * <p> * Any post-receive hook implementation should not update the status of a * command, as the command has already completed or failed, and the status has diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PostReceiveHookChain.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PostReceiveHookChain.java index 3bdcd68959..0bdf7d4f6b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PostReceiveHookChain.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PostReceiveHookChain.java @@ -47,7 +47,8 @@ import java.util.Collection; import java.util.List; /** - * {@link PostReceiveHook} that delegates to a list of other hooks. + * {@link org.eclipse.jgit.transport.PostReceiveHook} that delegates to a list + * of other hooks. * <p> * Hooks are run in the order passed to the constructor. */ @@ -77,6 +78,7 @@ public class PostReceiveHookChain implements PostReceiveHook { return new PostReceiveHookChain(newHooks, i); } + /** {@inheritDoc} */ @Override public void onPostReceive(ReceivePack rp, Collection<ReceiveCommand> commands) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PostUploadHook.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PostUploadHook.java index 5b37bcdf0c..09667eb01a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PostUploadHook.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PostUploadHook.java @@ -42,11 +42,11 @@ package org.eclipse.jgit.transport; -import org.eclipse.jgit.internal.storage.pack.PackWriter; import org.eclipse.jgit.storage.pack.PackStatistics; /** - * Hook invoked by {@link UploadPack} after the pack has been uploaded. + * Hook invoked by {@link org.eclipse.jgit.transport.UploadPack} after the pack + * has been uploaded. * <p> * Implementors of the interface are responsible for associating the current * thread to a particular connection, if they need to also include connection @@ -68,8 +68,9 @@ public interface PostUploadHook { * Notifies the hook that a pack has been sent. * * @param stats - * the statistics gathered by {@link PackWriter} for the uploaded - * pack + * the statistics gathered by + * {@link org.eclipse.jgit.internal.storage.pack.PackWriter} for + * the uploaded pack */ public void onPostUpload(PackStatistics stats); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PostUploadHookChain.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PostUploadHookChain.java index 26323badc6..542abe7563 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PostUploadHookChain.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PostUploadHookChain.java @@ -47,7 +47,8 @@ import java.util.List; import org.eclipse.jgit.storage.pack.PackStatistics; /** - * {@link PostUploadHook} that delegates to a list of other hooks. + * {@link org.eclipse.jgit.transport.PostUploadHook} that delegates to a list of + * other hooks. * <p> * Hooks are run in the order passed to the constructor. * @@ -78,6 +79,7 @@ public class PostUploadHookChain implements PostUploadHook { return new PostUploadHookChain(newHooks, i); } + /** {@inheritDoc} */ @Override public void onPostUpload(PackStatistics stats) { for (int i = 0; i < count; i++) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PreReceiveHook.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PreReceiveHook.java index 27b2df08ce..77c1a8af29 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PreReceiveHook.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PreReceiveHook.java @@ -46,7 +46,8 @@ package org.eclipse.jgit.transport; import java.util.Collection; /** - * Hook invoked by {@link ReceivePack} before any updates are executed. + * Hook invoked by {@link org.eclipse.jgit.transport.ReceivePack} before any + * updates are executed. * <p> * The hook is called with any commands that are deemed valid after parsing them * from the client and applying the standard receive configuration options to @@ -57,23 +58,24 @@ import java.util.Collection; * </ul> * This means the hook will not receive a non-fast-forward update command if * denyNonFastForwards is set to true in the configuration file. To get all - * commands within the hook, see {@link ReceivePack#getAllCommands()}. + * commands within the hook, see + * {@link org.eclipse.jgit.transport.ReceivePack#getAllCommands()}. * <p> * As the hook is invoked prior to the commands being executed, the hook may * choose to block any command by setting its result status with - * {@link ReceiveCommand#setResult(ReceiveCommand.Result)}. + * {@link org.eclipse.jgit.transport.ReceiveCommand#setResult(ReceiveCommand.Result)}. * <p> * The hook may also choose to perform the command itself (or merely pretend * that it has performed the command), by setting the result status to - * {@link ReceiveCommand.Result#OK}. + * {@link org.eclipse.jgit.transport.ReceiveCommand.Result#OK}. * <p> * Hooks should run quickly, as they block the caller thread and the client * process from completing. * <p> * Hooks may send optional messages back to the client via methods on - * {@link ReceivePack}. Implementors should be aware that not all network - * transports support this output, so some (or all) messages may simply be - * discarded. These messages should be advisory only. + * {@link org.eclipse.jgit.transport.ReceivePack}. Implementors should be aware + * that not all network transports support this output, so some (or all) + * messages may simply be discarded. These messages should be advisory only. */ public interface PreReceiveHook { /** A simple no-op hook. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PreReceiveHookChain.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PreReceiveHookChain.java index 7b1c8fb3f2..47b94c6e49 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PreReceiveHookChain.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PreReceiveHookChain.java @@ -47,7 +47,8 @@ import java.util.Collection; import java.util.List; /** - * {@link PreReceiveHook} that delegates to a list of other hooks. + * {@link org.eclipse.jgit.transport.PreReceiveHook} that delegates to a list of + * other hooks. * <p> * Hooks are run in the order passed to the constructor. */ @@ -76,6 +77,7 @@ public class PreReceiveHookChain implements PreReceiveHook { return new PreReceiveHookChain(newHooks, i); } + /** {@inheritDoc} */ @Override public void onPreReceive(ReceivePack rp, Collection<ReceiveCommand> commands) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PreUploadHook.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PreUploadHook.java index 7d9638cfc0..2e1cd5800a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PreUploadHook.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PreUploadHook.java @@ -48,9 +48,11 @@ import java.util.Collection; import org.eclipse.jgit.lib.ObjectId; /** - * Hook invoked by {@link UploadPack} before during critical phases. + * Hook invoked by {@link org.eclipse.jgit.transport.UploadPack} before during + * critical phases. * <p> - * If any hook function throws {@link ServiceMayNotContinueException} then + * If any hook function throws + * {@link org.eclipse.jgit.transport.ServiceMayNotContinueException} then * processing stops immediately and the exception is thrown up the call stack. * Most phases of UploadPack will try to report the exception's message text to * the end-user over the client's protocol connection. @@ -91,7 +93,7 @@ public interface PreUploadHook { * the list of wanted objects. * @param cntOffered * number of objects the client has offered. - * @throws ServiceMayNotContinueException + * @throws org.eclipse.jgit.transport.ServiceMayNotContinueException * abort; the message will be sent to the user. */ public void onBeginNegotiateRound(UploadPack up, @@ -115,7 +117,7 @@ public interface PreUploadHook { * @param ready * true if a pack is ready to be sent (the commit graph was * successfully cut). - * @throws ServiceMayNotContinueException + * @throws org.eclipse.jgit.transport.ServiceMayNotContinueException * abort; the message will be sent to the user. */ public void onEndNegotiateRound(UploadPack up, @@ -136,7 +138,7 @@ public interface PreUploadHook { * the list of common objects. Empty on an initial clone request. * These may be RevObject or RevCommit if the processed parsed * them. Implementors should not rely on the values being parsed. - * @throws ServiceMayNotContinueException + * @throws org.eclipse.jgit.transport.ServiceMayNotContinueException * abort; the message will be sent to the user. */ public void onSendPack(UploadPack up, Collection<? extends ObjectId> wants, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PreUploadHookChain.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PreUploadHookChain.java index c9f88dd164..bfd52af74a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PreUploadHookChain.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PreUploadHookChain.java @@ -49,7 +49,8 @@ import java.util.List; import org.eclipse.jgit.lib.ObjectId; /** - * {@link PreUploadHook} that delegates to a list of other hooks. + * {@link org.eclipse.jgit.transport.PreUploadHook} that delegates to a list of + * other hooks. * <p> * Hooks are run in the order passed to the constructor. If running a method on * one hook throws an exception, execution of remaining hook methods is aborted. @@ -79,6 +80,7 @@ public class PreUploadHookChain implements PreUploadHook { return new PreUploadHookChain(newHooks, i); } + /** {@inheritDoc} */ @Override public void onBeginNegotiateRound(UploadPack up, Collection<? extends ObjectId> wants, int cntOffered) @@ -87,6 +89,7 @@ public class PreUploadHookChain implements PreUploadHook { hooks[i].onBeginNegotiateRound(up, wants, cntOffered); } + /** {@inheritDoc} */ @Override public void onEndNegotiateRound(UploadPack up, Collection<? extends ObjectId> wants, int cntCommon, @@ -96,6 +99,7 @@ public class PreUploadHookChain implements PreUploadHook { hooks[i].onEndNegotiateRound(up, wants, cntCommon, cntNotFound, ready); } + /** {@inheritDoc} */ @Override public void onSendPack(UploadPack up, Collection<? extends ObjectId> wants, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/ProgressSpinner.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/ProgressSpinner.java index ac048a14a9..41af8078c8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/ProgressSpinner.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/ProgressSpinner.java @@ -104,7 +104,9 @@ public class ProgressSpinner { } } - /** Update the spinner if it is showing. */ + /** + * Update the spinner if it is showing. + */ public void update() { long now = System.currentTimeMillis(); if (now >= nextUpdateMillis) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificate.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificate.java index e450345b56..a9397a599b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificate.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificate.java @@ -132,6 +132,8 @@ public class PushCertificate { } /** + * Get the certificate version string. + * * @return the certificate version string. * @since 4.1 */ @@ -140,6 +142,8 @@ public class PushCertificate { } /** + * Get the raw line that signed the cert, as a string. + * * @return the raw line that signed the cert, as a string. * @since 4.0 */ @@ -148,6 +152,8 @@ public class PushCertificate { } /** + * Get identity of the pusher who signed the cert. + * * @return identity of the pusher who signed the cert. * @since 4.1 */ @@ -156,6 +162,8 @@ public class PushCertificate { } /** + * Get URL of the repository the push was originally sent to. + * * @return URL of the repository the push was originally sent to. * @since 4.0 */ @@ -164,6 +172,8 @@ public class PushCertificate { } /** + * Get the raw nonce value that was presented by the pusher. + * * @return the raw nonce value that was presented by the pusher. * @since 4.1 */ @@ -172,6 +182,8 @@ public class PushCertificate { } /** + * Get verification status of the nonce embedded in the certificate. + * * @return verification status of the nonce embedded in the certificate. * @since 4.0 */ @@ -180,6 +192,9 @@ public class PushCertificate { } /** + * Get the list of commands as one string to be feed into the signature + * verifier. + * * @return the list of commands as one string to be feed into the signature * verifier. * @since 4.1 @@ -189,9 +204,11 @@ public class PushCertificate { } /** + * Get the raw signature + * * @return the raw signature, consisting of the lines received between the - * lines {@code "----BEGIN GPG SIGNATURE-----\n"} and - * {@code "----END GPG SIGNATURE-----\n}", inclusive. + * lines {@code "----BEGIN GPG SIGNATURE-----\n"} and + * {@code "----END GPG SIGNATURE-----\n}", inclusive. * @since 4.0 */ public String getSignature() { @@ -199,6 +216,8 @@ public class PushCertificate { } /** + * Get text payload of the certificate for the signature verifier. + * * @return text payload of the certificate for the signature verifier. * @since 4.1 */ @@ -207,8 +226,11 @@ public class PushCertificate { } /** + * Get original text payload plus signature + * * @return original text payload plus signature; the final output will be - * valid as input to {@link PushCertificateParser#fromString(String)}. + * valid as input to + * {@link org.eclipse.jgit.transport.PushCertificateParser#fromString(String)}. * @since 4.1 */ public String toTextWithSignature() { @@ -233,11 +255,13 @@ public class PushCertificate { return sb; } + /** {@inheritDoc} */ @Override public int hashCode() { return signature.hashCode(); } + /** {@inheritDoc} */ @Override public boolean equals(Object o) { if (!(o instanceof PushCertificate)) { @@ -268,6 +292,7 @@ public class PushCertificate { return true; } + /** {@inheritDoc} */ @Override public String toString() { return getClass().getSimpleName() + '[' diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificateIdent.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificateIdent.java index 4c8acd2cc2..f9fddbe889 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificateIdent.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificateIdent.java @@ -58,18 +58,19 @@ import org.eclipse.jgit.util.RawParseUtils; /** * Identity in a push certificate. * <p> - * This is similar to a {@link PersonIdent} in that it contains a name, - * timestamp, and timezone offset, but differs in the following ways: + * This is similar to a {@link org.eclipse.jgit.lib.PersonIdent} in that it + * contains a name, timestamp, and timezone offset, but differs in the following + * ways: * <ul> * <li>It is always parsed from a UTF-8 string, rather than a raw commit - * buffer.</li> + * buffer.</li> * <li>It is not guaranteed to contain a name and email portion, since any UTF-8 - * string is a valid OpenPGP User ID (RFC4880 5.1.1). The raw User ID is - * always available as {@link #getUserId()}, but {@link #getEmailAddress()} - * may return null.</li> - * <li>The raw text from which the identity was parsed is available with {@link - * #getRaw()}. This is necessary for losslessly reconstructing the signed push - * certificate payload.</li> + * string is a valid OpenPGP User ID (RFC4880 5.1.1). The raw User ID is always + * available as {@link #getUserId()}, but {@link #getEmailAddress()} may return + * null.</li> + * <li>The raw text from which the identity was parsed is available with + * {@link #getRaw()}. This is necessary for losslessly reconstructing the signed + * push certificate payload.</li> * <li> * </ul> * @@ -79,18 +80,18 @@ public class PushCertificateIdent { /** * Parse an identity from a string. * <p> - * Spaces are trimmed when parsing the timestamp and timezone offset, with one - * exception. The timestamp must be preceded by a single space, and the rest - * of the string prior to that space (including any additional whitespace) is - * treated as the OpenPGP User ID. + * Spaces are trimmed when parsing the timestamp and timezone offset, with + * one exception. The timestamp must be preceded by a single space, and the + * rest of the string prior to that space (including any additional + * whitespace) is treated as the OpenPGP User ID. * <p> - * If either the timestamp or timezone offsets are missing, mimics {@link - * RawParseUtils#parsePersonIdent(String)} behavior and sets them both to - * zero. + * If either the timestamp or timezone offsets are missing, mimics + * {@link RawParseUtils#parsePersonIdent(String)} behavior and sets them + * both to zero. * * @param str * string to parse. - * @return identity, never null. + * @return a {@link org.eclipse.jgit.transport.PushCertificateIdent} object. */ public static PushCertificateIdent parse(String str) { MutableInteger p = new MutableInteger(); @@ -181,15 +182,21 @@ public class PushCertificateIdent { return raw; } - /** @return the OpenPGP User ID, which may be any string. */ + /** + * Get the OpenPGP User ID, which may be any string. + * + * @return the OpenPGP User ID, which may be any string. + */ public String getUserId() { return userId; } /** + * Get the name portion of the User ID. + * * @return the name portion of the User ID. If no email address would be - * parsed by {@link #getEmailAddress()}, returns the full User ID with - * spaces trimmed. + * parsed by {@link #getEmailAddress()}, returns the full User ID + * with spaces trimmed. */ public String getName() { int nameEnd = userId.indexOf('<'); @@ -208,6 +215,8 @@ public class PushCertificateIdent { } /** + * Get the email portion of the User ID + * * @return the email portion of the User ID, if one was successfully parsed * from {@link #getUserId()}, or null. */ @@ -223,19 +232,28 @@ public class PushCertificateIdent { return userId.substring(emailBegin + 1, emailEnd); } - /** @return the timestamp of the identity. */ + /** + * Get the timestamp of the identity. + * + * @return the timestamp of the identity. + */ public Date getWhen() { return new Date(when); } /** - * @return this person's declared time zone; null if the timezone is unknown. + * Get this person's declared time zone + * + * @return this person's declared time zone; null if the timezone is + * unknown. */ public TimeZone getTimeZone() { return PersonIdent.getTimeZone(tzOffset); } /** + * Get this person's declared time zone as minutes east of UTC. + * * @return this person's declared time zone as minutes east of UTC. If the * timezone is to the west of UTC it is negative. */ @@ -243,17 +261,20 @@ public class PushCertificateIdent { return tzOffset; } + /** {@inheritDoc} */ @Override public boolean equals(Object o) { return (o instanceof PushCertificateIdent) && raw.equals(((PushCertificateIdent) o).raw); } + /** {@inheritDoc} */ @Override public int hashCode() { return raw.hashCode(); } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificateParser.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificateParser.java index 5174f85627..89c1a93788 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificateParser.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificateParser.java @@ -133,11 +133,12 @@ public class PushCertificateParser { /** * Parse a push certificate from a reader. * <p> - * Differences from the {@link PacketLineIn} receiver methods: + * Differences from the {@link org.eclipse.jgit.transport.PacketLineIn} + * receiver methods: * <ul> * <li>Does not use pkt-line framing.</li> * <li>Reads an entire cert in one call rather than depending on a loop in - * the caller.</li> + * the caller.</li> * <li>Does not assume a {@code "push-cert-end"} line.</li> * </ul> * @@ -145,9 +146,9 @@ public class PushCertificateParser { * input reader; consumed only up until the end of the next * signature in the input. * @return the parsed certificate, or null if the reader was at EOF. - * @throws PackProtocolException + * @throws org.eclipse.jgit.errors.PackProtocolException * if the certificate is malformed. - * @throws IOException + * @throws java.io.IOException * if there was an error reading from the input. * @since 4.1 */ @@ -163,9 +164,9 @@ public class PushCertificateParser { * @param str * input string. * @return the parsed certificate. - * @throws PackProtocolException + * @throws org.eclipse.jgit.errors.PackProtocolException * if the certificate is malformed. - * @throws IOException + * @throws java.io.IOException * if there was an error reading from the input. * @since 4.1 */ @@ -207,6 +208,8 @@ public class PushCertificateParser { private final List<ReceiveCommand> commands = new ArrayList<>(); /** + * <p>Constructor for PushCertificateParser.</p> + * * @param into * destination repository for the push. * @param cfg @@ -240,9 +243,9 @@ public class PushCertificateParser { * input reader; consumed only up until the end of the next * signature in the input. * @return the parsed certificate, or null if the reader was at EOF. - * @throws PackProtocolException + * @throws org.eclipse.jgit.errors.PackProtocolException * if the certificate is malformed. - * @throws IOException + * @throws java.io.IOException * if there was an error reading from the input. * @since 4.1 */ @@ -267,8 +270,11 @@ public class PushCertificateParser { } /** - * @return the parsed certificate, or null if push certificates are disabled. - * @throws IOException + * Build the parsed certificate + * + * @return the parsed certificate, or null if push certificates are + * disabled. + * @throws java.io.IOException * if the push certificate has missing or invalid fields. * @since 4.1 */ @@ -285,6 +291,9 @@ public class PushCertificateParser { } /** + * Whether the repository is configured to use signed pushes in this + * context. + * * @return if the repository is configured to use signed pushes in this * context. * @since 4.0 @@ -294,6 +303,9 @@ public class PushCertificateParser { } /** + * Get the whole string for the nonce to be included into the capability + * advertisement + * * @return the whole string for the nonce to be included into the capability * advertisement, or null if push certificates are disabled. * @since 4.0 @@ -348,7 +360,7 @@ public class PushCertificateParser { * {@code NonceGenerator} will allow for some time skew caused by * clients disconnected and reconnecting in the stateless smart * HTTP protocol. - * @throws IOException + * @throws java.io.IOException * if the certificate from the client is badly malformed or the * client disconnects before sending the entire certificate. * @since 4.0 @@ -410,7 +422,7 @@ public class PushCertificateParser { * * @param pckIn * where we read the signature from. - * @throws IOException + * @throws java.io.IOException * if the signature is invalid. * @since 4.0 */ @@ -455,7 +467,7 @@ public class PushCertificateParser { * @param line * the line read from the wire that produced this * command, with optional trailing newline already trimmed. - * @throws PackProtocolException + * @throws org.eclipse.jgit.errors.PackProtocolException * if the raw line cannot be parsed to a command. * @since 4.0 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificateStore.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificateStore.java index 706e727060..ab58a3317a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificateStore.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushCertificateStore.java @@ -135,10 +135,12 @@ public class PushCertificateStore implements AutoCloseable { } /** + * {@inheritDoc} + * <p> * Close resources opened by this store. * <p> - * If {@link #get(String)} was called, closes the cached object reader created - * by that method. Does not close the underlying repository. + * If {@link #get(String)} was called, closes the cached object reader + * created by that method. Does not close the underlying repository. */ @Override public void close() { @@ -160,7 +162,7 @@ public class PushCertificateStore implements AutoCloseable { * the ref name to get the certificate for. * @return last certificate affecting the ref, or null if no cert was recorded * for the last update to this ref. - * @throws IOException + * @throws java.io.IOException * if a problem occurred reading the repository. */ public PushCertificate get(String refName) throws IOException { @@ -298,20 +300,20 @@ public class PushCertificateStore implements AutoCloseable { /** * Put a certificate to be saved to the store. * <p> - * Writes the contents of this certificate for each ref mentioned. It is up to - * the caller to ensure this certificate accurately represents the state of - * the ref. + * Writes the contents of this certificate for each ref mentioned. It is up + * to the caller to ensure this certificate accurately represents the state + * of the ref. * <p> - * Pending certificates added to this method are not returned by {@link - * #get(String)} and {@link #getAll(String)} until after calling {@link - * #save()}. + * Pending certificates added to this method are not returned by + * {@link #get(String)} and {@link #getAll(String)} until after calling + * {@link #save()}. * * @param cert * certificate to store. * @param ident * identity for the commit that stores this certificate. Pending - * certificates are sorted by identity timestamp during {@link - * #save()}. + * certificates are sorted by identity timestamp during + * {@link #save()}. */ public void put(PushCertificate cert, PersonIdent ident) { put(cert, ident, null); @@ -325,16 +327,16 @@ public class PushCertificateStore implements AutoCloseable { * list that exactly matches the old/new values mentioned in the push * certificate. * <p> - * Pending certificates added to this method are not returned by {@link - * #get(String)} and {@link #getAll(String)} until after calling {@link - * #save()}. + * Pending certificates added to this method are not returned by + * {@link #get(String)} and {@link #getAll(String)} until after calling + * {@link #save()}. * * @param cert * certificate to store. * @param ident * identity for the commit that stores this certificate. Pending - * certificates are sorted by identity timestamp during {@link - * #save()}. + * certificates are sorted by identity timestamp during + * {@link #save()}. * @param matching * only store certs for the refs listed in this list whose values * match the commands in the cert. @@ -347,15 +349,15 @@ public class PushCertificateStore implements AutoCloseable { /** * Save pending certificates to the store. * <p> - * One commit is created per certificate added with {@link - * #put(PushCertificate, PersonIdent)}, in order of identity timestamps, and - * a single ref update is performed. + * One commit is created per certificate added with + * {@link #put(PushCertificate, PersonIdent)}, in order of identity + * timestamps, and a single ref update is performed. * <p> - * The pending list is cleared if and only the ref update fails, which allows - * for easy retries in case of lock failure. + * The pending list is cleared if and only the ref update fails, which + * allows for easy retries in case of lock failure. * * @return the result of attempting to update the ref. - * @throws IOException + * @throws java.io.IOException * if there was an error reading from or writing to the * repository. */ @@ -384,18 +386,19 @@ public class PushCertificateStore implements AutoCloseable { /** * Save pending certificates to the store in an existing batch ref update. * <p> - * One commit is created per certificate added with {@link - * #put(PushCertificate, PersonIdent)}, in order of identity timestamps, all - * commits are flushed, and a single command is added to the batch. + * One commit is created per certificate added with + * {@link #put(PushCertificate, PersonIdent)}, in order of identity + * timestamps, all commits are flushed, and a single command is added to the + * batch. * <p> - * The cached ref value and pending list are <em>not</em> cleared. If the ref - * update succeeds, the caller is responsible for calling {@link #close()} - * and/or {@link #clear()}. + * The cached ref value and pending list are <em>not</em> cleared. If the + * ref update succeeds, the caller is responsible for calling + * {@link #close()} and/or {@link #clear()}. * * @param batch * update to save to. * @return whether a command was added to the batch. - * @throws IOException + * @throws java.io.IOException * if there was an error reading from or writing to the * repository. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushConnection.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushConnection.java index c2a885f622..ff2939a3d6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushConnection.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushConnection.java @@ -49,7 +49,6 @@ import java.util.Map; import org.eclipse.jgit.errors.TransportException; import org.eclipse.jgit.lib.ProgressMonitor; -import org.eclipse.jgit.transport.RemoteRefUpdate.Status; /** * Lists known refs from the remote and sends objects to the remote. @@ -60,9 +59,9 @@ import org.eclipse.jgit.transport.RemoteRefUpdate.Status; * into the remote repository, as well as a way to modify the refs stored by the * remote repository. * <p> - * Instances of a PushConnection must be created by a {@link Transport} that - * implements a specific object transfer protocol that both sides of the - * connection understand. + * Instances of a PushConnection must be created by a + * {@link org.eclipse.jgit.transport.Transport} that implements a specific + * object transfer protocol that both sides of the connection understand. * <p> * PushConnection instances are not thread safe and may be accessed by only one * thread at a time. @@ -79,13 +78,14 @@ public interface PushConnection extends Connection { * <p> * <p> * Only one call per connection is allowed. Subsequent calls will result in - * {@link TransportException}. + * {@link org.eclipse.jgit.errors.TransportException}. * </p> * <p> * Implementation may use local repository to send a minimum set of objects * needed by remote repository in efficient way. - * {@link Transport#isPushThin()} should be honored if applicable. - * refUpdates should be filled with information about status of each update. + * {@link org.eclipse.jgit.transport.Transport#isPushThin()} should be + * honored if applicable. refUpdates should be filled with information about + * status of each update. * </p> * * @param monitor @@ -97,12 +97,16 @@ public interface PushConnection extends Connection { * map of remote refnames to remote refs update * specifications/statuses. Can't be empty. This indicate what * refs caller want to update on remote side. Only refs updates - * with {@link Status#NOT_ATTEMPTED} should passed. - * Implementation must ensure that and appropriate status with - * optional message should be set during call. No refUpdate with - * {@link Status#AWAITING_REPORT} or {@link Status#NOT_ATTEMPTED} + * with + * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#NOT_ATTEMPTED} + * should passed. Implementation must ensure that and appropriate + * status with optional message should be set during call. No + * refUpdate with + * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#AWAITING_REPORT} + * or + * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#NOT_ATTEMPTED} * can be leaved by implementation after return from this call. - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * objects could not be copied due to a network failure, * critical protocol error, or error on remote side, or * connection was already used for push - new connection must be @@ -121,13 +125,14 @@ public interface PushConnection extends Connection { * <p> * <p> * Only one call per connection is allowed. Subsequent calls will result in - * {@link TransportException}. + * {@link org.eclipse.jgit.errors.TransportException}. * </p> * <p> * Implementation may use local repository to send a minimum set of objects * needed by remote repository in efficient way. - * {@link Transport#isPushThin()} should be honored if applicable. - * refUpdates should be filled with information about status of each update. + * {@link org.eclipse.jgit.transport.Transport#isPushThin()} should be + * honored if applicable. refUpdates should be filled with information about + * status of each update. * </p> * * @param monitor @@ -139,14 +144,18 @@ public interface PushConnection extends Connection { * map of remote refnames to remote refs update * specifications/statuses. Can't be empty. This indicate what * refs caller want to update on remote side. Only refs updates - * with {@link Status#NOT_ATTEMPTED} should passed. - * Implementation must ensure that and appropriate status with - * optional message should be set during call. No refUpdate with - * {@link Status#AWAITING_REPORT} or {@link Status#NOT_ATTEMPTED} + * with + * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#NOT_ATTEMPTED} + * should passed. Implementation must ensure that and appropriate + * status with optional message should be set during call. No + * refUpdate with + * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#AWAITING_REPORT} + * or + * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#NOT_ATTEMPTED} * can be leaved by implementation after return from this call. * @param out * output stream to write sideband messages to - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * objects could not be copied due to a network failure, * critical protocol error, or error on remote side, or * connection was already used for push - new connection must be diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushResult.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushResult.java index 41aa73cc3b..8bae5a5e09 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushResult.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PushResult.java @@ -51,7 +51,8 @@ import java.util.Map; /** * Result of push operation to the remote repository. Holding information of - * {@link OperationResult} and remote refs updates status. + * {@link org.eclipse.jgit.transport.OperationResult} and remote refs updates + * status. * * @see Transport#push(org.eclipse.jgit.lib.ProgressMonitor, Collection) */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/ReceiveCommand.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/ReceiveCommand.java index e9681b34c7..e14d18f3a6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/ReceiveCommand.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/ReceiveCommand.java @@ -52,6 +52,7 @@ import java.util.ArrayList; import java.util.Collection; import java.util.List; +import org.eclipse.jgit.annotations.NonNull; import org.eclipse.jgit.annotations.Nullable; import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.lib.AnyObjectId; @@ -63,10 +64,11 @@ import org.eclipse.jgit.revwalk.RevObject; import org.eclipse.jgit.revwalk.RevWalk; /** - * A command being processed by {@link BaseReceivePack}. + * A command being processed by + * {@link org.eclipse.jgit.transport.BaseReceivePack}. * <p> * This command instance roughly translates to the server side representation of - * the {@link RemoteRefUpdate} created by the client. + * the {@link org.eclipse.jgit.transport.RemoteRefUpdate} created by the client. */ public class ReceiveCommand { /** Type of operation requested. */ @@ -175,8 +177,10 @@ public class ReceiveCommand { /** * Set unprocessed commands as failed due to transaction aborted. * <p> - * If a command is still {@link Result#NOT_ATTEMPTED} it will be set to - * {@link Result#REJECTED_OTHER_REASON}. + * If a command is still + * {@link org.eclipse.jgit.transport.ReceiveCommand.Result#NOT_ATTEMPTED} it + * will be set to + * {@link org.eclipse.jgit.transport.ReceiveCommand.Result#REJECTED_OTHER_REASON}. * * @param commands * commands to mark as failed. @@ -196,8 +200,8 @@ public class ReceiveCommand { * * @param cmd * command. - * @return whether the command failed due to transaction aborted, as in {@link - * #abort(Iterable)}. + * @return whether the command failed due to transaction aborted, as in + * {@link #abort(Iterable)}. * @since 4.9 */ public static boolean isTransactionAborted(ReceiveCommand cmd) { @@ -205,14 +209,71 @@ public class ReceiveCommand { && cmd.getMessage().equals(JGitText.get().transactionAborted); } + /** + * Create a command to switch a reference from object to symbolic. + * + * @param oldId + * expected oldId. May be {@code zeroId} to create. + * @param newTarget + * new target; must begin with {@code "refs/"}. + * @param name + * name of the reference to make symbolic. + * @return command instance. + * @since 4.10 + */ + public static ReceiveCommand link(@NonNull ObjectId oldId, + @NonNull String newTarget, @NonNull String name) { + return new ReceiveCommand(oldId, newTarget, name); + } + + /** + * Create a command to switch a symbolic reference's target. + * + * @param oldTarget + * expected old target. May be null to create. + * @param newTarget + * new target; must begin with {@code "refs/"}. + * @param name + * name of the reference to make symbolic. + * @return command instance. + * @since 4.10 + */ + public static ReceiveCommand link(@Nullable String oldTarget, + @NonNull String newTarget, @NonNull String name) { + return new ReceiveCommand(oldTarget, newTarget, name); + } + + /** + * Create a command to switch a reference from symbolic to object. + * + * @param oldTarget + * expected old target. + * @param newId + * new object identifier. May be {@code zeroId()} to delete. + * @param name + * name of the reference to convert from symbolic. + * @return command instance. + * @since 4.10 + */ + public static ReceiveCommand unlink(@NonNull String oldTarget, + @NonNull ObjectId newId, @NonNull String name) { + return new ReceiveCommand(oldTarget, newId, name); + } + private final ObjectId oldId; + private final String oldSymref; + private final ObjectId newId; + private final String newSymref; + private final String name; private Type type; + private boolean typeIsCorrect; + private Ref ref; private Result status = Result.NOT_ATTEMPTED; @@ -227,30 +288,39 @@ public class ReceiveCommand { private Boolean forceRefLog; - private boolean typeIsCorrect; - /** - * Create a new command for {@link BaseReceivePack}. + * Create a new command for + * {@link org.eclipse.jgit.transport.BaseReceivePack}. * * @param oldId * the expected old object id; must not be null. Use - * {@link ObjectId#zeroId()} to indicate a ref creation. + * {@link org.eclipse.jgit.lib.ObjectId#zeroId()} to indicate a + * ref creation. * @param newId * the new object id; must not be null. Use - * {@link ObjectId#zeroId()} to indicate a ref deletion. + * {@link org.eclipse.jgit.lib.ObjectId#zeroId()} to indicate a + * ref deletion. * @param name * name of the ref being affected. */ public ReceiveCommand(final ObjectId oldId, final ObjectId newId, final String name) { if (oldId == null) { - throw new IllegalArgumentException(JGitText.get().oldIdMustNotBeNull); + throw new IllegalArgumentException( + JGitText.get().oldIdMustNotBeNull); } if (newId == null) { - throw new IllegalArgumentException(JGitText.get().newIdMustNotBeNull); + throw new IllegalArgumentException( + JGitText.get().newIdMustNotBeNull); + } + if (name == null || name.isEmpty()) { + throw new IllegalArgumentException( + JGitText.get().nameMustNotBeNullOrEmpty); } this.oldId = oldId; + this.oldSymref = null; this.newId = newId; + this.newSymref = null; this.name = name; type = Type.UPDATE; @@ -263,31 +333,46 @@ public class ReceiveCommand { } /** - * Create a new command for {@link BaseReceivePack}. + * Create a new command for + * {@link org.eclipse.jgit.transport.BaseReceivePack}. * * @param oldId * the old object id; must not be null. Use - * {@link ObjectId#zeroId()} to indicate a ref creation. + * {@link org.eclipse.jgit.lib.ObjectId#zeroId()} to indicate a + * ref creation. * @param newId * the new object id; must not be null. Use - * {@link ObjectId#zeroId()} to indicate a ref deletion. + * {@link org.eclipse.jgit.lib.ObjectId#zeroId()} to indicate a + * ref deletion. * @param name * name of the ref being affected. * @param type - * type of the command. Must be {@link Type#CREATE} if {@code - * oldId} is zero, or {@link Type#DELETE} if {@code newId} is zero. + * type of the command. Must be + * {@link org.eclipse.jgit.transport.ReceiveCommand.Type#CREATE} + * if {@code + * oldId} is zero, or + * {@link org.eclipse.jgit.transport.ReceiveCommand.Type#DELETE} + * if {@code newId} is zero. * @since 2.0 */ public ReceiveCommand(final ObjectId oldId, final ObjectId newId, final String name, final Type type) { if (oldId == null) { - throw new IllegalArgumentException(JGitText.get().oldIdMustNotBeNull); + throw new IllegalArgumentException( + JGitText.get().oldIdMustNotBeNull); } if (newId == null) { - throw new IllegalArgumentException(JGitText.get().newIdMustNotBeNull); + throw new IllegalArgumentException( + JGitText.get().newIdMustNotBeNull); + } + if (name == null || name.isEmpty()) { + throw new IllegalArgumentException( + JGitText.get().nameMustNotBeNullOrEmpty); } this.oldId = oldId; + this.oldSymref = null; this.newId = newId; + this.newSymref = null; this.name = name; switch (type) { case CREATE: @@ -311,42 +396,203 @@ public class ReceiveCommand { } break; default: - throw new IllegalStateException(JGitText.get().enumValueNotSupported0); + throw new IllegalStateException( + JGitText.get().enumValueNotSupported0); } this.type = type; } - /** @return the old value the client thinks the ref has. */ + /** + * Create a command to switch a reference from object to symbolic. + * + * @param oldId + * the old object id; must not be null. Use + * {@link ObjectId#zeroId()} to indicate a ref creation. + * @param newSymref + * new target, must begin with {@code "refs/"}. Use {@code null} + * to indicate a ref deletion. + * @param name + * name of the reference to make symbolic. + * @since 4.10 + */ + private ReceiveCommand(ObjectId oldId, String newSymref, String name) { + if (oldId == null) { + throw new IllegalArgumentException( + JGitText.get().oldIdMustNotBeNull); + } + if (name == null || name.isEmpty()) { + throw new IllegalArgumentException( + JGitText.get().nameMustNotBeNullOrEmpty); + } + this.oldId = oldId; + this.oldSymref = null; + this.newId = ObjectId.zeroId(); + this.newSymref = newSymref; + this.name = name; + if (AnyObjectId.equals(ObjectId.zeroId(), oldId)) { + type = Type.CREATE; + } else if (newSymref != null) { + type = Type.UPDATE; + } else { + type = Type.DELETE; + } + typeIsCorrect = true; + } + + /** + * Create a command to switch a reference from symbolic to object. + * + * @param oldSymref + * expected old target. Use {@code null} to indicate a ref + * creation. + * @param newId + * the new object id; must not be null. Use + * {@link ObjectId#zeroId()} to indicate a ref deletion. + * @param name + * name of the reference to convert from symbolic. + * @since 4.10 + */ + private ReceiveCommand(String oldSymref, ObjectId newId, String name) { + if (newId == null) { + throw new IllegalArgumentException( + JGitText.get().newIdMustNotBeNull); + } + if (name == null || name.isEmpty()) { + throw new IllegalArgumentException( + JGitText.get().nameMustNotBeNullOrEmpty); + } + this.oldId = ObjectId.zeroId(); + this.oldSymref = oldSymref; + this.newId = newId; + this.newSymref = null; + this.name = name; + if (oldSymref == null) { + type = Type.CREATE; + } else if (!AnyObjectId.equals(ObjectId.zeroId(), newId)) { + type = Type.UPDATE; + } else { + type = Type.DELETE; + } + typeIsCorrect = true; + } + + /** + * Create a command to switch a symbolic reference's target. + * + * @param oldTarget + * expected old target. Use {@code null} to indicate a ref + * creation. + * @param newTarget + * new target. Use {@code null} to indicate a ref deletion. + * @param name + * name of the reference to make symbolic. + * @since 4.10 + */ + private ReceiveCommand(@Nullable String oldTarget, String newTarget, String name) { + if (name == null || name.isEmpty()) { + throw new IllegalArgumentException( + JGitText.get().nameMustNotBeNullOrEmpty); + } + this.oldId = ObjectId.zeroId(); + this.oldSymref = oldTarget; + this.newId = ObjectId.zeroId(); + this.newSymref = newTarget; + this.name = name; + if (oldTarget == null) { + if (newTarget == null) { + throw new IllegalArgumentException( + JGitText.get().bothRefTargetsMustNotBeNull); + } + type = Type.CREATE; + } else if (newTarget != null) { + type = Type.UPDATE; + } else { + type = Type.DELETE; + } + typeIsCorrect = true; + } + + /** + * Get the old value the client thinks the ref has. + * + * @return the old value the client thinks the ref has. + */ public ObjectId getOldId() { return oldId; } - /** @return the requested new value for this ref. */ + /** + * Get expected old target for a symbolic reference. + * + * @return expected old target for a symbolic reference. + * @since 4.10 + */ + @Nullable + public String getOldSymref() { + return oldSymref; + } + + /** + * Get the requested new value for this ref. + * + * @return the requested new value for this ref. + */ public ObjectId getNewId() { return newId; } - /** @return the name of the ref being updated. */ + /** + * Get requested new target for a symbolic reference. + * + * @return requested new target for a symbolic reference. + * @since 4.10 + */ + @Nullable + public String getNewSymref() { + return newSymref; + } + + /** + * Get the name of the ref being updated. + * + * @return the name of the ref being updated. + */ public String getRefName() { return name; } - /** @return the type of this command; see {@link Type}. */ + /** + * Get the type of this command; see {@link Type}. + * + * @return the type of this command; see {@link Type}. + */ public Type getType() { return type; } - /** @return the ref, if this was advertised by the connection. */ + /** + * Get the ref, if this was advertised by the connection. + * + * @return the ref, if this was advertised by the connection. + */ public Ref getRef() { return ref; } - /** @return the current status code of this command. */ + /** + * Get the current status code of this command. + * + * @return the current status code of this command. + */ public Result getResult() { return status; } - /** @return the message associated with a failure status. */ + /** + * Get the message associated with a failure status. + * + * @return the message associated with a failure status. + */ public String getMessage() { return message; } @@ -452,8 +698,8 @@ public class ReceiveCommand { /** * Check whether the reflog should be written regardless of repo defaults. * - * @return whether force writing is enabled; null if {@code - * #setForceRefLog(boolean)} was never called. + * @return whether force writing is enabled; {@code null} if + * {@code #setForceRefLog(boolean)} was never called. * @since 4.9 */ @Nullable @@ -490,12 +736,13 @@ public class ReceiveCommand { * If the command's current type is UPDATE, a merge test will be performed * using the supplied RevWalk to determine if {@link #getOldId()} is fully * merged into {@link #getNewId()}. If some commits are not merged the - * update type is changed to {@link Type#UPDATE_NONFASTFORWARD}. + * update type is changed to + * {@link org.eclipse.jgit.transport.ReceiveCommand.Type#UPDATE_NONFASTFORWARD}. * * @param walk * an instance to perform the merge test with. The caller must * allocate and release this object. - * @throws IOException + * @throws java.io.IOException * either oldId or newId is not accessible in the repository * used by the RevWalk. This usually indicates data corruption, * and the command cannot be processed. @@ -525,7 +772,18 @@ public class ReceiveCommand { */ public void execute(final BaseReceivePack rp) { try { - final RefUpdate ru = rp.getRepository().updateRef(getRefName()); + String expTarget = getOldSymref(); + boolean detach = getNewSymref() != null + || (type == Type.DELETE && expTarget != null); + RefUpdate ru = rp.getRepository().updateRef(getRefName(), detach); + if (expTarget != null) { + if (!ru.getRef().isSymbolic() || !ru.getRef().getTarget() + .getName().equals(expTarget)) { + setResult(Result.LOCK_FAILURE); + return; + } + } + ru.setRefLogIdent(rp.getRefLogIdent()); ru.setRefLogMessage(refLogMessage, refLogIncludeResult); switch (getType()) { @@ -546,9 +804,13 @@ public class ReceiveCommand { case UPDATE_NONFASTFORWARD: ru.setForceUpdate(rp.isAllowNonFastForwards()); ru.setExpectedOldObjectId(getOldId()); - ru.setNewObjectId(getNewId()); ru.setRefLogMessage("push", true); //$NON-NLS-1$ - setResult(ru.update(rp.getRevWalk())); + if (getNewSymref() != null) { + setResult(ru.link(getNewSymref())); + } else { + ru.setNewObjectId(getNewId()); + setResult(ru.update(rp.getRevWalk())); + } break; } } catch (IOException err) { @@ -620,6 +882,7 @@ public class ReceiveCommand { JGitText.get().lockError, err.getMessage())); } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/ReceivePack.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/ReceivePack.java index 169df3be26..7c5f32ac0d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/ReceivePack.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/ReceivePack.java @@ -130,7 +130,11 @@ public class ReceivePack extends BaseReceivePack { pushOptions = options; } - /** @return the hook invoked before updates occur. */ + /** + * Get the hook invoked before updates occur. + * + * @return the hook invoked before updates occur. + */ public PreReceiveHook getPreReceiveHook() { return preReceive; } @@ -141,7 +145,8 @@ public class ReceivePack extends BaseReceivePack { * Only valid commands (those which have no obvious errors according to the * received input and this instance's configuration) are passed into the * hook. The hook may mark a command with a result of any value other than - * {@link Result#NOT_ATTEMPTED} to block its execution. + * {@link org.eclipse.jgit.transport.ReceiveCommand.Result#NOT_ATTEMPTED} to + * block its execution. * <p> * The hook may be called with an empty command collection if the current * set is completely invalid. @@ -153,7 +158,11 @@ public class ReceivePack extends BaseReceivePack { preReceive = h != null ? h : PreReceiveHook.NULL; } - /** @return the hook invoked after updates occur. */ + /** + * Get the hook invoked after updates occur. + * + * @return the hook invoked after updates occur. + */ public PostReceiveHook getPostReceiveHook() { return postReceive; } @@ -161,9 +170,10 @@ public class ReceivePack extends BaseReceivePack { /** * Set the hook which is invoked after commands are executed. * <p> - * Only successful commands (type is {@link Result#OK}) are passed into the - * hook. The hook may be called with an empty command collection if the - * current set all resulted in an error. + * Only successful commands (type is + * {@link org.eclipse.jgit.transport.ReceiveCommand.Result#OK}) are passed + * into the hook. The hook may be called with an empty command collection if + * the current set all resulted in an error. * * @param h * the hook instance; may be null to disable the hook. @@ -173,6 +183,9 @@ public class ReceivePack extends BaseReceivePack { } /** + * Set whether this class will report command failures as warning messages + * before sending the command results. + * * @param echo * if true this class will report command failures as warning * messages before sending the command results. This is usually @@ -199,7 +212,7 @@ public class ReceivePack extends BaseReceivePack { * through. When run over SSH this should be tied back to the * standard error channel of the command execution. For most * other network connections this should be null. - * @throws IOException + * @throws java.io.IOException */ public void receive(final InputStream input, final OutputStream output, final OutputStream messages) throws IOException { @@ -215,6 +228,7 @@ public class ReceivePack extends BaseReceivePack { } } + /** {@inheritDoc} */ @Override protected void enableCapabilities() { reportStatus = isCapabilityEnabled(CAPABILITY_REPORT_STATUS); @@ -325,6 +339,7 @@ public class ReceivePack extends BaseReceivePack { repo.autoGC(NullProgressMonitor.INSTANCE); } + /** {@inheritDoc} */ @Override protected String getLockMessageProcessName() { return "jgit receive-pack"; //$NON-NLS-1$ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/ReceivedPackStatistics.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/ReceivedPackStatistics.java index 052d5506f8..dec528970a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/ReceivedPackStatistics.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/ReceivedPackStatistics.java @@ -46,7 +46,7 @@ package org.eclipse.jgit.transport; import org.eclipse.jgit.lib.Constants; /** - * Statistics about {@link PackParser}. + * Statistics about {@link org.eclipse.jgit.transport.PackParser}. * * @since 4.6 */ @@ -65,57 +65,101 @@ public class ReceivedPackStatistics { private long numDeltaBlob; private long numDeltaTag; - /** @return number of bytes read from the input stream */ + /** + * Get number of bytes read from the input stream + * + * @return number of bytes read from the input stream + */ public long getNumBytesRead() { return numBytesRead; } - /** @return number of whole commit objects in the pack */ + /** + * Get number of whole commit objects in the pack + * + * @return number of whole commit objects in the pack + */ public long getNumWholeCommit() { return numWholeCommit; } - /** @return number of whole tree objects in the pack */ + /** + * Get number of whole tree objects in the pack + * + * @return number of whole tree objects in the pack + */ public long getNumWholeTree() { return numWholeTree; } - /** @return number of whole blob objects in the pack */ + /** + * Get number of whole blob objects in the pack + * + * @return number of whole blob objects in the pack + */ public long getNumWholeBlob() { return numWholeBlob; } - /** @return number of whole tag objects in the pack */ + /** + * Get number of whole tag objects in the pack + * + * @return number of whole tag objects in the pack + */ public long getNumWholeTag() { return numWholeTag; } - /** @return number of offset delta objects in the pack */ + /** + * Get number of offset delta objects in the pack + * + * @return number of offset delta objects in the pack + */ public long getNumOfsDelta() { return numOfsDelta; } - /** @return number of ref delta objects in the pack */ + /** + * Get number of ref delta objects in the pack + * + * @return number of ref delta objects in the pack + */ public long getNumRefDelta() { return numRefDelta; } - /** @return number of delta commit objects in the pack */ + /** + * Get number of delta commit objects in the pack + * + * @return number of delta commit objects in the pack + */ public long getNumDeltaCommit() { return numDeltaCommit; } - /** @return number of delta tree objects in the pack */ + /** + * Get number of delta tree objects in the pack + * + * @return number of delta tree objects in the pack + */ public long getNumDeltaTree() { return numDeltaTree; } - /** @return number of delta blob objects in the pack */ + /** + * Get number of delta blob objects in the pack + * + * @return number of delta blob objects in the pack + */ public long getNumDeltaBlob() { return numDeltaBlob; } - /** @return number of delta tag objects in the pack */ + /** + * Get number of delta tag objects in the pack + * + * @return number of delta tag objects in the pack + */ public long getNumDeltaTag() { return numDeltaTag; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/RefAdvertiser.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/RefAdvertiser.java index 745e813c41..5eb1661738 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/RefAdvertiser.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/RefAdvertiser.java @@ -67,7 +67,10 @@ import org.eclipse.jgit.lib.RefComparator; import org.eclipse.jgit.lib.Repository; import org.eclipse.jgit.util.RefMap; -/** Support for the start of {@link UploadPack} and {@link ReceivePack}. */ +/** + * Support for the start of {@link org.eclipse.jgit.transport.UploadPack} and + * {@link org.eclipse.jgit.transport.ReceivePack}. + */ public abstract class RefAdvertiser { /** Advertiser which frames lines in a {@link PacketLineOut} format. */ public static class PacketLineOutRefAdvertiser extends RefAdvertiser { @@ -247,7 +250,6 @@ public abstract class RefAdvertiser { * The symbolic ref, e.g. "HEAD" * @param to * The real ref it points to, e.g. "refs/heads/master" - * * @since 3.6 */ public void addSymref(String from, String to) { @@ -262,7 +264,7 @@ public abstract class RefAdvertiser { * sorted before display if necessary, and therefore may appear * in any order. * @return set of ObjectIds that were advertised to the client. - * @throws IOException + * @throws java.io.IOException * the underlying output stream failed to write out an * advertisement record. */ @@ -305,7 +307,7 @@ public abstract class RefAdvertiser { * * @param id * identity of the object that is assumed to exist. - * @throws IOException + * @throws java.io.IOException * the underlying output stream failed to write out an * advertisement record. */ @@ -313,7 +315,11 @@ public abstract class RefAdvertiser { advertiseAnyOnce(id, ".have"); //$NON-NLS-1$ } - /** @return true if no advertisements have been sent yet. */ + /** + * Whether no advertisements have been sent yet. + * + * @return true if no advertisements have been sent yet. + */ public boolean isEmpty() { return first; } @@ -341,7 +347,7 @@ public abstract class RefAdvertiser { * @param refName * name of the reference to advertise the object as, can be any * string not including the NUL byte. - * @throws IOException + * @throws java.io.IOException * the underlying output stream failed to write out an * advertisement record. */ @@ -372,7 +378,7 @@ public abstract class RefAdvertiser { * @param line * the advertisement line to be written. The line always ends * with LF. Never null or the empty string. - * @throws IOException + * @throws java.io.IOException * the underlying output stream failed to write out an * advertisement record. */ @@ -381,7 +387,7 @@ public abstract class RefAdvertiser { /** * Mark the end of the advertisements. * - * @throws IOException + * @throws java.io.IOException * the underlying output stream failed to write out an * advertisement record. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/RefFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/RefFilter.java index d4f85f2af5..bbe4f84bc8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/RefFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/RefFilter.java @@ -50,14 +50,17 @@ import org.eclipse.jgit.lib.Ref; /** * Filters the list of refs that are advertised to the client. * <p> - * The filter is called by {@link ReceivePack} and {@link UploadPack} to ensure - * that the refs are filtered before they are advertised to the client. + * The filter is called by {@link org.eclipse.jgit.transport.ReceivePack} and + * {@link org.eclipse.jgit.transport.UploadPack} to ensure that the refs are + * filtered before they are advertised to the client. * <p> * This can be used by applications to control visibility of certain refs based * on a custom set of rules. */ public interface RefFilter { - /** The default filter, allows all refs to be shown. */ + /** + * The default filter, allows all refs to be shown. + */ public static final RefFilter DEFAULT = new RefFilter() { @Override public Map<String, Ref> filter (final Map<String, Ref> refs) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/RefLeaseSpec.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/RefLeaseSpec.java index 734f523c4c..ea0f84a97f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/RefLeaseSpec.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/RefLeaseSpec.java @@ -47,6 +47,7 @@ import java.io.Serializable; /** * Describes the expected value for a ref being pushed. + * * @since 4.7 */ public class RefLeaseSpec implements Serializable { @@ -59,6 +60,7 @@ public class RefLeaseSpec implements Serializable { private final String expected; /** + * <p>Constructor for RefLeaseSpec.</p> * * @param ref * ref being pushed @@ -89,6 +91,7 @@ public class RefLeaseSpec implements Serializable { return expected; } + /** {@inheritDoc} */ @Override public String toString() { final StringBuilder r = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/RefSpec.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/RefSpec.java index 64f6c3fb97..e1b306ea90 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/RefSpec.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/RefSpec.java @@ -153,7 +153,7 @@ public class RefSpec implements Serializable { * @param mode * whether to allow a wildcard on one side without a wildcard on * the other. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * the specification is invalid. * @since 4.5 */ @@ -219,7 +219,7 @@ public class RefSpec implements Serializable { * * @param spec * string describing the specification. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * the specification is invalid. */ public RefSpec(final String spec) { @@ -288,7 +288,7 @@ public class RefSpec implements Serializable { * @param source * new value for source in the returned instance. * @return a new RefSpec with source as specified. - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * There is already a destination configured, and the wildcard * status of the existing destination disagrees with the * wildcard status of the new source. @@ -327,7 +327,7 @@ public class RefSpec implements Serializable { * @param destination * new value for destination in the returned instance. * @return a new RefSpec with destination as specified. - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * There is already a source configured, and the wildcard status * of the existing source disagrees with the wildcard status of * the new destination. @@ -350,7 +350,7 @@ public class RefSpec implements Serializable { * @param destination * new value for destination in the returned instance. * @return a new RefSpec with destination as specified. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * The wildcard status of the new source disagrees with the * wildcard status of the new destination. */ @@ -421,7 +421,7 @@ public class RefSpec implements Serializable { * @return a new specification expanded from provided ref name. Result * specification is wildcard if and only if provided ref name is * wildcard. - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * when the RefSpec was constructed with wildcard mode that * doesn't require matching wildcards. */ @@ -453,7 +453,7 @@ public class RefSpec implements Serializable { * @return a new specification expanded from provided ref name. Result * specification is wildcard if and only if provided ref name is * wildcard. - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * when the RefSpec was constructed with wildcard mode that * doesn't require matching wildcards. */ @@ -473,7 +473,7 @@ public class RefSpec implements Serializable { * @return a new specification expanded from provided ref name. Result * specification is wildcard if and only if provided ref name is * wildcard. - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * when the RefSpec was constructed with wildcard mode that * doesn't require matching wildcards. */ @@ -504,7 +504,7 @@ public class RefSpec implements Serializable { * @return a new specification expanded from provided ref name. Result * specification is wildcard if and only if provided ref name is * wildcard. - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * when the RefSpec was constructed with wildcard mode that * doesn't require matching wildcards. */ @@ -556,6 +556,7 @@ public class RefSpec implements Serializable { return true; } + /** {@inheritDoc} */ @Override public int hashCode() { int hc = 0; @@ -566,6 +567,7 @@ public class RefSpec implements Serializable { return hc; } + /** {@inheritDoc} */ @Override public boolean equals(final Object obj) { if (!(obj instanceof RefSpec)) @@ -590,6 +592,7 @@ public class RefSpec implements Serializable { return a.equals(b); } + /** {@inheritDoc} */ @Override public String toString() { final StringBuilder r = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/RemoteConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/RemoteConfig.java index c968ba37cf..7b882ec8d5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/RemoteConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/RemoteConfig.java @@ -109,7 +109,7 @@ public class RemoteConfig implements Serializable { * @return all remotes configurations existing in provided repository * configuration. Returned configurations are ordered * lexicographically by names. - * @throws URISyntaxException + * @throws java.net.URISyntaxException * one of the URIs within the remote's configuration is invalid. */ public static List<RemoteConfig> getAllRemoteConfigs(final Config rc) @@ -157,7 +157,7 @@ public class RemoteConfig implements Serializable { * The configuration must already be loaded into memory. * @param remoteName * subsection key indicating the name of this remote. - * @throws URISyntaxException + * @throws java.net.URISyntaxException * one of the URIs within the remote's configuration is invalid. */ public RemoteConfig(final Config rc, final String remoteName) @@ -525,6 +525,9 @@ public class RemoteConfig implements Serializable { } /** + * Whether pushing to the remote automatically deletes remote refs which + * don't exist on the source side. + * * @return true if pushing to the remote automatically deletes remote refs * which don't exist on the source side. */ @@ -542,7 +545,11 @@ public class RemoteConfig implements Serializable { mirror = m; } - /** @return timeout (in seconds) before aborting an IO operation. */ + /** + * Get timeout (in seconds) before aborting an IO operation. + * + * @return timeout (in seconds) before aborting an IO operation. + */ public int getTimeout() { return timeout; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/RemoteRefUpdate.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/RemoteRefUpdate.java index 5c58346189..3e9b16ee49 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/RemoteRefUpdate.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/RemoteRefUpdate.java @@ -55,17 +55,18 @@ import org.eclipse.jgit.revwalk.RevWalk; /** * Represent request and status of a remote ref update. Specification is - * provided by client, while status is handled by {@link PushProcess} class, - * being read-only for client. + * provided by client, while status is handled by + * {@link org.eclipse.jgit.transport.PushProcess} class, being read-only for + * client. * <p> * Client can create instances of this class directly, basing on user - * specification and advertised refs ({@link Connection} or through - * {@link Transport} helper methods. Apply this specification on remote - * repository using - * {@link Transport#push(org.eclipse.jgit.lib.ProgressMonitor, java.util.Collection)} + * specification and advertised refs + * ({@link org.eclipse.jgit.transport.Connection} or through + * {@link org.eclipse.jgit.transport.Transport} helper methods. Apply this + * specification on remote repository using + * {@link org.eclipse.jgit.transport.Transport#push(org.eclipse.jgit.lib.ProgressMonitor, java.util.Collection)} * method. * </p> - * */ public class RemoteRefUpdate { /** @@ -149,16 +150,19 @@ public class RemoteRefUpdate { /** * Construct remote ref update request by providing an update specification. - * Object is created with default {@link Status#NOT_ATTEMPTED} status and no - * message. + * Object is created with default + * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#NOT_ATTEMPTED} + * status and no message. * * @param localDb * local repository to push from. * @param srcRef * source revision - any string resolvable by - * {@link Repository#resolve(String)}. This resolves to the new - * object that the caller want remote ref to be after update. Use - * null or {@link ObjectId#zeroId()} string for delete request. + * {@link org.eclipse.jgit.lib.Repository#resolve(String)}. This + * resolves to the new object that the caller want remote ref to + * be after update. Use null or + * {@link org.eclipse.jgit.lib.ObjectId#zeroId()} string for + * delete request. * @param remoteName * full name of a remote ref to update, e.g. "refs/heads/master" * (no wildcard, no short name). @@ -176,13 +180,14 @@ public class RemoteRefUpdate { * advertised by remote side before update; update will take * place ONLY if remote side advertise exactly this expected id; * null if caller doesn't care what object id remote side - * advertise. Use {@link ObjectId#zeroId()} when expecting no - * remote ref with this name. - * @throws IOException + * advertise. Use {@link org.eclipse.jgit.lib.ObjectId#zeroId()} + * when expecting no remote ref with this name. + * @throws java.io.IOException * when I/O error occurred during creating - * {@link TrackingRefUpdate} for local tracking branch or srcRef - * can't be resolved to any object. - * @throws IllegalArgumentException + * {@link org.eclipse.jgit.transport.TrackingRefUpdate} for + * local tracking branch or srcRef can't be resolved to any + * object. + * @throws java.lang.IllegalArgumentException * if some required parameter was null */ public RemoteRefUpdate(final Repository localDb, final String srcRef, @@ -196,8 +201,9 @@ public class RemoteRefUpdate { /** * Construct remote ref update request by providing an update specification. - * Object is created with default {@link Status#NOT_ATTEMPTED} status and no - * message. + * Object is created with default + * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#NOT_ATTEMPTED} + * status and no message. * * @param localDb * local repository to push from. @@ -220,13 +226,14 @@ public class RemoteRefUpdate { * advertised by remote side before update; update will take * place ONLY if remote side advertise exactly this expected id; * null if caller doesn't care what object id remote side - * advertise. Use {@link ObjectId#zeroId()} when expecting no - * remote ref with this name. - * @throws IOException + * advertise. Use {@link org.eclipse.jgit.lib.ObjectId#zeroId()} + * when expecting no remote ref with this name. + * @throws java.io.IOException * when I/O error occurred during creating - * {@link TrackingRefUpdate} for local tracking branch or srcRef - * can't be resolved to any object. - * @throws IllegalArgumentException + * {@link org.eclipse.jgit.transport.TrackingRefUpdate} for + * local tracking branch or srcRef can't be resolved to any + * object. + * @throws java.lang.IllegalArgumentException * if some required parameter was null */ public RemoteRefUpdate(final Repository localDb, final Ref srcRef, @@ -240,8 +247,9 @@ public class RemoteRefUpdate { /** * Construct remote ref update request by providing an update specification. - * Object is created with default {@link Status#NOT_ATTEMPTED} status and no - * message. + * Object is created with default + * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#NOT_ATTEMPTED} + * status and no message. * * @param localDb * local repository to push from. @@ -250,7 +258,8 @@ public class RemoteRefUpdate { * be used instead. * @param srcId * The new object that the caller wants remote ref to be after - * update. Use null or {@link ObjectId#zeroId()} for delete + * update. Use null or + * {@link org.eclipse.jgit.lib.ObjectId#zeroId()} for delete * request. * @param remoteName * full name of a remote ref to update, e.g. "refs/heads/master" @@ -269,13 +278,14 @@ public class RemoteRefUpdate { * advertised by remote side before update; update will take * place ONLY if remote side advertise exactly this expected id; * null if caller doesn't care what object id remote side - * advertise. Use {@link ObjectId#zeroId()} when expecting no - * remote ref with this name. - * @throws IOException + * advertise. Use {@link org.eclipse.jgit.lib.ObjectId#zeroId()} + * when expecting no remote ref with this name. + * @throws java.io.IOException * when I/O error occurred during creating - * {@link TrackingRefUpdate} for local tracking branch or srcRef - * can't be resolved to any object. - * @throws IllegalArgumentException + * {@link org.eclipse.jgit.transport.TrackingRefUpdate} for + * local tracking branch or srcRef can't be resolved to any + * object. + * @throws java.lang.IllegalArgumentException * if some required parameter was null */ public RemoteRefUpdate(final Repository localDb, final String srcRef, @@ -333,10 +343,11 @@ public class RemoteRefUpdate { * configuration base. * @param newExpectedOldObjectId * new expected object id value. - * @throws IOException + * @throws java.io.IOException * when I/O error occurred during creating - * {@link TrackingRefUpdate} for local tracking branch or srcRef - * of base object no longer can be resolved to any object. + * {@link org.eclipse.jgit.transport.TrackingRefUpdate} for + * local tracking branch or srcRef of base object no longer can + * be resolved to any object. */ public RemoteRefUpdate(final RemoteRefUpdate base, final ObjectId newExpectedOldObjectId) throws IOException { @@ -346,6 +357,8 @@ public class RemoteRefUpdate { } /** + * Get expected old object id + * * @return expectedOldObjectId required to be advertised by remote side, as * set in constructor; may be null. */ @@ -354,6 +367,9 @@ public class RemoteRefUpdate { } /** + * Whether some object is required to be advertised by remote side, as set + * in constructor + * * @return true if some object is required to be advertised by remote side, * as set in constructor; false otherwise. */ @@ -362,6 +378,8 @@ public class RemoteRefUpdate { } /** + * Get new object id + * * @return newObjectId for remote ref, as set in constructor. */ public ObjectId getNewObjectId() { @@ -369,6 +387,8 @@ public class RemoteRefUpdate { } /** + * Whether this update is a deleting update + * * @return true if this update is deleting update; false otherwise. */ public boolean isDelete() { @@ -376,6 +396,8 @@ public class RemoteRefUpdate { } /** + * Get name of remote ref to update + * * @return name of remote ref to update, as set in constructor. */ public String getRemoteName() { @@ -383,6 +405,8 @@ public class RemoteRefUpdate { } /** + * Get tracking branch update if localName was set in constructor. + * * @return local tracking branch update if localName was set in constructor. */ public TrackingRefUpdate getTrackingRefUpdate() { @@ -390,9 +414,12 @@ public class RemoteRefUpdate { } /** + * Get source revision as specified by user (in constructor) + * * @return source revision as specified by user (in constructor), could be - * any string parseable by {@link Repository#resolve(String)}; can - * be null if specified that way in constructor - this stands for + * any string parseable by + * {@link org.eclipse.jgit.lib.Repository#resolve(String)}; can be + * null if specified that way in constructor - this stands for * delete request. */ public String getSrcRef() { @@ -400,6 +427,8 @@ public class RemoteRefUpdate { } /** + * Whether user specified a local tracking branch for remote update + * * @return true if user specified a local tracking branch for remote update; * false otherwise. */ @@ -408,6 +437,8 @@ public class RemoteRefUpdate { } /** + * Whether this update is forced regardless of old remote ref object + * * @return true if this update is forced regardless of old remote ref * object; false otherwise. */ @@ -416,6 +447,8 @@ public class RemoteRefUpdate { } /** + * Get status of remote ref update operation. + * * @return status of remote ref update operation. */ public Status getStatus() { @@ -424,7 +457,8 @@ public class RemoteRefUpdate { /** * Check whether update was fast-forward. Note that this result is - * meaningful only after successful update (when status is {@link Status#OK}). + * meaningful only after successful update (when status is + * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#OK}). * * @return true if update was fast-forward; false otherwise. */ @@ -433,6 +467,9 @@ public class RemoteRefUpdate { } /** + * Get message describing reasons of status when needed/possible; may be + * null. + * * @return message describing reasons of status when needed/possible; may be * null. */ @@ -461,7 +498,7 @@ public class RemoteRefUpdate { * * @param walk * walker used for checking update properties. - * @throws IOException + * @throws java.io.IOException * when I/O error occurred during update */ protected void updateTrackingRef(final RevWalk walk) throws IOException { @@ -471,6 +508,7 @@ public class RemoteRefUpdate { trackingRefUpdate.setResult(localUpdate.update(walk)); } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/RemoteSession.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/RemoteSession.java index d6a2fe6a80..525c895f45 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/RemoteSession.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/RemoteSession.java @@ -65,17 +65,18 @@ public interface RemoteSession { * Generate a new remote process to execute the given command. This function * should also start execution and may need to create the streams prior to * execution. + * * @param commandName * command to execute * @param timeout * timeout value, in seconds, for command execution * @return a new remote process - * @throws IOException + * @throws java.io.IOException * may be thrown in several cases. For example, on problems * opening input or output streams or on problems connecting or * communicating with the remote host. For the latter two cases, * a TransportException may be thrown (a subclass of - * IOException). + * java.io.IOException). */ public Process exec(String commandName, int timeout) throws IOException; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/RequestNotYetReadException.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/RequestNotYetReadException.java index 8b45174c01..428af960b9 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/RequestNotYetReadException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/RequestNotYetReadException.java @@ -51,12 +51,16 @@ package org.eclipse.jgit.transport; public class RequestNotYetReadException extends IllegalStateException { private static final long serialVersionUID = 1L; - /** Initialize with no message. */ + /** + * Initialize with no message. + */ public RequestNotYetReadException() { // Do not set a message. } /** + * <p>Constructor for RequestNotYetReadException.</p> + * * @param msg * a message explaining the state. This message should not * be shown to an end-user. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/ServiceMayNotContinueException.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/ServiceMayNotContinueException.java index 87c9a50038..940d2e2648 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/ServiceMayNotContinueException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/ServiceMayNotContinueException.java @@ -59,13 +59,17 @@ public class ServiceMayNotContinueException extends IOException { private final int statusCode; private boolean output; - /** Initialize with no message. */ + /** + * Initialize with no message. + */ public ServiceMayNotContinueException() { // Do not set a message. statusCode = FORBIDDEN; } /** + * <p>Constructor for ServiceMayNotContinueException.</p> + * * @param msg * a message explaining why it cannot continue. This message may * be shown to an end-user. @@ -76,6 +80,8 @@ public class ServiceMayNotContinueException extends IOException { } /** + * <p>Constructor for ServiceMayNotContinueException.</p> + * * @param msg * a message explaining why it cannot continue. This message may * be shown to an end-user. @@ -89,6 +95,8 @@ public class ServiceMayNotContinueException extends IOException { } /** + * <p>Constructor for ServiceMayNotContinueException.</p> + * * @param msg * a message explaining why it cannot continue. This message may * be shown to an end-user. @@ -102,6 +110,8 @@ public class ServiceMayNotContinueException extends IOException { } /** + * <p>Constructor for ServiceMayNotContinueException.</p> + * * @param msg * a message explaining why it cannot continue. This message may * be shown to an end-user. @@ -128,17 +138,25 @@ public class ServiceMayNotContinueException extends IOException { this(JGitText.get().internalServerError, cause); } - /** @return true if the message was already output to the client. */ + /** + * Whether the message was already output to the client. + * + * @return {@code true} if the message was already output to the client. + */ public boolean isOutput() { return output; } - /** Mark this message has being sent to the client. */ + /** + * Mark this message has being sent to the client. + */ public void setOutput() { output = true; } /** + * Get status code + * * @return true if the message was already output to the client. * @since 4.5 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/SideBandInputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/SideBandInputStream.java index fe9f2a3155..25486cb64f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/SideBandInputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/SideBandInputStream.java @@ -120,6 +120,7 @@ class SideBandInputStream extends InputStream { out = outputStream; } + /** {@inheritDoc} */ @Override public int read() throws IOException { needDataPacket(); @@ -129,6 +130,7 @@ class SideBandInputStream extends InputStream { return rawIn.read(); } + /** {@inheritDoc} */ @Override public int read(final byte[] b, int off, int len) throws IOException { int r = 0; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/SideBandOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/SideBandOutputStream.java index 0303eed9a7..af65827ca6 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/SideBandOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/SideBandOutputStream.java @@ -127,12 +127,14 @@ public class SideBandOutputStream extends OutputStream { writeBuffer(); } + /** {@inheritDoc} */ @Override public void flush() throws IOException { flushBuffer(); out.flush(); } + /** {@inheritDoc} */ @Override public void write(final byte[] b, int off, int len) throws IOException { while (0 < len) { @@ -159,6 +161,7 @@ public class SideBandOutputStream extends OutputStream { } } + /** {@inheritDoc} */ @Override public void write(final int b) throws IOException { if (cnt == buffer.length) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/SideBandProgressMonitor.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/SideBandProgressMonitor.java index aa800657e1..365545a092 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/SideBandProgressMonitor.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/SideBandProgressMonitor.java @@ -60,6 +60,7 @@ class SideBandProgressMonitor extends BatchingProgressMonitor { write = true; } + /** {@inheritDoc} */ @Override protected void onUpdate(String taskName, int workCurr) { StringBuilder s = new StringBuilder(); @@ -68,6 +69,7 @@ class SideBandProgressMonitor extends BatchingProgressMonitor { send(s); } + /** {@inheritDoc} */ @Override protected void onEndTask(String taskName, int workCurr) { StringBuilder s = new StringBuilder(); @@ -82,6 +84,7 @@ class SideBandProgressMonitor extends BatchingProgressMonitor { s.append(workCurr); } + /** {@inheritDoc} */ @Override protected void onUpdate(String taskName, int cmp, int totalWork, int pcnt) { StringBuilder s = new StringBuilder(); @@ -90,6 +93,7 @@ class SideBandProgressMonitor extends BatchingProgressMonitor { send(s); } + /** {@inheritDoc} */ @Override protected void onEndTask(String taskName, int cmp, int totalWork, int pcnt) { StringBuilder s = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/SignedPushConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/SignedPushConfig.java index 1ecbed95c7..f404737d14 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/SignedPushConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/SignedPushConfig.java @@ -60,7 +60,9 @@ public class SignedPushConfig { private int certNonceSlopLimit; private NonceGenerator nonceGenerator; - /** Create a new config with default values disabling push verification. */ + /** + * Create a new config with default values disabling push verification. + */ public SignedPushConfig() { } @@ -73,9 +75,10 @@ public class SignedPushConfig { * Set the seed used by the nonce verifier. * <p> * Setting this to a non-null value enables push certificate verification - * using the default {@link HMACSHA1NonceGenerator} implementation, if a - * different implementation was not set using {@link - * #setNonceGenerator(NonceGenerator)}. + * using the default + * {@link org.eclipse.jgit.transport.HMACSHA1NonceGenerator} implementation, + * if a different implementation was not set using + * {@link #setNonceGenerator(NonceGenerator)}. * * @param seed * new seed value. @@ -84,7 +87,11 @@ public class SignedPushConfig { certNonceSeed = seed; } - /** @return the configured seed. */ + /** + * Get the configured seed. + * + * @return the configured seed. + */ public String getCertNonceSeed() { return certNonceSeed; } @@ -101,18 +108,23 @@ public class SignedPushConfig { certNonceSlopLimit = limit; } - /** @return the configured nonce slop limit. */ + /** + * Get the configured nonce slop limit. + * + * @return the configured nonce slop limit. + */ public int getCertNonceSlopLimit() { return certNonceSlopLimit; } /** - * Set the {@link NonceGenerator} used for signed pushes. + * Set the {@link org.eclipse.jgit.transport.NonceGenerator} used for signed + * pushes. * <p> - * Setting this to a non-null value enables push certificate verification. If - * this method is called, this implementation will be used instead of the - * default {@link HMACSHA1NonceGenerator} even if {@link - * #setCertNonceSeed(String)} was called. + * Setting this to a non-null value enables push certificate verification. + * If this method is called, this implementation will be used instead of the + * default {@link org.eclipse.jgit.transport.HMACSHA1NonceGenerator} even if + * {@link #setCertNonceSeed(String)} was called. * * @param generator * new nonce generator. @@ -122,12 +134,13 @@ public class SignedPushConfig { } /** - * Get the {@link NonceGenerator} used for signed pushes. + * Get the {@link org.eclipse.jgit.transport.NonceGenerator} used for signed + * pushes. * <p> * If {@link #setNonceGenerator(NonceGenerator)} was used to set a non-null - * implementation, that will be returned. If no custom implementation was set - * but {@link #setCertNonceSeed(String)} was called, returns a newly-created - * {@link HMACSHA1NonceGenerator}. + * implementation, that will be returned. If no custom implementation was + * set but {@link #setCertNonceSeed(String)} was called, returns a + * newly-created {@link org.eclipse.jgit.transport.HMACSHA1NonceGenerator}. * * @return the configured nonce generator. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/SshSessionFactory.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/SshSessionFactory.java index 2d5029a010..e0022333ef 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/SshSessionFactory.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/SshSessionFactory.java @@ -54,9 +54,9 @@ import org.eclipse.jgit.util.FS; * communicating with the end-user as well as reading their personal SSH * configuration settings, such as known hosts and private keys. * <p> - * A {@link RemoteSession} must be returned to the factory that created it. - * Callers are encouraged to retain the SshSessionFactory for the duration of - * the period they are using the Session. + * A {@link org.eclipse.jgit.transport.RemoteSession} must be returned to the + * factory that created it. Callers are encouraged to retain the + * SshSessionFactory for the duration of the period they are using the Session. */ public abstract class SshSessionFactory { private static SshSessionFactory INSTANCE = new DefaultSshSessionFactory(); @@ -106,7 +106,7 @@ public abstract class SshSessionFactory { * @param tms * Timeout value, in milliseconds. * @return a session that can contact the remote host. - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * the session could not be created. */ public abstract RemoteSession getSession(URIish uri, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/SshTransport.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/SshTransport.java index 74865dc6dc..62a6f0e175 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/SshTransport.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/SshTransport.java @@ -99,7 +99,7 @@ public abstract class SshTransport extends TcpTransport { * * @param factory * a factory to set, must not be null - * @throws IllegalStateException + * @throws java.lang.IllegalStateException * if session has been already created. */ public void setSshSessionFactory(SshSessionFactory factory) { @@ -112,7 +112,10 @@ public abstract class SshTransport extends TcpTransport { } /** - * @return the SSH session factory that will be used for creating SSH sessions + * Get the SSH session factory + * + * @return the SSH session factory that will be used for creating SSH + * sessions */ public SshSessionFactory getSshSessionFactory() { return sch; @@ -122,7 +125,7 @@ public abstract class SshTransport extends TcpTransport { * Get the default SSH session * * @return a remote session - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * in case of error with opening SSH session */ protected RemoteSession getSession() throws TransportException { @@ -138,6 +141,7 @@ public abstract class SshTransport extends TcpTransport { return sock; } + /** {@inheritDoc} */ @Override public void close() { if (sock != null) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TagOpt.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TagOpt.java index 384e9fc4b2..e1134e8fa8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TagOpt.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TagOpt.java @@ -48,7 +48,9 @@ import java.text.MessageFormat; import org.eclipse.jgit.internal.JGitText; -/** Specification of annotated tag behavior during fetch. */ +/** + * Specification of annotated tag behavior during fetch. + */ public enum TagOpt { /** * Automatically follow tags if we fetch the thing they point at. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TestProtocol.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TestProtocol.java index 8a28e3a7d7..b186f9ecd3 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TestProtocol.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TestProtocol.java @@ -60,15 +60,16 @@ import org.eclipse.jgit.transport.resolver.UploadPackFactory; /** * Protocol for transport between manually-specified repositories in tests. * <p> - * Remote repositories are registered using {@link #register(Object, - * Repository)}, after which they can be accessed using the returned URI. As - * this class provides both the client side (the protocol) and the server side, - * the caller is responsible for setting up and passing the connection context, - * whatever form that may take. + * Remote repositories are registered using + * {@link #register(Object, Repository)}, after which they can be accessed using + * the returned URI. As this class provides both the client side (the protocol) + * and the server side, the caller is responsible for setting up and passing the + * connection context, whatever form that may take. * <p> * Unlike the other built-in protocols, which are automatically-registered * singletons, callers are expected to register/unregister specific protocol - * instances on demand with {@link Transport#register(TransportProtocol)}. + * instances on demand with + * {@link org.eclipse.jgit.transport.Transport#register(TransportProtocol)}. * * @param <C> * the connection type @@ -92,12 +93,16 @@ public class TestProtocol<C> extends TransportProtocol { private final HashMap<URIish, Handle> handles; /** + * Constructor for TestProtocol. + * * @param uploadPackFactory - * factory for creating {@link UploadPack} used by all connections - * from this protocol instance. + * factory for creating + * {@link org.eclipse.jgit.transport.UploadPack} used by all + * connections from this protocol instance. * @param receivePackFactory - * factory for creating {@link ReceivePack} used by all connections - * from this protocol instance. + * factory for creating + * {@link org.eclipse.jgit.transport.ReceivePack} used by all + * connections from this protocol instance. */ public TestProtocol(UploadPackFactory<C> uploadPackFactory, ReceivePackFactory<C> receivePackFactory) { @@ -106,16 +111,19 @@ public class TestProtocol<C> extends TransportProtocol { this.handles = new HashMap<>(); } + /** {@inheritDoc} */ @Override public String getName() { return JGitText.get().transportProtoTest; } + /** {@inheritDoc} */ @Override public Set<String> getSchemes() { return Collections.singleton(SCHEME); } + /** {@inheritDoc} */ @Override public Transport open(URIish uri, Repository local, String remoteName) throws NotSupportedException, TransportException { @@ -127,11 +135,13 @@ public class TestProtocol<C> extends TransportProtocol { return new TransportInternal(local, uri, h); } + /** {@inheritDoc} */ @Override public Set<URIishField> getRequiredFields() { return EnumSet.of(URIishField.HOST, URIishField.PATH); } + /** {@inheritDoc} */ @Override public Set<URIishField> getOptionalFields() { return Collections.emptySet(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TrackingRefUpdate.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TrackingRefUpdate.java index 5aae5ea21a..ba2a673a18 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TrackingRefUpdate.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TrackingRefUpdate.java @@ -49,7 +49,9 @@ import org.eclipse.jgit.lib.AnyObjectId; import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.lib.RefUpdate; -/** Update of a locally stored tracking branch. */ +/** + * Update of a locally stored tracking branch. + */ public class TrackingRefUpdate { private final String remoteName; final String localName; @@ -132,6 +134,8 @@ public class TrackingRefUpdate { } /** + * Get this update wrapped by a ReceiveCommand. + * * @return this update wrapped by a ReceiveCommand. * @since 3.4 */ @@ -201,6 +205,7 @@ public class TrackingRefUpdate { } } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransferConfig.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransferConfig.java index 099629c056..4c70725e42 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransferConfig.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransferConfig.java @@ -157,6 +157,8 @@ public class TransferConfig { } /** + * Create checker to verify fetched objects + * * @return checker to verify fetched objects, or null if checking is not * enabled in the repository configuration. * @since 3.6 @@ -167,6 +169,8 @@ public class TransferConfig { } /** + * Create checker to verify objects pushed into this repository + * * @return checker to verify objects pushed into this repository, or null if * checking is not enabled in the repository configuration. * @since 4.2 @@ -196,6 +200,8 @@ public class TransferConfig { } /** + * Whether to allow clients to request non-advertised tip SHA-1s + * * @return allow clients to request non-advertised tip SHA-1s? * @since 3.1 */ @@ -204,6 +210,8 @@ public class TransferConfig { } /** + * Whether to allow clients to request non-tip SHA-1s + * * @return allow clients to request non-tip SHA-1s? * @since 4.1 */ @@ -212,7 +220,11 @@ public class TransferConfig { } /** - * @return {@link RefFilter} respecting configured hidden refs. + * Get {@link org.eclipse.jgit.transport.RefFilter} respecting configured + * hidden refs. + * + * @return {@link org.eclipse.jgit.transport.RefFilter} respecting + * configured hidden refs. * @since 3.1 */ public RefFilter getRefFilter() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/Transport.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/Transport.java index 649e840626..8db796a83f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/Transport.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/Transport.java @@ -78,7 +78,6 @@ import org.eclipse.jgit.hooks.Hooks; import org.eclipse.jgit.hooks.PrePushHook; import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.lib.Constants; -import org.eclipse.jgit.lib.NullProgressMonitor; import org.eclipse.jgit.lib.ObjectChecker; import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.lib.ProgressMonitor; @@ -215,7 +214,8 @@ public abstract class Transport implements AutoCloseable { * Protocol definitions are held by WeakReference, allowing them to be * garbage collected when the calling application drops all strongly held * references to the TransportProtocol. Therefore applications should use a - * singleton pattern as described in {@link TransportProtocol}'s class + * singleton pattern as described in + * {@link org.eclipse.jgit.transport.TransportProtocol}'s class * documentation to ensure their protocol does not get disabled by garbage * collection earlier than expected. * <p> @@ -270,7 +270,8 @@ public abstract class Transport implements AutoCloseable { /** * Open a new transport instance to connect two repositories. * <p> - * This method assumes {@link Operation#FETCH}. + * This method assumes + * {@link org.eclipse.jgit.transport.Transport.Operation#FETCH}. * * @param local * existing local repository. @@ -279,12 +280,12 @@ public abstract class Transport implements AutoCloseable { * configuration name. * @return the new transport instance. Never null. In case of multiple URIs * in remote configuration, only the first is chosen. - * @throws URISyntaxException + * @throws java.net.URISyntaxException * the location is not a remote defined in the configuration * file and is not a well-formed URL. - * @throws NotSupportedException + * @throws org.eclipse.jgit.errors.NotSupportedException * the protocol specified is not supported. - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * the transport cannot open this URI. */ public static Transport open(final Repository local, final String remote) @@ -306,12 +307,12 @@ public abstract class Transport implements AutoCloseable { * based on the type of connection desired. * @return the new transport instance. Never null. In case of multiple URIs * in remote configuration, only the first is chosen. - * @throws URISyntaxException + * @throws java.net.URISyntaxException * the location is not a remote defined in the configuration * file and is not a well-formed URL. - * @throws NotSupportedException + * @throws org.eclipse.jgit.errors.NotSupportedException * the protocol specified is not supported. - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * the transport cannot open this URI. */ public static Transport open(final Repository local, final String remote, @@ -330,7 +331,8 @@ public abstract class Transport implements AutoCloseable { /** * Open new transport instances to connect two repositories. * <p> - * This method assumes {@link Operation#FETCH}. + * This method assumes + * {@link org.eclipse.jgit.transport.Transport.Operation#FETCH}. * * @param local * existing local repository. @@ -339,12 +341,12 @@ public abstract class Transport implements AutoCloseable { * configuration name. * @return the list of new transport instances for every URI in remote * configuration. - * @throws URISyntaxException + * @throws java.net.URISyntaxException * the location is not a remote defined in the configuration * file and is not a well-formed URL. - * @throws NotSupportedException + * @throws org.eclipse.jgit.errors.NotSupportedException * the protocol specified is not supported. - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * the transport cannot open this URI. */ public static List<Transport> openAll(final Repository local, @@ -366,12 +368,12 @@ public abstract class Transport implements AutoCloseable { * based on the type of connection desired. * @return the list of new transport instances for every URI in remote * configuration. - * @throws URISyntaxException + * @throws java.net.URISyntaxException * the location is not a remote defined in the configuration * file and is not a well-formed URL. - * @throws NotSupportedException + * @throws org.eclipse.jgit.errors.NotSupportedException * the protocol specified is not supported. - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * the transport cannot open this URI. */ public static List<Transport> openAll(final Repository local, @@ -390,7 +392,8 @@ public abstract class Transport implements AutoCloseable { /** * Open a new transport instance to connect two repositories. * <p> - * This method assumes {@link Operation#FETCH}. + * This method assumes + * {@link org.eclipse.jgit.transport.Transport.Operation#FETCH}. * * @param local * existing local repository. @@ -399,11 +402,11 @@ public abstract class Transport implements AutoCloseable { * repository. * @return the new transport instance. Never null. In case of multiple URIs * in remote configuration, only the first is chosen. - * @throws NotSupportedException + * @throws org.eclipse.jgit.errors.NotSupportedException * the protocol specified is not supported. - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * the transport cannot open this URI. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * if provided remote configuration doesn't have any URI * associated. */ @@ -425,11 +428,11 @@ public abstract class Transport implements AutoCloseable { * based on the type of connection desired. * @return the new transport instance. Never null. In case of multiple URIs * in remote configuration, only the first is chosen. - * @throws NotSupportedException + * @throws org.eclipse.jgit.errors.NotSupportedException * the protocol specified is not supported. - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * the transport cannot open this URI. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * if provided remote configuration doesn't have any URI * associated. */ @@ -448,7 +451,8 @@ public abstract class Transport implements AutoCloseable { /** * Open new transport instances to connect two repositories. * <p> - * This method assumes {@link Operation#FETCH}. + * This method assumes + * {@link org.eclipse.jgit.transport.Transport.Operation#FETCH}. * * @param local * existing local repository. @@ -457,9 +461,9 @@ public abstract class Transport implements AutoCloseable { * repository. * @return the list of new transport instances for every URI in remote * configuration. - * @throws NotSupportedException + * @throws org.eclipse.jgit.errors.NotSupportedException * the protocol specified is not supported. - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * the transport cannot open this URI. */ public static List<Transport> openAll(final Repository local, @@ -481,9 +485,9 @@ public abstract class Transport implements AutoCloseable { * based on the type of connection desired. * @return the list of new transport instances for every URI in remote * configuration. - * @throws NotSupportedException + * @throws org.eclipse.jgit.errors.NotSupportedException * the protocol specified is not supported. - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * the transport cannot open this URI. */ public static List<Transport> openAll(final Repository local, @@ -527,9 +531,9 @@ public abstract class Transport implements AutoCloseable { * @param uri * location of the remote repository. * @return the new transport instance. Never null. - * @throws NotSupportedException + * @throws org.eclipse.jgit.errors.NotSupportedException * the protocol specified is not supported. - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * the transport cannot open this URI. */ public static Transport open(final Repository local, final URIish uri) @@ -548,9 +552,9 @@ public abstract class Transport implements AutoCloseable { * name of the remote, if the remote as configured in * {@code local}; otherwise null. * @return the new transport instance. Never null. - * @throws NotSupportedException + * @throws org.eclipse.jgit.errors.NotSupportedException * the protocol specified is not supported. - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * the transport cannot open this URI. */ public static Transport open(Repository local, URIish uri, String remoteName) @@ -580,10 +584,10 @@ public abstract class Transport implements AutoCloseable { * Note that the resulting transport instance can not be used for fetching * or pushing, but only for reading remote refs. * - * @param uri + * @param uri a {@link org.eclipse.jgit.transport.URIish} object. * @return new Transport instance - * @throws NotSupportedException - * @throws TransportException + * @throws org.eclipse.jgit.errors.NotSupportedException + * @throws org.eclipse.jgit.errors.TransportException */ public static Transport open(URIish uri) throws NotSupportedException, TransportException { for (WeakReference<TransportProtocol> ref : protocols) { @@ -601,12 +605,13 @@ public abstract class Transport implements AutoCloseable { } /** - * Convert push remote refs update specification from {@link RefSpec} form - * to {@link RemoteRefUpdate}. Conversion expands wildcards by matching - * source part to local refs. expectedOldObjectId in RemoteRefUpdate is - * set when specified in leases. Tracking branch is configured if RefSpec - * destination matches source of any fetch ref spec for this transport - * remote configuration. + * Convert push remote refs update specification from + * {@link org.eclipse.jgit.transport.RefSpec} form to + * {@link org.eclipse.jgit.transport.RemoteRefUpdate}. Conversion expands + * wildcards by matching source part to local refs. expectedOldObjectId in + * RemoteRefUpdate is set when specified in leases. Tracking branch is + * configured if RefSpec destination matches source of any fetch ref spec + * for this transport remote configuration. * * @param db * local database. @@ -617,8 +622,9 @@ public abstract class Transport implements AutoCloseable { * @param fetchSpecs * fetch specifications used for finding localtracking refs. May * be null or empty collection. - * @return collection of set up {@link RemoteRefUpdate}. - * @throws IOException + * @return collection of set up + * {@link org.eclipse.jgit.transport.RemoteRefUpdate}. + * @throws java.io.IOException * when problem occurred during conversion or specification set * up: most probably, missing objects or refs. * @since 4.7 @@ -668,12 +674,13 @@ public abstract class Transport implements AutoCloseable { } /** - * Convert push remote refs update specification from {@link RefSpec} form - * to {@link RemoteRefUpdate}. Conversion expands wildcards by matching - * source part to local refs. expectedOldObjectId in RemoteRefUpdate is - * always set as null. Tracking branch is configured if RefSpec destination - * matches source of any fetch ref spec for this transport remote - * configuration. + * Convert push remote refs update specification from + * {@link org.eclipse.jgit.transport.RefSpec} form to + * {@link org.eclipse.jgit.transport.RemoteRefUpdate}. Conversion expands + * wildcards by matching source part to local refs. expectedOldObjectId in + * RemoteRefUpdate is always set as null. Tracking branch is configured if + * RefSpec destination matches source of any fetch ref spec for this + * transport remote configuration. * * @param db * local database. @@ -682,8 +689,9 @@ public abstract class Transport implements AutoCloseable { * @param fetchSpecs * fetch specifications used for finding localtracking refs. May * be null or empty collection. - * @return collection of set up {@link RemoteRefUpdate}. - * @throws IOException + * @return collection of set up + * {@link org.eclipse.jgit.transport.RemoteRefUpdate}. + * @throws java.io.IOException * when problem occurred during conversion or specification set * up: most probably, missing objects or refs. */ @@ -838,6 +846,7 @@ public abstract class Transport implements AutoCloseable { * Create a minimal transport instance not tied to a single repository. * * @param uri + * a {@link org.eclipse.jgit.transport.URIish} object. */ protected Transport(final URIish uri) { this.uri = uri; @@ -923,6 +932,8 @@ public abstract class Transport implements AutoCloseable { } /** + * Whether fetch will verify if received objects are formatted correctly. + * * @return true if fetch will verify received objects are formatted * correctly. Validating objects requires more CPU time on the * client side of the connection. @@ -932,6 +943,8 @@ public abstract class Transport implements AutoCloseable { } /** + * Configure if checking received objects is enabled + * * @param check * true to enable checking received objects; false to assume all * received objects are valid. @@ -945,6 +958,8 @@ public abstract class Transport implements AutoCloseable { } /** + * Get configured object checker for received objects + * * @return configured object checker for received objects, or null. * @since 3.6 */ @@ -953,6 +968,8 @@ public abstract class Transport implements AutoCloseable { } /** + * Set the object checker to verify each received object with + * * @param impl * if non-null the object checking instance to verify each * received object with; null to disable object checking. @@ -963,7 +980,8 @@ public abstract class Transport implements AutoCloseable { } /** - * Default setting is: {@link RemoteConfig#DEFAULT_RECEIVE_PACK} + * Default setting is: + * {@link org.eclipse.jgit.transport.RemoteConfig#DEFAULT_RECEIVE_PACK} * * @return remote executable providing receive-pack service for pack * transports. @@ -975,7 +993,8 @@ public abstract class Transport implements AutoCloseable { /** * Set remote executable providing receive-pack service for pack transports. - * Default setting is: {@link RemoteConfig#DEFAULT_RECEIVE_PACK} + * Default setting is: + * {@link org.eclipse.jgit.transport.RemoteConfig#DEFAULT_RECEIVE_PACK} * * @param optionReceivePack * remote executable, if null or empty default one is set; @@ -1036,6 +1055,9 @@ public abstract class Transport implements AutoCloseable { } /** + * Whether destination refs should be removed if they no longer exist at the + * source repository. + * * @return true if destination refs should be removed if they no longer * exist at the source repository. */ @@ -1075,6 +1097,9 @@ public abstract class Transport implements AutoCloseable { } /** + * Whether push operation should just check for possible result and not + * really update remote refs + * * @return true if push operation should just check for possible result and * not really update remote refs, false otherwise - when push should * act normally. @@ -1095,7 +1120,11 @@ public abstract class Transport implements AutoCloseable { this.dryRun = dryRun; } - /** @return timeout (in seconds) before aborting an IO operation. */ + /** + * Get timeout (in seconds) before aborting an IO operation. + * + * @return timeout (in seconds) before aborting an IO operation. + */ public int getTimeout() { return timeout; } @@ -1159,6 +1188,8 @@ public abstract class Transport implements AutoCloseable { } /** + * Get the option strings associated with the push operation + * * @return the option strings associated with the push operation * @since 4.5 */ @@ -1182,22 +1213,24 @@ public abstract class Transport implements AutoCloseable { * <p> * This is a utility function providing standard fetch behavior. Local * tracking refs associated with the remote repository are automatically - * updated if this transport was created from a {@link RemoteConfig} with - * fetch RefSpecs defined. + * updated if this transport was created from a + * {@link org.eclipse.jgit.transport.RemoteConfig} with fetch RefSpecs + * defined. * * @param monitor * progress monitor to inform the user about our processing - * activity. Must not be null. Use {@link NullProgressMonitor} if - * progress updates are not interesting or necessary. + * activity. Must not be null. Use + * {@link org.eclipse.jgit.lib.NullProgressMonitor} if progress + * updates are not interesting or necessary. * @param toFetch * specification of refs to fetch locally. May be null or the * empty collection to use the specifications from the * RemoteConfig. Source for each RefSpec can't be null. * @return information describing the tracking refs updated. - * @throws NotSupportedException + * @throws org.eclipse.jgit.errors.NotSupportedException * this transport implementation does not support fetching * objects. - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * the remote connection could not be established or object * copying (if necessary) failed or update specification was * incorrect. @@ -1252,17 +1285,18 @@ public abstract class Transport implements AutoCloseable { * For setting up remote ref update specification from ref spec, see helper * method {@link #findRemoteRefUpdatesFor(Collection)}, predefined refspecs * ({@link #REFSPEC_TAGS}, {@link #REFSPEC_PUSH_ALL}) or consider using - * directly {@link RemoteRefUpdate} for more possibilities. + * directly {@link org.eclipse.jgit.transport.RemoteRefUpdate} for more + * possibilities. * <p> * When {@link #isDryRun()} is true, result of this operation is just * estimation of real operation result, no real action is performed. * * @see RemoteRefUpdate - * * @param monitor * progress monitor to inform the user about our processing - * activity. Must not be null. Use {@link NullProgressMonitor} if - * progress updates are not interesting or necessary. + * activity. Must not be null. Use + * {@link org.eclipse.jgit.lib.NullProgressMonitor} if progress + * updates are not interesting or necessary. * @param toPush * specification of refs to push. May be null or the empty * collection to use the specifications from the RemoteConfig @@ -1273,10 +1307,10 @@ public abstract class Transport implements AutoCloseable { * output stream to write messages to * @return information about results of remote refs updates, tracking refs * updates and refs advertised by remote repository. - * @throws NotSupportedException + * @throws org.eclipse.jgit.errors.NotSupportedException * this transport implementation does not support pushing * objects. - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * the remote connection could not be established or object * copying (if necessary) failed at I/O or protocol level or * update specification was incorrect. @@ -1322,30 +1356,30 @@ public abstract class Transport implements AutoCloseable { * For setting up remote ref update specification from ref spec, see helper * method {@link #findRemoteRefUpdatesFor(Collection)}, predefined refspecs * ({@link #REFSPEC_TAGS}, {@link #REFSPEC_PUSH_ALL}) or consider using - * directly {@link RemoteRefUpdate} for more possibilities. + * directly {@link org.eclipse.jgit.transport.RemoteRefUpdate} for more + * possibilities. * <p> * When {@link #isDryRun()} is true, result of this operation is just * estimation of real operation result, no real action is performed. * * @see RemoteRefUpdate - * * @param monitor * progress monitor to inform the user about our processing - * activity. Must not be null. Use {@link NullProgressMonitor} if - * progress updates are not interesting or necessary. + * activity. Must not be null. Use + * {@link org.eclipse.jgit.lib.NullProgressMonitor} if progress + * updates are not interesting or necessary. * @param toPush * specification of refs to push. May be null or the empty * collection to use the specifications from the RemoteConfig * converted by {@link #findRemoteRefUpdatesFor(Collection)}. No * more than 1 RemoteRefUpdate with the same remoteName is * allowed. These objects are modified during this call. - * * @return information about results of remote refs updates, tracking refs * updates and refs advertised by remote repository. - * @throws NotSupportedException + * @throws org.eclipse.jgit.errors.NotSupportedException * this transport implementation does not support pushing * objects. - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * the remote connection could not be established or object * copying (if necessary) failed at I/O or protocol level or * update specification was incorrect. @@ -1357,20 +1391,22 @@ public abstract class Transport implements AutoCloseable { } /** - * Convert push remote refs update specification from {@link RefSpec} form - * to {@link RemoteRefUpdate}. Conversion expands wildcards by matching - * source part to local refs. expectedOldObjectId in RemoteRefUpdate is - * always set as null. Tracking branch is configured if RefSpec destination - * matches source of any fetch ref spec for this transport remote - * configuration. + * Convert push remote refs update specification from + * {@link org.eclipse.jgit.transport.RefSpec} form to + * {@link org.eclipse.jgit.transport.RemoteRefUpdate}. Conversion expands + * wildcards by matching source part to local refs. expectedOldObjectId in + * RemoteRefUpdate is always set as null. Tracking branch is configured if + * RefSpec destination matches source of any fetch ref spec for this + * transport remote configuration. * <p> * Conversion is performed for context of this transport (database, fetch * specifications). * * @param specs * collection of RefSpec to convert. - * @return collection of set up {@link RemoteRefUpdate}. - * @throws IOException + * @return collection of set up + * {@link org.eclipse.jgit.transport.RemoteRefUpdate}. + * @throws java.io.IOException * when problem occurred during conversion or specification set * up: most probably, missing objects or refs. */ @@ -1381,12 +1417,13 @@ public abstract class Transport implements AutoCloseable { } /** - * Convert push remote refs update specification from {@link RefSpec} form - * to {@link RemoteRefUpdate}. Conversion expands wildcards by matching - * source part to local refs. expectedOldObjectId in RemoteRefUpdate is - * set according to leases. Tracking branch is configured if RefSpec destination - * matches source of any fetch ref spec for this transport remote - * configuration. + * Convert push remote refs update specification from + * {@link org.eclipse.jgit.transport.RefSpec} form to + * {@link org.eclipse.jgit.transport.RemoteRefUpdate}. Conversion expands + * wildcards by matching source part to local refs. expectedOldObjectId in + * RemoteRefUpdate is set according to leases. Tracking branch is configured + * if RefSpec destination matches source of any fetch ref spec for this + * transport remote configuration. * <p> * Conversion is performed for context of this transport (database, fetch * specifications). @@ -1395,8 +1432,9 @@ public abstract class Transport implements AutoCloseable { * collection of RefSpec to convert. * @param leases * map from ref to lease (containing expected old object id) - * @return collection of set up {@link RemoteRefUpdate}. - * @throws IOException + * @return collection of set up + * {@link org.eclipse.jgit.transport.RemoteRefUpdate}. + * @throws java.io.IOException * when problem occurred during conversion or specification set * up: most probably, missing objects or refs. * @since 4.7 @@ -1415,9 +1453,9 @@ public abstract class Transport implements AutoCloseable { * be used for reading remote refs. * * @return a fresh connection to fetch from the remote repository. - * @throws NotSupportedException + * @throws org.eclipse.jgit.errors.NotSupportedException * the implementation does not support fetching. - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * the remote connection could not be established. */ public abstract FetchConnection openFetch() throws NotSupportedException, @@ -1427,15 +1465,17 @@ public abstract class Transport implements AutoCloseable { * Begins a new connection for pushing into the remote repository. * * @return a fresh connection to push into the remote repository. - * @throws NotSupportedException + * @throws org.eclipse.jgit.errors.NotSupportedException * the implementation does not support pushing. - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * the remote connection could not be established */ public abstract PushConnection openPush() throws NotSupportedException, TransportException; /** + * {@inheritDoc} + * <p> * Close any resources used by this transport. * <p> * If the remote repository is contacted by a network socket this method diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportAmazonS3.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportAmazonS3.java index 6cd119bd2f..c6191eceb0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportAmazonS3.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportAmazonS3.java @@ -86,8 +86,9 @@ import org.eclipse.jgit.lib.SymbolicRef; * extended HTTP/1.1 semantics. This make it possible to read or write Git data * from a remote repository that is stored on S3. * <p> - * Unlike the HTTP variant (see {@link TransportHttp}) we rely upon being able - * to list objects in a bucket, as the S3 API supports this function. By listing + * Unlike the HTTP variant (see + * {@link org.eclipse.jgit.transport.TransportHttp}) we rely upon being able to + * list objects in a bucket, as the S3 API supports this function. By listing * the bucket contents we can avoid relying on <code>objects/info/packs</code> * or <code>info/refs</code> in the remote repository. * <p> @@ -201,6 +202,7 @@ public class TransportAmazonS3 extends HttpTransport implements WalkTransport { } } + /** {@inheritDoc} */ @Override public FetchConnection openFetch() throws TransportException { final DatabaseS3 c = new DatabaseS3(bucket, keyPrefix + "/objects"); //$NON-NLS-1$ @@ -209,6 +211,7 @@ public class TransportAmazonS3 extends HttpTransport implements WalkTransport { return r; } + /** {@inheritDoc} */ @Override public PushConnection openPush() throws TransportException { final DatabaseS3 c = new DatabaseS3(bucket, keyPrefix + "/objects"); //$NON-NLS-1$ @@ -217,6 +220,7 @@ public class TransportAmazonS3 extends HttpTransport implements WalkTransport { return r; } + /** {@inheritDoc} */ @Override public void close() { // No explicit connections are maintained. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportBundleFile.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportBundleFile.java index f2ddc0d0d1..58f021c0ae 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportBundleFile.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportBundleFile.java @@ -125,11 +125,20 @@ class TransportBundleFile extends Transport implements TransportBundle { bundle = bundlePath; } + /** + * Constructor for TransportBundleFile. + * + * @param uri + * a {@link org.eclipse.jgit.transport.URIish} object. + * @param bundlePath + * transport bundle path + */ public TransportBundleFile(URIish uri, File bundlePath) { super(uri); bundle = bundlePath; } + /** {@inheritDoc} */ @Override public FetchConnection openFetch() throws NotSupportedException, TransportException { @@ -142,12 +151,14 @@ class TransportBundleFile extends Transport implements TransportBundle { return new BundleFetchConnection(this, src); } + /** {@inheritDoc} */ @Override public PushConnection openPush() throws NotSupportedException { throw new NotSupportedException( JGitText.get().pushIsNotSupportedForBundleTransport); } + /** {@inheritDoc} */ @Override public void close() { // Resources must be established per-connection. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportBundleStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportBundleStream.java index a9d881f9b9..573367ec06 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportBundleStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportBundleStream.java @@ -90,6 +90,7 @@ public class TransportBundleStream extends Transport implements TransportBundle src = in; } + /** {@inheritDoc} */ @Override public FetchConnection openFetch() throws TransportException { if (src == null) @@ -101,12 +102,14 @@ public class TransportBundleStream extends Transport implements TransportBundle } } + /** {@inheritDoc} */ @Override public PushConnection openPush() throws NotSupportedException { throw new NotSupportedException( JGitText.get().pushIsNotSupportedForBundleTransport); } + /** {@inheritDoc} */ @Override public void close() { if (src != null) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportGitAnon.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportGitAnon.java index 7bf5b947d8..816187ee0c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportGitAnon.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportGitAnon.java @@ -121,16 +121,19 @@ class TransportGitAnon extends TcpTransport implements PackTransport { super(uri); } + /** {@inheritDoc} */ @Override public FetchConnection openFetch() throws TransportException { return new TcpFetchConnection(); } + /** {@inheritDoc} */ @Override public PushConnection openPush() throws TransportException { return new TcpPushConnection(); } + /** {@inheritDoc} */ @Override public void close() { // Resources must be established per-connection. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportGitSsh.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportGitSsh.java index b1b910ea22..bc85e6f60f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportGitSsh.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportGitSsh.java @@ -164,11 +164,13 @@ public class TransportGitSsh extends SshTransport implements PackTransport { } } + /** {@inheritDoc} */ @Override public FetchConnection openFetch() throws TransportException { return new SshFetchConnection(); } + /** {@inheritDoc} */ @Override public PushConnection openPush() throws TransportException { return new SshPushConnection(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportHttp.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportHttp.java index 7c3f738d9c..db43edc4ca 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportHttp.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportHttp.java @@ -291,8 +291,11 @@ public class TransportHttp extends HttpTransport implements WalkTransport, } /** + * Set uri a {@link org.eclipse.jgit.transport.URIish} object. + * * @param uri - * @throws NotSupportedException + * a {@link org.eclipse.jgit.transport.URIish} object. + * @throws org.eclipse.jgit.errors.NotSupportedException * @since 4.9 */ protected void setURI(final URIish uri) throws NotSupportedException { @@ -333,6 +336,7 @@ public class TransportHttp extends HttpTransport implements WalkTransport, useSmartHttp = on; } + /** {@inheritDoc} */ @Override public FetchConnection openFetch() throws TransportException, NotSupportedException { @@ -427,6 +431,7 @@ public class TransportHttp extends HttpTransport implements WalkTransport, return new BufferedReader(new InputStreamReader(in, Constants.CHARSET)); } + /** {@inheritDoc} */ @Override public PushConnection openPush() throws NotSupportedException, TransportException { @@ -465,6 +470,7 @@ public class TransportHttp extends HttpTransport implements WalkTransport, return p; } + /** {@inheritDoc} */ @Override public void close() { // No explicit connections are maintained. @@ -803,7 +809,7 @@ public class TransportHttp extends HttpTransport implements WalkTransport, * @param method HTTP request method * @param u url of the HTTP connection * @return the HTTP connection - * @throws IOException + * @throws java.io.IOException * @since 3.3 * @deprecated use {@link #httpOpen(String, URL, AcceptEncoding)} instead. */ @@ -819,7 +825,7 @@ public class TransportHttp extends HttpTransport implements WalkTransport, * @param u url of the HTTP connection * @param acceptEncoding accept-encoding header option * @return the HTTP connection - * @throws IOException + * @throws java.io.IOException * @since 4.6 */ protected HttpConnection httpOpen(String method, URL u, @@ -1257,13 +1263,7 @@ public class TransportHttp extends HttpTransport implements WalkTransport, } authAttempts = 1; // We only do the Kerberos part of SPNEGO, which - // requires only one attempt. We do *not* to the - // NTLM part of SPNEGO; it's a multi-round - // negotiation and among other problems it would - // be unclear when to stop if no HTTP_OK is - // forthcoming. In theory a malicious server - // could keep sending requests for another NTLM - // round, keeping a client stuck here. + // requires only one round. break; default: // DIGEST or BASIC. Let's be sure we ignore @@ -1305,6 +1305,27 @@ public class TransportHttp extends HttpTransport implements WalkTransport, } catch (SSLHandshakeException e) { handleSslFailure(e); continue; // Re-try + } catch (IOException e) { + if (authenticator == null || authMethod + .getType() != HttpAuthMethod.Type.NONE) { + // Can happen for instance if the server advertises + // Negotiate, but the client isn't configured for + // Kerberos. The first time (authenticator == null) we + // must re-try even if the authMethod was NONE: this may + // occur if the server advertised NTLM on the GET + // and the HttpConnection managed to successfully + // authenticate under the hood with NTLM. We might not + // have picked this up on the GET's 200 response. + if (authMethod.getType() != HttpAuthMethod.Type.NONE) { + ignoreTypes.add(authMethod.getType()); + } + // Start over with the remaining available methods. + authMethod = HttpAuthMethod.Type.NONE.method(null); + authenticator = authMethod; + authAttempts = 1; + continue; + } + throw e; } } } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportLocal.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportLocal.java index f483ec7f9f..20eb898fbe 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportLocal.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportLocal.java @@ -178,6 +178,7 @@ class TransportLocal extends Transport implements PackTransport { } } + /** {@inheritDoc} */ @Override public FetchConnection openFetch() throws TransportException { final String up = getOptionUploadPack(); @@ -194,6 +195,7 @@ class TransportLocal extends Transport implements PackTransport { return new InternalFetchConnection<>(this, upf, null, openRepo()); } + /** {@inheritDoc} */ @Override public PushConnection openPush() throws TransportException { final String rp = getOptionReceivePack(); @@ -210,11 +212,21 @@ class TransportLocal extends Transport implements PackTransport { return new InternalPushConnection<>(this, rpf, null, openRepo()); } + /** {@inheritDoc} */ @Override public void close() { // Resources must be established per-connection. } + /** + * Spawn process + * + * @param cmd + * command + * @return a {@link java.lang.Process} object. + * @throws org.eclipse.jgit.errors.TransportException + * if any. + */ protected Process spawn(final String cmd) throws TransportException { try { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportProtocol.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportProtocol.java index e08efc4eaf..de58aa9e1b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportProtocol.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportProtocol.java @@ -72,11 +72,12 @@ import org.eclipse.jgit.lib.Repository; * * <p> * Applications may register additional protocols for use by JGit by calling - * {@link Transport#register(TransportProtocol)}. Because that API holds onto - * the protocol object by a WeakReference, applications must ensure their own - * ClassLoader retains the TransportProtocol for the life of the application. - * Using a static singleton pattern as above will ensure the protocol is valid - * so long as the ClassLoader that defines it remains valid. + * {@link org.eclipse.jgit.transport.Transport#register(TransportProtocol)}. + * Because that API holds onto the protocol object by a WeakReference, + * applications must ensure their own ClassLoader retains the TransportProtocol + * for the life of the application. Using a static singleton pattern as above + * will ensure the protocol is valid so long as the ClassLoader that defines it + * remains valid. * <p> * Applications may automatically register additional protocols by filling in * the names of their TransportProtocol defining classes using the services file @@ -102,25 +103,45 @@ public abstract class TransportProtocol { PATH, } - /** @return text name of the protocol suitable for display to a user. */ + /** + * Get text name of the protocol suitable for display to a user. + * + * @return text name of the protocol suitable for display to a user. + */ public abstract String getName(); - /** @return immutable set of schemes supported by this protocol. */ + /** + * Get immutable set of schemes supported by this protocol. + * + * @return immutable set of schemes supported by this protocol. + */ public Set<String> getSchemes() { return Collections.emptySet(); } - /** @return immutable set of URIishFields that must be filled in. */ + /** + * Get immutable set of URIishFields that must be filled in. + * + * @return immutable set of URIishFields that must be filled in. + */ public Set<URIishField> getRequiredFields() { return Collections.unmodifiableSet(EnumSet.of(URIishField.PATH)); } - /** @return immutable set of URIishFields that may be filled in. */ + /** + * Get immutable set of URIishFields that may be filled in. + * + * @return immutable set of URIishFields that may be filled in. + */ public Set<URIishField> getOptionalFields() { return Collections.emptySet(); } - /** @return if a port is supported, the default port, else -1. */ + /** + * Get the default port if the protocol supports a port, else -1. + * + * @return the default port if the protocol supports a port, else -1. + */ public int getDefaultPort() { return -1; } @@ -246,9 +267,9 @@ public abstract class TransportProtocol { * name of the remote, if the remote as configured in * {@code local}; otherwise null. * @return the transport. - * @throws NotSupportedException + * @throws org.eclipse.jgit.errors.NotSupportedException * this protocol does not support the URI. - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * the transport cannot open this URI. */ public abstract Transport open(URIish uri, Repository local, @@ -260,9 +281,10 @@ public abstract class TransportProtocol { * configuration instead of reading from configuration files. * * @param uri + * a {@link org.eclipse.jgit.transport.URIish} object. * @return new Transport - * @throws NotSupportedException - * @throws TransportException + * @throws org.eclipse.jgit.errors.NotSupportedException + * @throws org.eclipse.jgit.errors.TransportException */ public Transport open(URIish uri) throws NotSupportedException, TransportException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportSftp.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportSftp.java index 99e4809cf6..e2d08b64c7 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportSftp.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/TransportSftp.java @@ -88,11 +88,12 @@ import com.jcraft.jsch.SftpException; * repository that is available over SSH, but whose remote host does not have * Git installed. * <p> - * Unlike the HTTP variant (see {@link TransportHttp}) we rely upon being able - * to list files in directories, as the SFTP protocol supports this function. By + * Unlike the HTTP variant (see + * {@link org.eclipse.jgit.transport.TransportHttp}) we rely upon being able to + * list files in directories, as the SFTP protocol supports this function. By * listing files through SFTP we can avoid needing to have current - * <code>objects/info/packs</code> or <code>info/refs</code> files on the - * remote repository and access the data directly, much as Git itself would. + * <code>objects/info/packs</code> or <code>info/refs</code> files on the remote + * repository and access the data directly, much as Git itself would. * <p> * Concurrent pushing over this transport is not supported. Multiple concurrent * push operations may cause confusion in the repository state. @@ -139,6 +140,7 @@ public class TransportSftp extends SshTransport implements WalkTransport { super(local, uri); } + /** {@inheritDoc} */ @Override public FetchConnection openFetch() throws TransportException { final SftpObjectDB c = new SftpObjectDB(uri.getPath()); @@ -147,6 +149,7 @@ public class TransportSftp extends SshTransport implements WalkTransport { return r; } + /** {@inheritDoc} */ @Override public PushConnection openPush() throws TransportException { final SftpObjectDB c = new SftpObjectDB(uri.getPath()); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/URIish.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/URIish.java index ffd4d41f2a..a048fe30f2 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/URIish.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/URIish.java @@ -95,7 +95,7 @@ public class URIish implements Serializable { * Part of a pattern which matches the optional port part of URIs. Defines * one capturing group containing the port without the preceding colon. */ - private static final String OPT_PORT_P = "(?::(\\d+))?"; //$NON-NLS-1$ + private static final String OPT_PORT_P = "(?::(\\d*))?"; //$NON-NLS-1$ /** * Part of a pattern which matches the ~username part (e.g. /~root in @@ -200,10 +200,12 @@ public class URIish implements Serializable { private String host; /** - * Parse and construct an {@link URIish} from a string + * Parse and construct an {@link org.eclipse.jgit.transport.URIish} from a + * string * * @param s - * @throws URISyntaxException + * a {@link java.lang.String} object. + * @throws java.net.URISyntaxException */ public URIish(String s) throws URISyntaxException { if (StringUtils.isEmptyOrNull(s)) { @@ -222,11 +224,23 @@ public class URIish implements Serializable { scheme = matcher.group(1); user = unescape(matcher.group(2)); pass = unescape(matcher.group(3)); - host = unescape(matcher.group(4)); - if (matcher.group(5) != null) - port = Integer.parseInt(matcher.group(5)); - rawPath = cleanLeadingSlashes( - n2e(matcher.group(6)) + n2e(matcher.group(7)), scheme); + // empty ports are in general allowed, except for URLs like + // file://D:/path for which it is more desirable to parse with + // host=null and path=D:/path + String portString = matcher.group(5); + if ("file".equals(scheme) && "".equals(portString)) { //$NON-NLS-1$ //$NON-NLS-2$ + rawPath = cleanLeadingSlashes( + n2e(matcher.group(4)) + ":" + portString //$NON-NLS-1$ + + n2e(matcher.group(6)) + n2e(matcher.group(7)), + scheme); + } else { + host = unescape(matcher.group(4)); + if (portString != null && portString.length() > 0) { + port = Integer.parseInt(portString); + } + rawPath = cleanLeadingSlashes( + n2e(matcher.group(6)) + n2e(matcher.group(7)), scheme); + } path = unescape(rawPath); return; } @@ -395,7 +409,9 @@ public class URIish implements Serializable { host = u.getHost(); } - /** Create an empty, non-configured URI. */ + /** + * Create an empty, non-configured URI. + */ public URIish() { // Configure nothing. } @@ -411,6 +427,8 @@ public class URIish implements Serializable { } /** + * Whether this URI references a repository on another system. + * * @return true if this URI references a repository on another system. */ public boolean isRemote() { @@ -418,6 +436,8 @@ public class URIish implements Serializable { } /** + * Get host name part. + * * @return host name part or null */ public String getHost() { @@ -438,6 +458,8 @@ public class URIish implements Serializable { } /** + * Get protocol name + * * @return protocol name or null for local references */ public String getScheme() { @@ -458,6 +480,8 @@ public class URIish implements Serializable { } /** + * Get path name component + * * @return path name component */ public String getPath() { @@ -465,6 +489,8 @@ public class URIish implements Serializable { } /** + * Get path name component + * * @return path name component */ public String getRawPath() { @@ -491,7 +517,7 @@ public class URIish implements Serializable { * @param n * the new value for path. * @return a new URI with the updated value. - * @throws URISyntaxException + * @throws java.net.URISyntaxException */ public URIish setRawPath(final String n) throws URISyntaxException { final URIish r = new URIish(this); @@ -501,6 +527,8 @@ public class URIish implements Serializable { } /** + * Get user name requested for transfer + * * @return user name requested for transfer or null */ public String getUser() { @@ -521,6 +549,8 @@ public class URIish implements Serializable { } /** + * Get password requested for transfer + * * @return password requested for transfer or null */ public String getPass() { @@ -541,6 +571,8 @@ public class URIish implements Serializable { } /** + * Get port number requested for transfer or -1 if not explicit + * * @return port number requested for transfer or -1 if not explicit */ public int getPort() { @@ -560,6 +592,7 @@ public class URIish implements Serializable { return r; } + /** {@inheritDoc} */ @Override public int hashCode() { int hc = 0; @@ -578,6 +611,7 @@ public class URIish implements Serializable { return hc; } + /** {@inheritDoc} */ @Override public boolean equals(final Object obj) { if (!(obj instanceof URIish)) @@ -617,6 +651,7 @@ public class URIish implements Serializable { return format(true, false); } + /** {@inheritDoc} */ @Override public String toString() { return format(false, false); @@ -666,6 +701,8 @@ public class URIish implements Serializable { } /** + * Get the URI as an ASCII string. + * * @return the URI as an ASCII string. Password is not included. */ public String toASCIIString() { @@ -673,6 +710,9 @@ public class URIish implements Serializable { } /** + * Convert the URI including password, formatted with only ASCII characters + * such that it will be valid for use over the network. + * * @return the URI including password, formatted with only ASCII characters * such that it will be valid for use over the network. */ @@ -713,7 +753,7 @@ public class URIish implements Serializable { * * @return the "humanish" part of the path. May be an empty string. Never * {@code null}. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * if it's impossible to determine a humanish part, or path is * {@code null} or empty * @see #getPath diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/UploadPack.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/UploadPack.java index cf070c6348..822d47c7c2 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/UploadPack.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/UploadPack.java @@ -77,14 +77,18 @@ import org.eclipse.jgit.errors.MissingObjectException; import org.eclipse.jgit.errors.PackProtocolException; import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.internal.storage.pack.PackWriter; +import org.eclipse.jgit.lib.BitmapIndex; +import org.eclipse.jgit.lib.BitmapIndex.BitmapBuilder; import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.lib.NullProgressMonitor; import org.eclipse.jgit.lib.ObjectId; +import org.eclipse.jgit.lib.ObjectReader; import org.eclipse.jgit.lib.ProgressMonitor; import org.eclipse.jgit.lib.Ref; import org.eclipse.jgit.lib.RefDatabase; import org.eclipse.jgit.lib.Repository; import org.eclipse.jgit.revwalk.AsyncRevObjectQueue; +import org.eclipse.jgit.revwalk.BitmapWalker; import org.eclipse.jgit.revwalk.DepthWalk; import org.eclipse.jgit.revwalk.ObjectWalk; import org.eclipse.jgit.revwalk.RevCommit; @@ -342,12 +346,20 @@ public class UploadPack { setTransferConfig(null); } - /** @return the repository this upload is reading from. */ + /** + * Get the repository this upload is reading from. + * + * @return the repository this upload is reading from. + */ public final Repository getRepository() { return db; } - /** @return the RevWalk instance used by this connection. */ + /** + * Get the RevWalk instance used by this connection. + * + * @return the RevWalk instance used by this connection. + */ public final RevWalk getRevWalk() { return walk; } @@ -365,14 +377,15 @@ public class UploadPack { /** * Set the refs advertised by this UploadPack. * <p> - * Intended to be called from a {@link PreUploadHook}. + * Intended to be called from a + * {@link org.eclipse.jgit.transport.PreUploadHook}. * * @param allRefs * explicit set of references to claim as advertised by this - * UploadPack instance. This overrides any references that - * may exist in the source repository. The map is passed - * to the configured {@link #getRefFilter()}. If null, assumes - * all refs were advertised. + * UploadPack instance. This overrides any references that may + * exist in the source repository. The map is passed to the + * configured {@link #getRefFilter()}. If null, assumes all refs + * were advertised. */ public void setAdvertisedRefs(Map<String, Ref> allRefs) { if (allRefs != null) @@ -385,7 +398,11 @@ public class UploadPack { refs = refFilter.filter(refs); } - /** @return timeout (in seconds) before aborting an IO operation. */ + /** + * Get timeout (in seconds) before aborting an IO operation. + * + * @return timeout (in seconds) before aborting an IO operation. + */ public int getTimeout() { return timeout; } @@ -403,6 +420,9 @@ public class UploadPack { } /** + * Whether this class expects a bi-directional pipe opened between the + * client and itself. + * * @return true if this class expects a bi-directional pipe opened between * the client and itself. The default is true. */ @@ -411,6 +431,9 @@ public class UploadPack { } /** + * Set whether this class will assume the socket is a fully bidirectional + * pipe between the two peers + * * @param twoWay * if true, this class will assume the socket is a fully * bidirectional pipe between the two peers and takes advantage @@ -424,8 +447,10 @@ public class UploadPack { } /** - * @return policy used by the service to validate client requests, or null for - * a custom request validator. + * Get policy used by the service to validate client requests + * + * @return policy used by the service to validate client requests, or null + * for a custom request validator. */ public RequestPolicy getRequestPolicy() { if (requestValidator instanceof AdvertisedRequestValidator) @@ -442,15 +467,21 @@ public class UploadPack { } /** + * Set the policy used to enforce validation of a client's want list. + * * @param policy * the policy used to enforce validation of a client's want list. - * By default the policy is {@link RequestPolicy#ADVERTISED}, + * By default the policy is + * {@link org.eclipse.jgit.transport.UploadPack.RequestPolicy#ADVERTISED}, * which is the Git default requiring clients to only ask for an - * object that a reference directly points to. This may be relaxed - * to {@link RequestPolicy#REACHABLE_COMMIT} or - * {@link RequestPolicy#REACHABLE_COMMIT_TIP} when callers have - * {@link #setBiDirectionalPipe(boolean)} set to false. - * Overrides any policy specified in a {@link TransferConfig}. + * object that a reference directly points to. This may be + * relaxed to + * {@link org.eclipse.jgit.transport.UploadPack.RequestPolicy#REACHABLE_COMMIT} + * or + * {@link org.eclipse.jgit.transport.UploadPack.RequestPolicy#REACHABLE_COMMIT_TIP} + * when callers have {@link #setBiDirectionalPipe(boolean)} set + * to false. Overrides any policy specified in a + * {@link org.eclipse.jgit.transport.TransferConfig}. */ public void setRequestPolicy(RequestPolicy policy) { switch (policy) { @@ -474,6 +505,8 @@ public class UploadPack { } /** + * Set custom validator for client want list. + * * @param validator * custom validator for client want list. * @since 3.1 @@ -483,12 +516,20 @@ public class UploadPack { : new AdvertisedRequestValidator(); } - /** @return the hook used while advertising the refs to the client */ + /** + * Get the hook used while advertising the refs to the client. + * + * @return the hook used while advertising the refs to the client. + */ public AdvertiseRefsHook getAdvertiseRefsHook() { return advertiseRefsHook; } - /** @return the filter used while advertising the refs to the client */ + /** + * Get the filter used while advertising the refs to the client. + * + * @return the filter used while advertising the refs to the client. + */ public RefFilter getRefFilter() { return refFilter; } @@ -496,9 +537,10 @@ public class UploadPack { /** * Set the hook used while advertising the refs to the client. * <p> - * If the {@link AdvertiseRefsHook} chooses to call - * {@link #setAdvertisedRefs(Map)}, only refs set by this hook <em>and</em> - * selected by the {@link RefFilter} will be shown to the client. + * If the {@link org.eclipse.jgit.transport.AdvertiseRefsHook} chooses to + * call {@link #setAdvertisedRefs(Map)}, only refs set by this hook + * <em>and</em> selected by the {@link org.eclipse.jgit.transport.RefFilter} + * will be shown to the client. * * @param advertiseRefsHook * the hook; may be null to show all refs. @@ -513,10 +555,11 @@ public class UploadPack { /** * Set the filter used while advertising the refs to the client. * <p> - * Only refs allowed by this filter will be sent to the client. - * The filter is run against the refs specified by the - * {@link AdvertiseRefsHook} (if applicable). If null or not set, uses the - * filter implied by the {@link TransferConfig}. + * Only refs allowed by this filter will be sent to the client. The filter + * is run against the refs specified by the + * {@link org.eclipse.jgit.transport.AdvertiseRefsHook} (if applicable). If + * null or not set, uses the filter implied by the + * {@link org.eclipse.jgit.transport.TransferConfig}. * * @param refFilter * the filter; may be null to show all refs. @@ -525,7 +568,11 @@ public class UploadPack { this.refFilter = refFilter != null ? refFilter : RefFilter.DEFAULT; } - /** @return the configured pre upload hook. */ + /** + * Get the configured pre upload hook. + * + * @return the configured pre upload hook. + */ public PreUploadHook getPreUploadHook() { return preUploadHook; } @@ -541,6 +588,8 @@ public class UploadPack { } /** + * Get the configured post upload hook. + * * @return the configured post upload hook. * @since 4.1 */ @@ -571,6 +620,8 @@ public class UploadPack { } /** + * Set configuration controlling transfer options. + * * @param tc * configuration controlling transfer options. If null the source * repository's settings will be used. @@ -588,8 +639,9 @@ public class UploadPack { } /** - * @return the configured logger. + * Get the configured logger. * + * @return the configured logger. * @deprecated Use {@link #getPreUploadHook()}. */ @Deprecated @@ -614,7 +666,7 @@ public class UploadPack { * * @return true if the client has advertised a side-band capability, false * otherwise. - * @throws RequestNotYetReadException + * @throws org.eclipse.jgit.transport.RequestNotYetReadException * if the client's request has not yet been read from the wire, so * we do not know if they expect side-band. Note that the client * may have already written the request, it just has not been @@ -642,7 +694,7 @@ public class UploadPack { * through. When run over SSH this should be tied back to the * standard error channel of the command execution. For most * other network connections this should be null. - * @throws IOException + * @throws java.io.IOException */ public void upload(final InputStream input, OutputStream output, final OutputStream messages) throws IOException { @@ -885,9 +937,9 @@ public class UploadPack { * * @param adv * the advertisement formatter. - * @throws IOException + * @throws java.io.IOException * the formatter failed to write an advertisement. - * @throws ServiceMayNotContinueException + * @throws org.eclipse.jgit.transport.ServiceMayNotContinueException * the hook denied advertisement. */ public void sendAdvertisedRefs(final RefAdvertiser adv) throws IOException, @@ -953,6 +1005,8 @@ public class UploadPack { } /** + * Get an underlying stream for sending messages to the client + * * @return an underlying stream for sending messages to the client, or null. * @since 3.1 */ @@ -1315,6 +1369,18 @@ public class UploadPack { } } + private static void checkNotAdvertisedWantsUsingBitmap(ObjectReader reader, + BitmapIndex bitmapIndex, List<ObjectId> notAdvertisedWants, + Set<ObjectId> reachableFrom) throws IOException { + BitmapWalker bitmapWalker = new BitmapWalker(new ObjectWalk(reader), bitmapIndex, null); + BitmapBuilder reachables = bitmapWalker.findObjects(reachableFrom, null, false); + for (ObjectId oid : notAdvertisedWants) { + if (!reachables.contains(oid)) { + throw new WantNotValidException(oid); + } + } + } + private static void checkNotAdvertisedWants(UploadPack up, List<ObjectId> notAdvertisedWants, Set<ObjectId> reachableFrom) throws MissingObjectException, IncorrectObjectTypeException, IOException { @@ -1324,13 +1390,28 @@ public class UploadPack { // into an advertised branch it will be marked UNINTERESTING and no commits // return. - try (RevWalk walk = new RevWalk(up.getRevWalk().getObjectReader())) { + ObjectReader reader = up.getRevWalk().getObjectReader(); + try (RevWalk walk = new RevWalk(reader)) { AsyncRevObjectQueue q = walk.parseAny(notAdvertisedWants, true); try { RevObject obj; while ((obj = q.next()) != null) { - if (!(obj instanceof RevCommit)) + if (!(obj instanceof RevCommit)) { + // If unadvertized non-commits are requested, use + // bitmaps. If there are no bitmaps, instead of + // incurring the expense of a manual walk, reject + // the request. + BitmapIndex bitmapIndex = reader.getBitmapIndex(); + if (bitmapIndex != null) { + checkNotAdvertisedWantsUsingBitmap( + reader, + bitmapIndex, + notAdvertisedWants, + reachableFrom); + return; + } throw new WantNotValidException(obj); + } walk.markStart((RevCommit) obj); } } catch (MissingObjectException notFound) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/UploadPackInternalServerErrorException.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/UploadPackInternalServerErrorException.java index acdfe04f89..181352122c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/UploadPackInternalServerErrorException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/UploadPackInternalServerErrorException.java @@ -45,7 +45,9 @@ package org.eclipse.jgit.transport; import java.io.IOException; -/** UploadPack has already reported an error to the client.*/ +/** + * UploadPack has already reported an error to the client. + */ public class UploadPackInternalServerErrorException extends IOException { private static final long serialVersionUID = 1L; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/UploadPackLogger.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/UploadPackLogger.java index afc9965183..611418d22c 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/UploadPackLogger.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/UploadPackLogger.java @@ -46,14 +46,15 @@ package org.eclipse.jgit.transport; import org.eclipse.jgit.internal.storage.pack.PackWriter; /** - * Logs activity that occurred within {@link UploadPack}. + * Logs activity that occurred within + * {@link org.eclipse.jgit.transport.UploadPack}. * <p> * Implementors of the interface are responsible for associating the current * thread to a particular connection, if they need to also include connection * information. One method is to use a {@link java.lang.ThreadLocal} to remember * the connection information before invoking UploadPack. * - * @deprecated use {@link PostUploadHook} instead + * @deprecated use {@link org.eclipse.jgit.transport.PostUploadHook} instead */ @Deprecated public interface UploadPackLogger { // TODO remove in JGit 5.0 diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/UploadPackLoggerChain.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/UploadPackLoggerChain.java index 9a8c12c648..9e14672dc5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/UploadPackLoggerChain.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/UploadPackLoggerChain.java @@ -52,7 +52,8 @@ import org.eclipse.jgit.internal.storage.pack.PackWriter; * <p> * loggers are run in the order passed to the constructor. * - * @deprecated Use {@link PostUploadHookChain} instead. + * @deprecated Use {@link org.eclipse.jgit.transport.PostUploadHookChain} + * instead. */ @Deprecated public class UploadPackLoggerChain implements UploadPackLogger { @@ -81,9 +82,7 @@ public class UploadPackLoggerChain implements UploadPackLogger { return new UploadPackLoggerChain(newLoggers, i); } - /** - * @since 3.0 - */ + /** {@inheritDoc} */ @Override public void onPackStatistics(PackWriter.Statistics stats) { for (int i = 0; i < count; i++) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/UsernamePasswordCredentialsProvider.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/UsernamePasswordCredentialsProvider.java index 6caa5aa146..4445c3d561 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/UsernamePasswordCredentialsProvider.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/UsernamePasswordCredentialsProvider.java @@ -48,7 +48,8 @@ import java.util.Arrays; import org.eclipse.jgit.errors.UnsupportedCredentialItem; /** - * Simple {@link CredentialsProvider} that always uses the same information. + * Simple {@link org.eclipse.jgit.transport.CredentialsProvider} that always + * uses the same information. */ public class UsernamePasswordCredentialsProvider extends CredentialsProvider { private String username; @@ -59,7 +60,9 @@ public class UsernamePasswordCredentialsProvider extends CredentialsProvider { * Initialize the provider with a single username and password. * * @param username + * user name * @param password + * password */ public UsernamePasswordCredentialsProvider(String username, String password) { this(username, password.toCharArray()); @@ -69,18 +72,22 @@ public class UsernamePasswordCredentialsProvider extends CredentialsProvider { * Initialize the provider with a single username and password. * * @param username + * user name * @param password + * password */ public UsernamePasswordCredentialsProvider(String username, char[] password) { this.username = username; this.password = password; } + /** {@inheritDoc} */ @Override public boolean isInteractive() { return false; } + /** {@inheritDoc} */ @Override public boolean supports(CredentialItem... items) { for (CredentialItem i : items) { @@ -96,6 +103,7 @@ public class UsernamePasswordCredentialsProvider extends CredentialsProvider { return true; } + /** {@inheritDoc} */ @Override public boolean get(URIish uri, CredentialItem... items) throws UnsupportedCredentialItem { @@ -121,7 +129,9 @@ public class UsernamePasswordCredentialsProvider extends CredentialsProvider { return true; } - /** Destroy the saved username and password.. */ + /** + * Destroy the saved username and password.. + */ public void clear() { username = null; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/WalkEncryption.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/WalkEncryption.java index 333e09d463..615e46b982 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/WalkEncryption.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/WalkEncryption.java @@ -95,6 +95,20 @@ abstract class WalkEncryption { // consider permitting mixed ciphers to facilitate algorithm migration // i.e. user keeps the password, but changes the algorithm // then existing remote entries will still be readable + /** + * Validate + * + * @param u + * a {@link java.net.HttpURLConnection} object. + * @param prefix + * a {@link java.lang.String} object. + * @param version + * a {@link java.lang.String} object. + * @param name + * a {@link java.lang.String} object. + * @throws java.io.IOException + * if any. + */ protected void validateImpl(final HttpURLConnection u, final String prefix, final String version, final String name) throws IOException { String v; @@ -115,10 +129,9 @@ abstract class WalkEncryption { } IOException error(final Throwable why) { - final IOException e; - e = new IOException(MessageFormat.format(JGitText.get().encryptionError, why.getMessage())); - e.initCause(why); - return e; + return new IOException(MessageFormat + .format(JGitText.get().encryptionError, + why.getMessage()), why); } private static class NoEncryption extends WalkEncryption { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/WalkFetchConnection.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/WalkFetchConnection.java index 3d60aedcca..6708964d5e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/WalkFetchConnection.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/WalkFetchConnection.java @@ -223,11 +223,13 @@ class WalkFetchConnection extends BaseFetchConnection { workQueue = new LinkedList<>(); } + /** {@inheritDoc} */ @Override public boolean didFetchTestConnectivity() { return true; } + /** {@inheritDoc} */ @Override protected void doFetch(final ProgressMonitor monitor, final Collection<Ref> want, final Set<ObjectId> have) @@ -249,16 +251,19 @@ class WalkFetchConnection extends BaseFetchConnection { } } + /** {@inheritDoc} */ @Override public Collection<PackLock> getPackLocks() { return packLocks; } + /** {@inheritDoc} */ @Override public void setPackLockMessage(final String message) { lockMessage = message; } + /** {@inheritDoc} */ @Override public void close() { inserter.close(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/WalkPushConnection.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/WalkPushConnection.java index 5c4e14ca31..cf50c51d5d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/WalkPushConnection.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/WalkPushConnection.java @@ -134,6 +134,7 @@ class WalkPushConnection extends BaseConnection implements PushConnection { dest = w; } + /** {@inheritDoc} */ @Override public void push(final ProgressMonitor monitor, final Map<String, RemoteRefUpdate> refUpdates) @@ -141,6 +142,7 @@ class WalkPushConnection extends BaseConnection implements PushConnection { push(monitor, refUpdates, null); } + /** {@inheritDoc} */ @Override public void push(final ProgressMonitor monitor, final Map<String, RemoteRefUpdate> refUpdates, OutputStream out) @@ -212,6 +214,7 @@ class WalkPushConnection extends BaseConnection implements PushConnection { } } + /** {@inheritDoc} */ @Override public void close() { dest.close(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/WalkRemoteObjectDatabase.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/WalkRemoteObjectDatabase.java index 17f8c3ec19..a0ad2f3662 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/WalkRemoteObjectDatabase.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/WalkRemoteObjectDatabase.java @@ -417,7 +417,7 @@ abstract class WalkRemoteObjectDatabase { * @param avail * return collection of references. Any existing entries will be * replaced if they are found in the packed-refs file. - * @throws TransportException + * @throws org.eclipse.jgit.errors.TransportException * an error occurred reading from the packed refs file. */ protected void readPackedRefs(final Map<String, Ref> avail) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/WalkTransport.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/WalkTransport.java index f1c4357113..8262d0024d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/WalkTransport.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/WalkTransport.java @@ -53,8 +53,9 @@ package org.eclipse.jgit.transport; * from the loose objects directory, or entire packs if the source side does not * have the object as a loose object. * <p> - * WalkTransports are not as efficient as {@link PackTransport} instances, but - * can be useful in situations where a pack transport is not acceptable. + * WalkTransports are not as efficient as + * {@link org.eclipse.jgit.transport.PackTransport} instances, but can be useful + * in situations where a pack transport is not acceptable. * * @see WalkFetchConnection */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/WantNotValidException.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/WantNotValidException.java index f0f64344b8..601b0d0a5b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/WantNotValidException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/WantNotValidException.java @@ -54,7 +54,7 @@ import org.eclipse.jgit.lib.AnyObjectId; * <p> * Typically visible only inside of the server implementation; clients are * usually looking at the text message from the server in a generic - * {@link PackProtocolException}. + * {@link org.eclipse.jgit.errors.PackProtocolException}. * * @since 4.3 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/WriteAbortedException.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/WriteAbortedException.java index 267bf7a380..e3987ea070 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/WriteAbortedException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/WriteAbortedException.java @@ -49,7 +49,7 @@ import java.io.IOException; * An exception to be thrown when the write operation is aborted. * <p> * That can be thrown inside - * {@link ObjectCountCallback#setObjectCount(long)}. + * {@link org.eclipse.jgit.transport.ObjectCountCallback#setObjectCount(long)}. * * @since 4.1 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/http/HttpConnection.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/http/HttpConnection.java index 35a1ee15ed..d815bc354e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/http/HttpConnection.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/http/HttpConnection.java @@ -56,13 +56,12 @@ import java.util.Map; import javax.net.ssl.HostnameVerifier; import javax.net.ssl.KeyManager; -import javax.net.ssl.SSLContext; import javax.net.ssl.TrustManager; /** * The interface of connections used during HTTP communication. This interface - * is that subset of the interface exposed by {@link HttpURLConnection} which is - * used by JGit + * is that subset of the interface exposed by {@link java.net.HttpURLConnection} + * which is used by JGit * * @since 3.3 */ @@ -114,32 +113,42 @@ public interface HttpConnection { public static final int HTTP_FORBIDDEN = java.net.HttpURLConnection.HTTP_FORBIDDEN; /** + * Get response code + * * @see HttpURLConnection#getResponseCode() * @return the HTTP Status-Code, or -1 - * @throws IOException + * @throws java.io.IOException */ public int getResponseCode() throws IOException; /** + * Get URL + * * @see HttpURLConnection#getURL() * @return the URL. */ public URL getURL(); /** + * Get response message + * * @see HttpURLConnection#getResponseMessage() * @return the HTTP response message, or <code>null</code> - * @throws IOException + * @throws java.io.IOException */ public String getResponseMessage() throws IOException; /** + * Get list of header fields + * * @see HttpURLConnection#getHeaderFields() * @return a Map of header fields */ public Map<String, List<String>> getHeaderFields(); /** + * Set request property + * * @see HttpURLConnection#setRequestProperty(String, String) * @param key * the keyword by which the request is known (e.g., " @@ -150,17 +159,23 @@ public interface HttpConnection { public void setRequestProperty(String key, String value); /** + * Set request method + * * @see HttpURLConnection#setRequestMethod(String) * @param method * the HTTP method * @exception ProtocolException * if the method cannot be reset or if the requested method * isn't valid for HTTP. + * @throws java.net.ProtocolException + * if any. */ public void setRequestMethod(String method) throws ProtocolException; /** + * Set if to use caches + * * @see HttpURLConnection#setUseCaches(boolean) * @param usecaches * a <code>boolean</code> indicating whether or not to allow @@ -169,6 +184,8 @@ public interface HttpConnection { public void setUseCaches(boolean usecaches); /** + * Set connect timeout + * * @see HttpURLConnection#setConnectTimeout(int) * @param timeout * an <code>int</code> that specifies the connect timeout value @@ -177,6 +194,8 @@ public interface HttpConnection { public void setConnectTimeout(int timeout); /** + * Set read timeout + * * @see HttpURLConnection#setReadTimeout(int) * @param timeout * an <code>int</code> that specifies the timeout value to be @@ -185,6 +204,8 @@ public interface HttpConnection { public void setReadTimeout(int timeout); /** + * Get content type + * * @see HttpURLConnection#getContentType() * @return the content type of the resource that the URL references, or * <code>null</code> if not known. @@ -192,14 +213,20 @@ public interface HttpConnection { public String getContentType(); /** + * Get input stream + * * @see HttpURLConnection#getInputStream() * @return an input stream that reads from this open connection. * @exception IOException * if an I/O error occurs while creating the input stream. + * @throws java.io.IOException + * if any. */ public InputStream getInputStream() throws IOException; /** + * Get header field + * * @see HttpURLConnection#getHeaderField(String) * @param name * the name of a header field. @@ -209,6 +236,8 @@ public interface HttpConnection { public String getHeaderField(String name); /** + * Get content length + * * @see HttpURLConnection#getContentLength() * @return the content length of the resource that this connection's URL * references, {@code -1} if the content length is not known, or if @@ -217,6 +246,8 @@ public interface HttpConnection { public int getContentLength(); /** + * Set whether or not to follow HTTP redirects. + * * @see HttpURLConnection#setInstanceFollowRedirects(boolean) * @param followRedirects * a <code>boolean</code> indicating whether or not to follow @@ -225,27 +256,35 @@ public interface HttpConnection { public void setInstanceFollowRedirects(boolean followRedirects); /** + * Set if to do output + * * @see HttpURLConnection#setDoOutput(boolean) - * @param dooutput the new value. + * @param dooutput + * the new value. */ public void setDoOutput(boolean dooutput); /** + * Set fixed length streaming mode + * * @see HttpURLConnection#setFixedLengthStreamingMode(int) * @param contentLength * The number of bytes which will be written to the OutputStream. - * */ public void setFixedLengthStreamingMode(int contentLength); /** + * Get output stream + * * @see HttpURLConnection#getOutputStream() * @return an output stream that writes to this connection. - * @throws IOException + * @throws java.io.IOException */ public OutputStream getOutputStream() throws IOException; /** + * Set chunked streaming mode + * * @see HttpURLConnection#setChunkedStreamingMode(int) * @param chunklen * The number of bytes to write in each chunk. If chunklen is @@ -254,20 +293,26 @@ public interface HttpConnection { public void setChunkedStreamingMode(int chunklen); /** + * Get request method + * * @see HttpURLConnection#getRequestMethod() * @return the HTTP request method */ public String getRequestMethod(); /** + * Whether we use a proxy + * * @see HttpURLConnection#usingProxy() * @return a boolean indicating if the connection is using a proxy. */ public boolean usingProxy(); /** + * Connect + * * @see HttpURLConnection#connect() - * @throws IOException + * @throws java.io.IOException */ public void connect() throws IOException; @@ -283,21 +328,22 @@ public interface HttpConnection { * whether credentials presented by a peer should be accepted. * @param random * the source of randomness for this generator or null. See - * {@link SSLContext#init(KeyManager[], TrustManager[], SecureRandom)} - * - * @throws NoSuchAlgorithmException - * @throws KeyManagementException + * {@link javax.net.ssl.SSLContext#init(KeyManager[], TrustManager[], SecureRandom)} + * @throws java.security.NoSuchAlgorithmException + * @throws java.security.KeyManagementException */ public void configure(KeyManager[] km, TrustManager[] tm, SecureRandom random) throws NoSuchAlgorithmException, KeyManagementException; /** - * Set the {@link HostnameVerifier} used during https communication + * Set the {@link javax.net.ssl.HostnameVerifier} used during https + * communication * * @param hostnameverifier - * @throws NoSuchAlgorithmException - * @throws KeyManagementException + * a {@link javax.net.ssl.HostnameVerifier} object. + * @throws java.security.NoSuchAlgorithmException + * @throws java.security.KeyManagementException */ public void setHostnameVerifier(HostnameVerifier hostnameverifier) throws NoSuchAlgorithmException, KeyManagementException; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/http/HttpConnectionFactory.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/http/HttpConnectionFactory.java index 591353c18d..bd9d61fe66 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/http/HttpConnectionFactory.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/http/HttpConnectionFactory.java @@ -47,30 +47,33 @@ import java.net.Proxy; import java.net.URL; /** - * The interface of a factory returning {@link HttpConnection} + * The interface of a factory returning + * {@link org.eclipse.jgit.transport.http.HttpConnection} * * @since 3.3 */ public interface HttpConnectionFactory { /** - * Creates a new connection to a destination defined by a {@link URL} + * Creates a new connection to a destination defined by a + * {@link java.net.URL} * * @param url - * @return a {@link HttpConnection} - * @throws IOException + * a {@link java.net.URL} object. + * @return a {@link org.eclipse.jgit.transport.http.HttpConnection} + * @throws java.io.IOException */ public HttpConnection create(URL url) throws IOException; /** - * Creates a new connection to a destination defined by a {@link URL} using - * a proxy + * Creates a new connection to a destination defined by a + * {@link java.net.URL} using a proxy * * @param url + * a {@link java.net.URL} object. * @param proxy * the proxy to be used - * @return a {@link HttpConnection} - * - * @throws IOException + * @return a {@link org.eclipse.jgit.transport.http.HttpConnection} + * @throws java.io.IOException */ public HttpConnection create(URL url, Proxy proxy) throws IOException; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/http/JDKHttpConnection.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/http/JDKHttpConnection.java index 534e3d734f..8241c59d2b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/http/JDKHttpConnection.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/http/JDKHttpConnection.java @@ -63,8 +63,9 @@ import javax.net.ssl.SSLContext; import javax.net.ssl.TrustManager; /** - * A {@link HttpConnection} which simply delegates every call to a - * {@link HttpURLConnection}. This is the default implementation used by JGit + * A {@link org.eclipse.jgit.transport.http.HttpConnection} which simply + * delegates every call to a {@link java.net.HttpURLConnection}. This is the + * default implementation used by JGit * * @since 3.3 */ @@ -72,9 +73,12 @@ public class JDKHttpConnection implements HttpConnection { HttpURLConnection wrappedUrlConnection; /** + * Constructor for JDKHttpConnection. + * * @param url - * @throws MalformedURLException - * @throws IOException + * a {@link java.net.URL} object. + * @throws java.net.MalformedURLException + * @throws java.io.IOException */ protected JDKHttpConnection(URL url) throws MalformedURLException, @@ -83,10 +87,14 @@ public class JDKHttpConnection implements HttpConnection { } /** + * Constructor for JDKHttpConnection. + * * @param url + * a {@link java.net.URL} object. * @param proxy - * @throws MalformedURLException - * @throws IOException + * a {@link java.net.Proxy} object. + * @throws java.net.MalformedURLException + * @throws java.io.IOException */ protected JDKHttpConnection(URL url, Proxy proxy) throws MalformedURLException, IOException { @@ -94,117 +102,140 @@ public class JDKHttpConnection implements HttpConnection { .openConnection(proxy); } + /** {@inheritDoc} */ @Override public int getResponseCode() throws IOException { return wrappedUrlConnection.getResponseCode(); } + /** {@inheritDoc} */ @Override public URL getURL() { return wrappedUrlConnection.getURL(); } + /** {@inheritDoc} */ @Override public String getResponseMessage() throws IOException { return wrappedUrlConnection.getResponseMessage(); } + /** {@inheritDoc} */ @Override public Map<String, List<String>> getHeaderFields() { return wrappedUrlConnection.getHeaderFields(); } + /** {@inheritDoc} */ @Override public void setRequestProperty(String key, String value) { wrappedUrlConnection.setRequestProperty(key, value); } + /** {@inheritDoc} */ @Override public void setRequestMethod(String method) throws ProtocolException { wrappedUrlConnection.setRequestMethod(method); } + /** {@inheritDoc} */ @Override public void setUseCaches(boolean usecaches) { wrappedUrlConnection.setUseCaches(usecaches); } + /** {@inheritDoc} */ @Override public void setConnectTimeout(int timeout) { wrappedUrlConnection.setConnectTimeout(timeout); } + /** {@inheritDoc} */ @Override public void setReadTimeout(int timeout) { wrappedUrlConnection.setReadTimeout(timeout); } + /** {@inheritDoc} */ @Override public String getContentType() { return wrappedUrlConnection.getContentType(); } + /** {@inheritDoc} */ @Override public InputStream getInputStream() throws IOException { return wrappedUrlConnection.getInputStream(); } + /** {@inheritDoc} */ @Override public String getHeaderField(String name) { return wrappedUrlConnection.getHeaderField(name); } + /** {@inheritDoc} */ @Override public int getContentLength() { return wrappedUrlConnection.getContentLength(); } + /** {@inheritDoc} */ @Override public void setInstanceFollowRedirects(boolean followRedirects) { wrappedUrlConnection.setInstanceFollowRedirects(followRedirects); } + /** {@inheritDoc} */ @Override public void setDoOutput(boolean dooutput) { wrappedUrlConnection.setDoOutput(dooutput); } + /** {@inheritDoc} */ @Override public void setFixedLengthStreamingMode(int contentLength) { wrappedUrlConnection.setFixedLengthStreamingMode(contentLength); } + /** {@inheritDoc} */ @Override public OutputStream getOutputStream() throws IOException { return wrappedUrlConnection.getOutputStream(); } + /** {@inheritDoc} */ @Override public void setChunkedStreamingMode(int chunklen) { wrappedUrlConnection.setChunkedStreamingMode(chunklen); } + /** {@inheritDoc} */ @Override public String getRequestMethod() { return wrappedUrlConnection.getRequestMethod(); } + /** {@inheritDoc} */ @Override public boolean usingProxy() { return wrappedUrlConnection.usingProxy(); } + /** {@inheritDoc} */ @Override public void connect() throws IOException { wrappedUrlConnection.connect(); } + /** {@inheritDoc} */ @Override public void setHostnameVerifier(HostnameVerifier hostnameverifier) { ((HttpsURLConnection) wrappedUrlConnection) .setHostnameVerifier(hostnameverifier); } + /** {@inheritDoc} */ @Override public void configure(KeyManager[] km, TrustManager[] tm, SecureRandom random) throws NoSuchAlgorithmException, diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/http/JDKHttpConnectionFactory.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/http/JDKHttpConnectionFactory.java index b9f009f1b7..ef88947aad 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/http/JDKHttpConnectionFactory.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/http/JDKHttpConnectionFactory.java @@ -47,16 +47,19 @@ import java.net.Proxy; import java.net.URL; /** - * A factory returning instances of {@link JDKHttpConnection} + * A factory returning instances of + * {@link org.eclipse.jgit.transport.http.JDKHttpConnection} * * @since 3.3 */ public class JDKHttpConnectionFactory implements HttpConnectionFactory { + /** {@inheritDoc} */ @Override public HttpConnection create(URL url) throws IOException { return new JDKHttpConnection(url); } + /** {@inheritDoc} */ @Override public HttpConnection create(URL url, Proxy proxy) throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/FileResolver.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/FileResolver.java index 8ab112e5f9..16a6f4ab73 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/FileResolver.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/FileResolver.java @@ -70,7 +70,9 @@ public class FileResolver<C> implements RepositoryResolver<C> { private final Collection<File> exportBase; - /** Initialize an empty file based resolver. */ + /** + * Initialize an empty file based resolver. + */ public FileResolver() { exports = new ConcurrentHashMap<>(); exportBase = new CopyOnWriteArrayList<>(); @@ -91,6 +93,7 @@ public class FileResolver<C> implements RepositoryResolver<C> { setExportAll(exportAll); } + /** {@inheritDoc} */ @Override public Repository open(final C req, final String name) throws RepositoryNotFoundException, ServiceNotEnabledException { @@ -148,6 +151,9 @@ public class FileResolver<C> implements RepositoryResolver<C> { } /** + * Whether <code>git-daemon-export-ok</code> is required to export a + * repository + * * @return false if <code>git-daemon-export-ok</code> is required to export * a repository; true if <code>git-daemon-export-ok</code> is * ignored. @@ -167,7 +173,7 @@ public class FileResolver<C> implements RepositoryResolver<C> { * If true, all repositories are available through the daemon, whether or * not <code>git-daemon-export-ok</code> exists. * - * @param export + * @param export a boolean. */ public void setExportAll(final boolean export) { exportAll = export; @@ -214,7 +220,7 @@ public class FileResolver<C> implements RepositoryResolver<C> { * @param db * the opened repository instance. * @return true if the repository is accessible; false if not. - * @throws IOException + * @throws java.io.IOException * the repository could not be accessed, the caller will claim * the repository does not exist. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/ReceivePackFactory.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/ReceivePackFactory.java index 73c2ed80c9..4967169776 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/ReceivePackFactory.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/ReceivePackFactory.java @@ -47,13 +47,16 @@ import org.eclipse.jgit.lib.Repository; import org.eclipse.jgit.transport.ReceivePack; /** - * Create and configure {@link ReceivePack} service instance. + * Create and configure {@link org.eclipse.jgit.transport.ReceivePack} service + * instance. * * @param <C> * type of connection */ public interface ReceivePackFactory<C> { - /** A factory disabling the ReceivePack service for all repositories */ + /** + * A factory disabling the ReceivePack service for all repositories + */ public static final ReceivePackFactory<?> DISABLED = new ReceivePackFactory<Object>() { @Override public ReceivePack create(Object req, Repository db) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/RepositoryResolver.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/RepositoryResolver.java index 80211e5812..a305e4cea3 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/RepositoryResolver.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/RepositoryResolver.java @@ -48,13 +48,15 @@ import org.eclipse.jgit.lib.Repository; import org.eclipse.jgit.transport.ServiceMayNotContinueException; /** - * Locate a Git {@link Repository} by name from the URL. + * Locate a Git {@link org.eclipse.jgit.lib.Repository} by name from the URL. * * @param <C> * type of connection. */ public interface RepositoryResolver<C> { - /** Resolver configured to open nothing. */ + /** + * Resolver configured to open nothing. + */ public static final RepositoryResolver<?> NONE = new RepositoryResolver<Object>() { @Override public Repository open(Object req, String name) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/ServiceNotAuthorizedException.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/ServiceNotAuthorizedException.java index 57a61928b5..d2d1b99d2f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/ServiceNotAuthorizedException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/ServiceNotAuthorizedException.java @@ -56,8 +56,12 @@ public class ServiceNotAuthorizedException extends Exception { private static final long serialVersionUID = 1L; /** + * Constructor for ServiceNotAuthorizedException. + * * @param message + * error message * @param cause + * a {@link java.lang.Throwable} object. * @since 4.1 */ public ServiceNotAuthorizedException(String message, Throwable cause) { @@ -65,14 +69,19 @@ public class ServiceNotAuthorizedException extends Exception { } /** + * Constructor for ServiceNotAuthorizedException. + * * @param message + * error message * @since 4.1 */ public ServiceNotAuthorizedException(String message) { super(message); } - /** Indicates that the requested service requires authentication. */ + /** + * Indicates that the requested service requires authentication. + */ public ServiceNotAuthorizedException() { super(JGitText.get().unauthorized); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/ServiceNotEnabledException.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/ServiceNotEnabledException.java index 78ae303ed0..4473452d07 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/ServiceNotEnabledException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/ServiceNotEnabledException.java @@ -45,13 +45,19 @@ package org.eclipse.jgit.transport.resolver; import org.eclipse.jgit.internal.JGitText; -/** Indicates the request service is not enabled on a repository. */ +/** + * Indicates the request service is not enabled on a repository. + */ public class ServiceNotEnabledException extends Exception { private static final long serialVersionUID = 1L; /** + * Constructor for ServiceNotEnabledException. + * * @param message + * error message * @param cause + * a {@link java.lang.Throwable} object. * @since 4.1 */ public ServiceNotEnabledException(String message, Throwable cause) { @@ -59,14 +65,19 @@ public class ServiceNotEnabledException extends Exception { } /** + * Constructor for ServiceNotEnabledException. + * * @param message + * error message * @since 4.1 */ public ServiceNotEnabledException(String message) { super(message); } - /** Indicates the request service is not available. */ + /** + * Indicates the request service is not available. + */ public ServiceNotEnabledException() { super(JGitText.get().serviceNotEnabledNoName); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/UploadPackFactory.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/UploadPackFactory.java index d7ed0f68cf..40d1ffdc56 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/UploadPackFactory.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/resolver/UploadPackFactory.java @@ -47,13 +47,16 @@ import org.eclipse.jgit.lib.Repository; import org.eclipse.jgit.transport.UploadPack; /** - * Create and configure {@link UploadPack} service instance. + * Create and configure {@link org.eclipse.jgit.transport.UploadPack} service + * instance. * * @param <C> * the connection type */ public interface UploadPackFactory<C> { - /** A factory disabling the UploadPack service for all repositories. */ + /** + * A factory disabling the UploadPack service for all repositories. + */ public static final UploadPackFactory<?> DISABLED = new UploadPackFactory<Object>() { @Override public UploadPack create(Object req, Repository db) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/AbstractTreeIterator.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/AbstractTreeIterator.java index 6d4c342284..a7900f0b67 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/AbstractTreeIterator.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/AbstractTreeIterator.java @@ -51,7 +51,6 @@ import java.nio.CharBuffer; import org.eclipse.jgit.attributes.AttributesHandler; import org.eclipse.jgit.attributes.AttributesNode; -import org.eclipse.jgit.dircache.DirCacheCheckout; import org.eclipse.jgit.errors.CorruptObjectException; import org.eclipse.jgit.errors.IncorrectObjectTypeException; import org.eclipse.jgit.lib.Constants; @@ -59,7 +58,6 @@ import org.eclipse.jgit.lib.FileMode; import org.eclipse.jgit.lib.MutableObjectId; import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.lib.ObjectReader; -import org.eclipse.jgit.treewalk.filter.TreeFilter; import org.eclipse.jgit.util.Paths; /** @@ -154,7 +152,9 @@ public abstract class AbstractTreeIterator { */ protected int pathLen; - /** Create a new iterator with no parent. */ + /** + * Create a new iterator with no parent. + */ protected AbstractTreeIterator() { parent = null; path = new byte[DEFAULT_PATH_SIZE]; @@ -341,7 +341,7 @@ public abstract class AbstractTreeIterator { * @param name * file name to find (will not find a directory). * @return true if the file exists in this tree; false otherwise. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * tree is invalid. * @since 4.2 */ @@ -355,7 +355,7 @@ public abstract class AbstractTreeIterator { * @param name * file name to find (will not find a directory). * @return true if the file exists in this tree; false otherwise. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * tree is invalid. * @since 4.2 */ @@ -425,7 +425,11 @@ public abstract class AbstractTreeIterator { otherIterator.idBuffer(), otherIterator.idOffset()); } - /** @return true if the entry has a valid ObjectId. */ + /** + * Whether the entry has a valid ObjectId. + * + * @return {@code true} if the entry has a valid ObjectId. + */ public abstract boolean hasId(); /** @@ -447,17 +451,29 @@ public abstract class AbstractTreeIterator { out.fromRaw(idBuffer(), idOffset()); } - /** @return the file mode of the current entry. */ + /** + * Get the file mode of the current entry. + * + * @return the file mode of the current entry. + */ public FileMode getEntryFileMode() { return FileMode.fromBits(mode); } - /** @return the file mode of the current entry as bits */ + /** + * Get the file mode of the current entry as bits. + * + * @return the file mode of the current entry as bits. + */ public int getEntryRawMode() { return mode; } - /** @return path of the current entry, as a string. */ + /** + * Get path of the current entry, as a string. + * + * @return path of the current entry, as a string. + */ public String getEntryPathString() { return TreeWalk.pathOf(this); } @@ -474,7 +490,11 @@ public abstract class AbstractTreeIterator { return path; } - /** @return length of the path in {@link #getEntryPathBuffer()}. */ + /** + * Get length of the path in {@link #getEntryPathBuffer()}. + * + * @return length of the path in {@link #getEntryPathBuffer()}. + */ public int getEntryPathLength() { return pathLen; } @@ -529,10 +549,10 @@ public abstract class AbstractTreeIterator { * @param reader * reader to load the tree data from. * @return a new parser that walks over the current subtree. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the current entry is not actually a tree and cannot be parsed * as though it were a tree. - * @throws IOException + * @throws java.io.IOException * a loose object or pack file could not be read. */ public abstract AbstractTreeIterator createSubtreeIterator( @@ -560,10 +580,10 @@ public abstract class AbstractTreeIterator { * @param idBuffer * temporary ObjectId buffer for use by this method. * @return a new parser that walks over the current subtree. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the current entry is not actually a tree and cannot be parsed * as though it were a tree. - * @throws IOException + * @throws java.io.IOException * a loose object or pack file could not be read. */ public AbstractTreeIterator createSubtreeIterator( @@ -580,7 +600,7 @@ public abstract class AbstractTreeIterator { * method of repositioning the iterator to its first entry, so subclasses * are strongly encouraged to override the method. * - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the tree is invalid. */ public void reset() throws CorruptObjectException { @@ -629,7 +649,7 @@ public abstract class AbstractTreeIterator { * @param delta * number of entries to move the iterator by. Must be a positive, * non-zero integer. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the tree is invalid. */ public abstract void next(int delta) throws CorruptObjectException; @@ -653,7 +673,7 @@ public abstract class AbstractTreeIterator { * @param delta * number of entries to move the iterator by. Must be a positive, * non-zero integer. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the tree is invalid. */ public abstract void back(int delta) throws CorruptObjectException; @@ -662,11 +682,12 @@ public abstract class AbstractTreeIterator { * Advance to the next tree entry, populating this iterator with its data. * <p> * This method behaves like <code>seek(1)</code> but is called by - * {@link TreeWalk} only if a {@link TreeFilter} was used and ruled out the - * current entry from the results. In such cases this tree iterator may - * perform special behavior. + * {@link org.eclipse.jgit.treewalk.TreeWalk} only if a + * {@link org.eclipse.jgit.treewalk.filter.TreeFilter} was used and ruled + * out the current entry from the results. In such cases this tree iterator + * may perform special behavior. * - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the tree is invalid. */ public void skip() throws CorruptObjectException { @@ -685,7 +706,9 @@ public abstract class AbstractTreeIterator { } /** - * @return true if the iterator implements {@link #stopWalk()}. + * Whether the iterator implements {@link #stopWalk()}. + * + * @return {@code true} if the iterator implements {@link #stopWalk()}. * @since 4.2 */ protected boolean needsStopWalk() { @@ -693,14 +716,18 @@ public abstract class AbstractTreeIterator { } /** - * @return the length of the name component of the path for the current entry + * Get the length of the name component of the path for the current entry. + * + * @return the length of the name component of the path for the current + * entry. */ public int getNameLength() { return pathLen - pathOffset; } /** - * JGit internal API for use by {@link DirCacheCheckout} + * JGit internal API for use by + * {@link org.eclipse.jgit.dircache.DirCacheCheckout} * * @return start of name component part within {@link #getEntryPathBuffer()} * @since 2.0 @@ -724,6 +751,7 @@ public abstract class AbstractTreeIterator { System.arraycopy(path, pathOffset, buffer, offset, pathLen - pathOffset); } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { @@ -731,8 +759,10 @@ public abstract class AbstractTreeIterator { } /** - * @return whether or not this Iterator is iterating through the Work Tree + * Whether or not this Iterator is iterating through the working tree. * + * @return whether or not this Iterator is iterating through the working + * tree * @since 4.3 */ public boolean isWorkTree() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/CanonicalTreeParser.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/CanonicalTreeParser.java index 2d6abd1ad0..71113a661a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/CanonicalTreeParser.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/CanonicalTreeParser.java @@ -66,7 +66,9 @@ import org.eclipse.jgit.lib.MutableObjectId; import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.lib.ObjectReader; -/** Parses raw Git trees from the canonical semi-text/semi-binary format. */ +/** + * Parses raw Git trees from the canonical semi-text/semi-binary format. + */ public class CanonicalTreeParser extends AbstractTreeIterator { private static final byte[] EMPTY = {}; private static final byte[] ATTRS = encode(DOT_GIT_ATTRIBUTES); @@ -82,7 +84,9 @@ public class CanonicalTreeParser extends AbstractTreeIterator { /** Offset one past the current entry (first byte of next entry). */ private int nextPtr; - /** Create a new parser. */ + /** + * Create a new parser. + */ public CanonicalTreeParser() { reset(EMPTY); } @@ -102,10 +106,10 @@ public class CanonicalTreeParser extends AbstractTreeIterator { * messages if data corruption is found. * @throws MissingObjectException * the object supplied is not available from the repository. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the object supplied as an argument is not actually a tree and * cannot be parsed as though it were a tree. - * @throws IOException + * @throws java.io.IOException * a loose object or pack file could not be read. */ public CanonicalTreeParser(final byte[] prefix, final ObjectReader reader, @@ -120,7 +124,9 @@ public class CanonicalTreeParser extends AbstractTreeIterator { } /** - * @return the parent of this tree parser + * Get the parent of this tree parser. + * + * @return the parent of this tree parser. * @deprecated internal use only */ @Deprecated @@ -156,10 +162,10 @@ public class CanonicalTreeParser extends AbstractTreeIterator { * @return the root level parser. * @throws MissingObjectException * the object supplied is not available from the repository. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the object supplied as an argument is not actually a tree and * cannot be parsed as though it were a tree. - * @throws IOException + * @throws java.io.IOException * a loose object or pack file could not be read. */ public CanonicalTreeParser resetRoot(final ObjectReader reader, @@ -172,7 +178,11 @@ public class CanonicalTreeParser extends AbstractTreeIterator { return p; } - /** @return this iterator, or its parent, if the tree is at eof. */ + /** + * Get this iterator, or its parent, if the tree is at eof. + * + * @return this iterator, or its parent, if the tree is at eof. + */ public CanonicalTreeParser next() { CanonicalTreeParser p = this; for (;;) { @@ -203,10 +213,10 @@ public class CanonicalTreeParser extends AbstractTreeIterator { * messages if data corruption is found. * @throws MissingObjectException * the object supplied is not available from the repository. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the object supplied as an argument is not actually a tree and * cannot be parsed as though it were a tree. - * @throws IOException + * @throws java.io.IOException * a loose object or pack file could not be read. */ public void reset(final ObjectReader reader, final AnyObjectId id) @@ -214,6 +224,7 @@ public class CanonicalTreeParser extends AbstractTreeIterator { reset(reader.open(id, OBJ_TREE).getCachedBytes()); } + /** {@inheritDoc} */ @Override public CanonicalTreeParser createSubtreeIterator(final ObjectReader reader, final MutableObjectId idBuffer) @@ -238,7 +249,7 @@ public class CanonicalTreeParser extends AbstractTreeIterator { * @param id * ObjectId of the tree to open. * @return a new parser that walks over the current subtree. - * @throws IOException + * @throws java.io.IOException * a loose object or pack file could not be read. */ public final CanonicalTreeParser createSubtreeIterator0( @@ -249,43 +260,51 @@ public class CanonicalTreeParser extends AbstractTreeIterator { return p; } + /** {@inheritDoc} */ @Override public CanonicalTreeParser createSubtreeIterator(final ObjectReader reader) throws IncorrectObjectTypeException, IOException { return createSubtreeIterator(reader, new MutableObjectId()); } + /** {@inheritDoc} */ @Override public boolean hasId() { return true; } + /** {@inheritDoc} */ @Override public byte[] idBuffer() { return raw; } + /** {@inheritDoc} */ @Override public int idOffset() { return nextPtr - OBJECT_ID_LENGTH; } + /** {@inheritDoc} */ @Override public void reset() { if (!first()) reset(raw); } + /** {@inheritDoc} */ @Override public boolean first() { return currPtr == 0; } + /** {@inheritDoc} */ @Override public boolean eof() { return currPtr == raw.length; } + /** {@inheritDoc} */ @Override public void next(int delta) { if (delta == 1) { @@ -315,6 +334,7 @@ public class CanonicalTreeParser extends AbstractTreeIterator { parseEntry(); } + /** {@inheritDoc} */ @Override public void back(int delta) { if (delta == 1 && 0 <= prevPtr) { @@ -381,12 +401,15 @@ public class CanonicalTreeParser extends AbstractTreeIterator { } /** - * Retrieve the {@link AttributesNode} for the current entry. + * Retrieve the {@link org.eclipse.jgit.attributes.AttributesNode} for the + * current entry. * * @param reader - * {@link ObjectReader} used to parse the .gitattributes entry. - * @return {@link AttributesNode} for the current entry. - * @throws IOException + * {@link org.eclipse.jgit.lib.ObjectReader} used to parse the + * .gitattributes entry. + * @return {@link org.eclipse.jgit.attributes.AttributesNode} for the + * current entry. + * @throws java.io.IOException * @since 4.2 */ public AttributesNode getEntryAttributesNode(ObjectReader reader) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/EmptyTreeIterator.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/EmptyTreeIterator.java index ec4a84eff3..596d3d0835 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/EmptyTreeIterator.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/EmptyTreeIterator.java @@ -52,9 +52,13 @@ import org.eclipse.jgit.errors.IncorrectObjectTypeException; import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.lib.ObjectReader; -/** Iterator over an empty tree (a directory with no files). */ +/** + * Iterator over an empty tree (a directory with no files). + */ public class EmptyTreeIterator extends AbstractTreeIterator { - /** Create a new iterator with no parent. */ + /** + * Create a new iterator with no parent. + */ public EmptyTreeIterator() { // Create a root empty tree. } @@ -86,63 +90,75 @@ public class EmptyTreeIterator extends AbstractTreeIterator { pathLen = childPathOffset - 1; } + /** {@inheritDoc} */ @Override public AbstractTreeIterator createSubtreeIterator(final ObjectReader reader) throws IncorrectObjectTypeException, IOException { return new EmptyTreeIterator(this); } + /** {@inheritDoc} */ @Override public boolean hasId() { return false; } + /** {@inheritDoc} */ @Override public ObjectId getEntryObjectId() { return ObjectId.zeroId(); } + /** {@inheritDoc} */ @Override public byte[] idBuffer() { return zeroid; } + /** {@inheritDoc} */ @Override public int idOffset() { return 0; } + /** {@inheritDoc} */ @Override public void reset() { // Do nothing. } + /** {@inheritDoc} */ @Override public boolean first() { return true; } + /** {@inheritDoc} */ @Override public boolean eof() { return true; } + /** {@inheritDoc} */ @Override public void next(final int delta) throws CorruptObjectException { // Do nothing. } + /** {@inheritDoc} */ @Override public void back(final int delta) throws CorruptObjectException { // Do nothing. } + /** {@inheritDoc} */ @Override public void stopWalk() { if (parent != null) parent.stopWalk(); } + /** {@inheritDoc} */ @Override protected boolean needsStopWalk() { return parent != null && parent.needsStopWalk(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/FileTreeIterator.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/FileTreeIterator.java index afa2ed9cb8..8df764d293 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/FileTreeIterator.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/FileTreeIterator.java @@ -63,7 +63,8 @@ import org.eclipse.jgit.util.FS; * Working directory iterator for standard Java IO. * <p> * This iterator uses the standard <code>java.io</code> package to read the - * specified working directory as part of a {@link TreeWalk}. + * specified working directory as part of a + * {@link org.eclipse.jgit.treewalk.TreeWalk}. */ public class FileTreeIterator extends WorkingTreeIterator { /** @@ -108,7 +109,6 @@ public class FileTreeIterator extends WorkingTreeIterator { * @param fileModeStrategy * the strategy to use to determine the FileMode for a FileEntry; * controls gitlinks etc. - * * @since 4.3 */ public FileTreeIterator(Repository repo, FileModeStrategy fileModeStrategy) { @@ -148,7 +148,6 @@ public class FileTreeIterator extends WorkingTreeIterator { * @param fileModeStrategy * the strategy to use to determine the FileMode for a FileEntry; * controls gitlinks etc. - * * @since 4.3 */ public FileTreeIterator(final File root, FS fs, WorkingTreeOptions options, @@ -192,7 +191,6 @@ public class FileTreeIterator extends WorkingTreeIterator { * @param fs * the file system abstraction which will be necessary to perform * certain file system operations. - * * @since 4.3 */ protected FileTreeIterator(final FileTreeIterator p, final File root, @@ -215,7 +213,6 @@ public class FileTreeIterator extends WorkingTreeIterator { * @param fileModeStrategy * the strategy to use to determine the FileMode for a given * FileEntry. - * * @since 4.3 */ protected FileTreeIterator(final WorkingTreeIterator p, final File root, @@ -227,6 +224,7 @@ public class FileTreeIterator extends WorkingTreeIterator { init(entries()); } + /** {@inheritDoc} */ @Override public AbstractTreeIterator createSubtreeIterator(final ObjectReader reader) throws IncorrectObjectTypeException, IOException { @@ -407,6 +405,8 @@ public class FileTreeIterator extends WorkingTreeIterator { } /** + * <p>Getter for the field <code>directory</code>.</p> + * * @return The root directory of this iterator */ public File getDirectory() { @@ -414,6 +414,8 @@ public class FileTreeIterator extends WorkingTreeIterator { } /** + * Get the location of the working file. + * * @return The location of the working file. This is the same as {@code new * File(getDirectory(), getEntryPath())} but may be faster by * reusing an internal File instance. @@ -422,11 +424,13 @@ public class FileTreeIterator extends WorkingTreeIterator { return ((FileEntry) current()).getFile(); } + /** {@inheritDoc} */ @Override protected byte[] idSubmodule(final Entry e) { return idSubmodule(getDirectory(), e); } + /** {@inheritDoc} */ @Override protected String readSymlinkTarget(Entry entry) throws IOException { return fs.readSymLink(getEntryFile()); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/NameConflictTreeWalk.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/NameConflictTreeWalk.java index 59cf7989d4..3e06f046bf 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/NameConflictTreeWalk.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/NameConflictTreeWalk.java @@ -46,7 +46,6 @@ package org.eclipse.jgit.treewalk; import java.io.IOException; import org.eclipse.jgit.annotations.Nullable; -import org.eclipse.jgit.dircache.DirCacheBuilder; import org.eclipse.jgit.errors.CorruptObjectException; import org.eclipse.jgit.lib.FileMode; import org.eclipse.jgit.lib.ObjectReader; @@ -55,24 +54,26 @@ import org.eclipse.jgit.lib.Repository; /** * Specialized TreeWalk to detect directory-file (D/F) name conflicts. * <p> - * Due to the way a Git tree is organized the standard {@link TreeWalk} won't - * easily find a D/F conflict when merging two or more trees together. In the - * standard TreeWalk the file will be returned first, and then much later the - * directory will be returned. This makes it impossible for the application to - * efficiently detect and handle the conflict. + * Due to the way a Git tree is organized the standard + * {@link org.eclipse.jgit.treewalk.TreeWalk} won't easily find a D/F conflict + * when merging two or more trees together. In the standard TreeWalk the file + * will be returned first, and then much later the directory will be returned. + * This makes it impossible for the application to efficiently detect and handle + * the conflict. * <p> * Using this walk implementation causes the directory to report earlier than * usual, at the same time as the non-directory entry. This permits the * application to handle the D/F conflict in a single step. The directory is * returned only once, so it does not get returned later in the iteration. * <p> - * When a D/F conflict is detected {@link TreeWalk#isSubtree()} will return true - * and {@link TreeWalk#enterSubtree()} will recurse into the subtree, no matter - * which iterator originally supplied the subtree. + * When a D/F conflict is detected + * {@link org.eclipse.jgit.treewalk.TreeWalk#isSubtree()} will return true and + * {@link org.eclipse.jgit.treewalk.TreeWalk#enterSubtree()} will recurse into + * the subtree, no matter which iterator originally supplied the subtree. * <p> * Because conflicted directories report early, using this walk implementation - * to populate a {@link DirCacheBuilder} may cause the automatic resorting to - * run and fix the entry ordering. + * to populate a {@link org.eclipse.jgit.dircache.DirCacheBuilder} may cause the + * automatic resorting to run and fix the entry ordering. * <p> * This walk implementation requires more CPU to implement a look-ahead and a * look-behind to merge a D/F pair together, or to skip a previously reported diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/TreeWalk.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/TreeWalk.java index c54e1484ca..a91ad592cf 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/TreeWalk.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/TreeWalk.java @@ -81,7 +81,8 @@ import org.eclipse.jgit.util.RawParseUtils; import org.eclipse.jgit.util.io.EolStreamTypeUtil; /** - * Walks one or more {@link AbstractTreeIterator}s in parallel. + * Walks one or more {@link org.eclipse.jgit.treewalk.AbstractTreeIterator}s in + * parallel. * <p> * This class can perform n-way differences across as many trees as necessary. * <p> @@ -97,8 +98,9 @@ import org.eclipse.jgit.util.io.EolStreamTypeUtil; * usage of a TreeWalk instance to a single thread, or implement their own * synchronization at a higher level. * <p> - * Multiple simultaneous TreeWalk instances per {@link Repository} are - * permitted, even from concurrent threads. + * Multiple simultaneous TreeWalk instances per + * {@link org.eclipse.jgit.lib.Repository} are permitted, even from concurrent + * threads. */ public class TreeWalk implements AutoCloseable, AttributesProvider { private static final AbstractTreeIterator[] NO_TREES = {}; @@ -131,7 +133,11 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { private Map<String, String> filterCommandsByNameDotType = new HashMap<>(); /** + * Set the operation type of this walk + * * @param operationType + * a {@link org.eclipse.jgit.treewalk.TreeWalk.OperationType} + * object. * @since 4.2 */ public void setOperationType(OperationType operationType) { @@ -153,14 +159,14 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { * one or more trees to walk through, all with the same root. * @return a new tree walk configured for exactly this one path; null if no * path was found in any of the trees. - * @throws IOException + * @throws java.io.IOException * reading a pack file or loose object failed. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * an tree object could not be read as its data stream did not * appear to be a tree, or could not be inflated. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * an object we expected to be a tree was not a tree. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * a tree object was not found. */ public static TreeWalk forPath(final ObjectReader reader, final String path, @@ -178,7 +184,8 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { * * @param repo * repository to read config data and - * {@link AttributesNodeProvider} from. + * {@link org.eclipse.jgit.attributes.AttributesNodeProvider} + * from. * @param reader * the reader the walker will obtain tree data from. * @param path @@ -187,14 +194,14 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { * one or more trees to walk through, all with the same root. * @return a new tree walk configured for exactly this one path; null if no * path was found in any of the trees. - * @throws IOException + * @throws java.io.IOException * reading a pack file or loose object failed. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * an tree object could not be read as its data stream did not * appear to be a tree, or could not be inflated. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * an object we expected to be a tree was not a tree. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * a tree object was not found. * @since 4.3 */ @@ -234,14 +241,14 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { * one or more trees to walk through, all with the same root. * @return a new tree walk configured for exactly this one path; null if no * path was found in any of the trees. - * @throws IOException + * @throws java.io.IOException * reading a pack file or loose object failed. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * an tree object could not be read as its data stream did not * appear to be a tree, or could not be inflated. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * an object we expected to be a tree was not a tree. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * a tree object was not found. */ public static TreeWalk forPath(final Repository db, final String path, @@ -267,14 +274,14 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { * the single tree to walk through. * @return a new tree walk configured for exactly this one path; null if no * path was found in any of the trees. - * @throws IOException + * @throws java.io.IOException * reading a pack file or loose object failed. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * an tree object could not be read as its data stream did not * appear to be a tree, or could not be inflated. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * an object we expected to be a tree was not a tree. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * a tree object was not found. */ public static TreeWalk forPath(final Repository db, final String path, @@ -373,13 +380,19 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { this.closeReader = closeReader; } - /** @return the reader this walker is using to load objects. */ + /** + * Get the reader this walker is using to load objects. + * + * @return the reader this walker is using to load objects. + */ public ObjectReader getObjectReader() { return reader; } /** - * @return the {@link OperationType} + * Get the operation type + * + * @return the {@link org.eclipse.jgit.treewalk.TreeWalk.OperationType} * @since 4.3 */ public OperationType getOperationType() { @@ -387,6 +400,8 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { } /** + * {@inheritDoc} + * <p> * Release any resources used by this walker's reader. * <p> * A walker that has been released can be used again, but may need to be @@ -421,12 +436,14 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { * Note that filters are not thread-safe and may not be shared by concurrent * TreeWalk instances. Every TreeWalk must be supplied its own unique * filter, unless the filter implementation specifically states it is (and - * always will be) thread-safe. Callers may use {@link TreeFilter#clone()} - * to create a unique filter tree for this TreeWalk instance. + * always will be) thread-safe. Callers may use + * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#clone()} to create a + * unique filter tree for this TreeWalk instance. * * @param newFilter - * the new filter. If null the special {@link TreeFilter#ALL} - * filter will be used instead, as it matches every entry. + * the new filter. If null the special + * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#ALL} filter + * will be used instead, as it matches every entry. * @see org.eclipse.jgit.treewalk.filter.AndTreeFilter * @see org.eclipse.jgit.treewalk.filter.OrTreeFilter */ @@ -493,19 +510,23 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { } /** - * Sets the {@link AttributesNodeProvider} for this {@link TreeWalk}. + * Sets the {@link org.eclipse.jgit.attributes.AttributesNodeProvider} for + * this {@link org.eclipse.jgit.treewalk.TreeWalk}. * <p> - * This is a requirement for a correct computation of the git attributes. - * If this {@link TreeWalk} has been built using + * This is a requirement for a correct computation of the git attributes. If + * this {@link org.eclipse.jgit.treewalk.TreeWalk} has been built using * {@link #TreeWalk(Repository)} constructor, the - * {@link AttributesNodeProvider} has already been set. Indeed,the - * {@link Repository} can provide an {@link AttributesNodeProvider} using - * {@link Repository#createAttributesNodeProvider()} method. Otherwise you - * should provide one. + * {@link org.eclipse.jgit.attributes.AttributesNodeProvider} has already + * been set. Indeed,the {@link org.eclipse.jgit.lib.Repository} can provide + * an {@link org.eclipse.jgit.attributes.AttributesNodeProvider} using + * {@link org.eclipse.jgit.lib.Repository#createAttributesNodeProvider()} + * method. Otherwise you should provide one. * </p> * * @see Repository#createAttributesNodeProvider() * @param provider + * a {@link org.eclipse.jgit.attributes.AttributesNodeProvider} + * object. * @since 4.2 */ public void setAttributesNodeProvider(AttributesNodeProvider provider) { @@ -513,7 +534,10 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { } /** - * @return the {@link AttributesNodeProvider} for this {@link TreeWalk}. + * Get the attributes node provider + * + * @return the {@link org.eclipse.jgit.attributes.AttributesNodeProvider} + * for this {@link org.eclipse.jgit.treewalk.TreeWalk}. * @since 4.3 */ public AttributesNodeProvider getAttributesNodeProvider() { @@ -521,9 +545,11 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { } /** + * {@inheritDoc} + * <p> * Retrieve the git attributes for the current entry. * - * <h4>Git attribute computation</h4> + * <h3>Git attribute computation</h3> * * <ul> * <li>Get the attributes matching the current path entry from the info file @@ -542,7 +568,7 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { * </ul> * * - * <h4>Iterator constraints</h4> + * <h3>Iterator constraints</h3> * * <p> * In order to have a correct list of attributes for the current entry, this @@ -556,7 +582,6 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { * provided it will fallback on the {@link DirCacheIterator}. * </p> * - * @return a {@link Set} of {@link Attribute}s that match the current entry. * @since 4.2 */ @Override @@ -587,33 +612,45 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { } /** + * Get the EOL stream type of the current entry using the config and + * {@link #getAttributes()}. + * * @param opType * the operationtype (checkin/checkout) which should be used * @return the EOL stream type of the current entry using the config and - * {@link #getAttributes()} Note that this method may return null if - * the {@link TreeWalk} is not based on a working tree + * {@link #getAttributes()}. Note that this method may return null + * if the {@link org.eclipse.jgit.treewalk.TreeWalk} is not based on + * a working tree + * @since 4.10 */ - // TODO(msohn) make this method public in 4.4 @Nullable - EolStreamType getEolStreamType(OperationType opType) { - if (attributesNodeProvider == null || config == null) - return null; - return EolStreamTypeUtil.detectStreamType(opType, + public EolStreamType getEolStreamType(OperationType opType) { + if (attributesNodeProvider == null || config == null) + return null; + return EolStreamTypeUtil.detectStreamType( + opType != null ? opType : operationType, config.get(WorkingTreeOptions.KEY), getAttributes()); } /** + * Get the EOL stream type of the current entry using the config and + * {@link #getAttributes()}. + * * @return the EOL stream type of the current entry using the config and - * {@link #getAttributes()} Note that this method may return null if - * the {@link TreeWalk} is not based on a working tree + * {@link #getAttributes()}. Note that this method may return null + * if the {@link org.eclipse.jgit.treewalk.TreeWalk} is not based on + * a working tree * @since 4.3 + * @deprecated use {@link #getEolStreamType(OperationType)} instead. */ - // TODO(msohn) deprecate this method in 4.4 + @Deprecated public @Nullable EolStreamType getEolStreamType() { return (getEolStreamType(operationType)); } - /** Reset this walker so new tree iterators can be added to it. */ + /** + * Reset this walker so new tree iterators can be added to it. + */ public void reset() { attrs = null; attributesHandler = null; @@ -628,16 +665,16 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { * @param id * the tree we need to parse. The walker will execute over this * single tree if the reset is successful. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the given tree object does not exist in this repository. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the given object id does not denote a tree, but instead names * some other non-tree type of object. Note that commits are not * trees, even if they are sometimes called a "tree-ish". - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the object claimed to be a tree, but its contents did not * appear to be a tree. The repository may have data corruption. - * @throws IOException + * @throws java.io.IOException * a loose object or pack file could not be read. */ public void reset(final AnyObjectId id) throws MissingObjectException, @@ -669,16 +706,16 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { * @param ids * the trees we need to parse. The walker will execute over this * many parallel trees if the reset is successful. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the given tree object does not exist in this repository. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the given object id does not denote a tree, but instead names * some other non-tree type of object. Note that commits are not * trees, even if they are sometimes called a "tree-ish". - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the object claimed to be a tree, but its contents did not * appear to be a tree. The repository may have data corruption. - * @throws IOException + * @throws java.io.IOException * a loose object or pack file could not be read. */ public void reset(final AnyObjectId... ids) throws MissingObjectException, @@ -724,16 +761,16 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { * @param id * identity of the tree object the caller wants walked. * @return position of this tree within the walker. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * the given tree object does not exist in this repository. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * the given object id does not denote a tree, but instead names * some other non-tree type of object. Note that commits are not * trees, even if they are sometimes called a "tree-ish". - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the object claimed to be a tree, but its contents did not * appear to be a tree. The repository may have data corruption. - * @throws IOException + * @throws java.io.IOException * a loose object or pack file could not be read. */ public int addTree(final AnyObjectId id) throws MissingObjectException, @@ -784,19 +821,19 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { * * @return true if there is an entry available; false if all entries have * been walked and the walk of this set of tree iterators is over. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * {@link #isRecursive()} was enabled, a subtree was found, but * the subtree object does not exist in this repository. The * repository may be missing objects. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * {@link #isRecursive()} was enabled, a subtree was found, and * the subtree id does not denote a tree, but instead names some * other non-tree type of object. The repository may have data * corruption. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the contents of a tree did not appear to be a tree. The * repository may have data corruption. - * @throws IOException + * @throws java.io.IOException * a loose object or pack file could not be read. */ public boolean next() throws MissingObjectException, @@ -871,8 +908,6 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { * iterators to manage only one list of items, with the diving handled by * recursive trees. * - * @param <T> - * type of the tree iterator expected by the caller. * @param nth * tree to obtain the current iterator of. * @param clazz @@ -888,11 +923,13 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { } /** - * Obtain the raw {@link FileMode} bits for the current entry. + * Obtain the raw {@link org.eclipse.jgit.lib.FileMode} bits for the current + * entry. * <p> * Every added tree supplies mode bits, even if the tree does not contain - * the current entry. In the latter case {@link FileMode#MISSING}'s mode - * bits (0) are returned. + * the current entry. In the latter case + * {@link org.eclipse.jgit.lib.FileMode#MISSING}'s mode bits (0) are + * returned. * * @param nth * tree to obtain the mode bits from. @@ -905,10 +942,11 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { } /** - * Obtain the {@link FileMode} for the current entry. + * Obtain the {@link org.eclipse.jgit.lib.FileMode} for the current entry. * <p> * Every added tree supplies a mode, even if the tree does not contain the - * current entry. In the latter case {@link FileMode#MISSING} is returned. + * current entry. In the latter case + * {@link org.eclipse.jgit.lib.FileMode#MISSING} is returned. * * @param nth * tree to obtain the mode from. @@ -919,7 +957,8 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { } /** - * Obtain the {@link FileMode} for the current entry on the currentHead tree + * Obtain the {@link org.eclipse.jgit.lib.FileMode} for the current entry on + * the currentHead tree * * @return mode for the current entry of the currentHead tree. * @since 4.3 @@ -937,13 +976,16 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { * whenever possible. * <p> * Every tree supplies an object id, even if the tree does not contain the - * current entry. In the latter case {@link ObjectId#zeroId()} is returned. + * current entry. In the latter case + * {@link org.eclipse.jgit.lib.ObjectId#zeroId()} is returned. * * @param nth * tree to obtain the object identifier from. * @return object identifier for the current tree entry. * @see #getObjectId(MutableObjectId, int) * @see #idEqual(int, int) + * @see #getObjectId(MutableObjectId, int) + * @see #idEqual(int, int) */ public ObjectId getObjectId(final int nth) { final AbstractTreeIterator t = trees[nth]; @@ -955,7 +997,8 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { * Obtain the ObjectId for the current entry. * <p> * Every tree supplies an object id, even if the tree does not contain the - * current entry. In the latter case {@link ObjectId#zeroId()} is supplied. + * current entry. In the latter case + * {@link org.eclipse.jgit.lib.ObjectId#zeroId()} is supplied. * <p> * Applications should try to use {@link #idEqual(int, int)} when possible * as it avoids conversion overheads. @@ -1053,6 +1096,8 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { } /** + * Get the path length of the current entry. + * * @return The path length of the current entry. */ public int getPathLength() { @@ -1241,17 +1286,17 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { * If the current entry is a subtree this method arranges for its children * to be returned before the next sibling following the subtree is returned. * - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * a subtree was found, but the subtree object does not exist in * this repository. The repository may be missing objects. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * a subtree was found, and the subtree id does not denote a * tree, but instead names some other non-tree type of object. * The repository may have data corruption. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * the contents of a tree did not appear to be a tree. The * repository may have data corruption. - * @throws IOException + * @throws java.io.IOException * a loose object or pack file could not be read. */ public void enterSubtree() throws MissingObjectException, @@ -1357,10 +1402,14 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { } /** + * Get the tree of that type. + * * @param type * of the tree to be queried - * @return the tree of that type or null if none is present + * @return the tree of that type or null if none is present. * @since 4.3 + * @param <T> + * a tree type. */ public <T extends AbstractTreeIterator> T getTree( Class<T> type) { @@ -1381,7 +1430,7 @@ public class TreeWalk implements AutoCloseable, AttributesProvider { * which type of filterCommand should be executed. E.g. "clean", * "smudge" * @return a filter command - * @throws IOException + * @throws java.io.IOException * @since 4.2 */ public String getFilterCommand(String filterCommandType) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/WorkingTreeIterator.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/WorkingTreeIterator.java index b1b146c854..8d02f90ed1 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/WorkingTreeIterator.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/WorkingTreeIterator.java @@ -67,7 +67,6 @@ import org.eclipse.jgit.attributes.AttributesRule; import org.eclipse.jgit.attributes.FilterCommand; import org.eclipse.jgit.attributes.FilterCommandRegistry; import org.eclipse.jgit.diff.RawText; -import org.eclipse.jgit.dircache.DirCache; import org.eclipse.jgit.dircache.DirCacheEntry; import org.eclipse.jgit.dircache.DirCacheIterator; import org.eclipse.jgit.errors.CorruptObjectException; @@ -101,13 +100,15 @@ import org.eclipse.jgit.util.io.EolStreamTypeUtil; import org.eclipse.jgit.util.sha1.SHA1; /** - * Walks a working directory tree as part of a {@link TreeWalk}. + * Walks a working directory tree as part of a + * {@link org.eclipse.jgit.treewalk.TreeWalk}. * <p> * Most applications will want to use the standard implementation of this - * iterator, {@link FileTreeIterator}, as that does all IO through the standard - * <code>java.io</code> package. Plugins for a Java based IDE may however wish - * to create their own implementations of this class to allow traversal of the - * IDE's project space, as well as benefit from any caching the IDE may have. + * iterator, {@link org.eclipse.jgit.treewalk.FileTreeIterator}, as that does + * all IO through the standard <code>java.io</code> package. Plugins for a Java + * based IDE may however wish to create their own implementations of this class + * to allow traversal of the IDE's project space, as well as benefit from any + * caching the IDE may have. * * @see FileTreeIterator */ @@ -234,7 +235,8 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { } /** - * Define the matching {@link DirCacheIterator}, to optimize ObjectIds. + * Define the matching {@link org.eclipse.jgit.dircache.DirCacheIterator}, + * to optimize ObjectIds. * * Once the DirCacheIterator has been set this iterator must only be * advanced by the TreeWalk that is supplied, as it assumes that itself and @@ -244,13 +246,15 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { * @param walk * the walk that will be advancing this iterator. * @param treeId - * index of the matching {@link DirCacheIterator}. + * index of the matching + * {@link org.eclipse.jgit.dircache.DirCacheIterator}. */ public void setDirCacheIterator(TreeWalk walk, int treeId) { state.walk = walk; state.dirCacheTree = treeId; } + /** {@inheritDoc} */ @Override public boolean hasId() { if (contentIdFromPtr == ptr) @@ -258,6 +262,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { return (mode & FileMode.TYPE_MASK) == FileMode.TYPE_FILE; } + /** {@inheritDoc} */ @Override public byte[] idBuffer() { if (contentIdFromPtr == ptr) @@ -295,6 +300,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { return zeroid; } + /** {@inheritDoc} */ @Override public boolean isWorkTree() { return true; @@ -304,6 +310,8 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { * Get submodule id for given entry. * * @param e + * a {@link org.eclipse.jgit.treewalk.WorkingTreeIterator.Entry} + * object. * @return non-null submodule id */ protected byte[] idSubmodule(Entry e) { @@ -323,14 +331,18 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { * relative to the directory. * * @param directory + * a {@link java.io.File} object. * @param e + * a {@link org.eclipse.jgit.treewalk.WorkingTreeIterator.Entry} + * object. * @return non-null submodule id */ protected byte[] idSubmodule(File directory, Entry e) { final Repository submoduleRepo; try { submoduleRepo = SubmoduleWalk.getSubmoduleRepository(directory, - e.getName()); + e.getName(), + repository != null ? repository.getFS() : FS.DETECTED); } catch (IOException exception) { return zeroid; } @@ -504,11 +516,13 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { return state.options; } + /** {@inheritDoc} */ @Override public int idOffset() { return contentIdOffset; } + /** {@inheritDoc} */ @Override public void reset() { if (!first()) { @@ -518,16 +532,19 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { } } + /** {@inheritDoc} */ @Override public boolean first() { return ptr == 0; } + /** {@inheritDoc} */ @Override public boolean eof() { return ptr == entryCnt; } + /** {@inheritDoc} */ @Override public void next(final int delta) throws CorruptObjectException { ptr += delta; @@ -536,6 +553,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { } } + /** {@inheritDoc} */ @Override public void back(final int delta) throws CorruptObjectException { ptr -= delta; @@ -568,7 +586,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { * Get the filtered input length of this entry * * @return size of the content, in bytes - * @throws IOException + * @throws java.io.IOException */ public long getEntryContentLength() throws IOException { if (canonLen == -1) { @@ -610,7 +628,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { * The caller will close the stream once complete. * * @return a stream to read from the file. - * @throws IOException + * @throws java.io.IOException * the file could not be opened for reading. */ public InputStream openEntryStream() throws IOException { @@ -626,7 +644,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { * Determine if the current entry path is ignored by an ignore rule. * * @return true if the entry was ignored by an ignore rule file. - * @throws IOException + * @throws java.io.IOException * a relevant ignore rule file exists but cannot be read. */ public boolean isEntryIgnored() throws IOException { @@ -639,7 +657,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { * @param pLen * the length of the path in the path buffer. * @return true if the entry is ignored by an ignore rule. - * @throws IOException + * @throws java.io.IOException * a relevant ignore rule file exists but cannot be read. */ protected boolean isEntryIgnored(final int pLen) throws IOException { @@ -700,12 +718,12 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { } /** - * Retrieves the {@link AttributesNode} for the current entry. + * Retrieves the {@link org.eclipse.jgit.attributes.AttributesNode} for the + * current entry. * - * @return {@link AttributesNode} for the current entry. + * @return the {@link org.eclipse.jgit.attributes.AttributesNode} for the + * current entry. * @throws IOException - * if an error is raised while parsing the .gitattributes file - * @since 3.7 */ public AttributesNode getEntryAttributesNode() throws IOException { if (attributesNode instanceof PerDirectoryAttributesNode) @@ -809,6 +827,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { * Is the file mode of the current entry different than the given raw mode? * * @param rawMode + * an int. * @return true if different, false otherwise */ public boolean isModeDifferent(final int rawMode) { @@ -835,12 +854,14 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { /** * Compare the metadata (mode, length, modification-timestamp) of the - * current entry and a {@link DirCacheEntry} + * current entry and a {@link org.eclipse.jgit.dircache.DirCacheEntry} * * @param entry - * the {@link DirCacheEntry} to compare with - * @return a {@link MetadataDiff} which tells whether and how the entries - * metadata differ + * the {@link org.eclipse.jgit.dircache.DirCacheEntry} to compare + * with + * @return a + * {@link org.eclipse.jgit.treewalk.WorkingTreeIterator.MetadataDiff} + * which tells whether and how the entries metadata differ */ public MetadataDiff compareMetadata(DirCacheEntry entry) { if (entry.isAssumeValid()) @@ -890,7 +911,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { /** * Checks whether this entry differs from a given entry from the - * {@link DirCache}. + * {@link org.eclipse.jgit.dircache.DirCache}. * * File status information is used and if status is same we consider the * file identical to the state in the working directory. Native git uses @@ -904,7 +925,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { * @param reader * access to repository objects if necessary. Should not be null. * @return true if content is most likely different. - * @throws IOException + * @throws java.io.IOException * @since 3.3 */ public boolean isModified(DirCacheEntry entry, boolean forceContentCheck, @@ -945,9 +966,10 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { * in the index. * * @param indexIter - * {@link DirCacheIterator} positioned at the same entry as this - * iterator or null if no {@link DirCacheIterator} is available - * at this iterator's current entry + * {@link org.eclipse.jgit.dircache.DirCacheIterator} positioned + * at the same entry as this iterator or null if no + * {@link org.eclipse.jgit.dircache.DirCacheIterator} is + * available at this iterator's current entry * @return index file mode */ public FileMode getIndexFileMode(final DirCacheIterator indexIter) { @@ -1067,7 +1089,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { * @param entry * to read * @return the entry's content as a normalized string - * @throws IOException + * @throws java.io.IOException * if the entry cannot be read or does not denote a symlink * @since 4.6 */ @@ -1351,9 +1373,11 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { } /** + * Get the clean filter command for the current entry. + * * @return the clean filter command for the current entry or * <code>null</code> if no such command is defined - * @throws IOException + * @throws java.io.IOException * @since 4.2 */ public String getCleanFilterCommand() throws IOException { @@ -1369,11 +1393,13 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { } /** + * Get the eol stream type for the current entry. + * * @return the eol stream type for the current entry or <code>null</code> if * it cannot be determined. When state or state.walk is null or the - * {@link TreeWalk} is not based on a {@link Repository} then null - * is returned. - * @throws IOException + * {@link org.eclipse.jgit.treewalk.TreeWalk} is not based on a + * {@link org.eclipse.jgit.lib.Repository} then null is returned. + * @throws java.io.IOException * @since 4.3 */ public EolStreamType getEolStreamType() throws IOException { @@ -1394,11 +1420,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator { if (eolStreamTypeHolder == null) { EolStreamType type=null; if (state.walk != null) { - if (opType != null) { - type = state.walk.getEolStreamType(opType); - } else { - type=state.walk.getEolStreamType(); - } + type = state.walk.getEolStreamType(opType); } else { switch (getOptions().getAutoCRLF()) { case FALSE: diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/WorkingTreeOptions.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/WorkingTreeOptions.java index 2b18904a5f..2dfb2033d0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/WorkingTreeOptions.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/WorkingTreeOptions.java @@ -52,7 +52,9 @@ import org.eclipse.jgit.lib.CoreConfig.EOL; import org.eclipse.jgit.lib.CoreConfig.HideDotFiles; import org.eclipse.jgit.lib.CoreConfig.SymLinks; -/** Options used by the {@link WorkingTreeIterator}. */ +/** + * Options used by the {@link org.eclipse.jgit.treewalk.WorkingTreeIterator}. + */ public class WorkingTreeOptions { /** Key for {@link Config#get(SectionParser)}. */ public static final Config.SectionParser<WorkingTreeOptions> KEY = @@ -92,18 +94,29 @@ public class WorkingTreeOptions { } /** @return true if the execute bit on working files should be trusted. */ + /** + * Whether the execute bit on working files should be trusted. + * + * @return {@code true} if the execute bit on working files should be + * trusted. + */ public boolean isFileMode() { return fileMode; } - /** @return how automatic CRLF conversion has been configured. */ + /** + * Get automatic CRLF conversion configuration. + * + * @return how automatic CRLF conversion has been configured. + */ public AutoCRLF getAutoCRLF() { return autoCRLF; } /** - * @return how text line endings should be normalized. + * Get how text line endings should be normalized. * + * @return how text line endings should be normalized. * @since 4.3 */ public EOL getEOL() { @@ -111,7 +124,9 @@ public class WorkingTreeOptions { } /** - * @return how stat data is compared + * Get how stat data is compared. + * + * @return how stat data is compared. * @since 3.0 */ public CheckStat getCheckStat() { @@ -119,6 +134,8 @@ public class WorkingTreeOptions { } /** + * Get how we handle symbolic links + * * @return how we handle symbolic links * @since 3.3 */ @@ -127,6 +144,8 @@ public class WorkingTreeOptions { } /** + * Get how we create '.'-files (on Windows) + * * @return how we create '.'-files (on Windows) * @since 3.5 */ @@ -135,9 +154,10 @@ public class WorkingTreeOptions { } /** - * @return whether or not we treat nested repos as directories. - * If true, folders containing .git entries will not be - * treated as gitlinks. + * Whether or not we treat nested repos as directories. + * + * @return whether or not we treat nested repos as directories. If true, + * folders containing .git entries will not be treated as gitlinks. * @since 4.3 */ public boolean isDirNoGitLinks() { return dirNoGitLinks; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/AndTreeFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/AndTreeFilter.java index 9658166a85..6d40a4eb51 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/AndTreeFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/AndTreeFilter.java @@ -56,9 +56,10 @@ import org.eclipse.jgit.treewalk.TreeWalk; * Includes a tree entry only if all subfilters include the same tree entry. * <p> * Classic shortcut behavior is used, so evaluation of the - * {@link TreeFilter#include(TreeWalk)} method stops as soon as a false result - * is obtained. Applications can improve filtering performance by placing faster - * filters that are more likely to reject a result earlier in the list. + * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#include(TreeWalk)} method + * stops as soon as a false result is obtained. Applications can improve + * filtering performance by placing faster filters that are more likely to + * reject a result earlier in the list. */ public abstract class AndTreeFilter extends TreeFilter { /** diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/ByteArraySet.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/ByteArraySet.java index 91251e4d2d..653786b7ae 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/ByteArraySet.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/ByteArraySet.java @@ -213,6 +213,7 @@ class ByteArraySet { table = new byte[sz][]; } + /** {@inheritDoc} */ @Override public String toString() { StringBuilder sb = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/IndexDiffFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/IndexDiffFilter.java index b821a16471..6cca582b3b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/IndexDiffFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/IndexDiffFilter.java @@ -58,26 +58,33 @@ import org.eclipse.jgit.treewalk.TreeWalk; import org.eclipse.jgit.treewalk.WorkingTreeIterator; /** - * A performance optimized variant of {@link TreeFilter#ANY_DIFF} which should - * be used when among the walked trees there is a {@link DirCacheIterator} and a - * {@link WorkingTreeIterator}. Please see the documentation of - * {@link TreeFilter#ANY_DIFF} for a basic description of the semantics. + * A performance optimized variant of + * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#ANY_DIFF} which should be + * used when among the walked trees there is a + * {@link org.eclipse.jgit.dircache.DirCacheIterator} and a + * {@link org.eclipse.jgit.treewalk.WorkingTreeIterator}. Please see the + * documentation of {@link org.eclipse.jgit.treewalk.filter.TreeFilter#ANY_DIFF} + * for a basic description of the semantics. * <p> * This filter tries to avoid computing content ids of the files in the - * working-tree. In contrast to {@link TreeFilter#ANY_DIFF} this filter takes - * care to first compare the entry from the {@link DirCacheIterator} with the - * entries from all other iterators besides the {@link WorkingTreeIterator}. - * Since all those entries have fast access to content ids that is very fast. If - * a difference is detected in this step this filter decides to include that - * path before even looking at the working-tree entry. + * working-tree. In contrast to + * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#ANY_DIFF} this filter + * takes care to first compare the entry from the + * {@link org.eclipse.jgit.dircache.DirCacheIterator} with the entries from all + * other iterators besides the + * {@link org.eclipse.jgit.treewalk.WorkingTreeIterator}. Since all those + * entries have fast access to content ids that is very fast. If a difference is + * detected in this step this filter decides to include that path before even + * looking at the working-tree entry. * <p> * If no difference is found then we have to compare index and working-tree as * the last step. By making use of - * {@link WorkingTreeIterator#isModified(org.eclipse.jgit.dircache.DirCacheEntry, boolean, ObjectReader)} + * {@link org.eclipse.jgit.treewalk.WorkingTreeIterator#isModified(org.eclipse.jgit.dircache.DirCacheEntry, boolean, ObjectReader)} * we can avoid the computation of the content id if the file is not dirty. * <p> - * Instances of this filter should not be used for multiple {@link TreeWalk}s. - * Always construct a new instance of this filter for each TreeWalk. + * Instances of this filter should not be used for multiple + * {@link org.eclipse.jgit.treewalk.TreeWalk}s. Always construct a new instance + * of this filter for each TreeWalk. */ public class IndexDiffFilter extends TreeFilter { private final int dirCache; @@ -97,11 +104,13 @@ public class IndexDiffFilter extends TreeFilter { * filter in multiple treewalks. * * @param dirCacheIndex - * the index of the {@link DirCacheIterator} in the associated - * treewalk + * the index of the + * {@link org.eclipse.jgit.dircache.DirCacheIterator} in the + * associated treewalk * @param workingTreeIndex - * the index of the {@link WorkingTreeIterator} in the associated - * treewalk + * the index of the + * {@link org.eclipse.jgit.treewalk.WorkingTreeIterator} in the + * associated treewalk */ public IndexDiffFilter(int dirCacheIndex, int workingTreeIndex) { this(dirCacheIndex, workingTreeIndex, true /* honor ignores */); @@ -112,14 +121,16 @@ public class IndexDiffFilter extends TreeFilter { * filter in multiple treewalks. * * @param dirCacheIndex - * the index of the {@link DirCacheIterator} in the associated - * treewalk + * the index of the + * {@link org.eclipse.jgit.dircache.DirCacheIterator} in the + * associated treewalk * @param workingTreeIndex - * the index of the {@link WorkingTreeIterator} in the associated - * treewalk + * the index of the + * {@link org.eclipse.jgit.treewalk.WorkingTreeIterator} in the + * associated treewalk * @param honorIgnores * true if the filter should skip working tree files that are - * declared as ignored by the standard exclude mechanisms.. + * declared as ignored by the standard exclude mechanisms. */ public IndexDiffFilter(int dirCacheIndex, int workingTreeIndex, boolean honorIgnores) { @@ -128,6 +139,7 @@ public class IndexDiffFilter extends TreeFilter { this.honorIgnores = honorIgnores; } + /** {@inheritDoc} */ @Override public boolean include(TreeWalk tw) throws MissingObjectException, IncorrectObjectTypeException, IOException { @@ -255,6 +267,7 @@ public class IndexDiffFilter extends TreeFilter { return tw.getTree(workingTree, WorkingTreeIterator.class); } + /** {@inheritDoc} */ @Override public boolean shouldBeRecursive() { // We cannot compare subtrees in the working tree, so encourage @@ -262,11 +275,13 @@ public class IndexDiffFilter extends TreeFilter { return true; } + /** {@inheritDoc} */ @Override public TreeFilter clone() { return this; } + /** {@inheritDoc} */ @Override public String toString() { return "INDEX_DIFF_FILTER"; //$NON-NLS-1$ @@ -286,9 +301,11 @@ public class IndexDiffFilter extends TreeFilter { } /** + * <p>Getter for the field <code>untrackedFolders</code>.</p> + * * @return all paths of folders which contain only untracked files/folders. * If on the associated treewalk postorder traversal was turned on - * (see {@link TreeWalk#setPostOrderTraversal(boolean)}) then an + * (see {@link org.eclipse.jgit.treewalk.TreeWalk#setPostOrderTraversal(boolean)}) then an * empty list will be returned. */ public List<String> getUntrackedFolders() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/InterIndexDiffFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/InterIndexDiffFilter.java index 2ea8228b9a..81b8e6d148 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/InterIndexDiffFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/InterIndexDiffFilter.java @@ -49,8 +49,9 @@ import org.eclipse.jgit.treewalk.TreeWalk; /** * A filter for extracting changes between two versions of the dircache. In - * addition to what {@link TreeFilter#ANY_DIFF} would do, it also detects - * changes that will affect decorations and show up in an attempt to commit. + * addition to what {@link org.eclipse.jgit.treewalk.filter.TreeFilter#ANY_DIFF} + * would do, it also detects changes that will affect decorations and show up in + * an attempt to commit. */ public final class InterIndexDiffFilter extends TreeFilter { private static final int baseTree = 0; @@ -60,6 +61,7 @@ public final class InterIndexDiffFilter extends TreeFilter { */ public static final TreeFilter INSTANCE = new InterIndexDiffFilter(); + /** {@inheritDoc} */ @Override public boolean include(final TreeWalk walker) { final int n = walker.getTreeCount(); @@ -88,16 +90,19 @@ public final class InterIndexDiffFilter extends TreeFilter { return false; } + /** {@inheritDoc} */ @Override public boolean shouldBeRecursive() { return false; } + /** {@inheritDoc} */ @Override public TreeFilter clone() { return this; } + /** {@inheritDoc} */ @Override public String toString() { return "INTERINDEX_DIFF"; //$NON-NLS-1$ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/NotIgnoredFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/NotIgnoredFilter.java index 7f30cc7d08..3403c78578 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/NotIgnoredFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/NotIgnoredFilter.java @@ -50,7 +50,8 @@ import org.eclipse.jgit.treewalk.TreeWalk; import org.eclipse.jgit.treewalk.WorkingTreeIterator; /** - * Skip {@link WorkingTreeIterator} entries that appear in gitignore files. + * Skip {@link org.eclipse.jgit.treewalk.WorkingTreeIterator} entries that + * appear in gitignore files. */ public class NotIgnoredFilter extends TreeFilter { private final int index; @@ -65,6 +66,7 @@ public class NotIgnoredFilter extends TreeFilter { this.index = workdirTreeIndex; } + /** {@inheritDoc} */ @Override public boolean include(TreeWalk tw) throws MissingObjectException, IncorrectObjectTypeException, IOException { @@ -72,17 +74,20 @@ public class NotIgnoredFilter extends TreeFilter { return i == null || !i.isEntryIgnored(); } + /** {@inheritDoc} */ @Override public boolean shouldBeRecursive() { return false; } + /** {@inheritDoc} */ @Override public TreeFilter clone() { // immutable return this; } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/NotTreeFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/NotTreeFilter.java index 80c0b87e1c..2e023d0698 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/NotTreeFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/NotTreeFilter.java @@ -50,7 +50,9 @@ import org.eclipse.jgit.errors.IncorrectObjectTypeException; import org.eclipse.jgit.errors.MissingObjectException; import org.eclipse.jgit.treewalk.TreeWalk; -/** Includes an entry only if the subfilter does not include the entry. */ +/** + * Includes an entry only if the subfilter does not include the entry. + */ public class NotTreeFilter extends TreeFilter { /** * Create a filter that negates the result of another filter. @@ -69,11 +71,13 @@ public class NotTreeFilter extends TreeFilter { a = one; } + /** {@inheritDoc} */ @Override public TreeFilter negate() { return a; } + /** {@inheritDoc} */ @Override public boolean include(final TreeWalk walker) throws MissingObjectException, IncorrectObjectTypeException, @@ -81,6 +85,7 @@ public class NotTreeFilter extends TreeFilter { return matchFilter(walker) == 0; } + /** {@inheritDoc} */ @Override public int matchFilter(TreeWalk walker) throws MissingObjectException, IncorrectObjectTypeException, @@ -97,17 +102,20 @@ public class NotTreeFilter extends TreeFilter { return -1; } + /** {@inheritDoc} */ @Override public boolean shouldBeRecursive() { return a.shouldBeRecursive(); } + /** {@inheritDoc} */ @Override public TreeFilter clone() { final TreeFilter n = a.clone(); return n == a ? this : new NotTreeFilter(n); } + /** {@inheritDoc} */ @Override public String toString() { return "NOT " + a.toString(); //$NON-NLS-1$ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/OrTreeFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/OrTreeFilter.java index 2c1a9d4388..dbb062b973 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/OrTreeFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/OrTreeFilter.java @@ -56,9 +56,10 @@ import org.eclipse.jgit.treewalk.TreeWalk; * Includes a tree entry if any subfilters include the same tree entry. * <p> * Classic shortcut behavior is used, so evaluation of the - * {@link TreeFilter#include(TreeWalk)} method stops as soon as a true result is - * obtained. Applications can improve filtering performance by placing faster - * filters that are more likely to accept a result earlier in the list. + * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#include(TreeWalk)} method + * stops as soon as a true result is obtained. Applications can improve + * filtering performance by placing faster filters that are more likely to + * accept a result earlier in the list. */ public abstract class OrTreeFilter extends TreeFilter { /** diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/PathFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/PathFilter.java index 445ba157ea..2f7f5cdc57 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/PathFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/PathFilter.java @@ -51,9 +51,10 @@ import org.eclipse.jgit.treewalk.TreeWalk; /** * Includes tree entries only if they match the configured path. * <p> - * Applications should use {@link PathFilterGroup} to connect these into a tree - * filter graph, as the group supports breaking out of traversal once it is - * known the path can never match. + * Applications should use + * {@link org.eclipse.jgit.treewalk.filter.PathFilterGroup} to connect these + * into a tree filter graph, as the group supports breaking out of traversal + * once it is known the path can never match. */ public class PathFilter extends TreeFilter { /** @@ -70,7 +71,7 @@ public class PathFilter extends TreeFilter { * trailing '/' characters will be trimmed before string's length * is checked or is used as part of the constructed filter. * @return a new filter for the requested path. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * the path supplied was the empty string. */ public static PathFilter create(String path) { @@ -90,21 +91,28 @@ public class PathFilter extends TreeFilter { pathRaw = Constants.encode(pathStr); } - /** @return the path this filter matches. */ + /** + * Get the path this filter matches. + * + * @return the path this filter matches. + */ public String getPath() { return pathStr; } + /** {@inheritDoc} */ @Override public boolean include(final TreeWalk walker) { return matchFilter(walker) <= 0; } + /** {@inheritDoc} */ @Override public int matchFilter(final TreeWalk walker) { return walker.isPathMatch(pathRaw, pathRaw.length); } + /** {@inheritDoc} */ @Override public boolean shouldBeRecursive() { for (final byte b : pathRaw) @@ -113,11 +121,13 @@ public class PathFilter extends TreeFilter { return false; } + /** {@inheritDoc} */ @Override public PathFilter clone() { return this; } + /** {@inheritDoc} */ @Override @SuppressWarnings("nls") public String toString() { @@ -125,6 +135,9 @@ public class PathFilter extends TreeFilter { } /** + * Whether the path length of this filter matches the length of the current + * path of the supplied TreeWalk. + * * @param walker * The walk to check against. * @return {@code true} if the path length of this filter matches the length diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/PathFilterGroup.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/PathFilterGroup.java index 174a4f5b06..0652288b63 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/PathFilterGroup.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/PathFilterGroup.java @@ -55,10 +55,11 @@ import org.eclipse.jgit.util.RawParseUtils; /** * Includes tree entries only if they match one or more configured paths. * <p> - * Operates like {@link PathFilter} but causes the walk to abort as soon as the - * tree can no longer match any of the paths within the group. This may bypass - * the boolean logic of a higher level AND or OR group, but does improve - * performance for the common case of examining one or more modified paths. + * Operates like {@link org.eclipse.jgit.treewalk.filter.PathFilter} but causes + * the walk to abort as soon as the tree can no longer match any of the paths + * within the group. This may bypass the boolean logic of a higher level AND or + * OR group, but does improve performance for the common case of examining one + * or more modified paths. * <p> * This filter is effectively an OR group around paths, with the early abort * feature described above. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/PathSuffixFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/PathSuffixFilter.java index f54cbeae21..553e6bdd63 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/PathSuffixFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/PathSuffixFilter.java @@ -59,8 +59,8 @@ import org.eclipse.jgit.treewalk.TreeWalk; * paths ending in <code>.txt</code>. * <p> * Using this filter is recommended instead of filtering the entries using - * {@link TreeWalk#getPathString()} and <code>endsWith</code> or some other type - * of string match function. + * {@link org.eclipse.jgit.treewalk.TreeWalk#getPathString()} and + * <code>endsWith</code> or some other type of string match function. */ public class PathSuffixFilter extends TreeFilter { @@ -72,7 +72,7 @@ public class PathSuffixFilter extends TreeFilter { * @param path * the path suffix to filter on. Must not be the empty string. * @return a new filter for the requested path. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * the path supplied was the empty string. */ public static PathSuffixFilter create(String path) { @@ -89,11 +89,13 @@ public class PathSuffixFilter extends TreeFilter { pathRaw = Constants.encode(pathStr); } + /** {@inheritDoc} */ @Override public TreeFilter clone() { return this; } + /** {@inheritDoc} */ @Override public boolean include(TreeWalk walker) throws MissingObjectException, IncorrectObjectTypeException, IOException { @@ -104,6 +106,7 @@ public class PathSuffixFilter extends TreeFilter { } + /** {@inheritDoc} */ @Override public boolean shouldBeRecursive() { return true; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/SkipWorkTreeFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/SkipWorkTreeFilter.java index e6bedfd43e..b52d2bd718 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/SkipWorkTreeFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/SkipWorkTreeFilter.java @@ -69,6 +69,7 @@ public class SkipWorkTreeFilter extends TreeFilter { this.treeIdx = treeIdx; } + /** {@inheritDoc} */ @Override public boolean include(TreeWalk walker) { DirCacheIterator i = walker.getTree(treeIdx, DirCacheIterator.class); @@ -79,16 +80,19 @@ public class SkipWorkTreeFilter extends TreeFilter { return e == null || !e.isSkipWorkTree(); } + /** {@inheritDoc} */ @Override public boolean shouldBeRecursive() { return false; } + /** {@inheritDoc} */ @Override public TreeFilter clone() { return this; } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/TreeFilter.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/TreeFilter.java index 2c2fb47463..f0a76324b2 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/TreeFilter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/TreeFilter.java @@ -67,7 +67,8 @@ import org.eclipse.jgit.treewalk.WorkingTreeIterator; * <p> * <b>Path filters:</b> * <ul> - * <li>Matching pathname: {@link PathFilter}</li> + * <li>Matching pathname: + * {@link org.eclipse.jgit.treewalk.filter.PathFilter}</li> * </ul> * * <p> @@ -79,9 +80,9 @@ import org.eclipse.jgit.treewalk.WorkingTreeIterator; * <p> * <b>Boolean modifiers:</b> * <ul> - * <li>AND: {@link AndTreeFilter}</li> - * <li>OR: {@link OrTreeFilter}</li> - * <li>NOT: {@link NotTreeFilter}</li> + * <li>AND: {@link org.eclipse.jgit.treewalk.filter.AndTreeFilter}</li> + * <li>OR: {@link org.eclipse.jgit.treewalk.filter.OrTreeFilter}</li> + * <li>NOT: {@link org.eclipse.jgit.treewalk.filter.NotTreeFilter}</li> * </ul> */ public abstract class TreeFilter { @@ -173,24 +174,25 @@ public abstract class TreeFilter { * Determine if the current entry is interesting to report. * <p> * This method is consulted for subtree entries even if - * {@link TreeWalk#isRecursive()} is enabled. The consultation allows the - * filter to bypass subtree recursion on a case-by-case basis, even when - * recursion is enabled at the application level. + * {@link org.eclipse.jgit.treewalk.TreeWalk#isRecursive()} is enabled. The + * consultation allows the filter to bypass subtree recursion on a + * case-by-case basis, even when recursion is enabled at the application + * level. * * @param walker * the walker the filter needs to examine. * @return true if the current entry should be seen by the application; * false to hide the entry. - * @throws MissingObjectException + * @throws org.eclipse.jgit.errors.MissingObjectException * an object the filter needs to consult to determine its answer * does not exist in the Git repository the walker is operating * on. Filtering this current walker entry is impossible without * the object. - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * an object the filter needed to consult was not of the * expected object type. This usually indicates a corrupt * repository, as an object link is referencing the wrong type. - * @throws IOException + * @throws java.io.IOException * a loose object or pack file could not be read to obtain data * necessary for the filter to make its decision. */ @@ -203,19 +205,19 @@ public abstract class TreeFilter { * <p> * This method extends the result returned by {@link #include(TreeWalk)} * with a third option (-1), splitting the value true. This gives the - * application a possibility to distinguish between an exact match - * and the case when a subtree to the current entry might be a match. + * application a possibility to distinguish between an exact match and the + * case when a subtree to the current entry might be a match. * * @param walker * the walker the filter needs to examine. - * @return -1 if the current entry is a parent of the filter but no - * exact match has been made; 0 if the current entry should - * be seen by the application; 1 if it should be hidden. - * @throws MissingObjectException + * @return -1 if the current entry is a parent of the filter but no exact + * match has been made; 0 if the current entry should be seen by the + * application; 1 if it should be hidden. + * @throws org.eclipse.jgit.errors.MissingObjectException * as thrown by {@link #include(TreeWalk)} - * @throws IncorrectObjectTypeException + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException * as thrown by {@link #include(TreeWalk)} - * @throws IOException + * @throws java.io.IOException * as thrown by {@link #include(TreeWalk)} * @since 4.7 */ @@ -241,16 +243,17 @@ public abstract class TreeFilter { public abstract boolean shouldBeRecursive(); /** + * {@inheritDoc} + * * Clone this tree filter, including its parameters. * <p> * This is a deep clone. If this filter embeds objects or other filters it * must also clone those, to ensure the instances do not share mutable data. - * - * @return another copy of this filter, suitable for another thread. */ @Override public abstract TreeFilter clone(); + /** {@inheritDoc} */ @Override public String toString() { String n = getClass().getName(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/TreeFilterMarker.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/TreeFilterMarker.java index 59515dca52..738ccbd8b7 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/TreeFilterMarker.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/TreeFilterMarker.java @@ -53,8 +53,9 @@ import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.treewalk.TreeWalk; /** - * For testing an array of {@link TreeFilter} during a {@link TreeWalk} for each - * entry and returning the result as a bitmask. + * For testing an array of {@link org.eclipse.jgit.treewalk.filter.TreeFilter} + * during a {@link org.eclipse.jgit.treewalk.TreeWalk} for each entry and + * returning the result as a bitmask. * * @since 2.3 */ @@ -68,8 +69,8 @@ public class TreeFilterMarker { * * @param markTreeFilters * the filters to use for marking, must not have more elements - * than {@link Integer#SIZE}. - * @throws IllegalArgumentException + * than {@link java.lang.Integer#SIZE}. + * @throws java.lang.IllegalArgumentException * if more tree filters are passed than possible */ public TreeFilterMarker(TreeFilter[] markTreeFilters) { @@ -85,19 +86,23 @@ public class TreeFilterMarker { /** * Test the filters against the walk. Returns a bitmask where each bit - * represents the result of a call to {@link TreeFilter#include(TreeWalk)}, + * represents the result of a call to + * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#include(TreeWalk)}, * ordered by the index for which the tree filters were passed in the * constructor. * * @param walk * the walk from which to test the current entry * @return the marks bitmask - * @throws MissingObjectException - * as thrown by {@link TreeFilter#include(TreeWalk)} - * @throws IncorrectObjectTypeException - * as thrown by {@link TreeFilter#include(TreeWalk)} - * @throws IOException - * as thrown by {@link TreeFilter#include(TreeWalk)} + * @throws org.eclipse.jgit.errors.MissingObjectException + * as thrown by + * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#include(TreeWalk)} + * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException + * as thrown by + * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#include(TreeWalk)} + * @throws java.io.IOException + * as thrown by + * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#include(TreeWalk)} */ public int getMarks(TreeWalk walk) throws MissingObjectException, IncorrectObjectTypeException, IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/Base64.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/Base64.java index c05570b851..0c27ced76b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/Base64.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/Base64.java @@ -6,7 +6,8 @@ package org.eclipse.jgit.util; -import java.io.UnsupportedEncodingException; +import static java.nio.charset.StandardCharsets.UTF_8; + import java.nio.charset.StandardCharsets; import java.text.MessageFormat; import java.util.Arrays; @@ -18,14 +19,13 @@ import org.eclipse.jgit.internal.JGitText; * <p> * I am placing this code in the Public Domain. Do with it as you will. This * software comes with no guarantees or warranties but with plenty of - * well-wishing instead! Please visit <a - * href="http://iharder.net/base64">http://iharder.net/base64</a> periodically - * to check for updates or to contribute improvements. + * well-wishing instead! Please visit + * <a href="http://iharder.net/base64">http://iharder.net/base64</a> + * periodically to check for updates or to contribute improvements. * </p> * * @author Robert Harder * @author rob@iharder.net - * @version 2.1, stripped to minimum feature set used by JGit. */ public class Base64 { /** The equals sign (=) as a byte. */ @@ -40,9 +40,6 @@ public class Base64 { /** Indicates an invalid byte during decoding. */ private final static byte INVALID_DEC = -3; - /** Preferred encoding. */ - private final static String UTF_8 = "UTF-8"; //$NON-NLS-1$ - /** The 64 valid Base64 values. */ private final static byte[] ENC; @@ -54,15 +51,11 @@ public class Base64 { private final static byte[] DEC; static { - try { - ENC = ("ABCDEFGHIJKLMNOPQRSTUVWXYZ" // //$NON-NLS-1$ - + "abcdefghijklmnopqrstuvwxyz" // //$NON-NLS-1$ - + "0123456789" // //$NON-NLS-1$ - + "+/" // //$NON-NLS-1$ - ).getBytes(UTF_8); - } catch (UnsupportedEncodingException uee) { - throw new RuntimeException(uee.getMessage(), uee); - } + ENC = ("ABCDEFGHIJKLMNOPQRSTUVWXYZ" // //$NON-NLS-1$ + + "abcdefghijklmnopqrstuvwxyz" // //$NON-NLS-1$ + + "0123456789" // //$NON-NLS-1$ + + "+/" // //$NON-NLS-1$ + ).getBytes(UTF_8); DEC = new byte[128]; Arrays.fill(DEC, INVALID_DEC); @@ -254,7 +247,7 @@ public class Base64 { * @param len * The length of characters to decode * @return decoded data - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * the input is not a valid Base64 sequence. */ public static byte[] decode(byte[] source, int off, int len) { @@ -301,7 +294,7 @@ public class Base64 { * @return the decoded data */ public static byte[] decode(String s) { - byte[] bytes = s.getBytes(StandardCharsets.UTF_8); + byte[] bytes = s.getBytes(UTF_8); return decode(bytes, 0, bytes.length); } } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/BlockList.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/BlockList.java index c86c588acd..c3d474720f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/BlockList.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/BlockList.java @@ -84,7 +84,9 @@ public class BlockList<T> extends AbstractList<T> { private T[] tailBlock; - /** Initialize an empty list. */ + /** + * Initialize an empty list. + */ public BlockList() { directory = BlockList.<T> newDirectory(256); directory[0] = BlockList.<T> newBlock(); @@ -106,11 +108,13 @@ public class BlockList<T> extends AbstractList<T> { tailBlock = directory[0]; } + /** {@inheritDoc} */ @Override public int size() { return size; } + /** {@inheritDoc} */ @Override public void clear() { for (T[] block : directory) { @@ -123,6 +127,7 @@ public class BlockList<T> extends AbstractList<T> { tailBlock = directory[0]; } + /** {@inheritDoc} */ @Override public T get(int index) { if (index < 0 || size <= index) @@ -130,6 +135,7 @@ public class BlockList<T> extends AbstractList<T> { return directory[toDirectoryIndex(index)][toBlockIndex(index)]; } + /** {@inheritDoc} */ @Override public T set(int index, T element) { if (index < 0 || size <= index) @@ -187,6 +193,7 @@ public class BlockList<T> extends AbstractList<T> { } } + /** {@inheritDoc} */ @Override public boolean add(T element) { int i = tailBlkIdx; @@ -217,6 +224,7 @@ public class BlockList<T> extends AbstractList<T> { return true; } + /** {@inheritDoc} */ @Override public void add(int index, T element) { if (index == size) { @@ -238,6 +246,7 @@ public class BlockList<T> extends AbstractList<T> { } } + /** {@inheritDoc} */ @Override public T remove(int index) { if (index == size - 1) { @@ -277,6 +286,7 @@ public class BlockList<T> extends AbstractList<T> { tailBlock = directory[tailDirIdx]; } + /** {@inheritDoc} */ @Override public Iterator<T> iterator() { return new MyIterator(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/CachedAuthenticator.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/CachedAuthenticator.java index 8677c690fb..9915bdf49b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/CachedAuthenticator.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/CachedAuthenticator.java @@ -49,7 +49,9 @@ import java.net.PasswordAuthentication; import java.util.Collection; import java.util.concurrent.CopyOnWriteArrayList; -/** Abstract authenticator which remembers prior authentications. */ +/** + * Abstract authenticator which remembers prior authentications. + */ public abstract class CachedAuthenticator extends Authenticator { private static final Collection<CachedAuthentication> cached = new CopyOnWriteArrayList<>(); @@ -63,6 +65,7 @@ public abstract class CachedAuthenticator extends Authenticator { cached.add(ca); } + /** {@inheritDoc} */ @Override protected final PasswordAuthentication getPasswordAuthentication() { final String host = getRequestingHost(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/ChangeIdUtil.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/ChangeIdUtil.java index f1f6053e3b..c8e6645f57 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/ChangeIdUtil.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/ChangeIdUtil.java @@ -82,9 +82,11 @@ public class ChangeIdUtil { * @param firstParentId * parent id of previous commit or null * @param author - * the {@link PersonIdent} for the presumed author and time + * the {@link org.eclipse.jgit.lib.PersonIdent} for the presumed + * author and time * @param committer - * the {@link PersonIdent} for the presumed committer and time + * the {@link org.eclipse.jgit.lib.PersonIdent} for the presumed + * committer and time * @param message * The commit message * @return the change id SHA1 string (without the 'I') or null if the @@ -138,7 +140,9 @@ public class ChangeIdUtil { * line. * * @param message + * a message. * @param changeId + * a Change-Id. * @return a commit message with an inserted Change-Id line */ public static String insertId(String message, ObjectId changeId) { @@ -148,18 +152,21 @@ public class ChangeIdUtil { /** * Find the right place to insert a Change-Id and return it. * <p> - * If no Change-Id is found the Change-Id is inserted before - * the first footer line but after a Bug line. + * If no Change-Id is found the Change-Id is inserted before the first + * footer line but after a Bug line. * - * If Change-Id is found and replaceExisting is set to false, - * the message is unchanged. + * If Change-Id is found and replaceExisting is set to false, the message is + * unchanged. * - * If Change-Id is found and replaceExisting is set to true, - * the Change-Id is replaced with {@code changeId}. + * If Change-Id is found and replaceExisting is set to true, the Change-Id + * is replaced with {@code changeId}. * * @param message + * a message. * @param changeId + * a Change-Id. * @param replaceExisting + * a boolean. * @return a commit message with an inserted Change-Id line */ public static String insertId(String message, ObjectId changeId, @@ -219,6 +226,7 @@ public class ChangeIdUtil { * only lines matching {@code footerPattern}. * * @param message + * a message. * @param delimiter * the line delimiter, like "\n" or "\r\n", needed to find the * footer diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/FS.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/FS.java index 1f4215eed0..f04a45b8ab 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/FS.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/FS.java @@ -79,8 +79,12 @@ import org.eclipse.jgit.util.ProcessResult.Status; import org.slf4j.Logger; import org.slf4j.LoggerFactory; -/** Abstraction to support various file system operations not in Java. */ +/** + * Abstraction to support various file system operations not in Java. + */ public abstract class FS { + private static final Logger LOG = LoggerFactory.getLogger(FS.class); + /** * This class creates FS instances. It will be overridden by a Java7 variant * if such can be detected in {@link #detect(Boolean)}. @@ -162,8 +166,6 @@ public abstract class FS { } } - private final static Logger LOG = LoggerFactory.getLogger(FS.class); - /** The auto-detected implementation selected for this operating system and JRE. */ public static final FS DETECTED = detect(); @@ -196,7 +198,6 @@ public abstract class FS { * </ul> * * Note: this parameter is only relevant on Windows. - * * @return detected file system abstraction */ public static FS detect(Boolean cygwinUsed) { @@ -228,7 +229,11 @@ public abstract class FS { gitSystemConfig = src.gitSystemConfig; } - /** @return a new instance of the same type of FS. */ + /** + * Create a new instance of the same type of FS. + * + * @return a new instance of the same type of FS. + */ public abstract FS newInstance(); /** @@ -246,8 +251,8 @@ public abstract class FS { * parallel only one will succeed. In such cases both clients may think they * created a new file. * - * @return true if this implementation support atomic creation of new - * Files by {@link File#createNewFile()} + * @return true if this implementation support atomic creation of new Files + * by {@link java.io.File#createNewFile()} * @since 4.5 */ public boolean supportsAtomicCreateNewFile() { @@ -309,8 +314,9 @@ public abstract class FS { * than that of the link target. * * @param f + * a {@link java.io.File} object. * @return last modified time of f - * @throws IOException + * @throws java.io.IOException * @since 3.0 */ public long lastModified(File f) throws IOException { @@ -322,8 +328,10 @@ public abstract class FS { * symbolic links, the link is modified, not the target, * * @param f + * a {@link java.io.File} object. * @param time - * @throws IOException + * last modified time + * @throws java.io.IOException * @since 3.0 */ public void setLastModified(File f, long time) throws IOException { @@ -335,8 +343,9 @@ public abstract class FS { * it's the length of the link, else the length of the target. * * @param path + * a {@link java.io.File} object. * @return length of a file - * @throws IOException + * @throws java.io.IOException * @since 3.0 */ public long length(File path) throws IOException { @@ -347,7 +356,8 @@ public abstract class FS { * Delete a file. Throws an exception if delete fails. * * @param f - * @throws IOException + * a {@link java.io.File} object. + * @throws java.io.IOException * this may be a Java7 subclass with detailed information * @since 3.3 */ @@ -448,7 +458,7 @@ public abstract class FS { * Files to search for in the given path * @return the first match found, or null * @since 3.0 - **/ + */ protected static File searchPath(final String path, final String... lookFor) { if (path == null) return null; @@ -474,7 +484,7 @@ public abstract class FS { * to be used to parse the command's output * @return the one-line output of the command or {@code null} if there is * none - * @throws CommandFailedException + * @throws org.eclipse.jgit.errors.CommandFailedException * thrown when the command failed (return code was non-zero) */ @Nullable @@ -497,7 +507,7 @@ public abstract class FS { * current process * @return the one-line output of the command or {@code null} if there is * none - * @throws CommandFailedException + * @throws org.eclipse.jgit.errors.CommandFailedException * thrown when the command failed (return code was non-zero) * @since 4.0 */ @@ -636,6 +646,8 @@ public abstract class FS { } /** + * Discover the path to the Git executable. + * * @return the path to the Git executable or {@code null} if it cannot be * determined. * @since 4.0 @@ -643,6 +655,8 @@ public abstract class FS { protected abstract File discoverGitExe(); /** + * Discover the path to the system-wide Git configuration file + * * @return the path to the system-wide Git configuration file or * {@code null} if it cannot be determined. * @since 4.0 @@ -690,8 +704,10 @@ public abstract class FS { } /** - * @return the currently used path to the system-wide Git configuration - * file or {@code null} if none has been set. + * Get the currently used path to the system-wide Git configuration file. + * + * @return the currently used path to the system-wide Git configuration file + * or {@code null} if none has been set. * @since 4.0 */ public File getGitSystemConfig() { @@ -715,7 +731,10 @@ public abstract class FS { } /** + * Get the parent directory of this file's parent directory + * * @param grandchild + * a {@link java.io.File} object. * @return the parent directory of this file's parent directory or * {@code null} in case there's no grandparent directory * @since 4.0 @@ -733,8 +752,9 @@ public abstract class FS { * Check if a file is a symbolic link and read it * * @param path + * a {@link java.io.File} object. * @return target of link or null - * @throws IOException + * @throws java.io.IOException * @since 3.0 */ public String readSymLink(File path) throws IOException { @@ -742,9 +762,12 @@ public abstract class FS { } /** + * Whether the path is a symbolic link (and we support these). + * * @param path + * a {@link java.io.File} object. * @return true if the path is a symbolic link (and we support these) - * @throws IOException + * @throws java.io.IOException * @since 3.0 */ public boolean isSymLink(File path) throws IOException { @@ -756,6 +779,7 @@ public abstract class FS { * target does not exist * * @param path + * a {@link java.io.File} object. * @return true if path exists * @since 3.0 */ @@ -768,6 +792,7 @@ public abstract class FS { * path is a symbolic link to a directory, this method returns false. * * @param path + * a {@link java.io.File} object. * @return true if file is a directory, * @since 3.0 */ @@ -780,6 +805,7 @@ public abstract class FS { * symbolic links the test returns false if path represents a symbolic link. * * @param path + * a {@link java.io.File} object. * @return true if path represents a regular file * @since 3.0 */ @@ -788,10 +814,14 @@ public abstract class FS { } /** + * Whether path is hidden, either starts with . on unix or has the hidden + * attribute in windows + * * @param path + * a {@link java.io.File} object. * @return true if path is hidden, either starts with . on unix or has the * hidden attribute in windows - * @throws IOException + * @throws java.io.IOException * @since 3.0 */ public boolean isHidden(File path) throws IOException { @@ -802,8 +832,10 @@ public abstract class FS { * Set the hidden attribute for file whose name starts with a period. * * @param path + * a {@link java.io.File} object. * @param hidden - * @throws IOException + * whether to set the file hidden + * @throws java.io.IOException * @since 3.0 */ public void setHidden(File path, boolean hidden) throws IOException { @@ -814,8 +846,10 @@ public abstract class FS { * Create a symbolic link * * @param path + * a {@link java.io.File} object. * @param target - * @throws IOException + * target path of the symlink + * @throws java.io.IOException * @since 3.0 */ public void createSymLink(File path, String target) throws IOException { @@ -823,9 +857,9 @@ public abstract class FS { } /** - * Create a new file. See {@link File#createNewFile()}. Subclasses of this - * class may take care to provide a safe implementation for this even if - * {@link #supportsAtomicCreateNewFile()} is <code>false</code> + * Create a new file. See {@link java.io.File#createNewFile()}. Subclasses + * of this class may take care to provide a safe implementation for this + * even if {@link #supportsAtomicCreateNewFile()} is <code>false</code> * * @param path * the file to be created @@ -904,7 +938,8 @@ public abstract class FS { } /** - * See {@link FileUtils#relativizePath(String, String, String, boolean)}. + * See + * {@link org.eclipse.jgit.util.FileUtils#relativizePath(String, String, String, boolean)}. * * @param base * The path against which <code>other</code> should be @@ -937,7 +972,7 @@ public abstract class FS { * Arguments to pass to this hook. Cannot be <code>null</code>, * but can be an empty array. * @return The ProcessResult describing this hook's execution. - * @throws JGitInternalException + * @throws org.eclipse.jgit.api.errors.JGitInternalException * if we fail to run the hook somehow. Causes may include an * interrupted process or I/O errors. * @since 4.0 @@ -972,7 +1007,7 @@ public abstract class FS { * A string to pass on to the standard input of the hook. May be * <code>null</code>. * @return The ProcessResult describing this hook's execution. - * @throws JGitInternalException + * @throws org.eclipse.jgit.api.errors.JGitInternalException * if we fail to run the hook somehow. Causes may include an * interrupted process or I/O errors. * @since 4.0 @@ -1008,7 +1043,7 @@ public abstract class FS { * A string to pass on to the standard input of the hook. May be * <code>null</code>. * @return The ProcessResult describing this hook's execution. - * @throws JGitInternalException + * @throws org.eclipse.jgit.api.errors.JGitInternalException * if we fail to run the hook somehow. Causes may include an * interrupted process or I/O errors. * @since 4.0 @@ -1053,8 +1088,8 @@ public abstract class FS { * The repository within which to find a hook. * @param hookName * The name of the hook we're trying to find. - * @return The {@link File} containing this particular hook if it exists in - * the given repository, <code>null</code> otherwise. + * @return The {@link java.io.File} containing this particular hook if it + * exists in the given repository, <code>null</code> otherwise. * @since 4.0 */ public File findHook(Repository repository, final String hookName) { @@ -1084,9 +1119,9 @@ public abstract class FS { * A string to pass on to the standard input of the hook. Can be * <code>null</code>. * @return the exit value of this process. - * @throws IOException + * @throws java.io.IOException * if an I/O error occurs while executing this process. - * @throws InterruptedException + * @throws java.lang.InterruptedException * if the current thread is interrupted while waiting for the * process to end. * @since 4.2 @@ -1120,9 +1155,9 @@ public abstract class FS { * will be consumed by the process. The method will close the * inputstream after all bytes are read. * @return the return code of this process. - * @throws IOException + * @throws java.io.IOException * if an I/O error occurs while executing this process. - * @throws InterruptedException + * @throws java.lang.InterruptedException * if the current thread is interrupted while waiting for the * process to end. * @since 4.2 @@ -1248,15 +1283,15 @@ public abstract class FS { public abstract ProcessBuilder runInShell(String cmd, String[] args); /** - * Execute a command defined by a {@link ProcessBuilder}. + * Execute a command defined by a {@link java.lang.ProcessBuilder}. * * @param pb * The command to be executed * @param in * The standard input stream passed to the process * @return The result of the executed command - * @throws InterruptedException - * @throws IOException + * @throws java.lang.InterruptedException + * @throws java.io.IOException * @since 4.2 */ public ExecutionResult execute(ProcessBuilder pb, InputStream in) @@ -1409,8 +1444,11 @@ public abstract class FS { } /** + * Get the file attributes we care for. + * * @param path - * @return the file attributes we care for + * a {@link java.io.File} object. + * @return the file attributes we care for. * @since 3.3 */ public Attributes getAttributes(File path) { @@ -1430,6 +1468,7 @@ public abstract class FS { * Normalize the unicode path to composed form. * * @param file + * a {@link java.io.File} object. * @return NFC-format File * @since 3.3 */ @@ -1441,6 +1480,7 @@ public abstract class FS { * Normalize the unicode path to composed form. * * @param name + * path name * @return NFC-format string * @since 3.3 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_POSIX.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_POSIX.java index d2200309c0..45237c42be 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_POSIX.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_POSIX.java @@ -85,9 +85,15 @@ public class FS_POSIX extends FS { private volatile boolean supportsUnixNLink = true; - private volatile Boolean supportsAtomicCreateNewFile; + private volatile AtomicFileCreation supportsAtomicCreateNewFile = AtomicFileCreation.UNDEFINED; - /** Default constructor. */ + private enum AtomicFileCreation { + SUPPORTED, NOT_SUPPORTED, UNDEFINED + } + + /** + * Default constructor. + */ protected FS_POSIX() { } @@ -104,34 +110,38 @@ public class FS_POSIX extends FS { } } - @SuppressWarnings("boxing") private void determineAtomicFileCreationSupport() { // @TODO: enhance SystemReader to support this without copying code - Boolean ret = getAtomicFileCreationSupportOption( + AtomicFileCreation ret = getAtomicFileCreationSupportOption( SystemReader.getInstance().openUserConfig(null, this)); - if (ret == null && StringUtils.isEmptyOrNull(SystemReader.getInstance() - .getenv(Constants.GIT_CONFIG_NOSYSTEM_KEY))) { + if (ret == AtomicFileCreation.UNDEFINED + && StringUtils.isEmptyOrNull(SystemReader.getInstance() + .getenv(Constants.GIT_CONFIG_NOSYSTEM_KEY))) { ret = getAtomicFileCreationSupportOption( SystemReader.getInstance().openSystemConfig(null, this)); } - supportsAtomicCreateNewFile = (ret == null) || ret; + supportsAtomicCreateNewFile = ret; } - private Boolean getAtomicFileCreationSupportOption(FileBasedConfig config) { + private AtomicFileCreation getAtomicFileCreationSupportOption( + FileBasedConfig config) { try { config.load(); String value = config.getString(ConfigConstants.CONFIG_CORE_SECTION, null, ConfigConstants.CONFIG_KEY_SUPPORTSATOMICFILECREATION); if (value == null) { - return null; + return AtomicFileCreation.UNDEFINED; } - return Boolean.valueOf(StringUtils.toBoolean(value)); + return StringUtils.toBoolean(value) + ? AtomicFileCreation.SUPPORTED + : AtomicFileCreation.NOT_SUPPORTED; } catch (IOException | ConfigInvalidException e) { - return Boolean.TRUE; + return AtomicFileCreation.SUPPORTED; } } + /** {@inheritDoc} */ @Override public FS newInstance() { return new FS_POSIX(this); @@ -179,6 +189,7 @@ public class FS_POSIX extends FS { } } + /** {@inheritDoc} */ @Override protected File discoverGitExe() { String path = SystemReader.getInstance().getenv("PATH"); //$NON-NLS-1$ @@ -209,21 +220,25 @@ public class FS_POSIX extends FS { return gitExe; } + /** {@inheritDoc} */ @Override public boolean isCaseSensitive() { return !SystemReader.getInstance().isMacOS(); } + /** {@inheritDoc} */ @Override public boolean supportsExecute() { return true; } + /** {@inheritDoc} */ @Override public boolean canExecute(File f) { return FileUtils.canExecute(f); } + /** {@inheritDoc} */ @Override public boolean setExecute(File f, boolean canExecute) { if (!isFile(f)) @@ -232,7 +247,7 @@ public class FS_POSIX extends FS { return f.setExecutable(false, false); try { - Path path = f.toPath(); + Path path = FileUtils.toPath(f); Set<PosixFilePermission> pset = Files.getPosixFilePermissions(path); // owner (user) is always allowed to execute. @@ -264,6 +279,7 @@ public class FS_POSIX extends FS { } } + /** {@inheritDoc} */ @Override public ProcessBuilder runInShell(String cmd, String[] args) { List<String> argv = new ArrayList<>(4 + args.length); @@ -277,9 +293,7 @@ public class FS_POSIX extends FS { return proc; } - /** - * @since 4.0 - */ + /** {@inheritDoc} */ @Override public ProcessResult runHookIfPresent(Repository repository, String hookName, String[] args, PrintStream outRedirect, PrintStream errRedirect, @@ -288,48 +302,43 @@ public class FS_POSIX extends FS { errRedirect, stdinArgs); } + /** {@inheritDoc} */ @Override public boolean retryFailedLockFileCommit() { return false; } + /** {@inheritDoc} */ @Override public boolean supportsSymlinks() { return true; } + /** {@inheritDoc} */ @Override public void setHidden(File path, boolean hidden) throws IOException { // no action on POSIX } - /** - * @since 3.3 - */ + /** {@inheritDoc} */ @Override public Attributes getAttributes(File path) { return FileUtils.getFileAttributesPosix(this, path); } - /** - * @since 3.3 - */ + /** {@inheritDoc} */ @Override public File normalize(File file) { return FileUtils.normalize(file); } - /** - * @since 3.3 - */ + /** {@inheritDoc} */ @Override public String normalize(String name) { return FileUtils.normalize(name); } - /** - * @since 3.7 - */ + /** {@inheritDoc} */ @Override public File findHook(Repository repository, String hookName) { final File gitdir = repository.getDirectory(); @@ -343,24 +352,27 @@ public class FS_POSIX extends FS { return null; } + /** {@inheritDoc} */ @Override public boolean supportsAtomicCreateNewFile() { - if (supportsAtomicCreateNewFile == null) { + if (supportsAtomicCreateNewFile == AtomicFileCreation.UNDEFINED) { determineAtomicFileCreationSupport(); } - return supportsAtomicCreateNewFile.booleanValue(); + return supportsAtomicCreateNewFile == AtomicFileCreation.SUPPORTED; } @Override @SuppressWarnings("boxing") /** + * {@inheritDoc} + * <p> * An implementation of the File#createNewFile() semantics which works also * on NFS. If the config option * {@code core.supportsAtomicCreateNewFile = true} (which is the default) * then simply File#createNewFile() is called. * * But if {@code core.supportsAtomicCreateNewFile = false} then after - * successful creation of the lock file a hardlink to that lock file is + * successful creation of the lock file a hard link to that lock file is * created and the attribute nlink of the lock file is checked to be 2. If * multiple clients manage to create the same lock file nlink would be * greater than 2 showing the error. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_Win32.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_Win32.java index 060292160e..29fe5dc829 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_Win32.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_Win32.java @@ -83,36 +83,43 @@ public class FS_Win32 extends FS { super(src); } + /** {@inheritDoc} */ @Override public FS newInstance() { return new FS_Win32(this); } + /** {@inheritDoc} */ @Override public boolean supportsExecute() { return false; } + /** {@inheritDoc} */ @Override public boolean canExecute(final File f) { return false; } + /** {@inheritDoc} */ @Override public boolean setExecute(final File f, final boolean canExec) { return false; } + /** {@inheritDoc} */ @Override public boolean isCaseSensitive() { return false; } + /** {@inheritDoc} */ @Override public boolean retryFailedLockFileCommit() { return true; } + /** {@inheritDoc} */ @Override protected File discoverGitExe() { String path = SystemReader.getInstance().getenv("PATH"); //$NON-NLS-1$ @@ -141,6 +148,7 @@ public class FS_Win32 extends FS { return gitExe; } + /** {@inheritDoc} */ @Override protected File userHomeImpl() { String home = SystemReader.getInstance().getenv("HOME"); //$NON-NLS-1$ @@ -160,6 +168,7 @@ public class FS_Win32 extends FS { return super.userHomeImpl(); } + /** {@inheritDoc} */ @Override public ProcessBuilder runInShell(String cmd, String[] args) { List<String> argv = new ArrayList<>(3 + args.length); @@ -172,6 +181,7 @@ public class FS_Win32 extends FS { return proc; } + /** {@inheritDoc} */ @Override public boolean supportsSymlinks() { if (supportSymlinks == null) @@ -200,9 +210,7 @@ public class FS_Win32 extends FS { } } - /** - * @since 3.3 - */ + /** {@inheritDoc} */ @Override public Attributes getAttributes(File path) { return FileUtils.getFileAttributesBasic(this, path); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_Win32_Cygwin.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_Win32_Cygwin.java index 545cc0119e..64cdcc300d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_Win32_Cygwin.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/FS_Win32_Cygwin.java @@ -72,6 +72,8 @@ public class FS_Win32_Cygwin extends FS_Win32 { private static String cygpath; /** + * Whether cygwin is found + * * @return true if cygwin is found */ public static boolean isCygwin() { @@ -107,11 +109,13 @@ public class FS_Win32_Cygwin extends FS_Win32 { super(src); } + /** {@inheritDoc} */ @Override public FS newInstance() { return new FS_Win32_Cygwin(this); } + /** {@inheritDoc} */ @Override public File resolve(final File dir, final String pn) { String useCygPath = System.getProperty("jgit.usecygpath"); //$NON-NLS-1$ @@ -132,6 +136,7 @@ public class FS_Win32_Cygwin extends FS_Win32 { return super.resolve(dir, pn); } + /** {@inheritDoc} */ @Override protected File userHomeImpl() { final String home = AccessController @@ -146,6 +151,7 @@ public class FS_Win32_Cygwin extends FS_Win32 { return resolve(new File("."), home); //$NON-NLS-1$ } + /** {@inheritDoc} */ @Override public ProcessBuilder runInShell(String cmd, String[] args) { List<String> argv = new ArrayList<>(4 + args.length); @@ -159,18 +165,14 @@ public class FS_Win32_Cygwin extends FS_Win32 { return proc; } - /** - * @since 3.7 - */ + /** {@inheritDoc} */ @Override public String relativize(String base, String other) { final String relativized = super.relativize(base, other); return relativized.replace(File.separatorChar, '/'); } - /** - * @since 4.0 - */ + /** {@inheritDoc} */ @Override public ProcessResult runHookIfPresent(Repository repository, String hookName, String[] args, PrintStream outRedirect, PrintStream errRedirect, @@ -179,9 +181,7 @@ public class FS_Win32_Cygwin extends FS_Win32 { errRedirect, stdinArgs); } - /** - * @since 3.7 - */ + /** {@inheritDoc} */ @Override public File findHook(Repository repository, String hookName) { final File gitdir = repository.getDirectory(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/FileUtil.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/FileUtil.java index b87b9a41d3..96f21756d5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/FileUtil.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/FileUtil.java @@ -45,7 +45,6 @@ package org.eclipse.jgit.util; import java.io.File; import java.io.IOException; -import java.nio.file.Files; import org.eclipse.jgit.util.FS.Attributes; @@ -56,10 +55,14 @@ import org.eclipse.jgit.util.FS.Attributes; public class FileUtil { /** + * Read target path of a symlink. + * * @param path - * @return target path of the symlink - * @throws IOException - * @deprecated use {@link FileUtils#readSymLink(File)} instead + * a {@link java.io.File}. + * @return target path of the symlink. + * @throws java.io.IOException + * @deprecated use {@link org.eclipse.jgit.util.FileUtils#readSymLink(File)} + * instead */ @Deprecated public static String readSymlink(File path) throws IOException { @@ -67,12 +70,16 @@ public class FileUtil { } /** + * Create a symlink + * * @param path * path of the symlink to be created * @param target * target of the symlink to be created - * @throws IOException - * @deprecated use {@link FileUtils#createSymLink(File, String)} instead + * @throws java.io.IOException + * @deprecated use + * {@link org.eclipse.jgit.util.FileUtils#createSymLink(File, String)} + * instead */ @Deprecated public static void createSymLink(File path, String target) @@ -81,9 +88,14 @@ public class FileUtil { } /** + * Whether the passed file is a symlink + * * @param path + * a {@link java.io.File} object. * @return {@code true} if the passed path is a symlink - * @deprecated Use {@link Files#isSymbolicLink(java.nio.file.Path)} instead + * @deprecated Use + * {@link java.nio.file.Files#isSymbolicLink(java.nio.file.Path)} + * instead */ @Deprecated public static boolean isSymlink(File path) { @@ -91,11 +103,14 @@ public class FileUtil { } /** + * Get lastModified attribute for given path + * * @param path + * a {@link java.io.File}. * @return lastModified attribute for given path - * @throws IOException + * @throws java.io.IOException * @deprecated Use - * {@link Files#getLastModifiedTime(java.nio.file.Path, java.nio.file.LinkOption...)} + * {@link java.nio.file.Files#getLastModifiedTime(java.nio.file.Path, java.nio.file.LinkOption...)} * instead */ @Deprecated @@ -104,11 +119,15 @@ public class FileUtil { } /** + * Set lastModified attribute for given path + * * @param path + * a {@link java.io.File}. * @param time - * @throws IOException + * a long. + * @throws java.io.IOException * @deprecated Use - * {@link Files#setLastModifiedTime(java.nio.file.Path, java.nio.file.attribute.FileTime)} + * {@link java.nio.file.Files#setLastModifiedTime(java.nio.file.Path, java.nio.file.attribute.FileTime)} * instead */ @Deprecated @@ -117,10 +136,13 @@ public class FileUtil { } /** + * Whether this file exists + * * @param path + * a {@link java.io.File}. * @return {@code true} if the given path exists * @deprecated Use - * {@link Files#exists(java.nio.file.Path, java.nio.file.LinkOption...)} + * {@link java.nio.file.Files#exists(java.nio.file.Path, java.nio.file.LinkOption...)} * instead */ @Deprecated @@ -129,10 +151,14 @@ public class FileUtil { } /** + * Whether this file is hidden + * * @param path + * a {@link java.io.File}. * @return {@code true} if the given path is hidden - * @throws IOException - * @deprecated Use {@link Files#isHidden(java.nio.file.Path)} instead + * @throws java.io.IOException + * @deprecated Use {@link java.nio.file.Files#isHidden(java.nio.file.Path)} + * instead */ @Deprecated public static boolean isHidden(File path) throws IOException { @@ -140,10 +166,16 @@ public class FileUtil { } /** + * Set this file hidden + * * @param path + * a {@link java.io.File}. * @param hidden - * @throws IOException - * @deprecated Use {@link FileUtils#setHidden(File,boolean)} instead + * a boolean. + * @throws java.io.IOException + * @deprecated Use + * {@link org.eclipse.jgit.util.FileUtils#setHidden(File,boolean)} + * instead */ @Deprecated public static void setHidden(File path, boolean hidden) throws IOException { @@ -151,10 +183,14 @@ public class FileUtil { } /** + * Get file length + * * @param path + * a {@link java.io.File}. * @return length of the given file - * @throws IOException - * @deprecated Use {@link FileUtils#getLength(File)} instead + * @throws java.io.IOException + * @deprecated Use {@link org.eclipse.jgit.util.FileUtils#getLength(File)} + * instead */ @Deprecated public static long getLength(File path) throws IOException { @@ -162,10 +198,13 @@ public class FileUtil { } /** + * Whether the given File is a directory + * * @param path - * @return {@code true} if the given file a directory + * a {@link java.io.File} object. + * @return {@code true} if the given file is a directory * @deprecated Use - * {@link Files#isDirectory(java.nio.file.Path, java.nio.file.LinkOption...)} + * {@link java.nio.file.Files#isDirectory(java.nio.file.Path, java.nio.file.LinkOption...)} * instead */ @Deprecated @@ -174,10 +213,13 @@ public class FileUtil { } /** + * Whether the given File is a file + * * @param path + * a {@link java.io.File} object. * @return {@code true} if the given file is a file * @deprecated Use - * {@link Files#isRegularFile(java.nio.file.Path, java.nio.file.LinkOption...)} + * {@link java.nio.file.Files#isRegularFile(java.nio.file.Path, java.nio.file.LinkOption...)} * instead */ @Deprecated @@ -186,9 +228,13 @@ public class FileUtil { } /** + * Whether the given file can be executed + * * @param path + * a {@link java.io.File} object. * @return {@code true} if the given file can be executed - * @deprecated Use {@link FileUtils#canExecute(File)} instead + * @deprecated Use {@link org.eclipse.jgit.util.FileUtils#canExecute(File)} + * instead */ @Deprecated public static boolean canExecute(File path) { @@ -196,9 +242,12 @@ public class FileUtil { } /** + * Delete the given file + * * @param path - * @throws IOException - * @deprecated use {@link FileUtils#delete(File)} + * a {@link java.io.File} object. + * @throws java.io.IOException + * @deprecated use {@link org.eclipse.jgit.util.FileUtils#delete(File)} */ @Deprecated public static void delete(File path) throws IOException { @@ -206,10 +255,16 @@ public class FileUtil { } /** + * Get file system attributes for the given file + * * @param fs + * a {@link org.eclipse.jgit.util.FS} object. * @param path + * a {@link java.io.File} object. * @return file system attributes for the given file - * @deprecated Use {@link FileUtils#getFileAttributesPosix(FS,File)} instead + * @deprecated Use + * {@link org.eclipse.jgit.util.FileUtils#getFileAttributesPosix(FS,File)} + * instead */ @Deprecated public static Attributes getFileAttributesPosix(FS fs, File path) { @@ -217,9 +272,14 @@ public class FileUtil { } /** + * NFC normalize File (on Mac), otherwise do nothing + * * @param file - * @return on Mac: NFC normalized {@link File}, otherwise the passed file - * @deprecated Use {@link FileUtils#normalize(File)} instead + * a {@link java.io.File}. + * @return on Mac: NFC normalized {@link java.io.File}, otherwise the passed + * file + * @deprecated Use {@link org.eclipse.jgit.util.FileUtils#normalize(File)} + * instead */ @Deprecated public static File normalize(File file) { @@ -227,9 +287,13 @@ public class FileUtil { } /** + * NFC normalize file name (on Mac), otherwise do nothing + * * @param name + * a {@link java.lang.String} object. * @return on Mac: NFC normalized form of given name - * @deprecated Use {@link FileUtils#normalize(String)} instead + * @deprecated Use {@link org.eclipse.jgit.util.FileUtils#normalize(String)} + * instead */ @Deprecated public static String normalize(String name) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/FileUtils.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/FileUtils.java index 76dbb8756e..08c278e38a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/FileUtils.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/FileUtils.java @@ -47,10 +47,10 @@ package org.eclipse.jgit.util; import java.io.File; import java.io.IOException; -import java.nio.channels.FileLock; import java.nio.file.AtomicMoveNotSupportedException; import java.nio.file.CopyOption; import java.nio.file.Files; +import java.nio.file.InvalidPathException; import java.nio.file.LinkOption; import java.nio.file.Path; import java.nio.file.StandardCopyOption; @@ -112,15 +112,34 @@ public class FileUtils { public static final int EMPTY_DIRECTORIES_ONLY = 16; /** + * Safe conversion from {@link java.io.File} to {@link java.nio.file.Path}. + * + * @param f + * {@code File} to be converted to {@code Path} + * @return the path represented by the file + * @throws java.io.IOException + * in case the path represented by the file is not valid ( + * {@link java.nio.file.InvalidPathException}) + * @since 4.10 + */ + public static Path toPath(final File f) throws IOException { + try { + return f.toPath(); + } catch (InvalidPathException ex) { + throw new IOException(ex); + } + } + + /** * Delete file or empty folder * * @param f * {@code File} to be deleted - * @throws IOException + * @throws java.io.IOException * if deletion of {@code f} fails. This may occur if {@code f} * didn't exist when the method was called. This can therefore - * cause IOExceptions during race conditions when multiple - * concurrent threads all try to delete the same file. + * cause java.io.IOExceptions during race conditions when + * multiple concurrent threads all try to delete the same file. */ public static void delete(final File f) throws IOException { delete(f, NONE); @@ -136,12 +155,12 @@ public class FileUtils { * a subtree, {@code RETRY} to retry when deletion failed. * Retrying may help if the underlying file system doesn't allow * deletion of files being read by another thread. - * @throws IOException + * @throws java.io.IOException * if deletion of {@code f} fails. This may occur if {@code f} * didn't exist when the method was called. This can therefore - * cause IOExceptions during race conditions when multiple - * concurrent threads all try to delete the same file. This - * exception is not thrown when IGNORE_ERRORS is set. + * cause java.io.IOExceptions during race conditions when + * multiple concurrent threads all try to delete the same file. + * This exception is not thrown when IGNORE_ERRORS is set. */ public static void delete(final File f, int options) throws IOException { FS fs = FS.DETECTED; @@ -218,7 +237,7 @@ public class FileUtils { * the old {@code File} * @param dst * the new {@code File} - * @throws IOException + * @throws java.io.IOException * if the rename has failed * @since 3.0 */ @@ -228,18 +247,20 @@ public class FileUtils { } /** - * Rename a file or folder using the passed {@link CopyOption}s. If the - * rename fails and if we are running on a filesystem where it makes sense - * to repeat a failing rename then repeat the rename operation up to 9 times - * with 100ms sleep time between two calls. Furthermore if the destination - * exists and is a directory hierarchy with only directories in it, the - * whole directory hierarchy will be deleted. If the target represents a - * non-empty directory structure, empty subdirectories within that structure - * may or may not be deleted even if the method fails. Furthermore if the - * destination exists and is a file then the file will be replaced if - * {@link StandardCopyOption#REPLACE_EXISTING} has been set. If - * {@link StandardCopyOption#ATOMIC_MOVE} has been set the rename will be - * done atomically or fail with an {@link AtomicMoveNotSupportedException} + * Rename a file or folder using the passed + * {@link java.nio.file.CopyOption}s. If the rename fails and if we are + * running on a filesystem where it makes sense to repeat a failing rename + * then repeat the rename operation up to 9 times with 100ms sleep time + * between two calls. Furthermore if the destination exists and is a + * directory hierarchy with only directories in it, the whole directory + * hierarchy will be deleted. If the target represents a non-empty directory + * structure, empty subdirectories within that structure may or may not be + * deleted even if the method fails. Furthermore if the destination exists + * and is a file then the file will be replaced if + * {@link java.nio.file.StandardCopyOption#REPLACE_EXISTING} has been set. + * If {@link java.nio.file.StandardCopyOption#ATOMIC_MOVE} has been set the + * rename will be done atomically or fail with an + * {@link java.nio.file.AtomicMoveNotSupportedException} * * @param src * the old file @@ -247,10 +268,10 @@ public class FileUtils { * the new file * @param options * options to pass to - * {@link Files#move(java.nio.file.Path, java.nio.file.Path, CopyOption...)} - * @throws AtomicMoveNotSupportedException + * {@link java.nio.file.Files#move(java.nio.file.Path, java.nio.file.Path, CopyOption...)} + * @throws java.nio.file.AtomicMoveNotSupportedException * if file cannot be moved as an atomic file system operation - * @throws IOException + * @throws java.io.IOException * @since 4.1 */ public static void rename(final File src, final File dst, @@ -259,7 +280,7 @@ public class FileUtils { int attempts = FS.DETECTED.retryFailedLockFileCommit() ? 10 : 1; while (--attempts >= 0) { try { - Files.move(src.toPath(), dst.toPath(), options); + Files.move(toPath(src), toPath(dst), options); return; } catch (AtomicMoveNotSupportedException e) { throw e; @@ -269,7 +290,7 @@ public class FileUtils { delete(dst, EMPTY_DIRECTORIES_ONLY | RECURSIVE); } // On *nix there is no try, you do or do not - Files.move(src.toPath(), dst.toPath(), options); + Files.move(toPath(src), toPath(dst), options); return; } catch (IOException e2) { // ignore and continue retry @@ -293,11 +314,12 @@ public class FileUtils { * * @param d * directory to be created - * @throws IOException + * @throws java.io.IOException * if creation of {@code d} fails. This may occur if {@code d} * did exist when the method was called. This can therefore - * cause IOExceptions during race conditions when multiple - * concurrent threads all try to create the same directory. + * cause java.io.IOExceptions during race conditions when + * multiple concurrent threads all try to create the same + * directory. */ public static void mkdir(final File d) throws IOException { @@ -312,11 +334,12 @@ public class FileUtils { * @param skipExisting * if {@code true} skip creation of the given directory if it * already exists in the file system - * @throws IOException + * @throws java.io.IOException * if creation of {@code d} fails. This may occur if {@code d} * did exist when the method was called. This can therefore - * cause IOExceptions during race conditions when multiple - * concurrent threads all try to create the same directory. + * cause java.io.IOExceptions during race conditions when + * multiple concurrent threads all try to create the same + * directory. */ public static void mkdir(final File d, boolean skipExisting) throws IOException { @@ -336,11 +359,12 @@ public class FileUtils { * * @param d * directory to be created - * @throws IOException + * @throws java.io.IOException * if creation of {@code d} fails. This may occur if {@code d} * did exist when the method was called. This can therefore - * cause IOExceptions during race conditions when multiple - * concurrent threads all try to create the same directory. + * cause java.io.IOExceptions during race conditions when + * multiple concurrent threads all try to create the same + * directory. */ public static void mkdirs(final File d) throws IOException { mkdirs(d, false); @@ -357,11 +381,12 @@ public class FileUtils { * @param skipExisting * if {@code true} skip creation of the given directory if it * already exists in the file system - * @throws IOException + * @throws java.io.IOException * if creation of {@code d} fails. This may occur if {@code d} * did exist when the method was called. This can therefore - * cause IOExceptions during race conditions when multiple - * concurrent threads all try to create the same directory. + * cause java.io.IOExceptions during race conditions when + * multiple concurrent threads all try to create the same + * directory. */ public static void mkdirs(final File d, boolean skipExisting) throws IOException { @@ -381,12 +406,12 @@ public class FileUtils { * filesystem activities that might affect the file. * <p> * Note: this method should not be used for file-locking, as the resulting - * protocol cannot be made to work reliably. The {@link FileLock} facility - * should be used instead. + * protocol cannot be made to work reliably. The + * {@link java.nio.channels.FileLock} facility should be used instead. * * @param f * the file to be created - * @throws IOException + * @throws java.io.IOException * if the named file already exists or if an I/O error occurred */ public static void createNewFile(File f) throws IOException { @@ -403,12 +428,12 @@ public class FileUtils { * @param target * the target of the symbolic link * @return the path to the symbolic link - * @throws IOException + * @throws java.io.IOException * @since 4.2 */ public static Path createSymLink(File path, String target) throws IOException { - Path nioPath = path.toPath(); + Path nioPath = toPath(path); if (Files.exists(nioPath, LinkOption.NOFOLLOW_LINKS)) { BasicFileAttributes attrs = Files.readAttributes(nioPath, BasicFileAttributes.class, LinkOption.NOFOLLOW_LINKS); @@ -421,18 +446,21 @@ public class FileUtils { if (SystemReader.getInstance().isWindows()) { target = target.replace('/', '\\'); } - Path nioTarget = new File(target).toPath(); + Path nioTarget = toPath(new File(target)); return Files.createSymbolicLink(nioPath, nioTarget); } /** + * Read target path of the symlink. + * * @param path + * a {@link java.io.File} object. * @return target path of the symlink, or null if it is not a symbolic link - * @throws IOException + * @throws java.io.IOException * @since 3.0 */ public static String readSymLink(File path) throws IOException { - Path nioPath = path.toPath(); + Path nioPath = toPath(path); Path target = Files.readSymbolicLink(nioPath); String targetString = target.toString(); if (SystemReader.getInstance().isWindows()) { @@ -447,11 +475,13 @@ public class FileUtils { * Create a temporary directory. * * @param prefix + * prefix string * @param suffix + * suffix string * @param dir * The parent dir, can be null to use system default temp dir. * @return the temp dir created. - * @throws IOException + * @throws java.io.IOException * @since 3.4 */ public static File createTempDir(String prefix, String suffix, File dir) @@ -470,18 +500,19 @@ public class FileUtils { /** + * Relativize a path + * * @deprecated Use the more-clearly-named - * {@link FileUtils#relativizeNativePath(String, String)} + * {@link org.eclipse.jgit.util.FileUtils#relativizeNativePath(String, String)} * instead, or directly call - * {@link FileUtils#relativizePath(String, String, String, boolean)} + * {@link org.eclipse.jgit.util.FileUtils#relativizePath(String, String, String, boolean)} * * Expresses <code>other</code> as a relative file path from * <code>base</code>. File-separator and case sensitivity are * based on the current file system. * * See also - * {@link FileUtils#relativizePath(String, String, String, boolean)}. - * + * {@link org.eclipse.jgit.util.FileUtils#relativizePath(String, String, String, boolean)}. * @param base * Base path * @param other @@ -495,15 +526,17 @@ public class FileUtils { } /** - * Expresses <code>other</code> as a relative file path from <code>base</code>. - * File-separator and case sensitivity are based on the current file system. + * Expresses <code>other</code> as a relative file path from + * <code>base</code>. File-separator and case sensitivity are based on the + * current file system. * - * See also {@link FileUtils#relativizePath(String, String, String, boolean)}. + * See also + * {@link org.eclipse.jgit.util.FileUtils#relativizePath(String, String, String, boolean)}. * * @param base * Base path * @param other - * Destination path + * Destination path * @return Relative path from <code>base</code> to <code>other</code> * @since 4.8 */ @@ -512,15 +545,17 @@ public class FileUtils { } /** - * Expresses <code>other</code> as a relative file path from <code>base</code>. - * File-separator and case sensitivity are based on Git's internal representation of files (which matches Unix). + * Expresses <code>other</code> as a relative file path from + * <code>base</code>. File-separator and case sensitivity are based on Git's + * internal representation of files (which matches Unix). * - * See also {@link FileUtils#relativizePath(String, String, String, boolean)}. + * See also + * {@link org.eclipse.jgit.util.FileUtils#relativizePath(String, String, String, boolean)}. * * @param base * Base path * @param other - * Destination path + * Destination path * @return Relative path from <code>base</code> to <code>other</code> * @since 4.8 */ @@ -540,7 +575,6 @@ public class FileUtils { * </pre> * * This will return "..\\another_project\\pom.xml". - * </p> * * <p> * <b>Note</b> that this will return the empty String if <code>base</code> @@ -599,6 +633,7 @@ public class FileUtils { * Determine if an IOException is a Stale NFS File Handle * * @param ioe + * an {@link java.io.IOException} object. * @return a boolean true if the IOException is a Stale NFS FIle Handle * @since 4.1 */ @@ -614,6 +649,7 @@ public class FileUtils { * File Handle * * @param throwable + * a {@link java.lang.Throwable} object. * @return a boolean true if the throwable or a cause in its causal chain is * a Stale NFS File Handle * @since 4.7 @@ -644,7 +680,7 @@ public class FileUtils { * @throws IOException */ static long lastModified(File file) throws IOException { - return Files.getLastModifiedTime(file.toPath(), LinkOption.NOFOLLOW_LINKS) + return Files.getLastModifiedTime(toPath(file), LinkOption.NOFOLLOW_LINKS) .toMillis(); } @@ -654,7 +690,7 @@ public class FileUtils { * @throws IOException */ static void setLastModified(File file, long time) throws IOException { - Files.setLastModifiedTime(file.toPath(), FileTime.fromMillis(time)); + Files.setLastModifiedTime(toPath(file), FileTime.fromMillis(time)); } /** @@ -672,28 +708,35 @@ public class FileUtils { * @throws IOException */ static boolean isHidden(File file) throws IOException { - return Files.isHidden(file.toPath()); + return Files.isHidden(toPath(file)); } /** + * Set a file hidden (on Windows) + * * @param file + * a {@link java.io.File} object. * @param hidden - * @throws IOException + * a boolean. + * @throws java.io.IOException * @since 4.1 */ public static void setHidden(File file, boolean hidden) throws IOException { - Files.setAttribute(file.toPath(), "dos:hidden", Boolean.valueOf(hidden), //$NON-NLS-1$ + Files.setAttribute(toPath(file), "dos:hidden", Boolean.valueOf(hidden), //$NON-NLS-1$ LinkOption.NOFOLLOW_LINKS); } /** + * Get file length + * * @param file + * a {@link java.io.File}. * @return length of the given file - * @throws IOException + * @throws java.io.IOException * @since 4.1 */ public static long getLength(File file) throws IOException { - Path nioPath = file.toPath(); + Path nioPath = toPath(file); if (Files.isSymbolicLink(nioPath)) return Files.readSymbolicLink(nioPath).toString() .getBytes(Constants.CHARSET).length; @@ -719,8 +762,11 @@ public class FileUtils { } /** + * Whether the given file can be executed. + * * @param file - * @return {@code true} if the given file can be executed + * a {@link java.io.File} object. + * @return {@code true} if the given file can be executed. * @since 4.1 */ public static boolean canExecute(File file) { @@ -737,7 +783,7 @@ public class FileUtils { */ static Attributes getFileAttributesBasic(FS fs, File file) { try { - Path nioPath = file.toPath(); + Path nioPath = toPath(file); BasicFileAttributes readAttributes = nioPath .getFileSystem() .provider() @@ -762,14 +808,18 @@ public class FileUtils { } /** + * Get file system attributes for the given file. + * * @param fs + * a {@link org.eclipse.jgit.util.FS} object. * @param file - * @return file system attributes for the given file + * a {@link java.io.File}. + * @return file system attributes for the given file. * @since 4.1 */ public static Attributes getFileAttributesPosix(FS fs, File file) { try { - Path nioPath = file.toPath(); + Path nioPath = toPath(file); PosixFileAttributes readAttributes = nioPath .getFileSystem() .provider() @@ -795,8 +845,12 @@ public class FileUtils { } /** + * NFC normalize a file (on Mac), otherwise do nothing + * * @param file - * @return on Mac: NFC normalized {@link File}, otherwise the passed file + * a {@link java.io.File}. + * @return on Mac: NFC normalized {@link java.io.File}, otherwise the passed + * file * @since 4.1 */ public static File normalize(File file) { @@ -811,7 +865,10 @@ public class FileUtils { } /** + * On Mac: get NFC normalized form of given name, otherwise the given name. + * * @param name + * a {@link java.lang.String} object. * @return on Mac: NFC normalized form of given name * @since 4.1 */ @@ -825,16 +882,16 @@ public class FileUtils { } /** - * Best-effort variation of {@link File#getCanonicalFile()} returning the - * input file if the file cannot be canonicalized instead of throwing - * {@link IOException}. + * Best-effort variation of {@link java.io.File#getCanonicalFile()} + * returning the input file if the file cannot be canonicalized instead of + * throwing {@link java.io.IOException}. * * @param file * to be canonicalized; may be {@code null} * @return canonicalized file, or the unchanged input file if * canonicalization failed or if {@code file == null} - * @throws SecurityException - * if {@link File#getCanonicalFile()} throws one + * @throws java.lang.SecurityException + * if {@link java.io.File#getCanonicalFile()} throws one * @since 4.2 */ public static File canonicalize(File file) { @@ -848,4 +905,19 @@ public class FileUtils { } } + /** + * Convert a path to String, replacing separators as necessary. + * + * @param file + * a {@link java.io.File}. + * @return file's path as a String + * @since 4.10 + */ + public static String pathToString(File file) { + final String path = file.getPath(); + if (SystemReader.getInstance().isWindows()) { + return path.replace('\\', '/'); + } + return path; + } } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/GitDateFormatter.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/GitDateFormatter.java index d7ab5f882b..e461902a31 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/GitDateFormatter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/GitDateFormatter.java @@ -54,7 +54,8 @@ import org.eclipse.jgit.lib.PersonIdent; * A utility for formatting dates according to the Git log.date formats plus * extensions. * <p> - * The enum {@link Format} defines the available types. + * The enum {@link org.eclipse.jgit.util.GitDateFormatter.Format} defines the + * available types. */ public class GitDateFormatter { @@ -119,6 +120,8 @@ public class GitDateFormatter { * Create a new Git oriented date formatter * * @param format + * a {@link org.eclipse.jgit.util.GitDateFormatter.Format} + * object. */ public GitDateFormatter(Format format) { this.format = format; @@ -159,6 +162,7 @@ public class GitDateFormatter { * specification. * * @param ident + * a {@link org.eclipse.jgit.lib.PersonIdent} object. * @return formatted version of date, time and time zone */ @SuppressWarnings("boxing") diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/GitDateParser.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/GitDateParser.java index da78008a0b..a339b9aba0 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/GitDateParser.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/GitDateParser.java @@ -55,7 +55,7 @@ import java.util.Map; import org.eclipse.jgit.internal.JGitText; /** - * Parses strings with time and date specifications into {@link Date}. + * Parses strings with time and date specifications into {@link java.util.Date}. * * When git needs to parse strings specified by the user this parser can be * used. One example is the parsing of the config parameter gc.pruneexpire. The @@ -134,16 +134,17 @@ public class GitDateParser { } /** - * Parses a string into a {@link Date} using the default locale. Since this - * parser also supports relative formats (e.g. "yesterday") the caller can - * specify the reference date. These types of strings can be parsed: + * Parses a string into a {@link java.util.Date} using the default locale. + * Since this parser also supports relative formats (e.g. "yesterday") the + * caller can specify the reference date. These types of strings can be + * parsed: * <ul> * <li>"never"</li> * <li>"now"</li> * <li>"yesterday"</li> * <li>"(x) years|months|weeks|days|hours|minutes|seconds ago"<br> - * Multiple specs can be combined like in "2 weeks 3 days ago". Instead of - * ' ' one can use '.' to seperate the words</li> + * Multiple specs can be combined like in "2 weeks 3 days ago". Instead of ' + * ' one can use '.' to seperate the words</li> * <li>"yyyy-MM-dd HH:mm:ss Z" (ISO)</li> * <li>"EEE, dd MMM yyyy HH:mm:ss Z" (RFC)</li> * <li>"yyyy-MM-dd"</li> @@ -161,11 +162,12 @@ public class GitDateParser { * formats. E.g. if baseDate is "25.8.2012" then parsing of the * string "1 week ago" would result in a date corresponding to * "18.8.2012". This is used when a JGit command calls this - * parser often but wants a consistent starting point for calls.<br> + * parser often but wants a consistent starting point for + * calls.<br> * If set to <code>null</code> then the current time will be used * instead. - * @return the parsed {@link Date} - * @throws ParseException + * @return the parsed {@link java.util.Date} + * @throws java.text.ParseException * if the given dateStr was not recognized */ public static Date parse(String dateStr, Calendar now) @@ -174,16 +176,17 @@ public class GitDateParser { } /** - * Parses a string into a {@link Date} using the given locale. Since this - * parser also supports relative formats (e.g. "yesterday") the caller can - * specify the reference date. These types of strings can be parsed: + * Parses a string into a {@link java.util.Date} using the given locale. + * Since this parser also supports relative formats (e.g. "yesterday") the + * caller can specify the reference date. These types of strings can be + * parsed: * <ul> * <li>"never"</li> * <li>"now"</li> * <li>"yesterday"</li> * <li>"(x) years|months|weeks|days|hours|minutes|seconds ago"<br> - * Multiple specs can be combined like in "2 weeks 3 days ago". Instead of - * ' ' one can use '.' to seperate the words</li> + * Multiple specs can be combined like in "2 weeks 3 days ago". Instead of ' + * ' one can use '.' to seperate the words</li> * <li>"yyyy-MM-dd HH:mm:ss Z" (ISO)</li> * <li>"EEE, dd MMM yyyy HH:mm:ss Z" (RFC)</li> * <li>"yyyy-MM-dd"</li> @@ -201,13 +204,14 @@ public class GitDateParser { * formats. E.g. if baseDate is "25.8.2012" then parsing of the * string "1 week ago" would result in a date corresponding to * "18.8.2012". This is used when a JGit command calls this - * parser often but wants a consistent starting point for calls.<br> + * parser often but wants a consistent starting point for + * calls.<br> * If set to <code>null</code> then the current time will be used * instead. * @param locale * locale to be used to parse the date string - * @return the parsed {@link Date} - * @throws ParseException + * @return the parsed {@link java.util.Date} + * @throws java.text.ParseException * if the given dateStr was not recognized * @since 3.2 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/Holder.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/Holder.java index 3563e1bf1d..b4cc6ca33f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/Holder.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/Holder.java @@ -45,14 +45,15 @@ package org.eclipse.jgit.util; * Holder of an object. * * @param <T> - * the type of value held by this {@link Holder} - * + * the type of value held by this {@link org.eclipse.jgit.util.Holder} * @since 4.3 */ public class Holder<T> { private T value; /** + * <p>Constructor for Holder.</p> + * * @param value * is the initial value that is {@link #set(Object)} */ @@ -61,15 +62,20 @@ public class Holder<T> { } /** - * @return the value held by this {@link Holder} + * Get the value held by this {@link org.eclipse.jgit.util.Holder} + * + * @return the value held by this {@link org.eclipse.jgit.util.Holder} */ public T get() { return value; } /** + * Set a new value held by this {@link org.eclipse.jgit.util.Holder} + * * @param value - * to be set as new value held by this {@link Holder} + * to be set as new value held by this + * {@link org.eclipse.jgit.util.Holder} */ public void set(T value) { this.value = value; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/HttpSupport.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/HttpSupport.java index 13e61a7972..a5a858f85e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/HttpSupport.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/HttpSupport.java @@ -65,7 +65,9 @@ import javax.net.ssl.X509TrustManager; import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.transport.http.HttpConnection; -/** Extra utilities to support usage of HTTP. */ +/** + * Extra utilities to support usage of HTTP. + */ public class HttpSupport { /** The {@code GET} HTTP method. */ public static final String METHOD_GET = "GET"; //$NON-NLS-1$ @@ -192,8 +194,9 @@ public class HttpSupport { * @param c * connection the code should be obtained from. * @return r HTTP status code, usually 200 to indicate success. See - * {@link HttpConnection} for other defined constants. - * @throws IOException + * {@link org.eclipse.jgit.transport.http.HttpConnection} for other + * defined constants. + * @throws java.io.IOException * communications error prevented obtaining the response code. * @since 3.3 */ @@ -220,8 +223,9 @@ public class HttpSupport { * @param c * connection the code should be obtained from. * @return r HTTP status code, usually 200 to indicate success. See - * {@link HttpConnection} for other defined constants. - * @throws IOException + * {@link org.eclipse.jgit.transport.http.HttpConnection} for other + * defined constants. + * @throws java.io.IOException * communications error prevented obtaining the response code. */ public static int response(final java.net.HttpURLConnection c) @@ -248,7 +252,7 @@ public class HttpSupport { * @param headerName * the header name * @return the header value - * @throws IOException + * @throws java.io.IOException * communications error prevented obtaining the header. * @since 4.7 */ @@ -265,7 +269,7 @@ public class HttpSupport { * @param u * location of the server caller wants to talk to. * @return proxy to communicate with the supplied URL. - * @throws ConnectException + * @throws java.net.ConnectException * the proxy could not be computed as the supplied URL could not * be read. This failure should never occur. */ @@ -285,7 +289,9 @@ public class HttpSupport { * Disable SSL and hostname verification for given HTTP connection * * @param conn - * @throws IOException + * a {@link org.eclipse.jgit.transport.http.HttpConnection} + * object. + * @throws java.io.IOException * @since 4.3 */ public static void disableSslVerify(HttpConnection conn) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/IO.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/IO.java index 6cff76cc21..f39d217863 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/IO.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/IO.java @@ -71,9 +71,9 @@ public class IO { * @param path * location of the file to read. * @return complete contents of the requested local file. - * @throws FileNotFoundException + * @throws java.io.FileNotFoundException * the file does not exist. - * @throws IOException + * @throws java.io.IOException * the file exists, but its contents cannot be read. */ public static final byte[] readFully(final File path) @@ -91,9 +91,9 @@ public class IO { * only the first limit number of bytes are returned * @return complete contents of the requested local file. If the contents * exceeds the limit, then only the limit is returned. - * @throws FileNotFoundException + * @throws java.io.FileNotFoundException * the file does not exist. - * @throws IOException + * @throws java.io.IOException * the file exists, but its contents cannot be read. */ public static final byte[] readSome(final File path, final int limit) @@ -131,9 +131,9 @@ public class IO { * maximum number of bytes to read, if the file is larger than * this limit an IOException is thrown. * @return complete contents of the requested local file. - * @throws FileNotFoundException + * @throws java.io.FileNotFoundException * the file does not exist. - * @throws IOException + * @throws java.io.IOException * the file exists, but its contents cannot be read. */ public static final byte[] readFully(final File path, final int max) @@ -199,7 +199,7 @@ public class IO { * on obtaining the underlying array for efficient data access. If * {@code sizeHint} was too large, the array may be over-allocated, * resulting in {@code limit() < array().length}. - * @throws IOException + * @throws java.io.IOException * there was an error reading from the stream. */ public static ByteBuffer readWholeStream(InputStream in, int sizeHint) @@ -238,7 +238,7 @@ public class IO { * number of bytes that must be read. * @throws EOFException * the stream ended before dst was fully populated. - * @throws IOException + * @throws java.io.IOException * there was an error reading from the stream. */ public static void readFully(final InputStream fd, final byte[] dst, @@ -264,7 +264,7 @@ public class IO { * @param len * number of bytes that should be read. * @return number of bytes actually read. - * @throws IOException + * @throws java.io.IOException * there was an error reading from the channel. */ public static int read(ReadableByteChannel channel, byte[] dst, int off, @@ -293,7 +293,7 @@ public class IO { * @param off * position within the buffer to start writing to. * @return number of bytes in buffer or stream, whichever is shortest - * @throws IOException + * @throws java.io.IOException * there was an error reading from the stream. */ public static int readFully(InputStream fd, byte[] dst, int off) @@ -322,7 +322,7 @@ public class IO { * @throws EOFException * the stream ended before the requested number of bytes were * skipped. - * @throws IOException + * @throws java.io.IOException * there was an error reading from the stream. */ public static void skipFully(final InputStream fd, long toSkip) @@ -384,7 +384,7 @@ public class IO { * hint for buffer sizing; 0 or negative for default. * @return the next line from the input, always ending in {@code \n} unless * EOF was reached. - * @throws IOException + * @throws java.io.IOException * there was an error reading from the stream. * @since 4.1 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/IntList.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/IntList.java index 0a3c846a0e..24038f0976 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/IntList.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/IntList.java @@ -44,13 +44,17 @@ package org.eclipse.jgit.util; -/** A more efficient List<Integer> using a primitive integer array. */ +/** + * A more efficient List<Integer> using a primitive integer array. + */ public class IntList { private int[] entries; private int count; - /** Create an empty list with a default capacity. */ + /** + * Create an empty list with a default capacity. + */ public IntList() { this(10); } @@ -65,7 +69,11 @@ public class IntList { entries = new int[capacity]; } - /** @return number of entries in this list */ + /** + * Get number of entries in this list. + * + * @return number of entries in this list. + */ public int size() { return count; } @@ -86,10 +94,12 @@ public class IntList { } /** + * Get the value at the specified index + * * @param i * index to read, must be in the range [0, {@link #size()}). * @return the number at the specified index - * @throws ArrayIndexOutOfBoundsException + * @throws java.lang.ArrayIndexOutOfBoundsException * the index outside the valid range */ public int get(final int i) { @@ -98,7 +108,9 @@ public class IntList { return entries[i]; } - /** Empty this list */ + /** + * Empty this list + */ public void clear() { count = 0; } @@ -153,6 +165,7 @@ public class IntList { entries = n; } + /** {@inheritDoc} */ @Override public String toString() { final StringBuilder r = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/LongList.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/LongList.java index e3639f5c65..404594cf79 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/LongList.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/LongList.java @@ -46,13 +46,17 @@ package org.eclipse.jgit.util; import java.util.Arrays; -/** A more efficient List<Long> using a primitive long array. */ +/** + * A more efficient List<Long> using a primitive long array. + */ public class LongList { private long[] entries; private int count; - /** Create an empty list with a default capacity. */ + /** + * Create an empty list with a default capacity. + */ public LongList() { this(10); } @@ -67,16 +71,22 @@ public class LongList { entries = new long[capacity]; } - /** @return number of entries in this list */ + /** + * Get number of entries in this list + * + * @return number of entries in this list + */ public int size() { return count; } /** + * Get the value at the specified index + * * @param i * index to read, must be in the range [0, {@link #size()}). * @return the number at the specified index - * @throws ArrayIndexOutOfBoundsException + * @throws java.lang.ArrayIndexOutOfBoundsException * the index outside the valid range */ public long get(final int i) { @@ -99,7 +109,9 @@ public class LongList { return false; } - /** Empty this list */ + /** + * Clear this list + */ public void clear() { count = 0; } @@ -148,7 +160,9 @@ public class LongList { add(val); } - /** Sort the list of longs according to their natural ordering. */ + /** + * Sort the list of longs according to their natural ordering. + */ public void sort() { Arrays.sort(entries, 0, count); } @@ -159,6 +173,7 @@ public class LongList { entries = n; } + /** {@inheritDoc} */ @Override public String toString() { final StringBuilder r = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/LongMap.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/LongMap.java index 7b0b0c728a..09eee42024 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/LongMap.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/LongMap.java @@ -44,7 +44,7 @@ package org.eclipse.jgit.util; /** - * Simple Map<long,Object>. + * Simple Map<long, Object>. * * @param <V> * type of the value instance. @@ -61,13 +61,17 @@ public class LongMap<V> { /** Next {@link #size} to trigger a {@link #grow()}. */ private int growAt; - /** Initialize an empty LongMap. */ + /** + * Initialize an empty LongMap. + */ public LongMap() { table = createArray(64); growAt = (int) (table.length * LOAD_FACTOR); } /** + * Whether {@code key} is present in the map. + * * @param key * the key to find. * @return {@code true} if {@code key} is present in the map. @@ -77,9 +81,11 @@ public class LongMap<V> { } /** + * Get value for this {@code key} + * * @param key * the key to find. - * @return stored value of the key, or {@code null}. + * @return stored value for this key, or {@code null}. */ public V get(long key) { for (Node<V> n = table[index(key)]; n != null; n = n.next) { @@ -90,6 +96,8 @@ public class LongMap<V> { } /** + * Remove an entry from the map + * * @param key * key to remove from the map. * @return old value of the key, or {@code null}. @@ -113,6 +121,8 @@ public class LongMap<V> { } /** + * Put a new entry into the map + * * @param key * key to store {@code value} under. * @param value diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/MutableInteger.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/MutableInteger.java index cbe321086c..8cee9f9608 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/MutableInteger.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/MutableInteger.java @@ -43,7 +43,9 @@ package org.eclipse.jgit.util; -/** A boxed integer that can be modified. */ +/** + * A boxed integer that can be modified. + */ public final class MutableInteger { /** Current value of this boxed value. */ public int value; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/NB.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/NB.java index 471a4998d7..8ad6aa0ad8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/NB.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/NB.java @@ -43,7 +43,9 @@ package org.eclipse.jgit.util; -/** Conversion utilities for network byte order handling. */ +/** + * Conversion utilities for network byte order handling. + */ public final class NB { /** * Compare a 32 bit unsigned integer stored in a 32 bit signed integer. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/ProcessResult.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/ProcessResult.java index 77c9608c79..9267a325f4 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/ProcessResult.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/ProcessResult.java @@ -86,6 +86,8 @@ public class ProcessResult { } /** + * <p>Constructor for ProcessResult.</p> + * * @param exitCode * Exit code of the process. * @param status @@ -97,6 +99,8 @@ public class ProcessResult { } /** + * Get exit code of the process. + * * @return The exit code of the process. */ public int getExitCode() { @@ -104,6 +108,8 @@ public class ProcessResult { } /** + * Get the status of the process' execution. + * * @return The status of the process' execution. */ public Status getStatus() { @@ -111,6 +117,8 @@ public class ProcessResult { } /** + * Whether the execution occurred and resulted in an error + * * @return <code>true</code> if the execution occurred and resulted in a * return code different from 0, <code>false</code> otherwise. * @since 4.0 diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/QuotedString.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/QuotedString.java index 57dfb85903..77bc2495fb 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/QuotedString.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/QuotedString.java @@ -47,7 +47,9 @@ import java.util.Arrays; import org.eclipse.jgit.lib.Constants; -/** Utility functions related to quoted string handling. */ +/** + * Utility functions related to quoted string handling. + */ public abstract class QuotedString { /** Quoting style that obeys the rules Git applies to file names */ public static final GitPathStyle GIT_PATH = new GitPathStyle(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/RawCharSequence.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/RawCharSequence.java index e85bd659b4..23ee9d0d64 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/RawCharSequence.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/RawCharSequence.java @@ -74,21 +74,25 @@ public final class RawCharSequence implements CharSequence { endPtr = end; } + /** {@inheritDoc} */ @Override public char charAt(final int index) { return (char) (buffer[startPtr + index] & 0xff); } + /** {@inheritDoc} */ @Override public int length() { return endPtr - startPtr; } + /** {@inheritDoc} */ @Override public CharSequence subSequence(final int start, final int end) { return new RawCharSequence(buffer, startPtr + start, startPtr + end); } + /** {@inheritDoc} */ @Override public String toString() { final int n = length(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/RawParseUtils.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/RawParseUtils.java index ad138bbf18..014c7727a8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/RawParseUtils.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/RawParseUtils.java @@ -66,7 +66,9 @@ import org.eclipse.jgit.annotations.Nullable; import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.lib.PersonIdent; -/** Handy utility functions to parse raw object contents. */ +/** + * Handy utility functions to parse raw object contents. + */ public final class RawParseUtils { /** * UTF-8 charset constant. @@ -306,7 +308,7 @@ public final class RawParseUtils { * @param p * first position within the buffer to parse. * @return the integer value. - * @throws ArrayIndexOutOfBoundsException + * @throws java.lang.ArrayIndexOutOfBoundsException * if the string is not hex formatted. */ public static final int parseHexInt16(final byte[] bs, final int p) { @@ -336,7 +338,7 @@ public final class RawParseUtils { * @param p * first position within the buffer to parse. * @return the integer value. - * @throws ArrayIndexOutOfBoundsException + * @throws java.lang.ArrayIndexOutOfBoundsException * if the string is not hex formatted. */ public static final int parseHexInt32(final byte[] bs, final int p) { @@ -377,7 +379,7 @@ public final class RawParseUtils { * @param p * first position within the buffer to parse. * @return the integer value. - * @throws ArrayIndexOutOfBoundsException + * @throws java.lang.ArrayIndexOutOfBoundsException * if the string is not hex formatted. * @since 4.3 */ @@ -437,7 +439,7 @@ public final class RawParseUtils { * @param digit * hex character to parse. * @return numeric value, in the range 0-15. - * @throws ArrayIndexOutOfBoundsException + * @throws java.lang.ArrayIndexOutOfBoundsException * if the input digit is not a valid hex digit. */ public static final int parseHexInt4(final byte digit) { @@ -610,7 +612,7 @@ public final class RawParseUtils { * Index the region between <code>[ptr, end)</code> to find line starts. * <p> * The returned list is 1 indexed. Index 0 contains - * {@link Integer#MIN_VALUE} to pad the list out. + * {@link java.lang.Integer#MIN_VALUE} to pad the list out. * <p> * Using a 1 indexed list means that line numbers can be directly accessed * from the list, so <code>list.get(1)</code> (aka get line 1) returns @@ -619,8 +621,8 @@ public final class RawParseUtils { * The last element (index <code>map.size()-1</code>) always contains * <code>end</code>. * <p> - * If the data contains a '\0' anywhere, the whole region is considered binary - * and a LineMap corresponding to a single line is returned. + * If the data contains a '\0' anywhere, the whole region is considered + * binary and a LineMap corresponding to a single line is returned. * </p> * * @param buf @@ -1076,7 +1078,7 @@ public final class RawParseUtils { * data from. * @return a string representation of the range <code>[start,end)</code>, * after decoding the region through the specified character set. - * @throws CharacterCodingException + * @throws java.nio.charset.CharacterCodingException * the input is not in any of the tested character sets. */ public static String decodeNoFallback(final Charset cs, @@ -1222,13 +1224,15 @@ public final class RawParseUtils { } /** + * Get last index of {@code ch} in raw, trimming spaces. + * * @param raw * buffer to scan. * @param ch * character to find. * @param pos * starting position. - * @return last index of ch in raw, trimming spaces. + * @return last index of {@code ch} in raw, trimming spaces. * @since 4.1 */ public static int lastIndexOfTrim(byte[] raw, char ch, int pos) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/RawSubStringPattern.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/RawSubStringPattern.java index bc101bd7d7..a8f9bc72eb 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/RawSubStringPattern.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/RawSubStringPattern.java @@ -131,6 +131,7 @@ public class RawSubStringPattern { return needleString; } + /** {@inheritDoc} */ @Override public String toString() { return pattern(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/RefList.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/RefList.java index ce4b7c7507..639c353621 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/RefList.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/RefList.java @@ -71,9 +71,9 @@ public class RefList<T extends Ref> implements Iterable<Ref> { private static final RefList<Ref> EMPTY = new RefList<>(new Ref[0], 0); /** + * Create an empty unmodifiable reference list. + * * @return an empty unmodifiable reference list. - * @param <T> - * the type of reference being stored in the collection. */ @SuppressWarnings("unchecked") public static <T extends Ref> RefList<T> emptyList() { @@ -100,6 +100,7 @@ public class RefList<T extends Ref> implements Iterable<Ref> { this.cnt = src.cnt; } + /** {@inheritDoc} */ @Override public Iterator<Ref> iterator() { return new Iterator<Ref>() { @@ -124,18 +125,30 @@ public class RefList<T extends Ref> implements Iterable<Ref> { }; } - /** @return this cast as an immutable, standard {@link java.util.List}. */ + /** + * Cast {@code this} as an immutable, standard {@link java.util.List}. + * + * @return {@code this} as an immutable, standard {@link java.util.List}. + */ public final List<Ref> asList() { final List<Ref> r = Arrays.asList(list).subList(0, cnt); return Collections.unmodifiableList(r); } - /** @return number of items in this list. */ + /** + * Get number of items in this list. + * + * @return number of items in this list. + */ public final int size() { return cnt; } - /** @return true if the size of this list is 0. */ + /** + * Get if this list is empty. + * + * @return true if the size of this list is 0. + */ public final boolean isEmpty() { return cnt == 0; } @@ -303,6 +316,7 @@ public class RefList<T extends Ref> implements Iterable<Ref> { return add(idx, ref); } + /** {@inheritDoc} */ @Override public String toString() { StringBuilder r = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/RefMap.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/RefMap.java index 510e81821e..c1aaecfd91 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/RefMap.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/RefMap.java @@ -59,17 +59,19 @@ import org.eclipse.jgit.lib.RefComparator; * Specialized Map to present a {@code RefDatabase} namespace. * <p> * Although not declared as a {@link java.util.SortedMap}, iterators from this - * map's projections always return references in {@link RefComparator} ordering. - * The map's internal representation is a sorted array of {@link Ref} objects, + * map's projections always return references in + * {@link org.eclipse.jgit.lib.RefComparator} ordering. The map's internal + * representation is a sorted array of {@link org.eclipse.jgit.lib.Ref} objects, * which means lookup and replacement is O(log N), while insertion and removal * can be as expensive as O(N + log N) while the list expands or contracts. * Since this is not a general map implementation, all entries must be keyed by * the reference name. * <p> * This class is really intended as a helper for {@code RefDatabase}, which - * needs to perform a merge-join of three sorted {@link RefList}s in order to - * present the unified namespace of the packed-refs file, the loose refs/ - * directory tree, and the resolved form of any symbolic references. + * needs to perform a merge-join of three sorted + * {@link org.eclipse.jgit.util.RefList}s in order to present the unified + * namespace of the packed-refs file, the loose refs/ directory tree, and the + * resolved form of any symbolic references. */ public class RefMap extends AbstractMap<String, Ref> { /** @@ -109,7 +111,9 @@ public class RefMap extends AbstractMap<String, Ref> { private Set<Entry<String, Ref>> entrySet; - /** Construct an empty map with a small initial capacity. */ + /** + * Construct an empty map with a small initial capacity. + */ public RefMap() { prefix = ""; //$NON-NLS-1$ packed = RefList.emptyList(); @@ -145,11 +149,13 @@ public class RefMap extends AbstractMap<String, Ref> { this.resolved = (RefList<Ref>) resolved; } + /** {@inheritDoc} */ @Override public boolean containsKey(Object name) { return get(name) != null; } + /** {@inheritDoc} */ @Override public Ref get(Object key) { String name = toRefName((String) key); @@ -161,6 +167,7 @@ public class RefMap extends AbstractMap<String, Ref> { return ref; } + /** {@inheritDoc} */ @Override public Ref put(final String keyName, Ref value) { String name = toRefName(keyName); @@ -189,6 +196,7 @@ public class RefMap extends AbstractMap<String, Ref> { } } + /** {@inheritDoc} */ @Override public Ref remove(Object key) { String name = toRefName((String) key); @@ -212,11 +220,13 @@ public class RefMap extends AbstractMap<String, Ref> { return res; } + /** {@inheritDoc} */ @Override public boolean isEmpty() { return entrySet().isEmpty(); } + /** {@inheritDoc} */ @Override public Set<Entry<String, Ref>> entrySet() { if (entrySet == null) { @@ -258,6 +268,7 @@ public class RefMap extends AbstractMap<String, Ref> { return entrySet; } + /** {@inheritDoc} */ @Override public String toString() { StringBuilder r = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/RelativeDateFormatter.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/RelativeDateFormatter.java index a5df66e99c..83c60c63bc 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/RelativeDateFormatter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/RelativeDateFormatter.java @@ -67,10 +67,14 @@ public class RelativeDateFormatter { final static long YEAR_IN_MILLIS = 365 * DAY_IN_MILLIS; /** + * Get age of given {@link java.util.Date} compared to now formatted in the + * same relative format as returned by {@code git log --relative-date} + * * @param when - * {@link Date} to format - * @return age of given {@link Date} compared to now formatted in the same - * relative format as returned by {@code git log --relative-date} + * {@link java.util.Date} to format + * @return age of given {@link java.util.Date} compared to now formatted in + * the same relative format as returned by + * {@code git log --relative-date} */ @SuppressWarnings("boxing") public static String format(Date when) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/StringUtils.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/StringUtils.java index 2bfeaf1166..b4736d3e40 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/StringUtils.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/StringUtils.java @@ -48,7 +48,9 @@ import java.util.Collection; import org.eclipse.jgit.internal.JGitText; -/** Miscellaneous string comparison utility methods. */ +/** + * Miscellaneous string comparison utility methods. + */ public final class StringUtils { private static final char[] LC; @@ -102,10 +104,12 @@ public final class StringUtils { * * <p> * Capitalizes a String changing the first letter to title case as per - * {@link Character#toTitleCase(char)}. No other letters are changed. + * {@link java.lang.Character#toTitleCase(char)}. No other letters are + * changed. + * </p> + * <p> + * A <code>null</code> input String returns <code>null</code>. * </p> - * - * A <code>null</code> input String returns <code>null</code>.</p> * * @param str * the String to capitalize, may be null @@ -156,9 +160,8 @@ public final class StringUtils { * first string to compare. * @param b * second string to compare. - * @return negative, zero or positive if a sorts before, is equal to, or - * sorts after b. * @since 2.0 + * @return an int. */ public static int compareIgnoreCase(String a, String b) { for (int i = 0; i < a.length() && i < b.length(); i++) { @@ -179,9 +182,8 @@ public final class StringUtils { * first string to compare. * @param b * second string to compare. - * @return negative, zero or positive if a sorts before, is equal to, or - * sorts after b. * @since 2.0 + * @return an int. */ public static int compareWithCase(String a, String b) { for (int i = 0; i < a.length() && i < b.length(); i++) { @@ -199,7 +201,7 @@ public final class StringUtils { * @param stringValue * the string to parse. * @return the boolean interpretation of {@code value}. - * @throws IllegalArgumentException + * @throws java.lang.IllegalArgumentException * if {@code value} is not recognized as one of the standard * boolean names. */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/SystemReader.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/SystemReader.java index 2cd8035854..96a796cbdc 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/SystemReader.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/SystemReader.java @@ -151,12 +151,18 @@ public abstract class SystemReader { private static SystemReader INSTANCE = DEFAULT; - /** @return the live instance to read system properties. */ + /** + * Get time since epoch, with up to millisecond resolution. + * + * @return time since epoch, with up to millisecond resolution. + */ public static SystemReader getInstance() { return INSTANCE; } /** + * Set the new instance to use when accessing properties. + * * @param newReader * the new instance to use when accessing properties, or null for * the default instance. @@ -201,18 +207,26 @@ public abstract class SystemReader { public abstract String getHostname(); /** - * @param variable system variable to read + * Get value of the system variable + * + * @param variable + * system variable to read * @return value of the system variable */ public abstract String getenv(String variable); /** - * @param key of the system property to read + * Get value of the system property + * + * @param key + * of the system property to read * @return value of the system property */ public abstract String getProperty(String key); /** + * Open the git configuration found in the user home + * * @param parent * a config with values not found directly in the returned config * @param fs @@ -223,6 +237,8 @@ public abstract class SystemReader { public abstract FileBasedConfig openUserConfig(Config parent, FS fs); /** + * Open the gitonfig configuration found in the system-wide "etc" directory + * * @param parent * a config with values not found directly in the returned * config. Null is a reasonable value here. @@ -235,11 +251,15 @@ public abstract class SystemReader { public abstract FileBasedConfig openSystemConfig(Config parent, FS fs); /** + * Get the current system time + * * @return the current system time */ public abstract long getCurrentTime(); /** + * Get clock instance preferred by this system. + * * @return clock instance preferred by this system. * @since 4.6 */ @@ -248,12 +268,17 @@ public abstract class SystemReader { } /** - * @param when TODO + * Get the local time zone + * + * @param when + * a system timestamp * @return the local time zone */ public abstract int getTimezone(long when); /** + * Get system time zone, possibly mocked for testing + * * @return system time zone, possibly mocked for testing * @since 1.2 */ @@ -262,6 +287,8 @@ public abstract class SystemReader { } /** + * Get the locale to use + * * @return the locale to use * @since 1.2 */ @@ -274,7 +301,7 @@ public abstract class SystemReader { * * @param pattern * the pattern as defined in - * {@link SimpleDateFormat#SimpleDateFormat(String)} + * {@link java.text.SimpleDateFormat#SimpleDateFormat(String)} * @return the simple date format * @since 2.0 */ @@ -287,7 +314,7 @@ public abstract class SystemReader { * * @param pattern * the pattern as defined in - * {@link SimpleDateFormat#SimpleDateFormat(String)} + * {@link java.text.SimpleDateFormat#SimpleDateFormat(String)} * @param locale * locale to be used for the {@code SimpleDateFormat} * @return the simple date format @@ -302,10 +329,10 @@ public abstract class SystemReader { * * @param dateStyle * the date style as specified in - * {@link DateFormat#getDateTimeInstance(int, int)} + * {@link java.text.DateFormat#getDateTimeInstance(int, int)} * @param timeStyle * the time style as specified in - * {@link DateFormat#getDateTimeInstance(int, int)} + * {@link java.text.DateFormat#getDateTimeInstance(int, int)} * @return the date format * @since 2.0 */ @@ -314,7 +341,9 @@ public abstract class SystemReader { } /** - * @return true if we are running on a Windows. + * Whether we are running on Windows. + * + * @return true if we are running on Windows. */ public boolean isWindows() { if (isWindows == null) { @@ -325,6 +354,8 @@ public abstract class SystemReader { } /** + * Whether we are running on Mac OS X + * * @return true if we are running on Mac OS X */ public boolean isMacOS() { @@ -351,7 +382,7 @@ public abstract class SystemReader { * Scans a multi-directory path string such as {@code "src/main.c"}. * * @param path path string to scan. - * @throws CorruptObjectException path is invalid. + * @throws org.eclipse.jgit.errors.CorruptObjectException path is invalid. * @since 3.6 */ public void checkPath(String path) throws CorruptObjectException { @@ -365,7 +396,7 @@ public abstract class SystemReader { * * @param path * path string to scan. - * @throws CorruptObjectException + * @throws org.eclipse.jgit.errors.CorruptObjectException * path is invalid. * @since 4.2 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/TemporaryBuffer.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/TemporaryBuffer.java index e3f1916f43..31abb7c173 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/TemporaryBuffer.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/TemporaryBuffer.java @@ -114,6 +114,7 @@ public abstract class TemporaryBuffer extends OutputStream { reset(); } + /** {@inheritDoc} */ @Override public void write(final int b) throws IOException { if (overflow != null) { @@ -134,6 +135,7 @@ public abstract class TemporaryBuffer extends OutputStream { s.buffer[s.count++] = (byte) b; } + /** {@inheritDoc} */ @Override public void write(final byte[] b, int off, int len) throws IOException { if (overflow == null) { @@ -162,7 +164,7 @@ public abstract class TemporaryBuffer extends OutputStream { /** * Dumps the entire buffer into the overflow stream, and flushes it. * - * @throws IOException + * @throws java.io.IOException * the overflow stream cannot be started, or the buffer contents * cannot be written to it, or it failed to flush. */ @@ -177,7 +179,7 @@ public abstract class TemporaryBuffer extends OutputStream { * * @param in * the stream to read from, until EOF is reached. - * @throws IOException + * @throws java.io.IOException * an error occurred reading from the input stream, or while * writing to a local temporary file. */ @@ -227,10 +229,8 @@ public abstract class TemporaryBuffer extends OutputStream { * The buffer is only complete after {@link #close()} has been invoked. * * @return the complete byte array; length matches {@link #length()}. - * @throws IOException + * @throws java.io.IOException * an error occurred reading from a local temporary file - * @throws OutOfMemoryError - * the buffer cannot fit in memory */ public byte[] toByteArray() throws IOException { final long len = length(); @@ -253,13 +253,9 @@ public abstract class TemporaryBuffer extends OutputStream { * * @param limit * the maximum number of bytes to be returned - * * @return the byte array limited to {@code limit} bytes. - * @throws IOException + * @throws java.io.IOException * an error occurred reading from a local temporary file - * @throws OutOfMemoryError - * the buffer cannot fit in memory - * * @since 4.2 */ public byte[] toByteArray(int limit) throws IOException { @@ -288,7 +284,7 @@ public abstract class TemporaryBuffer extends OutputStream { * if not null progress updates are sent here. Caller should * initialize the task and the number of work units to <code> * {@link #length()}/1024</code>. - * @throws IOException + * @throws java.io.IOException * an error occurred reading from a temporary file on the local * system, or writing to the output stream. */ @@ -310,14 +306,16 @@ public abstract class TemporaryBuffer extends OutputStream { * * @return a stream to read from the buffer. The caller must close the * stream when it is no longer useful. - * @throws IOException + * @throws java.io.IOException * an error occurred opening the temporary file. */ public InputStream openInputStream() throws IOException { return new BlockInputStream(); } - /** Reset this buffer for reuse, purging all buffered content. */ + /** + * Reset this buffer for reuse, purging all buffered content. + */ public void reset() { if (overflow != null) { destroy(); @@ -334,7 +332,7 @@ public abstract class TemporaryBuffer extends OutputStream { * * @return the output stream to receive the buffered content, followed by * the remaining output. - * @throws IOException + * @throws java.io.IOException * the buffer cannot create the overflow stream. */ protected abstract OutputStream overflow() throws IOException; @@ -363,6 +361,7 @@ public abstract class TemporaryBuffer extends OutputStream { overflow.write(last.buffer, 0, last.count); } + /** {@inheritDoc} */ @Override public void close() throws IOException { if (overflow != null) { @@ -374,7 +373,9 @@ public abstract class TemporaryBuffer extends OutputStream { } } - /** Clear this buffer so it has no data, and cannot be used again. */ + /** + * Clear this buffer so it has no data, and cannot be used again. + */ public void destroy() { blocks = null; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoCRLFInputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoCRLFInputStream.java index 30f9ce95fc..45668255e5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoCRLFInputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoCRLFInputStream.java @@ -91,12 +91,14 @@ public class AutoCRLFInputStream extends InputStream { this.detectBinary = detectBinary; } + /** {@inheritDoc} */ @Override public int read() throws IOException { final int read = read(single, 0, 1); return read == 1 ? single[0] & 0xff : -1; } + /** {@inheritDoc} */ @Override public int read(byte[] bs, final int off, final int len) throws IOException { if (len == 0) @@ -135,6 +137,7 @@ public class AutoCRLFInputStream extends InputStream { return n; } + /** {@inheritDoc} */ @Override public void close() throws IOException { in.close(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoCRLFOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoCRLFOutputStream.java index 3a72f7e1dc..e764389ac8 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoCRLFOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoCRLFOutputStream.java @@ -75,14 +75,18 @@ public class AutoCRLFOutputStream extends OutputStream { private boolean isBinary; /** - * @param out + * <p>Constructor for AutoCRLFOutputStream.</p> + * + * @param out a {@link java.io.OutputStream} object. */ public AutoCRLFOutputStream(OutputStream out) { this(out, true); } /** - * @param out + * <p>Constructor for AutoCRLFOutputStream.</p> + * + * @param out a {@link java.io.OutputStream} object. * @param detectBinary * whether binaries should be detected * @since 4.3 @@ -92,12 +96,14 @@ public class AutoCRLFOutputStream extends OutputStream { this.detectBinary = detectBinary; } + /** {@inheritDoc} */ @Override public void write(int b) throws IOException { onebytebuf[0] = (byte) b; write(onebytebuf, 0, 1); } + /** {@inheritDoc} */ @Override public void write(byte[] b) throws IOException { int overflow = buffer(b, 0, b.length); @@ -105,6 +111,7 @@ public class AutoCRLFOutputStream extends OutputStream { write(b, b.length - overflow, overflow); } + /** {@inheritDoc} */ @Override public void write(byte[] b, final int startOff, final int startLen) throws IOException { @@ -166,6 +173,7 @@ public class AutoCRLFOutputStream extends OutputStream { write(binbuf, 0, cachedLen); } + /** {@inheritDoc} */ @Override public void flush() throws IOException { if (binbufcnt <= binbuf.length) @@ -174,6 +182,7 @@ public class AutoCRLFOutputStream extends OutputStream { out.flush(); } + /** {@inheritDoc} */ @Override public void close() throws IOException { flush(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoLFInputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoLFInputStream.java index 6e33f99127..06f83f3ed9 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoLFInputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoLFInputStream.java @@ -125,12 +125,14 @@ public class AutoLFInputStream extends InputStream { this.abortIfBinary = abortIfBinary; } + /** {@inheritDoc} */ @Override public int read() throws IOException { final int read = read(single, 0, 1); return read == 1 ? single[0] & 0xff : -1; } + /** {@inheritDoc} */ @Override public int read(byte[] bs, final int off, final int len) throws IOException { @@ -171,13 +173,16 @@ public class AutoLFInputStream extends InputStream { } /** - * @return true if the stream has detected as a binary so far + * Whether the stream has detected as a binary so far. + * + * @return true if the stream has detected as a binary so far. * @since 3.3 */ public boolean isBinary() { return isBinary; } + /** {@inheritDoc} */ @Override public void close() throws IOException { in.close(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoLFOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoLFOutputStream.java index c932b00f3c..32226c4af4 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoLFOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoLFOutputStream.java @@ -76,14 +76,24 @@ public class AutoLFOutputStream extends OutputStream { private boolean isBinary; /** + * <p> + * Constructor for AutoLFOutputStream. + * </p> + * * @param out + * an {@link java.io.OutputStream} object. */ public AutoLFOutputStream(OutputStream out) { this(out, true); } /** + * <p> + * Constructor for AutoLFOutputStream. + * </p> + * * @param out + * an {@link java.io.OutputStream} object. * @param detectBinary * whether binaries should be detected */ @@ -92,12 +102,14 @@ public class AutoLFOutputStream extends OutputStream { this.detectBinary = detectBinary; } + /** {@inheritDoc} */ @Override public void write(int b) throws IOException { onebytebuf[0] = (byte) b; write(onebytebuf, 0, 1); } + /** {@inheritDoc} */ @Override public void write(byte[] b) throws IOException { int overflow = buffer(b, 0, b.length); @@ -106,6 +118,7 @@ public class AutoLFOutputStream extends OutputStream { } } + /** {@inheritDoc} */ @Override public void write(byte[] b, final int startOff, final int startLen) throws IOException { @@ -180,6 +193,7 @@ public class AutoLFOutputStream extends OutputStream { write(binbuf, 0, cachedLen); } + /** {@inheritDoc} */ @Override public void flush() throws IOException { if (binbufcnt <= binbuf.length) { @@ -188,6 +202,7 @@ public class AutoLFOutputStream extends OutputStream { out.flush(); } + /** {@inheritDoc} */ @Override public void close() throws IOException { flush(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/CountingOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/CountingOutputStream.java index ad6f1deceb..6fb1e6d698 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/CountingOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/CountingOutputStream.java @@ -46,7 +46,9 @@ package org.eclipse.jgit.util.io; import java.io.IOException; import java.io.OutputStream; -/** Counts the number of bytes written. */ +/** + * Counts the number of bytes written. + */ public class CountingOutputStream extends OutputStream { private final OutputStream out; private long cnt; @@ -61,28 +63,36 @@ public class CountingOutputStream extends OutputStream { this.out = out; } - /** @return current number of bytes written. */ + /** + * Get current number of bytes written. + * + * @return current number of bytes written. + */ public long getCount() { return cnt; } + /** {@inheritDoc} */ @Override public void write(int val) throws IOException { out.write(val); cnt++; } + /** {@inheritDoc} */ @Override public void write(byte[] buf, int off, int len) throws IOException { out.write(buf, off, len); cnt += len; } + /** {@inheritDoc} */ @Override public void flush() throws IOException { out.flush(); } + /** {@inheritDoc} */ @Override public void close() throws IOException { out.close(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/DisabledOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/DisabledOutputStream.java index 9ddf9b3c2b..ec3649523b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/DisabledOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/DisabledOutputStream.java @@ -48,7 +48,9 @@ import java.io.OutputStream; import org.eclipse.jgit.internal.JGitText; -/** An OutputStream which always throws IllegalStateExeption during write. */ +/** + * An OutputStream which always throws IllegalStateExeption during write. + */ public final class DisabledOutputStream extends OutputStream { /** The canonical instance which always throws IllegalStateException. */ public static final DisabledOutputStream INSTANCE = new DisabledOutputStream(); @@ -58,6 +60,7 @@ public final class DisabledOutputStream extends OutputStream { // more than one instance from being created. } + /** {@inheritDoc} */ @Override public void write(int b) throws IOException { // We shouldn't be writing output at this stage, there diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/EolCanonicalizingInputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/EolCanonicalizingInputStream.java index ee729e893e..dd9a95306f 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/EolCanonicalizingInputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/EolCanonicalizingInputStream.java @@ -52,7 +52,7 @@ import java.io.InputStream; * Optionally, a binary check on the first 8000 bytes is performed and in case * of binary files, canonicalization is turned off (for the complete file). * - * @deprecated use {@link AutoLFInputStream} instead + * @deprecated use {@link org.eclipse.jgit.util.io.AutoLFInputStream} instead */ @Deprecated public class EolCanonicalizingInputStream extends AutoLFInputStream { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/EolStreamTypeUtil.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/EolStreamTypeUtil.java index 727c1f4ad6..822961f8de 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/EolStreamTypeUtil.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/EolStreamTypeUtil.java @@ -46,14 +46,13 @@ import java.io.InputStream; import java.io.OutputStream; import org.eclipse.jgit.attributes.Attributes; -import org.eclipse.jgit.lib.Config; import org.eclipse.jgit.lib.CoreConfig.EolStreamType; import org.eclipse.jgit.treewalk.TreeWalk.OperationType; import org.eclipse.jgit.treewalk.WorkingTreeOptions; /** * Utility used to create input and output stream wrappers for - * {@link EolStreamType} + * {@link org.eclipse.jgit.lib.CoreConfig.EolStreamType} * * @since 4.3 */ @@ -71,18 +70,24 @@ public final class EolStreamTypeUtil { * <li>global attributes</li> * <li>info attributes</li> * <li>working tree .gitattributes</li> + * </ul> * * @param op - * is the {@link OperationType} of the current traversal + * is the + * {@link org.eclipse.jgit.treewalk.TreeWalk.OperationType} of + * the current traversal * @param options - * are the {@link Config} options with key - * {@link WorkingTreeOptions#KEY} + * are the {@link org.eclipse.jgit.lib.Config} options with key + * {@link org.eclipse.jgit.treewalk.WorkingTreeOptions#KEY} * @param attrs - * are the {@link Attributes} of the file for which the - * {@link EolStreamType} is to be detected - * - * @return the stream conversion {@link EolStreamType} to be performed for - * the selected {@link OperationType} + * are the {@link org.eclipse.jgit.attributes.Attributes} of the + * file for which the + * {@link org.eclipse.jgit.lib.CoreConfig.EolStreamType} is to be + * detected + * @return the stream conversion + * {@link org.eclipse.jgit.lib.CoreConfig.EolStreamType} to be + * performed for the selected + * {@link org.eclipse.jgit.treewalk.TreeWalk.OperationType} */ public static EolStreamType detectStreamType(OperationType op, WorkingTreeOptions options, Attributes attrs) { @@ -97,11 +102,15 @@ public final class EolStreamTypeUtil { } /** + * Wrap the input stream depending on + * {@link org.eclipse.jgit.lib.CoreConfig.EolStreamType} + * * @param in * original stream * @param conversion * to be performed - * @return the converted stream depending on {@link EolStreamType} + * @return the converted stream depending on + * {@link org.eclipse.jgit.lib.CoreConfig.EolStreamType} */ public static InputStream wrapInputStream(InputStream in, EolStreamType conversion) { @@ -120,11 +129,15 @@ public final class EolStreamTypeUtil { } /** + * Wrap the output stream depending on + * {@link org.eclipse.jgit.lib.CoreConfig.EolStreamType} + * * @param out * original stream * @param conversion * to be performed - * @return the converted stream depending on {@link EolStreamType} + * @return the converted stream depending on + * {@link org.eclipse.jgit.lib.CoreConfig.EolStreamType} */ public static OutputStream wrapOutputStream(OutputStream out, EolStreamType conversion) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/InterruptTimer.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/InterruptTimer.java index 0c5edb0070..f400e50cd3 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/InterruptTimer.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/InterruptTimer.java @@ -88,7 +88,9 @@ public final class InterruptTimer { final AutoKiller autoKiller; - /** Create a new timer with a default thread name. */ + /** + * Create a new timer with a default thread name. + */ public InterruptTimer() { this("JGit-InterruptTimer"); //$NON-NLS-1$ } @@ -123,12 +125,16 @@ public final class InterruptTimer { state.begin(timeout); } - /** Disable the interrupt timer, as the operation is complete. */ + /** + * Disable the interrupt timer, as the operation is complete. + */ public void end() { state.end(); } - /** Shutdown the timer thread, and wait for it to terminate. */ + /** + * Shutdown the timer thread, and wait for it to terminate. + */ public void terminate() { state.terminate(); try { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/IsolatedOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/IsolatedOutputStream.java index 3598a7ba87..5e50995a2a 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/IsolatedOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/IsolatedOutputStream.java @@ -91,11 +91,13 @@ public class IsolatedOutputStream extends OutputStream { new ArrayBlockingQueue<Runnable>(1), new NamedThreadFactory()); } + /** {@inheritDoc} */ @Override public void write(int ch) throws IOException { write(new byte[] { (byte) ch }, 0, 1); } + /** {@inheritDoc} */ @Override public void write(final byte[] buf, final int pos, final int cnt) throws IOException { @@ -109,6 +111,7 @@ public class IsolatedOutputStream extends OutputStream { }); } + /** {@inheritDoc} */ @Override public void flush() throws IOException { checkClosed(); @@ -121,6 +124,7 @@ public class IsolatedOutputStream extends OutputStream { }); } + /** {@inheritDoc} */ @Override public void close() throws IOException { if (!copier.isShutdown()) { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/LimitedInputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/LimitedInputStream.java index d74532fd4a..9ab2caa1ac 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/LimitedInputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/LimitedInputStream.java @@ -51,13 +51,13 @@ import java.io.InputStream; import org.eclipse.jgit.internal.JGitText; /** - * Wraps a {@link InputStream}, limiting the number of bytes which can be - * read. + * Wraps a {@link java.io.InputStream}, limiting the number of bytes which can + * be read. * - * This class was copied and modifed from the Google Guava 16.0. Differently from - * the original Guava code, when a caller tries to read from this stream past - * the given limit and the wrapped stream hasn't yet reached its EOF this class - * will call the limitExceeded method instead of returning EOF. + * This class was copied and modifed from the Google Guava 16.0. Differently + * from the original Guava code, when a caller tries to read from this stream + * past the given limit and the wrapped stream hasn't yet reached its EOF this + * class will call the limitExceeded method instead of returning EOF. * * @since 3.3 */ @@ -80,18 +80,21 @@ public abstract class LimitedInputStream extends FilterInputStream { this.limit = limit; } + /** {@inheritDoc} */ @Override public int available() throws IOException { return (int) Math.min(in.available(), left); } // it's okay to mark even if mark isn't supported, as reset won't work + /** {@inheritDoc} */ @Override public synchronized void mark(int readLimit) { in.mark(readLimit); mark = left; } + /** {@inheritDoc} */ @Override public int read() throws IOException { if (left == 0) { @@ -107,6 +110,7 @@ public abstract class LimitedInputStream extends FilterInputStream { return result; } + /** {@inheritDoc} */ @Override public int read(byte[] b, int off, int len) throws IOException { if (left == 0) { @@ -123,6 +127,7 @@ public abstract class LimitedInputStream extends FilterInputStream { return result; } + /** {@inheritDoc} */ @Override public synchronized void reset() throws IOException { if (!in.markSupported()) @@ -135,6 +140,7 @@ public abstract class LimitedInputStream extends FilterInputStream { left = mark; } + /** {@inheritDoc} */ @Override public long skip(long n) throws IOException { n = Math.min(n, left); @@ -147,10 +153,11 @@ public abstract class LimitedInputStream extends FilterInputStream { * Called when trying to read past the given {@link #limit} and the wrapped * InputStream {@link #in} hasn't yet reached its EOF * - * @throws IOException - * subclasses can throw an IOException when the limit is exceeded. - * The throws IOException will be forwarded back to the caller of - * the read method which read the stream past the limit. + * @throws java.io.IOException + * subclasses can throw an {@link java.io.IOException} when the + * limit is exceeded. The throws java.io.IOException will be + * forwarded back to the caller of the read method which read + * the stream past the limit. */ protected abstract void limitExceeded() throws IOException; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/MessageWriter.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/MessageWriter.java index a675360da1..94e5ef3d74 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/MessageWriter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/MessageWriter.java @@ -66,20 +66,24 @@ import org.eclipse.jgit.util.RawParseUtils; * {@link #toString()} returns all written data, after converting it to a String * under the assumption of UTF-8 encoding. * <p> - * Internally {@link RawParseUtils#decode(byte[])} is used by {@code toString()} - * tries to work out a reasonably correct character set for the raw data. + * Internally {@link org.eclipse.jgit.util.RawParseUtils#decode(byte[])} is used + * by {@code toString()} tries to work out a reasonably correct character set + * for the raw data. */ public class MessageWriter extends Writer { private final ByteArrayOutputStream buf; private final OutputStreamWriter enc; - /** Create an empty writer. */ + /** + * Create an empty writer. + */ public MessageWriter() { buf = new ByteArrayOutputStream(); enc = new OutputStreamWriter(getRawStream(), Constants.CHARSET); } + /** {@inheritDoc} */ @Override public void write(char[] cbuf, int off, int len) throws IOException { synchronized (buf) { @@ -89,6 +93,9 @@ public class MessageWriter extends Writer { } /** + * Get the underlying byte stream that character writes to this writer drop + * into. + * * @return the underlying byte stream that character writes to this writer * drop into. Writes to this stream should should be in UTF-8. */ @@ -96,17 +103,20 @@ public class MessageWriter extends Writer { return buf; } + /** {@inheritDoc} */ @Override public void close() throws IOException { // Do nothing, we are buffered with no resources. } + /** {@inheritDoc} */ @Override public void flush() throws IOException { // Do nothing, we are buffered with no resources. } /** @return string version of all buffered data. */ + /** {@inheritDoc} */ @Override public String toString() { return RawParseUtils.decode(buf.toByteArray()); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/NullOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/NullOutputStream.java index 7b1e932738..f90f7e4164 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/NullOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/NullOutputStream.java @@ -57,16 +57,19 @@ public class NullOutputStream extends OutputStream { // more than one instance from being created. } + /** {@inheritDoc} */ @Override public void write(int b) { // Discard. } + /** {@inheritDoc} */ @Override public void write(byte[] buf) { // Discard. } + /** {@inheritDoc} */ @Override public void write(byte[] buf, int pos, int cnt) { // Discard. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/SafeBufferedOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/SafeBufferedOutputStream.java index 84c339889b..68b417e5d1 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/SafeBufferedOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/SafeBufferedOutputStream.java @@ -46,11 +46,15 @@ import java.io.BufferedOutputStream; import java.io.OutputStream; /** + * <p>SafeBufferedOutputStream class.</p> + * * @deprecated use BufferedOutputStream in Java 8 and later. */ @Deprecated public class SafeBufferedOutputStream extends BufferedOutputStream { /** + * <p>Constructor for SafeBufferedOutputStream.</p> + * * @see BufferedOutputStream#BufferedOutputStream(OutputStream) * @param out * underlying output stream @@ -60,6 +64,8 @@ public class SafeBufferedOutputStream extends BufferedOutputStream { } /** + * <p>Constructor for SafeBufferedOutputStream.</p> + * * @see BufferedOutputStream#BufferedOutputStream(OutputStream, int) * @param out * underlying output stream diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/StreamCopyThread.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/StreamCopyThread.java index 7aba0a583d..5c1af9efad 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/StreamCopyThread.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/StreamCopyThread.java @@ -48,7 +48,9 @@ import java.io.InputStream; import java.io.InterruptedIOException; import java.io.OutputStream; -/** Thread to copy from an input stream to an output stream. */ +/** + * Thread to copy from an input stream to an output stream. + */ public class StreamCopyThread extends Thread { private static final int BUFFER_SIZE = 1024; @@ -98,7 +100,7 @@ public class StreamCopyThread extends Thread { * This method signals to the copy thread that it should stop as soon as * there is no more IO occurring. * - * @throws InterruptedException + * @throws java.lang.InterruptedException * the calling thread was interrupted. */ public void halt() throws InterruptedException { @@ -112,6 +114,7 @@ public class StreamCopyThread extends Thread { } } + /** {@inheritDoc} */ @Override public void run() { try { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TeeInputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TeeInputStream.java index a7a0347401..dee4fe9e91 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TeeInputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TeeInputStream.java @@ -47,15 +47,13 @@ import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; -import org.eclipse.jgit.util.TemporaryBuffer; - /** * Input stream that copies data read to another output stream. * - * This stream is primarily useful with a {@link TemporaryBuffer}, where any - * data read or skipped by the caller is also duplicated into the temporary - * buffer. Later the temporary buffer can then be used instead of the original - * source stream. + * This stream is primarily useful with a + * {@link org.eclipse.jgit.util.TemporaryBuffer}, where any data read or skipped + * by the caller is also duplicated into the temporary buffer. Later the + * temporary buffer can then be used instead of the original source stream. * * During close this stream copies any remaining data from the source stream * into the destination stream. @@ -74,13 +72,14 @@ public class TeeInputStream extends InputStream { * source stream to consume. * @param dst * destination to copy the source to as it is consumed. Typically - * this is a {@link TemporaryBuffer}. + * this is a {@link org.eclipse.jgit.util.TemporaryBuffer}. */ public TeeInputStream(InputStream src, OutputStream dst) { this.src = src; this.dst = dst; } + /** {@inheritDoc} */ @Override public int read() throws IOException { byte[] b = skipBuffer(); @@ -88,6 +87,7 @@ public class TeeInputStream extends InputStream { return n == 1 ? b[0] & 0xff : -1; } + /** {@inheritDoc} */ @Override public long skip(final long count) throws IOException { long skipped = 0; @@ -104,6 +104,7 @@ public class TeeInputStream extends InputStream { return skipped; } + /** {@inheritDoc} */ @Override public int read(byte[] b, int off, int len) throws IOException { if (len == 0) @@ -115,6 +116,7 @@ public class TeeInputStream extends InputStream { return n; } + /** {@inheritDoc} */ @Override public void close() throws IOException { byte[] b = skipBuffer(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/ThrowingPrintWriter.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/ThrowingPrintWriter.java index 5eca0d99e1..caabcef574 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/ThrowingPrintWriter.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/ThrowingPrintWriter.java @@ -64,7 +64,7 @@ public class ThrowingPrintWriter extends Writer { * Construct a JGitPrintWriter * * @param out - * the underlying {@link Writer} + * the underlying {@link java.io.Writer} */ public ThrowingPrintWriter(Writer out) { this.out = out; @@ -76,16 +76,19 @@ public class ThrowingPrintWriter extends Writer { }); } + /** {@inheritDoc} */ @Override public void write(char[] cbuf, int off, int len) throws IOException { out.write(cbuf, off, len); } + /** {@inheritDoc} */ @Override public void flush() throws IOException { out.flush(); } + /** {@inheritDoc} */ @Override public void close() throws IOException { out.close(); @@ -94,8 +97,8 @@ public class ThrowingPrintWriter extends Writer { /** * Print a string and terminate with a line feed. * - * @param s - * @throws IOException + * @param s a {@link java.lang.String} object. + * @throws java.io.IOException */ public void println(String s) throws IOException { print(s + LF); @@ -104,7 +107,7 @@ public class ThrowingPrintWriter extends Writer { /** * Print a platform dependent new line * - * @throws IOException + * @throws java.io.IOException */ public void println() throws IOException { print(LF); @@ -113,8 +116,8 @@ public class ThrowingPrintWriter extends Writer { /** * Print a char * - * @param value - * @throws IOException + * @param value a char. + * @throws java.io.IOException */ public void print(char value) throws IOException { print(String.valueOf(value)); @@ -124,7 +127,8 @@ public class ThrowingPrintWriter extends Writer { * Print an int as string * * @param value - * @throws IOException + * an int. + * @throws java.io.IOException */ public void print(int value) throws IOException { print(String.valueOf(value)); @@ -133,8 +137,8 @@ public class ThrowingPrintWriter extends Writer { /** * Print a long as string * - * @param value - * @throws IOException + * @param value a long. + * @throws java.io.IOException */ public void print(long value) throws IOException { print(String.valueOf(value)); @@ -143,8 +147,8 @@ public class ThrowingPrintWriter extends Writer { /** * Print a short as string * - * @param value - * @throws IOException + * @param value a short. + * @throws java.io.IOException */ public void print(short value) throws IOException { print(String.valueOf(value)); @@ -152,11 +156,13 @@ public class ThrowingPrintWriter extends Writer { /** * Print a formatted message according to - * {@link String#format(String, Object...)}. + * {@link java.lang.String#format(String, Object...)}. * * @param fmt + * a {@link java.lang.String} object. * @param args - * @throws IOException + * objects. + * @throws java.io.IOException */ public void format(String fmt, Object... args) throws IOException { print(String.format(fmt, args)); @@ -166,7 +172,8 @@ public class ThrowingPrintWriter extends Writer { * Print an object's toString representations * * @param any - * @throws IOException + * an object. + * @throws java.io.IOException */ public void print(Object any) throws IOException { out.write(String.valueOf(any)); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TimeoutInputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TimeoutInputStream.java index 1148895cc6..01b25195ff 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TimeoutInputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TimeoutInputStream.java @@ -51,7 +51,9 @@ import java.text.MessageFormat; import org.eclipse.jgit.internal.JGitText; -/** InputStream with a configurable timeout. */ +/** + * InputStream with a configurable timeout. + */ public class TimeoutInputStream extends FilterInputStream { private final InterruptTimer myTimer; @@ -72,12 +74,18 @@ public class TimeoutInputStream extends FilterInputStream { myTimer = timer; } - /** @return number of milliseconds before aborting a read. */ + /** + * Get number of milliseconds before aborting a read. + * + * @return number of milliseconds before aborting a read. + */ public int getTimeout() { return timeout; } /** + * Set number of milliseconds before aborting a read. + * * @param millis * number of milliseconds before aborting a read. Must be > 0. */ @@ -88,6 +96,7 @@ public class TimeoutInputStream extends FilterInputStream { timeout = millis; } + /** {@inheritDoc} */ @Override public int read() throws IOException { try { @@ -100,11 +109,13 @@ public class TimeoutInputStream extends FilterInputStream { } } + /** {@inheritDoc} */ @Override public int read(byte[] buf) throws IOException { return read(buf, 0, buf.length); } + /** {@inheritDoc} */ @Override public int read(byte[] buf, int off, int cnt) throws IOException { try { @@ -117,6 +128,7 @@ public class TimeoutInputStream extends FilterInputStream { } } + /** {@inheritDoc} */ @Override public long skip(long cnt) throws IOException { try { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TimeoutOutputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TimeoutOutputStream.java index 9236d0eb51..ea40133383 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TimeoutOutputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/TimeoutOutputStream.java @@ -50,7 +50,9 @@ import java.text.MessageFormat; import org.eclipse.jgit.internal.JGitText; -/** OutputStream with a configurable timeout. */ +/** + * OutputStream with a configurable timeout. + */ public class TimeoutOutputStream extends OutputStream { private final OutputStream dst; @@ -73,14 +75,21 @@ public class TimeoutOutputStream extends OutputStream { myTimer = timer; } - /** @return number of milliseconds before aborting a write. */ + /** + * Get number of milliseconds before aborting a write. + * + * @return number of milliseconds before aborting a write. + */ public int getTimeout() { return timeout; } /** + * Set number of milliseconds before aborting a write. + * * @param millis - * number of milliseconds before aborting a write. Must be > 0. + * number of milliseconds before aborting a write. Must be > + * 0. */ public void setTimeout(final int millis) { if (millis < 0) @@ -89,6 +98,7 @@ public class TimeoutOutputStream extends OutputStream { timeout = millis; } + /** {@inheritDoc} */ @Override public void write(int b) throws IOException { try { @@ -101,11 +111,13 @@ public class TimeoutOutputStream extends OutputStream { } } + /** {@inheritDoc} */ @Override public void write(byte[] buf) throws IOException { write(buf, 0, buf.length); } + /** {@inheritDoc} */ @Override public void write(byte[] buf, int off, int len) throws IOException { try { @@ -118,6 +130,7 @@ public class TimeoutOutputStream extends OutputStream { } } + /** {@inheritDoc} */ @Override public void flush() throws IOException { try { @@ -130,6 +143,7 @@ public class TimeoutOutputStream extends OutputStream { } } + /** {@inheritDoc} */ @Override public void close() throws IOException { try { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/UnionInputStream.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/UnionInputStream.java index 1c46310ef5..51d3106aa5 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/io/UnionInputStream.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/io/UnionInputStream.java @@ -58,7 +58,7 @@ import java.util.LinkedList; * Currently this stream does not support the mark/reset APIs. If mark and later * reset functionality is needed the caller should wrap this stream with a * {@link java.io.BufferedInputStream}. - * */ + */ public class UnionInputStream extends InputStream { private static final InputStream EOF = new InputStream() { @Override @@ -69,7 +69,9 @@ public class UnionInputStream extends InputStream { private final LinkedList<InputStream> streams = new LinkedList<>(); - /** Create an empty InputStream that is currently at EOF state. */ + /** + * Create an empty InputStream that is currently at EOF state. + */ public UnionInputStream() { // Do nothing. } @@ -122,6 +124,7 @@ public class UnionInputStream extends InputStream { return streams.isEmpty(); } + /** {@inheritDoc} */ @Override public int read() throws IOException { for (;;) { @@ -136,6 +139,7 @@ public class UnionInputStream extends InputStream { } } + /** {@inheritDoc} */ @Override public int read(byte[] b, int off, int len) throws IOException { if (len == 0) @@ -152,11 +156,13 @@ public class UnionInputStream extends InputStream { } } + /** {@inheritDoc} */ @Override public int available() throws IOException { return head().available(); } + /** {@inheritDoc} */ @Override public long skip(final long count) throws IOException { long skipped = 0; @@ -190,6 +196,7 @@ public class UnionInputStream extends InputStream { return skipped; } + /** {@inheritDoc} */ @Override public void close() throws IOException { IOException err = null; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/sha1/SHA1.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/sha1/SHA1.java index 544971199e..9fe01f1d8d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/sha1/SHA1.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/sha1/SHA1.java @@ -70,8 +70,8 @@ import org.slf4j.LoggerFactory; * sha1collisiondetection</a> for more information. * <p> * When detectCollision is true (default), this implementation throws - * {@link Sha1CollisionException} from any digest method if a potential - * collision was detected. + * {@link org.eclipse.jgit.util.sha1.Sha1CollisionException} from any digest + * method if a potential collision was detected. * * @since 4.7 */ @@ -85,7 +85,11 @@ public class SHA1 { DETECT_COLLISIONS = v != null ? Boolean.parseBoolean(v) : true; } - /** @return a new context to compute a SHA-1 hash of data. */ + /** + * Create a new context to compute a SHA-1 hash of data. + * + * @return a new context to compute a SHA-1 hash of data. + */ public static SHA1 newInstance() { return new SHA1(); } @@ -121,6 +125,7 @@ public class SHA1 { * {@code -Dorg.eclipse.jgit.util.sha1.detectCollision=true}. * * @param detect + * a boolean. * @return {@code this} */ public SHA1 setDetectCollision(boolean detect) { @@ -131,7 +136,7 @@ public class SHA1 { /** * Update the digest computation by adding a byte. * - * @param b + * @param b a byte. */ public void update(byte b) { int bufferLen = (int) (length & 63); @@ -503,7 +508,7 @@ public class SHA1 { * Once {@code digest()} is called, this instance should be discarded. * * @return the bytes for the resulting hash. - * @throws Sha1CollisionException + * @throws org.eclipse.jgit.util.sha1.Sha1CollisionException * if a collision was detected and safeHash is false. */ public byte[] digest() throws Sha1CollisionException { @@ -524,7 +529,7 @@ public class SHA1 { * Once {@code digest()} is called, this instance should be discarded. * * @return the ObjectId for the resulting hash. - * @throws Sha1CollisionException + * @throws org.eclipse.jgit.util.sha1.Sha1CollisionException * if a collision was detected and safeHash is false. */ public ObjectId toObjectId() throws Sha1CollisionException { @@ -539,7 +544,7 @@ public class SHA1 { * * @param id * destination to copy the digest to. - * @throws Sha1CollisionException + * @throws org.eclipse.jgit.util.sha1.Sha1CollisionException * if a collision was detected and safeHash is false. */ public void digest(MutableObjectId id) throws Sha1CollisionException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/sha1/Sha1CollisionException.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/sha1/Sha1CollisionException.java index be126a570a..dcefe95498 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/sha1/Sha1CollisionException.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/sha1/Sha1CollisionException.java @@ -49,7 +49,8 @@ import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.lib.ObjectId; /** - * Thrown by {@link SHA1} if it detects a likely hash collision. + * Thrown by {@link org.eclipse.jgit.util.sha1.SHA1} if it detects a likely hash + * collision. * * @since 4.7 */ diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/time/MonotonicClock.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/time/MonotonicClock.java index 794d851903..c7c874d2ac 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/time/MonotonicClock.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/time/MonotonicClock.java @@ -44,7 +44,6 @@ package org.eclipse.jgit.util.time; import java.time.Duration; -import java.util.concurrent.TimeUnit; /** * A provider of time. @@ -53,7 +52,9 @@ import java.util.concurrent.TimeUnit; * source, such as the local system clock. * <p> * MonotonicClocks provide the following behavior, with the assertion always - * being true if {@link ProposedTimestamp#blockUntil(Duration)} is used: + * being true if + * {@link org.eclipse.jgit.util.time.ProposedTimestamp#blockUntil(Duration)} is + * used: * * <pre> * MonotonicClock clk = ...; @@ -64,7 +65,7 @@ import java.util.concurrent.TimeUnit; * } * * try (ProposedTimestamp t2 = clk.propose()) { - * assert t2.millis() > r1; + * assert t2.millis() > r1; * } * </pre> * @@ -83,14 +84,11 @@ public interface MonotonicClock { * by NTP) and return that proposal, concurrently sending network messages * to closely collaborating peers in the same cluster to also ensure their * system clocks are ahead of this time. In such an implementation the - * {@link ProposedTimestamp#blockUntil(Duration)} method would wait for - * replies from the peers indicating their own system clocks have moved past - * the proposed time. + * {@link org.eclipse.jgit.util.time.ProposedTimestamp#blockUntil(Duration)} + * method would wait for replies from the peers indicating their own system + * clocks have moved past the proposed time. * - * @return "now". The value can be immediately accessed by - * {@link ProposedTimestamp#read(TimeUnit)} and friends, but the - * caller must use {@link ProposedTimestamp#blockUntil(Duration)} to - * ensure ordering holds. + * @return a {@link org.eclipse.jgit.util.time.ProposedTimestamp} object. */ ProposedTimestamp propose(); } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/time/MonotonicSystemClock.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/time/MonotonicSystemClock.java index a9f483063c..cce1e11f0d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/time/MonotonicSystemClock.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/time/MonotonicSystemClock.java @@ -51,7 +51,8 @@ import java.util.concurrent.TimeUnit; import java.util.concurrent.atomic.AtomicLong; /** - * A {@link MonotonicClock} based on {@code System.currentTimeMillis}. + * A {@link org.eclipse.jgit.util.time.MonotonicClock} based on + * {@code System.currentTimeMillis}. * * @since 4.6 */ @@ -69,6 +70,7 @@ public class MonotonicSystemClock implements MonotonicClock { } } + /** {@inheritDoc} */ @Override public ProposedTimestamp propose() { final long u = nowMicros(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/util/time/ProposedTimestamp.java b/org.eclipse.jgit/src/org/eclipse/jgit/util/time/ProposedTimestamp.java index c09ab32b68..789950e2ca 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/util/time/ProposedTimestamp.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/util/time/ProposedTimestamp.java @@ -55,7 +55,8 @@ import java.util.concurrent.TimeUnit; import java.util.concurrent.TimeoutException; /** - * A timestamp generated by {@link MonotonicClock#propose()}. + * A timestamp generated by + * {@link org.eclipse.jgit.util.time.MonotonicClock#propose()}. * <p> * ProposedTimestamp implements AutoCloseable so that implementations can * release resources associated with obtaining certainty about time elapsing. @@ -73,10 +74,10 @@ public abstract class ProposedTimestamp implements AutoCloseable { * timestamps to wait on. * @param maxWait * how long to wait for the timestamps. - * @throws InterruptedException + * @throws java.lang.InterruptedException * current thread was interrupted before the waiting process * completed normally. - * @throws TimeoutException + * @throws java.util.concurrent.TimeoutException * the timeout was reached without the proposed timestamp become * certainly in the past. */ @@ -121,31 +122,44 @@ public abstract class ProposedTimestamp implements AutoCloseable { * <p> * This method forces the caller to wait up to {@code timeout} for * {@code this} to pass sufficiently into the past such that the creating - * {@link MonotonicClock} instance will not create an earlier timestamp. + * {@link org.eclipse.jgit.util.time.MonotonicClock} instance will not + * create an earlier timestamp. * * @param maxWait * how long the implementation may block the caller. - * @throws InterruptedException + * @throws java.lang.InterruptedException * current thread was interrupted before the waiting process * completed normally. - * @throws TimeoutException + * @throws java.util.concurrent.TimeoutException * the timeout was reached without the proposed timestamp * becoming certainly in the past. */ public abstract void blockUntil(Duration maxWait) throws InterruptedException, TimeoutException; - /** @return milliseconds since epoch; {@code read(MILLISECONDS}). */ + /** + * Get milliseconds since epoch; {@code read(MILLISECONDS}). + * + * @return milliseconds since epoch; {@code read(MILLISECONDS}). + */ public long millis() { return read(MILLISECONDS); } - /** @return microseconds since epoch; {@code read(MICROSECONDS}). */ + /** + * Get microseconds since epoch; {@code read(MICROSECONDS}). + * + * @return microseconds since epoch; {@code read(MICROSECONDS}). + */ public long micros() { return read(MICROSECONDS); } - /** @return time since epoch, with up to microsecond resolution. */ + /** + * Get time since epoch, with up to microsecond resolution. + * + * @return time since epoch, with up to microsecond resolution. + */ public Instant instant() { long usec = micros(); long secs = usec / 1000000L; @@ -153,22 +167,35 @@ public abstract class ProposedTimestamp implements AutoCloseable { return Instant.ofEpochSecond(secs, nanos); } - /** @return time since epoch, with up to microsecond resolution. */ + /** + * Get time since epoch, with up to microsecond resolution. + * + * @return time since epoch, with up to microsecond resolution. + */ public Timestamp timestamp() { return Timestamp.from(instant()); } - /** @return time since epoch, with up to millisecond resolution. */ + /** + * Get time since epoch, with up to millisecond resolution. + * + * @return time since epoch, with up to millisecond resolution. + */ public Date date() { return new Date(millis()); } - /** Release resources allocated by this timestamp. */ + /** + * {@inheritDoc} + * <p> + * Release resources allocated by this timestamp. + */ @Override public void close() { // Do nothing by default. } + /** {@inheritDoc} */ @Override public String toString() { return instant().toString(); |