This is an automated email from the ASF dual-hosted git repository.
ntimofeev pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cayenne.git
The following commit(s) were added to refs/heads/master by this push:
new 56d014b83 CAY-2772 Bootique-style module "extenders" for smoother
configuration - update documentation
56d014b83 is described below
commit 56d014b831bb6c69d7e235db598c006f9d567b3b
Author: Nikita Timofeev <stari...@gmail.com>
AuthorDate: Wed Apr 10 11:58:35 2024 +0400
CAY-2772 Bootique-style module "extenders" for smoother configuration
- update documentation
---
.../asciidoc/_cayenne-guide/part2/customize.adoc | 10 ++++----
.../asciidoc/_cayenne-guide/part2/lifecycle.adoc | 16 ++++++------
.../_cayenne-guide/part2/objectContext.adoc | 10 ++++----
.../asciidoc/_cayenne-guide/part2/starting.adoc | 4 +--
.../_cayenne-guide/part4/revEngineering.adoc | 2 +-
.../_cayenne-guide/part5/cacheInvalidation.adoc | 5 ++--
.../asciidoc/_cayenne-guide/part5/commitLog.adoc | 5 ++--
.../docs/asciidoc/_cayenne-guide/part5/crypto.adoc | 30 ++++++++++------------
.../docs/asciidoc/_cayenne-guide/part5/jCache.adoc | 14 +++++-----
9 files changed, 44 insertions(+), 52 deletions(-)
diff --git
a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/customize.adoc
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/customize.adoc
index ee0fd53e4..ab3d5c939 100644
---
a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/customize.adoc
+++
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/customize.adoc
@@ -18,7 +18,7 @@
Cayenne runtime is built around a small powerful dependency injection (DI)
container. Just like other popular DI technologies, such as Spring or Guice,
Cayenne DI container manages sets of interdependent objects and allows users to
configure them. These objects are regular Java objects. We are calling them
"services" in this document to distinguish from all other objects that are not
configured in the container and are not managed. DI container is responsible
for service instantiation, i [...]
-The services are configured in special Java classes called "modules". Each
module defines binding of service interfaces to implementation instances,
implementation types or providers of implementation instances. There are no XML
configuration files, and all the bindings are type-safe. The container supports
injection into instance variables and constructor parameters based on the
@Inject annotation. This mechanism is very close to Google Guice.
+The services are configured in special Java classes called "modules". Each
module defines binding of service interfaces to implementation instances,
implementation types or providers of implementation instances. There are no XML
configuration files, and all the bindings are type-safe. The container supports
injection into instance variables and constructor parameters based on the
`@Inject` annotation. This mechanism is very close to Google Guice.
The discussion later in this chapter demonstrates a standalone DI container.
But keep in mind that Cayenne already has a built-in Injector, and a set of
default modules. A Cayenne user would normally only use the API below to write
custom extension modules that will be loaded in that existing container when
creating CayenneRuntime. See "Starting and Stopping CayenneRuntime" chapter for
an example of passing an extension module to Cayenne.
@@ -250,8 +250,8 @@ public class MyDbAdapterDetector implements
DbAdapterDetector {
[source, Java]
----
-CoreModule.contributeAdapterDetectors(binder)
- .add(MyDbAdapterDetector.class);
+CoreModule.extend(binder)
+ .addAdapterDetector(MyDbAdapterDetector.class);
----
The names of built-in collections are listed in "Appendix B".
@@ -340,8 +340,8 @@ Last step is to register this new type in `CayenneRuntime`:
CayenneRuntime runtime = CayenneRuntime.builder()
.addConfig("cayenne-project.xml")
.addModule(binder ->
- CoreModule.contributeValueObjectTypes(binder)
- .add(MoneyValueObjectType.class))
+ CoreModule.extend(binder)
+ .addValueObjectType(MoneyValueObjectType.class))
.build();
----
diff --git
a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/lifecycle.adoc
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/lifecycle.adoc
index 74f9511b5..7178941ac 100644
---
a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/lifecycle.adoc
+++
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/lifecycle.adoc
@@ -128,14 +128,14 @@ public class Listener2 {
Ignore the annotations for a minute. The important point here is that the
listeners are arbitrary classes unmapped and unknown to Cayenne, that contain
some callback methods. Now let's register them with runtime:
-[source, Java]
+[source,Java]
----
CayenneRuntime runtime = CayenneRuntime.builder()
// ..
.addModule(binder ->
- CoreModule.contributeDomainListeners()
- .add(Listener1.class)
- .add(new Listener2())
+ CoreModule.extend(bidner)
+ .addListener(Listener1.class)
+ .addListener(new Listener2())
)
// ..
.build();
@@ -152,7 +152,7 @@ Now let's discuss the annotations. There are eight
annotations exactly matching
// belonging to MyEntity1, MyEntity2 or their subclasses
@PostRemove({ MyEntity1.class, MyEntity2.class })
void postRemove(Persistent object) {
- ...
+ // ...
}
----
@@ -164,7 +164,7 @@ void postRemove(Persistent object) {
@PostRemove(MyEntity1.class)
@PostUpdate(MyEntity1.class)
void postCommit(MyEntity1 object) {
- ...
+ // ...
}
----
@@ -257,8 +257,8 @@ Now since this is both a filter and a listener, it needs to
be registered as suc
CayenneRuntime runtime = CayenneRuntime.builder()
// ..
.addModule(b ->
- CoreModule.contributeDomainSyncFilters(b)
- .add(CommittedObjectCounter.class)
+ CoreModule.extend(b)
+ .addSyncFilter(CommittedObjectCounter.class)
)
// ..
.build();
diff --git
a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/objectContext.adoc
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/objectContext.adoc
index 2fe46fa8d..8e85c47e0 100644
---
a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/objectContext.adoc
+++
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/objectContext.adoc
@@ -296,9 +296,9 @@ You can control transaction isolation level and propagation
logic using `Transac
[source, java]
----
-TransactionDescriptor descriptor = new TransactionDescriptor(
- Connection.TRANSACTION_SERIALIZABLE,
- TransactionPropagation.REQUIRES_NEW
- );
-transactionManager.performInTransaction(transactionalOperation, descriptor);
+TransactionDescriptor descriptor = TransactionDescriptor.builder()
+ .isolation(Connection.TRANSACTION_SERIALIZABLE)
+ .propagation(TransactionPropagation.REQUIRES_NEW)
+ .build();
+runtime.performInTransaction(transactionalOperation, descriptor);
----
diff --git
a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/starting.adoc
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/starting.adoc
index bc546dbde..6b3c0c4c1 100644
---
a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/starting.adoc
+++
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/starting.adoc
@@ -32,8 +32,8 @@ CayenneRuntime encapsulates a single Cayenne stack. Most
applications will just
[source, java]
----
Module extensions = binder ->
- CoreModule.contributeProperties(binder)
- .put(Constants.EXTERNAL_TX_PROPERTY, "true");
+ CoreModule.extend(binder).setProperty(Constants.EXTERNAL_TX_PROPERTY,
"true");
+
CayenneRuntime runtime = CayenneRuntime.builder()
.addConfig("com/example/cayenne-project.xml")
.addModule(extensions)
diff --git
a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/revEngineering.adoc
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/revEngineering.adoc
index 95ac54b38..153bba400 100644
---
a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/revEngineering.adoc
+++
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part4/revEngineering.adoc
@@ -15,7 +15,7 @@
[[re-modeler]]
=== Reverse Engineering in Cayenne Modeler
-Alternative approach to using <<cdbimport>> is doing reverse engineering from
<<CayenneModeler Application, CayenneModeler>>.
+Alternative approach to using <<re-introduction,build tools>> is doing reverse
engineering from <<CayenneModeler Application, CayenneModeler>>.
You can find reverse engineering tool in dataMap view on *DbImport Tab*.
diff --git
a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cacheInvalidation.adoc
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cacheInvalidation.adoc
index 5281f2541..c2c66cd59 100644
---
a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cacheInvalidation.adoc
+++
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/cacheInvalidation.adoc
@@ -75,11 +75,10 @@ Now we'll set up it's usage by `CayenneRuntime`:
[source, java]
----
CayenneRuntime.builder()
- .addModule(CacheInvalidationModule.extend()
+ .addModule(binder -> CacheInvalidationModule.extend(binder)
// optionally you can disable @CacheGroups annotation
processing
.noCacheGroupsHandler()
- .addHandler(CustomInvalidationHandler.class)
- .module())
+ .addHandler(CustomInvalidationHandler.class))
----
NOTE: You can combine as many invalidation handlers as you need.
diff --git
a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/commitLog.adoc
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/commitLog.adoc
index 7e6717fba..0e89f4efd 100644
---
a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/commitLog.adoc
+++
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/commitLog.adoc
@@ -73,9 +73,8 @@ public class MyCommitLogListener implements CommitLogListener
{
[source, java]
----
CayenneRuntime.builder()
- .addModule(CommitLogModule.extend()
- .addListener(MyCommitLogListener.class)
- .module())
+ .addModule(binder -> CommitLogModule.extend(binder)
+ .addListener(MyCommitLogListener.class))
----
+
NOTE: You can use several listeners, but they all will get same changes.
diff --git
a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/crypto.adoc
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/crypto.adoc
index b589e8741..ad6242364 100644
---
a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/crypto.adoc
+++
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/crypto.adoc
@@ -56,10 +56,9 @@ strategy by injecting you own implementation of
`o.a.c.crypto.map.ColumnMapper`
[source, java]
----
-CayenneRuntime.builder()
- .addModule(CryptoModule.extend()
- .columnMapper(MyColumnMapper.class)
- .module())
+CayenneRuntime runtime = CayenneRuntime.builder()
+ .addModule(binder -> CryptoModule.extend(binder)
+ .columnMapper(MyColumnMapper.class));
----
Here is an example of how `ObjEntity` with two encrypted and two unencrypted
properties can look like:
@@ -73,24 +72,22 @@ KeyStore.
[source, java]
----
-CayenneRuntime.builder()
- .addModule(CryptoModule.extend()
- .keyStore(this.getClass().getResource("keystore.jcek"),
"my-password".toCharArray(), "my-key-alias")
- .module())
+CayenneRuntime runtime = CayenneRuntime.builder()
+ .addModule(binder -> CryptoModule.extend(binder)
+ .keyStore(this.getClass().getResource("keystore.jcek"),
"my-password".toCharArray(), "my-key-alias"));
----
===== Additional settings
-Additionally to `ColumnMapper` mentioned above you can customize other parts
of `crypto module`. You can enable `gzip`
+In addition to `ColumnMapper` mentioned above you can customize other parts of
`crypto module`. You can enable `gzip`
compression and `HMAC` usage (later will ensure integrity of data).
[source, java]
----
-CayenneRuntime.builder()
- .addModule(CryptoModule.extend()
+CayenneRuntime runtime = CayenneRuntime.builder()
+ .addModule(binder -> CryptoModule.extend(binder)
.compress()
- .useHMAC()
- .module())
+ .useHMAC());
----
Another useful extension point is support for custom Java value types. To add
support for your data type you need to
@@ -98,10 +95,9 @@ implement `o.a.c.crypto.transformer.value.BytesConverter`
interface that will co
[source, java]
----
-CayenneRuntime.builder()
- .addModule(CryptoModule.extend()
- .objectToBytesConverter(MyClass.class, new
MyClassBytesConverter())
- .module())
+CayenneRuntime runtime = CayenneRuntime.builder()
+ .addModule(binder -> CryptoModule.extend(binder)
+ .objectToBytesConverter(MyClass.class, new
MyClassBytesConverter()));
----
NOTE: In addition to Java primitive types (and their object counterparts),
`crypto module` supports encryption only
diff --git
a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jCache.adoc
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jCache.adoc
index 0417aaa00..78363789c 100644
---
a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jCache.adoc
+++
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part5/jCache.adoc
@@ -46,10 +46,9 @@ For advanced configuration and management please use
provider specific options a
JCache module supports custom configuration files for cache managers.
[source, java]
----
-CayenneRuntime.builder()
- .addModule(binder ->
- JCacheModule
- .contributeJCacheProviderConfig(binder,
"cache-config.xml"));
+CayenneRuntime runtime = CayenneRuntime.builder()
+ .addModule(binder -> JCacheModule.extend(binder)
+ .setJCacheProviderConfig("cache-config.xml"));
----
Also JCache module supports contribution of pre-configured cache manager.
@@ -82,10 +81,9 @@ If you need custom configuration you can contribute
configuration file to JCache
[source, java]
----
-CayenneRuntime.builder()
- .addModule(binder ->
- JCacheModule
- .contributeJCacheProviderConfig(binder,
"file:/ehcache.xml"));
+CayenneRuntime runtime = CayenneRuntime.builder()
+ .addModule(binder -> JCacheModule.extend(binder)
+ .setJCacheProviderConfig("file:/ehcache.xml"));
----
As a result you will have `ehcache` manager as your default cache manager.
\ No newline at end of file
