0.2.0 - Event, ByteHexConverter, InplaceSortable, EpochDateTime, and more

da4a Project Icon

The icon that presents da4a is out!

Event

This early-stage version may not works on Java platform.

Added a series of classes that can quickly create an Event object and pass events to listeners using rich-featured event context tool.

Events

Events are a series class that can manage listeners. It cannot be emitted directly, to emit a event, an Emitter is required.

                                    ┌────────────────────┐                 
   Event series class graph         │ AbstractEvent      │                 
                                    │   + SimpleEventOps │                 
                                    └─────────▲──────────┘                 
           ┌──────────────────────────────────┤                            
┌──────────┴───────────┐            ┌─────────┴─────────┐                  
│ SimpleEmittableEvent │            │ AbstractRichEvent │                  
└──────────▲───────────┘            │   + RichEventOps  │                  
           │                        └────────▲──────────┘                  
           │                                 ├───────────────┐             
           │              ┌──────────────────┘  ┌────────────┴────────────┐
           │   ┌──────────┴─────────┐           │ AbstractManageableEvent │
           │   │ RichEmittableEvent │           │   + ManagableEventOps   │
           │   └──────────▲─────────┘           └────────────▲────────────┘
           │              │                                  │             
           │              └──────────────┐                   │             
           │                       ┌─────┴─────┐     ┌───────┴────────┐    
           │                       │ RichEvent │     │ ManagableEvent │    
           │                       └─────┬─────┘     └───────▲────────┘    
           │                             │                   │             
           │                             ├───────────────────┘             
     ┌─────┴───────┐                 ┌───┴────┐                            
     │ SimpleEvent │                 │ Event  │                            
     └─────────────┘                 └────────┘                            

• AbstractEvent provides the registerListener(EP=>ER) and removeListener(EP=>ER) function. Its Ops provides an opeation variant of registerListener is --> (EP=>ER). Event that implements this will be able to register a callback, normally with no context manager and error handler.
• AbstractRichEvent provides registerListener(EventListener[EP, ER]) and removeListener(EventListener[EP, ER]). Its Ops provides registerRichListener(EventContext[EP]=>ER) along with its operator variant ==>(EventContext[EP]=>ER]), registerListener(Int,EP=>ER), registerRichListener(Int, EventContext[EP]=>ER), removeListenerIf(EventListener[EP, ER]=>Boolean), removeRichListener(EventContext[EP]=>ER)
• AbstractManageableEvent provides initContextWith(EventContext[EP]=>Unit) and initErrorHandlerWith((Throwable, EventContext[EP])=>Boolean). Those internal values can be accessed by the Emitter series.
• SimpleEmittableEvent provides foreachListeners[T]((EP=>ER)=>T) to iterate the event's listeners.
• RichEmittableEvent provides foreachListeners[T](EventListener[EP, ER]=>T) to iterate the event's listeners.
• Event is a type that for production use. It extends RichEvent and ManagableEvent, so that it can register and manager EventListeners that can handle EventContext, and it also can set the error handler to handle errors occurred by listeners.
• SimpleEvent is a trait that for production use.It only extends AbstractEvent and its ops. It can only register a simple callback EP=>ER, with no EventContext available and cannot handler errors occurred by listeners.

For user-oriented Event and SimpleEvent, some variant types is provided:

	no listener returns	no event params
Event[EP, ER]	SupplierEvent[EP]	ConsumerEvent[ER]
SimpleEvent[EP, ER]	SupplierSimpleEvent[EP]	ConsumerSimpleEvent[ER]

To create an Event, Event and SimpleEvent both has an apply function.

EventListener

EventListener is a rich-featured event listener trait. It has an priority: Int field that can be used to order listeners, it can receive EventContext using , and use the EventContext to control whether to skip running (by its isSkipEvent(usng EventContext[EP])).

For EventListener's priority, there are also a pre-defined EventListener.Priorities:

ABSOLUTE_LOW	LOWEST	LOWER	LOW	NORMAL	HIGH	HIGHER	HIGHEST	ABSOLUTE_HIGH
Int.MIN	Short.MIN	Byte.MIN	-64	0	64	Byte.MAX	Short.MAX	Int.MAX
-2147483648	-65536	-128	-64	0	64	127	65535	2147483647

There are also CallbackIsFunction and CallbackIsSimpleFunction helper traits. They are used to record the creation methods and parameters for its EventListener. By these traits, equality checks with EventListener and EP=>ER and so on are available, makes removeListener better to use.

Predefined ordering for EventLisner is also provided: OrderingByPriorityFixed, and OrderingByPriorityStables

To create an EventListener, the following method is provided: apply[EP, ER](EventContext[EP]=>ER, Int), apply[EP, ER](EventContext[EP]=>ER), simple[EP, ER](EP=>ER, Int), simple[EP,ER](EP=>ER)

EventContext

EventContext is the alternate event params that used in rich-event series.

Provides an param: EP. It is also the only param that required to create an EventContext.

Provides givenCxt: GivenContext, to pass context parameters with listeners.

Provides timeStartup: EpochMillis

Provides isEventOk(), pushEventState(EventState), setEventOk(), setEventCanceled(), state: EventStates|Null, stateOption: Option[EventState], status: List[EventStatus] for control event states.

EventStatus

EventStatus series are used in EventContext for tagging event status.

It has root trait EventStatus, helper trait WithSource that requires a from: StackTraceElement, sub class Success extends EventStatus with WithSource, sub class Canceled extends EventStatus with WithSource, sub class Custom extends EventStatus (unstable currently).

emitter

Trait Emitter (in package event.emitter) is used to emit an Event. An Emitter is for a specific type of AbstractEvent, and provides an emit(EP) method to emit the event.

The implementation of Emitter can also access the protected method patchContext(AbstractManageableEvent[EP, ER], EventContext[EP]) and getErrorHandler(AbstractManageableEvent[EP, ER]) to support the features of AbstractManagableEvent.

An static method emittingFor(AbstractEvent) is provided to create an emitter instance for a specific event. This emitter supports all event types in this library.

data.collections extension - InPlaceSortable

Scala only features.

Add trait InPlaceSortable, which provides sortInPlace(using Ordering).

Add trait IteratingOps, provides removeIf(T=>Boolean).

Add new mutable collection implementation LinkedList, extends trait like normal Seq with additional InPlaceSortable and IteratingOps. (The internal implementation is java's LinkedList).

datetime - DateTimeTypeAliases

Scala only feature.

Add the new types aliases:

• EpochMillis as alias of Long. Can be created from String time, String zone as well, or converted from EpochSeconds and EpochDays.
• EpochSeconds as alias of Int. Can be converted from EpochMillis as well. Max supported time is 2038-01-19 03:14:07 UTC.
• EpochDays as alias of Short. Can be coverted from EpochMillis as well. Max supported time is 2059-09-18 UTC.
• DurationMillis as alias of Long.

random features

This early-stage version may not works on Java platform.

ArrayChooser class changed to implicit class CollectiomChooser_ExtensionSeq, added top level method choose(Seq)(using RandomIntGenerator) and chooseOne(Seq, Int)(RandomIntGenerator)

GivenContext

Should works fine on both Java and Scala platform.

Add constructor method from to clone a GivenContext. Also the GivenContext extends Clonable now,clone method is available.

Add provide[T](Class[T], T), get[T: ClassTag], get[T](Class[T]) (and deprecated use), getOrNull[T](Class[T]), getOrNull[T: ClassTag] and its operator variant >?>[T](Class[T]), getUnsafe[T](Class[T]), getUnsafe[T: ClassTag] (as method variant of >!>), use[T, U](Class[T])(T=>U), use[T: ClassTag, U](T=>U) as a better consume, consume[T](Class[T])(T=>Any), consuming[T](Class[T])(java.function.Consumer[T]) as java friendly variant consume.

The above changes is applied for both GivenContext main context and OwnedContext that accessed by ownedBy method.

Add ownedBy[O](Class[O]) as java friendly variant of ownedBy.

stacks tools

Should works fine on both Java and Scala platform.

Fix method under WithCurrentStack has wrong answer when calling in java.

Add StackExtensions, contains static method dropWhileClass, and implicit class StackExtensions.StackExtensions with method dropWhileClass.

throwable/exception tools

Should works fine on both Java and Scala platform.

Deprecates implicit class ThrowableExtensions and the belong method toLogString.

Add Exceptions with implicic class ThrowableExtension as its inner class. Add method printString and printStringSimple to Exceptions and ThrowableExtensions (similar to old toLogString).

byte tools

Should works fine on both Java and Scala platform.

Add bytes.ByteHexConverter. Add implicit class Byte2Hex with toHex. Add ByteArray2Hex(Array[Byte]) with toHex.