ObjectInserter.java
/*
* Copyright (C) 2007, Robin Rosenberg <robin.rosenberg@dewire.com>
* Copyright (C) 2008, Shawn O. Pearce <spearce@spearce.org>
* Copyright (C) 2009, Google Inc.
* Copyright (C) 2010, Chris Aniszczyk <caniszczyk@gmail.com> and others
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Distribution License v. 1.0 which is available at
* https://www.eclipse.org/org/documents/edl-v10.php.
*
* SPDX-License-Identifier: BSD-3-Clause
*/
package org.eclipse.jgit.lib;
import java.io.ByteArrayInputStream;
import java.io.EOFException;
import java.io.IOException;
import java.io.InputStream;
import org.eclipse.jgit.internal.JGitText;
import org.eclipse.jgit.transport.PackParser;
import org.eclipse.jgit.util.sha1.SHA1;
/**
* Inserts objects into an existing {@code ObjectDatabase}.
* <p>
* An inserter is not thread-safe. Individual threads should each obtain their
* own unique inserter instance, or must arrange for locking at a higher level
* to ensure the inserter is in use by no more than one thread at a time.
* <p>
* Objects written by an inserter may not be immediately visible for reading
* after the insert method completes. Callers must invoke either
* {@link #close()} or {@link #flush()} prior to updating references or
* otherwise making the returned ObjectIds visible to other code.
*/
public abstract class ObjectInserter implements AutoCloseable {
/** An inserter that can be used for formatting and id generation only. */
public static class Formatter extends ObjectInserter {
@Override
public ObjectId insert(int objectType, long length, InputStream in)
throws IOException {
throw new UnsupportedOperationException();
}
@Override
public PackParser newPackParser(InputStream in) throws IOException {
throw new UnsupportedOperationException();
}
@Override
public ObjectReader newReader() {
throw new UnsupportedOperationException();
}
@Override
public void flush() throws IOException {
// Do nothing.
}
@Override
public void close() {
// Do nothing.
}
}
/** Wraps a delegate ObjectInserter. */
public abstract static class Filter extends ObjectInserter {
/** @return delegate ObjectInserter to handle all processing. */
protected abstract ObjectInserter delegate();
@Override
protected byte[] buffer() {
return delegate().buffer();
}
@Override
public ObjectId idFor(int type, byte[] data) {
return delegate().idFor(type, data);
}
@Override
public ObjectId idFor(int type, byte[] data, int off, int len) {
return delegate().idFor(type, data, off, len);
}
@Override
public ObjectId idFor(int objectType, long length, InputStream in)
throws IOException {
return delegate().idFor(objectType, length, in);
}
@Override
public ObjectId idFor(TreeFormatter formatter) {
return delegate().idFor(formatter);
}
@Override
public ObjectId insert(int type, byte[] data) throws IOException {
return delegate().insert(type, data);
}
@Override
public ObjectId insert(int type, byte[] data, int off, int len)
throws IOException {
return delegate().insert(type, data, off, len);
}
@Override
public ObjectId insert(int objectType, long length, InputStream in)
throws IOException {
return delegate().insert(objectType, length, in);
}
@Override
public PackParser newPackParser(InputStream in) throws IOException {
return delegate().newPackParser(in);
}
@Override
public ObjectReader newReader() {
final ObjectReader dr = delegate().newReader();
return new ObjectReader.Filter() {
@Override
protected ObjectReader delegate() {
return dr;
}
@Override
public ObjectInserter getCreatedFromInserter() {
return ObjectInserter.Filter.this;
}
};
}
@Override
public void flush() throws IOException {
delegate().flush();
}
@Override
public void close() {
delegate().close();
}
}
private final SHA1 hasher = SHA1.newInstance();
/** Temporary working buffer for streaming data through. */
private byte[] tempBuffer;
/**
* Create a new inserter for a database.
*/
protected ObjectInserter() {
}
/**
* Obtain a temporary buffer for use by the ObjectInserter or its subclass.
* <p>
* This buffer is supplied by the ObjectInserter base class to itself and
* its subclasses for the purposes of pulling data from a supplied
* InputStream, passing it through a Deflater, or formatting the canonical
* format of a small object like a small tree or commit.
* <p>
* <strong>This buffer IS NOT for translation such as auto-CRLF or content
* filtering and must not be used for such purposes.</strong>
* <p>
* The returned buffer is small, around a few KiBs, and the size may change
* between versions of JGit. Callers using this buffer must always check the
* length of the returned array to ascertain how much space was provided.
* <p>
* There is a single buffer for each ObjectInserter, repeated calls to this
* method will (usually) always return the same buffer. If the caller needs
* more than one buffer, or needs a buffer of a larger size, it must manage
* that buffer on its own.
* <p>
* The buffer is usually on first demand for a buffer.
*
* @return a temporary byte array for use by the caller.
*/
protected byte[] buffer() {
byte[] b = tempBuffer;
if (b == null)
tempBuffer = b = new byte[8192];
return b;
}
/**
* Compute digest to help compute an ObjectId
*
* @return digest to help compute an ObjectId
* @since 4.7
*/
protected SHA1 digest() {
return hasher.reset();
}
/**
* Compute the name of an object, without inserting it.
*
* @param type
* type code of the object to store.
* @param data
* complete content of the object.
* @return the name of the object.
*/
public ObjectId idFor(int type, byte[] data) {
return idFor(type, data, 0, data.length);
}
/**
* Compute the name of an object, without inserting it.
*
* @param type
* type code of the object to store.
* @param data
* complete content of the object.
* @param off
* first position within {@code data}.
* @param len
* number of bytes to copy from {@code data}.
* @return the name of the object.
*/
public ObjectId idFor(int type, byte[] data, int off, int len) {
SHA1 md = SHA1.newInstance();
md.update(Constants.encodedTypeString(type));
md.update((byte) ' ');
md.update(Constants.encodeASCII(len));
md.update((byte) 0);
md.update(data, off, len);
return md.toObjectId();
}
/**
* Compute the name of an object, without inserting it.
*
* @param objectType
* type code of the object to store.
* @param length
* number of bytes to scan from {@code in}.
* @param in
* stream providing the object content. The caller is responsible
* for closing the stream.
* @return the name of the object.
* @throws java.io.IOException
* the source stream could not be read.
*/
public ObjectId idFor(int objectType, long length, InputStream in)
throws IOException {
SHA1 md = SHA1.newInstance();
md.update(Constants.encodedTypeString(objectType));
md.update((byte) ' ');
md.update(Constants.encodeASCII(length));
md.update((byte) 0);
byte[] buf = buffer();
while (length > 0) {
int n = in.read(buf, 0, (int) Math.min(length, buf.length));
if (n < 0)
throw new EOFException(JGitText.get().unexpectedEndOfInput);
md.update(buf, 0, n);
length -= n;
}
return md.toObjectId();
}
/**
* Compute the ObjectId for the given tree without inserting it.
*
* @param formatter
* a {@link org.eclipse.jgit.lib.TreeFormatter} object.
* @return the computed ObjectId
*/
public ObjectId idFor(TreeFormatter formatter) {
return formatter.computeId(this);
}
/**
* Insert a single tree into the store, returning its unique name.
*
* @param formatter
* the formatter containing the proposed tree's data.
* @return the name of the tree object.
* @throws java.io.IOException
* the object could not be stored.
*/
public final ObjectId insert(TreeFormatter formatter) throws IOException {
// Delegate to the formatter, as then it can pass the raw internal
// buffer back to this inserter, avoiding unnecessary data copying.
//
return formatter.insertTo(this);
}
/**
* Insert a single commit into the store, returning its unique name.
*
* @param builder
* the builder containing the proposed commit's data.
* @return the name of the commit object.
* @throws java.io.IOException
* the object could not be stored.
*/
public final ObjectId insert(CommitBuilder builder) throws IOException {
return insert(Constants.OBJ_COMMIT, builder.build());
}
/**
* Insert a single annotated tag into the store, returning its unique name.
*
* @param builder
* the builder containing the proposed tag's data.
* @return the name of the tag object.
* @throws java.io.IOException
* the object could not be stored.
*/
public final ObjectId insert(TagBuilder builder) throws IOException {
return insert(Constants.OBJ_TAG, builder.build());
}
/**
* Insert a single object into the store, returning its unique name.
*
* @param type
* type code of the object to store.
* @param data
* complete content of the object.
* @return the name of the object.
* @throws java.io.IOException
* the object could not be stored.
*/
public ObjectId insert(int type, byte[] data)
throws IOException {
return insert(type, data, 0, data.length);
}
/**
* Insert a single object into the store, returning its unique name.
*
* @param type
* type code of the object to store.
* @param data
* complete content of the object.
* @param off
* first position within {@code data}.
* @param len
* number of bytes to copy from {@code data}.
* @return the name of the object.
* @throws java.io.IOException
* the object could not be stored.
*/
public ObjectId insert(int type, byte[] data, int off, int len)
throws IOException {
return insert(type, len, new ByteArrayInputStream(data, off, len));
}
/**
* Insert a single object into the store, returning its unique name.
*
* @param objectType
* type code of the object to store.
* @param length
* number of bytes to copy from {@code in}.
* @param in
* stream providing the object content. The caller is responsible
* for closing the stream.
* @return the name of the object.
* @throws java.io.IOException
* the object could not be stored, or the source stream could
* not be read.
*/
public abstract ObjectId insert(int objectType, long length, InputStream in)
throws IOException;
/**
* Initialize a parser to read from a pack formatted stream.
*
* @param in
* the input stream. The stream is not closed by the parser, and
* must instead be closed by the caller once parsing is complete.
* @return the pack parser.
* @throws java.io.IOException
* the parser instance, which can be configured and then used to
* parse objects into the ObjectDatabase.
*/
public abstract PackParser newPackParser(InputStream in) throws IOException;
/**
* Open a reader for objects that may have been written by this inserter.
* <p>
* The returned reader allows the calling thread to read back recently
* inserted objects without first calling {@code flush()} to make them
* visible to the repository. The returned reader should only be used from
* the same thread as the inserter. Objects written by this inserter may not
* be visible to {@code this.newReader().newReader()}.
* <p>
* The returned reader should return this inserter instance from {@link
* ObjectReader#getCreatedFromInserter()}.
* <p>
* Behavior is undefined if an insert method is called on the inserter in the
* middle of reading from an {@link ObjectStream} opened from this reader. For
* example, reading the remainder of the object may fail, or newly written
* data may even be corrupted. Interleaving whole object reads (including
* streaming reads) with inserts is fine, just not interleaving streaming
* <em>partial</em> object reads with inserts.
*
* @since 3.5
* @return reader for any object, including an object recently inserted by
* this inserter since the last flush.
*/
public abstract ObjectReader newReader();
/**
* Make all inserted objects visible.
* <p>
* The flush may take some period of time to make the objects available to
* other threads.
*
* @throws java.io.IOException
* the flush could not be completed; objects inserted thus far
* are in an indeterminate state.
*/
public abstract void flush() throws IOException;
/**
* {@inheritDoc}
* <p>
* Release any resources used by this inserter.
* <p>
* An inserter that has been released can be used again, but may need to be
* released after the subsequent usage.
*
* @since 4.0
*/
@Override
public abstract void close();
}