# Class UserInterface

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

public abstract class UserInterface extends Object
Abstraction via which authentication classes can acquire credentials from the user.

Since:
  15 Jun 2020
Author:
  Mark Taylor

## Field Summary

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

## Constructor Summary

Constructors
Constructor
Description
`UserInterface()`

## Method Summary

Modifier and Type
Method
Description
`abstract boolean`
`canRetry()`
Indicates whether there is any point in repeated attempts to acquire credentials from the user.
`static JComponent`
`createAuthPanel(String[] msgLines, JTextField userField, JPasswordField passField)`
Places the components for acquiring username and password.
`static UserInterface`
`createFixed(String username, 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.
`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(String userProp, String passProp)`
Returns a headless UI that takes username and password from two named System Properties.
`abstract void`
`message(String[] lines)`
Sends a message to the user.
`abstract UserPass`
`readUserPassword(String[] msgLines)`
Returns a username/password pair, or null if the user declines to supply one.
`void`
`setParent(Component parent)`
Sets a GUI component to which this UI is subordinate.

### Methods inherited from class Object

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

## Field Details

### 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 String USERNAME_PROP
Name of username system property for headless UI instance ("auth.username").

See Also:
  - Constant Field Values

### PASSWORD_PROP

public static final String PASSWORD_PROP
Name of password system property for headless UI instance ("auth.password").

See Also:
  - Constant Field Values

## Constructor Details

### UserInterface

public UserInterface()

## Method Details

### readUserPassword

public abstract UserPass readUserPassword(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(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(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 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(String username, 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(String userProp, 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 JComponent createAuthPanel(String[] msgLines, JTextField userField, 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