<commit_before>= Ehcache 3 developer wiki

:toc:

== Developer, be welcome!

This wiki contains all design documents and other related material to doing development on Ehcache, not _using_ Ehcache! If you are a developer that wants to get involved in developing new features, fixing bugs, extend the existing or implement a new module based on the Ehcache3 SPIs, this is the place you've been looking for. Be welcome!

== How to contribute?

=== Process

On paper (or on this screen), it's pretty straight forward:

 . Join the https://groups.google.com/forum/#!forum/ehcache-dev[developer mailing list] and say hello!
 . Check the https://github.com/ehcache/ehcache3/issues[issues] and verify what you want isn't yet planned or could even already being worked on by someone; We're also using a board on https://waffle.io/ehcache/ehcache3[waffle.io], where work for the current milestone is prioritized;
 . If the task exists already and isn't assigned: drop us an email on the https://groups.google.com/forum/#!forum/ehcache-dev[developer mailing list] about it and we'll make sure we help you getting started and we'll assign the task/issue to you;
 . If nothing matches in the existing issue list, create a bug as such; or, if we're talking about a larger task or feature, https://groups.google.com/forum/#!forum/ehcache-dev[drop us a message] first, and we'll see how to tackle it;
 . https://github.com/ehcache/ehcache3/fork[Fork] the project to your own repository and get started (you probably want to work on a dedicated branch);
 . Rebase your fork and do a pull request. We'll use that to code review it (see link:dev.git[git usage page] as well as the link:dev.guidelines[developer guidelines])
 . Be rich and famous!

Now, the doing the work part might be a little more challenging, and we don't provide any guarantees as to becoming rich... but you'll be famous to us!

=== Contributor agreement

In order to accept any contribution, we will need you to fill out and mail https://confluence.terracotta.org/download/attachments/27918462/Terracotta%20Individual%20Contributor%20Agreement%20v3.pdf?version=1&modificationDate=1393442245216&api=v2[the Individual Contributor Agreement] at <EMAIL>.

=== Code layout

The code core of Ehcache is split in three core modules:

 . the link:module.api[API module], which contains mainly interfaces. They are the core API to Ehcache (e.g. +Cache+, +CacheManager+) that users depend on. It also contains the entry points in terms of SPI (e.g. +Service+, +Store+, +AuthoritativeTier+ & +CachingTier+), that are used by other modules that in turn provide their implementations;
 . the link:module.core[Core module], that is composed of the plumbery that wires the API used by users with the SPI implementations present in packaged modules; and
 . the link:module.impl[Implementation module], containing the default implementation of +Cache+ and +CacheManager+, as well as implementations of core SPIs, such as +HeapResource+ that lets you create on-heap +Cache+ and +CachingTier+ instances.

== Fundamental concepts

=== Modular approach

+org.ehcache.spi.service.ServiceFactory+ are used to create +org.ehcache.spi.service.Service+, configured through +org.ehcache.spi.service.ServiceConfiguration+. Each of those services can be about anything.

A special kind of +Service+ is the +org.ehcache.spi.cache.CacheProvider+, which is used by the +CacheManager+ to create all caches.

=== Configuration

+org.ehcache.config.CacheConfiguration+, +org.ehcache.spi.service.ServiceConfiguration+, +org.ehcache.config.xml.XmlConfigurationParser+

NOTE: For more information on how the configuration is parsed, resolved and services are then bootstrapped, please read the link:design.bootstrapping#configuration[Bootstrapping design doc].

== How to extend?

=== SPIs
+org.ehcache.spi.service+, +org.ehcache.spi.cache+

=== Extension points<commit_msg>Architecture details<commit_after>= Ehcache 3 developer wiki

:toc:

== Developer, be welcome!

This wiki contains all design documents and other related material to doing development on Ehcache, not _using_ Ehcache! If you are a developer that wants to get involved in developing new features, fixing bugs, extend the existing or implement a new module based on the Ehcache3 SPIs, this is the place you've been looking for. Be welcome!

== How to contribute?

=== Process

