JBuilder OpenTools introduction

General description

JBuilder is designed to be an extremely open, extensible product. The concepts introduced in this document describe the basic organization of the product and some of the basic terminology necessary to get started. Links from this introduction to the detailed documentation for each subsystem will get you directly to the information you need to tailor the JBuilder environment.

PrimeTime vs. JBuilder

Packages in JBuilder start with com.borland.primetime or com.borland.jbuilder and most subsystems have classes in both parallel packages split between the two. Why the unusual organization? Because JBuilder was designed as a very flexible IDE, with everything necessary to provide general IDE-style support in the primetime packages, and behavior specific to editing Java code in the jbuilder packages.

Once you get used to the split personality, the organization is actually quite logical and well structured. The primetime packages define very general-purpose behavior, and never depend on anything in the jbuilder packages.

Architectural overview

Legend

Core
JBuilder's Core subsystem manage OpenTools, collections of files, and projects that underlie the user interface.
Browser
The general Browser user interface provides a framework for interacting with projects and files.
Viewers and Editors
The specific source code Editor and visual Designer subsystems provide a rich set of end user tools for manipulating Java code. Each of these subsystems is extensible in its own way.
Common Processes
The default JBuilder configuration knows how to compile and run basic Java projects, but the subsystems that manage the Build and Runtime processes are extensible to allow the default behavior to be further tailored.
Code Generation
While the source Editor allows direct manipulation of Java files, automated code generation is also available in JBuilder. The Wizard Framework provides a common look and feel for wizards, and JOT provides the infrastructure necessary to read, alter, and regenerate source code.
User Experience
JBuilder users become accustomed to a standard look and feel for the environment that is supported by a variety of additional libraries.

The Core

The Core subsystems in JBuilder provide functionality that is available to command-line tools as well as extensions to the full-blown graphical IDE.
 
OpenTools Loader
Documents: Concepts
Packages: com.borland.primetime
Classes: Command, PrimeTime The OpenTools Loader is a critical mechanism that all OpenTools authors need at least a passing familiarity with. The loader is responsible for discovering all extensions to the JBuilder IDE and initializing them when the product is launcher. The loader is also responsible for parsing the command-line. Objects that implement the Command interface can be registered with PrimeTime to provide this command-line behavior.
 
Virtual File System (VFS)
Packages: com.borland.primetime.vfs
Classes: VFS, Filesystem, Url, Buffer The Virtual File System in JBuilder provides seamless access to a number of different storage techniques, each defined by an implementation of the Filesystem interface. The contents of entries in Zip files, physical files, and New "untitled" documents are provided as three Filesystem implementations in the core VFS implementation.

Much as File instances are used in Java to represent filenames, logical files in the VFS are identified using instances of a special Url class (note that this is different from the java.net.URL class.) All virtual file manipulation is done through static methods on the VFS class and passing one or more Url instances as parameters.

The VFS also supports an in-memory representation of a file as an instance of the Buffer class. Buffers can be hold changes before being discarded or written to disk, and while a buffer exists all VFS operations treat the contents of the buffer as the "current" state of the virtual file.

Node System
Packages: com.borland.primetime.node, com.borland.jbuilder.node
Classes: Project, JBProject, Node, FileNode, LightweightNode, ProjectStorage The Node System provides the infrastructure for managing JBuilder projects. All projects are instances descending from the generic PrimeTime Project class, and most projects in a JBuilder environment will actually be instances of the JBProject subclass. The project manages a hierarchy of individual Node objects, typically either FileNode objects that represent a file in the Virtual File System, or LightweightNode objects that represent logical concepts such as folders and packages.

The Node System provides a way to associate any number of property values with each Node in a project. Lastly, ProjectStorage implementations to be registered to read (and optionally write) foreign project file formats.

The Browser

The Browser is the metaphor used by the graphical IDE to display a workspace that allows the user to manipulate projects and the contents of individual files within a project. Each section of the browser is described briefly below, with the relevant portion of the user interface highlighted in cyan.

