Default URL Mappings

You can find the URL mappings’ configuration file, UrlMappings.groovy, with the other configuration files in grails-app/conf/. It uses a simple domain-specific language to map URLs. Listing 9-6 shows the default contents of the file.

Listing 9-6.  Default UrlMappings.groovy

1.  class UrlMappings {
2.     static mappings = {
3.         "/$controller/$action?/$id?"{
4.             constraints {
5.                 // apply constraints here
6.             }
7.         }
8.             "500"(view:'/error')
9.     }
10. }

In case you thought the Grails URL convention was magic, well, it isn’t. Line 3 of Listing 9-6 reveals how the convention is mapped to a URL. The first path element, $controller, as explained in Chapters 4 and 5, identifies which controller handles the request. $action optionally (as noted by the ? operator, similar to the safe dereferencing operator in Groovy) identifies the action on the controller to perform the request. Finally, $id optionally specifies the unique identifier of a domain object associated with the controller to be acted upon.

Listing 9-6 shows how this configuration file maps the default URLs. It is completely customizable if you don’t like the default or if you want to create additional mappings for things such as RESTful web services. Mappings are explained in the next section.

RESTful Mappings

The basic concept behind RESTful URL mappings involves mapping a URL and an HTTP method to a controller and an action.

Listing 9-7.  RESTful URL Mapping

static mappings = {
   "/user/$id?"(resource:"user")
}

This maps the URI /user onto a UserController. Each HTTP method such as GET, PUT, POST, and DELETE map to unique actions within the controller. You can alter how HTTP methods are handled by using URL Mappings to map to HTTP methods, as shown in Listing 9-8.

Listing 9-8.  URL Mappings to Map to HTTP Methods

"/user/$id"(controller: "user") {
                        action = [GET: "show", PUT: "update", DELETE: "delete", POST: "save"]
}

As we discussed earlier, Grails provides automatic XML or JSON marshalling. However, unlike the resource argument used in Listing 9-7, Grails will not provide automatic XML or JSON marshalling in the case of Listing 9-8, unless you specify the parseRequest argument as shown in Listing 9-9.

Listing 9-9.  URL Mappings to Map to HTTP Methods with Auto Marshalling

"/product/$id"(controller: "product", parseRequest: true) {
                 action = [GET: "show", PUT: "update", DELETE: "delete", POST: "save"]
}

This technique also simplifies making the generic RestController in the next section, because using a common base URL can always be mapped to the RestController. So the URL to invoke a RESTful web service that returns an XML representation like that found in Listing 9-3 would look like this:

http://localhost:8080/collab-todo/rest/todo/1 

The URL for returning a JSON representation like that found in Listing 9-4 would look like this:

http://localhost:8080/collab-todo/json/todo/1 

You can implement this mapping by adding an additional URL mapping to UrlMappings.groovy. Listing 9-10 shows what the mapping looks like.

Listing 9-10.  Using rest Format Type

1. "/$rest/$controller/$id?"{
2.     controller = "rest"
3.     action = [GET:"show", PUT:"create", POST:"update", DELETE:"delete"]
4.     constraints {
5.         rest(inList:["rest","json"])
6.     }
7. }

Line 1 of Listing 9-10 shows the format of the URL. It includes a required $rest, which is the resulting format type, followed by the required $controller and an optional $id. Because $rest should only allow the two format types we are expecting, line 5 uses an inList constraint much like the constraints discussed in the GORM discussions of Chapter 6. Anything other than a “rest” or a “json” will cause an HTTP 404 (Not Found) error. Line 2 specifies that the RestController will handle any URL with this mapping. Finally, line 3 maps the HTTP methods to Grails conventional actions on the RestController.

Content Negotiation using the Accept Header

Every browser that conforms to the HTTP standards is required to send an Accept header. The Accept header contains information about the various MIME types the client is able to accept. Every incoming HTTP request has a special Accept header that defines what media types (or mime types) a client can “accept.” Listing 9-12 illustrates an example of a Firefox Accept header.

