001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *  http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing,
013     * software distributed under the License is distributed on an
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     * KIND, either express or implied.  See the License for the
016     * specific language governing permissions and limitations
017     * under the License.
018     */
019    
020    package javax.xml.rpc.handler;
021    
022    import javax.xml.namespace.QName;
023    
024    /**
025     * The <code>javax.xml.rpc.handler.Handler</code> interface is
026     * required to be implemented by a SOAP message handler. The
027     * <code>handleRequest</code>, <code>handleResponse</code>
028     * and <code>handleFault</code> methods for a SOAP message
029     * handler get access to the <code>SOAPMessage</code> from the
030     * <code>SOAPMessageContext</code>. The implementation of these
031     * methods can modify the <code>SOAPMessage</code> including the
032     * headers and body elements.
033     *
034     * @version $Rev: 467553 $ $Date: 2006-10-25 00:01:51 -0400 (Wed, 25 Oct 2006) $
035     */
036    public interface Handler {
037    
038        /**
039         * The <code>handleRequest</code> method processes the request message.
040         *
041         * @param context MessageContext parameter provides access to the request
042         *                  message.
043         * @return boolean boolean Indicates the processing mode
044         *            <ul>
045         *            <li>Return <code>true</code> to indicate continued
046         *                processing of the request handler chain. The
047         *                <code>HandlerChain</code>
048         *                takes the responsibility of invoking the next
049         *                entity. The next entity may be the next handler
050         *                in the <code>HandlerChain</code> or if this
051         *                handler is the last handler in the chain, the
052         *                next entity is the service endpoint object.
053         *            <li>Return <code>false</code> to indicate blocking
054         *                of the request handler chain. In this case,
055         *                further processing of the request handler chain
056         *                is blocked and the target service endpoint is
057         *                not dispatched. The JAX-RPC runtime system takes
058         *                the responsibility of invoking the response
059         *                handler chain next with the SOAPMessageContext.
060         *                The Handler implementation class has the the
061         *                responsibility of setting the appropriate response
062         *                SOAP message in either handleRequest and/or
063         *                handleResponse method. In the default processing
064         *                model, the response handler chain starts processing
065         *                from the same Handler instance (that returned false)
066         *                and goes backward in the execution sequence.
067         *             </ul>
068         *
069         * @throws javax.xml.rpc.JAXRPCException
070         *                indicates a handler-specific
071         *                runtime error. If <code>JAXRPCException</code> is thrown
072         *                by a handleRequest method, the HandlerChain
073         *                terminates the further processing of this handler
074         *                chain. On the server side, the HandlerChain
075         *                generates a SOAP fault that indicates that the
076         *                message could not be processed for reasons not
077         *                directly attributable to the contents of the
078         *                message itself but rather to a runtime error
079         *                during the processing of the message. On the
080         *                client side, the exception is propagated to
081         *                the client code
082         * @throws javax.xml.rpc.soap.SOAPFaultException
083         *                indicates a SOAP fault. The Handler
084         *                implementation class has the the responsibility
085         *                of setting the SOAP fault in the SOAP message in
086         *                either handleRequest and/or handleFault method.
087         *                If SOAPFaultException is thrown by a server-side
088         *                request handler's handleRequest method, the
089         *                HandlerChain terminates the further processing
090         *                of the request handlers in this handler chain
091         *                and invokes the handleFault method on the
092         *                HandlerChain with the SOAP message context. Next,
093         *                the HandlerChain invokes the handleFault method
094         *                on handlers registered in the handler chain,
095         *                beginning with the Handler instance that threw
096         *                the exception and going backward in execution. The
097         *                client-side request handler's handleRequest method
098         *                should not throw the SOAPFaultException.
099         */
100        public boolean handleRequest(MessageContext context);
101    
102        /**
103         * The <code>handleResponse</code> method processes the response SOAP message.
104         *
105         * @param context MessageContext parameter provides access to
106         *            the response SOAP message
107         *
108         * @return boolean Indicates the processing mode
109         *            <ul>
110         *            <li>Return <code>true</code> to indicate continued
111         *                processing ofthe response handler chain. The
112         *                HandlerChain invokes the <code>handleResponse</code>
113         *                method on the next <code>Handler</code> in
114         *                the handler chain.
115         *            <li>Return <code>false</code> to indicate blocking
116         *                of the response handler chain. In this case, no
117         *                other response handlers in the handler chain
118         *                are invoked.
119         *            </ul>
120         *
121         * @throws javax.xml.rpc.JAXRPCException
122         *                indicates a handler specific runtime error.
123         *                If JAXRPCException is thrown by a handleResponse
124         *                method, the HandlerChain terminates the further
125         *                processing of this handler chain. On the server side,
126         *                the HandlerChain generates a SOAP fault that
127         *                indicates that the message could not be processed
128         *                for reasons not directly attributable to the contents
129         *                of the message itself but rather to a runtime error
130         *                during the processing of the message. On the client
131         *                side, the runtime exception is propagated to the
132         *                client code.
133         */
134        public boolean handleResponse(MessageContext context);
135    
136        /**
137         * The <code>handleFault</code> method processes the SOAP faults
138         * based on the SOAP message processing model.
139         *
140         * @param  context MessageContext parameter provides access to
141         *            the SOAP message
142         * @return boolean Indicates the processing mode
143         *            <ul>
144         *            <li>Return <code>true</code> to indicate continued
145         *                processing of SOAP Fault. The HandlerChain invokes
146         *                the <code>handleFault</code> method on the
147         *                next <code>Handler</code> in the handler chain.
148         *            <li>Return <code>false</code> to indicate end
149         *                of the SOAP fault processing. In this case, no
150         *                other handlers in the handler chain
151         *                are invoked.
152         *            </ul>
153         * @throws javax.xml.rpc.JAXRPCException indicates handler specific runtime
154         *                error. If JAXRPCException is thrown by a handleFault
155         *                method, the HandlerChain terminates the further
156         *                processing of this handler chain. On the server side,
157         *                the HandlerChain generates a SOAP fault that
158         *                indicates that the message could not be processed
159         *                for reasons not directly attributable to the contents
160         *                of the message itself but rather to a runtime error
161         *                during the processing of the message. On the client
162         *                side, the JAXRPCException is propagated to the
163         *                client code.
164         */
165        public boolean handleFault(MessageContext context);
166    
167        /**
168         * The <code>init</code> method enables the Handler instance to
169         * initialize itself. The <code>init</code> method passes the
170         * handler configuration as a <code>HandlerInfo</code> instance.
171         * The HandlerInfo is used to configure the Handler (for example:
172         * setup access to an external resource or service) during the
173         * initialization.
174         * <p>
175         * In the init method, the Handler class may get access to
176         * any resources (for example; access to a logging service or
177         * database) and maintain these as part of its instance variables.
178         * Note that these instance variables must not have any state
179         * specific to the SOAP message processing performed in the
180         * various handle method.
181         *
182         * @param config HandlerInfo configuration for the initialization of this
183         *              handler
184         *
185         * @param config
186         * @throws javax.xml.rpc.JAXRPCException if initialization of the handler
187         *              fails
188         */
189        public abstract void init(HandlerInfo config);
190    
191        /**
192         * The <code>destroy</code> method indicates the end of lifecycle
193         * for a Handler instance.  The Handler implementation class should
194         * release its resources and perform cleanup in the implementation
195         * of the <code>destroy</code> method.
196         *
197         * @throws  javax.xml.rpc.JAXRPCException  if there was any error during
198         *              destroy
199         */
200        public abstract void destroy();
201    
202        /**
203         * Gets the header blocks processed by this Handler instance.
204         *
205         * @return Array of QNames of header blocks processed by this
206         *      handler instance. <code>QName</code> is the qualified
207         *      name of the outermost element of the Header block.
208         */
209        public QName[] getHeaders();
210    }
211