Liberty:Runtime environment known issues and restrictions

There are some known restrictions that apply when working with Liberty runtime environment.

List of known issues and restrictions:

Minimum supported Java levels

Liberty is supported with any compliant Java™ SE 6, Java SE 7, or Java SE 8 runtime environment (JRE) or Java SDK, subject to the minimum supported levels shown for the following specific implementations.
Java SE 6 runtime environment
For the Java SDK from IBM, the minimum supported level is 6.0 (J9 2.6) SR 1. For the JDK from Oracle, the minimum supported level is Java 6 update 26.

For IBM i platformsJava SE 6 is not supported on IBM i V7R3.

Java SE 7 runtime environment
For the Java SDK from IBM, the minimum supported level is IBM Runtime Environment, Java Technology Edition 7.0.4.1. For the JDK from Oracle on Windows and Linux, the minimum supported level is Java SDK/JRE/JDK 7.0.17. For the JDK from Oracle on Mac OS X, the minimum supported level is Java SDK/JRE/JDK 7.0 Update 15.
Java SE 8 runtime environment
For the Java SDK from IBM, the minimum supported level is IBM SDK, Java Technology Edition, Version 8. For the JDK from Oracle, the minimum supported level is Java 8 update 25.

For distributed platformsOn distributed platforms, 32-bit or 64-bit Java is supported.

For distributed platformsFor Windows and Linux systems, you can use either the JDK from Oracle or the Java SDK from IBM. If you are developing applications on Windows or Linux, and you plan to deploy those applications to a server that is running on WebSphere Application Server traditional, use the Java SDK from IBM. For HP systems and Mac OS, use the JDK from Oracle.

For IBM i platformsNote: To obtain the minimum supported Java level for IBM i, install IBM Java SE 6.0 32-bit JVM (5761-JV1 option 11 or 5770-JV1 option 11) or IBM Java SE 6.0 64 bit (5761-JV1 option 12 or 5770-JV1 option 12). For IBM i V7R1, also install Java PTF group SF99572 level 8 or later.

For IBM i V7R3, the minimum JDK level is IBM Java SE 7.0 32-bit JVM (5770-JV1 option 14) or IBM Java SE 7.0 64-bit JVM (5770-JV1 option 15).

The installation directory name and path cannot include non-ASCII characters

Recent JVMs do not fully support use of non-ASCII characters with the -jar and -javaagent commands. Use only ASCII characters in your installation directory names and paths.

Changing the JDBC data source at run time might result in JPA failures

If the database dictionary type is not specified through properties, it is detected and calculated by OpenJPA when the first entity manager is created and the database connection is made. This database dictionary type is used for all entity managers that are subsequently created. If the JDBC data source is changed while an application is running, the entity manager factory does not detect this change and continues to use the old dictionary for operations against the new data source. This can result in failures if the database is changed to a different vendor.

When you change a database to a different vendor, restart the application.

Modifying the dataSource, jdbcDriver, connectionManager, and JDBC vendor properties at run time might result in JPA failures

If you update the configuration of dataSource, jdbcDriver, connectionManager or any of the JDBC vendor properties lists (for example, properties.db2.jcc or properties.oracle) while the server is running, you might see J2CA8040E failures. These failures state that multiple dataSource elements cannot be associated with a single connectionManager. These failures are generated even if your configuration associates only one connectionManager with the dataSource element.

When you make updates to the configuration of any of these JDBC resources, restart the server.

An application that relies on a result being returned by getRealPath must be deployed as an expanded application, not as a WAR file

The Java EE specification states that the getRealPath() method returns a null value if the content is being made available from a web archive (WAR) file. When you deploy a WAR file to Liberty it does not automatically extract the archive file into a directory structure. Therefore the application might fail to start. 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.

WebSphere Application Server traditional scripts do not work with Liberty

You cannot use any of the scripts under the bin directory of the WebSphere Application Server traditional to administer Liberty.

Fileset restrictions

The following restriction applies to Filesets:
  • Filesets do not recursively explore subdirectories of the base directory. For example, the following instructions are not supported:
    <fileset id="testFileset" dir="\temp" includes="**\a.jar"/> 
    <fileset id="testFileset" dir="\temp" includes="a\a.jar"/>
    <fileset id="testFileset" dir="\temp" includes="*\a.jar"/>
    <fileset id="testFileset" dir="\temp" includes="a\b\a.jar"/>
