com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_link3' is unknown.

Webapp ClassLoading

Usually, Web applications that are deployed in production environments depend on external, third-party libraries for different functionality. WSO2 Web application management feature provides capability to load classes from different locations to your applications.

Through the WSO2 Application Server's runtime environment, you can control class loading per server/application. The default runtimes are sufficient for most users, but you can also define your own runtimes. There are three default run-times available so far as follows:

  • Tomcat  Environment : This is the minimal runtime, which is identical to a pure Tomcat runtime. It only has Tomcat, Servelet, JSP, EL, JSTL available in the server-level classpath. If you want additional Jars, you should package them with the Web application or place in 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 in WSO2 Carbon environment's extension directory.
  • CXF Environment : This consists of the Tomcat environment, CXF and Spring. It does not provide the Carbon runtime. If you want additional Jars, you should package them with the Web application or place in CXF environment's lib directory.

Next, let's take a look at how to place your external dependencies in a running Carbon server in order to configure class loading per application or server.

Configuring Class Loading

To configure class loading, you should add the class-loading configuration in a file by the name webapp-classloading.xml, and place it in the META-INF directory of a Web application. All the artifacts related to a Web application is saved in <PRODUCT_HOME>/repository/deployment/server/<Web_Application_Type>/<Web_Application_Name>. For example, <PRODUCT_HOME>/repository/deployment/server/jaxwebapps/SampleApp.

To use runtime environments other than Carbon, provide the webapp-classloading.xml file with correct configurations. Else, the application will be deployed in the default Carbon runtime environment.

webapp-classloading.xml file takes following format.

<Classloading xmlns="http://wso2.org/projects/as/classloading"> 
   <Environments>{Runtime Environment Names} </Environments> 
</Classloading> 

Shown below is the webapp-classloading.xml file configuration to specify CXF as the runtime environment:

<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 webapp-classloading.xml. The following example specifies both CXF and Carbon as the runtime environments:

<Classloading xmlns="http://wso2.org/projects/as/classloading">
   <Environments>CXF,Carbon</Environments>
</Classloading>

Runtime Environment Extensions

You can share dependencies with a number of applications without packaging them with each and every one of them.To do this, place the common dependencies in the following directories depending on your environment.

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

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 <PRODUCT_HOME>/lib/runtimes/ext, 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 the Web application in Tomcat environment itself. Libraries which are only used by a particular Web application can be put into <webapp_name>.war/WEB-INF/lib directory.

Adding Custom Runtime Environments

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

The following steps explain how to define a custom runtime environment for Spring.

1. Modify the webapp-classloading-environments.xml file with following entries.

<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 related Spring dependencies to <PRODUCT_HOME>/lib/runtimes/spring directory.

3. Add the following entries to the webapp-classloading.xml file of each Web application to use them in the Spring runtime environment defined above.

<Classloading xmlns="http://wso2.org/projects/as/classloading">
   <Environments>Spring,Carbon</Environments>
</Classloading>

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.3 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. Spring project does not recommend this as it will cause several classloading issues.

  2. CXF 2.7.3 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.3 and core Spring 3.0.7 dependencies. If you want to upgrade to a different CXF version, there are two recommendations:

    • Upgrade the CXF runtime environment : You can replace the existing CXF/Spring dependent Jars in <PRODUCT_HOME>/lib/runtimes/cxf directory, with new CXF/Spring Jars.

    • Instead of upgrading server-level CXF dependencies, you can package all the required Jars in the Web-INF/lib directory of the Web application and deploy that in Tomcat runtime environment.

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

Note:

Class loading pattern for Web applications is always child-first. You can't change this. Therefore location 2 is always given the highest priority when the same library exists in both locations.

com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links2' is unknown.