public interface IUserAdmin {
/**
 * Login to the user administration - depending on the userid and credentials, the server might elect not to
 * support specific commands
 * 
 * @param userid The user ID to login with.
 * @param credentials The credentials (usually password) to present to the server
 */
public void login(String userid, Object credentials) throws UserAdminException;

/**
 * Provides direct access to the useradministration if already logged in through another
 * channel
 * 
 * @param sessionid The PP session ID 
 */
public void login(String sessionid) throws UserAdminException;

/**
 * Tries to get a user record from the server
 * 
 * @param userid The userid to retrieve
 * @return The user record
 */
public User getUser(int userid) throws UserAdminException;

/**
 * Tries to fetch a user based on a row value from the user database
 * 
 * @param row The ID of a row in the user database (fetched from <code>IUserAttributes</code>)
 * @param rowValue The value of the row to look for
 * @return The user record
 */
public User getUser(String row, String rowValue) throws UserAdminException;

/**
 * Tries to get a user record from the server
 * 
 * @param logonID The logon ID (the user ID the user entered)
 * @param method The authentication method (userid/password, userid/keyfile, userid/certificate etc.)
 * @return The user record
 */
public User getUser(String logonID, int method) throws UserAdminException;

/**
 * Retrieves all user groups
 * 
 * @return A list of the retrieved groups
 */
public Group[] getAllGroups() throws UserAdminException;

/**
 * Retrieves all user profiles
 * 
 * @return A list of the retrieved profiles
 */
public Profile[] getAllProfiles() throws UserAdminException;

/**
 * Retrieves the groups a specific user is member of
 * 
 * @param userid The userid of the user to fetch member groups for
 * @return A list of the retrieved groups
 */
public Group[] getGroups(int userid) throws UserAdminException;

/**
 * Retrieves the groups attached to a specific list of profiles
 * 
 * @param profiles The list of profiles to fetch groups for
 * @return A list of the retrieved groups
 */
public Group[] getGroupsByProfiles(int profiles[]) throws UserAdminException;

/**
 * Retrieves the profiles a specific user is member of
 * 
 * @param userid The userid of the user to fetch member profiles for
 * @return A list of the retrieved profiles
 */
public Profile[] getProfiles(int userid) throws UserAdminException;

/**
 * Retrieves the profiles attached to a specific group
 * 
 * @param groupid The group id of the group to fetch attached profiles for
 * @return A list of the retrieved profiles
 */
public Profile[] getProfilesByGroup(int groupid) throws UserAdminException;

/**
 * Called to indicate that a users login failed, so invalid login counter is increased by 1
 * 
 * @param logonID The logon ID (the user ID the user entered)
 * @param method The authentication method (userid/password, userid/keyfile, userid/certificate etc.)
 */
public void loginFailed(String logonID, int method) throws UserAdminException;

/**
 * Called to indicate that the logon succeeded for the user, so the number of invalid password
 * attempts is reset, the last login timestamp is updated etc.
 * 
 * @param loginID The logon ID (the user ID the user entered)
 * @param method The authentication method (userid/password, userid/keyfile, userid/certificate etc.)
 */
public void loginSucceeded(String loginID, int method) throws UserAdminException;

/**	
 * Called to indicate that the user has lost his credentials - this will trigger the generation of
 * a new password, or of a new PIN-letter that is sent to the user, depending on the type of credentials,
 * and on the plugin running on the UserAdmin server.
 * 
 * @param loginID The logon ID (the user ID the user entered)
 * @param method The authentication method (userid/password, userid/keyfile, userid/certificate etc.)
 * @param data This object is sent along to the server, to allow you to specify extra information such as which action to take.
 * @return An object describing the result.
 */
public Object credentialsLost(String loginID, int method, Object data) throws UserAdminException;

/**
 * This method locks a user account by setting the the lock reason
 * on the user object
 * 
 * @param userid The id of the user to update
 * @param status The new status for this user
 * @param statusinfo The status info for this user - if the status is e.g. locked, the info field describes why.
 */
public void updateUserStatus(int userid, int status, int statusinfo) throws UserAdminException;
	
/**
 * This method overwrites the authentication level given by the authentication
 * method attached to a challenge. 
 * 
 * @param logonid The logon ID (the user ID the user entered)
 * @param methodid The authentication method (userid/password, userid/keyfile, userid/certificate etc.)
 * @param authlvl The new overwriting lock level for this challenge
 */
public void updateChallengeAuthLevel(String logonid, int methodid, int authlvl) throws UserAdminException;

/**
 * This method changes the status of a challenge (usually locks it) the status code
 * on the challenge object
 * 
 * @param logonid The logon ID (the user ID the user entered)
 * @param methodid The authentication method (userid/password, userid/keyfile, userid/certificate etc.)
 * @param status The new status for this challenge
 */
public void updateChallengeStatus(String logonid, int methodid, int status) throws UserAdminException;

/**
 * This method deletes an entire challenge entry from the challenge
 * database
 * 
 * @param logonid The logon ID (the user ID the user entered)
 * @param methodid The authentication method (userid/password, userid/keyfile, userid/certificate etc.)
 */
public void deleteChallenge(String logonid, int methodid) throws UserAdminException;

/**
 * This method create a new challenge entry in the challenge
 * database
 * 
 * @param userid The id of the user to update
 * @param logonid The logon ID (the user ID the user entered)
 * @param methodid The authentication method (userid/password, userid/keyfile, userid/certificate etc.)
 * @param credentials The credentials (usually password) to present to the server
 */
public void createChallenge(int userid, String logonid, int methodid, byte[] credentials ) throws UserAdminException;

/**
 * This method create a new challenge entry in the challenge
 * database. This method will result in a non delivery of the
 * challenge.
 * 
 * @param userid The id of the user to update
 * @param logonid The logon ID (the user ID the user entered)
 * @param methodid The authentication method (userid/password, userid/keyfile, userid/certificate etc.)
 * @param credentials The credentials (usually password) to present to the server
 * @param status The status code for the new challenge
 * @param authlvl The "real" authentication level to use
 */
public void createChallenge(int userid, String logonid, int methodid, int status, byte[] credentials, int authlvl ) throws UserAdminException;

/**
 * This method create a new challenge entry in the challenge
 * database
 * 
 * @param userid The id of the user to update
 * @param logonid The logon ID (the user ID the user entered)
 * @param methodid The authentication method (userid/password, userid/keyfile, userid/certificate etc.)
 * @param credentials The credentials (usually password) to present to the server
 * @param status The status code for the new challenge
 * @param authlvl The "real" authentication level to use
 * @param deliverymethod The delivery method of the challenge
 */
public void createChallenge(int userid, String logonid, int methodid, int status, byte[] credentials, int authlvl, int deliverymethod ) throws UserAdminException;

/**
 * This method updates a challenge entry in the challenge
 * database
 * 
 * @param logonid The logon ID (the user ID the user entered)
 * @param methodid The authentication method (userid/password, userid/keyfile, userid/certificate etc.)
 * @param credentials The credentials (usually password) to present to the server
 */
public void updateChallenge(String logonid, int methodid, byte[] credentials ) throws UserAdminException;

/**
 * This method updates a users attributes. The content should
 * be given as String objects (both key and values alike)
 * 
 * @param userid The userid of the user to update
 * @param attributes A hashtable containing the attributes to create/update (if a value is empty, it will be deleted)
 */
public void updateUserAttributes(int userid, Hashtable attributes) throws UserAdminException;

/**
 * This method can be used to create a user within the user database. 
 * The user will get a challenged attached to him.
 * 
 * @param logonid The logon id for the challenge attached to the user
 * @param methodid The authentication method for the challenge attached to the user
 * @param level Authentication level, or 0 for default for this method
 * @param credentials The credentials for the attached challenge
 * @return The user id of the newly created user
 * @throws UserAdminException If an error occurs. If a challenge entry exists, the exception is thrown with errorcode ERROR_ENTRYALREADYEXIST
 */
public int createUser( String logonid, int methodid, int level, byte[] credentials ) throws UserAdminException;

/**
 * This method can be used to create a user within the user database. 
 * The user will get a challenged attached to him. Also the parsed
 * attribute table will be added to the user database. If the attributes
 * parsen is <code>null</code> they will be ignored.
 * 
 * @param logonid The logon id for the challenge attached to the user
 * @param methodid The authentication method for the challenge attached to the user
 * @param level Authentication level, or 0 for default for this method
 * @param credentials The credentials for the attached challenge
 * @param attributes The attributes for the new user
 * @return The user id of the newly created user
 * @throws UserAdminException If an error occurs. If a challenge entry exists, the exception is thrown with errorcode ERROR_ENTRYALREADYEXIST
 */
public int createUser( String logonid, int methodid, int level, byte[] credentials, Hashtable attributes ) throws UserAdminException;

/**
 * This method can be used to create a user within the user database.
 * 
 * @return The user id of the newly created user
 */
public int createUser() throws UserAdminException;

/**
 * This method can be used to retreive a specific challenge for
 * a user. Very usefull for business logic depending on 
 * challenge information not requirering other user information
 * 
 * @param id The ID of the user with that specific challenge
 * @param method The ID of the authentication method to fetch
 * @return The challenge object retrieved from the database
 */
public Challenge getUserChallenge( int id, int method ) throws UserAdminException;

/**
 * This method can be used to retreive a specific challenge for
 * a user. Very usefull for business logic depending on 
 * challenge information not requirering other user information
 * 
 * @param logonid The logon id of the user with that specific challenge
 * @param method The ID of the authentication method to fetch
 * @return The challenge object retrieved from the database
 */
public Challenge getUserChallenge( String logonid, int method ) throws UserAdminException;

/**
 * This method can be used to search for challenges with a specific
 * authentication level which was created and never used
 * 
 * @param authlvl The authentication level
 * @param date The date to match up against
 * @param before A boolean stating whether to search before or after this date
 * @return A list of challenges matching the search
 * @throws UserAdminException If an error occurs during search. If no rows where found, error id <code>UserAdminException.ERROR_NOROWSFOUND</code> will be set 
 */
public Challenge[] searchInitialChallenges( int authlvl, Date date, boolean before )  throws UserAdminException;

/**
 * This method can be used to search for challenges with a specific
 * authentication level which have not logged on since a specific date
 * 
 * @param authlvl The authentication level
 * @param date The date to match up against
 * @param before A boolean stating whether to search before or after this date
 * @return A list of challenges matching the search
 * @throws UserAdminException If an error occurs during search. If no rows where found, error id <code>UserAdminException.ERROR_NOROWSFOUND</code> will be set 
 */
public Challenge[] searchInactiveChallenges( int authlvl, Date date, boolean before ) throws UserAdminException;

/**
 * This method can be called to activate a search that goes through
 * all the challenges in the challenge table and calls a handler 
 * for each challenge
 * 
 * @param handler The handler that is called for each challenge
 * @param continueOnError Specifies whether the server should continue when an exception is thrown from the handler
 */
public void batchChallenges( IChallengeHandler handler, boolean continueOnError ) throws UserAdminException;

/**
 * This method can be called to activate a search that goes through
 * all the challenges in the challenge table and calls a handler 
 * for each userid in the challenge table with the challenges for that 
 * user
 * 
 * @param handler The handler that is called for each user in the challenge table
 * @param continueOnError Specifies whether the server should continue when an exception is thrown from the handler
 */
public void batchChallenges( IUserChallengeHandler handler, boolean continueOnError ) throws UserAdminException;

/**
 * Attaches the given profiles to a user
 * 
 * @param userid The user to modify
 * @param profiles The list of profiles to add to the user
 */
public void attachProfiles(int userid, int[] profiles) throws UserAdminException;

/**
 * Detaches (removes) the given profiles from a user, so he is no longer member of the listed profiles.
 * 
 * @param userid The user to modify
 * @param profiles The list of profiles to remove from the user
 */
public void detachProfiles(int userid, int[] profiles) throws UserAdminException;

/**
 * Sends a custom command to the server
 * 
 * @param command The command object to execute
 * @return The command reply object
 */
public AbstractUserAdminCommand executeCustomCommand(AbstractUserAdminCommand command) throws UserAdminException;

/**
 * Sends a custom command to the server that will be interpreted and executed by it - this allows
 * for any commands to be executed by the useradmin server, and it is a great place for extending it
 * so it can support custom functionality.
 * 
 * @param command The name of the command to execute
 * @param data The request data object to send to the server
 * @return The reply data object
 */
public Object executeCustomCommand(String command, Object data) throws UserAdminException;

/**
 * Called to reset the number of invalid password attempts
 * 
 * @param loginID The logon ID (the user ID the user entered)
 * @param method The authentication method (userid/password, userid/keyfile, userid/certificate etc.)
 */
public void resetInvalidPasswordAttempts(String loginID, int method) throws UserAdminException;

/**
 * Sets the number of milliseconds to wait for a reply, this will affect all commands executed.
 * The default timeout is 30000 ms or 30 seconds.
 * 
 * @param timeout The timeout in milliseconds
 */
public void setTimeout(int timeout) throws UserAdminException;

/**
 * The specified string is logged in the revisionlog
 * 
 * @param str The string to add, could typically be signtext=xxxxx;certificate=yyyyy
 */
public void logInRevisionLog(String str) throws UserAdminException;

/**
 * Lists the acls defined in the useradmin database
 * @return The list of acls
 * @throws UserAdminException If an error occures during list
 */
public Acl[] listAcls() throws UserAdminException; 

/**
 * Searches for challenges with the specified logon ID, and who is member of the given group (if group is not null)
 */
public Challenge[] searchChallenges(String logonIdPattern, String groupName, int maxResults) throws UserAdminException;

	
/**
 * Attaches the given profiles to a series of users. Invalid combinations of 
 * logon_id and method_id will be ignored. If a user already has one of the profiles
 * attached that attachment will be skipped.
 * 
 * @param profiles The list of profiles to add to the user
 * @param logon_ids The users to modify
 * @param method_ids The methods deciding the logon_ids (must be same length)
 * @return The number of user that had one or more profiles attached
 */
public int attachProfiles(int profiles[], String logon_ids[], int method_ids[] ) throws UserAdminException;

/**
 * Allows the application using the API to set the name. Used for
 * identifying the application at the useradministration server.
 * @param appname The name of the application 
 */	
public void setApplicationName( String appname );
}