1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 *

    16 */

    17 

    18 

    19 package com.nokia.mj.impl.rt.support;

    20 

    21 /**

    22  * This interface is used by the system property extension mechanism in

    23  * order to ask the value of certain dynamic system property. The component

    24  * that provides this information must implement this interface in a package

    25  * <code>com.nokia.mj.impl.properties + &lt;jsr_package&gt;</code>. The name

    26  * of the class can be anything, but must be the same as defined in the value

    27  * of the dynamic system property. E.g. <code>fileconn.dir.graphics.name</code>

    28  * dynamic property value is set to :fileapi.DynamicPropertyHandler. Then the

    29  * name of the

    30  * class providing the value of <code>fileconn.dir.graphics.name</code>

    31  * property must be

    32  *<code>com.nokia.mj.impl.properties.file.DynamicPropertyHandler</code>.

    33  * <p>

    34  * If the dynamic system property implementation implements more than one

    35  * system property in a single class, the implementation must not make any

    36  * assumption wheter a new instance is always created or does the underlying

    37  * extemsion mechanism cache the created instance and re-use it.

    38  * <p>

    39  * Example how to implement a class providing some dynamic system property.

    40  * <pre>

    41  * package com.nokia.mj.impl.properties.file;

    42  *

    43  * import com.nokia.mj.impl.rt.support.SystemPropertyProvider;

    44  * public final class DynamicPropertyHandler implements SystemPropertyProvider

    45  * {

    46  *     public String getProperty(String key)

    47  *     {

    48  *         if(key.equals("fileconn.dir.graphics"))

    49  *         {

    50  *             return FileImpl.getDirGraphics();

    51  *         }

    52  *         else if(key.equals("fileconn.dir.graphics.name"))

    53  *         {

    54  *             return FileImpl.getDirGraphicsName();

    55  *         }

    56  *         else

    57  *         {

    58  *             return null;

    59  *         }

    60  *     }

    61  *

    62  *     public boolean isStatic(String key) {

    63  *         //All of the example file API dynamic properties are static

    64  *         return true;

    65  *     }

    66  * }

    67  * </pre>

    68  */

    69 public interface SystemPropertyProvider

    70 {

    71     /**

    72      * Gets the system property indicated by the specified key.

    73      * Called by the system property extension mechanism as

    74      * a result of <code>System.getProperty</code>

    75      * (or <code>System.getProperties</code>) call.

    76      *

    77      * @param key - the name of the system property.

    78      * @return the string value of the system property, or null if there is

    79      *         no property with that key.

    80      */

    81     public String getProperty(String key);

    82 

    83     /**

    84      * Returns the information whether the system property does

    85      * not change during the lifetime of the application.

    86      * <p>

    87      * Some detailed information how the underlying extension mechanism

    88      * works. Eventually all the static and dynamic properties are in a

    89      * Hashtable. The value of the property in the Hashtable tells whether

    90      * the property is static or dynamic.

    91      * If the value is static, it is returned to as it is. If the value is

    92      * dynamic, then a class providing the the dynamic value is created (or

    93      * previosly created instance might be used). Once the value has been

    94      * received from the object, the extension mechanism asks if the value

    95      * is now static using this method. If the value is static the value

    96      * is stored into the

    97      * Hashtable and if asked again the value is returned directly from the

    98      * Hashtable. If it is not a static the value in the HashTable remains

    99      * the same and if the system property is asked again, the described

   100      * scenario above happens again.

   101      *

   102      * @return true if value is static, false otherwise.

   103      */

   104     public boolean isStatic(String key);

   105 }