Package hudson.remoting

Class ChannelBuilder

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	Description
ChannelBuilder(String name, ExecutorService executors)	Specify the minimum mandatory parameters.

Method Summary

Modifier and Type	Method	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(@CheckForNull
                                       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

@CheckForNull
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(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