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 javax.xml.namespace.QName; 023 import java.util.Iterator; 024 import java.util.List; 025 import java.util.Map; 026 027 /** 028 * The <code>javax.xml.rpc.Call</code> interface provides support 029 * for the dynamic invocation of a service endpoint. The 030 * <code>javax.xml.rpc.Service</code> interface acts as a factory 031 * for the creation of <code>Call</code> instances. 032 * <p> 033 * Once a <code>Call</code> instance is created, various setter 034 * and getter methods may be used to configure this <code>Call</code> 035 * instance. 036 * 037 * @version $Rev: 467553 $ $Date: 2006-10-25 00:01:51 -0400 (Wed, 25 Oct 2006) $ 038 */ 039 public interface Call { 040 041 /** 042 * Standard property: User name for authentication 043 * <p>Type: <code>java.lang.String 044 */ 045 public static final String USERNAME_PROPERTY = 046 "javax.xml.rpc.security.auth.username"; 047 048 /** 049 * Standard property: Password for authentication 050 * <p>Type: <code>java.lang.String</code> 051 */ 052 public static final String PASSWORD_PROPERTY = 053 "javax.xml.rpc.security.auth.password"; 054 055 /** 056 * Standard property for operation style. This property is 057 * set to "rpc" if the operation style is rpc; "document" 058 * if the operation style is document. 059 * <p>Type: <code>java.lang.String</code> 060 */ 061 public static final String OPERATION_STYLE_PROPERTY = 062 "javax.xml.rpc.soap.operation.style"; 063 064 /** 065 * Standard property for SOAPAction. This boolean property 066 * indicates whether or not SOAPAction is to be used. The 067 * default value of this property is false indicating that 068 * the SOAPAction is not used. 069 * <p>Type: <code>java.lang.Boolean</code> 070 */ 071 public static final String SOAPACTION_USE_PROPERTY = 072 "javax.xml.rpc.soap.http.soapaction.use"; 073 074 /** 075 * Standard property for SOAPAction. Indicates the SOAPAction 076 * URI if the <code>javax.xml.rpc.soap.http.soapaction.use</code> 077 * property is set to <code>true</code>. 078 * <p>Type: <code>java.lang.String</code> 079 */ 080 public static final String SOAPACTION_URI_PROPERTY = 081 "javax.xml.rpc.soap.http.soapaction.uri"; 082 083 /** 084 * Standard property for encoding Style: Encoding style specified 085 * as a namespace URI. The default value is the SOAP 1.1 encoding 086 * <code>http://schemas.xmlsoap.org/soap/encoding/</code> 087 * <p>Type: <code>java.lang.String</code> 088 */ 089 public static final String ENCODINGSTYLE_URI_PROPERTY = 090 "javax.xml.rpc.encodingstyle.namespace.uri"; 091 092 /** 093 * Standard property: This boolean property is used by a service 094 * client to indicate whether or not it wants to participate in 095 * a session with a service endpoint. If this property is set to 096 * true, the service client indicates that it wants the session 097 * to be maintained. If set to false, the session is not maintained. 098 * The default value for this property is <code>false</code>. 099 * <p>Type: <code>java.lang.Boolean</code> 100 */ 101 public static final String SESSION_MAINTAIN_PROPERTY = 102 "javax.xml.rpc.session.maintain"; 103 104 /** 105 * Indicates whether <code>addParameter</code> and 106 * <code>setReturnType</code> methods 107 * are to be invoked to specify the parameter and return type 108 * specification for a specific operation. 109 * 110 * @param operationName Qualified name of the operation 111 * 112 * @return Returns true if the Call implementation class 113 * requires addParameter and setReturnType to be 114 * invoked in the client code for the specified 115 * operation. This method returns false otherwise. 116 */ 117 public boolean isParameterAndReturnSpecRequired(QName operationName); 118 119 /** 120 * Adds a parameter type and mode for a specific operation. 121 * Note that the client code may not call any 122 * <code>addParameter</code> and <code>setReturnType</code> 123 * methods before calling the <code>invoke</code> method. In 124 * this case, the Call implementation class determines the 125 * parameter types by using reflection on parameters, using 126 * the WSDL description and configured type mapping registry. 127 * 128 * @param paramName Name of the parameter 129 * @param xmlType XML datatype of the parameter 130 * @param parameterMode Mode of the parameter-whether 131 * <code>ParameterMode.IN</code>, 132 * <code>ParameterMode.OUT</code>, 133 * or <code>ParameterMode.INOUT 134 * @throws JAXRPCException This exception may 135 * be thrown if the method <code>isParameterAndReturnSpecRequired</code> 136 * returns <code>false</code> for this operation. 137 * @throws java.lang.IllegalArgumentException If any illegal 138 * parameter name or XML type is specified 139 */ 140 public void addParameter(String paramName, QName xmlType, 141 ParameterMode parameterMode); 142 143 /** 144 * Adds a parameter type and mode for a specific operation. 145 * This method is used to specify the Java type for either 146 * OUT or INOUT parameters. 147 * 148 * @param paramName Name of the parameter 149 * @param xmlType XML datatype of the parameter 150 * @param javaType The Java class of the parameter 151 * @param parameterMode Mode of the parameter-whether 152 * ParameterMode.IN, OUT or INOUT 153 * @throws JAXRPCException <ul> 154 * 155 * <li>This exception may be thrown if this method is 156 * invoked when the method <code>isParameterAndReturnSpecRequired</code> 157 * returns <code>false</code>. 158 * <li>If specified XML type and Java type mapping 159 * is not valid. For example, <code>TypeMappingRegistry</code> 160 * has no serializers for this mapping. 161 * </ul> 162 * @throws java.lang.IllegalArgumentException If any illegal 163 * parameter name or XML type is specified 164 * @throws java.lang.UnsupportedOperationException If this 165 * method is not supported 166 */ 167 public void addParameter(String paramName, QName xmlType, Class javaType, 168 ParameterMode parameterMode); 169 170 /** 171 * Gets the XML type of a parameter by name. 172 * 173 * @param paramName name of the parameter 174 * 175 * @return Returns XML type for the specified parameter 176 */ 177 public QName getParameterTypeByName(String paramName); 178 179 /** 180 * Sets the return type for a specific operation. Invoking 181 * <code>setReturnType(null)</code> removes the return 182 * type for this Call object. 183 * 184 * @param xmlType XML data type of the return value 185 * @throws JAXRPCException This exception 186 * may be thrown when the method 187 * <code>isParameterAndReturnSpecRequired</code> returns 188 * <code>false</code>. 189 * @throws java.lang.IllegalArgumentException If an illegal 190 * XML type is specified 191 */ 192 public void setReturnType(QName xmlType); 193 194 /** 195 * Sets the return type for a specific operation. 196 * 197 * @param xmlType XML data type of the return value 198 * @param javaType Java class of the return value 199 * @throws JAXRPCException <ul> 200 * <li>This exception may be thrown if this method is 201 * invoked when the method <code>isParameterAndReturnSpecRequired</code> 202 * returns <code>false</code>. 203 * <li>If XML type and Java type cannot be mapped 204 * using the standard type mapping or TypeMapping 205 * registry 206 * </ul> 207 * @throws java.lang.UnsupportedOperationException If this 208 * method is not supported 209 * @throws java.lang.IllegalArgumentException If an illegal 210 * XML type is specified 211 */ 212 public void setReturnType(QName xmlType, Class javaType); 213 214 /** 215 * Gets the return type for a specific operation. 216 * 217 * @return the XML type for the return value 218 */ 219 public QName getReturnType(); 220 221 /** 222 * Removes all specified parameters from this <code>Call</code> instance. 223 * Note that this method removes only the parameters and not 224 * the return type. The <code>setReturnType(null)</code> is 225 * used to remove the return type. 226 * 227 * @throws JAXRPCException This exception may be 228 * thrown If this method is called when the method 229 * <code>isParameterAndReturnSpecRequired</code> 230 * returns <code>false</code> for this Call's operation. 231 */ 232 public void removeAllParameters(); 233 234 /** 235 * Gets the name of the operation to be invoked using this Call instance. 236 * 237 * @return Qualified name of the operation 238 */ 239 public QName getOperationName(); 240 241 /** 242 * Sets the name of the operation to be invoked using this 243 * <code>Call</code> instance. 244 * 245 * @param operationName QName of the operation to be 246 * invoked using the Call instance 247 */ 248 public void setOperationName(QName operationName); 249 250 /** 251 * Gets the qualified name of the port type. 252 * 253 * @return Qualified name of the port type 254 */ 255 public QName getPortTypeName(); 256 257 /** 258 * Sets the qualified name of the port type. 259 * 260 * @param portType Qualified name of the port type 261 */ 262 public void setPortTypeName(QName portType); 263 264 /** 265 * Sets the address of the target service endpoint. 266 * This address must correspond to the transport specified 267 * in the binding for this <code>Call</code> instance. 268 * 269 * @param address Address of the target service endpoint; 270 * specified as an URI 271 */ 272 public void setTargetEndpointAddress(String address); 273 274 /** 275 * Gets the address of a target service endpoint. 276 * 277 * @return Endpoint address of the target service port as an URI 278 */ 279 public String getTargetEndpointAddress(); 280 281 /** 282 * Sets the value for a named property. JAX-RPC specification 283 * specifies a standard set of properties that may be passed 284 * to the <code>Call.setProperty</code> method. 285 * 286 * @param name Name of the property 287 * @param value Value of the property 288 * @throws JAXRPCException <ul> 289 * <li>If an optional standard property name is 290 * specified, however this <code>Call</code> implementation 291 * class does not support the configuration of 292 * this property. 293 * <li>If an invalid (or unsupported) property name is 294 * specified or if a value of mismatched property 295 * type is passed. 296 * <li>If there is any error in the configuration of 297 * a valid property. 298 * </ul> 299 */ 300 public void setProperty(String name, Object value); 301 302 /** 303 * Gets the value of a named property. 304 * 305 * @param name Name of the property 306 * 307 * @return Value of the named property 308 * @throws JAXRPCException if an invalid or 309 * unsupported property name is passed. 310 */ 311 public Object getProperty(String name); 312 313 /** 314 * Removes a named property. 315 * 316 * @param name Name of the property 317 * @throws JAXRPCException if an invalid or 318 * unsupported property name is passed. 319 */ 320 public void removeProperty(String name); 321 322 /** 323 * Gets the names of configurable properties supported by 324 * this <code>Call</code> object. 325 * 326 * @return Iterator for the property names 327 */ 328 public Iterator getPropertyNames(); 329 330 // Remote Method Invocation methods 331 332 /** 333 * Invokes a specific operation using a synchronous request-response 334 * interaction mode. 335 * 336 * @param inputParams Object[]--Parameters for this invocation. This 337 * includes only the input params 338 * 339 * @return Returns the return value or <code>null</code> 340 * 341 * @throws java.rmi.RemoteException if there is any error in the remote 342 * method invocation or if the Call 343 * object is not configured properly. 344 * @throws javax.xml.rpc.soap.SOAPFaultException Indicates a SOAP fault 345 * @throws JAXRPCException <ul> 346 * 347 * <li>If there is an error in the configuration of the 348 * <code>Call</code> object 349 * <li>If <code>inputParams</code> do not match the required parameter 350 * set (as specified through the <code>addParameter</code> 351 * invocations or in the corresponding WSDL) 352 * <li>If parameters and return type are incorrectly 353 * specified 354 * </ul> 355 */ 356 public Object invoke(Object[] inputParams) throws java.rmi.RemoteException; 357 358 /** 359 * Invokes a specific operation using a synchronous request-response 360 * interaction mode. 361 * 362 * @param operationName QName of the operation 363 * @param inputParams Object[]--Parameters for this invocation. This 364 * includes only the input params. 365 * 366 * @return Return value or null 367 * 368 * @throws java.rmi.RemoteException if there is any error in the 369 * remote method invocation. 370 * @throws javax.xml.rpc.soap.SOAPFaultException Indicates a SOAP fault 371 * @throws JAXRPCException <ul> 372 * <li>If there is an error in the configuration of the 373 * <code>Cal</code>l object 374 * <li>If <code>inputParam</code>s do not match the required parameter 375 * set (as specified through the <code>addParameter</code> 376 * invocations or in the corresponding WSDL) 377 * <li>If parameters and return type are incorrectly 378 * specified 379 * </ul> 380 */ 381 public Object invoke(QName operationName, Object[] inputParams) 382 throws java.rmi.RemoteException; 383 384 /** 385 * Invokes a remote method using the one-way interaction mode. The 386 * client thread does not block waiting for the completion of the 387 * server processing for this remote method invocation. This method 388 * must not throw any remote exceptions. This method may throw a 389 * <code>JAXRPCException</code> during the processing of the one-way 390 * remote call. 391 * 392 * @param params Object[]--Parameters for this invocation. This 393 * includes only the input params. 394 * 395 * @throws JAXRPCException if there is an error in the 396 * configuration of the <code>Call</code> object (example: a 397 * non-void return type has been incorrectly specified for the 398 * one-way call) or if there is any error during the 399 * invocation of the one-way remote call 400 */ 401 public void invokeOneWay(Object[] params); 402 403 /** 404 * Returns a <code>Map</code> of {name, value} for the output parameters of 405 * the last invoked operation. The parameter names in the 406 * returned Map are of type <code>java.lang.String</code>. 407 * 408 * @return Map Output parameters for the last <code>Call.invoke()</code>. 409 * Empty <code>Map</code> is returned if there are no output 410 * parameters. 411 * @throws javax.xml.rpc.JAXRPCException If this method is invoked for a 412 * one-way operation or is invoked before any 413 * <code>invoke</code> method has been called. 414 */ 415 public Map getOutputParams(); 416 417 /** 418 * Returns a <code>List</code> values for the output parameters 419 * of the last invoked operation. 420 * 421 * @return java.util.List Values for the output parameters. An 422 * empty <code>List</code> is returned if there are 423 * no output values. 424 * 425 * @throws JAXRPCException If this method is invoked for a 426 * one-way operation or is invoked before any 427 * <code>invoke</code> method has been called. 428 */ 429 public List getOutputValues(); 430 } 431