WebLogic Platform ISV Partners' Guide

Creating and Packaging WebLogic Workshop Java Controls

This chapter includes the following topics:

Java Controls Overview

WebLogic Workshop provides Java controls: software modules that give developers the ability to easily connect with existing data, systems, applications, and business logic. Java controls are visual components with methods and properties that meet all of the J2EE requirements governing how connections are made to an external source or piece of business logic. Developers interact with controls by handling events and setting properties.

In addition to the Java controls embedded in WebLogic Workshop 8.1 itself, Workshop 8.1 offers an architecture based on extensible controls. Extensible controls enable developers to create reusable components of business logic as modules that can be integrated with any enterprise resource, ISV application, or piece of business logic. Custom Java controls can leverage native Workshop Java controls. They can also be nested and easily reused. Moreover, any Java control can be incorporated in any project that spans multiple Web services, Web applications, and other WebLogic Platform applications. The process of creating a custom control is primarily one of declaratively specifying control behavior, and then focusing on handling events and calling methods with standard procedural Java code. This process does not require you to learn a new API.

Custom Java Controls and Workshop's Extensibility Model

Custom Java controls play an important role in Workshop's extensibility model, which provides a means for you to enhance Workshop's integrated environment for building Web applications efficiently. Through the Workshop extensibility model, you can enhance this environment to provide support for application and productivity needs that are not yet addressed by WebLogic Workshop.

Ways You Can Extend Workshop's Environment

Workshop's extensibility model encompasses four main areas:

Custom controls that expose complex functionality in simple ways through customizable interfaces, properties, and control-specific user interface components. Controls are used as components of applications built with WebLogic Workshop.
Templates that set up the initial structure for new projects, adding dependencies that might otherwise have to be imported or created, and generating files that help the project's user get started quickly. Templates enhance productivity.
Support for custom JSP tag libraries through tag library extensions that integrate the tags seamlessly with the Workshop design-time environment. Tag library extensions enhance productivity.
Components that augment the IDE with toolbar buttons and menus, views in dockable frames, additional document and project types, editing support for various kinds of source code, source control integration, debugging tools for data views, and so on.

In addition, the extensibility model provides a means by which you can deliver online help that is both specific to your extension and fully integrated with the WebLogic Workshop help system.

For more information about Workshop's extensibility model, see Extending WebLogic Workshop in the WebLogic Workshop Help.

Extensibility Portal

BEA's Extensibility Portal contains the latest updates to the Extensibility Development Kit, (described in Building Advanced Controls), along with updates to the documentation and samples, and other useful resources. Visit the Extensibility Portal at the following URL:

http://dev2dev.bea.com/products/wlworkshop81/workshop_ext.jsp

Note that one valuable resource at the Extensibility Portal of interest to ISVs is the Workshop Controls and Extensibility Program. This program provides a framework for assisting partners in building, testing, distributing, and marketing custom controls and IDE extensions. More more information about the Workshop Controls and Extensibility Program is available at the following URL:

http://dev2dev.bea.com/products/wlworkshop81/ext_overview.jsp

Key Benefits of Java Controls to ISVs

For ISVs, the use of Java controls is beneficial because these controls:

Describe themselves at design time, giving developers a visual representation of server-side business logic in the familiar Workshop development environment
Encapsulate best practices for accessing resources and application logic, ensuring that resources can be used with optimal efficiency
Expose a set of simple properties by which a user can implement advanced run-time functionality, such as asynchronous communication, security roles, lifecycle events, transaction support, and so on. Authors of custom controls have the option of populating the Properties sheet for the benefit of downstream users of the controls.
Make it easy for ISVs to package and distribute them as standard JAR files. Controls can easily be discovered and made available to end users, even before the control JAR files have been completely downloaded. Moreover, because Java controls can be nested, they can easily be re-used. Java controls make it possible to connect to any IT asset, ISV application, or piece of business logic, while protecting the developer's abstraction from most of the complexity of the infrastructure. As a result, developers can largely focus on procedural Java instead of J2EE or other vendor-specific APIs.

How to Make Custom Java Controls Available to End Users

To make it easy for ISVs to deliver custom Java controls to end users, BEA provides the following services and features:

When you create custom controls, you can specify how the controls are displayed on the WebLogic Workshop Insert menu. For example, if you create two or more controls, you may want to group them together in the Insert menu.
WebLogic Workshop tools make it easy to create ZIP files containing all the files, including online help, required for your controls.
BEA hosts the ComponentSource depot, an online facility at the dev2dev Web site, at which ISVs can make their custom controls available to end users for just-in-time downloading.
WebLogic Workshop provides a Help menu item labeled Premiere Component Gallery, which provides a link to the preceding Web site. End users can browse the component gallery to select the ISV controls they want to download.
WebLogic Workshop makes it easy for users who download your controls to install the controls and incorporate online help for them into the WebLogic Workshop help system.

