Domain Specific Languages are typically small, simple languages with a highly expressive syntax and grammar. In computing, DSLs are used to provide domain experts (who may or may not have prior programming experience) with programming capabilities limited to their specific area of expertise.

There are two types of DSLs: external and internal. External DSLs allow you to define a new language using any grammar or syntax you wish. External DSLs must then be parsed and executed by the programming language of your choice. Internal DSLs also define a new language, but are limited to the constructs made available by the implementing language. Because of their dynamic features, languages like Groovy and Ruby make writing internal DSLs relatively easy.

A Stock Trading DSL

A few weeks ago I wrote about trading stocks using Google's Finance API. Sticking with that theme, I thought it would be cool to write a Domain Specific Language that could also be used to mimic stock trading activities.

I'm guessing that most Wall Street traders don't know much about programming, but I'm sure most traders could decipher the actions that would take place after executing the following code:

buy 500, "AAPL", 179.30
buy(250, "AAPL", 179.30) //parenthesis are optional
buy 500, "SUNW", 10.14
sell 350, "AAPL", 179.30

show_transactions "AAPL"

print_portfolio_value

The code above is actual Groovy code. It tells the application to buy 750 shares of Apple stock at $179.30 in two separate transactions, buy 500 shares of Sun Microsystems stock at $10.14, and then sell 350 shares of Apple stock at $179.30. After all the transactions take place the code shows the transaction history for the Apple trades and then prints the total value of the portfolio.

The Groovy code to drive the functionality behind this simple DSL looks like this:

portfolio = [:] //Holds all of the stock transactions

/**
 *A simple object to hold the data for each individual transaction
 */
class StockTransaction {
    def tickerSymbol
    def numberOfShares
    def sharePrice
    def type
    def transactionDate
}

def buy(numberOfShares, symbol, sharePrice){
    transaction('Buy', numberOfShares, symbol, sharePrice)
}

def sell(numberOfShares, symbol, sharePrice){
    transaction('Sell', numberOfShares, symbol, sharePrice)
}

def transaction(transactionType, numberOfShares, symbol, sharePrice){
    def transaction = new StockTransaction(tickerSymbol:symbol,
        numberOfShares:numberOfShares, sharePrice:sharePrice,
        type:transactionType, transactionDate:new Date())

    println "${transaction.type}ing ${transaction.numberOfShares} shares" +
        " of ${transaction.tickerSymbol} at ${transaction.sharePrice}"

    //If no transactions exist for a particular stock, check to see that the
    //transaction type is a 'Buy' and if so create a new list to hold
    //transactions for a particular stock.
    if(portfolio[transaction.tickerSymbol] == null){
        if(transactionType == 'Buy')
            portfolio[transaction.tickerSymbol] = [transaction]
        else
            println "You can't sell a stock you don't own."
    } else{
        portfolio[transaction.tickerSymbol] << transaction
    }
}

def show_transactions(tickerSymbol){
    portfolio[tickerSymbol].each { transaction ->
        println "${transaction.transactionDate}: ${transaction.type} " +
          "${transaction.numberOfShares} shares of ${tickerSymbol} at " +
          "${transaction.sharePrice}"
    }
}

def getPrint_portfolio_value(){
    def totalValue = 0

    //Add all of the 'Buy' transactions and subtract all of the 'Sell'
    //transactions from the total portfolio value.
    portfolio.each { tickerSymbol, transactionList ->
        transactionList.each { transaction ->
            if(transaction.type == 'Buy')
                totalValue +=
                    (transaction.numberOfShares * transaction.sharePrice)
            else
                totalValue -=
                    (transaction.numberOfShares * transaction.sharePrice)
        }
    }

    println "Your Total Portfolio Value is: ${totalValue}"
}

The only thing the code really does is define methods for the different types of stock trading activities. I use a HashMap called portfolio to hold each of the individual stock transaction's attributes stored in a simple StockTransaction object. Each time a buy or sell action takes place the portfolio HashMap is updated with the corresponding StockTransaction object.

The readability of the DSL code is greatly improved because Groovy allows for optional parenthesis on methods that take one or more parameters. Notice that the second call to purchase Apple stock uses the parenthesis to illustrate this point. It is important to keep things as simple as possible when creating a DSL. Programmers should try to avoid bogging the domain expert down by forcing him or her to use unnecessary constructs of a language such as parenthesis.

