Cole-Greer commented on code in PR #3523: URL: https://github.com/apache/tinkerpop/pull/3523#discussion_r3605898270
########## docs/src/dev/provider/index.asciidoc: ########## @@ -192,12 +192,52 @@ The following bullets provide some tips to consider when implementing the struct `Graph open(Configuration)` method where the `Configuration` is an Apache Commons class of that name. Alternatively, the `Graph` implementation can have the `GraphFactoryClass` annotation which specifies a class with that static `Graph open(Configuration)` method. +* `Vertex` +** By default a vertex has exactly one immutable label. Graphs that want to support multiple, mutable, or zero +labels should follow the <<multi-label-support,Multi-Label Support>> section below. * `VertexProperty` ** This interface is both a `Property` and an `Element` as `VertexProperty` is a first-class graph element in that it can have its own properties (i.e. meta-properties). Even if the implementation does not intend to support meta-properties, the `VertexProperty` needs to be implemented as an `Element`. `VertexProperty` should return empty iterable for properties if meta-properties is not supported. +[[multi-label-support]] +==== Multi-Label Support + +By default a vertex has exactly one immutable label, matching the 3.x behavior. Providers that want to support +multiple, mutable, or zero labels declare their supported label cardinality via +`Graph.Features.VertexFeatures#getLabelCardinality()`, which defaults to `LabelCardinality.ONE`. To support +multi-label, return `ONE_OR_MORE` or `ZERO_OR_MORE` from this method. This value may be a static constant for +graphs which do not offer configurable label cardinality. The label cardinality should reflect the current `Graph` +instance. + +The `LabelCardinality` enum exposes `min()`, `max()`, and `supportsMutation()` for programmatic introspection of +constraints. Constraint enforcement is handled by the `LabelCardinalityValidator` utility class, which providers may +use directly or replace with their own validation logic tailored to their storage backend. + +Providers implementing multi-label must: + +- Store and return a `Set<String>` from `Element.labels()` +- Implement `Element.addLabel(String, String...)`, `Element.dropLabel(String, String...)`, and `Element.dropLabels()` Review Comment: I'm not sure this is the best presentation for these items. How a provider chooses to store labels is not significant, they may store them as a Set behind the scenes which is fine. The critical piece here which is unique to multilabelled graphs, is that they MUST override all of `Element.labels()`, `Element.addLabel(String, String...)`, `Element.dropLabel(String, String...)`, and `Element.dropLabels()`. What's unique about this situation compared to before is that none of these methods are abstract in `Element` (they all have default implementations which follow single-label semantics). That is a bit of a trap and really should be the focus here. -- 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. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
