cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r1029365 - in /websites/production/cxf/content: cache/docs.pageCache docs/mtom.html
Date Thu, 03 May 2018 15:56:42 GMT
Author: buildbot
Date: Thu May  3 15:56:42 2018
New Revision: 1029365

Log:
Production update by buildbot for cxf

Modified:
    websites/production/cxf/content/cache/docs.pageCache
    websites/production/cxf/content/docs/mtom.html

Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.

Modified: websites/production/cxf/content/docs/mtom.html
==============================================================================
--- websites/production/cxf/content/docs/mtom.html (original)
+++ websites/production/cxf/content/docs/mtom.html Thu May  3 15:56:42 2018
@@ -117,30 +117,8 @@ Apache CXF -- MTOM
          <td height="100%">
            <!-- Content -->
            <div class="wiki-content">
-<div id="ConfluenceContent"><h1 id="MTOM-UsingMTOM">Using MTOM</h1>
-
-<p>SOAP Message Transmission Optimization Mechanism (<a shape="rect" class="external-link"
href="http://www.w3.org/TR/soap12-mtom/" rel="nofollow">MTOM</a>) specifies an optimized
method for sending binary data as part of a SOAP message. Unlike SOAP with Attachments, MTOM
requires the use of XML-binary Optimized Packaging (XOP) packages for transmitting binary
data. Using MTOM to send binary data does not require you to fully define the MIME Multipart/Related
message as part of the SOAP binding. It does, however, require that you do the following:</p>
-<ol><li>Annotate the data that you are going to send as an attachment.<br
clear="none" class="atl-forced-newline">
-You can annotate either your WSDL or the Java class that implements your data.</li><li>Enable
the runtime's MTOM support.<br clear="none" class="atl-forced-newline">
-This can be done either programatically or through configuration.</li><li>Develop
a <code>DataHandler</code> for the data being passed as an attachment.</li></ol>
-
-
-<h2 id="MTOM-AnnotatingDataTypestouseMTOM">Annotating Data Types to use MTOM</h2>
-
-
-<h3 id="MTOM-Overview">Overview</h3>
-
-<p>When defining a data type for passing along a block of binary data, such as an image
file or a sound file, in WSDL you define the element for the data to be of type <code>xsd:base64Binary</code>.
By default, any element of type <code>xsd:base64Binary</code> results in the generation
of a <code>byte[]</code> which can be serialized using MTOM. However, the default
behavior of the code generators does not take full advantage of the serialization.</p>
-
-<p>In order to fully take advantage of MTOM you must add annotations to either your
service's WSDL document or the JAXB class that implements the binary data structure. Adding
the annotations to the WSDL document forces the code generators to generate streaming data
handlers for the binary data. Annotating the JAXB class involves specifying the proper content
types and may also involve changing the type specification of the field containing the binary
data.</p>
-
-<h3 id="MTOM-WSDLfirst">WSDL first</h3>
-
-<p>The following example shows a WSDL document for a Web service that uses a message
which contains one string field, one integer field, and a binary field. The binary field is
intended to carry a large image file, so it is not appropriate for sending along as part of
a normal SOAP message.</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader
pdl" style="border-bottom-width: 1px;"><b>Message for MTOM</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
-&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+<div id="ConfluenceContent"><h1 id="MTOM-UsingMTOM">Using MTOM</h1><p>SOAP
Message Transmission Optimization Mechanism (<a shape="rect" class="external-link" href="http://www.w3.org/TR/soap12-mtom/"
rel="nofollow">MTOM</a>) specifies an optimized method for sending binary data as
part of a SOAP message. Unlike SOAP with Attachments, MTOM requires the use of XML-binary
Optimized Packaging (XOP) packages for transmitting binary data. Using MTOM to send binary
data does not require you to fully define the MIME Multipart/Related message as part of the
SOAP binding. It does, however, require that you do the following:</p><ol><li>Annotate
the data that you are going to send as an attachment.<br clear="none" class="atl-forced-newline">
You can annotate either your WSDL or the Java class that implements your data.</li><li>Enable
the runtime's MTOM support.<br clear="none" class="atl-forced-newline"> This can be
done either programatically or through configuration.</li><li>Develop a <code>Da
 taHandler</code> for the data being passed as an attachment.</li></ol><h2
