Why the complexity, you ask? My team often found the simple examples understandable, but they struggled to see the application of the monads to day-to-day business code. “Sure, we write monads that read a String from a file, chain it to monad that converts the String to Int, but we’re having to generate reports,” they said.

The service

Let’s write a ReportService that generates reports and then produces a combined report by combining the individual reports into one. Its API is:

class ReportService {

  def produce()

  def combine()

}

Where the produce function generates the individual reports (pages, if you like); and the combine function takes the already generated reports and assembles the aggregate. We keep these reports in the database (and the content on the disk) and we map the RDBMS records to the Record instances. We are using Hibernate, leading the definition of the Report class:

@Entity
case class Report() {
  @Id
  @GeneratedValue
  @BeanProperty
  var id: Long = _
  @Version
  @BeanProperty
  var version: Int = _
  @BeanProperty
  var fileName: String = _

}

As I said earlier, we are using Hibernate to manipulate the Record instances, so our ReportService will need to depend on the SessionFactory. Because we’re running in the Spring Framework, we can have the dependency injected in. We just have to give the appropriate metadata to the Spring Framework’s DI core:

@Service
class ReportService @Autowired() (private val sessionFactory: SessionFactory) {

  def produce()

  def combine()

}

We’ll start with the produce() function. The task is to generate [a fixed number of] reports. So, we’ll need a for loop whose every iteration creates a Report instance and saves it to the DB.

@Service
class ReportService @Autowired() (private val sessionFactory: SessionFactory) {

  @Transactional
  def produce() {
    for (i < - 0 to 100) {
      val report = Report()
      val content = "Report %d".format(i)
      report.fileName = "%d".format(i)

      // save the report's content

      sessionFactory.getCurrentSession.saveOrUpdate(report)
    }
  }

}

So far, so good. We have the fancy Scala for loop, but the code remains very similar to its Java equivalent. Now, let's deal with the IO. To save a report, we need to:

• create / open a file into which the content is going to go,
• produce the report's content,
• write the content to the file.

So, we have three operations. We go from Report to operation giving File, second that goes from operation giving File and operation giving Data to operation giving Unit. So, let's write these operations and define what we mean by Data:

@Service
class ReportService @Autowired() (private val sessionFactory: SessionFactory) {
  type Data = Array[Char]
  import scalaz._
  import scalaz.effects._

  def reportToFile(report: Report) = io {
    new File("/Users/janmachacek/Tmp/r/%s".format(report.fileName))
  }
  def dataToFile(data: IO[Data])(file: File) = io {
    println("Written " + new String(data.unsafePerformIO) + " to " + file)
  }

  ...

}

The function reportToFile is the one that takes a Report and returns an operation that gives File. The operation that gives is whatever the io function returns. Then I have the dataToFile function that takes an operation that takes operation that gives Data and returns an operation that gives Unit. Figure 1 shows a picture of what we're trying to do.

Figure 1. The operations and the links between them



We would like to wire the three operations together to give us a new operation that combines the three together!

This is crucial concept: we're not just pushing data around, we're creating a new operation that combines the smaller operations to do something useful for us. So, let's drop in the real syntax:

@Service
class ReportService @Autowired() (private val sessionFactory: SessionFactory) {
  type Data = Array[Char]
  import scalaz._
  import scalaz.effects._

  def reportToFile(report: Report) = io {
    new File("/Users/janmachacek/Tmp/r/%s".format(report.fileName))
  }
  def dataToFile(data: IO[Data])(file: File) = io {
    println("Written " + new String(data.unsafePerformIO) + " to " + file)
  }

  @Transactional
  def produce() {
    for (i <- 0 to 100) {
      val report = Report()
      val content = "Report %d".format(i)
      report.fileName = "%d".format(i)

      (reportToFile(report) >>=
         dataToFile(io {content.toCharArray})).unsafePerformIO

      sessionFactory.getCurrentSession.saveOrUpdate(report)
    }
  }

}

Let's explore the mystical (reportToFile(report) >>= dataToFile(io {content.toCharArray})).unsafePerformIO line. We have reportToFile takes a Report and makes a thing that makes a File. Then we have dataToFile which takes a thing that makes Data and thing that makes File. We treat these things as black boxes--they do something obscure, unknown and unknowable. But these things have a "screen" on them; and we can look at that "screen" and obtain the current value.

And that's the principle of monads. They are opaque things that can return some value and they can be chained together to form new things that combine whatever the component things do.

And that explains the unsafePerformIO call. The (reportToFile(report) >>= dataToFile(io {content.toCharArray})) simply returns a new monad, but we must "look at its screen"; make it compute a value, in other words. And that's what the unsafePerformIO function does.

Onwards, then! Let’s implement the combine function that selects all existing reports, and merges them into a one fat report that it then saves.

@Service
class ReportService @Autowired() (private val sessionFactory: SessionFactory) {
  type Data = Array[Char]
  import scalaz._
  import scalaz.effects._
  import scala.collection.JavaConversions._

  def reportToFile(report: Report) = io {
    new File("/Users/janmachacek/Tmp/r/%s".format(report.fileName))
  }
  def dataToFile(data: IO[Data])(file: File) = io {
    println("Written " + new String(data.unsafePerformIO) + " to " + file)
  }
  def fileToData(file: File) = io {
    Source.fromFile(file).toArray
  }

  @Transactional
  def produce() {
    ...
  }

  @Transactional
  def combine() {
    val reports =
      sessionFactory.getCurrentSession.createCriteria(classOf[Report]).
        list().asInstanceOf[java.util.List[Report]].toList

    val out = Report()
    out.fileName = "out.txt"

    // take the reports and make one big fat report out

    sessionFactory.getCurrentSession.saveOrUpdate(out)
  }

}

The combine selects all Report records, and (using the function in scala.collection.JavaConversions._) converts the java.util.List[Report] into scala.collections.immutable.List[Report]. How do we now combine the reports? Let’s think about it:

