Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Usually, web applications that are deployed in production environments depend on external, third-party libraries for different functionalityWSO2 AS leverages a concept called runtime environments to separately maintain different runtimes for loading the relevant classes for your web applications. The WSO2 web application management feature provides the capability to load classes from different locations to your applications.

Most web applications that are deployed in production environments depend on external, third-party libraries for different functionality. Through the WSO2 Application Server's runtime environment, you can control class loading per server or application. The default following runtimes that are available with WSO2 AS are sufficient for most users, but you can also define your own runtimes. There are four default run-times runtime environments available in AS 65.03.0, which are as follows:

  • Tomcat Environment: This is the minimal runtime, which is identical to a pure Tomcat runtime. It only has Tomcat, Servlet, JSP, EL and JSTL available in the server-level classpath. If you want additional JARs, you should package them with the web application or place them in the Tomcat environment's extension directory.
  • Carbon Environment: This consists of both the Tomcat environment and the WSO2 Carbon runtime. It does not provide CXF or Spring dependencies. If you want additional JARs, you should package them with the web application or place them in the WSO2 Carbon environment's extension directory.
  • CXF Environment: This consists of the Tomcat environment, CXF and Spring. It does not provide the WSO2 Carbon runtime. If you want additional JARs, you should package them with the web application or place them in the CXF environment's lib directory.
  • Javaee Environment: This consists of the Javaee

    runtime.  

The subsequent sections explain how to place your external dependencies in a running Carbon server, to configure class loading per application or server.

...

  • runtime and the WSO2 Carbon runtime. If you want additional JARs, you should package them with the web application or place them in the Javaee environment's lib directory.

See the following topics for more information:

Table of Contents
maxLevel3
minLevel3

Setting up the runtime environment

To configure class loading, you should add the class - loading configuration in a file named webapp-classloading.xml and place it in the META-INF directory folder of a web application. All This folder should be created inside the src/main/webapp folder of you web application. All the artifacts related to a web application are saved in the following directory: <PRODUCT_HOME>/repository/deployment/server/<Web_Application_Type>/<Web_Application_Name>For example: <PRODUCT_HOME>/repository/deployment/server/webapps/SampleApp.

Info
To use The Carbon runtime is the default runtime in WSO2 products. If you want to use the runtime environments other than Carbon, provide the webapp-classloading.xml file with the correct configurations. Otherwise, the application will be deployed in the default Carbon runtime environment.

The webapp webapp-classloading.xml file takes the following format.:

Code Block
languagehtml/xml
<Classloading xmlns="http://wso2.org/projects/as/classloading"> 
   <Environments>{Runtime Environment Names} </Environments> 
</Classloading> 
  • Shown below is the the webapp-classloading.xml file  file configuration to specify CXF as the runtime environment:

    Code Block
    languagehtml/xml
    <Classloading xmlns="http://wso2.org/projects/as/classloading">
       <Environments>CXF</Environments>
    </Classloading>
  • You might want to access some Carbon features in a CXF application. To achieve this, specify a comma-separated list of environments in the webapp-classloading.xml file file. The following example specifies both CXF and Carbon as the runtime environments:

    Code Block
    languagehtml/xml
    <Classloading xmlns="http://wso2.org/projects/as/classloading">
       <Environments>Spring,Carbon</Environments>
    </Classloading>
  • You might want to access some Carbon features in a Javaee application. To achieve this, specify a comma-separated list of environments in webapp-classloading.xml file. The following example specifies both Javaee and Carbon as the runtime environments:

    Code Block
    languagehtml/xml
    <Classloading xmlns="http://wso2.org/projects/as/classloading">
       <Environments>Javaee,Carbon</Environments>
    </Classloading>

Runtime Environment Extensions

...

  • From AS 5.3.0 onwards, Java EE 6 Web Profile support is available as a feature, which allows you to enable the Javaee runtime environment, in addition to TomcatCarbon and CXF runtime environments. See the topic on enabling Java EE 6 Web Profile for step-by-step instructions on configuring the Java EE runtime.

Extending the runtime environments

This section explains how to place your external dependencies in a running server. This allows you to share dependencies with a number of applications without packaging them with each and every one of themapplication. To do this, place the common dependencies in the following directories depending on your environmentrelevant directories given below.

  • In Tomcat Environment - <PRODUCT_HOME>/lib/runtimes/ext
  • In Carbon Environment - <PRODUCT_HOME>/repository/components/lib
  • In CXF, Javaee or any Custom Environment – Use the environment's lib directory directory.
    For  For example:
     <PRODUCT_HOME>/lib/runtimes/cxf
Info

Practice caution when placing dependency files in Tomcat environment's ext directory as those dependencies will be visible to all other environments. For example, if you place incompatible Spring dependencies in the <PRODUCT_HOME>/lib/runtimes/ext directory, it can cause problems with the existing Spring dependencies in the CXF runtime environment.

If there are such incompatible dependencies, the recommended best practice is to package them in with the web application in the Tomcat environment itself. Libraries that are only used by a particular web application can be put into the <webapp_name>.war/WEB-INF/lib directory.

Adding Custom Runtime Environments

To define custom runtime environments, add a new element as as <ExclusiveEnvironments> in  in the <PRODUCT <PRODUCT_HOME>/repository/conf/tomcat/webapp-classloading-environments.xml file file.  

To define a custom runtime environment for Spring.:

  1. Modify the the webapp-classloading-environments.xmlfile with the following entries.

    Code Block
    languagehtml/xml
    <ExclusiveEnvironments> 
       <ExclusiveEnvironment> 
          <Name>Spring</Name> 
          <Classpath>${carbon.home}/lib/runtimes/spring/*.jar;${carbon.home}/lib/runtimes/spring/</Classpath> 
       </ExclusiveEnvironment> 
    </ExclusiveEnvironments>
  2. Next, create and copy of the related Spring dependencies in the the <PRODUCT_HOME>/lib/runtimes/spring directory directory.
  3. Add the following entries to the the webapp-classloading.xml file  file of each web application , to use them in so that they can be used in the Spring runtime environment defined above.

    Code Block
    languagehtml/xml
    <Classloading xmlns="http://wso2.org/projects/as/classloading">
       <Environments>Spring,Carbon</Environments>
    </Classloading>
Info

Note that adding custom runtime environments to your system without studying their impact can cause unfavorable results. For example, assume an Application Server (AS) instance contains the following configurations.

  • CXF (runtime provided by AS) contains CXF 2.7.5 and Spring 3.0.7 dependencies.

  • Spring (custom runtime) contains Spring 3.2.1 dependencies.

If a web application consumes both of the above environments, the following problems will arise:

  1. The web application's classpath contains dependencies from two Spring versions as 3.0.7 and 3.2.0. The Spring project does not recommend this as it will cause several classloading issues.

  2. CXF 2.7.5 itself uses Spring 3.0.7. It is possible that a particular CXF version is not properly tested for compliance with another version of Spring. You should study the CXF project recommendations to find a suitable Spring version.

Upgrading Existing Runtime Environments

The CXF runtime environment comes by default with core CXF 2.7.5 and core Spring 3.0.7 dependencies. If you want to upgrade to a different CXF version, there are two recommendations:

If you want to add optional optional CXF/Spring JARs JARs, copy them to the <PRODUCT_HOME>/lib/runtimes/cxf directory  directory after ensuring that they are compatible with the existing JARs.

Info

Class loading pattern for web applications is always child-first and this can not be changed. Therefore, location 2 is always given the highest priority when the same library exists in both locations.