org.drools.repository
Class RulesRepository

java.lang.Object
  extended by org.drools.repository.RulesRepository

public class RulesRepository
extends Object

RulesRepository is the class that defines the behavior for the JBoss Rules (drools) rule repository based upon the JCR specification (JSR-170).

An instance of this class is capable of storing rules used by the JBoss Rule engine. It also provides a versioning capability for rules. Rules can be imported from specified files. The RulesRepository is also capable of storing DSL content. Rules can be explicitly tied to a particular DSL node within the repository, and this reference can either follow the head version, or a specific version of the DSL node.

Rules can be tagged. Tags are stored in a separate area of the repository, and can be added on demand. Rules can have 0 or more tags. Tags are intended to help provide a means for searching for specific types of rules quickly, even when they aren't all part of the same rulepackage.

Rules can be associated with 0 or 1 states. States are created in a seperate area of the repository. States are intended to help track the progress of a rule as it traverses its life- cycle. (e.g. draft, approved, deprecated, etc.)

The RulesRepository provides versioning of rules, rule packages, and DSLs. This versioning works in a strictly linear fashion, with one version having at most 1 predecessor version (or none, if it is the first version), and at most 1 successor version (or none, if it is the most recently checked-in version). The JCR specification supports a more complicated versioning system, and if there is sufficient demand, we can modify our versioning scheme to be better aligned with JCR's versioning abilities.


Nested Class Summary
static class RulesRepository.DateQuery
           
 
Field Summary
static String CONFIGURATION_AREA
           
static String DEFAULT_PACKAGE
           
static String DEFAULT_WORKSPACE
           
static String DO_NOT_INSTALL_SAMPLE_NODE
          The name of the node to store user's preference if want to install the sample repository
static String DROOLS_URI
           
static String METADATA_TYPE_AREA
          The name of the meta data area within the JCR repository
static String PACKAGE_SNAPSHOT_AREA
          The name of the rulepackage area of the repository
static String PERSPECTIVES_CONFIGURATION_AREA
           
static String RULE_GLOBAL_AREA
           
static String RULE_PACKAGE_AREA
          The name of the rulepackage area of the repository
static String RULES_REPOSITORY_NAME
          The name of the rules repository within the JCR repository
static String SCHEMA_AREA
          The name of the schema area within the JCR repository
static String STATE_AREA
          The name of the state area of the repository
static String TAG_AREA
          The name of the tag area of the repository
static String WORKSPACE_AREA
          The name of the workspace area within the JCR repository
 
Constructor Summary
RulesRepository(javax.jcr.Session session)
          This requires a JCR session be setup, and the repository be configured.
 
Method Summary
protected static javax.jcr.Node addNodeIfNew(javax.jcr.Node parent, String nodeName, String type)
          Will add a node named 'nodeName' of type 'type' to 'parent' if such a node does not already exist.
 boolean containsPackage(String name)
          This returns true if the repository contains the specified package name.
 boolean containsSnapshot(String packageName, String snapshotName)
           
 String copyAsset(String uuidSource, String destinationPackage, String destinationName)
          This will copy an assets content to the new location.
 String copyPackage(String sourcePackageName, String destPackageName)
          Copy a package to the target name.
 void copyPackageSnapshot(String packageName, String snapshotName, String newName)
          Copies a snapshot to the new location/label.
 PackageItem createPackage(String name, String description)
          Adds a package to the repository.
 PackageItem createPackage(String name, String description, String format)
          Adds a package to the repository.
 PackageItem createPackage(String name, String description, String format, String[] workspace, String checkInComment)
          Adds a package to the repository.
 void createPackageSnapshot(String packageName, String snapshotName)
          This will copy the package to the snapshot area.
 StateItem createState(String name)
          Create a status node of the given name.
 PackageItem createSubPackage(String name, String description, String parentPackage)
          Adds a Sub package to the repository.
 javax.jcr.Node createWorkspace(String workspace)
          Create a status node of the given name.
 byte[] dumpPackageFromRepositoryXml(String packageName)
           
 byte[] exportPackageFromRepository(String packageName)
           
 void exportRulesRepositoryToStream(OutputStream output)
           
