kalix.javasdk.annotations.Subscribe Maven / Gradle / Ivy
/*
* Copyright 2021 Lightbend Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package kalix.javasdk.annotations;
import java.lang.annotation.*;
/**
* Annotation for providing ways to subscribe to different streams of information: value entities,
* event-sourced entities or topic.
*/
public @interface Subscribe {
/**
* Annotation for subscribing to updates from a Value Entity. It can be used both at type and
* method levels. When used at type level, it means the `View` or `Action` will not be transforming state.
* When used at method level, it gives the ability to transform the updates into a different state.
*/
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@interface ValueEntity {
/**
* Assign the class type of the entity one intends to subscribe to, which must extend {@link
* kalix.javasdk.valueentity.ValueEntity ValueEntity}.
*/
Class> value();
/**
* When true at type level of the `View` the subscription will automatically delete the view state based on ValueEntity deletion fact.
* When true at method level it allows to create a special handler for deletes (must be declared to receive zero parameters):
* {@code
* @Subscribe.ValueEntity(MyValueEntity.class)
* public UpdateEffect onChange(ValueEntity valueEntity) {
* return effects().updateState(...);
* }
*
* @Subscribe.ValueEntity(value = MyValueEntity.class, handleDeletes = true)
* public UpdateEffect onDelete() {
* return effects().deleteState();
* }
*
*
* The flag has no effect when used at type level of the `Action`. On the `Action` method level it allows to create a delete handler,
* similar to the example above.
*
*/
boolean handleDeletes() default false;
}
/**
* Annotation for subscribing to updates from an Event-sourced Entity.
*
* The underlying method must be declared to receive one or two parameters:
*
*
* - when one parameter is passed, the single parameter will be considered the event type such
* method will handle;
*
- when two parameters are passed, the first one will be considered the view state and the
* second one the event type.
*
*/
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@interface EventSourcedEntity {
/**
* Assign the class type of the entity one intends to subscribe to, which must extend {@link
* kalix.javasdk.eventsourcedentity.EventSourcedEntity EventSourcedEntity}.
*/
Class> value();
/**
* This option is only available for classes. Using it in a method has no effect.
*
*
* When there is no method in the class whose input type matches the event type:
*
* - if ignoreUnknown is true the event is discarded
* - if false, an Exception is raised
*
*/
boolean ignoreUnknown() default false;
}
/**
* Annotation for subscribing to messages from a topic (i.e PubSub or Kafka topic).
*/
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@interface Topic {
/**
* Assign the name of the topic to consume the stream from.
*/
String value();
/**
* Assign the consumer group name to be used on the broker.
*/
String consumerGroup() default "";
/**
* This option is only available for classes. Using it in a method has no effect.
*
*
* When there is no method in the class whose input type matches the event type:
*
* - if ignoreUnknown is true the event is discarded
* - if false, an Exception is raised
*
**/
boolean ignoreUnknown() default false;
}
/**
* Annotation for subscribing to messages from another Kalix service.
*/
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@interface Stream {
/**
* The unique identifier of the stream in the producing service
*/
String id();
/**
* The deployed name of the service to consume, can be the deployed name of another
* Kalix service in the same Kalix Project or a fully qualified public hostname of
* a Kalix service in a different project.
*
* Note: The service name is used as unique identifier for tracking progress in consuming it.
* Changing this name will lead to starting over from the beginning of the event stream.
*
* Can be a template referencing an environment variable "${MY_ENV_NAME}" set for the service at deploy
*/
String service();
/**
* When there is no method in the class whose input type matches the event type:
*
* - if ignoreUnknown is true the event is discarded
* - if false, an Exception is raised
*
**/
boolean ignoreUnknown() default false;
}
}