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.
Releases & Development Snapshots
Releases
You can subscribe to the atom feed to be notified of project releases.
The most recently released version of the package is 1.0.1.
1.0.1 Release (2024-09-06Z)
- Update jqwik.version:1.8.4 → 1.8.5.
- Update junit.version:5.10.2 → 5.10.3.
- Update jqwik.version:1.8.5 → 1.9.0.
- Update org.slf4j:slf4j-api:2.0.13 → 2.0.14.
- Update org.slf4j:slf4j-api:2.0.14 → 2.0.15.
- Update org.slf4j:slf4j-api:2.0.15 → 2.0.16.
- Update junit.version:5.10.3 → 5.11.0.
- Update ch.qos.logback:logback-classic:1.5.6 → 1.5.7.
The compiled artifacts for the release (and all previous releases) are available on Maven Central.
Maven Modules
<dependency> <group>com.io7m.jattribute</group> <artifactId>com.io7m.jattribute.core</artifactId> <version>1.0.1</version> </dependency><dependency> <group>com.io7m.jattribute</group> <artifactId>com.io7m.jattribute.tests</artifactId> <version>1.0.1</version> </dependency>
Previous Releases
The changelogs for the most recent previous releases are as follows:
1.0.0 Release (2024-05-10Z)
- Initial public release.
Development Snapshots
At the time of writing, the current unstable development version of the package is 1.0.2-SNAPSHOT.
Development snapshots may be available in the Central Portal Snapshots repository. Snapshots are published to this repository every time the project is built by the project's continuous integration system, but snapshots do expire after around ninety days and so may or may not be available depending on when a build of the package was last triggered.
Manual
This project does not have any user manuals or other documentation beyond what might be present on the page above.
Sources
This project uses Git to manage source code.
Repository: https://www.github.com/io7m-com/jattribute
$ git clone --recursive https://www.github.com/io7m-com/jattribute
Issues
This project uses GitHub Issues to track issues.
License
Copyright © 2023 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.