Integrated Development Environment

VisualAge(R) for Java(TM)

Version 3.5

Integrated Development Environment

RELEASE NOTES

1.0 Introduction
2.0 Limitations and known problems
      2.1 Web browsers
             2.1.1 Launching web browsers on Windows (R)
             2.1.2 Running applets in a Web browser
      2.2 Printing
      2.3 Import SmartGuide
      2.4 Debugger
            2.4.1 Security manager
            2.4.2 Breakpoints in classes.zip class files
            2.4.3 Breakpoints in constructors
            2.4.4 Breakpoints move when editing code
            2.4.5 Breakpoint placement in .class files
            2.4.6 Stepping through code with local variables
            2.4.7 Sorting exceptions in Exceptions page
      2.5 Scrapbook and Inspectors
      2.6 Code Assist
            2.6.1 Availability of code assist
            2.6.2 Activating code assist
            2.6.3 Code assist limitations
      2.7 Managed Project Resources
             2.7.1 National Language support
             2.7.2 Modifying resources externally
             2.7.3 Moving or copying product directories
     2.8 Types and resources with non-ascii names exported to .jar files
       2.9 Japanese fonts
             2.9.1 Japanese fonts in Options dialog
        2.10 Bidirectional text
               2.10.1 Undo/redo in bidirectional languages
               2.10.2 Disabling bidirectional text support
        2.11 Miscellaneous
              2.11.1 VisualAge for Java does not support Logitech scroll mouse
              2.11.2 Startup problem
              2.11.3 Multiple monitors on Windows 2000
3.0 Hints and Tips
      3.1 Caching
            3.1.1 Setting up the cache
            3.1.2 Clearing the caches
       3.2 Javadoc doclets
       3.3 Source View
             3.3.1 Retaining the format of files
             3.3.2 Viewing classes which are deleted, renamed or moved
             3.3.3 Viewing classes which are replaced with another edition
             3.3.4 Saving all pages
             3.3.5 Source View only shows parsing problems
             3.3.6 Saving a page that declares multiple types
             3.3.7 Editing large type declarations
             3.3.8 Names of types are visible when too many pages are open
          3.4 Editing multiple fields
4.0 Corrections to the documentation
      4.1 Broken links in the navigation panel

1.0 Introduction

This release note contains information about various limitations and known problems associated with the IDE, as well as hints, tips, and workarounds.

2.0 Limitations and known problems

2.1 Web browsers

