Author: desruisseaux
Date: Sat Feb 17 14:07:10 2018
New Revision: 1824593
URL: http://svn.apache.org/viewvc?rev=1824593&view=rev
Log:
Moved documentation from TransformingNamespaces to Transformer.
Modified:
sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/Pooled.java
sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/TransformVersion.java
sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/Transformer.java
sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/TransformingNamespaces.java
sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/TransformingWriter.java
Modified:
sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/Pooled.java
URL:
http://svn.apache.org/viewvc/sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/Pooled.java?rev=1824593&r1=1824592&r2=1824593&view=diff
==============================================================================
---
sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/Pooled.java
[UTF-8] (original)
+++
sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/Pooled.java
[UTF-8] Sat Feb 17 14:07:10 2018
@@ -246,7 +246,7 @@ abstract class Pooled {
* the output generated by JAXB will need to go through a {@link
TransformingWriter} in order to replace
* the namespace of versions implemented by SIS by the namespace of
versions requested by the user.
*
- * @see TransformingNamespaces
+ * @see Transformer
*/
final TransformVersion getTransformVersion() {
/*
Modified:
sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/TransformVersion.java
URL:
http://svn.apache.org/viewvc/sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/TransformVersion.java?rev=1824593&r1=1824592&r2=1824593&view=diff
==============================================================================
---
sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/TransformVersion.java
[UTF-8] (original)
+++
sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/TransformVersion.java
[UTF-8] Sat Feb 17 14:07:10 2018
@@ -25,14 +25,15 @@ import org.apache.sis.internal.jaxb.Lega
/**
- * The target version of standards for {@link TransformingNamespaces}.
- *
- * See {@link TransformingNamespaces} for more information.
+ * The target version of standards for {@link Transformer}.
*
* @author Martin Desruisseaux (Geomatys)
* @author Cullen Rombach (Image Matters)
* @version 1.0
- * @since 0.4
+ *
+ * @see Transformer
+ *
+ * @since 0.4
* @module
*/
final class TransformVersion {
Modified:
sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/Transformer.java
URL:
http://svn.apache.org/viewvc/sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/Transformer.java?rev=1824593&r1=1824592&r2=1824593&view=diff
==============================================================================
---
sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/Transformer.java
[UTF-8] (original)
+++
sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/Transformer.java
[UTF-8] Sat Feb 17 14:07:10 2018
@@ -24,15 +24,56 @@ import javax.xml.stream.events.Attribute
/**
- * Base class of XML reader or writer replacing the namespaces used by JAXB by
namespaces used in the XML document,
- * or conversely (depending on the direction of the I/O operation).
+ * Base class of XML reader or writer replacing the namespaces used in JAXB
annotations by namespaces used in
+ * the XML document, or conversely (depending on the direction of the I/O
operation). The {@code Transform*}
+ * classes in this package perform a work similar to XSLT transformers, but
using a lighter implementation at
+ * the expense of less transformation capabilities. This transformer supports:
*
- * See {@link TransformingNamespaces} for more information.
+ * <ul>
+ * <li>Renaming namespaces, which may depend on the parent element.</li>
+ * <li>Renaming elements (classes or properties).</li>
+ * <li>Moving elements provided that the old and new locations are in the
same parent element.</li>
+ * </ul>
+ *
+ * If a more complex transformation is needed, it should be handled by JAXB
methods. This {@code Transformer}
+ * is not expected to transform fully a XML document by itself. It is rather
designed to complete JAXB: some
+ * transformations are better handled with Java methods annotated with JAXB
(see for example the deprecated
+ * methods in {@link org.apache.sis.metadata.iso} packages for legacy ISO
19115:2003 properties), and some
+ * transformations, in particular namespace changes, are better handled by
this {@code Transformer}.
+ *
+ * <div class="section">Why using {@code Transformer}</div>
+ * When the XML schemas of an international standard is updated, the URL of
the namespace is often modified.
+ * For example when GML has been updated from version 3.1 to 3.2, the URL
mandated by the international standard
+ * changed from {@code "http://www.opengis.net/gml"} to {@code
"http://www.opengis.net/gml/3.2"}
+ * (XML namespaces usually have a version number or publication year - GML
before 3.2 were an exception).
+ * The problem is that namespaces in JAXB annotations are static. The
straightforward solution is
+ * to generate complete new set of classes for every GML version using the
{@code xjc} compiler.
+ * But this approach has many inconvenient:
+ *
+ * <ul>
+ * <li>Massive code duplication (hundreds of classes, many of them strictly
identical except for the namespace).</li>
+ * <li>Handling of above-cited classes duplication requires either a bunch
of {@code if (x instanceof Y)} in every
+ * SIS corners, or to modify the {@code xjc} output in order to give to
generated classes a common parent class
+ * or interface. In the later case, the auto-generated classes require
significant work anyways.</li>
+ * <li>The namespaces of all versions appear in the {@code xmlns} attributes
of the root element (we can not always
+ * create separated JAXB contexts), which is confusing and prevent usage
of usual prefixes for all versions
+ * except one.</li>
+ * </ul>
+ *
+ * An alternative is to support only one version of each standard, and
transform XML documents before unmarshalling
+ * or after marshalling if they use different versions of standards. We could
use XSLT for that, but this is heavy.
+ * A lighter approach is to use {@link javax.xml.stream.XMLEventReader} and
{@link javax.xml.stream.XMLEventWriter}
+ * as "micro-transformers". One advantage is that they can transform
on-the-fly (no need to load and transform the
+ * document in memory). It also avoid the need to detect in advance which
schemas a XML document is using, and can
+ * handle the cases where mixed versions are used.
*
* @author Martin Desruisseaux (Geomatys)
* @author Cullen Rombach (Image Matters)
* @version 1.0
- * @since 1.0
+ *
+ * @see javax.xml.transform.Transformer
+ *
+ * @since 1.0
* @module
*/
abstract class Transformer {
Modified:
sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/TransformingNamespaces.java
URL:
http://svn.apache.org/viewvc/sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/TransformingNamespaces.java?rev=1824593&r1=1824592&r2=1824593&view=diff
==============================================================================
---
sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/TransformingNamespaces.java
[UTF-8] (original)
+++
sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/TransformingNamespaces.java
[UTF-8] Sat Feb 17 14:07:10 2018
@@ -26,32 +26,7 @@ import javax.xml.XMLConstants;
/**
* In the associations between prefixes and namespaces, substitutes the
namespaces used in JAXB annotations
* by the namespaces used in the XML document at marshalling time. This class
is used internally by
- * {@link TransformingReader} and {@link TransformingWriter} only.
- *
- * <div class="section">The problem</div>
- * When the XML schemas of an international standard is updated, the URL of
the namespace is often modified.
- * For example when GML has been updated from version 3.1 to 3.2, the URL
mandated by the international standard
- * changed from {@code "http://www.opengis.net/gml"} to {@code
"http://www.opengis.net/gml/3.2"}
- * (XML namespaces usually have a version number or publication year - GML
before 3.2 were an exception).
- *
- * The problem is that namespaces in JAXB annotations are static. The
straightforward solution is
- * to generate complete new set of classes for every GML version using the
{@code xjc} compiler.
- * But this approach has many inconvenient:
- *
- * <ul>
- * <li>Massive code duplication (hundreds of classes, many of them strictly
identical except for the namespace).</li>
- * <li>Handling of above-cited classes duplication requires either a bunch
of {@code if (x instanceof Y)} in every
- * SIS corners, or to modify the {@code xjc} output in order to give to
generated classes a common parent class
- * or interface. In the later case, the auto-generated classes require
significant work anyways.</li>
- * <li>The namespaces of all versions appear in the {@code xmlns} attributes
of the root element (we can not always
- * create separated JAXB contexts), which is confusing and prevent usage
of usual prefixes for all versions
- * except one.</li>
- * </ul>
- *
- * An alternative is to support only one version of each standard, and
transform XML documents before unmarshalling
- * or after marshalling if they use different versions of standards. We could
use XSLT for that, but this is heavy.
- * A lighter approach is to use {@link javax.xml.stream.XMLEventReader} and
{@link javax.xml.stream.XMLEventWriter}
- * as "micro-transformers".
+ * {@link TransformingWriter} and {@link TransformedEvent} only.
*
* @author Martin Desruisseaux (Geomatys)
* @version 1.0
Modified:
sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/TransformingWriter.java
URL:
http://svn.apache.org/viewvc/sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/TransformingWriter.java?rev=1824593&r1=1824592&r2=1824593&view=diff
==============================================================================
---
sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/TransformingWriter.java
[UTF-8] (original)
+++
sis/branches/ISO-19115-3/core/sis-utility/src/main/java/org/apache/sis/xml/TransformingWriter.java
[UTF-8] Sat Feb 17 14:07:10 2018
@@ -46,7 +46,7 @@ import static javax.xml.stream.XMLStream
* at marshalling time. This class forwards every method calls to the wrapped
{@link XMLEventWriter},
* with all {@code namespaceURI} arguments transformed before to be delegated.
*
- * See {@link TransformingNamespaces} for more information.
+ * See {@link Transformer} for more information.
*
* @author Martin Desruisseaux (Geomatys)
* @author Cullen Rombach (Image Matters)
