[jboss-svn-commits] JBL Code SVN: r24003 - in labs/jbossrules/trunk/drools-api/src/main/java/org/drools: agent and 1 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Thu Nov 20 14:21:48 EST 2008
Author: mark.proctor at jboss.com
Date: 2008-11-20 14:21:48 -0500 (Thu, 20 Nov 2008)
New Revision: 24003
Modified:
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/KnowledgeBase.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/KnowledgeBaseFactory.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/agent/KnowledgeAgent.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/agent/KnowledgeAgentFactory.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/agent/KnowledgeAgentProvider.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/agent/KnowledgeEventListener.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/builder/DecisionTableConfiguration.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/builder/DecisionTableInputType.java
labs/jbossrules/trunk/drools-api/src/main/java/org/drools/builder/KnowledgeBuilder.java
Log:
-some more javadocs
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/KnowledgeBase.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/KnowledgeBase.java 2008-11-20 18:59:13 UTC (rev 24002)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/KnowledgeBase.java 2008-11-20 19:21:48 UTC (rev 24003)
@@ -22,6 +22,7 @@
* KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
* </pre>
*
+ * @see org.drools.KnowledgeBaseFactory
*
*/
public interface KnowledgeBase
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/KnowledgeBaseFactory.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/KnowledgeBaseFactory.java 2008-11-20 18:59:13 UTC (rev 24002)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/KnowledgeBaseFactory.java 2008-11-20 19:21:48 UTC (rev 24003)
@@ -3,9 +3,15 @@
import java.util.Properties;
/**
+ * <p>
* This factory will create and return a KnowledgeBase instance, an optional KnowledgeBaseConfiguration
* can be provided. The KnowlegeBaseConfiguration is also itself created from this factory.
+ * </p>
+ * <pre>
+ * KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
+ * </pre>
*
+ * @see org.drools.KnowledgeBase
*/
public class KnowledgeBaseFactory {
private static KnowledgeBaseProvider provider;
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/agent/KnowledgeAgent.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/agent/KnowledgeAgent.java 2008-11-20 18:59:13 UTC (rev 24002)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/agent/KnowledgeAgent.java 2008-11-20 19:21:48 UTC (rev 24003)
@@ -3,12 +3,30 @@
import org.drools.KnowledgeBase;
/**
- * The KnowlegeAgent is created by the KnowlegeAgentFactory. It's roll is to provide a cached
+ * <p>
+ * The KnowlegeAgent is created by the KnowlegeAgentFactory. It's role is to provide a cached
* KnowlegeBase and to update or rebuild this KnowlegeBase as the resources it uses are changed.
* The strategy for this is determined by the configuration given to the factory, but it is
* typically pull based using regular polling. We hope to add push based updates and rebuilds in future
* versions.
+ * </p>
+ * <p>
+ * The Follow example constructs an agent that will build a new KnowledgeBase from the files specified in the path String.
+ * It will poll those files every 30 seconds to see if they are updated. If new files are found it will construct a new
+ * KnowledgeBase, instead of upating the existing one, due to the "newInstance" set to "true":
+ * <p/>
+ * <pre>
+ * Properties props = new Properties();
+ * props.setProperty( "file", path );
+ *
+ * props.setProperty( "newInstance", "true" );
+ * props.setProperty( "poll", "30" );
+ * KnowledgeAgent kagent = KnowledgeAgentFactory.newKnowledgeAgent( "agent1", props );
+ * KnowledgeBase kbase = kagent.getKnowledgeBase();
+ * </pre>
*
+ * @see org.drools.agent.KnowledgeAgentFactory
+ *
*/
public interface KnowledgeAgent {
/**
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/agent/KnowledgeAgentFactory.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/agent/KnowledgeAgentFactory.java 2008-11-20 18:59:13 UTC (rev 24002)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/agent/KnowledgeAgentFactory.java 2008-11-20 19:21:48 UTC (rev 24003)
@@ -2,6 +2,7 @@
import java.util.Properties;
+import org.drools.KnowledgeBase;
import org.drools.KnowledgeBaseConfiguration;
import org.drools.ProviderInitializationException;
@@ -78,10 +79,38 @@
* events happen, or errors/warnings occur. As the updating happens in a background thread, this may be important.
* The default event listener logs to the System.err output stream.
* </p>
+ *
+ * <p>
+ * The Follow example constructs an agent that will build a new KnowledgeBase from the files specified in the path String.
+ * It will poll those files every 30 seconds to see if they are updated. If new files are found it will construct a new
+ * KnowledgeBase, instead of upating the existing one, due to the "newInstance" set to "true":
+ * <p/>
+ * <pre>
+ * Properties props = new Properties();
+ * props.setProperty( "file", path );
+ *
+ * props.setProperty( "newInstance", "true" );
+ * props.setProperty( "poll", "30" );
+ * KnowledgeAgent kagent = KnowledgeAgentFactory.newKnowledgeAgent( "agent1", props );
+ * KnowledgeBase kbase = kagent.getKnowledgeBase();
+ * </pre>
+ *
+ * Notice the 'k' for Knowledge prefix for the variable names.
+ *
+ * * @see org.drools.agent.KnowledgeAgent
+ *
*/
public class KnowledgeAgentFactory {
private static KnowledgeAgentProvider provider;
+ /**
+ * Create and return a new KnowlegeAgent using the given name and configuration.
+ *
+ * @param name
+ * @param config
+ * @return
+ * The KnowledgeAgent
+ */
public static KnowledgeAgent newKnowledgeAgent(String name,
Properties config) {
return newKnowledgeAgent( name,
@@ -91,18 +120,27 @@
}
/**
- * This allows an optional listener to be passed in.
- * The default one prints some stuff out to System.err only when really needed.
+ * Create and return a new KnowlegeAgent using the given name and configuration.
+ * A listener is also specified for callback type logging on for info, warning,
+ * exception and debug. The KnowledgeBaseConfiguration will be used by the
+ * KnowledgeBases that the RuleAgent creates.
+ *
+ * @param name
+ * @param config
+ * @param listener
+ * @param kbaseConf
+ * @return
+ * The KnowledgeAgent
*/
public static KnowledgeAgent newKnowledgeAgent(String name,
Properties config,
KnowledgeEventListener listener,
- KnowledgeBaseConfiguration ruleBaseConf) {
+ KnowledgeBaseConfiguration kbaseConf) {
return getKnowledgeAgentProvider().newKnowledgeAgent( name,
config,
listener,
- ruleBaseConf );
+ kbaseConf );
}
private static synchronized void setKnowledgeAgentProvider(KnowledgeAgentProvider provider) {
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/agent/KnowledgeAgentProvider.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/agent/KnowledgeAgentProvider.java 2008-11-20 18:59:13 UTC (rev 24002)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/agent/KnowledgeAgentProvider.java 2008-11-20 19:21:48 UTC (rev 24003)
@@ -4,33 +4,41 @@
import org.drools.KnowledgeBaseConfiguration;
+/**
+ * KnowledgeAgentProvider is used by the KnowledgeAgentFacotry to "provide" it's concrete implementation.
+ *
+ * This class is not considered stable and may change, the user is protected from this change by using
+ * the Factory api, which is consiered stable.
+ *
+ */
public interface KnowledgeAgentProvider {
- KnowledgeAgent newKnowledgeAgent(String name,
- Properties config);
-
/**
- * Properties configured to load up packages into a KnowledgeBase with the provided
- * configuration (and monitor them for changes).
+ * Create and return a new KnowlegeAgent using the given name and configuration.
+ *
+ * @param name
+ * @param config
+ * @return
+ * The KnowledgeAgent
*/
KnowledgeAgent newKnowledgeAgent(String name,
- Properties config,
- KnowledgeBaseConfiguration ruleBaseConf);
+ Properties config);
/**
- * This allows an optional listener to be passed in.
- * The default one prints some stuff out to System.err only when really needed.
+ * Create and return a new KnowlegeAgent using the given name and configuration.
+ * A listener is also specified for callback type logging on for info, warning,
+ * exception and debug. The KnowledgeBaseConfiguration will be used by the
+ * KnowledgeBases that the RuleAgent creates.
+ *
+ * @param name
+ * @param config
+ * @param listener
+ * @param kbaseConf
+ * @return
+ * The KnowledgeAgent
*/
KnowledgeAgent newKnowledgeAgent(String name,
Properties config,
- KnowledgeEventListener listener);
-
- /**
- * This allows an optional listener to be passed in.
- * The default one prints some stuff out to System.err only when really needed.
- */
- KnowledgeAgent newKnowledgeAgent(String name,
- Properties config,
KnowledgeEventListener listener,
KnowledgeBaseConfiguration ruleBaseConf);
}
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/agent/KnowledgeEventListener.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/agent/KnowledgeEventListener.java 2008-11-20 18:59:13 UTC (rev 24002)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/agent/KnowledgeEventListener.java 2008-11-20 19:21:48 UTC (rev 24003)
@@ -1,5 +1,9 @@
package org.drools.agent;
+/**
+ * This interface is used to provide callback style logging for the agents
+ * async events.
+ */
public interface KnowledgeEventListener {
/**
* For general info messages
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/builder/DecisionTableConfiguration.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/builder/DecisionTableConfiguration.java 2008-11-20 18:59:13 UTC (rev 24002)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/builder/DecisionTableConfiguration.java 2008-11-20 19:21:48 UTC (rev 24003)
@@ -1,13 +1,46 @@
package org.drools.builder;
+/**
+ * ResourceConfiguration for decision tables. It allows for the type of the decision, XLS or CSV, to be specified
+ * and optionally allows a worksheet name to also be specified.
+ *
+ * <p>
+ * Simple example showing how to build a KnowledgeBase from an XLS resource.
+ * <p>
+ *
+ * <pre>
+ * KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
+ * DecisionTableConfiguration dtconf = KnowledgeBuilderFactory.newDecisionTableConfiguration();
+ * dtconf.setInputType( DecisionTableInputType.XLS );
+ * dtconf.setWorksheetName( "Tables_2" );
+ * kbuilder.addResource( new URL( "file://IntegrationExampleTest.xls" ),
+ * KnowledgeType.DTABLE,
+ * dtconf );
+ * assertFalse( kbuilder.hasErrors() );
+ * KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
+ * </pre>
+ *
+ */
public interface DecisionTableConfiguration
extends
ResourceConfiguration {
+ /**
+ * Specify the type of decision table resource, currently either XLS or CSV.
+ * This parameter is mandatory.
+ * @param inputType
+ */
void setInputType(DecisionTableInputType inputType);
DecisionTableInputType getInputType();
+ /**
+ * Which named xls worksheet should be used.
+ * This parameter is optional, and a default worksheet
+ * will be used if not specified.
+ *
+ * @param name
+ */
void setWorksheetName(String name);
String getWorksheetName();
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/builder/DecisionTableInputType.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/builder/DecisionTableInputType.java 2008-11-20 18:59:13 UTC (rev 24002)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/builder/DecisionTableInputType.java 2008-11-20 19:21:48 UTC (rev 24003)
@@ -1,5 +1,13 @@
package org.drools.builder;
+
+/**
+ * <p>
+ * Specifies the type of decision table resource.
+ * Currently either XLS or CSV.
+ * </p>
+ *
+ */
public enum DecisionTableInputType {
XLS, CSV;
}
Modified: labs/jbossrules/trunk/drools-api/src/main/java/org/drools/builder/KnowledgeBuilder.java
===================================================================
--- labs/jbossrules/trunk/drools-api/src/main/java/org/drools/builder/KnowledgeBuilder.java 2008-11-20 18:59:13 UTC (rev 24002)
+++ labs/jbossrules/trunk/drools-api/src/main/java/org/drools/builder/KnowledgeBuilder.java 2008-11-20 19:21:48 UTC (rev 24003)
@@ -6,21 +6,105 @@
import org.drools.definition.KnowledgePackage;
+/**
+ * <p>
+ * The KnowledgeBuilder is responsible for taking source files, such as a .drl file or an xls file,
+ * and turning them into a KnowledgePackage of rule and process definitions which a KnowledgeBase
+ * can consume. It uses the KnowledgeType enum to tell it the type of the resource it is being asked to build.
+ * </p>
+ *
+ * <p>
+ * Binaries, such as xls decision tables must use the URL based methods, so that an InputStream
+ * can be obtained. Reader is only suitable for text based resources.
+ * </p>
+ *
+ * <p>
+ * Always check the hasErrors() method after an addition, you should not add more resources
+ * or get the KnowledgePackages if there are errors; KnowledgePackages() will return empty
+ * if there are errors.
+ * <p>
+ *
+ * <p>
+ * Simple example showing how to build a KnowledgeBase from an DRL rule resource.
+ * <p>
+ * <pre>
+ * KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
+ * kbuilder.addResource( new URL( "file://myrules.drl" ),
+ * KnowledgeType.DRL);
+ * assertFalse( kbuilder.hasErrors() );
+ * KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
+ * </p>
+ *
+ * <p>
+ * Simple example showing how to build a KnowledgeBase from an XLS decision table resource.
+ * <p>
+ * <pre>
+ * KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
+ * DecisionTableConfiguration dtconf = KnowledgeBuilderFactory.newDecisionTableConfiguration();
+ * dtconf.setInputType( DecisionTableInputType.XLS );
+ * dtconf.setWorksheetName( "Tables_2" );
+ * kbuilder.addResource( new URL( "file://IntegrationExampleTest.xls" ),
+ * KnowledgeType.DTABLE,
+ * dtconf );
+ * assertFalse( kbuilder.hasErrors() );
+ * KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
+ * </pre>
+ *
+ * <p>
+ * Simple example showing how to build a KnowledgeBase from an DRF flow resource.
+ * <p>
+ * <pre>
+ * KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
+ * kbuilder.addResource( new URL( "file://myflow.rf" ),
+ * KnowledgeType.DRF);
+ * assertFalse( kbuilder.hasErrors() );
+ * KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
+ * </pre>
+ * <p>
+ * If there are errors a simple toString can print the errors
+ * </p>
+ * <pre>
+ * if ( kbuilder.hasErrors() ) {
+ * log.exception( kbuilder.getErrors().toString() )
+ * }
+ * </pre>
+ *
+ */
public interface KnowledgeBuilder
extends
RuleBuilder,
ProcessBuilder {
+ /**
+ * A a resource of the KnowledgeType from a given URL.
+ *
+ * @param url
+ * @param type
+ */
void addResource(URL url,
KnowledgeType type);
-
+ /**
+ * A a resource of the KnowledgeType from a given URL, using the provided ResourceConfiguration.
+ * Currently only only decision tables use this, via the DecisionTableResourceConfiguration class.
+ */
void addResource(URL url,
KnowledgeType type,
ResourceConfiguration configuration);
+ /**
+ * A a resource of the KnowledgeType from a given Reader.
+ *
+ * @param url
+ * @param type
+ */
void addResource(Reader reader,
KnowledgeType type);
+ /**
+ * A a resource of the KnowledgeType from a given URL, using the provided ResourceConfiguration.
+ * Currently only only decision tables use this, via the DecisionTableResourceConfiguration class.
+ * IF you use a Reader, make sure a text based decision table is used, such as CSV and not binary like XLS.
+ */
void addResource(Reader reader,
KnowledgeType type,
ResourceConfiguration configuration);
More information about the jboss-svn-commits
mailing list