1 /*
   2  * Copyright (c) 2005, 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 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 1.6, 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 1.6, 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 1.6, JAX-WS 2.1
 148      **/
 149     public <T extends EndpointReference> T getEndpointReference(Class<T> clazz,
 150             Element... referenceParameters);
 151 }