This lesson discusses how to set up your Java development environment prior to starting coding for the Cartesian Plane Project.
Previous lesson: Java Graphics Tools
Lesson 1: Starting the Cartesian Plane Project
1. Installing the Development Tools
As with any Java project, this project will require some Java development tools: the Java compiler, the java command, libraries, etc. For this you will need the Java Development Kit (JDK), also know as the Java Software Environment (JSE). You can download the official JDK directly from Oracle; presently the best place to look for it is the Java Archive. To install the official JDK you will need an Oracle account, and agree to the Oracle license agreement. If you are using Java strictly for your own purposes this is not an issue; otherwise, if it is an issue, you may choose to download the OpenJDK; see the OpenJDK Installation Instructions. You may not wish to use the latest release of the JDK, which could still be undergoing some tuning. I am currently using JDK 14. Choose the download you wish and follow the installation instructions.
You will probably also want to install an Interactive Development Environment (IDE). Most of my students use Eclipse, so that's what I use. You may have your own favorite, such as BlueJ or IntelliJ which is fine. I may occasionally refer to techniques and shortcuts that are available using an IDE; I will always use Eclipse as an example, but all the common IDEs offer similar support. You can get Eclipse from the Eclipse Downloads page. Eclipse is a very flexible product, and during installation it may offer you several different installation options; be sure to choose the one for Java SE developers.
You don't need an IDE to do Java development. Everything can be managed from the command line (but IDEs simplify this task greatly!). If you choose to go the command line route you will need to know more about your operating system and Command Line Interpreter (CLI). You will also want to find a good source code editor; if you don't already have a favorite, Notepad++ (for Windows) and jEdit (for Unix/Mac) are good choices.
2. Project Structure
Within your file system, your project structure begins with a project root. You can call this anything you like; for this lesson and the next mine is Cartesian Plane Part 1. Within the root directory (a.k.a. folder) I follow the Maven standard. I have separate directories for source and binaries (called src and target). Within the target directory, I have separate directories for production binaries (classes) and test binaries (test-classes). Under the source directory, I have directories for production source code (main) and test source code (test). The main and test directories (for now) each have a java directory (later we may add a resources directory). After that, subdirectories follow the Java package naming convention (see below).
This is the project structure set up by the Maven configuration tool (more about Maven later; if you're curious now, see Maven in 5 Minutes on the Apache website). Chances are, if you create a new project with your IDE, it won't quite resemble this one; it is probably worth your time to go through the project and change it to match the above. Key features of the structure are:
- Source files and binary (executable) files are kept on separate branches of the tree.
- Within the source tree, production (main) sources and test sources are kept on separate subbranches (this is more important than you might think! More about testing later).
- Each source branch is divided into a java subbranch, where the .java files are stored, and... well, other related types of files (notably resource files, which we'll talk about later. Note that resource subbranches can be kept on the main and test branches).
- Likewise, on the binary (target) branch, binary files are divided into production (classes) and test (test-classes) subbranches.
- Below the java and classes directories, the project structure is dictated by the package name(s). Note that for each package on the production branches, there is typically a parallel package on the test branches.
About package names: in your Java projects to date, you may well have ignored package names, placing classes in the default package. If so, this is a habit you should try to break. Let's talk about packages for bit.
Package names: a package name is a hierarchy of Java identifiers separated by periods. By convention package names are always written in lower-case, giving, for example, org.w3c.dom and org.w3c.dom.events.
Fully-qualified class names: a quick note about class names: a full qualified class name (FQN) is the class name preceded by the name of the package it lives in. So the FQN for the String class is java.lang.String; the FQN for the LocalDate class is java.time.LocalDate.
What are packages for?
Packages serve two purposes. First, they create a namespace which guarantees that classes belonging to an organization or individual will be distinct from every other organization and individual. Organizations usually use a URL that they own, written backwards from the way you normally see it. Apache owns the URL apache.org, and every Apache package name begins with org.apache, for example org.apache.commons.cli. The World Wide Web Consortium (W3C) owns the URL w3c.org, and every W3C package name begins with org.w3c, for example org.w3c.dom. The built-in Java package names are the exception. Package names that begin with java or javax are reserved for use by the Java development team (examples: java.util, javax.swing). So long as everybody plays by the rules, and don't use names that belong to someone else, no one's names are going to conflict with Apache's, W3C's or the Java development team's.
The second purpose served by packages is to divide a project into logical pieces that can be developed and maintained separately. My Cellular Automata project is divided into ...cell_automata.components, ...cell_automata.extensions and ...cell_automata.geometry packages.
What should I use for a package name?
If you don't happen to own a URL like apache.org, and you're just working on a project for class or fun, it almost doesn't matter. For a given project, start with an identifier that represents the project and divide it logically from there. For example:
- dnd.gui
- dnd.gui.components
- dnd.main
- space_invaders.gui
- space_invaders.math
- space_invaders.math.geometry
- space_invaders.math.util
Once you know your package names you can complete your project directory structure. Each component in the package name must be allocated its own subdirectory. Source and class files for classes within a particular package must live in the designated subdirectory. So to begin the Cartesian Plane project we will have branches in our directory structure that look like this:
.png)
Some final words about the above project structure. In any project I almost always have a package named sandbox or ad_hoc. This is where I can experiment with algorithms or formulas or techniques before incorporating them into the main project. It doesn't have to be distributed with the final product, or even checked into source control if you don't wish. Classes in the sandbox package are always subject to revision or deletion without notice.
The project root may well contain other convenient files or subdirectories, such as a properties file. In the Cartesian Plane project I have a figures directory, where I store files containing figures that are uploaded to this blog. Eventually our root directory will contain a doc directory, which will contain the documentation for our packages and classes. If you're using Maven, this is where your POM configuration file lives. If you're using an IDE there will probably be files and/or subdirectories used directly by the IDE (these are not usually checked into source control).
No comments:
Post a Comment