Fork me on GitHub


Where can I find sample code?

For a variety of code examples see the snippets in the rmiio overview javadocs as well as the working examples in the test directory.


Why am I getting an IOException with the message "Corrupt GZIP trailer"?

This is most likely due to a bug in the JDK. Files greater than 2GB in size spuriously cause this exception to be generated. See Sun bug 5092263. This was finally fixed in JDK 1.5.0_08, 1.4.2_12, and should be fixed in JDK 1.6


What version of the JDK does this require?

Requires JDK 1.5 or higher. However, the only new feature used is generics, so a simple filter on the source code (removing all generics constructs) should make the source JDK 1.4 compatible (most likely, although I have not personally tested this, so YMMV). One option here may be the JBoss Retro project.


Why am I getting a NoSuchObjectException (or similar RMI exception)?

This most likely means that the RemoteStream client is trying to use a reference to a RemoteStreamServer which has not been serialized (in other words, the client is trying to use a local handle to the server). RMI uses a distributed garbage-collection (DGC) strategy to keep server references alive while clients have RemoteStub instances that reference them. If the RemoteStub is not been serialized/deserialized before usage, it does not trigger the DGC code, so the server instance gets cleaned up soon after creation. Basically, you should never use a RemoteStreamServer reference locally (you should just use a regular Input/OutputStream in this case).

In certain application servers, not using stateful session beans can also cause this exception. For more information, see the EJB section of the Usage Notes.


Why am I getting a NotSerializableException when trying to send a remote stream?

This happens when you try to send the RemoteStreamServer instance as the serializable value instead of the RemoteStub object returned from the RemoteStreamServer.export() method call. You must export your RemoteStreamServer in order to use it remotely.


How can I fix firewall issues?

This is a big question. First, make sure you have dealt with the basic firewall related issues for RMI.

Next, assuming you have normal RMI working from client to server, you may need to reverse the RMIIO client/server roles (as they may be the reverse of the conceptual client/server roles). This happens, for example, when you send a RemoteInputStream from the client to the server (because the client acts as the server for the RMIIO stream). You may be able to fix any firewall related problems by using a RemoteOutputStream returned from the server instead of a RemoteInputStream passed from the client (so the client pushes data to the server instead of the server pulling it from the client). A similar solution can be applied to a RemoteOutputStream (see the sequence diagrams for more details).

Additionally, you may need to control the port that the RMIIO server objects are exported on. This can be done setting the com.healthmarketscience.rmiio.exporter.port system property to the desired port, assuming you are using the default RemoteStreamExporter.

If all else fails, and you are only attempting to use a RemoteInputStream, then the DirectRemoteInputStream may be the answer to your problems (as of 2.0.1 release). This class is an RMI-only RemoteInputStream implementation which actually embeds the stream data directly into the ObjectOutputStream. It is not recommended for normal use, but can be a last ditch tool if nothing else seems to work. Please read the javadocs carefully in order to understand the pros and cons of the implementation before using the class.

Note, this answer is still a work in progress.


With which Application Servers/Frameworks has this been used?

JBoss (4.0.x):
Used extensively as-is on JBoss.
Needs a custom RemoteStreamExporter in order to work with WebLogic's custom RMI implementation.
Glassfish uses RMI-IIOP (Corba) for the transport layer, thus a a custom RemoteStreamExporter using PortableRemoteObject is necessary. This should work for any Application Server using RMI-IIOP. And, since glassfish supports dynamic stub generation, no additional work is necessary. For situations where stubs need to be statically generated, the RMI-IIOP Programmer's Guide is a good place to start.
Additionally, glassfish seems to tie the lifecyle of the exported RemoteStreams to the lifecycle of the EJB which created it, and therefore requires the use of stateful session beans in order for the streams to work correctly. EJB section of the Usage Notes for more details.
Spring (2.5)
Works as-is with the RMI invoker. To use with the HttpInvoker, you need to setup a singleton service which manages all the RMIIO servers. See this forum thread for details.


Why do I get a NoClassDefFoundError?

Probably because you're missing a jar that RMIIO depends on from your classpath. Take a look at the dependencies list. The "compile" and "runtime" dependencies are necessary for using RMIIO in your application. One great place to track down these dependencies is in the Ibiblio Maven Repository.


Where can I find more information?

More FAQ-like answers can be found in the Usage Notes.


Who is Health Market Science?

HMS is a small company located in suburban Philadelphia. Using proprietary matching and consolidation software, HMS scientifically manufactures the most comprehensive and accurate healthcare data sets in the market today.