[jboss-remoting-commits] JBoss Remoting SVN: r4698 - remoting2/branches/2.x/docs/guide/en.
jboss-remoting-commits at lists.jboss.org
jboss-remoting-commits at lists.jboss.org
Tue Nov 18 15:39:10 EST 2008
Author: ron.sigal at jboss.com
Date: 2008-11-18 15:39:09 -0500 (Tue, 18 Nov 2008)
New Revision: 4698
Modified:
remoting2/branches/2.x/docs/guide/en/chap7.xml
Log:
JBREM-1057: Replacing screwed up chapter.
Modified: remoting2/branches/2.x/docs/guide/en/chap7.xml
===================================================================
--- remoting2/branches/2.x/docs/guide/en/chap7.xml 2008-11-18 18:52:09 UTC (rev 4697)
+++ remoting2/branches/2.x/docs/guide/en/chap7.xml 2008-11-18 20:39:09 UTC (rev 4698)
@@ -1,44 +1,121 @@
- <chapter>
- <title>Serialization</title>
+<chapter>
+ <title>Sending streams</title>
- <para>Serialization - how it works within remoting: In general, remoting
- will rely on a factory to provide the serialization implementation, or
- <code>org.jboss.remoting.serialization.SerializationManager</code>, to be
- used when doing object serialization. This factory is
- <code>org.jboss.remoting.serialization.SerializationStreamFactory</code>
- and is a (as defined by its javadoc):</para>
+ <para>Remoting supports the sending of InputStreams. It is important to
+ note that this feature DOES NOT copy the stream data directly from the
+ client to the server, but is a true on demand stream. Although this is
+ obviously slower than reading from a stream on the server that has been
+ copied locally, it does allow for true streaming on the server. It also
+ allows for better memory control by the user (versus the framework trying
+ to copy a 3 Gig file into memory and getting out of memory errors).</para>
- <literallayout>factory is for defining the Object stream implemenations to be used along with creating those implemenations for use.
-The main function will be to return instance of ObjectOutput and ObjectInput. By default, the implementations will be
-java.io.ObjectOutputStream and java.io.ObjectInputStream.
-</literallayout>
+ <para>Use of this new feature is simple. From the client side, there is a
+ method in org.jboss.remoting.Client with the signature:</para>
- <para>Currently there are only two different types of serialization
- implementations; 'java' and 'jboss'. The 'java' type uses
- <code>org.jboss.remoting.serialization.impl.java.JavaSerializationManager</code>
- as the SerializationManager implementation and is backed by standard Java
- serialization provide by the JVM, which is the default. The 'jboss' type
- uses
- <code>org.jboss.remoting.serialization.impl.jboss.JBossSerializationManager</code>
- as the SerializationManager implementation and is backed by JBoss
- Serialization.</para>
+ <programlisting>public Object invoke(InputStream inputStream, Object param) throws Throwable
+ </programlisting>
- <para>JBoss Serialization is a new project under development to provide a
- more performant implementation of object serialization. It complies with
- java serialization standard with three exceptions:</para>
+ <para>So from the client side, would just call invoke as done in the past,
+ and pass the InputStream and the payload as the parameters. An example of
+ the code from the client side would be (this is taken directly from
+ org.jboss.test.remoting.stream.StreamingTestClient):</para>
- <para>- SerialUID not needed</para>
+ <programlisting>
+ String param = "foobar";
+ File testFile = new File(fileURL.getFile());
+ ...
+ Object ret = remotingClient.invoke(fileInput, param);
+ </programlisting>
- <para>- java.io.Serializable is not required</para>
+ <para>From the server side, will need to implement
+ <code>org.jboss.remoting.stream.StreamInvocationHandler</code> instead of
+ <code>org.jboss.remoting.ServerInvocationHandler</code> .
+ StreamInvocationHandler extends ServerInvocationHandler, with the addition
+ of one new method:</para>
- <para>- different protocol</para>
+ <programlisting>public Object handleStream(InputStream stream, Object param)</programlisting>
- <para>JBoss Serialization requires JDK 1.5</para>
+ <para>The stream passed to this method can be called on just as any
+ regular local stream. Under the covers, the InputStream passed is really
+ proxy to the real input stream that exists in the client's VM. Subsequent
+ calls to the passed stream will actually be converted to calls on the real
+ stream on the client via this proxy. If the client makes an invocation on
+ the server passing an InputStream as the parameter and the server handler
+ does not implement StreamInvocationhandler, an exception will be thrown to
+ the client caller.</para>
- <para></para>
+ <para>If want to have more control over the stream server being created to
+ send the stream data back to the caller, instead of letting remoting
+ create it internally, can do this by creating a Connector to act as stream
+ server and pass it when making Client invocation.</para>
- <para>It is possible to override the default SerializationManger
- implementation to be used by setting the system property 'SERIALIZATION'
- to the fully qualified name of the class to use (which will need to
- provide a void constructor).</para>
+ <programlisting>public Object invoke(InputStream inputStream, Object param, Connector streamConnector) throws Throwable</programlisting>
+
+ <para>Note, the Connector passed must already have been started (else an
+ exception will be thrown). The stream handler will then be added to the
+ connector with the subystem 'stream'. The Connector passed will NOT be
+ stopped when the stream is closed by the server's stream proxy (which
+ happens automatically when remoting creates the stream server
+ internally).</para>
+
+ <para>Can also call <methodname>invoke()</methodname> method on client and
+ pass the invoker locator
+ would like to use and allow remoting to create the stream server using the
+ specified locator.</para>
+
+ <programlisting>public Object invoke(InputStream inputStream, Object param, InvokerLocator streamServerLocator) throws Throwable </programlisting>
+
+ <para>In this case, the Connector created internally by remoting will be
+ stopped when the stream is closed by the server's stream proxy.</para>
+
+ <para>It is VERY IMPORTANT that the StreamInvocationHandler implementation
+ close the InputStream when it finishes reading, as will close the real
+ stream that lives within the client VM.</para>
+
+ <section>
+ <title>Configuration</title>
+
+ <para>By default, the stream server which runs within the client JVM
+ uses the following values for its locator uri:</para>
+
+ <para>transport - socket</para>
+
+ <para>host - tries to first get local host name and if that fails, the
+ local ip (if that fails, localhost).</para>
+
+ <para>port - 5405</para>
+
+ <para>Currently, the only way to override these settings is to set the
+ following system properties (either via JVM arguments or via
+ <code>System.setProperty()</code> method):</para>
+
+ <para>remoting.stream.transport - sets the transport type (rmi, http,
+ socket, etc.)</para>
+
+ <para>remoting.stream.host - host name or ip address to use</para>
+
+ <para>remoting.stream.port - the port to listen on</para>
+
+ <para>These properties are important because currently the only way for
+ a target server to get the stream data from the stream server (running
+ within the client JVM) is to have the server invoker make the invocation
+ on a new connection back to the client (see issues below).</para>
+ </section>
+
+ <section>
+ <title>Issues</title>
+
+ <para>This is a first pass at the implementation and needs some work in
+ regards to optimizations and configuration. In particular, there is a
+ remoting server that is started to service requests from the stream
+ proxy on the target server for data from the original stream. This
+ raises an issue with the current transports, since the client will have
+ to accept calls for the original stream on a different socket. This may
+ be difficult when control over the client's environment (including
+ firewalls) may not be available. A bi-directional transport, called
+ multiplex, is being introduced as of 1.4.0 release which will allow
+ calls from the server to go over the same socket connection established
+ by the client to the server (JBREM-91). This will make communications
+ back to client much simpler from this standpoint.</para>
+ </section>
</chapter>
\ No newline at end of file
More information about the jboss-remoting-commits
mailing list