Sun Java Studio Creator Design-Time
Total Page:16
File Type:pdf, Size:1020Kb
Sun Java™ Studio Creator 2 Design-Time API User Guide (for component authors) Joe Nuxoll Sun Microsystems Version: 2.0 August 15, 2005 Java Studio Creator Design-Time API User Guide Table of Contents 1 – Introduction 1.1 – Definitions 1.1.1 – Component 1.1.2 – Component Model 1.1.3 – JavaBean Component and JavaBeans Component Model 1.1.4 – Component Library 1.1.5 – Component Author 1.1.6 – IDE (Integrated Development Environment) 1.1.7 – IDE Vendor 1.1.8 – Application Developer 1.2 – JavaBeans 1.0 Extensions Provided by CDT 1.2.1 – Design-Time Context 1.2.2 – Generation of Persistence 1.2.3 – Manipulation of Hierarchy 1.2.4 – Rich Mouse Interaction 2 – The Java Studio Creator Design-Time API 2.1 – General Model and Hierarchy 2.1.1 – DesignProject 2.1.2 – DesignContext 2.1.2.1 – MarkupDesignContext 2.1.2.2 – FacesDesignContext 2.1.3 – DesignBean 2.1.3.1 – MarkupDesignBean 2.1.3.2 – FacesDesignBean 2.1.4 – DesignProperty 2.1.4.1 – FacesDesignProperty 2.1.5 – DesignEvent 2.2 – Access and Hook Points 2.2.1 – DesignInfo 2.2.1.1 – MarkupDesignInfo 2.2.1.1.1 – MarkupRenderContext 2.2.1.1.2 – MarkupMouseRegion 2.2.1.2 – MarkupTableDesignInfo 2.2.2 – PropertyEditor2 2.2.3 – Customizer2 2.2.4 – DisplayAction and DisplayActionSet 2.2.5 – Result 2.2.5.1 – ResultMessage 2.3 – Extended Metadata 2.3.1 – Additional BeanInfo Attributes 2.3.2 – Additional PropertyDescriptor Attributes 2.3.3 – Additional EventDescriptor Attributes 2.3.4 – Context Data Attributes 3 – Examples and Use Cases 3.1 - Example: Providing Extended BeanInfo Metadata 3.2 - Example: Providing Custom Right-Click Context Items 3.3 - Example: Using beanCreatedSetup Method to Setup Initial State 3.4 - Example: Creating a Customizer2 Dialog 3.5 - Example: Using a PropertyEditor2 to Scan Design Context 3.6 - Example: Interaction With the User Via a Result Object Java Studio Creator Design-Time API User Guide 1 – Introduction This document is for component authors that want to provide a better design-time experience for their users, developers using Sun Java™ Studio Creator Integrated Development Environment (the IDE). This document outlines the concepts, APIs, and use-model of the Java Studio Creator Design-Time API (CDT), which is the rich design- time interaction API hosted by Sun Java Studio Creator. The CDT provides component authors with access to the rich design-time interactions available in the visual design environment. Via this API, a component author can create a rich design-time experience for users of their components. This includes mouse interactions (drag/drop/link), custom context menus, custom rendering, as well as context-aware customizers and property editors. The CDT is closely coupled with the JavaBeans™ API – and extends this API to better handle design-time manipulation of live component objects in a visual design environment. 1.1 – Definitions A clear understanding of the following definitions is essential to understanding this guide. 1.1.1 – Component – A Java class that is used as a functional building block in a modern software application. A component has properties, methods, and events (PME). Properties can be manipulated at design-time and runtime, and affect the settings and behavior of the component. Methods can be invoked at runtime to make the component do things, and are also referred to as operations. Events are runtime messages broadcast by a component during its lifecycle, indicating that its state has changed in some way. A component’s events can be hooked by an application – thus invoking application-specific code. A component can be visual (like a TextField or a TreeControl) or non- visual (like a Connection or a Timer). Components can exist on the server or on the client. Sometimes, the term control is used in place of component, but the term control often implies a higher-level client-side component. Author’s aside: Components simplify learning how to build an application by allowing the application developer to learn the features of a software platform piece by piece – while employing the same development model (setting properties and hooking events). Instead of having to learn a new OO-based API for each new platform technology they might need to leverage, the developer can focus on one component at a time, and just learn how to use each one as they go along. 1.1.2 – Component Model – The rules for defining a component on a particular software platform. A component model includes patterns and/or language syntax for declaring the properties, methods, events (PME), and the interaction lifecycle of a component. A component model also defines the design-time interfaces that an IDE or a developer uses to manipulate a component. A software platform’s “component model” API typically defines the primary development model / methodology that a developer uses to build applications. 1.1.3 – JavaBean Component and JavaBeans Component Model – The Java Platform’s version of component and component model. A JavaBean is a component in the Java Platform. The JavaBeans Component Model (or simply JavaBeans) is the prescribed component model for the Java Platform. 1.1.4 – Component Library – A collection of components usually supplied by the same vendor, and designed to work together seamlessly. For example, Swing is a component library. 1.1.5 – Component Author – A company, group, or individual that is responsible for implementing and making available components or component libraries. Component authors leverage the Java Studio Creator Design-Time API to supply greater value with their components. 1.1.6 – IDE (Integrated Development Environment) – An IDE is a software program that is designed to aide in the creation of other software programs. An IDE typically includes a text-based source code editor, an integrated compiler, and debugging and profiling functionality. Modern IDEs also include a visual design environment for drag and drop creation of visual and non-visual applications, as well as fully context-sensitive code completion and refactoring in the editor. Sun Java Studio Creator software program is an IDE. 1.1.7 – IDE Vendor – This is simply a company, group, or individual that is responsible for implementing and making available one or more IDE products. Sun Microsystems is an IDE Vendor. 1.1.8 – Application Developer – An individual that uses an IDE to build an application. This person uses standard components, and might purchase 3rd party components to help them assemble applications quickly and simply. 1.2 – JavaBeans Extensions Provided by CDT The JavaBeans Component Model specification covers most of the requirements for defining a component in Java. A component author can declare and document properties, methods, and events, as well as most of the critical design-time metadata that describes a JavaBean component. The specification also covers a lot of design-time manipulation details, such as PropertyEditors, Customizers, and so on. One place where JavaBeans stands out from other component models is the strict separation of design-time vs. runtime. With JavaBeans and the Java Studio Creator Design-Time API, it is possible to create a rich design-time experience for a developer without sacrificing any runtime performance or incurring additional deployment overhead. CDT keeps true to this strict separation. CDT makes it possible to perform a number of common design-time tasks that are not possible with the standard JavaBeans 1.0 design-time APIs, as described in the sections that follow. 1.2.1 – Design-Time Context It is common to see a visual, data-aware control with two data-binding properties: for this example, a data-aware DbTextField with a rowSet property (of type javax.sql.RowSet), and a columnName property (of type java.lang.String). At design-time an application developer first sets the rowSet property. Typically, this will be done by clicking the DbTextField to select it in the Visual Editor, then choosing the rowSet property in the property sheet, then selecting a RowSet instance name from a drop-down list of RowSet instance names on the page being designed. Once the developer has set the rowSet property, they click the columnName property, and select a column name from the drop-down list of column names in the previously set RowSet instance. Though it seems simple, none of this can be done with standard JavaBeans APIs. With these APIs, a PropertyEditor is only passed the instance of the property value to edit. For the rowSet property, an instance of a RowSet (or null) would be passed to the PropertyEditor.setValue(Object) method, and there would be no way to obtain a list of RowSet instances on the page to display to the user. When the columnName property is set, a String (or null) is passed to the PropertyEditor.setValue (Object) method, and the PropertyEditor is only passed the characters of the String itself. The PropertyEditor does not know that the property value represents a column name on a component that also has a rowSet property that might or might not be set. This missing information is called design-time context. With the Java Studio Creator Design-Time API, it is trivial for a component author to access the live component that owns the property being set, and query its rowSet property to see if it is currently set, and then get the correct SQL metadata to provide a list of column names to display to the user. It is equally trivial to query the context of the component being designed to get a list of instances variables that satisfy a particular interface or ancestry constraint, like showing a list of RowSet instances available on the page. 1.2.2 – Generation of Persistence An IDE has to be able to persist everything that a user does in the Visual Editor.