For More Information About Java Controls

For a complete introduction to Workshop controls, see the following topics in the WebLogic Workshop Help:

For the latest samples and documentation updates for building extensions to WebLogic Workshop, visit the Extensibility Portal at the following URL.

http://dev2dev.bea.com/products/wlworkshop81/workshop_ext.jsp

Building Advanced Controls

The Extensibility Development Kit, provided by WebLogic Workshop, includes a package called the Control Development Kit. The latter kit provides tools for incorporating advanced features into Java controls. For example, you might use the tools in the Control Development Kit to make your Java controls highly customizable by end users, or to provide sophisticated property editors that are not required by all applications.

The Control Development Kit includes sample code and documentation that demonstrate, as well as describe, the advanced features of the Java control architecture. Using the samples as a guide, you can build controls with increasingly sophisticated capabilities. For example, your custom controls might:

Define properties that can be mapped to the Properties Editor, which is particularly useful for custom data types
Use a custom control insert wizard, which guides the end control user through the process of adding the control to the application and specifying required properties.
Use a class that you create to validate custom property attributes in both the Property Editor and in source code
Include code that handles specific user actions in the Design View
Handle lifecycle callback events for efficient management of resource dependencies
Include branding information

After you install WebLogic Platform, the Control Development Kit is located in the following directory:

BEA_HOME/weblogic81/samples/workshop/ExtensibilityDevKit/ControlDevKit

For complete details about using the Control Development Kit, see Developing Advanced Controls in the WebLogic Workshop Help.

Note: The Extensibility Development and Control Development Kits are delivered in WebLogic Platform 8.1 Service Pack 2 and later. However, we recommend you visit the Extensibility Portal to obtain the latest versions of those kits, along with the latest samples and updates to the documentation.

Creating Online Help

Depending on the nature or complexity of your control or IDE extension, you may choose to include online help. WebLogic Workshop includes a documentation system that enables you to add new content to support that control or extension. When you follow our guidelines for delivering help, you ensure that your documentation is integrated with the table of contents and search engine for the existing help. If you are delivering controls, you also guarantee that when a user selects your control in Source or Design View, and then presses F1, your documentation is available.

The topic Help Authoring Guide in the WebLogic Workshop Help explains how to do the following tasks for the documentation you provide for your controls and extensions.

Organize the files in your help system
Create individual HTML pages to be added to the help system
Make your help searchable by the built-in WebLogic Workshop online help search engine
Add an index to your help files and list it in the WebLogic Workshop online help table of contents

The Help Authoring Guide includes links to a stylesheet you can use for creating your help files in HTML format, and your table of contents, in XML.

Creating a Control Archive

WebLogic Workshop makes it easy to package two types of custom controls:

Control deliverables—JAR files containing the code that implements the control, along with the help files and sample files for the control
Control stubs—Placeholders for control deliverables that are dynamically downloaded and installed the first time an end user adds them to an application

The following sections describe these two control types in detail.

Control Deliverables

Control deliverables are archive files that contain the top-level directories described in the following table.

Table 5-1 Control Deliverable Directories

This directory . . .	Contains . . .
`controls`	Control implementation archive and any dependency archive JARs
`help`	Documentation and Javadoc for the control
`samples`	Samples that utilize the control

Note that while only a single control implementation JAR can exist in the controls folder, multiple controls may be bundled into that JAR. The first time an end user tries to install your custom control into any application, the control implementation archive and all its dependency archives are copied to the application's Libraries folder.

Once your control implementation files are complete, you right-click the name of the control project folder, then click Build Control Deliverable. WebLogic Workshop collects all the required files into a ZIP file and places that file in the application folder.

For more information about how to package control deliverables, see the following:

The topic Packaging Controls for Installation in the WebLogic Workshop Help
The Extensibility Portal, at the following URL, for the latest documentation updates:

http://dev2dev.bea.com/products/wlworkshop81/workshop_ext.jsp

Control Stubs

Control stubs allow you to make custom controls available to end users without requiring them to install the implementation files for those controls on their machines. Custom controls that can be accessed through stubs are listed on the menu displayed by the Workshop when you choose Insert—>Controls. When an end user selects a control from this menu, the implementation files for that control are downloaded to the user's machine. Thus, the difference between control deliverables and control stubs is transparent to the end user.

With control stubs, you can deliver controls just in time to your end users. As an ISV, you can take advantage of this capability to keep the controls offered at your Web site up to date. Customers who download your controls through stubs are guaranteed to receive the latest versions of your control implementations.

Note: If an end user who has downloaded a control through a control stub later wants a subsequent version, the user must reinstall the control, using the newer version.

For more information about creating control stubs, see "Using Control Stubs as Placeholders" in Packaging Controls for Installation in the WebLogic Workshop Help.