If you look closely at the code that defines the DSL you will notice that in order to make the parenthesis optional for calls to the print_portfolio_value method I had to get a little hacky and define the method as: getPrint_portfolio_value(). This is because Groovy thinks that print_portfolio_value is a call to a property. By adding the "get" in front of the method call, we can "trick" Groovy into calling the method as desired.

After executing the DSL code the output is as follows:

Buying 500 shares of AAPL at 179.30
Buying 250 shares of AAPL at 179.30
Buying 500 shares of SUNW at 10.14
Selling 350 shares of AAPL at 179.30
Sun Aug 17 19:15:05 EDT 2008: Buy 500 shares of AAPL at 179.30
Sun Aug 17 19:15:05 EDT 2008: Buy 250 shares of AAPL at 179.30
Sun Aug 17 19:15:05 EDT 2008: Sell 350 shares of AAPL at 179.30
Your Total Portfolio Value is: 76790.00

Fluency

In the context of trading stocks, the DSL we created above is pretty straightforward, but it does suffer a bit from a problem with fluency. It might be nice if we could make the DSL a bit more readable. For example, what if the DSL was changed to read like this:

buy 500.shares.of("AAPL").at(179.30)
buy 250.shares.of("AAPL").at(179.30)
buy 500.shares.of("SUNW").at(10.14)
sell 350.shares.of("AAPL").at(179.30)

show_transactions "AAPL"

print_portfolio_value

Using categories it is possible to allow for a fluent DSL like the one above. Take a look at the code behind this DSL:

/**
 * The class used for the category
 */
class StockHelper {
    static portfolio = [:]

    static buy(self, stockTransaction) {
        stockTransaction.type = 'Buy'
        transaction(stockTransaction)
    }

    static sell(self, stockTransaction) {
        stockTransaction.type = 'Sell'
        transaction(stockTransaction)
    }

    static transaction(stockTransaction){
        println "${stockTransaction.type}ing " +
        "${stockTransaction.numberOfShares}" +
        " shares of ${stockTransaction.tickerSymbol} at " +
        "${stockTransaction.sharePrice}"

        if(portfolio[stockTransaction.tickerSymbol] == null){
            if(stockTransaction.type == 'Buy')
                portfolio[stockTransaction.tickerSymbol] = [stockTransaction]
            else
                println "You can't sell a stock you don't own."
        } else{
            portfolio[stockTransaction.tickerSymbol] << stockTransaction
        }
    }

    static getShares(self) {
        def startTransaction = new StockTransaction(numberOfShares:self,
            transactionDate:new Date())
        return startTransaction
    }

    static of(self, tickerSymbol) {
        self.tickerSymbol = tickerSymbol
        return self
    }
    static at(self, sharePrice) {
        self.sharePrice = sharePrice
        return self
    }

    static show_transactions(self, tickerSymbol){
        portfolio[tickerSymbol].each { transaction ->
            println "${transaction.transactionDate}: ${transaction.type} " +
              "${transaction.numberOfShares} shares of ${tickerSymbol} at " +
              "${transaction.sharePrice}"
        }
    }

    static getPrint_portfolio_value(self){
        def totalValue = 0

        portfolio.each { tickerSymbol, transactionList ->

            transactionList.each { transaction ->
                if(transaction.type == 'Buy')
                    totalValue +=
                        (transaction.numberOfShares * transaction.sharePrice)
                else
                    totalValue -=
                        (transaction.numberOfShares * transaction.sharePrice)
            }
        }

        println "Your Total Portfolio Value is: ${totalValue}"
    }
}

By chaining methods calls together we can make our code very fluent. We build a StockTransaction object by calling 3 methods: getShares(), of(), and at(). Each of these calls is responsible for building a specific piece of the StockTransaction object and passing it along to the next call. The self keyword is used to reference the target instance (i.e. the StockTransaction object being created). After the StockTransaction is created, the buy or sell methods can be called to update the portfolio HashMap just as in the first example.

Even though parenthesis and the dot notation (for method access) must be used in order to execute this DSL code, I personally think this code is easier to read and understand as compared with the previous example.

Conclusion

The code in this blog entry is pretty brittle, but it illustrates how easily a DSL can be created using the Groovy programming language. In a real life scenario programmers must be diligent about the design and usage of the DSLs they create.

