Using Doclet Tags to Generate .xinfo files

Each block requires a corresponding .xinfo file that is read by the container at startup. As the developer, you have the option of using custom java doc tags to generate the .xinfo file. This has a number of advantages over generating the file by hand:

• its a lot faster than writing the xinfo file by hand
• its harder to make mistakes, since much of the data required for the xinfo file is parsed out of the source code

Using this feature requires that you markup the source code with the appropriate tags and then have the build script include the MetaGenerateTask task. Both these steps are described below.

The following tags are defined:

Scope	Applies to any class that is also a block.
Purpose	Marks the class as block and tells the MetaGenerateTask to generate an xinfo file for it.
Parameters	None.
Notes

Example:

/**
 * Ftp server starting point. Avalon framework will load this
 * from the jar file. This is also the starting point of remote
 * admin.
 *
 * @phoenix:block
 * @phoenix:service name="org.apache.avalon.ftpserver.interfaces.FtpServerInterface"
 *
 */
        

Scope	Applies to classes that are also blocks and export services..
Purpose	Identifies a service that is implemented by the block. A class can implement more than one service, in which case there will be multiple phoenix:service tags.
Parameters	Attribute "name" that is the full class name of the interface that defines the service.
Notes	version tag should also be supported?. The block must implement the interface for service it declares.

Example: see above

Scope	Classes that are also blocks.
Purpose	Indicates the full name of an interface that defines management methods for this block.
Parameters	Attribute "name" that is the full class name of the interface that defines the management methods.
Notes

Example:

/**
 * @phoenix:block
 * @phoenix:mx name="org.apache.avalon.apps.demos.helloworldserver.HelloWorldServerMBean"
 */
        

Scope	Applies to the service() method of the block.
Purpose	Identifies a dependency of this block on an another service.
Parameters	Attribute "name" that is the name of the required service.
Notes	Can also specify a required version number? Optional dependencies?

Example:

    /*
     * @phoenix:dependency name="org.apache.avalon.cornerstone.services.sockets.SocketManager"
     * @phoenix:dependency name="org.apache.avalon.cornerstone.services.connection.ConnectionManager"
     * @phoenix:dependency name="org.apache.avalon.ftpserver.usermanager.UserManagerInterface"
     * @phoenix:dependency name="org.apache.avalon.ftpserver.ip.IpRestrictorInterface"
     */
    public void service(ServiceManager serviceManager) throws ServiceException {
        

To have xinfo files generated as part as your ant build script, include the MetaGenerateTask like this:

    <!-- Make .xinfo, .mxinfo and manifest automatically for blocks -->
    <target name="metagenerate">

        <taskdef name="generatemeta" classname="org.apache.avalon.phoenix.tools.metagenerate.MetaGenerateTask">
          <classpath refid="project.class.path" />
        </taskdef>

        <generatemeta dest="${build.metagenerate}">
          <fileset dir="${java.dir}">
            <include name="**/*.java"/>
          </fileset>
        </generatemeta>

    </target>
 
      

Where build.metagenerate is where the .xinfo files should be placed, and java.dir is the location of the source files. Typically the build.metagenerate directory is an intermediate build directory. Output from this task are then copied to a release image directory and jar'ed as a subsequent step.

The qdox jar and phoenix-client.jar need to be in the project.class.path.