Q: How do I set the CLASSPATH and create the .jar file?
Applies to: 1.x, 2.0
This question discusses how to set the CLASSPATH and create the .jar file after you have made changes to the XML-DBMS source code. Although it uses version 1.0 in its examples, it applies to version 2.0 as well.
If you just want to set the CLASSPATH, see any Java tutorial or search the Web for java set classpath, plus the name of your operating system.
Unpacking the source code
Suppose you have installed XML-DBMS in the following directory:
c:\java\xmldbms101
If you want to make changes, the first thing you need to do is unpack the source code. In version 1.01, this is in the src.zip file. (I can't remember what file version 1.02 uses. For versions 1.1 and 2.0, you need to get the code from the CVS tree [1].) To unpack the source code, you can use your favorite ZIP file extractor (such as WinZip) or use jar. This places the source code in the de subdirectory.
c:\> cd java\xmldbms101 c:\java\xmldbms101> jar xvf src.zip
You can now make changes to the source code.
Compiling changes
To compile your changes, use the javac command. For example, suppose you changed DBMSToDOM.java. To compile this, use the following command:
c:\> cd java\xmldbms101\de\tudarmstadt\ito\xmldbms> c:\java\...\xmldbms> javac DBMSToDOM.java
This creates the DBMSToDOM.class file in the same directory as the DBMSToDOM.java file.
If you want to compile all of the classes, you have three choices:
Compile the Transfer and GenerateMap samples (or your application). Java is intelligent about how it compiles classes. If the class you are compiling depends on other classes, it compiles those other classes as needed. Transfer and GenerateMap depend on all other classes in the system (with a few minor exceptions you don't need to worry about).
Write a set of scripts to compile the classes for you. This is what I use, and it's just a set of DOS command files.
Use Ant [2]. Gary Lawrence Murphy [3] and Ben Hall [4] have recently posted Ant scripts for XML-DBMS on the mailing list.
Setting the CLASSPATH
Java uses the CLASSPATH environment variable as a way to locate classes. This works as follows.
Each class is expected to be in a directory based on its package name. This directory must be a subdirectory of a directory in the CLASSPATH variable. For example, the DBMSToDOM class is in the de.tudarmstadt.ito.xmldbms package. Therefore, it needs to be in the following subdirectory:
de\tudarmstadt\ito\xmldbms
Assuming that DBMSToDOM.class is actually in the following directory:
c:\java\xmldbms101\de\tudarmstadt\ito\xmldbms
then I need to set my CLASSPATH as follows to find DBMSToDOM.class:
c:\> set CLASSPATH=c:\java\xmldbms101
When I actually run the code, what happens is that Java looks in each directory listed in the CLASSPATH and checks: (1) if there is a subdirectory corresponding to the package name and (2) if the .class file it is searching for is in this subdirectory. In the example above, this means that Java looks in the c:\java\xmldbms101 directory, checks if there is a de\tudarmstadt\ito\xmldbms subdirectory, and checks if DBMSToDOM.class is in this subdirectory.
You can also place .jar files in a class path. These are treated like directories. For example, if you want only want Java to search the XML-DBMS .jar file, you would set your CLASSPATH as follows. (Remember that we installed XML-DBMS in the \java\xmldbms101 directory.)
c:\> set CLASSPATH=c:\java\xmldbms101\xmldbms.jar
Now suppose that you want to use the new version of DBMSToDOM and the shipping versions of all other classes. You have two choices. You can either use the newly compiled .class file from the file system or you can rebuild the XML-DBMS .jar file.
The advantage of using the .class file from the file system is that you don't have to modify the shipped version of the .jar. This is a good thing to do if you want to quickly test changes. (You will probably want to rebuild the .jar when you actually deploy your system.)
To do this, you add the c:\java\xmldbms101 directory and the XML-DBMS .jar file to your CLASSPATH:
c:\> set CLASSPATH=c:\java\xmldbms101;c:\java\xmldbms101\xmldbms.jar
Notice that the two entries are separated by a semi-colon. This is used on Windows systems. I think a colon is used on Unix systems, but I'm not sure. Notice also the order in which the entries are listed. This is important, as Java will search these in order.
Now let's see what happens when Java looks for two different class files: DBMSToDOM.class and Map.class. When it looks for DBMSToDOM.class, it first searches the subdirectories of c:\java\xmldbms101 as explained above. Since it finds a DBMSToDOM.class file here, it uses this one and not the one in xmldbms.jar.
However, when it looks for Map.class, it doesn't find one in the file system (we haven't compiled it yet) so it looks in c:\java\xmldbms101\xmldbms.jar. It finds Map.class in the .jar file, so it uses it. Thus, by adding both the root of the source code directories and the .jar file to the CLASSPATH, we can use .class files from both.
In real life, you'll probably want to add other directories to your CLASSPATH as well, such as the current directory (.\), the directory for the XML parser you use, and the directory for your application. For example, here's the command I use to set my CLASSPATH:
set CLASSPATH=c:\java\xmldbms101\xmldbms.jar;
c:\java\jdk1.1.8\lib\classes.zip;
.\;
c:\java\xerces-1_3_1\xerces.jar
Note that this is broken across multiple lines for clarity. The set command must be all on one line.
Building the XML-DBMS .jar file
When you actually deploy your code, you'll probably want to rebuild the .jar file to include your changes. (Alternatively, you could build your changes into a different .jar and make sure that one appears first in the CLASSPATH.) To build a .jar file, use the jar tool shipped with the JDK. This has the following syntax:
jar [ options ] [manifest] destination input-file [input-files]
The options you want are c (create), v (verbal), and f (file). The destination is the full path of your .jar file and the input files are the class files you want to add to the .jar file. You don't need to worry about the manifest.
jar stores relative path names, so it is important that you run it from the root source code directory. This will ensure that the correct paths are stored in the .jar file so that Java can match these to package names.
To build the jar file, you need to first compile all of the .java files you want to include, then cd to the root source code directory, then run jar. For example:
... compile source code ...
c:\> cd c:\java\xmldbms101
c:\java\xmldbms101\> jar cvf c:\java\xmldbms101\MYxmldbms.jar
de\tudarmstadt\ito\domutils\*.class
de\tudarmstadt\ito\schemas\converters\*.class
de\tudarmstadt\ito\schemas\dtd\*.class
de\tudarmstadt\ito\utils\*.class
de\tudarmstadt\ito\xmldbms\*.class
de\tudarmstadt\ito\xmldbms\helpers\*.class
de\tudarmstadt\ito\xmldbms\mapfactories\*.class
Note that this is broken across multiple lines for clarity. The jar command must be all on one line.
The only thing you need to do now is change your CLASSPATH to use the new .jar file. Note that you will need to remove the root source code directory, since you now want to use files in the .jar, not in the file system:
set CLASSPATH=c:\java\xmldbms101\MYxmldbms.jar;
c:\java\jdk1.1.8\lib\classes.zip;
.\;
c\:java\xerces-1_3_1\xerces.jar
Note that this is broken across multiple lines for clarity. The set command must be all on one line.
And that's all there is to it.
[1] http://sourceforge.net/cvs/?group_id=13613
[2] http://jakarta.apache.org/ant/
[3] http://groups.yahoo.com/group/xml-dbms/message/1960
[4] http://groups.yahoo.com/group/xml-dbms/message/2043