1/* 2 * Copyright (c) 1997, 2013, 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 com.sun.xml.internal.ws.api.server; 27 28import com.sun.istack.internal.NotNull; 29import com.sun.istack.internal.Nullable; 30import com.sun.xml.internal.ws.api.message.Packet; 31import com.sun.xml.internal.ws.api.pipe.Pipe; 32 33import javax.xml.ws.WebServiceContext; 34import javax.xml.ws.WebServiceException; 35import java.security.Principal; 36 37/** 38 * This object is set to {@link Packet#webServiceContextDelegate} 39 * to serve {@link WebServiceContext} methods for a {@link Packet}. 40 * 41 * <p> 42 * When the user application calls a method on {@link WebServiceContext}, 43 * the JAX-WS RI goes to the {@link Packet} that represents the request, 44 * then check {@link Packet#webServiceContextDelegate}, and forwards 45 * the method calls to {@link WebServiceContextDelegate}. 46 * 47 * <p> 48 * All the methods defined on this interface takes {@link Packet} 49 * (whose {@link Packet#webServiceContextDelegate} points to 50 * this object), so that a single stateless {@link WebServiceContextDelegate} 51 * can be used to serve multiple concurrent {@link Packet}s, 52 * if the implementation wishes to do so. 53 * 54 * <p> 55 * (It is also allowed to create one instance of 56 * {@link WebServiceContextDelegate} for each packet, 57 * and thus effectively ignore the packet parameter.) 58 * 59 * <p> 60 * Attaching this on a {@link Packet} allows {@link Pipe}s to 61 * intercept and replace them, if they wish. 62 * 63 * 64 * @author Kohsuke Kawaguchi 65 */ 66public interface WebServiceContextDelegate { 67 /** 68 * Implements {@link WebServiceContext#getUserPrincipal()} 69 * for the given packet. 70 * 71 * @param request 72 * Always non-null. See class javadoc. 73 * @see WebServiceContext#getUserPrincipal() 74 */ 75 Principal getUserPrincipal(@NotNull Packet request); 76 77 /** 78 * Implements {@link WebServiceContext#isUserInRole(String)} 79 * for the given packet. 80 * 81 * @param request 82 * Always non-null. See class javadoc. 83 * @see WebServiceContext#isUserInRole(String) 84 */ 85 boolean isUserInRole(@NotNull Packet request,String role); 86 87 /** 88 * Gets the address of the endpoint. 89 * 90 * <p> 91 * The "address" of endpoints is always affected by a particular 92 * client being served, hence it's up to transport to provide this 93 * information. 94 * 95 * @param request 96 * Always non-null. See class javadoc. 97 * @param endpoint 98 * The endpoint whose address will be returned. 99 * 100 * @throws WebServiceException 101 * if this method could not compute the address for some reason. 102 * @return 103 * Absolute URL of the endpoint. This shold be an address that the client 104 * can use to talk back to this same service later. 105 * 106 * @see WebServiceContext#getEndpointReference 107 */ 108 @NotNull String getEPRAddress(@NotNull Packet request, @NotNull WSEndpoint endpoint); 109 110 /** 111 * Gets the address of the primary WSDL. 112 * 113 * <p> 114 * If a transport supports publishing of WSDL by itself (instead/in addition to MEX), 115 * then it should implement this method so that the rest of the JAX-WS RI can 116 * use that information. 117 * 118 * For example, HTTP transports often use the convention {@code getEPRAddress()+"?wsdl"} 119 * for publishing WSDL on HTTP. 120 * 121 * <p> 122 * Some transports may not have such WSDL publishing mechanism on its own. 123 * Those transports may choose to return null, indicating that WSDL 124 * is not published. If such transports are always used in conjunction with 125 * other transports that support WSDL publishing (such as SOAP/TCP used 126 * with Servlet transport), then such transport may 127 * choose to find the corresponding servlet endpoint by {@link Module#getBoundEndpoints()} 128 * and try to obtain the address from there. 129 * 130 * <p> 131 * This information is used to put a metadata reference inside an EPR, 132 * among other things. Clients that do not support MEX rely on this 133 * WSDL URL to retrieve metadata, it is desirable for transports to support 134 * this, but not mandatory. 135 * 136 * <p> 137 * This method will be never invoked if the {@link WSEndpoint} 138 * does not have a corresponding WSDL to begin with 139 * (IOW {@link WSEndpoint#getServiceDefinition() returning null}. 140 * 141 * @param request 142 * Always non-null. See class javadoc. 143 * @param endpoint 144 * The endpoint whose address will be returned. 145 * 146 * @return 147 * null if the implementation does not support the notion of 148 * WSDL publishing. 149 */ 150 @Nullable String getWSDLAddress(@NotNull Packet request, @NotNull WSEndpoint endpoint); 151} 152