Installation Instructions

Visual BSF v3.1x

Table of Contents

1. Installation

2. Requirements

3. Updating the classpath

4. Running the Mapping Tool

5. Available Editions

6. Specifying an Alternate Repository Directory

7. Java2 Security

8. JDO Support

9. XML Support

10. Sample Applications

11. Tested Configurations

12. Support Information

13. Feedback and Ordering

 

1. INSTALLATION

The Visual Business Sight Framework™ (VBSF) binaries and its documentation are distributed in two separate compressed files. The binaries are included in the file named vbsf.zip. This file includes both the Enterprise and Professional editions with the JDBC database service.

The main documentation file is named vbsfdocs.zip, and contains this file, the License Agreement, the Mapping Tool Guide, the Programmer's Guide, the API Reference, and source code samples for both the local and distributed versions. All documentation in the main docs file is in HTML format. The Mapping Tool Guide and the Programmer's Guide can also be obtained in Acrobat PDF format by downloading the file vbsfpdf.zip .

The steps to install VBSF in your computer are outlined below:

1. Create a new directory in your computer where VBSF will be copied ( e.g., c:\vbsf ).

2. Copy the binaries zip file, documentation zip file(s), and any optional database service files to the directory just created.

3. Unzip the files (the order is not important). The following files and subdirectories will be created in the new directory:

2. REQUIREMENTS

VBSF requires a Java 2 Runtime Environment for both the persistence layer and the Mapping Tool. As of v3.0, the JDK 1.1.x is not supported.

For best performance we recommend running VBSF with the VM included in the JDK 1.3.1 or JDK 1.4.1. Earlier Java2 versions may also be used with VBSF. However, we do not recommend using the JDK 1.2.0, JDK 1.3.0 or JDK 1.4.0 environments.

3. UPDATING THE CLASSPATH

On a development machine where you will need both to run the mapping tool and be able to persist your classes at runtime, you must add the name of the installation directory (if using the default repository directory to store schemas) and the names of all four VBSF jar files to your CLASSPATH environment variable. For example, if you installed VBSF in a directory named c:\vbsf, then you would need to add the following entries to your CLASSPATH:

c:\vbsf;c:\vbsf\vbsf.jar;c:\vbsf\jdbcs.jar;c:\vbsf\maptool2.jar;c:\vbsf\schema.jar

On a machine where you only need to run the mapping tool the vbsf.jar and jdbcs.jar files are not necessary. On a deployment machine where the mapping tool is not run, the maptool2.jar file is not necessary. As stated in the license agreement, all VBSF jar files except for maptool2.jar can be freely redistributed with your applications.

To run the sample applications, you must also add the samples subdirectory ( e.g., c:\vbsf\samples ) to the CLASSPATH.

You may also have to set the class path directly in your IDE:

Under Visual Cafe from the pull down menu select Project, then Options, click on the Directories tab, make sure Show directories for displays Class Path, and add the names of the VBSF jar files as shown above. Alternatively, you can edit the sc.ini file located in the Visual Cafe bin directory so the new CLASSPATH applies to all projects.

Under Visual J++ from the pull down menu select Tools, then Options, click on the Directories tab, make sure Show directories for displays Class Files, and add the names of the VBSF jar files as shown above.

For other IDEs see their respective documentations.

4. RUNNING THE MAPPING TOOL

To run the mapping tool use the following command:

java com.objectmatter.bsf.mapping.toolgui.MapTool

The mapping tool requires that the maptool2.jar file, the schema.jar file, and the installation directory (if using the default repository directory to store schemas) be present in your CLASSPATH . To be able to reverse engineer Java classes you must also have the parent directory where the class files reside present in the CLASSPATH.

There is a batch file named maptool.bat located in the installation directory which can be used to run the mapping tool under windows.

Although the proper manifest information is present in maptool2.jar, you cannot execute this jar by using the java -jar option or by double-clicking on the jar file under windows. This is due to the fact that jars executed in this manner do not have access to the environment's CLASSPATH because the JVM overwrites it by setting the java.class.path system property to the executable jar file itself (plus any other jar files and directories specified in the Class-Path property of executable jar's manifest). The mapping tool needs access to the environment's CLASSPATH in order to locate the repository directory (unless you specify an alternate location), and to be able to search and load Java classes for reverse engineering. However, under windows it is possible to create a batch file that runs the mapping tool and associate this batch file with the .schema extension, so that double-clicking on a schema file executes the batch file. This approach is demonstrated in the automaptool.bat batch file included in the distribution binaries.

