DOCS-173 Update structure for new tutorials subsite (#64)

JakeSCahill · web-flow · commit 0dade83b4a78 · 2022-06-07T13:48:07.000+03:00
* DOCS-173 Update structure for new tutorials subsite

* Add examples to unique directories

Directories are shared among all tutorials, so we must do this to avoid conflicts with duplicate files

* Update symlinks

* Restructure

* Restructure

* Rename file

* Update build filters

* Change to IMDG
diff --git a/.github/workflows/build-site.yml b/.github/workflows/build-site.yml
@@ -0,0 +1,13 @@
+# This workflow takes the contents of the branches/tags and builds the production documentation site
+name: Build production site
+
+on:
+  push:
+    branches: [master]
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Trigger build
+      run: curl -X POST -d {} https://api.netlify.com/build_hooks/6238ac2881e6d20c7db8e6c8
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -2,10 +2,10 @@ name: build
 on:
   push:
     paths-ignore:
-      - 'doc/**'
+      - 'docs/**'
   pull_request:
     paths-ignore:
-      - 'doc/**'
+      - 'docs/**'
 
 jobs:
   build:
diff --git a/.github/workflows/guide-website-update.yml b/.github/workflows/guide-website-update.yml
diff --git a/README.adoc b/README.adoc
@@ -0,0 +1 @@
+See the link:https://docs.hazelcast.com/tutorials/springboot-hibernate[tutorial].
diff --git a/README.md b/README.md
diff --git a/doc/antora.yml b/doc/antora.yml
diff --git a/doc/modules/ROOT/pages/index.adoc b/doc/modules/ROOT/pages/index.adoc
diff --git a/docs/antora.yml b/docs/antora.yml
@@ -0,0 +1,2 @@
+name: tutorials
+version: ~
diff --git a/docs/modules/ROOT/examples/springboot-hibernate/pom.xml b/docs/modules/ROOT/examples/springboot-hibernate/pom.xml
@@ -0,0 +1 @@
+../../../../../pom.xml
diff --git a/docs/modules/ROOT/examples/springboot-hibernate/src b/docs/modules/ROOT/examples/springboot-hibernate/src
@@ -0,0 +1 @@
+../../../../../src
diff --git a/docs/modules/ROOT/pages/springboot-hibernate.adoc b/docs/modules/ROOT/pages/springboot-hibernate.adoc
@@ -0,0 +1,107 @@
+= Get Started with Hazelcast and Hibernate Second-Level Cache
+:templates-url: templates:ROOT:page$/
+:page-layout: tutorial
+:page-product: imdg
+:page-categories: Caching, Getting Started, Hibernate
+:page-lang: java
+:page-edition: 
+:page-est-time: 10 mins
+:framework: Spring Boot
+:description: In this tutorial, you'll learn how to quickly set up a Spring Boot application using Hazelcast as a Hibernate second-level cache.
+
+== What You’ll Learn
+
+{description}
+
+== Before you Begin
+
+include::{templates-url}/microservices/prerequisites.adoc[]
+
+In order to run the code sample, make sure to have PostgresSQL database accessible and configured properly in the `application.properties` file.
+
+[TIP]
+====
+You can spin-up a PostgreSQL instance easily using Docker:
+----
+docker run --name 2lc-postgres --publish 5432:5432 -e POSTGRES_PASSWORD=mysecretpassword -d postgres:13
+----
+====
+
+== Configuration
+
+In order to enable JPA, you need to add a dedicated Spring Boot Starter:
+
+[source,xml,indent=0]
+----
+include::ROOT:example$springboot-hibernate/pom.xml[tag=spring-boot-starter]
+----
+
+In order to configure Hazelcast as a second-level cache provider, you need to add two dependencies:
+
+[source,xml,indent=0]
+----
+include::ROOT:example$springboot-hibernate/pom.xml[tags=hazelcast-hibernate;hazelcast-dep]
+----
+
+And then, you need to configure the Hazelcast member setting by adding a standard `hazelcast.xml` file into `src/main/resources` directory.
+
+Keep in mind that this might trigger the autoconfiguration of another Hazelcast member so you might want to disable Hazelcast autoconfiguration:
+
+[source,java,indent=0]
+----
+include::ROOT:example$springboot-hibernate/src/main/java/com/hazelcast/hibernate/springhibernate2lc/SpringHibernate2lcApplication.java[tag=doc-exclude]
+----
+
+The last step involves turning on second-level cache by adding two properties in the `application.properties` file:
+
+[source,properties]
+----
+include::ROOT:example$springboot-hibernate/src/main/resources/application.properties[tag=doc-second-level]
+----
+
+And now, after you annotate your entity as `@Cacheable`, it will be cached in Hazelcast member:
+
+[source,java]
+----
+include::ROOT:example$springboot-hibernate/src/main/java/com/hazelcast/hibernate/springhibernate2lc/persistence/Book.java[tag=doc-cachable]
+----
+
+== Running the Application
+
+Run the application by executing the following command.
+
+----
+mvn spring-boot:run
+----
+
+You should see in logs that Hazelcast members started successfully.
+
+----
+Members {size:1, ver:1} [
+        Member [172.21.28.181]:5701 - f3984396-0ec9-40c8-861e-cb34f14d7204 this
+]
+----
+
+What happens then is that an object is saved to the database and then fetched. In the meantime, the object is stored in the second level cache. `SecondLevelCacheVisualizer` prints out the L2C content in every 10 seconds. 
+
+----
+20:56:46.937644
+size: 1
+    com.hazelcast.hibernate.springhibernate2lc.persistence.Book#1:read-write Item(CacheEntry(com.hazelcast.hibernate.springhibernate2lc.persistence.Book))
+
+20:56:56.997365
+size: 1
+    com.hazelcast.hibernate.springhibernate2lc.persistence.Book#1:read-write Item(CacheEntry(com.hazelcast.hibernate.springhibernate2lc.persistence.Book))
+----
+
+The object is then evicted from the L2C after 30 seconds, which is the configured time-to-live in `hazelcast.xml`.
+
+----
+20:57:17.028600
+size: 0
+----
+
+== Summary
+
+In this guide, you bootstrapped a Spring Boot application to use Hazelcast as a Hibernate second-level cache.
+
diff --git a/pom.xml b/pom.xml
@@ -31,10 +31,12 @@
     </build>
 
 	<dependencies>
+		<!-- tag::spring-boot-starter[] -->
 		<dependency>
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter-data-jpa</artifactId>
 		</dependency>
+		<!-- end::spring-boot-starter[] -->
 
 		<dependency>
 			<groupId>org.springframework.boot</groupId>
@@ -47,18 +49,20 @@
 				</exclusion>
 			</exclusions>
 		</dependency>
-
+		<!-- tag::hazelcast-hibernate[] -->
 		<dependency>
 			<groupId>com.hazelcast</groupId>
 			<artifactId>hazelcast-hibernate53</artifactId>
 			<version>${hazelcast-hibernate.version}</version>
 		</dependency>
-
+		<!-- end::hazelcast-hibernate[] -->
+		<!-- tag::hazelcast-dep[] -->
 		<dependency>
 			<groupId>com.hazelcast</groupId>
 			<artifactId>hazelcast</artifactId>
 			<version>${hazelcast.version}</version>
 		</dependency>
+		<!-- end::hazelcast-dep[] -->
 
 		<dependency>
 			<groupId>org.postgresql</groupId>
diff --git a/src/main/java/com/hazelcast/hibernate/springhibernate2lc/SpringHibernate2lcApplication.java b/src/main/java/com/hazelcast/hibernate/springhibernate2lc/SpringHibernate2lcApplication.java
@@ -6,7 +6,10 @@
 import org.springframework.scheduling.annotation.EnableScheduling;
 
 @EnableScheduling // needed just for the sake of SecondLevelCacheVisualizer
-@SpringBootApplication(exclude = HazelcastAutoConfiguration.class) // in order to avoid autoconfiguring an extra Hazelcast instance
+// in order to avoid autoconfiguring an extra Hazelcast instance
+// tag::doc-exclude[]
+@SpringBootApplication(exclude = HazelcastAutoConfiguration.class)
+// end::doc-exclude[]
 public class SpringHibernate2lcApplication {
 
     public static void main(String[] args) {
diff --git a/src/main/java/com/hazelcast/hibernate/springhibernate2lc/persistence/Book.java b/src/main/java/com/hazelcast/hibernate/springhibernate2lc/persistence/Book.java
@@ -7,9 +7,11 @@
 import javax.persistence.GeneratedValue;
 import javax.persistence.Id;
 
+// tag::doc-cachable[]
 @Entity
 @Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
 public class Book {
+// end::doc-cachable[]
 
     @Id
     @GeneratedValue
diff --git a/src/main/resources/application.properties b/src/main/resources/application.properties
@@ -10,8 +10,10 @@ spring.jpa.hibernate.ddl-auto=create-drop
 spring.jpa.properties.hibernate.show_sql=true
 
 # Second-Level Cache Configuration
+# tag::doc-second-level[]
 spring.jpa.properties.hibernate.cache.use_second_level_cache=true
 spring.jpa.properties.hibernate.cache.region.factory_class=com.hazelcast.hibernate.HazelcastCacheRegionFactory
+# end::doc-second-level[]
 # spring.jpa.properties.hibernate.cache.hazelcast.use_native_client=true
 
 logging.level.org.hibernate.type=trace

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+See the link:https://docs.hazelcast.com/tutorials/springboot-hibernate[tutorial].`