Author: buildbot
Date: Wed Jun 11 15:46:48 2014
New Revision: 912252
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/30-migration-guide.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/cxf/content/docs/30-migration-guide.html
==============================================================================
--- websites/production/cxf/content/docs/30-migration-guide.html (original)
+++ websites/production/cxf/content/docs/30-migration-guide.html Wed Jun 11
15:46:48 2014
@@ -107,7 +107,7 @@ Apache CXF -- 3.0 Migration Guide
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"><h2
id="id-3.0MigrationGuide-3.0MigrationGuide">3.0 Migration Guide</h2><h4
id="id-3.0MigrationGuide-JAX-RS">JAX-RS</h4><ul><li>JAX-RS 2.0 has been
completely implemented.</li><li>JAX-RS WADL auto-generation code has been moved
to a new cxf-rt-rs-service-description module.</li><li>JAX-RS 2.0 Client API
and CXF specific WebClient and Proxy client code is now available in a new
cxf-rt-rs-client module. Important: the namespace for jaxrs:client elements has
changed from "http://cxf.apache.org/jaxrs"; to
"http://cxf.apache.org/jaxrs-client";</li><li>CXF RequestHandler and
ResponseHandler filters have been removed, please use JAX-RS 2.0
ContainerRequestFilter and ContainerResponseFilter and also WriterInterceptor
and ReaderInterceptor when needed.</li><li>CXF JAX-RS Form extension has been
dropped, please use JAX-RS 2.0 Form.</li><li>CXF JAX-RS ParameterHandler has
been dropped, please use JAX-RS 2.0 ParamConverterProvider.</li></ul><h4
id="id-3.0MigrationGuide
-JAX-WS/Soap">JAX-WS/Soap</h4><ul><li>Add new code generator frontend to add
CXF specific constructors and methods. (pass "-fe cxf" to
wsdl2java)</li><li>Make AbstractFeature subclass WebServiceFeature and update
the JAX-WS frontend to look for them.</li><li>"jaxb-validation-event-handler"s
now apply for both Reading and Writing. (previously only applied to Reading).
There are separate jaxb-(reader|writer)-validation-event-handler properties if
you need it set for only one direction.</li><li>If the WSDL location that is
passed into CXF is not valid, previous versions of CXF *MAY* ignore the error
and proceed as if "null" was passed for the WSDL.   3.0 will now throw an
exception.</li><li>ClientProxy.getClient(proxy) is no longer needed for most
use cases.  The client proxy instances now implement the Client API
directly.   A direct cast to Client should work.</li></ul><h4
id="id-3.0MigrationGuide-Transports">Transports</h4><ul><li>Support for the
older JMS 1.0.2 API's
has been removed.   Your JMS provider must support the 1.1
API's. </li><li>A new WebSocket based transport has been
added</li><li>Support for Netty based HTTP servers and clients has been
added</li></ul><h4 id="id-3.0MigrationGuide-BeanValidation">Bean
Validation</h4><p>Bean Validation 1.1 interceptors and features have been
introduced for JAX-RS and JAX-WS frontends.</p><h4
id="id-3.0MigrationGuide-WS-Security">WS-Security</h4><ul><li>The
DefaultCryptoCoverageChecker now contains boolean properties to easily check if
a WSS UsernameToken was signed and/or encrypted. The default is now that a
UsernameToken must be encrypted.</li><li>CXF 3.0.x picks up a new major version
of Apache WSS4J (2.0.0). There are some changes in this release which will
impact on existing CXF users. These changes are extensively summarized in the
<a shape="rect" class="external-link"
href="http://ws.apache.org/wss4j/migration.html";>WSS4J 2.0.0 Migration
Guide</a>. The major changes are as follows:<
br clear="none"><ul><li>If you have implemented a CallbackHandler to
set/retrieve passwords for UsernameTokens/Signatures/Decryption/etc., then the
namespace of the WSPasswordCallback Object has changed from
"org.apache.ws.security" to "org.apache.wss4j.common.ext".</li><li>If you have
implemented a CallbackHandler to create SAML Assertions, then the namespace of
the SAML bean objects has changed from "org.apache.ws.security.saml.ext" to
"org.apache.wss4j.common.saml". </li><li>WSS4J 1.6.x used a saml
properties file to sign a SAML Assertion. This has been removed in WSS4J 2.0.0.
Instead the SAMLCallback Object contains additional properties that can be set
to sign the Assertion. Please see the section entitled "SAML Assertion changes"
in the <a shape="rect" class="external-link"
href="http://ws.apache.org/wss4j/migration.html";>WSS4J 2.0.0 Migration
Guide</a> for more information on this.</li><li>A small number of configuration
tags have been removed in WSS4J 2.0.0. Please
see the section entitled "Removed Configuration Tags in WSS4J 2.0.0" in
the <a shape="rect" class="external-link"
href="http://ws.apache.org/wss4j/migration.html";>WSS4J 2.0.0 Migration
Guide</a> for more information on this.</li><li>The default namespace for
derived keys and secure conversation is now  "<span
class="nolink">http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512</span>".
The older namespace can be used instead via a new configuration
tag.</li><li>The RSA v1.5 Key Transport algorithm is no longer allowed by
default. This can be changed via a configuration tag.</li><li>Turning off BSP
(Basic Security Profile) Compliance (Basic Security Profile) on the outbound
side no longer has the effect of disabling the addition of a
InclusiveNamespaces PrefixList when signing a portion of the message. This is
now controlled by a separate configuration tag in WSS4J
2.0.0.</li></ul></li><li>In addition to the changes above, CXF 3.0.0 fully
supports the new streaming
(StAX-based) WS-Security implementation in WSS4J 2.0.0.</li><li>To switch to
use the streaming code for the manual "Action" based approach, simply change
the outbound and inbound interceptors as
follows:<ul><li>"org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor" to
"org.apache.cxf.ws.security.wss4j.WSS4JStaxOutInterceptor".</li><li>"org.apache.cxf.ws.security.wss4j.WSS4JInInterceptor"
to
"org.apache.cxf.ws.security.wss4j.WSS4JStaxInInterceptor".</li></ul></li><li>For
the WS-SecurityPolicy based approach of configuring WS-Security, simply set
the JAX-WS property SecurityConstants.ENABLE_STREAMING_SECURITY
("ws-security.enable.streaming") to "true". For more information on the
streaming functionality available in WSS4J 2.0.0, please see the <a
shape="rect" class="external-link"
href="http://ws.apache.org/wss4j/streaming.html";>streaming documentation</a>
page of WSS4J.</li></ul><h4
id="id-3.0MigrationGuide-WS-ReliableMessaging">WS-ReliableMessaging</h4><ul><li>The
WS-RM subsystem h
as been updated to more completely implement the 1.1 specification.
 </li><li>Closing a client proxy via ((Closable)proxy).close() will now
