// Copyright 1997 The Open Group Research Institute.  All rights reserved.
// Copyright 1999 Memesoft.  All rights reserved.

package krb5.lib.ccache;

import krb5.lib.*;
import java.io.*;
import java.net.*;

/**
 * Credentials cache
 */
public interface CredentialsCache {

	/**
	 * Returns name for the credentials cache
	 *
	 * @return String is a result
	 */
	String getName();

	/**
	 * Sets primary name
	 *
	 * @param principal is of type String
	 * @exception RealmException an exception
	 * @see krb5.lib.RealmException
	 */
	void setPrimaryPrincipal(String principal) throws RealmException;

	/**
	 * Sets primary name
	 *
	 * @param principal is of type PrincipalName
	 * @see krb5.lib.PrincipalName
	 */
	void setPrimaryPrincipal(PrincipalName principal);

	/**
	 * Returns primary name
	 *
	 * @return PrincipalName is a result
	 * @see krb5.lib.PrincipalName
	 */
	PrincipalName getPrimaryPrincipal();

	/**
	 * Returns TGT service name
	 *
	 * @return PrincipalName is a result
	 * @see krb5.lib.PrincipalName
	 */
    PrincipalName getTGTServiceName();

	/**
	 * Destroys
	 */
	void destroy();

	/**
	 * Finalize
	 */
	void finalize();

	/**
	 * Adds credentials
	 *
	 * @param creds is of type Credentials
	 * @see krb5.lib.ccache.Credentials
	 */
	void add(Credentials creds);

	/**
	 * Adds an array of credentials
	 *
	 * @param creds is of type Credentials[]
	 * @see krb5.lib.ccache.Credentials
	 */
	void add(Credentials[] creds);

	/**
	 * Removes credentials
	 *
	 * @param creds is of type Credentials
	 * @see krb5.lib.ccache.Credentials
	 */
	void remove(Credentials creds);

	/**
	 * Removes an array of credentials
	 *
	 * @param creds is of type Credentials[]
	 * @see krb5.lib.ccache.Credentials
	 */
	void remove(Credentials[] creds);

	/**
	 * Returns credentials
	 *
	 * @return CCacheEnumerator is a result
	 * @see krb5.lib.ccache.CCacheEnumerator
	 */
	CCacheEnumerator getCredentials();

	/**
	 * Lookup a credentials for a given filter
	 *
	 * @return CCacheEnumerator is a result
	 * @param filter is of type CredentialsFilter
	 * @see krb5.lib.ccache.CCacheEnumerator
	 * @see krb5.lib.ccache.CredentialsFilter
	 */
	CCacheEnumerator lookupCredentials(CredentialsFilter filter);

	/**
	 * Lookup a credentials for a given filters
	 *
	 * @return CCacheEnumerator is a result
	 * @param filters is of type CredentialsFilter[]
	 * @see krb5.lib.ccache.CCacheEnumerator
	 * @see krb5.lib.ccache.CredentialsFilter
	 */
	CCacheEnumerator lookupCredentials(CredentialsFilter[] filters);

	/**
	 * Lookups a single credentials
	 *
	 * @return Credentials is a result
	 * @param filter is of type CredentialsFilter
	 * @see krb5.lib.ccache.Credentials
	 * @see krb5.lib.ccache.CredentialsFilter
	 */
	Credentials lookupSingleCredentials(CredentialsFilter filter);

	/**
	 * Lookups a single credentials 
	 *
	 * @return Credentials is a result
	 * @param filters is of type CredentialsFilter[]
	 * @see krb5.lib.ccache.Credentials
	 * @see krb5.lib.ccache.CredentialsFilter
	 */
	Credentials lookupSingleCredentials(CredentialsFilter[] filters);

	/**
	 * Lookups a single valid credentials
	 *
	 * @return Credentials is a result
	 * @param serviceName is of type PrincipalName
	 * @see krb5.lib.ccache.Credentials
	 * @see krb5.lib.PrincipalName
	 */
	Credentials lookupSingleValidCredentials(PrincipalName serviceName);

