Maven Overlay Project How To

Steps to create an overlay project

1. Create a directory for the top level: mkdir example-openid-connect-overlay

2. Create example-openid-connect-overlay/pom.xml

    <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">
      <modelVersion>4.0.0</modelVersion>  
      <groupId>org.example</groupId>  
      <artifactId>example-openid-connect-overlay</artifactId>
      <packaging>pom</packaging>
      <version>1.0-SNAPSHOT</version>
      <name>example-openid-connect-overlay</name>
      <modules>
        <module>OpenID-Connect-Java-Spring-Server</module>
        <module>my-openid-connect</module>
      </modules>
      <dependencies>
        <dependency>
          <groupId>org.mitre</groupId>
          <artifactId>openid-connect-server</artifactId>
          <type>war</type>
          <version>0.1-SNAPSHOT</version>
        </dependency>
      </dependencies>
      <properties>
        <java-version>1.6</java-version>
        <org.springframework-version>3.1.1.RELEASE</org.springframework-version>
        <org.slf4j-version>1.5.10</org.slf4j-version>
        <spring.security.version>3.1.0.RELEASE</spring.security.version>
      </properties>
      <build>
        <finalName>my-openid-connect-server</finalName>
      </build>
    </project>
   

   This creates a project with two modules, one bing the OpenID-Connect-Java-Spring-Server (the original), and my-openid-connect which will hold our modifications we want to overlay. We also set some global properties (versions of Java, Spring, etc.) and the finalName of our project.

3. Now clone the OpenID-Connect-Java-Spring-Server into the example-openid-connect-overlay/ directory

    cd example-openid-connect-overlay
    git clone https://github.com/mitreid-connect/OpenID-Connect-Java-Spring-Server.git
    cd OpenID-Connect-Java-Spring-Server
    git submodule update --init --recursive
   

   You now have the current version of OpenID-Connect-Java-Spring-Server. You should make sure that the version in example-openid-connect-overlay/OpenID-Connect-Java-Spring-Server/pom.xml matches the dependency version for openid-connect-server located in example-openid-connect-overlay/pom.xml

4. Create the my-openid-connect submodule

   Create the directory example-openid-connect-overlay/my-openid-connect and cd into it

5. Create example-openid-connect-overlay/my-openid-connect/pom.xml

    <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/xsd/maven-4.0.0.xsd">
      <modelVersion>4.0.0</modelVersion>
      <parent>
        <artifactId>example-openid-connect-overlay</artifactId>
        <groupId>org.example</groupId>
        <version>1.0-SNAPSHOT</version>
        <relativePath>..</relativePath>
      </parent>
      <artifactId>my-openid-connect</artifactId>
      <packaging>war</packaging>
      <build>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-compiler-plugin</artifactId>
          <configuration>
             <source>${java-version}</source>
             <target>${java-version}</target>
          </configuration>
        </plugin>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-war-plugin</artifactId>
          <version>2.1.1</version>
          <configuration>
            <overlays>
              <overlay>
                <groupId>org.mitre</groupId>
                <artifactId>openid-connect-server</artifactId>
              </overlay>
            </overlays>
          </configuration>
        </plugin>
      </plugins>
      </build>
        <properties>
          <java-version>1.6</java-version>
          <org.springframework-version>3.1.1.RELEASE</org.springframework-version>
          <org.slf4j-version>1.5.10</org.slf4j-version>
          <spring.security.version>3.1.0.RELEASE</spring.security.version>
        </properties>
        <dependencies>
          <dependency>
            <groupId>org.mitre</groupId>
            <artifactId>openid-connect-server</artifactId>
            <type>war</type>
            <version>0.1-SNAPSHOT</version> 
          </dependency>
          <dependency>
            <groupId>org.mitre</groupId>
            <artifactId>openid-connect-common</artifactId>
            <version>0.1-SNAPSHOT</version>
          </dependency>
        </dependencies>
    </project>
   

   At this point you should be able to do a mvn package from the example-openid-connect-overlay level and you'll get a .war file at example-openid-connect-overlay/my-openid-connect/target/my-openid-connect-server.war. Remember this name was set in the example-openid-connect-overlay/pom.xml as the finalName.

6. Any files you create in the my-openid-connect maven project will be inserted into the resultant war file. If you use the same name as a file in OpenID-Connect-Java-Spring-Server project, such as example-openid-connect-overlay/my-openid-connect/src/main/resources/META-INF/persistence.xml, the version from the my-openid-connect project will be used in the .war file. This is good for setting up things like database connections. You may also create new Spring beans with new names (in my-openid-connect/src/main/java/...) that implement or override the standard openid-connect beans. If you mark these with the Spring Framework's @Primary annotation, Spring will use your class instead of the default classes. You may need to add additional dependencies to the my-openid-connect/pom.xml configurations so you're code will compile.