Working with Tree Model Nodes in Jackson

1. 概述

本教程将重点介绍在 Jackson 中使用 树模型节点。

我们将使用 JsonNode 进行各种转换以及添加、修改和删除节点。

2. 创建节点

创建节点的第一个步骤是使用默认构造函数实例化一个 ObjectMapper 对象

ObjectMapper mapper = new ObjectMapper();

由于创建 ObjectMapper 对象代价较高，建议我们重用同一个对象进行多次操作。

接下来，一旦我们有了 ObjectMapper，就有三种不同的方法可以创建树节点。

2.1. 从头开始构建节点

这是从无到有创建节点的最常见方法

JsonNode node = mapper.createObjectNode();

或者，我们也可以通过 JsonNodeFactory 创建节点

JsonNode node = JsonNodeFactory.instance.objectNode();

2.2. 从 JSON 来源解析

此方法在 Jackson – Marshall String to JsonNode 文章中得到了很好的介绍。请参阅它以获取更多信息。

2.3. 从对象转换

可以通过调用 ObjectMapper 上的 valueToTree(Object fromValue) 方法将节点从 Java 对象转换而来

JsonNode node = mapper.valueToTree(fromValue);

convertValue API 在这里也很有帮助

JsonNode node = mapper.convertValue(fromValue, JsonNode.class);

让我们看看它在实践中是如何工作的。

假设我们有一个名为 NodeBean 的类

public class NodeBean {
    private int id;
    private String name;

    public NodeBean() {
    }

    public NodeBean(int id, String name) {
        this.id = id;
        this.name = name;
    }

    // standard getters and setters
}

让我们编写一个测试来确保转换发生正确

@Test
public void givenAnObject_whenConvertingIntoNode_thenCorrect() {
    NodeBean fromValue = new NodeBean(2016, "baeldung.com");

    JsonNode node = mapper.valueToTree(fromValue);

    assertEquals(2016, node.get("id").intValue());
    assertEquals("baeldung.com", node.get("name").textValue());
}

3. 转换节点

3.1. 写入为 JSON

这是将树节点转换为 JSON 字符串的基本方法，其中目标可以是 File、OutputStream 或 Writer

mapper.writeValue(destination, node);

通过重用第 2.3 节中声明的类 NodeBean，一个测试确保此方法按预期工作

final String pathToTestFile = "node_to_json_test.json";

@Test
public void givenANode_whenModifyingIt_thenCorrect() throws IOException {
    String newString = "{\"nick\": \"cowtowncoder\"}";
    JsonNode newNode = mapper.readTree(newString);

    JsonNode rootNode = ExampleStructure.getExampleRoot();
    ((ObjectNode) rootNode).set("name", newNode);

    assertFalse(rootNode.path("name").path("nick").isMissingNode());
    assertEquals("cowtowncoder", rootNode.path("name").path("nick").textValue());
}

3.2. 转换为对象

将 JsonNode 转换为 Java 对象的最佳方法是 treeToValue API

NodeBean toValue = mapper.treeToValue(node, NodeBean.class);

这在功能上等同于以下代码

NodeBean toValue = mapper.convertValue(node, NodeBean.class)

我们也可以通过令牌流来完成

JsonParser parser = mapper.treeAsTokens(node);
NodeBean toValue = mapper.readValue(parser, NodeBean.class);

最后，让我们实现一个测试来验证转换过程

@Test
public void givenANode_whenConvertingIntoAnObject_thenCorrect()
  throws JsonProcessingException {
    JsonNode node = mapper.createObjectNode();
    ((ObjectNode) node).put("id", 2016);
    ((ObjectNode) node).put("name", "baeldung.com");

    NodeBean toValue = mapper.treeToValue(node, NodeBean.class);

    assertEquals(2016, toValue.getId());
    assertEquals("baeldung.com", toValue.getName());
}

4. 操作树节点

我们将使用以下 JSON 元素，包含在一个名为 example.json 的文件中，作为要执行操作的基础结构

{
    "name": 
        {
            "first": "Tatu",
            "last": "Saloranta"
        },

    "title": "Jackson founder",
    "company": "FasterXML"
}

此 JSON 文件位于类路径上，被解析为一个模型树

public class ExampleStructure {
    private static ObjectMapper mapper = new ObjectMapper();

    static JsonNode getExampleRoot() throws IOException {
        InputStream exampleInput = 
          ExampleStructure.class.getClassLoader()
          .getResourceAsStream("example.json");
        
        JsonNode rootNode = mapper.readTree(exampleInput);
        return rootNode;
    }
}

