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

package javax.xml.rpc.handler;

import javax.xml.namespace.QName;

/**
 * The <code>javax.xml.rpc.handler.Handler</code> interface is
 * required to be implemented by a SOAP message handler. The
 * <code>handleRequest</code>, <code>handleResponse</code>
 * and <code>handleFault</code> methods for a SOAP message
 * handler get access to the <code>SOAPMessage</code> from the
 * <code>SOAPMessageContext</code>. The implementation of these
 * methods can modify the <code>SOAPMessage</code> including the
 * headers and body elements.
 *
 * @version $Rev$ $Date$
 */
public interface Handler {

    /**
     * The <code>handleRequest</code> method processes the request message.
     *
     * @param context MessageContext parameter provides access to the request
     *                  message.
     * @return boolean boolean Indicates the processing mode
     *            <ul>
     *            <li>Return <code>true</code> to indicate continued
     *                processing of the request handler chain. The
     *                <code>HandlerChain</code>
     *                takes the responsibility of invoking the next
     *                entity. The next entity may be the next handler
     *                in the <code>HandlerChain</code> or if this
     *                handler is the last handler in the chain, the
     *                next entity is the service endpoint object.
     *            <li>Return <code>false</code> to indicate blocking
     *                of the request handler chain. In this case,
     *                further processing of the request handler chain
     *                is blocked and the target service endpoint is
     *                not dispatched. The JAX-RPC runtime system takes
     *                the responsibility of invoking the response
     *                handler chain next with the SOAPMessageContext.
     *                The Handler implementation class has the the
     *                responsibility of setting the appropriate response
     *                SOAP message in either handleRequest and/or
     *                handleResponse method. In the default processing
     *                model, the response handler chain starts processing
     *                from the same Handler instance (that returned false)
     *                and goes backward in the execution sequence.
     *             </ul>
     *
     * @throws javax.xml.rpc.JAXRPCException
     *                indicates a handler-specific
     *                runtime error. If <code>JAXRPCException</code> is thrown
     *                by a handleRequest method, the HandlerChain
     *                terminates the further processing of this handler
     *                chain. On the server side, the HandlerChain
     *                generates a SOAP fault that indicates that the
     *                message could not be processed for reasons not
     *                directly attributable to the contents of the
     *                message itself but rather to a runtime error
     *                during the processing of the message. On the
     *                client side, the exception is propagated to
     *                the client code
     * @throws javax.xml.rpc.soap.SOAPFaultException
     *                indicates a SOAP fault. The Handler
     *                implementation class has the the responsibility
     *                of setting the SOAP fault in the SOAP message in
     *                either handleRequest and/or handleFault method.
     *                If SOAPFaultException is thrown by a server-side
     *                request handler's handleRequest method, the
     *                HandlerChain terminates the further processing
     *                of the request handlers in this handler chain
     *                and invokes the handleFault method on the
     *                HandlerChain with the SOAP message context. Next,
     *                the HandlerChain invokes the handleFault method
     *                on handlers registered in the handler chain,
     *                beginning with the Handler instance that threw
     *                the exception and going backward in execution. The
     *                client-side request handler's handleRequest method
     *                should not throw the SOAPFaultException.
     */
    public boolean handleRequest(MessageContext context);

    /**
     * The <code>handleResponse</code> method processes the response SOAP message.
     *
     * @param context MessageContext parameter provides access to
     *            the response SOAP message
     *
     * @return boolean Indicates the processing mode
     *            <ul>
     *            <li>Return <code>true</code> to indicate continued
     *                processing ofthe response handler chain. The
     *                HandlerChain invokes the <code>handleResponse</code>
     *                method on the next <code>Handler</code> in
     *                the handler chain.
     *            <li>Return <code>false</code> to indicate blocking
     *                of the response handler chain. In this case, no
     *                other response handlers in the handler chain
     *                are invoked.
     *            </ul>
     *
     * @throws javax.xml.rpc.JAXRPCException
     *                indicates a handler specific runtime error.
     *                If JAXRPCException is thrown by a handleResponse
     *                method, the HandlerChain terminates the further
     *                processing of this handler chain. On the server side,
     *                the HandlerChain generates a SOAP fault that
     *                indicates that the message could not be processed
     *                for reasons not directly attributable to the contents
     *                of the message itself but rather to a runtime error
     *                during the processing of the message. On the client
     *                side, the runtime exception is propagated to the
     *                client code.
     */
    public boolean handleResponse(MessageContext context);

    /**
     * The <code>handleFault</code> method processes the SOAP faults
     * based on the SOAP message processing model.
     *
     * @param  context MessageContext parameter provides access to
     *            the SOAP message
     * @return boolean Indicates the processing mode
     *            <ul>
     *            <li>Return <code>true</code> to indicate continued
     *                processing of SOAP Fault. The HandlerChain invokes
     *                the <code>handleFault</code> method on the
     *                next <code>Handler</code> in the handler chain.
     *            <li>Return <code>false</code> to indicate end
     *                of the SOAP fault processing. In this case, no
     *                other handlers in the handler chain
     *                are invoked.
     *            </ul>
     * @throws javax.xml.rpc.JAXRPCException indicates handler specific runtime
     *                error. If JAXRPCException is thrown by a handleFault
     *                method, the HandlerChain terminates the further
     *                processing of this handler chain. On the server side,
     *                the HandlerChain generates a SOAP fault that
     *                indicates that the message could not be processed
     *                for reasons not directly attributable to the contents
     *                of the message itself but rather to a runtime error
     *                during the processing of the message. On the client
     *                side, the JAXRPCException is propagated to the
     *                client code.
     */
    public boolean handleFault(MessageContext context);

    /**
     * The <code>init</code> method enables the Handler instance to
     * initialize itself. The <code>init</code> method passes the
     * handler configuration as a <code>HandlerInfo</code> instance.
     * The HandlerInfo is used to configure the Handler (for example:
     * setup access to an external resource or service) during the
     * initialization.
     * <p>
     * In the init method, the Handler class may get access to
     * any resources (for example; access to a logging service or
     * database) and maintain these as part of its instance variables.
     * Note that these instance variables must not have any state
     * specific to the SOAP message processing performed in the
     * various handle method.
     *
     * @param config HandlerInfo configuration for the initialization of this
     *              handler
     *
     * @param config
     * @throws javax.xml.rpc.JAXRPCException if initialization of the handler
     *              fails
     */
    public abstract void init(HandlerInfo config);

    /**
     * The <code>destroy</code> method indicates the end of lifecycle
     * for a Handler instance.  The Handler implementation class should
     * release its resources and perform cleanup in the implementation
     * of the <code>destroy</code> method.
     *
     * @throws  javax.xml.rpc.JAXRPCException  if there was any error during
     *              destroy
     */
    public abstract void destroy();

    /**
     * Gets the header blocks processed by this Handler instance.
     *
     * @return Array of QNames of header blocks processed by this
     *      handler instance. <code>QName</code> is the qualified
     *      name of the outermost element of the Header block.
     */
    public QName[] getHeaders();
}