On paper (or on this screen), it's pretty straight forward:

 . Join the https://groups.google.com/forum/#!forum/ehcache-dev[developer mailing list] and say hello!
 . Check the https://github.com/ehcache/ehcache3/issues[issues] and verify what you want isn't yet planned or could even already being worked on by someone; We're also using a board on https://waffle.io/ehcache/ehcache3[waffle.io], where work for the current milestone is prioritized;
 . If the task exists already and isn't assigned: drop us an email on the https://groups.google.com/forum/#!forum/ehcache-dev[developer mailing list] about it and we'll make sure we help you getting started and we'll assign the task/issue to you;
 . If nothing matches in the existing issue list, create a bug as such; or, if we're talking about a larger task or feature, https://groups.google.com/forum/#!forum/ehcache-dev[drop us a message] first, and we'll see how to tackle it;
 . https://github.com/ehcache/ehcache3/fork[Fork] the project to your own repository and get started (you probably want to work on a dedicated branch);
 . Rebase your fork and do a pull request. We'll use that to code review it (see link:dev.git[git usage page] as well as the link:dev.guidelines[developer guidelines])
 . Be rich and famous!

Now, the doing the work part might be a little more challenging, and we don't provide any guarantees as to becoming rich... but you'll be famous to us!

=== Contributor agreement

In order to accept any contribution, we will need you to fill out and mail https://confluence.terracotta.org/download/attachments/27918462/Terracotta%20Individual%20Contributor%20Agreement%20v3.pdf?version=1&modificationDate=1393442245216&api=v2[the Individual Contributor Agreement] at <EMAIL>.

=== Code layout

The code core of Ehcache is split in three core modules:

 . the link:module.api[API module], which contains mainly interfaces. They are the core API to Ehcache (e.g. +Cache+, +CacheManager+) that users depend on. It also contains the entry points in terms of SPI (e.g. +Service+, +Store+, +AuthoritativeTier+ & +CachingTier+), that are used by other modules that in turn provide their implementations;
 . the link:module.core[Core module], that is composed of the plumbery that wires the API used by users with the SPI implementations present in packaged modules; and
 . the link:module.impl[Implementation module], containing the default implementation of +Cache+ and +CacheManager+, as well as implementations of core SPIs, such as +HeapResource+ that lets you create on-heap +Cache+ and +CachingTier+ instances.

== Fundamental concepts

=== Modular approach

==== Services

A `CacheManager` manages `Cache` instances, but also `Service` instances that can be used by either `Cache` or other `Service` instances. An example of `Service` being the `org.ehcache.spi.cache.Store.Provider`, it's the `Service` the `CacheManager` will use to create the `Store` instance underlying your `Cache`.

`Service` are created by using the Java's https://docs.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html[`java.util.ServiceLoader` service-provider loading facility]. It is used to locate all `org.ehcache.spi.service.ServiceFactory` implementations on the classpath. These are in turn used to create `Service` instances. Each `CacheManager` uses its own `org.ehcache.spi.ServiceLocator` facility to locate `Service` instances, which it then in turn life cycles.

`Service` instances are configured by their own respective `ServiceConfiguration` at `Service.start()` invocation time. `CacheManager` and its `Service` instances can then use these services. In the case of the `org.ehcache.spi.cache.Store.Provider` instance, it is being used by the `CacheManager` to create a `Store` to back a `Cache`. Being a direct dependency of `Ehcache`, that `Service` interface is part of the core SPI. It defines a `createStore()` method that will be invoked by the `CacheManager` at `Cache` creation time. The `Store.Provider` implementation can introspect not only the `Store.Configuration` passed, but also all `ServiceConfiguration` instances associated with the `Cache` being created in order to decide what `Store` should be created (note: currently it only creates `OnHeapStore`, as this is the only topology supported... more to come).

=== Configuration

+org.ehcache.config.CacheConfiguration+, +org.ehcache.spi.service.ServiceConfiguration+, +org.ehcache.config.xml.XmlConfigurationParser+

NOTE: For more information on how the configuration is parsed, resolved and services are then bootstrapped, please read the link:design.bootstrapping#configuration[Bootstrapping design doc].

== How to extend?

=== SPIs
+org.ehcache.spi.service+, +org.ehcache.spi.cache+

=== Extension points
{'fraction_non_alphanumeric': 0.08486842105263158, 'fraction_numerical': 0.008223684210526315, 'mean_word_length': 4.9888378200919234, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 15, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7005307', 'n_tokens_mistral': 2542, 'n_tokens_neox': 2373, 'n_words': 1141}