cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r905468 - in /websites/production/cxf/content: cache/docs.pageCache docs/websocket.html
Date Tue, 08 Apr 2014 16:48:26 GMT
Author: buildbot
Date: Tue Apr  8 16:48:26 2014
New Revision: 905468

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 Tue Apr  8 16:48:26 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/.../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 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 ser
 vice (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
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">
 <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.</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></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>
            <!-- Content -->
          </td>



Mime
View raw message