I'm currently working with an XML Schema that has <xsd:annotation>/<xsd:documentation> on most types and elements. When I generate Java Beans from this XML Schema, then the Javadoc of those Beans only contains some generic generated information about the allowed content of the type/element.
I'd like to see the content of the <xsd:documentation> tag in the relevant places (for example the content of that tag for a complextType should show up in the Javadoc of the class generated to represent that complexType).
Is there any way to achieve this?
Edit: this XML Schema will be used in a WSDL with JAX-WS, so this tag might be appropriate as well.
Edit 2: I've read about <jxb:javadoc>. From what I understand I can specify that either in a separate JAXB binding file or directly in the XML Schema. That would almost solve my problem. But I'd rather use the existing <xsd:documentation> tag, since Javadoc is not the primary target of the documentation (it's information about the data structure primarily and not about the Java Beans generated from it) and to allow non-JAXB tools to access the information as well. Providing the documentation in both <jxb:javadoc> and xsd:documentation> "feels" wrong, because I'm duplicating data (and work) for no good reason.
Edit 3: Thanks to the answer by Pascal I realized that I already have half a solution: The <xsd:documentation> of complexTypes is written to the beginning of its Javadoc! The problem is still that only that complexTypes is used and simpleTypes (which can also result in a class) and elements are still Javadoc-less.
I've never been able to get regular xsd:documentation to be placed in the java source except if and only if it was a Complex Type. Documentation for elements, simple types,
etc are ignored.
So, I end up using jxb:javadoc. To do so, include the definition of xmlns:jxb="http://java.sun.com/xml/ns/jaxb" in your <xsd:schema> element.
Add a child to <xsd:complexType> or <xsd: element> or <xsd:attribute>:
<xsd:annotation><xsd:appinfo><jxb:XXX><jxb:javadoc>
This is my comment for a class/property
</jxb:javadoc></jxb:XXX></xsd:appinfo></xsd:annotation>
Where XXX is either "class" or "property".
For a package you write a child to xsd:schema
<xsd:annotation><xsd:appinfo><jxb:schemaBindings><jxb:package name="com.acme"><jxb:javadoc>
This is my comment for a package
</jxb:javadoc></jxb:package></jxb:schemaBindings></xsd:appinfo></xsd:annotation>
Writing HTML document requires bracketing with <![CDATA[ --- ]]>
(EDIT: While writing my answer, the question has been edited by the OP so I'm updating it accordingly)
In my case, javadoc was the only target so it was acceptable to use jxb:javadoc. But your update makes perfect sense and, actually, I totally agree with you. Sadly, I never found an ideal solution for the situation you describe (so I'll follow this question very carefully). Maybe you could use something like xframe to generate documentation from xsd:documentation, but this doesn't answer the question.
This just isn't possible with the JAXB reference implementation. Even if you were to try to write an XJC plugin, you'd find that the plugin API is given no reference to the Schema definition, so there's no way to extract this information.
Our only hope is that a future version of JAXB fixes the situation. There's an open feature request here.
I find the following techniques work pretty well for adding JavaDoc headers to Java element classes (generated from XML schemas). I nest the JavaDoc in tags defined in the jax-b namespace, nested within the xml schema annotation and appinfo tags. Note the jaxb namespace defines types of documentation tags; I use two of there: the class and the property tags. defined in the following namespace: xmlns:jxb="http://java.sun.com/xml/ns/jaxb"
1) To document a class, I use a jaxb "class" tag in the following sequence:
<xs:complexType name="Structure">
<xs:annotation>
<xs:appinfo>
<jxb:class>
<jxb:javadoc>
Documentation text goes here. Since parsing the schema
into Java involves evaluating the xml, I escape all
the tags I use as follows <p> for <p>.
</jxb:javadoc>
</jxb:class>
</xs:appinfo>
</xs:annotation>
.
.
.
</xs:complexType>
2) To document an element, I use the "property" tag as follows:
<xs:element name="description" type="rep:NamedString">
<xs:annotation>
<xs:appinfo>
<jxb:property>
<jxb:javadoc>
<p>Documentation goes here.</p>
</jxb:javadoc>
</jxb:property>
</xs:appinfo>
</xs:annotation>
</xs:element>
3) I use the same set of tags to document attributes:
<xs:attribute name="name" type="xs:NCName" use="required">
<xs:annotation>
<xs:appinfo>
<jxb:property>
<jxb:javadoc>
<p>Documentation goes here.</p>
</jxb:javadoc>
</jxb:property>
</xs:appinfo>
</xs:annotation>
</xs:attribute>
4) To document a choice, I use the property jaxb tag, and I document the choice.
<xs:choice maxOccurs="unbounded">
<xs:annotation>
<xs:appinfo>
<jxb:property>
<jxb:javadoc>
<p>Documentation goes here.</p>
</jxb:javadoc>
</jxb:property>
</xs:appinfo>
</xs:annotation>
<xs:element name="value" type="rep:NamedValue" />
<xs:element name="list" type="rep:NamedList" />
<xs:element name="structure" type="rep:NamedStructure" />
</xs:choice>
Attempting to document the individual choices here would fail, since this tag
produces an untyped list.
Especially for that case I wrote XJC plugin xjc-documentation-annotation-plugin.
What it does: <annotation><documentation> -> Java class annotations
Said we have this object described in XSD:
<xs:complexType name="CadastralBlock">
<xs:annotation>
<xs:documentation>Cadastral quarter</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="number" type="xs:string">
<xs:annotation>
<xs:documentation>Cadastral number</xs:documentation>
</xs:annotation>
</xs:element>
</xs:complexType>
We run xjc like:
xjc -npa -no-header -d src/main/generated-java/ -p xsd.generated scheme.xsd
And got class like (getters, setters and any annotations omitted for simplicity):
public class CadastralBlock {
protected String number;
}
But in my case I want known how to class and fields was named in source file! So it what this plugin do!
So you get:
#XsdInfo(name = "Cadastral quarter", xsdElementPart = "<complexType name=\"CadastralBlock\">\n <complexContent>\n <restriction base=\"{http://www.w3.org/2001/XMLSchema}anyType\">\n <sequence>\n <element name=\"number\" type=\"{http://www.w3.org/2001/XMLSchema}string\"/></sequence>\n </restriction>\n </complexContent></complexType>")
public class CadastralBlock {
#XsdInfo(name = "Cadastral number")
protected String number;
}
How to use
Manual call in commandline
If you want run it manually ensure jar class with plugin in run classpath and just add option -XPluginDescriptionAnnotation. F.e.:
xjc -npa -no-header -d src/main/generated-java/ -p xsd.generated -XPluginDescriptionAnnotation scheme.xsd
Call from Java/Groovy
Driver.run(
[
'-XPluginDescriptionAnnotation'
,'-d', generatedClassesDir.absolutePath
,'-p', 'info.hubbitus.generated.test'
,'CadastralBlock.xsd'
] as String[]
,new XJCListener() {...}
)
See test XJCPluginDescriptionAnnotationTest for example.
Use from Gradle
With gradle-xjc-plugin:
plugins {
id 'java'
id 'org.unbroken-dome.xjc' version '1.4.1' // https://github.com/unbroken-dome/gradle-xjc-plugin
}
...
dependencies {
xjcClasspath 'info.hubbitus:xjc-documentation-annotation-plugin:1.0'
}
// Results by default in `build/xjc/generated-sources`
xjcGenerate {
source = fileTree('src/main/resources') { include '*.xsd' }
packageLevelAnnotations = false
targetPackage = 'info.hubbitus.xjc.plugin.example'
extraArgs = [ '-XPluginDescriptionAnnotation' ]
}
Complete gradle example in example-project-gradle directory of project.
Related
I have the following XSD:
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:x="MY_NAMESPACE"
targetNamespace="MY_NAMESPACE">
<xs:element name="response" type="x:responseType"/>
<xs:complexType name="responseType">
<xs:all>
<xs:element name="param" type="x:responseParam"/>
</xs:all>
</xs:complexType>
<xs:complexType name="responseParam">
<xs:all>
<xs:element name="value" type="xs:string"/>
</xs:all>
</xs:complexType>
</xs:schema>
I use it to generate JAXB classes for unmarshalling a payload like the following:
<x:response xmlns:x="MY_NAMESPACE">
<param>
<value>OK</value>
</param>
</x:response>
via getWebServiceTemplate().marshalSendAndReceive in Spring. Problem is, I also want to unmarshal payloads without the namespace prefix, like this:
<response xmlns="MY_NAMESPACE">
<param>
<value>OK</value>
</param>
</response>
In this case, the response tag is parsed correctly, but the object reference representing param is always null. How can I edit my XSD to make things work? I already tried setting elementFormDefault="qualified" in the schema, or even form="qualified" on the param element.
Additional info that comes to mind (I might edit and add more depending on comments):
The unmarshaller is a Jaxb2Marshaller.
The XML documents
I think you probably know this, but removing that namespace prefix affects the entire document (because the 'param' and 'value' tags do not have any prefix and therefore inherit the default namespace binding). Becauses of this, in the first document the root tag 'response' is in namespace 'MY_NAMESPACE' and the other tags do not have any namespace. In the second document, all of the tags are in namespace 'MY_NAMESPACE'.
The XML Schema
The elementFormDefault attribute defaults to 'unqualified' so your schema should match the first document and reject the second. Your experiments confirm this.
If you set elementFormDefault to 'qualified' then it will reject the first document and match the second one.
There is no value of elementFormDefault that will make the XSD match both XML documents. The namespace is an integral part of the identity of the element.
Possible solution
If you are determined to construct an XSD that matches both documents then it could be done as follows:
explicitly set elementFormDefault to 'unqualified' (optional, but you're about to rely on that setting)b
wrap the current (globally-declared) contents of responseType in a choice group
add a second branch in the choice group containing a local declaration of element 'param' and all of its descendants. Because those are locally declared, they will be in noTargetNamespace.
This is not a general solution to the problem of making JAXB ignore namespaces, and I don't think you will find one (although I'm happy to be corrected by somebody who knows more than I do about JAXB).
Having said all of the above...I think you are probably solving the wrong problem. The JAXB standard is based on XML Schema. An XSD is not meant to tolerate the wrong namespaces. The second XML document is therefore invalid, and should be corrected by whoever is generating it.
I'm trying to connect to a C#/NET (*.svc) webservice. I have to use java, thus wsdl2java is my choice.
Problem: somehow the targeting webservice defines lots of elements dublicate. This might be due to the nature of C# or whatever.
There are like 100+ elements as follows:
<xs:complexType name="Ticket">
<xs:sequence>
<xs:element minOccurs="0" name="ASegment"
nillable="true" type="tns:AnArray" />
</xs:sequence>
</xs:complexType>
<xs:element name="Ticket" nillable="true" type="tns:Ticket" />
Resulting in:
'Ticket' is already defined (org.apache.cxf:cxf-codegen-plugin:3.0.1:wsdl2java:generate-sources:generate-sources)
How can I cope with this? I read about a jaxb-binding.xml file, where I can "rename" specific elements explicit.
But if I apply this for 100+ elements, well the week has only 5 days...
Is there any way I can though auto generate the classes?
Please see this answer:
Prefixing JAXB generated classes
jaxb:nameXmlTransform is your friend.
I normally do <jaxb:elementName suffix="Element"/>.
I'm not new to SOAP and turning WSDL's into POJO's. I've managed to connect to the web service and retrieve the data I need.
The problem rests in traversing the object hierarchy that the WSDL created.
Most of the variables stored in the generated classes are of the type JAXBElement<NameOfJavaClassHere>. So when ever I want that object I need to issue a call like ListOfEntitiesType loe = ents.getListOfEntities().getValue(); The .getValue() is where I have my issue.
Does there exist a way of making this a smoother integration? If I have to keep doing a getValue() it's going to be a death of 1000 cuts.
It feels like they left in a level of indirection at the client level that they didn't need to.
I've tried to unmarshal the xml with a JAXBContent object, there are a lot of examples on the net on how to do this, but it didn't work in this case. My object came out as null.
Should the WSDL not make POJO's that don't need all this casting about with generics?
Did I use the wrong settings on my wsimport command that came with java 1.7?
Should I use a different wsimport-ish program altogether to generate my POJO's?
If I have to stick with the .getValue() thing, I think I'd much rather make an xpath interface to the raw XML or turn the whole thing into Hashtables and ArrayLists than deal with this.
At least then, I'd have direct access to the info I want.
This XML schema has probably been developed under the influence of some bureaucratic rule. Consider, e.g.
<xs:element minOccurs="0" name="DUNSNumber" nillable="true" type="xs:string"/>
which results in a field
protected JAXBElement<String> dunsNumber;
causing the highly circumstantial get and set procedure you have (rightly) complained about. - What does the XML Schema entry mean? It says the element is a string, can be omitted and it must be possible to distinguish between an empty string and an absent string even when the element is present.
Here is a little experiment:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
version="1.0">
<xs:element name="root" type="RootType"/>
<xs:complexType name="RootType">
<xs:sequence>
<xs:element maxOccurs="unbounded" name="elem" type="ElemType"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="ElemType">
<xs:sequence>
<xs:element minOccurs="0" name="str01" type="xs:string"/>
<xs:element minOccurs="1" name="str1" type="xs:string"/>
<!-- The following element compiles to a JAXBElement<String> -->
<xs:element minOccurs="0" name="str01nil" nillable="true" type="xs:string"/>
<xs:element minOccurs="1" name="str1nil" nillable="true" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
And here is an XML file:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
<elem>
<str01></str01>
<str1></str1>
<str01nil></str01nil>
<str1nil></str1nil>
</elem>
<elem>
<str1>must be there</str1>
<str01nil xsi:nil="true"></str01nil>
<str1nil>must be there</str1nil>
</elem>
</root>
And here is what is printed by an unmarshalling routine:
str01 []
str1 []
str01Nil []
str1Nil []
str01 [null]
str1 [must be there]
str01Nil [null]
str1Nil [must be there]
What happens if you omit <str01nil xsi:nil="true"></str01nil> completely? The outcome will be the same, method JAXBElement.getValue() will return null, and that's it.
Now (sorry for the length of the answer) we can discuss what you can do to return to "sane" Java code generated from the XML schema. I would simply remove nillable="true" and use the resulting code. If you marshal, a null in a field will not produce an element. On unmarshal, there's the weak chance that you see an empty element with an xsi:nil="true". (It is essential to retain minOccurs="0", though.)
There are a few use cases where a JAXBElement is required to be able to round trip XML as defined in the XML Schema. If you are seeing alot of JAXBElement in your generated model then several of these conditions are probably true.
An element is both nillable="true" and minOccurs="0". In this case what does null on the mapped field/property mean? When the property is JAXBElement a null value means the element isn't present and a JAXBElement wrapping null means an XML element with xsi:nil="true".
There are 2 global elements with the same named complex type. Since in JAXB classes correspond to complex types a way is needed to capture which root element was encountered.
http://blog.bdoughan.com/2012/07/jaxb-and-root-elements.html
There is a choice structure where either foo or bar elements can occur and they are the same type. Here a JAXBElement is required because simply encountering a String value isn't enough to indicate which element should be marshalled.
An element with xsi:nil is encountered in the document that contains attributes. In this example the object corresponding to that element can still be unmarshalled to hold the attribute values, but JAXBElement can stil indicate that the element was null.
Mechanisms to Reduce the Number of JAXBElement in the Model
Binding file with generateElementProperty set to false.
<?xml version="1.0" encoding="UTF-8"?>
<bindings xmlns="http://java.sun.com/xml/ns/jaxb" xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/jaxb http://java.sun.com/xml/ns/jaxb/bindingschema_2_0.xsd"
version="2.1">
<globalBindings>
<generateElementProperty>false</generateElementProperty>
</globalBindings>
</bindings>
Simple plugin for XJC - https://jaxb.java.net/2.1.2/docs/vendorCustomizations.html#simple
<?xml version="1.0" encoding="UTF-8"?>
<bindings xmlns="http://java.sun.com/xml/ns/jaxb" xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xsi:schemaLocation="http://java.sun.com/xml/ns/jaxb http://java.sun.com/xml/ns/jaxb/bindingschema_2_0.xsd"
version="2.1">
<globalBindings>
<xjc:simple />
</globalBindings>
</bindings>
I want to generate documentation for XML schemas.
My goal is to analyze the xsd file and to display it as a tree structure (with all complex / anonymous types resolved). Furthermore I need to annotate all items in that tree with their cardinality (as defined by the schema).
The following small example might help to clarify my problem.
a) the xsd file:
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="client" type="clientType" />
<xs:complexType name="clientType">
<xs:sequence minOccurs="1" maxOccurs="1">
<xs:element name="first_name"/>
<xs:element name="last_name"/>
<xs:element name="address" type="addressType"
minOccurs="1" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="addressType">
<xs:sequence>
<xs:element name="street"/>
<xs:element name="number" minOccurs="0" maxOccurs="1"/>
<xs:element name="city"/>
<xs:element name="zipcode"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
b) Output I'd like to see:
client [1]
first_name [1]
last_name [1]
address [1..n]
street [1]
number [0..1]
city [1]
zipcode [1]
Does anybody know a java based solution for this problem? Preferably based on Eclipse Schema Infoset, but I'm happy to use other libraries as well.
XSOM can normalize an XSD into a comprehensible data structure that you can loop over and print out.
Given that XSD schema are also XML you could process this as XML giving you many options for how to do this.
My preference would be to use an XSLT stylesheet with templates to match the element and complex type elements to get the output list, and further templates to match the minOccurs and maxOccurs attributes to get your cardinality.
Examples of stylsheets to do this are probably available online already.
Although not having a proper solution I would propose the following: use a tool that is capable of generating a sample XML instance based on the XSD, e.g. eclipse IDE (as it is open source it should be possible to extract the relevant code and use it within a standalone solution). This XML should be very close to the tree structure you are requiring. Then, parse the XSD and annotate the elements in the generated XML structure with the cardinalities.
I have two schemas which are processed using JAXB. The first schema is preprocessed and information of this is used using an episode file (following http://www.java.net/blog/2006/09/05/separate-compilation-jaxb-ri-21).
The second schema imports the first, and again using jaxb, is processed. This all works as expected.
But now I have an element in the first schema, which is used in the second using a reference.
Schema a:
<schema elementFormDefault="qualified" xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:test="http://www.example.org/Test/"
targetNamespace="http://www.example.org/Test/">
<element name="type" type="test:MyType"></element>
Schema b:
<schema elementFormDefault="qualified"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:second="http://www.example.org/Second/"
xmlns:test="http://www.example.org/Test/"
targetNamespace="http://www.example.org/Second/">
<import namespace="http://www.example.org/Test/" />
<complexType name="SomeType">
<sequence>
<element ref="test:type" minOccurs="1" maxOccurs="unbounded" />
</sequence>
</complexType>
During processing nothing is wrong, but the generated code for both schemas provide the same method:
public JAXBElement<EventType> createType(TypeType value)
At runtime, this results in the following error:
com.sun.xml.internal.bind.v2.runtime.IllegalAnnotationsException: 1 counts of
IllegalAnnotationExceptions
The element name {http://www.example.org/Type/}type has more than one mapping.
How can I prevent JAXB from creating the duplicate createType methods?
Thanks in advance!
Update: I asked this same question on the JAXB mailing list, on that list I also posted a working example. The thread and example can be found at: http://java.net/projects/jaxb/lists/users/archive/2011-03/message/18
On this list I've been suggested a workaround, and now I can use the schemas the way I like. But I still think JAXB should not create the additional "create" method, since it should already be in the episode file.
I've written a few Schema Definitions in my day. You are declaring your first xsd in your second schema declaration and then you are importing it.
As per MSDN, when you import an XSD you do not include it in the Schema Declaration.
This is where it is in your schema declaration.
xmlns:test="http://www.example.org/Test/"
Remove this and just do the import... ( <xs:import namespace="http://www.example.com/IPO" /> )
see:http://msdn.microsoft.com/en-us/library/ms256480.aspx