Runtime environment known restrictions

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

See also Developer Tools known restrictions.

List of known issues and restrictions:

1. Minimum supported Java levels
2. The installation directory name and path cannot include non-ASCII characters
3. Changing the JDBC data source at run time might result in JPA failures
4. An application that relies on a result being returned by getRealPath must be deployed as an expanded application, not as a WAR file
5. WebSphere Application Server full profile scripts do not work with the Liberty profile
6. Fileset restrictions
7. Overriding classes from the Java SDK
8. When we unpublish a shared library, it cannot be deleted until the server is stopped
9. java:global lookups restrictions
10. appSecurity-2.0 feature restrictions
11. Applications not starting in an embedded Liberty server
12. WebSphere MQ resource adapter and generic JCA support related restrictions
13. Versioning is not possible for applications in the "dropins" directory
14. Admin Center feature restrictions
15. beanvalidation-1.0 feature restrictions
16. Dynamic cache feature restrictions
17. ejbLite-3.1 feature restrictions
18. jsp-2.2 feature restrictions
19. monitor-1.0 feature restriction
20. wmqJmsClient-1.1 feature restrictions
21. concurrent-1.0 feature restrictions

Minimum supported Java levels

The Liberty profile is supported with any compliant Java SE 6 or Java SE 7 runtime environment, 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.

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.

On distributed platforms, 32-bit or 64-bit Java is supported.
For Windows and Linux systems, we can use either the JDK from Oracle or the JDK from IBM. If we are developing applications on Windows or Linux, and we plan to deploy those applications to a server running on the WebSphere Application Server full profile, we should use the JDK from IBM. For HP systems and Mac OS, use the JDK from Oracle.

Note: To obtain the minimum supported Java level for IBM iSeries , install IBM J2SE 6.0 32-bit JVM (5761-JV1 option 11

or 5770-JV1 option 11) or IBM SE 6.0 64 bit (5761-JV1 option 12

or 5770-JV1 option 12), and also install Java PTF group SF99562 level 19 (or later) for IBM i 6.1 or SF99572 level 8 (or later) for IBM i 7.1.

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. We should use only ASCII characters in the 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 we 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, we might see J2CA8040E failures. These failures state that multiple dataSource elements cannot be associated with a single connectionManager. These failures are generated even if the configuration associates only one connectionManager with the dataSource element.

When we 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 we deploy a WAR file to the Liberty profile, the profile does not automatically extract the archive file into a directory structure. Therefore the application might fail to start. If the application relies on a result being returned by getRealPath(), we must deploy the application as an expanded web application, not as a WAR file. For example, we can manually extract the WAR file and copy the expanded application to the dropins directory.

WebSphere Application Server full profile scripts do not work with the Liberty profile

We cannot use any of the scripts under the bin directory of the WebSphere Application Server full profile to administer the Liberty profile.

Fileset restrictions

The following restrictions apply 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"/>

• If we use symbolic links with Filesets, add a forward slash ("/") at the end of the dir attribute value. For example:
  <fileset dir="${ihc.home}/" includes="*.jar"/>

Overriding classes from the Java SDK

Some Java EE 6 technologies supported by the Liberty profile require newer versions of APIs provided by Java SE 6. JAX-WS, JAXB and the javax.annotation.Resource annotation are all examples where a Java 6 SDK contains older classes than those required by Java EE 6. When compiling the application code against these APIs using Java SDK version 6, use classes provided by the Liberty profile rather than the Java SDK. We must take one of the following actions:

• If we are using javac to build from the command line, compile the code using the javac -endorseddirs option and the JAR files in the ${wlp.install.dir}/dev/specs directory.

• If we are using Apache Ant to build, compile the code using the <compilerarg> child element of the javac task and the JAR files in the ${wlp.install.dir}/dev/specs directory. In the build script, specify the -endorseddirs option and the ${wlp.install.dir}/dev/specs directory as separate <compilerarg> elements. For example:

  <javac srcdir="src" destdir="classes"/>
      <compilerarg value="-endorseddirs"/>
      <compilerarg value="${wlp.install.dir}/dev/specs"/>
  </javac>

• If we are using Apache Maven to build, compile the code using the endorseddirs element of the Maven compiler plug-in and the JAR files in the ${wlp.install.dir}/dev/specs directory. For example:

  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
      <source>1.6</source>
      <target>1.6</target>
      <compilerArguments>
        <endorseddirs>${wlp.install.dir}/dev/specs</endorseddirs>
      </compilerArguments>
    </configuration>
  </plugin>

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

