public class Channel extends Object implements VirtualChannel
Channel is a mechanism for two JVMs to communicate over
bi-directional InputStream/OutputStream pair.
Channel represents an endpoint of the stream, and thus
two Channels are always used in a pair.
Communication is established as soon as two Channel instances
are created at the end fo the stream pair
until the stream is terminated via close().
The basic unit of remoting is an executable Callable object.
An application can create a Callable object, and execute it remotely
by using the call(Callable) method or callAsync(Callable) method.
In this sense, Channel is a mechanism to delegate/offload computation
to other JVMs and somewhat like an agent system. This is bit different from
remoting technologies like CORBA or web services, where the server exposes a
certain functionality that clients invoke.
Callable object, as well as the return value / exceptions,
are transported by using Java serialization. All the necessary class files
are also shipped over Channel on-demand, so there's no need to
pre-deploy such classes on both JVMs.
Channel builds its features in a layered model. Its higher-layer
features are built on top of its lower-layer features, and they
are called layer-0, layer-1, etc.
Command for more details. This is for higher-level features,
and not likely useful for applications directly.
Request for more details. This is for higher-level features,
and not likely useful for applications directly.
| Modifier and Type | Class and Description |
|---|---|
static class |
Channel.DummyRemotePipeWriterCallable |
static class |
Channel.Listener
Callback "interface" for changes in the state of
Channel. |
static class |
Channel.Mode
Communication mode.
|
| Modifier and Type | Field and Description |
|---|---|
AtomicInteger |
classLoadingCount
Total counts of remote classloading activities.
|
AtomicLong |
classLoadingTime
Total number of nanoseconds spent for remote class loading.
|
static int |
PIPE_WINDOW_SIZE |
Capability |
remoteCapability
Capability of the remote
Channel. |
AtomicInteger |
resourceLoadingCount
Total count of remote resource loading.
|
AtomicLong |
resourceLoadingTime
Total number of nanoseconds spent for remote resource loading.
|
| Constructor and Description |
|---|
Channel(String name,
ExecutorService exec,
Channel.Mode mode,
InputStream is,
OutputStream os) |
Channel(String name,
ExecutorService exec,
Channel.Mode mode,
InputStream is,
OutputStream os,
OutputStream header) |
Channel(String name,
ExecutorService exec,
Channel.Mode mode,
InputStream is,
OutputStream os,
OutputStream header,
boolean restricted)
Creates a new channel.
|
Channel(String name,
ExecutorService exec,
InputStream is,
OutputStream os) |
Channel(String name,
ExecutorService exec,
InputStream is,
OutputStream os,
OutputStream header) |
| Modifier and Type | Method and Description |
|---|---|
void |
addListener(Channel.Listener l)
Registers a new
Channel.Listener. |
<V,T extends Throwable> |
call(Callable<V,T> callable)
Makes a remote procedure call.
|
<V,T extends Throwable> |
callAsync(Callable<V,T> callable)
Makes an asynchronous remote procedure call.
|
void |
close()
Performs an orderly shut down of this channel (and the remote peer.)
|
ListeningPort |
createLocalToRemotePortForwarding(int recvPort,
String forwardHost,
int forwardPort)
Starts a local to remote port forwarding (the equivalent of "ssh -L").
|
ListeningPort |
createRemoteToLocalPortForwarding(int recvPort,
String forwardHost,
int forwardPort)
Starts a remote to local port forwarding (the equivalent of "ssh -R").
|
static Channel |
current()
This method can be invoked during the serialization/deserialization of
objects when they are transferred to the remote
Channel,
as well as during Callable.call() is invoked. |
void |
dumpExportTable(PrintWriter w)
Dumps the list of exported objects and their allocation traces to the given output.
|
<T> T |
export(Class<T> type,
T instance)
Exports an object for remoting to the other
Channel
by creating a remotable proxy. |
void |
flushPipe() |
long |
getLastHeard() |
<T> T |
getProperty(ChannelProperty<T> key) |
Object |
getProperty(Object key)
Gets the application specific property set by
setProperty(Object, Object). |
Object |
getRemoteProperty(Object key) |
void |
join()
Waits for this
Channel to be closed down. |
void |
join(long timeout)
Waits for this
Channel to be closed down, but only up the given milliseconds. |
boolean |
preloadJar(Callable<?,?> classLoaderRef,
Class... classesInJar)
Preloads jar files on the remote side.
|
boolean |
preloadJar(ClassLoader local,
Class... classesInJar) |
boolean |
preloadJar(ClassLoader local,
URL... jars) |
boolean |
removeListener(Channel.Listener l)
Removes a listener.
|
void |
resetPerformanceCounters()
Resets all the performance counters.
|
Object |
setProperty(Object key,
Object value)
Sets the property value on this side of the channel.
|
hudson.remoting.ExportTable.ExportList |
startExportRecording() |
protected void |
terminate(IOException e)
Aborts the connection in response to an error.
|
String |
toString() |
Object |
waitForProperty(Object key)
Works like
getProperty(Object) but wait until some value is set by someone. |
Object |
waitForRemoteProperty(Object key) |
public final AtomicLong classLoadingTime
public final AtomicInteger classLoadingCount
classLoadingTime.public final AtomicLong resourceLoadingTime
classLoadingTimepublic final AtomicInteger resourceLoadingCount
classLoadingCountpublic final Capability remoteCapability
Channel.public static final int PIPE_WINDOW_SIZE
public Channel(String name, ExecutorService exec, InputStream is, OutputStream os) throws IOException
IOExceptionpublic Channel(String name, ExecutorService exec, Channel.Mode mode, InputStream is, OutputStream os) throws IOException
IOExceptionpublic Channel(String name, ExecutorService exec, InputStream is, OutputStream os, OutputStream header) throws IOException
IOExceptionpublic Channel(String name, ExecutorService exec, Channel.Mode mode, InputStream is, OutputStream os, OutputStream header) throws IOException
IOExceptionpublic Channel(String name, ExecutorService exec, Channel.Mode mode, InputStream is, OutputStream os, OutputStream header, boolean restricted) throws IOException
name - Human readable name of this channel. Used for debug/logging. Can be anything.exec - Commands sent from the remote peer will be executed by using this Executor.mode - The encoding to be used over the stream.is - Stream connected to the remote peer. It's the caller's responsibility to do
buffering on this stream, if that's necessary.os - Stream connected to the remote peer. It's the caller's responsibility to do
buffering on this stream, if that's necessary.header - If non-null, receive the portion of data in is before
the data goes into the "binary mode". This is useful
when the established communication channel might include some data that might
be useful for debugging/trouble-shooting.restricted - If true, this channel won't accept Commands that allow the remote end to execute arbitrary closures
--- instead they can only call methods on objects that are exported by this channel.
This also prevents the remote end from loading classes into JVM.
Note that it still allows the remote end to deserialize arbitrary object graph
(provided that all the classes are already available in this JVM), so exactly how
safe the resulting behavior is is up to discussion.IOExceptionpublic <T> T export(Class<T> type, T instance)
Channel
by creating a remotable proxy.
All the parameters and return values must be serializable.
export in interface VirtualChanneltype - Interface to be remoted.Channel, and calling methods on it from the remote side
will invoke the same method on the given local instance object.public boolean preloadJar(Callable<?,?> classLoaderRef, Class... classesInJar) throws IOException, InterruptedException
Channel,
this is normally an acceptable overhead. But sometimes, for example
when a channel is short-lived, or when you know that you'll need
a majority of classes in certain jar files, then it is more efficient
to send a whole jar file over the network upfront and thereby
avoiding individual class transfer over the network.
That is what this method does. It ensures that a series of jar files
are copied to the remote side (AKA "preloading.")
Classloading will consult the preloaded jars before performing
network transfer of class files.classLoaderRef - This parameter is used to identify the remote classloader
that will prefetch the specified jar files. That is, prefetching
will ensure that prefetched jars will kick in
when this Callable object is actually executed remote side.
RemoteClassLoaders are created wisely, one per local ClassLoader,
so this parameter doesn't have to be exactly the same Callable
to be executed later — it just has to be of the same class.classesInJar - Class objects that identify jar files to be preloaded.
Jar files that contain the specified classes will be preloaded into the remote peer.
You just need to specify one class per one jar.IOException - if the preloading fails.InterruptedExceptionpublic boolean preloadJar(ClassLoader local, Class... classesInJar) throws IOException, InterruptedException
IOExceptionInterruptedExceptionpublic boolean preloadJar(ClassLoader local, URL... jars) throws IOException, InterruptedException
IOExceptionInterruptedExceptionpublic <V,T extends Throwable> V call(Callable<V,T> callable) throws IOException, T extends Throwable, InterruptedException
Sends Callable to the remote system, executes it, and returns its result.
call in interface VirtualChannelIOException - If there's any error in the communication between Channels.InterruptedException - If the current thread is interrupted while waiting for the completion.T extends Throwablepublic <V,T extends Throwable> Future<V> callAsync(Callable<V,T> callable) throws IOException
Similar to VirtualChannel.call(Callable) but returns immediately.
The result of the Callable can be obtained through the Future object.
callAsync in interface VirtualChannelFuture object that can be used to wait for the completion.IOException - If there's an error during the communication.public void flushPipe()
throws IOException,
InterruptedException
IOExceptionInterruptedExceptionprotected void terminate(IOException e)
e - The error that caused the connection to be aborted. Never null.public void addListener(Channel.Listener l)
Channel.Listener.removeListener(Listener)public boolean removeListener(Channel.Listener l)
public void join()
throws InterruptedException
Channel to be closed down.
The close-down of a Channel might be initiated locally or remotely.join in interface VirtualChannelInterruptedException - If the current thread is interrupted while waiting for the completion.public void join(long timeout)
throws InterruptedException
Channel to be closed down, but only up the given milliseconds.join in interface VirtualChannelInterruptedException - If the current thread is interrupted while waiting for the completion.public void resetPerformanceCounters()
public void close()
throws IOException
close in interface VirtualChannelIOException - if the orderly shut-down failed.public Object getProperty(Object key)
setProperty(Object, Object).
These properties are also accessible from the remote channel via getRemoteProperty(Object).
This mechanism can be used for one side to discover contextual objects created by the other JVM
(as opposed to executing Callable, which cannot have any reference to the context
of the remote Channel.public <T> T getProperty(ChannelProperty<T> key)
public Object waitForProperty(Object key) throws InterruptedException
getProperty(Object) but wait until some value is set by someone.InterruptedExceptionpublic Object setProperty(Object key, Object value)
getProperty(Object)public Object waitForRemoteProperty(Object key) throws InterruptedException
InterruptedExceptionpublic ListeningPort createLocalToRemotePortForwarding(int recvPort, String forwardHost, int forwardPort) throws IOException, InterruptedException
recvPort - The port on this local machine that we'll listen to. 0 to let
OS pick a random available port. If you specify 0, use
ListeningPort.getPort() to figure out the actual assigned port.forwardHost - The remote host that the connection will be forwarded to.
Connection to this host will be made from the other JVM that
this Channel represents.forwardPort - The remote port that the connection will be forwarded to.IOExceptionInterruptedExceptionpublic ListeningPort createRemoteToLocalPortForwarding(int recvPort, String forwardHost, int forwardPort) throws IOException, InterruptedException
recvPort - The port on the remote JVM (represented by this Channel)
that we'll listen to. 0 to let
OS pick a random available port. If you specify 0, use
ListeningPort.getPort() to figure out the actual assigned port.forwardHost - The remote host that the connection will be forwarded to.
Connection to this host will be made from this JVM.forwardPort - The remote port that the connection will be forwarded to.IOExceptionInterruptedExceptionpublic void dumpExportTable(PrintWriter w) throws IOException
IOExceptionpublic hudson.remoting.ExportTable.ExportList startExportRecording()
public long getLastHeard()
lastHeardpublic static Channel current()
Channel,
as well as during Callable.call() is invoked.Copyright © 2015. All Rights Reserved.