Merge pull request #34 from xdev-software/docs

Docs

Author: JohannesRabauer

.github/workflows/antora-build.yml

@@ -0,0 +1,51 @@
+name: Antora Documentation Build  # Name of the GitHub Actions workflow
+
+on: workflow_dispatch  # This workflow is triggered manually
+
+env:
+  ACTIONS_STEP_DEBUG : true
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read  # Read permission for repository contents
+  pages: write    # Write permission for GitHub Pages
+  id-token: write  # Write permission for ID token
+  
+jobs:
+  build:
+    runs-on: ubuntu-latest  # Run the job on a machine with the latest version of Ubuntu
+
+    environment:
+      name: github-pages  # Environment name
+      url: https://github.com/xdev-software/spring-data-eclipse-store
+
+    steps:
+      - name: Checkout repository  # Step to check out the repository
+        uses: actions/checkout@v4
+
+      - name: Install Node.js  # Step to install Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18  # Specify Node.js version
+
+      - name: Install Antora and the Antora Lunr Extension  # Step to install Antora and the Lunr extension
+        run: npm i antora @antora/lunr-extension
+
+      - name: Generate Site  # Step to generate the documentation site
+        run: GIT_CREDENTIALS=https://${{ secrets.GITHUB_TOKEN }}:@github.com npx antora docs/antora-playbook.yml --fetch --stacktrace #GIT_CREDENTIALS are needed if the source repo with the documentation is private! 
+
+      - name: Setup Pages  # Step to set up GitHub Pages
+        uses: actions/configure-pages@v3
+
+      - name: Upload artifact  # Step to upload an artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          name: site  # Specify the name of the artifact
+          path: docs/site  # Specify the path to the artifact
+
+      - name: Deploy to GitHub Pages  # Step to deploy the site to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}  # Specify the GitHub token for deployment
+          artifact_name: site  # Specify the name of the artifact to deploy

docs/antora-playbook.yml

@@ -0,0 +1,36 @@
+site:
+  title: Spring-Data-Eclipse-Store
+  url: https://xdev-software.github.io/spring-data-eclipse-store/
+  robots: allow
+
+# see https://docs.antora.org/antora/2.3/playbook/configure-runtime/
+runtime:
+  cache_dir: ./.cache/antora
+  log:
+    # use pretty even on CI
+    format: pretty
+    # set to info to get details from the Antora extensions
+    level: info
+    # Antora exits with a non-zero exit code if an error is logged -> https://docs.antora.org/antora/latest/playbook/runtime-log-failure-level
+    failure_level: error
+  
+content:
+  sources:
+  # url of the repo 
+  - url: https://github.com/xdev-software/spring-data-eclipse-store
+    start_path: docs
+    branches:
+      - "master" 
+
+ui: 
+  bundle:
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
+    snapshot: true
+  supplemental_files: ./supplemental-ui
+
+output:
+  dir: ./site
+
+antora:
+  extensions:
+  - require: '@antora/lunr-extension'

docs/antora.yml

@@ -0,0 +1,14 @@
+name: manual
+title: Spring-Data-Eclipse-Store
+version: master
+display_version: '1.0'
+start_page: index.adoc
+nav:
+  - modules/ROOT/nav.adoc
+asciidoc:
+  attributes:
+    product-name: 'Spring-Data-Eclipse-Store'
+    display-version: '1.0.3'
+    maven-version: '1.0.3'
+    page-editable: false
+    page-out-of-support: false

docs/modules/ROOT/assets/images/WorkingCopy_1.svg

@@ -0,0 +1,5 @@
+* xref:index.adoc[Home]
+* xref:installation.adoc[Installation]
+* xref:working-copies.adoc[Working Copies]
+* xref:migration.adoc[Migration]
+* xref:known-issues.adoc[Known issues]

docs/modules/ROOT/assets/images/WorkingCopy_2.svg

@@ -0,0 +1,24 @@
+= Overview
+
+== About Spring-Data-Eclipse-Store
+
+A library to simplify using https://eclipsestore.io/[EclipseStore] in the https://spring.io/projects/spring-data/[Spring environment].
+
+What makes this library special is, that it creates a xref:working-copies.adoc[working copy] of the data.
+This way EclipseStore behaves almost exactly like relational database from a coding perspective.
+
+== Features
+
+The library provides following features:
+
+* Enforces the
+https://docs.spring.io/spring-data/jpa/reference/repositories/core-concepts.html[Spring data repository concept]
+for EclipseStore by using xref:working-copies.adoc[working copies].
+* xref:installation.adoc#drop-in-compatible[Drop in compatible] for your existing Spring application
+* Utilizes *ultra-fast EclipseStore serializing and storing*
+* Enables your application to select any https://docs.eclipsestore.io/manual/storage/storage-targets/index.html[EclipseStore target] (e.g.
+https://docs.eclipsestore.io/manual/storage/storage-targets/sql-databases/postgresql.html[PostgreSQL],
+https://docs.eclipsestore.io/manual/storage/storage-targets/blob-stores/aws-s3.html[AWS S3] or
+https://github.com/xdev-software/eclipse-store-afs-ibm-cos[IBM COS])
+* Can save up to *99%footnote:[If the COS Connector is used in the IBM Cloud instead of a PostgreSQL and approx. 10,000 entries with a total size of 1 GB of data are stored. (https://cloud.ibm.com/estimator/estimates[IBM Cloud Pricing], as of 08.01.2024)] of monthly costs* in the IBM Cloud and up to 82%footnote:[If the S3 connector is used instead of DynamoDB under the same conditions at AWS.
+(https://calculator.aws/#/estimate?id=ab85cddf77f0d1aa0457111ed82785dfb836b1d8[AWS Pricing Calculator], as of 08.01.2024)] in the AWS Cloud

docs/modules/ROOT/nav.adoc

@@ -0,0 +1,45 @@
+= Installation
+
+== Build Configuration
+
+You can find the {product-name} libraries in the Maven Central repository.
+
+Simply add the following dependency to your maven project
+
+[source,xml,subs=attributes+,title="Maven [pom.xml]"]
+----
+<dependencies>
+    <dependency>
+       <groupId>software.xdev</groupId>
+       <artifactId>spring-data-eclipse-store</artifactId>
+       <version>{maven-version}</version>
+    </dependency>
+</dependencies>
+----
+
+Also see the https://github.com/xdev-software/spring-data-eclipse-store/releases/latest#Installation[installation guide for the latest release].
+
+== Configuration
+
+After adding the library in your dependencies, using it is as easy as adding the ``@EnableEclipseStoreRepositories`` annotation to your ``@SpringBootApplication`` annotation.
+
+[NOTE]
+====
+Since the library is using reflection to copy data, the following JVM-Arguments may have to be set.
+
+[source,title="JVM Arguments"]
+----
+--add-opens=java.base/java.util=ALL-UNNAMED
+--add-exports java.base/jdk.internal.misc=ALL-UNNAMED
+--add-opens=java.base/java.lang=ALL-UNNAMED
+--add-opens=java.base/java.time=ALL-UNNAMED
+----
+====
+
+== Demo
+
+To see how easy it is to implement EclipseStore in your Spring project, take a look at the three https://github.com/xdev-software/spring-data-eclipse-store/tree/develop/spring-data-eclipse-store-demo[demos]:
+A https://github.com/xdev-software/spring-data-eclipse-store/tree/develop/spring-data-eclipse-store-demo/src/main/java/software/xdev/spring/data/eclipse/store/demo/simple[simple], a more https://github.com/xdev-software/spring-data-eclipse-store/tree/develop/spring-data-eclipse-store-demo/src/main/java/software/xdev/spring/data/eclipse/store/demo/complex[complex demo] and a https://github.com/xdev-software/spring-data-eclipse-store/tree/develop/spring-data-eclipse-store-jpa/src/main/java/software/xdev/spring/data/eclipse/store/jpa[demo with coexisting JPA].
+
+== Drop in compatible [[drop-in-compatible]]
+//TODO

docs/modules/ROOT/pages/index.adoc

@@ -0,0 +1,39 @@
+= Known issues
+
+== Lazy references
+
+One of the core features of EclipseStore is its https://docs.eclipsestore.io/manual/storage/loading-data/lazy-loading/index.html[Lazy references].
+Unfortunately this requires our library to implement some kind of proxy.
+That's something that takes a lot of effort to implement in our {product-name}.
+
+We created https://github.com/xdev-software/spring-data-eclipse-store/issues/31[an issue] for that but right now we *do not support Lazy references*.
+
+== Query annotations
+
+In Spring-Data-JPA you can write a Query over methods of repositories like this:
+
+[source,java,title="From https://github.com/spring-projects/spring-petclinic/blob/main/src/main/java/org/springframework/samples/petclinic/owner/OwnerRepository.java[spring-petclinic]"]
+----
+@Query("SELECT ptype FROM PetType ptype ORDER BY ptype.name")
+List<PetType> findPetTypes();
+----
+
+We created https://github.com/xdev-software/spring-data-eclipse-store/issues/32[an issue] for that but right now we *do not support Query annotations*.
+
+== Data changes
+
+There are two basic ways to keep your data up to date.
+
+=== Structural
+
+As with most projects, data that needs persisting changes over time.
+In EclipseStore that's handled through https://docs.eclipsestore.io/manual/storage/legacy-type-mapping/index.html[Legacy Type Mapping].
+
+That consists of https://docs.eclipsestore.io/manual/storage/legacy-type-mapping/index.html#_automatic_mapping[Automatic Mapping] through EclipseStores internal heuristic and https://docs.eclipsestore.io/manual/storage/legacy-type-mapping/index.html#explicit-mapping[Explicit Mapping] by the user.
+
+=== Values
+
+There is a library to version your data in the store called https://github.com/xdev-software/micro-migration[XDEV MicroMigration].
+This helps you keep your data up to date regardless of the current version.
+
+We created https://github.com/xdev-software/spring-data-eclipse-store/issues/33[an issue] for that but right now we *do not support XDEVs MicroMigration*.

docs/modules/ROOT/pages/installation.adoc

@@ -0,0 +1,36 @@
+= Migration
+
+Migrating from Spring Data JPA is very easy.
+We implemented a https://github.com/xdev-software/spring-data-eclipse-store-migration[OpenRewrite recipe] for that.
+It can be executed with a simple Maven command:
+
+[source,title="Maven"]
+----
+mvn org.openrewrite.maven:rewrite-maven-plugin:run \
+-Drewrite.recipeArtifactCoordinates=software.xdev:spring-data-eclipse-store-migration \
+-Drewrite.activeRecipes=software.xdev.spring.data.eclipse.store.JpaMigration
+----
+
+[CAUTION]
+====
+Since {product-name} can't handle ``@Query``-Annotations, these annotations are getting removed by the Rewrite-Recipe.
+====
+
+== Data
+
+To import data from different data sources like JPA, you can simply let the ``EclipseStoreDataImporterComponent`` get injected and then call ``importData()``.
+This reads all instances of ``EntityManagerFactory``, creates EclipseStoreRepositories for it and then imports that data.
+This can take quite some time if you have a lot of data.
+
+[source,java]
+----
+@Autowired
+private EclipseStoreDataImporterComponent eclipseStoreDataImporter;
+
+void importDataFromJpaToEclipseStore()
+{
+    final List<SimpleEclipseStoreRepository<?, ?>> repositories = this.eclipseStoreDataImporter.importData();
+}
+----
+
+After that you can change your JpaRepositories to EclipseStoreRepositories and you're done.

docs/modules/ROOT/pages/known-issues.adoc

@@ -0,0 +1,15 @@
+= Working copies
+
+If you use EclipseStore without our library, EclipseStore loads the data from the datastore directly into memory. You make your changes on these loaded Java objects and by calling ``store`` EclipseStore writes it directly from memory to the datastore.
+
+image::../images/WorkingCopy_1.svg[Native behavior of EclipseStore]
+
+If you e.g. change the address of a person, the changed address is already in your data model, *even before storing* this person.
+This is very different from the behavior a Spring user expects.
+
+image::../images/WorkingCopy_2.svg[Behavior of EclipseStore with Spring-Data-Eclipse-Store]
+
+With {product-name} every time an object is loaded from the datastore, a working copy of that object (or rather the object tree) is created and returned to the user.
+Therefore, the user can make the changes on the working copy without any changes to the actual data model.
+The changes are only persisted after calling ``save`` on a repository.
+

docs/modules/ROOT/pages/migration.adoc

@@ -0,0 +1,9 @@
+{
+  "dependencies": {
+    "@antora/lunr-extension": "^1.0.0-alpha.8"
+  },
+  "devDependencies": {
+    "@antora/cli": "3.1.4",
+    "@antora/site-generator": "3.1.4"
+  }
+}

docs/modules/ROOT/pages/working-copies.adoc

@@ -0,0 +1,47 @@
+body {
+	font-family: sans-serif;
+}
+
+.navbar {
+	background-color: #fff;
+}
+
+footer.footer {
+	color: #fff;
+	background-color: #333333;
+}
+
+footer.footer a,
+footer.footer .link-separator
+{
+	color: #c02222;
+}
+
+.navbar-item {
+	padding: 0px 8px;
+}
+
+.navbar-brand .navbar-item.logo {
+	align-self: center;
+	padding: 0;
+}
+
+.navbar-brand .navbar-item.logo img {
+	width: inherit;
+}
+
+.navbar-brand .navbar-item.title {
+	align-self: center;
+	color: var(--navbar-font-color);
+	font-size: 1rem;
+	line-height: 1;
+	position: relative;
+	top: 0.06em; /* compensate for built-in line height in font */
+	letter-spacing: -0.02em;
+	padding: 0;
+	margin: 0 1rem;
+}
+
+.doc h1 {
+	color: #333333;
+}