javax.xml.rpc.Call Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package javax.xml.rpc;
import javax.xml.namespace.QName;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
/**
* The javax.xml.rpc.Call interface provides support
* for the dynamic invocation of a service endpoint. The
* javax.xml.rpc.Service interface acts as a factory
* for the creation of Call instances.
*
* Once a Call instance is created, various setter
* and getter methods may be used to configure this Call
* instance.
*
* @version $Rev: 467553 $ $Date: 2006-10-25 00:01:51 -0400 (Wed, 25 Oct 2006) $
*/
public interface Call {
/**
* Standard property: User name for authentication
*
Type: java.lang.String
*/
public static final String USERNAME_PROPERTY =
"javax.xml.rpc.security.auth.username";
/**
* Standard property: Password for authentication
* Type: java.lang.String
*/
public static final String PASSWORD_PROPERTY =
"javax.xml.rpc.security.auth.password";
/**
* Standard property for operation style. This property is
* set to "rpc" if the operation style is rpc; "document"
* if the operation style is document.
*
Type: java.lang.String
*/
public static final String OPERATION_STYLE_PROPERTY =
"javax.xml.rpc.soap.operation.style";
/**
* Standard property for SOAPAction. This boolean property
* indicates whether or not SOAPAction is to be used. The
* default value of this property is false indicating that
* the SOAPAction is not used.
*
Type: java.lang.Boolean
*/
public static final String SOAPACTION_USE_PROPERTY =
"javax.xml.rpc.soap.http.soapaction.use";
/**
* Standard property for SOAPAction. Indicates the SOAPAction
* URI if the javax.xml.rpc.soap.http.soapaction.use
* property is set to true.
*
Type: java.lang.String
*/
public static final String SOAPACTION_URI_PROPERTY =
"javax.xml.rpc.soap.http.soapaction.uri";
/**
* Standard property for encoding Style: Encoding style specified
* as a namespace URI. The default value is the SOAP 1.1 encoding
* http://schemas.xmlsoap.org/soap/encoding/
*
Type: java.lang.String
*/
public static final String ENCODINGSTYLE_URI_PROPERTY =
"javax.xml.rpc.encodingstyle.namespace.uri";
/**
* Standard property: This boolean property is used by a service
* client to indicate whether or not it wants to participate in
* a session with a service endpoint. If this property is set to
* true, the service client indicates that it wants the session
* to be maintained. If set to false, the session is not maintained.
* The default value for this property is false.
*
Type: java.lang.Boolean
*/
public static final String SESSION_MAINTAIN_PROPERTY =
"javax.xml.rpc.session.maintain";
/**
* Indicates whether addParameter and
* setReturnType methods
* are to be invoked to specify the parameter and return type
* specification for a specific operation.
*
* @param operationName Qualified name of the operation
*
* @return Returns true if the Call implementation class
* requires addParameter and setReturnType to be
* invoked in the client code for the specified
* operation. This method returns false otherwise.
*/
public boolean isParameterAndReturnSpecRequired(QName operationName);
/**
* Adds a parameter type and mode for a specific operation.
* Note that the client code may not call any
* addParameter and setReturnType
* methods before calling the invoke method. In
* this case, the Call implementation class determines the
* parameter types by using reflection on parameters, using
* the WSDL description and configured type mapping registry.
*
* @param paramName Name of the parameter
* @param xmlType XML datatype of the parameter
* @param parameterMode Mode of the parameter-whether
* ParameterMode.IN,
* ParameterMode.OUT,
* or ParameterMode.INOUT
* @throws JAXRPCException This exception may
* be thrown if the method isParameterAndReturnSpecRequired
* returns false for this operation.
* @throws java.lang.IllegalArgumentException If any illegal
* parameter name or XML type is specified
*/
public void addParameter(String paramName, QName xmlType,
ParameterMode parameterMode);
/**
* Adds a parameter type and mode for a specific operation.
* This method is used to specify the Java type for either
* OUT or INOUT parameters.
*
* @param paramName Name of the parameter
* @param xmlType XML datatype of the parameter
* @param javaType The Java class of the parameter
* @param parameterMode Mode of the parameter-whether
* ParameterMode.IN, OUT or INOUT
* @throws JAXRPCException
*
* - This exception may be thrown if this method is
* invoked when the method
isParameterAndReturnSpecRequired
* returns false.
* - If specified XML type and Java type mapping
* is not valid. For example,
TypeMappingRegistry
* has no serializers for this mapping.
*
* @throws java.lang.IllegalArgumentException If any illegal
* parameter name or XML type is specified
* @throws java.lang.UnsupportedOperationException If this
* method is not supported
*/
public void addParameter(String paramName, QName xmlType, Class javaType,
ParameterMode parameterMode);
/**
* Gets the XML type of a parameter by name.
*
* @param paramName name of the parameter
*
* @return Returns XML type for the specified parameter
*/
public QName getParameterTypeByName(String paramName);
/**
* Sets the return type for a specific operation. Invoking
* setReturnType(null) removes the return
* type for this Call object.
*
* @param xmlType XML data type of the return value
* @throws JAXRPCException This exception
* may be thrown when the method
* isParameterAndReturnSpecRequired returns
* false.
* @throws java.lang.IllegalArgumentException If an illegal
* XML type is specified
*/
public void setReturnType(QName xmlType);
/**
* Sets the return type for a specific operation.
*
* @param xmlType XML data type of the return value
* @param javaType Java class of the return value
* @throws JAXRPCException
* - This exception may be thrown if this method is
* invoked when the method
isParameterAndReturnSpecRequired
* returns false.
* - If XML type and Java type cannot be mapped
* using the standard type mapping or TypeMapping
* registry
*
* @throws java.lang.UnsupportedOperationException If this
* method is not supported
* @throws java.lang.IllegalArgumentException If an illegal
* XML type is specified
*/
public void setReturnType(QName xmlType, Class javaType);
/**
* Gets the return type for a specific operation.
*
* @return the XML type for the return value
*/
public QName getReturnType();
/**
* Removes all specified parameters from this Call instance.
* Note that this method removes only the parameters and not
* the return type. The setReturnType(null) is
* used to remove the return type.
*
* @throws JAXRPCException This exception may be
* thrown If this method is called when the method
* isParameterAndReturnSpecRequired
* returns false for this Call's operation.
*/
public void removeAllParameters();
/**
* Gets the name of the operation to be invoked using this Call instance.
*
* @return Qualified name of the operation
*/
public QName getOperationName();
/**
* Sets the name of the operation to be invoked using this
* Call instance.
*
* @param operationName QName of the operation to be
* invoked using the Call instance
*/
public void setOperationName(QName operationName);
/**
* Gets the qualified name of the port type.
*
* @return Qualified name of the port type
*/
public QName getPortTypeName();
/**
* Sets the qualified name of the port type.
*
* @param portType Qualified name of the port type
*/
public void setPortTypeName(QName portType);
/**
* Sets the address of the target service endpoint.
* This address must correspond to the transport specified
* in the binding for this Call instance.
*
* @param address Address of the target service endpoint;
* specified as an URI
*/
public void setTargetEndpointAddress(String address);
/**
* Gets the address of a target service endpoint.
*
* @return Endpoint address of the target service port as an URI
*/
public String getTargetEndpointAddress();
/**
* Sets the value for a named property. JAX-RPC specification
* specifies a standard set of properties that may be passed
* to the Call.setProperty method.
*
* @param name Name of the property
* @param value Value of the property
* @throws JAXRPCException
* - If an optional standard property name is
* specified, however this
Call implementation
* class does not support the configuration of
* this property.
* - If an invalid (or unsupported) property name is
* specified or if a value of mismatched property
* type is passed.
*
- If there is any error in the configuration of
* a valid property.
*
*/
public void setProperty(String name, Object value);
/**
* Gets the value of a named property.
*
* @param name Name of the property
*
* @return Value of the named property
* @throws JAXRPCException if an invalid or
* unsupported property name is passed.
*/
public Object getProperty(String name);
/**
* Removes a named property.
*
* @param name Name of the property
* @throws JAXRPCException if an invalid or
* unsupported property name is passed.
*/
public void removeProperty(String name);
/**
* Gets the names of configurable properties supported by
* this Call object.
*
* @return Iterator for the property names
*/
public Iterator getPropertyNames();
// Remote Method Invocation methods
/**
* Invokes a specific operation using a synchronous request-response
* interaction mode.
*
* @param inputParams Object[]--Parameters for this invocation. This
* includes only the input params
*
* @return Returns the return value or null
*
* @throws java.rmi.RemoteException if there is any error in the remote
* method invocation or if the Call
* object is not configured properly.
* @throws javax.xml.rpc.soap.SOAPFaultException Indicates a SOAP fault
* @throws JAXRPCException
*
* - If there is an error in the configuration of the
*
Call object
* - If
inputParams do not match the required parameter
* set (as specified through the addParameter
* invocations or in the corresponding WSDL)
* - If parameters and return type are incorrectly
* specified
*
*/
public Object invoke(Object[] inputParams) throws java.rmi.RemoteException;
/**
* Invokes a specific operation using a synchronous request-response
* interaction mode.
*
* @param operationName QName of the operation
* @param inputParams Object[]--Parameters for this invocation. This
* includes only the input params.
*
* @return Return value or null
*
* @throws java.rmi.RemoteException if there is any error in the
* remote method invocation.
* @throws javax.xml.rpc.soap.SOAPFaultException Indicates a SOAP fault
* @throws JAXRPCException
* - If there is an error in the configuration of the
*
Call object
* - If
inputParams do not match the required parameter
* set (as specified through the addParameter
* invocations or in the corresponding WSDL)
* - If parameters and return type are incorrectly
* specified
*
*/
public Object invoke(QName operationName, Object[] inputParams)
throws java.rmi.RemoteException;
/**
* Invokes a remote method using the one-way interaction mode. The
* client thread does not block waiting for the completion of the
* server processing for this remote method invocation. This method
* must not throw any remote exceptions. This method may throw a
* JAXRPCException during the processing of the one-way
* remote call.
*
* @param params Object[]--Parameters for this invocation. This
* includes only the input params.
*
* @throws JAXRPCException if there is an error in the
* configuration of the Call object (example: a
* non-void return type has been incorrectly specified for the
* one-way call) or if there is any error during the
* invocation of the one-way remote call
*/
public void invokeOneWay(Object[] params);
/**
* Returns a Map of {name, value} for the output parameters of
* the last invoked operation. The parameter names in the
* returned Map are of type java.lang.String.
*
* @return Map Output parameters for the last Call.invoke().
* Empty Map is returned if there are no output
* parameters.
* @throws javax.xml.rpc.JAXRPCException If this method is invoked for a
* one-way operation or is invoked before any
* invoke method has been called.
*/
public Map getOutputParams();
/**
* Returns a List values for the output parameters
* of the last invoked operation.
*
* @return java.util.List Values for the output parameters. An
* empty List is returned if there are
* no output values.
*
* @throws JAXRPCException If this method is invoked for a
* one-way operation or is invoked before any
* invoke method has been called.
*/
public List getOutputValues();
}