View Javadoc
1   /*
2    * Copyright (c) 2005, 2010, 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 }