Listing 9-12.  Example of Accept Header

text/xml, application/xml, application/xhtml+xml, text/html;q=0.9,
text/plain;q=0.8, image/png, */*;q=0.5

Grails parses this incoming format and adds a property to the response object that outlines the preferred response format.

To deal with different kinds of requests from Controllers, you can use the withFormat method, which acts as kind of a switch statement, as shown in Listing 9-13.

Listing 9-13.  Using withFormat Method

import grails.converters.XML
class UserController {
               def list()  {
                       def users = User.list()
                              withFormat {
                                     html userList: users
                                     xml { render users as XML }
                       }
               }
        }

If the preferred format is html, Grails executes the html() call only. If the format is xml, the closure is invoked and an XML response is rendered. When using withFormat, make sure it is the last call in your controller action, as the return value of the withFormat method is used by the action to dictate what happens next. The request format is dictated by the CONTENT_TYPE header and is typically used to detect if the incoming request can be parsed into XML or JSON, while the response format uses the file extension, format parameter, or Accept header to attempt to deliver an appropriate response to the client. The withFormat available on controllers deals specifically with the response format. To add logic that deals with the request format, use a separate withFormat method on the request, as illustrated in Listing 9-14.

Listing 9-14.  Using withFormat with Request

request.withFormat {
                 xml {
                        // read XML
                }
                json {
                 // read JSON
                }
       }

Content Negotiation with the Format Request Parameter

Another mechanism of content negotiation is to use the format request parameter, which is used to override the format used in the request headers by specifying a format request parameter:

/user/list?format=xml

You can also define this parameter in the URL Mappings definition:

"/user/list"(controller:"user", action:"list") {
                format = "xml"
}

Content Negotiation with URI Extensions

Grails also supports content negotiation using URI extensions. For example, suppose you have the following URI:

/user/list.xml

In this case, Grails will remove the extension and map it to /user/list instead, while simultaneously setting the content format to xml based on this extension. This behavior is enabled by default; to turn it off, set the grails.mime.file.extensions property in grails-app/conf/Config.groovy to false:

grails.mime.file.extensions = false

Common Functionality

The common functionality of the RestController is implemented as an interceptor, as discussed in Chapter 5, along with two helper methods. Listing 9-15 contains a complete listing of the common functionality.

Listing 9-15.  RestController

import static org.apache.commons.lang.StringUtils.*
import org.codehaus.groovy.runtime.InvokerHelper
import org.codehaus.groovy.grails.commons.GrailsDomainClass
import Error

/**
 * Scaffolding like controller for exposing RESTful web services
 * for any domain object in both XML and JSON formats.
 */
class RestController {
  private GrailsDomainClass domainClass
  private String domainClassName

  // RESTful actions excluded

  def beforeInterceptor = {
    domainClassName = capitalize(params.domain)
    domainClass = grailsApplication.getArtefact("Domain", domainClassName)
  }

  private invoke(method, parameters) {
    InvokerHelper.invokeStaticMethod(domainClass.getClazz(), method, parameters)
  }

  private format(obj) {
    def restType = (params.rest == "rest")?"XML":"JSON"
    render obj."encodeAs$restType"()
  }
}

The beforeInterceptor found in Listing 9-15 is invoked before any of the action methods are called. It’s responsible for converting the $controller portion of the URL into a domain class name and a reference to a GrailsDomainClass, which are stored into private variables of the controller. You can use the domainClassName later for logging and error messages. The name is derived from using an interesting Groovy import technique. Since the controller in the URL is lowercased, you must uppercase it before doing the lookup. To do this, use the static Apache Commons Lang StringUtilscapitalize() method. Rather than specifying the utility class when the static method is called, an import in Groovy can also reference a class, making the syntax appear as if the static helper method is actually a local method. A reference to the actual domain class is necessary so the RestController can call dynamic GORM methods. Getting access to that domain class by name involves looking it up. However, because Grails domain classes are not in the standard classloader, you cannot use Class.forName(). Instead, controllers have an injected grailsApplication with a getArtefact() method, which you can use to look up a Grails artifact based on type. In this case, the type is domain. You can also use this technique to look up controllers, tag libraries, and so on.

