index.html

---
layout: default
animateHeader: true
title: Scaldi - Lightweight Scala Dependency Injection Library
---

<div class="jumbotron">
  <div class="main-spacer visible-xs"></div>
  <div class="container">
    <h1>Scal<span class="di">di</span></h1>
    <p>Lightweight Scala Dependency Injection Library</p>
    <p class="top-description">
      Scaldi provides simple and elegant way to do dependency injection in Scala. By using expressive power of the Scala language
      it defines intuitive and idiomatic DSL for binding and injecting dependencies. It is very extensible library, so you can easily extend or customize
      almost any aspect of it. Some of the more unique Scaldi features are advanced module composition and conditional bindings which definitely will
      help you build all kinds of applications - from small command-line tools to big non-trivial web applications. Not to mention Scaldi also nicely integrates with Akka and Play.
    </p>
  </div>
</div>

<section>
  <div class="container">
    <div class="row">
      <div class="col-md-4">
        <h2>Discover</h2>
        <p>Read the documentation and learn how you can use scaldi in your project.</p>
      </div>

      <div class="col-md-4">
        <h2>Discuss</h2>
        <p>Have any ideas or questions? There are many places where you can share and discuss them with others.</p>
      </div>

      <div class="col-md-4" style="padding-bottom: 0">
        <h2>Contribute</h2>
        <p>If you like the project and want to contribute, then there are plenty ways to do so. Any ideas, improvements or bugfixes are very welcome! Just fork it now and start implementing new cool stuff :)</p>
      </div>
    </div>

    <div class="row">
      <div class="col-md-4">
        <a class="btn btn-success" role="button" href="{{"/learn" | prepend: site.baseurl}}">
          <i class="fa fa-graduation-cap fa-lg top-icon"></i>
          <span>Learn</span>
        </a>
      </div>
      <div class="col-md-4">

        <a class="btn btn-success" role="button" href="{{"/community" | prepend: site.baseurl}}">
          <i class="fa fa-comments-o fa-lg top-icon"></i>
          <span>Community</span>
        </a>
      </div>

      <div class="col-md-4">
        <a class="btn btn-success" role="button" href="{{site.link.scaldi-github}}" target="_blank">
          <i class="fa fa-github fa-lg top-icon"></i>
          <span>Fork</span>
        </a>
      </div>
    </div>
  </div>
</section>

<section style="padding-top: 0px">
  <div class="container">
    <div class="row">
      <div class="col-md-12">
        <h2>Getting a Taste of Scaldi</h2>
      </div>
    </div>

    <div class="row">
      <div class="col-md-6">
        <h3>Define Bindings</h3>
        <p>Scaldi provides nice DSL for defining the bindings</p>
        <p>
{% highlight scala %}
class UserModule extends Module {
  bind [MessageService] to new OfficialMessageService

  binding identifiedBy "greeting.official" to "Welcome"
}
{% endhighlight %}
        </p>
        <a role="button" href="{{"/learn/#define-bindings" | prepend: site.baseurl}}">
          <span>Learn more about bindings</span>
        </a>
      </div>
      <div class="col-md-6">
        <h3>Inject Bindings</h3>
        <p>With neat DSL for for injecting them</p>
        <p>
{% highlight scala %}
class OfficialMessageService(implicit inj: Injector)
          extends MessageService with Injectable {

  val officialGreeting =
    inject [String] (identified by "greeting.official")

  def getGreetMessage(name: String) =
    s"$officialGreeting, $name!"
}
{% endhighlight %}
        </p>
        <a role="button" href="{{"/learn/#inject-bindings" | prepend: site.baseurl}}">
          <span>Learn more about injection</span>
        </a>
      </div>
    </div>
  </div>
</section>

<section class="play-section">
  <div class="container">
    <div class="row">
      <div class="col-md-4">
        <img src="{{"/assets/img/play_reverse.svg" | prepend: site.baseurl}}" title="play" class="integration-logo">
      </div>
      <div class="col-md-8">
        <h2>Play Integration</h2>
        <p>Scaldi also comes with the play framework support. Start using scaldi in a play application is as simple as configuring application loader and modules in <span class="class-name">application.conf</span>:</p>
        <p>
{% highlight scala %}
play.application.loader = scaldi.play.ScaldiApplicationLoader

play.modules.enabled += modules.MyModule
play.modules.enabled += scaldi.play.ControllerInjector
{% endhighlight %}
        </p>
        <p>Play now uses scaldi for dependency injection. From now on you can use scaldi to inject/bind bindings in your controllers as classes:</p>
        <p>
{% highlight scala %}
class Application(implicit inj: Injector) extends Controller with Injectable {
  val messageService = inject [MessageService]

  def index = Action {
    Ok(views.html.index(messageService.getGreetMessage("Test User")))
  }
}
{% endhighlight %}
        </p>
        <a class="btn btn-success btn-sm" role="button" href="{{"/learn/#play-integration" | prepend: site.baseurl}}">
          <span>Learn more about play integration</span>
        </a>
      </div>
    </div>
  </div>
</section>

<section>
  <div class="container">
    <div class="row">
      <div class="col-md-12">
        <h2>Feature Highlights</h2>
      </div>
    </div>

    <div class="row">
      <div class="col-md-6">
        <h3>Injector Composition</h3>
        <p>You can easily split bindings between different modules and then compose them together</p>
        <p>
{% highlight scala %}
def tokenModule = new Module {
  bind [Tokens] to new TokenRepo(db = inject [Database])
}

def dbModule = new Module {
  bind [Database] to new Riak
}

def appModule = tokenModule :: dbModule
{% endhighlight %}
        </p>
        <a role="button" href="{{"/learn/#injector-composition" | prepend: site.baseurl}}">
          <span>Learn more about composition</span>
        </a>
      </div>
      <div class="col-md-6">
        <h3>Constructor Injection</h3>
        <p>Scaldi provides an <span class="class-name">injected</span> macro, which will inject all constructor arguments for you:</p>
        <p>
{% highlight scala %}
class TokenRepo(db: Database, met: Metrics) extends Tokens

def tokenModule = new Module {
  bind [Tokens] to injected [TokenRepo]
}
{% endhighlight %}
        </p>
        <p>You can even override injection mechanism on argument level:</p>
        <p>
{% highlight scala %}
def tokenModule = new Module {
  bind [Tokens] to injected [TokenRepo] (
    'met -> inject [Metrics] (identified by 'statsd))
}
{% endhighlight %}
        </p>
        <a role="button" href="{{"/learn/#constructor-injection" | prepend: site.baseurl}}">
          <span>Learn more about constructor injection</span>
        </a>
      </div>
    </div>

    <div class="row">
      <div class="col-md-6">
        <h3>Binding Lifecycle</h3>
        <p>Bindings may have lifecycle</p>
        <p>
{% highlight scala %}
class MyModule extends Module {
  bind [ActorSystem] to
  ActorSystem("ScaldiExample") destroyWith (_.shutdown())

  bind [Database] to new Mongo initWith (_.start())
}
{% endhighlight %}
        </p>
        <a role="button" href="{{"/learn/#binding-lifecycle" | prepend: site.baseurl}}">
        <span>Learn more about lifecycle</span>
        </a>
      </div>
      <div class="col-md-6">
        <h3>Testing</h3>
        <p>You can override bindings in order to mock parts of the application</p>
        <p>
{% highlight scala %}
def mocksModule = new Module {
  bind [Database] to new InMemoryDb
}

implicit val testModule = mocksModule :: appModule
{% endhighlight %}
        </p>
        <a role="button" href="{{"/learn/#testing" | prepend: site.baseurl}}">
        <span>Learn more about testing</span>
        </a>
      </div>
    </div>

    <div class="row">
      <div class="col-md-6">
        <h3>Conditions</h3>
        <p>Bindings may have conditions associated with them</p>
        <p>
{% highlight scala %}
class UserModule extends Module {
  bind [MessageService] when (inDevMode or inTestMode) to
    new SimpleMessageService

  bind [MessageService] when inProdMode to
    new OfficialMessageService
}
{% endhighlight %}
        </p>
        <p>and it's pretty straightforward to define new conditions</p>
        <p>
{% highlight scala %}
def inDevMode(implicit inj: Injector) = {
  val mode = inject [Mode]
  Condition(mode == Dev)
}
{% endhighlight %}
        </p>
        <a role="button" href="{{"/learn/#conditions" | prepend: site.baseurl}}">
          <span>Learn more about conditions</span>
        </a>
      </div>
      <div class="col-md-6">
        <h3>Generics</h3>
        <p>You can bind things like functions, lists or maps</p>
        <p>
{% highlight scala %}
binding identifiedBy "intAdder" to
  ((a: Int, b: Int) => a + b)

binding identifiedBy "mapping" to Map(
  "scala" -> "http://scala-lang.org",
  "play" -> "http://www.playframework.com",
  "akka" -> "http://akka.io"
)
{% endhighlight %}
        </p>
        <p>and then inject them</p>
        <p>
{% highlight scala %}
val intAdder = inject [(Int, Int) => Int]
val mapping = inject [Map[String, String]]
{% endhighlight %}
        </p>
      </div>
    </div>

    <div class="row">
      <div class="col-md-6">
        <h3>JSR 330 Support</h3>
        <p>For seamless integration with other libraries or existing codebase.</p>
        <p>
{% highlight scala %}
def carModule = new Module {
  bind [Car] to annotated [Convertible]
  bind [Seat] identifiedBy qualifier [Drivers]
    to annotated [DriversSeat]
}

implicit val injector =
  carModule :: new OnDemandAnnotationInjector

val car = inject [Car]
{% endhighlight %}
        </p>
        <a role="button" href="{{"/learn/#jsr-330-support" | prepend: site.baseurl}}">
          <span>Learn more about JSR 330 support</span>
        </a>
      </div>
      <div class="col-md-6">
        <h3>Extensibility</h3>
        <p>Extend almost any part of the library, including</p>
        <ul>
          <li><span class="class-name">Injector</span></li>
          <li><span class="class-name">Condition</span></li>
          <li><span class="class-name">Binding</span> and <span class="class-name">BindingWithLifecycle</span></li>
          <li><span class="class-name">Identifier</span> - create your own and define how they match</li>
        </ul>
        <p>Some parts of the library are implemented as a type classes</p>
        <ul>
          <li><span class="class-name">CanCompose</span> - defines how <span class="class-name">Injector</span>s can be composed together</li>
          <li><span class="class-name">CanBeIdentifier</span></li>
        </ul>
      </div>
    </div>
  </div>
