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