NamedObject Description

The class that is annotated is a common superclass for all named objects associated with a particular object namer. The members of the annotation define the name of the named-object's helper class, the corresponding helper class for the matching object namer, and the class name of the object namer. The named-object's helper constructors all start with the same four arguments, the types of which are the object-namer class, a string naming the object, a class to classify the object, and a boolean flag indicating if the object is to be put into the namer's tables.


@NamedObject(helperClass="OHelper",
            namerHelperClass="NHelper",
            namerClass="ATestNamer")
public class ATestObject extends OHelper implements NamedObjectOps {
      public ATestObject(ATestNamer namer, String name, boolean intern) {
           super(namer, name, intern);
      }
}
The constructor always can throw an IllegalArgumentException, but this is an unchecked exception.

The more complex case, in which the helper has a superclass with type parameters, and where constructors have additional arguments and can throw additional exceptions, is shown below:


public class OurObject<T1 extends Number, T2 extends Number> {
  ...
  public OurObject() {
    ...
  }
  public OurObject(int ind, float scale) {
     ...
  }
}

@NamedObject(helperClass="OHelper",
             helperSuperclass = "OurObject",
             helperSuperclassTypeParms = "<Integer, Double>",
             helperSuperclassConstrTypes = {
                 @NamedObject.ConstrTypes({}),
                 @NamedObject.ConstrTypes(
                     value = {"int", "float"},
                     exceptions = {"NegativeArraySizeException"}),
             namerHelperClass="NHelper",
             namerClass="ATestNamer")
public class ATestObject extends OHelper implements NamedObjectOps {
      ...
      public ATestObject(ATestNamer namer, String name, boolean intern)
           throws IllegalArgumentException
      {
           super(namer, name, intern);
      }
 *
      public ATestObject(ATestNamer namer, String name, boolean intern,
                         int ind, float scale) 
           throws IllegalArgumentException, NegativeArraySizeException
      {
           super(namer, name, intern, ind, scale);
      }
     ...
}
In this case, the class OHelper will have constructors

   OHelper(ATestNamer namer, String, name, boolean intern) {
       super();
       // the remainder uses namer, name, clazz, and intern.
   }
 *
   OHelper(ATestNamer namer, String name, boolean intern,
           int ind, float scale)
       throws IllegalArgumentException, NegativeArraySizeException
   {
       super(ind, scale);
       // the remainder uses namer, name, clazz, and intern.
       ...
   }
and the class ATestObject's constructors must start with a call to either

       super(namer, name, intern);
or

       super(namer, name, intern, ind, scale);
where the arguments have the same types as those in the OHelper constructor. These constructors should also be declared to throw the same exceptions that the matching constructor in OHelper does.

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.

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.

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 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.