io7m.com | software | jattribute

---

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

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.