XDoclet starts (transferred from CJSDN)

XDoclet starts xDoclets are a code generation tool that can free from heavy duplicate labor in Java development. XDoclets can make your application develop more quickly, and you only need to pay more than a few efforts. You can hand over your lengthy and necessary code to help you, you can escape "Deployment Descriptor Hell", you can also make your application make it easier to manage. And what you have to do, just in your comment, add some kind of Javadoc attributes. Then, you will be surprised that XDoclet is everything to do. Discussing xDoclet, there is a little more prone to confusion, that is, XDoclet is not only a system code generated application, and it is still a code generation framework. Although the details of each application system have changed (such as the EJB code generation and Struts code generation is different, the JMX code generation is another scene), but the core concepts and usage of these code generated are similar. In this chapter, we will see the XDoclet Framework Foundation Concept in all XDoclet code generating programs. But before, let's start with an example. 2.1 XDoclet in an action Every programmer will recognize that their programs will never be completed. There will always be another function to be added, and the other bugs need to be corrected, or constantly reconstructing. So, add a comment in your code, remind yourself (or other programmers) What tasks have to be completed. How to track whether these tasks are completed? Ideally, you will collect a list of TODO tasks. In this regard, XDoclet provides a powerful TODO generator to help you complete this task. This is a good opportunity to introduce xDoclet into the project. 2.1.1 A common task assumes that you are developing a class that uses a spoon. Public class matrix {// Todo - Need to handle if there is no spoon Public void reload () {// ... spoon spot = getspoon (); // ...}} Ideally, you are reading this section next time When you are code, you will handle this "null spoon" problem. But if you have come back for a long time, you will remember that there are some work in this class to do it? Of course, you can search TODO in your source code, and even your integrated development environment has a built-in TODO list support. But if you want to mark the classes and methods where the task is also labeled, the xdoclet can be another option. XDoclets can generate a TODO report for your project. 2.1.2 Adding XDoclet Tags In order to convert your TODO project into another more formal format, you need some subtle changes to the code. As shown below: Public class matrix {/ ** @todo needs to handle when there is no spoon * / public void reload () {// ...}} This javadoc label required for XDoclet is added. XDoclet uses information of these tag tags, and the classes and methods where tags in this case are generated to generate Todo reports. 2.1.3 Integration with ANT To generate Todo reports, you need to make sure you have an xdoclet installed correctly on your machine.

In Ant tasks, at least one goal (eg init target) defines the task, this is an Ant custom task, for example: This task is one of the XDoclet core code generated in the application. Now you can add a TODO target to generate TODO reports in the Ant build file, such as: subtutency will traverse your source file, look for TODO tags, and generate Todo reports in the HTML format in the TDO subdirectory. 2.1.4 Creating a more professional Todo Report XDoclet generated Todo report can have a more professional appearance. The report will list an overview and display which class has a TODO item (and the number of TODO items). TODO items can be clearly distinguished from the report on the method, class, and domain. The class level TODO item will be labeled Class, and the method level TODO item is marked on the method signature. Constructor and domain-related TODO items will also be labeled. This task looks very simple, but considering what you need to do is just add some formatted @Todo tags to the comment, which is a machine that only mansual understanding of the unformed loose annotation. Read, it is more likely to program. The generated output is also easier to read and more commercialization. 2.2 Tasks and subtasks Generate Todo reports, just the hoss of the icebergs in XDoclets. At the beginning, XDoclets were named from automatically generating EJB complicated interfaces and deployment description files. However, the current XDoclet has evolved into a full-featured code generation framework. J2EE code generation is just an application of xdoclets, which can be completed, which has far exceeded J2EE and project documentation. 2.2.1 XDoclet Tasks So far, we have been discussing using XDoclet generating code, but in fact, more precise statements should be, we use xDoclets to generate code, such as . Each xdoclet task focuses on a specific area and provides a rich code generation tool in this field. [Definition: Task (Tasks) is the high-level concept of the code generated by the code available in the XDoclet. ] In xDoclet, there are currently seven core tasks as shown below. : Facing the EJB field, generating EJBs, toolbars, and deployment descriptors. : Developed to Web, generates Server, custom label libraries, and web framework files.

