3 December 2005 (Saturday)

Currently in the playforge development we’re using annotations to help with specifying “persistence” (really serialisation&marshalling, but it’s always within the context of saving and loading) and ”bindings” (hooking up XML-specified UIs to the execution of java code during runtime). Some people might well ask (especially those who have read around the issues about “Annotation Hell” or “Annotation Overkill”) why use annotations for this at all, why not just use method-naming standards and normal java introspection? 

Some responses to that then:

The collection of these annotations is quite literally meta-data – taken together (the meta data of each of the classes in a Playforge applications “type map”) is information about the way that this playforge-application expects to be used and reused. It should not It is also a form of separate API. We wouldn’t necessarily want the name of a playforge field (a stored member) or a playforge variable (a ui binding) to change just because the java method name changed. When such things change, then any stored document that depended on that field, or any stored UI that depended on that variable would no longer work in the way it had been created. On the one hand, that’s to be expected as the underlying application changes. but on the other that is something that the application developer, document developer and ui developer (as well as the sodaplay2 community as a whole) would like to track. In some (probably future) version of sodaplay, one could imagine explicitly tracking versions of applications, and when and how they break previous published APIs.

Furthermore, our aim for the launch of sodaplay2 is that this collection of meta-data is itself transformed into a form of auto-generated documentation on the application’s “playforge API” – a kind of javadoc for playforge. This information would be useful for people who want to tinker with the UI of an application as well as an overview for the application writer and any extension writers. In addition it might be interesting to more technically minded sodaplay community members, whether model creators or model writers.

But, are there any drawbacks of using annotations? Er yes – due to the way that annotation introspection has been implemented (the implementation, interestingly is not in java.lang.annotation or java.lang.reflect but in sun.reflect.annotation.AnnotationType), any introspection of any annotation (including a public annotation on a public class/member) requires “accessDeclaredMembers” – which is quite a wide security privilege to grant (and would thus require signing all jars and granting all permissions to jnlp files and more work to re-create a security sandbox). This is not the case for other kinds of (public-member) introspection that happily occur within a jnlp sandbox. As a result, we’re having to work around this and make annotation introspection only happen for developers, and not for jnlp-launched applications. For those, we will expect an xml-descriptor file to accompany every sodaplay application which will duplicate the contents of all the meta-data. Happily, this won’t be very far from what the documentation above will require (another reason we believe we will be launching with this documentation). The descriptor file can be created from the annotations as part of the compilation/packaging/upload step (and will be wrapped up in an ant-task).

%d bloggers like this: