/*
 * Copyright 2001-2004 The Apache Software Foundation.
 * 
 * Licensed 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 javax.xml.rpc.encoding.TypeMappingRegistry;
import javax.xml.rpc.handler.HandlerRegistry;

/**
 * <code>Service</code> class acts as a factory of the following:
 * <ul>
 * <li>Dynamic proxy for the target service endpoint.
 * <li>Instance of the type <code>javax.xml.rpc.Call</code> for
 *     the dynamic invocation of a remote operation on the
 *     target service endpoint.
 * <li>Instance of a generated stub class
 * </ul>
 *
 * @version 1.0
 */
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 <code>serviceEndpointInterface</code>
     * 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:
     *              <ul>
     *              <li>If there is an error in creation of
     *                  the dynamic proxy or stub instance
     *              <li>If there is any missing WSDL metadata
     *                  as required by this method
     *              <li>Optionally, if an illegal
     *                  <code>serviceEndpointInterface</code>
     *                  or <code>portName</code> is specified
     *              </ul>
     */
    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
     * <code>serviceEndpointInterface</code> 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 <code>Stub</code> 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 <ul>
     *              <li>If there is an error during creation
     *                  of stub instance or dynamic proxy
     *              <li>If there is any missing WSDL metadata
     *                  as required by this method
     *              <li>Optionally, if an illegal
     *                  <code>serviceEndpointInterface</code>
     *
     *                  is specified
     *              </ul>
     */
    public java.rmi.Remote getPort(Class serviceEndpointInterface)
        throws ServiceException;

    /**
     * Gets an array of preconfigured <code>Call</code> objects for
     * invoking operations on the specified port. There is one
     * <code>Call</code> object per operation that can be invoked
     * on the specified port. Each <code>Call</code> object is
     * pre-configured and does not need to be configured using
     * the setter methods on <code>Call</code> interface.
     *
     * <p>Each invocation of the <code>getCalls</code> method
     * returns a new array of preconfigured <code>Call</code>
     *
     * objects
     *
     * <p>This method requires the <code>Service</code> 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 <code>portName</code> is
     *              specified.
     */
    public Call[] getCalls(QName portName) throws ServiceException;

    /**
     * Creates a <code>Call</code> instance.
     *
     * @param portName Qualified name for the target service endpoint
     * @return Call instance
     * @throws ServiceException If any error in the creation of
     *              the <code>Call</code> object
     */
    public Call createCall(QName portName) throws ServiceException;

    /**
     * Creates a <code>Call</code> instance.
     *
     * @param portName Qualified name for the target service
     *              endpoint
     * @param operationName Qualified Name of the operation for
     *              which this <code>Call</code> object is to
     *              be created.
     * @return Call instance
     * @throws ServiceException If any error in the creation of
     *              the <code>Call</code> object
     */
    public Call createCall(QName portName, QName operationName)
        throws ServiceException;

    /**
     * Creates a <code>Call</code> instance.
     *
     * @param portName Qualified name for the target service
     *              endpoint
     * @param operationName Name of the operation for which this
     *                  <code>Call</code> object is to be
     *                  created.
     * @return Call instance
     * @throws ServiceException If any error in the creation of
     *              the <code>Call</code> object
     */
    public Call createCall(QName portName, String operationName)
        throws ServiceException;

    /**
     * Creates a <code>Call</code> object not associated with
     * specific operation or target service endpoint. This
     * <code>Call</code> object needs to be configured using the
     * setter methods on the <code>Call</code> interface.
     *
     * @return  Call object
     * @throws ServiceException If any error in the creation of
     *              the <code>Call</code> object
     */
    public Call createCall() throws ServiceException;

    /**
     * Gets the name of this Service.
     *
     * @return Qualified name of this service
     */
    public QName getServiceName();

    /**
     * Returns an <code>Iterator</code> for the list of
     * <code>QName</code>s of service endpoints grouped by this
     * service.
     *
     * @return Returns <code>java.util.Iterator</code> with elements
     *     of type <code>javax.xml.namespace.QName</code>
     * @throws ServiceException If this Service class does not
     *     have access to the required WSDL metadata
     */
    public java.util.Iterator getPorts() throws ServiceException;

    /**
     * Gets 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 <code>TypeMappingRegistry</code> for this
     * <code>Service</code> object. The returned
     * <code>TypeMappingRegistry</code> 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 <code>Service</code> class does not support
     *     the configuration of <code>TypeMappingRegistry</code>.
     */
    public TypeMappingRegistry getTypeMappingRegistry();

    /**
     * Returns the configured <code>HandlerRegistry</code> instance
     * for this <code>Service</code> instance.
     *
     * @return HandlerRegistry
     * @throws java.lang.UnsupportedOperationException - if the <code>Service</code> class does not support
     *     the configuration of a <code>HandlerRegistry</code>
     */
    public HandlerRegistry getHandlerRegistry();
}