Java Browser


Overview
========
The Java Browser supports both ObjectStore and PSE Pro Java
databases. It allows you to inspect, modify, and display objects in
databases. The browser also enables you to create classes, add new
classes to databases, create databases, and create new instances
in databases. When you browse a database, you can view the database
schema (the description of the classes whose instanaces are stored
in the database), the set of roots defined for the database, or all of the
extents defined on persistent classes.

Note that the Java Browser is beta software. See the top-level
CHANGES.src.htm file for instructions on where to send your comments.


Running the Browser
===================
This section explains how to set your CLASSPATH variable and how
to invoke the browser.


Setting your CLASSPATH for the browser
-------------------------------------
To run the browser, your CLASSPATH variable must contain an entry for 
the swing.jar file from Swing 1.0.3. You can download Swing from the
Swing Connection on the JavaSoft web site:

http://www.java.sun.com/products/jfc/tsc/index.html

In addition, pro.zip and tools.zip also need to be in your CLASSPATH. 

For example on Windows, if you place the PSE Pro distribution in the 
default directory C:\ODI\PSEPROJ, and the swing.jar file in 
C:\SWING-1.0.3, you need the following entries in your CLASSPATH: 

CLASSPATH=C:\ODI\PSEPROJ\pro.zip;C:\ODI\PSEPROJ\tools.zip;C:\SWING-1.0.3\swing.jar 

For UNIX, if you place the PSE Pro distribution into /usr/local/psepro, 
and the swing.jar file in /usr/local/swing-1.0.3, you need the following
entries in your CLASSPATH: 
 
CLASSPATH=/usr/local/psepro/pro.zip:/usr/local/psepro/tools.zip:/usr/local/swing-1.0.3/swing.jar 
 
Invoking the Browser
--------------------
To invoke the browser when installed PSE Pro is installed in C:\odi\Pseproj,
use the following command:

      java COM.odi.tools.Browser

To invoke the browser so that it displays information for a particular 
database, add the name of a database to the command line. For example, 
the following command invokes the browser and displays information for 
the Products database:

      java COM.odi.tools.Browser Products.odb

You can also invoke the browser by specifying osjbrowsedb on the command line, 
for example:

      osjbrowsedb

If you want to invoke the browser so it displays information about a specified
database called parts, then you would use:

      osjbrowsedb parts.odb

Note that if windows.jar is in your CLASSPATH, then the browser dynamically 
loads the Windows-specific display. If motif.jar is in your CLASSPATH, 
then the browser dynamically loads the Solaris-specific display. Otherwise, 
the browser uses the default Swing display that is platform independent.


Contents of this File
=====================
This file provides information about browser options and displays.

- File menu options allow you to create, open, and delete databases.

- View menu options control whether you are looking at roots or extents.

- Insert menu options allow you to create different kinds of objects.

- Schema menu options allow you to modify classes already stored
  in the database.

- Collection inspectors display information relevant to maps, lists,
  sets, and queries.

At the end of this file, there are descriptions of known problems.


File Menu Options
=================

New
------
Creates a database. The browser prompts you to enter a file name. It
then creates the new database and opens it for manipulation.

Open
----
Opens a database for browser manipulation. The browser prompts you to
enter the name of the database you want to open. This database must be
a valid PSE Pro (.odb file) or ObjectStore database. In the browser,
only one database at a time can be open.

Close
-----
Closes the currently opened database.

Destroy
-------
Deletes the currently opened database.

Save 
---- 
Commits changes you made with the browser to the currently opened
database. This includes changes to instances in the database, as 
well as definitions of new classes. 

Reset
-----
Undoes changes you made with the browser to the currently opened
database. This includes changes to instances in the database, and
schema changes. In other words, if you defined any new classes,
these definitions are deleted.

Exit
----
Ends the browser process.


View Menu Options
=================

Roots
-----
Displays the database roots in the main browser window. Double click
on a value to begin displaying and navigating through the object
graph. For simple objects, a window appears that displays the object's
field values. For collections objects, a collections inspector
appears. In a scrollable frame, it displays the toString() value of
each element. Double click on an element to see its field values.

Afer displaying the roots, you can use the right mouse button to
select a root and then assign a new value to it or to destroy it.

See Collections Inspector, toward the end of this file, for more
information about editing and querying collections.

Extents
-------
Displays the extents of any persistent classes defined in the
currently opened database. The display groups classes by package
name. When you select a class, the browser displays a Table Inspector
that allows you to examine the extent for that class. See Table
Inspector, toward the end of this file, for more information.

View Object History
-------------------
Displays a list of the objects that you have inspected. When you first
open a database, the history list is empty. When you close a database,
or select reset, the browser clears the history list.

Use Single Window in Navigation
-------------------------------

Select the "Use Single Window in Navigation" toggle to set the browser
to display all results in the same window. The default is that the
browser creates a new window each time you browse a new object.

Insert Menu Options
===================

Create Root
-----------
Creates a new root in the currently opened database. The browser
prompts you to enter a name for the root. The browser creates the root
with an initial null value. Right click on the null value cell to
paste a new value for the root.

New Instance
------------
Creates new object instances in the currently opened database. You
select the class that represents the type of object that you want to create. 
The browser groups classes by package to make it easy for you to
select the class you want.

After you select a class, the browser displays an object inspector
with default values set for the fields of the created object. Edit or
paste to initialize the object. 

The browser always pastes the new object to the clipboard by reference.

The Edit menu option in the New Instance window allows you to copy the
value or reference of the newly created object to the clipboard. 

New Array Instance
------------------
Creates arrays of objects. You select the type of array you want and
the browser prompts you to enter the dimension and the length of the
array. An array inspector appears with default values for the objects
in the array. You can edit or paste individual cells to initialize the
array.

The type of the array determines the type of objects the array holds,
for example, int. The dimension specifies the nesting level of the
array. For example, type int and a dimension of 2 results in an array
of arrays of int. The length determines the size of the first
array. So, for example, if you specify type int, a dimension of 2 and
a length of 10, the resulting array has 10 slots with null arrays in
each slot. You can then use the array inspector to initialize the
inner arrays with arrays of int.

The browser always pastes the new array to the clipboard by reference.

The Edit menu item in the array viewer allows you to copy the array to the
clipboard so that you can paste the array itself into other objects or roots.

Collection
----------
Creates new collections. You can create sets, such as OSHashSet or
OSTreeSet, maps, lists, and collections, such as OSHashBag and
OSVector. When you create a collection, the browser displays a Set,
Map, or List Inspector that shows the empty collection. You can then
use copy and paste to populate the collection.

The browser always pastes the new collection to the clipboard by reference.


Schema Menu Options
===================
In the browser, you can define new classes and define fields in new
classes. However, you cannot modify existing classes.

Create New Class
----------------
Defines a new class. The browser prompts you to enter a name for the
new class. You must specify the fully qualified class name, including
the package name. If you do not specify a package, the browser places
the class in the No Package package. After you specify the class name,
the browser displays a window in which you can add fields to the
class.

The browser does not automatically add the class to the current
database.  This is because the class might contain references to other
new classes. The browser can add such a class only after all the
classes referenced by the new class have been created. Select the Add
to Schema option to actually add new classes to the database
schema. Note that the browser creates the byte code for the new class
without generating the source code for it.

Select Add Field to add new fields. Double click on the Field Type or
the Field Name entry to create new fields. You can also modify the
name and type of fields. When you enter the type of the field, you
must specify a fully qualified class name, for example,
"java.lang.String". For primitive types, you just have to specify the
name, for example, "int".

When you are finished, select Done to save the changes. This does not 
add the class to the database schema. To add the class to the database
schema, you must select the Add to Schema menu option.

Select the Cancel button to abort the creation of the new class.

Select the SuperClass button to dynamically create a superclass for
the new class you just created.

Add to Schema 
------------- 
Saves a class definition in the currently opened database. The browser
prompts you to specify the name of the class that you want to add to
the database. This class can be an external class that is defined in
your class path or it can be a new class that you created with the 
Create New Class feature of the browser.

View Schema
-----------
Displays a list of the packages and classes in your class path. Double
click on a package to expand its contents. Double click on a class to
display a description of that class, including its superclasses,
fields, and methods.


Help Menu Options
=================
Select About to display a dialog box with the current version number 
of the browser.


Inspectors
==========
An inspector appears when you want to browse a collections
object. There are four kinds of collections inspectors:

- Map Inspector
- Set Inspector
- List Inspector
- Table Inspector

The browser uses the Set Inspector to display collections other than
lists and maps. The Table inspector displays the results of queries or
extents in a table format.

Map Inspector 
-------------
The Map Inspector displays the key value and the element value for
each element in the map. Edit the key value of an element by clicking
on the key value and typing a new value. Select Enter after you finish
editing the value. You can display the fields of an element by double
clicking on the value for that element.

The Edit menu item in the Map Viewer has several options:

- Paste takes the object reference or value from the clipboard and
  creates a new map entry. The browser uses the clipboard reference or
  value as the key and a default value for the map entry value. To set
  the value for the map entry, right click on the default value and use
  the paste menu option to set a new value.

- Remove removes the selected element from the map.

- Copy Map by Value places a serialized copy of the map on the
  clipboard.  This is not generally recommended since copies of
  collections can be very large.

