DHTMLX Planning Engine Documentation

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, LinkUpdate, ResourceUpdate and AssignmentUpdate 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#

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#

public final PatchKind kind;

Which of the three states the patch is in. See PatchKind.

Static methods#

missing#

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#

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#

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#

public boolean isMissing()
public boolean isNull()
public boolean hasValue()

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

value#

public T value()

Returns the carried value.

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

tryGetValue#

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> Out-parameter holder. Create it with new Ref<>().

equals, hashCode#

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

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.

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#

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
    }
}