KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > xml > rpc > handler > Handler


1 /*
2  * Copyright 2001-2004 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package javax.xml.rpc.handler;
17
18 import javax.xml.namespace.QName JavaDoc;
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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc[] getHeaders();
206 }
207
208
Popular Tags