IBM ® WebSphere ® Front cover

WebSphere Application
Server Liberty Profile
Guide for Developers
WebSphere Application Server V8.5.5
profile designed for developers

Lightweight, easy to install, and

fast to use application server

Simplified development
with the Liberty profile

Brent Daniel
Alex Mulholland
Erin Schnabel
Kevin Smith

ibm.com/redbooks
International Technical Support Organization

WebSphere Application Server Liberty Profile

Guide for Developers

August 2013

SG24-8076-01
 Note: Before using this information and the product it supports, read the information in
“Notices” on page ix.

Second Edition (August 2013)

This edition applies to WebSphere Application Server V8.5 Liberty Profile.

© Copyright International Business Machines Corporation 2012, 2013. All rights reserved.
Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP
Schedule Contract with IBM Corp.
Contents

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Authors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Now you can become a published author, too! . . . . . . . . . . . . . . . . . . . . . . . . xiii
Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv
Stay connected to IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv

Chapter 1. An introduction to the Liberty profile . . . . . . . . . . . . . . . . . . . . . 1

1.1 Liberty profile overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.1 Programming models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.2 Supported development environments . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.3 Application development and deployment tools . . . . . . . . . . . . . . . . . 4
1.1.4 Additional resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2 Simplified configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2.1 Server definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2.2 Server configuration using the server.xml file . . . . . . . . . . . . . . . . . . . 6
1.2.3 Bootstrap properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.2.4 Portable configuration using variables . . . . . . . . . . . . . . . . . . . . . . . . 8
1.2.5 New configuration types and validation. . . . . . . . . . . . . . . . . . . . . . . 10
1.2.6 Encoding passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.2.7 Shared configuration using includes . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.2.8 Dynamic configuration updates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.3 Runtime composition with features and services . . . . . . . . . . . . . . . . . . . 14
1.3.1 Feature management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.3.2 Automatic service discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1.4 Frictionless application development . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.4.1 Quick start using dropins. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.4.2 Configuration-based application deployment . . . . . . . . . . . . . . . . . . 18
1.4.3 Using loose configuration for applications. . . . . . . . . . . . . . . . . . . . . 19
1.4.4 Configuring an application’s context root . . . . . . . . . . . . . . . . . . . . . 20
1.4.5 Compatibility with WebSphere Application Server . . . . . . . . . . . . . . 20
1.5 Product extensions (new in Version 8.5.5) . . . . . . . . . . . . . . . . . . . . . . . . 21

Chapter 2. Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.1 Installing the WebSphere developer tools. . . . . . . . . . . . . . . . . . . . . . . . . 26
2.1.1 Installation from Eclipse Marketplace . . . . . . . . . . . . . . . . . . . . . . . . 26
2.1.2 Installation from the WASdev community site . . . . . . . . . . . . . . . . . . 27

© Copyright IBM Corp. 2012, 2013. All rights reserved. iii

 2.1.3 Installation from downloaded installation files . . . . . . . . . . . . . . . . . . 29
2.2 Installing the Liberty profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.2.1 Installation using the Liberty profile developer tools . . . . . . . . . . . . . 29
2.2.2 Installation using the command line . . . . . . . . . . . . . . . . . . . . . . . . . 35
2.2.3 Installation on z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.2.4 The Liberty profile runtime environment and server
directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.3 Configuring the server runtime JDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
2.3.1 Defining the JRE from within workbench . . . . . . . . . . . . . . . . . . . . . 40
2.3.2 Configuring the system JRE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
2.3.3 Using server.env to define the JRE. . . . . . . . . . . . . . . . . . . . . . . . . . 42
2.3.4 Specifying JVM properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
2.4 Starting and stopping a Liberty profile server . . . . . . . . . . . . . . . . . . . . . . 43
2.4.1 Starting and stopping the server using the command line . . . . . . . . 43
2.4.2 Starting and stopping the server from the workbench. . . . . . . . . . . . 44

Chapter 3. Developing and deploying web applications . . . . . . . . . . . . . . 45

3.1 Developing applications using the Liberty profile developer tools . . . . . . . 46
3.1.1 Using the tools to create a simple servlet application . . . . . . . . . . . . 46
3.1.2 Developing and deploying a JSP application . . . . . . . . . . . . . . . . . . 50
3.1.3 Developing and deploying a JSF application . . . . . . . . . . . . . . . . . . 52
3.1.4 Developing and deploying JAX-RS applications . . . . . . . . . . . . . . . . 59
3.1.5 Using Context and Dependency Injection in web applications with the
Liberty profile developer tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
3.1.6 Developing Java Message Service web applications with the Liberty
profile developer tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
3.1.7 Developing JAX-WS web services applications with the Liberty profile
developer tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
3.1.8 Debugging applications with the Liberty profile developer tools . . . . 77
3.2 Developing outside the Liberty profile developer tools . . . . . . . . . . . . . . . 78
3.2.1 Feature enablement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
3.2.2 Dynamic application update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
3.2.3 Common development configuration . . . . . . . . . . . . . . . . . . . . . . . . 80
3.2.4 Dynamic configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
3.2.5 API JAR files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
3.2.6 Debugging applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
3.2.7 Using Maven to automate tasks for the Liberty profile . . . . . . . . . . . 83
3.2.8 Using ANT to automate tasks for the Liberty profile . . . . . . . . . . . . . 87
3.3 Controlling class visibility in applications . . . . . . . . . . . . . . . . . . . . . . . . . . 88
3.3.1 Using shared libraries in applications . . . . . . . . . . . . . . . . . . . . . . . . 88
3.3.2 Creating a shared library in the Liberty profile developer tools . . . . . 89
3.3.3 Creating a shared library outside of the tools . . . . . . . . . . . . . . . . . . 90
3.3.4 Using libraries to override Liberty profile server classes . . . . . . . . . . 90

iv WebSphere Application Server Liberty Profile Guide for Developers

 3.3.5 Global libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
3.3.6 Using a classloader to control API visibility . . . . . . . . . . . . . . . . . . . . 91

Chapter 4. Iterative development of OSGi applications. . . . . . . . . . . . . . . 93

4.1 Introduction to OSGi applications in Liberty profile . . . . . . . . . . . . . . . . . . 94
4.2 Developing OSGi applications in the Liberty profile developer tools . . . . . 94
4.2.1 Using the tools to build an OSGi application . . . . . . . . . . . . . . . . . . . 95
4.2.2 Using the tools to deploy and test an OSGi application . . . . . . . . . . 99
4.2.3 Adding an OSGi web application bundle. . . . . . . . . . . . . . . . . . . . . 100
4.3 Developing OSGi applications outside Liberty profile developer tools . . 101
4.3.1 Building and deploying OSGi applications outside of the tools . . . . 102
4.3.2 Using Maven to automate OSGi development tasks . . . . . . . . . . . 102
4.3.3 Using ANT to automate OSGi development tasks . . . . . . . . . . . . . 102

Chapter 5. Data access in the Liberty profile . . . . . . . . . . . . . . . . . . . . . . 105

5.1 Accessing data using a data source and JDBC . . . . . . . . . . . . . . . . . . . 106
5.1.1 Basic concepts for configuring data access in Liberty
profile server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
5.1.2 Adding a data source using Liberty profile developer tools. . . . . . . 107
5.1.3 Adding a data source outside the Liberty profile developer tools . . 110
5.1.4 Using the data source in an application . . . . . . . . . . . . . . . . . . . . . 111
5.1.5 Defining a data source in an application . . . . . . . . . . . . . . . . . . . . . 111
5.1.6 Using application-defined data sources . . . . . . . . . . . . . . . . . . . . . 113
5.1.7 Testing the data sources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
5.1.8 Dynamic configuration updates for data sources . . . . . . . . . . . . . . 115
5.2 Developing JPA applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
5.2.1 JPA applications in the Liberty profile developer tools . . . . . . . . . . 116
5.2.2 JPA applications outside the Liberty profile developer tools . . . . . . 123
5.3 Developing Enterprise Java Bean applications . . . . . . . . . . . . . . . . . . . . 123
5.3.1 Developing EJB applications in the Liberty profile developer tools . 123
5.3.2 EJB applications outside the Liberty profile developer tools . . . . . . 126
5.4 Developing message driven bean applications . . . . . . . . . . . . . . . . . . . . 126
5.4.1 Developing message driven bean applications in the Liberty profile
developer tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
5.4.2 MDB applications outside the Liberty profile developer tools . . . . . 129
5.5 Data access with MongoDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
5.5.1 Developing MongoDB applications with the Liberty profile developer
tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
5.5.2 Developing MongoDB applications outside of the Liberty profile
developer tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Chapter 6. Configuring application security. . . . . . . . . . . . . . . . . . . . . . . 137

6.1 Enabling SSL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
6.1.1 Configuration using the WebSphere developer tools . . . . . . . . . . . 138

Contents v
 6.1.2 Configuration using the command line . . . . . . . . . . . . . . . . . . . . . . 141
6.2 HTTPS redirect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
6.3 Form login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
6.3.1 Defining the basic user registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
6.3.2 Updating an application to support Form Login . . . . . . . . . . . . . . . 149
6.3.3 Defining bindings between the application and the server . . . . . . . 155
6.4 Securing JMS applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
6.4.1 Setting up user authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
6.4.2 Setting up user authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
6.5 JAX-WS security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
6.6 Securing MongoDB applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Chapter 7. Serviceability and troubleshooting . . . . . . . . . . . . . . . . . . . . . 169

7.1 Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
7.1.1 Inspecting the output logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
7.1.2 Configuration of an additional trace . . . . . . . . . . . . . . . . . . . . . . . . 171
7.2 Server memory dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
7.3 MBeans and JConsole . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Chapter 8. From development to production . . . . . . . . . . . . . . . . . . . . . . 181

8.1 Configuring a server for production use . . . . . . . . . . . . . . . . . . . . . . . . . 182
8.1.1 Turning off application monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . 182
8.1.2 Generating a web server plug-in configuration . . . . . . . . . . . . . . . . 182
8.2 Using the package utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
8.2.1 Packaging a Liberty profile server by using the WebSphere developer
tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
8.2.2 Packaging a Liberty profile server from a command prompt. . . . . . 184
8.2.3 Using the Job Manager to package and distribute Liberty
profile servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
8.3 Moving an application to the full profile . . . . . . . . . . . . . . . . . . . . . . . . . . 185
8.3.1 Programming model differences between full profile and
Liberty profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
8.3.2 Configuration differences between full profile and
Liberty profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
8.4 Using the Liberty profile on z/OS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Chapter 9. Developing and deploying custom features (new in Version 8.5.5)

191
9.1 Considerations for creating custom features. . . . . . . . . . . . . . . . . . . . . . 192
9.2 Defining a custom feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
9.2.1 Elements of a feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
9.2.2 Visibility constraints for features, packages, and services . . . . . . . 196
9.2.3 Subsystem content: Writing a minify-compatible feature . . . . . . . . 200
9.2.4 Using the tools to create a custom feature . . . . . . . . . . . . . . . . . . . 201

vi WebSphere Application Server Liberty Profile Guide for Developers

 9.2.5 Automatic provisioning: Creating an auto-feature . . . . . . . . . . . . . . 210
9.2.6 Packaging native code in your bundles. . . . . . . . . . . . . . . . . . . . . . 211
9.2.7 Packaging features for delivery. . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
9.3 Liberty product extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Appendix A. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Locating the web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Using the web material. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Downloading and extracting the web material . . . . . . . . . . . . . . . . . . . . . 216
Importing the Liberty profile developer tools projects . . . . . . . . . . . . . . . . 216
Using the compressed Derby database files. . . . . . . . . . . . . . . . . . . . . . . 217

Related resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

Contents vii
viii WebSphere Application Server Liberty Profile Guide for Developers
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult your
local IBM representative for information on the products and services currently available in your area. Any
reference to an IBM product, program, or service is not intended to state or imply that only that IBM product,
program, or service may be used. Any functionally equivalent product, program, or service that does not infringe
any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and
verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document. The
furnishing of this document does not grant you any license to these patents. You can send license inquiries, in
writing, to:
IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785 U.S.A.
The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of
express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the
information herein; these changes will be incorporated in new editions of the publication. IBM may make
improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time
without notice.
Any references in this information to non-IBM websites are provided for convenience only and do not in any
manner serve as an endorsement of those websites. The materials at those websites are not part of the materials
for this IBM product and use of those websites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any
obligation to you.
Any performance data contained herein was determined in a controlled environment. Therefore, the results
obtained in other operating environments may vary significantly. Some measurements may have been made on
development-level systems and there is no guarantee that these measurements will be the same on generally
available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual
results may vary. Users of this document should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their published
announcements or other publicly available sources. IBM has not tested those products and cannot confirm the
accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the
capabilities of non-IBM products should be addressed to the suppliers of those products.
This information contains examples of data and reports used in daily business operations. To illustrate them as
completely as possible, the examples include the names of individuals, companies, brands, and products. All of
these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is
entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any
form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs
conforming to the application programming interface for the operating platform for which the sample programs are
written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample
programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing
application programs conforming to IBM's application programming interfaces.

© Copyright IBM Corp. 2012, 2013. All rights reserved. ix

Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business
Machines Corporation in the United States, other countries, or both. These and other IBM trademarked
terms are marked on their first occurrence in this information with the appropriate symbol (® or ™),
indicating US registered or common law trademarks owned by IBM at the time this information was
published. Such trademarks may also be registered or common law trademarks in other countries. A current
list of IBM trademarks is available on the Web at http://www.ibm.com/legal/copytrade.shtml
The following terms are trademarks of the International Business Machines Corporation in the United States,
other countries, or both:

AIX® MVS™ Redbooks (logo) ®

CICS® Passport Advantage® Tivoli®
DB2® Rational® WebSphere®
IBM® Redbooks® z/OS®
The following terms are trademarks of other companies:
Linux is a trademark of Linus Torvalds in the United States, other countries, or both.
Windows, and the Windows logo are trademarks of Microsoft Corporation in the United States, other
countries, or both.
Java, and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its
affiliates.
Other company, product, or service names may be trademarks or service marks of others.

x WebSphere Application Server Liberty Profile Guide for Developers

Preface

IBM WebSphere® Application Server V8.5 includes a Liberty profile, which is a

highly composable, dynamic application server profile. It is designed for two
specific use cases: Developer with a smaller production run time, and production
environments. For a developer, it focuses on the tasks a developer does most
frequently and makes it possible for the developer to complete those tasks as
quickly and as simply as possible. For production environments, it provides a
dynamic, small footprint run time to be able to maximize system resources.

This IBM® Redbooks® publication provides you with information to effectively

use the WebSphere Application Server V8.5 Liberty profile along with the
WebSphere Application Server Developer Tools for Eclipse, for development
and testing of web applications that do not require a full Java Platform. It
provides a quick guide on getting started, providing a scenario-based approach
to demonstrate the capabilities of the Liberty profile along with the developer
tools, providing a simplified, but comprehensive, application development and
testing environment.

The intended audience for this book is developers of web and OSGi applications
who are familiar with web and OSGi application concepts.

This book has been updated to reflect the new features in WebSphere
Application Server V8.5.5.

Authors
This book was produced by a team of specialists from around the world working
at the International Technical Support Organization, Raleigh Center.

© Copyright IBM Corp. 2012, 2013. All rights reserved. xi

 Brent Daniel is a developer for WebSphere
Application Server Liberty profile. He has worked
in the WebSphere organization for over 13 years
on a diverse set of technologies including
persistence, web applications, administration,
and SCA.

Alex Mulholland is a Senior Technical Staff

Member in the WebSphere Application Server
Development team at the IBM Lab in Raleigh, NC,
and is the Liberty Profile architect. She has worked
in IBM software development for over 20 years,
including IBM CICS® and Component Broker
development before moving to the WebSphere
Transaction Manager team at the IBM Hursley lab
in the UK. Alex was the Release Architect for
WebSphere Application Server V6.1 and version
7.0, then led an incubation project that developed
into the Liberty Profile. She now provides technical
direction to the team that delivers the Liberty
Profile to the WebSphere Application
Server product.

Erin Schnabel is the Development lead for the

WebSphere Application Server Liberty profile. She
has over 12 years of experience in the WebSphere
Application Server development organization in
various technical roles. Erin has over 15 years of
experience working with Java and application
middleware across various hardware platforms,
including IBM z/OS®. She specializes in
composable run times, including the application of
OSGi, object-oriented and service-oriented
technologies and design patterns to decompose
existing software systems into flexible,
composable units.

xii WebSphere Application Server Liberty Profile Guide for Developers

 Kevin Smith is the test architect for the
WebSphere Application Server Liberty profile.
Based in Hursley in the United Kingdom he has
worked in IBM for almost 20 years on all aspects
of the development lifecycle. For the last five
years, Kevin has been focused on innovating the
way we test in an agile development environment
and most recently has been applying these
practices to the Liberty profile to drive increased
quality and efficiency across the worldwide
development teams.

Thanks to the following people for their contributions to this project:

Margaret Ticknor, Deana Coble, Shari Deiana, Tamikia Lee, Linda Robinson
International Technical Support Organization, Raleigh Center

Carla Sadtler
International Technical Support Organization, Poughkeepsie Center

Gary R. Picher, Nathan Rauh

IBM US

Ian Robinson
IBM UK

Jacek Laskowski
IBM Poland

Now you can become a published author, too!

Here’s an opportunity to spotlight your skills, grow your career, and become a
published author—all at the same time! Join an ITSO residency project and help
write a book in your area of expertise, while honing your experience using
leading-edge technologies. Your efforts will help to increase product acceptance
and customer satisfaction, as you expand your network of technical contacts and
relationships. Residencies run from two to six weeks in length, and you can
participate either in person or as a remote resident working from your
home base.

Find out more about the residency program, browse the residency index, and
apply online at:
ibm.com/redbooks/residencies.html

Preface xiii
Comments welcome
Your comments are important to us!

We want our books to be as helpful as possible. Send us your comments about

this book or other IBM Redbooks publications in one of the following ways:
򐂰 Use the online Contact us review Redbooks form found at:
ibm.com/redbooks
򐂰 Send your comments in an email to:
redbooks@us.ibm.com
򐂰 Mail your comments to:
IBM Corporation, International Technical Support Organization
Dept. HYTD Mail Station P099
2455 South Road
Poughkeepsie, NY 12601-5400

Stay connected to IBM Redbooks

򐂰 Find us on Facebook:
http://www.facebook.com/IBMRedbooks
򐂰 Follow us on Twitter:
http://twitter.com/ibmredbooks
򐂰 Look for us on LinkedIn:
http://www.linkedin.com/groups?home=&gid=2130806
򐂰 Explore new Redbooks publications, residencies, and workshops with the
IBM Redbooks weekly newsletter:
https://www.redbooks.ibm.com/Redbooks.nsf/subscribe?OpenForm
򐂰 Stay current on recent Redbooks publications with RSS Feeds:
http://www.redbooks.ibm.com/rss.html

xiv WebSphere Application Server Liberty Profile Guide for Developers

 1

Chapter 1. An introduction to the

Liberty profile
The IBM WebSphere Application Server V8.5 Liberty Profile is a composable,
dynamic application server environment that supports development and testing
of web applications that do not require a full Java Platform, Enterprise Edition 6
(Java EE 6) stack. The profile is fully supported for production use, but is
designed to work alongside WebSphere Application Server Developer Tools for
Eclipse to provide a simplified, but comprehensive, application development and
testing environment.

This guide is for developers of web and OSGi applications. It assumes familiarity
with web and OSGi application concepts, but does not assume familiarity with
WebSphere Application Server resources or products. This guide refers to other
IBM Redbooks publications and the WebSphere Application Server V8.5
Information Center for additional information.

The topics in this chapter provide an overview of Liberty profile characteristics

that are useful for iterative and collaborative application development:
򐂰 Liberty profile overview
򐂰 Simplified configuration
򐂰 Runtime composition with features and services
򐂰 Frictionless application development
򐂰 Product extensions (new in Version 8.5.5)

© Copyright IBM Corp. 2012, 2013. All rights reserved. 1

1.1 Liberty profile overview
The Liberty profile is a simplified, lightweight development and application
runtime environment that is:
򐂰 Simple to configure. Configuration is read from a single XML file with
text-editor-friendly syntax.
򐂰 Dynamic and flexible. The run time loads only what your application needs
and recomposes the run time in response to configuration changes.
򐂰 Fast. The server starts in under five seconds with a basic web application.
򐂰 (New in Version 8.5.5) Extensible. The Liberty profile provides support for
user and product extensions, which can use System Programming Interfaces
(SPIs) to extend the run time.

The Liberty profile is built by using OSGi technology and concepts. The
fit-for-purpose nature of the run time relies on the dynamic behavior inherent in
the OSGi Framework and Service Registry. As bundles are installed to or
uninstalled from the framework, the services each bundle provides are added or
removed from the service registry. The addition and removal of services similarly
cascades to other dependent services. The result is a dynamic, composable run
time that can be provisioned with only what your application requires and
responds dynamically to configuration changes as your application evolves.

1.1.1 Programming models

The Liberty profile supports a subset of the Java EE 6 stack. The following list
notes the supported technologies that are supported by all versions of the
Liberty profile:
򐂰 Java Servlet 3.0
򐂰 JavaServer Faces (JSF) 2.0
򐂰 JavaServer Pages (JSP) 2.2
򐂰 Java Expression Language 2.2
򐂰 Standard Tag Library for JavaServer Pages (JSTL) 1.2
򐂰 Bean Validation 1.0
򐂰 Java Persistence API (JPA) 2.0
򐂰 Java Transaction API (JTA) 1.1
򐂰 Java Database Connectivity (JDBC) 4.0
򐂰 Java API for RESTful Web Services (JAX-RS) 1.1

2 WebSphere Application Server Liberty Profile Guide for Developers

 (New in Version 8.5.5) The WebSphere Application Server Liberty Core edition is
a separate offering that is available for production use that is based on the
Liberty profile. The Liberty Core edition extends the technologies that were listed
previously to support the following Java EE 6 Web Profile specifications:
򐂰 Contexts and Dependency Injection for Java (Web Beans 1.0)
򐂰 Dependency Injection for Java 1.0
򐂰 Enterprise JavaBeans 3.1 (includes Interceptors 1.1) - EJB Lite subset

In other editions, such as WebSphere Application Server and WebSphere

Application Server Network Deployment, the Liberty profile supports the
following technologies in addition to those contained in Liberty Core:
򐂰 Java API for XML-Based Web Services (JAX-WS) 2.2
򐂰 Java Architecture for XML Binding (JAXB) 2.2
򐂰 SOAP with Attachments API for Java (SAAJ) 1.3
򐂰 Java Message Service API (JMS) 1.1
򐂰 Enterprise JavaBeans 3.1 - Message-Driven beans

The Liberty profile supports OSGi applications in all editions. The following list
shows supported technologies for OSGi applications (with a reference to the
specification where appropriate):
򐂰 Web Application Bundles (OSGi R4.2 Enterprise, Chapter 128)
򐂰 Blueprint Container (OSGi R4.2 Enterprise, Chapter 121)
– Blueprint Transactions
– Blueprint Managed JPA
򐂰 JNDI (OSGi R4.2 Enterprise, Chapter 126)
򐂰 OSGi application of Java EE technologies that are supported by the profile

A complete list of the technologies that are supported by the Liberty profile can
be found at the following Information Center website:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
wlp.nd.doc/ae/rwlp_prog_model_support.html

1.1.2 Supported development environments

Both Liberty and full profile WebSphere Application Server support a broad list of
operating systems: IBM AIX®, HP, IBM i, Linux, Solaris, Windows, and z/OS.
The Liberty profile is also supported, for development, on Mac OSX.

The Liberty profile server runs on Java Version 6 or later regardless of the
vendor that provides it.

Chapter 1. An introduction to the Liberty profile 3

 The list of supported operating systems and requirements for the Liberty profile
can be found at:
http://www-01.ibm.com/support/docview.wss?uid=swg27038218

1.1.3 Application development and deployment tools

IBM provides two development tools that are designed for use with WebSphere
Application Server applications and include tools that are specifically suited for
use with the Liberty profile:
򐂰 IBM Rational® Application Developer for WebSphere Software V9
IBM Rational Application Developer for WebSphere Software V9 provides a
development environment for building applications that run on WebSphere
Application Server. This tool supports all Java EE artifacts that are supported
by WebSphere Application Server, such as servlets, JavaServer Pages
(JSP), JavaServer Faces (JSF), Enterprise JavaBeans (EJB), Extensible
Markup Language (XML), SIP, Portlet, and web services. It also includes
integration with the Open Services Gateway initiative (OSGi) programming
model. The workbench contains wizards and editors that help build
standards-compliant, business-critical Java EE, Web 2.0, and
service-oriented architecture (SOA) applications. Code quality tools help
teams find and correct problems before they escalate into expensive
problems. Rational Application Developer for WebSphere Software can be
used to develop applications for both the full profile and the Liberty profile.
For more information about Rational Application Developer for WebSphere
Software V9, see the following website:
http://www.ibm.com/software/awdtools/developer/application/
򐂰 WebSphere Application Server Developer Tools for Eclipse
The IBM WebSphere developer tools V8.5.5 provides a development
environment for developing, assembling, and deploying Java EE, OSGi, Web
2.0, and Mobile applications, and supports multiple versions of WebSphere
Application Server. When combined with Eclipse SDK and Eclipse Web Tools
Platform, WebSphere developer tools provides a lightweight environment for
developing Java EE applications.
WebSphere Application Server Developer Tools for Eclipse is a no additional
charge edition for developer desktop and includes Eclipse adapters. With
Version 8.5.5, WebSphere Application Server and WebSphere Application
Server Developer Tools for Eclipse editions are provided at no additional
charge for developer desktops and are supported under production
runtime licenses.

4 WebSphere Application Server Liberty Profile Guide for Developers

 Although not as rich in features as Rational Application Developer for
WebSphere Software, this tool is an attractive option for developers using
both the Liberty profile and the full profile.
For more information about WebSphere developer tools and access to the
tool, see the following website:
https://www.ibm.com/developerworks/community/blogs/wasdev/entry/down
loads_final_releases?lang=en

WebSphere developer tools: In this book, the development and deployment

processes that are described are applicable to either tool. We use the generic
term WebSphere developer tools as an inclusive term for both WebSphere
Application Server Developer Tools for Eclipse and Rational Application
Developer for WebSphere Software.

1.1.4 Additional resources

There are additional resources available to support development with the Liberty
profile. The following list notes developer-community focused resources:
򐂰 WASdev community
http://wasdev.net/
The WASdev community is a hub for information about developing
applications for WebSphere Application Server, and using the Liberty profile
in particular. Articles, podcasts, videos, and samples are refreshed regularly
as new technology is made available through early access programs or new
product releases.
򐂰 WASdev forum
http://www.ibm.com/developerworks/forums/forum.jspa?forumID=2666
The WASdev forum provides an opportunity for users of WebSphere
Application Server and the Liberty profile to interact with each other and with
the IBM developers working on the products.
򐂰 Stack Overflow tags
http://stackoverflow.com/questions/tagged/websphere-liberty
Stack Overflow is a Q&A site that has no cost to use. It allows users to ask
and answer questions with built-in incentives to reward high-quality answers.
Use the websphere or websphere-liberty tags to ask or answer questions
about WebSphere Application Server and the Liberty profile.

Chapter 1. An introduction to the Liberty profile 5

1.2 Simplified configuration
The Liberty profile runtime environment is composed of a set of OSGi bundles.
Any bundle containing configurable resources also contains metadata describing
the configuration that those resources accept or require using the OSGi
Metatype service. A generic description of a metatype service is a bundle
containing within it an XML schema describing each resource’s configuration
attributes, types, and value bounds. The configuration metadata within each
bundle will also assign appropriate default values, and can construct default
instances where appropriate. With functional defaults already in place, you only
need to specify the values you want to customize.

1.2.1 Server definition

The Liberty profile supports multiple servers using the same installation. Each
server is defined in its own directory, where the directory name is the server
name. New servers are easily created using the command line or the
WebSphere developer tools, but manual creation will also work. Using the
WebSphere developer tools to create a server is described in 2.2, “Installing the
Liberty profile” on page 29.

A server definition requires only one configuration file, server.xml, to define a

server. The server.xml file must contain a server element. If there are no
configuration changes, then default values suffice. The server element can be
empty, as shown in Example 1-1.

Example 1-1 Server.xml file

<server description=”optional description” />

The empty definition in Example 1-1 starts only the core kernel. Additional
function is enabled using features. Features are described in 1.3.1, “Feature
management” on page 15.

1.2.2 Server configuration using the server.xml file

The server.xml file has a simple XML format that can be edited using your
favorite text editor. Though there is no requirement to use a GUI to edit your
server’s configuration, the WebSphere developer tools provide an enhanced
editor for use in an Eclipse IDE. This editor has context-sensitive help,
wizard-style value selection, and built-in configuration validation. The enhanced
editor also allows direct viewing and editing of the XML source.

6 WebSphere Application Server Liberty Profile Guide for Developers

 Figure 1-1 shows the design and source tabs of the enhanced server.xml editor
in the WebSphere developer tools.

Figure 1-1 The source and design tabs show different views of the server’s configuration

The subsequent chapters in this publication provide examples using the

enhanced editor to make server configuration updates. If you follow the
examples, you might find it interesting to switch to the source view. There you
can observe changes in the server.xml file after using the enhanced editor to
modify the server’s configuration.

1.2.3 Bootstrap properties

There is another configuration file, which is used by the Liberty profile server
when initializing the OSGi framework and platform core, called
bootstrap.properties. The bootstrap.properties file is an optional peer of the
server.xml file containing simple text properties as key=value pairs. Bootstrap
properties are generally used to influence early server start behavior or to define
machine-specific properties.

Chapter 1. An introduction to the Liberty profile 7

1.2.4 Portable configuration using variables
The Liberty profile configuration manager resolves variables when processing
configuration information. Using configuration variables allows
environment-specific attributes to be removed from the bulk of the server’s
configuration. This isolates general aspects of server or application configuration
from environment-specific elements such as host names, port numbers, or file
system locations.

The Liberty profile provides several predefined variables to help make server
configurations portable. The following list demonstrates syntax and briefly
summarizes the supported location variables:
wlp.install.dir This is the profile’s installation directory.
wlp.user.dir This directory is the root of the tree containing user
configuration. By default, this directory is a child of the
installation directory, ${wlp.install.dir}/usr. It can be
configured to an alternative location using an environment
variable when the server is started.
server.config.dir The server configuration directory contains the
server.xml file and any other optional configuration files
that are used to customize the server’s environment. The
name of this directory is used as the server’s name. By
default, this directory is a child of the user directory called
${wlp.user.dir}/servers/serverName.
server.output.dir The server output directory contains resources that are
generated by the server, such as logs. The Liberty profile
supports shared configurations, for example, multiple
running server instances sharing the configuration files.
Shared configurations are supported by allowing the
instance-specific output directory to be moved using an
environment variable when the server is started. By
default, the server output directory is the same as the
server’s configuration directory.
shared.app.dir Shared user applications directory,
${wlp.user.dir}/shared/apps.
shared.config.dir Shared user configuration directory,
${wlp.user.dir}/shared/config.
shared.resource.dir Shared user resources directory,
${wlp.user.dir}/shared/resources.

8 WebSphere Application Server Liberty Profile Guide for Developers

When specifying file or resource locations, use the most specific location variable
that applies. Being specific helps to ensure that your server configuration can be
propagated to other environments (a fellow developer’s notebook, a dedicated
test automation framework, a distributed production environment) without
requiring changes to the server.xml file.

