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