Package tigase.xmpp

## Class RepositoryAccess

- java.lang.Object
- - tigase.xmpp.RepositoryAccess

- Direct Known Subclasses:
    `XMPPResourceConnection`

      public abstract class RepositoryAccess
      extends java.lang.Object

  Describe class RepositoryAccess here.
  Created: Tue Oct 24 10:38:41 2006
  Author:
    Artur Hefczyc

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected AuthRepository` | `authRepo` |
    `protected Authorization` | `authState` | Current authorization state - initialy session i `NOT_AUTHORIZED`.
    `protected VHostItem` | `domain` |
    `protected boolean` | `is_anonymous` |
    `protected static java.lang.String` | `NO_ACCESS_TO_REP_MSG` |
    `protected static java.lang.String` | `NOT_AUTHORIZED_MSG` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `RepositoryAccess​(UserRepository rep, AuthRepository auth)` | Creates a new `RepositoryAccess` instance.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addDataList​(java.lang.String subnode, java.lang.String key, java.lang.String[] list)` |
    `void` | `addOfflineDataList​(java.lang.String subnode, java.lang.String key, java.lang.String[] list)` |
    `void` | `addPublicDataList​(java.lang.String subnode, java.lang.String key, java.lang.String[] list)` |
    `Authorization` | `changeRegistration​(java.lang.String name_param, java.lang.String pass_param, java.util.Map<java.lang.String,​java.lang.String> registr_params)` |
    `java.lang.String` | `getAuthenticationToken​(java.lang.String xmpp_sessionId)` |
    `Authorization` | `getAuthState()` | Gets the value of authState
    `abstract BareJID` | `getBareJID()` | Returns user JID but without resource part.
    `java.lang.String` | `getData​(java.lang.String subnode, java.lang.String key, java.lang.String def)` | `getData` method is a twin sister (brother?)
    `java.lang.String[]` | `getDataGroups​(java.lang.String subnode)` | This method retrieves list of all direct subnodes for given node.
    `java.lang.String[]` | `getDataKeys​(java.lang.String subnode)` | This method returns all data keys available in permanent storage in given node.
    `java.lang.String[]` | `getDataList​(java.lang.String subnode, java.lang.String key)` | This method allows to retrieve list of values associated with one key.
    `VHostItem` | `getDomain()` |
    `JID` | `getDomainAsJID()` |
    `java.lang.String` | `getOfflineData​(java.lang.String subnode, java.lang.String key, java.lang.String def)` |
    `java.lang.String[]` | `getOfflineDataList​(java.lang.String subnode, java.lang.String key)` |
    `java.lang.String` | `getPublicData​(java.lang.String subnode, java.lang.String key, java.lang.String def)` |
    `java.lang.String[]` | `getPublicDataList​(java.lang.String subnode, java.lang.String key)` |
    `abstract java.lang.String` | `getUserName()` |
    `boolean` | `isAnonymous()` |
    `boolean` | `isAuthorized()` | This method allows you test this session if it already has been authorized.
    `protected abstract void` | `login()` |
    `void` | `logout()` |
    `void` | `queryAuth​(java.util.Map<java.lang.String,​java.lang.Object> authProps)` |
    `void` | `removeData​(java.lang.String subnode, java.lang.String key)` |
    `void` | `removeDataGroup​(java.lang.String subnode)` | Removes the last data node given in subnode path as parameter to this method.
    `void` | `removeOfflineData​(java.lang.String subnode, java.lang.String key)` |
    `void` | `removeOfflineDataGroup​(java.lang.String subnode)` |
    `void` | `removePublicData​(java.lang.String subnode, java.lang.String key)` |
    `void` | `removePublicDataGroup​(java.lang.String subnode)` |
    `void` | `setData​(java.lang.String subnode, java.lang.String key, java.lang.String value)` | This method stores given data in permanent storage in given point of hierarchy of data base.
    `void` | `setDataList​(java.lang.String subnode, java.lang.String key, java.lang.String[] list)` | This method allows to store list of values under one key ID reference.
    `void` | `setDomain​(VHostItem domain)` |
    `void` | `setOfflineData​(java.lang.String subnode, java.lang.String key, java.lang.String value)` |
    `void` | `setOfflineDataList​(java.lang.String subnode, java.lang.String key, java.lang.String[] list)` |
    `void` | `setPublicData​(java.lang.String subnode, java.lang.String key, java.lang.String value)` |
    `void` | `setPublicDataList​(java.lang.String subnode, java.lang.String key, java.lang.String[] list)` |
    `void` | `setRegistration​(java.lang.String name_param, java.lang.String pass_param, java.util.Map<java.lang.String,​java.lang.String> registr_params)` |
    `Authorization` | `unregister​(java.lang.String name_param)` | Deprecated.

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

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

