L01: Using the WebSphere Application Server Liberty Profile for lightweight, rapid development. Lab Exercise

Transcription

1 L01: Using the WebSphere Application Server Liberty Profile for lightweight, rapid development Lab Exercise

2 Copyright IBM Corporation, 2012 US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

3 Contents LAB 1! USING THE LIBERTY PROFILE FOR LIGHTWEIGHT, RAPID DEVELOPMENT... 7! 1.1! CONFIGURING YOUR DEVELOPMENT ENVIRONMENT (DISCONNECTED SCENARIO)... 9! 1.1.1! INSTALL THE LIBERTY PROFILE IN A DISCONNECTED MODE... 9! 1.1.2! LAUNCH THE ECLIPSE INDIGO DEVELOPMENT ENVIRONMENT... 13! 1.1.3! CONFIGURE YOUR LIBERTY SERVER IN ECLIPSE IN A DISCONNECTED MODE... 17! 1.2! DEPLOYING A SAMPLE APPLICATION TO THE LIBERTY PROFILE... 32! 1.2.1! IMPORT A SAMPLE APPLICATION INTO ECLIPSE... 32! 1.2.2! MODIFY THE APPLICATION... 36! 1.2.3! MODIFY THE SERVER HTTP(S) PORTS... 40! 1.2.4! ADD INFO LOGGING OUTPUT TO THE CONSOLE... 46! 1.2.5! UPDATE TRACE SPECIFICATION... 48! 1.3! CUSTOMIZING THE LIBERTY JVM OPTIONS... 51! 1.4! INTRODUCING THE LIBERTY ENVIRONMENT VARIABLE CONFIGURATION... 53! 1.5! INTRODUCING THE LIBERTY BOOTSTRAP PROPERTIES... 55! 1.6! SUMMARY... 55! 1.7! APPENDIX A: DOWNLOADING THE LIBERTY PROFILE FROM WASDEV... 56! 1.8! APPENDIX B: DOWNLOADING ECLIPSE FROM WASDEV... 58! Contents Page 3

4

5 Lab 1 Using the Liberty Profile for lightweight, rapid development In this lab, you are going to install the Liberty Profile in a disconnected mode, meaning the resources have already been downloaded from the internet and are available locally on the virtual image that has been provided. And, then use you will work with the Liberty profile server in Eclipse to do some simple application development. The Liberty Profile is a lightweight, composable application server runtime that is small to download, easy to install and configure, and very fast to start. Both the Liberty Profile and the Eclipse adapter to use this profile in your development environment are available at no charge for a single user to unit test your applications on the desktop.you can use this environment to develop applications against the lightweight Liberty Profile and then transfer your environment to a production Network Deployment server with full fidelity. This lab uses a desktop virtual image, and the following components have been previously downloaded from the internet and are available on the virtual image: Eclipse Installed WebSphere Tools Plug-in for eclipse Liberty Profile server The Eclipse Java EE IDE for Web Developers version (Indigo) platform has been pre-installed on the virtual image. However, it is available as a free download on WASDev at the following URL: The IBM JDK 1.6 has been pre-installed on the virtual image, and is set as the default JRE for the development environment. Page 7

6 Windows NOTE: You may be prompted with a Windows security alert when launching the Liberty Server and deploying an application the server. Just select Unblock, and continue with the lab instructions. In this exercise, you will: Page 8

7 Install the WebSphere Application Server V8.5 Liberty Profile in a disconnected mode Install the WebSphere tools plug-in for Eclipse in a disconnected mode Configure Eclipse to work with your Liberty Profile server Use the Eclipse workbench to modify your Liberty Profile server configuration Use the Eclipse workbench to publish and modify an existing application Customize the Liberty Server JVM Options Be introduced to the Liberty Server Bootstrap properties file Be introduced to the Liberty Server environment configuration file To run this lab, your workstation must meet the following requirements: Approximately 8GB of storage available for the Windows XP virtual image Approximately 1.5 GB of memory free to run the developer workbench and the server The lab files for this lab must be unzipped on your workstation; the instructions will refer to the location of the sample files using the <LAB_FILES> variable. Connectivity to the internet is NOT required 1.1 Configuring your development environment (Disconnected Scenario) The Liberty Profile, Eclipse, and the WebSphere Developer Tools to support the Liberty Profile in Eclipse are all available as no-charge downloads for development and evaluation without IBM support. This means that you can set up an end-to-end development environment at no cost! Install the Liberty Profile in a disconnected mode 1. Install the WebSphere Liberty profile from the package that has already been downloaded from the internet a. Locate the <WLP_JAR> file that has been provided by the instructor. i. Optionally, copy the LabFiles directory provided by the instructor to the C:\Student directory on the virtual image. X:\Student\LabFiles\Lab01\LibertyProfile\wlp-developers jar Page 9

8 b. c. Open a Windows command prompt. And, then change to the directory that contains the wlp-developers jar file. Run the following command to install the Liberty profile into C:\Student\LibertyWork directory: java -jar wlp-developers jar --acceptlicense "C:\Student\LibertyWork" d. e. You will be left with a folder called C:\Student\LibertyWork\wlp (this document will refer to this folder as <LIBERTY_ROOT>). That s it! The Liberty Profile is installed and ready to use! TIP: Alternatively, the Liberty package can be downloaded and installed from the internet. The basic steps are illustrated in Appendix A. f. g. Explore the content of <LIBERTY_ROOT>. This should be located at C:\student\LibertyWork\wlp Open a file system browser or terminal session and go look at the content of the <LIBERTY_ROOT> folder. Page 10

9 h. i. Use a text editor to open the README.TXT file. It explains how to install and start the server, and contains information about how to configure the server, install applications, and so forth. You can close the text file, or keep it open as a reference. A default server is NOT included in the Liberty package. In this step, you will create a new default server. i. ii. Open a Windows command prompt. And, then change to the <LIBERTY_ROOT>\bin directory. This directory contains the server command that can be used to create, stop, and start the Liberty server. It can also be used to dump the configuration to aid in customer support. Enter and execute the following command to create a new server named defaultserver. server create defaultserver j. Using the Windows Explorer, Look under <LIBERTY_ROOT>/usr/servers/defaultServer. The folder name defaultserver indicates the server name. Initially, the server contains a server.xml file with the JSP feature enabled, and default HTTP(S) endpoints configured. You can open the server.xml file in a text editor and view it: server.xml Page 11

10 a. b. In this exercise, you will not be modifying the server configuration files directly rather, you will set up your server configuration in the next sections, using Eclipse. Notice that the server.xml file has the featuremanager section with the jsp-2.2 feature enabled on this server. To see which feature options are available for the Liberty Profile, open the <LIBERTY_ROOT>/lib/features folder and look through the list of.mf files. These files represent all of the features that you can enable in your Liberty Profile server. i. In terms of feature names, the string you need to include in the server.xml file to enable a feature corresponds to the name portion of the feature s.mf file. Consider the file jsp-2.2.mf. The feature name that you would add to the server.xml is jsp-2.2. For example: <feature>jsp,2.2</feature>0 Of course, you can add features to the server.xml file using the Liberty tooling in eclipse, as shown below. But don t worry; we will work with the Liberty Tools later in the lab. 2. Start the server. a. b. Open a command prompt or terminal session and navigate to <LIBERTY_ROOT>/bin Use the run option to start your server so that you can see the timestamp messages; you will not specify a server name, so the default server will be used. i. ii. On Windows: server.bat run On other platforms:./server run Page 12

11 c. The server will start very quickly; this sample output shows the server is ready to run. You should have noticed that the server started in just a few seconds. d. e. You will not be doing anything with the server now, so type CTRL+C in your command prompt to kill the server process. When prompted to terminate the batch job, type Yes Launch the Eclipse Indigo Development Environment 1. Launch the Eclipse Indigo for Java EE Developers (3.7.2) that has already been installed in the virtual image. TIP: the first time you launch the eclipse development environment, you may be presented with a dialog to upload Data usage. Just click the Cancel button and continue with the lab. Page 13

12 The Eclipse Indigo development environment is available as a free download, as a compressed archive file, from The compressed archive is approximately 215 MB. Page 14

13 a. b. Using the Windows Explorer, navigate to the eclipse directory, C:\Student\LibertyWork\eclipse. The eclipse directory will be referred to in these instructions as <ECLIPSE_ROOT>. Inside of <ECLIPSE_ROOT>, locate the Eclipse application file and open it (for example, by double-clicking it in your file browser). c. When the Eclipse launcher prompts you to Select a workspace, ensure the workspace is set to C:\Student\LibertyWork\workspace. And then click OK. Page 15

14 e. Your Eclipse IDE will open to the Welcome page. Click the Workbench icon in the upper right to continue to your workbench and begin using Eclipse. Page 16

15 TIP: As mentioned before, the Eclipse Indigo for Java EE Developers (3.7.2) can be downloaded from the internet. The basic steps are illustrated in Appendix B Configure your Liberty server in Eclipse in a disconnected mode 1. Install the WebSphere Liberty Profile developer tools plug-in for Eclipse from a previously downloaded zip file. a. b. IBM provides a no-charge adapter so that you can easily use your Eclipse environment with the Liberty Profile Start your Eclipse workbench if it is not already started. i. ii. iii. Navigate to <ECLIPSE_ROOT> (C:\student\LibertyWork\eclipse) Double-click on eclipse.exe Accept the default workspace location, when prompted c. Within Eclipse, go to Help > Install New Software. d. If there is no internet connection, you may see an error indicating a problem connecting to the software sites. That is OK since we will be installing from a local repository. Just click the OK button and continue. Page 17

16 e. On the Available Software page, click the Add button. f. In the Add Repository Dialog, click on the Archive button and browse to the WebSphere Developer Tools zip archive file provided by the instructor. Then click the OK button to begin the installation of the plug-ins. X:\Student\LabFiles\Lab01\WebSphereDeveloperTools\wdt-update-site_8.5.0.WDT85- I _0920.zip g. Install the Liberty Profile Server plug-in i. From the list of available software to install, select the following components: (1) WebSphere Application Server V8.5 Tools Liberty Profile. (2) WebSphere Application Server V8.5 Tools ii. iii. Deselect the checkbox labeled Contact all update sites during install to find required software Click the Next button to install the selected components. Page 18

17 NOTES: The Web Development Tools have been pre-installed on the virtual image. The WAS V8.5 Tools includes the WebSphere Persistence Editor which is needed in the lab. h. Review the details of the items to be installed. And, then click the Next button. Page 19

18 i. Accept the license terms. And then click Finish to install the tools. Again, this process may take several minutes. Page 20

19 j. Your Eclipse environment will begin processing the plug-in components; this process may take a few minutes. k. If you are prompted with any security warnings, you can ignore the warning and click OK to continue the installation Page 21

20 l. When the installation finishes, you will be prompted to restart Eclipse. Click the Restart Now button. When Eclipse restarts, if you are prompted for a workspace, accept the default and click OK to continue to the development workbench. 2. Configure a Liberty server instance in Eclipse. a. At the bottom of the IDE workbench, select the Servers tab, then right-click in the server list area and choose New > Server from the context menu. Page 22

21 b. In the Define a New Server dialog, expand the IBM folder, and select WebSphere Application Server V8.5 Liberty Profile. Keep the default host and server names, and click Next. Page 23

22 c. In the WebSphere Runtime Environment dialog, click Browse to open the file system browser. Navigate to your <LIBERTY_ROOT> directory, C:\Student\LibertyWork\wlp. And, then click OK. TIP: The virtual image has the IBM JDK 6 installed, and we will use that for the Liberty server. Liberty can also run with the IBM JDK 7 and the Oracle Hotspot JDK 6 or 7. Notice that, if you do not have the Liberty profile installed yet, you can easily download and install it using the links on this panel. Click Next to continue. d. In the WebSphere Server dialog, notice that the WebSphere server field is set to your defaultserver instance. i. For this exercise, create a new instance for your development environment by clicking the New button. Page 24

23 e. In the new server panel, locate the Server name field and type labserver. You will be using this server to run a simple servlet sample application. Click Finish. f. In the New Server dialog, click Finish. You will notice that the server contains the jsp-2.2 feature enabled and a default HTTP Endpoint definition. Page 25

24 g. Now your server is defined! 3. Start the server. a. b. From the Servers view, select your labserver instance and click the Start the server button ( ). Alternatively, you can also right-click the server name and choose the Start option from the context menu. Switch to the Console view. Look at the messages to see how fast your server starts! Page 26

25 4. Modify the lab server configuration. a. b. In the Servers view, double-click on your labserver server to open the configuration editor (or right-click and select Open from the context menu). First, expand the Publishing section and notice that the server is set to automatically detect and publish changes. Keep this default setting. Page 27

26 c. In this exercise, you will be deploying a simple servlet application, so try enabling the servlet feature on this server. On the Overview page, locate the Liberty Profile Settings section, and click the Open server configuration link to open the server.xml editor. d. Start by providing a meaningful description for your server. In the Configuration Structure area, highlight the Server Configuration item in the list. In the Configuration Details area on the right, delete the default description for your server and provide something more meaningful, such as Liberty server for labs. e. To add a feature, such as servlet-3.0, go back in the Configuration Structure area, and determine if the Feature Manager has already been added to the configuration. i. ii. The Feature Manager will already exist in the configuration if the Liberty Server configuration already has features defined, such as jsp-2.2. Review the Feature Manager settings. In this lab, the Feature Manager has already been added to the configuration profile because of the jsp-2.2 feature having been included in the labserver you created earlier. Page 28

