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 <[email protected]> Authored: Wed Apr 18 20:40:56 2018 +0200 Committer: ddekany <[email protected]> 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);
