001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 */ 019 020 package javax.xml.rpc.handler; 021 022 import javax.xml.namespace.QName; 023 024 /** 025 * The <code>javax.xml.rpc.handler.Handler</code> interface is 026 * required to be implemented by a SOAP message handler. The 027 * <code>handleRequest</code>, <code>handleResponse</code> 028 * and <code>handleFault</code> methods for a SOAP message 029 * handler get access to the <code>SOAPMessage</code> from the 030 * <code>SOAPMessageContext</code>. The implementation of these 031 * methods can modify the <code>SOAPMessage</code> including the 032 * headers and body elements. 033 * 034 * @version $Rev: 467553 $ $Date: 2006-10-25 00:01:51 -0400 (Wed, 25 Oct 2006) $ 035 */ 036 public interface Handler { 037 038 /** 039 * The <code>handleRequest</code> method processes the request message. 040 * 041 * @param context MessageContext parameter provides access to the request 042 * message. 043 * @return boolean boolean Indicates the processing mode 044 * <ul> 045 * <li>Return <code>true</code> to indicate continued 046 * processing of the request handler chain. The 047 * <code>HandlerChain</code> 048 * takes the responsibility of invoking the next 049 * entity. The next entity may be the next handler 050 * in the <code>HandlerChain</code> or if this 051 * handler is the last handler in the chain, the 052 * next entity is the service endpoint object. 053 * <li>Return <code>false</code> to indicate blocking 054 * of the request handler chain. In this case, 055 * further processing of the request handler chain 056 * is blocked and the target service endpoint is 057 * not dispatched. The JAX-RPC runtime system takes 058 * the responsibility of invoking the response 059 * handler chain next with the SOAPMessageContext. 060 * The Handler implementation class has the the 061 * responsibility of setting the appropriate response 062 * SOAP message in either handleRequest and/or 063 * handleResponse method. In the default processing 064 * model, the response handler chain starts processing 065 * from the same Handler instance (that returned false) 066 * and goes backward in the execution sequence. 067 * </ul> 068 * 069 * @throws javax.xml.rpc.JAXRPCException 070 * indicates a handler-specific 071 * runtime error. If <code>JAXRPCException</code> is thrown 072 * by a handleRequest method, the HandlerChain 073 * terminates the further processing of this handler 074 * chain. On the server side, the HandlerChain 075 * generates a SOAP fault that indicates that the 076 * message could not be processed for reasons not 077 * directly attributable to the contents of the 078 * message itself but rather to a runtime error 079 * during the processing of the message. On the 080 * client side, the exception is propagated to 081 * the client code 082 * @throws javax.xml.rpc.soap.SOAPFaultException 083 * indicates a SOAP fault. The Handler 084 * implementation class has the the responsibility 085 * of setting the SOAP fault in the SOAP message in 086 * either handleRequest and/or handleFault method. 087 * If SOAPFaultException is thrown by a server-side 088 * request handler's handleRequest method, the 089 * HandlerChain terminates the further processing 090 * of the request handlers in this handler chain 091 * and invokes the handleFault method on the 092 * HandlerChain with the SOAP message context. Next, 093 * the HandlerChain invokes the handleFault method 094 * on handlers registered in the handler chain, 095 * beginning with the Handler instance that threw 096 * the exception and going backward in execution. The 097 * client-side request handler's handleRequest method 098 * should not throw the SOAPFaultException. 099 */ 100 public boolean handleRequest(MessageContext context); 101 102 /** 103 * The <code>handleResponse</code> method processes the response SOAP message. 104 * 105 * @param context MessageContext parameter provides access to 106 * the response SOAP message 107 * 108 * @return boolean Indicates the processing mode 109 * <ul> 110 * <li>Return <code>true</code> to indicate continued 111 * processing ofthe response handler chain. The 112 * HandlerChain invokes the <code>handleResponse</code> 113 * method on the next <code>Handler</code> in 114 * the handler chain. 115 * <li>Return <code>false</code> to indicate blocking 116 * of the response handler chain. In this case, no 117 * other response handlers in the handler chain 118 * are invoked. 119 * </ul> 120 * 121 * @throws javax.xml.rpc.JAXRPCException 122 * indicates a handler specific runtime error. 123 * If JAXRPCException is thrown by a handleResponse 124 * method, the HandlerChain terminates the further 125 * processing of this handler chain. On the server side, 126 * the HandlerChain generates a SOAP fault that 127 * indicates that the message could not be processed 128 * for reasons not directly attributable to the contents 129 * of the message itself but rather to a runtime error 130 * during the processing of the message. On the client 131 * side, the runtime exception is propagated to the 132 * client code. 133 */ 134 public boolean handleResponse(MessageContext context); 135 136 /** 137 * The <code>handleFault</code> method processes the SOAP faults 138 * based on the SOAP message processing model. 139 * 140 * @param context MessageContext parameter provides access to 141 * the SOAP message 142 * @return boolean Indicates the processing mode 143 * <ul> 144 * <li>Return <code>true</code> to indicate continued 145 * processing of SOAP Fault. The HandlerChain invokes 146 * the <code>handleFault</code> method on the 147 * next <code>Handler</code> in the handler chain. 148 * <li>Return <code>false</code> to indicate end 149 * of the SOAP fault processing. In this case, no 150 * other handlers in the handler chain 151 * are invoked. 152 * </ul> 153 * @throws javax.xml.rpc.JAXRPCException indicates handler specific runtime 154 * error. If JAXRPCException is thrown by a handleFault 155 * method, the HandlerChain terminates the further 156 * processing of this handler chain. On the server side, 157 * the HandlerChain generates a SOAP fault that 158 * indicates that the message could not be processed 159 * for reasons not directly attributable to the contents 160 * of the message itself but rather to a runtime error 161 * during the processing of the message. On the client 162 * side, the JAXRPCException is propagated to the 163 * client code. 164 */ 165 public boolean handleFault(MessageContext context); 166 167 /** 168 * The <code>init</code> method enables the Handler instance to 169 * initialize itself. The <code>init</code> method passes the 170 * handler configuration as a <code>HandlerInfo</code> instance. 171 * The HandlerInfo is used to configure the Handler (for example: 172 * setup access to an external resource or service) during the 173 * initialization. 174 * <p> 175 * In the init method, the Handler class may get access to 176 * any resources (for example; access to a logging service or 177 * database) and maintain these as part of its instance variables. 178 * Note that these instance variables must not have any state 179 * specific to the SOAP message processing performed in the 180 * various handle method. 181 * 182 * @param config HandlerInfo configuration for the initialization of this 183 * handler 184 * 185 * @param config 186 * @throws javax.xml.rpc.JAXRPCException if initialization of the handler 187 * fails 188 */ 189 public abstract void init(HandlerInfo config); 190 191 /** 192 * The <code>destroy</code> method indicates the end of lifecycle 193 * for a Handler instance. The Handler implementation class should 194 * release its resources and perform cleanup in the implementation 195 * of the <code>destroy</code> method. 196 * 197 * @throws javax.xml.rpc.JAXRPCException if there was any error during 198 * destroy 199 */ 200 public abstract void destroy(); 201 202 /** 203 * Gets the header blocks processed by this Handler instance. 204 * 205 * @return Array of QNames of header blocks processed by this 206 * handler instance. <code>QName</code> is the qualified 207 * name of the outermost element of the Header block. 208 */ 209 public QName[] getHeaders(); 210 } 211