Keep in mind that JBuilder supports displaying more than one browser at a time. All of the components described below are present in each browser window, each of which maintains its own state. Methods that register new behavior affect all browser windows simultaneously.

Action Framework: Menus and Toolbars 
Documents: Concepts
Packages: com.borland.primetime.actions
Classes: UpdateAction, BrowserAction, StateAction, DelegateAction, JBuilderToolBar, JBuilderMenuBar, ActionToolBar, ActionMenuBar The main menu and toolbar in JBuilder are constructed dynamically from collections of Swing Action objects. The standard menu and toolbars can be extended with new Action objects, and new user interface additions can incorporate additional Action-based menu and toolbars.

JBuilder makes extensive use of several convenient Action subclasses that offer more features and flexibility than the basic Swing Action:

Message View
Documents: Concepts
Packages: com.borland.primetime.ide
Classes: MessageView, MessageCategory, Message The Message View in JBuilder automatically appears when content is added to it in order to communicate with the user. Content is organized into groups, each group visible as a tab at the bottom of the message area. Tabs can be created which organize simple messages into lists or hierarchies, or tabs with complex user interfaces may be created by defining a custom component.

The user has control over removal of tabs and may hide the entire message view at any time.
 

Project View
Documents:Concepts
Packages: com.borland.primetime.ide
Classes: ProjectView The Project View reflects the state of the active project, representing visually the information available through the Node System including the "display hierarchy" of nodes, their display names and icons. Most interaction with the project view happens indirectly by defining new node types or modifying the node hierarchy through the Node System.

A ProjectView instance can be queried for the currently active project and the currently selected nodes. The list of open projects is also available, but is shared among all project views. Lastly, the context menu available on the project view can be directly influenced by registering ContextActionProvider objects with the ProjectView class.

Status View
Documents: Concepts
Packages: com.borland.primetime.ide
Classes: StatusView The Status View displays a single message that can be replaced on demand. Informative messages about the last user action are typically displayed here.

The status bar will display long descriptions for toolbar buttons and menu items are

Longer messages, messages that the user must be guaranteed to see and respond to, and messages that the user needs to interact with should use the Message View facility instead of the Status View.

Content Manager
Documents: Concepts
Packages: com.borland.primetime.ide
Classes: Browser, NodeViewer, NodeViewerFactory The Browser manages the set of open file through the Content Manager. While OpenTools cannot replace the ContentManager, they can register viewer tabs through a static Browser method.

Each viewer tab is registered as a NodeViewerFactory. The factory evaluates whether or not its viewer type is available for a given node.

For available viewers, the factory constructs a NodeViewer implementation. The viewer instance provides the tab name and creates a pair of JComponent instances: one for the structure pane, and one for the content area.

Viewers and editors

Several standard viewers and editors are automatically registered with the Content Manager in JBuilder. The source code editor, visual designer, image viewer, HTML viewer, BeansExpress, and JavaDoc viewer are all examples of standard viewers included with the product. Two of these are noteworthy because they can, in turn, be enhanced by other OpenTools.
 
Source Editor
Documents: Source Editor concepts, Keymapping Concepts
Packages: com.borland.primetime.editor
Classes: TextFileNode, Scanner, EditorActions The Source Editor in JBuilder is automatically displayed for decendants of TextFileNode. Each individual node can provide its own syntax highlighting with a Scanner implementation, a unique structure pane, and a CodeInsight implementation.

The editor can also be customized at a global level by registering new user-selectable keymappings, each of which can borrow freely from our existing collection of actions implemented in EditorActions.
 

Visual Designer
Packages: com.borland.jbuilder.designer
Classes: JavaFileNode The Visual Designer in JBuilder is displayed for descendants of JavaFileNode. It provides a full JavaBean assembly environment that can be extended in a number of ways. The most obvious is that property editors and customizers included with JavaBeans are automatically exposed through the designer.

