Class RefUpdate

java.lang.Object
org.eclipse.jgit.lib.RefUpdate
Direct Known Subclasses:
DfsRefUpdate, FileReftableDatabase.FileReftableRefUpdate, RefDirectoryUpdate

public abstract class RefUpdate extends Object
Creates, updates or deletes any reference.
  • Field Details

    • newValue

      private ObjectId newValue
      New value the caller wants this ref to have.
    • force

      private boolean force
      Does this specification ask for forced updated (rewind/reset)?
    • refLogIdent

      private PersonIdent refLogIdent
      Identity to record action as within the reflog.
    • refLogMessage

      private String refLogMessage
      Message the caller wants included in the reflog.
    • refLogIncludeResult

      private boolean refLogIncludeResult
      Should the Result value be appended to refLogMessage.
    • forceRefLog

      private boolean forceRefLog
      Should reflogs be written even if the configured default for this ref is not to write it.
    • oldValue

      private ObjectId oldValue
      Old value of the ref, obtained after we lock it.
    • expValue

      private ObjectId expValue
      If non-null, the value oldValue must have to continue.
    • result

      private RefUpdate.Result result
      Result of the update operation.
    • pushCert

      private PushCertificate pushCert
      Push certificate associated with this update.
    • ref

      private final Ref ref
    • detachingSymbolicRef

      private boolean detachingSymbolicRef
      Is this RefUpdate detaching a symbolic ref? We need this info since this.ref will normally be peeled of in case of detaching a symbolic ref (HEAD for example). Without this flag we cannot decide whether the ref has to be updated or not in case when it was a symbolic ref and the newValue == oldValue.
    • checkConflicting

      private boolean checkConflicting
  • Constructor Details

    • RefUpdate

      protected RefUpdate(Ref ref)
      Construct a new update operation for the reference.

      ref.getObjectId() will be used to seed getOldObjectId(), which callers can use as part of their own update logic.

      Parameters:
      ref - the reference that will be updated by this operation.
  • Method Details

    • getRefDatabase

      protected abstract RefDatabase getRefDatabase()
      Get the reference database this update modifies.
      Returns:
      the reference database this update modifies.
    • getRepository

      protected abstract Repository getRepository()
      Get the repository storing the database's objects.
      Returns:
      the repository storing the database's objects.
    • tryLock

      protected abstract boolean tryLock(boolean deref) throws IOException
      Try to acquire the lock on the reference.

      If the locking was successful the implementor must set the current identity value by calling setOldObjectId(ObjectId).

      Parameters:
      deref - true if the lock should be taken against the leaf level reference; false if it should be taken exactly against the current reference.
      Returns:
      true if the lock was acquired and the reference is likely protected from concurrent modification; false if it failed.
      Throws:
      IOException - the lock couldn't be taken due to an unexpected storage failure, and not because of a concurrent update.
    • unlock

      protected abstract void unlock()
      Releases the lock taken by tryLock(boolean) if it succeeded.
    • doUpdate

      protected abstract RefUpdate.Result doUpdate(RefUpdate.Result desiredResult) throws IOException
      Do update
      Parameters:
      desiredResult - a RefUpdate.Result object.
      Returns:
      result
      Throws:
      IOException
    • doDelete

      protected abstract RefUpdate.Result doDelete(RefUpdate.Result desiredResult) throws IOException
      Do delete
      Parameters:
      desiredResult - a RefUpdate.Result object.
      Returns:
      result
      Throws:
      IOException
    • doLink

      protected abstract RefUpdate.Result doLink(String target) throws IOException
      Do link
      Parameters:
      target - a String object.
      Returns:
      RefUpdate.Result.NEW on success.
      Throws:
      IOException
    • getName

      public String getName()
      Get the name of the ref this update will operate on.
      Returns:
      name of underlying ref.
    • getRef

      public Ref getRef()
      Get the reference this update will create or modify.
      Returns:
      the reference this update will create or modify.
    • getNewObjectId

      public ObjectId getNewObjectId()
      Get the new value the ref will be (or was) updated to.
      Returns:
      new value. Null if the caller has not configured it.
    • setDetachingSymbolicRef

      public void setDetachingSymbolicRef()
      Tells this RefUpdate that it is actually detaching a symbolic ref.
    • isDetachingSymbolicRef

      public boolean isDetachingSymbolicRef()
      Return whether this update is actually detaching a symbolic ref.
      Returns:
      true if detaching a symref.
      Since:
      4.9
    • setNewObjectId

      public void setNewObjectId(AnyObjectId id)
      Set the new value the ref will update to.
      Parameters:
      id - the new value.
    • getExpectedOldObjectId

      public ObjectId getExpectedOldObjectId()
      Get the expected value of the ref after the lock is taken, but before update occurs.
      Returns:
      the expected value of the ref after the lock is taken, but before update occurs. Null to avoid the compare and swap test. Use ObjectId.zeroId() to indicate expectation of a non-existant ref.
    • setExpectedOldObjectId

      public void setExpectedOldObjectId(AnyObjectId id)
      Set the expected value of the ref after the lock is taken, but before update occurs.
      Parameters:
      id - the expected value of the ref after the lock is taken, but before update occurs. Null to avoid the compare and swap test. Use ObjectId.zeroId() to indicate expectation of a non-existant ref.
    • isForceUpdate

      public boolean isForceUpdate()
      Check if this update wants to forcefully change the ref.
      Returns:
      true if this update should ignore merge tests.
    • setForceUpdate

      public void setForceUpdate(boolean b)
      Set if this update wants to forcefully change the ref.
      Parameters:
      b - true if this update should ignore merge tests.
    • getRefLogIdent

      public PersonIdent getRefLogIdent()
      Get identity of the user making the change in the reflog.
      Returns:
      identity of the user making the change in the reflog.
    • setRefLogIdent

      public void setRefLogIdent(PersonIdent pi)
      Set the identity of the user appearing in the reflog.

      The timestamp portion of the identity is ignored. A new identity with the current timestamp will be created automatically when the update occurs and the log record is written.

      Parameters:
      pi - identity of the user. If null the identity will be automatically determined based on the repository configuration.
    • getRefLogMessage

      public String getRefLogMessage()
      Get the message to include in the reflog.
      Returns:
      message the caller wants to include in the reflog; null if the update should not be logged.
    • isRefLogIncludingResult

      protected boolean isRefLogIncludingResult()
      Whether the ref log message should show the result.
      Returns:
      true if the ref log message should show the result.
    • setRefLogMessage

      public void setRefLogMessage(String msg, boolean appendStatus)
      Set the message to include in the reflog.

      Repository implementations may limit which reflogs are written by default, based on the project configuration. If a repo is not configured to write logs for this ref by default, setting the message alone may have no effect. To indicate that the repo should write logs for this update in spite of configured defaults, use setForceRefLog(boolean).

      Parameters:
      msg - the message to describe this change. It may be null if appendStatus is null in order not to append to the reflog
      appendStatus - true if the status of the ref change (fast-forward or forced-update) should be appended to the user supplied message.
    • disableRefLog

      public void disableRefLog()
      Don't record this update in the ref's associated reflog.
    • setForceRefLog

      public void setForceRefLog(boolean force)
      Force writing a reflog for the updated ref.
      Parameters:
      force - whether to force.
      Since:
      4.9
    • isForceRefLog

      protected boolean isForceRefLog()
      Check whether the reflog should be written regardless of repo defaults.
      Returns:
      whether force writing is enabled.
      Since:
      4.9
    • getOldObjectId

      public ObjectId getOldObjectId()
      The old value of the ref, prior to the update being attempted.

      This value may differ before and after the update method. Initially it is populated with the value of the ref before the lock is taken, but the old value may change if someone else modified the ref between the time we last read it and when the ref was locked for update.

      Returns:
      the value of the ref prior to the update being attempted; null if the updated has not been attempted yet.
    • setOldObjectId

      protected void setOldObjectId(ObjectId old)
      Set the old value of the ref.
      Parameters:
      old - the old value.
    • setPushCertificate

      public void setPushCertificate(PushCertificate cert)
      Set a push certificate associated with this update.

      This usually includes a command to update this ref, but is not required to.

      Parameters:
      cert - push certificate, may be null.
      Since:
      4.1
    • getPushCertificate

      protected PushCertificate getPushCertificate()
      Set the push certificate associated with this update.

      This usually includes a command to update this ref, but is not required to.

      Returns:
      push certificate, may be null.
      Since:
      4.1
    • getResult

      public RefUpdate.Result getResult()
      Get the status of this update.

      The same value that was previously returned from an update method.

      Returns:
      the status of the update.
    • requireCanDoUpdate

      private void requireCanDoUpdate()
    • forceUpdate

      public RefUpdate.Result forceUpdate() throws IOException
      Force the ref to take the new value.

      This is just a convenient helper for setting the force flag, and as such the merge test is performed.

      Returns:
      the result status of the update.
      Throws:
      IOException - an unexpected IO error occurred while writing changes.
    • update

      public RefUpdate.Result update() throws IOException
      Gracefully update the ref to the new value.

      Merge test will be performed according to isForceUpdate().

      This is the same as:

       return update(new RevWalk(getRepository()));
       
      Returns:
      the result status of the update.
      Throws:
      IOException - an unexpected IO error occurred while writing changes.
    • update

      public RefUpdate.Result update(RevWalk walk) throws IOException
      Gracefully update the ref to the new value.

      Merge test will be performed according to isForceUpdate().

      Parameters:
      walk - a RevWalk instance this update command can borrow to perform the merge test. The walk will be reset to perform the test.
      Returns:
      the result status of the update.
      Throws:
      IOException - an unexpected IO error occurred while writing changes.
    • delete

      public RefUpdate.Result delete() throws IOException
      Delete the ref.

      This is the same as:

       return delete(new RevWalk(getRepository()));
       
      Returns:
      the result status of the delete.
      Throws:
      IOException
    • delete

      public RefUpdate.Result delete(RevWalk walk) throws IOException
      Delete the ref.
      Parameters:
      walk - a RevWalk instance this delete command can borrow to perform the merge test. The walk will be reset to perform the test.
      Returns:
      the result status of the delete.
      Throws:
      IOException
    • link

      public RefUpdate.Result link(String target) throws IOException
      Replace this reference with a symbolic reference to another reference.

      This exact reference (not its traversed leaf) is replaced with a symbolic reference to the requested name.

      Parameters:
      target - name of the new target for this reference. The new target name must be absolute, so it must begin with refs/.
      Returns:
      RefUpdate.Result.NEW or RefUpdate.Result.FORCED on success.
      Throws:
      IOException
    • updateImpl

      private RefUpdate.Result updateImpl(RevWalk walk, RefUpdate.Store store) throws IOException
      Throws:
      IOException
    • setCheckConflicting

      public void setCheckConflicting(boolean check)
      Enable/disable the check for conflicting ref names. By default conflicts are checked explicitly.
      Parameters:
      check - whether to enable the check for conflicting ref names.
      Since:
      3.0
    • safeParseNew

      private static RevObject safeParseNew(RevWalk rw, AnyObjectId newId) throws IOException
      Throws:
      IOException
    • safeParseOld

      private static RevObject safeParseOld(RevWalk rw, AnyObjectId oldId) throws IOException
      Throws:
      IOException