For Windows platforms

When you unpublish a shared library, it cannot be deleted until the server is stopped

When you unpublish a shared library from a server, the library JAR file is not immediately released from the server. Therefore the operating system does not know that the file is no longer in use, and does not let you delete the file. When you next stop the server, the library JAR file is released and you can delete the file.

java:global lookups restrictions

Resources defined in applications with java:global lookups can only be used to access names declared by applications deployed in the current server.

Applications not starting in an embedded Liberty server

Ensure that the Java process that starts the embedded Liberty server was started with the -javaagent JVM argument that pointed to the libertyInstallDir/bin/tools/ws-javaagent.jar. If the -javaagent JVM argument is not used the server runtime starts, but applications fail to start with no obvious exceptions.

WebSphere MQ resource adapter and generic JCA support related restrictions

The WebSphere® MQ resource adapter can be used within the WebSphere Application Server Liberty by using either the wmqJmsClient-1.1 or wmqJmsClient-2.0 feature or by using generic JCA support.

You can use the WebSphere MQ resource adapter version 7.5 with Liberty version 8.5.5 and later. If you want to use WebSphere MQ resource adapter version 8.0, which is based on JMS 2.0 resource adapter, you must ensure that you are using the latest Liberty version that is compatible with the JMS 2.0 resource adapter.

Notes:
  • With Liberty version 8.5.5.2, the wmqJmsClient-1.1 feature must be used with a IBM MQ resource adapter version 7.5.0.5 or later.
  • With Liberty version 8.5.5.6, the wmqJmsClient-2.0 feature must be used with a IBM MQ resource adapter version 8.0.0.3 or later.

To know more about the version compatibility information between WebSphere MQ resource adapter and Liberty, see the Reference to obtain the WebSphere MQ resource adapter.

If you are using generic JCA support, the following restrictions apply:
  • To run the IBM® WebSphere MQ resource adapter on z/OS®, you must use the wmqJmsClient-1.1 or wmqJmsClient-2.0 feature.
  • Tracing and logging are not integrated within the Liberty trace system using generic JCA. Trace is written to a separate file, and it must be enabled by setting the system properties. The procedure to enable tracing is the same as configuring the WebSphere MQ classes for JMS trace facility for a Java Standard Environment. See Java Standard Environment Trace stanza.
  • The IBM MQ classes for Java are not supported in Liberty. They must not be used with either the IBM MQ Liberty messaging feature or with the generic JCA support. For more information, see Using WebSphere MQ Java Interfaces in J2EE/JEE Environments.

Versioning is not possible for applications in the dropins directory

For applications in the dropins directory, the file name and file extension are used by the application monitor to determine the type of application, and to generate the application id and application name. It is therefore not possible to specify the version number for the application by using the file name or file extension. In a production environment, you are not recommended to use the dropins directory.

Shared session applications must store session objects in shared libraries

When you are using the shared-session-context application extension, or <shared-session-context value="true"/> in ibm-application-ext.xml, all objects that are stored in the session must be available in the shared libraries that are associated with the application so that the session can be invalidated.

Admin Center feature restrictions

For the adminCenter-1.0 feature, the following restrictions apply:
  • Using an IBM Java virtual machine (JVM) available with a WebSphere Application Server traditional product, such as Network Deployment, can cause WebSphere Liberty Administrative Center ("Admin Center") to not display in a browser. By default, the IBM JVM available with a WebSphere Application Server traditional product points to security classes that are available only with a WebSphere Application Server traditional product, and not to security classes needed by Admin Center, which requires Secure Sockets Layer (SSL). Use a JVM that supports Liberty products and SSL.
    You can get a JVM that supports Liberty products and SSL from Installation Manager offerings or developerWorks®:
    • Using Installation Manager, select Liberty product first and then select WebSphere SDK for Liberty. Use Installation Manager to install Liberty product and software development kit (SDK). The WebSphere SDK for Liberty includes the needed support for Liberty products and SSL and offers a Java client, JConsole.
    • Go to http://www.ibm.com/developerworks/java/jdk/index.html on the developerWorks website and download an IBM Java development kit (JDK) for your operating system. The developerWorks website does not have a JVM for all operating systems. For example, you have to get the JDK from Eclipse for Windows operating systems.
  • The CPU Usage chart of the Admin Center Monitor view shows 0% CPU usage for JVMs that do not supply process CPU statistics. For information about the chart, see Monitoring metrics in Admin Center.