• If the reports contains just one item, then the result is that one item,
• If the reports contains two items, then we need some function that takes two Reports and makes the combined Report,
• If the reports contains many (i.e. more than two!) items, then we take the first two and combine them into one (using the function from the previous step). Then we take the combined report and combine it with the third item; then we take the combined report and combine it with the fourth item; and so on, until the end.

So, we need a function that combines two reports into one and then an operation that implements the algorithm we described earlier. The name for the operation is foldl1 and Figure 2 shows how it works:

Figure 2. foldl1 function



The arrows in the image are our function and report1, report2, ..., reportn is our list. Hence the code of the combine function becomes:

@Service
class ReportService @Autowired() (private val sessionFactory: SessionFactory) {

  ...

  @Transactional
  def combine() {
    val reports =
      sessionFactory.getCurrentSession.createCriteria(classOf[Report]).
        list().asInstanceOf[java.util.List[Report]].toList

    val out = Report()
    out.fileName = "out.txt"

    reports.foldl1 { (r1: Report, r2: Report) =>
      // read the r1 and r2 from the files,
      // combine them and write to out
      out
    }

    sessionFactory.getCurrentSession.saveOrUpdate(out)
  }
}

We now have to read the report from a file into Data and the combine the two Datas representing the reports together. The good news is that we have already written the monads that deal with the report IO. All we have to do is to combine them to form new interesting monad that combines the reports.

@Service
class ReportService @Autowired() (private val sessionFactory: SessionFactory) {

  ...

  @Transactional
  def combine() {
    val reports =
      sessionFactory.getCurrentSession.createCriteria(classOf[Report]).
        list().asInstanceOf[java.util.List[Report]].toList

    val out = Report()
    out.fileName = "out.txt"

    def combine(data: (Data, Data)) = io { data._1 ++ data._2 }

    reports.foldl1 { (r1: Report, r2: Report) =>
      (reportToFile(out) >>= dataToFile(
        (reportToFile(r1) >>= fileToData) <|*|>
        (reportToFile(r2) >>= fileToData) >>= combine)
      ).unsafePerformIO

      out
    }

    sessionFactory.getCurrentSession.saveOrUpdate(out)
  }
}

You already know about chaining the monads (using >>=), the new thing in the reports.foldl1 function is the <|*|> operation. Think of this operation indeed as multiplication, but multiplication of the computed values of the monads. The monad on the left-hand side ((reportToFile(r1) >>= fileToData)) computes Data, the monad on the right-hand side ((reportToFile(r2) >>= fileToData)) computes Data. In this case, we have Data * Data, in other words a pair–tuple in computer speak–of Data. And that’s precisely what the combine function takes (its body simply appends the two arrays) and it returns the combined IO of Data… and we can use it as input of the dataToFile function, which is an IO monad that follows the reportToFile(out) monads.

The whole contraption represents our report + report function; which we give to the foldl1 function. For completeness, we save the combined report using the injected sessionFactory.

Summary

This code combines dependency injection, load-time weaving (courtesy of the Spring Framework) with elegance and effectiveness of the Scala code. Finally, we take advantage of the IO monads in Scalaz to compose the individual trivial operations (report -> file, data -> file, etc.) to compose new operations that we use in the produce and combine functions.

0.4 follows the very short-lived Maven Central practice-release 0.3. We now include support for Spring 2.5, 3.0 and 3.1; for the latest verion of Spring, we include bean profiles and environment variables settable from the test annotations. We have also included support for raw SessionFactory and HibernateTemplate to work with the most popular ORM tool. The updates include:

• Supports Spring 2.5 through 3.1, including environment values and bean profiles in 3.1,
• Test data setup (using BeanTables) now works with HibernateTemplate as well as SessionFactory in Hibernate 4
• The @Bean annotation’s type value is now clazz to make it usable from Scala code

Most excitingly, Specs2 Spring is now available in Maven Central and Sonatype OSS! All you need to do now is to include the dependency in your pom.xml:

<dependency>
    <groupId>org.specs2</groupId>
    <artifactId>spring_2.9.1</artifactId>
    <version>0.4</version>
</dependency>

To get started, download the ScalaDocs and PDF user guide; check out the http://www.cakesolutions.org/specs2-spring.html

Sonatype OSS support

The first thing to is to open an issue in Sonatype’s JIRA, asking them to set up the Nexus repository for you. Once that’s done, you will be able to publish your snapshots and releases to Sonatype; the releases are then synchronised to Maven Central. The first few pages of Sonatype OSS Maven Repository Usage Guide will show you how to get started.

Building and publishing

Now, this is the interesting bit. We are using SBT to build the project and we’d like to be able to run sbt publish to compile, package and publish the project to Sonatype automatically. Before we can do that, we need to configure GPG and SBT plugin that uses GPG to sign the artefacts. The plugin is xsbt-gpg-plugin, which will use GPG to sign the artefacts–properly signed artefacts are the requirement for Maven Central synchronisation. So, with the plugin, your project/plugins.sbt file should contain:

...
resolvers += Resolver.url("scalasbt", /* no new line */
  new URL("http://scalasbt.artifactoryonline.com/scalasbt/sbt-plugin-releases")) /* no new line */
  (Resolver.ivyStylePatterns)

addSbtPlugin("com.jsuereth" % "xsbt-gpg-plugin" % "0.5")
...

If you do not have GPG, you must also install & configure it for your platform; if you do not have your keys, you must also generate key pair and then publish your public key. I cannot quite show you how to do this on Windows (sorry, get a Mac!). On OS X, you can use GPG Tools. Download and install it; the first thing GPG Tools will prompt you to do is to generate your key, protected by a passphrase. (I recommend that you keep the passphrase very long, as XKCD points out in Figure 1!)

Figure 1. Key strengths

Before I can release the artefacts in Sonatype OSS releases and in Maven Central, I need to publish my public keys (so that others can verify that the artefacts are intact and that it was I who has produced them). To do that, you can use the GPG Keychain Access (see Figure 2) tool or use the gpg command-line program.

Figure 2. GPG Keychain Access

We are programmers, so let’s turn to the command line: we need to export a key, but to do that, we need to know its identifier:

