bitflicker64 commented on code in PR #511: URL: https://github.com/apache/hugegraph-doc/pull/511#discussion_r4225565134
########## content/en/docs/guides/shared-foundation-migration.md: ########## @@ -0,0 +1,231 @@ +--- +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 1.8.0 shared-foundation 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. | + +The implementation has merged into Server `master` through [apache/hugegraph#3270](https://github.com/apache/hugegraph/pull/3270), targeting 1.8.0. +Use matching Server, PD, Store and downstream artifacts when upgrading. +See the [source migration guide](https://github.com/apache/hugegraph/blob/master/docs/shared-foundation-migration.md) +for Java mappings 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 | +|---|---| +| Shared types listed below in `org.apache.hugegraph.backend.id` | `org.apache.hugegraph.id.*` | +| `org.apache.hugegraph.schema.*` metadata | `org.apache.hugegraph.struct.schema.*` | Review Comment: Minor: The table and the note below it list the classes that move out of `backend.id` and `backend.query`, but this schema row still reads as a whole-package move. In apache/hugegraph master, `hugegraph-core/src/main/java/org/apache/hugegraph/schema/` still contains `SchemaManager.java` and the `builder/` package. Only `EdgeLabel`, `IndexLabel`, `PropertyKey`, `SchemaElement`, `SchemaLabel`, `Userdata` and `VertexLabel` moved to `hugegraph-struct/.../struct/schema/`. Line 98 covers the builders, but `SchemaManager` is the type a plugin gets from `graph.schema()`, and it isn't a builder. A reader who rewrites `org.apache.hugegraph.schema.SchemaManager` to `struct.schema` because of this row gets an import that doesn't compile. Please list the moved schema classes here, as lines 92-96 do for IDs and queries, or add `SchemaManager` to the classes that stay in core. The CN page needs the same change at line 81 (and line 96). -- 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]
