jgit/org.eclipse.jgit/src/org/eclipse/jgit/transport/RemoteRefUpdate.java

/*
 * Copyright (C) 2008, Marek Zawirski <marek.zawirski@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.transport;

import java.io.IOException;
import java.text.MessageFormat;

import org.eclipse.jgit.internal.JGitText;
import org.eclipse.jgit.lib.ObjectId;
import org.eclipse.jgit.lib.Ref;
import org.eclipse.jgit.lib.RefUpdate;
import org.eclipse.jgit.lib.Repository;
import org.eclipse.jgit.revwalk.RevWalk;

/**
 * Represent request and status of a remote ref update. Specification is
 * provided by client, while status is handled by
 * {@link org.eclipse.jgit.transport.PushProcess} class, being read-only for
 * client.
 * <p>
 * Client can create instances of this class directly, basing on user
 * specification and advertised refs
 * ({@link org.eclipse.jgit.transport.Connection} or through
 * {@link org.eclipse.jgit.transport.Transport} helper methods. Apply this
 * specification on remote repository using
 * {@link org.eclipse.jgit.transport.Transport#push(org.eclipse.jgit.lib.ProgressMonitor, java.util.Collection)}
 * method.
 * </p>
 */
public class RemoteRefUpdate {
	/**
	 * Represent current status of a remote ref update.
	 */
	public enum Status {
		/**
		 * Push process hasn't yet attempted to update this ref. This is the
		 * default status, prior to push process execution.
		 */
		NOT_ATTEMPTED,

		/**
		 * Remote ref was up to date, there was no need to update anything.
		 */
		UP_TO_DATE,

		/**
		 * Remote ref update was rejected, as it would cause non fast-forward
		 * update.
		 */
		REJECTED_NONFASTFORWARD,

		/**
		 * Remote ref update was rejected, because remote side doesn't
		 * support/allow deleting refs.
		 */
		REJECTED_NODELETE,

		/**
		 * Remote ref update was rejected, because old object id on remote
		 * repository wasn't the same as defined expected old object.
		 */
		REJECTED_REMOTE_CHANGED,

		/**
		 * Remote ref update was rejected for other reason, possibly described
		 * in {@link RemoteRefUpdate#getMessage()}.
		 */
		REJECTED_OTHER_REASON,

		/**
		 * Remote ref didn't exist. Can occur on delete request of a non
		 * existing ref.
		 */
		NON_EXISTING,

		/**
		 * Push process is awaiting update report from remote repository. This
		 * is a temporary state or state after critical error in push process.
		 */
		AWAITING_REPORT,

		/**
		 * Remote ref was successfully updated.
		 */
		OK;
	}

	private ObjectId expectedOldObjectId;

	private final ObjectId newObjectId;

	private final String remoteName;

	private final TrackingRefUpdate trackingRefUpdate;

	private final String srcRef;

	private final boolean forceUpdate;

	private Status status;

	private boolean fastForward;

	private String message;

	private final Repository localDb;

	private RefUpdate localUpdate;

