Inhaltsverzeichnis

Installation

General GUI Issues

Services

Look and Feel

Workspaces

Introduction

The Source Index

Choosing a JDK

Creating New Files

Compiling a Workspace's files

Import/Export of Workspaces

Provided Project Types

Creating a Workspace from Scratch

Creating a Workspace from existing source

Editing

Code Completion (Code Assist)

Auto Import

Error detection

Window Management

Inline Templates (Code Snippets)

Bookmarks

Misc Editing

Browsing

The Help Agent

Opening JavaDoc

The FileTree

The ClassView

The Class Browser (ClassTree)

Browsing all Implementors of an Interface

The Index Viewer

Hierarchy Analysis

Searching and Refactoring

Full Text Search

Syntax Search

Typed Search

Generating Accessors

Generating Import Statements

Extracting Methods, Introduce Locals, Introduce Get-Methods

Renaming Classes, Packages, Methods and Fields

Using AnyJ's GUI Builder

Introduction

Creating a sample workspace

Creating Components

Defining the Resizing Behaviour of a Form

Misc

Creating J2EE Applications with AnyJ and JBoss

A very short introduction to EJB's

Running the examples

How the J2ee workspace is organized

EJB development cycle

Creating a Session Bean (step by step)

Trouble Shooting

Debugging

Versioning

Snapshots

Using CVS with AnyJ

Integration of other VCS

Misc

Generating JavaDoc

Deployment support

Extending AnyJ

External Tools

Scripting AnyJ

#

# Installation

### Prerequisites

AnyJ requires a JDK 1.3.x or higher to run AnyJ's Installer. If you want to use newer technologies, you'll need:

- JDK 1.4 to run and create Web Application using Tomcat 4.x (bundled with AnyJ4.0)

- WebLogic6.1sp2 and a JDK 1.3.1 (additionally recommended: Java Enterprise SDK) to create J2EE applications using WebLogic 6.1 (EJB2.0)

- A JDK 1.2 or higher to create RMI Applications with AnyJ

- The debugger has been tested with JDK 1.3, 1.3.1, 1.3.2, 1.4

### Running the Installer

If you have a properly installed JDK (registered to handle .jar extensions), just double click the anyj-xy.jar to start the installation.
If that fails (or on Unix machines), open a command line shell and type 'java -jar anyj4.0-win32-xy.jar' to start the Installer.

AnyJ does not support filenames containing blanks (' '):

- ' ' (Blank) in the name of AnyJ's installation directory (e.g. 'Program Files')

- ' ' (Blank) in the name of the JDK's installation directory

### Pre-Installing AnyJ in a 'Workstation-Image'

- Run the AnyJ installer as described above (java -jar anyj*.jar)

- Do *not* start AnyJ from the menu, since this starts the second level user-specific setup.

- AnyJ requires write access in the installation directory and the JDK directories

- To install a licensed version of AnyJ 4.0, put a .txt file named license.txt into the 'bin' directory of AnyJ4.0. The license.txt should contain 3 lines as provided by your AnyJ license: " [email] [company] [key] " All three lines have to be terminated by a line feed.

# General GUI Issues

## Services

AnyJ's application framework follows a simple but powerful design: The GUI components such as the editor and trees maintain a 'current selection'. Once a user opens the pop up or the global menu, AnyJ asks all action items (we call them 'Services'), whether they are able to work with the current selection. If an action item is able to work with the current selection, the associated menu item or button gets enabled. In order to keep pop up menus small, they display enabled menu items only, disabled items are not shown in pop up menus.

The main menu contains all available actions, while the pop up menu contains enabled actions only.

Additionally it is possible to enforce the removal of items from the pop up menu in the 'Menus and shortcut section' of the Preferences Panel:

In the editor below, there are a number of selections available.

- a String 'Vector'

- Since 'Vector' has been scanned, the class 'Vector' is also selected

- The Editor Component

- The File 'Vector.java'

- The File the editor is editing

- The directory of the package of 'Vector.java'

Therefore all menu items, which are able to operate on one of the above selections, get enabled. E.g. since Vector is not an interface 'Browse all Implementors' is not enabled (and not visible in the pop up menu), but since 'Vector' is a class, 'Browse in ClassTree' is enabled (and therefore visible in the pop up menu).

An advantage of this general logic is that all functionality is available in all views of the GUI. E. g. Whenever there is a String or TreeNode representing an Interface is selected, you may open the pop up menu and will find the 'Browse all Implementors' menu item.

Shortcuts and Abbreviations

Each service (=menu item) can be assigned a shortcut and an Abbreviation.

An Abbreviation is a character sequence, which can be invoked from the editor by typing them, followed by a ' '. E.g. typing 'ct ' in the editor will invoke 'Edit|Insert Template|Catch'. Though this feature is likely used to insert code snippets, you may invoke arbitrary actions using abbreviations.

Note that everything which can be invoked in some way (E.g. 'External Tools', Scripts, a 'Deployment' configuration, Runnable Classes) is represented by a Service (menu action). E.g. if you add a new main class in 'Preferences, Run & Debug', a new menu item will be added to the 'Run |Run Class' submenu. Adding a new 'External Tool' will create a new menu item in 'Tools|External Tools', etc. . Therefore it is possible to assign shortcuts and abbreviations to user defined items, too.

Misc GUI specials

| Use Ctrl-Alt-M to quickly define a shortcut for a selected menu.
--- | ---
| You can 'type into' any list box of AnyJ to search for an item
| 'Alt-[number]' allows to switch to the associated tab in AnyJ's main window.
| Single clicking on a tree node always opens the file in the editor, while double clicking invokes the default action for a file type. E.g. clicking the icon opens a .html file in the editor, double clicking the tree item will launch a .html browser.

## Look and Feel

| If you are using AnyJ in MDI-mode, you can specify which layout mode you prefer using the Layout menu.
--- | ---
| AnyJ supports two major modes: Single Window, Multiple Documents Multiple Windows (one window per editor) You have to restart AnyJ in order to let changes of this option to take effect.
| Choose the position of the editor tabs here (MDI mode only).
| Choose the Look and Feel of AnyJ. Note that the Windows Look and Feel does not work correctly on some Windows machines (depends on OS-version, Graphics Adapter). Use the AnyJ Look and feel, if you have problems with the Windows L&F.

##

# Workspaces

## Introduction

A workspace in AnyJ is a set of directories making up your project. It is also possible to group several related projects into one workspace.

Files are added to a workspace by simply mounting a directory into AnyJ's current workspace. Once a directory has been mounted, options for the directory can be set.

Directory-related options include:

- whether a directory contains sourcecode and should be parsed
  for coding assistance (e.g. code completion).

- whether a directory should be compiled at build time.

Options set on one directory are automatically applied to all subdirectories, except you decide to set different options on such a subdirectory.

| The 'DirProperties' pop up menu available when a directory is selected allowsx to specify various options ...
--- | ---
| ... which at least modify 'Preferences, Directories'. Please note, that if you select 'Scan class instead of .java' AnyJ looks for .class files and won't display .java files in this directory. This option is useful, if you don't have the sourcecode, no .jar, and therefore need to parse .class files in order to get code completion.
| A feature checking for double classes and other configuration problems. A common error is to organize source code in a wrong way, so you get 'Package/Directory Mismatch'. The JDK's javac compiler and AnyJ expect, that each .java file is located in a directory matching its package name. E.g. class Me.java of package foo.bar.tryst should reside in a directory x:\somedir\mypackageroot\foo\bar\tryst\Me.java.
| These menu items allow to mount and unmount directories to/from a workspace.

## The Source Index

A large part of AnyJ's features such as Code Completion, Refactoring and Browsers (ClassView, ClassBrowser, Hierarchy Analyzer, .. ) rely on the so called 'Source Index' of AnyJ. The Source Index is a database containing all the meta information of your project. In order to let AnyJ build a complete Source Index, it is recommended to mount all libraries used by your project and mark them for parsing (select a directory, open pop up menu|DirProperties).

If a directory has been marked for parsing, AnyJ builds up the SourceIndex by parsing the .java files (or .class files if a .jar file has been marked for parsing).

| Update the SourceIndex (e.g. if you made a fresh 'Get' from Revision Control) using 'Update SourceIndex'. 'Update class & File Outline' refreshes all Trees and Views displaying Files, Classes and/or methods.
--- | ---
| Shorthands for the SourceIndexer window. Click the progress bar to open the SourceIndexer window.
| Since AnyJ's parser database stores any parsed information of a workspace in a database, it is necessary to clear and rebuild this database time by time. Else the Source Index will continuously grow, eating your hard disks free space and slowdown AnyJ. In order to keep heap usage as low as possible, you should care not to scan source or .jars twice (e.g. scanning the source of JDK1.3 and 1.4 in one workspace would not make much sense, but would drastically increase the internal memory usage of AnyJ).

## Choosing a JDK

'Preferences, JDK's' allow to switch the JDK AnyJ uses to run, debug and compile java classes. Note that switching this does not affect the 'Source Index' used for coding assistance. If you want the code completion to display exactly the methods of the newly set JDK, you'll have to unmount the old JDK source, and mount the source of the newly set JDK. Although this might look rather long winded, it has the advantage of enabling cross JDK development. E.g. let the code completion show the limited API of a embedded devices JVM, but compile, debug and run on your PC using JDK1.4 .

You may use the JavaDoc Generation Tool to generate javadoc for your JDK. So you don't have to download the JDK's doc-package.

Note that AnyJ works best if you mount the source code of the JDK to your workspace. The JDK source code is delivered with the JDK and usually is contained in a file 'src.zip' or 'src.jar' in the JDKs root directory. AnyJ automatically tries to unpack this file, anyway if you do not have write access to the JDK directory or SUN decides to rename the src.jar file, it may be necessary that you manually unpack the JDK sources. Note that you can set the location of the JDK sources in the System Libraries panel of the Preferences.

