Tools Guide

Chapter 1   Workbench Basics

SilverStream eXtend Workbench is an extensible IDE for developing and deploying J2EE and Web Service applications. Workbench automates and simplifies many tasks associated with J2EE and Web Service development, including creating and maintaining J2EE archives, populating and editing XML deployment descriptors, and deploying archives to a J2EE server.

This chapter introduces the Workbench tools and facilities. It describes how to perform basic operations such as opening files, setting preferences, setting profiles, and using version control. It includes the following sections:

• What Workbench provides

• Workbench panes

• Basic Workbench operations

• Workbench wizards

• Standard Workbench editors

• Workbench viewers

• Web Service tools

• Setting preferences

• Setting Workbench profiles

• Using version control

• Maintaining Todo lists

• Specifying a debugger

• Using Ant

• Internationalization support

• Extending the Workbench toolset and services

    For more information about performing project-level operations, such as creating a project, adding files to a project, building a project, and creating an archive, see Chapter 2, "Projects and Archives".

What Workbench provides

Workbench is a file-system based development environment that provides:

• Component wizards to help you create J2EE components such as JSP pages, EJBs, servlets, Java classes, JavaBeans, and tag libraries

• Web Service facilities including a wizard for creating Java-based Web Service components, a SOAP runtime environment, and a Registry Manager for searching and publishing to Web Service registries

• Graphical and text-based editors for working on Java files, JSP files, XML files, WSDL documents, deployment descriptors, and plain text files

• Project views that show the structure of a project's source files and the structure of a project's generated archives

• Project tools for building projects, creating and validating J2EE archives, and deploying archives to J2EE application servers

• Version control integration that provides access from Workbench to your version control system

Server independence   Workbench is server-independent. When working on projects, you can create source files, build your project, and create archives all within Workbench, without any application server support. You do not need to run an application server until you are ready to deploy your project archives.

You can deploy archives built in Workbench to any J2EE-compatible application server. Workbench provides automated deployment to leading application servers, including SilverStream eXtend Application Server, BEA WebLogic, IBM WebSphere, Jakarta Tomcat, and Oracle9i. See the Release Notes for information about supported versions.

Workbench panes

Workbench consists of three resizable panes: Navigation, Output, and Edit. This section describes how to use these panes when creating projects.

The Navigation Pane   The Navigation Pane lets you access various aspects of projects and registries. For example, the Project tab lets you view and select files from the source and archive directory structures.

At the base of the Navigation Pane are three tabs: Directory, Project, and Registries. When either the Project or Directory tab is selected, the Navigation Pane consists of two subpanes: the top one shows the directories and the bottom one lists the files in any directory that you select.

• The Directory tab lets you access files from the file system

• The Project tab shows the directory structure of source and archive layouts

• The Registries tab lets you browse and publish to Web Service registries

Here's how it works:

TIP   You can see a file's complete name and path by positioning the mouse pointer over it in the lower subpane of the Directory or Project tab. Workbench tool tips are particularly useful in the Archive Layout or Archive Contents view of the Project tab for comparing a file as it conceptually exists in the archive (such as WEB-INF/web.xml) to its file system name (such as C:\dev\proj4\web.xml).

Edit Pane    The Edit Pane is the file editor work area. It displays the contents of any file you have opened. You can use View menu items to hide the Output and Navigation Panes to give you additional work area.

Output Pane   The Output Pane contains tabs that display information from any of the following processes: build, validate, deploy, find, and version control.

Status bar   The status bar displays messages, such as when a file is saved.

About dialog   Use the About dialog (Help>About Workbench) to check version information for Workbench and its components (editors, wizards, viewers, and so on). This dialog shows you what is installed in the product version you are running and which components have been individually revised.

Basic Workbench operations

This section tells you about:

• Starting and stopping Workbench

• Using proxy servers

• Opening, saving, and closing projects and files

Starting and stopping Workbench

Start Workbench using the appropriate command on your operating system, such as the Windows Start menu (Programs>SilverStream eXtend>Workbench).

Select File>Exit to exit Workbench.

Using proxy servers

If you are using a proxy server, you need to specify the proxy host and its port in xwb.conf, which is in the Workbench bin directory. Uncomment the following lines and specify your site's values.

  vmarg -DsocksProxyHost=proxy-host
  vmarg -DsocksProxyPort=proxy-port-number
  vmarg -Dhttp.proxyHost=proxy-host
  vmarg -Dhttp.proxyPort=proxy-port-number

If there are hosts that don't require a proxy, you can specify them (separated by |) with this property:

  vmarg -Dhttp.nonProxyHosts=host1|host2...

Opening, saving, and closing projects and files

This section describes how to work with project files and source files in Workbench:

• Working with project files

• Working with source files

• Performing file system operations

    For details about working with projects, see Chapter 2, "Projects and Archives".

Working with project files

To work on an existing project, open its project file. Workbench project files have the extension .SPF (for SilverStream project file).

To open a project file:

1. Choose File>Open Project. A file selection dialog appears.

2. Navigate to the project's SPF file.

3. Select the SPF file and click open (or double-click the SPF file). Workbench displays the project in the Project tab of the Navigation Pane.

   You cannot have multiple projects open (though you can work with multiple subprojects of an open project). If you have a project open and then open another unrelated project, Workbench closes the original project and any associated files before opening the second project.

Alternatively, you can:

1. Navigate to the project file in the Directory tab in the Navigation Pane of Workbench.

2. Either double-click the file or right-click it and then choose Open File in the popup menu that appears.

If you have opened the project file recently, you can also select it from the list under File>Recent Files.

To save a project file:

No action is needed on your part to save a project. Whenever you modify the project contents or settings (for example, by adding a directory to the project), the project file is saved automatically.

The project file must be writable before you can make changes to the project in Workbench. Typically, this means that you must check out the project file from your version control system.

To close a project file:

• Choose File>Close Project.

Working with source files

This section describes how to open, save, and close source files, such as Java, JSP, XML, and plain text files.

To open a source file:

1. Choose File>Open.

   A file selection dialog appears.

2. Navigate to the source file.

3. Select the file and click Open (or double-click the file). Workbench displays the file in the appropriate source file editor (Java, JSP, XML, or Text) in the Edit Pane.

Alternatively, you can:

1. Navigate to the file in the Directory tab in the Navigation Pane. If you have a project open and the file is included in that project, you can find it in the Project tab as well.

2. Either double-click the file or right-click it and choose Open in the popup menu that appears.

If you have opened the file recently, you can also select it from the list under File>Recent Files.

Working with open files   One file is active at a time. By default, there is a tab for each open file in the Edit Pane. Simply click a tab to make that file active. (You can customize and turn off the display of tabs. See Display preferences.)

You can also make an open file the active file by selecting Documents>More Documents and selecting the file from the list of open documents

To save a source file:

• Choose File>Save.

File>Save As enables you to save the contents of the currently open file to another file.

TIP   You can also save a file by right-clicking its tab in the Edit Pane.

To close a source file:

• To close the currently selected source file, select File>Close or click the Close button in the upper-right corner of the source editor.

  TIP   You can also close a file by right-clicking its tab in the Edit Pane.

• To close all open source files, select File>Close All.

If you have made changes to a source file, Workbench prompts you to save that file before closing it, closing its parent project, or exiting Workbench.

Performing file system operations

You can delete and rename files from within Workbench.

To delete one or more files:

1. Go to either the Project or Directory tab in the Navigation Pane and select the directory containing the files to be deleted.

2. Select the files you want to delete. You can select multiple files using Shift+Click and Control+Click.

3. Right-click and select Delete.

4. Confirm the deletion.

   The files are deleted from the file system.

   If the files had been individually added to the current project (as opposed to being in the project because they are in a directory included in the project), you are asked whether you want to delete the entries from the project.

5. Click Yes to have the deleted files removed from the project.

To rename a file:

1. Go to either the Project or Directory tab in the Navigation Pane and select the directory containing the file.

2. Select the file you want to rename.

3. Right-click and select Rename.

4. Specify the new name.

   The file is renamed in the file system.

   NOTE   If you had multiple files selected, only the first one is renamed.

   If the file had been individually added to the current project (as opposed to being in the project because it is in a directory included in the project), you are asked whether you want the project to use the new file name.

5. Click Yes to have the project use the new file name.

Workbench wizards

To speed project development, you can use Workbench wizards when creating J2EE projects or components. Workbench has several types of wizards:

Standard Workbench editors

As you create J2EE applications and components, Workbench source editors and the Debugger help you create well-structured archives that are easy to build, deploy, debug, and maintain.

About the Workbench source editors

When you open a source file, the appropriate editor starts automatically.

NOTE   Opening an EAR, JAR, WAR, or ZIP file in Workbench lists the contents of the archive, along with some information about each entry. The listing is read-only.

    For a summary of the core functionality provided in all the source editors, see Chapter 6, "Source Editors".

In addition, Workbench provides specialized functionality in the following editors.

Deployment Descriptor Editor

The Deployment Descriptor Editor lets you construct and populate J2EE deployment descriptors. A deployment descriptor is an XML document that provides information required for J2EE application assembly.

NOTE   To open an existing deployment descriptor, right-click the project or archive (in the Project tab) and select Open Deployment Descriptor.

    For more information, see Chapter 10, "Deployment Descriptor Editor".

Deployment Plan Editor

The Deployment Plan Editor lets you construct and populate deployment plans for deploying J2EE modules and applications to a SilverStream eXtend Application Server. A deployment plan is an XML document that describes how a J2EE module should run in the application server environment.

NOTE   To open an existing deployment plan, right-click the project or archive (in the Project tab) and select Open Deployment Plan.

    For more information, see Chapter 11, "Deployment Plan Editor".

XML Editor

