The Visual Editor for Java in WebSphere® Studio Application Developer, hereafter called Application Developer, allows users to create and edit Java™ source files that contain JavaBeans™ components. This article describes a technique that extends the palette of JavaBeans in the Visual Editor for Java allowing the extension of the palette. IBM does not guarantee that the technique described in this article is supported in future releases. All of the classes that make up the palette extension mechanism are in internal packages and IBM reserves the right to withdraw or alter the API allowing access to these classes.

Background

When the Java source file is opened, it is parsed for any recognized patterns of JavaBeans. These are shown in a tree view and on a graphical canvas surface. If the JavaBeans are part of the Abstract Window Toolkit (AWT) or Swing, then they are visually shown on the canvas as they would appear at runtime. You can view and modify JavaBeans properties in the Properties View.

The Visual Editor for Java allows users to build applications using a set of JavaBeans that are included in the palette. These are the common AWT and Swing JavaBeans, such as frames, text boxes, and lists. You can also use other JavaBeans through the ChooseBean dialog.

If you are creating a library of JavaBeans, this article describes how to build a plugin to Application Developer. This plugin extends the Visual Editor for Java's palette to include your classes and contains a wizard that easily configures a Java project.

Back to top

Introduction

This article begins at the point where you have created some JavaBeans and you now wish to create a plugin to deploy them to developers for development. A Java bean sample, com.abc.wizzowidgets.shape , is provided and packaged as follows:

As a Java beans provider, you may not want to separate your code as shown in the provided example. For example, you can include your source code with the runtime in the same jar, and include your BeanInfo classes in the runtime jar in the same package. If you do so, you simplify the creation of the plugin. However, this article uses an example where the files have been packaged separately to show a complex scenario.

This article shows how to:

• Create a plugin so that the user can install the wizzo widgets classes with a single operation and configure the correct attachment of source files and BeanInfo class.
• Extend the palette to add a new category containing the Shape Java bean.

Back to top

Using the plugin files

If you wish to download the completed plugin, it is available. You can download the three jar and zip files separately and create the plugin yourself. The first section of this article shows how to package the files containing the wizzo widgets into a plugin. The second section shows how to test the plugin.

To create the plugin:

1. Creating the plugin directory: Create a plugin that contains the jar and zip files and a plugin.xml file that defines extension points.
2. Defining the container: Use the org.eclipse.jdt.ui.classpathContainerPage extension point in the plugin to specify the name of a container and the wizard that creates it.
3. Specifying the classpath entries for the container: The container wizard needs to know details about how the JavaBeans have been packaged, such as the jar files that contain the classes and any source attachments. These are defined in the com.ibm.etools.jbcf.registrations extension point. The same extension point also references the location of the palette XMI file you can use to add categories to the Visual Editor for Java's palette.
4. Location of the BeanInfo classes: When a JavaBean is running in an end-user application, this is a run-time environment. Within a builder tool, such as the Visual Editor for Java, the JavaBean is running in a design time environment. The JavaBean provides information to the builder tool that makes it easier to use, such as how to display and edit its properties and how to customize it. A JavaBean splits its runtime and design time logic so you can deploy it at run-time, without the need to include the design time code. The design time information is provided in BeanInfo classes. These are usually in a separate jar than the JavaBean. They may be in a different package. The com.ibm.etools.beaninfo.registrations extension point specifies the location of the BeanInfo classes.
5. Extending the palette: Create an XMI file to describe the categories that are added to the palette and the JavaBeans.

Having done the above, the steps required for a user are:

1. Install the plugin in the plugins directory of the user's copy of Application Developer.
2. Change the build path of a Java project so that the user can write classes that make use of your JavaBeans.

Back to top

Creating the plugin directory

WebSphere Studio is built on the Eclipse tools framework, and consists of a series of plugins. Each plugin is a directory that contains a plugin.xml file. The plugin.xml file is known as the plugin's manifest file, and contains XML tags that describe extension points. You can use extension points to add items to toolbars, wizards, preferences pages, and to define new editors. The Visual Editor for Java has a number of extension points that you can use.

1. Create a unique name for the plugin directory so that it does not conflict with other plugins. Plugin names are often named in the same way that a java package is, with your company's URL reversed and a suffix you can guarantee will not be re-used within your organization. For example, if your company URL is abc.com and your JavaBeans package is called WizzoWidgets, name the plugin name as com.abc.wizzowidgets .
2. Create a folder with this name that contains the plugin.xml file and the jar and zip files. To test your plugin as you write it, place it in the plugins directory of Application Developer. When you ship the plugin to your users, this is the same location that they use to take advantage of your plugin. WebSphere Studio has two plugin folders that you can use. One is within the eclipse folder beneath the runtime folder, and the other is within the wstools folder. You can use either of these to create the plugin folder as shown in Figure 1.

