javax.xml.rpc.Service Maven / Gradle / Ivy
/*
* 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 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 $Rev: 467553 $ $Date: 2006-10-25 00:01:51 -0400 (Wed, 25 Oct 2006) $
*/
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
*
*/
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 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 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();
}