	/**
	 * Returns initial credentials
	 *
	 * @return Credentials is a result
	 * @exception RealmException an exception
	 * @exception KrbException an exception
	 * @exception IOException an exception
	 * @exception UnknownHostException an exception
	 * @see krb5.lib.ccache.Credentials
	 * @see krb5.lib.RealmException
	 * @see java.io.IOException
	 * @see java.net.UnknownHostException
	 */
	Credentials getInitialCredentials()
	    throws RealmException, KrbException, IOException, UnknownHostException;

	/**
	 * Returns initial credentials
	 *
	 * @return Credentials is a result
	 * @param principal is of type String
	 * @param pw is of type StringBuffer
	 * @exception RealmException an exception
	 * @exception KrbException an exception
	 * @exception IOException an exception
	 * @exception UnknownHostException an exception
	 * @see krb5.lib.ccache.Credentials
	 * @see krb5.lib.RealmException
	 * @see krb5.lib.KrbException
	 * @see java.io.IOException
	 * @see java.net.UnknownHostException
	 */
	Credentials getInitialCredentials(String principal, StringBuffer pw)
	     throws RealmException, KrbException, IOException, UnknownHostException;

	/**
	 * Returns initial credentials
	 *
	 * @return Credentials is a result
	 * @param pw is of type StringBuffer
	 * @exception KrbException an exception
	 * @exception IOException an exception
	 * @exception UnknownHostException an exception
	 * @see krb5.lib.ccache.Credentials
	 * @see krb5.lib.KrbException
	 * @see java.io.IOException
	 * @see java.net.UnknownHostException
	 */
	Credentials getInitialCredentials(StringBuffer pw)
	     throws KrbException, IOException, UnknownHostException;

	/**
	 * Returns initial credentials
	 *
	 * @return Credentials is a result
	 * @param principal is of type String
	 * @param key is of type EncryptionKey
	 * @exception RealmException an exception
	 * @exception KrbException an exception
	 * @exception IOException an exception
	 * @exception UnknownHostException an exception
     * @see krb5.lib.ccache.Credentials
     * @see krb5.lib.EncryptionKey
	 * @see krb5.lib.RealmException
	 * @see krb5.lib.KrbException
	 * @see java.io.IOException
	 * @see java.net.UnknownHostException
	 */
	Credentials getInitialCredentials(String principal, EncryptionKey key)
	     throws RealmException, KrbException, IOException, UnknownHostException;

	/**
	 * Returns initial credentials
	 *
	 * @return Credentials is a result
	 * @param key is of type EncryptionKey
	 * @exception KrbException an exception
	 * @exception IOException an exception
	 * @exception UnknownHostException an exception
	 * @see krb5.lib.ccache.Credentials
     * @see krb5.lib.EncryptionKey
	 * @see krb5.lib.KrbException
	 * @see java.io.IOException
	 * @see java.net.UnknownHostException
	 */
	Credentials getInitialCredentials(EncryptionKey key)
	     throws KrbException, IOException, UnknownHostException;

	/**
	 * Returns service credentials
	 *
	 * @return Credentials is a result
	 * @param serviceName is of type PrincipalName
	 * @exception KrbException an exception
	 * @exception IOException an exception
	 * @exception UnknownHostException an exception
	 * @see krb5.lib.ccache.Credentials
	 * @see krb5.lib.PrincipalName
	 * @see krb5.lib.KrbException
	 * @see java.io.IOException
	 * @see java.net.UnknownHostException
	 */
	Credentials getServiceCredentials(PrincipalName serviceName)
	     throws KrbException, IOException, UnknownHostException;

	/**
	 * Returns service credentials
	 *
	 * @return Credentials is a result
	 * @param serviceName is of type String
	 * @exception RealmException an exception
	 * @exception KrbException an exception
	 * @exception IOException an exception
	 * @exception UnknownHostException an exception
	 * @see krb5.lib.ccache.Credentials
	 * @see krb5.lib.RealmException
	 * @see krb5.lib.KrbException
	 * @see java.io.IOException
	 * @see java.net.UnknownHostException
	 */
	Credentials getServiceCredentials(String serviceName)
	     throws RealmException, KrbException, IOException, UnknownHostException;

	/**
	 * Copies a credential cache from the given one
	 *
	 * @param ccache is of type CredentialsCache
	 * @see krb5.lib.ccache.CredentialsCache
	 */
	void copyFrom(CredentialsCache ccache);

	/**
	 * Print
	 */
	void print();
}