common

Type Members

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
```
class BoxJBridge extends AnyRef

A bridge to make using Lift Box from Java easier.
A bridge to make using Lift Box from Java easier.
In particular, provides access to the Box companion object so that functions like legacyNullTest can be used easily from Java, as well as access to the Empty singleton so that empty values can be created easily from Java.
sealed trait BoxOrRaw[T] extends AnyRef

Sometimes it's convenient to access either a Box[T] or a T.
Sometimes it's convenient to access either a Box[T] or a T. If you specify BoxOrRaw[T], either a T or a Box[T] can be passed and the "right thing" will happen, including nulls being treated as Empty.
sealed trait BoxTrait extends AnyRef

Implementation for the Box singleton.
trait Boxable[T] extends AnyRef

A trait that a class can mix into itself to indicate that it can convert itself into a Box.
final case class BoxedBoxOrRaw[T](box: Box[T]) extends BoxOrRaw[T] with Product with Serializable

The BoxOrRaw that represents a boxed value.
trait CommonLoanWrapper extends AnyRef

A component that takes action around some other functionality.
A component that takes action around some other functionality. It may choose to execute or not execute that functionality, but should not interpret or change the returned value; instead, it should perform orthogonal actions that need to occur around the given functionality. A canonical example is wrapping an SQL transaction around some piece of code.
As an example, this trait defines the principal contract for function objects that wrap the processing of HTTP requests in Lift.
final case class ConstStringFunc(str: String) extends StringFunc with Product with Serializable

See StringFunc.
final class DoNotCallThisMethod extends AnyRef

Used as a return type for certain methods that should not be called.
Used as a return type for certain methods that should not be called. One example is the get method on a Lift Box. It exists to prevent client code from using .get as an easy way to open a Box, so it needs a return type that will match no valid client return types.
sealed abstract class EmptyBox extends Box[Nothing] with Serializable

An EmptyBox is a Box containing no value.
An EmptyBox is a Box containing no value. It can sometimes carry additional failure information, as in Failure and ParamFailure.
sealed trait ExcludeThisType[A, B] extends AnyRef

Encoding for "A is not a subtype of B".
sealed case class Failure(msg: String, exception: Box[Throwable], chain: Box[Failure]) extends EmptyBox with Product with Serializable

A Failure is an EmptyBox with an additional failure message explaining the reason for its being empty.
A Failure is an EmptyBox with an additional failure message explaining the reason for its being empty. It can also optionally provide an exception and/or a chain of previous Failures that may have caused this one.
trait ForwardableActor[From, To] extends AnyRef

Interface for an actor that can internally forward received messages to other actors.
final case class Full[+A](value: A) extends Box[A] with Product with Serializable

Full is a Box that contains a value.
final class Func extends AnyRef
trait Func0[Z] extends AnyRef
trait Func1[A, Z] extends AnyRef
trait Func2[A, B, Z] extends AnyRef
trait Func3[A, B, C, Z] extends AnyRef
trait Func4[A, B, C, D, Z] extends AnyRef
class FuncJBridge extends AnyRef

Bridges from Java functions to Scala functions.
Bridges from Java functions to Scala functions.
The implicits defined here allow Scala code to interact seamlessly between the Java function-like interfaces and the Scala function interfaces for various function arities.
In particular, there is a pair of implicits for each arity of function from 0 to 4. There is one implicit (called lift) from the Java function type to the corresponding Scala function type and one (called drop) from the Scala function type to the corresponding Java function type.
trait GenericActor[+R] extends TypedActor[Any, R]

Generic Actor interface.
Generic Actor interface. Can receive any type of message. Can return (via !! and !?) messages of type R.
class LRUMap[K, V] extends LinkedListElem[K, V]

Implements an LRU Hashmap.
Implements an LRU Hashmap. Given a size, this map will evict the least recently used item(s) when new items are added.
Note that LRUMap is not thread-safe.
trait LazyLoggable extends AnyRef

If you mix this into your class, you will get a protected logger instance lazy val that will be a Logger instance.
If you mix this into your class, you will get a protected logger instance lazy val that will be a Logger instance.
Useful for mixing into objects that are created before Lift has booted (and thus Logging is not yet configured).
trait Loggable extends AnyRef

If you mix this into your class, you will get a protected logger instance val that will be a Logger instance.
trait Logger extends AnyRef

Logger is a thin wrapper on top of an SLF4J Logger.
Logger is a thin wrapper on top of an SLF4J Logger.
The main purpose is to utilize Scala features for logging.
Note that the dynamic type of "this" is used when this trait is mixed in.
This may not always be what you want. If you need the static type, you have to declare your own Logger:
```
class MyClass {
  val logger = Logger(classOf[MyClass])
}
```

final class ParamFailure[T] extends Failure with Serializable

A ParamFailure is a Failure with an additional type-safe parameter that can allow an application to store other information related to the failure.

For example:

val loggedInUser =
  for {
    username ?~ "Missing username" ~> "error.missingUser"
    password ?~! "Missing password" ~> "error.missingPassword"
    user <- User.find("username" -> username)
    if User.checkPassword(password, user.password)
  } yield {
    user
  }

loggedInUser match {
  case ParamFailure(message, _, _, i18nKey: String) =>
    tellUser(i18n(i18nKey))
  case Failure(message, _, _) =>
    tellUser(failureMessage)
  case Empty =>
    tellUser("Unknown login failure.")
  case _ =>
    tellUser("You're in!")
}

final case class RawBoxOrRaw[T](raw: T) extends BoxOrRaw[T] with Product with Serializable

The BoxOrRaw that represents a raw value.
final case class RealStringFunc(func: () ⇒ String) extends StringFunc with Product with Serializable

See StringFunc.
trait SimpleActor[-T] extends AnyRef

The simple definition of an actor.
The simple definition of an actor. Something that can be sent a message of type T.
final case class SimpleList[T](underlying: List[T]) extends List[T] with Product with Serializable

An immutable singly linked list that uses the Scala List class as backing store, but is Java-friendly as a java.util.List.
An immutable singly linked list that uses the Scala List class as backing store, but is Java-friendly as a java.util.List. Note however that since it is immutable, you have to capture the results of addition/removal operations.
The typical mutating methods like add, set, clear, and remove are all unsupported, as are mutating methods on its iterators, since this collection is immutable.
final case class SimpleVector[T](underlying: Vector[T]) extends List[T] with Product with Serializable

An immutable vector that uses the Scala Vector class as backing store, but is Java-friendly as a java.util.List.
An immutable vector that uses the Scala Vector class as backing store, but is Java-friendly as a java.util.List. Note however that since it is immutable, you have to capture the results of addition/removal operations.
The typical mutating methods like add, set, clear, and remove are all unsupported, as are mutating methods on its iterators, since this collection is immutable.

See also
"Scala's Collection Library overview" section on Vectors for more information.
trait SimplestActor extends SimpleActor[Any]

An Actor that can receive a message of any type.
trait SimplestGenericActor extends GenericActor[Any]

Generic Actor interface.
Generic Actor interface. Can receive any type of message. Can return (via !! and !?) messages of any type.
sealed trait StringFunc extends AnyRef

This trait is used to unify ()=>String and String into one type.
This trait is used to unify ()=>String and String into one type. It is used in conjunction with the implicit conversions defined in its companion object.
sealed trait StringOrNodeSeq extends AnyRef

This trait is used to unify Strings and NodeSeqs into one type.
This trait is used to unify Strings and NodeSeqs into one type. It is used in conjuction with the implicit conversions defined in its companion object.
trait Tryo extends AnyRef
trait TypedActor[-T, +R] extends SimpleActor[T]

An Actor that can receive messsages of type T and return responses of type R.
class WrappedLogger extends Logger

Represents a Logger backed by an SLF4J Logger.
final case class ConstNodeSeqFunc(ns: NodeSeq) extends NodeSeqFunc with Product with Serializable

The case class that holds the NodeSeq constant.
The case class that holds the NodeSeq constant.

Annotations
@deprecated
Deprecated
(Since version 3.0) Lift now mostly uses NodeSeq=>NodeSeq transformations rather than NodeSeq constants; consider doing the same.
sealed trait NodeSeqFunc extends AnyRef

This trait is used to unify ()=>NodeSeq and NodeSeq into one type.
This trait is used to unify ()=>NodeSeq and NodeSeq into one type. It is used in conjunction with the implicit conversions defined in its companion object.

Annotations
@deprecated
Deprecated
(Since version 3.0) Lift now mostly uses NodeSeq=>NodeSeq transformations rather than NodeSeq constants; consider doing the same.
final case class RealNodeSeqFunc(func: () ⇒ NodeSeq) extends NodeSeqFunc with Product with Serializable

The case class that holds a NodeSeq function.
The case class that holds a NodeSeq function.

Annotations
@deprecated
Deprecated
(Since version 3.0) Lift now mostly uses NodeSeq=>NodeSeq transformations rather than NodeSeq constants; consider doing the same.

Value Members

object Box extends BoxTrait with Tryo with Serializable

The Box companion object provides methods to create a Box from:
The Box companion object provides methods to create a Box from:
- an Option
- a List
- any AnyRef object, converting null to Empty and anything else to a Full with the given object
It also provides implicit methods to transform Option to Box, Box to Iterable, and Box to Option.
object BoxOrRaw

Companion object with implicit conversions to allow BoxOrRaw[T] to masquerade as the appropriate types.
object CombinableBox

Via an HList containing a collection of Box, either generates an HList of the things (unboxed) or a List[Failure].
object CommonLoanWrapper
object Empty extends EmptyBox with Product with Serializable

Singleton object representing a completely empty Box with no value or failure information.
object ExcludeThisType

The companion object to ExcludeThisType.
The companion object to ExcludeThisType. This allows one of specify that a type is not a subtype of another type.
Based on work by Miles Sabin.
object Failure extends Serializable

Companion object used to simplify the creation of a simple Failure with just a message.
object FuncJBridge extends FuncJBridge

object HLists

Basic support for heterogeneous lists, aka HLists.

An HList can be constructed like so:

import net.liftweb.common.HLists._

trait Base
case class Type1(value: String) extends Base
case class Type2(otherValue: String) extends Base

val myHList = Type1("Value") :+: Type2("Other Value") :+: HNil
myHList match {
  case firstThing :+: secondThing :+: HNil =>
    println(firstThing.value)
    println(secondThing.otherValue)
}

Above, we see that the HList preserved the value of the types of its members, otherwise we wouldn't have been able to fetch value and otherValue, respectively.

Trying the same thing with a list won't work:

val myList = Type1("Value") :: Type2("Other Value") :: Nil
myList match {
  case firstThing :: secondThing :: Nil =>
    // error: value value is not a member of Product with Serializable with Base
    println(firstThing.value)
}

This is because value is not defined in Base. The inferred type of the List has to be a common ancestor class or trait of Type1 and Type2, and no such type has a value method.

object Log4j

Configuration helpers for the log4j logging backend.
object Logback

Configuration helpers for the Logback logging backend.

object Logger

Provides some helpers to easily create Logger instances.

For example:

class MyClass {
  val logger = Logger(classOf[MyClass])
}

It can also be used to provide global setup for loggers created this way:

Logger.setup = Full(Logback.withFile(new URL("file:///path/to/config.xml")))

class MyClass {
  val logger = Logger(classOf[MyClass])

  logger.debug("Hello") // uses the above configuration
}

Last but not least, you can wrap chunks of code with particular Mapped Diagnostic Context values:

Logger.logWith("mykey" -> "value") {
  logger.debug("stuff") // has mykey set to value in the MDC
}
logger.debug("more stuff") // mykey is set to its previous value

object MDC

The Mapped Diagnostics Context can hold values per thread and output them with each logged output.
The Mapped Diagnostics Context can hold values per thread and output them with each logged output.
The logging backend needs to be configured to log these values.
object ParamFailure extends Serializable

Companion object used to simplify the creation of simple ParamFailures, as well as allow pattern-matching on the ParamFailure.
object StringFunc

Provides implicit conversions to the StringFunc trait.
Provides implicit conversions to the StringFunc trait. This allows using a String as a natural part of APIs that want to allow the flexibility of a ()=>String without having to write overloads for all methods that should accept both.
Lift's Menu API, for example, allows CSS classes to be defined either as a String or a ()=>String. The latter could use the current request and session state to do more interesting things than a hard-coded String would, while the former is simpler to use.
object StringOrNodeSeq

Provides implicit conversions to the StringOrNodeSeq trait, which can in turn be implicitly converted to NodeSeq.
Provides implicit conversions to the StringOrNodeSeq trait, which can in turn be implicitly converted to NodeSeq. This allows using a String as a natural part of NodeSeq APIs without having to explicitly wrap it in scala.xml.Text or having to write overloads for all methods that should accept both.
This is used in certain Lift APIs, for example, to accept either a String or more complex content. For example, a button can have either a simple label or complex HTML content. HTML APIs that can do this can accept a parameter of type StringOrNodeSeq to allow the user to pass either in as their needs dictate.

Deprecated Value Members

object NodeSeqFunc

Provides implicit conversions to the NodeSeqFunc trait.
Provides implicit conversions to the NodeSeqFunc trait. This allows using a NodeSeq as a natural part of APIs that want to allow the flexibility of a ()=>NodeSeq without having to write overloads for all methods that should accept both.

Annotations
@deprecated
Deprecated
(Since version 3.0) Lift now mostly uses NodeSeq=>NodeSeq transformations rather than NodeSeq constants; consider doing the same.

package common

Type Members

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

Exceptions and Empty Box Handling

class BoxJBridge extends AnyRef

sealed trait BoxOrRaw[T] extends AnyRef

sealed trait BoxTrait extends AnyRef

trait Boxable[T] extends AnyRef

final case class BoxedBoxOrRaw[T](box: Box[T]) extends BoxOrRaw[T] with Product with Serializable

trait CommonLoanWrapper extends AnyRef

final case class ConstStringFunc(str: String) extends StringFunc with Product with Serializable

final class DoNotCallThisMethod extends AnyRef

sealed abstract class EmptyBox extends Box[Nothing] with Serializable

sealed trait ExcludeThisType[A, B] extends AnyRef

sealed case class Failure(msg: String, exception: Box[Throwable], chain: Box[Failure]) extends EmptyBox with Product with Serializable

trait ForwardableActor[From, To] extends AnyRef

final case class Full[+A](value: A) extends Box[A] with Product with Serializable

final class Func extends AnyRef

trait Func0[Z] extends AnyRef

trait Func1[A, Z] extends AnyRef

trait Func2[A, B, Z] extends AnyRef

trait Func3[A, B, C, Z] extends AnyRef

trait Func4[A, B, C, D, Z] extends AnyRef

class FuncJBridge extends AnyRef

trait GenericActor[+R] extends TypedActor[Any, R]

class LRUMap[K, V] extends LinkedListElem[K, V]

trait LazyLoggable extends AnyRef

trait Loggable extends AnyRef

trait Logger extends AnyRef

final class ParamFailure[T] extends Failure with Serializable

final case class RawBoxOrRaw[T](raw: T) extends BoxOrRaw[T] with Product with Serializable

final case class RealStringFunc(func: () ⇒ String) extends StringFunc with Product with Serializable

trait SimpleActor[-T] extends AnyRef

final case class SimpleList[T](underlying: List[T]) extends List[T] with Product with Serializable

final case class SimpleVector[T](underlying: Vector[T]) extends List[T] with Product with Serializable

trait SimplestActor extends SimpleActor[Any]

trait SimplestGenericActor extends GenericActor[Any]

sealed trait StringFunc extends AnyRef

sealed trait StringOrNodeSeq extends AnyRef

trait Tryo extends AnyRef

trait TypedActor[-T, +R] extends SimpleActor[T]

class WrappedLogger extends Logger

final case class ConstNodeSeqFunc(ns: NodeSeq) extends NodeSeqFunc with Product with Serializable

sealed trait NodeSeqFunc extends AnyRef

final case class RealNodeSeqFunc(func: () ⇒ NodeSeq) extends NodeSeqFunc with Product with Serializable

Value Members

object Box extends BoxTrait with Tryo with Serializable

object BoxOrRaw

object CombinableBox

object CommonLoanWrapper

object Empty extends EmptyBox with Product with Serializable

object ExcludeThisType

object Failure extends Serializable

object FuncJBridge extends FuncJBridge

object HLists

object Log4j

object Logback

object Logger

object MDC

object ParamFailure extends Serializable

object StringFunc

object StringOrNodeSeq

Deprecated Value Members

object NodeSeqFunc

Ungrouped