The mapping tool can accept the name of a schema to load or work on, and various command line parameters as shown below:

Usage: java com.objectmatter.bsf.mapping.toolgui.Maptool [schema] [options]

Where schema is the name of the schema to load or work on.

Options are:
-i<input file with path>      Imports a text schema into schema.
-e<output file with path>     Exports schema to the specified output file.
-c<package>                   Compares schema to the classes in package.
-u<package>                   Updates schema with the classes in package.
-t<input file with path>      If placed before the -d/-s tags, specifies a template.
                              Multiple templates separated by commas may be specified.
-p<package name>              If placed before the -d/-s tags, specifies the package
                              name of the classes to use for generation.
-s<output directory>          Generates source code for all classes in schema.
-d<output file with path>     Generates a DDL script code for all classes in schema.
                              Multiple output files separated by commas may be
                              specified if multiple templates are specified.
-g                            Loads the GUI after performing the specified task(s).
-n                            Loads the GUI and connects to the database with the
                              parameters specified in the schema configuration.
-?                            Displays this help screen.

WARNING: The import and update options will overwrite the specified schema.
Multiple options may be specified. Options are executed in the order found.

If only the schema name is supplied, the GUI is automatically loaded. If any other options are specified, the GUI is not loaded unless the -g or -n options are specified. For example, the command below loads the contactdemo schema and brings up the GUI:

java com.objectmatter.bsf.mapping.toolgui.MapTool contactdemo

The command below generates source code under the c:\vbsf\source directory and a DDL script in the c:\vbsf\sql directory for all classes in the contactdemo2 schema, and returns to the operating system without loading the GUI:

java com.objectmatter.bsf.mapping.toolgui.MapTool contactdemo2 -sc:\vbsf\source -dc:\vbsf\sql\contacdemo2.sql

The command below generates source code for all classes in the posdemo schema against 2 source code templates (one for a class and one for an interface), and puts the resulting sources under the c:\vbsf\source directory:

java com.objectmatter.bsf.mapping.toolgui.MapTool posdemo.schema -tc:\vbsf\schrepository\template5.tmpl,c:\vbsf\schrepository\template6.tmpl -sc:\vbsf\source

The command below generates 3 DDL scripts for all classes in the posdemo schema, each against a different template:

java com.objectmatter.bsf.mapping.toolgui.MapTool posdemo.schema -tc:\vbsf\schrepository\createtablesddl.tmpl,c:\vbsf\schrepository\droptablesddl.tmpl,c:\vbsf\schrepository\grantddl.tmpl -dc:\vbsf\sql\createtablesddl.sql,c:\vbsf\sql\droptablesddl.sql,c:\vbsf\sql\grantddl.sql

The command below generates source code only for the classes in the posdemo schema that belong in the vposdemo.engine package. Each class is generated against 2 source code templates, and the resulting sources are placed under the c:\vbsf\source directory:

java com.objectmatter.bsf.mapping.toolgui.MapTool posdemo.schema -pvposdemo.engine -tc:\vbsf\schrepository\template5.tmpl,c:\vbsf\schrepository\template6.tmpl -sc:\vbsf\source

5. AVAILABLE EDITIONS

VBSF is available in two editions: Enterprise and Professional. The Enterprise Edition features a global shared cache. Both editions are distributed in the same binaries, but only one is active during execution.

The evaluation version is set to run in Enterprise Edition mode by default. If you wish to evaluate the Professional Edition instead you can invoke the static Server.setProfessionalMode() method to instruct VBSF to run in Professional Edition mode. This method must be invoked prior to creating any Server objects.

The Server.setProfessionalMode() method can also be used in the licensed Enterprise Edition to force VBSF to run in Professional Edition mode.

6. SPECIFYING AN ALTERNATE REPOSITORY DIRECTORY

Mapping information defined using the mapping tool is saved in files with an extension of .schema (e.g., contactdemo.schema). Schema files are saved by default in a repository directory named schrepository. This directory is created by default under the VBSF installation directory. Because VBSF searches the environment's CLASSPATH in order to locate the default repository directory, the directory may be moved to anywhere in your hard drive as long as its name is not changed and its parent directory is included in the CLASSPATH.

