GlassFish Wiki : AddingModule

Adding a Module to GlassFish V3

Addding a module to GlassFish is pretty easy, first you create the module and have it published in the maven repository, then you add entries in the distribution pom.xml to package it in the distribution.

Module Creation

When creating a module, you either already have the source files (coming from v2 codebase most likely) or you create new sources alltogeher. The latter is a lot more simple to handle.

Case 1 : I don't have the sources

Create a new directory under glassfish or create a new java.net project if you think your artifact can be reused independently of GlassFish. In this directory, create a src/java directory and place your sources there. There is in fact documentation on the maven web site that describe how projects should be organized. You can also look at the hk2.java.net for examples.

Once you have your sources you need to create a pom.xml to compile everything. The simplest pom.xml can be found in appserv-api/pom.xml

This pom file insures that the maven plugins for v3 are invoked when compiling, declares it's dependency on the hk2 APIs and produces a full module with the right manifest entries.

 
        <?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">


    <parent>
        <artifactId>bootstrap</artifactId>
        <groupId>com.sun.enterprise.glassfish</groupId>
        <version>10.0-SNAPSHOT</version>
    </parent>    
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.jvnet.glassfish</groupId>
    <artifactId>glassfish-api</artifactId>
    <packaging>hk2-jar</packaging>
    <version>${project.parent.version}</version>
    <name>Public APIs of Glassfish V3</name>

    <build>
        <sourceDirectory>src/java</sourceDirectory>
		<plugins>
        <plugin>
            <groupId>com.sun.enterprise</groupId>
            <artifactId>hk2-maven-plugin</artifactId>
        </plugin>
	</plugins>
	</build>
    <dependencies>
        <dependency>
            <groupId>com.sun.enterprise</groupId>
            <artifactId>hk2</artifactId>
            <version>${hk2.version}</version>
        </dependency>
    </dependencies>
</project> 
       

Be aware of the following points :

use hk2-jar as the packaging so you get the manifest file generated automatically
use the sourceDirectory to point to your source directory
rememember to put the hk2-maven-plugin in your plugins so the META-INF/Services files are generated automatically.

Case 2 : I already have the sources somewhere and I want to compile and package them all

Easy enough, it's like case 1, except you don't get to choose the sourceDirectory.

Case 3 : I have the sources and I only want a subset of them

On top of what you have to do in case 1, you need to configure the plugin compiler to include or exclude sources. glassfish/appserv-commons is a good place to look at how this is done. I have splitted the appserv-commons sources in 2 modules, one is the commons module, the other is the DOL.

I created a maven subdirectory and placed each pom.xml in a separate subdir (commons and dol). I did not move the sources under these directories because I want to retain the ability to merge the code with the trunk and for that the sources cannot be moved, therefore the sourceDirectory in the pom.xml points to ../../src/java

After that it's pretty simple albeit a bit combersome :

 
        <modelVersion>4.0.0</modelVersion>
    <artifactId>commons</artifactId>
    <packaging>hk2-jar</packaging>
    <name>Appserver V3 Common Classes</name>
    <description>Glassfish appserver V3 common launcher classes</description>

    <build>
        <sourceDirectory>../../src/java</sourceDirectory>
        <plugins>
            <plugin>
                <groupId>com.sun.enterprise</groupId>
                <artifactId>hk2-maven-plugin</artifactId>
                <configuration>
                    <includes>
                        <include>com/sun/logging/LogDomains.*</include>
                        <include>com/sun/enterprise/util/LocalStringManager.java</include>
                        <include>com/sun/enterprise/util/LocalStringManagerImpl.java</include>
                        <include>com/sun/enterprise/util/StringUtils.java</include>
                        <include>com/sun/enterprise/util/SystemPropertyConstants.java</include>
                        <include>com/sun/enterprise/util/OS.java</include>
                        <include>com/sun/enterprise/util/io/FileUtils.java</include>
                        <include>com/sun/enterprise/util/io/FileLister.java</include>
                        <include>com/sun/enterprise/util/io/FileListerRelative.java</include>
                        <include>com/sun/enterprise/util/zip/**</include>
                        <include>com/sun/enterprise/util/i18n/**</include>
                        <include>com/sun/enterprise/admin/monitor/callflow/**</include>                        
                        <include>com/sun/enterprise/config/**</include>
                        <include>com/sun/enterprise/util/RelativePathResolver.java</include>
                        <include>com/sun/enterprise/security/store/**</include>
                        <include>com/sun/enterprise/deployment/deploy/shared/**</include>
                        <include>com/sun/enterprise/deployment/util/DOLUtils.java</include>
                        <include>com/sun/enterprise/util/shared/ArchivistUtils.java</include>
                        <include>com/sun/enterprise/deployment/backend/IASDeploymentException.java</include>
                    </includes>
                    <excludes>
                        <exclude>com/sun/enterprise/config/ConfigBeansFactory.java</exclude>
                        <exclude>com/sun/enterprise/config/ConfigBeanBase.java</exclude>
                        <exclude>com/sun/enterprise/config/ConfigChangeFactory.java</exclude>
                        <exclude>com/sun/enterprise/config/clientbeans/**</exclude>
                        <exclude>com/sun/enterprise/config/impl/ConfigContextImpl.java</exclude>
                        <exclude>com/sun/enterprise/config/ConfigFactory.java</exclude>
                        <exclude>com/sun/enterprise/config/ConfigContextFactory.java</exclude>
                        <exclude>com/sun/enterprise/config/ConfigRegistry.java</exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
        <resources>
            <resource>
                <directory>../../src/java</directory>
                <includes>
                    <include>**/*.properties</include>
                </includes>
            </resource>
        </resources>
    </build>
    
    <dependencies>
        <dependency>
            <groupId>javax.xml.bind</groupId>
            <artifactId>jaxb-api</artifactId>
            <version>2.1</version>
        </dependency>
        <dependency>
            <groupId>org.jvnet.glassfish</groupId>
            <artifactId>glassfish-api</artifactId>
            <version>${project.version}</version>
        </dependency>        
    </dependencies>
</project> 
       

As you can see, there are resources in this examples too but overall it ressembles the case 1, just more complicated.

How to get your bundled shipped with the distribution

So now you have create your new modules, you want to have them being packaged with the glassfish distribution to start testing.

Say you have the following new module :

 
        <modelVersion>4.0.0</modelVersion>
    <groupId>com.sun.enterprise</groupId>
    <artifactId>random-module</artifactId>
    <version>${random-module.version}</version>
    <packaging>hk2-jar</packaging>
    <name>Some Random classes that are needed</name> 
       

in the glassfish/distributions/pe/pom.xml, just add you module in the list of dependencies :

 
        <dependency>
      <groupId>com.sun.enterprise</groupId>
      <artifactId>random-module</artifactId>
      <version>${random-module.version}</version>
      <scope>runtime</scope>
    </dependency> 
       

and that's it, you should find your new module in the glassfish/lib directory after the packaging. Any dependent jar will be placed in the glassfish/lib/jars and the system will hook things up automatically at runtime.