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.api.server;
27  
28  import com.sun.istack.internal.NotNull;
29  import com.sun.istack.internal.Nullable;
30  import com.sun.xml.internal.ws.api.message.Packet;
31  import com.sun.xml.internal.ws.api.pipe.Pipe;
32  
33  import javax.xml.ws.WebServiceContext;
34  import javax.xml.ws.WebServiceException;
35  import java.security.Principal;
36  
37  /**
38   * This object is set to {@link Packet#webServiceContextDelegate}
39   * to serve {@link WebServiceContext} methods for a {@link Packet}.
40   *
41   * <p>
42   * When the user application calls a method on {@link WebServiceContext},
43   * the JAX-WS RI goes to the {@link Packet} that represents the request,
44   * then check {@link Packet#webServiceContextDelegate}, and forwards
45   * the method calls to {@link WebServiceContextDelegate}.
46   *
47   * <p>
48   * All the methods defined on this interface takes {@link Packet}
49   * (whose {@link Packet#webServiceContextDelegate} points to
50   * this object), so that a single stateless {@link WebServiceContextDelegate}
51   * can be used to serve multiple concurrent {@link Packet}s,
52   * if the implementation wishes to do so.
53   *
54   * <p>
55   * (It is also allowed to create one instance of
56   * {@link WebServiceContextDelegate} for each packet,
57   * and thus effectively ignore the packet parameter.)
58   *
59   * <p>
60   * Attaching this on a {@link Packet} allows {@link Pipe}s to
61   * intercept and replace them, if they wish.
62   *
63   *
64   * @author Kohsuke Kawaguchi
65   */
66  public interface WebServiceContextDelegate {
67      /**
68       * Implements {@link WebServiceContext#getUserPrincipal()}
69       * for the given packet.
70       *
71       * @param request
72       *      Always non-null. See class javadoc.
73       * @see WebServiceContext#getUserPrincipal()
74       */
75      Principal getUserPrincipal(@NotNull Packet request);
76  
77      /**
78       * Implements {@link WebServiceContext#isUserInRole(String)}
79       * for the given packet.
80       *
81       * @param request
82       *      Always non-null. See class javadoc.
83       * @see WebServiceContext#isUserInRole(String)
84       */
85      boolean isUserInRole(@NotNull Packet request,String role);
86  
87      /**
88       * Gets the address of the endpoint.
89       *
90       * <p>
91       * The "address" of endpoints is always affected by a particular
92       * client being served, hence it's up to transport to provide this
93       * information.
94       *
95       * @param request
96       *      Always non-null. See class javadoc.
97       * @param endpoint
98       *      The endpoint whose address will be returned.
99       *
100      * @throws WebServiceException
101      *      if this method could not compute the address for some reason.
102      * @return
103      *      Absolute URL of the endpoint. This shold be an address that the client
104      *      can use to talk back to this same service later.
105      *
106      * @see WebServiceContext#getEndpointReference
107      */
108     @NotNull String getEPRAddress(@NotNull Packet request, @NotNull WSEndpoint endpoint);
109 
110     /**
111      * Gets the address of the primary WSDL.
112      *
113      * <p>
114      * If a transport supports publishing of WSDL by itself (instead/in addition to MEX),
115      * then it should implement this method so that the rest of the JAX-WS RI can
116      * use that information.
117      *
118      * For example, HTTP transports often use the convention {@code getEPRAddress()+"?wsdl"}
119      * for publishing WSDL on HTTP.
120      *
121      * <p>
122      * Some transports may not have such WSDL publishing mechanism on its own.
123      * Those transports may choose to return null, indicating that WSDL
124      * is not published. If such transports are always used in conjunction with
125      * other transports that support WSDL publishing (such as SOAP/TCP used
126      * with Servlet transport), then such transport may
127      * choose to find the corresponding servlet endpoint by {@link Module#getBoundEndpoints()}
128      * and try to obtain the address from there.
129      *
130      * <p>
131      * This information is used to put a metadata reference inside an EPR,
132      * among other things. Clients that do not support MEX rely on this
133      * WSDL URL to retrieve metadata, it is desirable for transports to support
134      * this, but not mandatory.
135      *
136      * <p>
137      * This method will be never invoked if the {@link WSEndpoint}
138      * does not have a corresponding WSDL to begin with
139      * (IOW {@link WSEndpoint#getServiceDefinition() returning null}.
140      *
141      * @param request
142      *      Always non-null. See class javadoc.
143      * @param endpoint
144      *      The endpoint whose address will be returned.
145      *
146      * @return
147      *      null if the implementation does not support the notion of
148      *      WSDL publishing.
149      */
150     @Nullable String getWSDLAddress(@NotNull Packet request, @NotNull WSEndpoint endpoint);
151 }