Duplicate all eventstream event shapes + add new legacy event modes

[alextwoods]

Fixes codegeneration issues for eventstreams with shared event shapes: Duplicate and rename all eventstream event shapes with a unique name + add new disableUniqueEventStreamShapePreprocessing customization config.

Motivation and Context

When an event shape is shared between multiple eventstreams, it causes SDK generation/compilation failures. The top level shape POJO implements the event stream interface for each stream and the return type of the sdkEventType method conflicts.

Modifications

This PR does two things:

1. Adds a new disableUniqueEventStreamShapePreprocessing customization config.
2. If both useLegacyEventGenerationScheme and disableUniqueEventStreamShapePreprocessing is unset a for an event, the event shape will be duplicated and given a unique name: <ShapeName><EventStreamName>.

Note: There are a large number of changes in the codegen test to add the new customization mode to existing test eventstreams.

Open Questions

What naming scheme should we use to produce unique names?

This PR currently uses <ShapeName><EventStreamName>, for example an event named Payload in eventstream StreamA would get the name: PayloadStreamA. We could reverse this (StreamAPayload).

The downside of this naming scheme is that it can produce long names. For example the existing HeartbeatEvent from LexRuntimeV2's StartConversationResponseEventStream would be (without the legacy customization) renamed to: HeartbeatEventStartConversationResponseEventStream.

FAQ

Why do we always need to rename the event shape? Couldn't we do that only when there is a shared event?

We must ensure that shapes names are deterministic and do not depend on the shapes in the model because if a shared event shape is added in the future, we have no way of telling which was the existing shape.

Alternatives

For POCs of alternative approaches see:

• Support through customization: Add processor to detect shared events + customization to duplicate. #6031
• Remove eventstream interface from generic POJOs: https://github.com/alextwoods/aws-sdk-java-v2/pull/2/files
• add SDKEventType interface: Demo of orig eventstream with shared events: add sdkEventType interface alextwoods/aws-sdk-java-v2#3

User Experience

There are no changes for users for any existing Eventstreams/events. New eventstreams or new events added to existing evenstreams will have unique, longer names, but the fluid visitor and builder methods will continue to use the member names. For example, assuming we have Payload event (with member name "PayloadEvent") in eventstream StreamA, the handler and builder methods will still be onPayloadEvent and payloadEventBuilder.

// Handling events
StreamAResponseHandler.builder()
    .subscriber(
        StreamAResponseHandler.Visitor.builder()
            .onPayloadEvent(event -> { // NOTE: onPayload is still used because the member name is "PayloadEvent"
                System.out.println("Payload event: " + event);
            })
            .build()
    );

// sending events
subscriber.onNext(
    StreamA.payloadEventBuilder() // NOTE: We still use `payloadEventBuilder` because the member name is "Payload"
        .payload("text/plain;charset=utf-8")
        .build()
);

Note: For users using switch/case or if/else on sdkEventType or checking instance of, when casting the events they will need to use the longer shape names. Using the example from above:

subsciber(event -> {
    if (event instanceof PayloadStreamA) { // NOTE: we need to check the rename/unique shape name here
        handlePayloadEvent((PayloadStreamA)event);
    }
});

subscriber(event -> {
    switch(event.sdkEventType()) {
        case PAYLOAD_EVENT: // the sdkEventType will still use the member name
            handlePayloadEvent((PayloadStreamA)event); // Note: Need to cast to the renamed/uniqe shape name
            break;
    }
})

Testing

New Unit tests - see shared event stream cases (model was modified to add new streams that share an event)

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)

Checklist

• I have read the CONTRIBUTING document
• Local run of mvn install succeeds
• My code follows the code style of this project
• I have added tests to cover my changes
• All new and existing tests passed
• I have added a changelog entry. Adding a new entry must be accomplished by running the scripts/new-change script and following the instructions. Commit the new file created by the script in .changes/next-release with your changes.

License

• I confirm that this pull request can be released under the Apache 2 licens

[dagnir]

The downside of this naming scheme is that it can produce long names. For example the existing HeartbeatEvent from LexRuntimeV2's StartConversationResponseEventStream would be (without the legacy customization) renamed to: HeartbeatEventStartConversationResponseEventStream.

The current non-legacy way is there's a package per eventstream, e.g. software.amazon.awssdk.services.lexruntimev2.model.startconversationresponseeventstream that contains the event stream specific event classes. Could we do something similar in this case?

[alextwoods]

The current non-legacy way is there's a package per eventstream, e.g. software.amazon.awssdk.services.lexruntimev2.model.startconversationresponseeventstream that contains the event stream specific event classes. Could we do something similar in this case?

We could, but it would require fairly large changes in multiple parts of the code generation and require maintaining 3 separate paths through codegen (for each of the cases) including marshallers, builders and others.

The benefit of renaming the shape up front is that all other parts of the codegen are able to remain the same, but it doesn't let us change the packaging/namespace of the generated classes.

[alextwoods]

The current non-legacy way is there's a package per eventstream, e.g. software.amazon.awssdk.services.lexruntimev2.model.startconversationresponseeventstream that contains the event stream specific event classes. Could we do something similar in this case?

I did try to put together a POC for this but It would require a much more significant refactoring to get working. There are a few issues/sharp edges:

1. In some cases we need both the model. and model.. POJOs (an event in a legacy ES + in a new, non-legacy ES).
2. There are package private model classes that are required by the event pojos. We would need to make these public to allow access/usage in the eventstream model package).
3. Fairly extensive updates to code generation for marshallers, async client (usage of marshallers), Builders, Handlers to ensure the correct types are used (each place needs to switch behavior on legacy modes).

[dagnir]

Just checking: is it necessary to have eventmember.getShape() be capitalized here?

[alextwoods]

What do you mean? The parameter name eventMember? Or do you mean we should apply some naming transform of the shape name to ensure it has correct capitalization?

RE: the parameter name, theres no reason it couldn't be eventmember.

RE: applying capitalization to the existing shape name - Thats a good question - I was assuming that the existing shape name has already been validated (and any divergence from standard is intended and should be preserved).

[dagnir]

Can we have tests to verify the code for DefaultPerson?

[alextwoods]

The SharedStreamAwsModelSpecTest is testing only the interfaces, but EventModelSpecTest (which uses a different model) tests tests the Default<Shape> generation (but not the interfaces) for event stream event shapes - between the two I think we get decent coverage of all of the files we're generating.

It might be a little tricky, but the SharedStreamAwsModelSpecTest could probably be updated to test the implementations (ie Default<shape>.java) as well but we would need to add files for all of the shapes I think. What do you think?

[dagnir]

Yeah let's do that please. I don't think we need to do it for every renamed shape, just for a sample.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
96.9% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud