Creating a new Device Importer
In this section, you will be learning how to create a device importer for a non Unified Emulator Interface (UEI) compliant SDKs.
Summary:
The device importer creation process is composed of the following tasks:
- Extend the
org.eclipse.mtj.core.deviceimporter
extension point;
- Implement the
org.eclipse.mtj.core.sdk.device.IDeviceImporter
interface;
Extending the org.eclipse.mtj.core.deviceimporter Extension Point
The 3 required extension fields must filled in:
-
id
: a fully-qualified identifier for this device importer
implementation.
-
priority
: define the priority order for this importer. The
priority may range from 1 to 99. The importers will be consulted in priority order starting with
the lower numbered priority and working toward the highest numbered priority. The first device
importer that requires a non-null result for a particular folder will "win" and no further
importer instances will be consulted.
-
class
: the implementation of the
org.eclipse.mtj.core.sdk.device.IDeviceImporter
interface.
An optional displayable name for this particular device importer may also be defined on the
name
field.
On the example bellow you'll find the declaration of a deviceimporter named
"ME4SE Device Importer":
<extension
point=
"org.eclipse.mtj.core.deviceimporter"
>
<importer
class=
"org.eclipse.mtj.examples.toolkits.me4se.ME4SEDeviceImporter"
id=
"org.eclipse.mtj.toolkit.me4se.importer"
name=
"ME4SE Device Importer"
priority=
"50"
/>
</extension>
Implementing the org.eclipse.mtj.core.sdk.device.IDeviceImporter interface
The
org.eclipse.mtj.core.sdk.device.IDeviceImporter
interface has
just one method to be implemented.
public List<IDevice> importDevices(File directory, IProgressMonitor monitor)
throws CoreException, InterruptedException;
The implementor is responsible for, given an existing file system directory, return a list of
org.eclipse.mtj.core.sdk.device.IDevice
instances available
in that directory.
On the example bellow you'll find the implementation of the IDeviceImporter for a
"ME4SE" SDK:
public class ME4SEDeviceImporter extends JavaEmulatorDeviceImporter {
// Various pieces of static information
private static final String EMULATOR_JAR_PREFIX = "me4se"; //$NON-NLS-1$
private static final String EMULATOR_JAR_SUFFIX = ".jar"; //$NON-NLS-1$
// Properties file holding emulator/device information
private static final String PROPS_FILE = "me4se.properties"; //$NON-NLS-1$
/* (non-Javadoc)
* @see org.eclipse.mtj.core.sdk.device.IDeviceImporter#importDevices(java.io.File, org.eclipse.core.runtime.IProgressMonitor)
*/
public List<IDevice> importDevices(File directory, IProgressMonitor monitor) {
ArrayList<IDevice> devices = null;
try {
File[] files = directory.listFiles(new FilenameFilter() {
public boolean accept(File dir, String name) {
return name.startsWith(EMULATOR_JAR_PREFIX)
&& name.endsWith(EMULATOR_JAR_SUFFIX);
}
});
// We should probably look more deeply into the jar, but this should
// do for now.
if ((files != null) && (files.length > 0)) {
IMIDPDevice device = createDevice(files[0]);
if (device != null) {
devices = new ArrayList<IDevice>(1);
devices.add(device);
}
}
} catch (Exception e) {
MTJLogger.log(IStatus.WARNING,
Messages.ME4SEDeviceImporter_importing_error, e);
}
return devices;
}
/**
* Add the device libraries.
*
* @param jarFile
* @param classpath
* @param importer
*/
private void addDeviceLibraries(File jarFile, IDeviceClasspath classpath,
ILibraryImporter importer) {
// Now add the player libraries
String classpathString = getDeviceProperties().getProperty(
JavaEmulatorDeviceProperties.CLASSPATH.toString(), //$NON-NLS-1$
Utils.EMPTY_STRING);
Map<String, String> replaceableParameters = new HashMap();
replaceableParameters.put("me4sejar", jarFile.toString()); //$NON-NLS-1$
classpathString = ReplaceableParametersProcessor
.processReplaceableValues(classpathString,
replaceableParameters);
String[] entries = classpathString.split(";"); //$NON-NLS-1$
for (String entrie : entries) {
IMIDPLibrary library = (IMIDPLibrary) importer
.createLibraryFor(new File(entrie));
// Because of the structure of the libraries,
// we need to hard-code the CLDC and MIDP API versions
IMIDPAPI api = library.getAPI(MIDPAPIType.CONFIGURATION);
if (api != null) {
api.setVersion(new Version("1.1")); //$NON-NLS-1$
}
api = library.getAPI(MIDPAPIType.PROFILE);
if (api != null) {
api.setVersion(new Version("2.0")); //$NON-NLS-1$
}
classpath.addEntry(library);
}
}
/**
* Create the new device instance for the specified ME4SE jar file.
*
* @param jarFile
* @return
*/
private IMIDPDevice createDevice(File jarFile) {
ME4SEDevice device = new ME4SEDevice();
device.setBundle(Activator.getDefault().getBundle().getSymbolicName());
device.setClasspath(getDeviceClasspath(jarFile));
device.setDebugServer(isDebugServer());
device.setDescription("ME4SE Device"); //$NON-NLS-1$
device.setDeviceProperties(new Properties());
device.setGroupName("ME4SE"); //$NON-NLS-1$
device.setName("ME4SE"); //$NON-NLS-1$
device.setPreverifier(getPreverifier(jarFile));
device.setProtectionDomains(new String[0]);
device.setLaunchCommandTemplate(getLaunchCommand());
device.setJarFile(jarFile);
ISymbolSet dss = MTJCore.getSymbolSetFactory()
.createSymbolSetFromDevice(device);
ISymbolSet pss = MTJCore.getSymbolSetFactory()
.createSymbolSetFromProperties(deviceProperties);
dss.add(pss.getSymbols());
dss.setName(device.getName());
device.setSymbolSet(dss);
return device;
}
/**
* Get the device classpath based on the specified player.jar file.
*
* @param jarFile
* @return
*/
private IDeviceClasspath getDeviceClasspath(File jarFile) {
IDeviceClasspath classpath = MTJCore.createNewDeviceClasspath();
addDeviceLibraries(jarFile, classpath, MTJCore
.getLibraryImporter(ILibraryImporter.LIBRARY_IMPORTER_UEI));
return classpath;
}
/* (non-Javadoc)
* @see org.eclipse.mtj.internal.core.sdk.device.JavaEmulatorDeviceImporter#getDevicePropertiesURL()
*/
@Override
protected URL getDevicePropertiesURL() {
return Activator.getDefault().getBundle().getEntry(PROPS_FILE);
}
}
How to access the deviceimporter implementations
The developer can access the available implementations through the MTJCore facade method
getDeviceFinder()
MTJ provides 3 implementations for the deviceimporter E.P., available in the
following plug-ins:
-
org.eclipse.mtj.toolkit.uei
responsible for importing all UEI
compatible SDK's (id org.eclipse.mtj.toolkit.uei.importer)
-
org.eclipse.mtj.toolkit.mpowerplayer
responsible for importing the
MPowerPlayer SDK (id org.eclipse.mtj.toolkit.mpowerplayer.importer)
-
org.eclipse.mtj.toolkit.microemu
responsible for importing the
MicroEmu SDK (id org.eclipse.mtj.toolkit.microemu.importer)
