ADD: delete method and set length property to NativeJavaList

[rPraml]

This change is extracted from #830 and adds support for delete and setting the length

• javaList.length = x I think this is clear. It will grow or truncate the underlying java list to given size.
• delete javaList[x] which effectively set the value in the wrapped javaList to null. (It will not remove elements, so the size of the list will stay the same)

Note: on the java side, we can not distinguish between null and undefined, So increasing the size will add null values in java vs. empty slots in JS.
The same is also true for delete javaList[x], it will be equivalent with javaList[x] = null

@tuchida you always have good objections:
I know the current implemetation is not exactly what the spec describes:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/delete
Especially in strict mode, delete javaList['length'] etc. should throw TypeError and should return true if element is deleted.

What I want to achive is, that delete on a javaList "works". Currently it is completely ignored. So I think, this implementation is an improvement.

(Btw: The same is for NativeJavaObject. Deleting properties should throw a TypeError)

Cheers
Roland

[tuchida]

Sounds good.

[tuchida]

By the way, what do you think Object.freeze and property descriptor should be?

var a = Object.freeze([1, 2, 3]);
a[1] = 123;
a;  // 1,2,3

var al = java.util.ArrayList([1, 2, 3]);
Object.freeze(al); // `-version 200` is required.
al[1] = 123;
al; // [1.0, 123.0, 3]

[tonygermano]

This seems dangerous since typical java Lists don't support sparse layouts like javascript arrays do. If you set length to a very large value on a javascript array it's no big deal, but do the same on an ArrayList, and you're probably going to run out of memory.

Should we at least add a javadoc description for the class that describes the additional behaviors which NativeJavaList adds to NativeJavaObject and potential pitfalls when using these features as if Lists were arrays? Is this stuff documented anywhere else other than in PRs and commit messages?

[gbrail]

Improving the Javadoc sounds great to me.

In general, the "embedding guide" is very very old and hasn't it been archived by Mozilla? Do we have any volunteers to resurrect it?

[rPraml]

How should we document this? JavaDoc, MD, wiki-page?

I would prefer a markdown documentation like this one: https://github.com/oracle/graaljs/blob/master/docs/user/JavaInteroperability.md

[tonygermano]

Personally, I think the javadoc should contain basic important information for using the class. Wiki/user guide type documentation is good for going into more detail if someone is willing to write that. As we know, external documentation is not always easily accessible and developers should have some idea how a class works without having to closely study the code or pull up external docs.

[rPraml]

I've added some documentation and using add instead of grow/set if last element is added to list

[rPraml]

@gbrail @tuchida @tonygermano
I wanted to ask if the PR can be merged or if there are still objections?

[tonygermano]

I'm ok with the added documentation.

[gbrail]

No, I think that this looks good now. Let me run another test to make sure.