View Javadoc
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   */
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</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 {
49  
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();
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</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();
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</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);
100 
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);
126 
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 }