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 Details

    • 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 Details

    • 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