CrayFish Alarms

The library contains primitives that allow you to control the installation of tasks for processing on a schedule

TimeRange

Structure of TimeRange

duration

The main parameter of the time range is its duration. You cannot set the duration to zero. When a time range is built, two parameters are needed to determine its start and end: boundary and duration. If the duration is negative, then the time range is built to the left of the border, and if positive, then to the right.

completeTimeout

The completeTimeout interval describes a delay that describes the time interval during which, after the current moment of time has crossed the extreme TimeRegion boundary, the ability to access object data through api is guaranteed to remain. That is, the object will be present in memory and open to calls.

interval

The entire TimeRange is divided into sub-ranges with the duration specified by the interval parameter. For each subrange, a separate structure for storing elements marked with a time-marker is allocated, which just falls into the specified subrange.

delay

When accessing TimeRange, you can get information about the interval until the nearest event, however, if this is not the end of the range lifetime, then this value will be limited from below by the delay parameter. Thus, the 'delay' parameter describes the minimum delay between repeated calls to TimeRange.

Supported items

The implemented library allows you to store elements that have a time marker inside the TimeRange and retrieve at each moment of time those objects that have a time marker earlier than the current moment. A temporary marker can be attached to an object in three ways:

An implementation of the Expected<T extends TemporalAccessor> interface, where the token is obtained by calling the getTick() method
Packing the element into an object that implements the ExpectedPackage<M,T extends TemporalAccessor> interface, which also supports the Expected<T extends TemporalAccessor> interface, and the element itself is obtained by calling the getElemen() method
A description of two methods that implement the interfaces Expectation<M,? extends TemporalAccessor> to get the temporary marker from the object and ITimeRangeFactory.Transformer<M,R> to get the resulting object from the original one.

Uniqueness Constraint

There is one TimeRange limitation: you cannot describe two objects at the same time that, when cast to the resulting object, will turn out to be equal. To implement this restriction, the Comparator<> of the resulting object is used, which is used exactly in case of a match in time markers and allows you to filter out duplicates (perform a distinct operation)

Creation of ITimeRangeFactory<M,R>

The create, packable, and expected factory methods are used to instantiate the ITimeRangeFactory<M,R> description.

method create

This is the most general method. When calling it, you must specify the duration, interval, delay, completeTimeout, expectation, comparator and extractor parameters described above.

    ITimeRangeFactory<SourceObject,FiredObject> timeRangeFactory = ITimeRangeFactory.create(
            Duration.ofSeconds(180),
            Duration.ofMillis(15000),
            Duration.ofMillis(250),
            Duration.ofSeconds(15),
            Source2Package::transform
            obj::getFireTime,
            Package2Alarm::transform
            null
    );

method packable

This method allows you to create a ITimeRangeFactory described the TimeRange that takes ExpectedPackage<M,T extends TemporalAccessor> as input elements, and the element contained in the specified package as result elements. In this case, the expectation and extractor parameters are missing

    ITimeRangeFactory<Expected<Instant>> timeRangeFactory = ITimeRangeFactory.packable(
        Duration.ofSeconds(10),
        Duration.ofMillis(1000),
        Duration.ofMillis(100),
        Duration.ofSeconds(3),
        StringToExpectedPackage::transform,
        String::compareTo
    );

method expected

This method also defines the expectation and extractor parameters itself and creates a ITimeRangeFactory<M,R> that has the same object at the input and output that implements the Expected<T extends TemporalAccessor> interface.

    ITimeRangeFactory<Expected<Instant>, Expected<Instant>> timeRangeFactory = TimeRangeConfig.expected(
        Duration.ofSeconds(10),
        Duration.ofMillis(1000),
        Duration.ofMillis(100),
        Duration.ofSeconds(3),
        null
    );

method temporal

This method creates a ITimeRangeFactory<M,M> that has the same object at the input and output that reilize the <M extends TemporalAccessor> class.

    ITimeRangeFactory<Instant,Instant> timeRangeFactory = ITimeRangeFactory.temporal (
            Duration.ofSeconds(SECONDS),
            Duration.ofMillis(333),
            Duration.ofSeconds(1),
            Instant::compareTo
    );

ITimeRangeFacroty<M,R>

The creation of a physical region is implemented in the ITimeRangeFactory class.

Creation of ITimeRange

The ITimeRange instance is created by the timeRange(TemporalAccessor) method. Those a time point is taken and, depending on the sign of the Duration parameter, the physical time range is described to the left or right of the time point using the TimeRangeConfig described above

    ITimeRange<MyObject, NewObject> timeRange = timeRangeFactory.timeRange(Instant.now);

ITimeRegion attributes

ITimeRangeFactory has the following attributes, which can be obtained using the corresponding getter:

startInstant - Left border of the time range described by the holder
lastInstant - Right border of the time range described by the holder
interval - Corresponds to the Time Range interval parameter we described earlier
delay - Corresponds to the Time Range delay parameter we described earlier
completeTimeout - Corresponds to the Time Range completeTimeout parameter we described earlier

There are also three additional methods:

isExpired() - true if the time specified by the parameter or the current time (if the parameter is not set) is greater than lastInstant by at least completeDuration
isComplete() - true if expired and there is no element inside the holder
duration() - get time interval until the next event occurs from the moment specified by the parameter, or from the current moment if the parameter is not set

Adding new elements to the holder

To add new elements, use the addElements method:

    List<MyObject> elements=getElements();
    List<MyObject> rejected=timeRange.addElements(elements);

If any elements do not fall within the specified region (excluding the right border), then these elements will be returned by the adElements method as not processed (rejected)

Getting triggered (fired) elements from a holder

To get fired elements, you need to call the extractFiredElements method specifying the point in time at which you want to search for elements. If no point in time is specified, then the current one is used. All fired elements will be extracted from the holder and returned as a result as a Collection of elements (unique if the timestamp matches).

    Collection<NewObject> firedSet=timeRange.extractFiredElements(Instant.now.plusMillis(250));

sftwnd/crayfish-alarms