bitflicker64 commented on code in PR #511: URL: https://github.com/apache/hugegraph-doc/pull/511#discussion_r4183174499
########## content/en/docs/guides/shared-foundation-migration.md: ########## @@ -0,0 +1,220 @@ +--- +title: "1.8.0 shared-foundation migration" +linkTitle: "1.8.0 Java and upgrade migration" +description: "Update Java imports and plugins, then prepare matching Server, PD and Store upgrades for the 1.8.0 shared-foundation changes." +weight: 8 +--- + +The planned 1.8.0 migration changes Java imports and extension signatures, and requires Server, PD and Store to upgrade together. +Use this guide to identify affected code, rebuild your integrations and check existing data before deployment. + +## Find the work that applies to you + +| Your integration | What to prepare | +|---|---| +| Java code using Server IDs, schema metadata, queries or indexes | Update imports and affected signatures, then recompile against matching 1.8.0 artifacts. | +| Custom serializers, `HugeGraph` implementations or element subclasses | Adapt the SPI contracts and shared element state below. | +| Custom Gremlin imports or scripts | Replace the old `IdGenerator` class name and test packaged Gremlin startup. | +| Hubble, Java client or Computer integration | Apply the downstream exception changes when matching artifacts are available. | +| HStore deployment | Align the PD namespace, inspect legacy rebuilt indexes and upgrade all writers together. | +| Loader or another REST-only caller | Keep the independent client DTOs; migrate any actual affected Java calls. | + +These changes are planned for 1.8.0 and have not been released. +The [implementation PR](https://github.com/apache/hugegraph/pull/3270) includes the source migration document and compatibility fixtures. + +## Where shared code now lives + +Server core and struct previously carried separate implementations of several IDs, schema types, queries, elements and codecs. +The migration gives these shared types one owner so Server and Store can use the same implementation. +`hugegraph-core` continues to run the graph engine, `hugegraph-struct` supplies shared models and codecs, and `hugegraph-common` supplies utilities. + + + +*Core retains graph execution and adapters, Store retains storage and schema lifecycle, and struct/common own the shared implementations. +The arrows show shared ownership, not the full dependency tree.* + +| Owner | Responsibilities | +|---|---| +| struct | IDs, schema metadata, type codes, queries, base elements, property/byte codecs, index construction and analyzers | +| core | Transactions, traversal, tasks, schema mutation, backend adapters and index update orchestration | +| Store | PD-backed schema access, listeners and cache lifecycle through `SchemaGraph`/`SchemaDriver` | +| common | JWT signing/verification, shared auth constants and RPC configuration interfaces | + +The Server HStore adapter still needs PD and Store clients. Store retains its network, PD client and storage libraries. +PD and Store must not depend on core, and struct must not depend on core or PD clients. + +Core and Store implement `HugeGraphSupplier` to provide schema, configuration and clock access. +Shared base elements hold state and adjacency. `HugeVertex` and `HugeEdge` retain engine behavior and wrapper identity over that same state; +property mutation, cloning, removal, expiration and loading state must propagate through it. +Core serializers retain backend adapters and delegate shared encoding. +Shared index and OLAP selection receive schema candidates and result sinks from their callers; core keeps transaction writes and backend capability checks. + +## Update Java source and SPI implementations + +Start with the types your code imports. This ID construction call keeps the same string value while its imports move. + +**Before, using the 1.7.0 core API** + +```java +import org.apache.hugegraph.backend.id.Id; +import org.apache.hugegraph.backend.id.IdGenerator; + +Id vertexId = IdGenerator.of("vertex-1"); +``` + +**After, using the shared API** + +```java +import org.apache.hugegraph.id.Id; +import org.apache.hugegraph.id.IdGenerator; + +Id vertexId = IdGenerator.of("vertex-1"); +``` + +Recompile the application and its plugins after adapting source. Relocated types also change method descriptors, +so editing imports cannot make an old compiled jar binary-compatible. Removed core classes have no general compatibility package. +The [plugin examples](/docs/guides/custom-plugin/) still describe 1.7.0; apply the following mappings when targeting the migrated API. + +| Previous Java entry | Use in the migrated API | +|---|---| +| `org.apache.hugegraph.backend.id.*` | `org.apache.hugegraph.id.*` | Review Comment: Important: The `backend.id.*` row (line 80) and the `backend.query.*` row (line 82) tell readers to move every class in those packages, but some of them stay in core under their old names. At apache/hugegraph#3270 head `eee539d49d67`, `hugegraph-core/.../backend/id/` still holds `SnowflakeIdGenerator`, and `hugegraph-core/.../backend/query/` still holds `QueryResults`, `ConditionQueryFlatten`, `EdgesQueryIterator`, `QueryBatch` and `QueryResultContext`. Neither `org.apache.hugegraph.id` nor `org.apache.hugegraph.query` in struct has any of these classes, and 34 source files in that PR still import `backend.query.QueryResults` or `SnowflakeIdGenerator` from core. A plugin or custom backend that rewrites these imports as the table says will not compile, and `QueryResults` is a common import for custom backends. The note on line 90 only names schema builders and backend serializers as exceptions. Please list the moved classes explicitly in these two rows (`Id`, `IdGenerator`, `EdgeId `, `IdUtil`, `SplicingIdGenerator`; `Query`, `ConditionQuery`, `Condition`, `IdQuery`, `IdPrefixQuery`, `IdRangeQuery`, `BatchConditionQuery`, `Aggregate`), or say which classes stay in core. The same rows are on lines 79 and 81 of `content/cn/docs/guides/shared-foundation-migration.md`, and in `docs/shared-foundation-migration.md` of #3270. -- 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] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
