[Proposal] Use custom classes required at compile time (e.g. Activity, Application, etc.)

[slavchev]

Overview

In Android development it is a standard practice to use inheritance to create custom activities, applications and other components. Currently NativeScript runtime for Android ({N}) has limited support for this scenario. This proposal aims to provide a solution for creating custom activities, applications and other components.

Note: for the sake of this proposal I use the common scenario to extend an activity class.

Current State

{N} provides built-in NativeScriptApplication and NativeScriptActivity classes. While these classes helped the adoption of {N} they also provide limitations. Currently it is not possible to inherit from a third party activity or other types which are used in AndroidManifest.xml file.

Technical Details

Here is how a Java class is extended in {N}

// app/myactivity.js
var MyActivity = android.app.Activity.extend({
   onCreate: function(bundle) {
      // implementation
   }
});

However MyActivity class is generated at runtime by {N} bridge. This mean you cannot use MyActivity in AndroidManifest.xml the way we currently use NativeScriptActivity for example.

<!-- AndroidManifest.xml -->
<activity
    android:name="com.tns.NativeScriptActivity"
    android:label="TestApp">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

Proposal

The current extend implementation can accept two parameters as well. We can rewrite the previous example as follows

// app/myactivity.js
var MyActivity = android.app.Activity.extend("MyActivity", {
   onCreate: function(bundle) {
      // implementation
   }
});

We can leverage the latter syntax of extend function and pass the fully qualified type name of the new class as follows

// app/myactivity.js
var MyActivity = android.app.Activity.extend("com.example.MyActivity", {
   onCreate: function(bundle) {
      // implementation
   }
});

During build time we can parse the JavaScript and generate Java file com/example/MyActivity.java. This proposal will not make the existing code ambiguous because currently there is a validation rule that says the class name cannot contain . symbol. The generated MyActivity.java file will look as follows

// com/example/MyActivity.java
package com.example;

@com.tns.JavaScriptImplementation(javaScriptFile = "app/myactivity.js")
public class MyActivity extends android.app.Activity {
   public MyActivity() {
      com.tns.Platform.initInstance(this);
   }
   public void onCreate(android.os.Bundle param_0) {
      Object[] args = new Object[1];
      args[0] = param_0;
      com.tns.Platform.callJSMethod(this, "onCreate", void.class, args);
   }
}

This is how the currently runtime generated types look like. We can provide a tool that generates equivalent types at build time. The only difference is the use of com.tns.JavaScriptImplementation annotation. The need a way to find the JavaScript implementation for MyActivity when an instance is created. Using annotation is just one possible approach. I find it clear and, more importantly, I find it aligned with the following proposition how to extend Java class in TypeScript.

// myactivity.ts
@JavaProxy("com.tns.MyActivity")
class MyActivity extends android.app.Activity {
   onCreate(bundle: android.os.Bundle)  {
      // implementation
   }
}

Using ES6/TypeScript decorators is a simple way to indicate that we have to generate Java class at build time. The main benefit of using decorators is that the change is less obtrusive than other alternatives.

Impact

This proposal will require {N} modules to change the way an application is initialized and activities are created. I expect that this would be small-to-medium change. The immediate benefits are better encapsulation and control. Also, it may require {N} modules to come with prebuilt Activity and Application classes. Another approach would be adding these classes to the project template.

Summary

This proposal has some other benefits as well. Removing NativeScriptActivity and NativeScriptApplication from {N} will allows us to support lower Android API levels. Currently we have to compile against API level 17 and there is no technical justification for that. Also it will allow embedding {N} in other applications much easier. One primary scenario is NativeScript companion app.

Finally, you can find a prototype here

[gordonpro]

! + 1

[gordonpro]

IS the NativeScript companion app open source?

[slavchev]

Hi @gordonpro

NativeScript companion app is not open-sourced as it is used with Telerik AppBuilder services which are part of Telerik paid offerings. Also, currently {N} runtime has some Telerik AppBuilder related logic in order to make the integration between the two products. This proposal will help us to remove all AppBuilder specific logic from {N} runtime. Essentially, it will make {N} much more easy to embed whether it is NativeScript companion app or something else.

[sitefinitysteve]

+1 need to implement an interface asap for a plugin

[jlooper]

Boosting the volume on this so we can get the Auth0 plugin working for Android. Pretty please.

[gordonpro]

@slavchev
This will let {N} Easy to embed with present app codebase.
Is there a approximate release date of this plan ？

[slavchev]

@gordonpro It is hard to say because it is a cross-team effort. The work on the android runtime side is already done and the prototype works as expected. The only unclear thing is how we are going to distribute the Java stuff which our modules depend on. ping @teobugslayer @hshristov

[katturajam]

I have tried this proposal but i am facing error "com.example.MyActivity" class is not found. kindly provide steps to create custom activity class.

[slavchev]

@katturajam

I haven't been clear enough. Both com.tns.MyApp and com.tns.MyActivity (the above com.example.MyActivity is just an example) will be generated at build time. In my prototype I wrote these files manually (you can find them at https://github.com/NativeScript/android-runtime/tree/slavchev/new-project-template2/test-app/src/com/tns). Currently our plan is to provide a new tool that will be seamlessly integrated in tns build command the will generate all *.java files. In short, this tool will parse your JavaScript source code and every time it finds ES5 extend or ES6 extends syntax it will generate the required *.java file. It is important these *.java files to be generated so the build can compiled and dex them. Otherwise, you cannot cite them in the AndroidManifest.xml file.

[slavchev]

Just a quick update: we won't manage to ship this feature with the upcoming 1.6 release. While the functionality is implemented we need more time for proper testing.

[slavchev]

@NathanaelA Most of the code is public (PRs and some branches, the changes for metadata generator are in the master branch already). The only thing that is private is the modified static binding generator. It is a matter of a week or two to integrate all parts in a single feature.

[katturajam]

@slavchev

https://github.com/NativeScript/android-runtime/tree/slavchev/new-project-template2/test-app/src/com/tns

gradle packar -PwidgetsPath=./widgets.jar

I am facing error when i was build android-runtime

[x86] SharedLibrary : libNativeScript.so
[x86] Install : libNativeScript.so => libs/x86/libNativeScript.so
:copyCppRuntime
:cleanCppRuntime
:revertNdkConfigurationfatal: Not a git repository (or any of the parent directories): .git
FAILED

FAILURE: Build failed with an exception.

• What went wrong:
  Execution failed for task ':revertNdkConfiguration'.

  Process 'command 'git'' finished with non-zero exit value 128

[Plamen5kov]

hi, @katturajam
here is something that can help you out: link
and you can read more about git repositories here: link

[katturajam]

Great. Good News. Awesome.

[ghost]

@slavchev any updates on this?

[slavchev]

#364 is already merged into master branch so it
will be released with 1.7 release.

[ghost]

:)

[Plamen5kov]

related to: #250

[sitefinitysteve]

Are we able to add another build step to maybe copy over the .java files...? So like have a custom folder (maybe under App_Resource/android) where we can put our custom files... modifying the NativeScriptApplication/Activity files in the platform folder is becoming tedious here... :/

[sitefinitysteve]

@NathanaelA I kinda want this to be just a thing "that just works" though... I don't want my plugin install step to be "Go install another plugin, and add this to it". Like this PR opened up the ability for us to modify these files, but in the worst possible place. Would make more sense to modify them externally and have it copied over. So in that case the step would be simply, "Take the .java files from here https://github.com/sitefinitysteve/nativescript-auth0/tree/master/plugin/platforms/android and paste them into X folder). This would then let the dev modify them further to maybe do things for multiple plugins.

...I dunno, anything but /platforms/android

[sitefinitysteve]

@NathanaelA GOTCHA! :D ...so onboard with the original idea?

[slavchev]

@NathanaelA @sitefinitysteve

Guys, let me shed some light on what the original idea is. Also it would be awesome if you provide feedback.

Firstly, because of the time pressure for 1.7.0 we released only a half of what was initially intended. As I wrote in the proposal, we intended to ship a tool which parses *.js and *.ts files and generates *.java source files during build time. The good news is that the tool is ready and we tested it with the current modules. So far it generates correct *.java files which are compiled as expected. I guess we will open the tool repo these days and it won't take long to integrate it in the gradle build scripts.

Secondly, we wanted to keep the change as small as possible and right now the *.java files are manually coded. We wanted to see how this proposal will work in real-world scenarios, and indeed it turns out to be a bumpy road. Hopefully, tomorrow we will release 1.7.1 which will fix the most critical issues.

With that said, our assumption was that {N} developers prefer to write JavaScript/TypeScript and try to avoid platform specific code such as Java. Also, we assumed that {N} developers will hate to see *.java files in the project folder. So far it seems that we are wrong in our assumptions. To be honest, we had some brief internal discussions about providing special folders for platform specific source code but never came with a final decision. One of our ideas was to generate *.java files with a 1970-1-1 time stamp and once the developer edit a file we skip any further generation for this file until the developer specifies explicitly his/her intent. Another approach worth exploring is providing "partial" classes or something similar. So, to put it in another words we are open for any suggestions.

[sitefinitysteve]

@slavchev NONO, I very much hate running\writing .java! :)

However for this auth0 plugin I need to do it, and even though it's my plugin I'm getting annoying with having to keep going back and "fixing" these files on a platform add\remove...

[Plamen5kov]

@NathanaelA I very much like the idea for a .java file to be created from several .js files, but I am wandering if two plugins declare

function OnRequestPermission(a,b) { 
// do something
}

How should we know which one to include and use in the project. I'm thinking if there is a way to create one .java file from several .js files it will be something like partial classes, and we can come up with a convention to follow in such cases, but we need to consider all scenarios.