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;
021    
022    import java.util.Iterator;
023    
024    /**
025     * The interface <code>javax.xml.rpc.Stub</code> is the common base interface
026     * for the stub classes. All generated stub classes are required to
027     * implement the <code>javax.xml.rpc.Stub</code> interface. An instance
028     * of a stub class represents a client side proxy or stub instance for
029     * the target service endpoint.
030     *
031     * <p>The <code>javax.xml.rpc.Stub</code> interface provides an
032     * extensible property mechanism for the dynamic configuration of
033     * a stub instance.
034     *
035     * @version $Rev: 467553 $ $Date: 2006-10-25 00:01:51 -0400 (Wed, 25 Oct 2006) $
036     */
037    public interface Stub {
038    
039        // Constants for the standard properties
040    
041        /**
042         * Standard property: User name for authentication.
043         * <p>Type: java.lang.String
044         */
045        public static final String USERNAME_PROPERTY = Call.USERNAME_PROPERTY;
046    
047        /**
048         * Standard property: Password for authentication.
049         * <p>Type: java.lang.String
050         */
051        public static final String PASSWORD_PROPERTY = Call.PASSWORD_PROPERTY;
052    
053        /**
054         * Standard property: Target service endpoint address. The
055         * URI scheme for the endpoint address specification must
056         * correspond to the protocol/transport binding for this
057         * stub class.
058         * <p>Type: java.lang.String
059         */
060        public static final String ENDPOINT_ADDRESS_PROPERTY =
061            "javax.xml.rpc.service.endpoint.address";
062    
063        /**
064         * Standard property: This boolean property is used by a service
065         * client to indicate whether or not it wants to participate in
066         * a session with a service endpoint. If this property is set to
067         * true, the service client indicates that it wants the session
068         * to be maintained. If set to false, the session is not maintained.
069         * The default value for this property is false.
070         * <p>Type: java.lang.Boolean
071         */
072        public static final String SESSION_MAINTAIN_PROPERTY =
073            Call.SESSION_MAINTAIN_PROPERTY;
074    
075        /**
076         * Sets the name and value of a configuration property
077         * for this Stub instance. If the Stub instances contains
078         * a value of the same property, the old value is replaced.
079         * <p>Note that the <code>_setProperty</code> method may not
080         * perform validity check on a configured property value. An
081         * example is the standard property for the target service
082         * endpoint address that is not checked for validity in the
083         * <code>_setProperty</code> method.
084         * In this case, stub configuration errors are detected at
085         * the remote method invocation.
086         *
087         * @param name Name of the configuration property
088         * @param value Value of the property
089         * @throws JAXRPCException <ul>
090         *     <li>If an optional standard property name is
091         *         specified, however this Stub implementation
092         *         class does not support the configuration of
093         *         this property.
094         *     <li>If an invalid or unsupported property name is
095         *         specified or if a value of mismatched property
096         *         type is passed.
097         *     <li>If there is any error in the configuration of
098         *         a valid property.
099         *     </ul>
100         */
101        public void _setProperty(String name, Object value);
102    
103        /**
104         * Gets the value of a specific configuration property.
105         *
106         * @param name Name of the property whose value is to be
107         *          retrieved
108         * @return Value of the configuration property
109         * @throws JAXRPCException if an invalid or
110         *     unsupported property name is passed.
111         */
112        public Object _getProperty(String name);
113    
114        /**
115         * Returns an <code>Iterator</code> view of the names of the properties
116         * that can be configured on this stub instance.
117         *
118         * @return Iterator for the property names of the type
119         *     <code>java.lang.String</code>
120         */
121        public Iterator _getPropertyNames();
122    }    // interface Stub
123