Launch

The underlying technology for ModelPro execution is (apache ant), a Java-based build tool.  Within the eclipse/ant environment, a ModelPro-specific ant task is used to execute the provisioning engine. 

The eclipse Ant Editor is used to edit the ant script.  The eclipse Build Properties Editor is used to edit any associated property files.

Variations of the basic launch mechanism are used to support different provisioning applications, such as:

· Model-driven Launches

· Headless builds

· Help Content Engine

A. org.modeldriven.modelPro task

Description

Provision a set of artifacts from a model based on a Binding Specification.

This task supports the use of a nested <param> element which is used to pass values to an <xsl:param> declaration.

This task uses the following resource resolution mechanisms provided within the eclipse environment:

· platform.  An Eclipse platform resource reference is of the form project/folder/…file.  Folders and files may be linked to locations in the file system outside the project’s location using the eclipse linked resource mechanism.

· URI.  A model resource is specified via URI, which enables access to models located both within the platform workspace as well as plug-ins and external URLs.  For models located in the workspace, the form of the URI is “platform:/resource/project/folder/..file”.

Parameters

Figure 12modelPro Task Parameters

Parameter name	Description	Required
platformTemplateBinding	Eclipse platform  resource path to the Binding Specification.	Yes
platformVelocityDirectory	Eclipse platform  resource path to the global Template folder.  Subfolders of the global Template folder include  the override, default, and project Template sub-folders.	Yes
platformTargetWorkspace	Eclipse platform  resource path to the target workspace folder.  Subfolders of the target workspace folder include the provisioned project sub-folders.	Yes
modelResourceURI	The URI of the source model.	Yes

1. Parameters specified as nested elements

1. param

param is used to pass a parameter to the Binding Specification.

1. Parameters

Figure 13ModelPro task nested elements

Attribute	Description	Required
name	Name of the XSL parameter	Yes
expression	Text value to be placed into the param.	Yes
if	The param will only be passed if this property is set.	No
unless	The param will only be passed unless this property is set.	No

B. Console

During execution of the modePro task, information is logged to the Console view, including:

· Error conditions

o Includes errors reported from underlying tools, identifying location of error with respect to Binding Specification and/or Template.

· Progress reporting

o Includes information related to context resolution, indentifying names and values of context selections as well as location of definition within the Binding Specification.

1. Error conditions

The most frequent kinds of error encountered during development of ModelPro provisioning processes are various kinds of syntax errors.  The following sections indicate how these errors are communicated back to the developer.

1. Ant build errors

Errors related to build file syntax or execution errors are reported via standard eclipse mechanisms, including appropriate hyperlinks to points of failure.

2. Binding Specification XML Syntax

Errors related to Binding Specification XML syntax should be observed and reported by xml editors and validators prior to ModelPro launch.  When ModelPro encounters this kind of error the following form of parsing error will be logged:

The first line of this logging fragment is a hyperlink to the parser-reported point of failure.

3. XPATH

XPATH syntax or execution violations will result in logging the error in the following form:

The log entry contains information regarding the error violation, the XPATH expression which was specified in the Binding Specification, and the context for evaluation of the XPATH expression.  The first line of this logging fragment is a hyperlink to the line within the Binding Specification which caused the failure.

4. Template

Velocity Template  syntax or execution violations will result in logging the error in the following form:

The log entries contain information regarding the error violation.  The first line of this logging fragment is a hyperlink to the line within the Template which caused the failure.

5. File/Folder references

Invalid file/folder/resource references will result in logging the error in one of a few different forms, some of which are elaborated below:

Invalid Template directory references may occur as a result of  a @folder reference to a non-existent project kind.  The First line of this logging fragment is a hyperlink to the Binding Specification reference to a project folder which caused the failure.

Invalid parameter input during launch of ModelPro will log an error of the form:

Cross reference from a <provisioningContext>/<projectRef>  to a non-existent <project > will log an error of the form:

The First line of this logging fragment is a hyperlink to the invalid Binding Specification reference to a project.

