CODEWITHSUNDEEP
javaxml
membersound
membersound

Reputation: 86807

Should list array elements be wrapped in xml representation?

When creating a REST/XML webservice, and showing List objects: should the list elements be wrapped in a list element (eg <persons>), or should the response just list multiple <person> elements?

Example:

@XmlElement
private List<Person> persons;

public class Person {
    private String name;
    private int age;
    //...
}

Nested:

<rsp>
 <persons>
   <person>
     <name />
     <age />
   </person>
   <person>
    ...
   </person>
 </persons>
</rsp>

Flat:

<rsp>
   <person>
     <name />
     <age />
   </person>
   <person>
    ...
   </person>
</rsp>

Upvotes: 5

Views: 2014

Answers (4)

imhotap
imhotap

Reputation: 2490

The XmlElement annotation is from the JAXB 2 specification for representing XML as Java classes/object graphs and vice versa. JAXB 2 binding rules are essentially based on mapping XML Schema definitions to Java classes. Elements that can occur multiple times via the XML Schema maxOccurs="unbounded" attribute, or a maxOccurs value greater than 1 within their containing type are by default represented as a list property (a Java.util.List of element items), or alternatively, and less commonly, as an indexed property with accessors such as getProp(int index) for Prop an element name.

So I would say unless specific requirements dictate otherwise, I would not use wrapper elements for the typical use case you describe. One caveat, though, is that you'll want Java member names in plural form whereas in XML you'll want the singular form. In your example, you'll want to avoid an XML element Name Persons for a Java method signature such as List<Person> getPersons(), and you can use the @XmlElement(Name = Person) annotation to get you an XML element in the singular form instead.

There's a larger discussion behind your question: XML, like SGML (the common superset of XML and HTML), is a text format for representing semistructured data (it was initially designed to supersede HTML, but that didn't work out). As such, the kind of data that SGML/XML was designed for, by definition, isn't represented adequately in a Java component model seeking to tightly map Java classes/objects to markup elements at all. Instead, a DOM representation, or another representation for sequential acccess to markup elements where the document order of elements of different types among each other is honored, is arguably a more natural fit. In fact, JAXB 1 had more complex mapping rules which could roundtrip document order of elements. But it turned out that for the comparatively simple data-oriented use cases which XML is used for most of the time this wasn't helpful. Hence, JAXB 2 was designed to more easily capture data-oriented use case like yours.

Upvotes: 1

Mark
Mark

Reputation: 4455

When it comes right down to it, I would go through a few well known RESTFUL interfaces ( or at least interfaces used in your services environment ). I would try to be as consistent as possible so your ecosystem of developers will have an intuitive start to understanding the API that you have designed.

From a technical perspective, I suspect that the wrapping of the element can make parsing or application coding more efficient. Of course, there are the benefits of being able to provide attributes for the list itself (as tanyehzheng has already stated ).

Personally, I prefer the wrapped XML as well, but not for any technical reasons. In XML editors/viewers, the element can be collapsed and thus the response can be made more terse for humans.

Upvotes: 2

Gautam
Gautam

Reputation: 564

It'll be apt to wrap the list in a parent element like persons. Two reasons for doing that:

As pointed out by @tanyehzheng, it allows adding attributes to the list like size.

With a wrapped style, it allows your response object <rsp> to be extensible to include other objects, in a cleaner fashion. Say tomorrow we wish to add data like below (this is just an example)

<rsp>
   <persons>
      <person>
       <name />
       <age />
      </person>
      <person>
       ...
      </person>
  </persons>
  <performanceInfo>
    <processingTime>122</processingTime>
  </performanceInfo>
</rsp>

Upvotes: 4

tanyehzheng
tanyehzheng

Reputation: 2221

I would have wrapped it nested. Because it's more natural to add metadata like the size of the list

<persons size="42">
  <person>
    ...
  </person>
  <person>
    ...
  </person>
  .
  .
  .
<persons>

Upvotes: 4

Related Questions