The plugin.xml manifest file contains a number of entries. The first set defines details about the plugin itself.

<?xml version="1.0"?>
<plugin name = "Wizzo Widgets" id = "com.abc.wizzowidgets" version = "1.0.0" vendor-name = "IBM">

<requires> <import plugin="com.ibm.etools.jbcf"/> </requires>

The xml version entry specifies which version of the XML parser to use. The plugin tag defines its name and id. The id is unique across all plugins within Application Developer, so most plugin manifest files define their id to be the name of the plugin directory. The version attribute is required, and is a three part number that allows you to manage releases of your plugin. Within Application Developer, each plugin has its own class loader, and each class that is created by a plugin uses the plugin's loader. Use the loader to locate classes and resources. You must define classes that need to be visible to the loader as prerequisite plugins.

The requires tag specifies that the Java beans composition framework plugin, part of the Visual Editor for Java that has the plugin id of com.ibm.etools.jbcf, is a prerequisite of the Wizzo Widgets plugin. The requires statement is similar to a traditional -classpath statement in a java command. Unlike the java -classpath that is scoped across the entire JVM, each plugin class loader has its own distinct set of prerequisite plugins.

When the plugin is shipped, the jar files containing the Shape Java bean and its BeanInfo source are also included. These are in the three files: wizzowidgets.jar, wizzowidgets_src.jar, and wizzowidgets_dt.jar. The jar and zip files are included in the plugin directory. Create a directory called bin that contains the object code for the JavaBeans and the BeanInfo classes as shown in Figure 2.

Create a src directory that contains the zip file with the .java source files as shown in Figure 3.

Back to top

Defining the container

To use the JavaBeans, add a container to the build path of a Java project. To define this, declare the org.eclipse.jdt.ui.classpathContainerPage extension point in the manifest file.

<extension point="org.eclipse.jdt.ui.classpathContainerPage">
    <classpathContainerPage id= "com.abc.wizzowidgets.classpathcontainerpage"
    name="Wizzo Widgets"
    class="com.ibm.etools.jbcf.internal.ClasspathWizardPage:WIZZO_WIDGETS"/>
   </extension>

The name defines the label that the user sees in the Application Developer. In the example, this is hard coded to a single language. However, you can externalize this string into a .properties file. Externalizing a plugin is beyond the scope of this article. For more information, see How to Internationalize your Eclipse plugin.

The class name is the name of the wizard page that appears when the user selects OK. This class is a valid wizard page by implementing the org.eclipse.jface.wizard.WizardPage and org.eclipse.jdt.ui.wizards.IClasspathContainerPage.IClasspathContainerPage interfaces. You may choose to write your own wizard page or use the example, com.ibm.etools.jbcf.internal.ClasspathWizardPage, that is included with the Visual Editor for Java. The ClasspathWizardPage class is an internal package and is an unsupported class that you can remove from future releases of WebSphere Studio. If you are commercially packaging your JavaBeans into a product, create your implementation of IClasspathContainerPage for your particular scenario.

If you are using the generic wizard page, com.ibm.etools.jbcf.internal.ClasspathWizardPage, give the name of the Java variable for the JavaBeans container. This is done by passing the variable name as part of the initialization data for the class by entering it after the class name separated by a colon. For example, class="com.ibm.etools.jbcf.internal.ClasspathWizardPage:VARIABLE_NAME".

Back to top

Specifying classpath entries for the container

The container is transformed so that it does not remain in the classpath, but it is expanded into the individual classpath entries for each external jar containing the JavaBeans. This is may change in a future release so that the user sees a single build path entry for JAVA_BEANS/WIZZO_WIDGETS. The user can remove or re-order it. The expansion into the constituent jar files is done internally by WebSphere Studio when it has to create a JVM. However, in version 5.0, each JavaBeans jar file is added to the build path. A Java variable that is created points to the location of the actual plugin directory on the disk. Each jar entry is defined as an extension of the variable. For example, the WIZZO_WIDGETS Java variable points to C:\WebSphere_Studio_ApplicationDeveloper\wstools\eclipse\plugins\com.abc.wizzowidgets. The class path entry is created for WIZZO_WIDGETS/bin/wizzowidgets.jar.

To determine which jar files to add to the build path, define the com.ibm.etools.jbcf.registrations extension point in the manifest file.