protected  void finalize()
           
 AssetItemIterator findArchivedAssets()
           
 AssetItemPageResult findAssetsByCategory(String categoryTag, boolean seekArchivedAsset, int skip, int numRowsToReturn)
          This will retrieve a list of RuleItem objects - that are allocated to the provided category.
 AssetItemPageResult findAssetsByCategory(String categoryTag, boolean seekArchivedAsset, int skip, int numRowsToReturn, RepositoryFilter filter)
          This will retrieve a list of RuleItem objects - that are allocated to the provided category.
 AssetItemPageResult findAssetsByCategory(String categoryTag, int skip, int numRowsToReturn)
           
 AssetItemIterator findAssetsByName(String name)
           
 AssetItemIterator findAssetsByName(String name, boolean seekArchived)
          This will search assets, looking for matches against the name.
 AssetItemIterator findAssetsByName(String name, boolean seekArchived, boolean isCaseSensitive)
          This will search assets, looking for matches against the name.
 AssetItemPageResult findAssetsByState(String stateName, boolean seekArchivedAsset, int skip, int numRowsToReturn)
          Finds the AssetItem's linked to the requested state.
 AssetItemPageResult findAssetsByState(String stateName, boolean seekArchivedAsset, int skip, int numRowsToReturn, RepositoryFilter filter)
          Finds the AssetItem's linked to the requested state.
 javax.jcr.Node getAreaNode(String areaName)
           
 javax.jcr.Session getSession()
           
 StateItem getState(String name)
          Gets a StateItem for the specified state name.
 void importPackageToRepository(byte[] byteArray, boolean importAsNew)
           
 void importRepository(InputStream in)
          Import the repository from a stream.
 void importRulesRepositoryFromStream(InputStream instream)
          Clean and import the rules repository.
 boolean isDoNotInstallSample()
           
 boolean isPackageArchived(String name)
          Check if package is archived.
 PackageIterator listPackages()
           
 String[] listPackageSnapshots(String packageName)
          Return a list of the snapshots available for the given package name.
 StateItem[] listStates()
           
 String[] listWorkspaces()
           
 AssetItem loadAssetByUUID(String uuid)
          Loads a rule by its UUID (generally the fastest way to load something).
 CategoryItem loadCategory(String tagName)
          This will return a category for the given category path.
 PackageItem loadDefaultPackage()
          This will return or create the default package for rules that have no home yet.
 PackageItem loadGlobalArea()
          This will return the global area for rules that can be shared.
 VersionableItem loadItemByUUID(String uuid)
          Similar to above.
 PackageItem loadPackage(String name)
          Loads a RulePackage for the specified package name.
 PackageItem loadPackage(String name, long versionNumber)
          Loads a RulePackage for the specified package name and version.
 PackageItem loadPackageByUUID(String uuid)
          Similar to above.
 PackageItem loadPackageSnapshot(String packageName, String snapshotName)
           
 StateItem loadState(String name)
           
 void logout()
          Explicitly logout of the underlying JCR repository.
 void moveRuleItemPackage(String newPackage, String uuid, String explanation)
          This moves a rule asset from one package to another, preserving history etc etc.
 AssetItemIterator query(Map<String,String[]> params, boolean seekArchived, RulesRepository.DateQuery[] dates)
          This will do a general predicate search.
 AssetItemIterator queryFullText(String qry, boolean seekArchived)
          This will search assets, looking for matches against the name.
 void removePackageSnapshot(String packageName, String snapshotName)
          This will remove the specified snapshot.
 void removeWorkspace(String workspace)
           
 String renameAsset(String uuid, String newAssetName)
          This will rename an asset and apply the change immediately.
 void renameCategory(String originalPath, String newName)
          Rename a category.
 String renamePackage(String uuid, String newPackageName)
          This will rename a package and apply the change immediately.
 void renameState(String oldName, String newName)
           
 void restoreHistoricalAsset(AssetItem versionToRestore, AssetItem headVersion, String comment)
          This will restore the historical version, save, and check it in as a new version with the given comment.
 void save()
          Save any pending changes.
 void setDoNotInstallSample()
           
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_PACKAGE

