= Commons

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

_Apache Isis Commons_ is a library with utilities, that are shared with the entire 
_Apache Isis_ ecosystem.

== Motivation

This module was initially created, to remove dependence on 3^rd^ party (general purpose) 
_Java_ libraries like _Guava_ or _Apache Commons_. This should reduce the likelihood for 
_Apache Isis_ developers to run into _jar_ version conflicts, when using one of these 
3^rd^ party libraries. 

It now also allows us to collect utilities in support of common idioms, that we use 
throughout the _Apache Isis_ ecosystem. 

== Packages

Package structure distinguishes classes either for _internal_ or _public_ use.

=== Public

[source]
----
org.apache.isis.commons.* // excluding ...internal.*
----

Classes meant for public use. For any changes, that break compatibility with older code, 
we will write migration or release notes to inform developers how to migrate.   
 
=== Internal

[source]
----
org.apache.isis.commons.internal.* // internal
----

Classes meant for framework internal use. By convention these classes are prefixed with 
an underscore `*_*`, to explicitly indicate their nature.

WARNING: Do *not* use any of the classes provided by these *internal* packages, simply 
because these may be changed or removed without notice! 

== Install

[source,xml]
.Maven
----
<dependency>
    <groupId>org.apache.isis.commons</groupId>
    <artifactId>isis-commons</artifactId>
    <version>xxx</version>
</dependency>
----

[source]
.Gradle
----
compile group: 'org.apache.isis', name: 'isis-commons', version: 'xxx'
----



