org.eclipse.jgit.lib
Class PackWriter

java.lang.Object
  extended by org.eclipse.jgit.lib.PackWriter

public class PackWriter
extends java.lang.Object

PackWriter class is responsible for generating pack files from specified set of objects from repository. This implementation produce pack files in format version 2.

Source of objects may be specified in two ways:

Typical usage consists of creating instance intended for some pack, configuring options, preparing the list of objects by calling preparePack(Iterator) or preparePack(Collection, Collection), and finally producing the stream with writePack(OutputStream).

Class provide set of configurable options and ProgressMonitor support, as operations may take a long time for big repositories. Deltas searching algorithm is NOT IMPLEMENTED yet - this implementation relies only on deltas and objects reuse.

This class is not thread safe, it is intended to be used in one thread, with one instance per created pack. Subsequent calls to writePack result in undefined behavior.


Field Summary
static java.lang.String COUNTING_OBJECTS_PROGRESS
          Title of ProgressMonitor task used during counting objects to pack.
static boolean DEFAULT_DELTA_BASE_AS_OFFSET
          Default value of delta base as offset option.
static int DEFAULT_MAX_DELTA_DEPTH
          Default value of maximum delta chain depth.
static boolean DEFAULT_REUSE_DELTAS
          Default value of deltas reuse option.
static boolean DEFAULT_REUSE_OBJECTS
          Default value of objects reuse option.
static java.lang.String SEARCHING_REUSE_PROGRESS
          Title of ProgressMonitor task used during searching for objects reuse or delta reuse.
static java.lang.String WRITING_OBJECTS_PROGRESS
          Title of ProgressMonitor task used during writing out pack (objects)
 
Constructor Summary
PackWriter(Repository repo, ProgressMonitor monitor)
          Create writer for specified repository.
PackWriter(Repository repo, ProgressMonitor imonitor, ProgressMonitor wmonitor)
          Create writer for specified repository.
 
Method Summary
 void addObject(RevObject object)
          Include one object to the output file.
 ObjectId computeName()
          Computes SHA-1 of lexicographically sorted objects ids written in this pack, as used to name a pack file in repository.
 int getMaxDeltaDepth()
          Get maximum depth of delta chain set up for this writer.
 int getObjectsNumber()
          Returns objects number in a pack file that was created by this writer.
 boolean isDeltaBaseAsOffset()
          Check whether writer can store delta base as an offset (new style reducing pack size) or should store it as an object id (legacy style, compatible with old readers).
 boolean isIgnoreMissingUninteresting()
           
 boolean isReuseDeltas()
          Check whether object is configured to reuse deltas existing in repository.
 boolean isReuseObjects()
          Checks whether object is configured to reuse existing objects representation in repository.
 boolean isThin()
           
 void preparePack(java.util.Collection<? extends ObjectId> interestingObjects, java.util.Collection<? extends ObjectId> uninterestingObjects)
          Prepare the list of objects to be written to the pack stream.
 void preparePack(java.util.Iterator<RevObject> objectsSource)
          Prepare the list of objects to be written to the pack stream.
 void setDeltaBaseAsOffset(boolean deltaBaseAsOffset)
          Set writer delta base format.
 void setIgnoreMissingUninteresting(boolean ignore)
           
 void setIndexVersion(int version)
          Set the pack index file format version this instance will create.
 void setMaxDeltaDepth(int maxDeltaDepth)
          Set up maximum depth of delta chain for this writer.
 void setReuseDeltas(boolean reuseDeltas)
          Set reuse deltas configuration option for this writer.
 void setReuseObjects(boolean reuseObjects)
          Set reuse objects configuration option for this writer.
 void setThin(boolean packthin)
           
 boolean willInclude(AnyObjectId id)
          Determine if the pack file will contain the requested object.
 void writeIndex(java.io.OutputStream indexStream)
          Create an index file to match the pack file just written.
 void writePack(java.io.OutputStream packStream)
          Write the prepared pack to the supplied stream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

COUNTING_OBJECTS_PROGRESS

public static final java.lang.String COUNTING_OBJECTS_PROGRESS
Title of ProgressMonitor task used during counting objects to pack.

See Also:
preparePack(Collection, Collection), Constant Field Values

SEARCHING_REUSE_PROGRESS

public static final java.lang.String SEARCHING_REUSE_PROGRESS
Title of ProgressMonitor task used during searching for objects reuse or delta reuse.

See Also:
writePack(OutputStream), Constant Field Values

WRITING_OBJECTS_PROGRESS

public static final java.lang.String WRITING_OBJECTS_PROGRESS
Title of ProgressMonitor task used during writing out pack (objects)

See Also:
writePack(OutputStream), Constant Field Values

DEFAULT_REUSE_DELTAS

public static final boolean DEFAULT_REUSE_DELTAS
Default value of deltas reuse option.

