Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 1.0-pr
    • Fix Version/s: 1.0-pr
    • Labels:
      None

      Description

      Feedback from Mark Reinhold
      --------------------------------------
      The EDR javadoc for JsonObject contains this builder-pattern example:

          JsonObject object = new JsonBuilder()
              .beginObject()
                  .add("firstName", "John")
                  .add("lastName", "Smith")
                  .add("age", 25)
                  .beginObject("address")
                      .add("streetAddress", "21 2nd Street")
                      .add("city", "New York")
                      .add("state", "NY")
                      .add("postalCode", "10021")
                  .endObject()
                  .beginArray("phoneNumber")
                      .beginObject()
                          .add("type", "home")
                          .add("number", "212 555-1234")
                      .endObject()
                      .beginObject()
                          .add("type", "home")
                          .add("number", "646 555-4567")
                      .endObject()
                  .endArray()
              .endObject()
          .build();
      

      One problem with this style is that the structure of the object being
      constructed is not reflected in the syntax of the expression. A reader
      must visually scan for "begin" and "end" methods in order to understand
      the resulting object structure, or even just to indent the code.

      Here's a variant of the above example written against a (hypothetical)
      alternative API:

          JsonObject value = new JsonObjectBuilder()
              .add("firstName", "John")
              .add("lastName", "Smith")
              .add("age", 25)
              .add("address", new JsonObjectBuilder()
                   .add("streetAddress", "21 2nd Street")
                   .add("city", "New York")
                   .add("state", "NY")
                   .add("postalCode", "10021"))
              .add("phoneNumber", new JsonArrayBuilder()
                   .add(new JsonObjectBuilder()
                        .add("type", "home")
                        .add("number", "212 555-1234"))
                   .add(new JsonObjectBuilder()
                        .add("type", "home")
                        .add("number", "646 555-4567")))
              .build();
      

      Note how the structure of the resulting object is obvious from the
      structure of the expression, which (by the way) is indented correctly
      (at least by Emacs) without any manual effort at all. You also don't
      need the "end" methods.

      Have you considered a design that would support this style? I think
      it's much more readable.
      --------------------------

        Activity

        jitu created issue -
        jitu made changes -
        Field Original Value New Value
        Description Feedback from Mark Reinhold
        --------------------------------------
        The EDR javadoc for JsonObject contains this builder-pattern example:

            JsonObject object = new JsonBuilder()
                .beginObject()
                    .add("firstName", "John")
                    .add("lastName", "Smith")
                    .add("age", 25)
                    .beginObject("address")
                        .add("streetAddress", "21 2nd Street")
                        .add("city", "New York")
                        .add("state", "NY")
                        .add("postalCode", "10021")
                    .endObject()
                    .beginArray("phoneNumber")
                        .beginObject()
                            .add("type", "home")
                            .add("number", "212 555-1234")
                        .endObject()
                        .beginObject()
                            .add("type", "home")
                            .add("number", "646 555-4567")
                        .endObject()
                    .endArray()
                .endObject()
            .build();

        One problem with this style is that the structure of the object being
        constructed is not reflected in the syntax of the expression. A reader
        must visually scan for "begin" and "end" methods in order to understand
        the resulting object structure, or even just to indent the code.

        Here's a variant of the above example written against a (hypothetical)
        alternative API:

            JsonObject value = new JsonObjectBuilder()
                .add("firstName", "John")
                .add("lastName", "Smith")
                .add("age", 25)
                .add("address", new JsonObjectBuilder()
                     .add("streetAddress", "21 2nd Street")
                     .add("city", "New York")
                     .add("state", "NY")
                     .add("postalCode", "10021"))
                .add("phoneNumber", new JsonArrayBuilder()
                     .add(new JsonObjectBuilder()
                          .add("type", "home")
                          .add("number", "212 555-1234"))
                     .add(new JsonObjectBuilder()
                          .add("type", "home")
                          .add("number", "646 555-4567")))
                .build();

        Note how the structure of the resulting object is obvious from the
        structure of the expression, which (by the way) is indented correctly
        (at least by Emacs) without any manual effort at all. You also don't
        need the "end" methods.

        Have you considered a design that would support this style? I think
        it's much more readable.
        --------------------------
        Feedback from Mark Reinhold
        --------------------------------------
        The EDR javadoc for JsonObject contains this builder-pattern example:
        {code}
            JsonObject object = new JsonBuilder()
                .beginObject()
                    .add("firstName", "John")
                    .add("lastName", "Smith")
                    .add("age", 25)
                    .beginObject("address")
                        .add("streetAddress", "21 2nd Street")
                        .add("city", "New York")
                        .add("state", "NY")
                        .add("postalCode", "10021")
                    .endObject()
                    .beginArray("phoneNumber")
                        .beginObject()
                            .add("type", "home")
                            .add("number", "212 555-1234")
                        .endObject()
                        .beginObject()
                            .add("type", "home")
                            .add("number", "646 555-4567")
                        .endObject()
                    .endArray()
                .endObject()
            .build();
        {code}
        One problem with this style is that the structure of the object being
        constructed is not reflected in the syntax of the expression. A reader
        must visually scan for "begin" and "end" methods in order to understand
        the resulting object structure, or even just to indent the code.

        Here's a variant of the above example written against a (hypothetical)
        alternative API:
        {code}
            JsonObject value = new JsonObjectBuilder()
                .add("firstName", "John")
                .add("lastName", "Smith")
                .add("age", 25)
                .add("address", new JsonObjectBuilder()
                     .add("streetAddress", "21 2nd Street")
                     .add("city", "New York")
                     .add("state", "NY")
                     .add("postalCode", "10021"))
                .add("phoneNumber", new JsonArrayBuilder()
                     .add(new JsonObjectBuilder()
                          .add("type", "home")
                          .add("number", "212 555-1234"))
                     .add(new JsonObjectBuilder()
                          .add("type", "home")
                          .add("number", "646 555-4567")))
                .build();
        {code}
        Note how the structure of the resulting object is obvious from the
        structure of the expression, which (by the way) is indented correctly
        (at least by Emacs) without any manual effort at all. You also don't
        need the "end" methods.

        Have you considered a design that would support this style? I think
        it's much more readable.
        --------------------------
        Hide
        jitu added a comment -

        The current design was used by JsonBuilder as well as JsonGenerator, and it is more suitable from streaming generation. Now JsonGenerator is moved to its own abstraction, this proposal is appealing.

        Here are some observations:

        • proposal seems to be simpler
        • here one has to start with JsonObjectBuilder and JsonArrayBuilder. In the current design, one just starts with JsonBuilder always.
        • uses two classes, instead of all the other baggage like JsonBuildable, JsonBuilder
        • avoids the generics trick which end() method is doing.
        • end() is not required
        • The earlier design also works for generating JSON in a streaming fashion. Now(after EDR) JsonGenerator uses its own abstraction, so this seems more suitable now.
        • I think this is also guarantees compile-time safety to the building objects similar to the current one i.e one cannot add JSON array values in objects (name/value pairs)
        • I think we can still add existing JsonArray/JsonObject

        I would like to incorporate the Marc's proposal.

        Show
        jitu added a comment - The current design was used by JsonBuilder as well as JsonGenerator, and it is more suitable from streaming generation. Now JsonGenerator is moved to its own abstraction, this proposal is appealing. Here are some observations: proposal seems to be simpler here one has to start with JsonObjectBuilder and JsonArrayBuilder. In the current design, one just starts with JsonBuilder always. uses two classes, instead of all the other baggage like JsonBuildable, JsonBuilder avoids the generics trick which end() method is doing. end() is not required The earlier design also works for generating JSON in a streaming fashion. Now(after EDR) JsonGenerator uses its own abstraction, so this seems more suitable now. I think this is also guarantees compile-time safety to the building objects similar to the current one i.e one cannot add JSON array values in objects (name/value pairs) I think we can still add existing JsonArray/JsonObject I would like to incorporate the Marc's proposal.
        Hide
        jitu added a comment -

        Incorporating the suggested proposal.

        Show
        jitu added a comment - Incorporating the suggested proposal.
        jitu made changes -
        Status Open [ 1 ] Closed [ 6 ]
        Assignee jitu [ jitu ]
        Resolution Fixed [ 1 ]

          People

          • Assignee:
            jitu
            Reporter:
            jitu
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved: