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.
