Packages

  • package root

    Documentation for the Axiell Utilities Project

    Documentation for the Axiell Utilities Project

    Overview

    The Axiell Utilities Project attempts to provide a small library of classes and object applicable to most Axiell developments. The library is not geared towards any one project and so should be useful for new projects as well as existing ones.

    The library is based on a few simple principles, namely:

    • referential transparency. The principle that defines a call to a method with the same arguments will always return the same result and that the method does not have any side effects (e.g. updating global variables, etc).
    • functional programming support. If a method or class does have side effects then the method or class is marked as effectful. The library has been designed to not contain any effectful code.
    • minimal functionality. The library is designed to be small with support for a small number of common utilities. The main reason for the small size is to limit the number of dependencies drawn in by the package.

    Package structure

    The com.axiell.util package consists of a number of utilities, where each utility provides a single piece of functionality.

    Notable utilities are:

    • Configure generic configuration reader allowing application settings defined as resources to be interrogated.
    • Error generic error handling class defining a locale independent error message along with details relating to the context of the error. The context may include an exception and other relevant values.
    • Formatter retrieves and formats a locale specific string from a specified resource bundle. The formatting is specified in a C printf style.
    • Implicits implements implicit methods and classes used to pimp methods onto existing classes (e.g. fold() method to Boolean class) and to provide implicit implementations for the JsonLocal and ShowLocal type classes.
    • JsonLocal type class used to output locale specific JSON structures. Implementations exist for Message and Error.
    • Message provides a locale independent mechanism for handling strings. The strings for a given locale are stored in resource bundles that are accessed when the message is to be displayed.
    • ShowLocal type class used to show locale specific strings. Allows Message and Error to be converted to a given language string.

    Dependencies

    The list of dependencies are:

    • Typesafe Config a generic configuration file reader. The library is used by the Configure class to access settings stored as resources within an application.
    Definition Classes
    root
  • package com
    Definition Classes
    root
  • package axiell
    Definition Classes
    com
  • package util

    Axiell Utilities Project

    Axiell Utilities Project

    A set of classes and traits that provide a simple mechanism for the internationalisation of strings and error handling. A mechanism is also supplied to read an application's configuration resource. All methods have been designed to be referentially transparent without the introduction of an effectful library (e.g. cats).

    Imports

    The utility classes/traits can be imported in the usual way, however it is necessary to include the Implicits object if the showLocal and jsonLocal type class methods are used, similarly for the read method on Configure.

    Example:

    import com.axiell.util.Implicits._

    A shorthand way to gain access to all utility classes is to import:

    import com.axiell.util._
    import com.axiell.util.Implicits._

    For more detail on project see the root package page.

    Definition Classes
    axiell
  • package instances

    Contains implicit values used by type classes.

    Contains implicit values used by type classes.

    The implicit values are used by the ShowLocal, JsonLocal and ConfigureReader type classes to print out language dependent strings, language dependent JSON strings and read configuration values respectively.

    Implicit values exist for the following classes:

    • ConfigureReader (read)
    • Error (showLocal, jsonLocal)
    • Int (showLocal, jsonLocal)
    • List (showLocal, jsonLocal)
    • Message (showLocal, jsonLocal)
    • java.time.OffsetDateTime (showLocal, jsonLocal)
    • java.lang.String (showLocal, jsonLocal)
    • java.lang.Throwable (showLocal, jsonLocal)

    The method names appended in brackets are the extension methods added by the implicit values.

    Definition Classes
    util
  • package syntax

    Contains implicit classes used to add extension methods.

    Contains implicit classes used to add extension methods.

    The implicit classes are used to add the following extension methods:

    • showLocal displays a language dependent version of an object
    • jsonLocal generates a JSON string with language dependent strings
    • masonLocal generates a Mason Draft 2 compliant JSON string for Error
    • fold functionality for Boolean type

    All traits found in the package are for the implementation of extension methods. The traits are mixed into the Implicits object so they can be easily imported into clients when required.

    Definition Classes
    util
  • Configure
  • ConfigureReader
  • Error
  • ErrorException
  • Formatter
  • Implicits
  • JsonLocal
  • Message
  • MessageBundle
  • ShowLocal

final case class Error extends Product with Serializable

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)
Source
Error.scala
Linear Supertypes
Serializable, Product, Equals, AnyRef, Any
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. Error
  2. Serializable
  3. Product
  4. Equals
  5. AnyRef
  6. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. Protected

Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##(): Int
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  4. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  5. def clone(): AnyRef
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.CloneNotSupportedException]) @native()
  6. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  7. def finalize(): Unit
    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.Throwable])
  8. def get[A](key: String)(implicit arg0: ClassTag[A]): Option[A]

    Returns the value associated with an error property

    Returns the value associated with an error property

    The context values associated with an error all have a key or label associated with them. The reserved keys, code and message contain the error code as a String and the error message as a Message. When retrieving a property value you must specify the type to be retrieved.

    Example:

    Error("BadPath", "/home/user")
      .get[String]("code")
    
    BadPath
    A

    type of the value to be retrieved

    key

    for which the value is to be retrieved

    returns

    None if key does not exist or is wrong type, otherwise Some(value)

  9. final def getClass(): Class[_ <: AnyRef]
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  10. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  11. val map: ListMap[String, (A, JsonLocal[A], ShowLocal[A]) forSome {type A}]
  12. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  13. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  14. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  15. def productElementNames: Iterator[String]
    Definition Classes
    Product
  16. final def synchronized[T0](arg0: => T0): T0
    Definition Classes
    AnyRef
  17. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  18. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException])
  19. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws(classOf[java.lang.InterruptedException]) @native()
  20. def withProperty[A](key: String, value: A)(implicit json: JsonLocal[A], show: ShowLocal[A]): Error

    Adds a generic key/value to error

    Adds a generic key/value to error

    When an error is generated there may be extra context information associated with the error that should make up the error messages. The context information varies depending on the error. It is possible to add generic values to an error and associate a key with the value.

    Example:

    Error("BadPath", path)
      .withProperty("path", path)

    In the example the key path has the value path associated with it.

    A

    type of the context value being set

    key

    for the context value

    value

    associated with the context key

    json

    formatter to output JSON version of error

    show

    formatter to output string version of error

    returns

    Error with the context information added

Inherited from Serializable

Inherited from Product

Inherited from Equals

Inherited from AnyRef

Inherited from Any

Ungrouped