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.net.URL;
   25   import java.rmi.Remote;
   26   import java.util.Iterator;
   27   
   28   import javax.xml.namespace.QName;
   29   import javax.xml.rpc.encoding.TypeMappingRegistry;
   30   import javax.xml.rpc.handler.HandlerRegistry;
   31   
   32   /** Service class acts as a factory for:
   33    * <ul>
   34    *    <li>Dynamic proxy for the target service endpoint.
   35    *    <li>Instance of the type javax.xml.rpc.Call for the dynamic invocation of a remote operation on the target service endpoint.
   36    *    <li>Instance of a generated stub class
   37    * </ul>
   38    *
   39    * @author Scott.Stark@jboss.org
   40    * @author Thomas.Diesler@jboss.org
   41    */
   42   public interface Service
   43   {
   44      /**
   45       * The getPort method returns either an instance of a generated stub implementation class or a dynamic proxy.
   46       * A service client uses this dynamic proxy to invoke operations on the target service endpoint.
   47       * The serviceEndpointInterface specifies the service endpoint interface that is supported by the created dynamic proxy or stub instance.
   48       *
   49       * @param portName Qualified name of the service endpoint in the WSDL service descr
   50       * @param seiClass Service endpoint interface supported by the dynamic proxy or stub instance
   51       * @return Stub instance or dynamic proxy that supports the specified service endpoint interface
   52       * @throws ServiceException This exception is thrown in the following cases:
   53       * <ul>
   54       *    <li>If there is an error in creation of the dynamic proxy or stub instance
   55       *    <li>If there is any missing WSDL metadata as required by this method
   56       *    <li>Optionally, if an illegal serviceEndpointInterface or portName is specified 
   57       * </ul>
   58       */
   59      public Remote getPort(QName portName, Class seiClass) throws ServiceException;
   60   
   61      /**
   62       * The getPort method returns either an instance of a generated stub implementation class or a dynamic proxy.
   63       * The parameter serviceEndpointInterface specifies the service endpoint interface that is supported by the returned stub or proxy.
   64       * In the implementation of this method, the JAX-RPC runtime system takes the responsibility of selecting a protocol binding (and a port)
   65       * and configuring the stub accordingly. The returned Stub instance should not be reconfigured by the client.
   66       */
   67      public Remote getPort(Class seiClass) throws ServiceException;
   68   
   69      /** Gets an array of preconfigured Call objects for invoking operations on the specified port.
   70       * There is one Call object per operation that can be invoked on the specified port.
   71       * Each Call object is pre-configured and does not need to be configured using the setter methods on Call interface.
   72       *
   73       * Each invocation of the getCalls method returns a new array of preconfigured Call objects
   74       *
   75       * This method requires the Service implementation class to have access to the WSDL related metadata.
   76       *
   77       * @param portName  Qualified name for the target service endpoint
   78       * @return Call[] Array of pre-configured Call objects
   79       * @throws ServiceException If this Service class does not have access to the required WSDL metadata or if an illegal portName is specified.
   80       */
   81      public Call[] getCalls(QName portName) throws ServiceException;
   82   
   83      /** Creates a Call instance.
   84       *
   85       * @param portName Qualified name for the target service endpoint
   86       * @return Call instance
   87       * @throws ServiceException  If any error in the creation of the Call object
   88       */
   89      public Call createCall(QName portName) throws ServiceException;
   90   
   91      /** Creates a Call instance.
   92       *
   93       * @param portName  Qualified name for the target service endpoint
   94       * @param operationName Qualified name of the operation for which this Call object is to be created.
   95       * @return  Call instance
   96       * @throws ServiceException  If any error in the creation of the Call object
   97       */
   98      public Call createCall(QName portName, QName operationName) throws ServiceException;
   99   
  100      /** Creates a Call instance.
  101       *
  102       * @param portName  Qualified name for the target service endpoint
  103       * @param operationName   Name of the operation for which this Call object is to be created.
  104       * @return  Call instance
  105       * @throws ServiceException  If any error in the creation of the Call object
  106       */
  107      public Call createCall(QName portName, String operationName) throws ServiceException;
  108   
  109      /**
  110       * Creates a Call object not associated with specific operation or target service endpoint.
  111       * This Call object needs to be configured using the setter methods on the Call interface.
  112       *
  113       * @return Call object
  114       * @throws ServiceException   If any error in the creation of the Call object
  115       */
  116      public Call createCall() throws ServiceException;
  117   
  118      /** Gets the name of this service.
  119       * @return Qualified name of this service
  120       */
  121      public QName getServiceName();
  122   
  123      /** Returns an Iterator for the list of QNames of service endpoints grouped by this service
  124       *
  125       * @return Returns java.util.Iterator with elements of type javax.xml.namespace.QName
  126       * @throws ServiceException If this Service class does not have access to the required WSDL metadata
  127       */
  128      public Iterator getPorts() throws ServiceException;
  129   
  130      /** Gets the location of the WSDL document for this Service.
  131       *
  132       * @return URL for the location of the WSDL document for this service
  133       */
  134      public URL getWSDLDocumentLocation();
  135   
  136      /** Gets the TypeMappingRegistry for this Service object. The returned TypeMappingRegistry instance is pre-configured
  137       * to support the standard type mapping between XML and Java types types as required by the JAX-RPC specification.
  138       *
  139       * @return The TypeMappingRegistry for this Service object.
  140       * @throws java.lang.UnsupportedOperationException if the Service class does not support the configuration of TypeMappingRegistry.
  141       */
  142      public TypeMappingRegistry getTypeMappingRegistry();
  143   
  144      /** Returns the configured HandlerRegistry instance for this Service instance.
  145       *
  146       * @return HandlerRegistry
  147       * @throws java.lang.UnsupportedOperationException if the Service class does not support the configuration of a HandlerRegistry
  148       */
  149      public HandlerRegistry getHandlerRegistry();
  150   
  151   }

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