Setting up the examples’ environment

These instructions describe how to set up an Eclipse environment. Everything that the course covers is doable directly from the command line, and also using other IDEs. The steps should work on all common operating systems.

1. Get the software.
   1. If you don’t have a JDK already, download the newest JDK here.
      • Be sure to have a JDK, not only a JRE.
      • Older versions (e.g. 1.8.0_11) are known to have incompatibilities with our tools. Generally, the newest one is the safest bet, which is 1.8.0_112 at the time of writing.
   2. Download the Eclipse IDE for Java EE Developers.
      • I suggest that you use the Eclipse Installer. After launching it, you must choose the EE Developers edition.
      • Alternatively, you can download the zip and unpack it.
   3. After launching Eclipse, select a workspace directory.
      • It is a good idea to name the directory after the course, e.g. workspaceSEA.
      • You can later go to Files⇉Switch Workspace to quickly switch between workspaces, e.g. those used for other courses.
2. Install Eclipse add-ons.
   1. Open Help⇉Eclipse Marketplace.
      1. Search for GlassFish Tools, and install it.
         • No need to restart yet.
      2. Go to the Marketplace again, and install AnyEdit Tools as well.
      3. You have to restart Eclipse at this point.
3. Download libraries.
   1. EclipseLink Installer.
   2. Payara (full version).
      • This is a variant of GlassFish with a few fixes.
   3. Extract both zips. You’ll get two directories: eclipselink and payara41.
   4. Lombok.
      • Download the jar file and run it, then follow the on-screen directions.
      • Also, keep the lombok.jar file, we’ll need it.
4. Setup libraries in your Eclipse workspace.
   1. Back in Eclipse, go to Window⇉Preferences⇉Java⇉Build Path⇉Classpath Variables. Click New... to add the following variables.
      • JAVA_HOME: the path to your JDK folder. By default, it will be installed in (supposing you have version 1.8.0_112):
        • Windows: C:/Program Files/Java/jdk1.8.0_112
        • Linux: /usr/lib/jvm/java-8-oracle/ or java-8-openjdk-amd64
          • Executing echo $JAVA_HOME on the command line might show this path.
        • Mac: /Library/Java/JavaVirtualMachines/jdk1.8.0_112.jdk/Contents/Home/
      • ECLIPSELINK: your eclipselink folder.
      • GLASSFISH: your payara41 folder.
      • PERS: the file jlib/jpa/javax.persistence_2.1.1.v201509150925.jar under your eclipselink folder.
        • There’s also a persistence_source file, make sure you don’t select that one.
        • Note: the file’s version number may be different.
      • LOMBOK: your lombok.jar file.
5. Set up a Derby connection.
   1. Go to Window⇉Show view⇉Data Source Explorer. A tab labelled Data Source Explorer opens.
   2. In the tab, right click on Database Connections, and select New...
   3. Choose Derby, then click Next.
   4. Click the globe with star/green plus icon (tooltip: “New Driver Definition”)
   5. Choose Derby Client JDBC Driver, 10.2.
      1. You’ll see a red error indicator. Don’t worry, we’ll fix it.
      2. Choose the JAR List tab.
      3. Click on derbyclient.jar, then on Edit JAR/Zip...
         • Select db\lib\derbyclient.jar under your JDK folder.
   6. Click OK to exit "Edit Driver Definition"
      • Now the Drivers dropdown contains a "Derby Client JDBC Driver"
   7. To test the connection, do the steps titled Starting Derby from the command line.
      • Once you’ve started Derby from the command line, in Eclipse, click Test Connection.
      • It should say, Ping succeeded!
   8. Click Finish.
   9. You don’t really need the Database Connections tab anymore, but you can keep it around to check the actual contents of the database when you run the examples.
6. Set up a new GlassFish server.
   1. In File⇉New⇉Other...⇉Server, choose GlassFish v4.
   2. As GlassFish location, choose the glassfish folder under payara41.
   3. Do not enter an admin password. The default GlassFish configuration has an empty password.
   4. If Eclipse asks, the admin port is 4848.
7. Get the examples.
   1. Download and unzip the examples’ zip file into the workspace directory.
   2. In Eclipse, File⇉Import, select Existing Projects into Workspace.
      1. Browse your workspace directory.
      2. Click Finish.
   3. If you have installed AnyEdit Tools, you can organize the example projects much better.
      1. Go to File⇉Import⇉Working Sets.
      2. In the downloaded examples, you’ll find an enterprise-application-examples.wst file. Select it, then click Finish.
      3. I suggest you use the Package Explorer view.
         • For extra comfort, click the downwards pointing little white triangle at the right top inside the sidebar of Package Explorer. There, select Filters, and tick Libraries from external.
