JSR 175: Metadata for Java in Public Review

Discussions

News: JSR 175: Metadata for Java in Public Review

  1. JSR 175: Metadata for Java in Public Review (14 messages)

    The expert group for JSR 175 has released a public review draft of the Metadata Facility for the Java Programming Language spec.

    Info from the details page

    We believe there are several elements needed as part of this JSR:

    - Definition of a Java programming language feature that allows medatadata information to be supplied for (at least) classes, interfaces, methods, and fields. This language extension will allow metadata to be recognized by development tools. It appears likely that it will be useful to allow attribute values to be associated with given metadata attributes.

          The exact syntax will need to be determined by the expert group. There appear to be a number of possibilities, including (but not limited to!) using a doc comment tag @meta or adding a new Java programming language keyword meta.

    - Definition of a runtime delivery format for metadata and of runtime APIs so that tools and libraries can accesss metadata information at deployment time and at runtime.

    - Definition of rules for the attribute namespace so as to avoid accidental collisions over the same attribute name. Details will be determined by the expert group, but it seems that a mechanism leveraging the class naming conventions might be useful.

    This list is not meant to be exhaustive. For example, if it is determined that there is a need for the compiler to do some validity checking on metadata, we will need a mechanism for communicating restrictions on the use of a particular attribute (such as "The attribute com.acme.Remote may be used on methods, but not on classes, interfaces, or fields"). Metadata processing tools such as stub generators, however, are outside the scope of this JSR. The JSR is intended to enable such tools, but not to define them.

    Download the public review draft

    View the home page of JSR 175: A Metadata Facility for the Java Programming Language

    This Public Review closes on 5 December 2003.

    Does it match the expectations? Is what we are waiting for?

    Threaded Messages (14)

  2. Having some problems downloading the spec[ Go to top ]

    People have noted that there are problems actually downloading the spec. If someone manages to get it let us know :)
  3. There were some troubles, but after a couple of retries I've managed.
  4. Metadata for code generation[ Go to top ]

    I have been hoping to see this specification better enable code generation.

    Doclet tags are a rather crude but non-intrusive way to do this. I have been hoping to see this JSR provide a better mechanism.

    What I see in this specification is a very intrusive mechanism. By intrusive, I mean that it has altered the syntax of the Java language itself, rather than trying to remain embedded in comments like Doclet tags. I was hoping to see a richer syntax, mostly based on XML, to Doclet tags, with no intrusive changes to the Java code itself.

    Ben
  5. My very first thought is that I am glad the spec includes the use of the RetentionPolicy enum. I think this will definitely break down some barriers towards the effective use of metadata.

    IMHO, this is key to ensure that you can add annotations that are ignorable at compile time. In fact, I posted some concerns about this sort of stuff in an earlier thread.

    Sandeep.
  6. <Appendix III. Usage Notes>
    Programmers using annotations should be aware that programs acquire dependencies on any annotation types they use, just as they acquire dependencies on libraries. In order to ensure portability, programmers may elect to avoid using proprietary annotation types.
    </Appendix III. Usage Notes>

    On a more complete reading, apparently not.

    Hmmm, this is definitely NOT fun.

    Sandeep.
  7. My conclusions[ Go to top ]

    First of all, I would like to apologize for jumping the gun (to incorrect conclusions) in my first post. But after reading the spec twice over, my conclusions are:

    1) This is a very well thought out spec - readers should definitely read the appendices (esp the FAQ) at the end. Probably before reading the spec itself.

    2) The problem of compile-time dependency seems intractable. It may very well be that there is no solution to the problem. Which means external tools that add annotations would do well to create small JARs of their annotations as and when they annotate (for inclusion at compile time, and if needed, for bundling).

    3) (Comment to Ben's comment on using Doclet tags) This is obviously a choice of style. A lot of people feel that Doclet-style tags in comments worked well. However, such tags are also fragile and are inextricably woven into the fabric of Javadoc. Providing VM-based runtime access to attributes defined in Javadoc is, IMHO, not a good design construct.

    Sandeep

    > My very first thought is that I am glad the spec includes the use of the RetentionPolicy enum. I think this will definitely break down some barriers towards the effective use of metadata.
    >
    > IMHO, this is key to ensure that you can add annotations that are ignorable at compile time. In fact, I posted some concerns about this sort of stuff in an earlier thread.
    >
    > Sandeep.
  8. A few precisions[ Go to top ]

    Just to reinforce the point: please read carefully the section listing the open issues. This is where we listed the points where the experts group could not come up with a satisfying resolution. Therefore, we chose a side in order to make the specification available for public review, but all the points listed in this section are definitely up for debate.

    We are hoping that the public review will bring up new cases that we did not see and we will definitely revisit these parts of the specification if convincing arguments are made.

    In particular, I urge everyone to think about the "ignorable annotations" problem and let us know how they feel about it. This is an issue that has split the experts group (not 50-50, though). If no convincing case is made for ignorable annotations, the specification will remain as it is right now and mandate the presence of annotations for javac to succeed.

    Please turn in your papers by December 5th :-)

    --
    Cedric
    http://beust.com/weblog
  9. A few precisions[ Go to top ]

    In particular, I urge everyone to think about the "ignorable annotations" problem and let us know how they feel about it. This is an issue that has split the experts group (not 50-50, though). If no convincing case is made for ignorable annotations, the specification will remain as it is right now and mandate the presence of annotations for javac to succeed.


    The only way I see to specify an ignorable annotation would be to specify it as an standard attribute on each use of the annotation type in a given source file. For example,

    @UMLToolSpecificInfo(ignorable=true)
    public class Employee { ... }

    Note that it's no use to specify this in the type definition, if the client program has no access to the definition.
  10. On a more general Java front, I think the changes to Arrays are also cool. These are often reinvented wheels.

    Sandeep.
  11. probelms with downloading JSR175[ Go to top ]

    Looks like it is ok now, I tried with Mozilla and ie and I was able to download it successfully.
  12. JSR175[ Go to top ]

    I did a quick reviewe, and one reservation I have is that methods arent permitted to have their paramterets annotated, I think this is too restrictive.

    But a general comment on the JSR175, meta data facility is good to have but again this approach is a little time consuming.

    Perhaps some other approached would be:

    1) enhance the reflection api to include language based annotations for extra runtime information that a user may choose to deploy.
    2) Allow the user to create their own extended annotation types and place them into the some registry that is available to the compiler. Perhaps JSR175 is trying to do this, but couldn't it be done without having to create a new annotation syntax, or maybe a very simple annotaiton syntax.

    /**
     * Describes the "request-for-enhancement" (RFE) that led to the presence of
     * the annotated API element.
     */
    public @interface RequestForEnhancement {
        int id(); // Unique ID number associated with RFE
        String synopsis(); // Synopsis of RFE
        String engineer(); // Name of engineer who implemented RFE
        String date(); // Date RFE was implemented
    }
  13. JSR175 feedback[ Go to top ]

    One more thing: while you are welcome to share your thoughts and suggestions here, you should also email them to:

    jsr-175-comments at jcp dot org

    if you want to make sure that the experts group read them.

    --
    Cedric
  14. Nice language feature, poor tool story[ Go to top ]

    Here is a comment from my blog: http://homepage.mac.com/spullara/rants/

    JSR-175... Great spec for the language, totally ignores tools


    Java really needs annotations so we can stop shipping around all these files that are representing one logical entity. JSR-175 addresses the need on the declaration side but fails to produce a processing model.


    I love the new annotations. We have been waiting for them for a long time at BEA and in the mean-time have been using Javadocs to do the markup. See my previous blog entry about EJBGen for an example. Being able to move that markup into the language is a great advantage and will let us catch some of the errors at compile time that we normally catch when someone runs EJBGen on their source file.

    However, after reading the specification, I feel there is a large gaping hole in it. There is no specification for the processing of these annotations in the document. They don't talk about what an end user needs to do once they have an annotated source file and a set of annotations in order to completely process that source file. If I have a .java file I know I need to run javac. If I have a .g file I know to run Antlr. Since all these files are going to say .java I think I should just have to run javac and only javac. The annotations should tell javac what tools are needed. Additionally, they do not talk about how these annotated classes are efficiently found at runtime. Let's run through some scenarios that I would like to see addressed:

    1) End user has a set of SOURCE annotations and a source file with those annotations. How will this be processed?
    2) End user has a set of annotations and a source file with annotations that are semantically incorrect because there is some conflict between two annotations that is not syntactically wrong. When is the error caught?
    3) Javac decides to recompile a source file with annotations when it was told to compile a dependent class. How does the end user know to rerun the annotation processing tool?
    4) Class annotations have some global effect. How does a runtime efficiently find these classes and apply the global effect? For instance, a servlet with its registration annotated within it a la XDoclet.
    5) I am given a Jar file that contains annotations and classes that use those annotations. How do I determine the tool or runtime requirements to use that jar file?
    6) Given a tool that needs to process the .jar file in 5) how do I determine which classes have annotations that I am interested in without scanning every class?

    I don't like putting up these scenarios without some idea how I would handle them if I were writing the specification. For the cases where we need to process or reprocess annotations with a tool or report errors at compilation time I believe that the best solution is to make javac extensible. Annotation tool jars could be configured for javac's use and they would register themselves as interested in annotations. Annotations would be able to specify whether or not a tool is required to be registered in order for them to work properly. The API for these tools would include the ability to abort the compilation with an error if they determine that any of their internal semantics wrt to the annotations they find are in violation. It would also give the required hook for reprocessing classes that are recompiled by javac without scanning the all of the class files and comparing them with whatever the output of the processing tool is.

    For instance, if I try and compile a new annotated RMI class and there is not RMI stub generator registered then I would get an error that the compilation could not complete. In this case there may be a default registration that uses the JDKs RMIC to process the file but in the case of say WebLogic it would register an empty processor because we do all the work at runtime.

    In order to quickly find annotated classes within a classpath or a Jar file I believe that a manifest or index should be generated by Javac detailing all the classes that have annotations and the types of those annotations. Otherwise, lets say we have a system like XDoclet where you specify the servlet path for a servlet class. Everytime I deploy a webapp I would have to scan all the classes in the entire classpath to determine if there are any servlets that need to be registered. This clearly requires some sort of index mechanism, probably at the package.class level and additionally at the jar manifest level that aggregates all the package.class information.

    When given a jar file with annotated classes and annotations the there should be some way to indicate in the jar file what runtime or compile time processor is required in order to use the classes. Simply handing these out without any programmatic way to determine dependencies is liable to be frustrating to the end user. There are dependency mechanisms build into the Jar format that can be exploited for this.

    I feel like JSR-175 is only handling half the problem. Can you imagine if the other Java specifications simply gave you a data format without specifying how that data leads to processing? It's like God made a new creature with no ecosystem for it to live in.

    P.S. Other problems of note include the requirement for the annotations for compilation. Javac could generate fake annotations based on usage. You would have to get rid of default annotations though.
  15. Have you submitted your concerns to jsr-175-comments at jcp dot org?