This document discusses issues related to the storage and retrieval of
application schema files.


The Application Schema
----------------------

An application schema holds the mapping information needed for VBSF to be
able to map your persistent classes to a relational database. Application
schemas are defined and saved using the mapping tool. They are later read
at runtime by the persistence engine so it knows how to store and retrieve
your persistent objects from the database.

The mappings for a single application may be defined using one or multiple
application schemas since VBSF has the ability to combine multiple schemas
at runtime. Using multiple schemas may be useful for applications that map
a large number of classes to the database, because it keeps the number of
classes in each schema down to a manageable size. There are no restrictions
on how a large application schema can be split up, as long as the mappings
for each class are defined in their entirety within the same schema. For
example, different classes in the same Java package maybe defined in multiple
schemas, and subclasses may inherit from superclasses defined in other schemas.

Application schemas are saved with a file extension of .schema (e.g.,
contactdemo.schema). If an application schema extension is changed, the
mapping tool will not be able to load it. 



The Default Schema Directory
----------------------------

Application schemas are saved by default in a repository directory named
'schrepository'. This directory is created by default under the VBSF installation
directory.

By default VBSF looks for the schrepository directory by looking at the CLASSPATH.
VBSF looks under all the directories listed in CLASSPATH looking for a subdirectory
named 'schrepository'. Once it finds it, then it looks for the specific schema file.
For example, if you installed VBSF in a directory named c:\vbsf, then by default
the 'schrepository' is located in c:\vbsf\schrepository, and you would have to add
the c:\vbsf directory to the CLASSPATH.

Because VBSF searches the environment's CLASSPATH in order to locate the default
repository directory, the repository 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. For example, if the repository directory is moved to c:\server\schrepository,
then you would have to add the c:\server parent directory to the CLASSPATH.



Specifying an Alternate Repository Directory
--------------------------------------------

You may also specify an alternate directory where application schema files are to be
saved by using the 'vbsf.repository' command line system property. This property can
be used both at runtime and 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 schema files reside. Note that if you specify an alternate
repository directory there is no need to add the name of the 'schrepository' parent
directory to your CLASSPATH.

If you cannot save or retrieve application schemas, and you are not using the
vbsf.repository property, is because the schrepository directory is not located under
a directory visible to the CLASSPATH.



Specifying the Schema File at Runtime
-------------------------------------

You can also provide the full path to the schema file to the Server
constructor at runtime. This is done by specifying the absolute location of the
schema file using a URI that uses the full path name prefixed by the string 'file:/'
For example:

Server svr = new Server
          ("file:/c:\\tomcat\\webapps\\myApp\\WEB-INF\\classes\\contactdemo.schema");


Schema files can also be placed inside a jar file for deployment, along with the
vbsf jars and your application executables. To take advantage of this feature,
prefix the relative path of the schema file with the word 'resource:'. For example,
if the contactdemo.schema file was placed inside a jar file under the 'schrepository'
directory, then you would create a Server object as follows:

  Server svr = new Server("resource:/schrepository/contactdemo.schema");



(c) 1998-2002 Objectmatter, Inc. All rights reserved.
TRADEMARKS. Products and company names mentioned herein are the trademarks of
their respective owners.