Save This Page
Home » xml-commons-external-1.4.01-src » javax » xml » rpc » [javadoc | source]
    1   /*
    2    * JBoss, Home of Professional Open Source.
    3    * Copyright 2006, Red Hat Middleware LLC, and individual contributors
    4    * as indicated by the @author tags. See the copyright.txt file in the
    5    * distribution for a full listing of individual contributors.
    6    *
    7    * This is free software; you can redistribute it and/or modify it
    8    * under the terms of the GNU Lesser General Public License as
    9    * published by the Free Software Foundation; either version 2.1 of
   10    * the License, or (at your option) any later version.
   11    *
   12    * This software is distributed in the hope that it will be useful,
   13    * but WITHOUT ANY WARRANTY; without even the implied warranty of
   14    * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   15    * Lesser General Public License for more details.
   16    *
   17    * You should have received a copy of the GNU Lesser General Public
   18    * License along with this software; if not, write to the Free
   19    * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
   20    * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
   21    */
   22   package javax.xml.rpc;
   23   
   24   import java.rmi.RemoteException;
   25   import java.util.Iterator;
   26   import java.util.List;
   27   import java.util.Map;
   28   
   29   import javax.xml.namespace.QName;
   30   
   31   /** The javax.xml.rpc.Call interface provides support for the dynamic invocation of a service endpoint.
   32    * The javax.xml.rpc.Service interface acts as a factory for the creation of Call instances.
   33    *
   34    * Once a Call instance is created, various setter and getter methods may be used to configure this Call instance.
   35    *
   36    * @author Scott.Stark@jboss.org
   37    */
   38   public interface Call
   39   {
   40      /** Standard property: User name for authentication Type: java.lang.String */
   41      public static final String USERNAME_PROPERTY = "javax.xml.rpc.security.auth.username";
   42      /** Standard property: Password for authentication Type: java.lang.String */
   43      public static final String PASSWORD_PROPERTY = "javax.xml.rpc.security.auth.password";
   44      /** Standard property for operation style. */
   45      public static final String OPERATION_STYLE_PROPERTY = "javax.xml.rpc.soap.operation.style";
   46      /** Standard property for SOAPAction. */
   47      public static final String SOAPACTION_USE_PROPERTY = "javax.xml.rpc.soap.http.soapaction.use";
   48      /** Standard property for SOAPAction. */
   49      public static final String SOAPACTION_URI_PROPERTY = "javax.xml.rpc.soap.http.soapaction.uri";
   50      /** Standard property for encoding Style: Encoding style specified as a namespace URI. */
   51      public static final String ENCODINGSTYLE_URI_PROPERTY = "javax.xml.rpc.encodingstyle.namespace.uri";
   52      /** 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. */
   53      public static final String SESSION_MAINTAIN_PROPERTY = "javax.xml.rpc.session.maintain";
   54   
   55      /** Indicates whether addParameter and setReturnType methods are to be invoked to specify the parameter and return
   56       * type specification for a specific operation.
   57       * @param operationName Qualified name of the operation
   58       * @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.
   59       * @throws IllegalArgumentException If invalid operation name is specified
   60       */
   61      public boolean isParameterAndReturnSpecRequired(QName operationName);
   62   
   63      /** Adds a parameter type and mode for a specific operation.
   64       * Note that the client code may not call any addParameter and setReturnType methods before calling the invoke method.
   65       * In this case, the Call implementation class determines the parameter types by using reflection on parameters,
   66       * using the WSDL description and configured type mapping registry.
   67       *
   68       * @param paramName Name of the parameter
   69       * @param xmlType XML type of the parameter
   70       * @param parameterMode Mode of the parameter-whether ParameterMode.IN, ParameterMode.OUT, or ParameterMode.INOUT
   71       * @throws JAXRPCException This exception may be thrown if the method isParameterAndReturnSpecRequired returns false for this operation.
   72       * @throws IllegalArgumentException If any illegal parameter name or XML type is specified
   73       */
   74      public void addParameter(String paramName, QName xmlType, ParameterMode parameterMode);
   75   
   76      /** Adds a parameter type and mode for a specific operation.
   77       * This method is used to specify the Java type for either OUT or INOUT parameters.
   78       *
   79       * @param paramName Name of the parameter
   80       * @param xmlType XML type of the parameter
   81       * @param javaType  Java class of the parameter
   82       * @param parameterMode Mode of the parameter-whether ParameterMode.IN, ParameterMode.OUT, or ParameterMode.INOUT
   83       * @throws JAXRPCException
   84       * <ul>
   85       *    <li>This exception may be thrown if the method isParameterAndReturnSpecRequired returns false for this operation.
   86       *    <li>If specified XML type and Java type mapping is not valid. For example, TypeMappingRegistry has no serializers for this mapping.
   87       * </ul>
   88       * @throws IllegalArgumentException If any illegal parameter name or XML type is specified
   89       * @throws UnsupportedOperationException If this method is not supported
   90       */
   91      public void addParameter(String paramName, QName xmlType, Class javaType, ParameterMode parameterMode);
   92   
   93      /** Gets the XML type of a parameter by name.
   94       *
   95       * @param paramName - Name of the parameter
   96       * @return Returns XML type for the specified parameter
   97       */
   98      public QName getParameterTypeByName(String paramName);
   99   
  100      /** Sets the return type for a specific operation. Invoking setReturnType(null) removes the return type for this Call object.
  101       *
  102       * @param xmlType XML data type of the return value
  103       * @throws JAXRPCException This exception may be thrown when the method isParameterAndReturnSpecRequired returns false.
  104       * @throws IllegalArgumentException If an illegal XML type is specified
  105       */
  106      public void setReturnType(QName xmlType);
  107   
  108      /** Sets the return type for a specific operation.
  109       *
  110       * @param xmlType XML data type of the return value
  111       * @param javaType Java Class of the return value
  112       * @throws JAXRPCException
  113       * <ul>
  114       *    <li>This exception may be thrown if this method is invoked when the method isParameterAndReturnSpecRequired returns false.
  115       *    <li>If XML type and Java type cannot be mapped using the standard type mapping or TypeMapping registry
  116       * </ul>
  117       * @throws UnsupportedOperationException If this method is not supported
  118       * @throws IllegalArgumentException If an illegal XML type is specified
  119       */
  120      public void setReturnType(QName xmlType, Class javaType);
  121   
  122      /** Gets the return type for a specific operation
  123       *
  124       * @return Returns the XML type for the return value
  125       */
  126      public QName getReturnType();
  127   
  128      /** Removes all specified parameters from this Call instance. Note that this method removes only the parameters and
  129       * not the return type. The setReturnType(null) is used to remove the return type.
  130       * @throws JAXRPCException This exception may be thrown If this method is called when the method isParameterAndReturnSpecRequired returns false for this Call's operation.
  131       */
  132      public void removeAllParameters();
  133   
  134      /** Gets the name of the operation to be invoked using this Call instance.
  135       * @return Qualified name of the operation
  136       */
  137      public QName getOperationName();
  138   
  139      /** Sets the name of the operation to be invoked using this Call instance.
  140       *
  141       * @param operationName QName of the operation to be invoked using the Call instance
  142       */
  143      public void setOperationName(QName operationName);
  144   
  145      /** Gets the qualified name of the port type.
  146       * @return Qualified name of the port type
  147       */
  148      public QName getPortTypeName();
  149   
  150      /** Sets the qualified name of the port type.
  151       *
  152       * @param portType - Qualified name of the port type
  153       */
  154      public void setPortTypeName(QName portType);
  155   
  156      /** Sets the address of the target service endpoint. This address must correspond to the transport
  157       * specified in the binding for this Call instance.
  158       *
  159       * @param address Address of the target service endpoint; specified as an URI
  160       */
  161      public void setTargetEndpointAddress(String address);
  162   
  163      /** Gets the address of a target service endpoint.
  164       * @return Address of the target service endpoint as an URI
  165       */
  166      public String getTargetEndpointAddress();
  167   
  168      /** Sets the value for a named property.
  169       * JAX-RPC specification specifies a standard set of properties that may be passed to the Call.setProperty method.
  170       *
  171       * @param name Name of the property
  172       * @param value Value of the property
  173       * @throws JAXRPCException
  174       * <ul>
  175       *    <li> If an optional standard property name is specified, however this Call implementation class does not support the configuration of this property.
  176       *    <li> If an invalid (or unsupported) property name is specified or if a value of mismatched property type is passed.
  177       *    <li> If there is any error in the configuration of a valid property.
  178       * </ul>
  179       */
  180      public void setProperty(String name, Object value);
  181   
  182      /** Gets the value of a named property.
  183       *
  184       * @param name Name of the property
  185       * @return Value of the named property
  186       * @throws JAXRPCException if an invalid or unsupported property name is passed.
  187       */
  188      public Object getProperty(String name);
  189   
  190      /** Removes a named property.
  191       * @param name Name of the property
  192       * @throws JAXRPCException if an invalid or unsupported property name is passed.
  193       */
  194      public void removeProperty(String name);
  195   
  196      /** Gets the names of configurable properties supported by this Call object.
  197       * @return Iterator for the property names
  198       */
  199      public Iterator getPropertyNames();
  200   
  201      /** Invokes a specific operation using a synchronous request-response interaction mode.
  202       *
  203       * @param inputParams Object[]--Parameters for this invocation. This includes only the input params
  204       * @return Returns the return value or null
  205       * @throws RemoteException if there is any error in the remote method invocation
  206       * @throws javax.xml.rpc.soap.SOAPFaultException Indicates a SOAP fault
  207       * @throws JAXRPCException
  208       * <ul>
  209       *    <li>If there is an error in the configuration of the Call object
  210       *    <li> If inputParams do not match the required parameter set (as specified through the addParameter invocations or in the corresponding WSDL)
  211       *    <li> If parameters and return type are incorrectly specified
  212       * </ul>
  213       */
  214      public Object invoke(Object[] inputParams) throws RemoteException;
  215   
  216      /** Invokes a specific operation using a synchronous request-response interaction mode.
  217       *
  218       * @param operationName QName of the operation
  219       * @param inputParams Object[]--Parameters for this invocation. This includes only the input params.
  220       * @return Return value or null
  221       * @throws RemoteException if there is any error in the remote method invocation.
  222       * @throws javax.xml.rpc.soap.SOAPFaultException - Indicates a SOAP fault
  223       * @throws JAXRPCException
  224       * <ul>
  225       *    <li> If there is an error in the configuration of the Call object
  226       *    <li> If inputParams do not match the required parameter set (as specified through the addParameter invocations or in the corresponding WSDL)
  227       *    <li> If parameters and return type are incorrectly specified
  228       * </ul>
  229       */
  230      public Object invoke(QName operationName, Object[] inputParams) throws RemoteException;
  231   
  232      /** Invokes a remote method using the one-way interaction mode.
  233       * The client thread does not normally block waiting for the completion of the server processing for this
  234       * remote method invocation. When the protocol in use is SOAP/HTTP, this method should block until an HTTP response
  235       * code has been received or an error occurs. This method must not throw any remote exceptions.
  236       * This method may throw a JAXRPCException during the processing of the one-way remote call.
  237       *
  238       * @param inputParams Object[]--Parameters for this invocation. This includes only the input params.
  239       * @throws JAXRPCException if there is an error in the configuration of the Call object
  240       * (example: a non-void return type has been incorrectly specified for the one-way call) or
  241       * if there is any error during the invocation of the one-way remote call
  242       */
  243      public void invokeOneWay(Object[] inputParams);
  244   
  245      /** Returns a Map of {name, value} for the output parameters of the last invoked operation.
  246       *  The parameter names in the returned Map are of type java.lang.String.
  247       *
  248       * @return Map Output parameters for the last Call.invoke(). Empty Map is returned if there are no output parameters.
  249       * @throws JAXRPCException If this method is invoked for a one-way operation or is invoked before any invoke method has been called.
  250       */
  251      public Map getOutputParams();
  252   
  253      /** Returns a List values for the output parameters of the last invoked operation.
  254       *
  255       * @return java.util.List Values for the output parameters. An empty List is returned if there are no output values.
  256       * @throws JAXRPCException If this method is invoked for a one-way operation or is invoked before any invoke method has been called.
  257       */
  258      public List getOutputValues();
  259   }

Save This Page
Home » xml-commons-external-1.4.01-src » javax » xml » rpc » [javadoc | source]