/* ======================================================================
   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;

import org.bodington.database.PrimaryKey;

/**
 * Class that encapsulates a single resource session. This class is intended to
 * act as a superclass for session implementations that represent a single user
 * associated with a single resource. The method
 * {@link #setResourceId(PrimaryKey)} has been overridden so that within the
 * life-cycle of a session a resource can only be bound to it once and then
 * subsequently not changed. Session implementations that need to be able to
 * bind to different resources within their life-cycle, should subclass
 * {@link ReusableResourceSession} instead.
 * @see #setResourceId(PrimaryKey)
 * @see ReusableResourceSession
 * @author Jon Maber
 * @author Alexis O'Connor
 */
public abstract class SingleResourceSession extends org.bodington.server.BuildingSessionImpl
	{
	public SingleResourceSession()
		{
		super();
		}

    /**
     * Overridden to be called just once. Instances of this class should have
     * this method called just once. Within the life-cycle of the session, it
     * can be bound to a single resource and can not be re-assigned to another.
     * @param k the ID of the resource for this instance.
     * @throws IllegalStateException if the resource for this object has
     *         already been set.
     */
    public void setResourceId( PrimaryKey k )
        {
        if ( getResourceId() != k && getResourceId() != null)
            throw new IllegalStateException(
                "Can not change resource for a resource bound session." );
        super.setResourceId( k );
        }
	}