/*
 * 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 <code>javax.xml.rpc.Call</code> interface provides support
 * for the dynamic invocation of a service endpoint. The
 * <code>javax.xml.rpc.Service</code> interface acts as a factory
 * for the creation of <code>Call</code> instances.
 * <p>
 * Once a <code>Call</code> instance is created, various setter
 * and getter methods may be used to configure this <code>Call</code>
 * instance.
 *
 * @version $Rev$ $Date$
 */
public interface Call {

    /**
     * Standard property: User name for authentication
     * <p>Type: <code>java.lang.String
     */
    public static final String USERNAME_PROPERTY =
        "javax.xml.rpc.security.auth.username";

    /**
     * Standard property: Password for authentication
     * <p>Type: <code>java.lang.String</code>
     */
    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.
     * <p>Type: <code>java.lang.String</code>
     */
    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.
     * <p>Type: <code>java.lang.Boolean</code>
     */
    public static final String SOAPACTION_USE_PROPERTY =
        "javax.xml.rpc.soap.http.soapaction.use";

    /**
     * Standard property for SOAPAction. Indicates the SOAPAction
     * URI if the <code>javax.xml.rpc.soap.http.soapaction.use</code>
     * property is set to <code>true</code>.
     * <p>Type: <code>java.lang.String</code>
     */
    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
     * <code>http://schemas.xmlsoap.org/soap/encoding/</code>
     * <p>Type: <code>java.lang.String</code>
     */
    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 <code>false</code>.
     * <p>Type: <code>java.lang.Boolean</code>
     */
    public static final String SESSION_MAINTAIN_PROPERTY =
        "javax.xml.rpc.session.maintain";

    /**
     * Indicates whether <code>addParameter</code> and
     * <code>setReturnType</code> 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
     * <code>addParameter</code> and <code>setReturnType</code>
     * methods before calling the <code>invoke</code> 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
     *                <code>ParameterMode.IN</code>,
     *                <code>ParameterMode.OUT</code>,
     *                or <code>ParameterMode.INOUT
     * @throws JAXRPCException This exception may
     *     be thrown if the method <code>isParameterAndReturnSpecRequired</code>
     *     returns <code>false</code> 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 <ul>
     *
     *     <li>This exception may be thrown if this method is
     *     invoked when the method <code>isParameterAndReturnSpecRequired</code>
     *     returns <code>false</code>.
     *     <li>If specified XML type and Java type mapping
     *     is not valid. For example, <code>TypeMappingRegistry</code>
     *     has no serializers for this mapping.
     *     </ul>
     * @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
     * <code>setReturnType(null)</code> 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
     *     <code>isParameterAndReturnSpecRequired</code> returns
     *     <code>false</code>.
     * @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 <ul>
     *     <li>This exception may be thrown if this method is
     *     invoked when the method <code>isParameterAndReturnSpecRequired</code>
     *     returns <code>false</code>.
     *     <li>If XML type and Java type cannot be mapped
     *     using the standard type mapping or TypeMapping
     *     registry
     *     </ul>
     * @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 <code>Call</code> instance.
     * Note that this method removes only the parameters and not
     * the return type. The <code>setReturnType(null)</code> is
     * used to remove the return type.
     *
     * @throws JAXRPCException This exception may be
     *     thrown If this method is called when the method
     *     <code>isParameterAndReturnSpecRequired</code>
     *     returns <code>false</code> 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
     * <code>Call</code> 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 <code>Call</code> 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 <code>Call.setProperty</code> method.
     *
     * @param name Name of the property
     * @param value Value of the property
     * @throws JAXRPCException <ul>
     *     <li>If an optional standard property name is
     *         specified, however this <code>Call</code> implementation
     *         class does not support the configuration of
     *         this property.
     *     <li>If an invalid (or unsupported) property name is
     *         specified or if a value of mismatched property
     *         type is passed.
     *     <li>If there is any error in the configuration of
     *         a valid property.
     *     </ul>
     */
    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 <code>Call</code> 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 <code>null</code>
     *
     * @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 <ul>
     *
     *     <li>If there is an error in the configuration of the
     *         <code>Call</code> object
     *     <li>If <code>inputParams</code> do not match the required parameter
     *         set (as specified through the <code>addParameter</code>
     *         invocations or in the corresponding WSDL)
     *     <li>If parameters and return type are incorrectly
     *         specified
     *     </ul>
     */
    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 <ul>
     *     <li>If there is an error in the configuration of the
     *         <code>Cal</code>l object
     *     <li>If <code>inputParam</code>s do not match the required parameter
     *         set (as specified through the <code>addParameter</code>
     *         invocations or in the corresponding WSDL)
     *     <li>If parameters and return type are incorrectly
     *         specified
     *     </ul>
     */
    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
     * <code>JAXRPCException</code> 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 <code>Call</code> 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 <code>Map</code> of {name, value} for the output parameters of
     * the last invoked operation. The parameter names in the
     * returned Map are of type <code>java.lang.String</code>.
     *
     * @return Map Output parameters for the last <code>Call.invoke()</code>.
     *         Empty <code>Map</code> 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
     *     <code>invoke</code> method has been called.
     */
    public Map getOutputParams();

    /**
     * Returns a <code>List</code> values for the output parameters
     * of the last invoked operation.
     *
     * @return java.util.List Values for the output parameters. An
     *         empty <code>List</code> 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
     *     <code>invoke</code> method has been called.
     */
    public List getOutputValues();
}