: Hibernate Continuous, Profile, MBeans : JDO, metadata, Vender Configuration : JMX, MBean interface, Mlets, configuration file. : Use the user-defined template to generate code. : Generate project files (such as Todo Report) This, is most common, and many projects are only using XDoclets to generate EJB code generation. is a commonly used code generation task. Of course, it is possible to use several xdoclet tasks in a project (and also recommended), but it is completely independent between these tasks, and they cannot communicate with each other. 2.2.2 XDoclet Sub Task XDoclet tasks are domain-related, and in a particular area xdoclet task, it is also made up of many subtranes that are closely coupled together, and each of these subtasks is only implemented. And simple code generation tasks. [Definition: Subtasks is a coded code generation process generating process generated by the task provides the context of the sub-task execution, and the associated sub-task organizations manage it. The task relies on these sub-tasks to generate code. Calling multiple subtasks in a task to coexist with a variety of comparison large-scale code generation tasks is very common. For example, when developing EJB, you may want to generate an HOME interface, a remote interface, and an EJB-JAR.XML deployment descriptor file for each bean. This is the three independent code generation sub tasks in the context environment of the task. The subtask can be arranged casually to meet the needs of the project code generation. Subsmen included in an XDoclet task often share features and use the same xdoclet tag in the source file. This means that when you start a task, you can easily integrate a related sub-task without having a big change. Sub task interaction allows us to take advantage of how the associated subtask is associated with the task. Suppose you are developing a CMP (container management persistence) entity bean. You want to use some of the number of : : Generate an EJB-JAR.XML deployment descriptor file. • : Generate a local home interface. • : Generate a Local interface. When executing such as upon tasks, you need to marke your entity bean's CMP domain. When you release your bean, you also need to provide specific tables in a particular relational database in the developer-related deployment descriptor and mapping relationships to your CMP entity beans. XDoclets allow you to add some relationship mapping properties on the basis of the originally existing CMP XDoclet property, then you can join a developer related sub-task (such as or ) to generate in the task. Market descriptor file. XDoclet provides almost all application servers, you only need some initialized small modifications, you can generate these application servers related code. But that is just a horn of the iceberg. You can also use the subtutoma to generate an implementation subclass of an entity bean interface for your bean.

If you use subtrans to generate value objects for your bean, subtuto will also generate a method for your value object. I feel incredible. Unfortunately, XDoclet does not provide subtask, otherwise we can have a cup of coffee and take a break. Here you don't want to introduce you all the code generation features that you can complete, but just how you work together just how you want to show you the child task. Once you start and get familiar with an XDoclet sub-task, familiar with another sub-task is very simple - each sub-task is isolated, using this subtraction that can collaborate, the development cost will be significantly reduced It is also a more immediate effect. 2.3 Executive Task XDoclet "Marry" with ANT Give Ant. The xdoclet task is the custom task of Ant, in addition to this, there is no other way to run the xdoclet task. Fortunately, Ant has become a solid standard for Java build tools, so this is not limited. In fact, in turn, this "intimate" relationship with Ant with AT makes XDoclets to participate in any Ant build process. 2.3.1 Declaration Tasks XDoclets are not released with Ant, so if you want to use xDoclet, you need separate downloads and installations. Before using any XDoclet task, you first need to declare it in the task using Ant. For example: If you are familiar with Ant, you will know that this code is telling Ant loading The task definition. Of course, you can also name this custom task in any way you like, but it is best to comply with the standard naming law to avoid confusion. ClassName and ClassPathref Attribute tell Ant where to find the xdoclet class that implements this custom task. If you want to use other xdoclet tasks, you must first declare this task like this. The general common practice is that all the xdoclet tasks that need to be used are declared in one target of Ant, so if they need to use these tasks in other destinations, as long as Depends tasks are OK. You may have already included the init target in the Ant build file, which is a good place to place the xdoclet task (of course if you don't, you can build one).

