Community
Participate
Working Groups
Annotation value matching like this is completely undocumented: @Target(value={ElementType.METHOD,ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) public @interface MyAnnotation { int value(); String name() default ""; Class<?> type() default Object.class; } ------------------------------------------------------------ @Before("execution(* *(..)) && @annotation(RequestMapping(name))") public void logName(JoinPoint thisJoinPoint, String name) { System.out.println(" name = '" + name + "'"); } @Before("execution(@MyAnnotation(value=11) * *(..))") public void logName(JoinPoint thisJoinPoint) { System.out.println(" @MyAnnotation(value=11) detected"); } @Before("execution(@MyAnnotation(value=11, name=\"John Doe\", type=String.class) * *(..)) && @annotation(myAnnotation)") public void logName(JoinPoint thisJoinPoint, MyAnnotation myAnnotation) { System.out.println(" " + myAnnotation); } ------------------------------------------------------------ I do not even remember where I got the information from, definitely not from the AspectJ documentation and also not from any of the many release notes (README-xxx.html). Maybe I found it in some tests in the AspectJ source code. The only thing mentioned in release READMEs is how to match on the annotation's 'value' parameter without naming it and how to bind the value (not the annotation itself) to a parameter, see also: https://www.eclipse.org/aspectj/doc/released/README-160.html https://www.eclipse.org/aspectj/doc/released/README-161.html https://www.eclipse.org/aspectj/doc/released/README-1612.html Only in the latter there is a mention in passing with regard to using '=' vs. '!=' for annotation value matching with examples like: get(@Anno(someValue=1) * *) || get(@Anno(someValue=3) * *) get(@Anno(someValue!=2) * *) I think this is a powerful feature going unnoticed. Sometimes I answer questions about it on StackOverflow, just like today: https://stackoverflow.com/a/61165990/1082681 I always have to search my list of sample projects in order to find it. Sorry Andy, I know you do not have enough time for this kind of thing, but why add features and then not document them? Maybe some of your supporting co-workers can do this for you and benefit everyone using AspectJ or Spring AOP. I think that going through the release READMEs or - even better - through the list of resolved tickets per release step by step would uncover more of those undocumented gems.
Oh, and I know that I could do it myself, creating PRs. I did create one sample PR (just some .gitignore improvements) on GitHub months ago just in order to see if someone might notice and merge it and if it works with the e-mail address registered there and with which I signed the Eclipse contributor's agreement long ago. But it was not noticed or commented upon. Furthermore I think I offered two or three times already to contribute more with regard to mavenising the project (which then you did alone) *after* you personally would have on-boarded me and explained the project structure and build process to me. This is what kept me from contributing, and I don't want to be a documentation buddy only. No offence meant, I am just explaining the consequences of not on-boarding me back then.
One more undocumented feature is method parameter annotation matching. Method parameter *type* matching à la execution(* *(@MyAnn *)) is documented here: https://www.eclipse.org/aspectj/doc/next/adk15notebook/annotations-pointcuts-and-advice.html#methodPatterns But in the same chapter there is not clue of execution(* *(@MyAnn (*))) which should also be documented there. BTW, not for the first time I just answered a question on SO here: https://stackoverflow.com/a/61284425/1082681
As I try and get 1.9.6 (java14) done, saw this! > Sorry Andy, I know you do not have enough time for this kind of thing, but why add features and then not document them? I don't quite see the missing thing? You are combining direct value binding (readme 1612) with explicit value matching (readme160) - is that the issue that they haven't been documented as usuable/valuable together? That would be an oversight, and yes would have been addressed if these had been merged into base docs rather than kept separate. > Oh, and I know that I could do it myself, creating PRs. I did create one sample PR (just some .gitignore improvements) on GitHub months ago just in order to see if someone might notice and merge it and if it works with the e-mail address registered there and with which I signed the Eclipse contributor's agreement long ago. But it was not noticed or commented upon. Sorry I missed that, I have had so few PRs over the years that I don't even check for them anymore. As I go looking at github just now I see a bunch there now, more than I expected. I think one problem here is still using horribly crumbly old bugzilla. We should be on github with github issues, if I were in there more often I'd actually be noticing things like that. > Furthermore I think I offered two or three times already to contribute more with regard to mavenising the project (which then you did alone) *after* you personally would have on-boarded me and explained the project structure and build process to me. This is what kept me from contributing, and I don't want to be a documentation buddy only. No offence meant, I am just explaining the consequences of not on-boarding me back then. I would have been embarrassed to onboard you into the previous process, it needed a lot of work and was a lot of magic that I didn't really understand until I got into the weeds. I basically had to onboard myself into it first. On the parameter annotation type matching, I guess that is you saying it isn't in the 'main docs' because it is covered in the 160 readme. Yep, it should be in the main docs. What is killing me these days is the frequency of Java releases - all cycles i have to progress anything end up taken up with doing that, as it is another arcane process. Thanks again for keeping on top of stack overflow questions!!
"No documented outside read-me files" is what I describe as undocumented. As for the first issue, even in the read-me files is is not explicitly documented and easy to overlook. You are mentioning improvements in 1.6.12 for RC1 for something that was never mentioned before in any read-me or official documentation. So this counts as undocumented IMO. > Prior to this change it was only possible to specify an annotation match like this: > > get(@Anno(someValue=1) * *) || get(@Anno(someValue=3) * *) > > Now it is possible to use != and write this: > > get(@Anno(someValue!=2) * *) This is the only place where - noticing 'someValue=1' - I see that there even exists a syntax to match anything other than an annotations default 'value' parameter. Even the small sample code I provided explains it better. And I repeat: Don't do everything by yourself, let somebody help you! ------------------------------------------------------------ As for the second issue of parameter annotation matching, it is not even documented in the release notes AFAIK and definitely not in the mentioned documentation chapter. I am talking about the 'execution(* *(@MyAnn (*)))' variant here, i.e. matching method parameter annotations, NOT matching method parameter annotation *types*. ------------------------------------------------------------ The idea to track issues on GitHub instead of Bugzilla where I cannot even properly -- quote previous posts, -- use code blocks or any other formatting, -- edit posts or -- do many other useful things is a good one. Using GitHub instead of the Eclipse Git system for main development, pull requests etc. would also be desirable, but I am not sure if a single Eclipse project lead can just decide to do that. ------------------------------------------------------------ Andy, you are the bottleneck in AspectJ development because you have the most knowledge. You should find a way to let other people support you with regard to contributions requiring less expertise and save your own cycles for the things with you being the guy with "truck factor" 1, i.e. the person without whom the project would grind to a halt if that person was hit by a bus. Working on upping said truck factor would also be a mid term goal in order to ensure the survival of this project.