	/**
	 * Construct remote ref update request by providing an update specification.
	 * Object is created with default
	 * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#NOT_ATTEMPTED}
	 * status and no message.
	 *
	 * @param localDb
	 *            local repository to push from.
	 * @param srcRef
	 *            source revision - any string resolvable by
	 *            {@link org.eclipse.jgit.lib.Repository#resolve(String)}. This
	 *            resolves to the new object that the caller want remote ref to
	 *            be after update. Use null or
	 *            {@link org.eclipse.jgit.lib.ObjectId#zeroId()} string for
	 *            delete request.
	 * @param remoteName
	 *            full name of a remote ref to update, e.g. "refs/heads/master"
	 *            (no wildcard, no short name).
	 * @param forceUpdate
	 *            true when caller want remote ref to be updated regardless
	 *            whether it is fast-forward update (old object is ancestor of
	 *            new object).
	 * @param localName
	 *            optional full name of a local stored tracking branch, to
	 *            update after push, e.g. "refs/remotes/zawir/dirty" (no
	 *            wildcard, no short name); null if no local tracking branch
	 *            should be updated.
	 * @param expectedOldObjectId
	 *            optional object id that caller is expecting, requiring to be
	 *            advertised by remote side before update; update will take
	 *            place ONLY if remote side advertise exactly this expected id;
	 *            null if caller doesn't care what object id remote side
	 *            advertise. Use {@link org.eclipse.jgit.lib.ObjectId#zeroId()}
	 *            when expecting no remote ref with this name.
	 * @throws java.io.IOException
	 *             when I/O error occurred during creating
	 *             {@link org.eclipse.jgit.transport.TrackingRefUpdate} for
	 *             local tracking branch or srcRef can't be resolved to any
	 *             object.
	 * @throws java.lang.IllegalArgumentException
	 *             if some required parameter was null
	 */
	public RemoteRefUpdate(final Repository localDb, final String srcRef,
			final String remoteName, final boolean forceUpdate,
			final String localName, final ObjectId expectedOldObjectId)
			throws IOException {
		this(localDb, srcRef, srcRef != null ? localDb.resolve(srcRef)
				: ObjectId.zeroId(), remoteName, forceUpdate, localName,
				expectedOldObjectId);
	}

	/**
	 * Construct remote ref update request by providing an update specification.
	 * Object is created with default
	 * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#NOT_ATTEMPTED}
	 * status and no message.
	 *
	 * @param localDb
	 *            local repository to push from.
	 * @param srcRef
	 *            source revision. Use null to delete.
	 * @param remoteName
	 *            full name of a remote ref to update, e.g. "refs/heads/master"
	 *            (no wildcard, no short name).
	 * @param forceUpdate
	 *            true when caller want remote ref to be updated regardless
	 *            whether it is fast-forward update (old object is ancestor of
	 *            new object).
	 * @param localName
	 *            optional full name of a local stored tracking branch, to
	 *            update after push, e.g. "refs/remotes/zawir/dirty" (no
	 *            wildcard, no short name); null if no local tracking branch
	 *            should be updated.
	 * @param expectedOldObjectId
	 *            optional object id that caller is expecting, requiring to be
	 *            advertised by remote side before update; update will take
	 *            place ONLY if remote side advertise exactly this expected id;
	 *            null if caller doesn't care what object id remote side
	 *            advertise. Use {@link org.eclipse.jgit.lib.ObjectId#zeroId()}
	 *            when expecting no remote ref with this name.
	 * @throws java.io.IOException
	 *             when I/O error occurred during creating
	 *             {@link org.eclipse.jgit.transport.TrackingRefUpdate} for
	 *             local tracking branch or srcRef can't be resolved to any
	 *             object.
	 * @throws java.lang.IllegalArgumentException
	 *             if some required parameter was null
	 */
	public RemoteRefUpdate(final Repository localDb, final Ref srcRef,
			final String remoteName, final boolean forceUpdate,
			final String localName, final ObjectId expectedOldObjectId)
			throws IOException {
		this(localDb, srcRef != null ? srcRef.getName() : null,
				srcRef != null ? srcRef.getObjectId() : null, remoteName,
				forceUpdate, localName, expectedOldObjectId);
	}

	/**
	 * Construct remote ref update request by providing an update specification.
	 * Object is created with default
	 * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#NOT_ATTEMPTED}
	 * status and no message.
	 *
	 * @param localDb
	 *            local repository to push from.
	 * @param srcRef
	 *            source revision to label srcId with. If null srcId.name() will
	 *            be used instead.
	 * @param srcId
	 *            The new object that the caller wants remote ref to be after
	 *            update. Use null or
	 *            {@link org.eclipse.jgit.lib.ObjectId#zeroId()} for delete
	 *            request.
	 * @param remoteName
	 *            full name of a remote ref to update, e.g. "refs/heads/master"
	 *            (no wildcard, no short name).
	 * @param forceUpdate
	 *            true when caller want remote ref to be updated regardless
	 *            whether it is fast-forward update (old object is ancestor of
	 *            new object).
	 * @param localName
	 *            optional full name of a local stored tracking branch, to
	 *            update after push, e.g. "refs/remotes/zawir/dirty" (no
	 *            wildcard, no short name); null if no local tracking branch
	 *            should be updated.
	 * @param expectedOldObjectId
	 *            optional object id that caller is expecting, requiring to be
	 *            advertised by remote side before update; update will take
	 *            place ONLY if remote side advertise exactly this expected id;
	 *            null if caller doesn't care what object id remote side
	 *            advertise. Use {@link org.eclipse.jgit.lib.ObjectId#zeroId()}
	 *            when expecting no remote ref with this name.
	 * @throws java.io.IOException
	 *             when I/O error occurred during creating
	 *             {@link org.eclipse.jgit.transport.TrackingRefUpdate} for
	 *             local tracking branch or srcRef can't be resolved to any
	 *             object.
	 * @throws java.lang.IllegalArgumentException
	 *             if some required parameter was null
	 */
	public RemoteRefUpdate(final Repository localDb, final String srcRef,
			final ObjectId srcId, final String remoteName,
			final boolean forceUpdate, final String localName,
			final ObjectId expectedOldObjectId) throws IOException {
		if (remoteName == null)
			throw new IllegalArgumentException(JGitText.get().remoteNameCannotBeNull);
		if (srcId == null && srcRef != null)
			throw new IOException(MessageFormat.format(
					JGitText.get().sourceRefDoesntResolveToAnyObject, srcRef));

		if (srcRef != null)
			this.srcRef = srcRef;
		else if (srcId != null && !srcId.equals(ObjectId.zeroId()))
			this.srcRef = srcId.name();
		else
			this.srcRef = null;

		if (srcId != null)
			this.newObjectId = srcId;
		else
			this.newObjectId = ObjectId.zeroId();

		this.remoteName = remoteName;
		this.forceUpdate = forceUpdate;
		if (localName != null && localDb != null) {
			localUpdate = localDb.updateRef(localName);
			localUpdate.setForceUpdate(true);
			localUpdate.setRefLogMessage("push", true); //$NON-NLS-1$
			localUpdate.setNewObjectId(newObjectId);
			trackingRefUpdate = new TrackingRefUpdate(
					true,
					remoteName,
					localName,
					localUpdate.getOldObjectId() != null
						? localUpdate.getOldObjectId()
						: ObjectId.zeroId(),
					newObjectId);
		} else
			trackingRefUpdate = null;
		this.localDb = localDb;
		this.expectedOldObjectId = expectedOldObjectId;
		this.status = Status.NOT_ATTEMPTED;
	}

	/**
	 * Create a new instance of this object basing on existing instance for
	 * configuration. State (like {@link #getMessage()}, {@link #getStatus()})
	 * of base object is not shared. Expected old object id is set up from
	 * scratch, as this constructor may be used for 2-stage push: first one
	 * being dry run, second one being actual push.
	 *
	 * @param base
	 *            configuration base.
	 * @param newExpectedOldObjectId
	 *            new expected object id value.
	 * @throws java.io.IOException
	 *             when I/O error occurred during creating
	 *             {@link org.eclipse.jgit.transport.TrackingRefUpdate} for
	 *             local tracking branch or srcRef of base object no longer can
	 *             be resolved to any object.
	 */
	public RemoteRefUpdate(final RemoteRefUpdate base,
			final ObjectId newExpectedOldObjectId) throws IOException {
		this(base.localDb, base.srcRef, base.remoteName, base.forceUpdate,
				(base.trackingRefUpdate == null ? null : base.trackingRefUpdate
						.getLocalName()), newExpectedOldObjectId);
	}

	/**
	 * Get expected old object id
	 *
	 * @return expectedOldObjectId required to be advertised by remote side, as
	 *         set in constructor; may be null.
	 */
	public ObjectId getExpectedOldObjectId() {
		return expectedOldObjectId;
	}

