Package tigase.db.jdbc

# Class TigaseCustomAuth

java.lang.Object
tigase.db.AbstractAuthRepositoryWithCredentials
tigase.db.jdbc.TigaseCustomAuth

All Implemented Interfaces:
  `AuthRepository`, `DataSourceAware<DataRepository>`, `Repository`, `RepositoryVersionAware`

Direct Known Subclasses:
  `TigaseSPAuth`

public class TigaseCustomAuth extends AbstractAuthRepositoryWithCredentials implements DataSourceAware<DataRepository>, RepositoryVersionAware
The user authentication connector allows for customized SQL queries to be used. Queries are defined in the configuration file and they can be either plain SQL queries or stored procedures.
If the query starts with characters: `{ call` then the server assumes this is a stored procedure call, otherwise it is executed as a plain SQL query. Each configuration value is stripped from white characters on both ends before processing.
Please don't use semicolon `';'` at the end of the query as many JDBC drivers get confused and the query may not work for unknown obvious reason.
Some queries take arguments. Arguments are marked by question marks `'?'` in the query. Refer to the configuration parameters description for more details about what parameters are expected in each query.
Example configuration.
The first example shows how to put a stored procedure as a query with 2 required parameters.

     add-user-query={ call TigAddUserPlainPw(?, ?) }

The same query with plain SQL parameters instead:

     add-user-query=insert into users (user_id, password) values (?, ?)

Created: Sat Nov 11 22:22:04 2006

