Project icon

com.io7m.jattribute

Build status Maven Central Codecov

The jattribute package provides a simple abstraction that exposes a mutable variable as an observable value. Consumers can subscribe to attribute values and are notified when values change.

Contents

Features

  • Type-safe, mutable, observable values.
  • Tiny codebase.
  • 100% automated test suite coverage.
  • OSGi ready.
  • JPMS ready.
  • ISC license.

Releases

The most recently published version of the software is 0.0.1.

Source code and binaries are available from the repository.

Documentation

Documentation for the 0.0.1 release is available for reading online.

Documentation for current and older releases is archived in the repository.

Usage

Create an instance of the Attributes class to create new attributes. The class takes a function as an argument that will receive exceptions raised by subscribers.

    var attributes = Attributes.create(e -> LOG.error("exception raised: ", e));
    
  

Creating Attributes

Use the attributes instance to create new attribute values. The values held in an attribute should be of an immutable class. This is not strictly required, but the purpose of attributes is ostensibly to communicate state updates to consumers, and mutating a value held in an attribute will not cause subscribers to be notified that anything has changed.

The following code creates an integer-typed attribute initialized with a value of 23:

    var ival = attributes.create(23);
    
  

Attributes implement the AttributeType interface, which allows for both reading and writing values. AttributeType is a subtype of AttributeReadableType, which is a read-only interface. Code that should not be allowed to write to an attribute can be passed the attribute as a value of type AttributeReadableType.

Attributes are thread-safe and can be written to and read from any number of threads.

Subscribing To Attributes

Consumers can subscribe to state updates. Subscribing to an attribute creates a subscription that must be closed when no longer needed. Subscriptions create strong references, and so can prevent attributes from being garbage collected. It's important to be aware of this in applications that are frequently creating and discarding attributes.

    var sub = ival.subscribe((oldValue, newValue) -> { ... });
    
  

Subscriptions implement AutoCloseable and can therefore be used with try-with-resources:

    try (var sub = ival.subscribe((oldValue, newValue) -> { ... })) { ... }
    
  

If a subscriber raises an exception on receipt of a state update, the subscriber's subscription is automatically closed. The exception raised will be delivered to the function passed to the Attributes class above. The rationale for this is that the client that modified the attribute should not receive an exception if one of the subscribers failed to handle the state update properly, and none of the other subscribers should be subjected to the errors of one failing subscriber. The failing subscriber failed to handle the exception, and we don't want to just discard the exception silently.

Subscriber functions are called on the same thread that updated the attribute.

Updating Attributes

Use the set method to update the value held in an attribute.

    ival.set(25);
    
  

All subscribers to ival will be notified immediately that the value has changed from 23 to 25.

Transforming Attributes

Attributes are functors, and so the map method (mapR for read-only attributes) can be used to produce a new attribute K that will transform values from an existing attribute M each time M is updated.

    var dval = ival.map(i -> (double) i);
    
  

Each time ival is updated, the subscribers of dval will see the transformed value in state updates. Subscribers of ival are not automatically subscribed to dval; conceptually, it is an entirely new and distinct attribute.

Maven

The following is a complete list of the project's modules expressed as Maven dependencies:

<dependency>
  <groupId>com.io7m.jattribute</groupId>
  <artifactId>com.io7m.jattribute</artifactId>
  <version>0.0.1</version>
</dependency>

<dependency>
  <groupId>com.io7m.jattribute</groupId>
  <artifactId>com.io7m.jattribute.core</artifactId>
  <version>0.0.1</version>
</dependency>

<dependency>
  <groupId>com.io7m.jattribute</groupId>
  <artifactId>com.io7m.jattribute.tests</artifactId>
  <version>0.0.1</version>
</dependency>

Each release of the project is made available on Maven Central within ten minutes of the release announcement.

Changes

Subscribe to the releases atom feed.

No formal releases have been made.

Sources

This project uses Git to manage source code.

Repository: https://www.github.com/io7m/jattribute

$ git clone https://www.github.com/io7m/jattribute

License

Copyright © 2022 Mark Raynsford <code@io7m.com> https://www.io7m.com

Permission to use, copy, modify, and/or distribute this software for
any purpose with or without fee is hereby granted, provided that the
above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR
BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES
OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
SOFTWARE.

Bug Tracker

The project uses GitHub Issues to track issues.