See Also:
setReuseDeltas(boolean), Constant Field Values

DEFAULT_REUSE_OBJECTS

public static final boolean DEFAULT_REUSE_OBJECTS
Default value of objects reuse option.

See Also:
setReuseObjects(boolean), Constant Field Values

DEFAULT_DELTA_BASE_AS_OFFSET

public static final boolean DEFAULT_DELTA_BASE_AS_OFFSET
Default value of delta base as offset option.

See Also:
setDeltaBaseAsOffset(boolean), Constant Field Values

DEFAULT_MAX_DELTA_DEPTH

public static final int DEFAULT_MAX_DELTA_DEPTH
Default value of maximum delta chain depth.

See Also:
setMaxDeltaDepth(int), Constant Field Values
Constructor Detail

PackWriter

public PackWriter(Repository repo,
                  ProgressMonitor monitor)
Create writer for specified repository.

Objects for packing are specified in preparePack(Iterator) or preparePack(Collection, Collection).

Parameters:
repo - repository where objects are stored.
monitor - operations progress monitor, used within preparePack(Iterator), preparePack(Collection, Collection) , or writePack(OutputStream).

PackWriter

public PackWriter(Repository repo,
                  ProgressMonitor imonitor,
                  ProgressMonitor wmonitor)
Create writer for specified repository.

Objects for packing are specified in preparePack(Iterator) or preparePack(Collection, Collection).

Parameters:
repo - repository where objects are stored.
imonitor - operations progress monitor, used within preparePack(Iterator), preparePack(Collection, Collection)
wmonitor - operations progress monitor, used within writePack(OutputStream).
Method Detail

isReuseDeltas

public boolean isReuseDeltas()
Check whether object is configured to reuse deltas existing in repository.

Default setting: true

Returns:
true if object is configured to reuse deltas; false otherwise.

setReuseDeltas

public void setReuseDeltas(boolean reuseDeltas)
Set reuse deltas configuration option for this writer. When enabled, writer will search for delta representation of object in repository and use it if possible. Normally, only deltas with base to another object existing in set of objects to pack will be used. Exception is however thin-pack (see preparePack(Collection, Collection) and preparePack(Iterator)) where base object must exist on other side machine.

When raw delta data is directly copied from a pack file, checksum is computed to verify data.

Default setting: true

Parameters:
reuseDeltas - boolean indicating whether or not try to reuse deltas.

isReuseObjects

public boolean isReuseObjects()
Checks whether object is configured to reuse existing objects representation in repository.

Default setting: true

Returns:
true if writer is configured to reuse objects representation from pack; false otherwise.

setReuseObjects

public void setReuseObjects(boolean reuseObjects)
Set reuse objects configuration option for this writer. If enabled, writer searches for representation in a pack file. If possible, compressed data is directly copied from such a pack file. Data checksum is verified.

Default setting: true

Parameters:
reuseObjects - boolean indicating whether or not writer should reuse existing objects representation.

isDeltaBaseAsOffset

public boolean isDeltaBaseAsOffset()
Check whether writer can store delta base as an offset (new style reducing pack size) or should store it as an object id (legacy style, compatible with old readers).

Default setting: false

Returns:
true if delta base is stored as an offset; false if it is stored as an object id.

setDeltaBaseAsOffset

public void setDeltaBaseAsOffset(boolean deltaBaseAsOffset)
Set writer delta base format. Delta base can be written as an offset in a pack file (new approach reducing file size) or as an object id (legacy approach, compatible with old readers).

Default setting: false

Parameters:
deltaBaseAsOffset - boolean indicating whether delta base can be stored as an offset.

getMaxDeltaDepth

public int getMaxDeltaDepth()
Get maximum depth of delta chain set up for this writer. Generated chains are not longer than this value.

Default setting: 50

Returns:
maximum delta chain depth.

setMaxDeltaDepth

public void setMaxDeltaDepth(int maxDeltaDepth)
Set up maximum depth of delta chain for this writer. Generated chains are not longer than this value. Too low value causes low compression level, while too big makes unpacking (reading) longer.

Default setting: 50

Parameters:
maxDeltaDepth - maximum delta chain depth.

isThin

public boolean isThin()
Returns:
true if this writer is producing a thin pack.

setThin

public void setThin(boolean packthin)
Parameters:
packthin - a boolean indicating whether writer may pack objects with delta base object not within set of objects to pack, but belonging to party repository (uninteresting/boundary) as determined by set; this kind of pack is used only for transport; true - to produce thin pack, false - otherwise.

isIgnoreMissingUninteresting

public boolean isIgnoreMissingUninteresting()
Returns:
true to ignore objects that are uninteresting and also not found on local disk; false to throw a MissingObjectException out of preparePack(Collection, Collection) if an uninteresting object is not in the source repository. By default, true, permitting gracefully ignoring of uninteresting objects.

