/*
* Copyright (c) 2008-2009 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;
import com.nokia.mj.impl.utils.Uid;
/**
* ApplicationInfo is an abstract base class for API implementations,
* which allows getting application related static information.
* <p>
* The class provides a static getter method for getting an instance of
* the running application. In those runtimes that are always running only
* one instance (like MIDP) returns always the same instance of the
* ApplicationInfo. However those runtimes (like eRCP), that may run several
* application in the same JVM instance, will return an application specific
* instance.
* <p>
* The runtime implementation hides the solving of the correct application
* when method <code>getInstace</code> is called. However it must be noted
* that if the call is made some common thread, the <code>getInstace</code>
* might not able to solve the correct application.
* <p>
* Example how to get the name of the application:
* <pre>
* package com.nokia.mj.impl.mypackage;
*
* import com.nokia.mj.impl.rt.support;
* public void myClass()
* {
* public void myMethod()
* {
* //Get the name of the application.
* String appName = ApplicationInfo.getInstance().getName();
*
* //my implementation...
* }
* }
*</pre>
* <p>
* Example how to reuse the application object:
* <pre>
* package com.nokia.mj.impl.mypackage;
*
* import com.nokia.mj.impl.rt.support;
* public void myClass2()
* {
* public void myMethod()
* {
* //Get the insatnce of ApplicationInfo.
* ApplicationInfo appInfo = ApplicationInfo.getInstance();
*
* //Get the name of the application.
* String appName = appInfo.getName();
*
* //Get the vendor of the application.
* String appVendor = appInfo.getVendor();
*
* //my implementation...
* }
* }
*</pre>
* @author Nokia Corporation
* @version 1.0
*/
public abstract class ApplicationInfo
{
/**
* A constant representing the manufacturer domain when returned from the
* method {@link ApplicationInfo#getProtectionDomain
* getProtectionDomain}
*/
public static final String MANUFACTURER_DOMAIN = "MFD";
/**
* A constant representing the identified third party domain when returned
* from the method {@link ApplicationInfo#getProtectionDomain
* getProtectionDomain}
*/
public static final String IDENTIFIED_THIRD_PARTY_DOMAIN = "ITPD";
/**
* A constant representing the operator domain when returned from the
* method {@link ApplicationInfo#getProtectionDomain getProtectionDomain}
*/
public static final String OPERATOR_DOMAIN = "OPD";
/**
* A constant representing the unidentified third party domain when
* returned from the method {@link ApplicationInfo#getProtectionDomain
* getProtectionDomain}
*/
public static final String UNIDENTIFIED_THIRD_PARTY_DOMAIN = "UTPD";
/**
* A constant representing the MIDP runtime when
* returned from the method {@link ApplicationInfo#getRuntimeType
* getRuntimeType}
*/
public static final String RUNTIME_MIDP = "MIDP";
/**
* A constant representing the JavaInstaller runtime when
* returned from the method {@link ApplicationInfo#getRuntimeType
* getRuntimeType}
*/
public static final String RUNTIME_INSTALLER = "INSTALLER";
/**
* A constant representing the non managed runtime when
* returned from the method {@link ApplicationInfo#getRuntimeType
* getRuntimeType}.
*/
public static final String RUNTIME_NON_MANAGED = "NON_MANAGED";
/**
* A constant representing the eRCP runtime when
* returned from the method {@link ApplicationInfo#getRuntimeType
* getRuntimeType}.
*/
public static final String RUNTIME_ERCP = "ERCP";
/**
* Property name of the runtime implementation package end. It
* should be noted that ApplicationUtils class uses the same
* property for similar purposes as ApplicationInfo class does.
*/
static final String PACKAGE_END_PROPERTY_NAME = "com.nokia.rt.port";
/**
* Runtime implmentation package prefix. It should be noted that
* ApplicationUtils class uses the same property for similar purposes
* as ApplicationInfo class does.
*/
static final String PACKAGE_PREFIX = "com.nokia.mj.impl.rt.";
/**
* Name of the runtime specific class that extends this base class.
*/
private static final String PORTCLASS = ".ApplicationInfoImpl";
/**
* A singleton instance of runtime dependent instance of class extending
* the ApplicationInfo base class.
*/
private static ApplicationInfo sInstance = null;
/**
* When the class is first loaded the static initializer will create a
* singleton instance of runtime dependent instance of class extending the
* ApplicationInfo base class. The class is created using dynamic
* instantiation (<code>Class.forname & Class.newInstance</code>) and
* the name of the class is a combination of PACKAGE_PREFIX +
* <value of system property PACKAGE_END_PROPERTY_NAME >
* + .<value of PORTCLASS member variable >.
*/
static
{
//Get the system proptery defining the end of package.
String packageEnd = System.getProperty(PACKAGE_END_PROPERTY_NAME);
if (packageEnd == null)
{
throw new RuntimeException
("Not able to load " + PORTCLASS + "class since " +
PACKAGE_END_PROPERTY_NAME +
" system property is undefined");
}
//Construct the class
String className = PACKAGE_PREFIX + packageEnd + PORTCLASS;
try
{
Class clazz = Class.forName(className);
sInstance = (ApplicationInfo)clazz.newInstance();
}
catch (Exception e)
{
e.printStackTrace();
throw new RuntimeException("Not able to instantiate class " +
className+". Reason is: " + e);
}
}
/**
* Returns an instace of ApplicationInfo class which provides access to
* application related static information.
*
* @return the ApplicationInfo object, null if the construction of the
* object has faild
*/
public static ApplicationInfo getInstance()
{
return sInstance;
}
/**
* Returns the type of the runtime where in the application is run. There
* are three predefined runtime types that are represented by constants
*
* @see #RUNTIME_MIDP
* @see #RUNTIME_NON_MANAGED
* @see #RUNTIME_ERCP
*
*
* @return the runtime type as String. The return value should never be
* null
*/
public abstract String getRuntimeType();
/**
* Returns the protection domain of the application. There are four predefined
* protection domains that are represented by constants
*
* @see #MANUFACTURER_DOMAIN
* @see #IDENTIFIED_THIRD_PARTY_DOMAIN
* @see #OPERATOR_DOMAIN
* @see #UNIDENTIFIED_THIRD_PARTY_DOMAIN
*
* @return protection domain as String
*/
public abstract String getProtectionDomain();
/**
* Returns an unique application identifier.
*
* @return the Uid. The return value should never be null
*/
public abstract Uid getUid();
/**
* Returns a unique application suite identifier. The suite concept may be
* different in different runtimes and some of them might not support the
* concept at all.
* <p>
* Note: Please consider carefully if GetUid() would be enough for your
* purposes, earlier suite UIDs have been used extensively just for nothing.
* The OMJ code should use this method as little as feasibly possible.
* <p>
* @return the suite Uid if available, otherwise null.
*/
public abstract Uid getSuiteUid();
/**
* Returns the suite name of the application. The suite concept may be
* different in different runtimes and some of them migth not support the
* concept at all.
* <p>
* In MIDP this method returns the name of the MIDlet Suite.
*
*
* @return Suite name as String if available, otherwise null.
*/
public String getSuiteName()
{
return null;
}
/**
* Returns the name of the application. Some runtime implmentations
* might not return the value at all.
* <p>
* In MIDP this method returns the name of the MIDlet.
*
* @return application name as String if available, otherwise null.
*/
public String getName()
{
return null;
}
/**
* Returns the localized name of the application. Some runtime implmentations
* might not return the value at all.
* <p>
* In MIDP this method returns the localized name of the MIDlet,
* i.e. the value of Nokia-MIDlet-<n>-<locale>, for example
* Nokia-MIDlet-Name-es-MX: HolaMundo
*
* @return localized application name as String if available, otherwise null.
*/
public String getLocalizedName()
{
return null;
}
/**
* Returns the vendor of the application. Some runtime implmentations
* might not return the value at all.
*
* @return application vendor as String if available, otherwise null.
*/
public String getVendor()
{
return null;
}
/**
* Returns the version of the application. The format of the version is
* <code><main>.<major>.<minor></code> where
* <code>main</code>, <code>major</code> and <code>minor</code> are in
* decimal format.
* <p>
* Some runtime implmentations might not return the value at all.
* @return application version as String if available, otherwise null.
*/
public String getVersion()
{
return null;
}
/**
* Returns the root path of the application. The root path means an
* application specific directory where the different API implementations
* are able to write their files. No other applications are able access
* files under the root path.
* <p>
* API implemetations must not rely that the JAR file(s) or descriptor file
* can always be found from the root path even if they sometimes might be
* found.
* @return application root path as String
*/
public abstract String getRootPath();
/**
* Returns the main class of the application. The main class concept might
* differ between different runtimes. E.g. the in MIDP this method returns
* the class that extends the javax.microedition.MIDlet class.
* <p>
* Currently only known user for this is MIDP push.
*
* @return application main class as String
*/
public abstract String getMainClass();
/**
* Returns the attribute whose name is given as parameter. The attribute
* value is obtained from the JAR manifest file and/or some other
* descriptor (e.g. JAD file) using the runtime specific override rules.
*
* @param key Attribute key value.
*
* @return the attribute value as String if found, otherwise null.
*/
public abstract String getAttribute(String key);
}