请注意，树的根将在以下子节中说明节点操作时使用。

4.1. 查找节点

在使用任何节点之前，我们需要做的第一件事是找到它并将其分配给一个变量。

如果我们事先知道节点的路径，那么很容易做到。

假设我们想要一个名为 last 的节点，它位于 name 节点之下

JsonNode locatedNode = rootNode.path("name").path("last");

或者，也可以使用 get 或 with API 代替 path。

如果路径未知，搜索当然会变得更复杂和迭代。

我们可以在 第 5 节 – 迭代节点 中看到遍历所有节点的示例。

4.2. 添加新节点

可以将节点作为另一个节点的子节点添加

ObjectNode newNode = ((ObjectNode) locatedNode).put(fieldName, value);

可以使用许多重载的 put 变体来添加不同值类型的新节点。

还有许多其他类似的方法可用，包括 putArray、putObject、PutPOJO、putRawValue 和 putNull。

最后，让我们看一个示例，我们将整个结构添加到树的根节点

"address":
{
    "city": "Seattle",
    "state": "Washington",
    "country": "United States"
}

这是完整的测试，经过所有这些操作并验证结果

@Test
public void givenANode_whenAddingIntoATree_thenCorrect() throws IOException {
    JsonNode rootNode = ExampleStructure.getExampleRoot();
    ObjectNode addedNode = ((ObjectNode) rootNode).putObject("address");
    addedNode
      .put("city", "Seattle")
      .put("state", "Washington")
      .put("country", "United States");

    assertFalse(rootNode.path("address").isMissingNode());
    
    assertEquals("Seattle", rootNode.path("address").path("city").textValue());
    assertEquals("Washington", rootNode.path("address").path("state").textValue());
    assertEquals(
      "United States", rootNode.path("address").path("country").textValue();
}

4.3. 编辑节点

可以通过调用 set(String fieldName, JsonNode value) 方法修改 ObjectNode 实例

JsonNode locatedNode = locatedNode.set(fieldName, value);

通过使用相同类型的对象上的 replace 或 setAll 方法可以获得类似的结果。

为了验证该方法是否按预期工作，我们将更改根节点下字段 name 的值，从包含 first 和 last 对象的结构更改为仅包含 nick 字段的结构，并在测试中进行验证。

@Test
public void givenANode_whenModifyingIt_thenCorrect() throws IOException {
    String newString = "{\"nick\": \"cowtowncoder\"}";
    JsonNode newNode = mapper.readTree(newString);

    JsonNode rootNode = ExampleStructure.getExampleRoot();
    ((ObjectNode) rootNode).set("name", newNode);

    assertFalse(rootNode.path("name").path("nick").isMissingNode());
    assertEquals("cowtowncoder", rootNode.path("name").path("nick").textValue());
}

4.4. 移除节点

可以通过调用其父节点上的 remove(String fieldName) API 来移除节点。

JsonNode removedNode = locatedNode.remove(fieldName);

为了同时移除多个节点，我们可以调用一个重载的方法，该方法参数类型为 Collection<String>，它返回父节点而不是要移除的节点。

ObjectNode locatedNode = locatedNode.remove(fieldNames);

在想要删除给定节点的所有子节点这种极端情况下，removeAll API 会派上用场。

以下测试将重点关注上述第一种方法，这是最常见的情况。

@Test
public void givenANode_whenRemovingFromATree_thenCorrect() throws IOException {
    JsonNode rootNode = ExampleStructure.getExampleRoot();
    ((ObjectNode) rootNode).remove("company");

    assertTrue(rootNode.path("company").isMissingNode());
}

5. 遍历节点

让我们遍历 JSON 文档中的所有节点，并将它们重新格式化为 YAML。

JSON 有三种类型的节点，分别是 Value（值）、Object（对象）和 Array（数组）。

因此，让我们通过添加一个 Array 来确保我们的示例数据包含所有三种不同的类型。

{
    "name": 
        {
            "first": "Tatu",
            "last": "Saloranta"
        },

    "title": "Jackson founder",
    "company": "FasterXML",
    "pets" : [
        {
            "type": "dog",
            "number": 1
        },
        {
            "type": "fish",
            "number": 50
        }
    ]
}

现在让我们看看我们想要生成的 YAML。

name: 
  first: Tatu
  last: Saloranta
title: Jackson founder
company: FasterXML
pets: 
- type: dog
  number: 1
- type: fish
  number: 50

我们知道 JSON 节点具有分层树结构。 因此，遍历整个 JSON 文档最简单的方法是从顶部开始，然后通过所有子节点向下工作。

我们将把根节点传递给一个递归方法。 然后，该方法将使用提供的节点的每个子节点调用自身。

5.1. 测试遍历

我们将首先创建一个简单的测试，以检查我们是否可以成功地将 JSON 转换为 YAML。

我们的测试将 JSON 文档的根节点提供给我们的 toYaml 方法，并断言返回的值是我们期望的值。

@Test
public void givenANodeTree_whenIteratingSubNodes_thenWeFindExpected() throws IOException {
    JsonNode rootNode = ExampleStructure.getExampleRoot();
    
    String yaml = onTest.toYaml(rootNode);

    assertEquals(expectedYaml, yaml); 
}

public String toYaml(JsonNode root) {
    StringBuilder yaml = new StringBuilder(); 
    processNode(root, yaml, 0); 
    return yaml.toString(); }
}

