/*

* Copyright (c) 2005 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of the License "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

package com.nokia.sdt.emf.dm;

import org.eclipse.emf.common.util.EList;

import org.eclipse.emf.ecore.EObject;

import java.util.Map;

import java.util.Set;

/**

 * This interface gathers a collection of tables, presumably

 * sharing the same keys, each which map to strings in different

 * languages.

 * 

 * 

 * @model

 */

public interface ILocalizedStringBundle extends EObject {

	public interface IListener {

		void stringTableAdded(Language language);

		void stringTableRemoved(Language language);

		void defaultLanguageChanged(Language newDefaultLanguage);

	}

	void addListener(IListener listener);

	void removeListener(IListener listener);

    /** 

     * Get all the language-specific string Tables 

     * @model type="com.nokia.sdt.emf.dm.ILocalizedStringTable" 

     * 		  containment="true"

     */

    EList getLocalizedStringTables();

    /**

     * Adds a new table for the given language. Empty strings are

     * added for all existing keys, i.e. keys present in the other

     * tables.

     * @throws IllegalArgumentException if the language is already present

     * @return the new, initialized string table

     */

    ILocalizedStringTable addLocalizedStringTable(Language language);

    /** Find a language table

     * 

     * @param language the language to look up

     * @return table, or null

     */

    ILocalizedStringTable findLocalizedStringTable(Language language);

    /**

     * Find a string in the given language with the given key.

     */

    String findString(Language language, String key);

     /**

     * Get an map of strings among the tables matching the given key.

     * The returned map has keys of type Language and values of type String.

     * Null is returned if there are no matches

     */

    Map findStrings(String key);

    /**

     * Tell if the table is in the bundle

     */

    boolean hasStringTable(ILocalizedStringTable table);

    /**

     * Tell whether the bundle has a table defining this key

     */

    boolean hasStringKey(String key);

    /** Register a string.  If it already exists, that

     * definition is deleted and replaced with this one; otherwise, 

     * the string is added.  A language table for the string's

     * language is added if necessary.  

     * @param language a language table for this language is added if necessary

     * @param key key value for the string. If null a new one is generated. If

     * the key value exists the existing entry is updated

     * @param value

     */

    StringValue registerString(Language language, String key, String value);

    void setKeyProvider(IStringKeyProvider provider);

    /**

     * Establish the default language. The default

     * language is implied by methods that don't have

     * any ILanguage context and whose method name ends in 'Default'

     * @throws IllegalArgumentException if null is passed

     */

    void setDefaultLanguage(Language language);

    Language getDefaultLanguage();

    /**

     * Returns any existing entry for the key

     * in the default language

     */

    String getLocalizedStringDefault(String key);

    /**

     * Adds the current string in the default language

     * A new key is generated. Empty string values are

     * entered for the same key in all other languages 

     * in the string table.

     * @param value

     * @return the localized string entry

     */

    StringValue addLocalizedStringDefault(String value);

    /**

     * Updates the localized value for the string with the given

     * key in the default language. If the key is not present

     * a new entry is made with the given key and value and empty

     * values inserted for other languages

     * @return the updated localized string entry

     */

    StringValue updateLocalizedStringDefault(String key, String value);

    /**

     * Removes entries for the given key from all languages.

     * @param key

     */

    void removeLocalizedStringAllLanguages(String key);

    /**

     * Get user-generated string keys.

     */

    Set<String> getUserGeneratedStringKeys();

}