26,59 → 26,69 |
|
// $Id$ |
|
import java.lang.reflect.Method; |
import java.util.Map; |
import javax.script.ScriptEngine; |
|
/** |
* Public methods provided by the sandbox. |
* Note that all methods in this interface imply a call to {@link #execute}. |
*/ |
// Note that all methods defined directly in this interface imply a call to {@link #execute}. |
public interface Sandbox extends RuntimeHooks, SandboxProperties { |
|
/** |
* @see #createDelayedImplementation(Class, boolean) |
* @deprecated (TEMPORARILY) Until the API stabilizes, |
* {@link #createDelayedImplementation(Class, String)} is the only |
* secure variant. |
*/ |
<T> T createDelayedImplementation(final Class<T> interfaceClass) throws PluginExecutionException; |
|
/** |
* Creates an implementation of an interface from JS code |
* @param interfaceClass Class of the interface to implement |
* @param allowPartialImplementation If true, the implementation would be used |
* even if incomplete (note that calling an unimplemented method will produce |
* an exception) |
* @return The implementation |
* @throws net.outlyer.plugins.sandboxing.PluginExecutionException |
* @deprecated (TEMPORARILY) Until the API stabilizes, |
* {@link #createDelayedImplementation(Class, String)} is the only |
* secure variant. |
*/ |
<T> T createDelayedImplementation(final Class<T> interfaceClass, |
boolean allowPartialImplementation) |
throws PluginExecutionException; |
|
/** |
* @see #createDelayedImplementation(Class, boolean) |
* @param fallbackObject If not null incomplete implementations are allowed and |
* calls to undefined methods will be passed to this object |
* @deprecated (TEMPORARILY) Until the API stabilizes, |
* {@link #createDelayedImplementation(Class, String)} is the only |
* secure variant. |
*/ |
<T> T createDelayedImplementation(final Class<T> interfaceClass, |
final T fallbackObject) |
throws PluginExecutionException; |
|
/** |
* Creates an implementation of an interface from a JS object |
* containing the interface's methods. |
* <br /> |
* <b>Note</b>: Implies a call to {@link #execute()}. |
* @param interfaceClass Interface to implement |
* @param objectName Name of the JS object implementing the interface |
* @return The implementation |
* @throws net.outlyer.plugins.PluginExecutionException |
* @see #createDelayedImplementation(Class,Map) |
* @see #execute() |
*/ |
<T> T createDelayedImplementation(final Class<T> interfaceClass, final String objectName) throws PluginExecutionException; |
|
/** |
* Creates an implementation of an interface from inline JS code. |
* This variant allows more flexibility (e.g. the implementation might |
* be split among objects, map to global functions or fallback to other |
* object if unimplemented). |
* Note the mapped code should be evaluable as a JS function AND |
* it shouldn't end in a semicolon, e.g.: |
* <br /> |
* Valid: |
* <pre> |
* function() { return SomeValue; } |
* </pre> |
* <pre> |
* // myFunc() is a function defined somewhere in the code |
* myFunc |
* </pre> |
* <br /> |
* Not valid: |
* <pre> |
* function() { return SomeValue; }; |
* </pre> |
* <pre> |
* SomeValue |
* </pre> |
* <br /> |
* Where possible {@link #createDelayedImplementation(Class,String)} is |
* a much cleaner option. |
* <br /> |
* <b>Note</b>: Implies a call to {@link #execute()}. |
* @param interfaceClass |
* @param methodToCodeMap |
* @return |
* @throws net.outlyer.plugins.PluginExecutionException |
* @see #createDelayedImplementation(Class,String) |
*/ |
<T> T createDelayedImplementation(final Class<T> interfaceClass, |
final Map<Method, String> methodToCodeMap) |
throws PluginExecutionException; |
|
/** |
* Run the script |
*/ |
void execute() throws PluginExecutionException; |
85,8 → 95,18 |
|
/** |
* Obtains object containing the plugin object |
* <br /> |
* <b>Note</b>: Implies a call to {@link #execute()}. |
* @see #getPluginName |
* @return Plugin object associated to this sandbox |
*/ |
BasePluginObject getPluginObject() throws PluginExecutionException; |
|
/** |
* Obtains a reference to the engine currently in use, if any. |
* If called during an execution it will return the current engine, from calling |
* outside will return null. |
* @return Current ScriptEngine |
*/ |
ScriptEngine getCurrentEngine(); |
} |