Service


1   /*
2    * Copyright 2001-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
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 
225
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags