ObjectBuilder

/*
 * Copyright (C) 2020, Thomas Wolf <thomas.wolf@paranor.ch> 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 static java.nio.charset.StandardCharsets.UTF_8;

import java.io.IOException;
import java.io.OutputStream;
import java.io.UnsupportedEncodingException;
import java.nio.charset.Charset;
import java.nio.charset.StandardCharsets;
import java.text.MessageFormat;
import java.util.Objects;

import org.eclipse.jgit.annotations.NonNull;
import org.eclipse.jgit.annotations.Nullable;
import org.eclipse.jgit.internal.JGitText;
import org.eclipse.jgit.util.References;

/**
 * Common base class for {@link CommitBuilder} and {@link TagBuilder}.
 *
 * @since 5.11
 */
public abstract class ObjectBuilder {

	/** Byte representation of "encoding". */
	private static final byte[] hencoding = Constants.encodeASCII("encoding"); //$NON-NLS-1$

	private PersonIdent author;

	private GpgSignature gpgSignature;

	private String message;

	private Charset encoding = StandardCharsets.UTF_8;

	/**
	 * Retrieves the author of this object.
	 *
	 * @return the author of this object, or {@code null} if not set yet
	 */
	protected PersonIdent getAuthor() {
		return author;
	}

	/**
	 * Sets the author (name, email address, and date) of this object.
	 *
	 * @param newAuthor
	 *            the new author, must be non-{@code null}
	 */
	protected void setAuthor(PersonIdent newAuthor) {
		author = Objects.requireNonNull(newAuthor);
	}

	/**
	 * Sets the GPG signature of this object.
	 * <p>
	 * Note, the signature set here will change the payload of the object, i.e.
	 * the output of {@link #build()} will include the signature. Thus, the
	 * typical flow will be:
	 * <ol>
	 * <li>call {@link #build()} without a signature set to obtain payload</li>
	 * <li>create {@link GpgSignature} from payload</li>
	 * <li>set {@link GpgSignature}</li>
	 * </ol>
	 * </p>
	 *
	 * @param gpgSignature
	 *            the signature to set or {@code null} to unset
	 * @since 5.3
	 */
	public void setGpgSignature(@Nullable GpgSignature gpgSignature) {
		this.gpgSignature = gpgSignature;
	}

	/**
	 * Retrieves the GPG signature of this object.
	 *
	 * @return the GPG signature of this object, or {@code null} if the object
	 *         is not signed
	 * @since 5.3
	 */
	@Nullable
	public GpgSignature getGpgSignature() {
		return gpgSignature;
	}

	/**
	 * Retrieves the complete message of the object.
	 *
	 * @return the complete message; can be {@code null}.
	 */
	@Nullable
	public String getMessage() {
		return message;
	}

	/**
	 * Sets the message (commit message, or message of an annotated tag).
	 *
	 * @param message
	 *            the message.
	 */
	public void setMessage(@Nullable String message) {
		this.message = message;
	}

	/**
	 * Retrieves the encoding that should be used for the message text.
	 *
	 * @return the encoding that should be used for the message text.
	 */
	@NonNull
	public Charset getEncoding() {
		return encoding;
	}

	/**
	 * Sets the encoding for the object message.
	 *
	 * @param encoding
	 *            the encoding to use.
	 */
	public void setEncoding(@NonNull Charset encoding) {
		this.encoding = encoding;
	}

	/**
	 * Format this builder's state as a git object.
	 *
	 * @return this object in the canonical git format, suitable for storage in
	 *         a repository.
	 * @throws java.io.UnsupportedEncodingException
	 *             the encoding specified by {@link #getEncoding()} is not
	 *             supported by this Java runtime.
	 */
	@NonNull
	public abstract byte[] build() throws UnsupportedEncodingException;

	/**
	 * Writes signature to output as per <a href=
	 * "https://github.com/git/git/blob/master/Documentation/technical/signature-format.txt#L66,L89">gpgsig
	 * header</a>.
	 * <p>
	 * CRLF and CR will be sanitized to LF and signature will have a hanging
	 * indent of one space starting with line two. A trailing line break is
	 * <em>not</em> written; the caller is supposed to terminate the GPG
	 * signature header by writing a single newline.
	 * </p>
	 *
	 * @param in
	 *            signature string with line breaks
	 * @param out
	 *            output stream
	 * @param enforceAscii
	 *            whether to throw {@link IllegalArgumentException} if non-ASCII
	 *            characters are encountered
	 * @throws IOException
	 *             thrown by the output stream
	 * @throws IllegalArgumentException
	 *             if the signature string contains non 7-bit ASCII chars and
	 *             {@code enforceAscii == true}
	 */
	static void writeMultiLineHeader(@NonNull String in,
			@NonNull OutputStream out, boolean enforceAscii)
			throws IOException, IllegalArgumentException {
		int length = in.length();
		for (int i = 0; i < length; ++i) {
			char ch = in.charAt(i);
			switch (ch) {
			case '\r':
				if (i + 1 < length && in.charAt(i + 1) == '\n') {
					++i;
				}
				if (i + 1 < length) {
					out.write('\n');
					out.write(' ');
				}
				break;
			case '\n':
				if (i + 1 < length) {
					out.write('\n');
					out.write(' ');
				}
				break;
			default:
				// sanity check
				if (ch > 127 && enforceAscii)
					throw new IllegalArgumentException(MessageFormat
							.format(JGitText.get().notASCIIString, in));
				out.write(ch);
				break;
			}
		}
	}

	/**
	 * Writes an "encoding" header.
	 *
	 * @param encoding
	 *            to write
	 * @param out
	 *            to write to
	 * @throws IOException
	 *             if writing fails
	 */
	static void writeEncoding(@NonNull Charset encoding,
			@NonNull OutputStream out) throws IOException {
		if (!References.isSameObject(encoding, UTF_8)) {
			out.write(hencoding);
			out.write(' ');
			out.write(Constants.encodeASCII(encoding.name()));
			out.write('\n');
		}
	}
}