diff --git a/README.md b/README.md new file mode 100644 index 0000000000000000000000000000000000000000..0d0693895c5fd4d16691a436258bc153b602d626 --- /dev/null +++ b/README.md @@ -0,0 +1,55 @@ +# VOSpace Data Model + +## Generating beans from XML schema + + cd xsd + xjc vospace.xsd + +### Changes to the online XSD files + +It seems that xjc does something wrong when retriving the imported XSD from the web, so the dependent files have been downloaded and relative path has been specified in `schemaLocation` attribute. + +In vospace.xsd: + + <xsd:import namespace="http://www.ivoa.net/xml/UWS/v1.0" schemaLocation="./uws.xsd"/> + +In uws.xsd: + + <xs:import namespace="http://www.w3.org/1999/xlink" schemaLocation="./xlink.xsd"/> + +### Changes to the generated classes + +In package-info.java the following element has been added to serialize the XML keeping the namespace. + + xmlns = { + @javax.xml.bind.annotation.XmlNs( + namespaceURI = "http://www.ivoa.net/xml/VOSpace/v2.0", + prefix = "vos" + ) + } + +Some issues emerged in handling inheritance and namespaces in a way compatible both to JSON and XML formats. Moreover it was necessary to setup a workaround for filling the `xsi:type` of the root node: + +In Node.java type field and removeType() method have been added: + + // Used for generating missing type attribute for root node. For child nodes it is filled automatically. + @XmlAttribute(name = "type", namespace = "http://www.w3.org/2001/XMLSchema-instance", required = false) + private String type; + + /* This method exists to fix the issue with type attribute. See RemoveDuplicateTypeAdapter class. */ + public void removeType() { + this.type = null; + } + +For JSON compatibility the following has been added to Node.java (annotation on class): + + @JsonTypeInfo(use = JsonTypeInfo.Id.CUSTOM, property = "type", include = JsonTypeInfo.As.EXISTING_PROPERTY) + @JsonTypeIdResolver(NodeTypeJsonResolver.class) + +The `@JsonTypeInfo` tells to Jackson that the field type is used to handle inheritance. A custom type id resolver has been created to handle the `vos:` prefix. + +2 annotations have been added to each node subtype: + + @XmlRootElement(name = "node") + +`@XmlRootElement` is necessary to parse single nodes. The value `"node"` has been specified because by default the bean would be serialized as `<unstructuredDataNode>`.