Tue, 07 Nov 2017 18:54:04 -0800
Added tag jdk8u162-b06 for changeset 6095742f8034
1 /*
2 * Copyright (c) 2005, 2011, 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 */
26 package javax.xml.ws;
28 import java.security.Principal;
29 import javax.xml.ws.handler.MessageContext;
30 import javax.xml.ws.wsaddressing.W3CEndpointReference;
31 import org.w3c.dom.Element;
34 /**
35 * A <code>WebServiceContext</code> makes it possible for
36 * a web service endpoint implementation class to access
37 * message context and security information relative to
38 * a request being served.
39 *
40 * Typically a <code>WebServiceContext</code> is injected
41 * into an endpoint implementation class using the
42 * <code>Resource</code> annotation.
43 *
44 * @since JAX-WS 2.0
45 *
46 * @see javax.annotation.Resource
47 **/
48 public interface WebServiceContext {
50 /**
51 * Returns the <code>MessageContext</code> for the request being served
52 * at the time this method is called. Only properties with
53 * APPLICATION scope will be visible to the application.
54 *
55 * @return MessageContext The message context.
56 *
57 * @throws IllegalStateException This exception is thrown
58 * if the method is called while no request is
59 * being serviced.
60 *
61 * @see javax.xml.ws.handler.MessageContext
62 * @see javax.xml.ws.handler.MessageContext.Scope
63 * @see java.lang.IllegalStateException
64 **/
65 public MessageContext getMessageContext();
67 /**
68 * Returns the Principal that identifies the sender
69 * of the request currently being serviced. If the
70 * sender has not been authenticated, the method
71 * returns <code>null</code>.
72 *
73 * @return Principal The principal object.
74 *
75 * @throws IllegalStateException This exception is thrown
76 * if the method is called while no request is
77 * being serviced.
78 *
79 * @see java.security.Principal
80 * @see java.lang.IllegalStateException
81 **/
82 public Principal getUserPrincipal();
84 /**
85 * Returns a boolean indicating whether the
86 * authenticated user is included in the specified
87 * logical role. If the user has not been
88 * authenticated, the method returns <code>false</code>.
89 *
90 * @param role A <code>String</code> specifying the name of the role
91 *
92 * @return a <code>boolean</code> indicating whether
93 * the sender of the request belongs to a given role
94 *
95 * @throws IllegalStateException This exception is thrown
96 * if the method is called while no request is
97 * being serviced.
98 **/
99 public boolean isUserInRole(String role);
101 /**
102 * Returns the <code>EndpointReference</code> for this
103 * endpoint.
104 * <p>
105 * If the {@link Binding} for this <code>bindingProvider</code> is
106 * either SOAP1.1/HTTP or SOAP1.2/HTTP, then a
107 * <code>W3CEndpointReference</code> MUST be returned.
108 *
109 * @param referenceParameters Reference parameters to be associated with the
110 * returned <code>EndpointReference</code> instance.
111 * @return EndpointReference of the endpoint associated with this
112 * <code>WebServiceContext</code>.
113 * If the returned <code>EndpointReference</code> is of type
114 * <code>W3CEndpointReference</code> then it MUST contain the
115 * the specified <code>referenceParameters</code>.
116 *
117 * @throws IllegalStateException This exception is thrown
118 * if the method is called while no request is
119 * being serviced.
120 *
121 * @see W3CEndpointReference
122 *
123 * @since JAX-WS 2.1
124 */
125 public EndpointReference getEndpointReference(Element... referenceParameters);
127 /**
128 * Returns the <code>EndpointReference</code> associated with
129 * this endpoint.
130 *
131 * @param clazz The type of <code>EndpointReference</code> that
132 * MUST be returned.
133 * @param referenceParameters Reference parameters to be associated with the
134 * returned <code>EndpointReference</code> instance.
135 * @return EndpointReference of type <code>clazz</code> of the endpoint
136 * associated with this <code>WebServiceContext</code> instance.
137 * If the returned <code>EndpointReference</code> is of type
138 * <code>W3CEndpointReference</code> then it MUST contain the
139 * the specified <code>referenceParameters</code>.
140 *
141 * @throws IllegalStateException This exception is thrown
142 * if the method is called while no request is
143 * being serviced.
144 * @throws WebServiceException If the <code>clazz</code> type of
145 * <code>EndpointReference</code> is not supported.
146 *
147 * @since JAX-WS 2.1
148 **/
149 public <T extends EndpointReference> T getEndpointReference(Class<T> clazz,
150 Element... referenceParameters);
151 }