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 java.util.List;
   25   import java.util.Map;
   26   
   27   import javax.xml.rpc.JAXRPCException;
   28   
   29   /** This interface represents a list of handlers. All elements in the
   30    * HandlerChain are of the type javax.xml.rpc.handler.Handler.
   31    * 
   32    * An implementation class for the HandlerChain interface abstracts the policy
   33    * and mechanism for the invocation of the registered handlers. 
   34    * 
   35    * @author Scott.Stark@jboss.org
   36    * @author Rahul Sharma (javadoc)
   37    */
   38   public interface HandlerChain extends List
   39   {
   40      /**
   41       * Initializes the configuration for a HandlerChain.
   42       * @param config Configuration for the initialization of this handler chain
   43       * @throws JAXRPCException If any error during initialization
   44       */
   45      public void init(Map config);
   46   
   47      /**
   48       * Indicates the end of lifecycle for a HandlerChain.
   49       * @throws JAXRPCException If any error during destroy
   50       */
   51      public void destroy();
   52   
   53      /**
   54       * Gets SOAP actor roles registered for this HandlerChain at this SOAP node. The returned array includes the
   55       * special SOAP actor next.
   56       * @return SOAP Actor roles as URIs
   57       */
   58      public String[] getRoles();
   59   
   60      /**
   61       * Sets SOAP Actor roles for this HandlerChain. This specifies the set of roles in which this HandlerChain is to act
   62       * for the SOAP message processing at this SOAP node. These roles assumed by a HandlerChain must be invariant during
   63       * the processing of an individual SOAP message through the HandlerChain.
   64       * <p/>
   65       * A HandlerChain always acts in the role of the special SOAP actor next. Refer to the SOAP specification for the
   66       * URI name for this special SOAP actor. There is no need to set this special role using this method.
   67       * @param soapActorNames URIs for SOAP actor name
   68       */
   69      public void setRoles(String[] soapActorNames);
   70   
   71      /**
   72       * The handleRequest method initiates the request processing for this handler chain.
   73       * @param msgContext MessageContext parameter provides access to the request SOAP message.
   74       * @return Returns true if all handlers in chain have been processed. Returns false if a handler in the chain returned false from its handleRequest method.
   75       * @throws JAXRPCException if any processing error happens
   76       */
   77      public boolean handleRequest(MessageContext msgContext);
   78   
   79      /**
   80       * The handleResponse method initiates the response processing for this handler chain.
   81       * @return Returns true if all handlers in chain have been processed. Returns false if a handler in the chain returned false from its handleRequest method.
   82       * @throws JAXRPCException if any processing error happens
   83       */
   84      public boolean handleResponse(MessageContext msgContext);
   85   
   86      /**
   87       * The handleFault method initiates the SOAP fault processing for this handler chain.
   88       * @return Returns true if all handlers in chain have been processed. Returns false if a handler in the chain returned false from its handleRequest method.
   89       * @throws JAXRPCException if any processing error happens
   90       */
   91      public boolean handleFault(MessageContext msgContext);
   92   }