ChannelBuilder (Jenkins remoting layer 3.13 API)

java.lang.Object
- hudson.remoting.ChannelBuilder

Direct Known Subclasses:

NioChannelBuilder
```
public class ChannelBuilder
extends Object
```
Factory for Channel, including hand-shaking between two sides and various configuration switches to change the behaviour of Channel.

Author:

Kohsuke Kawaguchi

Constructor Summary

Constructors
Constructor and Description

ChannelBuilder(String name, ExecutorService executors)
Specify the minimum mandatory parameters.

Constructors
Constructor and Description
`ChannelBuilder(String name, ExecutorService executors)` Specify the minimum mandatory parameters.

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`Channel`	`build(CommandTransport transport)`
`Channel`	`build(InputStream is, OutputStream os)` Performs a handshake over the communication channel and builds a `Channel`.
`Channel`	`build(Socket s)`
`Channel`	`build(SocketChannel s)`
`ClassLoader`	`getBaseLoader()`
`Capability`	`getCapability()`
`ClassFilter`	`getClassFilter()`
`List<CallableDecorator>`	`getDecorators()`
`ExecutorService`	`getExecutors()`
`OutputStream`	`getHeaderStream()`
`JarCache`	`getJarCache()` Gets the JAR Cache storage.
`Channel.Mode`	`getMode()`
`String`	`getName()`
`Map<Object,Object>`	`getProperties()`
`boolean`	`isArbitraryCallableAllowed()`
`boolean`	`isRemoteClassLoadingAllowed()`
`boolean`	`isRestricted()` Deprecated. Test individual features instead.
`protected CommandTransport`	`makeTransport(InputStream is, OutputStream os, Channel.Mode mode, Capability cap)` Instantiate a transport.
`protected CommandTransport`	`negotiate(InputStream is, OutputStream os)` Performs hand-shaking and creates a `CommandTransport`.
`ChannelBuilder`	`with(CallableDecorator decorator)`
`ChannelBuilder`	`withArbitraryCallableAllowed(boolean b)` If false, this channel only allows the other side to invoke methods on exported objects, but not `Channel.call(Callable)` (and its family of methods.) The default is `true`.
`ChannelBuilder`	`withBaseLoader(ClassLoader base)` Specify the classloader used for deserializing remote commands.
`ChannelBuilder`	`withCapability(Capability capability)` Controls the capabilities that we'll advertise to the other side.
`ChannelBuilder`	`withClassFilter(ClassFilter filter)` Replaces the `ClassFilter` used by the channel.
`ChannelBuilder`	`withHeaderStream(OutputStream header)` If non-null, receive the portion of data in `is` before the data goes into the "binary mode".
`ChannelBuilder`	`withJarCache(JarCache jarCache)` Sets the JAR cache storage.
`ChannelBuilder`	`withJarCacheOrDefault(JarCache jarCache)` Sets the JAR cache storage.
`ChannelBuilder`	`withMode(Channel.Mode mode)` The encoding to be used over the stream.
`ChannelBuilder`	`withoutJarCache()` Resets JAR Cache setting to the default.
`<T> ChannelBuilder`	`withProperty(ChannelProperty<T> key, T value)`
`ChannelBuilder`	`withProperty(Object key, Object value)` Sets the property.
`ChannelBuilder`	`withRemoteClassLoadingAllowed(boolean b)` Controls whether or not this channel is willing to load classes from the other side.
`ChannelBuilder`	`withRestricted(boolean restricted)` Deprecated. Control individual features.
`ChannelBuilder`	`withRoleChecker(RoleChecker checker)` Installs another `RoleChecker`.
`ChannelBuilder`	`withRoles(Collection<? extends Role> actual)` Convenience method to install `RoleChecker` that verifies against the fixed set of roles.
`ChannelBuilder`	`withRoles(Role... roles)` Convenience method to install `RoleChecker` that verifies against the fixed set of roles.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - ChannelBuilder
```
public ChannelBuilder(String name,
                      ExecutorService executors)
```
    Specify the minimum mandatory parameters.
    
    Parameters:
    
    name - Human readable name of this channel. Used for debug/logging. Can be anything.
    
    executors - Commands sent from the remote peer will be executed by using this Executor.
- Method Detail
  - getName
```
public String getName()
```
  - getExecutors
```
public ExecutorService getExecutors()
```
  - withBaseLoader
```
public ChannelBuilder withBaseLoader(ClassLoader base)
```
    Specify the classloader used for deserializing remote commands. This is primarily related to Channel.getRemoteProperty(Object). Sometimes two parties communicate over a channel and pass objects around as properties, but those types might not be visible from the classloader loading the Channel class. In such a case, specify a classloader so that those classes resolve. If null, Channel.class.getClassLoader() is used.
  - getBaseLoader
```
public ClassLoader getBaseLoader()
```
  - withMode
```
public ChannelBuilder withMode(Channel.Mode mode)
```
    The encoding to be used over the stream.
  - getMode
```
public Channel.Mode getMode()
```
  - withCapability
```
public ChannelBuilder withCapability(Capability capability)
```
    Controls the capabilities that we'll advertise to the other side.
  - getCapability
```
public Capability getCapability()
```
  - withHeaderStream
