SessionControl (${name} ${version} Class documentation)

java.lang.Object
- org.proteios.core.SessionControl

```
public final class SessionControl
extends Object
```
This class handles user sessions. Each instance is thread-safe and can handle a single user at a time. This class is used to create DbControl objects which are needed to access the database.

Version:

2.0

Author:

Nicklas

See Also:
Application.newSessionControl(String, String, String), Application.getSessionControl(String, String)
Last modified

$Date: 2010-04-20 14:02:33 +0200 (Tue, 20 Apr 2010) $

Method Summary

Methods
Modifier and Type	Method and Description
`protected void`	`finalize()` Clean up if a bad client application forgets to logout.
`int`	`getActiveProjectId()` Get the id of the active project, or 0 if no project is active.
`String`	`getChallenge()` Generate a new random string to be used for password encryption in the login method.
`String`	`getClientDefaultSetting(String name)` Get the value of the ClientDefaultSetting with the specified name.
`int`	`getClientId()` Get the id of the `Client` application in use.
`String`	`getExternalClientId()` Get the external id of the `Client` application in use.
`Set<Integer>`	`getFriends()` Get the id of all friends to logged in user.
`Set<Integer>`	`getGroups()` Get the id of all groups where the logged in user is a member, directly or indirectly.
`String`	`getId()` Get the id of this `SessionControl`.
`Set<Integer>`	`getItemKeys()` Get the id of all item keys where the logged in user has a permission.
`int`	`getLoggedInUserId()` Get the id of the logged in user, or 0 if no user is logged in.
`int`	`getLoggedInUserIdAdminInfo()` Get the id of the logged in user, or 0 if no user is logged in.
`int`	`getProjectKeyId()` Get the id of the `ProjectKey` that can be used to share an item to the active project with full permission, or 0 if no project is active or the logged in user only has read permission to the active project.
`Set<Integer>`	`getProjectKeys()` Get the id of all project keys where the logged in user has a permission.
`Set<Integer>`	`getProjects()` Get the id of all projects where the logged in user is a member, directly or indirectly.
`Set<Integer>`	`getRoles()` Get the id of all roles where the logged in user is a member.
`Object`	`getSessionSetting(String name)` Get the value of a session setting with the specified name.
`String`	`getUserClientSetting(String name)` Get the value of the UserClientSetting with the specified name.
`String`	`getUserDefaultSetting(String name)` Get the value of the UserDefaultSetting with the specified name.
`boolean`	`hasPermission(Permission permission, Item itemType)` Check if the logged in user has the specfied permission for all item of the specified type.
`boolean`	`hasSystemPermission(Permission permission)` Check if the logged in user has the specified system permission.
`SessionControl`	`impersonateLogin(int userId, String comment)` Log in as another user.
`boolean`	`isFriendOf(User user)` Check if the logged in user is a friend of of the specified user.
`boolean`	`isImpersonated()` Check if the logged in user was impersonated by another user.
`boolean`	`isLoggedIn()` Checks if a user is logged in or not.
`boolean`	`isLoggedInAdminInfo()` Checks if a user is logged in or not.
`boolean`	`isMemberOf(Group group)` Check if the logged in user is a member, directly or indirectly, of the specified group.
`boolean`	`isMemberOf(Project project)` Check if the logged in user is a member, directly or indirectly, of the specified project.
`boolean`	`isMemberOf(Role role)` Check if the logged in user is a member of the specified role.
`void`	`login(String login, String password, String comment, boolean encryptedPassword)` Log in to Proteios.
`void`	`logout()` Log out of Proteios.
`DbControl`	`newDbControl()` Create a new `DbControl` object for this session.
`void`	`reloadPermissions()` Tell the core to reload the logged in users permission the next time the client application needs to check the permissions.
`void`	`reloadSettings(boolean onlyClientDefaultSettings, boolean saveCurrentUserSettings)` Reloads user- and client-specific settings.
`void`	`setActiveProject(Project project)` Set the active project.
`Object`	`setSessionSetting(String name, Object value)` Set the value of a session setting.
`String`	`setUserClientSetting(String name, String value)` Set the value of a UserClientSetting.
`String`	`setUserDefaultSetting(String name, String value)` Set the value of a UserDefaultSetting.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - getId
```
public String getId()
```
    Get the id of this SessionControl. Use this value for retrieving the object from the Application cache.
    
    Returns:
    The id
    See Also:
    Application.getSessionControl(String,String)
  - getClientId
```
public int getClientId()
```
    Get the id of the Client application in use.
  - getExternalClientId
```
public String getExternalClientId()
```
    Get the external id of the Client application in use.
    
    See Also:
    getClientId()
  - newDbControl
```
public DbControl newDbControl()
                       throws BaseException
```
    Create a new DbControl object for this session.
    
    Returns:
    A DbControl object
    
    Throws:
    
    BaseException - If there is an error
  - getChallenge
```
public String getChallenge()
```
    Generate a new random string to be used for password encryption in the login method. Using encryption prevents that user passwords are sent in clear text between client and server (ie. web browser and web server). The client application should use the challenge as follows:
    1. Calculate the MD5 of the real password
    2. Concatenate this with the challenge with a colon inbetween: MD5:challenge
    3. Calculate the MD5 of the concatenated string. This is the encrypted password, which should be sent to the login method.
    Note! This is not intended as a replacement for SSL encrypted communication. Note! Each call to this method generates a new random challenge.
    Returns:
    A challenge string used to encrypt the password
    See Also:
    login(String, String, String, boolean)
  - login
```
public void login(String login,
         String password,
         String comment,
         boolean encryptedPassword)
           throws ItemNotFoundException,
                  PermissionDeniedException,
                  InvalidPasswordException,
                  BaseException
```
    Log in to Proteios. The method checks that the given login is valid, the password is correct and that the user has USE permission for the client application if one has been specified.
    The encryptedPassword parameter is used if the client application sends the password encrypted. See getChallenge() for information about how to encrypt the password.
    
    Parameters:
    login - The login of the user
    password - The password for the user
    comment - A comment for the login, which will show in the Session
    encryptedPassword - A flag indicating if the password has been encrypted or not
    
    Throws:
    
    ItemNotFoundException - If a user with the specified username is not found
    
    InvalidPasswordException - If the specified password is incorrect
    
    PermissionDeniedException - If the user doesn't have Permission.USE permission for the current client application or if a user is already logged in
    
    BaseException - If there is any other error
    See Also:
    logout(), isLoggedIn(), getLoggedInUserId()
  - impersonateLogin
```
public SessionControl impersonateLogin(int userId,
                              String comment)
                                throws ItemNotFoundException,
                                       PermissionDeniedException,
                                       BaseException
```
    Log in as another user. If this call is successful, you will get a new SessionControl object which is equivalent to a SessionControl where that user logged in by normal means. This method requires that the logged in user has Permission.ACT_AS_ANOTHER_USER permission.
    
    Parameters:
    userId - The id of the user to login as
    comment - A comment that will be placed in the Session information
    
    Returns:
    A new SessionControl object
    
    Throws:
    
    ItemNotFoundException - If no user with the specified id exists
    
    PermissionDeniedException - If the logged in user doesn't have Permission.ACT_AS_ANOTHER_USER permission
    
    BaseException - If there is another error
  - logout
```
public void logout()
            throws BaseException
```
    Log out of Proteios. If the logged in user was impersonated the system will revert to the original user. If no user is logged in this method does nothing. If there are any DbControl objects still open, they will be closed. Changes made to items managed by those DbControl objects will be lost unless the items are connected to a new DbControl object.
    
    Throws:
    
    BaseException - If there is an error
    See Also:
    login(String, String, String, boolean), isLoggedIn(), impersonateLogin(int, String), isImpersonated()
  - isLoggedIn
```
public boolean isLoggedIn()
```
    Checks if a user is logged in or not.
    
    Returns:
    TRUE if a user is logged in, FALSE otherwise.
    See Also:
    login(String, String, String, boolean), logout(), getLoggedInUserId()
  - isLoggedInAdminInfo
```
public boolean isLoggedInAdminInfo()
```
    Checks if a user is logged in or not. Intended for administrative info only, therefore does not update last access time.
    
    Returns:
    TRUE if a user is logged in, FALSE otherwise.
    See Also:
    login(String, String, String, boolean), logout(), getLoggedInUserId()
  - getLoggedInUserId
```
public int getLoggedInUserId()
```
    Get the id of the logged in user, or 0 if no user is logged in. Use User.getById(DbControl, int) to get the User object.
    
    See Also:
    login(String, String, String, boolean), logout(), isLoggedIn()
  - getLoggedInUserIdAdminInfo
```
public int getLoggedInUserIdAdminInfo()
```
    Get the id of the logged in user, or 0 if no user is logged in. Use User.getById(DbControl, int) to get the User object. Intended for administrative info only, therefore does not update last access time.
    
    See Also:
    login(String, String, String, boolean), logout(), isLoggedIn()
  - isImpersonated
```
public boolean isImpersonated()
```
    Check if the logged in user was impersonated by another user.
    
    Returns:
    TRUE or FALSE
    See Also:
    impersonateLogin(int, String)
  - reloadPermissions
```
public void reloadPermissions()
```
    Tell the core to reload the logged in users permission the next time the client application needs to check the permissions.
  - reloadSettings
```
public void reloadSettings(boolean onlyClientDefaultSettings,
                  boolean saveCurrentUserSettings)
                    throws BaseException
```
    Reloads user- and client-specific settings.
    
    Parameters:
    saveCurrentUserSettings - Setting this to TRUE will save the current user-specific settings before reloading them. This parameter is ignored if onlyClientDefaultSettings is true (This feature is current not implemented)
    
    Throws:
    
    BaseException - If the settings cannot be reloaded
  - getActiveProjectId
```
public int getActiveProjectId()
```
    Get the id of the active project, or 0 if no project is active. Use Project.getById(DbControl, int) to get the Project object.
    
    See Also:
    setActiveProject(Project)
  - setActiveProject
```
public void setActiveProject(Project project)
                      throws PermissionDeniedException,
                             BaseException
```
    Set the active project. When a project is active queries will by default only load items shared to the that project, and new Shareable items will automatically be shared to the active project with delete permission. The active project doesn't affect already existing items.
    
    Parameters:
    project - The project to make active
    
    Throws:
    
    PermissionDeniedException - If the logged in user doesn't have Permission.USE permission for the project
    
    BaseException - If there is another error
    See Also:
    getActiveProjectId()
  - getProjectKeyId
```
public int getProjectKeyId()
```
    Get the id of the ProjectKey that can be used to share an item to the active project with full permission, or 0 if no project is active or the logged in user only has read permission to the active project. Use ProjectKey.getById(DbControl, int) to get the ProjectKey object.
    
    See Also:
    getActiveProjectId(), setActiveProject(Project)
  - hasSystemPermission
```
public boolean hasSystemPermission(Permission permission)
```
    Check if the logged in user has the specified system permission.
    
    Parameters:
    permission - One of the system permission constants defined by the Permission enumeration
    
    Returns:
    TRUE if the logged in user has the permission, FALSE otherwise
  - hasPermission
```
public boolean hasPermission(Permission permission,
                    Item itemType)
```
    Check if the logged in user has the specfied permission for all item of the specified type.
    
    Parameters:
    permission - One of the permissions constants defined by the Permission enumeration
    itemType - One of the item constants defined by the Item enumeration
    
    Returns:
    TRUE if the logged in user has the permission, FALSE otherwise
  - isMemberOf
```
public boolean isMemberOf(Group group)
```
    Check if the logged in user is a member, directly or indirectly, of the specified group.
    
    Parameters:
    group - The group to check
    
    Returns:
    TRUE if the user is a member, FALSE otherwise
  - isMemberOf
```
public boolean isMemberOf(Role role)
```
    Check if the logged in user is a member of the specified role.
    
    Parameters:
    role - The role to check
    
    Returns:
    TRUE if the user is a member, FALSE otherwise
  - isMemberOf
```
public boolean isMemberOf(Project project)
```
    Check if the logged in user is a member, directly or indirectly, of the specified project.
    
    Parameters:
    project - The project to check
    
    Returns:
    TRUE if the user is a member, FALSE otherwise
  - isFriendOf
