1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package javax.xml.rpc;
17
18 import javax.xml.namespace.QName;
19 import javax.xml.rpc.encoding.TypeMappingRegistry;
20 import javax.xml.rpc.handler.HandlerRegistry;
21
22 /**
23 * <code>Service</code> class acts as a factory of the following:
24 * <ul>
25 * <li>Dynamic proxy for the target service endpoint.
26 * <li>Instance of the type <code>javax.xml.rpc.Call</code> for
27 * the dynamic invocation of a remote operation on the
28 * target service endpoint.
29 * <li>Instance of a generated stub class
30 * </ul>
31 *
32 * @version 1.0
33 */
34 public interface Service {
35
36 /**
37 * The getPort method returns either an instance of a generated
38 * stub implementation class or a dynamic proxy. A service client
39 * uses this dynamic proxy to invoke operations on the target
40 * service endpoint. The <code>serviceEndpointInterface</code>
41 * specifies the service endpoint interface that is supported by
42 * the created dynamic proxy or stub instance.
43 *
44 * @param portName Qualified name of the service endpoint in
45 * the WSDL service description
46 * @param serviceEndpointInterface Service endpoint interface
47 * supported by the dynamic proxy or stub
48 * instance
49 * @return java.rmi.Remote Stub instance or dynamic proxy that
50 * supports the specified service endpoint
51 * interface
52 * @throws ServiceException This exception is thrown in the
53 * following cases:
54 * <ul>
55 * <li>If there is an error in creation of
56 * the dynamic proxy or stub instance
57 * <li>If there is any missing WSDL metadata
58 * as required by this method
59 * <li>Optionally, if an illegal
60 * <code>serviceEndpointInterface</code>
61 * or <code>portName</code> is specified
62 * </ul>
63 */
64 public java.rmi
65 .Remote getPort(QName portName, Class serviceEndpointInterface)
66 throws ServiceException;
67
68 /**
69 * The getPort method returns either an instance of a generated
70 * stub implementation class or a dynamic proxy. The parameter
71 * <code>serviceEndpointInterface</code> specifies the service
72 * endpoint interface that is supported by the returned stub or
73 * proxy. In the implementation of this method, the JAX-RPC
74 * runtime system takes the responsibility of selecting a protocol
75 * binding (and a port) and configuring the stub accordingly.
76 * The returned <code>Stub</code> instance should not be
77 * reconfigured by the client.
78 *
79 * @param serviceEndpointInterface Service endpoint interface
80 * @return Stub instance or dynamic proxy that supports the
81 * specified service endpoint interface
82 *
83 * @throws ServiceException <ul>
84 * <li>If there is an error during creation
85 * of stub instance or dynamic proxy
86 * <li>If there is any missing WSDL metadata
87 * as required by this method
88 * <li>Optionally, if an illegal
89 * <code>serviceEndpointInterface</code>
90 *
91 * is specified
92 * </ul>
93 */
94 public java.rmi.Remote getPort(Class serviceEndpointInterface)
95 throws ServiceException;
96
97 /**
98 * Gets an array of preconfigured <code>Call</code> objects for
99 * 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