[16.0.0.4 and later]For the beta version of the Java Batch tool, the following restrictions apply:
  • Job logs from remote machines cannot be viewed because of security authentication issues.
  • If instance logs are viewed, expect an error if the executions are spread across multiple hosts.
  • Unfiltered lists only show results that are sorted according to the most recently updated instances.
  • When executing a filter for all, the results are not sorted by the most recently updated instances.
  • Only fifty or fewer results are displayed in the list whether or not the list has been filtered.
  • Using Java Batch beta requires using a persisted database with the batchManagement-1.0 feature.

appClient-1.0 feature restriction

For the appClient-1.0 feature, the following restriction applies:
  • The feature does not support Java EE application clients and can launch only stand-alone client programs.

appSecurity-2.0 feature restrictions

For the appSecurity-2.0 feature, the following restrictions apply:
  • For EJB applications, the run-as-mode of SYSTEM_IDENTITY is not supported in the extension settings of the ibm-ejb-jar-ext.xml file.
  • The getCallerIdentity API is not supported for Singleton session beans.
  • Role names can be referenced by the HttpServletRequest.isUserInRole and EJBContext.isCallerInRole APIs or by elements in the deployment descriptor without first declaring the role names using the @DeclareRoles annotation or the <security-role/> element in the deployment descriptor. However, roles must be declared before being used in WebSphere Application Server traditional.

Bean validation feature restrictions

For the beanvalidation-1.0 feature, the following restriction applies:
  • There is no support for bean validation inside OSGi applications.
For the beanValidation-1.1 feature, the following restrictions apply:
  • There is no support for bean validation inside OSGi applications.
  • Applications that provide a custom ConstraintValidatorFactory implementation in a validation.xml file with the beanValidation-1.0 feature do not compile against the Bean Validation 1.1 API.
  • If a validation.xml file is not located in the module it is associated with, then there can be only one validation.xml file and the com.ibm.ws.beanvalidation.allowMultipleConfigsPerApp property must be set to false in either of the following files:
    • jvm.options
      -Dcom.ibm.ws.beanvalidation.allowMultipleConfigsPerApp=false
    • bootstrap.properties
      com.ibm.ws.beanvalidation.allowMultipleConfigsPerApp=false

Dynamic cache feature restrictions

The following dynamic cache features are not available or have limited availability:
  • Cache replication is not supported.
  • Only high performance disk caching mode is supported with random and size based eviction techniques.
  • There is no support for Web Services client and server side caching as well as portlet cache in the cachespec.xml file.
  • There is no support for servlet caching of SingleThreadModel servlets.
  • Defining cache configuration by using properties files is not supported for JAR files that contain only Enterprise JavaBeans (EJBs).
  • Limiting a heap cache size works only for 32-bit Java virtual machines (JVM).

Enterprise JavaBeans (EJB) feature restrictions

The following restrictions apply to EJB features:
  • EJB modules before version 3.0 are not supported when using the EJB Lite features only because EJB homes are not included in EJB Lite. This restriction also means that bindings and extensions that use the .xmi file format rather than the .xml file format are not supported.
  • Session beans are not bound to the ejblocal namespace, which means JNDI lookups and ejb-ref binding names must use java:global, java:app, or java:module names. The simple-binding-name and interface binding-name elements are ignored in ibm-ejb-jar-bnd.xml files.
  • The stateful bean passivation directory is not configurable. Files are passivated to the server work area.

j2eeManagement-1.1 feature restriction

For the j2eeManagement-1.1 feature, the following restriction applies:

  • The Management EJB getListenerRegistry() method is not supported. You cannot register an event notification listener in a Management EJB component.

jaxb-2.2 feature restrictions

For the jaxb-2.2 feature, the following restrictions apply:
  • If your application requires JAXB API classes and has already been started, and the jaxb-2.2 server feature is to be enabled, you must restart the server with the --clean option so that you application can call the JAXB 2.2 API and implementation classes that are provided by the jaxb-2.2 feature. Otherwise, your application might still bind to the JAXB API and implementation classes that are provided in the Java SDK
  • If the jaxb-2.2 server feature is enabled, and you want to use your own JAXB API and implementation classes in your application, you must place your own JAXB API and implementation JAR files into the /WEB-INF/lib directory of your application, and configure the class loader of your application to use parentLast delegation behavior. Otherwise, the JAXB API and implementation classes that are provided by the jaxb-2.2 feature always take effect. For more information of configuring class loader behavior for you applications on Liberty, see Overriding a provided API with an alternative version.