id="MTOM-AnnotatingDataTypestouseMTOM">Annotating Data Types to use MTOM</h2><h3
id="MTOM-Overview">Overview</h3><p>When defining a data type for passing along
a block of binary data, such as an image file or a sound file, in WSDL you define the element
for the data to be of type <code>xsd:base64Binary</code>. By default, any element
of type <code>xsd:base64Binary</code> results in the generation of a <code>byte[]</code>
which can be serialized using MTOM. However, the default behavior of the code generators does
not take full advantage of the serialization.</p><p>In order to fully take advantage
of MTOM you must add annotations to either your service's WSDL document or the JAXB class
that implements the binary data structure. Adding the annotations to the WSDL document forces
the code generators to generate streaming data handlers for the binary data. Annotating the
JAXB class involves specifying the proper c
 ontent types and may also involve changing the type specification of the field containing
the binary data.</p><h3 id="MTOM-WSDLfirst">WSDL first</h3><p>The
following example shows a WSDL document for a Web service that uses a message which contains
one string field, one integer field, and a binary field. The binary field is intended to carry
a large image file, so it is not appropriate for sending along as part of a normal SOAP message.</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader
pdl" style="border-bottom-width: 1px;"><b>Message for MTOM</b></div><div
class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">&lt;?xml
version="1.0" encoding="UTF-8"?&gt;
 &lt;definitions name="XrayStorage"
     targetNamespace="http://mediStor.org/x-rays"
     xmlns="http://schemas.xmlsoap.org/wsdl/"
@@ -192,19 +170,8 @@ This can be done either programatically
   ...
 &lt;/definitions&gt;
 </pre>
