[Canonical page](<https://docs.dhtmlx.com/planning-engine/java/api/changes/patch/>)
[Full documentation index](<https://docs.dhtmlx.com/planning-engine/llms.txt>)


# Patch<T>

A three-state field of an update record. A patch is missing (keep the current value), null (clear it) or carries a value (set it). Every editable field of [`TaskUpdate`](<https://docs.dhtmlx.com/planning-engine/java/api/changes/task-update.md>), [`LinkUpdate`](<https://docs.dhtmlx.com/planning-engine/java/api/changes/link-update.md>), [`ResourceUpdate`](<https://docs.dhtmlx.com/planning-engine/java/api/changes/resource-update.md>) and [`AssignmentUpdate`](<https://docs.dhtmlx.com/planning-engine/java/api/changes/assignment-update.md>) is a `Patch<T>`, and a new update record starts with every patch missing.

Build one with the static factories `Patch.missing()`, `Patch.nullValue()` or `Patch.of(value)`. There's no public constructor.

## Declaration

```java
package org.dhtmlx.plen;

public final class Patch<T> extends ValueRecord
```

A patch is immutable: `kind` is `final` and the carried value is private.

## Fields

### kind

```java
public final PatchKind kind;
```

Which of the three states the patch is in. See [`PatchKind`](<https://docs.dhtmlx.com/planning-engine/java/api/changes/patch.md#patchkind>).

## Static methods

### missing

```java
public static <T> Patch<T> missing()
```

Returns a patch that leaves the field unchanged. Every patch field of an update record starts with this value.

### nullValue

```java
public static <T> Patch<T> nullValue()
```

Returns a patch that clears the field. What clearing means depends on the field: an optional field is cleared, a field with a default goes back to that default, and a required field (a link's `source` / `target`, an assignment's `task` / `resource`) rejects the operation. Each update record's page lists its fields.

### of

```java
public static <T> Patch<T> of(T value)
```

Returns a patch that sets the field to `value`.

`Patch.of(null)` is a `VALUE` patch that holds `null`, not a `NULL` patch. On task and resource `calendarId` it clears the field. On task `parent` and `pauses`, link `source` / `target`, assignment `task` / `resource` and the boxed scalar fields (`Patch<Double>`, `Patch<Boolean>`, `Patch<Integer>`) it throws `NullPointerException` when the change is applied. Use `Patch.nullValue()` to clear a field.

## Methods

### isMissing, isNull, hasValue

```java
public boolean isMissing()
public boolean isNull()
public boolean hasValue()
```

Return `true` when `kind` is `MISSING`, `NULL` or `VALUE`, in that order.

### value

```java
public T value()
```

Returns the carried value.

**Errors:** throws `IllegalStateException` when the patch isn't `hasValue()`.

### tryGetValue

```java
public boolean tryGetValue(Ref<T> out)
```

Writes the carried value into `out.value` and returns `true` when the patch has one. For a missing or null patch it writes `null` and returns `false`.

| Name | Type | Description |
|---|---|---|
| `out` | [`Ref<T>`](<https://docs.dhtmlx.com/planning-engine/java/api/support/ref.md>) | Out-parameter holder. Create it with `new Ref<>()`. |

### equals, hashCode

```java
public boolean equals(Object o)
public int hashCode()
```

Two patches are equal when they have the same `kind` and their values are equal by `Objects.equals`. `missing()` equals `missing()`, and `nullValue()` equals `nullValue()`. `hashCode` follows the same rule.

### toString

Inherited from [`ValueRecord`](<https://docs.dhtmlx.com/planning-engine/java/api/support/value-record.md>). It prints only the public field, e.g. `Patch{kind=VALUE}`, without the carried value.

## Ref<T>

A mutable holder for the out-parameter of [`tryGetValue`](<https://docs.dhtmlx.com/planning-engine/java/api/changes/patch.md#trygetvalue>).

```java
package org.dhtmlx.plen;

public class Ref<T> {
    public T value;

    public Ref()
    public Ref(T value)
}
```

| Member | Description |
|---|---|
| `value` | The held value. `null` after `new Ref<>()`. |

## PatchKind

The state of a `Patch<T>`, held in [`kind`](<https://docs.dhtmlx.com/planning-engine/java/api/changes/patch.md#kind>).

```java
package org.dhtmlx.plen;

public enum PatchKind { MISSING, NULL, VALUE }
```

| Value | Description |
|---|---|
| `MISSING` | The field isn't touched; the current value stays. The default. |
| `NULL` | The field is cleared or reset to its default. |
| `VALUE` | The field gets the carried value. |

## Example

```java
import org.dhtmlx.plen.*;

public class PatchExample {
    public static void main(String[] args) throws Exception {
        TaskUpdate update = new TaskUpdate(Id.num(1))
                .withDuration(Patch.of(3.0))             // set
                .withConstraintDate(Patch.nullValue());  // clear
        // every other field stays Patch.missing()

        System.out.println(update.duration.kind);        // VALUE
        System.out.println(update.progress.isMissing()); // true

        Ref<Double> duration = new Ref<>();
        if (update.duration.tryGetValue(duration)) {
            System.out.println(duration.value);          // 3.0
        }

        System.out.println(update.constraintDate.equals(Patch.nullValue())); // true
    }
}
```

## Related

- [`TaskUpdate`](<https://docs.dhtmlx.com/planning-engine/java/api/changes/task-update.md>) - the update record with the most patch fields
- [`SchedulingChanges`](<https://docs.dhtmlx.com/planning-engine/java/api/changes/scheduling-changes.md>) - the change set the update records go into
- [`Ref<T>`](<https://docs.dhtmlx.com/planning-engine/java/api/support/ref.md>) - the out-parameter holder of `tryGetValue`
- [Records, ids and dates](<https://docs.dhtmlx.com/planning-engine/java/records-ids-and-dates.md#patch-fields>) - working with patch fields
- [Data Updates](<https://docs.dhtmlx.com/planning-engine/java/live-projects/editing-a-project.md#update-records-and-patch>) - update records and `Patch` in a live project