jaxws-2.2 feature restrictions

For the jaxws-2.2 feature, the following restrictions apply:
  • If you application provides its own copy of CXF JAR files as the application libraries, for example, in the WEB-INF/lib directory of a web application, you cannot enable the jaxws-2.2 feature in the server.xml file.
  • Because the jaxws-2.2 feature depends on the jaxb-2.2 feature, the jaxb-2.2 feature restrictions also apply to the jaxws-2.2 feature.
  • If your application requires JAX-WS API classes and has already been started, and the jaxws-2.2 server feature is to be enabled, you must restart the server with the --clean option so that you application can call the JAX-WS 2.2 API and implementation classes that are provided by the jaxws-2.2 feature. Otherwise, your application might still bind to the JAX-WS API and implementation classes that are provided in the Java SDK
  • The web services binding file for Liberty is the ibm-ws-bnd.xml file. The following web services binding files for WebSphere Application Server traditional are not supported:
    • ibm-webservices-ext.xmi
    • ibm-webservices-bnd.xmi
    • ibm-webservicesclient-ext.xmi
    • ibm-webservicesclient-bnd.xmi
    • ws-security.xml
  • The Apache Axis2 configurations or classes are not supported.
  • The web service providers that implement javax.xml.ws.Provider<OMElement> or javax.xml.ws.Provider<String> interface are not supported.
  • The content-id attribute of MIME attachments must be enclosed with angle brackets for Liberty. For example, <testID>.
  • The -inlineSchemas option is not supported by the wsgen tool that is provided by Liberty.
  • Enable MTOM if you want to transfer big binary data using JAX-WS web services to avoid the Out of Memory (OOM) error.
  • For web service applications, if the service client and service provider are not in the same application and the WSDL file in the service provider application is changed, you need to restart the web service client application manually to avoid the WSDL definition cache issue.

jsf-2.2 feature restrictions

For the jsf-2.2 feature, the following restrictions apply:
  • When you use the jsf-2.2 feature with a faces-config.xml file and specify version 2.2 and namespace, you will get an error.
  • There are feature conflicts if you enable jsf-2.2 with cdi-1.2, ejb-3.2, and jpa-2.1.

jsp-2.2 feature restrictions

For the jsp-2.2 feature, the following restriction applies:
  • There is no support for the useInMemory configuration option to only store the translated JSP file in memory.

logstashCollector-1.0 feature restrictions

The following limitations apply to the logstashCollector-1.0 feature:
  • Data Loss – Some events that are generated in Liberty might not be forwarded to Logstash as expected. Data loss might occur under the following scenarios:
    1. Starting the Liberty server before the Logstash server is started. It is recommended that you start the Logstash server before starting the Liberty server.
    2. Heavy load conditions. Events might be dropped in cases where events are created in Liberty faster than they can be processed by Liberty's event pipeline, Logstash, and any other downstream consumers. Liberty uses buffers to avoid data loss when event creation is briefly faster than event consumption.
  • The logstashCollector-1.0 feature is tested and is compatible with Logstash V2.x.

logmetCollector-1.0 feature restrictions

The following limitations apply to the logmetCollector-1.0 feature:
  • Data Loss – Some events that are generated in Liberty might not be forwarded to logmet as expected. Data loss might occur under the following scenario:

    Heavy load conditions. Events might be dropped in cases where events are created in Liberty faster than they can be processed by Liberty's event pipeline, logmet, and any other downstream consumers. Liberty uses buffers to avoid data loss when event creation is briefly faster than event consumption.

  • Connection loss - The connection to the logmet service in Bluemix® frequently disconnects.

monitor-1.0 feature restriction

For the monitor-1.0 feature, the following restriction applies:
  • When the feature is removed from the server.xml file, you must restart the server to make the JAX-WS applications work.

requestTiming-1.0 feature restrictions

For the requestTiming-1.0 feature, the following restriction applies:
  • The requestTiming-1.0 feature, when activated, has been shown to have a 4% adverse effect on maximum possible application throughput when measured with the DayTrader application. While the effect on your application might be more or less than that, you should be aware that some performance degradation might be noticeable.

restConnector-1.0 feature restriction

