javacardx.annotations

Annotation Type StringPool

@Target(value=TYPE)
@Retention(value=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:

Java Card Classic 3.0.4

See Also:

StringDef

Required Element Summary

Required Elements

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

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and 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 Detail

value

public abstract StringDef[] value

The individual string constant definitions.

export

public abstract boolean export

Whether the string constant definitions are to be exported, such as for a library.

Default:

false

name

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

Default:

""