jdk8-mips64-public/jaxws: src/share/jaxws_classes/com/sun/xml/internal/ws/api/server/WebServiceContextDelegate.java@9c07ef4934dd

     1 /*

     2  * Copyright (c) 1997, 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  */

    26 package com.sun.xml.internal.ws.api.server;

    28 import com.sun.istack.internal.NotNull;

    29 import com.sun.istack.internal.Nullable;

    30 import com.sun.xml.internal.ws.api.message.Packet;

    31 import com.sun.xml.internal.ws.api.pipe.Pipe;

    33 import javax.xml.ws.WebServiceContext;

    34 import javax.xml.ws.WebServiceException;

    35 import java.security.Principal;

    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  */

    66 public 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);

    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);

    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);

   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 }

Mercurial > jdk8-mips64-public > jaxws / file revision