org.drools.ChangeSet Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of knowledge-api Show documentation
The Drools and jBPM public API which is backwards compatible between releases.
The newest version!
/*
 * Copyright 2010 Red Hat, Inc. and/or its affiliates.
 *
 * Licensed 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.
 */

package org.drools;

import java.util.Collection;

import org.drools.io.Resource;

/**
 * 
 * This class is used to provide a ChangeSet info to a ResourceChangeNotifier. It should be used when you implement the ResourceChangeMonitor interface.
 * Each method provides a Collection of removed, added and modified resources, and determined by the monitor. Drools currently only provides the
 * ResourceChangeScanner, which scans the local disk for changes. The scanning only works with the ChangeSet is applied to a KnowledgeAgent, and not a KnowledgeBase. 
 * 
 * 
 * 
 * The xml format has a root level  element and then it can contain <add>, <modified>, <removed> elements - each one can only be used once.
 * add, modified, removed then contain a list of <resource> elements. Resources may take a configuration, currently only decision table resources use that.
 * 
 *
 * KnowledgeBuilder currently ignores Added/Modified xml elements, the KnowledgeAgent will use them, when rebuilding the KnowledgeBase.
 * 
 *  * <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>
 * 
 * 
 * Notice that each resource defines a protocol for it's source, this is because when using a ChangeSet all resource elements are turned into a URL instance, so it
 * obeys the format as provided by the JDK URL class. There is one exception which is the classpath protocol, which is handled separately. Here the resource is loaded
 * from the classpath, where it uses the default ClassLoader of the KnowledgeBase.

 * 
 * 
A path, when using file based protocols, can point to a folder. In such a situation all the resources in that folder will be added. When used with a KnowledgeAgent,
 * which is also set to scan directories, it will continue to scan the directory for new or removed resources.
 * 
 * 
 * The ChangeSet can be used as a ResourceType with the KnowledgeBuilder or applied directly to a KnowledgeAgent.
 * 
 * 
 * Example showing a changeset being used with a KnowledgeBuilder:
 *  * KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
 * kbuilder.add( ResourceFactory.newUrlResource( url ),
 *               ResourceType.ChangeSet );
 * 
 * 
 * Example showing a changeset being applied to a KnowledgeAgent:
 *  * KnowledgeAgent kagent = KnowledgeAgentFactory.newKnowledgeAgent( "MyAgent" );
 * kagent.applyChangeSet( ResourceFactory.newUrlResource( url ) );
 * KnowledgeBase kbase = kagent.getKnowledgeBase();
 * 
 * 
 * 
 * This interface, as well as ResourceChangeMonitor, ResourceChangeNotifier, ResourceChangeScanner and ResourceChangeListener are still considered subject to change. 
 * Use the XML format change-set, as part of the ResourceType api when adding to KnowledgeBuilder, which is considered stable.
 * 
 */
public interface ChangeSet {
    /**
     * Returns an immutable Collection of removed Resources for this ChangeSet
     * @return
     */
    public Collection getResourcesRemoved();

    /**
     * Returns an immutable Collection of added Resources for this ChangeSet
     * @return
     */
    public Collection getResourcesAdded();

    /**
     * Returns an immutable Collection of modified Resources for this ChangeSet
     * @return
     */
    public Collection getResourcesModified();

    /**
     * Returns a collection containing the full names (package+name) of the kdefinitions to be removed.
     * @return
     */
    Collection getKnowledgeDefinitionsRemoved();


}