The following example is to add and in an init target: Now, the task declares, XDoclet" ready ". 2.3.2 Using Tasks You can use declaration tasks in any target. In the context environment of the task, you can mobilize the relevant subtasks. Let us look at an example, this example calls task. Don't worry about seeing the details of the grammar, now you only need to care about some basic concepts. The task imagine a configuration environment you need to run when a subroutine is run (remember, the sub-task is truly code generated). When a child task is called, the subtask inherits the context environment from the task, of course, you can also override these values ​​as needed. In the above example, because the deploymentdescriptor> subtraction generated deployment descriptor file and other Java source file generated by other subtasks that generate various interfaces requires different locations, override the properties value of Destdir. The deployment descriptor file needs to be placed in a place where the EJB JAR file can be easily included, and the generated Java code needs to be placed in a place that can call the Java compiler to compile. It is necessary to be closely associated between these subtasks, but as long as you need, you can have enough autonomous control tasks to generate the environment. The property is also applied to all subtasks. This is an ANT complex type (relative to the simple type of the text and the value), so declared in the task as a child element. Don't mix it with submission to talk. Of course, if you want to specify a different input file set in a subtrack, you can also place a child element in this subtraction to overwrite it. The configurable options for sub-tasks are far more than this.

We will continue to introduce all tasks and subtasks in the next chapter, as well as commonly used configuration options. 2.4 Trying the code to generate the output of interest to generate an output of interest. A parser generator also requires a language description to resolve the generated parser. A business object code generator requires a domain model to know which business objects want to generate. XDoclets require a Java source file as an output to generate a related class or deployment / configuration file. However, the source file may not provide all the information required to generate the code generation. Consider a servlet-based app that when you want to generate a web.xml file, the servlet source file can only provide class names and appropriate servlet interface methods. Other information such as URI Pattern mapping, the information such as initialization parameters required by the servlet is not covered. Obviously, if the class does not provide this information to you, you need to manually fill in this information when you are web.xml file. XDoclets certainly will not know this. Fortunately, the solution is simple. If the required information is not available in the source file, then provide it, the practice is to add some xdoclet properties in the source file. XDoclet parses the source file, extracts these properties, and passes them to templates, and templates use this information to generate code. 2.4.1 Analysis The Attribute XDoclet property is actually a JavaDoc extension. They can be placed in the Javadoc documentation in the Javadoc documentation on the Javadoc Documentation. Document Note Beginning in / **, * / end. Here is a simple example: / *** This is a javadoc comment. * The annotation can be decomposed into multiple lines, and each line begins in an asterisk. * / All text in the comment is considered Javadoc comments and can be accessed by xdoclets. Comment blocks are generally related to a entity in the Java source file, and follow the front of this entity. An annotation block without an entity will not be processed. Class (or interface) can have an comment block, method and domain can also have its own annotation block, such as: / *** class comment block * / public class SomeClass {/ ** domain Note block * / private int id; / * ** Constructor Note Block * / Public SomeClass () {// ...} / ** * Method Note Block * / Public Int GetId () {Return ID;}} The comment block is divided into two parts: the description section and the label section . When you encounter the first Javadoc tag, the label portion starts. The Javadoc label is also divided into two parts: label name and label description. The label description is optional and can be multi-line. For example: / *** This is a description section * @ Tag1 label section starts from here * @ tag2 * @ tag3 front a tag without label description. * This label has multiple line label descriptions. * / Xdoclet Extension Javadoc labels using the parameterized tag. In the xDoclet, you can join the Name = "Value" parameter in the label description section of the Javadoc tag. This tiny change greatly enhances the expression of Javadoc tags that allows the Javadoc tag to describe complex metadata.

The following code shows the use of xdoclet attribute description entity bean methods: / *** @ ejb.interface-method * @ ejb.relation * name = "blog-entries" * role-name = "blog-haas-entries" * @ ejb.value-object * compose = "com.xdocletbook.blog.value.EntryValue" * compose-name = "Entry" * members = "com.xdocletbook.blog.interfaces.EntryLocal" * members-name = "Entries" * Relation = "external" * type = "java.util.set" * / public abstract set getNTries (); parameterized tags allow combination logical properties. You can join the meta information describing this class, so that this class is sufficient to generate code. In addition, the programmer can quickly understand how this class is used by reading such meta information. (If you don't understand this example, don't worry, in Chapter 4, we will learn the EJB-related tags and their connotation.) In addition, pay attention to the above example, all labels Be started with EJB. XDoclets provide a namespace with Namespace.Tagname. In addition to distinguishing between Javadoc, you can organize task-related labels to prevent confusion between tags between tasks.

2.5 Code Generation Mode XDoclet is a template-based code generating engine. From the high-level view, the output file is actually generated by parsing a wide variety of templates. If you understand the template and the context environment it execute, it can be exactly what xDoclets can generate and cannot be generated. If you are evaluating the XDoclet platform, understanding these concepts is very important. Otherwise, you may miss many powerful features of XDoclet, or may be confused by some restrictions on xdoclet. XDoclets are run in an Ant build file environment that provides an ANT-custom task and sub-task to interact with the XDoclet engine. The task is the container of the sub-task, and the sub-task is responsible for performing code generation. Submission call template. The template provides a biscuit mold that will generate a code. XDoclet parses the input source file, extracts the xdoclet attribute metadata in the outgoing file, and then supplies these data to the template, drive template execution. In addition, the template can also provide a merge point, allowing the user to insert some template pieces (merge file Merge Files) to customize code generation as needed. 2.5.1 Template Basic XDoclet uses the code template to generate code. Template is the prototype you want to generate files. The template uses some XML tags to guide the template engine to adjust the generation of the code based on the input class and their metadata. [Definition: Template (Template) is an abstract mold view that generates code or description file. When the template is parsed, the specified details information will be filled. ] Template is in general, there will be an execution environment. Templates may be applied to a class environment (conversion generation transform generation), and it is also possible to apply in a global environment (aggregation generation aggregate generation). Conversion generation and aggregation generation is the two types of task modes of XDoclets, understanding the differences between them are very important for understanding xDoclets. When you use the XDoclet to generate a descriptor file, you use the aggregation generation. Arranging the descriptor file is not only related to a class, in contrast, it needs to aggregate information from multiple classes to an input file. In this architecture, the parsing of the template will only generate an output file, no matter how many input files. In the conversion generation mode, the template will be parsed once every source file, and the output is generated according to the context environment of the file class. This generated mode generates an output file for each input file. A good example of the conversion generation mode is to generate the Local and Remote interfaces of EJB. Obviously, the interface is associated with a bean class. Extract information from each class (class, domain, interface, and xDoclet attribute) to convert an interface. No other information is required. Extracting an interface from the implementation seems to be a bit reverse. If you write a program, you generally say an interface first, then write a class to turn it. But XDoclet can't do, XDoclets are not possible to help you implement an existing interface because it is not possible to help you generate your business logic. Of course, if business logic can get from the interface itself (such as a JavaBean Get / SET Accessor) or use the xdoclet attribute to declare, generate business logic code to implement an interface is not impossible. But in general, this is not really realistic. In contrast, an implementation is provided and the association between the interface and this implementation is much easier. The aggregation generation and conversion generation is mainly different from their environmental information. Even if a Java file is generated in a code generation task, it is generally not commonly used to generate, because generating a Java class also requires some important information, such as the package, the class name you want, is unable to provide in this environment of. If you must use aggregation generation, you need to provide information on another separate place. 2.5.2 Template Tags have been more in-depth to understand it before I haven't seen the template. What is the template file? It is a bit like a JSP file.

They all contain files and XML tags, and the XML tab will be parsed when generating output files, and then generate text and displayed at the location where the XML tag is located. In addition to the XML tab that heads earlier with XDT, the rest of the XML tag xdoclet will ignore regardless of the XDoclet engine. The following code snippet shows XDoclet template "classic style": public class Extends Observabe {static _instance = null; public static getInstance () {if (_instance == null) {_instance = new ();} return _instance;}} Study this template, you will find that it is a class definition. This class defines a static variable instance, and uses a static method to control access to this static file. With Java syntax, you can easily infer the directory of the XDoclet template tags that generate class names, although you don't know much about how you work this label. Even if you never want to write templates yourself, understand how the template is resolved or necessary. Bermate morning, you will call to a failure of XDoclet tasks, do not produce the output you expect, then the faster way to find the reason is to check the template file directly, see where the problem is. Let's take a look at the pieces that generate static domain definitions: static _instance = null; in the eyes of xdoclet, this template code is very simple, that is: Static _INSTANCE = NULL; XDoclet parsing the execution tag, if there is output, put the input back to the text. Some tags will perform some operations and put the output back to a stream. Such labels are called Content Tags because they generate content. Another type of label is called a Body tag. The Body label exists between the start and end tags. The Body tag is strongly powerful in these texts, and the template can be analyzed by the peripheral label. For example, in the example, the xdtclass: classof tag, their content is the template piece: Classof tag resolves this template, extracts full-restricted content, then shave the front cover, only output class name. The Body tag does not always parse its content. Before doing this, they will check some external judgment conditions in advance (such as checking checking that you are generating an interface or a class).

The standard tag is called the conditional tags here. There are also some Body tags to provide similar iterations, which will be parsed for multiple times. For example, a label parses each method in the class. The XDoclet tag provides many high-level code generation features, but sometimes they may appear to be flexible enough, or the ability to express your needs. At this time, you can choose to extend the XDoclet template engine compared to additional development of a common function. You can develop your own labels with more expressive capabilities, and more powerful Java platforms. 2.6 Use the consolidation of custom code generation systems for use, main reason is that they often generate some deadlines, not flexible code. Most code generation systems do not allow you to change their generated code; if this system is not flexible enough, the best extension you can do is the application inherited the code generated, or use some common design patterns (such as Proxy And adaptor to meet your needs. Whether this, this is not a good way to generate the code you want to generate. The code generator is best to do the resulting Wygiwyg (What You Generate Is What You get, replacing the code that you need to spend a lot of time to generate and do not satisfy the required code. Therefore, for the code generator, supporting flexible customization is a prerequisite for generating code that can fully meet the requirements. XDoclets support customized codes in the template file definition by merge point (Merge Points) to allow runtime to insert custom code when the schedule file definition is allowed. Sometimes, merge points can even affect the generation of global code, not only allow you to add some custom content, but also fundamentally change things that will be generated. [Definition: Merge Points is a pre-defined schedule predefined extension point to add custom content in code generated by code] Let us study a template code from the xdoclet source code. At the end of the template that generates primary keys for entity beans, such a merge point is defined: If you create a name in your merge directory EntityPK-Custom.xdt file, the content of this template file will be included in this merge point. Your customization can perform all the powerful features that the high-level template can perform, you can perform all templates that can be made (including customized tags to define their own merge points). This merge point above uses the same file for all type environments. Of course, you can use different merge files for each class environment. This will be useful if you don't want to customize all class files, or you don't want to rewrite the template for some changes. Regardless of the motivation, the category merge point is easy to identify: they will include a category tag {0} in the name.