Liberty profile: Runtime environment known restrictions

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

List of known issues and restrictions:

Minimum supported Java levels

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

Note: To obtain the minimum supported Java level for IBM iSeries®, install IBM J2SE 6.0 32-bit JVM (5761-JV1 option 11 Fix Pack 8552 or 5770-JV1 option 11) or IBM SE 6.0 64 bit (5761-JV1 option 12 Fix Pack 8552 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. You should 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 the Liberty profile, the profile 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 full profile scripts do not work with the Liberty profile

You 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 you use symbolic links with Filesets, you must 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 that are 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 your application code against these APIs using Java SDK version 6, you need to use classes that are provided by the Liberty profile rather than the Java SDK. You must take one of the following actions:
  • If you are using javac to build from the command line, compile your code by using the javac -endorseddirs option and the JAR files in the ${wlp.install.dir}/dev/specs directory.
  • If you are using Apache Ant to build, compile your code by 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 you are using Apache Maven to build, compile your code by 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>

Some server command logs are encoded in EBCDIC on IBM i

On the IBM i platform, some Liberty profile server command logs are encoded in EBCDIC. Typically, these logs are used to help debug server command exceptions. Examples are start.log for the server start command, and stop.log for the server stop command. If the command does not succeed, the log is written to the target server's logs directory.  Because these logs are encoded in EBCIDIC, they must either be viewed in an EBCDIC capable browser, or converted to ASCII then viewed in an ASCII capable browser.

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.

Fix Pack 8550

appSecurity-2.0 feature restrictions

For the appSecurity-2.0 feature, the following restrictions apply:
  • Fix Pack 8550 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.

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.
Fix Pack 8550

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).
Fix Pack 8550

ejbLite-3.1 feature restrictions

Fix Pack 8550 For the ejbLite-3.1 feature, the following restrictions apply:
  • Fix Pack 8550 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.
Fix Pack 8550

jaxb-2.2 feature restriction

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. Other wise, 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 the Liberty profile, see Overriding a provided API with an alternative version.
Fix Pack 8550

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 profile is the ibm-ws-bnd.xml file. The following web services binding files for the full profile 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 the Liberty profile. For example, <testID>.
  • The -inlineSchemas option is not supported by the wsgen tool that is provided by the Liberty profile.
  • 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.

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.
Fix Pack 8550

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.
Fix Pack 8550

wmqJmsClient-1.1 feature restrictions

For the wmqJmsClient-1.1 feature, the following restrictions apply:
  • Fix Pack 8550 You must manually set the PATH variable in the Windows environment variables to point to the WebSphere MQ installation bin directory. You must set this path variable when the application uses the BINDING connection mode.
  • Fix Pack 8550 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. For more information, see Using WebSphere MQ Java Interfaces in J2EE/JEE Environments.
  • Fix Pack 8550 The BINDINGS_THEN_CLIENT transport type of WebSphere MQ resource adapter is not supported for the wmqJmsClient-1.1 feature.
  • Fix Pack 8550 The Advanced Messaging Security (AMS) feature is not included for the wmqJmsClient-1.1 feature.
Fix Pack 8550

collectiveController-1.0 feature restriction

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


Icon that indicates the type of topic Reference topic

Terms and conditions for information centers | Feedback


Timestamp icon Last updated: Monday, 21 April 2014
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-iseries&topic=rwlp_restrict
File name: rwlp_restrict.html