About this file
These are step-by-step instructions that describe how you can set up an environment for the Scalable Enterprise Applications course.
- The description uses specific tools: Eclipse, EclipseLink, Payara etc.
- You can do the same using a different IDE (or, indeed, from the command line), different JPA provider, different application server etc.
- If you feel adventurous, try to set up your environment in a different way than is described here.
- In that case, you will have to do your own research on how to set up the environment.
- The instructions in this document spoon-feed you. If you abandon them, prepare to feel 😓😨😱😖😆😵.
- The steps should work on all common operating systems.
- The order of the steps is important.
- If you skip some steps, or take some steps out of order, the system may not work out of the box.
- If you run into any problems, look at the Troubleshooting section.
Setting up the examples’ environment
- Get the necessary files.
- You can download all files at the same time to save time.
- You can skip those components which you already have.
- On Windows, I suggest you use 7-Zip Portable to extract the zip files.
- 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.
- 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.
- EclipseLink Installer.
- Extract the downloaded zip.
- 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.
- Lombok.
- 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.
- The examples’ zip file.
- Setup Eclipse.
- 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.
- Install Eclipse add-ons.
- Open
Help⇉Eclipse Marketplace
. Search for GlassFish Tools
, and install it.
- Go to the Marketplace again, and install
AnyEdit Tools
as well.
- 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.
- Restart Eclipse now.
- Setup library access paths.
- Go to
Window⇉Preferences⇉Java⇉Build Path⇉Classpath Variables
.
- 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.
- Prepare the examples.
- 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.
File⇉Import
, select Existing Projects into Workspace
.
- Browse your workspace folder.
- Click
Finish
.
File⇉Import⇉Working Sets
.
- Select
enterprise-application-examples.wst
in your workspace folder, then click Finish
.
- A
Package Explorer
view appears. Drag it beside the Project Explorer
tab on the left, then close Project Explorer
.
- 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
.
- Setup the application server in Eclipse.
- 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
.
- Start GlassFish. (Right click on it.)
- 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
.
- Optional step: setup the database viewer.
- Go to
Window⇉Show view⇉Data Source Explorer
. A tab labelled Data Source Explorer
opens.
- In the tab, right click on
Database Connections
, and select New...
- Choose
Derby
, then click Next
.
- Click the globe with star/green plus icon (tooltip: “New Driver Definition”)
- Choose
Derby Client JDBC Driver, 10.2
.
- You’ll see a red error indicator. Don’t worry, we’ll fix it.
- Choose the
JAR List
tab.
- Click on
derbyclient.jar
, then on Edit JAR/Zip...
- Select
db\lib\derbyclient.jar
under your JDK folder.
- Click
OK
to exit "Edit Driver Definition"
- Now the
Drivers
dropdown contains a "Derby Client JDBC Driver"
- 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!
- Click
Finish
.
- You can use the
Database Connections
tab to check the actual contents of the database when you run the examples.
Troubleshooting
- Installation problems. 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.
- On Windows, the Eclipse shortcut in the menu may be set up only halfway. Open the properties of the shortcut, and see if
Start in
is empty. If it is, enter Eclipse’s directory here; you can copy it from the Target
field above.
- 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. Run Derby from the command line.
- Derby problems.
- If you have problems with the database, it’s possible that you’ve started Derby in the wrong folder.
- If Derby doesn’t run from the command line, try invoking
set "DERBY_OPTS=-Duser.language=en -Dderby.drda.debug=true"
before you call startNetworkServer
.
- If Eclipse is slow.
- Make your antivirus, indexing service etc. ignore the following folders: 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 folders 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.
- Compilation errors.
- Read the error message if there is one.
- This suggestion may seem trivial, but it’s so easy to forget reading the error messages.
- The error message may be somewhat hidden, and you have to click the
Details
button.
- If you forget a crucial step, you might get an error message that doesn’t seem to make sense.
- For example, classes that you use in the interface of an EJB have to be
Serializable
.
- If a file or folder is missing, and you know that it’s present, you can
Refresh
the project from its context menu.
- 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.
- An error marker shows up beside a project.
- Check the project properties, most notably
Java Build Path⇉Libraries
.
- Open the Markers view (
Window⇉Show View⇉Markers
), and have a look at the error message.
- You can use
Close Unrelated Projects
in the project’s context menu to see just the relevant messages.
- GlassFish problems.
- 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.
- 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
Clean
in GlassFish’s context menu.
- Stop the GlassFish server and restart it.
- Things to try if all else fails, in the approximate order of induced discomfort.
- Use
Project⇉Clean...
in Eclipse.
- 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.
- Restart with a new workspace, and go through the setup steps again.
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"
- 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.
- 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.
- Keep this command line window open as long as you need the Derby connection.
Notes:
- The first three instructions ensure that you end up in a directory that you can write into.
- You are allowed to use a different directory, provided that that you can write into it.
- If the folder is not writable, then Derby will seemingly start up, but you’ll get errors anyway.
- On Windows, look at the directory in the prompt. If it contains
Program Files
, it is not good.
- You can delete the
derbytmp
directory once you’re done running Derby.
- The
DERBY_OPTS
line helps avoid a problem that seems to manifest if your operating system is set to a language other than English.
Web applications
You can create a web application in Eclipse in the following way.
- Make a new
Dynamic Web Project
.
- 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
.
- If you are using JPA within GlassFish, you have to set that up as well.
- Go to the
GlassFish Console
: in your browser, go to the URL http://localhost:4848
.
- Select
Create New JDBC Resource
, and create two resources for each of your persistence units: jdbc/YOURPERSISTENCEUNIT__pm
and jdbc/YOURPERSISTENCEUNIT__nontx
.
- Note the double underscores.
- Now, we are using Derby even more indirectly: we use JTA (Java Transaction API), which has to be indicated in
META-INF/persistence.xml
.
- Of course, Derby has to be running when you are deploying your application. See the section Running the database.
- 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.
- Basic setup is done, now you can create HTML files, servlets, JSP files,
@WebMethod
s etc.
- For further details, look at the examples.
Unfortunately, the GlassFish console sometimes fails spectacularly when you try creating a resource with it. Here is another approach.
- Open a console.
- Run
$GLASSFISH/bin/asadmin start-domain
- If your GlassFish application server is already running, you don’t need this step.
- Run
$GLASSFISH/bin/asadmin create-jdbc-resource --connectionpoolid=DerbyPool RESOURCENAME
- For the example, replace
RESOURCENAME
with jdbc/books__pm
and jdbc/books__nontx
.
- Note the double underscores.
- For your own projects, replace the
jdbc/books
parts above with your JTA data source, which is located in your project: JPA Content>persistence.xml
, look inside the Source
tab, see the jta-data-source
element
EJB
You can create a basic EJB following these steps. You will need to create four projects.
- 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.
- Make an EJB project for the implementation of the EJB.
- In it, create an EJB class that implements your Java interface from the interface project.
- Note that you will have to “fix your project setup” for that.
- Annotate your class with
@Stateless
and @Remote
similar to the example.
- Make an Enterprise Application Project that deploys the EJB.
- Right click on the project, and in
Deployment Assembly
, add both the interface project and the EJB project to it.
- Make a client project with JNDI. (Or, alternatively, with dependency injection.)