001: /*
002: * Copyright 2001-2007 Geert Bevin <gbevin[remove] at uwyn dot com>
003: * Distributed under the terms of either:
004: * - the common development and distribution license (CDDL), v1.0; or
005: * - the GNU Lesser General Public License, v2.1 or later
006: * $Id: ContinuationConfigRuntime.java 3810 2007-06-25 13:36:58Z gbevin $
007: */
008: package com.uwyn.rife.continuations;
009:
010: import com.uwyn.rife.continuations.exceptions.MissingActiveContinuationConfigRuntimeException;
011:
012: /**
013: * Configures the runtime behavior of the continuations engine.
014: * <p>The active runtime configuration always has to be available through
015: * {@link #getActiveConfigRuntime()} when a {@link ContinuableObject} is
016: * executed. Therefore, it's best to always call
017: * {@link #setActiveConfigRuntime} before the executing. The
018: * {@link com.uwyn.rife.continuations.basic.BasicContinuableRunner} does
019: * this by default. If you create your own runner, you have to ensure that
020: * this is respected.
021: * <p>By default the lifetime duration and purging of {@link ContinuableObject}
022: * instances is set to a sensible default, so this only needs tuning in
023: * specific case.
024: * <p>This class has to be extended though to provide information that suits
025: * your continuations usage and to indicate whether continuations should be
026: * cloned when they are resumed.
027: *
028: * @author Geert Bevin (gbevin[remove] at uwyn dot com)
029: * @version $Revision: 3810 $
030: * @since 1.6
031: */
032: public abstract class ContinuationConfigRuntime<T extends ContinuableObject> {
033: /**
034: * The default duration is 20 minutes.
035: * @since 1.6
036: */
037: public static final long DEFAULT_CONTINUATION_DURATION = 1200000;
038:
039: /**
040: * The default frequency is every 20 times out of the scale, with the
041: * default scale of 1000 this means, 1/50th of the time.
042: * @since 1.6
043: */
044: public static final int DEFAULT_CONTINUATION_PURGE_FREQUENCY = 20;
045:
046: /**
047: * The default purge scale is 1000.
048: * @since 1.6
049: */
050: public static final int DEFAULT_CONTINUATION_PURGE_SCALE = 1000;
051:
052: private static transient ThreadLocal<ContinuationConfigRuntime> sActiveConfigRuntime = new ThreadLocal<ContinuationConfigRuntime>();
053:
054: /**
055: * Sets the active runtime configuration for the executing thread.
056: *
057: * @param config the active runtime configuration for the executing thread
058: * @since 1.6
059: */
060: public static void setActiveConfigRuntime(
061: ContinuationConfigRuntime config) {
062: sActiveConfigRuntime.set(config);
063: }
064:
065: /**
066: * Retrieves the active runtime configuration for the executing thread.
067: *
068: * @return the active runtime configuration
069: * @throws MissingActiveContinuationConfigRuntimeException when the active
070: * runtime configuration isn't set
071: * @since 1.6
072: */
073: public static ContinuationConfigRuntime getActiveConfigRuntime()
074: throws MissingActiveContinuationConfigRuntimeException {
075: ContinuationConfigRuntime config = sActiveConfigRuntime.get();
076: if (null == config) {
077: throw new MissingActiveContinuationConfigRuntimeException();
078: }
079: return config;
080: }
081:
082: /**
083: * The duration, in milliseconds, by which a continuation stays valid.
084: * <p>When this period is exceeded, a continuation can not be retrieved
085: * anymore and it will be removed from the manager during the next purge.
086: *
087: * @return the validity duration of a continuation in milliseconds
088: * @since 1.6
089: */
090: public long getContinuationDuration() {
091: return DEFAULT_CONTINUATION_DURATION;
092: }
093:
094: /**
095: * The frequency by which the continuations purging will run in the
096: * {@link ContinuationManager}.
097: * <p>This works together with the scale that is configured through
098: * {@link #getContinuationPurgeScale}. The frequency divided by the scale
099: * makes how often the purging will happen. For instance, a frequency of 20
100: * and a scale of 1000 means that purging will happen 1/50th of the time.
101: *
102: * @return the continuation purge frequency
103: * @see #getContinuationPurgeScale
104: * @since 1.6
105: */
106: public int getContinuationPurgeFrequency() {
107: return DEFAULT_CONTINUATION_PURGE_FREQUENCY;
108: }
109:
110: /**
111: * The scale that will be used to determine how often continuations purging
112: * will run in the {@link ContinuationManager}.
113: * <p>See {@link #getContinuationPurgeScale} for more info.
114: *
115: * @return the continuation purge scale
116: * @see #getContinuationPurgeFrequency
117: * @since 1.6
118: */
119: public int getContinuationPurgeScale() {
120: return DEFAULT_CONTINUATION_PURGE_SCALE;
121: }
122:
123: /**
124: * Retrieves the {@code ContinuableObject} that corresponds to the currently
125: * executing object instance.
126: * <p> If you don't work with a seperate continuable support class
127: * ({@link ContinuationConfigInstrument#getContinuableSupportClassName see here})
128: * and don't allow people to just implement a marker interface without having
129: * to extend a base class, the associated continuable object is the same as
130: * the executing instance.
131: * <p>However, if there is a separate continuable support class, you'll need
132: * to return the appropriate continuable object here.
133: *
134: * @param executingInstance the currently executing object instance
135: * @return the executing {@code ContinuableObject}
136: * @see ContinuationConfigInstrument#getContinuableSupportClassName
137: * @since 1.6
138: */
139: public abstract T getAssociatedContinuableObject(
140: Object executingInstance);
141:
142: /**
143: * Retrieves the manager that is responsible for the
144: * {@code ContinuableObject} that is currently executing.
145: *
146: * @param executingContinuable the currently executing continuable
147: * @return the corresponding manager
148: * @since 1.6
149: */
150: public abstract ContinuationManager getContinuationManager(
151: T executingContinuable);
152:
153: /**
154: * Indicates whether a continuable should be cloned before resuming the
155: * execution.
156: *
157: * @param executingContinuable the currently executing continuable
158: * @return {@code true} is the continuation should be cloned; or
159: * <p>{@code false} otherwise
160: * @since 1.6
161: */
162: public abstract boolean cloneContinuations(T executingContinuable);
163: }
|