[design]mayloon partial conversion
When an Android application being converted uses APIs not supported by the MayLoon runtime, the porting tool will convert this portion of code into stub classes / functions, and the conversion of code using supported APIs are not affected. These stub classes / functions, until executed, do not affect running of the resulting HTML5 application.
The stub functions should show alert dialog to user by default. Application developers also have the option to turn on/off the partial conversion feature by setting mayloon project configuration file.
The motivation of the feature is to allow application developers to justify their effort to be spent on MayLoon as early as possible and to reduce the effect that application developers merge their customized API into mayloon framework from Java/Javascript side.
There are several cases to consider.
Native methods will be done on "convert to mayloon application" step, no other material need to be prepared by mayloon dev team.
If there is a native method in the application code,
public native final int addAssetPath(String path);it should be converted to a stub method, with the same name addAssetPath and parameters, within the original class. Note that this applies to not only public ones but also internal ones.
/**
* @j2sNative
* alert("Missing native method: addAssetPath");
* console.log("Missing native method: addAssetPath");
*/
@MayloonStubAnnotation
public final int addAssetPath(String path) {
System.out.println("Stub Funtion: addAssetPath");
return 0;
}If a method is missing from the MayLoon runtime, invocation on that method will show an alert dialog to user
Example, suppose
android.view.MenuItem.getItemId()is not supported, then any reference to this method in the source application will be located in mayloon-runtime framework as the following:
// stub call for android.view.MenuItem.getItemId
android.view.MenuItem.getItemId_stub();/*
* stub Clss for android.view.MenuItem
*/
public class MenuItem {
/*
* @j2sNative
* alert("Missing method: getItemId");
* console.log("Missing method: getItemId");
*/
@MayloonStubAnnotation
public void getItemId_stub() {
System.out.println("Stub Function: getItemId");
return;
}
}Miss Method partial conversion feature is supported by mayloon-runtime javascript framework. some method should be done on the generation of mayloon-runtime javascript framework.
- Get official android 2.3.3_r1 source code from mayloon-runtime git
android-2.3.3_r1-sources.zip
1.1 extract it to any folder in your local disk
see figure, partial_conversion_1.gif
- Get MayloonFrameworkSourceParser python project from mayloon-runtime git
2.1 import this python project to eclipse IDE (pydev plugin is installed), run it with two parameters as figure, partial_conversion_2_1.gif
parameter 1 is csv file which is output of mayloon-runtime method coverage tool
parameter 2 is file path which is extracted in step 1.1
2.2 after run this python script, you will get some android official java files which is implemented in mayloon-runtime, those unimplemented files are removed by it.
2.3 copy generated file mayloon_class.json to C:\\Dev\\mayloon\\mayloon_sdk\\, it will be used in future(step 3)
- Get MayloonFrameworkParser plugin and com.intel.ide.eclipse.mpt.gson from mayloon-runtime git
3.1 import them to eclipse IDE(3.7.2 RCP)
see figure, partial_conversion_3_1.gif
3.2 after build them successful, run MayloonFrameworkParser as "Eclipse Application"
see figure, partial_conversion_3_2.gif
3.3 create a new java project(named MayloonRuntimeStubGen) in new opened runtime eclipse workspace, and import source files gotten from 2.2 into it.
see figure, partial_conversion_3_3.gif
3.4 build MayloonRuntimeStubGen project, stub method will be add to the end of java file.
see figure, partial_conversion_3_4.gif
- Get MayloonRuntimeStubFilesLineParser python project from mayloon-runtime git
4.1 import this python project to eclipse IDE (pydev plugin is installed), run it with two parameters as figure, partial_conversion_4_1.gif
parameter 1 is source code folder which generated by step 3.3
4.2 after run this python script, you will get one json file named mayloon_stub_info.json which include all stub method code start and end line information.
- Get MayloonRuntimeLineParser python project from mayloon-runtime git
5.1 import this python project to eclipse IDE (pydev plugin is installed), run it with two parameters as figure, partial_conversion_5_1.gif
parameter 1 is a source code folder which located in com.intel.jsdroid/src/android
5.2 after run this python script, you will get one json file named mayloon_class_insert_info.json which include line information about all stub method code should be inserted to.
- Get MayloonFrameworkPatchGenerator python project from mayloon-runtime git
6.1 import this python project to eclipse IDE (pydev plugin is installed), run it with two parameters as figure, partial_conversion_6_1.gif
parameter 1 is a json file generated in step 5.2
parameter 2 is a json file generated in step 4.2
6.2 after run this python script, some of patch files will be generated in com.intel.jsdroid/src/android/xxx folder
for example, Activity.java_patch will be generated in com.intel.jsdroid/src/android/app/ folder. see figure partial_conversion_6_2.gif
- Get MayloonFrameworkPatchApply python project from mayloon-runtime git
7.1 install patch-2.5.9-7-setup.exe to C:\GnuWin32, you can get it from http://sourceforge.net/projects/gnuwin32/files/patch/2.5.9-7/
7.2 import this python project to eclipse IDE (pydev plugin is installed), run it with two parameters as figure, partial_conversion_7_1.gif
parameter 1 is a json file generated in step 5.2
parameter 2 is a json file generated in step 4.2
7.3 after run this python script, all patch files generated by step 6.2 would be apply to java file based on file basename
- import com.intel.jsdroid project which is applied all patch from step 7
8.1 fixs all errors in this project by manual
If a class is missing from the MayLoon runtime, or the application being converted uses extension to the Android framework, e.g. in the following scenario,
import android.view.UnimplementedView;
UnimplementedView instance = new UnimplementedView();
instance.methodA();the missing class should be converted to a stub class of the same name UnimplementedView, with three constructor stub method only. other method members will not be generated automatically.
And we will generate UnimpementedView.java file in android.view package.
package android.view package;
/*
* stub Clss for android.view.UnimplementedView
*/
public class UnimplementedView{
/**
* @j2sNative
* alert("Missing method: UnimplementedView");
* console.log("Missing method: UnimplementedView");
*/
@MayloonStubAnnotation
public UnimplementedView() {
}
/**
* @j2sNative
* alert("Missing method: UnimplementedView");
* console.log("Missing method: UnimplementedView");
*/
@MayloonStubAnnotation
public UnimplementedView(Object arg) {
}
/**
* @j2sNative
* alert("Missing method: UnimplementedView");
* console.log("Missing method: UnimplementedView");
*/
@MayloonStubAnnotation
public UnimplementedView(Object arg, Object arg1) {
}
}This is similiar to missing method, we will generate an empty stub class (with the @Override in it).
This is similiar to missing class, we will generate an empty stub Interface with all methods in correct package.
We will extend the org.eclipse.jdt.core.compiler.CompilationParticipant extension-point to inject into JDT compile logic. By doing this, we can: create customized java compilation unit for user android application generate AST from application get all necessary information about compilation error(especially unsupport api related) generate stub class/function for these unsupport APIs by rewriting user’s java/javascript source
When we generate stub class/function for unsupport API, there are two kinds of scenario should be considered: 1. Customer implemented the extension API 2. Mayloon Runtime unimplemented android framework API
For 1, we suggest that user should merge these extension API source to their android application at first, then using our mayloon porting tool to perform normal java to javascript conversion.
For 2, we will generate stub code in both java and runtime javascript side as follows:
Note:
a. in conversion logic, when partial conversion is enabled, MPT will inject into JDT by extending CompilationParticipant extension-point for retrieving compile
errors from JDT. In this stage, MPT will not add Mayloon related buildcommand & build nature to user's application, these mayloon customized buildcommand&nature
will add to user's application after stub code is generated successfully.
TBD