<extension point="com.ibm.etools.jbcf.registrations">
   <variable
     path="WIZZO_WIDGETS"
 palettecats="platform:/plugin/com.abc.wizzowidgets/wizzopalette.xmi">
       <extend runtime="bin/wizzowidgets.jar" source="src/wizzowidgets_src.zip" prefix="src"/>
   </variable>
   </extension>

The com.ibm.etools.jbcf.registrations extension point defines the name of the variable that is also the name of the initialization data passed to the ClasspathWizardPage. A variable is created in Application Developer with this name and used in the build path in the path tag. You can use the extend tag to define the actual runtime jar files that are to the build path. For example, the location of the runtime JavaBeans. The source and prefix attribute are optional and are used to attach the source code to the runtime jar, if required. The two tags are required when wizzowidgets.jar contains the .class files, and the source code is in the wizzowidgets_src.zip file in a directory structure prefixed by src. If the JavaBeans are supplied in more than one jar or zip file, then enter multiple extend tags beneath each other in the extension point. For example:

<extend runtime="bin/wizzowidgets.jar" source="src/wizzowidgets_src.zip" prefix="src"/>
<extend runtime="bin/wizzowidgetsextra.jar" source="src/wizzowidgetsextra_src.zip" prefix="src">

The palettecats extension point points to the location of an XMI file that contains the extensions to the Visual Editor for Java palette. This is covered in Extending the palette.

Back to top

Location of BeanInfo classes

When the Visual Editor for Java performs introspection of JavaBeans, it creates a JVM that it loads with the java.beans.Introspector. The classpath of this JVM is the Java build path of the project combined with any entries in the BeanInfo path. The BeanInfo classes are in a separate jar than the JavaBeans, so you must include wizzowidgets_dt.jar in the BeanInfo path of the project. Instead of the user manually updating the BeanInfo Path of the project, you can automatically update through the com.ibm.etools.beaninfo.registrations extension point.

<extension point="com.ibm.etools.beaninfo.registrations">
  <variable path="WIZZO_WIDGETS">
      <beaninfos>
      <beaninfo kind="plugin"path="/com.abc.wizzowidgets/bin/wizzowidgets_dt.jar">
        <searchpath package="com.abc.wizzowidgets.beaninfo"/>
         </beaninfo>
      </beaninfos>
     </variable>
</extension>

The variable path points to the name of a variable, WIZZO_WIDGETS. When the JVM used for introspection is created, WebSphere Studio searches the Java build path of the project and looks for variable entries. If the WIZZO_WIDGETS variable is found, then the file wizzowidgets_dt.jar in the plugin com.abc.wizzowidgets is in the JVM's classpath. If a variable is found that is an extension of WIZZO_WIDGETS, then this is also used as a match. If the project's Java build path contains WIZZO_WIDGETS/wizzowidgets.jar, then the beaninfo registration for WIZZO_WIDGETS is considered a match and wizzowidgets_dt.jar is added to the JVM's class path. You can also also specify the extension directly in the path, <variable path="WIZZO_WIDGETS/wizzowidgets.jar>, to allow fine grained control over inclusion of the beaninfo jars.

The java.beans.Introspector class that is used to locate the BeanInfo classes for a JavaBean has a search path of packages. These are passed to the introspector through its java.beans.Introspector.setSearchPath(String[] packageNames) method. If the BeanInfo classes are in a different package than the JavaBeans, then you must explicitly give the bean info package to the introspector by using the searchpath tag. The com.abc.wizzowidgets.beaninfo.ShapeBeanInfo is the BeanInfo class for the com.abc.wizzowidgets.Shape JavaBean. You must define the com.abc.wizzowidgets.beaninfo package in the beaninfo registrations extension point for the Introspector to find the ShapeBeanInfo class.

This step, to define a com.ibm.etools.beaninfo.registrations extension point, is not required if there are no BeanInfo classes for the JavaBeans, or if the BeanInfo classes are in the same package and jar as the JavaBeans. For example, if the ShapeBeanInfo class is not in the com.abc.wizzowidgets.beaninfo package, but is included the com.abc.wizzowidgets package, and is included in the wizzowidgets.jar file, no beaninfo registrations extension point is necessary for the introspector to locate the class.

Back to top

Extending the palette

The Visual Editor for Java stores its palette of JavaBeans in an object model that is serialized into XMI. To include your palette entries, use the palettecats= extension point defined earlier that points to an XMI file. The extension point uses the wizzopalette.xmi file, so a file with the same name is created in the plugin folder.

