Skip to content

Commit

Permalink
Restructure content to include partials from Commons.
Browse files Browse the repository at this point in the history
See #3080
  • Loading branch information
mp911de committed Aug 23, 2023
1 parent 016be28 commit b47a340
Show file tree
Hide file tree
Showing 30 changed files with 304 additions and 260 deletions.
26 changes: 13 additions & 13 deletions spring-data-jpa-distribution/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -37,24 +37,24 @@
<artifactId>maven-assembly-plugin</artifactId>
</plugin>

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>resources</goal>
</goals>
</execution>
</executions>

</plugin>

<plugin>
<groupId>io.spring.maven.antora</groupId>
<artifactId>antora-maven-plugin</artifactId>
</plugin>
</plugins>
</build>

<profiles>

<profile>
<id>antora</id>
<build>
<plugins>

</plugins>
</build>
</profile>

</profiles>

</project>
5 changes: 5 additions & 0 deletions src/main/antora/antora-playbook.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,11 @@ content:
branches: HEAD
start_path: src/main/antora
worktrees: true
- url: https://github.com/spring-projects/spring-data-commons
# Refname matching:
# https://docs.antora.org/antora/latest/playbook/content-refname-matching/
branches: [main, 3.2.x]
start_path: src/main/antora
asciidoc:
attributes:
page-pagination: ''
Expand Down
27 changes: 22 additions & 5 deletions src/main/antora/modules/ROOT/nav.adoc
Original file line number Diff line number Diff line change
@@ -1,17 +1,34 @@
* xref:index.adoc[Overview]
** xref:commons/upgrade.adoc[]
* xref:repositories/introduction.adoc[]
** xref:repositories/core-concepts.adoc[]
** xref:repositories/definition.adoc[]
** xref:repositories/create-instances.adoc[]
** xref:repositories/query-methods-details.adoc[]
** xref:repositories/projections.adoc[]
** xref:repositories/custom-implementations.adoc[]
** xref:repositories/core-domain-events.adoc[]
** xref:repositories/core-extensions.adoc[]
** xref:repositories/null-handling.adoc[]
** xref:repositories/query-keywords-reference.adoc[]
** xref:repositories/query-return-types-reference.adoc[]
* xref:jpa.adoc[]
** xref:jpa/introduction.adoc[]
** xref:jpa/configuration.adoc[]
** xref:jpa/entity-persistence.adoc[]
** xref:jpa/query-methods.adoc[]
** xref:jpa/stored-procedures.adoc[]
** xref:jpa/specifications.adoc[]
** xref:jpa/query-by-example.adoc[]
** xref:query-by-example.adoc[]
** xref:jpa/transactions.adoc[]
** xref:jpa/locking.adoc[]
** xref:jpa/auditing.adoc[]
** xref:auditing.adoc[]
** xref:jpa/misc-context.adoc[]
** xref:jpa/misc-merging-persistence-units.adoc[]
** xref:jpa/jpd-misc-cdi-integration.adoc[]
** xref:jpa/faq.adoc[]
** xref:jpa/glossary.adoc[]
* xref:envers.adoc[]
* xref:faq.adoc[]
* xref:glossary.adoc[]
** xref:envers/introduction.adoc[]
** xref:envers/configuration.adoc[]
** xref:envers/usage.adoc[]
* https://github.com/spring-projects/spring-data-commons/wiki[Wiki]
Original file line number Diff line number Diff line change
@@ -1,8 +1,4 @@
[[jpa.auditing]]
= JPA Auditing