public static final String DEFAULT_PACKAGE
See Also:
Constant Field Values

DEFAULT_WORKSPACE

public static final String DEFAULT_WORKSPACE
See Also:
Constant Field Values

DROOLS_URI

public static final String DROOLS_URI
See Also:
Constant Field Values

RULE_PACKAGE_AREA

public static final String RULE_PACKAGE_AREA
The name of the rulepackage area of the repository

See Also:
Constant Field Values

RULE_GLOBAL_AREA

public static final String RULE_GLOBAL_AREA
See Also:
Constant Field Values

PACKAGE_SNAPSHOT_AREA

public static final String PACKAGE_SNAPSHOT_AREA
The name of the rulepackage area of the repository

See Also:
Constant Field Values

TAG_AREA

public static final String TAG_AREA
The name of the tag area of the repository

See Also:
Constant Field Values

STATE_AREA

public static final String STATE_AREA
The name of the state area of the repository

See Also:
Constant Field Values

CONFIGURATION_AREA

public static final String CONFIGURATION_AREA
See Also:
Constant Field Values

PERSPECTIVES_CONFIGURATION_AREA

public static final String PERSPECTIVES_CONFIGURATION_AREA
See Also:
Constant Field Values

SCHEMA_AREA

public static final String SCHEMA_AREA
The name of the schema area within the JCR repository

See Also:
Constant Field Values

METADATA_TYPE_AREA

public static final String METADATA_TYPE_AREA
The name of the meta data area within the JCR repository

See Also:
Constant Field Values

WORKSPACE_AREA

public static final String WORKSPACE_AREA
The name of the workspace area within the JCR repository

See Also:
Constant Field Values

DO_NOT_INSTALL_SAMPLE_NODE

public static final String DO_NOT_INSTALL_SAMPLE_NODE
The name of the node to store user's preference if want to install the sample repository

See Also:
Constant Field Values

RULES_REPOSITORY_NAME

public static final String RULES_REPOSITORY_NAME
The name of the rules repository within the JCR repository

See Also:
Constant Field Values
Constructor Detail

RulesRepository

public RulesRepository(javax.jcr.Session session)
This requires a JCR session be setup, and the repository be configured.

Method Detail

addNodeIfNew

protected static javax.jcr.Node addNodeIfNew(javax.jcr.Node parent,
                                             String nodeName,
                                             String type)
                                      throws RulesRepositoryException
Will add a node named 'nodeName' of type 'type' to 'parent' if such a node does not already exist.

Parameters:
parent - the parent node to add the new node to
nodeName - the name of the new node
type - the type of the new node
Returns:
a reference to the Node object that is created by the addition, or, if the node already existed, a reference to the pre-existant node.
Throws:
RulesRepositoryException

logout

public void logout()
Explicitly logout of the underlying JCR repository.


getAreaNode

public javax.jcr.Node getAreaNode(String areaName)
                           throws RulesRepositoryException
Throws:
RulesRepositoryException

copyAsset

public String copyAsset(String uuidSource,
                        String destinationPackage,
                        String destinationName)
This will copy an assets content to the new location.

Returns:
the UUID of the new asset.

loadPackage

public PackageItem loadPackage(String name)
                        throws RulesRepositoryException
Loads a RulePackage for the specified package name. Will throw an exception if the specified rule package does not exist.

