Allow for extension classes to post-process generated XML

[mauromol]

This change allows for any java-saml consumer to extend the standard
classes used to generate SAML messages (AuthnRequest, LogoutRequest and
LogoutResponse), as well as the metadata, and provide their own logic to
post-process the default XML produced by java-saml. Any extension class
will then be able to transform or enrich the generated XML as required,
before the framework applies encoding, encryption or signing.

This is the implementation of the idea I was thinking of when writing #265 (comment). I think this is the most non-instrusive and not too dirty way to let java-saml be extended by consumers. Of course, this is just one step: if the consumer wants to use the Auth class as well, the other problem I mentioned in the above comment must be solved (please see #265 (comment) for a proposal).

[mauromol]

While using this feature myself to implement SPID, it emerged that postProcessXml may need to access input parameters, in particular when post processing outgoing messages (AuthRequest and LogoutRequest). This is made harder by the fact that postProcessXml is called at construction time: indeed, accessing the standard input parameters (which can be retrieved using the AuthnRequest and LogoutRequest getters) is not a problem, since the call to postProcessXml is made after basic class initialization has already been performed. However, if your custom extension of AuthRequest and/or LogoutRequest requires further input, this can be a problem.
If the approach described in #307 for AuthnRequest is accepted, the solution can be to pass the AuthnRequestParams input parameters to the postProcessXml (along with the original XML String): if custom input is required, a subclass of AuthnRequestParams may be implemented and postProcessXml may simply access the required information by casting the AuthnRequestParams object to the target expected type.

I can't add this change to this pull request right now, until the refactoring introduced in #307 is accepted. Here is just a preview: mauromol@c96a1d4 (but a more comprehensive change should most probably increase the AuthnRequestParams getter visibility to public, otherwise accessing the input from postProcessXml would still be impossible).
This use case, though, shows another benefit we could get by applying such a refactoring.

An alternative but more invasive approach could be the following (I use the AuthnRequest example):

• store the AuthnRequestParams in a class field
• provide a getter that postProcessXml may use to retrieve the input parameters

However in this case, to avoid confusion, all the input-related getters in AuthnRequest (like isForceAuthn(), isPassive(), etc.) should then delegate to the corresponding methods of the stored input parameters (and perhaps they could possibly be deprecated): in fact, to maintain backward compatibility without going too deep in changing the current API, #307 lets AuthnRequest extend AuthnRequestParams directly.

[pitbulk]

I'm ok with the postProcessXml idea that will allow you to extend the behavior.

But I don't see why in each class you need to recover the settings.

If you are using the Auth class, you already have the getSettings method
If you executed the constructor of AuthnRequest, SamlResponse, LogoutRequest, LogoutResponse or Metadata.
You already provided the setting object on the constructor, so you still have it.

I believe that instead of adding settings to the class and create a return method, you could simply define postProcessXml as

protected String postProcessXml(Saml2Settings settings,  final String logoutResponseXml) {
    return logoutResponseXml;
}

That way you could even inject changes on the settings object

[mauromol]

I think that lowering the coupling between the message classes and the settings is a good idea, so adding the settings parameter to postProcessXml is a good solution and I can change it this way. Still it's a fact that all message classes already store the settings instance in a field, which is private and hence not accessible to subclasses. I can't look at the code right now, but I was wondering whether getting rid of this strong coupling would be viable or not.

[mauromol]

As a follow up to my previous comment, let's consider AuthnRequest for instance: the settings property was added in commit ac8ae33, my change only provides a protected getter available to subclasses to retrieve it.
This said, we may shape postProcessXml method similarly to generateSubstitutor, so letting it receive the settings instance as an input parameter. If you agree on this, I will adapt this PR.

[mauromol]

@pitbulk I made postProcessXml receive the settings directly, hence reverting the addition of the settings getters on all classes. I also rebased changes on current master.