
                      VisualAge(R) for Java(TM)
                             Version 3.0

                        Java Tool Integration 

                            RELEASE NOTES


Table of Contents
-----------------

1.0 Integrating tools written in Java
    1.1 Limitations and known problems
        1.1.1 Concurrent use of classes by tools and loaded user code
        1.1.2 Testing tool code inside VisualAge for Java
        1.1.3 Small empty window appearing before prompter dialogs
2.0 Newly added APIs 
    2.1 ImportCodeSpec.useSharedResDir
    2.2 Workspace.changeOwner, Workspace.getValidUsers
    2.3 ProjectEdition.purge
    2.4 PackageEdition.purge
    2.5 Repository.compact 


1.0 Integrating tools written in Java
-------------------------------------

1.1 Limitations and known problems

1.1.1 Concurrent use of classes by tools and loaded user code

VisualAge for Java does not support concurrent loading of classes
with the same name from different sources (that is, some from the 
workspace and some from the file system). This issue is not likely
to be a problem in most application development scenarios, however,
it can cause problems for tool developers. Tools frequently generate
code against a set of runtime libraries that need to be loaded into 
the workspace (otherwise the internal compiler will tag the generated
code in error). The same set of runtime classes may also be needed
for execution of the tool itself. Since the classpath setting for
tool execution is limited to the tool installation directory (plus
system libraries), the runtime classes also have to be present in the
tool installation directory.  Concurrent execution of the tool, and
its generated code will result in an attempt to load the same class
from the workspace and the file system. Typically, this will
manifest itself as an exception indicating inability to find a class.
Terminate the offending programs and rerun them one at a time.

Tool developers should avoid this situation by sharing the runtime
code loaded into the workspace. Tool writers can use the IBM IDE
Utility class libraries API to check if a copy of the required
runtime is loaded, and if it is not, instruct the user to load the
runtime (likely packaged as a Java feature).  Alternatively, the tool
code can cause a copy of the required runtime to be loaded from the
repository as part of tool execution. The following code sample
illustrates the API calls required (no error checking):

// assume import com.ibm.ivj.util.base.*;

   Workspace ws = ToolEnv.connectToWorkspace();

// Check for existence of prerequisite runtime

   String prereq = "My Required Runtime Project";
   Project proj = ws.loadedProjectNamed(prereq);

// Load from repository if needed.
// Alternatively,terminate execution and instruct user to load runtime

   if (proj == null) {
      Repository rep = ws.getRepository();
      ProjectEdition[] projList = rep.getProjectEditions(prereq);
      projList[0].loadIntoWorkspace();//assume exactly 1 in repository
      proj = ws.loadedProjectNamed(prereq);
   }

// Add required project to current classpath

   Object[] current = ws.getClassPathEntries();
   Object[] newPath = new Object[current.length+1];
   newPath[0] = proj; // as first entry on classpath
   for (int i=0; i<current.length; i++) newPath[i+1] = current[i];
   ws.setClassPath(newPath);


1.1.2 Testing tool code inside VisualAge for Java

While under development, tools are typically tested in the 
workspace by running the main() method of the tool. When doing
so, ensure that the classpath is properly set for the tool
execution. Open the Properties dialog for the main tool class.
The tool classpath must include the following two projects:

   IBM IDE Utility class libraries
   IBM IDE Utility local implementation

The first project is shipped with the repository, as well as with 
the file system (ide\project_resources\IBM IDE Utility class 
libraries). The second is only shipped in the file system 
(ide\project_resources\IBM IDE Utility local implementation).


1.1.3 Small empty window appearing before any prompter dialog

When using prompter dialogs, you may notice a smaller window appearing 
initially but gets hidden behind the dialog.   This window can be safely
ignored.


2.0 Newly added APIs 

These APIs were added but were not documented:

2.1 ImportCodeSpec.useSharedResDir

	public boolean useSharedResDir()

A "true" return code indicates the project's setting of  the shared 
project_resources directory, if one is used, will be observed.

   Returns:
	boolean


	public void useSharedResDir(boolean setting) 

Indicate if the project's setting of the shared project_resources 
directory, if one is used, should be observed.

    Parameters: 
          setting - boolean 



2.2 Workspace.changeOwner, Workspace.getValidUsers

	public void changeOwner(String newOwner, String password) throws IvjException

Change workspace owner.  

       Parameters: 
	newOwner -  The New owner of the workspace, using the full name
	password -  Specify null if none used



	public String[] getValidUsers()

Returns all valid user names

      Returns:
	String[]


2.3 ProjectEdition.purge

	public void purge() throws IvjException

Purge this edition of the Project


2.4 PackageEdition.purge

	public void purge() throws IvjException

Purge this edition of the Package


2.5 Repository.compact 

	void compact() throws IvjException

Compresses current repository (Pro and Entry support).
Only versioned elements in the repository are preserved during a compaction.
Compacting the repository will remove any open editions in the repository.


	public void compact(String target) throws IvjException

Compresses and clones to a new repository (Team support).
Only versioned elements in the repository are copied during a compaction.
Compacting the repository will create a new repository.  The current/original
repository is not affected by the compaction.  Target cannot be the current
repository and cannot already exist.


       Parameters: 
	target - Name of the new repository to compact to.
	