- - ### Field Detail

    - #### NO_ACCESS_TO_REP_MSG

          protected static final java.lang.String NO_ACCESS_TO_REP_MSG

      See Also:
        Constant Field Values

    - #### NOT_AUTHORIZED_MSG

          protected static final java.lang.String NOT_AUTHORIZED_MSG

      See Also:
        Constant Field Values

    - #### authRepo

          protected AuthRepository authRepo

    - #### authState

          protected Authorization authState

      Current authorization state - initialy session i `NOT_AUTHORIZED`. It becomes `AUTHORIZED`

    - #### domain

          protected VHostItem domain

    - #### is_anonymous

          protected boolean is_anonymous

  - ### Constructor Detail

    - #### RepositoryAccess

          public RepositoryAccess​(UserRepository rep,
                                  AuthRepository auth)

      Creates a new `RepositoryAccess` instance.

  - ### Method Detail

    - #### addDataList

          public void addDataList​(java.lang.String subnode,
                                  java.lang.String key,
                                  java.lang.String[] list)
                           throws NotAuthorizedException,
                                  TigaseDBException

      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### addOfflineDataList

          public void addOfflineDataList​(java.lang.String subnode,
                                         java.lang.String key,
                                         java.lang.String[] list)
                                  throws NotAuthorizedException,
                                         TigaseDBException

      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### addPublicDataList

          public void addPublicDataList​(java.lang.String subnode,
                                        java.lang.String key,
                                        java.lang.String[] list)
                                 throws NotAuthorizedException,
                                        TigaseDBException

      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### logout

          public void logout()
                      throws NotAuthorizedException

      Throws:
        `NotAuthorizedException`

    - #### queryAuth

          public void queryAuth​(java.util.Map<java.lang.String,​java.lang.Object> authProps)
                         throws TigaseDBException

      Throws:
        `TigaseDBException`

    - #### changeRegistration

          public Authorization changeRegistration​(java.lang.String name_param,
                                                  java.lang.String pass_param,
                                                  java.util.Map<java.lang.String,​java.lang.String> registr_params)
                                           throws NotAuthorizedException,
                                                  TigaseDBException,
                                                  TigaseStringprepException

      Throws:
        `NotAuthorizedException`
        `TigaseDBException`
        `TigaseStringprepException`

    - #### removeData

          public void removeData​(java.lang.String subnode,
                                 java.lang.String key)
                          throws NotAuthorizedException,
                                 TigaseDBException

      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### removeDataGroup

          public void removeDataGroup​(java.lang.String subnode)
                               throws NotAuthorizedException,
                                      TigaseDBException

      Removes the last data node given in subnode path as parameter to this method. All subnodes are moved as well an all data stored as `(key, val)` are removed as well. Changes are commited to repository immediatelly and there is no way to undo this operation so use it with care.
      Parameters:
        `subnode` - a `String` value of path to node which has to be removed.
      Throws:
        `NotAuthorizedException` - is thrown when session has not been authorized yet and there is no access to permanent storage.
        `TigaseDBException`
      See Also:
        `setData(String, String, String)`

    - #### removeOfflineData

          public void removeOfflineData​(java.lang.String subnode,
                                        java.lang.String key)
                                 throws NotAuthorizedException,
                                        TigaseDBException

      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### removeOfflineDataGroup

          public void removeOfflineDataGroup​(java.lang.String subnode)
                                      throws NotAuthorizedException,
                                             TigaseDBException

      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### removePublicData

          public void removePublicData​(java.lang.String subnode,
                                       java.lang.String key)
                                throws NotAuthorizedException,
                                       TigaseDBException

      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### removePublicDataGroup

          public void removePublicDataGroup​(java.lang.String subnode)
                                     throws NotAuthorizedException,
                                            TigaseDBException

      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### getAuthenticationToken

          public java.lang.String getAuthenticationToken​(java.lang.String xmpp_sessionId)
                                                  throws NotAuthorizedException,
                                                         TigaseDBException

      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### getAuthState

          public final Authorization getAuthState()

      Gets the value of authState
      Returns:
        the value of authState

    - #### getBareJID

          public abstract BareJID getBareJID()
                                      throws NotAuthorizedException

      Returns user JID but without resource part. This is real user ID not session ID. To retrieve session ID - full JID refer to `getJID()` method.
      If session has not been authorized yet this method throws `NotAuthorizedException`.
      Returns:
        a `String` value of user ID - this is user JID without resource part. To obtain full user JID please refer to `getJID` method.
      Throws:
        `NotAuthorizedException` - when this session has not been authorized yet and some parts of user JID are not known yet.

    - #### getData

          public java.lang.String getData​(java.lang.String subnode,
                                          java.lang.String key,
                                          java.lang.String def)
                                   throws NotAuthorizedException,
                                          TigaseDBException

      `getData` method is a twin sister (brother?) of `setData(String, String, String)` method. It allows you to retrieve data stored with above method. It is data stored in given node with given key identifier. If there are no data associated with given key or given node does not exist given `def` value is returned.
      Parameters:
        `subnode` - a `String` value is path to node where pair `(key, value)` are stored.
        `key` - a `String` value of key ID for data to retrieve.
        `def` - a `String` value of default returned if there is nothing stored with given key. `def` can be set to any value you wish to have back as default value or `null` if you want to have back `null` if no data was found. If you set `def` to `null` it has exactly the same effect as if you use `getData(String)` method.
      Returns:
        a `String` value of data found for given key or `def` if there was no data associated with given key.
      Throws:
        `NotAuthorizedException` - is thrown when session has not been authorized yet and there is no access to permanent storage.
        `TigaseDBException`
      See Also:
        `setData(String, String, String)`

    - #### getDataGroups

          public java.lang.String[] getDataGroups​(java.lang.String subnode)
                                           throws NotAuthorizedException,
                                                  TigaseDBException

      This method retrieves list of all direct subnodes for given node. It works in similar way as `ls` unix command or `dir` under DOS/Windows systems.
      Parameters:
        `subnode` - a `String` value of path to node for which we want to retrieve list of direct subnodes.
      Returns:
        a `String[]` array of direct subnodes names for given node.
      Throws:
        `NotAuthorizedException` - is thrown when session has not been authorized yet and there is no access to permanent storage.
        `TigaseDBException`
      See Also:
        `setData(String, String, String)`

    - #### getDataKeys

          public java.lang.String[] getDataKeys​(java.lang.String subnode)
                                         throws NotAuthorizedException,
                                                TigaseDBException

      This method returns all data keys available in permanent storage in given node. There is not though any information what kind of data is stored with this key. This is up to user (developer) to determine what data type is associated with key and what is it's meaning.
      Parameters:
        `subnode` - a `String` value pointing to specific subnode in user reposiotry where data have to be stored.
      Returns:
        a `String[]` array containing all data keys found in given subnode.
      Throws:
        `NotAuthorizedException` - is thrown when session has not been authorized yet and there is no access to permanent storage.
        `TigaseDBException`
      See Also:
        `setData(String, String, String)`

    - #### getDataList

          public java.lang.String[] getDataList​(java.lang.String subnode,
                                                java.lang.String key)
                                         throws NotAuthorizedException,
                                                TigaseDBException

      This method allows to retrieve list of values associated with one key. As it is possible to store many values with one key there are a few methods which provides this functionality. If given key does not exists in given subnode `null` is returned.
      Parameters:
        `subnode` - a `String` value pointing to specific subnode in user reposiotry where data have to be stored.
        `key` - a `String` value of data key ID.
      Returns:
        a `String[]` array containing all values found for given key.
      Throws:
        `NotAuthorizedException` - is thrown when session has not been authorized yet and there is no access to permanent storage.
        `TigaseDBException`
      See Also:
        `setData(String, String, String)`

    - #### getDomain

          public VHostItem getDomain()

    - #### setDomain

          public void setDomain​(VHostItem domain)
                         throws TigaseStringprepException

      Throws:
        `TigaseStringprepException`

    - #### getDomainAsJID

          public JID getDomainAsJID()

    - #### getOfflineData

          public java.lang.String getOfflineData​(java.lang.String subnode,
                                                 java.lang.String key,
                                                 java.lang.String def)
                                          throws NotAuthorizedException,
                                                 TigaseDBException

      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### getOfflineDataList

          public java.lang.String[] getOfflineDataList​(java.lang.String subnode,
                                                       java.lang.String key)
                                                throws NotAuthorizedException,
                                                       TigaseDBException

      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### getPublicData

          public java.lang.String getPublicData​(java.lang.String subnode,
                                                java.lang.String key,
                                                java.lang.String def)
                                         throws NotAuthorizedException,
                                                TigaseDBException

      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### getPublicDataList

          public java.lang.String[] getPublicDataList​(java.lang.String subnode,
                                                      java.lang.String key)
                                               throws NotAuthorizedException,
                                                      TigaseDBException

      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### getUserName

          public abstract java.lang.String getUserName()
                                                throws NotAuthorizedException

      Throws:
        `NotAuthorizedException`

    - #### isAnonymous

          public boolean isAnonymous()

    - #### isAuthorized

          public boolean isAuthorized()

      This method allows you test this session if it already has been authorized. If `true` is returned as method result it means session has already been authorized, if `false` however session is still not authorized.
      Returns:
        a `boolean` value which informs whether this session has been already authorized or not.

    - #### setData

          public void setData​(java.lang.String subnode,
                              java.lang.String key,
                              java.lang.String value)
                       throws NotAuthorizedException,
                              TigaseDBException

      This method stores given data in permanent storage in given point of hierarchy of data base. This method is similar to `setData(String, String)` and differs in one additional parameter which point to user data base subnode where data must be stored. It helps to organize user data in more logical hierarchy.
      User data is kind of tree where you can store data in each tree node. The most relevant sample might be structure like typical file system or XML like or LDAP data base. The first implementation is actually done as XML file to make it easier test application and deploy simple installation where there is no more users than 1000.
      To find out more about user repository refer to `UserRepository` interface for general info and to `XMLRepository` for detailed explanation regarding XML implementation of user repository.
      Thus `subnode` is kind of path to data node. If you specify `null` or empty node data will be stored in root user node. This has exactly the same effect as you call `setData(String, String)`. If you want to store data in different node you must just specify node path like you do it to directory on most file systems:

           /roster

      Or, if you need access deeper node:

           /just/like/path/to/file

      If given node does not yet exist it will be automaticaly created with all nodes in given path so there is no need for developer to perform additional action to create node. There is, however method `removeDataGroup(String)` for deleting specified node as nodes are not automaticaly deleted.
      Parameters:
        `subnode` - a `String` value pointing to specific subnode in user reposiotry where data have to be stored.
        `key` - a `String` value of data key ID.
        `value` - a `String` actual data stored in user repository.
      Throws:
        `NotAuthorizedException` - is thrown when session has not been authorized yet and there is no access to permanent storage.
        `TigaseDBException`
      See Also:
        `removeDataGroup(String)`, `UserRepository`

    - #### setDataList

          public void setDataList​(java.lang.String subnode,
                                  java.lang.String key,
                                  java.lang.String[] list)
                           throws NotAuthorizedException,
                                  TigaseDBException

      This method allows to store list of values under one key ID reference. It is often necessary to keep set of values which can be refered by one key. As an example might be list of groups for specific buddy in roster. There is no actual need to store each group with separate key because we usually need to acces whole list of groups.
      Parameters:
        `subnode` - a `String` value pointing to specific subnode in user reposiotry where data have to be stored.
        `key` - a `String` value of data key ID.
        `list` - a `String[]` keeping list of actual data to be stored in user repository.
      Throws:
        `NotAuthorizedException` - is thrown when session has not been authorized yet and there is no access to permanent storage.
        `TigaseDBException`
      See Also:
        `setData(String, String, String)`

    - #### setOfflineData

          public void setOfflineData​(java.lang.String subnode,
                                     java.lang.String key,
                                     java.lang.String value)
                              throws NotAuthorizedException,
                                     TigaseDBException

      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### setOfflineDataList

          public void setOfflineDataList​(java.lang.String subnode,
                                         java.lang.String key,
                                         java.lang.String[] list)
                                  throws NotAuthorizedException,
                                         TigaseDBException

      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### setPublicData

          public void setPublicData​(java.lang.String subnode,
                                    java.lang.String key,
                                    java.lang.String value)
                             throws NotAuthorizedException,
                                    TigaseDBException

      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### setPublicDataList

          public void setPublicDataList​(java.lang.String subnode,
                                        java.lang.String key,
                                        java.lang.String[] list)
                                 throws NotAuthorizedException,
                                        TigaseDBException

      Throws:
        `NotAuthorizedException`
        `TigaseDBException`

    - #### setRegistration

          public void setRegistration​(java.lang.String name_param,
                                      java.lang.String pass_param,
                                      java.util.Map<java.lang.String,​java.lang.String> registr_params)
                               throws TigaseDBException,
                                      TigaseStringprepException

      Throws:
        `TigaseDBException`
        `TigaseStringprepException`

    - #### unregister

          @Deprecated
          public Authorization unregister​(java.lang.String name_param)
                                   throws NotAuthorizedException,
                                          TigaseDBException,
                                          TigaseStringprepException

      Deprecated.
      Throws:
        `NotAuthorizedException`
        `TigaseDBException`
        `TigaseStringprepException`

    - #### login

          protected abstract void login()