	/**
	 * Whether some object is required to be advertised by remote side, as set
	 * in constructor
	 *
	 * @return true if some object is required to be advertised by remote side,
	 *         as set in constructor; false otherwise.
	 */
	public boolean isExpectingOldObjectId() {
		return expectedOldObjectId != null;
	}

	/**
	 * Get new object id
	 *
	 * @return newObjectId for remote ref, as set in constructor.
	 */
	public ObjectId getNewObjectId() {
		return newObjectId;
	}

	/**
	 * Whether this update is a deleting update
	 *
	 * @return true if this update is deleting update; false otherwise.
	 */
	public boolean isDelete() {
		return ObjectId.zeroId().equals(newObjectId);
	}

	/**
	 * Get name of remote ref to update
	 *
	 * @return name of remote ref to update, as set in constructor.
	 */
	public String getRemoteName() {
		return remoteName;
	}

	/**
	 * Get tracking branch update if localName was set in constructor.
	 *
	 * @return local tracking branch update if localName was set in constructor.
	 */
	public TrackingRefUpdate getTrackingRefUpdate() {
		return trackingRefUpdate;
	}

	/**
	 * Get source revision as specified by user (in constructor)
	 *
	 * @return source revision as specified by user (in constructor), could be
	 *         any string parseable by
	 *         {@link org.eclipse.jgit.lib.Repository#resolve(String)}; can be
	 *         null if specified that way in constructor - this stands for
	 *         delete request.
	 */
	public String getSrcRef() {
		return srcRef;
	}

	/**
	 * Whether user specified a local tracking branch for remote update
	 *
	 * @return true if user specified a local tracking branch for remote update;
	 *         false otherwise.
	 */
	public boolean hasTrackingRefUpdate() {
		return trackingRefUpdate != null;
	}

	/**
	 * Whether this update is forced regardless of old remote ref object
	 *
	 * @return true if this update is forced regardless of old remote ref
	 *         object; false otherwise.
	 */
	public boolean isForceUpdate() {
		return forceUpdate;
	}

	/**
	 * Get status of remote ref update operation.
	 *
	 * @return status of remote ref update operation.
	 */
	public Status getStatus() {
		return status;
	}

	/**
	 * Check whether update was fast-forward. Note that this result is
	 * meaningful only after successful update (when status is
	 * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#OK}).
	 *
	 * @return true if update was fast-forward; false otherwise.
	 */
	public boolean isFastForward() {
		return fastForward;
	}

	/**
	 * Get message describing reasons of status when needed/possible; may be
	 * null.
	 *
	 * @return message describing reasons of status when needed/possible; may be
	 *         null.
	 */
	public String getMessage() {
		return message;
	}

	void setExpectedOldObjectId(ObjectId id) {
		expectedOldObjectId = id;
	}

	void setStatus(Status status) {
		this.status = status;
	}

	void setFastForward(boolean fastForward) {
		this.fastForward = fastForward;
	}

	void setMessage(String message) {
		this.message = message;
	}

	/**
	 * Update locally stored tracking branch with the new object.
	 *
	 * @param walk
	 *            walker used for checking update properties.
	 * @throws java.io.IOException
	 *             when I/O error occurred during update
	 */
	protected void updateTrackingRef(RevWalk walk) throws IOException {
		if (isDelete())
			trackingRefUpdate.setResult(localUpdate.delete(walk));
		else
			trackingRefUpdate.setResult(localUpdate.update(walk));
	}

	/** {@inheritDoc} */
	@SuppressWarnings("nls")
	@Override
	public String toString() {
		return "RemoteRefUpdate[remoteName="
				+ remoteName
				+ ", "
				+ status
				+ ", "
				+ (expectedOldObjectId != null ? expectedOldObjectId.name()
						: "(null)") + "..."
				+ (newObjectId != null ? newObjectId.name() : "(null)")
				+ (fastForward ? ", fastForward" : "")
				+ ", srcRef=" + srcRef
				+ (forceUpdate ? ", forceUpdate" : "") + ", message="
				+ (message != null ? "\"" + message + "\"" : "null") + "]";
	}
}