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