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