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