You may specify an alternate directory where schema files reside by using the vbsf.repository command line system property when the mapping tool is brought up. For example, the command below loads the mapping tool specifying that schemas files are to be saved to and loaded from the c:\MySchemas directory:

java -Dvbsf.repository=c:\MySchemas com.objectmatter.bsf.mapping.toolgui.MapTool

The vbsf.repository system property can also be used at runtime to indicate to the persistence layer where schemas reside. In addition, you may specify the full path of the schema file at runtime, or even load the schema as a resource from a jar file. For details, please see the API Reference.

If you specify an alternate repository directory there is no need to add the name of the VBSF installation directory to your CLASSPATH.

7. JAVA2 SECURITY

The Java 2 platform security mechanism requires that all applications that run under a security manager must be explicitly assigned permission to use system resources. If your classes have private, protected, or package access attributes or constructors that VBSF must persist or access, then you must explicitly grant the VBSF code the permission to do so.

To grant VBSF the access it needs to access private, protected, or package access attributes or constructors, edit the java.policy file using a text editor and add the following lines:

grant codeBase "file:c:/vbsf/-" {
    permission java.security.AllPermission;
};

grant codeBase "file:c:/java/classes/-" {
    permission java.security.AllPermission;
};

For example, if the JDK 1.2 is installed in c:\jdk1.2, then the java.policy file would be located in the c:\jdk1.2\jre\lib\security directory. The first grant block assigns all code executed from the c:/vbsf directory access to all system resources (assuming that VBSF is installed in c:\vbsf). The second grant block is used to assign your classes access to system resources. In the above example your code runs from the c:\java\classes directory. Change this directory to reflect the actual codebase directory for your classes. For additional information please consult the JDK documentation.

8. JDO SUPPORT

VBSF provides an implementation of the JDO PersistenceManagerFactory, PersistenceManager, Extent, Transaction and InstanceCallbacks interfaces. Currently missing is support for the JDO Query language, which is planned for implementation by v3.1.

VBSF support for JDO is at the API level and not at the spec level. VBSF cannot follow the JDO spec 100% because the spec requires that OR mapping tools post-process Java classes or source code. According to the JDO spec, it is in this post-processing that the persistence code gets added to the persistence classes. More specifically, the post-processing procedure adds code to the persistence classes in order to implement a JDO interface that the persistence layer can call upon for persistence operations. Using this approach your source code and your compiled classes do not match.

In contrast, VBSF is a dynamic tool that does not intrude on your persistence classes by forcing a post-processing procedure. As a result, it is impossible for VBSF, or any OR tool based on reflection, to implement the spec 100%. Our implementation of JDO tries to follow the API as thoroughly as possible. However, due to JDO's post-processing centric approach, there are some methods or concepts that have no meaning in VBSF. In addition, VBSF includes an "extended" JDO API to access VBSF functionality that the spec does not address.

The VBSF JDO specific interfaces are defined in the com.objectmatter.bsf.jdo package, which is fully documented in the API Reference. A JDO version of the client class in the POS Demo sample application described in section 9.10 below is also included. This class is named vposdemo.client.JDOPOSApp. The JDO POS Demo sample application is a good example of a portable application that is independent of VBSF.

9. XML SUPPORT

VBSF supports XML in the mapping tool as well as at runtime when persisting your classes. In the mapping tool, mapping schemas and configurations can be saved in XML format. To save an existing binary schema to XML format, simply use the File->Save As menu option and enter the name of the schema with an extension of xml (e.g., contactdemo.xml). To save an existing configuration use the [Save as File] button and enter the name of configuration with an extension of xml. The mapping tool can also save to binary format, by either specifying the appropriate extension (.schema and .config) or by not specifying an extension, when saving the file. Schemas and configurations will save to the same format they were loaded in (XML or binary) when using the File->Save menu option.

At runtime, the persistence layer can convert object graphs to XML documents, and XML documents to object graphs. This allows persistent objects to be retrieved from the database as XML documents and updated in the database from XML documents. XML-to-Class and Class-to-XML transformation mappings may be defined in order to adapt to any XML format required by external systems.

To utilize any of the XML features of the mapping tool and persistence layer you must update the CLASSPATH to include the sax.jar, jaxp-api.jar and xercesImpl.jar files from Sun's Java API for XML Processing (JAXP) package, which is freely available from Sun at:

http://java.sun.com/xml/

If you will not be using any of the XML features in VBSF, then the XML jar files listed above are not required to be present in the CLASSPATH.

10. SAMPLE APPLICATIONS

VBSF includes many sample applications, each designed to demonstrate different concepts. Each sample application includes its own Microsoft Access 2000 database file. If you have an earlier version of Access or want to use another database, you can create and populate the tables manually by referring to the tables.htm and tables.sql or <tableName>.txt files located in each sample subdirectory. The sample applications must be compiled into byte code prior to execution.

Before running each sample make sure you specify the following in your IDE:

• That the project is an application (as opposed to an applet).
• The name of the starting class containing the main method.

10.1. Contact Demo Application

This sample is a personal contact management application that maintains a contact's addresses and locators (phone numbers, e-mail addresses, etc.) and categorizes contacts as friends or business associates. It contains the following business classes:

• Contact is class that owns the Address and Locator classes (one-to-many aggregation), and references a Category (to-one association).
• Category class.
• Address and Locator are owned classes.

It demonstrates the following concepts:

• Object references and contained object references
• Ownership and owned collections.
• Object queries including class joins, ad-hoc & constrained queries using OQuery and a specialized query object.
• Retrieving objects as enumerations.
• Validity checks.
• Handling of images and large text.
• Transaction control.
• Named Custom SQL.
• Saving/Retrieving Objects in XML format.

Before running this sample, you must create an ODBC datasource named Contact that points to the contact.mdb database file in the vcontactdemo subdirectory. The contact demo sample application uses the mapping schema file contactdemo.schema located in the repository directory. This file was created and can be edited using the mapping tool.

Note: the ODBC datasource must be named Contact because this is the URL that has been specified in the database configuration option of the contactdemo.schema file. If you use another datasource name, make sure to edit the contactdemo.schema file to specify the new URL.

The application contains two packages: vcontactdemo.client and vcontactdemo.engine. The vcontactdemo.engine package contains the four business  classes described above. This package also contains a Database class which is not required to run the sample, but is included as an example of how to define mappings entirely in code by subclassing VBSF's Database class. The vcontactdemo.client package contains two client applications that use the business objects in the vcontactdemo.engine package to display a list of contacts, categories, locators and addresses, and to perform various update operations. The client applications are named vcontactdemo.client.ContactApp and vcontactdemo.client.ContactXMLApp. The ContactXMLApp demonstrates the XML support in VBSF by saving and retrieving object graphs in XML format.

Note: Before running the contactdemo sample applications please change the parentDir variable in ContactApp.java and ContactXMLApp.java to the full path where the sample application is installed.

10.2. Contact Demo2 Application

This sample is a modified version of the above contact management application that categorizes contacts by creating specific subclasses for each type. It contains the following business classes:

• Contact is an abstract class that owns the Address and Locator classes (one-to-many aggregation), and references a Company (to-one association).
• PersonalContact is a class that extends Contact and uses Subset mapping.
• BusinessContact is a class that extends Contact and uses Subset mapping. This class demonstrates self-associations by referencing another BusinessContact (its supervisor) in a one-to-one association, and a collection of BusinessContacts (its supervised contacts) in a one-to-many association.
• ThinContact is a class that uses a Superset mapping and references a Company (to-one association).
• Address and Locator are owned classes.
• Company is a class that represents a company that a Contact and ThinContact works for.

It demonstrates the following concepts:

• Superset class-to-table mappings.
• Use of filters to model a simple inheritance tree.
• Abstract class ownership (Address & Locator are owned by Contact).
• Class joined, ad-hoc, and constrained queries for Subset and Superset objects.
• Use of the AggregateOQuery class to execute SQL aggregate queries.
• Named Stored Procedures.
• Concurrency columns.
• Implementation of the ConcurrencyAware interface.

Before running this sample, you must create an ODBC datasource named Contact2 that points to the contact.mdb database file in the vcontactdemo2 subdirectory. The contact demo2 sample application uses the mapping schema file contactdemo2.schema located in the repository directory. This file was created and can be edited using the mapping tool.

Note: the ODBC datasource must be named Contact2 because this is the URL that has been specified in the database configuration option of the contactdemo2.schema file. If you use another datasource name, make sure to edit the contactdemo2.schema file to specify the new URL.

The application contains two packages: vcontactdemo2.client and vcontactdemo2.engine. The vcontactdemo2.engine package contains the above persistent classes. The vcontactdemo2.client package represents a client application that uses business objects in the vcontactdemo2.engine package to display a list of contacts, categories, locators and addresses, and to perform various update operations. The starting class containing the main method is named vcontactdemo2.client.ContactApp.

10.3. Contact Demo3 Application

This sample application is a version of the first contact management sample application modified to demonstrate composite ID support. All classes, except for the top AddressBook class, are mapped to tables that have multi-column primary keys.

This application is further split up into two sub-applications:

1. The persistent classes in the vcontactdemo3.engine package use OReference and OCollection attributes to maintain relationships. The  vcontactdemo3.client.ContactApp is the client application that manipulates the persistent classes in this package.
2. The persistent classes in the vcontactdemo3.engine2 package do not use attributes in the persistent classes to maintain relationships. Instead methods of the Database class are used to maintain and traverse relationships. The  vcontactdemo3.client.ContactApp2 is the client application that manipulates the persistent classes in this package.

Before running this sample, you must create an ODBC datasource named Contact3 that points to the contact.mdb database file in the vcontactdemo3 subdirectory. The contact demo3 sample application uses the mapping schema file contactdemo3.schema located in the repository directory. This file was created and can be edited using the mapping tool.

Note: the ODBC datasource must be named Contact3 because this is the URL that has been specified in the database configuration option of the contactdemo3.schema file. If you use another datasource name, make sure to edit the contactdemo3.schema file to specify the new URL.

10.4. Company Demo Application

This simple application tracks a company's users, departments, and locations. It contains the following business classes:

• Company is a class that owns the User, Location and Department classes (one-to-many aggregations).
• User is an owned class that references its Location and Department. (to-one associations).
• Location is an owned class that references a collection of the Users assigned to each location. (one-to-many association).
• Department is an owned class that references a collection of the Users assigned to each department. (one-to-many association).

It demonstrates the following concepts:

• Object references and ownership.
• Use of  referenced collections to implement one-to-many associations.
• Event registration and notification.

Before running this sample, you must create an ODBC datasource named Company that points to the company.mdb database file in the vcompanydemo subdirectory. The company demo sample application uses the mapping schema file companydemo.schema located in the repository directory. This file was created and can be edited using the mapping tool.

Note: the ODBC datasource must be named Company because this is the URL that has been specified in the database configuration option of the companydemo.schema file. If you use another datasource name, make sure to edit the companydemo.schema file to specify the new URL.

The application contains only package: vcompanydemo. The starting class that represents a client and contains the main method is named vcompanydemo.CompanyApp.

10.5. Company2 Demo Application

This is a modified version of the company demo sample application that demonstrates the following concepts:

• How to specify relationships using the referenced type and arrays (as opposed to OReference and OCollection).
• Pre-fetching collections to the cache to improve performance.
• Accessing attributes via get/set methods.

This application uses the same ODBC data source of the company demo sample.

The application contains only package: vcompanydemo2. The starting class that represents a client and contains the main method is named vcompanydemo2.CompanyApp.

10.6. Join Demo Applications

The three joindemo applications demonstrate various ways to model many-to-many associations using join tables. Each application demonstrates a different type of join:

• Transactional join.
• Transparent join.
• Self-join.

Before running these samples, you must create three ODBC datasources named TransactionalJoin, TransparentJoin, and SelfJoin  that point to the part.mdb database file in each of the sample subdirectories. The join demo sample applications use the mapping schema files named transactionaljoindemo.schema, transparentjoindemo.schema, and selfjoindemo.schema located in the repository directory. These files were created and can be edited using the mapping tool.

Each application contains only package: vjoindemo.xxxxjoin (where xxxx is either: transactional, transparent, or self). The starting class that represents a client and contains the main method is named vjoindemo.xxxxjoin.PartApp.

10.7. Employee Demo Application

This sample application demonstrates how to create a class that is both an owner and an owned class at the same time. This allows the creation of hierarchical trees in which all nodes belong to the same class. It contains only one persistent class named Employee which encapsulates an employee of an organization. If an Employee object is a supervisor, it holds an owned collection of other Employee objects that it supervises. If an Employee object is supervised, it holds a reference to its Supervisor object. An Employee can be a supervisor and in turn be supervised. The attributes of the Employee class are set and read by the persistence layer via get and set methods instead of by direct variable access.

It also demonstrates the following concepts:

• A CONTAINED OBJECT attribute that references a contained object mapped to multiple columns within the persistent class.
• A CONTAINED BLOB OBJECT attribute that references a contained object mapped to a binary column.

Before running this sample, you must create an ODBC datasource named Employee that points to the employee.mdb database file in the vemployeedemo subdirectory. The employee demo sample application uses the mapping schema file employeedemo.schema located in the repository directory. This file was created and can be edited using the mapping tool.

Note: the ODBC datasource must be named Employee because this is the URL that has been specified in the database configuration option of the employeedemo.schema file. If you use another datasource name, make sure to edit the employeedemo.schema file to specify the new URL.

The application contains only package: vemployeedemo. The starting class that represents a client and contains the main method is named vemployeedemo.EmployeeApp.

10.8. ID Demo Application

This is a modified version of the original contact management application described in section 10.1 modified to demonstrate the following concepts:

• ID Generation using a ID sequence table.
• ID Generation using an long ID generator object.

Before running this sample, you must create an ODBC datasource named IDContact that points to the contact.mdb database file in the viddemo subdirectory. The id demo sample application uses the mapping schema file iddemo.schema located in the repository directory. This file was created and can be edited using the mapping tool.

Note: the ODBC datasource must be named IDContact because this is the URL that has been specified in the database configuration option of the iddemo.schema file. If you use another datasource name, make sure to edit the iddemo.schema file to specify the new URL.

The application contains two packages: viddemo.client and viddemo.engine. The starting class containing the main method is named viddemo.client.ContactApp.

10.9. String ID Demo Application

Another modified version of the original contact management application described in section 10.1 changed to demonstrate the following concepts:

• IDs of type String instead of long.
• ID Generation using an String ID generator object.

Before running this sample, you must create an ODBC datasource named StringContact that points to the contact.mdb database file in the vstringiddemo subdirectory. The string id demo sample application uses the mapping schema file stringiddemo.schema located in the repository directory. This file was created and can be edited using the mapping tool.

Note: the ODBC datasource must be named StringContact because this is the URL that has been specified in the database configuration option of the stringiddemo.schema file. If you use another datasource name, make sure to edit the stringiddemo.schema file to specify the new URL.

The application contains two packages: vstringiddemo.client and vstringiddemo.engine. The starting class containing the main method is named vstringiddemo.client.ContactApp.

10.10. Point of Sale Demo Application

This sample point of sale application demonstrates some of  the more advanced concepts. It tracks sales to customers, and maintains inventory items and customer information. It contains the following business classes:

• Invoice is a class that owns the InvoiceLine class (one-to-many aggregation), and references a Customer (to-one association).
• Customer is an abstract class that owns the Locator abstract owned class (one-to-many aggregation).
• Person and Organization are concrete classes that extend Customer. They are both stored in the same table using a filter column to distinguish between them.
• Phone and EMail are concrete owned classes that extend Locator. Each is stored in a different table, but they share a common ID table in order to generate unique IDs across both classes.
• InvoiceLine is an owned class that references a LineItem (to-one association).
• LineItem is an abstract class that represent an item (SKU) for available for sale.
• Item and Labor are concrete classes that extend LineItem.
• Assembly and Component are concrete classes that extend Item. An Assembly references a collection of its Components (one-to-many association). A Component also references its corresponding Assembly (to-one association). All four classes Item, Labor, Assembly, and Component are stored in the same table using a filter column to distinguish between them.

This sample demonstrates the following concepts:

• Use of OCollection declared as java.util.Collection and REFERENCE attributes declared as an application specific interface.
• Heterogeneous collections.
• Heterogeneous references.
• Abstract class and heterogeneous ownership.
• Multi-class queries involving heterogeneous collections, including class joins and ad-hoc queries.

Before running this sample, you must create an ODBC datasource named POS that points to the pos.mdb database file in the vposdemo subdirectory. The POS demo sample application uses the mapping schema file posdemo.schema located in the repository directory. This file was created and can be edited using the mapping tool.

