=============================================================================
                Together/J import/export addin 1.3 for

      VisualAge(R) for Java(TM), Enterprise Edition for Windows(R),

                               Version 2.0, 3.0

                              README Information
=============================================================================


Table of Contents
=================

   1.0 Features summary
   2.0 Installation Procedures
   2.1 Installation Procedures (MS Windows)
   2.2 Installation Procedures (Linux)
   3.0 Work with addin
   3.1 Sample import/export to Visual Age
   4.0 Known problems
   5.0 Future improvements


1.0 Features summary
====================

  TJ works with  VAJ  in the  same way  as  with Revision Control   Systems -
  one can get files   from VAJ Workspace,  work  with them  in TJ,  put  them
  back to VAJ    Workspace,  change   in   VAJ   Workspace,  put   into   VAJ
  Repository. Other  team   members  can  get   the  changed  files  from VAJ
  Repository into  their local  VAJ Workspace,  work with  them, export to TJ
  and so on.

  The  difference   between  VAJ   and  a   "normal" Revision Control  System
  from TJ's point  of view   - "normal" RCS  works  in  one phase -   Checkin
  from  local  file  system  to  RCS  -  Checkout  from RCS to the local file
  system.

  By working with VAJ there are two phases:
    a)  "Checkin"  (Import)  from  local  file  system  into  the  local  VAJ
       Workspace using TJ-VAJ smart import, then
    b) put a new version into the VAJ Repository using VAJ.

  It's  a   lightweight  support   using  the   VAJ  Tool  API. It could   be
  called "smart  Import/Export"  because   TJ  works  with  sources  exported
  from VAJ, then the changes are imported back into VAJ.

  The differences to the standard Import/Export:

  1. safer and easier for the user

    Standard  Import/Export   asks  user   each  time   for  directory    and
    settings. It's  error prone.   TJ   Import/Export stores  settings in the
    VAJ workspace and uses them on the consequent invoking.

  2. Nicer for the VAJ Repository

     Only changes  (changed files)  are imported  it avoids  creating of  new
     Open Editions / Scratch Editions for each file on each Import

  3. Possibility to import/export TJ diagram and project files

     Standard  import/export  doesn't   work  with  TJ   diagram  and project
     files. Together/J converts  these files to   a form reasonable  from the
     VAJ point of  view  before  they  are  imported,  and  back  to standard
     TJ form after export.  So, you can store  your diagram in repository  as
     usual files.

  4. Possibility to skip some files during the import/export process

     It is possible to skip some files from import/export process.

  5. Import/export statistics

  6. Possibility to export specific VAJ class information

     VAJ-specific class   information like    "Developer Name"   or  "Version
     Name" can be exported   and represented as  Together/J  design comments.
     So, you  can   work   with   version,   author   and  other  information
     from  the VAJ repository in the Together/J Inspector.


2.0 Installation Procedures
===========================

  Before installing the TJ import/export  add-in, you should have Visual  Age
  for Java installed on your computer. It is strongly recommended to  install
  Visual Age 3.0 with  JDK 1.2 to be  able to use all  the existing features,
  but current version of the add-in can be used both with Visual Age 2.0  and
  Visual Age 3.0 plus JFC 1.0.3.


2.1 Installation Procedures (MS Windows)
========================================

  Exit Visual Age if running.

  Run  setup  file  (<TogetherHome>\lib\VisualAgeInstallation\TjVAge.exe) and
  wait. Setup will install the Together Add-In for IBM VisualAge for Java.

  After installation you should have subdirectory
  com-togethersoft-vaj-cmdline in ide\Tools directory in Visual Age
  installation.

  If you want to work only with projects, you should rename
  ide\Tools\com-togethersoft-vaj-cmdline\smallDefault.ini to
  ide\Tools\com-togethersoft-vaj-cmdline\default.ini


2.2 Installation Procedures (Linux)
===================================

  Stop Visual Age if running.

  Unpack the Visual Age add-in archive located at:
     <TogetherHome>\lib\VisualAgeInstallation\TjVAge.tgz)
  into the Visual Age home directory using the command:
     "tar xvf <TogetherHome>\lib\VisualAgeInstallation\TjVAge.tgz".

  When  the  unpacking  process  is  finished  you  should  have subdirectory
  com-togethersoft-vaj-cmdline  in   ide\Tools  directory   in  Visual    Age
  installation.

  If you want to work only with projects, you should rename
  ide\Tools\com-togethersoft-vaj-cmdline\smallDefault.ini to
  ide\Tools\com-togethersoft-vaj-cmdline\default.ini

  Note  that  you  have  to  install  Visual  Age  tool  integration  API for
  successfully working with the add-in on Linux.


3.0 Getting started
===================

 - Set the TJ working directory for the selected project.
   Use "Tools/Together J/Project  Settings" menu item  in project node  popup
   menu;

 - Create packages, classes and interfaces in selected project using VAJ

 - Export project from VAJ to Together/J.
  Use "Tools/Together J/Export project"  menu  item.  Before   starting   the
  export operation you are prompted  "Do you want to delete  Together project
  file before export?". Answer  "yes"  if you  want to have exactly  the same
  state as in VAJ.  Once export operation has  been finished, you will  see a
  message resembling  the following:

         Export operation finished
         12 Processed file(s)
            (including 6 Together special files)
         0 file(s) cannot be exported
            (including 0 Together special files)

 - Start TJ,  open the  project in selected directory and make  some changes.
  Create some additional diagrams.

 -  Import  project  from  Together/J  into VAJ.
   Use "Tools/Together J/Import project". You will be  asked "Do you want  to
   clean project directory after import?". Answer "yes" if you don't plan  to
   work  with  these  files  in  future.  Once  the import operation has been
   finished, you will see something like this:

         Import operation finished
         12 Processed file(s)
         Imported:
            0 older as on the media
            12 no timestamp
            (including 6 Together special files)
         Not imported:
            0 remained unchanged
            0 unable to import
            (including 0 Together special files)
         12 Open edition(s) created

Note, that one additional package has been created in your workspace:
   "TogetherJDesignFilesDirectoryFor<YourProject>",  where  <YourProject>  is
   the  name  of  the  Project  you  are  importing in. This package contains
   converted TJ diagrams files.  That allows you to  have more than one  copy
   of the same diagram files in different projects.

 - Change to  Together working directory,  export the VAJ  project to it  and
   open the Together project  in this directory. Now  you have two copies  of
   the TJ project and one storage for them in VAJ repository.

 - Importing non-java files into the repository.
  Besides TJ diagram files, you may want to import some other non-Java  files
  into the repository for storage. You may add the file 'special.ini' to  the
  directory where your project  located. All you need  to place in that  file
  are strings like:

       ext=<extension>

  ...where <extension> is the extension of  the non-java file you want to  be
  imported into the repository. If there are no such files in the  directory,
  default extensions would be used. Note  that if you place this file  in the
  project directory, all the special  file extensions will be read  from this
  file. So you should add all the Together/J special file extensions used  in
  this project into this file.

 - Skipping some files from the import/export process
  You may  want to  exclude some  special files,  created during working with
  Together/J, from the import/export process.  So you may add the  extensions
  of these files into 'special.ini' file like

       skip=<extension>

  where extension is the extension of the file you don't want to be  imported
  to the Visual Age repository.

 - Exporting Visual Age-specific class information.
  You  can  export  Visual  Age-specific  class  information  when you export
  project  files.   You  may   add  the   following  construction   to   your
  'special.ini' file:

       developer=<prefix for this information>
       versionName=<prefix for this information>
       versionStamp=<prefix for this information>
       owner=<prefix for this information>

  Where  <prefix  for  this  information>  is  a  prefix which will be placed
  before a  corresponding value  from the  Visual Age  repository in  javadoc
  block comment before the class source. Just specify Together/J design  tags
  that  you  want  to  use  for  Visual  Age-specific  class  information  in
  'special.ini' file, e.g.,

       developer= * @author
       versionName= * @version

  and import the project to Visual  Age. On every successive export you  will
  be able to work with  corresponding information from Visual Age  repository
  in your source files and in Together/J Inspector.


3.1 Sample import/export to Visual Age
==========================================

 - Create new project called CashSales in your Visual Age for Java workspace.

 - Invoke Tools->Together J->Project Settings popup menu for created  project
   and  set  <Together  Home>\samples\java\CashSales  directory  as a project
   directory for this project.

 - Perform import  using Tools->Together J->Import  Cash Sales project  popup
   menu item. Then  you can see  Cash Sales together  sample project imported
   to a Visual Age workspace.

 - Version imported project.

 - Specify another directory as  a project directory for Cash  Sales project
   in Visual Age.

 - Perform export  using Tools->Together J->Export  popup menu item  for Cash
   Sales project. Then you can see that special Visual Age information  about
   all the exported types will be  added into design comments for classes  as
   values of "@author" and "@version" javadoc-style tags.


4.0 Known problems
==================

 - Notice,  that while  working with  the remote  repository you will receive
   an error message if you   haven't the required permissions  to  add files.
   So if you want several users   to work with the  remote repository  and to
   have  the  possibility  to  add  files  to  the shared project, apply more
   permissions for them.

 - Only .java source files can be imported/exported to Visual Age. So do  not
   try to work with files with other extensions. You have to specify non-java
   files extensions in special.ini to inlude them into import process.

 - You can correctly execute import/export procedure only for one project  or
   packages/classes of one project.


5.0 Future improvements
=======================
