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