View Javadoc

1   /*
2    * Copyright 2001-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package javax.xml.rpc;
17  
18  import java.util.Iterator;
19  
20  /**
21   * The interface <code>javax.xml.rpc.Stub</code> is the common base interface
22   * for the stub classes. All generated stub classes are required to
23   * implement the <code>javax.xml.rpc.Stub</code> interface. An instance
24   * of a stub class represents a client side proxy or stub instance for
25   * the target service endpoint.
26   *
27   * <p>The <code>javax.xml.rpc.Stub</code> interface provides an
28   * extensible property mechanism for the dynamic configuration of
29   * a stub instance.
30   *
31   * @version 1.0
32   */
33  public interface Stub {
34  
35      // Constants for the standard properties
36  
37      /**
38       * Standard property: User name for authentication.
39       * <p>Type: java.lang.String
40       */
41      public static final String USERNAME_PROPERTY = Call.USERNAME_PROPERTY;
42  
43      /**
44       * Standard property: Password for authentication.
45       * <p>Type: java.lang.String
46       */
47      public static final String PASSWORD_PROPERTY = Call.PASSWORD_PROPERTY;
48  
49      /**
50       * Standard property: Target service endpoint address. The
51       * URI scheme for the endpoint address specification must
52       * correspond to the protocol/transport binding for this
53       * stub class.
54       * <p>Type: java.lang.String
55       */
56      public static final String ENDPOINT_ADDRESS_PROPERTY =
57          "javax.xml.rpc.service.endpoint.address";
58  
59      /**
60       * Standard property: This boolean property is used by a service
61       * client to indicate whether or not it wants to participate in
62       * a session with a service endpoint. If this property is set to
63       * true, the service client indicates that it wants the session
64       * to be maintained. If set to false, the session is not maintained.
65       * The default value for this property is false.
66       * <p>Type: java.lang.Boolean
67       */
68      public static final String SESSION_MAINTAIN_PROPERTY =
69          Call.SESSION_MAINTAIN_PROPERTY;
70  
71      /**
72       * Sets the name and value of a configuration property
73       * for this Stub instance. If the Stub instances contains
74       * a value of the same property, the old value is replaced.
75       * <p>Note that the <code>_setProperty</code> method may not
76       * perform validity check on a configured property value. An
77       * example is the standard property for the target service
78       * endpoint address that is not checked for validity in the
79       * <code>_setProperty</code> method.
80       * In this case, stub configuration errors are detected at
81       * the remote method invocation.
82       *
83       * @param name Name of the configuration property
84       * @param value Value of the property
85       * @throws JAXRPCException <ul>
86       *     <li>If an optional standard property name is
87       *         specified, however this Stub implementation
88       *         class does not support the configuration of
89       *         this property.
90       *     <li>If an invalid or unsupported property name is
91       *         specified or if a value of mismatched property
92       *         type is passed.
93       *     <li>If there is any error in the configuration of
94       *         a valid property.
95       *     </ul>
96       */
97      public void _setProperty(String name, Object value);
98  
99      /**
100      * Gets the value of a specific configuration property.
101      *
102      * @param name Name of the property whose value is to be
103      *          retrieved
104      * @return Value of the configuration property
105      * @throws JAXRPCException if an invalid or
106      *     unsupported property name is passed.
107      */
108     public Object _getProperty(String name);
109 
110     /**
111      * Returns an <code>Iterator</code> view of the names of the properties
112      * that can be configured on this stub instance.
113      *
114      * @return Iterator for the property names of the type
115      *     <code>java.lang.String</code>
116      */
117     public Iterator _getPropertyNames();
118 }    // interface Stub
119