Package org.eclipse.jgit.lib

## Class RefUpdate

- java.lang.Object
- - org.eclipse.jgit.lib.RefUpdate

    public abstract class RefUpdate
    extends Object

Creates, updates or deletes any reference.

### Nested Class Summary

Nested Classes
`static class` `RefUpdate.Result` Status of an update request.

### Constructor Summary

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

### Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
`RefUpdate.Result` `delete()` Delete the ref.
`RefUpdate.Result` `delete​(RevWalk walk)` Delete the ref.
`void` `disableRefLog()` Don't record this update in the ref's associated reflog.
`protected abstract RefUpdate.Result` `doDelete​(RefUpdate.Result desiredResult)`
`protected abstract RefUpdate.Result` `doLink​(String target)`
`protected abstract RefUpdate.Result` `doUpdate​(RefUpdate.Result desiredResult)`
`RefUpdate.Result` `forceUpdate()` Force the ref to take the new value.
`ObjectId` `getExpectedOldObjectId()`
`String` `getName()` Get the name of the ref this update will operate on.
`ObjectId` `getNewObjectId()` Get the new value the ref will be (or was) updated to.
`ObjectId` `getOldObjectId()` The old value of the ref, prior to the update being attempted.
`Ref` `getRef()`
`protected abstract RefDatabase` `getRefDatabase()`
`PersonIdent` `getRefLogIdent()`
`String` `getRefLogMessage()` Get the message to include in the reflog.
`protected abstract Repository` `getRepository()`
`RefUpdate.Result` `getResult()` Get the status of this update.
`boolean` `isForceUpdate()` Check if this update wants to forcefully change the ref.
`protected boolean` `isRefLogIncludingResult()`
`RefUpdate.Result` `link​(String target)` Replace this reference with a symbolic reference to another reference.
`void` `setCheckConflicting​(boolean check)` Enable/disable the check for conflicting ref names.
`void` `setDetachingSymbolicRef()` Tells this RefUpdate that it is actually detaching a symbolic ref.
`void` `setExpectedOldObjectId​(AnyObjectId id)`
`void` `setForceUpdate​(boolean b)` Set if this update wants to forcefully change the ref.
`void` `setNewObjectId​(AnyObjectId id)` Set the new value the ref will update to.
`protected void` `setOldObjectId​(ObjectId old)` Set the old value of the ref.
`void` `setRefLogIdent​(PersonIdent pi)` Set the identity of the user appearing in the reflog.
`void` `setRefLogMessage​(String msg, boolean appendStatus)` Set the message to include in the reflog.
`protected abstract boolean` `tryLock​(boolean deref)` Try to acquire the lock on the reference.
`protected abstract void` `unlock()` Releases the lock taken by `tryLock(boolean)` if it succeeded.
`RefUpdate.Result` `update()` Gracefully update the ref to the new value.
`RefUpdate.Result` `update​(RevWalk walk)` Gracefully update the ref to the new value.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### 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 Detail

#### getRefDatabase

    protected abstract RefDatabase getRefDatabase()

Returns:
  the reference database this update modifies.

#### getRepository

    protected abstract Repository getRepository()

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

Parameters:
  `desiredResult` -
Returns:
  `result`
Throws:
  `IOException`

#### doDelete

    protected abstract RefUpdate.Result doDelete​(RefUpdate.Result desiredResult)
                                          throws IOException

Parameters:
  `desiredResult` -
Returns:
  `result`
Throws:
  `IOException`

#### doLink

    protected abstract RefUpdate.Result doLink​(String target)
                                        throws IOException

Parameters:
  `target` -
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()

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.

#### setNewObjectId

    public void setNewObjectId​(AnyObjectId id)

Set the new value the ref will update to.

Parameters:
  `id` - the new value.

#### getExpectedOldObjectId

    public ObjectId getExpectedOldObjectId()

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)

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()

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()

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.

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.

#### 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.

#### 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.

#### 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`

#### setCheckConflicting

    public void setCheckConflicting​(boolean check)

Enable/disable the check for conflicting ref names. By default conflicts are checked explicitly.

Parameters:
  `check` -
Since:
  3.0