1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package javax.xml.rpc.handler;
17
18 import javax.xml.namespace.QName;
19
20 /**
21 * The <code>javax.xml.rpc.handler.Handler</code> interface is
22 * required to be implemented by a SOAP message handler. The
23 * <code>handleRequest</code>, <code>handleResponse</code>
24 * and <code>handleFault</code> methods for a SOAP message
25 * handler get access to the <code>SOAPMessage</code> from the
26 * <code>SOAPMessageContext</code>. The implementation of these
27 * methods can modify the <code>SOAPMessage</code> including the
28 * headers and body elements.
29 *
30 * @version 1.0
31 */
32 public interface Handler {
33
34 /**
35 * The <code>handleRequest</code> method processes the request message.
36 *
37 * @param context MessageContext parameter provides access to the request
38 * message.
39 * @return boolean boolean Indicates the processing mode
40 * <ul>
41 * <li>Return <code>true</code> to indicate continued
42 * processing of the request handler chain. The
43 * <code>HandlerChain</code>
44 * takes the responsibility of invoking the next
45 * entity. The next entity may be the next handler
46 * in the <code>HandlerChain</code> or if this
47 * handler is the last handler in the chain, the
48 * next entity is the service endpoint object.
49 * <li>Return <code>false</code> to indicate blocking
50 * of the request handler chain. In this case,
51 * further processing of the request handler chain
52 * is blocked and the target service endpoint is
53 * not dispatched. The JAX-RPC runtime system takes
54 * the responsibility of invoking the response
55 * handler chain next with the SOAPMessageContext.
56 * The Handler implementation class has the the
57 * responsibility of setting the appropriate response
58 * SOAP message in either handleRequest and/or
59 * handleResponse method. In the default processing
60 * model, the response handler chain starts processing
61 * from the same Handler instance (that returned false)
62 * and goes backward in the execution sequence.
63 * </ul>
64 *
65 * @throws javax.xml.rpc.JAXRPCException
66 * indicates a handler-specific
67 * runtime error. If <code>JAXRPCException</code> is thrown
68 * by a handleRequest method, the HandlerChain
69 * terminates the further processing of this handler
70 * chain. On the server side, the HandlerChain
71 * generates a SOAP fault that indicates that the
72 * message could not be processed for reasons not
73 * directly attributable to the contents of the
74 * message itself but rather to a runtime error
75 * during the processing of the message. On the
76 * client side, the exception is propagated to
77 * the client code
78 * @throws javax.xml.rpc.soap.SOAPFaultException
79 * indicates a SOAP fault. The Handler
80 * implementation class has the the responsibility
81 * of setting the SOAP fault in the SOAP message in
82 * either handleRequest and/or handleFault method.
83 * If SOAPFaultException is thrown by a server-side
84 * request handler's handleRequest method, the
85 * HandlerChain terminates the further processing
86 * of the request handlers in this handler chain
87 * and invokes the handleFault method on the
88 * HandlerChain with the SOAP message context. Next,
89 * the HandlerChain invokes the handleFault method
90 * on handlers registered in the handler chain,
91 * beginning with the Handler instance that threw
92 * the exception and going backward in execution. The
93 * client-side request handler's handleRequest method
94 * should not throw the SOAPFaultException.
95 */
96 public boolean handleRequest(MessageContext context);
97
98 /**
99 * 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