2
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
4
* Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
6
* The contents of this file are subject to the terms of either the GNU
7
* General Public License Version 2 only ("GPL") or the Common
8
* Development and Distribution License("CDDL") (collectively, the
9
* "License"). You may not use this file except in compliance with the
10
* License. You can obtain a copy of the License at
11
* http://www.netbeans.org/cddl-gplv2.html
12
* or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
13
* specific language governing permissions and limitations under the
14
* License. When distributing the software, include this License Header
15
* Notice in each file and include the License file at
16
* nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
17
* particular file as subject to the "Classpath" exception as provided
18
* by Sun in the GPL Version 2 section of the License file that
19
* accompanied this code. If applicable, add the following below the
20
* License Header, with the fields enclosed by brackets [] replaced by
21
* your own identifying information:
22
* "Portions Copyrighted [year] [name of copyright owner]"
26
* The Original Software is NetBeans. The Initial Developer of the Original
27
* Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
28
* Microsystems, Inc. All Rights Reserved.
30
* If you wish your version of this file to be governed by only the CDDL
31
* or only the GPL Version 2, indicate your decision by adding
32
* "[Contributor] elects to include this software in this distribution
33
* under the [CDDL or GPL Version 2] license." If you do not indicate a
34
* single choice of license, a recipient has the option to distribute
35
* your version of this file under either the CDDL, the GPL Version 2 or
36
* to extend the choice of license to its licensees as provided above.
37
* However, if you add GPL Version 2 code and therefore, elected the GPL
38
* Version 2 license, then the option applies only if the new code is
39
* made subject to such option by the copyright holder.
42
package org.openide.execution;
44
import java.security.AllPermission;
45
import java.security.CodeSource;
46
import java.security.PermissionCollection;
47
import java.security.Permissions;
48
import org.openide.util.Lookup;
49
import org.openide.util.RequestProcessor;
50
import org.openide.windows.IOProvider;
51
import org.openide.windows.InputOutput;
54
* Engine providing the environment necessary to run long-lived processes.
55
* May perform tasks such as setting up thread groups, etc.
56
* Modules should not implement this class.
57
* @author Jaroslav Tulach, Ales Novak
59
public abstract class ExecutionEngine extends Object {
62
* Run some task in the execution engine.
63
* @param name a name of the new process
64
* @param run a runnable to execute
65
* @param io an I/O handle to automatically redirect system I/O streams in the dynamic scope of the task to,
66
* or null if no such redirection is required
67
* @return an executor task that can control the execution
69
public abstract ExecutorTask execute(String name, Runnable run, InputOutput io);
72
* Users that want to link their classes with NetBeans module classes should do this through
73
* internal execution. The {@link NbClassLoader} used in internal execution will assume that calling
74
* this method and giving the permission collection to the class being defined will
75
* trigger automatic redirection of system output, input, and error streams into the given I/O tab.
76
* Implementations of the engine should bind the tab and returned permissions.
77
* Since the permission collection is on the stack when calling methods on {@link System#out} etc.,
78
* it is possible to find the appropriate tab for redirection.
79
* @param cs code source to construct the permission collection for
80
* @param io an I/O tab
81
* @return a permission collection
83
protected abstract PermissionCollection createPermissions(CodeSource cs, InputOutput io);
85
/** Method that allows implementor of the execution engine to provide
86
* class path to all libraries that one could find useful for development
89
* @return class path to libraries
90
* @deprecated There are generally no excuses to be using this method as part of a normal module;
91
* its exact meaning is vague, and probably not what you want.
93
protected abstract NbClassPath createLibraryPath ();
96
* Obtains default instance of the execution engine.
97
* If default {@link Lookup} contains an instance of {@link ExecutionEngine},
98
* that is used. Otherwise, a trivial basic implementation is returned with
99
* the following behavior:
101
* <li>{@link #execute} just runs the runnable immediately and pretends to be done.
102
* <li>{@link #createPermissions} just uses {@link AllPermission}. No I/O redirection
103
* or {@link System#exit} trapping is done.
104
* <li>{@link #createLibraryPath} produces an empty path.
106
* This basic implementation is helpful in unit tests and perhaps in standalone usage
107
* of other libraries.
108
* @return some execution engine implementation (never null)
111
public static ExecutionEngine getDefault() {
112
ExecutionEngine ee = (ExecutionEngine) Lookup.getDefault().lookup(ExecutionEngine.class);
120
* Dummy fallback implementation, useful for unit tests.
122
static final class Trivial extends ExecutionEngine {
126
protected NbClassPath createLibraryPath() {
127
return new NbClassPath(new String[0]);
130
protected PermissionCollection createPermissions(CodeSource cs, InputOutput io) {
131
PermissionCollection allPerms = new Permissions();
132
allPerms.add(new AllPermission());
133
allPerms.setReadOnly();
137
public ExecutorTask execute(String name, Runnable run, InputOutput io) {
138
return new ET(run, name, io);
141
private static final class ET extends ExecutorTask {
142
private RequestProcessor.Task task;
143
private int resultValue;
144
private final String name;
145
private InputOutput io;
147
public ET(Runnable run, String name, InputOutput io) {
149
this.resultValue = resultValue;
151
task = RequestProcessor.getDefault().post(this);
158
public int result() {
163
public InputOutput getInputOutput() {
170
} catch (RuntimeException x) {