001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package org.netbeans.api.debugger;
043:
044: import java.util.List;
045: import org.netbeans.spi.debugger.ContextProvider;
046:
047: /**
048: * Debugger Engine represents implementation of one debugger (Java Debugger,
049: * CPP Debugger). It can support debugging of one or more
050: * {@link Session}s, in one or more languages.
051: * It provides root of threads hierarchy (call stacks, locals)
052: * and manages debugger actions.
053: *
054: * <p><br><table border="1" cellpadding="3" cellspacing="0" width="100%">
055: * <tbody><tr bgcolor="#ccccff">
056: * <td colspan="2"><font size="+2"><b>Description </b></font></td>
057: * </tr><tr><td align="left" valign="top" width="1%"><font size="+1">
058: * <b>Functionality</b></font></td><td>
059: *
060: * <b>Support for actions:</b>
061: * DebuggerEngine manages list of actions ({@link #getActionsManager}).
062: * Debugger action (implemented by
063: * {@link org.netbeans.spi.debugger.ActionsProvider}) can be registerred to
064: * DebuggerEngine during a start of debugger. See
065: * {@link org.netbeans.spi.debugger.ActionsProvider}.
066: * ActionsManager can be used to call some debugger action
067: * ({@link ActionsManager#doAction}) and to distinguish availability of action
068: * ({@link ActionsManager#isEnabled}).
069: * Example how to call Kill Action on this engine:
070: * <pre>
071: * engine.getActionsManager ().doAction (ActionsManager.ACTION_KILL);</pre>
072: *
073: * <br>
074: * <b>Support for aditional services:</b>
075: * DebuggerEngine is final class. That is why the standard method how to
076: * extend its functionality is using lookup methods ({@link #lookup} and
077: * {@link #lookupFirst}).
078: * There are two ways how to register some service provider for some
079: * type of DebuggerEngine:
080: * <ul>
081: * <li>Register 'live' instance of service provider during creation of
082: * new instance of DebuggerEngine (see method
083: * {@link org.netbeans.spi.debugger.DebuggerEngineProvider#getServices}).
084: * </li>
085: * <li>Register service provider in Manifest-inf/debugger/<type ID>
086: * folder. See Debugger SPI for more information about
087: * registration.</li>
088: * </ul>
089: *
090: * <br>
091: * <b>Support for listening:</b>
092: * DebuggerEngine propagates all changes to two type of listeners - general
093: * {@link java.beans.PropertyChangeListener} and specific
094: * {@link ActionsManagerListener}.
095: *
096: * <br>
097: * </td></tr><tr><td align="left" valign="top" width="1%"><font size="+1">
098: * <b>Clinents / Providers</b></font></td><td>
099: *
100: * This class is final, so it does not have any external provider.
101: * Debugger Plug-ins and UI modules are clients of this class.
102: *
103: * <br>
104: * </td></tr><tr><td align="left" valign="top" width="1%"><font size="+1">
105: * <b>Lifecycle</b></font></td><td>
106: *
107: * A new instance(s) of DebuggerEngine class are created in Debugger Core
108: * module only, during the process of starting of debugging (see
109: * {@link DebuggerManager#startDebugging}.
110: *
111: * DebuggerEngine is removed automatically from {@link DebuggerManager} when the
112: * the last action is ({@link ActionsManager#ACTION_KILL}).
113: *
114: * </td></tr><tr><td align="left" valign="top" width="1%"><font size="+1">
115: * <b>Evolution</b></font></td><td>
116: *
117: * No method should be removed from this class, but some functionality can
118: * be added in future.
119: *
120: * </td></tr></tbody></table>
121: *
122: * @author Jan Jancura
123: */
124: public final class DebuggerEngine implements ContextProvider {
125:
126: // variables ...............................................................
127:
128: private Lookup lookup;
129: private ActionsManager actionsManager;
130:
131: DebuggerEngine(String typeID, Session s, Object[] services,
132: Lookup sessionLookup) {
133: Object[] services1 = new Object[services.length + 1];
134: System.arraycopy(services, 0, services1, 0, services.length);
135: services1[services1.length - 1] = this ;
136: Lookup privateLookup = new Lookup.Compound(new Lookup.Instance(
137: services1), new Lookup.MetaInf(typeID));
138: this .lookup = new Lookup.Compound(privateLookup, sessionLookup);
139: }
140:
141: // /**
142: // * Returns list of services of given type.
143: // *
144: // * @param service a type of service to look for
145: // * @return list of services of given type
146: // */
147: // public List lookup (Class service) {
148: // return lookup.lookup (null, service);
149: // }
150: //
151: // /**
152: // * Returns one service of given type.
153: // *
154: // * @param service a type of service to look for
155: // * @return ne service of given type
156: // */
157: // public Object lookupFirst (Class service) {
158: // return lookup.lookupFirst (null, service);
159: // }
160:
161: /**
162: * Returns list of services of given type from given folder.
163: *
164: * @param service a type of service to look for
165: * @return list of services of given type
166: */
167: public <T> List<? extends T> lookup(String folder, Class<T> service) {
168: return lookup.lookup(folder, service);
169: }
170:
171: /**
172: * Returns one service of given type from given folder.
173: *
174: * @param service a type of service to look for
175: * @return ne service of given type
176: */
177: public <T> T lookupFirst(String folder, Class<T> service) {
178: return lookup.lookupFirst(folder, service);
179: }
180:
181: // main public methods .....................................................
182:
183: public synchronized ActionsManager getActionsManager() {
184: if (actionsManager == null)
185: actionsManager = new ActionsManager(lookup);
186: return actionsManager;
187: }
188:
189: // innerclasses ............................................................
190:
191: /**
192: * This class notifies about DebuggerEngine remove from the system, and
193: * about changes in language support. Instance of Destructor can be
194: * obtained from: {@link org.netbeans.spi.debugger.DebuggerEngineProvider#setDestructor(DebuggerEngine.Destructor)}, or
195: * {@link org.netbeans.spi.debugger.DelegatingDebuggerEngineProvider#setDestructor(DebuggerEngine.Destructor)}.
196: */
197: public class Destructor {
198:
199: /**
200: * Removes DebuggerEngine form all sessions.
201: */
202: public void killEngine() {
203: Session[] ss = DebuggerManager.getDebuggerManager()
204: .getSessions();
205: int i, k = ss.length;
206: for (i = 0; i < k; i++)
207: ss[i].removeEngine(DebuggerEngine.this );
208: getActionsManager().destroy();
209: }
210:
211: /**
212: * Removes given language support from given session.
213: *
214: * @param s a session
215: * @param language a language to be removed
216: */
217: public void killLanguage(Session s, String language) {
218: s.removeLanguage(language, DebuggerEngine.this);
219: getActionsManager().destroy();
220: }
221: }
222: }
|