1 /* 2 * Copyright (c) 2005, 2015, 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 clazz The type of {@code EndpointReference} that 132 * MUST be returned. 133 * @param referenceParameters Reference parameters to be associated with the 134 * returned {@code EndpointReference} instance. 135 * @return EndpointReference of type {@code clazz} of the endpoint 136 * associated with this {@code WebServiceContext} instance. 137 * If the returned {@code EndpointReference} is of type 138 * {@code W3CEndpointReference} then it MUST contain the 139 * the specified {@code referenceParameters}. 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} type of 145 * {@code EndpointReference} 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 }