001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *  http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing,
013     * software distributed under the License is distributed on an
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     * KIND, either express or implied.  See the License for the
016     * specific language governing permissions and limitations
017     * under the License.
018     */
019    
020    package javax.xml.rpc;
021    
022    import javax.xml.namespace.QName;
023    import javax.xml.rpc.encoding.TypeMappingRegistry;
024    import javax.xml.rpc.handler.HandlerRegistry;
025    
026    /**
027     * <code>Service</code> class acts as a factory of the following:
028     * <ul>
029     * <li>Dynamic proxy for the target service endpoint.
030     * <li>Instance of the type <code>javax.xml.rpc.Call</code> for
031     *     the dynamic invocation of a remote operation on the
032     *     target service endpoint.
033     * <li>Instance of a generated stub class
034     * </ul>
035     *
036     * @version $Rev: 467553 $ $Date: 2006-10-25 00:01:51 -0400 (Wed, 25 Oct 2006) $
037     */
038    public interface Service {
039    
040        /**
041         * The getPort method returns either an instance of a generated
042         * stub implementation class or a dynamic proxy. A service client
043         * uses this dynamic proxy to invoke operations on the target
044         * service endpoint. The <code>serviceEndpointInterface</code>
045         * specifies the service endpoint interface that is supported by
046         * the created dynamic proxy or stub instance.
047         *
048         * @param portName Qualified name of the service endpoint in
049         *              the WSDL service description
050         * @param serviceEndpointInterface Service endpoint interface
051         *              supported by the dynamic proxy or stub
052         *              instance
053         * @return java.rmi.Remote Stub instance or dynamic proxy that
054         *              supports the specified service endpoint
055         *              interface
056         * @throws ServiceException This exception is thrown in the
057         *              following cases:
058         *              <ul>
059         *              <li>If there is an error in creation of
060         *                  the dynamic proxy or stub instance
061         *              <li>If there is any missing WSDL metadata
062         *                  as required by this method
063         *              <li>Optionally, if an illegal
064         *                  <code>serviceEndpointInterface</code>
065         *                  or <code>portName</code> is specified
066         *              </ul>
067         */
068        public java.rmi
069            .Remote getPort(QName portName, Class serviceEndpointInterface)
070                throws ServiceException;
071    
072        /**
073         * The getPort method returns either an instance of a generated
074         * stub implementation class or a dynamic proxy. The parameter
075         * <code>serviceEndpointInterface</code> specifies the service
076         * endpoint interface that is supported by the returned stub or
077         * proxy. In the implementation of this method, the JAX-RPC
078         * runtime system takes the responsibility of selecting a protocol
079         * binding (and a port) and configuring the stub accordingly.
080         * The returned <code>Stub</code> instance should not be
081         * reconfigured by the client.
082         *
083         * @param serviceEndpointInterface Service endpoint interface
084         * @return Stub instance or dynamic proxy that supports the
085         *              specified service endpoint interface
086         *
087         * @throws ServiceException <ul>
088         *              <li>If there is an error during creation
089         *                  of stub instance or dynamic proxy
090         *              <li>If there is any missing WSDL metadata
091         *                  as required by this method
092         *              <li>Optionally, if an illegal
093         *                  <code>serviceEndpointInterface</code>
094         *
095         *                  is specified
096         *              </ul>
097         */
098        public java.rmi.Remote getPort(Class serviceEndpointInterface)
099            throws ServiceException;
100    
101        /**
102         * Gets an array of preconfigured <code>Call</code> objects for
103         * invoking operations on the specified port. There is one
104         * <code>Call</code> object per operation that can be invoked
105         * on the specified port. Each <code>Call</code> object is
106         * pre-configured and does not need to be configured using
107         * the setter methods on <code>Call</code> interface.
108         *
109         * <p>Each invocation of the <code>getCalls</code> method
110         * returns a new array of preconfigured <code>Call</code>
111         *
112         * objects
113         *
114         * <p>This method requires the <code>Service</code> implementation
115         * class to have access to the WSDL related metadata.
116         *
117         * @param portName Qualified name for the target service endpoint
118         * @return Call[]  Array of pre-configured Call objects
119         * @throws ServiceException If this Service class does not
120         *              have access to the required WSDL metadata
121         *              or if an illegal <code>portName</code> is
122         *              specified.
123         */
124        public Call[] getCalls(QName portName) throws ServiceException;
125    
126        /**
127         * Creates a <code>Call</code> instance.
128         *
129         * @param portName Qualified name for the target service endpoint
130         * @return Call instance
131         * @throws ServiceException If any error in the creation of
132         *              the <code>Call</code> object
133         */
134        public Call createCall(QName portName) throws ServiceException;
135    
136        /**
137         * Creates a <code>Call</code> instance.
138         *
139         * @param portName Qualified name for the target service
140         *              endpoint
141         * @param operationName Qualified Name of the operation for
142         *              which this <code>Call</code> object is to
143         *              be created.
144         * @return Call instance
145         * @throws ServiceException If any error in the creation of
146         *              the <code>Call</code> object
147         */
148        public Call createCall(QName portName, QName operationName)
149            throws ServiceException;
150    
151        /**
152         * Creates a <code>Call</code> instance.
153         *
154         * @param portName Qualified name for the target service
155         *              endpoint
156         * @param operationName Name of the operation for which this
157         *                  <code>Call</code> object is to be
158         *                  created.
159         * @return Call instance
160         * @throws ServiceException If any error in the creation of
161         *              the <code>Call</code> object
162         */
163        public Call createCall(QName portName, String operationName)
164            throws ServiceException;
165    
166        /**
167         * Creates a <code>Call</code> object not associated with
168         * specific operation or target service endpoint. This
169         * <code>Call</code> object needs to be configured using the
170         * setter methods on the <code>Call</code> interface.
171         *
172         * @return  Call object
173         * @throws ServiceException If any error in the creation of
174         *              the <code>Call</code> object
175         */
176        public Call createCall() throws ServiceException;
177    
178        /**
179         * Gets the name of this Service.
180         *
181         * @return Qualified name of this service
182         */
183        public QName getServiceName();
184    
185        /**
186         * Returns an <code>Iterator</code> for the list of
187         * <code>QName</code>s of service endpoints grouped by this
188         * service.
189         *
190         * @return Returns <code>java.util.Iterator</code> with elements
191         *     of type <code>javax.xml.namespace.QName</code>
192         * @throws ServiceException If this Service class does not
193         *     have access to the required WSDL metadata
194         */
195        public java.util.Iterator getPorts() throws ServiceException;
196    
197        /**
198         * Gets location of the WSDL document for this Service.
199         *
200         * @return URL for the location of the WSDL document for
201         *     this service
202         */
203        public java.net.URL getWSDLDocumentLocation();
204    
205        /**
206         * Gets the <code>TypeMappingRegistry</code> for this
207         * <code>Service</code> object. The returned
208         * <code>TypeMappingRegistry</code> instance is pre-configured
209         * to support the standard type mapping between XML and Java
210         * types types as required by the JAX-RPC specification.
211         *
212         * @return  The TypeMappingRegistry for this Service object.
213         * @throws java.lang.UnsupportedOperationException if the <code>Service</code> class does not support
214         *     the configuration of <code>TypeMappingRegistry</code>.
215         */
216        public TypeMappingRegistry getTypeMappingRegistry();
217    
218        /**
219         * Returns the configured <code>HandlerRegistry</code> instance
220         * for this <code>Service</code> instance.
221         *
222         * @return HandlerRegistry
223         * @throws java.lang.UnsupportedOperationException - if the <code>Service</code> class does not support
224         *     the configuration of a <code>HandlerRegistry</code>
225         */
226        public HandlerRegistry getHandlerRegistry();
227    }
228