/***********************************************************************
 * 
 *  Copyright (C) 2006 Novell, Inc. All Rights Reserved.
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; version 2.1
 *  of the License.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Library Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, Novell, Inc.
 * 
 *  To contact Novell about this file by physical or electronic mail, 
 *  you may find current contact information at www.novell.com.
 * 
 *  Author: Juan Carlos Luciani <jluciani@novell.com>
 *  
 ***********************************************************************/

package com.novell.casa.authtoksvc;

import org.apache.log4j.Logger;

/**
 * IdentityToken Interface.
 * <p>
 * This is the interface implemented by Identity Token Providers.
 */
public interface IdentityToken
{
   /**
    * Initialize the token with parameters.
    *
    * @param identityId    Identity identifier.
    * @param sourceName    Name of the realm where the identityId is valid.
    * @param sourceUrl     URL to the realm (identity data source).
    * @param targetService Name of service being targeted.
    * @param targetHost    Host where the targeted service resides.
    * @param svcConfig     Service configuration object.
    * @throws Exception
    */
   void initialize(String identityId,
                   String sourceName,
                   String sourceUrl,
                   String targetService,
                   String targetHost,
                   SvcConfig svcConfig) throws Exception;

   /**
    * Initialize the token object with encoded token string.
    *
    * @param encodedToken  Encoded identity token string.
    * @throws Exception
    */
   void initialize(String encodedToken) throws Exception;

   /**
    * Returns encoded token string.
    * 
    * IMPORTANT: The token string can not contain the substring "]]>"
    * within it.
    *
    * @return  Encoded identity token string.
    * @throws Exception
    */
   String getEncodedToken() throws Exception;

   /**
    * Returns a string containing the identity token provider type.
    *
    * @return  Identity token provider type.
    * @throws Exception
    */
   String getProviderType() throws Exception;

   /**
    * Returns a string containing the identity id.
    *
    * @return  Identity identifier.
    * @throws Exception
    */
   String getIdentityId() throws Exception;

   /**
    * Returns a string containing the name associated with the
    * identity source.
    *
    * @return  Name of the authentication realm.
    * @throws Exception
    */
   String getSourceName() throws Exception;

   /**
    * Returns a string containing the url associated with the
    * identity source.
    *
    * @return  Url of the identity data source.
    * @throws Exception
    */
   String getSourceUrl() throws Exception;

   /**
    * Returns a string containing the name of the targeted service.
    *
    * @return  Name of the targeted service.
    * @throws Exception
    */
   String getTargetService() throws Exception;

   /**
    * Returns a string containig the name of the host where the
    * targeted service resides.
    *
    * @return  Name of the host where the targeted service resides.
    * @throws Exception
    */
   String getTargetHost() throws Exception;

   /**
    * Returns the attributes of the identity.
    *
    * @return  Identity attributes.
    * @throws Exception
    */
   javax.naming.directory.Attributes getAttributes() throws Exception;
}
