← Back to branch summary

~ubuntu-branches/debian/squeeze/axis/squeeze

« back to all changes in this revision

Viewing changes to src/javax/xml/rpc/handler/Handler.java

  • Committer: Bazaar Package Importer
  • Author(s): Vladimír Lapáček
  • Date: 2006-09-06 22:31:39 UTC
  • Revision ID: james.westby@ubuntu.com-20060906223139-l7m5edxeositeppl
Tags: upstream-1.4
Import upstream version 1.4

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/javax/xml/rpc/handler/Handler.java
 
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;
 
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