= Chronicle Wire
Chronicle Software
:css-signature: demo
:toc: macro
:toclevels: 2
:icons: font

image:https://maven-badges.herokuapp.com/maven-central/net.openhft/chronicle-wire/badge.svg[caption="",link=https://maven-badges.herokuapp.com/maven-central/net.openhft/chronicle-wire]
image:https://javadoc.io/badge2/net.openhft/chronicle-wire/javadoc.svg[link="https://www.javadoc.io/doc/net.openhft/chronicle-wire/latest/index.html"]
//image:https://javadoc-badge.appspot.com/net.openhft/chronicle-wire.svg?label=javadoc[JavaDoc, link=https://www.javadoc.io/doc/net.openhft/chronicle-wire]
image:https://img.shields.io/github/license/OpenHFT/Chronicle-Wire[GitHub]
image:https://img.shields.io/badge/release%20notes-subscribe-brightgreen[link="https://chronicle.software/release-notes/"]
image:https://sonarcloud.io/api/project_badges/measure?project=OpenHFT_Chronicle-Wire&metric=alert_status[link="https://sonarcloud.io/dashboard?id=OpenHFT_Chronicle-Wire"]

image::images/Wire_line.png[width=20%]

toc::[]

== About

Chronicle Wire is a Wire Format abstraction library, The purpose of Chronicle Wire is to address the following concerns in a consistent manner:

- Application configuration. (Using YAML)
- Data serialization (YAML, binary YAML, JSON, Raw binary data, CSV)
- Accessing off-heap memory in a thread-safe manner. (Bind to shared off-heap memory)
- High performance data exchange using binary formats. Only include as much meta data as you need.

== Design

Chronicle Wire uses Chronicle Bytes for bytes manipulation, and Chronicle Core for low level JVM access.

=== Why are these concerns conflated?

Often you want to use these interchangeably.

- Configuration includes aliased type information.
This supports easy extension by adding new classes/versions, and cross-platform using type aliasing.
- By supporting types, a configuration file can bootstrap itself.
You control how the configuration file is decoded.
See link:src/test/resources/docs/qe_cfg.yaml[example Queue Enterprise config].
- To send the configuration of a server to a client, or from a client to a server.
- To store the configuration of a data store in its header.
- In configuration, to be able to create any object or component.
- Save a configuration after you have changed it.
- To be able to share data in memory between processes in a thread-safe manner.

=== Features

Chronicle Wire supports a separation of describing what data you want to store and retrieve, and how it should be rendered/parsed.
Chronicle Wire handles a variety of formatting options, for a wide range of formats.

A key aim of Chronicle Wire is to support schema changes.
It should make reasonable attempts to handle:

* optional fields
* fields in a different order
* fields that the consumer doesn't expect; optionally parsing them, or ignoring them
* more or less data than expected; in field-less formats
* reading a different type to the one written
* updating fixed-length fields, automatically where possible using a `bound` data structure.
* dynamic updates of Enums or objects passed-by-name

Chronicle Wire will also be efficient where any, or all, of the following points are true:

* fields are in the order expected
* fields are the type expected
* fields names/numbers are not used
* self-describing types are not needed
* random access of data values is supported.

Chronicle Wire is designed to make it easy to convert from one wire format to another.
For example, you can use fixed-width binary data in memory for performance, and variable-width or text over the network.
Different TCP connections could use different formats.

Chronicle Wire also supports hybrid wire formats.
For example, you can have one format embedded in another.

== Support

This library requires Java 8. Support for `C++` and `C#` is planned.

== Text Formats

The text formats include:

* `YAML` - subset of mapping structures included
* `JSON` - superset to support serialization
* `CSV` - superset to support serialization
* `XML` - planned

Options include:

* field names (for example, JSON), or field numbers (for example, FIX)
* optional fields with default values that can be dropped
* zero-copy access to fields - planned
* thread-safe operations in text - planned

To support wire format discovery, the first byte should be in the `ASCII` range; adding an `ASCII` whitespace if needed.

== Binary Formats

The binary formats include:

* binary YAML.
* delta compressing Binary YAML.This is a Chronicle Wire Enterprise feature
* typed data without fields
* raw untyped fieldless data
* Trivially Copyable Objects (lowest latency)

Options for Binary format:

* field names or field numbers
* variable width
* optional fields with a default value can be dropped
* fixed width data with zero copy support
* thread-safe operations

Note: Chronicle Wire supports debug/transparent combinations like self-describing data with zero copy support.

To support wire format discovery, the first bytes should have the top bit set.

== Using Wire

=== link:https://github.com/OpenHFT/Chronicle-Wire/blob/ea/demo/src/main/java/run/chronicle/wire/demo/Example1.java[Simple use case]

First you need to have a buffer to write to.
This can be a `byte[]`, a `ByteBuffer`, off-heap memory, or even an address and length that you have obtained from some other library.

[source,Java]
----
// Bytes which wraps a byte[]
Bytes<byte[]> bytes = Bytes.allocateElasticOnHeap();
// or
// Bytes which wraps a ByteBuffer which is resized as needed.
Bytes<ByteBuffer> bytes = Bytes.elasticByteBuffer();
----

Now you can choose which format you are using.
As the wire formats are themselves unbuffered, you can use them with the same buffer, but in general using one wire format is easier.

[source,Java]
----
Wire wire = new TextWire(bytes);
// or
WireType wireType = WireType.TEXT;
Wire wireB = wireType.apply(bytes);
// or
Bytes<?> bytes2 = Bytes.allocateElasticOnHeap();
Wire wire2 = new BinaryWire(bytes2);
// or
Bytes<?> bytes3 = Bytes.allocateElasticOnHeap();
Wire wire3 = new RawWire(bytes3);
----

So now you can write to the wire with a simple document.

[source,Java]
----
wire.write("message").text("Hello World")
      .write("number").int64(1234567890L)
      .write("code").asEnum(TimeUnit.SECONDS)
      .write("price").float64(10.50);

System.out.println(bytes);
----

prints

[source,yaml]
----
message: Hello World
number: 1234567890
code: SECONDS
price: 10.5
----

[source,Java]
----
// The same code for BinaryWire
wire2.write("message").text("Hello World")
        .write("number").int64(1234567890L)
        .write("code").asEnum(TimeUnit.SECONDS)
        .write("price").float64(10.50);

System.out.println(bytes2.toHexString());
----

prints

