Class Channel
- java.lang.Object
-
- hudson.remoting.Channel
-
- All Implemented Interfaces:
VirtualChannel
,Closeable
,AutoCloseable
public class Channel extends Object implements VirtualChannel, Closeable
Represents a communication channel to the remote peer.A
Channel
is a mechanism for two JVMs to communicate over bi-directionalInputStream
/OutputStream
pair.Channel
represents an endpoint of the stream, and thus twoChannel
s 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 viaclose()
.The basic unit of remoting is an executable
Callable
object. An application can create aCallable
object, and execute it remotely by using thecall(Callable)
method orcallAsync(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 overChannel
on-demand, so there's no need to pre-deploy such classes on both JVMs.Implementor's Note
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.- Author:
- Kohsuke Kawaguchi
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
Channel.Listener
Callback "interface" for changes in the state ofChannel
.static class
Channel.Mode
Communication mode used in conjunction withClassicCommandTransport
.
-
Field Summary
Fields Modifier and Type Field Description AtomicInteger
classLoadingCount
Total counts of remote classloading activities.AtomicInteger
classLoadingPrefetchCacheCount
Prefetch cache hits.AtomicLong
classLoadingTime
Total number of nanoseconds spent for remote class loading.ExecutorService
executor
static int
PIPE_WINDOW_SIZE
Default pipe window size.Capability
remoteCapability
Capability of the remoteChannel
.AtomicInteger
resourceLoadingCount
Total count of remote resource loading.AtomicLong
resourceLoadingTime
Total number of nanoseconds spent for remote resource loading.
-
Constructor Summary
Constructors Modifier Constructor Description protected
Channel(ChannelBuilder settings, CommandTransport transport)
Channel(String name, ExecutorService exec, Channel.Mode mode, InputStream is, OutputStream os)
Deprecated.as of 2.24 UseChannelBuilder
ChannelBuilder(name, exec) .withMode(mode) .build(is, os)Channel(String name, ExecutorService exec, Channel.Mode mode, InputStream is, OutputStream os, OutputStream header)
Deprecated.as of 2.24 UseChannelBuilder
ChannelBuilder(name, exec) .withMode(mode) .withHeaderStream(header) .withArbitraryCallableAllowed(true) .withRemoteClassLoadingAllowed(true) .build(is, os)Channel(String name, ExecutorService exec, Channel.Mode mode, InputStream is, OutputStream os, OutputStream header, boolean restricted)
Deprecated.as of 2.24 UseChannelBuilder
ChannelBuilder(name, exec) .withMode(mode) .withHeaderStream(header) .withArbitraryCallableAllowed(!restricted) .withRemoteClassLoadingAllowed(!restricted) .withBaseLoader(base) .build(is, os)Channel(String name, ExecutorService exec, Channel.Mode mode, InputStream is, OutputStream os, OutputStream header, boolean restricted, ClassLoader base)
Deprecated.as of 2.24 UseChannelBuilder
ChannelBuilder(name, exec) .withMode(mode) .withHeaderStream(header) .withArbitraryCallableAllowed(!restricted) .withRemoteClassLoadingAllowed(!restricted) .withBaseLoader(base) .build(is, os)Channel(String name, ExecutorService exec, CommandTransport transport, boolean restricted, ClassLoader base)
Deprecated.as of 2.24 UseChannelBuilder
ChannelBuilder(name, exec) .withArbitraryCallableAllowed(!restricted) .withRemoteClassLoadingAllowed(!restricted) .withBaseLoader(base) .build(transport)Channel(String name, ExecutorService exec, CommandTransport transport, boolean restricted, ClassLoader base, JarCache jarCache)
Deprecated.as of 2.38 UseChannelBuilder
ChannelBuilder(name, exec) .withArbitraryCallableAllowed(!restricted) .withRemoteClassLoadingAllowed(!restricted) .withBaseLoader(base) .withJarCache(jarCache) .build(transport)Channel(String name, ExecutorService exec, InputStream is, OutputStream os)
Deprecated.as of 2.24 UseChannelBuilder
ChannelBuilder(name, exec) .withMode(Channel.Mode.BINARY) .build(is, os)Channel(String name, ExecutorService exec, InputStream is, OutputStream os, OutputStream header)
Deprecated.as of 2.24 UseChannelBuilder
ChannelBuilder(name, exec) .withMode(Channel.Mode.BINARY) .withHeaderStream(header) .build(is, os)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
addListener(Channel.Listener l)
Registers a newChannel.Listener
.void
addLocalExecutionInterceptor(CallableFilter filter)
Deprecated.void
addLocalExecutionInterceptor(CallableDecorator decorator)
Adds aCallableDecorator
that gets a chance to decorate everyCallable
s that run locally sent by the other peer.<V,T extends Throwable>
Vcall(Callable<V,T> callable)
Makes a remote procedure call.<V,T extends Throwable>
Future<V>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.)void
close(Throwable diagnosis)
Closes the channel.ListeningPort
createLocalToRemotePortForwarding(int recvPort, String forwardHost, int forwardPort)
Deprecated.as of 3.39ListeningPort
createRemoteToLocalPortForwarding(int recvPort, String forwardHost, int forwardPort)
Deprecated.as of 3.39static Channel
current()
This method can be invoked during the serialization/deserialization of objects when they are transferred to the remoteChannel
, as well as duringCallable.call()
is invoked.static Channel
currentOrFail()
Gets current channel or fails withIllegalStateException
.void
dumpDiagnostics(PrintWriter w)
Print the diagnostic information.static void
dumpDiagnosticsForAll(PrintWriter w)
CallsdumpDiagnostics(PrintWriter)
across all the active channels in this system.void
dumpExportTable(PrintWriter w)
Dumps the list of exported objects and their allocation traces to the given output.void
dumpPerformanceCounters(PrintWriter w)
Print the performance counters.<T> T
export(Class<T> type, T instance)
Exports an object for remoting to the otherChannel
by creating a remotable proxy.Throwable
getCloseRequestCause()
Gets cause of the close request.JarCache
getJarCache()
If this channel is built with jar file caching, return the object that manages this cache.long
getLastHeard()
TODO: this is not safe against clock skew and is called from jenkins core (and potentially plugins)String
getName()
<T> T
getProperty(ChannelProperty<T> key)
Object
getProperty(Object key)
Gets the application specific property set bysetProperty(Object, Object)
.<T> T
getRemoteProperty(ChannelProperty<T> key)
Object
getRemoteProperty(Object key)
Gets the property set on the remote peer.Throwable
getSenderCloseCause()
Get why the sender side of the channel has been closed.OutputStream
getUnderlyingOutput()
Deprecated.Future version of the remoting module may add other modes of creating channel that doesn't involve stream pair.boolean
isArbitraryCallableAllowed()
boolean
isClosingOrClosed()
Returnstrue
if the channel is either in the process of closing down or has closed down.boolean
isInClosed()
If the receiving end of the channel is closed (that is, if we are guaranteed to receive nothing further), this method returns true.boolean
isOutClosed()
Is the sender side of the transport already closed?boolean
isRemoteClassLoadingAllowed()
boolean
isRestricted()
Deprecated.Use methods likeisRemoteClassLoadingAllowed()
andisArbitraryCallableAllowed()
to test individual features.void
join()
Waits for thisChannel
to be closed down.void
join(long timeout)
Waits for thisChannel
to be closed down, but only up the given milliseconds.void
pin(Object instance)
Increase reference count so much to effectively prevent de-allocation.void
pinClassLoader(ClassLoader cl)
Pin down the exported classloader.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
removeLocalExecutionInterceptor(CallableFilter filter)
Deprecated.void
removeLocalExecutionInterceptor(CallableDecorator decorator)
Removes the filter introduced byaddLocalExecutionInterceptor(CallableDecorator)
.void
resetPerformanceCounters()
Resets all the performance counters.void
setArbitraryCallableAllowed(boolean b)
void
setJarCache(JarCache jarCache)
You can change theJarCache
while the channel is in operation, but doing so doesn't impactRemoteClassLoader
s that are already created.void
setMaximumBytecodeLevel(short level)
Sets the maximum bytecode version (~ JDK) that we expect this channel to be able to load.<T> T
setProperty(ChannelProperty<T> key, T value)
Object
setProperty(Object key, Object value)
Sets the property value on this side of the channel.void
setRemoteClassLoadingAllowed(boolean b)
Controls whether or not this channel is willing to load classes from the other side.void
setRestricted(boolean b)
Deprecated.Use methods likesetRemoteClassLoadingAllowed(boolean)
andsetArbitraryCallableAllowed(boolean)
to control individual features.hudson.remoting.ExportTable.ExportList
startExportRecording()
void
syncIO()
Blocks until all the I/O packets sent before this gets fully executed by the remote side, then return.void
syncLocalIO()
Blocks until all the I/O packets sent from remote is fully locally executed, then return.void
terminate(IOException e)
Aborts the connection in response to an error.String
toString()
<T> T
waitForProperty(ChannelProperty<T> key)
Object
waitForProperty(Object key)
Works likegetProperty(Object)
but wait until some value is set by someone.<T> T
waitForRemoteProperty(ChannelProperty<T> key)
Deprecated.BecauseChannelProperty
is identity-equality, this method would never work.Object
waitForRemoteProperty(Object key)
Gets the property set on the remote peer.
-
-
-
Field Detail
-
executor
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public final ExecutorService executor
-
classLoadingTime
public final AtomicLong classLoadingTime
Total number of nanoseconds spent for remote class loading.Remote code execution often results in classloading activity (more precisely, when the remote peer requests some computation on this channel, this channel often has to load necessary classes from the remote peer.)
This counter represents the total amount of time this channel had to spend loading classes from the remote peer. The time measurement doesn't include the time locally spent to actually define the class (as the local classloading would have incurred the same cost.)
-
classLoadingCount
public final AtomicInteger classLoadingCount
Total counts of remote classloading activities. Used in a pair withclassLoadingTime
.
-
classLoadingPrefetchCacheCount
public final AtomicInteger classLoadingPrefetchCacheCount
Prefetch cache hits. Out of all the counts inclassLoadingCount
, how many times were we able to resolve them by ourselves, saving a remote roundtrip call?- Since:
- 2.24
-
resourceLoadingTime
public final AtomicLong resourceLoadingTime
Total number of nanoseconds spent for remote resource loading.- See Also:
classLoadingTime
-
resourceLoadingCount
public final AtomicInteger resourceLoadingCount
Total count of remote resource loading.- See Also:
classLoadingCount
-
remoteCapability
public final Capability remoteCapability
Capability of the remoteChannel
.
-
PIPE_WINDOW_SIZE
public static final int PIPE_WINDOW_SIZE
Default pipe window size.This controls the amount of bytes that can be in flight. Value too small would fail to efficiently utilize a high-latency/large-bandwidth network, but a value too large would cause the risk of a large memory consumption when a pipe clogs (that is, the receiver isn't consuming bytes we are sending fast enough.)
If we have a gigabit ethernet (with effective transfer rate of 100M bps) and 20ms latency, the pipe will hold (100M bits/sec * 0.02sec / 8 bits/byte = 0.25MB. So 1MB or so is big enough for most network, and hopefully this is an acceptable enough memory consumption in case of clogging.
- See Also:
PipeWindow
-
-
Constructor Detail
-
Channel
@Deprecated public Channel(String name, ExecutorService exec, InputStream is, OutputStream os) throws IOException
Deprecated.as of 2.24 UseChannelBuilder
ChannelBuilder(name, exec) .withMode(Channel.Mode.BINARY) .build(is, os)- Throws:
IOException
-
Channel
@Deprecated public Channel(String name, ExecutorService exec, Channel.Mode mode, InputStream is, OutputStream os) throws IOException
Deprecated.as of 2.24 UseChannelBuilder
ChannelBuilder(name, exec) .withMode(mode) .build(is, os)- Throws:
IOException
-
Channel
@Deprecated public Channel(String name, ExecutorService exec, InputStream is, OutputStream os, OutputStream header) throws IOException
Deprecated.as of 2.24 UseChannelBuilder
ChannelBuilder(name, exec) .withMode(Channel.Mode.BINARY) .withHeaderStream(header) .build(is, os)- Throws:
IOException
-
Channel
@Deprecated public Channel(String name, ExecutorService exec, Channel.Mode mode, InputStream is, OutputStream os, OutputStream header) throws IOException
Deprecated.as of 2.24 UseChannelBuilder
ChannelBuilder(name, exec) .withMode(mode) .withHeaderStream(header) .withArbitraryCallableAllowed(true) .withRemoteClassLoadingAllowed(true) .build(is, os)- Throws:
IOException
-
Channel
@Deprecated public Channel(String name, ExecutorService exec, Channel.Mode mode, InputStream is, OutputStream os, OutputStream header, boolean restricted) throws IOException
Deprecated.as of 2.24 UseChannelBuilder
ChannelBuilder(name, exec) .withMode(mode) .withHeaderStream(header) .withArbitraryCallableAllowed(!restricted) .withRemoteClassLoadingAllowed(!restricted) .withBaseLoader(base) .build(is, os)- Throws:
IOException
-
Channel
@Deprecated public Channel(String name, ExecutorService exec, Channel.Mode mode, InputStream is, OutputStream os, OutputStream header, boolean restricted, ClassLoader base) throws IOException
Deprecated.as of 2.24 UseChannelBuilder
ChannelBuilder(name, exec) .withMode(mode) .withHeaderStream(header) .withArbitraryCallableAllowed(!restricted) .withRemoteClassLoadingAllowed(!restricted) .withBaseLoader(base) .build(is, os)Creates a new channel.- Parameters:
restricted
- SeeChannel(String, ExecutorService, Mode, InputStream, OutputStream, OutputStream, boolean, ClassLoader)
- Throws:
IOException
-
Channel
@Deprecated public Channel(String name, ExecutorService exec, CommandTransport transport, boolean restricted, ClassLoader base) throws IOException
Deprecated.as of 2.24 UseChannelBuilder
ChannelBuilder(name, exec) .withArbitraryCallableAllowed(!restricted) .withRemoteClassLoadingAllowed(!restricted) .withBaseLoader(base) .build(transport)- Throws:
IOException
- Since:
- 2.13
-
Channel
@Deprecated public Channel(String name, ExecutorService exec, CommandTransport transport, boolean restricted, ClassLoader base, JarCache jarCache) throws IOException
Deprecated.as of 2.38 UseChannelBuilder
ChannelBuilder(name, exec) .withArbitraryCallableAllowed(!restricted) .withRemoteClassLoadingAllowed(!restricted) .withBaseLoader(base) .withJarCache(jarCache) .build(transport)Creates a new channel.- Parameters:
name
- SeeChannel(String, ExecutorService, Mode, InputStream, OutputStream, OutputStream, boolean, ClassLoader)
exec
- SeeChannel(String, ExecutorService, Mode, InputStream, OutputStream, OutputStream, boolean, ClassLoader)
transport
- The transport that we runChannel
on top of.base
- SeeChannel(String, ExecutorService, Mode, InputStream, OutputStream, OutputStream, boolean, ClassLoader)
restricted
- SeeChannel(String, ExecutorService, Mode, InputStream, OutputStream, OutputStream, boolean, ClassLoader)
- Throws:
IOException
- Since:
- 2.24
-
Channel
protected Channel(@NonNull ChannelBuilder settings, @NonNull CommandTransport transport) throws IOException
- Throws:
IOException
- Since:
- 2.38
-
-
Method Detail
-
isOutClosed
public boolean isOutClosed()
Is the sender side of the transport already closed?
-
getSenderCloseCause
@CheckForNull public final Throwable getSenderCloseCause()
Get why the sender side of the channel has been closed.- Returns:
- Close cause or
null
if the sender side is active.null
result does not guarantee that the channel is actually operational. - Since:
- 3.11
-
isClosingOrClosed
public boolean isClosingOrClosed()
Returnstrue
if the channel is either in the process of closing down or has closed down. If the result istrue
, it means that the channel will be closed at some point by Remoting, and that it makes no sense to send any newUserRequest
s to the remote side. Invocations likecall(hudson.remoting.Callable)
andcallAsync(hudson.remoting.Callable)
will just fail as well.- Since:
- 2.33
-
getCloseRequestCause
@CheckForNull public Throwable getCloseRequestCause()
Gets cause of the close request.- Returns:
outClosed
if notnull
, value of the transient cachecloseRequestCause
otherwise. The latter one may show random cause in the case of race conditions.- Since:
- 3.11
-
export
public <T> T export(Class<T> type, T instance)
Exports an object for remoting to the otherChannel
by creating a remotable proxy. The returned reference must be kept if there is ongoing operation on the remote side. Once it is released, the exported object will be deallocated as well. Please keep in mind that the object may be also released earlier than expected by JVM (e.g. see JENKINS-23271).- Specified by:
export
in interfaceVirtualChannel
- Type Parameters:
T
- Type- Parameters:
type
- Interface to be remoted.instance
- Instance to be exported.null
instances won't be exported to the remote instance.All the parameters and return values must be serializable.
- Returns:
- the proxy object that implements
T
. This object can be transferred to the otherChannel
, and calling methods on it from the remote side will invoke the same method on the given localinstance
object.null
if the input instance isnull
.
-
pin
public void pin(@NonNull Object instance)
Increase reference count so much to effectively prevent de-allocation.- Parameters:
instance
- Instance to be pinned
-
pinClassLoader
public void pinClassLoader(ClassLoader cl)
Pin down the exported classloader.
-
preloadJar
public boolean preloadJar(Callable<?,?> classLoaderRef, Class<?>... classesInJar) throws IOException, InterruptedException
Preloads jar files on the remote side.This is a performance improvement method that can be safely ignored if your goal is just to make things working.
Normally, classes are transferred over the network one at a time, on-demand. This design is mainly driven by how Java classloading works — we can't predict what classes will be necessarily upfront very easily.
Classes are loaded only once, so for long-running
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.
Beware that this method is not useful in all configurations. If a
RemoteClassLoader
has anotherRemoteClassLoader
as a parent, which would be typical, then preloading a JAR in it will not reduce network round-trips: each class load still has to callloadClass
on the parent, which will wind up checking the remote side just to get a negative answer.- Parameters:
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 thisCallable
object is actually executed remote side.RemoteClassLoader
s are created wisely, one per localClassLoader
, so this parameter doesn't have to be exactly the sameCallable
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.- Returns:
- true if the preloading actually happened. false if all the jars are already preloaded. This method is implemented in such a way that unnecessary jar file transfer will be avoided, and the return value will tell you if this optimization kicked in. Under normal circumstances your program shouldn't depend on this return value. It's just a hint.
- Throws:
IOException
- if the preloading fails.InterruptedException
-
preloadJar
public boolean preloadJar(ClassLoader local, Class<?>... classesInJar) throws IOException, InterruptedException
- Throws:
IOException
InterruptedException
-
preloadJar
public boolean preloadJar(ClassLoader local, URL... jars) throws IOException, InterruptedException
- Throws:
IOException
InterruptedException
-
getJarCache
@CheckForNull public JarCache getJarCache()
If this channel is built with jar file caching, return the object that manages this cache.- Returns:
- JAR Cache object.
null
if JAR caching is disabled - Since:
- 2.24, 3.10 JAR Cache is Nonnull, 3.12 JAR Cache made nullable again due to JENKINS-45755
-
setJarCache
public void setJarCache(@NonNull JarCache jarCache)
You can change theJarCache
while the channel is in operation, but doing so doesn't impactRemoteClassLoader
s that are already created. So to best avoid performance loss due to race condition, please set a JarCache in the constructor, unless your call sequence guarantees that you call this method before remote classes are loaded.- Parameters:
jarCache
- New JAR Cache to be used. Cannot benull
, JAR Cache disabling on a running channel is not supported.- Since:
- 2.24
-
call
public <V,T extends Throwable> V call(Callable<V,T> callable) throws IOException, T extends Throwable, InterruptedException
Makes a remote procedure call.Sends
Callable
to the remote system, executes it, and returns its result. Such calls will be considered as user-space requests. If the channel cannot execute the requests (e.g. when it is being closed), the operations may be rejected even if the channel is still active.- Specified by:
call
in interfaceVirtualChannel
- Parameters:
callable
- Callable to be executed- Throws:
IOException
- If there's any error in the communication betweenChannel
s.T
- User exception defined by the callableInterruptedException
- If the current thread is interrupted while waiting for the completion.T extends Throwable
-
callAsync
public <V,T extends Throwable> Future<V> callAsync(Callable<V,T> callable) throws IOException
Makes an asynchronous remote procedure call.Similar to
VirtualChannel.call(Callable)
but returns immediately. The result of theCallable
can be obtained through theFuture
object. Such calls will be considered as user-space requests. If the channel cannot execute the requests (e.g. when it is being closed), the operations may be rejected even if the channel is still active.- Specified by:
callAsync
in interfaceVirtualChannel
- Returns:
- The
Future
object that can be used to wait for the completion. - Throws:
IOException
- If there's an error during the communication.
-
terminate
public void terminate(@NonNull IOException e)
Aborts the connection in response to an error. This is an SPI forCommandTransport
implementation to notifyChannel
when the underlying connection is severed. Once the call is calledcloseRequested
will be set immediately to prevent further executions ofUserRequest
s.- Parameters:
e
- The error that caused the connection to be aborted. Never null.
-
addListener
public void addListener(Channel.Listener l)
Registers a newChannel.Listener
.- See Also:
removeListener(Listener)
-
removeListener
public boolean removeListener(Channel.Listener l)
Removes a listener.- Returns:
- false if the given listener has not been registered to begin with.
-
addLocalExecutionInterceptor
public void addLocalExecutionInterceptor(CallableDecorator decorator)
Adds aCallableDecorator
that gets a chance to decorate everyCallable
s that run locally sent by the other peer. This is useful to tweak the environment those closures are run, such as setting up the thread context environment.
-
removeLocalExecutionInterceptor
public void removeLocalExecutionInterceptor(CallableDecorator decorator)
Removes the filter introduced byaddLocalExecutionInterceptor(CallableDecorator)
.
-
addLocalExecutionInterceptor
@Deprecated public void addLocalExecutionInterceptor(CallableFilter filter)
Deprecated.
-
removeLocalExecutionInterceptor
@Deprecated public void removeLocalExecutionInterceptor(CallableFilter filter)
Deprecated.
-
join
public void join() throws InterruptedException
Waits for thisChannel
to be closed down. The close-down of aChannel
might be initiated locally or remotely.- Specified by:
join
in interfaceVirtualChannel
- Throws:
InterruptedException
- If the current thread is interrupted while waiting for the completion.
-
isInClosed
public boolean isInClosed()
If the receiving end of the channel is closed (that is, if we are guaranteed to receive nothing further), this method returns true.
-
isRestricted
@Deprecated public boolean isRestricted()
Deprecated.Use methods likeisRemoteClassLoadingAllowed()
andisArbitraryCallableAllowed()
to test individual features.Returns true if this channel has any of the security restrictions enabled.
-
setRestricted
@Deprecated public void setRestricted(boolean b)
Deprecated.Use methods likesetRemoteClassLoadingAllowed(boolean)
andsetArbitraryCallableAllowed(boolean)
to control individual features.Activates/disables all the security restriction mode.
-
isRemoteClassLoadingAllowed
public boolean isRemoteClassLoadingAllowed()
- Since:
- 2.47
-
setRemoteClassLoadingAllowed
public void setRemoteClassLoadingAllowed(boolean b)
Controls whether or not this channel is willing to load classes from the other side. The default is on.- Since:
- 2.47
-
isArbitraryCallableAllowed
public boolean isArbitraryCallableAllowed()
- Since:
- 2.47
-
setArbitraryCallableAllowed
public void setArbitraryCallableAllowed(boolean b)
- Since:
- 2.47
- See Also:
ChannelBuilder.withArbitraryCallableAllowed(boolean)
-
setMaximumBytecodeLevel
public void setMaximumBytecodeLevel(short level) throws IOException, InterruptedException
Sets the maximum bytecode version (~ JDK) that we expect this channel to be able to load. If attempts are made to load remote classes using newer bytecode, they are immediately rejected, even if the remote JVM is actually new enough to load it. This helps maintain compatibility by making tests fail immediately without the need for an old JDK installation. By default, the remote class loader will try to load any bytecode version.- Parameters:
level
- e.g. 5 for JDK 5 (the minimum sensible value)- Throws:
IOException
InterruptedException
- Since:
- 2.29
-
join
public void join(long timeout) throws InterruptedException
Waits for thisChannel
to be closed down, but only up the given milliseconds.- Specified by:
join
in interfaceVirtualChannel
- Parameters:
timeout
- TImeout in milliseconds- Throws:
InterruptedException
- If the current thread is interrupted while waiting for the completion.- Since:
- 1.299
-
resetPerformanceCounters
public void resetPerformanceCounters()
Resets all the performance counters.
-
dumpPerformanceCounters
public void dumpPerformanceCounters(PrintWriter w) throws IOException
Print the performance counters.- Parameters:
w
- Output writer- Throws:
IOException
- Since:
- 2.24
-
dumpDiagnostics
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public void dumpDiagnostics(@NonNull PrintWriter w) throws IOException
Print the diagnostic information.Here's how you interpret these metrics:
- Created
- When the channel was created, which is more or less the same thing as when the channel is connected.
- Commands sent
-
Number of
Command
objects sent to the other side. More specifically, number of commands successfully passed totransport
, which means data was written to socket withClassicCommandTransport
but just buffered for write withNioChannelHub
. If you have access to the remoting diagnostics of the other side of the channel, then you can compare this with "commandsReceived" metrics of the other side to see how many commands are in transit in transport. IfcommandsSent==commandsReceived
, then no command is in transit. - Commands received
-
Number of
Command
objects received from the other side. More precisely, number of commands reported fromtransport
. So for example, if data is still buffered somewhere in the networking stack, it won't be counted here. - Last command sent
-
The timestamp in which the last command was sent to the other side. The timestamp in which
lastCommandSentAt
was updated. - Last command received
-
The timestamp in which the last command was sent to the other side. The timestamp in which
lastCommandReceivedAt
was updated. - Pending outgoing calls
- Number of RPC calls (e.g., method call through a proxy) that are made but not returned yet. If you have the remoting diagnostics of the other side, you can compare this number with "pending incoming calls" on the other side to see how many RPC calls are executing vs in flight. "one side's incoming calls" < "the other side's outgoing calls" indicates some RPC requests or responses are passing through the network layer, and mismatch between "# of commands sent" vs "# of commands received" can give some indication of whether it is request or response that's in flight.
- Pending incoming calls
- The reverse of "pending outgoing calls". Number of RPC calls (e.g., method call through a proxy) that the other side has made to us but not yet returned yet.
- Parameters:
w
- Output destination- Throws:
IOException
- Error while creating or writing the channel information- Since:
- 2.62.3 - stable 2.x (restricted), 3.1
-
close
public void close() throws IOException
Performs an orderly shut down of this channel (and the remote peer.)- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Specified by:
close
in interfaceVirtualChannel
- Throws:
IOException
- if the orderly shut-down failed.
-
close
public void close(@CheckForNull Throwable diagnosis) throws IOException
Closes the channel. Once the call is calledcloseRequested
will be set immediately to prevent further executions ofUserRequest
s.- Parameters:
diagnosis
- If someone (either this side or the other side) tries to use a channel that's already closed, they'll get a stack trace indicating that the channel has already been closed. This diagnosis, if provided, will further chained to that exception, providing more contextual information about why the channel was closed.- Throws:
IOException
- Since:
- 2.8
-
getProperty
public Object getProperty(Object key)
Gets the application specific property set bysetProperty(Object, Object)
. These properties are also accessible from the remote channel viagetRemoteProperty(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 remoteChannel
.- Parameters:
key
- Key- Returns:
- The property or
null
if there is no property for the specified key
-
getProperty
public <T> T getProperty(ChannelProperty<T> key)
-
waitForProperty
@NonNull public Object waitForProperty(@NonNull Object key) throws InterruptedException
Works likegetProperty(Object)
but wait until some value is set by someone.- Parameters:
key
- Property key- Throws:
IllegalStateException
- if the channel is closed. The idea is that channel properties are expected to be the coordination mechanism between two sides of the channel, and this method in particular is a way of one side to wait for the set by the other side of the channel (viawaitForRemoteProperty(Object)
. If we don't abort after the channel shutdown, this method will block forever.InterruptedException
-
waitForProperty
public <T> T waitForProperty(ChannelProperty<T> key) throws InterruptedException
- Throws:
InterruptedException
-
setProperty
@CheckForNull public Object setProperty(@NonNull Object key, @CheckForNull Object value)
Sets the property value on this side of the channel.- Parameters:
key
- Property keyvalue
- Value to set.null
removes the existing entry without adding a new one.- Returns:
- Old property value or
null
if it was not set - See Also:
getProperty(Object)
-
setProperty
public <T> T setProperty(ChannelProperty<T> key, T value)
-
getRemoteProperty
@CheckForNull public Object getRemoteProperty(Object key)
Gets the property set on the remote peer.- Returns:
null
if the property of the said key isn't set.
-
getRemoteProperty
@CheckForNull public <T> T getRemoteProperty(ChannelProperty<T> key)
-
waitForRemoteProperty
public Object waitForRemoteProperty(Object key) throws InterruptedException
Gets the property set on the remote peer. This method blocks until the property is set by the remote peer.- Throws:
InterruptedException
-
waitForRemoteProperty
@Deprecated public <T> T waitForRemoteProperty(ChannelProperty<T> key) throws InterruptedException
Deprecated.BecauseChannelProperty
is identity-equality, this method would never work. This is a design error.- Throws:
InterruptedException
-
getUnderlyingOutput
@Deprecated public OutputStream getUnderlyingOutput()
Deprecated.Future version of the remoting module may add other modes of creating channel that doesn't involve stream pair. Therefore, we aren't committing to this method. This method isn't a part of the committed API of the channel class.Obtain the output stream passed to the constructor.- Returns:
- While the current version always return a non-null value, the caller must not
make that assumption for the above reason. This method may return null in the future version
to indicate that the
Channel
is not sitting on top of a stream pair.
-
createLocalToRemotePortForwarding
@Deprecated public ListeningPort createLocalToRemotePortForwarding(int recvPort, String forwardHost, int forwardPort) throws IOException, InterruptedException
Deprecated.as of 3.39Starts a local to remote port forwarding (the equivalent of "ssh -L").- Parameters:
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, useListeningPort.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 thisChannel
represents.forwardPort
- The remote port that the connection will be forwarded to.- Returns:
- Created
PortForwarder
- Throws:
IOException
InterruptedException
-
createRemoteToLocalPortForwarding
@Deprecated public ListeningPort createRemoteToLocalPortForwarding(int recvPort, String forwardHost, int forwardPort) throws IOException, InterruptedException
Deprecated.as of 3.39Starts a remote to local port forwarding (the equivalent of "ssh -R").- Parameters:
recvPort
- The port on the remote JVM (represented by thisChannel
) that we'll listen to. 0 to let OS pick a random available port. If you specify 0, useListeningPort.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.- Returns:
- Created
PortForwarder
. - Throws:
IOException
InterruptedException
-
syncIO
public void syncIO() throws IOException, InterruptedException
Blocks until all the I/O packets sent before this gets fully executed by the remote side, then return.- Throws:
IOException
- If the remote doesn't support this operation, or if sync fails for other reasons.InterruptedException
-
syncLocalIO
public void syncLocalIO() throws InterruptedException
Description copied from interface:VirtualChannel
Blocks until all the I/O packets sent from remote is fully locally executed, then return.- Specified by:
syncLocalIO
in interfaceVirtualChannel
- Throws:
InterruptedException
-
getName
public String getName()
-
dumpExportTable
public void dumpExportTable(PrintWriter w) throws IOException
Dumps the list of exported objects and their allocation traces to the given output.- Throws:
IOException
-
startExportRecording
public hudson.remoting.ExportTable.ExportList startExportRecording()
-
getLastHeard
public long getLastHeard()
TODO: this is not safe against clock skew and is called from jenkins core (and potentially plugins)- See Also:
lastCommandReceivedAt
-
current
@CheckForNull public static Channel current()
This method can be invoked during the serialization/deserialization of objects when they are transferred to the remoteChannel
, as well as duringCallable.call()
is invoked.- Returns:
null
if the calling thread is not performing serialization.
-
currentOrFail
@NonNull public static Channel currentOrFail() throws IllegalStateException
Gets current channel or fails withIllegalStateException
.- Returns:
- Current channel
- Throws:
IllegalStateException
- the calling thread has no associated channel.- Since:
- 3.14
- See Also:
SerializableOnlyOverRemoting
-
dumpDiagnosticsForAll
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public static void dumpDiagnosticsForAll(@NonNull PrintWriter w)
CallsdumpDiagnostics(PrintWriter)
across all the active channels in this system. Used for diagnostics.- Parameters:
w
- Output destination- Since:
- 2.62.3 - stable 2.x (restricted), 3.1
-
-