table of contents »

Introducing Circumflex

Circumflex is a set of software components for quick and robust application development using the Scala programming language.

Circumflex consists of several separate projects:

At a glance

All Circumflex components share the same philosophy: the development process should be natural and intuitive. They rely on Scala's support for domain-specific languages that make development extremely efficient. And simple.

Web Framework

Circumflex Web Framework is a DSL for quick web application development.

It is designed around the route concept. A route is an HTTP method with matching mechanism and attached block. The application itself is essentially a sequential set of routes: they are matched in the order they are defined, the first route that matches the request is invoked.

Here's a simple web application:

class Main extends RequestRouter {
  get("/") = "Hello world!"
  get("/posts/:id") = "Post #" + uri("id")
  post("/form") = {
    // Do some work
    // . . .
    // Render FreeMarker template:
    ftl("/done.ftl")
  }
}

Of course, the capabilities of Web framework are not limited to responding to HTTP methods and matching URLs. Check out the Circumflex Web Framework page for detailed overview.

ORM

What can possibly be better than designing the domain model using the domain specific language that closely resembles the data definition language of SQL databases?

class City extends Record[City] {
  val name = "name" TEXT
  val country = "country_id" REFERENCES(Country) ON_DELETE CASCADE ON_UPDATE CASCADE
  override def toString = name.getOrElse("Unknown")
}

object City extends Table[City]

class Country extends Record[Country] {
  val code = "code" VARCHAR(2) DEFAULT("'ch'")
  val name = "name" TEXT
  def cities = inverse(City.country)
  override def toString = name.getOrElse("Unknown")
}

object Country extends Table[Country] {
  INDEX("country_code_idx", "LOWER(code)") USING "btree" UNIQUE
}

But still it is nothing comparing to object-oriented querying:

// Prepare the relations that will participate in queries:
val ci = City as "ci"
val co = Country as "co"
// Select all russian cities, return Seq[City]:
SELECT (ci.*) FROM (ci JOIN co) WHERE (co.code LIKE "ru") ORDER_BY (ci.name ASC) list
// Select countries with corresponding cities, return Seq[(Country, City)]:
SELECT (co.*, ci.*) FROM (co JOIN ci) list
// Select countries and count their cities, return Seq[(Country, Int)]:
SELECT (co.*, COUNT(ci.id)) FROM (co JOIN ci) GROUP_BY (co.*) list

Circumflex ORM also features lazy and eager fetching strategies for associations, complex queries, including subqueries of all kinds, data manipulation statements (INSERT .. SELECT, UPDATE and DELETE), set operations between queries (UNION, INTERSECT, EXCEPT), transaction-scoped caching, xml data import, schema generation with Maven plugin and arbitrary projections.

For more information, please check out the Circumflex ORM page.

Markdown

The infamous text-to-html conversion tool for writers, Markdown, is now available for Scala users with some extensions and improved performance. The usage is pretty simple:

val html = Markdown(text)

You are welcome to try it online!

Freemarker

Circumflex Freemarker module brings the power of the most advanced Java templating language, Freemarker to Scala. Due to the fact that Freemarker templates can effectively render any possible content, the Freemarker is considered the main view technology for Circumflex Web Framework.

Docco

Circumflex Docco is a port of Docco Project for Scala. The ideas of documenting open-source Scala programs in Docco style are under evaluation for now, but you still might want to try it and let us know, what you think about it.

Why Circumflex?

  • Circumflex components require minimum initial configuration, while still allowing developers to easily override defaults if necessary.
  • Circumflex is based on Scala. It has all the benefits of Scala. It runs on the JVM. It is fast. It is concise.
  • Circumflex does not try to solve all the problems a developer might ever face. It maintains a minimal features set, allowing developers to choose the tools and libraries that best suit their particular needs.
  • Circumflex is designed to use the powers of the Apache Maven 2 software management platform. Adding Circumflex components to your project is a matter of few more lines in your pom.xml.
  • All Circumflex components are designed to maximize the ease-of-use and clarity of your code. The development process with Circumflex is intuitive and extremely productive.
  • Circumflex is completely free, with a BSD-style license.