terminate open sequences.</li></ul><h4
id="id-3.0MigrationGuide-Majordependencychanges">Major dependency
changes</h4><ul><li>Spring 3.2 or newer is required.   The calls to the
API's that were deprecated in Spring 3.x have been removed.  This allows
CXF 3.0 to work with Spring 4, but means it can no longer with with Spring
2.5.</li></ul><h4 id="id-3.0MigrationGuide-CXFModule/JarChanges">CXF Module/Jar
Changes</h4><ul><li>Combined api/core into just a cxf-core. All "wsdl" related
stuff has been moved to a new cxf-wsdl bundle to remove the wsdl4j requirement
for JAX-RS applications.</li><li>Dropped support for Karaf 2.2.x. Karaf 2.3.x
is now required.</li><li>The direct dependency on a javax.mail implementation
has been removed and the CXF maven poms will not pull one in transitively
anymore. For MOST users, this is not a problem. H
owever, if your application uses MTOM or Soap w/Attachments or similar that
requires some of the DataContentHandlers that are part of the mail
implementations, you may need to re-add this to your
classpath.</li><li>DynamicClientFactory was moved from the JAXB databinding to
the Simple frontend. However, users are strongly encouraged to use the
JaxWsDynamicClientFactory subclass.</li><li>The large bundle jar has been
removed due to maintenance issues as well as new functionality not being usable
from the bundle jar.  Users should upgrade to the individual modules that
they need for their application.</li></ul><h4
id="id-3.0MigrationGuide-Removed/ChangedAPI's">Removed/Changed
API's</h4><ul><li>CXFBusImpl has been removed. The only subclass was the
ExtensionMangerBus (SpringBus and Blueprint/osgi stuff subclassed that) so the
functionality was pushed up into ExtensionMangerBus. Some of the "common"
methods were put directly on the Bus interface to make using the Bus cleaner
(no ca
sts to the impl).</li><li>The unused "run()" method on Bus was
removed.</li><li>Merge BaseDataReader/DataReader and the same for the writer
getting rid of the "Base" versions that are unreferenced.</li><li>The 2 unused
params on Destination.getBackChannel were removed. They were unused and
normally passed in as null.</li><li>Remove QueryHandlers -> these were
originally used for the ?wsdl processing (and is still used for ?js). However,
that stuff is better done directly on the interceptor chains as interceptors to
allow user supplied interceptors to also handle them. I'd like to just remove
these. (obviously update the ?js stuff) Would simplify the CXFServlet a
bit.</li><li>Removed all the /META-INF/cxf/cxf-extension-XYZ.xml files. They
have been deprecated an not needed for a long time.</li><li>Updated
ConduitInitiator and DestinationFactory to pass Bus as parameter to the various
methods.</li><li>Removed support for the old bus-extensions.xml file (in favor
of the current and
much faster bus-extensions.txt)</li><li>Move ALL XML parsing and writing to
StaxUtils and DOM based utilities to DOMUtils. The XMLUtils class that used SAX
based parsing and Transformer based writing has been eliminated. This
simplifies the code as well as increases security as we can provide better
limits and have more control with the StAX based
IO.</li><li>AddressingProperties has been turned from an interface to a
concrete class that can be created directly with "new".
AddressingPropertiesImpl has been removed.</li><li>Many of our
interfaces/classes that held onto constants were either removed or moved. In
particular XmlSchemaConstants was removed (use the Constants from the XmlSchema
library directly), WSDLConstants was moved from api to rt-wsdl, SOAPConstants
was removed (most are available in WSDLConstants). Goal is to reduce some
memory usage and help startup time and reduce a lot of
duplication.</li><li>AlternativeSelector and the PolicyEngine and other
PolicyRelated classe
s have been updated to pass the current Message in (when appropriate) to allow
using message contextual information to select the alternative. HOWEVER, keep
in mind that the selected alternative is likely cached and thus if contextual
information changes, the alternatively may not be
recalculated.</li><li>FailoverTargetSelector will not activate the fail-over in
cases when HTTP client errors are returned, only HTTP 404 and 503 statuses will
be recognized. Set FailoverTargetSelector supportNotAvailableErrorsOnly
property to false if the support for all HTTP errors is
required.</li><li>ServletController will not override the endpoint addresses by
default as it has side-effects when a given endpoint is accessed via multiple
paths. Set CXFServlet "disable-address-updates" parameter to 'false' if
required.</li><li>The long since
deprecated org.apache.cxf.frontend.MethodDispatcher has been removed.
 (It was replaced
with org.apache.cxf.service.invoker.MethodDispatcher in 2.
6)</li><li>The deprecated JAXBToStringBuilder and JAXBToStringStyle
classes that were in cxf-rt-databindind-jaxb have been removed.  The
functionality has been provided by cxf-xjc-runtime for a while now.</li><li>The
deprecated URIMappingInterceptor has been removed.  This hasn't been
on the default chain for some time due to a bunch of security related
issues.</li><li>SchemaValidation annotation has had its deprecated "enabled"
property removed. Please use its "type" property to control the
validation.</li><li>The "Spring" type was removed from the FactoryType
annotation.  Instead, use factoryClass=<span style="line-height:
1.4285715;">SpringBeanFactory.class.</span></li></ul></div>
+<div id="ConfluenceContent"><h2
id="id-3.0MigrationGuide-3.0MigrationGuide">3.0 Migration Guide</h2><h4
id="id-3.0MigrationGuide-JAX-RS">JAX-RS</h4><ul><li>JAX-RS 2.0 has been
completely implemented.</li><li>JAX-RS WADL auto-generation code has been moved
to a new cxf-rt-rs-service-description module.</li><li>JAX-RS 2.0 Client API
and CXF specific WebClient and Proxy client code is now available in a new
cxf-rt-rs-client module. Important: the namespace for jaxrs:client elements has
changed from "http://cxf.apache.org/jaxrs"; to
"http://cxf.apache.org/jaxrs-client";</li><li>CXF RequestHandler and
ResponseHandler filters have been removed, please use JAX-RS 2.0
ContainerRequestFilter and ContainerResponseFilter and also WriterInterceptor
and ReaderInterceptor when needed.</li><li>CXF JAX-RS Form extension has been
dropped, please use JAX-RS 2.0 Form.</li><li>CXF JAX-RS ParameterHandler has
been dropped, please use JAX-RS 2.0 ParamConverterProvider.</li></ul><h4
id="id-3.0MigrationGuide
-JAX-WS/Soap">JAX-WS/Soap</h4><ul><li>Add new code generator frontend to add
CXF specific constructors and methods. (pass "-fe cxf" to
wsdl2java)</li><li>Make AbstractFeature subclass WebServiceFeature and update
the JAX-WS frontend to look for them.</li><li>"jaxb-validation-event-handler"s
now apply for both Reading and Writing. (previously only applied to Reading).
There are separate jaxb-(reader|writer)-validation-event-handler properties if
you need it set for only one direction.</li><li>If the WSDL location that is
passed into CXF is not valid, previous versions of CXF *MAY* ignore the error
and proceed as if "null" was passed for the WSDL.   3.0 will now throw an
exception.</li><li>ClientProxy.getClient(proxy) is no longer needed for most
use cases.  The client proxy instances now implement the Client API
directly.   A direct cast to Client should work.</li></ul><h4
id="id-3.0MigrationGuide-Transports">Transports</h4><ul><li>Support for the
older JMS 1.0.2 API's
has been removed.   Your JMS provider must support the 1.1
API's. </li><li>A new WebSocket based transport has been
added</li><li>Support for Netty based HTTP servers and clients has been
added</li></ul><h4 id="id-3.0MigrationGuide-BeanValidation">Bean
Validation</h4><p>Bean Validation 1.1 interceptors and features have been
introduced for JAX-RS and JAX-WS frontends.</p><h4
id="id-3.0MigrationGuide-WS-Security">WS-Security</h4><ul><li>The
DefaultCryptoCoverageChecker now contains boolean properties to easily check if
a WSS UsernameToken was signed and/or encrypted. The default is now that a
UsernameToken must be encrypted.</li><li>CXF 3.0.x picks up a new major version
of Apache WSS4J (2.0.0). There are some changes in this release which will
impact on existing CXF users. These changes are extensively summarized in the
<a shape="rect" class="external-link"
href="http://ws.apache.org/wss4j/migration.html";>WSS4J 2.0.0 Migration
Guide</a>. The major changes are as follows:<
br clear="none"><ul><li>If you have implemented a CallbackHandler to
set/retrieve passwords for UsernameTokens/Signatures/Decryption/etc., then the
namespace of the WSPasswordCallback Object has changed from
"org.apache.ws.security" to "org.apache.wss4j.common.ext".</li><li>If you have
implemented a CallbackHandler to create SAML Assertions, then the namespace of
the SAML bean objects has changed from "org.apache.ws.security.saml.ext" to
"org.apache.wss4j.common.saml". </li><li>WSS4J 1.6.x used a saml
properties file to sign a SAML Assertion. This has been removed in WSS4J 2.0.0.
Instead the SAMLCallback Object contains additional properties that can be set
to sign the Assertion. Please see the section entitled "SAML Assertion changes"
in the <a shape="rect" class="external-link"
href="http://ws.apache.org/wss4j/migration.html";>WSS4J 2.0.0 Migration
Guide</a> for more information on this.</li><li>A small number of configuration
tags have been removed in WSS4J 2.0.0. Please
see the section entitled "Removed Configuration Tags in WSS4J 2.0.0" in
the <a shape="rect" class="external-link"
href="http://ws.apache.org/wss4j/migration.html";>WSS4J 2.0.0 Migration
Guide</a> for more information on this.</li><li>The default namespace for
derived keys and secure conversation is now  "<span
class="nolink">http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512</span>".
The older namespace can be used instead via a new configuration
tag.</li><li>The RSA v1.5 Key Transport algorithm is no longer allowed by
default. This can be changed via a configuration tag.</li><li>Turning off BSP
(Basic Security Profile) Compliance (Basic Security Profile) on the outbound
side no longer has the effect of disabling the addition of a
InclusiveNamespaces PrefixList when signing a portion of the message. This is
now controlled by a separate configuration tag in WSS4J
2.0.0.</li></ul></li><li>In addition to the changes above, CXF 3.0.0 fully
supports the new streaming
(StAX-based) WS-Security implementation in WSS4J 2.0.0.</li><li>To switch to
use the streaming code for the manual "Action" based approach, simply change
the outbound and inbound interceptors as
follows:<ul><li>"org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor" to
"org.apache.cxf.ws.security.wss4j.WSS4JStaxOutInterceptor".</li><li>"org.apache.cxf.ws.security.wss4j.WSS4JInInterceptor"
to
"org.apache.cxf.ws.security.wss4j.WSS4JStaxInInterceptor".</li></ul></li><li>For
the WS-SecurityPolicy based approach of configuring WS-Security, simply set
the JAX-WS property SecurityConstants.ENABLE_STREAMING_SECURITY
("ws-security.enable.streaming") to "true". For more information on the
streaming functionality available in WSS4J 2.0.0, please see the <a
shape="rect" class="external-link"
href="http://ws.apache.org/wss4j/streaming.html";>streaming documentation</a>
page of WSS4J.</li></ul><h4
id="id-3.0MigrationGuide-WS-ReliableMessaging">WS-ReliableMessaging</h4><ul><li>The
WS-RM subsystem h
as been updated to more completely implement the 1.1 specification.
 </li><li>Closing a client proxy via ((Closable)proxy).close() will now