- Copy Map by Reference places the object reference of the map on the
  clipboard.

- Paste Into Map copies a map object from the clipboard and pastes
  all the key/value pairs into the current map. If the clipboard
  does not contain a map object, this option does nothing.

You can use the right mouse button with individual keys and values to
copy and paste a key or value, respectively. In addition, the remove
menu item removes the map entry associated with the selected key or
value.

Set Inspector
-------------
The Set Inspector displays the results of calling the toString() 
method on each element in the set. Double click on an element
to display its fields.

The Edit menu item in the Set Inspector has several options:

- Paste takes the object reference or value from the clipboard and
  creates a new set element. The browser uses the clipboard reference or
  value for the set element.

- Remove removes the selected element from the set.

- Copy Collection by Value places a serialized copy of the set on the
  clipboard.

- Copy Collection by Reference places the object reference for the set
  on the clipboard.

- Paste Into Collection copies a collection object from the clipboard
  and pastes all the elements into the current collection. If the
  clipboard does not contain a collections object, this option does
  nothing.

The Query menu item allows you to query the collection. Select Pick or
Select depending on whether you want just the first element returned
or all elements that satisfy the query, respectively. After you select
Pick or Select, the browser prompts you to enter the query
string. Select OK to execute the query. For a Pick query, the
inspector displays the result in a simple object inspector. For a
Select query, the browser displays the Table Inspector.

You can view query performance statistics. The browser displays a message
window with statistics about the query execution. You can see the time
taken for the query, the potential indexes that could be used and the
indexes that were actually used in the query.

The Index menu item in the Set Inspector allows you to add or drop an
index. This option is valid only for COM.odi.util.OSTreeSet
objects. Select Add or Drop from the Index menu. The browser prompts
you to specify the index path. The path must be a public field or
function.

Use the right mouse button to select an element and copy that element
by value or by reference to the clipboard. You can also remove
elements from the set with the right button Remove menu option.

List Inspector
--------------
The List Inspector displays an integer index along with the result of
a call to the toString() method on each element in the list. Double
click on an element to display its fields.

The Edit menu item in the List Inspector has several options:

- Paste takes the object reference or value from the clipboard and
  creates a new list element. The browser uses the clipboard reference 
  or value for the list element value. The browser inserts the new 
  element at the end of the list.

- Paste here takes the object reference or value from the clipboard and 
  creates a new list element. The browser uses the clipboard reference 
  or value for the list element value. The browser inserts the new element 
  before the currently selected list element.

- Remove removes the selected element from the list.

- Copy Collection by Value places a serialized copy of the list on the
  clipboard. 

- Copy Collection by Reference places the object reference for the
  list on the clipboard.

- Paste Into Collection copies a collection object from the clipboard
  and pastes all the elements into the current list. If the
  clipboard does not contain a list object, this option does
  nothing.

The Query menu item allows you to query the list. Click on Pick or
Select, depending on whether you want just the first element returned
or all elements that satisfy the query, respectively. After you select
Pick or Select, the browser prompts you to enter the query string.
Select OK to execute the query. For a Pick query, the browser displays
the result in a simple object inspector. For a Select query, the
browser displays the result in the Table Inspector.

You can view query performance statistics. The browser displays a message
window with statistics about the query execution. You can see the time
taken for the query, the potential indexes that could be used and the
indexes that were actually used in the query.

Use the right mouse button to select an element and copy that element
by value or by reference to the clipboard. You can paste new elements
into the list with the Paste Here menu item. The new element appears
directly before the currently selected element. You can also remove
elements from the set with the right button Remove menu option.

Table Inspector 
--------------- 
The Table Inspector displays the results of queries or extents in a
table format. The columns in the table map to the fields in the object
that is the element type of the target set of the query or the type of
extent that you are displaying. The last column is always the result of
a call to the toString() method on the element that is being displayed.

Edit the field values of objects by typing, copying or pasting into
individual cells in the table.

The right mouse button allows you to do various things depending on
the type of value in the cell. For example, with an object reference
you can copy it by value or reference, set it to null, or paste into
the cell. If there is a null value in the cell, you can paste into it.

The right mouse button also allows you to remove a column from the
table. This can be useful when displaying results. It also allows you
to remove the current row from the table.

If you are viewing an extent, the right mouse button for the last
column (the reference) allows you to destroy the object that is
currently selected. This removes it from the class extent and from the
database. This can be dangerous since it can result in dangling
references.

The File menu item dumps the contents of the table in an external
format. You can dump the contents in an Excel format, which is
basically a comma-separated file, HTML format, or XML format. In each
case, the browser prompts you to enter the name of a file that will be
created and populated with the output from the table.

Use the Query menu item to query the items in the table.