/* ======================================================================
   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 java.util.Vector;
import java.util.Properties;
import java.security.cert.X509Certificate;
import org.bodington.database.PrimaryKey;
import org.bodington.server.realm.User;
import org.bodington.server.resources.Resource;
import org.bodington.server.resources.ResourceSummary;

/**
 * Represents a Users session with the site. For each user using the site there
 * is one instance of NavigationSession and it may be used by multiple clients at the same time.
 * For this reason it shouldn't store data that changes with every request such as the current resource.
 * And it probably shouldn't deal with anything that relates to the current resource.
 * @author Jon Maber
 * @author buckett
 */
public interface NavigationSession 
{
	public String currentUserName()
		throws BuildingServerException;
		
	public ResourceSummary getRootSummary()
		throws BuildingServerException;
		
	public Vector childSummaries( PrimaryKey resource_id )
		throws BuildingServerException;
		
	public PrimaryKey findResourceId( String[] names )
		throws BuildingServerException;

	public Resource findResource( PrimaryKey resource_id )
		throws BuildingServerException;
	
    /**
     * Gets a property for the current user.
     * @param name The name of the property to get.
     * @return The value of the property.
     */
	public String getUserProperty( String name )
		throws BuildingServerException;
	
    /**
     * Sets a property for the current user.
     * @param name The name of the property. This can't be null.
     * @param value The value to set the property to, if it is null then the
     * property is deleted.
     */
	public void setUserProperty( String name, String value )
		throws BuildingServerException;
	
	public String getUserPreferredStyleSheet()
		throws BuildingServerException;
	
	public void clearAuthenticationCredentials()
		throws BuildingServerException;
	
	public void setAuthenticationCredentials( Properties credentials, String authenticator_alias )
		throws BuildingServerException;
	
	public void setClientX509( X509Certificate cert )
		throws BuildingServerException;
	
	public boolean isAuthenticated()
		throws BuildingServerException;

	public boolean isAnonymous()
		throws BuildingServerException;

	public String getAuthenticationError()
		throws BuildingServerException;
	
	public PrimaryKey getAuthenticatedUserId()
		throws BuildingServerException;
	
	public User getAuthenticatedUser()
		throws BuildingServerException;
	
	public String getAuthenticatorAlias()
		throws BuildingServerException;
    
    /**
     * Get the container for home resources.
     * @return The container for home resources or null if we can't find it.
     */
    public HomeContainerSession getHomeContainerSession()
        throws BuildingServerException;
    
	}


