External functions and resources of the Liberty profile
can be used directly, and can be relied on to be in the next release.
Internal or incidental aspects of the profile might change when you
apply service, or upgrade to a future release.
What can I use directly in the profile and rely on
being in the next release?
The following resources can be
used directly and will continue to be available in the next release:
- The application programming interfaces (APIs) and system programing
interfaces (SPIs) defined by the content of the JAR files in the ${wlp.install.dir}/dev directories.
- The application class loader has visibility to the API that is
provided by the features in your server configuration. Product extension
features have visibility to all API and SPI that is provided by the
features in your server configuration.
- Compile your code against the JAR files in the ${wlp.install.dir}/dev directories.
- The server configuration, including features with public or protected visibility.
Public features and configuration elements can be specified in the server.xml file
and included files; protected features can be included in your own
features.
- Commands, scripts and archives in the ${wlp.install.dir}/bin directory
and subdirectories.
- Client utilities in the ${wlp.install.dir}/clients directory
and subdirectories.
What should I avoid dependencies on?
Do
not build dependencies on incidental aspects of the product, or you
might be impacted when you apply service or upgrade to future releases.
Examples of product internals that you should avoid relying on include,
but are not restricted to, the following scenarios:
- The names of product binary jars, for example those in the ${wlp.install.dir}/dev directory.
Compile your code against these JAR files by using the tools or the javac
-extdirs option. See Overriding classes from the Java SDK.
- Direct use of the product binaries in the ${wlp.install.dir}/lib directory.
The only JAR files that can be directly invoked are in the ${wlp.install.dir}/bin/tools directory.
- Messages that are output by the server at run time. The text and
inserts of messages are subject to change in service and version upgrades.
As far as practically possible, the product will be consistent in
the message IDs that are output at particular points of operation,
but this cannot be guaranteed because underlying implementations might
change.
- The layout of the product installation, other than the ${wlp.install.dir}/bin and ${wlp.install.dir}/dev directories.
- Examples and template files in the ${wlp.install.dir}/templates directory.
These files might be modified when you apply services to your installation.
- Private or third party Java™ packages
that are not explicitly exposed as APIs. These are not visible to
the application class loader at run time.
What might be modified by applying
service or an upgrade?
The contents of the following directories
and their subdirectories might be modified when service or upgrade
is applied. Do not make your own modifications to files in these
locations, or they might be overwritten by product maintenance or
upgrade:
- ${wlp.install.dir}/bin
- ${wlp.install.dir}/clients
- ${wlp.install.dir}/dev
- ${wlp.install.dir}/java
- ${wlp.install.dir}/lib
- ${wlp.install.dir}/templates
No modifications are made to the contents of the following
directories. These are your files, and applying service or upgrade
will not modify them:
- ${wlp.install.dir}/etc (where you might have
added a server.env or jvm.options file).
- ${wlp.install.dir}/usr (the default location
for user configuration and applications).
- Any non-default directory that you designate through the WLP_USER_DIR environment
variable.
There is an exception to the policy
that no modifications are made to the contents of ${wlp.install.dir}/etc.
The file ${wlp.install.dir}/etc/default.env is
created when you install the Liberty profile on IBM® iSeries® Platforms
using the Installation Manager. This file is also created or replaced
by the iAdmin POSTINSTALL command during archive
and Job Manager installations. The iAdmin command
is in the ${wlp.install.dir}/lib/native/os400/bin directory.
See Liberty profile: iAdmin command.
Third-party
APIs might change over time without consideration to backward compatibility.
These are Java packages that
are considered part of the implementation of features developed in
open source communities and delivered as part of the Liberty profile.
Third-party APIs are not visible to applications by default; Java EE applications with a classloader
configuration that explicitly allows third-party access will have
visibility to those packages on the application class loader, and
OSGi applications must explicitly import the packages. Consider the
impact of incompatible changes before deciding to use third-party
APIs.