Here is the comparison chart:
@JsExport @JsType
class MyClass {}
@JsType(exports=ALL)
class MyClass {}
@JsExport
class MyClass {}
@JsType(exports=STATIC_MEMBERS)
class MyClass {}
@JsExport(“Name”)
class MyClass {}
@JsType(name=”Name”, exports=STATIC_MEMBERS)
class MyClass {}
@JsExport(“Name”) @JsType
class MyClass {}
@JsType(name=”Name”, exports=ALL)
class MyClass {}
@JsType
class MyClass {}
@JsType(exports=INSTANCE_MEMBERS)
class MyClass {}
@JsType
interface MyInterface{}
@JsType(exports=INSTANCE_MEMBERS)
interface MyInterface{}
@JsType
interface ImportedLibrary{}
@JsType
interface ImportedLibrary{}
@JsType
interface ImportedLibraryCallback{}
@JsType(exports=INSTANCE_MEMBERS)
interface ImportedLibraryCallback{}
@JsExport
SomeConstructor{}
@JsExport
static void someStaticMethod{}
@JsExport
static Object someStaticField;
@JsConstructor(export=true)
SomeConstructor{}
@JsMethod(export=true)
static void someStaticMethod{}
@JsProperty(export=true)
static Object someStaticField;
@JsExport(“someName”)
static void someStaticMethod{}
@JsExport(“someName”)
static Object someStaticField;
@JsMethod(name=”someName”, export=true)
static void someStaticMethod{}
@JsProperty(name=”someName”, export=true)
static Object someStaticField;
@JsNoExport
static void someStaticMethod{}
@JsMethod(export=false) or @JsIgnore
static void someStaticMethod{}
@JsNoExport
void someMethod{}
@JsIgnore
void someMethod{}
@JsProperty
void someMethod{}
@JsProperty
void someMethod{}
@JsProperty(“someName”)
int someField;
@JsProperty(“someName”)
void someMethod{}
@JsProperty(name = “someName”)
int someField;
@JsProperty(name = “someName”)
void someMethod{}
On Tue, May 19, 2015 at 3:17 PM, Goktug Gokdogan <gok...@google.com> wrote:
> Thanks for the nice summary Ray.
>
> This is still work in progress but here is the tentative list of
> annotations and details of the new semantics. Please play with it and
> continue making suggestions.
>
> *@JsConstructor*
> JsConstructor marks a constructor so that it will be the constructor
> function for the JavaScript type. Note that, there could be only one
> JsConstructor in a type and all other constructors should be delegating to
> it.
>
> public @interface JsConstructor {
> /**
> * If a constructor is exported, then it will be not be pruned by the
> compiler.
> */
> boolean export() default false;
> }
>
> *@JsMethod*
> JsMethod marks a method in a type as a method that will be directly
> translated into a JavaScript method without any obfuscation to its name.
> Note that, while instance members are slotted in the prototype, class
> members will be defined under the constructor function of the type.
>
> public @interface JsMethod {
> /**
> * Customizes the name of the method in generated JavaScript. If not
> provided, the Java name will
> * be used.
> */
> String name() default "";
>
> /**
> * If a method is exported, then it will be not be pruned by the
> compiler. Note that if the class
> * is pruned then instance members will also be pruned even they are
> exported (i.e. exporting
> * instance members doesn't prevent class pruning).
> */
> boolean export() default false;
> }
>
> *@JsProperty:*
> JsProperty marks a field in a type as a method that will be directly
> translated into a javascript property without any obfuscation to its name.
> If it is applied to a method, it will be treated as a property accessor.
> As a result, instead of translating method calls to JsProperty methods as
> method calls in JS, they will be translated as property lookups. When a
> JsProperty method implemented by a Java class, such methods will be
> generated as custom property setter and getter in JavaScript, hence the
> property access will trigger the execution of the matching getter or setter
> methods.
>
> JsProperty follows JavaBean style naming convention to extract the default
> property name. If the JavaBean convention is not followed, the name should
> be set explicitly. For example:
> @JsProperty getX() or @JsProperty isX() translates as <tt>this.x</tt>
> @JsProperty setX(int y) translates as <tt>this.x=y</tt>
>
> Note that, while non-static member are slotted in the prototype, static
> members will be defined under the constructor function of the type.
>
> public @interface JsProperty {
> /**
> * Customizes the name of the member in generated javascript. If none is
> provided;
> * <p>
> * <li>if it is field, the simple Java name will be used.
> * <li>if it is a method, the name will be generated based on JavaBean
> conventions.
> */
> String name() default "";
>
> /**
> * If a method is exported, then it will be not be pruned by the
> compiler. Note that if the class
> * is pruned then non-static members will also be pruned even they are
> exported (i.e. exporting
> * non-static methods doesn't prevent class pruning).
> */
> boolean export() default false;
> }
>
> *@JsType:*
> JsType is used to describe the JavaScript API of an object, either one
> that already exists from the external JavaScript environment, or one that
> will be accessible from the external JavaScript environment.
>
> Marking an object with JsType is similar to marking each public member of
> the class with {@link JsProperty}/{@link JsMethod}/{@link JsConstructor}
> respectively. In order for this to work correctly the JavaScript name needs
> to be unique for each member. Some unobvious ways to cause such name
> collisions are:
> * Having method or constructor overloads.
> * Using the same name for a method and a field.
> * Shadowing a field from parent.
>
> A name collision needs to be avoided by providing a custom name (e.g.
> {@link JsProperty#name}) or
> by completely ignoring the member using {@link JsIgnore}.
>
> If the JsType is marked with a prototype reference, then classes extend
> from this will use the specified prototype as opposed to the ordinary one
> (e.g. java.lang.Object).
>
> JsTypes act like JavaScriptObject in terms of castability, except when a
> prototype is specified, in which case, cast checks and instanceof checks
> will be delegated to the native JavaScript instanceof operator.
>
> public @interface JsType {
> /**
> * Customizes the name of the type in generated javascript. If not
> provided, the simple Java name
> * will be used.
> */
> String name() default "";
>
> String prototype() default "";
>
> /**
> * Setting export here is a shortcut for setting export for each
> individual member of the class.
> * TODO: might replace with export={ALL, CLASS_MEMBERS,
> INSTANCE_MEMBERS} instead.
> */
> boolean export() default false;
> }
>
> *@JsIgnore:*
> Marks a member to be ignored for JsInterop purposes.
> This is particularly useful when {@link JsType} applied to a class and
> some members are needed to be ignored as they don't comply with
> restrictions (e.g. overloading) or shouldn't be exported.
>
> public @interface JsIgnore {
> }
>
> *@JsNamespace / @JsFunction:* No changes.
>
> *@JsExport / @JsNoExport:* Deleted.
>
> On Sat, May 9, 2015 at 6:35 PM, 'Ray Cromwell' via GWT Contributors <
> google-web-toolkit-contributors@googlegroups.com> wrote:
>
>> There are multiple things JsInterop needs to accomplish:
>>
>> 1) preventing method/field renames
>> 2) pinning methods (preventing code pruning)
>> 3) giving a global name/namespace alias to something
>> 4) auto-converting parameters to allow idiomatic programming
>> 5) allowing GWT objects to extend native objects
>>
>> @JsType actually combines #1/#2/#5 (although it only pins methods if the
>> object is instantiated)
>> @JsExport combines #2 and #3 (it not only pins a method, but treats the
>> type as instantiable, plus it gives it a global alias)
>>
>> #4 is handled by @JsConvert/JsAware/JsFunction
>>
>> #5 is handled by @JsType(prototype="...")
>>
>> Goktug is trying separate out the behavior into the 5 types of interop
>> semanics:
>>
>> 1) a way of indicating a method/field should not be renamed
>> 2) a way of indicating not to prune something
>> 3) a way of indicating giving a global alias to something
>> 4) a way of indicating something extends a native object
>>
>> There are cases where you want to prevent renaming, but allow dead code
>> elimination.
>>
>> You could make these separate annotations, that's matter of aesthetics,
>> e.g.
>>
>> @JsPin
>> @JsExport
>> @JsName
>> @JsPrototype
>>
>> etc
>>
>>
>>
>> On Sat, May 9, 2015 at 2:34 PM, Alex White <alexwhite3...@gmail.com>
>> wrote:
>>
>>> +1 to keeping the original system. For an interface a finite number of
>>> types > infinite number of String parameters.
>>> Once it gets properly documented on gwtproject.org I doubt people will
>>> consider it confusing. The problem imo is that most of the existing stuff
>>> out there is pseudocode.
>>>
>>> We just started using JsInterop and the only stumbling block we
>>> encountered was that at first we weren't using @JsNamespace.
>>> The other thing we have found is really weird bugs in some of the
>>> nightlies a few days ago, like types deleted from our codebase still
>>> existing and other new types not existing.
>>> It was from about 4-7 days ago and seems to have stopped now. It may be
>>> related to the sourcemaps. The emergent behavior was that after a hard
>>> cache reset Chrome would be trying to fetch a sourcemap for a deleted type.
>>> If we grepped for that symbol in our codebase, we would find references to
>>> it despite it being long gone in a cleanly built proj. Does the gwt
>>> compiler keep some state information hidden somewhere on the hd? Because
>>> that was weird.
>>>
>>>
>>>
>>> On Wednesday, April 22, 2015 at 4:42:10 AM UTC+10, Goktug Gokdogan wrote:
>>>
>>>> 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*
>>>> ...
>>>
>>> --
>>> 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/50de995a-3b18-4432-9b79-76ae51940729%40googlegroups.com
>>> <https://groups.google.com/d/msgid/google-web-toolkit-contributors/50de995a-3b18-4432-9b79-76ae51940729%40googlegroups.com?utm_medium=email&utm_source=footer>
>>> .
>>>
>>> For more options, visit https://groups.google.com/d/optout.
>>>
>>
>> --
>> 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/CAPVRV7cii4dCEdLWqK_-gL%2B4nSB57fCZp2mFzJSL1BUS_7-5aQ%40mail.gmail.com
>> <https://groups.google.com/d/msgid/google-web-toolkit-contributors/CAPVRV7cii4dCEdLWqK_-gL%2B4nSB57fCZp2mFzJSL1BUS_7-5aQ%40mail.gmail.com?utm_medium=email&utm_source=footer>
>> .
>>
>> For more options, visit https://groups.google.com/d/optout.
>>
>
>
--
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%3DyUA1WnH3WsQ-f0oHgbDTnTWW5wjS1mHREtD%3DxvDNxR_DbNg%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