Note: the ODBC datasource must be named POS because this is the URL that has been specified in the database configuration option of the posdemo.schema file. If you use another datasource name, make sure to edit the posdemo.schema file to specify the new URL.

The application contains two packages: vposdemo.client and vposdemo.engine. The vposdemo.engine package contains the above persistent classes. The vposdemo.client package represents a client application that uses the business objects in the vposdemo.engine package to display a list of invoices, customers, items, and to perform queries and various update operations. The starting class containing the main method is named vposdemo.client.POSApp.

10.11. Point of Sale 2 Demo Application

This is a modified version of the sample point of sale application that demonstrates the following concepts:

• Persistent classes that do not have relationship attributes, instead the Database class is used to retrieve referenced objects.
• Implementation of the OPersistable interface.
• Extending a superclass in order to implement behavior.
• Dynamically adding attributes to a persistent class at runtime using indexed method access.

Before running this sample, you must create an ODBC datasource named POS2 that points to the pos.mdb database file in the vposdemo2 subdirectory. The POS2 demo sample application uses the mapping schema file posdemo2.schema located in the repository directory. This file was created and can be edited using the mapping tool.

Note: the ODBC datasource must be named POS2 because this is the URL that has been specified in the database configuration option of the posdemo2.schema file. If you use another datasource name, make sure to edit the posdemo2.schema file to specify the new URL.

The application contains two packages: vposdemo2.client and vposdemo2.engine. The vposdemo2.engine package contains the above persistent classes. The vposdemo2.client package represents a client application that uses the business objects in the vposdemo2.engine package to display a list of invoices, customers, items, and to perform queries and various update operations. The starting class containing the main method is named vposdemo2.client.POSApp.

10.12. Shapes Demo Application

This sample application demonstrates heterogeneous collections based on an interface. It maintains drawings made up of geometrical shapes. It contains the following business classes:

• Drawing is a class that owns any object that implements the Shape interface (one-to-many aggregation).
• Square, Rectangle, and Circle are concrete owned classes that implement the Shape interface. Each is stored in a different table, but they share a common ID table in order to generate unique IDs across all three classes.

Before running this sample, you must create an ODBC datasource named Shape that points to the shapes.mdb database file in the vshapesdemo subdirectory. The shapes demo sample application uses the mapping schema file shapesdemo.schema located in the repository directory. This file was created and can be edited using the mapping tool.

Note: the ODBC datasource must be named Shape because this is the URL that has been specified in the database configuration option of the shapesdemo.schema file. If you use another datasource name, make sure to edit the shapesdemo.schema file to specify the new URL.

The application contains only package: vshapesdemo. The starting class that represents a client and contains the main method is named vshapesdemo.ShapeApp.

10.13. Person Demo Application

This sample application demonstrates how to model a class inheritance tree using vertical mapping and the use of concurrency columns. Each class in the inheritance tree is mapped to its own database table. It contains the following business classes:

• Person is an abstract class from which all other classes inherit.
• Employee is a concrete subclass of Person that represents an employee in an organization.
• Customer is also a concrete subclass of Person that represents an individual person that purchases goods.
• CorpCustomer is a concrete subclass of Customer that represents an entity that purchases goods.

Before running this sample, you must create an ODBC datasource named Person that points to the person.mdb database file in the vpersondemo subdirectory. The person demo sample application uses the mapping schema file person.schema located in the repository directory. This file was created and can be edited using the mapping tool.

Note: the ODBC datasource must be named Person because this is the URL that has been specified in the database configuration option of the person.schema file. If you use another datasource name, make sure to edit the person.schema file to specify the new URL.

The application contains only package: vpersondemo. The starting class that represents a client and contains the main method is named vpersondemo.PersonApp.

10.14. Person Demo2 Application

This is a modified version of the above person demo application with the following business classes added:

• Store represents a store with a list of clients of type Person, or any of its subclasses, and a list of employees of type Employee.
• SubContractorCustomer extends CorpCustomer and represents a corporate customer that has a valid contract for goods/services.

This applications contains some fairly complex mappings to demonstrate the following concepts:

• Superset classes with vertical mappings.
• Relationships maintained and traversed using methods of the Database class.
• Heterogeneous many-to-many relationships implemented via join tables.
• Queries that traverse join tables.

Before running this sample, you must create an ODBC datasource named Person2 that points to the person.mdb database file in the vpersondemo2 subdirectory. The person demo sample application uses the mapping schema file person2.schema located in the repository directory. This file was created and can be edited using the mapping tool.

