//
// 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.
//

=== Apache WSS4J 2.1.0 Migration Guide

This section is a migration guide for helping Apache WSS4J 2.0.x users to migrate
to the 2.1.x releases. 

==== JDK7 minimum requirement

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.

==== OpenSAML 3.x migration

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.

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 https://github.com/apache/ws-wss4j/tree/master/ws-security-common/src/main/java/org/apache/wss4j/common/saml/bean/Version.java[Version] bean. See
https://github.com/apache/ws-wss4j/tree/master/ws-security-dom/src/test/java/org/apache/wss4j/dom/common/SAML2CallbackHandler.java[here] for an example.

==== Custom processor changes

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.