Author:
  Artur Hefczyc

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from interface tigase.db.AuthRepository

  `AuthRepository.AccountStatus, AuthRepository.DefaultCredentials, AuthRepository.SingleCredential`

  ## Nested classes/interfaces inherited from interface tigase.db.Repository

  `Repository.Meta, Repository.SchemaId`

  ## Nested classes/interfaces inherited from interface tigase.db.util.RepositoryVersionAware

  `RepositoryVersionAware.SchemaVersion`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `DEF_ACCOUNTSTATUS_KEY`
  `static final String`
  `DEF_ACCOUNTSTATUS_QUERY`
  `static final String`
  `DEF_ACTIVE_USERS_COUNT_KEY`
  `static final String`
  `DEF_ACTIVE_USERS_COUNT_QUERY`
  `static final String`
  `DEF_ADDUSER_KEY`
  Query adding a new user to the database.
  `static final String`
  `DEF_ADDUSER_QUERY`
  `static final String`
  `DEF_CONNVALID_KEY`
  Query executing periodically to ensure active connection with the database.
  `static final String`
  `DEF_DELUSER_KEY`
  Removes a user from the database.
  `static final String`
  `DEF_DELUSER_QUERY`
  `static final String`
  `DEF_DISABLEACCOUNT_KEY`
  Deprecated.
  `static final String`
  `DEF_ENABLEACCOUNT_KEY`
  Deprecated.
  `static final String`
  `DEF_GETPASSWORD_KEY`
  Retrieves user password from the database for given user_id (JID).
  `static final String`
  `DEF_GETPASSWORD_QUERY`
  `static final String`
  `DEF_INITDB_KEY`
  Database initialization query which is run after the server is started.
  `static final String`
  `DEF_INITDB_QUERY`
  `static final String`
  `DEF_LISTDISABLEDACCOUNTS_KEY`
  `static final String`
  `DEF_LISTDISABLEDACCOUNTS_QUERY`
  `static final String`
  `DEF_NONSASL_MECHS`
  `static final String`
  `DEF_NONSASL_MECHS_KEY`
  Comma separated list of NON-SASL authentication mechanisms.
  `static final String`
  `DEF_SASL_MECHS`
  `static final String`
  `DEF_SASL_MECHS_KEY`
  Comma separated list of SASL authentication mechanisms.
  `static final String`
  `DEF_UPDATEACCOUNTSTATUS_KEY`
  `static final String`
  `DEF_UPDATEACCOUNTSTATUS_QUERY`
  `static final String`
  `DEF_UPDATELOGINTIME_KEY`
  `static final String`
  `DEF_UPDATEPASSWORD_KEY`
  Updates (changes) password for a given user_id (JID).
  `static final String`
  `DEF_USERLOGIN_KEY`
  Performs user login.
  `static final String`
  `DEF_USERLOGOUT_KEY`
  This query is called when user logs out or disconnects.
  `static final String`
  `DEF_USERS_COUNT_KEY`
  `static final String`
  `DEF_USERS_COUNT_QUERY`
  `static final String`
  `DEF_USERS_DOMAIN_COUNT_KEY`
  `static final String`
  `DEF_USERS_DOMAIN_COUNT_QUERY`
  `static final String`
  `NO_QUERY`
  `static final String`
  `SP_STARTS_WITH`

  ### Fields inherited from interface tigase.db.AuthRepository

  `DATA_KEY, DIGEST_ID_KEY, DIGEST_KEY, MACHANISM_KEY, PASSWORD_KEY, PROTOCOL_KEY, PROTOCOL_VAL_NONSASL, PROTOCOL_VAL_SASL, REALM_KEY, RESULT_KEY, SERVER_NAME_KEY, USER_ID_KEY`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TigaseCustomAuth()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addUser(BareJID user, String password)`
  `AuthRepository.AccountStatus`
  `getAccountStatus(BareJID user)`
  `long`
  `getActiveUsersCountIn(Duration duration)`
  `Collection<String>`
  `getCredentialIds(BareJID user)`
  `Credentials`
  `getCredentials(BareJID user, String credentialId)`
  `protected String`
  `getParamWithDef(Map<String,String> params, String key, String def)`
  `String`
  `getResourceUri()`
  `getResourceUri` method returns database connection string.
  `long`
  `getUsersCount()`
  `getUsersCount` method is thread safe.
  `long`
  `getUsersCount(String domain)`
  This method is only used by the server statistics component to report number of registered users for given domain.
  `void`
  `initRepository(String connection_str, Map<String,String> params)`
  Deprecated.
  `boolean`
  `isMechanismSupported(String domain, String mechanism)`
  `void`
  `loggedIn(BareJID user)`
  Do some actions on repository, when user logs in.
  `void`
  `logout(BareJID user)`
  `boolean`
  `otherAuth(Map<String,Object> props)`
  `void`
  `queryAuth(Map<String,Object> authProps)`
  `queryAuth` returns mechanisms available for authentication.
  `void`
  `removeCredential(BareJID user, String credentialId)`
  `void`
  `removeUser(BareJID user)`
  `void`
  `setAccountStatus(BareJID user, AuthRepository.AccountStatus value)`
  `void`
  `setDataSource(DataRepository data_repo)`
  Method called to provide class with instance of a data source.
  `void`
  `updateCredential(BareJID user, String credentialId, String password)`
  `void`
  `updatePassword(BareJID user, String password)`

  ### Methods inherited from class tigase.db.AbstractAuthRepositoryWithCredentials

  `getCredentialsDecoder, getCredentialsEncoder, getPassword, setCredentialsCodecs`

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

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

  ### Methods inherited from interface tigase.db.AuthRepository

  `getUsernames, isUserDisabled, setUserDisabled`

  ### Methods inherited from interface tigase.db.util.RepositoryVersionAware

  `getVersion, updateSchema`

- ## Field Details

  - ### DEF_CONNVALID_KEY

    public static final String DEF_CONNVALID_KEY
    Query executing periodically to ensure active connection with the database.
    Takes no arguments.
    Example query:

         select 1

    See Also:
      - Constant Field Values

  - ### DEF_INITDB_KEY

    public static final String DEF_INITDB_KEY
    Database initialization query which is run after the server is started.
    Takes no arguments.
    Example query:

         update tig_users set online_status = 0

    See Also:
      - Constant Field Values

  - ### DEF_ADDUSER_KEY

    public static final String DEF_ADDUSER_KEY
    Query adding a new user to the database.
    Takes 2 arguments: `(user_id (JID), password)`
    Example query:

         insert into tig_users (user_id, user_pw) values (?, ?)

    See Also:
      - Constant Field Values

  - ### DEF_DELUSER_KEY

    public static final String DEF_DELUSER_KEY
    Removes a user from the database.
    Takes 1 argument: `(user_id (JID))`
    Example query:

         delete from tig_users where user_id = ?

    See Also:
      - Constant Field Values

  - ### DEF_GETPASSWORD_KEY

    public static final String DEF_GETPASSWORD_KEY
    Retrieves user password from the database for given user_id (JID).
    Takes 1 argument: `(user_id (JID))`
    Example query:

         select user_pw from tig_users where user_id = ?

    See Also:
      - Constant Field Values

  - ### DEF_UPDATEPASSWORD_KEY

    public static final String DEF_UPDATEPASSWORD_KEY
    Updates (changes) password for a given user_id (JID).
    Takes 2 arguments: `(password, user_id (JID))`
    Example query:

         update tig_users set user_pw = ? where user_id = ?

    See Also:
      - Constant Field Values

  - ### DEF_USERLOGIN_KEY

    public static final String DEF_USERLOGIN_KEY
    Performs user login. Normally used when there is a special SP used for this purpose. This is an alternative way to a method requiring retrieving user password. Therefore at least one of those queries must be defined: `user-login-query` or `get-password-query`.
    If both queries are defined then `user-login-query` is used. Normally this method should be only used with plain text password authentication or sasl-plain.
    The Tigase server expects a result set with user_id to be returned from the query if login is successful and empty results set if the login is unsuccessful.
    Takes 2 arguments: `(user_id (JID), password)`
    Example query:

         select user_id from tig_users where (user_id = ?) AND (user_pw = ?)

    See Also:
      - Constant Field Values

  - ### DEF_USERLOGOUT_KEY

    public static final String DEF_USERLOGOUT_KEY
    This query is called when user logs out or disconnects. It can record that event in the database.
    Takes 1 argument: `(user_id (JID))`
    Example query:

         update tig_users, set online_status = online_status - 1 where user_id = ?

    See Also:
      - Constant Field Values

  - ### DEF_UPDATELOGINTIME_KEY

    public static final String DEF_UPDATELOGINTIME_KEY
    See Also:
      - Constant Field Values

  - ### DEF_USERS_COUNT_KEY

    public static final String DEF_USERS_COUNT_KEY
    See Also:
      - Constant Field Values

  - ### DEF_ACTIVE_USERS_COUNT_KEY

    public static final String DEF_ACTIVE_USERS_COUNT_KEY
    See Also:
      - Constant Field Values

  - ### DEF_USERS_DOMAIN_COUNT_KEY

    public static final String DEF_USERS_DOMAIN_COUNT_KEY
    See Also:
      - Constant Field Values

  - ### DEF_LISTDISABLEDACCOUNTS_KEY

    public static final String DEF_LISTDISABLEDACCOUNTS_KEY
    See Also:
      - Constant Field Values

  - ### DEF_DISABLEACCOUNT_KEY

    @Deprecated public static final String DEF_DISABLEACCOUNT_KEY
    Deprecated.
    See Also:
      - Constant Field Values

  - ### DEF_ENABLEACCOUNT_KEY

    @Deprecated public static final String DEF_ENABLEACCOUNT_KEY
    Deprecated.
    See Also:
      - Constant Field Values

  - ### DEF_UPDATEACCOUNTSTATUS_KEY

    public static final String DEF_UPDATEACCOUNTSTATUS_KEY
    See Also:
      - Constant Field Values

  - ### DEF_ACCOUNTSTATUS_KEY

    public static final String DEF_ACCOUNTSTATUS_KEY
    See Also:
      - Constant Field Values

  - ### DEF_NONSASL_MECHS_KEY

    public static final String DEF_NONSASL_MECHS_KEY
    Comma separated list of NON-SASL authentication mechanisms. Possible mechanisms are: `password` and `digest`. `digest` mechanism can work only with `get-password-query` active and only when password are stored in plain text format in the database.
    See Also:
      - Constant Field Values

  - ### DEF_SASL_MECHS_KEY

    public static final String DEF_SASL_MECHS_KEY
    Comma separated list of SASL authentication mechanisms. Possible mechanisms are all mechanisms supported by Java implementation. The most common are: `PLAIN`, `DIGEST-MD5`, `CRAM-MD5`.
    "Non-PLAIN" mechanisms will work only with the `get-password-query` active and only when passwords are stored in plain text format in the database.
    See Also:
      - Constant Field Values

  - ### NO_QUERY

    public static final String NO_QUERY
    See Also:
      - Constant Field Values

  - ### DEF_INITDB_QUERY

    public static final String DEF_INITDB_QUERY
    See Also:
      - Constant Field Values

  - ### DEF_ADDUSER_QUERY

    public static final String DEF_ADDUSER_QUERY
    See Also:
      - Constant Field Values

  - ### DEF_DELUSER_QUERY

    public static final String DEF_DELUSER_QUERY
    See Also:
      - Constant Field Values

  - ### DEF_GETPASSWORD_QUERY

    public static final String DEF_GETPASSWORD_QUERY
    See Also:
      - Constant Field Values

  - ### DEF_USERS_COUNT_QUERY

    public static final String DEF_USERS_COUNT_QUERY
    See Also:
      - Constant Field Values

  - ### DEF_ACTIVE_USERS_COUNT_QUERY

    public static final String DEF_ACTIVE_USERS_COUNT_QUERY
    See Also:
      - Constant Field Values

  - ### DEF_USERS_DOMAIN_COUNT_QUERY

    public static final String DEF_USERS_DOMAIN_COUNT_QUERY
    See Also:
      - Constant Field Values

  - ### DEF_LISTDISABLEDACCOUNTS_QUERY

    public static final String DEF_LISTDISABLEDACCOUNTS_QUERY
    See Also:
      - Constant Field Values

  - ### DEF_UPDATEACCOUNTSTATUS_QUERY

    public static final String DEF_UPDATEACCOUNTSTATUS_QUERY
    See Also:
      - Constant Field Values

  - ### DEF_ACCOUNTSTATUS_QUERY

    public static final String DEF_ACCOUNTSTATUS_QUERY
    See Also:
      - Constant Field Values

  - ### DEF_NONSASL_MECHS

    public static final String DEF_NONSASL_MECHS
    See Also:
      - Constant Field Values

  - ### DEF_SASL_MECHS

    public static final String DEF_SASL_MECHS
    See Also:
      - Constant Field Values

  - ### SP_STARTS_WITH

    public static final String SP_STARTS_WITH
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### TigaseCustomAuth

    public TigaseCustomAuth()

- ## Method Details

  - ### addUser

    public void addUser(BareJID user, String password) throws TigaseDBException
    Specified by:
      `addUser` in interface `AuthRepository`
    Throws:
      `TigaseDBException`

  - ### getAccountStatus

    public AuthRepository.AccountStatus getAccountStatus(BareJID user) throws TigaseDBException
    Specified by:
      `getAccountStatus` in interface `AuthRepository`
    Throws:
      `TigaseDBException`

  - ### getCredentials

    public Credentials getCredentials(BareJID user, String credentialId) throws TigaseDBException
    Specified by:
      `getCredentials` in interface `AuthRepository`
    Throws:
      `TigaseDBException`

  - ### getParamWithDef

    protected String getParamWithDef(Map<String,String> params, String key, String def)

  - ### getResourceUri

    public String getResourceUri()
    Description copied from interface: `AuthRepository`
    `getResourceUri` method returns database connection string.
    Specified by:
      `getResourceUri` in interface `AuthRepository`
    Returns:
      a `String` value of database connection string.

  - ### getCredentialIds

    public Collection<String> getCredentialIds(BareJID user) throws TigaseDBException
    Specified by:
      `getCredentialIds` in interface `AuthRepository`
    Throws:
      `TigaseDBException`

  - ### getActiveUsersCountIn

    public long getActiveUsersCountIn(Duration duration)
    Specified by:
      `getActiveUsersCountIn` in interface `AuthRepository`
    Parameters:
      `duration` - Time range within which active users should be counted. Method is only used by statistics.
    Returns:
      number of active users in required range

  - ### getUsersCount

    public long getUsersCount()
    `getUsersCount` method is thread safe. It uses local variable for storing `Statement`.
    Specified by:
      `getUsersCount` in interface `AuthRepository`
    Returns:
      a `long` number of user accounts in database.

  - ### getUsersCount

    public long getUsersCount(String domain)
    Description copied from interface: `AuthRepository`
    This method is only used by the server statistics component to report number of registered users for given domain.
    Specified by:
      `getUsersCount` in interface `AuthRepository`
    Parameters:
      `domain` - for which get the statistics
    Returns:
      a `long` number of registered users in the repository.

  - ### initRepository

    @Deprecated public void initRepository(String connection_str, Map<String,String> params) throws DBInitException
    Deprecated.
    Description copied from interface: `Repository`
    Method is deprecated and should not be user any more.
    The method is called to initialize the data repository. Depending on the implementation all the initialization parameters can be passed either via `resource_uri` parameter as the database connection string or via `params` map if the required repository parameters are more complex or both.
    Specified by:
      `initRepository` in interface `Repository`
    Parameters:
      `connection_str` - value in most cases representing the database connection string.
      `params` - is a `Map` with repository properties necessary to initialize and perform all the functions. The initialization parameters are implementation dependent.
    Throws:
      `DBInitException` - if there was an error during repository initialization. Some implementations, though, perform so called lazy initialization so even though there is a problem with the underlying repository it may not be signaled through this method call.

  - ### isMechanismSupported

    public boolean isMechanismSupported(String domain, String mechanism)
    Specified by:
      `isMechanismSupported` in interface `AuthRepository`
    Overrides:
      `isMechanismSupported` in class `AbstractAuthRepositoryWithCredentials`

  - ### loggedIn

    public void loggedIn(BareJID user) throws TigaseDBException
    Description copied from interface: `AuthRepository`
    Do some actions on repository, when user logs in. (for example update `last_login_time`)
    Specified by:
      `loggedIn` in interface `AuthRepository`
    Parameters:
      `user` - JID of logged user.
    Throws:
      `TigaseDBException` - if an error occurs

  - ### logout

    public void logout(BareJID user) throws TigaseDBException
    Specified by:
      `logout` in interface `AuthRepository`
    Throws:
      `TigaseDBException`

  - ### otherAuth

    public boolean otherAuth(Map<String,Object> props) throws TigaseDBException, AuthorizationException
    Specified by:
      `otherAuth` in interface `AuthRepository`
    Throws:
      `TigaseDBException`
      `AuthorizationException`

  - ### queryAuth

    public void queryAuth(Map<String,Object> authProps)
    Description copied from interface: `AuthRepository`
    `queryAuth` returns mechanisms available for authentication.
    Specified by:
      `queryAuth` in interface `AuthRepository`
    Parameters:
      `authProps` - a `Map` value with parameters for authentication.

  - ### removeCredential

    public void removeCredential(BareJID user, String credentialId) throws TigaseDBException
    Specified by:
      `removeCredential` in interface `AuthRepository`
    Throws:
      `TigaseDBException`

  - ### removeUser

    public void removeUser(BareJID user) throws TigaseDBException
    Specified by:
      `removeUser` in interface `AuthRepository`
    Throws:
      `TigaseDBException`

  - ### setAccountStatus

    public void setAccountStatus(BareJID user, AuthRepository.AccountStatus value) throws TigaseDBException
    Specified by:
      `setAccountStatus` in interface `AuthRepository`
    Throws:
      `TigaseDBException`

  - ### setDataSource

    public void setDataSource(DataRepository data_repo) throws DBInitException
    Description copied from interface: `DataSourceAware`
    Method called to provide class with instance of a data source.
    Specified by:
      `setDataSource` in interface `DataSourceAware<DataRepository>`
    Throws:
      `DBInitException`

  - ### updateCredential

    public void updateCredential(BareJID user, String credentialId, String password) throws TigaseDBException
    Specified by:
      `updateCredential` in interface `AuthRepository`
    Throws:
      `TigaseDBException`

  - ### updatePassword

    public void updatePassword(BareJID user, String password) throws TigaseDBException
    Specified by:
      `updatePassword` in interface `AuthRepository`
    Throws:
      `TigaseDBException`