Example 1-2 shows a simple bootstrap.properties file that defines custom

variables for machine-specific host and ports, and a common file location that is
based on one of the built-in location variables.

Example 1-2 A simple bootstrap.properties file

appCacheFile=${server.output.dir}/application/cache
hostName=*
httpPort=9082
httpsPort=9445

Figure 1-2 provides an example of a server.xml file that references the variables
from the bootstrap.properties file from Example 1-2.

Figure 1-2 Using variables in the enhanced editor

Chapter 1. An introduction to the Liberty profile 9

 The enhanced editor provides content assist for variables that are defined in
either the bootstrap.properties or server.xml files. Variables are filtered based
on the field being configured. If the field is for a number (integer, long, and so
on), the content assist list will show variables only with numeric values. This
context-sensitive variable filtering is shown in Figure 1-3.

Figure 1-3 Content assist will filter-defined variables

1.2.5 New configuration types and validation

The simple XML format that is used in server.xml uses intuitive, natural types to
make configuring the server more natural. For example, durations and timeouts
can be specified using strings containing units (specify 1m30s for 1 minute and
30 seconds).

The server is tolerant of configuration mistakes where possible. If the initial

configuration for the server is malformed, the server will not start, but indicates
where the syntax error occurred to help with correcting the problem. If the
configuration for a running server is updated with invalid syntax, the change is
not applied, and the server continues to run. It will also display a message
indicating where the configuration problem was so it can be corrected.
Subsequent updates to correct the error will be applied to the server without
requiring a server restart. A configuration that is provided for unknown or inactive
elements is ignored; you do not have to remove configuration for features that
are disabled.

10 WebSphere Application Server Liberty Profile Guide for Developers

 The following Information Center website provides an index describing all
configurable attributes of the run time:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
wlp.nd.doc/autodita/rwlp_metatype_4ic.html

1.2.6 Encoding passwords

Passwords can be specified as encoded strings to alleviate concerns about
using plain text passwords in configuration files. There are two ways to create
and specify an encoded password:
򐂰 The command line. You can use the securityUtility script in the
${wlp.install.dir}/bin directory:
securityUtility encode myPassword
This will return an encoded string, starting with “{xor}...”, to be copied
verbatim into your server.xml file.
(New in Version 8.5.5) The securityUtility script can be used to produce
passwords that are XOR-encoded, hash-encoded, or aes-encrypted. Run the
following help command for more information about the new
encoding options:
securityUtility help encode
򐂰 The enhanced editor. When the editor is used to configure passwords, a
standard password dialog box performs the same encoding step and sets the
attribute value to the resulting encoded string.

Chapter 1. An introduction to the Liberty profile 11

1.2.7 Shared configuration using includes
The Liberty profile also supports composed configuration. It is possible for the
server.xml file to include other files. Included files are specified using the
<include.../> directive, and must use the server.xml file’s syntax. Each
included file must also contain a <server.../> element. Figure 1-4 provides a
basic representation of how the configuration manager works with configuration
coming from various sources. Each bundle in the run time provides configuration
defaults and configuration metadata. The configuration manager reads this
information from each bundle and merges it with information read from the
server.xml file and any included files. The configuration manager will stop
processing, with an error, if any required configuration files cannot be found.

shared.xml
Config defaults
Config metadata

Kernel Bundle
more.xml

optional Config defaults

include Config metadata

<include optional="true" location="more.xml"/> Feature Bundle

<include location="shared.xml"/>

extra.xml

read default inject merged

configuration configuration

read user
<include location="extra.xml"/> configuration Configuration Manager
server.xml (OSGi Configuration Admin)

Figure 1-4 The configuration manager processing configuration metadata

Through the use of variables and included files, a wide variety of configuration
patterns becomes possible. Configuration can be shared across servers or
persisted in a source control repository at varying levels of granularity. For
example, a configuration that is associated with a data source can be collected
into a single XML file that is reused (as an included resource) across multiple
server configurations. The data source configuration can use variables (for
output directories, host names, ports, and so on) so that it can be applied directly
across multiple servers unchanged.

12 WebSphere Application Server Liberty Profile Guide for Developers

 Included files can be specified using full paths, paths with variables, or relative
paths. Relative paths are resolved by looking in a location relative to the parent
file, the server’s configuration directory, or the shared configuration directory (in
that order).

Include statements can appear anywhere within the <server.../> configuration

element, and each included file can include other files. To ensure that your
included configuration behaves predictably, you must be aware of the following
processing rules for included configuration files:
򐂰 Each included file is logically merged into the main configuration at the
position that the <include /> statement occurs in the parent file.
򐂰 For configuration instances such as applications or endpoints, a unique
configuration is created for each appearance of the element in the XML file.
An ID is generated if not otherwise specified.
򐂰 For singleton services, such as logging or application monitoring, entries are
processed in the order they appear in the file and later entries add to or
override previous ones. This is also true for configuration instances (an
application or data source) where the configuration instances have the
same ID.

1.2.8 Dynamic configuration updates

The Liberty profile contains an implementation of the OSGi Configuration Admin
service, which operates using the service patterns that are defined in that
specification. Per that specification, the Liberty profile configuration manager
does the following tasks:
򐂰 Maintains and manages the configuration of the OSGi Service Platform as a
whole. It sets the active configuration, at run time, for all
configurable services.
򐂰 Monitors the OSGi Service Registry and provides configuration information to
configurable services as they are registered.

At startup, the configuration manager processes the contents of the server.xml

file. It then merges those contents with the default values provided by each
bundle to provide configuration information to each registered configurable
service. If the server.xml file changes, the configuration manager will reprocess
the file contents and immediately push configuration changes out to the
configurable services affected by the change. There is no need to restart
the server.

Chapter 1. An introduction to the Liberty profile 13

 The configuration manager also responds dynamically as bundles are added or
removed from the system. For example, a new bundle might introduce additional
configurable services. When a bundle is started, the configuration manager:
򐂰 Detects new services.
򐂰 Resolves any user-provided configuration against the new configuration
metadata and defaults that are provided by the new bundle.
򐂰 Provides the resolved configuration to the consuming services.

Because the run time is dynamic, the configuration manager is tolerant when it
processes configuration information from any source (user or system). The
configuration manager will safely ignore configuration elements or attributes for
which it does not have metadata. For unknown attributes, the values are passed
to the associated configurable services along with the rest of its configuration
data. For unknown configuration definitions, the configuration manager parses
configuration information at the time it becomes available and provides it to
associated configurable services.

1.3 Runtime composition with features and services

The composable nature of the Liberty profile is based on the concept of features.
A feature is a unit of function, essentially the minimum set of bundles that are
required to support a particular technology. Features can, and do, overlap, and
they can include other features.

As an example, the servlet-3.0 feature installs the collection of OSGi bundles

required to support Servlet applications, but not JSP applications. The jsp-2.2
feature includes the servlet-3.0 feature (it requires a servlet engine). When you
enable the jsp-2.2 feature in a server, it installs all of the bundles that are
required for servlet applications in addition to the bundles required to support
JSPs (see Figure 1-5 on page 15).

14 WebSphere Application Server Liberty Profile Guide for Developers

 Liberty profile runtime
(OSGi framework)

monitor-1.0 jsf-2.0

jndi-1.0 jsp-2.2

Features ... servlet-3.0

Applications
appSecurity-1.0
Container
jdbc-4.0

Kernel

JDK 6.0+

Figure 1-5 Features are the units of composition for a Liberty profile server run time

1.3.1 Feature management

Features are configured in server.xml by adding <feature> elements to the
<featureManager../>. When a new server is created using the server create
command, the server.xml file has the jsp-2.2 feature enabled, as shown in
Example 1-3.

Example 1-3 Server.xml file with jsp-2.2 feature

<featureManager>
<feature>jsp-2.2</feature>
</featureManager>

Chapter 1. An introduction to the Liberty profile 15

 The WebSphere developer tools enhanced editor provides a list of features to
choose from and shows those features implicitly enabled by others, as shown in
Figure 1-6.

Figure 1-6 Selecting features with the enhanced editor

Features can be added or removed from the server configuration while the server
is running without requiring a server restart.

1.3.2 Automatic service discovery

The fit-to-purpose nature of the run time relies on dynamic behavior inherent in
the OSGi Framework and the Service Registry. The Liberty profile relies on the
OSGi Service Registry for dynamic registration and discovery of services.

When a feature is enabled, the bundles that are required by that feature are
installed in the OSGi framework. When a bundle is installed and started, in some
cases, services are registered in the Service Registry. For most bundles in the
Liberty profile, service registration and lifecycle are managed using OSGi
Declarative Services (DS) components.

16 WebSphere Application Server Liberty Profile Guide for Developers

 DS support operates on declared components, each of which is defined by an
XML file in the bundle. When a bundle containing component declarations is
added to the framework, DS takes action. It reads each component declaration
and registers provided services in the service registry. DS then manages the
lifecycle of the component by controlling its lifecycle based on a combination of
declared attributes and satisfied dependencies.

The simple XML description of components allows DS to resolve service

dependencies without requiring the component to be instantiated, or its
implementation classes to be loaded. All of this facilitates late and lazy resource
loading, which helps improve server startup and runtime memory footprint.

1.4 Frictionless application development

The Liberty profile can deploy applications in the following ways:
򐂰 As an archive file (WAR, EAR, or EBA)
򐂰 Extracted into a directory
򐂰 Described by an XML file (loose configuration)

There is no distinction between installing and starting an application, though

installed applications can be stopped and restarted.

By default, the Liberty profile will monitor deployed applications for changes.
Updates to static files (HTML, CSS, or JavaScript) or JSP files are detected and
served immediately. Changes to servlet classes cause an automatic restart of
the application.

Caution: For large applications, monitoring the file system for changes to an
application can be resource-intensive. Consider extending the monitoring
interval if you see excessive I/O activity while the server is running.
Application update monitoring should be disabled in production environments.
For information, see 8.1.1, “Turning off application monitoring” on page 182.

1.4.1 Quick start using dropins

By default, each server contains a monitored application directory named
dropins. When an application is placed in this directory, the server will
automatically deploy and start the application.

Chapter 1. An introduction to the Liberty profile 17

 There are several options for placing applications in the dropins directory. Each
provides a way for the server to determine the application type. The following list
describes the placement options:
򐂰 Place the archive file with its identifying suffix (ear, war, wab, and so on)
directly into the dropins directory:
${server.config.dir}/dropins/myApp.war
򐂰 Extract the archive file into a directory that is named with the application
name and the identifying suffix:
${server.config.dir}/dropins/myApp.war/WEB-INF/...
򐂰 Place the archive file or the extracted archive into a subdirectory that is
named with the identifying suffix:
${server.config.dir}/dropins/war/myApp/WEB-INF/...

1.4.2 Configuration-based application deployment

Explicitly declaring your application allows you to specify additional properties
such as the context root, alter application startup behavior, and so on. Explicitly
configured applications are recommended for production environments to allow
dropins monitoring to be disabled.

An application is declared in the server.xml file using the <application.../>

element, which supports the following attributes:
location The path to the application resource.
id A unique identifier for the application.
name A descriptive/display name for the application.
type The application type: WAR, EAR, or EBA. If this is not
specified, it will be inferred (if possible) from the
application file name.
context-root The context root of the application.
autoStart A Boolean value indicating whether the server should
start the application automatically. The default is true.

The location is the only required attribute for a declared application. It specifies
the location of the application resource (archive, extracted directory, or loose
configuration XML file) and can refer to any location in the file system. If the
specified location is a relative path, it is resolved first against
${server.config.dir}/apps and then against ${shared.app.dir}.

Example 1-4 on page 19 shows the terms for defining a web application in the
serverl.xml file.

18 WebSphere Application Server Liberty Profile Guide for Developers

 Example 1-4 Defining a web application in the server.xml file by using the application
element
<application context-root="helloworld" type="war" id="helloworld"
location="helloworld.war" name="helloworld"/>

(New in Version 8.5.5) Type-specific application elements can be used to simplify

the declaration of applications:
򐂰 <webApplication.../>
򐂰 <osgiApplication.../>
򐂰 <enterpriseApplication.../>

These elements are used in a manner identical to the generic

<application.../> element, but eliminate the type attribute, as the application
type is built into the shorthand of the element itself. The I<webApplication.../>
element also uses a contextRoot attribute instead of context-root. Example 1-4
and Example 1-5 show two equivalent declarations for an application, using the
<application.../> and <webApplication.../> elements.

Example 1-5 Defining a web application in the server.xml file by using the webApplication
element added in Version 8.5.5
<webApplication contextRoot="helloworld" location="helloworld.war" />

Update monitoring for declared applications has a configurable trigger. By

default, the file system is polled for changes. When you use the tools to develop
your applications, the tools change the update trigger from polled to mbean. This
allows the tools to influence when the server discovers updated files based on
when files are saved and whether they are actively being edited.

1.4.3 Using loose configuration for applications

In a loose configuration, an application can be distributed across arbitrary
locations on disk, and yet run as though it existed in a single, flat directory
structure. Tools such as Rational Application Developer and WebSphere
Application Server Developer Tools for Eclipse use loose configuration to allow
users to run their applications directly from the projects in their Eclipse
workspace. This saves disk space, improves performance, and gives developers
more immediate feedback when they make changes, because it avoids copying
files between the Eclipse workspace and the server definition.

Chapter 1. An introduction to the Liberty profile 19

1.4.4 Configuring an application’s context root
The context root is the entry point of a web application. The context root for an
application is determined using the following criteria in order of precedence:
1. The context root attribute of an application declared in server.xml
<application context-root=”rootOne” location=”...”/>, or
<webApplication contextRoot=”rootOne” location=”...”/>
2. The context-root element in the application.xml file in an EAR application
<context-root>rootTwo</context-root>
3. The context-root element in the ibm-web-ext.xml in a web application
<context-root uri="rootThree" />
4. The name of the declared web application in server.xml
<application name=”rootFour” ... />
5. The Web-ContextPath in the bundle manifest of an OSGi WAB
Web-ContextPath: /rootFive
6. The directory or file name of an artifact in the dropins directory
${server.config.dir}/dropins/war/rootSix
${server.config.dir}/dropins/rootSix.war

1.4.5 Compatibility with WebSphere Application Server

The Liberty profile is a part of WebSphere Application Server and shares core
technologies with the full profile. Applications that are developed on Version v8.5
of the Liberty profile will run on version v8.0 or v8.5 of the full profile. There are
differences between the Liberty profile and full profile. The differences are mostly
focused on the definition and use of classloading or shared libraries. Section 3.3,
“Controlling class visibility in applications” on page 88 provides an overview of
how classloading and shared library support work in the Liberty profile. That
overview gives special regard to management and use of third-party libraries.

Chapter 8, “From development to production” on page 181 describes strategies

for promoting applications that are developed using the Liberty profile to
production systems.

20 WebSphere Application Server Liberty Profile Guide for Developers

1.5 Product extensions (new in Version 8.5.5)
The Liberty profile supports direct extension of the run time by using product
extensions. A product extension allows custom content to be added to a Liberty
installation in a way that avoids conflicts with the base content of the product and
with other product extensions. A product extension is defined by using a simple
properties file in the ${wlp.install.dir}/etc/extensions/ directory named
<extensionName>.properties. This naming convention helps ensure that each
product extension has a unique name. The unique name, in turn, is used as a
prefix to avoid collisions when specifying extension-provided features and
configuration in the server.xml file.

Product extensions usually contain features and bundles, but can also contain
other things such as custom server templates or scripts. In general, the structure
of a product extension resembles the structure of a Liberty profile installation, as
shown in Figure 1-7 on page 22, particularly regarding the following items
򐂰 Bundles (in a lib/ directory),
򐂰 Features (in a lib/features/ directory),
򐂰 Server templates (in a templates/servers/ directory)

Creating a product extension is as simple as creating a properties file in the

${wlp.install.dir}/etc/extensions/ directory, which follows the naming
convention and contains the following two values:
򐂰 com.ibm.websphere.productId
A descriptive product ID, usually in the form of a reverse-qualified
domain name.
򐂰 com.ibm.websphere.productInstall
The absolute or relative location of the root product extension directory. If the
value of this property is a relative path, it is assumed to be a peer of the
Liberty installation directory, ${wlp.install.dir}.

Chapter 1. An introduction to the Liberty profile 21

 For convenience in development, the ${wlp.user.dir}/extension/ directory
functions as a default product extension, and uses, usr as its prefix in the
configuration. Figure 1-7 shows the Liberty profile installation with default and
product extension content.

Product Extension A (extensionA/)

README.TXT
bin/
Liberty profile installation (wlp/)
lib/
etc/extensions/ extA.bundle-1.0.jar
extA.properties lib/features/
extB.properties simpleTai-1.0.mf

Default Extension
Product Extension B (extensionB/)
usr/extension/lib/
usr.ext.bundleX-1.0.jar README.TXT
usr/extension/lib/features/ bin
usrExtFeature-1.0.mf lib/
extB.bundle-1.0.jar
lib/features/
blueprintExtension-1.0.mf
templates/servers/extBServer/
server.xml

Figure 1-7 A Liberty profile installation with default and product extension content

Example 1-6 provides a snippet of the server.xml file demonstrating how

prefixes are used when enabling extension-provided features. The prefix that is
used for Product Extension A from Figure 1-7 is extA, which matches the name
of the extA.properties file in ${wlp.install.dir}/etc/extensions that defines
the extension.

Example 1-6 Using extension-provided features in the server.xml file

<featureManager>
<feature>usr:usrExtFeature-1.0</feature>
<feature>extA:simpleTai-1.0</feature>
<feature>extB:blueprintExtension-1.0</feature>
</featureManager>

Section 9.2, “Defining a custom feature” on page 193 walks through creating and
packaging a custom feature as a subsystem archive (an *.esa file). Both the
featureManager command and the WebSphere developer tools provide
mechanisms for managing the features that are installed into product extensions.

22 WebSphere Application Server Liberty Profile Guide for Developers

For more information about product extensions, see the following Information
Center website:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
wlp.nd.multiplatform.doc/ae/cwlp_prod_ext.html

Chapter 1. An introduction to the Liberty profile 23

24 WebSphere Application Server Liberty Profile Guide for Developers
 2

Chapter 2. Installation
There are several ways to install the Liberty profile. In this chapter, we focus on
the installation methods that are most commonly used for setting up a
development environment.

The Liberty profile is designed for easy operation using the provided scripts and
direct editing of the server configuration XML files. The development tools
provide an integrated development environment (IDE) for application
development with plenty of assistance and short-cuts to aid creating, modifying,
and controlling Liberty profile servers. The development tools make development
easier but are not strictly required, and if you prefer, you can just install the
run time.

The chapter contains the following sections:

򐂰 Installing the WebSphere developer tools
򐂰 Installing the Liberty profile
򐂰 Configuring the server runtime JDK
򐂰 Starting and stopping a Liberty profile server

For additional installation methods, including installation for production, see the
following Information Center website:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
wlp.nd.multiplatform.doc/topics/twlp_inst.html

© Copyright IBM Corp. 2012, 2013. All rights reserved. 25

2.1 Installing the WebSphere developer tools
IBM WebSphere Application Server V8.5.5 Liberty Profile Developer Tools for
Eclipse is a lightweight set of tools for developing, assembling, and deploying
applications to the WebSphere Application Server V8.5.5 Liberty profile. These
tools should be installed into your Eclipse workbench. Additionally, you can use
IBM Rational Application Developer V9, which has IBM WebSphere Application
Server V8.5.5 Liberty Profile Developer Tools for Eclipse integrated.

For supported Eclipse versions and additional installation methods, see the
following Information Center website:
http://pic.dhe.ibm.com/infocenter/radhelp/v9/topic/com.ibm.rad.install.
doc/topics/t_install_wdt.html

2.1.1 Installation from Eclipse Marketplace

You can install IBM WebSphere Application Server V8.5.5 Liberty Profile
Developer Tools for Eclipse directly from the Eclipse Marketplace by completing
the following steps:
1. Start the Eclipse integrated development environment (IDE) for Java EE
Developers workbench.
2. Click Help  Eclipse Marketplace.
3. In the Find field, type WebSphere and then click Go.
4. In the list of results, locate IBM WebSphere Application Server V8.5.5
Liberty Profile Developer Tools for Eclipse and then click Install.
5. On the Confirm Selected Features page, expand the parent nodes and select
the features that you want to install. When you are finished, click Next.
The features that are available are the following ones:
– OSGi Application Development Tools
– Web Development Tools
– Web Services Development Tools
– WebSphere Application Server V8.5 Liberty Profile Tools
6. On the Review Licenses page, review the license and if you agree to the
terms, click I accept the terms of the license agreement. Then, click
Finish. The installation process then starts.

26 WebSphere Application Server Liberty Profile Guide for Developers

 Tip: During the installation, a security warning dialog box might open and
display the following warning:

“Warning: You are installing software that contains unsigned content. The
authenticity or validity of this software cannot be established. Do you want
to continue with the install?”

You can safely ignore the message and click OK to continue.

7. When the installation process completes, restart the workbench.

2.1.2 Installation from the WASdev community site

You can install the WebSphere developer tools using the links that are provided
on the WASdev community site if you are using Eclipse 3.7.2 or later. Use the
following steps to download the toolset:
1. Start the Eclipse IDE for Java EE Developers workbench.
2. Open your web browser to http://wasdev.net and click the download tab.
3. Select the WebSphere Application Server Developer Tools from the
downloads page, as shown in Figure 2-1.

Figure 2-1 Download selection page on WASdev.net

Chapter 2. Installation 27
 4. Locate WebSphere Application Server Developer Tools for Eclipse and
click Download for your version of Eclipse.
5. Locate the Install icon for WebSphere Application Server Liberty Profile, as
shown in Figure 2-2.

Figure 2-2 WASdev installation icon

6. Select and drag the Install icon to your Eclipse workbench and drop it onto
your toolbar.
7. On the Confirm Selected Features page, expand the parent node and select
the features that you want to install.
The features available are:
– OSGi Application Development Tools
– Web Development Tools
– Web Services Development Tools
– WebSphere Application Server V8.5 Liberty Profile Tools
When you are finished, click Next.
8. On the Review Licenses page, review the license and if you agree to the
terms, click I accept the terms of the license agreement. Then, click
Finish. The installation process then starts.

28 WebSphere Application Server Liberty Profile Guide for Developers

 Tip: During the installation, a security warning dialog box might open and
display the following warning:

“Warning: You are installing software that contains unsigned content. The
authenticity or validity of this software cannot be established. Do you want
to continue with the install?”

You can safely ignore the message and click OK to continue.

9. When the installation process completes, restart the workbench.

2.1.3 Installation from downloaded installation files

You can install the IBM WebSphere Application Server V8.5.5 Liberty Profile
Developer Tools for Eclipse into an existing Eclipse workbench. This is facilitated
by using that installation files that you download to your computer.

If you run the system disconnected from the Internet, Eclipse requires some
prerequisite files. For detailed instructions about how to perform this installation
and details about the additional prerequisite Eclipse files, see the following
Information Center website:
http://publib.boulder.ibm.com/infocenter/radhelp/v9/topic/com.ibm.rad.i
nstall.doc/topics/t_install_wdt.html

2.2 Installing the Liberty profile

To serve your applications, you must install the Liberty profile runtime
environment. The environment is the same whether you are using it for
development, test, or production. The WebSphere developer tools integrate with
the Liberty profile to give you a seamless, integrated development environment
that can aid you in developing and testing your applications.

2.2.1 Installation using the Liberty profile developer tools

The Liberty profile runtime environment can be installed directly from within the
Liberty profile developer tools. Installing in this manner also creates an
initial server.

Chapter 2. Installation 29
 Tip: During the configuration of the run time and server, you are prompted to
provide names for similar items, which can cause confusion. The following are
the names that you will be asked to define, in the order you encounter them:
Server Host Name The name of the machine running the server
or local host.
Server Name The name of the server as it will be known by
Eclipse. This should not be confused with the
actual server created in the Liberty profile.
Liberty Profile Server Name The name of the server that will be created in
the Liberty profile runtime environment. This
is your actual Liberty Profile Server.

The following steps for installing the Liberty profile and server assume that you
have already installed the tools that are described in 2.1, “Installing the
WebSphere developer tools” on page 26:
1. Start Eclipse with WebSphere developer tools installed (or Rational
Application Developer V9).
2. Select File  New  Other.
3. In the Wizards text box, type server. Select the Server icon and then click
Next, as illustrated in Figure 2-3.

Figure 2-3 Selecting the server installation wizard

30 WebSphere Application Server Liberty Profile Guide for Developers

4. Select WebSphere Application Server V8.5 Liberty Profile from the
available server list, as shown in Figure 2-4. Provide the Server’s host name
and the Server name that you want displayed in the workbench, and then
click Next.

Figure 2-4 Defining the Liberty profile for a new server

Chapter 2. Installation 31
 5. If you have already installed a Liberty profile runtime environment, you can
use the Browse button to select the Liberty profile runtime installation location
and continue with step 10 on page 34. This example does not have a Liberty
runtime environment that is installed, so you must install one. To do so, click
the Download or install link, as shown in Figure 2-5.

Figure 2-5 Download or install a new runtime environment

32 WebSphere Application Server Liberty Profile Guide for Developers

6. If you have previously downloaded a Liberty profile runtime archive file from
IBM Passport Advantage® or WASdev.net, you can select the downloaded
archive using the first option. In our example, we are downloading directly
from the IBM website. We chose the second option and click WebSphere
Application Server V8.5 download site and then click Next (Figure 2-6).

Figure 2-6 Download from the IBM site

Chapter 2. Installation 33
 7. On the Install Add-ons page, select any additional features that you want
added to your server installation. The additional features include open source
packages and the extended version of the Liberty profile, which adds extra
capabilities, including JMS and Web Services. Click Next, as shown in
Figure 2-7.

Figure 2-7 Install optional server add-ons

8. Accept the License agreements, and then click Next.

9. When you are prompted for the installation folder, select the folder that you
want to install the Liberty profile runtime environment into, and then click
Finish. The Liberty profile runtime environment is downloaded and installed.
10.After installation, the wizard returns to the New Server Runtime Environment
page, as shown in Figure 2-5 on page 32. Click Next to continue. Optionally,
you can choose the JRE that you want the Liberty profile to use.
11.Now that you have a runtime environment, you are prompted to select the
Liberty profile server to use. If you have a Liberty profile server that is already
defined, select it from the drop-down list and proceed to step 12 on page 35.
If there is no Liberty profile server that is defined, you are prompted to create
a Liberty profile server. Enter the name for your new Liberty profile server and
click Finish. A server is created under your runtime environment.

34 WebSphere Application Server Liberty Profile Guide for Developers

 12.When setup is complete, you see the new server and runtime environment
displayed in the Servers view of your workbench. Figure 2-8 shows the newly
created server that is expanded.

Figure 2-8 The new server shown in the Servers view

2.2.2 Installation using the command line

If you have obtained the Liberty profile runtime environment from WASdev.net or
through Passport Advantage, you have downloaded a JAR file. The JAR file has
a name similar to wlp-developers-runtime-8.5.0.0.jar. Always download the
latest version.

Note: If you obtained an edition other than the developers edition, the file
name contains your edition name rather than developers.

Installing the runtime environment

To install the Liberty profile, you must extract the archive file by completing the
following steps:
1. Run the following command to extract the contents of the Liberty archive:
java -jar wlp-developers-runtime-8.5.0.0.jar
2. Press x to skip reading the license terms or press Enter to view them.
3. Press Enter to view the license agreement.
4. Press 1 if you agree to the license terms and are ready to proceed.
5. Provide the installation path for the Liberty profile, for example:
C:\IBM\WebSphere
6. Press Enter.

The server is installed into a wlp directory within the install directory that is
specified in step 5. If you did not specify an installation location, it installs to the
current directory.

Chapter 2. Installation 35
 Creating a server
The Liberty profile runtime environment does not come with a server defined. To
create a server, you must run the following command from the Liberty profile bin
directory (wlp/bin):
server create <server name>

This creates a server, with the provided name, in the usr/servers directory.

Tip: A Liberty profile runtime environment can contain multiple servers. You
do not need to install multiple run times onto a machine to run
multiple servers.

Server name is an optional parameter. If you do not specify a server name,

defaultServer is used.

Adding the new server and runtime environment into the tools
To use the Liberty profile developer tools with your new runtime and server, you
must add them into the tools. This can be done by following the instructions in
2.2.1, “Installation using the Liberty profile developer tools” on page 29. Then,
select your run time and server at the relevant steps.

2.2.3 Installation on z/OS

IBM Installation Manager is used to install the Liberty profile on z/OS using a part
of the com.ibm.websphere.zOS.v85 package offering. To install the Liberty
profile, install this package with the Liberty feature by running the following
imcl command:
/usr/lpp/InstallationManager/V1R5/tools $ imcl install
com.ibm.websphere.zOS.v85,liberty -installationDirectory
/usr/lpp/zWebSphere/V8R5 -repositories
/usr/lpp/InstallationManagerRepository/HBBO850 -acceptLicense

The following folders are created during the installation process:

򐂰 bin
򐂰 java64
򐂰 lib
򐂰 wlp
򐂰 java
򐂰 lafiles
򐂰 properties

36 WebSphere Application Server Liberty Profile Guide for Developers

 If only core.feature is selected, which is the default, the Liberty profile is not
installed. If core.feature is selected along with the Liberty profile feature, then
both WebSphere Application Server and Liberty profile are installed.

After the WebSphere Application Server is installed without Liberty, it is not

possible to add the Liberty profile feature. You get an exception, which is shown
in Example 2-1.

Example 2-1 Error adding Liberty profile to existing WebSphere Application Server
installation on z/OS
CRIMA1155E ERROR: Error modifying.
ERROR: The WebSphere Application Server and WebSphere Application
Server Liberty Profile features cannot be added to or removed from an
existing package group after installation.

Installation Manager cannot modify the application server features of an existing

package group. To add features, use Install and include them in a new package
group. To remove features, use Uninstall to completely remove the entire
package group.

Important: On z/OS, create your Liberty server configurations in a location

independent of the installed Liberty profile. Do not use the usr subdirectory
(wlp/usr).

2.2.4 The Liberty profile runtime environment and server

directory structure
The location of the various files and directories that make up the Liberty profile
runtime environment and server are important. You must become familiar with
these files to configure and deploy applications to the server.

Chapter 2. Installation 37
 Runtime directory structure
Figure 2-9 provides an overview of the directory structure that is used by the
Liberty profile runtime environment. The directory structure and location of files
are essential for the healthy running of your servers.

Figure 2-9 The Liberty runtime directory structure

Here are the most important Liberty runtime directories:

򐂰 bin
This directory contains scripts that are used to manage the Liberty profile
server and server instances
򐂰 etc
This directory is optional. It can be used for customization of the whole Liberty
profile installation. The configurations that are defined by files in this directory
apply to all Liberty profile servers.
򐂰 lib
This directory contains the Liberty runtime libraries.
򐂰 templates
This directory contains sample configuration files and a sample server.xml
file for the Liberty profile.

38 WebSphere Application Server Liberty Profile Guide for Developers

򐂰 usr
This directory contains the server instances with their configuration and
applications and any resources that can be shared between servers. The usr
directory is user-owned and as such is not modified by any service releases.

Server directory structure

Similar to the runtime directory structure, it is essential that you become familiar
with the location and layout of the Liberty profile server files and directories, as
shown in Figure 2-10.

Figure 2-10 The Liberty server directory structure

Here are the most important Liberty profile server directories:

򐂰 apps
This directory is optional. It can contain deployed applications or application
descriptors if they are deployed using the WebSphere developer tools.
򐂰 dropins
Applications can be added and removed to the liberty server simply by
dropping them into this folder. This directory is constantly monitored by the
server to identify any changes and add or remove an application when the
changes occur.

Chapter 2. Installation 39
 򐂰 logs
Contains the logs that are produced by the Liberty profile server. By default,
this is the place where the trace or message logs are written. It also contains
the First Failure Data Captures (FFDC).
򐂰 resources
Contains additional resources for the Liberty profile server instance. For
example, keystores that are generated by the Liberty profile server are in
this directory.
򐂰 tranlog
Contains the transactional logs that are produced by the server run time and
the applications. The transactional logs are used to commit or roll back
transactional resources in the event of server failure.
򐂰 workarea
Contains the Liberty profile server operational files; is created during the first
server run.

2.3 Configuring the server runtime JDK

The Liberty profile requires a Java Runtime Environment (JRE) to run in. The
Liberty profile server runs on Java version 6 or above provided by any vendor. A
full list of supported Java versions is noted in the following System Requirements
document:

http://www-01.ibm.com/support/docview.wss?rs=180&uid=swg27028175

The following sections describe the ways that you can define which JRE is used.

2.3.1 Defining the JRE from within workbench

When running a server through the workbench, the JRE to be used is defined in
the server properties. When you created the server in Eclipse, you could define
the JRE. To change the JRE, complete the following steps:
1. Switch to the Servers view in the workbench.
2. Right-click your server and select Open, as shown in Figure 2-11 on page 41.

40 WebSphere Application Server Liberty Profile Guide for Developers

 Figure 2-11 Opening a Server Properties window

3. Select the Runtime Environments link, as shown in Figure 2-12.

Figure 2-12 Opening the Runtime Environment properties

4. A window is displayed allowing you to change the runtime environment,

including changing your JRE. After you are satisfied with your changes,
click Finish.
5. Save the changes to the Server properties. The new settings are used when
you next start the server.

Caution: If you created a server.env file that defines the JRE (either for the
server or for the run time) this takes preference over the Eclipse setting. You
must remove this file in order for the Eclipse setting to work.

Chapter 2. Installation 41
2.3.2 Configuring the system JRE
When starting the Liberty server using the command line, the server must know
where to find its JRE. In the absence of any server or runtime configuration files
that define the JRE, the system JRE is used.

On Windows systems, you can use Example 2-2 to set the JAVA_HOME
property, so the Liberty server uses your own JRE installation directory.

Example 2-2 Setting the JRE for Liberty on Windows

set JAVA_HOME=C:\IBM\jre6
set PATH=%JAVA_HOME%\bin;%PATH%

On Linux Systems, you can use Example 2-3 to set the JAVA_HOME property.

Example 2-3 Setting the JRE for Liberty on Linux

export JAVA_HOME=/opt/IBM/jre6
export PATH=$JAVA_HOME:$PATH

The Liberty profile runtime environment searches for the Java command in the
following order of properties: JAVA_HOME, JRE_HOME, and PATH.

2.3.3 Using server.env to define the JRE

The server.env file is a Liberty profile-specific configuration file that can be used
to define the JRE for the servers to use. When you install the Liberty profile this
configuration file does not exist, so you must create it. Create the file in one of
the following locations:
򐂰 ${wlp.install.dir}/etc/server.env
The settings here apply to all servers in the runtime environment.
򐂰 ${server.config.dir}/server.env
These settings are specific to the server containing the file. This server.env is
used in preference to the runtime level when both exist.

To define the JRE, add the following line into the server.env file:
JAVA_HOME=<path to your JRE>

You can use the server.env file to provide any other additional environment
variables that your server might need.

42 WebSphere Application Server Liberty Profile Guide for Developers

 Caution: The server.env files support only key=value pairs. Variable
expansion is not supported.

2.3.4 Specifying JVM properties

You can use the jvm.options files at the runtime and server levels to specify
jvm-specific start options, for example, -X arguments. The options are applied
when you start, run, or debug the server. Be sure to specify only one option
per line.

When you install the Liberty profile, this configuration file does not exist, so you
must create it. Create the file in one of the following locations:
򐂰 ${wlp.install.dir}/etc/jvm.options
The settings here apply to all servers in the run time.
򐂰 ${server.config.dir}/jvm.options
These settings are specific to the server containing the file. This jvm.options
file is used in preference to one at the runtime level when both exist.

2.4 Starting and stopping a Liberty profile server

You can control the state of the Liberty profile server either from the command
line or through the workbench. We describe the two methods in this section.

2.4.1 Starting and stopping the server using the command line
The server can be controlled from a single server command that is in the
${wlp.install.dir}/bin directory. The following commands can be used to start
and stop the server:
򐂰 server start <servername>
Starts the server running in the background
򐂰 server run <servername>
Starts the server running in the foreground and writes the console output to
the window. To stop the Liberty profile server in this mode, press Ctrl+c or kill
its process or run server stop from another command window.
򐂰 server debug <servername>
Starts the server in debug mode.

Chapter 2. Installation 43
 򐂰 server stop <servername>
Stops the server.
򐂰 server status <servername>
Displays the current state of the server.

Hint: If workbench is open and it has the Liberty profile server already defined,
it automatically updates. Updates reflect the status of the server and show the
output from the server in the console window.

2.4.2 Starting and stopping the server from the workbench

You can control the state of the Liberty profile server from directly within the
workbench. This can be done from the Server view. Either right-click the server
and select the required option, or click the icons that are attached to the Server
view, as shown in Figure 2-13.

Figure 2-13 Starting the server using the start button

The following buttons are available to control the server:

Starts the server in debug mode.
Starts the server.
Stops the server.

44 WebSphere Application Server Liberty Profile Guide for Developers

 3

Chapter 3. Developing and deploying

web applications
IBM WebSphere Application Server V8.5 Liberty Profile provides a simplified
environment for developing and deploying applications. Whether working in the
Liberty profile developer tools or in a third-party text editor, you can quickly build,
run, and update applications. Development impact, such as configuration and
server restarts, are kept to a minimum to reduce the amount of time it takes to
develop new applications. In this chapter, we describe the benefits of developing
applications in the Liberty profile environment.

The chapter contains the following sections:

򐂰 Developing applications using the Liberty profile developer tools
򐂰 Developing outside the Liberty profile developer tools
򐂰 Controlling class visibility in applications

© Copyright IBM Corp. 2012, 2013. All rights reserved. 45

3.1 Developing applications using the Liberty profile
developer tools
The Liberty profile developer tools provide a lightweight, rich environment for
developing applications. Using the Liberty profile developer tools simplifies the
creation of applications by providing wizards and graphical design tools for Java
EE applications. Server configuration tasks are simplified using the tools. In
many cases, the tools can infer what configuration is needed based on the
application and update it automatically. Working in the Liberty profile developer
tools environment also enables iterative development by republishing
applications when you make changes in the integrated development
environment (IDE).

In this section, we describe an iterative development scenario involving several

technologies that are supported by the Liberty profile server.

3.1.1 Using the tools to create a simple servlet application

In this section, we describe how to develop and deploy a simple servlet
application using either the Liberty profile developer tools or a simple text editor.
Following the procedure that is described in this chapter shows the simplicity of
developing and updating applications in the Liberty environment.

Liberty profile supports the Java EE Servlet 3.0 API. This book assumes some
knowledge of Java EE technologies, so the actual coding of the example servlet
is not described here.

The Liberty profile developer tools provide a rich development environment for
building web applications. In this section, we take you through the end-to-end
process of developing, deploying, and updating an application.

Getting started
Before you begin, make sure that you have installed the Liberty profile server
and tools as described in 2.1, “Installing the WebSphere developer tools” on
page 26. The following steps outline how to create a new project for later
deployment:
1. Begin by creating a web project in the Liberty profile developer tools by using
the Create a Web Project wizard from the toolbar, as shown in Figure 3-1 on
page 47.

46 WebSphere Application Server Liberty Profile Guide for Developers

 Figure 3-1 Selecting the Create a Web Project wizard

2. In the first window, give the project the name ITSOWeb and select the
Simple project template. Leave Programming Model as the default value,
Java EE. Clicking Next takes you to the Deployment options.
3. Under Target Runtime, make sure that WebSphere Application Server V8.5
Liberty Profile is selected. Leave all other options as the default values, and
click Finish. Accept the option to switch to the web perspective if you are
prompted to do so.

Building a servlet application

Now add a servlet to the ITSOweb web project by completing the following steps:
1. Begin by creating a servlet by using the Create Servlet wizard.
a. To start the wizard, right-click your ITSOWeb project in the Enterprise
Explorer window and select New  Servlet.
b. Use com.itso.example for the package name and HelloITSO for the servlet
class name. All other values can be left at the defaults.

Chapter 3. Developing and deploying web applications 47

 The window in Figure 3-2 shows the Create Servlet wizard.

Figure 3-2 Create Servlet wizard

2. After finishing the wizard, the HelloITSO.java file is included in the ITSOWeb
project. Open the file and add some simple output to the servlet’s doGet
method. Figure 3-3 shows an example doGet method.

Figure 3-3 Example doGet method for the HelloITSO servlet

48 WebSphere Application Server Liberty Profile Guide for Developers

 For more information about developing servlets and other dynamic web content,
see the Liberty profile developer tools at the following Information
Center website:
http://publib.boulder.ibm.com/infocenter/radhelp/v9/topic/org.eclipse.w
st.webtools.doc.user/topics/twsrvwiz.html

Deploying the application

Before deploying the application, ensure that you created a Liberty Profile Server
in the development environment as described in 2.2.1, “Installation using the
Liberty profile developer tools” on page 29. To deploy the application, complete
the following steps:
1. In the Servers view, locate your Liberty Profile Server. Right-click the server
and select Add and Remove.
2. In the resulting window, select the ITSOWeb project and click Add, then click
Finish. The web project is now available on the server. You should see
output similar to Figure 3-4 in the console. If your server is not started, start
your server. The application was automatically assigned the context root
matching the project name of ITSOWeb. The application start is fast.

Figure 3-4 Output from deploying an application

Result: Note the extreme speed of the application start and that it was
automatically assigned the context root matching the project name of
ITSOWeb.

Verifying the application

To verify the application, open a web browser and go to:
http://localhost:9080/ITSOWeb/HelloITSO

You should see the following output syntax:

Hello, Liberty developer

Chapter 3. Developing and deploying web applications 49

 Updating the application
The Liberty profile server supports hot deployment for all applications. To verify,
change the servlet to output a different message in its doGet method. When you
save the file, the changes automatically are published to the server. In the
console output, notice that the application was stopped, updated, and made
available again almost instantaneously. Verify that your changes are active by
visiting the HelloITSO page again.

3.1.2 Developing and deploying a JSP application

The Liberty profile server supports the JavaServer Pages (JSP) 2.2 specification.
JSP allows you to separate presentation logic from your business logic.

The procedure for creating and deploying a JSP in the Liberty profile developer
tools is similar to the procedure for a servlet. Complete the following steps:
1. Begin by creating a new JSP file by right-clicking the ITSOWeb project and
selecting New  JSP File.
2. Enter ITSOWelcome.jsp for the name of the page and click Next.
3. On the Select JSP template window, make sure that the template New JSP
File (HTML) is selected and click Finish.
4. The ITSOWelcome.jsp page automatically opens in the Rich Page editor. By
default, the editor displays a split view that shows both the JSP source and a
preview of the output.
Insert some text into the source editor between the body tags. Notice that the
preview pane is automatically updated. Figure 3-5 on page 51 shows the JSP
editor after adding a form to submit a simple input value to the
HelloITSO servlet.

50 WebSphere Application Server Liberty Profile Guide for Developers

Figure 3-5 Editing the ITSOWelcome JSP file

The Rich Page editor contains several powerful features that are beyond the
scope of this book. For more information, see the following Information
Center website:
http://publib.boulder.ibm.com/infocenter/radhelp/v9/topic/com.ibm.et
ools.rpe.doc/topics/crpe.html

Chapter 3. Developing and deploying web applications 51

 5. Because the ITSOWeb project is already deployed to the ITSO Example
Server, there are no extra steps that are needed to deploy and test the new
JSP file. However, to test the JSP file, which is shown in Figure 3-5 on
page 51, open the HelloITSO servlet again and add an implementation for the
doPost method. For example, the code, which is shown in Figure 3-6, outputs
a message using the value of the JSP’s input field. When you are finished
editing the servlet, save and close the file. Notice that the application
automatically is updated on the server.

Figure 3-6 Example doPost implementation for the HelloITSO servlet

6. To test the application, enter the link in to your web browser:

http://localhost:9080/ITSOWeb/ITSOWelcome.jsp
You should be able to submit a value in the JSP file and see the output
message from the servlet that reflects the value that is given in the input field
of the JSP.

3.1.3 Developing and deploying a JSF application

JavaServer Faces (JSF) simplifies the development of user interfaces for web
applications by providing the following features:
򐂰 Templates to define layout
򐂰 Composite components that turn a page into a JSF UI component
򐂰 Custom logic tags
򐂰 Expression functions and validation
򐂰 Component libraries
򐂰 XHTML page development

For more information about JSF and the features it provides, see the
following website:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
nd.multiplatform.doc/ae/cweb_javaserver_faces.html

52 WebSphere Application Server Liberty Profile Guide for Developers

JSF tools
The Liberty profile developer tools provide a rich development environment for
building high-quality JSF applications. In this section, we describe a simple JSF
application using JSP files, a managed bean, and navigation rules. For more
information about the powerful features that are provided by the JSF tools, see
the following Information Center website:
http://publib.boulder.ibm.com/infocenter/radhelp/v9/topic/com.ibm.etool
s.jsf.doc/topics/tjsfover.html

Enabling JSF in a web project

To enable JSF in a web project, right-click the project and select Properties.
Click Project Facets and enable JavaServer Faces, as shown in Figure 3-7.
Click OK to close the properties.

Figure 3-7 Enabling JSF in a web project

Feature enablement
To reduce the impact and resource usage, the Liberty profile server enables only
features that are actively being used. When you create a server using the Liberty
profile developer tools, the configuration automatically is updated to enable
servlets and JSPs. By default, the JSF application run time is not enabled. The
server configuration must be updated to run JSF applications.

Chapter 3. Developing and deploying web applications 53

 When you add applications to the server or update the facets of a project that is
deployed to the server, the Liberty profile developer tools try to determine what
features should be enabled on the server to support the application. If you
update the project to add the JSF facet, the tools prompt you to add the jsf-2.0
feature to the Liberty profile server, as shown in Figure 3-8.

Figure 3-8 JSF feature enablement

You can verify that this took place by opening the server.xml file and confirming
that <feature>jsf-2.0</feature> was added. Also, the console output shows
that the jsf-2.0 and beanvalidation-1.0 features were installed to the server, as
shown in Figure 3-9.

Figure 3-9 Console output after JSF feature enablement

Building a JSF application

Now that JSF is enabled in your web project, begin creating a JSF application by
opening the WebContent/WEB-INF/ faces-config.xml file for editing in the Faces
Config editor.

54 WebSphere Application Server Liberty Profile Guide for Developers

 Adding a managed bean and set properties
Complete the following steps to add a managed bean:
1. On the ManagedBean tab, click Session and then click Add to add a session
scoped managed bean.
2. In the resulting window, click Create a new Java class for the managed
bean.
3. In the following window, create a class named UserManagedBean in the
com.itso.example package.
4. Go through the remaining windows in the managed bean wizard by clicking
Next and then Finish.

Figure 3-10 shows the ManagedBean configuration after the wizard finishes.

Figure 3-10 ManagedBean configuration for UserManagedBean

Now that the managed bean is added, complete the following steps to edit the
userManagedBean class:
1. Open the UserManagedBean class for editing.
2. Add String fields named user and location.
3. Add a getter and setter for both fields.
4. Add a method named clear that sets both fields to null and returns the
string “clear”.

Chapter 3. Developing and deploying web applications 55

 5. Add a method that is named submit that simply returns the string “submit”.

Example code for the userManagedBean class is shown in Figure 3-11.

Figure 3-11 Example UserManagedBean code

To further edit the properties of the managed bean, complete the following steps:
1. Go back to the Faces Config editor for the managed bean. You can set initial
values for the managed bean’s properties by clicking Add under the
Initialization section.
2. From the property name drop-down menu, select the Name property. In the
value field, enter Liberty User (Figure 3-12 on page 57).

56 WebSphere Application Server Liberty Profile Guide for Developers

 Figure 3-12 Adding a Managed Property

3. Repeat the process for the location property. In the value field, enter Liberty
User Location.

Adding JSF-enabled JSP files

Create three JSP files, input.jsp, visit.jsp, and goodbye.jsp vy using the
Create JSP wizard. To create each file, in the wizard’s template selection page,
select New JavaServer Faces (JSF) Page (html).

The input.jsp file asks for two input parameters, a name and a location. The
values are taken from the managed bean userManagedBean. Figure 3-13 shows
example code to accomplish this process.

Figure 3-13 Example code for input.jsp

Chapter 3. Developing and deploying web applications 57

 The visit.jsp file outputs the name and location value from the
userManagedBean. It then displays a button to return to the previous page, and
a button to quit the application. Figure 3-14 shows example code for visit.jsp.

Figure 3-14 Example code for visit.jsp

The goodbye.jsp file outputs the name and have a command button that allows
you to start over. Example code is shown in Figure 3-15.

Figure 3-15 Example goodbye.jsp file

Adding navigation rules and setting outcome properties

To add navigation rules, complete the following steps:
1. In the Faces Config editor, click the tab that is labeled Navigation Rule. Drag
each of the three JSP files you created in the editor.
2. Create links between the files. If the palette is not already displayed, select
Window  Show View  Palette. On the palette, click Link, and then click
the input.jsp file. End the link by clicking the visit.jsp file. You should now
see an arrow pointing from input.jsp to visit.jsp.
3. On the palette, click Select and then click the new link and view the
properties in the properties view. If the properties view is not available, select
Window  Show View  Properties. In the from outcome field of the
properties, enter submit.
4. Follow the same procedure to create a link between the visit.jsp file and the
goodbye.jsp file, and set the outcome field to goodbye.
5. Create a link between the goodbye.jsp file and the input.jsp file, and set the
outcome property to clear.
6. Finally, create a link from the visit.jsp file back to the input.jsp file and set
the outcome to clear.

58 WebSphere Application Server Liberty Profile Guide for Developers

 Figure 3-16 shows the navigation rule window after all the rules are created.

Figure 3-16 JSF navigation rules

Testing the application

Access the application by visiting:
http://localhost:9080/ITSOWeb/faces/input.jsp

Result: Notice how the managed bean fields were initialized without having to
add code in the JSP. Also, notice that the application navigates to the correct
pages based on the navigation rules without having to embed navigation logic
in the JSP files.

3.1.4 Developing and deploying JAX-RS applications

The Java API for RESTful Web Services (JAX-RS) simplifies the development of
applications that use Representational State Transfer (REST) principles.

Chapter 3. Developing and deploying web applications 59

 More information about JAX-RS is available at the following website:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
nd.multiplatform.doc/ae/cwbs_jaxrs_overview.html

Building a simple JAX-RS application

To build and configure a JAX-RS application in the Liberty profile developer
tools, complete the following steps:
1. To enable the JAX-RS facet on the web project, right-click the project and
select Properties. Click Project Facets and enable JAX-RS by selecting the
check box next to JAX-RS (REST Web Services), as shown in Figure 3-17.

Figure 3-17 Web project facet list

2. After you select the check box next to JAX-RS (REST Web Services), you
see a red circle below the window with a note that further configuration
is required.
3. Clicking the note opens a window with various configuration options for
JAX-RS. You can leave all of the values on this window as their defaults and
click OK. If you open the web.xml file for the web project, you notice that a
servlet and servlet mapping were added for JAX-RS.

Feature enablement
Enabling the facet prompts you to enable the jaxrs-1.1 feature on the server. As
with JSF, the Liberty profile server does not load the JAX-RS run time unless it is
actively being used. Click Yes to enable the feature. If you load the server.xml
file, in the source view, you notice that <feature>jaxrs-1.1</feature> now is
added to the list of feature definitions.

60 WebSphere Application Server Liberty Profile Guide for Developers

Creating an application class
A JAX-RS application class is used to define the classes that are used in the
application. Create one now by creating a new Java class that extends
javax.ws.rs.core.Application. The class should contain a getClasses()
method that returns the classes that are involved in the application, as shown in
Figure 3-18.

Figure 3-18 JAX-RS application class

Creating the ITSOJaxrsExample class

To create the class for your JAX-RS, complete the following steps:
1. Create a Java class named ITSOJaxrsExample or import the class that is
included in the download material for this book. For more information see
Appendix A, “Additional material” on page 215.
2. The class must be annotated with @Path(“/example”) to indicate that the
class is used with requests to ITSOWeb/jaxrs/example.
3. Add a method that is called getString that returns a javax.ws.rs.Response
object. The method must be annotated with @GET. Also, add a method that is
called postString that takes a string as a parameter and returns a response
object. The postString method should be annotated with @POST.

Chapter 3. Developing and deploying web applications 61

 Figure 3-19 shows an example of the completed class.

Figure 3-19 JAX-RS resource class

Adding a servlet initialization parameter

The servlet that was added when we updated the web project to enable the
JAX-RS facet must know about your application class. This is done by creating
an initialization parameter for the JAX-RS Servlet. To create an initialization
parameter, complete the following steps:
1. Open the web.xml file in the design editor and right-click JAX-RS Servlet.
2. Select Add  Initialization Parameter.
3. On the resulting details window, enter javax.ws.rs.Application in the name
field and the name of your Application class in the value field, as shown in
Figure 3-20.

Figure 3-20 Creating an initialization parameter for the JAX-RS servlet

Testing your application

Open a web browser and visit:
http://localhost:9080/ITSOWeb/jaxrs/example

62 WebSphere Application Server Liberty Profile Guide for Developers

 You should see the output Hello ITSO from JAX-RS.

Note: When you access web applications with JAX-RS enabled, you might
see the error, which is shown in Example 3-1, displayed in the console output.
This message does not represent a functional error and can be safely ignored.

Example 3-1 Error message with JAX-RS enabled

[ERROR ] An exception occurred during processing of the
org.apache.wink.server.internal.providers.exception.EJBAccessExceptionM
apper class. This class is ignored.

3.1.5 Using Context and Dependency Injection in web applications

with the Liberty profile developer tools
By using the Context and Dependency Injection (CDI) feature of Java EE 6, you
can inject resources into your applications. Previous versions of Java EE could
inject certain resources, such as EJBs or a Persistence Context, but the CDI
specification allows for more general-purpose resource injection.

CDI also helps manage the lifecycle of beans through annotations. Beans can be
defined to live for the life of a request, session, application, or conversation.

For more information about CDI, see the following Information Center website:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
zseries.doc/ae/cweb_cdi.html

Use the procedure that is outlined in the rest of this section to create a simple
faces application that uses JavaBeans that are injected by CDI.

Enabling the CDI project facet

Enable the CDI project facet by completing the following steps
1. Right-click the ITSOWeb project and select Properties. In the window that
opens, click Project Facets.

Chapter 3. Developing and deploying web applications 63

 2. Enable the CDI project facet by selecting the check box next to Context and
dependency injection (CDI), as shown in Figure 3-21. This creates a file
named beans.xml in the web project. You can find it under WebContent 
WEB-INF.

Figure 3-21 Enabling the CDI project facet

Creating a simple bean class

Create a Java class named InjectedBean or import the class that is included in
the download material for this book. The class should be annotated with
@javax.enterprise.context.RequestScoped to indicate that the bean’s lifecycle
is only as long as a single request.

The InjectedBean class should contain one method, getHello(), which simply
returns the string “Hello from the injected bean”. The completed class should
look like the example in Figure 3-22 on page 65.

64 WebSphere Application Server Liberty Profile Guide for Developers

Figure 3-22 The InjectedBean class

Creating another managed bean class

Now, create a Java class named ExampleBean that uses the InjectedBean to
return a value. Add the following actions to the class implementation:
򐂰 The @javax.enterprise.context.RequestScoped annotation should be added
to the class to indicate the bean’s lifecycle.
򐂰 The annotation @javax.inject.Named(“itsoBean”) should be added to the
class to indicate that clients can access this managed bean by the
name itsoBean.
򐂰 The class should have a field of type InjectedBean. The field should be
annotated with @javax.inject.Inject to indicate that the value is injected by
the container.
򐂰 The class should have a single method, getMessage() that simply returns the
value of injectedBean.getHello().

The completed class should look like the example in Figure 3-23.

Figure 3-23 The ExampleBean class

Creating a JSP file to use the managed beans

Create a JSP named cdiExample.jsp by using the Create JSP wizard. In the
wizard’s template selection window, click New JavaServer Faces (JSF)
Page (html).

Chapter 3. Developing and deploying web applications 65

 In the body of the new JSP file, add an outputText element that has a value of
#{itsoBean.message}, as shown in Example 3-2. Earlier, you annotated the
ExampleBean class with @javax.inject.Named(“itsoBean”), so the value for the
outputText element is populated with the results of calling getMessage() on an
ExampleBean instance.

Example 3-2 Outputting the bean value in cdiExample.jsp

<body>
<f:view>
<h:outputText value=”#{itsoBean.message}”/>
</f:view>
</body>

Testing the application

Test the web application by visiting the link:
http://localhost:9080/ITSOWeb/faces/cdiExample.jsp

Result: You should see the output (Hello from the injected bean). Your
web application did not have to directly instantiate either the ExampleBean or
the InjectedBean class.

3.1.6 Developing Java Message Service web applications with the

Liberty profile developer tools
Using the Java Message Service (JMS) API, you can send messages between
Java EE components. It allows you to develop applications with loosely coupled
communication between components. JMS is supported by WebSphere Liberty
Profile, but it is not supported by the WebSphere Liberty core edition.

The WebSphere Liberty profile provides an embedded messaging server that

allows applications to act as a JMS server. Your applications can also act as
JMS clients for another WebSphere Liberty profile instance or for an external
WebSphere MQ server. WebSphere Liberty profile server supports both the point
to point model and the publish and subscribe model.

Use the procedure that is outlined in the rest of this section to create a web
application that uses the JMS publish and subscribe model. If you are using
Liberty core edition, you cannot compile this application in the Liberty profile
developer tools because the API JAR files for JMS are not available.

66 WebSphere Application Server Liberty Profile Guide for Developers

Configuring a JMS Topic
In the publish/subscribe model, messages are published to a Topic. All
resources that are subscribed to that Topic receive the published messages. To
configure a Topic in WebSphere Liberty profile server, you must define several
resources.
1. Begin by creating a JMS Topic by selecting Server Configuration, clicking
Add, and selecting JMS Topic in the Add Item dialog box. You can filter the
entries that are shown in the dialog box by entering JMS in the search box, as
shown in Figure 3-24.

Figure 3-24 Filtering the Add Item list

2. In the details window for the JMS topic, enter ITSOTopic in the id field and
jndi/ITSO_TOPIC in the JNDI name field.
3. The configuration must also indicate whether the JMS Topic uses the
WebSphere embedded messaging engine or an external instance of
WebSphere MQ. To accomplish this task, select the JMS Topic in the server
configuration and click Add.
4. In the Add Item dialog box, select WebSphere Embedded JMS Topic. The
details window allows you to specify various properties for the Topic, but for
this example you can leave all the values at their defaults.

Chapter 3. Developing and deploying web applications 67

 Configuring a JMS Topic connection factory
To create JMS Topic connections that allow you to work with JMS topics, you
must have a JMS topic connection factory. Complete the following steps:
1. Create a JMS topic connection factory by selecting Server Configuration
and clicking Add.
2. In the Add Item dialog box, select JMS Topic Connection Factory.
3. In the details window, enter ITSO_CF in the Id field and jndi/jmsTCF in the
JNDI Name field.
4. You also must add a nested configuration for connection factory properties.
Create this configuration by selecting the JMS Topic Connection Factory and
clicking Add.
5. In the Add Item dialog box, select WebSphere Embedded Topic
Connection Factory. For this example, you can leave all properties in the
details window at their default values.

Enabled features
When you create JMS resources, the Liberty profile developer tools likely prompt
you to add features to the server. For this example, wasJmsClient-1.1 and
wasJmsServer-1.0 must be enabled. You can enable these features manually by
selecting Feature Manager in the server configuration. Click Add and select the
JMS features to add, as shown in Figure 3-25 on page 69.

68 WebSphere Application Server Liberty Profile Guide for Developers

Figure 3-25 Enabling the wasJmsServer-1.0 feature

Creating a JMS application

Create a servlet named JMSTopicExample in the ITSOWeb project, or import the
existing servlet from the additional materials. To perform these steps, see the
procedure in “Building a servlet application” on page 47.

If you are developing the servlet code yourself, complete the following steps:
1. Add a constant named TOPIC_CONNECTION_FACTORY_JNDI_NAME with a value
that is equal to the JNDI name that you specified for the JMS topic connection
factory, jndi/jmsTCF.

Chapter 3. Developing and deploying web applications 69

 2. Add a constant named TOPIC_JNDI_NAME with a value that is equal to the JNDI
name that you specified for the JMS topic, jndi/ITSO_TOPIC.
3. Obtain a TopicConnectionFactory object by looking up the
TOPIC_CONNECTION_FACTORY_JNDI_NAME constant in JNDI.
4. Use the TopicConnectionFactory to obtain a new TopicConnection by calling
createTopicConnection.
5. Start the TopicConnection by running start.
6. Create a TopicSession by running createTopicSession on the
TopicConnection. Pass in the arguments false and
javax.jms.Session.AUTO_ACKNOWLEDGE.
7. Obtain a Topic instance by looking up the TOPIC_JNDI_NAME constant in JNDI.
8. Create a TopicSubscriber by running createSubscriber on the TopicSession
and passing in the Topic.
9. Create a TopicPublisher by running createPublisher on the TopicSession
and passing in the Topic.
10.Create a TextMessage by running createTextMessage on the TopicSession
and passing in the String Hello, subscriber.
11.Publish the TextMessage by running publish on the TopicPublisher and
passing in the TextMessage as the argument.
12.Receive the TextMessage by running receive on the TopicSubscriber and
passing in 5000 as the argument. This tells the receive method to wait at most
five seconds for a message.
13.Verify that the message was received correctly by printing the output.

70 WebSphere Application Server Liberty Profile Guide for Developers

 The completed servlet should be similar to the code shown in Figure 3-26.

Figure 3-26 JMSTopicExample servlet

Chapter 3. Developing and deploying web applications 71

 Testing the servlet
Access the application by visiting the link:
http://localhost:9080/ITSOWeb/JMSTopicExample

Result: You should see the message Received message: Hello, subscriber
in your web browser. This simple example shows that JMS APIs can be used
to transmit messages between a client and server. In this case, the client and
server are both in the same servlet. In 5.4, “Developing message driven bean
applications” on page 126, we show how you can add a Message Driven Bean
(MDB) as a client by using these same resources.

3.1.7 Developing JAX-WS web services applications with the Liberty

profile developer tools
The Java API for XML Web Services (JAX-WS) allows you to create web
services applications in a Java EE environment. The JAX-WS API eases the
development of web services applications by allowing developers to expose Java
classes as web services using annotations. Developers are freed from having to
deal with the complexities of the message format. For more information about
JAX-WS, see the following Information Center website:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
nd.doc/ae/cwbs_jaxws.html

JAX-WS support is provided only by WebSphere Liberty profile editions other

than the core edition.

Complete the actions outline in the following sections to expose a Java class as
a web service in WebSphere Liberty profile.

Creating the service implementation

This example simulates bottom-up web services development where an existing
implementation is exposed as a service. To do this, create a simple Java class to
act as the service implementation.

Create a Java class in the ITSOWeb project named ITSOGreeter. It should have
one method, named getValue, that takes a String as an input. It should return the
String Hello, <name> from the ITSO Greeter. The completed ITSOGreeter
class is shown in Figure 3-27 on page 73.

72 WebSphere Application Server Liberty Profile Guide for Developers

Figure 3-27 The ITSOGreeter class

Creating a web service

To expose the ITSOGreeter class as a web service, complete the
following steps:
1. Begin by right-clicking the ITSOWeb project and selecting New  Other. In
the Select a wizard dialog box, expand Web Services and select Web
Service, as shown in Figure 3-28.

Figure 3-28 Web Service wizard selection

Chapter 3. Developing and deploying web applications 73

 2. On the first window of the wizard, click Browse to select the ITSOGreeter
class as the service implementation. Leave the web service type as the
default, Bottom up Java bean Web Service.
3. On the left side of the window, there is a slider that lets you control how much
of the web service is generated. For this example, leave the slider at the
default value of Start service.
4. Under Configuration, the server run time should be WebSphere Application
Server V8.5 Liberty Profile and the Web Service run time should be IBM
WebSphere JAX-WS. These values are set by default, but if they are not, you
can click the values to change them.
5. By default, the wizard does not generate client code for the web service. You
can change this by moving the lower slider up to Start client. As with the web
service configuration, the server run time should be WebSphere Application
Server V8.5 Liberty Profile and the Web Service run time should be IBM
WebSphere JAX-WS.
Figure 3-29 on page 75 shows the completed wizard window.

74 WebSphere Application Server Liberty Profile Guide for Developers

Figure 3-29 Web Services wizard

6. Click Next to advance to the next window. The second window has many
options for the generated web service. If you plan to use this example code as
a starting point for the example in 6.5, “JAX-WS security” on page 162, select
the check box next to Generate WSDL file into the project. This step is
optional as the example in this chapter works with or without a generated
WSDL file, and the file can be generated later if needed.
7. Accept all of the defaults for other options and click Next to advance to the
next window.

Chapter 3. Developing and deploying web applications 75

 8. Accept all of the defaults on the WSDL interface options window and
click Next.
9. If the Liberty profile server is not started, the next window requires you to start
it before proceeding. After it is started, click Next.
10.Accept all defaults on the web service client options window and click Next.
11.Click Finish to complete the wizard. Note the following changes that the
wizard made:
– The wizard created a class named ITSOGreeterDelegate that provides a
wrapper for the ITSOGreeter class. The ITSOGreeterDelegate class is
annotated with @WebService to expose it as a JAX-WS web service.
– The wizard created a new EAR project named ITSOWebEAR and added
the ITSOWeb dynamic web project to the new project's modules. It also
added the new EAR to the server. You can verify this by loading the
server configuration.
– A new web project named ITSOWebClient was created to contain the
JAX-WS client code. In addition to the JAX-WS artifacts, the new project
contains JAXB generated classes.
– A new EAR project named ITSOWebClientEAR was created to contain the
ITSOWebClient. The wizard also deployed this EAR to the server.

Caution: The code in the client project is generated to use JAX-WS APIs
that are not available in JavaSE 6. If you are using JRE Version 6, you
might need to change the order of dependencies on the project’s build path
so that the Liberty profile runtime dependency is above the
JRE dependency.

Testing the web service

Test the web service by completing the following steps:
1. Make sure that the service side of the web service is working correctly by
visiting the link:
http://localhost:9080/ITSOWeb/ITSOGreeterService?wsdl
This should return the WSDL document for the web service. Some web
browsers hide XML documents by default. If you see an empty page when
visiting the link, you might need to view the source to see the
WSDL document.
2. Create a servlet in the ITSOWebClient project to drive the web service client.
Using the Create Servlet wizard, create a servlet named JAXWSGreeterClient.

76 WebSphere Application Server Liberty Profile Guide for Developers

 In the servlet’s doGet method, create an instance of ITSOGreeterService.
This is one of the client classes that was generated by the web services
wizard. Call the getITSOGreeterPort method on the ITSOGreeterService
instance to get an ITSOGreeterDelegate instance. Finally, print the value that
is returned from calling getValue on the delegate instance.
Figure 3-30 shows the completed servlet code.

Figure 3-30 JAXWSGreeterClient servlet code

3. Test the servlet by visiting the link:

http://localhost:9080/ITSOWebClient/JAXWSGreeterClient

Result: You should see the output Hello, JAX-WS Client from the
ITSO Greeter.

3.1.8 Debugging applications with the Liberty profile developer tools

One of the most powerful features of developing in the Liberty profile developer
tools environment is the ability to debug code running on the server directly from
the development environment. The following procedure is an example of how
you debug a simple application in the Liberty profile developer tools environment.

Chapter 3. Developing and deploying web applications 77

 To debug applications, complete the following steps:
1. The server must be run in debug mode. You can start (or restart) the server in
debug mode by clicking the bug icon in the Servers view, as shown in
Figure 3-31.

Figure 3-31 Restarting the server in debug mode

2. To debug the application, set a breakpoint in the doGet method of the

HelloITSO servlet. On most platforms, you can do this by selecting a line in
the method and pressing Ctrl+Shift+b. You can also right-click the vertical bar
to the left of the line of code and select Toggle Breakpoint.
3. Open a web browser and enter the address for the HelloITSO example:
http://localhost:9080/ITSOWeb/HelloITSO
4. A dialog in the tools prompts you to switch to the debug perspective (unless
you configured Eclipse to switch automatically). Click YES, and you see that
the debugger hit the breakpoint in the doGet method. Make a change to the
method and save the file. Advance past the breakpoint by clicking Resume
on the menu bar (or by pressing F8.) The output in the browser changed
based on the changes that you made.

3.2 Developing outside the Liberty profile developer

tools
Developers who prefer working outside of the Liberty profile developer tools
environment can also enjoy a simplified development experience by using the
Liberty profile server. Liberty profile is designed to reduce development impact
by providing a fast, lightweight environment for application development. The
following list covers some of the key design features of the Liberty profile server
that contribute to the new environment:
򐂰 Quick server startup
򐂰 Hot deployment of applications
򐂰 Dynamic feature enablement

78 WebSphere Application Server Liberty Profile Guide for Developers

 򐂰 Dynamic configuration
򐂰 Simple configuration that can be modified in a text editor

These characteristics of the Liberty profile ensure that developers can write,
debug, and update applications without wasting time on server restarts or
updating configuration through a complex administrative interface.

In this section, we cover several considerations to keep in mind when developing

applications outside of the Liberty profile developer tools environment.

3.2.1 Feature enablement

The Liberty profile server load only into memory the subset of the run time that is
being used. You must specifically enable features in the configuration for them to
be available to your applications. The following is a list of features that are used
in the examples in this chapter:
servlet-3.0 Servlet 3.0
jsp-2.2 JavaServer Pages (JSP) 2.2
jpa-2.0 Java Persistence Architecture (JPA) 2.0
jaxrs-1.1 Java API for RESTful Web Services (JAX-RS) 1.1
wasJmsClient-1.1 Java Messaging Service (JMS) Client 1.1
wasJmsServer-1.0 Java Messaging Service (JMS) Server 1.0
cdi-1.0 Context and Dependency Injection (CDI) 1.0
jaxws-2.2 Java XML Web Services (JAX-WS) 2.2

Some of those listed features also provide other features. For example, the
jsp-2.2 feature contains the servlet-3.0 feature. If your server configuration has
jsp-2.2 enabled, it does not need to have servlet-3.0 additionally specified to
run servlets.

When you add or remove a feature, the run time is dynamically updated to
enable or disable the function. You can test this by deploying a simple servlet
and removing the servlet-3.0 feature from the configuration. When you remove
the feature, you see the text in Example 3-3 in the console output.

Example 3-3 Console output after removing the servlet feature

[AUDIT ] CWWKF0013I: The server removed the following features:
[servlet-3.0].

Chapter 3. Developing and deploying web applications 79

 If you attempt to load a servlet, the server should fail to respond to the request.
Now, enable the servlet-3.0 feature again. You should see the output in
Example 3-4 in the console.

Example 3-4 Console output after enabling the servlet feature

[AUDIT ] CWWKF0012I: The server installed the following features:
[servlet-3.0].

If you load the servlet now, the request succeeds.

3.2.2 Dynamic application update

By default, applications are automatically updated whenever a change to the
application files is made. This allows you to save time that is not lost restarting
applications manually.

This behavior can be seen by updating the web.xml file for a deployed Web
Archive (WAR). Make a change, such as changing the value of a servlet
mapping, and save the file. Then, load the servlet using the new mapping, and
observe that the application is automatically updated.

3.2.3 Common development configuration

Liberty profile uses reasonable default values for configuration whenever
possible. Some common cases where you might decide to update the
configuration during development are covered next in this section.

Context root for web applications

Unless it is explicitly defined in the server.xml file or in the application, the
context root for a web application is automatically determined from the file name
of the WAR file. By default, the value of the context root is the WAR file name
without the WAR extension. If you want to change the value of the context root, it
can be specified in the configuration using the application definition that is shown
in Example 3-5.

Example 3-5 An application definition from server.xml

<application location=”ITSOWeb.war” context-root=”myWebAppRoot”/>

80 WebSphere Application Server Liberty Profile Guide for Developers

 HTTP server ports
The default port for HTTP requests is 9080. You can also change this value in the
configuration. To change the port to 9090, add the endpoint definition in
Example 3-6 to the server.xml file.

Example 3-6 An endpoint definition from server.xml

<httpEndpoint id=”defaultHttpEndpoint” host=”*” httpPort=”9090”/>

3.2.4 Dynamic configuration

Dynamic configuration updates in Liberty profile server mean that you do not
have to waste time restarting the server when you make changes to the
configuration. This section covers some scenarios that display the benefits of
dynamic configuration updates.

Changing the HTTP server port

If port 9080 is in use on your machine or you are running multiple server
instances, you might want to change the default HTTP port. With the server
running, add the endpoint configuration, which is shown in Example 3-6, to your
server.xml file. Save the file, and try to access a web application from the
updated port. The server did not need to restart to make this change.

Adding a JNDI entry

Liberty profile server gives you the ability to bind JNDI entries in the
configuration. These values are automatically updated when they are added,
updated, or removed from the configuration.

Before using JNDI, you must add the JNDI-1.0 feature to your
server’s configuration.

To test this, create a simple servlet and add code similar to that shown in
Figure 3-32.

Figure 3-32 Look up a value using JNDI

Chapter 3. Developing and deploying web applications 81

 Run the servlet, and notice that the servlet was unable to find the value. Now,
add the XML element in Example 3-7 to the server.xml file.

Example 3-7 XML element in server.xml file

<jndiEntry value="This is a sample value"
jndiName="jndi/exampleValue"/>

Save the file and without restarting the server, run the servlet again. Notice that it
now prints out the value that was set in the server configuration. You can also
test updating the value or removing the jndiEntry element. In each case, the
server is dynamically updated without a restart.

Caution: Only the server configuration is dynamically updated. Values are

only read from bootstrap.properties when the server starts, so any value
changes does not take place until you restart the server.

3.2.5 API JAR files

API JAR files for technologies that are included in the Liberty profile server are in
the dev directory under the Liberty profile server home directory. The following
list notes those directories:
򐂰 Java EE APIs are in dev/api/spec.
򐂰 IBM APIs are in dev/api/ibm.
򐂰 Third-party APIs are in dev/api/third-party.

The following list shows the API JAR files that are used for technologies that are
covered in this chapter:
򐂰 Servlets
dev/api/spec/com.ibm.ws.javaee.servlet.3.0_1.0.0.jar
򐂰 JSP
dev/api/spec/com.ibm.ws.javaee.jsp.2.2_1.0.0.jar
򐂰 JSF
dev/api/spec/com.ibm.ws.javaee.jsf.2.0_1.0.0.jar
dev/api/spec/com.ibm.ws.javaee.jsf.tld.jar
dev/api/spec/com.ibm.ws.javaee.jstl.1.2_1.0.0.jar

82 WebSphere Application Server Liberty Profile Guide for Developers

 򐂰 JAX-RS
dev/api/spec/com.ibm.ws.javaee.jaxrs.1.1_1.0.0.jar
dev/api/ibm/com.ibm.websphere.appserver.api.jaxrs_1.0.0.jar
dev/api/third-party/com.ibm.websphere.appserver.thirdparty.jaxrs_1.0
.0.jar
򐂰 CDI
dev/api/spec/com.ibm.ws.javaee.cdi.1.0_1.0.0.jar
򐂰 JMS
dev/api/spec/com.ibm.ws.javaee.jms.1.1_1.0.0.jar
򐂰 JAX-WS
dev/api/spec/com.ibm.ws.javaee.jaxws.2.2_1.0.0.jar

Caution: Only spec and ibm-api libraries are visible to applications by default.
See 3.3, “Controlling class visibility in applications” on page 88 for more
information about class visibility.

3.2.6 Debugging applications

You can use a Java debugger to debug your applications by starting the server in
debug mode. To do this, start the server with the command server debug. The
server waits for a Java debugger to attach on port 7777 before starting.
Optionally, you can change the port that the server uses for debugging by setting
the value of WLP_DEBUG_ADDRESS to the wanted port in your operating
system’s environment.

3.2.7 Using Maven to automate tasks for the Liberty profile

Apache Maven is a build scripting tool that is designed to hide some of the
complexities of build management from the user. Maven simplifies dependency
management by maintaining a set of versioned artifacts in a repository.

Liberty profile enables building with Maven by providing a plug-in that can be
used for common administrative tasks and a repository that contains certain API
JAR files.

Chapter 3. Developing and deploying web applications 83

 Plug-in repository
To use Maven for automating development tasks, first include the Liberty profile
plug-in, in your project’s pom.xml file. The plug-in is in a public central repository.
Example 3-8 shows a sample plug-in definition.

Example 3-8 Maven plug-in repository definition

<pluginRepository>
<id>Liberty</id>
<name>Liberty Repository</name>

<url>http://public.dhe.ibm.com/ibmdl/export/pub/software/websphere/wasd
ev/maven/repository/</url>
<layout>default</layout>
<snapshots>
<enabled>false</enabled>
</snapshots>
<releases>
<enabled>true</enabled>
</releases>
</pluginRepository>

Specifying the plug-in and configuration

Example 3-9 shows how to load the Liberty Maven plug-in and specify a basic
configuration. The configuration for serverHome and serverName is optional, but if
it is not specified, it generally must be passed in as an argument when running
from the command line.

Example 3-9 Loading and configuring the Liberty plug-in

<build>
<plugins>
<!-- Enable liberty-maven-plugin -->
<plugin>
<groupId>com.ibm.websphere.wlp.maven.plugins</groupId>
<artifactId>liberty-maven-plugin</artifactId>
<version>1.0</version>
<!-- Specify configuration -->
<configuration>
<serverHome>/opt/IBM/wlp</serverHome>
<serverName>testServer</serverName>
</configuration>
</plugin>
</plugins>
</build>

84 WebSphere Application Server Liberty Profile Guide for Developers

 Examples: The following examples pass in the serverHome and serverName
as arguments on the command line. These can be omitted if they are specified
in the pom.xml file.

Creating a server
Use the following command to create a server named SERVER_NAME in the
directory SERVER_HOME:
mvn liberty:create-server -DserverHome=SERVER_HOME
-DserverName=SERVER_NAME

Deploying and undeploying applications

Use the following command to deploy an application that is in APPLICATION_FILE
to the server named SERVER_NAME:
mvn liberty:deploy -DserverName=SERVER_NAME -DserverHome=SERVER_HOME
-DappArchive=APPLICATION_FILE

The server must be started to deploy the application.

Use the following command to undeploy the same application: mvn

liberty:undeploy -DserverName=SERVER_NAME
-DserverHome=SERVER_HOME -DappArchive=APPLICATION_NAME

The server must be started to remove the application. In this scenario, the
appArchive parameter uses the application name rather than a file path.

Starting and stopping the server

Use the following command line to start a Liberty profile server instance:
mvn liberty:start-server -DserverHome=SERVER_HOME
-DserverName=SERVER_NAME

Use the following command to stop a running server:

mvn liberty:stop-server -DserverHome=SERVER_HOME
-DserverName=SERVER_NAME

Packaging and installing the server

Use the following command line to package an existing server named
SERVER_NAME in a file named ARCHIVE_FILE:
mvn liberty:package-server -DserverName=SERVER_NAME
-DserverHome=SERVER_HOME -DpackageFile=ARCHIVE_FILE

Chapter 3. Developing and deploying web applications 85

 Use the following command to install a server from an archive named
ARCHIVE_FILE:
mvn liberty:install-server -DassemblyArchive=ARCHIVE_FILE

Dependency repositories
The API JAR files that are in the dev/ibm-api directory underneath the Liberty
Profile Server home directory are also available in a public Maven repository. To
use the repository, add the repository definition in Example 3-10 to your
pom.xml file.

Example 3-10 Maven repository definition

<repository>
<id>wlp.central</id>

<url>http://public.dhe.ibm.com/ibmdl/export/pub/software/websphere/wasd
ev/maven/repository</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>

Example 3-11 provides an example of referencing a specific artifact dependency.

In this scenario, the example is referencing the IBM JAX-RS extension APIs.

Example 3-11 IBM JAX-RS extension APIs

<dependency>
<groupId>com.ibm.websphere.appserver.api</groupId>
<artifactId>com.ibm.websphere.appserver.api.jaxrs</artifactId>
<version>1.0</version>
<scope>provided</scope>
</dependency>

Java EE dependencies, such as the servlet API, are not available in the IBM
repository. These dependencies can be accessed using the repository definition
in Example 3-12.

Example 3-12 Repository definition

<repository>
<id>java.net</id>

86 WebSphere Application Server Liberty Profile Guide for Developers

 <url>http://download.java.net/maven/2</url>
</repository>

The dependency definition in Example 3-13 shows how to reference the Java EE
6 API.

Example 3-13 Java EE 6 API reference

<dependency>
<groupId>javax</groupId>
<artifactId>javaee-api</artifactId>
<version>6.0</version>
<scope>provided</scope>
</dependency>

3.2.8 Using ANT to automate tasks for the Liberty profile

Liberty profile provides an ANT plug-in so you can automate build processes that
include management of the server and applications.

ANT plug-in
The Liberty profile ANT plug-in is in the dev/tools/ant directory under the server
home directory. To use the plug-in, you must make it available on the class path.
To make the plug-in available, copy the plug-in JAR file to the lib directory of the
ANT installation and reference it using an antlib namespace, as shown in
Example 3-14.

Example 3-14 Using antlib to include the ANT plug-in

<project .... xmlns:wlp="antlib:com.ibm.websphere.wlp.ant">

...
</project>

Deploying and undeploying applications

You can automate the addition and removal of applications using the deploy and
undeploy tasks that are shown in Example 3-15.

Example 3-15 Example of deploy and undeploy tasks

<wlp:deploy file="${basedir}/resources/ITSOExample.ear"
timeout="40000"/>

<wlp:undeploy file="ITSOExample.ear" timeout="60000" />

Chapter 3. Developing and deploying web applications 87

 Server administration
The following tasks are available for automating server administration tasks:
򐂰 Create
<wlp:server installDir=”${wlp_install_dir} operation=”create”/>
򐂰 Start
<wlp:server installDir="${wlp_install_dir}" operation="start"
serverName="${serverName}" />
򐂰 Stop
<wlp:server installDir=”${wlp_install_dir}” operation=”stop”
serverName=”${serverName}” />
򐂰 Status
<wlp:server installDir=${wlp_install_dir}” operation="status"/>
򐂰 Package
<wlp:server installDir=”${wlp_install_dir}” operation=”package”
archive=”packagedServer.zip”/>

3.3 Controlling class visibility in applications

Class visibility in the Liberty profile server is controlled by configuring a
classloader for an application in the server configuration. Defining the
classloader allows you to share common libraries with other applications and
control the types of APIs that are visible to the application. Defining the
classloader also ensures that applications load classes from their own libraries
before using classes from the Liberty profile server run time.

3.3.1 Using shared libraries in applications

Java EE application development often involves using common utility JAR files
across several applications. You can avoid having to maintain several copies of
the same utility JAR files by using shared libraries.

A library, in the Liberty profile server, is composed of a collection of file sets that
reference the JAR files to be included in the library. The library can be used in an
application by creating a classloader definition for the application in the server
configuration. The application classloader can share the in-memory copy of the
library classes with other applications, or it can have its own private copy of the
classes that are loaded from the same location.

88 WebSphere Application Server Liberty Profile Guide for Developers

 Shared libraries, which are defined in the configuration, can be used only by
applications that are explicitly configured in the server.xml file. Applications
without configuration, such as those placed in the dropins directory, can use a
global shared library, as described in 3.3.5, “Global libraries” on page 91.

3.3.2 Creating a shared library in the Liberty profile developer tools

To create a shared library in the Liberty profile developer tools, complete the
following steps:
1. Load the server.xml file in the design editor.
2. Right-click the application and click Add  Classloader.
3. In the Classloader properties, click New next to Shared library references.
4. On the Shared Library details window, click New next to the Fileset reference
to add a file set.
5. Enter the properties for the Fileset details window and save the
server.xml file.

Look at the source view for the server.xml file. The application now contains a
classloader, which contains a library, which contains a file set. Example 3-16
shows the resulting configuration from the server.xml file.

Example 3-16 Shared library configuration in server.xml

<classloader >
<commonLibrary>
<fileset includes=”utility.jar”/>
</commonLibrary>
</classloader>

The Liberty profile configuration is flexible enough to allow many configuration

elements to be specified either as a child of a parent element, or as an attribute
reference from that parent element. The shared library configuration in 3.3.3,
“Creating a shared library outside of the tools” on page 90 displays how some of
the same configuration can be specified using references.

Caution: The Liberty profile developer tools use slightly different terminology
than the server configuration file. A library in the tools is equivalent to a
privateLibrary in server.xml. A shared library in the tools is equivalent to a
commonLibrary in server.xml.

Chapter 3. Developing and deploying web applications 89

3.3.3 Creating a shared library outside of the tools
To create a shared library outside of the Liberty profile developer tools, you must
manually edit the server.xml file to add the following items:
򐂰 A file set that references the JAR files on disk.
򐂰 A library that either contains or references the file set.
򐂰 A classloader for each application that uses the shared library. The
classloader should reference the library element. If you want the application
to share the in-memory copy of the library, use the attribute commonLibraryRef
to reference the library. If you want the application to have its own copy of the
library, use the attribute privateLibraryRef.

Example 3-17 shows the definition of a shared library that is used by two different
applications. Both applications share an in-memory copy of the classes.

Example 3-17 Definition of two applications using the same shared library
<library id=”loggingLibrary”>
<fileset dir=”${server.config.dir}/logger”
includes=”ITSOLogger.jar”/>
</library>

<application name=”ITSOApp1” location=”ITSO_1.ear”>

<classloader commonLibraryRef=”loggingLibrary”/>
</application>

<application name=”ITSOApp2” location=”ITSO_2.ear”>

<classloader commonLibraryRef=”loggingLibrary”/>
</application>

3.3.4 Using libraries to override Liberty profile server classes

In some situations, you might decide to override certain classes in the Liberty
profile server with your own version of the same classes. You can accomplish
this by creating a shared library that contains the classes you want to use. Use
the following options:
򐂰 In the Liberty profile tools
On the classloader properties window, change the value in the drop-down
menu for delegation to parentLast.

90 WebSphere Application Server Liberty Profile Guide for Developers

 򐂰 Outside the Liberty profile tools
To change the classloader delegation outside the Liberty profile developer
tools, add the attribute delegation=”parentLast” on the classloader element
in the server.xml file.

3.3.5 Global libraries

The Liberty profile server allows you to provide a library or set of libraries that
can be accessed by all applications. To add a JAR file to this global shared
library, simply copy it to one of the following two locations under
${WLP_USER_DIR}:
򐂰 shared/config/lib/global
򐂰 servers/server_name/lib/global

The libraries in these directories are used by all applications that do not
specifically define a classloader. If you define a classloader for an application,
the global library classes is not available unless you add the library global as a
shared library. The sample configuration in Example 3-18 shows an application
that is configured to use the global shared library.

Example 3-18 Application using a global shared library

<application name=”ITSOApp1” location=”ITSO_1.ear”>
<classloader commonLibraryRef=”global”/>
</application>

3.3.6 Using a classloader to control API visibility

By default, an application in Liberty profile can see supported specification APIs
(such as the Java EE Servlet specification) and IBM-provided APIs. For the
application to load classes from third-party libraries, such as those in
dev/third-party, you must configure the allowed API types for the application
classloader. In the Liberty profile developer tools, you can configure this value in
the Allowed API types field on the classloader service details window. If you are
directly editing the server.xml file, add the attribute apiTypeVisibility to the
classloader element. In both cases, the value is to be a comma-separated list of
any combination of the following items:
spec Supported Specification Libraries
ibm-api IBM-provided APIs
ibm-spi IBM-provided SPIs
third-party Third-party APIs

Chapter 3. Developing and deploying web applications 91

 For example, the following classloader element allows an application to see
specification libraries, IBM-provided APIs, and third-party APIs:
<classloader apiTypeVisibility="spec,ibm-api, third-party"/>

92 WebSphere Application Server Liberty Profile Guide for Developers

 4

Chapter 4. Iterative development of

OSGi applications
In addition to Java EE applications, WebSphere Application Server Liberty
Profile allows you to develop OSGi applications. OSGi provides a framework for
developing flexible, modular applications. With OSGi applications, you can
deploy and manage applications as a set of versioned OSGi bundles.

The chapter contains the following sections:

򐂰 Introduction to OSGi applications in Liberty profile
򐂰 Developing OSGi applications in the Liberty profile developer tools
򐂰 Developing OSGi applications outside Liberty profile developer tools

© Copyright IBM Corp. 2012, 2013. All rights reserved. 93

4.1 Introduction to OSGi applications in Liberty profile
The Liberty profile server and Liberty profile developer tools help you to develop
and deploy modular OSGi applications quickly. The advantages of OSGi are
included in the following list:
򐂰 Reduces complexity through modular design.
򐂰 Integrates with standard Java EE technologies such as servlets.
򐂰 Promotes service-oriented design.
򐂰 Composes isolated enterprise applications using multiple versioned bundles
with dynamic lifecycles.
򐂰 Provides careful dependency and version management.
򐂰 Offers declarative assembly of components.
򐂰 Allows sharing modules through a bundle repository that can host common
and versioned bundles.
򐂰 Allows access to external bundle repositories.
򐂰 Allows administrative updates to deployed applications at a bundle level.

For more information, see the OSGi home page at the following website:
http://www.osgi.org

The OSGi support in the WebSphere Application Server Liberty profile is based
on the Apache Aries open community project.

4.2 Developing OSGi applications in the Liberty profile

developer tools
The Liberty profile developer tools make developing OSGi applications easier by
providing graphical editors for OSGi artifacts such as OSGi Blueprint and
manifest files. The tool environment allows you to safely create dependencies on
other bundles without having to worry about problems being introduced by
mistakes in manual editing of manifest files. The Liberty profile developer tools
can also help converting existing Java EE applications into OSGi applications.

94 WebSphere Application Server Liberty Profile Guide for Developers

4.2.1 Using the tools to build an OSGi application
In this section, we describe how to build a simple hello world style OSGi
application using different bundles for client, service, and API. The application
shows a limited subset of what is possible with OSGi applications, and shows
how to get started building OSGi applications in the Liberty profile
developer tools.

Creating OSGi bundle projects

In this application, we use three bundles: a client bundle, a service bundle, and
an API bundle. Begin by creating a project for each bundle using the following
process:
1. Click File  New  OSGi Bundle Project.
2. Enter a project name. This example uses the project names
ITSO.OSGiExample.API, ITSO.OSGiExample.Client, and
ITSO.OSGiExample.Service.
3. For the Target Runtime, select WebSphere Application Server V8.5
Liberty Profile.
4. Clear the Add bundle to application check box. If you leave this check box
selected, a new OSGi application project is created.
5. Leave all other values as the default settings and exit the wizard by clicking
Next  Next  Finish.

Creating the client API

In the ITSO.OSGiExample.API project, create an interface named HelloAPI in the
com.itso.example.osgi.api package. The interface should contain a single public
method with a void return type named sayHello.

Chapter 4. Iterative development of OSGi applications 95

 Expose this interface class to other bundles by editing the manifest file for the
project. You can open the manifest editor by double-clicking the Manifest
element underneath the bundle project, as shown in Figure 4-1.

Figure 4-1 API bundle project

In the manifest editor, click the Runtime tab. In the exported packages pane,
click Add. Select the com.itso.example.osgi.api package from the list and then
click OK.

Creating the service bundle

The OSGi service bundle provides an implementation of the API. For the API’s
interface to be visible in the service project, import the API package in the service
bundle. To import the API package, complete the following steps:
1. Open the manifest editor for the ITSO.OSGiExample.Service project. In the
Imported Packages pane of the Dependencies tab, click Add. In the package
selection dialog, select com.itso.example.osgi.api. Then, save and close
the manifest.
2. Create an implementation for the API by creating a new Java class in the
ITSO.OSGiExample.Service project named HelloImpl in the
com.itso.example.osgi.service package. The class should implement the
HelloAPI interface. In the implementation of the sayHello() method, enter an
output statement such as System.out.println(“Hello, Liberty developers
from OSGi”). Save and close the file.

Warning: When selecting an interface, you might need to start typing

before the list of available interfaces is shown.

3. Export the service implementation using an OSGi Blueprint file. Begin by

creating the file. Right-click the ITSO.OSGiExample.Service project and select
New  Blueprint File. Leave all values as the defaults, and click Finish.

96 WebSphere Application Server Liberty Profile Guide for Developers

4. In the Overview pane of the Blueprint editor’s design tab, click Add. Click
Bean and click OK. Click Browse and select HelloImpl (you must start
typing in the choose type name field to display the list of options). Leave the
Bean ID field as the default value, HelloImplBean.
5. Click Blueprint in the Overview pane and click Add.
a. Click Service, and click OK.
b. Click Browse next to the Service Interface field and select HelloAPI.
c. Click Browse next to the Bean Reference field and select HelloImplBean.
d. Click OK and save the file.
e. Examine the source for the Blueprint file and verify that it resembles the
XML that is shown in Figure 4-2.

Figure 4-2 Service Blueprint file

Creating an OSGi client bundle

The OSGi client bundle calls the sayHello method on the service
implementation. Similar to the service bundle, the client bundle must have
access to the API by importing the API package in its manifest. Use the
procedure from step 1 on page 96 to edit the manifest and import the API.

Create a HelloITSOClient class in the ITSO.OSGiExample.Client project. The

class should contain the following pieces:
򐂰 A private field of type HelloAPI named helloService.
򐂰 Get and Set methods for the helloService field.
򐂰 A method named init that is called when the client is initialized. This method
should print a message and then run helloService.sayHello().

Chapter 4. Iterative development of OSGi applications 97

 The completed class should resemble the code that is shown in Figure 4-3.

Figure 4-3 Source code for HelloITSOClient

The client must be configured so that it can recognize the service implementation
and have the service dependency that is injected into the helloService field. This
is done by creating a Blueprint file for the client using the following steps:
1. Create a Blueprint file by right-clicking the ITSO.OSGiExample.Client project
and selecting New  Blueprint File. You can accept all default values for the
file and click Finish.
2. Add a reference element to the Blueprint:
a. Click Add in the Overview pane in the Blueprint editor.
b. Click Reference and click OK.
c. Click Browse beside the Reference Interface field, and select HelloAPI
from the list of classes.
d. In the Reference ID field, enter helloRef.
e. Click OK to finish adding the reference element.
3. Add a bean element to the Blueprint file:
a. Click Add in the Overview pane.
b. Select Bean and click OK.
c. Click Browse, select HelloITSOClient, and click OK.

98 WebSphere Application Server Liberty Profile Guide for Developers

 d. Click OK again to finish adding the bean element.
e. In the bean properties window on the right side of the editor, locate the
Initialization Method field and click Browse.
f. Select the init() method and click OK. This alerts the Blueprint container
to run the init method when the HelloITSOClient class is instantiated.
4. Add a property to the HelloITSOClientBean by selecting the bean in the
Overview pane and clicking Add. Select Property and click OK. In the Details
window, enter helloService in the Name field. Then, click Browse beside the
Reference field and select the helloRef reference. Click OK to finish adding
the property.
5. Save the Blueprint file and switch to the Source tab.

The completed file should resemble Figure 4-4.

Figure 4-4 Blueprint file for ITSO.OSGiExample.Client

Creating an OSGi application

Create an OSGi application to contain the three OSGi bundles by completing the
following steps:
1. Click File  New  OSGi Application Project.
2. Enter a project name, such as ITSO.OSGiExample.App. Leave the other values
as the defaults and click Next.
3. In the contained bundles list, select all three OSGi bundle projects and
click Finish.

4.2.2 Using the tools to deploy and test an OSGi application

To deploy the OSGi application to a WebSphere Liberty profile server instance,
right-click the server in the Servers view and select Add and Remove. In the
Add and Remove window, select the ITSO.OSGiExample.App application and click
Add. Then, click Finish to complete adding the application to the server.

Chapter 4. Iterative development of OSGi applications 99

 The application is now deployed and started. You should see output in the
console similar to Figure 4-5.

Figure 4-5 Output after adding the OSGi application to the server

The blueprint-1.0 feature is added automatically. The client’s init method is

called during the application start, so you see the messages that are printed in
the init method in the console. Note also that the message from the service
implementation is printed because the client started the sayHello method.

4.2.3 Adding an OSGi web application bundle

Now add an OSGi web application bundle to the OSGi application. The web
application uses the existing service inside a servlet. Rather than using Blueprint
to manage the service reference, use the service registry to locate the service.
Complete the following steps:
1. Begin by creating am OSGi bundle project called ITSO.OSGiExample.WebApp.
This process is similar to the process that is described in “Creating OSGi
bundle projects” on page 95. The following list shows the differences:
a. On the first window of the create project wizard, select the Add Web
Support check box.
b. Leave the check box for adding the bundle to the OSGi application
checked so that it is added to the ITSO.OSGiExample.App application.
c. Optionally, on the web module window, enter a different value for the
context root. In this example, we use a context root of osgi.
2. As was the case with the service and client bundles, you must edit the
manifest for the web application bundle to import its dependencies. Open the
manifest editor and navigate to the Dependencies tab. Notice that several
servlet dependencies were automatically added to the manifest when the
project was created. Add the com.itso.example.osgi.api package to the list
of dependencies. Additionally, you must add org.osgi.framework version
1.5.0 to the list.

100 WebSphere Application Server Liberty Profile Guide for Developers

 3. Create a servlet in the new bundle project using the Create Servlet wizard.
Name the servlet HelloWABServlet, and edit the servlet mapping value to be
hello. For more information about creating servlets in the Liberty profile
developer tools, see 3.1.1, “Using the tools to create a simple servlet
application” on page 46.
4. In the servlet, add a private field of type HelloAPI named helloService. In the
doGet method, add a call to helloService.sayHello().
5. Also, in the servlet, override the init(ServletContext) method. In this
method, you use the ServletContext to get the ServletConfig. From the
ServletConfig, get the osgi-bundlecontext attribute. This is the OSGi
BundleContext object. You can use this BundleContext to look up the
HelloAPI service in the service registry. The complete init method is shown
in Figure 4-6.

Figure 4-6 Example init method for the HelloWABServlet

6. Save the servlet.

You can test this by visiting the link:

http://localhost:9080/osgi/hello

You do not see any output in the browser (unless you added output in the
servlet’s doGet method) but you see the message Hello, Liberty developer
displayed in the console output. This message shows that the servlet
successfully retrieved the service from the service register in its init method
and started the service’s sayHello method in its doGet method.

4.3 Developing OSGi applications outside Liberty

profile developer tools
Developers who prefer working outside of the Liberty profile developer tools
environment can still develop OSGi applications quickly using the Liberty profile
server. In this section, we describe some considerations for developing in this
environment and some tools to automate build and deployment processes.

Chapter 4. Iterative development of OSGi applications 101

4.3.1 Building and deploying OSGi applications outside of the tools
When building OSGi applications outside the Liberty profile developer tools,
there are several API and SPI JAR files that are in the dev directory that contain
important core classes such as BundleContext and ServiceReference:
򐂰 dev/api/spec/com.ibm.ws.org.osgi.cmpn.4.2.0_1.0.1.jar
򐂰 dev/api/spec/com.ibm.ws.org.osgi.core.4.2.0_1.0.1.jar
򐂰 dev/spi/third-party/com.ibm.wsspi.thirdparty.blueprint.1.0.0.jar
򐂰 dev/spi/spec/com.ibm.wsspi.org.osgi.cmpn.5.0.0_1.0.0.jar
򐂰 dev/spi/spec/com.ibm.wsspi.org.osgi.core.5.0.0_1.0.0.jar

Enterprise bundle archive (EBA) files can be placed in the dropins directory, such
as EAR or WAR files. You can also define them explicitly using an application
element in the server.xml file.

Also, note that you might need to manually enable the features blueprint-1.0
and wab-1.0 in the server configuration.

4.3.2 Using Maven to automate OSGi development tasks

You can automate the building and deployment of OSGi applications by using the
Liberty Maven plug-in, with open source tools. An example of an open source
tool is the EBA Maven plug-in that is developed by Apache Aries.

As described in 3.2.7, “Using Maven to automate tasks for the Liberty profile” on
page 83, you can use the Liberty Maven plug-in to automate tasks. Some
examples of these tasks are deploying applications and starting a Liberty profile
server.

The EBA Maven plug-in allows you to build EBA archives from component
bundles. It can automatically generate an Application Manifest file from
information that is contained in the Maven pom file. For more information about
the EBA Maven plug-in, see:
http://aries.apache.org/modules/ebamavenpluginproject.html

4.3.3 Using ANT to automate OSGi development tasks

With Apache Ant and the Liberty Ant plug-in, you can automate the packaging
and deployment of OSGi applications. Refer to 3.2.8, “Using ANT to automate
tasks for the Liberty profile” on page 87 for more information about using the
Liberty plug-in. This section gives further details on how to automate tasks such
as deploying and undeploying applications or starting and stopping servers.

102 WebSphere Application Server Liberty Profile Guide for Developers

You can use standard Ant tasks, such as zip, to package OSGi applications that
can then be deployed using the Liberty plug-in. Example 4-1 shows sample
syntax for creating an OSGi application named ITSOExampleApp.

Example 4-1 Syntax for creating an OSGi application

<zip destfile="${output.dir}/ITSOExampleApp.eba" basedir="${basedir}">
<filename name="META-INF/APPLICATION.MF"/>
<fileset dir="${basedir}">
<include name="*.jar"/>
</fileset>
</zip>

Chapter 4. Iterative development of OSGi applications 103

104 WebSphere Application Server Liberty Profile Guide for Developers
 5

Chapter 5. Data access in the Liberty

profile
The Liberty profile server supports standard Java EE technologies for data
access such as the Java Persistence API (JPA) and JDBC. The Liberty profile
developer tools simplify the development of data access applications for these
technologies by assisting with the setup of required resources. In this chapter,
we give an overview of data access in Liberty profile and give examples of how
to develop data access applications with the Liberty profile.

The chapter contains the following sections:

򐂰 Accessing data using a data source and JDBC
򐂰 Developing JPA applications
򐂰 Developing Enterprise Java Bean applications
򐂰 Developing message driven bean applications
򐂰 Data access with MongoDB

© Copyright IBM Corp. 2012, 2013. All rights reserved. 105

5.1 Accessing data using a data source and JDBC
JDBC provides a database-independent API for querying and updating data.
Liberty profile provides support for data access using JDBC 4.0.

5.1.1 Basic concepts for configuring data access in Liberty

profile server
To use JDBC in an application, first configure access to the database. In Liberty
profile, define a data source that has knowledge of the database. Several key
configuration concepts important to this process are described in this section.

File sets
A file set is simply a collection of files. They have several purposes in Liberty
profile. In the context of data access, they are used to point to the JDBC driver
library files provided by a database vendor.

Shared libraries
As described in 3.3, “Controlling class visibility in applications” on page 88,
shared libraries provide a collection of classes that can be used by one or more
applications or data sources. Libraries are composed of file set elements that
define the location of the class files.

JDBC drivers
A JDBC driver definition references a shared library. You can optionally specify
individual classes from the vendor-provided JDBC driver library to be used as the
data source implementation. If you do not specify the implementation classes,
the Liberty profile server infers the appropriate class name for most
common databases.

Data sources
A data source is the key piece of configuration for data access in the Liberty
profile server. In the simplest case, a data source is composed only of a JDBC
driver and the JNDI name where the data source is made available. In more
complex scenarios, you can specify other properties such as the type of data
source, transactional behavior, or vendor-specific database properties. For more
information about the various configuration options available for data sources,
see the following information center website:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
wlp.nd.doc/ae/twlp_dep_configuring_ds.html

106 WebSphere Application Server Liberty Profile Guide for Developers

5.1.2 Adding a data source using Liberty profile developer tools
The Liberty profile developer tools facilitate the definition of adding a data source
and related entities. The following scenario shows one way to define all of the
artifacts necessary to add a data source to your application. Complete the
following steps to add a data source:
1. Open the server.xml file for your WebSphere Liberty profile server. In the
design view, select Server Configuration and click Add. Select Data
Source and click OK (Figure 5-1).

Figure 5-1 Adding a data source to an application

2. In the input field for JNDI Name, enter jdbc/ITSO.

Chapter 5. Data access in the Liberty profile 107

 3. The Data Source requires a JDBC Driver. On the Data Source Details
window, beside the JDBC driver reference, click Add. This opens a window
where you configure the new JDBC driver. Enter an Id of derbyDriver, as
shown in Figure 5-2.

Figure 5-2 JDBC driver configuration

4. A JDBC driver requires a shared library that references the JDBC driver
implementation classes. Beside the Shared libraries reference field, click New
to create a shared library. This opens a window to configure a shared library,
as shown in Figure 5-3.

Figure 5-3 Adding a shared library

5. Now, create a new file set for the shared library by clicking Add next to the
input field for Fileset reference. This opens the Fileset Details window.

108 WebSphere Application Server Liberty Profile Guide for Developers

 Finding the JAR files: The JAR files that are used for accessing your
database are not provided as part of the Liberty run time. You need to point
to the JAR files that are provided as part of your database run time. This
example uses a Derby database, which can be downloaded from the
following website:
http://db.apache.org/derby/

6. Enter the directory where the JAR files for your JDBC driver are in the Base
directory field, or click Browse to select a directory, as shown in Figure 5-4.

Figure 5-4 Fileset Service Details window

7. Right-click the Data Source element under the Configuration Structure and
select Add  Derby Embedded Properties.
8. In the Properties window, select Create in the Create database
drop-down menu.
9. Also, in the database properties window, enter ITSO in the Database name
field.
10.Save the server.xml file. The data source is now available for applications.

Chapter 5. Data access in the Liberty profile 109

5.1.3 Adding a data source outside the Liberty profile developer tools
You can also add a data source to the Liberty profile server by simply editing the
server.xml file in a text editor. The following procedure details the four key parts
of creating a data source for your applications:
1. Creating a file set
The first step in defining a data source is to create a file set that contains all of
the JAR files that are required for a JDBC driver. Example 5-1 shows a simple
file set definition that includes all files in the directory c:\Derby.

Example 5-1 A file set definition

<fileset id=”derbyFileset” dir="c:\Derby"/>

2. Creating a shared library

The next step in creating a data source is to create a shared library that
contains the file set or file sets that reference the JDBC driver JAR files.
Example 5-2 shows a shared library definition that references the file set you
created earlier. The filesetRef attribute is the same as the id attribute of the
fileset element.

Example 5-2 Shared library definition

<library id=”derbyLibrary” filesetRef=”derbyFileset”/>

3. Creating a JDBC driver

Next, create a JDBC driver that references the shared library you created.
Example 5-3 gives an example JDBC driver definition. The value of the
libraryRef attribute is the same as the id from the library element.

Example 5-3 JDBC driver definition

<jdbcDriver id=”derbyDriver” libraryRef=”derbyLibrary”/>

4. Creating a data source

Finally, create a data source definition. The minimum required configuration
for a data source consists of a JDBC driver definition and a JNDI name that
your application uses to access the data source. Example 5-4 shows a data
source definition that references the JDBC driver you created.

Example 5-4 Data source definition

<dataSource jdbcDriverRef=”derbyDriver” jndiName=”jdbc/ITSO”/>

110 WebSphere Application Server Liberty Profile Guide for Developers

 This scenario describes an simple data source configuration. More information
about configuring database connectivity in the Liberty profile can be found at the
following information center website:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
wlp.nd.multiplatform.doc/ae/twlp_dep_configuring_ds.html

5.1.4 Using the data source in an application

A data source that is defined in the server configuration can be accessed using
JNDI. The jndiName property specifies the location of the data source in the
namespace. To retrieve the DataSource object, simply look it up in JNDI. The
code in Figure 5-5 displays how to accomplish this using the
javax.annotation.Resource annotation on a field. You can also obtain the
DataSource object by creating a new InitialContext object and starting the lookup
method with the JNDI name of the data source as an argument.

Figure 5-5 Retrieving a DataSource in a servlet

Caution: The javax.annotation.Resource annotation does not support the

lookup attribute in JDK 1.6. If you are using JDK 1.6, you must change the
order of libraries on the build path for the project so that the Liberty library is
loaded before the JDK 1.6 library.

5.1.5 Defining a data source in an application

Applications can also define data sources through annotations or a deployment
descriptor. To configure a data source this way, the application must have
access to the JDBC driver classes. To do this, create a classloader for the
application as described in 3.3, “Controlling class visibility in applications” on
page 88. The classloader should reference a shared library that contains the
JDBC driver classes.

Chapter 5. Data access in the Liberty profile 111

 Defining a data source using annotations
Example 5-5 defines a data source in a Java class of an application using
annotations. The DataSourceDefinition annotation on the class defines various
properties for the data source. Only the name and className are
required properties.

Example 5-5 Annotations defining a data source

@DataSourceDefinition(name="java:comp/env/jdbc/ITSODataSource",
className ="org.apache.derby.jdbc.EmbeddedXADataSource40",
databaseName = "ITSO",
isolationLevel = Connection.TRANSACTION_READ_COMMITTED,
loginTimeout = 88,
maxPoolSize = 10,
properties = {"connectionTimeout=0",
"createDatabase=create",
"queryTimeout=1m20s"})

Defining a data source using a deployment descriptor

You can define a data source in a WAR file deployment descriptor by adding a
data source element to the web.xml file. You can simply edit the file, or use the
deployment descriptor editor in the Liberty profile developer tools.

To create the data source in the tools, complete the following steps:
1. Begin by loading the web.xml file. In the design view, select the Web
Application and click Add.
2. On the resulting window, select Data Source. Complete the properties for the
data source. For example, enter java:comp/env/jdbc/ITSODataSourceDD for
the name, org.apache.derby.jdbc.EmbeddedDataSource for the class name,
and ITSODD for the database name.
3. Now, click the new data source in the window on the left, and click Add.
Select Property to add a property. In the property editor, enter
createDatabase in the name field and create in the value field.
4. Save the deployment descriptor. If the server is running, the data source is
now available to your applications.

Example 5-6 shows how the completed data source appears in the web.xml file.

Example 5-6 Data source definition in a deployment descriptor

<data-source>
<name>java:comp/env/jdbc/ITSODataSourceDD</name>
<class-name>
org.apache.derby.jdbc.EmbeddedDataSource

112 WebSphere Application Server Liberty Profile Guide for Developers

 </class-name>
<database-name>ITSODD</database-name>
<property>
<name>createDatabase</name>
<value>create</value>
</property>
</data-source>

The definitions here represent a small portion of the configuration options

available for data sources. For more information about application-defined data
sources, see the following information center website:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
wlp.nd.multiplatform.doc/ae/rwlp_ds_appdefined.html

5.1.6 Using application-defined data sources

Obtaining an application-defined data source in an application uses the same
procedure regardless of whether the data source was defined in a
DataSourceDefinition annotation or in a deployment descriptor. In both cases,
the data source is available in the namespace at the location you specified in the
name property. Figure 5-6 shows sample code for retrieving a DataSource that
was defined in the web application’s deployment descriptor.

Figure 5-6 Obtaining a DataSource defined in web.xml

Chapter 5. Data access in the Liberty profile 113

 Figure 5-7 shows sample code for accessing a DataSource that was defined in
an annotation.

Figure 5-7 Obtaining a DataSource defined in annotations

5.1.7 Testing the data sources

The additional materials contain an application and three prebuilt Derby
databases that can be used to test each data source.

Caution: When importing entire projects from the additional materials, some
of the examples for later sections might have compile errors. For example, the
class MongoServlet has compile errors until you add the MongoDB JDBC
driver to the project’s class path, as described in “Setting up the MongoDB
JDBC driver” on page 130.

You can use one of the following database options:

򐂰 To use the Derby databases, expand ITSO_Derby.zip, ITSO2_Derby.zip, and
ITSODD_Derby.zip in the server’s root directory. The data source definitions
in the applications are designed to access these databases.
򐂰 To use another database, you must update the data sources to reference
your database. Also, you must create a table named USERTBL in the database
with the following configurations:
– A column named NAME with a type that maps to java.lang.String (such as
VARCHAR).
– A column named LOCATION with a type that maps to java.lang.String.
– A column named ID with a type that maps to java.lang.Integer (such as
INTEGER). This column should be generated by the database.

114 WebSphere Application Server Liberty Profile Guide for Developers

 The application contains three servlets: DataSourceServlet,
AnnotationDataSourceServlet, and WebXmlDataSourceServlet. Each extends
the abstract class BaseDataSourceServlet. Each servlet can perform four simple
operations on the database table. The operations include selecting all rows,
inserting a new row, dropping the table, or creating the table.

Note: Because of database differences, the create table statement might not
work for all databases.

Each servlet can be tested using the JSP page dataSource.jsp that is included
in the additional materials. To access the page, visit:
http://localhost:9080/ITSOWeb/dataSource.jsp

5.1.8 Dynamic configuration updates for data sources

Changing the attributes of a data source element at run time results in dynamic
updates to the server. Although the run time is updated immediately, some
dynamic updates might affect a running server differently than others. For
example, changing the isolationLevel attribute will change the isolation level for
any future connection request, but current connections will retain their existing
isolation level. An update to the value of the commitOrRollbackOnCleanup
attribute takes place immediately.

You can find a list of data source properties and their associated configuration
update behaviors at:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
wlp.nd.multiplatform.doc/ae/rwlp_ds_config_updates.html

The rules noted apply only to data sources that are defined in the server
configuration. When you update the properties of an application-defined data
source, the entire data source is destroyed and the updated application uses a
new data source. Effectively, from a developer perspective, all of the changes
take place immediately.

Chapter 5. Data access in the Liberty profile 115

5.2 Developing JPA applications
The Java Persistence API (JPA) provides a framework for working with relational
databases in an object-oriented way. WebSphere Liberty profile server provides
support for applications that use application-managed and container-managed
JPA written to the JPA 2.0 specification. The support is built on top of Apache
OpenJPA with extensions to support the container-managed
programming model.

5.2.1 JPA applications in the Liberty profile developer tools

The following procedure allows you to create a simple JPA application in the
Liberty profile developer tools:
1. Before beginning, make sure that you defined a data source as described in
5.1, “Accessing data using a data source and JDBC” on page 106. Your
database also must be configured with the USERTBL as described in 5.1.7,
“Testing the data sources” on page 114. The ITSO_Derby.zip file in the
additional materials provides a preconfigured Derby database.
2. Begin by enabling the JPA-2.0 facet on the ITSOWeb project. This causes a
persistence.xml file to be added to the project. If the project is deployed to
the Liberty profile server, it also causes the tools to prompt you to add the
JPA-2.0 feature to the server configuration.
3. Create a JPA entity class by right-clicking the project and selecting New 
JPA Entity. Enter com.itso.example in the Java package field and UserEntity
in the Class name field.
Figure 5-8 on page 117 shows the first page of the JPA entity wizard.

116 WebSphere Application Server Liberty Profile Guide for Developers

 Figure 5-8 New JPA Entity wizard

4. Click Next to advance to the next window. Under Table name, clear the Use
default check box. Enter USERTBL in the Table name field. Add an entity
field by clicking Add. Click Browse next to the Type field to select
java.lang.String, enter location in the name field, and then click OK.
5. Repeat step 4 to add entities for a java.lang.String field named name and a
java.lang.Integer field named id. Select the check box in the Key column for
the row containing the id field to indicate that the field is the primary key for
the table.

Chapter 5. Data access in the Liberty profile 117

 Figure 5-9 shows the completed second window of the JPA wizard. Click
Finish to exit the wizard.

Figure 5-9 JPA Entity Properties

6. To see automated changes, open the Persistence XML editor in either the
design or source view. Notice that the persistence class for UserEntity was
automatically added to the persistence.xml file. Now, open the source for the
UserEntity class. Notice that the id field is annotated with the
javax.persistence.Id annotation to indicate that it is the primary key.
7. The Derby database that we use is automatically generating the id field. For
JPA to handle the generated id field correctly, it must be annotated with
javax.persistence.GeneratedValue. The strategy attribute for the annotation
should be set to GeneratedValue.IDENTITY. Figure 5-10 on page 119 shows
how the annotation should look.

118 WebSphere Application Server Liberty Profile Guide for Developers

 Figure 5-10 The id field for the UserEntity class

8. Open the persistence.xml file again in the design editor. Click the ITSOWeb
persistence unit. In the details window, enter jdbc/ITSO in the JTA data
source field.
9. Add a persistence context reference to the deployment descriptor. Open the
web.xml file in the design editor. Right-click the Web Application (ITSOWeb)
element and select Add  Persistence Context Reference. In the details
window, enter jpasample/entitymanager in the Persistence Context
Reference Name field and ITSOWeb in the Persistence Unit Name field.
10.Create a utility class to handle the actual persistence by right-clicking the
project and selecting New  Class. Enter com.itso.example for the package
name and Persistor for the class name. In the source editor, create two
methods: retrieveVisitors and persistVisitor.
The retrieveVisitors method looks up an entity manager using the JNDI name
java:comp/env/jpasample/entitymanager. It then uses the EntityManager to
run a query that selects all UserEntity objects and returns the results.
The persistVisitor method accepts two String arguments, username and
location. It first looks up a UserTransaction object and starts the begin
method to start a global transaction. The method then creates a new
UserEntity object using the username and location variables. It then looks up
the EntityManager and persists the UserEntity object. Finally, the commit
method is started on the UserTransaction to commit the transaction.

Chapter 5. Data access in the Liberty profile 119

 The completed Persistor class is shown in Figure 5-11.

Figure 5-11 Example utility class to handle persistence

11.Create a front end for the JPA application. Begin by creating a JSP file named
jpaInput.jsp. The JSP contains a form with two input fields and a Submit
button. Figure 5-12 on page 121 shows the completed JSP file.

120 WebSphere Application Server Liberty Profile Guide for Developers

 Figure 5-12 jpaInput.jsp file

12.Create a servlet named JPAServlet. The doGet method uses the

retrieveVisitors method on the Persistor class to output a table of names
and locations. It also uses a RequestDispatcher to include the jpaInput.jsp
file. Figure 5-13 shows an example doGet method.

Figure 5-13 JPAServlet doGet method

Chapter 5. Data access in the Liberty profile 121

 The JPAServlet also has a doPost method that uses the name and location
parameters on the request to persist a new UserEntity object. Figure 5-14
shows a sample doPost method.

Figure 5-14 JPAServlet doPost method

13.Finally, test the application by visiting:

http://localhost:9080/ITSOWeb/JPAServlet
You should see output similar to Figure 5-15.

Figure 5-15 Output from the JPA application

122 WebSphere Application Server Liberty Profile Guide for Developers

5.2.2 JPA applications outside the Liberty profile developer tools
You can develop JPA applications outside of the Liberty profile developer tools. If
you do so, then you must enable the jpa-2.0 feature in the server configuration
as described in 1.3.1, “Feature management” on page 15.

The following list notes the key steps for creating a JPA application outside of the
Liberty profile developer tools environment:
򐂰 Creating the UserEntity class that maps to the database table USERTBL.
򐂰 Creating the persistence.xml file.
򐂰 Adding a persistence context reference to the deployment descriptor.

As with other types of applications, the dynamic nature of the Liberty profile
server speeds up application development by allowing you to make iterative
updates to your JPA application without having to restart the application
or server.

5.3 Developing Enterprise Java Bean applications

The Enterprise Java Bean (EJB) specification describes a component model for
business logic in server applications. WebSphere Liberty Profile Server supports
the EJB 3.1 Lite specification and Message Driven Beans (MDB). The EJB 3.1
Lite specification is a subset of the full EJB specification. It provides many of the
core components of the EJB specification, such as session beans, JPA,
transactions, and security. For more information about EJB 3.1, see the following
Information Center website:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
base.doc/ae/cejb_ejb31spec.html

5.3.1 Developing EJB applications in the Liberty profile developer

tools
The Liberty profile developer tools facilitate the development of EJB applications
by providing wizards that help generate portions of the EJB code. Use the
following sections and procedures to create and test a simple stateless
session bean.

Chapter 5. Data access in the Liberty profile 123

 Creating an EJB project
To create an EJB project, complete the following steps:
1. Begin by creating a new EJB project to hold the EJB application. Click File 
New  EJB Project. On the first page of the New EJB Project wizard, enter
ITSOEJB in the Project name field.
2. Make sure that WebSphere Application Server V8.5 Liberty Profile is selected
for the Target run time. Also, ensure that the Add project to an EAR check
box is selected, and that ITSOWebEAR is specified as the EAR project name.
3. Click Finish to complete the wizard. A new project named ITSOEJB is created
after you exit the wizard.

Creating the EJB

After creating the EJB project, complete the following steps to create the EJB:
1. Right-click the ITSOEJB project and select New  Session Bean (EJB 3.x),
which starts the Create EJB 3.x Session Bean wizard.
2. In the first window of the wizard, enter com.itso.example in the Java package
field and ExampleEJB in the Class name field. Ensure that Stateless is
specified for the State type field.
3. Click Next to advance to the next window, and then click Finish. The wizard
now creates a class named ExampleEJB. Notice that the class is annotated
with @Stateless and @LocalBean.
4. Now, complete the EJB implementation by adding a method that is named
hello that returns the string Hello, ITSO EJB. The completed class is shown
in Figure 5-16.

Figure 5-16 ExampleEJB class

Enabling the EJB feature

After creating the EJB, complete the following steps to enable the EJB feature
(automatically or manually):
1. To run EJB applications, the ejbLite-3.1 feature must be enabled. The
Liberty profile developer tools prompt you to add this feature, as shown in
Figure 5-17 on page 125.

124 WebSphere Application Server Liberty Profile Guide for Developers

 Figure 5-17 Automatic enabling of the ejbLite-3.1 feature

2. You can also add it manually by selecting Feature Manager in the server
configuration, clicking Add, and selecting ejbLite-3.1.

Creating a test client

To create a test client, complete the following steps:
1. Using the Create New Servlet wizard, create a servlet in the ITSOWeb project
named ExampleEJBServlet. In the generated class, add a field named
statelessBean of type ExampleEJB. Annotate the field with @EJB.
2. You might see an error resolving the ExampleEJB class. If so, you must set
up the build path for the ITSOWeb project so that it depends on the ITSOEJB
project. To do so, right-click the ITSOWeb project and select Properties.
Select Java Build Path and then click the Projects tab. Click Add and then
select the ITSOEJB project.

Chapter 5. Data access in the Liberty profile 125

 3. In the servlet’s doGet method, print the results of calling the hello method on
statelessBean. The completed servlet is shown in Figure 5-18.

Figure 5-18 ExampleEJBServlet class

4. Now, test the application by visiting the link:

http://localhost:9080/ITSOWeb/ExampleEJBServlet

Result: You should see the output Hello, ITSO EJB in your web browser. This
shows that the EJB was automatically injected into the statelessBean field and
that the servlet was able to successfully start the method hello.

5.3.2 EJB applications outside the Liberty profile developer tools

To develop EJB applications outside of the Liberty profile developer tools, enable
the ejblite-3.1 feature in the server configuration, as described in 1.3.1,
“Feature management” on page 15.

5.4 Developing message driven bean applications

In addition to the EJB lite 3.1 specification, Liberty profile server provides support
for the Message Driven Bean (MDB) 3.1 specification. Message driven beans
allow you to construct enterprise beans that operate asynchronously on
messages that are received from other Java EE components.

126 WebSphere Application Server Liberty Profile Guide for Developers

5.4.1 Developing message driven bean applications in the Liberty
profile developer tools
The Liberty profile developer tools simplify the development of message driven
beans by providing wizards for creating message driven beans and for creating
related JMS resources.

Creating message driven bean resources

The following example maximizes the resources that are created in the JMS
example in 3.1.6, “Developing Java Message Service web applications with the
Liberty profile developer tools” on page 66, including the messaging engine,
topic space, and JMS Topic. For this message driven bean example, you also
must create a JMS activation specification and properties.

To create a JMS activation specification, complete the following steps:

1. Right-click the server configuration and select Add  JMS Activation
Specification.
2. In the details window, specify a value for the Id field. The value must be in the
format application name/module name/bean name, where application name
is the name of the EAR application, module name is the name of the module
in which the message driven bean is packaged, and bean name is the
ejb-name of the enterprise bean. For this example, enter the value
ITSOApplication/ITSOEJB/ExamplePubSubMDB.

You also must add properties to the JMS activation specification to indicate that
you are using the embedded messaging engine and to specify the JMS Topic to
be used. To do this, complete the following steps:
1. Click JMS Activation Specification in the server configuration and
click Add.
2. Select WebSphere Embedded JMS Activation Specification in the dialog
box.
3. On the details window for the properties, enter ITSOTopic in the Destination
reference field. In the Destination type field, change the drop-down value so
that it reads javax.jms.Topic.

Creating the message driven bean

To create a message driven bean, complete the following steps:
1. Right-click the ITSOEJB project and select New  Message Driven Bean

Chapter 5. Data access in the Liberty profile 127

 2. In the message driven bean wizard, enter the package name
com.itso.example and the class name ExamplePubSubMDB. For the
destination name, enter ITSOTopic. This is the ID of the JMS Topic that we
created in 3.1.6, “Developing Java Message Service web applications with the
Liberty profile developer tools” on page 66.
3. Click Next and then click Finish to create the message driven bean. The
ExamplePubSubMDB class is generated with annotations that indicate the
JMS resources that are used.
4. To finish implementing the ExamplePubSubMDB class, modify the onMessage
method so that it prints the message that is received by the console. The
completed message driven bean class is shown in Figure 5-19.

Figure 5-19 Completed ExamplePubSubMDB class

Enabling features
After saving the message driven bean class and resources, the Liberty profile
developer tools should automatically prompt you to enable the jmsMdb-3.1
feature. To add this feature manually, complete the following steps:
1. Select Feature Manager in the server configuration.
2. Click Add, and select the jmsMdb-3.1 feature.

Testing the message driven bean

To test the message driven bean, we use the JMSTopicExample servlet from
3.1.6, “Developing Java Message Service web applications with the Liberty
profile developer tools” on page 66. Visit the link:
http://localhost:9080/ITSOWeb/JMSTopicExample

128 WebSphere Application Server Liberty Profile Guide for Developers

 Result: You should see the output Received message from publisher:
Hello, subscriber in the server console. The servlet also indicates that it
received the same message.

5.4.2 MDB applications outside the Liberty profile developer tools

When developing message driven bean applications outside of the Liberty profile
developer tools, there are several key considerations:
򐂰 You must enable the jmsMdb-3.1 feature in the server.xml file.
򐂰 When you compile your application, you can find the API classes in
dev/api/spec/com.ibm.ws.javaee.ejb.3.1_1.0.0.jar.
򐂰 You must add a jmsTopic or jmsQueue element for each topic or queue you
want to use.
򐂰 Each jmsTopic and jmsQueue must have a nested properties.wasJms
element, even if there are no attributes that are specified.
򐂰 You must add a jmsActivationSpec element to the server.xml file, and its id
attribute must be in the form Application Name/Module Name/Bean Name.
򐂰 The JMS activation specification should have a nested properties.wasJms
element that has a destinationRef attribute that specified the topic or queue
to use. It must also have a destinationType attribute that specifies whether
the destination is a topic or a queue.

5.5 Data access with MongoDB

MongoDB is a lightweight open source NoSQL database. Although it lacks
traditional database features such as transaction management and defined
schemas, its simple development and ability to scale horizontally make it a good
choice for some applications.

5.5.1 Developing MongoDB applications with the Liberty profile

developer tools
The Liberty profile developer tools can facilitate the development of data access
applications using MongoDB by simplifying the setup of required resources. Use
the following sections and procedures to create an example application that
stores, retrieves, and deletes data from a MongoDB database.

Chapter 5. Data access in the Liberty profile 129

 Installing MongoDB
For this example, you need a running instance of MongoDB. For more
information about downloading, installing, and running MongoDB, go to the
following link:
http://www.mongodb.org

Setting up the MongoDB JDBC driver

To set up the MongoDB JDBC driver, complete the following steps:
1. Download the MongoDB JDBC driver from the MongoDB website. Make sure
to download Version 2.10.1 or later. Save the JDBC driver JAR file in the
location on disk where you want the Liberty profile server to access the driver.
2. Now, configure the Liberty profile server so that the MongoDB JDBC driver is
visible to it. The procedure is similar to the one found in 5.1.2, “Adding a data
source using Liberty profile developer tools” on page 107, but is different in
that only a file set and JDBC driver is created in the configuration in
this scenario.
3. Create a shared library. Select the Server configuration, click Add, and
select Shared Library. In the details window for the shared library, enter the
value mongoLibrary in the Id field. Click the Add button next to the Fileset
reference field to add a file set to the shared library. In the Base directory
field, enter the directory where you saved the MongoDB JDBC driver JAR file.
In the Includes pattern field, enter the JDBC driver JAR file name. For Version
2.10.1, the file name is mongo-java-driver-2.10.1.jar.
4. Now you must make the shared library available to the application
classloader. If you did not create a classloader for the ITSOWebEAR
application in the earlier examples, you must do so now. Select the
ITSOWebEAR application in the server configuration, click Add, and select
Classloader. If the Classloader element under the ITSOWebEAR application
already exists, select it now.
5. In the Classloader Details window, click the Browse button next to the
Shared library references field. Select mongoLibrary from the list of available
IDs and click OK.

130 WebSphere Application Server Liberty Profile Guide for Developers

Configuring MongoDB in the server configuration
To configure MongoDB in the server configuration, complete the following steps:
1. Create a Mongo instance in the server configuration.
a. Select the server configuration, click Add, and then select Mongo.
b. The details window contains several different options for configuring the
Mongo instance, but you can keep all of the defaults except for the Id and
MongoDB Java driver library reference. In the Id field, enter
mongoInstance1. In the Java driver library reference field, use the
drop-down menu to select mongoLibrary.
2. Create a MongoDB DB in the configuration.
a. Select the server configuration, click Add, and then select MongoDB DB.
b. In the JNDI name field, enter the value jndi/mongoDB.
c. In the database name field, enter exampleDB.
d. Use the Mongo instance reference drop-down menu to select
mongoInstance1.

Enabling the MongoDB feature

You must enable the MongoDB feature to run MongoDB data access applications
on Liberty profile server. Enable the feature by selecting the Feature Manager in
the server configuration. Click Add, and select the mongodb-2.0 feature.

Creating an application
To test the MongoDB setup, we create a web application with two parts. A JSP
file is used to display an input form, and a servlet is used to interact with the
MongoDB instance and return results. Complete the following steps:
1. Begin by creating a JSP file named mongoInput.jsp in the ITSOWeb project
by using the New JSP File wizard. On the template selection page, choose
New JSP File (html).

Chapter 5. Data access in the Liberty profile 131

 2. In the JSP file, add a form that has an input field named Item and an input
field named Price. The action attribute for the form should be MongoServlet
and the method attribute should be POST. Add three submit buttons to the
form, labeled Add to Catalog, Find in Catalog, and Delete from Catalog.
Figure 5-20 shows the completed mongoInput.jsp file.

Figure 5-20 Example mongoInput.jsp file

3. Create a servlet named MongoServlet in the ITSOWeb project by using the

Create Servlet wizard. In the servlet, access is needed to the APIs that are
contained in the MongoDB JDBC driver JAR file. Add this JAR file to the build
path for the ITSOWeb project by right-clicking the project and selecting
Properties. Select Java Build Path, and then click the Libraries tab. Then,
proceed with one of the following two options:
– If your MongoDB JDBC driver JAR file is in your Eclipse workspace, click
Add to add it to the build path.
– Otherwise, click Add External Jars and navigate to the location of the
JAR file. When you add the JAR file to the build path, click OK to update
the project.
4. In the servlet, add a field of type com.mongodb.DB named mongoDB. Add the
annotation @Resource(name = “jndi/mongoDB”) to the field so that the Liberty
profile server injects the DB instance automatically.
5. All of the database access takes place in the doPost method. In the doGet
method, add the code in Example 5-7 to forward the request to the
mongoInput.jsp file.

Example 5-7 Code to forward the request

RequestDispatcher rd =
request.getRequestDispatcher(“mongoInput.jsp”);
rd.forward(request, response);

6. In the doPost method, obtain a DBCollection object by calling the

getCollection method on the mongoDB field. The method parameter
identifies the collection name. For this example, we use the name catalog.

132 WebSphere Application Server Liberty Profile Guide for Developers

7. Also, in the doPost method, create a com.mongodb.BasicDBObject instance
named dbObject. Store the request parameters for item and price in the
dbObject by using the append method. Continue with the following
configuration options:
– If the request parameter add is not null, call insert on the DBCollection
object, passing in dbObject.
– If the request parameter find is not null, call find on the DBCollection
object, passing in dbObject. The find method returns a
com.mongodb.DBCursor object. Use the size method on DBCursor to
determine the number of results.
– If the request parameter delete is not null, run the remove method on the
collection object, again passing in the dbObject. The remove method
returns an object of type com.mongodb.WriteResult. You can use the getN
method on the WriteResult object to determine how many results were
deleted from the database.
8. Now call the find method on the DBCollection object without passing in any
parameters. This returns a DBCursor object that contains all entries in the
catalog collection. Iterate through the results using the hasNext and next
methods on DBCursor. The next method returns a DBObject instance that
you can use to obtain the data.

Chapter 5. Data access in the Liberty profile 133

 9. Finally, obtain a RequestDispatcher instance and call the include method to
include the contents of the mongoInput.jsp file. The completed doPost
method is shown in Figure 5-21.

Figure 5-21 Example doPost method

Testing the application

Test the application by visiting the link:
http://localhost:9080/ITSOWeb/MongoServlet

134 WebSphere Application Server Liberty Profile Guide for Developers

 Result: You should be able to use the web page to add, find, and remove
items from the database. For the find operation to succeed, both input fields
must match the corresponding fields in a database entry.

5.5.2 Developing MongoDB applications outside of the Liberty profile

developer tools
When developing MongoDB applications for Liberty profile server in
environments other than the Liberty profile developer tools, you must take into
account the following considerations.
򐂰 The mongodb-2.0 feature must be added to the list of features in the
server.xml file.
򐂰 You must create library and fileset elements to reference the MongoDB
JDBC driver file.
򐂰 A mongo element is required in server.xml file to define a MongoDB instance.
The element should have an id attribute that has some unique value and a
libraryRef attribute equal to the id attribute of the library element.
򐂰 You also need a mongoDB element with jndiName and databaseName attributes.
The element should also have a mongoRef attribute that specifies the value of
the id attribute of the mongo element.

Chapter 5. Data access in the Liberty profile 135

136 WebSphere Application Server Liberty Profile Guide for Developers
 6

Chapter 6. Configuring application

security
Security is an essential component of any enterprise-level application. In this
chapter, we provide you with a basic introduction to security using the Liberty
profile.

The chapter contains the following sections:

򐂰 Enabling SSL
򐂰 HTTPS redirect
򐂰 Form login
򐂰 Securing JMS applications
򐂰 JAX-WS security
򐂰 Securing MongoDB applications

It is beyond the scope of this book to describe all aspects of security and how to
configure them. For more information about security and how to implement
specific security models not covered by this chapter (such as LTPA or SSO) see
the Information Center at the following website:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
wlp.nd.doc/ae/twlp_sec_webappsecurity.html

© Copyright IBM Corp. 2012, 2013. All rights reserved. 137

6.1 Enabling SSL
You can configure the Liberty profile server to provide secure communication
between a client and the server by enabling SSL. To establish secure
communication, a certificate and an SSL configuration must be specified.

The keystore and certificate can be created either by using the WebSphere
developer tools or from the command line. For development, you usually use a
self-signed certificate, as shown in our examples.

Important: On production servers, import a certificate from a trusted provider

to the server keystore rather than using a self-signed certificate.

6.1.1 Configuration using the WebSphere developer tools

Use the WebSphere developer tools to add the keystore and self-signed
certificate to your server using the following steps:
1. Open the Servers view in the workbench.
2. Right-click your server and select Utilities  Create SSL Certificate, as
shown in Figure 6-1.

Figure 6-1 Selecting to crete the SSL Certificate using WebSphere developer tools

3. You are prompted to create a password for your keystore and optionally set
the validity period or subject for the certificate, as shown in Figure 6-2 on
page 139.

138 WebSphere Application Server Liberty Profile Guide for Developers

 Figure 6-2 Entering values for the keystore and certificate

4. Enter the required values and click Finish. The Console window shows the
output of the command, as shown in Figure 6-3.

Figure 6-3 Output from the creation of the SSL Certificate

Chapter 6. Configuring application security 139

 5. The output contains the values that must be entered into the server
configuration. You can either paste the required values directly into the
server.xml configuration file (in which case your configuration is complete
and you can proceed to “HTTPS redirect”) or alternatively use the Design
view to be guided through the configuration as shown in the following steps:
6. In the Servers view, expand the server until you see the Feature Manager
entry. Double-click the Feature Manager or right-click and select Open.
7. The Feature Manager window opens. Under Feature Manager Details click
Add, as shown in Figure 6-4.

Figure 6-4 Adding a feature using the Feature Manager

8. In the Add Feature dialog, select ssl-1.0 from the list and click OK.
9. On the left side of the Feature Manager window, you see the Configuration
Structure being displayed. To add in the keystore, select Server
Configuration and click Add, as shown in Figure 6-5.

Figure 6-5 Adding new items to the configuration structure

140 WebSphere Application Server Liberty Profile Guide for Developers

 10.Scroll down the list until you find the keystore entry. Select keystore and then
click OK.
11.The keystore configuration now appears under the Server Configuration. The
keystore details are shown in the right side of the window (if they are not
shown, select Keystore in the Server Configuration).
12.In the Id field, enter defaultKeyStore.
13.Click Set next to the Password field and enter the password you used when
creating your keystore during step 3 on page 138.
14.Your configuration is now complete. Save the changes to the server
configuration. The server (if started) now detects the new settings and the
SSL port is opened.
15.If you have applications that are installed on your server, you now can access
them by specifying https:// and pointing your browser to the https port
defined in your server configuration, httpEndpoint.

6.1.2 Configuration using the command line

To create the keystore and generate the self-signed certificate using the
command line, you must use the securityUtility command that is in
${wlp.install.dir}/bin. Example 6-1 shows the command and the
expected output.

Example 6-1 Using the securityUtility command

C:\Liberty\v85Runtime\bin>securityUtility createSSLCertificate
--server=myThirdServer --password=passw0rd --validity=365
--subject="CN=liberty,O=IBM,C=US"

Creating keystore
C:\Liberty\v85Runtime\usr\servers\myThirdServer\resources\security\key.
jks

Created SSL certificate for server myThirdServer

Add the following lines to the server.xml to enable SSL:

<featureManager>
<feature>ssl-1.0</feature>
</featureManager>
<keyStore id="defaultKeyStore" password="{xor}Lz4sLChvLTs=" />

Chapter 6. Configuring application security 141

 The output from the command contains the information to be added into your
server configuration to enable SSL. Cut and paste this output into your
server.xml file. The server automatically detects the changes and activates the
SSL port.

6.2 HTTPS redirect

With SSL enabled, the client can, in most cases, still access the application on
both the secure and nonsecure port. HTTPS redirect allows you to always direct
the client to the secure HTTPS port even if the client requested the standard
nonsecure port.

This section assumes that you are starting with the web application created in
Chapter 3, “Developing and deploying web applications” on page 45. If you do
not have this application in your project workspace, you can find a completed
version included in the download material for this book. For more information see
Appendix A, “Additional material” on page 215.

To access and edit the available web applications to work with HTTPS redirect,
complete the following steps:
1. In Project Explorer, expand your web application and right-click the
deployment descriptor. Select Open With  Web Application 3.0
Deployment Descriptor EditorIf you do not see Web Application 3.0
Deployment Descriptor Editor in the menu, select Other and select the
correct editor.
2. To enable HTTPS redirect, add a security constraint to your application. To
do this, select Web Application in the Overview section and then click Add,
as shown in Figure 6-6 on page 143.

142 WebSphere Application Server Liberty Profile Guide for Developers

 Figure 6-6 Adding a security constraint to the deployment descriptor

3. In the Add Item window, scroll down and select Security Constraint, then
click OK.
4. The Security Constraint now appears in the Overview section. Next, define
the Web Resource Collection for the Security Constraint. This identifies which
addresses are covered by the Security Constraint. Expand the Security
Constraint in the Overview section and select Web Resource Collection.

Chapter 6. Configuring application security 143

 5. The details window, to the right of the Editor, allows you to enter the details of
the Web Resources. Give the Web Resource Collection a name and add in
the URL Patterns to be used, as shown in Figure 6-7.

Figure 6-7 Entering details for the Web Resource Collection

6. Next, specify the details of the Security Constraint. In the Overview section,
select Security Constraint. The details window now allows you to define the
Security Constraint.
7. Give the Security Constraint a name. Under the User Data Constraint section,
select CONFIDENTIAL for the transport guarantee, as shown in Figure 6-8
on page 145. This specifies that we allow only secure communication with the
web resource collection.

144 WebSphere Application Server Liberty Profile Guide for Developers

 Figure 6-8 Specifying the confidential transport

8. Our example currently applies the HTTPS redirect to all communications with
the addresses defined in the Web Resource Collection. To apply this redirect
to only specific HTTP methods, right-click the Web Resource Collection in
the Overview section and select Add  HTTP Method. We restrict our
HTTPS redirect to GET requests only by entering GET for the HTTP Method.
9. The next step is to enable application security. In the server view, expand the
server until you see the Feature Manager entry. Double-click the Feature
Manager or right-click and select Open.
10.The Feature Manager window opens. Click Add, select appSecurity-2.0
from the list, and click OK.
11.HTTPS redirect is now fully configured. Save your changes and WebSphere
Developer Tool automatically updates the server with the new version of your
application. If you now attempt to access the application at
http://localhost:9080/ITSOWeb/HelloITSO, you notice that you are always
redirected to https://localhost:9443/ITSOWeb/HelloITSO.

Chapter 6. Configuring application security 145

6.3 Form login
One of the most common ways to provide an authentication method to users of a
web application is to use form-based login. This presents the users with a form
where they can provide their login credentials. This section describes how to
update your application and server to provide the form-based login.

This section expands on the HTTPS redirect example in 6.2, “HTTPS redirect” on
page 142.

6.3.1 Defining the basic user registry

The first step in configuring form login is to create and define the actual registry
that is used for authentication. In our example, we use a Basic User Registry.
However, the Liberty profile does support other registries, including Active
Directory and LDAP. The following website provides more information about
configuring the Liberty profile to work with these other registries:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
wlp.nd.doc/ae/twlp_sec_authenticating.html

Use the following steps to create and define the registry for authentication using
a Basic User Registry:
1. Update the server.xml configuration file with the form login configuration.
Open the server view in your workbench and double-click the Server
Configuration for your server. This opens your server.xml file. Switch to the
design tab if it is not already selected.
2. In the Configuration Structure section on the left, select the Feature
Manager. The Feature Manager details are displayed on the right, as shown
in Figure 6-9 on page 147.

146 WebSphere Application Server Liberty Profile Guide for Developers

 Figure 6-9 Viewing the Feature Manager details

3. If the appSecurity-2.0 feature is not already in the list of features, click Add
and select the appSecurity-2.0 feature.

4. We add the basic registry that is used for our authentication. Under the
Configuration Structure, select Server Configuration and click Add, as
shown in Figure 6-10.

Figure 6-10 Adding items to the server configuration

5. Select Basic User Registry and click OK.

Chapter 6. Configuring application security 147

 6. Select Basic User Registry in the Configuration Structure. Under the Basic
User Registry Details section on the right, enter an ID and Realm name for
your registry, as shown in Figure 6-11.

Figure 6-11 Entering the Basic Registry details

7. Now that we have our basic user registry, we must add users and groups to it.
Click Add.
8. In the resulting window, select User and click OK.
9. A user object now appears under your basic user registry. Click the user
object. On the right, under User Details, enter a user name of User1 and then
click Set to enter a password, as shown in Figure 6-12.

Figure 6-12 Adding a user

10.Enter the password and click OK. You have now created a user for the basic
registry. Repeat the process and add another user that is called User2.
11.Then, add a security group to the basic user registry. Select the Basic User
Registry and click Add....
12.Select group from the Add Item window and click OK.
13.A group element appears under your basic user registry. Ensure that it is
selected and under Group Details enter Group1 as the group name.

148 WebSphere Application Server Liberty Profile Guide for Developers

 14.We now must add users to the group. Select the group under the
Configuration Structure and click Add. In the Add Item window, select
member and click OK.
15.Select the member element that appears under the group. In the Group
Member Details window, enter User1 for the User name.
16.Save the changes. Your configuration Structure should now contain the basic
user registry structure, as shown in Figure 6-13.

Figure 6-13 The completed basic user registry

6.3.2 Updating an application to support Form Login

To use Form Login for your application, you must make a number of changes to
the application and its configuration. These changes are needed to allow the
user to authenticate. The following sections describe the changes in detail.

Adding the login page

The user of the application must provide their login credentials to be
authenticated. To allow them to do this, provide a login page. This login page
must contain a form that requests the user name and password and must always
have the j_security_check action.

Example 6-2 shows an example form from the login.html page.

Example 6-2 The login form

<form method="POST" action="j_security_check">
<strong> Enter user ID and password: </strong>
<BR>

Chapter 6. Configuring application security 149

 <strong> User ID</strong> <input type="text" size="20"
name="j_username">
<strong> Password </strong> <input type="password" size="20"
name="j_password">
<BR>
<strong> Click submit to authenticate: </strong>
<input type="submit" name="login" value="Login">
</form>

Use the j_username input field to obtain the user name and use the j_password
input field to obtain the user password.

When a user requests a webpage that requires authentication, the web server
stores the original request and displays the login form. When the login form is
completed and the user is successfully authenticated, the web server redirects
the call to the original request.

Adding a login error page

If the authentication of a user fails, you must be able to advise the user of the
failure. This is done by adding a login error page to your application. Example 6-3
shows an example of a loginError.jsp file.

Example 6-3 An example login error page

<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
pageEncoding="ISO-8859-1"%>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"

"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;
charset=ISO-8859-1">
<title>Login Error</title>
</head>
<body>
<H1><B>A Form login authentication failure occurred</B></H1>
<P>Authentication might fail for one of many reasons. Some
possibilities include:
<OL>
<LI>The user ID or password might have been entered incorrectly; either
misspelled or the wrong case was used.
<LI>The user ID or password does not exist, has expired, or has been
disabled.
</OL>

150 WebSphere Application Server Liberty Profile Guide for Developers

</body>
</html>

Adding a form logout page

Form logout is a mechanism to log out without having to close all web browser
sessions. After logging out, access to a protected web resource will require
reauthentication.

The form logout page is an HTML or JSP file that you include with your web
application. This logout page contains a form with a special post action.
Example 6-4 provides an example of a logout.jsp file.

Example 6-4 A Sample logout page

<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
pageEncoding="ISO-8859-1"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;
charset=ISO-8859-1">
<title>Insert title here</title>
</head>
<body>
<h2>Sample Form Logout</h2>
<form method="POST" action="ibm_security_logout" name="logout">
<BR>
<strong> Click this button to log out: </strong>
<input type="submit" name="logout" value="Logout">
<input type="HIDDEN" name="logoutExitPage" value="/login.html">
</form>
</body>
</html>

The logoutExitPage specifies where the user is to be redirected after logging out.

Configuring the application

The final changes that are needed to the web application are in the configuration.
The web application must define the login mechanism and also restrict access to
the relevant endpoints.

Chapter 6. Configuring application security 151

 Although you do not need to do the HTTPS redirect as part of the form login, it is
advised because it ensures confidentiality of the login credentials. The following
steps expand upon the configuration you set up in 6.2, “HTTPS redirect” on
page 142 to define the login mechanism and limit the access to the
relevant endpoints:
1. In the Project Explorer, expand your web application and right-click the
deployment descriptor. Select Open With  Web Application 3.0
Deployment Descriptor Editor
2. The first configuration that must be added is a login configuration, which
defines the login mechanism. In the Overview section of the Deployment
Descriptor Editor, select Web Application and click Add, as shown in
Figure 6-14.

Figure 6-14 Adding a login configuration

3. Select Login Configuration from the list and click OK.

4. Click the login configuration. You can now define how the user logs in by
updating the properties for the login configuration, as shown in Figure 6-15 on
page 153.

152 WebSphere Application Server Liberty Profile Guide for Developers

Figure 6-15 Defining the login configuration settings

Note: The realm name is an optional attribute that is used for differentiating
between different repositories. If you have multiple repositories in your
server, each one can have a realm name. You can then use the realm
name to identify the repository to use for authentication. If you have only
one repository, you can leave this value blank.

Chapter 6. Configuring application security 153

 5. You now must restrict your endpoint to allow only certain users to access the
resource. This is done by adding a security constraint and adding an
authorization constraint to it. We already have a security constraint that we
added in 6.2, “HTTPS redirect” on page 142. We use this and add the
authorization constraint to it. Select the Security Constraint from within the
Overview section, as shown in Figure 6-16.

Figure 6-16 Selecting the Security Constraint

6. In the detail section, under Authorization Constraint, click Add to the right of
the Role Name. This adds a role that is required for access to the resource.
Give the role a name, as shown in Figure 6-17 on page 155.

154 WebSphere Application Server Liberty Profile Guide for Developers

 Figure 6-17 Adding an authorization role

Note: The Role Name within your application is a logical name and can be
any value that you like. In 6.3.3, “Defining bindings between the application
and the server” on page 155, you add mappings between your application
roles and the users and groups that are defined in your user registry.

7. The application changes are now complete. Save all the changes.

6.3.3 Defining bindings between the application and the server

The final step in enabling Form Login is to map the roles that are defined within
the application to the groups and users in your user registry. To do this, you must
add an application binding in your server configuration using the following steps:
1. Open the Server view in Eclipse and double-click Server Configuration for
your server. This opens your server.xml file. Switch to the design tab if it is
not already selected.

Chapter 6. Configuring application security 155

 2. In the Configuration Structure, select your application and click Add, as
shown in Figure 6-18.

Figure 6-18 Adding an application binding

3. Select Application Binding from the list and click OK.

4. We now must specify the role to map. This should be the role that you defined
in your application. Select the Application Binding under the Configuration
Structure and click Add.
5. Select security-role from the list and click OK.
6. Make sure that the security role is selected in the Configuration Structure and
complete the security role name, as shown in Figure 6-19.

Figure 6-19 Defining the security role name

7. Map the security role with the users and groups that are to be considered part
of this role. In our example, we are going to map Group1 to the
AuthorizedManager role. Select the security-role under the Configuration
Structure and click Add.

156 WebSphere Application Server Liberty Profile Guide for Developers

 8. Select group from the list and click OK.

Note: As well as user and group, you can also select the special-subject
option to assign access to either everyone or all authenticated users.

9. Select the Group element in the Configuration Structure and under Group
Details enter the name of the group that is to be allowed access to the
resource, as shown in Figure 6-20.

Figure 6-20 Entering the group details

10.Your Forms Login configuration is now complete. Save all changes.

If you now access your application, you are taken to the login window. When you
enter the user credentials, only User1, which is in Group1, has access to
the application.

6.4 Securing JMS applications

By default, JMS resources that are configured in the WebSphere Liberty profile
server can be accessed by any user. You can enable JMS security to ensure that
only authenticated and authorized users can access JMS resources, such as
queues and topics.

You can enable JMS security by manually editing the list of features in the server
configuration file to add wasJmsSecurity-1.0. You can also enable the feature in
the WebSphere developer tools by loading the server configuration editor and
adding the wasJmsSecurity-1.0 feature to the feature manager.

After you enable the JMS security feature, you must authenticate with an
authorized user to access any JMS resources.

Chapter 6. Configuring application security 157

6.4.1 Setting up user authentication
The first step to authenticating users is to create a user registry. Instructions for
creating a basic user registry can be found in 6.3.1, “Defining the basic user
registry” on page 146. You can also use a quickStartSecurity registry or an
LDAP registry.

Users can be authenticated within application code or by configuration. To

authenticate in application code, you pass in the user name and password as
parameters when you create a TopicConnection or QueueConnection in your
application. Example 6-5 shows how you use the JMS API to authenticate.

Example 6-5 Authenticating within application code

TopicConnectionFatory tcf = (TopicConnectionFActory) new
InitialContext().lookup(TOPIC_CONNECTION_FACTORY_JNDI_NAME);

TopicConnection tc = tcf.createTopicConnection(“user1”, “password1”);

To authenticate within the server configuration, you edit the properties for the
JMS Topic Connection Factory or JMS Queue Connection Factory to specify a
user name and password. Example 6-6 shows the configuration in the
server.xml file.

Example 6-6 Authenticating using properties.wasJms

<jmsTopicConnectionFactory id=”ITSO_CF” jndiName=”jndi/jmsTCF”>
<properties.wasJms userName=”user1” password=”password1”/>
</jmsTopicConnectionFactory>

158 WebSphere Application Server Liberty Profile Guide for Developers

 Figure 6-21 shows the window in the Liberty profile developer tools where you
specify the user name and password.

Figure 6-21 WebSphere Embedded Topic Connection Factory details window

6.4.2 Setting up user authorization

To access JMS resources, an authenticated user must be granted authorization
to access the resources. Authorization can be configured by editing the server
configuration to add roles, users, and groups.

Chapter 6. Configuring application security 159

 To complete this process, complete the following steps:
1. To begin, set up authorization in the Liberty profile developer tools. Open the
server configuration editor and select Messaging Engine. Click Add and
select Messaging Security, as shown in Figure 6-22.

Figure 6-22 Adding Messaging Security

2. Now select Role underneath Messaging Security. In the details window, enter
a name such as developer in the Role name field. With Role still selected,
click Add to add a user. In the User details window, enter a user name from
your user registry, such as User1.
3. Add permissions for the role by selecting Role, clicking Add, and selecting
Topic Permission. In the Action field of the details window, you can
configure whether the user is authorized to send messages, receive
messages, or both. Add an action by clicking the Add button next to the
Action field. This adds a value of SEND to the field. You can change this
value to RECEIVE or ALL by changing the value of the drop-down field.

160 WebSphere Application Server Liberty Profile Guide for Developers

 In the Topic name and TopicSpace reference fields, enter values that
correspond to the topic name and topic space values on the JMS topic
properties. If you did not specify any values for those fields in the JMS topic
properties, use the values Default.Topic and Default.Topic.Space, as shown
in Figure 6-23.

Figure 6-23 Topic Permission details window

You can also manually edit configurations. Example 6-7 shows the configuration
that must be added to the server.xml file for manual editing.

Example 6-7 Configuration for manual editing

<messagingEngine>
<messagingSecurity>
<role name=”developer”>
<user name=”User1”>
<topicPermission topicName=”Default.Topic”>
<action>ALL<action>

Chapter 6. Configuring application security 161

 </topicPermission>
</role>
</messagingSecurity>
</messaging>

6.5 JAX-WS security

Web services in Liberty profile server can be secured either at the transport layer
or at the messaging layer. Configuring transport security allows you to
authenticate and ensure confidentiality of HTTP communications between a web
service client and a web service provider. Transport security can be enabled
using SSL, basic authentication, or client certificate authentication.

Message level security allows you to secure SOAP messages that are
exchanged between web service clients and web service providers using
WS-Security standards. WebSphere Liberty profile supports the following web
service standards:
򐂰 Web Services Security SOAP Message Security 1.1
򐂰 Web Services Security Username Token Profile 1.1
򐂰 Web Services Security X.509 Certificate Token Profile 1.1
򐂰 WS-SecurityPolicy 1.3

This section provides an example of how to secure a web service using SSL at
the transport layer and Username Token authentication at the message layer.
For more information about other ways to secure web services, see the following
Information Center website:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
wlp.doc/ae/cwlp_wssec.html

This example builds on the JAX-WS example in 3.1.7, “Developing JAX-WS web
services applications with the Liberty profile developer tools” on page 72. Before
you begin, make sure that you enabled SSL by creating a keystore, as described
in 6.1, “Enabling SSL” on page 138. Also, make sure that the appSecurity-2.0
feature is enabled.

In addition to creating a keystore, you must create an SSL Default Repertoire. To

complete that process, complete the following steps:
1. In the Liberty profile developer tools server configuration editor, create the
default repertoire by selecting the server configuration element.

162 WebSphere Application Server Liberty Profile Guide for Developers

2. Click Add and then select SSL Default Repertoire. In the details window,
enter defaultSSLConfig in the Default SSL repertoire field. Outside of the tool
environment, create the sslDefault element, as shown in Example 6-8.

Example 6-8 Default SSL Repertoire

<sslDefault sslRef=”defaultSSLConfig”/>

3. You must also enable HTTPS redirect for the pattern /ITSOGreeterService so
that requests to the web service over HTTP are redirected to the SSL port
using HTTPS. To accomplish this task, use the procedure in 6.2, “HTTPS
redirect” on page 142. After enabling redirect, test that it is working by visiting
the following link:
http://localhost:9080/ITSOWeb/ITSOGreeterService?wsdl
You should be redirected to the following ULR:
https://localhost:9443/ITSOWeb/ITSOGreeterService?wsdl
You should see the contents of the WSDL document.
4. To enable the web services security run time, you must enable the
wsSecurity-1.1 feature in the server configuration.
5. To configure the JAX-WS run time to send a Username Token with web
service client requests, you can add a wsSecurityClient element to the
server configuration. When it is specified, the WS-Security client configuration
becomes the default configuration for all web services clients on the server.
The configuration might be overridden programmatically by passing in
property values on the RequestContext in the client code. Example 6-9 shows
an example WS-Security client configuration.

Example 6-9 WS-Security Client configuration

<wsSecurityClient ws-security.password=”password1”
ws-security.username=”user1”/>

6. The WS-Security provider can also have a default configuration that is

specified in the server configuration. To specify that web service providers
should place the identity of the Username Token from the SOAP message on
the thread, configure a wsSecurityProvider element in the server.xml file, as
shown in Example 6-10.

Example 6-10 WS-Security Provider configuration

<wsSecurityProvider ws-security.username=”user1”>
<callerToken name=”UsernameToken”/>
</wsSecurityProvider>

Chapter 6. Configuring application security 163

 7. You also must configure the WSDL for the web service provider and client to
