tigase.db.jdbc

## Class TigaseCustomAuth

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

- All Implemented Interfaces:
    AuthRepository

      public class TigaseCustomAuth
      extends Object
      implements AuthRepository

  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
  Version:
    $Rev$
  Author:
    Artur Hefczyc

- - ### Field Summary

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

    - ### 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, USERNAME_KEY`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TigaseCustomAuth()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addUser(tigase.xmpp.BareJID user, String password)` Describe `addUser` method here.
    `boolean` | `digestAuth(tigase.xmpp.BareJID user, String digest, String id, String alg)` Deprecated.
    `protected String` | `getParamWithDef(Map<String,String> params, String key, String def)`
    `String` | `getResourceUri()` Method description
    `long` | `getUsersCount()` `getUsersCount` method is thread safe.
    `long` | `getUsersCount(String domain)` Method description
    `void` | `initRepository(String connection_str, Map<String,String> params)` Describe `initRepository` method here.
    `void` | `logout(tigase.xmpp.BareJID user)` Method description
    `boolean` | `otherAuth(Map<String,Object> props)` Describe `otherAuth` method here.
    `boolean` | `plainAuth(tigase.xmpp.BareJID user, String password)` Deprecated.
    `void` | `queryAuth(Map<String,Object> authProps)` Describe `queryAuth` method here.
    `void` | `removeUser(tigase.xmpp.BareJID user)` Describe `removeUser` method here.
    `void` | `updatePassword(tigase.xmpp.BareJID user, String password)` Describe `updatePassword` method here.

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

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

