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 <[email protected]> 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 <
> [email protected]> 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 <[email protected]>
>> 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 [email protected]
>>> .
>>> 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 [email protected].
>> 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 [email protected].
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.
