Module org.hsqldb
Package org.hsqldb.auth

## Class AuthBeanMultiplexer

- java.lang.Object
- - org.hsqldb.auth.AuthBeanMultiplexer

-     public class AuthBeanMultiplexer
      extends java.lang.Object

  This class provides a method which can be used directly as a HyperSQL static Java function method. Manages a set of AuthFunctionBean implementations
  Since:
    2.0.1
  Author:
    Blaine Simpson (blaine dot simpson at admc dot com)

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static java.sql.Array` | `authenticate​(java.lang.String database, java.lang.String user, java.lang.String password)` | HyperSQL Java Function Method.
    `void` | `clear()` | Clear the set of AuthFunctionBeans
    `static AuthBeanMultiplexer` | `getSingleton()` |
    `void` | `setAuthFunctionBean​(java.lang.String dbName, AuthFunctionBean authFunctionBean)` | This is not an "adder" function, but a "setter" function for the specified dbName , so do not use this to add to a database's FunctionBeans, but to assign ths single given AuthFunctionBean as the specified database's authenticator.
    `void` | `setAuthFunctionBean​(java.sql.Connection c, AuthFunctionBean authFunctionBean)` | Exactly the same as setAuthFunctionBeans(String, List) other than taking an open Connection to identify the database.
    `void` | `setAuthFunctionBeans​(java.lang.String dbName, java.util.List<AuthFunctionBean> authFunctionBeans)` | This is not an "adder" function, but a "setter" function for the specified dbName , so do not use this to add to a database's FunctionBeans, but to assign the entire list for that database.
    `void` | `setAuthFunctionBeans​(java.sql.Connection c, java.util.List<AuthFunctionBean> authFunctionBeans)` | Wrapper for `setAuthFunctionBeans(String, List<AuthFunctionBean>)`
    `void` | `setAuthFunctionBeans​(java.util.Map<java.lang.String,​java.util.List<AuthFunctionBean>> authFunctionBeanMap)` | Primary purpose of this class is to manage this static map.

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

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

- - ### Method Detail

    - #### getSingleton

          public static AuthBeanMultiplexer getSingleton()

    - #### clear

          public void clear()

      Clear the set of AuthFunctionBeans

    - #### setAuthFunctionBeans

          public void setAuthFunctionBeans​(java.util.Map<java.lang.String,​java.util.List<AuthFunctionBean>> authFunctionBeanMap)

      Primary purpose of this class is to manage this static map. From dbNames to ordered-lists-of-AuthFunctionBeans. This is not an "adder" function, but a "setter" function, so do not use this to add to a partial set, but to assign the entire set.

      The given entries are copied, to limit side-effects and concurrency issues.

    - #### setAuthFunctionBeans

          public void setAuthFunctionBeans​(java.sql.Connection c,
                                           java.util.List<AuthFunctionBean> authFunctionBeans)
                                    throws java.sql.SQLException

      Wrapper for `setAuthFunctionBeans(String, List<AuthFunctionBean>)`
      Parameters:
        `c` - An open Connection to the desired database.
      Throws:
        `java.sql.SQLException` - if failed to obtain unique name from given Connection.

    - #### setAuthFunctionBeans

          public void setAuthFunctionBeans​(java.lang.String dbName,
                                           java.util.List<AuthFunctionBean> authFunctionBeans)

      This is not an "adder" function, but a "setter" function for the specified dbName , so do not use this to add to a database's FunctionBeans, but to assign the entire list for that database.

      The given entries are copied, to limit side-effects and concurrency issues.

      Use this method instead of setAuthFunctionBean(String, AuthFunctionBean) in order to set up multiple authenticators for a single database for redundancy purposes.

      See Also:
        `setAuthFunctionBeans(Map)`, `setAuthFunctionBean(String, AuthFunctionBean)`

    - #### setAuthFunctionBean

          public void setAuthFunctionBean​(java.sql.Connection c,
                                          AuthFunctionBean authFunctionBean)
                                   throws java.sql.SQLException

      Exactly the same as setAuthFunctionBeans(String, List) other than taking an open Connection to identify the database.
      Throws:
        `java.sql.SQLException`

    - #### setAuthFunctionBean

          public void setAuthFunctionBean​(java.lang.String dbName,
                                          AuthFunctionBean authFunctionBean)

      This is not an "adder" function, but a "setter" function for the specified dbName , so do not use this to add to a database's FunctionBeans, but to assign ths single given AuthFunctionBean as the specified database's authenticator.

      To set up multiple authenticators for a single database for redundancy purposes, use the method setAuthFunctionBeans(String, List) instead.

      See Also:
        `setAuthFunctionBeans(String, List)`

    - #### authenticate

          public static java.sql.Array authenticate​(java.lang.String database,
                                                    java.lang.String user,
                                                    java.lang.String password)
                                             throws java.lang.Exception

      HyperSQL Java Function Method.

      Registered AuthFunctionBeans matching the specified database and password will be tried in order.

      1. If the AuthFunctionBean being tried throws a non-runtime Exception, then that RuntimeException is passed through (re-thrown), resulting in a SQLException for the authenticating application.
      2. If the AuthFunctionBean being tried doesn't throw anything, then the return value is passed through (returned) and HyperSQL will allow access and set roles according to HyperSQL's authentication function contract.
      3. If the AuthFunctionBean being tried throws a RuntimeException, then the next AuthFunctionBean in turn will be tried. If all matching AuthFunctionBeans throw RuntimeExceptions, then the first RuntimeException that was thrown will be passed through (re-thrown), resulting in a SQLException for the authenticating application.
      4. If there are no AuthFunctionBeans registered for the specified dbName, then this method will throw an IllegalArgumentException, resulting in a SQLException for the authenticating application.
      Returns:
        Null or java.sql.Array to indicate successful authentication according to the contract for HyperSQL authentication functions.
      Throws:
        `java.lang.IllegalArgumentException` - if no AuthFunctionBean has been set for specified dbName.
        `java.lang.RuntimeException` - if all matching AuthFunctionBeans threw RuntimeExceptions. (This indicates that no matching AuthFunctionBean functioned properly, not that authentication was purposefully denied by any AuthFunctionBean).
        `java.lang.Exception` - (non-runtime). A matching AuthFunctionBean threw this Exception.
      See Also:
        "HyperSQL User Guide, System Management chapter, Authentication Settings subsection."