27 f. Add an additional feature (servlet-3.0) i. Select Feature Manager located under the Configuration Structure area. g. Highlight Feature Manager in the Server Configuration list. On the right side, in the Feature Manager Details area, click the Add button. Then, use the menu to select the servlet-3.0 feature. h. In the server.xml editor, switch to the Source tab at the bottom to see the XML source for this configuration file. You will see that a new featuremanager element has been added, and that it contains the servlet-3.0 feature. Page 29

28 i. Now you have a server that is configured to use the servlet-3.0 feature. Click the Save button ( ) to save your changes (or use CTRL+S). Page 30

29 j. Switch to the Console panel at the bottom of the workbench and review the latest messages. These messages are showing that your Liberty server automatically detected the configuration update, processed the feature that you enabled, and is now listening for incoming requests. i. You will notice that the server configuration was automatically updated and the feature update was completed very quickly. In this example, it was one second. k. Now you are ready to start working with a sample application that uses the Servlet or JSP features. Page 31

30 1.2 Deploying a sample application to the Liberty Profile Import a sample application into Eclipse 1. A simple servlet WAR file has been provided for this exercise; import it into your workbench. a. In Eclipse, go to File > Import. Expand the Web section, then select WAR file. Click Next. Page 32

31 b. c. In the WAR file field, select Browse. Navigate to X:\Student\LabFiles\Lab01\Sample1.war and click Open. Set the Target runtime to WebSphere Application Server V8.5 Liberty Profile. Click Finish d. Now, you have a Sample1 web project in your workspace. You can expand it in the Enterprise Explorer view to see the different components of the project. Page 33

32 2. Start the sample application. a. In the Enterprise Explorer pane, navigate to the SimpleServlet.java as shown below. i. Sample1 -> Java resources -> src -> wasdev.sample -> SimpleServlet.java b. c. Right-click on SimpleServlet.java. From the context menu, select Run As > Run on Server. Page 34

33 d. In the Run On Server dialog, verify that Choose an existing server is chosen. i. Under localhost, select the WebSphere Application Server V8.5 Liberty Profile server that you defined earlier. The server should be listed in Started state. ii. Click Finish. e. After a moment, your application will be installed and started. See the Console pane for the corresponding messages. Page 35

34 f. g. h. In the main panel of the workbench, a browser also opened, pointing to If you receive a 404 the first time, try to refresh the browser once the application is completely deployed and started. At this point, you should see the rendered HTML content generated by the simple servlet Modify the application 1. Open the servlet source. a. In the Enterprise Explorer panel, expand the Sample1 project, then go to Sample1 > Servlets. Double-click the wasdev.sample.simpleservlet entry to open the Java editor for the servlet. Page 36

35 Page 37

36 b. This is how the SimpleServlet.java source looks in the editor: c. This is a very simple servlet with a doget() method that sends out an HTML snippet string as a response. Your doget() method will look similar to this (some of the HTML tags might be a little different that is ok). 0/**0 0*0@see0HttpServlet#doGet(HttpServletRequest0request,0HttpServletResponse0response)0 0*/0 0protected0void0doGet(HttpServletRequest0request,0HttpServletResponse0response)0throws0 ServletException,0IOException0{0 0 response.getwriter().print(0 0 0 "<h1><font0color=green>simple0servlet0ran0successfully</font></h1>" "Powered0by0WebSphere0Application0Server0V8.50Liberty0Profile");0 0} 2. Modify the application and publish the change. a. In the doget() method, Locate the <h1> heading element of the HTML string, and notice that it contains a font tag to set the color to green. Modify this string by changing the text green to purple, so your font tag will look read <font color=purple>. 0response.getWriter().print(0 0 0 "<h1><font0color=purple>simple0servlet0ran0successfully</font></h1>" "Powered0by0WebSphere0Application0Server0V8.50Liberty0Profile");0 Page 38

37 b. Save your changes to the Java source file by either clicking the Save button ( ) or using CTRL+S. c. d. Recall that your server configuration is setup to automatically detect and publish application changes immediately. By saving the changes to your Java source file, you automatically triggered an application update on the server. To see this, go to the Console view at the bottom of the workbench. The application update started almost immediately after you saved the change to the application, and the update completed in seconds. 3. Access the updated application. a. Refresh the browser in your workbench to see the application change. The title should now be rendered in purple text. b. c. Optionally continue to play around with application modifications and see how quickly those changes are available in the deployed application. Maybe put in some additional text to display on the page, or add extra HTML tags to see formatting changes (you could add a title tag to set the text displayed in the browser title bar, for example, <head><title>liberty Profile</title></head>). The key is that this edit / publish / debug cycle is very simple and fast! Page 39

38 1.2.3 Modify the server HTTP(s) ports 1. Open the server configuration editor. a. In the Servers view, double-click on the labserver server to open the configuration Overview page (or right-click the labserver server and choose Open). b. In the Liberty Profile Settings section, select the Open server configuration link to open the server.xml editor. c. Ensure you are in the Design mode by selecting the Design tab on the Server Configuration editor. Page 40

39 d. Under the Configuration Structure section, Click on Feature Manager. e. Select the Application: Sample1 item in the Server Configuration and look at its configuration details. From here, you can set basic application parameters, including the context root for the application. Page 41

40 f. Select the Application Monitoring item in the Server Configuration and look at its configuration details. You can see that the monitor polls for changes every 500ms using an mbean trigger. You did not add any JMX features to your server to support mbean notification so how is that working? g. Select the Feature Manager item to see the features that are configured on your server. You added the servlet-3.0 feature because you knew that you were going to be running a servlet application. But the development tools automatically added the localconnector-1.0. feature to your server to support notifications and application updates. In fact, you would not have needed to add the servlet feature to your server at the beginning at all the tools would have automatically enabled that feature, based on the content of the application. Page 42

41 2. Change the HTTP port. a. b. Using the default HTTP port (9080) is an easy way to quickly bring up an application, but it is common to want to use a different port. This is an easy thing to change. In the Configuration Structure area, select Server Configuration, then select HTTP Endpoint Page 43

42 c. In the HTTP Endpoint Details area, Change the HTTP Port to i. Update the Port field to d. e. Save your changes to the server configuration (CTRL+S). You can review your full server configuration in the server.xml source file. Back in the server configuration editor, switch to the Source tab at the bottom to view the full XML source for your server configuration. 0 0 f. After you saved your configuration changes, the configuration of your running server was automatically updated. The Console pane will show that the Sample1 servlet is now available on port Page 44

43 g. Now, you can access your sample application using the new port. In the browser in your workbench, change the port from 9080 to 9580 and refresh the application. Page 45

44 1.2.4 Add INFO logging output to the Console By default, the Liberty profile Server has the console log level set to AUDIT. In this section, you will change the level of log messages written to the console from AUDIT to INFO. You will perform this activity in the server.xml file using the UI. It is also possible to set default logging options in the bootstrap.properties file. If the logging options are set in the bootstrap.properties file, the logging options will take effect for ALL servers that are defined. 1. Open the server configuration editor. a. b. In the Servers view, double-click on the labserver server to open the configuration Overview page (or right-click the labserver server and choose Open). In the Liberty Profile Settings section, select the Open server configuration link to open the server.xml editor. c. Ensure you are in the Design mode by selecting the Design tab on the Server Configuration editor. 2. Add the Logging configuration option to the server a. Under the Configuration Structure section, Click on Server Configuration. And, then click the Add button. Page 46

45 b. On the Add Item dialog, select Logging, And, then click the OK button. c. The logging page displays the properties for the logging configuration, such as the name of the log files, the maximum size of log files, and the maximum number of log files to retain. Additional configuration information is displayed regarding tracing. Notice that the Console Log Level is set to AUDIT by default. Page 47

46 3. Change the Console log level to INFO using the pull down menu. a. Switch to the Source view for the server.xml file to see the configuration changes added to server.xml. <logging consoleloglevel="info"/> b. c. Save the configuration file. Stop and restart the server. The changes you made are dynamic and take effect immediately. However, running the SimpleServlet does not produce INFO messages because the Servlet has already been initialized in the environment. When you restart the server, you will immediately see INFO messages in the console Update Trace Specification By default, the Liberty profile Server trace specification is set to *=info=enabled. This is the same for Traditional WAS. Updating the trace specification for debugging is easily performed using the server configuration editor. You can specify the trace specification in the UI, or copy / paste the trace specification directly into the server.xml file. In this section, you will specify a trace specification using the configuration editor. And, then, you will look at the result in the servr.xml source file 1. Open the server configuration editor, if it is not already opened. Page 48

47 a. b. In the Servers view, double-click on the labserver server to open the configuration Overview page (or right-click the labserver server and choose Open). In the Liberty Profile Settings section, select the Open server configuration link to open the server.xml editor. c. Ensure you are in the Design mode by selecting the Design tab on the Server Configuration editor. 2. Update the Trace Specification under the logging configuration. a. Click on Logging under the Server Configuration section. This displays the logging and trace details. b. Update the Trace Specification field with the following trace string: webcontainer=all=enabled:*=info=enabled c. Switch to the Source tab on the configuration editor and view the logging configuration. : <logging tracespecification="webcontainer=all=enabled:*=info=enabled"/> Page 49

48 d. Save the configuration changes. 3. Run the SimpleServlet to produce trace messages. a. b. Navigate to SimpleServlet.java Using the menus, run the SimpleServlet on the Liberty Server 4. Verify that the trace.log file contains trace data. a. From a Windows Explorer, navigate to the server logs directory. C:\Student\LibertyWork\wlp\usr\servers\labServer\logs The trace.log file has been created and contains content. b. You can view the trace.log file using Notepad. Page 50

49 Note: To open the trace.log file using Wordpad, you must first stop the Liberty server. 5. Very importantly, reset the trace specification back to the defualt value. a. Switch to the Source tab on the configuration editor and update the logging configuration to: logging consoleloglevel="info" tracespecification="*=info=enabled "/> b. Save the configuration. 1.3 Customizing the Liberty JVM Options The generic JVM arguments are used to configure and adjust how the JVM executes. The WebSphere Application Server Liberty profile is pre-configured with minimal settings defined. The following steps will direct you how to define custom generic JVM arguments such as heap settings for a Liberty server. 1. Create a text file named jvm.options in the ${server.config.dir} directory. TIP: On the virtual image for this lab, the ${server.config.dir} is c:\student\libertywork\wlp\usr\<servers>\<servername> The built in environment variables in the Liberty profile are discussed I the next section of this lab. a. Open the Enterprise Explorer view in eclipse b. Navigate to WebSphere Application Server V8.5 Liberty profile! Servers! labserver. c. Right mouse click on the labserver folder. And, then select New! File from the context menu. Page 51

50 d. Create new file named jvm.options in the labserver folder 2. a. Insert your generic JVM options, one per line, into the jvm.options file. Double click to open the file in the eclipse text editor b. Enter the following two lines in the jvm.options file to set the minimum and maximum heap size for eth labserver server. The following options will set the min / max JVM heap size to 25 MB and 500 MB respectively. -Xms25m -Xmx500m Page 52

51 TIP: The default minimum and maximum heap size values of the JVM heap size is: Xms4m and Xmx488m VerboseGC can be enabled by specifying -verbose:gc in the jvm.options file. Verbose GC output will be logged to the following location by default: <wlp.install.directory>/usr/servers/<servername>/logs/console.log TIP: Depending on your preferences, you might configure a single JVM or all Liberty JVMs with your options file. a. To apply these settings to a single server, save jvm.options at: ${server.config.dir}/jvm.options TIP: On the virtual image for this lab, the ${server.config.dir} is c:\student\libertywork\wlp\usr\<servers>\<servername> b. To apply these settings to all Liberty Servers, save jvm.options at: ${wlp.install.dir}/etc/jvm.options TIP: On the virtual image for this lab, the ${wlp.install.dir} is c:\student\libertywork\wlp The changes will take effect for all JVMs that do not have a locally defined jvm.options file. 3. Restart the server to enable changes. This concludes the customization portion of the lab. In the next sections, you will be introduced to the Liberty configuration files for customizing the server initialization and environment settings. 1.4 Introducing the Liberty Environment Variable configuration You can customize the Liberty profile environment using certain specific variables to support the placement of product binaries and shared resources. Page 53

52 The Liberty environment variables are specified using server.env file. You can use server.env file at the installation and server levels to specify environment variables such as JAVA_HOME, WLP_USER_DIR and WLP_OUTPUT_DIR. NOTE: You will not modify the default environment configuration in this lab. Review the information in this section to become familiar with the environment variables that are available for customizing the Liberty environment. The following Liberty profile specific variables can be used to customize the Liberty profile environment: ${wlp.install.dir} This configuration variable has an inferred location. The installation directory is always set to the parent of the directory containing the launch script or the parent of the /lib directory containing the target jar files. TIP: On the virtual image for this lab, the ${wlp.install.dir} is c:\student\libertywork\wlp WLP_USER_DIR This environment variable can be used to specify an alternate location for ${wlp.install.dir}. This variable can only be an absolute path. If this is specified, the runtime environment looks for shared resources and server definition in the specified directory. The ${server.config.dir} is equivalent to ${wlp.user.dir}/servers/servername. TIP: On the virtual image for this lab, the ${server.config.dir} is c:\student\libertywork\wlp\usr\<servers>\<servername> WLP_OUTPUT_DIR This environment variable can be used to specify an alternate location for server generated output such as logs, the workarea directory and generated files. This variable can only be an absolute path. If this environment variable is specified, ${server.output.dir} is set to the equivalent of WLP_OUTPUT_DIR/serverName. If not, the ${server.output.dir} is the same as ${server.config.dir}. TIP: On the virtual image for this lab, the ${server.output.dir} is c:\student\libertywork\wlp\usr\<servers>\<servername>, which is the same as ${server.config.dir}. Page 54