In Listing 9-15, the helper methods are the invoke() method and format() method. The invoke() method uses the InvokerHelper helper class to simplify making calls to the static methods on the domain class. The methods on the domain class that are invoked by the RestController are all GORM-related. The format method uses the $rest portion of the URL to determine which Grails encodeAsXXX() methods it will call on the domain class. Grails includes encodeAsXML() and encodeAsJSON() methods on all domain objects.

There is one other class involved in the common functionality, and that is the Error domain class found in Listing 9-16.

Listing 9-16.   Error Domain Class

class Error {

  String message
}

Yes, the Groovy Error class in Listing 9-16 is a domain class found in the grails-app/domain directory. Making it a domain class causes Grails to attach the encoding methods, therefore enabling XML or JSON to be returned if an error occurs during the invocation of a RESTful web service.

RESTful show

The show action has double duty. It displays both a single domain model and a collection of domain models. Listing 9-17 exhibits the show action implementation.

Listing 9-17.  show Action

def show = {
  def result
  if(params.id) {
    result = invoke("get", params.id)
  } else {
    if(!params.max) params.max = 10
    result = invoke("list", params)
  }

  format(result)
}

In Listing 9-17, you should notice that the action uses params to determine if an ID was passed in the URL. If it was, the GORM get() method is called for that single domain model. If it wasn’t, the action calls the GORM list() method to return all of the domain objects. Also, notice that just like scaffolding, the action only returns a maximum of 10 domain objects by default. Using URL parameters, you can override that, just like you can with scaffolding. So adding ?max=20 to the end of the URL would return a maximum of 20 domain classes, but it does break the spirit of REST.

Listing 9-18 contains example code of a client application that calls the show action and returns a single domain model.

Listing 9-18.  RESTful GET Client (GetRestClient.groovy)

import groovy.util.XmlSlurper

def slurper = new XmlSlurper()

def url = " http://localhost:8080/collab-todo/rest/todo/1 "
def conn = new URL(url).openConnection()
conn.requestMethod = "GET"
conn.doOutput = true

if (conn.responseCode == conn.HTTP_OK) {
  def response

  conn.inputStream.withStream {
    response = slurper.parse(it)
  }

  def id = response.@id
  println "$id - $response.name"
}
conn.disconnect()

There are a couple of things to notice in Listing 9-18. First, the example uses the standard Java URL and URLConnection classes defined in the java.net package. This is true of all client applications through the rest of the chapter. You could also use other HTTP client frameworks, such as Apache HttpClient.¹ Second, notice that the request method of GET was used. Finally, the Groovy XmlSlurper class was used to parse the returned XML. This allows you to use the XPath notation to access things such as the name element and the id attribute of the result.

RESTful delete

Because DELETE is so similar to GET, both the action code and the client code are similar to that shown in the previous show action section. Listing 9-19 shows the delete action implementation.

Listing 9-19.  delete Action

def delete = {

  def result = invoke("get", params.id);

  if(result) {
    result.delete()
  } else {
    result = new Error(message: "${domainClassName} not found with id ${params.id}")
  }

  format(result)
}

In Listing 9-19, the GORM get() method is called on the domain class. If it is found, it is deleted. If it isn’t, it will return an error message. Listing 9-20 shows the client code that calls the delete RESTful web service.

Listing 9-20.  RESTful DELETE Client (DeleteRestClient.groovy)

def url = " http://localhost:8080/collab-todo/rest/todo/1 "
def conn = new URL(url).openConnection()
conn.requestMethod = "DELETE"
conn.doOutput = true

if (conn.responseCode == conn.HTTP_OK) {
  input = conn.inputStream
  input.eachLine {
    println it
  }
}
conn.disconnect()

