Want this course?
Running Java with options
Course: JVM Fundamentals for Clojure
This lesson goes over some of the most common commands for running java on the command line.
So, Java is actually a program that you can run at the command line. That's what runs your Java programs. It's what starts the jvm, loads up a jar file, loads up class path, and executes. Notice that there's an option called jar. We typically don't use that. That's if you have an executable jar. Some jars are executable.
Usually what we're going to be doing is setting the class path. Okay, these two are equivalent. But I'm getting ahead of myself. So the first thing that you'll want to do is check your Java version. Don't do dash dash version in the sort of Unix style, because it's unrecognized, and don't do dash v, also unrecognized. You want dash version, like this. And this tells you the release of Java that you're currently running.
Notice that it's one dot eight. This is the eight from Java 8. This is the important part. It seems that they're so good at doing backwards compatibility that they're probably never going to bump this number. They're never going to have breaking changes. They're only going to bump this one. And so they call it Java 8, just to show progress. I think they started doing that with Java 5. Okay, Java 8 is the current version that's released. Java 7 is still widely used. Probably some people use Java 6. But you should be using 8 right now.
Now, I talked about the class path. When Java loads up and you start running some code, it's gotta search for what are called class files, which are the compiled bit code version of your Java source code. Each class has one class, so it corresponds roughly one Java file to one class file. Inner classes will get their own files, too, their own class files, and they're named with the dollar sign, like we see in the import statement lesson. If you're more interested in that right now, go watch that.
So we've got a class path, and so we kind of specify it like you would specify your executable path in Unix. You put directories with semicolons. And those directories have to point to the-- to a directory containing the package hierarchy. Usually you're not going to be dealing with that anymore. Usually you're going to have one or two jars that you put on your class path. So a jar file is a collection of class files in a zip. It's all zipped up into one big package, and the Java vm can read that. So, I've got, let me show you. I've got the clojure jar. This contains clojure, the language. So it's just a jar, it's just a dependency, and I'm gonna add it to my class path. Okay, so now everything that's in that zip file, called the jar, is going to be loadable, all the classes that are in there. Also, all the clojure code that's in there, too. So I have this jar, and I want to call a particular-- I want to instantiate a particular-- sorry, instantiate, I want to start it. I want to run something.
There's a thing called a main method on certain objects, and it's a static method, but it's an entry point into your program. And clojure has one, called clojure dot main, so I can run this, and you see it has a REPL. Okay, there's other options to clojure dot main, but if you don't have options it runs a REPL. So, this is the name of the class. And this is the class path. You can put semicolons and add different things. But I just want to show you that these are all just command line options that you can use.
All right, so we have this command, and we want to change the heap size, the minimum heap size. All right, so when the jvm starts up, it has-- it's going to grab a bunch of memory. That's called the heap. The heap is where it's going to allocate its objects from. And there's two parameters for configuring the heap. The main thing is, how big is it? So there's the minimum size, and the maximum size. So if you're getting an out of memory error, that says ran out of heap, then you need to increase the maximum size. The minimum size is how much it's going to grab when it first starts up. Let's go back to this, and we're gonna start adding an option, xms, now this is a minimum size. We can put one g, one gigabyte. Okay, and it started up just fine. I think the default is something really small, like 32 megabytes.
Okay, so this is the minimum size, and then if you get an error that says it's too small, I ran out of space, well you can set it here, you can set a bigger size. It's very common that you run out of space if you're doing something big, reading in a big file or something. Okay, so there's also this other space called the permanent generation. Java has a generational garbage collector, which means that old stuff, old objects that you've allocated, are going to be considered, like they're never going to die, meaning if they live a long time, there's just never going to go away, which is probably true, if something has been around for minutes, and it hasn't been collected, it's probably going to be around for the rest of the Java running.
There's also stuff that are known to be around forever, and so they just go in there already. Those are things like if you create what's called in-line strings, or like, classes, if you make a new class, that kind of thing, those things go in the permanent. And it can be collected, but it's basically almost never collected. And this-- it's only collected at the last, last, very last thing. So there's settings to set that, and sometimes... Oh, look, the option-- oh, support was removed in eight. Well, there you go. So that's out of date information. Let's see if you can do max perm size. Yeah, that was removed.
Okay, well, if you're still using one seven, you probably want to know that. There's perm size and max perm size. If you get an error that says out of memory, perm size, perm gen, the permanent generation, then this is the thing you need to change. A lot of people are still running one seven, so it's still valid. Okay, if you get a lot of stack overflows, you're probably doing something wrong, but maybe you know what you're doing, and there is an option for setting the stack size. Each thread has its own stack, and you can set it like, you know, like that. Stack size is too small, at least 160k, okay, I'll do that. How about we do 1000k?
There we go. Right, so if you think, hey, I just need a little bit more stack space, do this. Often that's not really the real problem, it's that you've got infinite recursion or something, so you're gonna wanna fix that bug. But it's good to know that that's there. Okay, the final thing is, there are two options, I'm gonna delete these, there's two options that are mutually exclusive. If you're running a server on a-- you know, like a web server or something that's supposed to be running for a long time, there's a bunch of options built in, that if you just use dash server, it's optimized for that, meaning the start-up time is not so important, what's really important is the long-running efficiency of the thing, so you do like that, and then if you're building a desktop client, and you wanna start it up real fast, you do client. Cool, so these are the jvm options.
Now I want to show you that you can actually put them into your project dot clj, your lining in file. So here I am in my project file, and I wanna do, I wanna set the max heap size, so I do jvm opts, you still need a dash, and now you put that xmx, I want 10 gigabytes, whatever, I want four gigabytes, not 14, four gigabytes. Right, and you can just put a bunch of them in here, so you do x server, and, oh, I wanna set the minimum heap size, xms to one gigabyte. I mean, for instance, the reason you would set this, just as an example, is if you know I'm gonna grow to four gigabytes anyway, I'm just gonna start with four gigabytes. And you know, that's a valid option, right there.
Okay, cool, I'm going to-- I'm gonna remove this, because it's probably not good to start with four, to get up to four gigabytes, not for the little stuff I'm doing right now, so there we go, run it as a server, minimum size, there. Cool.
Fields and Methods
Everything in Clojure is based on Java Objects. That means it all boils down to methods and fields on objects and classes. When you're interfacing with a Java library, including the standard library, you will need to access methods and fields all the time. This lesson covers the normal and most common ways of calling methods and accessing/changing the state of objects.