When we 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 we next stop the server, the library JAR file is released and we 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.

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 the full profile.

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 installed in the WebSphere Application Server Liberty profile version 8.5.5.2 or later, using either the wmqJmsClient1.1 feature or generic JCA support. If we are using generic JCA support, the following restrictions apply:

• To run the IBM WebSphere MQ resource adapter on z/OS , use the wmqJmsClient1.1 feature.

• Tracing, and logging are not integrated within the Liberty trace system. Trace is written to a separate file, and it must be enabled by setting the system property. 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.

• If we create a JMS unified domain connection from a domain-specific connection factory a JMSException MQJMS1026 is generated. To resolve this issue, ensure that the WebSphere MQ Resource Adapter installed into the WebSphere Application Server Liberty profile contains the fix for APAR IT02539.

  We can use the WebSphere MQ resource adapter version 7.5 with the Liberty profile version 8.5.5 and later. Although to use WebSphere MQ resource adapter version 8.0 which is based on JMS 2.0 resource adapter, we must ensure that we are using the latest Liberty profile version that is compatible with the JMS 2.0 resource adapter. To know more about the version compatibility information between WebSphere MQ resource adapter and the Liberty profile, see the Reference to obtain the WebSphere MQ resource adapter.

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 using the file name or file extension. In a production environment, we are not recommended to use the "dropins" directory.

Admin Center feature restrictions

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

• Use an IBM Java virtual machine (JVM) available with a WebSphere Application Server full profile product, such as Network Deployment, causes WebSphere Liberty Administrative Center ("Admin Center") to not display in a browser. The IBM JVM available with a full profile product points to security classes available only with a full profile product, and not to security classes needed by Admin Center, which requires SSL. Use a JVM that supports Liberty profile products and SSL.

  We can get a JVM that supports Liberty profile products and SSL from Installation Manager offerings or developerWorks:

  • Use Installation Manager, select the Liberty profile product first and then select WebSphere SDK for Liberty. Use Installation Manager to install the Liberty profile product and software development kit (SDK). The WebSphere SDK for Liberty includes the needed support for Liberty profile 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 the operating system. The developerWorks website does not have a JVM for all operating systems. For example, we have to get the JDK from Eclipse for Windows operating systems.

• When deploying a server package to a controller, only package a server that has not joined any controller.

  Alternatively, if the server has joined a controller, move the $WLP_INSTALL_DIR/usr/servers/server_name/resources/collective directory (with subdirectories) to a temporary directory such as /tmp before running the server package command. Then, after the server package is created, move the resources/collective directory (with subdirectories) back to $WLP_INSTALL_DIR/usr/servers/server_name from the temporary directory.

• From the Admin Center Deploy tool, we cannot use the Use the connection method and credentials configured for each target host option of Remote Management Credentials to deploy a Liberty profile 8.5.5.3 or earlier server package to a registered host. The server package must support Liberty profile 8.5.5.4 or later.

beanvalidation-1.0 feature restrictions

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

• There is no support for bean validation inside OSGi applications.

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 using properties files is not supported for JAR files containing only Enterprise JavaBeans (EJBs).

• Limiting a heap cache size works only for 32-bit Java virtual machines (JVM).

ejbLite-3.1 feature restrictions

For the ejbLite-3.1 feature, the following restrictions apply:

• EJB modules prior to version 3.0 are not supported. This restriction also means that bindings and extensions using 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.

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.

monitor-1.0 feature restriction

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

• When the feature is removed from server.xml, we must restart the server to make the JAX-WS applications work.

wmqJmsClient-1.1 feature restrictions

For the wmqJmsClient-1.1 feature, the following restrictions apply:

• We must manually set the PATH variable in the Windows environment variables to point to the WebSphere MQ installation bin directory. We must set this path variable when the application uses the BINDING connection mode.

• The WebSphere MQ classes for Java (generally called the Base Java) are not included in the wmqJmsClient-1.1 feature. This is included in the Resource Adapter for other application servers but is not recommended for the Base Java APIs in the Java Enterprise Edition environments.

  See Use WebSphere MQ Java Interfaces in J2EE/JEE Environments.

• The BINDINGS_THEN_CLIENT transport type of WebSphere 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.

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 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.

Parent topic: Troubleshooting tips

Concepts:

EJB 3.0 and EJB 3.1 application bindings overview

Reference:
Developer Tools known restrictions