[source,text]
----
00000000 c7 6d 65 73 73 61 67 65  eb 48 65 6c 6c 6f 20 57 ·message ·Hello W
00000010 6f 72 6c 64 c6 6e 75 6d  62 65 72 a6 d2 02 96 49 orld·num ber····I
00000020 c4 63 6f 64 65 e7 53 45  43 4f 4e 44 53 c5 70 72 ·code·SE CONDS·pr
00000030 69 63 65 90 00 00 28 41                          ice···(A
----

Using `RawWire` strips away all the meta data to reduce the size of the message, and improves speed.
The down-side is that we cannot easily see what the message contains.

[source, Java]
----
// The same code for RawWire
wire3.write("message").text("Hello World")
        .write("number").int64(1234567890L)
        .write("code").asEnum(TimeUnit.SECONDS)
        .write("price").float64(10.50);

System.out.println(bytes3.toHexString());
----

prints in `RawWire`.

[source, text]
----
00000000 0b 48 65 6c 6c 6f 20 57  6f 72 6c 64 d2 02 96 49 ·Hello W orld···I
00000010 00 00 00 00 07 53 45 43  4f 4e 44 53 00 00 00 00 ·····SEC ONDS····
00000020 00 00 25 40                                      ··%@
----

//For more examples see https://github.com/OpenHFT/Chronicle-Wire/blob/master/README-Chapter1.md[Examples Chapter1]
=== link:https://github.com/OpenHFT/Chronicle-Wire/blob/ea/demo/src/main/java/run/chronicle/wire/demo/Example2.java[Simple example with a data type]

This example is much the same as the previous section, with the code required wrapped in a method. See Section "The code for the class Data" for the code for Data.
[source,Java]
----
// Bytes which wraps a ByteBuffer which is resized as needed.
Bytes<ByteBuffer> bytes = Bytes.elasticByteBuffer();

Wire wire = new TextWire(bytes);

Data data = new Data("Hello World", 1234567890L, TimeUnit.NANOSECONDS, 10.50);
data.writeMarshallable(wire);
System.out.println(bytes);

Data data2= new Data();
data2.readMarshallable(wire);
System.out.println(data2);
----

prints

[source,yaml]
----
message: Hello World
number: 1234567890
code: NANOSECONDS
price: 10.5
----

[source,text]
----
Data{message='Hello World', number=1234567890, timeUnit=NANOSECONDS, price=10.5}
----

To write in binary instead

[source,Java]
----
Bytes<ByteBuffer> bytes2 = Bytes.elasticByteBuffer();
Wire wire2 = new BinaryWire(bytes2);

data.writeMarshallable(wire2);
System.out.println(bytes2.toHexString());

Data data3= new Data();
data3.readMarshallable(wire2);
System.out.println(data3);
----

prints

[source,text]
----
00000000 c7 6d 65 73 73 61 67 65  eb 48 65 6c 6c 6f 20 57 ·message ·Hello W
00000010 6f 72 6c 64 c6 6e 75 6d  62 65 72 a6 d2 02 96 49 orld·num ber····I
00000020 c8 74 69 6d 65 55 6e 69  74 eb 4e 41 4e 4f 53 45 ·timeUni t·NANOSE
00000030 43 4f 4e 44 53 c5 70 72  69 63 65 90 00 00 28 41 CONDS·pr ice···(A

Data{message='Hello World', number=1234567890, timeUnit=NANOSECONDS, price=10.5}
----

=== link:https://github.com/OpenHFT/Chronicle-Wire/blob/ea/demo/src/main/java/run/chronicle/wire/demo/Example3.java[Simple example with a nested data type]

In this example the data is marshalled as a nested data structure.

[source,java]
----

// Bytes which wraps a byte[] which is resized as needed
Bytes<?> bytes = Bytes.allocateElasticOnHeap();

Wire wire = new TextWire(bytes);

Data data = new Data("Hello World", 1234567890L, TimeUnit.NANOSECONDS, 10.50);
wire.write("mydata").marshallable(data);
System.out.println(bytes);

Data data2= new Data();
wire.read("mydata").marshallable(data2);
System.out.println(data2);
----

prints

[source, yaml]
----
mydata: {
  message: Hello World,
  number: 1234567890,
  timeUnit: NANOSECONDS,
  price: 10.5
}
----

[source,text]
----
Data{message='Hello World', number=1234567890, timeUnit=NANOSECONDS, price=10.5}
----

To write in binary instead

[source,java]
----
Bytes<?> bytes2 = new HexDumpBytes();
Wire wire2 = new BinaryWire(bytes2);

wire2.write("mydata").marshallable(data);
System.out.println(bytes2.toHexString());

Data data3= new Data();
wire2.read("mydata").marshallable(data3);
System.out.println(data3);
----

prints

[source,text]
----
c6 6d 79 64 61 74 61                            # mydata
80 40                                           # Data
c7 6d 65 73 73 61 67 65                         # message
eb 48 65 6c 6c 6f 20 57 6f 72 6c 64             # Hello World
c6 6e 75 6d 62 65 72                            # number
a6 d2 02 96 49                                  # 1234567890
c8 74 69 6d 65 55 6e 69 74                      # timeUnit
eb 4e 41 4e 4f 53 45 43 4f 4e 44 53             # NANOSECONDS
c5 70 72 69 63 65 90 00 00 28 41                # price

Data{message='Hello World', number=1234567890, timeUnit=NANOSECONDS, price=10.5}
----

=== link:https://github.com/OpenHFT/Chronicle-Wire/blob/ea/demo/src/main/java/run/chronicle/wire/demo/Example4.java[Simple example with a data type with a type]

In this example, the type is encoded with the data.
Instead of showing the entire package name which will almost certainly not work on any other platform, an alias for the type is used.
It also means the message is shorter and faster.

[source,Java]
----
Wire wire = new TextWire(Bytes.allocateElasticOnHeap());

ClassAliasPool.CLASS_ALIASES.addAlias(Data.class);

Data data = new Data("Hello World", 1234567890L, TimeUnit.NANOSECONDS, 10.50);
wire.write("mydata").object(data);
System.out.println(wire);

Data data2= wire.read("mydata").object(Data.class);
System.out.println(data2);
----

prints

[source,yaml]
----
mydata: !Data {
  message: Hello World,
  number: 1234567890,
  timeUnit: NANOSECONDS,
  price: 10.5
}
----

[source,text]
----
Data{message='Hello World', number=1234567890, timeUnit=NANOSECONDS, price=10.5}
----

To write in binary instead

[source,Java]
----
Wire wire2 = new TextWire(Bytes.allocateElasticOnHeap());

wire2.write("mydata").object(data);
System.out.println(wire2.bytes().toHexString());

Data data3 = wire2.read("mydata").object(Data.class);
System.out.println(data3);
----

prints

[source,text]
----
c6 6d 79 64 61 74 61                            # mydata
b6 04 44 61 74 61                               # Data
80 40                                           # Data
c7 6d 65 73 73 61 67 65                         # message
eb 48 65 6c 6c 6f 20 57 6f 72 6c 64             # Hello World
c6 6e 75 6d 62 65 72                            # number
a6 d2 02 96 49                                  # 1234567890
c8 74 69 6d 65 55 6e 69 74                      # timeUnit
eb 4e 41 4e 4f 53 45 43 4f 4e 44 53             # NANOSECONDS
c5 70 72 69 63 65 90 00 00 28 41                # price

Data{message='Hello World', number=1234567890, timeUnit=NANOSECONDS, price=10.5}
----

=== link:https://github.com/OpenHFT/Chronicle-Wire/blob/ea/demo/src/main/java/run/chronicle/wire/demo/Example6.java[Write a message with a sequence of records]

[source,Java]
----
// Bytes which wraps a ByteBuffer which is resized as needed
Bytes<ByteBuffer> bytes = Bytes.elasticByteBuffer();

Wire wire = new TextWire(bytes);

ClassAliasPool.CLASS_ALIASES.addAlias(Data.class);

Data[] data = {
        new Data("Hello World", 98765, TimeUnit.HOURS, 1.5),
        new Data("G'Day All", 1212121, TimeUnit.MINUTES, 12.34),
        new Data("Howyall", 1234567890L, TimeUnit.SECONDS, 1000)
};
wire.writeDocument(false, w -> w.write("mydata")
        .sequence(v -> Stream.of(data).forEach(v::object)));

System.out.println(Wires.fromSizePrefixedBlobs(bytes));

List<Data> dataList = new ArrayList<>();
wire.readDocument(null, w -> w.read("mydata")
        .sequence(dataList, (l, v) -> {
            while (v.hasNextSequenceItem())
                l.add(v.object(Data.class));
       }));

dataList.forEach(System.out::println);
----

prints

[source,yaml]
----
--- !!data
mydata: [
  !Data {
    message: Hello World,
    number: 98765,
    timeUnit: HOURS,
    price: 1.5
},
  !Data {
    message: G'Day All,
    number: 1212121,
    timeUnit: MINUTES,
    price: 12.34
},
  !Data {
    message: Howyall,
    number: 1234567890,
    timeUnit: SECONDS,
    price: 1E3
}
]
----
[source,text]
----
Data{message='Hello World', number=98765, timeUnit=HOURS, price=1.5}
Data{message='G'Day All', number=1212121, timeUnit=MINUTES, price=12.34}
Data{message='Howyall', number=1234567890, timeUnit=SECONDS, price=1000.0}
----

To write in binary instead

[source,Java]
----
Bytes<ByteBuffer> bytes2 = Bytes.elasticByteBuffer();
Wire wire2 = new BinaryWire(bytes2);

wire2.writeDocument(false, w -> w.write("mydata")
        .sequence(v -> Stream.of(data).forEach(v::object)));
System.out.println(Wires.fromSizePrefixedBlobs(bytes2));

List<Data> dataList2 = new ArrayList<>();
wire2.readDocument(null, w -> w.read("mydata")
        .sequence(dataList2, (l, v) -> {
            while (v.hasNextSequenceItem())
                l.add(v.object(Data.class));
        }));

dataList2.forEach(System.out::println);
----

prints

[source,yaml]
----
--- !!data #binary
mydata: [
  !Data {
    message: Hello World,
    number: !int 98765,
    timeUnit: HOURS,
    price: 1.5
},
  !Data {
    message: G'Day All,
    number: 1212121,
    timeUnit: MINUTES,
    price: 12.34
},
  !Data {
    message: Howyall,
    number: !int 1234567890,
    timeUnit: SECONDS,
    price: !int 1000
}
]
----
[source,text]
----
Data{message='Hello World', number=98765, timeUnit=HOURS, price=1.5}
Data{message='G'Day All', number=1212121, timeUnit=MINUTES, price=12.34}
Data{message='Howyall', number=1234567890, timeUnit=SECONDS, price=1000.0}
----

=== link:https://github.com/OpenHFT/Chronicle-Wire/blob/ea/demo/src/main/java/run/chronicle/wire/demo/Example7.java[Using the `ClassAliasPool`]
This example shows how to pass your classes to `ClassAliasPool.CLASS_ALIASES.addAlias(Class<?>... classes)`, to create alias names for them so that you can refer to them without using the complete name of their packages.

[source,java]
----
// Create two classes Data1 and Data2 and add only the Data1.class to alias pool.
static {
        ClassAliasPool.CLASS_ALIASES.addAlias(Data1.class);
}

private static class Data1 extends SelfDescribingMarshallable {
    String name;
    int age;
    String address;
}

private static class Data2 extends SelfDescribingMarshallable {
    String name;
    int age;
    String address;
}

// Create instances of Data1 and Data2
Data1 data1 = new Data1();
data1.name = "James";
data1.age = 20;
data1.address = "12 Kingston, London";

Data2 data2 = new Data2();
data2.name = "James";
data2.age = 20;
data2.address = "12 Kingston, London";
----
Printing out data1 and data2, you will see that the alias name is printed out for data1 but data2 appears with complete package name.

[source, jave]
----
System.out.println(data1);
System.out.println(data2);
----
prints:
[source, text]
----
!Data1 {
  name: James,
  age: 20,
  address: "12 Kingston, London"
}

!run.chronicle.wire.demo.Example7$Data2 {
  name: James,
  age: 20,
  address: "12 Kingston, London"
}
----

Create configuration files cfg1.yaml and cfg2.yaml. See how the classes' names appear differently in yaml files for classes with alias name and without alias name. For Data1 object alias name is used in the yaml file (cfg1.yaml). Data2 object should be loaded from a yaml file
with the complete name of class (including package name) otherwise you will receive an Exception.

.cfg1.yaml
[source,yaml]
----
!Data1 {
  name: Tom,
  age: 25,
  address: "21 High street, Liverpool"
}
----

.cfg2.yaml
[source,yaml]
----
!run.chronicle.wire.demo.Example7$Data2 {
  name: Helen,
  age: 19,
  address: "15 Royal Way, Liverpool"
}
----
Create instances of Data1 and Data2 by reading the above configuration files and print the created objects:
[source, java]
----
Data1 o1 = WireType.TEXT.fromFile("cfg1.yaml");
System.out.println("o1 = " + o1);
----
prints:
[source, text]
----
o1 = !Data1 {
name: Tom,
age: 25,
address: "21 High street, Liverpool"
}
----
and
[source,java]
----
Data2 o2 = WireType.TEXT.fromFile("cfg2.yaml");
System.out.println("o2 = " + o2);
----

prints:
[source, text]
----
o2 = !run.chronicle.wire.demo.Example7$Data2 {
name: Helen,
age: 19,
address: "15 Royal Way, Liverpool"
}
----
You will see the complete package name for `o2` object.

=== link:https://github.com/OpenHFT/Chronicle-Wire/blob/ea/demo/src/main/java/run/chronicle/wire/demo/Data.java[The code for the class Data]

[source,Java]
----
class Data implements Marshallable {
    private String message;
    private long number;
    private TimeUnit timeUnit;
    private double price;

    public Data() {
    }

    public Data(String message, long number, TimeUnit timeUnit, double price) {
        this.message = message;
        this.number = number;
        this.timeUnit = timeUnit;
        this.price = price;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public void setNumber(long number) {
        this.number = number;
    }

    public void setPrice(double price){
        this.price =price;
    }

    public void setTimeUnit(TimeUnit timeUnit){
        this.timeUnit = timeUnit;
    }

    public String getMessage() {
        return message;
    }

    public long getNumber() {
        return number;
    }

    public TimeUnit getTimeUnit() {
        return timeUnit;
    }

    public double getPrice() {
        return price;
    }

    @Override
    public void readMarshallable(WireIn wire) throws IllegalStateException {
        wire.read("message").text(this, Data::setMessage)
                .read("number").int64(this, Data::setNumber)
                .read("timeUnit").asEnum(TimeUnit.class, this, Data::setTimeUnit)
                .read("price").float64(this,Data::setPrice);
    }

    @Override
    public void writeMarshallable(WireOut wire) {
        wire.write("message").text(message)
                .write("number").int64(number)
                .write("timeUnit").asEnum(timeUnit)
                .write("price").float64(price);
    }

    @Override
    public String toString() {
        return "Data{" +
                "message='" + message + '\'' +
                ", number=" + number +
                ", timeUnit=" + timeUnit +
                ", price=" + price +
                '}';
    }
}
----

== A note on `Wires.reset()`

Chronicle Wire allows (and encourages) objects to be re-used in order to reduce allocation rates.

When a marshallable object is re-used or initialised by the framework, it is first reset by way of `Marshallable.reset()`
which is recommended over calling `Wires.reset()`.
In the case of most DTOs with simple scalar values, this will not cause any issues.
However, more complicated objects with object instance fields may experience undesired behaviour.

In order to `reset` a marshallable object, the process is as follows:

1. create a new instance of the object to be reset (this is done just once per object type, then cached)
2. reset all fields, so that
  a. when the field value implements `Resettable` interface, and the default value of the field is not `null`, and the current field value is of exactly the same class as the default value, `value.reset()` will be called. This behavior is introduced in Chronicle Wire `2.25`.
  b. when the field type is `Collection` or `Map`, and the default value is empty collection, it will be cleared.
  c. there is specific built-in copy-by-value handling for some types such as `Bytes`
  d. all other fields will be copied by reference from the new instance to the existing instance
3. the existing instance is now considered 'reset' back to default values

The object created in step `1` is cached for performance reasons, meaning that both the new and existing instance of the marshallable object could have a reference to the same object.

While this will not be a problem for primitive or immutable values (for example, `int`, `Long`, `String`), a mutable field such as `ByteBuffer` will cause problems.
Consider the following case:

[source,java]
----
public class BufferContainer {
    private final ByteBuffer b = ByteBuffer.allocate(16);
}

@Test
public void shouldDemonstrateMutableFieldIssue2() {
    // create 2 instances of a marshallable POJO
    final BufferContainer c1 = new BufferContainer();
    final BufferContainer c2 = new BufferContainer();
    // reset both instances - this will set each container's
    // b field to a 'default' value
    Wires.reset(c1);
    Wires.reset(c2);
    // write to the buffer in c1
    c1.b.putInt(42);
    // inspect the buffer in both c1 and c2
    System.out.println(c1.b.position());
    System.out.println(c2.b.position());
    System.out.println(c1.b == c2.b);
}
----

The output of the test above is:

----
4
4
true
----

showing that the field **b** of each container object is now referencing the same `ByteBuffer` instance.

An exception to this is when the field value implements `Resettable` interface, when the default value of the field is not null, and the current field value is of exactly the same class as the default value. In this case, `value.reset()` will be called instead of overwriting it with default value by reference.

In order to work around this, if necessary, the marshallable class can override `Marshallable.reset`:

[source,java]
----
public class BufferContainer implements Marshallable {
    private ByteBuffer b = ByteBuffer.allocate(16);

    @Override
    public void reset() {
        // or acquire from a pool if allocation should
        // be kept to a minimum
        b = ByteBuffer.allocate(16);
    }
}
----

If the field type implements `Resettable` (including `Marshallable` classes), and the field has non-`null` default value, the existing value will be reset without creating any extra garbage:

[source,java]
----
public class ComplexDto implements SelfDescribingMarshallable {
    private ContainedDto v = new ContainedDto(); // reset() will be propagated to this value
}

public class ContainedDto implements SelfDescribingMarshallable {
    // more fields which would be reset by default reset() implementation
}
----

== Binding to a field value

While serialized data can be updated by replacing a whole record, this might not be the most efficient option, nor thread-safe.

Chronicle Wire offers the ability to bind a reference to a fixed value of a field, and perform atomic operations on that field; for example, volatile read/write, and compare-and-swap.

[source,Java]
----
   // field to cache the location and object used to reference a field.
   private LongValue counter = null;

   // find the field and bind an approritae wrapper for the wire format.
   wire.read(COUNTER).int64(counter, x -> counter = x);

   // thread safe across processes on the same machine.
   long id = counter.getAndAdd(1);
----

Other types are supported; for example, 32-bit integer values, and an array of 64-bit integer values.

== Pass-by-name or Dynamic Enums

Chronicle Wire supports passing objects reference by the `name()` of the object referenced.
This is supported trivially with `enum` which define a `name()` for you. e.g.

.Passing a reference to an enum using it's name
[source,java]
----
enum ServerId {
    LN_A
}

interface Output {
    void serverId(ServerId serverId);
}

// later
Output out; // is a MethodWriter

out.serverId(ServerId.LN_A);
----

.Message on the Wire
[source,yaml]
serverId: LN_A

However, we might wish to alter metadata associated with the enum

[source,java]
----
enum ServerId implements DynamicEnum {
    LN_A(101);

    public int priority;
}
----

=== Not passing by name

Sometimes you need to pass the actually data, esp the first time. This can be achieved by using the `@AsMarshallable` annotation which will always pass the object as a typedMarshallable.

[source, java]
----
public class RefData extends AbstractEventCfg<RefData> {
    @AsMarshallable
    private final DynamicEnum data;

    public RefData(DynamicEnum data) {
        this.data = data;
    }

    public DynamicEnum data() {
        return data;
    }
}
----

You can choose to update the existing `enum` with this information.

[source,java]
----
public void refData(RefData refData) {
    DynamicEnum.updateEnum(refData.data);
}
----

[source,yaml]
----
refData: {
    eventId: GUI,
    eventTime: 2020-09-09T09:09:09.999,
    data: !ServerId {
        name: LN_A,
        priority: 128
    }
}
----

NOTE: You can add an enum which didn't exist.

[source,yaml]
----
refData: {
    eventId: GUI,
    eventTime: 2020-09-09T09:09:09.999,
    data: !ServerId {
        name: HK_A,
        priority: 200
    }
}
----

NOTE: You can't use an enum before it is defined, this is assumed to be in input error.

=== Pass by reference

You may wish to pass by reference a data type which is not an enum.
This can be done by adding `DynamicEnum` to a regular class and adding a `name` field.

[source,java]
----
class MyData implements DynamicEnum {
    public static final MyData ONE = new MyData("One"); // used as a predefined object
    public static final MyData TWO = new MyData("Two"); // used as a predefined object
    private String name; // set via reflection.

    @Override public String name() { return name; }
}
----

NOTE: This is particularly useful if you have a class which must extend another parent.

[source,yaml]
----
myData: One # uses predefined value
...
myData: Two # uses predefined value
...
refData: {
    eventId: GUI,
    eventTime: 2020-09-09T09:09:09.999,
    data:  !MyData {
        name: Three
   }
}
...
myData: Three # use the one just defined
...
myData: Four # will error as doesn't exist.
...
----

The consumer doesn't need to do anything special to use the new enum, however the producer need to create it in code as follows.

[source, Java]
----
ServerId serverId = EnumCache.of(ServerId.class).nameFor("HK_A");
serverId.priority(200);
out.refData(new RefData(serverId));

MyData myData = EnumCache.of(MyData.class).nameFor("Three");
out.refData(new RefData(myData));
----

NOTE: The unique key for these objects is their type and name. Two objects of different types can have the same name.

IMPORTANT: These objects passed by reference are never cleaned up. Only use them when there is likely to be a limited number of them over the life of the application.

== Using @MethodId

You can assign a method id to a method using the annotation `@MethodId(long int: id)`.
The provided id should be unique across all classes using the same MethodReader/Writer, therefore it is safe practice to use unique method id in your entire system.A method name can be determined from its method id and this results in saving memory when calling the method.The following example shows the difference between memory usage when using method id and when not using it.In this example the method `saysomethingnice()` has been annotated with `MethodId(7)` and it has been called from `shouldDetermineMethodNamesFromMethodIds()`.

[source,Java]
----

 interface Speaker {
     @MethodId(7)
     void saysomethingnice(final String message);
 }

 void shouldDetermineMethodNamesFromMethodIds() {
     Bytes<?> bytes = Bytes.allocateElasticOnHeap();

     final BinaryWire wire = new BinaryWire(bytes);
     final Speaker speaker =
             wire.methodWriterBuilder(Speaker.class).get();
     speaker.saysomethingnice("hello");
----

.Using a @MethodId
----
08 00 00 00                                     # msg-length
ba 07                                           # say
e5 68 65 6c 6c 6f                               # hello
----

.Without a @MethodId
----
0b 00 00 00                                     # msg-length
b9 03 73 61 79                                  # say
e5 68 65 6c 6c 6f                               # hello
----

== Bytes options

Chronicle Wire is built on top of the `Bytes` library, however `Bytes`, in turn, can wrap:

* `ByteBuffer` - heap and direct
* `byte[]` - using `ByteBuffer`
* `byte[]` or primitive array without ByteBuffer
* raw memory addresses.
* portion of a regular on heap object

== Handling instance classes of an unknown type

This feature allows Chronicle Wire to de-serialize, manipulate, and serialize an instance class of an unknown type.

If the type is unknown at runtime, a proxy is created; assuming that the required type is an interface.

When the tuple is serialized, it will be give the same type as when it was deserialized, even if that class is not available.

Methods following our `getter`/`setter` convention will be treated as `getters` and `setters`.

This feature is needed for a service that stores and passes on data, for classes it might not have in its class path.

NOTE: This is not garbage collection free, but if the volume is low, this may be easier to work with.

NOTE: This only works when the expected type is not a class.

=== LongConversionExample

[source,Java]
----
@Test
public void unknownType() throws NoSuchFieldException {
    Marshallable marshallable = Wires.tupleFor(Marshallable.class, "UnknownType");
    marshallable.setField("one", 1);
    marshallable.setField("two", 2.2);
    marshallable.setField("three", "three");
    String toString = marshallable.toString();
    assertEquals("!UnknownType {\n" +
            "  one: !int 1,\n" +
            "  two: 2.2,\n" +
            "  three: three\n" +
            "}\n", toString);
    Object o = Marshallable.fromString(toString);
    assertEquals(toString, o.toString());
}

@Test
public void unknownType2() {
    String text = "!FourValues {\n" +
            "  string: Hello,\n" +
            "  num: 123,\n" +
            "  big: 1e6,\n" +
            "  also: extra\n" +
            "}\n";
    ThreeValues tv = Marshallable.fromString(ThreeValues.class, text);
    assertEquals(text, tv.toString());
    assertEquals("Hello", tv.string());
    tv.string("Hello World");
    assertEquals("Hello World", tv.string());

    assertEquals(123, tv.num());
    tv.num(1234);
    assertEquals(1234, tv.num());

    assertEquals(1e6, tv.big(), 0.0);
    tv.big(0.128);
    assertEquals(0.128, tv.big(), 0.0);

    assertEquals("!FourValues {\n" +
            "  string: Hello World,\n" +
            "  num: !int 1234,\n" +
            "  big: 0.128,\n" +
            "  also: extra\n" +
            "}\n", tv.toString());

}

interface ThreeValues {
    ThreeValues string(String s);
    String string();

    ThreeValues num(int n);
    int num();

    ThreeValues big(double d);
    double big();
}
----

== Handling unexpected fields
By default, Chronicle Wire skips fields which names don't match any field of the DTO class. It's possible to capture such fields by overriding method or `ReadMarshallable`:

[source,Java]
----
    default void unexpectedField(Object event, ValueIn valueIn) {
        valueIn.skipValue();
    }
----

One of best practices is saving unexpected fields in order to process them after the deserialization:

[source, Java]
----
        transient Map<String, Object> others = new LinkedHashMap<>();

        @Override
        public void unexpectedField(Object event, ValueIn valueIn) {
            others.put(event.toString(), valueIn.object());
        }
----

It's also possible to use fail-fast approach and throw an exception:

[source, Java]
----
        @Override
        public void unexpectedField(Object event, ValueIn valueIn) {
            throw new IllegalStateException("Unexpected field: name=" + event + ", value=" + valueIn);
        }
----
Exceptions that are thrown from this method are never swallowed, they are wrapped into runtime `UnexpectedFieldHandlingException` and thrown back to a high-level API call.

== LongConversionExample with `MethodReaders`

[source,Java]
----
@Test
public void testUnknownClass() {
    Wire wire2 = new TextWire(Bytes.elasticHeapByteBuffer(256));
    MRTListener writer2 = wire2.methodWriter(MRTListener.class);

    String text = "top: !UnknownClass {\n" +
            "  one: 1,\n" +
            "  two: 2.2,\n" +
            "  three: words\n" +
            "}\n" +
            "---\n" +
            "top: {\n" +
            "  one: 11,\n" +
            "  two: 22.2,\n" +
            "  three: many words\n" +
            "}\n" +
            "---\n";
    Wire wire = TextWire.from(text);
    MethodReader reader = wire.methodReader(writer2);
    assertTrue(reader.readOne());
    assertTrue(reader.readOne());
    assertFalse(reader.readOne());
    assertEquals(text, wire2.toString());
}
----

=== Filtering with MethodReaders

To support filtering, you need to make sure the first of multiple arguments can be used to filter the method call.
If you have only one argument, you may need to add an additional argument to support efficient filtering.

This feature calls an implementation of `MethodFilterOnFirstArg` to see if the rest of the method call should be parsed.
For example, today you have:

[source,Java]
----
interface MyInterface {
    void method(ExpensiveDto dto);
}
----

This can be migrated to:

[source,Java]
----
interface MyInterface extends MethodFilterOnFirstArg<String> {
    @Deprecated
    void method(ExpensiveDto dto);
    void method2(String filter, ExpensiveDto dto);
}
----

where the implementation can look like this:

[source,Java]
----
class MyInterfaceImpl extends MyInterface {
    public void method(ExpensiveDto dto) {
       // something
    }

    public void method2(String filter, ExpensiveDto dto) {
        method(dto);
    }

    public boolean ignoreMethodBasedOnFirstArg(String methodName, String filter) {
        return someConditionOn(methodName, filter);
    }
}
----

For an example, see `net.openhft.chronicle.wire.MethodFilterOnFirstArgTest`.

=== Intercepting `MethodReader` calls

You may wish to intercept handling a call in the method reader in order to execute additional logic, to record a call somewhere for monitoring purposes, or to even skip the original method invocation.

==== Intercepting by passing control over the original method call

`MethodReader` provides a flexible feature for supporting all the above use cases -- the option to specify `MethodReaderInterceptorReturns`.
If set, it will be triggered *instead* of the original call. It's possible to either skip the original method or to call it via passed `Invocation` instance:

[source,Java]
----
class MyInterceptor implements MethodReaderInterceptorReturns {
    @Override
    Object intercept(Method m, Object o, Object[] args, Invocation invocation) throws InvocationTargetException {
        // Execute any logic you want before the call
        if (some_condition)
            invocation.invoke(m, o, args); // Invoke the original method if needed
        // Execute any logic you want after the call
    }
}
----

==== Intercepting by modifying `MethodReader` generated source code

`GeneratingMethodReaderInterceptorReturns` allows to change the logic of `MethodReader` without an overhead provided by reflexive calls.

Code returned by `codeBeforeCall` and `codeAfterCall` will be added before and after actual method call in the generated source code of the method reader. It's possible to use original call arguments and object instance in the added code.

Simple example that enforces skipping the original call in case the second agrument is `null`:

[source,Java]
----
class SkippingInterceptor implements GeneratingMethodReaderInterceptorReturns {
    @Override
    public String generatorId() {
        return "skipping";
    }

    @Override
    public String codeBeforeCall(Method m, String objectName, String[] argumentNames) {
        return "if (" + argumentNames[1] + " != null) {";
    }

    @Override
    public String codeAfterCall(Method m, String objectName, String[] argumentNames) {
        return "}";
    }
}
----
If the code provided by generating interceptor differs from the code provided by another generating interceptor, their `generatorId` should be different as well. It's needed to ensure re-compilation in case a new interceptor is passed.

See `MethodReaderInterceptorReturnsTest` for more examples.

=== Spring Boot and dynamic compilation in Chronicle Wire
Chronicle Wire's `MethodReader` and `MethodWriter` dynamically compile Java code to get around some limitations in Java's underlying proxy mechanism and to do this the Java platform's standard compilation mechanism is used. The platform compiler uses the classpath variable to look for classes in directories and JAR files, and is not able to make use of classloaders to find classes.
Spring Boot uses a custom deployment mechanism - all classes and JARs are deployed in a fat JAR and Spring's classloader can extract classes from this. In order for the compiler to be able to see classes from the fat JAR, the classes should be extracted onto the disk somewhere. This is easy if the classes are contained in a JAR (i.e. a JAR inside the fat JAR) - Spring can be made to extract the JAR to a temp directory, such as by configuring Maven Spring Boot plugin:

[source,xml]
----
<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <requiresUnpack>
            <dependency>
                <groupId>net.openhft</groupId>
                <artifactId>chronicle-bytes</artifactId>
            </dependency>
            <dependency>
                <groupId>net.openhft</groupId>
                <artifactId>chronicle-core</artifactId>
            </dependency>
            <dependency>
                <groupId>net.openhft</groupId>
                <artifactId>chronicle-wire</artifactId>
            </dependency>
        </requiresUnpack>
    </configuration>
</plugin>
----

This will allow the latest Chronicle-Wire to use classes in those JAR files.

Dynamic compilation may be also configured via Gradle Spring Boot plugin:

[source,groovy]
----
bootJar {
    requiresUnpack '**/chronicle-*.jar'
}
----

NOTE: For more information see link:https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#howto.build.extract-specific-libraries-when-an-executable-jar-runs[Extract Specific Libraries When an Executable JAR Runs] and link:https://docs.spring.io/spring-boot/docs/current/gradle-plugin/reference/html/#packaging-executable-configuring-unpacking[Spring Boot Gradle Plugin Reference Guide].

== Using MethodWriter and MethodReader

Chronicle Wire's `MethodWriter` is used for writing data, and `MethodReader` is used for then reading this data. However,
there are many use cases for them. One of many benefits to these are their ease of use.

In particular, link:https://vanilla-java.github.io/2016/03/23/Microservices-in-the-Chronicle-world-Part-1.html[this article] captures the simplicity of using `MethodWriter` and `MethodReader`.

In another example, link:https://dzone.com/articles/java-how-to-leverage-method-chaining-to-add-smart[here], we can see how written data could be sent as a streaming event over an Event-Driven architecture, and then a `MethodReader` could be used to read these streaming events.

These are also not limited to being used only within Chronicle Wire. With Chronicle Queue for instance, another example would be to have a `MethodWriter` that serialises and writes a method call to the out queue,
and a `MethodReader` that reads in the in queue for any methods implemented. For more detail about this example, see link:https://github.com/OpenHFT/Chronicle-Queue-Demo/blob/c1e128545e8f219daa186836ca58a07047436084/md-pipeline/src/main/java/org/trading/Runner.java[here].

== Uses of Chronicle Wire

Chronicle Wire can be used for:

* file headers
* TCP connection headers; where the optimal wire format that is actually used can be negotiated
* message/excerpt contents
* Chronicle Queue version 4.x and later
* the API for marshalling generated data types

== Similar projects

=== Simple Binary Encoding (SBE)

Simple Binary Encoding (SBE) is designed to be a more efficient replacement for FIX. It is not limited to FIX protocols, and can be easily extended by updating an XML schema.
It is simple, binary, and it supports C++ and Java.

XML, when it first started, did not use XML for its own schema files, and it is not insignificant that SBE does not use SBE for its schema either.
This is because it is not trying to be human-readable.
It has XML which, though standard, is not designed to be human-readable either.
Chronicle believes that it is a limitation that it does not naturally lend itself to a human-readable form.

The encoding that SBE uses is similar to binary; with field numbers and fixed-width types.

SBE assumes the field types, which can be more compact than Chronicle Wire's most similar option; though not as compact as others.

SBE has support for schema changes provided that the type of a field doesn't change.

=== Message Pack (`msgpack`)

Message Pack is a packed binary wire format which also supports `JSON` for human readability and compatibility.
It has many similarities to the binary (and `JSON`) formats of this library.
Chronicle Wire is designed to be human-readable first, based on `YAML`, and has a range of options to make it more efficient.
The most extreme being fixed position binary.

Message Pack has support for embedded binary, whereas Chronicle Wire has support for comments and hints, to improve rendering for human consumption.

The documentation looks well-thought-out, and it is worth emulating.

=== Comparison with Cap'n'Proto

|===============
| Feature                          | Wire Text              | Wire Binary         | Protobuf               | Cap'n Proto             | SBE                 | FlatBuffers
| Schema evolution                 | yes                    | yes                 | yes                    | yes                     | caveats             | yes
| Zero-copy                        | yes                    | yes                 | no                     | yes                     | yes                 | yes
| Random-access reads              | yes                    | yes                 | no                     | yes                     | no                  | yes
| Random-access writes             | yes                    | yes                 | no                     | ?                       | no                  | ?
| Safe against malicious input     | yes                    | yes                 | yes                    | yes                     | yes                 | opt-in / upfront
| Reflection / generic algorithms  | yes                    | yes                 | yes                    | yes                     | yes                 | yes
| Initialization order             | any                    | any                 | any                    | any                     | preorder            | bottom-up
| Unknown field retention          | yes                    | yes                 | yes                    | yes                     | no                  | no
| Object-capability RPC system     | yes                    | yes                 | no                     | yes                     | no                  | no
| Schema language                  | no                     | no                  | custom                 | custom                  | XML                 | custom
| Usable as mutable state          | yes                    | yes                 | yes                    | no                      | no                  | no
| Padding takes space on wire?     | optional               | optional            | no                     | optional                | yes                 | yes
| Unset fields take space on wire? | optional               | optional            | no                     | yes                     | yes                 | no
| Pointers take space on wire?     | no                     | no                  | no                     | yes                     | no                  | yes
| Pass-by-name (Dynamic Enums) | yes                     | no                  | no                     | no                     | no                  | no
| C++                              | yes                | planned             | yes                    | yes (C++11)*            | yes                 | yes
| Java                             | Java 8                 | Java 8              | yes                    | yes*                    | yes                 | yes
| C#                               | yes                    | yes                 | yes                    | yes*                    | yes                 | yes*
| Go                               | no                     | no                  | yes                    | yes                     | no                  | yes*
| Other languages                  | no                     | no                  | 6+                     | others*                 | no                  | no
| Authors' preferred use case      | distributed computing | financial / trading | distributed computing | platforms / sandboxing | financial / trading | games
|===============

NOTE: The `Binary YAML` format can be automatically converted to `YAML` without any knowledge of the schema, because the messages are self-describing.

NOTE: You can parse all the expected fields (if any) and then parse any remaining fields.
As `YAML` supports object field names (or keys), these could be strings or even objects as keys and values.

Based on https://capnproto.org/news/2014-06-17-capnproto-flatbuffers-sbe.html

NOTE: It is not clear what padding which does not take up space on the wire means.

== Design notes

See https://capnproto.org/news/2014-06-17-capnproto-flatbuffers-sbe.html for a comparison to other encoders.

=== Schema evolution

Wire optionally supports:

- field name changes
- field order changes
- capturing or ignoring unexpected fields
- setting of fields to the default, if not available
- raw messages can be longer or shorter than expected

The more flexibility, the larger the overhead in terms of CPU and memory.
Chronicle Wire allows you to dynamically pick the optimal configuration, and convert between these options.

=== Zero copy

Chronicle Wire supports zero-copy random access to fields, and direct-copy from in-memory to the network.
It also supports translation from one wire format to another.
For example, switching between fixed-length data and variable-length data.

=== Random Access

You can access a random field in memory, For example, in a `2TB` file, page-in/pull-into CPU cache, only the data relating to your read or write.

[options="header"]
|===============
| format | access style
| fixed-length binary | random access without parsing first
| variable-length binary | random access with partial parsing allowing you to skip large portions
| fixed-length text | random access with parsing
| variable-length text | no random access
|===============

Chronicle Wire references are relative to the start of the data contained, to allow loading in an arbitrary point in memory.

=== Safe against malicious input

Chronicle Wire has built in tiers of bounds checks to prevent accidental read/writing that corrupts the data.
It is not complete enough for a security review.

=== Reflection / generic algorithms

Chronicle Wire supports generic reading and writing of an arbitrary stream.
This can be used in combination with predetermined fields.
For example, you can read the fields you know about, and ask it to provide the fields that you do not.
You can also give generic field names like keys to a map as `YAML` does.

=== Initialization order

Chronicle Wire can handle unknown information like lengths, by using padding.
It will go back and fill in any data that it was not aware of when it was writing the data.
For example, when it writes an object, it does not know how long it is going to be, so it adds padding at the start.
Once the object has been written, it goes back and overwrites the length.
It can also handle situations where the length was more than needed; this is known as packing.

=== Unknown field retention

Chronicle Wire can read data that it did not expect, interspersed with data it did expect.
Rather than specify the expected field name, a `StringBuilder` is provided.

NOTE: There are times when you want to skip/copy an entire field or message, without reading any more of it.
This is also supported.

=== Object-maximumLimit RPC system

Chronicle Wire supports references based on name, number, or UUID. This is useful when including a reference to an object that the reader should look up by other means.

A common case is if you have a proxy to a remote object, and you want to pass or return this in an RPC call.

=== Schema language

Chronicle Wire's schema is not externalised from the code.
However, it is planned to use `YAML` in a format that it can parse.

=== Usable as mutable state

Chronicle Wire supports storing an application's internal state.
This will not allow it to grow or shrink.
You can't free any of it without copying the pieces that you need, and discarding the original copy.

=== Padding takes space on the wire

The Chronicle Wire format that is chosen determines if there is any padding on the wire.
If you copy the in-memory data directly, its format does not change.

If you want to drop padding, you can copy the message to a wire format without padding.
You can decide whether the original padding is to be preserved or not, if turned back into a format with padding.

We could look at supporting *Cap'n'Proto*'s zero-byte removal compression.

=== Un-set fields take space on the wire

Chronicle Wire supports fields with, and without, optional fields, and automatic means of removing them.
Chronicle Wire does not support automatically adding them back in, because information has been lost.

=== Pointers take space on the wire

Chronicle Wire does not have pointers, but it does have content-lengths which are a useful hint for random access and robustness; but these are optional.

== Working with IntelliJ

These templates can be added to IntelliJ to create simple getters and setters.

.Simple Getter
[source,velocity]
----
$field.type ##
${field.name}() {
  return $field.name;
}
----

.Simple Setter
[source,velocity]
----
#set($paramName = $helper.getParamName($field, $project))
$class.name ${field.name}($field.type $paramName) {
  this.$field.name = $paramName;
  return this;
}
----

== Why use Marshallable objects

Marshallable objects have been designed to allow you to

- write a simple POJO
- have the `toString()`, `hashCode()` and `equals(Object)` methods created for you.
- serialization to a human-readable format (based on YAML), as well as efficient binary formats.
- the string format for text and binary can be logged and reconstructed from the text or hexadecimal dump
- copying and conversion of data from one type to another

== Pojo LongConversionExample
The following is a simple example of a POJO with a nested data type in a List.

.A Simple Pojo without needing to define toString/hashCode/equals
[source,java]
----
import net.openhft.chronicle.wire.SelfDescribingMarshallable;

class MyPojo extends SelfDescribingMarshallable {
    String text;
    int num;
    double factor;

    public MyPojo(String text, int num, double factor) {
        this.text = text;
        this.num = num;
        this.factor = factor;
    }
}

class MyPojos extends SelfDescribingMarshallable {
    String name;
    List<MyPojo> myPojos = new ArrayList<>();

    public MyPojos(String name) {
        this.name = name;
    }
}
----

By extending `SelfDescribingMarshallable` the class has an implementation
for `readMarshallable(WireIn)`, `writeMarshallable(WireOut)` and from these
`toString()`, `hashCode()` and `equals(Object)`.  You only need to define the method
yourself for improved efficiency.  These default implementations can give you
2/3rds of the performance of hand coding but save time and potential errors
writing them yourself.

=== The toString()

An important feature of the `toString()` method is no information is lost.
The object can be reconstructed from the output of the `toString()` method.
This is useful for building sample data in unit tests for from a file.
It also means that you can take the dump of an object in a log file and reconstruct the original object.

[source, java]
----
MyPojos mps = new MyPojos("test-list");
mps.myPojos.add(new MyPojo("text1", 1, 1.1));
mps.myPojos.add(new MyPojo("text2", 2, 2.2));

System.out.println(mps); // <1>
----
<1> Uses the default `toString()` provided.

prints

[source, yaml]
----
!MyPojos {
  name: test-list,
  myPojos: [
    { text: text1, num: 1, factor: 1.1 },
    { text: text2, num: 2, factor: 2.2 }
  ]
}
----

You can take the same output and reconstruct the original object.

[source, java]
----
MyPojos mps2 = Marshallable.fromString(mps.toString());
assertEquals(mps, mps2); // <1>

String text = "!MyPojos {\n" +
        "  name: test-list,\n" +
        "  myPojos: [\n" +
        "    { text: text1, num: 1, factor: 1.1 },\n" +
        "    { text: text2, num: 2, factor: 2.2 }\n" +
        "  ]\n" +
        "}\n";
MyPojos mps3 = Marshallable.fromString(text);
assertEquals(mps, mps3); // <1>
----
<1> `SelfDescribingMarshallable` also provides a default `equals(Object)` and `hashCode()`

Finally, you can take data from a file and build the object.

[source, java]
----
MyPojos mps4 = Marshallable.fromFile("my-pojos.yaml");
assertEquals(mps, mps4);
----

== Self describing messages

When writing and reading from text, Marshallable are always self describing, however when using Binary there is two choices:
`SelfDescribingMarshallable` which is self describing in binary and `BytesInBinaryMarshallable` which uses raw values.

`SelfDescribingMarshallable` is slightly slower, and larger when writing but supports schema changes such as

- Adding fields.
- Removing fields
- Changing the order of fields
- Change the type of fields
- Dumbing as text without access to the class specification.

`BytesInBinaryMarshallable` is faster and more compact, however you need to add your own support for schema changes.
See the Code Generating section below.

=== Code Generation for Marshallable

Install the Code Generation plugin, and add a template in `File` -> `Settings` -> `Code Generation` as follows.

Use the `Add Member Dialog` button and `Exclude transient fields`

This will add more efficient code for Marshallable format.

[source]
.SelfDescribingMarshallable
----
#set($javaPsiFacade = $JavaPsiFacade.getInstance($project))
#set($global = $GlobalSearchScope.allScope($project))

@Override public void writeMarshallable(net.openhft.chronicle.wire.WireOut out) {
#if($class0.superName != "SelfDescribingMarshallable")
   super.writeMarshallable(out);
#end
#foreach( $member in $members )
    #set($memberType = $member.type.split("<").get(0))
    #set($type = $javaPsiFacade.findClass($memberType, $global))
    #if ($member.primitive)
        out.write("$member.name").write${StringUtil.capitalizeWithJavaBeanConvention($memberType)}($member.name);
    #else
        out.write("$member.name").object(${memberType}.class, $member.name);
    #end
#end
}

@Override public void readMarshallable(net.openhft.chronicle.wire.WireIn in) {
#if($class0.superName != "SelfDescribingMarshallable")
   super.readMarshallable(in);
#end
#foreach( $member in $members )
    #set($memberType = $member.type.split("<").get(0))
    #set($type = $javaPsiFacade.findClass($memberType, $global))
    #if ($member.primitive)
        $member.name = in.read("$member.name").read${StringUtil.capitalizeWithJavaBeanConvention($memberType)}();
    #else
        $member.name = in.read("$member.name").object($member.name, ${memberType}.class);
    #end
#end
}
----

[source]
.BytesInBinaryMarshallable
----
#set($javaPsiFacade = $JavaPsiFacade.getInstance($project))
#set($global = $GlobalSearchScope.allScope($project))

private static final int MASHALLABLE_VERSION = 1;

@Override public void writeMarshallable(net.openhft.chronicle.bytes.BytesOut<?> out) {
#if($class0.superName != "BytesInBinaryMarshallable")
   super.writeMarshallable(out);
#end
   out.writeStopBit(MASHALLABLE_VERSION);
#foreach( $member in $members )
   #set($memberType = $member.type.split("<").get(0))
   #set($type = $javaPsiFacade.findClass($memberType, $global))
   #if ($member.primitive)
       out.write${StringUtil.capitalizeWithJavaBeanConvention($memberType)}($member.name);
   #else
       out.writeObject(${memberType}.class, $member.name);
   #end
#end
}

@Override public void readMarshallable(net.openhft.chronicle.bytes.BytesIn<?> in) {
#if($class0.superName != "BytesInBinaryMarshallable")
   super.readMarshallable(in);
#end
   int version = (int) in.readStopBit();
   if (version == MASHALLABLE_VERSION) {
#foreach( $member in $members )
   #set($memberType = $member.type.split("<").get(0))
   #set($type = $javaPsiFacade.findClass($memberType, $global))
   #if ($member.primitive)
       $member.name = in.read${StringUtil.capitalizeWithJavaBeanConvention($memberType)}();
   #else
       $member.name = (${memberType})in.readObject(${memberType}.class);
   #end
#end
   } else {
       throw new IllegalStateException("Unknown version " + version);
   }
}
----

[source]
.BytesMarshallable
----
#set($javaPsiFacade = $JavaPsiFacade.getInstance($project))
#set($global = $GlobalSearchScope.allScope($project))

private static final int MASHALLABLE_VERSION = 1;

@Override public void writeMarshallable(net.openhft.chronicle.bytes.BytesOut<?> out) {
#if($class0.hasSuper)
   super.writeMarshallable(out); // <1>
#end
  out.writeStopBit(MASHALLABLE_VERSION);
#foreach( $member in $members )
   #set($memberType = $member.type.split("<").get(0))
   #set($type = $javaPsiFacade.findClass($memberType, $global))
   #if ($member.primitive)
       out.write${StringUtil.capitalizeWithJavaBeanConvention($memberType)}($member.name);
   #else
       out.writeObject(${memberType}.class, $member.name);
   #end
#end
}

@Override public void readMarshallable(net.openhft.chronicle.bytes.BytesIn<?> in) {
#if($class0.hasSuper)
   super.readMarshallable(in);
#end
   int version = (int) in.readStopBit();
   if (version == MASHALLABLE_VERSION) {
#foreach( $member in $members )
   #set($memberType = $member.type.split("<").get(0))
   #set($type = $javaPsiFacade.findClass($memberType, $global))
   #if ($member.primitive)
       $member.name = in.read${StringUtil.capitalizeWithJavaBeanConvention($memberType)}();
   #else
       $member.name = (${memberType})in.readObject(${memberType}.class);
   #end
#end
   } else {
       throw new IllegalStateException("Unknown version " + version);
   }
}
----
<1> You will have to remove this line if the class extends `AbstractBytesMarshallable`

=== JLBH Benchmark Performance

To explore the efficiency of the examples above, this link:https://github.com/OpenHFT/Chronicle-Wire/blob/develop/src/test/java/net/openhft/chronicle/wire/TriviallyCopyableJLBH.java[TrivallyCopyableJLBH.java] test was created.
As can be seen on lines 18-26, we have the ability to switch between running the TriviallyCopyable House (“House1”), the BinaryWire House (“House2”) or 'UNKNOWN'.Important to note is that trivially copyable objects were used in order to improve java serialisation speeds.For further understanding on trivially copyable objects, refer to link:https://dzone.com/articles/how-to-get-c-speed-in-java-serialisation[this article].
This shows that we can serialise and then de-serialise 100,000 messages in a second.The Trivially Copyable version is even faster, especially at the higher percentiles.

.Benchmark Performance Between TriviallyCopyable and BinaryWire
image::jlbhBenchmark.png[buffer,600,400]
* Microseconds to both serialise and deserialise a message

===  Platform support

Chronicle Wire supports `Java 8`, `Java 11` and `C++`.
Future versions may support `Java 14`, `python`.

'''

https://github.com/OpenHFT/Chronicle-Wire[Back to Chronicle Wire project]

== Network Channels in Wire

Chronicle Wire supports creating channels over TCP.
That `ChronicleChannel` acts as `MarshallableIn` and `MarshallableOut`, as `Wire` does, except that it writes to a TCP connection and reads from the same connection.

=== Simple ChronicleChannel - EchoHandler

When you create a channel, you specify what type of connection you want.
The simplest is an EchoHandler that echos everything you send it.

[source,java]
----
// start a server on an unused port
String url = "tcp://:0";
// create a context for new channels, all channels are closed when the context is closed
try (ChronicleContext context = ChronicleContext.newContext(url)) {
    // open a new channel that acts as an EchoHandler
    ChronicleChannel channel = context.newChannelSupplier(new EchoHandler()).get();
    // create a proxy that turns each call to Says into an event on the channel
    Says say = channel.methodWriter(Says.class);
    // add an event
    say.say("Hello World");
    // ad a second event
    say.say("Bye now");

    // A buffer so the event name can be returned as well
    StringBuilder event = new StringBuilder();
    // read one message excepting the object after the event name to be a String
    String text = channel.readOne(event, String.class);
    // check it matches
    assertEquals("say: Hello World", event + ": " + text);

    // read the second message
    String text2 = channel.readOne(event, String.class);
    // check it matches
    assertEquals("say: Bye now", event + ": " + text2);
}
----


PlayN
=====

PlayN is a cross-platform Java game development library written in [Java] that targets HTML5
browsers (via [GWT]), desktop JVMs, [Android] and [iOS] devices.

Information on PlayN can be found in this README and on the [PlayN project website].

PlayN developers, contributors, and users regularly communicate on the [PlayN Google Group].

Building and Running
--------------------

It is not necessary to build PlayN to use it. PlayN is shipped to [Maven Central] from where it
will be automatically downloaded by projects that use it. However, you still may find it useful to
build a local copy of PlayN in case you need to modify it when debugging your own game, to add new
features, or to fix bugs you find in the PlayN code.

Building PlayN locally is very easy using [Maven]:

```
cd playn
mvn clean install
```

This will install the latest snapshot version of PlayN into your local Maven repository. You can
then modify the `playn.version` property of your game to reference that snapshot version and your
game will use your local copy of PlayN instead of a version downloaded from [Maven Central].

Instructions for building and running the PlayN sample games can be found in the [Documentation].

Licensing
---------

Unless otherwise stated, all source files are licensed under the Apache License, Version 2.0:

```
Copyright 2011-2015 The PlayN Authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this
file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
ANY KIND, either express or implied. See the License for the specific language
governing permissions and limitations under the License.
```

[Android]: http://www.android.com/
[Documentation]: http://playn.github.io/docs/
[GWT]: http://code.google.com/webtoolkit/
[Java]: http://www.java.com/
[Maven Central]: http://search.maven.org/
[Maven]: http://maven.apache.org/
[PlayN Google Group]: http://groups.google.com/group/playn
[PlayN project website]: http://playn.github.io/
[iOS]: https://developer.apple.com/devcenter/ios/index.action


# Artio

[![Actions Status](https://github.com/real-logic/artio/workflows/Continuous%20Integration/badge.svg)](https://github.com/real-logic/artio/actions)
[![CodeQL Status](https://github.com/real-logic/artio/workflows/CodeQL/badge.svg)](https://github.com/real-logic/artio/actions)
[![GitHub](https://img.shields.io/github/license/real-logic/Aeron.svg)](https://github.com/real-logic/aeron/blob/master/LICENSE)

High-Performance FIX Gateway

Please check out the [Wiki](https://github.com/real-logic/artio/wiki).

## How to build

Just run the standard Gradle build and install process:

```
    ./gradlew
```

After the first build this is all that is required.

## Downloading

Binaries can be found on [Maven Central](https://central.sonatype.com/search?q=artio&namespace=uk.co.real-logic)


# ROBOT is an OBO Tool

[![Java CI](https://github.com/ontodev/robot/workflows/Java%20CI/badge.svg?branch=master)](https://github.com/ontodev/robot/actions?query=branch%3Amaster)
[![Maven Central](https://img.shields.io/maven-central/v/org.obolibrary.robot/robot.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22org.obolibrary.robot%22%20AND%20a:%22robot%22)
[![Javadocs](https://www.javadoc.io/badge/org.obolibrary.robot/robot-core.svg)](https://www.javadoc.io/doc/org.obolibrary.robot/robot-core)

ROBOT is a command-line tool and library for automating ontology development tasks, with a focus on [Open Biological and Biomedical Ontologies (OBO)](http://obofoundry.org).

### Cite ROBOT

R.C. Jackson, J.P. Balhoff, E. Douglass, N.L. Harris, C.J. Mungall, and J.A. Overton. [ROBOT: A tool for automating ontology workflows](https://rdcu.be/bMnHT). BMC Bioinformatics, vol. 20, July 2019.

### Installation and Usage

Please see <http://robot.obolibrary.org>.

## Build

We use [Maven](http://maven.apache.org) as our build tool. Make sure it's [installed](http://maven.apache.org/download.cgi), then run:

    mvn clean package

This will create a self-contained Jar file in `bin/robot.jar`.

Other build options:

- `mvn clean test` runs JUnit tests with reports in `[module]/target/surefire-reports`
- `mvn clean verify` rebuilds the package and runs integration tests against it, with reports in `[module]/target/failsafe-reports`
- `mvn site` generates Javadoc in `target/site` and `[module]/target/site`

Alternatively, you can use [Docker](https://www.docker.com) with the provided [Dockerfile](Dockerfile) to build and run ROBOT from within a container. First build an image with `docker build --tag robot .` then run ROBOT from the container with the usual command-line arguments: `docker run --rm robot --help`.

## Code Style

We use [Google Java Style](https://google.github.io/styleguide/javaguide.html), automatically enforced with [google-java-format](https://github.com/google/google-java-format) and [fmt-maven-plugin](https://github.com/coveo/fmt-maven-plugin). You may want to use the [styleguide configuration file](https://github.com/google/styleguide) for [Eclipse](https://github.com/google/styleguide/blob/gh-pages/eclipse-java-google-style.xml) or [IntelliJ](https://github.com/google/styleguide/blob/gh-pages/intellij-java-google-style.xml).

## Design

The library provides a set of Operations and a set of Commands. Commands handle the command-line interface and IO tasks, while Operations focus on manipulating ontologies. Sometimes you will have the pair of an Operation and a Command, but there's no necessity for a one-to-one correspondence between them.

Commands implement the Command interface, which requires a `main(String[] args)` method. Each command can be called via `main`, but the CommandLineInterface class provides a single entry point for selecting between all the available commands. While each Command can run independently, there are shared conventions for command-line options such as `--input`, `--prefix`, `--output`, etc. These shared conventions are implemented in the CommandLineHelper utility class. There is also an IOHelper class providing convenient methods for loading and saving ontologies and lists of terms. A simple Command will consist of a few CommandLineHelper calls to determine arguments, a few IOHelper calls to load or save files, and one call to the appropriate Operation.

Operations are currently implemented with static methods and no shared interface. They should not contain IO or CLI code.

The current implementation is modular but not pluggable. In particular, the CommandLineInterface class depends on a hard-coded list of Commands.

## Term Lists

Many Operations require lists of terms. The IOHelper class defines methods for collecting lists of terms from strings and files, and returning a `Set<IRI>`. Our convention is that a term list is a space-separated list of IRIs or CURIEs with optional comments. The "#" character and everything to the end of the line is ignored. Note that a "#" must start the line or be preceded by whitespace -- a "#" inside an IRI does not start a comment.

## Acknowledgments

The initial version of ROBOT was developed by James A. Overton, based on requirements and designs given by Chris Mungall, Heiko Dietze and David Osumi-Sutherland. This initial version was funded by P41 grant 5P41HG002273-09 to the Gene Ontology Consortium. Current support is from NIH grant 1 R24 HG010032-01, “Services to support the OBO foundry standards” to C. Mungall and B. Peters.

## Copyright

The copyright for ROBOT code and documentation belongs to the respective authors. ROBOT code is distributed under a [BSD3 license](https://github.com/ontodev/robot/blob/master/LICENSE.txt). Our `pom.xml` files list a number of software dependencies, each with its own license.


[![Build Status](https://travis-ci.org/owlcollab/owltools.svg?branch=master)](https://travis-ci.org/owlcollab/owltools)
[![DOI](https://zenodo.org/badge/13996/owlcollab/owltools.svg)](https://zenodo.org/badge/latestdoi/13996/owlcollab/owltools)

For full documentation,

 * [see the Wiki](https://github.com/owlcollab/owltools/wiki).
 * [see the java API docs](https://owlcollab.github.io/owltools)

## OWLTools Build Instructions

The OWLTools use maven as a build tool.

These instructions assume that a valid maven installation is available. The recommended maven version is 3.0.x, whereby x denotes the latest release for this branch.

Update: OWLTools also requires `git`. Only a proper clone via git, will allow the build to complete.

During the build process, we extract the git version and branch information. These details (and the build date) will be added to the manifest of the jar. If the `.git` folder is not available the build process will fail.

### Building OWLTools

#### Prerequiste: Get source from Git

`git clone https://github.com/owlcollab/owltools.git`

#### Option 1: Command line

1) Change into to the folder of `OWLTools-Parent`

2a) Run command: `mvn clean install`: This will trigger a complete build of all OWLTools projects and generate the required jars for execution. Remark: As part of the build the tests are executed. Any failed test will stop the build.

2b) Build without test execution (Not Recommended): Run command: mvn clean install -DskipTests

#### Option 2: Eclipse

Requires either:
* Eclipse 3.7
* Eclipse 3.6 with installed maven plugin m2e

Use the provided Eclipse launch configurations to trigger the build. The configuration are located in the `OWLTools-Parent/eclipse-configs` folder.

## Downloading OWLTools

You can download a pre-built JAR and script-wrapper instead of building owltools from the Java source. You can find releases on the [OWLTools GitHub releases page](https://github.com/owlcollab/owltools/releases).

Note: you may need to make this file executable. Occasionally when downloaded files lose the "executable" permisison. You can do this with `chmod +x owltools`.

If you add this to your [PATH](https://en.wikipedia.org/wiki/PATH_(variable)), you can run owltools on the command line:

```
export PATH=$PATH:directory/to/where/you/downloaded/owltools/
owltools -h
```

## Running OWLTools (Unix and MacOS)

Running OWLTools requires a successful build, as described in the previous section.

+ OWLTools Command-Line Tools: The build produces a combined executable bash script and jar, to be found in `OWLTools-Runner/bin`
or in the `OWLTools-Runner/target` directory

+ OORT: The executables and the generated jar are both located in `OWLTools-Oort/bin`


# edison-microservice

Collection of independent libraries on top of Spring Boot to provide a faster setup of jvm microservices.

> "I never did anything by accident, nor did any of my inventions come by accident; they came by work." - Thomas Edison

## Status

[![Build](https://github.com/otto-de/edison-microservice/workflows/Build/badge.svg?branch=master)](https://github.com/otto-de/edison-microservice/actions?query=workflow%3ABuild)
[![codecov](https://codecov.io/gh/otto-de/edison-microservice/branch/master/graph/badge.svg)](https://codecov.io/gh/otto-de/edison-microservice)
[![Known Vulnerabilities](https://snyk.io/test/github/otto-de/edison-microservice/badge.svg)](https://snyk.io/test/github/otto-de/edison-microservice)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/otto-de/edison-microservice/badge)](https://securityscorecards.dev/viewer/?uri=github.com/otto-de/edison-microservice)
[![Maven Central](https://img.shields.io/maven-central/v/de.otto.edison/edison-core?label=maven-central)](https://search.maven.org/search?q=g:de.otto%20a:edison-core%20v:RELEASE%20p:jar)
[![license](https://img.shields.io/github/license/otto-de/edison-microservice.svg)](./LICENSE)

Have a look at the [release notes](CHANGELOG.md) for details about updates and changes.

## About

This project contains a number of independent libraries on top of Spring Boot to provide a faster setup of jvm microservices.
The libraries are used in different projects at OTTO.
It's purpose is to provide a common implementation for cross-cutting requirements like:

* Health checks that are used to tell the load balancer or mesos platform whether or not a service is healthy.
* A [status page/document](https://github.com/otto-de/edison-microservice/tree/master/edison-core) that is used to give information about the current state of the service. Status information also include details about sub-components, background jobs like imports, and so on.
* A simple job handling library that is used to run asynchronous background jobs, which for example can be used to run data imports from other systems.
* An optional MongoDB-based implementation of a JobRepository
* Support for MongoDB-based repositories in case you do not like Spring Data
* Support for feature toggles based on [Togglz](https://www.togglz.org/)

... plus all the features of [Spring Boot](http://projects.spring.io/spring-boot/).

## Releases

[Semantic Versioning v2.0.0](http://semver.org/spec/v2.0.0.html) is used to specify the version numbers.

This project maintains its roadmap with [issues](https://github.com/otto-de/edison-microservice/issues) and [milestones](https://github.com/otto-de/edison-microservice/milestones).

**2.7.x**: Edison Microservices for Spring Boot 2.7.x ✔ - Compatible with Java 11 and greater

**3.0.x**: Edison Microservices for Spring Boot 3.0.x ✔ - Compatible with Java 17 and greater

**3.1.x**: Edison Microservices for Spring Boot 3.1.x ✔ - Compatible with Java 17 and greater

**3.2.x**: Edison Microservices for Spring Boot 3.2.x ✔ - Compatible with Java 17 and greater

## Migration from Edison 2 to Edison 3

In edison-ldap, whitelisted-paths was replaced with allowlisted-paths.
Everything else should be ok if you follow the Spring Boot 2 -> 3 migration guide:
https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-3.0-Migration-Guide

## Migration from Edison 1.x to Edison 2

Edison 2 has several breaking changes that will make a refactoring of your current application necessary. For a list of
the actual changes, please take a look at the [Changelog](CHANGELOG.md).

When migrating, take care of the following adjustments:

* Follow the [Spring Boot 2.0 Migration Guide](https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-2.0-Migration-Guide)
  to fix the most common problems.
    * If you want to use the behaviour of Edison 1.x, which hosts all management endpoints below `/internal`, you have to
      configure `management.endpoints.web.base-path=/internal` in your `application.yml`
* Remove dependencies to the [edison-aws Project](https://github.com/otto-de/edison-aws), which will be deprecated some time in the future.
  Necessary functionality was transferred to a submodule of `edison-microservice` (named `edison-aws`).
* If you have used `gradlew bootRepackage` for packaging your application so far, you have to migrate this to `gradlew bootJar`.
* Refactor calls made through the AWS SDK, which got updated in the process of the new major version of edison and this
  will most probably break prior code that relied on the AWS SDK.
* To use `@Timed`-Annotations, you need to configure Micrometer accordingly. See the following Example for a configuration that
  covers the annotation and naming of all metrics:

  ```java
    @Configuration
    @EnableAspectJAutoProxy
    public class MicrometerConfiguration {

        @Bean
        public PrometheusNamingConvention prometheusNamingConvention() {
            return new PrometheusNamingConvention();
        }

        @Bean
        public MeterRegistryCustomizer<MeterRegistry> metricsCommonTags(@Value("${service.vertical}") final String vertical,
                                                                        @Value("${service.name}") final String serviceName,
                                                                        final PrometheusNamingConvention prometheusNamingConvention) {
            return registry -> registry
                    .config()
                    .namingConvention(new NamingConvention() {
                        // Set naming convention that gets applied to all metrics, in this  example explicitly using a Prometheus naming convention
                        @Override
                        public String name(final String name, final Meter.Type type, final String baseUnit) {
                            return prometheusNamingConvention.name(String.format("%s.%s.%s", vertical, serviceName, name), type, baseUnit);
                        }
                    })
                    .meterFilter(new MeterFilter() { // Configure generally applicable configurations, like percentiles
                        @Override
                        public DistributionStatisticConfig configure(final Meter.Id id,
                                                                     final DistributionStatisticConfig config) {
                            return config.merge(DistributionStatisticConfig.builder()
                                    .percentiles(0.5, 0.9, 0.95, 0.98, 0.99, 0.999)
                                    .build());
                        }
                    });
        }

        // Create a `TimedAspect` to enable `@Timed`-Annotations
        @Bean
        public TimedAspect timedAspect(final MeterRegistry registry) {
            return new TimedAspect(registry);
        }
    }

  ```

## Documentation

Edison Modules:
* [`edison-aws`](edison-auth-aws/README.md): AWS related configuration and togglz settings
* [`edison-core`](edison-core/README.md): Main library of Edison microservices.
* [`edison-jobs`](edison-jobs/README.md): Optional module providing a simple job library.
* [`edison-mongo`](edison-mongo/README.md): Auto-configuration for MongoDB repositories plus implementation of MongoJobRepository and Togglz StateRepository.
* [`edison-oauth`](edison-oauth/README.md): Auto-configuration for OAuth Public Key repositories with autofetching and a simple JWT Token Validation.
* [`edison-togglz`](edison-togglz/README.md): Optional support for feature toggles for Edison microservices based on [Togglz](https://www.togglz.org/).
* `edison-testsupport`: Test support for feature toggles plus utilities.
* [`edison-validation`](edison-validation/README.md): Optional module for validation in Spring with a specific response format.

Examples:
* [`example-status`](examples/example-status): Service only relying on `edison-core` to show the usage of health and status features.
* [`example-jobs`](examples/example-jobs): Edison service using edison-jobs to run background tasks.
* [`example-togglz`](examples/example-togglz): Example using `edison-togglz´ to implement feature toggles.
* [`example-togglz-mongo`](examples/example-togglz-mongo): Same `edison-toggz`, but with a MongoDB configuration to auto-configure persistence of feature toggles.

## Setup

Make sure you have Java 11 or later and gradle 6.x installed on your computer.

### Testing

Test and create coverage report

    gradle check

### Dependency Update

Determine possible dependency updates

    gradle dependencyUpdates -Drevision=release

### Publishing

#### Publish new releases to sonatype

    ./release.sh

#### Create a release in github
Click on "Releases" -> "Draft a new release". Create a tag and copy&paste the relevant info from the changelog.<br/>
Don't publish packages to github. They are published to sonatype.

## Examples

There are a few examples that may help you to start your first microservice based
on Edison and Spring Boot. Because Spring Boot itself has some complexity, it is
recommended to first read its documentation before starting with Edison.

The examples can be started with gradle:

    gradle examples:example-status:bootRun
    gradle examples:example-jobs:bootRun
    gradle examples:example-togglz:bootRun
    gradle examples:example-togglz-mongo:bootRun

Open in your browser [http://localhost:8080/](http://localhost:8080/)

*Note:* Every example is configured to use port 8080, so make sure to run only one example at a time or to reconfigure
the ports.

## Contributing

Have a look at our [contribution guidelines](CONTRIBUTING.md).


# Arend proof assistant

![](https://arend-lang.github.io/assets/images/Logo_byJB.svg)

[![JetBrains offical project](https://jb.gg/badges/official.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub)
[![Actions Status](https://github.com/JetBrains/Arend/workflows/gradle/badge.svg)](https://github.com/JetBrains/Arend/actions)
[![Gitter](https://badges.gitter.im/arend-lang/community.svg)](https://gitter.im/arend-lang/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
[![](https://jitpack.io/v/JetBrains/Arend.svg)](https://jitpack.io/#JetBrains/Arend)

Arend is a theorem prover and a programming language based on [Homotopy Type Theory](https://ncatlab.org/nlab/show/homotopy+type+theory).

+ For more information about the Arend language,
  visit [arend-lang.github.io](https://arend-lang.github.io/)
  or the [documentation](https://arend-lang.github.io/documentation/).
+ For instructions on building Arend locally, general description of the codebase,
  there's [ARCHITECTURE.md](ARCHITECTURE.md).
+ For community forums, checkout [this link](https://arend-lang.github.io/documentation/#forums).
+ For editing Arend code, we suggest [IntelliJ Arend](https://plugins.jetbrains.com/plugin/11162-arend)
  ([instructions](https://arend-lang.github.io/documentation/getting-started#intellij-arend)).
+ The standard library of Arend is [here](https://github.com/JetBrains/arend-lib).
  It serves as a math library.

## Usage

### As a binary

You can find release version of Arend binary (a jar file named "Arend.jar")
in the [release](https://github.com/JetBrains/Arend/releases) page.
The Arend jar can be used to typecheck a library:

```bash
$ java -jar Arend.jar [path-to-library]
```

You can also start a REPL:

```bash
$ java -jar Arend.jar -i
```

If you start the REPL at the root directory of a library, the REPL will load the library.
For more information and usage about command line usage of Arend, please refer to `--help`:

```bash
$ java -jar Arend.jar -h
```

### As a library

Arend is under active development, so you may expect to depend your project on
a development version of Arend,
either a certain git revision or the SNAPSHOT version.
This is possible via [JitPack](https://jitpack.io/#JetBrains/Arend/-SNAPSHOT),
simply add this to your `build.gradle`:

```groovy
repositories {
    maven { url 'https://jitpack.io' }
}
dependencies {
    // The version of Arend -- can be a short revision, "[branch]-SNAPSHOT",
    // "-SNAPSHOT", or a tag (or a release, like "v1.4.0").
    String arendVersion = "master-SNAPSHOT"
    // Open API for writing Arend extensions
    implementation "com.github.JetBrains.Arend:api:$arendVersion"
    // The generated ANTLR parser
    implementation "com.github.JetBrains.Arend:parser:$arendVersion"
    // The generated protobuf classes
    implementation "com.github.JetBrains.Arend:proto:$arendVersion"
    // The main compiler
    implementation "com.github.JetBrains.Arend:base:$arendVersion"
}
```

In case you prefer Gradle Kotlin DSL,
use the following syntax in your `build.gradle.kts`:

```kotlin
repositories {
    maven("https://jitpack.io")
}
dependencies {
    // The version of Arend
    val arendVersion = "master-SNAPSHOT"
    implementation("com.github.JetBrains.Arend:api:$arendVersion")
    implementation("com.github.JetBrains.Arend:parser:$arendVersion")
    implementation("com.github.JetBrains.Arend:proto:$arendVersion")
    implementation("com.github.JetBrains.Arend:base:$arendVersion")
}
```