enforce SSL and to require a user name token. The Liberty profile developer
tools make it easy to add web service security policy templates to the WSDL.
8. If you did not generate a WSDL file for the web service, you can do so now by
following the procedure in “Creating a web service” on page 73 and making
sure that the Generate WSDL file into the project option is selected on the
second window. The wizard does not overwrite any existing artifacts without
confirmation, so you do not lose any modifications that you made.
Begin by expanding ITSOWeb  Services and selecting
(http://example.itso.com/ITSOGreeterService). Right-click the service and
select Add Security Policy to Service WSDL. In the wizard, give the policy
a name, such as UsernameTokenSSL. In the drop-down field for Policy
template, select Username Token with password text, nonce, and created
time stamp over SSL, as shown in Figure 6-24.

Figure 6-24 Web Service Security Policy wizard

164 WebSphere Application Server Liberty Profile Guide for Developers

 9. Click Next and then select the check box to attach the security policy to the
ITSOGreeterPortBinding. Click Finish and open the WSDL document in
ITSOWeb/WebContent/WEB-INF/wsdl. A Policy element is added with the name
UsernameTokenSSL. Also, there is now a PolicyReference element underneath
the binding element. With these changes to the WSDL file, the web service
now generates an error if a client attempts to access the service without SSL
or without a user name token.
In the same WSDL file, we can ensure that SSL is used by changing the
address for the ITSOGreeterPort. The new service definition is shown in
Example 6-11.

Example 6-11 ITSOGreeterService definition

<service name=”ITSOGreeterService”>
<port name=”ITSOGreeterPort”
binding=”tns:ITSOGreeterPortBinding”>
<soap:address
location=”https://localhost:9443/ITSOWeb/ITSOGreeterService”/>
</port>
</service>

10.You can attempt to test these changes now by visiting the link
http://localhost:9080/ITSOWebClient/JAXWSGreeterClient. However, the
test fails because the client does not send a user name token.
11.Now, make the same changes that were made to the provider WSDL to add
the WS-Security policy and update the address to the client WSDL in the
ITSOWebClient project. After making these changes, you can again try
visiting the test client. This time, you should see the output Hello, JAX-WS
Client from the ITSO Greeter that indicates that the service was
successfully started.

6.6 Securing MongoDB applications

Applications using MongoDB can be secured by using either application
managed security or container managed security. You must also enable access
control on the MondoDB instance. For more information about enabling database
authorization in MongoDB, see the following website:
http://docs.mongodb.org/manual/core/security/

Chapter 6. Configuring application security 165

 In application managed security, you make changes inside the application code
to authenticate with the MongoDB instance. The code in Example 6-12 shows
how to use the MongoDB APIs to authenticate.

Example 6-12 Authenticating with a MongoDB instance

// mongoDB is an instance of com.mongodb.DB
if (!mongoDB.isAuthenticated())
mongoDB.authenticate(“user1”, “password1”.toCharArray());

In container managed security, you edit the server configuration to specify a user
name and password for the MongoDB instance. Example 6-13 shows how you
specify the user name and password in the server.xml file.

Example 6-13 Configuring authentication in a server.xml file

<mongo id=”mongoInstance1” libraryRef=”mongoLibrary” user=”user1”
password=”password1”/>

166 WebSphere Application Server Liberty Profile Guide for Developers

 You can also edit the configuration in the Liberty profile developer tools.
Figure 6-25 shows the Mongo details window where you enter the user name
and password.

Figure 6-25 Details window for configuration

Chapter 6. Configuring application security 167

168 WebSphere Application Server Liberty Profile Guide for Developers
 7

Chapter 7. Serviceability and

troubleshooting
The Liberty profile has several tools to help identify problems with the server and
the applications that are deployed to it.

The chapter contains the following sections:

򐂰 Trace
򐂰 Server memory dump
򐂰 MBeans and JConsole

© Copyright IBM Corp. 2012, 2013. All rights reserved. 169

7.1 Trace
The Liberty profile can produce various traces that enable you to debug issues
with the server and your applications. By default, limited information is reported,
however; you can request more trace information if required. In this section, we
describe where to find the output and how to configure what trace data
is collected.

7.1.1 Inspecting the output logs

The Liberty profile server records limited information by default. This basic
information is useful for debugging common configuration issues. You can view
the output logs by opening the ${server.config.dir}/logs/messages.log file.
Example 7-1 shows a sample output from a server start.

Example 7-1 Sample content of the message.log file

[05/09/12 16:48:15:350 EDT] 00000001
.ibm.ws.kernel.launch.internal.platform.FrameworkManagerImpl A CWWKE0001I: The
server myFirstServer has been launched.
[05/09/12 16:48:17:063 EDT] 00000001
.ibm.ws.kernel.launch.internal.platform.FrameworkManagerImpl I CWWKE0002I: The
kernel started after 1.866
[05/09/12 16:48:17:063 EDT] 00000028
com.ibm.ws.kernel.feature.internal.FeatureManager I CWWKF0007I:
Feature update started.
[05/09/12 16:48:17:309 EDT] 0000001d
com.ibm.ws.security.internal.SecurityReadyService I CWWKS0007I: The
security service is starting...
[05/09/12 16:48:17:449 EDT] 0000001d com.ibm.ws.tcpchannel.internal.TCPChannel
I CWWKO0219I: TCP Channel defaultHttpEndpoint has been started and is now
listening for requests on host 127.0.0.1 (IPv4: 127.0.0.1) port 9080.
[05/09/12 16:48:18:162 EDT] 00000035 com.ibm.ws.tcpchannel.internal.TCPChannel
I CWWKO0219I: TCP Channel defaultHttpEndpoint-ssl has been started and is now
listening for requests on host 127.0.0.1 (IPv4: 127.0.0.1) port 9443.
[05/09/12 16:48:18:411 EDT] 0000001d
com.ibm.ws.app.manager.internal.monitor.DropinMonitor A CWWKZ0058I:
Monitoring dropins for applications.
[05/09/12 16:48:18:456 EDT] 00000021
com.ibm.ws.app.manager.internal.statemachine.StartAction I CWWKZ0018I:
Starting application ITSOWeb.
[05/09/12 16:48:18:560 EDT] 00000033
com.ibm.ws.security.internal.SecurityReadyService I CWWKS0008I: The
security service is ready.

170 WebSphere Application Server Liberty Profile Guide for Developers

 [05/09/12 16:48:18:562 EDT] 00000033
com.ibm.ws.security.token.ltpa.internal.LTPAKeyCreator I CWWKS4105I: LTPA
configuration is ready after 0.25 seconds.
[05/09/12 16:48:19:765 EDT] 00000021
com.ibm.ws.webcontainer.osgi.webapp.WebGroup I SRVE0169I:
Loading Web Module: ITSOWeb.
[05/09/12 16:48:19:766 EDT] 00000021 com.ibm.ws.webcontainer
I SRVE0250I: Web Module ITSOWeb has been bound to default_host.
[05/09/12 16:48:19:767 EDT] 00000021 com.ibm.ws.http.internal.VirtualHostImpl
A CWWKT0016I: Web application available (default_host):
http://localhost:9080/ITSOWeb/*
[05/09/12 16:48:19:768 EDT] 00000021 com.ibm.ws.webcontainer.osgi.WebContainer
I SRVE9998I: Application ITSOWeb added to web container.
[05/09/12 16:48:19:769 EDT] 00000021
com.ibm.ws.app.manager.internal.statemachine.StartAction A CWWKZ0001I:
Application ITSOWeb started in 1.313 seconds.
[05/09/12 16:48:19:835 EDT] 00000028
com.ibm.ws.kernel.feature.internal.FeatureManager I CWWKF0008I:
Feature update completed in 2.772 seconds.
[05/09/12 16:48:19:835 EDT] 00000028
com.ibm.ws.kernel.feature.internal.FeatureManager A CWWKF0011I: The
server myFirstServer is ready to run a smarter planet.

The log shows the server startup procedure. First, the kernel starts. Then, the
feature manager initializes and reads the configuration from the server.xml file.
The server is configured to listen on a given port. Then, the ITSOWeb application
is started and finally the server is ready to serve the application.

7.1.2 Configuration of an additional trace

A typical task when working with applications is to enable and configure the
logging properties of the runtime server to inspect for problems. The Liberty
profile server can be configured to gather debug information for both runtime
issues and application code.

The Liberty profile server, when received, is configured to capture a minimal

amount of trace information. You can modify this default by specifying properties
in the server configuration file or bootstrap.properties file. OSGi logging output
is intercepted and delivered through the trace support. There is also interception
of java.util.logging output.

To learn more about configuring the logging service, refer to the information
center at the following website:
http://pic.dhe.ibm.com/infocenter/radhelp/v9/topic/com.ibm.websphere.wl
p.nd.multiplatform.doc/ae/rwlp_logging.html

Chapter 7. Serviceability and troubleshooting 171

 Configuring trace in the servers configuration
To configure an additional trace in the servers configuration, follow these
simple steps:
1. Open the server view in your workbench and double-click Server
Configuration for your server. This opens your server.xml file. Select the
Design tab.
2. Under the Configuration Structure, select Server Configuration and click
Add, as shown in Figure 7-1.

Figure 7-1 Adding the logging option to the server configuration

3. Select Logging and click OK.

172 WebSphere Application Server Liberty Profile Guide for Developers

4. Ensure that logging is selected under the Configuration Structure. You can
now configure logging in the Logging Details section, as shown in Figure 7-2.

Figure 7-2 Entering the trace details

The Logging Details window allows you to configure many aspects of logging,
including the location of the logs and where they are stored. The Trace
Specification defines what information to capture in the logs. In our example,
we capture information level messages for all classes. In addition, we chose
to capture all debug or higher level messages for any
com.itso.example.* classes.
For information about how to add logging to your applications, refer to the
following WebSphere Application Server Information Center website:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphe
re.nd.multiplatform.doc/ae/ttrb_javalogapps.html

Configuring trace using bootstrap.properties

Using the server configuration file to enable logging is an easy and efficient
method. However, the following list notes some cases where you might want to
put logging properties in to the bootstrap.properties file:
򐂰 When logging is required before the configuration processing occurs at server
start (this might be required for IBM support for debugging a server start
problem).
򐂰 When the server.xml configuration is shared by multiple server instances,
and logging is only required on one server (then the bootstrap.properties
file for that server can be modified).

Chapter 7. Serviceability and troubleshooting 173

 Example 7-2 shows a sample bootstrap.properties file that enables tracing of
any com.itso.example.* classes.

Example 7-2 A sample bootstrap.properties file

# New trace messages are written to the end of the file (true or false)
com.ibm.ws.logging.trace.append = "true"
# maximum size of e;ach trace file (in MB)
com.ibm.ws.logging.trace.max.file.size = 2
# maximum number of trace files
com.ibm.ws.logging.trace.max.files = 2
# Trace format (basic or advanced)
com.ibm.ws.logging.trace.format = "basic"
# Trace settings string - this string enables all trace
com.ibm.ws.logging.trace.specification =
com.itso.example.*=debug=enabled

7.2 Server memory dump

To capture state information of a Liberty profile server, you can use the dump
command. This can be useful for problem diagnosis of a Liberty profile server.

The result file that is generated by the dump command contains server
configuration, log information, and details of the deployed applications in the
workarea directory. The dump command can be used against a running or
stopped server. If the server is running, the following additional information
is gathered:
򐂰 State of each OSGi bundle in the server
򐂰 Wiring information for each OSGi bundle in the server
򐂰 Component list managed by the Service Component Runtime (SCR)
򐂰 Detailed information of each component from SCR

The following syntax is an example of running the dump command:

server dump server1 --archive=c:\tmp\server1_dump.zip

You can also create a memory dump of the Liberty profile server using the
WebSphere developer tools. This is done by right-clicking the server in the
Servers view and selecting Utilities  Generate Dump for Support.

174 WebSphere Application Server Liberty Profile Guide for Developers

7.3 MBeans and JConsole
The Liberty profile does not come with any dedicated tools to monitor its run
time, such as the IBM Tivoli® Performance Viewer available in the traditional
WebSphere Application Server console. To monitor the Liberty runtime
characteristics, administrators and developers can use standard tools for Java
run times, such as the Jconsole.

The Liberty profile offers the monitor-1.0 feature. This feature allows users to
track information about the Liberty profile server run time, such as JVM, web
applications, and the thread pool. To enable this monitoring, add the monitor-1.0
feature to the server.xml configuration so the following MXBeans are available:
򐂰 WebSphere:type=JvmStats
򐂰 WebSphere:type=ServletStats,name=*
򐂰 WebSphere:type=ThreadPoolStats,name=Default Executor

For more information about monitoring the Liberty profile using MXBeans, see
the following Information Center website:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
wlp.nd.doc/ae/twlp_mon.html

Jconsole is shipped as part of the Java Runtime package. To run Jconsole

against the Liberty profile, start it from the command line, as shown in the
following syntax:
C:\IBM\WebSphere\AppServer\java\bin>jconsole.exe

Chapter 7. Serviceability and troubleshooting 175

 When Jconsole launches, a welcome page opens. You must connect to the Java
process that runs the Liberty profile. The connection is made by logging in. The
Jconsole process must run under the same operating system user ID and use
the same Java run time as the server. As illustrated in Figure 7-3, we chose to
use the local server for our example.

Figure 7-3 Establishing a connection using JConsole

176 WebSphere Application Server Liberty Profile Guide for Developers

 The JConsole loads all runtime information into the tool. This includes the
characteristic of the Java runtime, heap size, or processor usage, as illustrated in
Figure 7-4.

Figure 7-4 Example monitoring output using JConsole

Chapter 7. Serviceability and troubleshooting 177

 Using the JConsole tool, you can also trigger MBeans operations that are part of
the Liberty profile. MBeans are available under the MBeans tab. Figure 7-5
shows an example of issuing a restart command on the ITSOWeb application.

Figure 7-5 Issuing a restart request for an application using MBeans

178 WebSphere Application Server Liberty Profile Guide for Developers

 If you enabled the monitoring infrastructure in Liberty, you can also access
additional MXBeans such as JvmStats, as illustrated in Figure 7-6.

Figure 7-6 Viewing JVMStats using Jconsole

Chapter 7. Serviceability and troubleshooting 179

180 WebSphere Application Server Liberty Profile Guide for Developers
 8

Chapter 8. From development to

production
The Liberty profile server is optimized for development use, but is supported for
use in both development and production environments. This chapter describes
several considerations for moving the Liberty profile server from a development
environment to a production environment.

The chapter contains the following sections:

򐂰 Configuring a server for production use
򐂰 Using the package utility
򐂰 Moving an application to the full profile
򐂰 Using the Liberty profile on z/OS

© Copyright IBM Corp. 2012, 2013. All rights reserved. 181

8.1 Configuring a server for production use
The following advanced configuration settings should be considered when using
a Liberty profile server in a production environment.

8.1.1 Turning off application monitoring

By default, application directories are monitored for any updates. Because
applications are unlikely to change frequently in a production environment and
because this monitoring can be resource-intensive, the preferred practice is to
disable application monitoring.

Application monitoring can be disabled in the Liberty profile developer tools by

editing the server configuration. In the design view, click Application
Monitoring. In the Application Monitoring Details window, clear the box next to
Monitor application drop-in directory. Additionally, you might want to change the
value of the drop-down menu for Application update trigger to disabled.

To disable application monitoring, by editing the server.xml file, add the

following element:
<applicationMonitor updateTrigger=”disabled” dropinsEnabled=”false”/>

You can also change the value of the updateTrigger attribute to mbean. This
allows you to update the application manually by using JMX.

8.1.2 Generating a web server plug-in configuration

To use the Liberty profile server with an external web server, you must generate
the web server plug-in configuration, whose properties can be specified in the
server configuration.

To add plug-in configuration properties in the Liberty profile developer tools, load
the server.xml file in the Design editor and click the server configuration. Then,
click Add and select Generate Plug-in. You can specify properties such as ports
in the Generate Plug-in details window.

To add plug-in configuration properties by editing the server.xml file, add a

pluginConfiguration element to the file. The element supports the
following attributes:
webServerPort The port the web server uses to listen for requests.
The default value is 80.

182 WebSphere Application Server Liberty Profile Guide for Developers

 webServerSecurePort The port the web server uses to listen for secure
requests. The default value is 443.
ipv6Preferred Whether to prefer ipv6. The default value is false.
pluginInstallRoot The plug-in installation root
sslCertLabel SSL certificate label
sslKeyringLocation SSL keyring location
sslStashFileLocation SSL stash file location

The actual plug-in configuration file must be generated either by using a utility in
the Liberty profile developer tools, or by running an mbean command using JMX.
In the tools, generate the file by right-clicking the server and selecting Utilities
Generate  Web Server Plug-in.

To generate the plug-in configuration using mbean, use a JMX console, such as
jconsole, to connect to the server. The localConnector-1.0 feature must be
enabled on the server. From the console, start the defaultPluginConfig
generation MBean.

8.2 Using the package utility

Because a Liberty profile server is lightweight, it can be packaged easily with
applications in a compressed file. This package can be stored, distributed to
colleagues, and used to deploy the application to a different location or to another
system. It can even be embedded in the product distribution.

A Liberty profile image is an archive file that contains one or more types of
resources of the Liberty profile environment. The types are dependent on the
topology that is deployed. You can extract them manually or you can use an
extraction tool to deploy the file to one or more systems. Alternatively, you can
use the job manager in the WebSphere Application Server Network Deployment
product to deploy these images.

The package contains all of the binary files, server configuration, and
applications necessary to distribute the server.

Chapter 8. From development to production 183

8.2.1 Packaging a Liberty profile server by using the WebSphere
developer tools
Use the following procedure to package a Liberty profile server from the
WebSphere developer tools:
1. Stop the server.
2. From the Servers view, right-click the server and select Utilities 
Package Server.
3. Enter a file name for the archive.
4. Select whether you want to include all server content (including the server
binary files) or only the server applications and configuration.
5. Click Finish.

8.2.2 Packaging a Liberty profile server from a command prompt

Use the following procedure to package a Liberty profile server from a command
prompt:
1. Navigate to the Liberty profile server installation root directory.
2. Run the command bin/server package server_name.

The package command supports the following options:

--archive The name of the output file
--include Include the entire server configuration by specifying all. Include
only the server applications and configuration by specifying usr.
Include only resources that are required by the server by
specifying minify.

8.2.3 Using the Job Manager to package and distribute Liberty

profile servers
In WebSphere Application Server V8.5 Network Deployment, use the Job
Manager to perform these functions:
򐂰 Package the Liberty profile runtime environments, configurations, and
applications.
򐂰 Distribute and deploy a Liberty profile server and applications.
򐂰 Start embedded profile packages.

184 WebSphere Application Server Liberty Profile Guide for Developers

 For more information about how to package the Liberty profile using the job
manager, see the Information Center at the following website:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
nd.multiplatform.doc/ae/tagt_jobmgr_comp_server.html

8.3 Moving an application to the full profile

Applications that are developed on the Liberty profile server can also be
redeployed to run on a WebSphere full profile server. The WebSphere full profile
environment provides some features not available in the Liberty profile server.
Applications that are developed in the full profile environment might not run on
Liberty profile.

8.3.1 Programming model differences between full profile and

Liberty profile
The WebSphere full profile server and the Liberty profile server differ in
programming support for the following technologies:
򐂰 Java EE 6
򐂰 Enterprise OSGi

For example, the full profile supports Java EE technologies such as Java EE
Connector architecture and the Java API for XML Based RPC (JAX-RPC), but
Liberty profile does not. For OSGi applications, Liberty profile does not support
Blueprint security.

For a more detailed comparison of technologies that are supported by the full
profile and Liberty profile, refer to the following information center website:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
wlp.nd.doc/ae/rwlp_prog_model_support.html

8.3.2 Configuration differences between full profile and

Liberty profile
Although applications developed in the Liberty profile environment can be run on
the full profile, there might be some configuration differences that must
be addressed.

Chapter 8. From development to production 185

 General concerns
In the Liberty profile, many properties that represent time values can be specified
using units of time. For example, one hour can be specified as the value 1h. In
full profile, time values are typically expressed as numeric values. When
migrating application resources such as data sources or connection managers to
full profile, you might need to modify property values to be specified as numbers.

Class loading
The Liberty profile server provides different methods of controlling class visibility
than the full profile server. If your application requires you to configure advanced
class loading behavior, you might need to reconfigure class loading in the full
profile environment. You might also need to configure class loading in full profile
if your application embeds classes that conflict with the full profile run time. For
more information about class loading in full profile, see the following page in the
Information Center website:

http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
express.doc/ae/trun_classload.html

Data sources
Some data source properties have different names:
򐂰 ifxIFX_LOCK_MODE_WAIT is informixLockModeWait in the full profile.
򐂰 supplementalJDBCTrace is supplementalTrace in the full profile.

Some data source properties have different default values:

򐂰 beginTranForResultSetScrollingAPIs is true by default in the Liberty profile
򐂰 beginTranForVendorAPIs is true by default in the Liberty profile
򐂰 statementCacheSize is 10 by default in the Liberty profile

The Liberty profile allows connectionSharing to be configured to either

MatchOriginalRequest or MatchCurrentState. By default, it is
MatchOriginalRequest.

The full profile allows connectionSharing to be configured in a finer grained

manner, where individual connection properties can be matched based on the
original connection request or current state of the connection. In the full profile,
connectionSharing is a combination of bits representing which connection
properties to match based on the current state of the connection.

186 WebSphere Application Server Liberty Profile Guide for Developers

In the full profile, a value of 0 means match all properties that are based on the
original connection request, and a value of -1 means to match all properties that
are based on the current state of the connection. The default value for the full
profile is 1, which means that the isolation level is matched based on the current
state of the connection and all other properties are matched based on the
original connection request.

Connection Manager
Some of the connection manager properties have different names in the full
profile and Liberty profile. Table 8-1 shows the property naming differences.

Table 8-1 Properties with different names

Liberty profile property name Full profile property name

maxConnectionsPerThread maxNumberofMCsAllowableInThread

maxIdleTime unusedTimeout

maxPoolSize maxConnections

minPoolSize minConnections

There are also differences in the way timeout values for immediate or never
(disabled) are specified. In Liberty profile, 0 represents an immediate timeout and
-1 represents a disabled timeout. In full profile, -1 represents an immediate
timeout and 0 represents a disabled timeout.

The value of the purge policy can also differ slightly between full profile and
Liberty profile. There are three possible values in Liberty profile: EntirePool,
FailingConnectionOnly, and ValidateAllConnections. The EntirePool option
maps directly to the EntirePool option in full profile. FailingConnectionOnly
maps to the FailingConnectionOnly option with the
defaultPretestOptimizationOverride property set to false in the full profile.
ValidateAllConnections corresponds to FailingConnectionOnly with the
defaultPretestOptimizationOverride property set to true in full profile.

Security
In the Liberty profile, you can configure user-to-role mappings and runAs users in
the application-bnd element of the server.xml file. In the full profile, you can
configure this only in ibm-application-bnd.xml/xmi.

Chapter 8. From development to production 187

 Liberty profile has the following security limitations as compared to full profile:
򐂰 No Java 2 security.
򐂰 Not all public APIs and SPIs are supported. The Java API document for each
Liberty profile API is detailed in the Programming Interfaces (APIs) section of
the information center, and is also available as a JAR file under the
/dev/api/ibm/javadoc directory of the server image.
򐂰 No horizontal propagation.
򐂰 No SecurityAdmin MBean support; therefore, methods such as clearing the
authentication cache are not available.
򐂰 No Java Authorization Contract for Container (JACC) support.
򐂰 No Java 2 Connector (J2C) principal mapping modules support.
򐂰 No Java Authentication SPI (JASPI) support.
򐂰 No multiple security domain support.
򐂰 No security auditing subsystem that is part of the security infrastructure of the
server.

Web Services Security

WS-Security in the Liberty profile is configured by using the WS-SecurityPolicy
within the WSDL file of a web service application. WS-Security, in the full profile,
is configured and enabled by using a policy set.

WS-Security in Liberty profile supports the following WS-Security

Policy namespaces:
򐂰 http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702
򐂰 http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200802
򐂰 http://schemas.xmlsoap.org/ws/2005/07/securitypolicy

WS-Security, in full profile, supports the WS-Security policy namespace

http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200512.

The Liberty profile supports more policy assertions than the full profile. To sign or
encrypt a SupportingToken such as a UsernameToken in the Liberty profile, you
assert the token as SignedSupportingTokens,
SignedEncryptedSupportingTokens, or EncryptedSupportingTokens. In the full
profile, you must use an XPath expression to sign or encrypt a SupportingToken.

Some endorsing tokens are not supported in the full profile, including
EndorsingSupportingTokens, SignedEndorsingSupportingTokens,
EndorsingEncryptedSupportingTokens, and
SignedEndorsingEncryptedSupportingTokens.

188 WebSphere Application Server Liberty Profile Guide for Developers

 Both the Liberty profile and the full profile support the SymmetricBinding and
AsymmetricBinding assertions. Only Liberty profile supports the
TransportBinding assertion.

The IncludeToken assertion is enforced in the Liberty profile, but is ignored in the
WS-Security runtime environment of the full profile.

The Liberty profile supports PasswordDigest and key derivation in the

UsernameToken assertion. The full profile supports only PasswordText in a
UsernameToken.

An unrecognized element in the Security header is rejected by the full profile. It is

accepted by the Liberty profile.

Web applications
The Liberty profile server does not automatically expand web archive (WAR) files
that are deployed to the server. The Java EE specification states that the
getRealPath() method returns a null value if the content is being made available
from a WAR file.

If your application relies on a result being returned by getRealPath(), you must

deploy the application as an expanded web application, not as a WAR file. For
example, you can manually extract the WAR file and copy the expanded
application to the dropins directory.

JSP
Full profile supports a useInMemory configuration option to store only translated
JSP files in memory. Liberty profile does not support this option.

JAX-RS
The Liberty profile developer tools do not support third-party JAX-RS APIs. The
developer tools for full profile include this support.

Bean validation
There is no support for bean validation inside OSGi applications in Liberty profile.

8.4 Using the Liberty profile on z/OS

WebSphere Application Server V8.5 provides features for administering a Liberty
profile on a z/OS platform. You can use IBM MVS™ operator commands to start,
stop, or modify the Liberty profile.

Chapter 8. From development to production 189

 Additional optional features provide enhanced integration with z/OS qualities
of service:
򐂰 Classify inbound HTTP requests with WLM
򐂰 Use an IBM DB2® Type 2 driver with RRS transaction management
򐂰 Authenticate users using a SAF user registry
򐂰 Authorize users using a SAF authorization provider

The IBM Installation Manager is used to install the Liberty profile on z/OS using a
part of the com.ibm.websphere.zOS.v85 package offering.

For more information, see the following Information Center website:

http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
wlp.zseries.doc/ae/twlp_admin_zos.html

190 WebSphere Application Server Liberty Profile Guide for Developers

 9

Chapter 9. Developing and deploying

custom features (new in
Version 8.5.5)
As mentioned in the overview, IBM WebSphere Application Server V8.5.5 Liberty
Profile supports direct enhancement of the run time with user-defined features
deployed in product extensions. Creating your own features allows you to
customize or extend the behavior of the run time using System Programming
Interfaces (SPIs) that applications do not have access to. User-defined features
can also provide additional application programming interfaces (APIs) and
services to deployed applications.

This chapter walks through the creation, packaging, and deployment of a custom
feature in the following sections:
򐂰 Considerations for creating custom features
򐂰 Defining a custom feature
򐂰 Liberty product extensions

© Copyright IBM Corp. 2012, 2013. All rights reserved. 191

9.1 Considerations for creating custom features
User-defined features become an integrated part of the run time, which allows
you to do things you cannot do with an application in the following ways:
򐂰 Features are installed and managed separately from business applications,
keeping your run time or product code separate from user code.
򐂰 Services that are provided by a user-defined feature can receive
user-specified configuration from the server.xml file, and that configuration
can be viewed and modified in the WebSphere developer tools
configuration editor.
򐂰 Classes in OSGi bundles that are provisioned by a user-defined feature can
use SPIs that are provided by the Liberty profile or by other extensions.
򐂰 OSGi bundles in a user-defined feature can augment or extend supported
programming models. For example, a custom trusted association interceptor
(TAI) can be provided by a user-defined feature.
򐂰 OSGi bundles in a user-defined feature can interact with OSGi services that
are provided by the run time and by other extensions. With correct metadata,
OSGi services that are provided by user-defined features can also be shared
with OSGi applications.

General instructions for writing features and receiving configuration properties

can be found at the following Information Center website:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
wlp.core.doc/ae/twlp_admin_extend.html

Consider the following list before you choose to extend the Liberty profile
run time:
򐂰 Depending on your needs, features can run directly on the Liberty kernel with
no dependence on application containers or other features. This provides a
lightweight solution.
򐂰 Defining your own features can be powerful, but comes at the cost of
portability. If portability between application servers is a primary concern,
developing specification-compliant applications is more appropriate than
creating product extensions and features.
򐂰 It is important to use only documented and supported externals to ensure that
the Liberty profile can be serviced or upgraded with minimal disruption to your
features and extensions. APIs, SPIs, and Javadoc are provided in the
${wlp.install.dir}/dev/ directory for use when developing and building
your features.

192 WebSphere Application Server Liberty Profile Guide for Developers

 򐂰 Features can use OSGi management of native library loading, allowing you to
package libraries for multiple architectures in a single JAR file. OSGi loads
the appropriate library at run time.

Other details about supported externals are provided in following Information

Center article, which should be considered the authoritative source:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
wlp.core.doc/ae/rwlp_profile_externals.html

9.2 Defining a custom feature

A Liberty profile feature is a collection of resources, usually OSGi bundles, that
provide classes and services to the Liberty profile run time. A feature is defined
using a text-based manifest file that follows the Subsystem Service metadata
format in the OSGi Enterprise R5 specification.

9.2.1 Elements of a feature

To create a feature, either manually or using WebSphere developer tools, you
essentially must create a manifest file, example.mf, in the lib/features/
directory of a product extension. That manifest file must describe the feature
(what it is called, how it is referenced, and whether other features can use it) and
enumerate the feature’s content, including any bundles that should be
provisioned if the feature is enabled.

For more information about feature manifests, including the full list of all
supported manifest headers, see the following Information Center article:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
wlp.core.doc/ae/rwlp_feat_definition.html

Fixed-value manifest headers

There are a few headers in a feature manifest that must have specific, predefined
values to allow the file to be recognized as a feature:
IBM-Feature-Version: 2
The version of the feature subsystem type. Required.
Subsystem-Type: osgi.subsystem.feature
The feature subsystem type. Required.
Subsystem-ManifestVersion: 1
The version of the OSGi Subsystem manifest format.
Specifying this header is optional, but recommended.

Chapter 9. Developing and deploying custom features (new in Version 8.5.5) 193
 Required manifest headers
Here are the key elements of a feature definition, which is shown with a
representative example value:
Subsystem-SymbolicName: com.example.product.feature-1.0
The symbolic name of the feature, which follows the same
style and syntax as the Bundle-SymbolicName header for
bundles. Features can include other features, and when
they do, they use the symbolic name to reference each
other. The symbolic name of a feature should be
sufficiently unique that it is safe to assume that two
features with the same symbolic name are, in fact, the
same feature. This header also supports the usage of
attributes and directives, notably the visibility directive
that is described in 9.2.2, “Visibility constraints for
features, packages, and services” on page 196.
Subsystem-Content: com.example.product.bundle; version="[1,1.0.100)"
This header is the key to provisioning. It is a
comma-separated list of resources that defines the
feature’s content. As with package declarations in a
bundle manifest, each element of this list can specify
additional directives, such as type, location, or version.
These directives are described in more detail in 9.2.3,
“Subsystem content: Writing a minify-compatible feature”
on page 200.

Recommended headers for public features

Here are the recommended headers for public features:
IBM-ShortName: example-1.0
A representative short name that can be used with the
extension name, in server.xml, to enable a feature. This
is recommended to simplify the user configuration of
public features.
Subsystem-Localization: OSGI-INF/l10n/localization
The name and description of a feature can be globalized.
Use this header to package properties files containing the
translated values with your feature.
Subsystem-Name: %name
A short, localizable, and descriptive feature name. You
can specify the value directly, or use a %propertyName
format, which looks up the translated value in the file that
is referenced by the Subsystem-Localization header.

194 WebSphere Application Server Liberty Profile Guide for Developers

Subsystem-Description: %description
A short, localizable, and descriptive feature name. You
can specify the value directly, or use a %propertyName
format, which looks up the translated value in the file that
is referenced by the Subsystem-Localization header.

Headers that influence provisioning behavior

Here are the headers that influence provisioning behavior:
IBM-API-Package: javax.servlet; type="spec"
A list of packages that follows the bundle manifest’s
Export-Package syntax, and lists the packages that are
provided by a feature that should be visible to
applications. For more information, see 9.2.2, “Visibility
constraints for features, packages, and services” on
page 196.
IBM-API-Service: com.example.service.FeatureServiceOne
This header is used to indicate which services from the
feature are visible to OSGi applications. The services that
are listed in this header must be registered in the service
registry by the bundles that comprise the feature. The
service-name is the Java class or interface name of the
service. Any specified attributes are interpreted as service
properties that should be used when providing the service
to OSGi applications. For more information, see 9.2.2,
“Visibility constraints for features, packages, and services”
on page 196.
IBM-SPI-Package: com.example.spi.utils
A list of packages that follows the bundle manifest’s
Export-Package syntax, and lists packages that are
provided by a feature that should be visible to other
features in other extensions. For more information, see
9.2.2, “Visibility constraints for features, packages, and
services” on page 196.
IBM-Provision-Capability: <OSGi LDAP Filter>
Some features provide a function that is only useful if
other features are enabled. This header allows for a
feature to be auto-provisioned when its requirements, as
specified in the feature definition using a standard OSGi
LDAP filter, are satisfied. This header is described in
more detail in 9.2.5, “Automatic provisioning: Creating an
auto-feature” on page 210.

Chapter 9. Developing and deploying custom features (new in Version 8.5.5) 195
 IBM-App-ForceRestart: install,uninstall
The presence of this header in a feature manifest causes
applications to be restarted when this feature is either
installed, uninstalled, or both.

9.2.2 Visibility constraints for features, packages, and services

The Liberty profile run time imposes visibility constraints to allow both the core
run time and any installed extensions to evolve independently. By default,
features and their associated bundles are considered internal details of the run
time or extension that provides them. The following list notes what this
default means:
򐂰 All features are private, and cannot be specified in server.xml or included by
features from other extensions.
򐂰 Exported packages are only visible to other bundles provided by the
same extension.
򐂰 Services that are registered in the service registry are not available to OSGi
applications. Usage of registered services by consumers from other
extensions is limited by the ability of consuming code to resolve the
service interface.

The Subsystem-SymbolicName header supports a visibility attribute that

controls how the feature can be used and resolved by the run time and product
extensions. As shown in Figure 9-1 on page 197, there are three possible values
for the visibility attribute: public, protected, and private (the default).

196 WebSphere Application Server Liberty Profile Guide for Developers

 






 
 
 
    


 

Figure 9-1 Visibility restrictions and features

Public features
Public features should be considered product externals, or APIs. They can be
used directly in server.xml files, and are seen and used by the WebSphere
developer tools, and appear in messages. Public features should have an
IBM-ShortName header that is defined to simplify use. A list of public features that
is provided by the Liberty run time can be found in the following Information
Center article:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
wlp.core.doc/ae/rwlp_feat.html

A public feature might be superseded by a newer version if necessary, such that

the older version that is used by existing server configurations continue to
function. For more information about superseded features, see the Information
Center article:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
wlp.core.doc/ae/cwlp_feat_mgmt.html

Chapter 9. Developing and deploying custom features (new in Version 8.5.5) 197
 Example 9-1 shows a snippet from a public feature manifest. Note the presence
of the IBM-ShortName header, which is used in combination with the extension
prefix in server.xml, and the public visibility constraint on the
Subsystem-SymbolicName header.

Example 9-1 Declaration of a public feature, with an IBM-ShortName

IBM-ShortName: example-1.0
Subsystem-SymbolicName: com.ibm.example.feature.public-1.0;
visibility:=public

Protected features
Protected features are also product externals, but should be considered SPI, as
the target consumer for a protected feature is another feature. Although
protected features are not directly referenced in a configuration, they are
referenced by other extensions, and should be treated with an equal amount of
care when changes are made to avoid breaking consumers.

The Liberty profile defines several protected features, including features for the
application manager and the classloading service, for use by product extensions.
A list of protected features that are provided by the Liberty run time can be found
in the following Information Center article:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphere.
wlp.core.doc/ae/rwlp_protected_features.html

Example 9-2 shows a snippet from a protected feature manifest.

Example 9-2 Declaration of a protected feature

Subsystem-SymbolicName: com.ibm.example.feature.protected-1.0;
visibility:=protected

Private features
Finally, we have the default: private features. Private features are usable only
within a product extension. Implementation details should be packaged using
private features. Auto features, which are described in 9.2.5, “Automatic
provisioning: Creating an auto-feature” on page 210, are almost always private
features, which rely on the provisioning of other public or protected features to
automatically enable additional capabilities.

Example 9-3 on page 199 shows a snippet from a private feature manifest.

198 WebSphere Application Server Liberty Profile Guide for Developers

Example 9-3 Declaration of a private feature, which omits the visibility attribute

Subsystem-SymbolicName: com.ibm.example.feature.private-1.0

Declaring API and SPI packages that are provided by a feature

By default, the individual packages that are exported by the bundles that are
provisioned by a feature are private to the feature’s extension. This means the
individual packages that the bundles use to comprise your features are treated
as internal implementation details for your product extension. Packages that
should be shared with applications (as API), or with bundles from features in
other extensions (as SPI), must be explicitly declared using manifest headers
that follow the bundle’s Export-Package syntax.

The IBM-SPI-Package header is used to list packages that are provided by a

feature that should be treated as SPI, and the IBM-API-Package header is used to
list packages that are provided by a feature that should be treated as API. Both
headers support an optional type attribute, which identifies the type of package
that is being shared. The type attribute uses the following values:
api This value applies only to the IBM-API-Package header,
and is the default type for API package declarations. It is
used to mark user-defined or product-defined API.
ibm-api This value applies only to the IBM-API-Package header,
and is used for IBM-provided API packages.
internal This value applies only to the IBM-API-Package header,
and is used to indicate packages that are not API
packages, but that must be available to application
classloaders. For example, because of use of reflection,
bytecode enhancement or weaving, and
resource injection.
spec Used for API or SPI provided by a standards body, such
as javax.servlet or org.osgi.framework.
third-party Used for API or SPI that is visible, but is not provided or
controlled by IBM. This usually applies to open source
code. Use of third-party packages carries additional risk
for version to version migration, as these packages might
change over time without consideration for compatibility
with earlier versions.

Note: When enumerating API and SPI packages, the package version is not
respecified; the package versions should be maintained only by the bundles
that provide those packages.

Chapter 9. Developing and deploying custom features (new in Version 8.5.5) 199
9.2.3 Subsystem content: Writing a minify-compatible feature
The package utility, which is mentioned in 8.2, “Using the package utility” on
page 183, can produce a minified server image. When you package a server
with the --include=minify option, the package utility creates an archive that
contains resources that only the server configuration requires. The list of
required resources is built using the Subsystem-Content header that is defined
for each enabled feature. When you create your own feature, it is important to
verify the value of this header to ensure that a minified server that uses your
feature has all of the resources that it needs.

The Subsystem-Content header follows the syntax that shown in Example 9-4. As
with an Export-Package bundle header, it is a comma-separated list of values,
with optional semi-colon separated parameters, which can be attributes (=) or
directives (:=). Each item in the list identifies an individual resource using a
unique name.

Example 9-4 Syntax for Subsystem-Content header (see OSGi core spec section 1.3.2)
Subsystem-Content ::= resource ( ',' resource )*

resource ::= unique-name ( ';' parameter )*

unique-name ::= identifier ( ’.’ identifier )*

parameter ::= directive | attribute

directive ::= extended ’:=’ argument
attribute ::= extended ’=’ argument

argument ::= extended | quoted-string

extended ::= ( alphanum | ’_’ | ’-’ | ’.’ )+
quoted-string ::= ’"’ ( ~["\#x0D#x0A#x00] | ’\"’|’\\’)* ’"’

The name that is used for a resource is influenced by its type, which is specified
as an optional attribute. By default, a resource is assumed to be an OSGi bundle
(type="osgi.bundle"). The bundle's symbolic name is used when specifying a
bundle resource. Likewise, a feature's symbolic name is used, along with
type="osgi.subsystem.feature", to include another feature as a resource. For
other supported types (type="file" and type="jar"), a unique string should be
created for the resource using the syntax and character set that is allowed for
symbolic or package names.

200 WebSphere Application Server Liberty Profile Guide for Developers

 Resources can also specify a location directive to indicate where the artifact for
that resource can or should be found. The specified location is also dependent
on the type. The directive is not required for bundles or features, as the default
(lib/ and lib/features/, respectively) is sufficient. For bundles and JAR files,
the location directive can point to a list of directory locations, which constitute a
search path (such as, look in dev/ first, then in lib/). The core run time uses this
list mechanism to provide API and SPI JAR files in the dev/ directory that are
then serviced by the lib/ directory. For JAR and plain files, the location can (and
in the case of files, must) contain a single path pointing directly to the backing
resource. Paths are specified relative to the installation root of the extension
containing the feature. When referencing public or protected features from
another extension, the location field should not be specified. Rely on the
symbolic name of the feature you are referencing, and let the run time figure out
where to load it from.

In addition to type, the following list notes other supported directives:

version The version attribute applies to bundles, and specifies the
versions to be matched when finding a bundle to satisfy
the feature. Only bundles in this range are selected. A
typical example of the version range is (1,1.0.100).
start-phase Start-phase is a directive that indicates when (relative to
the rest of the run time) a bundle that is used by a feature
should be started. The start-phase directive can take
one of the following values: SERVICE, CONTAINER, or
APPLICATION. Bundles can also be defined to start before
or just after these phases by adding _LATE to be later, or
_EARLY to be earlier than the key phase. So if you want to
run immediately after the container phase, use
CONTAINER_LATE, and if you want to run before the
APPLICATION phase, then use APPLICATION_EARLY.

The next few sections provide examples of these directives in use.

9.2.4 Using the tools to create a custom feature

In this section, we describe how to build a simple feature containing a single
bundle that prints “Hello World!” when it is started, and “Goodbye World!” when it
is stopped. The focus here is on creating a feature and the supporting bundle
resource, publishing the feature to a product extension, and then using the
feature as the catalyst to cause our bundle to be loaded and started by the OSGi
run time.

Chapter 9. Developing and deploying custom features (new in Version 8.5.5) 201
 Creating an OSGi bundle project
Begin by creating a project for this bundle by completing the following steps:
1. Click File  New  OSGi Bundle Project.
2. Enter a project name. This example uses the project name
ITSO.OSGiExample.SimpleBundle.
3. For the Target Runtime, select WebSphere Application Server V8.5 Liberty
Profile.
4. Clear the Add bundle to application check box. If you leave this selected, a
new OSGi application project is created.
5. Leave all other values at the default settings and click Next  Next.
6. This example uses a simple BundleActivator to show that the bundle is
loaded by the run time. Select the Generate an activator check box.
7. Exit the wizard by clicking Finish. The contents of the new bundle project
should resemble what is shown in Figure 9-2.

Figure 9-2 OSGi bundle project with generated Activator

202 WebSphere Application Server Liberty Profile Guide for Developers

8. Update the contents of the Activator to roughly match the contents of
Figure 9-3.

Figure 9-3 Simple bundle activator

Chapter 9. Developing and deploying custom features (new in Version 8.5.5) 203
 Creating a Liberty feature project
Begin by creating a project for the new feature by completing the following steps:
1. Click File  New  Other  OSGi  Liberty Feature Project, and then
click Next to open the Liberty Feature Project wizard, as shown in Figure 9-4.

Figure 9-4 The Liberty Feature project wizard

2. Enter a project name. This example uses the project name

ITSO.OSGiExample.SimpleFeature.
3. For the Target Runtime, select WebSphere Application Server V8.5 Liberty
Profile, and click Next.

204 WebSphere Application Server Liberty Profile Guide for Developers

4. Select the check box next to itso.osgiexample.simplebundle to include our
example bundle in our new feature, as shown in Figure 9-5.

Figure 9-5 Adding a bundle to a feature

5. Exit the wizard by clicking Finish. The contents of the new feature project
should resemble what is shown in Figure 9-6.

Figure 9-6 Liberty feature project

Chapter 9. Developing and deploying custom features (new in Version 8.5.5) 205
 6. Double-click the Manifest element in the feature project to open the manifest
editor. Update the values in the manifest, as shown in Figure 9-7, and save
your changes. Specifically, update the feature’s symbolic name and the
feature name to include a version representation. This is counter to how
versions usually work; in this case, consider the version string in the feature
name to be a statement of API/SPI compatibility, especially for
public features.

Figure 9-7 The feature manifest editor

7. To support making changes to the bundle version (to apply service), select
the bundle from the Subsystem-Content section of the editor, click
Properties, and edit the Minimum Version and Maximum Version fields, as
shown in Figure 9-8 on page 207, and click OK.

206 WebSphere Application Server Liberty Profile Guide for Developers

 Figure 9-8 Editing the properties of a bundle that is listed in a feature’s
Subsystem-Content

8. Click the SUBSYSTEM.MF tab at the bottom of the manifest editor to view the
raw source of the manifest, which should resemble what is shown in
Figure 9-9. The specified Subsystem-Content is minimal, as the feature
includes only a bundle resource (which is the default type), in a default
location, with the specified required version range.

Figure 9-9 Raw contents of the feature manifest

Chapter 9. Developing and deploying custom features (new in Version 8.5.5) 207
 Installing the feature
The WebSphere developer tools make installing the feature painless. Right-click
the feature project, select Install Feature... from the menu, select WebSphere
Application Server V8.5 Liberty Profile for the target run time, and click Finish.
The WebSphere developer tools adds the feature and its contents to the default
product extension of the target run time, as shown in Figure 9-10.

Figure 9-10 The example bundle and feature that is installed into the default product
extension

Enabling the feature in a test server

Use the server configuration editor to edit the configuration of a test server by
clicking Add and selecting the feature that we created from the list. Because it is
a feature in the default product extension, it appears in the list with an usr:
prefix. This example shows usr:simple-1.0 (see Figure 9-11 on page 209). Click
OK to finish, and save the updated server configuration.

208 WebSphere Application Server Liberty Profile Guide for Developers

Figure 9-11 The simple-1.0 feature appears in the feature list with the usr: prefix

If you add this feature to a running server, you see something similar to the
output shown in Example 9-5. “Hello World!” is the output from the simple
activator that we provided for the feature bundle.

Example 9-5 Console output after enabling the usr:simple-1.0 feature.

[AUDIT ] CWWKF0011I: The server simpleServer is ready to run a
smarter planet.
[AUDIT ] CWWKG0016I: Starting server configuration update.
Hello World!
[AUDIT ] CWWKF0012I: The server installed the following features:
[usr:simple-1.0].
[AUDIT ] CWWKF0008I: Feature update completed in 0.220 seconds.
[AUDIT ] CWWKG0017I: The server configuration was successfully
updated in 0.236 seconds.

Chapter 9. Developing and deploying custom features (new in Version 8.5.5) 209
9.2.5 Automatic provisioning: Creating an auto-feature
An automatic feature is not configured by the user in the server XML. It is
automatically loaded by the feature manager if the features specified in its
IBM-Provision-Capability manifest header are configured by the user. This is
useful when two features require additional Java classes to work together. The
additional classes are put into the automatic feature. When only one of those
features is configured, the extra Java classes are not loaded. In this way,
automatic features can be used to keep features as small as possible without
requiring the user to understand any relationships between them.

For example, one feature might provide an application container and another
might provide a generic security service. In order for them to work together,
security collaborators specific to that container are required. Those collaborators
are not useful in the absence of either the container or the security service. In
this example, the security collaborator classes are packaged into a third,
automatic feature, which contains the entry that is shown in Example 9-6 in its
manifest file.

Example 9-6 Entry for automatic feature

IBM-Provision-Capability:
osgi.identity;
filter:=”(&(type=osgi.subsystem.feature)(osgi.identity=com.ibm.itso.con
tainer))”,
osgi.identity;
filter:=”(&(type=osgi.subsystem.feature)(osgi.identity=com.ibm.itso.sec
urity))”

The syntax for the IBM-Provision-Capability header is an LDAP query. The

feature names that are specified in the query must be the
Subsystem-SymbolicName values, not the IBM-ShortName values.

The bundles in the automatic feature can have mandatory dependencies on the
bundles in both of the other features because the feature is provisioned only
when both the container and security features are present. This is another way
that automatic features helps minimize the mandatory dependencies between
configured features.

210 WebSphere Application Server Liberty Profile Guide for Developers

9.2.6 Packaging native code in your bundles
OSGi provides help with loading native libraries. You can package libraries for all
supported architectures in your bundle and list them on the Bundle-NativeCode
manifest header. Code a single System.loadLibrary call in your Java code.
OSGi examines the manifest header, determines the correct library for the
architecture being used, and loads that library. Example 9-7 shows an example
definition of the native library name for Windows and OSX.

Example 9-7 Definition of the native library name for Windows and OSX
Bundle-NativeCode:
lib/win32/x86/name.dll; osname=win32; processor=x86,
lib/macosx/libname.dylib; osname=macosx; processor=x86;
processor=x86_64

Java has some limitations when loading native libraries that also apply in an
OSGi framework. For example, a native library can be loaded only by one
classloader in a JVM process, so the same native library cannot be used by more
than one OSGi bundle.

9.2.7 Packaging features for delivery

Features can be packaged individually for an application to an existing Liberty
profile installation or can be included in a packaged server if a self-contained
deployment package is required.

OSGi subsystem archive

A subsystem archive is the OSGi specified package for an individual feature. It
contains the feature (subsystem) manifest and the files that are described by the
Subsystem-Content manifest header. It is an archive file with a suffix of .esa.

A subsystem archive is output by the WebSphere developer tools when you

select Export for a Liberty feature project. They can be applied to a Liberty profile
installation by running the featureManager command in the bin directory.

Packaged server
If you want to create a complete deployment solution, you can generate an
archive by running the server package command. This outputs a compressed file
with the following contents:
򐂰 The Liberty run time
򐂰 Any features in the user product extension directory (wlp/usr/extension)

Chapter 9. Developing and deploying custom features (new in Version 8.5.5) 211
 򐂰 Your server configuration (for the server that is specified on the server
package command)
򐂰 Any applications and resources that are contained within the server

Using the minify option generates a smaller package containing only the
features that are used by the server. This includes features that are configured in
the server.xml file, features that are included by configured features, and
features that are resolved as automatic features from the configured features.
For example, a minified server package for servlet support is only about 17 MB.

9.3 Liberty product extensions

A Liberty product extension is a set of directories and files that have a layout
similar to the Liberty product installation but are placed in your own installation
location. It can contain the same types that are present in the LIberty product,
such as feature and command-line scripts.

The function in a product extension can be fully integrated into the Liberty run
time and WebSphere developer tools. Because it uses the extensible Liberty
architecture, it also integrates into future tools that are written to use
that extensibility.

A product extension is identified to the Liberty run time through placement of a

properties file in the Liberty install. The name of the properties file is used as the
product extension. For convenient development of features, there is a built-in
user extension location in the Liberty installation structure: the usr/extension
directory. You can install your features to that location for easy testing before you
package them into your product extension. This is the location that the
WebSphere developer tools use for feature installation.

When you design product extensions, there are many aspects that you might
want to consider beyond simple function. These design principles are applied to
the Liberty product features to keep the servers highly composable and simple to
use. Those design principles are covered in the following sections.

Allowing the user to compose their server

It is a core design principle of the Liberty profile that the user should select which
features are in their server. This allows the user to control at a fine-grained level
the exact services that are available. There is intentionally no support for profile
augmentation, so when your feature is installed into an existing Liberty profile, it
is not used by any servers unless the user explicitly adds the feature to the
server configuration.

212 WebSphere Application Server Liberty Profile Guide for Developers

If you want to provide a way for your feature to be used without being manually
added to the server configuration, you can provide a server template in the
template servers directory of your product extension. This also allows you to
provide a predefined configuration in addition to the feature itself. You can direct
your users to specify your template on the server create command or you can
provide your own command script in your extension bin directory that wraps the
server create command and specifies your template, as shown in Example 9-8.

Example 9-8 Wrapping the server create command

server create --template=<extension-name>:<template-name>

Although this might be a convenient way to allow simple creation of working

servers, it should not be used in place of providing useful configuration defaults
in your features through metatype. Keeping the default values inside your feature
allows you to adjust them in service or future releases. There is no support for
modifying existing server.xml configuration files. These files are considered to
be user-owned files and the Liberty profile does not change them.

All configuration is specified in the server.xml file

Almost all configuration for a server can be specified in the server.xml or other
included configuration files. One exception is the case where properties must be
set before server.xml processing. For example, JVM properties cannot be set in
server.xml. Another exception is the case where a public specification requires
that the configuration be contained in a specific file. Specifying configuration in
the server.xml or included files allows an ecosystem of commands and tools to
be built on those files.

By receiving your configuration from the server.xml file, you benefit from the
following capabilities:
򐂰 Automatic parsing and injection of your configuration properties
򐂰 Reinjection every time the property values are updated
򐂰 Inclusion of your configuration in the generated schema that is used by the
WebSphere developer tools and any future graphical user interfaces
򐂰 Management of configuration files by the Liberty run time

It also benefits your users by allowing them to keep all of their server
configurations in a single file or set of files.

Chapter 9. Developing and deploying custom features (new in Version 8.5.5) 213
 Keeping it small and fast
Keep your dependency stack as short as possible. Defer as much of your
initialization processing as possible. For example, you can use OSGi Declarative
Services to delay loading of your service implementation classes until they
are used.

Dynamic behavior
Features should be able to stop and restart independent of the server restarting
and independent of each other. This relies on correct cleanup on shutdown and
the dynamic management of references to services in other features. Your
features should react dynamically to configuration updates. This dramatically
reduces the need for servers to be restarted, especially during application
development. It also greatly increases usability.

Simple migration
It should be painless for users to apply service and product upgrades. Some
design points that help to achieve that goal are included in the following list:
򐂰 No migration is required for configuration; all configuration remains
compatible with earlier versions.
򐂰 Longer toleration of Java versions.
򐂰 Clear separation of product/user files and internal/external function.
򐂰 Feature evolution is strictly compatible with earlier versions. The versions in
feature names provide a way to handle incompatibilities in upgrades by
providing a new feature version with the new behavior but continuing to
support the existing feature.

214 WebSphere Application Server Liberty Profile Guide for Developers

 A

Appendix A. Additional material

This book refers to additional material that can be downloaded from the Internet,
as described in the following sections.

Locating the web material

The web material that is associated with this book is available in softcopy on the
Internet from the IBM Redbooks web server. Point your web browser to the
following URL:
ftp://www.redbooks.ibm.com/redbooks/SG248076

Alternatively, you can go to the IBM Redbooks website at:

ibm.com/redbooks

Select Additional materials and open the directory that corresponds with the
IBM Redbooks form number, SG248076.

© Copyright IBM Corp. 2012, 2013. All rights reserved. 215

Using the web material
The additional web material that accompanies this book includes the
following files:
File name Description
ch3_ITSOWeb.zip A Liberty profile developer tools project with code
samples from Chapter 3, “Developing and deploying
web applications” on page 45
ch4_OSGiExample.zip A Liberty profile developer tools project with code
samples from Chapter 4, “Iterative development of
OSGi applications” on page 93
ch5_ITSOWeb.zip A Liberty profile developer tools project with code
samples from Chapter 5, “Data access in the Liberty
profile” on page 105
ITSO_derby.zip A Derby database for use with samples from
Chapter 5, “Data access in the Liberty profile” on
page 105
ITSO2_derby.zip A Derby database for use with samples from
Chapter 5, “Data access in the Liberty profile” on
page 105
ITSODD_derby.zip A Derby database for use with samples from
Chapter 5, “Data access in the Liberty profile” on
page 105

Downloading and extracting the web material

Create a subdirectory (folder) on your workstation, and download the contents of
the web material files into this folder. Extract the sg248076.zip file into this folder
to access the sample application files.

Importing the Liberty profile developer tools projects

To use any of the Liberty profile developer tools projects, you must first create a
Liberty profile server runtime environment in your Eclipse installation, as
described in 2.2.1, “Installation using the Liberty profile developer tools” on
page 29.

Use the following process to use any of the three example projects,
ch3_ITSOWeb.zip, ch4_OSGiExample.zip, or ch5_ITSOWeb.zip:
1. Extract the compressed project file into its own subdirectory.

216 WebSphere Application Server Liberty Profile Guide for Developers

 2. From Eclipse, run File  Import  Existing Projects Into Workspace.
3. In the Import Projects window, enter the path to the subdirectory where you
extracted the compressed file in the Select root directory field. This should
complete the Projects field with either ITSOWeb (for the examples from
Chapter 3, “Developing and deploying web applications” on page 45 and
Chapter 5, “Data access in the Liberty profile” on page 105), or five projects
beginning with ITSO.OSGiExample (for the examples from Chapter 4,
“Iterative development of OSGi applications” on page 93).
4. Select the box to copy projects into the workspace.
5. Click Finish.

Using the compressed Derby database files

To use the compressed Derby database files, simply extract the compressed
files and make a note of the file path. The examples in Chapter 5, “Data access
in the Liberty profile” on page 105 describe how to set up a data source to point
to these example databases.

Appendix A. Additional material 217

218 WebSphere Application Server Liberty Profile Guide for Developers
Related resources

The resources that are listed in this section are considered suitable for a more
detailed description of the topics that are covered in this book.

Online resources
These websites are relevant as further information sources:
򐂰 Enterprise Bundle Archive (EBA) Maven plug-in:
http://aries.apache.org/modules/ebamavenpluginproject.html
򐂰 OSGi home page:
http://www.osgi.org
򐂰 Stack Overflow tags:
http://stackoverflow.com/questions/tagged/websphere-liberty
򐂰 Supported operating systems for the Liberty profile:
http://www-01.ibm.com/support/docview.wss?uid=swg27038218
򐂰 Technologies that are supported by the Liberty profile:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphe
re.wlp.nd.doc/ae/rwlp_prog_model_support.html
򐂰 WASdev community:
http://wasdev.net/
򐂰 WASdev forum:
http://www.ibm.com/developerworks/forums/forum.jspa?forumID=2666
򐂰 WebSphere Application Server Developer Tools for Eclipse:
http://publib.boulder.ibm.com/infocenter/radhelp/v9/topic/com.ibm.ra
d.install.doc/topics/t_install_wdt.html
򐂰 WebSphere Application Server Liberty Profile Information Center:
http://pic.dhe.ibm.com/infocenter/wasinfo/v8r5/topic/com.ibm.websphe
re.wlp.nd.doc/ae/twlp_inst.html

© Copyright IBM Corp. 2012, 2013. All rights reserved. 219

Help from IBM
IBM Support and downloads
ibm.com/support

IBM Global Services

ibm.com/services

220 WebSphere Application Server Liberty Profile Guide for Developers

WebSphere Application Server Liberty Profile Guide for Developers
(0.2”spine)
0.17”<->0.473”
90<->249 pages
 Back cover ®

WebSphere Application
Server Liberty Profile
Guide for Developers ®

WebSphere IBM WebSphere Application Server V8.5 includes a Liberty profile,

Application Server which is a highly composable, dynamic application server profile. It INTERNATIONAL
V8.5.5 profile is designed for two specific use cases: Developer with a smaller TECHNICAL
designed for
production run time, and production environments. For a developer, SUPPORT
it focuses on the tasks a developer does most frequently and makes ORGANIZATION
developers it possible for the developer to complete those tasks as quickly and
as simply as possible. For production environments, it provides a
Lightweight, easy to dynamic, small footprint run time to be able to maximize system
install, and fast to resources.
BUILDING TECHNICAL
use application This IBM Redbooks publication provides you with information to INFORMATION BASED ON
server effectively use the WebSphere Application Server V8.5 Liberty PRACTICAL EXPERIENCE
profile along with the WebSphere Application Server Developer
Tools for Eclipse, for development and testing of web applications
Simplified that do not require a full Java Platform. It provides a quick guide on IBM Redbooks are developed by
development with getting started, providing a scenario-based approach to the IBM International Technical
the Liberty profile demonstrate the capabilities of the Liberty profile along with the Support Organization. Experts
developer tools, providing a simplified, but comprehensive, from IBM, Customers and
Partners from around the world
application development and testing environment.
create timely technical
The intended audience for this book is developers of web and OSGi information based on realistic
applications who are familiar with web and OSGi application scenarios. Specific
concepts. recommendations are provided
to help you implement IT
This book has been updated to reflect the new features in solutions more effectively in
WebSphere Application Server V8.5.5. your environment.

For more information:

ibm.com/redbooks

SG24-8076-01 ISBN 0738438618