1 /*
2 * Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.xml.ws;
27
28 import java.util.Map;
29 import javax.xml.ws.wsaddressing.W3CEndpointReference;
30
31 /**
32 * The <code>BindingProvider</code> interface provides access to the
33 * protocol binding and associated context objects for request and
34 * response message processing.
35 *
36 * @since JAX-WS 2.0
37 *
38 * @see javax.xml.ws.Binding
39 **/
40 public interface BindingProvider {
41 /**
42 * Standard property: User name for authentication.
43 * <p>Type: <code>java.lang.String</code>
44 **/
45 public static final String USERNAME_PROPERTY =
46 "javax.xml.ws.security.auth.username";
47
48 /**
49 * Standard property: Password for authentication.
50 * <p>Type: <code>java.lang.String</code>
51 **/
52 public static final String PASSWORD_PROPERTY =
53 "javax.xml.ws.security.auth.password";
54
55 /**
56 * Standard property: Target service endpoint address. The
57 * URI scheme for the endpoint address specification MUST
58 * correspond to the protocol/transport binding for the
59 * binding in use.
60 * <p>Type: <code>java.lang.String</code>
61 **/
62 public static final String ENDPOINT_ADDRESS_PROPERTY =
63 "javax.xml.ws.service.endpoint.address";
64
65 /**
66 * Standard property: This boolean property is used by a service
67 * client to indicate whether or not it wants to participate in
68 * a session with a service endpoint. If this property is set to
69 * <code>true</code>, the service client indicates that it wants the session
70 * to be maintained. If set to <code>false</code>, the session is not maintained.
71 * The default value for this property is <code>false</code>.
72 * <p>Type: <code>java.lang.Boolean</code>
73 **/
74 public static final String SESSION_MAINTAIN_PROPERTY =
75 "javax.xml.ws.session.maintain";
76
77 /**
78 * Standard property for SOAPAction. This boolean property
79 * indicates whether or not the value of the
80 * <code>javax.xml.ws.soap.http.soapaction.uri</code> property
81 * is used for the value of the SOAPAction. The
82 * default value of this property is <code>false</code> indicating
83 * that the
84 * <code>javax.xml.ws.soap.http.soapaction.uri</code> property
85 * is not used for the value of the SOAPAction, however,
86 * if WS-Addressing is enabled, the default value is
87 * <code>true</code>.
88 *
89 * <p>Type: <code>java.lang.Boolean</code>
90 **/
91 public static final String SOAPACTION_USE_PROPERTY =
92 "javax.xml.ws.soap.http.soapaction.use";
93
94 /**
95 * Standard property for SOAPAction. Indicates the SOAPAction
96 * URI if the <code>javax.xml.ws.soap.http.soapaction.use</code>
97 * property is set to <code>true</code>. If WS-Addressing
98 * is enabled, this value will also be used for the value of the
99 * WS-Addressing Action header. If this property is not set,
100 * the default SOAPAction and WS-Addressing Action will be sent.
101 *
102 * <p>Type: <code>java.lang.String</code>
103 **/
104 public static final String SOAPACTION_URI_PROPERTY =
105 "javax.xml.ws.soap.http.soapaction.uri";
106
107 /**
108 * Get the context that is used to initialize the message context
109 * for request messages.
110 *
111 * Modifications to the request context do not affect the message context of
112 * either synchronous or asynchronous operations that have already been
113 * started.
114 *
115 * @return The context that is used in processing request messages.
116 **/
117 Map<String, Object> getRequestContext();
118
119 /**
120 * Get the context that resulted from processing a response message.
121 *
122 * The returned context is for the most recently completed synchronous
123 * operation. Subsequent synchronous operation invocations overwrite the
124 * response context. Asynchronous operations return their response context
125 * via the Response interface.
126 *
127 * @return The context that resulted from processing the latest
128 * response messages.
129 **/
130 Map<String, Object> getResponseContext();
131
132 /**
133 * Get the Binding for this binding provider.
134 *
135 * @return The Binding for this binding provider.
136 **/
137 Binding getBinding();
138
139
140
141 /**
142 * Returns the <code>EndpointReference</code> associated with
143 * this <code>BindingProvider</code> instance.
144 * <p>
145 * If the Binding for this <code>bindingProvider</code> is
146 * either SOAP1.1/HTTP or SOAP1.2/HTTP, then a
147 * <code>W3CEndpointReference</code> MUST be returned.
148 *
149 * @return EndpointReference of the target endpoint associated with this
150 * <code>BindingProvider</code> instance.
151 *
152 * @throws java.lang.UnsupportedOperationException If this
153 * <code>BindingProvider</code> uses the XML/HTTP binding.
154 *
155 * @see W3CEndpointReference
156 *
157 * @since JAX-WS 2.1
158 */
159 public EndpointReference getEndpointReference();
160
161
162 /**
163 * Returns the <code>EndpointReference</code> associated with
164 * this <code>BindingProvider</code> instance. The instance
165 * returned will be of type <code>clazz</code>.
166 *
167 * @param clazz Specifies the type of <code>EndpointReference</code>
168 * that MUST be returned.
169
170 * @return EndpointReference of the target endpoint associated with this
171 * <code>BindingProvider</code> instance. MUST be of type
172 * <code>clazz</code>.
173
174 * @throws WebServiceException If the Class <code>clazz</code>
175 * is not supported by this implementation.
176 * @throws java.lang.UnsupportedOperationException If this
177 * <code>BindingProvider</code> uses the XML/HTTP binding.
178 *
179 * @since JAX-WS 2.1
180 */
181 public <T extends EndpointReference> T getEndpointReference(Class<T> clazz);
182 }