By creating an internal DSL domain experts with some programming knowledge will also be able to exploit other constructs found in the implementing language such as loops and conditional statements. For example, code could be written to do things such as:

if(currentStockPriceVariable < SOME_SHARE_PRICE_CONSTANT){
    buy 500.shares.of("AAPL").at(currentStockPriceVariable)
}

or perhaps something like this:

3.times {
    sell 500.shares.of("AAPL").at(179.30)
}

Over the past few years DSLs have gained popularity along with the rise of dynamic languages. For example, GANT is a popular DSL for the Groovy programming language that can be used to script Ant style builds. It will be interesting to see what other types of DSLs become available in the future. Be sure to look out for Martin Fowler's upcoming book on the subject.

Code

Click here to download the code examples from this post.

Disclaimer

I am in no way endorsing any of the companies mentioned in this blog entry and all company references are for example purposes only.

This particular blog entry makes use of Google's Finance Data API. I'll explain how it is possible to programmatically authenticate with Google, create a new stock portfolio, and create positions (buy and sell stocks) within this portfolio by making REST based service calls. I won't dive too deep into the details of the REST architecture, but if you have a general understanding of XML and the HTTP protocol it won't be too difficult to follow along. For more information on REST, please see the links in the Reference section below.

Authenticating with Google

In order to use Google's service we must first authenticate by POSTing a query string containing our username, password, service identifier, and source (application name) to the following URL: https://www.google.com/accounts/ClientLogin. This code snippet illustrates how a POST request can be made in Groovy:

static createAuthToken(String username, String password){
    def url = new URL("https://www.google.com/accounts/ClientLogin")
    def connection = url.openConnection()

    def queryString = "Email=${username}&Passwd=${password}" +
                      "&service=finance&source=company-groovyfinance-1.0"

    def returnMessage = processRequest(connection, queryString)

    if(returnMessage != "Error"){
        //the authentication token
        return returnMessage.split(/Auth=/)[1].trim()
    }
}

static String processRequest(connection, dataString){
    connection.setRequestMethod("POST")
    connection.doOutput = true
    Writer writer = new OutputStreamWriter(connection.outputStream)
    writer.write(dataString)
    writer.flush()
    writer.close()
    connection.connect()

    if (connection.responseCode == 200 || connection.responseCode == 201)
        return connection.content.text

    return "Error"
}

In the code above we create a connection to Google's authentication URL and POST the queryString by calling the reusable processRequest() method. Within processRequest() we set the connection's request method type to "POST", create a Writer, and write the data to the supplied connection.

If our credentials are valid, Google will respond to our request with a string of name value pairs similar to this:

SID=DQAAAIEAAAIgccs7qKgmwXGagt...lu6fg
LSID=DQAAAIIAAACsegj9oEm0Ob8pz...abyi5
Auth=DQAAAIMAAACgadj9oEm0Ob8pz...AGasG

The only piece of information we are interested in is the authorization token value that follows the "Auth" label. We will need to use this token in the rest of our requests in order to authenticate with Google.

Creating a Portfolio

When users log into Google Finance for the first time they will be presented by default with an empty portfolio called "My Portfolio". Note: a portfolio is simply a collection of assets (stocks, bonds, mutual funds, cash, etc.).

Let's pretend however that we do not wish to use the default portfolio, but instead want to create our own. To create a new portfolio we simply need to send a well formed Atom XML feed that contains the name of the new portfolio (and optionally a currency code) to this URL: http://finance.google.com/finance/feeds/default/portfolios

static createPortfolio(String authorizationToken, String portfolioName){
    def url =
    	 new URL("http://finance.google.com/finance/feeds/default/portfolios")

    def connection = url.openConnection()
    connection.setRequestProperty("Content-Type", "application/atom+xml")
    connection.setRequestProperty("Authorization",
                                  "GoogleLogin auth=${authorizationToken}")

    def atomString = """<?xml version='1.0'?>
    <entry xmlns='http://www.w3.org/2005/Atom'
    	   xmlns:gf='http://schemas.google.com/finance/2007'
           xmlns:gd='http://schemas.google.com/g/2005'>
        <title type='text'>${portfolioName}</title>
        <gf:portfolioData currencyCode='USD'/>
    </entry>"""

    def returnMessage = processRequest(connection, atomString)

    //Get the id of the newly created portfolio
    if(returnMessage != "Error"){
    	def entry = new XmlSlurper().parseText(returnMessage)
    	def entryId = "${entry.id}"

    	return entryId[entryId.lastIndexOf('/')+1..-1]
    }
}

Once again we create a connection, but this time we also need to set two request header parameters: Content-Type and Authorization. We set these parameters to "application/atom+xml" and "GoogleLogin auth=${authorizationToken}" respectively. Note that the authorizationToken variable stores the authentication token that was returned by the createAuthToken() method.

After the connection is created we again call the processRequest() method that was discussed in the Authenticating with Google section above. If all goes well, Google will create the new portfolio and return an Atom representation of that new portfolio to the client. If we are logged into our web based Google Finance account we can refresh the screen and will notice our newly created portfolio.

Two code features really shine through in the example above: Groovy's Triple Quotes and Groovy's XmlSlurper. The triple quotes surrounding the Atom XML allow us to easily write multi-line XML strings without having to worry about escaping special characters. The XmlSluper meanwhile allows us to easily parse and locate a specific attribute (the portfolio id in this case) within the returned XML string. Imagine how many lines of Java code it would take to recreate this functionality.

Placing an Order

So far our portfolio is pretty boring. Let's create some stock transactions to add some assets into our portfolio.

static createStockTransaction(authorizationToken, tickerSymbol, numberOfShares,
                              transactionType, portfolioId){

    StringBuffer transactionURL = new StringBuffer()
    transactionURL.append("http://finance.google.com/finance/feeds/")
        .append("default/portfolios/${portfolioId}/positions/")
        .append("${URLEncoder.encode(tickerSymbol)}/transactions")

    def url = new URL(transactionURL.toString())
    def connection = url.openConnection()

    connection.setRequestProperty("Content-Type", "application/atom+xml")
    connection.setRequestProperty("Authorization",
                                  "GoogleLogin auth=${authorizationToken}")

    String timeFormat = "yyyy-MM-dd'T'HH:mm:ss.S"
    SimpleDateFormat dateFormatter = new SimpleDateFormat(timeFormat)
    String transactionDate = dateFormatter.format(new Date())

    def atomString = """<?xml version='1.0'?>
    <entry xmlns='http://www.w3.org/2005/Atom'
    	xmlns:gf='http://schemas.google.com/finance/2007'
    	xmlns:gd='http://schemas.google.com/g/2005'>
    	  <gf:transactionData date='${transactionDate}'
    	      shares='${numberOfShares}' type='${transactionType}' />
    </entry>"""

    processRequest(connection, atomString)
}

The concept with this code is basically the same as the portfolio creation example above. We create a connection with the correct Content-Type and Authorization headers, define some Atom XML with attributes about the transaction we would like to make, and then POST the XML to a specific URL. The interesting thing to note about this code is that unlike the other two examples, the URL for creating transactions is not static. Instead, this URL needs to be parameterized with the portfolio id and ticker symbol of the stock you wish to trade: http://finance.google.com/finance/feeds/default/portfolios/<portfolio id>/ positions/<ticker symbol>/transactions.

Method calls to createStockTransaction() might look something like this:

createStockTransaction(authorizationToken, "NASDAQ:JAVA", 10000.00, "Buy", pId)
sleep(2000)
createStockTransaction(authorizationToken, "NYSE:F", 10000.00, "Buy", pId)

This would place an order for 10,000 shares of Sun Microsystems and Ford Motor Company stock. Notice that the ticker symbol must be preceded by the name of the market on which it trades. Therefore the ticker symbol we sent to Google to purchase Sun stock is: NASDAQ:JAVA because Sun trades on the NASDAQ stock exchange. Stocks that trade on the New York Stock Exchange would be preceded by the acronym: NYSE (i.e. Ford = NYSE:F). Also notice that it is a good idea to "sleep" between service calls because sending too many requests to Google at once will result in errors.

When we refresh our Google Finance page we will notice these shares placed into our portfolio.

Conclusion

This blog post only skims the surface of what is possible using Google's Finance Data API. The API also allows for RESTful calls to GET, UPDATE and DELETE specific portfolio and transaction feeds. Overall, I've been incredibly impressed by all of the data and functionality made available through Google's Data APIs.

