/*
    * 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 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.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 static abstract 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();
 }