/*
* Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "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.mj.impl.rt.support;

/**
 * This interface is used by the system property extension mechanism in
 * order to ask the value of certain dynamic system property. The component
 * that provides this information must implement this interface in a package
 * <code>com.nokia.mj.impl.properties + &lt;jsr_package&gt;</code>. The name
 * of the class can be anything, but must be the same as defined in the value
 * of the dynamic system property. E.g. <code>fileconn.dir.graphics.name</code>
 * dynamic property value is set to :fileapi.DynamicPropertyHandler. Then the
 * name of the
 * class providing the value of <code>fileconn.dir.graphics.name</code>
 * property must be
 *<code>com.nokia.mj.impl.properties.file.DynamicPropertyHandler</code>.
 * <p>
 * If the dynamic system property implementation implements more than one
 * system property in a single class, the implementation must not make any
 * assumption wheter a new instance is always created or does the underlying
 * extemsion mechanism cache the created instance and re-use it.
 * <p>
 * Example how to implement a class providing some dynamic system property.
 * <pre>
 * package com.nokia.mj.impl.properties.file;
 *
 * import com.nokia.mj.impl.rt.support.SystemPropertyProvider;
 * public final class DynamicPropertyHandler implements SystemPropertyProvider
 * {
 *     public String getProperty(String key)
 *     {
 *         if(key.equals("fileconn.dir.graphics"))
 *         {
 *             return FileImpl.getDirGraphics();
 *         }
 *         else if(key.equals("fileconn.dir.graphics.name"))
 *         {
 *             return FileImpl.getDirGraphicsName();
 *         }
 *         else
 *         {
 *             return null;
 *         }
 *     }
 *
 *     public boolean isStatic(String key) {
 *         //All of the example file API dynamic properties are static
 *         return true;
 *     }
 * }
 * </pre>
 */
public interface SystemPropertyProvider
{
    /**
     * Gets the system property indicated by the specified key.
     * Called by the system property extension mechanism as
     * a result of <code>System.getProperty</code>
     * (or <code>System.getProperties</code>) call.
     *
     * @param key - the name of the system property.
     * @return the string value of the system property, or null if there is
     *         no property with that key.
     */
    public String getProperty(String key);

    /**
     * Returns the information whether the system property does
     * not change during the lifetime of the application.
     * <p>
     * Some detailed information how the underlying extension mechanism
     * works. Eventually all the static and dynamic properties are in a
     * Hashtable. The value of the property in the Hashtable tells whether
     * the property is static or dynamic.
     * If the value is static, it is returned to as it is. If the value is
     * dynamic, then a class providing the the dynamic value is created (or
     * previosly created instance might be used). Once the value has been
     * received from the object, the extension mechanism asks if the value
     * is now static using this method. If the value is static the value
     * is stored into the
     * Hashtable and if asked again the value is returned directly from the
     * Hashtable. If it is not a static the value in the HashTable remains
     * the same and if the system property is asked again, the described
     * scenario above happens again.
     *
     * @return true if value is static, false otherwise.
     */
    public boolean isStatic(String key);
}