ohair@286: /* ohair@286: * Copyright (c) 1997, 2010, Oracle and/or its affiliates. All rights reserved. ohair@286: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. ohair@286: * ohair@286: * This code is free software; you can redistribute it and/or modify it ohair@286: * under the terms of the GNU General Public License version 2 only, as ohair@286: * published by the Free Software Foundation. Oracle designates this ohair@286: * particular file as subject to the "Classpath" exception as provided ohair@286: * by Oracle in the LICENSE file that accompanied this code. ohair@286: * ohair@286: * This code is distributed in the hope that it will be useful, but WITHOUT ohair@286: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or ohair@286: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License ohair@286: * version 2 for more details (a copy is included in the LICENSE file that ohair@286: * accompanied this code). ohair@286: * ohair@286: * You should have received a copy of the GNU General Public License version ohair@286: * 2 along with this work; if not, write to the Free Software Foundation, ohair@286: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. ohair@286: * ohair@286: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA ohair@286: * or visit www.oracle.com if you need additional information or have any ohair@286: * questions. ohair@286: */ ohair@286: ohair@286: package com.sun.xml.internal.ws.api.server; ohair@286: ohair@286: import com.sun.istack.internal.NotNull; ohair@286: import com.sun.istack.internal.Nullable; ohair@286: import com.sun.xml.internal.ws.api.message.Packet; ohair@286: import com.sun.xml.internal.ws.api.pipe.Pipe; ohair@286: ohair@286: import javax.xml.ws.WebServiceContext; ohair@286: import javax.xml.ws.WebServiceException; ohair@286: import java.security.Principal; ohair@286: ohair@286: /** ohair@286: * This object is set to {@link Packet#webServiceContextDelegate} ohair@286: * to serve {@link WebServiceContext} methods for a {@link Packet}. ohair@286: * ohair@286: *

ohair@286: * When the user application calls a method on {@link WebServiceContext}, ohair@286: * the JAX-WS RI goes to the {@link Packet} that represents the request, ohair@286: * then check {@link Packet#webServiceContextDelegate}, and forwards ohair@286: * the method calls to {@link WebServiceContextDelegate}. ohair@286: * ohair@286: *

ohair@286: * All the methods defined on this interface takes {@link Packet} ohair@286: * (whose {@link Packet#webServiceContextDelegate} points to ohair@286: * this object), so that a single stateless {@link WebServiceContextDelegate} ohair@286: * can be used to serve multiple concurrent {@link Packet}s, ohair@286: * if the implementation wishes to do so. ohair@286: * ohair@286: *

ohair@286: * (It is also allowed to create one instance of ohair@286: * {@link WebServiceContextDelegate} for each packet, ohair@286: * and thus effectively ignore the packet parameter.) ohair@286: * ohair@286: *

ohair@286: * Attaching this on a {@link Packet} allows {@link Pipe}s to ohair@286: * intercept and replace them, if they wish. ohair@286: * ohair@286: * ohair@286: * @author Kohsuke Kawaguchi ohair@286: */ ohair@286: public interface WebServiceContextDelegate { ohair@286: /** ohair@286: * Implements {@link WebServiceContext#getUserPrincipal()} ohair@286: * for the given packet. ohair@286: * ohair@286: * @param request ohair@286: * Always non-null. See class javadoc. ohair@286: * @see WebServiceContext#getUserPrincipal() ohair@286: */ ohair@286: Principal getUserPrincipal(@NotNull Packet request); ohair@286: ohair@286: /** ohair@286: * Implements {@link WebServiceContext#isUserInRole(String)} ohair@286: * for the given packet. ohair@286: * ohair@286: * @param request ohair@286: * Always non-null. See class javadoc. ohair@286: * @see WebServiceContext#isUserInRole(String) ohair@286: */ ohair@286: boolean isUserInRole(@NotNull Packet request,String role); ohair@286: ohair@286: /** ohair@286: * Gets the address of the endpoint. ohair@286: * ohair@286: *

ohair@286: * The "address" of endpoints is always affected by a particular ohair@286: * client being served, hence it's up to transport to provide this ohair@286: * information. ohair@286: * ohair@286: * @param request ohair@286: * Always non-null. See class javadoc. ohair@286: * @param endpoint ohair@286: * The endpoint whose address will be returned. ohair@286: * ohair@286: * @throws WebServiceException ohair@286: * if this method could not compute the address for some reason. ohair@286: * @return ohair@286: * Absolute URL of the endpoint. This shold be an address that the client ohair@286: * can use to talk back to this same service later. ohair@286: * ohair@286: * @see WebServiceContext#getEndpointReference ohair@286: */ ohair@286: @NotNull String getEPRAddress(@NotNull Packet request, @NotNull WSEndpoint endpoint); ohair@286: ohair@286: /** ohair@286: * Gets the address of the primary WSDL. ohair@286: * ohair@286: *

ohair@286: * If a transport supports publishing of WSDL by itself (instead/in addition to MEX), ohair@286: * then it should implement this method so that the rest of the JAX-WS RI can ohair@286: * use that information. ohair@286: * ohair@286: * For example, HTTP transports often use the convention {@code getEPRAddress()+"?wsdl"} ohair@286: * for publishing WSDL on HTTP. ohair@286: * ohair@286: *

ohair@286: * Some transports may not have such WSDL publishing mechanism on its own. ohair@286: * Those transports may choose to return null, indicating that WSDL ohair@286: * is not published. If such transports are always used in conjunction with ohair@286: * other transports that support WSDL publishing (such as SOAP/TCP used ohair@286: * with Servlet transport), then such transport may ohair@286: * choose to find the corresponding servlet endpoint by {@link Module#getBoundEndpoints()} ohair@286: * and try to obtain the address from there. ohair@286: * ohair@286: *

ohair@286: * This information is used to put a metadata reference inside an EPR, ohair@286: * among other things. Clients that do not support MEX rely on this ohair@286: * WSDL URL to retrieve metadata, it is desirable for transports to support ohair@286: * this, but not mandatory. ohair@286: * ohair@286: *

ohair@286: * This method will be never invoked if the {@link WSEndpoint} ohair@286: * does not have a corresponding WSDL to begin with ohair@286: * (IOW {@link WSEndpoint#getServiceDefinition() returning null}. ohair@286: * ohair@286: * @param request ohair@286: * Always non-null. See class javadoc. ohair@286: * @param endpoint ohair@286: * The endpoint whose address will be returned. ohair@286: * ohair@286: * @return ohair@286: * null if the implementation does not support the notion of ohair@286: * WSDL publishing. ohair@286: */ ohair@286: @Nullable String getWSDLAddress(@NotNull Packet request, @NotNull WSEndpoint endpoint); ohair@286: }