Notes in Tiger, part 1th: Adding metadata to Java code

One of the latest trends in programming, especially in Java programming, is the use of meta data. Simply put, metadata is data about data. Metadata can be used to create documents, track dependencies in code, and even perform basic compile-time checks. Many metadata tools, such as XDoclet (see Resources), add these features to the core Java language and temporarily become part of the Java programming functionality.

Until you can use J2SE 5.0 (also called Tiger, now the second beta version), the core Java language is closest to the Meta Data tool with the Javadoc method. You use a special set of tags to mark the code and execute the Javadoc command to convert the tags into formatted HTML pages that describe the class to which the label is attached. However, Javadoc is a flawed metadata tool because you do not have a fixed, practical, standardized way to use the data for other purposes in addition to the document being generated. The fact that HTML code is often mixed into Javadoc output even further reduces its value for any other purpose.

Tiger merges a more generic metadata tool into the core Java language through a new feature called Annotations. Comments are modifiers that you can add to your code and can be used for package declarations, type declarations, constructors, methods, fields, parameters, and variables. Tiger contains built-in annotations and also supports custom annotations that you write yourself. This article outlines the benefits of metadata and introduces you to Tiger's built-in annotations. The 2nd part of this series will study custom annotations. I want to thank O ' Reilly Media, Inc., who have been very generous in allowing me to use the code example in the "Notes" chapter of my book on Tiger in this article (see Resources).

Value of meta data

Generally, the benefits of metadata fall into three categories: documentation, compiler checking, and code analysis. Code-level documents are most often referenced. Metadata provides a useful way to indicate whether a method depends on other methods, whether they are complete, whether a particular class must reference another class, and so on. This is really useful, but documentation may be the least relevant reason for adding metadata to the Java language. Javadoc has provided a very easy to understand and robust way to document code. In addition, who writes documentation tools when there is already a documentation tool and most of the time it works well?

Compiler check

The more important advantage of metadata is that the compiler can use it to perform basic compile-time checks. For example, you will see in the Override comment later in this article that Tiger introduced a comment that allows you to specify a method that overrides another method in the superclass. The Java compiler can ensure that the behavior that is indicated in the metadata actually occurs at the code level. This may seem silly if you've never found this type of bug, but most older Java programmers have spent at least a few nights figuring out why their code doesn't work. You may feel more uncomfortable when you finally realize that the method's parameters are wrong and that the method does not actually overwrite the methods in the superclass. Tools that use metadata can help you easily pinpoint this type of error, which saves you the night to see the Halo tournament in the long run.

Code Analysis

As you can attest, the best feature of any good annotation or metadata tool is that you can use additional data to analyze your code. In a simple case, you might build the code directory, provide the required input type, and indicate the return type. However, you might think that Java reflection has the same advantages; After all, you can introspect the code for all this information. This appears to be correct on the surface, but is not usually used in practice. Many times, a type that is accepted as input or returned as output is not actually the type that the method wants. For example, the parameter type may be Object, but the method may use only integers. This can occur easily in a number of situations, such as when a method is overwritten and the superclass uses the general parameters to declare the method, as well as in a system that is doing many serialization. In both cases, the metadata can indicate the code analysis tool, although the parameter type is Object, but the Integer is really needed. This kind of analysis is very useful, but it cannot exaggerate its value.

In more complex cases, the Code analysis tool can perform all kinds of extra tasks. The example du jour is a Enterprise JavaBean (EJB) component. Even the dependencies and complexities of simple EJB systems are astonishing. You have a home interface and a remote interface, as well as a local and local home interface, and an implementation class. It is very difficult to keep all of these classes synchronized. However, the metadata can provide a solution to this problem. A good tool (or to mention XDoclet) can manage all of these dependencies and ensure that classes without a "code level" connection, but with a "logical level" bundle, remain synchronized. The metadata can really play its part here.

Basic knowledge of annotations

Now that you know the benefits of metadata, I'll introduce the comments in Tiger. The annotation takes the "at" notation (@) followed by the annotation name. The data is then provided to the annotation through Name=value when data is needed. Each time you use this notation, you are generating a comment. A piece of code might have 10, 50, or more annotations. However, you will find that multiple annotations may use the same annotation type. A type is a structure that is actually used, and in a particular context, the annotation itself is the specific use of that type (see sidebar comments or annotation types?) ）。

The annotation is divided into three basic categories:

Tag annotations have no variables. Comments are simple to display, are identified by name and do not provide additional data. For example, @MarkerAnnotation is a markup annotation. It contains no data, only a comment name.

A single value annotation is similar to a markup annotation, but provides a piece of data. Because only a little bit of data is available, you can use shortcut syntax (assuming the annotation type accepts this syntax): @SingleValueAnnotation ("My Data"). This should look like a normal Java method call, except for the @ tag.

Full annotations have multiple data members. Therefore, you must use a more complete syntax (annotations are no longer like normal Java methods): @FullAnnotation (var1= "Data value 1", var2= "data value 2", var3= "data value 3").

In addition to providing values to annotations by default syntax, you can also use name-value pairs when you need to transfer multiple values. You can also provide an array of values for annotation variables through curly braces. Listing 1 shows an example of an array of values in the annotation.