1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
/*
* JBoss, Home of Professional Open Source
* Copyright 2005, JBoss Inc., and individual contributors as indicated
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
* This is free software; you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation; either version 2.1 of
* the License, or (at your option) any later version.
*
* This software is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this software; if not, write to the Free
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
package javax.xml.rpc.handler;
import javax.xml.namespace.QName;
import javax.xml.rpc.JAXRPCException;
import javax.xml.rpc.soap.SOAPFaultException;
/** This interface is required to be implemented by a SOAP message handler.
* The handleRequest, handleResponse and handleFault methods for a SOAP message
* handler get access to the SOAPMessage from the SOAPMessageContext. The
* implementation of these methods can modify the SOAPMessage including the
* headers and body elements.
*
* @author Scott.Stark@jboss.org
* @author Rahul Sharma (javadoc)
* @version $Revision: 2897 $
*/
public interface Handler
{
/** Gets the header blocks processed by this Handler instance.
*
* @return Array of QNames of header blocks processed by this handler instance.
* QName is the qualified name of the outermost element of the Header block.
*/
public QName[] getHeaders();
/** The init method enables the Handler instance to initialize itself. The init method passes the handler
* configuration as a HandlerInfo instance. The HandlerInfo is used to configure the Handler (for example: setup
* access to an external resource or service) during the initialization.
* In the init method, the Handler class may get access to any resources
* (for example; access to a logging service or database) and maintain these as part of its instance variables.
* Note that these instance variables must not have any state specific to the SOAP message processing performed in
* the various handle method.
*
* @param config HandlerInfo configuration for the initialization of this handler
* @throws JAXRPCException - if initialization of the handler fails
*/
public void init(HandlerInfo config) throws JAXRPCException;
/** The destroy method indicates the end of lifecycle for a Handler instance. The Handler implementation class should
* release its resources and perform cleanup in the implementation of the destroy method.
*
* @throws JAXRPCException - if there was any error during destroy
*/
public void destroy() throws JAXRPCException;
/** The handleRequest method processes the request message.
*
* @param msgContext MessageContext parameter provides access to the request message.
* @return boolean boolean Indicates the processing mode
* <ul>
* <li> Return true to indicate continued processing of the request handler chain.
* The HandlerChain takes the responsibility of invoking the next entity.
* The next entity may be the next handler in the HandlerChain or if this handler is the last handler in the chain,
* the next entity is the service endpoint object. </li>
*
* <li> Return false to indicate blocking of the request handler chain. In this case, further processing of the request
* handler chain is blocked and the target service endpoint is not dispatched. The JAX-RPC runtime system takes the
* responsibility of invoking the response handler chain next with the SOAPMessageContext. The Handler implementation
* class has the the responsibility of setting the appropriate response SOAP message in either handleRequest and/or
* handleResponse method. In the default processing model, the response handler chain starts processing from the same
* Handler instance (that returned false) and goes backward in the execution sequence. </li>
* </ul>
*
* @throws JAXRPCException - indicates a handler-specific runtime error.
* If JAXRPCException is thrown by a handleRequest method, the HandlerChain terminates the further processing of this handler chain.
* On the server side, the HandlerChain generates a SOAP fault that indicates that the message could not be processed
* for reasons not directly attributable to the contents of the message itself but rather to a runtime error during
* the processing of the message. On the client side, the exception is propagated to the client code
*
* @throws SOAPFaultException - indicates a SOAP fault. The Handler implementation class has the the responsibility
* of setting the SOAP fault in the SOAP message in either handleRequest and/or handleFault method.
* If SOAPFaultException is thrown by a server-side request handler's handleRequest method, the HandlerChain
* terminates the further processing of the request handlers in this handler chain and invokes the handleFault
* method on the HandlerChain with the SOAP message msgContext. Next, the HandlerChain invokes the handleFault method
* on handlers registered in the handler chain, beginning with the Handler instance that threw the exception and
* going backward in execution. The client-side request handler's handleRequest method should not throw the SOAPFaultException.
*/
public boolean handleRequest(MessageContext msgContext) throws JAXRPCException, SOAPFaultException;
/** The handleResponse method processes the response SOAP message.
*
* @param msgContext MessageContext parameter provides access to the response SOAP message
* @return boolean Indicates the processing mode
* <ul>
* <li> Return true to indicate continued processing ofthe response handler chain. The HandlerChain invokes the handleResponse method on the next Handler in the handler chain.</li>
* <li>Return false to indicate blocking of the response handler chain. In this case, no other response handlers in the handler chain are invoked.</li>
* </ul>
* @throws JAXRPCException - indicates a handler specific runtime error. If JAXRPCException is thrown by a
* handleResponse method, the HandlerChain terminates the further processing of this handler chain. On the server
* side, the HandlerChain generates a SOAP fault that indicates that the message could not be processed for reasons
* not directly attributable to the contents of the message itself but rather to a runtime error during the processing
* of the message. On the client side, the runtime exception is propagated to the client code.
*/
public boolean handleResponse(MessageContext msgContext);
/** The handleFault method processes the SOAP faults based on the SOAP message processing model.
*
* @param msgContext MessageContext parameter provides access to the SOAP message
* @return boolean Indicates the processing mode
* <ul>
* <li> Return true to indicate continued processing of SOAP Fault. The HandlerChain invokes the handleFault method
* on the next Handler in the handler chain. </li>
* <li> Return false to indicate end of the SOAP fault processing. In this case, no other handlers in the handler
* chain are invoked. </li>
* </ul>
*
* @throws JAXRPCException - indicates handler specific runtime error.
* If JAXRPCException is thrown by a handleFault method, the HandlerChain terminates the further processing of this
* handler chain. On the server side, the HandlerChain generates a SOAP fault that indicates that the message could
* not be processed for reasons not directly attributable to the contents of the message itself but rather to a runtime
* error during the processing of the message. On the client side, the JAXRPCException is propagated to the client code.
*/
public boolean handleFault(MessageContext msgContext);
}
|
