1 /*
2 * Copyright (c) 2005, 2017, 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.security.Principal;
29 import javax.xml.ws.handler.MessageContext;
30 import javax.xml.ws.wsaddressing.W3CEndpointReference;
31 import org.w3c.dom.Element;
32
33
34 /**
35 * A {@code WebServiceContext} 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} is injected
41 * into an endpoint implementation class using the
42 * {@code Resource} annotation.
43 *
44 * @since 1.6, JAX-WS 2.0
45 *
46 * @see javax.annotation.Resource
47 **/
48 public interface WebServiceContext {
49
50 /**
51 * Returns the {@code MessageContext} 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();
66
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}.
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();
83
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}.
89 *
90 * @param role A {@code String} specifying the name of the role
91 *
92 * @return a {@code boolean} 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);
100
101 /**
102 * Returns the {@code EndpointReference} for this
103 * endpoint.
104 * <p>
105 * If the {@link Binding} for this {@code bindingProvider} is
106 * either SOAP1.1/HTTP or SOAP1.2/HTTP, then a
107 * {@code W3CEndpointReference} MUST be returned.
108 *
109 * @param referenceParameters Reference parameters to be associated with the
110 * returned {@code EndpointReference} instance.
111 * @return EndpointReference of the endpoint associated with this
112 * {@code WebServiceContext}.
113 * If the returned {@code EndpointReference} is of type
114 * {@code W3CEndpointReference} then it MUST contain the
115 * the specified {@code referenceParameters}.
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 1.6, JAX-WS 2.1
124 */
125 public EndpointReference getEndpointReference(Element... referenceParameters);
126
127 /**
128 * Returns the {@code EndpointReference} associated with
129 * this endpoint.
130 *
131 * @param <T> The type of {@code EndpointReference}.
132 * @param clazz The type of {@code EndpointReference} that
133 * MUST be returned.
134 * @param referenceParameters Reference parameters to be associated with the
135 * returned {@code EndpointReference} instance.
136 * @return EndpointReference of type {@code clazz} of the endpoint
137 * associated with this {@code WebServiceContext} instance.
138 * If the returned {@code EndpointReference} is of type
139 * {@code W3CEndpointReference} then it MUST contain the
140 * the specified {@code referenceParameters}.
141 *
142 * @throws IllegalStateException This exception is thrown
143 * if the method is called while no request is
144 * being serviced.
145 * @throws WebServiceException If the {@code clazz} type of
146 * {@code EndpointReference} is not supported.
147 *
148 * @since 1.6, JAX-WS 2.1
149 **/
150 public <T extends EndpointReference> T getEndpointReference(Class<T> clazz,
151 Element... referenceParameters);
152 }