sashapolo commented on a change in pull request #153:
URL: https://github.com/apache/ignite-3/pull/153#discussion_r643157555
##########
File path:
modules/network-api/src/main/java/org/apache/ignite/network/annotations/AutoMessage.java
##########
@@ -32,41 +30,65 @@
import org.apache.ignite.network.serialization.MessageSerializer;
/**
- * Annotation for marking network message interfaces (i.e. those extending the
{@link NetworkMessage} interface). For
- * such interfaces, the following classes will be generated:
+ * Annotation for interfaces intended to be used as <i>Network Messages</i>. A
Network Message is an interface that
+ * must satisfy the following requirements:
+ *
+ * <ol>
+ * <li>It must extend the {@link NetworkMessage} interface either directly
or transitively;</li>
+ * <li>It must only contain Ignite-style getter methods that represent the
message's properties.</li>
+ * </ol>
+ *
+ * When such interface is marked by this annotation, it can be used by the
annotation processor to generate
+ * the following classes:
+ *
+ * <ol>
+ * <li>Builder interface with setters for all declared properties;</li>
+ * <li>An immutable implementation of the message and a nested
implementation of the generated builder
+ * for creating new message instances;</li>
+ * </ol>
+ *
+ * If the {@link #autoSerializable} property is set to {@code true}, the
annotation processor will additionally generate
+ * serialization-related classes:
*
* <ol>
* <li>{@link MessageSerializer};</li>
* <li>{@link MessageDeserializer};</li>
* <li>{@link MessageSerializationFactory}.</li>
* </ol>
- * <p>
- * These messages must obey the <i>network message declaration contract</i>
and can only contain
- * <i>directly marshallable types</i>, which can be one of the following:
+ *
+ * Properties of messages that can be auto-serialized can only be of
<i>directly marshallable type</i>,
+ * which is one of the following:
*
* <ol>
* <li>Primitive type;</li>
- * <li>{@link String};</li>
+ * <li>{@code String};</li>
* <li>{@link UUID};</li>
* <li>{@link IgniteUuid};</li>
* <li>{@link BitSet};</li>
- * <li>Nested {@link NetworkMessage};</li>
+ * <li>Nested {@code NetworkMessage};</li>
* <li>Array of primitive types, corresponding boxed types or other
directly marshallable types;</li>
- * <li>{@link Collection} of boxed primitive types or other directly
marshallable types;</li>
- * <li>{@link Map} where both keys and values can be of a directly
marshallable type.</li>
+ * <li>{@code Collection} of boxed primitive types or other directly
marshallable types;</li>
+ * <li>{@code Map} where both keys and values can be of a directly
marshallable type.</li>
* </ol>
+ *
+ * After all messages in the module have been processed, the processor will
use the <i>module descriptor</i> (class
+ * annotated with {@link ModuleMessageTypes}) to expose the builders via a
+ * Message Factory.
+ *
+ * @see ModuleMessageTypes
*/
-// TODO: describe the message declaration contract, see
https://issues.apache.org/jira/browse/IGNITE-14715
@Target(ElementType.TYPE)
// using the RUNTIME retention policy in order to avoid problems with
incremental compilation in an IDE.
@Retention(RetentionPolicy.RUNTIME)
-public @interface AutoSerializable {
+public @interface AutoMessage {
+ /**
+ * This message's type as described in {@link NetworkMessage#messageType}.
+ */
+ short value();
+
/**
- * Message factory class that will be used to create message builders
during deserialization.
- * <p>
- * Message factories must have a static method with the same name as the
created message type and return a builder
- * for that type, e.g. a factory for creating {@code TestMessage}
instances must have a {@code TestMessage.Builder
- * testMessage()} method.
+ * When this property is set to {@code true} (default),
serialization-related classes will be generated in addition
+ * to the message implementation.
*/
- Class<?> messageFactory();
+ boolean autoSerializable() default true;
Review comment:
If I remember correctly, there is a use-case where you would want to
write the serializers yourself, because they don't fit the standard
auto-generated model
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
