uk.ac.starlink.auth

## Class Redirector

- java.lang.Object
- - uk.ac.starlink.auth.Redirector

-     public abstract class Redirector
      extends java.lang.Object

  Defines how HTTP 3xx redirects are handled.
  Since:
    22 Jun 2020

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Redirector` | `DEFAULT` Default instance.
    `static Redirector` | `NO_REDIRECT` No redirections are performed.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Redirector()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Redirector` | `createStandardInstance(int[] redirectCodes)` Returns an instance that redirects on a given list of 3xx codes.
    `java.net.URL` | `getRedirectUrl(java.net.URLConnection conn)` Returns a URL to which connections should be redirected from a supplied URL connection, according to this redirector's policy.
    `abstract boolean` | `isRedirect(int responseCode)` Indicates whether a given HTTP response code should be followed as a redirect.
    `abstract boolean` | `willRedirect(java.lang.String fromProto, java.lang.String toProto)` Indicates whether HTTP 3xx redirection is permitted between two URL protocols.

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

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

- - ### Field Detail

    - #### DEFAULT

          public static final Redirector DEFAULT

      Default instance. Redirects 301, 302, 303, 307 and 308 are followed, and all protocol redirections are permitted except from HTTPS to other (less secure) protocols.

    - #### NO_REDIRECT

          public static final Redirector NO_REDIRECT

      No redirections are performed.

  - ### Constructor Detail

    - #### Redirector

          public Redirector()

  - ### Method Detail

    - #### isRedirect

          public abstract boolean isRedirect(int responseCode)

      Indicates whether a given HTTP response code should be followed as a redirect. This will generaly return true for some or all 3xx values and false otherwise. Codes for which true is returned are assumed to imply an accompanying Location header.
      Parameters:
        `responseCode` - HTTP response code
      Returns:
        true iff responseCode should result in following a Location header

    - #### willRedirect

          public abstract boolean willRedirect(java.lang.String fromProto,
                                               java.lang.String toProto)

      Indicates whether HTTP 3xx redirection is permitted between two URL protocols.

      The behaviour of the J2SE `HttpURLConnection.setInstanceFollowRedirects(boolean)` method is that redirection is only permitted beween identical protocols (for instance HTTP->HTTP, but not HTTP->HTTPS), see http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4620571. This is for security reasons, but considerations of the same arguments could reasonably lead to weaker restrictions.

      Parameters:
        `fromProto` - protocol part of source URL
        `toProto` - protocol part of destination URL
      See Also:
        `URL.getProtocol()`

    - #### getRedirectUrl

          public java.net.URL getRedirectUrl(java.net.URLConnection conn)
                                      throws java.io.IOException

      Returns a URL to which connections should be redirected from a supplied URL connection, according to this redirector's policy.
      Parameters:
        `conn` - URL connection; will be connected if it is not already
      Returns:
        URL to which requests should be redirected if any; otherwise null
      Throws:
        `java.io.IOException` - if there is a problem with the redirection (for instance missing Location header)

    - #### createStandardInstance

          public static Redirector createStandardInstance(int[] redirectCodes)

      Returns an instance that redirects on a given list of 3xx codes. If the supplied list is empty, no redirection is performed. Redirection between protocols is permitted except from HTTPS to other (less secure) protocols; not this differs from J2SE behaviour.
      Parameters:
        `redirectCodes` - list of zero or more 3xx codes which are to be treated as redirects
      Returns:
        new instance