001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common Development
008: * and Distribution License("CDDL") (collectively, the "License"). You
009: * may not use this file except in compliance with the License. You can obtain
010: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
011: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
012: * language governing permissions and limitations under the License.
013: *
014: * When distributing the software, include this License Header Notice in each
015: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
016: * Sun designates this particular file as subject to the "Classpath" exception
017: * as provided by Sun in the GPL Version 2 section of the License file that
018: * accompanied this code. If applicable, add the following below the License
019: * Header, with the fields enclosed by brackets [] replaced by your own
020: * identifying information: "Portions Copyrighted [year]
021: * [name of copyright owner]"
022: *
023: * Contributor(s):
024: *
025: * If you wish your version of this file to be governed by only the CDDL or
026: * only the GPL Version 2, indicate your decision by adding "[Contributor]
027: * elects to include this software in this distribution under the [CDDL or GPL
028: * Version 2] license." If you don't indicate a single choice of license, a
029: * recipient has the option to distribute your version of this file under
030: * either the CDDL, the GPL Version 2 or to extend the choice of license to
031: * its licensees as provided above. However, if you add GPL Version 2 code
032: * and therefore, elected the GPL Version 2 license, then the option applies
033: * only if the new code is made subject to such option by the copyright
034: * holder.
035: */
036:
037: package com.sun.xml.ws.api.server;
038:
039: import com.sun.istack.NotNull;
040: import com.sun.istack.Nullable;
041: import com.sun.xml.ws.api.message.Packet;
042: import com.sun.xml.ws.api.pipe.Pipe;
043:
044: import javax.xml.ws.WebServiceContext;
045: import javax.xml.ws.WebServiceException;
046: import java.security.Principal;
047:
048: /**
049: * This object is set to {@link Packet#webServiceContextDelegate}
050: * to serve {@link WebServiceContext} methods for a {@link Packet}.
051: *
052: * <p>
053: * When the user application calls a method on {@link WebServiceContext},
054: * the JAX-WS RI goes to the {@link Packet} that represents the request,
055: * then check {@link Packet#webServiceContextDelegate}, and forwards
056: * the method calls to {@link WebServiceContextDelegate}.
057: *
058: * <p>
059: * All the methods defined on this interface takes {@link Packet}
060: * (whose {@link Packet#webServiceContextDelegate} points to
061: * this object), so that a single stateless {@link WebServiceContextDelegate}
062: * can be used to serve multiple concurrent {@link Packet}s,
063: * if the implementation wishes to do so.
064: *
065: * <p>
066: * (It is also allowed to create one instance of
067: * {@link WebServiceContextDelegate} for each packet,
068: * and thus effectively ignore the packet parameter.)
069: *
070: * <p>
071: * Attaching this on a {@link Packet} allows {@link Pipe}s to
072: * intercept and replace them, if they wish.
073: *
074: *
075: * @author Kohsuke Kawaguchi
076: */
077: public interface WebServiceContextDelegate {
078: /**
079: * Implements {@link WebServiceContext#getUserPrincipal()}
080: * for the given packet.
081: *
082: * @param request
083: * Always non-null. See class javadoc.
084: * @see WebServiceContext#getUserPrincipal()
085: */
086: Principal getUserPrincipal(@NotNull
087: Packet request);
088:
089: /**
090: * Implements {@link WebServiceContext#isUserInRole(String)}
091: * for the given packet.
092: *
093: * @param request
094: * Always non-null. See class javadoc.
095: * @see WebServiceContext#isUserInRole(String)
096: */
097: boolean isUserInRole(@NotNull
098: Packet request, String role);
099:
100: /**
101: * Gets the address of the endpoint.
102: *
103: * <p>
104: * The "address" of endpoints is always affected by a particular
105: * client being served, hence it's up to transport to provide this
106: * information.
107: *
108: * @param request
109: * Always non-null. See class javadoc.
110: * @param endpoint
111: * The endpoint whose address will be returned.
112: *
113: * @throws WebServiceException
114: * if this method could not compute the address for some reason.
115: * @return
116: * Absolute URL of the endpoint. This shold be an address that the client
117: * can use to talk back to this same service later.
118: *
119: * @see WebServiceContext#getEndpointReference
120: */
121: @NotNull
122: String getEPRAddress(@NotNull
123: Packet request, @NotNull
124: WSEndpoint endpoint);
125:
126: /**
127: * Gets the address of the primary WSDL.
128: *
129: * <p>
130: * If a transport supports publishing of WSDL by itself (instead/in addition to MEX),
131: * then it should implement this method so that the rest of the JAX-WS RI can
132: * use that information.
133: *
134: * For example, HTTP transports often use the convention {@code getEPRAddress()+"?wsdl"}
135: * for publishing WSDL on HTTP.
136: *
137: * <p>
138: * Some transports may not have such WSDL publishing mechanism on its own.
139: * Those transports may choose to return null, indicating that WSDL
140: * is not published. If such transports are always used in conjunction with
141: * other transports that support WSDL publishing (such as SOAP/TCP used
142: * with Servlet transport), then such transport may
143: * choose to find the corresponding servlet endpoint by {@link Module#getBoundEndpoints()}
144: * and try to obtain the address from there.
145: *
146: * <p>
147: * This information is used to put a metadata reference inside an EPR,
148: * among other things. Clients that do not support MEX rely on this
149: * WSDL URL to retrieve metadata, it is desirable for transports to support
150: * this, but not mandatory.
151: *
152: * <p>
153: * This method will be never invoked if the {@link WSEndpoint}
154: * does not have a corresponding WSDL to begin with
155: * (IOW {@link WSEndpoint#getServiceDefinition() returning null}.
156: *
157: * @param request
158: * Always non-null. See class javadoc.
159: * @param endpoint
160: * The endpoint whose address will be returned.
161: *
162: * @return
163: * null if the implementation does not support the notion of
164: * WSDL publishing.
165: */
166: @Nullable
167: String getWSDLAddress(@NotNull
168: Packet request, @NotNull
169: WSEndpoint endpoint);
170: }
|