Because the palette represents a serialized object model into XMI, its structure is more verbose than the pure XML used by the manifest file. The best way to create a palette file is to copy some existing XMI into the file, and then change the class name tags as required. For example, copy the file provided in com.abc.wizzowidgets.zip into your plugin, and modify it as needed:

<xmi:XMI xmi:version="2.0"   xmlns:xmi="http://www.omg.org/XMI" xmlns:palette="palettecde.xmi"
xmlns:cdm="cdm.xmi"
  xmlns:utility="utilitycde.xmi">
  <palette:CategoryCmp xmi:id="cat1">
  <categoryLabel xsi:type="utility:ConstantString" xmi:id="string0" string="Wizzo Widgets"/>
       <cmpGroups xsi:type="palette:GroupCmp" xmi:id="group1">
      <cmpEntries xsi:type="palette:AnnotatedCreationEntry" xmi:id="entry1"
icon16Name="platform:/plugin/com.abc.wizzowidgets/icons/shape.gif">
          <objectCreationEntry xsi:type="palette:EMFCreationToolEntry xmi:id="entry1obj"
        creationClassURI="java:/com.abc.wizzowidgets#Shape"/>
      <values xmi:type="cdm:KeyedString" xmi:id="stringname1"
key="com.ibm.etools.cde.nameincomposition"
value="ivjShape"/>
        <entryLabel xsi:type="utility:ConstantString" xmi:id="string1" string="Shape"/>
         </cmpEntries>
       </cmpGroups>
     </palette:CategoryCmp>    
</xmi:XMI>

The palette.CategoryCmp tag defines each category. The above file contains one category. You can include more than one by having new top level palette:CategoryCmp tags. Within the category, its name is defined by the categoryLabel tag that references the class utility:ConstantString whose string attribute is the category name. The example category above is called "Wizzo Widgets". Within each category, there is a cmpGroup that contains cmpEntries . Use these to define each Java bean. The example has only the single shape Java bean so there is one cmpEntries tag. However, you can repeat the tag within the cmpGroups tag. Each cmpEntries tag is an instance of the palette:AnnotatedCreationEntry class that contains the icon and class name.

The class name of the Java bean is defined as the creationClassURI of the palette:EMFCreationToolEntry objectCreationEntry class. This is the java:/packagename#classname: form. For the Shape class, it is java:/com.abc.wizzowidgets#Shape.

When the user selects a palette entry and drops it in the Visual Editor to create a JavaBean, a field is created. For a visual JavaBean, the field name is the class name appended with a number that makes it unique within the Java file. The com.abc.wizzowidgets.Shape class is visual because it inherits from java.awt.Canvas so its field name is called shape1 . Subsequent field names for JavaBeans are called shape2, shape3, and so forth.

Because of the parsing rules used by the Visual Editor, all fields that represent non-visual JavaBeans must begin with ivj. The ivj prefix is a switch indicating that they are included in the graphical canvas and the tree view. To specify the name of a non-visual JavaBean that is part of a palette cateogory, define a (E>) <values tag that is a cdm:KeyedString with a key of com.ibm.etools.cde.nameincomposition. The wizzopalette.xmi file includes a <values tag to show the syntax. Because Shape is a visual JavaBean, this is ignored.

The name that appears on the palette is defined by the entryLabel tab, which is a constant string whose string attribute is used.

The icon16Name= tag specifies an attribute of the cmpEntires tag itself. If you get a red square instead of an icon, this means that the graphic did not load correctly. The Shape class is icon16Name="platform:/plugin/com.abc.wizzowidgets/icons/shape.gif". In the plugin directory, there is a folder icon that contains the shape.gif file.

If you do not have a custom icon provided for your JavaBean, you can use the default bean icon by setting the attribute to icon16Name="platform:/plugin/com.ibm.etools.jbcf/icons/bean16.gif". Note that if your JavaBean has a BeanInfo class that returns an icon from its public java.awt.Image getIcon(int iconKind) method, this is not used by the Visual Editor for Java. You must define an icon16Name= tag to get the icon included in the palette.

Back to top

Installing the plugin

To allow the user to use your plugin, the user copies the com.abc.wizzowidgets directory into the plugins directory of their copy of Application Developer. When Application Developer first starts, it reads every plugin.xml contained in folders within the plugins directory. The extension points define the rules for the WIZZO_WIDGETS container.

Back to top

Using the WizzoWidgets plugin

Each .java source file within Application Developer is created within a Java project. The scope of available classes that a Java file can reference is defined by its project's build path. To use the WIZZO_WIDGETS plugin for a Java project, the user changes its build path by opening the project's properties and selecting Java build path. The Libraries tab of the build path page allows the build path to be changed.

