Extending NetBeans by Tim Boudreau by Jesse Glick Copyright © 2001, 2002 O’Reilly & Associates, Inc. Warning This is a DRAFT IN PROGRESS and should not be distributed freely! Except with special permission, only O’Reilly employees, authors, and reviewers should be reading this manuscript at this stage. Table of Contents Foreword—byJamesGosling 1.Introduction Who Should Read this Book? 249 What’sDifferent aboutNetBeans? 250 The Core and theOpen APIs 250 TheLicense 251 Open-Source 252 Thenetbeans.org WebSite 252 NetBeansfor BeanCounters 254 Getting andInstalling the Open APIs Support Module 255 LifeisChange 256 Source code for the examples 256 2.History ofNetBeans HumbleBeginnings 257 FirstSuccesses, FirstCosts 258 SunMeetsNetBeans 259 Open-Source,Fire-DrillStyle 260 NetBeansToday 260 3. Understanding the NetBeans APIs DesignPhilosophyofNetBeans 261 Abstracting the Abstractions—the Open APIs 262 Modularity 262 Hierarchy,Files andNodes 263 Everythingis aFile—Virtually 263 Mapping Files to Java Objects 264 TheSystemFilesystem 265 ModuleLayers 265 Layers in the System Filesystem 266 Exploringthe SystemFilesystem 267 Data Objects—Wrappers for Persistent Data 270 NetBeansandJavaBeans 270 Nodes—theApplication asHierarchy 270 Presenting Nodes to the User—Explorer 271 User-LevelCustomization 273 Nodes inAction—Customizing the IDE without Writing Code 275 Modules—Overview 278 HowModules AddFunctionality 278 How Modules Install VirtualFilesystem Layers 279 WhatModules CanDo 279 DisablingModules 280 An Illustration—NetBeans with No Modules at All 280 Interacting with the IDE through Internal Execution 281 Setting the Status Bar Text 282 Settingthe CurrentWorkspace 283 4.The OpenAPIs The IDE’s Architecture andthe APIs 284 APIs versus Core versus Modules 285 Service Provider Interfaces andClient APIs 286 Overview of the APIs and Their Purposes 286 Modules 287 Lookup and the Services API 294 Nodes 296 Datasystems 299 Explorer 299 Actions 304 Options 305 Compiler 305 Editor 306 WindowingSystem 307 Cookies 309 Execution 310 JavaHierarchy 310 Filesystems 311 Modules, JARs, and Class Loaders 312 Threading, Deadlocks, and How to Avoid Them 317 5. Developing Modules—the NewModule Wizard TheHelloWorldModule 319 Creating aModule Using the New Module Wizard 319 TheSourceFiles 320 6. Internals of theRunning IDE TheActivatedNode(s) 323 Cookies 324 A Peek under the Hood—Examining the Activated Nodes with the CurrentNodeViewer 325 Touring NetBeans with theBean Browser 325 Data Objects, Nodes and Cookies 327 FilesystemsandtheRepository 327 Services 328 Lookup 329 Options 330 UIComponents 331 TopComponents,Modes andWorkspaces 331 Actions 336 Presenters 337 CustomPropertyEditors 337 Localization 337 Wizards 338 Jumping-offPlaces 338 Special Folders in theSystem Filesystem 339 7. Creating the QuickPanel Module Abstractions Covered in this Chapter 342 Creating the Project Files Drop-Down 343 FilterNode—Filtering WhichChildren of a Node are Displayed 347 Creatingthe MethodsDrop-Down 349 Improvingthe MethodsDrop-Down 350 CreatingtheModule 353 Creating a Container GUI Component 354 CreatingtheShowQuickPanelAction 354 Creating the XML Filesystem Layer 355 Creating and Populating theModule JAR 356 Building and Testing the Module 356 ALittleHomework 357 8.A Mail-BasedFilesystem Building aMail Reader in the NetBeans Paradigm 358 Implementing MailFileSystem Using AbstractFileSystemand JavaMail 359 Creating a New AbstractFileSystem Implementation 359 MailFilesystem:AbstractFileSystem.Info 360 MailFilesystem:AbstractFileSystem.List 361 MailFilesystem:AbstractFileSystem.Change 362 MailFilesystem:AbstractFileSystem.Attr 363 OtherParts ofAbstractFileSystem 363 Creating Folder Objects for Attachments 366 Using FileSystem.Status Annotations to Mark Unread Messages 367 BeanInfo—DisplayingFilesystemProperties 369 Using the Wizard Framework to Set Up Mail Accounts 371 CreatingWizardClasses 371 The IMAP Mail ServerTemplate Wizard 372 9. Creating the User Interface for the Mail Client Creating a DataLoader for Messages 381 Displaying andEditing Simple Messages and Unnamed Attachments 382 HandlingMultipartMessages 386 Creating aThreaded Mail View Using Filter Nodes 387 Making a Basic Mail View 388 Making aThreaded Mail View as an Alternative 394 Creatinga MailWorkspace 400 10.Score FileSupport Overview—FunctionalitytobeImplemented 406 Creating the Minicomposer Module—First Things 406 CreatingtheManifest 406 CreatingtheLayer 407 Creating a JAR FileUsing Ant 408 Creating aUniFileLoader and MultiDataObject for *.score Files 408 Creating an Editor Supportfor Scores 411 Creating a Fixed ExecCookie to Play Scores 414 Creatinga SimpleTemplate 417 11. Creatinga Structural View of the Score Creating a ScoreCookie to Represent a Sequence of Notes 419 Examples ofState-Based Supports in the NetBeans APIs 420 CreatingaScoreSupport 421 Why a Document is Used 421 ImplementationofScoreSupport 422 Lifecycleof theScore 426 AnOpenSupport 426 Creatingan OpenCookieImplementation 427 Showing a GUI View of the ScoreCookie 429 Indicating Parse Errors onthe Node 433 12.CompilingScores What Does NetBeans Meanby “Compilation”? 437 Creatingthe CompilersThemselves 437 Creating and Using theCompiler Cookie 441 Displaying an Out-of-Date Badge on Score Icons 445 13.ExecutingScores Execution Service Types—Internal and External 448 Creating the .au Player Executor 448 TheInternalPlayer 449 TheExternalPlayer 451 Registering the Players as Services 454 Creating Player Configuration Support (ExecSupport) 457 Creating a SystemOption for the Default Executor 461 14. Better Score Support in the Explorer TheClipLengthProperty 467 Clearing the Cache andFiring Changes 469 Adding the Property to the Property Sheet 470 Representing Notes as SubnodesUsing Children.Keys 470 Using Keys to Model Children 471 Being Lazy and Cleaning Up 473 CreatingtheSubnodes 474 Attaching the Children tothe Parent 475 Permitting Subnodes to be Renamed or Deleted 476 DeletionofNotes 476 RenamingofNotes 477 Permitting Subnodes to be Added 479 Making Read/Write Properties on Subnodes 481 ReorderingSubnodes 484 Data Transfer—Cut, Copy, and Paste of Notes and Sequences 489 Overviewof theTransferables 490 CuttingandCopying 491 Pasting 492 Drag&Drop 495 Converting Score # Text, Text # Score, Several Scores # One 495 15. TuningModules for Performance & Memory Footprint Startup Performance vs. Runtime Performance 501 OperatingPrinciples 501 “Nobody Will Ever UseMy Module” 501 What Does My Module Really Need to Do on Startup? 501 What are the Critical Paths? 502 Techniques 503 LazyInitialization 503 AvoidStaticInitializers 503 Avoid ModuleInstall Classes—Use XMLLayers Instead 504 Partial Loading Considerations—InstanceCookie and InstanceDataObject 505 Use URLs Instead of CDATA Sections in XML Layers 505 Reduce the Number of Classes You Create 505 GUIComponents—Wait foraddNotify() 505 Using the addNotify() and removeNotify() Pattern Where Exposed by Non-GUI Classes 506 Use Weak and Soft References for Objects which May Not be Needed Forever 506 UseWeakListener 508 AvoidExcessive EventFiring 508 AvoidOveruse ofThreads 508 BatchingEvents 509 SwingPerformance 509 16. Producing Modules (Packaging& Distribution) Versioning 511 Version Numbers and WhatThey Mean 511 SpecifyingDependencies 512 ManagingInter-ModuleDependencies 513 UpgradingUserSettings 516 Settings History and Physical Format 517 UpgradeScenarios forSettings 518 What Happens When a Module is Disabled? 520 UserDevelopmentData 521 BundlingExtensionLibraries 521 ReferencingLibraries withClass-Path 522 UsingAutoload LibraryModules 523 Ad-Hoc Resources and ModuleInstaller Validation 525 InternationalizationandAccessibility 526 I18NandL10N 526 A11Y 528 JavaHelp—WritingandDistributing 529 Creatinga HelpSet 529 Adding a Help Setto NetBeans 531 AddingContextHelp 534 SeparatingHelp fromCode 535 SupportingUser-Level JavaAPIs 535 Supplyinga ParserDatabase 535 BundlingJavadoc 536 Adding to the Default Classpath 537 Templates 538 BeanInstallation 539 Creating theModule JAR File within the IDE 540 Creating a Build ScriptUsing Ant 540 Producingthe .nbmFile 541 Publishing Using the Update Center 543 Using ErrorManager to Log Problems 545 Testing 547 17. Building Your Distributionof NetBeans Do You Need YourOwn Distribution? 549 Licensing 550 SelectingaBaseline 550 GettingtheSources 551 How to Customize the Build Process to Add Your Modules 552 Adding Modules to a“Stock” Distribution 553 CreatingPreconfiguredSettings 555 Branding 555 Implementing Branding on a Distribution 556 Simple Branding: Text Stringsand Images 557 Configuration Branding: Menu Bar,Workspaces, … 558 AdvancedBranding: PatchingBehavior 564 A. A Tour of Existing Modules to Use and Learn From Modules thatExpose Functionality Your Module Might Need 569 TheXMLModules 569 TheEditor 570 Version Control—the VCS Core Module 570 RemoteFS 571 TheAntModule 571 TheJavaModule 571 DebuggerCore 572 J2EEServer 572 FormEditor 572 HTTPServerModule 572 ClassfileReaderModule 572 The Metadata Repository—a Whole Host of APIs 572 Socket-Based Editor Support—the ExternalEditor Module 573 Incidental APIs, Utilities and Extensions 573 TheUtilitiesModule 573 APIExtensions(openidex) 573 Modules which Make Good Examples for Things You May Need to Implement 574 Annotations and Dynamic Editor Tool Tips—the Ant Module and the Debugger Core Module 574 Adding Information to the View of Java Sources—the Beans Module 574 Adding a Debugger Type—theApplet Module 574 Multiplexing DataObjects,and Complex Cut/Copy/Paste Support—the Properties Module 574 Working with Network Protocols to Access Files—JavaCVS and RemoteFS 574 Domain-Specific XML Support—the Tomcat and Ant Modules 575 Stretching the Limits—the Web Modules 575 Complex Syntax Coloring—the JSP Module 575 Multi-Stage Compilation—the JSP, RMI, and CORBA Modules 575 Bridging to an Entirely Different Build System—the Ant and Makefile Modules 575 Use of the Compiler Infrastructure for Non-Compilation Tasks—the JAR Packager Module 576 Execution—the Applet and JSP/Servlet Modules 576 Custom Hyperlinkingin the Output Window—the Ant Module 576 Specifying Windows, Workspaces and Components Using XML—the Core Window System and the Form Editor Module 576 Complex Work with MIMEResolvers and Multi-File DataObjects—the CPP Module 577 Cut/Copy/Paste—Data Transfer Support for Complex Elements—the Ant and Java Modules 577 Interconversion between Different Types of Clipboard Contents—JNDI, CORBA, and RMI 577 Integrating Other Programming Languages—the C++/Fortran, Scripting, and WebL Modules 577 Fancy Footwork with Nodes—theJava Module 578 Adding Nodes to the Runtime Tab in the Explorer—the RMI, CORBA, JNDI, and Database ExplorerModules 578 The Bare Essentials of Non-Data-Driven Nodes—the System Properties Module 578 Wizards—the CORBA,Java and New Module Wizard Modules 578 Embedding Property Panels into Wizards—the Java Module 578 Complex Explorer Views—the DebuggerCore Module 578 Enabling/Disabling Sets of Actions based on Context—the VCS Core Module 579 B.Useful UtilityClasses XMLUtilities 580 org.openide.xml.XMLUtil 580 org.openide.xml.EntityCatalog 580 Visual Componentsand Extensions to Standard Swing Components 580 LookupImplementations 581 Threading 581 Miscellaneous Utility Classes in org.openide.util 581 SerializationHelpers 582 C.FuturePlans DeclarativeInstantiation 583 UniformLookup 583 DatasystemsII 584 TheLooksAPI 584 DeclarativeActions 585 Deprecation ofIDE-Specific Functionality in the Open APIs 585 TheMetadataRepository 585 Standards Employed by the MDR 586 ProjectSupport 587 D. Working with Open-Sourceand NetBeans Practices 589 Governance 589 Consensus 590 Howto GetInvolved 595 The Lifecycle of Module Development 600 Resources 602 CVS(Concurrent VersioningSystem) 602 Projects 602 MailingLists 602 Issuezilla 603 Interacting Effectively on Mailing Lists 604 E. AdditionalModules and Where to Find Them Open-Source Modules Available via the Update Center 606 The Modules Marketplace on Flashline 606 IDEs thatare Distributions of the NetBeans IDE 608 Open-Source Application Projects Basedon NetBeans 609 Commercial Applications Built on the NetBeans Platform 609 Commercial Modules Available for NetBeans 610 Should You Create Your Own Update Server? 612 Glossary List of Figures 3.1. MultiFileSystem merging constituent filesystems 264 3.2. Module adding XML layer to the system filesystem 265 3.3. Structure of thesystem filesystem 267 3.4. The system filesystem viewed from the Explorer window 268 3.5. Architectural domains underlying nodes 272 3.6. The menu configuration folders in the Options window 274 3.7. The File menu with the Build action added to it 275 3.8. The File menu with a custom executable class added to it 277 4.1. Mappingof files to Java class instances 289 4.2. Mappingfrom files to InstanceDataObjects to lookup 290 4.3. Anatomy of a node 296 4.4.Explorerviews—BeanTreeView 300 4.5.Explorerviews—ChoiceView 301 4.6.Explorerviews—IconView 301 4.7.Explorerviews—ListView 302 4.8.Explorerviews—ListView 302 4.9. A “Pseudo-Windows Explorer” mock-up created using IconView and ContextTreeView 302 4.10.Explorerviews—TreeTableView 303 4.11. Modes, TopComponents and Nodes—anatomy of the Explorer window 307 4.12. NetBeansclass loaders (with three modules installed) 313 6.1.Bean Browser—masterview 326 6.2. BeanBrowser showing list of registered ServiceTypes 328 6.3. Browsing the live window system in the system filesystem 332 7.1.The FileSelectorcomponent 346 7.2. The improved FileSelector component 348 7.3. Thefinal version of the QuickPanel component 356 8.1.Mail filesystem:BeanInfo 370 8.2.Mail filesystem:SelectServerPanel 373 8.3.Mail filesystem:SelectRootFolderPanel 376 8.4. Mail filesystem: IMAP Mail Server template 380 9.1. Mailfilesystem: property sheet of a message 385 9.2. Mail filesystem: raw Filesystems view of a mail server 388 9.3. Mail filesystem: Message Servers in the Runtime tab 393 9.4. Mailfilesystem: relationships among nodes and objects 397 9.5. Mail filesystem: threaded view 399 9.6. Mail filesystem: mail workspace 404 10.1. Minicomposer: editing a score as text 413 10.2. Minicomposer: using the Musical Score template 418 11.1. UML of theScoreSupport lifecycle 426 11.2. Minicomposer: two-way editing of score files 432 13.1. Minicomposer: audio players in Options window 456 13.2. Minicomposer: choosing to use an external audio player 458 13.3. Minicomposer: configuring an external audio player 459 13.4. Minicomposer: selecting the audio player process 460 13.5. Minicomposer: settings displayed in Options window 465 14.1. Minicomposer:parent and child nodes with keys 472 14.2. Minicomposer: ScoreChildren lifecyclestate diagram 474 14.3. Minicomposer: score file with note subnodes 476 14.4. Minicomposer: unrecognized tone dialog 478 14.5.Minicomposer: in-placerename 478 14.6. Minicomposer: add newnote dialog 481 [...]... Different about NetBeans? 250 The Core and the Open APIs 250 TheLicense 251 Open-Source 252 The netbeans. org Web Site 252 NetBeans for Bean Counters 254 Getting and Installing the Open APIs Support Module 255 Life is Change 256 Source code for the examples 256 Who... concentrate on the actual logic The Core and the Open APIs The architecture of NetBeans breaks down into two major sections: The core (also referred to as the application runtime) and the Open APIs The core plus the Open APIs makes up the NetBeans Platform These are represented in the org .netbeans. core.* and org.openide.* Java packages, respectively, in the source code for NetBeans Binary libraries of these... Beans (the beta of NetBeans Developer 3.0 in the summer of 1999 was the first IDE on the market to support EJBs) Take any engineer and show them a specification and they will probably tell you how they could write a better one—it is to the real credit of the developers of NetBeans that they had the discipline to take the long view and use the available standards rather than reinvent the wheel But there... with the Session layer, the directory name may be called nbuser or nbdev, depending on the type of build, followed by the version User directory locations Note that as of NetBeans 3.4, NetBeans user directories live in a netbeans directory off the user s home directory, such as $HOME/ .netbeans/ 3.4dev> For other differences likely to be found in NetBeans 3.4 and later releases, see Appendix C The system... robot But these students weren’t satisfied with any of them They brought this up to their professor—they wanted to design their own project But what would it be? That was the subject of the argument When the dust cleared, they had settled on the ambitious task of building a visual C++ development tool along the lines of Borland Delphi for the X Window System, and named the project Xelfi Over the next... home directory (the folder name is 266 Chapter 3 Understanding the NetBeans APIs nbdev or nbuser and a version number depending on whether the build is a development build or a stable release) On Windows systems, the runide.exe launcher prompts the user for this directory the first time NetBeans is run. [5] The session layer is where things such as window positions, editor colorings and the like are stored—settings... at the activity on the NetBeans mailing lists, and the success that the NetBeans open-source project has had, clearly it was worth it Through heroic efforts on the part of the entire team in the Palmovka office, and with a great deal of help from CollabNet, the company contracted to host the site and provide the server-side infrastructure, we successfully launched netbeans. org in early June of 2000 NetBeans. .. directory NetBeans is installed in The contents of this filesystem are merged with any XML filesystems from modules that are bundled with NetBeans Changes to this layer will propagate to all users using a shared copy of NetBeans 2 Session or User This is the contents of the user s settings directory On Unix systems this might be the nbuserVERSION/system or nbdev/system subdirectory of the user s home... Another useful resource to supplement this book is the mailing list The openide .netbeans. org [http://openide .netbeans. org/] project is where the ongoing evolution of the Open APIs happens, and if you have questions about how to do something or the usage of a particular part of the Open APIs that you cannot find the answer to, the APIs documentation or this book, that is the. .. Today The team that built NetBeans, including Ian and Yarda, are still in Prague, working for Sun on NetBeans while a few members of the original team have moved on, almost everybody who built this tool can be found on the NetBeans mailing lists, working on a project they love, and which for some may be their life’s work The difference now is the many others involved in the project, joining the work . aboutNetBeans? 250 The Core and theOpen APIs 250 TheLicense 251 Open-Source 252 Thenetbeans.org WebSite 252 NetBeansfor BeanCounters 254 Getting andInstalling the Open APIs Support Module 255 LifeisChange. aboutNetBeans? 250 The Core and theOpen APIs 250 TheLicense 251 Open-Source 252 Thenetbeans.org WebSite 252 NetBeansfor BeanCounters 254 Getting andInstalling the Open APIs Support Module 255 LifeisChange. Functionality in the Open APIs 58 5 TheMetadataRepository 58 5 Standards Employed by the MDR 58 6 ProjectSupport 58 7 D. Working with Open-Sourceand NetBeans Practices 58 9 Governance 58 9 Consensus 59 0 Howto