Annotation Type DMethodContext


@Retention(RUNTIME) @Target(TYPE) public @interface DMethodContext
Annotation to provide class names for dynamic-method helpers. This annotation applies to each class definition that contains at least one method with a @DMethodImpl annotation.

Dynamic methods are implemented using "helper" classes. There is a helper associated with the top-level class or interface type, and also one associated with each class that implements a dynamic method. The top-level class or interface's helper is created via a @DynamicMethod annotation, whereas the methods for specific argument types are tagged with @DMethodImpl annotations, where the top-level helper class name is used as a key. This key associates the method implementing a specific set of arguments with the dynamic method. Each class implementing dynamic methods by using @DMethodImpl annotations must be tagged with a @DMethodContext annotation that associates a top-level helper class with a local helper class. The local helper class must be a class in the current package (an unqualified class name can be used).

If more than one key is appropriate, use the @DMethodContexts annotation to list each one. Recommended options for the java compiler (we assume the command-line syntax used in Sun Microsystem's implementation) for non-modular jar files are


  javac -d CLASSES -s TMPSRC \
         -classpath /usr/lib/libbzdev/libbzdev.jar:CLASSES \
         FILES...
 
where CLASSES is the name of a directory containing the class files (with subdirectories matching the package hierarchy), TMPSRC is a directory for files created by the annotation processor, and SRC is a directory (or search path) containing source files (again with subdirectories matching the package hierarchy). Without CLASSES in the class path, you may get a warning about implicitly compiled files. Without the '-s' flag, automatically generated java files will appear in the CLASSES directory. The default locking mode can be set at compile time by adding a -A flag as described in the documentation for @DMethodOptions.

During compilation, the JAR file containing the org.bzdev.base module must be accessible from the class path, as must the file

META-INF/services/javax.annotation.processing.Processor
(the libbzdev.jar file contains both). For separate compilation, the class files corresponding to the helper files are needed.

Finally, if none of the files being compiled contain a DynamicMethod or DMethodImpl annotation, nothing special needs to be done.

When modules are used, one will typically create a directory named mods and a subdirectory mods/MODULE where MODULE is the name of the module (e.g., com.foo.bar). One will also create a directory tmpsrc and a corresponding subdirectory tmpsrc/MODULE. A typical compiler command, assuming the source code is in a directory src, is


    javac -d mods/MODULE -p /usr/share/bzdev -s tmpsrc/MODULE \
          --processor-module-path /usr/share/bzdev \
          src/MODULE/module-info.java src/MODULE/DIR/*.java
 
where DIR is the directory corresponding to a package name following the usual Java conventions (e.g., com/foo/bar for the package com.foo.bar). Placing generated source files in tmpsrc/MODULE and the source tree in src/MODULE will make it easy to use javadoc to generate documentation: for javadoc the options

    -d TARGET
    --module-path PATH
    --module-source-path src:tmpsrc
    --add-modules MODULES
    --module MODULE
 
and possibly

    --exclude PACKAGES
 
are useful. For these options,
  • TARGET is the directory that will hold the API documentation
  • PATH is a list of directories separate by the path separator (":" for Linux or Unix, ';' for Windows), with each containing modular JAR files.
  • MODULES is a comma-separated list of modules that should be included in the documentation.
  • PACKAGES is a colon-separated list of package names listing packages that should be excluded (Fully qualified package s * names are necessary). The BZDev class library has a number of packages for which the last component of their names is "lpack". These packages contain Java "properties" files and are used for localization. As such, they should not be documented.
See Also:
  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    Helper class name.
    Local helper class name.
  • Element Details

    • helper

      String helper
      Helper class name. This is the fully qualified class name for the helper class used in the matching DMethodImpl annotation for one or more methods in the class marked by this annotation.
      Returns:
      the helper
    • localHelper

      String localHelper
      Local helper class name. This is the class name of a class in the current package that will be used to implement a dynamic method. The code for that class will be automatically generated. If not fully qualified, the package name will be added to the class name.
      Returns:
      the local helper