Less obvious ways of extending the Visual Designer include:

Standard processes

Build System
Packages: com.borland.primetime.build, com.borland.jbuilder.build The Build System is responsible for scheduling a series of tasks when the user requests a compile or rebuild operation. Each task is then invoked in turn and may report errors or warnings that are accumulated on the compile tab of the message view. OpenTools can inject tasks into the build process based on the type of nodes selected for the compile.

Note: While there is currently an OpenTools API in place for the build system, we expect to replace this design in a future version of JBuilder. The available documentation is extremely limited in part due to our intention to introduce an incompatible system.
 

Runtime System
Packages: com.borland.primetime.runtime, com.borland.jbuilder.runtime
Classes: Runner, JavaRunner, RuntimeManager Projects in JBuilder can be configured to run in one of a variety of ways using either the Run tab of the Project Properties dialog (or the Configurations dialog under the Run menu in the Professional and Enterprise editions.) The available runtime configurations are registered with a RuntimeManager as implementations of the Runner interface. Each Runner provides a name, a configuration panel, and behavior for running and debugging.

Most custom runners will want to share the standard Java runtime and debugging framework. The class JavaRunner provides a Runner implementation that can be subclassed and customized. An application and applet runtime are installed by JBuilder, and an additional JSP runtime is added by the Enterprise edition. These all use a standard runtime and debugging framework.

Debugger

The Java debugger cannot be directly customized, but any custom runtime that uses the standard debugging framework can take full advantage of the debugger.

Manipulating Java code

Wizard Framework
Documents: Concepts
Packages: com.borland.primetime.wizard
Classes: BasicWizard, BasicWizardPage, WizardManager The JBuilder wizards all share a common look and feel courtesy of the Wizard Framework. This framework can be used to create multi-page wizards by subclassing BasicWizard to provide one or more BasicWizardPage subclasses, and registering the resulting wizard instance with the WizardManager.
Java Object Tool (JOT)
Documents: Temporary JavaDoc
Classes: JBProject JOT is the core of our unique two-way design tools, providing a full parsing and code generation engine. In some ways it acts like Java reflection for source code, but with a full API for making modifications. Those familiar with the Document Object Model for XML should feel right at home with the basic concepts.

JOT can be used in a read-only fashion, in which case it can operate on either source code or class files. It can also be used to generate new source files, a facility used by many of the standard JBuilder wizards. The true power of JOT lies in making precise modifications to existing code, preserving existing formatting and comments exactly while making exacting changes to any aspect of the source code. This facility is used by JBuilder's visual designer, by BeansExpress, and by some of the more powerful wizards. JOT's full functionality is also available to OpenTools.

Note: The JavaDoc for JOT was inadvertently omitted from JBuilder 3 Foundation and JBuilder 3.5. An early draft of the JOT JavaDoc is linked here but not yet integrated into the full OpenTools JavaDoc set.

The user experience

Properties System
Documents: Concepts
Packages: com.borland.primetime.properties
Classes: Property, PropertyGroup, PropertyManager, PropertyPageFactory, PropertyPage The Properties System provides a standardized way of reading and writing user preferences. Each setting is represented by an instance of a Property subclass, where different subclasses manage different kinds of storage and provide default values for the property.

Users typically interact with properties through pages on property dialogs. Registering a PropertyGroup with the PropertyManager gives your OpenTool a chance to provide a PropertyPageFactory whenever a property dialog is displayed for a given topic. Topics can include global properties, properties associated with subsystems such as the editor, and individual projects and files.

Help

The JBuilder help system uses an HTML browser and an indexing scheme based on JDataStore technology.

Note: OpenTools will allowed to integrate with the JBuilder help system in a future release, including the ability to update help indexes.
 

Utility Classes

There are a variety of utility classes included in JBuilder that can help OpenTools maintain a consistent look and feel. The simplest is to ensure that all tree controls in your OpenTool descend from SearchTree to enable the "type-to-search" mechanism.