There is some upcoming changes to JsInteorp in preparation toward v1.0
release.

The most major change is to the annotations and their meanings. Here is the
doc explaining the changes and the reasoning. We are looking for your
feedback, especially on alternatives.

































*Issues with existing design and annotations 1. @JsExport/@JsType slicing
is not intuitive for a lot of people esp. with gwt-exporter background.
People are confused about when to use what.2. There is no reason to why
@JsType doesn’t have any effect on the static methods. That is only because
of the original use cases that the design was tackling only cared about
well formed prototypal structures. Diving deeper into Elemental and
different javascript output styles, ability to define the full class
structure without exporting proves to be useful.3. @JsExport uses @JsType
to define the prototype structure. However this imposes unnecessary
restriction if/when there will be no javascript implementers of the @JsType
contract. @JsType that extends non-JsType is normally ok if it is not
implemented in js.4. You always need to fully qualify the name of the
export even if you just want to change the simple name.The New Annotation
SystemThere will be single annotation called @Js. Applying @Js to a member
is making that member available in javascript without any obfuscation.
However it is not safe from pruning if there are no references in java
code, so one needs to put enable exporting for the type if no pruning
wanted. Applying @Js at class level should considered as a shortcut to
apply @Js to all members. See following chart for the attributes and their
corresponding behavior:@JsType@Js(exports =
INSTANCE_MEMBERS)@JsFunction@Js(mode = FUNCTION)@JsLiteral@Js(mode =
LITERAL)@JsMethod@Js(name = "myName")@JsProperty@Js(property =
true)@Js(name = "myName", property = true)@JsNamespace@Js(namespace =
"mynamespace")@JsExport@Js(exports = STATIC_MEMBERS)@Js(name = “A”, exports
= ALL)@Js(name = “A”, namespace=”a.b.c.”, exports = ALL)// When applied to
a member@Js(export = true)@Js(name = “myName”, export =
true)@JsNoExport@Js(ignore=true)@JsOpaque@Js(opaque=true)See Appendix below
for a complete comparison to existing annotations.Semantics /
Implementation in GWTImplementation: - Apply all Js names as bridge methods
(or the reverse if Js extends Java object case
<https://groups.google.com/a/google.com/d/msg/gwt-users/i5KCHorBC6k/6wkPSuBBXBgJ>
needs to be supported).- Optimize away everything with regular optimization
rules if the member is not exported.- Generate export statements for all
pinned methods/classes.Usage: - Hybrid / Inbox use case needs to use @Js
with exports. This will make the whole object exported and not pruned.-
Regular library importing should use @Js with interfaces (no exports), if
it is a callback the @Js interface should be marked as exported so the
methods are not pruned when the object is not pruned.- Elemental needs to
use not exported Js types with prototype set and native methods.Checks -
mode and exports is only used in types.- export and ignore is only used in
members.- property is only used in methods.- name is only used in members
and types.- namespace is only used in exported static members, types and
packages.- mode=FUNCTION cannot have any attribute set.Considered
AlternativesAlternative 1:We could follow the above design but keep using
old annotations for class level annotations: - @Js(mode=OBJECT) -->
@JsType- @Js(mode=FUNCTION) --> @JsFunction- @Js(mode=LITERAL) -->
@JsLiteral- @Js(namespace=”...”) --> @JsNamespace- @JsMember for the
rest.Pros: - Reads well . (e.g. @JsType interface Element instead of @Js
interface Element { .. } ).- These modes are substantially different so
different annotations makes that explicit and helps to document.- Need to
add additional checks as attributes are mostly disjoint. e.g exports
doesn't apply to members, name/namespace isn't applicable for
Js(mode=LITERAL) etc.Cons: - Multiple annotations to learn.- Using
JsType/JsFunction/JsLiteral in the same type is forbidden but having single
annotations automatically enforces that.Alternative 2:We can introduce two
different concepts JsImport and JsExport. Both annotation will imply old
JsType behavior if applied at class level. It can be applied at method
level to provide method level customizations.The main advantage is that the
name implies what the developer is trying to achieve. If importing a
library or generating Elemental, @JsImport is used. For exporting code
@JsExport is used.However, it actually make things more confusing when it
comes to callbacks. In that case, an imported callback is actually an
export so @JsExport should be applied instead.The main issue is, unlike the
above designs it doesn’t let you configure your JS output without
introducing exports.@JsType@JsImport@JsFunction@JsImport(mode = FUNCTION)//
Another gotcha, here we are actually logically not importing always. If it
is to call some javascript code, it is for importing but when you implement
it in java, it is for exporting. So one can argue we should just keep it
@JsFunction.@JsLiteral@JsExport(mode =
LITERAL)@JsMethod{@JsImport/@JsExport}(name = "myName")// Another gotcha,
need to choose one depending on context so we should probably stick to
@JsExport/@JsName approach in the old
design@JsProperty@JsImport/JsExport(isProperty=true)@JsImport/JsExport(name
= "myName", isProperty=true)@JsNamespace@JsNamespace@JsExport@JsExport //
also implies old @JsType semantics@JsExport(name = “A”, pinned =
true)@JsExport(name = “A”, namespace=”a.b.c.”, pinned =
true)@JsNoExport@JsIgnore@JsOpaque@JsOpaque*

-- 
You received this message because you are subscribed to the Google Groups "GWT 
Contributors" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to google-web-toolkit-contributors+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/google-web-toolkit-contributors/CAN%3DyUA0-W8eqUUK1XUx_cr%3D-FsyYM7oeGrLEdHF6miMozzdGEw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

Reply via email to