$ gpg --list-secret-keys
/Users/janmachacek/.gnupg/secring.gpg
-------------------------------------
sec   2048R/90A468A9 2012-01-30 [expires: 2016-01-30]
uid                  Jan Machacek <jan.machacek@gmail.com>
ssb   2048R/A9ED23D0 2012-01-30

$ gpg --send-keys 90A468A9

Your public key is now uploaded to the default key server (specified in ~/.gnupg/gpg.conf) and it will be distributed to other key servers over the next few minutes. Once that happens, you’ll be ready to release your artefacts to Maven Central.

Releasing

Before we’ll configure the JAR signing, we must deal with the publish process. We set the publishTo (and several other settings) in build.sbt to use the Sonatype repository like so:

publishTo <<= version { v: String =>
  val nexus = "https://oss.sonatype.org/"
  if (v.trim.endsWith("SNAPSHOT"))
    Some("snapshots" at nexus + "content/repositories/snapshots")
  else
    Some("releases" at nexus + "service/local/staging/deploy/maven2")
}

Before we can publish our SBT-based project, we must ensure that its generated Maven POMs match the strict requirements of Sonatype and Maven Central. So, we must include the following code in your build.sbt:

publishMavenStyle := true

publishArtifact in Test := false

pomIncludeRepository := { x => false }

pomExtra := (
  <url>http://www.cakesolutions.org/specs2-spring.html</url>
  <licenses>
    <license>
      <name>BSD-style</name>
      <url>http://www.opensource.org/licenses/bsd-license.php</url>
      <distribution>repo</distribution>
    </license>
  </licenses>
  <scm>
    <url>git@github.com:janm399/specs2-spring.git</url>
    <connection>scm:git:git@github.com:janm399/specs2-spring.git</connection>
  </scm>
  <developers>
    <developer>
      <id>janmachacek</id>
      <name>Jan Machacek</name>
      <url>http://cakesolutions.org</url>
    </developer>
  </developers>
)

Now, before we even attempt to run sbt publish, we need to specify the credentials for the Sonatype repository. But we don’t want to do that in the files we push to the VCS! Instead, we’ll create file ~/.sbt/sonatype.sbt, which sets the credentials setting to the Sonatype ones:

credentials += Credentials("Sonatype Nexus Repository Manager",
                           "oss.sonatype.org",
                           "your-sonatype-username",
                           "your-sonatype-password")

The work is done! We’ve modified

• ~/.sbt/sonatype.sbt with the Sonatype OSS credentials
• project/plugins.sbt with the xsbt-gpg-plugin plugin to sign the artefacts
• build.sbt to include the release settings

Now we can run sbt publish, supply our key phrase go GPG and push the artefacts to Sonatype. If you are publishing snapshot release, then your work is done. If you are publishing a “real” release, keep reading.

Promoting

Once you’ve published your non-snapshot release, you will need to go to the Sonatype Nexus, login, select the staging repository and close it. (Again, follow the Sonatype Nexus guide for details.) Closing will verify that the Maven POMs are well formed, that the artefacts’ signatures are valid. If all is well, your repository will end up in Maven Central within a few hours’ time!

Summary

Publishing SBT-based projects to Sonatype and then Maven Central is easy–once you’ve dealt with the details of the Maven POMs. For complete views of the build.sbt and project/plugins.sbt files, take a look at Specs2 Spring’s sources at https://www.github.com/janm399/specs2-spring.

