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 java.util.List;
023    import java.util.Map;
024    
025    /**
026     * The <code>javax.xml.rpc.handler.HandlerChain</code> represents
027     * a list of handlers. All elements in the HandlerChain are of
028     * the type <code>javax.xml.rpc.handler.Handler</code>.
029     * <p>
030     * An implementation class for the <code>HandlerChain</code>
031     * interface abstracts the policy and mechanism for the invocation
032     * of the registered handlers.
033     *
034     * @version $Rev: 467553 $ $Date: 2006-10-25 00:01:51 -0400 (Wed, 25 Oct 2006) $
035     */
036    public interface HandlerChain extends List {
037    
038        /**
039         * The <code>handleRequest</code> method initiates the request
040         * processing for this handler chain.
041         * @param context MessageContext parameter provides access to
042         *             the request SOAP message.
043         * @return boolean Returns <code>true</code> if all handlers in
044         *             chain have been processed. Returns <code>false</code>
045         *
046         *             if a handler in the chain returned
047         *             <code>false</code> from its handleRequest
048         *             method.
049         * @throws javax.xml.rpc.JAXRPCException if any processing error happens
050         */
051        public boolean handleRequest(MessageContext context);
052    
053        /**
054         * The <code>handleResponse</code> method initiates the response
055         * processing for this handler chain.
056         *
057         * @param context MessageContext parameter provides access to the response
058         *                  SOAP message.
059         * @return boolean Returns <code>true</code> if all handlers in
060         *             chain have been processed. Returns <code>false</code>
061         *             if a handler in the chain returned
062         *             <code>false</code> from its handleResponse method.
063         * @throws javax.xml.rpc.JAXRPCException if any processing error happens
064         */
065        public boolean handleResponse(MessageContext context);
066    
067        /**
068         * The <code>handleFault</code> method initiates the SOAP
069         * fault processing for this handler chain.
070         *
071         * @param  context MessageContext parameter provides access to the SOAP
072         *         message.
073         * @return Returns boolean Returns <code>true</code> if all handlers in
074         *             chain have been processed. Returns <code>false</code>
075         *             if a handler in the chain returned
076         *             <code>false</code> from its handleFault method.
077         * @throws javax.xml.rpc.JAXRPCException if any processing error happens
078         */
079        public boolean handleFault(MessageContext context);
080    
081        /**
082         * Initializes the configuration for a HandlerChain.
083         *
084         * @param config Configuration for the initialization of this handler
085         *                 chain
086         *
087         * @throws javax.xml.rpc.JAXRPCException if there is any error that prevents
088         *              initialization
089         */
090        public void init(Map config);
091    
092        /**
093         * Indicates the end of lifecycle for a HandlerChain.
094         *
095         * @throws javax.xml.rpc.JAXRPCException if there was any error that
096         *              prevented destroy from completing
097         */
098        public void destroy();
099    
100        /**
101         * Sets SOAP Actor roles for this <code>HandlerChain</code>. This
102         * specifies the set of roles in which this HandlerChain is to act
103         * for the SOAP message processing at this SOAP node. These roles
104         * assumed by a HandlerChain must be invariant during the
105         * processing of an individual SOAP message through the HandlerChain.
106         * <p>
107         * A <code>HandlerChain</code> always acts in the role of the
108         * special SOAP actor <code>next</code>. Refer to the SOAP
109         * specification for the URI name for this special SOAP actor.
110         * There is no need to set this special role using this method.
111         *
112         * @param soapActorNames URIs for SOAP actor name
113         */
114        public void setRoles(String[] soapActorNames);
115    
116        /**
117         * Gets SOAP actor roles registered for this HandlerChain at
118         * this SOAP node. The returned array includes the special
119         * SOAP actor <code>next</code>.
120         * @return String[] SOAP Actor roles as URIs
121         */
122        public java.lang.String[] getRoles();
123    }
124