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