<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<document>
<body>
<section name="Apache WSS4J 2.1.0 Migration Guide">
<p>
This page is a migration guide for helping Apache WSS4J 2.0.x users to migrate
to the 2.1.x releases. 
</p>

<subsection name="JDK7 minimum requirement">
<p>
WSS4J 2.0.x required JDK6 as a minimum requirement. WSS4J 2.1.x requires at
least JDK7. The Xerces and xml-api dependencies have been removed from the DOM
code, as they are no longer required due to the JDK7 minimum requirement.
</p>
</subsection>

<subsection name="OpenSAML 3.x migration">
<p>
A key dependency change in WSS4J 2.1.0 is the upgrade from OpenSAML 2.x to
3.x (currently 3.1.0). OpenSAML 3.x contains a large number of package
changes. Therefore if you have any OpenSAML dependencies in a CallbackHandler
used to create SAML Assertions in WSS4J, code changes will be required.
</p>
<p>
The most common OpenSAML dependency is to include a "SAMLVersion" to tell
the SAMLCallback whether to create a SAML 2.0 or 1.1 Assertion. WSS4J 2.1
provides an alternative way of specifying the SAML Version, via a <a href="https://svn.apache.org/repos/asf/webservices/wss4j/trunk/ws-security-common/src/main/java/org/apache/wss4j/common/saml/bean/Version.java">Version</a> bean. See
<a href="https://svn.apache.org/repos/asf/webservices/wss4j/trunk/ws-security-dom/src/test/java/org/apache/wss4j/dom/common/SAML2CallbackHandler.java">here</a> for an example.
</p>
</subsection>

<subsection name="Custom processor changes">
<p>
If you have a custom Processor instance to process a token in the security
header in some custom way, you must add the WSSecurityEngineResult that is
generated by the processing, to the WSDocInfo Object via the "addResult"
method. Otherwise, it will not be available when security results are
retrieved and processed.
</p>
</subsection>

</section>
</body>
</document>