Josh Suereth (http://jsuereth.com/), the maintainer of the xsbt-gpg-plugin SBT plugin maintains a page where he outlines the latest details of the SBT deployment process. Clicky-here to see Josh’s instructions.

<dependency>
  <groupId>org.specs2</groupId>
  <artifactId>spring_${scala.version}</artifactId>
  <version>0.3</version>
  <scope>test</scope>
</dependency>

Where scala.version property is 2.9.1; or, if you prefer SBT, simply add to libraryDependencies:

libraryDependencies ++= Seq(
  "org.specs2" %% "spring" % "0.3"
)

What to do in the next few days/weeks

But before that happens, you’ll need to build Specs2 Spring yourself. The good news is that it’s not at all difficult. You’ll need:

1. Paul Phillips’s SBT Extras at https://github.com/paulp/sbt-extras
2. Clones of https://github.com/janm399/sbt-docbook-plugin and https://github.com/janm399/specs2-spring

Once you download the SBT Extras shell script, put it somewhere you remember and add it to your PATH. In my case, I copied the SBT Extras sbt script to /usr/share/scala/sbt and I’ve modified /etc/profile to say:

export PATH=$PATH:/usr/share/scala/sbt

Next, clone the two repositories to some directory, say ~/sandbox. Then you need to publish both projects to your local Ivy repository (this is where they are going to be picked up from later on).

~/sandbox$ cd sbt-docbook-plugin
~/sandbox/sbt-docbook-plugin$ sbt publish-local
~/sandbox/sbt-docbook-plugin$ cd ../specs2-spring
~/sandbox/specs2-spring$ sbt publish-local

And you’re ready to go. The "de.undercouch" % "sbt-docbook-plugin" % "0.2-SNAPSHOT" "org.specs2" % "spring" % "0.3" are now available in your local Ivy repository; and you can use them in your Maven or SBT projects.

If you would like to contribute, and if you use IntelliJ IDEA, you can generate the IntelliJ IDEA project files by running sbt gen-idea in both projects.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:context="http://www.springframework.org/schema/context"
  xmlns:scala="http://www.springframework.org/schema/scala"
  xsi:schemaLocation=...>

  <scala:bean class="org.cakesolutions.scala.services.UserService" >
    <scala:with trait="org.cakesolutions.scala.services.Mixin1" />
    <scala:with trait="org.cakesolutions.scala.services.Mixin2" />

    <scala:property name="dependency" value="Injected" />
  <scala:bean>

</beans>

The difficulty is that Class.forName function does not allow me to specify the mixins. In the end, I modified a very hacky solution on Stack Overflow (which did not quite work in Scala 2.9 and only used one mixin). The solution involves generating classes that are similar to the classes that the Scala compiler generates when we run something like new Cat with Eating with Speaking. So, here it is in its full gory:

class ScalaBeanFactory(private val beanType: Class[_ <: AnyRef],
                       private val mixinTypes: Seq[Class[_ <: AnyRef]]) {
  val loader = new DynamicClassLoader
  val clazz = loader.buildClass(beanType, mixinTypes)

   def getTypedObject[T] = getObject.asInstanceOf[T]

   def getObject = {
     clazz.newInstance()
   }

   def getObjectType = null

   def isSingleton = true

}

object DynamicClassLoader {
  private var id = 0
  def uniqueId = synchronized {  id += 1; "Klass" + id.toString }
}

class DynamicClassLoader extends java.lang.ClassLoader(getClass.getClassLoader) {

  def buildClass(t: Class[_ <: AnyRef], vs: Seq[Class[_ <: AnyRef]]) = {
    val id = DynamicClassLoader.uniqueId

    val classDef = new StringBuilder

    classDef.append("class ").append(id)
    classDef.append(" extends ").append(t.getCanonicalName)
    vs.foreach(c => classDef.append(" with %s".format(c.getCanonicalName)))

    val settings = new Settings(null)
    settings.usejavacp.value = true
    val interpreter = new IMain(settings)

    interpreter.compileString(classDef.toString())

    val r = interpreter.classLoader.getResourceAsStream(id)
    val o = new ByteArrayOutputStream
    val b = new Array[Byte](16384)
    Stream.continually(r.read(b)).takeWhile(_ > 0).foreach(o.write(b, 0, _))
    val bytes = o.toByteArray

    defineClass(id, bytes, 0, bytes.length)
  }

}

The code cannot yet deal with constructors with parameters and does not copy annotations from the parent class’s constructor (should it do that?). However, it gives us a good starting point that is usable in the scala Spring namespace. Of course, don’t just take my word for it, verify it in a Specs2 specification:

class ScalaBeanFactorySpec extends Specification {

  "getTypedObject mixes-in the specified traits" in {
    val f1 = new ScalaBeanFactory(classOf[Cat],
                                  Seq(classOf[Speaking], classOf[Eating]))

    val c1 = f1.getTypedObject[Cat with Eating with Speaking]

    c1.isInstanceOf[Cat with Eating with Speaking] must_==(true)

    /*
    c1.speak    // in trait Speaking
    c1.eat      // in trait Eating
    c1.meow     // in class Cat
    */
  }

}

What is Scala

Scala is a type-safe, object-functional language. Scala allows you to build scalable (no, really?) systems by attempting to address the complexity of large systems. Its functional nature allows you to focus on the procedures in your system rather than the components in which these procedures live. Finally, Scala remains object-orieted, giving you the familiar inheritance, encapsulation and polymorphism.

In Scala, a functions is a first-class type; and as such can be assigned to a variable or passed as argument. You can kiss good-bye to the anonymous implementations of interfaces containing exactly one method: replace them with functions. But Scala goes further: its functions can accept functions as parameters and return functions; you can supply only some parameters of a function and the Scala compiler will create a new function that takes the remaining parameters! Finally, Scala functions can also have multiple parameter lists!

def curry(i: Int)(j: Int) = i * j
val f = (x: Double, y: Double) => x * y
val fWithXEq5 = f(5, _: Double)
val oneTimeX = curry(1)_

fWithXEq5(3)   // == 15
curry(1)(2)    // == 2
oneTimeX(2)    // == 2

In Scala, you compose functionality through composition inheritance. You can think of this as multiple implementation inheritance with some terms and conditions; the closest equivalent in Java would be an interface with method bodies. With careful design, you can inject functionality to the objects that you construct; while keeping the elements (traits in Scala speak) completely isolated and independent.

trait Speakable {
  def sound: String

  def speak() {
    val voice = VoiceManager.getInstance().getVoice("kevin16")
    voice.allocate()
    voice.speak(sound)
    voice.deallocate()
  }
}

abstract class Animal {
  def sound: String
}
class Dog extends Animal {
  def sound = "Woof"
}
class Cat extends Animal {
  def sound = "Meow"
}
class SpeakingCat extends Cat with Speakable 

val cat = new Cat with Speakable
val dog = new Dog with Speakable
val muteDog = new Dog
val speakingCat = new SpeakingCat

cat.speak()           // OK, meows
dog.speak()           // OK, woofs
speakingCat.speak()   // OK, meows
muteDog.speak()       // Does not compile

Notice that I was able to mix-in the Speakable trait to either individual instances or create a new subclass of Cat with the speaking trait mixed-in.

You can also express meaning in the types in your code; meaning that in Java is impossible to convey in the source code and we must rely on the programmers’ common sense.

abstract class Animal {
  type SuitableFood <: Food
}
class Cat extends Animal {
  type SuitableFood = CatFood
}
class Dog extends Animal {
  type SuitableFood = DogFood
}

abstract class Food
class CatFood extends Food
class LuxuryCatFood extends CatFood
class DogFood extends Food

def feed[A <: Animal, F <: A#SuitableFood](animal: A, food: F) =
  // somehow feed food to animal

I have expressed the common sense knowledge that a cat will eat cat food (just about), it will certainly eat luxury cat food, but will not touch dog food. The function feed enforces this at compile time!

feed(new Cat, new CatFood)       // OK
feed(new Cat, new LuxuryCatFood) // OK
feed(new Cat, new DogFood)       // Don't be silly; does not compile!

See! Too complicated

You might be thinking, “this is exactly the complexity I don’t want in my code!” Yes, the code I’ve shown is more complex than your Java code, but it does so much more! It is impossible to express the concepts I’ve shown in Java as clearly and as succinctly as I can do in Scala. Yes, Scala code can be complex, but not because the language is inherently and needlessly complex, but because it can solve very complicated problems.

All right, it’s not complex, but it’s not really useful

Scala is brilliantly useful, because it compiles to the standard Java byte code and because it can use all your existing Java code. Combine Java and Scala and implement polyglot codebase that uses the best language to solve your problems! Look–you can even have use Scala with Spring Framework!

@Controller
class UserController @Autowired() (private val userService: UserService) {

  @RequestMapping(value = "/users", method = RequestMethod.GET)
  @ModelAttribute("users")
  def index = userService.findAll

}

Find out more!

Try out Scala, ask us for advice, guidance and mentoring, and you will have polyglot codebase that uses the best language to solve your problems! I’d be delighted to show you how to combine Scala in traditional Java EE applications either by implementing discrete portion of your application in Scala or even implementing most of your application in Scala, but using your existing Java.

Think about a typical JEE application: you have the domain, repository, services and web app; the dependencies between the modules are that:

• domain does not have any dependencies
• repository depends on domain
• services depends on domain and repository
• web app depends on domain and services

In this post, I am not going to be talking about Spring Java EE application. I will show you how I have moved Specs2 Spring from Maven to SBT.

Specs2 Spring was a multi-module Maven project, with five modules:

• org.specs2.spring with no dependencies
• org.specs2.spring-example depends on org.specs2.spring
• org.specs2.spring.web depends on org.specs2.spring
• org.specs2.spring.web-example depends on org.specs2.spring.web
• org.specs2.spring.documentation with no dependencies

In addition to expressing the structure in the Maven poms, I needed to configure the Scala compiler to run during the compile and testCompile phases. Also, I wanted to generate DocBooks as part of the build process. All this made the parent pom.xml rather verbose, reaching 215 lines of XML; the most notable ones being:

<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.specs2</groupId>
  <artifactId>parent</artifactId>
  <version>0.3</version>
  <packaging>pom</packaging>

  <properties>
      ...
    <specs2.version>1.7</specs2.version>

  </properties>

  <dependencies>
    <dependency>
      <groupId>org.scala-lang</groupId>
      <artifactId>scala-library</artifactId>
      <version>2.9.1</version>
    </dependency>
  </dependencies>

  <modules>
    <module>org.specs2.spring</module>
    <module>org.specs2.spring.web</module>
    <module>org.specs2.spring.documentation</module>

    <module>org.specs2.spring-example</module>
    <module>org.specs2.spring.web-example</module>
  </modules>

  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-compiler-plugin</artifactId>
          <version>2.0.2</version>
        </plugin>
        <plugin>
          <groupId>org.scala-tools</groupId>
          <artifactId>maven-scala-plugin</artifactId>
          <version>2.15.3-SNAPSHOT</version>
        </plugin>
      </plugins>
    </pluginManagement>
    <plugins>
      <plugin>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>2.7.2</version>
        <configuration>
          <classesDirectory>target/classes</classesDirectory>
          <includes>
            <include>**/*Test.class</include>
          </includes>
          <argLine>-Xmx1024M -XX:MaxPermSize=256m</argLine>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <source>1.6</source>
          <target>1.6</target>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.1</version>
        <configuration>
          <failOnMissingWebXml>false</failOnMissingWebXml>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.scala-tools</groupId>
        <artifactId>maven-scala-plugin</artifactId>
        <executions>
          <execution>
            <goals>
              <goal>compile</goal>
              <goal>testCompile</goal>
            </goals>
          </execution>
        </executions>
      </plugin>

      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
        <version>2.0.13</version>
        <configuration>
          <xincludeSupported>true</xincludeSupported>
          <highlightSource>1</highlightSource>
          <foCustomization>
            ${project.basedir}/src/docbkx/styles/pdf/custom.xsl
          </foCustomization>
        </configuration>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
          <dependency>
            <groupId>net.sf.xslthl</groupId>
            <artifactId>xslthl</artifactId>
            <version>2.0.1</version>
            <scope>runtime</scope>
          </dependency>
          <dependency>
            <groupId>net.sf.offo</groupId>
            <artifactId>fop-hyph</artifactId>
            <version>1.2</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>

        <executions>
          <execution>
            <phase>pre-site</phase>
            <goals>
              <goal>generate-html</goal>
              <goal>generate-pdf</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>

</project>

This parent pom.xml refers to modules, which must be sub-directories with another pom.xml file in them. The org.specs2.spring/pom.xml with no dependencies amongst the project modules simply listed all other dependencies:

<?xml version="1.0" encoding="UTF-8"?>
<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">

  <parent>
    <groupId>org.specs2</groupId>
    <artifactId>parent</artifactId>
    <version>0.3</version>
  </parent>
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.specs2</groupId>
  <artifactId>spring</artifactId>
  <packaging>jar</packaging>
  <version>0.3</version>

  <dependencies>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-core</artifactId>
      <version>${spring.version}</version>
    </dependency>
    ...
  </dependencies>

</project>

The org.specs2.spring-example module depends on the org.specs2.spring module, so its pom.xml had to include the org.specs2.spring-example module like so:

<?xml version="1.0" encoding="UTF-8"?>
<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">

  <parent>
    <groupId>org.specs2</groupId>
    <artifactId>parent</artifactId>
    <version>0.3</version>
  </parent>
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.specs2</groupId>
  <artifactId>spring-example</artifactId>
  <packaging>jar</packaging>
  <version>0.3</version>

  <dependencies>
    <dependency>
      <groupId>org.specs2</groupId>
      <artifactId>spring</artifactId>
      <version>0.3</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-core</artifactId>
      <version>${spring.version}</version>
    </dependency>
    ...
  </dependencies>

</project>

Oh, the humanity!

Quite. All this XML became a bit too uncomfortable to navigate around. Furthermore, most of the Scala projects out there use SBT, which promises to be as powerful, but much more concise build tool. So, I set out to replace Maven’s verbose XML with SBT’s… call it scripts.

SBT Scripts?

SBT is essentially a domain-specific language for building projects. SBT (the tool) then runs the Scala program that is assembled from the various script files as well as full-blown Scala sources. To make life easier, SBT maintains two sets of files: the .sbt files are decorated into the full Scala syntax and then compiled together with the grown-up Scala code. <ins>SBT decorates the body of the .sbt file to become a compilation unit (put simply, a class with all imports and functions resolved). Every block in the .sbt file then becomes a function in the resulting compilation unit. SBT uses empty lines to demarcate what is to become the functions, which is why every “statement” in the .sbt file needs to be on its own line and why you cannot have empty lines in multi-line “statements”. (Many thanks to @plalloni for clarification and comments!)</ins> SBT then executes the resulting Scala program to build your project. There is much more detail at SBT’s documentation at https://github.com/harrah/xsbt/wiki. Let’s take a look at how I’ve transformed the multi-module Maven beast into SBT.

Multi-module SBT

First, let’s take a look at a typical SBT project. It contains the build.sbt file (that gets rewritten into the grown-up Scala program that then compiles your code, but you already knew that!). A SBT project also needs the source files, which are in the usual Maven structure. So, a single SBT project typically looks like this:

src
  main
    java
    scala
    resources
  test
    java
    scala
    resources
build.sbt

SBT is smart enough to work out that the files in the java directory are to be compiled using the Java compiler; that the files in the scala directory need to be compiled using the Scala compiler and that the files in resources are not to be compiled, simply copied to the output.

Now, in Specs2 Spring, I have five projects, so the first approach was to include the build.sbt in every sub-project:

org.specs2.spring
  src
    ...
  build.sbt
org.specs2.spring-example
  src
    ...
  build.sbt
org.specs2.spring.web
  src
    ...
  build.sbt
org.specs2.spring.web-example
  src
    ...
  build.sbt
org.specs2.spring.documentation
  src
    ...
  build.sbt

build.sbt

The structure is clear[-ish]: we have five modules, each module’s build.sbt describes how it is to be built; and there is a main build.sbt, which should build all modules in the right sequence.

The situation is slightly more complicated. There is no provision for project dependencies in the simplified syntax of the .sbt files. (Recall that they are transformed into Scala by SBT.)
In order to have multi-module SBT projects, we need to define a Scala source that represents the project build. We do so by creating the project directory at the same level as the modules and adding the Build.scala file, which contains object that extends sbt.Build. So, we have:

org.specs2.spring
  build.sbt
org.specs2.spring-example
  build.sbt
org.specs2.spring.web
  build.sbt
org.specs2.spring.web-example
  build.sbt
org.specs2.spring.documentation
  build.sbt

project
  Build.scala

build.sbt

The interesting file is the Build.scala, which defines the “modules” that make up the project and that sets the dependencies between the modules. It is surprisingly simple:

import sbt._

object Specs2Spring extends Build {

  lazy val root =
    Project("specs2-spring", file("."))
            aggregate(core, coreExample, documentation, web, webExample)
  lazy val core =
    Project("org.specs2.spring", file("org.specs2.spring"))
  lazy val coreExample =
    Project("org.specs2.spring-example",
            file("org.specs2.spring-example")) dependsOn(core)

  lazy val web =
    Project("org.specs2.spring.web",
            file("org.specs2.spring.web")) dependsOn(core)
  lazy val webExample =
    Project("org.specs2.spring.web-example",
            file("org.specs2.spring.web-example")) dependsOn(web)

  lazy val documentation =
    Project("org.specs2.spring.documentation",
            file("org.specs2.spring.documentation"))
}

Notice that the object Specs2Spring extends sbt.Build and defines the variables that represent the projects. We have the root project, which is simply an aggregate of the remaining projects, which are each defined in their own variable. Projects can define dependencies using the dependsOn function, specifying the project variable of the dependency. How simple!

Now that we have the Specs2Spring project build source out of the way, let’s take a look at the smaller build.sbt files that complete the picture. By far the most complex is the org.specs2.spring/build.sbt:

/** Project */
name := "specs2-spring"

version := "0.3"

organization := "org.specs2"

scalaVersion := "2.9.1"

crossScalaVersions := Seq("2.9.0")

/** Dependencies */
resolvers ++= Seq("snapshots-repo" at "http://scala-tools.org/repo-snapshots")

libraryDependencies <<= scalaVersion { scala_version => Seq(
  "org.specs2" %% "specs2" % "1.7.1",
  "junit" % "junit" % "4.7" % "optional",
  "org.springframework" % "spring-core" % "3.1.0.RELEASE",
  "org.springframework" % "spring-beans" % "3.1.0.RELEASE",
  "org.springframework" % "spring-jdbc" % "3.1.0.RELEASE",
  "org.springframework" % "spring-tx" % "3.1.0.RELEASE",
  "org.springframework" % "spring-orm" % "3.1.0.RELEASE",
  "org.springframework" % "spring-test" % "3.1.0.RELEASE",
  "org.hibernate" % "hibernate-core" % "3.6.0.CR1",
  "javax.mail" % "mail" % "1.4.1",
  "javax.transaction" % "jta" % "1.1",
  "com.atomikos" % "transactions-jta" % "3.7.0",
  "com.atomikos" % "transactions-jdbc" % "3.7.0",
  "org.apache.activemq" % "activemq-core" % "5.4.1"
  )
}

/** Compilation */
javacOptions ++= Seq()

javaOptions += "-Xmx2G"

scalacOptions ++= Seq("-deprecation", "-unchecked")

maxErrors := 20 

pollInterval := 1000

logBuffered := false

cancelable := true

testOptions := Seq(Tests.Filter(s =>
  Seq("Spec", "Suite", "Unit", "all").exists(s.endsWith(_)) &&
    !s.endsWith("FeaturesSpec") ||
    s.contains("UserGuide") ||
    s.contains("index") ||
    s.matches("org.specs2.guide.*")))

In the build.sbt file, you can see that I specify some common settings (name, version, Scala version); the managed libraries (dependencies in Maven speak) and I configure the parameters of the compiler. But that’s all I need to do!

The remaining build.sbt files can be much simpler, because SBT compiles the project/Build.scala and all transformed build.sbt files into a single program that then builds your project. Let’s pick the org.specs2.spring-example/build.sbt as an example:

libraryDependencies <<= scalaVersion { scala_version => Seq(
  "org.springframework" % "spring-core" % "3.1.0.RELEASE",
  "org.springframework" % "spring-beans" % "3.1.0.RELEASE",
  "org.springframework" % "spring-jdbc" % "3.1.0.RELEASE",
  "org.springframework" % "spring-tx" % "3.1.0.RELEASE",
  "org.springframework" % "spring-orm" % "3.1.0.RELEASE",
  "org.hibernate" % "hibernate-core" % "3.6.0.CR1",
  "org.hibernate" % "hibernate-validator" % "4.0.2.GA",
  "javassist" % "javassist" % "3.4.GA",
  "org.hsqldb" % "hsqldb" % "2.2.4"
  )
}

That is all!; you can now run sbt compile, sbt test, sbt publish-local and many others. sbt is a shell script; one example is at https://github.com/harrah/xsbt/wiki/Getting-Started-Setup, but Paul Phillips created far more powerful version, which you can download at https://github.com/paulp/sbt-extras.

The devil in the detail

Now, we have a successful multi-module project in SBT. Everything builds, all libraries are downloaded and the dependencies between the projects work as well. But what about DocBook? In Maven, I used to use the com.agilejava.docbkx:docbkx-maven-plugin plugin, which took care of generating the HTMLs and PDFs.

Luckily, SBT supports similar plugin infrastructure. All we need to do is to include the appropriate plugins in our project and we can run tasks that the plugins expose. To do what I just described, we need to create the project/plugins.sbt file that lists the required plugins in the project that requires the plugin. So, taking our org.specs2.spring.documentation module (or sub-project, if you like), we need to create the following structure:

org.specs2.spring
...
org.specs2.spring.documentation
  project
    plugins.sbt
  src
    main
      docbook
        ...
  build.sbt
...
project
  Build.scala
build.sbt

The interesting file is the plugins.sbt, which defines the plugins our project requires. The org.specs2.spring.documentation/project/plugins.sbt contains just a single line:

addSbtPlugin("de.undercouch" % "sbt-docbook-plugin" % "0.2-SNAPSHOT")

The "de.undercouch" % "sbt-docbook-plugin" % "0.2-SNAPSHOT" plugin requires some properties to be set in the build.sbt, namely the sourceFilter and, because we have our own XSL for the PDF, the docBookXslFoStyleSheet. So, in the org.specs2.spring.documentation/build.sbt, we have:

sourceFilter := "**/*.xml"

docBookXslFoStyleSheet in DocBook:= "src/docbkx/styles/pdf/custom.xsl"

I updated the plugin to the latest version of Scala and SBT and sent a pull request to the original author; my sources are at https://github.com/janm399/sbt-docbook-plugin (for the future of the plugin, see the open issues).

Summary

So, what can you achieve? Put simply, the same build functionality in approximately quarter lines of code. Even if you do not use any of the advanced features of SBT, you have gained a more intuitive way of building Java and Scala applications; you can also release your libraries for the correct version of the Scala compiler (no more appending _2.9.1, _2.9.0_1 and similar to your Maven dependencies!). The artefacts that SBT produces fit directly into the Scala repositories without additional effort.

With this structure, the project will build just like the Maven monster it replaced! As usual, the devil was in the details, so keep reading.

P.S. All SBT goodness is at the SBT master branch of https://github.com/janm399/specs2-spring I will make some final modifications (namely get rid of the now superfluous root project directory) in preparation for the 0.4 release. (With all the changes applied.)

P.P.S. All signs point to Specs2 Spring being available on the scala-tools.org repo in the next few days!

I’ll be speaking at Spring IO in Madrid in 17th to 18th February 2012. My talk will be Spring in Scala, showing how to make the most of Scala in your Spring applications.

If you can, escape the winter blues, come to Madrid and hopefully to my talk.

Synopsis

In his Spring in Scala talk, Jan will start by comparing Scala to the other languages on the Java platform. Find out that Scala code gets compiled to regular Java bytecode, making it accessible to your Spring code. You will also learn what functional programming means and how to see & apply the patterns of functional programming in what we would call enterprise code.
Throughout the talk, there will be plenty of code examples comparing the Spring bean in Java with their new form in Scala; together with plentiful references to the ever-growing Scala ecosystem, the talk will give you inspiration & guidance on using Scala in your Spring applications.
Come over and find your functional mojo!

public interface LegalRegulations {
  boolean hasDoped(Rider rider);
}

@Component
@Profile("UCI")
public class UCILegalRegulations implements LegalRegulations {
  @Override
  public boolean hasDoped(Rider rider) {
    return true;
  }
}

@Component
@Profile("ACU")
public class ACULegalRegulations implements LegalRegulations {

  @Override
  public boolean hasDoped(Rider rider) {
    return false;
  }
}

Now, I have two beans that implement the same interface. Depending on which country we run the application in, we want to use the appropriate implementation of the LegalRegulations interface. Notice in the code above the @Profile annotation with a constant that specifies the name of the profile in which the bean should be included.

In addition to the profiled beans, I have other beans that are included in every profile. The last bean that I will show you is the SomeComponent bean (which just so happens to be implemented in Scala).

@Component
class SomeComponent
  @Autowired()(private val hibernateTemplate: HibernateTemplate) {

  def findAll(entityType: Class[_]) =
    this.hibernateTemplate.loadAll(entityType)

  def generate(count: Int) {
    for (c <- 0 until count) {
      val rider = new Rider()
      rider.setName("Rider #" + c)
      rider.setUsername("user " + c)
      this.hibernateTemplate.saveOrUpdate(rider)
    }
  }

  def getByUsername(username: String) = {
    val riders = this.hibernateTemplate.findByCriteria(
      DetachedCriteria.forClass(classOf[Rider]).add(
        Restrictions.eq("username", username)))
    riders.get(0).asInstanceOf[Rider]
  }

}

This bean depends on the HibernateTemplate, which in turn depends on SessionFactory; the SessionFactory depends on a DataSource, which is looked up in JNDI. The Spring context file for the application is simply

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans" ... >

  <context:component-scan base-package="org.specs2.springexample"/>

  <tx:jta-transaction-manager />

  <tx:annotation-driven />

  <jee:jndi-lookup id="dataSource" jndi-name="java:comp/env/jdbc/test"
    expected-type="javax.sql.DataSource"/>

  <bean id="sessionFactory"
    class="org.springframework.orm.hibernate3.annotation.AnnotationSessionFactoryBean">
    <property name="dataSource" ref="dataSource"/>
    <property name="packagesToScan">
      <list>
        <value>org.specs2.springexample</value>
      </list>
    </property>
    <property name="hibernateProperties">
      <value>
        hibernate.show_sql=true
        hibernate.dialect=org.hibernate.dialect.HSQLDialect
        hibernate.query.factory_class=org.hibernate.hql.ast.ASTQueryTranslatorFactory
        hibernate.cache.use_structured_entries=true
        hibernate.hbm2ddl.auto=create-drop
      </value>
    </property>
  </bean>

  <bean id="hibernateTemplate"
    class="org.springframework.orm.hibernate3.HibernateTemplate">
    <property name="sessionFactory" ref="sessionFactory"/>
  </bean>

</beans>

Testing it

Now, to test the application, I need to prepare the JNDI environment and specify the profile that I want to use for testing. Nothing is easier in Specs2 Spring. All I need to do is to create the class that contains the specifications; that extends org.specs2.spring.Specification and is annotated with the Specs2 Spring annotations. (There is much more detail at http://www.cakesolutions.org/specs2-spring.html.) In this post, I will show just the code that is necessary to test the trivial rider manager application.

@Transactional
@TransactionConfiguration (defaultRollback = true)
@ContextConfiguration(
  Array("classpath*:/META-INF/spring/module-context.xml"))
@UseProfile(Array("ACU"))
@SystemEnvironment(Array("efoo=bar;ebaz=null"))
@SystemProperties(Array("pfoo=bar;pbaz=null"))
@DataSource(name = "java:comp/env/jdbc/test",
  driverClass = classOf[JDBCDriver], url = "jdbc:hsqldb:mem:test")
@TransactionManager(name = "java:comp/TransactionManager")
class ApplicationSpec extends Specification
  with HibernateDataAccess with BeanTables {

  @Autowired var regulations: LegalRegulations = _
  @Autowired var someComponent: SomeComponent = _

  "no-one dopes!" in {
    "age" | "username" | "name"    | "teamName" |
       32 ! "wheeler"  ! "Wheeler" ! "Wheelers" |
       30 ! "nemesis"  ! "Nemesis" ! "Baddies"  |> insert[Rider]

    val rider = this.someComponent.getByUsername("wheeler")
    regulations.hasDoped(rider) must be_== (false)
  }

}

Specs2 Spring understands all the annotations and prepares the JNDI environment (the DataSource and the TransactionManager), then creates the Spring ApplicationContext using the configuration files specified in @ContextConfiguration annotation with the ACU profile (see the @UseProfile(Array("ACU")) annotation). It also specifies the system environment and system properties to be efoo => "bar" and ebaz => null and pfoo => "bar" and pbaz => null. Presumably, some beans use the @Value annotation with the SPEL expression that extracts the value from the environment.

Getting it

If you want to get your hands on Specs2 Spring 0.3, go to https://github.com/janm399/specs2-spring. If you find a bug or if you’d like a feature to be included, please do create an issue at https://github.com/janm399/specs2-spring/issues.

import annotation.tailrec

abstract class Tree(val left: Tree) {
  def o = new Ball(this)
  def x = new Spike(this)
  def * = new Candle(this)
  def oxo = new BigBall(this)
  def oo = new DoubleBall(this)
  def *** = new ElectricCandle(this)

  def / = new LeftNeedle(this)
  def \ = new RightNeedle(this)
  def | = new Trunk(this)

}
class Top(star: Star) extends Tree(star)
abstract class Needle(left: Tree) extends Tree(left)
class LeftNeedle(left: Tree) extends Needle(left)
class RightNeedle(left: Tree) extends Needle(left) {

  def |||() {
    |||(true)
  }

  @tailrec
  final def |||(sparkle: Boolean) {
    val f = (t: Tree) =>
      t match {
        case _: LeftNeedle => "/"
        case _: RightNeedle => "\\"
        case _: Trunk => "|"
        case _: Ball => "o"
        case _: Spike => "x"
        case _: Candle => "*"
        case _: BigBall => "oxo"
        case _: DoubleBall => "oo"
        case _: ElectricCandle => "***"
      }

    def walk(t: Tree, depth: Int): List[String] = {
      def walkLevel(t: Tree, acc: String,
                    f: (Tree) => String): (Tree, String) = {
        val fx = (t: Tree) => if (sparkle) f(t).toUpperCase else f(t)
        t match {
          case l: LeftNeedle => (l.left, fx(l) + "." + acc)
          case t: Tree => walkLevel(t.left, fx(t) + "." + acc, f)
        }
      }

      t match {
        case r: RightNeedle =>
          val l = walkLevel(r, "", f)
          l._2 +: walk(l._1, depth + 1)
        case s: Star =>
          List("-->*<-- ", "\\-/.")
      }
    }

    val tree = "||| " +: walk(this, 0)

    tree.reverse.foreach({l =>
      val numSpaces = 30 - (l.length() / 2)
      val padding = " " * numSpaces
      print(padding)
      println(l)
    })

    Thread.sleep(500)

    |||(!sparkle)
  }

}
class Trunk(parent: Tree) extends Tree(parent)

abstract class Decoration(left: Tree) extends Tree(left)
class Star extends Decoration(null)
class Candle(left: Tree) extends Decoration(left)
class Ball(left: Tree) extends Decoration(left)
class Spike(left: Tree) extends Decoration(left)
class BigBall(left: Tree) extends Decoration(left)
class DoubleBall(left: Tree) extends Decoration(left)
class ElectricCandle(left: Tree) extends Decoration(left)

trait DecorationBuilder {
 def \-/ = new PartialDecoration
}
class PartialDecoration {
 def -->*<-- = new Star
}

object ChristmasTree extends DecorationBuilder {

  def main(args: Array[String]) {
           \-/.
         -->*<--
            .
           /.\
         ./.|.\.
         /.oxo.\
       ./.*.|.x.\.
       /.oo.|.oo.\
     ./.oxo.|.***.\.
     /.*.oo.|.*.oo.\.
           |||
  }

}