2.1.1 Launching web browsers on Windows
Windows(R) has two different types of file associations for web based documentation. The first type of association is for .htm and .html files launched locally (e.g. c:\index.htm). The second is for non-local files in URL format (e.g. http://www.software.ibm.com/ad/vajava)
and is called "URL - Hypertext Transfer Protocol". VisualAge for Java uses the first association for most Help menu items, and the second one for the Help > Support menu item. Typically, when a web browser is installed it configures both of these associations automatically.

If a VisualAge for Java Help menu option fails to open a web browser it means your associations are not properly configured. To determine if the associations in Windows are properly setup, go to the Windows Start menu and select Run. Type in the name of an .htm file or a URL (e.g. 'http://www.software.ibm.com/ad/vajava'). In both cases, a web browser should open. If a web browser fails to open it means your associations are not properly configured.

In the event the web browser does not open, you can either reinstall the web browser, manually configure your Windows associations or in VisualAge for Java go to the Help page of the go to the Help page of the Options dialog (which can be reached from the Workbench by selecting Window > Options) and choose 'Specify browser path' instead of 'Use file association'.

2.1.2 Running applets in a Web browser
If your exported applet does not run in your web browser ensure that your browser supports J2DK(TM) v1.2.2. Consult the web browser's vendor site for any JDK(TM) related fixes. Also, ensure that your web browser's security settings are correct for running your applet.

2.2 Printing Problems

Some printer drivers provide incorrect information about the size of the fonts used in the driver. Others have problems scaling images or drawing lines properly. These problems are most commonly found in PCL printer drivers.

Printer driver problems can cause some of the following symptoms when printing from VisualAge for Java:

text runs off the right margin of a page
text extends outside of its rectangle in the class graph
class graph icons are positioned improperly
unexpected lines are drawn in class graphs

These problems can often be solved by ensuring that you have the latest printer driver that is available for your printer. If your printer supports PCL and Postscript, try the Postscript version of the driver. It is usually more accurate.

The following drivers have exhibited these kinds of problems:
IBM Network Printer 17 PCL - OS/2 <older versions>
IBM Network Printer PCL Driver 1.14 - Windows 95

2.3 Import SmartGuide

When importing from directories, you normally should not select a subdirectory of a package hierarchy as the root for import. If you do, the resources will be copied incorrectly. For example, if you were to "export" the IBM Java Examples project, the result is a directory structure such as:

\com\ibm\ivj\examples\awttextframework
\com\ibm\ivj\examples\awttestlauncher
\com\ibm\ivj\examples\awttests
and so on

To import from directories you should choose the directory which contains the com subdirectory and use the "Details..." prompter to select the subdirectories you want. The subdirectory structure for the resources will be recreated when you import.

2.4 Debugger

2.4.1 Security manager
Installing a security manager that does not allow complete access to members and properties can cause exceptions or missing fields in the debugger due to introspection failures. This affects SecurityManager and its subclasses.

Workaround: Do not use a security manager when debugging code, or ensure that your security manager allows access to members and properties.

2.4.2 Breakpoints in classes.zip class files
Breakpoints placed in external class files found in classes.zip may not trigger.

Workaround: Place the breakpoint in the copy of the class which is located in your Workspace.

2.4.3 Breakpoints in constructors
When a breakpoint is set in a constructor, it may appear in the line of code below the line that you want. This same problem also causes the debugger to improperly highlight the constructor code when you are stepping through it.

Workaround: If the breakpoint is appearing on the wrong line, you can can add a multi line comment above the constructor definition to move the lines of code.

2.4.4 Breakpoints move when editing code
Breakpoints move to different lines when new lines of code re inserted or deleted above them.

Workaround: Clear all the breakpoints in the method before adding new lines of code or removing code and set them again after the method is saved.

2.5 Scrapbook and Inspectors

Displaying extremely long single lines (larger than 10K) in the scrapbook can cause an exception, depending on the platform and graphics driver. In some situations an exception may not occur but a noticeable delay will occur as the text is inserted.

Workaround: If an exception occurs remove the scrapbook page.

2.6 Code assist

2.6.1 Availability of code assist
Code assist is available in a method source view, Scrapbook, Inspector, breakpoint modify dialog and the event-to-code connection editor of the Visual Composition Editor. A limited form of code assist is available in the class source view. Code assist generally requires
that your code prior to the current cursor location be syntactically correct. An exception to this is the Scrapbook and Inspector where, if a syntactic error is found, code assist will use only the source back to the first empty line or the beginning of the line. Also the limited code assist in the class definition considers only the current word and
provides completion for types and statics based on the last saved class definition.

2.6.2 Activating code assist
To activate code assist press Ctrl-Space or Ctrl-L. On some Japanese platforms Ctrl-Space is reserved for IME activation. In this situation Ctrl-L can be used to activate code assist. These keys can be modified using the key bindings in the Options dialog (which can be reached from the Workbench by selecting Window > Options).

2.6.3 Code assist limitations
This section describes some of the limitations of code assist:

In the case where a possible field completion would be hidden by a visible local variable with the same name, code assist will not filter out the hidden field and will still present it as part of the user selection. Note that even having picked up the field, compilation will bind to the local variable. For example, after
defining the following class X, browse its constructor.
class X { int value; X(int value){ this.value = value } } When requesting code assistance in the constructor, in the right hand side of the assignment: this.value = val<code assist> VisualAge will find two completions: the field and the local, where actually
the local variable is hiding the field.
There are some locations where code assist will propose type completions where it should not. Selecting and inserting a type in this case will result in invalid source. For example the completions for:
new Thread(s<code assist here>
will list some types (such as short) where no possible Java construction could require a type in this case.
If a type name needs to be qualified and it is not, no code assist will be available for static members. For example:
public String newMethod ( ) { ResourceBundle a = ResourceBundle.<code assist>
does not produce a list but
public String newMethod ( ) { java.util.ResourceBundle a = java.util.ResourceBundle.<assist>
will produce a list. The easiest way to produce a qualified name in this case (assuming you do not want to add this class/package to the import list) is to place the cursor before the period and activate code assist. Select the class name from the list and it will be fully qualified for you automatically if required.

2.7 Managed Project Resources

2.7.1 National Language support
If you are using VisualAge for Java Enterprise on a non-English platform and managing projects or resource files and folders with names containing non-ASCII characters, be sure to read the Team Development Environment release notes. You must ensure that the client and server are using compatible character encoding schemes.

2.7.2 Modifying resources externally
This release of VisualAge for Java enables you to version and store resources for each edition of a project. These versioned resources are stored in the same directory as your repository in a directory called Repositoryname.dat.pr.

Local resources (that have not been versioned) exist in a subdirectory of the project_resources directory for each project that exists in the workspace. If you change the contents of a project_resources directory outside of the product by adding, deleting or modifying files directly in the file system, you must use F5 (Window > Refresh) to refresh the contents of any windows that show the contents of that directory. You must do this even if you make such changes while the product is not running (when you next start the product, you must refresh any affected open windows).

If VisualAge for Java detects that resources were modified externally, it will print a message to the log and make appropriate changes (in Entry and Professional versions the resources will be immediately stored, in Enterprise versions, the resources will appear as unreleased if they were previously released).

2.7.3 Moving or copying product directories
When VisualAge for Java is started, the resources for each directory will be checked against the local resource index for that project. Local resource indexes reside in the project_resources directory. If VisualAge for Java determines that no files have been added or deleted and the modification timestamp of every file has changed, it will treat that project as having been moved or copied. In this case it will silently update the local resource index for that project. If files are added or deleted or only some of the files have been modified, the local resource index for that project will not be modified and the next time resources are checked for that project, the local resource index will be updated along with a message indicating that resources were externally modified.

If you intentionally modify every resource for a project while the product is not running and then start the product, VisualAge for Java will believe that the directory has been moved or copied and will not treat the files as new editions. It is recommended that you only modify resources externally while the product is running so that it can track these changes.

2.8 Types and resources with non-ascii names exported to. jar files

If types and resources with non-ascii names are exported to a .jar file, the files within the .jar will not be encoded in windows native encoding. Instead, they will render the names as UTF-8.

2.9 Japanese fonts

2.9.1 Japanese fonts in Options dialog
If the dialog font in the Options dialog is set to an English font (for example, adobe helvetica) on a Japanese machine, the font will not contain the necessary Japanese characters, and the Options dialog will be unreadable.

Workaround: The Options dialog can still be used to set the dialog font back to a Japanese font. The keyboard arrow keys may have to be used instead of the mouse to make selections when the Options dialog is in this state.

2.10 Bidirectional text

2.10.1 Undo/redo in bidirectional languages
The Undo and Redo operations in the editors are not available on operating systems that are didirectional.

2.10.2 Disabling bidirectional text support
On operating systems that are didirectional, it is possible to turn off the didirectional support in the text editors. If the support is turned off, the Undo/Redo operations will be available in the text editors.

To disable the bidirectional text support, add the following line to the [National Language Support] section of the ide.ini file in the ide/program directory:

EnableBidiSource=false

2.11 Miscellaneous

2.11.1 VisualAge for Java does not support Logitech scroll mouse
Any Logitech mice with drivers that remap scrolling action to the mouse will cause a system error to occur when it is used to scroll.

2.11.2 Startup problem
If you receive the following error message during startup:

The following error(s) were detected during the startup sequence which may interfere with correct operation: 1)Error accessing ivj.dat: OS error 11001 2)Error accessing ivj.dat: OS error 11001 Do you wish to continue anyway?

Verify that the server address in your ide.ini can be resolved and pinged. You may need to contact your network administrator and confirm your machine is properly configured.

2.11.3 Multiple monitors on Windows 2000
VisualAge for Java provides limited support when utilizing multiple monitors on Windows 2000.

3.0 Hints and Tips

3.1 Caching

3.1.1 Setting up the cache
VisualAge for Java uses a disk cache and a memory cache to improve .class file access time for classes in the IDE.

The memory cache is used to keep a number of classes resident in memory. When the IDE is started, only the most frequently used classes are maintained in the memory cache. The memory cache preferred size can be set by the user in the Cache page in the Options dialog. This value is the number of classes that will be preserved when the IDE is started. Any class found in the cache can be almost instantaneously dynamically loaded. A system with a large amount of RAM can take advantage of a large memory cache; a system with a limited amount of RAM should keep the memory cache small - this will allow VisualAge to flush unused classes.

The disk cache is used to help fill the memory cache. When an IDE class must be loaded, the disk cache is searched first and if the class is not there it is loaded from the repository. The resulting class is then put in the memory cache. The disk cache improves performance, but does not have as significant an impact as the memory cache. There are two variables that the developer can control on the disk cache: (1) disk cache enable, and (2) disk cache preferred size.

To enable the disk cache, the directory named "cache" must exist as a subdirectory of the ide directory. There are a few reasons you may not wish to enable the disk cache. Systems with limited available disk space should not use the disk cache. As well, if accessing the repository is almost as fast as accessing the cache directory, the disk cache provides no additional value.

The disk cache preferred size is the number of classes (files) that will be preserved when the IDE is exited (or saved while remaining in the IDE). The most frequently used .class files are maintained in the disk cache; all other files in the directory are deleted.

3.1.2 Clearing the caches
If you click Clear the Memory Cache in the Cache page of the Options dialog, the contents of the memory cache will be discarded the next time the IDE is started.

If you click Clear the Disk Cache in the Cache page of the Options dialog, the contents of the cache directory will be immediately discarded.

3.2 Javadoc doclets

When you are using doclets that were not provided with the default installation the following steps are needed:

Create a project for your doclets.
Select the project and open the Properties dialog.
Mark the project as an Extension. Thiswill assure that resources are copied to the correct location on import. It will also allow the doclet class to be found when
javadoc is run.
Import the doclet's classes into the project. (This is also a good time to version the project).
Select the Java component(s) you wish to document.
Open the Javadoc SmartGuide by selecting Selected >Document > Generate Javadoc.
Select the doclet you wish to use and fill in the fields as necessary.

Third party doclets can differ widely in implementation and command-line options. Be sure and read all documentation provided by the doclet supplier

3.3 Source View

3.3.1 Retaining the format of files
When Java source files are imported, or classes are edited in the Source tab of a class browser or in the Source View browser, VisualAge for Java will attempt to retain all formatting (positions and ordering of elements and white space). This information is used to reconstruct the source to its original state when it is exported or viewed in a Source tab or the Source View browser. There are cases when the formatting will not always be fully maintained although the syntactic content should never be incorrect.

3.3.2 Viewing classes which are deleted, renamed or moved
When a class is viewed in the Source View browser, deleting the class (or its package or project), or renaming or moving the class will not affect the page in the Source View browser. The page will remain open and the class may subsequently be saved to
its original state.

3.3.3 Viewing classes which are replaced with another edition
When a class is viewed in the Source View browser, replacing it with another edition will cause the page in the Source View browser to be updated with the source of the edition added to the workspace. If there are unsaved changes in the page, they will be
discarded.

3.3.4 Saving all pages
Saving all pages in the Source View browser is faster than saving each page individually. Saving all pages will compile all the source in the browser at the same time.

3.3.5 Source View only shows parsing problems
The set of problems shown in the Source tab and Source View browser are not the same set of problems shown in other browsers. The Source tab and Source View only show parsing problems. Problems viewed in other browsers including some parsing problems as well as compilation and verification problems.

3.3.6 Saving a page that declares multiple types
When a Java source file declaring multiple types is imported, each type is managed individually in the repository. If those types are subsequently exported, each type will produce its own Java source file. This behavior is mirrored in the Source tab and Source View browser. When saving a page that declares multiple types, only the first type will be kept in the page. Other types will be saved but new pages must be opened on those types to view them.

3.3.7 Editing large type declarations
The Source tab and Source View browser parse Java source code in real-time to update the element tree and parsing problems list. This updating never occurs more than once per second. Parsing very large amounts of source may take longer than this and therefore a slight lag may be experienced when entering text.

3.3.8 Names of types are visible when too many pages are open
When there are too many pages open in the Source View browser to allow all of the type names to be shown on the page tabs, none of the tabs will show their type names. Hovering or placing the mouse pointer over a tab will show the name of the type for that page.

3.4 Editing multiple fields

If a line has a multiple filed declaration as follows:

int F1, F2;

this will show as two separate fields in the browser tree views. When you select one of the fields in the tree view, you are shown the complete field declaration line. If you delete the selected field from the tree, you will delete the complete field declaration line, not just the single field. If you wish to delete a single item from the field declaration line, you will
need to select the class and edit the field there.

4.0 Corrections to the documentation

4.1 Broken links in the navigation panel

The following navigation panel links do not work in the Entry Professional Edition of VisualAge for Java:

...for resource files (this is an IDE Concepts link)
Scratch editions (this is an IDE Concepts link)
Providing a standard workspace (this is an IDE Tasks link)

These links are to team development environment information. They do not work because the team component is not included with the Entry Professional Edition of VisualAge for Java. No information contained in these files is applicable to development in the Entry Professional Edition of VisualAge for Java.

VisualAge(R) for Java(TM)

Version 3.5