5.2. 处理不同类型的节点

我们需要略微不同地处理不同类型的节点。

我们将在我们的 processNode 方法中执行此操作。

private void processNode(JsonNode jsonNode, StringBuilder yaml, int depth) {
    if (jsonNode.isValueNode()) {
        yaml.append(jsonNode.asText());
    }
    else if (jsonNode.isArray()) {
        for (JsonNode arrayItem : jsonNode) {
            appendNodeToYaml(arrayItem, yaml, depth, true);
        }
    }
    else if (jsonNode.isObject()) {
        appendNodeToYaml(jsonNode, yaml, depth, false);
    }
}

首先，让我们考虑一个 Value 节点。 我们只需调用节点的 asText 方法来获取值的 String 表示形式。

接下来，让我们看一下 Array 节点。 Array 节点内的每个项目本身都是一个 JsonNode，因此我们遍历 Array 并将每个节点传递给 appendNodeToYaml 方法。 我们还需要知道这些节点是数组的一部分。

不幸的是，节点本身不包含任何表明这一点的内容，因此我们将一个标志传递给我们的 appendNodeToYaml 方法。

最后，我们想要遍历每个 Object 节点的子节点。 一种选择是使用 JsonNode.elements。

但是，我们无法从元素确定字段名，因为它只包含字段值。

Object  {"first": "Tatu", "last": "Saloranta"}
Value  "Jackson Founder"
Value  "FasterXML"
Array  [{"type": "dog", "number": 1},{"type": "fish", "number": 50}]

相反，我们将使用 JsonNode.fields，因为它使我们可以访问字段名和值。

Key="name", Value=Object  {"first": "Tatu", "last": "Saloranta"}
Key="title", Value=Value  "Jackson Founder"
Key="company", Value=Value  "FasterXML"
Key="pets", Value=Array  [{"type": "dog", "number": 1},{"type": "fish", "number": 50}]

对于每个字段，我们将字段名添加到输出中，然后通过将其传递给 processNode 方法来处理该值作为子节点。

private void appendNodeToYaml(
  JsonNode node, StringBuilder yaml, int depth, boolean isArrayItem) {
    Iterator<Entry<String, JsonNode>> fields = node.fields();
    boolean isFirst = true;
    while (fields.hasNext()) {
        Entry<String, JsonNode> jsonField = fields.next();
        addFieldNameToYaml(yaml, jsonField.getKey(), depth, isArrayItem && isFirst);
        processNode(jsonField.getValue(), yaml, depth+1);
        isFirst = false;
    }
        
}

我们无法从节点判断它有多少祖先。

因此，我们将一个名为 depth 的字段传递给 processNode 方法来跟踪这一点，并且每次获得子节点时都会增加此值，以便我们可以正确地缩进 YAML 输出中的字段。

private void addFieldNameToYaml(
  StringBuilder yaml, String fieldName, int depth, boolean isFirstInArray) {
    if (yaml.length()>0) {
        yaml.append("\n");
        int requiredDepth = (isFirstInArray) ? depth-1 : depth;
        for(int i = 0; i < requiredDepth; i++) {
            yaml.append("  ");
        }
        if (isFirstInArray) {
            yaml.append("- ");
        }
    }
    yaml.append(fieldName);
    yaml.append(": ");
}

现在我们已经准备好所有代码来遍历节点并生成 YAML 输出，我们可以运行我们的测试来证明它有效。

6. 结论

本文涵盖了在使用 Jackson 处理树模型时的常用 API 和场景。