SAMLSOAPBinding.java

/*
 *  Copyright 2001-2005 Internet2
 * 
 * Licensed 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.
 */

package gov.nih.nci.cagrid.opensaml;

import org.w3c.dom.Element;

/**
 *  Interface for SAML SOAP binding implementations. The addHook method must
 *  be synchronized by the caller with respect to other binding methods.
 *
 * @author     Scott Cantor
 * @created    February 3, 2005
 */
public interface SAMLSOAPBinding extends SAMLBinding
{
    
    /**
     *  Callback interface provided by client application enabling post-construction
     *  modification or examination of SOAP envelope. For example,
     *  a caller may embed security information and/or sign the envelope,
     *  or insert additional headers as required.
     * 
     * @author Scott Cantor
     */
    public interface SOAPHook {
        
        /**
         *  Callback hook enabling incoming envelope examination.
         * 
         * @param envelope  The SOAP envelope after insertion of the SAML protocol message
         * @param globalCtx  Context data to pass to registered hooks on each call
         * @param  callCtx         Context data to pass to registered hooks for this call
         * @return  true iff receipt of message should proceed
         * @throws  SAMLException   Raised by hook if an error occurs, aborts receipt
         */
        public abstract boolean incoming(Element envelope, Object globalCtx, Object callCtx)
            throws SAMLException;

        /**
         *  Callback hook enabling outgoing envelope modification.
         * 
         * @param envelope  The SOAP envelope after insertion of the SAML protocol message
         * @param globalCtx  Context data to pass to registered hooks on each call
         * @param  callCtx         Context data to pass to registered hooks for this call
         * @return  true iff transmission of message should proceed
         * @throws  SAMLException   Raised by hook if an error occurs, aborts transmission
         */
        public abstract boolean outgoing(Element envelope, Object globalCtx, Object callCtx)
            throws SAMLException;
    }
    
    /**
     *  Packages a SAML request for transmission via SOAP
     * 
     * @param request   The SAML request to prepare
     * @param callCtx   Context data to pass to registered hooks for this call
     * @return  A SOAP envelope compliant with the SOAP binding
     * @throws SAMLException    Raised if an error occurs in preparing the SOAP message
     */
    public abstract Element sendRequest(SAMLRequest request, Object callCtx)
        throws SAMLException;

    /**
     *  Unpacks a SAML request from a SOAP envelope
     * 
     * @param envelope  The SOAP envelope received
     * @param callCtx   Context data to pass to registered hooks for this call
     * @return  The SAML request received
     * @throws SAMLException    Raised if the SAML request cannot be unpacked successfully
     */
    public abstract SAMLRequest recvRequest(Element envelope, Object callCtx)
        throws SAMLException;
    
    /**
     *  Packages a SAML response for transmission via SOAP
     * 
     * @param response   The SAML response to prepare (may be null)
     * @param e         An exception to package for transmission as a SOAP fault
     * @param callCtx   Context data to pass to registered hooks for this call
     * @return  A SOAP envelope compliant with the SOAP binding
     * @throws SAMLException    Raised if an error occurs in preparing the SOAP message
     */
    public abstract Element sendResponse(SAMLResponse response, SAMLException e, Object callCtx)
        throws SAMLException;
    
    /**
     *  Unpacks a SAML response from a SOAP envelope
     * 
     * @param envelope  The SOAP envelope received
     * @param callCtx   Context data to pass to registered hooks for this call
     * @return  The SAML response received
     * @throws SAMLException    Raised if the SAML response cannot be unpacked successfully
     *      or if it contains an error
     */
    public abstract SAMLResponse recvResponse(Element envelope, Object callCtx) throws
        SAMLException;
    
    /**
     *  Attach a SOAP hook.
     *  
     * @param h Hook interface to attach
     */
    public abstract void addHook(SOAPHook h);

    /**
     *  Attach a SOAP hook.
     *  
     * @param h Hook interface to attach
     * @param globalCtx  Context data to pass to registered hooks on each call
     */
    public abstract void addHook(SOAPHook h, Object globalCtx);
}