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: ContinuationConfigInstrument.java 3811 2007-06-25 15:06:16Z gbevin $
007: */
008: package com.uwyn.rife.continuations;
009:
010: /**
011: * This interface needs to be implemented to configure the bytecode
012: * instrumentation that enables the continuations functionalities.
013: *
014: * @author Geert Bevin (gbevin[remove] at uwyn dot com)
015: * @version $Revision: 3811 $
016: * @since 1.6
017:
018: */
019: public interface ContinuationConfigInstrument {
020: /**
021: * The name of the interface that will indicate that a class should be
022: * instrumented for continuations functionalities, for instance
023: * {@code ContinuableObject.class.getName()}.
024: *
025: * @return the name of the marker interface
026: * @since 1.6
027: */
028: public String getContinuableMarkerInterfaceName();
029:
030: /**
031: * The class name of the support class that contains dummy implementations
032: * of the continuation methods that are configured below, for instance
033: * {@code ContinuableSupport.class.getName()}.
034: * <p>If you implement these methods in your continuable classes or extend
035: * these classes from a common base class with those methods that are then
036: * called locally, this configuration can return {@code null} since it
037: * will not be used. A class name only needs to be provided if your
038: * continuable classes only implement the marker interface, and you call
039: * the continuation methods on an instance of this support inside your
040: * continuations logic.
041: *
042: * @return the name of the continuable support class; or
043: * <p>{@code null} if such a support class isn't used
044: * @since 1.6
045: */
046: public String getContinuableSupportClassName();
047:
048: /**
049: * The name of the entry method that will be invoked when a new instance
050: * of a continuable class is created and its execution is started, for
051: * instance {@code "execute"}.
052: *
053: * @return the name of the entry method
054: * @since 1.6
055: */
056: public String getEntryMethodName();
057:
058: /**
059: * The return type of the entry method, for instance
060: * {@code void.class}.
061: * <p>This will solely be used to detect and lookup the method before
062: * instrumenting or calling it.
063: *
064: * @return the class of the entry method's return value
065: * @since 1.6
066: */
067: public Class getEntryMethodReturnType();
068:
069: /**
070: * The array argument types that the entry method takes, for instance
071: * {@code null} if it takes none.
072: * <p>This will solely be used to detect and lookup the method before
073: * instrumenting or calling it.
074: *
075: * @return the array of argument types of the entry method; or
076: * {@code null} if there are none
077: * @since 1.6
078: */
079: public Class[] getEntryMethodArgumentTypes();
080:
081: /**
082: * The name of the method that will trigger a pause continuation, for
083: * instance {@code "pause"}.
084: * <p>This method should have a {@code void} return type and take no
085: * arguments.
086: *
087: * @return the name of the pause method
088: * @since 1.6
089: */
090: public String getPauseMethodName();
091:
092: /**
093: * The name of the method that will trigger a step-back continuation, for
094: * instance {@code "stepback"}.
095: * <p>This method should have a {@code void} return type and take no
096: * arguments.
097: *
098: * @return the name of the step-back method
099: * @since 1.6
100: */
101: public String getStepbackMethodName();
102:
103: /**
104: * The name of the method that will trigger a call continuation, for
105: * instance {@code "call"}.
106: *
107: * @return the name of the call method
108: * @since 1.6
109: */
110: public String getCallMethodName();
111:
112: /**
113: * The return type of the call method, for instance {@code Object.class}.
114: * <p>This needs to be an object, not a primitive and you have to be
115: * certain that it's compatible with the values that are sent through the
116: * answer to the call continuation. It's just recommended to keep this as
117: * generic as possible (hence {@code Object.class}).
118: *
119: * @return the type of the call method's return value
120: * @since 1.6
121: */
122: public Class getCallMethodReturnType();
123:
124: /**
125: * The array argument types that the call method takes, for instance
126: * {@code new Class[] {String.class}}.
127: * <p>This needs to be a single object argument, not more or less than one,
128: * and not a primitive. You will use this yourself in the implementation
129: * of the runner that executes the continuations. If the
130: * {@link com.uwyn.rife.continuations.basic.BasicContinuableRunner} is
131: * used, {@link com.uwyn.rife.continuations.basic.CallTargetRetriever} will
132: * be used to resolve the target of the call continuation by using the
133: * what's provided as the argument of the method call.
134: *
135: * @return the array of argument types of the call method
136: * @since 1.6
137: */
138: public Class[] getCallMethodArgumentTypes();
139:
140: /**
141: * The name of the method that will trigger the answer to a call
142: * continuation, for instance {@code "answer"}.
143: * <p>This method should have a {@code void} return type and take one
144: * argument with the type {@code java.lang.Object}.
145: *
146: * @return the name of the answer method
147: * @since 1.6
148: */
149: public String getAnswerMethodName();
150: }
|