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