Document archive formats, the archive format interface, and the parameters of the GitAPIException constructors. Noticed by eclipse. Reported-by: Dani Megert <Daniel_Megert@ch.ibm.com> Change-Id: I22b5f9d4c0358bbe867c1906feec7c279e214273tags/v3.1.0.201309270735-rc1
@@ -56,10 +56,23 @@ import org.osgi.framework.BundleContext; | |||
* leaks). | |||
*/ | |||
public class FormatActivator implements BundleActivator { | |||
/** | |||
* Registers all included archive formats by calling | |||
* {@link #start()}. This method is called by the OSGi framework | |||
* when the bundle is started. | |||
* | |||
* @param context unused | |||
*/ | |||
public void start(BundleContext context) { | |||
ArchiveFormats.registerAll(); | |||
} | |||
/** | |||
* Cleans up after {@link #start(BundleContext)} by calling | |||
* {@link #stop()}. | |||
* | |||
* @param context unused | |||
*/ | |||
public void stop(BundleContext context) { | |||
ArchiveFormats.unregisterAll(); | |||
} |
@@ -53,6 +53,9 @@ import org.eclipse.jgit.api.ArchiveCommand; | |||
import org.eclipse.jgit.lib.FileMode; | |||
import org.eclipse.jgit.lib.ObjectLoader; | |||
/** | |||
* Unix TAR format (ustar + old GNU long filename extension). | |||
*/ | |||
public class TarFormat implements ArchiveCommand.Format<ArchiveOutputStream> { | |||
public ArchiveOutputStream createArchiveOutputStream(OutputStream s) { | |||
return new TarArchiveOutputStream(s); |
@@ -51,6 +51,9 @@ import org.eclipse.jgit.api.ArchiveCommand; | |||
import org.eclipse.jgit.lib.FileMode; | |||
import org.eclipse.jgit.lib.ObjectLoader; | |||
/** | |||
* gzip-compressed tarball (tar.gz) format. | |||
*/ | |||
public class TgzFormat implements ArchiveCommand.Format<ArchiveOutputStream> { | |||
private final ArchiveCommand.Format<ArchiveOutputStream> tarFormat = new TarFormat(); | |||
@@ -51,6 +51,9 @@ import org.eclipse.jgit.api.ArchiveCommand; | |||
import org.eclipse.jgit.lib.FileMode; | |||
import org.eclipse.jgit.lib.ObjectLoader; | |||
/** | |||
* Xz-compressed tar (tar.xz) format. | |||
*/ | |||
public class TxzFormat implements ArchiveCommand.Format<ArchiveOutputStream> { | |||
private final ArchiveCommand.Format<ArchiveOutputStream> tarFormat = new TarFormat(); | |||
@@ -52,6 +52,9 @@ import org.eclipse.jgit.api.ArchiveCommand; | |||
import org.eclipse.jgit.lib.FileMode; | |||
import org.eclipse.jgit.lib.ObjectLoader; | |||
/** | |||
* PKWARE's ZIP format. | |||
*/ | |||
public class ZipFormat implements ArchiveCommand.Format<ArchiveOutputStream> { | |||
public ArchiveOutputStream createArchiveOutputStream(OutputStream s) { | |||
return new ZipArchiveOutputStream(s); |
@@ -116,9 +116,39 @@ public class ArchiveCommand extends GitCommand<OutputStream> { | |||
* } finally { | |||
* out.close(); | |||
* } | |||
* | |||
* @param <T> | |||
* type representing an archive being created. | |||
*/ | |||
public static interface Format<T extends Closeable> { | |||
/** | |||
* Start a new archive. Entries can be included in the archive using the | |||
* putEntry method, and then the archive should be closed using its | |||
* close method. | |||
* | |||
* @param s | |||
* underlying output stream to which to write the archive. | |||
* @return new archive object for use in putEntry | |||
* @throws IOException | |||
* thrown by the underlying output stream for I/O errors | |||
*/ | |||
T createArchiveOutputStream(OutputStream s) throws IOException; | |||
/** | |||
* Write an entry to an archive. | |||
* | |||
* @param out | |||
* archive object from createArchiveOutputStream | |||
* @param path | |||
* full filename relative to the root of the archive | |||
* @param mode | |||
* mode (for example FileMode.REGULAR_FILE or | |||
* FileMode.SYMLINK) | |||
* @param loader | |||
* blob object with data for this entry | |||
* @throws IOException | |||
* thrown by the underlying output stream for I/O errors | |||
*/ | |||
void putEntry(T out, String path, FileMode mode, | |||
ObjectLoader loader) throws IOException; | |||
} |
@@ -48,6 +48,11 @@ public abstract class GitAPIException extends Exception { | |||
/** | |||
* Constructs a new exception with the specified detail | |||
* message and cause. | |||
* | |||
* @param message | |||
* detail message | |||
* @param cause | |||
* cause | |||
*/ | |||
protected GitAPIException(String message, Throwable cause) { | |||
super(message, cause); | |||
@@ -56,6 +61,9 @@ public abstract class GitAPIException extends Exception { | |||
/** | |||
* Constructs a new exception with the specified detail | |||
* message and no cause. | |||
* | |||
* @param message | |||
* detail message | |||
*/ | |||
protected GitAPIException(String message) { | |||
super(message); |