Package io.mats3.spring

Annotation Interface MatsClassMapping

@Documented @Retention(RUNTIME) @Target({TYPE,ANNOTATION_TYPE}) @Repeatable(MatsClassMappings.class) @Service public @interface MatsClassMapping
A class annotated with this repeatable annotation will become a Mats Endpoint, where an instance of the class itself is the State (STO) object for the Endpoint, and each @Stage-annotated method on the class is a stage of the Endpoint. This annotation is meta-annotated with @Service, and is thus also a Spring bean. This singleton Spring bean acts as a "template" for the State, and any wired (injected/autowired) fields will be available for the stage-methods, but will not be regarded as part of the State when serialized and sent on the wire. You should use the Java-modifier transient on such Spring-injected fields, so that the serializer understands that it is not a part of state. In addition, if a field is of type ProcessContext, it will be injected by the Mats JavaConfig machinery before a stage-method is invoked.

All methods that are annotated with @Stage is regarded as a stage of the Mats Endpoint. To know the order of the stages, and ordinal must be assigned to the Stage - read its JavaDoc. The initial stage is the method annotated with @Stage(0) (The constant Stage.INITIAL is conveniently available), and the subsequent stages are the ordered list of these stage-methods. The last stage will typically have a return type - which defines the return type of the endpoint - while no other stage can have a return type. It is, however, still possible to return early if needed, by using context.reply(..). If the last stage does not have a return type (i.e. it is void), it will be a Terminator. Any methods that are not annotated with @Stage is ignored, thus you may structure and divide your code into sub methods as you see fit.

Note: If you only need a single stage, i.e. a single-stage Endpoint, or Terminator, you should instead consider MatsMapping.

Note: You should mark the injected/autowired fields with the java keyword transient to ensure that the serializer understands that it is not part of the state. (The values are null'ed out before state serialization takes place, so an injected DataSource will never be attempted serialized as state. However, some type of serializers, e.g. Gson, will prepare to serialize all fields, even though they will always be null, and thus possibly fail on newer versions of Java. Such preparation does not take place if a field is marked transient.)

Each stage-method can take zero, one, two or many arguments. The machinery looks for a ProcessContext and an incoming DTO argument. Neither ProcessContext nor an incoming DTO is required. The rationale for taking more than the required arguments is that you could potentially want to invoke it differently in a testing scenario (depending on how you feel towards testing).

  • 0: No ProcessContext nor incoming DTO.
  • 1: Either it is a ProcessContext, otherwise it must be the incoming DTO.
  • 2: If one is a ProcessContext, the other must be the incoming DTO.
  • 2+: One may be the ProcessContext, and the others are searched for the @Dto annotation, and if one is found, this is the incoming DTO.

The logic to determine which fields are state, and which fields are injected, is as follows: When Mats SpringConfig gets the bean, injection is already performed by Spring. Any fields that are non-null is thus assumed to be injected by Spring and not part of the State, unless the field is also non-null when simply instantiated as a new object, using the current Mats serialization mechanism of creating an empty State object. The rationale for the latter is that such fields must be default initialized, like e.g. List<Car> cars = new ArrayList<>(). A field of type ProcessContext is not a state field.

It is worth noting that the singleton Spring-constructed bean instance is never actually employed outside of being inspected at start up: Its class is inspected to set up the MatsEndpoint and its stages, and the singleton instance is used as a template for which fields of the Endpoint's State object are injected, and which fields are state.

In a multi-MatsFactory setup, you may qualify which MatsFactory this Endpoint should be constructed on - read JavaDoc on @MatsMapping for how this works.

See Also:

  • Element Details

    • endpointId

      @AliasFor("value") String endpointId
      The Mats Endpoint Id that this endpoint should listen to.
      Returns:
      the Mats Endpoint Id which this endpoint listens to.
      Default:
      ""

    • value

      @AliasFor("endpointId") String value
      Alias for "endpointId", so that if you only need to set the endpointId, you can do so directly: @MatsEndpointSetup("endpointId")
      Returns:
      the endpointId.
      Default:
      ""

    • matsFactoryCustomQualifierType

      Class<? extends Annotation> matsFactoryCustomQualifierType
      Specifies the MatsFactory to use by means of a specific qualifier annotation type (which thus must be meta-annotated with Qualifier). Notice that this will search for the custom qualifier annotation type, as opposed to if you add the annotation to the @MatsEndpointSetup-annotated method directly, in which case it "equals" the annotation instance (as Spring also does when performing injection with such qualifiers). The difference comes into play if the annotation has values, where e.g. a @SpecialMatsFactory(location="central") is not equal to @SpecialMatsFactory(location="region_west") - but they are equal when comparing types, as the qualification here does. Thus, if using this qualifier-approach, you should probably not use values on your custom qualifier annotations (instead make separate custom qualifier annotations, e.g. @MatsFactoryCentral and @MatsFactoryRegionWest for the example).
      Returns:
      the custom qualifier type which the wanted MatsFactory is qualified with.
      Default:
      java.lang.annotation.Annotation.class

    • matsFactoryQualifierValue

      String matsFactoryQualifierValue
      Specified the MatsFactory to use by means of specifying the @Qualifier value. Spring performs such lookup by first looking for actual qualifiers with the specified value, e.g. @Qualifier(value="the_value"). If this does not produce a result, it will try to find a bean with this value as the bean name.
      Returns:
      the qualifier value which the wanted MatsFactory is qualified with.
      Default:
      ""

    • matsFactoryBeanName

      String matsFactoryBeanName
      Specified the MatsFactory to use by means of specifying the bean name of the MatsFactory.
      Returns:
      the bean name of the wanted MatsFactory.
      Default:
      ""