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

java.lang.Object
  java.io.OutputStream
      org.rhq.enterprise.communications.command.client.RemoteOutputStream

All Implemented Interfaces:

Closeable, Flushable, Serializable

public class RemoteOutputStream
extends OutputStream
implements Serializable

This is an output stream that actually sends the stream data to a remote server. Note that this extends OutputStream 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 output 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 write the output 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 output stream was registered. Note that, for convienence, the constructor RemoteOutputStream(OutputStream, ServiceContainer) is provided to both add the output stream to the server-side services container and instantiate this object with the appropriate stream ID. This RemoteOutputStream 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 writing 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" OutputStream. Note that remote output 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

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

RemoteOutputStream(OutputStream stream, ServiceContainer server)
Creates a new RemoteOutputStream object.

Method Summary

void	close()
void	flush()
String	getServerEndpoint() Returns the endpoint of the server where the remote output stream is actually located.
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 output stream object will use to send the remote invocation requests.
String	toString()
void	write(byte[] b)
void	write(byte[] b, int off, int len)
void	write(int b)

Methods inherited from class java.lang.Object

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

Constructor Detail

RemoteOutputStream

public RemoteOutputStream(OutputStream stream,
                          ServiceContainer server)
                   throws Exception

Creates a new RemoteOutputStream object. This constructor is the same as RemoteOutputStream(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.addRemoteOutputStream(OutputStream)).

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 output stream to the given container

RemoteOutputStream

public RemoteOutputStream(Long id,
                          ServiceContainer server)

Creates a new RemoteOutputStream object. Because the remote output 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 output 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 output stream is actually located. Its this server that must be the endpoint of any given client sender.

Returns:

the output stream's server endpoint

setClientCommandSender

public void setClientCommandSender(ClientCommandSender sender)

Sets the sender that this output 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 output 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()

close

public void close()
           throws IOException

Specified by:

close in interface Closeable

Overrides:

close in class OutputStream

Throws:

IOException

flush

public void flush()
           throws IOException

Specified by:

flush in interface Flushable

Overrides:

flush in class OutputStream

Throws:

IOException

write

public void write(int b)
           throws IOException

Specified by:

write in class OutputStream

Throws:

IOException

write

public void write(byte[] b)
           throws IOException

Overrides:

write in class OutputStream

Throws:

IOException

write

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

Overrides:

write in class OutputStream

Throws:

IOException

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 output stream actually encountered a problem