Hi Shane,
Let me think a bit more on the validation technology (JDT-APT vs.
EMF)
Regarding the annotation API. The WS DOM tools need to be able
to add, remove and update annotations and their properties. Whether we would
use AnnotationWriter or AnnotationUtils doesn’t really
matter.
TextFileChange/TextEdit along their undo features sounds great.
I would personally prefer having a return value rather than having an
input-output parameter (i.e. would vote for public static TextEdit
addAnnotation(IJavaElement javaElement, Annotation annotation) throws CoreException).
I would also prefer to have an interface for the annotation
utility (e.g. IAnnotationUtil) and to have nonstatic method in the
implementation. The benefit of the interface and nonstatic methods is that they
ease a lot JUnit tests implementation. Also, static methods do not allow
overriding which is quite painful when a static method provides _almost_
what you need.
Best regards, Danail
From: wtp-incubator-dev-bounces@xxxxxxxxxxx
[mailto:wtp-incubator-dev-bounces@xxxxxxxxxxx] On Behalf Of shane clarke
Sent: Sunday, October 11, 2009 9:59 PM
To: wtp-incubator-dev@xxxxxxxxxxx
Subject: [JUNK]RE: [wtp-incubator-dev] Integrating the JAX-WS DOM Tools
contribution
Hi Danail,
>As the source code is now available in the CVS we should
start thinking of integrating it with the surrounding environment in order to
achieve a consistent user experience.
>I had a quick look at the current web service annotation
tools and found a couple of points which are common for both CFX and WS DOM
tools but are implemented in different manner. I think that we should combine
the best features of both and remove duplications
Yes +1 to removing duplication and unifying
the code bases.
1.
Validation
> I am
not a JDT-APT expert and could not tell the advantages which JDT-APT offers
I wouldn't
consider myself a JDT-APT expert but some of the advantages of using it are:
- It
ships as a standard part of JDT.
- Configurable on any Java
based project (Regular Java Project, Dynamic Web, EJB) using the API or in
a projects properties page (Java Compiler > Annotation Processing)
- APIs
for analyzing annotations and the java elements they are applied
to.
- APIs for logging error,
warning and info messages along with marking those messages as being
quick-fixable.
- Processors executed during
compilation. Both reconcile (interactive, feedback as you type) and during
the build. Again configurable, you can turn off the 'reconcile'
processing.
- We don't use it but there
is a capability there to generate additional types and other resources
during processor execution.
And some of the disadvantages are:
- Another
API to learn.
- Possible
to cause performance issues with badly designed processors executing long
running operations etc..
- We
don't have a way of letting the user enable or disable individual processors
or categories of processors that are contributed through the
org.eclipse.jst.ws.annotations.core.annotationProcessor extension point.
We need a preference page for this similar to the 'Model Validation >
Constraints' preference page.
2.
Properties view
>
I do have certain worries that usability experts would dislike having two
property views (the standard one and the annotations one) and would prefer the
annotations to be displayed in the standard properties view.
This has been looked at in the past. There is another annotations view which is
form based in the WTP Dali sub-project. They've looked at having the Java
Editor activate the tabbed properties view where contributors can then add
there own tabs for configuring their annotations. But it looks to be currently
blocked and has been for a while.
https://bugs.eclipse.org/bugs/show_bug.cgi?id=154781
https://bugs.eclipse.org/bugs/show_bug.cgi?id=162079
We should look into it. But with limited time and resources i don't think it's
achievable for 1.0
Something else to think about here. If this solution was open to us now in
Eclipse 3.6 and we went with it, it would set the minimum requirements for the
tooling to that level which would have an impact on current adopters disabling
their use of the annotations view if they were shipping a product built on a
version of Eclipse less than 3.6.
3.
Annotation API
>From
my point of view the interface this utility is pretty complex.
Yes the org.eclipse.jst.ws.annotations.core.utils.AnnotationUtils
class is unnecessarily complex at the moment. That method signature can be
reduced to:
public static void
addAnnotationToField(IField field, Annotation annotation, TextFileChange
textFileChange) throws CoreException
You
could also provide something like:
public static void
addAnnotation(IJavaElement javaElement, Annotation annotation, TextFileChange
textFileChange) throws CoreException
and
then switch on the Java element type calling the appropriate method.
We
use the org.eclipse.ltk.core.refactoring.* classes to manage adding the
annotations and also to provide undo support. This is where the TextFileChange
comes into play. That TextFileChange is also used to 'preview' the
annotation changes in the wizard.
We
could look to remove that TextFileChange parameter from the method signature
and return a TextEdit which can then be used by the method callers to create a
TextFileChange. So you'd end up with something like:
public static TextEdit
addAnnotation(IJavaElement javaElement, Annotation annotation) throws CoreException
Looking
at the org.eclipse.jst.ws.jaxws.utils.annotations.AnnotationWriter class
we do have the additional requirement of having to add/remove annotations from
package declarations (for JAXB). Also, updating an annotation with that class
could make the annotation jump position in the Java Editor. We need to be able
to update a member value pair without the possibility of a change in position.
We
also used the same method to write the annotations to the underlying file in an
earlier version of the tools. This caused intermittent problems in the wizard
when adding multiple annotations while also handling the undo support directly
with the UndoEdit's returned for TextEdit.apply().
>So does the tools unification makes sense to you?
Yes.
> If yes, we should come up with a plan what/when to refactor
So
we need to make a decision on the validation route to continue with and which
Annotation utility class to rework/refactor so that it works for all plug-ins and
preserves existing functionality.
For
the validation i'd prefer to stay with JDT-APT. I haven't had a chance yet to
modify the JAX-WS DOM validation unit tests to see if the existing JDT-APT
validation rules handle all those cases. I'll try and do that soon.
For the Annotation API. I was looking to clean up the public API's i listed
here http://wiki.eclipse.org/JAXWS/Tools_API_Catalog
for this M3 milestone as i go through them adding javadoc.
Could
a more simplified API in org.eclipse.jst.ws.annotations.core.utils.AnnotationUtils
like the changes i mentioned above work for the JAX-WS DOM section of the
tooling?
Thanks,
Shane
From: danail.branekov@xxxxxxx
To: wtp-incubator-dev@xxxxxxxxxxx
Date: Thu, 8 Oct 2009 17:09:57 +0200
Subject: RE: [wtp-incubator-dev] Integrating the JAX-WS DOM Tools contribution
Hi,
As the source code is now available in the CVS we should start
thinking of integrating it with the surrounding environment in order to achieve
a consistent user experience.
I had a quick look at the current web service annotation tools
and found a couple of points which are common for both CFX and WS DOM tools but
are implemented in different manner. I think that we should combine the best
features of both and remove duplications
1.
Validation
a.
The CFX validation plugs into java compilation process via
JDT-APT, analyzes the annotations in the java class and generates error markers
if necessary
b. WS DOM validation is implemented as an EMF validator. The
implementation would check the current state of the web service model and would
return status (org.eclipse.core.runtime.IStatus) objects. Creating error
markers in case of status with severity of ERROR is responsibility of
the EMF validation framework and the corresponding contributors.
We obviously do not need two validation implementations as
multiple similar error markers can confuse the user. I am not a JDT-APT expert
and could not tell the advantages which JDT-APT offers. But I could point out
the advantages provided by the WS DOM implementation:
-
The implementation is not bound to a specific component (e.g.
java build). It would only analyze the current WS model and will return status
objects. Whether error markers are generated or not is a matter of further
processing. Thus a validation user code could decide what to do with these
errors – generate error markers or for example try to fix the errors on
the fly
-
The validation is performed on the web service model. The web
service model updates itself upon resource change and “reconcile”
events thus giving adequate representation of the current source code (no
matter built or not). With a model which is up to date, an user (no
matter human or API) can trigger validation of the current source code and get
the validation results immediately
-
The validation can be managed centrally (via Window ->
Preferences -> Validation)
2.
Properties view
a.
CFX provides its own annotation view which shows all the
annotations relevant for the current selection. The user can turn on/off a
given annotation and can change its attributes. I think that it is a pretty
powerful tool. However, I do have certain worries that usability experts would
dislike having two property views (the standard one and the annotations one)
and would prefer the annotations to be displayed in the standard properties
view.
b.
WS DOM plugins contribute pages to the standard properties view
for the WS model artifacts but provides much less information than the
annotation properties view does. Also, the editing support is pretty limited
3.
Annotation API
a.
CFX uses the org.eclipse.jst.ws.annotations.core.utils.AnnotationUtils
class to create and modify annotations. From my point of view the interface
this utility is pretty complex. For example, here is the signature of a random
method:
public static void
addAnnotationToField(ICompilationUnit source, CompilationUnit compilationUnit,
ASTRewrite rewriter, IField field, Annotation annotation, TextFileChange
textFileChange) throws CoreException
The method has lots of input parameters and I personally find it
hard to get instances of everything I need to call this method
b.
WS DOM comes with the org.eclipse.jst.ws.jaxws.utils.annotations.AnnotationWriter
utility class. Here is the equivalent method for adding annotations:
public <T extends
IJavaElement> void setAppliedElement(final
IAnnotation<T> annotation, final T javaElement) throws
AnnotationGeneratorException
As
you can see, the method signature is pretty simple – it only says
“please apply this annotation to that java element”
So does the tools unification makes sense to you? If yes, we
should come up with a plan what/when to refactor
Best regards, Danail
Get
the next generation of Free Windows Live Services Click here!