Type Members

1.  final class Configure extends AnyRef

   Reads values from application configuration resource

   Reads values from application configuration resource

   A configuration resource consists of a hierarchical set of properties. The resource uses a superset of the JSON format called HOCON to specify settings.

   Example configuration file:

   server {
     # The interface the server should bind to for servicing requests.
     # The default value of 0.0.0.0 forces the server to bind to all
     # interfaces on the machine.
     interface = 0.0.0.0
     interface = ${?SERVER_INTERFACE}
   
     # The port the server should bind to when accepting requests. The
     # default port used is 8000.
     port = 8000
     port = ${?SERVER_PORT}
   }

   Property values are read using the read method defined in this class:

   val result: Either[Error, (String, Int)] =
     for {
       config <- Configure()
       interface <- config.read[String]
       port <- config.read[Int]
     } yield (interface, port)

   The read method returns an Error if the property cannot be read as the type requested.

2.  trait ConfigureReader[A] extends AnyRef

   Reads a configuration value

   Reads a configuration value

   ConfigureReader is a type class that implements the read method on Configure. The method takes a configuration and key and extracts the key's value. The type of the key's value is determined by the type of the constructed ConfigureReader. A set of implicit instances implement common return types (e.g. String, Int, List[_]). It is possible to define your own reader, however the most common will already be available as part of the com.axiell.util.Implicits._ import.

   Example:

   implicit val stringForConfigureReader =
     new ConfigureReader[String] {
       def read[String](config: Configure, key: String): Result[String] =
         Try { configure.config.getString(key) }
          .fold(
            { exc => Left(Error("BadString", key).withException(exc)) },
            { Right(_) }
          )

   A

   return type of key value

3.  final case class Error extends Product with Serializable

   Contains a language independent error.

   Contains a language independent error.

   When an error occurs in a method it is useful to be able to return a description of what the error was, along with some context values associated with the error. In order to support internationalisation the error description should not contain a language specific string, but rather a code used to identify the error. Fortunately we can use the Message class to describe the error in a language independent way.

   The context for an error may include an optional exception, if the error was due to an exception, but it may also contain many other context specific values (e.g. file paths, error codes, counts, etc). In order to handle arbitrary context data Error contains an internal map where the key is an arbitrary label identifying the context and the value is the context data itself.

   The withProperty method allows an entry to be added to the internal map. For example, if an exception and a status code are to be associated with the error then the following code is required:

   Error("BadInt", value)
     .withProperty("exception", exc)
     .withProperty("status", 404)

   The labels exception and status are arbitrary and identify the kind of context data. The data itself can be any type that has an implicit ShowLocal and JsonLocal defined and in scope. The labels message and code are set to the error message and error code when the error is created.

   It is possible to retrieve context data by using the get method. The method takes the label to retrieve and the expected type of the data:

   Error("BadInt", value)
     .withProperty("status", 404)
     .get[Int]("status")

   will return the Int 404.

   A common paradigm, especially in functional programming is to have methods that may generate errors return either an Error or the return value. So it is common to see method return values like:

   def method[A]: Either[Error, A]

   The use of Either for return values is encouraged.

   Example:

   def method(value: String): Either[Error, Int] =
     Try { value.toInt }
       .fold(
         { exc =>
             Left(Error("BadInt", value).withProperty("exception", exc)
         },
         { Right(_) }
       )

   The method tries to convert a string to an integer value, which may result in an exception being thrown if the conversion fails.

   The showLocal method allows a language specific string for an Error to be output as a string. The method takes an implicit java.util.Locale identifying the language to be shown. The method is an extension method added by the ShowLocal type class.

   The jsonLocal method outputs the error as a JSON object where the map labels are the property names and the map values the property values. An implicit java.util.Locale is required for language specific values (e.g. Message). The method is an extension method added by the JsonLocal type class.

   The masonLocal method outputs the error as a JSON object conforming to the Mason Draft 2 specification. The method is an extension method.

   A number of extension methods are provided to set specific values with predefined labels, these include:

   • withException (label: exception)
   • withId (label: id)
   • withTime (label: time)
   • withHttpStatusCode (label: httpStatusCode)
   • withMessages (label: messages)
4.  final case class ErrorException(error: Error) extends Exception with Product with Serializable

   Wraps an Error with an Exception

   Wraps an Error with an Exception

   In some instances an exception needs to be thrown that contains a language independent error message. The language independent error message is represented by an Error. The getMessage() method returns the error message using the system default Locale. In most instances the catching code will unpack the error and use it.

   Example:

   def method(value: String): Int =
     Try { value.toInt }
       .fold(
         { _ => throw ErrorException(Error("BadInt", value)) },
         { _ }
       )

   The showLocal method can be used to generate a String containing the error properties along with a stack trace. The jsonLocal method produces a JSON object consisting of the error properties and the stack trace of where the exception was created.

   error

   Error to be wrapped in a Exception

5.  final class Formatter extends AnyRef

   Provides access to a set of language specific strings.

   Provides access to a set of language specific strings.

   A code is used support language independent strings. The code is effectively a label used to identify a language specified string in a resource bundle loaded when the class was created. The string extracted from the bundle may contain printf() style formatting markers. In order to satisfy the formatting markers a variable number of arguments are passed along with the string code.

6.  trait JsonLocal[-A] extends AnyRef

   Displays locale specific JSON string for any object.

   Displays locale specific JSON string for any object.

   JsonLocal is a type class that adds the jsonLocal extension method to any object. The method takes an implicit java.util.Locale defining the language to use for language specific strings. An implicit implementation of the JsonLocal trait must exist in scope for the method to be available.

   Example:

   val error = Error(MessageBundle("Errors"), "Bad Error")
   
   implicit val locale = Locale.ENGLISH
   error.jsonLocal
   error.jsonLocal(Locale.GERMAN)

   Output:

   {"message":"A bad error","code":"BadError"}
   {"message":"Ein schlimmer Fehler","code":"BadError"}

   The jsonLocal extension method can be defined for any class A provided an implementation of JsonLocal[A] exists implicitly and is in scope. The code below shows the implementation of JsonLocal[Error]:

   implicit val utilJsonLocalForError: JsonLocal[Error] =
     new JsonLocal[Error] {
       def jsonLocal(error: Error)(implicit locale: Locale): String = {
         error.map.toList.map { case (key, (value, format, _)) =>
           s""""${escape(key)}":${format.jsonLocal(value)}"""
         }
           .mkString("{", ",", "}")
       }
     }

   A

   type for which a language specific JSON string is generated

7.  final case class Message extends Product with Serializable

   Contains a language independent message.

   Contains a language independent message.

   In order to support internationalisation of applications it is necessary to provide a mechanism that allows a string to be generated in a language independent way. The Message class provides such a mechanism.

   A Message contains information used to extract a string and format it when it needs to be displayed. In order to display the string it is necessary to invoke the showLocal method passing in an implicit java.util.Locale. The locale determines what language is used to extract the string.

   A language independent string is identified by three things, namely:

   • bundle identifies a group of strings stored within the one resource
   • code indicates which string to extract from the bundle
   • args that are interpolated into the string when displayed

   Message objects may be passed around and the showLocal method only invoked when it is necessary to display the string in a language dependent way.

   Let's look at an example:

   class Messages_en extends java.util.ListResourceBundle {
     final override val getContents: Array[Array[AnyRef]] =
       Array(
         Array("BadValue", "The bad value is %s")
         ...
       )
   }
   
   class Messages_de extends java.util.ListResourceBundle {
     final override val getContents: Array[Array[AnyRef]] =
       Array(
         Array("BadValue", "Der falsche Wert ist %s")
         ...
       )
   }
   
   implicit val bundle = MessageBundle("Messages")
   val message = Message("BadValue", "abc123")
   
   implicit val locale = Locale.ENGLISH
   message.showLocal
   message.showLocal(Locale.GERMAN)

   Output:

   The bad value is abc123
   Der falsche Wert ist abc123

   The Messages_en class contains a mapping between the code used to identify a string and its English message, similarly Messages_de contains the same codes with the equivalent German message.

   The Message is created using an implicit MessageBundle identifying the base class name containing the translated strings. Since the translated strings contain a format marker (%s) an argument must be supplied along with the code when the Message is instantiated.

   The showLocal method is used when a Message is to be displayed. The method takes an implicit java.util.Locale identifying which language is to be shown. The method is an extension method added by the ShowLocal type class.

8.  final case class MessageBundle(name: String) extends Product with Serializable

   Identifies the class name containing string resources.

   Identifies the class name containing string resources.

   A bundle is a set of classes containing string resources. Each class in the set begins with the MessageBundle name and has a locale appended to it identifying the language of the strings it contains. A special case is the class name without any locale appended. If a locale specific class cannot be located then the class without the locale is appended.

   A bundle extends the java.util.ListResoruceBundle class and overrides the getContents method. The method returns an Array where each element is an array containing two elements. The first element is a code used to identify a string in a language independent way and the second is a language dependent string.

   Example:

   class com.acme.Messages extends java.util.ListResourceBundle {
     final override val getContents: Array[Array[Object]] =
       Array(
         Array("BadValue", "The bad value is %s")
         ...
       )
   }
   
   class com.acme.Messages_de extends java.util.ListResourceBundle {
     final override val getContents: Array[Array[Object]] =
       Array(
         Array("BadValue", "Der falsche Wert ist %s")
         ...
       )
   }

   The name of the class to supply to the MessageBundle to access the above string resources is "com.acme.Messages". Hence the MessageBundle is instantiated with:

   MessageBundle("com.acme.Messages")

   Best practice would dictate that each resource bundle class is placed in a separate file so that only the strings for a given language are loaded when required.

   name

   of the class containing the resource strings

9.  trait ShowLocal[A] extends AnyRef

   Displays locale specific string for any object.

   Displays locale specific string for any object.

   ShowLocal is a type class that extends classes with the showLocal method. The method takes an implicit java.util.Locale defining in what language the returned string should be. In order to add the extension method to an object it is necessary to define an implicit implementation of the ShowLocal trait.

   Example:

   case class Person(name: String, age: Int)
   
   implicit val showLocalForPerson: ShowLocal[Person] =
     new ShowLocal[Person] {
       def showLocal(person: Person)(implicit locale: Locale): String = {
         locale.getLanguage match {
           case "en" => s"Name: ${person.name}, Age: ${person.age}"
           case "fr" => s"prénom: ${person.name}, âge: ${person.age}"
         }
       }
     }
   
   val person = Person("John Smith", 32)
   implicit val locale = Locale.ENGLISH
   
   person.showLocal
   person.showLocal(Locale.FRENCH)

   Output:

   Name: John Smith, Age: 32
   prénom: John Smith, âge: 32

   The showLocal extension method can be defined for any class A provided an implementation of ShowLocal[A] exists implicitly and is in scope. The implicit definitions are generally defined in separate classes in a "instances" sub-directory enclosed within a trait. The trait is then mixed into an Implicits object allowing user to only import Implicits._.

   For the example above the trait class would look like:

   trait PersonInstances {
     implicit val showLocalForPerson: ShowLocal[Person] =
       new ShowLocal[Person] {
         def showLocal(person: Person)(implicit locale: Locale): String = {
           locale.getLanguage match {
             case "en" => s"Name: ${person.name}, Age: ${person.age}"
             case "fr" => s"prénom: ${person.name}, âge: ${person.age}"
           }
         }
       }
   }

   stored in the file instances/PersonInstances.scala. All implicits would be mixed in a file called Implicits.scala that looks like:

   object Implicits
     extends instances.PersonInstances

   A

   type for which a language specific string is generated