Maven + Lucee, Part 2

Maven + Lucee, Part 2

So in part 1, we walked through setting up a WAR application with Lucee 5 embedded.  In this post, I will walk through creating a Maven project to produce a LAR artifact from a set of utility CFCs.

So you may ask, what is a LAR?  It stands for Lucee ARchive, and it is a zip archive of your CFML components and templates.  They come in two flavors: regular archives and component archives.  Regular archives are mapped with virtual paths and can be made web-accessible - think webjars for CFML templates.  Component archives are more similar to JARs as you know them, and are useful for bundling APIs or utility libraries for reuse.

Some other interesting features about LAR archives is that they contain the actual Java class files generated from your CFML code.  This is important for two reasons.  It means that the Lucee engine does not have to do its JIT compilation.  It also means that LAR files allow you to build source-less deploys if you are wanting to provide commercially-licensed packages.

So let's get started.  For this tutorial, I will again be using CFEclipse with M2E.  I will also be using a custom maven plugin I've been working on to provide the lar packaging type, which simplifies this process greatly.

Creating a project

Typically for a LAR project, I start by creating a simple Maven Java project:

1. File > New > Maven Project (or just Project, then search for Maven Project)
2. Check the box labeled Create a simple project (skip archetype selection)
3. Click next to continue filling out the project information, and click Finish when you are done.

Once you have your project created, you need to reconfigure your source folders.

1. Rename the src/main/java folder to src/main/lucee. The easiest way to do this is by clicking the folder, hitting F2 and entering lucee in the dialog.
2. For the time being, delete the src/test folders.  I am not aware of any plugins that are compatible with surefire that can do automated CFML testing (although that is next on my list).

Now it is time to configure the project to use the lar-maven-plugin.  As of now, the plugin is only available as a snapshot release.

To make use of this project, simply add the following to your pom.xml:

  <packaging>lar</packaging>

  <build>
    <plugins>
        <plugin>
            <groupId>org.jdsnet.maven.lucee</groupId>
            <artifactId>lar-maven-plugin</artifactId>
            <version>0.1.0-SNAPSHOT</version>
            <extensions>true</extensions>
        </plugin>
    </plugins>
  </build>

  <pluginRepositories>
    <pluginRepository>
      <id>dajester2013-snapshots</id>
      <url>http://dajester2013.github.io/maven-snapshots/</url>
    </pluginRepository>
  </pluginRepositories>

Your project is now set up.  By default, the plugin is configured to build a component archive.  To build a regular archive, you can add the following configuration to the plugin:

  <configuration>
    <larType>mapping</larType>
    <larVirtualPath>/my-mapping</larVirtualPath>
  </configuration>

You can use M2E's completions to see other options.

Building your project

At this point, your project is ready to start adding your CFML source.  You can begin creating packages/components/etc. within your lucee source directory.  When you are ready to build, you can right-click on the project and select Run As > maven install.  This will execute the packaging phase, and install the .lar artifact in your local repository.

Hopefully this will prove helpful to the community moving forward!  Any questions feel free to ask below, or check out the plugin project at https://github.com/dajester2013/lucee-maven-plugin/.

Maven + Lucee, part 1

Introduction

Recently I started working with Maven for new Lucee-based web applications.  I'd like to share what I've learned so far.  I will be using Eclipse WTP for this series, as it provides everything I need to run the app from one spot.

My setup:

* Eclipse 4.1 Mars

* Eclipse WTP tools, including the necessary servlet container connector run Tomcat

* Tomcat 8

* Java 8

* Eclipse J2EE tools

* M2E

* EGit

* CFEclipse

For this series, I will assume that you have a Tomcat server instance registered in your Eclipse IDE.

Part 1: Basic Dynamic Web App

Create the project:

For this post, I am starting off by creating a new Dynamic Web Project:

I chose this instead of starting from a maven archetype, because the sample webapp archetype is set on servlet api version 2.5, and I want to be able to configure it myself.  I've selected 3.1 for this example:

However, because I chose to do this, I have to make some changes to the default source folders to make it maven-friendly:

Now that I have a basic project created, I can add Maven support:

At this point, I now have a project that I can begin adding content.  You can add index.html to your src/main/webapp directory, then right-click the project folder and select Run As > Run on Server.

Now to set up Lucee.  I will be working with the most recent release candidate for this example. It is available on maven central. However, if you want to work with the latest snapshot, those are available (at least at the time of writing this) on Sonatype's snapshots repo:

<repositories>
  <repository>
    <id>sonatype-snapshots</id>
    <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
  </repository>
</repositories>

Now to add the dependencies:

<dependencies>
  <dependency>
    <groupId>org.lucee</groupId>
    <artifactId>lucee</artifactId>
    <version>5.0.0.213-RC</version> 
    <!-- all the runtime dependencies are embedded or will be downloaded on demand by lucee -->
    <exclusions>
      <exclusion>
        <artifactId>*</artifactId>
        <groupId>*</groupId>
      </exclusion>
    </exclusions>
  </dependency>

  <dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>3.1.0</version>
    <scope>provided</scope>
  </dependency>
</dependencies>

First I add the lucee dependency.  It has several transitive dependencies that are not necessary, so I excluded all of them.  It does have one dependency that is necessary - that being felix.  Right now, the required version is 4.2.1.  There is talk of bundling the felix runtime into the lucee jar, so in the future, this dependency could be eliminated also.  Finally, for Eclipse to work properly, you either need to add a runtime library to the project, or add the servlet-api.  It is not necessary to include this into the final war, so set the scope to provided.

The last thing to do is to add the servlets/mappings to src/main/webapp/WEB-INF/web.xml (you can see an example here), and then you can add your application files to src/main/webapp.

Now you can run your application from within Eclipse, or use

mvn package to generate your war file.  Hope this proves helpful to someone.

It's official. I've started a blog.

I am a web developer, primarily working with CFML and JavaScript.  This will mainly be a collection of my experiences along the way.