Cartridges
Reusable provisioning specifications are distributed in the form of eclipse plug-ins, commonly referred to as “cartridges”. A cartridge may be used in one of the following ways:
· Direct application of cartridge provisioning to a selected UML model. In this scenario, the provisioning process is executed directly from the cartridge and no provisioning specifications are materialized in the workspace. The result is typically a set of eclipse projects structured for a target technology. The selection of cartridge to be applied to the model is based on model content.
· Addition of a cartridge nature to an existing project. This option adds a cartridge-specific nature and launch configuration to an existing project. This option is useful under one or more of the following situations:
o The source model is not UML.
o parameterization of a provisioning launch is required
o the provisioning process is part of a larger build process
o the provisioning process requires tailoring of pre- or post-processing
o the provisioning process is to be run as part of a headless eclipse build
o the provisioning process is to be run on a model which has a different default cartridge specified
Direct application of a cartridge
A cartridge provisioning process may be directly applied to a model by right-clicking a model resource in the navigation view and selecting the ModelPro toolsèuml to provisioned projects, as illustrated below:
The result will be a set of eclipse projects provisioned into the workspace. The provisioned project will typically be built as they are provisioned. An example result is illustrated below:
Adding a cartridge nature
A cartridge can be applied to any eclipse project, and enables a common provisioning specification to be applied to project-specific models. Applying a cartridge does not alter any existing project natures, such as java, pde, jee, etc. so the provisioning capabilities are in addition to any innate capabilities provided by other eclipse tools. After applying a cartridge, the procedures for build parameterization and management use standard eclipse UI actions. For clarity, the sequence of those standard actions is elaborated in the following section.
Adding a cartridge to a project:
|
·
Will result in a ModelPro launch script being
added to the project. ·
Will not
result in the Binding Specifications or Templates being added to the project,
they are used directly from their resident plug-in and are not intended for
modification. The cartridge provider
should normally include instructions on any offered parameterization of the
provisioning process. ·
Will result in the addition of a project
builder, which may be tailored by the project developer. ·
Will require the project developer provide
the instance source models for the provisioning process. |
To add a cartridge to a project:
|
·
From a navigator pane, right click on a
project ·
Select “ModelPro Tools”è ·
Select an appropriate “Add cartridge name” option |
Figure 36 Adding a cartridge to a project
This action will result in:
|
·
Creation of a ModelPro ant launch script in the root folder of the
project. This launch script may be modified
as required to incorporate any pre- or post- provisioning process steps. ·
Creation of an additional builder for the
project. Properties of the builder may
need to be tailored according to the configuration requirements of the
existing project. To adjust builder
properties, select the eclilpse menu option ProjectèProperties,
as shown below: |
Figure 37 Eclipse selection sequence for project properties
The result of this selection action will be the eclilpse project properties dialog. From the dialog box:
|
·
Select “builders” on the left pane. ·
Select the “name provisioning” builder corresponding to the cartridge in the
middle pane. ·
Push the “Edit…” button on right. |
Figure 38 Cartridge provisioning builder edit selection
The result of the above action sequence is the Edit Configuration dialog. From here:
|
·
Select the Properties tab ·
Select the name of the property to be edited
(e.g., “platformModelResource”) ·
Push the Edit Property… button |
Figure 39 Cartridge Property Edit Selection Sequence
The result of the previous action sequence is an “Edit User Property” dialog which enables modification of the value for the selected property. Shown below is the edit box for the most likely property requiring change, the location of the “platformModelResource”:
Figure 40 Editing Cartridge properties
Additional requirements for the project developer are to provide the source model for the provisioning process, at the location specified in the “platformModelResource” property.
Making a cartridge
The process of making a cartridge includes the following steps:
|
·
Develop the Binding Specification and
Templates in a normal eclipse project. ·
If the provisioning specification is a good
candidate for reuse, then proceed to following steps. ·
Convert the project to a PDE project. ·
Add extensions to the plugin.xml to bind to
the base ModelPro plug-ins. ·
Add the plug-in to a site, making it
available via the standard eclipse software update mechanism. |
Converting a ModelPro Project to a Cartridge Plug-in
Use the standard pde tool for project conversion:
|
·
Right click on a selected project ·
Select “PDE ToolsèConvert
Projects to Plug-in Projects ·
Finish the resulting dialog |
Figure 41 Invoking PDE tool for project to plugin conversion
Cartridge Implementation Declarations
A ModelPro cartridge plug-in may declare implementations for the following concepts
· Pop-up menu for applying the cartridge nature to a project
· A new project wizard for creating a cartridge-oriented project
· Extra classpath entries to enable use of cartridge resident java classes from ModelPro provisioning.
· Ant tasks implemented by cartridge-resident java classes.
· Location properties for ant script references to cartridge plug-in and/or server implementations.
· Classpath container initializers and pages to support java source code references to plug-in or server-resident jars.
All of these concepts may be declared in the cartridge’s plugin.xml file, an example of which follows:
The following sections provide additional information about the enumerated concepts.
Parameterized natures
Parameterized nature declarations are used in the following scenarios:
· Applying a cartridge nature to a project. Parameters of the declaration specify source locations for files and folders to be copied into a project.
· Creating a new project. The action includes applying a cartridge nature to a project.
· Performing model-driven provisioning. In this case, parameters of the declaration are used to
o Locate the binding specification, templates, and launch to be applied to a selected model.
o Optionally specify a pre-provisioning action to be executed
o Specify the cartridge name used in a UML model to associate the UML model with this cartridge plug-in provisioning process.
A parameterized nature declaration defines a unique (eclipse) nature. Each cartridge is an independent, unique nature which can be added to a user workspace project. Implementation of the nature class is provided by a ModelPro plug-in.
The following fragment represents a parameterized nature declaration:
|
<extension id="org.modeldriven.component.plugin.modelpro.nature.soaml"
name="ModelPro
Cartridge SOA-ML JEE Web Service" point="org.eclipse.core.resources.natures"> <runtime>
<run class="org.modeldriven.component.plugin.modelPro.nature.CartridgeProjectNature">
<parameter name="cartridge" value="JEE Web Service"/>
<parameter name="platformTemplateBinding" value="platform:/plugin/org.modeldriven.component.plugin.modelPro.cartridge.soaml/transform/binding/jeeBindingSpecification.xml"/>
<parameter name="platformVelocityDirectory" value="platform:/plugin/org.modeldriven.component.plugin.modelPro.cartridge.soaml/transform/velocity"/>
<parameter name="platformAnt" value="platform:/plugin/org.modeldriven.component.plugin.modelPro.cartridge.soaml/modelPro.build.xml"/>
<parameter name="platformAntProperties" value="platform:/plugin/org.modeldriven.component.plugin.modelPro.cartridge.soaml/build.properties"/>
<parameter name="platformModelResourceSourceFolder" value="platform:/plugin/org.modeldriven.component.plugin.modelPro.cartridge.soaml/model"/>
<parameter name="platformModelResource" value="platform:/resource/${project_name}/model/Calculator.uml"/>
<parameter name="preProvisioningRunnableClass" value="org.modeldriven.modelPro.cartridge.soauml.PreProvisioningRunnable"/>
</run> </runtime> </extension> |
The nature
extension declaration must specify:
·
an @id value of the
form “org.modeldriven.component.plugin.modelpro.nature.<name>”. <name> may
be referenced by a pop-up
menu declaration.
·
a runtime/run/@class
value as shown above. This is the
ModelPro implementation for cartridge project natures.
The parameters
are:
·
cartridge. If this declaration is to be used for
performing model-driven provisioning,
then the cartridge value must be the logical name of the cartridge, as
referenced in the UML model. More
specifically, if the selected model contains a UML Node stereotyped with
<Provisioning Profile::Provision> that has a “runtime” tag value matching
the cartridge value, then this cartridge plug-in will perform the provisioning
for that model.
·
platformTemplateBinding,
platformVelocityDirectory. These
parameters are URI locations for required provisioning specifications. If the parameter is not defined, then
ModelPro will provide a default value.
Provisioning specified by this cartridge will reference these resources
directly.
·
platformAnt,
platformAntProperties. These
parameters are URI locations for required provisioning specifications. If the parameter is not defined, then
ModelPro will provide a default value.
When this nature declaration is used for applying a cartridge nature to a project,
then resources at these locations will be copied to the target project. When this nature declaration is used for performing model-driven provisioning,
then these resources will be referenced directly.
·
platformModelResourceSourceFolder. This (optional) parameter is URI
location for folder containing example source models. If the parameter is not defined, then
ModelPro will provide a default value.
When this nature declaration is used for applying a cartridge nature to a project,
then resources at these locations will be copied to the target project. When this nature declaration is used for performing model-driven provisioning,
then this parameter is ignored.
·
platformModelResource This parameter is the default URI
location for the source model to be used for provisioning. If the parameter is not defined, then
ModelPro will provide a default value.
When this nature declaration is used for applying a cartridge nature to a project,
then this parameter, as well as the parameters: platformTargetWorkspace, platformVelocityDirectory, and
platformTemplateBinding are used
to initialize the launch configuration ant properties. These properties may be edited by the user. When this nature declaration is used for performing model-driven provisioning,
then this parameter is ignored.
·
preProvisioningRunnableClass This (optional) parameter may be used
to specify a java class provided by the cartridge. The class will be instantiated and run before
provisioning is executed.
Additional <parameter> may be set as required depending upon the actual layout of the plug-in project and desired defaults for parameters. These parameters are ultimately initialization values for the cartridge build properties in an eclipse project.
Pop-up menu for applying cartridge nature to a project
This optional concept enables user application of the cartridge nature to a project. The declaration defines submenu items off the “ModelPro tools” item for a project pop-up menu. The submenu item is enabled only if it is not already an applied cartridge (nature).
The following fragment example is a declaration that the user may apply the cartridge nature to a project:
|
<!—pop-up
menu for applying the nature à <extension point="org.eclipse.ui.popupMenus"> <objectContribution id="org.modeldriven.component.plugin.modelpro.nature.menu.soaml" objectClass="org.eclipse.core.resources.IProject" >
<action id="org.modeldriven.component.plugin.modelpro.nature.project.soaml" label="&Add
cartridge SOA-ML" style="push"
menubarPath="org.modeldriven.component.plugin.modelPro.nature.project.Menu/group1"
helpContextId="org.modeldriven.component.plugin.modelPro.nature.project.run_action_context"
enablesFor="1" > <enablement> <not> <objectState name="projectNature" value="org.modeldriven.component.plugin.modelpro.nature.soaml"/> </not> </enablement>
<class class="org.modeldriven.component.plugin.modelPro.nature.CartridgeActionDelegate"> <parameter name="cartridge" value="soaml"/>
</class>
</action> </objectContribution> </extension> |
This declaration
must specify:
·
objectContribution/action/enablement/not/objectState
with:
o
@name=”projectNature”
o
@value=="org.modeldriven.component.plugin.modelpro.nature.<name>",
which is identical to the @id attribute in the nature
declaration.
·
objectContribution/action/class/@class with value as shown above. The <class/> element must contain a <parameter/>
with :
o
@name=”cartridge”
o
@value=”<name>”. <name> is same as that specified in the nature
declaration
New project wizard
This optional concept is used to enable the user to create a cartridge-specific project.
The following fragment example is a declaration that the user may create a project with the cartridge nature:
|
<extension point="org.eclipse.ui.newWizards"> <wizard category="org.modeldriven.modelPro.wizards.category"
class="org.modeldriven.component.plugin.modelPro.nature.WizardProject"
hasPages="true" icon="./icons/modelPro.gif" id="org.modeldriven.modelPro.wizards.wizard.project.soaml"
name="New ModelPro SOA-ML Cartridge
Project" cartridge="JEE Web
Service" project="true">
<description> New <<JEE Web
Service>> SOA-ML Cartridge Project with Example SOA-ML Model</description> </wizard>
</extension> |
This declaration
must specify:
·
/wizard element with
following attributes:
o
@class with value set
to the ModelPro class indicated above.
o
@cartridge with value
set to same value declared for “cartridge” parameter in the nature declaration
Extra classpath entries
This optional concept is used to enable access to cartridge-provided java classes from Velocity Templates and XPATH expressions in the Binding Specification.
The following fragment example is a declaration that cartridge java classes are accessible from ModelPro provisioning specifications:
|
<extension point="org.eclipse.ant.core.extraClasspathEntries"> <extraClasspathEntry eclipseRuntime="true" library="lib/javaee.jar"/> </extension> |
Ant tasks
This optional concept is used to contribute ant tasks to all ant-based launches.
The following fragment example is a declaration that cartridge-based java classes are available to all ant executions (in same jvm as eclipse):
|
<!-- jax ws ant tasks referenced by
provisioned ant builds --> <extension point="org.eclipse.ant.core.antTasks"> <antTask class="com.sun.tools.xjc.XJCTask" library="lib/webservices-tools.jar"
name="xjc"/> <antTask class="com.sun.tools.xjc.XJCTask" library="lib/webservices-tools.jar"
name="wsgen"/> <antTask class="com.sun.tools.ws.ant.WsImport" library="lib/webservices-tools.jar"
name="wsimport"/> </extension> |
Location properties
This optional concept is used to contribute properties providing location information to all ant-based launches.
The following fragment example is a declaration that properties will be available to all ant executions (in same jvm as eclipse):
|
<!-- ant properties containing location of
plugin and server --> <extension point="org.eclipse.ant.core.antProperties"> <antProperty class="org.modeldriven.component.plugin.modelPro.nature.AntPropertyValueProvider"
name="org.modeldriven.component.plugin.modelPro.cartridge.soaml.location"/> <antProperty class="org.modeldriven.modelPro.cartridge.soauml.ServerAntPropertyValueProvider"
name="com.sun.enterprise.jst.server.runtime.sunappsrv91.location"/> </extension> |
This declaration
must specify:
·
/antProperty elements
with following attributes:
o
@class with value set
to the ModelPro class "org.modeldriven.component.plugin.modelPro.nature.AntPropertyValueProvider"
or a subclass of that class.
o
@name with value set
to one of following:
§
<plug-in
id>.location Where <plug-in
id> is the plug-in ID of a plug-in whose location is to be provided as an
ant property.
§
<server type
id>.location Where <server type
id> is the ID associated with a server type.
The location of the runtime for a server will be provided as an ant
property. If necessary, an attempt will
be made to allocate a server and/or its associated runtime instance.
Classpath containers
This optional concept is used to contribute libraries, extending project build classpath to include jars in either cartridge plug-ins or servers bound to run-time instances. There are 2 parts to each declaration:
· classPathContainerInitializer Provides the location of jars within a library.
· classpathContainerPage Provides display of jar information.
The following fragment example is a declaration that libraries may be made available to project builds:
|
<!-- java containers for plugin and server
--> <extension id="org.modeldriven.modelPro.containerInitializer2"
name="ModelPro
Glassfish v2 Library" point="org.eclipse.jdt.core.classpathContainerInitializer"> <classpathContainerInitializer class="org.modeldriven.component.plugin.modelPro.nature.ModelProClasspathContainerInitializer"
id="com.sun.enterprise.jst.server.runtime.sunappsrv91"/> </extension> <extension name="ModelPro Glassfish v2 library" point="org.eclipse.jdt.ui.classpathContainerPage"> <classpathContainerPage class="org.modeldriven.component.plugin.modelPro.nature.ModelProClasspathContainerPage"
id="com.sun.enterprise.jst.server.runtime.sunappsrv91" name="ModelPro Glassfish v2 libraries"/> </extension> <extension point="org.eclipse.jdt.core.classpathContainerInitializer"> <classpathContainerInitializer
class="org.modeldriven.component.plugin.modelPro.nature.ModelProClasspathContainerInitializer"
id="org.modeldriven.component.plugin.modelPro.cartridge.soaml"> </classpathContainerInitializer> </extension> <extension point="org.eclipse.jdt.ui.classpathContainerPage"> <classpathContainerPage
class="org.modeldriven.component.plugin.modelPro.nature.ModelProClasspathContainerPage"
id="org.modeldriven.component.plugin.modelPro.cartridge.soaml" name="ModelPro SOA-ML libraries"/> </extension> |
This declaration
must specify:
·
/classpathContainerPage
elements and /classpathContainerPage elements, each with following attributes:
o
@class with value set
to the ModelPro class indicated.
o
@id with value set to
one of following:
§
<plug-in
id> Where <plug-in id> is the plug-in
ID of a plug-in whose jar locations is to be provided as a library.
§
<server type
id> Where <server type id> is
the ID associated with a server type.
The jar locations of the runtime for a server will be provided as a
library. If necessary, an attempt will
be made to allocate a server and/or its associated runtime instance.
Dependencies and Build Configuration
In addition to the plugin.xml extension definitions, the following needs to be specified:
|
·
Dependency on ModelPro nature plugin ·
Inclusion of provisioning specifications in
plugin build |
Dependency on ModelPro nature plugin is specified on the “Dependencies” tab of the plugin editor via “Add…” button:
