Packages

•  package root

  Definition Classes

  root

•  package net

  Definition Classes

  root

•  package liftweb

  Definition Classes

  net

•  package common

  Definition Classes

  liftweb

•  sealed abstract class Box [+A] extends Product with Serializable

  The Box class is a container which is able to declare if it is Full (containing a single non-null value) or EmptyBox.

  The Box class is a container which is able to declare if it is Full (containing a single non-null value) or EmptyBox. An EmptyBox, or empty, can be the Empty singleton, Failure or ParamFailure. Failure and ParamFailure contain information about why the Box is empty including exception information, possibly chained Failures and a String message.

  This serves a similar purpose to the Option class from Scala standard library but adds several features:

  • You can transform it to a Failure object if it is Empty (with the ?~ or failMsg method).
  • You can chain failure messages on Failures (with the ?~! or compoundFailMsg method).
  • You can "run" a function on a Box, with a default to return if the box is Empty:

  val littleTeddyBears: Box[Int] = Full(10)
  littleTeddyBears.run("and then there were none") { (default: String, teddyBears: Int) =>
    s"$teddyBears little teddy bears"
  } // => 10 little teddy bears
  
  val updatedTeddyBears: Box[Int] = Empty
  littleTeddyBears.run("and then there were none") { (default: String, teddyBears: Int) =>
    s"$teddyBears little teddy bears"
  } // => and then there were none

  • You can "pass" a Box to a function for side effects:

  val littleTeddyBears: Box[Int] = Full(10)
  
  doSomething(
    littleTeddyBears $ { teddyBears: Box[Int] =>
      println("Are there any?")
      println(teddyBears openOr 0)
    }
  ) // doSomething gets a Box[Int] as well

  Exceptions and Empty Box Handling

  If you grew up on Java, you're used to Exceptions as part of your program logic. The Scala philosophy and the Lift philosophy is that exceptions are for exceptional conditions such as failure of an external resource (e.g., your database goes offline) rather than simply indicating that a parameter wasn't supplied or couldn't be parsed.

  Lift's Box and Scala's Option provide mechanisms for being explicit about a value existing or not existing rather than relying on a reference being not-null. However, extracting a value from a Box should be done correctly. Available options are:

  • Using a for comprehension, especially for multiple boxes:

  val loggedInUser: Box[User] =
    for {
      username <- possibleUsername
      password <- possiblePassword
      user <- User.find("username" -> username)
      if User.checkPassword(password, user.password)
    } yield {
      user
    }

  • Using map, flatMap, filter, and foreach (for comprehensions use these under the covers):

  val fullName: Box[String] =
    loggedInUser.map { user =>
      user.name + " (" + user.nickname + ")"
    }
  val bestFriend: Box[User] =
    loggedInUser.flatMap { user =>
      UserFriends.find(user.bestFriend.id)
    }
  val allowedUser: Box[User] =
    loggedInUser.filter(_.canAccess_?(currentPage))
  
  fullName.foreach { name =>
    logger.info(s"User $name is in the building.")
  }

  • Using pattern-matching (a good way to deal with Failures):

  val loginMessage: String =
    loggedInUser match {
      case Full(user) =>
        "Login successful!"
      case Failure(message, _, _) =>
        s"Login failed: $message"
      case Empty =>
        s"Unknown failure logging in."
    }

  • For comparisons (e.g., in tests), use == and ===:

  loggedInUser must_== Full(mockUser)
  (loggedInUser === mockUser) must beTrue

  Definition Classes

  common

• WithFilter

net.liftweb.common.Box

WithFilter 