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> </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 and
there is also a browser based demo
at 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> </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 and
systests/jaxws/src/test/java/org/apache/cxf/systest/jaxws/websocket. There is
also a browser based demo
at distribution/src/main/release/samples/jax_rs/websocket.</li><li> 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> </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;"> </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> </p><h3
id="WebSocket-Furtherdetails">Further details</h3><ul style="list-style-type:
square;"><li> the text encoding is fixed when text is sent as
bytes. <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> </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> </p><p> </p><p> </p></div>
+</div></div><p> </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;"> </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> </p><h3
id="WebSocket-Furtherdetails">Further details</h3><ul style="list-style-type:
square;"><li> the text encoding is fixed when text is sent as
bytes. <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. </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> </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> </p><p> </p><p> </p></div>
</div>
<!-- Content -->
</td>
