RemoteOutputStream (RHQ Enterprise Agent-Server Communications Layer 4.9.0 API)

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

All Implemented Interfaces:

Closeable, Flushable, Serializable, AutoCloseable
```
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

Constructors
Constructor and Description
`RemoteOutputStream(Long id, ServiceContainer server)` Creates a new `RemoteOutputStream` object.
`RemoteOutputStream(OutputStream stream, ServiceContainer server)` Creates a new `RemoteOutputStream` object.

Method Summary

Methods
Modifier and Type	Method and Description
`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
    
    Specified by:
    
    close in interface AutoCloseable
    
    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

Class RemoteOutputStream

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

RemoteOutputStream

RemoteOutputStream

Method Detail

getServerEndpoint

setClientCommandSender

toString

close

flush

write

write

write

sendRequest