Parameters:
name - the name of the package to load
Returns:
a RulePackageItem object
Throws:
RulesRepositoryException

loadPackage

public PackageItem loadPackage(String name,
                               long versionNumber)
                        throws RulesRepositoryException
Loads a RulePackage for the specified package name and version. Will throw an exception if the specified rule package does not exist.

Parameters:
name - the name of the package to load
versionNumber -
Returns:
a RulePackageItem object
Throws:
RulesRepositoryException

loadState

public StateItem loadState(String name)
                    throws RulesRepositoryException
Throws:
RulesRepositoryException

containsPackage

public boolean containsPackage(String name)
This returns true if the repository contains the specified package name.


isPackageArchived

public boolean isPackageArchived(String name)
Check if package is archived.


containsSnapshot

public boolean containsSnapshot(String packageName,
                                String snapshotName)

loadPackageSnapshot

public PackageItem loadPackageSnapshot(String packageName,
                                       String snapshotName)

createPackageSnapshot

public void createPackageSnapshot(String packageName,
                                  String snapshotName)
This will copy the package to the snapshot area. Creating a copy for deployment, etc.


removePackageSnapshot

public void removePackageSnapshot(String packageName,
                                  String snapshotName)
This will remove the specified snapshot.


copyPackageSnapshot

public void copyPackageSnapshot(String packageName,
                                String snapshotName,
                                String newName)
Copies a snapshot to the new location/label. If one exists at that location, it will be replaced.

Parameters:
packageName - The name of the package.
snapshotName - The label of the source snapshot
newName - The new label. The old one is left intact.

loadDefaultPackage

public PackageItem loadDefaultPackage()
                               throws RulesRepositoryException
This will return or create the default package for rules that have no home yet.

Throws:
RulesRepositoryException

loadGlobalArea

public PackageItem loadGlobalArea()
                           throws RulesRepositoryException
This will return the global area for rules that can be shared.

Throws:
RulesRepositoryException

loadPackageByUUID

public PackageItem loadPackageByUUID(String uuid)
                              throws RulesRepositoryException
Similar to above. Loads a RulePackage for the specified uuid.

Parameters:
uuid - the uuid of the package to load
Returns:
a RulePackageItem object
Throws:
RulesRepositoryException

loadItemByUUID

public VersionableItem loadItemByUUID(String uuid)
                               throws RulesRepositoryException
Similar to above. Loads a RulePackage or an AssetItem for the specified uuid.

Parameters:
uuid - the uuid of the package or asset to load
Returns:
a VersionableItem object
Throws:
RulesRepositoryException

restoreHistoricalAsset

public void restoreHistoricalAsset(AssetItem versionToRestore,
                                   AssetItem headVersion,
                                   String comment)
This will restore the historical version, save, and check it in as a new version with the given comment.

Parameters:
versionToRestore -
headVersion -
comment -

loadAssetByUUID

public AssetItem loadAssetByUUID(String uuid)
Loads a rule by its UUID (generally the fastest way to load something).


createPackage

public PackageItem createPackage(String name,
                                 String description)
                          throws RulesRepositoryException
Adds a package to the repository.

Parameters:
name - what to name the node added
description - what description to use for the node
Returns:
a PackageItem, encapsulating the created node
Throws:
RulesRepositoryException

createPackage

public PackageItem createPackage(String name,
                                 String description,
                                 String format)
                          throws RulesRepositoryException
Adds a package to the repository.

Parameters:
name - what to name the node added
description - what description to use for the node
format - module format.
Returns:
a PackageItem, encapsulating the created node
Throws:
RulesRepositoryException

createPackage

public PackageItem createPackage(String name,
                                 String description,
                                 String format,
                                 String[] workspace,
                                 String checkInComment)
                          throws RulesRepositoryException
Adds a package to the repository.

Parameters:
name - what to name the node added
description - what description to use for the node
format - module format.
workspace - the initial workspaces that this module belongs to.
Returns:
a PackageItem, encapsulating the created node
Throws:
RulesRepositoryException

createSubPackage

public PackageItem createSubPackage(String name,
                                    String description,
                                    String parentPackage)
                             throws RulesRepositoryException
Adds a Sub package to the repository.

Parameters:
name - what to name the node added
description - what description to use for the node
parentPackage - parent node under which this new package will be created
Returns:
a PackageItem, encapsulating the created node
Throws:
RulesRepositoryException

getState

public StateItem getState(String name)
                   throws RulesRepositoryException
Gets a StateItem for the specified state name. If a node for the specified state does not yet exist, one is first created.

Parameters:
name - the name of the state to get
Returns:
a StateItem object encapsulating the retrieved node
Throws:
RulesRepositoryException

createState

public StateItem createState(String name)
Create a status node of the given name.


listWorkspaces

public String[] listWorkspaces()
                        throws RulesRepositoryException
Throws:
RulesRepositoryException

createWorkspace

public javax.jcr.Node createWorkspace(String workspace)
Create a status node of the given name.


removeWorkspace

public void removeWorkspace(String workspace)

loadCategory

public CategoryItem loadCategory(String tagName)
                          throws RulesRepositoryException
This will return a category for the given category path.

Parameters:
tagName - the name of the tag to get. If the tag to get is within a hierarchy of tag nodes, specify the full path to the tag node of interest (e.g. if you want to get back 'child-tag', use "parent-tag/child-tag")
Returns:
a TagItem object encapsulating the node for the tag in the repository
Throws:
RulesRepositoryException

findAssetsByCategory

public AssetItemPageResult findAssetsByCategory(String categoryTag,
                                                boolean seekArchivedAsset,
                                                int skip,
                                                int numRowsToReturn)
                                         throws RulesRepositoryException
This will retrieve a list of RuleItem objects - that are allocated to the provided category. Only the latest versions of each RuleItem will be returned (you will have to delve into the rules deepest darkest history yourself... mahahahaha).

Throws:
RulesRepositoryException

findAssetsByCategory

public AssetItemPageResult findAssetsByCategory(String categoryTag,
                                                boolean seekArchivedAsset,
                                                int skip,
                                                int numRowsToReturn,
                                                RepositoryFilter filter)
                                         throws RulesRepositoryException
This will retrieve a list of RuleItem objects - that are allocated to the provided category. Only the latest versions of each RuleItem will be returned (you will have to delve into the rules deepest darkest history yourself... mahahahaha).

Pass in startRow of 0 to start at zero, numRowsToReturn can be set to -1 should you want it all.

Parameters:
filter - an AssetItem filter
Throws:
RulesRepositoryException

findAssetsByState

public AssetItemPageResult findAssetsByState(String stateName,
                                             boolean seekArchivedAsset,
                                             int skip,
                                             int numRowsToReturn)
                                      throws RulesRepositoryException
Finds the AssetItem's linked to the requested state. Similar to finding by category.

Throws:
RulesRepositoryException

findAssetsByState

public AssetItemPageResult findAssetsByState(String stateName,
                                             boolean seekArchivedAsset,
                                             int skip,
                                             int numRowsToReturn,
                                             RepositoryFilter filter)
                                      throws RulesRepositoryException
Finds the AssetItem's linked to the requested state. Similar to finding by category.

Parameters:
filter - an AssetItem filter
Throws:
RulesRepositoryException

findAssetsByCategory

public AssetItemPageResult findAssetsByCategory(String categoryTag,
                                                int skip,
                                                int numRowsToReturn)
                                         throws RulesRepositoryException
Throws:
RulesRepositoryException

exportRulesRepositoryToStream

public void exportRulesRepositoryToStream(OutputStream output)

exportPackageFromRepository

