| /* |
| * Copyright (C) 2010, Google Inc. |
| * and other copyright owners as documented in the project's IP log. |
| * |
| * This program and the accompanying materials are made available |
| * under the terms of the Eclipse Distribution License v1.0 which |
| * accompanies this distribution, is reproduced below, and is |
| * available at http://www.eclipse.org/org/documents/edl-v10.php |
| * |
| * All rights reserved. |
| * |
| * Redistribution and use in source and binary forms, with or |
| * without modification, are permitted provided that the following |
| * conditions are met: |
| * |
| * - Redistributions of source code must retain the above copyright |
| * notice, this list of conditions and the following disclaimer. |
| * |
| * - Redistributions in binary form must reproduce the above |
| * copyright notice, this list of conditions and the following |
| * disclaimer in the documentation and/or other materials provided |
| * with the distribution. |
| * |
| * - Neither the name of the Eclipse Foundation, Inc. nor the |
| * names of its contributors may be used to endorse or promote |
| * products derived from this software without specific prior |
| * written permission. |
| * |
| * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND |
| * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, |
| * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
| * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR |
| * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT |
| * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; |
| * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER |
| * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, |
| * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
| * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF |
| * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| */ |
| |
| package org.eclipse.jgit.internal.storage.pack; |
| |
| import java.io.IOException; |
| import java.util.Collection; |
| import java.util.List; |
| |
| import org.eclipse.jgit.errors.MissingObjectException; |
| import org.eclipse.jgit.errors.StoredObjectRepresentationNotAvailableException; |
| import org.eclipse.jgit.lib.AnyObjectId; |
| import org.eclipse.jgit.lib.BitmapIndex.BitmapBuilder; |
| import org.eclipse.jgit.lib.ObjectReader; |
| import org.eclipse.jgit.lib.ProgressMonitor; |
| |
| /** |
| * Extension of {@link ObjectReader} that supports reusing objects in packs. |
| * <p> |
| * {@code ObjectReader} implementations may also optionally implement this |
| * interface to support {@link PackWriter} with a means of copying an object |
| * that is already in pack encoding format directly into the output stream, |
| * without incurring decompression and recompression overheads. |
| */ |
| public interface ObjectReuseAsIs { |
| /** |
| * Allocate a new {@code PackWriter} state structure for an object. |
| * <p> |
| * {@link PackWriter} allocates these objects to keep track of the |
| * per-object state, and how to load the objects efficiently into the |
| * generated stream. Implementers may subclass this type with additional |
| * object state, such as to remember what file and offset contains the |
| * object's pack encoded data. |
| * |
| * @param objectId |
| * the id of the object that will be packed. |
| * @param type |
| * the Git type of the object that will be packed. |
| * @return a new instance for this object. |
| */ |
| public ObjectToPack newObjectToPack(AnyObjectId objectId, int type); |
| |
| /** |
| * Select the best object representation for a packer. |
| * <p> |
| * Implementations should iterate through all available representations of |
| * an object, and pass them in turn to the PackWriter though |
| * {@link PackWriter#select(ObjectToPack, StoredObjectRepresentation)} so |
| * the writer can select the most suitable representation to reuse into the |
| * output stream. |
| * <p> |
| * If the implementation returns CachedPack from {@link #getCachedPacksAndUpdate(BitmapBuilder)} |
| * it must consider the representation of any object that is stored in any |
| * of the offered CachedPacks. PackWriter relies on this behavior to prune |
| * duplicate objects out of the pack stream when it selects a CachedPack and |
| * the object was also reached through the thin-pack enumeration. |
| * <p> |
| * The implementation may choose to consider multiple objects at once on |
| * concurrent threads, but must evaluate all representations of an object |
| * within the same thread. |
| * |
| * @param packer |
| * the packer that will write the object in the near future. |
| * @param monitor |
| * progress monitor, implementation should update the monitor |
| * once for each item in the iteration when selection is done. |
| * @param objects |
| * the objects that are being packed. |
| * @throws MissingObjectException |
| * there is no representation available for the object, as it is |
| * no longer in the repository. Packing will abort. |
| * @throws IOException |
| * the repository cannot be accessed. Packing will abort. |
| */ |
| public void selectObjectRepresentation(PackWriter packer, |
| ProgressMonitor monitor, Iterable<ObjectToPack> objects) |
| throws IOException, MissingObjectException; |
| |
| /** |
| * Write objects to the pack stream in roughly the order given. |
| * |
| * {@code PackWriter} invokes this method to write out one or more objects, |
| * in approximately the order specified by the iteration over the list. A |
| * simple implementation of this method would just iterate the list and |
| * output each object: |
| * |
| * <pre> |
| * for (ObjectToPack obj : list) |
| * out.writeObject(obj) |
| * </pre> |
| * |
| * However more sophisticated implementors may try to perform some (small) |
| * reordering to access objects that are stored close to each other at |
| * roughly the same time. Implementations may choose to write objects out of |
| * order, but this may increase pack file size due to using a larger header |
| * format to reach a delta base that is later in the stream. It may also |
| * reduce data locality for the reader, slowing down data access. |
| * |
| * Invoking {@link PackOutputStream#writeObject(ObjectToPack)} will cause |
| * {@link #copyObjectAsIs(PackOutputStream, ObjectToPack, boolean)} to be |
| * invoked recursively on {@code this} if the current object is scheduled |
| * for reuse. |
| * |
| * @param out |
| * the stream to write each object to. |
| * @param list |
| * the list of objects to write. Objects should be written in |
| * approximately this order. Implementors may resort the list |
| * elements in-place during writing if desired. |
| * @throws IOException |
| * the stream cannot be written to, or one or more required |
| * objects cannot be accessed from the object database. |
| */ |
| public void writeObjects(PackOutputStream out, List<ObjectToPack> list) |
| throws IOException; |
| |
| /** |
| * Output a previously selected representation. |
| * <p> |
| * {@code PackWriter} invokes this method only if a representation |
| * previously given to it by {@code selectObjectRepresentation} was chosen |
| * for reuse into the output stream. The {@code otp} argument is an instance |
| * created by this reader's own {@code newObjectToPack}, and the |
| * representation data saved within it also originated from this reader. |
| * <p> |
| * Implementors must write the object header before copying the raw data to |
| * the output stream. The typical implementation is like: |
| * |
| * <pre> |
| * MyToPack mtp = (MyToPack) otp; |
| * byte[] raw; |
| * if (validate) |
| * raw = validate(mtp); // throw SORNAE here, if at all |
| * else |
| * raw = readFast(mtp); |
| * out.writeHeader(mtp, mtp.inflatedSize); |
| * out.write(raw); |
| * </pre> |
| * |
| * @param out |
| * stream the object should be written to. |
| * @param otp |
| * the object's saved representation information. |
| * @param validate |
| * if true the representation must be validated and not be |
| * corrupt before being reused. If false, validation may be |
| * skipped as it will be performed elsewhere in the processing |
| * pipeline. |
| * @throws StoredObjectRepresentationNotAvailableException |
| * the previously selected representation is no longer |
| * available. If thrown before {@code out.writeHeader} the pack |
| * writer will try to find another representation, and write |
| * that one instead. If throw after {@code out.writeHeader}, |
| * packing will abort. |
| * @throws IOException |
| * the stream's write method threw an exception. Packing will |
| * abort. |
| */ |
| public void copyObjectAsIs(PackOutputStream out, ObjectToPack otp, |
| boolean validate) throws IOException, |
| StoredObjectRepresentationNotAvailableException; |
| |
| /** |
| * Append an entire pack's contents onto the output stream. |
| * <p> |
| * The entire pack, excluding its header and trailing footer is sent. |
| * |
| * @param out |
| * stream to append the pack onto. |
| * @param pack |
| * the cached pack to send. |
| * @throws IOException |
| * the pack cannot be read, or stream did not accept a write. |
| */ |
| public abstract void copyPackAsIs(PackOutputStream out, CachedPack pack) |
| throws IOException; |
| |
| /** |
| * Obtain the available cached packs that match the bitmap and update |
| * the bitmap by removing the items that are in the CachedPack. |
| * <p> |
| * A cached pack has known starting points and may be sent entirely as-is, |
| * with almost no effort on the sender's part. |
| * |
| * @param needBitmap |
| * the bitmap that contains all of the objects the client wants. |
| * @return the available cached packs. |
| * @throws IOException |
| * the cached packs cannot be listed from the repository. |
| * Callers may choose to ignore this and continue as-if there |
| * were no cached packs. |
| */ |
| public Collection<CachedPack> getCachedPacksAndUpdate( |
| BitmapBuilder needBitmap) throws IOException; |
| } |