I am hoping if someone can explain what a classpath is, looking for an explanation that can stick in my head so when I hear or read the word classpath I don't get confused.
I was just reading this line: "The first thing the format() method does is load a Velocity template from the classpath named output.vm"
And I couldn't figure out what was meant by classpath in this context.
The classpath in this context is exactly what it is in the general context: anywhere the VM knows it can find classes to be loaded, and resources as well (such as output.vm in your case).
I'd understand Velocity expects to find a file named output.vm anywhere in "no package". This can be a JAR, regular folder, ... The root of any of the locations in the application's classpath.
The classpath is the path where the Java Virtual Machine look for user-defined classes, packages and resources in Java programs.
In this context, the format() method load a template file from this path.
Think of it as Java's answer to the PATH environment variable - OSes search for EXEs on the PATH, Java searches for classes and packages on the classpath.
Like the springsteen-esque question, too.
When programing in Java, you make other classes available to the class you are writing by putting something like this at the top of your source file:
import org.javaguy.coolframework.MyClass
or sometimes you 'bulk import' stuff by saying:
import org.javaguy.coolframework.*
so later in your program when you say:
mine = MyClass.new();
the java virtual machine can know to load your compiled class.
It would be impractical to have the VM look through every folder on your machine, so you have to provide the VM a list of places to look. This is done by putting folder and jar files on your classpath.
Before we talk about how the classpath is set, lets talk about .class files, packages, and .jar files.
First, let suppose that MyClass is something you built as part of your project, and it is in a directory in your project called 'output'. The .class file would be at 'output/org/javaguy/coolframework/MyClass.class' (along with every other file in that package). in order to get to that file, your path would simply need to contain the folder 'output'... not the whole package structure, since your import statement provides all that information to the VM.
Now lets suppose that you bundle CoolFramework up into a .jar file, and put that CoolFramework.jar into a lib directory in your project. you would now need to put 'lib/CoolFramework.jar' into your classpath... the VM will look inside th jar file for the 'org/javaguy/coolpackage' part, and find your class.
So, classpaths contain:
How do you set your classpath?
The first way everyone seems to learn is with environment variables. On a unix machine, you can say something like:
export CLASSPATH=/home/myaccount/myproject/lib/CoolFramework.jar:/home/myaccount/myproject/output/
on a windows machine you have to go to your environment settings and either add or modify the value that s already there.
The second way is to use the -cp parameter when starting Java, like this:
java -cp "/home/myaccount/myproject/lib/CoolFramework.jar:/home/myaccount/myproject/output/" MyMainClass
A variant on this third way is often done with a .sh or .bat file that calculates the classpath and passes it to java via the -cp parameter.
So whats the best way to do it?
Setting stuff globally via environment variables is bad... generally for the same kinds of reasons that global variables are bad. You change the CLASSPATH environment variable so one program works, and you end up breaking another program.
The -cp is the way to go... I generally make sure my CLASSPATH environment variable is an empty string where I develop, whenever possible, so that I avoid global classpath issues (some tools aren't happy when the global classpath is empty though - I know of two common, mega-thousand dollar licensed J2EE and Java servers that have this kind of issue with their command-line tools).