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
26package javax.xml.ws;
27
28import java.security.Principal;
29import javax.xml.ws.handler.MessageContext;
30import javax.xml.ws.wsaddressing.W3CEndpointReference;
31import 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 **/
48public 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}
153