← Back to branch summary

~ubuntu-branches/ubuntu/raring/libjboss-remoting-java/raring

« back to all changes in this revision

Viewing changes to docs/guide/html/ch07.html

  • Committer: Package Import Robot
  • Author(s): Torsten Werner
  • Date: 2011-09-09 14:01:03 UTC
  • mfrom: (1.1.6 upstream)
  • Revision ID: package-import@ubuntu.com-20110909140103-hqokx61534tas9rg
Tags: 2.5.3.SP1-1
http://bugs.debian.org/628303
* Newer but not newest upstream release. Do not build samples.
* Change debian/watch to upstream's svn repo.
* Add patch to fix compile error caused by tomcat update.
  (Closes: #628303)
* Switch to source format 3.0.
* Switch to debhelper level 7.
* Remove useless Depends.
* Update Standards-Version: 3.9.2.
* Update README.source.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/guide/html/ch07.html
1
 
<html><head>
2
 
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
3
 
   <title>Chapter&nbsp;7.&nbsp;Sending streams</title><link rel="stylesheet" href="css/html.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="JBoss Remoting Guide"><link rel="up" href="index.html" title="JBoss Remoting Guide"><link rel="previous" href="chapter-adding-new-transport.html" title="Chapter&nbsp;6.&nbsp;Adding a New Transport"><link rel="next" href="ch08.html" title="Chapter&nbsp;8.&nbsp;Serialization"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter&nbsp;7.&nbsp;Sending streams</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="chapter-adding-new-transport.html">Prev</a>&nbsp;</td><th width="60%" align="center">&nbsp;</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ch08.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d0e6623"></a>Chapter&nbsp;7.&nbsp;Sending streams</h2></div></div><div></div></div><p>Remoting supports the sending of InputStreams. It is important to
4
 
    note that this feature DOES NOT copy the stream data directly from the
5
 
    client to the server, but is a true on demand stream. Although this is
6
 
    obviously slower than reading from a stream on the server that has been
7
 
    copied locally, it does allow for true streaming on the server. It also
8
 
    allows for better memory control by the user (versus the framework trying
9
 
    to copy a 3 Gig file into memory and getting out of memory errors).</p><p>Use of this new feature is simple. From the client side, there is a
10
 
    method in org.jboss.remoting.Client with the signature:</p><pre class="programlisting">public Object invoke(InputStream inputStream, Object param) throws Throwable
11
 
      </pre><p>So from the client side, would just call invoke as done in the past,
12
 
    and pass the InputStream and the payload as the parameters. An example of
13
 
    the code from the client side would be (this is taken directly from
14
 
    org.jboss.test.remoting.stream.StreamingTestClient):</p><pre class="programlisting">
15
 
         String param = "foobar";
16
 
         File testFile = new File(fileURL.getFile());
17
 
         ...
18
 
         Object ret = remotingClient.invoke(fileInput, param);
19
 
    </pre><p>From the server side, will need to implement
20
 
    <tt class="code">org.jboss.remoting.stream.StreamInvocationHandler</tt> instead of
21
 
    <tt class="code">org.jboss.remoting.ServerInvocationHandler</tt> .
22
 
    StreamInvocationHandler extends ServerInvocationHandler, with the addition
23
 
    of one new method:</p><pre class="programlisting">public Object handleStream(InputStream stream, Object param)</pre><p>The stream passed to this method can be called on just as any
24
 
    regular local stream. Under the covers, the InputStream passed is really
25
 
    proxy to the real input stream that exists in the client's VM. Subsequent
26
 
    calls to the passed stream will actually be converted to calls on the real
27
 
    stream on the client via this proxy. If the client makes an invocation on
28
 
    the server passing an InputStream as the parameter and the server handler
29
 
    does not implement StreamInvocationhandler, an exception will be thrown to
30
 
    the client caller.</p><p>If want to have more control over the stream server being created to
31
 
    send the stream data back to the caller, instead of letting remoting
32
 
    create it internally, can do this by creating a Connector to act as stream
33
 
    server and pass it when making Client invocation.</p><pre class="programlisting">public Object invoke(InputStream inputStream, Object param, Connector streamConnector) throws Throwable</pre><p>Note, the Connector passed must already have been started (else an
34
 
    exception will be thrown). The stream handler will then be added to the
35
 
    connector with the subystem 'stream'. The Connector passed will NOT be
36
 
    stopped when the stream is closed by the server's stream proxy (which
37
 
    happens automatically when remoting creates the stream server
38
 
    internally).</p><p>Can also call <tt class="methodname">invoke()</tt> method on client and
39
 
    pass the invoker locator
40
 
    would like to use and allow remoting to create the stream server using the
41
 
    specified locator.</p><pre class="programlisting">public Object invoke(InputStream inputStream, Object param, InvokerLocator streamServerLocator) throws Throwable </pre><p>In this case, the Connector created internally by remoting will be
42
 
    stopped when the stream is closed by the server's stream proxy.</p><p>It is VERY IMPORTANT that the StreamInvocationHandler implementation
43
 
    close the InputStream when it finishes reading, as will close the real
44
 
    stream that lives within the client VM.</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e6665"></a>7.1.&nbsp;Configuration</h2></div></div><div></div></div><p>By default, the stream server which runs within the client JVM
45
 
      uses the following values for its locator uri:</p><p>transport - socket</p><p>host - tries to first get local host name and if that fails, the
46
 
      local ip (if that fails, localhost).</p><p>port - 5405</p><p>Currently, the only way to override these settings is to set the
47
 
      following system properties (either via JVM arguments or via
48
 
      <tt class="code">System.setProperty()</tt> method):</p><p>remoting.stream.transport - sets the transport type (rmi, http,
49
 
      socket, etc.)</p><p>remoting.stream.host - host name or ip address to use</p><p>remoting.stream.port - the port to listen on</p><p>These properties are important because currently the only way for
50
 
      a target server to get the stream data from the stream server (running
51
 
      within the client JVM) is to have the server invoker make the invocation
52
 
      on a new connection back to the client (see issues below).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e6689"></a>7.2.&nbsp;Issues</h2></div></div><div></div></div><p>This is a first pass at the implementation and needs some work in
53
 
      regards to optimizations and configuration. In particular, there is a
54
 
      remoting server that is started to service requests from the stream
55
 
      proxy on the target server for data from the original stream. This
56
 
      raises an issue with the current transports, since the client will have
57
 
      to accept calls for the original stream on a different socket. This may
58
 
      be difficult when control over the client's environment (including
59
 
      firewalls) may not be available. A bi-directional transport, called
60
 
      multiplex, is being introduced as of 1.4.0 release which will allow
61
 
      calls from the server to go over the same socket connection established
62
 
      by the client to the server (JBREM-91). This will make communications
63
 
      back to client much simpler from this standpoint.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="chapter-adding-new-transport.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ch08.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;6.&nbsp;Adding a New Transport&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;8.&nbsp;Serialization</td></tr></table></div></body></html>
 
 
b'\\ No newline at end of file'