53 1.5 Introducing the Liberty Bootstrap Properties In this section of the lab, you will gain an understanding of how and when bootstrap properties are required during environment initialization. NOTE: You will not modify any of the default environment initialization. This information is provided in the lab for your reference. Bootstrap properties are used to initialize the runtime environment for a particular server. Generally, they are attributes that affect the configuration and initialization of the runtime. Bootstrap properties are set in a text file named bootstrap.properties. This file should be located in the server directory alongside the configuration root file server.xml. By default, the server directory is usr/servers/server_name. The bootstrap.properties file contains two types of properties: A small, predefined set of initialization properties. Any custom properties you choose to define which you can then use as variables in other configuration files (that is, server.xml and included files). You can edit the bootstrap.properties file using a text editor, or using the editor that is part of the Liberty profile developer tools. Changes to the bootstrap.properties file are applied when the server is restarted. TIP: As an example, the logging service can be controlled through the server configuration (server.xml) file. Occasionally you need to set logging properties so they can take effect before the server configuration files are processed; In this case you set them in the bootstrap.properties file instead of the server configuration. You do not usually need to do this to get logging from your own code, which is loaded after server configuration processing, but you might need to do this to analyze problems in early server start or configuration processing. This completes the lab exercise. 1.6 Summary In this exercise, you: Installed the WebSphere Application Server V8.5 Liberty Profile Page 55

54 Installed the Liberty Profile tools plug-in Configured a Liberty Profile server in your Eclipse environment and modified the server configuration Deployed a sample application and experienced the rapid edit / deploy cycle that is supported by this environment Added additional server features Modified the HTTP Endpoint configuration Customized the JVM options for the lab server to setup the min / max heap sizes for the lab server. Familiarized yourself with the environment initialization, (bootstrap.properties) file. Familiarized yourself with the environment configuration options, (server.env) file for the Liberty profile. 1.7 Appendix A: Downloading the Liberty Profile from WasDev Page 56

55 The Liberty package can be downloaded and installed from the internet. For your reference, the basic steps are illustrated below. This is for your reference only. Do not download the resources from the internet in this lab. a. b. c. Open a web browser and go to Go to the Download tab. In the main area at the top of the page, locate the Just want the Liberty Profile section, and click the button to download the Liberty Profile (the text here, shown below). Page 57

56 1.8 Appendix B: Downloading Eclipse from WasDev As mentioned before, the Eclipse Indigo for Java EE Developers (3.7.2) can be downloaded from the internet using these simple steps. This is for your reference only. Do not download the resources from the internet in this lab. a. b. In your browser, go back to and go to the Download section. From the main download area at the top of the page, locate Step 1, to download and install Eclipse. Click the link Eclipse Indigo for Java EE Developers (3.7.2). This will redirect you to the Eclipse download page. c. The Eclipse package is approximately 200MB in size, and may take several minutes to download. Page 58

57 L02: Learn to Accelerate your Web App Development with the WebSphere Application Server Liberty Profile Lab Exercise

58 Copyright IBM Corporation, 2012 US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

59 Contents LAB 2! LEARN TO ACCELERATE YOUR WEB APP DEVELOPMENT WITH THE WEBSPHERE APPLICATION SERVER LIBERTY PROFILE... 7! 2.1! LAB SETUP (REQUIRED ONLY IF YOU DID NOT COMPLETE LAB 1)... 8! 2.2! PREPARING THE LIBERTY PROFILE TO WORK AROUND A KNOWN ISSUE... ERROR! BOOKMARK NOT DEFINED.! 2.3! BLOG SERVLET APPLICATION... 9! 2.3.1! THE JPA (JAVA PERSISTENCE) ENTITY... 10! 2.3.2! SUMMARY... 15! 2.4! REVIEWING THE WEB FRONT END FOR THE BLOG APPLICATION... 15! 2.4.1! EXPLORING THE POSTBLOG SERVLET... 16! 2.4.2! EXPLORING THE VIEWBLOG SERVLET... 20! 2.4.3! EXPLORING THE CREATEBLOGPOST HTML... 22! 2.4.4! SUMMARY... 23! 2.5! CONFIGURING THE SERVER AND RUNNING THE APPLICATION... 24! 2.5.1! CONFIGURING THE DATA SOURCE TO CONNECT TO THE DATABASE... 24! 2.5.2! SUMMARY... 37! 2.6! SECURING AN APPLICATION... 37! 2.6.1! CONFIGURE THE LIBERTY SERVER FOR HTTPS SUPPORT... 37! 2.6.2! SETUP A BASIC USER REGISTRY TO TEST ROLE BASED ACCESS TO THE BLOG APPLICATION... 41! 2.6.3! SECURING THE BLOG APPLICATION RESOURCES... 43! 2.6.4! TESTING USER ACCESS TO SECURE RESOURCES IN THE BLOG APPLICATION... 51! 2.6.5! SUMMARY... 54! 2.7! PACKAGING THE LIBERTY PROFILE SERVER USING THE DEVELOPER TOOLS... 54! 2.7.1! PACKAGE THE LIBERTY SERVER, CONFIGURATION, AND APPLICATIONS... 55! 2.7.2! SUMMARY... 57! 2.8! CONCLUSION... 57! 2.9! APPENDIX A: REVIEW OF JPA PROJECT CODE AND PERSISTENCE XML CONFIGURATION... 58! 2.9.1! EXPLORING THE BLOGENTRY JPA CODE... 58! 2.9.2! EXPLORING THE PERSISTENCE XML IN THE JPA PROJECT... 60! 2.10! APPENDIX B: REVIEW OF POSTBLOG JAVA CODE IN THE BLOG PROJECT... 63! ! EXPLORING THE POSTBLOG SERVLET... 63! 2.11! APPENDIX C: REVIEW OF VIEWBLOG JAVA CODE IN THE BLOG PROJECT... 68! ! EXPLORING THE VIEWBLOG SERVLET... 68! 2.12! APPENDIX D: REVIEW OF CREATEBLOGPOST HTML CODE IN THE BLOG PROJECT... 72! ! EXPLORING THE CREATEBLOGPOST HTML... 72! Contents Page 3

60

61 Lab 2 Learn to Accelerate your web App development with the WebSphere Application Server Liberty profile In this lab, you are going to work with an existing Web application, and configure the Liberty Profile server and resources in order to run the application on the Liberty development server. The Blog Application requires a database. You will configure the data source needed to connect to the Derby database. The Blog application requires that some of its resource be accessed in a secure manner. You will setup the security of the Liberty server, and configure the user role mappings in order to provide role based access to the secure resources. The Blog application includes a JPA project (Java Persistence API) programming model for access to the backend database. You will add the necessary features to the Liberty profile to support the JPA programming model for Entity persistence. The Blog application also uses Java Servlets to interact with the persistence layer, and to display the resulting HTML content. You will configure the Liberty server to include the necessary features to support the Servlet programming model. In tis lab, you will be introduced to the debugger in order to learn how quickly you can get up and running in debug mode using the Liberty profile. Finally, you will test the Blog application and export the Liberty profiler resources to a compressed archive file. The compressed archive file includes the Liberty Server configuration and the Blog application. In subsequent labs, you will remotely deploy and manage the Blog application and Liberty Profile server using the remote management capabilities available for the Liberty profile. This lab uses a desktop virtual image. The completion of Lab 01 is required to begin this lab exercise. If you have not completed lab 1, you must compete the lab setup section of this lab before you begin the Lab 2 exercise. In this exercise, you will learn: How to create and deploy a simple static Web application using the IBM WebSphere Application Server V8.5 Liberty Profile Developer Tools How to create and deploy a simple blog Web application that makes use of Servlets, and persistence (using JPA Java persistence API) How to create and configure Shared Libraries How to configure JDBC drivers and data sources How to configure a Web application to access to certain Servlets and web pages require authentication How to configure the server to use SSL, to have a user registry to authenticate clients with, and how to define role mappings for a web Application How to package the Liberty server, configuration, and applications for deployment to other environments To run this lab, your workstation must meet the following requirements: Page 7

62 Approximately 8GB of storage available for the Windows XP virtual image Approximately 1.5 GB of memory free to run the developer workbench and the server The sample files for this lab, unzipped on your workstation; the instructions will refer to the location of the sample files using the <LAB_FILES> variable. Connectivity to the internet is NOT required 2.1 Lab Setup (Required only if you did not complete Lab 1) This lab requires the completion of Lab 01. If you have not completed lab 01, it is recommended that you do so be before attempting this lab. However, you may, instead, follow these simple instructions for importing the completed version of Lab 01. The Lab1_Completed.zip file includes the following: LibertyWork: This directory is the root directory for the labs exercises to be performed. eclipe: Eclipse installation (Indigo 3.7.2) wlp: Liberty Profile installation, configuration, and deployed apps. workspace: The eclipse workspace that includes the completed lab exercises. NOTE: The completion of Lab 01, or the unzipping of this completed Lab 01 archive is required in order to begin Lab 02. These steps required only if you did not complete Lab 01, and want to perform Lab Locate the completed lab 01 archive in X:\Student\CompletedLabs\Lab01\Lab1_Completed.zip 2. Unzip the file to C:\Student Page 8

63 This will unzip everything under the c:\student\libertywork folder which is where the lab exercises are performed. 3. When prompted to replace files, select Yes to All. 4. You are now ready to continue to the next section of Lab Blog Servlet Application In this section of the exercise, you are going to import the resources for a simple Blog application. You will explore the application components in order to become familiar with the Web application that uses JPA to implement a simple blog. The Blog will consist of JPA entity, two servlets and an html file. Here is the application model diagram and use case: 1. The user inputs a blog entry into an HTML form. 2. The form data is posted to the PostBlog Servlet, 3. The PostBlog Servlet uses the JPA persistence API to save the blog entry in the database via the JPA Entity. 4. Then the ViewBlog Servlet is invoked from the PostBlog Servlet 5. The ViewBlog Servlet uses the JPA persistence API to retrieve ALL the blog entries from the database and render them in HTML format. Page 9

64 Blog Application Model Diagram WebSphere Application Server - Liberty Profile V8.5 Web Container Input HTML form cresteblogpost.html JPA Persistence BlogEntry.java Post HTML form data Post Blog Content PostBlog.java Invoke Blog View View Blog Content ViewBlog.java Add a Blog Entry Retrieve Blog Entries Persist and retrieve blog records Derby DB The JPA (Java persistence) Entity Java Persistence API (JPA) provides a simple POJO based programming model for reading and writing data to a database. It is based around annotated POJOs called entities which are mapped into rows and tables in a relational database. In this section, we will import and review the JPA Entity used to persist the blog data to the Derby database provisioned on the virtual image. 1. Import the Blog JPA Project into the Workspace a. Launch Eclipse and ensure the selected Workpace is C:\Student\LibertyWork\workspace b. Select File! Import! General! Existing Projects into Workspace from the menu bar. Then click the Next button. Page 10

65 c. On the Import Projects dialog, click on the radio button labeled Select Archive File, and then click the Browse button to select the X:\Student\LabFiles\Lab02\BlogJPAProject_Archive_Import2.zip file. Then click Open. d. Select the JPA Project (JPA Project) from the archive. Then click the Finish button to import the archive file. 2. At this point, you will notice an error in the persistence.xml file. The error appears to be a bug in the Web Developer Tools in Eclipse. Page 11

66 a. To eliminate the error, simply edit the persistence.xml file in Eclipse. b. Add a space character or a blank line. c. Then save the file. The errors will go away. 3. Review the BlogEntry java code in the JPA Project. a. In the Enterprise Explorer, navigate to JPA Project! src! lab.blog.jpa! BlogEntry.java. b. Double click on BlogEntry.java to display the source code in the editor pane. You can take time here to review the code on your own. TIP: You can refer to Appendix A for a guided tour of the JPA project code and persistence configuration in the JPA Project application. Page 12

67 4. Review the persistence.xml in the JPA Project. You can take time here to review the persistence XML on your own. TIP: You can refer to Appendix A for a guided tour of the JPA Project code and persistence configuration in the JPA Project application. A JPA Persistence Unit is a logical grouping of user defined persistable classes with related settings. Persistence units are defined in a persistence.xml file, which has to be located in the META-INF directory in the classpath. a. In the Enterprise Explorer, navigate to JPA Project! src! META-INF! persistence.xml. b. Right click on the persistence.xml. Then select open with! Other from the context menu. Page 13

68 c. Then select Persistence XML Editor (WebSphere) from the selection list. Then click OK. d. The persistence.xml file will open in the WebSphere persistence editor. Select the Design Tab to view the content. e. Close the editor for the persistence.xml file. Page 14

69 2.2.2 Summary Congratulations you have successfully reviewed the JPA project and the required JPA Entity that is used in the Blog application to persist blog entries into the database. In this section you should have a high level understanding of the purpose and functionality of the JPA Entity and the associated persistence XML file. In this section, you reviewed: The JPA project The JPA entity The persistence.xml 2.3 Reviewing the Web Front End for the Blog Application In the next tasks, you will review and explore the Web Application project, two servlets and the html file that are part of the Blog application. One Servlet displays the blog posts and the other Servlet allows you to create new posts. The html file provides a form to submit the new blog post. 1. For your reference, here is the html input form. There is no action to take on this step. 2. For your reference, here is the view of the Blog postings. There is no action to take on this step. Page 15

70 2.3.1 Exploring the PostBlog Servlet The role of the PostBlog Servlet is to post the contents of the Blog entry and persist the data to the Derby database. The PostBlog Servlet is invoked by a simple HTML form that we will explore later in this lab. 1. Import the Blog Web Project into the Workspace a. Select File! Import! General! Existing Projects into Workspace from the menu bar. Then click the Next button. b. On the Import Projects dialog, click on the radio button labeled Select Archive File, and then click the Browse button to select the X:\Student\LabFiles\Lab02\BlogArchive_Import2.zip file. Then click Open. Page 16

71 2. c. Select the Blog (Blog) project from the archive. Then click the Finish button to import the archive file Add the JPA Project to the Blog application Deployment Assembly. The Blog application needs to use the JPA entity, so we need to make it visible at runtime. NOTE: Ideally, this could be included in the archive when the project is imported. However, at the time of this writing, there is an issue at runtime if the Deployment Assembly is pre-configured in the archive that is imported during the lab. a. b. c. d. Right mouse click on the Blog project. Select Properties from the context menu. Select Deployment Assembly from the Properties dialog. Then click the Add button. Select Project from the dialog window. Then click the Next button. Page 17

72 e. Select the JPA Project from the Projects dialog. And, then click the Finish button to complete the process. f. Click the OK button to complete the configuration changes. Page 18

73 3. Navigate to the PostBlog Servlet a. Switch to the Java EE perspective in eclipse. b. In the Project Explorer, navigate to Blog! Java Resources! src! lab.blog.web! PostBlog.java. c. Double click on PostBlog.java to display the source code in the editor pane. 4. Now we will do a quick review of the PostBlog.java. Page 19

74 You can take time here to review the code on your own. TIP: You can refer to Appendix B for a guided tour of the PostBlog Servlet code in the Blog application Exploring the ViewBlog Servlet You can take time here to review the code on your own. TIP: You can refer to Appendix C for a guided tour of the ViewBlog Servlet code in the Blog application. The role of the ViewBlog Servlet is to access the Blog database and query the Blog data. The Servlet generates a List of Blog entries in which the Servlet displays as HTML to render the output in a Web Browser. 1. Now we will do a quick review of the ViewBlog.java. First, navigate to the ViewBlog Servlet a. Switch to the Java EE perspective in eclipse. b. In the Enterprise Explorer, navigate to Blog! Java Resources! src! lab.blog.web! ViewBlog.java. Page 20

75 c. Double click on ViewBlog.java to display the source code in the editor pane. The ViewBlog.java is used to display the contents of the Blog as the user enters new blog entries. d. That s it for the Servlet review for the Blog application. All that is left is to review the html page with a simple form so a blog can be posted. In the next section, we will quickly review the content of the createblogpost.html that serves this purpose. Page 21

76 e. Close the ViewBlog java editor Exploring the createblogpost HTML You can take time here to review the code on your own. TIP: You can refer to Appendix D for a guided tour of the createblogpost html code in the Blog application. The role of the createblogpost HTML is to provide an input form for the user to enter a blog entry. The HTML form invokes the PostBlog Servlet which persists the blog entry to the database. 1. Now we will do a quick review of the createblogpost.html. First, navigate to the createblogpost.html file a. Switch to the Java EE perspective in eclipse. b. In the Enterprise Explorer, navigate to Blog! WebContent! createblogpost.html. c. Open the createblogpost.html using the Rich Page editor to display the source and design views of the html page. i. Right Mouse click on the createblogpost.html file. ii. Select Open With! Rich Page Editor from the context menu. And, then select the Source View. Page 22

77 d. The body of the HLML file contains a simple HTML form that contains input fields for the Blog Title and Blog Body. The form invokes the PostBlog Servlet when the Submit button is pressed. The HTML source for the createblogpost.html should look similar to the illustration below Summary In this section of the lab, you have explored the components of the Web Application that makes use of the JPA project to access content from a database. You explored the following aspects of the Web Project: Configuration of the Web project to place the output of another project in the WEB-INF/lib. How to create two Servlets that make use of JPA. How to configure a resource reference using annotations. How to create a simple HTML based form. Page 23

78 2.4 Configuring the server and running the application Congratulations your application review is now complete. Now the fun starts as you configure the server so it can connect to a database Configuring the Data Source to connect to the database 1. In this lab, a simple embedded derby database is required. In this step, you will make the derby.jar available as a shared library for the Liberty Profile Server where the Derby library will be available to the runtime environment. a. To do this, you will use eclipse to import the derby.jar file, from the Lab Files directory, into the Liberty Server shared resources folder. b. If not already started, Launch Eclipse and open the Java EE perspective. c. In the Enterprise Explorer view, Navigate to the shared resources folder in the Liberty Server configuration: WebSphere Application Server V8.5 Liberty Profile! shared! resources d. Create a new folder named derby. i. Right mouse click on the Resources folder. And then select New! Folder. Page 24

79 ii. Enter derby in the folder name field. And then click Finish to create the new folder. e. Import the derby.jar into the Derby shard resources folder. i. Right mouse click on the derby folder. And then select Import from the context menu. ii. On the Import dialog, select General! File System. And then click the Next button. iii. On the File System Import Dialog, use the Browse button, next to the From Directory field, and navigate to X:\Student\LabFiles\Lab02\. iv. Select derby.jar from the file list. Page 25

80 v. Click the Finish Button to import the derby.jar file. 2. The server does not start the necessary components required for database access unless configured to do so. This means the server is currently unable to access databases. To enable the database support the jdbc-4.0 feature needs to be configured. a. In Eclipse, Switch to the Java EE Perspective. This perspective includes the Servers view. b. Navigate to the Servers view and expand WebSphere Application Server V8.5 Liberty Profile at localhost [labserver] This item can be expanded to show a logical view of the configuration. However you need to edit rather than view the configuration. Page 26

81 c. Right click Server Configuration [server.xml] Liberty Server for Labs and click open. d. e. Select the Design tab on the configuration editor. Click the Feature Manager option from the Configuration Structure section. f. On the right side of the editor the details are viewable. To add a new feature click Add... to add a new feature into the list. Page 27

82 g. Click the down arrow and select jdbc-4.0. h. Save the file. If the server is still running after the earlier activity, switch to the console view to see the server report that it has responded to the new feature being configured. The server can now support database access; however no DataSources have been configured. 3. The next step is to configure the server so it can locate the database jar from the previous step. a. In the Design tab of the server configuration editor, click Server Configuration and click Add. b. Start typing Shared Library and when highlighted click OK. c. The shared library needs to have an id so it can be used elsewhere. In the Shared Library Details section in the id field enter derby. Page 28

83 d. In the Configuration Structure section, click Shared Library. And, then click Add. e. f. Click Fileset Reference. And then click the OK button. As the Base directory, enter ${shared.resource.dir}/derby Page 29

84 g. Save the configuration This has created a shared library that contains the derby jar. If you switch to the Source view it looks like this: <library id="derby"> <fileset dir="${shared.resource.dir}/derby"/> </library> Notice that the Design view shows all the values, but the Source view only includes values which are different from the defaults. 4. Back in the Design tab the next step is to define the JDBC driver. a. b. c. d. Click Server Configuration and click Add. Type JDBC Driver and when selected click OK. On the JDBC Driver Details enter derbydriver into the Id field. In the Shared Libraries field select derby from the pull down menu. Page 30

85 5. The next step is to define a DataSource In the persistence.xml, this was created using the resource ref JNDI name java:comp/env/jdbc/blogdb. By default, if no binding is provided, then the resource ref name of jdbc/blogdb is used to look up an object in JNDI. a. b. c. d. e. In the Design tab click Server Configuration and click Add. Type Data Source and when highlighted click OK. In the JNDI name field on the Data Source Details enter jdbc/blogdb In the JDBC driver field select derbydriver from the pull down menu. In the Type field, select javax.sql.connectionpooldatasource from the pull down menu. Page 31

86 6. Now, configure the derby specific properties: a. In the Configuration Structure click the DataSource and click Add. b. Select Properties for Derby Embedded. And, then click OK. c. In the Properties for Derby Embedded Details, choose false from the Create Database pull down menu. d. TIP: The Derby database required for the lab has already been created in the virtual image. Therefore, the create database flag should be set to false. In the Database name enter C:\Student\Derby\databases\blogDB This is the location of the pre-configured Derby Database on the Virtual Image. Page 32

87 e. Save the configuration. Looking in the source view you should see the following: <datasource jndiname="jdbc/blogdb" jdbcdriverref="derbydriver" type="javax.sql.connectionpooldatasource"> <properties.derby.embedded createdatabase="false" databasename="c:\student\derby\databases\blogdb"/> </datasource> This configures a derby Data Source in JNDI at jdbc/blogdb and specifies the location of the blogdb database. 7. Add the JPA-2.0 feature to the Liberty Server configuration. a. b. Select the Design tab on the configuration editor. Click the Feature Manager option from the Configuration Structure section. Page 33

88 c. On the right side of the editor the details are viewable. To add a new feature click Add... to add a new feature into the list. d. Click the down arrow and select jpa-2.0. e. Save the configuration file. Page 34

89 8. The application has now been created, and the server configured to support it. The next step is to run the application. a. If the server is running, Stop the Liberty Profile Server [labserver], using the STOP icon located on the Server view. b. Start the Liberty Profile Server. Use the Start icon in the Servers view to start the server if necessary. c. When the server starts, navigate to the createblogpost.html file in the Blog Web Project. d. e. f. g. Right click createblogpost.html file in the Enterprise Explorer view. Select RunAs > Run on Server. Select the WebSphere Application Server V8.5 Liberty Profile and click Finish. The application is be added to the server and the web page opened. TIP: If a 404 error is returned, refresh the web browser editor and it should come up. Page 35

90 9. Test the Blog application a. Enter a title and body into the blog and click the Submit Query button. The post is written to the database and a list of the posts shown. Page 36

91 b. To prove that the post was persisted, select the server in the servers view, right click on the server, and select restart. c. Then refresh the web browser to see the content remains unchanged Summary In this exercise you have learned how to: Configure a Liberty profile server. Add features to the server configuration to enable additional capabilities. Configure a library that contains a JDBC driver for database access. Configure a DataSource that can be used by applications, or JPA to persist data. Have a feature automatically added to the configuration based on the Liberty Profile s intelligence about features being used in the Blog application. This demonstrates how little configuration is required to access a database. 2.5 Securing an Application In this next section of the lab, you are going to secure access to the blog application. The Liberty Profile maintains security in a default install by ensuring that it only listens to requests from the local host. In this exercise you learn how to configure the server to listen for https requests, configure a basic user registry, and protect access so only authorized users can post to the blog Configure the Liberty server for https support The configuration of the server to enable https support is a two-step process. Page 37

92 Create self-signed SSL certificates Configuring the server to use these certificates for SSL 1. Create a self-signed certificate a. b. c. d. e. The securityutility command line tool needs to be used to create the SSL certificates: First, minimize the eclipse workbench Open a Windows command prompt Navigate to the directory the liberty profile was installed to: C:\Student\LibertyWork\wlp To create the certificate in the command prompt, type the following text as a single line: bin\securityutility createsslcertificate --server=labserver -- password=passw0rd This generates the keystore and places it in the server configuration directory. The utility also produces output of the XML snippet that can be copied into the server.xml to use the keystore. 2. Update the server configuration with the ssl feature and keystore a. Navigate to the server.xml file in the eclipse workbench. WebSphere Application Server V8.5 Liberty Profile! servers! labserver! server.xml Page 38

93 b. Copy the output generated by the securityutility command. And, then paste it into the server.xml Source tab (in the eclipse workbench). This configures the SSL feature in the runtime and tells the runtime the password to use when accessing the default key store. c. d. Save the configuration. Look in the console view to see the ssl-1.0 feature has been installed. It displays this message: [AUDIT ] CWWKG0016I: Starting server configuration update. [AUDIT ] CWWKG0017I: The server configuration was successfully updated in seconds. [AUDIT ] CWWKF0012I: The server installed the following features: [ssl-1.0]. Page 39

94 [AUDIT ] CWWKF0008I: Feature update completed in seconds. 3. Configure the Liberty Server to run the security related features. The appsecurity-1.0 feature is used to secure web resources. a. b. Select the Design tab on the configuration editor. Click the Feature Manager option from the Configuration Structure section. c. On the right side of the editor the details are viewable. To add a new feature click Add... to add a new feature into the list. d. Click the down arrow and select appsecurity-1.0. Page 40

95 e. Save the configuration file. The Liberty Profile Server is now configured to support http traffic on port In the next section, you will setup a basic user registry that is included with the Liberty profile. And, then, you will configure the Blog application to secure its web resources Setup a basic user registry to test role based access to the blog application 1. Configure a user registry. The Liberty Profile comes with a basic registry that can be configured in server.xml. In this lab, you will configure a basic user registry to test the security features in the Liberty profile. a. b. Switch to the Design tab and click Server Configuration. And, then click Add. Type Basic User Registry, and when highlighted click OK c. In the Basic User Registry Details provide a value for the Id by entering BasicRegistry. Page 41

96 2. Add a new user to the User Registry a. In the Configuration Structure, click Basic User Registry. And, then click Add. b. Click User. And, then click OK. c. d. e. In the User Details section, enter alice as the user name. Next to the User Password field, click the Edit button. Enter and confirm a password and click OK. ii. Use alicepw as the password iii. Remember the password as it is needed later in the lab Page 42

97 f. Save the server configuration. Congratulations a registry now exists in the server, and contains one user named alice Securing the blog application resources The next step is to configure security for the Blog application. This requires a web deployment descriptor. 1. Create a web descriptor file a. From the Enterprise Explorer view, Right click on the Blog Web Project b. Click Java EE Tools > Generate Deployment Descriptor Stub. Page 43

98 2. Define a new security Role in the web descriptor file. a. In the Project Explorer view, navigate to Blog > WebContent > WEB-INF and double click on the web.xml to view it in the Web Deployment Descriptor Editor. TIP: The web Deployment Descriptor editor is included with the Web Development Tools that is included with the Liberty Profile Tools eclipse plug-in. These tools were pre-installed on the virtual image, b. c. Select Web Application and click Add. Type Security Role and then click OK. Page 44

99 d. In the Role Name field enter author. 3. Define the security constraints for the protected resources a. Select Web Application and click Add. b. Type Security Constraint and when selected, click OK. i. Ignore any errors that are displayed. These will be fixed in the subsequent steps. Page 45

100 c. In the Details section, enter Post Constraint in the Display Name field. d. Next to the Role Name field, click Add and replace [New Item] with author. e. In Transport Guarantee select NONE from the pull down menu. Setting the Transport Guarantee to NONE means that SSL is not required to invoke the Blog application. However, as we will demonstrate, the Blog application will be available form the HTTP and HTTPS transports. In both cases, you will be prompted for user credentials to access the protected web resources in the application. Page 46

101 4. Define the Web resources to protect a. In the Overview section in the web.xml file, select Web Resource Collection under Web Application! Security Constraint (Post Constraint) b. Enter Post Resources in the Web Resource Name field. c. Next to URL Pattern field, click the Add button. And then enter /PostBlog. d. Next to URL Pattern field, click the Add button again. And then enter /createblogpost.html This ensures that requests to PostBlog and createblogpost.html are authenticated using basic http authentication. Page 47

102 e. Save the Web Deployment Descriptor. The errors in the Web Deployment Descriptor should now be resolved. The application is now configured to be secure, but the roles to user/group mappings have not yet been defined. 5. Define User / Group mappings a. Go to the Servers view. b. Double click on the Server Configuration to open the Server Configuration editor. c. Ensure you are in the Design mode by selecting the Design Tab on the Server Configuration editor. d. Find the Application:Blog element for the Blog application in the Configuration Structure in the Design tab. Page 48

103 e. f. g. Click on the Application: Blog element. And then click the Add button. Select Application Bindings from the menu. When highlighted, click the OK button. Click on Application Bindings. And then click the Add button. h. i. Select security-role from the list. When highlighted, click the OK button. In the Security role details section, provide the Security role name as author Page 49

104 This ties up with the role name in the web.xml defined earlier in the lab. j. Select the security-role from the Configuration Structure section. And then click the Add button. k. Select user from the list. When highlighted click the OK button. l. In the User name field, enter the user name you defined earlier. In the example this was alice. Page 50

105 The normal best practice would be to use groups for role mappings rather than users. Defining groups is performed basically the same as defining users. m. n. Save the configuration The application is now ready to run with security enabled Testing user access to secure resources in the blog application Now that the security features of the Liberty server is configured, you can now test the Blog application to ensure that the resources are protected as expected using SSL and role based access control to protected resources Stop and then restart the Liberty profile Server in order for the security settings to take effect. Close any Web browser windows in Eclipse that have the blog application loaded. Launch the createblogpost html file on the Liberty Server. a. Find createblogpost.html in the Enterprise Explorer view, located under the WebContent folder. b. Right click and select Run As > Run on server c. Run it on the Liberty profile server. Page 51

106 . d. e. g. The web browser comes up. You are then prompted for a user name and password. Enter the credentials as defined in the lab username: alice password: alicepw Click OK h. i. Finally, fill in the title and body and click Submit. This securely posts to the blog. 4. Close the Web browser windows in Eclipse that have the blog application loaded. Page 52

107 5. Launch the createblogpost html file on the Liberty Server. f. Find createblogpost.html in the Enterprise Explorer view, located under the WebContent folder. g. Right click and select Run As > Run on server h. Run it on the Liberty profile server. i. When the browser comes up, change the URL to use the HTTPS transport and SSL port; And, then click the GO browser. icon on the j. This re-executes the URL using the SSL transport. It prompts for you to accept the selfsigned certificate. This demonstrates that SSL is working and requests are redirected to the SSL port automatically. k. Click the Yes button to proceed. Page 53

108 j. Finally, fill in the title and body and click Submit. k. This securely posts to the blog using the SSL transport. Because you already provided the authorization credentials, you will not be prompted again for the userid and password Summary In this section of the lab, you have learned how to: Generate self-signed certificates Configure the Liberty Server to use the certificates. Update a Web application to protect servlets and html files so authentication and encryption are used when accessing them. Configure the role mappings for the Web application to enable a user to access the Web application. 2.6 Packaging the Liberty Profile Server using the Developer Tools Page 54

109 You can create a compressed file containing a server runtime environment, server configuration, and applications using the packaging wizard in the development environment. This is useful for packaging the Liberty profile and its application resources for a remote deployment using the WebSphere Job Manager Package the Liberty Server, configuration, and applications 1. In the Servers view, stop the Liberty profile Server using the Stop Server icon. 2. Package the Server, configuration, and applications. a. From the Servers view, Right-Click on your Liberty Profile. And, then select Utilities! Package Server. From the context menu. b. Package the server into a distributable archive i. From the Package Server dialog, enter c:\student\libertywork\output\lab2package.zip for the Archive location. Page 55

110 ii. Select All server content for the Include pull down menu, iii. Click the Finish button to create the package. This will result in ALL of the server configuration and applications to be included in the archive file that will be created. c. You can explore the compressed file that was generated. You will notice that the package includes the server, server configuration, and the applications deployed to the server. The packaged distributable archive is suitable to be deployed to a remote Liberty server using the WebSphere Job Manager. You will explore these capabilities in a subsequent lab. Page 56

111 2.6.2 Summary In this section of the lab, you have learned how to: Package a Liberty Server and its resources using the developer tools. This capability is also available from the Liberty Profile command line using the server package command and its associated command line options. The equivalent command is: server package labserver archive=c:\student\outputlab2package 2.7 Conclusion Congratulations on completing this lab. In it you have learned how to: Work with a JPA project Work with JPA entities Work with a persistence.xml Work with a Web project Configure the Web project to place the output of another project in the WEB-INF/lib Associate the Web project with a target runtime Use Servlets that make use of JPA Configure a resource reference using annotations Create a simple HTML based form Page 57

112 Configure a Liberty profile server Add a feature to the server configuration to enable additional capabilities Configure a library that contains a JDBC driver for database access Configure a DataSource that can be used by applications, or JPA to persist data Generate self-signed certificates and configured the server to use them Update a Web application to protect servlets and html files so authentication and encryption are used when accessing them Configure the role mappings for the Web application to enable a user to access the Web application Package the Liberty Profile resources for remote deployment to integration test or production environments If you are interested in learning more then check out the WAS Dev community at wasdev.net/. This is a new developer focused community which is supported by the development team responsible for the Liberty profile and the developer tools. The community website contains: Instructions on how to get the latest developer tools for all platforms. The latest version of the runtime. Videos on how to use various features of the Liberty profile. Podcasts about the early access program. Samples to help understand how to use the Liberty profile. Articles on the Liberty profile and developer tools. A forum to request and provide help when using the Liberty profile and the developer tools. Ability to request enhancements. =================== END OF LAB 02 ==================== 2.8 Appendix A: Review of JPA Project code and persistence XML configuration Exploring the BlogEntry JPA code 1. Here, you can review the BlogEntry code in the JPA Project. a. The BlogEntry is a POJO that contains the getter / setter methods used to access and update the fields defined in the BlogEntry entity. b. The BlogEntry contains the following fields that are used to create a blog entry in the database, which will be persisted into the Derby database. Page 58

113 private int ID; private String title; private String body; private Date postdate = new Date(); i. The id is the unique identifier for the blog entry. ii. The title is a title for the blog entry, as entered by the user. iii. The body is the text of the blog as entered by the user. iv. The postdate sets the current data and timestamp for the blog entry, when it was posted by the user. c. The Id field is a generated value that uniquely identifies the blog entry in the database. We would like to get the JPA runtime to generate a value for the id field. Remember this is the database primary key so needs to be unique. This is accomplished using the following annotation to the public int getid() { return this.id; } i. annotation defines the Id field as the identifier ii. annotation signifies the value is to be generated using the generation type specified. d. The remainder of the Java code represents simple getter / setter methods for accessing and updating the title, body, and date fields on the Blog Entry. public String gettitle() { return this.title; } public void settitle(string title) { this.title = title; } public String getbody() { return this.body; } public void setbody(string body) { this.body = body; } public Date getpostdate() { return this.postdate; } public void setpostdate(date postdate) { this.postdate = postdate; Page 59

114 } e. Close the BlogEntry editor Exploring the persistence XML in the JPA Project 1. Open the persistence.xml for review. A JPA Persistence Unit is a logical grouping of user defined persistable classes with related settings. Persistence units are defined in a persistence.xml file, which has to be located in the META-INF directory in the classpath. a. In the Enterprise Explorer, navigate to JPA Project! src! META-INF! persistence.xml. b. Right click on the persistence.xml. Then select open with! Other from the context menu. Page 60

115 c. Then select Persistence XML Editor (WebSphere) from the selection list. Then click OK. d. The persistence.xml file will open in the WebSphere persistence editor. Select the Design Tab to view the content. Page 61

116 e. Click on Persistence Unit (blog) under the Overview section to view the details of the persistence unit configuration in the persistence.xml file. i. Here you see the data source definition that is required to connect to the database. This must match the data source definition that is defined in the Liberty Profile server configuration. We have not yet defined the server resources. That is covered in a subsequent section of the lab. f. Click the + sign next to the Persistence Unit (blog) entry to view the details of the persistence class. Page 62

117 i. Here you see the set of classes that are managed by the persistence unit. In this case, the lab.blog.jpa.blogentry class that we just reviewed is defined. g. You may click the Source tab and explore the complete source for the persistence.xml file. h. Close the editor for the persistence.xml file. 2.9 Appendix B: Review of PostBlog java code in the Blog project Exploring the PostBlog Servlet Page 63

118 1. Navigate to the PostBlog Servlet a. Switch to the Java EE perspective in eclipse. b. In the Project Explorer, navigate to Blog! Java Resources! src! lab.blog.web! PostBlog.java. c. Double click on PostBlog.java to display the source code in the editor pane. 2. Now we will do a quick review of the PostBlog.java. The function of the PostBlog.java is to perform an HTTP Post of the form data to persist the blog content to the database. a. The first thing we did is to define a resource reference to lookup the JDBC DataSource. This is done either using annotations or via the web.xml file. In this lab, the annotation based approach was used. i. The annotation is used to define the resource definition to our Blog data source. Page 64

119 This defines a resource reference for a DataSource that is available in java:comp/env/jdbc/blogdb. This is the name defined in the persistence.xml we explored earlier in the JPA PAroject. b. Since this servlet makes use of JPA, you need to get an EntityManagerFactory injected. The EntityManager is used to create, update, and persist entities into the database. i. The EntityManager belongs to the javax.persistence.* package. c. Now we will take a quick look at the method body of the dopost method. The first thing we do is extract the information from the request. i. This is done by adding the highlighted code into the dopost method: This code extracts the title and body into String variables. d. Once we have the data, we populate the entity. This is quite simple since the id and postdate fields are automatically generated. The entity can be created like a simple POJO, using the setter methods defined on the BlogEntry JPA class. Page 65

120 e. Now that the entity is populated, the next step is creating an EntityManager instance from the EntityManagerFactory that is injected. The EntityManager is used to create, update, and persist entities into the database. f. Updates to the entity manager, such as creating a new entity, need to be done under a transaction. You can either use a 2 phase commit transaction using the JTA support, or you can use a transaction local to the EntityManager. This lab uses the latter option. In the persistence.xml you earlier set the Transaction Type to RESOURCE_LOCAL. To use this, we created an entity manager local transaction object. Page 66

121 g. Now that we have transaction, we can begin the transaction, persist the entity, and commit the transaction, as illustrated below. h. The entity has now been persisted to the database. The last thing to do is keep the runtime tidy and close the EntityManager. Page 67

122 i. At this point the servlet is done, but nothing has been sent back to the client. Rather than return nothing the client should be redirected to some content. In this case displaying the blog entries would seem appropriate. The ViewBlog Servlet is used to render the blog content to the user. So, we put in a simple redirect to point to the ViewBlog Servlet to display the output. j. Close the PostBlog editor 2.10 Appendix C: Review of ViewBlog java code in the Blog project Exploring the ViewBlog Servlet The role of the ViewBlog Servlet is to access the Blog database and query the Blog data. The Servlet generates a List of Blog entries in which the Servlet displays as HTML to render the output in a Web Browser. 1. Now we will do a quick review of the ViewBlog.java. First, navigate to the ViewBlog Servlet a. Switch to the Java EE perspective in eclipse. Page 68

123 b. In the Enterprise Explorer, navigate to Blog! Java Resources! src! lab.blog.web! ViewBlog.java. c. Double click on ViewBlog.java to display the source code in the editor pane. The ViewBlog.java is used to display the contents of the Blog as the user enters new blog entries. d. Like the PostBlog servlet, this Servlet makes use of JPA. So we added the same code to get an EntityManagerFactory. Page 69

124 e. The client needs some HTML so it can render the output in a web browser. To do this, we developed the following code in the doget method to output the HTML to the web browser. f. Next, we create and start reading the entity. To do this, we use an EntityManager instance, and add it to the body of the HTML. This is not exactly a best practice, but it serves our purpose to display output to a web browser. EntityManager em = blog.createentitymanager(); g. To access the blog posts you need to query the database for all entities. This is done by passing a query string to the entity manager. Query q = em.createquery("select b FROM BlogEntry b ORDER BY b.postdate DESC"); This requests all BlogEntry entities in the database, in descending order based on the post date. Since this is a simple application, the lab does not filter the list of results to be returned. It just returns all of them. In reality only a subset would be requested. h. Next, we execute the query and assign place the results into a List of BlogEntry objects. List<BlogEntry> entries = q.getresultlist(); i. At this point, the doget method should look similar to the illustration below. Page 70

125 j. Now that we have a List of BlogEntry objects, we need to loop through all the entries writing them to the client with some html markup. For this, we use a for loop. k. The last thing is to write the close body and html tags to the client. out.println("</body>"); out.println("</html>"); Page 71

126 The doget method is now complete, and should look similar to the illustration below. l. The Servlets have now been created. All that is left is to create an html page with a simple a simple form so a blog can be posted. m. In the next section, we will quickly review the content of the createblogpost.html that serves this purpose. Close the ViewBlog java editor 2.11 Appendix D: Review of createblogpost html code in the Blog project Exploring the createblogpost HTML Page 72

127 The role of the createblogpost HTML is to provide an input form for the user to enter a blog entry. The HTML form invokes the PostBlog Servlet which persists the blog entry to the database. 1. Now we will do a quick review of the createblogpost.html. First, navigate to the createblogpost.html file a. Switch to the Java EE perspective in eclipse. b. In the Enterprise Explorer, navigate to Blog! WebContent! createblogpost.html. c. Open the createblogpost.html using the Rich Page editor to display the source and design views of the html page. i. Right Mouse click on the createblogpost.html file. ii. Select Open With! Rich Page Editor from the context menu. And, then select the Source View. d. The body of the HLML file contains a simple HTML form that contains input fields for the Blog Title and Blog Body. The form invokes the PostBlog Servlet when the Submit button is pressed. The HTML source for the createblogpost.html should look similar to the illustration below Page 73

128 The split view of the createblogpost.html file should look like this: Page 74

129 e. Close the createblogpost.html editor Page 75

130 L03: WebSphere Application Server V8.5 Installation and Liberty Profile Management Lab Exercise 3

131

132 Contents Contents' LAB 3- INSTALLATION OF WEBSPHERE APPLICATION SERVER AND LIBERTY PROFILE MANAGEMENT... 9! LAB REQUIREMENTS... 9! WHAT YOU SHOULD BE ABLE TO DO... 9! EXERCISE INSTRUCTIONS... 9! PART 1: INSTALLATION OF WEBSPHERE APPLICATION SERVER AND THE WEBSPHERE APPLICATION SERVER LIBERTY PROFILE ! START THE VIRTUAL MACHINE AND MOUNT THE WAS V8.5 ISO CD IMAGE ! INSTALL WEBSPHERE APPLICATION SERVER V8.5 USING INSTALLATION MANAGER... 11! PART 2: LIBERTY PROFILE REMOTE INSTALLATION AND MANAGEMENT USING THE JOB MANAGER ! CREATE A JOB MANAGER PROFILE... 20! LOGIN TO THE JOB MANAGER CONSOLE AND SETUP THE LIBERTY WORKING DIRECTORY VARIABLE... 21! CREATE A NEW TARGET TO HOSTB ! UPDATE THE LIBERTY SERVER CONFIGURATION FILE (SERVER.XML) FOR HOSTB ! USE THE JOB MANAGEWR TO INSTALL LIBERTY RESOURCES ON THE REMOTE HOST (HOSTB)... 26! USE THE JOB MANAGER TO START THE LIBERTY PROFILE SERVER ON HOSTB ! INVOKE THE BLOG APPLICATION ON THE REMOTE LIBERTY PROFILE SERVER ! GENERATE THE HTTP SERVER PLUG-IN CONFIGURATION FILE FOR THE REMOTE LIBERTY PROFILE SERVER... 30! APPENDIX A - USING THE PACKAGING UTILITY TO CREATE THE INSTALLATION IMAGES... 34! APPENDIX B - SERVER.XML FOR THE LAB WITH CHANGES... 35! Page 7

133 Installation of WebSphere Application Server V8.5 and Liberty Profile Management Page 8

134 Lab 3- Installation of WebSphere Application Server and Liberty Profile Management The objective of this lab is to provide you with an understanding of how to install WebSphere Application Server Network Deployment, then to create a WebSphere Application Server Network Deployment Job Manager Profile. Then turn use the Job Manager to remotely install and manage a WebSphere Application Server Liberty Profile. The scenario simulated in this lab is creation of a production environment for management and deployment of an application running on a Liberty profile application server fronted by an HTTP server. This lab is provided AS-IS, with no formal IBM support. Lab requirements This lab requires uses two VMware virtual machines, hosta and hostb, as well as an iso image that was created for this lab; WAS_ND_v85.iso What you should be able to do At the end of this lab you should be able to Install WebSphere Application Serve Network Deployment using IBM Installation Manager Create a WAS-ND Job Manager profile Configure an existing Liberty Profile for remote deployment and perform a remote install Remotely manage the Liberty Profile. Exercise instructions Some instructions in this lab may be Windows operating-system specific. If you plan on running the lab on an operating-system other than Windows, you will need to execute the appropriate commands, and use appropriate files (.sh vs..bat) for your operating system. The directory locations are specified in the lab instructions using symbolic references, as follows: Reference variable Windows location Linux or UNIX locations <WAS_HOME> C:\IBM\WebSphere\AppServer /usr/websphere/appserver Page 9

135 /opt/websphere/appserver <PROFILE_HOME> C:\IBM\WebSphere\AppServer\profiles\AppSrv01 /usr/websphere/appserver/profiles/appsr v01 /opt/websphere/appserver/profiles/appsr v01 <RAD_HOME> C:\Program Files\IBM\SDP /opt/ibm/sdp <LAB_FILES> C:\Labfiles85 /tmp/labfiles85 <TEMP> C:\temp /tmp Note for Windows users: When directory locations are passed as parameters to a Java program such as EJBdeploy or wsadmin, it is necessary to replace the backslashes with forward slashes to follow the Java convention. For example, C:\Labfiles85\ would be replaced by C:/Labfiles85/ Page 10

136 Part 1: Installation of WebSphere Application Server and the WebSphere Application Server Liberty Profile. Start the Virtual Machine and mount the WAS v8.5 iso CD image. 1. In order to insure that you have a recovery point, take a VM snapshot for both hosta and hostb and provide a meaningful name such as Lab 3 Starting Image. Refer to Common Tasks if you need information on how to take a VMware snapshot. 2. Start the hosta Virtual Machine image a. Log in using Administrator with the password passw0rd (numeric zero) 3. Mount the WASND_v85.iso image on the CD/DVD device for the host A virtual machine, refer to Common Tasks in the L0.5_BeforeYouBegin document, if you need detailed instructions on how to do so. a. Close the window that automatically opens when the CD/DVD mounts Install WebSphere Application Server V8.5 using Installation Manager 4. Using Windows Explorer (shortcut is on the desktop) navigate to C:\Program Files\IBM\Installation Manager\eclipse a. Highlight one of the folders in the eclipse directory and click the right mouse button and click Command Window as shown below (this will open a Windows Command Shell) Page 11

137 b. Enter IBMIM.exe -skipinstall "C:\temp\imRegistry" -keyring C:\IM\im.keyring -record C:\temp\wasnd_response_file.xml on a single line as shown below and hit the Enter key, this will launch the Installation Manager in record mode and create a response file to be used for the actual command line (silent) install. c. Validate the you are in record mode by looking for Recording on the top of the Installation Manager d. From the upper left corner of the Installation Manager select File -> Preferences (as shown below) e. Click Add Repository then click Browse Page 12

138 f. Browse to the repository.config file on the CD/DVD drive. And then click Open. g. h. i. ii. Click OK As shown below, ensure that: the repository you just selected is checked Search service repositories.. is not checked i. Then, click Apply and click OK Page 13

139 j. Click Install k. Select Version as shown below and click Next Page 14

140 l. Six recommended ifixes are part of the installation image as depicted below, ensure that they are all selected and click Next m. Select I accept the terms in the license agreement and click Next n. On the next screen, accept the Default Shared Resources directory location shown below and click Next Page 15

141 o. Override the default Installation Directory and enter C:\IBM\WebSphere\AppServer as shown below then click Next p. Select English and click Next q. Select the Features shown below WebSphere Application Server Full Profile and ND and WebSphere Application Server Liberty Profile then click Next r. Validate the list of packages shown below, and click Install Page 16

142 s. The install will end very quickly because you are only recording the responses, not actually installing. When the packages are installed panel as shown below is displayed, click Finish t. Exit the Installation Manager Page 17

143 u. Now that you have created a response file to be used for a silent (command line) install,in the command window that you launched the Installation Manager GIU in record mode from, enter the command cd tools as shown below v. The IBM Installation Manager command line implementation is imcl. To perform the install, enter the following command on a single line: imcl input C:\temp\wasnd_response_file.xml -preferences com.ibm.cic.common.core.preferences.preservedownloadedartifacts=false -acceptlicense as shown below. This will use the response file, via the input parameter, that you just created to perform a silent install. The preservedownloadedartifacts=false parameter is used to save disk space and discards the install binaries that were downloaded to the local machine once the install is created (as opposed to saving a copy of the binaries on the local machine which is the default. The acceptlicense parameter, accepts the product license. As the install will take minutes, you might want to stretch your legs. w. When the installation is complete you should see the screen below indicating the WAS V8.5 and the ifixes were all installed Page 18

144 x. Type exit and press enter to close the command window Page 19

145 Part 2: Liberty Profile Remote Installation and Management Using the Job Manager. Create a Job Manager Profile 1. Using the Windows Explorer shortcut on the desktop navigate to C:\IBM\WebSphere\AppServer\bin and highlight a folder, then use the right mouse button to open a command window (as you did in the first section of the lab) 2. In the command window enter the command shown below (in a single line) The manageprofiles command will create a Job Manger profile in the WebSphere environment. manageprofiles.bat -create -profilename JobMgr001 -templatepath C:\IBM\WebSphere\AppServer\profileTemplates\management -servertype JOB_MANAGER - enableadminsecurity true -adminusername jobadmin -adminpassword j0badmin 3. Confirm that the profile is created with an INSTCONFSUCCESS message as shown below. Page 20

146 4. In the command window, enter cd..\profiles\jobmgr001\bin to change to the bin directory for the Job Manager profile you just created. 5. Enter startserver.bat jobmgr to start the Job Manager a. Wait until the Job Manager is started which is indicated with an ADMU3000I message as shown below ADMU3000I: Server jobmgr open for e-business; process id is xxxx Login to the Job Manager console and setup the Liberty Working Directory variable The Job Manager needs to have the WLP_WORKING_DIR environment variable set, which defines the directory that Liberty will be installed to on the remote host(s) Open a browser and enter the URL If you receive a secure connection failed error and need help in resolving it refer to the Common Tasks section for more information. Log into the Job Manager console using jobadmin/j0badmin (as specified when you created the profile) 8. If you receive a message to remember the password, good security practice to specify Never for This Site (or any site) 9. Once the console is open navigate to Environment -> WebSphere Variables (as shown below) Page 21

147 10. Select a scope of Cell= HOSTAJobMgrCell01 as shown below and the click New 11. Create a variable name, WLP_WORKING_DIR with a value of C:\IBM\WebSphere as shown below, then click OK ( this is the directory that Liberty will be installed to on the remote host(s). 12. Save your changes Page 22

148 NOTE: The Job functions in the Job Manager and Deployment Manage use the Remote Execution and Access (RXA) component in WebSphere Application Server. Many of the configuration steps needed for RXA have already been performed on these OS images. Before using the Job Manager or Deployment Manager for remote job submission in your environment you should refer to the WAS Information Center article Requirements for using Remote Exaction and Access to insure that your environment is correctly configured. 13. If you have not already done so, start the hostb VMware image Create a new Target to hostb. The Job Manager does not require an agent to be running in the remote host to invoke commands and execute light touch administration of the Liberty Server, such as installations, start server, and stop server. However, you must configure targets to the remote hosts where the remote Liberty severs will be installed. You will perform this task now. 14. On hosta, Navigate to Jobs -> Targets in the console as shown below 15. Click New Host as shown below Page 23

149 16. As shown below a. Enter hostb for the Host Name b. Select Windows for the Operating System c. Enter Administrator for the Administrative User d. Enter passw0rd for the password 17. Click OK and confirm that the new target for hostb is created (as shown below) Page 24

150 18. You can now log out of the Job Manager console on hosta. Update the Liberty Server configuration file (server.xml) for hostb. The Liberty server configuration for the Blog application in lab #2 was configured for local access. In order to configure the Liberty server for remote management and to use an http server plug-in, minor changes to the erver.xml is required prior to deployment of the Liberty server to the remote host. 19. Copy the Lab2Package.zip that you created at the end of Lab 2 (recall the lab instructed you to place it in c:\student\libertywork\output ) to the C:\temp directory 20. To prepare the application and Liberty server for deployment, some changes need to be made to the configuration of the server in the Lab2Package.zip archive a. Unzip the copy of Lab2Package.zip in C:\temp b. Navigate to the directory wlp\usr\servers\labserver in the unzipped/expanded application archive on your laptop. c. d. Make a copy of the server.xml file (e.g. server.xml.copy) Open the server.xml file in an editor (notepad or wordpad) e. Add <feature>restconnector-1.0</feature> to the file in the feature manager stanza (just below the localconnector-1.0 feature) f. Add <feature>serverstatus-1.0</feature> to the file in the feature manager stanza (just below the restconnector-1.0 feature) g. Update the httpendpoint stanza by changing the host parameter from localhost to hostb as shown below <httpendpoint host="hostb" httpport="9580" httpsport="9443" id="defaulthttpendpoint"/> h. Add <pluginconfiguration webserverport="80" webserversecureport="443"/> to the file (just below the httpendpoint feature). While these are the default values, adding them explicitly is good management practice i. Using the wlp securityutility, encode wlpadm1n (note the numeric 1) as the password for the wlpadmin user. The securityutility command is located in the C:\IBM\WebSphere\AppServer\wlp\bin directory. i. Navigate to the directory: C:\IBM\WebSphere\AppServer\wlp\bin Page 25

151 ii. Run the command: securityutility encode wlpadm1n The command will generate output of the encrypted password as shown below. {xor}kdmvpjsybje= j. Add <user&name="wlpadmin"&password="{xor}kdmvpjsybje="&/>to the basicregistry stanza, just below the entry for alice. k. Add the following stanza to the server.xml file, after the basicregistry stanza, as shown below. <administratorrole> <user>wlpadmin</user> </administratorrole> l. Save the file (for reference, a copy of the modified server.xml is in the appendix at the end Note: Due to defect in the code, the Liberty Profile administrative security constraints and role configured in the server.xml are not consistently enforced. As a result you may or may not be prompted for the wlpadmin user name and password further along in this lab, even though a prompt is the expected behavior. This defect is scheduled to be corrected in FixPack 1 (WAS V ) m. Rezip the archive and name the archive Lab2Package_v1.zip by highlighting the wlp directory then using the right mouse button select Send to -> Compressed (zipped) Folder n. Copy the archive to C:\temp on hosta Use the Job Manager to install Liberty resources on the remote host (hostb) 21. Log into the Job Manager console with the user jobadmin and password j0badmin and navigate to Jobs -> Submit Page 26

152 22. Select a Job Type of Install Liberty Profile Resources and click Next 23. a. b. c. Enter hostb for the Target names, and click Add, which will add hostb as shown below, Enter Administrator and passw0rd for the User name and password as shown below Click Next 24. Browse to the Lab Archive file in the C:\temp directory, Select it and click OK 25. Click Next Page 27

153 26. Accept the defaults on the Schedule the Job panel and click Next 27. Review the Job Parameters as shown below and click Finish to submit the job 28. This will bring up the Job Status dialog as shown below. Be patient as you wait for the job to execute!! n 29. A successfully completed job is illustrated below: Page 28

154 Use the Job Manager to start the Liberty Profile Server on hostb. 30. Now return to the Jobs panel and create and submit a job to start the Liberty server that was just installed a. Select Job Type of Start Liberty Profile Server and click Next b. Add hostb to the target list and enter Administrator and passw0rd as you did for the installation job., then click next c. Find the server runtime/wlp/liberty_server/labserver as shown below, then click Next Page 29 d. Accept the default job schedule parameters and click Next

155 e. Review the job parameters and click Finish 31. As before when installing the Liberty package, a successful job execution will be indicated as shown below. Invoke the Blog application on the remote Liberty Profile Server. 32. Open a web browser on hostb and enter the URL As before, if you receive a secure connection failed error and need help in resolving it refer to the Common Tasks section for more information. 34. When prompted for credentials, enter alice for the user name with the password: alicepw Generate the http server plug-in configuration file for the remote Liberty Profile server 35. Generate a plugin-cfg.xml on hostb a. Using the Windows Explorer on the hostb desktop, navigate to C:\Program Files\IBM\Java60\bin and open a Command Window (highlighting a folder inside that directory as you have done previously) b. Enter the command jconsole as shown below c. d. As shown below Select local process Page 30

156 e. Highlight the labserver f. Enter wlpadmin for the username and wlpadm1n for the password g. Click Connect JConsole is a JMX compliant graphical monitoring and management tool that connects to a running Java Virtual Machine (JVM)both on a local or remote machine. JConsole comes as part of Java Development Kit (JDK). 36. Generate the http server plugin configuration file, using the WebSphere MBeans, as shown below a. Click on the Mbeans tab b. c. d. e. Expand the WebSphere Mbeans Highlight the generateplugincfg Mbean Click generate (in the right hand panel) You should receive a Method successfully invoked popup Page 31

157 Note: The HTTP server and the Liberty Profile application server are located on the same machine (VMware image in this case). This was done to facilitate demonstration of remote Liberty Profile management in a lab exercise context and should not be considered a recommendation to place any application server in a DMZ on the same machine as the HTTP server. 37. The HTTP server and plugin has already been configured to point to the plugin-cfg.xml which was generated and placed in the C:\IBM\WebSphere\wlp\usr\servers\labServer directory. So. all you need to do is to start the IBM HTTP Server by opening a command window C:\IBM\HTTPServer\bin and then entering apache as shown below 38. Open a browser on hostb and enter the URL Page 32

158 End of Lab 3 Congratulations! You have successfully performed a silent install of WebSphere Application Server - ND using a response file, created a WebSphere Application Server-ND Job Manager, used the Job Manager to install a Liberty Profile server and application to a remote server and performed a remote start of the Liberty Profile server. Additionally you have also covered some production aspects of Liberty configuration management by adding features to the Liberty Profile server server.xml file. Page 33

159 Appendix A - Using the Packaging Utility to create the installation images C:\Program Files\IBM\Packaging Utility>pucl listavailablepackages repositories D:\STEWInstalls\ND com.ibm.websphere.nd.v85_ _1108 C:\Program Files\IBM\Packaging Utility>pucl.exe copy com.ibm.websphere.nd.v85_ _1108 -repositories D:\STEWInstalls\ND,D:\STEWInstalls\WASv85iFixes\ ws-was-ifpm62795.zip,D:\STEWInstalls\WASv85iFixes\ ws-was-ifpm zip,D:\STEWInstalls\WASv85iFixes\ ws-was-ifpm63827.zip,D:\STEWInstalls \WASv85iFixes\ ws-wasnd-distexceptibmi-ifpm64890.zip,D:\STEWInstalls\WASv 85iFixes\ ws-wasprod-ifpm64186.zip,D:\STEWInstalls\WASv85iFixes\ w s-wasprod-multios-ifpm63479.zip -platform os=win32 -target d:\stewinstalls\pu_ Image -prompt -acceptlicense The operation completed successfully. C:\Program Files\IBM\Packaging Utility>pucl listavailablepackages repositories D:\STEWInstalls\Java7 com.ibm.websphere.ibmjava.v70_ _1539 C:\Program Files\IBM\Packaging Utility>pucl.exe copy com.ibm.websphere.ibmjava.v70_ _1539 -repositories D:\StewInstalls\Java7 -target D:\STEWInstalls\Java7\PU_Win32 -platform os=win32 -prompt -acceptlicense The operation completed successfully. Page 34

160 Appendix B - server.xml for the lab with changes <server description="liberty server for labs"> <!-- Enable features --> <featuremanager> <feature>jsp-2.2</feature> <feature>servlet-3.0</feature> <feature>localconnector-1.0</feature> <feature>restconnector-1.0</feature> <feature>serverstatus-1.0</feature> <feature>jdbc-4.0</feature> <feature>jpa-2.0</feature> <feature>appsecurity-1.0</feature> </featuremanager> <httpendpoint host="hostb" httpport="9580" httpsport="9443" id="defaulthttpendpoint"/> <pluginconfiguration webserverport="80" webserversecureport="443"/> <applicationmonitor updatetrigger="mbean"/> <application id="sample1" location="sample1.war" name="sample1" type="war"/> <logging consoleloglevel="info" tracespecification="*=info=enabled "/> <library id="derby"> <fileset dir="${shared.resource.dir}/derby"/> </library> <jdbcdriver id="derbydriver" libraryref="derby"/> <datasource jdbcdriverref="derbydriver" jndiname="jdbc/blogdb" type="javax.sql.connectionpooldatasource"> <properties.derby.embedded createdatabase="false" databasename="c:\student\derby\databases\blogdb"/> </datasource> <application id="blog" location="blog.war" name="blog" type="war"> <application-bnd> <security-role name="author"> <user name="alice" /> </security-role> </application-bnd> </application> <featuremanager> <feature>ssl-1.0</feature> </featuremanager> <keystore id="defaultkeystore" password="{xor}lz4slchvlts=" /> Page 35

161 <administratorrole> <user>wlpadmin</user> </administratorrole> <basicregistry id="basicregistry"> <user password="{xor}pjm2pdopca==" name="alice" /> <user password="{xor}kdmvpjsybje=" name="wlpadmin" /> </basicregistry> </server> Page 36

162 Page 37

163 Lab 04: WebSphere Application Server V8.5 Operations and Control Lab Exercise 4

164 Contents' WEBSPHERE APPLICATION SERVER V8.5 OPERATIONS AND CONTROL... 7! LAB REQUIREMENTS... 7! WHAT YOU SHOULD BE ABLE TO DO... 7! EXERCISE INSTRUCTIONS... 7! PART 1: JAVA 7 SE INSTALLATION AND CONFIGURATION OF WEBSPHERE APPLICATION SERVER TO USE JAVA 7 SE... 9! START THE VIRTUAL MACHINE AND MOUNT THE JAVA 7 ISO CD IMAGE.... 9! INSTALL JAVA 7 USING INSTALLATION MANAGER... 9! CREATE A STAND-ALONE SERVER PROFILE... 10! DISPLAY AND SWITCH THE JAVA SE VERSION USED FOR THE WEBSPHERE APPLICATION SERVER... 11! PART 2: TRACKING ADMINISTRATIVE CONFIGURATION CHANGES... 14! ENABLE AUTOMATIC TRACKING REPOSITORY CHECKPOINTS... 14! UPDATE THE JAVA HEAP SIZE ON THE SERVER, WHICH WILL TRIGGER AN AUTOMATIC REPOSITORY CHECKPOINT ! COMPARE THE CONFIGURATION CHANGES FROM THE EXTRACTED DATA GENERATED BY THE AUTOMATIC REPOSITORY CHECKPOINT ! PART 3: MEMORY LEAK DETECTION AND CORRECTION... 22! INSTALL A TEST APPLICATION THAT WILL PRODUCE A JAVA MEMORY LEAK ! START THE MEMORY LEAK APPLICATION... 25! ENABLE THE LEAK DETECTION FEATURE USING THE WSADMIN COMMANDS ! APPENDIX A MEMORY LEAK DETECTION PERSISTENT CONFIGURATION... 33! Page 2

165 WebSphere Application Server V8.5 Operations and Control The objective of this lab is to demonstrate some of the new operations and control features in WebSphere Application Server V8.5. This lab is provided AS-IS, with no formal IBM support. Lab requirements This lab requires uses one VMware virtual machine, hosta with WebSphere Application Server Version 8.5 installed, as well as an iso image was created for this lab; Java7win32.iso What you should be able to do At the end of this lab you should be able to Install Java 7 SE and configure WebSphere Application Server to use Java 7 SE Configure and use the Memory Leak Detection function Have an understanding of the functions provided by the Delta Checkpoints for tracking administrative configuration changes.. Exercise instructions Some instructions in this lab may be Windows operating-system specific. If you plan on running the lab on an operating-system other than Windows, you will need to execute the appropriate commands, and use appropriate files (.sh vs.bat) for your operating system. The directory locations are specified in the lab instructions using symbolic references, as follows: Reference variable Windows location Linux or UNIX locations <WAS_HOME> C:\IBM\WebSphere\AppServer /usr/websphere/appserver /opt/websphere/appserver Page 7

166 <PROFILE_HOME> C:\IBM\WebSphere\AppServer\profiles\AppSrv01 /usr/websphere/appserver/profiles/ap psrv01 /opt/websphere/appserver/profiles/ap psrv01 <RAD_HOME> C:\Program Files\IBM\SDP /opt/ibm/sdp <LAB_FILES> C:\Labfiles85 /tmp/labfiles85 <TEMP> C:\temp /tmp Note for Windows users: When directory locations are passed as parameters to a Java program such as EJBdeploy or wsadmin, it is necessary to replace the backslashes with forward slashes to follow the Java convention. For example, C:\Labfiles85\ would be replaced by C:/Labfiles85/ Page 8

167 Part 1: Java 7 SE Installation and Configuration of WebSphere Application Server to use Java 7 SE Note: If you intend to copy and paste snippets from this document into the Windows command window in the VMware image used for this lab, in order to avoid typing you might want to consider copying to notepad, and from there to the Windows command window in order to avoid any extended character attributes from Word or PDF not being correctly interpreted when copied directly to a Windows command shell. 1. In order to insure that you have a recovery point in case of problems take a VM snapshot. Provide a meaningful name such as Lab 4 Starting Image. Refer to the Common Tasks Section of Before You Begin if you need detailed instructions. Start the Virtual Machine and mount the Java 7 iso CD image. 2. If it is not already started, start the host A Virtual Machine image a. Log in using Administrator with the password passw0rd (numeric zero) 3. Mount the Java7win32.iso on the CD/DVD device for the host A virtual machine, refer to common tasks section at the end of this document if you need detailed instructions on how to do so. a. Close the window that automatically opens when the CD/DVD mounts Install Java 7 using Installation Manager 4. Using Windows Explorer (shortcut is on the desktop) navigate to C:\Program Files\IBM\Installation Manager\eclipse\tools a. Highlight one of the folders and click the right mouse button and click Command Window as shown below (this will open a Windows Command Shell) Page 9

168 b. A response file has already been created for the Java 7 SE install, copy the java7se_response_file.xml file from the Lab 4 directory to the C:\temp directory c. Navigate to the directory: C:\Program Files\IBM\Installation Manager\eclipse\tools d. On a single line enter the as shown below: imcl input C:\temp\java7se_response_file.xml -preferences com.ibm.cic.common.core.preferences.preservedownloadedartifacts=false -acceptlicense e. This will take 2-3 minutes to complete; you can safely ignore the Warning indicated below. When the installation is complete you should see the screen below indicating the Java 7 SE was installed. f. Type exit and hit enter to close the command window Create a Stand-Alone Server Profile Page 10

169 5. Using the Windows Explorer shortcut on the desktop navigate to C:\IBM\WebSphere\AppServer\bin, highlight a folder using the right mouse button to open a command window 6. In the command window enter the command shown below (in a single line) manageprofiles.bat -create -profilename AppServer01 -templatepath C:\IBM\WebSphere\AppServer\profileTemplates\default -enableadminsecurity true - adminusername wasadmin -adminpassword wasadm1n 7. Confirm that the profile is created with an INSTCONFSUCCESS message as shown below. Display and switch the Java SE version used for the WebSphere Application Server In the command window, enter cd..\profiles\appserver01\bin to change to the bin directory for the profile you just created. From the command line, enter managesdk.bat listavailable to display the list of available SDKs. The expected results are shown below. 10. Enter the command managesdk.bat -profilename AppServer01 listenabledprofile This command displays the SDK that is currently enabled for the WebSphere Application Server you just created. You can see the profile is configured to use Java 6 SE) Page 11

170 11. Enter the command managesdk.bat -enableprofile -sdkname 1.7_32 -profilename AppServer01, The command enables the Java 7 SE for the WebSphere Application Server. The expected results are shown below (as you can see the profile will now use Java 7 SE) 12. Enter the command managesdk.bat listenabledprofileall This command displays the DSK version for all profiles in the cell. The expected results are shown below. As you can see the Job Manager is still configured to use Java 6 SE while the Application Server is configured to use Java 7 SE. We will leave the Application Server configured to use Java 7 SE for the remainder of this lab. Page 12

171 Page 13

172 Part 2: Tracking Administrative Configuration Changes Enable automatic tracking repository Checkpoints In this exercise, after you enable the automatic repository checkpoints, you will change the heap size settings on the application server s JVM. Then, you will review the changes to the configuration based on the checkpoint configurations that were automatically generated. 1. Enter the command startserver.bat server1 (in the current command window) You should be in directory: C:\IBM\WebSphere\AppServer\profiles\AppServer01\bin 2. When the application server has started as indicated with an ADMU3000I message as shown below ADMU3000I: Server server1 open for e-business; process id is xxxx Open a browser and enter the URL If you receive a secure connection failed error and need help in resolving it, refer to the Common Tasks in Before You Begin document for more information. Log in as the user wasadmin with the password wasadm1n Navigate to System Administration -> Extended Repository Service as shown below 6. Select Enable automatic repository checkpoints as shown below and click OK Page 14

173 Update the Java Heap Size on the server, which will trigger an automatic repository checkpoint. 7. Navigate to Servers -> Server Types -> WebSphere application servers as shown below 8. Click on server1 Page 15

174 9. In the right hand panel navigate to Server Infrastructure and expand Java and Process Management then select Process Definition 10. Click on Java Virtual Machine 11. Enter 128 for the Initial Heap Size and 256 for the Maximum Heap Size 12. Click OK, then Save your changes Page 16

175 Compare the configuration changes from the extracted data generated by the automatic repository checkpoint. 13. Navigate back to System administration -> Extended Repository Service 14. Click on the Repository Checkpoints link. 15. Select the last checkpoint and click Export Page 17

176 16. Click on the zip file 17. Then choose to Save File (if using Firefox this is saved to My Documents\Downloads) Page 18

177 18. Navigate to the folder the zip file was saved in and extract the files 19. This will create a folder of the format Delta-<checkpointnumber>. Inside that folder will be two more folders named before and after 20. There are several ways to determine the differences a. Manual compare all the files in the before and after directories, which show that the lines noted below in the server.xml file has changed. b. Use of a diff tool such as Beyond Compare which can be used to produce the output shown below Page 19

178 Page 20

179 Page 21

180 Part 3: Memory Leak Detection and Correction 1. Copy logger.exe from the Lab4 folder to C:\IBM\WebSphere\AppServer\profiles\AppServer01\logs\server1 2. logger is a utility for Windows that provides the Unix tail function. Open a command window for the C:\IBM\WebSphere\AppServer\profiles\AppServer01\logs\server1 directory and enter the command logger.exe SystemOut.log The SystemOut.log will then scroll as you make changes in this lab. Minimize but DO NOT CLOSE this command window, we will return to it later in the lab Install a test application that will produce a Java memory leak. 3. Open the WebSphere admin console. Then navigate to Applications and click on New Application Page 22

181 4. Click on New Enterprise Application 5. Using the Local file system option, browse to the location where you placed the LeakApp.ear. Click open then click Next. The instructor has provided the LeakAppEar.ear file as part of this lab exercise. 6. Use the Fast path option and click Next 7. Accept the default values of the Select installation options panel and click Next Page 23

182 8. Accept the default values on the Map modules to server panel and click Next 9. Accept the default values on the Map virtual hosts for Web modules panel and click Next 10. Accept the default values on the Metadata for modules panel and click Next 11. Review the parameters on the Summary panel and click Finish Page 24

183 12. When the application has been successfully installed, click Save Start the Memory Leak Application 13. Check to see that the application is started by navigating to Applications -> Application Types, expand Application Types, click on WebSphere enterprise applications, To start the LeakAppEar, select the checkbox to the left of the application name and click the Start button as shown below. Page 25

184 Note: There are two options for configuring memory leak detection, application server configuration changes which are persisted to the application server configuration and application server runtime changes. Configuration changes are permanent and apply each time the application server is started (and require a server restart to become effective) Runtime changes are not permanent and need to be made each time an application server is started. In order to speed delivery of this lab the memory leak detection function will be enabled using runtime changes using wsadmin to update the Mbeans associated with this function. The instructions for using configuration changes to permanently update the configuration is provided in Appendix A Enable the Leak Detection feature using the wsadmin commands. The leak detection policy for the WebSphere Application Server is turned off by default. You can configure a leak detection, prevention, and action policy to accommodate your applications and environment so that potential memory leaks are reported and acted upon. Leak detection, prevention, and proactive fixing provides for protection and resiliency for servers that face persistent out of memory errors. When a classloader memory leak is detected, WebSphere Application Server notifies you with informational messages in the log and by taking JVM heapdumps so that you can troubleshoot the problem. Optionally, you might also choose to have WebSphere Application Server mitigate, and if possible, fix the memory leak using reflection and other techniques. You will explore several of the capabilities of the memory leak detection and mitigation in this section of the exercise. 14. Return to the command window where you started server1 and enter wsadmin -lang jython Page 26

185 Ensure you are in the following directory in the command prompt: C:\IBM\WebSphere\AppServer\profiles\AppServer01\bin a. when prompted, enter wasadmin for the user and wasadm1n for the password. b. Since this is the first time the wsadmin jython libraries have been used you ll see a number of messages similar to those shown below. indicating *sys-package-mgr*: processing new jar, <jar name> 15. Obtain a reference to the memory leak configuration Mbean using the following command: leakconfig = AdminControl.completeObjectName('type=MemoryLeakConfig,*') TIP: You need a reference to the memory leak Configuration MBean in order to execute the configuration commands that are listed on step 19, that influence the configuration of the memory leak configuration. 16. Check to see the reference that was returned using the following command print leakconfig 17. Obtain a reference to the memory leak administrative Mbean using the following command leakadmin = AdminControl.completeObjectName('type=MemoryLeakAdmin,*') Page 27

186 TIP: You need a reference to the memory leak Administrative MBean in order to execute the administrative commands listed in step Check to see the reference that was obtained using the following command print leakadmin 19. Look at the current configuration of the configuration Mbean using the following command. These are the attributes that can be set to influence the configuration. print Help.all(leakconfig) 20. Look at the current configuration of the administrative Mbean using the command. These are the attributes that can be set to influence the configuration. Page 28

187 print Help.all(leakadmin) 21. Enter the following wsadmin command to tell WAS to stop any Timer threads the application is started by an application. AdminControl.setAttribute(leakconfig,'ClearReferencesStopTimerThreads','true') TIP: Set the value to true for WebSphere Application Server to stop any java.util.timerthreads that is started by the web application. 22. Enter the wsadmin command to ensure that the value for this attribute was updated. AdminControl.getAttribute(leakconfig,'ClearReferencesStopTimerThreads') 23. Enter the following wsadmin command to detect Class Loader leaks in applications. AdminControl.setAttribute(leakconfig,'DetectAppCLLeaks','true') TIP: When the server is shutting down or an application stops, WebSphere Application Server determines the classloaders that have leaked and issues warnings and other additional information that aids in debugging the memory leak. 24. Enter the wsadmin command to ensure that the value for this attribute was updated AdminControl.getAttribute(leakconfig,'DetectAppCLLeaks') Page 29

188 25. Enter the following wsadmin command to detect Thread Local leaks. AdminControl.setAttribute(leakconfig,'CheckThreadLocalLeaks','true') TIP: Checks for ThreadLocal leaks when an application stops. 26. Enter the wsadmin command to ensure that the value for this attribute was updated AdminControl.getAttribute(leakconfig,'CheckThreadLocalLeaks') 27. Enter the following wsadmin command to enable WebSphere proactive leak mediation. AdminControl.setAttribute(leakconfig,'ClearAppCLLeaks','true') TIP: This enables proactive classloader leak mediation and fixing. When this property is set to true, WebSphere Application Server mediates on behalf of the application to remedy any classloader leaks that are detected. 28. Enter the command to ensure that the value for this attribute was changed AdminControl.getAttribute(leakconfig,'ClearAppCLLeaks') 29. Enter the following wsadmin command to check for memory leaks. (note that no leaks are found) AdminControl.invoke(leakadmin, 'findleaks') 30. Open a browser and enter the URL Page 30

189 31. Refresh the URL several times The application is designed to leak classes. The memory leak will be very slow and may not be noticeable, even after executing the leaking applications several times. Note: Application stop is required because only when an application is stopped, is the memory leak function able to insure that the classloader of the application/module is no longer needed. 32. Enter the wsadmin command to attempt to fix the memory leak and reclaiming memory that has been leaked by the application. AdminControl.invoke(leakadmin, 'fixleaks') WARNING: At the time of this writing, using WAS , the fixleaks command does not seem to attempt to fix any leaks. However, upon stopping the leaking application, WebSphere detects the memory leaks and reports them in the SystemOut.log. Furthermore, the findleaks command only seems to fin the memory leaks once the application has been stopped. So, in order to see the memory leak, you will stop the leaking application, and review the SystemOut.log. 33. From the WebSphere Admin Console, stop the LeakAppEar, by selecting the application and clicking the Stop button. (using the same process you did to start the application) Note: Application stop is required because only when an application stopped, is the memory leak function able to insure that the classloader of the application/module is no longer needed Depending on the underlying cause of the memory leak, the fixleaks method, may or may not be able to provide a remedy. Memory leaks caused by incorrect use of Threadlocals, Timers, Threads, static Page 31

190 variables may be correctable by calling standard Java APIs or to use reflection to null out references or by stopping timers, interrupting threads or refreshing the thread pool. Other leaks related to the object references on the classloader on the other hand, may only be correctable by stopping the application. 34. Stopping the application will result in the following types of messages in the SystemOut.log 35. Notice that stopping the leaking application caused the memory leak detection function to realize that classes used by the application were not cleaned up, ev3en when the application stopped. This is a class loader memory leak. a. You will also notice that the memory leak function produced Java heap dumps, which can be analyzed by the systems administrator and development team during problem determination. End of Lab 4 Congratulations! You have successfully performed a silent install of Java 7 SE and configured WebSphere Application Server to use Java 7 using the managesdk command, used delta checkpoints to determine configuration changes, and used the memory leak detection function to find and correct memory leaks. Page 32

191 Appendix A Memory Leak Detection Persistent Configuration Log in to the WebSphere Application Server admin console Navigate to Servers, expand Server Types, and click on WebSphere application servers 3. Click on server1 4. Issue the command startserver.bat server1 (in the current command window) 5. On the application server details panel locate the Server Infrastructure heading, then expand the Java and Process Management category, then click Process definition. Page 33

192 6. On the Process definition screen, locate the Additional Properties heading, and then click Java Virtual Machine. 7. On the Java Virtual Machine page, locate the Additional Properties heading. Then click Custom properties 8. Use the Custom properties screen to add the following memory leak detection, prevention, and action properties to the server configuration. (select new, add the property and value, then click OK) a. com.ibm.ws.runtime.component.memoryleakconfig.detectappclleaks with a value of true b. com.ibm.ws.runtime.component.memoryleakconfig.clearappclleaks with a value of true c. com.ibm.ws.runtime.component.memoryleakconfig.preventjrememoryleaks with a value of true d. com.ibm.ws.runtime.component.memoryleakconfig.clearreferencesstatic with a value of true e. com.ibm.ws.runtime.component.memoryleakconfig.clearreferencesinterruptthreads with a value of true f. com.ibm.ws.runtime.component.memoryleakconfig.clearreferencesstoptimerthreads with a value of true g. com.ibm.ws.runtime.component.memoryleakconfig.clearreferencesthreadlocal with a value of true 9. Then click Save to save the changes to the master configuration Page 34

193 Page 35

194 This page is left intentionally blank. Page 36

195 Page 37