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  */
  25 
  26 /**
  27  * <h1>JAX-WS 2.0.1 Server Runtime</h1>
  28  * <P>This document describes the architecture of server side
  29  * JAX-WS 2.0.1 runtime. </p>
  30  *
  31  * <h3>JAX-WS 2.0.1 Server Runtime Sequence Diagram</h3>
  32 
  33   * <img src='../../../../../jaxws/basic-server.seq.png'>
  34 
  35  *
  36  *
  37  * <H3>Message Flow</H3>
  38  * <P>A Web Service invocation starts with either the
  39  * {@link com.sun.xml.internal.ws.transport.http.servlet.WSServletDelegate WSServletDelegate}
  40  * or the {@link com.sun.xml.internal.ws.transport.http.server.ServerConnectionImpl ServerConnectionImpl}.
  41  * Both of these classes find the appropriate {@link com.sun.xml.internal.ws.server.RuntimeEndpointInfo RuntimeEndpointInfo}
  42  * and invokes the {@link com.sun.xml.internal.ws.server.Tie#handle(com.sun.xml.internal.ws.api.server.WSConnection,
  43  * com.sun.xml.internal.ws.spi.runtime.RuntimeEndpointInfo) Tie.handle}
  44  * method. This method first creates a {@link com.sun.pept.ept.MessageInfo MessageInfo}
  45  * used to gather inforrmation about the message to be received. A
  46  * {@link com.sun.xml.internal.ws.server.RuntimeContext RuntimeContext}
  47  * is then created with the MessageInfo and the {@link com.sun.xml.internal.ws.api.model.SEIModel RuntimeModel}
  48  * retrieved from the RuntimeEndpointInfo. The RuntimeContext is then
  49  * stored in the MessageInfo. The {@link com.sun.pept.ept.EPTFactory EPTFactory}
  50  * is retrieved from the {@link com.sun.xml.internal.ws.server.EPTFactoryFactoryBase EPTFactoryFactoryBase}
  51  * and also placed in the MessagInfo. A {@link com.sun.pept.protocol.MessageDispatcher MessageDispatcher}
  52  * is then created and the receive method is invoked. There will be two
  53  * types of MessageDispatchers for JAX-WS 2.0.1, SOAPMessageDispatcher
  54  * (one for client and one for the server) and an XMLMessageDispatcher
  55  * (one for the client and one for the server).</P>
  56  * <P>The MessageDispatcher.receive method orchestrates the receiving of
  57  * a Message. The SOAPMessageDispatcher first converts the MessageInfo
  58  * to a SOAPMessage. The SOAPMessageDispatcher then does mustUnderstand
  59  * processing followed by an invocation of any handlers. The SOAPMessage
  60  * is then converted to an InternalMessage and stored in the
  61  * MessageInfo. The converting of the SOAPMessage to an InternalMessage
  62  * is done using the decoder retrieved from the EPTFactory that is
  63  * contained in the MessageInfo. Once the SOAPMessage has been converted
  64  * to an InternalMessage the endpoint implementation is invoked via
  65  * reflection from the Method stored in the MessageInfo. The return
  66  * value of the method call is then stored in the InternalMessage. An
  67  * internalMessage is then created from the MessageInfo. The SOAPEncoder
  68  * is retrieved from the EPTFactory stored in the MessageInfo. The
  69  * SOAPEncoder.toSOAPMessage is then invoked to create a SOAPMessage
  70  * from the InternalMessage. A WSConnection is then retrieved from the
  71  * MessageInfo and the SOAPMessage is returned over that WSConnection.</P>
  72  * <P><BR>
  73  * </P>
  74  * <H3>External Interactions</H3>
  75  * <H4>SAAJ API</H4>
  76  * <UL>
  77  *      <LI><P>JAX-WS creates SAAJ javax.xml.soap.SOAPMessage
  78  *      from the HttpServletRequest.
  79  *      At present, JAX-WS reads all the bytes from the request stream and
  80  *      then creates SOAPMessage along with the HTTP headers.</P>
  81  * </UL>
  82  * <P>javax.xml.soap.MessageFactory(binding).createMessage(MimeHeaders, InputStream)</P>
  83  * <UL>
  84  *      <LI><P>SOAPMessage parses the content from the stream including MIME
  85  *      data</P>
  86  *      <LI><P>com.sun.xml.internal.ws.server.SOAPMessageDispatcher::checkHeadersPeekBody()</P>
  87  *      <P>SOAPMessage.getSOAPHeader() is used for mustUnderstand processing
  88  *      of headers. It further uses
  89  *      javax.xml.soap.SOAPHeader.examineMustUnderstandHeaderElements(role)</P>
  90  *      <P>SOAPMessage.getSOAPBody().getFistChild() is used for guessing the
  91  *      MEP of the request</P>
  92  *      <LI><P>com.sun.xml.internal.ws.handler.HandlerChainCaller:insertFaultMessage()</P>
  93  *      <P>SOAPMessage.getSOAPPart().getEnvelope() and some other SAAJ calls
  94  *      are made to create a fault in the SOAPMessage</P>
  95  *      <LI><P>com.sun.xml.internal.ws.handler.LogicalMessageImpl::getPayload()
  96  *      interacts with SAAJ to get body from SOAPMessage</P>
  97  *      <LI><P>com.sun.xml.internal.ws.encoding.soap.SOAPEncoder.toSOAPMessage(com.sun.xml.internal.ws.encoding.soap.internal.InternalMessage,
  98  *      SOAPMessage). There is a scenario where there is SOAPMessage and a
  99  *      logical handler sets payload as Source. To write to the stream,
 100  *      SOAPMessage.writeTo() is used but before that the body needs to be
 101  *      updated with logical handler' Source. Need to verify if this
 102  *      scenario is still happening since Handler.close() is changed to take
 103  *      MessageContext.</P>
 104  *      <LI><P>com.sun.xml.internal.ws.handlerSOAPMessageContextImpl.getHeaders()
 105  *      uses SAAJ API to get headers.</P>
 106  *      <LI><P>SOAPMessage.writeTo() is used to write response. At present,
 107  *      it writes into byte[] and this byte[] is written to
 108  *      HttpServletResponse.</P>
 109  * </UL>
 110  * <H4>JAXB API</H4>
 111  * <P>JAX-WS RI uses the JAXB API to marshall/unmarshall user created
 112  * JAXB objects with user created {@link javax.xml.bind.JAXBContext JAXBContext}.
 113  * Handler, Dispatch in JAX-WS API provide ways for the user to specify his/her own
 114  * JAXBContext. {@link com.sun.xml.internal.ws.encoding.jaxb.JAXBTypeSerializer JAXBTypeSerializer} class uses all these methods.</P>
 115  * <UL>
 116  *      <LI><p>{@link javax.xml.bind.Marshaller#marshal(Object,XMLStreamWriter) Marshaller.marshal(Object,XMLStreamWriter)}</p>
 117  *      <LI><P>{@link javax.xml.bind.Marshaller#marshal(Object,Result) Marshaller.marshal(Object, DomResult)}</P>
 118  *      <LI><P>{@link javax.xml.bind.Unmarshaller#unmarshal(XMLStreamReader) Object Unmarshaller.unmarshal(XMLStreamReader)}</P>
 119  *      <LI><P>{@link javax.xml.bind.Unmarshaller#unmarshal(Source) Object Unmarshaller.unmarshal(Source)}</P>
 120  * </UL>
 121  * The following two JAXB classes are implemented by JAX-WS to enable/implement MTOM and XOP
 122  * <UL>
 123  *      <LI><P>{@link javax.xml.bind.attachment.AttachmentMarshaller AttachmentMarshaller}</P>
 124  *      <LI><P>{@link javax.xml.bind.attachment.AttachmentUnmarshaller AttachmentUnmarshaller}</P>
 125  * </UL>
 126  * <H4>JAXB Runtime-API (private contract)</H4>
 127  * <P>JAX-WS RI uses these private API for serialization/deserialization
 128  * purposes. This private API is used to serialize/deserialize method
 129  * parameters at the time of JAXBTypeSerializer class uses all
 130  * these methods.</P>
 131  * <UL>
 132  *      <LI><P>{@link com.sun.xml.internal.bind.api.Bridge#marshal(BridgeContext, Object, XMLStreamWriter) Bridge.marshal(BridgeContext, Object, XMLStreamWriter)}</P>
 133  *      <LI><P>{@link com.sun.xml.internal.bind.api.Bridge#marshal(BridgeContext, Object, Node) Bridge.marshal(BridgeContext, Object, Node)}</P>
 134  *      <LI><P>{@link com.sun.xml.internal.bind.api.Bridge#unmarshal(BridgeContext, XMLStreamReader) Object Bridge.unmarshal(BridgeContext, XMLStreamReader)}</P>
 135  * </UL>
 136  *

 137  **/
 138 package com.sun.xml.internal.ws.server;
 139 
 140 import com.sun.xml.internal.bind.api.BridgeContext;
 141 
 142 import javax.xml.stream.XMLStreamReader;
 143 import javax.xml.stream.XMLStreamWriter;
 144 import javax.xml.transform.Source;
 145 import javax.xml.transform.Result;
 146 
 147 import org.w3c.dom.Node;
--- EOF ---