You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@freemarker.apache.org by dd...@apache.org on 2018/04/18 18:41:18 UTC
freemarker git commit: Improved the JavaDocs of CustomStateScope
related API-s
Repository: freemarker
Updated Branches:
refs/heads/3 ef409c2be -> 976ce3ac1
Improved the JavaDocs of CustomStateScope related API-s
Project: http://git-wip-us.apache.org/repos/asf/freemarker/repo
Commit: http://git-wip-us.apache.org/repos/asf/freemarker/commit/976ce3ac
Tree: http://git-wip-us.apache.org/repos/asf/freemarker/tree/976ce3ac
Diff: http://git-wip-us.apache.org/repos/asf/freemarker/diff/976ce3ac
Branch: refs/heads/3
Commit: 976ce3ac176341a6afb6559948812cea0efea4d3
Parents: ef409c2
Author: ddekany <dd...@apache.org>
Authored: Wed Apr 18 20:40:56 2018 +0200
Committer: ddekany <dd...@apache.org>
Committed: Wed Apr 18 20:40:56 2018 +0200
----------------------------------------------------------------------
.../apache/freemarker/core/CustomStateKey.java | 43 ++++++++++++++++----
.../freemarker/core/CustomStateScope.java | 4 ++
2 files changed, 38 insertions(+), 9 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/freemarker/blob/976ce3ac/freemarker-core/src/main/java/org/apache/freemarker/core/CustomStateKey.java
----------------------------------------------------------------------
diff --git a/freemarker-core/src/main/java/org/apache/freemarker/core/CustomStateKey.java b/freemarker-core/src/main/java/org/apache/freemarker/core/CustomStateKey.java
index fedf096..9abeff5 100644
--- a/freemarker-core/src/main/java/org/apache/freemarker/core/CustomStateKey.java
+++ b/freemarker-core/src/main/java/org/apache/freemarker/core/CustomStateKey.java
@@ -20,24 +20,49 @@
package org.apache.freemarker.core;
/**
- * Used with {@link CustomStateScope}-s; each subclass must have exactly one instance, which should be stored in
- * a static final field. So the usual usage is like this:
+ * Used with {@link CustomStateScope}-s; each subclass must have exactly one instance, which should be stored in a
+ * static final field. So the usual usage is like this:
*
* <pre>
- * static final CustomStateKey MY_STATE = new CustomStateKey() {
- * @Override
- * protected Object create() {
- * return new ...;
- * }
- * };
+ * static final CustomStateKey<FooState> FOO_STATE_KEY = new CustomStateKey<>() {
+ * @Override
+ * protected Object create() {
+ * return new FooState();
+ * }
+ * };
* </pre>
+ *
+ * <p>
+ * And then later somewhere (if it's {@link Environment} scoped):
+ *
+ * <pre>
+ * FooState fooState = env.getCustomState(FOO_STATE_KEY);
+ * // Use FooState API from here on:
+ * int x = fooState.getX();
+ * int y = fooState.getY();
+ * fooState.setX(0)
+ * </pre>
+ *
+ * <p>
+ * Note that above we haven't defined multiple keys for each value we need ({@code x} and {@code y}), instead we
+ * have defined a container class ({@code FooState}) that contains all the values we need, and we just get that
+ * single container object, and then use its API ({@code getX()}, {@code setX(int)}, etc. above).
+ *
+ * @param <T>
+ * The type of the object returned for this key (initially created by {@link #create()}).
+ *
*/
public abstract class CustomStateKey<T> {
/**
* This will be invoked when the state for this {@link CustomStateKey} is get via {@link
- * CustomStateScope#getCustomState(CustomStateKey)}, but it doesn't yet exists in the given scope. Then the created
+ * CustomStateScope#getCustomState(CustomStateKey)} for the first time in a scope. Then the created
* object will be stored in the scope and then it's returned. Must not return {@code null}.
+ *
+ * <p>In case you wonder how to initialize the contents of the newly created object, because you should use some
+ * values that aren't available inside the method, you shouldn't do such initialization in this method. Rather,
+ * the code that is responsible for such initialization should call
+ * {@link CustomStateScope#getCustomState(CustomStateKey)} and set up the returned object through its API.
*/
protected abstract T create();
http://git-wip-us.apache.org/repos/asf/freemarker/blob/976ce3ac/freemarker-core/src/main/java/org/apache/freemarker/core/CustomStateScope.java
----------------------------------------------------------------------
diff --git a/freemarker-core/src/main/java/org/apache/freemarker/core/CustomStateScope.java b/freemarker-core/src/main/java/org/apache/freemarker/core/CustomStateScope.java
index 4067823..d1c9041 100644
--- a/freemarker-core/src/main/java/org/apache/freemarker/core/CustomStateScope.java
+++ b/freemarker-core/src/main/java/org/apache/freemarker/core/CustomStateScope.java
@@ -28,6 +28,10 @@ public interface CustomStateScope {
* Gets the custom state belonging to the key, automatically creating it if it doesn't yet exists in the scope.
* If the scope is {@link Configuration} or {@link Template}, then this method is thread safe. If the scope is
* {@link Environment}, then this method is not thread safe ({@link Environment} is not thread safe either).
+ *
+ * <p>There's no {@code setCustomState} method; the code that wants to initialize the state object should call
+ * {@link CustomStateScope#getCustomState(CustomStateKey)} to receive the instance, then set up the returned object
+ * through its API.
*/
<T> T getCustomState(CustomStateKey<T> customStateKey);