-</div></div>
-
-<p>If you wanted to use MTOM to send the binary part of the message as an optimized
attachment you would need to add the <code>xmime:expectedContentTypes</code> attribute
to the element containing the binary data. This attribute is defined in the <code><a
shape="rect" class="external-link" href="http://www.w3.org/2005/05/xmlmime" rel="nofollow">http://www.w3.org/2005/05/xmlmime</a></code>
namespace and specifies the MIME types that the element is expected to contain. You can specify
a comma separated list of MIME types. The setting of this attribute will change how the code
generators create the JAXB class for the data. For most MIME types, the code generator will
create a <code>DataHandler</code>. Some MIME types, such as those for images,
have defined mappings.</p>
-<div class="confluence-information-macro confluence-information-macro-note"><span
class="aui-icon aui-icon-small aui-iconfont-warning confluence-information-macro-icon"></span><div
class="confluence-information-macro-body">
-<p>The MIME types are maintained by the Internet Assigned Numbers Authority (IANA)
and described in detail in <strong>Multipurpose Internet Mail Extensions (MIME) Part
One: Format of Internet Message Bodies</strong> (<a shape="rect" class="external-link"
href="ftp://ftp.isi.edu/in-notes/rfc2045.txt" rel="nofollow">ftp://ftp.isi.edu/in-notes/rfc2045.txt</a>)
and <strong>Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types</strong>(<a
shape="rect" class="external-link" href="ftp://ftp.isi.edu/in-notes/rfc2046.txt" rel="nofollow">ftp://ftp.isi.edu/in-notes/rfc2046.txt</a>)</p></div></div>
-<div class="confluence-information-macro confluence-information-macro-tip"><span
class="aui-icon aui-icon-small aui-iconfont-approve confluence-information-macro-icon"></span><div
class="confluence-information-macro-body">
-<p>For most uses you would specify <code>application/octet-stream</code>.</p></div></div>
-
-<p>The following example shows how you would modify <code>xRayType</code>
to use MTOM.</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader
pdl" style="border-bottom-width: 1px;"><b>Binary Data for MTOM</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
-...
+</div></div><p>If you wanted to use MTOM to send the binary part of the
message as an optimized attachment you would need to add the <code>xmime:expectedContentTypes</code>
attribute to the element containing the binary data. This attribute is defined in the <code><a
shape="rect" class="external-link" href="http://www.w3.org/2005/05/xmlmime" rel="nofollow">http://www.w3.org/2005/05/xmlmime</a></code>
namespace and specifies the MIME types that the element is expected to contain. You can specify
a comma separated list of MIME types. The setting of this attribute will change how the code
generators create the JAXB class for the data. For most MIME types, the code generator will
create a <code>DataHandler</code>. Some MIME types, such as those for images,
have defined mappings.</p><div class="confluence-information-macro confluence-information-macro-note"><span
class="aui-icon aui-icon-small aui-iconfont-warning confluence-information-macro-icon"></span><div
class="confluence-informati
 on-macro-body"><p>The MIME types are maintained by the Internet Assigned Numbers
Authority (IANA) and described in detail in <strong>Multipurpose Internet Mail Extensions
(MIME) Part One: Format of Internet Message Bodies</strong> (<a shape="rect" class="external-link"
href="ftp://ftp.isi.edu/in-notes/rfc2045.txt" rel="nofollow">ftp://ftp.isi.edu/in-notes/rfc2045.txt</a>)
and <strong>Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types</strong>(<a
shape="rect" class="external-link" href="ftp://ftp.isi.edu/in-notes/rfc2046.txt" rel="nofollow">ftp://ftp.isi.edu/in-notes/rfc2046.txt</a>)</p></div></div><div
class="confluence-information-macro confluence-information-macro-tip"><span class="aui-icon
aui-icon-small aui-iconfont-approve confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>For most uses you would specify <code>application/octet-stream</code>.</p></div></div><p>The
following example shows how you would modify <code>xRayTyp
 e</code> to use MTOM.</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Binary
Data for MTOM</b></div><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">...
   &lt;types&gt;
     &lt;schema targetNamespace="http://mediStor.org/types/"
             xmlns="http://www.w3.org/2001/XMLSchema"
@@ -222,22 +189,8 @@ This can be done either programatically
   &lt;/types&gt;
 ...
 </pre>
-</div></div>
-<p>The generated JAXB class generated for <code>xRayType</code> will no
longer contain a <code>byte[]</code>. Instead the code generator will see the
<code>xmime:expectedContentTypes</code> attribute and generate a <code>DataHandler</code>
for the <code>imageData</code> field.</p>
-<div class="confluence-information-macro confluence-information-macro-note"><span
class="aui-icon aui-icon-small aui-iconfont-warning confluence-information-macro-icon"></span><div
class="confluence-information-macro-body">
-<p>You do not need to change the binding element to use MTOM. The runtime will make
the appropriate changes when the data is sent.</p></div></div>
-
-<h3 id="MTOM-Javafirst">Java first</h3>
-
-<p>If you are doing Java first development you can make your JAXB class MTOM ready
by doing the following:</p>
-<ol><li>Make sure the field holding the binary data is a <code>DataHandler</code>.</li><li>Add
the <code>@XmlMimeType()</code> annotation to the field containing the data you
want to be streamed as an MTOM attachment.</li></ol>
-
-
-<p>The following example shows a JAXB class annotated for using MTOM.</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader
pdl" style="border-bottom-width: 1px;"><b>JAXB Class for MTOM</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
-@XmlType
+</div></div><p>The generated JAXB class generated for <code>xRayType</code>
will no longer contain a <code>byte[]</code>. Instead the code generator will
see the <code>xmime:expectedContentTypes</code> attribute and generate a <code>DataHandler</code>
for the <code>imageData</code> field.</p><div class="confluence-information-macro
confluence-information-macro-note"><span class="aui-icon aui-icon-small aui-iconfont-warning
confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>You
do not need to change the binding element to use MTOM. The runtime will make the appropriate
changes when the data is sent.</p></div></div><h3 id="MTOM-Javafirst">Java
first</h3><p>If you are doing Java first development you can make your JAXB class
MTOM ready by doing the following:</p><ol><li>Make sure the field holding
the binary data is a <code>DataHandler</code>.</li><li>Add the <code>@XmlMimeType()</code>
annotation to the field containing the data you want to be 
 streamed as an MTOM attachment.</li></ol><p>The following example shows
a JAXB class annotated for using MTOM.</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>JAXB
Class for MTOM</b></div><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">@XmlType
 public class XRayType {
     protected String patientName;
     protected int patientNumber;
@@ -246,72 +199,22 @@ public class XRayType {
   ...
 }
 </pre>
-</div></div>
-
-<h2 id="MTOM-EnablingMTOM">Enabling MTOM</h2>
-
-<p>By default the runtime does not enable MTOM support. It will send all binary data
as either part of the normal SOAP message or as an unoptimized attachment. You can activate
MTOM support either programatically or through the use of configuration.</p>
-
-<h3 id="MTOM-UsingJAX-WSAPIs">Using JAX-WS APIs</h3>
-
-<p>Both clients and servers need to have the MTOM optimizations enabled. The JAX-WS
APIs offer different mechanisms for each type of endpoint.</p>
-
-<h4 id="MTOM-server">server</h4>
-
-<p>If you published your server using the JAX-WS APIs you enable the runtime's MTOM
support as follows:</p>
-<ol><li>Get access to the <code>Endpoint</code> object for your published
service.<br clear="none" class="atl-forced-newline">
-The easiest way to get the <code>Endpoint</code> object is when you publish the
endpoint.</li><li>Get the SOAP binding from the <code>Endpoint</code>
using its <code>getBinding()</code> method as shown below.<br clear="none"
class="atl-forced-newline">
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader
pdl" style="border-bottom-width: 1px;"><b>Getting the SOAP Binding from an Endpoint</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
-// Endpoint ep is declared previously
+</div></div><h2 id="MTOM-EnablingMTOM">Enabling MTOM</h2><p>By
default the runtime does not enable MTOM support. It will send all binary data as either part
of the normal SOAP message or as an unoptimized attachment. You can activate MTOM support
either programatically or through the use of configuration.</p><h3 id="MTOM-UsingJAX-WSAPIs">Using
JAX-WS APIs</h3><p>Both clients and servers need to have the MTOM optimizations
enabled. The JAX-WS APIs offer different mechanisms for each type of endpoint.</p><h4
id="MTOM-server">server</h4><p>If you published your server using the JAX-WS
APIs you enable the runtime's MTOM support as follows:</p><ol><li>Get access
to the <code>Endpoint</code> object for your published service.<br clear="none"
class="atl-forced-newline"> The easiest way to get the <code>Endpoint</code>
object is when you publish the endpoint.</li><li><p>Get the SOAP binding
from the <code>Endpoint</code> using its <code>getBinding()</code>
method as shown below.</p><div cla
 ss="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>Getting the SOAP Binding from an Endpoint</b></div><div
class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">//
Endpoint ep is declared previously
 SOAPBinding binding = (SOAPBinding)ep.getBinding();
 </pre>
-</div></div>
-You must cast the returned binding object to a <code>SOAPBinding</code> object
in order to access the MTOM property.</li><li>Set the bindings MTOM enabled property
to true using the binding's setMTOMEnabled() method as shown below.<br clear="none" class="atl-forced-newline">
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader
pdl" style="border-bottom-width: 1px;"><b>Setting a Service Provider's MTOM Enabled
Property</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
-binding.setMTOMEnabled(true);
+</div></div><p>You must cast the returned binding object to a <code>SOAPBinding</code>
object in order to access the MTOM property.</p></li><li><p>Set the
bindings MTOM enabled property to true using the binding's setMTOMEnabled() method as shown
below.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>Setting a Service Provider's
MTOM Enabled Property</b></div><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">binding.setMTOMEnabled(true);
 </pre>
-</div></div></li></ol>
-
-
-<h4 id="MTOM-Client">Client</h4>
-
-<p>To MTOM enable a JAX-WS client you do the following:</p>
-<ol><li>Cast the client's proxy to a <code>BindingProvider</code>
object.</li><li>Get the SOAP binding from the <code>BindingProvider</code>
using its <code>getBinding()</code> method as shown below.<br clear="none"
class="atl-forced-newline">
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader
pdl" style="border-bottom-width: 1px;"><b>Getting a SOAP Binding from a BindingProvider</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
-// BindingProvider bp declared previously
+</div></div></li></ol><h4 id="MTOM-Client">Client</h4><p>To
MTOM enable a JAX-WS client you do the following:</p><ol><li>Cast the client's
proxy to a <code>BindingProvider</code> object.</li><li><p>Get
the SOAP binding from the <code>BindingProvider</code> using its <code>getBinding()</code>
method as shown below.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Getting a
SOAP Binding from a BindingProvider</b></div><div class="codeContent panelContent
pdl">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">//
BindingProvider bp declared previously
 SOAPBinding binding = (SOAPBinding)bp.getBinding();
 </pre>
-</div></div></li><li>Set the bindings MTOM enabled property to <code>true</code>
using the binding's <code>setMTOMEnabled()</code> method as shown below.<br
clear="none" class="atl-forced-newline">
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader
pdl" style="border-bottom-width: 1px;"><b>Setting a Consumer's MTOM Enabled Property</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
-binding.setMTOMEnabled(true);
+</div></div></li><li><p>Set the bindings MTOM enabled property
to <code>true</code> using the binding's <code>setMTOMEnabled()</code>
method as shown below.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Setting a
Consumer's MTOM Enabled Property</b></div><div class="codeContent panelContent
pdl">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">binding.setMTOMEnabled(true);
 </pre>
-</div></div></li></ol>
-
-
-<h3 id="MTOM-Usingconfiguration">Using configuration</h3>
-
-
-<h4 id="MTOM-Overview.1">Overview</h4>
-
-<p>If you publish your service using XML, such as when deploying into a container,
you can enable your endpoint's MTOM support in the endpoint's configuration file.</p>
-
-<p><span class="confluence-anchor-link" id="MTOM-ConfigFile"></span>h4.
Procedure</p>
-
-<p>The MTOM property is set inside the <code>jaxws:endpoint</code> element
for your endpoint. To enable MTOM do the following:</p>
-<ol><li>Add a <code>jaxws:property</code> child element to the endpoint's
<code>jaxws:endpoint</code> element.</li><li>Add a <code>entry</code>
child element to the <code>jaxws:property</code> element.</li><li>Set
the <code>entry</code> element's <code>key</code> attribute to <code>mtom-enabled</code>.</li><li>Set
the <code>entry</code> element's <code>value</code> attribute to <code>true</code>.</li></ol>
-
-
-<h4 id="MTOM-Example">Example</h4>
-
-<p>The following example shows an endpoint that is MTOM enabled.</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader
pdl" style="border-bottom-width: 1px;"><b>Configuration for Enabling MTOM</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
-&lt;beans xmlns="http://www.springframework.org/schema/beans"
+</div></div></li></ol><h3 id="MTOM-Usingconfiguration">Using
configuration</h3><h4 id="MTOM-Overview.1">Overview</h4><p>If you
publish your service using XML, such as when deploying into a container, you can enable your
endpoint's MTOM support in the endpoint's configuration file.</p><h4 id="MTOM-ConfigFileProcedure"><span
class="confluence-anchor-link" id="MTOM-ConfigFile"></span>Procedure</h4><p>The
MTOM property is set inside the <code>jaxws:endpoint</code> element for your endpoint.
To enable MTOM do the following:</p><ol><li>Add a <code>jaxws:property</code>
child element to the endpoint's <code>jaxws:endpoint</code> element.</li><li>Add
a <code>entry</code> child element to the <code>jaxws:property</code>
element.</li><li>Set the <code>entry</code> element's <code>key</code>
attribute to <code>mtom-enabled</code>.</li><li>Set the <code>entry</code>
element's <code>value</code> attribute to <code>true</code>.</li></ol><h4
id="MTOM-Example">Example</h4><p>The following example s
 hows an endpoint that is MTOM enabled.</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Configuration
for Enabling MTOM</b></div><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">&lt;beans
xmlns="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:jaxws="http://cxf.apache.org/jaxws"
        xsi:schemaLocation="http://www.springframework.org/schema/beans



Mime
View raw message