org.rhq.enterprise.communications.command.client
Class RemoteInputStream

java.lang.Object
  java.io.InputStream
      org.rhq.enterprise.communications.command.client.RemoteInputStream

All Implemented Interfaces:

Closeable, Serializable

public class RemoteInputStream
extends InputStream
implements Serializable

This is an input stream that actually pulls down the stream data from a remote server. Note that this extends InputStream so it can be used as any normal stream object; however, all methods are overridden to actually delegate the methods to the remote stream.

In order to be able to use this object, you should understand how input streams are remoted. First, an input stream must be assigned a server-side service component. At that point, your server is ready to begin accepting remote commands to read the input stream. That's where this object comes in. You instantiate this object by giving its constructor the ID of the stream and the service container where that input stream was registered. Note that, for convienence, the constructor RemoteInputStream(InputStream, ServiceContainer) is provided to both add the input stream to the server-side services container and instantiate this object with the appropriate stream ID. This RemoteInputStream object can then be passed to a remote client in some way (typically by serializing it as part of a Command). The remote endpoint must then tell this object (after its been deserialized) which client sender to use when communicating back to the server (which it needs to do when pulling the stream data). We need that remote endpoint to give this object a sender because its the remote endpoint's job to configure that sender with things like its keystore and truststore locations (when transporting over SSL). In order to configure that client sender, the remote endpoint must create the sender such that it uses the server endpoint as its target. After the remote endpoint sets up its sender in this object, it is free to operate on this object as if it were a "normal" InputStream. Note that remote input streams should be closed in order to clean up server-side resources in a timely manner.

Author:

John Mazzitelli

See Also:

Serialized Form

Constructor Summary

RemoteInputStream(InputStream stream, ServiceContainer server)
Creates a new RemoteInputStream object.

RemoteInputStream(Long id, ServiceContainer server)
Creates a new RemoteInputStream object.

Method Summary

int	available()
void	close()
String	getServerEndpoint() Returns the endpoint of the server where the remote input stream is actually located.
void	mark(int readlimit)
boolean	markSupported()
int	read()
int	read(byte[] b)
int	read(byte[] b, int off, int len)
void	reset()
protected Object	sendRequest(Method method, Object[] args) Builds the command to execute the method on the remote stream and submit the request.
void	setClientCommandSender(ClientCommandSender sender) Sets the sender that this input stream object will use to send the remote invocation requests.
long	skip(long n)
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RemoteInputStream

public RemoteInputStream(InputStream stream,
                         ServiceContainer server)
                  throws Exception

Creates a new RemoteInputStream object. This constructor is the same as RemoteInputStream(Long, ServiceContainer) but additionally adds the stream's server-side component that is required in order for the stream to be remotely accessible (see ServiceContainer.addRemoteInputStream(InputStream)).

Parameters:

stream - the stream to remote

server - the server-side container that is responsible for remoting the stream

Throws:

Exception - if failed to add the remote input stream to the given container

RemoteInputStream

public RemoteInputStream(Long id,
                         ServiceContainer server)

Creates a new RemoteInputStream object. Because the remote input stream needs a server-side component to be able to serve up the stream data to remote endpoints, the given server is needed so this object knows that server component's endpoint.

Parameters:

id - identifies the stream this object will remotely access

server - the server where the input stream service is registered and awaiting for the remote endpoint to begin sending it requests

Method Detail

getServerEndpoint

public String getServerEndpoint()

Returns the endpoint of the server where the remote input stream is actually located. Its this server that must be the endpoint of any given client sender.

Returns:

the input stream's server endpoint

setClientCommandSender

public void setClientCommandSender(ClientCommandSender sender)

Sets the sender that this input stream object will use to send the remote invocation requests. Note that the target endpoint of that client sender must be the server identified by getServerEndpoint(). Therefore, before a caller calls this method, it must ensure that any sender it passes in has been configured to send its messages to the input stream's server endpoint.

Parameters:

sender - object used to send the requests to the remote server

toString

public String toString()

Overrides:

toString in class Object

See Also:

Object.toString()

available

public int available()
              throws IOException

Overrides:

available in class InputStream

Throws:

IOException

See Also:

InputStream.available()

close

public void close()
           throws IOException

Specified by:

close in interface Closeable

Overrides:

close in class InputStream

Throws:

IOException

See Also:

InputStream.close()

mark

public void mark(int readlimit)

Overrides:

mark in class InputStream

See Also:

InputStream.mark(int)

markSupported

public boolean markSupported()

Overrides:

markSupported in class InputStream

See Also:

InputStream.markSupported()

read

public int read()
         throws IOException

Specified by:

read in class InputStream

Throws:

IOException

See Also:

InputStream.read()

read

public int read(byte[] b)
         throws IOException

Overrides:

read in class InputStream

Throws:

IOException

See Also:

InputStream.read(byte[])

read

public int read(byte[] b,
                int off,
                int len)
         throws IOException

Overrides:

read in class InputStream

Throws:

IOException

See Also:

InputStream.read(byte[], int, int)

reset

public void reset()
           throws IOException

Overrides:

reset in class InputStream

Throws:

IOException

See Also:

InputStream.reset()

skip

public long skip(long n)
          throws IOException

Overrides:

skip in class InputStream

Throws:

IOException

See Also:

InputStream.skip(long)

sendRequest

protected Object sendRequest(Method method,
                             Object[] args)
                      throws RemoteIOException

Builds the command to execute the method on the remote stream and submit the request.

Parameters:

method - the method to invoke on the remote stream

args - the arguments to pass to the invoked method on the remote stream

Returns:

the results of the invocation on the remote stream

Throws:

RemoteIOException - if either the sending of the request failed of the remote input stream actually encountered a problem