motiejus
/
jgit
1
Fork 0
Code Releases Activity

Fix javadoc in org.eclipse.jgit util packages 

Change-Id: Ia655f45153bcf1d422ffffce6dcf914847e14c4c
Signed-off-by: Matthias Sohn <matthias.sohn@sap.com>
This commit is contained in:
Matthias Sohn 2017-12-19 23:06:46 +01:00
parent c4207c5fbe
commit fdbaa25db9
56 changed files with 876 additions and 386 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
org.eclipse.jgit/src/org/eclipse/jgit/util/Base64.java
View File

@ -19,14 +19,13 @@
* <p> * <p>
* I am placing this code in the Public Domain. Do with it as you will. This * I am placing this code in the Public Domain. Do with it as you will. This
* software comes with no guarantees or warranties but with plenty of * software comes with no guarantees or warranties but with plenty of
* well-wishing instead! Please visit <a * well-wishing instead! Please visit
* href="http://iharder.net/base64">http://iharder.net/base64</a> periodically * <a href="http://iharder.net/base64">http://iharder.net/base64</a>
* to check for updates or to contribute improvements. * periodically to check for updates or to contribute improvements.
* </p> * </p>
* *
* @author Robert Harder * @author Robert Harder
* @author rob@iharder.net * @author rob@iharder.net
* @version 2.1, stripped to minimum feature set used by JGit.
*/ */
public class Base64 { public class Base64 {
/** The equals sign (=) as a byte. */ /** The equals sign (=) as a byte. */
@ -248,7 +247,7 @@ else if (source[srcOffset + 3] == EQUALS_SIGN) {
* @param len * @param len
* The length of characters to decode * The length of characters to decode
* @return decoded data * @return decoded data
* @throws IllegalArgumentException * @throws java.lang.IllegalArgumentException
* the input is not a valid Base64 sequence. * the input is not a valid Base64 sequence.
*/ */
public static byte[] decode(byte[] source, int off, int len) { public static byte[] decode(byte[] source, int off, int len) {

12
org.eclipse.jgit/src/org/eclipse/jgit/util/BlockList.java
View File

@ -84,7 +84,9 @@ public class BlockList<T> extends AbstractList<T> {
private T[] tailBlock; private T[] tailBlock;
/** Initialize an empty list. */ /**
* Initialize an empty list.
*/
public BlockList() { public BlockList() {
directory = BlockList.<T> newDirectory(256); directory = BlockList.<T> newDirectory(256);
directory[0] = BlockList.<T> newBlock(); directory[0] = BlockList.<T> newBlock();
@ -106,11 +108,13 @@ public BlockList(int capacity) {
tailBlock = directory[0]; tailBlock = directory[0];
} }
/** {@inheritDoc} */
@Override @Override
public int size() { public int size() {
return size; return size;
} }
/** {@inheritDoc} */
@Override @Override
public void clear() { public void clear() {
for (T[] block : directory) { for (T[] block : directory) {
@ -123,6 +127,7 @@ public void clear() {
tailBlock = directory[0]; tailBlock = directory[0];
} }
/** {@inheritDoc} */
@Override @Override
public T get(int index) { public T get(int index) {
if (index < 0 || size <= index) if (index < 0 || size <= index)
@ -130,6 +135,7 @@ public T get(int index) {
return directory[toDirectoryIndex(index)][toBlockIndex(index)]; return directory[toDirectoryIndex(index)][toBlockIndex(index)];
} }
/** {@inheritDoc} */
@Override @Override
public T set(int index, T element) { public T set(int index, T element) {
if (index < 0 || size <= index) if (index < 0 || size <= index)
@ -187,6 +193,7 @@ public void addAll(T[] src, int srcIdx, int srcCnt) {
} }
} }
/** {@inheritDoc} */
@Override @Override
public boolean add(T element) { public boolean add(T element) {
int i = tailBlkIdx; int i = tailBlkIdx;
@ -217,6 +224,7 @@ public boolean add(T element) {
return true; return true;
} }
/** {@inheritDoc} */
@Override @Override
public void add(int index, T element) { public void add(int index, T element) {
if (index == size) { if (index == size) {
@ -238,6 +246,7 @@ public void add(int index, T element) {
} }
} }
/** {@inheritDoc} */
@Override @Override
public T remove(int index) { public T remove(int index) {
if (index == size - 1) { if (index == size - 1) {
@ -277,6 +286,7 @@ private void resetTailBlock() {
tailBlock = directory[tailDirIdx]; tailBlock = directory[tailDirIdx];
} }
/** {@inheritDoc} */
@Override @Override
public Iterator<T> iterator() { public Iterator<T> iterator() {
return new MyIterator(); return new MyIterator();

5
org.eclipse.jgit/src/org/eclipse/jgit/util/CachedAuthenticator.java
View File

@ -49,7 +49,9 @@
import java.util.Collection; import java.util.Collection;
import java.util.concurrent.CopyOnWriteArrayList; import java.util.concurrent.CopyOnWriteArrayList;
/** Abstract authenticator which remembers prior authentications. */ /**
* Abstract authenticator which remembers prior authentications.
*/
public abstract class CachedAuthenticator extends Authenticator { public abstract class CachedAuthenticator extends Authenticator {
private static final Collection<CachedAuthentication> cached = new CopyOnWriteArrayList<>(); private static final Collection<CachedAuthentication> cached = new CopyOnWriteArrayList<>();
@ -63,6 +65,7 @@ public static void add(final CachedAuthentication ca) {
cached.add(ca); cached.add(ca);
} }
/** {@inheritDoc} */
@Override @Override
protected final PasswordAuthentication getPasswordAuthentication() { protected final PasswordAuthentication getPasswordAuthentication() {
final String host = getRequestingHost(); final String host = getRequestingHost();

24
org.eclipse.jgit/src/org/eclipse/jgit/util/ChangeIdUtil.java
View File

@ -82,9 +82,11 @@ static String clean(String msg) {
* @param firstParentId * @param firstParentId
* parent id of previous commit or null * parent id of previous commit or null
* @param author * @param author
* the {@link PersonIdent} for the presumed author and time * the {@link org.eclipse.jgit.lib.PersonIdent} for the presumed
* author and time
* @param committer * @param committer
* the {@link PersonIdent} for the presumed committer and time * the {@link org.eclipse.jgit.lib.PersonIdent} for the presumed
* committer and time
* @param message * @param message
* The commit message * The commit message
* @return the change id SHA1 string (without the 'I') or null if the * @return the change id SHA1 string (without the 'I') or null if the
@ -138,7 +140,9 @@ public static ObjectId computeChangeId(final ObjectId treeId,
* line. * line.
* *
* @param message * @param message
* a message.
* @param changeId * @param changeId
* a Change-Id.
* @return a commit message with an inserted Change-Id line * @return a commit message with an inserted Change-Id line
*/ */
public static String insertId(String message, ObjectId changeId) { public static String insertId(String message, ObjectId changeId) {
@ -148,18 +152,21 @@ public static String insertId(String message, ObjectId changeId) {
/** /**
* Find the right place to insert a Change-Id and return it. * Find the right place to insert a Change-Id and return it.
* <p> * <p>
* If no Change-Id is found the Change-Id is inserted before * If no Change-Id is found the Change-Id is inserted before the first
* the first footer line but after a Bug line. * footer line but after a Bug line.
* *
* If Change-Id is found and replaceExisting is set to false, * If Change-Id is found and replaceExisting is set to false, the message is
* the message is unchanged. * unchanged.
* *
* If Change-Id is found and replaceExisting is set to true, * If Change-Id is found and replaceExisting is set to true, the Change-Id
* the Change-Id is replaced with {@code changeId}. * is replaced with {@code changeId}.
* *
* @param message * @param message
* a message.
* @param changeId * @param changeId
* a Change-Id.
* @param replaceExisting * @param replaceExisting
* a boolean.
* @return a commit message with an inserted Change-Id line * @return a commit message with an inserted Change-Id line
*/ */
public static String insertId(String message, ObjectId changeId, public static String insertId(String message, ObjectId changeId,
@ -219,6 +226,7 @@ public static String insertId(String message, ObjectId changeId,
* only lines matching {@code footerPattern}. * only lines matching {@code footerPattern}.
* *
* @param message * @param message
* a message.
* @param delimiter * @param delimiter
* the line delimiter, like "\n" or "\r\n", needed to find the * the line delimiter, like "\n" or "\r\n", needed to find the
* footer * footer

114
org.eclipse.jgit/src/org/eclipse/jgit/util/FS.java
View File

@ -75,7 +75,9 @@
import org.slf4j.Logger; import org.slf4j.Logger;
import org.slf4j.LoggerFactory; import org.slf4j.LoggerFactory;
/** Abstraction to support various file system operations not in Java. */ /**
* Abstraction to support various file system operations not in Java.
*/
public abstract class FS { public abstract class FS {
private static final Logger LOG = LoggerFactory.getLogger(FS.class); private static final Logger LOG = LoggerFactory.getLogger(FS.class);
@ -192,7 +194,6 @@ public static FS detect() {
* </ul> * </ul>
* *
* Note: this parameter is only relevant on Windows. * Note: this parameter is only relevant on Windows.
*
* @return detected file system abstraction * @return detected file system abstraction
*/ */
public static FS detect(Boolean cygwinUsed) { public static FS detect(Boolean cygwinUsed) {
@ -224,7 +225,11 @@ protected FS(FS src) {
gitSystemConfig = src.gitSystemConfig; gitSystemConfig = src.gitSystemConfig;
} }
/** @return a new instance of the same type of FS. */ /**
* Create a new instance of the same type of FS.
*
* @return a new instance of the same type of FS.
*/
public abstract FS newInstance(); public abstract FS newInstance();
/** /**
@ -242,8 +247,8 @@ protected FS(FS src) {
* parallel only one will succeed. In such cases both clients may think they * parallel only one will succeed. In such cases both clients may think they
* created a new file. * created a new file.
* *
* @return true if this implementation support atomic creation of new * @return true if this implementation support atomic creation of new Files
* Files by {@link File#createNewFile()} * by {@link java.io.File#createNewFile()}
* @since 4.5 * @since 4.5
*/ */
public boolean supportsAtomicCreateNewFile() { public boolean supportsAtomicCreateNewFile() {
@ -305,8 +310,9 @@ public boolean supportsSymlinks() {
* than that of the link target. * than that of the link target.
* *
* @param f * @param f
* a {@link java.io.File} object.
* @return last modified time of f * @return last modified time of f
* @throws IOException * @throws java.io.IOException
* @since 3.0 * @since 3.0
*/ */
public long lastModified(File f) throws IOException { public long lastModified(File f) throws IOException {
@ -318,8 +324,10 @@ public long lastModified(File f) throws IOException {
* symbolic links, the link is modified, not the target, * symbolic links, the link is modified, not the target,
* *
* @param f * @param f
* a {@link java.io.File} object.
* @param time * @param time
* @throws IOException * last modified time
* @throws java.io.IOException
* @since 3.0 * @since 3.0
*/ */
public void setLastModified(File f, long time) throws IOException { public void setLastModified(File f, long time) throws IOException {
@ -331,8 +339,9 @@ public void setLastModified(File f, long time) throws IOException {
* it's the length of the link, else the length of the target. * it's the length of the link, else the length of the target.
* *
* @param path * @param path
* a {@link java.io.File} object.
* @return length of a file * @return length of a file
* @throws IOException * @throws java.io.IOException
* @since 3.0 * @since 3.0
*/ */
public long length(File path) throws IOException { public long length(File path) throws IOException {
@ -343,7 +352,8 @@ public long length(File path) throws IOException {
* Delete a file. Throws an exception if delete fails. * Delete a file. Throws an exception if delete fails.
* *
* @param f * @param f
* @throws IOException * a {@link java.io.File} object.
* @throws java.io.IOException
* this may be a Java7 subclass with detailed information * this may be a Java7 subclass with detailed information
* @since 3.3 * @since 3.3
*/ */
@ -444,7 +454,7 @@ public String run() {
* Files to search for in the given path * Files to search for in the given path
* @return the first match found, or null * @return the first match found, or null
* @since 3.0 * @since 3.0
**/ */
protected static File searchPath(final String path, final String... lookFor) { protected static File searchPath(final String path, final String... lookFor) {
if (path == null) if (path == null)
return null; return null;
@ -470,7 +480,7 @@ protected static File searchPath(final String path, final String... lookFor) {
* to be used to parse the command's output * to be used to parse the command's output
* @return the one-line output of the command or {@code null} if there is * @return the one-line output of the command or {@code null} if there is
* none * none
* @throws CommandFailedException * @throws org.eclipse.jgit.errors.CommandFailedException
* thrown when the command failed (return code was non-zero) * thrown when the command failed (return code was non-zero)
*/ */
@Nullable @Nullable
@ -493,7 +503,7 @@ protected static String readPipe(File dir, String[] command,
* current process * current process
* @return the one-line output of the command or {@code null} if there is * @return the one-line output of the command or {@code null} if there is
* none * none
* @throws CommandFailedException * @throws org.eclipse.jgit.errors.CommandFailedException
* thrown when the command failed (return code was non-zero) * thrown when the command failed (return code was non-zero)
* @since 4.0 * @since 4.0
*/ */
@ -632,6 +642,8 @@ private void setError(IOException e, String message, int exitCode) {
} }
/** /**
* Discover the path to the Git executable.
*
* @return the path to the Git executable or {@code null} if it cannot be * @return the path to the Git executable or {@code null} if it cannot be
* determined. * determined.
* @since 4.0 * @since 4.0
@ -639,6 +651,8 @@ private void setError(IOException e, String message, int exitCode) {
protected abstract File discoverGitExe(); protected abstract File discoverGitExe();
/** /**
* Discover the path to the system-wide Git configuration file
*
* @return the path to the system-wide Git configuration file or * @return the path to the system-wide Git configuration file or
* {@code null} if it cannot be determined. * {@code null} if it cannot be determined.
* @since 4.0 * @since 4.0
@ -686,8 +700,10 @@ protected File discoverGitSystemConfig() {
} }
/** /**
* @return the currently used path to the system-wide Git configuration * Get the currently used path to the system-wide Git configuration file.
* file or {@code null} if none has been set. *
* @return the currently used path to the system-wide Git configuration file
* or {@code null} if none has been set.
* @since 4.0 * @since 4.0
*/ */
public File getGitSystemConfig() { public File getGitSystemConfig() {
@ -711,7 +727,10 @@ public FS setGitSystemConfig(File configFile) {
} }
/** /**
* Get the parent directory of this file's parent directory
*
* @param grandchild * @param grandchild
* a {@link java.io.File} object.
* @return the parent directory of this file's parent directory or * @return the parent directory of this file's parent directory or
* {@code null} in case there's no grandparent directory * {@code null} in case there's no grandparent directory
* @since 4.0 * @since 4.0
@ -729,8 +748,9 @@ protected static File resolveGrandparentFile(File grandchild) {
* Check if a file is a symbolic link and read it * Check if a file is a symbolic link and read it
* *
* @param path * @param path
* a {@link java.io.File} object.
* @return target of link or null * @return target of link or null
* @throws IOException * @throws java.io.IOException
* @since 3.0 * @since 3.0
*/ */
public String readSymLink(File path) throws IOException { public String readSymLink(File path) throws IOException {
@ -738,9 +758,12 @@ public String readSymLink(File path) throws IOException {
} }
/** /**
* Whether the path is a symbolic link (and we support these).
*
* @param path * @param path
* a {@link java.io.File} object.
* @return true if the path is a symbolic link (and we support these) * @return true if the path is a symbolic link (and we support these)
* @throws IOException * @throws java.io.IOException
* @since 3.0 * @since 3.0
*/ */
public boolean isSymLink(File path) throws IOException { public boolean isSymLink(File path) throws IOException {
@ -752,6 +775,7 @@ public boolean isSymLink(File path) throws IOException {
* target does not exist * target does not exist
* *
* @param path * @param path
* a {@link java.io.File} object.
* @return true if path exists * @return true if path exists
* @since 3.0 * @since 3.0
*/ */
@ -764,6 +788,7 @@ public boolean exists(File path) {
* path is a symbolic link to a directory, this method returns false. * path is a symbolic link to a directory, this method returns false.
* *
* @param path * @param path
* a {@link java.io.File} object.
* @return true if file is a directory, * @return true if file is a directory,
* @since 3.0 * @since 3.0
*/ */
@ -776,6 +801,7 @@ public boolean isDirectory(File path) {
* symbolic links the test returns false if path represents a symbolic link. * symbolic links the test returns false if path represents a symbolic link.
* *
* @param path * @param path
* a {@link java.io.File} object.
* @return true if path represents a regular file * @return true if path represents a regular file
* @since 3.0 * @since 3.0
*/ */
@ -784,10 +810,14 @@ public boolean isFile(File path) {
} }
/** /**
* Whether path is hidden, either starts with . on unix or has the hidden
* attribute in windows
*
* @param path * @param path
* a {@link java.io.File} object.
* @return true if path is hidden, either starts with . on unix or has the * @return true if path is hidden, either starts with . on unix or has the
* hidden attribute in windows * hidden attribute in windows
* @throws IOException * @throws java.io.IOException
* @since 3.0 * @since 3.0
*/ */
public boolean isHidden(File path) throws IOException { public boolean isHidden(File path) throws IOException {
@ -798,8 +828,10 @@ public boolean isHidden(File path) throws IOException {
* Set the hidden attribute for file whose name starts with a period. * Set the hidden attribute for file whose name starts with a period.
* *
* @param path * @param path
* a {@link java.io.File} object.
* @param hidden * @param hidden
* @throws IOException * whether to set the file hidden
* @throws java.io.IOException
* @since 3.0 * @since 3.0
*/ */
public void setHidden(File path, boolean hidden) throws IOException { public void setHidden(File path, boolean hidden) throws IOException {
@ -810,8 +842,10 @@ public void setHidden(File path, boolean hidden) throws IOException {
* Create a symbolic link * Create a symbolic link
* *
* @param path * @param path
* a {@link java.io.File} object.
* @param target * @param target
* @throws IOException * target path of the symlink
* @throws java.io.IOException
* @since 3.0 * @since 3.0
*/ */
public void createSymLink(File path, String target) throws IOException { public void createSymLink(File path, String target) throws IOException {
@ -819,15 +853,15 @@ public void createSymLink(File path, String target) throws IOException {
} }
/** /**
* Create a new file. See {@link File#createNewFile()}. Subclasses of this * Create a new file. See {@link java.io.File#createNewFile()}. Subclasses
* class may take care to provide a safe implementation for this even if * of this class may take care to provide a safe implementation for this
* {@link #supportsAtomicCreateNewFile()} is <code>false</code> * even if {@link #supportsAtomicCreateNewFile()} is <code>false</code>
* *
* @param path * @param path
* the file to be created * the file to be created
* @return <code>true</code> if the file was created, <code>false</code> if * @return <code>true</code> if the file was created, <code>false</code> if
* the file already existed * the file already existed
* @throws IOException * @throws java.io.IOException
* @since 4.5 * @since 4.5
*/ */
public boolean createNewFile(File path) throws IOException { public boolean createNewFile(File path) throws IOException {
@ -835,7 +869,8 @@ public boolean createNewFile(File path) throws IOException {
} }
/** /**
* See {@link FileUtils#relativizePath(String, String, String, boolean)}. * See
* {@link org.eclipse.jgit.util.FileUtils#relativizePath(String, String, String, boolean)}.
* *
* @param base * @param base
* The path against which <code>other</code> should be * The path against which <code>other</code> should be
@ -868,7 +903,7 @@ public String relativize(String base, String other) {
* Arguments to pass to this hook. Cannot be <code>null</code>, * Arguments to pass to this hook. Cannot be <code>null</code>,
* but can be an empty array. * but can be an empty array.
* @return The ProcessResult describing this hook's execution. * @return The ProcessResult describing this hook's execution.
* @throws JGitInternalException * @throws org.eclipse.jgit.api.errors.JGitInternalException
* if we fail to run the hook somehow. Causes may include an * if we fail to run the hook somehow. Causes may include an
* interrupted process or I/O errors. * interrupted process or I/O errors.
* @since 4.0 * @since 4.0
@ -903,7 +938,7 @@ public ProcessResult runHookIfPresent(Repository repository,
* A string to pass on to the standard input of the hook. May be * A string to pass on to the standard input of the hook. May be
* <code>null</code>. * <code>null</code>.
* @return The ProcessResult describing this hook's execution. * @return The ProcessResult describing this hook's execution.
* @throws JGitInternalException * @throws org.eclipse.jgit.api.errors.JGitInternalException
* if we fail to run the hook somehow. Causes may include an * if we fail to run the hook somehow. Causes may include an
* interrupted process or I/O errors. * interrupted process or I/O errors.
* @since 4.0 * @since 4.0
@ -939,7 +974,7 @@ public ProcessResult runHookIfPresent(Repository repository,
* A string to pass on to the standard input of the hook. May be * A string to pass on to the standard input of the hook. May be
* <code>null</code>. * <code>null</code>.
* @return The ProcessResult describing this hook's execution. * @return The ProcessResult describing this hook's execution.
* @throws JGitInternalException * @throws org.eclipse.jgit.api.errors.JGitInternalException
* if we fail to run the hook somehow. Causes may include an * if we fail to run the hook somehow. Causes may include an
* interrupted process or I/O errors. * interrupted process or I/O errors.
* @since 4.0 * @since 4.0
@ -984,8 +1019,8 @@ protected ProcessResult internalRunHookIfPresent(Repository repository,
* The repository within which to find a hook. * The repository within which to find a hook.
* @param hookName * @param hookName
* The name of the hook we're trying to find. * The name of the hook we're trying to find.
* @return The {@link File} containing this particular hook if it exists in * @return The {@link java.io.File} containing this particular hook if it
* the given repository, <code>null</code> otherwise. * exists in the given repository, <code>null</code> otherwise.
* @since 4.0 * @since 4.0
*/ */
public File findHook(Repository repository, final String hookName) { public File findHook(Repository repository, final String hookName) {
@ -1015,9 +1050,9 @@ public File findHook(Repository repository, final String hookName) {
* A string to pass on to the standard input of the hook. Can be * A string to pass on to the standard input of the hook. Can be
* <code>null</code>. * <code>null</code>.
* @return the exit value of this process. * @return the exit value of this process.
* @throws IOException * @throws java.io.IOException
* if an I/O error occurs while executing this process. * if an I/O error occurs while executing this process.
* @throws InterruptedException * @throws java.lang.InterruptedException
* if the current thread is interrupted while waiting for the * if the current thread is interrupted while waiting for the
* process to end. * process to end.
* @since 4.2 * @since 4.2
@ -1051,9 +1086,9 @@ public int runProcess(ProcessBuilder processBuilder,
* will be consumed by the process. The method will close the * will be consumed by the process. The method will close the
* inputstream after all bytes are read. * inputstream after all bytes are read.
* @return the return code of this process. * @return the return code of this process.
* @throws IOException * @throws java.io.IOException
* if an I/O error occurs while executing this process. * if an I/O error occurs while executing this process.
* @throws InterruptedException * @throws java.lang.InterruptedException
* if the current thread is interrupted while waiting for the * if the current thread is interrupted while waiting for the
* process to end. * process to end.
* @since 4.2 * @since 4.2
@ -1179,15 +1214,15 @@ private static boolean shutdownAndAwaitTermination(ExecutorService pool) {
public abstract ProcessBuilder runInShell(String cmd, String[] args); public abstract ProcessBuilder runInShell(String cmd, String[] args);
/** /**
* Execute a command defined by a {@link ProcessBuilder}. * Execute a command defined by a {@link java.lang.ProcessBuilder}.
* *
* @param pb * @param pb
* The command to be executed * The command to be executed
* @param in * @param in
* The standard input stream passed to the process * The standard input stream passed to the process
* @return The result of the executed command * @return The result of the executed command
* @throws InterruptedException * @throws java.lang.InterruptedException
* @throws IOException * @throws java.io.IOException
* @since 4.2 * @since 4.2
*/ */
public ExecutionResult execute(ProcessBuilder pb, InputStream in) public ExecutionResult execute(ProcessBuilder pb, InputStream in)
@ -1340,8 +1375,11 @@ boolean exists() {
} }
/** /**
* Get the file attributes we care for.
*
* @param path * @param path
* @return the file attributes we care for * a {@link java.io.File} object.
* @return the file attributes we care for.
* @since 3.3 * @since 3.3
*/ */
public Attributes getAttributes(File path) { public Attributes getAttributes(File path) {
@ -1361,6 +1399,7 @@ public Attributes getAttributes(File path) {
* Normalize the unicode path to composed form. * Normalize the unicode path to composed form.
* *
* @param file * @param file
* a {@link java.io.File} object.
* @return NFC-format File * @return NFC-format File
* @since 3.3 * @since 3.3
*/ */
@ -1372,6 +1411,7 @@ public File normalize(File file) {
* Normalize the unicode path to composed form. * Normalize the unicode path to composed form.
* *
* @param name * @param name
* path name
* @return NFC-format string * @return NFC-format string
* @since 3.3 * @since 3.3
*/ */

39
org.eclipse.jgit/src/org/eclipse/jgit/util/FS_POSIX.java
View File

@ -86,7 +86,9 @@ private enum AtomicFileCreation {
SUPPORTED, NOT_SUPPORTED, UNDEFINED SUPPORTED, NOT_SUPPORTED, UNDEFINED
} }
/** Default constructor. */ /**
* Default constructor.
*/
protected FS_POSIX() { protected FS_POSIX() {
} }
@ -134,6 +136,7 @@ private AtomicFileCreation getAtomicFileCreationSupportOption(
} }
} }
/** {@inheritDoc} */
@Override @Override
public FS newInstance() { public FS newInstance() {
return new FS_POSIX(this); return new FS_POSIX(this);
@ -181,6 +184,7 @@ private static int readUmask() {
} }
} }
/** {@inheritDoc} */
@Override @Override
protected File discoverGitExe() { protected File discoverGitExe() {
String path = SystemReader.getInstance().getenv("PATH"); //$NON-NLS-1$ String path = SystemReader.getInstance().getenv("PATH"); //$NON-NLS-1$
@ -211,21 +215,25 @@ protected File discoverGitExe() {
return gitExe; return gitExe;
} }
/** {@inheritDoc} */
@Override @Override
public boolean isCaseSensitive() { public boolean isCaseSensitive() {
return !SystemReader.getInstance().isMacOS(); return !SystemReader.getInstance().isMacOS();
} }
/** {@inheritDoc} */
@Override @Override
public boolean supportsExecute() { public boolean supportsExecute() {
return true; return true;
} }
/** {@inheritDoc} */
@Override @Override
public boolean canExecute(File f) { public boolean canExecute(File f) {
return FileUtils.canExecute(f); return FileUtils.canExecute(f);
} }
/** {@inheritDoc} */
@Override @Override
public boolean setExecute(File f, boolean canExecute) { public boolean setExecute(File f, boolean canExecute) {
if (!isFile(f)) if (!isFile(f))
@ -266,6 +274,7 @@ private static void apply(Set<PosixFilePermission> set,
} }
} }
/** {@inheritDoc} */
@Override @Override
public ProcessBuilder runInShell(String cmd, String[] args) { public ProcessBuilder runInShell(String cmd, String[] args) {
List<String> argv = new ArrayList<>(4 + args.length); List<String> argv = new ArrayList<>(4 + args.length);
@ -279,9 +288,7 @@ public ProcessBuilder runInShell(String cmd, String[] args) {
return proc; return proc;
} }
/** /** {@inheritDoc} */
* @since 4.0
*/
@Override @Override
public ProcessResult runHookIfPresent(Repository repository, String hookName, public ProcessResult runHookIfPresent(Repository repository, String hookName,
String[] args, PrintStream outRedirect, PrintStream errRedirect, String[] args, PrintStream outRedirect, PrintStream errRedirect,
@ -290,48 +297,43 @@ public ProcessResult runHookIfPresent(Repository repository, String hookName,
errRedirect, stdinArgs); errRedirect, stdinArgs);
} }
/** {@inheritDoc} */
@Override @Override
public boolean retryFailedLockFileCommit() { public boolean retryFailedLockFileCommit() {
return false; return false;
} }
/** {@inheritDoc} */
@Override @Override
public boolean supportsSymlinks() { public boolean supportsSymlinks() {
return true; return true;
} }
/** {@inheritDoc} */
@Override @Override
public void setHidden(File path, boolean hidden) throws IOException { public void setHidden(File path, boolean hidden) throws IOException {
// no action on POSIX // no action on POSIX
} }
/** /** {@inheritDoc} */
* @since 3.3
*/
@Override @Override
public Attributes getAttributes(File path) { public Attributes getAttributes(File path) {
return FileUtils.getFileAttributesPosix(this, path); return FileUtils.getFileAttributesPosix(this, path);
} }
/** /** {@inheritDoc} */
* @since 3.3
*/
@Override @Override
public File normalize(File file) { public File normalize(File file) {
return FileUtils.normalize(file); return FileUtils.normalize(file);
} }
/** /** {@inheritDoc} */
* @since 3.3
*/
@Override @Override
public String normalize(String name) { public String normalize(String name) {
return FileUtils.normalize(name); return FileUtils.normalize(name);
} }
/** /** {@inheritDoc} */
* @since 3.7
*/
@Override @Override
public File findHook(Repository repository, String hookName) { public File findHook(Repository repository, String hookName) {
final File gitdir = repository.getDirectory(); final File gitdir = repository.getDirectory();
@ -345,6 +347,7 @@ public File findHook(Repository repository, String hookName) {
return null; return null;
} }
/** {@inheritDoc} */
@Override @Override
public boolean supportsAtomicCreateNewFile() { public boolean supportsAtomicCreateNewFile() {
if (supportsAtomicCreateNewFile == AtomicFileCreation.UNDEFINED) { if (supportsAtomicCreateNewFile == AtomicFileCreation.UNDEFINED) {
@ -356,13 +359,15 @@ public boolean supportsAtomicCreateNewFile() {
@Override @Override
@SuppressWarnings("boxing") @SuppressWarnings("boxing")
/** /**
* {@inheritDoc}
* <p>
* An implementation of the File#createNewFile() semantics which works also * An implementation of the File#createNewFile() semantics which works also
* on NFS. If the config option * on NFS. If the config option
* {@code core.supportsAtomicCreateNewFile = true} (which is the default) * {@code core.supportsAtomicCreateNewFile = true} (which is the default)
* then simply File#createNewFile() is called. * then simply File#createNewFile() is called.
* *
* But if {@code core.supportsAtomicCreateNewFile = false} then after * But if {@code core.supportsAtomicCreateNewFile = false} then after
* successful creation of the lock file a hardlink to that lock file is * successful creation of the lock file a hard link to that lock file is
* created and the attribute nlink of the lock file is checked to be 2. If * created and the attribute nlink of the lock file is checked to be 2. If
* multiple clients manage to create the same lock file nlink would be * multiple clients manage to create the same lock file nlink would be
* greater than 2 showing the error. * greater than 2 showing the error.

14
org.eclipse.jgit/src/org/eclipse/jgit/util/FS_Win32.java
View File

@ -83,36 +83,43 @@ protected FS_Win32(FS src) {
super(src); super(src);
} }
/** {@inheritDoc} */
@Override @Override
public FS newInstance() { public FS newInstance() {
return new FS_Win32(this); return new FS_Win32(this);
} }
/** {@inheritDoc} */
@Override @Override
public boolean supportsExecute() { public boolean supportsExecute() {
return false; return false;
} }
/** {@inheritDoc} */
@Override @Override
public boolean canExecute(final File f) { public boolean canExecute(final File f) {
return false; return false;
} }
/** {@inheritDoc} */
@Override @Override
public boolean setExecute(final File f, final boolean canExec) { public boolean setExecute(final File f, final boolean canExec) {
return false; return false;
} }
/** {@inheritDoc} */
@Override @Override
public boolean isCaseSensitive() { public boolean isCaseSensitive() {
return false; return false;
} }
/** {@inheritDoc} */
@Override @Override
public boolean retryFailedLockFileCommit() { public boolean retryFailedLockFileCommit() {
return true; return true;
} }
/** {@inheritDoc} */
@Override @Override
protected File discoverGitExe() { protected File discoverGitExe() {
String path = SystemReader.getInstance().getenv("PATH"); //$NON-NLS-1$ String path = SystemReader.getInstance().getenv("PATH"); //$NON-NLS-1$
@ -141,6 +148,7 @@ protected File discoverGitExe() {
return gitExe; return gitExe;
} }
/** {@inheritDoc} */
@Override @Override
protected File userHomeImpl() { protected File userHomeImpl() {
String home = SystemReader.getInstance().getenv("HOME"); //$NON-NLS-1$ String home = SystemReader.getInstance().getenv("HOME"); //$NON-NLS-1$
@ -160,6 +168,7 @@ protected File userHomeImpl() {
return super.userHomeImpl(); return super.userHomeImpl();
} }
/** {@inheritDoc} */
@Override @Override
public ProcessBuilder runInShell(String cmd, String[] args) { public ProcessBuilder runInShell(String cmd, String[] args) {
List<String> argv = new ArrayList<>(3 + args.length); List<String> argv = new ArrayList<>(3 + args.length);
@ -172,6 +181,7 @@ public ProcessBuilder runInShell(String cmd, String[] args) {
return proc; return proc;
} }
/** {@inheritDoc} */
@Override @Override
public boolean supportsSymlinks() { public boolean supportsSymlinks() {
if (supportSymlinks == null) if (supportSymlinks == null)
@ -200,9 +210,7 @@ private void detectSymlinkSupport() {
} }
} }
/** /** {@inheritDoc} */
* @since 3.3
*/
@Override @Override
public Attributes getAttributes(File path) { public Attributes getAttributes(File path) {
return FileUtils.getFileAttributesBasic(this, path); return FileUtils.getFileAttributesBasic(this, path);

18
org.eclipse.jgit/src/org/eclipse/jgit/util/FS_Win32_Cygwin.java
View File

@ -72,6 +72,8 @@ public class FS_Win32_Cygwin extends FS_Win32 {
private static String cygpath; private static String cygpath;
/** /**
* Whether cygwin is found
*
* @return true if cygwin is found * @return true if cygwin is found
*/ */
public static boolean isCygwin() { public static boolean isCygwin() {
@ -107,11 +109,13 @@ protected FS_Win32_Cygwin(FS src) {
super(src); super(src);
} }
/** {@inheritDoc} */
@Override @Override
public FS newInstance() { public FS newInstance() {
return new FS_Win32_Cygwin(this); return new FS_Win32_Cygwin(this);
} }
/** {@inheritDoc} */
@Override @Override
public File resolve(final File dir, final String pn) { public File resolve(final File dir, final String pn) {
String useCygPath = System.getProperty("jgit.usecygpath"); //$NON-NLS-1$ String useCygPath = System.getProperty("jgit.usecygpath"); //$NON-NLS-1$
@ -132,6 +136,7 @@ public File resolve(final File dir, final String pn) {
return super.resolve(dir, pn); return super.resolve(dir, pn);
} }
/** {@inheritDoc} */
@Override @Override
protected File userHomeImpl() { protected File userHomeImpl() {
final String home = AccessController final String home = AccessController
@ -146,6 +151,7 @@ public String run() {
return resolve(new File("."), home); //$NON-NLS-1$ return resolve(new File("."), home); //$NON-NLS-1$
} }
/** {@inheritDoc} */
@Override @Override
public ProcessBuilder runInShell(String cmd, String[] args) { public ProcessBuilder runInShell(String cmd, String[] args) {
List<String> argv = new ArrayList<>(4 + args.length); List<String> argv = new ArrayList<>(4 + args.length);
@ -159,18 +165,14 @@ public ProcessBuilder runInShell(String cmd, String[] args) {
return proc; return proc;
} }
/** /** {@inheritDoc} */
* @since 3.7
*/
@Override @Override
public String relativize(String base, String other) { public String relativize(String base, String other) {
final String relativized = super.relativize(base, other); final String relativized = super.relativize(base, other);
return relativized.replace(File.separatorChar, '/'); return relativized.replace(File.separatorChar, '/');
} }
/** /** {@inheritDoc} */
* @since 4.0
*/
@Override @Override
public ProcessResult runHookIfPresent(Repository repository, String hookName, public ProcessResult runHookIfPresent(Repository repository, String hookName,
String[] args, PrintStream outRedirect, PrintStream errRedirect, String[] args, PrintStream outRedirect, PrintStream errRedirect,
@ -179,9 +181,7 @@ public ProcessResult runHookIfPresent(Repository repository, String hookName,
errRedirect, stdinArgs); errRedirect, stdinArgs);
} }
/** /** {@inheritDoc} */
* @since 3.7
*/
@Override @Override
public File findHook(Repository repository, String hookName) { public File findHook(Repository repository, String hookName) {
final File gitdir = repository.getDirectory(); final File gitdir = repository.getDirectory();

120
org.eclipse.jgit/src/org/eclipse/jgit/util/FileUtil.java
View File

@ -45,7 +45,6 @@
import java.io.File; import java.io.File;
import java.io.IOException; import java.io.IOException;
import java.nio.file.Files;
import org.eclipse.jgit.util.FS.Attributes; import org.eclipse.jgit.util.FS.Attributes;
@ -56,10 +55,14 @@
public class FileUtil { public class FileUtil {
/** /**
* Read target path of a symlink.
*
* @param path * @param path
* @return target path of the symlink * a {@link java.io.File}.
* @throws IOException * @return target path of the symlink.
* @deprecated use {@link FileUtils#readSymLink(File)} instead * @throws java.io.IOException
* @deprecated use {@link org.eclipse.jgit.util.FileUtils#readSymLink(File)}
* instead
*/ */
@Deprecated @Deprecated
public static String readSymlink(File path) throws IOException { public static String readSymlink(File path) throws IOException {
@ -67,12 +70,16 @@ public static String readSymlink(File path) throws IOException {
} }
/** /**
* Create a symlink
*
* @param path * @param path
* path of the symlink to be created * path of the symlink to be created
* @param target * @param target
* target of the symlink to be created * target of the symlink to be created
* @throws IOException * @throws java.io.IOException
* @deprecated use {@link FileUtils#createSymLink(File, String)} instead * @deprecated use
* {@link org.eclipse.jgit.util.FileUtils#createSymLink(File, String)}
* instead
*/ */
@Deprecated @Deprecated
public static void createSymLink(File path, String target) public static void createSymLink(File path, String target)
@ -81,9 +88,14 @@ public static void createSymLink(File path, String target)
} }
/** /**
* Whether the passed file is a symlink
*
* @param path * @param path
* a {@link java.io.File} object.
* @return {@code true} if the passed path is a symlink * @return {@code true} if the passed path is a symlink
* @deprecated Use {@link Files#isSymbolicLink(java.nio.file.Path)} instead * @deprecated Use
* {@link java.nio.file.Files#isSymbolicLink(java.nio.file.Path)}
* instead
*/ */
@Deprecated @Deprecated
public static boolean isSymlink(File path) { public static boolean isSymlink(File path) {
@ -91,11 +103,14 @@ public static boolean isSymlink(File path) {
} }
/** /**
* Get lastModified attribute for given path
*
* @param path * @param path
* a {@link java.io.File}.
* @return lastModified attribute for given path * @return lastModified attribute for given path
* @throws IOException * @throws java.io.IOException
* @deprecated Use * @deprecated Use
* {@link Files#getLastModifiedTime(java.nio.file.Path, java.nio.file.LinkOption...)} * {@link java.nio.file.Files#getLastModifiedTime(java.nio.file.Path, java.nio.file.LinkOption...)}
* instead * instead
*/ */
@Deprecated @Deprecated
@ -104,11 +119,15 @@ public static long lastModified(File path) throws IOException {
} }
/** /**
* Set lastModified attribute for given path
*
* @param path * @param path
* a {@link java.io.File}.
* @param time * @param time
* @throws IOException * a long.
* @throws java.io.IOException
* @deprecated Use * @deprecated Use
* {@link Files#setLastModifiedTime(java.nio.file.Path, java.nio.file.attribute.FileTime)} * {@link java.nio.file.Files#setLastModifiedTime(java.nio.file.Path, java.nio.file.attribute.FileTime)}
* instead * instead
*/ */
@Deprecated @Deprecated
@ -117,10 +136,13 @@ public static void setLastModified(File path, long time) throws IOException {
} }
/** /**
* Whether this file exists
*
* @param path * @param path
* a {@link java.io.File}.
* @return {@code true} if the given path exists * @return {@code true} if the given path exists
* @deprecated Use * @deprecated Use
* {@link Files#exists(java.nio.file.Path, java.nio.file.LinkOption...)} * {@link java.nio.file.Files#exists(java.nio.file.Path, java.nio.file.LinkOption...)}
* instead * instead
*/ */
@Deprecated @Deprecated
@ -129,10 +151,14 @@ public static boolean exists(File path) {
} }
/** /**
* Whether this file is hidden
*
* @param path * @param path
* a {@link java.io.File}.
* @return {@code true} if the given path is hidden * @return {@code true} if the given path is hidden
* @throws IOException * @throws java.io.IOException
* @deprecated Use {@link Files#isHidden(java.nio.file.Path)} instead * @deprecated Use {@link java.nio.file.Files#isHidden(java.nio.file.Path)}
* instead
*/ */
@Deprecated @Deprecated
public static boolean isHidden(File path) throws IOException { public static boolean isHidden(File path) throws IOException {
@ -140,10 +166,16 @@ public static boolean isHidden(File path) throws IOException {
} }
/** /**
* Set this file hidden
*
* @param path * @param path
* a {@link java.io.File}.
* @param hidden * @param hidden
* @throws IOException * a boolean.
* @deprecated Use {@link FileUtils#setHidden(File,boolean)} instead * @throws java.io.IOException
* @deprecated Use
* {@link org.eclipse.jgit.util.FileUtils#setHidden(File,boolean)}
* instead
*/ */
@Deprecated @Deprecated
public static void setHidden(File path, boolean hidden) throws IOException { public static void setHidden(File path, boolean hidden) throws IOException {
@ -151,10 +183,14 @@ public static void setHidden(File path, boolean hidden) throws IOException {
} }
/** /**
* Get file length
*
* @param path * @param path
* a {@link java.io.File}.
* @return length of the given file * @return length of the given file
* @throws IOException * @throws java.io.IOException
* @deprecated Use {@link FileUtils#getLength(File)} instead * @deprecated Use {@link org.eclipse.jgit.util.FileUtils#getLength(File)}
* instead
*/ */
@Deprecated @Deprecated
public static long getLength(File path) throws IOException { public static long getLength(File path) throws IOException {
@ -162,10 +198,13 @@ public static long getLength(File path) throws IOException {
} }
/** /**
* Whether the given File is a directory
*
* @param path * @param path
* @return {@code true} if the given file a directory * a {@link java.io.File} object.
* @return {@code true} if the given file is a directory
* @deprecated Use * @deprecated Use
* {@link Files#isDirectory(java.nio.file.Path, java.nio.file.LinkOption...)} * {@link java.nio.file.Files#isDirectory(java.nio.file.Path, java.nio.file.LinkOption...)}
* instead * instead
*/ */
@Deprecated @Deprecated
@ -174,10 +213,13 @@ public static boolean isDirectory(File path) {
} }
/** /**
* Whether the given File is a file
*
* @param path * @param path
* a {@link java.io.File} object.
* @return {@code true} if the given file is a file * @return {@code true} if the given file is a file
* @deprecated Use * @deprecated Use
* {@link Files#isRegularFile(java.nio.file.Path, java.nio.file.LinkOption...)} * {@link java.nio.file.Files#isRegularFile(java.nio.file.Path, java.nio.file.LinkOption...)}
* instead * instead
*/ */
@Deprecated @Deprecated
@ -186,9 +228,13 @@ public static boolean isFile(File path) {
} }
/** /**
* Whether the given file can be executed
*
* @param path * @param path
* a {@link java.io.File} object.
* @return {@code true} if the given file can be executed * @return {@code true} if the given file can be executed
* @deprecated Use {@link FileUtils#canExecute(File)} instead * @deprecated Use {@link org.eclipse.jgit.util.FileUtils#canExecute(File)}
* instead
*/ */
@Deprecated @Deprecated
public static boolean canExecute(File path) { public static boolean canExecute(File path) {
@ -196,9 +242,12 @@ public static boolean canExecute(File path) {
} }
/** /**
* Delete the given file
*
* @param path * @param path
* @throws IOException * a {@link java.io.File} object.
* @deprecated use {@link FileUtils#delete(File)} * @throws java.io.IOException
* @deprecated use {@link org.eclipse.jgit.util.FileUtils#delete(File)}
*/ */
@Deprecated @Deprecated
public static void delete(File path) throws IOException { public static void delete(File path) throws IOException {
@ -206,10 +255,16 @@ public static void delete(File path) throws IOException {
} }
/** /**
* Get file system attributes for the given file
*
* @param fs * @param fs
* a {@link org.eclipse.jgit.util.FS} object.
* @param path * @param path
* a {@link java.io.File} object.
* @return file system attributes for the given file * @return file system attributes for the given file
* @deprecated Use {@link FileUtils#getFileAttributesPosix(FS,File)} instead * @deprecated Use
* {@link org.eclipse.jgit.util.FileUtils#getFileAttributesPosix(FS,File)}
* instead
*/ */
@Deprecated @Deprecated
public static Attributes getFileAttributesPosix(FS fs, File path) { public static Attributes getFileAttributesPosix(FS fs, File path) {
@ -217,9 +272,14 @@ public static Attributes getFileAttributesPosix(FS fs, File path) {
} }
/** /**
* NFC normalize File (on Mac), otherwise do nothing
*
* @param file * @param file
* @return on Mac: NFC normalized {@link File}, otherwise the passed file * a {@link java.io.File}.
* @deprecated Use {@link FileUtils#normalize(File)} instead * @return on Mac: NFC normalized {@link java.io.File}, otherwise the passed
* file
* @deprecated Use {@link org.eclipse.jgit.util.FileUtils#normalize(File)}
* instead
*/ */
@Deprecated @Deprecated
public static File normalize(File file) { public static File normalize(File file) {
@ -227,9 +287,13 @@ public static File normalize(File file) {
} }
/** /**
* NFC normalize file name (on Mac), otherwise do nothing
*
* @param name * @param name
* a {@link java.lang.String} object.
* @return on Mac: NFC normalized form of given name * @return on Mac: NFC normalized form of given name
* @deprecated Use {@link FileUtils#normalize(String)} instead * @deprecated Use {@link org.eclipse.jgit.util.FileUtils#normalize(String)}
* instead
*/ */
@Deprecated @Deprecated
public static String normalize(String name) { public static String normalize(String name) {

170
org.eclipse.jgit/src/org/eclipse/jgit/util/FileUtils.java
View File

@ -47,7 +47,6 @@
import java.io.File; import java.io.File;
import java.io.IOException; import java.io.IOException;
import java.nio.channels.FileLock;
import java.nio.file.AtomicMoveNotSupportedException; import java.nio.file.AtomicMoveNotSupportedException;
import java.nio.file.CopyOption; import java.nio.file.CopyOption;
import java.nio.file.Files; import java.nio.file.Files;
@ -118,10 +117,9 @@ public class FileUtils {
* @param f * @param f
* {@code File} to be converted to {@code Path} * {@code File} to be converted to {@code Path}
* @return the path represented by the file * @return the path represented by the file
* @throws IOException * @throws java.io.IOException
* in case the path represented by the file is not valid ( * in case the path represented by the file is not valid (
* {@link java.nio.file.InvalidPathException}) * {@link java.nio.file.InvalidPathException})
*
* @since 4.10 * @since 4.10
*/ */
public static Path toPath(final File f) throws IOException { public static Path toPath(final File f) throws IOException {
@ -137,11 +135,11 @@ public static Path toPath(final File f) throws IOException {
* *
* @param f * @param f
* {@code File} to be deleted * {@code File} to be deleted
* @throws IOException * @throws java.io.IOException
* if deletion of {@code f} fails. This may occur if {@code f} * if deletion of {@code f} fails. This may occur if {@code f}
* didn't exist when the method was called. This can therefore * didn't exist when the method was called. This can therefore
* cause IOExceptions during race conditions when multiple * cause java.io.IOExceptions during race conditions when
* concurrent threads all try to delete the same file. * multiple concurrent threads all try to delete the same file.
*/ */
public static void delete(final File f) throws IOException { public static void delete(final File f) throws IOException {
delete(f, NONE); delete(f, NONE);
@ -157,12 +155,12 @@ public static void delete(final File f) throws IOException {
* a subtree, {@code RETRY} to retry when deletion failed. * a subtree, {@code RETRY} to retry when deletion failed.
* Retrying may help if the underlying file system doesn't allow * Retrying may help if the underlying file system doesn't allow
* deletion of files being read by another thread. * deletion of files being read by another thread.
* @throws IOException * @throws java.io.IOException
* if deletion of {@code f} fails. This may occur if {@code f} * if deletion of {@code f} fails. This may occur if {@code f}
* didn't exist when the method was called. This can therefore * didn't exist when the method was called. This can therefore
* cause IOExceptions during race conditions when multiple * cause java.io.IOExceptions during race conditions when
* concurrent threads all try to delete the same file. This * multiple concurrent threads all try to delete the same file.
* exception is not thrown when IGNORE_ERRORS is set. * This exception is not thrown when IGNORE_ERRORS is set.
*/ */
public static void delete(final File f, int options) throws IOException { public static void delete(final File f, int options) throws IOException {
FS fs = FS.DETECTED; FS fs = FS.DETECTED;
@ -239,7 +237,7 @@ public static void delete(final File f, int options) throws IOException {
* the old {@code File} * the old {@code File}
* @param dst * @param dst
* the new {@code File} * the new {@code File}
* @throws IOException * @throws java.io.IOException
* if the rename has failed * if the rename has failed
* @since 3.0 * @since 3.0
*/ */
@ -249,18 +247,20 @@ public static void rename(final File src, final File dst)
} }
/** /**
* Rename a file or folder using the passed {@link CopyOption}s. If the * Rename a file or folder using the passed
* rename fails and if we are running on a filesystem where it makes sense * {@link java.nio.file.CopyOption}s. If the rename fails and if we are
* to repeat a failing rename then repeat the rename operation up to 9 times * running on a filesystem where it makes sense to repeat a failing rename
* with 100ms sleep time between two calls. Furthermore if the destination * then repeat the rename operation up to 9 times with 100ms sleep time
* exists and is a directory hierarchy with only directories in it, the * between two calls. Furthermore if the destination exists and is a
* whole directory hierarchy will be deleted. If the target represents a * directory hierarchy with only directories in it, the whole directory
* non-empty directory structure, empty subdirectories within that structure * hierarchy will be deleted. If the target represents a non-empty directory
* may or may not be deleted even if the method fails. Furthermore if the * structure, empty subdirectories within that structure may or may not be
* destination exists and is a file then the file will be replaced if * deleted even if the method fails. Furthermore if the destination exists
* {@link StandardCopyOption#REPLACE_EXISTING} has been set. If * and is a file then the file will be replaced if
* {@link StandardCopyOption#ATOMIC_MOVE} has been set the rename will be * {@link java.nio.file.StandardCopyOption#REPLACE_EXISTING} has been set.
* done atomically or fail with an {@link AtomicMoveNotSupportedException} * If {@link java.nio.file.StandardCopyOption#ATOMIC_MOVE} has been set the
* rename will be done atomically or fail with an
* {@link java.nio.file.AtomicMoveNotSupportedException}
* *
* @param src * @param src
* the old file * the old file
@ -268,10 +268,10 @@ public static void rename(final File src, final File dst)
* the new file * the new file
* @param options * @param options
* options to pass to * options to pass to
* {@link Files#move(java.nio.file.Path, java.nio.file.Path, CopyOption...)} * {@link java.nio.file.Files#move(java.nio.file.Path, java.nio.file.Path, CopyOption...)}
* @throws AtomicMoveNotSupportedException * @throws java.nio.file.AtomicMoveNotSupportedException
* if file cannot be moved as an atomic file system operation * if file cannot be moved as an atomic file system operation
* @throws IOException * @throws java.io.IOException
* @since 4.1 * @since 4.1
*/ */
public static void rename(final File src, final File dst, public static void rename(final File src, final File dst,
@ -314,11 +314,12 @@ public static void rename(final File src, final File dst,
* *
* @param d * @param d
* directory to be created * directory to be created
* @throws IOException * @throws java.io.IOException
* if creation of {@code d} fails. This may occur if {@code d} * if creation of {@code d} fails. This may occur if {@code d}
* did exist when the method was called. This can therefore * did exist when the method was called. This can therefore
* cause IOExceptions during race conditions when multiple * cause java.io.IOExceptions during race conditions when
* concurrent threads all try to create the same directory. * multiple concurrent threads all try to create the same
* directory.
*/ */
public static void mkdir(final File d) public static void mkdir(final File d)
throws IOException { throws IOException {
@ -333,11 +334,12 @@ public static void mkdir(final File d)
* @param skipExisting * @param skipExisting
* if {@code true} skip creation of the given directory if it * if {@code true} skip creation of the given directory if it
* already exists in the file system * already exists in the file system
* @throws IOException * @throws java.io.IOException
* if creation of {@code d} fails. This may occur if {@code d} * if creation of {@code d} fails. This may occur if {@code d}
* did exist when the method was called. This can therefore * did exist when the method was called. This can therefore
* cause IOExceptions during race conditions when multiple * cause java.io.IOExceptions during race conditions when
* concurrent threads all try to create the same directory. * multiple concurrent threads all try to create the same
* directory.
*/ */
public static void mkdir(final File d, boolean skipExisting) public static void mkdir(final File d, boolean skipExisting)
throws IOException { throws IOException {
@ -357,11 +359,12 @@ public static void mkdir(final File d, boolean skipExisting)
* *
* @param d * @param d
* directory to be created * directory to be created
* @throws IOException * @throws java.io.IOException
* if creation of {@code d} fails. This may occur if {@code d} * if creation of {@code d} fails. This may occur if {@code d}
* did exist when the method was called. This can therefore * did exist when the method was called. This can therefore
* cause IOExceptions during race conditions when multiple * cause java.io.IOExceptions during race conditions when
* concurrent threads all try to create the same directory. * multiple concurrent threads all try to create the same
* directory.
*/ */
public static void mkdirs(final File d) throws IOException { public static void mkdirs(final File d) throws IOException {
mkdirs(d, false); mkdirs(d, false);
@ -378,11 +381,12 @@ public static void mkdirs(final File d) throws IOException {
* @param skipExisting * @param skipExisting
* if {@code true} skip creation of the given directory if it * if {@code true} skip creation of the given directory if it
* already exists in the file system * already exists in the file system
* @throws IOException * @throws java.io.IOException
* if creation of {@code d} fails. This may occur if {@code d} * if creation of {@code d} fails. This may occur if {@code d}
* did exist when the method was called. This can therefore * did exist when the method was called. This can therefore
* cause IOExceptions during race conditions when multiple * cause java.io.IOExceptions during race conditions when
* concurrent threads all try to create the same directory. * multiple concurrent threads all try to create the same
* directory.
*/ */
public static void mkdirs(final File d, boolean skipExisting) public static void mkdirs(final File d, boolean skipExisting)
throws IOException { throws IOException {
@ -402,12 +406,12 @@ public static void mkdirs(final File d, boolean skipExisting)
* filesystem activities that might affect the file. * filesystem activities that might affect the file.
* <p> * <p>
* Note: this method should not be used for file-locking, as the resulting * Note: this method should not be used for file-locking, as the resulting
* protocol cannot be made to work reliably. The {@link FileLock} facility * protocol cannot be made to work reliably. The
* should be used instead. * {@link java.nio.channels.FileLock} facility should be used instead.
* *
* @param f * @param f
* the file to be created * the file to be created
* @throws IOException * @throws java.io.IOException
* if the named file already exists or if an I/O error occurred * if the named file already exists or if an I/O error occurred
*/ */
public static void createNewFile(File f) throws IOException { public static void createNewFile(File f) throws IOException {
@ -424,7 +428,7 @@ public static void createNewFile(File f) throws IOException {
* @param target * @param target
* the target of the symbolic link * the target of the symbolic link
* @return the path to the symbolic link * @return the path to the symbolic link
* @throws IOException * @throws java.io.IOException
* @since 4.2 * @since 4.2
*/ */
public static Path createSymLink(File path, String target) public static Path createSymLink(File path, String target)
@ -447,9 +451,12 @@ public static Path createSymLink(File path, String target)
} }
/** /**
* Read target path of the symlink.
*
* @param path * @param path
* a {@link java.io.File} object.
* @return target path of the symlink, or null if it is not a symbolic link * @return target path of the symlink, or null if it is not a symbolic link
* @throws IOException * @throws java.io.IOException
* @since 3.0 * @since 3.0
*/ */
public static String readSymLink(File path) throws IOException { public static String readSymLink(File path) throws IOException {
@ -468,11 +475,13 @@ public static String readSymLink(File path) throws IOException {
* Create a temporary directory. * Create a temporary directory.
* *
* @param prefix * @param prefix
* prefix string
* @param suffix * @param suffix
* suffix string
* @param dir * @param dir
* The parent dir, can be null to use system default temp dir. * The parent dir, can be null to use system default temp dir.
* @return the temp dir created. * @return the temp dir created.
* @throws IOException * @throws java.io.IOException
* @since 3.4 * @since 3.4
*/ */
public static File createTempDir(String prefix, String suffix, File dir) public static File createTempDir(String prefix, String suffix, File dir)
@ -491,18 +500,19 @@ public static File createTempDir(String prefix, String suffix, File dir)
/** /**
* Relativize a path
*
* @deprecated Use the more-clearly-named * @deprecated Use the more-clearly-named
* {@link FileUtils#relativizeNativePath(String, String)} * {@link org.eclipse.jgit.util.FileUtils#relativizeNativePath(String, String)}
* instead, or directly call * instead, or directly call
* {@link FileUtils#relativizePath(String, String, String, boolean)} * {@link org.eclipse.jgit.util.FileUtils#relativizePath(String, String, String, boolean)}
* *
* Expresses <code>other</code> as a relative file path from * Expresses <code>other</code> as a relative file path from
* <code>base</code>. File-separator and case sensitivity are * <code>base</code>. File-separator and case sensitivity are
* based on the current file system. * based on the current file system.
* *
* See also * See also
* {@link FileUtils#relativizePath(String, String, String, boolean)}. * {@link org.eclipse.jgit.util.FileUtils#relativizePath(String, String, String, boolean)}.
*
* @param base * @param base
* Base path * Base path
* @param other * @param other
@ -516,15 +526,17 @@ public static String relativize(String base, String other) {
} }
/** /**
* Expresses <code>other</code> as a relative file path from <code>base</code>. * Expresses <code>other</code> as a relative file path from
* File-separator and case sensitivity are based on the current file system. * <code>base</code>. File-separator and case sensitivity are based on the
* current file system.
* *
* See also {@link FileUtils#relativizePath(String, String, String, boolean)}. * See also
* {@link org.eclipse.jgit.util.FileUtils#relativizePath(String, String, String, boolean)}.
* *
* @param base * @param base
* Base path * Base path
* @param other * @param other
* Destination path * Destination path
* @return Relative path from <code>base</code> to <code>other</code> * @return Relative path from <code>base</code> to <code>other</code>
* @since 4.8 * @since 4.8
*/ */
@ -533,15 +545,17 @@ public static String relativizeNativePath(String base, String other) {
} }
/** /**
* Expresses <code>other</code> as a relative file path from <code>base</code>. * Expresses <code>other</code> as a relative file path from
* File-separator and case sensitivity are based on Git's internal representation of files (which matches Unix). * <code>base</code>. File-separator and case sensitivity are based on Git's
* internal representation of files (which matches Unix).
* *
* See also {@link FileUtils#relativizePath(String, String, String, boolean)}. * See also
* {@link org.eclipse.jgit.util.FileUtils#relativizePath(String, String, String, boolean)}.
* *
* @param base * @param base
* Base path * Base path
* @param other * @param other
* Destination path * Destination path
* @return Relative path from <code>base</code> to <code>other</code> * @return Relative path from <code>base</code> to <code>other</code>
* @since 4.8 * @since 4.8
*/ */
@ -620,6 +634,7 @@ else if (!caseSensitive
* Determine if an IOException is a Stale NFS File Handle * Determine if an IOException is a Stale NFS File Handle
* *
* @param ioe * @param ioe
* an {@link java.io.IOException} object.
* @return a boolean true if the IOException is a Stale NFS FIle Handle * @return a boolean true if the IOException is a Stale NFS FIle Handle
* @since 4.1 * @since 4.1
*/ */
@ -635,6 +650,7 @@ public static boolean isStaleFileHandle(IOException ioe) {
* File Handle * File Handle
* *
* @param throwable * @param throwable
* a {@link java.lang.Throwable} object.
* @return a boolean true if the throwable or a cause in its causal chain is * @return a boolean true if the throwable or a cause in its causal chain is
* a Stale NFS File Handle * a Stale NFS File Handle
* @since 4.7 * @since 4.7
@ -697,9 +713,13 @@ static boolean isHidden(File file) throws IOException {
} }
/** /**
* Set a file hidden (on Windows)
*
* @param file * @param file
* a {@link java.io.File} object.
* @param hidden * @param hidden
* @throws IOException * a boolean.
* @throws java.io.IOException
* @since 4.1 * @since 4.1
*/ */
public static void setHidden(File file, boolean hidden) throws IOException { public static void setHidden(File file, boolean hidden) throws IOException {
@ -708,9 +728,12 @@ public static void setHidden(File file, boolean hidden) throws IOException {
} }
/** /**
* Get file length
*
* @param file * @param file
* a {@link java.io.File}.
* @return length of the given file * @return length of the given file
* @throws IOException * @throws java.io.IOException
* @since 4.1 * @since 4.1
*/ */
public static long getLength(File file) throws IOException { public static long getLength(File file) throws IOException {
@ -740,8 +763,11 @@ static boolean isFile(File file) {
} }
/** /**
* Whether the given file can be executed.
*
* @param file * @param file
* @return {@code true} if the given file can be executed * a {@link java.io.File} object.
* @return {@code true} if the given file can be executed.
* @since 4.1 * @since 4.1
*/ */
public static boolean canExecute(File file) { public static boolean canExecute(File file) {
@ -783,9 +809,13 @@ static Attributes getFileAttributesBasic(FS fs, File file) {
} }
/** /**
* Get file system attributes for the given file.
*
* @param fs * @param fs
* a {@link org.eclipse.jgit.util.FS} object.
* @param file * @param file
* @return file system attributes for the given file * a {@link java.io.File}.
* @return file system attributes for the given file.
* @since 4.1 * @since 4.1
*/ */
public static Attributes getFileAttributesPosix(FS fs, File file) { public static Attributes getFileAttributesPosix(FS fs, File file) {
@ -816,8 +846,12 @@ public static Attributes getFileAttributesPosix(FS fs, File file) {
} }
/** /**
* NFC normalize a file (on Mac), otherwise do nothing
*
* @param file * @param file
* @return on Mac: NFC normalized {@link File}, otherwise the passed file * a {@link java.io.File}.
* @return on Mac: NFC normalized {@link java.io.File}, otherwise the passed
* file
* @since 4.1 * @since 4.1
*/ */
public static File normalize(File file) { public static File normalize(File file) {
@ -832,7 +866,10 @@ public static File normalize(File file) {
} }
/** /**
* On Mac: get NFC normalized form of given name, otherwise the given name.
*
* @param name * @param name
* a {@link java.lang.String} object.
* @return on Mac: NFC normalized form of given name * @return on Mac: NFC normalized form of given name
* @since 4.1 * @since 4.1
*/ */
@ -846,16 +883,16 @@ public static String normalize(String name) {
} }
/** /**
* Best-effort variation of {@link File#getCanonicalFile()} returning the * Best-effort variation of {@link java.io.File#getCanonicalFile()}
* input file if the file cannot be canonicalized instead of throwing * returning the input file if the file cannot be canonicalized instead of
* {@link IOException}. * throwing {@link java.io.IOException}.
* *
* @param file * @param file
* to be canonicalized; may be {@code null} * to be canonicalized; may be {@code null}
* @return canonicalized file, or the unchanged input file if * @return canonicalized file, or the unchanged input file if
* canonicalization failed or if {@code file == null} * canonicalization failed or if {@code file == null}
* @throws SecurityException * @throws java.lang.SecurityException
* if {@link File#getCanonicalFile()} throws one * if {@link java.io.File#getCanonicalFile()} throws one
* @since 4.2 * @since 4.2
*/ */
public static File canonicalize(File file) { public static File canonicalize(File file) {
@ -873,6 +910,7 @@ public static File canonicalize(File file) {
* Convert a path to String, replacing separators as necessary. * Convert a path to String, replacing separators as necessary.
* *
* @param file * @param file
* a {@link java.io.File}.
* @return file's path as a String * @return file's path as a String
* @since 4.10 * @since 4.10
*/ */

6
org.eclipse.jgit/src/org/eclipse/jgit/util/GitDateFormatter.java
View File

@ -54,7 +54,8 @@
* A utility for formatting dates according to the Git log.date formats plus * A utility for formatting dates according to the Git log.date formats plus
* extensions. * extensions.
* <p> * <p>
* The enum {@link Format} defines the available types. * The enum {@link org.eclipse.jgit.util.GitDateFormatter.Format} defines the
* available types.
*/ */
public class GitDateFormatter { public class GitDateFormatter {
@ -119,6 +120,8 @@ static public enum Format {
* Create a new Git oriented date formatter * Create a new Git oriented date formatter
* *
* @param format * @param format
* a {@link org.eclipse.jgit.util.GitDateFormatter.Format}
* object.
*/ */
public GitDateFormatter(Format format) { public GitDateFormatter(Format format) {
this.format = format; this.format = format;
@ -159,6 +162,7 @@ public GitDateFormatter(Format format) {
* specification. * specification.
* *
* @param ident * @param ident
* a {@link org.eclipse.jgit.lib.PersonIdent} object.
* @return formatted version of date, time and time zone * @return formatted version of date, time and time zone
*/ */
@SuppressWarnings("boxing") @SuppressWarnings("boxing")

38
org.eclipse.jgit/src/org/eclipse/jgit/util/GitDateParser.java
View File

@ -55,7 +55,7 @@
import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.internal.JGitText;
/** /**
* Parses strings with time and date specifications into {@link Date}. * Parses strings with time and date specifications into {@link java.util.Date}.
* *
* When git needs to parse strings specified by the user this parser can be * When git needs to parse strings specified by the user this parser can be
* used. One example is the parsing of the config parameter gc.pruneexpire. The * used. One example is the parsing of the config parameter gc.pruneexpire. The
@ -134,16 +134,17 @@ private ParseableSimpleDateFormat(String formatStr) {
} }
/** /**
* Parses a string into a {@link Date} using the default locale. Since this * Parses a string into a {@link java.util.Date} using the default locale.
* parser also supports relative formats (e.g. "yesterday") the caller can * Since this parser also supports relative formats (e.g. "yesterday") the
* specify the reference date. These types of strings can be parsed: * caller can specify the reference date. These types of strings can be
* parsed:
* <ul> * <ul>
* <li>"never"</li> * <li>"never"</li>
* <li>"now"</li> * <li>"now"</li>
* <li>"yesterday"</li> * <li>"yesterday"</li>
* <li>"(x) years|months|weeks|days|hours|minutes|seconds ago"<br> * <li>"(x) years|months|weeks|days|hours|minutes|seconds ago"<br>
* Multiple specs can be combined like in "2 weeks 3 days ago". Instead of * Multiple specs can be combined like in "2 weeks 3 days ago". Instead of '
* ' ' one can use '.' to seperate the words</li> * ' one can use '.' to seperate the words</li>
* <li>"yyyy-MM-dd HH:mm:ss Z" (ISO)</li> * <li>"yyyy-MM-dd HH:mm:ss Z" (ISO)</li>
* <li>"EEE, dd MMM yyyy HH:mm:ss Z" (RFC)</li> * <li>"EEE, dd MMM yyyy HH:mm:ss Z" (RFC)</li>
* <li>"yyyy-MM-dd"</li> * <li>"yyyy-MM-dd"</li>
@ -161,11 +162,12 @@ private ParseableSimpleDateFormat(String formatStr) {
* formats. E.g. if baseDate is "25.8.2012" then parsing of the * formats. E.g. if baseDate is "25.8.2012" then parsing of the
* string "1 week ago" would result in a date corresponding to * string "1 week ago" would result in a date corresponding to
* "18.8.2012". This is used when a JGit command calls this * "18.8.2012". This is used when a JGit command calls this
* parser often but wants a consistent starting point for calls.<br> * parser often but wants a consistent starting point for
* calls.<br>
* If set to <code>null</code> then the current time will be used * If set to <code>null</code> then the current time will be used
* instead. * instead.
* @return the parsed {@link Date} * @return the parsed {@link java.util.Date}
* @throws ParseException * @throws java.text.ParseException
* if the given dateStr was not recognized * if the given dateStr was not recognized
*/ */
public static Date parse(String dateStr, Calendar now) public static Date parse(String dateStr, Calendar now)
@ -174,16 +176,17 @@ public static Date parse(String dateStr, Calendar now)
} }
/** /**
* Parses a string into a {@link Date} using the given locale. Since this * Parses a string into a {@link java.util.Date} using the given locale.
* parser also supports relative formats (e.g. "yesterday") the caller can * Since this parser also supports relative formats (e.g. "yesterday") the
* specify the reference date. These types of strings can be parsed: * caller can specify the reference date. These types of strings can be
* parsed:
* <ul> * <ul>
* <li>"never"</li> * <li>"never"</li>
* <li>"now"</li> * <li>"now"</li>
* <li>"yesterday"</li> * <li>"yesterday"</li>
* <li>"(x) years|months|weeks|days|hours|minutes|seconds ago"<br> * <li>"(x) years|months|weeks|days|hours|minutes|seconds ago"<br>
* Multiple specs can be combined like in "2 weeks 3 days ago". Instead of * Multiple specs can be combined like in "2 weeks 3 days ago". Instead of '
* ' ' one can use '.' to seperate the words</li> * ' one can use '.' to seperate the words</li>
* <li>"yyyy-MM-dd HH:mm:ss Z" (ISO)</li> * <li>"yyyy-MM-dd HH:mm:ss Z" (ISO)</li>
* <li>"EEE, dd MMM yyyy HH:mm:ss Z" (RFC)</li> * <li>"EEE, dd MMM yyyy HH:mm:ss Z" (RFC)</li>
* <li>"yyyy-MM-dd"</li> * <li>"yyyy-MM-dd"</li>
@ -201,13 +204,14 @@ public static Date parse(String dateStr, Calendar now)
* formats. E.g. if baseDate is "25.8.2012" then parsing of the * formats. E.g. if baseDate is "25.8.2012" then parsing of the
* string "1 week ago" would result in a date corresponding to * string "1 week ago" would result in a date corresponding to
* "18.8.2012". This is used when a JGit command calls this * "18.8.2012". This is used when a JGit command calls this
* parser often but wants a consistent starting point for calls.<br> * parser often but wants a consistent starting point for
* calls.<br>
* If set to <code>null</code> then the current time will be used * If set to <code>null</code> then the current time will be used
* instead. * instead.
* @param locale * @param locale
* locale to be used to parse the date string * locale to be used to parse the date string
* @return the parsed {@link Date} * @return the parsed {@link java.util.Date}
* @throws ParseException * @throws java.text.ParseException
* if the given dateStr was not recognized * if the given dateStr was not recognized
* @since 3.2 * @since 3.2
*/ */

14
org.eclipse.jgit/src/org/eclipse/jgit/util/Holder.java
View File

@ -45,14 +45,15 @@
* Holder of an object. * Holder of an object.
* *
* @param <T> * @param <T>
* the type of value held by this {@link Holder} * the type of value held by this {@link org.eclipse.jgit.util.Holder}
*
* @since 4.3 * @since 4.3
*/ */
public class Holder<T> { public class Holder<T> {
private T value; private T value;
/** /**
* <p>Constructor for Holder.</p>
*
* @param value * @param value
* is the initial value that is {@link #set(Object)} * is the initial value that is {@link #set(Object)}
*/ */
@ -61,15 +62,20 @@ public Holder(T value) {
} }
/** /**
* @return the value held by this {@link Holder} * Get the value held by this {@link org.eclipse.jgit.util.Holder}
*
* @return the value held by this {@link org.eclipse.jgit.util.Holder}
*/ */
public T get() { public T get() {
return value; return value;
} }
/** /**
* Set a new value held by this {@link org.eclipse.jgit.util.Holder}
*
* @param value * @param value
* to be set as new value held by this {@link Holder} * to be set as new value held by this
* {@link org.eclipse.jgit.util.Holder}
*/ */
public void set(T value) { public void set(T value) {
this.value = value; this.value = value;

22
org.eclipse.jgit/src/org/eclipse/jgit/util/HttpSupport.java
View File

@ -65,7 +65,9 @@
import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.internal.JGitText;
import org.eclipse.jgit.transport.http.HttpConnection; import org.eclipse.jgit.transport.http.HttpConnection;
/** Extra utilities to support usage of HTTP. */ /**
* Extra utilities to support usage of HTTP.
*/
public class HttpSupport { public class HttpSupport {
/** The {@code GET} HTTP method. */ /** The {@code GET} HTTP method. */
public static final String METHOD_GET = "GET"; //$NON-NLS-1$ public static final String METHOD_GET = "GET"; //$NON-NLS-1$
@ -192,8 +194,9 @@ public static void encode(final StringBuilder urlstr, final String key) {
* @param c * @param c
* connection the code should be obtained from. * connection the code should be obtained from.
* @return r HTTP status code, usually 200 to indicate success. See * @return r HTTP status code, usually 200 to indicate success. See
* {@link HttpConnection} for other defined constants. * {@link org.eclipse.jgit.transport.http.HttpConnection} for other
* @throws IOException * defined constants.
* @throws java.io.IOException
* communications error prevented obtaining the response code. * communications error prevented obtaining the response code.
* @since 3.3 * @since 3.3
*/ */
@ -220,8 +223,9 @@ public static int response(final HttpConnection c) throws IOException {
* @param c * @param c
* connection the code should be obtained from. * connection the code should be obtained from.
* @return r HTTP status code, usually 200 to indicate success. See * @return r HTTP status code, usually 200 to indicate success. See
* {@link HttpConnection} for other defined constants. * {@link org.eclipse.jgit.transport.http.HttpConnection} for other
* @throws IOException * defined constants.
* @throws java.io.IOException
* communications error prevented obtaining the response code. * communications error prevented obtaining the response code.
*/ */
public static int response(final java.net.HttpURLConnection c) public static int response(final java.net.HttpURLConnection c)
@ -248,7 +252,7 @@ public static int response(final java.net.HttpURLConnection c)
* @param headerName * @param headerName
* the header name * the header name
* @return the header value * @return the header value
* @throws IOException * @throws java.io.IOException
* communications error prevented obtaining the header. * communications error prevented obtaining the header.
* @since 4.7 * @since 4.7
*/ */
@ -265,7 +269,7 @@ public static String responseHeader(final HttpConnection c,
* @param u * @param u
* location of the server caller wants to talk to. * location of the server caller wants to talk to.
* @return proxy to communicate with the supplied URL. * @return proxy to communicate with the supplied URL.
* @throws ConnectException * @throws java.net.ConnectException
* the proxy could not be computed as the supplied URL could not * the proxy could not be computed as the supplied URL could not
* be read. This failure should never occur. * be read. This failure should never occur.
*/ */
@ -285,7 +289,9 @@ public static Proxy proxyFor(final ProxySelector proxySelector, final URL u)
* Disable SSL and hostname verification for given HTTP connection * Disable SSL and hostname verification for given HTTP connection
* *
* @param conn * @param conn
* @throws IOException * a {@link org.eclipse.jgit.transport.http.HttpConnection}
* object.
* @throws java.io.IOException
* @since 4.3 * @since 4.3
*/ */
public static void disableSslVerify(HttpConnection conn) public static void disableSslVerify(HttpConnection conn)

24
org.eclipse.jgit/src/org/eclipse/jgit/util/IO.java
View File

@ -71,9 +71,9 @@ public class IO {
* @param path * @param path
* location of the file to read. * location of the file to read.
* @return complete contents of the requested local file. * @return complete contents of the requested local file.
* @throws FileNotFoundException * @throws java.io.FileNotFoundException
* the file does not exist. * the file does not exist.
* @throws IOException * @throws java.io.IOException
* the file exists, but its contents cannot be read. * the file exists, but its contents cannot be read.
*/ */
public static final byte[] readFully(final File path) public static final byte[] readFully(final File path)
@ -91,9 +91,9 @@ public static final byte[] readFully(final File path)
* only the first limit number of bytes are returned * only the first limit number of bytes are returned
* @return complete contents of the requested local file. If the contents * @return complete contents of the requested local file. If the contents
* exceeds the limit, then only the limit is returned. * exceeds the limit, then only the limit is returned.
* @throws FileNotFoundException * @throws java.io.FileNotFoundException
* the file does not exist. * the file does not exist.
* @throws IOException * @throws java.io.IOException
* the file exists, but its contents cannot be read. * the file exists, but its contents cannot be read.
*/ */
public static final byte[] readSome(final File path, final int limit) public static final byte[] readSome(final File path, final int limit)
@ -131,9 +131,9 @@ public static final byte[] readSome(final File path, final int limit)
* maximum number of bytes to read, if the file is larger than * maximum number of bytes to read, if the file is larger than
* this limit an IOException is thrown. * this limit an IOException is thrown.
* @return complete contents of the requested local file. * @return complete contents of the requested local file.
* @throws FileNotFoundException * @throws java.io.FileNotFoundException
* the file does not exist. * the file does not exist.
* @throws IOException * @throws java.io.IOException
* the file exists, but its contents cannot be read. * the file exists, but its contents cannot be read.
*/ */
public static final byte[] readFully(final File path, final int max) public static final byte[] readFully(final File path, final int max)
@ -199,7 +199,7 @@ public static final byte[] readFully(final File path, final int max)
* on obtaining the underlying array for efficient data access. If * on obtaining the underlying array for efficient data access. If
* {@code sizeHint} was too large, the array may be over-allocated, * {@code sizeHint} was too large, the array may be over-allocated,
* resulting in {@code limit() < array().length}. * resulting in {@code limit() < array().length}.
* @throws IOException * @throws java.io.IOException
* there was an error reading from the stream. * there was an error reading from the stream.
*/ */
public static ByteBuffer readWholeStream(InputStream in, int sizeHint) public static ByteBuffer readWholeStream(InputStream in, int sizeHint)
@ -238,7 +238,7 @@ public static ByteBuffer readWholeStream(InputStream in, int sizeHint)
* number of bytes that must be read. * number of bytes that must be read.
* @throws EOFException * @throws EOFException
* the stream ended before dst was fully populated. * the stream ended before dst was fully populated.
* @throws IOException * @throws java.io.IOException
* there was an error reading from the stream. * there was an error reading from the stream.
*/ */
public static void readFully(final InputStream fd, final byte[] dst, public static void readFully(final InputStream fd, final byte[] dst,
@ -264,7 +264,7 @@ public static void readFully(final InputStream fd, final byte[] dst,
* @param len * @param len
* number of bytes that should be read. * number of bytes that should be read.
* @return number of bytes actually read. * @return number of bytes actually read.
* @throws IOException * @throws java.io.IOException
* there was an error reading from the channel. * there was an error reading from the channel.
*/ */
public static int read(ReadableByteChannel channel, byte[] dst, int off, public static int read(ReadableByteChannel channel, byte[] dst, int off,
@ -293,7 +293,7 @@ public static int read(ReadableByteChannel channel, byte[] dst, int off,
* @param off * @param off
* position within the buffer to start writing to. * position within the buffer to start writing to.
* @return number of bytes in buffer or stream, whichever is shortest * @return number of bytes in buffer or stream, whichever is shortest
* @throws IOException * @throws java.io.IOException
* there was an error reading from the stream. * there was an error reading from the stream.
*/ */
public static int readFully(InputStream fd, byte[] dst, int off) public static int readFully(InputStream fd, byte[] dst, int off)
@ -322,7 +322,7 @@ public static int readFully(InputStream fd, byte[] dst, int off)
* @throws EOFException * @throws EOFException
* the stream ended before the requested number of bytes were * the stream ended before the requested number of bytes were
* skipped. * skipped.
* @throws IOException * @throws java.io.IOException
* there was an error reading from the stream. * there was an error reading from the stream.
*/ */
public static void skipFully(final InputStream fd, long toSkip) public static void skipFully(final InputStream fd, long toSkip)
@ -384,7 +384,7 @@ public static List<String> readLines(final String s) {
* hint for buffer sizing; 0 or negative for default. * hint for buffer sizing; 0 or negative for default.
* @return the next line from the input, always ending in {@code \n} unless * @return the next line from the input, always ending in {@code \n} unless
* EOF was reached. * EOF was reached.
* @throws IOException * @throws java.io.IOException
* there was an error reading from the stream. * there was an error reading from the stream.
* @since 4.1 * @since 4.1
*/ */

23
org.eclipse.jgit/src/org/eclipse/jgit/util/IntList.java
View File

@ -44,13 +44,17 @@
package org.eclipse.jgit.util; package org.eclipse.jgit.util;
/** A more efficient List&lt;Integer&gt; using a primitive integer array. */ /**
* A more efficient List&lt;Integer&gt; using a primitive integer array.
*/
public class IntList { public class IntList {
private int[] entries; private int[] entries;
private int count; private int count;
/** Create an empty list with a default capacity. */ /**
* Create an empty list with a default capacity.
*/
public IntList() { public IntList() {
this(10); this(10);
} }
@ -65,7 +69,11 @@ public IntList(final int capacity) {
entries = new int[capacity]; entries = new int[capacity];
} }
/** @return number of entries in this list */ /**
* Get number of entries in this list.
*
* @return number of entries in this list.
*/
public int size() { public int size() {
return count; return count;
} }
@ -86,10 +94,12 @@ public boolean contains(int value) {
} }
/** /**
* Get the value at the specified index
*
* @param i * @param i
* index to read, must be in the range [0, {@link #size()}). * index to read, must be in the range [0, {@link #size()}).
* @return the number at the specified index * @return the number at the specified index
* @throws ArrayIndexOutOfBoundsException * @throws java.lang.ArrayIndexOutOfBoundsException
* the index outside the valid range * the index outside the valid range
*/ */
public int get(final int i) { public int get(final int i) {
@ -98,7 +108,9 @@ public int get(final int i) {
return entries[i]; return entries[i];
} }
/** Empty this list */ /**
* Empty this list
*/
public void clear() { public void clear() {
count = 0; count = 0;
} }
@ -153,6 +165,7 @@ private void grow() {
entries = n; entries = n;
} }
/** {@inheritDoc} */
@Override @Override
public String toString() { public String toString() {
final StringBuilder r = new StringBuilder(); final StringBuilder r = new StringBuilder();

27
org.eclipse.jgit/src/org/eclipse/jgit/util/LongList.java
View File

@ -46,13 +46,17 @@
import java.util.Arrays; import java.util.Arrays;
/** A more efficient List&lt;Long&gt; using a primitive long array. */ /**
* A more efficient List&lt;Long&gt; using a primitive long array.
*/
public class LongList { public class LongList {
private long[] entries; private long[] entries;
private int count; private int count;
/** Create an empty list with a default capacity. */ /**
* Create an empty list with a default capacity.
*/
public LongList() { public LongList() {
this(10); this(10);
} }
@ -67,16 +71,22 @@ public LongList(final int capacity) {
entries = new long[capacity]; entries = new long[capacity];
} }
/** @return number of entries in this list */ /**
* Get number of entries in this list
*
* @return number of entries in this list
*/
public int size() { public int size() {
return count; return count;
} }
/** /**
* Get the value at the specified index
*
* @param i * @param i
* index to read, must be in the range [0, {@link #size()}). * index to read, must be in the range [0, {@link #size()}).
* @return the number at the specified index * @return the number at the specified index
* @throws ArrayIndexOutOfBoundsException * @throws java.lang.ArrayIndexOutOfBoundsException
* the index outside the valid range * the index outside the valid range
*/ */
public long get(final int i) { public long get(final int i) {
@ -99,7 +109,9 @@ public boolean contains(final long value) {
return false; return false;
} }
/** Empty this list */ /**
* Clear this list
*/
public void clear() { public void clear() {
count = 0; count = 0;
} }
@ -148,7 +160,9 @@ public void fillTo(int toIndex, final long val) {
add(val); add(val);
} }
/** Sort the list of longs according to their natural ordering. */ /**
* Sort the list of longs according to their natural ordering.
*/
public void sort() { public void sort() {
Arrays.sort(entries, 0, count); Arrays.sort(entries, 0, count);
} }
@ -159,6 +173,7 @@ private void grow() {
entries = n; entries = n;
} }
/** {@inheritDoc} */
@Override @Override
public String toString() { public String toString() {
final StringBuilder r = new StringBuilder(); final StringBuilder r = new StringBuilder();

14
org.eclipse.jgit/src/org/eclipse/jgit/util/LongMap.java
View File

@ -61,13 +61,17 @@ public class LongMap<V> {
/** Next {@link #size} to trigger a {@link #grow()}. */ /** Next {@link #size} to trigger a {@link #grow()}. */
private int growAt; private int growAt;
/** Initialize an empty LongMap. */ /**
* Initialize an empty LongMap.
*/
public LongMap() { public LongMap() {
table = createArray(64); table = createArray(64);
growAt = (int) (table.length * LOAD_FACTOR); growAt = (int) (table.length * LOAD_FACTOR);
} }
/** /**
* Whether {@code key} is present in the map.
*
* @param key * @param key
* the key to find. * the key to find.
* @return {@code true} if {@code key} is present in the map. * @return {@code true} if {@code key} is present in the map.
@ -77,9 +81,11 @@ public boolean containsKey(long key) {
} }
/** /**
* Get value for this {@code key}
*
* @param key * @param key
* the key to find. * the key to find.
* @return stored value of the key, or {@code null}. * @return stored value for this key, or {@code null}.
*/ */
public V get(long key) { public V get(long key) {
for (Node<V> n = table[index(key)]; n != null; n = n.next) { for (Node<V> n = table[index(key)]; n != null; n = n.next) {
@ -90,6 +96,8 @@ public V get(long key) {
} }
/** /**
* Remove an entry from the map
*
* @param key * @param key
* key to remove from the map. * key to remove from the map.
* @return old value of the key, or {@code null}. * @return old value of the key, or {@code null}.
@ -113,6 +121,8 @@ public V remove(long key) {
} }
/** /**
* Put a new entry into the map
*
* @param key * @param key
* key to store {@code value} under. * key to store {@code value} under.
* @param value * @param value

4
org.eclipse.jgit/src/org/eclipse/jgit/util/MutableInteger.java
View File

@ -43,7 +43,9 @@
package org.eclipse.jgit.util; package org.eclipse.jgit.util;
/** A boxed integer that can be modified. */ /**
* A boxed integer that can be modified.
*/
public final class MutableInteger { public final class MutableInteger {
/** Current value of this boxed value. */ /** Current value of this boxed value. */
public int value; public int value;

4
org.eclipse.jgit/src/org/eclipse/jgit/util/NB.java
View File

@ -43,7 +43,9 @@
package org.eclipse.jgit.util; package org.eclipse.jgit.util;
/** Conversion utilities for network byte order handling. */ /**
* Conversion utilities for network byte order handling.
*/
public final class NB { public final class NB {
/** /**
* Compare a 32 bit unsigned integer stored in a 32 bit signed integer. * Compare a 32 bit unsigned integer stored in a 32 bit signed integer.

8
org.eclipse.jgit/src/org/eclipse/jgit/util/ProcessResult.java
View File

@ -86,6 +86,8 @@ public ProcessResult(Status status) {
} }
/** /**
* <p>Constructor for ProcessResult.</p>
*
* @param exitCode * @param exitCode
* Exit code of the process. * Exit code of the process.
* @param status * @param status
@ -97,6 +99,8 @@ public ProcessResult(int exitCode, Status status) {
} }
/** /**
* Get exit code of the process.
*
* @return The exit code of the process. * @return The exit code of the process.
*/ */
public int getExitCode() { public int getExitCode() {
@ -104,6 +108,8 @@ public int getExitCode() {
} }
/** /**
* Get the status of the process' execution.
*
* @return The status of the process' execution. * @return The status of the process' execution.
*/ */
public Status getStatus() { public Status getStatus() {
@ -111,6 +117,8 @@ public Status getStatus() {
} }
/** /**
* Whether the execution occurred and resulted in an error
*
* @return <code>true</code> if the execution occurred and resulted in a * @return <code>true</code> if the execution occurred and resulted in a
* return code different from 0, <code>false</code> otherwise. * return code different from 0, <code>false</code> otherwise.
* @since 4.0 * @since 4.0

4
org.eclipse.jgit/src/org/eclipse/jgit/util/QuotedString.java
View File

@ -47,7 +47,9 @@
import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.lib.Constants;
/** Utility functions related to quoted string handling. */ /**
* Utility functions related to quoted string handling.
*/
public abstract class QuotedString { public abstract class QuotedString {
/** Quoting style that obeys the rules Git applies to file names */ /** Quoting style that obeys the rules Git applies to file names */
public static final GitPathStyle GIT_PATH = new GitPathStyle(); public static final GitPathStyle GIT_PATH = new GitPathStyle();

4
org.eclipse.jgit/src/org/eclipse/jgit/util/RawCharSequence.java
View File

@ -74,21 +74,25 @@ public RawCharSequence(final byte[] buf, final int start, final int end) {
endPtr = end; endPtr = end;
} }
/** {@inheritDoc} */
@Override @Override
public char charAt(final int index) { public char charAt(final int index) {
return (char) (buffer[startPtr + index] & 0xff); return (char) (buffer[startPtr + index] & 0xff);
} }
/** {@inheritDoc} */
@Override @Override
public int length() { public int length() {
return endPtr - startPtr; return endPtr - startPtr;
} }
/** {@inheritDoc} */
@Override @Override
public CharSequence subSequence(final int start, final int end) { public CharSequence subSequence(final int start, final int end) {
return new RawCharSequence(buffer, startPtr + start, startPtr + end); return new RawCharSequence(buffer, startPtr + start, startPtr + end);
} }
/** {@inheritDoc} */
@Override @Override
public String toString() { public String toString() {
final int n = length(); final int n = length();

24
org.eclipse.jgit/src/org/eclipse/jgit/util/RawParseUtils.java
View File

@ -66,7 +66,9 @@
import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.lib.Constants;
import org.eclipse.jgit.lib.PersonIdent; import org.eclipse.jgit.lib.PersonIdent;
/** Handy utility functions to parse raw object contents. */ /**
* Handy utility functions to parse raw object contents.
*/
public final class RawParseUtils { public final class RawParseUtils {
/** /**
* UTF-8 charset constant. * UTF-8 charset constant.
@ -306,7 +308,7 @@ public static final long parseLongBase10(final byte[] b, int ptr,
* @param p * @param p
* first position within the buffer to parse. * first position within the buffer to parse.
* @return the integer value. * @return the integer value.
* @throws ArrayIndexOutOfBoundsException * @throws java.lang.ArrayIndexOutOfBoundsException
* if the string is not hex formatted. * if the string is not hex formatted.
*/ */
public static final int parseHexInt16(final byte[] bs, final int p) { public static final int parseHexInt16(final byte[] bs, final int p) {
@ -336,7 +338,7 @@ public static final int parseHexInt16(final byte[] bs, final int p) {
* @param p * @param p
* first position within the buffer to parse. * first position within the buffer to parse.
* @return the integer value. * @return the integer value.
* @throws ArrayIndexOutOfBoundsException * @throws java.lang.ArrayIndexOutOfBoundsException
* if the string is not hex formatted. * if the string is not hex formatted.
*/ */
public static final int parseHexInt32(final byte[] bs, final int p) { public static final int parseHexInt32(final byte[] bs, final int p) {
@ -377,7 +379,7 @@ public static final int parseHexInt32(final byte[] bs, final int p) {
* @param p * @param p
* first position within the buffer to parse. * first position within the buffer to parse.
* @return the integer value. * @return the integer value.
* @throws ArrayIndexOutOfBoundsException * @throws java.lang.ArrayIndexOutOfBoundsException
* if the string is not hex formatted. * if the string is not hex formatted.
* @since 4.3 * @since 4.3
*/ */
@ -437,7 +439,7 @@ public static final long parseHexInt64(final byte[] bs, final int p) {
* @param digit * @param digit
* hex character to parse. * hex character to parse.
* @return numeric value, in the range 0-15. * @return numeric value, in the range 0-15.
* @throws ArrayIndexOutOfBoundsException * @throws java.lang.ArrayIndexOutOfBoundsException
* if the input digit is not a valid hex digit. * if the input digit is not a valid hex digit.
*/ */
public static final int parseHexInt4(final byte digit) { public static final int parseHexInt4(final byte digit) {
@ -610,7 +612,7 @@ public static final int prevLF(final byte[] b, int ptr, final char chrA) {
* Index the region between <code>[ptr, end)</code> to find line starts. * Index the region between <code>[ptr, end)</code> to find line starts.
* <p> * <p>
* The returned list is 1 indexed. Index 0 contains * The returned list is 1 indexed. Index 0 contains
* {@link Integer#MIN_VALUE} to pad the list out. * {@link java.lang.Integer#MIN_VALUE} to pad the list out.
* <p> * <p>
* Using a 1 indexed list means that line numbers can be directly accessed * Using a 1 indexed list means that line numbers can be directly accessed
* from the list, so <code>list.get(1)</code> (aka get line 1) returns * from the list, so <code>list.get(1)</code> (aka get line 1) returns
@ -619,8 +621,8 @@ public static final int prevLF(final byte[] b, int ptr, final char chrA) {
* The last element (index <code>map.size()-1</code>) always contains * The last element (index <code>map.size()-1</code>) always contains
* <code>end</code>. * <code>end</code>.
* <p> * <p>
* If the data contains a '\0' anywhere, the whole region is considered binary * If the data contains a '\0' anywhere, the whole region is considered
* and a LineMap corresponding to a single line is returned. * binary and a LineMap corresponding to a single line is returned.
* </p> * </p>
* *
* @param buf * @param buf
@ -1076,7 +1078,7 @@ public static String decode(final Charset cs, final byte[] buffer,
* data from. * data from.
* @return a string representation of the range <code>[start,end)</code>, * @return a string representation of the range <code>[start,end)</code>,
* after decoding the region through the specified character set. * after decoding the region through the specified character set.
* @throws CharacterCodingException * @throws java.nio.charset.CharacterCodingException
* the input is not in any of the tested character sets. * the input is not in any of the tested character sets.
*/ */
public static String decodeNoFallback(final Charset cs, public static String decodeNoFallback(final Charset cs,
@ -1222,13 +1224,15 @@ public static final int endOfParagraph(final byte[] b, final int start) {
} }
/** /**
* Get last index of {@code ch} in raw, trimming spaces.
*
* @param raw * @param raw
* buffer to scan. * buffer to scan.
* @param ch * @param ch
* character to find. * character to find.
* @param pos * @param pos
* starting position. * starting position.
* @return last index of ch in raw, trimming spaces. * @return last index of {@code ch} in raw, trimming spaces.
* @since 4.1 * @since 4.1
*/ */
public static int lastIndexOfTrim(byte[] raw, char ch, int pos) { public static int lastIndexOfTrim(byte[] raw, char ch, int pos) {

1
org.eclipse.jgit/src/org/eclipse/jgit/util/RawSubStringPattern.java
View File

@ -131,6 +131,7 @@ public String pattern() {
return needleString; return needleString;
} }
/** {@inheritDoc} */
@Override @Override
public String toString() { public String toString() {
return pattern(); return pattern();

24
org.eclipse.jgit/src/org/eclipse/jgit/util/RefList.java
View File

@ -71,9 +71,9 @@ public class RefList<T extends Ref> implements Iterable<Ref> {
private static final RefList<Ref> EMPTY = new RefList<>(new Ref[0], 0); private static final RefList<Ref> EMPTY = new RefList<>(new Ref[0], 0);
/** /**
* Create an empty unmodifiable reference list.
*
* @return an empty unmodifiable reference list. * @return an empty unmodifiable reference list.
* @param <T>
* the type of reference being stored in the collection.
*/ */
@SuppressWarnings("unchecked") @SuppressWarnings("unchecked")
public static <T extends Ref> RefList<T> emptyList() { public static <T extends Ref> RefList<T> emptyList() {
@ -100,6 +100,7 @@ protected RefList(RefList<T> src) {
this.cnt = src.cnt; this.cnt = src.cnt;
} }
/** {@inheritDoc} */
@Override @Override
public Iterator<Ref> iterator() { public Iterator<Ref> iterator() {
return new Iterator<Ref>() { return new Iterator<Ref>() {
@ -124,18 +125,30 @@ public void remove() {
}; };
} }
/** @return this cast as an immutable, standard {@link java.util.List}. */ /**
* Cast {@code this} as an immutable, standard {@link java.util.List}.
*
* @return {@code this} as an immutable, standard {@link java.util.List}.
*/
public final List<Ref> asList() { public final List<Ref> asList() {
final List<Ref> r = Arrays.asList(list).subList(0, cnt); final List<Ref> r = Arrays.asList(list).subList(0, cnt);
return Collections.unmodifiableList(r); return Collections.unmodifiableList(r);
} }
/** @return number of items in this list. */ /**
* Get number of items in this list.
*
* @return number of items in this list.
*/
public final int size() { public final int size() {
return cnt; return cnt;
} }
/** @return true if the size of this list is 0. */ /**
* Get if this list is empty.
*
* @return true if the size of this list is 0.
*/
public final boolean isEmpty() { public final boolean isEmpty() {
return cnt == 0; return cnt == 0;
} }
@ -303,6 +316,7 @@ public final RefList<T> put(T ref) {
return add(idx, ref); return add(idx, ref);
} }
/** {@inheritDoc} */
@Override @Override
public String toString() { public String toString() {
StringBuilder r = new StringBuilder(); StringBuilder r = new StringBuilder();

23
org.eclipse.jgit/src/org/eclipse/jgit/util/RefMap.java
View File

@ -59,17 +59,19 @@
* Specialized Map to present a {@code RefDatabase} namespace. * Specialized Map to present a {@code RefDatabase} namespace.
* <p> * <p>
* Although not declared as a {@link java.util.SortedMap}, iterators from this * Although not declared as a {@link java.util.SortedMap}, iterators from this
* map's projections always return references in {@link RefComparator} ordering. * map's projections always return references in
* The map's internal representation is a sorted array of {@link Ref} objects, * {@link org.eclipse.jgit.lib.RefComparator} ordering. The map's internal
* representation is a sorted array of {@link org.eclipse.jgit.lib.Ref} objects,
* which means lookup and replacement is O(log N), while insertion and removal * which means lookup and replacement is O(log N), while insertion and removal
* can be as expensive as O(N + log N) while the list expands or contracts. * can be as expensive as O(N + log N) while the list expands or contracts.
* Since this is not a general map implementation, all entries must be keyed by * Since this is not a general map implementation, all entries must be keyed by
* the reference name. * the reference name.
* <p> * <p>
* This class is really intended as a helper for {@code RefDatabase}, which * This class is really intended as a helper for {@code RefDatabase}, which
* needs to perform a merge-join of three sorted {@link RefList}s in order to * needs to perform a merge-join of three sorted
* present the unified namespace of the packed-refs file, the loose refs/ * {@link org.eclipse.jgit.util.RefList}s in order to present the unified
* directory tree, and the resolved form of any symbolic references. * namespace of the packed-refs file, the loose refs/ directory tree, and the
* resolved form of any symbolic references.
*/ */
public class RefMap extends AbstractMap<String, Ref> { public class RefMap extends AbstractMap<String, Ref> {
/** /**
@ -109,7 +111,9 @@ public class RefMap extends AbstractMap<String, Ref> {
private Set<Entry<String, Ref>> entrySet; private Set<Entry<String, Ref>> entrySet;
/** Construct an empty map with a small initial capacity. */ /**
* Construct an empty map with a small initial capacity.
*/
public RefMap() { public RefMap() {
prefix = ""; //$NON-NLS-1$ prefix = ""; //$NON-NLS-1$
packed = RefList.emptyList(); packed = RefList.emptyList();
@ -145,11 +149,13 @@ public RefMap(String prefix, RefList<? extends Ref> packed,
this.resolved = (RefList<Ref>) resolved; this.resolved = (RefList<Ref>) resolved;
} }
/** {@inheritDoc} */
@Override @Override
public boolean containsKey(Object name) { public boolean containsKey(Object name) {
return get(name) != null; return get(name) != null;
} }
/** {@inheritDoc} */
@Override @Override
public Ref get(Object key) { public Ref get(Object key) {
String name = toRefName((String) key); String name = toRefName((String) key);
@ -161,6 +167,7 @@ public Ref get(Object key) {
return ref; return ref;
} }
/** {@inheritDoc} */
@Override @Override
public Ref put(final String keyName, Ref value) { public Ref put(final String keyName, Ref value) {
String name = toRefName(keyName); String name = toRefName(keyName);
@ -189,6 +196,7 @@ public Ref put(final String keyName, Ref value) {
} }
} }
/** {@inheritDoc} */
@Override @Override
public Ref remove(Object key) { public Ref remove(Object key) {
String name = toRefName((String) key); String name = toRefName((String) key);
@ -212,11 +220,13 @@ public Ref remove(Object key) {
return res; return res;
} }
/** {@inheritDoc} */
@Override @Override
public boolean isEmpty() { public boolean isEmpty() {
return entrySet().isEmpty(); return entrySet().isEmpty();
} }
/** {@inheritDoc} */
@Override @Override
public Set<Entry<String, Ref>> entrySet() { public Set<Entry<String, Ref>> entrySet() {
if (entrySet == null) { if (entrySet == null) {
@ -258,6 +268,7 @@ public void clear() {
return entrySet; return entrySet;
} }
/** {@inheritDoc} */
@Override @Override
public String toString() { public String toString() {
StringBuilder r = new StringBuilder(); StringBuilder r = new StringBuilder();

10
org.eclipse.jgit/src/org/eclipse/jgit/util/RelativeDateFormatter.java
View File

@ -67,10 +67,14 @@ public class RelativeDateFormatter {
final static long YEAR_IN_MILLIS = 365 * DAY_IN_MILLIS; final static long YEAR_IN_MILLIS = 365 * DAY_IN_MILLIS;
/** /**
* Get age of given {@link java.util.Date} compared to now formatted in the
* same relative format as returned by {@code git log --relative-date}
*
* @param when * @param when
* {@link Date} to format * {@link java.util.Date} to format
* @return age of given {@link Date} compared to now formatted in the same * @return age of given {@link java.util.Date} compared to now formatted in
* relative format as returned by {@code git log --relative-date} * the same relative format as returned by
* {@code git log --relative-date}
*/ */
@SuppressWarnings("boxing") @SuppressWarnings("boxing")
public static String format(Date when) { public static String format(Date when) {

18
org.eclipse.jgit/src/org/eclipse/jgit/util/StringUtils.java
View File

@ -48,7 +48,9 @@
import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.internal.JGitText;
/** Miscellaneous string comparison utility methods. */ /**
* Miscellaneous string comparison utility methods.
*/
public final class StringUtils { public final class StringUtils {
private static final char[] LC; private static final char[] LC;
@ -102,10 +104,12 @@ public static String toLowerCase(final String in) {
* *
* <p> * <p>
* Capitalizes a String changing the first letter to title case as per * Capitalizes a String changing the first letter to title case as per
* {@link Character#toTitleCase(char)}. No other letters are changed. * {@link java.lang.Character#toTitleCase(char)}. No other letters are
* changed.
* </p> * </p>
* *
* A <code>null</code> input String returns <code>null</code>.</p> * A <code>null</code> input String returns <code>null</code>.
* </p>
* *
* @param str * @param str
* the String to capitalize, may be null * the String to capitalize, may be null
@ -156,9 +160,8 @@ public static boolean equalsIgnoreCase(final String a, final String b) {
* first string to compare. * first string to compare.
* @param b * @param b
* second string to compare. * second string to compare.
* @return negative, zero or positive if a sorts before, is equal to, or
* sorts after b.
* @since 2.0 * @since 2.0
* @return an int.
*/ */
public static int compareIgnoreCase(String a, String b) { public static int compareIgnoreCase(String a, String b) {
for (int i = 0; i < a.length() && i < b.length(); i++) { for (int i = 0; i < a.length() && i < b.length(); i++) {
@ -179,9 +182,8 @@ public static int compareIgnoreCase(String a, String b) {
* first string to compare. * first string to compare.
* @param b * @param b
* second string to compare. * second string to compare.
* @return negative, zero or positive if a sorts before, is equal to, or
* sorts after b.
* @since 2.0 * @since 2.0
* @return an int.
*/ */
public static int compareWithCase(String a, String b) { public static int compareWithCase(String a, String b) {
for (int i = 0; i < a.length() && i < b.length(); i++) { for (int i = 0; i < a.length() && i < b.length(); i++) {
@ -199,7 +201,7 @@ public static int compareWithCase(String a, String b) {
* @param stringValue * @param stringValue
* the string to parse. * the string to parse.
* @return the boolean interpretation of {@code value}. * @return the boolean interpretation of {@code value}.
* @throws IllegalArgumentException * @throws java.lang.IllegalArgumentException
* if {@code value} is not recognized as one of the standard * if {@code value} is not recognized as one of the standard
* boolean names. * boolean names.
*/ */

53
org.eclipse.jgit/src/org/eclipse/jgit/util/SystemReader.java
View File

@ -151,12 +151,18 @@ public int getTimezone(long when) {
private static SystemReader INSTANCE = DEFAULT; private static SystemReader INSTANCE = DEFAULT;
/** @return the live instance to read system properties. */ /**
* Get time since epoch, with up to millisecond resolution.
*
* @return time since epoch, with up to millisecond resolution.
*/
public static SystemReader getInstance() { public static SystemReader getInstance() {
return INSTANCE; return INSTANCE;
} }
/** /**
* Set the new instance to use when accessing properties.
*
* @param newReader * @param newReader
* the new instance to use when accessing properties, or null for * the new instance to use when accessing properties, or null for
* the default instance. * the default instance.
@ -201,18 +207,26 @@ protected final void setPlatformChecker() {
public abstract String getHostname(); public abstract String getHostname();
/** /**
* @param variable system variable to read * Get value of the system variable
*
* @param variable
* system variable to read
* @return value of the system variable * @return value of the system variable
*/ */
public abstract String getenv(String variable); public abstract String getenv(String variable);
/** /**
* @param key of the system property to read * Get value of the system property
*
* @param key
* of the system property to read
* @return value of the system property * @return value of the system property
*/ */
public abstract String getProperty(String key); public abstract String getProperty(String key);
/** /**
* Open the git configuration found in the user home
*
* @param parent * @param parent
* a config with values not found directly in the returned config * a config with values not found directly in the returned config
* @param fs * @param fs
@ -223,6 +237,8 @@ protected final void setPlatformChecker() {
public abstract FileBasedConfig openUserConfig(Config parent, FS fs); public abstract FileBasedConfig openUserConfig(Config parent, FS fs);
/** /**
* Open the gitonfig configuration found in the system-wide "etc" directory
*
* @param parent * @param parent
* a config with values not found directly in the returned * a config with values not found directly in the returned
* config. Null is a reasonable value here. * config. Null is a reasonable value here.
@ -235,11 +251,15 @@ protected final void setPlatformChecker() {
public abstract FileBasedConfig openSystemConfig(Config parent, FS fs); public abstract FileBasedConfig openSystemConfig(Config parent, FS fs);
/** /**
* Get the current system time
*
* @return the current system time * @return the current system time
*/ */
public abstract long getCurrentTime(); public abstract long getCurrentTime();
/** /**
* Get clock instance preferred by this system.
*
* @return clock instance preferred by this system. * @return clock instance preferred by this system.
* @since 4.6 * @since 4.6
*/ */
@ -248,12 +268,17 @@ public MonotonicClock getClock() {
} }
/** /**
* @param when TODO * Get the local time zone
*
* @param when
* a system timestamp
* @return the local time zone * @return the local time zone
*/ */
public abstract int getTimezone(long when); public abstract int getTimezone(long when);
/** /**
* Get system time zone, possibly mocked for testing
*
* @return system time zone, possibly mocked for testing * @return system time zone, possibly mocked for testing
* @since 1.2 * @since 1.2
*/ */
@ -262,6 +287,8 @@ public TimeZone getTimeZone() {
} }
/** /**
* Get the locale to use
*
* @return the locale to use * @return the locale to use
* @since 1.2 * @since 1.2
*/ */
@ -274,7 +301,7 @@ public Locale getLocale() {
* *
* @param pattern * @param pattern
* the pattern as defined in * the pattern as defined in
* {@link SimpleDateFormat#SimpleDateFormat(String)} * {@link java.text.SimpleDateFormat#SimpleDateFormat(String)}
* @return the simple date format * @return the simple date format
* @since 2.0 * @since 2.0
*/ */
@ -287,7 +314,7 @@ public SimpleDateFormat getSimpleDateFormat(String pattern) {
* *
* @param pattern * @param pattern
* the pattern as defined in * the pattern as defined in
* {@link SimpleDateFormat#SimpleDateFormat(String)} * {@link java.text.SimpleDateFormat#SimpleDateFormat(String)}
* @param locale * @param locale
* locale to be used for the {@code SimpleDateFormat} * locale to be used for the {@code SimpleDateFormat}
* @return the simple date format * @return the simple date format
@ -302,10 +329,10 @@ public SimpleDateFormat getSimpleDateFormat(String pattern, Locale locale) {
* *
* @param dateStyle * @param dateStyle
* the date style as specified in * the date style as specified in
* {@link DateFormat#getDateTimeInstance(int, int)} * {@link java.text.DateFormat#getDateTimeInstance(int, int)}
* @param timeStyle * @param timeStyle
* the time style as specified in * the time style as specified in
* {@link DateFormat#getDateTimeInstance(int, int)} * {@link java.text.DateFormat#getDateTimeInstance(int, int)}
* @return the date format * @return the date format
* @since 2.0 * @since 2.0
*/ */
@ -314,7 +341,9 @@ public DateFormat getDateTimeInstance(int dateStyle, int timeStyle) {
} }
/** /**
* @return true if we are running on a Windows. * Whether we are running on Windows.
*
* @return true if we are running on Windows.
*/ */
public boolean isWindows() { public boolean isWindows() {
if (isWindows == null) { if (isWindows == null) {
@ -325,6 +354,8 @@ public boolean isWindows() {
} }
/** /**
* Whether we are running on Mac OS X
*
* @return true if we are running on Mac OS X * @return true if we are running on Mac OS X
*/ */
public boolean isMacOS() { public boolean isMacOS() {
@ -351,7 +382,7 @@ public String run() {
* Scans a multi-directory path string such as {@code "src/main.c"}. * Scans a multi-directory path string such as {@code "src/main.c"}.
* *
* @param path path string to scan. * @param path path string to scan.
* @throws CorruptObjectException path is invalid. * @throws org.eclipse.jgit.errors.CorruptObjectException path is invalid.
* @since 3.6 * @since 3.6
*/ */
public void checkPath(String path) throws CorruptObjectException { public void checkPath(String path) throws CorruptObjectException {
@ -365,7 +396,7 @@ public void checkPath(String path) throws CorruptObjectException {
* *
* @param path * @param path
* path string to scan. * path string to scan.
* @throws CorruptObjectException * @throws org.eclipse.jgit.errors.CorruptObjectException
* path is invalid. * path is invalid.
* @since 4.2 * @since 4.2
*/ */

31
org.eclipse.jgit/src/org/eclipse/jgit/util/TemporaryBuffer.java
View File

@ -114,6 +114,7 @@ protected TemporaryBuffer(final int estimatedSize, final int limit) {
reset(); reset();
} }
/** {@inheritDoc} */
@Override @Override
public void write(final int b) throws IOException { public void write(final int b) throws IOException {
if (overflow != null) { if (overflow != null) {
@ -134,6 +135,7 @@ public void write(final int b) throws IOException {
s.buffer[s.count++] = (byte) b; s.buffer[s.count++] = (byte) b;
} }
/** {@inheritDoc} */
@Override @Override
public void write(final byte[] b, int off, int len) throws IOException { public void write(final byte[] b, int off, int len) throws IOException {
if (overflow == null) { if (overflow == null) {
@ -162,7 +164,7 @@ public void write(final byte[] b, int off, int len) throws IOException {
/** /**
* Dumps the entire buffer into the overflow stream, and flushes it. * Dumps the entire buffer into the overflow stream, and flushes it.
* *
* @throws IOException * @throws java.io.IOException
* the overflow stream cannot be started, or the buffer contents * the overflow stream cannot be started, or the buffer contents
* cannot be written to it, or it failed to flush. * cannot be written to it, or it failed to flush.
*/ */
@ -177,7 +179,7 @@ protected void doFlush() throws IOException {
* *
* @param in * @param in
* the stream to read from, until EOF is reached. * the stream to read from, until EOF is reached.
* @throws IOException * @throws java.io.IOException
* an error occurred reading from the input stream, or while * an error occurred reading from the input stream, or while
* writing to a local temporary file. * writing to a local temporary file.
*/ */
@ -227,10 +229,8 @@ private long inCoreLength() {
* The buffer is only complete after {@link #close()} has been invoked. * The buffer is only complete after {@link #close()} has been invoked.
* *
* @return the complete byte array; length matches {@link #length()}. * @return the complete byte array; length matches {@link #length()}.
* @throws IOException * @throws java.io.IOException
* an error occurred reading from a local temporary file * an error occurred reading from a local temporary file
* @throws OutOfMemoryError
* the buffer cannot fit in memory
*/ */
public byte[] toByteArray() throws IOException { public byte[] toByteArray() throws IOException {
final long len = length(); final long len = length();
@ -253,13 +253,9 @@ public byte[] toByteArray() throws IOException {
* *
* @param limit * @param limit
* the maximum number of bytes to be returned * the maximum number of bytes to be returned
*
* @return the byte array limited to {@code limit} bytes. * @return the byte array limited to {@code limit} bytes.
* @throws IOException * @throws java.io.IOException
* an error occurred reading from a local temporary file * an error occurred reading from a local temporary file
* @throws OutOfMemoryError
* the buffer cannot fit in memory
*
* @since 4.2 * @since 4.2
*/ */
public byte[] toByteArray(int limit) throws IOException { public byte[] toByteArray(int limit) throws IOException {
@ -288,7 +284,7 @@ public byte[] toByteArray(int limit) throws IOException {
* if not null progress updates are sent here. Caller should * if not null progress updates are sent here. Caller should
* initialize the task and the number of work units to <code> * initialize the task and the number of work units to <code>
* {@link #length()}/1024</code>. * {@link #length()}/1024</code>.
* @throws IOException * @throws java.io.IOException
* an error occurred reading from a temporary file on the local * an error occurred reading from a temporary file on the local
* system, or writing to the output stream. * system, or writing to the output stream.
*/ */
@ -310,14 +306,16 @@ public void writeTo(final OutputStream os, ProgressMonitor pm)
* *
* @return a stream to read from the buffer. The caller must close the * @return a stream to read from the buffer. The caller must close the
* stream when it is no longer useful. * stream when it is no longer useful.
* @throws IOException * @throws java.io.IOException
* an error occurred opening the temporary file. * an error occurred opening the temporary file.
*/ */
public InputStream openInputStream() throws IOException { public InputStream openInputStream() throws IOException {
return new BlockInputStream(); return new BlockInputStream();
} }
/** Reset this buffer for reuse, purging all buffered content. */ /**
* Reset this buffer for reuse, purging all buffered content.
*/
public void reset() { public void reset() {
if (overflow != null) { if (overflow != null) {
destroy(); destroy();
@ -334,7 +332,7 @@ public void reset() {
* *
* @return the output stream to receive the buffered content, followed by * @return the output stream to receive the buffered content, followed by
* the remaining output. * the remaining output.
* @throws IOException * @throws java.io.IOException
* the buffer cannot create the overflow stream. * the buffer cannot create the overflow stream.
*/ */
protected abstract OutputStream overflow() throws IOException; protected abstract OutputStream overflow() throws IOException;
@ -363,6 +361,7 @@ private void switchToOverflow() throws IOException {
overflow.write(last.buffer, 0, last.count); overflow.write(last.buffer, 0, last.count);
} }
/** {@inheritDoc} */
@Override @Override
public void close() throws IOException { public void close() throws IOException {
if (overflow != null) { if (overflow != null) {
@ -374,7 +373,9 @@ public void close() throws IOException {
} }
} }
/** Clear this buffer so it has no data, and cannot be used again. */ /**
* Clear this buffer so it has no data, and cannot be used again.
*/
public void destroy() { public void destroy() {
blocks = null; blocks = null;

3
org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoCRLFInputStream.java
View File

@ -91,12 +91,14 @@ public AutoCRLFInputStream(InputStream in, boolean detectBinary) {
this.detectBinary = detectBinary; this.detectBinary = detectBinary;
} }
/** {@inheritDoc} */
@Override @Override
public int read() throws IOException { public int read() throws IOException {
final int read = read(single, 0, 1); final int read = read(single, 0, 1);
return read == 1 ? single[0] & 0xff : -1; return read == 1 ? single[0] & 0xff : -1;
} }
/** {@inheritDoc} */
@Override @Override
public int read(byte[] bs, final int off, final int len) throws IOException { public int read(byte[] bs, final int off, final int len) throws IOException {
if (len == 0) if (len == 0)
@ -135,6 +137,7 @@ public int read(byte[] bs, final int off, final int len) throws IOException {
return n; return n;
} }
/** {@inheritDoc} */
@Override @Override
public void close() throws IOException { public void close() throws IOException {
in.close(); in.close();

13
org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoCRLFOutputStream.java
View File

@ -75,14 +75,18 @@ public class AutoCRLFOutputStream extends OutputStream {
private boolean isBinary; private boolean isBinary;
/** /**
* @param out * <p>Constructor for AutoCRLFOutputStream.</p>
*
* @param out a {@link java.io.OutputStream} object.
*/ */
public AutoCRLFOutputStream(OutputStream out) { public AutoCRLFOutputStream(OutputStream out) {
this(out, true); this(out, true);
} }
/** /**
* @param out * <p>Constructor for AutoCRLFOutputStream.</p>
*
* @param out a {@link java.io.OutputStream} object.
* @param detectBinary * @param detectBinary
* whether binaries should be detected * whether binaries should be detected
* @since 4.3 * @since 4.3
@ -92,12 +96,14 @@ public AutoCRLFOutputStream(OutputStream out, boolean detectBinary) {
this.detectBinary = detectBinary; this.detectBinary = detectBinary;
} }
/** {@inheritDoc} */
@Override @Override
public void write(int b) throws IOException { public void write(int b) throws IOException {
onebytebuf[0] = (byte) b; onebytebuf[0] = (byte) b;
write(onebytebuf, 0, 1); write(onebytebuf, 0, 1);
} }
/** {@inheritDoc} */
@Override @Override
public void write(byte[] b) throws IOException { public void write(byte[] b) throws IOException {
int overflow = buffer(b, 0, b.length); int overflow = buffer(b, 0, b.length);
@ -105,6 +111,7 @@ public void write(byte[] b) throws IOException {
write(b, b.length - overflow, overflow); write(b, b.length - overflow, overflow);
} }
/** {@inheritDoc} */
@Override @Override
public void write(byte[] b, final int startOff, final int startLen) public void write(byte[] b, final int startOff, final int startLen)
throws IOException { throws IOException {
@ -166,6 +173,7 @@ private void decideMode() throws IOException {
write(binbuf, 0, cachedLen); write(binbuf, 0, cachedLen);
} }
/** {@inheritDoc} */
@Override @Override
public void flush() throws IOException { public void flush() throws IOException {
if (binbufcnt <= binbuf.length) if (binbufcnt <= binbuf.length)
@ -174,6 +182,7 @@ public void flush() throws IOException {
out.flush(); out.flush();
} }
/** {@inheritDoc} */
@Override @Override
public void close() throws IOException { public void close() throws IOException {
flush(); flush();

7
org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoLFInputStream.java
View File

@ -125,12 +125,14 @@ public AutoLFInputStream(InputStream in, boolean detectBinary,
this.abortIfBinary = abortIfBinary; this.abortIfBinary = abortIfBinary;
} }
/** {@inheritDoc} */
@Override @Override
public int read() throws IOException { public int read() throws IOException {
final int read = read(single, 0, 1); final int read = read(single, 0, 1);
return read == 1 ? single[0] & 0xff : -1; return read == 1 ? single[0] & 0xff : -1;
} }
/** {@inheritDoc} */
@Override @Override
public int read(byte[] bs, final int off, final int len) public int read(byte[] bs, final int off, final int len)
throws IOException { throws IOException {
@ -171,13 +173,16 @@ public int read(byte[] bs, final int off, final int len)
} }
/** /**
* @return true if the stream has detected as a binary so far * Whether the stream has detected as a binary so far.
*
* @return true if the stream has detected as a binary so far.
* @since 3.3 * @since 3.3
*/ */
public boolean isBinary() { public boolean isBinary() {
return isBinary; return isBinary;
} }
/** {@inheritDoc} */
@Override @Override
public void close() throws IOException { public void close() throws IOException {
in.close(); in.close();

15
org.eclipse.jgit/src/org/eclipse/jgit/util/io/AutoLFOutputStream.java
View File

@ -76,14 +76,24 @@ public class AutoLFOutputStream extends OutputStream {
private boolean isBinary; private boolean isBinary;
/** /**
* <p>
* Constructor for AutoLFOutputStream.
* </p>
*
* @param out * @param out
* an {@link java.io.OutputStream} object.
*/ */
public AutoLFOutputStream(OutputStream out) { public AutoLFOutputStream(OutputStream out) {
this(out, true); this(out, true);
} }
/** /**
* <p>
* Constructor for AutoLFOutputStream.
* </p>
*
* @param out * @param out
* an {@link java.io.OutputStream} object.
* @param detectBinary * @param detectBinary
* whether binaries should be detected * whether binaries should be detected
*/ */
@ -92,12 +102,14 @@ public AutoLFOutputStream(OutputStream out, boolean detectBinary) {
this.detectBinary = detectBinary; this.detectBinary = detectBinary;
} }
/** {@inheritDoc} */
@Override @Override
public void write(int b) throws IOException { public void write(int b) throws IOException {
onebytebuf[0] = (byte) b; onebytebuf[0] = (byte) b;
write(onebytebuf, 0, 1); write(onebytebuf, 0, 1);
} }
/** {@inheritDoc} */
@Override @Override
public void write(byte[] b) throws IOException { public void write(byte[] b) throws IOException {
int overflow = buffer(b, 0, b.length); int overflow = buffer(b, 0, b.length);
@ -106,6 +118,7 @@ public void write(byte[] b) throws IOException {
} }
} }
/** {@inheritDoc} */
@Override @Override
public void write(byte[] b, final int startOff, final int startLen) public void write(byte[] b, final int startOff, final int startLen)
throws IOException { throws IOException {
@ -180,6 +193,7 @@ private void decideMode() throws IOException {
write(binbuf, 0, cachedLen); write(binbuf, 0, cachedLen);
} }
/** {@inheritDoc} */
@Override @Override
public void flush() throws IOException { public void flush() throws IOException {
if (binbufcnt <= binbuf.length) { if (binbufcnt <= binbuf.length) {
@ -188,6 +202,7 @@ public void flush() throws IOException {
out.flush(); out.flush();
} }
/** {@inheritDoc} */
@Override @Override
public void close() throws IOException { public void close() throws IOException {
flush(); flush();

14
org.eclipse.jgit/src/org/eclipse/jgit/util/io/CountingOutputStream.java
View File

@ -46,7 +46,9 @@
import java.io.IOException; import java.io.IOException;
import java.io.OutputStream; import java.io.OutputStream;
/** Counts the number of bytes written. */ /**
* Counts the number of bytes written.
*/
public class CountingOutputStream extends OutputStream { public class CountingOutputStream extends OutputStream {
private final OutputStream out; private final OutputStream out;
private long cnt; private long cnt;
@ -61,28 +63,36 @@ public CountingOutputStream(OutputStream out) {
this.out = out; this.out = out;
} }
/** @return current number of bytes written. */ /**
* Get current number of bytes written.
*
* @return current number of bytes written.
*/
public long getCount() { public long getCount() {
return cnt; return cnt;
} }
/** {@inheritDoc} */
@Override @Override
public void write(int val) throws IOException { public void write(int val) throws IOException {
out.write(val); out.write(val);
cnt++; cnt++;
} }
/** {@inheritDoc} */
@Override @Override
public void write(byte[] buf, int off, int len) throws IOException { public void write(byte[] buf, int off, int len) throws IOException {
out.write(buf, off, len); out.write(buf, off, len);
cnt += len; cnt += len;
} }
/** {@inheritDoc} */
@Override @Override
public void flush() throws IOException { public void flush() throws IOException {
out.flush(); out.flush();
} }
/** {@inheritDoc} */
@Override @Override
public void close() throws IOException { public void close() throws IOException {
out.close(); out.close();

5
org.eclipse.jgit/src/org/eclipse/jgit/util/io/DisabledOutputStream.java
View File

@ -48,7 +48,9 @@
import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.internal.JGitText;
/** An OutputStream which always throws IllegalStateExeption during write. */ /**
* An OutputStream which always throws IllegalStateExeption during write.
*/
public final class DisabledOutputStream extends OutputStream { public final class DisabledOutputStream extends OutputStream {
/** The canonical instance which always throws IllegalStateException. */ /** The canonical instance which always throws IllegalStateException. */
public static final DisabledOutputStream INSTANCE = new DisabledOutputStream(); public static final DisabledOutputStream INSTANCE = new DisabledOutputStream();
@ -58,6 +60,7 @@ private DisabledOutputStream() {
// more than one instance from being created. // more than one instance from being created.
} }
/** {@inheritDoc} */
@Override @Override
public void write(int b) throws IOException { public void write(int b) throws IOException {
// We shouldn't be writing output at this stage, there // We shouldn't be writing output at this stage, there

2
org.eclipse.jgit/src/org/eclipse/jgit/util/io/EolCanonicalizingInputStream.java
View File

@ -52,7 +52,7 @@
* Optionally, a binary check on the first 8000 bytes is performed and in case * Optionally, a binary check on the first 8000 bytes is performed and in case
* of binary files, canonicalization is turned off (for the complete file). * of binary files, canonicalization is turned off (for the complete file).
* *
* @deprecated use {@link AutoLFInputStream} instead * @deprecated use {@link org.eclipse.jgit.util.io.AutoLFInputStream} instead
*/ */
@Deprecated @Deprecated
public class EolCanonicalizingInputStream extends AutoLFInputStream { public class EolCanonicalizingInputStream extends AutoLFInputStream {

36
org.eclipse.jgit/src/org/eclipse/jgit/util/io/EolStreamTypeUtil.java
View File

@ -46,14 +46,13 @@
import java.io.OutputStream; import java.io.OutputStream;
import org.eclipse.jgit.attributes.Attributes; import org.eclipse.jgit.attributes.Attributes;
import org.eclipse.jgit.lib.Config;
import org.eclipse.jgit.lib.CoreConfig.EolStreamType; import org.eclipse.jgit.lib.CoreConfig.EolStreamType;
import org.eclipse.jgit.treewalk.TreeWalk.OperationType; import org.eclipse.jgit.treewalk.TreeWalk.OperationType;
import org.eclipse.jgit.treewalk.WorkingTreeOptions; import org.eclipse.jgit.treewalk.WorkingTreeOptions;
/** /**
* Utility used to create input and output stream wrappers for * Utility used to create input and output stream wrappers for
* {@link EolStreamType} * {@link org.eclipse.jgit.lib.CoreConfig.EolStreamType}
* *
* @since 4.3 * @since 4.3
*/ */
@ -73,16 +72,21 @@ private EolStreamTypeUtil() {
* <li>working tree .gitattributes</li> * <li>working tree .gitattributes</li>
* *
* @param op * @param op
* is the {@link OperationType} of the current traversal * is the
* {@link org.eclipse.jgit.treewalk.TreeWalk.OperationType} of
* the current traversal
* @param options * @param options
* are the {@link Config} options with key * are the {@link org.eclipse.jgit.lib.Config} options with key
* {@link WorkingTreeOptions#KEY} * {@link org.eclipse.jgit.treewalk.WorkingTreeOptions#KEY}
* @param attrs * @param attrs
* are the {@link Attributes} of the file for which the * are the {@link org.eclipse.jgit.attributes.Attributes} of the
* {@link EolStreamType} is to be detected * file for which the
* * {@link org.eclipse.jgit.lib.CoreConfig.EolStreamType} is to be
* @return the stream conversion {@link EolStreamType} to be performed for * detected
* the selected {@link OperationType} * @return the stream conversion
* {@link org.eclipse.jgit.lib.CoreConfig.EolStreamType} to be
* performed for the selected
* {@link org.eclipse.jgit.treewalk.TreeWalk.OperationType}
*/ */
public static EolStreamType detectStreamType(OperationType op, public static EolStreamType detectStreamType(OperationType op,
WorkingTreeOptions options, Attributes attrs) { WorkingTreeOptions options, Attributes attrs) {
@ -97,11 +101,15 @@ public static EolStreamType detectStreamType(OperationType op,
} }
/** /**
* Wrap the input stream depending on
* {@link org.eclipse.jgit.lib.CoreConfig.EolStreamType}
*
* @param in * @param in
* original stream * original stream
* @param conversion * @param conversion
* to be performed * to be performed
* @return the converted stream depending on {@link EolStreamType} * @return the converted stream depending on
* {@link org.eclipse.jgit.lib.CoreConfig.EolStreamType}
*/ */
public static InputStream wrapInputStream(InputStream in, public static InputStream wrapInputStream(InputStream in,
EolStreamType conversion) { EolStreamType conversion) {
@ -120,11 +128,15 @@ public static InputStream wrapInputStream(InputStream in,
} }
/** /**
* Wrap the output stream depending on
* {@link org.eclipse.jgit.lib.CoreConfig.EolStreamType}
*
* @param out * @param out
* original stream * original stream
* @param conversion * @param conversion
* to be performed * to be performed
* @return the converted stream depending on {@link EolStreamType} * @return the converted stream depending on
* {@link org.eclipse.jgit.lib.CoreConfig.EolStreamType}
*/ */
public static OutputStream wrapOutputStream(OutputStream out, public static OutputStream wrapOutputStream(OutputStream out,
EolStreamType conversion) { EolStreamType conversion) {

12
org.eclipse.jgit/src/org/eclipse/jgit/util/io/InterruptTimer.java
View File

@ -88,7 +88,9 @@ public final class InterruptTimer {
final AutoKiller autoKiller; final AutoKiller autoKiller;
/** Create a new timer with a default thread name. */ /**
* Create a new timer with a default thread name.
*/
public InterruptTimer() { public InterruptTimer() {
this("JGit-InterruptTimer"); //$NON-NLS-1$ this("JGit-InterruptTimer"); //$NON-NLS-1$
} }
@ -123,12 +125,16 @@ public void begin(final int timeout) {
state.begin(timeout); state.begin(timeout);
} }
/** Disable the interrupt timer, as the operation is complete. */ /**
* Disable the interrupt timer, as the operation is complete.
*/
public void end() { public void end() {
state.end(); state.end();
} }
/** Shutdown the timer thread, and wait for it to terminate. */ /**
* Shutdown the timer thread, and wait for it to terminate.
*/
public void terminate() { public void terminate() {
state.terminate(); state.terminate();
try { try {

4
org.eclipse.jgit/src/org/eclipse/jgit/util/io/IsolatedOutputStream.java
View File

@ -91,11 +91,13 @@ public IsolatedOutputStream(OutputStream out) {
new ArrayBlockingQueue<Runnable>(1), new NamedThreadFactory()); new ArrayBlockingQueue<Runnable>(1), new NamedThreadFactory());
} }
/** {@inheritDoc} */
@Override @Override
public void write(int ch) throws IOException { public void write(int ch) throws IOException {
write(new byte[] { (byte) ch }, 0, 1); write(new byte[] { (byte) ch }, 0, 1);
} }
/** {@inheritDoc} */
@Override @Override
public void write(final byte[] buf, final int pos, final int cnt) public void write(final byte[] buf, final int pos, final int cnt)
throws IOException { throws IOException {
@ -109,6 +111,7 @@ public Void call() throws IOException {
}); });
} }
/** {@inheritDoc} */
@Override @Override
public void flush() throws IOException { public void flush() throws IOException {
checkClosed(); checkClosed();
@ -121,6 +124,7 @@ public Void call() throws IOException {
}); });
} }
/** {@inheritDoc} */
@Override @Override
public void close() throws IOException { public void close() throws IOException {
if (!copier.isShutdown()) { if (!copier.isShutdown()) {

27
org.eclipse.jgit/src/org/eclipse/jgit/util/io/LimitedInputStream.java
View File

@ -51,13 +51,13 @@
import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.internal.JGitText;
/** /**
* Wraps a {@link InputStream}, limiting the number of bytes which can be * Wraps a {@link java.io.InputStream}, limiting the number of bytes which can
* read. * be read.
* *
* This class was copied and modifed from the Google Guava 16.0. Differently from * This class was copied and modifed from the Google Guava 16.0. Differently
* the original Guava code, when a caller tries to read from this stream past * from the original Guava code, when a caller tries to read from this stream
* the given limit and the wrapped stream hasn't yet reached its EOF this class * past the given limit and the wrapped stream hasn't yet reached its EOF this
* will call the limitExceeded method instead of returning EOF. * class will call the limitExceeded method instead of returning EOF.
* *
* @since 3.3 * @since 3.3
*/ */
@ -80,18 +80,21 @@ protected LimitedInputStream(InputStream in, long limit) {
this.limit = limit; this.limit = limit;
} }
/** {@inheritDoc} */
@Override @Override
public int available() throws IOException { public int available() throws IOException {
return (int) Math.min(in.available(), left); return (int) Math.min(in.available(), left);
} }
// it's okay to mark even if mark isn't supported, as reset won't work // it's okay to mark even if mark isn't supported, as reset won't work
/** {@inheritDoc} */
@Override @Override
public synchronized void mark(int readLimit) { public synchronized void mark(int readLimit) {
in.mark(readLimit); in.mark(readLimit);
mark = left; mark = left;
} }
/** {@inheritDoc} */
@Override @Override
public int read() throws IOException { public int read() throws IOException {
if (left == 0) { if (left == 0) {
@ -107,6 +110,7 @@ public int read() throws IOException {
return result; return result;
} }
/** {@inheritDoc} */
@Override @Override
public int read(byte[] b, int off, int len) throws IOException { public int read(byte[] b, int off, int len) throws IOException {
if (left == 0) { if (left == 0) {
@ -123,6 +127,7 @@ public int read(byte[] b, int off, int len) throws IOException {
return result; return result;
} }
/** {@inheritDoc} */
@Override @Override
public synchronized void reset() throws IOException { public synchronized void reset() throws IOException {
if (!in.markSupported()) if (!in.markSupported())
@ -135,6 +140,7 @@ public synchronized void reset() throws IOException {
left = mark; left = mark;
} }
/** {@inheritDoc} */
@Override @Override
public long skip(long n) throws IOException { public long skip(long n) throws IOException {
n = Math.min(n, left); n = Math.min(n, left);
@ -147,10 +153,11 @@ public long skip(long n) throws IOException {
* Called when trying to read past the given {@link #limit} and the wrapped * Called when trying to read past the given {@link #limit} and the wrapped
* InputStream {@link #in} hasn't yet reached its EOF * InputStream {@link #in} hasn't yet reached its EOF
* *
* @throws IOException * @throws java.io.IOException
* subclasses can throw an IOException when the limit is exceeded. * subclasses can throw an {@link java.io.IOException} when the
* The throws IOException will be forwarded back to the caller of * limit is exceeded. The throws java.io.IOException will be
* the read method which read the stream past the limit. * forwarded back to the caller of the read method which read
* the stream past the limit.
*/ */
protected abstract void limitExceeded() throws IOException; protected abstract void limitExceeded() throws IOException;
} }

16
org.eclipse.jgit/src/org/eclipse/jgit/util/io/MessageWriter.java
View File

@ -66,20 +66,24 @@
* {@link #toString()} returns all written data, after converting it to a String * {@link #toString()} returns all written data, after converting it to a String
* under the assumption of UTF-8 encoding. * under the assumption of UTF-8 encoding.
* <p> * <p>
* Internally {@link RawParseUtils#decode(byte[])} is used by {@code toString()} * Internally {@link org.eclipse.jgit.util.RawParseUtils#decode(byte[])} is used
* tries to work out a reasonably correct character set for the raw data. * by {@code toString()} tries to work out a reasonably correct character set
* for the raw data.
*/ */
public class MessageWriter extends Writer { public class MessageWriter extends Writer {
private final ByteArrayOutputStream buf; private final ByteArrayOutputStream buf;
private final OutputStreamWriter enc; private final OutputStreamWriter enc;
/** Create an empty writer. */ /**
* Create an empty writer.
*/
public MessageWriter() { public MessageWriter() {
buf = new ByteArrayOutputStream(); buf = new ByteArrayOutputStream();
enc = new OutputStreamWriter(getRawStream(), Constants.CHARSET); enc = new OutputStreamWriter(getRawStream(), Constants.CHARSET);
} }
/** {@inheritDoc} */
@Override @Override
public void write(char[] cbuf, int off, int len) throws IOException { public void write(char[] cbuf, int off, int len) throws IOException {
synchronized (buf) { synchronized (buf) {
@ -89,6 +93,9 @@ public void write(char[] cbuf, int off, int len) throws IOException {
} }
/** /**
* Get the underlying byte stream that character writes to this writer drop
* into.
*
* @return the underlying byte stream that character writes to this writer * @return the underlying byte stream that character writes to this writer
* drop into. Writes to this stream should should be in UTF-8. * drop into. Writes to this stream should should be in UTF-8.
*/ */
@ -96,17 +103,20 @@ public OutputStream getRawStream() {
return buf; return buf;
} }
/** {@inheritDoc} */
@Override @Override
public void close() throws IOException { public void close() throws IOException {
// Do nothing, we are buffered with no resources. // Do nothing, we are buffered with no resources.
} }
/** {@inheritDoc} */
@Override @Override
public void flush() throws IOException { public void flush() throws IOException {
// Do nothing, we are buffered with no resources. // Do nothing, we are buffered with no resources.
} }
/** @return string version of all buffered data. */ /** @return string version of all buffered data. */
/** {@inheritDoc} */
@Override @Override
public String toString() { public String toString() {
return RawParseUtils.decode(buf.toByteArray()); return RawParseUtils.decode(buf.toByteArray());

3
org.eclipse.jgit/src/org/eclipse/jgit/util/io/NullOutputStream.java
View File

@ -57,16 +57,19 @@ private NullOutputStream() {
// more than one instance from being created. // more than one instance from being created.
} }
/** {@inheritDoc} */
@Override @Override
public void write(int b) { public void write(int b) {
// Discard. // Discard.
} }
/** {@inheritDoc} */
@Override @Override
public void write(byte[] buf) { public void write(byte[] buf) {
// Discard. // Discard.
} }
/** {@inheritDoc} */
@Override @Override
public void write(byte[] buf, int pos, int cnt) { public void write(byte[] buf, int pos, int cnt) {
// Discard. // Discard.

6
org.eclipse.jgit/src/org/eclipse/jgit/util/io/SafeBufferedOutputStream.java
View File

@ -46,11 +46,15 @@
import java.io.OutputStream; import java.io.OutputStream;
/** /**
* <p>SafeBufferedOutputStream class.</p>
*
* @deprecated use BufferedOutputStream in Java 8 and later. * @deprecated use BufferedOutputStream in Java 8 and later.
*/ */
@Deprecated @Deprecated
public class SafeBufferedOutputStream extends BufferedOutputStream { public class SafeBufferedOutputStream extends BufferedOutputStream {
/** /**
* <p>Constructor for SafeBufferedOutputStream.</p>
*
* @see BufferedOutputStream#BufferedOutputStream(OutputStream) * @see BufferedOutputStream#BufferedOutputStream(OutputStream)
* @param out * @param out
* underlying output stream * underlying output stream
@ -60,6 +64,8 @@ public SafeBufferedOutputStream(OutputStream out) {
} }
/** /**
* <p>Constructor for SafeBufferedOutputStream.</p>
*
* @see BufferedOutputStream#BufferedOutputStream(OutputStream, int) * @see BufferedOutputStream#BufferedOutputStream(OutputStream, int)
* @param out * @param out
* underlying output stream * underlying output stream

7
org.eclipse.jgit/src/org/eclipse/jgit/util/io/StreamCopyThread.java
View File

@ -48,7 +48,9 @@
import java.io.InterruptedIOException; import java.io.InterruptedIOException;
import java.io.OutputStream; import java.io.OutputStream;
/** Thread to copy from an input stream to an output stream. */ /**
* Thread to copy from an input stream to an output stream.
*/
public class StreamCopyThread extends Thread { public class StreamCopyThread extends Thread {
private static final int BUFFER_SIZE = 1024; private static final int BUFFER_SIZE = 1024;
@ -98,7 +100,7 @@ public void flush() {
* This method signals to the copy thread that it should stop as soon as * This method signals to the copy thread that it should stop as soon as
* there is no more IO occurring. * there is no more IO occurring.
* *
* @throws InterruptedException * @throws java.lang.InterruptedException
* the calling thread was interrupted. * the calling thread was interrupted.
*/ */
public void halt() throws InterruptedException { public void halt() throws InterruptedException {
@ -112,6 +114,7 @@ public void halt() throws InterruptedException {
} }
} }
/** {@inheritDoc} */
@Override @Override
public void run() { public void run() {
try { try {

16
org.eclipse.jgit/src/org/eclipse/jgit/util/io/TeeInputStream.java
View File

@ -47,15 +47,13 @@
import java.io.InputStream; import java.io.InputStream;
import java.io.OutputStream; import java.io.OutputStream;
import org.eclipse.jgit.util.TemporaryBuffer;
/** /**
* Input stream that copies data read to another output stream. * Input stream that copies data read to another output stream.
* *
* This stream is primarily useful with a {@link TemporaryBuffer}, where any * This stream is primarily useful with a
* data read or skipped by the caller is also duplicated into the temporary * {@link org.eclipse.jgit.util.TemporaryBuffer}, where any data read or skipped
* buffer. Later the temporary buffer can then be used instead of the original * by the caller is also duplicated into the temporary buffer. Later the
* source stream. * temporary buffer can then be used instead of the original source stream.
* *
* During close this stream copies any remaining data from the source stream * During close this stream copies any remaining data from the source stream
* into the destination stream. * into the destination stream.
@ -74,13 +72,14 @@ public class TeeInputStream extends InputStream {
* source stream to consume. * source stream to consume.
* @param dst * @param dst
* destination to copy the source to as it is consumed. Typically * destination to copy the source to as it is consumed. Typically
* this is a {@link TemporaryBuffer}. * this is a {@link org.eclipse.jgit.util.TemporaryBuffer}.
*/ */
public TeeInputStream(InputStream src, OutputStream dst) { public TeeInputStream(InputStream src, OutputStream dst) {
this.src = src; this.src = src;
this.dst = dst; this.dst = dst;
} }
/** {@inheritDoc} */
@Override @Override
public int read() throws IOException { public int read() throws IOException {
byte[] b = skipBuffer(); byte[] b = skipBuffer();
@ -88,6 +87,7 @@ public int read() throws IOException {
return n == 1 ? b[0] & 0xff : -1; return n == 1 ? b[0] & 0xff : -1;
} }
/** {@inheritDoc} */
@Override @Override
public long skip(final long count) throws IOException { public long skip(final long count) throws IOException {
long skipped = 0; long skipped = 0;
@ -104,6 +104,7 @@ public long skip(final long count) throws IOException {
return skipped; return skipped;
} }
/** {@inheritDoc} */
@Override @Override
public int read(byte[] b, int off, int len) throws IOException { public int read(byte[] b, int off, int len) throws IOException {
if (len == 0) if (len == 0)
@ -115,6 +116,7 @@ public int read(byte[] b, int off, int len) throws IOException {
return n; return n;
} }
/** {@inheritDoc} */
@Override @Override
public void close() throws IOException { public void close() throws IOException {
byte[] b = skipBuffer(); byte[] b = skipBuffer();

35
org.eclipse.jgit/src/org/eclipse/jgit/util/io/ThrowingPrintWriter.java
View File

@ -64,7 +64,7 @@ public class ThrowingPrintWriter extends Writer {
* Construct a JGitPrintWriter * Construct a JGitPrintWriter
* *
* @param out * @param out
* the underlying {@link Writer} * the underlying {@link java.io.Writer}
*/ */
public ThrowingPrintWriter(Writer out) { public ThrowingPrintWriter(Writer out) {
this.out = out; this.out = out;
@ -76,16 +76,19 @@ public String run() {
}); });
} }
/** {@inheritDoc} */
@Override @Override
public void write(char[] cbuf, int off, int len) throws IOException { public void write(char[] cbuf, int off, int len) throws IOException {
out.write(cbuf, off, len); out.write(cbuf, off, len);
} }
/** {@inheritDoc} */
@Override @Override
public void flush() throws IOException { public void flush() throws IOException {
out.flush(); out.flush();
} }
/** {@inheritDoc} */
@Override @Override
public void close() throws IOException { public void close() throws IOException {
out.close(); out.close();
@ -94,8 +97,8 @@ public void close() throws IOException {
/** /**
* Print a string and terminate with a line feed. * Print a string and terminate with a line feed.
* *
* @param s * @param s a {@link java.lang.String} object.
* @throws IOException * @throws java.io.IOException
*/ */
public void println(String s) throws IOException { public void println(String s) throws IOException {
print(s + LF); print(s + LF);
@ -104,7 +107,7 @@ public void println(String s) throws IOException {
/** /**
* Print a platform dependent new line * Print a platform dependent new line
* *
* @throws IOException * @throws java.io.IOException
*/ */
public void println() throws IOException { public void println() throws IOException {
print(LF); print(LF);
@ -113,8 +116,8 @@ public void println() throws IOException {
/** /**
* Print a char * Print a char
* *
* @param value * @param value a char.
* @throws IOException * @throws java.io.IOException
*/ */
public void print(char value) throws IOException { public void print(char value) throws IOException {
print(String.valueOf(value)); print(String.valueOf(value));
@ -124,7 +127,8 @@ public void print(char value) throws IOException {
* Print an int as string * Print an int as string
* *
* @param value * @param value
* @throws IOException * an int.
* @throws java.io.IOException
*/ */
public void print(int value) throws IOException { public void print(int value) throws IOException {
print(String.valueOf(value)); print(String.valueOf(value));
@ -133,8 +137,8 @@ public void print(int value) throws IOException {
/** /**
* Print a long as string * Print a long as string
* *
* @param value * @param value a long.
* @throws IOException * @throws java.io.IOException
*/ */
public void print(long value) throws IOException { public void print(long value) throws IOException {
print(String.valueOf(value)); print(String.valueOf(value));
@ -143,8 +147,8 @@ public void print(long value) throws IOException {
/** /**
* Print a short as string * Print a short as string
* *
* @param value * @param value a short.
* @throws IOException * @throws java.io.IOException
*/ */
public void print(short value) throws IOException { public void print(short value) throws IOException {
print(String.valueOf(value)); print(String.valueOf(value));
@ -152,11 +156,13 @@ public void print(short value) throws IOException {
/** /**
* Print a formatted message according to * Print a formatted message according to
* {@link String#format(String, Object...)}. * {@link java.lang.String#format(String, Object...)}.
* *
* @param fmt * @param fmt
* a {@link java.lang.String} object.
* @param args * @param args
* @throws IOException * objects.
* @throws java.io.IOException
*/ */
public void format(String fmt, Object... args) throws IOException { public void format(String fmt, Object... args) throws IOException {
print(String.format(fmt, args)); print(String.format(fmt, args));
@ -166,7 +172,8 @@ public void format(String fmt, Object... args) throws IOException {
* Print an object's toString representations * Print an object's toString representations
* *
* @param any * @param any
* @throws IOException * an object.
* @throws java.io.IOException
*/ */
public void print(Object any) throws IOException { public void print(Object any) throws IOException {
out.write(String.valueOf(any)); out.write(String.valueOf(any));

16
org.eclipse.jgit/src/org/eclipse/jgit/util/io/TimeoutInputStream.java
View File

@ -51,7 +51,9 @@
import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.internal.JGitText;
/** InputStream with a configurable timeout. */ /**
* InputStream with a configurable timeout.
*/
public class TimeoutInputStream extends FilterInputStream { public class TimeoutInputStream extends FilterInputStream {
private final InterruptTimer myTimer; private final InterruptTimer myTimer;
@ -72,12 +74,18 @@ public TimeoutInputStream(final InputStream src,
myTimer = timer; myTimer = timer;
} }
/** @return number of milliseconds before aborting a read. */ /**
* Get number of milliseconds before aborting a read.
*
* @return number of milliseconds before aborting a read.
*/
public int getTimeout() { public int getTimeout() {
return timeout; return timeout;
} }
/** /**
* Set number of milliseconds before aborting a read.
*
* @param millis * @param millis
* number of milliseconds before aborting a read. Must be &gt; 0. * number of milliseconds before aborting a read. Must be &gt; 0.
*/ */
@ -88,6 +96,7 @@ public void setTimeout(final int millis) {
timeout = millis; timeout = millis;
} }
/** {@inheritDoc} */
@Override @Override
public int read() throws IOException { public int read() throws IOException {
try { try {
@ -100,11 +109,13 @@ public int read() throws IOException {
} }
} }
/** {@inheritDoc} */
@Override @Override
public int read(byte[] buf) throws IOException { public int read(byte[] buf) throws IOException {
return read(buf, 0, buf.length); return read(buf, 0, buf.length);
} }
/** {@inheritDoc} */
@Override @Override
public int read(byte[] buf, int off, int cnt) throws IOException { public int read(byte[] buf, int off, int cnt) throws IOException {
try { try {
@ -117,6 +128,7 @@ public int read(byte[] buf, int off, int cnt) throws IOException {
} }
} }
/** {@inheritDoc} */
@Override @Override
public long skip(long cnt) throws IOException { public long skip(long cnt) throws IOException {
try { try {

20
org.eclipse.jgit/src/org/eclipse/jgit/util/io/TimeoutOutputStream.java
View File

@ -50,7 +50,9 @@
import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.internal.JGitText;
/** OutputStream with a configurable timeout. */ /**
* OutputStream with a configurable timeout.
*/
public class TimeoutOutputStream extends OutputStream { public class TimeoutOutputStream extends OutputStream {
private final OutputStream dst; private final OutputStream dst;
@ -73,14 +75,21 @@ public TimeoutOutputStream(final OutputStream destination,
myTimer = timer; myTimer = timer;
} }
/** @return number of milliseconds before aborting a write. */ /**
* Get number of milliseconds before aborting a write.
*
* @return number of milliseconds before aborting a write.
*/
public int getTimeout() { public int getTimeout() {
return timeout; return timeout;
} }
/** /**
* Set number of milliseconds before aborting a write.
*
* @param millis * @param millis
* number of milliseconds before aborting a write. Must be &gt; 0. * number of milliseconds before aborting a write. Must be &gt;
* 0.
*/ */
public void setTimeout(final int millis) { public void setTimeout(final int millis) {
if (millis < 0) if (millis < 0)
@ -89,6 +98,7 @@ public void setTimeout(final int millis) {
timeout = millis; timeout = millis;
} }
/** {@inheritDoc} */
@Override @Override
public void write(int b) throws IOException { public void write(int b) throws IOException {
try { try {
@ -101,11 +111,13 @@ public void write(int b) throws IOException {
} }
} }
/** {@inheritDoc} */
@Override @Override
public void write(byte[] buf) throws IOException { public void write(byte[] buf) throws IOException {
write(buf, 0, buf.length); write(buf, 0, buf.length);
} }
/** {@inheritDoc} */
@Override @Override
public void write(byte[] buf, int off, int len) throws IOException { public void write(byte[] buf, int off, int len) throws IOException {
try { try {
@ -118,6 +130,7 @@ public void write(byte[] buf, int off, int len) throws IOException {
} }
} }
/** {@inheritDoc} */
@Override @Override
public void flush() throws IOException { public void flush() throws IOException {
try { try {
@ -130,6 +143,7 @@ public void flush() throws IOException {
} }
} }
/** {@inheritDoc} */
@Override @Override
public void close() throws IOException { public void close() throws IOException {
try { try {

11
org.eclipse.jgit/src/org/eclipse/jgit/util/io/UnionInputStream.java
View File

@ -58,7 +58,7 @@
* Currently this stream does not support the mark/reset APIs. If mark and later * Currently this stream does not support the mark/reset APIs. If mark and later
* reset functionality is needed the caller should wrap this stream with a * reset functionality is needed the caller should wrap this stream with a
* {@link java.io.BufferedInputStream}. * {@link java.io.BufferedInputStream}.
* */ */
public class UnionInputStream extends InputStream { public class UnionInputStream extends InputStream {
private static final InputStream EOF = new InputStream() { private static final InputStream EOF = new InputStream() {
@Override @Override
@ -69,7 +69,9 @@ public int read() throws IOException {
private final LinkedList<InputStream> streams = new LinkedList<>(); private final LinkedList<InputStream> streams = new LinkedList<>();
/** Create an empty InputStream that is currently at EOF state. */ /**
* Create an empty InputStream that is currently at EOF state.
*/
public UnionInputStream() { public UnionInputStream() {
// Do nothing. // Do nothing.
} }
@ -122,6 +124,7 @@ public boolean isEmpty() {
return streams.isEmpty(); return streams.isEmpty();
} }
/** {@inheritDoc} */
@Override @Override
public int read() throws IOException { public int read() throws IOException {
for (;;) { for (;;) {
@ -136,6 +139,7 @@ else if (in == EOF)
} }
} }
/** {@inheritDoc} */
@Override @Override
public int read(byte[] b, int off, int len) throws IOException { public int read(byte[] b, int off, int len) throws IOException {
if (len == 0) if (len == 0)
@ -152,11 +156,13 @@ else if (in == EOF)
} }
} }
/** {@inheritDoc} */
@Override @Override
public int available() throws IOException { public int available() throws IOException {
return head().available(); return head().available();
} }
/** {@inheritDoc} */
@Override @Override
public long skip(final long count) throws IOException { public long skip(final long count) throws IOException {
long skipped = 0; long skipped = 0;
@ -190,6 +196,7 @@ public long skip(final long count) throws IOException {
return skipped; return skipped;
} }
/** {@inheritDoc} */
@Override @Override
public void close() throws IOException { public void close() throws IOException {
IOException err = null; IOException err = null;

19
org.eclipse.jgit/src/org/eclipse/jgit/util/sha1/SHA1.java
View File

@ -70,8 +70,8 @@
* sha1collisiondetection</a> for more information. * sha1collisiondetection</a> for more information.
* <p> * <p>
* When detectCollision is true (default), this implementation throws * When detectCollision is true (default), this implementation throws
* {@link Sha1CollisionException} from any digest method if a potential * {@link org.eclipse.jgit.util.sha1.Sha1CollisionException} from any digest
* collision was detected. * method if a potential collision was detected.
* *
* @since 4.7 * @since 4.7
*/ */
@ -85,7 +85,11 @@ public class SHA1 {
DETECT_COLLISIONS = v != null ? Boolean.parseBoolean(v) : true; DETECT_COLLISIONS = v != null ? Boolean.parseBoolean(v) : true;
} }
/** @return a new context to compute a SHA-1 hash of data. */ /**
* Create a new context to compute a SHA-1 hash of data.
*
* @return a new context to compute a SHA-1 hash of data.
*/
public static SHA1 newInstance() { public static SHA1 newInstance() {
return new SHA1(); return new SHA1();
} }
@ -121,6 +125,7 @@ private SHA1() {
* {@code -Dorg.eclipse.jgit.util.sha1.detectCollision=true}. * {@code -Dorg.eclipse.jgit.util.sha1.detectCollision=true}.
* *
* @param detect * @param detect
* a boolean.
* @return {@code this} * @return {@code this}
*/ */
public SHA1 setDetectCollision(boolean detect) { public SHA1 setDetectCollision(boolean detect) {
@ -131,7 +136,7 @@ public SHA1 setDetectCollision(boolean detect) {
/** /**
* Update the digest computation by adding a byte. * Update the digest computation by adding a byte.
* *
* @param b * @param b a byte.
*/ */
public void update(byte b) { public void update(byte b) {
int bufferLen = (int) (length & 63); int bufferLen = (int) (length & 63);
@ -503,7 +508,7 @@ private void finish() {
* Once {@code digest()} is called, this instance should be discarded. * Once {@code digest()} is called, this instance should be discarded.
* *
* @return the bytes for the resulting hash. * @return the bytes for the resulting hash.
* @throws Sha1CollisionException * @throws org.eclipse.jgit.util.sha1.Sha1CollisionException
* if a collision was detected and safeHash is false. * if a collision was detected and safeHash is false.
*/ */
public byte[] digest() throws Sha1CollisionException { public byte[] digest() throws Sha1CollisionException {
@ -524,7 +529,7 @@ public byte[] digest() throws Sha1CollisionException {
* Once {@code digest()} is called, this instance should be discarded. * Once {@code digest()} is called, this instance should be discarded.
* *
* @return the ObjectId for the resulting hash. * @return the ObjectId for the resulting hash.
* @throws Sha1CollisionException * @throws org.eclipse.jgit.util.sha1.Sha1CollisionException
* if a collision was detected and safeHash is false. * if a collision was detected and safeHash is false.
*/ */
public ObjectId toObjectId() throws Sha1CollisionException { public ObjectId toObjectId() throws Sha1CollisionException {
@ -539,7 +544,7 @@ public ObjectId toObjectId() throws Sha1CollisionException {
* *
* @param id * @param id
* destination to copy the digest to. * destination to copy the digest to.
* @throws Sha1CollisionException * @throws org.eclipse.jgit.util.sha1.Sha1CollisionException
* if a collision was detected and safeHash is false. * if a collision was detected and safeHash is false.
*/ */
public void digest(MutableObjectId id) throws Sha1CollisionException { public void digest(MutableObjectId id) throws Sha1CollisionException {

3
org.eclipse.jgit/src/org/eclipse/jgit/util/sha1/Sha1CollisionException.java
View File

@ -49,7 +49,8 @@
import org.eclipse.jgit.lib.ObjectId; import org.eclipse.jgit.lib.ObjectId;
/** /**
* Thrown by {@link SHA1} if it detects a likely hash collision. * Thrown by {@link org.eclipse.jgit.util.sha1.SHA1} if it detects a likely hash
* collision.
* *
* @since 4.7 * @since 4.7
*/ */

16
org.eclipse.jgit/src/org/eclipse/jgit/util/time/MonotonicClock.java
View File

@ -44,7 +44,6 @@
package org.eclipse.jgit.util.time; package org.eclipse.jgit.util.time;
import java.time.Duration; import java.time.Duration;
import java.util.concurrent.TimeUnit;
/** /**
* A provider of time. * A provider of time.
@ -53,7 +52,9 @@
* source, such as the local system clock. * source, such as the local system clock.
* <p> * <p>
* MonotonicClocks provide the following behavior, with the assertion always * MonotonicClocks provide the following behavior, with the assertion always
* being true if {@link ProposedTimestamp#blockUntil(Duration)} is used: * being true if
* {@link org.eclipse.jgit.util.time.ProposedTimestamp#blockUntil(Duration)} is
* used:
* *
* <pre> * <pre>
* MonotonicClock clk = ...; * MonotonicClock clk = ...;
@ -83,14 +84,11 @@ public interface MonotonicClock {
* by NTP) and return that proposal, concurrently sending network messages * by NTP) and return that proposal, concurrently sending network messages
* to closely collaborating peers in the same cluster to also ensure their * to closely collaborating peers in the same cluster to also ensure their
* system clocks are ahead of this time. In such an implementation the * system clocks are ahead of this time. In such an implementation the
* {@link ProposedTimestamp#blockUntil(Duration)} method would wait for * {@link org.eclipse.jgit.util.time.ProposedTimestamp#blockUntil(Duration)}
* replies from the peers indicating their own system clocks have moved past * method would wait for replies from the peers indicating their own system
* the proposed time. * clocks have moved past the proposed time.
* *
* @return "now". The value can be immediately accessed by * @return a {@link org.eclipse.jgit.util.time.ProposedTimestamp} object.
* {@link ProposedTimestamp#read(TimeUnit)} and friends, but the
* caller must use {@link ProposedTimestamp#blockUntil(Duration)} to
* ensure ordering holds.
*/ */
ProposedTimestamp propose(); ProposedTimestamp propose();
} }

4
org.eclipse.jgit/src/org/eclipse/jgit/util/time/MonotonicSystemClock.java
View File

@ -51,7 +51,8 @@
import java.util.concurrent.atomic.AtomicLong; import java.util.concurrent.atomic.AtomicLong;
/** /**
* A {@link MonotonicClock} based on {@code System.currentTimeMillis}. * A {@link org.eclipse.jgit.util.time.MonotonicClock} based on
* {@code System.currentTimeMillis}.
* *
* @since 4.6 * @since 4.6
*/ */
@ -69,6 +70,7 @@ private static long nowMicros() {
} }
} }
/** {@inheritDoc} */
@Override @Override
public ProposedTimestamp propose() { public ProposedTimestamp propose() {
final long u = nowMicros(); final long u = nowMicros();

51
org.eclipse.jgit/src/org/eclipse/jgit/util/time/ProposedTimestamp.java
View File

@ -55,7 +55,8 @@
import java.util.concurrent.TimeoutException; import java.util.concurrent.TimeoutException;
/** /**
* A timestamp generated by {@link MonotonicClock#propose()}. * A timestamp generated by
* {@link org.eclipse.jgit.util.time.MonotonicClock#propose()}.
* <p> * <p>
* ProposedTimestamp implements AutoCloseable so that implementations can * ProposedTimestamp implements AutoCloseable so that implementations can
* release resources associated with obtaining certainty about time elapsing. * release resources associated with obtaining certainty about time elapsing.
@ -73,10 +74,10 @@ public abstract class ProposedTimestamp implements AutoCloseable {
* timestamps to wait on. * timestamps to wait on.
* @param maxWait * @param maxWait
* how long to wait for the timestamps. * how long to wait for the timestamps.
* @throws InterruptedException * @throws java.lang.InterruptedException
* current thread was interrupted before the waiting process * current thread was interrupted before the waiting process
* completed normally. * completed normally.
* @throws TimeoutException * @throws java.util.concurrent.TimeoutException
* the timeout was reached without the proposed timestamp become * the timeout was reached without the proposed timestamp become
* certainly in the past. * certainly in the past.
*/ */
@ -121,31 +122,44 @@ public static void blockUntil(Iterable<ProposedTimestamp> times,
* <p> * <p>
* This method forces the caller to wait up to {@code timeout} for * This method forces the caller to wait up to {@code timeout} for
* {@code this} to pass sufficiently into the past such that the creating * {@code this} to pass sufficiently into the past such that the creating
* {@link MonotonicClock} instance will not create an earlier timestamp. * {@link org.eclipse.jgit.util.time.MonotonicClock} instance will not
* create an earlier timestamp.
* *
* @param maxWait * @param maxWait
* how long the implementation may block the caller. * how long the implementation may block the caller.
* @throws InterruptedException * @throws java.lang.InterruptedException
* current thread was interrupted before the waiting process * current thread was interrupted before the waiting process
* completed normally. * completed normally.
* @throws TimeoutException * @throws java.util.concurrent.TimeoutException
* the timeout was reached without the proposed timestamp * the timeout was reached without the proposed timestamp
* becoming certainly in the past. * becoming certainly in the past.
*/ */
public abstract void blockUntil(Duration maxWait) public abstract void blockUntil(Duration maxWait)
throws InterruptedException, TimeoutException; throws InterruptedException, TimeoutException;
/** @return milliseconds since epoch; {@code read(MILLISECONDS}). */ /**
* Get milliseconds since epoch; {@code read(MILLISECONDS}).
*
* @return milliseconds since epoch; {@code read(MILLISECONDS}).
*/
public long millis() { public long millis() {
return read(MILLISECONDS); return read(MILLISECONDS);
} }
/** @return microseconds since epoch; {@code read(MICROSECONDS}). */ /**
* Get microseconds since epoch; {@code read(MICROSECONDS}).
*
* @return microseconds since epoch; {@code read(MICROSECONDS}).
*/
public long micros() { public long micros() {
return read(MICROSECONDS); return read(MICROSECONDS);
} }
/** @return time since epoch, with up to microsecond resolution. */ /**
* Get time since epoch, with up to microsecond resolution.
*
* @return time since epoch, with up to microsecond resolution.
*/
public Instant instant() { public Instant instant() {
long usec = micros(); long usec = micros();
long secs = usec / 1000000L; long secs = usec / 1000000L;
@ -153,22 +167,35 @@ public Instant instant() {
return Instant.ofEpochSecond(secs, nanos); return Instant.ofEpochSecond(secs, nanos);
} }
/** @return time since epoch, with up to microsecond resolution. */ /**
* Get time since epoch, with up to microsecond resolution.
*
* @return time since epoch, with up to microsecond resolution.
*/
public Timestamp timestamp() { public Timestamp timestamp() {
return Timestamp.from(instant()); return Timestamp.from(instant());
} }
/** @return time since epoch, with up to millisecond resolution. */ /**
* Get time since epoch, with up to millisecond resolution.
*
* @return time since epoch, with up to millisecond resolution.
*/
public Date date() { public Date date() {
return new Date(millis()); return new Date(millis());
} }
/** Release resources allocated by this timestamp. */ /**
* {@inheritDoc}
* <p>
* Release resources allocated by this timestamp.
*/
@Override @Override
public void close() { public void close() {
// Do nothing by default. // Do nothing by default.
} }
/** {@inheritDoc} */
@Override @Override
public String toString() { public String toString() {
return instant().toString(); return instant().toString();