motiejus
/
jgit
1
Fork 0
Code Releases Activity

Fix javadoc in org.eclipse.jgit lib package 

Change-Id: I1e85a951488177993521ce177fdea212615e6164
Signed-off-by: Matthias Sohn <matthias.sohn@sap.com>
This commit is contained in:
Matthias Sohn 2017-12-18 16:52:40 +01:00
parent d0342be42d
commit 8a6af368c4
64 changed files with 1215 additions and 550 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
org.eclipse.jgit/src/org/eclipse/jgit/lib/AbbreviatedObjectId.java
View File

@ -52,7 +52,7 @@
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 static final AbbreviatedObjectId fromString(final byte[] buf,
}
/**
* 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 @@ static int mask(final int nibbles, final int word, final int v) {
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 int prefixCompare(final int[] bs, final int p) {
return NB.compareUInt32(w5, mask(5, bs[p + 4]));
}
/** @return value for a fan-out style map, only valid of length &gt;= 2. */
/**
* Get value for a fan-out style map, only valid of length &gt;= 2.
*
* @return value for a fan-out style map, only valid of length &gt;= 2.
*/
public final int getFirstByte() {
return w1 >>> 24;
}
@ -334,11 +351,13 @@ private int mask(final int word, final int v) {
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 boolean equals(final Object o) {
}
/**
* 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 String name() {
return new String(b, 0, nibbles);
}
/** {@inheritDoc} */
@SuppressWarnings("nls")
@Override
public String toString() {

50
org.eclipse.jgit/src/org/eclipse/jgit/lib/AnyObjectId.java
View File

@ -53,9 +53,9 @@
/**
* 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 final int getFirstByte() {
*
* @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 final int getByte(int index) {
}
/**
* {@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 &lt; 0 if this id comes before other; 0 if this id is equal to
* other; &gt; 0 if this id comes after other.
*/
@Override
public final int compareTo(final AnyObjectId other) {
@ -262,6 +261,7 @@ public boolean startsWith(final AbbreviatedObjectId abbr) {
return abbr.prefixCompare(this) == 0;
}
/** {@inheritDoc} */
@Override
public final int hashCode() {
return w2;
@ -278,6 +278,7 @@ public final boolean equals(final AnyObjectId other) {
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 void copyRawTo(final int[] b, final int o) {
*
* @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 @@ private static void writeRawInt(final OutputStream w, int v)
*
* @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 @@ private static void formatHexByte(final byte[] dst, final int p, int w) {
*
* @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 void copyTo(final Writer w) throws IOException {
* 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 @@ static void formatHexChar(final char[] dst, final int p, int w) {
dst[o--] = '0';
}
/** {@inheritDoc} */
@SuppressWarnings("nls")
@Override
public String toString() {
@ -495,6 +497,8 @@ public String toString() {
}
/**
* <p>name.</p>
*
* @return string form of the SHA-1, in lower case hexadecimal.
*/
public final String name() {
@ -502,6 +506,8 @@ public final String name() {
}
/**
* 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 final String getName() {
/**
* 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 AbbreviatedObjectId abbreviate(final int len) {
* 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

19
org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncObjectLoaderQueue.java
View File

@ -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;

18
org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncObjectSizeQueue.java
View File

@ -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();
}

4
org.eclipse.jgit/src/org/eclipse/jgit/lib/AsyncOperation.java
View File

@ -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();
}

82
org.eclipse.jgit/src/org/eclipse/jgit/lib/BaseRepositoryBuilder.java
View File

@ -160,7 +160,11 @@ public B setFS(FS fs) {
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 B setGitDir(File gitDir) {
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 B setObjectDirectory(File objectDirectory) {
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 B addAlternateObjectDirectories(File[] inList) {
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 B setBare() {
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 B setMustExist(boolean mustExist) {
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 B setWorkTree(File workTree) {
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 B setIndexFile(File indexFile) {
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 B findGitDir(File current) {
* 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 B setup() throws IllegalArgumentException, IOException {
* @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 R build() throws IOException {
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 @@ protected void requireGitDirOrWorkTree() {
/**
* 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 @@ protected void setupGitDir() throws IOException {
* 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 @@ protected void setupWorkTree() throws IOException {
/**
* 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 @@ protected void setupInternals() throws IOException {
* 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 @@ protected Config getConfig() throws IOException {
* 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 @@ private File guessWorkTreeOrFail() throws IOException {
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;

63
org.eclipse.jgit/src/org/eclipse/jgit/lib/BatchRefUpdate.java
View File

@ -135,6 +135,9 @@ protected BatchRefUpdate(RefDatabase refdb) {
}
/**
* 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 BatchRefUpdate setAllowNonFastForwards(boolean allow) {
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 String getRefLogMessage() {
* 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 boolean isRefLogIncludingResult() {
/**
* 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 @@ protected boolean isForceRefLog() {
* {@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 BatchRefUpdate setAtomic(boolean atomic) {
}
/**
* Whether updates should be atomic.
*
* @return atomic whether updates should be atomic.
* @since 4.4
*/
@ -335,7 +350,11 @@ protected PushCertificate getPushCertificate() {
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 @@ protected void setPushOptions(List<String> options) {
}
/**
* 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 List<ProposedTimestamp> getProposedTimestamps() {
* 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 BatchRefUpdate addProposedTimestamp(ProposedTimestamp ts) {
* <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 BatchRefUpdate addProposedTimestamp(ProposedTimestamp ts) {
* 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 @@ protected boolean blockUntilTimestamps(Duration maxWait) {
* 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 @@ protected static void addPrefixesTo(String name, Collection<String> out) {
* @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 @@ protected boolean isForceRefLog(ReceiveCommand cmd) {
: isForceRefLog();
}
/** {@inheritDoc} */
@Override
public String toString() {
StringBuilder r = new StringBuilder();

9
org.eclipse.jgit/src/org/eclipse/jgit/lib/BatchingProgressMonitor.java
View File

@ -48,7 +48,9 @@
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 void setDelayStart(long time, TimeUnit unit) {
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 void beginTask(String title, int work) {
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 void endTask() {
}
}
/** {@inheritDoc} */
@Override
public boolean isCancelled() {
return false;

6
org.eclipse.jgit/src/org/eclipse/jgit/lib/BitmapIndex.java
View File

@ -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();
/**

2
org.eclipse.jgit/src/org/eclipse/jgit/lib/BitmapObject.java
View File

@ -50,7 +50,7 @@
*/
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
*/

12
org.eclipse.jgit/src/org/eclipse/jgit/lib/BlobBasedConfig.java
View File

@ -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 BlobBasedConfig(Config base, final byte[] blob)
* 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 @@ private static byte[] read(ObjectReader or, AnyObjectId blobId)
* 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,

2
org.eclipse.jgit/src/org/eclipse/jgit/lib/BlobObjectChecker.java
View File

@ -85,7 +85,7 @@ public void endBlob(AnyObjectId id) {
*
* @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;

15
org.eclipse.jgit/src/org/eclipse/jgit/lib/BranchConfig.java
View File

@ -113,6 +113,8 @@ public BranchConfig(final Config config, String branchName) {
}
/**
* 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 String getTrackingBranch() {
}
/**
* 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 String getRemoteTrackingBranch() {
}
/**
* 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 boolean isRemoteLocal() {
}
/**
* 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 String getRemote() {
}
/**
* 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 String getMerge() {
}
/**
* 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 boolean isRebase() {
/**
* 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() {

10
org.eclipse.jgit/src/org/eclipse/jgit/lib/BranchTrackingStatus.java
View File

@ -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 @@ private BranchTrackingStatus(String remoteTrackingBranch, int aheadCount,
}
/**
* Get full remote-tracking branch name
*
* @return full remote-tracking branch name
*/
public String getRemoteTrackingBranch() {
@ -126,6 +128,9 @@ public String getRemoteTrackingBranch() {
}
/**
* 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 int getAheadCount() {
}
/**
* 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
*/

4
org.eclipse.jgit/src/org/eclipse/jgit/lib/CheckoutEntry.java
View File

@ -8,11 +8,15 @@
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();

48
org.eclipse.jgit/src/org/eclipse/jgit/lib/CommitBuilder.java
View File

@ -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 void setTreeId(AnyObjectId id) {
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 void setAuthor(PersonIdent newAuthor) {
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 void setCommitter(PersonIdent newCommitter) {
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 void addParentId(AnyObjectId additionalParent) {
}
}
/** @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 void setMessage(final String newMessage) {
* 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 void setEncoding(Charset enc) {
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 Charset getEncoding() {
*
* @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 byte[] build() throws UnsupportedEncodingException {
*
* @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 byte[] toByteArray() throws UnsupportedEncodingException {
return build();
}
/** {@inheritDoc} */
@SuppressWarnings("nls")
@Override
public String toString() {

50
org.eclipse.jgit/src/org/eclipse/jgit/lib/Config.java
View File

@ -108,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);
}
@ -126,8 +128,8 @@ public Config(Config defaultConfig) {
}
/**
* 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.
@ -340,8 +342,6 @@ public boolean getBoolean(final String section, String subsection,
/**
* Parse an enumeration from the configuration.
*
* @param <T>
* type of the enumeration object.
* @param section
* section the key is grouped within.
* @param subsection
@ -374,8 +374,6 @@ private static <T> T[] allValuesOf(final T value) {
/**
* 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()}.
@ -471,7 +469,8 @@ public long getTimeUnit(String section, String subsection, String name,
}
/**
* 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.
@ -479,7 +478,8 @@ public long getTimeUnit(String section, String subsection, String name,
* 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,
@ -488,6 +488,9 @@ public List<RefSpec> getRefSpecs(String section, String subsection,
}
/**
* 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
@ -501,16 +504,20 @@ public Set<String> getSubsections(final String section) {
}
/**
* @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
@ -520,6 +527,8 @@ public Set<String> getNames(String section) {
}
/**
* Get the list of names defined for this subsection
*
* @param section
* the section
* @param subsection
@ -531,6 +540,8 @@ public Set<String> getNames(String section, String subsection) {
}
/**
* Get the list of names defined for this section
*
* @param section
* the section
* @param recursive
@ -544,6 +555,8 @@ public Set<String> getNames(String section, boolean recursive) {
}
/**
* Get the list of names defined for this section
*
* @param section
* the section
* @param subsection
@ -600,7 +613,8 @@ public void uncache(final SectionParser<?> parser) {
* 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
@ -755,8 +769,6 @@ public void setBoolean(final String section, final String subsection,
* name = value
* </pre>
*
* @param <T>
* type of the enumeration object.
* @param section
* section name, e.g "branch"
* @param subsection
@ -976,6 +988,8 @@ private static int findSectionEnd(final List<ConfigLine> entries,
}
/**
* Get this configuration, formatted as a Git style text file.
*
* @return this configuration, formatted as a Git style text file.
*/
public String toText() {
@ -1025,7 +1039,7 @@ public String toText() {
*
* @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}.
*/
@ -1114,7 +1128,7 @@ private List<ConfigLine> fromTextRecurse(final String text, int depth)
* 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 ConfigInvalidException
* @throws org.eclipse.jgit.errors.ConfigInvalidException
* if something went wrong while reading the config
* @since 4.10
*/

1
org.eclipse.jgit/src/org/eclipse/jgit/lib/ConfigLine.java
View File

@ -112,6 +112,7 @@ private static boolean eqSameCase(final String a, final String b) {
return a.equals(b);
}
/** {@inheritDoc} */
@SuppressWarnings("nls")
@Override
public String toString() {

10
org.eclipse.jgit/src/org/eclipse/jgit/lib/Constants.java
View File

@ -55,7 +55,9 @@
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 static byte[] encodedTypeString(final int typeCode) {
* <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 static byte[] encodeASCII(final long s) {
* 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.
*/

10
org.eclipse.jgit/src/org/eclipse/jgit/lib/CoreConfig.java
View File

@ -180,6 +180,8 @@ private CoreConfig(final Config rc) {
}
/**
* 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 int getCompression() {
}
/**
* 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 int getPackIndexVersion() {
}
/**
* Whether to log all refUpdates
*
* @return whether to log all refUpdates
*/
public boolean isLogAllRefUpdates() {
@ -201,6 +207,8 @@ public boolean isLogAllRefUpdates() {
}
/**
* Get path of excludesfile
*
* @return path of excludesfile
*/
public String getExcludesFile() {
@ -208,6 +216,8 @@ public String getExcludesFile() {
}
/**
* Get path of attributesfile
*
* @return path of attributesfile
* @since 3.7
*/

10
org.eclipse.jgit/src/org/eclipse/jgit/lib/DefaultTypedConfigGetter.java
View File

@ -57,13 +57,14 @@
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 boolean getBoolean(Config config, String section, String subsection,
}
}
/** {@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 <T extends Enum<?>> T getEnum(Config config, T[] all, String section,
}
}
/** {@inheritDoc} */
@Override
public int getInt(Config config, String section, String subsection,
String name, int defaultValue) {
@ -150,6 +153,7 @@ public int getInt(Config config, String section, String subsection,
.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 long getLong(Config config, String section, String subsection,
}
}
/** {@inheritDoc} */
@Override
public long getTimeUnit(Config config, String section, String subsection,
String name, long defaultValue, TimeUnit wantUnit) {
@ -286,6 +291,7 @@ private static IllegalArgumentException notTimeUnit(String section,
section, name, valueString));
}
/** {@inheritDoc} */
@Override
public @NonNull List<RefSpec> getRefSpecs(Config config, String section,
String subsection, String name) {

5
org.eclipse.jgit/src/org/eclipse/jgit/lib/EmptyProgressMonitor.java
View File

@ -51,26 +51,31 @@
*/
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;

22
org.eclipse.jgit/src/org/eclipse/jgit/lib/FileMode.java
View File

@ -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 @@ private FileMode(int mode, final int expType) {
}
/**
* 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 @@ private FileMode(int mode, final int expType) {
*
* @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 void copyTo(byte[] buf, int ptr) {
}
/**
* 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 int copyToLength() {
/**
* 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 int getObjectType() {
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() {

51
org.eclipse.jgit/src/org/eclipse/jgit/lib/IndexDiff.java
View File

@ -285,12 +285,13 @@ public TreeFilter clone() {
* 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 IndexDiff(Repository repository, String revstr,
* 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 IndexDiff(Repository repository, ObjectId objectId,
}
/**
* Defines how modifications in submodules are treated
*
* @param mode
* defines how modifications in submodules are treated
* @since 3.6
@ -336,7 +340,8 @@ public void setIgnoreSubmoduleMode(IgnoreSubmoduleMode mode) {
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 void setWorkingTreeItFactory(WorkingTreeIteratorFactory wTreeIt) {
* 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 void setFilter(TreeFilter filter) {
* 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 boolean diff() throws IOException {
* 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)
@ -621,6 +626,8 @@ private void addConflict(String path, int stage) {
}
/**
* 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 +635,8 @@ public Set<String> getAdded() {
}
/**
* Get list of files changed from tree to index
*
* @return list of files changed from tree to index
*/
public Set<String> getChanged() {
@ -635,6 +644,8 @@ public Set<String> getChanged() {
}
/**
* 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 +653,8 @@ public Set<String> getRemoved() {
}
/**
* Get list of files in index, but not filesystem
*
* @return list of files in index, but not filesystem
*/
public Set<String> getMissing() {
@ -649,6 +662,8 @@ public Set<String> getMissing() {
}
/**
* 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 +671,8 @@ public Set<String> getModified() {
}
/**
* 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 +680,9 @@ public Set<String> getUntracked() {
}
/**
* 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 +691,11 @@ public Set<String> getConflicting() {
}
/**
* 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 +716,8 @@ public Set<String> getIgnoredNotInIndex() {
}
/**
* Get list of files with the flag assume-unchanged
*
* @return list of files with the flag assume-unchanged
*/
public Set<String> getAssumeUnchanged() {
@ -707,6 +732,8 @@ public Set<String> getAssumeUnchanged() {
}
/**
* Get list of folders containing only untracked files/folders
*
* @return list of folders containing only untracked files/folders
*/
public Set<String> getUntrackedFolders() {
@ -717,7 +744,7 @@ public Set<String> getUntrackedFolders() {
/**
* 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 +756,7 @@ public FileMode getIndexMode(final String path) {
* 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

4
org.eclipse.jgit/src/org/eclipse/jgit/lib/InflaterCache.java
View File

@ -46,7 +46,9 @@
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;

21
org.eclipse.jgit/src/org/eclipse/jgit/lib/MutableObjectId.java
View File

@ -79,15 +79,17 @@ public MutableObjectId() {
*
* @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 @@ private static int set(int w, int index, int value) {
}
}
/** 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 void fromRaw(final int[] ints) {
* 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 void fromRaw(final int[] ints, final int p) {
* 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 @@ private void fromHexString(final byte[] bs, int p) {
}
}
/** {@inheritDoc} */
@Override
public ObjectId toObjectId() {
return new ObjectId(this);

5
org.eclipse.jgit/src/org/eclipse/jgit/lib/NullProgressMonitor.java
View File

@ -56,26 +56,31 @@ private NullProgressMonitor() {
// 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.

67
org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectChecker.java
View File

@ -317,12 +317,12 @@ public ObjectChecker setSafeForMacOS(boolean mac) {
*
* @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 void check(int objType, byte[] raw)
* 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 @@ private void checkPersonIdent(byte[] raw, @Nullable AnyObjectId id)
*
* @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 void checkCommit(byte[] raw) throws CorruptObjectException {
* 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 void checkCommit(@Nullable AnyObjectId id, byte[] raw)
*
* @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 void checkTag(byte[] raw) throws CorruptObjectException {
* 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 @@ else if (cmp == 0)
*
* @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 void checkTree(byte[] raw) throws CorruptObjectException {
* 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 @@ private void report(@NonNull ErrorType err, @Nullable AnyObjectId id,
/**
* 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 void checkPath(String path) throws CorruptObjectException {
/**
* 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 void checkPath(byte[] raw, int ptr, int end)
/**
* 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 @@ private static boolean isPositiveDigit(byte b) {
}
/**
* 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 BlobObjectChecker newBlobObjectChecker() {
/**
* 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 {

29
org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectDatabase.java
View File

@ -52,10 +52,12 @@
* 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 boolean exists() {
/**
* 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 void create() throws IOException {
* @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 boolean has(final AnyObjectId objectId) throws IOException {
*
* @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 ObjectLoader open(final AnyObjectId objectId)
* 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)

6
org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectId.java
View File

@ -252,10 +252,15 @@ private static final ObjectId fromHexString(final byte[] bs, int p) {
* 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 @@ protected ObjectId(final AnyObjectId src) {
w5 = src.w5;
}
/** {@inheritDoc} */
@Override
public ObjectId toObjectId() {
return this;

46
org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdOwnerMap.java
View File

@ -48,10 +48,12 @@
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 @@
* 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 ObjectIdOwnerMap() {
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 V get(final AnyObjectId toFind) {
}
/**
* {@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 boolean contains(final AnyObjectId toFind) {
*
* @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 <Q extends V> void add(final Q newValue) {
* @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 <Q extends V> V addIfAbsent(final Q newValue) {
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>() {

12
org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdRef.java
View File

@ -47,7 +47,10 @@
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 @@ protected ObjectIdRef(@NonNull Storage st, @NonNull String name,
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() {

3
org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdSet.java
View File

@ -48,7 +48,8 @@
* <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
*/

35
org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectIdSubclassMap.java
View File

@ -49,13 +49,15 @@
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 V get(final AnyObjectId toFind) {
}
/**
* {@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 boolean contains(final AnyObjectId toFind) {
*
* @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 <Q extends V> void add(final Q newValue) {
* @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 <Q extends V> V addIfAbsent(final Q newValue) {
}
/**
* 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>() {

27
org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectInserter.java
View File

@ -182,7 +182,9 @@ public void close() {
/** 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 @@ protected byte[] buffer() {
}
/**
* Compute digest to help compute an ObjectId
*
* @return digest to help compute an ObjectId
* @since 4.7
*/
@ -272,7 +276,7 @@ public ObjectId idFor(int type, byte[] data, int off, int len) {
* 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 ObjectId idFor(int objectType, long length, InputStream in)
* 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 ObjectId idFor(TreeFormatter formatter) {
* @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 final ObjectId insert(TreeFormatter formatter) throws IOException {
* @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 final ObjectId insert(CommitBuilder builder) throws IOException {
* @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 final ObjectId insert(TagBuilder builder) throws IOException {
* @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 ObjectId insert(final int type, final byte[] data)
* @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 ObjectId insert(int type, byte[] data, int off, int len)
* 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 ObjectId insert(int objectType, long length, InputStream in)
* 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.
*/
@ -436,13 +441,15 @@ public abstract ObjectId insert(int objectType, long length, InputStream in)
* 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

48
org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectLoader.java
View File

@ -61,16 +61,23 @@
*/
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 boolean isLarge() {
* 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 final byte[] getBytes() throws LargeObjectException {
*
* @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 final byte[] getBytes(int sizeLimit) throws LargeObjectException,
* 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 final byte[] getBytes(int sizeLimit) throws LargeObjectException,
* @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 byte[] getCachedBytes(int sizeLimit) throws LargeObjectException,
* @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 ObjectStream openStream() throws MissingObjectException,
* 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.
*/

72
org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectReader.java
View File

@ -53,13 +53,13 @@
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 AbbreviatedObjectId abbreviate(AnyObjectId objectId)
* [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 AbbreviatedObjectId abbreviate(AnyObjectId objectId, int len)
* 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 Collection<ObjectId> resolve(AbbreviatedObjectId id)
* @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 boolean has(AnyObjectId objectId) throws IOException {
* 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 boolean has(AnyObjectId objectId, int typeHint) throws IOException {
*
* @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 ObjectLoader open(AnyObjectId objectId)
* 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 ObjectLoader open(AnyObjectId objectId, int typeHint)
* 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 void release() {
* 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 long getObjectSize(AnyObjectId objectId, int typeHint)
/**
* 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 void setAvoidUnreachableObjects(boolean avoid) {
* 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 BitmapIndex getBitmapIndex() throws IOException {
}
/**
* @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 ObjectInserter getCreatedFromInserter() {
}
/**
* {@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

16
org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectStream.java
View File

@ -46,12 +46,22 @@
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();
/**

50
org.eclipse.jgit/src/org/eclipse/jgit/lib/PersonIdent.java
View File

@ -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 static void appendSanitized(StringBuilder r, String str) {
* 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 PersonIdent(String aName, String aEmailAddress,
* 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 PersonIdent(final PersonIdent pi, final Date when, final TimeZone tz) {
}
/**
* 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 PersonIdent(final PersonIdent pi, final Date aWhen) {
/**
* 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 PersonIdent(final String aName, final String aEmailAddress,
* 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 @@ private PersonIdent(final UserConfig config) {
}
/**
* 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 @@ private PersonIdent(final UserConfig config) {
* 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 PersonIdent(final String aName, final String aEmailAddress,
}
/**
* Get name of person
*
* @return Name of person
*/
public String getName() {
@ -305,6 +319,8 @@ public String getName() {
}
/**
* Get email address of person
*
* @return email address of person
*/
public String getEmailAddress() {
@ -312,6 +328,8 @@ public String getEmailAddress() {
}
/**
* Get timestamp
*
* @return timestamp
*/
public Date getWhen() {
@ -319,6 +337,8 @@ public Date getWhen() {
}
/**
* 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 TimeZone getTimeZone() {
}
/**
* 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 int getTimeZoneOffset() {
}
/**
* {@inheritDoc}
* <p>
* Hashcode is based only on the email address and timestamp.
*/
@Override
@ -344,6 +368,7 @@ public int hashCode() {
return hc;
}
/** {@inheritDoc} */
@Override
public boolean equals(final Object o) {
if (o instanceof PersonIdent) {
@ -372,6 +397,7 @@ public String toExternalString() {
return r.toString();
}
/** {@inheritDoc} */
@Override
@SuppressWarnings("nls")
public String toString() {

8
org.eclipse.jgit/src/org/eclipse/jgit/lib/ProgressMonitor.java
View File

@ -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();
/**

7
org.eclipse.jgit/src/org/eclipse/jgit/lib/RebaseTodoFile.java
View File

@ -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 RebaseTodoFile(Repository repo) {
* @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 @@ private static RebaseTodoLine parseLine(byte[] buf, int tokenBegin,
* 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 {

21
org.eclipse.jgit/src/org/eclipse/jgit/lib/RebaseTodoLine.java
View File

@ -142,8 +142,11 @@ public RebaseTodoLine(String newComment) {
* 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 RebaseTodoLine(Action action, AbbreviatedObjectId commit,
}
/**
* Get rebase action type
*
* @return rebase action type
*/
public Action getAction() {
@ -167,7 +172,8 @@ public Action getAction() {
* 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 void setAction(Action newAction) throws IllegalTodoFileModification {
/**
* <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 @@ private static IllegalArgumentException createInvalidCommentException(
}
/**
* 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 AbbreviatedObjectId getCommit() {
}
/**
* 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 String getShortMessage() {
}
/**
* 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 String getComment() {
return comment;
}
/** {@inheritDoc} */
@SuppressWarnings("nls")
@Override
public String toString() {

14
org.eclipse.jgit/src/org/eclipse/jgit/lib/Ref.java
View File

@ -47,7 +47,8 @@
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 boolean isPacked() {
/**
* 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 boolean isPacked() {
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();

1
org.eclipse.jgit/src/org/eclipse/jgit/lib/RefComparator.java
View File

@ -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);

73
org.eclipse.jgit/src/org/eclipse/jgit/lib/RefDatabase.java
View File

@ -55,11 +55,13 @@
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 Collection<String> getConflictingNames(String name)
* 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 RefUpdate newUpdate(String name, boolean detach)
* @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 BatchRefUpdate newBatchUpdate() {
* 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 boolean performsAtomicTransactions() {
* 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 boolean performsAtomicTransactions() {
* @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 Ref exactRef(String name) throws IOException {
* 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 Map<String, Ref> exactRef(String... refs) throws IOException {
* @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 Ref firstExactRef(String... refs) throws IOException {
* @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 Ref firstExactRef(String... refs) throws IOException {
* 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 Ref firstExactRef(String... refs) throws IOException {
* 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 Ref firstExactRef(String... refs) throws IOException {
* 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

25
org.eclipse.jgit/src/org/eclipse/jgit/lib/RefRename.java
View File

@ -86,7 +86,11 @@ protected RefRename(final RefUpdate src, final RefUpdate dst) {
+ 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 void setRefLogMessage(final String msg) {
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 Result getResult() {
}
/**
* 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 Result rename() throws IOException {
}
/**
* 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 {

87
org.eclipse.jgit/src/org/eclipse/jgit/lib/RefUpdate.java
View File

@ -233,10 +233,18 @@ protected RefUpdate(final Ref ref) {
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 @@ protected RefUpdate(final Ref ref) {
* 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 String getName() {
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 void setNewObjectId(final AnyObjectId id) {
}
/**
* 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 void setForceUpdate(final boolean b) {
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 String getRefLogMessage() {
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 @@ else if (msg == null && appendStatus) {
}
}
/** 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 @@ private void requireCanDoUpdate() {
* 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 Result forceUpdate() throws IOException {
* </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 Result update() throws IOException {
* 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 @@ Result execute(Result status) throws IOException {
* </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 Result delete() throws IOException {
* 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 @@ Result execute(Result status) throws IOException {
* @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 @@ && getRefDatabase().isNameConflicting(getName())) {
* are checked explicitly.
*
* @param check
* whether to enable the check for conflicting ref names.
* @since 3.0
*/
public void setCheckConflicting(boolean check) {

33
org.eclipse.jgit/src/org/eclipse/jgit/lib/RefWriter.java
View File

@ -56,8 +56,8 @@
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 RefWriter(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.
@ -88,6 +92,8 @@ public RefWriter(Map<String, 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.
@ -97,13 +103,13 @@ public RefWriter(RefList<Ref> refs) {
}
/**
* 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 void writeInfoRefs() throws IOException {
}
/**
* 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 void writePackedRefs() throws IOException {
* 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;

15
org.eclipse.jgit/src/org/eclipse/jgit/lib/ReflogEntry.java
View File

@ -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();

14
org.eclipse.jgit/src/org/eclipse/jgit/lib/ReflogReader.java
View File

@ -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;

252
org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java
View File

@ -83,7 +83,6 @@
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;
@ -106,9 +105,9 @@
* 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.
@ -129,7 +128,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;
}
@ -166,7 +169,11 @@ protected Repository(final BaseRepositoryBuilder options) {
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;
@ -193,7 +200,7 @@ public void fireEvent(RepositoryEvent<?> event) {
* 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 {
@ -207,12 +214,14 @@ public void create() throws IOException {
* @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.
*/
/*
@ -227,44 +236,64 @@ public File getDirectory() {
}
/**
* 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.
*/
@ -280,7 +309,11 @@ public FS getFS() {
}
/**
* 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.
*/
@ -301,10 +334,11 @@ public boolean hasObject(AnyObjectId objectId) {
*
* @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
@ -323,16 +357,17 @@ public ObjectLoader open(final AnyObjectId objectId)
* 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
@ -350,7 +385,7 @@ public ObjectLoader open(AnyObjectId objectId, int typeHint)
* @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.
*/
@ -369,7 +404,7 @@ public RefUpdate updateRef(final String ref) throws IOException {
* @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.
*/
@ -386,9 +421,8 @@ public RefUpdate updateRef(final String ref, final boolean detach) throws IOExce
* @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 {
@ -432,17 +466,17 @@ public RefRename renameRef(final String fromRef, final String toRef) throws IOEx
* 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
@ -466,11 +500,11 @@ public ObjectId resolve(final String revstr)
* 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)
@ -889,12 +923,18 @@ else if (matches.size() == 1)
}
}
/** 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();
@ -930,6 +970,7 @@ protected void doClose() {
getRefDatabase().close();
}
/** {@inheritDoc} */
@Override
@NonNull
public String toString() {
@ -959,7 +1000,7 @@ public String toString() {
* 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 {
@ -987,7 +1028,7 @@ public String getFullBranch() throws IOException {
* @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 {
@ -1020,7 +1061,7 @@ public Set<ObjectId> getAdditionalHaves() {
* "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.
*/
@ -1038,7 +1079,7 @@ public Ref getRef(final String name) throws IOException {
* 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
@ -1054,7 +1095,7 @@ public Ref exactRef(String name) throws IOException {
* "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
@ -1063,6 +1104,8 @@ public Ref findRef(String name) throws IOException {
}
/**
* Get mutable map of all known refs
*
* @return mutable map of all known refs (heads, tags, remotes).
*/
@NonNull
@ -1075,6 +1118,8 @@ public Map<String, Ref> getAllRefs() {
}
/**
* 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").
@ -1092,7 +1137,8 @@ public Map<String, Ref> getTags() {
* 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
@ -1114,6 +1160,8 @@ public Ref peel(final Ref ref) {
}
/**
* Get a map with all objects referenced by a peeled ref.
*
* @return a map with all objects referenced by a peeled ref.
*/
@NonNull
@ -1141,9 +1189,11 @@ public Map<AnyObjectId, Set<Ref>> getAllRefsByPeeledObjectId() {
}
/**
* 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()}.
*/
@ -1163,11 +1213,11 @@ public File getIndexFile() throws NoWorkTreeException {
* @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
*/
@ -1190,12 +1240,12 @@ public RevCommit parseCommit(AnyObjectId id) throws IncorrectObjectTypeException
*
* @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.
*/
@ -1214,13 +1264,13 @@ public DirCache readDirCache() throws NoWorkTreeException,
*
* @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.
*/
@ -1239,7 +1289,9 @@ public void onIndexChanged(IndexChangedEvent event) {
}
/**
* @return an important state
* Get the repository state
*
* @return the repository state
*/
@NonNull
public RepositoryState getRepositoryState() {
@ -1320,8 +1372,7 @@ public RepositoryState getRepositoryState() {
*
* 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) {
@ -1392,7 +1443,6 @@ public static boolean isValidRefName(final String refName) {
*
* @param name
* to normalize
*
* @return The normalized name or an empty String if it is {@code null} or
* empty.
* @since 4.7
@ -1499,6 +1549,8 @@ public static String stripWorkDir(File workDir, File file) {
}
/**
* Whether this repository is bare
*
* @return true if this is bare, which implies it has no working directory.
*/
public boolean isBare() {
@ -1506,9 +1558,12 @@ public boolean isBare() {
}
/**
* 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()}.
*/
@ -1522,7 +1577,7 @@ public File getWorkTree() throws NoWorkTreeException {
/**
* Force a scan for changed refs.
*
* @throws IOException
* @throws java.io.IOException
*/
public abstract void scanForRepoChanges() throws IOException;
@ -1532,8 +1587,10 @@ public File getWorkTree() throws NoWorkTreeException {
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
@ -1548,7 +1605,10 @@ public static String shortenRefName(String refName) {
}
/**
* 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/&lt;remote&gt;</code> prefix, if
* <code>refName</code> represents a remote tracking branch;
@ -1566,7 +1626,10 @@ public String shortenRemoteBranchName(String refName) {
}
/**
* 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/&lt;remote&gt;</code> prefix, if
* <code>refName</code> represents a remote tracking branch;
@ -1587,7 +1650,7 @@ public String getRemoteName(String refName) {
* 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
*/
@ -1601,7 +1664,7 @@ public String getGitwebDescription() throws IOException {
*
* @param description
* new description; null to clear the description.
* @throws IOException
* @throws java.io.IOException
* description cannot be persisted.
* @since 4.6
*/
@ -1611,10 +1674,13 @@ public void setGitwebDescription(@Nullable String description)
}
/**
* 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
*/
@ -1629,8 +1695,8 @@ public abstract ReflogReader getReflogReader(String refName)
*
* @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()}.
*/
@ -1648,8 +1714,7 @@ public String readMergeCommitMsg() throws IOException, NoWorkTreeException {
* @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);
@ -1663,8 +1728,8 @@ public void writeMergeCommitMsg(String msg) throws IOException {
*
* @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
@ -1682,8 +1747,7 @@ public String readCommitEditMsg() throws IOException, NoWorkTreeException {
* @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 {
@ -1699,8 +1763,8 @@ public void writeCommitEditMsg(String msg) throws IOException {
* @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()}.
*/
@ -1731,7 +1795,7 @@ public List<ObjectId> readMergeHeads() throws IOException, NoWorkTreeException {
* @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);
@ -1743,8 +1807,8 @@ public void writeMergeHeads(List<? extends ObjectId> heads) throws IOException {
* @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()}.
*/
@ -1767,8 +1831,8 @@ public ObjectId readCherryPickHead() throws IOException,
* @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()}.
*/
@ -1790,7 +1854,7 @@ public ObjectId readRevertHead() throws IOException, NoWorkTreeException {
* @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)
@ -1805,7 +1869,7 @@ public void writeCherryPickHead(ObjectId head) throws IOException {
* @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)
@ -1819,7 +1883,7 @@ public void writeRevertHead(ObjectId head) throws IOException {
* @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)
@ -1833,8 +1897,8 @@ public void writeOrigHead(ObjectId head) throws IOException {
* @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()}.
*/
@ -1854,7 +1918,7 @@ public ObjectId readOrigHead() throws IOException, NoWorkTreeException {
*
* @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()}.
@ -1873,8 +1937,7 @@ public String readSquashCommitMsg() throws IOException {
* @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);
@ -1970,7 +2033,7 @@ private void writeHeadsFile(List<? extends ObjectId> heads, String filename)
* @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
@ -1990,7 +2053,7 @@ public List<RebaseTodoLine> readRebaseTodo(String path,
* 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,
@ -2000,6 +2063,8 @@ public void writeRebaseTodoFile(String path, List<RebaseTodoLine> steps,
}
/**
* Get the names of all known remotes
*
* @return the names of all known remotes
* @since 3.4
*/
@ -2016,7 +2081,8 @@ public Set<String> getRemoteNames() {
* objects.
* <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

2
org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryBuilder.java
View File

@ -46,7 +46,7 @@
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

43
org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryCache.java
View File

@ -62,7 +62,9 @@
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 final static Logger LOG = LoggerFactory
.getLogger(RepositoryCache.class);
@ -73,15 +75,17 @@ public class 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 static Repository open(final Key location) throws IOException,
* 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 static Repository open(final Key location, final boolean mustExist)
* 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 static void close(@NonNull final Repository db) {
* <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 static void unregister(final Repository db) {
* <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 static void unregister(Key location) {
}
/**
* 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 @@ static boolean isCached(@NonNull Repository repo) {
return cache.cacheMap.get(key) == repo;
}
/** Unregister all repositories from the cache. */
/**
* Unregister all repositories from the cache.
*/
public static void clear() {
cache.clearAll();
}

23
org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryCacheConfig.java
View File

@ -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 void setExpireAfter(long expireAfterMillis) {
}
/**
* 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 long getCleanupDelay() {
}
/**
* 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

4
org.eclipse.jgit/src/org/eclipse/jgit/lib/RepositoryState.java
View File

@ -381,7 +381,9 @@ public String getDescription() {
};
/**
* @return true if changing HEAD is sane.
* Whether checkout can be done.
*
* @return whether checkout can be done.
*/
public abstract boolean canCheckout();

11
org.eclipse.jgit/src/org/eclipse/jgit/lib/StoredConfig.java
View File

@ -51,7 +51,9 @@
* 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 StoredConfig(Config defaultConfig) {
* 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 StoredConfig(Config defaultConfig) {
/**
* 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();

12
org.eclipse.jgit/src/org/eclipse/jgit/lib/SymbolicRef.java
View File

@ -47,7 +47,8 @@
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 SymbolicRef(@NonNull String refName, @NonNull Ref target) {
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 Ref getLeaf() {
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() {

31
org.eclipse.jgit/src/org/eclipse/jgit/lib/TagBuilder.java
View File

@ -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 void setObjectId(RevObject obj) {
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 void setTag(String shortName) {
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 void setTagger(PersonIdent taggerIdent) {
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 byte[] toByteArray() {
return build();
}
/** {@inheritDoc} */
@SuppressWarnings("nls")
@Override
public String toString() {

12
org.eclipse.jgit/src/org/eclipse/jgit/lib/TextProgressMonitor.java
View File

@ -51,13 +51,17 @@
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 TextProgressMonitor(Writer out) {
this.write = true;
}
/** {@inheritDoc} */
@Override
protected void onUpdate(String taskName, int workCurr) {
StringBuilder s = new StringBuilder();
@ -80,6 +85,7 @@ protected void onUpdate(String taskName, int workCurr) {
send(s);
}
/** {@inheritDoc} */
@Override
protected void onEndTask(String taskName, int workCurr) {
StringBuilder s = new StringBuilder();
@ -97,6 +103,7 @@ private void format(StringBuilder s, String taskName, int workCurr) {
s.append(workCurr);
}
/** {@inheritDoc} */
@Override
protected void onUpdate(String taskName, int cmp, int totalWork, int pcnt) {
StringBuilder s = new StringBuilder();
@ -104,6 +111,7 @@ protected void onUpdate(String taskName, int cmp, int totalWork, int pcnt) {
send(s);
}
/** {@inheritDoc} */
@Override
protected void onEndTask(String taskName, int cmp, int totalWork, int pcnt) {
StringBuilder s = new StringBuilder();

18
org.eclipse.jgit/src/org/eclipse/jgit/lib/ThreadSafeProgressMonitor.java
View File

@ -48,7 +48,8 @@
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 ThreadSafeProgressMonitor(ProgressMonitor pm) {
this.process = new Semaphore(0);
}
/** {@inheritDoc} */
@Override
public void start(int totalTasks) {
if (!isMainThread())
@ -94,6 +96,7 @@ public void start(int totalTasks) {
pm.start(totalTasks);
}
/** {@inheritDoc} */
@Override
public void beginTask(String title, int totalWork) {
if (!isMainThread())
@ -101,7 +104,9 @@ public void beginTask(String title, int totalWork) {
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 void startWorkers(int count) {
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 void pollForUpdates() {
* 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 @@ private void doUpdates() {
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 boolean isCancelled() {
}
}
/** {@inheritDoc} */
@Override
public void endTask() {
if (!isMainThread())

18
org.eclipse.jgit/src/org/eclipse/jgit/lib/TreeFormatter.java
View File

@ -94,7 +94,9 @@ public static int entrySize(FileMode mode, int nameLen) {
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 TreeFormatter(int size) {
}
/**
* 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 void append(String name, RevCommit commit) {
}
/**
* 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 void append(String name, RevTree tree) {
}
/**
* 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 @@ private void fmtOverflowBuffer(byte[] nameBuf, int namePos, int nameLen,
* @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 ObjectId insertTo(ObjectInserter ins) throws IOException {
/**
* 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 ObjectId computeId(ObjectInserter ins) {
* 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 byte[] toByteArray() {
}
}
/** {@inheritDoc} */
@SuppressWarnings("nls")
@Override
public String toString() {

22
org.eclipse.jgit/src/org/eclipse/jgit/lib/TypedConfigGetter.java
View File

@ -50,15 +50,15 @@
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 @@ boolean getBoolean(Config config, String section, String subsection,
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 @@ <T extends Enum<?>> T getEnum(Config config, T[] all, String section,
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 @@ int getInt(Config config, String section, String subsection, String name,
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 @@ long getLong(Config config, String section, String subsection, String name,
/**
* 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 @@ long getTimeUnit(Config config, String section, String subsection,
/**
* 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 @@ long getTimeUnit(Config config, String section, String subsection,
* 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,

37
org.eclipse.jgit/src/org/eclipse/jgit/lib/UserConfig.java
View File

@ -48,7 +48,9 @@
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 @@ private UserConfig(final Config rc) {
}
/**
* 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 String getAuthorName() {
}
/**
* 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 String getCommitterName() {
}
/**
* @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 boolean isAuthorNameImplicit() {
}
/**
* 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 boolean isAuthorEmailImplicit() {
}
/**
* 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 boolean isCommitterNameImplicit() {
}
/**
* 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

2
org.eclipse.jgit/src/org/eclipse/jgit/lib/internal/WorkQueue.java
View File

@ -95,6 +95,8 @@ protected void finalize() {
}
/**
* Get the WorkQueue's executor
*
* @return the WorkQueue's executor
*/
public static ScheduledThreadPoolExecutor getExecutor() {