```
public boolean isFriendOf(User user)
```
    Check if the logged in user is a friend of of the specified user. A users is a friend if the logged in user is a member, directly or indirectly, of a group where the other user is direct member.
    
    Parameters:
    user - The user to check
    
    Returns:
    TRUE if the user is a friend, FALSE otherwise
  - getRoles
```
public Set<Integer> getRoles()
```
    Get the id of all roles where the logged in user is a member.
    
    Returns:
    A Set containing role id:s
  - getGroups
```
public Set<Integer> getGroups()
```
    Get the id of all groups where the logged in user is a member, directly or indirectly.
    
    Returns:
    A Set containing group id:s
  - getFriends
```
public Set<Integer> getFriends()
```
    Get the id of all friends to logged in user. A users is a friend if the logged in user is a member, directly or indirectly, of a group where the other user is direct member.
    
    Returns:
    A Set containing user id:s
  - getProjects
```
public Set<Integer> getProjects()
```
    Get the id of all projects where the logged in user is a member, directly or indirectly.
    
    Returns:
    A Set containing project id:s
  - getItemKeys
```
public Set<Integer> getItemKeys()
```
    Get the id of all item keys where the logged in user has a permission.
    
    Returns:
    A Set containing item key id:s
  - getProjectKeys
```
public Set<Integer> getProjectKeys()
```
    Get the id of all project keys where the logged in user has a permission.
    
    Returns:
    A Set containing project key id:s
  - getSessionSetting
```
public Object getSessionSetting(String name)
```
    Get the value of a session setting with the specified name.
    
    Parameters:
    name - The name of the setting
    
    Returns:
    A object with the value of the setting, or null if no setting is found
  - setSessionSetting
```
public Object setSessionSetting(String name,
                       Object value)
```
    Set the value of a session setting.
    
    Parameters:
    name - The name of the setting
    value - The new value of the setting, or null to remove the setting
    
    Returns:
    The old value of the setting, or null if it did not exist
  - getUserClientSetting
```
public String getUserClientSetting(String name)
```
    Get the value of the UserClientSetting with the specified name. If no user is logged in null is returned.
    
    Parameters:
    name - The name of the setting
    
    Returns:
    A string with the value of the setting, or null if no setting is found
  - setUserClientSetting
```
public String setUserClientSetting(String name,
                          String value)
```
    Set the value of a UserClientSetting.
    
    Parameters:
    name - The name of the setting
    value - The new value of the setting, or null to remove the setting
    
    Returns:
    The old value of the setting, or null if it did not exist or no user is logged in
  - getUserDefaultSetting
```
public String getUserDefaultSetting(String name)
```
    Get the value of the UserDefaultSetting with the specified name.
    
    Parameters:
    name - The name of the setting
    
    Returns:
    A string with the value of the setting, or null if no setting is found
  - setUserDefaultSetting
```
public String setUserDefaultSetting(String name,
                           String value)
```
    Set the value of a UserDefaultSetting.
    
    Parameters:
    name - The name of the setting
    value - The new value of the setting, or null to remove the setting
    
    Returns:
    The old value of the setting, or null if it did not exist or no user is logged in
  - getClientDefaultSetting
```
public String getClientDefaultSetting(String name)
```
    Get the value of the ClientDefaultSetting with the specified name.
    
    Parameters:
    name - The name of the setting
    
    Returns:
    A string with the value of the setting, or null if no setting is found
  - finalize
```
protected void finalize()
                 throws Throwable
```
    Clean up if a bad client application forgets to logout.
    
    Overrides:
    
    finalize in class Object
    
    Throws:
    
    Throwable

Class SessionControl

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getId

getClientId

getExternalClientId

newDbControl

getChallenge

login

impersonateLogin

logout

isLoggedIn

isLoggedInAdminInfo

getLoggedInUserId

getLoggedInUserIdAdminInfo

isImpersonated

reloadPermissions

reloadSettings

getActiveProjectId

setActiveProject

getProjectKeyId

hasSystemPermission

hasPermission

isMemberOf

isMemberOf

isMemberOf

isFriendOf

getRoles

getGroups

getFriends

getProjects

getItemKeys

getProjectKeys

getSessionSetting

setSessionSetting

getUserClientSetting

setUserClientSetting

getUserDefaultSetting

setUserDefaultSetting

getClientDefaultSetting

finalize