If no source code is present for the JDK, AnyJ will mount the rt.jar (that's where all JDK core classes are contained) to your workspace in order to provide code completion for the JDK classes.

## Creating New Files

To create a new file, select a directory in the main window’s filetree and choose ”File|New” from the main menu or ”New..” from the popup menu of the filetree. Choosing ”New File from Template” will let you choose from different predefined ”Template”-Files. You can add your own templates or change existing in [anyjdir]\templates. For further information about templates refer to the online Help provided by the HelpAgent.

## Compiling a Workspace's files

| The 'Build ..' menu items always apply to your source path (see 'Preferences, Paths'). The resulting class files are stored into the output directory as set in 'Preferences, Compiler Settings'.
--- | ---
| The 'Compile ..' menu items apply to the current selection, regardless whether a selected directory is marked for 'Add to source path [Compile on Build]' or not.
| The preferences section containing compiling related options.
| Choose on of the supported javac compilers by selecting the appropriate tab. Note that AnyJ can read Emacs and javac compatible error messages only ('+E' for jikes).
| You can use the items of the 'Search' menu to step through compile errors.
| If the plug is pressed, the source path is computed from your mounted directories and their settings. If the plug is not pressed, the source path can be specified manually.
| Note that the compile panel keeps old error messages. This eases compiling of large projects, since you can resolve several errors at step by step, without the need to do a complete build for each error. The errors are removed from the 'All Errors' Panel, whenever the corresponding classfile is actually written by javac or jikes. This means if the compiler decides for any reason not to write the .class file (because it has detected an error in a related class), old error messages may be kept until you resolved the secondary problem. The raw section of the compile panel directly displays the compilers output.

## Import/Export of Workspaces

AnyJ's project files are stored in a binary format. Using the 'Export' and 'Import' menu items, it is possible to save and restore important parts of a workspace (e.g. mounted directories, path settings, keyboard shortcuts, external tools, etc. ). User specific settings such as syntax hi lighting etc. are not stored using export. This enables a team to share / exchange common project-related settings, while maintaining the user specific settings such as JDK, etc. .
The export/import menu items store their settings using a xml-flavor ('.ajpr'). '.ajpr'-files do not necessary define a complete workspace, it is possible to load several '.ajpr' configurations to one workspace. This enables you e.g. to only import a set of external tool configurations.

! Warning: AnyJ 4.0 cannot read every export made by previous versions of AnyJ.
Exporting a Workspace Configuration
Editing the project file
The .ajpr file consists of several major sections, you can remove sections which shall not be part of your export. E.g. if you'd like to save your keyboard & menu shortcut configuration only, delete all sections except the 'ServiceOptions' section.
It is possible to use AnyJ's symbolic variables in the configurations. E.g. ($SystemClasses) references the rt.jar of the current JDK, ($Source.SystemClasses) references the JDK sources if available (other important vars: ($outputDir), ($Tools), ($Source.Tools) ).
Usage of relative paths to make the project relocatable
AnyJ makes best efforts to store relative paths in the .ajpr file. AnyJ constructs relative paths taking the directory where the .ajpr is stored as 'current dir'. Additionally AnyJ tries to insert symbolic variables, if a path of the .ajpr file is starting with a valid symbolic variable's value (Check also the 'Preferences, User Environment' form and try the'Tools|Scripting Support|Dump Environment' menu).
You can manually modify .ajpr files by editing them. Please refer to the current dir using '.\'. E.g. to reference a directory named 'lib\xy.jar' write '.\lib\xy.jar' (or './lib/xy.jar' on a Linux box).
Relative paths are resolved at import time. The directory of the .ajpr at import time defines the base directory used to resolve relative paths. E.g. 'lib/myjar.jar' would resolve to [directory of .ajpr file]/lib/myjar.jar. See also the examples in '[anyjinstalldir]/examples'.
Importing a Workspace Configuration
1. Create a new workspace if necessary.
2. Import the .ajpr by drag & drop or by using 'Workspace|Import .ajpr' or double clicking.

# Provided Project Types

### Core Workspace

The core workspace creates an empty workspace having only the source code (or worse: the rt.jar if source code is not available) mounted. You are prompted during creation if you would like to create and mount an empty source folder for your .java files. Choose 'no' if you like to mount an already present source tree of your work.

### Copy current Workspace

Creates a copy of the current workspace in the given project directory. Note that only the configuration of AnyJ are copied. No source file or .jar files are copied.

### Swing Workspace

A swing workspace is like a 'core workspace', but initially the runtime libraries for the GUI Builder are mounted. The runtime library of AnyJ consists of two classes: a LayoutManager implementation and a Helper class to locate and load images at runtime.

Note that,

- you can redistribute those runtime libraries if you own a license of AnyJ.

- It is possible to create forms, which don't need a runtime library (choose GUIBuilder tab, General, 'private Layout' checkbox). In this case AnyJ generates an inner class implementing the GUIBuilders layoutmanager. You need to implement a form's getImageForBuilder() method on your own in order to get rid of the 'ApplicationHelper' class of AnyJ's runtime library.

### Tomcat Workspace

Important: You need a JDK 1.4 in order to run the tomcat distribution delivered with AnyJ.

Follow the instructions given in the index.html file to start and debug servlets and .jsp's. Of course you will need to read the tomcat documentation. AnyJ contains a complete tomcat 4.01 distribution including documentation in [anyjinstalldir]/lib/tomcat.

### RMI Workspace

Creates a workspace demonstrating the use of RMI to create a distributed application. Note that server side classes, which should be accessible for the client remotely have to be added to the RMI panel of AnyJ's preferences.

In order to ease debugging, a class starting both: the client and the server side is created. We recommend to run and debug your distributed application this way during development, so you don't have to deal with remote debugging (though this is possible, of course).

### (Jboss/Weblogic) J2EE Workspace

Creates a workspace for use with one of the following applications servers

- Weblogic 6.1sp2

- Weblogic 7.0

- Jboss 3.0

AnyJ supports

- EJB1.x/EJB2.0 development and deployment

- Webapplication development and deployment

- Debugging of EJB's / Web Applications

- HotDeploy (change your EJB App or Webapplication without restarting the server)

The necessary DTD's to get code completion when editing the various .xml config files are delivered with AnyJ (see [anyj]/bin/dtds. You can add new DTD's by simply copying them to that directory. Note that the HelpAgent displays the DTD's comments for each tag during code completion similar to code completion in .java files.

For an introduction to EJB programming with AnyJ, see below.

## Creating a Workspace from Scratch

1. Choose 'Workspace|New Workspace' from the menu. |
2. Select 'Core Java Workspace' from the list box. Enter the directory, where the project files should be stored. |
3. Mount the workspace directory. Use Drag and Drop or 'Workspace|Mount Directory'. Choose 'Directory' from the 'Add Directory' Dialog |
4. Create a directory where you want to put your java sources. |
5. Mark your source folder for parsing and compiling. (This can also be done in 'Workspace|Preferences,Directories') |
6. [optional] If your new project requires additional libraries, add them to the classpath. (Use the '..' buttons to open the path editor). |
7. Mount all libraries for which you need coding assistance using 'Mount Directories'. You can also mount .jar files if the source is not available. Mark them for parsing. You may use Drag & Drop or use 'Workspace|Mount Directory'. |
8. [optional] Add Misc Directories (such as resource, documentation) related to your project. |
9. [optional] Set the output directory, where the compiled classes are stored if the default doesn't fit. |
10. [optional] Compile your project ('Workspace|Build All Workspace Files'), then configure one or more main classes to run and debug. |

## Creating a Workspace from existing source

1. Choose 'Workspace|New Workspace' from the menu. |
--- | ---
2. Select 'Core Java Workspace' from the list box. Enter the directory, where the project files should be saved. |
3. Drag & Drop (or use 'Workspace|Mount Directory') one or more root directories containing the source of your project. Choose 'Project Source' from the 'Add Directory' Dialog |
4. Mount all libraries for which you need coding assistance. You can also mount .jar files if the source is not available. Mark them for parsing. Use Drag & Drop (or use 'Workspace|Mount Directory') |
5 [optional] Add Misc Directories related to your project (e.g. resources, documentation). |
7. [optional] Update the source index if not done automatically. Click on the progress bar below the editor to open the source indexer window. |
8. [optional] Set the output directory, where the compiled classes are stored if the default doesn't fit. |
9. Set the class path. (Use the '..' buttons to open the path editor). |
11. [optional] Compile your project ('Workspace|Build All Workspace Files'), then configure one or more main classes to run and debug. |

# Editing

## Code Completion (Code Assist)

| Pressing Ctrl+Space in the Editor opens the code completion pop up list. Note that the HelpAgent displays JavaDoc of the selected method, if the index for that specific class has been built from .java source. If the index has been built from .jar or .class files, no javadoc will be available. Note that you also can press Ctrl-Space on already existing source in order to obtain the javadoc, to trigger auto-import (move the caret on to a valid class-name, press ctrl-space) or to get type information in the status line of AnyJ. Every time you type a '.', '(', ',' , the completion pop up is invoked automatically. Code completion + HelpAgent documentation also works with Html files. Xml and .txt files use the Default Completion Engine, which simply offers strings of the existing filetree in the code completion popup menu.
--- | ---
| To view the set of available parameters for a method, move the caret to the left of the opening brace of a method call and press Ctrl-Space.
| Note that the status line displays additional information. (Image shows status line after Ctrl-Space has been pressed).

Important: This feature requires an up-to-date and properly setup SourceIndex

## Auto Import

Move the editor caret onto a valid classname and press Ctrl-Space. If the class has not been imported in the files 'import ..;' section, the following window pops up and allows to automatically insert the required popup. If you make use of the code completion during typing of the classname, the window will also popup.

Note that there are additional ways to organize your imports (see below 'Refactoring, Generating Imports'):

## Error detection

AnyJ marks syntax errors during editing. The syntax check is performed whenever a file or part of a file is parsed (e.g. if you use code-completion or save a file). As soon to type a character in the editor, the red mark is removed so readability of the sourcecode is not hurt by this feature. Note that code completion may fail to work, if the file contains syntax errors in the method you are editing.

Important: This feature requires an up-to-date and properly setup SourceIndex

## Window Management

| The window menu offers various ways to manage the layout of AnyJ.
--- | ---
| Ctrl W or 'Window|Recent Files' pops up a list containing recently opened files.
| Note that it is easy to navigate to a definition of a class, method or variable. You should never browse classes or files clicking TreeNodes. Use these shorthands to let AnyJ open the TreeNodes for you. Press 'F1' to open the IndexViewer, which lets you quickly locate, classes, methods and variables. Use 'Goto Previous Open File' to move back to the latest edited file. Use 'Move to last line position' to cycle through recently edited positions inside a single editor.

## Inline Templates (Code Snippets)

AnyJ allows to define code snippets, which can be inserted into your File. Inside a code snippet, ‘|’ defines the position of the cursor after inserting, ($varname) allows to define dynamic values. You are prompted for each distinct variable once during insertion of the code snippet.

Note that each code snippet template creates a new entry in the 'Edit|Insert Template' menu. Since any menu item can be assigned to a keyboard shortcut or editor abbreviation (Preferences, Menus&shortcuts) this also holds true for inline-templates (code snippets).

## Bookmarks

AnyJ allows to define an arbitrary amount of bookmarks. Use 'Navigate|Add Bookmark' to add a bookmark. Bookmarks can be organized in a tree hierarchy. If a bookmark is added while a file (e.g. In the FileTree) is selected, double clicking the bookmark will open the associated file. If a bookmark is defined from within the editor, the file and the current caret position is associated with the bookmark, so double clicking will open the associated file and move the caret to the associated position.

| Bookmarks can be organized in folders. Move bookmarks and folders by using the arrow keys to select items, open and close folders. Move a selected item using 'SHIFT+[Arrow Key]'. Note that it is possible to add the content of a directory to a bookmark folder using the '+' button at the top of the bookmark panel. The content of a bookmark folder can be compiled (popup menu). Files can be started (popup menu, 'Run Selected Class').
--- | ---

## Misc Editing

| Double clicking on a brace marks the matching expression. Using Ctrl-E does the same. If Ctrl-E is pressed several times in turn, the selection is expanded to the outer matching pair of braces.
--- | ---
| Format Region (or Ctrl-R) formats a given selection or the whole file (if nothing is selected).
Double click and hold chooses word-selection mode, triple click and hold turns into line-selection mode (or Shift-Ctrl arrow keys). Ctrl-B moves to the least recent position. Ctrl-M on a selection adds / removes a comment.

# Browsing

## The Help Agent

The Help Agent displays Java Doc of the selected method or class in the file tree or class tree or a code completion popup list.
This works if the source has been added to your project files and has been marked to for parsing, since AnyJ reads the javadoc on-the-fly directly from the sourcecode. If you just have the classes or a .jar file, AnyJ can't display the JavaDoc.

| The Help Agent displays javadoc as you are selecting items in the ClassView, ClassBrowser, FileTree or the code completion popup (if the source code of the associated classes are available to AnyJ).
--- | ---
| The Help Agent also provides context sensitive help during Html editing. Note that the Help Agent is triggered whenever code completion happens. E.g. to show help for a Html tag, move the caret onto the tag and press Ctrl-Space. Note: if you are missing tags or attributes in the Html completion, define them in [anyj_installdir]/bin/doc/html/senseinf.txt.

## Opening JavaDoc

Selecting a classname and choosing

opens a html browser on the associated javadoc file, if the javadoc path is set correctly.

Important: since the format of javadoc differs depending on the JDK version, this menu item may fail sometimes. Especially the javadoc provided for download sometimes has a non-standard format. Use the Javadoc generation frontend provided by AnyJ (Tools|Generate javaDoc) to generate javadoc. The standard output of the javadoc.exe tool will be recognized by AnyJ (see 'Choosing a JDK' for an example configuration of AnyJ's javadoc generation tool).

##

## The FileTree

Java Files in the file tree can be expanded if the directory is marked for parsing. Use the popup menu to create new folders, forms and files. Clicking the icon opens the selected file in the editor. Double-Click will expand the TreeNode and open the file in the editor. Note that you can type 'into' all Listboxes and trees in AnyJ to find a specific item. The Filetree also acts as a drop target, when dragging and dropping files into AnyJ.

| Expanding of filenodes can be disabled. Note that the filetree does not display all file types, depending on the settings.
--- | ---
| Use 'Browse in Filetree' to quickly show a file in the FileTree. This menu item is available whenever a class or file is selected in the editor, classbrowser, bookmark panel, ... .

Important: for some special files (e.g. .html files), clicking the icon will open the file in the editor, double clicking the tree node will do something different (e.g. open a .html browser).

## The ClassView

The ClassView shows a class, its superclasses and the interfaces implemented by those classes. Note that also inhereted interfaces are shown.

Pressing Alt-F1 while having selected a class name in the editor opens this class in the ClassView.

Pressing Alt-2 shows the class view and sets the input focus to the listbox at the bottom, so you can immediately type a method name 'into' the listbox in order to locate it in the editor. Pressing 'Enter' will open the selected method in the editor.

Important: This feature requires an up-to-date and properly setup SourceIndex

## The Class Browser (ClassTree)

AnyJ's class browser allows to inspect the class hierarchy top down.

| Note that you never should try to locate a class by clicking tree nodes. Select a class name (e.g. Use the F1 window to locate a class) and choose 'Browse in ClassTree' from the pop up menu or global menu.
| Use the filter to remove unwanted packages. Note that you have to add required packages in the filter. E.g. If you would remove 'java.awt' in the example to the left. javax.swing.JComponent would not be shown, since java.awt.Component would miss. 'Browse in ClassTree' may silently fail, if the class you are looking for is missing (because of a filter or a wrong 'parsing' configuration).

Important: This feature requires an up-to-date and properly setup SourceIndex

## Browsing all Implementors of an Interface

Selecting an Interface and choosing 'Navigate|Find all Implementors' from the menu allows to browse all implementors (and their subclasses) of an interface.

Important: This feature requires an up-to-date and properly setup SourceIndex

## The Index Viewer

The F1-Window (or IndexViewer) shows all definintions of your current workspace's files (with 'Parse' option enabled). Just press the 'F1' key to open it on the currently selected String.

Use it to:

- edit or browse a class, without knowing the package of the class

- browse a class in the class browser without knowing the package of that class

- find the definition of a constant or method without knowing which class or interface defines it

- have a quick view on the constructors of a given class

- find out if someone overrides a method

- copy the package or the absolute filename of a class to the clipboard

- Check for double classes

## Hierarchy Analysis

The hierarchy Analyzer Window displays a single class's hierarchy. Superclasses are displayed in the table's columns, members amke up the rows. Overriden methods are displayed in the same row.

# Searching and Refactoring

Note: The performance of searching and refactoring features speeds up significantly if the filecache setting (Preferences, Common) approximately matches the size of your source code.

AnyJ supports 4 basic types of searching:

- Editor local. Matches are hilighted in the editor

- Full text search / replace. Searches and replaces in files/directories/paths

- Syntax Search. Search/Replace common Syntax constructs such as method call, Constructor call, field assignment, etc. Note that 'Syntax Search' does not do any type analysis. E.g. Searching the sourepath for all assignments to a field named 'foo' matches all assigments to a variable named 'foo'. You can use 'Typed Search' if you need full type analysis (e.g. Find all calls to e.g. '[expression with type Vector].size()').

- Typed Search. A type analysis is done. E.g. It is possible to only find usages of a specific variable or method of a class

Warning:
Syntax Search requires syntactically correct files. Unparsable file (containing syntax errors) will be marked red int the result panel of AnyJ. Typed Search/Refactoring requires syntactically correct files and an up-to-date and complete sourceindex.

You can update the sourceindex manually by using the icon (or 'Workspace|Update SourceIndex). You can verify if your sourceindex is complete (= all referenced classes of your sourcepath are known) by doing a 'Workspace|Check Workspace Settings). If AnyJ detects an unknown expression during a 'Typed Search' or renaming, the result panel will show a red line for the unknown match.

The result panel contains buttons to

- start searching (or press 'Enter' in the 'Text:'-Textfield)

- step through the search result (or [Shift] F4, 'Search|Show next/previous Error or Result')

- replace current result and step to next result

- Replace all results.
  Note that only checked items of the search result are replaced if you use 'Replace all'. Note that you can select a region, press Ctrl-H (=Search in File) to obtain a search result having matches contained in your current editor selection are checked only.

## Full Text Search

[..]

## Syntax Search

[..]

## Typed Search

[..]

## Generating Accessors

[..]

## Generating Import Statements

[..]

## Extracting Methods, Introduce Locals, Introduce Get-Methods

[..]

## Renaming Classes, Packages, Methods and Fields

[..]

# Using AnyJ's GUI Builder

## Introduction

The GUI builder enables you to quickly create Swing GUIs by means of a generic layout scheme. (Please read the respective section below as the layout scheme, though simple, is not self-explaining). AnyJ's GUI builder supports the kind of tasks which profit from visual representation & manipulation:

- instantiating components and Beans,

- laying them out,

- setting properties,

- generating event handlers.

The most important facts for hasty readers:

- The Layout of a form is stored in a XML-format '.gml'. This file is not needed at runtime.

- It uses a special layoutmanager at runtime (ScalingLayout.java, source is part of the AnyJ distribution).

- The dynamic behaviour of the Layout is set by use of the 'Resize Wizard'. To avoid the need of a runtime-library some callbacks are made to the form's class by use of the reflection API. ('getImageForBuilder', 'internationalize', 'instanttiationHook').

- AnyJ generates pure Java sourcecode each time you save a Form.

- Each form consists of a subclass of JPanel (say 'MyForm.java', and a (completely generated) class to setup the GUI ('MyFormGUI.java').

## Creating a sample workspace

We create a new workspace of type 'Swing Project'. This kind of workspace mounts two classes (ScalingLayout.java, Applicationhelper.java) required by AnyJ's forms at runtime. You can make any workspace a 'Swing'-type workspace by adding the runtime classes to the classpath.
Additionally we create and mount a directory to put our sources in and mark it to be parsed and compiled.
Now we select the directory (package) where to create the new form and choose 'File|New|Form' from the menu. We name the new form 'ATestForm'. AnyJ opens a new, empty form. The .gml file contains a description of the form (xml). It is used by AnyJ and not required at runtime.
The 'ATestForm.java' is your JPanel subclass containing the form later on. Eventhandlers are implemented here.
The 'ATestFormGUI.java' contains generated GUI-creation code. GUI-creation is separated from your main JPanel to avoid cluttering your application code with tons of Component initialization etc. .
The 'images' subdirectory may contain images. The GUI-Builder looks into this folder to look up images used in the form.
! If you use images, these ressources must be reachable using the classpath. In this example 'C:\apps\anyj3.0\anyj\projects\swing_project\source' has to be added to the classpath, in order to make the images accessable at runtime
Another possibility is to copy the images to the output directory or change the implementation of the 'getImageForBuilder' method in your form class.

## Creating Components

AnyJ has a built-in support for Swing components. Some of the listed components refer to the same swing-class using different preconfigurations. E.g. 'HtmlView', 'RichTextView' and 'PlainText' are JEditorPanes.
Since some components are rarely used without being put into a JScrollPane, common controls such as TreeView and ListBox are automatically wrapped into a JScrollPane.
To create a component, choose one from the Components tab and create it by double-clicking or pressing the 'Create' button.
Note: If there is no property of a customizers type (e.g., a textfield cannot have an image), the corresponding customizer will be disabled.
Setting properties
Properties can be set in several ways. The basic property types (such as string or integer) can be edited with the 'Properties' tab. More complex types (Font, Color, Images, Border .. ) can be set up using the 'Customizers' tab. If there is no customizer for a property, you can set up the property programatically.
Accessing Components from within your program
For access to a component from within your program, specify a name for this component (see image below). You have to save the edited form in order to prompt AnyJ to generate the corresponding variables into your source. Do not remove the code markers (e.g., '//$$varinit'...//$$endvarinit'). They mark sections into which sourcecode is generated. Do not insert sourcecode between those markers.
Adding Event Handlers
Select the component in your form and double-click an event method (in the 'Events' section of the 'Events & Properties' tab) of the GUI builder UI. AnyJ pops up the source and generates an action handler named '[id of component]_[methodname]' (e.g., 'myButton_actionPerformed( ActionEvent e )'.
Note that you have to remove the event handler source code manually if you remove an event from a component. If you decide to rename a component, it is necessary to rename the event handler methods.

## Defining the Resizing Behaviour of a Form

We think the LayoutManagers concept is laudable but a rather long winded approach for visual GUI Building. The best approach to make use of LayoutManagers is to manually write your GUI code. AnyJ uses a simple yet powerful layout scheme, more suitable for use in GUI builders. It works as follows:

- you enter the minimum size of your form,

- then resize the form to a larger size.

- AnyJ computes a transformation from the smaller layout to the bigger one.

All of AnyJs forms use this layout scheme, so you may wish to play around a bit to see what is possible. GUI's created with AnyJ's layout scheme have several advantages:

- Pixel level position control, even in dynamically resizing forms

- Possibility to create stylish forms by overlaying components (without the requirement to give the form an absolute layout).

- Memory and performance savings, since it is not necessary to create subpanels to achieve specific component layouts.

Step by step:

1. We want to layout the following form:
   Open the 'Resize Wizard' using 'Gui Builder|Resize Wizard' from the menu.

2. Layout your form to the minimum size and press 'Continue' to proceed. As our example is already of minimum size, we need to do nothing but press the 'Continue' button.

3. The second step of the resize wizard appears ('Recall' resets the previous maximum form size if present.):
   We resize the headline because it should always cover the whole width of the form. (Note that the resizing behaviour of the headline is the same as the resizing behaviour of a menu component.)
   We don't resize the upper textual field as it has the right size.
   We enlarge the text area in the middle. At least we shift the controls below the text area to the bottom:
   We press the 'Done' button of the resize wizard.

4. Now we proudly watch our result using AnyJ's feature. Note: First press 'Done' in the Wizard, only then press the 'Preview' button ! (I've just done it wrong myself....)

The resulting resizing behaviour looks like this:
Both width and height increased
Width increased only
Height increased only

## Misc

What about Frames and Windows ?
AnyJ's GUI Builder always creates JPanels. You have to manually add the Panel to a Window, Frame or Dialog. We think it is bad style to directly add controls directly to a Window (or Frame) since it is impossible to reuse your form later on as a subcomponent. Additionally you may use a form either in a Dialog or Frame, you don't have to decide this at time of form creation.
You may want to make use of the ApplicationHelper class provided by NetComputing GmbH to easily create Frames or Dialogs for your forms.
Internationalization, Cross Platform Layout

Since the sizes of component differ slightly depending on the operating system and Look & Feel, it is sometimes necessary to globally increase or decrease the size of forms and controls. This is possible by setting the “fontFakX” and “fontFakY” static variables in the class “de.netcomputing.runtime.ScalingLayout”. E.g. setting “fontFakX” to 1.1 will increase the minimum width of all controls (e.g. labels, textfields) in your forms by 10%. This can also be useful to fix internationalization issues.

If the checkbox shown above is enabled, AnyJ will create a hook which enables you to replace each string of a form. It is necessary to implement a method with the following signature in your form’s class:

    public String internationalize( String toMap ) {
        if ( toMap.equals( “Cancel”) )
            return “Abbrechen”;
        else
            return toMap;
    }

Note that the language mapping is demonstrated as an example in the method above. You are free to make use of any internationalization scheme (e.g. Ressource Bundles) in this method.

It is recommended to keep possible differences of String sizes depending on the current language in mind when layouting a form. Additionally it may be necessary to make use of the global size factors depending on the current language as described above.

If the “generate InstantiationHook” checkbox is selected you may implement the following method in your form in order to change the Class which is actually instantiated at runtime or apply some default property

    public Object instantiationHook ( Object toMap ) {
        if ( toMap instanceof JButton )
            return new MyButton();
        else
            return toMap;
    }

Adding a Bean based on a .class file (recommended)
Adding a Java-Bean from a .class file is similar to adding Beans from a .jar file. Press the 'Add' Button in the 'Components' tab of the GUI Builder and select the .class representing the Java Bean Another way to add a .class file based Bean is to select a class in the file tree (or editor) and choose 'Gui Builder|Add as Bean to component palette' from the menu.
Adding a Bean from a .jar file
Select the 'Components' tab of the GUI builder, and press the 'Add' button. AnyJ will open a dialog to select a .class or .jar file which should contain one or several beans. AnyJ scans the jar for java beans, and if everything works well the java beans become available in the GUI builder's 'Component' tab.
AnyJ will silently update your compile-classpath. If you choose to specify a different classpath for running (runtime-classpath), don't forget to update it.
Note: Some bean libraries consist of several jars which have to be imported in the correct version due to inter-jar dependencies. As an alternative, you may add these jars to the compile-classpath (Compile Options) before importing the jar. Note: AnyJ silently adds the imported bean jars to your classpath settings.
A bean is instantiated just as normal components are: double-click on the selected component, or select it and press the 'Create' button.
Working with Container Components (Tabs/Groups)
Container components are components which are able to contain other components. AnyJ offers special support for 'TabbedPane' and 'Group' boxes. As long as a container shows black pivots when selected, it acts like a normal non-container component (e.g., a button).
By couble clicking on it, a container component is 'activated'. This is indicated by the pivot elements turning red. Your working area which covered the complete form before is now restricted to the content of the active container. E.g., if you create or paste a button it will be added to the active container. This also works within nested containers, as illustrated by the graph below:
You can move components from one container to another by Drag & Drop. To add or remove 'Tabs' to a 'TabbedPane', use the Tabbed Pane Customizer.
Note: When you use the resize wizard to specify the resizing behaviour of your form, don't forget to layout all panes of a TabbedPane.
To create SplitPane's, simply define two separate forms one for upper/left, one for lower/right and add them to a splitpane programatically. The resize Algorithm used by the GUI Builder is for logical reasons not applicable to SplitPanes in-place.
Working with Images
If a selected component or bean has 'Image' or 'Icon' properties, the image customizer is enabled.
How are images found
Consider the following structure:
The MainFrame resides in the package 'propedit'.
Design Time:
The GUIBuilder's Image Customizer first looks in the images folder of the currently edited form. If this is empty (there are no .gif's) it shows the content of [workspacedir]/images. This check is done each time a component is selected in a form.
Runtime:
For each form two classes exist. The form class itself (usually a subclass of JPanel) and the generated GUI-creation class ('MyFormsNameGUI.java'). Each time a property of type 'Image' or 'Icon' is set, the GUI-creation class calls back the form class to obtain the image. This is done if and only if the form class implements a method with the following signature:

    public Image getImageForBuilder( String imageName, String packageAsPath ) {
        // load via classpath from mypackage.subpack/images/imageName.gif
        // resp. /images/imageName.gif (2cnd lookup)
        return ApplicationHelper.Singleton().getImage(
                             getClass(), "images/"+imageName
                          );
    }

By default we use our ApplicationHelper class to retrieve the image ('ApplicationHelper.Singleton().getImage(..)') which implements the following image retrieval scheme:
a lookup is made via the classpath in the package of the Form (in this example in 'propedit/images/yourimage.gif'). If that fails, a lookup is made from the package root ('/images/yourimage.gif').
You have the choice to store ressources in the same package as the form's class (which is suited for reuse, e.g. Beans) or store all ressources in the root package (well suited if the forms are unlikely to get reused and you won't deal with image copying).
If you don't want to use the ApplicationHelper class or want to implement your own lookup scheme (e.g. Applet) simply provide an alternative implementation of the 'getImageForBuilder' method.
Note: You can add the source root to your classpath, so the images are found at runtime and at design time. If you decide to deploy your application, don't forget to add them to the .jar file.

# Creating J2EE Applications with AnyJ and JBoss

## A very short introduction to EJB's

The EJB specification provides a standard way to define,implement and distribute (middle-tier) software components (EJB's). An EJB is never accessed directly by clients. Instead you define and implement interfaces, which serve as a 'view' to your EJB component. There can be different interfaces for the same EJB: One for remote clients outside the EJB's virtual machine, one for local clients running inside the same virtual machine (e.g. A web application hosted by the same appserver instance as your EJBs).

An EJB consists of

- A class ('MyBean') which implements the functionality of your software component. Depending on the type of EJB, you'll have to implement some methods required by the application server to manage your bean.

- All clients (users) of your EJB have to use an interface to access your EJB. Therefore it is required, that you define these interfaces.

- For each EJB there is a 'Factory' interface, which has to be used by clients to create instances of your EJB. These interfaces are called 'Home' interfaces (replace 'Home' by factory in your mind).

- For each EJB there is an instance interface, which owns the method actually available in your EJB. These interface are called 'Remote' or 'Local' interfaces.

- There are two flavours to access your EJB: 'Remote' and 'Local'. If you are using an EJB remotely (using the 'Remote' interfaces), all arguments of a method call are copied (serialized). You pass everything by value. If you are using an EJB locally (within on VM instance), the arguments of a method call are passed normally.

So we get the following flavours of interfaces for your software component 'MyBean':

'MyBeanRemoteHome'
– The factory interface for remote clients (Note: often called just 'MyBeanHome' without the 'Remote').
'MyBeanRemote'
– instances of your EJB can be accessed using this.

'MyBeanLocalHome'
– The factory interface for local clients.
'MyBeanLocal'
– local instances of your EJB can be accessed using this.

Please note that these interfaces are used by clients to access your one and only EJB component. You don't have different implementations for each interface.

You might think your software component (EJB) consists of two classes: a Factory and an implementation class. That's not the case: your EJB has to implement both: The factory interface and the 'real' interface at once. The methods of the factory interfaces are not actually implemented, they are defined using a naming convention. Factory methods usually start with 'ejb' or 'ejbHome'. So if your 'MyBeanRemoteHome' interface has a method 'getXY', your EJB has to implement 'ejbHomeGetXY' in order to be a valid EJB.

There are different types of EJB components:

- SessionBeans
  Used to provide functionality. Somewhat a default type. They can be stateful or stateless.

- EntityBeans
  Used to model an entity (e.g. a Database row). They can organize reading/writing to a data source by themself (=Bean Managed Persistance, BMP) or let the applicationserver do this (=Container Managed Persistance, CMP)

- Message Driven Beans
  For messaging (e.g. JMS).

Depending on the basic type of your EJB, there are several methods which have to be implemented by your EJB (lifecycle management, persistence/transaction management).

EJB's need a container to live in. The EJB container is provided by an application server. The EJB-container provides lifecycle management, transactions, CMP, marshalling, etc. for EJBs.

Of course this is not a sufficient introduction. You'll need to read more about EJBs. There are numerous books and websites covering EJBs out there.

## Running the examples

1. Download Jboss 3.0 and install it.

2. Start AnyJ and create a new Workspace selecting 'Jboss j2ee workspace' in the workspace-type dialog.

3. Open the 'index.html' file in a browser and follow the instructions provided there.

You now have an properly configured workspace for EJB development. You may want to delete the samples provided by the workspace if you not longer interested in them.

## How the J2ee workspace is organized

The j2ee workspace contains two 'modules': An EJB and a Web module. You can simply delete a module if you don't need it (e.g. You don't want to use EJBs or don't need a web client application).

The EJB module

The deploy directory contains all files which will be deployed to the applicationserver. This includes the configuration files in 'META-INF' and the classes which are copied automatically from the output directory to the deployment directory (which files are actuall copied has to be set in 'Preferences, Deployment Helper'. The source directory contains your EJB components as well as the source of helper classes and the EJB interfaces generated by AnyJ.

The Webapplication module

This contains the client of your EJB module. The deploy directory contains all files which will deployed to the applicationserver. Non-java classes such as .jsp .html and config files are located here. The source directory contains your servlets and the source of helper classes. By changing the webmodule deployment configuration in 'Preferences, Deployment Helper', it is possible to to hold .html and .jsp files (even the web.xml) in the source folder. They are copied to the deployment directory before the .war archieve is created if you choose 'Deploy Web Module' or 'Deploy all modules' from the Workspace Menu.

## EJB development cycle

The graph above illustrates modifications done by the programmer (blue) and necessary tasks to deploy and test EJBs.

## Creating a Session Bean (step by step)

1. Create a j2ee workspace as described above |
2. Create a new package for your EJBs |
3. Create a SessionBean from a template |
Generate the local/remote interfaces Note: be sure the file does not contain syntax/compile errors when generating the EJB interfaces. Note: If you only need Remote or only Local interfaces for your EJB, just edit the //@EJB directive: AnyJ won't generate Local interfaces, if the word 'local' is removed. |
5. Adjust the ejbmodule/deploy/META-INF/ejb-jar.xml file |
6. Ajust the jboss.xml [weblogic.xml,..] |
Move the caret on the '<local-jndi-name>' tag and press control-space. The Helpagent displays a description for the tag. |
7. Do a 'Build all workspace files' (enforces the creation of the outputdirectory if your project never has been compiled yet. This step can be left out if the output directory exists) |
Adjust the deployment settings (only necessary if this is the first EJB in your package). The deployment helper is invoked internally by AnyJ right before the deployment of your files to the application server takes place. Note: Since the Deployment Helper is a multi-purpose deployment tool of AnyJ, pressing the 'Run Deployment' button here won't deploy the file to the app server, it just will copy .class files from your output directory ('[..]\classes') to the modules' 'deploy' directory. Use 'Workspace|Deploy All Modules' to run EJB deployment.
9. Start the application server. Verify it started without errors. |
10. Deploy your modules. |
The application server's output (jboss) should show the following lines or something similar: 23:25:56,843 INFO [MainDeployer] Undeployed file:/D:/work/anyj/jboss/jboss300/jboss-3.0.0/server/default/deploy/ejbmodule.jar 23:25:56,853 INFO [MainDeployer] Starting deployment of package: file:/D:/work/anyj/jboss/jboss300/jboss-3.0.0/server/default/deploy/ejbmodule.jar 23:25:56,963 INFO [EjbModule] Creating 23:25:56,993 INFO [EjbModule] Deploying ExampleBean 23:25:57,013 INFO [EjbModule] Deploying MainSession 23:25:57,053 INFO [EjbModule] Created 23:25:57,063 INFO [EjbModule] Starting 23:25:57,143 INFO [EjbModule] Started 23:25:57,143 INFO [MainDeployer] Successfully completed deployment of package: file:/D:/work/anyj/jboss/jboss300/jboss-3.0.0/server/default/deploy/ejbmodule.jar
11. We add two methods to our EJB (ExampleBean.java). Note that it is required to add the //@EJB tags, else these methods are private to your EJB's implementation. Save. Then regenerate the interfaces using: The ExampleRemote, ExampleHome interface should contain two more methods now. |
        String mTest;

        //@EJB:remote,local
        public void init( String s)
        {
            mTest = s;
        }

        //@EJB:remote,local
        public String getString()
        {
            return mTest;
        }
12. We change the sample client to access and test our EJB: (File: SampleServlet.java in the webmodule source tree) |
         try {
                [.. MainSession example .. ]
                // tutorial remote example:
                ExampleHome exHome = (ExampleHome) PortableRemoteObject.narrow(
                    context.lookup( "ExampleRemote" ),
                    ExampleHome.class
                );
                ExampleRemote exRemote = exHome.create();
                exRemote.init( "Hello" );
                out.println( "<b>result of calling getString() </b><br>" );
                out.println( exRemote.getString() );
                out.println( "<BR><br>" );

                exRemote.remove();

                // tutorial local example:
                ExampleLocalHome exLocalHome = (ExampleLocalHome) PortableRemoteObject.narrow(
                    context.lookup( "ExampleLocal" ),
                    ExampleLocalHome.class
                );
                ExampleLocal exLocal = exLocalHome.create();
                exLocal.init( "Hello Local" );
                out.println( "<b>result of calling getString() </b><br>" );
                out.println( exLocal.getString() );
                out.println( "<BR><br>" );

                exLocal.remove();

            } catch ( Exception ex ) {
                ex.printStackTrace();
            }
As you might experience, dealing with all those 'remote', 'local' and 'home' interfaces is rather errorprone.
13. Do a 'Build All' and a 'Deploy All modules' |
DoubleClick the index.html at the root of your work directory to open it in the browser. Click the link to test our new modifications. (Warning: clicking the icon will open the .html file in the editor, double click the text) |

## Trouble Shooting

EJB development is a rather errorprone and xml-ish task, especially for beginners. Be prepared to discover various bug's in the application servers (though AnyJ is bugfree, of course) and receive cryptic error messages from the application server ('method not found' without further explanation, ...). At least we discovered some major problems during integration:

- Your outputdirectory must not be added to the application servers classpath. HotDeploy does not work in this case (you'll have to restart the appserver in order to let changes take effect). The j2ee workspaces initally configure this correct.

- AnyJ's initial configuration only adds the minimal set of .jars to your pathes. If you make use of advanced functionality provided by the application server, you'll have to add a lot of other jar files to your classpath.

Weblogic 7.0

- It is sometimes necessary to remove all files generated by ejbc from the deployment directory (Attention: do not delete your META-INF directory containing your ejb.xml and other config files).

- It is recommended to always deploy all modules after a change. Redeploying the EJB module without redeploying the webmodule can lead to runtime errors.

- Changing the configuration files of the appserver may require a restart.

Jboss 3.0

- We didn't manage to define new 'create' methods for our ExampleHome interface ('method not found' exception). The same EJB deployed without problems with weblogic 7.0, though.

## Debugging

If you are running a webapplication accessing EJBs, just start the server in the debugger. Because of the appservers HotDeploy feature, you don't have to restart it again and again. Just start once, deploy+debug many.

If you are developing a standalone EJB-client:

- Start the application server from the menu ('Tools|External Tools|Start [Jboss/Weblogic] Server'), the standalone client in the debugger to debug the client code.

- Start the application server in the debugger and the client as external tool in order to debug your EJBs. (Note: you'll have to add an external tool for your client.

# Versioning

## Snapshots

pending

## Using CVS with AnyJ

Quick introduction to CVS
CVS is an open source command line based version control system. If you know other version control systems, here are some significant differences to most other systems:

- CVS puts all files into a repository ('CVSROOT'). You get a local copy of the repository (or parts of the repository) to work on the files.

- CVS is capable to work on whole file trees.

- In CVS, a developer does not lock files. CVS uses an optimistic locking mechanism to allow concurent modification of a project. Whenever you want to save ('COMMIT') your changes from a local copy to the repository, it checks whether other developers have modified the same sections in a file since you last updated your local copy from the repository (this is called 'CONFLICT').
  If a conflict is detected, CVS puts control back to you and you have to manually merge the two modification into one version. After that you can try again to commit your changes.

- Words known from other version control systems such as 'Check in' and 'Check out' have a different meaning in CVS.

- The basic working cycle is:
  - UPDATE your local copy from the repository to get changes made by other developers.
  - EDIT your local copy
  - COMMIT your changes to the repository to make them available to other developers.

- during COMMIT you may have to MERGE changes made by other developers, since they have modified the same files. Merging is done automatically by CVS. If you edited the same section as other developers, you'll have to resolve a 'CONFLICT' before you can try again to commit the changed file.

- CVS supports common features known from other vc systems such as branches, tagging ('labeling'), ...

- CVS can be run in file-based mode, the repository is mounted as part of your file system.

- CVS can be run in client server mode, in this case your cvs client (=the commandline tools) communicates using TCPIP with the repository.

For more information on CVS see menu 'Help|CVS Home' and 'Help|CVS Help'.
AnyJ's built in CVS support
AnyJ supports daily used funtions such as UPDATE, COMMIT, DIFF, creating a CVS-project, adding/removing files. There is no special support to configure CVS (this is textfile based), use the CVS command line tools to do this. You should read the original documentation of CVS to understand what is going on.
AnyJ does not do any hidden or magic things. All CVS commands executed by AnyJ's GUI-front end are logged in the output panel of AnyJ.
Creating a cvs-playground
We create a new workspace to be able to play around a bit. We mount a temporary directory to the new workspace.
Creating a CVS repository using AnyJ
First, it is necessary to create a repository and init it.
After pressing the 'Init' button, you have created a fresh CVS repository. See below on how to edit the config files. Also notice the CVS-log showing which command has been executed.
Note that you should not edit the files in the repository directory. You edit the configuration files of CVS by getting them, editing them and commiting the changes to the repository.
Initially getting a CVS project from the repository
Modification of the configuration files of CVS (text files) works exactly the same as working with any other project ('modules'). The CVS configuration files are a kind of of a 'built-in' project (named 'CVSROOT'). So we are able to demonstrate both in the following section: usage of CVS and some important settings of CVS.
Create a folder (e.g. c:\temp\cvsconfig), select it in the file tree and choose 'Versioning|Initial CVS Checkout' from the menu. Note that the combo box at the top is empty since this is your first checkout, so AnyJ doesn't know anything about the repository. Type 'CVSROOT' (==CVS-internal project name for CVS-config files) as project name and press the 'Checkout' button.
Now you made an initial checkout. From now on you can use 'update' and 'commit' on this directory (from within AnyJ use the 'CVS Commit and Update Center').
Often it is a good idea to ignore specific file-types by version control. CVS looks for a file name 'cvsignore' which contains patterns describing which files should be ignored by version control. We create a file 'cvsignore' ('File|New|Empty File') in our local copy of the configuration files and add some entries:
Another good idea is to mark some file types as binary files. If a binary file is handled as source code, CVS would probably destroy the binary file by doing keyword substitution and CR/LF conversion.
This can be configured in the 'cvswrappers' file of CVS.
Now its time to commit the changes we made to the configuration files to the repository. Therefore we select the parent directory of the CVS configuration files and choose 'Versioning|CVS Commit and Update Center'
Since we changed one file ('cvswrappers') it appears in the 'Local modified' list box. Selecting the file and pressing the commit button puts this file to the repository. Since we added one file ('cvsignore') it appears in the 'New/Add/Rem' list box. Selecting the file and pressing the add button schedules the file for addition. It has to be commited to be added 'really' to the repository.
Selecting the 'cvsignore' file in the filetree an selecting 'Versioning|CVS Differences' opens the Diff Viewer. By selecting one revision in the table at the top, differences to your local version can be viewed. By selecting two revisions in the table a diff between those revisions can be seen. If only one row is selected, a diff to your local working copy is shown.
Creating a CVS project from existing source
For test purposes we copied some source to our temporary workspace. We select the root of the source-tree and choose 'versioning|Create CVS project'.
Behind the scenes AnyJ does the following:
1. the original directory is renamed (ensure there is no file-lock on this directory or one of its subdirectories).
2. the renamed directory is imported into the repository
3. the newly created CVS module is updated from the repository to the original directory you selected for import. Therefore files marked by 'cvsignore' are not present in this directory, you'll have to get them from the renamed original. It is recommended to backup the renamed directory to another place.
We now create two checkouts of the new project to simulate concurrent modification (create folder 'developerA', 'developerB', use 'Versioning|Initial CVS Checkout').
At first we act as 'developerA' and modify two files by adding some comments. If we now open the 'Commit and Update Center' on the project root ('DeveloperA') directory we'll see the following:
You can diff your local version against the repository by using the 'Versioning|CVS Differences' as described above. Developer A commits his changes to the repository by pressing the commit button.
Updating your file tree
Now we act as developer B. We modify some other files, and open the 'Update and Commit Center' on the root directory of developer B's local version.
Pressing the 'Update' button would update the local version of Developer B from the repository. Entries in the 'Needs Update' Listbox indicate, that the version of the repository is newer than your local copy. But we don't update since we want to create a conflict situation.
Merging and Conflict handling
Developer B now changes the same files as developer A without updating his local copy. We open the update center again (or just press the 'Check Status' button).
We now have created two conflicts (developer A put modifications to the repository, developer b changes the same files, without getting the actual version from the repository). If we press the 'Update' button, the version of the repository would be copied to the local version of developer B. The changes of developer B would get lost. Pressing the 'Merge' button merges the changes from the repository into the local version of developer B (changes of Developer A and Developer B are merged). The two merged files move from the 'Conflict' list box to the 'Locally modified' list box. You are encouraged to review the merged files, since auto merging may produce compile errors. If both developers modify the same lines in a file, CVS does not merge, but inserts both versions marking them with '>>>>>>>>>>' and '<<<<<<<<'.
The merged files now can be commited to the repository the usual way.

##

## Integration of other VCS

Integrating Visual Sourcesafe

define two external tools

- Name: 'sscheckout'
  Working Dir: ($currentDir)
  Command line: ss checkout -I ($currentFile)

- Name: 'sscheckin'
  Working Dir: ($currentDir)
  Command line: ss checkin -I ($currentFile)

Set the "project based on directory" CheckBox in the SourceSafe GUI. Note that any External Tool named "Checkout" can be invoked automatically by AnyJ.
Ensure the ss commandline utilities are found in the path of (OS-environment variable).

# Misc

## Generating JavaDoc

[..]

## Deployment support

Deployment of applications or beans can be a time consuming issue, since due to the nature of java a lot of files have to be handled and copied correctly.

AnyJ’s deployment Helper allows to automate this task and lets you easily create jar files.

Basically the Deployment Helper works in two steps:

1. The files or directories added for deployment are copied to a single directory. It is possible to specify filters to leave out specific files. This is done to ensure that your sources, classes and ressources get located below a single root directory (the output directory).

2. A jar file can be generated from that copy.

During copying AnyJ provides some intelligence to put files at the right place:

- .java files
  .java files are copied to [outputdir]/package/subpackage/file.java, where 'package' and 'subpackage' are given from the package of the .java file.

- .class files
  .class files are deployed to [outputdir]/package/subpackage/file.class, where 'package' and 'subpackage' are given from the package of the .class file.

- .jar files
  If you add a .jar file to the list of deployment directories, the jar file will be automatically unpacked to [output dir]/. This is useful to create executable jars, which contain their libraries or beans.

- All other files are deployed relative to the Ressource Base directory. This means if the RessouceBase is set to "c:\myprog" and the output dir is "d:\tmp\deploy\", the File "c\myprog\images\splash.gif" would be deployed to "d:\tmp\deploy\images\splash.gif". Note that you can add several Ressource Bases (since AnyJ2.0) ‘;’ separated.

The Deployment Helper does not clean up the deployment directory, it is possible to add files to the output directory manually in order to add them to the resulting jar. The jar is written to “[outputdir]\..\xy.jar”.

Filter

The deployment wizard works on a directory level rather than file level. There are two filters for each directory.

- The Exclude Filter (“copy all files except .jpr,.anyj;..” )
  To prevent specific files from deploying, set a exclude filter for the appropriate directory (e.g. ".proj;.txt;makefile"). The filter is a ';' separated list of file endings, all files ending with one of the strings listed in the filter are excluded from deployment. Note that each directory has its own filter strings. If this field is empty, no files will be excluded.

- The Include Filter (“copy no files except .java,..”)
  If this filter is set to “all”, all files of this directory will be copied to the output directory (except they are excluded by the exclude-filter).

These two filters are applied in order. At first it is checked whether a file passes the include filter, after that it is checked that the file is not excluded by the exclude filter.

Output Dir

This is the directory, where the files are copied to. The .jars are created in [outputdir]\..\xy.jar.

Main Class

By specifying a (fully qualified) Main Class it is possible to create executable jar files (double click on win32 or run with “java –jar myjar.jar”).

Bean Classes

By specififying a list of bean classes it is possible to create Java Beans which can be imported into other IDE’s. Don’t forget to add the “ScalingLayout” class (the GUI Builders layout class) and (optional) the ApplicationHelper class (only required if you make use of it.

# Extending AnyJ

## External Tools

Any external program can be called up from within AnyJ. Tools defined here appear in popup menus in the ”Tools” submenu. Among the possibilities is the integration of an external version vontrol system such as RCS, CVS, or SourceSafe. Note that usually some configuration needs to be done on an external version control system (especially on SourceSafe, RCS) in order to make it work properly with AnyJ.

Note: AnyJ looks for a tool named ”CHECKOUT” each time you try to edit a read-only file. If a tool named ”CHECKOUT” is found, it is executed automatically.

Note: On win32 you have to prepend a 'cmd /c' t your tools commandline in order to execute a shell executable.
This is how a tool is added:

- Press Add New to create a new tool.

- Enter a name for it (Tool Name). This name is used for the menu item later on. It has no relation to the name of the program called.

- Specify the working directory the tool is to run with. You can insert context-sensitive variables with the combobox on the right (the meaning of those variables is explained below).

- Specify a commandline, including the name of the program to call. Again it is possible to insert environment variables using the combobox.

- Specify whether the program’s output should be redirected to AnyJ’s console or not.

The values of the ”variables” are context dependent:

- ($workspaceDir)
  is replaced by the directory of the current workspace.

- ($currentFile)
  is replaced by the name (without directories) of the eventually selected file (resp. by ””).

- ($currentDir)
  is replaced by the directory of the eventually selected file/dir. Therefore ($currentDir)\($currentFile) constitute an absolute path of a selected file, e.g. in the filetree or in the editor.

- ($currentClass)
  is replaced by the fully qualified name of the eventually selected class (e.g., in the editor).

- ($currentLineNr)
  is replaced by the number of the line containing the cursor in the editor (when tool is called up from within the editor).

- ($currentTextSel)
  is replaced by the currently selected text in the editor (when tool is called up from within the editor).

- ($ask:Text to display)
  asks interactively each time the tool is called up using the text entered behind ”ask:”.

## Scripting AnyJ

The current API is intended to extend AnyJ (e.g. to create small helpers in the editor) or to integrate third party products (e.g. versioncontrol).

### What you can do using scripts

- Define new Menu Items

- Access the current selection of the IDE

- Access some basic settings of the current workspace

- Manipulate the document of an Editor

- (limited) remote control of AnyJ

### What is used as Scripting Language ?

The scripting language is Java. In 4.0 we dropped the use of the 'Dynamic Java' java interpreter [memory leaks, performance]. Anyway existing AnyJ 3.x scripts are easy to port. Scripts can be developed interactively (without restarting AnyJ after each change).

### Writing a Service (Menu Item)

A service is similar to an 'Action' in swing. A service shows up in the GUI as a tool bar button or menu item. See the API javadoc for further explanation.

- Choose 'Tools|Scripting Support|Mount Scripting Directory' from the menu. The directory containing scripts should get mounted to your workspace.

- Choose 'Tools|Scripting Support|new Scripting package'

- Follow the instructions in the template code:
  - Define when your menu item should be enabled.
  - Implement the action to be done when the menu item gets selected.
  Use the helper scripts Tools|Scripting Support|Dump selected objects and Tools|Scripting Support|Dump Environment to discover which objects are selected (depends on the last selection made in the IDE).

- Choose 'Tools|Scripting Support|Compile Scripts' to compile your scripts. Ensure there are no error messages.

- Enable your scripts choosing 'Tools|Scripting Support|Enable/Disable Scripts'

- Choose 'Tools|Scripting Support|Reload Scripts' to enforce AnyJ to update the newly compiled classes

- Test your new menu item

- make changes if necessary and again use 'Tools|Scripting Support|Compile Scripts' and 'Tools|Scripting Support|Reload Scripts' to make the changes active

- submit your script to support@netcomputing.de ;) .

- assign a shortcut the usual way (Preferences|Menus and Shortcuts).

### Accessing external .jars from your Script

All .jar file copied into the scripts directory are automatically added to a scripts class path.

### Provided Scripts

AnyJ comes with some sample scripts, among them a set of scripts making up a rather complete interface to the CCC Harvest version control system. Use these as examples to roll your own ..