Cross reference from a Template @artifactContext to a non-existent <artifactContext > will log an error of the form:

The First line of this logging fragment is a hyperlink to the Template containing the invalid @artifactContext reference.

2. Progress Reporting

Information related to context resolution processing of the Binding Specification  is logged , as elaborated in the following sections.  In most cases, hyperlinks are included to the relevant Binding Specification lines.

1. Prefix/namespace map

The implicit prefix/namespace mapping for models is logged in the following form:

These prefixes are available for use in all XPATH expressions referencing model elements.  The map only includes model prefix assignments, it does not include other implicit (e.g., fn:, xs:, mp:) prefixes or prefixes assigned explicitly in the Binding Specification document.

2. Provisioning Context

Information related to Provisioning Context is logged in the following form:

All these log entries have a hyperlink to the relevant line within the Binding Specification.

· Provisioning Context jbi=[2] .  Indicates the name of the Provisioning Context and the number of Provisioning Context instances selected.

· Provisioning Context instance… .Identifies the current Provisioning Context instance being processed.

· Provisioning Context param GlassFishESBDirectory=C:\\GlassFishESB\\ .  Provides the name and value of associated with any <xsl:param> statement within the Binding Specification.

· Provisioning Context variable clientParticipant[1]=(…) \\ .  Provides the name, count, and value of first item associated with any <xsl:variable> statements associated with the Provisioning Context.

3. Project Context

Information related to Project Context is logged in the following form:

  Explanation of some of the project context log items:

· project context XSLTImplementation=[1].  Indicates the @folder value (project kind) for a <projectRef> from the current Provisioning Context, and the number of Project Context instances selected.  Hyperlink is to <project> definition within the Binding Specification.

· project context instance… .Identifies the current Project Context instance being processed. Hyperlink is to <project> definition within the Binding Specification.

· project target folder @name=SolicitationServiceImplementation .  Identifies the name of the target project folder as evaluated from the <project  name=”…”/> expression, for the current Project Context instance. Hyperlink is to <project> definition within the Binding Specification.

4. Artifact Context

Information related to Artifact Context is logged in the following form:

 Explanation of some of the artifact context log items:

· Artifact Context instance=.  Identifies the current artifact instance being processed.  Hyperlink is to <artifactContext> definition within the Binding Specification.

· target artifact  .The location of the generated target artifact associated with the current artifact instance.  Hyperlink is to the target artifact.

C. Engine Driver

The engine driver is an XSLT which controls the ModelPro provisioning process.  That XSLT is reproduced here to help clarify the sequence of processing.  (Portions of the actual XSLT related to error detection and console log entry production have been removed for brevity).  The source document for the XSLT is the Binding Specification.  The XSLT is explained in the following sections.

1. Initialization

 Clarification of the constructs used for initialization:

· <xsl:stylesheet namespaces.. In addition to the standard x* namespaces:

o java:  a saxon provided extension for accessing java objects

o ModelController:  for accessing the underlying ModelPro XPATH implementation.

o Template:  for accessing the underlying ModelPro Template management implementation.

o ProvisioningContext:  for accessing the underlying ModelPro context management implementation.

· <xsl:param>  To retrieve the parameters passed via the launch ant script.

· <xsl:Template match="/">  Processing starts at the root of the incoming Binding Specification document.

· <xsl:variable name="Template.root"  Save the root of the Binding Specification document for later processing.

· <xsl:variable name="modelController"  Create an instance of the underlying ModelPro XPATH controller.  In addition to providing XPATH nodes for the given model ($platformModelResource), manages the location of the global Template directory ($platformVelocityDirectory) and the location of the target workspace ($platformTargetWorkspace).

· <xsl:variable name="root"  Save the root node of the model (corresponds to the Resource Set of the model).

· <xsl:for-each select="fn:in-scope-prefixes(*[1])">  Iterates through the user-defined namespaces and registers them with the ModelPro XPATH Controller, making them available for use in subsequent XPATH expressions. The registered namespaces may include declarations such as xmlns:Element="java:org.eclipse.uml2.uml.Element" from the Binding Specification.