The only differences between Listing 9-20 and Listing 9-18 are that the request method used in Listing 9-20 is DELETE, and instead of using the XmlSlurper, the contents of the result are just printed to the console, which is either an XML or JSON result of the deleted domain.

RESTful update

A POST is used to update the existing domain models in the RESTful paradigm. Listing 9-21 shows the implementation of the method that updates the domain models.

Listing 9-21.  update Action

def update = {
  def result
  def domain = invoke("get", params.id)
  if(domain) {
    domain.properties = params
    if(!domain.hasErrors() && domain.save()) {
      result = domain
    } else {
      result = new Error(message: "${domainClassName} could not be saved")
    }
  } else {
    result = new Error(message: "${domainClassName} not found with id ${params.id}")
  }
  format(result)
}

Like previous examples, Listing 9-21 invokes the GORM get() method to return the domain model to update. If a domain model is returned, all the parameters passed from the client are copied to the domain. Assuming there are no errors, the domain model is saved. Listing 9-22 shows a client that calls the POST.

Listing 9-22.  RESTful POST Client (PostRestClient.groovy)

def url = " http://localhost:8080/collab-todo/rest/todo "
def conn = new URL(url).openConnection()
conn.requestMethod = "POST"

conn.doOutput = true
conn.doInput = true

def data = "id=1&note=" + new Date()

conn.outputStream.withWriter { out ->
  out.write(data)
  out.flush()
}

if (conn.responseCode == conn.HTTP_OK) {
  input = conn.inputStream
  input.eachline {
    println it
  }
}
conn.disconnect()

Notice that Listing 9-22 uses a POST method this time. Also, pay attention to the fact that the data is passed to the service as name/value pairs separated by &s. At a minimum, you must use the id parameter so the service knows on which domain model to operate. You can also append other names to reflect changes to the domain. Because this is a POST, the container automatically parses the name/value pairs and puts them into params. The result will either be an XML or a JSON representation of the updated domain.

RESTful create

Finally, the most complicated of the RESTful services: the create service. Listing 9-23 shows the implementation.

Listing 9-23.  create Action

def create = {
  def result
  def domain = InvokerHelper.invokeConstructorOf(domainClass.getClazz(), null)

  def input = ""
  request.inputStream.eachLine {
    input += it
  }


  // convert input to name/value pairs
  if(input  && input != '') {
    input.tokenize('&').each {
      def nvp = it.tokenize('='),
      params.put(nvp[0],nvp[1]);
    }
  }
  domain.properties = params

  if(!domain.hasErrors() && domain.save()) {
    result = domain
  } else {
    result = new Error(message: "${domainClassName} could not be created")
  }

  format(result)
}

Listing 9-23 begins by using InvokerHelper to call a constructor on the domain class. Unlike POST, PUT’s input stream of name/value pairs is not automatically added to the params. You must do this programmatically. In this case, two tokenizers are used to parse the input stream. After that, the rest of the implementation follows the update example found in Listing 9-21. Listing 9-24 demonstrates a client application that does a PUT.

Listing 9-24.  RESTful PUT Client (PutRestClient.groovy)

def url = " http://localhost:8080/collab-todo/rest/todo "
def conn = new URL(url).openConnection()
conn.requestMethod = "PUT"

conn.doOutput = true
conn.doInput = true

def data = "name=fred&note=cool&owner.id=1&priority=1&status=1&"+
"createDate=struct&createDate_hour=00&createDate_month=12&" +
"createDate_minute=15&createDate_year=2012&createDate_day=11"

conn.outputStream.withWriter { out ->
  out.write(data)
  out.flush()
}
if (conn.responseCode == conn.HTTP_OK) {
  input = conn.inputStream
  input.eachLine {
    println it
  }
}
conn.disconnect()

Listing 9-24 is nearly identical to Listing 9-22, except that the PUT request method and a more complicated set of data are passed to the service. In this example, the data includes the created date being passed. Notice that each element of the date/time must be passed as a separate parameter. In addition, the createDate parameter itself must have a value of struct. The result is either an XML or JSON representation of the created domain object.