Annotation Type StringPool

@Target(TYPE) @Retention(SOURCE) public @interface StringPool
Defines a pool of character string constants.

Within a defined pool each string constant is defined using the StringDef annotation.

This annotation is processed at compile-time and is then discarded by the compiler. The annotation processor that handles this annotation generates the source for a class that defines a field of type byte[] for each of the string constants. The generated class is named as per the given name attribute.

If the export attribute is set to true then the string constant definitions are typically intended to be part of a library. The generated class is a public class and for each string constant definition a field with the following characteristics is generated:

  • the field is an instance field
  • the access modifier is public
  • the type is byte[]
  • the name is set to that of the string constant definition's name attribute
  • the field is initialized with the UTF-8 encoded byte sequence of the string constant definition's value attribute or the value of the string constant definition's field referenced by the reference attribute
The generated class has a public default constructor.
If string constants are defined by referencing other string constants (typically string constants defined in one or more other libraries), the default constructor of the generated class instantiates all the string pool classes from these libraries defining the string constants that are referenced.

If the export attribute is set to false then the string constant definitions are typically intended to be used within an applet's package. The generated class is a package-private class and for each string constant definition a field with the following characteristics is generated:

  • the field is a class (static) field
  • the access modifier is package-private
  • the type is byte[]
  • the name is set to that of the string constant definition's name attribute
  • the field is initialized with the UTF-8 encoded byte sequence of the string constant definition's value attribute or the value of the string constant definition's field referenced by the reference attribute
If one of the string constants is defined by referencing another string constant (typically a string constant defined in a library), the generated class includes a package-private static method importLibConstants() with the void return type that must be invoked prior to accessing any string constant field defined by reference. This method instantiates all the string pool classes defining the string constants that are referenced.

Defining string constants that reference other string constants from libaries is a convenience mechanism that allows for an applet developer to use the same coding pattern regardless of whether a string constant is defined in the applet's package or in a library. In both cases, the applet developer can use static field access. If footprint is an issue, an applet developer should directly instantiate string constant pool classes from libraries.

The following example illustrates how to use the annotation to declare string constants local to the declaring application or imported from a library: 

     package com.sun.jcclassic.samples.stringapp;

      import javacardx.annotations.*;

       @StringPool(value = {
              @StringDef(name = "S1", value = "Hello World!"),
              @StringDef(name = "S2", reference = "com.sun.jcclassic.samples.stringlib.LibStrings.Hello")
           },
          name = "AppStrings")
       public class StringHandlingApp extends Applet {
         protected StringHandlingApp() {
             AppStrings.importLibConstants(); // initializes lib constants
             byte[] x = AppStrings.S1;
             byte[] y = AppStrings.S2;
             short l = (short) AppStrings.S1.length;
             ...
         }
         ...
       }
For information on how to invoke a string annotation processor, see Oracle's string annotation processor.

Since:
3.0.4
See Also:

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    StringDef[]
    value
    The individual string constant definitions.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    export
    Whether the string constant definitions are to be exported, such as for a library.
    java.lang.String
    name
    The name of the generated class.

  • Element Details

    • value

      StringDef[] value
      The individual string constant definitions.
      Returns:
      -

    • export

      boolean export
      Whether the string constant definitions are to be exported, such as for a library.
      Returns:
      -
      Default:
      false

    • name

      java.lang.String name
      The name of the generated class. If this attribute is set to the empty string value (the default), the annotation processor generates a class named by appending the string "$$Strings" to the fully qualified name of the annotated class or interface.
      Returns:
      -
      Default:
      ""