Accessing Nested Data Structures in Java

Enterprise data structures are not usually flat. More often they are hierarchical, nesting one or more levels deep. For example, an account object might contain a customer object, which might contain an address object, and so on.

Such data structures are often returned by web services. A single call to the server requires less code and incurs less network overhead than multiple calls to retrieve the same information. Often, these data structures are returned as JSON and mapped to strongly typed equivalents such as Java beans on the client side. This works well when modeling the complete server response; however, it can be overkill when only a small subset of the returned data is required.

For example, the sample user service at typicode.com returns a collection of records structured like this:

{
  "id": 1,
  "name": "Leanne Graham",
  "username": "Bret",
  "email": "Sincere@april.biz",
  "address": {
    "street": "Kulas Light",
    "suite": "Apt. 556",
    "city": "Gwenborough",
    "zipcode": "92998-3874",
    "geo": {
      "lat": "-37.3159",
      "lng": "81.1496"
    }
  },
  "phone": "1-770-736-8031 x56442",
  "website": "hildegard.org",
  "company": {
    "name": "Romaguera-Crona",
    "catchPhrase": "Multi-layered client-server neural-net",
    "bs": "harness real-time e-markets"
  }
} 

It would be straightforward to map this content to a bean representation. However, if the caller is only interested in the "catchPhrase" values, for example, it would still require the following class definitions at a minimum:

public static class User {
    private Company company;

    public Company getCompany() {
        return company;
    }

    public void setCompany(Company company) {
        this.company = company;
    }
}

public static class Company {
    private String catchPhrase;

    public String getCatchPhrase() {
        return catchPhrase;
    }

    public void setCatchPhrase(String catchPhrase) {
        this.catchPhrase = catchPhrase;
    }
}

Using HTTP-RPC‘s WebServiceProxy class, the following code could then be used to bind the response data to bean instances, extract the catch-phrase values, and convert them to a JSON list:

URL url = new URL("https://jsonplaceholder.typicode.com/users");

List<User> users = WebServiceProxy.get(url).invoke(BeanAdapter.typeOf(List.class, User.class));

List<String> catchPhrases = users.stream()
    .map(user -> user.getCompany().getCatchPhrase())
    .collect(Collectors.toList());

JSONEncoder jsonEncoder = new JSONEncoder();

jsonEncoder.write(catchPhrases, System.out);

For example:

[
  "Multi-layered client-server neural-net",
  "Proactive didactic contingency",
  "Face to face bifurcated interface",
  "Multi-tiered zero tolerance productivity",
  "User-centric fault-tolerant solution",
  "Synchronised bottom-line interface",
  "Configurable multimedia task-force",
  "Implemented secondary concept",
  "Switchable contextually-based project",
  "Centralized empowering task-force"
]

Alternatively, interfaces could be used in place of the bean types to eliminate some of the boilerplate code:

public interface User {
    Company getCompany();
}

public interface Company {
    String getCatchPhrase();
}

The code for extracting the catch-phrases would be identical to the previous example, and the resulting output would be the same:

URL url = new URL("https://jsonplaceholder.typicode.com/users");

List<User> users = WebServiceProxy.get(url).invoke(BeanAdapter.typeOf(List.class, User.class));

List<String> catchPhrases = users.stream()
    .map(user -> user.getCompany().getCatchPhrase())
    .collect(Collectors.toList());

JSONEncoder jsonEncoder = new JSONEncoder();

jsonEncoder.write(catchPhrases, System.out);

A third option would be to deserialize the "raw" JSON data and access the catch-phrases via successive calls to Map#get():

URL url = new URL("https://jsonplaceholder.typicode.com/users");

List<Map<String, Map<String, ?>>> users = WebServiceProxy.get(url).invoke();

List<String> catchPhrases = users.stream()
    .map(user -> (String)user.get("company").get("catchPhrase"))
    .collect(Collectors.toList());

JSONEncoder jsonEncoder = new JSONEncoder();

jsonEncoder.write(catchPhrases, System.out);

This uses less code than the bean or interface approaches, but still requires the declaration of a moderately complex generic, even for this fairly simple case.

A fourth alternative would be to use the valueAt() method of HTTP-RPC’s Collections class to access the nested values by key path:

URL url = new URL("https://jsonplaceholder.typicode.com/users");

List<?> users = WebServiceProxy.get(url).invoke();

List<String> catchPhrases = users.stream()
    .map(user -> (String)Collections.valueAt(user, "company", "catchPhrase"))
    .collect(Collectors.toList());

JSONEncoder jsonEncoder = new JSONEncoder();

jsonEncoder.write(catchPhrases, System.out);

This approach is the least verbose, as it allows the caller to retrieve the desired data directly, without the need for intermediate types or nested generics.

If a caller needs access to most or all of the data returned by a service, then binding to bean or interface types is probably the most practical solution. However, if access to only a targeted subset of nested data is required (e.g. for lightweight transformation or basic validation), then the generic map or valueOf() approach may be preferable.

For more information, see the project README.