This is an automated email from the ASF dual-hosted git repository.
jamesnetherton pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new 2bf23015bc3 camel-jaxb: Tidy up docs. Fix typos, wording and out of
date links
2bf23015bc3 is described below
commit 2bf23015bc3e0f12e3f496ebceda49be914a8d68
Author: James Netherton <[email protected]>
AuthorDate: Tue Jul 5 10:26:33 2022 +0100
camel-jaxb: Tidy up docs. Fix typos, wording and out of date links
---
.../camel-jaxb/src/main/docs/jaxb-dataformat.adoc | 209 +++++++++++----------
1 file changed, 109 insertions(+), 100 deletions(-)
diff --git a/components/camel-jaxb/src/main/docs/jaxb-dataformat.adoc
b/components/camel-jaxb/src/main/docs/jaxb-dataformat.adoc
index b1bbb295d74..a8b6d6b3166 100644
--- a/components/camel-jaxb/src/main/docs/jaxb-dataformat.adoc
+++ b/components/camel-jaxb/src/main/docs/jaxb-dataformat.adoc
@@ -11,7 +11,7 @@
*Since Camel {since}*
JAXB is a Data Format which uses the JAXB2 XML
-marshalling standard which is included in Java 6 to unmarshal an XML
+marshalling standard to unmarshal an XML
payload into Java objects or to marshal Java objects into an XML
payload.
@@ -24,9 +24,9 @@ include::partial$dataformat-options.adoc[]
== Using the Java DSL
-For example the following uses a named DataFormat of _jaxb_ which is
-configured with a number of Java package names to initialize the
-http://java.sun.com/javase/6/docs/api/javax/xml/bind/JAXBContext.html[JAXBContext].
+The following example uses a named DataFormat of `jaxb` which is
+configured with a Java package name to initialize the
+https://jakarta.ee/specifications/xml-binding/2.3/apidocs/javax/xml/bind/jaxbcontext[JAXBContext].
[source,java]
-------------------------------------------------------
@@ -50,67 +50,84 @@ from("activemq:My.Queue").
== Using Spring XML
-The following example shows how to use JAXB to unmarshal using
-Spring configuring the jaxb data type
+The following example shows how to configure the `JaxbDataFormat` and use it
in multiple routes.
-This example shows how to configure the data type just once and reuse it
-on multiple routes.
+[source,xml]
+-------------------------------
+<beans xmlns="http://www.springframework.org/schema/beans";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
+ http://camel.apache.org/schema/spring
http://camel.apache.org/schema/spring/camel-spring.xsd";>
+
+ <bean id="myJaxb" class="org.apache.camel.converter.jaxb.JaxbDataFormat">
+ <property name="contextPath" value="org.apache.camel.example"/>
+ </bean>
+
+ <camelContext xmlns="http://camel.apache.org/schema/spring";>
+ <route>
+ <from uri="direct:start"/>
+ <marshal><custom ref="myJaxb"/></marshal>
+ <to uri="direct:marshalled"/>
+ </route>
+ <route>
+ <from uri="direct:marshalled"/>
+ <unmarshal><custom ref="myJaxb"/></unmarshal>
+ <to uri="mock:result"/>
+ </route>
+ </camelContext>
+
+</beans>
+-------------------------------
-*Multiple context paths*
+== Multiple context paths
It is possible to use this data format with more than one context path.
-You can specify context path using `:` as separator, for example
-`com.mycompany:com.mycompany2`. Note that this is handled by JAXB
-implementation and might change if you use different vendor than RI.
+You can specify multiple context paths using `:` as a separator, for example
+`com.mycompany:com.mycompany2`.
-== Partial marshalling/unmarshalling
+== Partial marshalling / unmarshalling
JAXB 2 supports marshalling and unmarshalling XML tree fragments. By
-default JAXB looks for `@XmlRootElement` annotation on given class to
-operate on whole XML tree. This is useful but not always - sometimes
-generated code does not have @XmlRootElement annotation, sometimes you
-need unmarshall only part of tree.
+default JAXB looks for the `@XmlRootElement` annotation on a given class to
+operate on whole XML tree. This is useful, but not always. Sometimes
+generated code does not have the `@XmlRootElement` annotation and sometimes you
+need to unmarshall only part of the tree.
In that case you can use partial unmarshalling. To enable this
-behaviours you need set property `partClass`. Camel will pass this class
-to JAXB's unmarshaler. If `JaxbConstants.JAXB_PART_CLASS` is set as
-one of headers, (even if partClass property is set on DataFormat), the property
-on DataFormat is surpassed and the one set in the headers is used.
+behaviour you need set property `partClass` on the `JaxbDataFormat`. Camel
will pass this class
+to the JAXB unmarshaller. If `JaxbConstants.JAXB_PART_CLASS` is set as
+one of the exchange headers, its value is used to override the `partClass`
property
+on the `JaxbDataFormat`.
+
+For marshalling you have to add the `partNamespace` attribute with the `QName`
of
+the destination namespace.
-For marshalling you have to add `partNamespace` attribute with QName of
-destination namespace. Example of Spring DSL you can find above.
If `JaxbConstants.JAXB_PART_NAMESPACE` is set as
-one of headers, (even if partNamespace property is set on DataFormat), the
property
-on DataFormat is surpassed and the one set in the headers is used. While
setting
-`partNamespace` through `JaxbConstants.JAXB_PART_NAMESPACE`, please
-note that you need to specify its value {[namespaceUri]}[localPart]
+one of the exchange headers, its value is used to override the `partNamespace`
property
+on the `JaxbDataFormat`.
+
+While setting `partNamespace` through `JaxbConstants.JAXB_PART_NAMESPACE`,
please
+note that you need to specify its value in the format
`{namespaceUri}localPart`, as per the example below.
[source,java]
--------------------------------------------------------------------------------------
- ...
- .setHeader(JaxbConstants.JAXB_PART_NAMESPACE,
simple("{http://www.camel.apache.org/jaxb/example/address/1}address";));
- ...
+.setHeader(JaxbConstants.JAXB_PART_NAMESPACE,
constant("{http://www.camel.apache.org/jaxb/example/address/1}address";));
--------------------------------------------------------------------------------------
== Fragment
-JaxbDataFormat has new property fragment which can set the the
-`Marshaller.JAXB_FRAGMENT` encoding property on the JAXB Marshaller. If
-you don't want the JAXB Marshaller to generate the XML declaration, you
-can set this option to be true. The default value of this property is
-false.
+`JaxbDataFormat` has a property named `fragment` which can set the
`Marshaller.JAXB_FRAGMENT`
+property on the JAXB Marshaller. If you don't want the JAXB Marshaller to
generate
+the XML declaration, you can set this option to be `true`. The default value
of this property is `false`.
-== Ignoring the NonXML Character
+== Ignoring Non-XML Characters
-JaxbDataFormat supports to ignore the
-http://www.w3.org/TR/2004/REC-xml-20040204/#NT-Char[NonXML Character],
-you just need to set the filterNonXmlChars property to be true,
-JaxbDataFormat will replace the NonXML character with " " when it is
-marshaling or unmarshaling the message. You can also do it by setting
-the Exchange property
-`Exchange.FILTER_NON_XML_CHARS`.
+`JaxbDataFormat` supports ignoring
+https://www.w3.org/TR/xml/#NT-Char[Non-XML Characters],
+you just need to set the `filterNonXmlChars` property to `true`.
+The `JaxbDataFormat` will replace any non-XML character with a space character
(`" "`) during message
+marshalling or unmarshalling. You can also set the Exchange property
`Exchange.FILTER_NON_XML_CHARS`.
-
[width="100%",cols="30%,10%,60%",options="header",]
|=======================================================================
| | JDK 1.5 | JDK 1.6+
@@ -123,97 +140,90 @@ the Exchange property
This feature has been tested with Woodstox 3.2.9 and Sun JDK 1.6 StAX
implementation.
-JaxbDataFormat now allows you to customize the XMLStreamWriter used to
+`JaxbDataFormat` now allows you to customize the `XMLStreamWriter` used to
marshal the stream to XML. Using this configuration, you can add your
-own stream writer to completely remove, escape, or replace non-xml
+own stream writer to completely remove, escape, or replace non-XML
characters.
[source,java]
--------------------------------------------------------------------------------------
- JaxbDataFormat customWriterFormat = new
JaxbDataFormat("org.apache.camel.foo.bar");
- customWriterFormat.setXmlStreamWriterWrapper(new TestXmlStreamWriter());
+JaxbDataFormat customWriterFormat = new
JaxbDataFormat("org.apache.camel.foo.bar");
+customWriterFormat.setXmlStreamWriterWrapper(new TestXmlStreamWriter());
--------------------------------------------------------------------------------------
The following example shows using the Spring DSL and also enabling
-Camel's NonXML filtering:
+Camel's non-XML filtering:
[source,xml]
------------------------------------------------------------------------------------------------------------------------------
<bean id="testXmlStreamWriterWrapper"
class="org.apache.camel.jaxb.TestXmlStreamWriter"/>
-<jaxb filterNonXmlChars="true" contextPath="org.apache.camel.foo.bar"
xmlStreamWriterWrapper="#testXmlStreamWriterWrapper" />
+<jaxb filterNonXmlChars="true" contextPath="org.apache.camel.foo.bar"
xmlStreamWriterWrapper="#testXmlStreamWriterWrapper" />
------------------------------------------------------------------------------------------------------------------------------
-== Working with the ObjectFactory
+== Working with the `ObjectFactory`
If you use XJC to create the java class from the schema, you will get an
-ObjectFactory for you JAXB context. Since the ObjectFactory uses
-http://java.sun.com/javase/6/docs/api/javax/xml/bind/JAXBElement.html[JAXBElement]
+`ObjectFactory` for your JAXB context. Since the `ObjectFactory` uses
+https://jakarta.ee/specifications/xml-binding/2.3/apidocs/javax/xml/bind/jaxbelement[JAXBElement]
to hold the reference of the schema and element instance value,
-jaxbDataformat will ignore the JAXBElement by default and you will get
-the element instance value instead of the JAXBElement object form the
-unmarshaled message body. +
- If you want to get the JAXBElement object form the unmarshaled message
-body, you need to set the JaxbDataFormat object's ignoreJAXBElement
-property to be false.
+`JaxbDataformat` will ignore the `JAXBElement` by default and you will get
+the element instance value instead of the `JAXBElement` object from the
+unmarshaled message body.
-== Setting encoding
+If you want to get the `JAXBElement` object form the unmarshaled message
+body, you need to set the `JaxbDataFormat` `ignoreJAXBElement`
+property to be `false`.
-You can set the *encoding* option to use when marshalling. Its the
-`Marshaller.JAXB_ENCODING` encoding property on the JAXB Marshaller. +
- You can setup which encoding to use when you declare the JAXB data
-format. You can also provide the encoding in the
-Exchange property `Exchange.CHARSET_NAME`. This
-property will overrule the encoding set on the JAXB data format.
+== Setting the encoding
-In this Spring DSL we have defined to use `iso-8859-1` as the encoding:
+You can set the `encoding` option on the `JaxbDataFormat` to configure the
+`Marshaller.JAXB_ENCODING` encoding property on the JAXB Marshaller.
+
+You can setup which encoding to use when you declare the `JaxbDataFormat`. You
can also provide the encoding in the
+Exchange property `Exchange.CHARSET_NAME`. This property will override the
encoding set on the `JaxbDataFormat`.
== Controlling namespace prefix mapping
*Since Camel 2.11*
When marshalling using xref:jaxb-dataformat.adoc[JAXB] or
xref:jaxb-dataformat.adoc[SOAP] then
-the JAXB implementation will automatic assign namespace prefixes, such
-as ns2, ns3, ns4 etc. To control this mapping, Camel allows you to refer
+the JAXB implementation will automatically assign namespace prefixes, such
+as `ns2`, `ns3`, `ns4` etc. To control this mapping, Camel allows you to refer
to a map which contains the desired mapping.
-Notice this requires having JAXB-RI 2.1 or better (from SUN) on the
-classpath, as the mapping functionality is dependent on the
-implementation of JAXB, whether its supported.
-
-For example in Spring XML we can define a Map with the mapping. In the
-mapping file below, we map SOAP to use soap as prefix. While our custom
-namespace "http://www.mycompany.com/foo/2"; is not using any prefix.
+For example, in Spring XML we can define a `Map` with the mapping. In the
+mapping file below, we map SOAP to use soap as as a prefix. While our custom
+namespace `http://www.mycompany.com/foo/2` is not using any prefix.
[source,xml]
-----------------------------------------------------------------------
- <util:map id="myMap">
+ <util:map id="myMap">
<entry key="http://www.w3.org/2003/05/soap-envelope"; value="soap"/>
- <!-- we dont want any prefix for our namespace -->
+ <!-- we don't want any prefix for our namespace -->
<entry key="http://www.mycompany.com/foo/2"; value=""/>
- </util:map>
+ </util:map>
-----------------------------------------------------------------------
To use this in JAXB or SOAP data formats you refer to
this map, using the `namespacePrefixRef` attribute as shown below. Then
Camel will lookup in the Registry a `java.util.Map`
-with the id "myMap", which was what we defined above.
+with the id `myMap`, which was what we defined above.
[source,xml]
----------------------------------------------------------------------------------------
- <marshal>
+ <marshal>
<soap version="1.2" contextPath="com.mycompany.foo"
namespacePrefixRef="myMap"/>
- </marshal>
+ </marshal>
----------------------------------------------------------------------------------------
== Schema validation
*Since Camel 2.11*
-The JAXB Data Format supports validation by
-marshalling and unmarshalling from/to XML. Your can use the prefix
-*classpath:*, *file:* or *http:* to specify how the resource should by
-resolved. You can separate multiple schema files by using the *','*
-character.
+The `JaxbDataFormat` supports validation by
+marshalling and unmarshalling from / to XML. You can use the prefix
+`classpath:`, `file:` or `http:` to specify how the resource should be
+resolved. You can separate multiple schema files by using the `,` character.
Using the Java DSL, you can configure it in the following way:
@@ -234,10 +244,10 @@ You can do the same using the XML DSL:
-------------------------------------------------------------------------
Camel will create and pool the underling `SchemaFactory` instances on
-the fly, because the `SchemaFactory` shipped with the JDK is not thread
-safe. +
- However, if you have a `SchemaFactory` implementation which is thread
-safe, you can configure the JAXB data format to use this one:
+the fly, because the `SchemaFactory` shipped with the JDK is not thread safe.
+
+However, if you have a `SchemaFactory` implementation which is thread
+safe, you can configure the `JaxbDataFormat` to use this one:
[source,java]
--------------------------------------------------------
@@ -249,8 +259,7 @@ jaxbDataFormat.setSchemaFactory(thradSafeSchemaFactory);
*Since Camel 2.14*
-The JAXB Data Format supports to specify the
-SchemaLocation when marshaling the XML.
+The `JaxbDataFormat` supports to specify the `SchemaLocation` when marshalling
the XML.
Using the Java DSL, you can configure it in the following way:
@@ -275,13 +284,13 @@ You can do the same using the XML DSL:
*Since Camel 2.14.1*
The JAXB marshaller requires that the message body is JAXB compatible,
-eg its a JAXBElement, eg a java instance that has JAXB annotations, or
-extend JAXBElement. There can be situations where the message body is
-already in XML, eg from a String type. There is a new
-option `mustBeJAXBElement` you can set to false, to relax this check, so
-the JAXB marshaller only attempts to marshal JAXBElements
-(javax.xml.bind.JAXBIntrospector#isElement returns true). And in those
-situations the marshaller fallbacks to marshal the message body as-is.
+e.g it is a `JAXBElement`, a java instance that has JAXB annotations, or
+extends `JAXBElement`. There can be situations where the message body is
+already in XML, e.g from a `String` type.
+
+`JaxbDataFormat` has an option named `mustBeJAXBElement` which you can set to
`false` to relax this check and
+have the JAXB marshaller only attempt marshalling on `JAXBElement`
(`javax.xml.bind.JAXBIntrospector#isElement` returns `true`).
+In those situations the marshaller will fallback to marshal the message body
as-is.
== Dependencies
