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.Iterator;
023    
024    /**
025     * The interface <code>MessageContext</code> abstracts the message
026     * context that is processed by a handler in the <code>handle</code>
027     * method.
028     *
029     * <p>The <code>MessageContext</code> interface provides methods to
030     * manage a property set. <code>MessageContext</code> properties
031     * enable handlers in a handler chain to share processing related
032     * state.
033     *
034     * @version $Rev: 467553 $ $Date: 2006-10-25 00:01:51 -0400 (Wed, 25 Oct 2006) $
035     */
036    public interface MessageContext {
037    
038        /**
039         * Sets the name and value of a property associated with the
040         * <code>MessageContext</code>. If the <code>MessageContext</code>
041         * contains a value of the same property, the old value is replaced.
042         *
043         * @param  name ame of the property associated with the
044         *         <code>MessageContext</code>
045         * @param  value Value of the property
046         * @throws java.lang.IllegalArgumentException If some aspect
047         *         the property is prevents it from being stored
048         *         in the context
049         * @throws java.lang.UnsupportedOperationException If this method is
050         *         not supported.
051         */
052        public abstract void setProperty(String name, Object value);
053    
054        /**
055         * Gets the value of a specific property from the
056         * <code>MessageContext</code>.
057         *
058         * @param name the name of the property whose value is to be
059         *        retrieved
060         * @return the value of the property
061         * @throws java.lang.IllegalArgumentException if an illegal
062         *        property name is specified
063         */
064        public abstract Object getProperty(String name);
065    
066        /**
067         * Removes a property (name-value pair) from the
068         * <code>MessageContext</code>.
069         *
070         * @param  name the name of the property to be removed
071         *
072         * @throws java.lang.IllegalArgumentException if an illegal
073         *        property name is specified
074         */
075        public abstract void removeProperty(String name);
076    
077        /**
078         * Returns true if the <code>MessageContext</code> contains a property
079         * with the specified name.
080         * @param   name Name of the property whose presense is to be tested
081         * @return  Returns true if the MessageContext contains the
082         *     property; otherwise false
083         */
084        public abstract boolean containsProperty(String name);
085    
086        /**
087         * Returns an Iterator view of the names of the properties
088         * in this <code>MessageContext</code>.
089         *
090         * @return Iterator for the property names
091         */
092        public abstract Iterator getPropertyNames();
093    }
094