For the restConnector-1.0 feature, the following restriction applies:

  • Users of the restConnector-1.0 feature or any feature that includes restConnector-1.0, such as collectiveMember-1.0 and collectiveController-1.0, who want to run applications containing a custom JAXRS 2.0 runtime must add the jaxrs-2.0 feature to that server.

scim-1.0 feature restrictions

The following restrictions apply for the scim-1.0 feature:
  • The members attributes are not retrieved while searching for groups.
  • The groups attributes of users are not retrieved while searching for users.
  • The Canonical type of direct/indirect cannot be set for groups attribute of users.
  • Only one email attribute of user of Canonical type, work, can be defined.
  • Only one ims attribute of user of Canonical type, work, can be defined.
  • Extended schema attributes of SCIM such as entitlements, roles and x509Certificates cannot be set or returned.
  • The userName attribute cannot be used with some other attributes in a filter.
  • For users in Basic and SAF registries, only userName, displayName, id, schema, meta.location and groups can be set. The userName and displayName will have the same value.
  • List/query with Basic and SAF registries does not work the same as the ldapRegistry registry.
  • Operators like pr, gt, ge, lt, le, and, or, and () will not work with Basic and SAF registries. Also, only one operator must be used in the filter for Basic and SAF registries.
  • Basic and SAF are read only registries.
  • While creating user, groups attribute cannot be set.

wmqJmsClient-1.1 feature restrictions

For the wmqJmsClient-1.1 feature, the following restrictions apply:
  • You must manually set the PATH variable in the Windows environment variables to point to the IBM MQ installation bin directory. You must set this path variable when the application uses the BINDING connection mode.
  • The IBM MQ classes for Java are not supported in Liberty. They must not be used with either the IBM MQ Liberty messaging feature or with the generic JCA support. For more information, see Using WebSphere MQ Java Interfaces in J2EE/JEE Environments.
  • The BINDINGS_THEN_CLIENT transport type of IBM MQ resource adapter is not supported for the wmqJmsClient-1.1 feature.
  • The Advanced Messaging Security (AMS) feature is not included for the wmqJmsClient-1.1 feature.

wmqJmsClient-2.0 feature restrictions

For the wmqJmsClient-2.0 feature, the following restrictions apply:
  • You must manually set the PATH variable in the Windows environment variables to point to the IBM MQ installation bin directory. You must set this path variable when the application uses the BINDING connection mode.
  • The IBM MQ classes for Java are not supported in Liberty. They must not be used with either the IBM MQ Liberty messaging feature or with the generic JCA support. For more information, see Using WebSphere MQ Java Interfaces in J2EE/JEE Environments.
  • The BINDINGS_THEN_CLIENT transport type of IBM MQ resource adapter is not supported for the wmqJmsClient-2.0 feature.

collectiveController-1.0 feature restriction

If you start a collective controller server and then change your IP configuration, the controller no longer functions correctly.

jpa-2.1 feature restrictions

For the jpa-2.1 feature, the following restrictions apply:
  • You cannot use an alternate JPA 2.1 provider. If you need 2.1 support, you must use the built in provider.
  • You cannot use any EclipseLink-specific features or annotations in your application. You can only use the javax.persistence APIs.

concurrent-1.0 feature restrictions

For the concurrent-1.0 feature, the following restrictions apply:

For the thread context of type securityContext, any custom information in the subject that was not added by using a JAAS login module will not be propagated. For example, if the submitter's subject contains a custom Principal that was added by a TAI, the propagated subject will not contain this custom Principal.

sipServlet-1.1 feature restrictions

For the sipServlet-1.1 feature, the following restrictions apply to Session Initiation Protocol (SIP) support:
  • SIP counters for Performance Monitoring Infrastructure (PMI) are not supported.
  • SIP digest authentication and JSR 289 Section 17, the security section, are not supported.
  • Clustering and SIP dialog persistence are not supported.

jacc-1.5 feature restrictions

For the jacc-1.5 feature, the following configurations are ignored:
  • Authorization information (the users and groups attributes of the authorizations attribute) in an ibm-application-bnd.xml file or an ibm-application-bnd.xmi file of the application's ear file.
  • Authorization information (the user, group and special-subject attributes of the security-role attribute in the application-bnd element) in the server.xml file.

Icon that indicates the type of topic Reference topic



Timestamp icon Last updated: Monday, 5 December 2016
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=rwlp_restrict
File name: rwlp_restrict.html