Builder User Guide. Version 5.4. Visual Rules Suite - Builder. Bosch Software Innovations

(1)

Builder User Guide

Version 5.4

Bosch Software Innovations

(2)

Visual Rules Builder User Guide, Version 5.4

Copyright © 2004-2012 Bosch Software Innovations GmbH

© Bosch Software Innovations GmbH, 2004-2012. All rights reserved. Dissemination or reproduction of this publication or any part of it for any purpose or in any form whatsoever is not permitted without the prior express written consent of Bosch Software Innovations GmbH. Information contained in this publication may be subject to revision without advance notice. MLDS, Visual Rules and Work Frame Relations are registered trademarks of Bosch Software Innovations GmbH. BOSCH and the symbol are registered trademarks of Robert Bosch GmbH, Germany. Some of the product and company names used in this document are trademarks and/or registered trademarks. They are used explicitly for reference purposes and are, independent of marking, prop-erty of their respective owners.

(3)

1. Introduction ... 1

1.1. Configuring the License ... 1

1.2. Contents of the Distribution ... 1

2. Using Maven ... 3

2.1. Overview ... 3

2.2. Installing Visual Rules Maven Plugins ... 3

2.3. Configuring the License File ... 4

2.4. Building the Provided Maven Example Project ... 4

2.5. Deploying Rule Artifacts for Usage in Visual Rules Modeler ... 4

2.6. Project Structure ... 5

2.7. Validating Rule Models ... 5

2.8. Testing Rule Models ... 6

2.9. Generating Documentation of Test Results ... 8

2.10. Generating Java Source Code ... 9

2.11. Generating Web Service Interface ... 10

2.12. Generating Manifest File ... 11

2.13. Checking in Files and Directories to a Visual Rules Team Server ... 13

2.14. Creating and Populating a Version in the Visual Rules Team Server ... 14

2.15. Deploying to Visual Rules Execution Server ... 15

3. Using the Ant Tasks ... 17

3.1. Overview ... 17

3.2. Running the Example Ant Build Script ... 17

3.3. Setting up the Ant Tasks ... 18

3.3.1. Defining the Ant Tasks with <taskdef> ... 18

3.3.2. Running Ant Scripts in Eclipse ... 19

3.4. Generating Java Rule Code with VRGenerate ... 20

3.5. Compiling Java Rule Code ... 21

3.6. Executing Rule Tests with VRTest ... 22

3.7. Generating the Rule Model Documentation with VRDoc ... 23

3.8. Checking out Rule Projects from a Visual Rules Team Server with VRCheckout ... 24

3.9. Checking in Files and Directories to a Visual Rules Team Server ... 25

3.10. Creating and Populating a Version in the Visual Rules Team Server ... 26

3.11. Deploying Rule Artifacts to Visual Rules Execution Server with VRDeploy ... 27

(4)

Chapter 1. Introduction

The Visual Rules Builder distirubtion is used to setup an automated rule change, test and deployment process. The automation is done using either Ant or Maven, two popular build automation tools for the Java platform. The Builder distribution contains the following Maven plugins:

• Rule model validation

• Generation of Java code from rule models • Generation of WSDL and XML schema files • Generation of Manifest files

• Deploying rule artifacts to a Visual Rules Execution Server

Further information about Maven is available on the internet at http://maven.apache.org/

The Builder distribution contains the following Ant tasks: • Checking out rule projects from a Visual Rules Team Server

• Generation of Java code from rule models (including validation, WSDL and Manifest) • Testing rules

• Generation of a rule project documentation

• Deploying rule artifacts to a Visual Rules Execution Server

Further information about Ant is available on the internet at http://ant.apache.org/.

1.1. Configuring the License

The Builder components require a valid license. If the file containing the license resides in the default location, which is the .visualrules5 folder in the current user's home directory, no additional configuration is necessary. Otherwise each task or plugin must be configured to read the license from a specified location. See the reference of either the Ant tasks or the Maven plugins for details.

1.2. Contents of the Distribution

(5)

Table 1.1. Contents of the distribution

Folder Contents Usage

doc Manuals (German and English)

eclipse Eclipse distribution containing the Ant tasks (mandatory for the VRDoc

task)

Section 3.3.2, “Running Ant Scripts in Eclipse” [19]

examples Examples Section 3.2, “Running the Example

Ant Build Script” [17]

Section 2.4, “Building the Provided Maven Example Project” [4]

lib Java libraries containing the Ant

tasks and their dependencies Section 3.3.1, “Defining the AntTasks with <taskdef>” [18]

runtime Visual Rules Runtime libraries as listed in

Table 3.8, “Visual Rules Runtime Dependencies” [28]

and

Table 3.9, “Visual Rules Databa-seIntegrator Runtime Dependen-cies” [29]

Section 3.5, “Compiling Java Rule Code” [21]

Section 3.6, “Executing Rule Tests with VRTest” [22]

Section 3.11, “Deploying Rule Ar-tifacts to Visual Rules Execution Server with VRDeploy” [27]

visualrules-mvnartifacts Deploy script with Maven artifacts

(6)

Chapter 2. Using Maven

2.1. Overview

The Visual Rules Builder distributions contains different Maven Plugins for the underlying functions in Visual Rules: • visualrules-validation-plugin for validating rule models

• visualrules-testing-plugin for running tests

• visualrules-testdocgenerator-plugin for creating a documentation of test results

• visualrules-javagenerator-plugin for the generation of Java code

• visualrules-wsdlgenerator-plugin for the generation of WSDL and XML schema files

• visualrules-manifestgenerator-plugin for creating the meta information for a rule artifact • visualrules-deploy-plugin for deploying an rule artifact to a Visual Rules Execution Server

For the following sections it is assumed that Maven is already installed and configured. Instructions and downloads can be found on the Maven website at http://maven.apache.org.

By default Eclipse does not provide a Maven integration out of the box. Therefore, Visual Rules Mod-eler, which is built upon the Eclipse platform, also does not provide any Maven integration. The M2 Eclipse Project is providing a Maven integration for Eclipse.

2.2. Installing Visual Rules Maven Plugins

The Visual Rules Maven Plugins must be accessible from a Maven repository. For this purpose the Builder distri-bution contains a script to deploy the plugins to a Maven repository. The script is called deploy.cmd for usage on Windows based systems and deploy.sh for usage on Unix based systems.

The distribution and use of the Visual Rules Maven Plugins may only be carried out with respect to the licence terms.

The script will deploy the plugins and their dependencies to a remote Maven repository. It must allow release type uploads and host normal artifacts as well as plugins. For instance an Apache Archiva installation is suitable for the task.

Detailed instructions for installing and configuring Apache Archiva can be found on the Internet at

http://archiva.apache.org/

The remote repository has to be added to the Maven configuration as normal and as plugin repository. The user-name and password information needs to be added as well. Consult the Maven documentation for information on how to do this.

Before the deployment script can be used, it has to be edited in order to add or adapt some required information. The first five lines of the script are variable definitions. Informations about the used remote repository have to be entered here. This example for the Windows script assumes running Apache Archiva on the local machine (local-host) listening on port 9090 with a default configuration and an id called releaseRepositoryID as specified in the settings.xml of Maven. set REPOSITORY_ID=releaseRepositoryID set REPOSITORY_LAYOUT=default set URL=http://localhost:9090/archiva/repository/releases/ set UNIQUE_VERSION=false set GOAL=deploy:deploy-file

(7)

Table 2.1. Variables for the deployment script

Variable Description

REPOSITORY_ID The id of the remote repository. This has to be the same as configured in the maven settings in the <servers> section.

REPOSITORY_LAYOUT Whether this repository uses the default layout or the legacy layout.

URL URL of the Maven repository into which the artifact will be deployed.

UNIQUE_VERSION Whether to deploy snapshots with a unique version or not.

GOAL If you set GOAL to install:install-file, the Maven plugins will be installed into the local Maven repository only. The default is deploy:deploy-file, which installs them into the repository specified by the URL above.

The artifacts in the Builder distribution are in the Maven 2 default layout. You can directly copy the ar-tifacts into a Maven 2 repository to use them.

2.3. Configuring the License File

If the license file is not in the default location as described in Section 1.1, “Configuring the License” [1], it is re-quired to set the license file for each plugin. Be aware that this makes the build process platform dependent.

Maven supports the concept of profiles, which can be used to cope with platform dependent builds. Consult the Maven documentation for details.

2.4. Building the Provided Maven Example Project

In order to import the example project select File -> New -> Example... in the menu. In the Visual Rules catego-ry choose Visual Rules Example Project and click Next >. Select the Movie Ticket Pricing Maven example and click Finish.

The Maven Plugins used in this example must be found in a Maven repository such as Apache Archi-va. It suffices to have a local installation running. The Builder distribution includes a script to install the Visual Rules Maven Plugins to a repository. This is further described in Section 2.2, “Installing Vi-sual Rules Maven Plugins” [3].

The following examples use Maven on the command line. For this a command prompt is required. This is specific for the used operating system and is not explained here.

Open a command prompt and navigate to your workspace. Change the directory to Movie Ticket Pricing Maven

and enter mvn package in the prompt.

Maven will start the build process that will use Visual Rules Maven Plugins for Validation and Generation of Java source code, WSDL, XML schema files and meta information. The result of the build is a Jar file that is usable as rule artifact in Visual Rules Modeler and on the Execution Server.

The pom.xml in the example project is configured to deploy the rule artifact to a default installation of a Visual Rules Execution Server. Before proceeding make sure the server is running. The Visual Rules Maven Deploy Plugin is executed during the install build phase. By entering mvn install in the prompt the build process starts again

in-stalling the artifact into the local Maven repository and deploying it to the Visual Rules Execution Server.

(8)

to a Maven repository using the mvn deploy command. For this the distributionManagement entry has to be added to the pom.xml of the project. This defines the repositories an artifact can be deployed to. These should be reposi-tories that are configured in Visual Rules Modeler for downloading artifacts.

The following snippet shows how this may look like for a default installation of Apache Archiva. Two Maven repos-itories are defined: one for snapshots and one for releases. This is a concept of Maven, which is further explained in the documentation at http://maven.apache.org.

<project ...> ... <distributionManagement> <snapshotRepository> <id>snapshotRepositoryID</id> <uniqueVersion>false</uniqueVersion> <url>dav:http://localhost:8080/archiva/repository/snapshots/</url> </snapshotRepository> <repository> <id>releaseRepositoryID</id> <url>dav:http://localhost:8080/archiva/repository/releases/</url> </repository> </distributionManagement> ... </project> 2.6. Project Structure

The Movie Ticket Pricing Maven example is structured differently than a "normal" rule project. The rule model and its files are found in the source folder src/main/rules. For the model to be included in the artifact, it is advisable to move them to a directory that does not conflict with the compiled byte code. For this the pom.xml contains the fol-lowing configuration: <project ...> ... <build> <resources> <resource> <targetPath>META-INF/visualrules/models</targetPath> <directory>src/main/rules</directory> </resource> </resources> ... </build> ... </project>

After a mvn package command, the model files will be found in the folder META-INF/visualrules/models in the JAR.

It is strongly advised that model files do not reside directly under src/main/rules or src/main/re-sources without the configuration mentioned above. In that case it is likely that the model folders and the packages of the generated code are conflicting in regard to case sensitivity, which will lead to an unusable rule artifact.

Another thing to notice is the target folder where Maven puts all created files as well as the compiled byte code. In

the example, the code generator is configured to use target/generated-sources/visualrules as target folder. It is a source folder, so it can be used within Eclipse as well as in a Maven build.

After a successful build using the mvn package command, the created rule artifact can also be found in the target

folder.

2.7. Validating Rule Models

The Visual Rules Maven Validation Plugin applies all validation rules on every rule model in the project. If an error is found a build failure is triggered.

The purpose of the visualrules-validation-plugin is to validate rule models before other plugins start processing them. It is intended that it should run in the validate phase.

(9)

Example 2.1. Example for the visualrules-validation-plugin <build> ... <plugins> ... <plugin> <groupId>de.visualrules.maven</groupId> <artifactId>visualrules-validation-plugin</artifactId> <version>${vrVersion}</version> <executions> <execution> <configuration>  <licensefile>C:\mycompany\mylicense.txt</licensefile>  <verbose>false</verbose>  <writeXmlReport>false</writeXmlReport> </configuration> <goals> <goal>validate</goal> </goals> </execution> </executions> </plugin> ... </plugins> ... </build>

Table 2.2. Parameters for the visualrules-validation-plugin

Parameter Description Required Type

verbose If true all warning and error messages are printed to the

console, otherwise only the first error message. No (default:false) boolean licensefile The path to a valid license file. This is required if the

li-cense file is not in the default location. No File writeXmlReport If true all validation messages are written to an XML

re-port file. Rere-ports are found in the rere-porting folder, e.g.

target/site/visual-rules-reports

No (default:

false)

boolean

2.8. Testing Rule Models

The visualrules-testing-plugin is used to execute Visual Rules tests in the build process. By default each test

within the project will be run. If one of the tests does not pass the output of the build process is considered incor-rect and thus a build failure is triggered. The plugin can also be configured to use a pattern for test suites. In that mode, all test suites found by the pattern are run. On test failure the same behavior applies as mentioned before. It is not possible to run tests and test suites at the same time.

The test results are printed by default to the console and as well written into a XML file. It is also possible to write a more detailed report which also contains the statistics. This test report archive can be viewed in the Visual Rules Modeler. Reports are found in the reporting folder, e.g. target/site/visual-rules-reports. The genera-tion of a summarizing HTML documentagenera-tion is described in Section 2.9, “Generating Documentation of Test Re-sults” [8].

Last but not least, there are options to configure the execution of all tests by defining a global binding configuration and statistics level for requests and sessions. Note that this always will override any setting defined in the individu-al test or test suite.

(10)

Example 2.2. Example for the visualrules-testing-plugin <build> ... <plugins> ... <plugin> <groupId>de.visualrules.maven</groupId> <artifactId>visualrules-testing-plugin</artifactId> <version>${vrVersion}</version> <executions> <execution> <configuration>  <licensefile>C:\mycompany\mylicense.txt</licensefile>  <testSuitePattern>All Tests</testSuitePattern>  <writeTestReportArchive>true</writeTestReportArchive>  <writeXmlReport>true</writeXmlReport>  <activeConfigurationName>production</activeConfigurationName>  <requestStatisticsLevel>medium</requestStatisticsLevel>  <sessionStatisticsLevel>medium</sessionStatisticsLevel>  <verbose>false</verbose> </configuration> <goals> <goal>test</goal> </goals> </execution> </executions> </plugin> ... </plugins> ... </build>

(11)

Table 2.3. Parameters for the visualrules-testing-plugin

verbose If true information about each executed test is printed to

the console. No (default:false) boolean

licensefile The path to a valid license file. This is required if the

li-cense file is not in the default location. No File testSuitePattern The pattern denoting the test suites. This is typically a

file name that can contain wildcards. To express one ar-bitrary character a ? is used and * for multiple arbitrary

characters. For example the pattern All* would find All Tests as well as All Nightly Tests.

No String

writeTestRe-portArchive If sults and statistics which can be viewed in the Visualtrue a archive will be created containing the test re-Rules Modeler.

No (default:

false) boolean writeXmlReport If true the test results are written in a simple XML

for-mat. No (default:true)

boolean

activeConfigu-rationName Name of the configuration for the rule execution that willbe used by all tests. No String

requestStatistic-sLevel The level of the statistics for the request to be used byall tests. Valid values are (not case-sensitive): QUIET,

LOW, MEDIUM or HIGH.

No String

sessionStatis-ticsLevel The level of the statistics for the session to be used byall tests. Valid values are (not case-sensitive): QUIET,

LOW, MEDIUM or HIGH.

No String

2.9. Generating Documentation of Test Results

The visualrules-testdocgenerator-plugin Maven Plugin is capable of generating a summarizing HTML docu-mentation of all test results. It's necessary that the execution of tests, including the creation of XML reports, has already taken place. The generated report TestResults.html is found in the same reporting folder as the XML

re-ports, e.g. target/site/visual-rules-reports.

(12)

Example 2.3. Example for the visualrules-testdocgenerator-plugin <build> ... <plugins> ... <plugin> <groupId>de.visualrules.maven</groupId> <artifactId>visualrules-testdocgenerator-plugin</artifactId> <version>${vrVersion}</version> <executions> <execution> <configuration>  <licensefile>C:\mycompany\mylicense.txt</licensefile> </configuration> <phase>site</phase> <goals> <goal>generate-testdoc</goal> </goals> </execution> </executions> </plugin> ... </plugins> ... </build>

Table 2.4. Parameters for the visualrules-testdocgenerator-plugin

li-cense file is not in the default location. No File

2.10. Generating Java Source Code

The visualrules-javagenerator-plugin Maven Plugin is responsible for generating Java source code. Normally a folder in the target directory of the project is used. If a target folder is specified in the rule model, this will be used instead. However not all settings are applicable in a Maven build, e.g. when writing to a different project. For this the parameter targetDirectory can be set, which will override the setting from the model.

(13)

Example 2.4. Example for the visualrules-javagenerator-plugin <build> ... <plugins> ... <plugin> <groupId>de.visualrules.maven</groupId> <artifactId>visualrules-javagenerator-plugin</artifactId> <version>${vrVersion}</version> <executions> <execution> <configuration>  <verbose>false</verbose>  <licensefile>C:\mycompany\mylicense.txt</licensefile>  <targetDirectory>target/vr-srcgen</targetDirectory> </configuration> <goals> <goal>generate</goal> </goals> </execution> </executions> </plugin> ... </plugins> ... </build>

Table 2.5. Parameters for the visualrules-javagenerator-plugin

verbose If true, all warning and error messages are printed to the console, otherwise only two messages (at the begin-ning and the end) are printed.

No (default:

false) boolean targetDirectory The folder where the code generator places the source.

This can be an absolute or a relative path. This setting overrides the target directory defined in the model.

No File

encoding Sets the encoding of the generated Java source code. If this setting is not configured, the default from the Java virtual machine is used. Note that the encoding on the rulemodel will always be used if it is specified there.

No String

2.11. Generating Web Service Interface

The visualrules-wsdlgenerator-plugin Maven Plugin is capable of generating WSDL and XML schema files used for the Web Service interface. This enables the artifact to be used on the Visual Rules Execution Server.

(14)

Example 2.5. Example for the visualrules-wsdlgenerator-plugin <build> ... <plugins> ... <plugin> <groupId>de.visualrules.maven</groupId> <artifactId>visualrules-wsdlgenerator-plugin</artifactId> <version>${vrVersion}</version> <executions> <execution> <configuration>  <licensefile>C:\mycompany\mylicense.txt</licensefile> </configuration> <goals> <goal>generate</goal> </goals> </execution> </executions> </plugin> ... </plugins> ... </build>

Table 2.6. Parameters for the visualrules-wsdlgenerator-plugin

2.12. Generating Manifest File

The visualrules-manifestgenerator-plugin is used to generate this meta information. It is intended that this is used in conjunction with the Java- and WSDL Generator Plugin. If there are multiple rule models in the project, one must be chosen as entry point.

(15)

Example 2.6. Example for the visualrules-manifestgenerator-plugin <build> ... <plugins> ... <plugin> <groupId>de.visualrules.maven</groupId> <artifactId>visualrules-manifestgenerator-plugin</artifactId> <version>${vrVersion}</version> <executions> <execution> <configuration> <includesWebService>true</includesWebService>  <licensefile>C:\mycompany\mylicense.txt</licensefile>  <entryModel>MyModelName</entryModel> </configuration> <goals> <goal>generate</goal> </goals> </execution> </executions> </plugin> ... </plugins> ... </build>

In order for the Manifest file to be included in the artifact, the maven-jar-plugin must be configured as follows: <build> ... <pluginManagement> ... <plugins> ... <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-jar-plugin</artifactId> <configuration> <useDefaultManifestFile>true</useDefaultManifestFile> </configuration> </plugin> ... </plugins> </pluginManagement> ... </build>

Table 2.7. Parameters for the visualrules-manifestgenerator-plugin

includesWeb-Service Set this to Generator Plugin.true, if used in conjunction with the WSDL Yes boolean entryModel If more then one rule model is in the project then it is

re-quired to specify the name of the one that is intended to be called as entry point. This can be omitted if only one model exists.

No String

(16)

2.13. Checking in Files and Directories to a Visual Rules Team Server

The following example illustrates how to check in a file or a directory to a Visual Rules Team Server 5.x (separately available) with the aid of the Maven Plugin visualrules-team-plugin:

Example 2.7. Example for visualrules-team-plugin to checkin files and directories

<build> ... <plugins> ... <plugin> <groupId>de.visualrules.maven</groupId> <artifactId>visualrules-team-plugin</artifactId> <version>${vrVersion}</version> <executions> <execution> <configuration> <url>http://localhost:8080/teamserver</url> <username>admin</username> <password>admin</password>

<destination>Movie Ticket Pricing</destination> <repository>RuleRepository</repository> <fileset> <directory>${basedir}</directory> <includes> <include>**/*</include> </includes> <excludes> <exclude>target/*</exclude> </excludes> </fileset> </configuration> <goals> <goal>checkin</goal> </goals> </execution> </executions> </plugin> ... </plugins> ... </build>

(17)

Table 2.8. Parameters for the visualrules-team-plugin to checkin files and directories

url The URL of the

Team Server Back-end (e.g. http:// some.host.com:8080/ teamserver). For Team Server 5.x.x.

Yes URL

username The username used for

lo-gin Yes String

password The password used for

lo-gin Yes String

repository The name of the

reposito-ry. Yes String

destination The name of the folder, in which the files and direc-tories are to be checked in (will be created, if neces-sary)

Yes String

fileset Files and directories to be

checked in Yes Fileset

version The target version, in which the destination will be placed.

No. If not specified, the latest version in the repos-itory will be fetched.

String

encoding The encoding of the files to be checked in to the Team Server.

No (Standard: The Java

Encoding) String

commitComment Comment for the check in. No (Standard: without

comment) String

licensefile Path of the license file No. If not speci-fied, the directory

<user.home>/.visualrules5 will be scanned for a li-cense file.

File

2.14. Creating and Populating a Version in the Visual Rules Team Server

The following example illustrates how to create a new version in the Visual Rules Team Server (version 5.x) and populate it with a project with the aid of the Maven Plugin visualrules-team-plugin:

(18)

Example 2.8. Example for the visualrules-team-plugin to create and populate a Version in Team Server <build> ... <plugins> ... <plugin> <groupId>de.visualrules.maven</groupId> <artifactId>visualrules-team-plugin</artifactId> <version>${vrVersion}</version> <executions> <execution> <configuration> <url>http://localhost:8080/teamserver</url> <username>admin</username> <password>admin</password> <repository>RuleRepository</repository> <projects>Movie Ticket Pricing</projects> <version>HEAD</version> <newVersion>Version 1.0.x</newVersion> </configuration> <goals> <goal>version</goal> </goals> </execution> </executions> </plugin> ... </plugins> ... </build>

Table 2.9. Parameters for the visualrules-team-plugin

url The URL of the Team Server Backend (e.g. http://

some.host.com:8080/teamserver). Yes URL

username The username used for login Yes String

password The password used for login Yes String

repository The repository name Yes String

newVersion Name of the version to be newly created Yes String version Specification of a given version from which the projects

are to be copied No (standard:the latest ver-sion)

String

projects Specification of one or more projects, which are as-signed to the newly generated version. Multiple projects can be separated by |.

Yes String

licensefile Path of the license file No. If not

specified, the directory <user.home>/.visualrules5 will be scanned for a license file. File

2.15. Deploying to Visual Rules Execution Server

The visualrules-deploy-plugin deploys a rule artifact and all dependencies to a running Visual Rules Execution Server. This means that the plugin must run in a phase after the package phase.

(19)

Example 2.9. Example for the visualrules-deploy-plugin <build> ... <plugins> ... <plugin> <groupId>de.visualrules.maven</groupId> <artifactId>visualrules-deploy-plugin</artifactId> <version>${vrVersion}</version> <configuration> <url>http://localhost:8080/executionserver/admin/upload</url> <user>admin</user> <password>admin</password>  <timeout>5000</timeout>  <licensefile>C:\mycompany\mylicense.txt</licensefile> </configuration> <executions> <execution> <phase>install</phase> <goals> <goal>vrdeploy</goal> </goals> </execution> </executions> </plugin> ... </plugins> ... </build>

Table 2.10. Parameters for the visualrules-deploy-plugin

url The URL of the Visual Rules Execution Server. Yes String

user The name of the user on the server. Yes String

password The password of the user on the server. Yes String

timeout The connection timeout in milliseconds. This must be a

positive value. No Integer

(20)

Chapter 3. Using the Ant Tasks

3.1. Overview

The Visual Rules Builder distribution contains the following Ant tasks: • VRGenerate for the generation of Java code

• VRTest for testing of rules

• VRDoc for the generation of rule project documentation

• VRCheckout for checking out rule projects from a Visual Rules Team Server • VRCheckin for the checking in files into the Visual Rules Team Server

• VRVersion for the generation and population of a version in the Visual Rules Team Server • VRDeploy for deploying rule artifacts to the Visual Rules Execution Server

• VRArchiveDeploy for deploying Visual Rules Archive (VRA) files to the Visual Rules Execution Server

3.2. Running the Example Ant Build Script

The Builder distribution includes an example project to illustrate the use of the Ant tasks.

You need to have a Java Development Kit (JDK) and Apache Ant installed and configured correctly to run the example. The bin folder of the Ant distribution must be on your PATH and the ANT_HOME envi-ronment variable must be set. See http://ant.apache.org for details.

1. Open a command line and go to the Movie Ticket Pricing Ant folder. You can find it in the examples folder of the Builder distribution, e.g.:

C:\VR5-builder\examples\Movie Ticket Pricing Ant>

2. The project contains the files build.xml and buildDoc.xml. These are Ant build scripts that illustrate the use of the Ant tasks. Run Ant to execute the build script build.xml.

The Ant build script will generate the rule model documentation (VRDoc), then generate the rule code ( VRGener-ate), compile it and finally execute rule tests and a test suite (VRTest). The output will look like this:

C:\VR5-builder\examples\Movie Ticket Pricing Ant>ant Buildfile: build.xml

generateDocumentation:

[java] Buildfile: buildDoc.xml [java]

[java] generateDocumentation:

[java] [VRDoc] Generated report at D:\VR5-builder\examples\Movie Ticket Pricing Ant\documentation

[java] BUILD SUCCESSFUL [java]

[java] BUILD SUCCESSFUL [java] Total time: 4 seconds generateRuleCode:

[VRGenerate] Generated 26 Java source files to C:\VR5-builder\examples\Movie Ticket Pricing Ant\src-ant

[VRGenerate] Generated wsdl to C:\VR5-builder\examples\Movie Ticket Pricing Ant\src-ant \META-INF\visualrules\webservice

[VRGenerate] Generated MANIFEST.MF to C:\VR5-builder\examples\Movie Ticket Pricing Ant\src-ant\META-INF

compile:

[javac] Compiling 25 source files to C:\VR5-builder\examples\Movie Ticket Pricing Ant \bin-ant

(21)

[javac] Note: Recompile with -Xlint:unchecked for details. executeTests:

[VRTest] Test 'BonusPoints Test' executed in 50ms (7/7 test cases processed, 7.14ms per case).

[VRTest] Test 'Pricing Test' executed in 50ms (8/8 test cases processed, 6.25ms per case).

executeTestSuite:

[VRTest] Test 'BonusPoints Test' executed in 30ms (7/7 test cases processed, 4.29ms per case).

[VRTest] Test 'Pricing Test' executed in 20ms (8/8 test cases processed, 2.5ms per case).

[VRTest] Test suite 'All Tests' processed. all:

BUILD SUCCESSFUL Total time: 12 seconds

3. If you have a Visual Rules Execution Server, you can also run the deployArtifact target in build.xml to create a rule artifact and deploy it to the Execution Server (VRDeploy).

You will have to configure the parameters of the VRDeploy task in build.xml to match your environment, i.e. you will have to specify the Execution Server URL, user name and password.

If you run the deployArtifact target, the output will look like this:

C:\VR5-builder\examples\Movie Ticket Pricing Ant>ant deployArtifact Buildfile: build.xml

generateRuleCode:

[VRGenerate] Generated 26 Java source files to C:\VR5-builder\examples\Movie Ticket Pricing Ant\src-ant

[VRGenerate] Generated wsdl to C:\VR5-builder\examples\Movie Ticket Pricing Ant\src-ant \META-INF\visualrules\webservice

[VRGenerate] Generated MANIFEST.MF to C:\VR5-builder\examples\Movie Ticket Pricing Ant\src-ant\META-INF

compile:

[javac] Compiling 25 source files to C:\VR5-builder\examples\Movie Ticket Pricing Ant \bin-ant

[javac] Note: Some input files use unchecked or unsafe operations. [javac] Note: Recompile with -Xlint:unchecked for details.

createArtifact:

[jar] Building jar: C:\VR5-builder\examples\Movie Ticket Pricing Ant \movieticketpricing-1.0.jar

deployArtifact:

[VRDeploy] Successfully deployed C:\VR5-builder\examples\Movie Ticket Pricing Ant \movieticketpricing-1.0.jar

as movie-ticket-pricing-ant:Movie-Ticket-Pricing-Ant:1.0 to http:// localhost:8080/executionserver-4.6.1/admin/upload

BUILD SUCCESSFUL Total time: 6 seconds

3.3. Setting up the Ant Tasks

(22)

You will have to set the property builder.home to the location where you have installed the Builder distribution. <property name="builder.home" value="C:\VR5-builder" />

The VRDoc task cannot be used this way, because it only works within Eclipse. See the following sec-tion.

3.3.2. Running Ant Scripts in Eclipse

The VRDoc task only works within a running Eclipse which has the Visual Rules Modeler plugins installed. The Builder distribution provides such an Eclipse within the eclipse folder.

Eclipse provides the ability to execute Ant scripts with the Eclipse AntRunner. You can execute the Eclipse AntRunner from the command line like this:

C:\>java -jar "C:\Progam Files\Visual Rules\eclipse\plugins \org.eclipse.equinox.launcher_1.0.201.R35x_v20090715.jar" -application org.eclipse.ant.core.antRunner

-buildfile "Movie Ticket Pricing Ant\build.xml" generateDocumentation

The -buildfile option specifies the Ant build script to use, and generateDocumentation denotes the Ant target in the example above.

If you want to start the Eclipse AntRunner from a regular Ant build script, you can use the java task to do this (the "Movie Ticket Pricing Ant" example does this):

You can run all Visual Rules Ant tasks with AntRunner, but it is needed and recommended only for the VRDoc task.

(23)

3.4. Generating Java Rule Code with VRGenerate

The VRGenerate task is used for the generation of Java rule code. The task can be used as follows: <VRGenerate modelFile="${modelFile}" targetDir="${src-dir}" >

(24)

Table 3.1. Parameters for the VRGenerate Ant task

Attribute Description Required Ant Type

modelFile Path to the rule model file Yes file

targetDir Path to the target directory Yes directory

modelpath A nested path denoting folders and jars that contain additional rule model files (e.g. referenced via Reuse Packages)

No path

modelFolders Please note that this attribute is deprecated. Use mod-elpath instead. A nested directory set (dirSet) denoting the folder(s) that contain additional rule model files (e.g. referenced via Reuse Packages).

No dirset

validateModel Whether or not the model should validated prior to code

generation No (default:true) boolean

failOnValida-tionErrors Please note that this attribute is deprecated and has noeffect anymore. It was used to trigger a build failure in the case of a validation error. This is now the default be-havior but may be deactivated by setting validateModel

to false. No (default: true) boolean enableStatistic- sAndListener-Code

Whether or not to enable the generation of the code necessary to support collection of execution statistics and custom listeners

No (default:

true) boolean

checkPathLimit Whether or not to check, if the generated files exceed the Windows path limit. If set to true the build will fail in case the limit is exceeded.

No (default:

false) boolean

generatemani-fest Whether or not to generate a informations about the Rule Model or not. The resultingMANIFEST.MF file containing file will be created in the folder <targetDir>/META-INF.

No (default:

false)

boolean

generatewsdl Whether or not to generate WSDL and XML schema files containing web service definitions of the rules that are exported as web services. The resulting files will be created in the folder <targetDir>/META-INF/visual-rules/webservice. When both wsdl generation and

man-ifest generation are enabled the resulting manman-ifest file will also contain information about the web services.

No (default:

false) boolean

encoding Sets the encoding of the generated Java source code. If this setting is not configured, the default from the Java virtual machine is used. Note that the encoding on the rulemodel will always be used if it is specified there.

No String

licenseFile Path to a license file No. If not

speci-fied the default license file lo-cation will be scanned for a li-cense file and the one found there will be used.

file

3.5. Compiling Java Rule Code

The generated rule code can be compiled with the javac task. The generated code has dependencies to several li-braries: the Visual Rules runtime library, several third party utility libraries and the libraries additionally introduced

(25)

by the user (for example for custom functions, Java type libraries etc.). These libraries have to be on the classpath of the javac task in order to compile the code. In the example the compilation of the rule code looks as follows. <javac srcdir="${basedir}/src-ant" destdir="${basedir}/bin-ant">

3.6. Executing Rule Tests with VRTest

The VRTest task can be used to execute one or more rule tests and/or test suites. In the example provided, the

VRTest task is used as shown below.

<modelPath>

(26)

Table 3.2. Parameters for the VRTest Ant task

Attribute/Ele-ment Description Required Ant Type

tests A nested path denoting all tests and/or test suites which

should be to executed. Yes Path

modelpath A nested path denoting folders and jars that contain ad-ditional rule model files (e.g. referenced via reuse pack-ages)

Yes Path

classpath A nested path denoting folders and/or jars containing

the compiled rule code and/or additional classes (e.g. custom actions/functions or business object model).

Yes Path

summaryRe-portDir Specifies the target directory for test summary reports(simple xml files providing information about which tests failed and which not). If not assigned no summary report will be created (default).

No String

generateHtml-Report Set to sults is generated in HTML format and saved astrue a summarizing report of all test

re-TestResults.html in the directory specified by summa-ryReportDir. If summaryReportDir isn't defined the HTML report won't be created.

No (default:

false) Boolean

executionRe-sultDir Specifies the target directory for execution files (*.vrex-ecution) These files can be copied into the Visual Rules Modeler to inspect detailed test results and execution statistics. If not assigned no execution file will be creat-ed (default).

No String

failOnError Set to true the VRTest task will raise an exception if at

least one test execution failed. All tests will be executed. No (default:true) Boolean

activeConfigu-rationName Specifies the name of the configuration which shouldbe used for test execution. Overwrites all configurations that might be set on executed tests or test suites (avail-able since version 5.2, this attribute is known as config-uration in former versions; this is still supported).

No String

verbose If set to true status messages about test execution will

be reported on standard output. No (default:false) Boolean

requestStatistic-sLevel Overwrites the statistics level for every test case. No Enumeration(possilbe values are none, medium, high)

sessionStatis-ticsLevel Overwrites the statistics level for entire tests. No Enumeration(possilbe values are none, medium,

high) licenseFile Path to a license file. If not specified the default license

file location will be scanned for a license file and the one found there will be used.

No File

3.7. Generating the Rule Model Documentation with VRDoc

The VRDoc task generates the documentation for a rule model. It is possible to generate the documentation in either HTML or PDF format. In the example provided the documentation is generated in HTML format, which is the de-fault setting.

(27)

Since the VRDoc task creates images for the rule documentation, a running graphical environment is needed on the system it is executed on.

Additionally, the VRDoc task can only be used on platforms that are supported by the Standard Widget Toolkit (SWT). For more information please visit http://www.eclipse.org/swt

Table 3.3. Parameters for the VRDoc Ant task

modelFile Path to the rule model file Yes File

targetDir Path to the target directory Yes Directory

modelpath A nested path denoting folders and jars that contain

additional rule model files (e.g. referenced via Reuse Packages)

No path

reportType The type of the report. Either html, pdf or word. No (default:

html) Enumeration(possible values: html, pdf, word)

includeRuleIm-ages Whether or not the documentation should contain ruleimages No (default:true)

boolean

includeDescrip- tionsInRuleIm-ages

Whether or not descriptions should be included in rule

images No (default:true) boolean

includeCon- tentsInRuleIm-ages

Whether or not the rule element contents should be

in-cluded in rule images No (default:true) boolean

includeCallAs- signmentDe- tailsInRuleIm-ages

Whether or not data values should be included in rule

images No (default:true) boolean

includeNotesIn-RuleImages Whether or not notes should be included in rule images No (default:false) boolean

includeStatistic-sInRuleImages Whether or not statistics information should be includedin rule images No (default:false) boolean

includeExcep- tionHandlingIn-RuleImages

Whether or not exception handling should be included in

rule images No (default:true) boolean

includeRuleEle-mentDetails Whether or not the documentation should contain de-tails of rule elements No (default:true)

boolean

(28)

<VRCheckout teamserverhost="localhost" teamserverport="1530" username="vruser" password="secret" repository="repo1"

project="MyProject" targetdirectory="${basedir}" />

If you are working with a Team Server 5.x.x do the following to checkout a rule project:

<VRCheckout url="http://localhost:8080/teamserver-5.x.x" username="vruser" password="secret" repository="repo1"

project="MyProject" targetdirectory="${basedir}" />

Table 3.4. Parameters for the VRCheckout Ant task

teamServer-Host The URL of the Team Server host. Only for 4.x.x TeamServers. Yes, if no url At-tribute given String teamServerPort The port of the Team Server host. Only for 4.x.x Team

Servers. No (default:1530) Integer

username The username to be used for login Yes String

password The password to be used for login Yes String

repository The name of the repository to checkout from Yes String

project The name of the project to checkout Yes String

targetDirectory The directory on the local file system where the project

should be placed Yes Directory

createSubdirec-tory If the targetDirectory, named like the project. If true the files are checked out into a subdirectory offalse, the files are checked out directly into targetDirectory.

No (default:

true) boolean

version The version of the project to checkout No. If not spec-ified, the latest version in the repository will be fetched.

String

File

url The URL of the Team Server Backend. Only for 5.x.x

Team Servers. Yes, if no team-ServerHost at-tribute given

URL

3.9. Checking in Files and Directories to a Visual Rules Team Server

The following example illustrates how to check in a file or a directory to a Visual Rules Team Server 5.x (separately available) with the aid of the task VRCheckin:

(29)

</fileset> </VRCheckin>

Table 3.5. Parameters for the VRCheckin task

url The URL of the Team Server Backend (e.g. http:// some.host.com:8080/teamserver). For Team Server 5.x.x.

Yes URL

repository The name of the repository to check in to Yes String destination The name of the folder, in which the files and directories

are to be checked in (will be created, if necessary) Yes String

fileset Files and directories to be checked in Yes Fileset

version The target version, in which the destination will be

placed. No. If not spec-ified, the latest

version in the repository will be fetched.

String

encoding The encoding of the files to be checked in to the Team

Server. No (standard:the Java

En-coding)

String

licenseFile Path of the license file No. If not

commitCom-ment Comment for the check in. No (standard:without com-ment)

String

3.10. Creating and Populating a Version in the Visual Rules Team Server

The following example illustrates how to create a new version in the Visual Rules Team Server (version 5.x) and populate it with a project with the aid of the task VRVersion:

(30)

Table 3.6. Parameters for the VRVersion task

Attribut Beschreibung Erforderlich Ant Typ

url The URL of the Team Server Backend (e.g. http://

some.host.com:8080/teamserver). Yes URL

repository The repository name Yes String

newVersion Name of the version to be newly created Yes String version Specification of a given version from which the projects

are to be copied No (standard:the latest ver-sion)

String

projects Specification of one or more projects, which are as-signed to the newly generated version. Multiple projects can be separated by |.

Yes String

licenseFile Path of the license file No. If not

3.11. Deploying Rule Artifacts to Visual Rules Execution Server with VRDeploy

In order to deploy a rule artifact to the Execution Server the rule artifact has to be created first. To create rule arti-facts usable by the Execution Server a jar archive has to be created which contains special files that can be pro-cessed by the Execution Server. When using the Ant tasks to create such a jar archive perform the following steps: • Set the generatemanifest attribute of the VRGenerate task to true. If it is desired to export and deploy rules to the

Execution Server then it is also necessary to set generatewsdl to true.

• The MANIFEST.MF created by the VRGenerate task has to be the first entry in the jar archive. To make sure it is the first entry specify it as manifest explicitly when calling the jar ant task.

• In the resulting jar file the models that were used to generate the source code have to reside in the folder META-INF/visualrules/models.

• Create a ruleartifact.vr which describes all the transitive dependencies of this project. In this file all the de-pendencies have to be specified with groupId, artifactId and version. This file has to contain both the Java de-pendencies (for example the Visual Rules Runtime) and dependent rule artifacts. Take a look at the Movie Tick-et Pricing Ant example available in the Visual Rules Modeler for an example ruleartifact.vr.

The following example illustrates how to deploy an artifact to a Visual Rules Execution Server. <VRDeploy username="admin" password="admin" fileToDeploy="artifact-1.0.jar" uploadURL="http://localhost:8080/executionserver/admin/upload"

(31)

Table 3.7. Parameters for the VRDeploy Ant task

username The user name to be used for the deployment Yes String password The password to be used for the deployment Yes String uploadURL The upload URL of the Visual Rules Execution Server to

where the artifact is being deployed Yes String

fileToDeploy The absolute or relative location of the artifact that is

be-ing deployed Yes File

groupId The group id of the artifact that is being deployed Yes String artifactId The artifact id of the artifact that is being deplDoyed Yes String version The version of the artifact that is being deployed Yes String

File

timeOut Timeout in milliseconds (ms) for the deployment

con-nection No. If not speci-fied a default of

5000ms (5 sec-onds) is used

Integer

Additionally, it is necessary to deploy all the dependent artifacts specified in the ruleartifact.vr to the Execution Server. See the table below for a list of dependencies required by the Visual Rules Runtime that are always nec-essary for executing a rule artifact. These jar archives can be found in the runtime folder of the Builder distribution.

They should always be present in the ruleartifact.vr and be deployed on the Execution Server.

Table 3.8. Visual Rules Runtime Dependencies

jar name groupId artifactId version

visualrules-runtime.jar de.visualrules visualrules-runtime 5.x.x

mail.jar javax.mail mail 1.4.2

activation.jar javax.activation activation 1.1

stax-api-1.0.jar stax stax-api 1.0

stax-1.2.0.jar stax stax 1.2.0

com-mons-collections-3.2.1.jar commons-collections commons-collections 3.2.1

commons-lang-2.5.jar commons-lang commons-lang 2.5

com-mons-logging-1.0.3.jar commons-logging commons-logging 1.0.3

(32)

Table 3.9. Visual Rules DatabaseIntegrator Runtime Dependencies

jar name groupId artifactId version

visualrules-dbcruntime.jar de.visualrules visualrules-dbcruntime 5.x.x

When working with projects that have a lot of dependencies between each other and to various Java libraries this process can become tedious, as you will have to create and maintain a ruleartifact.vr

for each project. Consider using Maven instead of Ant for your build system, which simplifies depen-dency management.

3.12. Deploying Visual Rules Archive (VRA) Files to Visual Rules Execution Server with VRArchiveDeploy

As an alternative to VRDeploy, VRArchiveDeploy deploys Visual Rules Archive (VRA) files, which can be build with Visual Rules Team Platform or downloaded from a running Visual Rules Execution Server. The VRA file consists of all dependencies and all necessary information about groupId, artifactId and version of the contained files, making this a good choice when distributing to different environments like test or production.

The following snippet illustrates the deployment of "archive.vra" to a running Execution Server: <VRArchiveDeploy username="admin" password="admin"

uploadURL="http://localhost:8080/executionserver/admin/upload" archiveFile="archive.vra"/>

Table 3.10. Parameters for the VRArchiveDeploy Ant task

username The user name to be used for the deployment Yes String password The password to be used for the deployment Yes String uploadURL The upload URL of the Visual Rules Execution Server to

where the artifact is being deployed Yes String

archiveFile The absolute or relative location of the Visual Rules

Archive (VRA) file that is being deployed Yes File

File

timeOut Timeout in milliseconds (ms) for the deployment

con-nection No. If not speci-fied a default of

5000ms (5 sec-onds) is used

Builder User Guide. Version 5.4. Visual Rules Suite - Builder. Bosch Software Innovations