Quick start

Use With Existing Projects

If you already have a project and wish to use one of the Circumflex components, just add the corresponding dependency to your project's pom.xml:

<properties>
  <cx.version><!-- desired version --></cx.version>
</properties>
<dependencies>
  <!-- Circumflex Web Framework -->
  <dependency>
    <groupId>ru.circumflex</groupId>
    <artifactId>circumflex-core</artifactId>
    <version>{cx.version}</version>
  </dependency>
  <!-- Circumflex ORM -->
  <dependency>
    <groupId>ru.circumflex</groupId>
    <artifactId>circumflex-orm</artifactId>
    <version>{cx.version}</version>
  </dependency>
  <!-- Circumflex Freemarker Views -->
  <dependency>
    <groupId>ru.circumflex</groupId>
    <artifactId>circumflex-ftl</artifactId>
    <version>{cx.version}</version>
  </dependency>
  <!-- Circumflex Markdown -->
  <dependency>
    <groupId>ru.circumflex</groupId>
    <artifactId>circumflex-md</artifactId>
    <version>{cx.version}</version>
  </dependency>
  <!-- Circumflex Docco -->
  <dependency>
    <groupId>ru.circumflex</groupId>
    <artifactId>circumflex-docco</artifactId>
    <version>{cx.version}</version>
  </dependency>
</dependencies>

Note that all Circumflex components should share the same version. Check out the Central Maven Repository to determine the latest version of Circumflex.

Create New Project

As soon as Circumflex is built, you are ready to create your first project. Change to the directory where you store your projects, and run:

$ mvn archetype:generate

Choose the circumflex-archetype from your local catalog:

Choose archetype:
1: local -> circumflex-archetype (Circumflex Application Archetype)
2: internal -> . . .
Choose a number:  (1/2/3/ . . .) 17: : 1

Provide basic information about your project:

Define value for groupId: : com.myapp
Define value for artifactId: : myapp
Define value for version:  1.0-SNAPSHOT: : 1.0
Define value for package:  com.myapp: :

After you confirm your choice, a simple Circumflex application will be created. To run it, go to your project root (it matches the artifactId that you specified above) and execute the following:

$ mvn compile jetty:run

The following lines indicate that your application is ready to serve requests:

[INFO] Started Jetty Server
[INFO] Starting scanner at interval of 5 seconds.

Now you may visit your application at http://localhost:8180.

Build From Sources

You can obtain the latest Circumflex sources at GitHub:

$ git clone git://github.com/inca/circumflex.git

Circumflex, like all Scala applications, is compiled into Java VM bytecode. Make sure that the latest Java 6 SDK is installed on your system.

Circumflex uses Apache Maven 2 for build management. If you don't already have Maven 2, install it. Note that some operating systems (e.g. Mac OS X 10.5 and higher) are shipped with Maven 2 by default. On some systems it is also preferrable to install Maven 2 via package managers. For example, on Debian or Ubuntu systems you can install Maven 2 by executing the following line:

$ sudo apt-get install maven2

If you are unfamiliar with Maven, you should probably read the Maven in 5 Minutes article or Getting Started Guide.

Once you are ready to build, execute the following in the Circumflex root directory:

$ mvn clean install

After the build has successfully finished, Circumflex with all its dependencies will be available in your local Maven 2 repository (it may take a while to download dependencies the first time).

Contribute

Circumflex is actively being developed. It is very young project, and it needs your help and support to grow strong. You can help make the Circumflex project better in following ways:

You can also help Circumflex get popular by placing following link to sites you've built with Circumflex:

Here's the markup:

<a href="http://circumflex.ru" title="I've been created with Circumflex!">
  <img src="http://circumflex.ru/img/cx-thanks.png" alt="I've been created with Circumflex!"/>
</a>

We are highly appreciating your help!