cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r918739 - in /websites/production/cxf/content: cache/docs.pageCache docs/websocket.html
Date Fri, 08 Aug 2014 14:46:56 GMT
Author: buildbot
Date: Fri Aug  8 14:46:56 2014
New Revision: 918739

Log:
Production update by buildbot for cxf

Modified:
    websites/production/cxf/content/cache/docs.pageCache
    websites/production/cxf/content/docs/websocket.html

Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.

Modified: websites/production/cxf/content/docs/websocket.html
==============================================================================
--- websites/production/cxf/content/docs/websocket.html (original)
+++ websites/production/cxf/content/docs/websocket.html Fri Aug  8 14:46:56 2014
@@ -122,7 +122,7 @@ Apache CXF -- WebSocket
                             <p>This page summarizes the current status of WebSocket
support in CXF. This feature is currently only available in trunk (CXF 3.0.0-SNAPSHOT).</p>
                     </div>
     </div>
-<h1 id="WebSocket-UsingtheWebSockettransport">Using the WebSocket transport</h1><p>The
intention for providing the WebSocket transport in CXF is to turn CXF endpoint services capable
of reading or writing data over the socket that is connected to the client. For example, a
JAXRS service using the WebSocket transport can continuously push or write data (e.g., status
changes, events, etc) to the client once the client establishes a WebSocket connection to
the service.</p><p>&#160;</p><h1 id="WebSocket-CurrentStatus">Current
Status</h1><h3 id="WebSocket-Shortsummary">Short summary</h3><ul style="list-style-type:
square;"><li>the code resides in rt/transport/http-websocket and it enables cxf services
to be invoked over websockets.</li><li>it supports both the embedded mode and
the servlet container mode. The former can be used in the standalone setup that uses an embedded
jetty server and the latter can be used in the container setup that uses the servlet container
provided by the conta
 iner.</li><li>some test cases are located in systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/websocket&#160;and
