High-level sequence of changes to adopt AS 2.0
- Move the json schemas and test documents out of streams-pojo into their own module, isolating them from streams interfaces and utilities, with an as1 designation in the module and package.
Something like: https://github.com/apache/incubator-streams/pull/284/commits/0424855cf0a4fd15be298906922333ae74c8e9ae - Complete initial implementation of a org.apache.streams controlled maven plugin for generating java pojos - allowing the project to have all necessary control over how these artifacts turn out.
First take at that plugin: https://github.com/apache/incubator-streams/pull/284/commits/7b8ef0a22707af88426c18e0869ad01a261602c5 - Switch use of jsonschema2pojo maven plug in throughout code base to a similar org.apache.streams controlled maven plugin.
Basically just use the above plugin everything instead and ensure everything that uses it still builds and tests still pass. - Collect static json ld resources and test documents into a new as2 module.
Just as schemas supporting streams code are hosted at streams.incubator.apache.org, some existing and some new JSON-LD context documents likely will be too we'll start by collecting basic draft AS 2.0 into the source tree. Figure out whether we need/want to generate different POJOs for 2.0 vs 1.0 or if interoperability with both using one generated artifact per class is possible.
Write test cases sufficient to demonstrate minimal compliance with as 2.0 only for core processing outside of streams.
Stuff likely needed to implemented and test for compliance (confirm this with W3C community):
- Support updated vocabulary
- Support for most fields may be either a primitive or an object or an array
- Support for new 'Map' suffix fields for internationalization
- ID resolution and object de-referencing to a URI
- Backward / forward compatibility with AS 1.0
- Resolve and track details of other contexts i.e. schema.org
- Almost certainly more
Begin develop in a new module or branch - a streams-pojo variant to use in satisfying these test cases.
May involve changes to core interfaces - that's OK
At this point the project can assert support for 2.0 but most providers and other components cannot.
- In parallel we can work to bring all providers (other than some which are no longer running) current with api and data format in the wild, and add with integration testing against real endpoints.
- Sort out a way for persistent credentials to be created that can be used by Jenkins, and a convention for developers to supply credentials for their own testing from CLI.
Analyze providers as described below.
- youtube
- googleplus
- rss
- foursquare
- moreover
- sysomos
For each provider module we should create a matrix of endpoints vs object and activity types. Example:
| native object | native activity | normalized object(s) | normalized activity(ies) | normalized relationship(s) | |
|---|---|---|---|---|---|
| /users | o.a.s.t.User | o.a.s.p.as1.Page (1.0) o.a.s.p.as2.Profile (2.0) | |||
| /statuses |
| o.a.s.t.Tweet o.a.s.t.Retweet | o.a.s.p.as1.Post (1.0) o.a.s.p.as_.Note (1.x) (2.0) | ||
| /friends | o.a.s.t.Follow | o.a.s.p.as_.Follow (1.0) (2.0) | o.a.s.p.as2.r.IsFollowing o.a.s.p.as2.r.IsFollowedBy | ||
| /followers | o.a.s.t.Follow | o.a.s.p.as_.Follow (1.0) (2.0) | o.a.s.p.as2.r.IsFollowing o.a.s.p.as2.r.IsFollowedBy | ||
| /userstream | o.a.s.t.Delete o.a.s.t.FriendList o.a.s.t.UserstreamEvent | o.a.s.p.as_.Delete (1.0) (2.0) o.a.s.p.as2.Delete o.a.s.p.as_.Block (1.x) (2.0) o.a.s.p.as_.Create (1.x) (2.0) o.a.s.p.as_.Like (1.x) (2.0) |
Note: This design exercise illuminates the coverage of within the AS 2.0 draft spec that is expected to be achieved with each provider integration after implementation
(1.0) : Implemented for 1.0
(1.x) : Sensible but not yet implemented for 1.0
(2.0) : Only sensible to implement for 2.0 not 1.0
(N/A) : No match with core AS 2.0
Do the same for the project road map of not yet implemented providers which supply documents that generally align with AS 2.0
There is not existing provider for foursquare, tumblr, meetup, github, reddit, soundcloud, but appropriate APIs exist and support additional portions of the AS 2.0 spec
Start breaking refactoring and net new work into stories and tasks
Start upgrading providers to support generation of as 2.0 one at a time
Augment or alter integration testing piece by piece - once upgraded provider integration testing should cover AS 1.0 and AS 2.0 formatted output
Implement providers to fill in key parts of 2.0 spec not covered by existing providers.