Home » xml-commons-external-1.4.01-src » javax » xml » rpc » handler » [javadoc | source]

    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   }

Home » xml-commons-external-1.4.01-src » javax » xml » rpc » handler » [javadoc | source]