About this file

These are step-by-step instructions that describe how you can set up an environment for the Scalable Enterprise Applications course.

Setting up the examples’ environment

  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 bin 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. 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.
  4. 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

Common tasks

Running the database

In most of the examples, we use JPA, which is configured to try to connect to a running Derby instance. The following steps help you start a Derby instance. You need to do this again every time you start the computer.

Open a command prompt (Windows key, then type cmd), then execute the following.

cd %USERPROFILE%
mkdir derbytmp
cd derbytmp

set "DERBY_OPTS=-Duser.language=en -Dderby.drda.debug=true"
"c:\Program Files\Java\jdk1.8.0_152\db\bin\startNetworkServer.bat"
  1. If Derby is installed somewhere else on your computer, you will have to change the "c:\Program Files\Java\jdk1.8.0_152\db bit.
  2. After some seconds, you will see a message Apache Derby Network Server started and ready to accept connections on port 1527. If you don’t, there is something wrong.
  3. Keep this command line window open as long as you need the Derby connection.

Notes:

Web applications

You can create a web application in Eclipse in the following way.

  1. Make a new Dynamic Web Project.
  2. Right click on the project in Project Explorer, and choose Java EE Tools>Generate Deployment Descriptor Stub. This generates a web.xml file in WebContent/WEB-INF.
  3. If you are using JPA within GlassFish, you have to set that up as well.
  4. Go to the GlassFish Console: in your browser, go to the URL http://localhost:4848.
  5. Select Create New JDBC Resource, and create two resources for each of your persistence units: jdbc/YOURPERSISTENCEUNIT__pm and jdbc/YOURPERSISTENCEUNIT__nontx.
  6. Now, we are using Derby even more indirectly: we use JTA (Java Transaction API), which has to be indicated in META-INF/persistence.xml.
  7. Of course, Derby has to be running when you are deploying your application. See the section Running the database.
  8. Note: if you encounter a problem while deploying your application (for example, sometimes you get the message Publishing to GlassFish ... has encountered a problem with the details cannot Deploy your-application-name deploy is failing=Application with name [your-application-name] is not deployed), you may have to explicitly remove it from GlassFish before you can attempt to deploy the application again. To do that, go to the Servers tab in Eclipse, select the application, and press Del.
  9. Basic setup is done, now you can create HTML files, servlets, JSP files, @WebMethods etc.

Unfortunately, the GlassFish console sometimes fails spectacularly when you try creating a resource with it. Here is another approach.

  1. Open a console.
  2. Run $GLASSFISH/bin/asadmin start-domain
  3. Run $GLASSFISH/bin/asadmin create-jdbc-resource --connectionpoolid=DerbyPool RESOURCENAME

EJB

You can create a basic EJB following these steps. You will need to create four projects.

  1. Make a project for the interface of the EJB. It will surely contain a Java interface for the EJB, but can also contain helper classes.
  2. Make an EJB project for the implementation of the EJB.
  3. Make an Enterprise Application Project that deploys the EJB.
  4. Make a client project with JNDI. (Or, alternatively, with dependency injection.)