there is also a browser based demo at&#160;distribution/src/main/release/samples/jax_rs/websocket.</li><li>it
requires several additional libraries to enable this feature depending on the usage. Concretely,
it will require jetty-websocket for the embedded standalone mode (i.e., the endpoint is given
with the host and port part as in address="<a shape="rect" href="ws://hostport" rel="nofollow">ws://host:port/path</a>").
For the servlet mode (i.e., the endpoint is given using a relative path (i.e., address="/path"),
it will either require jetty-websocket to use jetty or require atmosphere-runtime and a specific
websocket implementation such as jetty-websocket or tomcat-websocket to use that specific
container.</li></ul><h3 id="WebSocket-UsagePatterns">Usage Patterns</h3><p><span
style="font-size: 14.0px;line-height: 1.4285715;">We have the following message exchang
 e patterns to use this websocket transport for cxf service invocation.</span></p><ol><li>the
client opens a websocket to some URL hosting a cxf service (e.g. <a shape="rect" href="ws://localhost:8080/cxf/myapp/books"
rel="nofollow">ws://localhost:8080/cxf/myapp/books</a>)</li><li><p><span
style="line-height: 1.4285715;">the client can subsequently invoke an operation provided
by this service (e.g., the book order operation at /myapp/books/order/123) by sending a request
message that a simplified HTTP request message.</span><br clear="none"><span
style="line-height: 1.4285715;"><br clear="none"></span></p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>Request Syntax</b></div><div class="codeContent panelContent
pdl">
+<h1 id="WebSocket-UsingtheWebSockettransport">Using the WebSocket transport</h1><p>The
intention for providing the WebSocket transport in CXF is to turn CXF endpoint services capable
of reading or writing data over the socket that is connected to the client. For example, a
JAXRS service using the WebSocket transport can continuously push or write data (e.g., status
changes, events, etc) to the client once the client establishes a WebSocket connection to
the service.</p><p>&#160;</p><h1 id="WebSocket-CurrentStatus">Current
Status</h1><h3 id="WebSocket-Shortsummary">Short summary</h3><ul style="list-style-type:
square;"><li>The code resides in rt/transport/http-websocket and it enables cxf services
to be invoked over websockets.</li><li>It supports both the embedded mode and
the servlet container mode. The former can be used in the standalone setup that uses an embedded
jetty server and the latter can be used in the container setup that uses the servlet container
provided by the conta
 iner.</li><li>Some test cases are located in systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/websocket&#160;and
systests/jaxws/src/test/java/org/apache/cxf/systest/jaxws/websocket. There is also a browser
based demo at&#160;distribution/src/main/release/samples/jax_rs/websocket.</li><li>&#160;Several
additional libraries are required to enable this feature depending on the usage. Concretely,
jetty-websocket is required for the embedded standalone mode (i.e., the endpoint is given
with the host and port part as in address="<a shape="rect" href="ws://hostport" rel="nofollow">ws://host:port/path</a>").
For the servlet mode (i.e., the endpoint is given using a relative path (i.e., address="/path"),
it requires either jetty-websocket to use jetty or atmosphere-runtime and a specific websocket
implementation such as jetty-websocket or tomcat-websocket to use that specific container's
websocket capability.</li></ul><h3 id="WebSocket-UsagePatterns">Usage Patterns</h3><p><span
styl
 e="font-size: 14.0px;line-height: 1.4285715;">We have the following message exchange patterns
to use this websocket transport for cxf service invocation.</span></p><ol><li>the
client opens a websocket to some URL hosting a cxf service (e.g. <a shape="rect" href="ws://localhost:8080/cxf/myapp/books"
rel="nofollow">ws://localhost:8080/cxf/myapp/books</a>)</li><li><p><span
style="line-height: 1.4285715;">the client can subsequently invoke an operation provided
by this service (e.g., the book order operation at /myapp/books/order/123) by sending a request
message that a simplified HTTP request message.</span><br clear="none"><span
style="line-height: 1.4285715;"><br clear="none"></span></p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>Request Syntax</b></div><div class="codeContent panelContent
pdl">
 <script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[Request
= Request-Line CRLF
              *(( header ) CRLF)
              CRLF
@@ -139,7 +139,7 @@ Request-Line  = Method SP Request-URI
 
 Status-Line = Status-Code
  ]]></script>
-</div></div><p>&#160;</p><p>Status-Code uses the HTTP status
codes.</p><br clear="none"><span style="line-height: 1.4285715;"><br
clear="none"></span></li><li><span style="line-height: 1.4285715;">&#160;</span>the
service can subsequently push further data using jaxrs StreamingOuptut or writing to the injected
servlet response's output stream. In this case, the message is simply returned to the client
without Status-Line and may or may not include headers.</li></ol><p>(Note:
need for discussing the above binding syntax).</p><p>&#160;</p><h3
id="WebSocket-Furtherdetails">Further details</h3><ul style="list-style-type:
square;"><li>&#160;the text encoding is fixed when text is sent as bytes.&#160;<span
style="line-height: 1.4285715;">Currently, when the text is sent in the binary mode, its
encoding is assumed to be utf-8.</span></li></ul><ul style="list-style-type:
square;"><li>if the client and the service want to explicitly exchange a sequence
of requests and responses, they are res
 ponsible in passing some id and ref-id in the exchanged message's headers so that each response
can be correlated to its request.</li></ul><h3 id="WebSocket-Openquestions">Open
questions</h3><ul style="list-style-type: square;"><li>the content-length
header is not used to determine the length of the message, as the message end can be determined
for a websocket message using other means (i.e., either its length when used a block-mode
or the fragment's indicator). So it is not clear whether we can filter out the content-length.</li><li>the
referencing mechanism is needed for correlating requests and their responses that are sent
back asynchronously or even continuously. This means we need to add something like message-id
in the request and message-ref-id in the response headers.</li><li>the protocol
format needs to be clarified (see above regarding the protocol format used currently) and
possibly to several variations binding variations.</li></ul><h3 id="WebSocket-TODOsofimmediateinte
 rests">TODOs of immediate interests</h3><p>&#160;</p><ul><li>allow
setting a buffer size to switch to the fragment transfer mode over websockets</li></ul><p>Currently,
what is written over out.write(byte[] b, int offset, int length) will be written as a websocket
message (e.g., triggering a single onMessage event to the client). We should allow sending
back a sequence of fragments and terminates the transmission at the flushing step (i.e., out.flush()
or of some sort).</p><ul><li>native string message transfer</li></ul><p>Currently,
strings are converted into utf-8 bytes and sent using the byte transfer mode of websocket.
We could add the native string/text transfer as websocket supports it. However, this should
be allowed only when the entity body is absent or of string/text.</p><ul><li>add
message-ref-id part 1</li></ul><p>see above "open question".</p><ul><li>add
message-ref-id part 2</li></ul><p>we might want to link this mechanism to
cxf's current decoupled request/response cor
 relation.</p><ul><li>add some browser based sample client applications</li></ul><p>we
can add some js examples or update the logbrowser sample. There is a browser based demo in
the samples collection (see above). This demo uses the current default binding which is not
javascript friendly. To support browser based applications, we need different bindings.</p><h3
id="WebSocket-TODOsoffutureinterests"><br clear="none">TODOs of future interests</h3><ul><li>supporting
a direct output stream connection from the client application to the service application.
Currently, from the service application to the client, a direct output stream can be kept
open after the initial call from the client to the service takes place. Thus, the service
can continue to push data directly to the client over this output stream. Similarly, it would
be interesting to establish a direct output stream from the client to the service so that
the client can continue to push data directly to the service.</li><li>use a
  websocket instead of a decoupled endpoint to receive decoupled responses</li></ul><p>&#160;</p><p>&#160;</p><p>&#160;</p></div>
+</div></div><p>&#160;</p><p>Status-Code uses the HTTP status
codes.</p><br clear="none"><span style="line-height: 1.4285715;"><br
clear="none"></span></li><li><span style="line-height: 1.4285715;">&#160;</span>the
service can subsequently push further data using jaxrs StreamingOuptut or writing to the injected
servlet response's output stream. In this case, the message is simply returned to the client
without Status-Line and may or may not include headers.</li></ol><p>(Note:
need for discussing the above binding syntax).</p><p>&#160;</p><h3
id="WebSocket-Furtherdetails">Further details</h3><ul style="list-style-type:
square;"><li>&#160;the text encoding is fixed when text is sent as bytes.&#160;<span
style="line-height: 1.4285715;">Currently, when the text is sent in the binary mode, its
encoding is assumed to be utf-8.</span></li></ul><ul style="list-style-type:
square;"><li>if the client and the service want to explicitly exchange a sequence
of requests and responses, they are res
 ponsible in passing some id and ref-id in the exchanged message's headers so that each response
can be correlated to its request.</li><li>for correlating requests and their responses
that are send back asynchronously, the request message may include the RequestId header and
the corresponding response may set this value in its ResponseId header.</li><li>asynchronous
web service calls that are performed using a decoupled endpoint using the http transport can
be performed using the websocket transport without using a decoupled endpoint.&#160;</li></ul><h3
id="WebSocket-Openquestions">Open questions</h3><ul style="list-style-type: square;"><li>the
content-length header is not used to determine the length of the message, as the message end
can be determined for a websocket message using other means (i.e., either its length when
used a block-mode or the fragment's indicator). So it is not clear whether we can filter out
the content-length.</li><li>the protocol format needs to be clarified
  (see above regarding the protocol format used currently) and possibly to several variations
binding variations.</li></ul><h3 id="WebSocket-TODOsofimmediateinterests">TODOs
of immediate interests</h3><p>&#160;</p><ul><li>allow setting
a buffer size to switch to the fragment transfer mode over websockets</li></ul><p>Currently,
what is written over out.write(byte[] b, int offset, int length) will be written as a websocket
message (e.g., triggering a single onMessage event to the client). We should allow sending
back a sequence of fragments and terminates the transmission at the flushing step (i.e., out.flush()
or of some sort).</p><ul><li>native string message transfer</li></ul><p>Currently,
strings are converted into utf-8 bytes and sent using the byte transfer mode of websocket.
We could add the native string/text transfer as websocket supports it. However, this should
be allowed only when the entity body is absent or of string/text.</p><ul><li>add
more browser based sample client a
 pplications</li></ul><p>we can update the logbrowser sample. There is a
browser based demo in the samples collection (see above). This demo uses the current default
binding which is not javascript friendly. To support browser based applications, we need different
bindings.</p><h3 id="WebSocket-TODOsoffutureinterests"><br clear="none">TODOs
of future interests</h3><ul><li>supporting a direct output stream connection
from the client application to the service application. Currently, from the service application
to the client, a direct output stream can be kept open after the initial call from the client
to the service takes place. Thus, the service can continue to push data directly to the client
over this output stream. Similarly, it would be interesting to establish a direct output stream
from the client to the service so that the client can continue to push data directly to the
service.</li></ul><p>&#160;</p><p>&#160;</p><p>&#160;</p></div>
            </div>
            <!-- Content -->
          </td>



Mime
View raw message