[[_kie.releasenoteskie.6.0.0]]
= New and Noteworthy in KIE API 6.0.0

== New KIE name


KIE is the new umbrella name used to group together our related projects; as the family continues to grow.
KIE is also used for the generic parts of unified API; such as building, deploying and loading.
This replaces the kiegroup and knowledge keywords that would have been used before.

.KIE Anatomy
image::KIE/Overview/kie.png[align="center"]


== Maven aligned projects and modules and Maven Deployment


One of the biggest complaints during the 5.x series was the lack of defined methodology for deployment.
The mechanism used by Drools and jBPM was very flexible, but it was too flexible.
A big focus for 6.0 was streamlining the build, deploy and loading (utilization) aspects of the system.
Building and deploying activities are now aligned with Maven and Maven repositories.
The utilization for loading rules and processes is now convention and configuration oriented, instead of programmatic, with sane defaults to minimise the configuration.

Projects can be built with Maven and installed to the local M2_REPO or remote Maven repositories.
Maven is then used to declare and build the classpath of dependencies, for KIE to access.

== Configuration and convention based projects


The 'kmodule.xml' provides declarative configuration for KIE projects.
Conventions and defaults are used to reduce the amount of configuration needed. 

.Declare KieBases and KieSessions
====
[source,xml]
----
<kmodule xmlns="http://www.drools.org/xsd/kmodule">
  <kbase name="kbase1" packages="org.mypackages">
    <ksession name="ksession1"/>
  </kbase>
</kmodule>
----
====

.Utilize the KieSession
====
[source,java]
----
KieServices ks = KieServices.Factory.get();
KieContainer kContainer = ks.getKieClasspathContainer();

KieSession kSession = kContainer.newKieSession("ksession1");
kSession.insert(new Message("Dave", "Hello, HAL. Do you read me, HAL?"));
kSession.fireAllRules();
----
====

== KieBase Inclusion


It is possible to include all the KIE artifacts belonging to a KieBase into a second KieBase.
This means that the second KieBase, in addition to all the rules, function and processes directly defined into it,  will also contain the ones created in the included KieBase.
This inclusion can be done declaratively in the kmodule.xml file

.Including a KieBase into another declaratively
====
[source,xml]
----
<kmodule xmlns="http://www.drools.org/xsd/kmodule">
  <kbase name="kbase2" includes="kbase1">
    <ksession name="ksession2"/>
  </kbase>
</kmodule>
----
====


or programmatically using the ``KieModuleModel``.

.Including a KieBase into another programmatically
====
[source,java]
----
KieModuleModel kmodule = KieServices.Factory.get().newKieModuleModel();
KieBaseModel kieBaseModel1 = kmodule.newKieBaseModel("KBase2").addInclude("KBase1");
----
====

== KieModules, KieContainer and KIE-CI


Any Maven produced JAR with a 'kmodule.xml' in it is considered a KieModule.
This can be loaded from the classpath or dynamically at runtime from a Resource location.
If the kie-ci dependency is on the classpath it embeds Maven and all resolving is done automatically using Maven and can access local or remote repositories.
Settings.xml is obeyed for Maven configuration.

The KieContainer provides a runtime to utilize the KieModule, versioning is built in throughout, via Maven.
Kie-ci will create a classpath dynamically from all the Maven declared dependencies for the artifact being loaded.
Maven LATEST, SNAPSHOT, RELEASE and version ranges are supported.

.Utilize and Run - Java
====
[source,java]
----
KieServices ks = KieServices.Factory.get();
KieContainer kContainer = ks.newKieContainer(
        ks.newReleaseId("org.mygroup", "myartifact", "1.0") );

KieSession kSession = kContainer.newKieSession("ksession1");
kSession.insert(new Message("Dave", "Hello, HAL. Do you read me, HAL?"));
kSession.fireAllRules();
----
====


KieContainers can be dynamically updated to a specific version, and resolved through Maven if KIE-CI is on the classpath.
For stateful KieSessions the existing sessions are incrementally updated.

.Dynamically Update - Java
====
[source,java]
----
KieContainer kContainer.updateToVersion(
                ks.newReleaseId("org.mygroup", "myartifact", "1.1") );
----
====

== KieScanner


The `KieScanner` is a Maven-oriented replacement of the KnowledgeAgent present in Drools 5.
It continuously monitors your Maven repository to check if a new release of a Kie project has been installed and if so, deploys it in the `KieContainer` wrapping that project.
The use of the `KieScanner` requires kie-ci.jar to be on the classpath.

A `KieScanner` can be registered on a `KieContainer` as in the following example.

.Registering and starting a KieScanner on a KieContainer
====
[source,java]
----
KieServices kieServices = KieServices.Factory.get();
ReleaseId releaseId = kieServices.newReleaseId( "org.acme", "myartifact", "1.0-SNAPSHOT" );
KieContainer kContainer = kieServices.newKieContainer( releaseId );
KieScanner kScanner = kieServices.newKieScanner( kContainer );

// Start the KieScanner polling the Maven repository every 10 seconds
kScanner.start( 10000L );
----
====


In this example the `KieScanner` is configured to run with a fixed time interval, but it is also possible to run it on demand by invoking the `scanNow()` method on it.
If the `KieScanner` finds, in the Maven repository, an updated version of the Kie project used by that `KieContainer` it automatically downloads the new version and triggers an incremental build of the new project.
From this moment all the new ``KieBase``s and ``KieSession``s created from that `KieContainer` will use the new project version.

== Hierarchical ClassLoader


The CompositeClassLoader is no longer used; as it was a constant source of performance problems and bugs.
Traditional hierarchical classloaders are now used.
The root classloader is at the KieContext level, with one child ClassLoader per namespace.
This makes it cleaner to add and remove rules, but there can now be no referencing between namespaces in DRL files; i.e.
functions can only be used by the namespaces that declared them.
The recommendation is to use static Java methods in your project, which is visible to all namespaces; but those cannot (like other classes on the root KieContainer ClassLoader) be dynamically updated.

== Legacy API Adapter


The 5.x API for building and running with Drools and jBPM is still available through Maven dependency "knowledge-api-legacy5-adapter". Because the nature of deployment has significantly changed in 6.0, it was not possible to provide an adapter bridge for the KnowledgeAgent.
If any other methods are missing or problematic, please open a JIRA, and we'll fix for 6.1

== KIE Documentation


While a lot of new documentation has been added for working with the new KIE API, the entire documentation has not yet been brought up to date.
For this reason there will be continued references to old terminologies.
Apologies in advance, and thank you for your patience.
We hope those in the community will work with us to get the documentation updated throughout, for 6.1
