Package org.kie.internal.builder

## Interface KnowledgeBuilder

- All Superinterfaces:
    `ProcessBuilder`, `RuleBuilder`

      public interface KnowledgeBuilder
      extends RuleBuilder, ProcessBuilder

  The KnowledgeBuilder is responsible for taking source files, such as a .drl file, a .bpmn2 file or an .xls file, and turning them into a KnowledgePackage of rule and process definitions which a KnowledgeBase can consume. It uses the ResourceType enum to tell it the type of the resource it is being asked to build.

  The ResourceFactory provides capabilities to load Resources from a number of sources; such as Reader, ClassPath, URL, File, ByteArray. Binaries, such as XLS decision tables, should not use a Reader based Resource handler, which is only suitable for text based resources.

  It is best practice to always check the hasErrors() method after an addition, you should not add more resources or get the KnowledgePackages if there are errors. getKnowledgePackages() will return an empty list if there are errors.

  You can create a new KnowledgeBase for all the resources that were added using this builder using the newKnowledgeBase() method. This will throw an exception if there are errors for any of the resources.

  Simple example showing how to build a KnowledgeBase from an DRL rule resource.

       KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
       kbuilder.add( ResourceFactory.newUrlResource( "file://myrules.drl" ),
                             ResourceType.DRL);
       assertFalse( kbuilder.hasErrors() );
       KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();

  Simple example showing how to build a KnowledgeBase from an XLS decision table resource.

       KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
       DecisionTableConfiguration dtconf = KnowledgeBuilderFactory.newDecisionTableConfiguration();
       dtconf.setInputType( DecisionTableInputType.XLS );
       dtconf.setWorksheetName( "Tables_2" );
       kbuilder.add( ResourceFactory.newUrlResource( "file://IntegrationExampleTest.xls" ),
                     ResourceType.DTABLE,
                       dtconf );
       assertFalse( kbuilder.hasErrors() );
       KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();

  Simple example showing how to build a KnowledgeBase from an BPMN2 process resource.

       KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
       kbuilder.add( ResourceFactory.newUrlResource( "file://myProcess.bpmn2" ),
                     ResourceType.BPMN2 );
       KnowledgeBase kbase = kbuilder.newKnowledgeBase();

  If there are errors a simple toString can print the errors

       if ( kbuilder.hasErrors() ) {
           log.exception( kbuilder.getErrors().toString() )
       }

  The KnowledgeBuilder can also be built from a configuration using the XML change-set format and the ResourceType.CHANGE_SET value. While change-set supports add, remove, and modify as elements. KnowledgeBuilder will only process add. If the resource element provided points to a directory, all files found in that directory will be added. Currently the knowledge type is not derived from the file extension and must be explicitly set in the XML for the resource. It is expected that all resources in a directory given resource are of the specified type.

       <change-set xmlns='http://drools.org/drools-5.0/change-set'
                   xmlns:xs='http://www.w3.org/2001/XMLSchema-instance'
                   xs:schemaLocation='http://drools.org/drools-5.0/change-set http://anonsvn.jboss.org/repos/labs/labs/jbossrules/trunk/drools-api/src/main/resources/change-set-1.0.0.xsd' >
        <add>
             <resource source='http:org/domain/myrules.drl' type='DRL' />
             <resource source='classpath:data/IntegrationExampleTest.xls' type="DTABLE">
                 <decisiontable-conf input-type="XLS" worksheet-name="Tables_2" />
             </resource>
             <resource source='file:org/drools/decisiontable/myflow.drf' type='DRF' />
         </add>
       </change-set>

       KnowledgeAgent kagent = KnowledgeAgentFactory.newKnowledgeAgent( "test agent", // the name of the agent
                                                                        kaconf );
       kagent.applyChangeSet( ResourceFactory.newUrlResource( url ) ); // resource to the change-set xml for the resources to add

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `add​(org.kie.api.io.Resource resource, org.kie.api.io.ResourceType type)` | Add a resource of the given ResourceType, using the default resource configuration.
    `void` | `add​(org.kie.api.io.Resource resource, org.kie.api.io.ResourceType type, org.kie.api.io.ResourceConfiguration configuration)` | Add a resource of the given ResourceType, using the provided ResourceConfiguration.
    `CompositeKnowledgeBuilder` | `batch()` | Return a CompositeKnowledgeBuilder allowing to add multiple Resources at the same time, without worrying about cross dependencies among them.
    `KnowledgeBuilderErrors` | `getErrors()` | Return errors that occurred during the build process.
    `Collection<org.kie.api.definition.KiePackage>` | `getKnowledgePackages()` | Returns the built packages.
    `KnowledgeBuilderResults` | `getResults​(ResultSeverity... severities)` | Return the knowledge builder results for the listed severities.
    `boolean` | `hasErrors()` | If errors occurred during the build process they are added here
    `boolean` | `hasResults​(ResultSeverity... severities)` | Checks if the builder generated any results of the listed severities
    `org.kie.api.KieBase` | `newKieBase()` | Creates a new KnowledgeBase from the knowledge packages that have been added to this builder.
    `void` | `undo()` | Remove the last added Resource.

- - ### Method Detail

    - #### add

          void add​(org.kie.api.io.Resource resource,
                   org.kie.api.io.ResourceType type)

      Add a resource of the given ResourceType, using the default resource configuration.
      Parameters:
        `resource` - the Resource to add
        `type` - the resource type

    - #### add

          void add​(org.kie.api.io.Resource resource,
                   org.kie.api.io.ResourceType type,
                   org.kie.api.io.ResourceConfiguration configuration)

      Add a resource of the given ResourceType, using the provided ResourceConfiguration. Resources can be created by calling any of the "newX" factory methods of ResourceFactory. The kind of resource (DRL, XDRL, DSL,... CHANGE_SET) must be indicated by the second argument.
      Parameters:
        `resource` - the Resource to add
        `type` - the resource type
        `configuration` - the resource configuration

    - #### getKnowledgePackages

          Collection<org.kie.api.definition.KiePackage> getKnowledgePackages()

      Returns the built packages. If the KnowledgeBuilder has errors the Collection will be empty. The hasErrors() method should always be checked first, to make sure you are getting the packages that you wanted built.
      Returns:
        The Collection of KnowledgePackages

    - #### newKieBase

          org.kie.api.KieBase newKieBase()

      Creates a new KnowledgeBase from the knowledge packages that have been added to this builder. An exception is thrown if there are any errors.

    - #### hasErrors

          boolean hasErrors()

      If errors occurred during the build process they are added here
      Returns:

    - #### getErrors

          KnowledgeBuilderErrors getErrors()

      Return errors that occurred during the build process.
      Returns:

    - #### getResults

          KnowledgeBuilderResults getResults​(ResultSeverity... severities)

      Return the knowledge builder results for the listed severities.
      Parameters:
        `severities` -
      Returns:

    - #### hasResults

          boolean hasResults​(ResultSeverity... severities)

      Checks if the builder generated any results of the listed severities
      Parameters:
        `severities` -
      Returns:

    - #### undo

          void undo()

      Remove the last added Resource. Can be useful in case this last addition generated some compilation problem. If multiple Resources have been added in batch using a CompositeKnowledgeBuilder, it removes all of them.

    - #### batch

          CompositeKnowledgeBuilder batch()

      Return a CompositeKnowledgeBuilder allowing to add multiple Resources at the same time, without worrying about cross dependencies among them.
      Returns: