com.sun.mail.util

## Class SocketFetcher

- java.lang.Object
- - com.sun.mail.util.SocketFetcher

-     public class SocketFetcher
      extends Object

  This class is used to get Sockets. Depending on the arguments passed it will either return a plain java.net.Socket or dynamically load the SocketFactory class specified in the classname param and return a socket created by that SocketFactory.
  Author:
    Max Spivak, Bill Shannon

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Socket` | `getSocket(String host, int port, Properties props, String prefix)`
    `static Socket` | `getSocket(String host, int port, Properties props, String prefix, boolean useSSL)` This method returns a Socket.
    `static Socket` | `startTLS(Socket socket)` Deprecated.
    `static Socket` | `startTLS(Socket socket, Properties props, String prefix)` Deprecated.
    `static Socket` | `startTLS(Socket socket, String host, Properties props, String prefix)` Start TLS on an existing socket.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### getSocket

          public static Socket getSocket(String host,
                         int port,
                         Properties props,
                         String prefix,
                         boolean useSSL)
                                  throws IOException

      This method returns a Socket. Properties control the use of socket factories and other socket characteristics. The properties used are:
      - prefix.socketFactory
      - prefix.socketFactory.class
      - prefix.socketFactory.fallback
      - prefix.socketFactory.port
      - prefix.ssl.socketFactory
      - prefix.ssl.socketFactory.class
      - prefix.ssl.socketFactory.port
      - prefix.timeout
      - prefix.connectiontimeout
      - prefix.localaddress
      - prefix.localport
      - prefix.usesocketchannels

      If we're making an SSL connection, the ssl.socketFactory properties are used first, if set.

      If the socketFactory property is set, the value is an instance of a SocketFactory class, not a string. The instance is used directly. If the socketFactory property is not set, the socketFactory.class property is considered. (Note that the SocketFactory property must be set using the `put` method, not the `setProperty` method.)

      If the socketFactory.class property isn't set, the socket returned is an instance of java.net.Socket connected to the given host and port. If the socketFactory.class property is set, it is expected to contain a fully qualified classname of a javax.net.SocketFactory subclass. In this case, the class is dynamically instantiated and a socket created by that SocketFactory is returned.

      If the socketFactory.fallback property is set to false, don't fall back to using regular sockets if the socket factory fails.

      The socketFactory.port specifies a port to use when connecting through the socket factory. If unset, the port argument will be used.

      If the connectiontimeout property is set, the timeout is passed to the socket connect method.

      If the timeout property is set, it is used to set the socket timeout.

      If the localaddress property is set, it's used as the local address to bind to. If the localport property is also set, it's used as the local port number to bind to.

      If the usesocketchannels property is set, and we create the Socket ourself, and the selection of other properties allows, create a SocketChannel and get the Socket from it. This allows us to later retrieve the SocketChannel from the Socket and use it with Select.

      Parameters:
        `host` - The host to connect to
        `port` - The port to connect to at the host
        `props` - Properties object containing socket properties
        `prefix` - Property name prefix, e.g., "mail.imap"
        `useSSL` - use the SSL socket factory as the default
      Returns:
        the Socket
      Throws:
        `IOException` - for I/O errors

    - #### getSocket

          public static Socket getSocket(String host,
                         int port,
                         Properties props,
                         String prefix)
                                  throws IOException

      Throws:
        `IOException`

    - #### startTLS

          @Deprecated
          public static Socket startTLS(Socket socket)
                                 throws IOException

      Deprecated.
      Start TLS on an existing socket. Supports the "STARTTLS" command in many protocols. This version for compatibility with possible third party code that might've used this API even though it shouldn't.
      Parameters:
        `socket` - the existing socket
      Returns:
        the wrapped Socket
      Throws:
        `IOException` - for I/O errors

    - #### startTLS

          @Deprecated
          public static Socket startTLS(Socket socket,
                                   Properties props,
                                   String prefix)
                                 throws IOException

      Deprecated.
      Start TLS on an existing socket. Supports the "STARTTLS" command in many protocols. This version for compatibility with possible third party code that might've used this API even though it shouldn't.
      Parameters:
        `socket` - the existing socket
        `props` - the properties
        `prefix` - the property prefix
      Returns:
        the wrapped Socket
      Throws:
        `IOException` - for I/O errors

    - #### startTLS

          public static Socket startTLS(Socket socket,
                        String host,
                        Properties props,
                        String prefix)
                                 throws IOException

      Start TLS on an existing socket. Supports the "STARTTLS" command in many protocols.
      Parameters:
        `socket` - the existing socket
        `host` - the host the socket is connected to
        `props` - the properties
        `prefix` - the property prefix
      Returns:
        the wrapped Socket
      Throws:
        `IOException` - for I/O errors

Copyright © 2016 Oracle. All rights reserved.