Package tigase.xmpp

# Class RepositoryAccess

java.lang.Object
tigase.xmpp.RepositoryAccess

Direct Known Subclasses:
  `XMPPResourceConnection`

public abstract class RepositoryAccess extends 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 final String`
  `NO_ACCESS_TO_REP_MSG`
  `protected static final String`
  `NOT_AUTHORIZED_MSG`

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addDataList(String subnode, String key, String[] list)`
  `void`
  `addOfflineDataList(String subnode, String key, String[] list)`
  `void`
  `addPublicDataList(String subnode, String key, String[] list)`
  `Authorization`
  `changeRegistration(String name_param, String pass_param, Map<String,String> registr_params)`
  `String`
  `getAuthenticationToken(String xmpp_sessionId)`
  `final Authorization`
  `getAuthState()`
  Gets the value of authState
  `abstract BareJID`
  `getBareJID()`
  Returns user JID but without resource part.
  `String`
  `getData(String subnode, String key, String def)`
  `getData` method is a twin sister (brother?)
  `String[]`
  `getDataGroups(String subnode)`
  This method retrieves list of all direct subnodes for given node.
  `String[]`
  `getDataKeys(String subnode)`
  This method returns all data keys available in permanent storage in given node.
  `String[]`
  `getDataList(String subnode, String key)`
  This method allows to retrieve list of values associated with one key.
  `VHostItem`
  `getDomain()`
  `JID`
  `getDomainAsJID()`
  `String`
  `getOfflineData(String subnode, String key, String def)`
  `String[]`
  `getOfflineDataList(String subnode, String key)`
  `String`
  `getPublicData(String subnode, String key, String def)`
  `String[]`
  `getPublicDataList(String subnode, String key)`
  `abstract 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(Map<String,Object> authProps)`
  `void`
  `removeData(String subnode, String key)`
  `void`
  `removeDataGroup(String subnode)`
  Removes the last data node given in subnode path as parameter to this method.
  `void`
  `removeOfflineData(String subnode, String key)`
  `void`
  `removeOfflineDataGroup(String subnode)`
  `void`
  `removePublicData(String subnode, String key)`
  `void`
  `removePublicDataGroup(String subnode)`
  `void`
  `setData(String subnode, String key, String value)`
  This method stores given data in permanent storage in given point of hierarchy of data base.
  `void`
  `setDataList(String subnode, String key, String[] list)`
  This method allows to store list of values under one key ID reference.
  `void`
  `setDomain(VHostItem domain)`
  `void`
  `setOfflineData(String subnode, String key, String value)`
  `void`
  `setOfflineDataList(String subnode, String key, String[] list)`
  `void`
  `setPublicData(String subnode, String key, String value)`
  `void`
  `setPublicDataList(String subnode, String key, String[] list)`
  `void`
  `setRegistration(String name_param, String pass_param, Map<String,String> registr_params)`
  `Authorization`
  `unregister(String name_param)`
  Deprecated.

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

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

- ## Field Details

  - ### NO_ACCESS_TO_REP_MSG

    protected static final String NO_ACCESS_TO_REP_MSG
    See Also:
      - Constant Field Values

  - ### NOT_AUTHORIZED_MSG

    protected static final 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 Details

  - ### RepositoryAccess

    public RepositoryAccess(UserRepository rep, AuthRepository auth)
    Creates a new `RepositoryAccess` instance.

