GServlet API

Table of contents

1. Description
2. Main Features
3. Requirements
4. Getting Started
5. Building from source
6. Versioning
7. Status
8. Relase Plan
9. Snapshot builds
10. Contributing
11. License

Description

GServlet is an open source project inspired from the Groovlets, which aims to use the Groovy language and its provided modules to simplify Servlet API web development. Groovlets are Groovy scripts executed by a servlet. They are run on request, having the whole web context (request, response, etc.) bound to the evaluation context. They are much more suitable for smaller web applications. Compared to Java Servlets, coding in Groovy can be much simpler. It has a couple of implicit variables we can use, for example, request, response to access the HttpServletRequest, and HttpServletResponse objects. We have access to the HttpSession with the session variable. If we want to output data, we can use out, sout, and html. This is more like a script as it does not have a class wrapper.

Groovlet

if (!session) {
    session = request.getSession(true)
}
if (!session.counter) {
    session.counter = 1
}
html.html {
  head {
      title('Groovy Servlet')
  }
  body {
    p("Hello, ${request.remoteHost}: ${session.counter}! ${new Date()}")
  }
}
session.counter = session.counter + 1

The same philosophy has been followed in the design of this API while maintaining a class-based programming approach.

SessionCounterServlet.groovy

import org.gservlet.annotation.Servlet

@Servlet("/counter")
class SessionCounterServlet {

  void get() {
    if (!session.counter) {
      session.counter = 1
    }
    html.html {
      head {
        title('Groovy Servlet')
      }
      body {
        p("Hello, ${request.remoteHost}: ${session.counter}! ${new Date()}")
      }
    }
    session.counter = session.counter + 1
  }

}

More information can be found on the project homepage where you can find the online documentation and the Javadocs for a particular release can be browsed as well.

Main Features

• Servlet 3.1+ Support
• Groovy Scripting and Hot Reloading
• JSON, XML, HTML and JDBC Support

Requirements

• Java 8
• Java IDE (Eclipse, IntelliJ IDEA, NetBeans..)
• Java EE 7+ compliant WebServer (Tomcat, Wildfly, Glassfish, Payara..)

Getting Started

If you are just getting started with GServlet, you may want to begin by creating your first project. This section shows you how to get up and running quickly. It is highly recommended to consume the GServlet API through a dependency management tool and the artifact can be found in Maven's central repository. It is named gservlet-api and you just need to name a dependency on it in your project.

Maven

<dependency>
 <groupId>org.gservlet<groupId/>
 <artifactId>gservlet-api</artifactId>
 <version>1.0.1</version>
</dependency>

Gradle

 repositories {
    mavenCentral()
}

dependencies {
    compile("org.gservlet:gservlet-api:1.0.1")
}

Your First Groovy Servlet

Once your Java web server is installed and configured, you can put it to work. Five steps take you from writing your first Groovy servlet to running it. These steps are as follows:

1. Create a dynamic web project
2. Create the groovy folder inside your webapp directory
3. Write the servlet source code
4. Run your Java web server
5. Call your servlet from a web browser

You can find below some examples that you can try out and for a hot reloading of your source code, set the GSERVLET_RELOAD environment variable to true in your IDE.

ProjectServlet.groovy

import org.gservlet.annotation.Servlet

@Servlet("/projects")
class ProjectServlet {

	def projects = []

	void init() {
	   projects << [id : 1, name : "Groovy", url : "https://groovy-lang.org"]
	   projects << [id : 2, name : "Spring", url : "https://spring.io"]
	   projects << [id : 3, name : "Maven", url : "https://maven.apache.org"]
	}

	void get() {
	   json(projects)
	}

	void post() {
	   def project = request.body
	   projects << project
	   json(project)
	}

	void put() {
	   def project = request.body
	   int index = projects.findIndexOf { it.id == project.id }
	   projects[index] = project
	   json(project)
	}

	void delete() {
	  def project = request.body
	  int index = projects.findIndexOf { it.id == project.id }
	  json(projects.remove(index))
   }
	
}

CorsFilter.groovy

import org.gservlet.annotation.Filter

@Filter("/*")
class CorsFilter {

    void filter() {
      response.addHeader("Access-Control-Allow-Origin", "*")
      response.addHeader("Access-Control-Allow-Methods","GET, OPTIONS, HEAD, PUT, POST, DELETE")
      if (request.method == "OPTIONS") {
        response.status = response.SC_ACCEPTED
        return
      }
      next()
    }
    
}

ServletRequestListener.groovy

import org.gservlet.annotation.RequestListener

@RequestListener
class ServletRequestListener {
	
   void requestInitialized() {
     println "request initialized"
   }
	
   void requestDestroyed() {
     println "request destroyed"
   }

}

For a deep insight of how to write your Groovy artifacts, please refer to the developer guide.

Code Examples

We have created several code examples to help beginners to learn and gain expertise at GServlet. Checkout the appropriate branch for the version that you are using.

Building from source

> git clone git@github.com:gservlet/gservlet-api.git
> cd gservlet-api
> mvn clean install

Documentation

The developer guide generated with Maven is based on Asciidoctor. Only the HTML output is enabled.

> mvn clean generate-resources -Pdocumentation

The built documentation can then be found in the following location:

> ./target/generated-docs

On the other hand, the Javadocs can be found in the folder:

> ./target/site/apidocs    

We use UMLGraph to generate UML class diagrams which are embedded in the Javadocs, therefore you must have Graphviz installed in your computer and the GraphvizX.XX\bin directory added to your system PATH.

Versioning

We version GServlet by following the Semantic Versioning, which is a general template that everyone uses and understands.

Status

The current version of GServlet is 1.0.1.

Release Plan

• 1.x.x : Java EE 7+ and Jakarta EE 8 support
• 2.x.x : Jakarta EE 9 support
• 3.x.x : Jakarta EE 10 support

Snapshot builds

You can access snapshot builds from the sonatype snapshot repository by adding the following to your repositories:

<repository>
	<id>sonatype-nexus-snapshots</id>
	<name>Sonatype Nexus Snapshots</name>
	<url>https://oss.sonatype.org/content/repositories/snapshots/</url>
	<snapshots>
		<enabled>true</enabled>
	</snapshots>
	<releases>
		<enabled>false</enabled>
	</releases>
</repository>

Contributing

New contributors are always welcome. We collected some helpful hints on how to get started on our Contribute page.

License

GServlet is an Open Source software released under the Apache 2.0 license.