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!
|