- ## Method Details

  - ### addDataList

    public void addDataList(String subnode, String key, String[] list) throws NotAuthorizedException, TigaseDBException
    Throws:
      `NotAuthorizedException`
      `TigaseDBException`

  - ### addOfflineDataList

    public void addOfflineDataList(String subnode, String key, String[] list) throws NotAuthorizedException, TigaseDBException
    Throws:
      `NotAuthorizedException`
      `TigaseDBException`

  - ### addPublicDataList

    public void addPublicDataList(String subnode, String key, String[] list) throws NotAuthorizedException, TigaseDBException
    Throws:
      `NotAuthorizedException`
      `TigaseDBException`

  - ### logout

    public void logout() throws NotAuthorizedException
    Throws:
      `NotAuthorizedException`

  - ### queryAuth

    public void queryAuth(Map<String,Object> authProps) throws TigaseDBException
    Throws:
      `TigaseDBException`

  - ### changeRegistration

    public Authorization changeRegistration(String name_param, String pass_param, Map<String,String> registr_params) throws NotAuthorizedException, TigaseDBException, TigaseStringprepException
    Throws:
      `NotAuthorizedException`
      `TigaseDBException`
      `TigaseStringprepException`

  - ### removeData

    public void removeData(String subnode, String key) throws NotAuthorizedException, TigaseDBException
    Throws:
      `NotAuthorizedException`
      `TigaseDBException`

  - ### removeDataGroup

    public void removeDataGroup(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(String subnode, String key) throws NotAuthorizedException, TigaseDBException
    Throws:
      `NotAuthorizedException`
      `TigaseDBException`

  - ### removeOfflineDataGroup

    public void removeOfflineDataGroup(String subnode) throws NotAuthorizedException, TigaseDBException
    Throws:
      `NotAuthorizedException`
      `TigaseDBException`

  - ### removePublicData

    public void removePublicData(String subnode, String key) throws NotAuthorizedException, TigaseDBException
    Throws:
      `NotAuthorizedException`
      `TigaseDBException`

  - ### removePublicDataGroup

    public void removePublicDataGroup(String subnode) throws NotAuthorizedException, TigaseDBException
    Throws:
      `NotAuthorizedException`
      `TigaseDBException`

  - ### getAuthenticationToken

    public String getAuthenticationToken(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 String getData(String subnode, String key, 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 String[] getDataGroups(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 String[] getDataKeys(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 String[] getDataList(String subnode, 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 String getOfflineData(String subnode, String key, String def) throws NotAuthorizedException, TigaseDBException
    Throws:
      `NotAuthorizedException`
      `TigaseDBException`

  - ### getOfflineDataList

    public String[] getOfflineDataList(String subnode, String key) throws NotAuthorizedException, TigaseDBException
    Throws:
      `NotAuthorizedException`
      `TigaseDBException`

  - ### getPublicData

    public String getPublicData(String subnode, String key, String def) throws NotAuthorizedException, TigaseDBException
    Throws:
      `NotAuthorizedException`
      `TigaseDBException`

  - ### getPublicDataList

    public String[] getPublicDataList(String subnode, String key) throws NotAuthorizedException, TigaseDBException
    Throws:
      `NotAuthorizedException`
      `TigaseDBException`

  - ### getUserName

    public abstract 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(String subnode, String key, 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(String subnode, String key, 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(String subnode, String key, String value) throws NotAuthorizedException, TigaseDBException
    Throws:
      `NotAuthorizedException`
      `TigaseDBException`

  - ### setOfflineDataList

    public void setOfflineDataList(String subnode, String key, String[] list) throws NotAuthorizedException, TigaseDBException
    Throws:
      `NotAuthorizedException`
      `TigaseDBException`

  - ### setPublicData

    public void setPublicData(String subnode, String key, String value) throws NotAuthorizedException, TigaseDBException
    Throws:
      `NotAuthorizedException`
      `TigaseDBException`

  - ### setPublicDataList

    public void setPublicDataList(String subnode, String key, String[] list) throws NotAuthorizedException, TigaseDBException
    Throws:
      `NotAuthorizedException`
      `TigaseDBException`

  - ### setRegistration

    public void setRegistration(String name_param, String pass_param, Map<String,String> registr_params) throws TigaseDBException, TigaseStringprepException
    Throws:
      `TigaseDBException`
      `TigaseStringprepException`

  - ### unregister

    @Deprecated public Authorization unregister(String name_param) throws NotAuthorizedException, TigaseDBException, TigaseStringprepException
    Deprecated.
    Throws:
      `NotAuthorizedException`
      `TigaseDBException`
      `TigaseStringprepException`

  - ### login

    protected abstract void login()