View Javadoc
1   /*
2    * Copyright (c) 1997, 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 com.sun.xml.internal.ws.developer;
27  
28  import com.sun.istack.internal.NotNull;
29  import com.sun.xml.internal.ws.api.ComponentRegistry;
30  import com.sun.xml.internal.ws.api.message.Header;
31  import com.sun.xml.internal.ws.api.message.Headers;
32  import com.sun.xml.internal.ws.api.addressing.WSEndpointReference;
33  import com.sun.xml.internal.ws.api.client.WSPortInfo;
34  import javax.xml.bind.JAXBContext;
35  import javax.xml.namespace.QName;
36  import javax.xml.ws.BindingProvider;
37  import javax.xml.ws.Dispatch;
38  import javax.xml.ws.Service;
39  import javax.xml.ws.Service.Mode;
40  import java.util.List;
41  import java.io.Closeable;
42  import com.sun.org.glassfish.gmbal.ManagedObjectManager;
43  
44  /**
45   * {@link BindingProvider} with JAX-WS RI's extension methods.
46   *
47   * @author Kohsuke Kawaguchi
48   * @author Jitendra Kotamraju
49   * @since 2.1EA3
50   */
51  public interface WSBindingProvider extends BindingProvider, Closeable, ComponentRegistry {
52      /**
53       * Sets the out-bound headers to be added to messages sent from
54       * this {@link BindingProvider}.
55       *
56       * <p>
57       * Calling this method would discard any out-bound headers
58       * that were previously set.
59       *
60       * <p>
61       * A new {@link Header} object can be created by using
62       * one of the methods on {@link Headers}.
63       *
64       * @param headers
65       *      The headers to be added to the future request messages.
66       *      To clear the outbound headers, pass in either null
67       *      or empty list.
68       * @throws IllegalArgumentException
69       *      if the list contains null item.
70       */
71      void setOutboundHeaders(List<Header> headers);
72  
73      /**
74       * Sets the out-bound headers to be added to messages sent from
75       * this {@link BindingProvider}.
76       *
77       * <p>
78       * Works like {@link #setOutboundHeaders(List)} except
79       * that it accepts a var arg array.
80       *
81       * @param headers
82       *      Can be null or empty.
83       */
84      void setOutboundHeaders(Header... headers);
85  
86      /**
87       * Sets the out-bound headers to be added to messages sent from
88       * this {@link BindingProvider}.
89       *
90       * <p>
91       * Each object must be a JAXB-bound object that is understood
92       * by the {@link JAXBContext} object known by this {@link WSBindingProvider}
93       * (that is, if this is a {@link Dispatch} with JAXB, then
94       * {@link JAXBContext} given to {@link Service#createDispatch(QName,JAXBContext,Mode)}
95       * and if this is a typed proxy, then {@link JAXBContext}
96       * implicitly created by the JAX-WS RI.)
97       *
98       * @param headers
99       *      Can be null or empty.
100      * @throws UnsupportedOperationException
101      *      If this {@link WSBindingProvider} is a {@link Dispatch}
102      *      that does not use JAXB.
103      */
104     void setOutboundHeaders(Object... headers);
105 
106     List<Header> getInboundHeaders();
107 
108     /**
109      * Sets the endpoint address for all the invocations that happen
110      * from {@link BindingProvider}. Instead of doing the following
111      *
112      * <p>
113      * ((BindingProvider)proxy).getRequestContext().put(
114      *      BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "...")
115      * <p>
116      * you could do this:
117      *
118      * <p>
119      * ((WSBindingProvider)proxy).setAddress("...");
120      *
121      * @param address Address of the service
122      */
123     void setAddress(String address);
124 
125     /**
126      * Similar to {link BindingProvider#getEndpointReference(}, but returns WSEndpointReference that has more
127      * convenience methods
128      *
129      * @return WSEndpointReference of the target servcie endpoint
130      *
131      * @since JAX-WS 2.2
132      */
133     WSEndpointReference getWSEndpointReference();
134 
135     /**
136      *
137      * @return WSPortInfo object that captures the port information for which the stub is created.
138      * @since JAX-WS 2.2
139      */
140     WSPortInfo getPortInfo();
141 
142     /**
143      * Get the ManagedObjectManager for this provider.
144      */
145     public @NotNull ManagedObjectManager getManagedObjectManager();
146 }