The application contains only package: vpersondemo2. The starting class that represents a client and contains the main method is named vpersondemo2.PersonApp.

10.15. Dynamic Demo Application

This application utilizes the same business classes as the original contact management application described in section 10.1, but the client application has been modified to demonstrate the following dynamic features of VBSF:

• Working with persistent classes off-line (i.e. while not connected to a db).
• Switching class-to-table mappings at runtime.
• Switching databases dynamically.
• Loading objects from one database and saving them to another.
• Pre-fetching owned collections into the cache.

Before running this sample, you must create two ODBC datasources named Dynamic1 and Dynamic2 that point to the contactbase1.mdb and contactbase2.mdb database files in the vdynamicdemo subdirectory. The dynamic demo sample application uses the mapping schema file dynamicdemo.schema located in the repository directory. This file was created and can be edited using the mapping tool.

Note: the ODBC datasources must be named Dynamic1 and Dynamic2 because these are the URL that have been specified in the client class DynamicApp. If you use other datasource names, make sure to edit the vdynamicdemo.client.java file to specify the new URLs.

The application contains two packages: vdynamicdemo.client and vdynamicdemo.engine. The starting class containing the main method is named vdynamicdemo.client.DynamicApp.

11. TESTED CONFIGURATIONS

VBSF has been designed to integrate with virtually any type of existing legacy database under any platform that supports a Java VM. VBSF does not use any native methods, and issues only SQL 89 and entry level SQL 92 statements to the database. VBSF recognizes major database products and is able to configure itself to take advantage of specific extensions.

VBSF has been tested in-house under Win 95/98, NT 4.0 and Win 2000 using the following databases:

1. Microsoft Access 97/2000 using the following configurations:
   • Sun's JDK 1.2.0-1.2.2, 1.3.1 & 1.4.1 and the JDBC/ODBC bridge.
   • Symantec's Visual Cafe v2.x/3.0/4.0/4.5 and the JDBC/ODBC bridge.
2. Microsoft SQL Server 6.5/7.0/2000 using the following configurations:
   • Sun's JDK 1.2.0-1.2.2, 1.3.1 & 1.4.1 and the JDBC/ODBC bridge.
   • Sun's JDK 1.2.0-1.2.2, 1.3.1 & 1.4.1 and WebLogic's thin JDBC driver.
   • Symantec's Visual Cafe v2.x/3.0/4.0/4.5 and the JDBC/ODBC bridge.
3. Oracle 7.3.3/8.0 using Sun's JDK 1.2.0-1.2.2, 1.3.1 & 1.4.1 and Oracle's JDBC thin driver.

We have extensively tested VBSF with the JDBC/ODBC bridge against Microsoft Access 97/2000 and found no problems whatsoever. However, we do not recommend the use of the JDBC/ODBC bridge for server based databases, such as SQL Server or Oracle, except for development.

In addition the above database products, our customers have reported they have VBSF working with Oracle 8i, Sybase v11 (SQL Anywhere and Adaptive Server), DB2, Informix, Solid, Interbase, PostgresSQL, InstantDB, and mySQL, in addition to connections to other legacy back-ends such as VAX RMS via ODBC, under various operating systems including  Linux, Solaris and other flavors of Unix. If you have successfully tested VBSF under other configurations we would appreciate if you let us know.

12. SUPPORT INFORMATION

Objectmatter provides free technical support for general questions to licensees and evaluators via our support group and by e-mail.

For additional support information please refer to our support page at http://www.objectmatter.com/support.htm.

13. FEEDBACK AND ORDERING

We will constantly be improving this product. We encourage you to provide us with feedback, comments, suggestions, and bug reports to help us improve it.

For a feature overview refer to http://www.objectmatter.com/vbsfproductinfo.htm.

For a white paper and product overview refer to http://www.objectmatter.com/vbsfoview.htm

For pricing information or to order VBSF refer to http://www.objectmatter.com/vbsfpricing.htm.

You may contact us in any of the following ways:

INTERNET:

http://www.objectmatter.com

E-MAIL:

© 1997-2003 Objectmatter, Inc. All rights reserved

TRADEMARKS. Products and company names mentioned herein are the trademarks of their respective owners.

Return to Documents Available