public byte[] exportPackageFromRepository(String packageName)
                                   throws IOException,
                                          javax.jcr.PathNotFoundException,
                                          javax.jcr.RepositoryException
Throws:
IOException
javax.jcr.PathNotFoundException
javax.jcr.RepositoryException

dumpPackageFromRepositoryXml

public byte[] dumpPackageFromRepositoryXml(String packageName)
                                    throws javax.jcr.PathNotFoundException,
                                           IOException,
                                           javax.jcr.RepositoryException
Throws:
javax.jcr.PathNotFoundException
IOException
javax.jcr.RepositoryException

importRepository

public void importRepository(InputStream in)
Import the repository from a stream.


importRulesRepositoryFromStream

public void importRulesRepositoryFromStream(InputStream instream)
Clean and import the rules repository. Will run any needed migrations as well.


importPackageToRepository

public void importPackageToRepository(byte[] byteArray,
                                      boolean importAsNew)

listPackages

public PackageIterator listPackages()
Returns:
an Iterator which will provide RulePackageItem's. This will show ALL the packages, only returning latest versions, by default.

getSession

public javax.jcr.Session getSession()
Returns:
The JCR session that this repository is using.

save

public void save()
Save any pending changes.


moveRuleItemPackage

public void moveRuleItemPackage(String newPackage,
                                String uuid,
                                String explanation)
This moves a rule asset from one package to another, preserving history etc etc.

Parameters:
newPackage - The destination package.
uuid - The UUID of the rule
explanation - The reason (which will be added as the checkin message).

renameAsset

public String renameAsset(String uuid,
                          String newAssetName)
This will rename an asset and apply the change immediately.

Returns:
the UUID of the new asset

renameCategory

public void renameCategory(String originalPath,
                           String newName)
Rename a category.

Parameters:
originalPath - The full path to the category.
newName - The new name (just the name, not the path).

renameState

public void renameState(String oldName,
                        String newName)

renamePackage

public String renamePackage(String uuid,
                            String newPackageName)
This will rename a package and apply the change immediately.

Returns:
the UUID of the package

listPackageSnapshots

public String[] listPackageSnapshots(String packageName)
Return a list of the snapshots available for the given package name.


findArchivedAssets

public AssetItemIterator findArchivedAssets()

findAssetsByName

public AssetItemIterator findAssetsByName(String name,
                                          boolean seekArchived)
This will search assets, looking for matches against the name.


findAssetsByName

public AssetItemIterator findAssetsByName(String name,
                                          boolean seekArchived,
                                          boolean isCaseSensitive)
This will search assets, looking for matches against the name.

Parameters:
name - The search text
seekArchived - True is Archived Assets should be included
isCaseSensitive - True is the search is case-sensitive

queryFullText

public AssetItemIterator queryFullText(String qry,
                                       boolean seekArchived)
This will search assets, looking for matches against the name.


query

public AssetItemIterator query(Map<String,String[]> params,
                               boolean seekArchived,
                               RulesRepository.DateQuery[] dates)
This will do a general predicate search.

Parameters:
params - - a map of field to a list of possible values (which are or-ed together if there is more then one).
seekArchived - - include archived stuff in the results.

findAssetsByName

public AssetItemIterator findAssetsByName(String name)

listStates

public StateItem[] listStates()
Returns:
A list of statii in the system.

copyPackage

public String copyPackage(String sourcePackageName,
                          String destPackageName)
Copy a package to the target name.


isDoNotInstallSample

public boolean isDoNotInstallSample()
                             throws javax.jcr.RepositoryException
Throws:
javax.jcr.RepositoryException

setDoNotInstallSample

public void setDoNotInstallSample()
                           throws javax.jcr.RepositoryException
Throws:
javax.jcr.RepositoryException

finalize

protected void finalize()
                 throws Throwable
Overrides:
finalize in class Object
Throws:
Throwable


Copyright © 2001-2012 JBoss by Red Hat. All Rights Reserved.