terminate open sequences.</li></ul><h4
id="id-3.0MigrationGuide-Majordependencychanges">Major dependency
changes</h4><ul><li>Spring 3.2 or newer is required.   The calls to the
API's that were deprecated in Spring 3.x have been removed.  This allows
CXF 3.0 to work with Spring 4, but means it can no longer work with Spring
2.5.</li></ul><h4 id="id-3.0MigrationGuide-CXFModule/JarChanges">CXF Module/Jar
Changes</h4><ul><li>Combined api/core into just a cxf-core. All "wsdl" related
stuff has been moved to a new cxf-wsdl bundle to remove the wsdl4j requirement
for JAX-RS applications.</li><li>Dropped support for Karaf 2.2.x. Karaf 2.3.x
is now required.</li><li>The direct dependency on a javax.mail implementation
has been removed and the CXF maven poms will not pull one in transitively
anymore. For MOST users, this is not a problem. H
owever, if your application uses MTOM or Soap w/Attachments or similar that
requires some of the DataContentHandlers that are part of the mail
implementations, you may need to re-add this to your
classpath.</li><li>DynamicClientFactory was moved from the JAXB databinding to
the Simple frontend. However, users are strongly encouraged to use the
JaxWsDynamicClientFactory subclass.</li><li>The large bundle jar has been
removed due to maintenance issues as well as new functionality not being usable
from the bundle jar.  Users should upgrade to the individual modules that
they need for their application.</li></ul><h4
id="id-3.0MigrationGuide-Removed/ChangedAPI's">Removed/Changed
API's</h4><ul><li>CXFBusImpl has been removed. The only subclass was the
ExtensionManagerBus (SpringBus and Blueprint/osgi stuff subclassed that) so the
functionality was pushed up into ExtensionManagerBus. Some of the "common"
methods were put directly on the Bus interface to make using the Bus cleaner
(no
casts to the impl).</li><li>The unused "run()" method on Bus was
removed.</li><li>Merge BaseDataReader/DataReader and the same for the writer,
getting rid of the "Base" versions that are unreferenced.</li><li>The 2 unused
params on Destination.getBackChannel were removed. They were unused and
normally passed in as null.</li><li>Remove QueryHandlers -> these were
originally used for the ?wsdl processing (and is still used for ?js). However,
that stuff is better done directly on the interceptor chains as interceptors to
allow user supplied interceptors to also handle them. I'd like to just remove
these. (obviously update the ?js stuff) Would simplify the CXFServlet a
bit.</li><li>Removed all the /META-INF/cxf/cxf-extension-XYZ.xml files. They
have been deprecated and not needed for a long time.</li><li>Updated
ConduitInitiator and DestinationFactory to pass Bus as parameter to the various
methods.</li><li>Removed support for the old bus-extensions.xml file (in favor
of the current
and much faster bus-extensions.txt)</li><li>Move ALL XML parsing and writing
to StaxUtils and DOM based utilities to DOMUtils. The XMLUtils class that used
SAX based parsing and Transformer based writing has been eliminated. This
simplifies the code as well as increases security as we can provide better
limits and have more control with the StAX based
IO.</li><li>AddressingProperties has been turned from an interface to a
concrete class that can be created directly with "new".
AddressingPropertiesImpl has been removed.</li><li>Many of our
interfaces/classes that held onto constants were either removed or moved. In
particular XmlSchemaConstants was removed (use the Constants from the XmlSchema
library directly), WSDLConstants was moved from api to rt-wsdl, SOAPConstants
was removed (most are available in WSDLConstants). Goal is to reduce some
memory usage and help startup time and reduce a lot of
duplication.</li><li>AlternativeSelector and the PolicyEngine and other
PolicyRelated cl
asses have been updated to pass the current Message in (when appropriate) to
allow using message contextual information to select the alternative. HOWEVER,
keep in mind that the selected alternative is likely cached and thus if
contextual information changes, the alternative may not be
recalculated.</li><li>FailoverTargetSelector will not activate the fail-over in
cases when HTTP client errors are returned, only HTTP 404 and 503 statuses will
be recognized. Set FailoverTargetSelector supportNotAvailableErrorsOnly
property to false if the support for all HTTP errors is
required.</li><li>ServletController will not override the endpoint addresses by
default as it has side-effects when a given endpoint is accessed via multiple
paths. Set CXFServlet "disable-address-updates" parameter to 'false' if
required.</li><li>The long since
deprecated org.apache.cxf.frontend.MethodDispatcher has been removed.
 (It was replaced
with org.apache.cxf.service.invoker.MethodDispatcher in
2.6)</li><li>The deprecated JAXBToStringBuilder
and JAXBToStringStyle classes that were in cxf-rt-databinding-jaxb have
been removed.  The functionality has been provided by cxf-xjc-runtime for
a while now.</li><li>The deprecated URIMappingInterceptor has been
removed.  This hasn't been on the default chain for some time due to a
bunch of security related issues.</li><li>SchemaValidation annotation has had
its deprecated "enabled" property removed. Please use its "type" property to
control the validation.</li><li>The "Spring" type was removed from the
FactoryType annotation.  Instead, use factoryClass=<span
style="line-height: 1.4285715;">SpringBeanFactory.class.</span></li></ul></div>
</div>
<!-- Content -->
</td>
