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. Java Development Kit 1.8.
      • 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_152 at the time of writing.
      • One step in this description requires Java 1.8. Therefore, Java 1.8 has to be installed.
        • It is possible to use Java 1.9 for all other steps, and it’s not a problem if both versions are installed.
    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 4 with a few fixes.
        • Note: there is also a newer edition of GlassFish (version 5). At the moment, Eclipse’s GlassFish Tools does not support it.
      • Extract the downloaded zip.
    5. Lombok.
    6. Derby.
      • If you use Java 1.8, Derby is already installed, and is located at the db folder of your JDK folder. By default, it will be installed in (supposing you have version 1.8.0_152):
        • Windows: C:/Program Files/Java/jdk1.8.0_152
        • 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_152.jdk/Contents/Home/
      • If you use Java 1.9 or newer, Derby isn’t included in the distribution anymore. Download the lib distribution of Derby manually and extract the zip.
    7. The examples’ zip file.
  2. Setup Eclipse.
    1. Run Eclipse. Select a workspace folder.
      • I suggest you name the folder workspaceSEA so that it’s easy to see what it contains.
      • 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.
        • Note: jar files are executable; they can be run as any other program, e.g. double click on them.
      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.
        • DERBY: your extracted db-derby-10.14.1.0-lib folder, or the db folder under your JDK (for Java 1.8).
        • ECLIPSELINK: your eclipselink folder.
        • GLASSFISH: your payara41 folder.
          • Note: choosing the folder that contains the payara41 folder (whose is payara4-1.1.173 or similar) is not good enough.
        • 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 folder.
        • If you don’t see a lot of subfolders will in the workspace folder, maybe you’ve created an extra folder.
      2. File⇉Import, select Existing Projects into Workspace.
        1. Browse your workspace folder.
        2. Click Finish.
      3. File⇉Import⇉Working Sets.
        1. Select enterprise-application-examples.wst in your workspace folder, 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 folder that you can write into.
      • If the folder is not writable (e.g. you entered the db/bin folder to start Derby on Windows), then Derby will seemingly start up, but you’ll get errors anyway.
      • Tip: make a new folder for this purpose, because Derby will create a lot of files in the folder.
    3. Execute the command DERBY\bin\startNetworkServer.bat (replace DERBY with your Derby 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 executing 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.
      • As GlassFish location, choose the glassfish folder under payara41.
      • If Java location is not automatically filled, put your JDK folder there. Java 1.9 is not recognised here; you are required to have Java 1.8.
      • Do not enter an admin password. The default GlassFish configuration has an empty password.
      • If Eclipse asks, the admin port is 4848.
    2. Start GlassFish. (Right click on it.)
    3. 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