8. Configure GlassFish.
   1. Start GlassFish.
   2. Once it’s running, in the GlassFish administrator console, add the following.
      • For the servlet-jpa example, in Resources⇉JDBC⇉JDBC Resources, add two resource pools: jdbc/books__pm and jdbc/books__nontx.
        • Note the double underscores in both names.
        • Here, pm stands for “persistence managed”, and nontx for “non-transactional”.
      • For the JMS-Queue example, in Resources⇉JMS Resources⇉Destination Resources, add a new message queue named jms/ExampleQueue with the physical destination name ExampleQueue.
9. Setup is done.
   • Before you run the examples, consider Starting Derby from the command line.
   • If any subsystem gives you trouble, e.g. problems (not just warnings) in the Problems view, have a look at the Troubleshooting section.
10. If Eclipse is slow, you can…
    • Make your antivirus, indexing service etc. ignore the following directories: Eclipse, GlassFish, JDK, and your workspace.
    • Make sure that no unnecessary programs are running.
    • If you have memory you can spare, you can make a ramdisk that contains any (or all) of the directories above.
      • Note that if you turn your computer off, or if it crashes, all content on the ramdisk will be gone! For that reason, placing your workspace there is very risky, and I suggest you don’t do that.

Starting Derby from the command line

For some examples (and to test the connection during setup), you need a running Derby instance to connect to. Here is how you can start it.

1. Open the command prompt.
2. Go to a directory that you can write into.
   • If the directory is not writable (e.g. you entered the db/bin directory to start Derby on Windows), then Derby will seemingly start up, but you’ll get errors anyway.
   • It is advisable to make a new directory for this purpose, because Derby will create a lot of files in the directory.
3. Execute the command JDKDIR\db\bin\startNetworkServer.bat (replace JDKDIR with your JDK folder).
   • After some seconds, you should see a message Apache Derby Network Server started and ready to accept connections on port 1527
   • If you don’t see this message, try invoking set "DERBY_OPTS=-Duser.language=en -Dderby.drda.debug=true" before you call startNetworkServer.

Troubleshooting

1. Read the error message if there is one.
   • This suggestion might seem trivial, but it’s so easy to avoid reading the error messages.
   • The error message may be somewhat hidden, and you have to click the Details button.
2. Maybe you forgot to take one of the steps listed above, or did something differently?
   • Check whether you have the proper Eclipse distribution. You need the EE Developers version.
   • If you see compilation errors, probably you haven’t got all the classpath variables.
   • If you see an error message about port number 1527, it is most probably about Derby not running.
     • Those examples that have JDBC or JPA in their names will try to connect to a running Derby instance. Before you run them, you have to do the steps titled Starting Derby from the command line.
3. Check in Window⇉Preferences⇉Java⇉Installed JREs whether you have a JDK selected. If you’ve got a JRE instead, add your JDK, and make it default.
4. If you have problems with the database, it’s possible that you’ve started Derby in the wrong directory.
5. If a file or directory is missing, and you know that it’s present, you can Refresh the project from its context menu.
6. It can happen that there is an application that is deployed into GlassFish, but Eclipse doesn’t show it. In that case, deploying the application will fail (possibly with a bogus NullPointerException). You can use the GlassFish Admin Console to remove the stuck application.
7. Things to try if all else fails, in the approximate order of induced discomfort.
   • Look inside $GLASSFISH\glassfish\domains\domain1\logs\server.log
   • Remove the application from the GlassFish server, then deploy it again.
     • You are practically forced to do this whenever the previous deployment was unsuccessful. For example, if you get the message “Invalid ejb jar … it contains zero ejb” even though you do have at least one in your EJB descriptor.
   • Use Project⇉Clean... in Eclipse or Clean in GlassFish’s context menu.
   • Stop the GlassFish server and restart it.
   • Remove the line where the error is displayed, save, then reinsert the line, and save again.
     • If the error doesn’t go away, closing the project and reopening it might help.
   • Quit Eclipse and start it again.
   • If you make a mistake, or would like to change something, quite often you can fix it, but sometimes it’s very hard: settings are not always too logically placed, and the error messages are often cryptic. If the problem doesn’t seem easiliy fixable, you can always restart with a new workspace, and go through the setup stages again.