/* ======================================================================
   Parts Copyright 2006 University of Leeds, Oxford University, University of the Highlands and Islands.

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

====================================================================== */

package org.bodington.server.userimport;
import java.util.Collection;
import org.bodington.server.BuildingServerException;


/** This interface should be implemented by providers of special information
resources. For example, the class org.bodington.server.userimport.ldapir.LDAPGeneratedUser
implements it.
<p>
<br/>$HeadURL: https://svn.oucs.ox.ac.uk/sysdev/src/u/usrgrpgen/tags/2.0-3/uk/ac/ox/usrgrpgen/GeneratedUser.java $
<br/>$LastChangedRevision: 3381 $
<br/>$LastChangedDate: 2004-04-02 16:43:20 +0100 (Fri, 02 Apr 2004) $
<br/>$LastChangedBy: mats $
</p>
@author	Mats Henrikson
@version $LastChangedRevision: 3381 $
*/
public interface GeneratedUser {


	/** Saves a user to the database. It shouldn't matter if the user already
	exists or not.
	@throws	BuildingServerException	Throws a BSE if something goes wrong.
	@throws	NotInitialisedException	Throws a NIE if the User hasn't been loaded.
	*/
	public void save() throws BuildingServerException, NotInitialisedException;


	/** Returns a String if this is <strong>NOT</strong> a valid user for the
	Bodington system, returns null if this user can has valid data to be added
	to the database. See the documentation for your implementation of this
	class for information on what tests are carried out, and the error messages
	to expect.
	@return	Returns null if this user can be added, returns a
			<strong>multiline</strong> String with brief explanations of all
			reasons why this user should not be added.
	*/
	public String problems();


	/** Returns a unique ID of some sort for this user.
	@return	A unique ID of some sort identifying this user.
	*/
	public String getUniqueID();


	/** Loads a User from the bodington db.
	@return	Returns true if it was possible to load them, false otherwise.
	@throws	BuildingServerException	Throws a BSE if something goes wrong.
	*/
	public boolean load() throws BuildingServerException;


	/**
     * Creates a new User and sets their initial values. Does not save the
	 * user. 
	 * @throws UserCreationException If the user can't be created.
     * */
	public void create() throws UserCreationException;


	/** Updates a User with the data from the user attribute map and puts them
	in an extra groups. Only updates fields that needs to be updated. Does not
	save the user. Make sure the user already exists or deal with a
	NullPointerException.
	@throws	BuildingServerException	Throws a BSE if something goes wrong.
	@throws	NotInitialisedException	Throws a NIE if the User hasn't been loaded.
	*/
	public void update()
			throws BuildingServerException, NotInitialisedException;


	/** Put the User in all Groups passed in the Collection.
	@param	newGroups	All the groups the user should be in.
	@throws	NotInitialisedException	Throws a NIE if the User hasn't been loaded.
	*/
	public void addToGroups(Collection newGroups)
			throws NotInitialisedException;

}