The XML Editor lets you create, edit, and view XML files. It provides intelligent editing of XML files (by reading the XML DTD or Schema, it knows which elements and attributes are valid where) and a graphical tree view.

     For more information, see Chapter 7, "XML Editors".

WSDL Editor

The WSDL Editor lets you create, edit, and view WSDL documents. WSDL (Web Services Description Language) is an XML vocabulary for describing Web Services.

     For more information, see Chapter 8, "WSDL Editor".

Debugger

As part of application development, you can use the SilverStream Debugger to debug server-based applications (such as J2EE applications) and client applications. You can invoke the Debugger from within Workbench.

    For more information, see Chapter 12, "Debugger".

Workbench viewers

In addition to providing a set of source editors, Workbench provides the following viewers so you can view other files within Workbench:

• Image Viewer

• Class Viewer

Image Viewer

If you open a .gif, .jpg, .jpeg, or .png file, the file is opened in the Workbench's Image Viewer. You can zoom the image:

• Left-click or press + to zoom in

• Ctrl+left-click or press - to zoom out

• Shift+left-click or press = to restore the image to its actual size

TIP   If you want these files to open in an external program, specify the file extensions and the program in your preferences. For more information, see File type preferences.

Class Viewer

If you open a .class file, information about the .class file is displayed in the Class Viewer (exception: double-clicking a .class file in the Project tab's Archive Contents view opens the corresponding .java file in the Java Editor).

The Class Viewer displays the following information:

• Name of the file, its corresponding source file, and the version of the compiler

• The class's package statement

• The class's declaration

• List of all fields, sorted by visibility

• List of all methods, sorted by visibility

• The same information for all inner classes

Web Service tools

Workbench supports Web Service development by providing:

• A Web Service Wizard to help you create Java-based Web Services and Web Service consumers from Java classes or WSDL files

• A WSDL Editor for creating, editing, or viewing WSDL files

• A Registry Manager for publishing and discovering Web Services

    For more information, see Chapter 5, "Web Service Wizard", Chapter 8, "WSDL Editor", and Chapter 9, "Registry Manager".

Setting preferences

You can configure your Workbench development environment by setting:

• General preferences

• Build preferences

• Display preferences

• Text editing preferences

• Printing preferences

• Deployment preferences

• Abbreviations preferences

• File type preferences

• Backup preferences

• Version control preferences

• Editor setup preferences

• NetBeans directories preferences

• XML Editor color preferences

To specify preferences:

1. Select Edit>Preferences.

   The Preferences dialog appears.

2. Select the tab you want.

3. Set your preferences. See the following sections for information about specific preferences.

4. Click OK.

General preferences

Specify general preferences as follows:

Build preferences

Specify build preferences as follows:

Display preferences

Specify display preferences as follows:

Text editing preferences

Specify editor preferences as follows:

    For additional text options, see Chapter 6, "Source Editors".

Printing preferences

Specify printing preferences as follows:

Deployment preferences

Deployment preferences are used by the Deployment Descriptor Editor and the Deployment Plan Editor. When you open either of these editors, Workbench loads all of the project's classes (including subproject classes). The editor then uses information from the classes to populate the dialogs that display lists of classes, methods, member variables, and so on. If the classes are not up to date, the information the editors display can be incorrect or missing.

You can control whether Workbench automatically builds a project when you access the Deployment Descriptor Editor or Deployment Plan Editor. You can specify one of the following build settings:

NOTE   You do not need to create the archives in order for the deployment editors to load class information, because the editors load the classes directly from the file system, not from the archives.

You can also specify the following deployment preference:

Abbreviations preferences

You can define abbreviations that can be expanded to one or more lines of text—such as a word that expands to a predefined language construct. Once you have defined an abbreviation, you can type its name in an editor and select Edit>Text Tools>Complete Abbreviation (or press Ctrl+U) to replace the abbreviation with the expanded text.

Use %c in an abbreviation's definition to signify where the insertion point will be positioned when the abbreviation has been expanded.

For example, the abbreviation main is predefined as follows and is meant to be used in Java files:

  public static void main(String args[])
  {
      %c
  }

To define an abbreviation:

1. Select Edit>Preferences and click the Abbreviations tab.

2. Click Add.

3. Type the abbreviation (shortcut) in the Abbreviation text box and click OK.

   Abbreviations must be single words and are case-sensitive.

4. Click inside the Definition text box and type the text you want the abbreviation to expand to.

5. Click OK.

To delete an abbreviation:

1. Select Edit>Preferences and click the Abbreviations tab.

2. Select the abbreviation in the Abbreviations text box.

3. Click Delete.

4. Click OK.

To edit an abbreviation:

1. Select Edit>Preferences and click the Abbreviations tab.

2. Select the abbreviation in the Abbreviations text box.

3. Click inside the Definition text box and change the abbreviation.

4. Click OK.

To use an abbreviation in your source code:

1. Type the abbreviation shortcut in the editor.

2. Position the cursor within the shortcut text or highlight it.

3. Click Edit>Text Tools>Complete Abbreviation or press Ctrl+U. The shortcut text is replaced with the expanded text defined for that abbreviation.

NOTE   If the abbreviation text is not defined, the Complete Abbreviation command is ignored.

File type preferences

Workbench lets you use third-party tools to edit specific file types. You can set preferences that let you launch files in an external editor rather than opening them in Workbench. Use the File Types tab to associate file extensions with external editors. For each file type you can choose whether to open the file in:

• Workbench

• The Windows default editor for that file type

• The Windows program you specify

To define how a file type is launched:

1. Select Edit>Preferences and click the File Types tab.

2. Click Add.

3. Type the file extension in the dialog and click OK.

4. Specify one of the following preferences for the file type:

   Setting	Description
   Open in Workbench	(The default) Opens files using the Workbench source editor.
   Open using the default Windows program	Opens files using the Windows default editor for that file type (same as double-clicking a file in Windows Explorer—for example, using Notepad to open files with the .TXT extension).
   Open using this application	Opens files with the application you specify. You can type the path to the application, or click Browse and navigate to the application. NOTE   Because some editors launch a new program instance each time you open a file, this setting is not always recommended.

5. Click OK.

CAUTION   Consider the following when associating an external editor with the XML file extension: if you use an external editor to edit SilverStream deployment plans, you will not be able to take advantage of the default setup that the SilverStream editor provides and your project will not be associated with a deployment plan.

Backup preferences

You can set Workbench preferences that control:

• Autosave files—successive copies of a modified file (each successive save replaces the preceding one). Autosave files are copies of any file in the Edit Pane that has been modified.

• Backup files—the original file before it was modified and saved.

By default, autosave and backup operations are not enabled.

You can set global backup preferences that control how all projects are backed up. However, because your projects may contain files with identical names, you may want to store separate backup and autosave files for each project. To do so, specify a subdirectory relative to the file's source directory for both backup and autosave files. Files that are backed up in parallel backup directories won't be overwritten.

NOTE   When you specify a relative name for a backup or autosave directory, it will be relative to the source file.

Specify autosave and/or backup preferences as follows:

To define how files are autosaved and/or backed up:

1. Select Edit>Preferences and click the Backup tab.

2. Choose Auto save enabled and/or Backup enabled.

3. Specify autosave and/or backup file parameters as described above.

4. Click OK.

Version control preferences

    See Using version control.

Editor setup preferences

These preferences specify which types of files will be edited using the Workbench NetBeans-based editors.

    See "Adding files types edited by NetBeans-based editors" on page 213 and "Using the native Java, JSP, or HTML editor" on page 217.

NetBeans directories preferences

    See "Creating parser database files" on page 212.

XML Editor color preferences

You can specify the colors used in the XML Editor's Source View to display different types of information in XML documents, such as tags, arguments, values, text, errors, and white space (listed in the dialog as ws).

For each type of information, you can specify a foreground and a background color. You can pick from a list of colors or define your own by clicking the ellipsis button. You can also specify whether to use a bold font.

To specify colors used in the XML Editor:

1. Select Edit>Preferences and click the tab for XML Editor colors.

2. Select the type of information whose color you want to specify, then specify a foreground and/or a background color and specify whether you want to use a bold font.

Setting Workbench profiles

You can define the following types of Workbench profiles:

• Server profile

• Database profile

• Registry profile

Server profile

A server profile stores information about an application server, including the server's host name and port. When selected at deployment time, the server profile tells Workbench what server to deploy to and provides the information required for deployment to that server. A server profile applies to a specific server. If you are deploying to multiple servers, you need to set up a separate profile for each.

Your server's configuration determines how to specify the server profile information. For example, if your server uses security certificates you will specify the https protocol. The server configuration may also affect how you specify the server name, server port number, database name, and so on.

    For information about configuring a particular application server, see the product documentation for that server.

To create a server profile:

1. Select Edit>Profiles.

2. On the Servers tab of the Profiles dialog, click New.

3. Specify settings in the Create a New Server Profile dialog as follows:

   Setting	Description
   Profile name	Enter a name to identify the profile. NOTE   The server profile name cannot contain the period (.) character.
   Server type	Select a server type from the list. Server types are organized by brand and version number. The version number indicates the lowest version supported by a given server type. A server type is often valid for multiple subsequent versions as well. As a rule, you should select the server type for your brand that is closest to the target server's version, without being higher. For example, if your target is Version 3.7.5 of the SilverStream eXtend Application Server, the server type to select is SilverStream 3.7.4 or higher.
   Deployment tools directory	Specify the directory containing the executables used to deploy to the server.
   Rapid deployment directory	For rapid deployment only. Enter the directory where you want Workbench to write the files for rapid deployment. Some servers require that files be written to a specific directory for rapid deploys. Make sure that you specify the appropriate location for your server's configuration. See Setting rapid deployment directories for the directory listings.     For more information on rapid deployment, see Workbench rapid deployment.
   Server name	Set the server name using the following formats. For servers running http: servername http://servername[:port] For servers running https: https://servername[:port] Specify the port number if the server is not listening on the default port.
   Database name	For SilverStream eXtend Application Servers only. Enter the name of the database to deploy to.
   Target servers	For BEA WebLogic servers only. Enter the names of the target servers.

4. Click OK to close the Create a New Server Profile dialog

5. Click OK to close the Profiles dialog.

Setting rapid deployment directories   This table shows the rapid deployment directory you should specify in the Server Profile dialog.

Using Workbench with secure servers   Workbench connects to the target J2EE server at deployment time using the server profile. If the server profile indicates a secure server, then Workbench will make the SSL connection automatically. Workbench uses the set of commercial Certificate Authority certificates listed in agrootca.jar (located in Workbench's lib directory). If the server you are trying to deploy to uses a certificate that was issued by a CA certificate that is not listed in agrootca.jar, Workbench will not successfully connect to the server. You can add the CA certificate to agroootca.jar using any tool that allows you to modify the contents of a JAR file (for example, Sun's JAR utility or WinZip).

Database profile

You'll need to set up a database profile if you use any of the following Workbench components:

The database profile provides JDBC information that enables Workbench to connect to the datasource and retrieve table and field information. You can create multiple profiles to support different databases and JDBC drivers.

To create a database profile:

1. Select Edit>Profiles.

2. On the Databases tab of the Profiles dialog, click New.

3. Specify settings in the Create a New Database Profile dialog as follows:

   Setting	Description
   Profile name	Enter any name to identify the profile.
   JDBC Driver	Enter the class name of the JDBC driver. You can specify any JDBC 2.0-compliant driver. To use the Sun JDBC-ODBC bridge driver (which is included in the JRE), specify sun.jdbc.odbc.JdbcOdbcDriver. If you specify a JDBC driver other than Sun's bridge driver, make sure that the driver class can be loaded by Workbench (see To make the driver class available: below).
   JDBC URL	Enter an URL that specifies the database you want—for example, jdbc:odbc:TestDB NOTE   The text you enter after the first colon is driver specific.
   Connection Catalog	(Optional) Specify which SQL catalog (subset) of the database to connect to—for example, PayrollDb. If your database driver does not support catalogs, it will ignore this request. If supported, the connection catalog lets you set up which database tables are retrieved. Connection catalogs are useful when you are connecting to a very large database or only want to connect to a subset of database tables (for example, to exclude production database access).
   Datasource Name	Specify the name of the data source to associate with this database profile. You can specify either the datasource name, like SilverBooks, or the full JNDI specification, like java:pm/JDBC/SilverBooks.

4. Click Test to check the connection to the database specified by the JDBC URL.

   This test makes a JDBC connection to the database. The test will fail when a connection is not available or a setting is not correctly specified.

5. On the test popup, enter your database user name and password and click OK to verify access.

6. Click OK to close the Create a New Database Profile dialog.

7. Click OK to close the Profiles dialog.

To make the driver class available:

1. Obtain the JAR or other archive file that contains the JDBC driver.

2. Do one of the following:

   • Put the JAR in the Workbench lib\ext directory.

   • Edit the Workbench configuration file (bin\xwb.conf) to point to the driver archive by including the line addcp path/mydriver.jar. For example:

       addcp c:/sybase/SybJConnect.jar
     

3. Start Workbench.

Registry profile

Workbench provides a facility for defining profiles for Web Service registries. These profiles supply the information that allows you to search registries and deploy Web Services.

    For more information on registry profiles, see "Defining registry profiles" on page 274.

Using version control

If you use a version control system, you can set up Workbench to access it. This enables you to perform version control operations on the files in your projects while working in the IDE.

• Setting up access to version control

• Accessing version control

Setting up access to version control

Before you can perform version control operations in Workbench, you need to adjust preference settings to enable version control and configure support for your version control system.

To adjust version control settings:

1. Select Edit>Preferences to display the Preferences dialog, then go to the Version Control tab.

2. Check the Enable Version Control property.

   This turns on the version control features of Workbench.

3. Select one of the available Version Control Systems.

   In this property, you're actually choosing a version control system definition that tells Workbench the version control commands to support. Workbench comes with definitions for several popular version control systems (ClearCase, CS-RCS, CVS, PVCS, Visual SourceSafe). If you choose one of these, you can use it as is or edit the commands it defines to suit your needs and system configuration.

   You also have the option of creating version control system definitions yourself. This lets you set up Workbench support for just about any version control system you might have.

Working with definitions   The following topics provide more detail about working with version control system definitions:

• Editing a version control system definition

• Creating a version control system definition

• Distributing a version control system definition

• Deleting a version control system definition

Editing a version control system definition

A version control system definition specifies a list of version control menu items that Workbench is to display. Each menu item is mapped to a command-line operation of the chosen version control system and also specifies details about how that operation is to be executed. You can edit the list to modify, create, or delete menu items.

To edit a definition:

1. From the Version Control tab of the Preferences dialog, select a definition from the Version Control Systems dropdown list.

2. Click the Setup button.

3. In the Setup dialog, make your changes to the list of version control menu items:

   If you want to	Do this
   Change the behavior of a menu item	Select that item from the Version Control Command listbox, then edit its Command properties.
   Change the name of a selected menu item	Click the Edit button. The name can include letters, numbers, spaces, and special characters. You can also edit the mnemonic character to be used for keyboard access to the menu item (when pressed in combination with the Alt key).
   Create a new menu item	Click the Add button, then specify the item's name and mnemonic character. Your new item will be added to the end of the list.
   Delete a selected menu item	Click the Remove button.
   Switch the order of menu items	Select an item you want to reposition, then use the arrow buttons to move it up or down in the list.

Command properties   The following table describes the command-related properties you can specify in the Setup dialog for version control menu items:

Predefined environment variables   The following table describes the predefined environment variables you can include in the command you specify for a version control menu item:

  x:/com/myco/myfile.java

  x:/com/myco

  myfile.java

  myfile

  java

Creating a version control system definition

If Workbench doesn't provide a definition for your version control system, you can create one yourself.

To create a definition:

1. From the Version Control tab of the Preferences dialog, click the Add button.

2. When prompted, type a name for your version control system definition.

   The definition name can include letters, numbers, spaces, and certain special characters. The name you specify is added to the Version Control Systems dropdown list.

   Workbench also creates an XML file to store your definition. The name of this file matches the definition name you specify (except that spaces are replaced by underscores). Workbench saves your definition XML file in its Resources\version_control_config directory (along with the definition XML files it provides).

3. When the Setup dialog displays, specify the details of your version control system definition.

       See Editing a version control system definition.

Distributing a version control system definition

Once you edit or create a version control system definition, you might want to copy it to other computers where Workbench is installed.

To distribute a definition:

1. Find the XML file for your version control system definition in the Workbench Resources\version_control_config directory.

2. Copy that file to the corresponding directory on each target computer.

   When Workbench is run on those computers, the Version Control Systems dropdown list (on the Version Control tab of the Preferences dialog) will automatically include your copied definition.

Deleting a version control system definition

If you don't need a particular version control system definition, you can remove it.

To delete a definition:

1. From the Version Control tab of the Preferences dialog, select a definition from the Version Control Systems dropdown list.

2. Click the Remove button.

   Workbench prompts you to confirm, then deletes that definition from the list. The definition's XML file is deleted from the Workbench Resources\version_control_config directory.

Accessing version control

When you use Workbench with version control access enabled, the commands specified by the active version control system definition are available via a popup menu. You just need to right-click one of the following:

• Any file name on the Project tab of the Navigation Pane

• An open file in the Edit Pane

When you execute a version control command, resulting text messages display on the Version Control tab of the Output Pane.

Maintaining Todo lists

Developing J2EE and Web Service applications can be quite a complex undertaking. It is sometimes hard to manage the work. With that in mind, Workbench provides the ability for you to maintain a Todo list that organizes and tracks your tasks.

You maintain your Todo list in the Todo tab of the Output Pane.

You can:

• Create Todo items

• Associate items with Workbench projects or mark them as independent of particular projects

• Mark the completion status of items

• Create a hierarchy of items

• Reorganize the items in the hierarchy

• Delete items

In addition, various Workbench wizards and tools generate items in your Todo list to point you to areas where work needs to be done and to describe the nature of that work.

Working in the Todo tab

When you first click the Todo tab, the Todo list is empty (unless you have run a tool or wizard that populates the list; see Working with generated items).

Creating items   The first thing you'll do is add one or more items, which can be tasks or folders.

To add an item:

1. Select the item following which you want to add an item and either press Ins or right-click and select Add Item.

   TIP   You can also use Edit>Add Todo Item to insert an item at the end of the list, or press Shift+Ins to add the item as a child of the selected item.

   The Add Todo Item dialog displays.

2. Enter the following information:

   Item	Description
   Description	Text to display for the item in the Todo list
   Note	(Optional) Additional information about the item. This text displays as part of the item's tool tip when the mouse pointer is over the item
   Add to open project	If you want to associate this item with an open project, select the project from the list. If you select a project, the Todo item is added to the end of the list in the project's folder (the folder is created if necessary). A project's Todo folder is a top-level folder named: projectFile in pathToProject For example, if a project file is in c:\WorkbenchProjects\myEAR\MyEAR.spf, the project folder will be named: MyEAR.spf in c:/WorkbenchProjects/myEAR

3. Click OK.

   The item is created.

   If you associated the item with a project, it is created as the last item in that project's list.

   If you did not associate the item with a project, it is created as a sibling following the selected item (unless no item was selected when you added the item, in which case the item is added as the first item in the list, or unless you added the item with Shift+Ins, in which case the new item is a child of the selected item).

New items appear with the description you entered, along with a checkbox. The checkbox indicates the completion status of the item (see the next section).

Editing items   You indicate an item's completion status, as well as revise its description and note, by editing the item.

To edit an item:

1. Select the item.

2. Right-click and select Edit Item.

   The Edit Todo Item dialog displays.

3. Update the information as appropriate. To indicate completion status, select a value from the Percent done listbox or type a value.

4. Click OK.

A faded checkbox indicates that the task has not begun. A half-filled checkbox indicates partial completion. A filled checkbox indicates completion.

TIP   You can also toggle an item's completion status between 0 and 100 percent by selecting the item, right-clicking, and selecting Toggle Item(s) Done. If the completion status was zero, it is set to 100; if it was non-zero, it is set to zero.

Tool tips   When you position the mouse pointer over an item, the item's tool tip displays as:

  percent done; Notes: noteText

Creating a hierarchy   Todo lists can be hierarchical—items can contain other items. For example, you can create a folder of related tasks.

To create a hierarchy:

• Move one or more items under another one by selecting the item(s) and either pressing > or by right-clicking and selecting Indent.

  The item becomes a child of its previous sibling, which is now a folder.

Similarly, to outdent one or more items, select them and press < or right-click and select Outdent. If an item no longer has children, it is no longer displayed as a folder.

Moving items   You can move an item around with drag and drop: Press and hold the mouse button on an item and move the item within the list. A horizontal line indicates where the item will be moved to. Release the mouse button to move the item. Moving a folder moves all of its contents as well.

You can move an item anywhere in the list.

TIP   You can drag more than one item at a time as long as you drag as soon as you have selected the last of the multiple entries. (If you click after selecting the last entry, it reverts to a single selection. This behavior is a limitation of the JDK 1.3 version of the control used in the Todo tab and has been addressed in JDK 1.4.)

Deleting items   You can delete one or more items at a time.

To delete items:

1. Select the items you want to delete. You can select a folder to delete it and all its contents. You can select multiple items anywhere in the list using Shift+Click and Ctrl+Click.

2. Press Del or right-click and select Delete item(s).

   You are asked to confirm your deletion.

3. Click Yes to delete the items.

Using keyboard shortcuts   The following keyboard shortcuts are supported in the Todo tab:

Disabling the Todo feature   If you don't want to use the Todo feature, you can disable it by deselecting Enable Todo in General Preferences (Edit>Preferences). With Todo disabled, the Todo tab does not display and the Edit>Add Todo Item menu item is disabled.

NOTE   Even after disabling the Todo feature, your Todo list remains intact and will be displayed when you later reenable Todo.

Working with generated items

Various Workbench wizards and tools generate Todo items and add them to the corresponding project folder in your Todo list (remember that the Todo folder for a project is a top-level folder named projectFile in pathToProject). For example, the Servlet Wizard adds items about processing the servlet's GET and POST requests and implementing any interface stub methods.

@todo comments   In addition to populating the Todo list with items, the wizards include @todo javadoc-style comments in the generated source files. These comments are of a finer granularity than the items generated in the Todo list. The Todo list would be too cluttered if all the @todo comments appeared in the list, but the @todo comments can be helpful to you in your detailed work.

Actions in generated items   Generated items are just like the items you create in the Todo tab, with one exception:

A generated item might have an action associated with it. If a generated item has an action associated with it, you can invoke the action by doing either of the following:

• Double-clicking the item

• Right-clicking the item and selecting the first menu item, which describes the action

NOTE   If an item has no associated action, the first menu item is Launch Action and it is disabled.

Typically, the action is to open an associated file. For example, if you double-click the Todo item generated by the Servlet Wizard about specifying the servlet's GET request, Workbench opens the servlet's source file and positions the insertion point appropriately.

Specifying a debugger

By default, when you select Edit>Launch Debugger or click the Launch Debugger toolbar button, Workbench opens a dialog asking you for information, then launches the SilverStream Debugger provided with Workbench. (For more information about using the SilverStream Debugger, see Chapter 12, "Debugger".)

Instead of using the SilverStream Debugger, you can also specify your own debugger so that when you select Edit>Launch Debugger, your debugger is launched with the proper command-line arguments.

To specify your own debugger to launch from Workbench:

1. Select Edit>Preferences.

2. In the Debugger command field in the General tab, specify the command line to launch your debugger, as described next.

   If this field is not empty, Workbench executes the specified command when you launch a debugger. If this field is empty, Workbench launches the SilverStream Debugger.

3. Click OK.

Specifying the command

Specify the operating system command that Workbench should issue when you select Edit>Launch Debugger or click the Launch Debugger button. See your debugger's documentation for information about how to invoke your debugger from the command line.

You can include environment variables in the command by using the syntax %varname% or ${varname}. Workbench substitutes the values of these variables when invoking the command.

In addition to environment variables set at the operating system, you can also use environment variables that are predefined by Workbench:

• You can use the same variables that the Workbench version control interface uses (see Predefined environment variables).

  The file-related environment variables (such as %_PATH%) refer to the file that is open and currently active in Workbench.

• Plus you can use the following two predefined variables:

  Variable	Description
  %_CLASSPATH%	The semicolon-delimited list of the classpath entries for the project and its subprojects
  %_SOURCEPATH%	The directory containing the project file

Using Ant

Internally, Workbench uses Apache Ant when you build a project by selecting one of the Build commands on the Project menu (for more information about building Workbench projects, see "Compiling, building, and archiving" on page 84). You don't need to know anything about Ant if you only want to do builds from the Workbench IDE. But Workbench also provides direct access to Ant so that you can accomplish the following:

• Do project builds from the command line

• Do your own customized Ant processing

If you want to do either of these tasks, read this section to learn about Ant and how to use it.

What is Ant?

Apache Ant is a Java-based build tool, much like make but without make's foibles. A couple of key differences between Ant and make are:

• Instead of using makefiles, Ant uses XML-based buildfiles, which specify targets that define the processing that you want.

• Instead of using shell-based commands, Ant is extended using Java classes. It comes with a built-in set of tasks, each implemented through a Java class. To define a new task, you define a new Java class that extends the Ant Task class.

Ant is an open-source Jakarta subproject. To learn more about Ant, including details on defining your own tasks and creating buildfiles, see http://jakarta.apache.org/ant.

Using the Workbench Ant tools

You can use Workbench tools to invoke Ant from the command line. There are two Ant-based executables in the Workbench bin directory:

• xwbbuild, which allows you to build a Workbench project

• xwbant, which allows you to perform customized processing based on buildfiles (and possibly task classes) that you have created

The difference between the two executables is that xwbbuild takes a Workbench project file as input, and xwbant takes an Ant buildfile.

You invoke the tools from the command line.

xwbbuild syntax   Here is the command syntax for xwbbuild:

  xwbbuild projectFile WorkbenchTarget options

where:

xwbant syntax   Here is the command syntax for xwbant:

  xwbant CustomizedTargets options

where:

Options   Here are the options you can provide with xwbbuild and xwbant:

Workbench modification to Ant   The version of Ant shipped with Workbench is exactly the same as the version from Apache (use the -version command-line option to see the version number), with one exception: the Workbench Ant javac task supports a sourcepath attribute, which allows you to specify the -sourcepath argument to the compiler. Workbench generates buildfiles with this attribute, so Workbench buildfiles will not work with an unmodified Ant.

Examples

xwbbuild examples   The following command builds and creates the archive(s) for the myApp Workbench project (if changes have been made since the last time the project was built and archived).

  xwbbuild myApp.spf build

The following command rebuilds all the files and creates the archive(s) for the myApp project.

  xwbbuild myApp.spf rebuild

The following command removes all files from the build directory and deletes the archive(s).

  xwbbuild myApp.spf clean

xwbant examples   The following command performs the tasks defined for the default target in build.xml in the current directory.

  xwbant

The following command performs the tasks defined for the purge target in build.xml in the current directory.

  xwbant purge

The following command performs the tasks defined for the purge target in test.xml. If test.xml isn't found in the current directory, Ant searches for it in parent directories until it hits the root directory.

  xwbant purge -find test.xml

Internationalization support

This section describes Workbench's support for internationalization.

Specifying fonts

If some international characters are not displaying correctly in Workbench (for example, they are displaying as boxes) or if the font mapping on your system is poor, you can specify different fonts for Workbench to use for its menus, labels, dialogs, and so on (note that the editors themselves are not affected by changes you make as described next).

To change the fonts used by Workbench:

1. Exit Workbench.

2. Specify alternate font names (and optionally sizes and colors) in the following lines in ide.props, which is in the Workbench Resources\Preferences directory:

     font-name-standard = font-name 
     font-size-standard = font-size 
     font-name-big = font-name 
     font-size-big = font-size 
     output-font-name = font-name 
     output-font-size = font-size 
     output-background-color = font-color 
     output-font-color = font-color 
   

Font sizes are specified in points. Colors are specified as R,G,B integer values; for example, 255,255,255 is white and 0,0,0 is black.

• The standard font is used to display all standard-sized text, menus, labels, and so on. The default is 11-point Arial.

• The big font is used to display title text in wizards as well as buttons in wizards and dialogs. The default is 18-point Arial.

• The output font is used to display text in the Output Pane. The default is 12-point Monospaced, black on a white background.

Sun recommends that you use Serif as the font name to provide the best font mapping on most systems.

Extending the Workbench toolset and services

SilverStream eXtend Workbench is an extensible IDE for developing J2EE applications and Web Services. The standard toolset described in this documentation can be extended using the Workbench framework API. Contact your SilverStream representative for more information about extensibility.

Tools Guide

Copyright © 2002, SilverStream Software, Inc. All rights reserved.