2. Provisioning Context

  Clarification of the constructs used for provisioning context processing:

· <xsl:for-each select="//provisioningContexts/provisioningContext">  Iterates through each Provisioning Context in the Binding Specification.  For each:

o <xsl:variable name="provisioningContext.node" saves the Binding Specification <provisioningContext> node for later access

o <xsl:for-each select="ModelController:evaluate($modelController,string(@select),$root)">  Evaluates the XPATH expression defined in the <provisioningContext @select=?> property, within the context of the model root.  For each Provisioning Context instance in the result, perform the following:

§ <xsl:variable name="provisioningContextSelect" select="."/> Save the Provisioning Context instance for subsequent processing.

§ <xsl:variable name="provisioningContext" select="ModelController:createProvisioningContext($modelController,$provisioningContextSelect)"/>  Create a new Provisioning Context manager based on the current Provisioning Context instance and save it for subsequent processing.

§ <xsl:for-each select="$Template.root//xsl:param">  For each <xsl:param> defined in the Binding Specification, add a variable name/value to both the XPATH evaluation context and the Template evaluation context.

§ <xsl:for-each select="$provisioningContext.node/xsl:variable">  For each <xsl:variable> defined within the <provisioningContext>, evaluate the @select XPATH expression (given the current Provisioning Context instance) and store the result name/value to both the XPATH evaluation context and the Template evaluation context.

3. Project Context

   Clarification of the constructs used for project context processing:

· <xsl:for-each select="$provisioningContext.node/projectRef">  Iterates through each <projectRef> within the <provisioningContext> of the Binding Specification.  For each <projectRef>:

o <xsl:variable name="folder" select="string(@folder)"/> saves the value of the @folder reference for subsequent processing

o <xsl:for-each select="$Template.root//projects/project[string(@folder)=$folder]">  For each <project @folder=”?”> definition within the Binding Specification which matches the <projectRef folder=”?”>, perform the following:

§ <xsl:variable name="project.node" select="."/> Save the <project> node within the Binding Specification for subsequent processing.

§ <xsl:for-each select="ModelController:evaluate($modelController,string(@select),$provisioningContextSelect)">  Evaluate the <project select=”?”> XPATH expression within the context of the current Provisioning Context instance.  The result is a set of Project Context instances.  For each Project Context instance perform the following:

· <xsl:variable name="projectContext" select="."/>  Save the current Project Context instance for subsequent processing.

· <xsl:for-each select="$project.node/xsl:variable">  For each <xsl:variable> defined within the <project>, evaluate the @select XPATH expression (given the current Project Context instance) and store the result name/value to both the XPATH evaluation context and the Template evaluation context.

· <xsl:variable name="targetProjectFolder" select="ModelController:evaluate($modelController,string($project.node/@name),$projectContext)"/>  Evaluate the <project name=”?”> XPATH expression in the context of the current Project Context instance and save the result for subsequent processing.

4. Artifact Context

  Clarification of the constructs used for artifact context processing:

· <xsl:for-each select="ProvisioningContext:getAllTemplates($provisioningContext,$folder,$targetProjectFolder)">  The Provisioning Context manager is requested to provide a set of Template managers, one for each Template file in the current project kind folder.  For each of these Template manager instances:

o <xsl:variable name="Template" select="."/> saves the Template manager instance for subsequent processing

o <xsl:for-each select="$Template.root//artifactContexts/artifactContext[string(@name)=Template:getArtifactContext($Template)]">  The @artifactContext is retrieved from the current Template.  The named <artifactContext name=”?”> definitions within the Binding Specification are searched for a match with the Template @artifactContext reference.  For the matching <artifactContext>, perform the following:

§ <xsl:for-each select="ModelController:evaluate($modelController,$string(@select),$projectContext)">  Evaluate the <artifactContext select=”?”> XPATH expression with the current Project Context instance.  The result is a set of Artifact Context instances.  For each Artifact Context instance, perform the following:

· <xsl:sequence select="Template:updateTarget($Template,Template:createInstanceContextMap($Template,.))"/>  The Template evaluation context is created from accumulated information in the Provisioning Context manager (which includes <xsl:variable>,<xsl:param> maps) plus the properties associated with the current Artifact Context instance.  The @projectPath within the Template is evaluated using the VTL expression interpreter, the result determines the target artifact location.  The Template is then evaluated in its entirety and the result is serialized to the specified target artifact location.

D. Example

The following is a generic ant build script which can be used for any ModelPro provisioning step:

In this generic script, all parameterization is performed via build.properties, which may look like this:

The ant script may be incorporated into larger builds using standard techniques.  On eclipse, the build could be a step configured into the projectàpropertiesàbuilders  configuration, as illustrated below (where “fUML generation” is the name assigned to a ModelPro provisioning build script):

Figure 14Adding ModelPro Ant Script to Eclipse Project Build

Model-driven Launches

Launch configurations may be pre-packaged in Cartridge plug-ins. A Cartridge plug-in is a combination of Binding Specifications, Templates, and launch specifications driven by a single variant: the model used to drive the provisioning process. The user need only include the model within the workspace and invoke the pre-packaged provisioning process on that model. Invocation of a model-driven launch consists of:

· Right-click model

· Select an option under ModelPro toolsè

Following illustrates the launch process:

The example above illustrates provisioning from an EMF model. ModelPro is based on EMF models, so models built from 3^rd party providers may need to be transformed into EMF models prior to provisioning. To facilitate use of 3^rd party models, tool-specific ModelPro plug-in extensions are used to pre-process non-EMF models into suitable form for provisioning, and then immediately perform the provisioning process. The following illustrates the one-step provisioning process for a Magic Draw model:

Pre-provisioning Processes

Prior to execution of a Model-driven Launch, a ModelPro Cartridge may perform initialization tasks, such as:

· Initialization of server instances.

Extended Properties and Libraries

The ModelPro provisioning process produces a set of primary target artifacts. These primary artifacts are often used by 3^rd party tools to produce secondary artifacts. The build process for the secondary processing is generally controlled by ModelPro-provisioned ant scripts. Some of the components and/or tools required for secondary processing are not in the default eclipse build environment. For example, required components/tools may be located in:

· A cartridge plug-in.

· A server.

To facilitate access to such components, a ModelPro cartridge may utilize the following ModelPro extensions:

· Location properties. These properties are available to any ant script run in the eclipse jvm. They may be used to specify the current runtime location of:

o The cartridge plugin itself

o A server which is bound to a specific runtime location.

· LIB definitions. A named library which may be bound to the eclipse project and which includes the jars located in one of the following:

o The cartridge plugin itself

o A server which is bound to a specific runtime location.

Location properties

Location properties are associated with, and available to, any ant launch. The values may be observed in the launch configuration properties associated with an ant file. For provisioned projects, the following steps may be used to view the properties:

· Select a provisioned project from a Navigator pane.

· Select eclipse menu bar Project/Properties…

· From the result dialog box, select Builders

· Select a provisioned ant build launch

· Click Edit…

· From the resulting dialog box, select Properties tab

· Result will be a list of properties available to ant scripts, including the property name, its current value, and the (Cartridge) plugin contributing the property.

In the case of server location properties, a Cartridge plug-in may dynamically bind a server to a runtime location, if it is not already bound and if the runtime location can be determined by the Cartridge.

LIB definitions

Libraries are used primarily for compilation and execution of provisioned java artifacts. In most cases, libraries are provided by eclipse server adapters. In those cases where either cartridge-resident libraries are required or an extended set of server jars are required, cartridge plug-ins may utilize ModelPro library extensions to incorporate the required jars into the build process. For provisioned projects, the following steps may be used to view project libaries:

· Select a provisioned project from a Navigator pane.

· Select eclipse menu bar Project/Properties…

· From the result dialog box, select Java Build Path from the left pane

· On the right pane select Libraries

· In the following example, 2 modelPro libraries are associated with the project:

o “soaml”: a set of “soaml” cartridge jars

o “sunappsrv91”: a set of jars obtained from the currently allocated server runtime location. (This is included only for illustrative purposes, since the server adapter provides its own “Server Library [GlassFish v2 Java EE 5)”. Use of the server adapter-provided libraries is preferred approach for cartridge developers, if possible).

· The content and location of libraries may be viewed by selecting a single library and clicking “Edit…”

· Result is a display of resolved classpaths for each jar in the library:

Headless Builds

Model-driven builds may be executed from the command line, enabling support for continuous integration environments and automated testing. This form of provisioning is similar to headless eclipse execution, except that the environment allows for multi-threaded execution, including services requiring the UI thread. The environment enables secondary build processes to execute to completion even if they run on multiple threads or require services available only on the UI thread. The environment also provides comprehensive reporting of primary provisioning problems, spawned secondary build errors, and project problem markers attached to provisioned projects.

The command used for ModelPro headless builds is:

eclipsec -nosplash -application org.eclipse.ant.core.antRunner -data {workspace} -buildfile {ant build file}

where:

· {workspace} is the file-path to the workspace. All primary artifacts will be created within the specified {workspace}

· {ant build file} is the file path to the ant build script. This does not necessarily need to exist within {workspace}. The script is typically as shown in the example above. Example values for the parameters to the provisioning task:

o platformTargetWorkspace=/ Indicates that provisioned projects are physically located directly under the {workspace} folder.

o platformTemplateBinding=platform:/plugin/{pluginID} /transform/binding/BindingSpecification.xml specifies a binding specification within the cartridge plug-in having identifier {pluginID}

o platformVelocityDirectory=platform:/plugin/{pluginID} /transform/velocity specifies a velocity folder within the cartridge plug-in having identifier {pluginID}

o modelResourceURI={URI } Where {URI} does not necessarily need to exist within {workspace}

§ platform:/resource/${source.project}/${path.to.model} Use this form to reference a model which is located in the workspace (within a project named ${source.project}).

Help Content Engine

The basic provisioning specifications are the Binding Specification and Templates.  With variances in the launch and engine machinery, these provisioning specifications may be applied to a broader range of applications. An example of another application of provisioning is the dynamic production of help content pages for the eclipse help system. Provisioning-based help content may be found by navigating to the following location in the eclipse help content tree:

The differences between provisioning eclipse help content and provisioning arbitrary text artifacts lie in the implementations of the following mechanisms:

· launch

· engine driver

Help Content Launch

Help content launch is an extension of the launch ModelPro task which implements the eclipse IHelpContentProducer.

· It receives control via the eclipse help machinery when the requested URL contains a specific pattern.

· It returns a stream of information which is melded into the page content produced by the help system.

The help content launch behaves similar to the ModelPro task, with the following overrides:

· Parameters are obtained via the query parameters of the incoming URL, or are defaulted to values provided by the help content launch.

· The engine driver is set to the help content engine driver.

· An additional parameter named “templateName” is added to the set of parameters. The value is obtained via query parameters of the incoming URL, or is defaulted to a value provided by the help content launch.

Help Content Engine Driver

The engine driver for help content is similar to the default engine driver, with the following exceptions:

· A single template is used for expansion (instead of all templates within a project kind). The selected template is based on the “templateName” parameter.

· The result of template expansion is routed to the stream returned by the Help Content Launch (instead of a file system file).

[i]

---

[i] [i]This material is covered under copyright law. Copyright © 2009, Data Access Technologies, Inc. for ModelDriven.org as an unpublished work, all rights reserved worldwide.

This material is licensed for your use for free under the terms of the GNU public license version 2 which is located at this web address: http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt. This material is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software foundation; either version 2 of the License, or (at your option) any later version. This material is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt for more details. By downloading, copying or using this material you agree to this license unless this license has been superseded by a specific agreement with ModelDriven.org or Data Access Technologies, Inc. If the above license does not meet your needs you may contact http://www.modeldriven.org for further options.