Spring Data JPA provides auditing based upon the foundation provided by {spring-data-commons-docs-url}/auditing.html[Spring Data Common's Auditing support].

include::{commons}@data-commons::page$auditing.adoc[]

There is also a convenience base class, `AbstractAuditable`, which you can extend to avoid the need to manually implement the interface methods. Doing so increases the coupling of your domain classes to Spring Data, which might be something you want to avoid. Usually, the annotation-based way of defining auditing metadata is preferred as it is less invasive and more flexible.

Expand Down
1 change: 1 addition & 0 deletions src/main/antora/modules/ROOT/pages/commons/upgrade.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
include::{commons}@data-commons::page$upgrade.adoc[]
205 changes: 3 additions & 202 deletions src/main/antora/modules/ROOT/pages/envers.adoc
Original file line number Diff line number Diff line change
@@ -1,204 +1,5 @@
[[envers]]
= Spring Data Envers
= Envers
:page-section-summary-toc: 1

[[envers.what.is.spring.data]]
== What is Spring Data Envers?

Spring Data Envers makes typical Envers queries available in repositories for Spring Data JPA.
It differs from other Spring Data modules in that it is always used in combination with another Spring Data Module: Spring Data JPA.

[[envers.what]]
== What is Envers?

Envers is a https://hibernate.org/orm/envers/[Hibernate module] that adds auditing capabilities to JPA entities.
This documentation assumes you are familiar with Envers, just as Spring Data Envers relies on Envers being properly configured.

[[envers.configuration]]
== Configuration

As a starting point for using Spring Data Envers, you need a project with Spring Data JPA on the classpath and an additional `spring-data-envers` dependency:

====
[source,xml,subs="+attributes"]
----
<dependencies>
<!-- other dependency elements omitted -->
<dependency>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-envers</artifactId>
<version>{version}</version>
</dependency>
</dependencies>
----
====

This also brings `hibernate-envers` into the project as a transient dependency.

To enable Spring Data Envers and Spring Data JPA, we need to configure two beans and a special `repositoryFactoryBeanClass`:

====
[source,java]
----
@Configuration
@EnableEnversRepositories
@EnableTransactionManagement
public class EnversDemoConfiguration {
@Bean
public DataSource dataSource() {
EmbeddedDatabaseBuilder builder = new EmbeddedDatabaseBuilder();
return builder.setType(EmbeddedDatabaseType.HSQL).build();
}
@Bean
public LocalContainerEntityManagerFactoryBean entityManagerFactory() {
HibernateJpaVendorAdapter vendorAdapter = new HibernateJpaVendorAdapter();
vendorAdapter.setGenerateDdl(true);
LocalContainerEntityManagerFactoryBean factory = new LocalContainerEntityManagerFactoryBean();
factory.setJpaVendorAdapter(vendorAdapter);
factory.setPackagesToScan("example.springdata.jpa.envers");
factory.setDataSource(dataSource());
return factory;
}
@Bean
public PlatformTransactionManager transactionManager(EntityManagerFactory entityManagerFactory) {
JpaTransactionManager txManager = new JpaTransactionManager();
txManager.setEntityManagerFactory(entityManagerFactory);
return txManager;
}
}
----
====

To actually use Spring Data Envers, make one or more repositories into a {spring-data-commons-javadoc-base}/org/springframework/data/repository/history/RevisionRepository.html[`RevisionRepository`] by adding it as an extended interface:

====
[source,java]
----
interface PersonRepository
extends CrudRepository<Person, Long>,
RevisionRepository<Person, Long, Long> // <1>
{}
----
<1> The first type parameter (`Person`) denotes the entity type, the second (`Long`) denotes the type of the id property, and the last one (`Long`) is the type of the revision number.
For Envers in default configuration, the revision number parameter should be `Integer` or `Long`.
====

The entity for that repository must be an entity with Envers auditing enabled (that is, it must have an `@Audited` annotation):

====
[source,java]
----
@Entity
@Audited
class Person {
@Id @GeneratedValue
Long id;
String name;
@Version Long version;
}
----
====

[[envers.usage]]
== Usage

You can now use the methods from `RevisionRepository` to query the revisions of the entity, as the following test case shows:

====
[source,java]
----
@ExtendWith(SpringExtension.class)
@Import(EnversDemoConfiguration.class) // <1>
class EnversIntegrationTests {
final PersonRepository repository;
final TransactionTemplate tx;
EnversIntegrationTests(@Autowired PersonRepository repository, @Autowired PlatformTransactionManager tm) {
this.repository = repository;
this.tx = new TransactionTemplate(tm);
}
@Test
void testRepository() {
Person updated = preparePersonHistory();
Revisions<Long, Person> revisions = repository.findRevisions(updated.id);
Iterator<Revision<Long, Person>> revisionIterator = revisions.iterator();
checkNextRevision(revisionIterator, "John", RevisionType.INSERT);
checkNextRevision(revisionIterator, "Jonny", RevisionType.UPDATE);
checkNextRevision(revisionIterator, null, RevisionType.DELETE);
assertThat(revisionIterator.hasNext()).isFalse();
}
/**
* Checks that the next element in the iterator is a Revision entry referencing a Person
* with the given name after whatever change brought that Revision into existence.
* <p>
* As a side effect the Iterator gets advanced by one element.
*
* @param revisionIterator the iterator to be tested.
* @param name the expected name of the Person referenced by the Revision.
* @param revisionType the type of the revision denoting if it represents an insert, update or delete.
*/
private void checkNextRevision(Iterator<Revision<Long, Person>> revisionIterator, String name,
RevisionType revisionType) {
assertThat(revisionIterator.hasNext()).isTrue();
Revision<Long, Person> revision = revisionIterator.next();
assertThat(revision.getEntity().name).isEqualTo(name);
assertThat(revision.getMetadata().getRevisionType()).isEqualTo(revisionType);
}
/**
* Creates a Person with a couple of changes so it has a non-trivial revision history.
* @return the created Person.
*/
private Person preparePersonHistory() {
Person john = new Person();
john.setName("John");
// create
Person saved = tx.execute(__ -> repository.save(john));
assertThat(saved).isNotNull();
saved.setName("Jonny");
// update
Person updated = tx.execute(__ -> repository.save(saved));
assertThat(updated).isNotNull();
// delete
tx.executeWithoutResult(__ -> repository.delete(updated));
return updated;
}
}
----
<1> This references the application context configuration presented earlier (in the xref:envers.adoc#envers.configuration[Configuration] section).
====

[[envers.resources]]
== Further Resources

You can download the https://github.com/spring-projects/spring-data-examples[Spring Data Envers example in the Spring Data Examples repository] and play around with to get a feel for how the library works.

You should also check out the {spring-data-commons-javadoc-base}/org/springframework/data/repository/history/RevisionRepository.html[Javadoc for `RevisionRepository`] and related classes.

You can ask questions at https://stackoverflow.com/questions/tagged/spring-data-envers[Stackoverflow by using the `spring-data-envers` tag].

The https://github.com/spring-projects/spring-data-jpa[source code and issue tracker for Spring Data Envers is hosted at GitHub] (as a module of Spring Data JPA).
This chapter points out the specialties for repository support for Envers. This builds on the core repository support explained earlier. Make sure you have a sound understanding of the basic concepts explained there.
Loading

0 comments on commit b47a340

Please sign in to comment.