Annotation Interface ProtoSchema

@Target({TYPE,PACKAGE}) @Retention(CLASS) public @interface ProtoSchema
Generates compile-time auto-implementations of SerializationContextInitializer. Annotate a class or interface extending from SerializationContextInitializer with this annotation and a new concrete public class named based on className(), having a default no-arguments public constructor will be generated at compile time in the same package. The implementations of the methods from SerializationContextInitializer will be generated based on the information provided in the attributes of this annotation.

This annotation is used at compile time annotation processing only and should not be relied upon at runtime, so its retention is set to RetentionPolicy.CLASS.

Since:
5.0

  • Element Details

    • className

      String className
      The name of the generated Java implementation class (optional). If missing, the name of the current class plus the "Impl" suffix is assumed by default.
      Default:
      ""

    • schemaFileName

      String schemaFileName
      The generated Protobuf schema file name (optional). It can contain '/' characters, so it might appear like a relative or absolute file name. Must end with ".proto" suffix. The schema will be registered under this name in the SerializationContext by SerializationContextInitializer.registerSchema(SerializationContext). If missing, the simple name of the annotated class plus the ".proto" suffix will be used by default.
      Default:
      ""

    • schemaFilePath

      String schemaFilePath
      Generated Protobuf schema resource file path (optional). If this is present then a resource file is generated in the designated path, with the given file name, and will be available to the ClassLoader at runtime, otherwise the generated schema file is directly baked as a String constant into the generated class and no resource file is generated.
      Default:
      ""

    • schemaPackageName

      String schemaPackageName
      Package of the generated Protobuf schema. This is optional. If the package name is not specified then the unnamed/default package is assumed.
      Default:
      ""

    • value

      String[] value
      A handy alias for basePackages(). value and basePackages() are mutually exclusive. See basePackages() for usage.
      Default:
      {}

    • basePackages

      String[] basePackages
      The list of packages to scan (optional). basePackages and includeClasses() are mutually exclusive. The packages are scanned for annotated classes recursively. If basePackages is empty then all packages are considered, starting from root and including the default (unnamed) package. The packages are filtered based on the excludeClasses() filter. If neither includeClasses() nor basePackages is specified then the entire source path is scanned. Be wary of using this last option in anything but very simple demo projects.
      Default:
      {}

    • includeClasses

      Class<?>[] includeClasses
      Annotated classes to process (optional). If includeClasses is empty, all ProtoXyz annotated classes that belong to the packages listed in basePackages() will be scanned. If neither includeClasses nor basePackages() was specified then the entire source path will be scanned. Be wary of using this last option in anything but very simple demo projects.
      Default:
      {}

    • excludeClasses

      Class<?>[] excludeClasses
      Classes to be explicitly excluded. excludeClasses and includeClasses() are mutually exclusive. This can be used together with basePackages().
      Default:
      {}

    • service

      boolean service
      Enable generation of a META-INF/services file for the generated implementation class of the SerializationContextInitializer to be loadable by the ServiceLoader. This defaults to true. The ProtoStream library does not make any use of the ServiceLoader to benefit from this mechanism but the user's application is free to use it.
      Default:
      true

    • marshallersOnly

      boolean marshallersOnly
      Generate only the marshallers and skip the schema file.

      The schema is actually always generated at compile time, in memory, so that various validations can be performed at compile time, but with this flag you effectively ensure it finally gets excluded from both the generated source code and the generated resource files and it does not get registered at runtime by this SerializationContextInitializer implementation. This flag is useful in cases where you want to register the schema manually for whatever reason or the schema is already provided/registered by other parts of your application.

      This option conflicts with schemaFilePath() and they cannot be used together. Also, this option cannot be set to true if the annotated element is a subtype of GeneratedSchema, which is expected to always provide a generated schema, as the name implies.

      Default:
      false

    • dependsOn

      Class<? extends SerializationContextInitializer>[] dependsOn
      The SerializationContextInitializers that must be executed before this one. Classes or interfaces listed here must implement SerializationContextInitializer and must also be annotated with AutoProtoSchemaBuilder. Classes not annotated with ProtoSchema will result in a compilation error.
      Default:
      {}

    • syntax

      ProtoSyntax syntax
      Specifies the protobuf syntax used by the generated schema. Defaults to ProtoSyntax.PROTO2
      Default:
      PROTO2

    • allowNullFields

      boolean allowNullFields
      Specifies whether generated marshallers should allow missing fields of Byte Arrays, Enums, boxed primitives and Strings to be initialized as null when the ProtoField.defaultValue() is defined as an empty string.

      This field has no affect when utilising ProtoSyntax.PROTO2 as this is the only supported behavior, see IPROTO-349 for more details.

      WARNING. Enabling this behaviour goes against the protobuf specification and could cause issues if your application utilises other languages and/or protobuf libraries. We only recommend enabling this feature if ProtoStream is the only protobuf library in use.

      Default:
      false