Setting up the examples’ environment

These instructions describe how to setup an Eclipse environment for the Scalable Enterprise Applications course.

  1. Get the necessary files.
    1. A recent Java Development Kit.
      • 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_144 at the time of writing.
    2. 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. EclipseLink Installer.
      • Extract the downloaded zip.
    4. Payara (full version).
      • This is a variant of GlassFish with a few fixes.
      • Extract the downloaded zip.
    5. Lombok.
    6. The examples’ zip file.
  2. Setup Eclipse.
    1. Run Eclipse. Select a workspace directory.
      • It is a good idea to name the directory after the course, e.g. workspaceSEA.
      • Later on, you can use 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. 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. Run the Lombok jar file. Follow the on-screen directions.
      4. Restart Eclipse now.
    3. Setup library access paths.
      1. Go to Window⇉Preferences⇉Java⇉Build Path⇉Classpath Variables.
      2. 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_144):
          • Windows: C:/Program Files/Java/jdk1.8.0_144
          • 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_144.jdk/Contents/Home/
        • ECLIPSELINK: your eclipselink folder.
        • GLASSFISH: your payara41 folder.
        • PERS: the file jlib/jpa/javax.persistence_2.2.0.v201708071007.jar under your eclipselink folder.
          • There’s also a javax.persistence file that has source in its name, make sure you don’t select that one.
          • Note: the file’s version number may be different.
        • LOMBOK: your lombok.jar file.
    4. Prepare the examples.
      1. Unzip the examples’ zip file into the workspace directory.
        • If you don’t see a lot of subdirectories will in the workspace dir, maybe you’ve created an extra directory.
      2. File⇉Import, select Existing Projects into Workspace.
        1. Browse your workspace directory.
        2. Click Finish.
      3. File⇉Import⇉Working Sets.
        1. Select enterprise-application-examples.wst in your workspace dir, then click Finish.
        2. A Package Explorer view appears. Drag it beside the Project Explorer tab on the left, then close Project Explorer.
        3. 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.
  3. Run the database.
    1. Open a command prompt (Windows key, then type cmd).
    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.
      • Tip: 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.
      • Keep the command line window open as long as you need the Derby connection.
  4. Setup the application server in Eclipse.
    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.
    5. Start GlassFish. (Right click on it.)
    6. 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.
  5. Optional step: setup the database viewer.
    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, the database has to be running, of couse.
      • Once you’ve started Derby from the command line, in Eclipse, click Test Connection.
      • It should say, Ping succeeded!
    8. Click Finish.
    9. You can use the Database Connections tab to check the actual contents of the database when you run the examples.

Troubleshooting