Liberty externals support

External functions and resources of Liberty can be used directly, and can be relied on to be in the next release. Internal or incidental aspects of Liberty might change when you apply service, or upgrade to a future release.

What can I use directly in Liberty 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 programming 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 provided by the features in the server configuration. Product extension features have visibility to all API and SPI provided by the features in your server configuration.

  • Compile your code against the JAR files in the ${wlp.install.dir}/dev directories. The JAR files in the ${wlp.install.dir}/dev directories are provided only for compilation of applications and features, they are not supported for runtime use. Do not use these JAR files in applications, libraries, or tests.

• 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 our 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?

• The names of the product binary JAR files, for example those in the ${wlp.install.dir}/dev directory. Compile your code against these JAR files using the tools or the javac -extdirs option.If we are using Apache Ant to compile your code, use wildcards to avoid dependencies on the specific JAR version; for example:

  <fileset dir="${wlp.install.dir}/dev/api/spec" includes="com.ibm.ws.javaee.servlet.3.0_*.jar"/>

  Alternatively, we can use the featureManager classpath command to generate a classpath for a specific set of features.

  See featureManager command.

• Direct use of the product binary files 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.

• Undocumented configuration properties. The Liberty code base is common with the WebSphere Application Server traditional code base. Therefore, some configuration properties in the Liberty code base might not be documented, but when specified might affect the behavior of Liberty. As these configuration properties are not documented for Liberty, they are not supported for Liberty. They were not tested for Liberty and might not work reliably in Liberty now or in the future. As these properties are not documented as a product external, they can be removed at any time.

What might be modified by applying service or an 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 we 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.

IBM i: No modifications are maded to contents of ${wlp.install.dir}/etc. The file ${wlp.install.dir}/etc/default.env is created when we install Liberty on IBM iSeries Platforms using the Installation Manager. This file is also created or replaced by the iAdmin POSTINSTALL command during archive. The iAdmin command is in the ${wlp.install.dir}/lib/native/os400/bin directory. See 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 Liberty. 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 effect of incompatible changes before deciding to use third-party APIs.