Internal API: Introduction

[Andreas Huber <a....@corax.at>]

Hi Folks!

I'd like to give a summary of changes introduced with branch
ISIS-1846_internal_utils that's meant for version 2.0.0. (Ready for
review and comments.)

In order to consolidate recurring code fragments and idioms, we gather
these within an Internal API which ...
* is shared among the entire code base (except unittestsupport)
* has explicit java-doc warnings 'internal use only ... likely to change
without notice'
* is gathered within org.apache.isis.applib.internal.xxx
* has naming convention: class-names should be prefixed with underscore (_)
* has naming suggestion: package private support classes should follow
'mixin naming style'
* is not part of the public API and will be access restricted once Java
9 will be in place

= Internal API Summary [1]

== _Constants
* as the name suggests, a collection of immutable recurring immutables
* helps to reduce heap pollution (at least a little bit)

== _Casts
* collection of common type casting use-cases
* by now we have only one: unchecked casts

== _NullSafe
* shortcuts for common null-check idioms
* shortcuts for common empty-check idioms
* convenient ways for null-safe stream creation

== _Strings
* all use-cases are implemented null-safe (we handle null inputs properly)
* has some basic building blocks like 'trim', 'upper', 'lower', 'capitalize'
* can combine building blocks via unary-operator composition
* more complex string processing operators are provided via mixins
* convenient string splitting via Stream<String> splitThenStream(input,
separator)

== _Comparators
* complex recurring comparators (e.g. dewey-order) are provided via mixins

== _Context
* provides a mechanism for storing and retrieving singletons
* needed to replaces static fields in our code-base that have a
application-scoped life-cycle
* could be backed with CDI once we have it, by now uses a static hash-map

== _Exceptions
provides recurring exception creation idioms like
* 'unexpected code reach' or
* 'case not handled' in switch statements

== _Reflect
Since we use an external reflection API (reflections.org), we refactored
all use-cases throughout our code-base (except unittestsupport) to
access 'reflections.org' only via the interfaces now provided by
_Reflect. This allows for easy replacement under the hood, if needed.
Maven dependencies have been updated, such that 'reflections.org' is
only a compile-dependency for isis-core-applib (and unittestsupport) but
this dependency is not transitive (meaning, its not propagated to the
other core-projects).

Cheers Andi!

[1]
https://github.com/apache/isis/tree/ISIS-1846_internal_utils/core/applib/src/main/java/org/apache/isis/applib/internal

Re: Internal API: Introduction

[Andreas Huber <a....@corax.at>]

Excellent! I think, making this clear distinction between what's public 
and what's not, gives us more flexibility. E.g. we can experiment with 
ideas not having to worry about removing anything later, in case an idea 
has flaws.

By the way, at first I thought removing guava entirely from applib is 
too much effort. But after digging into it, I'd say, its not that hard.

I'd love to remove the dependency on reflections.org as well (without 
any urge). But that would need some investigation. Refactoring showed, 
we have few uses-cases for reflections, now (with the Internal API 
branch) all 'redirected' through the interfaces provided by _Reflect.

Cheers Andi

On 27.01.2018 09:37, Dan Haywood wrote:
> OK, thanks Andi.
>
> Well, for myself I'm happy to leave these classes in isis-core-applib, 
> ie where you've moved them.  In any case, suspect folk will be moving 
> to Java 9 in the next year, and so we're gonna have to figure out a 
> way to bundle Isis for both Java 8 and Java 9 (ie with 
> module-info.java).  In the module-info.java we'll just not export that 
> new package.
>
> Cheers
> Dan

Re: Internal API: Introduction

[Dan Haywood <da...@haywood-associates.co.uk>]

OK, thanks Andi.

Well, for myself I'm happy to leave these classes in isis-core-applib, ie
where you've moved them.  In any case, suspect folk will be moving to Java
9 in the next year, and so we're gonna have to figure out a way to bundle
Isis for both Java 8 and Java 9 (ie with module-info.java).  In the
module-info.java we'll just not export that new package.

Cheers
Dan

On Thu, 25 Jan 2018 at 22:28 Andi Huber <ho...@gmx.at> wrote:

> Thx Dan!
>
> Giving just quick answers inline ...
>
> Cheers, Andi!
>
> On 25.01.2018 23:05, Dan Haywood wrote:
> > Hi Andreas,
> >
> > thanks for doing this work, very happy to see the codebase being tidied
> up
> > and you bringing in some useful utility classes.
> >
> > One question though ...
> >
> > Obviously in the future when we're on Java 9, this package can be made
> > truly private and hidden from other consumers.  But in the meantime, is
> > there any reason to have these classes within applib, given that they are
> > intended only for use by the framework, and not by domain applications?
> When refactoring applib, I felt the need for a place, where we could put
> utility classes, that we can share among the entire(!) core code base,
> without having to care too much about changes without notice. Since
> every other module depends on applib, except for 'unittestsupport' and I
> guess 'schema', applib seemed to be the natural place for this.
> > In the isis-core-metamodel module (upon which most other stuff in the
> > framework depends) we have org.apache.isis.core.common package, could it
> go
> > there?
> This would exclude applib from access to the internal API. (Which in my
> refactored version requires access to the new _Reflect and _Context
> classes, and makes heavy use of _NullSafe.)
> >
> > Or, if you'd rather create a new isis-core-commons module, to sit between
> > applib and metamodel, that'd also make sense to me.
> From my point of view, a technical solution could be to have the
> internal API in a separate module, but share it also with applib!
> >
> > Let me know,
> >
> > thx
> > Dan
>
>

Re: Internal API: Introduction

[Andi Huber <ho...@gmx.at>]

Thx Dan!

Giving just quick answers inline ...

Cheers, Andi!

On 25.01.2018 23:05, Dan Haywood wrote:
> Hi Andreas,
>
> thanks for doing this work, very happy to see the codebase being tidied up
> and you bringing in some useful utility classes.
>
> One question though ...
>
> Obviously in the future when we're on Java 9, this package can be made
> truly private and hidden from other consumers.  But in the meantime, is
> there any reason to have these classes within applib, given that they are
> intended only for use by the framework, and not by domain applications?
When refactoring applib, I felt the need for a place, where we could put
utility classes, that we can share among the entire(!) core code base,
without having to care too much about changes without notice. Since
every other module depends on applib, except for 'unittestsupport' and I
guess 'schema', applib seemed to be the natural place for this.
> In the isis-core-metamodel module (upon which most other stuff in the
> framework depends) we have org.apache.isis.core.common package, could it go
> there?
This would exclude applib from access to the internal API. (Which in my
refactored version requires access to the new _Reflect and _Context
classes, and makes heavy use of _NullSafe.)
>
> Or, if you'd rather create a new isis-core-commons module, to sit between
> applib and metamodel, that'd also make sense to me.
From my point of view, a technical solution could be to have the
internal API in a separate module, but share it also with applib!
>
> Let me know,
>
> thx
> Dan

Re: Internal API: Introduction

[Dan Haywood <da...@haywood-associates.co.uk>]

Hi Andreas,

thanks for doing this work, very happy to see the codebase being tidied up
and you bringing in some useful utility classes.

One question though ...

Obviously in the future when we're on Java 9, this package can be made
truly private and hidden from other consumers.  But in the meantime, is
there any reason to have these classes within applib, given that they are
intended only for use by the framework, and not by domain applications?

In the isis-core-metamodel module (upon which most other stuff in the
framework depends) we have org.apache.isis.core.common package, could it go
there?

Or, if you'd rather create a new isis-core-commons module, to sit between
applib and metamodel, that'd also make sense to me.

Let me know,

thx
Dan

On Wed, 24 Jan 2018 at 07:14 Andreas Huber <a....@corax.at> wrote:

> Hi Folks!
>
> I'd like to give a summary of changes introduced with branch
> ISIS-1846_internal_utils that's meant for version 2.0.0. (Ready for
> review and comments.)
>
> In order to consolidate recurring code fragments and idioms, we gather
> these within an Internal API which ...
> * is shared among the entire code base (except unittestsupport)
> * has explicit java-doc warnings 'internal use only ... likely to change
> without notice'
> * is gathered within org.apache.isis.applib.internal.xxx
> * has naming convention: class-names should be prefixed with underscore (_)
> * has naming suggestion: package private support classes should follow
> 'mixin naming style'
> * is not part of the public API and will be access restricted once Java
> 9 will be in place
>
> = Internal API Summary [1]
>
> == _Constants
> * as the name suggests, a collection of immutable recurring immutables
> * helps to reduce heap pollution (at least a little bit)
>
> == _Casts
> * collection of common type casting use-cases
> * by now we have only one: unchecked casts
>
> == _NullSafe
> * shortcuts for common null-check idioms
> * shortcuts for common empty-check idioms
> * convenient ways for null-safe stream creation
>
> == _Strings
> * all use-cases are implemented null-safe (we handle null inputs properly)
> * has some basic building blocks like 'trim', 'upper', 'lower',
> 'capitalize'
> * can combine building blocks via unary-operator composition
> * more complex string processing operators are provided via mixins
> * convenient string splitting via Stream<String> splitThenStream(input,
> separator)
>
> == _Comparators
> * complex recurring comparators (e.g. dewey-order) are provided via mixins
>
> == _Context
> * provides a mechanism for storing and retrieving singletons
> * needed to replaces static fields in our code-base that have a
> application-scoped life-cycle
> * could be backed with CDI once we have it, by now uses a static hash-map
>
> == _Exceptions
> provides recurring exception creation idioms like
> * 'unexpected code reach' or
> * 'case not handled' in switch statements
>
> == _Reflect
> Since we use an external reflection API (reflections.org), we refactored
> all use-cases throughout our code-base (except unittestsupport) to
> access 'reflections.org' only via the interfaces now provided by
> _Reflect. This allows for easy replacement under the hood, if needed.
> Maven dependencies have been updated, such that 'reflections.org' is
> only a compile-dependency for isis-core-applib (and unittestsupport) but
> this dependency is not transitive (meaning, its not propagated to the
> other core-projects).
>
> Cheers Andi!
>
> [1]
>
> https://github.com/apache/isis/tree/ISIS-1846_internal_utils/core/applib/src/main/java/org/apache/isis/applib/internal
>
>
>
>
>
>
>
>
>
>
>
>
>