To configure the project to include the Wizzo Widgets JavaBeans, the user clicks Advanced and selects the Add Container radio button. The Wizzo Widgets entry defined in the manifest file appears in the list. The user selects it and clicks OK.

The ClasspathWizardPage reads the extension point from the manifest file that defines how the container has been packaged. The user can see details of the Java variable that is created, the jar files that are added to the build path, and the entries that are included in the palette.

After clicking Finish, the ClasspathContainerWizard adds a container to the build path. The name of the container is JAVA_BEANS, extended with the name of variable, such as JAVA_BEANS/WIZZO_WIDGETS. Because the container is defined as pointing to a number of jar files in the com.ibm.etools.jbcf.registration extension point, the class path is modified further so that the individual jar files are added. The individual jar files are specified by extending the definition of the Java variable, so the WIZZO_WIDGETS variable is a container, which points to the runtime directory in the location of the plugin directory. The wizzowidgets.jar file is defined as an extension to the variable.

When the user opens the Visual Editor for Java, the categories defined in the XMI file are added to the top of the palette. The user can select the JavaBeans and drop them onto the canvas without having to use the Choose Bean dialog.

Back to top

Checking for errors

If there are any problems with your plugin, such as not appearing in the list of containers for the project, you may have errors in the plugin.xml file. Application Developer writes these errors in the .log file in the .metadata directory. For example, if you forgot to include a version attribute in the plugin tag, you have the following errors in the .log file:

!MESSAGE Version attribute missing from plug-in or fragment at
"file:C:/WebSphere_Studio_Application_Developer/eclipse/plugins/com.abc.wizzowidgets/plugin.xml".

If you forgot to put a closing > after a tag name, the error message is:

org.xml.sax.SAXParseException: The end-tag for element type "extension"
must end with a '>' delimiter. 
!MESSAGE Error while processing "file:C:/WebSphere_Studio_Application_Developer/wstools/eclipse/ 
plugins/com.abc.wizzowidgets/plugin.xml".

You may have errors in the LoggingUtil file in the .metadata directory. Check for errors by browsing the log and LoggingUtil files.

Back to top

Conclusion

This article shows how you can package JavaBeans into a plugin that allows your users to easily update a project's build path. This also automatically updates all underlying configuration of source attachment and BeanInfo Path details. In addition, you can extend the palette on the Visual Editor for Java by the plugin with new categories that include your JavaBeans. Your users can easily drop them onto the canvas and begin working with them.

Disclaimer: The API described in this article is experimental and is part of WebSphere Studio Application Developer 5.0. It is expected that the process of extending the palette and creating plugins that contain JavaBeans will improve in a future release of Application Developer, and as such IBM undertakes no guarantee to support or maintain the extension points. The JavaBeans supplied with this article are for illustrative purposes only and should be used accordingly. All of the software supplied with this article is provided on an "AS IS" basis and to the maximum extent permitted by applicable law, IBM provides the software as is and with all faults, and hereby disclaims all other warranties and conditions, either express, implied or statutory, including, but not limited to, any (if any) implied warranties, duties or conditions of merchantability, of fitness for a particular purpose, of accuracy or completeness of responses, of results, of workmanlike effort, of lack of viruses, and of lack of negligence, all with regard to the software.

Back to top

Resources

Comparing WebSphere Studio Application Developer with VisualAge for Java -- Part 3: Using the New Visual Editor

Top of page

Back to top

Download

Name	Size	Download method
com.abc.wizzowidgets.zip	.8 MB	FTP|HTTP

Information about download methods

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Background
• Introduction
• Using the plugin files
• Creating the plugin directory
• Defining the container
• Specifying classpath entries for the container
• Location of BeanInfo classes
• Extending the palette
• Installing the plugin
• Using the WizzoWidgets plugin
• Checking for errors
• Conclusion
• Resources
• Download
• About the authors
• Comments

Next steps from IBM

Spring, JRuby, and Ajax development is easier with WebSphere Application Server - a smart Java 5 and J2EE Web services-based application server.

---

• Try: The no-charge WebSphere Application Server Community Edition is a pre-integrated, lightweight Java 5 application server built on Apache Tomcat and other best-of-breed open source software such as OpenEJB, Apache Axis, and Apache Derby.
• Article: The article leverage the Spring Framework and the WebSphere Application Server to improve your J2EE project productivity.
• Tutorial: See how the free WebSphere Application Server and XML can improve the efficiency of your JRuby on Rails and Ajax development.
• Buy: WebSphere Application Server - Express

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers