===== Help using Eclipse ===== According to www.eclipse.org, the Eclipse project is an "open development platform comprised of extensible frameworks, tools and runtimes for building, deploying and managing software across the lifecycle". ==== Startup ==== If Eclispe is running slowly you may want to increase the amount of memory allocated to it. You can do this by adding lines to the file ''%%eclipse.ini%%''. For example: -vmargs -Xms512m -Xmx2048m -XX:PermSize=256m -XX:MaxPermSize=512m The first line indicates that the subsequent lines should be sent to the virtual machine as arguments. The second sets the heap space to 128Mb initially. The third sets the maximum heap space to 521Mb. The last two set the starting and maximum amount of space to use for class names, objects that are never garbage collected, etc...) to 128Mb. ==== Workspaces ==== A workspace is a directory that Eclipse uses to store preferences/configurations and projects. As a student, you will probably want to create a workspace for each course (since, for example, the style guide for each course may be different, and this information will be captured in the workspace's preferences/configurations). Eclipse can only use one workspace at a time (though it is possible to have multiple instances of Eclipse running at the same time, each with its own workspace). Each time you start Eclipse, you will prompted for the workspace to use. You can change the current workspace (and create a new one if necessary) by clicking on File+Switch Workspace. You can then choose an existing workspace or click on Other... to create a new one. ==== Projects ==== Eclipse organizes resources (including design documents,code, tests, data, external documentation) into //projects//. === Perspectives === Eclipse offers several different ways to present and interact with projects, each of which is called a //perspective//. The most convenient way to interact with a project is using a perspective that is appropriate for the language(s) you are using and the task you are performing. For example, for most tasks in a Java project you'll want to use the Java Perspective. As another example, for most git tasks, you'll want to use the Git Perspective. To open a perspective, click on Window-Perspective-Open Perspective and then choose the perspective you want. Note, if the perspective you want isn't an option, you may need to click on Other... and do a little looking. === Creating === To create a project: - Click on File-New and select the appropriate kind of project (which may require you to first click on Other...). - After the dialog box appear, enter a "Project name:", and whatever other information is appropriate. - Click on Finish. Unless you are specifically told to do so, **do not** create a %%module-info.java%% file (i.e. **do not** create a module). Also, unless you are specifically told otherwise, select the option to create separate %%src%% and %%bin%% directories/folders (i.e. **do not** put everything in one directory/folder). If you are using Checkstyle, you must activate it for the newly created project. To do so: - Right-click on the project in the "Package Explorer" and pull down to "Checkstyle". - Pull across to "Activate Checkstyle". === Importing === Eclipse projects can be exported as ''%%.zip%%'' files. To import such a project, click on File+Import, expand "General", select "Existing Projects into Workspace", and click Next. Then, choose "Select archive file", browse to the appropriate archive file, select the relevant project(s) if necessary, and click Finish. === Converting a Generic Project to a Java Project === Eclipse has many different kinds of projects. Java projects have a "J" above the folder icon in the package explorer while generic projects do not. After backing everything up outside of Eclipse, you may be able to convert a generic project to a Java project by: - Right-clicking on the project icon in the package explorer. - Pulling down to "Properties". - Selecting "Project Natures". - Clicking on Add. - Select "Java". === Customizing the Formatter === The way Eclipse formats code can be customized in a variety of different ways. These customizations can either be generic or project-specific. To create/modify a project-specific formatter: - Right-click on the project in the "Package Explorer" and pull down to "Properties". - Expand the appropriate "[] Code Style" property (e.g., "Java Code Style"). - Click on "Formatter". - Select "Enable project specific settings". - Select the appropriate "Active profile". - Click on Edit.... At this point, a dialog will open up that will allow you to change a wide variety of formatting options. You can also import an existing formatter. To import a formatter for a specific project (which is probably what you should do if you are using one workspace for all of your courses): - Right-click on the project and pull down to Properties - Expand "[] Code Style" (e.g., "Java Code Style"). - Click on Formatter - Click on Import - Navigate to the appropriate ''.xml'' file and click Ok - Click on Apply To import a formatter for all projects in a workspace (which is probably what you should do if you are using a different workspace for each course), see the page on [[ student:eclipse:install#install_and_use_a_custom_formatter | installing Eclipse ]]. === Custom Key Bindings === To save yourself some time, you can bind common commands to "shortcut keys". To do so, click on Preferences (which will either be under Window or Eclipse depending on your OS) and then General+Keys. === Creating Packages === Some courses require that code within a project be organized in packages and some do not. To create a package: - Right-click on the appropriate project (in the package explorer). - Pull down to New. - Pull over to Package. - Enter the name of the package in the "Name" field. - Unless you are explicitly told to do so, **do not** check the "Create package-info.java" box. Subpackages can be created by including a dot/period in the name. So, for example, if you have a %%data%% package you can create a subpackage named %%data.io%% simply by including the dot/period in the name when you create it. However, note that Eclipse will not visually put the %%io%% package insides of the %%data%% package (though it will put the corresponding %%io%% directory/folder inside of the %%data%% directory/folder). This is to remind you that the statement %%import data.*%% does not import the subpackage %%data.io%%. === Creating Files === There are many ways to create files and add them to a project. The easiest is: - Right-click on the appropriate folder. - Pull down to New and over to the appropriate kind of file. In particular, to create a file that defines a class (i.e., describes the attributes and methods in the class): - Right-click on the appropriate project or package (in the package explorer). - Pull down to New. - Pull over to Class. - Enter the full name of the package (including any subpackages, delimited with a .) in the "Package" field (or leave it blank if the class is in the default package). - Enter the name of the class in the "Name" field. - Optionally, complete the other fields and make the appropriate selections. - Click on Finish. To create a file that defines an interface or %%enum%%, simply pull over to Interface or Enum after pulling down to New. === Adding Data Files (and Other Resources) to a Project === Adding data files (and other resources like images) to a project can be a little tricky because of the way Eclipse organizes and executes code (i.e., the ''%%.java%%'' files are kept in the project's ''%%src%%'' directory, the ''%%.class%%'' files are kept in and loaded from the project's ''%%bin%%'' directory, and the interpreter is run from the project directory (with the classpath set to include the ''%%bin%%'' directory). == For Beginners == For beginners, the easiest thing to do is paste (or drag) the files into the project (not the ''%%src%%'' directory/folder) using Eclipse. (Note: If you use another file system utility to put the files in the project directory they will be accessible to the program when you execute it but not visible within Eclipse). == The More Maintainable Approach == The more maintainable (and generally accepted) approach is to keep resources in their own directory/directories under a top-level directory named ''%%resources%%''. In order to ensure that Eclipse copies this files to ''%%bin%%'' directory, one has to be careful when creating the ''%%resources%%'' directory. There are two common ways to do so. Either click on New+Source Folder or click on Build Path+New Source Folder. This will create a directory with whatever name you give it at the same level as the ''%%src%%'' directory and instruct Eclipse to copy it to the appropriate **top-level directory** (not a directory named ''%%resources%%'') when needed. You can then copy the projects resources into this directory (or sub-directories). Note that **if you create an "ordinary" folder (i.e., not a source folder), it will not be copied to the appropriate locations at the appropriate times**. === Adding Existing Source Files to a Project === The easiest way to add existing source (e.g., ''%%.java%%'') files to a project is to "click-and-drag" them from a file explorer/finder window to the appropriate location in the Eclipse "Package Explorer". (Note: If this doesn't work, it may be because you are not using the "Java Perspective".) === Using Third-Party .class/.jar Files === You will sometimes be given the byte code (i.e., the ''%%.class%%'' files) for classes that were developed by a "third-party" (i.e., classes that are neither part of the Java library nor written by you). Such classes will either be delivered in a single ''%%.jar%%'' file or as a collection of ''%%.class%%'' files. If given both (or a choice), you should (almost always) use the ''%%.jar%%'' file. To instruct Eclipse to use them when compiling and executing you should: - Create a directory/folder for the ''%%.class%%'' files or ''%%.jar%%'' file external to the workbench/eclipse-workspace (e.g., ''%%downloads%%''). - Copy or download the ''%%.class%%'' files or ''%%.jar%%'' file to that directory/folder. - Open Eclipse. - Select a project. - Click on Project and pull down to Properties. - Click on Java Build Path. - Select the Libraries tab. - Select the "Classpath" entry from the list. - As appropriate, click on one of the following. * Add External Class Folder... * Add External JARs... - Navigate to the appropriate location (which will be the directory/folder containing the ''%%.class%%'' in the first case, and the ''%%.jar%%'' file itself in the second case) and click Open or OK or the equivalent. - Click on Apply and Close (and whatever else you might need to click on to complete the process). - You may need to close and re-open the project for the files to be found. Remember, if you only have the byte code, you will not be able to edit these "third party" classes, but you will be able to use them in your source code. == Troubleshooting == If in trying to run your project you get a ''%%java.lang.UnsupportedClassVersionError%%'', it's likely that you are using the wrong version of Java (usually one too old). Check the expected java version in your course's documents. If you're not sure where to look, it's highly likely that your instructor requires you have at least the same [[student:computer_labs:start|version as the computer labs]]. === Incorporating Other Projects into a Project === It is sometimes useful to give code in one project access to the code in another project. For example, when creating a library that will be used in multiple products, you want the project containing the product to have access to the project containing the library. As another example, it is common practice to put tests in one project and deployable code in another project (to facilitate deployment), in which case you want the project containing the tests to have access to the project containing the deployable code. To do so: - Right-click on the project that depends on another project (e.g., the project containing the product). - Pull down to "Build Path". - Pull down to "Configure Build Path". - Select the "Projects" tab. - Select "Classpath". - Click on Add. - Click on the project that this project needs to access (e.g., the project containing the library). - Click on Ok. - Click on Apply and Close. ==== Editing ==== The editor in Eclipse is very sophisticated and supports (almost) everything that anyone could ask for. What follows are answers to some of the most common questions that arise. === Shortcut Keys === Type Ctrl+Shift+L to see a list of all of the shortcut keys. === Fixing Indentation Problems === To fix the indentation of a file: - Select the appropriate section of the code. - Type Ctrl+I or click on Source-Correct Indentation. === Completions === Type Ctrl+Space to see a list of suggested completions. (Typing one or more characters before doing so will shorten the list.) When the cursor is in a method, type Ctrl+Shift+Space to see a list of parmeter "hints". === Matching Braces/Curly Brackets === To find a matching curly bracket (either opening or closing) type Ctrl+Shift+P. ==== Counting Lines of Code (LOC) ==== Though there are several software metrics plug-ins available, there is an easy "hack" for counting lines of code. - Click on Search+File - Enter ''\n'' (to count all lines) or ''\n[\s]*'' (to count non-blank lines) in the "Containing text:" field - Check the "Regular expressions" checkbox - Enter ''*.java'' (or other file type) in the "File name patterns" field - Select the appropriate scope - Click on Search The top line of the "Search" panel will show the total number of matches (i.e., lines). You can also get matches/counts by package, file, etc. ==== Comparing Files ==== Files can be compared in a variety of different ways. === Comparing Files in Workspaces === To compare two files that are in a workspace, select both files (e.g., click on one and then ctrl-click on the other) then: - Right-click on one of the selected files. - Pull down to "Compare With". - Pull across to "Each Other". The two files will appear side-by-side in a window with a single scroll bar that you can use to move up and down through the two at the same time. === Comparing External Files === To compare any two files (either in a workspace or external to one), enter "Compare with Other Resource" in the "Quick Access" field (if necessary, first press Ctrl+3 to open the Quick Access field). Then enter the names of the two files and click on OK. === Comparing Different Versions of the Same File === When you edit a file Eclipse actually keeps both the old version and the new version. To compare different versions of the same file (e.g., the current version with an earlier version): - Right-click on the file. - Pull down to "Compare With". - Pull across to "Local History...". - In the "History" window, select the other version you are interested in. === Comparing with a Version in a Repository === If you are managing your code (e.g., with Subversion or Git), you can compare the "local" version of the code with a version in the repository. To do so: - Right-click on the file. - Pull down to "Compare With". - Pull across to to the appropriate revision (e.g., the ''HEAD Revision'' or the ''Previous Revision'') ==== Running ==== In Eclipse, applications are started using the Run button or the "Run" menu. They are configured from the 'Run" menu using the "Run Configurations..." option. === Run Configurations === There are different kinds of run configurations, the two most important are configurations for Java Applications and configurations for JUnit tests. To create a run configuration, select the appropriate type and click on the [New launch configuration] button (that looks like a blank sheet with a + in the upper-right corner). Then, fill in the name and other relevant information. For Java Applications, the most important information is entered on the "Main" tab. For JUnit tests, the most important information is entered on the "Test" tab. === Command-Line Arguments === It is sometimes necessary to pass parameters to an application at start-up. Such parameters are typically called command-line arguments because applications used to be started only from the command line. You can instruct Eclispe to pass the a ''%%main()%%'' method arguments as follows. - Expand the Run button (or click on the "Run" menu) and pull down to Run Configurations.... - On the "Main" tab, select the project and the main class (i.e., the class that contains the ''%%main()%%'' method). - On the "Arguments" tab, enter the arguments to pass in the "Program arguments:" field (delimited by spaces). Of course, since the only parameter of ''%%main()%%'' is a ''%%String[]%%'', all such arguments are treated as ''%%String%%'' objects. ==== Testing Using JUnit ==== The JUnit view (i.e., tab) can be configrued in a variety of ways. If you click on the "expand" arrow, you can select Activate on Error/Failure Only in which case the JUNIT view will only be come visible when there are failed tests. There are also toggles for Show Failures Only and Show Skipped Tests Only. ==== Instrumenting Code (Using the Debugger) ==== Code can be executed in debug mode using the {{eclipse_debug.png}} button. === Setting/Clearing Breakpoints === Simple breakpoints can be set/unset by right-cliking on the line number and pulling down to Toggle Breakpoint. Exception breakpoints (i.e., breakpoints that suspend execution when an exception is thrown) can be set using the {{eclipse_exception-breakpoint.png}} button that is available from the Breakpoint View. Execution can be suspended based on whether one or more exceptions is caught, uncaught, or both. Conditions can be added to breakpoints (i.e., so that the breakpoint suspends execution only when a Boolean is ''%%true%%'' or changes value) from the Breakpoints View. To so so, select the breakpoints, select "Conditional", choose the type of condition, and enter/choose the condition itself. (Note: The condition editor is below the dropdown and you may need to increase the size of the Breakpoints View to see it.) === Seeing and Skipping Breakpoints === You can see all of the breakpoints that are currently set using the Breakpoints view (Window+Show View+Breakpoints). (Note: If Breakpoints is not an option, you may need to click on Other... and expand Debug.) You can toggle between skipping and not skipping all breakpoints using the {{eclipse_skip-all-breakpoints.png}} button. (When Eclipse is skipping breakpoints, the breakpoints that are set will have a slash through them.) === Writing to System.out === It's quite common to instrument code outside of the debugger using calls to ''%%System.out.println()%%''. You can accomplish the same thing using conditional breakpoints, without adding "noise" to the actual code. To do so, add a conditional breakpoint that suspends when ''%%true%%'', includes the instrumentation code and evaluates to ''%%false%%''. For example, ''%%System.out.print("Age: "+age); return false;%%'' === Managing the Variables View === You can control what is shown in the Variables View by clicking on ⋮+Java and then selecting the items you are interested in. One particularly useful item is "Show References". === Debugging with Third-Party Classes === Sometimes you will only have %%.class%% files (or a %%.jar%% file) for some of the classes that you are using. When this happens, you won't be able to step into those classes (because you don't have the source code). However, you can still use the debugger. For example, you can step over any calls to methods that you don't have the source code for. Frequently in these kinds of situations, what you want to do is run to a breakpoint and the resume execution until that breakpoint (or another one) is encountered. This can be accomplished using the {{eclipse_resume.png}} button in the Debug Perspective. In other words: - Set a breakpoint (or multiple breakpoints). - Step through your code as far as you can (i.e., until you encounter method calls that you don't have the source code for) or as far as is necessary. - Click on the resume button. This will resume the execution of the code until a breakpoint is encountered. ==== Deploying ==== === Cross-Compiling === You can compile Java programs to be compatible with earlier versions of Java (and earlier %%.class%% file formats), even if you are using a later version of the JDK. To do so: - Right-click on the project and pull down to Properties. - Select (don't expand) Java Compiler. - Select Enable project specific settings. - De-select Use compliance from execution environment. - De-select Use --release option. - De-select Use default compliance settings. - Set the various compatibilities/compliances. === Creating .jar Files === To create a ''%%.jar%%'' file containing only ''%%.class%%'' files and resources: - Click on File-Export and expand "Java". - Select the "JAR File" wizard and click on Next. - In the "Select the resources to export" tree, select the appropriate packages and resource directories. - Deselect the Eclipse-related files (e.g., ''%%.classpath%%'', ''%%.project%%''). - Choose **only** "Export generated class files and resources" and "Compress the contents of the JAR file". - Enter the name of the "JAR file:". - Click on Finish. === Creating an Executable/Runnable .jar File === Though it is possible to create an executable/runnable ''%%.jar%%'' using the wizard for a "Runnable JAR File", that wizard is fairly inflexible. Hence, it is better to do the following. - Click on File-Export and expand "Java". - Select the "JAR File" wizard and click on Next. - In the "Select the resources to export" tree, select the appropriate packages and the appropriate resource directories/folders. **Note that the ''%%.jar%%'' file will include a directory/folder containing the resources. You will need to take this into account when loading resources withing the program (i.e., you will need to include the directory in the path). See the section on [[ student:java:resources | using resources ]]** - Deselect the Eclipse-related files (e.g., ''%%.classpath%%'', ''%%.project%%''). - Select **only** "Export generated class files and resources" and "Compress the contents of the JAR file". - Enter the name of the "JAR file:". - Click on Next. - Select **only** "Export class files with compile warnings". - Click on Next. - If the default manifest file is appropriate select "Generate the manifest file" otherwise select "Use existing manifest" and enter the path. (For more information, see the [[ http://java.sun.com/docs/books/tutorial/deployment/jar/appman.html | tutorial ]].) - If necessary, select "Seal some packages" but do not choose any packages to seal. (If grayed-out, you can skip this step.) - If you didn't specify an existing manifest, enter the name of the "Main class". - Click on Finish. Remember that if your application uses resources you must load them "properly" or they will not be found (i.e., not from the file system but from the ''%%.jar%%'' file). === Creating HTML Documentation === To create HTML documentation: - Click on File-Export and expand "Java". - Select "Javadoc" and click on Next. - If the "Javadoc command:" field is empty, click on Configure and navigate to the ''%%bin%%'' directory for the Java Development Kit (JDK). Find and select the "javadoc" file, then click on open. - Enter the "Destination:". - Click on Finish. === Adding Annotation Processing === It is relatively easy to add a custom annotation processor to an Eclipse project. - Add a directory to the project named ''META_INF'' that contains a directory named ''services'' that, in turn, contains a text file named ''java.annotation.processing.Processor'' that contains a single line with the name of the class that implements the ''Processor'' interface. - Create a ''.jar'' file that contains the annotation(s), the class that implements the ''Processor'' interface (usually by extending ''AbstractProcessor''), and any supporting classes. - Right-click on the project and select Properties. - Navigate to Java Compiler-Annotation Processing and check "Enable annotation processing". - Navigate to Java Compiler-Annotation Processing-Factory Path, check "Enable project specific settings", and add your ''.jar'' file to the list. - Clean and build the project. If you use the ''Messager'' that is passed to the ''init()'' method of your ''Processor'', Eclipse will display your output within the editor. If you send output to the console, it will display it there. (Note: You may need to click on Window-Show View-Error Log to see the output.) === Using the @SuppressWarnings Annotation === To enable ''@SuppressWarning'' annotations for a particular project, right-click on the project name and pull down to Properties. Then, expand Java Compiler, expand Annotation Processing, click on Errors/Warnings, and check "Enable project specific settings". Then check "Enable '@SuppressWarnings' annotations. To also ignore unhandled tokens in custom ''@SuppressWarnings'' annotations (as, for example, are included with JUnit and Checkstyle), change the value of "Unhandled token in '@SuppressWarnings'" to Ignore. ==== Getting Installation Details ==== Eclipse has a lot of plug-ins and it can be difficult to keep track of the versions of all of them. You can get this information by clicking on Help+About Eclipse IDE+Installation Details.