uk.ac.starlink.auth

## Class UserInterface

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

-     public abstract class UserInterface
      extends java.lang.Object

  Abstraction via which authentication classes can acquire credentials from the user.
  Since:
    15 Jun 2020

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static UserInterface` | `CLI` Command-line instance.
    `static UserInterface` | `GUI` Instance that uses Swing popup dialogues.
    `static UserInterface` | `NO_AUTH` Instance that will not authenticate.
    `static java.lang.String` | `PASSWORD_PROP` Name of password system property for headless UI instance ("auth.password").
    `static java.lang.String` | `USERNAME_PROP` Name of username system property for headless UI instance ("auth.username").

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `UserInterface()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract boolean` | `canRetry()` Indicates whether there is any point in repeated attempts to acquire credentials from the user.
    `static javax.swing.JComponent` | `createAuthPanel(java.lang.String[] msgLines, javax.swing.JTextField userField, javax.swing.JPasswordField passField)` Places the components for acquiring username and password.
    `static UserInterface` | `createFixed(java.lang.String username, java.lang.String password)` Returns a headless implementation with a fixed user name and password supplied as strings.
    `static UserInterface` | `createFixed(UserPass userpass)` Returns a headless implementation with a fixed username+password object.
    `java.awt.Component` | `getParent()` Returns the GUI component to which this UI is subordinate.
    `static UserInterface` | `getPropertiesUi()` Returns a headless UI that takes username and password from the system properties `USERNAME_PROP` and `PASSWORD_PROP` respectively, if both properties are set.
    `static UserInterface` | `getPropertiesUi(java.lang.String userProp, java.lang.String passProp)` Returns a headless UI that takes username and password from two named System Properties.
    `abstract void` | `message(java.lang.String[] lines)` Sends a message to the user.
    `abstract UserPass` | `readUserPassword(java.lang.String[] msgLines)` Returns a username/password pair, or null if the user declines to supply one.
    `void` | `setParent(java.awt.Component parent)` Sets a GUI component to which this UI is subordinate.

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

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

- - ### Field Detail

    - #### CLI

          public static final UserInterface CLI

      Command-line instance.

    - #### GUI

          public static final UserInterface GUI

      Instance that uses Swing popup dialogues.

    - #### NO_AUTH

          public static final UserInterface NO_AUTH

      Instance that will not authenticate.

    - #### USERNAME_PROP

          public static final java.lang.String USERNAME_PROP

      Name of username system property for headless UI instance ("auth.username").
      See Also:
        Constant Field Values

    - #### PASSWORD_PROP

          public static final java.lang.String PASSWORD_PROP

      Name of password system property for headless UI instance ("auth.password").
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### UserInterface

          public UserInterface()

  - ### Method Detail

    - #### readUserPassword

          public abstract UserPass readUserPassword(java.lang.String[] msgLines)

      Returns a username/password pair, or null if the user declines to supply one.
      Parameters:
        `msgLines` - message to output to the user first
      Returns:
        credentials, or null if the user declines

    - #### message

          public abstract void message(java.lang.String[] lines)

      Sends a message to the user. In the case of a GUI this will typically provoke a popup window, so it should not be used gratitously.
      Parameters:
        `lines` - message to pass to the user

    - #### canRetry

          public abstract boolean canRetry()

      Indicates whether there is any point in repeated attempts to acquire credentials from the user. In an interactive context, this would typically return true, but in a headless context with preset credentials that will not change between invocations, it should return false.
      Returns:
        true if repeated requests may return different results

    - #### setParent

          public void setParent(java.awt.Component parent)

      Sets a GUI component to which this UI is subordinate. For non-GUI implementations, this method is likely to have no effect, but for GUI-based implementations, it can be used to manage the ownership of popup dialogues.
      Parameters:
        `parent` - new parent component, may be null

    - #### getParent

          public java.awt.Component getParent()

      Returns the GUI component to which this UI is subordinate. Likely to be irrelevant for non-GUI implementations.
      Returns:
        parent component, may be null

    - #### createFixed

          public static UserInterface createFixed(java.lang.String username,
                                                  java.lang.String password)

      Returns a headless implementation with a fixed user name and password supplied as strings.
      Parameters:
        `username` - username
        `password` - password
      Returns:
        headless instance

    - #### createFixed

          public static UserInterface createFixed(UserPass userpass)

      Returns a headless implementation with a fixed username+password object.
      Parameters:
        `userpass` - credentials object
      Returns:
        headless instance

    - #### getPropertiesUi

          public static UserInterface getPropertiesUi()

      Returns a headless UI that takes username and password from the system properties `USERNAME_PROP` and `PASSWORD_PROP` respectively, if both properties are set.

      If the first character of either property value is "@", the remainder is interpreted as a filename containing the value.

      Use the result of this method with care, since it risks leaking credentials to sites for which they are not intended.

      This is a shortcut for `getPropertiesUi`(`USERNAME_PROP`, `PASSWORD_PROP`).

      Returns:
        new headless UserInterface instance, or null if not both properties are set

    - #### getPropertiesUi

          public static UserInterface getPropertiesUi(java.lang.String userProp,
                                                      java.lang.String passProp)

      Returns a headless UI that takes username and password from two named System Properties. If the system properties, read at the time of this invocation, have not been defined, then null is returned.

      If the first character of either property value is "@", the remainder is interpreted as a filename containing the value.

      Use the result of this method with care, since it risks leaking credentials to sites for which they are not intended.

      Parameters:
        `userProp` - system property name for acquiring username
        `passProp` - system property name for acquiring password
      Returns:
        new headless UserInterface instance, or null if not both properties are set

    - #### createAuthPanel

          public static javax.swing.JComponent createAuthPanel(java.lang.String[] msgLines,
                                                               javax.swing.JTextField userField,
                                                               javax.swing.JPasswordField passField)

      Places the components for acquiring username and password.
      Parameters:
        `msgLines` - message to display to user
        `userField` - field for username
        `passField` - field for password