[Ws Wiki] Update of "FrontPage/WsFx/refactor" by WernerDittmann

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Ws Wiki" for change notification.

The following page has been changed by WernerDittmann:
http://wiki.apache.org/ws/FrontPage/WsFx/refactor

New page:
The org.apache.ws.security.message directory contains new classes to handle WS
Security. The new classes have the same functionality as the old (depreceated)
classes but provide more flexibility to control the setup of the security
header. 

To minimize the migration effort every new class has a {{{build(...)}}} method that works
exactly as the known build method in the old classes. However, the new build
methods have slightly different method signatures.

The following table shows the old classes and their replacement with the new
classes. 

||''Old class''                            ||''New class''||
||WS``Add``Signature``Confirmation     ||WS``Sec``Signature``Confirmation||
||WS``Add``Timestamp                   || WS``Sec``Timestamp||
||WS``Base``Message                    || WS``Sec``Base||
||WS``Encrypt``Body                    || WS``Sec``Encrypt||
||WSS``Add``SAMLToken                  || WS``Sec``SAML``Token||
||WSS``Add``Username``Token            || WS``Sec``Username``Token||
||WS``Sign``Envelope                   || WS``Sec``Signature||
||WS``Sign``SAML``Envelope (in *.saml) || WS``Sec``Signature``SAML||


Because of the refactoring we need the new class {{{WSSecHeader}}} to instantiate a
WS Security header. The following code snippets show how to use the new
classes and how it compares to the old classes.

First the code snippet that shows the flow using the old classes:
{{{
Document doc = ....;

WSEncryptBody builder = new WSEncryptBody();
builder.setUserInfo("wss4jcert");
builder.setKeyIdentifierType(WSConstants.X509_KEY_IDENTIFIER);
builder.setSymmetricEncAlgorithm(WSConstants.TRIPLE_DES);
Document encryptedDoc = builder.build(doc, crypto);
}}}

And here the flow with the new classes:

{{{
Document doc = .... ;
WSSecEncrypt builder = new WSSecEncrypt();
builder.setUserInfo("wss4jcert");
builder.setKeyIdentifierType(WSConstants.BST_DIRECT_REFERENCE);
builder.setSymmetricEncAlgorithm(WSConstants.TRIPLE_DES);

WSSecHeader secHeader = new WSSecHeader();
secHeader.insertSecurityHeader(doc);

Document encryptedDoc = builder.build(doc, crypto, secHeader);
}}}

As you see you have to create the `WSSecHeader` and call its
{{{insertSecurityHeader(...)}}} method before you can call the build of {{{WSSecEncrypt}}}. The
build method requires the {{{WSSecHeader}}} as last parameter. The {{{WSSecHeader}}}
provides constructors and setter methods to initialize the actor/role and
mustUnderstand attributes.

'''The use of the old classes is depreceated.'''