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


# Wire

Static JSON entry points. Each operation takes its inputs as JSON text, runs the matching engine call and returns a JSON envelope string: `{"ok":true,"result":…}` on success, `{"ok":false,"error":…}` when the engine reports an error. The per-project operations take a typed [`Project`](<https://docs.dhtmlx.com/planning-engine/java/api/project/project.md>), so typed and JSON calls can work on the same instance. For a project used only through JSON, [`JsonProject`](<https://docs.dhtmlx.com/planning-engine/java/api/json/json-project.md>) wraps the same operations around a project it owns.

`Wire` has a private constructor and only static methods.

## Declaration

```java
package org.dhtmlx.plen;

public final class Wire {
  public static String schedule(String data, String options)
  public static Project newProject(String options)

  public static String solve(Project project, String data, String options)
  public static String preview(Project project, String changes, String options)
  public static String analyze(Project project, String data, String options)
  public static String apply(Project project, String changes)
  public static String level(Project project, String options)
  public static String evaluate(Project project, String candidates, String options)
  public static String suggestAssignments(Project project, String slots, String options)
  public static String loadProfile(Project project, String options)
  public static String slots(Project project, String pool, String requirements)

  public static String envelopeText(Supplier<?> run)
  public static Object envelope(Supplier<?> run)
  public static String resultText(Object value)
  public static String errorText(PlenException e)
  public static Object error(PlenException e)
}
```

`Supplier` is `java.util.function.Supplier`. Every method is synchronous.

## Envelopes and errors

Every operation that returns `String` returns an envelope. Input fields use the snake_case names and the result fields follow the JSON contract described in [JSON API](<https://docs.dhtmlx.com/planning-engine/java/api/json/overview.md>).

```json
{"ok":true,"result":{"baselineId":"1-c9a569b56aab2c77","conflicts":[],"converged":true,"cycles":[],"notes":[],"updates":[…]}}
```

```json
{"error":{"code":null,"kind":"parse","message":"missing field `tasks`","path":null},"ok":false}
```

| Error field | Value |
|---|---|
| `kind` | `"parse"` for an [`InputException`](<https://docs.dhtmlx.com/planning-engine/java/api/errors/input-exception.md>) of kind `PARSE`, `"validation"` for kind `VALIDATION`, `"project"` for a [`ProjectException`](<https://docs.dhtmlx.com/planning-engine/java/api/errors/project-exception.md>). |
| `message` | `getMessage()` of the exception. For a `ProjectException`, the kebab-case code. |
| `path` | `InputException.path`, in wire spelling (`tasks[3].constraint_date`). `null` for parse errors and project errors. |
| `code` | The kebab-case [`ProjectError`](<https://docs.dhtmlx.com/planning-engine/java/api/errors/project-exception.md>) (`"no-baseline"`, `"stale-baseline"`, `"needs-resync"`). `null` for input errors. |

Only a [`PlenException`](<https://docs.dhtmlx.com/planning-engine/java/api/errors/plen-exception.md>) becomes an error envelope. Decoding failures, including malformed JSON, duplicate keys, a missing required field and a JSON `null` document, are `InputException`s and come back as envelopes. Other exceptions propagate:

- `NullPointerException` for a `null` `project` or a `null` JSON string. Only the `data` argument of `solve` and `analyze` accepts `null`
- `IllegalStateException` when the result holds a NaN or infinite number, from [`Encode.text`](<https://docs.dhtmlx.com/planning-engine/java/api/json/encode.md#text>)
- `OutOfMemoryError` from `slots` with very large requirement counts

Results that carry their own problems, such as rejected operations in an [`ApplyReport`](<https://docs.dhtmlx.com/planning-engine/java/api/changes/apply-report.md>) or conflicts in a [`ScheduleResult`](<https://docs.dhtmlx.com/planning-engine/java/api/results/schedule-result.md>), are success envelopes.

## Static methods

### schedule

```java
public static String schedule(String data, String options)
```

Decodes the project data and options, runs [`Engine.schedule`](<https://docs.dhtmlx.com/planning-engine/java/api/engine-schedule.md>) and returns the envelope. Stateless: nothing is kept between calls.

| Name | Type | Description |
|---|---|---|
| `data` | `String` | [`ProjectData`](<https://docs.dhtmlx.com/planning-engine/java/api/data/project-data.md>) JSON. |
| `options` | `String` | [`SolveOptions`](<https://docs.dhtmlx.com/planning-engine/java/api/project/solve-options.md>) JSON. Pass `"{}"` for the defaults. |

**Returns** an envelope with a [`ScheduleResult`](<https://docs.dhtmlx.com/planning-engine/java/api/results/schedule-result.md>).

### newProject

```java
public static Project newProject(String options)
```

Decodes the options and creates an empty, unsolved [`Project`](<https://docs.dhtmlx.com/planning-engine/java/api/project/project.md>).

| Name | Type | Description |
|---|---|---|
| `options` | `String` | [`ProjectOptions`](<https://docs.dhtmlx.com/planning-engine/java/api/project/project-options.md>) JSON, such as `{"validation":"repair"}`. Pass `"{}"` for strict validation. |

**Returns** the new `Project`, not an envelope.

**Errors** throws [`InputException`](<https://docs.dhtmlx.com/planning-engine/java/api/errors/input-exception.md>) when the options JSON doesn't decode.

### solve

```java
public static String solve(Project project, String data, String options)
```

Runs [`Project#solve`](<https://docs.dhtmlx.com/planning-engine/java/api/project-solve.md>) on `project`.

| Name | Type | Description |
|---|---|---|
| `project` | [`Project`](<https://docs.dhtmlx.com/planning-engine/java/api/project/project.md>) | The project to solve. |
| `data` | `String` | [`ProjectData`](<https://docs.dhtmlx.com/planning-engine/java/api/data/project-data.md>) JSON. Nullable; `null` re-solves the current state. |
| `options` | `String` | [`SolveOptions`](<https://docs.dhtmlx.com/planning-engine/java/api/project/solve-options.md>) JSON. |

**Returns** an envelope with a [`ScheduleResult`](<https://docs.dhtmlx.com/planning-engine/java/api/results/schedule-result.md>).

### preview

```java
public static String preview(Project project, String changes, String options)
```

Runs [`Project#preview`](<https://docs.dhtmlx.com/planning-engine/java/api/project-preview.md>) on `project`.

| Name | Type | Description |
|---|---|---|
| `project` | [`Project`](<https://docs.dhtmlx.com/planning-engine/java/api/project/project.md>) | A solved project. |
| `changes` | `String` | [`SchedulingChanges`](<https://docs.dhtmlx.com/planning-engine/java/api/changes/scheduling-changes.md>) JSON. |
| `options` | `String` | [`PreviewOptions`](<https://docs.dhtmlx.com/planning-engine/java/api/project/preview-options.md>) JSON. |

**Returns** an envelope with a [`ScheduleResult`](<https://docs.dhtmlx.com/planning-engine/java/api/results/schedule-result.md>).

### analyze

```java
public static String analyze(Project project, String data, String options)
```

Runs [`Project#analyze`](<https://docs.dhtmlx.com/planning-engine/java/api/project-analyze.md>) on `project`.

| Name | Type | Description |
|---|---|---|
| `project` | [`Project`](<https://docs.dhtmlx.com/planning-engine/java/api/project/project.md>) | The project to analyze. |
| `data` | `String` | [`ProjectData`](<https://docs.dhtmlx.com/planning-engine/java/api/data/project-data.md>) JSON with the dates to analyze. Nullable; `null` uses the project's current dates. |
| `options` | `String` | [`AnalyzeOptions`](<https://docs.dhtmlx.com/planning-engine/java/api/project/analyze-options.md>) JSON. |

**Returns** an envelope with a [`ScheduleResult`](<https://docs.dhtmlx.com/planning-engine/java/api/results/schedule-result.md>).

### apply

```java
public static String apply(Project project, String changes)
```

Runs [`Project#apply`](<https://docs.dhtmlx.com/planning-engine/java/api/project-apply.md>) on `project`.

| Name | Type | Description |
|---|---|---|
| `project` | [`Project`](<https://docs.dhtmlx.com/planning-engine/java/api/project/project.md>) | The project to edit. |
| `changes` | `String` | [`SchedulingChanges`](<https://docs.dhtmlx.com/planning-engine/java/api/changes/scheduling-changes.md>) JSON. |

**Returns** an envelope with an [`ApplyReport`](<https://docs.dhtmlx.com/planning-engine/java/api/changes/apply-report.md>).

### level

```java
public static String level(Project project, String options)
```

Runs [`Project#level`](<https://docs.dhtmlx.com/planning-engine/java/api/project-level.md>) on `project`.

| Name | Type | Description |
|---|---|---|
| `project` | [`Project`](<https://docs.dhtmlx.com/planning-engine/java/api/project/project.md>) | The project to level. |
| `options` | `String` | [`LevelingOptions`](<https://docs.dhtmlx.com/planning-engine/java/api/resources/leveling-options.md>) JSON. |

**Returns** an envelope with a [`LevelingResult`](<https://docs.dhtmlx.com/planning-engine/java/api/resources/leveling-result.md>).

### evaluate

```java
public static String evaluate(Project project, String candidates, String options)
```

Runs [`Project#evaluate`](<https://docs.dhtmlx.com/planning-engine/java/api/project-evaluate.md>) on `project`.

| Name | Type | Description |
|---|---|---|
| `project` | [`Project`](<https://docs.dhtmlx.com/planning-engine/java/api/project/project.md>) | A solved project. |
| `candidates` | `String` | JSON array of [`Candidate`](<https://docs.dhtmlx.com/planning-engine/java/api/evaluate/candidate.md>) objects. A `null` element is a parse error. |
| `options` | `String` | [`EvaluateOptions`](<https://docs.dhtmlx.com/planning-engine/java/api/evaluate/evaluate-options.md>) JSON. |

**Returns** an envelope with an [`EvaluateResult`](<https://docs.dhtmlx.com/planning-engine/java/api/evaluate/evaluate-result.md>).

### suggestAssignments

```java
public static String suggestAssignments(Project project, String slots, String options)
```

Runs [`Project#suggestAssignments`](<https://docs.dhtmlx.com/planning-engine/java/api/project-suggest-assignments.md>) on `project`.

| Name | Type | Description |
|---|---|---|
| `project` | [`Project`](<https://docs.dhtmlx.com/planning-engine/java/api/project/project.md>) | A solved project. |
| `slots` | `String` | JSON array of [`Slot`](<https://docs.dhtmlx.com/planning-engine/java/api/suggest/slot.md>) objects. A `null` element is a parse error. |
| `options` | `String` | [`SuggestOptions`](<https://docs.dhtmlx.com/planning-engine/java/api/suggest/suggest-options.md>) JSON. |

**Returns** an envelope with a [`SuggestResult`](<https://docs.dhtmlx.com/planning-engine/java/api/suggest/suggest-result.md>).

### loadProfile

```java
public static String loadProfile(Project project, String options)
```

Runs [`Project#loadProfile`](<https://docs.dhtmlx.com/planning-engine/java/api/project-load-profile.md>) on `project`.

| Name | Type | Description |
|---|---|---|
| `project` | [`Project`](<https://docs.dhtmlx.com/planning-engine/java/api/project/project.md>) | A solved project. |
| `options` | `String` | [`LoadProfileOptions`](<https://docs.dhtmlx.com/planning-engine/java/api/resources/load-profile-options.md>) JSON. |

**Returns** an envelope with a [`LoadProfile`](<https://docs.dhtmlx.com/planning-engine/java/api/resources/load-profile.md>).

### slots

```java
public static String slots(Project project, String pool, String requirements)
```

Runs [`SkillLayer.slots`](<https://docs.dhtmlx.com/planning-engine/java/api/skill-layer-slots.md>) on `project`. A [`MatchException`](<https://docs.dhtmlx.com/planning-engine/java/api/errors/match-exception.md>) is converted with `toPlenException()`, so invalid pools and requirements come back as error envelopes.

| Name | Type | Description |
|---|---|---|
| `project` | [`Project`](<https://docs.dhtmlx.com/planning-engine/java/api/project/project.md>) | A solved project. |
| `pool` | `String` | [`Pool`](<https://docs.dhtmlx.com/planning-engine/java/api/assign/pool.md>) JSON. |
| `requirements` | `String` | JSON array of [`Requirement`](<https://docs.dhtmlx.com/planning-engine/java/api/assign/requirement.md>) objects. A `null` element is a parse error. |

**Returns** an envelope with the array of [`Slot`](<https://docs.dhtmlx.com/planning-engine/java/api/suggest/slot.md>) objects.

### envelopeText

```java
public static String envelopeText(Supplier<?> run)
```

Calls `run`, encodes its return value with [`Encode.text`](<https://docs.dhtmlx.com/planning-engine/java/api/json/encode.md#text>) and wraps it in a success envelope. A `PlenException` thrown by `run` becomes an error envelope, as from [`errorText`](<https://docs.dhtmlx.com/planning-engine/java/api/json/wire.md#errortext>). Every other exception propagates.

| Name | Type | Description |
|---|---|---|
| `run` | `Supplier<?>` | The call to run. It must return a result type that `Encode.text` accepts, such as `ScheduleResult` or `ApplyReport`. |

**Returns** the envelope as JSON text.

**Errors** `UnsupportedOperationException` when `Encode.text` has no encoder for the returned value; `IllegalStateException` when the value holds a NaN or infinite number.

### envelope

```java
public static Object envelope(Supplier<?> run)
```

Same as [`envelopeText`](<https://docs.dhtmlx.com/planning-engine/java/api/json/wire.md#envelopetext>), parsed with [`Json.parse`](<https://docs.dhtmlx.com/planning-engine/java/api/json/json.md#parse>).

**Returns** the envelope as a JSON tree: `Map<String, Object>`, `List<Object>`, `String`, `Boolean`, `null`, and numbers as `Long` or `Double`. Read numbers as `Number`.

### resultText

```java
public static String resultText(Object value)
```

Wraps an already computed typed result in a success envelope.

| Name | Type | Description |
|---|---|---|
| `value` | `Object` | A result type that [`Encode.text`](<https://docs.dhtmlx.com/planning-engine/java/api/json/encode.md#text>) accepts. |

**Returns** `{"ok":true,"result":…}` as JSON text.

**Errors** same as [`envelopeText`](<https://docs.dhtmlx.com/planning-engine/java/api/json/wire.md#envelopetext>) for the encoding step.

### errorText

```java
public static String errorText(PlenException e)
```

Builds the error envelope for an engine exception. Keys are sorted: `{"error":{"code":…,"kind":…,"message":…,"path":…},"ok":false}`. The field values are listed in [Envelopes and errors](<https://docs.dhtmlx.com/planning-engine/java/api/json/wire.md#envelopes-and-errors>).

| Name | Type | Description |
|---|---|---|
| `e` | [`PlenException`](<https://docs.dhtmlx.com/planning-engine/java/api/errors/plen-exception.md>) | An `InputException` or a `ProjectException`. |

**Returns** the error envelope as JSON text.

### error

```java
public static Object error(PlenException e)
```

Same as [`errorText`](<https://docs.dhtmlx.com/planning-engine/java/api/json/wire.md#errortext>), parsed with [`Json.parse`](<https://docs.dhtmlx.com/planning-engine/java/api/json/json.md#parse>).

**Returns** the error envelope as a JSON tree.

## Example

Load and solve a project from JSON, edit it through the typed API, then read the result back as JSON:

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

public class WireExample {
  public static void main(String[] args) throws Exception {
    Project project = Wire.newProject("{}");

    String data = "{\"tasks\":["
        + "{\"id\":\"a\",\"start_date\":\"2026-03-02\",\"duration\":2},"
        + "{\"id\":\"b\",\"start_date\":\"2026-03-02\",\"duration\":1}],"
        + "\"links\":[{\"id\":\"ab\",\"source\":\"a\",\"target\":\"b\"}]}";
    System.out.println(Wire.solve(project, data, "{\"includeUnchanged\":true}"));

    // typed edit on the same project
    project.apply(Decode.fromJson(
        "{\"tasks\":{\"update\":[{\"id\":\"a\",\"duration\":3}]}}",
        SchedulingChanges.class));

    // typed call, JSON envelope out
    System.out.println(Wire.envelopeText(() -> project.solve(null, new SolveOptions())));

    // engine errors come back as envelopes
    System.out.println(Wire.preview(project, "{\"baselineId\":\"old\"}", "{}"));
  }
}
```

The last call prints:

```json
{"error":{"code":"stale-baseline","kind":"project","message":"stale-baseline","path":null},"ok":false}
```

## Related

- [`JsonProject`](<https://docs.dhtmlx.com/planning-engine/java/api/json/json-project.md>) - the same operations on a project used only through JSON
- [`Project`](<https://docs.dhtmlx.com/planning-engine/java/api/project/project.md>) - the typed project the operations run on
- [`Encode`](<https://docs.dhtmlx.com/planning-engine/java/api/json/encode.md>) - writes the `result` of a success envelope
- [`Decode`](<https://docs.dhtmlx.com/planning-engine/java/api/json/decode.md>) - decodes the input JSON into typed records
- [Exchange JSON with a client](<https://docs.dhtmlx.com/planning-engine/java/how-to/exchange-json-with-a-client.md#read-the-envelope>) - reading envelopes and mixing typed and JSON calls