The code provided in this example should give you a solid foundation to start playing around with Google's Finance API, but it is far from bulletproof. For example, I don't really do much in the way of error handling or input validation. So you shouldn't be surprised if things bomb out if you try to sell shares of a stock that you don't own or create a portfolio with the same name as one of your existing portfolios.

The examples I've shown here are very low level because I wanted to learn the basics of REST. A much easier way to implement the same functionality would be to use Google's Data APIs Client Libraries (which by the way work perfectly well with Groovy).

References

Disclaimer

I am in no way endorsing any of the companies mentioned in this blog entry and all company references are for example purposes only.

To the average Java programmer (myself included), the idea of generating methods on the fly might seem bizarre at first, but Groovy's built in method interception capabilities allow programmers to easily realize this type of functionality in their Groovy code. In Groovy Metaprogramming - Adding Behavior Dynamically, I discussed how to add a method to the java.math.BigDecimal class to allow for the conversion of U.S. Dollars (USD) into Euros (EUR). What if, however, I wanted to convert from USD to British Pounds (GBP) or to Japanese Yen (JPY)? I could certainly write a method for each of these conversions, but what if there was a better, cleaner, and more flexible way to build in this functionality?

Groovy's methodMissing()

The magic behind Groovy's ability to create methods on the fly comes from the language's built in facilities for intercepting method calls. In particular, one practice for intercepting calls in Groovy is to implement the methodMissing() method on your Groovy classes. Before Groovy throws a MissingMethodException for calls that are made to methods not defined within a class, Groovy first routes the calls through an object's methodMissing() method. This gives programmers a chance to intercept calls to these non-existing methods and define an implementation for them:

import java.text.NumberFormat

def exchangeRates = ['GBP':0.501882, 'EUR':0.630159,
                     'CAD':1.0127, 'JPY':105.87] // (7/2/2008)

BigDecimal.metaClass.methodMissing = { String methodName, args ->
    conversionType = methodName[2..-1]
    conversionRate = exchangeRates[conversionType]

    if(conversionRate){
        NumberFormat nf = NumberFormat.getCurrencyInstance(Locale.US)
        nf.setCurrency(Currency.getInstance(conversionType))

        return nf.format(delegate * conversionRate)
    }

    "No conversion for USD to ${conversionType}"
}

println 2500.00.inGBP()
println 2500.00.inJPY()
println 2500.00.inXYZ()

Notice that in the example above we make calls to the methods: inGBP(), inJPY(), and inXYZ() on the BigDecimal object 2500.00. Also notice however, that we did not actually define any of these methods on the BigDecimal class. Instead we override BigDecimal's methodMissing() method which allows us to intercept calls to these methods (inGBP(), inJPY(), etc.) and create an implementation for them.

Within the methodMissing() method we parse the name of the called method and look up the corresponding conversion rate from the exchangeRate HashMap which stores conversion rate values for various countries. In the future it might be nice if this code called a remote service to actually lookup the exchange rates, but for these examples I'll just keep it simple. If no corresponding conversion rate is found then a message is returned stating that there is "No conversion for USD to <the conversion type specified>" (XYZ in our case).

GBP1,254.70
JPY264,675.00
No conversion for USD to XYZ

Method Caching

One way to improve the performance of the previous example is to cache the implementation of the method calls that we have intercepted. This will allow future calls to these methods to be invoked directly and prevent them from having to be routed through the BigDecimal class's methodMissing() method:

import java.text.NumberFormat

def exchangeRates = ['GBP':0.501882, 'EUR':0.630159,
                     'CAD':1.0127, 'JPY':105.87] // (7/2/2008)

BigDecimal.metaClass.methodMissing = { String methodName, args ->
    println "method missing called"

    def cachedMethod = { Object[] cmArgs ->
        conversionType = methodName[2..-1]
        conversionRate = exchangeRates[conversionType]

        if(conversionRate){
            NumberFormat nf = NumberFormat.getCurrencyInstance(Locale.US)
            nf.setCurrency(Currency.getInstance(conversionType))

            return nf.format(delegate * conversionRate)
        }

        "No conversion for USD to ${conversionType}"
    }

    BigDecimal.metaClass."${methodName}" = cachedMethod

    return cachedMethod(args)
}

println 2500.00.inJPY()
println 2500.00.inGBP()
println 2500.00.inGBP()

In the example above notice that the functionality for the called method is implemented and stored within a closure called cachedMethod. By storing the functionality within a closure we can then assign it to BigDecimal's metaClass so that subsequent method calls are invoked directly.

In the result we can see that the second call to inGBP() does not get routed through BigDecimal's methodMissing():

method missing called
JPY264,675.00
method missing called
GBP1,254.70
GBP1,254.70

Conclusion

It's not too hard to think of ways that the given code samples could be improved. Imagine that instead of assuming all BigDecimal objects were defined in USD, that they could represent any currency type and that our future method calls could actually look something like this:

2500.00.fromEURtoCAD()

The examples given in this blog entry are trivial, but they showcase the power and flexibility that can be gained by using Groovy's metaprogramming capabilities. These metaprogramming techniques give programmers a powerful tool that can be used within their code, but with this power programmers need to show a great deal of caution. Imagine if the following method was called on the BigDecimal object in our examples above:

2500.00.someRandomMethod()

I'm guessing the result would not be desirable. Programmers should always be sure to code defensively and write unit tests when using Groovy's powerful metaprogramming capabilities.

Metaprogramming is the ability of a computer language to manipulate other programs (including itself) to add or create functionality in a dynamic fashion. In Groovy, metaprogramming is especially useful because among other things it gives programmers the ability to easily implement domain specific languages, create builders, or generate mock objects for unit testing. Adding functionality to pre-existing Java or Groovy code can be accomplished by using either the ExpandoMetaClass or Categories.

Note: the best way to test the code examples from this blog entry yourself is to simply copy and paste them into a text file saved with a .groovy extension and then run them from the command line. Running these examples in the GroovyConsole may yield unpredictable results.

The ExpandoMetaClass

The ExpandoMetaClass can be used to dynamically add methods, properties, and constructors to Groovy or Java objects. These tasks can be accomplished by simply assigning a closure to an object's MetaClass. For instance, let's pretend that we want to add a method to java.math.BigDecimal that will convert a BigDecimal (in U.S. Dollars) to its equivalent value in Euros.

import java.text.NumberFormat

BigDecimal.metaClass.inEuros = {
    def EXCHANGE_RATE = 0.634961 // (6/27/2008)
    NumberFormat nf = NumberFormat.getCurrencyInstance(Locale.US)
    nf.setCurrency(Currency.getInstance("EUR"))
    nf.format(delegate * EXCHANGE_RATE)
}

println 2500.00.inEuros()
	

To access BigDecimal's MetaClass we simply use the following syntax BigDecimal.metaClass.inEuros and assign it a closure. Within the closure we set an exchange rate, create a NumberFormat instance, set the currency type to "EUR" (Euros), and multiply the delegate (the BigDecimal we specified) by the exchange rate. Groovy automatically returns the last line of a closure so our call to println 2500.00.inEuros() will yield the following result:

EUR1,587.40

It is also possible to make the code a bit more readable by dropping the parenthesis after the call to inEuros(). This can be accomplished by setting up inEuros as a property on the BigDecimal class instead of as a method:

import java.text.NumberFormat

BigDecimal.metaClass.getInEuros = {->
    def EXCHANGE_RATE = 0.634961 //June 27, 2008
    NumberFormat nf = NumberFormat.getCurrencyInstance(Locale.US)
    nf.setCurrency(Currency.getInstance("EUR"))
    nf.format(delegate * EXCHANGE_RATE)
}

println 2500.00.inEuros
	

Notice that instead of writing inEuros we create a property on the MetaClass by writing getInEuros. This allows us to drop the parenthesis from println 2500.00.inEuros and yields the same result as the method injection technique described above:

EUR1,587.40

For detailed information on the ExpandoMetaClass and all of its uses, be sure to check out the Groovy User Guide.

Categories

Methods, properties, and constructors that are injected into a class via the ExpandoMetaClass are available anywhere within your application. This is a convenient feature if you plan on using the method multiple times but could cause confusion if you only want the changes to take place in isolation. This is where Categories come into play. Categories allow you to inject functionality into a class, but these changes only take affect while calling the method from within the built in use() method's code block.

In order to take advantage of the use() method you must provide it with a "Category". A Category is simply a class with static methods that you wish to inject into your class. Again, the scope of the added functionality is limited to the use() method's calling block. If we take the exchange rate example from above and modify it to be used as a Category the code will be as follows:

