All Downloads are FREE. Search and download functionalities are using the official Maven repository.

javax.xml.rpc.Service Maven / Gradle / Ivy

The newest version!
/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 2003-2018 Oracle and/or its affiliates. All rights reserved.
 *
 * The contents of this file are subject to the terms of either the GNU
 * General Public License Version 2 only ("GPL") or the Common Development
 * and Distribution License("CDDL") (collectively, the "License").  You
 * may not use this file except in compliance with the License.  You can
 * obtain a copy of the License at
 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
 * or LICENSE.txt.  See the License for the specific
 * language governing permissions and limitations under the License.
 *
 * When distributing the software, include this License Header Notice in each
 * file and include the License file at LICENSE.txt.
 *
 * GPL Classpath Exception:
 * Oracle designates this particular file as subject to the "Classpath"
 * exception as provided by Oracle in the GPL Version 2 section of the License
 * file that accompanied this code.
 *
 * Modifications:
 * If applicable, add the following below the License Header, with the fields
 * enclosed by brackets [] replaced by your own identifying information:
 * "Portions Copyright [year] [name of copyright owner]"
 *
 * Contributor(s):
 * If you wish your version of this file to be governed by only the CDDL or
 * only the GPL Version 2, indicate your decision by adding "[Contributor]
 * elects to include this software in this distribution under the [CDDL or GPL
 * Version 2] license."  If you don't indicate a single choice of license, a
 * recipient has the option to distribute your version of this file under
 * either the CDDL, the GPL Version 2 or to extend the choice of license to
 * its licensees as provided above.  However, if you add GPL Version 2 code
 * and therefore, elected the GPL Version 2 license, then the option applies
 * only if the new code is made subject to such option by the copyright
 * holder.
 */

package javax.xml.rpc;

import javax.xml.namespace.QName;
import java.net.URL;
import java.util.Iterator;
import javax.xml.rpc.encoding.TypeMappingRegistry;
import javax.xml.rpc.handler.HandlerRegistry;

/** Service class acts as a factory of the following:
 *  
    *
  • Dynamic proxy for the target service endpoint. *
  • Instance of the type javax.xml.rpc.Call for * the dynamic invocation of a remote operation on the * target service endpoint. *
  • Instance of a generated stub class *
* * @version 1.0 * @author Rahul Sharma * @see javax.xml.rpc.Call * @see javax.xml.rpc.Stub **/ public interface Service { /** The getPort method returns either an instance of a generated * stub implementation class or a dynamic proxy. A service client * uses this dynamic proxy to invoke operations on the target * service endpoint. The serviceEndpointInterface * specifies the service endpoint interface that is supported by * the created dynamic proxy or stub instance. * * @param portName Qualified name of the service endpoint in * the WSDL service description * @param serviceEndpointInterface Service endpoint interface * supported by the dynamic proxy or stub * instance * @return java.rmi.Remote Stub instance or dynamic proxy that * supports the specified service endpoint * interface * @throws ServiceException This exception is thrown in the * following cases: *
    *
  • If there is an error in creation of * the dynamic proxy or stub instance *
  • If there is any missing WSDL metadata * as required by this method *
  • Optionally, if an illegal * serviceEndpointInterface * or portName is specified *
* @see java.lang.reflect.Proxy * @see java.lang.reflect.InvocationHandler **/ public java.rmi.Remote getPort(QName portName, Class serviceEndpointInterface) throws ServiceException; /** The getPort method returns either an instance of a generated * stub implementation class or a dynamic proxy. The parameter * serviceEndpointInterface specifies the service * endpoint interface that is supported by the returned stub or * proxy. In the implementation of this method, the JAX-RPC * runtime system takes the responsibility of selecting a protocol * binding (and a port) and configuring the stub accordingly. * The returned Stub instance should not be * reconfigured by the client. * * @param serviceEndpointInterface Service endpoint interface * @return Stub instance or dynamic proxy that supports the * specified service endpoint interface * @throws ServiceException *
    *
  • If there is an error during creation * of stub instance or dynamic proxy *
  • If there is any missing WSDL metadata * as required by this method *
  • Optionally, if an illegal * serviceEndpointInterface * is specified *
**/ public java.rmi.Remote getPort(Class serviceEndpointInterface) throws ServiceException; /** Gets an array of preconfigured Call objects for * invoking operations on the specified port. There is one * Call object per operation that can be invoked * on the specified port. Each Call object is * pre-configured and does not need to be configured using * the setter methods on Call interface. * *

Each invocation of the getCalls method * returns a new array of preconfigured Call * objects * *

This method requires the Service implementation * class to have access to the WSDL related metadata. * * @param portName Qualified name for the target service endpoint * @return Call[] Array of pre-configured Call objects * @throws ServiceException If this Service class does not * have access to the required WSDL metadata * or if an illegal portName is * specified. **/ public Call[] getCalls(QName portName) throws ServiceException; /** Creates a Call instance. * @param portName Qualified name for the target service endpoint * @return Call instance * @throws ServiceException If any error in the creation of * the Call object **/ public Call createCall(QName portName) throws ServiceException; /** Creates a Call instance. * @param portName Qualified name for the target service * endpoint * @param operationName Qualified Name of the operation for * which this Call object is to * be created. * @return Call instance * @throws ServiceException If any error in the creation of * the Call object **/ public Call createCall(QName portName, QName operationName) throws ServiceException; /** Creates a Call instance. * @param portName Qualified name for the target service * endpoint * @param operationName Name of the operation for which this * Call object is to be * created. * @return Call instance * @throws ServiceException If any error in the creation of * the Call object **/ public Call createCall(QName portName, String operationName) throws ServiceException; /** Creates a Call object not associated with * specific operation or target service endpoint. This * Call object needs to be configured using the * setter methods on the Call interface. * * @return Call object * @throws ServiceException If any error in the creation of * the Call object */ public Call createCall() throws ServiceException; /** Gets the name of this service. * @return Qualified name of this service **/ public QName getServiceName(); /** Returns an Iterator for the list of * QNames of service endpoints grouped by this * service * * @return Returns java.util.Iterator with elements * of type javax.xml.namespace.QName * @throws ServiceException If this Service class does not * have access to the required WSDL metadata **/ public Iterator getPorts() throws ServiceException; /** Gets the location of the WSDL document for this Service. * * @return URL for the location of the WSDL document for * this service **/ public java.net.URL getWSDLDocumentLocation(); /** Gets the TypeMappingRegistry for this * Service object. The returned * TypeMappingRegistry instance is pre-configured * to support the standard type mapping between XML and Java * types types as required by the JAX-RPC specification. * * @return The TypeMappingRegistry for this Service object. * @throws java.lang.UnsupportedOperationException * if the Service class does not support * the configuration of TypeMappingRegistry. **/ public TypeMappingRegistry getTypeMappingRegistry(); /** Returns the configured HandlerRegistry instance * for this Service instance. * @return HandlerRegistry * @throws java.lang.UnsupportedOperationException * if the Service class does not support * the configuration of a HandlerRegistry **/ public HandlerRegistry getHandlerRegistry(); }