- - ### Field Detail

    - #### 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_USERS_COUNT_KEY

          public static final String DEF_USERS_COUNT_KEY

      Field description
      See Also:
        Constant Field Values

    - #### DEF_USERS_DOMAIN_COUNT_KEY

          public static final String DEF_USERS_DOMAIN_COUNT_KEY

      Field description
      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

      Field description
      See Also:
        Constant Field Values

    - #### DEF_ADDUSER_QUERY

          public static final String DEF_ADDUSER_QUERY

      Field description
      See Also:
        Constant Field Values

    - #### DEF_DELUSER_QUERY

          public static final String DEF_DELUSER_QUERY

      Field description
      See Also:
        Constant Field Values

    - #### DEF_GETPASSWORD_QUERY

          public static final String DEF_GETPASSWORD_QUERY

      Field description
      See Also:
        Constant Field Values

    - #### DEF_UPDATEPASSWORD_QUERY

          public static final String DEF_UPDATEPASSWORD_QUERY

      Field description
      See Also:
        Constant Field Values

    - #### DEF_USERLOGIN_QUERY

          public static final String DEF_USERLOGIN_QUERY

      Field description
      See Also:
        Constant Field Values

    - #### DEF_USERLOGOUT_QUERY

          public static final String DEF_USERLOGOUT_QUERY

      Field description
      See Also:
        Constant Field Values

    - #### DEF_USERS_COUNT_QUERY

          public static final String DEF_USERS_COUNT_QUERY

      Field description
      See Also:
        Constant Field Values

    - #### DEF_USERS_DOMAIN_COUNT_QUERY

          public static final String DEF_USERS_DOMAIN_COUNT_QUERY

      Field description
      See Also:
        Constant Field Values

    - #### DEF_NONSASL_MECHS

          public static final String DEF_NONSASL_MECHS

      Field description
      See Also:
        Constant Field Values

    - #### DEF_SASL_MECHS

          public static final String DEF_SASL_MECHS

      Field description
      See Also:
        Constant Field Values

    - #### SP_STARTS_WITH

          public static final String SP_STARTS_WITH

      Field description
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### TigaseCustomAuth

          public TigaseCustomAuth()

  - ### Method Detail

    - #### addUser

          public void addUser(tigase.xmpp.BareJID user,
                     String password)
                       throws UserExistsException,
                              TigaseDBException

      Describe `addUser` method here.
      Specified by:
        `addUser` in interface `AuthRepository`
      Parameters:
        `user` - a `String` value
        `password` - a `String` value
      Throws:
        `UserExistsException` - if an error occurs
        `TigaseDBException` - if an error occurs

    - #### digestAuth

          @Deprecated
          public boolean digestAuth(tigase.xmpp.BareJID user,
                                      String digest,
                                      String id,
                                      String alg)
                             throws UserNotFoundException,
                                    TigaseDBException,
                                    AuthorizationException

      Deprecated.
      Describe `digestAuth` method here.
      Specified by:
        `digestAuth` in interface `AuthRepository`
      Parameters:
        `user` - a `String` value
        `digest` - a `String` value
        `id` - a `String` value
        `alg` - a `String` value
      Returns:
        a `boolean` value
      Throws:
        `UserNotFoundException` - if an error occurs
        `TigaseDBException` - if an error occurs
        `AuthorizationException` - if an error occurs

    - #### getResourceUri

          public String getResourceUri()

      Method description
      Specified by:
        `getResourceUri` in interface `AuthRepository`
      Returns:
        a `String` value of database connection string.

    - #### 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)

      Method description
      Specified by:
        `getUsersCount` in interface `AuthRepository`
      Parameters:
        `domain` -
      Returns:
        a `long` number of registered users in the repository.

    - #### initRepository

          public void initRepository(String connection_str,
                            Map<String,String> params)
                              throws DBInitException

      Describe `initRepository` method here.
      Specified by:
        `initRepository` in interface `AuthRepository`
      Parameters:
        `connection_str` - a `String` value
        `params` -
      Throws:
        `DBInitException` - if an error occurs

    - #### logout

          public void logout(tigase.xmpp.BareJID user)
                      throws UserNotFoundException,
                             TigaseDBException

      Method description
      Specified by:
        `logout` in interface `AuthRepository`
      Parameters:
        `user` -
      Throws:
        `TigaseDBException`
        `UserNotFoundException`

    - #### otherAuth

          public boolean otherAuth(Map<String,Object> props)
                            throws UserNotFoundException,
                                   TigaseDBException,
                                   AuthorizationException

      Describe `otherAuth` method here.
      Specified by:
        `otherAuth` in interface `AuthRepository`
      Parameters:
        `props` - a `Map` value
      Returns:
        a `boolean` value
      Throws:
        `UserNotFoundException` - if an error occurs
        `TigaseDBException` - if an error occurs
        `AuthorizationException` - if an error occurs

    - #### plainAuth

          @Deprecated
          public boolean plainAuth(tigase.xmpp.BareJID user,
                                     String password)
                            throws UserNotFoundException,
                                   TigaseDBException,
                                   AuthorizationException

      Deprecated.
      Describe `plainAuth` method here.
      Specified by:
        `plainAuth` in interface `AuthRepository`
      Parameters:
        `user` - a `String` value
        `password` - a `String` value
      Returns:
        a `boolean` value
      Throws:
        `AuthorizationException`
        `UserNotFoundException` - if an error occurs
        `TigaseDBException` - if an error occurs

    - #### queryAuth

          public void queryAuth(Map<String,Object> authProps)

      Describe `queryAuth` method here.
      Specified by:
        `queryAuth` in interface `AuthRepository`
      Parameters:
        `authProps` - a `Map` value

    - #### removeUser

          public void removeUser(tigase.xmpp.BareJID user)
                          throws UserNotFoundException,
                                 TigaseDBException

      Describe `removeUser` method here.
      Specified by:
        `removeUser` in interface `AuthRepository`
      Parameters:
        `user` - a `String` value
      Throws:
        `UserNotFoundException` - if an error occurs
        `TigaseDBException` - if an error occurs

    - #### updatePassword

          public void updatePassword(tigase.xmpp.BareJID user,
                            String password)
                              throws UserNotFoundException,
                                     TigaseDBException

      Describe `updatePassword` method here.
      Specified by:
        `updatePassword` in interface `AuthRepository`
      Parameters:
        `user` - a `String` value
        `password` - a `String` value
      Throws:
        `TigaseDBException` - if an error occurs
        `UserNotFoundException`

    - #### getParamWithDef

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

Copyright © 2014 "Tigase, Inc.". All rights reserved.