Browse Source

Fix javadoc in org.eclipse.jgit storage/file and pack package

Change-Id: If1fee165782823dc21d896073f60ee838365463d
Signed-off-by: Matthias Sohn <matthias.sohn@sap.com>
stable-4.10
Matthias Sohn 7 years ago
parent
commit
56cc6afeba
  1. 27
      org.eclipse.jgit/src/org/eclipse/jgit/storage/file/FileBasedConfig.java
  2. 15
      org.eclipse.jgit/src/org/eclipse/jgit/storage/file/FileRepositoryBuilder.java
  3. 53
      org.eclipse.jgit/src/org/eclipse/jgit/storage/file/WindowCacheConfig.java
  4. 23
      org.eclipse.jgit/src/org/eclipse/jgit/storage/pack/PackConfig.java
  5. 92
      org.eclipse.jgit/src/org/eclipse/jgit/storage/pack/PackStatistics.java

27
org.eclipse.jgit/src/org/eclipse/jgit/storage/file/FileBasedConfig.java

@ -115,27 +115,29 @@ public class FileBasedConfig extends StoredConfig {
this.hash = ObjectId.zeroId();
}
/** {@inheritDoc} */
@Override
protected boolean notifyUponTransientChanges() {
// we will notify listeners upon save()
return false;
}
/** @return location of the configuration file on disk */
/**
* Get location of the configuration file on disk
*
* @return location of the configuration file on disk
*/
public final File getFile() {
return configFile;
}
/**
* {@inheritDoc}
* <p>
* Load the configuration as a Git text style configuration file.
* <p>
* If the file does not exist, this configuration is cleared, and thus
* behaves the same as though the file exists, but is empty.
*
* @throws IOException
* the file could not be read (but does exist).
* @throws ConfigInvalidException
* the file is not a properly formatted configuration file.
*/
@Override
public void load() throws IOException, ConfigInvalidException {
@ -178,6 +180,8 @@ public class FileBasedConfig extends StoredConfig {
}
/**
* {@inheritDoc}
* <p>
* Save the configuration as a Git text style configuration file.
* <p>
* <b>Warning:</b> Although this method uses the traditional Git file
@ -185,9 +189,6 @@ public class FileBasedConfig extends StoredConfig {
* configuration file, it does not ensure that the file has not been
* modified since the last read, which means updates performed by other
* objects accessing the same backing file may be lost.
*
* @throws IOException
* the file could not be written.
*/
@Override
public void save() throws IOException {
@ -221,6 +222,7 @@ public class FileBasedConfig extends StoredConfig {
fireConfigChangedEvent();
}
/** {@inheritDoc} */
@Override
public void clear() {
hash = hash(new byte[0]);
@ -231,6 +233,7 @@ public class FileBasedConfig extends StoredConfig {
return ObjectId.fromRaw(Constants.newMessageDigest().digest(rawText));
}
/** {@inheritDoc} */
@SuppressWarnings("nls")
@Override
public String toString() {
@ -238,14 +241,18 @@ public class FileBasedConfig extends StoredConfig {
}
/**
* Whether the currently loaded configuration file is outdated
*
* @return returns true if the currently loaded configuration file is older
* than the file on disk
* than the file on disk
*/
public boolean isOutdated() {
return snapshot.isModified(getFile());
}
/**
* {@inheritDoc}
*
* @since 4.10
*/
@Override

15
org.eclipse.jgit/src/org/eclipse/jgit/storage/file/FileRepositoryBuilder.java

@ -52,7 +52,7 @@ import org.eclipse.jgit.lib.BaseRepositoryBuilder;
import org.eclipse.jgit.lib.Repository;
/**
* Constructs a {@link FileRepository}.
* Constructs a {@link org.eclipse.jgit.internal.storage.file.FileRepository}.
* <p>
* Applications must set one of {@link #setGitDir(File)} or
* {@link #setWorkTree(File)}, or use {@link #readEnvironment()} or
@ -73,18 +73,14 @@ import org.eclipse.jgit.lib.Repository;
public class FileRepositoryBuilder extends
BaseRepositoryBuilder<FileRepositoryBuilder, Repository> {
/**
* {@inheritDoc}
* <p>
* Create a repository matching the configuration in this builder.
* <p>
* If an option was not set, the build method will try to default the option
* based on other options. If insufficient information is available, an
* exception is thrown to the caller.
*
* @return a repository matching this configuration.
* @throws IllegalArgumentException
* insufficient parameters were set.
* @throws IOException
* the repository could not be accessed to configure the rest of
* the builder's parameters.
* @since 3.0
*/
@Override
@ -96,12 +92,13 @@ public class FileRepositoryBuilder extends
}
/**
* Convenience factory method to construct a {@link FileRepository}.
* Convenience factory method to construct a
* {@link org.eclipse.jgit.internal.storage.file.FileRepository}.
*
* @param gitDir
* {@code GIT_DIR}, the repository meta directory.
* @return a repository matching this configuration.
* @throws IOException
* @throws java.io.IOException
* the repository could not be accessed to configure the rest of
* the builder's parameters.
* @since 3.0

53
org.eclipse.jgit/src/org/eclipse/jgit/storage/file/WindowCacheConfig.java

@ -47,7 +47,9 @@ import org.eclipse.jgit.internal.storage.file.WindowCache;
import org.eclipse.jgit.lib.Config;
import org.eclipse.jgit.storage.pack.PackConfig;
/** Configuration parameters for JVM-wide buffer cache used by JGit. */
/**
* Configuration parameters for JVM-wide buffer cache used by JGit.
*/
public class WindowCacheConfig {
/** 1024 (number of bytes in one kibibyte/kilobyte) */
public static final int KB = 1024;
@ -67,7 +69,9 @@ public class WindowCacheConfig {
private int streamFileThreshold;
/** Create a default configuration. */
/**
* Create a default configuration.
*/
public WindowCacheConfig() {
packedGitOpenFiles = 128;
packedGitLimit = 10 * MB;
@ -78,6 +82,8 @@ public class WindowCacheConfig {
}
/**
* Get maximum number of streams to open at a time.
*
* @return maximum number of streams to open at a time. Open packs count
* against the process limits. <b>Default is 128.</b>
*/
@ -86,6 +92,8 @@ public class WindowCacheConfig {
}
/**
* Set maximum number of streams to open at a time.
*
* @param fdLimit
* maximum number of streams to open at a time. Open packs count
* against the process limits
@ -95,6 +103,9 @@ public class WindowCacheConfig {
}
/**
* Get maximum number bytes of heap memory to dedicate to caching pack file
* data.
*
* @return maximum number bytes of heap memory to dedicate to caching pack
* file data. <b>Default is 10 MB.</b>
*/
@ -103,6 +114,9 @@ public class WindowCacheConfig {
}
/**
* Set maximum number bytes of heap memory to dedicate to caching pack file
* data.
*
* @param newLimit
* maximum number bytes of heap memory to dedicate to caching
* pack file data.
@ -112,6 +126,9 @@ public class WindowCacheConfig {
}
/**
* Get size in bytes of a single window mapped or read in from the pack
* file.
*
* @return size in bytes of a single window mapped or read in from the pack
* file. <b>Default is 8 KB.</b>
*/
@ -120,6 +137,8 @@ public class WindowCacheConfig {
}
/**
* Set size in bytes of a single window read in from the pack file.
*
* @param newSize
* size in bytes of a single window read in from the pack file.
*/
@ -128,25 +147,32 @@ public class WindowCacheConfig {
}
/**
* @return true enables use of Java NIO virtual memory mapping for windows;
* false reads entire window into a byte[] with standard read calls.
* <b>Default false.</b>
* Whether to use Java NIO virtual memory mapping for windows
*
* @return {@code true} enables use of Java NIO virtual memory mapping for
* windows; false reads entire window into a byte[] with standard
* read calls. <b>Default false.</b>
*/
public boolean isPackedGitMMAP() {
return packedGitMMAP;
}
/**
* Set whether to enable use of Java NIO virtual memory mapping for windows
*
* @param usemmap
* true enables use of Java NIO virtual memory mapping for
* windows; false reads entire window into a byte[] with standard
* read calls.
* {@code true} enables use of Java NIO virtual memory mapping
* for windows; false reads entire window into a byte[] with
* standard read calls.
*/
public void setPackedGitMMAP(final boolean usemmap) {
packedGitMMAP = usemmap;
}
/**
* Get maximum number of bytes to cache in delta base cache for inflated,
* recently accessed objects, without delta chains.
*
* @return maximum number of bytes to cache in delta base cache for
* inflated, recently accessed objects, without delta chains.
* <b>Default 10 MB.</b>
@ -156,6 +182,9 @@ public class WindowCacheConfig {
}
/**
* Set maximum number of bytes to cache in delta base cache for inflated,
* recently accessed objects, without delta chains.
*
* @param newLimit
* maximum number of bytes to cache in delta base cache for
* inflated, recently accessed objects, without delta chains.
@ -164,12 +193,18 @@ public class WindowCacheConfig {
deltaBaseCacheLimit = newLimit;
}
/** @return the size threshold beyond which objects must be streamed. */
/**
* Get the size threshold beyond which objects must be streamed.
*
* @return the size threshold beyond which objects must be streamed.
*/
public int getStreamFileThreshold() {
return streamFileThreshold;
}
/**
* Set new byte limit for objects that must be streamed.
*
* @param newLimit
* new byte limit for objects that must be streamed. Objects
* smaller than this size can be obtained as a contiguous byte

23
org.eclipse.jgit/src/org/eclipse/jgit/storage/pack/PackConfig.java

@ -262,7 +262,9 @@ public class PackConfig {
private boolean singlePack;
/** Create a default configuration. */
/**
* Create a default configuration.
*/
public PackConfig() {
// Fields are initialized to defaults.
}
@ -280,7 +282,8 @@ public class PackConfig {
}
/**
* Create a configuration honoring settings in a {@link Config}.
* Create a configuration honoring settings in a
* {@link org.eclipse.jgit.lib.Config}.
*
* @param cfg
* the source to read settings from. The source is not retained
@ -531,6 +534,9 @@ public class PackConfig {
}
/**
* Whether existing delta chains should be cut at
* {@link #getMaxDeltaDepth()}.
*
* @return true if existing delta chains should be cut at
* {@link #getMaxDeltaDepth()}. Default is false, allowing existing
* chains to be of any length.
@ -558,9 +564,11 @@ public class PackConfig {
}
/**
* Whether all of refs/* should be packed in a single pack.
*
* @return true if all of refs/* should be packed in a single pack. Default
* is false, packing a separate GC_REST pack for references outside
* of refs/heads/* and refs/tags/*.
* is false, packing a separate GC_REST pack for references outside
* of refs/heads/* and refs/tags/*.
* @since 4.9
*/
public boolean getSinglePack() {
@ -785,7 +793,11 @@ public class PackConfig {
this.threads = threads;
}
/** @return the preferred thread pool to execute delta search on. */
/**
* Get the preferred thread pool to execute delta search on.
*
* @return the preferred thread pool to execute delta search on.
*/
public Executor getExecutor() {
return executor;
}
@ -1073,6 +1085,7 @@ public class PackConfig {
getBitmapInactiveBranchAgeInDays()));
}
/** {@inheritDoc} */
@Override
public String toString() {
final StringBuilder b = new StringBuilder();

92
org.eclipse.jgit/src/org/eclipse/jgit/storage/pack/PackStatistics.java

@ -254,7 +254,8 @@ public class PackStatistics {
private Accumulator statistics;
/**
* Creates a new {@link PackStatistics} object from the accumulator.
* Creates a new {@link org.eclipse.jgit.storage.pack.PackStatistics} object
* from the accumulator.
*
* @param accumulator
* the accumulator of the statistics
@ -270,6 +271,8 @@ public class PackStatistics {
}
/**
* Get unmodifiable collection of objects to be included in the pack.
*
* @return unmodifiable collection of objects to be included in the pack.
* May be {@code null} if the pack was hand-crafted in a unit test.
*/
@ -278,6 +281,9 @@ public class PackStatistics {
}
/**
* Get unmodifiable collection of objects that should be excluded from the
* pack
*
* @return unmodifiable collection of objects that should be excluded from
* the pack, as the peer that will receive the pack already has
* these objects.
@ -287,6 +293,9 @@ public class PackStatistics {
}
/**
* Get unmodifiable collection of objects that were shallow commits on the
* client.
*
* @return unmodifiable collection of objects that were shallow commits on
* the client.
*/
@ -295,6 +304,8 @@ public class PackStatistics {
}
/**
* Get unmodifiable list of the cached packs that were reused in the output
*
* @return unmodifiable list of the cached packs that were reused in the
* output, if any were selected for reuse.
*/
@ -302,12 +313,19 @@ public class PackStatistics {
return statistics.reusedPacks;
}
/** @return unmodifiable collection of the root commits of the history. */
/**
* Get unmodifiable collection of the root commits of the history.
*
* @return unmodifiable collection of the root commits of the history.
*/
public Set<ObjectId> getRootCommits() {
return statistics.rootCommits;
}
/**
* Get number of objects in the output pack that went through the delta
* search process in order to find a potential delta base.
*
* @return number of objects in the output pack that went through the delta
* search process in order to find a potential delta base.
*/
@ -316,6 +334,9 @@ public class PackStatistics {
}
/**
* Get number of objects in the output pack that went through delta base
* search and found a suitable base.
*
* @return number of objects in the output pack that went through delta base
* search and found a suitable base. This is a subset of
* {@link #getDeltaSearchNonEdgeObjects()}.
@ -325,6 +346,8 @@ public class PackStatistics {
}
/**
* Get total number of objects output.
*
* @return total number of objects output. This total includes the value of
* {@link #getTotalDeltas()}.
*/
@ -333,6 +356,9 @@ public class PackStatistics {
}
/**
* Get the count of objects that needed to be discovered through an object
* walk because they were not found in bitmap indices.
*
* @return the count of objects that needed to be discovered through an
* object walk because they were not found in bitmap indices.
* Returns -1 if no bitmap indices were found.
@ -342,6 +368,8 @@ public class PackStatistics {
}
/**
* Get total number of deltas output.
*
* @return total number of deltas output. This may be lower than the actual
* number of deltas if a cached pack was reused.
*/
@ -350,6 +378,9 @@ public class PackStatistics {
}
/**
* Get number of objects whose existing representation was reused in the
* output.
*
* @return number of objects whose existing representation was reused in the
* output. This count includes {@link #getReusedDeltas()}.
*/
@ -358,6 +389,9 @@ public class PackStatistics {
}
/**
* Get number of deltas whose existing representation was reused in the
* output.
*
* @return number of deltas whose existing representation was reused in the
* output, as their base object was also output or was assumed
* present for a thin pack. This may be lower than the actual number
@ -368,6 +402,8 @@ public class PackStatistics {
}
/**
* Get total number of bytes written.
*
* @return total number of bytes written. This size includes the pack
* header, trailer, thin pack, and reused cached pack(s).
*/
@ -376,6 +412,8 @@ public class PackStatistics {
}
/**
* Get size of the thin pack in bytes.
*
* @return size of the thin pack in bytes, if a thin pack was generated. A
* thin pack is created when the client already has objects and some
* deltas are created against those objects, or if a cached pack is
@ -387,6 +425,8 @@ public class PackStatistics {
}
/**
* Get information about this type of object in the pack.
*
* @param typeCode
* object type code, e.g. OBJ_COMMIT or OBJ_TREE.
* @return information about this type of object in the pack.
@ -395,17 +435,28 @@ public class PackStatistics {
return new ObjectType(statistics.objectTypes[typeCode]);
}
/** @return true if the resulting pack file was a shallow pack. */
/**
* Whether the resulting pack file was a shallow pack.
*
* @return {@code true} if the resulting pack file was a shallow pack.
*/
public boolean isShallow() {
return statistics.depth > 0;
}
/** @return depth (in commits) the pack includes if shallow. */
/**
* Get depth (in commits) the pack includes if shallow.
*
* @return depth (in commits) the pack includes if shallow.
*/
public int getDepth() {
return statistics.depth;
}
/**
* Get time in milliseconds spent enumerating the objects that need to be
* included in the output.
*
* @return time in milliseconds spent enumerating the objects that need to
* be included in the output. This time includes any restarts that
* occur when a cached pack is selected for reuse.
@ -415,6 +466,9 @@ public class PackStatistics {
}
/**
* Get time in milliseconds spent matching existing representations against
* objects that will be transmitted.
*
* @return time in milliseconds spent matching existing representations
* against objects that will be transmitted, or that the client can
* be assumed to already have.
@ -424,6 +478,9 @@ public class PackStatistics {
}
/**
* Get time in milliseconds spent finding the sizes of all objects that will
* enter the delta compression search window.
*
* @return time in milliseconds spent finding the sizes of all objects that
* will enter the delta compression search window. The sizes need to
* be known to better match similar objects together and improve
@ -434,6 +491,8 @@ public class PackStatistics {
}
/**
* Get time in milliseconds spent on delta compression.
*
* @return time in milliseconds spent on delta compression. This is observed
* wall-clock time and does not accurately track CPU time used when
* multiple threads were used to perform the delta compression.
@ -443,6 +502,9 @@ public class PackStatistics {
}
/**
* Get time in milliseconds spent writing the pack output, from start of
* header until end of trailer.
*
* @return time in milliseconds spent writing the pack output, from start of
* header until end of trailer. The transfer speed can be
* approximated by dividing {@link #getTotalBytes()} by this value.
@ -451,7 +513,11 @@ public class PackStatistics {
return statistics.timeWriting;
}
/** @return total time spent processing this pack. */
/**
* Get total time spent processing this pack.
*
* @return total time spent processing this pack.
*/
public long getTimeTotal() {
return statistics.timeCounting + statistics.timeSearchingForReuse
+ statistics.timeSearchingForSizes + statistics.timeCompressing
@ -459,14 +525,20 @@ public class PackStatistics {
}
/**
* @return get the average output speed in terms of bytes-per-second.
* Get the average output speed in terms of bytes-per-second.
*
* @return the average output speed in terms of bytes-per-second.
* {@code getTotalBytes() / (getTimeWriting() / 1000.0)}.
*/
public double getTransferRate() {
return getTotalBytes() / (getTimeWriting() / 1000.0);
}
/** @return formatted message string for display to clients. */
/**
* Get formatted message string for display to clients.
*
* @return formatted message string for display to clients.
*/
public String getMessage() {
return MessageFormat.format(JGitText.get().packWriterStatistics,
Long.valueOf(statistics.totalObjects),
@ -475,7 +547,11 @@ public class PackStatistics {
Long.valueOf(statistics.reusedDeltas));
}
/** @return a map containing ObjectType statistics. */
/**
* Get a map containing ObjectType statistics.
*
* @return a map containing ObjectType statistics.
*/
public Map<Integer, ObjectType> getObjectTypes() {
HashMap<Integer, ObjectType> map = new HashMap<>();
map.put(Integer.valueOf(OBJ_BLOB), new ObjectType(

Loading…
Cancel
Save