This is an automated email from the ASF dual-hosted git repository. kwin pushed a commit to branch feature/document-version-manager in repository https://gitbox.apache.org/repos/asf/jackrabbit-oak.git
commit e6d5cd5e9f19e15f4f89573e00c9d03a8dd33077 Author: Konrad Windszus <[email protected]> AuthorDate: Thu Jan 16 20:13:02 2025 +0100 Document Version Manager --- oak-doc/pom.xml | 41 +++++++++++++++++ oak-doc/src/plantuml/versionStorage.puml | 53 ++++++++++++++++++++++ .../src/site/markdown/plugins/versionmanager.md | 46 +++++++++++++++++++ oak-doc/src/site/site.xml | 1 + 4 files changed, 141 insertions(+) diff --git a/oak-doc/pom.xml b/oak-doc/pom.xml index 5ae7c90a78..c642139eee 100644 --- a/oak-doc/pom.xml +++ b/oak-doc/pom.xml @@ -32,8 +32,49 @@ <url>http://jackrabbit.apache.org/oak/docs/</url> <packaging>jar</packaging> + <properties> + <version.plantuml-maven-plugin>0.2</version.plantuml-maven-plugin> + </properties> <build> <plugins> + <plugin> + <groupId>it.mulders.puml</groupId> + <artifactId>plantuml-maven-plugin</artifactId> + <version>${version.plantuml-maven-plugin}</version> + <dependencies> + <dependency> + <groupId>it.mulders.puml</groupId> + <artifactId>plantuml-v1-adapter</artifactId> + <version>${version.plantuml-maven-plugin}</version> + </dependency> + <dependency> + <groupId>net.sourceforge.plantuml</groupId> + <artifactId>plantuml</artifactId> + <version>1.2025.0</version> + </dependency> + </dependencies> + <executions> + <execution> + <id>generate-svg-from-plantuml</id> + <goals> + <goal>generate</goal> + </goals> + <phase>pre-site</phase> + <configuration> + <sourceFiles> + <directory>src/plantuml</directory> + <includes> + <include>**/*.dot</include> + <include>**/*.puml</include> + </includes> + </sourceFiles> + <outputDirectory>${project.reporting.outputDirectory}</outputDirectory> + <format>SVG</format> + <stripPath>src/plantuml</stripPath> + </configuration> + </execution> + </executions> + </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-site-plugin</artifactId> diff --git a/oak-doc/src/plantuml/versionStorage.puml b/oak-doc/src/plantuml/versionStorage.puml new file mode 100644 index 0000000000..4ba5a7735c --- /dev/null +++ b/oak-doc/src/plantuml/versionStorage.puml @@ -0,0 +1,53 @@ +/' +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +'/ +@startuml +!pragma layout smetana + + +package versionStorage { + object "frozenNode [nt:frozenNode]" as frozenNode1 + map "1.1 [nt:version]" as version2 { + jcr:frozenNode *-> frozenNode1 + jcr:predecessors => [1.0] + jcr:successors => [] + jcr:uuid => 345 + } + object "frozenNode [nt:frozenNode]" as frozenNode2 + map "1.0 [nt:version]" as version1 { + jcr:frozenNode *-> frozenNode2 + jcr:predecessors =>[jcr:rootVersion] + jcr:successors *-> version2 + jc:uuid => 234 + } + object "frozenNode [nt:frozenNode]" as frozenNode3 + map "jcr:rootVersion [nt:version]" as rootVersion { + jcr:frozenNode *-> frozenNode3 + jcr:predecessors => empty + jcr:successors *-> version1 + jcr:uuid => 123 + } +} + +map "myNode [mix:versionable]" as myNode { + jcr:baseVersion *-> rootVersion + jcr:predecessors *-> rootVersion + jcr:versionHistory => ?? + } +} +@enduml \ No newline at end of file diff --git a/oak-doc/src/site/markdown/plugins/versionmanager.md b/oak-doc/src/site/markdown/plugins/versionmanager.md new file mode 100644 index 0000000000..6fcb7d550a --- /dev/null +++ b/oak-doc/src/site/markdown/plugins/versionmanager.md @@ -0,0 +1,46 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + --> + +# Version Manager + +The [`javax.jcr.version.VersionManager`][jcr-versionmanager.javadoc] is implemented in Oak in [`ReadWriteVersionManager`][oak-github-rwversionmanager] + +TODO: Simple Versioning vs Full Versioning + +## Representation in Repository + +The root node of the versioned nodes is `/jcr:system/jcr:versionStorage`. +Below that follows the 128 bit UUID which is separated into a 3-level node hierarchy where each level covers 8 bit (=2 hexadecimal digits). +This limits the number of sibling nodes to 256 in those levels. Below follows a node with the name being equal to the `jcr:versionableUuid` property of the node. + +*This is not equal to is `jcr:uuid` property value!* + + + +## Relevant node types + +Node Type | Is Mixin | Description +--- | --- | --- +`mix:simpleVersionable` | yes | Used on nodes which should be versioned (prerequisite for checkin) +`mix:versionable` | yes | Used on nodes which should be versioned (prerequisite for checkin) +`nt:versionHistory` | no | Contains child nodes `jcr:versionLabels` and `jcr:rootVersion` +`nt:version` | no | Contains child node `jcr:frozenNode` +`nt:versionLabels` | no +`nt:frozenNode` | no | node type of the node containing the actual versioned node's content. + +[jcr-versionmanager.javadoc]: https://s.apache.org/jcr-2.0-javadoc/javax/jcr/version/VersionManager.html +[oak-github-rwversionmanager]: https://github.com/apache/jackrabbit-oak/blob/trunk/oak-jcr/src/main/java/org/apache/jackrabbit/oak/jcr/version/ReadWriteVersionManager.java \ No newline at end of file diff --git a/oak-doc/src/site/site.xml b/oak-doc/src/site/site.xml index 00d2845c72..aac9dab0c4 100644 --- a/oak-doc/src/site/site.xml +++ b/oak-doc/src/site/site.xml @@ -137,6 +137,7 @@ under the License. </item> <item href="features/atomic-counter.html" name="Atomic Counter" /> <item href="features/observation.html" name="Observation" /> + <item href="plugins/versionmanager.html" name="Version Manager" /> </menu> <menu name="Using Oak"> <item href="use_getting_started.html" name="Getting Started" />
