KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > api > debugger > DebuggerEngine


1 /*
2  * The contents of this file are subject to the terms of the Common Development
3  * and Distribution License (the License). You may not use this file except in
4  * compliance with the License.
5  *
6  * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7  * or http://www.netbeans.org/cddl.txt.
8  *
9  * When distributing Covered Code, include this CDDL Header Notice in each file
10  * and include the License file at http://www.netbeans.org/cddl.txt.
11  * If applicable, add the following below the CDDL Header, with the fields
12  * enclosed by brackets [] replaced by your own identifying information:
13  * "Portions Copyrighted [year] [name of copyright owner]"
14  *
15  * The Original Software is NetBeans. The Initial Developer of the Original
16  * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */
19
20 package org.netbeans.api.debugger;
21
22 import java.beans.*;
23 import java.io.*;
24 import java.util.*;
25
26 /**
27  * Debugger Engine represents implementation of one debugger (Java Debugger,
28  * CPP Debugger). It can support debugging of one or more
29  * {@link Session}s, in one or more languages.
30  * It provides root of threads hierarchy (call stacks, locals)
31  * and manages debugger actions.
32  *
33  * <p><br><table border="1" cellpadding="3" cellspacing="0" width="100%">
34  * <tbody><tr bgcolor="#ccccff">
35  * <td colspan="2"><font size="+2"><b>Description </b></font></td>
36  * </tr><tr><td align="left" valign="top" width="1%"><font size="+1">
37  * <b>Functionality</b></font></td><td>
38  *
39  * <b>Support for actions:</b>
40  * DebuggerEngine manages list of actions ({@link #getActionsManager}).
41  * Debugger action (implemented by
42  * {@link org.netbeans.spi.debugger.ActionsProvider}) can be registerred to
43  * DebuggerEngine during a start of debugger. See
44  * {@link org.netbeans.spi.debugger.ActionsProvider}.
45  * ActionsManager can be used to call some debugger action
46  * ({@link ActionsManager#doAction}) and to distinguish availability of action
47  * ({@link ActionsManager#isEnabled}).
48  * Example how to call Kill Action on this engine:
49  * <pre>
50  * engine.getActionsManager ().doAction (ActionsManager.ACTION_KILL);</pre>
51  *
52  * <br>
53  * <b>Support for aditional services:</b>
54  * DebuggerEngine is final class. That is why the standard method how to
55  * extend its functionality is using lookup methods ({@link #lookup} and
56  * {@link #lookupFirst}).
57  * There are two ways how to register some service provider for some
58  * type of DebuggerEngine:
59  * <ul>
60  * <li>Register 'live' instance of service provider during creation of
61  * new instance of DebuggerEngine (see method
62  * {@link org.netbeans.spi.debugger.DebuggerEngineProvider#getServices}).
63  * </li>
64  * <li>Register service provider in Manifest-inf/debugger/&lt;type ID&gt;
65  * folder. See Debugger SPI for more information about
66  * registration.</li>
67  * </ul>
68  *
69  * <br>
70  * <b>Support for listening:</b>
71  * DebuggerEngine propagates all changes to two type of listeners - general
72  * {@link java.beans.PropertyChangeListener} and specific
73  * {@link ActionsManagerListener}.
74  *
75  * <br>
76  * </td></tr><tr><td align="left" valign="top" width="1%"><font size="+1">
77  * <b>Clinents / Providers</b></font></td><td>
78  *
79  * This class is final, so it does not have any external provider.
80  * Debugger Plug-ins and UI modules are clients of this class.
81  *
82  * <br>
83  * </td></tr><tr><td align="left" valign="top" width="1%"><font size="+1">
84  * <b>Lifecycle</b></font></td><td>
85  *
86  * A new instance(s) of DebuggerEngine class are created in Debugger Core
87  * module only, during the process of starting of debugging (see
88  * {@link DebuggerManager#startDebugging}.
89  *
90  * DebuggerEngine is removed automatically from {@link DebuggerManager} when the
91  * the last action is ({@link ActionsManager#ACTION_KILL}).
92  *
93  * </td></tr><tr><td align="left" valign="top" width="1%"><font size="+1">
94  * <b>Evolution</b></font></td><td>
95  *
96  * No method should be removed from this class, but some functionality can
97  * be added in future.
98  *
99  * </td></tr></tbody></table>
100  *
101  * @author Jan Jancura
102  */
103 public final class DebuggerEngine {
104     
105     
106     // variables ...............................................................
107
108     private Lookup lookup;
109     private ActionsManager actionsManager;
110
111     
112     DebuggerEngine (
113         String JavaDoc typeID,
114         Session s,
115         Object JavaDoc[] services,
116         Lookup sessionLookup
117     ) {
118         Object JavaDoc[] services1 = new Object JavaDoc [services.length + 1];
119         System.arraycopy (services, 0, services1, 0, services.length);
120         services1 [services1.length - 1] = this;
121         Lookup privateLookup = new Lookup.Compound (
122                 new Lookup.Instance (services1),
123                 new Lookup.MetaInf (typeID)
124             );
125         this.lookup = new Lookup.Compound (
126             privateLookup,
127             sessionLookup
128         );
129     }
130     
131 // /**
132 // * Returns list of services of given type.
133 // *
134 // * @param service a type of service to look for
135 // * @return list of services of given type
136 // */
137 // public List lookup (Class service) {
138 // return lookup.lookup (null, service);
139 // }
140 //
141 // /**
142 // * Returns one service of given type.
143 // *
144 // * @param service a type of service to look for
145 // * @return ne service of given type
146 // */
147 // public Object lookupFirst (Class service) {
148 // return lookup.lookupFirst (null, service);
149 // }
150
151     /**
152      * Returns list of services of given type from given folder.
153      *
154      * @param service a type of service to look for
155      * @return list of services of given type
156      */
157     public List lookup (String JavaDoc folder, Class JavaDoc service) {
158         return lookup.lookup (folder, service);
159     }
160     
161     /**
162      * Returns one service of given type from given folder.
163      *
164      * @param service a type of service to look for
165      * @return ne service of given type
166      */
167     public Object JavaDoc lookupFirst (String JavaDoc folder, Class JavaDoc service) {
168         return lookup.lookupFirst (folder, service);
169     }
170     
171     
172     // main public methods .....................................................
173
174
175     public synchronized ActionsManager getActionsManager () {
176         if (actionsManager == null)
177             actionsManager = new ActionsManager (lookup);
178         return actionsManager;
179     }
180     
181     
182     // innerclasses ............................................................
183
184     /**
185      * This class notifies about DebuggerEngine remove from the system, and
186      * about changes in language support. Instance of Destructor can be
187      * obtained from: {@link org.netbeans.spi.debugger.DebuggerEngineProvider#setDestructor(DebuggerEngine.Destructor)}, or
188      * {@link org.netbeans.spi.debugger.DelegatingDebuggerEngineProvider#setDestructor(DebuggerEngine.Destructor)}.
189      */
190     public class Destructor {
191         
192         /**
193          * Removes DebuggerEngine form all sessions.
194          */
195         public void killEngine () {
196             Session[] ss = DebuggerManager.getDebuggerManager ().getSessions ();
197             int i, k = ss.length;
198             for (i = 0; i < k; i++)
199                 ss [i].removeEngine (DebuggerEngine.this);
200             getActionsManager ().destroy ();
201         }
202         
203         /**
204          * Removes given language support from given session.
205          *
206          * @param s a session
207          * @param language a language to be removed
208          */
209         public void killLanguage (Session s, String JavaDoc language) {
210             s.removeLanguage (language, DebuggerEngine.this);
211             getActionsManager ().destroy ();
212         }
213     }
214 }
215
216
Popular Tags