Should I list array elements in an XML representation?

Question

When creating a REST / XML web service and displaying List objects: should the list elements be wrapped in a list element (for example, <persons> ), or if the answer simply displays 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> 

Answer 1

This will be apt to wrap the list in the parent element, e.g. persons . Two reasons for this:

As @tanyehzheng pointed out, it allows you to add attributes to the list as a size.






























Say tomorrow we want to add data as shown below (this is just an example)

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

Answer 2

I would wrap it nested. Since it’s more natural to add metadata like list size

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

Answer 3

When it comes to it, I would consider a few well-known RESTFUL interfaces (or at least the interfaces used in your service environment). I will try to be as consistent as possible so that your ecosystem of developers has an intuitive start to understanding the API that you have developed.

From a technical point of view, I suspect that wrapping an element may make parsing or coding the application more efficient. Of course, there are advantages to being able to provide attributes of the list itself (as tanyehzheng already stated).

Personally, I also prefer packaged XML, but not for any technical reasons. In editors / viewers, the XML element can be collapsed and thus the answer can be more subtle for people.

Answer 4

Annotation XmlElement is a JAXB 2 specification for representing XML as Java classes / objects and vice versa. JAXB 2 binding rules are mainly based on mapping XML schema definitions to Java classes. Elements that can occur several times through the XML Schema attribute maxOccurs="unbounded" or a value of maxOccurs greater than 1 in their containing type are by default represented as a list property (a Java.util.List element elements) or, alternatively, less often, as an indexed property using accessories such as getProp(int index) for the Prop name of the element.

Therefore, I would say that unless the specific requirements require otherwise, I would not use shell elements for the typical use case that you describe. One caveat is that you will need Java member names in the plural, whereas in XML you will need a single form. In your example, you need to avoid the Name Persons XML element for the signature of a Java method, such as List<Person> getPersons() , and you can use the @XmlElement(Name = Person) annotation to get the XML element in a single form instead.

There is a broader discussion of your question: XML, like SGML (a common superset of XML and HTML), is a text format for representing semi-structured data (it was originally designed to replace HTML, but it didn’t work), therefore, the type of data that SGML / XML was developed, by definition, insufficiently represented in the Java component, trying to closely match Java classes / objects with markup elements in general. Instead, the DOM view or another view for sequential access to markup elements, where the order of documents of elements of different types among themselves is observed, may be more natural. In fact, JAXB 1 had more complex mapping rules that could round the order of element documents. But it turned out that for the relatively simple data-oriented applications that XML is used in most cases, this did not help. Consequently, JAXB 2 was designed to more easily capture data-oriented uses such as yours.