[Download] | [Documentation Index] | [Release Note]

WSO2 Application Server Class Loading

Contents

Introduction

Most of the time, real Web Services and Web Applications which are deployed in production environments depend on external libraries for different functionalities. Web Services and Web Applications deployed in AppServer can load classes from different locations. Therefore, it is important to understand how you can place your external dependencies within WSO2 AppServer in the most suitable manner according to your requirement.

Class Loading for Web Services

Note: If any of the folders specified in this document doesn't exist by default, you can create those manually.

There are different kinds of services like AAR services, JAX-WS services etc. that can be deployed in WSO2 AppServer. You can upload those services from the management console. However, finally those service archives will be written to the relevant folder under the following location of the file system. 
CARBON_HOME/repository/deployment/server/
In this folder, there are separate sub folders for different types of services. Those are called deployment folders for different service types.

Ex: 
        AAR Services - CARBON_HOME/repository/deployment/server/axis2services
        JAX-WS Services - CARBON_HOME/repository/deployment/server/servicejars
These services can load classes from 4 different locations. Numbers 1, 2, 3, 4 will be used to refer the above 4 locations respectively.
  1. CARBON_HOME/repository/components/lib

    When a .jar file is copied into this location, it will be converted into an OSGi bundle and injected into the Carbon OSGi runtime. Any other OSGi bundle can import packages provided by the copied .jar file. We recommend users to copy external libraries into this location when it is necessary to make the dependency available within the OSGi environment.

    Ex: If you've installed mediation features into WSO2 AppServer and you want to share the same library between a mediator and a AAR service.

    Note: If your external dependency is already an OSGi bundle, you can directly copy that bundle into CARBON_HOME/repository/components/dropins folder and the behavior will be the same as above.

  2. CARBON_HOME/repository/deployment/server/lib

    As mentioned above, all sub folders relevant to different service types exist under the "server" folder. So this 'lib' is the place to copy libraries which should be shared across different services of different service types.

    Ex: If you have a AAR service and a JAX-WS service which shares the same dependency, you can copy it into this location.

  3. CARBON_HOME/repository/deployment/server/<deployment_folder>/lib

    The "deployment_folder" here is the relevant folder for the service type. For AAR services, it is "axis2services". This 'lib' is the place to copy libraries which should be shared across different services of the same service type.

    Ex: If you have two different AAR services which shares the same dependency, you can copy it into the axis2services/lib folder.

  4. 'lib' folder inside the service archive file

    You can include your external libraries into the service archive file itself. Create a 'lib' folder on the top level of your archive file and include the dependency inside that folder. This is recommended to be done when the external library is used only by the particular service.

    Ex: If your StudentMarks.aar service depends on foo.jar, embed the .jar file inside the AAR file as shown below.

                    StudentMarks.aar
                    - META-INF
                        - services.xml
                    - lib
                        - foo.jar
                    - org
                        - wso2
                            - sample
                                - Marks.class

Now let's have a look at how we can change the class loading behavior among the above mentioned locations.

Parent First Class Loading

WSO2 AppServer follows parent first class loading by default. You can see that by opening the CARBON_HOME/repository/conf/axis2.xml file and checking the following parameter.

<parameter name="EnableChildFirstClassLoading">false</parameter>

That means the priority reduces in the order 1 > 2 > 3 > 4 above. So when loading classes, highest priority is given to location 1 above and the least priority is give to location 4 above.

Ex: If you have two different versions of the same library in 1 and 3 above and your AAR service depends on that library, classes will be loaded from the library in location 1.

Child First Class Loading

If you want to enable child first class loading, you can do that by opening the CARBON_HOME/repository/conf/axis2.xml file and setting the value of the following parameter to 'true'.

<parameter name="EnableChildFirstClassLoading">true</parameter>

That means the priority reduces in the order 4 > 3 > 2 > 1 above. So when loading classes, highest priority is given to location 4 above and the least priority is give to location 1 above.

Ex: If you have two different versions of the same library in 1 and 3 above and your AAR service depends on that library, classes will be loaded from the library in location 3.

Enabling Child First Class Loading for a particular Service

If you want to enable child first class loading only for a particular AAR service while the overall server behavior remains parent first, you can add the above parameter into the META-INF/services.xml file of the AAR file.

<parameter name="EnableChildFirstClassLoading">true</parameter>

Ex: If you have two different versions of the same library in location 1 and 4 above, adn your service depends on that library, classes will be loaded from the library in location 4.

Note: You can only control the behavior of location 4 using this method. Therefore, use this method only when you've embedded your libraries inside your service archive.

Class Loading for Web Applications

Web Applications deployed in WSO2 AppServer can load classes from two locations.

  1. CARBON_HOME/lib

    If you want to share the same library between two Web Applications, you can copy that into this location.
  2. <webapp_name>.war/WEB-INF/lib

    Libraries which is only used by a particular .war file can be put into this location.

Important: You have to be careful when copying libraries into above location 1 as it can change the behavior of the server if a conflict occurs with the existing libraries. Therefore, it is recommended to use location 2 whenever possible.

Class loading pattern for Web Applications is always child first and you can't change it. Therefore location 2 above is always given the highest priority when the same library exists in both locations.