common

package common

Ordering

Alphabetic

Visibility

Public
All

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.
trait BoxLogging extends AnyRef
Mix this trait in to get some low-cost implicits for logging boxes easily.
Mix this trait in to get some low-cost implicits for logging boxes easily. The consumer will need to implement a logBoxError method to log messages with an optional Throwable, as well as its related friends for trace, debug, info, and warn levels. This allows abstracting out where and what the actual logger is.
With this mixed in, boxes will have logFailure and logFailure methods. The first logs all Failures as well as Empty. The second logs only Failures and ParamFailures, treating Empty as a valid value. These both log their respective items at ERROR level. You can also use traceLog*, debugLog*, infoLog*, and warnLog* if you want to log at other levels (e.g., you can use infoLogFailure to log an Empty or Failure at INFO level).
All of these return the box unchanged, so you can continue to use it in for comprehensions, call openOr on it, etc.
There is an implementation for anyone who wants to use Lift's Loggable trait called LoggableBoxLogging. Another implementaiton is available for use with a plain SLF4J logger, SLF4JBoxLogging. You can also implement a version for any other logging adapter. Lastly, you can simply import BoxLogging._ to get the methods available at a top level; however, note that using them this way will lose information about where the log message came from.
Here is an example of how you might use this in system that executes a third- party service and notifies another system of failures.
```
val systemResult: Box[ServiceReturn] =
  system
    .executeService(true, requester)
    .map(...)
    .logFailure("Failed to execute service") match {
      case Full(content) =>
        content
      case failure: Failure =>
        otherSystem.notifyFailure(failure)
      case Empty =>
        otherSystem.notifyFailure(Failure("No idea what happened."))
    }
```
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 OptionImplicits
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
The bridge from various arity FuncX to Scala's function instances
trait Func0[Z] extends AnyRef
A zero argument function that returns something of type Z
trait Func1[A, Z] extends AnyRef
A one argument function that returns something of type Z
trait Func2[A, B, Z] extends AnyRef
A two argument function that returns something of type Z
trait Func3[A, B, C, Z] extends AnyRef
A three argument function that returns something of type Z
trait Func4[A, B, C, D, Z] extends AnyRef
A four argument function that returns something of type Z
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 LoggableBoxLogging extends BoxLogging with Loggable
A version of BoxLogging with a default implementation of logBoxError that logs to the logger provided by Lift's Loggable.
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 SLF4JBoxLogging extends BoxLogging
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 BoxLogging extends LoggableBoxLogging
A convenience singleton for BoxLogging that makes logFailure and logFailure available for all code after it's been imported as import com.elemica.common.BoxLogging._.
A convenience singleton for BoxLogging that makes logFailure and logFailure available for all code after it's been imported as import com.elemica.common.BoxLogging._. Logging done this way will come from BoxLogging, not from the class where the box was logged.
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.

Packages

common

package common

Type Members

Exceptions and Empty Box Handling

Value Members

Deprecated Value Members

Ungrouped

Packages

common 

package common

Type Members

Exceptions and Empty Box Handling

Value Members

Deprecated Value Members

Ungrouped

common