</section>

<section class="akka-section">
  <div class="container">
    <div class="row">
      <div class="col-md-8">
        <h2>Akka Integration</h2>
        <p>
          With <span class="class-name">scaldi-akka</span> you can inject
          <span class="class-name">ActorRef</span>s and <span class="class-name">Props</span> with
          <span class="class-name">injectActorProps</span> and <span class="class-name">injectActorRef</span>.
          Actors themselves can be defined in scaldi module.
        </p>
        <p>
{% highlight scala %}
class Receptionist(implicit inj: Injector) extends Actor with AkkaInjectable {
  val orderProcessorProps = injectActorProps [OrderProcessor]
  val priceCalculator = injectActorRef [PriceCalculator]

  def receive = {
    case PlaceOrder(userName, itemId, netAmount) =>
      val processor = context.actorOf(orderProcessorProps)
      // ...
  }
}
{% endhighlight %}
        </p>
        <a class="btn btn-primary btn-sm" role="button" href="{{"/learn/#akka-integration" | prepend: site.baseurl}}">
          <span>Learn more about akka integration</span>
        </a>
      </div>
      <div class="col-md-4">
        <img src="{{"/assets/img/akka_icon_reverse.svg" | prepend: site.baseurl}}" title="akka" class="integration-logo">
      </div>
    </div>
  </div>
</section>

<section>
  <div class="container">
    <div class="row">
      <div class="col-md-12">
        <h2>Getting Started</h2>
        <p>Just include scaldi dependency in the SBT build and you are ready to go:</p>
        <p>
{% highlight scala %}
libraryDependencies += "org.scaldi" %% "scaldi" % "{{site.version.scaldi}}"
{% endhighlight %}
        </p>
        <p>If you want to include scaldi into the play application, then <span class="class-name">scaldi-play</span> would probably be more suitable for you</p>
        <p>
{% highlight scala %}
libraryDependencies += "org.scaldi" %% "scaldi-play" % "{{site.version.scaldi-play}}"
{% endhighlight %}
        </p>
        <p>Then you can just define application loader and your modules in the <span class="class-name">application.conf</span> like this:</p>
        <p>
{% highlight scala %}
play.application.loader = scaldi.play.ScaldiApplicationLoader

play.modules.enabled += "modules.MyModule"
play.modules.enabled += "scaldi.play.ControllerInjector"
{% endhighlight %}
        </p>
        <p><strong>Play 2.3.x</strong> is still supported, you just need to use <strong>scaldi-play-23</strong> instead:</p>
        <p>
          {% highlight scala %}
          libraryDependencies += "org.scaldi" %% "scaldi-play-23" % "{{site.version.scaldi-play-23}}"
          {% endhighlight %}
        </p>
        <p>For the akka applications, <span class="class-name">scaldi-akka</span> is the way to go:</p>
        <p>
{% highlight scala %}
libraryDependencies += "org.scaldi" %% "scaldi-akka" % "{{site.version.scaldi-akka}}"
{% endhighlight %}
        </p>
        <p>If you are integrating or migrating existing apps that use JSR 330 annotations, then <span class="class-name">scaldi-jsr330</span> is the right choice:</p>
        <p>
          {% highlight scala %}
          libraryDependencies += "org.scaldi" %% "scaldi-jsr330" % "{{site.version.scaldi-jsr330}}"
          {% endhighlight %}
        </p>
        <br>
        <p>After the initial setup you can read <a href="{{"/learn" | prepend: site.baseurl}}">some documentation</a> or look at <a target="_blank" href="{{site.link.scaldi-presentation}}">scaldi presentation slides</a>.</p>
        <p>If you prefer more hands-on approach, then you may be interested in two example projects which you can play with:</p>
        <ul>
          <li>Scaldi Play 2.4 Example (<a target="_blank" href="{{site.link.scaldi-play-example-github}}">GitHub</a>, <a target="_blank" href="{{site.link.scaldi-play-example-template}}">Typesafe activator template</a>)</li>
          <li>Scaldi Play 2.3 Example (<a target="_blank" href="{{site.link.scaldi-play-example-github-23}}">GitHub</a>, <a target="_blank" href="{{site.link.scaldi-play-example-blog}}">Blog</a>, <a target="_blank" href="{{site.link.scaldi-play-example-template-23}}">Typesafe activator template</a>)</li>
          <li>Scaldi Akka Example (<a target="_blank" href="{{site.link.scaldi-akka-example-github}}">GitHub</a>, <a target="_blank" href="{{site.link.scaldi-akka-example-blog}}">Blog</a>, <a target="_blank" href="{{site.link.scaldi-akka-example-template}}">Typesafe activator template</a>)</li>
        </ul>
      </div>
    </div>
  </div>
</section>