Environment setup for Scalable Enterprise Applications
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 instructions in this document spoon-feed you. If you abandon them, prepare to feel đđ¨đąđđđľ.
If you feel adventurous, try to set up your environment in a different way. It is possible to use a different IDE (or, indeed, the command line), different JPA provider, different application server etc.
If you go your own way, you will have to do your own research on how to set up the environment. It will be quite similar, but very different in many places.
The steps should work on all common operating systems.
Follow the description closely.
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.
All details in the description are important.
Example: if you are supposed to choose your glassfish5 folder, donât choose the glassfish-5.1.0 one.
If you run into any problems, take a look at the Troubleshooting section.
Once downloaded, run the downloaded .jar file. Just like a standard executable, you can double click it.
In the installer, donât rely on autodetection: select your Eclipse directory manually. On Windows, it should be under C:\Users\*user*\eclipse\jee-2019-09 (where *user* is your username).
You can download all files at the same time to save time.
You can skip those components which you already have.
For zip files: unzip them into a separate directory.
On Windows, I suggest you use 7-Zip Portable to extract the zip files.
You can also âunzipâ JDK installer .exe files.
Install Eclipse modules.
Run Eclipse.
Instead of the suggested folder name, call the workspace folder workspaceSEA.
I suggest that you use this workspace for this course only.
If you already have a workspace, and you install SEA materials into it, it will work, but it will be messy.
You may tick Use as the default and do not ask again.
If you use Eclipse for other purposes, you can create other workspaces (FileâSwitch WorkspaceâOther), and switch between them using FileâSwitch Workspace.
Install the following.
Using HelpâEclipse Marketplace, install AnyEdit Tools.
Using HelpâInstall new software (not from the marketplace), install the following.
Note: unchecking the Contact all update sites... option can shorten the time needed.
Setup Eclipse.
Setup library access paths.
Open WindowâPreferencesâJavaâBuild PathâClasspath Variables.
Note: when you open WindowâPreferences, type a part of what you search for (e.g. variables) to filter options quickly.
Note: typing into the search field in the main window (on the top right; accessible with the keyboard shortcut Ctrl-3) can be even faster.
Click New... to add the following variable.
GLASSFISH: use Folder and choose extracted glassfish5 folder (not the bin folder inside)
If the Markers tab shows Unbound classpath variable problems, open the related projectâs properties, then Java Build PathâLibraries. There, all items with variables should show the resolved full paths. If some of them are missing, fix the variableâs contents.
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-applications-working-sets.wst (the only file in the workspace folder, below the directories) in your workspace folder, then click Finish.
These additional steps are also suggested for extra comfort.
In WindowâPreferences, on the bottom left there is an arrow Ⲡwhose tooltip says Import. Click it, and select eclipse-sea-quick-preferences.epf in the workspace directory.
Close the Task List and Outline tabs, as they wonât be needed.
Click the â˝ triangle on the right top inside the sidebar of Package Explorer. There, select Filters, and tick Libraries from external and Libraries in project.
Place your Package Explorer tab to the left side, then close Project Explorer.
Place your Servers tab to the right of Console so that both are visible.
When you run a project without saving it beforehand, a Save and Launch dialog window appears. In it, tick Always save resources before launching.
Setup the application server. [Not needed for JPA only]
In FileâNewâOther...âServer, choose GlassFish.
As GlassFish location, choose the glassfish folder under glassfish5.
If Java location is not automatically filled, enter your JDK folder there.
Anything newer than Java 8 is not recognised here and/or wonât work properly.
Change the name of the server to GlassFish SEA.
Youâll have to make this change on the tab whose subtitle is Define GlassFish runtime properties..
If you forget this step, you can later change the name in WindowâPreferencesâServerâRuntime Environments.
You shouldnât need to change anything else.
Do not enter an admin password. The default GlassFish configuration has an empty password.
If itâs not set by default, the admin port is 4848.
For the servlet-jpa example, in ResourcesâJDBCâJDBC Resources, add the resource pool jdbc/books.
In older GlassFish versions, you would need to add two resources: jdbc/books__pm and jdbc/books__nontx.
Note the double underscore.
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 and resource type Queue.
Setup the database viewer. [Optional for JPA]
Go to WindowâShow viewâData Source Explorer. The Data Source Explorer tab 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 GLASSFISH/javadb/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.
Common tasks
Running the database server
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 working with the examples.
Open a command prompt (Windows key, then type cmd), then execute the following commands.
You can copy-paste the lines into the command line.
In the last command, substitute GLASSFISH with the path to your glassfish5 folder.
cd %USERPROFILE%
mkdir derbytmp
cd derbytmp
set "DERBY_OPTS=-Duser.language=en -Dderby.drda.debug=true"
"GLASSFISH/javadb/bin/startNetworkServer.bat"
After some seconds, you will see the 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 may 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 name in the prompt. If it contains Program Files, it is definitely not good.
You can delete the derbytmp folder once youâre done running Derby.
The DERBY_OPTS line helps avoid a problem that seems to appear if your operating system uses a display language other than English.
Creating a Web application
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.
Create the resource jdbc/YOURPERSISTENCEUNIT.
For older versions of GlassFish, you have to create two resources for each JTA data source: jdbc/YOURPERSISTENCEUNIT__pm and jdbc/YOURPERSISTENCEUNIT__nontx.
Note the double underscore.
The JTA data source can be found under JPA Contentâpersistence.xmlâSourceâjta-data-source in your project.
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 server.
Basic setup is done, now you can create HTML files, servlets, JSP files, @WebMethods etc.
Unfortunately, the GlassFish admin console sometimes fails spectacularly when you try creating a resource with it. Here is another approach.
Run $GLASSFISH/bin/asadmin start-domain in a console.
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, RESOURCENAME can be jdbc/books (or, for older GlassFish versions, jdbc/books__pm and jdbc/books__nontx).
Creating an EJB
You can create a basic EJB following these steps. You will need to create four projects.
Make a Java project for the interface of the EJB.
In it, create Java interfaces and supporting classes for the EJB.
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 Java project for the client.
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 path here.
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 to 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.
A problem can arise while deploying your application.
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.
In this case, 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.
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.
Have a look at what was printed in $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, try this 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.
Also, use ProjectâClean... afterwards.
Close the project and reopen it.
Quit Eclipse and start it again.
Restart with a new workspace (FileâSwitch Workspace), and do all setup steps from the beginning.