import java.text.NumberFormat

class ExchangeRateUtil  {
    def static inEuros(self) {
        def EXCHANGE_RATE = 0.634961 //June 27, 2008
        NumberFormat nf = NumberFormat.getCurrencyInstance(Locale.US)
        nf.setCurrency(Currency.getInstance("EUR"))
        nf.format(self * EXCHANGE_RATE)
    }
}

use(ExchangeRateUtil){
    println 2500.00.inEuros()
}

println 10000.00.inEuros() //throws MissingMethodException
	

I've created a new class called ExchangeRateUtil and created a static method called inEuros() within this class. Notice that method takes a parameter called self which is used to represent the BigDecimal that we specified. The remainder of the code for the conversion is exactly the same.

To use this category we call the use() method and within its block call the inEuros() method the same way we did in the example above. The output will be the same for the call that is made within the use() calling block, but when we try to call the inEuros() method outside of the use() block a MissingMethodException is thrown.

EUR1,587.40
Caught: groovy.lang.MissingMethodException: ...

Conclusion

As you can see, using metaprogramming gives static language programmers a whole new set of tools that can be used to creatively and elegantly arrive at solutions that can otherwise be overly complex in static languages. In my next blog entry, I'll expand upon this current discussion and explain how we can use metaprogramming to not only add functionality to a class, but to actually create it on the fly with no previous knowledge of the methods that will be called on our class.

Any Groovy object that implements this interface will automatically have all of its method calls routed through its invokeMethod() (assuming of course that this method has been implemented on the Groovy object itself or on its MetaClass).

A Simple Example

Let's take a look at a quick example. Assume that for whatever reason we want to know the time before and after each call to a method in a class called SimplePOGO. To accomplish this task in Groovy, we simply implement the GroovyInterceptable interface and the invokeMethod() like this:

class SimplePOGO implements GroovyInterceptable {
    void simpleMethod1(){
        System.out.println("simpleMethod1() called")
    }

    void simpleMethod2(String param1, Integer param2){
        System.out.println("simpleMethod2(${param1},${param2}) called")
        System.out.println("sleeping...")
        Timer.sleep(2000)
    }

    def invokeMethod(String name, args){
        System.out.println("time before ${name} called: ${new Date()}")

        //Get the method that was originally called.
        def calledMethod = SimplePOGO.metaClass.getMetaMethod(name, args)

        //The "?" operator first checks to see that the "calledMethod" is not
	//null (i.e. it exists).
        calledMethod?.invoke(this, args)

        System.out.println("time after ${name} called: ${new Date()}\n")
    }
}

simplePogo = new SimplePOGO()
simplePogo.simpleMethod1()
simplePogo.simpleMethod2("stringParam", 24)
	

This code will produce the following output:

time before simpleMethod1 called: Wed Jun 18 12:07:06 EDT 2008
simpleMethod1() called
time after simpleMethod1 called: Wed Jun 18 12:07:06 EDT 2008

time before simpleMethod2 called: Wed Jun 18 12:07:06 EDT 2008
simpleMethod2(stringParam,24) called
sleeping...

time after simpleMethod2 called: Wed Jun 18 12:07:08 EDT 2008

Because SimplePOGO implements GroovyInterceptable all calls to its methods will first be routed through its invokeMethod(). Within the invokeMethod() we print the current time, look up the actual method that was called, call that method, and then print out the current time after execution.

An Example with Nested Methods

What happens if we nest methods? Take a look at this example:

class SimplePOGO implements GroovyInterceptable {

    void simpleMethod1(){
        System.out.println("simpleMethod1() called")
        simpleMethod2Nested("stringParam", 24)
    }

    void simpleMethod2Nested(String param1, Integer param2){
        System.out.println("simpleMethod2Nested(${param1},${param2}) called")
        System.out.println("\nsleeping...\n")
        Timer.sleep(2000)
    }

    def invokeMethod(String name, args){
        System.out.println("time before ${name} called: ${new Date()}")

        //Get the method that was originally called.
        def calledMethod = SimplePOGO.metaClass.getMetaMethod(name, args)

        //The "?" operator first checks to see that the "calledMethod" is not
	//null (i.e. it exists).
        calledMethod?.invoke(this, args)

        System.out.println("time after ${name} called: ${new Date()}")
    }
}

