001    /*
002     * Copyright 2001-2004 The Apache Software Foundation.
003     * 
004     * Licensed under the Apache License, Version 2.0 (the "License");
005     * you may not use this file except in compliance with the License.
006     * You may obtain a copy of the License at
007     * 
008     *      http://www.apache.org/licenses/LICENSE-2.0
009     * 
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS,
012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     * See the License for the specific language governing permissions and
014     * limitations under the License.
015     */
016    package javax.xml.rpc.handler;
017    
018    import javax.xml.namespace.QName;
019    import java.io.Serializable;
020    
021    /**
022     * The <code>javax.xml.rpc.handler.HandlerRegistry</code>
023     * provides support for the programmatic configuration of
024     * handlers in a <code>HandlerRegistry</code>.
025     * <p>
026     * A handler chain is registered per service endpoint, as
027     * indicated by the qualified name of a port. The getHandlerChain
028     * returns the handler chain (as a java.util.List) for the
029     * specified service endpoint. The returned handler chain is
030     * configured using the java.util.List interface. Each element
031     * in this list is required to be of the Java type
032     * <code>javax.xml.rpc.handler.HandlerInfo</code>
033     *
034     * @version 1.0
035     */
036    public interface HandlerRegistry extends Serializable {
037    
038        /**
039         * Gets the handler chain for the specified service endpoint.
040         * The returned <code>List</code> is used to configure this
041         * specific handler chain in this <code>HandlerRegistry</code>.
042         * Each element in this list is required to be of the Java type
043         * <code>javax.xml.rpc.handler.HandlerInfo</code>.
044         *
045         * @param   portName Qualified name of the target service
046         * @return  HandlerChain java.util.List Handler chain
047         * @throws java.lang.IllegalArgumentException If an invalid <code>portName</code> is specified
048         */
049        public java.util.List getHandlerChain(QName portName);
050    
051        /**
052         * Sets the handler chain for the specified service endpoint
053         * as a <code>java.util.List</code>. Each element in this list
054         * is required to be of the Java type
055         * <code>javax.xml.rpc.handler.HandlerInfo</code>.
056         *
057         *  @param   portName Qualified name of the target service endpoint
058         *  @param   chain a List representing configuration for the
059         *             handler chain
060         *  @throws  javax.xml.rpc.JAXRPCException if there is any error in the
061         *             configuration of the handler chain
062         *  @throws java.lang.UnsupportedOperationException if this
063         *     set operation is not supported. This is done to
064         *     avoid any overriding of a pre-configured handler
065         *     chain.
066         *  @throws java.lang.IllegalArgumentException If an invalid
067         *     <code>portName</code> is specified
068         */
069        public abstract void setHandlerChain(QName portName, java.util.List chain);
070    }
071