```
public ChannelBuilder withHeaderStream(OutputStream 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.
  - getHeaderStream
```
public OutputStream getHeaderStream()
```
  - withRestricted
```
@Deprecated
public ChannelBuilder withRestricted(boolean restricted)
```
    Deprecated. Control individual features.
    
    For compatibility reasons, activates/disables all the security restriction features.
  - isRestricted
```
@Deprecated
public boolean isRestricted()
```
    Deprecated. Test individual features instead.
  - withArbitraryCallableAllowed
```
public ChannelBuilder withArbitraryCallableAllowed(boolean b)
```
    If false, this channel only allows the other side to invoke methods on exported objects, but not Channel.call(Callable) (and its family of methods.) The default is true.
    
    Since:
    
    2.47
  - isArbitraryCallableAllowed
```
public boolean isArbitraryCallableAllowed()
```
    Since:
    
    2.47
  - withRemoteClassLoadingAllowed
```
public ChannelBuilder withRemoteClassLoadingAllowed(boolean b)
```
    Controls whether or not this channel is willing to load classes from the other side. The default is true.
    
    Since:
    
    2.47
  - isRemoteClassLoadingAllowed
```
public boolean isRemoteClassLoadingAllowed()
```
    Since:
    
    2.47
  - withJarCache
```
public ChannelBuilder withJarCache(@Nonnull
                                   JarCache jarCache)
```
    Sets the JAR cache storage.
    
    Parameters:
    
    jarCache - JAR Cache to be used. If a deprecated null value is passed, the behavior will be determined by the Channel implementation.
    
    Returns:
    
    this
    
    Since:
    
    2.38, 3.12 null parameter value is deprecated. withoutJarCache() or withJarCacheOrDefault(JarCache) should be used instead.
  - withJarCacheOrDefault
```
public ChannelBuilder withJarCacheOrDefault(@CheckForNull
                                            JarCache jarCache)
                                     throws IOException
```
    Sets the JAR cache storage.
    
    Parameters:
    
    jarCache - JAR Cache to be used. If null, value of JarCache.getDefault() will be used.
    
    Returns:
    
    this
    
    Throws:
    
    IOException - Default JAR Cache location cannot be initialized
    
    Since:
    
    3.12
  - withoutJarCache
```
public ChannelBuilder withoutJarCache()
```
    Resets JAR Cache setting to the default. The behavior will be determined by the Channel implementation.
    
    Since:
    
    3.12
  - getJarCache
```
@CheckForNull
public JarCache getJarCache()
```
    Gets the JAR Cache storage.
    
    Returns:
    
    null if it is not defined. Channel implementation defines the behavior in such case.
    
    Since:
    
    2.38
  - with
```
public ChannelBuilder with(CallableDecorator decorator)
```
  - getDecorators
```
public List<CallableDecorator> getDecorators()
```
  - withRoles
```
public ChannelBuilder withRoles(Role... roles)
```
    Convenience method to install RoleChecker that verifies against the fixed set of roles.
    
    Since:
    
    2.47
  - withRoles
```
public ChannelBuilder withRoles(Collection<? extends Role> actual)
```
    Convenience method to install RoleChecker that verifies against the fixed set of roles.
    
    Since:
    
    2.47
  - withRoleChecker
```
public ChannelBuilder withRoleChecker(RoleChecker checker)
```
    Installs another RoleChecker.
    
    Since:
    
    2.47
  - withProperty
```
public ChannelBuilder withProperty(Object key,
                                   Object value)
```
    Sets the property. Properties are modifiable after Channel is created, but a property set during channel building is guaranteed to be visible to the other side as soon as the channel is established.
    
    Since:
    
    2.47
  - withProperty
```
public <T> ChannelBuilder withProperty(ChannelProperty<T> key,
                                       T value)
```
    Since:
    
    2.47
  - getProperties
```
public Map<Object,Object> getProperties()
```
    Since:
    
    2.47
  - withClassFilter
```
public ChannelBuilder withClassFilter(ClassFilter filter)
```
    Replaces the ClassFilter used by the channel. By default, ClassFilter.DEFAULT is installed.
    
    Since:
    
    2.53
  - getClassFilter
```
public ClassFilter getClassFilter()
```
    Since:
    
    2.53
  - build
```
public Channel build(InputStream is,
                     OutputStream os)
              throws IOException
```
    Performs a handshake over the communication channel and builds a Channel.
    
    Parameters:
    
    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.
    
    Throws:
    
    IOException
  - build
```
public Channel build(Socket s)
              throws IOException
```
    Throws:
    
    IOException
  - build
```
public Channel build(SocketChannel s)
              throws IOException
```
    Throws:
    
    IOException
  - build
```
public Channel build(CommandTransport transport)
              throws IOException
```
    Throws:
    
    IOException
  - negotiate
```
protected CommandTransport negotiate(InputStream is,
                                     OutputStream os)
                              throws IOException
```
    Performs hand-shaking and creates a CommandTransport. This is an implementation detail of ChannelBuilder and it's protected just so that
    
    Throws:
    
    IOException
  - makeTransport
```
protected CommandTransport makeTransport(InputStream is,
                                         OutputStream os,
                                         Channel.Mode mode,
                                         Capability cap)
                                  throws IOException
```
    Instantiate a transport.
    
    Parameters:
    
    is - The negotiated input stream that hides
    
    os - the underlying stream.
    
    mode - The mode to create the transport in.
    
    cap - Capabilities of the other side, as determined during the handshaking.
    
    Throws:
    
    IOException

Class ChannelBuilder

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ChannelBuilder

Method Detail

getName

getExecutors

withBaseLoader

getBaseLoader

withMode

getMode

withCapability

getCapability

withHeaderStream

getHeaderStream

withRestricted

isRestricted

withArbitraryCallableAllowed

isArbitraryCallableAllowed

withRemoteClassLoadingAllowed

isRemoteClassLoadingAllowed

withJarCache

withJarCacheOrDefault

withoutJarCache

getJarCache

with

getDecorators

withRoles

withRoles

withRoleChecker

withProperty

withProperty

getProperties

withClassFilter

getClassFilter

build

build

build

build

negotiate

makeTransport