simplePogo = new SimplePOGO()
simplePogo.simpleMethod1()
	

This code will produce the following output:

time before simpleMethod1 called: Wed Jun 18 12:07:35 EDT 2008
simpleMethod1() called
time before simpleMethod2Nested called: Wed Jun 18 12:07:35 EDT 2008
simpleMethod2Nested(stringParam,24) called

sleeping...

time after simpleMethod2Nested called: Wed Jun 18 12:07:37 EDT 2008
time after simpleMethod1 called: Wed Jun 18 12:07:37 EDT 2008

Not too surprising. When simpleMethod1() is called, the invokeMethod() in SimplePOGO is called which prints the current time stamp and then executes the simpleMethod1(). Notice however that simpleMethod1() calls simpleMethod2Nested(). When this call is made invokeMethod() will again be called so that the "before" time stamp will be printed out again. When simpleMethod2Nested() finishes executing an "after" time stamp is printed to the screen and control returns to simpleMethod1() which also finishes executing and prints the current time to the screen.

Gotcha?

You may have noticed that I used System.out.println() instead of the Groovier println() to print the output to the screen. This is because println() is a method that is built into the GroovyObject which is extended by all other Groovy objects (including SimplePOGO). If a call to println() is made within one of SimplePOGO's methods then the invokeMethod() on SimplePOGO will be called again which may lead to output that is not quite expected:

class SimplePOGO implements GroovyInterceptable {

    void simpleMethod1(){
        println "simpleMethod1() called"
    }

    void simpleMethod2(String param1, Integer param2){
        println "simpleMethod2(${param1},${param2}) called"
        println "sleeping..."
        Timer.sleep(2000)
    }

    def invokeMethod(String name, args){
        System.out.println("time before ${name} called: ${new Date()}")

        //Get the method that was originally called.
        def calledMethod = SimplePOGO.metaClass.getMetaMethod(name, args)

        //The "?" operator first checks to see that the "calledMethod" is not
	//null (i.e. it exists).
        calledMethod?.invoke(this, args)

        System.out.println("time after ${name} called: ${new Date()}")
    }
}

simplePogo = new SimplePOGO()
simplePogo.simpleMethod1()
simplePogo.simpleMethod2("stringParam", 24)
	

This code will produce the following output:

time before simpleMethod1 called: Wed Jun 18 12:13:32 EDT 2008
time before println called: Wed Jun 18 12:13:32 EDT 2008
simpleMethod1() called
time after println called: Wed Jun 18 12:13:32 EDT 2008
time after simpleMethod1 called: Wed Jun 18 12:13:32 EDT 2008
time before simpleMethod2 called: Wed Jun 18 12:13:32 EDT 2008
time before println called: Wed Jun 18 12:13:32 EDT 2008
simpleMethod2(stringParam,24) called
time after println called: Wed Jun 18 12:13:32 EDT 2008
time before println called: Wed Jun 18 12:13:32 EDT 2008
sleeping...
time after println called: Wed Jun 18 12:13:32 EDT 2008
time after simpleMethod2 called: Wed Jun 18 12:13:34 EDT 2008

Worse still is if you try to place the println() method inside of the invokeMethod() itself. This will lead to recursive calls and an eventual StackOverflowError:

class SimplePOGO implements GroovyInterceptable {

    void simpleMethod1(){
        System.out.println("simpleMethod1() called")
    }

    def invokeMethod(String name, args){
    	try {
	    println("time before ${name} called: ${new Date()}")

	    //Get the method that was originally called.
	    def calledMethod = SimplePOGO.metaClass.getMetaMethod(name, args)

	    //The "?" operator first checks to see that the "calledMethod" is
            //not null (i.e. it exists).
	    calledMethod?.invoke(this, args)

	    println("time after ${name} called: ${new Date()}\n")
	} catch (StackOverflowError soe) {
	    System.out.println("A StackOverflowError was caught")
	    System.exit(0)
	}
    }
}

simplePogo = new SimplePOGO()
simplePogo.simpleMethod1()
	

This code will produce the following output:

A StackOverflowError was caught

Conclusion

The examples listed above are very simple, but they illustrate how easy it is to implement the powerful features of AOP in Groovy. It's not too difficult to envision how such a capability could be built into an application to handle a lot of the boiler plate code that tends to crowd non AOP applications.