001: /*
002: * Copyright 2007 Sun Microsystems, Inc. All rights reserved.
003: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
004: */
005:
006: package javax.xml.ws;
007:
008: import java.security.Principal;
009: import javax.xml.ws.handler.MessageContext;
010: import javax.xml.ws.wsaddressing.W3CEndpointReference;
011: import org.w3c.dom.Element;
012:
013: /**
014: * A <code>WebServiceContext</code> makes it possible for
015: * a web service endpoint implementation class to access
016: * message context and security information relative to
017: * a request being served.
018: *
019: * Typically a <code>WebServiceContext</code> is injected
020: * into an endpoint implementation class using the
021: * <code>Resource</code> annotation.
022: *
023: * @since JAX-WS 2.0
024: *
025: * @see javax.annotation.Resource
026: **/
027: public interface WebServiceContext {
028:
029: /**
030: * Returns the <code>MessageContext</code> for the request being served
031: * at the time this method is called. Only properties with
032: * APPLICATION scope will be visible to the application.
033: *
034: * @return MessageContext The message context.
035: *
036: * @throws IllegalStateException This exception is thrown
037: * if the method is called while no request is
038: * being serviced.
039: *
040: * @see javax.xml.ws.handler.MessageContext
041: * @see javax.xml.ws.handler.MessageContext.Scope
042: * @see java.lang.IllegalStateException
043: **/
044: public MessageContext getMessageContext();
045:
046: /**
047: * Returns the Principal that identifies the sender
048: * of the request currently being serviced. If the
049: * sender has not been authenticated, the method
050: * returns <code>null</code>.
051: *
052: * @return Principal The principal object.
053: *
054: * @throws IllegalStateException This exception is thrown
055: * if the method is called while no request is
056: * being serviced.
057: *
058: * @see java.security.Principal
059: * @see java.lang.IllegalStateException
060: **/
061: public Principal getUserPrincipal();
062:
063: /**
064: * Returns a boolean indicating whether the
065: * authenticated user is included in the specified
066: * logical role. If the user has not been
067: * authenticated, the method returns </code>false</code>.
068: *
069: * @param role A <code>String</code> specifying the name of the role
070: *
071: * @return a <code>boolean</code> indicating whether
072: * the sender of the request belongs to a given role
073: *
074: * @throws IllegalStateException This exception is thrown
075: * if the method is called while no request is
076: * being serviced.
077: **/
078: public boolean isUserInRole(String role);
079:
080: /**
081: * Returns the <code>EndpointReference</code> for this
082: * endpoint.
083: * <p>
084: * If the {@link Binding} for this <code>bindingProvider</code> is
085: * either SOAP1.1/HTTP or SOAP1.2/HTTP, then a
086: * <code>W3CEndpointReference</code> MUST be returned.
087: *
088: * @param referenceParameters Reference parameters to be associated with the
089: * returned <code>EndpointReference</code> instance.
090: * @return EndpointReference of the endpoint associated with this
091: * <code>WebServiceContext</code>.
092: * If the returned <code>EndpointReference</code> is of type
093: * <code>W3CEndpointReference</code> then it MUST contain the
094: * the specified <code>referenceParameters</code>.
095: *
096: * @throws IllegalStateException This exception is thrown
097: * if the method is called while no request is
098: * being serviced.
099: *
100: * @see W3CEndpointReference
101: *
102: * @since JAX-WS 2.1
103: */
104: public EndpointReference getEndpointReference(
105: Element... referenceParameters);
106:
107: /**
108: * Returns the <code>EndpointReference</code> associated with
109: * this endpoint.
110: *
111: * @param clazz The type of <code>EndpointReference</code> that
112: * MUST be returned.
113: * @param referenceParameters Reference parameters to be associated with the
114: * returned <code>EndpointReference</code> instance.
115: * @return EndpointReference of type <code>clazz</code> of the endpoint
116: * associated with this <code>WebServiceContext</code> instance.
117: * If the returned <code>EndpointReference</code> is of type
118: * <code>W3CEndpointReference</code> then it MUST contain the
119: * the specified <code>referenceParameters</code>.
120: *
121: * @throws IllegalStateException This exception is thrown
122: * if the method is called while no request is
123: * being serviced.
124: * @throws WebServiceException If the <code>clazz</code> type of
125: * <code>EndpointReference</code> is not supported.
126: *
127: * @since JAX-WS 2.1
128: **/
129: public <T extends EndpointReference> T getEndpointReference(
130: Class<T> clazz, Element... referenceParameters);
131: }
|