setIgnoreMissingUninteresting

public void setIgnoreMissingUninteresting(boolean ignore)
Parameters:
ignore - true if writer should ignore non existing uninteresting objects during construction set of objects to pack; false otherwise - non existing uninteresting objects may cause MissingObjectException

setIndexVersion

public void setIndexVersion(int version)
Set the pack index file format version this instance will create.

Parameters:
version - the version to write. The special version 0 designates the oldest (most compatible) format available for the objects.
See Also:
PackIndexWriter

getObjectsNumber

public int getObjectsNumber()
Returns objects number in a pack file that was created by this writer.

Returns:
number of objects in pack.

preparePack

public void preparePack(java.util.Iterator<RevObject> objectsSource)
                 throws java.io.IOException
Prepare the list of objects to be written to the pack stream.

Iterator exactly determines which objects are included in a pack and order they appear in pack (except that objects order by type is not needed at input). This order should conform general rules of ordering objects in git - by recency and path (type and delta-base first is internally secured) and responsibility for guaranteeing this order is on a caller side. Iterator must return each id of object to write exactly once.

When iterator returns object that has RevFlag.UNINTERESTING flag, this object won't be included in an output pack. Instead, it is recorded as edge-object (known to remote repository) for thin-pack. In such a case writer may pack objects with delta base object not within set of objects to pack, but belonging to party repository - those marked with RevFlag.UNINTERESTING flag. This type of pack is used only for transport.

Parameters:
objectsSource - iterator of object to store in a pack; order of objects within each type is important, ordering by type is not needed; allowed types for objects are Constants.OBJ_COMMIT, Constants.OBJ_TREE, Constants.OBJ_BLOB and Constants.OBJ_TAG; objects returned by iterator may be later reused by caller as object id and type are internally copied in each iteration; if object returned by iterator has RevFlag.UNINTERESTING flag set, it won't be included in a pack, but is considered as edge-object for thin-pack.
Throws:
java.io.IOException - when some I/O problem occur during reading objects.

preparePack

public void preparePack(java.util.Collection<? extends ObjectId> interestingObjects,
                        java.util.Collection<? extends ObjectId> uninterestingObjects)
                 throws java.io.IOException
Prepare the list of objects to be written to the pack stream.

Basing on these 2 sets, another set of objects to put in a pack file is created: this set consists of all objects reachable (ancestors) from interesting objects, except uninteresting objects and their ancestors. This method uses class ObjectWalk extensively to find out that appropriate set of output objects and their optimal order in output pack. Order is consistent with general git in-pack rules: sort by object type, recency, path and delta-base first.

Parameters:
interestingObjects - collection of objects to be marked as interesting (start points of graph traversal).
uninterestingObjects - collection of objects to be marked as uninteresting (end points of graph traversal).
Throws:
java.io.IOException - when some I/O problem occur during reading objects.

willInclude

public boolean willInclude(AnyObjectId id)
Determine if the pack file will contain the requested object.

Parameters:
id - the object to test the existence of.
Returns:
true if the object will appear in the output pack file.

computeName

public ObjectId computeName()
Computes SHA-1 of lexicographically sorted objects ids written in this pack, as used to name a pack file in repository.

Returns:
ObjectId representing SHA-1 name of a pack that was created.

writeIndex

public void writeIndex(java.io.OutputStream indexStream)
                throws java.io.IOException
Create an index file to match the pack file just written.

This method can only be invoked after preparePack(Iterator) or preparePack(Collection, Collection) has been invoked and completed successfully. Writing a corresponding index is an optional feature that not all pack users may require.

Parameters:
indexStream - output for the index data. Caller is responsible for closing this stream.
Throws:
java.io.IOException - the index data could not be written to the supplied stream.

writePack

public void writePack(java.io.OutputStream packStream)
               throws java.io.IOException
Write the prepared pack to the supplied stream.

At first, this method collects and sorts objects to pack, then deltas search is performed if set up accordingly, finally pack stream is written. ProgressMonitor tasks "Compressing objects" (only if reuseDeltas or reuseObjects is enabled) and "Writing objects" are updated during packing.

All reused objects data checksum (Adler32/CRC32) is computed and validated against existing checksum.

Parameters:
packStream - output stream of pack data. If the stream is not buffered it will be buffered by the writer. Caller is responsible for closing the stream.
Throws:
java.io.IOException - an error occurred reading a local object's data to include in the pack, or writing compressed object data to the output stream.

addObject

public void addObject(RevObject object)
               throws IncorrectObjectTypeException
Include one object to the output file.

Objects are written in the order they are added. If the same object is added twice, it may be written twice, creating a larger than necessary file.

Parameters:
object - the object to add.
Throws:
IncorrectObjectTypeException - the object is an unsupported type.