/** * Classes with a non-reentrant lock should implement this interface. */ @Mutable public interface Locking { /** * Returns whether the lock is held by the current thread. */ @Pure public boolean isLockHeldByCurrentThread(); }
/** * The root class for all custom classes whose initialization does not throw a checked exception. */ @Mutable public abstract class RootClass extends RootClassWithException<RuntimeException> {}
/** * Extends Java's {@link java.util.Set} interface. * * @param <E> the type of the elements of this set. * * @see ConcurrentHashSet */ @Mutable public interface ConcurrentSet<E> extends Set<E> {}
/** * This interface allows to validate the invariant of implementing classes. */ @Mutable public interface Validatable { /** * Validates the invariant and all non-private fields of this object. * Typically, the programmer implements this method to check all non- * trivial invariants which cannot be expressed through annotations * and the field checks are generated by an annotation processor in * a subclass by overriding this method and calling the supermethod. * * @throws InvariantException if the invariant is violated. */ @Pure @CallSuper public default void validate() {} }
/** * This interface provides an easy way to cast an object to a subclass. */ @Mutable public interface Castable { /* -------------------------------------------------- Casting -------------------------------------------------- */ /** * Casts this object to the given target class. * * @require targetClass.isInstance(this) : "This object is an instance of the given target class."; */ @Pure public default @Chainable <T> @Nonnull T castTo(@Nonnull Class<T> targetClass) { Require.that(targetClass.isInstance(this)).orThrow("This object $ has to be an instance of the target class $.", this, targetClass); return targetClass.cast(this); } }
/** * All custom interfaces in the Digital ID Library extend this root interface. * * @see RootClass */ @Mutable public interface RootInterface extends Castable, Validatable { /* -------------------------------------------------- Object -------------------------------------------------- */ // The following methods will always be implemented by classes but are important when generating an implementation directly from an interface. @Pure @Override public boolean equals(@Nullable Object object); @Pure @Override public int hashCode(); @Pure @Override public @Nonnull String toString(); }
/** * This class implements an iterator that returns only read-only entries. */ @Mutable public class ReadOnlyEntrySetIterator<K, V> extends ReadOnlyIterableIterator<Map.@Nonnull Entry<K, V>> { /* -------------------------------------------------- Constructors -------------------------------------------------- */ protected ReadOnlyEntrySetIterator(@Captured @Nonnull Iterator<? extends Map.@Nonnull Entry<K, V>> iterator) { super(iterator); } /* -------------------------------------------------- Operations -------------------------------------------------- */ @Impure @Override public @Nonnull ReadOnlyEntry<K, V> next() { return new ReadOnlyEntry<>(super.next()); } }
/** * An import group collects all the import statements of a given prefix. */ @Mutable private static class ImportGroup { final @Nonnull String prefix; ImportGroup(@Nonnull String prefix) { this.prefix = prefix; } final @Nonnull Set<@Nonnull String> imports = new HashSet<>(); }
/** * This interface models an iterator that returns an infinite number of elements. */ @Mutable public abstract class InfiniteIterator<@Specifiable ELEMENT> extends ReadOnlyIterator<ELEMENT> { /* -------------------------------------------------- Overridden Operations -------------------------------------------------- */ @Pure @Override public final boolean hasNext() { return true; } }
/** * This annotation processor generates the service loader entry for other annotation processors. */ @Mutable @SupportedAnnotations(SupportedAnnotations.class) public class ProcessorProcessor extends CustomProcessor { /* -------------------------------------------------- Processing -------------------------------------------------- */ @Impure @Override public void processFirstRound(@Nonnull FiniteIterable<@Nonnull ? extends TypeElement> annotations, @Nonnull RoundEnvironment roundEnvironment) { final @Nonnull ServiceFileGenerator serviceLoaderFile = ServiceFileGenerator.forService(Processor.class); for (@Nonnull Element annotatedElement : roundEnvironment.getElementsAnnotatedWith(SupportedAnnotations.class)) { serviceLoaderFile.addProvider(annotatedElement); } serviceLoaderFile.write(); } }
/** * Objects that implement this interface can be used to {@link Property#register(net.digitalid.utility.property.Observer) observe} {@link ReadOnlyVolatileValueProperty volatile value properties}. */ @Mutable @Functional public interface VolatileValueObserver<@Specifiable VALUE> extends ValueObserver<VALUE, RuntimeException, RuntimeException, VolatileValueObserver<VALUE>, ReadOnlyVolatileValueProperty<VALUE>> {}
/** * This class implements an iterator which is based on a single iterator. * * @see DoubleIteratorBasedIterator */ @Mutable public abstract class SingleIteratorBasedIterator<@Specifiable OUTPUT, @Specifiable INPUT0> extends ReadOnlyIterator<OUTPUT> { /* -------------------------------------------------- Primary Iterator -------------------------------------------------- */ /** * Stores the primary iterator on which this iterator is based. */ protected final @Nonnull Iterator<? extends INPUT0> primaryIterator; /* -------------------------------------------------- Constructors -------------------------------------------------- */ protected SingleIteratorBasedIterator(@Captured @Nonnull Iterator<? extends INPUT0> primaryIterator) { this.primaryIterator = primaryIterator; } }
/** * This class implements an iterator which is based on a primary and a secondary iterator. */ @Mutable public abstract class DoubleIteratorBasedIterator<@Specifiable OUTPUT, @Specifiable INPUT0, @Specifiable INPUT1> extends SingleIteratorBasedIterator<OUTPUT, INPUT0> { /* -------------------------------------------------- Secondary Iterator -------------------------------------------------- */ /** * Stores the secondary iterator on which this iterator is based. */ protected final @Nonnull Iterator<? extends INPUT1> secondaryIterator; /* -------------------------------------------------- Constructors -------------------------------------------------- */ protected DoubleIteratorBasedIterator(@Captured @Nonnull Iterator<? extends INPUT0> primaryIterator, @Captured @Nonnull Iterator<? extends INPUT1> secondaryIterator) { super(primaryIterator); this.secondaryIterator = secondaryIterator; } }
/** * Objects that implement this interface can be used to {@link Property#register(net.digitalid.utility.property.Observer) observe} {@link ReadOnlyVolatileSetProperty volatile set properties}. */ @Mutable @Functional public interface VolatileSetObserver<@Unspecifiable VALUE, @Unspecifiable READONLY_SET extends ReadOnlySet<@Nonnull @Valid VALUE>> extends SetObserver<VALUE, READONLY_SET, RuntimeException, RuntimeException, VolatileSetObserver<VALUE, READONLY_SET>, ReadOnlyVolatileSetProperty<VALUE, READONLY_SET>> {}
/** * Objects that implement this interface can be used to {@link Property#register(net.digitalid.utility.property.Observer) observe} {@link ReadOnlyVolatileMapProperty volatile map properties}. */ @Mutable @Functional public interface VolatileMapObserver<@Unspecifiable KEY, @Unspecifiable VALUE, @Unspecifiable READONLY_MAP extends ReadOnlyMap<@Nonnull @Valid("key") KEY, @Nonnull @Valid VALUE>> extends MapObserver<KEY, VALUE, READONLY_MAP, RuntimeException, RuntimeException, VolatileMapObserver<KEY, VALUE, READONLY_MAP>, ReadOnlyVolatileMapProperty<KEY, VALUE, READONLY_MAP>> {}
/** * This class simplifies the creation and declaration of {@link WritableVolatileSetProperty}. */ @ThreadSafe @GenerateBuilder @GenerateSubclass @Mutable(ReadOnlyVolatileSimpleSetProperty.class) public abstract class WritableVolatileSimpleSetProperty<@Unspecifiable VALUE> extends WritableVolatileSetProperty<VALUE, ReadOnlySet<@Nonnull @Valid VALUE>, FreezableSet<@Nonnull @Valid VALUE>> implements ReadOnlyVolatileSimpleSetProperty<VALUE> { @Pure @Override @Default("net.digitalid.utility.collections.set.FreezableLinkedHashSetBuilder.build()") protected abstract @Nonnull @NonFrozen FreezableSet<@Nonnull @Valid VALUE> getSet(); }
/** * This class simplifies the creation and declaration of {@link WritableVolatileMapProperty}. */ @ThreadSafe @GenerateBuilder @GenerateSubclass @Mutable(ReadOnlyVolatileSimpleMapProperty.class) public abstract class WritableVolatileSimpleMapProperty<@Unspecifiable KEY, @Unspecifiable VALUE> extends WritableVolatileMapProperty<KEY, VALUE, ReadOnlyMap<@Nonnull @Valid("key") KEY, @Nonnull @Valid VALUE>, FreezableMap<@Nonnull @Valid("key") KEY, @Nonnull @Valid VALUE>> implements ReadOnlyVolatileSimpleMapProperty<KEY, VALUE> { @Pure @Override @Default("net.digitalid.utility.collections.map.FreezableLinkedHashMapBuilder.build()") protected abstract @Nonnull @NonFrozen FreezableMap<@Nonnull @Valid("key") KEY, @Nonnull @Valid VALUE> getMap(); }
/** * Objects that implement this interface can be used to {@link Property#register(net.digitalid.utility.property.Observer) observe} {@link ReadOnlyMapProperty map properties}. * * @see VolatileMapObserver */ @Mutable public interface MapObserver<@Unspecifiable KEY, @Unspecifiable VALUE, @Unspecifiable READONLY_MAP extends ReadOnlyMap<@Nonnull @Valid("key") KEY, @Nonnull @Valid VALUE>, @Unspecifiable EXCEPTION1 extends Exception, @Unspecifiable EXCEPTION2 extends Exception, @Unspecifiable OBSERVER extends MapObserver<KEY, VALUE, READONLY_MAP, EXCEPTION1, EXCEPTION2, OBSERVER, PROPERTY>, @Unspecifiable PROPERTY extends ReadOnlyMapProperty<KEY, VALUE, READONLY_MAP, EXCEPTION1, EXCEPTION2, OBSERVER, PROPERTY>> extends Observer { /** * This method is called on {@link Property#isRegistered(net.digitalid.utility.property.Observer) registered} observers when a key-value pair has been added to or removed from the given property. * * @param added {@code true} if the given key-value pair has been added to or {@code false} if it has been removed from the given property. */ @Impure public void notify(@Nonnull PROPERTY property, @NonCaptured @Unmodified @Nonnull @Valid("key") KEY key, @NonCaptured @Unmodified @Nonnull @Valid VALUE value, boolean added); }
/** * Objects that implement this interface can be used to {@link Property#register(net.digitalid.utility.property.Observer) observe} {@link ReadOnlySetProperty set properties}. * * @see VolatileSetObserver */ @Mutable @Functional public interface SetObserver<@Unspecifiable VALUE, @Unspecifiable READONLY_SET extends ReadOnlySet<@Nonnull @Valid VALUE>, @Unspecifiable EXCEPTION1 extends Exception, @Unspecifiable EXCEPTION2 extends Exception, @Unspecifiable OBSERVER extends SetObserver<VALUE, READONLY_SET, EXCEPTION1, EXCEPTION2, OBSERVER, PROPERTY>, @Unspecifiable PROPERTY extends ReadOnlySetProperty<VALUE, READONLY_SET, EXCEPTION1, EXCEPTION2, OBSERVER, PROPERTY>> extends Observer { /** * This method is called on {@link Property#isRegistered(net.digitalid.utility.property.Observer) registered} observers when a value has been added to or removed from the given property. * * @param added {@code true} if the given value has been added to or {@code false} if it has been removed from the given property. */ @Impure public void notify(@Nonnull PROPERTY property, @NonCaptured @Unmodified @Nonnull @Valid VALUE value, boolean added); }
/** * Objects that implement this interface can be used to {@link Property#register(net.digitalid.utility.property.Observer) observe} {@link ReadOnlyValueProperty value properties}. * * @see VolatileValueObserver */ @Mutable @Functional public interface ValueObserver<@Specifiable VALUE, @Unspecifiable EXCEPTION1 extends Exception, @Unspecifiable EXCEPTION2 extends Exception, @Unspecifiable OBSERVER extends ValueObserver<VALUE, EXCEPTION1, EXCEPTION2, OBSERVER, PROPERTY>, @Unspecifiable PROPERTY extends ReadOnlyValueProperty<VALUE, EXCEPTION1, EXCEPTION2, OBSERVER, PROPERTY>> extends Observer { /** * This method is called on {@link Property#isRegistered(net.digitalid.utility.property.Observer) registered} observers when the value of the given property has been replaced. * * @require !Objects.equals(newValue, oldValue) : "The new value may not be the same as the old value."; */ @Impure public void notify(@Nonnull PROPERTY property, @NonCaptured @Unmodified @Valid VALUE oldValue, @NonCaptured @Unmodified @Valid VALUE newValue); }