https://github.com/realityforge/braincheck

https://github.com/realityforge/braincheck

Last synced: about 2 months ago
JSON representation

• Host: GitHub
• URL: https://github.com/realityforge/braincheck
• Owner: realityforge
• License: apache-2.0
• Created: 2017-09-21T04:00:19.000Z (about 7 years ago)
• Default Branch: master
• Last Pushed: 2024-07-26T02:52:37.000Z (5 months ago)
• Last Synced: 2024-10-04T17:12:54.788Z (2 months ago)
• Language: Java
• Homepage: http://realityforge.org/braincheck
• Size: 583 KB
• Stars: 0
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

• gwt-boot-awesome-lili - braincheck - A GWT/J2CL invariant checking toolkit that is optimized out in (Miscellaneous Library)
• gwt-boot-awesome-lili - braincheck - A GWT/J2CL invariant checking toolkit that is optimized out in (Miscellaneous Library)

README

        
# Braincheck

[![Build Status](https://api.travis-ci.com/realityforge/braincheck.svg?branch=master)](http://travis-ci.com/realityforge/braincheck)

[](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.realityforge.braincheck%22%20a%3A%22braincheck%22)

![GWT3/J2CL compatible](https://img.shields.io/badge/GWT3/J2CL-compatible-brightgreen.svg)

Braincheck is a very simple library that you can used to check invariants in code. It is designed that these invariant

checks can be compiled out in production environments either by the JIT or the GWT compiler. Braincheck also super-sources

`Objects.requireNonNull(...)` to call `javaemul.internal.InternalPreconditions.checkNotNull(...)` so that these guards

can be stripped by configuring the compile-time property `jre.checks.checkLevel` to `DISABLED`.

## Quick Start

The simplest way to use Braincheck is to;

* Review the [javadocs](http://realityforge.org/braincheck/).

* Add the BrainCheck dependencies into the build system. i.e.

```xml

   org.realityforge.braincheck

   braincheck

   1.31.0

```

* If the application is a GWT application, then inherit from `org.realityforge.braincheck.BrainCheck`

  in your .gwt.xml for a production build or inherit `org.realityforge.braincheck.BrainCheckDev` in a

  development build. You can also explicitly set the configuration properties to control which parts

  of the application are optimized away during builds. See the configuration properties section below.

* Add invariant checks to your code to verify various conditions.

```java

import static org.realityforge.braincheck.Guards.*;

class MyClass

{

  public void myMethod(int i)

  {

    // Raise an exception if condition (first parameter) is not true

    apiInvariant( () -> i > 0, () -> "You are using the api incorrectly!" );

    // Raise an exception if condition (first parameter) is not true

    invariant( () -> 1 == 1, () -> "Maths has broken down!" );

    // Raise an exception if invariant checks enabled

    fail( () -> "You have reached a failing scenario in the application" );

  }

}

```

* You can also modify the invariant configuration in tests by setting system property

  `braincheck.environment` to `development` and interacting with the `BrainCheckTestUtil`

  class. i.e.

```java

import org.realityforge.braincheck.BrainCheckTestUtil;

class MyTest

{

  @Test

  public void myTest()

  {

    BrainCheckTestUtil.setCheckApiInvariants( true );

    //...

  }

}

```

## Configuration Properties

The following configuration properties can be used to configure BrainCheck. These are mainly used to optimize

the size of applications that statically compile code (i.e. GWT) when we want to minimize code size.

* `braincheck.verbose_error_messages` which can be set to `true` or `false` and if `true`, then invariant exception

  messages will use the supplied message, otherwise no message will be passed to exception.

* `braincheck.check_invariants` which can be set to `true` or `false` and if `false`, calls to `Guards.invariant()`

  and `Guards.fail()` are ignored.

* `braincheck.check_api_invariants` which can be set to `true` or `false` and if `false` or if

  `braincheck.check_invariants` is false then calls to `Guards.apiInvariant()` are ignored.

* `braincheck.environment` which can be set to `development` or `production` and defaults to `production`. If

  `production` then the default values for `braincheck.verbose_error_messages`, `braincheck.check_invariants`

  and `braincheck.check_api_invariants` will be `false` otherwise they will default to be `true`.