Session


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.PropertyChangeListener  ;
23  import java.beans.PropertyChangeSupport  ;
24  import java.util.ArrayList  ;
25  import java.util.Arrays  ;
26  import java.util.HashSet  ;
27  import java.util.Iterator  ;
28  import java.util.List  ;
29  
30  
31  /** Session visually represents one process or application. It should
32   * be simple bean with properties like process ID, session name, etc.
33   * All other functionality is deleagted to current debugger engine.
34   *
35   * <p><br><table border="1" cellpadding="3" cellspacing="0" width="100%">
36   * <tbody><tr bgcolor="#ccccff">
37   * <td colspan="2"><font size="+2"><b>Description </b></font></td>
38   * </tr><tr><td align="left" valign="top" width="1%"><font size="+1">
39   * <b>Functionality</b></font></td><td>
40   *
41   * <b>Properties:</b>
42   *    Session has two standard read only properties - name ({@link #getName}) and
43   *    location name ({@link #getLocationName}).
44   *
45   * <br><br>
46   * <b>Management of languages and engines:</b>
47   *    Debugger Core supports debugging in different languages. It means that 
48   *    each session can be debugged using different languages and 
49   *    {@link org.netbeans.api.debugger.DebuggerEngine}s. Session manages list 
50   *    of supported languages ({@link #getSupportedLanguages}) and current 
51   *    language ({@link #getCurrentLanguage}). Current language can be changed
52   *    ({@link #setCurrentLanguage}).
53   *    Each language corresponds to one 
54   *    {@link org.netbeans.api.debugger.DebuggerEngine} 
55   *    ({@link #getEngineForLanguage}). So, the current language
56   *    defines current debuggger engine ({@link #getCurrentEngine})
57   *
58   *    A support for a new debugger language can be added during a start of
59   *    debugging only. See 
60   *    {@link org.netbeans.api.debugger.DebuggerManager#startDebugging} and
61   *    {@link org.netbeans.spi.debugger.DebuggerEngineProvider}
62   *
63   * <br><br>
64   * <b>Support for aditional services:</b>
65   *    Session is final class. The standard method how to 
66   *    extend its functionality is using lookup methods ({@link #lookup} and 
67   *    {@link #lookupFirst}).
68   *    There are two ways how to register some service provider for some
69   *    type of Session:
70   *    <ul>
71   *      <li>Register 'live' instance of service provider during creation of 
72   *        new instance of Session (see method
73   *        {@link org.netbeans.spi.debugger.SessionProvider#getServices}).
74   *      </li>
75   *      <li>Register service provider in Manifest-inf/debugger/&lt;type ID&gt;
76   *        folder. See Debugger SPI for more information about
77   *        registration.</li>
78   *    </ul>
79   *
80   * <br>
81   * <b>Support for listening:</b>
82   *    Session propagates all changes to
83   *    {@link java.beans.PropertyChangeListener}.
84   *
85   * <br> 
86   * </td></tr><tr><td align="left" valign="top" width="1%"><font size="+1">
87   * <b>Clinents / Providers</b></font></td><td>
88   *
89   * This class is final, so it does not have any external provider.
90   * Debugger Core and UI modules are clients of this class.
91   *
92   * <br>
93   * </td></tr><tr><td align="left" valign="top" width="1%"><font size="+1">
94   * <b>Lifecycle</b></font></td><td>
95   *
96   * A new instance of Session class can be created and registerred to 
97   * {@link org.netbeans.api.debugger.DebuggerManager} during the process
98   * of starting of debugging (see
99   * {@link org.netbeans.api.debugger.DebuggerManager#startDebugging}).
100  *
101  * Session is removed automatically from 
102  * {@link org.netbeans.api.debugger.DebuggerManager} when the 
103  * number of "supported languages" ({@link #getSupportedLanguages}) is zero.
104  *
105  * </td></tr><tr><td align="left" valign="top" width="1%"><font size="+1">
106  * <b>Evolution</b></font></td><td>
107  *
108  * No method should be removed from this class, but some functionality can
109  * be added in future.
110  *
111  * </td></tr></tbody></table>
112  *
113  * @author Jan Jancura
114  */
115 public final class Session {
116     
117     /** Name of property for current language. */
118     public static final String   PROP_CURRENT_LANGUAGE = "currentLanguage";
119     
120     /** Name of property for the set of supported languages. */
121     public static final String   PROP_SUPPORTED_LANGUAGES = "supportedLanguages";
122 
123     
124     // variables ...............................................................
125     
126     private String                name;
127     private String                locationName;
128     private DebuggerEngine      currentDebuggerEngine;
129     private String                currentLanguage;
130     private String  []            languages;
131     private DebuggerEngine[]    engines;
132 //    private Listener            listener;
133     private PropertyChangeSupport   pcs;
134     private Lookup              lookup;
135     Lookup                      privateLookup;
136 
137     
138     // initialization ..........................................................
139     
140     Session (
141         String   name,
142         String   locationName,
143         String   id,
144         Object  [] services,
145         Lookup diLookup
146     ) {
147         this.name = name;
148         this.locationName = locationName;
149         this.languages = new String   [0];
150         this.engines = new DebuggerEngine [0];
151         pcs = new PropertyChangeSupport   (this);
152         
153         // create lookup
154         Object  [] s = new Object   [services.length + 1];
155         System.arraycopy (services, 0, s, 0, services.length);
156         s [s.length - 1] = this;
157         privateLookup = new Lookup.Compound (
158             new Lookup.Instance (s),
159             new Lookup.MetaInf (id)
160         );
161         this.lookup = new Lookup.Compound (
162             diLookup,
163             privateLookup
164         );
165     }
166 
167     
168     // public interface ........................................................
169 
170     /**
171      * Returns display name of this session.
172      *
173      * @return display name of this session
174      */
175     public String   getName () {
176         return name;
177     }
178     
179     /**
180      * Returns identifier of type of this session. This id is used for 
181      * identification of engine during registration of services in 
182      * Meta-inf/debugger.
183      *
184      * @return identifier of type of this engine
185      */
186 //    public String getTypeID () {
187 //        return id;
188 //    }
189     
190     /**
191      * Returns name of location this session is running on.
192      *
193      * @return name of location this session is running on
194      */
195     public String   getLocationName () {
196         return locationName;
197     }
198     
199     /**
200      * Returns current debugger engine for this session.
201      *
202      * @return current debugger engine for this session
203      */
204     public DebuggerEngine getCurrentEngine () {
205         return currentDebuggerEngine;
206     }
207     
208     /**
209      * Returns current language for this session.
210      *
211      * @return current language for this session
212      */
213     public String   getCurrentLanguage () {
214         return currentLanguage;
215     }
216     
217     /**
218      * Returns set of all languages supported by this session.
219      *
220      * @return set of all languages supported by this session
221      * @see org.netbeans.spi.debugger.DebuggerEngineProvider
222      */
223     public String  [] getSupportedLanguages () {
224         return languages;
225     }
226     
227     /**
228      * Returns list of services of given type from given folder.
229      *
230      * @param service a type of service to look for
231      * @return list of services of given type
232      */
233     public List   lookup (String   folder, Class   service) {
234         return lookup.lookup (folder, service);
235     }
236     
237     /**
238      * Returns one service of given type from given folder.
239      *
240      * @param service a type of service to look for
241      * @return ne service of given type
242      */
243     public Object   lookupFirst (String   folder, Class   service) {
244         return lookup.lookupFirst (folder, service);
245     }
246     
247     /**
248      * Kills all registerred engines / languages. This utility method calls
249      * <pre>doAction (DebuggerEngine.ACTION_KILL)</pre> method on all
250      * registerred DebuggerEngines.
251      */
252     public void kill () {
253         HashSet   dead = new HashSet   (Arrays.asList (engines));
254         Iterator   i = dead.iterator ();
255         while (i.hasNext ())
256             ((DebuggerEngine) i.next ()).getActionsManager ().
257                 doAction (ActionsManager.ACTION_KILL);
258     }
259 
260     /**
261      * Return DebuggerEngine registerred for given language or null.
262      *
263      * @return DebuggerEngine registerred for given language or null
264      */
265     public DebuggerEngine getEngineForLanguage (String   language) {
266         int i, k = languages.length;
267         for (i = 0; i < k; i++)
268             if (languages [i].equals (language))
269                 return engines [i];
270         return null;
271     }
272     
273     /**
274      * Sets current language for this session. Language should be refisterred
275      * for this session.
276      *
277      * @param language current language
278      * @see org.netbeans.spi.debugger.DebuggerEngineProvider
279      */
280     public void setCurrentLanguage (String   language) {
281         int i, k = languages.length;
282         for (i = 0; i < k; i++) {
283             if (language.equals (languages [i])) {
284                 Object   oldL = currentLanguage;
285                 currentLanguage = language;
286                 currentDebuggerEngine = engines [i];
287                 pcs.firePropertyChange (
288                     PROP_CURRENT_LANGUAGE,
289                     oldL, 
290                     currentLanguage
291                 );
292             }
293         }
294     }
295 
296     
297     // support methods .........................................................
298     
299     Lookup getLookup () {
300         return lookup;
301     }
302     
303     void addLanguage (
304         String   language,
305         DebuggerEngine engine
306     ) {
307         // is pair already added?
308         int i, k = languages.length;
309         for (i = 0; i < k; i++)
310             if (language.equals (languages [i])) {
311                 engines [i] = engine;
312                 return;
313             }
314         
315         // add pair
316         String  [] newLanguages = new String   [languages.length + 1];
317         DebuggerEngine[] newEngines = new DebuggerEngine [engines.length + 1];
318         System.arraycopy (languages, 0, newLanguages, 0, languages.length);
319         System.arraycopy (engines, 0, newEngines, 0, engines.length);
320         newLanguages [languages.length] = language;
321         newEngines [engines.length] = engine;
322         Object   oldL = languages;
323         languages = newLanguages;
324         engines = newEngines;
325         DebuggerManager.getDebuggerManager ().addEngine (engine);
326         pcs.firePropertyChange (
327             PROP_SUPPORTED_LANGUAGES,
328             oldL,
329             languages
330         );
331 //        engine.addEngineListener (
332 //            DebuggerEngineListener.PROP_ACTION_PERFORMED,
333 //            listener
334 //        );
335         if (currentLanguage == null) {
336             setCurrentLanguage (language);
337         }
338     }
339     
340     void removeEngine (
341         DebuggerEngine engine
342     ) {
343         if (engines.length == 0) return;
344         int i, k = engines.length;
345         ArrayList   newLanguages = new ArrayList   ();
346         ArrayList   newEngines = new ArrayList   ();
347         for (i = 0; i < k; i++)
348             if (!engine.equals (engines [i])) {
349                 newLanguages.add (languages [i]);
350                 newEngines.add (engines [i]);
351             }
352         String  [] oldL = languages;
353         languages = (String  []) newLanguages.toArray 
354             (new String   [newLanguages.size ()]);
355         engines = (DebuggerEngine[]) newEngines.toArray 
356             (new DebuggerEngine [newEngines.size ()]);
357         DebuggerManager.getDebuggerManager ().removeEngine (engine);
358         
359         pcs.firePropertyChange (
360             PROP_SUPPORTED_LANGUAGES,
361             oldL,
362             languages
363         );
364     }
365     
366     void removeLanguage (
367         String   language,
368         DebuggerEngine engine
369     ) {
370         int i, k = languages.length;
371         for (i = 0; i < k; i++)
372             if (language.equals (languages [i])) {
373                 if (engines [i] != engine)
374                     throw new IllegalArgumentException   ();
375                 break;
376             }
377         if (i >= k) return;
378         
379         String  [] newLanguages = new String   [k - 1];
380         DebuggerEngine[] newEngines = new DebuggerEngine [k - 1];
381         if (i > 0) {
382             System.arraycopy (languages, 0, newLanguages, 0, i);
383             System.arraycopy (engines, 0, newEngines, 0, i);
384         }
385         System.arraycopy (languages, i + 1, newLanguages, i, k - i - 1);
386         System.arraycopy (engines, i + 1, newEngines, i, k - i - 1);
387         Object   oldL = languages;
388         languages = newLanguages;
389         engines = newEngines;
390         pcs.firePropertyChange (
391             PROP_SUPPORTED_LANGUAGES,
392             oldL,
393             languages
394         );
395         
396         k = engines.length;
397         for (i = 0; i < k; i++)
398             if (engines [i] == engine)
399                 return;
400         DebuggerManager.getDebuggerManager ().removeEngine (engine);
401     }
402 
403     /**
404      * Returns string representation of this session.
405      *
406      * @return string representation of this session
407      */
408     public String   toString () {
409         return "" + getClass ().getName () + " " + getLocationName () + ":" +
410             getName ();
411     }
412     
413     
414     // listener support ........................................................
415     
416 
417     /**
418      * Adds a property change listener.
419      *
420      * @param l the listener to add
421      */
422     public void addPropertyChangeListener (PropertyChangeListener   l) {
423         pcs.addPropertyChangeListener (l);
424     }
425     
426     /**
427      * Removes a property change listener.
428      *
429      * @param l the listener to remove
430      */
431     public void removePropertyChangeListener (PropertyChangeListener   l) {
432         pcs.removePropertyChangeListener (l);
433     }
434     
435     /**
436      * Adds a property change listener.
437      *
438      * @param propertyName a name of property to listen on
439      * @param l the listener to add
440      */
441     public void addPropertyChangeListener (String   propertyName, PropertyChangeListener   l) {
442         pcs.addPropertyChangeListener (propertyName, l);
443     }
444     
445     /**
446      * Removes a property change listener.
447      *
448      * @param propertyName a name of property to stop listening on
449      * @param l the listener to remove
450      */
451     public void removePropertyChangeListener (String   propertyName, PropertyChangeListener   l) {
452         pcs.removePropertyChangeListener (propertyName, l);
453     }
454     
455 
456     // innerclasses ............................................................
457     
458 //    private class Listener extends DebuggerEngineAdapter {
459 //        
460 //        public void actionPerformed (
461 //            DebuggerEngine engine, 
462 //            Object action, 
463 //            boolean success
464 //        ) {
465 //            if (action != DebuggerEngine.ACTION_KILL) return;
466 //            removeEngine (engine);
467 //        }
468 //        
469 //        public void actionStateChanged (
470 //            DebuggerEngine engine, 
471 //            Object action, 
472 //            boolean enabled
473 //        ) {
474 //        }
475 //        
476 //    }
477 }
478 
479 
480
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags