AIMDOCS

Appendix A - Deprecated API
Module PortfolioModelQuery
Module PortfolioModelRules
Module PortfolioModelQuery
Deprecated Methods
Method Comments
com.optimyth.apm.modelquery.FunctionCallException.getNestedException() replaced by Throwable.getCause()
Module PortfolioModelRules
Deprecated Interfaces
Interface Comments
com.optimyth.apm.builder.rules.j2ee.jdbc.JdbcDependenciesCallback Use JdbcCallback instead (TODO: modify JdbcBuilderRule to

remove this interface)
Deprecated Classes
Class Comments
com.optimyth.apm.builder.rules.j2ee.jdbc.JdbcBuilderRule Use JdbcRule instead
Deprecated Methods
Method Comments
com.optimyth.apm.builder.rules.model.ComponentsHelper.addMethod(String, Component) Use addBean(), is the same...
Appendix B - Rules migration

The new API rules were a bit changed: this changes are essential and require a migration.
New Types class
Component.ComponentType and Software.SoftwareType objects and do not exist anymore.

Use Types (com.optimyth.apm.model.Types) having Types.SoftwareType.XYZ and Types.ComponentType.XYZ. These
are now strings, not objects anymore.
The ComponentsHelper is ready to use strings instead of the old SoftwareType / ComponentType objects.
If you want to adapt your rules, just import Types class and replace Software.SoftwareType / Component.ComponentType with
Types.SoftwareType / Types.ComponentType.
To use a custom type, just pass an arbitrary string to ComponentsHelper.
It is possible that these types were used in comparisons: you need to change == by equals():
Example
// replace:
if (candidateWin.getComponentType () == Types.ComponentType.WINDOW) ...
// by:
if (Types.ComponentType.WINDOW.equals (candidateWin.getComponentType ())) ...
Relations
There is only one type of relationship: ApmRelation. Change all the uses of **Relation to *ApmRelation (this class is in the same
package).
Entities
The meta-model entities (Software, Component, Person, Unit ..) are now interfaces, so the main difference with the old version is that
they cannot be instantiated directly.
Many search methods have been now removed from these interfaces, and some have been maintained, moved to
com.optimyth.apm.util.queries package.
Example
Set<Software> apps = callingWindow.getSoftware().getParentSoftwares();
// should be replaced with:
Iterable<Software> apps = Softwares.getParentSoftwares(callingWindow.getSoftware());
calledFNG.getChildComponents()
Softwares.getChildComponents(calledFNG)
Collections (IMPORTANT)
Most of the old collections are now returned are Iterable.
For example, the iteration PortfolioModel.getEntities():
for (Iterator i = ctx.getPortfolioModel().getEntities(); i.hasNext() \;) {

ApmEntity entity = (ApmEntity) i.next();
...
}
// *can* be rewritten to (but not necessary):
for (ApmEntity entity: ctx.getPortfolioModel().getEntities()) {
...
}
This is the most frequent use, and - as you can see - this is just java5 makeup.
Anyway this is an important change, you don't have size() method anymore. For those cases where is absolutely unavoidable, you can
use count* methods:
ApmEntity.countLinks();
ApmEntity.countOutgoingLinks();
ApmEntity.countIncomingLinks();
IQueryEngine.countLinkedEntities();
IQueryEngine.countDirectLinks();
PropertyDefinitions
Almost all PropertyDefinitions remain centralized in com.optimyth.apm.model.PropertyDefinitions class.
In the previous version, there were multiple classes as com.optimyth.apm.model.portfolio.PropertyDefinitions which

have been now removed. Some technologies can extend SqlPropertyDefinitions the original properties.
Creating entities
As before, all rule callbacks (RuleCallback class) have a getter getHelper() which provides you with a ComponentHelper, the main
class for entities creation in any AIM model.
ComponentsHelper has very few changes:
Now it implements an interface, IComponentsHelper, which is the return type of RuleCallbackBase.getHelper().

There is no more a method getKeyGenerator(). Now com.optimyth.apm.model.KeyGenerator provides static methods.
A new method component() has been created, to allow arbitrary components creation
A new method relation() has been created, to allow the creation of arbitrary relations
Good practices - Model semantics

Some general rules on components creation:
Whenever is possible, use ComponentsHelper to create standard components (better than low-level entity
creation)
Use component() and relation() which are better than low-level entity creation.
Whenever is possible, reuse the existing specific methods (eg program() ore use() methods) instead of creating
new ones with component() and relation()
This last note is very important: try reusing the existing methods will give the final model a semantic much easier to
understand: using general concepts as program fits with a javascript snippet or a cobol application, and is reused in
AIM product's rules. In this example, language property will be enough to distinguish those programs. Another
example would be c#, c++ and java classes: they are all class components.
A normal tendency would be calling web page "webPage". Instead, this is modeled as "page". The concept of "page"
can be re-used by any other document-oriented language... in the same way, "window" is general enough to model
oracle forms, visual basic forms or abap screens. This makes querying with AQL much easier, because it's more
intuitive filtering datasets than aggregating.
Of course all these considerations on model's semantic are just a suggestion given by Optimyth's experience, but they
can be adapted to the customer's needs.
Low level entity creation
As Component is now an interface, you cannot use new Component(...) anymore... so, thi would be the low-level translation of "new
Component", using IApmModelFactory:
Example
public Component addDataArea(Component container, String dataAreaName) {

String dbType = container.getSoftware().getName();
String key = getKeyGenerator().getTableKey(dataAreaName, container, dbType);
Component dataArea = getBuilderContext().getPortfolioModel().getComponent(key);
if (dataArea == null) {
dataArea = new Component(key, dataAreaName);
dataArea.setDescription("Data area "+dataAreaName);
dataArea.setComponentType(DB_OBJECT);\\
getBuilderContext().getPortfolioModel().addComponent(dataArea);\\
ApmRelation contains = contains(container, dataArea);

contains.setDescription(container.getName()+" contains data area "+dataAreaName);
} else {
purgeRelations(dataArea);
}
return dataArea;
}
// would be replaced with:
public Component addDataArea(Component container, String dataAreaName) {

String dbType = container.getSoftware().getName();
String key = KeyGenerator.getTableKey(dataAreaName, container, dbType);
Component dataArea = getBuilderContext().getPortfolioModel().getComponent(key);

if (dataArea == null) {
// Here is the component cretion... adding it to portfolioModel is now *not* necessary

dataArea = getModelFactory().createEntity(getBuilderContext().getPortfolioModel(), key,
dataAreaName, Component.class);
dataArea.setDescription("Data area "+dataAreaName);

dataArea.setComponentType(ComponentType.DATABASE_OBJECT);
ApmRelation contains = contains(container, dataArea);

contains.setDescription(container.getName()+" contains data area "+dataAreaName);
} else {
purgeRelations(dataArea);
}
return dataArea;
}
IMPORTANT
As a general rule, you SHOULD NOT use low-level entity creation (modelFactory.createEntity()) which is documented
here, try to use ComponentsHelper methods whenever is possible.
Properties
PropertyDefinition(s) are created in the same way (via constructor), with the only change that PID (first argument) has been
removed (the property name is now the property's key).
That is:
Creating PropertyDefinition...
PropertyDefinition ENTRY_PROGRAM = new PropertyDefinition("cics.1", "entryProgram", "entry

program for CICS transaction", String.class, true);
// must be changed to:

PropertyDefinition ENTRY_PROGRAM = new PropertyDefinition("entryProgram", "entry program for CICS
transaction", String.class, true);
As Property is now an interface, you must use a factory (IApmModelFactory) to create it:
Creating Property...
Property<String> entryProgram = new Property<String>(ENTRY_PROGRAM, trans.program);
// should be translated to:

Property<String> entryProgram = ApmFactory.createModelFactory().createProperty(ENTRY_PROGRAM,
trans.program);
IMPORTANT
As property values??, you must use only primitive types (strings, int, etc...) or arrays of primitive types.
Tags
Tags class has disappeared, and a Set<String> is used.
Adding a tag to a component c (this remains unaltered)

c.addTag(tagString)
Good practice
Wherever you can, use ComponentsHelper methods:
Set<String> tag (ApmEntity entity, String tag)
Set<String> tag (ApmEntity entity, String ... tags)
For more complex operations, there is a utility com.optimyth.apm.util.TagUtils containing methods for dealing with these
Set<String> of tags.
Artifacts
The class Artifacts has been removed, artifacts are now stored in List<String>. There is also an utility
com.optimyth.apm.util.ArtifactsUtil, which offers some methods to deal with filepaths, normalization etc...
Adding an artifact to a component c:

List<String> addArtifact(PortfolioEntity entity, BuilderContext ctx)
List<String> addArtifact(PortfolioEntity entity, File codeFile, int basedirPos, File
basedir)
List<String> addArtifact(PortfolioEntity entity, int basedirPos, String pattern)
Good practice
Wherever you can, use these ComponentsHelper() methods
Removing Artifacts instantiations
if (datafile != null) transaction.setArtifacts(new Artifacts(ctx.getModel().getBaseDirs(),

datafile));
String art = ArtifactsUtil.encode(ctx.getModel().getBaseDirs(), datafile);

if (datafile != null) transaction.setArtifacts(ArtifactsUtil.list(art));
Replacing getLocations() method:
Artifacts artifactsTarget = compTarget.getArtifacts();

row[PATH_TARGET] = artifactsTarget == null || artifactsTarget.isEmpty() ? N_A :
artifactsTarget.getLocations()[0];
List<String> artifactsTarget = compTarget.getArtifacts();

row[PATH_TARGET] = artifactsTarget == null || artifactsTarget.isEmpty() ? N_A :
artifactsTarget.get(0);
Home
Navigation
checking AIM Basic Concepts

checKing AIM overview
What does it do?
How does it do this?
What are the benefits?
What are its potential usages?
Introduction
Application Discovery
What is the dependency Model
Analysis rules
Local rules
Global rules
Types of rules according to their purpose
Extraction rules
Validation rules
Tagging rules
Export rules
Model tree
Analysis Workflow
The meta model
Defining the model
Rules Development
Useful manuals
Glossary of terms
checKing AIM overview
What does it do?
checKing AIM provides a corporate view of an enterprise’s software assets allowing this information to be accessed at different levels.
From a single program or file up to the IT infrastructure resource usage level. checKing AIM helps customers to understand the
complexity of their software systems and their relationships, simplify its management and to make the best tactical and strategic
decisions.
Through its advanced technology, checKing AIM builds the foundation for modernisation initiatives imposed by external forces such as:
Merges, acquisitions and enterprise consolidations;

Update of the most important applications to comply with new laws and currencies etc;
Systems integration;
Servers and data consolidation.
How does it do this?
checKing AIM allows the organisation to:
Automatically build a map of the software systems in hierarchical form, from an organisational level down to the lowest level software
component;
Understand in real time the correlation between the software components;
Execute impact analysis for regular maintenance activities (planning, change requests and implementation of new functionalities)
based on factors such as costs, resources and technical complexity etc;
Evaluate the effects associated with the implementation of new specifications;
Offer several alternatives to the systems change requests;
Analyse cost mitigation;
Establish cost/benefit analysis that allows project or application comparisons based on either predesigned Quality Models or the
customer’s own models;
Help simplify and consolidate the IT environment whilst identifying the value areas within the application portfolio.
What are the benefits?
checKing AIM helps enterprises from different perspectives:
Risk Management: The huge variety of technologies, architectures, languages and systems that make up the enterprise application
portfolio are recognised and documented thus reducing the risks associated with changes and updates;
Simplicity: checKing AIM helps reduce the complexity of the application portfolio and of the applications themselves;
Assets Classification: checKing AIM enables the classification of software assets helping to align the applications with the business
process and the business units that depend on them;
Productivity: checKing AIM increases the productivity during the development and maintenance stages;
Outsourcing Management: checKing AIM offers the ability to efficiently manage the knowledge transfer process. It can generate,
consolidate and provide the documentation of the complexity and the value of the applications thus reducing unexpected difficulties;
Change Management: checKing AIM offers impact analysis to determine which systems will be affected by changes and to
drastically reduce regression issues.
What are its potential usages?

To load APP technical data into checKing from software artifacts (e.g. source code). Software assets inventory form the core of
application data in checKing.
To check if software elements are compliant with architectural standards (e.g. detecting illegal dependencies).
To perform impact analysis (identify items that may be affected by a change in a specific set of items).
To detect potential design antipatterns (‘smells’) due to bad couplings.
To resolve the group of software items that belong to a certain category (classification by tagging).
To keep track of the code items that make up a certain logical entity.
Introduction
checKing AIM consists of a collection of plug-ins and JNLP. They are as follows:
APMMETRICS plug-in: This plug-in computes metrics on APPMAP models extracted using rules that will navigate the model and
derive measures for different metrics. These metrics can be viewed with specific panels in checKing. See the APMMETRICS plug-in
manual for further details;
APPMAP Browser: A JNPL application launched from a panel that creates a global view modelling relationship among different
concepts within a corporation. See the APPMAP Browser manual.
checKing AIM creates a global view modelling relationship among different concepts within a corporation: logical structures (programs,
applications, routines and web services etc.) and physical structure (organisational units, departments and staff etc.). All these elements
are graphically represented, so that the user can easily use this model for the purpose of impact analysis. Which web service is related
to which business process? What will cause a change in a specified element in the company's structure?
Moreover, checKing AIM assigns different tags to these modelled concepts. Thus, the user can differentiate between owners and other
categories. These tags can be propagated, by the user automatically, from certain artifacts by specified rules.
The model is displayed in tree and graphical form, see figure 1. The Model tree shows a hierarchy of relationship among different
concepts within a corporation while the Node's Graph and Properties shows a graphical representation of the node/entity selected from
the Model tree and the entities connected to that node.
Figure 1: Application Map Portfolio
The icons used to represent the entities in the Node's Graph and Properties are customisable.
Application Discovery
The Application Discovery and Inventory Management technologies of checKing AIM enables automatic validation of predefined or
proprietary architecture through its customisable rules extraction engine. It also offers software system information capture and
correlation such as:
Modules, components, application logic and dependencies;

Tagging;
Links with organisational units;
Batch processes (both complete and incremental).
What is the dependency Model
checKing AIM creates a global view which models relationships among different concepts within a corporation. These concepts are
physical structures such as programs, applications, routines and web services and logical structures such as organisational units,
departments and staff. All these structures are represented graphically, thus making it easy to generate a model for the purpose of
impact analysis.
A model could be generated to answer the following questions:
What web services are related to a given business process?

What is the effect caused by a change to a certain element in the company's structure?
checKing AIM assigns different tags to each modelled concepts, allowing the user to differentiate between owners and other categories.
These tags can be propagated to different elements within the model automatically, based on specified rules.
APPMAP is a checKing plug-in that provides:
A browser (Swing technology, launchable via script or JNLP);

Query Server: responds to AQL-formulated queries
A set of extraction, validation and tagging rules;
An API (Java): meta-model, persistence, query and scripting.
APPMAP provides a dependency analysis script that can be scheduled or launched from the checKing administration interface. The
script uses a set of configuration files (based on the Spring framework) that specifies the extraction, tagging and validation rules (and
their configuration) applicable, the filters on source files, and the source directories to analyse.
The outputs from the analysis script are a dependency model and a report. The report shows the artifacts and dependencies, and the
classification tags for each matching artifact. Details of architectural validations are also shown. Output is generated in the directory
$CHECKING_HOME/plugindata/appmap/PROJECT.
Analysis rules
The analysis rules are a set of rules that are applied in each analysis and they are configurable by Spring files. There are two types of
rules, defined by their scope:
Local rules
Local rules are invoked on every source code artifact processed (that matches the rule filter). The rule operates locally, deriving
model entities and relationships from parsed representation (AST) of source code.
The rule logic is normally implemented in the void visit(BuilderContext) method.
Global rules
Global rules operate once all the source code files are processed (by local rules), in order to resolve global dependencies that
require that the artifacts are resolved by local rules. For example, inheritance dependencies need to know the component for
supertypes.
The rule logic is normally implemented in the void postProcess(BuilderContext) method.
Types of rules according to their purpose
There are four kinds of rules according to their purpose: extraction rules, validation rules, tagging rules and export rules.
Extraction rules
These rules are defined in an XML file that is firstly referenced in the apm-modelbuilder.xml file. A suggested name for the XML file is
apm-rules-extraction.xml. The purpose of the extraction rules is to analyses the source code in order to identify and insert into the
model all components (artifacts) and relationships (dependencies).
Validation rules
These global rules analyse the full model in order to identify architectural violations and to generate an HTML report with all violations
found. These rules are defined in the file apm-rules-check.xml.
Tagging rules
Such rules bear responsibility for propagating the classification tags to elements. These rules are defined in the apm-rules-tagging.xml
file.
Export rules
Such rules export a CSV file with useful information extracted from the model. These rules are defined in the apm-rules-tagging.xml
file.
Model tree
The Model tree is a representation of the modelled structure. Figure 2 shows an example of this structure.
Figure 2: Model tree
Analysis Workflow
The dependency analyser operates according to the following workflow, see figure 3:
1. Configuration is loaded.
a. The initial model (if specified, for example in delta analysis) is loaded by persistence managers. If no initial model is
specified. An empty model is created.
2. Every rule is initialised (invoking its initialize(BuilderContext) method).
3. For each rule matching its filter, the visit(BuillderContext) method is invoked.
4. The postProcess(BuilderContext) on each rule is invoked.
5. The output reports (HTML, XML and TXT) are generated and the model built is persisted using the registered persistence manager,
see the section The Persistence Model.
Figure 3: Workflow analysis
The meta model
APPMAP uses a meta-model, see figure 4:
Three containers (ApmModel, OrganizationalModel and PortfolioModel);

Three organisational beans: Organization, Unit and Person;
Two software logical beans: Software and Component;
An item is represented by an ApmEntity, a relationship by an ApmRelation;
One ApmRelation bean for any (two-fold) relationship between two entities (left and right).
Containers, entities and relationships are ApmAtom, the top-most type in APPMAP model. ApmAtom may have arbitrary Property
beans. There are some special properties: Artifacts (models the files that make-up a portfolio entity), and Tags (multi-valued sets of
‘attributes’ that classify any entity in the model). Every entity in the model has a unique key (unique name, DN)
Figure 4: Appmap meta model
One ApmRelation bean for any (two-fold) relationship between two entities (left and right). Containers, entities and relationship are
ApmAtom, the top-most type in APPMAP model.
Defining the model
A software architecture is created by adapting the meta-model:
How to map any item in your organisation or software architecture to a meta-model bean, and their dependencies as meta-model
relationships
What namespace to use for defining the unique key
What properties shall be added to the entities
How to map software artifacts to entities
How to add tags for classifying entities
Once the model is defined, you can proceed with other tasks:
Definition of extraction (standard + custom) rules

Scripts and batch capture
Rules Development
Rules are developed for application portfolio extraction from code and other artifacts. The Application Portfolio provides an extensible
framework for automated extraction of entities (software-related and organisational) and their relationships, for compilation of an
application map, to be used by different checKing plug-ins.
The framework is based on a set of BuilderRules, that may perform different tasks:
To create portfolio entities (software-related or organisational) and resolve their mutual relationships;
To check if the software artifacts are compliant with architectural standards;
To detect potential architectural antipatterns (‘smells’);
To resolve the group of code artifacts that are logically related to software entities in the application map, for later analysis.
A BuilderRule is a unit of logic that may perform any of the above tasks.
Useful manuals
Manual Description
XXX DESC
Glossary of terms
Term Definition Term Definition
Artifacts models the files that make-up a portfolio entity The persistence The model that persists the data.
model
Tags multi-valued sets of ‘attributes’ that classify any BuilderRules The builder rules are used to extract data from the
entity in the model code and other artefacts.
DN A unique key that every entity is given. Meta Model The meta model models the organisational structure
and its entities.
checking AIM User Manual
APPMAP plugin
Purpose
How it works
Installation
Scripts
Panels
Purpose
This plug-in creates a global view modelling the relationships among different entities within a corporation: logical structures (programs,
applications, routines and web services, etc.) and physical structure (organisational units, departments and staff, etc.). All those
elements are represented graphically, so the user can request this model to make impact analysis. Which web service is related to which
business process? What effects will cause a change in a certain element in the company's structure?
How it works
There is a general generic model which is used as framework to develop a custom model builder for each company. Each company has
different ways to provide the necessary information needed to build the global model. This includes: organizational model (XML files),
code (java classes, jar files, Cobol programs and SQL scripts, etc.). Specific "extracting rules" are designed for each client and a final
custom library is given along with the plug-in. The analyse script will build the model each time the administrator wants to reflect changes
in the organisation.
APM Query Language

At some points during the configuration process you will have the possibility to use AQL (APM Query Language)
expressions. Some examples are:
Using an AQL expression to filter an ApmModel.
Performing a query or impact analysis from the command line using AQL expressions to set sources and/or
targets.
You can learn more about AQL in the APPMAP Query Language (AQL) manual.
Installation
First of all, you need to deploy APPMAP following the standard instructions from checKing Plug-in's Installation Guide.
This plug-in is configured by default with the company's specific characteristics, as each company has a different organisational structure
or business requirements. It is supposed that the plug-in will be fully functional when deployed within client's distribution.
However there are a certain amount of configuration files that might be edited to reflect changes in the company (e.g. addition of new
folders and changes in databases etc).
Scripts
Once you have installed APPMAP and the configuration files are ready to use, you would typically want to perform an analysis of your
system.
The script APPMAP/script/analyze analyses the organisation and their applications, extracting entities and relationships between
them. The rules defined in configuration files decide which entities should be included and their structure. Finally, an APPMAP model
is built and saved. Check on its own page for details.
Or if you already have an APPMAP model built, you may want to update the checKing projects tree with information about all software
entities found by this plug-in.
The script APPMAP/script/syncSoftware synchronise software elements contained in the APPMAP model with checKing current
projects, creating and/or updating when necessary. Check on its own page for details.
The script APPMAP/script/exec launches an AppMap script: APPMAP scripts can execute a query, a model transformation, a
validation or a model update. This checKing script is a wrapper for executing them under the checKing system. Parameters are:
operation - The name of the script to execute.
model - A list of models launched previously is shown. Select one.
properties - Input properties to be passed to the script, in format String with PROP=VALUE pairs separated by '|' (pipe)
characters.
configFile - Path of configuration file with properties that will be searched for.
Note: If you want to select a model, please specify only relative path from CHECKING_DATA/plugindata/appmap. For
example: /Name_of_Project/Name_of_Model.
To launch the script diff from checKing interface, enter the second model as a property:
secondModel=/Name_of_Project/Name_of_secondModel.
Before executing AIM TASK - Analyze, you may generate automatically a configuration using the AIM TASK - Configuration
discovery, which could be used as a starting point for a proper configuration for model building.
Panels
This plug-in currently shows one panel with two links for each project being analysed. The first one launches theApplication map
Browser with the selected model, while the second opens a report with the statistics found during the model building process.
Please note that the browser link will open a JNLP application to be run on the client side, and that this might use a large amount of
memory. Check more information in the Application map Browser manual.
Additionally, from the summary link you can open a detailed HTML report with the architectural problems found during the construction of
the application model and a brief summary with specific statistics of the company that is using this plug-in.
Furthermore, Panels APPMAP allows you to open a JNLP application running on the client side without loading any appmap model, by
clicking in visualization link.
APMMETRICS plugin
APMMETRICS Plug-in
Purpose
How it works
Scripts
APMMETRICS/script/analyze
APMMETRICS/script/purge
Panels
Artefacts count table
Artefact count comparison
Pie chart Unresolved / Unreferenced
Pie char for multivalued criteria
Artefacts by Container
Artefacts by Criterium
Time evolution of artefacts
Time evolution for metric
Time evolution of artefacts by criteria
Metric list
Architecture compliance evolution
Architecture compliance index
Architecture compliance table
Architecture violation distribution
Architecture violation evolution
Architecture violations table
Architecture violations, compared
Time evolution of artifacts
Dependencies
Change log
Appendix A - How to add a new metric based on dependencies model
Steps summary
Define the metric and the panels that will convey the information that the metric represents.
Create metric values table(s)
Implement a metric computation rule
Implement metric DAO (and optional querybuilder if needed when metric uses the "tuplets" scheme)
Create panels for rendering data for the new metrics
Deploy your customisations
Appendix B - How to define thresholds for global metrics
Purpose
This plug-in computes metrics on APPMAP models extracted using rules that will navigate the model and derive measures for different
metrics. These metrics can be viewed with specific panels in checKing.
How it works
The plug-in analyze script will execute a metrics computation engine that will perform the following work flow:
1. The engine configuration is loaded using PLUGIN_DIR/scripts/resources/metrics.xml (Spring) configuration;

2. The requested model is opened;
3. The metrics ruleset are applied against the selected model. The ruleset are composite rules that implement the MetricRule
interface.
The metric provided is Artefacts count, that counts the number of artefacts in an AppModel classified by tuples (set of three) of criteria in
a specific time.
Scripts
This plug-in has two scripts, defined in the plugin-scripts.xml configuration file:
APMMETRICS/script/analyze
This script analyses the specified AppModel, applies the rules defined, obtains the metric Artefact count and saves them within the
persistence manager. It has the following parameters:
Parameter Meaning Example
project The name of the checKing project associated to an AppModel with the same name. Must be a valid /ChecKing
checKing project.
model.name The name of the AppModel used to count artefacts. If it is not supplied then appmap.model is assumed appModel
environment The environment of the AppModel. env1
The script uses the model stored in the path /webapp/plugindata/appmap/<project>/<environment>/<model.name>
APMMETRICS/script/purge
Deletes all data contained in the AppMetrics tables in the checKing database. It does not require any parameters.
Panels
The APPMetrics can display eight different panels that provide a friendly and useful way to show metrics to the user. These are the
available panels:
Artefacts count table
This panel shows a table with counts of current artefacts for selected model, by specified criteria:
Criteria Description
Tags Grouped by tags
Type Grouped by Type
Subtype Grouped by Subtype
Language Grouped by Language
Container Grouped by container
Unresolved Grouped by unresolved
Unreferred Grouped by unreferred
If a criterion is not specified, it will not be taken into account for filter/grouping. If a criterion is specified as '*', it will be selected for
grouping. If a criterion is specified as a value, it will be selected for filtering on the selected value.
For example, to get the artefact counts for type 'program' grouped by classification tags, select TYPE = 'program', TAGS = '*'
To get the artefact counts grouped by classification tags and type, select TYPE = '', TAGS = ''
In this panel you can see the number of artefacts where the language is Java and grouped by their container. In this type of panel the
first column always shows the total number of artefacts and the second is the relative percent.
Artefact count comparison
This panel shows a spider graph that compares two different models by a defined criteria. This comparison is always made with the
counted metrics in the last execution of the analysing script. It can be used to compare two models of different environments. In this
panel you must specify the two models you want to compare and a comparison criteria (tags, type, subtype and etc.).
This example shows a comparison between two models and the criteria used to compare is type.
Pie chart Unresolved / Unreferenced
In this panel you can see a pie chart showing the relationship between unresolved/unreferenced artefacts with all artefacts of the
specified model. You have to select the model and the criteria (unresolved or unreferenced).
This panel shows the relation between artefacts unresolved and all artefacts for a given model.
Pie char for multivalued criteria
This panel shows a pie chart for a selected model where you can see the relationship between artefacts classified by a multivalued
criteria (tags, type and subtype etc. except unresolved and unreferenced). Each slice represents a set of artefacts grouped by the criteria
value.
In this panel you can see how the artefacts are grouped by a specific criteria (in this case the criteria is TYPE)
Artefacts by Container
This chart groups all artefacts by the container criteria and shows all sets as a pie chart.
Here are shown the artefacts grouped by their container
Artefacts by Criterium
This chart groups all artefacts by a previously defined criterium defined in the panel properties.The CRITERIUM property is included in a
list where you can select one grouping CRITERIUM.
Time evolution of artefacts
In this panel you can see how a model varies its artefacts count over time. To see this chart you have to specify the model you want, the
criteria count and the time range.
In this example the panel shows the evolution of the number of artefacts by language over two days.
Time evolution for metric
In this panel you can see how global metric (a metric that computes a single value for a specific model) varies over time. To see this
chart you have to specify the model you want, the metric and the time range.
In this example you can see the evolution of metric "Architecture Compliance" in the last week.
Time evolution of artefacts by criteria
In this panel you can see how a model varies its artefacts count over time. You can filter the results for a series of criteria that are loaded
dynamically.
In this example you can see the panel and the dynamic properties.
Metric list
In this panel you can see for a given model the last values for global metrics. Some global metrics can have a description that can be
accessed clicking on the icon close to metric name. Some global metrics can have a detailed report that can be shown by clicking on the
metric value.
For some metrics you can define a thresholds value so for metric values outside from those thresholds the value is shown with red color.
Architecture compliance evolution
This panel shows a graphic for architecture compliance evolution for a model pattern. For each model that matchs with the given model
pattern a line for this evolution is shown.
Architecture compliance index
This panel shows the architecture compliance index for selected model.
Architecture compliance table
This panel shows a table with architecture compliance index for all models that match with the given model pattern.
Architecture violation distribution
This panel shows a graph whit architecture violation distribution for selected model and grouped by the selected criterium.
Architecture violation evolution
This panel shows a graph for architecture violations temporal evolution for a selected model, grouped by a criteria and restricted by the
selected data range (if there is no data range, dashboard data range will be used instead).
Architecture violations table
This panel renders an architecture violations count table for the selected model and filtered by criteria.
Architecture violations, compared
This panel shows a pie chart to compare architecture violatios for two models grouped by selected criteria.
Time evolution of artifacts
This panel renders a line chart showing time evolution of artefacts, for specified model, grouping by criterium, in the selected date range
(if date range is not explicit, the dashboard date range will be used).
Dependencies
This plug-in needs AppMap plug-in in order to work properly because the artefacts counted are extracted from the models generated
with the AppMap plug-in.
Change log
Version 1.1: First release. Creation of the plug-in to count artefacts and display panels.
Appendix A - How to add a new metric based on dependencies model
This section describes the steps needed to add a new metric derived from dependencies model, using a sample metric for illustration
purposes.
Steps summary
1. Define the metric that you want added to the system, and the panels that will show the measures computed on such metric.
2. Create one or more details table(s) in which to store the historical measures derived for the metric.
3. Implement a metric computation rule, that will compute current metric values for current dependencies model/analysis reports.
Register it under the metrics-rules.xml descriptor.
4. Implement a DAO class for storing/deleting the data values and for fetching data matching defined criteria, and register it under
metrics-persistence.xml descriptor.
5. Create panels to show the metric values filtered/grouped by user parameters, and add them to the plugin-panels.xml
descriptor.
It is recommended to separate custom bean definitions from the plug-in's included configuration. You may use a
metric-custom.xml descriptor for rule, metric definition and DAO configurations (for metric computation engine),
and plugin-custom.xml descriptor for panels, views and datasets (for panel rendering).
This separation facilitates upgrading the plug-in without overwriting your custom metric configurations.
We use the following use-case: "Add support for a model violations count metric" in what follows.
Define the metric and the panels that will convey the information that the metric represents.
The metric will have the following goals:
To count the number of violations of architecture-validation rules emitted during analysis, categorised by violation type and severity.
The metric computation will evaluate a global index that will show the compliance level with the architectural rules defined for the
analysis.
Panels will show the number of violations, grouped by severity and/or violation type:
Current values for a specified model (for a system, application and environment etc.), and the global compliance factor.
Time-evolution of the metric for a specified model, grouped by severity and/or violation type.
Comparison of the metric for two models, again grouped by severity and/or violation type.
Similar panels for the derived compliance level metric.
Compliance factor will be computed as the density of violations weighted by its severity and divided by the number of artefacts in the
model. It will be computed by the formula:
---------------------- number of violations of rule R * violation weight R

compliance factor (CF) = 100 - -------------------------------------------------------------
---------------------- ( SUM(weights for all rules) * number of components in model)
Create metric values table(s)
Remember that the master table APMMETRICS_EXECS contains a row for each metrics analysis on the given MODEL at EXEC_DATE. Its
primary key ID_EXEC will be used by the metric table to refer to the execution of the metric computation rules for the given MODEL and
EXEC_DATE.
We want to store for the analysis execution ID_EXEC both the index (compliance factor, a number) and the violation counts, by rule, type
and severity. Such information can be conveyed in the following tables and auxiliary views:
Table definitions for the metric
CREATE TABLE APMMETRICS_VIOL_FACTOR (

ID_EXEC INTEGER PRIMARY KEY,
CONFIDENCE NUMBER(5,2) NOT NULL
);
CREATE TABLE APMMETRIC_VIOL_DETAIL (

ID_EXEC INTEGER NOT NULL,
RULE VARCHAR(20) NOT NULL,
CATEGORY VARCHAR(20) NOT NULL,
SEVERITY INTEGER NOT NULL,
NUM_VIOL INTEGER NOT NULL
)
-- Views for easier computation of current values

CREATE VIEW APMMETRIC_VIOL_FACTOR_LAST AS
SELECT
E.MODEL AS MODEL, E.EXEC_DATE AS EXEC_DATE,
V.CONFIDENCE AS CONFIDENCE
FROM
APMMETRICS_EXECS E, APMMETRICS_VIOL_FACTOR V,
(
SELECT MODEL, MAX(EXEC_DATE) AS LAST_EXEC
FROM APMMETRICS_EXECS
GROUP BY MODEL
) LE
WHERE
E.ID_EXEC = V.ID_EXEC AND
E.MODEL = LE.MODEL AND E.EXEC_DATE = LE.LAST_EXEC;
CREATE VIEW APMMETRIC_VIOL_DETAIL_LAST AS

SELECT
E.MODEL AS MODEL, E.EXEC_DATE AS EXEC_DATE,
D.CATEGORY AS CATEGORY, D.SEVERITY AS SEVERITY,
SUM(D.NUM_VIOL) AS NUM_VIOL
FROM
APMMETRICS_EXECS E, APMMETRIC_VIOL_DETAIL D,
(
SELECT MODEL, MAX(EXEC_DATE) AS LAST_EXEC
FROM APMMETRICS_EXECS
GROUP BY MODEL
) LE
WHERE
E.ID_EXEC = D.ID_EXEC AND
E.MODEL = LE.MODEL AND E.EXEC_DATE = LE.LAST_EXEC
GROUP BY E.MODEL, E.EXEC_DATE, D.SEVERITY, D.CATEGORY;
Database normalisation issues aside, the example defines two tables for storing the confidence factor and the violations count
decomposed into rule, rule category and rule severity, and two views to simplify getting current (last) values for both confidence factors
and violations count grouped by category and severity.
Implement a metric computation rule
Metric computation rules should implement the following interface:
public interface MetricRule {

/** Compute metric values on input model, using the passed MetricBuildContext */
void fetch(MetricBuildContext ctx);
}
For the example metric the computation logic will use the following strategy:
1. From the input parameters (project, model.name and environment), it parses the analysis report (XML file) that conveys the
violations detected by the dependencies validation rules;
2.
2. Counts each violation in a bin made-up by a tuplet (RULE, CATEGORY, SEVERITY);
3. Counts the components number from the model (or from the report itself);
4. Evaluates the index using the computation formulae;
5. Adds the two measure types (a single MetricValue for the index and one MetricValue for each bin counting the violations count).
The rule implementation is straightforward:
Rule ViolationsMetricRule.java
/**
* checKing - Scorecard for software development processes
* [C] Optimyth Software Technologies, 2009
* Created by: lrodriguez Date: Jan 26, 2010 10:18:54 PM
*/
package com.zurich.apm.aimmetrics.rules;
import com.optimyth.checking.plugin.aimmetrics.rule.MetricRule;
import com.optimyth.checking.plugin.aimmetrics.engine.MetricBuildContext;
import com.optimyth.checking.plugin.aimmetrics.model.Tuple;
import com.optimyth.checking.plugin.aimmetrics.model.MetricValue;
import com.optimyth.checking.plugin.aimmetrics.model.MetricDefinition;
import com.optimyth.checking.plugin.aimmetrics.MetricConstants;
import java.util.Map;
import java.util.HashMap;
import java.util.List;
import java.util.Collection;
import java.io.File;
import org.dom4j.Document;
import org.dom4j.DocumentException;
import org.dom4j.Element;
import org.dom4j.io.SAXReader;
/**
* ViolationsMetricRule - Computes values for two metrics: violationCount (grouped by RULE,
CATEGORY, PRIORITY)
* and complianceIndex (a 0-100 index measuring the global compliance).
*
* @author <a href="mailto:lrodriguez@optimyth.org">lrodriguez</a>
* @version 26-01-2010
*/
public class ViolationsMetricRule implements MetricRule {
private MetricDefinition complianceIndexMetric;

private MetricDefinition violationCountMetric;
/** The definition of the complianceIndex metric */

public void setComplianceIndexMetric(MetricDefinition complianceIndexMetric) {
this.complianceIndexMetric = complianceIndexMetric;
}
/** The definition of the violationCount metric */

public void setViolationCountMetric(MetricDefinition violationCountMetric) {
this.violationCountMetric = violationCountMetric;
}
/**
* Parses the build-generated XML report to fetch the violations detected in last model
analysis.
* Produce multi-valued measures for violationCountMetric (one value for each tuple
{RULE,CATEGORY,PRIORITY})
* and a single-valued measure for complianceIndexMetric.
*
* @param ctx
*/
public void fetch(MetricBuildContext ctx) {
Map<Tuple, MetricValue> metrics = new HashMap<Tuple, MetricValue>(100);
try {
Document doc = parseReport(ctx);
int numComponents = ctx.getModel().getPortfolioModel().getComponents().size();
@SuppressWarnings({"unchecked"})
List<Element> violations = (List<Element>)doc.getRootElement().element("archvViolations"
).elements("violation");
countViolations(violations, metrics);
double complianceIndex = computeComplianceIndex(metrics.values(), numComponents);
for(MetricValue violCount : metrics.values()) ctx.addMetricValue(violCount);

MetricValue complianceIndexValue = new MetricValue(complianceIndexMetric, null,
complianceIndex);
ctx.addMetricValue(complianceIndexValue);
} catch(DocumentException de) {
throw new IllegalArgumentException("Report file for model "+ctx.getModelPath()+" does not
exist");
}
// Count violations for each {RULE,CATEGORY,PRIORITY} tuple

private void countViolations(List<Element> violations, Map<Tuple, MetricValue> metrics) {
// <violation rule='${viol.rule.name}' category priority file='${viol.file}'
line='${viol.line}' reason='${viol.reason}'>
for(Element violEl : violations) {
Map<String,Object> map = new HashMap<String,Object>();
map.put("RULE", violEl.attributeValue("rule"));
map.put("CATEGORY", violEl.attributeValue("category"));
map.put("SEVERITY", violEl.attributeValue("priority"));
Tuple tuple = new Tuple(map);
MetricValue mv = metrics.get(tuple);
if(mv==null) {
mv = new MetricValue(violationCountMetric, tuple, 1);
metrics.put(tuple, mv);
} else {
mv.incValue();
}
}
}
// Compute compliance index taking into account

private double computeComplianceIndex(Collection<MetricValue> metrics, int numComponents) {
double sum = 0.0D;
double weights = 0.0D;
for(MetricValue metric : metrics) {
Tuple t = metric.getTuple();
int priority = Integer.parseInt((String)t.getProperty("SEVERITY"));
weights += priority;
sum += metric.getValue()*priority;
}
double complianceIndex = weights>0? 100.0D - ( sum / (weights*numComponents)) : 100.0D;
return complianceIndex>100.0D? 100.0D : complianceIndex;
}
private Document parseReport(MetricBuildContext ctx) throws DocumentException {

String modelPath = ctx.getModelPath();
File report = new File(MetricConstants.APPMAP_PLUGINDATA_DIR, modelPath+".xml");
if(!report.exists()) {
throw new IllegalArgumentException("Report file for model "+modelPath+" does not exist");
}
SAXReader parser = new SAXReader(false);

return parser.read(report);
}
}
Implement metric DAO (and optional querybuilder if needed when metric uses the "tuplets" scheme)
This is straightforward if your implementation derives from

com.optimyth.checking.plugin.aimmetrics.dao.AbstractMetricDao, so you should simple perform INSERTs/DELETEs
on the table that will receive the metric data.
Sample ViolationsMetricDao
/**
* ViolationsMetricDao - Inserts/deletes violatonsCount measures on APMMETRIC_VIOL_DETAIL
*
* @author <a href="mailto:lrodriguez@optimyth.org">lrodriguez</a>
* @version 27-01-2010
*/
public class ViolationsMetricDao extends AbstractMetricDao {
private static final String SQL_INSERT = "INSERT INTO APMMETRIC_VIOL_DETAIL
(ID_EXEC,RULE,CATEGORY,SEVERITY,NUM_VIOL) VALUES (?,?,?,?,?)";
private static final String SQL_DELETE_WITH_FILTER = "DELETE FROM APMMETRIC_VIOL_DETAIL WHERE
ID_EXEC IN (SELECT ID_EXEC FROM APMMETRICS_EXECS WHERE ";
private static final String SQL_DELETE_WITH_ID = "DELETE FROM APMMETRIC_VIOL_DETAIL WHERE
ID_EXEC = ?";
public void insert(MetricValue value, int execId, JdbcTemplate tpl) throws DaoException {
if( accept(value.getDefinition()) ) {
Tuple tuple = value.getTuple();
tpl.update(SQL_INSERT, new Object[] {execId, tuple.getProperty("RULE"), tuple.getProperty(
"CATEGORY"), Integer.parseInt((String)tuple.getProperty("SEVERITY")), (int)value.getValue()});
}
}
public void delete(String filter, Object[] parameters, JdbcTemplate tpl) throws DaoException {
tpl.update(SQL_DELETE_WITH_FILTER + filter + ")", parameters);
}
public void delete(int execId, JdbcTemplate tpl) {

tpl.update(SQL_DELETE_WITH_ID, new Object[]{execId});
}
}
To register the new metrics (here we call them violationsCount and complianceIndex):
Configure the metric definitions, DAOs and computation rule in the metrics-custom.xml descriptor:
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi=
"http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=
"http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">

<bean name="APMMETRICS/metric/complianceIndex" class=

"com.optimyth.checking.plugin.aimmetrics.model.MetricDefinition">
<property name="name" value="Compliance index with dependency validation rules"/>
<property name="description" value="Measures the degree of compliance with validation rules
based on dependencies between artifacts"/>
</bean>
<bean name="APMMETRICS/metric/violationsCount" class=

<property name="name" value="Number of violations in validation rules, per
rule/category/severity"/>
<property name="description" value="Count violations in validation rules in models, according
to different criteria (rule, category, severity)"/>
</bean>

<bean name="APMMETRICS/dao/complianceIndex" class=

"com.zurich.apm.aimmetrics.dao.ComplianceIndexMetricDao">
<property name="definition" ref="APMMETRICS/metric/complianceIndex"/>
</bean>
<bean name="APMMETRICS/dao/violationsCount" class=

"com.zurich.apm.aimmetrics.dao.ViolationsMetricDao">
<property name="definition" ref="APMMETRICS/metric/violationsCount"/>
<property name="query" ref="APMMETRICS/dao/violationsCount/querybuilder"/>
</bean>
<bean name="APMMETRICS/dao/violationsCount/querybuilder" class=

"com.zurich.apm.aimmetrics.dao.ViolationsQueryBuilder">
<property name="metricDefinition" ref="APMMETRICS/metric/violationsCount"/>
<property name="table" value="APMMETRIC_VIOL_DETAIL_LAST"/>
<property name="availableParameters" value="MODEL,RULE,CATEGORY,SEVERITY"/>
</bean>

<bean name="APMMETRICS/rule/violations" class=

"com.zurich.apm.aimmetrics.rules.ViolationsMetricRule">
<property name="violationCountMetric" ref="APMMETRICS/metric/violationsCount"/>
<property name="complianceIndexMetric" ref="APMMETRICS/metric/complianceIndex"/>
</bean>
</beans>
Reference the computation rule in the metrics-rules.xml descriptor:
<bean name="APMMETRICS/rule/registry" class=

"com.optimyth.checking.plugin.aimmetrics.rule.MetricRuleRegistry">
<property name="ruleset"><list>
<ref bean="APMMETRICS/rule/artefacts"/>
<ref bean="APMMETRICS/rule/violations"/>
</list></property>
</bean>
Add your DAO beans to master DAO in metrics-persistence.xml descriptor:

<bean name="APMMETRICS/dao/composite" class=
"com.optimyth.checking.plugin.aimmetrics.dao.CompositeMetricDao">
<property name="daos"><list>
<ref bean="APMMETRICS/dao/artefacts"/>

<ref bean="APMMETRICS/dao/violationsCount"/>
<ref bean="APMMETRICS/dao/complianceIndex"/>
</list></property>
</bean>
Create panels for rendering data for the new metrics
You should declare your panels (and supporting datasets/views) according to the [checKing plug-ins development guide] provided with
checKing.
As an example, we show how to configure a tabular panel (for the violationsCount metric) and a meter panel (for the
complianceIndex metric):

<bean name="APMMETRICS/panel/violationsCount_table" class=

"es.als.checking.framework.panel.CacheablePanelMVC">
<property name="config">
<bean parent="APMMETRICS/panel/baseConfig">
<property name="title" value="PANEL TITLE"/>
<property name="description"><value><![CDATA[PANEL DESCRIPTION]]></value></property>
<property name="editablePropertyNames" value="${MODEL.combo},${CRITERIA.violationCount}"
/>
<property name="type" value="summary"/>
<property name="avoidRefresh" value="true"/>
</bean>
</property>
<property name="controller">
<bean class="es.als.checking.framework.panel.controller.JdbcDatasetPanelController">
<property name="dataset" value="APMMETRICS/dataset/violationsCount_table"/>
</bean>
</property>
<property name="view" ref="panel/view/table"/>
</bean>
<bean name="APMMETRICS/panel/complianceIndex_meter" class=

"es.als.checking.framework.panel.IndirectCacheablePanelMVC">
<property name="config">
<bean parent="APMMETRICS/panel/baseConfig">
<property name="editablePropertyNames" value="${MODEL.combo}" />
<property name="title" value="PANEL TITLE"/>
<property name="description"><value><![CDATA[PANEL DESCRIPTION]]></value></property>
<property name="type" value="meter"/>
<property name="defaultLayout"><bean parent="APMMETRICS/panel/baseLayout">
<property name="width" value="160"/><property name="height" value="160"/></bean>
</property>
</bean>
</property>
<property name="controller">
<bean class="es.als.checking.framework.panel.controller.JdbcDatasetPanelController">
<property name="dataset" value="APMMETRICS/dataset/complianceIndex_meter"/>
<property name="validation">
<bean class="es.als.checking.framework.panel.NonEmptyParametersPanelValidation">
<property name="parameters" value="MODEL"/>
</bean>
</property>
</bean>
</property>
<property name="view">
<bean class="es.als.checking.framework.panel.view.MeterPanelView" singleton="false">
<property name="title" value="METER IMAGE TITLE"/>
<property name="low" value="0.0"/>
<property name="high" value="100.0"/>
<property name="column" value="INDEX"/><property name="row" value="COMPLIANCE"/>
<property name="thresholds" value="70.0, 90.0"/>
<property name="labels" value="@i18n:panel:meter.labels@"/>
</bean>
</property>
<property name="htmlView" ref="panel/view/image"/>
</bean>

<bean name="APMMETRICS/dataset/violationsCount_table" class=

"es.als.checking.framework.panel.dataset.JdbcTabularDataset" singleton="false">
<constructor-arg ref="dataSource"/>
<property name="queryBean" ref="APMMETRICS/query/violationsCount"/>
<property name="firstColumnAsRowTitle" value="false"/>
<property name="sorting" value=",numeric,numeric,alphanumeric,alphanumeric,alphanumeric"/>
<property name="filtering" value=",none,none,text,text,text"/>
</bean>
<bean name="APMMETRICS/dataset/complianceIndex_meter" class=

"es.als.checking.framework.panel.dataset.JdbcCategoryDataset" singleton="false">
<constructor-arg ref="dataSource"/>
<property name="dynamicQuery"><value><![CDATA[
SELECT 'INDEX' AS CATEGORY, COMPLIANCE
FROM APMMETRIC_VIOL_FACTOR_LAST
WHERE MODEL = #MODEL#
]]></value></property>
</bean>
Deploy your customisations
Place your implementation classes in a JAR under PLUGIN_DIR/lib, plugin-custom.xml in PLUGIN_DIR and
metrics-custom.xml in PLUGIN_DIR/scripts/resources, and restart the plug-in (using the administrative plug-in tab).
Now you may launch the analysis script (that will execute your custom metric rules), and place your custom panels in checKing
dashboards.
Appendix B - How to define thresholds for global metrics
In order to define the thresholds you have to define a metafile whith the format:
beanName.*.*:operator value
the characters .*.*: that follows the bean name are mandatory.
Where beanName must be the bean definition name in metrics_models.xml
Example of thresholds metafile:
APMMETRICS/metric/stabilityIndex.*.*:>95.00
APMMETRICS/metric/fragilityIndex.*.*:>95.00
APMMETRICS/metric/stabilityIndex.*.*:>97.00
This example establish the normal values for each metric. For example, if the fragility index for a model takes a value equals 90.0, it's
out of the normal value (>95.00) so it should be rendered in a different formal, usually in red color:
The file should be used as a normal metafile for quality models.
And in your metric_models.xml you have to be defined the above metrics, as you can see in the following example
<bean name="APMMETRICS/metric/stabilityIndex" class=
<property name="name" value="Stability Index for model / components" />
<property name="description" value="% of incoming relations from other software components"
/>
</bean>
<bean name="APMMETRICS/metric/fragilityIndex" class=

<property name="name" value="Fragility Index for model / components" />
<property name="description" value="% of outgoing relations to other software components"
/>
</bean>
<bean name="APMMETRICS/metric/ArchCompliance" class=

<property name="name" value="Architecture Compliance" />
<property name="description" value="% of components without any architecture violations" />
</bean>
</beans>
At last in metric_rules.xml you can define the rules that computes the metrics:
<bean name="APMMETRICS/rule/registry" class=

"com.optimyth.checking.plugin.aimmetrics.rule.MetricRuleRegistry">
<property name="ruleset"><list>
<ref bean="APMMETRICS/rule/Stability"/>
<ref bean="APMMETRICS/rule/Fragility"/>
<ref bean="APMMETRICS/rule/ArchCompliance" />
</list></property>
</bean>
<bean name="APMMETRICS/rule/ArchCompliance" class=

"com.optimyth.checking.plugin.aimmetrics.rule.globalModel.ArchComplianceRule">
<property name="metricDefinition" ref="APMMETRICS/metric/ArchCompliance"/>
<property name="violationPriority" value="3" />
<property name="ruleFileResolver" ref="APMMETRICS/RuleFileResolver/StandarFileResolver" />
<property name="archCompute"><bean class=
"com.optimyth.checking.plugin.aimmetrics.rule.globalModel.StandardArchComplianceCompute" />
</property>
</bean>
<bean name="APMMETRICS/rule/Stability" class=

"com.optimyth.checking.plugin.aimmetrics.rule.globalModel.StabilityMetricRule">
<property name="metricDefinition" ref="APMMETRICS/metric/stabilityIndex" />
<property name="stabilityComputer">
<bean class=
"com.optimyth.checking.plugin.aimmetrics.rule.globalModel.StandardStabilityMetricCompute" />
</property>
<property name="reportFileName" value="stabilityReport.xml" />
<property name="detailReport"><bean class=
"com.optimyth.checking.plugin.aimmetrics.rule.globalModel.DefaultMetricDetailReport" />
</property>
</bean>
<bean name="APMMETRICS/rule/Fragility" class=

"com.optimyth.checking.plugin.aimmetrics.rule.globalModel.FragilityMetricRule">
<property name="metricDefinition" ref="APMMETRICS/metric/fragilityIndex" />
<property name="stabilityComputer">
<bean class=
"com.optimyth.checking.plugin.aimmetrics.rule.globalModel.StandardStabilityMetricCompute" />
</property>
<property name="reportFileName" value="fragilityReport.xml" />
<property name="detailReport"><bean class=
"com.optimyth.checking.plugin.aimmetrics.rule.globalModel.DefaultMetricDetailReport" />
</property>
</bean>
</beans>
AIM TASK - Analyze

Overview
Configuration
Task properties
Results
Incremental analysis
Incremental (no special treatment)
Delta
SCM
Overview
The APPMAP Analyse Task launches the ANT script that invokes the whole process of model-building. If the script is properly configured
it also inserts the results of the global analysis in the DBMS (if the database scheme has been created).
Typically the script's name is run-apm-modelbuilder-configurations.xml and it is located in ${plugin.dir}/scripts. In

the resources subfolders you will find the configuration files deployed with APPMAP, as well as the SQL scripts needed for creating the
DB schemas.
Configuration
Configuration is done in the apm-modelbuilder.xml file and all its dependencies use the configuration files mentioned before as
templates for your own configuration and upload them as project's configuration files (check the process in the APPMAP plugin manual).
However, a few features are customisable via the task properties.
Task properties
Name Description
project The checKing project name. This will be used to set the output model location and to retrieve the associated
configuration files. It is the only mandatory parameter because the task must retrieve the configuration from the
checKing project.
src.dir Use this property to set several paths containing the files to analyse, using semi-colons to separate the list of files. If you
leave this field blank, the source paths will be taken from the configuration files. If neither this field is filled nor the
configuration files have source paths set, the task will use checKing project's path property instead.
model.name With this property you can set the serialised model file name.
environment Represents the project environment. This environment will be set as AppMap models. Its name will be used to retrieve
the correct configuration files and it will be appended to the end of the file model.name task property.
initial Set this property if you want to perform an incremental build using an initial serialised model. Entities and dependencies
discovered will be added to and/or updated in that model. The initial model's full name will be resolved following the
same process as for the final model built.
noBackup Whether enable or disable backup of the model (default value is false). NB: Be aware this won't generate model
backup, so user is responsible of any impact on the processes on final users
delta Whether incremental update is strictly incremental, or it should be looking for components removed (default value is
false).
scm Behaves like delta analysis (and alternative to it), but requires a changelog file: scm.changelog.xml. See
encoding Default encoding to use when loading files for analysis. You can define a specific encoding for a particular
QakingFileParserAdapter (apm-modelbuilder.xml). The priority is the following:
1. If defined, the encoding specified in the apm-modelbuilder.xml will apply, ignoring this task configuration.
2. If defined, the encoding of this task will apply.
3. If none is defined, UTF-8 will be the default value.
configuration You can choose one of the configurations previously generated through the auto-discovery feature (see ChecKing's
Manual for further information).
Configurations generated through the auto-discovery feature (configuration parameter) prevails over manual
configurations (configuration files associated to project).
The initial serialised model's have to be on the same project.path of the final model. This fact will prevent from errors
building incremental model.
Be aware that if noBackup is enabled it won't generate any model backup, so user is responsible of any impact on the
processes on final users. Also be aware if user try to work in local mode.
To customize properties of the APPMAP plugin JKQA will copy the file qaking.configuration.properties in the
directory ${CHECKING_DATA}/config/plugins/APPMAP and modify the properties that it deems appropriate.
In case that this file does not exist, the file that is loaded by default is what is found in ${JKQA_HOME}/bin
Results
Once a successful analysing task has been completed:
Typically you will have a model file located at ${plugindata.dir}/project_name/${model.name}_${environment}, where

${plugindata.dir} is ${CHECKING_HOME}/plugindata/appmap/, ${model.name} and ${environment} are the task
properties set by the user;
In the same location and with the same prefix, its reports will have been created, each one with its own extension (.xml, .txt,
.html, etc.);
If you used a DatabaseApmPersistenceManager, the DB would have been populated.
You can now launch the AppMap Browser and navigate through the model, perform queries or impact analysis (see AppMap Browser),
or launch the synchronisation script (see APPMAP/script/syncSoftware script).
Incremental analysis has three different modes: none, delta and scm, with slightly different implementations.
Incremental (no special treatment)
If you don't specify delta nor scm (in the task's panel this is indicated by delta.mode=- ), the most simple incremental analysis is
performed.
The initialModel is copied, and all src.dirs are analyzed, adding those changes to model. No component of the original model is
removed.
This mode is meant to split the analysis of a big software with repeated sub-model. Let's call it a " spacial increment".
Note Please take into consideration that src.dir must not be contained in the initial analysis directory, and use a
different location for sourcode to be analized on this incremental analysis.
Example: there is a project, composed by three big isolated applications A, B and C, plus a shared database D.
A common approach for modeling this situation is preparing D as a standalone model (normal analysis), and then create an incremental
analysis for each application, resulting in the following models: A+D, B+D, C+D.
If we know that the applications are isolated (a part from the use of shared resources such as a database), this is the suggested
approach, because we can see all the important dependencies, while reducing the volume of the final models. The tradeoff is that any
impact analysis starting from a shared object (belonging to D), must be repeated in every model (A+D, B+D and C+D).
Delta
If you specify delta=true (delta.mode=delta in the task's panel), the initialModel is copied, and all src.dirs are analyzed,
applying those changes to the model. This mode is suitable for adding those differences to an existing model, performing a "increment in
time" analysis.
Applying changes means that:
1. (optional) If present, all deleted files found in scm.changelog.xml, will be first removed from the model
2. All new files are added to the model
3. For those re-analyzed component, outgoing relations are updated, removing those that are not present anymore and adding new
ones.
Example: A big application 'A', is analyzed once, creating an initial model. Every night, every change that has been made during that
day is added to a <YYYYMMDD> folder by an automated script. That folder contains then only the changed files.
YYYYMMDD is the src.dir of that day, and the initial model is the previous day's model.
Note that is is different from incremental mode, because while there we had a spacial partition (every analysis is
meant to be just additive), here we have a timeline, therefore we can (and usually do) analyze the same file which has
changed in time.
Note change log file must be named scm.changelog.xml, and must be placed on analysis directory src.dirs.
Please see example of changelog file below.
SCM
You can specify the scm=true parameter, allowing a different approach to AIM file analysis. If you use a source control management
system, you are used to have your local source replaced by the revision you want to work on. Well, here we're talking about the same
philosopy.
Using checking's SCM plugin, you can update your local copy, and then analyze it with AIM. A special changelog file (
scm.changelog.xml) will be produced by that plugin under project's root dir, and the files under analysis will be just those indicated
by that changelog.
Note also that src.dir is ignored if it is the same as above: the AIM model knows which are the base directories, and
this task re-analyzes them, taking in consideration scm.changelog.xml
Note change log file must be named scm.changelog.xml, and must be placed on analysis directory src.dirs.
Please see example of changelog file below.
Example of SCM change log file
<?xml version="1.0" encoding="ISO-8859-1"?>

<changeset datePattern="yyyyMMdd HH:mm:ss z" start="20121111 12:40:11 CET" end="20130511 13:40:11
CEST">
<changelog-entry>
<date pattern="yyyy-MM-dd">2013-05-08</date>
<time pattern="HH:mm:ss">16:56:41</time>
<author><![CDATA[tespeleta <tomas.espeleta@optimyth.com>]]></author>
<file>
<action>modified</action>
<name>modules/AimUtils/src/com/optimyth/apm/AimConstants.java</name>
<revision>69183825f4f028a12fe1181cb0e74dd135e724ca</revision>
</file>
<file>
<action>deleted</action>
<name>modules/AimUtils/src/com/optimyth/apm/util/JarUtils.java</name>
<revision>69183825f4f028a12fe1181cb0e74dd135e724ca</revision>
</file>
<msg><![CDATA[AIM-439 Custom icons extension]]></msg>
</changelog-entry>
<changelog-entry>
<date pattern="yyyy-MM-dd">2013-04-10</date>
<time pattern="HH:mm:ss">17:24:23</time>
<author><![CDATA[tespeleta <tomas.espeleta@optimyth.com>]]></author>
<file>
<action>added</action>
<name>modules/AimUtils/src/com/optimyth/apm/util/spring/SpringVisitor.java</name>
<revision>e8ad838ac8a3050ed5bc0c74da95839956917ea2</revision>
</file>
<msg><![CDATA[AIM-432]]></msg>
</changelog-entry>
</changeset>
AIM TASK - Synchronization with checKing
APPMAP - Synchronization with checKing

Purpose
synchronization task configuration
synchronization scripts
The Ant script
Memory requirements
The Spring beans
The persistence manager
The item DAO
The project converter
Project converters
Basic project converter
Hierarchical project converter
Purpose
This document is a quick guide to understanding and customising the synchronization between APPMAP plug-in and checKing. This
task is meant to export all the information from the APPMAP model to checKing projects.
synchronization task configuration
Upon selection of this task in the checKing scheduler, the usual panel will pop up. Properties for this task are:
appmapModel: The path of the APPMAP serialised model to be synchronized. The default value is
${plugindata.dir}/appmap.h2.db;
updateExisting: Indicates whether synchronization must update existing checKing projects or not. The default value is false;
copyFiles: Indicates whether the APPMAP artefacts must be copied or not. The default value is false;
targetPath: If copyFiles is set to true, this will be the path folder into which the APPMAP artefacts will be copied. The default
value is ${CHECKING_SRC}.
synchronization scripts
There are two main scripts which configure synchronization, run-apm-synchronization.xml and apm-synchronizer.xml, both of them are
located in the ${plugin.dir}/scripts folder.
The Ant script
This script can be executed from both checKing tasks scheduler, as explained before, and from the command line. To execute from the
command line just launch the script as a normal Ant script. You can specify your own arguments using the -D option.
Example:
${plugin.dir}/scripts> ant -f run-apm-synchronization.xml -DappmapModel=path/my.h2.db

-DupdateExisting=true -DcopyFiles=true -DtargetPath=myTargetPath
Memory requirements
Because the APPMAP model might need a lot of memory, you can modify this script to be executed in a forked JVM with your own
memory restrictions (this is the default configuration). The <sync.task> argument fork lets you decide between the same JVM or a
new one, and <jvmarg> elements control the memory restrictions:
-Xms: initial Java heap size.

-Xmx: maximum Java heap size.
-Xss: the stack size for each thread.
run-apm-synchronization.xml
<project name="APM-Synchronization" default="sync" basedir=".">

<description>
Script de sincronizacion de AppMap con ChecKing.
</description>
[CHKM:...]
<sync.task
appmapModel="@{appmapModel}"
targetDir="@{targetDir}"
updateExisting="@{updateExisting}"
copyFiles="@{copyFiles}"
classpathref="sync.classpath"
fork="yes"
>
<jvmarg value="-Xms192m"/>
<jvmarg value="-Xmx192m"/>
<jvmarg value="-Xss256k"/>
</sync.task>
[CHKM:...]
</project>
The Spring beans
These are the default beans defined in the apm-synchronizer.xml file:
A persistence manager.
An item DAO (Database Access Object).
A project converter.
The persistence manager
This element is used to retrieve and load an APPMAP model. The default manager loads the model and deserialises it from the file set
as the file bean property.
<bean name="APPMAP/sync/persistenceManager" class=

"com.optimyth.apm.persistence.SerializableApmPersistenceManager">
<property name="file" value="${CHECKING_HOME}/plugindata/appmap/appmap.h2.db"/>
</bean>
Available managers are:
com.optimyth.apm.persistence.CompositeApmPersistenceManager (this manager allows the setting of more than one

manager at the same time)
com.optimyth.apm.persistence.DatabaseApmPersistenceManager (loads the model from a DB containing APPMAP
model data)
com.optimyth.apm.persistence.SerializableApmPersistenceManager (the default one, as explained before)
The item DAO
This element is used to retrieve the projects from checKing. The default item DAO is the XML implementation.
<bean name="APPMAP/sync/itemDao" class="com.als.checking.model.project.XmlItemDao" />
Available DAOs item are:
com.als.checking.model.project.XmlItemDao
The project converter
The default converter used is the most basic one.
<bean name="APPMAP/sync/projectConverter" class=

"com.optimyth.checking.plugin.appmap.script.BasicProjectConverter" />
Available converters are:
com.optimyth.checking.plugin.appmap.script.BasicProjectConverter
com.optimyth.checking.plugin.appmap.script.HierarchicalProjectConverter
Both are explained in detail in the following section.
Project converters
The project converter selected in apm-synchronizer.xml defines how the synchronization will behave when an APPMAP software entity
is found. There are several cases:
The software does not exists as a project item in checKing.

The software exists as a checKing project and it must NOT be modified.
The software exists as a checKing project and it must be updated with APPMAP model data.
Basic project converter
Default strategy for mapping between APPMAP software entities ("bean" in what follows) and checKing (software) items ("item" in what
follows).
If flag updateExisting is true, existing items will be updated with bean information (if false, existing items will be kept
unmodified).
appmapKey and swType properties will be added to item as user properties from the bean's key and softwareType
properties.
The item mailing list will be extracted from the Person's email p where p is each Person related to a bean.
The path property will be derived from a bean's artefacts property, as concatenation of
/BASEDIR_PATH/RELATIVE_PATH, where BASEDIR_PATH is one of the directories where the APPMAP analysis started,
and RELATIVE_PATH is the largest path substring not containing wildcards .
If copyFiles is true, the item path will be targetPath/projectPath/RELATIVE_PATH, where targetDir is specified in task
configuration, projectPath is an item's name and RELATIVE_PATH is computed as before. Files matching the item pattern will be
copied from the APPMAP analysis area to the item path.
In order to load the APPMAP model, appmapModel argument will be used to set the ApmPersistenceManager's file using reflection. If
the manager does not use a file, its own behaviour would take place instead.
For each piece of software found in the APPMAP model, it uses only its own artefacts. If that software does not have any, then the
checKing project will not have files associated either.
Hierarchical project converter
Identical to basic project converter, but implements different artefacts processing.
For each piece of software found in the APPMAP model, it uses its own artefacts just in case there were not any available. Otherwise, it
collects all the artefacts from its component entities directly associated to it and from its child software entities applying this process
recursively. In other words, a software artefact prevails over those of its components, but the last ones are used in case the software
does not have any.
AIM - Application map Browser

Overview
Quick Meta-Model Review
Main Elements
Menu Bar
Tools Bar
Tree View
Tree View Tools Bar
Tree View Contextual Actions
Status Bar
Browsing the Model
Pivotal Graphs Tools Bar
Applying Filters to Graphs
Pivotal Graphs Contextual Actions
Graph filter...
Go to previous node
Picking Mode
Transforming Mode
Show legend
Show graph options
Artifacts
Code Viewer
Pivotal Graphs Auxiliary Tabs
Properties, Relations and Metrics Tabs
Collapsed Node Tab
Querying the Model
Queries Tools Bar
Queries Wizard
Queries Auxiliary Tabs, Results
Query Results Contextual Actions
Right-click on Query Results
Navigation from Query Results
Performing Impact Analyses
Impact Analyses Tools Bar
Impact Analyses Wizard
Sources
Targets
Impact Analysis results
Targets tab
Path summary and Path graph
Targets Tab Contextual Actions
Right-click on Targets Table
Navigation from Targets Table
Preferences
Connection preferences
Searching in APPMAP Navigator
Appendix A: How to configure your own model tree
General structure of a view
Main node tree
Description
Imports section
Definition of macros
The view
userDefined elements
systemDefined elements
group elements
Appendix B: Entity relations
Appendix C: Icons available
Appendix D: How to configure time consuming AQL queries
Appendix E: How to set browser permissions
Appendix F: How to customized new icons in the browser
Overview
APPMAP Browser is a tool used to show an overall view of a certain company. As its name states, it is an application map containing
information about both organizational and logical entities, allowing the execution of queries against the model as well as impact analysis
(e.g. in what way are entities within the model affected by modifying other entities? ).
When clicking on the browser's link in the APPMAP panel, a JNLP application is launched.
JDK version
Since version 2.5.1, the JNLP file specifies that java 1.6+ is required on client side to launch APPMAP browser. This is
the supported and tested version, but this is not strictly necessary: you can try to configure it back to 1.5+, but this is
not the default mode and could originate some minor graphical glitches.
Quick Meta-Model Review
Models from different companies share the meta-model specified in APPMAP. The meta-model structure is the following:
The main container, ApmModel is divided in two secondary containers and contain all the relations between them. Those containers
are:
OrganizationalModel: Contains all the organizational entities and relations between themselves. Represents all the
company's organizational information, like divisions or staff. Those entities are:
Organization: Represents an organization, a company, as its name states; it might be the client's own company or
other partners.
Unit: A type of Organization, each one could represent a company's division or department.
Person: Represents each person of the company's staff, or maybe managers, developers or contacts from other
companies.
PortfolioModel: Contains all the logical entities and relations between them. Represents the company's software
information. Those entities are:
Software: They could be applications or modules used within the company, created by it or by third-parties.
Component: Represents business entities like business processes or business objects etc.
LogicalModel: Contains groups (explicit and dynamic) and their membership relations:
DynamicGroup: A group containing aql or groovy expressions for filter and grouping entities. An ApmEntity can
belong or not to a group. Membership relations are not serialized and must be recalculated every time the model
changes ("classify" operation).
ExplicitGroup: A group where all its members are explicitly specified by the user. Memberships to these groups
are not calculated, so they are stored into the model as "GroupRelation".
Relations between entities are as follows:
Organization - Unit: These relations could be containment relations, because an organization might be divided into several units.
Organization - Person: These relations could be containment relations, because an organization is made up of staff.
Person - Unit: These relations are special relations between a person and a unit (e.g. its manager).
Person - Person: These relations are between people for example between manager, supervisor or partner etc.
Software - Software: These relations are typically a software entity formed by many modules.
Software - Component: These relations may be formed of several components (e.g. database tables and methods), or they are used
in different ways.
Component - Component: These relations relate to components which can be split into other components, or they might
use/call/invoke each other.
Organization - Software: These relations relate to organizations that develop, use or take care of different applications.
Person - Software: However it might be a specific person instead of an organization that is developing, using or taking care of it.
Organizational entity - Component: The same is true of components.
GroupEntity - ApmEntity: These are group membership relations.
Main Elements
APPMAP actions are accesible via the menu bar located at the top of the screen (1), a tool bar located just below the menu bar (2),
and a pop-up menu that is activated by right-clicking on different elements of the browser (tree nodes, table rows or graph's vertices and
edges). A statusbar at the bottom of the window (3) informs about major changes in the state of the browser. Users have at all times a
tree view of current model loaded at his/her disposition (4), which is highly customizable and offers different functionality based on
central tab shown at that time. Central tabbed panel (5) contain main browser's functionality, like navigating through dependencies
graph and performing queries or impact analyses. Each central tab typically has one or more associated tabs located in south tabbed
panel (6).
Central tabs names are editable, just double-click on it, enter a new name and click intro. In addition, you can close
them by pressing the little button next to their name.
Menu Bar
On the top menu bar there are some common operations:
File:
Load Model...: Retrieves available APPMAP models, either from checKing if working in server mode, or from client's file
system if working in local mode.
Work Offline: When working with server models, this option is available in order to download the model and work
autonomously from that moment on.
Preferences: Shows a few customizable options.
Output Console: Shows the application's default output stream.
Disconnect / Connect: If connection with server is available, commutes between server and local (without conection)
working modes.
Quit: Exits the browser.
View:
New Pivotal Graph: Adds new pivotal graph tab.
Properties Table: If tab currently selected is a pivotal graph tab, adds properties tab to its south panel, or shows it already
exists.
Relations Table: If tab currently selected is a pivotal graph tab, adds relations tab to its south panel, or shows it already
exists.
Search:
New Query: Adds new query tab.
New Impact Analysis: Adds new impact analysis tab.
Help:
Help Contents: Opens the PDF documentation in an external reader.
About APM: Shows application's basic information.
Shortcuts
Almost all actions have a combination of key associated, shown right next to its label. Pressing that combination will
trigger its action.
Tools Bar
The main toolbar is just below the menu bar. It contains the following buttons:
Icon Name Description
Load Model Retrieves available

APPMAP models from
checKing, or from the
client's file system if
server is not available.
Work When working with

Offline server models, this
option is available in
order to download the
model and work
autonomously from that
moment on.
New Pivotal Adds new pivotal graph

Graph tab.
New Query Adds new query tab.
New Impact Adds new impact

Analysis analysis tab.
Preferences Shows a few
customizable options.
Work Offline
This option might interest you because download the model to work offline would mean that you will no longer depend
on server availability.
You can always load the original model at the server again.
Tree View
This view is accessible from anywhere in the browser. It offers a hierarchical view of current model and basic interaction with central
tabbed panel tabs.
Tree View Tools Bar
The tree tab has its own toolbar, from which you can access some actions related with tree navigation:
Expand all This button will expand all tree paths, showing all its nodes (disabled for big
models for efficiency purposes).
Collapse all This button will collapse all tree nodes expanded at that moment.
Update When toggled down, tree selection will change automatically if navigating
selection through graph.
Sort Sorts the tree alphabetically or logically (default mode, based on the XML
alphabetically configuration file used to render the tree model).
Change view There is a pulldown menu where you can select which view must apply.
pulldown Available views are either collected from client's file system (previously
applied views) if working in local mode, in which case you can add new
views too, or from checKing if working in server mode.
Tree View Contextual Actions

By right-clicking nodes in tree, you can access additional options:
Add to impact analysis. If central tab shown is an Impact Analysis tab, this action add nodes currently selected as impact analysis
sources.
Artifacts. If model's entity has artifacts (source files) associated, this option let you choose one and open it in code viewer (only
available in server mode). See Code Viewer section for further information.
Status Bar
Located at the bottom of the browser's window, this bar will show information about important changes in browser's state. More
specifically, its main function is to show changes in browser's connection state with checKing server.
Browsing the Model
A Pivotal Graph tab is created by default on browser start-up. You can add several more though the corresponding action of the menu
bar or the tools bar. This kind of tab shows a pivotal entity and its direct relations with other entities.
If you select an entity in the tree view, the tab will display a graph of that entity showing all those entities directly related to it. This can be
configured through graph filters. By double clicking on a node in the graph you can navigate through the model.
Pivotal Graphs Tools Bar
The Pivotal Graph tab has its own toolbar, from which you can access some actions related with graph:
Auto-fit Forces zoom on graph in order to see it completely, and take advantage of all space available.
graph
Change Commutes between picking and transforming modes. See picking mode and transforming mode sections for
mode further information.
Apply filter... Create, apply, load or save a graph filter. See this section for further information.
Save graph Pulldown menu that let you export current graph to a image format.
Update When toggled down, graph is updated selection will change automatically if navigating through graph.
graph
Applying Filters to Graphs
Graphs can be filtered, showing only those entities of relevance. In the tools bar you will see a pulldown menu like this one:
First, standard options are shown:
- No filters -: Disable all filters in graph.

- Customized filter -: You can recall the last customized filter, which you can create using the New Filter menu option.
A list of preset graph filters will follow, use the pulldown menu to select one:
Second level components: components directly related to current entity (presumably a class), and those directly related to them.
Class hierarchy: up to five levels of inheritance, in both directions, with current entity.
Calls between classes: up to five levels of calls from/to current entity (presumably a class).
Table usages: components performing SELECT, INSERT or UPDATE directly or indirectly on current entity (presumably a database
table).
Finally, filter management options:
New Filter: Create a new filter

Load Filter... from local file: lets you load a filter previously saved to the client's file system; from server displays a list of available
queries in checKing. The filter loaded is added to the list of filters).
Save Filter... to local file: saves current customised filter on the client's file system; in server adds the filter to those stored in
checKing (filter saved is added to the list of filters).
Pivotal Graphs Contextual Actions
By right-clicking in the graph you can access additional options:
Graph filter: Allows you to refine the data displayed in the graph.
Go to previous node: Navigates to the previous node in the hierarchy.
Picking mode: Allows the nodes to be moved around the screen.
Transforming mode: Allows the entire graph to be moved.
Show legend: Displays the legend box.
Show graph options: Displays a window detailing the keyboard short cuts for the picking and transform mode.
Artifacts: When right-clicked on an entity, let the user select one if its artifacts to show it in Code Viewer.
Below we explain the function of each menu option.

Graph filter...
This option lets you decide which types of entities and relations are relevant, and the graph's depth (longest path length). A dialogue box
like the following one will be shown:
Entity types: This list contains the entity types discovered within the current model. Select those allowed in the query results.
Relation types: This list contains relation types discovered within the current model. The query results will be those entities with at
least one incident relation whose type were selected in the list.
Depth: This element lets the user decide how far the search should go into entities not related directly with the selected one (the
length of the longest path from the pivot entity to any other one). Since searching too far would cause too much delay, and the graph
would be too big, the number should be chosen with care.
The Activate filter button must be activated and customized filter selected from the preset graph filters drop down
on the toolbar.
Go to previous node
Navigation from one entity to another is stored. By selecting this option the graph will render the last entity seen.
Picking Mode
This option allows the nodes to be moved around the screen. When you click on this option no pop-up is displayed, however the way you
can rearrange the way the graph is displayed does change. This is the default mode.
The nodes can be repositioned within the panel by selecting a node with the mouse pointer and dragging it to the desired position. The
possible actions are:
Click on a node/edge: selects that node/edge;

Drag & Drop on a selection: moves that selection to the desired position;
Drag & Drop not on a node/edge: draws a rectangle and selects all nodes within it;
Control + click on a node: centres the graph on that node;
Shift + click on a node/edge: adds that node/edge to the selection;
Shift + Drag & Drop not on a node: adds the nodes within the rectangle to the selection.
Pressing the 'P' key will also set this mode.
Transforming Mode
This mode allows the user to apply some basic transformations to the entire graph. The possible actions are:
Drag & Drop: Moves the whole graph to the desired position.
Pressing the 'T' key will also set this mode.
Show legend
An internal box will be shown with the graph's legend.
Show graph options
An internal box will be shown explaining Picking and Transforming modes.
Artifacts
If graph's entity has artifacts (source files) associated, this option let you choose one and open it in code viewer (only available in server
mode). See Code Viewer section for further information.
Code Viewer
This viewer is only available when you right-click on an entity in the graph, in the model tree or in the query results, and select the option
Artifacts. It requires working in server mode, too.
Allows the user to see the artifact(s) (source files) associated with that entity. When you chose this option for a portfolio entity (software
or component) which has artifacts associated, a dialogue box will be shown from which you can choose one of them:
Chose whichever artifact you want to see and accept. This will open a new dialogue box showing the desired artifact, with syntax
highlighting if its language and/or file extension is within those supported (the language prevails over file extension):
Remember that only specific artifact locations can be used to retrieve artifacts. Those declared as a file pattern will be
ignored.
Pivotal Graphs Auxiliary Tabs
Properties, Relations and Metrics Tabs
Selecting a node in the model tree will show its properties, relations and metrics (if the model has metrics) at the bottom of the main
window as two tables. Both of them are sortable left-clicking on each column header (rotating between A-Z, Z-A, and original order).
Furthermore, columns shown in all tables can be customized. You can right-click on the header and a list of available columns will be
shown. Check/uncheck each one in order to show/hide it.
It is possible to export table's information to a CSV file by right-clicking on the table and selecting that option.
Collapsed Node Tab
If there are too many entities to paint in a graph, entities of the same type are collapsed into one node in order to reduce their numbers.
Double-clicking on a collapsed node opens a new tab in the south panel. This tab contains a table with all collapsed entities:
Querying the Model
To query the model select New Query from the menu bar or the tools bar. You can have as many new query tabs as you wish
simultaneosly. This kind of tabs allows the user to search for entities in the model with specific characteristics.
Queries Tools Bar
Query tab has its own toolbar, from which you can access some actions related with query management:
Run Start query execution and display results in the lower panel.
query
Reset Reset query parameters and remove the last results panel.
Load Options are: from local file system, search and select the properties file; or from server, a combo box will be shown with
query queries stored in checKing, select one. The state of that tab search criteria (wizards and AQL expression textfields) will
be restored to match the query data.
Save Options are to local file system or in server. In both cases insert name and description (optional) in the dialogue box to
query save it. If saved to local file, location of the file will be requested, too. The state of that tab search criteria (wizards and
AQL expression textfields) will be stored into a properties file.
Queries Wizard
The wizard provides an easy way to make a query. To do so, follow these steps:
1. Enter an entity name in the Entity Name text box;

2. Select the Entity types and Relation types. Use the Control key to make more than one selection.
3. Click the Run query button.
Search results will appear in the results section below the wizard.
It is not necessary to enter an entity name nor select an entity type or relation type. However the search may take a
long time and return an unmanageable quantity of results.
AQL tab
Users familiar with AQL expressions are recommended to use one in AppMap Query Language tab. See the manual
APPMAP Query Language for more information on how to build AQL expressions.
Queries Auxiliary Tabs, Results
Results of a query created either by the wizard or by entering an AQL statement are shown in table form. Columns are sortable
left-clicking on each one's header (rotating between A-Z, Z-A, and original order). Furthermore, you can right-click on the header and a
list of available columns will be shown. Check/uncheck each one in order to show/hide it.
Query Results Contextual Actions
Right-click on Query Results
Right-clicking on any row will show a pop-up menu with the following actions:
Export to CSV: saves the results to a CSV formatted (semi-colon separated) file (note that only shown columns are exported).
Artifacts: if row is an entity, and it has artifacts associated, let the user select an artifact and shows it in Code Viewer.
Navigation from Query Results
Double-clicking on a row opens a new Pivotal Graph tab with that entity as pivot node.
Performing Impact Analyses
Impact analysis shows the impact of changing one or more entities in the model. Perhaps you wish to remove an entity, or refactor some
module of your application, and need to determine the impact of such a decision. The impact analysis tool can be used for this purpose.
Impact Analyses Tools Bar
Impact analysis tab has its own toolbar, giving you access to actions related with this analysis management:
Run Start query execution and display results in the lower panel.
impact
analysis
Reset Reset analysis parameters and remove the last results panel.
Add Open wizard to add source entities to this analysis.

sources
Auto-fit Forces zoom on impact graph, in order to see it completely, and take advantage of all space available.
graph
Load Options are: from local file system, search and select the properties file; or from server, a combo box will be shown
query with queries stored in checKing, select one. The state of that tab search criteria (wizards and AQL expression
textfields) will be restored to match the query data.
Save Options are to local file system or in server. In both cases insert name and description (optional) in the dialogue box to
query save it. If saved to local file, location of the file will be requested, too. The state of that tab search criteria (wizards and
AQL expression textfields) will be stored into a properties file.
Export Saves an HTML report of the last impact analysis performed and shows it in a panel.
HTML
Report
Export Exports an XML report of the last impact analysis performed.

XML
Report
Impact Analyses Wizard
This wizard is divided in two sections: sources and targets. While sources is a list of entities used as the starting point of analysis,
targets represents the criteria of the analysis, in other words, which kind of entities we care for.
Sources
This list contains all the entities that will be used as sources for the impact analysis. This list can be filled by:
Drag & Drop a (multiple) selection from the tree view to the sources list.
Right-click on selected entities in tree view -> Add to impact analysis
Sources Wizard: opened with (from the tools bar), or Add Source entry on the right-click popup menu. This wizard lets you
specify source entities' name pattern and/or type and fill the sources list with matching elements.
AQL tab
Targets
This panel contains a wizard to set the entities' name pattern, type, direction and/or depth (see Appendix B for further information about
directions in wizards). These criteria will apply to analysis in order to collect target entities.
AQL tab
Impact Analysis results
Targets tab
If impact analysis execution is successfully completed, an All targets tab will be shown as a result, containing all the entities that were
resolved as targets by the impact analysis.
Path summary and Path graph
As well as the final targets, APPMAP browser will compute all the possible paths between sources and targets.
Along with targets tab, an Path summary tab will be shown to express how may paths can be found between each pair source - target.
Path Limits
Founding all-pairs between software components is a complex task, so some limitations are applied. Please, take them
into consideration when reading paths:
An AQL traverses the subgraph until we reach desired targets. The algorithm will stop at some point. The
maximum depth (D) reached by the AQL algorithm is taken into account when calculating paths, so that all those
paths longer than this limit will not be shown.
The intermediate nodes between sources and targets are limited to those traversed by AQL.
The relations taken in consideration are more than those traversed by AQL: actually, they are ALL the relations
between the intermediate nodes.
contains relation, on the other hand, are NOT considered.
This is an example of impact analysis, showing paths summary and graph:

Path selector: impact graph paths are context subgraphs with potentially many intermediate nodes, so with this tool you can highlight
each path
Path summary: a table with source-targets combinations, with the number of paths found for each combination.
Single path toggle: sometimes the paths between source and target are too many to be displayed in a context graph, so you can
switch to single path mode with this toggle
Targets Tab Contextual Actions
Right-click on Targets Table
Right-clicking on any row will show a pop-up menu with the following actions:
Export to CSV: saves the results to a CSV formatted (semi-colon separated) file (note that only shown columns are exported).
Artifacts: if selected target has artifacts associated, let the user select an artifact and shows it in Code Viewer.
Navigation from Targets Table
Double-clicking on a row opens a new Pivotal Graph tab with that target as pivot node.
Preferences
User is allowed to customise some application preferences, grouped by category. The following actions apply over all categories:
Save: Saves all changes performed by user.

Restore: Restores all preferences to their stored values.
Cancel: Changes are discarted and dialog is closed.
Connection preferences
Those related to communication between APPMAP Browser and checKing server.
Configurable options:
Proxy Host: if client's machine is accessing checKing server through proxy, type here the URL where proxy host is located;
Proxy Port: the port to access the proxy host;
Username: if proxy host requires authentication, fill this field with your username;
Password: if proxy host requires authentication, fill this field with your password;
Scheme: proxy authentication scheme, this will set the scheme to be used. NTLMv2 is not supported.
Cookies policy: provides corresponding cookie management interface for a given type or version of cookie.
Query server: if proxy is set, query server can work in two different modes.
If you have direct connection to the server (no firewalls, you're using a web proxy for caching purposes), use direct
(Direct Connection)
If you do not have direct connection to the server (e.g. a firewall is blocking you), use proxy (Always offline). This
will downlaod a copy of the model, and it will open it locally.
Available actions:
Test connection: checks if current configuration actually works (note that it does not save anything).
Load default: restore all connection preferences to their default values.
Searching in APPMAP Navigator
The APPMAP Browser makes intensive use of the APM Query Language (AQL) expressions, so it is important to be familiar with this
language. See APPMAP Query Language (AQL) for full details.
Appendix A: How to configure your own model tree
The company defined model entities are shown in the model tree in order to be able to navigate through the model or to choose the
sources of the impact analysis. Different tree configurations can be loaded with Tree view... menu button. You can write your own
configuration following its DTD file (located at
${CHECKING_HOME}/WEB-INF/plugins/plugin-APPMAP/scripts/resources/TreeView.dtd) and typing in the proper AQL
expression (or groovy closures) in the CDATA sections that would match desired nodes. It is also possible to specify one icon of those
packed with APPMAP plug-in for each element, see Appendix C: Icons available.
There are basically three types of elements: userDefined, systemDefined and group. You can combine and nest them in order to define
the configuration desired.
It is advisable to modify or create a view creating a new view, i.e., a new file in the directory view ${CHECKING_DATA}
\plugindata\appmap\treeConfig. This is because future updates of view may result in loss of existing in the view
changes by defect in the product.
General structure of a view
Main node tree
This node has a name attribute which indicates the name of the view and that is the name that will be displayed in the browser.
<tree name="My view">
It will appear in the browser:
Description
Here is where the view is described. For example:
<description>
Default Tree View. You may simply activate / deactivate blocks (with the active attributes),
change parameters, reorder view elements, etc.
</description>
Imports section
Import other xml files. For example:
<import resource="viewComponents/treeview.j2ee.xml" />
Definition of macros
It is possible to define macros for reuse in different blocks of the body from view.
A macro can contain:
A description in the node description.

Parameters necesaries for the macro:
<param name="param1" default="defaultValue1"/>

<param name="param2" default="defaultValue2"/>
Body with part of the view where the elements are: userDefined, systemDefined and group.
For example a macro can be of the form:
<macrodef name="cpp.classes">
<description>C++ classes, grouped by namespace</description>
<param name="classIcon" default="cplusplus"/>

<param name="namespaceIcon" default="folder"/>
<param name="methodIcon" default="flow"/>
<param name="languageFilter"><![CDATA[o.language == 'cpp']]></param>
<body>
<group iconPath="/resources/icons/@{classIcon}.png">
<groupFilter resolver="groovyFilter" iconPath="/resources/icons/@{namespaceIcon}.png">
<![CDATA[def name = o.name; if (name==null) return '<default>'; int lastPoint =
name.lastIndexOf(':'); return lastPoint!=-1 ? name.substring(0, lastPoint-1) : '<default>'; ]]>
</groupFilter>
<entityFilter><![CDATA[o.subType == 'class' && (@{languageFilter})]]></entityFilter>
<toString>
def name = o.name; if (name==null) return 'UNKNOWN'; int lastPoint = name.lastIndexOf(':');
return lastPoint!=-1 ? name.substring(lastPoint+1) : name;
</toString>
<systemDefined iconPath="/resources/icons/@{methodIcon}.png">
<filter><![CDATA[ o.type=='component' && o.subType=='operation' ]]></filter>
</systemDefined>
</group>
</body>
</macrodef>
To make a macro call is enough to put the following:
<macro name="my.macro">
<arg name="param1" value="value1"/>
<arg name="param2" value="value2"/>
</macro>
This means that the part of the view defined in the body of the macro with parameters that are defined will be inserted.
The view
The last part of the view is the view itself that contains elements of type userDefined, systemDefined and group.
userDefined elements
Description
Use this element if you want to define an artificial container in to which you can drop other elements.
Attributes
name: Swing tree node's name.

iconPath: Swing tree node's icon.
Subelements
userDefined, _systemDefined _ or _group _: As the simplest element possible, the only subelements allowed are these ones.
Example
<userDefined name="ContainerName" iconPath="/resources/icons/icon.png">


</userDefined>
systemDefined elements
Description
This element lets you decide current entity's children (initially, ApmModel) to decide which ones must be added as a swing tree node's
child.
Attributes
resolver: This value must be one of aqlFilter or groovyFilter, the first one being the default value if you do not specify it.
iconPath: Swing tree node's icon for each matching entity.
Subelements
filter: It contains a CDATA element with the AQL or Groovy expression to apply as the filter of current entity's children. This means
that within the current set of child entities, filter is going to be applied in order to know if the filter expression matchs or not, so this
filter expression must return a boolean value. If there were several filter subelements, only the first one is used, but you must specify
at least one.
selector: (optional) It contains a CDATA element with the AQL expression to retrieve a set of child entitites within current context.
In this way we may want to skip some levels on model in order to retrieve some entities from children of the current direct children.
(i.e.: if we have 'programs -> queries -> tables' and we want to show on tree 'programs -> tables' avoiding to include query entities
on tree). After retrieve a subset, we may filtering those elements applying previous subelement filter on it. (i.e.: filter only those
entities that matchs name starts with 'M').
userDefined, _systemDefined _ or _group _: Nest them as you wish.
Example
<systemDefined resolver="groovyFilter" iconPath="/resources/icons/module.png">

<selector><![CDATA[ {aqlExpression} ]]></selector>
<filter><![CDATA[
o.getPropertyByName('softwareType').value?.name == 'module'
]]></filter>
</systemDefined>
group elements
Description
Finally, group elements are handy in order to classify the current entity's children in different groups. It is very similar to checKing
project's portfolio grouping.
Attributes
This element has one sole attribute: type, which indicates whether interpret or not subtrees.
type: (optional) May be "entity" or "subtree". The first one (entity) is the default mode: all entities belonging to a group are nested
under the group node. On the other way, subtree allows nesting userDefined, systemDefined or group elements.
Subelements
groupFilter: This contains a CDATA element with an AQL expression that collects the group names.
Attribute iconPath: A Swing tree node's icon for each matching entity.
Attribute resolver: This value must be one of aqlFilter or groovyFilter, being the second one the default value if you do not
specify it.
Attribute preset: You can use a preset filter instead of typing the code yourself.
Name Description Example
groupType Uses each entity type as a group. Groups 'software' and 'component'
discovered
groupSubtype Uses each entity subtype (softwareType, componentType, Groups 'layer', 'module' and 'program'
etc.) as a group. discovered
groupTag Each tag group discovered will be used as a group. Groups 'TAG1', 'TAG2' and 'TAG3'
discovered
groupPackage Thought for object oriented components (e.g.: Java classes), Groups 'com.apm', 'com.apm.gui',
which full names include its package name, uses each 'com.apm.rules' and
package as a group. 'com.apm.builder' discovered
entitySelector: (optional) It contains a CDATA element with the AQL expression to retrieve a set of child entitites within current
context. In this way we may want to skip some levels on model in order to retrieve some entities from children of the current direct
children. (i.e.: if we have 'programs -> queries -> tables' and we want to show on tree 'programs -> tables' avoiding to include query
entities on tree). After retrieve a subset, we may filtering those elements applying below subelement entityFilter on it. (i.e.: filter only
those entities that matchs name starts with 'M').
entityFilter: This contains a CDATA element with the AQL or Groovy expression to apply as the filter of the current entity's children,
classifying them into the groups discovered before. This means that within the current set of child entities, entityFilter is going to be
applied in order to know if the filter expression matchs or not, so this filter expression must return a boolean value. When filling the
groups, each appearance of #group# placeholder in that expression will be replaced with the current group's name.
Attribute iconPath: The Swing tree node's icon for each matching entity.
Attribute resolver: This value must be one of aqlFilter or groovyFilter, being the first one the default value if you do not
specify it.
Name Description
filterGroovyType Checks if current entity's type is #group#.
filterGroovySubtype Checks if current entity's subtype is #group#.
filterGroovyTag Checks if current entity's tags are #group#.
filterGroovyPackage Checks if current entity's package is #group#.
toString: This contains a CDATA element with Groovy code that transforms an entity (a variable called 'o' in the code) into a proper
string for tree node's name. This element is optional, if it is not set, the entity's name will be used.
Name Description Example
toStringShortname Transform the entity's name into a substring after its last point. com.apm.Class -> Class
userDefined, systemDefined or group: Nest them as you wish.

In all elements, preset attribute prevails over any CDATA subelement.
Example
<group type="entity"> 

<groupFilter iconPath="/resources/icons/groupIcon.png"><![CDATA[
./*/*[@language='java']/#int lastPoint = o.name?.lastIndexOf('.');
return (lastPoint!=-1)? o.name?.substring(0, lastPoint) : 'Without Package'#
]]></groupFilter>
<entitySelector><![CDATA[ {aqlExpression} ]]></entitySelector>
<entityFilter preset="filterGroovyPackage" resolver="groovyFilter" iconPath=
"/resources/icons/entityIcon.png" />
<toString preset="toStringShortname" />
</group>
Example with subtree
<group type="subtree">
<groupFilter iconPath="/resources/icons/application.png">
<![CDATA[ def af = o.getPropertyByName("area"); return af ==
com.optimyth.apm.model.Property.NULL ? "UNRESOLVED" : af.value ]]>
</groupFilter>
<toString preset="toStringShortname" />
<userDefined name="Cobol programs" iconPath="/resources/icons/layer.png" active="true">
<systemDefined iconPath="/resources/icons/program.png" resolver="groovyFilter">
<filter/>
<selector>
<![CDATA[ //program[@area='#group#' and @language='cobol'] ]]>
</selector>
</systemDefined>
</userDefined>
</group>
Appendix B: Entity relations
Since the purpose of each possible value might be hard to comprehend at first, we will illustrate them with a graphic example (figures B1
and B2). The following image shows how the whole graph looks without filtering (just setting depth to 2).
Depth:
Figure B1: Unfiltered entity relations
Any element: All entities will be shown. This direction is not filtered.
Outgoing: Shows entities accessed through relations going out of the selected entity. If there are several levels, apply this
same direction to other relations.
Incoming: Shows entities accessed through relations coming into the selected entity. If there are several levels, apply this
same direction to other relations.
Outgoing & Incoming: It combines both outgoing and incoming options by showing their node groups.
Any element Outgoing & Incoming
Outgoing Incoming
Figure B2: Entity relations filtered by direction
Appendix C: Icons available
Here is a list of currently supported icons.
Icon Path Icon Path
/resources/icons/application.png /resources/icons/beans.png
/resources/icons/building.png /resources/icons/business_object.png
/resources/icons/business_process.png /resources/icons/business_service.png
/resources/icons/cascade.png /resources/icons/cloud.png
/resources/icons/computer.png /resources/icons/configuration.png
/resources/icons/cplusplus.png /resources/icons/csharp.png
/resources/icons/css.png /resources/icons/database.png
/resources/icons/databases.png /resources/icons/excel.png
/resources/icons/flash.png /resources/icons/flow.png
/resources/icons/helper.png /resources/icons/html.png
/resources/icons/image.png /resources/icons/java.png
/resources/icons/key.png /resources/icons/layer.png
/resources/icons/lock.png /resources/icons/module.png
/resources/icons/monitor.png /resources/icons/organisation.png
/resources/icons/panel.png /resources/icons/pdf.png
/resources/icons/person.png /resources/icons/php.png
/resources/icons/plugin.png /resources/icons/program.png
/resources/icons/report.png /resources/icons/ruby.png
/resources/icons/sap.png /resources/icons/script.png
/resources/icons/server.png /resources/icons/shield.png
/resources/icons/table.png /resources/icons/terminal.png
/resources/icons/tux.png /resources/icons/unit.png
/resources/icons/url_mapper.png /resources/icons/validation.png
/resources/icons/view.png /resources/icons/visualstudio.png
/resources/icons/web_service.png /resources/icons/xhtml.png
/resources/icons/folder.png
Appendix D: How to configure time consuming AQL queries
The browser warns the user when he tries to execute a time-consuming AQL query. This is achieved with a list of regular expressions
that identify these dangerous queries.
The administrator can edit these regular expressions in the file:

${CHECKING_HOME}/plugindata/appmap/aql-patterns.txt
Each line represents a regular expression that has to match the entire AQL query.
Appendix E: How to set browser permissions
Some actions in the browser can be limited to some roles. These can be configured with a special path in the standard checking
permissions system. Configurable actions include:
Permission path Description
+APPMAP/browser/saveQuery Right to save queries into the server
+APPMAP/browser/saveFilter Right to save filters into the server
+APPMAP/browser/savePatterns Right to save "slow aql" patterns into the server
+APPMAP/browser/viewSource Right to view source code of the entities
These permissions must be configured as ROLE permissions.
Appendix F: How to customized new icons in the browser
Description
We can extend default product icons used in the browser, customizing new ones once we want to browse models. Through a ZIP file we
can setup new PNG icons with a descriptor of them.
First of all is to package all PNG icons with custom relative paths within a ZIP file. Also we need to add an XML descriptor file with
relative paths of each icon within the ZIP file.
This could be an example of the file structure in the ZIP file:
custom-icons.xml
icon-path\icon1.png
...
icon-path\iconoN.png
Icons descriptor file is an XML file with same format as used in the original product file.
It is mandatory that filename of the icons descriptor XML must be custom-icons.xml, but relative paths pointing to the
icons could be modified.
Example
<icons>
<icon id="1" file="/resources/icons/a.png" />
<icon id="2" file="/resources/icons/d.png" />
<icon id="3" file="/resources/icons/p.png" />
<icon id="4" file="/resources/icons/r.png" />
<icon id="5" file="/resources/icons/s.png" />
<icon id="6" file="/resources/icons/sp.png" />
</icons>
Each icon tag setup two attributes:
id: a sequence to be used as identification of each icon. May starts at 1, it does not overwrite default product icon sequence.
file: relative path pointing to the icon within ZIP file.
Once ZIP file is generated we should place it into ${CHECKING_DATA}\config\plugins\APPMAP directory
AIM - Scripting
APPMAP Scripting
Overview
How it works
Configuration
How to execute APPMAP scripts
From command line
Scheduled execution
Script reference
Diff
Groovy
ImpactAnalysis
Query
Tag
Validation
Table
Propagation
Overview
APPMAP Scripting provide a "batch" interface (complementary to the AIM - Application map Browser) based on "command-line" oriented
logic that can be scheduled or executed on demand.
There are scripts for different purposes, which typically belong to one of the following groups:
Query: Looks for entities/relationships matching certain criteria, in an existing APPMAP model. An impact analysis is a special kind
of query, that looks for dependencies between a set of source entities matching an AQL query, and a set of targets with dependency
paths from the sources matching another AQL query.
Diff: Finds the differences (either at enties, relations or property values) between two (similar) models. The typical use case is when
a software evolved in time and it is needed to understand the differences between two versions.
Tagging: Tag entities in a model according to certain conditions and tag operations.
Validation: Checks if entities and relationships in an existing APPMAP model follow certain rules (architecture rules, dependency
patterns and so on).
Propagation: Executes a Propagation Analysis that analyze model dependencies for different usages (dead-code detection,
tagging, model dependencies validation).
For building an APPMAP model from source code and a model build configuration, see AIM TASK - Analyze.
How it works
In what follows, $APPMAP_PLUGINDIR will stand for the directory where APPMAP plug-in is installed (e.g.
CHECKING_HOME/WEB-INF/plugins/plugin-APPMAP), and $APPMAP_EXTDIR will stand for the plugin configuration directory,
e.g. CHECKING_DATA/config/plugins/APPMAP.
Each script uses the AIM Query Service to connect to a remote AIM system. Scripts could be invoked programmatically, using the Script
API, via command-line using provided ANT scripts, or via the APPMAP plugin APPMAP/scripts/exec analyzer.
Configuration
To use Scripting funcionalities, you must activate xmlrpc in your checking server. Set xmlrpc.active=true in your
checking configuration properties tab.
The file AimScript.properties contain global configuration parameters. When executing scripts from checKing web interface, it is
recommended to place and edit this file in the APPMAP plugin extensions directory CHECKING_DATA/config/plugins/APPMAP. The
most important parameter is the connection url to the query service.
Default AimScript.properties
# Configuration properties for AIM Scripting# Configuration properties for AIM Scripting
# URL to the AIM Query Service: aim://user:pass@host:port

url=aim://administrator:administrator@localhost:7890
# Timeout for connections to query service, in seconds
timeout=300
# Paths to libraries
# This dirs exist when client is in the checKing machine.
# Copy jars (see classpath in AimScript.xml) to local machine and change, if necessary
# Directory with AIM libraries
lib.dir.aim=${env.CHECKING_HOME}/WEB-INF/plugins/plugin-APPMAP/lib
# Directory with ChecKing libraries
lib.dir.chk=${env.CHECKING_HOME}/WEB-INF/lib
# Entity properties to render in reports

report.properties=key,name,type,subtype,tags,artifacts
# Report file to use

report=
# Templates to use for rendering results

template.query=resources/templates/query.xml.template
template.impact=resources/templates/impactAnalysis.xml.template
template.diff=resources/templates/diff.xml.template
template.validation=resources/templates/validation.xml.template
template.table=
# References to server-side templates (report for propagation analysis is done server-side)

template.deadcode=
template.tagging=
template.validation.server=
# Groovy script for rendering an item when no template is specified.

renderCode=
# Diff script (redefine in script invocation)

checkRelations=yes
checkProperties=yes
entityPredicate=
relationPredicate=
propertyPredicate=
# Tag script (redefine in script invocation)

startAql=
startTagOp=
startTagOpFile=
propagationAql=
propagationTagOp=
propagationTagOpFile=
# File with Groovy code for the Groovy script (redefine in script invocation)
code.resource=
forked=true
When invoking a script either from command-line or from web interface, you may provide a different value for any of the
above properties. that will take precedence over the value in this AimScript.properties file.
How to execute APPMAP scripts
The scripts could be executed from command line (as a set of ANT scripts) or as a checKing job provided by the APPMAP plugin.
From command line

The plug-in provides Apache ANT files with targets for executing APPMAP scripts locally from command-line.
Such Ant files are located in $APPMAP_PLUGINDIR/scripts/remoteScripts or in the installation media.
Basic usage is simple:
ant -f FILE TARGET [-DPARAM=VALUE ...]
Where each script property (model.input etc.) (see Script reference) is passed to the Ant script as Java properties, -DPARAM=VALUE.
If no TARGET is specified, help is assumed, and a short description of script usage will be displayed.
Execution example (e.g. a simple "dead-code" detector):
ant -f Query.xml query -Dmodel=MyPath/MyModel "-Dquery=//component[count(in:component)=0]"
Note that command-line args could be quoted to avoid shell metacharacter expansion issues.
Apache Ant is required by checKing, and the host where the checKing product is installed will typically have the ant
command available for certain accounts on the checKing host. Your system administrator may help you to configure
your user account in checKing host with access to Ant tool.
For further help, execute
ant -f FILE help
for details on each target (script) available.
Scheduled execution
The APPMAP/script/exec is a wrapper that permits the execution of any of the "local" scripts as a checKing analyser: It may be
executed or scheduled from the web admin job scheduling tab.
Script properties:
Property Meaning Format Example
operation Kind of action to execute. Select one action Query
model Software item path (used only for Select one model /my/project/MyModel
resolving configFile )
properties Input properties for script String with PROP=VALUE pairs model.input=MODELFILE|
separated by '|' (pipe) characters query=//table|report=MyReport.xml
configFile Path of configuration file with properties Properties file with PROP=VALUE query.properties
that will be searched for
NOTE: One of the configFile or properties should be specified. When both properties and configFile are specified, values specified in the
properties parameter takes precedence over values with same name in the configFile. If you need a value including vertical bars (|)
characters, prepend them with
(backslash).
If configFile is specified but cannot be located relative to plugin extension dir, execution terminates with error.
Script reference
Script Category Description
Diff Query Performs diff between model and secondModel
Groovy Executes groovy code, with access to the Query Service
ImpactAnalysis Query Performs impact analysis on model, using AQL sources.query for selecting source entities and
AQL query for path between matched sources to targets
Query Query Performs AQL query on model
Tag Transformation Retags model on matched entities, according to a tag operation
Validation Validation Applies validation rules on the given AIM model.
Diff
Performs diff between model and secondModel, generating output in report (or in console).
Differences could be: New or removed entities, relations (dependencies), and properties; or properties with different values.
Parameters:
model - (Mandatory) first input model relative path.

secondModel - (Mandatory) second input model relative path.
report - (Optional) report file with differences between models. If not given, output is generated in standard output.
checkRelations - (Optional) boolean yes/true or no/false, for checking differences in relations (default: yes)
checkProperties - (Optional) boolean yes/true or no/false, for checking differences in properties (default: yes)
entityPredicate - (Optional) groovy predicate (example: o.subtype=='table') on entities to consider for differences.
relationPredicate - (Optional) groovy predicate (example: o.name != 'contains') on relations to consider for differences.
propertyPredicate - (Optional) groovy predicate on property names (example: o in 'myProp', 'myProp2') on properties to
consider for differences.
Output:
Formatted report at report or standard output.
NOTE: If desired, a Groovy template may be set in the "template.diff" property (a resource path available from script execution
classpath). By default, the /resources/templates/diff.xml.template for XML output is used. If desired, you may provide
your own template in order to customise report output.
Usage:
ant -f Diff.xml diff -Dmodel=MODEL_A -DsecondModel=MODEL_B

[-DcheckRelations=yes|no] [-DcheckProperties=yes|no]
[-DentityPredicate=PRED] [-DrelationPredicate=PRED] [-DpropertyPredicate=PRED]
[-Dreport=REPORTFILE]
Groovy
Executes groovy code, which can access to the remote query service.
The groovy script receives the following bounded variables:
client: Instance of com.optimyth.apm.query.client.IQueryClient, for performing remote operations.

ctx: The ScriptContext where parameters and results from other scripts could be stored.
log: Instance of a org.apache.log4j.Logger for logging results from the script code.
Parameters:
code.resource - (Mandatory) Script groovy to be executed.

Usage:
ant -f GroovyScript.xml groovy -Dcode.resource=<Groovy script path>
ImpactAnalysis
Performs impact analysis on model, using sources.query and query, and saving results in report.
Parameters:
model - (Mandatory) input model filename.

sources.query - (Mandatory) "Absolute" AQL expression for entities that will act as "sources" for impact analysis.
query - (Mandatory) "Relative" AQL expression (from matched sources) for entities that will act as "destinations" for impact
analysis.
report - (Optional) The report file where the impact analysis report will be formatted. If not given, output will be generated at
standard output.
NOTE: To use your own template, you may configure it in the template.impact parameter. The default template (
/resources/templates/impactAnalysis.xml.template) will produce a simple XML report with all matched entities (in
source and target sets) and their properties. You may provide a different template in the APPMAP plugin extension dir.
Example:
ant -f ImpactAnalysis.xml impact.analysis -Dmodel=MODEL -Dsources.query=QUERY -Dquery=QUERY

[-Dreport=REPORTFILE]
Query
Performs a query on model, using AQL query language, and saves the output into a report (or standard output if not specified).
Parameters:
model - (Mandatory) input model.

query - (Mandatory) AQL query to execute over the model required.
report - (Optional) The report file where the query report will be formatted. If not given, output will be generated at standard output.
properties - (Optional) comma-separated list of property names in the result to show. Default:
key,name,type,subtype,tags,artifacts
Output:
Report with matched entities / relationships / scalars is dumped to report (or in standard output).
Usage:
ant -f Query.xml query -Dmodel=MODEL -Dquery=QUERY [-Dreport=REPORTFILE]

[-Dproperties=PROP,PROP2,...]
Example:
A (too simple) "dead code" detector.
ant -f Query.xml query -Dmodel=path/to/prj/MyModel "-Dquery=//component[count(in:component)=0]"
Tag
Retags model. Tagging rules are declared in apm-rules-tagging.xml.
Parameters:
model - (Mandatory) model location
start.aql - (Mandatory) AQL query for selecting "starter entities" to tag.
start.tagop - CSV-encoded tag operation on (see below).
start.tagop.file - File with the CSV-encoded tag operation (see below).
propagation.aql - (Optional) Relative AQL query for selecting "propagation" entities from starter entities.
propagation.tagop - (Optional) CSV-encoded tag operation on "propagation" entities.
propagation.tagop.file - (Optional) File with the CSV-encoded tag operation (see below).
Either start.tagop or start.tagop.file should be specified. When propagation.aql is specified, either

propagation.tagop or propagation.tagop.file should be provided.
Tag operation specification:

A tag operation is specified as a sequence of CSV-formatted rows (with 4 columns):
1. Action: One of A (add tags), V (add tags from value closure), R (remove tags), M (replace tags), P (add property)
2. Values to add: comma-separated list of tags to add (A, M), groovy closure returning a string with tags to add (V), or groovy closure
returning the property value (P). Unused for R.
3. Values to remove: comma-separated list of tags to remove (R,M), or property name (P). Unused for A and V.
4. filter: (optional) groovy condition on each entity to alter (use o as argument). Example: o.componentType=='x'
Example:
A|FirstTag,SecondTag||o.subtype=='class'
A|ThirdTag||o.subType='table'
R||OtherTag|
M|FirstTag:ejb|FirstTag|o.subType='class' && o.getPropertyByName('j2eeType')?.value = 'ejb'
V|VarTag:o.subType||
P|o.type + '/' + o.subType|myProperty|
With the above, first tag op means setting FirstTag and SecondTag tag values to every class, setting ThirdTag to every table,
removing OtherTag unconditionally, modifying tags for ejb classes by removing FirstTag and setting FirstTag.ejb, setting a
variable tag VarTag value based on the element subtype, and setting a myProperty property by concatenating the type and subType
properties.
Output:
Model under model location will have all entities retagged by the tagging rules, accoding to the following algorithm:
Entities matched by start.aql ("starter entities") will be tagged by the tag operation provided in either start.tagop or
start.tagop.file.
If propagation.aql is provided, it is executed with starter entities as initial context for the AQL query. The tag operation provided
by either propagation.tagop or propagation.tagop.file are applied on matched entities.
Usage:
ant -f Tag.xml tag -Dmodel=MODEL

-Dstart.aql=AQL {-Dstart.tagop=TAGOP | -Dstart.tagop.file=CSVfile}
[-Dpropagation.aql=AQL [-Dpropagation.tagop=TAGOP | -Dpropagation.tagop.file=CSVfile]]
Example:
To tag tables in model with incident relations from classes with "programTable":
ant -f Tag.xml tag -Dmodel=path/to/prj/MyModel "-Dstart.sql=//table[count(in:program)>0]"

"-Dstart.tagop=A|programTable||"
Validation
Loads model and applies validation rules, generation output at report.

NOTE: Validation rules are configured in the apm-rules-validation.xml descriptor. The script will use the validation ruleset
declared in such descriptor.
A validation rule is focused on emitting "violations" where certain conditions are met in the dependencies model, and typically
represent deviations from architecture standards.
You may specify arquitecture validations in the APPMAP Dependencies Validation Language, directly in the code property, or as a
file in the codeFile property.
Alternatively, you may specify the path to a server-side Spring descriptor (descriptor) that configures validation rules, and
optionally the name of the rule/ruleset bean (beanName) to execute (if not given, the first ruleset found will be used).
See provided APPMAP API documentation (in javadoc format) for implementing your own validation rules.
Parameters:
model - (Mandatory) input model filename

code - Code of dependencies Validation.
codeFile - File with Dependencies Validation.
descriptor - Remote Spring descriptor (in plugin classpath) with validation rules declared.
beanName - The name of the bean.
report - (Optional) The report file where rules' violations detected in the input model will be formatted. If not given, output will be
generated at standard output.
renderCode - (Optional) Code rendered (only used when template.validation is empty)
Output:
Formatted violations report in report, or in standard output when not specified.
NOTE: If desired, a Groovy template may be set in the template.validation property in file AimScript.properties (a
resource path available from script execution classpath). By default, resources/templates/validation.xml.template is
used. If desired, you may provide your own template in order to customise the report output.
Usage:
ant -f Validation.xml validate -Dmodel=MODEL

{-Dcode=DEPVAL_CODE | -DcodeFile=DEPVAL_FILE | -Ddescriptor=REMOTE_DESC [-DbeanName=BEAN]}
[-Dreport=REPORTFILE] [-DrenderCode=RENDERCODE]
Example:
ant -f Validation.xml validate -Dmodel=path/to/prj/MyModel -DcodeFile=ArchValidation.depval

-Dreport=ArchValidation.xml
Table
Performs queries for tabular data (using AQL) on a remote model. An absolute query selects a set of target entities, and additional AQL
expressions produce additional results related to each matched entity. The first column in the results table is the matched entity.
This feature is useful to compute dependency metrics or to find values relative to entities of interest.
By default, result is rendered in comma-separated values (CSV) format, unless renderCode or template.table properties are
specified.
Usage:
ant -f Table.xml table -Dmodel=MODEL
{-Dquery=QUERY | -Dquery.file=FILE} -Dheader=COLNAME,COLNAME... -DtoString=FORMAT_SPEC
{"-Dcolumn.queries=COLQUERY,COLQUERY..." | -Dcolumn.queries.file=FILE}
[-Dcolumns.toString=FORMAT_SPEC,FORMAT_SPEC... | -Dcolumns.toString.file=FILE]
[-Dreport=REPORTFILE] [-DrenderCode=RENDERCODE] [-Dtemplate.table=TEMPLATE]
Where:
MODEL is the model path (e.g. /MyProject/MyModel)

QUERY is an AQL expression, typically absolute, for the target entities to select as rows in table (also the value for the first column
in result).
COLQUERY is an AQL expression for the , relative for column.queries
FILE in query.file is a file containing AQL expression corresponding to query. If specified, query is ignored.
FILE in column.queries.file is a file containing AQL expressions corresponding to column.queries, with expressions separated by
blank lines. If specified, column.queries are ignored.
FORMAT_SPEC is the format specification to use for the matching column: One of key, name, value, atom, relation, or
any groovy expression for formatting each value with o as bound variable (like o.name). Specify toString for formatting each
matched entity by the query expression (first column), and columns.toString for formatting the rest of columns. As before, if you
specify a filename in columns.toString.file, that file must contain comma-separated formatting specifications to give each column.
The default formatting specification for entities is key, for relations is relation (left key -name:role-> right key).
REPORTFILE is the file where the output will be written. When not given, output is rendered in the standard output.
RENDERCODE is a groovy expression for formatting each row (list of strings). Use "o" as the binding variable.
TEMPLATE is a groovy template to use for rendering the TableResult object returned. See provided table.xml.template for
an example.
Output:
Formatted tabular report, written in report file or standard output.
Examples:
1. To show, for each table in the selected model, the list of incident components and its count ( fan-in):
ant -f Table.xml table -Dmodel=/MyPrj/MyModel "-Dheader=table,usedBy,fanin"

-Dquery=//table "-Dcolumn.queries=in:component,count(in:component)" -DtoString=name
2. Trivial dead-code report (not very much accurate, see Propagation Analysis for a more robust alternative):
ant -f Table.xml table -Dmodel=/MyPrj/MyModel

"-Dheader=software,deadClasses,deadTables,deadPrograms"
-Dquery=//application -Dcolumn.queries.file=deadcode.txt -DtoString=name
"-Dcolumns.toString=name,name,name"
with deadcode.txt containing the "trivial dead-code" queries for each entity kind in each application:
class[empty(in:component)]
table[empty(in:component)]
program[empty(in:component)]
Propagation
Executes a Propagation Analysis that analyze model dependencies for different usages (dead-code detection, tagging, model
dependencies validation). See Propagation script for full details on how to use the Propagation.xml script.
APPMAP Query Language (AQL)
APPMAP Query Language (AQL)

Purpose
Syntax
Types in AQL
Conversion rules
AQL elements
Examples
AQL functions
Function count()
Function empty()
Function difference()
Functions dn() and id()
Function intersection()
Function match()
Function tags()
Function union()
AQL API
Using AQL in your own Java programs
For query / impact analysis / APM inventory filtering and other usages, expressions may be written in the APM Query Language.
APPMAP browser, APPMAP scripts and other tools use AQL as their expression language for such usages. This document describes
the language syntax.
Purpose
AQL is a simple declarative language that performs queries, filtering, impact analysis and other operations on an APM model.
AQL is based on expressions that declare a model traversal: think of the APM model as a (directed) object graph where nodes are the
entities (organisational or logical) and their containers, and edges are the relationships between the nodes (for example, if Cobol
program P uses table T, a "uses" relationship links P and T). AQL expressions operate on an initial context node, and apply a sequence
of steps to traverse the model from initial context nodes to a nodeset of reached nodes.
Syntax
APM Query Language (AQL) is an expression language for traversing the APM entities/relationships, similar to XPath (XPath is focused
on finding nodes in XML trees, while AQL is focused on finding entities in APM object graphs).
An AQL program is made by zero or more variable declarations, followed by an AQL expression.
An AQL expression is a sequence of steps, followed by zero or more predicates.
Types in AQL
The supported types are:
boolean: true/false. Any predicate evaluates to boolean.

number: A decimal (floating-point) number. Some AQL functions return a number.
string: A character string.
nodeset: A set of nodes (no duplications allowed). "Node" is any "scalar" value, another nodeset, or an APM object (an
ApmEntity, ApmRelation, ApmContainer, Property).
Type conversions may be done automatically at certain points in expression evaluation:
Return values from expressions inside predicates are converted to boolean.

Functions may expect certain argument/return types. Type conversions are applied accordingly.
In the AQL API (class com.optimyth.apm.modelquery.AqlPath), some methods perform conversions from nodeset to its
scalar return type (boolean, number and string).
Conversion rules
From To Conversion done
nodeset boolean true if nodeset is not empty

nodeset number nodeset size
nodeset string space-separated string values for each node in nodeset
ANY scalar nodeset nodeset with a single scalar node
string number string character length
string boolean true if string has non-whitespace text
number string string representation of the number
number boolean true if number different from 0
boolean string 'true' or 'false'
boolean number 1 for true, 0 for false
AQL elements
Comments
Block comments in AQL use the same delimiters as in XML:

Location paths
A location path is a sequence of steps (separated by /), where each step is a navigation route from current context nodeset, with optional
predicates between [ and ] that will be checked for on navigated items: if a navigated item match the predicates, it will be added to the
next context nodeset.
Root locations defined in APPMAP model
/portfolioModel (where all the components and software entities are stored)
/organizationalModel (reflects the organization model (person, unit etc...)
/logicalModel (contains groups and membership relations)
Axis
A step can start with an axis specification
Step examples, for different axis
in[>1]:stepName (all incoming stepName entities, two or more links away)

in[*]:* (all incoming entities of any type)
inout[>1]:stepName (all related stepName entities, two or more links away)
out[<3]:stepName (outward stepName entities, one or two links away)
..stepName (equals to in:stepName)
//stepName (equals to out[*]:stepName)
Relationships
You may add a percent sign followed by one or more relationship names between the axis and the entity types in order to restrict
resulting nodeset to those entities reached through one of the relationships specified.
Examples using relation filtering
./in[*]%inherits:class (classes that 'inherit' from current node)

./out[*]%calls:class ('calls' done by current node to other classes)
./in%(select,insert,update):component (components that perform a select|insert|update on current
node)
Function calls
Functions may be specified both in steps and predicates. See AQL functions section.
Cobol Programs that reference two or more tables
.//component[@componentType='program' and @language='cobol' ][count(databaseObject)>1]
Code blocks
For programmatic operations, a block of Groovy code could be specified as a code block between # (a code block is treated as a _step,
see above).
code block as a predicate
/portfolioModel/component[#o.componentType == 'businessProcess'#]
Variable declarations and references

AQL expressions can reference variable declarations. Variables are declared and referenced as $varname. A variable declaration
assigns an AQL expression a name, that could be referenced later.


$progs = //component[@componentType = 'program'][match('PATTERN', @name)];
$tables = //component[@componentType = 'db table'][match('PATTERN', @name)];
$progs/in:software | $tables/in:software
Substitution macros
A query can be parametric (bind variables), so that during execution, for example from AIM - Application map Browser), a popup window
will automatically ask for those parameters.
A MACRO_DESCRIPTOR has the following syntax: NAME[:TYPE][:val1;val2;...] where NAME is the parameter name, TYPE could
be one of text, textarea, combo, list, checkbox, radio (text is the default), and val1;val2;... are a ;-separated list of possible values
(for combo, list, checkbox or radio) or a single textual value (for text and textarea). Default values are those placed first in the list.
The values (taken from user) will replaced the macros defined. Examples of parameterized AQL queries:

dn('@{SOURCE}')/component[@language='@{LANGUAGE:combo:java;cobol;jcl}']

/*/@{TYPE1:radio:*;component;software}/@{TYPE1}/(@{TYPE2:list:component;software})

/(@{CONTAINER:checkbox:organizationalModel;portfolioModel})/@{TYPE:textarea:component}
Examples

portfolioModel/component


//component[..software/@name = 'COMMON']


/*//component[intersection(., .//component)]
/*//component[. in .//component]


/*//component[tags('MY_TAG,OTHER_TAG', .)]

dn('sys=MYAPP,bo=MyBusObj')/inout[<3]:component

out[*]:*

/portfolioModel/component[#o.componentType=='businessProcess'#]
/portfolioModel/#o.components.find{ it.componentType=='businessProcess'}#

./in[*]:component

//databaseObject[match('^MYTABS', @name)]/in[*]:(program,class)[in:software/@name='MYAPP']
AQL functions
Function Meaning
number count(arg,...) Counts the total number of nodes in each nodeset arg, or the total number of non false values
for non-nodeset args
boolean empty(arg) Returns true if the arg, evaluated as a nodeset, contains one or more elements, false
otherwise
nodeset difference(nodeset, Returns the set difference of the input args, evaluated as nodesets
nodeset)
nodeset dn Returns a nodeset with all entities matched by key in the model
(string|nodeset,...)
nodeset intersection(nodeset, Set the intersection of all args, evaluated as nodesets

...)
boolean match(regexp, Returns boolean true if the string value for all arguments (2..N) match the regular expression
values...) given as first argument
boolean tags(string, arg, Boolean function that returns true if tags for ALL nodes in args(2..N) implies all tags in first arg
...)
nodeset union(nodeset,...) Returns the union of the input args, evaluated as nodesets
Function count()
Counts the total number of nodes in each nodeset arg, or the total number of non false values for non-nodeset args.
number count(arg,...)
With 0 args, this function returns 0.
Function empty()
Returns true if the arg, evaluated as a nodeset, contains zero elements, false otherwise. Typically used in AQL predicates, similar to
count(arg)=0.
boolean empty(arg).
A single arg should be specified.
Function difference()
Returns the set difference of the input args, evaluated as nodesets.
nodeset difference(nodeset, nodeset)
If a = difference(b, c), a contains all elements in b and NOT in c.

If zero args, returns empty nodeset. If one arg, returns the arg untouched.
If an arg is a "scalar" (string, number, boolean), it is converted to a nodeset with a single node.
Functions dn() and id()
Return a nodeset with all entities matched by key in the model. This is similar to the id() XPath function (this function is aliased as
id() for compatibility).
nodeset dn(string|nodeset,...)
nodeset id(string|nodeset,...)
The string value of each argument is evaluated, and used as a key for direct search in the model. If the argument is a nodeset, for each
node the string value is evaluated and used as a key.
Examples:
dn('my key')/component - Return outgoing components for the specified entity matching 'my key'
dn(component/@referenced) - Return entities with a key in the attribute 'referenced' in components from context node
Function intersection()
Set intersection of all args, evaluated as nodesets.
nodeset intersection(nodeset, ...)
Arguments: One or more nodesets. If no args, an empty nodeset is returned.
Examples:
intersection(x/y/z, u/v/w, o/p/q)

Returns all nodes in ALL the three nodesets
intersection(., x/y/z, u/v/w)
Returns nodeset with . if . is in both x/y/z AND u/v/w, or empty nodeset if . is NOT in both x/y/z AND u/v/w.
intersection(., out[*]:component)
Returns context node if there are component-cycles from context nodeset, or empty nodeset if there is no cycles: A simple "cycles"
detector.
intersection()
Returns empty nodeset
intersection(x/y/z)
Returns x/y/z (does nothing)
Function match()
Returns boolean true if the string value of the arguments (2..N) match the regular expression given as the first argument. A submatch will
be checked (see Java java.util.regex.Matcher.find() for details).
boolean match(regexp, values...)
Properties:
regexp - Regular expression (the arg is converted to a string)
values - One or more value arg. If value is a nodeset, the string value for each node in the nodeset is matched against regexp; if non
match, false is returned. Else, value is converted to string and matched against regexp. ALL values must match the regexp if.
If 0 or 1 arg is provided, the function returns false.
Examples:
match('((\.java)|(\.cob))$', @artifact) - True if the artefact property for ALL context nodes is set and ends with .java
or .cob
match('(java)|(cobol)', component/@language) - True if the language property for ALL component outgoing nodes from
context nodes is set and contains java or cobol
match('^com\.optimyth\.', #o.getPropertyByName('class')#, in:component/@package) - True if the class for
context nodes and the package for all their incoming components starts with 'com.optimyth.'
match('anything') - False, nothing to match
match('^x +z$', 'xyyyz') - True
Function tags()
Boolean function that returns true if tags for ALL nodes in args(2..N) implies all tags in the first arg.
boolean tags(string, arg, ...)
First arg could be a string arg (that evaluates to comma-separated list of tags to be implied), or a non-empty nodeset with at least one
node, that could be an entity or property with Tags value.
args(2..N) could be nodesets of entities or property of Tags type.
NOTE: tagsA implies tagsB if tagsB contains ALL tags in tagsA.
Examples:
tags('t1,t2', .) - Returns true if context node is ApmEntity or Property of type Tags, and its tags imply 't1' and 't2' tags.
tags('t1,t2', out:component) - Return true if tags in ALL outward components implies t1 and t2 tags.
tags(@tags, out:component) - Return true if tags in ALL outward components implies tags in context node.
tags('t1,t2') - Returns false
tags() - Returns false
Function union()
Returns the union of the input args, evaluated as nodesets.
nodeset union(nodeset,...)
If an arg is an "scalar" (string, number, boolean), it is converted to a nodeset with a single node for performing the union.
AQL API
The PortolioModelQuery.jar exposes certain classes for:
1) Using AQL programmatically (for example to construct your own query logic in your Java programs).
2) Extending AQL by adding custom functions.
Using AQL in your own Java programs
The com.optimyth.apm.modelquery.AqlPath interface represents an AQL query. Typical usage is as follows:
1. Fetch the ApmModel that you will query.

2. Construct the AqlPath object from the AQL code and the ApmModel.
3. Execute one of the evaluation methods provided by AqlPath.
AQL from Java: obtaining a reusable nodeset
ApmModel model = ...;

IQueryEngine queryEngine = ApmFactory.createModelFactory().createQueryEngine();
IAqlPath expr = queryEngine.createQuery("portfolioModel//component", model);
NodeSet result = expr.execute(model);
for (Object o : result) {
... your code ...
}
...reuse your nodeset...
or, if don't need reusing the result set, and you want just to iterate once over it (like a ResultSet), you can use the more efficient
executeAsIterable method:
AQL from Java: iterate through results once
ApmModel model = ...;

IQueryEngine queryEngine = ApmFactory.createModelFactory().createQueryEngine();
IAqlPath expr = queryEngine.createQuery("portfolioModel//component", model);
Iterable<ApmEntity> result = expr.executeAsIterable(model);
for (Object o : result) {
... your code ...
}
APPMAP Dependencies Validation Language

Overview
Language Structure
ruleset
rule
pattern
subset
allow/ deny
from/ to
include/ exclude
matcher property
Examples
Rules on tags
Cycle detections
Tips for defining real-world architectures in DEPVAL
Use variables to avoid repetition in AQL queries
Layered architectures
Matching entities by name
Overview
DEPendencies VAlidation Language (DEPVAL) is a high-level declarative language for specifying checking conditions on a software
architecture. DEPVAL uses rules based on AQL to decide if entities defined in the model follow architecture compliance rules, emitting
violations when an entity in the model violates an architecture rule.
Rules are organized in groups (rulesets) that could be nested. For all entities in APPMAP model, each entity (denoted context entity in
what follows) is checked against the top-level ruleset, and violatios emitted if the rules find non-allowed dependencies from context
entity.
Language Structure
A top-level ruleset element should be defined (a ruleset may have nested rulesets and rules).
ruleset
ruleset has the following parameters:
Parameter Type Meaning Example
name string ruleset name 'architecture'
priority string One of 'fatal', 'error', 'warning', 'minor', 'info' 'error'
category string ruleset category 'sql rules'
description string explanation of the ruleset 'Avoid SQL code in presentation/business artifacts'
message string template for rendering detailed message '${rule.description}: ${source} -> ${target}'
active string true or false false
Properties priority, category, description and message are inherited from parent ruleset. In this way, you may give a value to
the ruleset and all rulesets/rules enclosed inherit the value if they do not specify any.
The default value for priority is 'info'; the default value for active is true.
message receives the following objects, that could be used in ${...} expressions:
rule, the Rule object that sent the violation to format

source, source entity
target, a NodeSet with all matched targets violating the rule
file, source codefile for source artifact
ctx, the context containing rule execution data (see JavaDoc for class
com.optimyth.apm.builder.rules.validation.model.RuleExecContext for full details)
Sample ruleset
ruleset(name: 'architecture', category: 'architecture', message: '${rule.description}: ${source}

-> ${target}') {
ruleset(name: 'crossBUchecks', severity: 'fatal', category: 'compliance') {
...
}
}
ruleset may have the following children:
ruleset (nested rulesets)

rule, to be applied for all matching
pattern, groups of elements that may be referred in {{rule}}s or {{subject}}s
subset, a filter based on a pattern. Only entities matching at least one of the subject specified will be checked by the ruleset/
rule
rule
rule has the same parameters as ruleset, plus:
checkEntity Groovy Closure Logic for check on model entities (see below)
rule may have the following children:
subset, Zero or more filters based on a pattern. Only entities matching at least one of the subject specified will be checked by
the ruleset/rule
allow/deny, sequence of "what can be done" and "what should be avoided" in logical architecture.
pattern
A pattern is a named group of entities matching certain include/exclude conditions. They typically represent a layer, a module, a
transaction, or any logical entity that could be defined using AQL predicates.
pattern has a single parameter:
name string pattern name 'backend layer'
pattern may have the following children:
include/exclude, a sequence of inclusion/exclusion filters (typically based on AQL).
Example:
// A pattern with all components of languages cobol, jcl, or java and having "datalayer" in its
name.
pattern(name:'backend layer') {
exclude(aql: ".[@type != 'component']")
include(aql: ".[@language = 'cobol' or @language = 'jcl']")
include(aql: ".[@language = 'java' and match('.*datalayer.*', @name)]")
}
pattern could be referenced in a subset, a from/to, or an include/exclude. The logical conditions expressed by the pattern will
be used in the referring element.
Pattern definitions are reachable from later references. Scope rules are similar to local variables in common
programming languages.
For example:
ruleset(name:'A') {
subset(pattern: 'P_A') // Error, P_A is not defined yet
pattern(name:'P_A')
ruleset(name: 'A.1') {
pattern(name: 'P_A.1')
rule(...) {
subset(pattern: 'P_A') // OK, references P_A pattern in A
subset(pattern: 'P_A.1') // OK, references P_A.1 pattern in A.1
...
}
}
ruleset(name: 'B') {
pattern(name:'P_A')
ruleset(name: 'B.1') {
rule(...) {
subset(pattern: 'P_A') // OK, references P_A pattern in B (NOT A)
subset(pattern: 'P_A.1') // Error, P_A.1 is not defined in B.1, B or A (rule
ancestors)
...
}
}
}
}
subset
A subset is a filter that applies to its enclosing rule or ruleset. subset may reference an existing pattern, or specify an explicit
checkEntity parameter:
pattern string pattern name 'backend layer'
checkEntity Groovy closure Code that will check its ApmEntity argument
{e ->
e.name.contains('dataaccess')}
Examples:
subset(pattern: 'backend layer')

subset(checkEntity: { e ->
return e.name.contains('dataaccess')
})
When one or more subset are placed in a rule, they are executed in sequence for the first that responds with an accept or reject
value. If first tells to accept the entity currently examined, allow/deny conditions in rule will be applied. If first tells to reject the entity,
allow/deny conditions will not be checked. If no subset match the current entity, rule is ignored.
When one or more subset are placed in a ruleset, the same behaviour is applied, so enclosed rules/rulesets will be checked if
first matching subset tells to accept the entity, else nested rules/rulesets are ignored for current entity.
allow/deny
They are conditions that typically express accepted or forbidden dependencies for currently examined entity.
allow/deny can be placed in any rule. It has no parameters, and may have optional from and to children (at most one of each).
Please note that order of allow/deny in a rule is important. If an allow condition was first matched, entity dependencies are
considered OK and the rest of the conditions are not checked. If an deny condition is matched (with no previous accept condition
matching the entity), a violation is emitted but following accept/deny are checked following the same behaviour.
Examples:
allow { from(pattern: 'ignorable') } // This could be used for ignoring entities matched by
_ignorable_ pattern
deny {
// Illegal business -> presentation dependency
from(pattern: 'business')
to(aql: "component[${PRESENTATION}]")
}
deny {
// Illegal backend -> business/presentation dependency
from(pattern: 'backend')
to(aql: "component[${PRESENTATION} or ${BUSINESS}]")
}
deny {
// Illegal presentation -> backend dependency
from(pattern: 'presentation')
to(aql: "component[${BACKEND}]")
}
from/to
Describe a dependency filter flowing from a source entity (matched from context entity in from) to a target entity (incoming or outgoing
dependencies from context entity, as specified in to).
Please note that from and to roles are conventional. to typically use AQL expressions or patterns that define outgoing
dependencies, but they could be based as well in incoming dependencies.
Parameters:
aql string AQL query

"component[${BACKEND}]"
pattern string Pattern name 'backend layer'
matcher string Matcher specification See matcher section
checkEntity Groovy closure Code that will check its ApmEntity argument
{e ->
e.name.contains('dataaccess')}
Only one of them should be specified. If not specified, nested include/exclude filters should be specified.
from/to may have the following children:

include/exclude, a sequence of inclusion/exclusion filters (typically based on AQL).
include/exclude
Basic condition for including / excluding context entity in its containing element (which could be from, to, or pattern).
These elements cannot have children.
Parameters are the same as with from/to elements.
matcher property
For simple conditions, a matcher could be specified instead of defining conditions using AQL queries or patterns.
Matchers could be specified as properties in pattern, from/to, or include/exclude elements.
Matcher Behaviour Parameters Example
namePattern Checks entity name regexp, a regular expression

include(matcher:'namePattern',
against regexp
regexp:/com\.myorg\.dataaccess\./)
propertyPattern Checks entity regexp, a regular expression;

from(matcher:'propertyPattern ',
property against property to check for
property:'businessUnit',
regexp regexp:/^marketing/)
tags Checks entity for tags, a comma-separated list of

pattern(name:'A and B',
tags tags that entity should have
matcher:'tags', tags:'A,B')
An instantiated matcher could also be assigned directly to the matcher property if desired:
include(matcher: new NamePatternMatcher(/com\.myorg\.dataaccess\./))

from(matcher: new PropertyPatternMatcher('businessUnit', /^marketing/))
pattern(name: 'A and B', matcher: new TagMatcher('A,B'))
Examples
Rules on tags
An example DEPVAL code follows:

// A sample nested ruleset based on AQL expressions
-> ${target}') {
// Checks if any component tagged CO uses any component tagged as BU-specific, which is
forbidden by architecture rules
rule(name: 'CO2CO', description: 'CO artefact calling BU-specific artefact is forbidden') {
deny {
from(aql: ".['CO' == @tags]");
// See how to ignore outgoing usages of a set of components
to(aql: "component[#!['app=MODULE,prog=IS.D'].contains(o.key)#][@tags and @tags != 'CO']")
}
}
// Checks if any BU-specific component uses any component tagged for a different BU, which is
rule(name: 'BU2sameOrCO', description: 'BU-specific artefact using other BU artefact is
forbidden') {
deny {
from(aql: ".[@tags and @tags != 'CO']");
to(aql: "\$tag = ./@tags; component[@tags and @tags != 'CO' and @tags != \$tag]")
}
}
// Checks for COPYs that are not included in any other program. Uses specific Groovy logic
(checkEntity)
rule(name: 'Unused COPY', description: 'Every COPY should have incoming deps from Cobol
programs',
message: '${rule.description}: ${source}',
checkEntity: { entity, ctx, rule ->
def progType = entity.getPropertyByName('programType').value;
if('COPY' == progType) {
// If no incoming usages from other programs: 'dead code' COPY
return null == entity.parentComponents.find{ parent -> 'program' == parent.componentType.name }
}
return false;
}
)
}
// Add other rulesets...

}
Cycle detections
Another simple example is cycle detection, like A calls> B -> ... -> A:
ruleset(name: 'cycles', category: 'architecture', message: '${rule.description}: ${source} ->

${target}') {
pattern('toCheckForCycles') {
exclude(...) // Define here which entities should be checked or ignored for cycles
include(...)
include(...)
}
rule(name: 'cycle', severity: 'warning') {

deny {
from(pattern: 'toCheckForCycles')
to(aql: ".[. in out[*]%calls:component]") // context entity is in a call path from itself
}
}
}
Tips for defining real-world architectures in DEPVAL

Use variables to avoid repetition in AQL queries
In a DEPVAL program you may define Groovy variables, and include the variables in AQL code below. This enables defining predicates
that could be used in pattern, from/to conditions, and generally in any AQL query.
For example, the AQL predicate
tags('business', in:software)
could be used to specify a logical condition that components should have, and embed that condition as part of AQL queries later, using
${...} substitution. For example:
String PRESENTATION = "tags('presentation', in:software)"

// More DEPVAL code
pattern(name: 'presentation') { include(aql: ".[${PRESENTATION}]") }
// More DEPVAL code

deny {
}
See below for a full example of this technique.
Layered architectures
Layered architectures are common in software systems. Typically components in a layer are allowed to use components in the
immediate lower layer, but other dependencies are forbidden. To check for dependencies in a layered architecture, you may define
patterns for each layer and specify deny for not allowed usages.
As an example, imagine that the model defines software entities that are tagged according to the layer they belong to. The following
DEPVAL code may detect forbidden dependencies across layers:
ruleset(name: 'architecture', severity: 'warning', message:'${rule.description}: ${source} ->
${target}' ) {
// Predicates for matching each layer. Assumes that containing software has a tag according to
its layer
String PRESENTATION = "tags('presentation', in:software)"
String BUSINESS = "tags('business', in:software)"
String BACKEND = "tags('dataAccess', in:software) or tags('host', in:software)"
pattern(name: 'component') { include(aql: ".[@type == 'component']") }

// Patterns that define the layers, using predicates above
pattern(name: 'presentation') { include(aql: ".[${PRESENTATION}]") }
pattern(name: 'business') { include(aql: ".[${BUSINESS}]") }
pattern(name: 'backend') { include(aql: ".[${BACKEND}]") }
rule(name: 'layering', description: 'A component in a layer may call only components in other
layers (or infrastructure)') {
subset(pattern:'component') // Only interested in components
deny {
}
deny {
// Illegal backend -> business/presentation dependency
from(pattern: 'backend')
to(aql: "component[${PRESENTATION} or ${BUSINESS}]")
}
deny {
// Illegal presentation -> backend dependency
from(pattern: 'presentation')
to(aql: "component[${BACKEND}]")
}
}
}
Matching entities by name
It is common practice to use, in artifacts implemented in object-oriented languages, to use namespaces for qualifying the artifact in
business or technical groups. For example, in Java the package could be used like this:
com.myorg.unit.* for business unit unit.

com.myorg.module.* for logical module module.
In other languages, like Cobol, other naming conventions could be used in program name to classify the artifact. Rules may be encoded
following the particular naming conventions obeyed by software artifacts.
You may use matchers (e.g. namePattern) for defining filters based on entity names:
pattern(name: 'data access', matcher: 'namePattern', regexp: /^com\.myorg\.dao\./)
AIM - Propagation Analysis
Propagation analysis
Analyzing software dependencies

Script
Local execution
Remote execution
Rules
Propagation Analysis API
Appendix: Propagation Analysis Program syntax
Main structure
Macros
Conditions and propagations (filters)
Actions
Example 1: Dead code
Example 2: Tagging
Example 3: Architecture Validation
Analyzing software dependencies
Once the software map is build (an AIM model is produced after analyzing software artifacts), it could be analyzed under different usage
scenarios:
Dead (Unused) Code Detection. Software has certain 'entry points' (programs executed, initial transactions, batch jobs, web
application front-end elements, input web services...) that are called from the external world. Such 'entry points' (starters set in
propagation analysis terms) have outgoing dependencies that reference other software entities (outgoing dependencies on other
entities make the target entities as used from a static point of view). The set of entities reached transitively by outward dependencies
propagated from starters is named propagated set. An entity in the software of interest is considered potential 'dead code' if it is
neither in the starters set nor in the propagated set.
Classification of model entities. If you want to partition the entities in the software map following certain criteria (like technology,
platform, business / functional area, etc., potential classification criteria could be almost anything), it could be possible to start from a
set of entities where that classification is known (starters set), and then propagate the classification using the dependencies in the
map to other related entities (propagated set). Mapping each entity (in either the starters or the propagated set) to the proper
"logical" group could be done by tagging (e.g. setting a tag value, or an entity property with the name of the logical group where each
classified entity belongs). That way, the tag could be used later in AQL searches to find the components that belong to a certain
"logical" group.
Dependencies validation. Certain kind of entities in software must obey certain (architectural or design) norms that limit the type of
allowed dependencies in software. If a software map is built, that architecture / design norms (either positive i.e. "what is allowed", or
negative i.e. "what is forbidden") could be also checked by looking if certain software entities (propagated set) in the model are
reached from certain source entities (starters set). That means that e.g. entities in the starters set have dependencies "banned" by
certain architecture / design norms.
The examples above all follow the same pattern:
Different instances of starter sets are found in the model.

From each one of the instances sets, differente propagation conditions are evaluated, that will traverse the dependencies graph to
reach the propagated set.
When building either each one of the starter sets, or after navigating to the dependent propagated set, certain actions could be done
(e.g. reporting a normative violation, setting properties or tags in the entity processed according to the classification scheme, etc.)
At the end of the analysis, other actions could be done (e.g. reporting entities of interest neither in any of the starter set nor in any of
the related propagated sets as "unused").
This is named Propagation Analysis. AIM enable propagation analysis with the following interfaces:
(Java) API
Command-line script: either aim-propagation.xml or Propagation.xml for launching propagation program either in the
checKing host, or remotely via Query Service.
Model builder rules (like DeadCodeRule}) or {{TaggingRule that launch the configured propagation program.
You may write your own propagation analysis programs where filters for starters and propagated entities from starters are declared.
Additionally, you may specify actions (like setting a property or a tag value) that will apply either to the starter entities, propagated
entities, or both. You may use the sample programs provided under PLUGINDIR/scripts/propagation as initial examples that you
may extend to fit your particular needs.
Once the propagation analysis program is built, you may execute it using any of the available interfaces, as shown below.
Script
Local execution
To execute a propagation analysis over an AIM model, the aim-propagation.xml Ant script (located under APPMAP plugin's
scripts directory) could be launched from command-line (locally, in checKing host).
The model should not be opened by AIM QueryService. This "local" script is intended to be executed immediately after
model building, and before other clients access the model. Use the remote script instead if the model could be opened
by Query Service when the script is about to be launched.
Syntax:
ant -f aim-propagation.xml TARGET

-Dprogram=PROGRAM_FILE -Dmodel=MODEL
[-Dreport.file=REPORT_FILE] [-Dreport.format=FORMAT] [-D_TARGET_.report.template=TEMPLATE]
(As usual, [ ... ] represents an optional value).
Where:
TARGET is the type of analysis to perform. Available values are:

deadcode: Dead (unused) code detection.
tagging: Tags propagation (for classification of model entities).
validation: Architecture validation (detect not allowed dependencies).
log: Logs the starters and reached entities from starters. Useful for debugging propagation programs.
PROGRAM_FILE is the descriptor for the analysis program to execute (XML file). Loaded as a resource from script classpath, or
relative to the script directory. Use URL format (file:... or classpath:...) formats for forcing the resource to be resolved from either
filesystem or classpath, respectively.
MODEL is the relative path to the AIM model to analyze (e.g. /MyProject/MyModel).
REPORT_FILE specifies where to dump the analysis results. Could be an absolute path, a relative path (relative to current
directory), or "--" (default) for standard output.
REPORT_FORMAT is one of text, csv, xml, template or none.
text (default for deadcode): Dumps results as plain text.
xml: Dumps results in structured XML format, if you need to later process the results.
csv: Dumps results in comma-separated values format.
template: Uses a groovy template for rendering the report. TEMPLATE resource will be used if provided, else the default
template is used.
none (default for tagging): No report is rendered.
Note: Executing deadcode analysis with none report format will not render the unused components anywhere.
Examples:
Detects dead code and generates a CSV report on given file, with the given properties:
ant -f aim-propagation.xml deadcode -Dprogram=propagation/DeadCode.xml -Dmodel=/MyPrj/MyModel

-Dreport.format=csv "-Ddeadcode.report.csv.properties=name,type,subType,artifacts"
Please note that default properties in the aim-propagation.properties could be overridden from command-line parameters, as
shown above with deadcode.report.csv.properties.
Tags model entities according to the given propagation rules, and dump to MyModel_Tags.txt report file:
ant -f aim-propagation.xml tagging -Dprogram=propagation/Tagging.xml -Dmodel=/MyPrj/MyModel

-Dreport.format=text -Dreport.file=MyModel_Tags.txt
Validate architecture norms by analyzing illegal dependencies (with tags on the source entities showing illegal outward dependencies):
ant -f aim-propagation.xml validation -Dprogram=propagation/ArchitectureValidation.xml -Dmodel=/MyPrj/MyModel

-Dreport.format=text -Dreport.file=MyModel_Violations.txt "-Dvalidation.tagPrefix=violation:"
Debug the propagation rules in program. Entities reached (as starters or propagated) are displayed in the script output (standard output
in the example).
ant -f aim-propagation.xml log -Dprogram=classpath:MyProgram.xml -Dmodel=/MyPrj/MyModel
Sample propagation programs for these usages could be found in the PLUGINDIR/scripts/propagation directory.
Script default properties is found in the aim-propagation.properties file, located in the

CHECKING_DATA/config/plugins/APPMAP directory. You may change the listed properties there:
Default aim-propagation.properties
# Report format (one of text, xml, csv or template)

report.format=text
# Encoding for generating the output file

encoding=UTF-8
# --------------------------------
# Dead-code analysis configuration
# --------------------------------
# If true, dead-code analysis will only check entities in the software layer (portfolio model)
# If false, dead-code analysis will check any model entity
deadcode.onlyCheckSoftwareEntities=true
# Properties to render in CSV dead-code output

deadcode.report.csv.properties=key,name,type,subType,tags,artifacts
# If true, cells in CSV are quoted (set to true if any property value may contain the CSV field
separator character)
# If false, no value is quoted
deadcode.report.csv.quoted=true
# Groovy code to render each of the reported unused entities

deadcode.report.text.code=o.toString()
# Default groovy template resource (when report.format=template)

deadcode.report.template=
# If set, unused entities are given this tag value

deadcode.tag=
# ------------------------------
# Tagging analysis configuration
# ------------------------------
# Properties to render in CSV tagging output

tagging.report.csv.properties=key,name,type,subType,tags,artifacts
# If true, cells in CSV are quoted (set to true if any property value may contain the CSV field
tagging.report.csv.quoted=true
# Groovy code to render each of the tagged entities

tagging.report.text.code=o.toString() + ': ' + o.tags?.join(',') ?: ''

tagging.report.template=
# ----------------------------------------------
# Dependencies validation analysis configuration
# ----------------------------------------------
# Properties to render in CSV tagging output

validation.report.csv.properties=rule,starter,propagator,source.key,source.name,source.type,source.subType,targe
If true, cells in CSV are quoted (set to true if any property value may contain the CSV field
validation.report.csv.quoted=true

validation.report.template=
# If set, sources of illegal dependencies are tagged, using this prefix concatenated with the
propagation key.
validation.tagPrefix=
Remote execution
The Propagation.xml script, located under APPMAP plugin's scripts/remoteScripts directory or in the distribution media, could
be used for execution propagation analysis in a remote node (not necessarily the checKing host). It uses Query Service to launch the
analysis, the result report could be dumped in standard output or in a report file.
Usage:
ant -f Propagation.xml OPERATION -Dmodel=MODEL -Dprogram=PROGRAM

[-Dreport=REPORT_FILE] [-Dreport.format=REPORT_FORMAT] [-Dreport.properties=CSV_PROPS]
[-DrenderCode=RENDERCODE] [-Dtemplate.OPERATION=TEMPLATE] [-Dtag=TAG]
Where:
OPERATION: Analysis to perform. one of deadcode, tagging, validation or log.

MODEL: Model relative location path (e.g. /MyProject/MyModel).
PROGRAM: location of propagation program, resolved at server-side (e.g. propagation/DeadCode.xml).
REPORT_FILE: Local filename to store analysis results. Use – for standard output (default).
REPORT_FORMAT: Report format, one of text, csv, xml, template or none (default: text).
RENDER_CODE: Groovy code for customizing how entities are dumpled (when REPORT_TYPE=text).
TEMPLATE: Path to the groovy template to use (server-side) when REPORT_TYPE=template.
TAG: Tag (for deadcode) or tag prefix (for validation) to use for markup of entities of interest.
Edit configuration file AimScript.properties for default properties (connection url, templates, etc.).
Such properties could be provided also via command-line properties (-Dprop=value).
Examples:
Find dead code using the propagation/DeadCode.xml propagation analysis (in server-side, using classpath).
Report the results in a CSV file, and mark each unused component in model with the DEADCODE tag:
ant -f Propagation.xml deadcode -Dmodel=/MyPrj/MyModel -Dprogram=classpath:propagation/DeadCode.xml

-Dreport=deadCode.csv -Dreport.format=csv -Dtag=DEADCODE
Find entities with outgoing illegal dependencies, according to the propagation/ArchitectureValidation.xml program:
ant -f Propagation.xml validation -Dmodel=/MyPrj/MyModel -Dprogram=propagation/ArchitectureValidation.xml
Tag entities according to the propagation/Tagging.xml program:
ant -f Propagation.xml tagging -Dmodel=/MyPrj/MyModel -Dprogram=propagation/ArchitectureValidation.xml
Dump entities in starter and propagated sets for each rule, for debugging rule definitions:
ant -f Propagation.xml log -Dmodel=/MyPrj/MyModel -Dprogram=MyProgramToDebug.xml
Rules
There are two builder rules provided, that could be added to a builder configuration:
Rule Classname Purpose
DeadCodeRule com.optimyth.aim.propagation.rule.DeadCodeRule Detects dead code based on the configured propagation

program. Dead code elements could be marked as such in the
model (with a configured tag) and/or reported to an external
report
TaggingRule com.optimyth.aim.propagation.rule.TaggingRule Applies tags to entities in AIM model following a propagation

analysis program. Tagging criteria is typically coded in
propagation rules, with actual tagging operations in action blocks
matching specific starter/propagation.
ValidationRule com.optimyth.aim.propagation.rule.ValidationRule Considers each related starter and propagated entities as

"illegal" dependencies that are reported (optionally, the starter is
tagged if tagPrexix property is set)
Full documentation could be found in the AIM Rules API or in the rules JavaDoc.
A Java API is provided, in order to use propagation analysis in AIM custom extensions. See Propagation Analysis API for details on how
to use this API.
Appendix: Propagation Analysis Program syntax
Main structure
Each propagation analysis is coded in an XML file with the following structure:
<program name=''>
<macros>
<macro name='MACRO'>VALUE</macro>
...
<macros>
<starterCondition>
CONDITION
</starterCondition>
<rules>
<rule name=''>
<starter name=''>
<filter>EXPR</filter>
<propagation name=''>PROPAGATION_EX</propagation>
</starter>
...
</rule>
...
</rules>
<checkCondition>
CONDITION
</checkCondition>
<actions>
<actionBlock name=''>
<match pattern='' on='starter|propagation|all'>
OPERATION
</match>
</actionBlock>
</actions>
</program>
The full syntax could be seen in the PLUGIN_DIR/scripts/resources/PropagationProgram.dtd. You may use this DTD
file in your favourite XML Editor to help creating your own propagation analysis programs with the right syntax.
The propagation analysis engine will execute each rule starter's (<starter> elements in sequence, as they appear in the program). For
each starter it will fetch matched model entities, applying the actions that match the rule and starter, notifying each registered listener
(here is where the starters could be remembered or processed elsewhere according to the target usage of the propagation analysis),
and then each starter's <propagation> is executed using the matched starters set as relative context. For each element in the
propagated set computed, actions are executed (if any) and the analysis listener is notified.
Please note that when using AQL, filter in <starter> use typically absolute AQL expressions (like //component[PREDICATE]), while
filter in <propagation> use typically relative AQL expressions (like out[*]:component).
Most of the items have an active attribute (with true or false values) that could be used to deactivate the element.
This way you may activate/deactivate a rule, an actionBlock, a starter etc. selectively.
Macros
In the <macros> block, substitution macros are defined. They are replaced in other parts of the propagation analysis descriptor using the
${MACRONAME} reference. Use macros for values that may change between executions to ease maintenance of the propagation
program.
Examples:
<macros>
<macro name='MODULES'>'App1', 'App2'</macro>
<macro name='COND_ACTIVE' value='true'/>
<macro name='MODULES_FILTER'>//software[#o.name in [${MODULES}]#]</macro>
...
</macros>
...

<condition type='groovy' active='${COND_ACTIVE}'>o.software?.name in [${MODULES}]</condition>
Please note that a macro could have in its value another previous macro substituted.
Conditions and propagations (filters)
A condition match a single entity under certain criteria. Conditions appear in <starterCondition> and <checkCondition>.
An atomic condition (<condition> element). Conditions could be composed by boolean connectors (and, or and not) to form a composed
condition.
An atomic condition has the following syntax (first option for enumerated attributes is the default):
<condition active='true|false' id='ID' ref='REF'

type='groovy|aql|byType|byKey|byName|byProperty|inDatabase'
value='VALUE' resource='RESOURCE' caseSensitive='false|true'
property='PROPNAME'>VALUE</condition>
All attributes are optional, except one of VALUE or RESOURCE that should be provided.
The following condition types are supported:
groovy: VALUE is a Groovy expression using 'o' as the variable that contains the AIM entity to check.
aql: VALUE is an AQL expression, relative to the entity to check (example:
.[in:software[match('pattern', @name)]]
).
byType: VALUE is the comma-separated list of types / subtypes accepted.

byName: VALUE is the comma-separated list of entity names accepted.
byProperty: VALUE is the comma-separated list of property values accepted. property attribute contains the name of the property
to check.
inDatabase: VALUE is the comma-separated list of DATABASE.SCHEMA patterns (use * as wildcard for database or schema).
Examples:
<and>

<condition id='app_filter' active='true'>o.software?.name in [${MODULES}]</condition>

<not><condition type='byName'>${IGNORE}</condition></not>
</and>
...
<or>
<and>
<condition ref='app_filter'/>
<condition type='byType'>${APP_TYPES_TO_CHECK}</condition>
</and>
<and active='true'>
<condition type='byType'>${DB_TYPES_TO_CHECK}</condition>
<condition type='inDatabase' caseSensitive='true'>${SCHEMAS_TO_CHECK}</condition>
</and>
</or>
A filter navigates from a certain context (the full model in the <starter> filter, or the starter set in the <propagation>) to find a set of model
entities matching certain conditions. A <propagation> element is essentially a filter that builds the propagated set from the starters set.
Syntax:
<filter
id='ID' ref='REF'
type='aql|groovy|byType|byKey|byName|byProperty'
description='DESCR' value='VALUE' resource='RESOURCE'
caseSensitive='false|true' property='PROPNAME'>VALUE</filter>
<propagation name='NAME' onEach='false|true' active='true|false'

type='aql|groovy|byType|byKey|byName|byProperty'
description='DESCR' value='VALUE' resource='RESOURCE'
caseSensitive='false|true' property='PROPNAME'>VALUE</propagation>
Note: Typically, starter filters and propagation filters use AQL. It is recommended to use AQL whenever possible, particularly in starter
filters, as the other filters must iterate on all model entities.
Actions
When a single model entity is found as starter, or propagated from starters, in one rule starter, the registered actions are executed on
that entity.
The optional <actions> element contain zero or more <actionBlock> (with active flag). Each <actionBlock> has zero or more <match>
subelements. Each <match> element (also with optional active flag) could have zero or more actions.
When the current rule / starter / propagation names match the <match> pattern and on attributes, the contained actions in the
<match> element are executed. pattern is a regular expression for checking the current propagation (
ruleName.starterName[.propagationName]) and on could be starter, propagated or all for matching entities in the starter or
propagated sets, or both cases.
Current actions implemented and supported in the XML are:
Element Effect Attributes Example
<addTag> Adds a single tag to active, type, <addTag type='dynamic'>'businessArea:' +

entity value ctx.starter.name</addTag>
<deleteTag> Removes a tag or active, type, <deleteTag pattern='businessArea:.*' />

tags value, pattern
<setProperty> Sets entity property active, property, <setProperty property='businessArea' type='dynamic'

type, value value='ctx.starter.name'/>
<deleteProperty> Removes entity active, property <deleteProperty property='businessArea'/>

property
<action> User-defined action, active, class <action class='ACTION.CLASS.NAME'>OPTIONAL CONFIG

by classname TEXT PASSED TO CONSTRUCTOR</action>
Note: Value could be coded either in a value attribute, or as text in the action element.
Actions have a type flag with two possibilities: fixed (the default) so the action value is taken as a literal, or dynamic so the action
value is considered a Groovy expression that will be executed to compute the value for the action.
Example 1: Dead code
First example is a simple dead code detection. Finds typical software 'entry points', and follow from them dependencies that mark
reached entities as used. At the end, entities of interest that are not reachable from the entry points are reported as "dead" (unused)
code.
<program name='DeadCode'>
<macros>
<macro name='MODULES'>'/ArchitectureViolations'</macro>
<macro name='NORMAL_PROPAGATION'>out[*]:component</macro>
<macro name='CLASS_PROPAGATION'>
out[*]:component |
in[*]%inherits:class/out[*]:component |
out[*]:component/in[*]%inherits:class/out[*]:component
</macro>
<macro name='APP_TYPES_TO_CHECK'>class,program,element,operation</macro>
<macro name='DB_TYPES_TO_CHECK'>table,view,sequence,storedProcedure,function</macro>
<macro name='SCHEMAS_TO_CHECK'>ArchitectureViolationsDB.*</macro>
</macros>
<starterCondition>
<description>Global filter that affects to every starter condition</description>
<condition id='app_filter' type='groovy'>o.software?.name in [${MODULES}]</condition>
</starterCondition>
<rules>
<rule name='j2ee'>
<starter name='ejb'>
<description>Any component used from an EJB's implementation class is used</description>
<filter>$var = //element[@j2eeType='ejb']; $var | $var/in:class</filter>
<propagation name='used from implementation class' active='true
'>${CLASS_PROPAGATION}</propagation>
</starter>
<starter name='webXml'>
<description>Any component used from J2EE elements (servlets, filters,
listeners)</description>
<filter>//configuration[@j2eeType='web.descriptor']/(class,element,page)</filter>
<propagation name='used from implementation class' active='true
'>${CLASS_PROPAGATION}</propagation>
</starter>
</rule>
<rule name='webService'>
<starter name='webService'>
<description>Anything used from a web service is used</description>
<filter>//webService</filter>
<propagation>${CLASS_PROPAGATION}</propagation>
</starter>
<starter name='webService operations'>
<description>Anything used from a web service operation is used</description>
<filter>//webService/operation</filter>
</starter>
</rule>
<rule name='host'>
<starter name='jcl'>
<description>JCLs are considered entry-points here</description>
<filter>//program[@language='jcl' and @programType='script']</filter>
<propagation>${NORMAL_PROPAGATION}</propagation>
</starter>
</rule>
<rule name='customStarters' active='false'>

<starter name='starterPrograms'>
<filter type='byName' resource='starterPrograms.list'/>
<propagation>${NORMAL_PROPAGATION}</propagation>
</starter>
<starter name='starterClasses'>
<filter type='byName' resource='starterClasses.list'/>
</starter>
</rule>
</rules>
<checkCondition>
<description>Which components in model to check for usages</description>
<or>
<and>
<condition ref='app_filter'/>
<condition type='byType'>${APP_TYPES_TO_CHECK}</condition>
</and>
<and>
<condition type='byType'>${DB_TYPES_TO_CHECK}</condition>
<condition type='inDatabase' caseSensitive='true'>${SCHEMAS_TO_CHECK}</condition>
</and>
</or>
</checkCondition>
</program>
Please note above the CLASS_PROPAGATION AQL traverse expression. Due to polymorphism in O-O languages, a
client class may reference another class using an interface, not the real implementation class. The client class may
receive a reference on the implementation to use via e.g. inversion-of-control (IoC) framework (Spring is a common
example of this IoC frameworks). This design pattern ("refer to interfaces, not to implementations") complicates
dead-code detection, as the implementation class may be used by another "client" class but there are no references to
the runtime implementation class in the client code. With IoC or certain object factories that dependencies on
implementation classes are hidden (this is one of the goals for IoC !). For dead-code analysis, it is conservative to
examine outward dependencies on subclasses that extend / implement a used interface or abstract class.
This shows how difficult may result traversing potential usages in software.
Example 2: Tagging
The following is an example of propagation analysis for:
Classification of software entities (applications) according to the technology of the components they contain.
Classification of software entities into functional areas, and propagating the functional area to the contained components.
<program name='Tagging'>
<description>
Tagging propagation program example. You may define your own tagging rules
following the sample rules below.
</description>
<macros>

<macro name='APPS_TYPE_1'>'/ArchitectureViolations', 'app2', 'app3'</macro>
<macro name='APPS_TYPE_2'>'app4', 'app5'</macro>
<macro name='HOST_LANGUAGES'>'cobol','jcl','cl400','natural'</macro>
</macros>

<rules>
<rule name='cleanup' active='true'>
<description>Trick: for cleaning previous businessArea and technology tags</description>
<starter name='cleanup'><filter>//software | //component</filter></starter>
</rule>
<rule name='businessArea' active='true'>

<description>Classify applications by name, and propagate tag to contained
components</description>
<starter name='TYPE_1'>
<filter>//application[#o.name in [${APPS_TYPE_1}]#]</filter>
<propagation>component</propagation>
</starter>
<starter name='TYPE_2'>
<filter>//application[#o.name in [${APPS_TYPE_2}]#]</filter>
<propagation>component</propagation>
</starter>

</rule>
<rule name='technology'>
<description>Classify applications according to the technology it contains</description>
<starter name='java'><filter>//component[@language='java']</filter>
<propagation>in:software</propagation>
</starter>
<starter name='j2ee'><filter>//component[not empty(@j2eeType)]</filter>

</starter>
<starter name='spring'><filter>//component[not empty(@springType)]</filter>

</starter>
<starter name='dotnet'><filter>//component[@language='csharp' or
@language='vbnet']</filter>
</starter>
<starter name='aspnet'><filter>//component[not empty(@aspnetType)]</filter>

</starter>
<starter name='host'><filter>//component[#o.language in [${HOST_LANGUAGES}]#]</filter>

</starter>

</rule>
</rules>
<actions>
<actionBlock name='classify software' active='true'>
<match pattern='cleanup.cleanup' on='starter' active='true'>
<deleteTag pattern='businessArea:.*' />
<deleteTag pattern='technology:.*' />
</match>
<match pattern='businessArea.*' on='all' active='true'>

<description>Rule starter name as tag value, on starter (software) and propagated (its
components)</description>
<addTag type='dynamic'>'businessArea:' + ctx.starter.name</addTag>
<setProperty property='businessArea' type='dynamic' value='ctx.starter.name'/>
</match>
<match pattern='technology.*' on='propagated' active='true'>

<description>Use the rule starter name as tag value on the propagated (containing
software)</description>
<addTag type='dynamic'>'technology:' + ctx.starter.name</addTag>
</match>
</actionBlock>
</actions>
</program>
The effect of the program is to give a businessArea:AREA tag to each software (and contained components) according to software
name, and a technnology:TECH tag / property to each software based on the type of components it contains.
Remember that rules are executed in sequence, and for each rule all propagation is done before processing the next
rule. The first cleanup.cleanup starter (and matching <match pattern='cleanup.cleanup' on='starter'>) are used to
removing tags and properties that will be recalculated later in the rest of the rules.
Example 3: Architecture Validation
Imagine that, in a software system, there is a "layered architecture" divided in three layers: front-end, service and data access. The
architecture norms state that each component in a layer can only use components in the immediate lower layer. So front-end cannot
access data access, service cannot access front-end, and data access cannot access neither service nor front-end.
The dependencies in the AIM model could be examined following the above norms using this simple propagation program:
<program name="ArchitectureValidation">
<description>
Sample architecture norms that define illegal dependencies that should not appear in AIM
model.
At the end, detected illegal dependencies are reported. Additionally, illegal
dependencies could be marked in the model (property validation.tagPrefix).
</description>
<macros>
<macro name="PKG_BASE" value="com.optimyth.myapp."/>
<macro name="PKG_DAO" value="${PKG_BASE}dao."/>
<macro name="PKG_SERVICE" value="${PKG_BASE}service."/>
<macro name="layer.frontEnd">//page | //component[@j2eeType='servlet']</macro>

<macro name="layer.service">//class[ match('${PKG_SERVICE}', @name) ]</macro>
<macro name="layer.dataAccess">//class[ match('${PKG_DAO}', @name) ]</macro>
<macro name="usage.frontEnd">page | component[@j2eeType='servlet']</macro>

<macro name="usage.service">class[ match('${PKG_SERVICE}', @name) ]</macro>
<macro name="usage.dataAccess">component[ not empty(@sqlType) ] | class[ match('${PKG_DAO}',
@name) ]</macro>
</macros>
<rules>

<rule name="layering">
<description>Describe illegal dependencies in the 3-level layer model</description>
<starter name="frontEnd">
<filter>${layer.frontEnd}</filter>
<propagation onEach="true" name="dataAccess" description="Illegal frontEnd -> dataAccess"
>
${usage.dataAccess}
</propagation>
</starter>
<starter name="service">
<filter>${layer.service}</filter>
<propagation onEach="true" name="frontEnd" description="Illegal service -> frontEnd">
${usage.frontEnd}
</propagation>
</starter>
<starter name="dataAccess">
<filter>${layer.dataAccess}</filter>
<propagation onEach="true" name="frontEnd" description="Illegal dataAccess -> frontEnd">
${usage.frontEnd}
</propagation>
<propagation onEach="true" name="service" description="Illegal dataAccess -> service">
${usage.service}
</propagation>
</starter>
</rule>
</rules>
</program>
AIM Access Control
How does AIM access control apply?
AIM access control applied to data from models that a user can view.
Groups of resources that contain access to components have been defined, and subsequently, these groups of resources will be
allocated to users.
Users with administrator role will have full access to data of the different models regardless of whether the user has permissions
assigned or not.
Access control model
To activate the access control is mandatory to set qs.activeAccessControl property from file
$CHECKING_DATA/config/plugins/APPMAP/appmap.user.properties to true. (Properties updated into this file require restarting the
server)
There are two possibilities to use the access control: by xml or web and database. This configuration is through the property
qs.typeAccessControl with two possibles values: xml or web. If the configuration is by xml, all operations in web will be ignored, and if
the configuration is by web all xml files are ignored.
Configuration by xml
There are two access control model configuration files:
aim.access.control.groups.xml
aim.access.control.users.xml
File aim.access.control.groups.xml
The aim.access.control.groups.xml file contains the configuration of the different groups of resources as well as global access control
settings. This file contains the following sections:
Tag default: Default value for users who are not in the configuration. Possible values are "all" or "nothing". "all" indicates that the
user will have full access to the model data and "nothing" indicates that the user will not have access to any data.
Tag allowedproperties: contains properties that will be visible from the elements to which a user does not have access (Properties
recid, name and dn always be visible).
Tag predicate: Indicates types and subtypes which will be considered for entities which will be accessed, i.e. these are the entities
from where the access will be given. An user will have access to entities that meet the corresponding aql is also a type or subtype of
those indicated in this property, the user will also have access to all the sons of these entities.
Tag groups: will have a list of groups, each of them with its configuration.
The configuration of each group is as follows:

Each group will have three sections:
Tag name: Identifies the Group and also gives a name.

Tag aql: Query aql to be performed on each model to retrieve the ids that the group gives access.
Tag models: Patterns of names of model that applies to the group. In case of this value is null, will apply to all models.
<access>
<default>all</default>

<allowedproperties></allowedproperties>

<predicate>
<types>...</types>
<subtypes>...</subtypes>
</predicate>

<groups>
<group>
<name></name>
<aql><![CDATA[ ]]></aql>
<models/>
</group>
<group>
...
</group>
...
<group>
...
</group>
</groups>
</access>
File aim.access.control.users.xml
The aim.access.control.users.xml file contains the relationship between users and groups. This file contains a list of users identified by
the checking login and each of them has a list of resource groups.
This relationship will be that give each user depending on the groups that have access.
<access>

<users>
<user>
<id></id> 
<groups>
<group></group>
</groups>
</user>
<user>
...
</user>
...
<user>
...
</user>
</users>
</access>
Data visualization
Users who do not have full access to the model you are referring to will be dependencies between nodes if they have access, and nodes
which do not have access but the latter will not have all properties that have normally.
Properties that have the node that the user does not have access will be configurable with the exception of id, dn and name that will
always be visible.
Users who have access control may not download the appropriate model.
Access control settings
The xml files described above must be placed into sub-directories of:
$CHEKING_DATA/config/projectfiles
Configuration files that apply to each model are that they are following the structure of directories ascending from the directory of the
project until a configuration file is either reach the directory $CHEKING_DATA/config/projectfiles. In the event that there is no
configuration files, all users will have full access to the data of the models.
Users with administrator role will have full access to the data of the different models regardless of whether the user has
permissions assigned or not.
An example of access configuration file is as follows:

aim.access.control.groups.xml
<access>
<default>all</default>

<allowproperties></allowproperties>

<predicate>
<types>software</types>
<subtypes>databaseInstance</subtypes>
</predicate>


<groups>
<group>
<name>GROUP_1</name>
<aql><![CDATA[ //software[ match(".* QA", @name)] ]]></aql>
<models/>
</group>
<group>
<aql><![CDATA[ //component[ match(".*MA", @name) or match(".*_DB", @name)] ]]></aql>
<models> 
<model>Pr1/model1</model>
</models>
</group>
<group>
<aql><![CDATA[ //component[ match(".*MA", @name) or match(".*_DB", @name)] ]]></aql>
<models> 
<model>.*pru</model>
</models>
</group>
</groups>
</access>
aim.access.control.users.xml
<access>

<users>
<user>
<id>user1</id> 
<groups>
<group>GROUP_1</group>
</groups>
</user>
<user>
<groups>
</groups>
</user>
<user>
<groups/>
</user>
</users>
</access>
Configuration by web
With this configuration there are use the administration web.
To access the web administration you have to go to the tab plugins, select the APPMAP plugin and, subsequently, press the button "
Configuration".
In this panel there are a button "Adminstration".
For access to the administration of AIM access control you have to press this button. When press this button a new window will be
shown with the next interface:
There are two tabs: the first tab contains the access of the user by groups. and the second tab is the administration of groups.
Manage groups
To manage the groups must press in tab Access groups and show next interface:
In this tab you can filter, add, modify or remove groups.
Add group
To add a group you have to press the button "Add" and will be displayed the next panel:
The fields in this panel are:
Project: Project of the group. All child projects of this project that have not associated a group apply this group.
Access for users without this group: For all or users that have not associated to this group will have access to all or nothing
depends on the selection.
Name: Name of the group.
Description: Description of the group.
AQL: AQL to identify components to access. This components will be software or databaseInstance components.
Models of the group: In this section affected models by the group are specified being able to put regular expressions for example
.*/Model_.*
For add models to the group, you have to fill the text field and press the icon plus.
To choose the project and model, there is a folder icon. Click on one of them, a tree panel will be shown to choose a project or model.
To complete this action you must press the button "Save".
Modify group
To modify a group you must select the group in datatable and press the button "Modify". This action will showed the same panel that add
a group but with the fields filled.
Delete group
To delete any group you must select one or more groups and press the button "Delete". If there are user associated to any group will
showed a message with this information. If you press yes groups will be deleted and if you press "No" the action will be cancelled.
Manage user groups
To manage user groups you must select tab User access.
In the left part there are a tree of users by role. To admin user access you must select any user in this tree.
When you select any user the table will be loaded with the groups of this user.
Add groups to user
To add groups to user you must press the button "Add" and will showed the panel with the available groups:
To add groups you must select the groups in datatable and press "Add".
Delete user groups
To delete user groups you must select the groups to remove and press the button "Delete".
AIM Access Control XML-RPC
AIM Access Control XML-RPC
To modify groups and users group by xmlrpc aim has next interface to this.
Activation of the XML-RPC services
The XML-RPC services are disabled by default.
To activate, go to admin (you must be logged as administrator), and in the configuration tab, set the xmlrpc.active property to true:
Service description
Delete all groups
delete all groups
Purpose: Delete all groups and his relations.

Endpoint: http:// checkingserver:port/appContext/pluginweb/APPMAP/xmlrpc/accessControl.pluginweb.deleteAllGroups
Methods:
parameters type description
token auth token (string) token of authorization
return value: true if all ok or false in other case
Delete all groups
delete all user groups
Purpose: Delete all relations with user and groups.

Endpoint: http:// checkingserver:port/appContext
/pluginweb/APPMAP/xmlrpc/accessControl.pluginweb.deleteAllUserGroups
Methods:
Add group
add group
Purpose: Add group.

Endpoint: http:// checkingserver:port/appContext/pluginweb/APPMAP/xmlrpc/accessControl.pluginweb.addGroup
Methods:
groupData groupData (Hashtable) Group data
Group data must contain:
attribute description
name Name of group
project Project of the group
defaultValue Default value for the group: all or nothing
description Description for the group
aql AQL for the group
Add user group
add user group
Purpose: Add relation with user and group

Endpoint: http:// checkingserver:port/appContext/pluginweb/APPMAP/xmlrpc/accessControl.pluginweb.addUserGroup
Methods:
user user (String) Users login
groupName groupName (String) Groups name
Add model group

add model group
Purpose: Add relation with model and group

Endpoint: http:// checkingserver:port/appContext/pluginweb/APPMAP/xmlrpc/accessControl.pluginweb.addModelGroup
Methods:
model model (String) Model or pattern
groupName groupName (String) Groups name
Executing by ANT
To execute by ant there are next targets in the file webapp\WEB-INF\plugins\plugin-APPMAP\scripts\xmlrpc\AccessControlService.xml.
targets
target name parameters description
deleteAllGroups N/A Delete all groups
deleteAllUserGroups N/A Delete all user

groups
addGroup name (name of group), project (Project of group), defaultValue (Default value: all or Add group to
nothing), description (Description of group), aql (AQL of group) batabase
addUserGroup userLogin (Login of user), group (name of group ) Add relation

between user and
group
addModelGroup model (Model), name (name of group ) Add relation

between user and
group
Examples:
ant -f AccessControlService.xml deleteAllGroups

ant -f AccessControlService.xml deleteAllUserGroups
ant -f AccessControlService.xml addGroup -Dname=GROUP_NAME -Dproject=/project -DdefaultValue=all -Ddescription=Description
-Daql="//sofware[@name = 'soft']"
ant -f AccessControlService.xml addUserGroup -DuserLogin=administrator -Dgroup=GROUP_NAME
ant -f AccessControlService.xml addModelGroup -Dmodel=model -Dname=GROUP_NAME
checking AIM Architecture

Elements
Elements
Application Inventory Management (AIM) tool is composed by the following elements:
APPMAP plugin. A plugin deployable in a ChecKing system, containing all the elements needed for software inventory operations.
Include scripts for model building and configuration discovery, among others.
AIM Query Service. A centralized query service that the APPMAP plugin starts during plugin initialization. This service opens two
TCP ports, a management port and a service port. Clients and administrative points use those ports to communicate with the Query
Service.
AIM - Application map Browser, end-user graphical console for operations on AIM models. The browser connects to AIM Query
Service, but it could operate in "disconnected mode" and open AIM models stored in local filesystem.
AIM - Scripting, a set of scripts and libraries for connecting with AIM Query Service and performing operations on the application
inventory models.
The following image shows the top-level architecture of the AIM system:
checking AIM Integration Manual
AIM Rules Framework
AIM Rules Framework

Purpose
Overview of rules framework
Anatomy of a builder rule
Building complex configurations: AIM technology blocks
AIM configuration discovery
Implementing custom builder rules
Typical logical design for a custom builder rule
Rule packaging and configuration
Structure of apm-modelbuilder.xml
Rule's structure
Other kinds of builder rules
Validation Rules
QaKing rules (adapted)
DeclarativeValidationRule
Rules for Object Oriented languages
Default class dependency resolvers
ClassCallback
When a rule should be customized?
Good practices for the customization of rules AIM
Overriding of methods of classes of product
Beans product overwriting
New spring beans which extend one product
Implementation of rules accessing the generated AST
Recommendations
Purpose
This document is a quick guide for developing custom rules for application portfolio extraction from code and other artifacts.
Application Portfolio provides an extensible framework for automated extraction of entities (organisational and software-related) and their
relations, for compilation of an application map, to be used by different checKing plug-ins.
The framework is based on a set of BuilderRules, that may perform different tasks:
To create portfolio entities (organisational or software-related) and resolve their mutual relations.
To check if the software artifacts are compliant with architecture standards.
To detect potential architectural anti-patterns (smells).
To resolve the group of code artifacts that are logically related to software entities in the application map, for later analysis.
A BuilderRule is an unit of logic that may perform any of the above tasks.
Overview of rules framework
The generic portfolio model framework is provided as a java library inside the APPMAP plug-in (PortFolioModel*.jar). This framework
contains:
ModelBuilders, that will perform the application map extraction (the default DefaultApmModelBuilder suffices for most
needs).
BuilderRule, with many standard implementations for common situations. Many rules are provided within the framework (for
example, TooMuchCouplingValidationRule will detect coupling anti-patterns in the application map). Organisations may
program their own BuilderRules if necessary.
Model classes, for representing organisational and software-related entities and their relations (see com.optimyth.apm.model
package in distributed JavaDocs for full details). The standard entities are Organization (a company or an external organisation
etc.), Unit (for modelling an area or department), Person (for modelling people), Software (for modelling any software system)
and Component (for modelling any software component, like a program, database table or business process etc. that should be
included in the application map). Those entities have arbitrary properties (values with a certain type) for representing any entity of
interest.
Persistence facilities, for making persistent the application map into a certain repository (a default database schema is provided and
persistence engine is included in the distribution, but organisations may provide their own persistence engines, for example for
populating an external CMDB system or their own software assets repository).
Each company may add its own custom extensions on the above facilities, to reflect the particular features of its
organisation. For example, to analyse custom frameworks, extract organisational dependencies from an external
system (like a Source-Control tool or an LDAP directory), or to check if existing code complies with architectural rules.
The generic framework provides different ModelBuilders. Currently the only one used is the DefaultApmModelBuilder class.Every apm
model builder needs:
parsersRegistry: a bean defining parsers of languages that are being analysed by app map. A QakingFileParserAdapter class
adapt QAking parsers (Cobol, java, JavaScript, C#, VB.net, JSP, PLSQL etc.) to this framework. Specific apm parsers can be
loaded.
ruleset: an apm ruleset with model builder rules used to generate the company's model.
reportRenderer: renderer classes to dump the information. Currently XmlBuilderReportRenderer and HtmlBuilderReportRenderer are
supported.
fileFilter: java.io.FileFilter to use when deciding which directories/files to process (defaults to all files/directories).
This configuration is defined in the APPMAP plug-in scripts/resources/apm-modelbuilder.xml configuration file (a Spring XML
descriptor that configures the model building process).
The normal operation of a ModelBuilder is as follows:
First,a BuilderContext is initialised (you can register in the bean "apm_modelBuilder" a custom ModelBuilderListener to add extra
logic). See the ModelBuilderListener javadoc for more information about the implementations of this interface. By default a dummy
Listener is created.
The BuilderContext is started by defining the apmmodel that is being generated as well as the ruleset that will be applied. If
you have defined a listener then it is notified of that event. The model statistics then start to collect information.
Then, all the defined client rules are initialised by the BuilderRuleset. This implies that all defined (and active) builder rules execute
its initialize() method (once).
For each basedir defined in config files (typically apm-modelbuilder.properties), all files beneath it are traversed (recursing
through subfolders) and for each file found, each BuilderRule is run on this file (if matching the rule filter).
After all basedirs are processed, the postProcess(BuilderContext) method for each rule is invoked. This can be useful when
you want to make a rule that may need information compiled from various rules, or data that can only be estimated once all files
have been traversed.
Anatomy of a builder rule
All builder rules must implement at least the com.optimyth.apm.builder.rules.BuilderRule interface. Typically a base
AbstractBuilderRule class provides a basic implementation that could be extended.
A typical builder rule has the following structure:
initialize(BuilderContext). Is executed once and during the model builder initialisation.

run(). For each source file that matches the rule File Filter property. The FileFilter property must be injected on configuration.
postProccess(BuilderContext). After all rules are executed. Useful to compute global rules.
AbstractBuilderRule provides an empty implementations for postProcess(BuilderContext) and

initialize(BuilderContext) methods, and a default run(BuilderContext) implementation, that delegates on
visit(BuilderContext) to be provided by the actual implementation. The run() method simply checks with the injected FileFilter if
the currently analysed file should be processed, and in that case invokes the visit(BuilderContext) method.
Specific rules can be subclassed by implementing the visit(BuilderContext) method (for "local" rules), or providing an empty
visit(BuilderContext) method and overriding either initialize(BuilderContext) / postProcess(BuilderContext) (for "global"
rules).
Building complex configurations: AIM technology blocks
In what follows, PLUGIN_EXTENSION_DIR is the directory where APPMAP extensions are located (
CHECKING_DATA/config/plugins/APPMAP).
Software technology could be very complex, and that complexity affects AIM configurations for real software systems. Some platforms
(think on J2EE, .Net, complex database code, or legacy systems) typically combine multiple programming languages, with different
configuration descriptors. The layout for a real-world software system could be fairly complex.
To improve modularity in configuration, AIM defines a set of AIM configuration blocks by technology. An AIM configuration block is
present for each technology/subtechnology supported (e.g. the block j2ee/ejb represents the configuration rules for modelling EJB
entities and relations for a J2EE-based system).
common: Contains common elements, used by the rest of the AIM configuration blocks.
abap: Rules for ABAP.
actionscript: Rules for ActionScript.
cpp: Rules for C/C++.
database/database: Rules for analyzing extracted schema descriptors (generic or database-specific).
database/plsql: Rules for Oracle PL/SQL technology.
database/transactsql: Rules for Microsoft SQL Server (Transact-SQL) code.
dotnet/dotnet: Rules for .Net languages (C#, VB.NET), excluding ASP.NET-specific artifacts.
dotnet/aspnet: Rules for ASP.Net technology.
html/asp: Rules for Microsoft ASP 3 technology.
html/html: Rules for static HTML code.
j2ee/java: Rules for Java code (not framework-specific).
j2ee/jdbc: Rules for analyzing embedded SQL code in Java classes using JDBC API.
j2ee/hibernate: Rules for analyzing Hibernate persistence descriptors.
j2ee/ibatis: Rules for analyzing Ibatis persistence descriptors.
j2ee/jsp: Rules for JSP / JSF pages and related web resources.
j2ee/spring: Rules for analyzing Spring framework (beans, Spring WebFlow)
j2ee/ejb: Rules for analyzing EJB code.
j2ee/struts: Rules for analyzing Struts code.
j2ee/weblogic: Rules for analyzing Weblogic code.
j2ee/webservices: Rules for analyzing WebServices code.
legacy/cl400: Rules for IBM ILE (OS/400) CL scripting language.
legacy/cobol: Rules for Cobol language and related technology (CICS, embedded SQL).
legacy/jcl: Rules for IBM JCL (Job Control Language).
legacy/Natural: Rules for Software AG Natural code (and Adabas).
legacy/rpg: Rules for RPG code.
php: Rules for PHP code.
validation: Rules for architecture validation and detection of dependency anti-patterns.
vb: Rules for Visual Basic code (up to VB 6).
Each configuration block is composed of a generic XML descriptor (Spring), tech/aim.subtech.xml, and a
.properties file (tech/aim.subtech.properties) that configures the beans declared in the XML file. For simple software layouts, it
could be sufficient to select the different technologies present in software, and edit the properties for each AIM configuration block.
An AIM Configuration (placed in a subdirectory under PLUGIN_EXTENSION_DIR/configurations) is normally defined by the

following files:
aim.configuration.xml: Configuration metadata (generated by discovery).

aim.technologies.xml: Imports AIM configuration blocks to use.
aim.properties: Execution properties, like timeouts, logging, etc.
aim.custom.xml: Spring descriptor for customization rules (initially empty). Custom rules could be declared here.
For each configuration block, its .properties file is included (under tech/aim.subtech.properties). There is a default configuration
(named DEFAULT, which should not be modified) that contains all the AIM technology blocks as well as some engine files. A user
configuration inherits these configuration, unless it redefines a particular file. This simplifies configuration.
In the AIM TASK - Analyze the name of the configuration could be specified when analyzing a software system with a matching layout
for the configuration. You may define multiple configurations for the different software layouts,
and reuse them when analyzing multiple software systems.
AIM configuration discovery
To help building the AIM configuration for model building, the configuraton discovery task provides a mechanism to generate an initial
configuration (based on AIM configuration blocks), analyzing one or more input directories (e.g. with source code for a software system
with a certain layout). The generated configuration (under PLUGIN_EXTENSION_DIR/configurations/CONFIG_NAME) could be
edited either manually or using provided editor.
Implementing custom builder rules
The discovery of custom entities and relationships (if not already supported by any of the provided standard discovery rules) can be
done by implementing custom discovery rules that will analyse the input artifacts (e.g. source code files), identify the model entities,
properties to add to model entities, and their dependencies, and update the current model in the discovery engine. Typically you will add
such custom rules (and configuration items like filters) to the Spring apm-rules.xml configuration file, and reference the rule in the
apm-modelbuilder.xml main Spring descriptor.
Typical logical design for a custom builder rule
It is recommended to decompose the discovery logic in three parts:
Analysis on the (parsed) item
This is the responsibility for the rule itself. The input to the rule (held by the BuilderContext passed to rule methods) is typically a
BaseNode AST (root node) (provided by a com.optimyth.apm.builder.parser.QakingFileParserAdapter), an ASM
ClassNode (provided by the com.optimyth.apm.builder.parser.JavaBytecodeFileParser), or anything else provided by
other com.optimyth.apm.builder.parser.FileParser implementation).
For the rule, you may implement the com.optimyth.apm.builder.rules.BuilderRule or extend from the base
com.optimyth.apm.builder.rules.AbstractBuilderRule.
For rule initialisation, implement the rule's initialize(BuilderContext) method.
For discovery logic for each processed input artifact, implement the rule's void run(BuilderContext ctx) method (or
AbstractBuilderRule's void visit(BuilderContext ctx)).
Sometimes you need to "remember" certain results that should be post-processed when the engine has visited all the input artifacts. You
may specify rule's post processing logic in the void postProcess(BuilderContext ctx). For example, you may need to
remember "calls" and resolved the remembered calls to relationships between model entities only at the end, when all entities are built in
the model.
Modelling of entities and relationships (dependencies)
The rule, when it detects a construct that should be modelled in the application portfolio in a certain way, it may delegate the modelling
logic to an external callback class, that provides callback methods ("event handlers") with the extracted information from the rule. With
this design, you are separating navigation and analysis on the input item from entities/relations modelling. Define an interface (e.g.
MyArchitectureFrameworkCallback) and provide onEVENT(... args ...) methods that will be invoked by the rule at the
points where something of interest for the model is found in the input item.
The implementation of your callback interface may extend the com.optimyth.apm.builder.RuleCallbackBase, that provides
basic facilities for registering a model helper (see below).
Adding the entities, properties and relationships to the model
The callback above described may delegate to another component, the ModelHelper, the instantiation of APPMAP model objects
(entities, properties, relationships). Typically this logic could be reused by different callbacks (in fact, a base
com.optimyth.apm.builder.rules.model.ComponentsHelper) is provided, with methods for building some common cases. It
may extend that class to add additional methods).
For logging, APPMAP uses Apache Log4j. You may log errors and traces etc. using code like this, in your rule,
callback or model helper items:
private static final Logger log = Logger.getLogger(MyBuilderRule.class);

...
log.error("Something bad happened", exception);
NOTE: Logging is configured by the APPMAP log4j.properties configuration.
Rule packaging and configuration
Custom builder rules can be packed into a separated jar, to be deployed at

${CHECKING_HOME}/WEB-INF/plugins/plugin-APPMAP-2.0/lib directory. Additionally, the rules should be registered in the
apm-modelbuilder.xml file deployed in ${CHECKING_HOME}/WEB-INF/plugins/plugin-APPMAP-2.0/scripts/resources.
Structure of apm-modelbuilder.xml
This file must contain the following items:
<xml declaration>
<Doctype>
<beans>
<property files declaration>
<apm_modelbuilder bean>
<apm_parsersRegistry>
<apm_ruleset>
<rule beans>
<..>
<file filter beans>
<apm_report_renderer beans>
<renderer bean>
<..>
<auxiliar beans>
<import of other files>
</beans>
For modular configuration, typically specific model building beans are configured in separate Spring
descriptors, that are imported from main apm-modelbuilder.xml. Common specific descriptors are:
apm-rules.xml, where each rule (discovery, architecture validation or antipattern detection etc.) is
configured.
apm-persistence.xml, where the persistence managers for the discovered model are configured.
apm-qaking.xml, with configurations for the parsers for each language/technology, that will provide
parsed content to rules.
apm-script.xml, with configurations for the scripts, that may be used from the batch interface for different
operations on extracted APPMAP models.
Property files declaration and apm_modelbuilder bean

<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN"
"http://www.springframework.org/dtd/spring-beans.dtd">
<beans>
<bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
<property name="locations" value="classpath:apm-*.properties"/>
</bean>
<bean id="apm_modelBuilder" class="com.optimyth.apm.builder.DefaultApmModelBuilder">

<property name="basedir" value="${basedir}" />


<property name="parsersRegistry" ref="apm_parsersRegistry"/>
<property name="ruleset" ref="apm_ruleset"/>
<property name="reportRenderer" ref="apm_report_renderer"/>
</bean>
The apm_modelBuilder bean defines the DefaultApmModelBuilder class and its sets of properties (parserRegistry, ruleset,
reportRenderer and the optional modelBuilderlistener)
Parser registry bean
<bean id="apm_parsersRegistry" class="com.optimyth.apm.builder.parser.FileParsersRegistry">

<property name="parsers"><list>

<bean class="com.optimyth.apm.builder.parser.JavaBytecodeFileParser">
<description>Java bytecode parser</description>
</bean>
<bean class="com.optimyth.apm.builder.parser.QakingFileParserAdapter">
<description>Cobol parser</description>
<property name="filter" ref="apm_filter_cobol"/>
<property name="languageSupport" ref="ls_cobol"/>
<property name="encoding" value="iso-8859-1"/> 
</bean>
</list></property>
</bean>
There are three kinds of parser classes:
JavaBytecodeFileParser for java .class files.

QakingFileParserAdapter, that wraps parsers for all technologies present in JKQA. Encoding could be set to force specific encoding
for this technology (the script global encoding property will be used if not specified here).
filter property is defined ahead on this configuration file (apm-modelbuilder.xml)
languageSupport is defined in a separated configuration file (apm-qaking.xml) and is deployed in
${CHECKING_HOME}/WEB-INF/plugins/plugin-APPMAP-2.0/scripts/resources. This file must define languageSupport
beans for QAking technology. These beans must be similar to the ones used in qaking-tech-TECHNOLOGYNAME.xml files
that you can find in ${JKQA_HOME}/lib/qaking_TECHNOLOGYNAME.parser.jar/resources
XmlFileParser. Parses XML file as a DOM4J Document. This is useful for processing descriptors and configuration files in XML
format.
BuilderRuleset and Builder Rules beans
<bean id="apm_ruleset" class="com.optimyth.apm.builder.rules.BuilderRuleset">

<property name="name" value="my ruleset"/>
<property name="rules">
<list>
<bean class="com.COMPANY.apm.builder.rules.CustomRule">
<property name= "filter" ref="apm_filter_one"/>

</bean>

</list>
</property>
</bean>
Define the builder Ruleset with a list of rule beans, injecting different properties if needed.You can override the filter property if you want
to use a custom file filter instead of the "AllFileFilter" class.
File Filter beans


<bean id="apm_filter_one" class="com.optimyth.apm.builder.file.RegexpFileFilter">
<property name="regexp" value="/WEB-INF/classes/com"/>
</bean>
There are six kinds of file filters in the model:
AllFileFilter - Accepts all kind of files

AndFileFilter - AND file filter. Matches the file if ALL combined filefilters match.
Constructor argument: java.io.FileFilter[]
ExtensionsFileFilter - A FileFilter that will match a certain extensions set (without dot).
Constructor argument: Set<String> - extensions
NotFileFilter - NOT file filter. Matches the file if the negatedFilter DOES NOT match it.
Constructor argument: java.io.FileFilter
OrFileFilter - OR file filter. Matches the file if ANY of the combined filefilters match.
Constructor argument: java.io.FileFilter[]
RegexpFileFilter - A FileFilter that will match using a regular expression on the file's absolute path. Can be used to match files in a
certain directory, ending with a particular pattern, etc. (See javadoc for more information).
apm_report_renderer bean
<bean id="apm_report_renderer" class="com.optimyth.apm.builder.report.CompositeReportRenderer">

<property name="renderers"><list>
<bean class="com.optimyth.apm.builder.report.XmlBuilderReportRenderer" />
<bean class="com.optimyth.apm.builder.report.HtmlBuilderReportRenderer" />
</list></property>
</bean>
There are three kinds of BuilderReportRenderer. They need outputFule as the property to inject.
XmlBuilderReportRenderer - Dumps Application Map building report (see javadoc for more information).
HtmlBuilderReportRenderer - Dumps report in HTML format using a builderReport.template file
CompositeReportRenderer - Composite ('fan-out') BuilderReportRenderer.
Rule's structure
Rules can have several properties needed to perform their tasks; some of them can be references to other specific objects also declared
in spring files. These special objects are grouped by:
filters
callbacks
resolvers: the logic to resolve external references to external resources as programs, includes, images and so on.
Other kinds of builder rules
Validation Rules
These are BuilderRules focused on checking if the analysed software artifacts comply with the architecture standards. Typically they
provide its logic on the postProcess() method (where the full software entities are already extracted). They look for global information
within the model. For example, for each Component in the ApmModel they look at the number of their outgoing relationships to
determine if it is too high and then emit a "smell detection" to include in the report. This smell is included as a architecture violation in the
final report.
Below is an example:
public class MyValidationRule extends AbstractValidationRule {
public void postProcess(BuilderContext ctx) {

super.postProcess(ctx);
BuilderReport report = ctx.getReport();
ApmModel model = ctx.getModel();
for(Iterator<ApmEntity> i = pm.getEntities(); i.hasNext();) {
ApmEntity toCheck = i.next();
if(mycheck(current)) {
ValidationRuleViolation viol = ValidationRuleViolation.newViolation(this, null, -1,
toCheck.toString(), getDescription());
ctx.getReport().addViolation(viol);
}
}
}
private boolean mycheck(ApmEntity toCheck) {

// .... logic that checks invalid dependencies
}
}
See JavaDoc of the APPMAP API for full details.
QaKing rules (adapted)
Any JKQA rule can be wrapped by QakingValidationRuleAdapter and be included as a ValidationRule. If you find JKQA rules
to be suitable to form an "Architecture rule", just declare it wrapped into this class:
apm-qaking.xml
<bean id="apm_rule_java" abstract="true" class=

"com.optimyth.apm.builder.rules.QakingValidationRuleAdapter">
<property name="filter" ref="apm_filter_java"/>
</bean>


<bean id="qaking_tooComplex" class="com.als.clases.oyr.cmetrics.Tcc"/>

<bean id="apm_rule_tooComplex" parent="apm_rule_java"><constructor-arg ref="qaking_tooComplex"
/></bean>
For enhaced modularity, you may place such definitions in the imported apm-qaking.xml file:
amp-modelbuilder.xml
<bean id="apm_ruleset" class="com.optimyth.apm.builder.rules.BuilderRuleset">

<property name="name" value="my ruleset"/>
<property name="rules"><list>
... Rest of rules ...
<ref bean="apm_rule_tooComplex"/>
</list></property>
</bean>
...
<import resource="apm-qaking.xml"/>
DeclarativeValidationRule
Instead of implementing (in Java) a ValidationRule, the DeclarativeValidationRule could be used. This rule uses a domain-specific
language (DEPVAL for short) to define software architecture compliance rules, and could be configured as in the following example:
Rule configuration example
<bean id="apm_rule_architecture" class=

"com.optimyth.apm.builder.rules.validation.DeclarativeValidationRule">
<property name="code"><value><![CDATA[
-> ${target}') {
// Checks if any component tagged CO uses any component tagged as BU-specific, which is
rule(name: 'CO2CO', description: 'CO artifact calling BU-specific artifact is forbidden') {
deny {
from(aql: ".['CO' == @tags]");
// See how to ignore outgoing usages of a set of components
to(aql: "component[#!['app=MODULE,prog=IS.D'].contains(o.key)#][@tags and @tags != 'CO']")
}
}
// Checks if any BU-specific component uses any component tagged for a different BU,
which is forbidden by architecture rules
rule(name: 'BU2sameOrCO', description: 'BU-specific artifact using other BU artifact is
forbidden') {
deny {
from(aql: ".[@tags and @tags != 'CO']");
to(aql: "\$tag = ./@tags; component[@tags and @tags != 'CO' and @tags != \$tag]")
}
}
// Checks for COPYs that are not included in any other program. Uses specific Groovy
logic (checkEntity)
rule(name: 'Unused COPY', description: 'Every COPY should have incoming deps from Cobol
programs',
message: '${rule.description}: ${source}',
checkEntity: { entity, ctx, rule ->
def progType = entity.getPropertyByName('programType').value;
if('COPY' == progType) {
// If no incoming usages from other programs: 'dead code' COPY
return null == entity.parentComponents.find{ parent -> 'program' == parent.componentType.name }
}
return false;
}
)
}
// Add other rulesets...

}
</value></property>
</bean>
See Dependencies Validation Language manual for full details on DEPVAL.
Rules for Object Oriented languages
We try here to explain one of the most complicated rules in AIM, rules for object oriented languages (i.e. Java, C#, VB.NET, ABAP)
CSharpClassRule is an AbstractTypeResolverRule (which extends AbstractClassRule, the base for all the rules for OO
languages).
AbstractTypeResolverRule uses a TypeResolver, a class devoted to resolve found types: given the namespaces found in the
analyzed classes, the type resolver identifies which is the referred class. In our example, there is a TypeResolverDotNet, which uses
a descriptor of .NET framework classes. This descriptor can be generated also from custom DLLs (see utility "DllTypeExtractor.exe",
included in QAKing).
The class ClassDepsResolver instead, resolves candidate dependencies into APM model's components and relations: the rule
searches the AST, finding possible dependencies with candidate types, while the ClassDepsResolver solves those dependencies:
Java example
A.java
B.java
C.java
Analyzing A.java, we find a use of C class into its code... we still didn't find any C class, so AbstractClassRule stores
that "use candidate". When the rule finds C class, then the Deps resolver decides if it must add or not those
components and relations to the model.
Note: deps resolver needs then a reference to the callback, the only class that is supposed to modify APM model.
Default class dependency resolvers
ExistingClassDepsResolver - This class deps resolution strategy will generate component for any class parsed in the model, and
relations between pairs of classes when both are present in the model. So this automatically skips any class declared in artifacts not
analyzed during model building.
Properties:
classnameFilter
un Predicate<String> que macheará las clases a descartar, por considerarse que forman parte del marco estándar y que no
deben reflejarse en el modelo). Por defecto es Predicate.JDK_FILTER, puede usarse para CSharp
Predicate.CSHARP_FILTER (o Predicate.VBNET_FILTER para vb.net)
callback
ClassCallback used to insert entities (software and components) into APM model
MatchingPkgClassDepsResolver - Matches dependencies using two Predicate injected at classnameFilter and predicate properties.
Properties:
classnameFilter
is used to skip classes that should be ignored (e.g. JDK or .NET framework).
predicate
is used to accept only the classes matching the predicate.
callback
ClassCallback used to insert entities (software and components) into APM model
ClassCallback
This class is will receive events that process classes in any OO language, deciding what to do whenever these events occur.
The same callback can be used and injected into the rule and the deps resolver.
A class callback can be configured in different ways:
Manually register the application name: all components will belong to given Software
Use a SoftwareResolver to know which application (Software) is Component container
This is useful when the application name is specified in files like web.xml, web.config or .csproj/.vbproj
ApplicationRegistrySoftwareResolver: looks into applications previously discovered by other rules like DotnetProjectRule (and
maintained in a ApplicationRegistry)
WebAppSoftwareResolver: resolves the software looking at webApps resolved by WebAppBuilderRule which analyzes web.config file
(ASP.NET)
When a rule should be customized?
To decide whether a rule should be custom or not we must take into account the following:
Is it a case of technology standard?: in case of not being the technology standard will be a rule customized.
It is standard technology and product rules solve it correctly but it is not the desired model?: If the technology standard and is not a
bug in the product will be a rule customized.
Good practices for the customization of rules AIM
This section describes best practices to follow when it comes to rules of product customizations.
Overriding of methods of classes of product
To the overwrite a method of a class to always put the label @Override. It should change the signature of the method it will fail to
compile.
To the extent possible make a call to the superclass method since logic can change between versions.
Beans product overwriting
If you want to overwrite a product bean, i.e., define a bean's spring custom with the same name that product should be checked in
every version change if there are new properties in the bean overwritten in case of ignoring them can get unexpected results or even
errors.
New spring beans which extend one product
When you create a bean extending one product use the parent attribute in the definition of spring and if there are properties that are
added to the existing bean this will be transparent to the customization.
For example:
aim.custom.xml
<bean id="aim.myproject.mybean" parent="aim.bean.product" class="mypackage.MyClass">

<property name="myproperty" value="myvalue"/>
</bean>
Implementation of rules accessing the generated AST
Accessing nodes in the AST avoid the use of methods such as child (0) as possible changes in the AST can cause unexpected errors,
so it is advisable to use methods such as child("node name") or find("node name").
Recommendations
As recommendation is a good practice to have available unit testing of each rule customized to be able to launch them in each version
that you want to implement, so it can detect errors as soon as possible.
AIM TASK - Configuration discovery

Purpose
How it works
Configuration
Results
Purpose
To help setting up the configuration for building an application map model, this task provides a discovery tool that generates
an AIM configuration from one or more source code directories. The generated configuration could be later refined and executed
using the AIM TASK - Analyze over a software system with a layout similar to the one analyzed during discovery.
The APPMAP plugin APPMAP/script/discovery script could be launched from the checKing web interface. Alternatively, you may
execute from command-line the script directly:
ant -f aim-config-admin.xml discover -Dconfiguration=MyConfiguration

"-Ddirectories=path,path2,..." [-Dconfig.dir=DIR]
In either case, the discovery task takes a comma-separated list of directories with software source folders, and discovers automatically
which technologies should be applied, generating configuration files for them.
How it works
The discovery engine uses a set of discovery rules, tailored for discovering code artifacts (source code, configuration descriptors,
application content...) and generating configuration blocks for each technology discovered. The rules are defined in the
CHECKING_DATA/plugins/APPMAP/configurations/modelbuilder/DEFAULT/aim.discovery.xml, but typically the
provided configuration (for the supported technologies in AIM) does not need to be modified.
The engine generates a set of configuration files under CHECKING_DATA/plugins/APPMAP/configurations/modelbuilder/

CONFIGURATION_NAME, where CONFIGURATION_NAME is the name given to the configuration processed. The configuration could be
used when executing the AIM TASK - Analyze on multiple software systems with similar layout to the one analyzed.
Configuration
The script has the following parameters:
parameter meaning example
configuration (mandatory) Name of the AIM configuration to generate/augment MyConfiguration
directories (mandatory) Comma-separated list of directories to analyze /PATH/TO/CODE,/PATH2/TO/CODE
config.dir (optional, only available via command line) configuration output directory
If the configuration specified already exists, it is augmented with the new technologies discovered, if any.
Results
The task execution shows the discovered technologies and the count of elements found:
discover:
[aim.discovery] Technologies discovered: common/common,j2ee/java,j2ee/jdbc,j2ee/spring
[aim.discovery] Technology: j2ee/java
[aim.discovery] file: 36
[aim.discovery] Technology: j2ee/spring
[aim.discovery] configuration: 9
[aim.discovery] element: 49
[aim.discovery] Matched files: 45
[aim.discovery] Ignored files: 241
BUILD SUCCESSFUL
Total time: 1 second
A new set of configuration files are created in the CHECKING_DATA/plugins/APPMAP/configurations/modelbuilder/

CONFIGURATION_NAME directory. After discovery, you may edit it manually (for example, for adding custom rules in the
aim.custom.xml descriptor) or using the provided tools for AIM configuration management. If the software layout is very complex, you
may need to change some of the .properties files.
AIM Query Service
AIM Query Service
Overview
Configuration
Startup / shutdown
Service Management
Query server: com.optimyth.aim:type=queryServer
Query service: com.optimyth.aim:type=queryServer,module=queryService
Statistics: com.optimyth.aim:type=queryServer,module=queryService,data=statistics
TheadPool: com.optimyth.aim:type=queryServer,module=threadpool
SessionManager: com.optimyth.aim:type=queryServer,module=sessionManager
Logging: com.optimyth.aim:type=Logging
Query Service API
Query Service URL
Additional client configuration
Authentication (session open) and session close
Operations
Technical notes
Overview
The AIM Query Service is a centralized service that APPMAP plugin starts during plugin initialization. This service is not running on the
webserver itself, but it's on a different process: a stand-alone server.
This server opens two TCP ports, a management port and a service port. Clients and administrative tasks use those ports to
communicate with the Query Service and perform operations on existing models, generated by the AIM TASK - Analyze.
Typical clients are:
AIM - Application map Browser, end-user console for analyzing model dependencies.
Scripts that perform operations (query, tagging, analyzing arquitecture rules...) on existing AIM models.
Third-party applications that use the AIM Query Service API (see below) for interacting with existing AIM models.
Client access is validated in the service using the credentials (e.g. username/password) for checKing accounts.
Configuration
The service configuration parameters are stored in the appmap.user.properties file, stored in the plugin extensions dir
CHECKING_DATA/config/plugins/APPMAP. The following properties are relevant for Query Service:
Property Meaning Default value
qs.host Hostname/IP address where the server binds to localhost
qs.port service TCP port 7890
qs.managementPort management TCP port 7891
qs.querytimeout configure timeout that is set in the client and server 300
qs.maxthreads Service threads (increase for high client loads) 3
qs.modelsDir Path where models are stored (do not change in normal usage) CHECKING_DATA/plugindata/appmap
qs.Xms Initial memory 192m (192 MB)
qs.Xmx Maximum memory 256m (256 MB)
qs.Xss Stack memmory size per thread 256k (256 KB)
qs.maxResults Max results size (set to a number, e.g. 10000, to avoid collapsing -1
service with large resultsets)
Note: It is recommended to stop the service before changing any of these values.
Startup / shutdown
APPMAP plugin starts automatically the service during plugin initialization, and shuts down the service during plugin termination.
Although not necessary in general, the service could be started/stopped manually using the run-queryserver.xml script located in
PLUGINDIR/scripts.
ant -f run-queryserver.xml start|stop|ping

[-Dport <port>] [-DmanagementPort <jmxPort>]
[-Dmaxthreads <maxthreads>] [-Dmodelsdir <modelsdir>]
Examples:
ant -f run-queryserver.xml start
start:
[echo] + ---------------------------------------------------------
[echo] + Query Server v0.1 - (c) Copyright by Optimyth 2012
[echo] + ---------------------------------------------------------
[echo] Starting the server...
[server.task] [2012-05-17 11:38:15] AIM QueryService contacted successfully: localhost:7890
ant -f run-queryserver.xml ping
ping:
[echo] + ---------------------------------------------------------
[echo] + ---------------------------------------------------------
[echo] Pinging the server...
[server.task] [2012-05-17 11:38:15] AIM QueryService contacted successfully: localhost:7890
ant -f run-queryserver.xml stop
stop:
[echo] + ---------------------------------------------------------
[echo] + ---------------------------------------------------------
[echo] Stopping the server...
[server.task] [2012-05-17 11:39:27] AIM QueryService localhost:7890 successfully stopped!
Service Management
Besides startup / shutdown, the service management interface is exposed via JMX (Java Management eXtensions) agent.
External JMX-enabled tools, like jconsole or jvisualvm (provided with Oracle Java Runtime), could connect to the management
port.
JMX management interfaces (beans) are exposed by query server for monitoring and/or live configuration changes. The beans could be
seen in the JMX management console:
All JMX beans exposed are placed under the com.optimyth.aim domain.
Query server: com.optimyth.aim:type=queryServer
Represents the query service. Child nodes (queryService, threadpool) expose management interfaces for the underlying query service
and supporting thead pool.
Attribute Type Meaning
BindingAddress string hostname where query server is bound (read-only)
Port int port where query server is listening (read-only)
Operation Signature Meaning
stop boolean stop(string password) Stops query server
Query service: com.optimyth.aim:type=queryServer,module=queryService
This bean exposes management interface for the service that responds to requests.
LoadedModelNames string[] Names of currently opened models (read-only)
MaxResults int Max number of results to return (-1 means "no limit")

closeModel boolean closeModel(string modelPath) Forcedly closes an opened model
Statistics: com.optimyth.aim:type=queryServer,module=queryService,data=statistics
This entry provides statistics for operations served since last startup.
DiffOperations int Number of diff operations executed (read-only)
Errors int Number of failed operations (read-only)
ImpactAnalysis int Number of impact analysis operations (read-only)
Logins int Number of successful logins (read-only)
LoginErrors int Number of failed logins (read-only)
PropagationOperations int Number of propagation operation (read-only)
Queries int Number of query operations (read-only)
TableOperations int Number of table operations (read-only)
TopN int Max number of top-N operations to remember, by time and result size
TopNBySize record Top-N operations by returned size (read-only)
TopNByTime record Top-N operations by elapsed time (read-only)
Validations int Number of validation operations (read-only)
clearTopN void clearTopN() Cleans top-N records
TheadPool: com.optimyth.aim:type=queryServer,module=threadpool
This entry provides a management interface for the thread pool that serve requests in query server.
ActiveCount int Number of currently active threads executing requests (read-only)
CorePoolSize int Number of threads that will be kept idle in pool
KeepAliveSeconds int Number of seconds an idle thread will be kept (above CorePoolSize)
before been removed from pool
MaxPoolSize int Maximum number of threads that will allowed in pool (must be non less
than CorePoolSize)
PoolSize int Number of threads in pool (read-only)
ThreadNamePrefix string Name prefix for threads in pool (read-only)
ThreadPriority int Priority for threads in pool (between 1=lowest and 10=highest)
Daemon boolean Daemon theads
changeQueueCapacity void changeQueueCapacity(int Queue capacity for holding pending tasks, when no idle threads available
queueCapacity) in pool
Normally this settings should not be changed under normal circumstances. The MaxPoolSize property could be configured in the
qs.maxthreads property
of the appmap.user.properties configuration file.
SessionManager: com.optimyth.aim:type=queryServer,module=sessionManager
Expose statistics for the session service (authentication in query server is done using ChecKing identities).
ActiveSessions int Number of active user sessions (read-only)
CurrentUsers string[] Usernames for active sessions (read-only)
LoginsFailed int Number of authentication operations failed (read-only)
LoginsOk int Number of authentication operations succeeded (read-only)
Timeout int Timeout (in milliseconds) for authentication operations against checking server
Represents query server logging system. This management interface permits live changes on the logging configuration.
DefaultLevel string Log4J default log level
LogFile string Path to the query server logfile (read-only)
getLevel string getLevel(string logger) Get logging level for the logger item
setLevel void setLevel(string logger, string level) Set logging level for logger item
configure void configure(string) Configures logging (properties text or path to .properties file)
clearLogFile void clearLogFile() Cleans logfile (remove all content)
getLoggers string[] getLoggers() Get names of logger items registered
deactivateLogging void deactivateLogging(string logger) Deactivate logging for the given logger
printConfiguration string printConfiguration() Dumps current Log4J logging configuration
openLogHub void openLogHub(int port, string format) Create a log hub (server where log collectors can connect)
closeLogHub void closeLogHub() Closes any active log hub
Query Service API
The com.optimyth.apm.query.client.IQueryClient interface provides access (from Java) to a remote AIM Query Service. API
classes are located in the QueryService.jar (located in PLUGINDIR/lib directory or in the distribution media). You may need other
JARs in runtime (libthrift-*.jar, for example).
Most operations may throw a com.optimyth.apm.query.service.QueryServiceException when error. Additional classes in

the API are located in the com.optimyth.apm.query.service Java package.
Query Service URL
To specify the service endpoint, a URL could be used, with the following syntax:
aim://[username[:password]@]host[:port][/modelLocation]
Example:
aim://administrator:adminpwd@checkinghost:7890
The authentication credentials (username and password, credentials for checKing accounts) and model location are optional. If port is
not specified, the default 7890 service port is used.
import com.optimyth.apm.query.client.*;
...
IQueryClient client = new QueryClient();
client.setUrl("aim://user:pwd@localhost");
...
If the credentials are not coded in the URL, they must be set via API:
import com.optimyth.apm.query.client.*;
import com.optimyth.apm.query.service.*;
...
IQueryClient client = new QueryClient();
clinet.setCredentials(new Credentials("user", "pwd"));
client.setUrl("aim://localhost");
...
Additional client configuration
The query client has a timeout (30 seconds by default) that, when exceeded, shuts down a running operation. Sometimes, for
long-running operations, you may need to increase the timeout:
QueryClient client = new QueryClient();

...
client.getPool().setSocketTimeout(300); // new timeout, in seconds
See the JavaDoc for the QueryClient class for full details.
Authentication (session open) and session close
The login() and close() methods create an authenticated session and terminates current session, respectively. It is recommended
to call close() in a finally block to ensure that session termination is attemped even in case of exceptions:
IQueryClient client = ...;

try {
client.login();
...
} finally {
client.close();
}
Operations
As most of the operations work on a particular AIM model, you must typically specify the relative path to the model before executing any
operation:
IQueryClient client = ...;

client.setModelLocation("project/MyModel");
The following operations are available in the IQueryClient object:
/**
* Executes a remote query, using model as starting context.
* @param aqlQuery
* @return
* @throws QueryServiceException
*/
List<Atom> query(String aqlQuery) throws QueryServiceException;
/**
* Executes a remote query, using given entity as starting context.
* @param aqlQuery
* @param ctxEntityId
* @return
*/
List<Atom> query(String aqlQuery, long ctxEntityId) throws QueryServiceException;
/**
* Executes a remote query, using given entities as starting context.
* @param aqlQuery
* @param ctxEntityIds
* @return
*/
List<Atom> query(String aqlQuery, List<Long> ctxEntityIds) throws QueryServiceException;
/**
* Executes impact analysis, using AQL for sources and targets
*/
ImpactAnalysisResult impactAnalysis(ImpactAnalysis analysis) throws QueryServiceException;
/**
* Executes impact analysis with intermidiate paths, using AQL for sources and targets
*/
String execImpactAnalysisWithPaths(ImpactAnalysis analysis) throws QueryServiceException;
/**
* Executes impact analysis with intermidiate paths, using AQL for sources and targets
*/
List<ImpactGraph> getImpactAnalysisWithPaths(String queryId, String modelId) throws
QueryServiceException;
/**
* Performs tagging in an AIM model, according to the TagOperation
*/
void tag(TagRequest tagOp) throws QueryServiceException;
/**
* Performs diff on a pair of models, returning the differences as a DiffResult
*/
DiffResult diff(DiffRequest diffReq) throws QueryServiceException;
/**
* Validates dependencies in model, looking for violations on validation rules
*/
List<Violation> validate(ValidationRequest req) throws QueryServiceException;
See JavaDoc for full details on the objects seen in the method signatures. Please note that some IQueryClient methods are used by
APPMAP Browser and are not of interest for typical usage of this API.
Technical notes
AIM Query Service uses Apache Thrift for service protocol implementation. This means that clients use TCP connections, which are not
compatible with web (HTTP) proxies that could be placed in the middle. APPMAP Browser supports a 'model download mode', when a
web proxy in the middle is the unique network path for accessing checKing server, that downloads the model datafiles via HTTP to the
browser's local filesystem, but other clients need direct TCP connection to the service port. Remember to contact your network
administrator to enable network access to the service port (with firewalls and other network access control devices).
Please, be careful with ant version. Version tested and supported to run AIM and Query Service, is ant-1.7.0.
AIM Scripting API
AIM Scripting API
Overview
Programming custom scripts
Overview
For integrating AIM in other applications, AIM provides a library (AIM Scripting API) for performing operations on remote AIM models,
that operate with connection to the AIM Query Service. This AIM Scripting API is built on top of the
com.optimyth.apm.query.client.IQueryClient (see Query Service API for full details).
For Java, the library JAR is named Scripting.jar and contains client-side classes for using programmatically
existing scripts or implementing your own. You probably need other dependencies, like QueryService.jar or
libthrift-*.jar, that could be located in the plugin lib directory or in the distribution media.
The base item for scripting in AIM is the com.optimyth.apm.scripting.Script interface:
package com.optimyth.apm.scripting;
public interface Script {
/**
* Executes an operation (typically in remote models via AIM Query Service).
* @param ctx ScriptContext
* @throws ScriptException if there was a problem when executing the operation
*/
public void run(ScriptContext ctx) throws ScriptException;
Programming custom scripts
There is a base abstract class com.optimyth.apm.scripting.AbstractScript that could be extended for implementing your
own script (in Java).
API elements
Propagation Analysis provides a Java API for executing analysis. The main class is the PropagationEngine, that will process a
program XML descriptor from a resource, with a proper PropagationListener that will be notified when an AIM model entity is
traversed (as starter or propagated) in a propagation rule described in the XML program descriptor.
You may use this API in many places (custom scripts, rules, etc.).
Note: All classes in the API are located in the com.optimyth.aim.propagation package, in the PropagationAnalysis.jar.
For full details, refer to the JavaDoc for the PropagationAnalysis module, included in the product distribution.
public interface PropagationEngine<T> {

/**
* Execute the propagation analysis program
* @param programResource propagation analysis XML descriptor resource
* @param model to analyze
* @param properties External properties passed to configure the analysis
* @param listener PropagationListener that will react on starter / traversed entities
(and typically render results report)
* @return PropagationContext
* @throws PropagationException
*/
PropagationContext<T> run(
Resource programResource, ApmModel model, Map<String, Object> properties,
PropagationListener<T> listener
) throws PropagationException;
}
PropagationListener will receive notifications (calls to its onXYZ() methods) of the stages in propagation analysis, and on the starters and
propagated items found. The listener then performs an appropiate action in these event notification methods. This is where the
processing logic of interest is encoded (propagation itself is generic and it is managed by the PropagationEngine).
public interface PropagationListener<T> {
/** Invoked at the beginning of the propagation analysis */

void onStart(PropagationContext<T> ctx);
/** Invoked when a Starter finds a starter item */

void onStarterItem(T item, StarterContext<T> starterCtx, PropagationContext<T> ctx);
/** Invoked when a Propagation finds a propagated item */

void onPropagatedItem(T item, StarterContext<T> starterCtx, PropagationContext<T> ctx);
/** Invoked at the end of the propagation analysis */

void onEnd(PropagationContext<T> ctx);
}
PropagationEngine will parse the XML program descriptor, invokes listener's onStart() and launch all rules declared in sequence.
For each rule starter, the actions are executed, and onStarterItem() on listener is called.
After processing all starter entities in the current starter, propagations are launched for the starters set in the containing starter, and for
each entity visited by current propagation, actions are executed, then the onPropagatedItem() method is invoked.
When all rules are processed, the engine calls onEnd() on the listener (many listeners report the results of the analysis here).
Sample client code
Direct execution of a propagation analysis

PropagationEngine<ApmAtom> engine = new BasicPropagationEngine<ApmAtom>();
Map<String,Object> props = new HashMap<String,Object>();
TaggingReporter reporter = new NullTaggingReporter();

PropagationListener<ApmAtom> listener = new TaggingListener(reporter);
// Run propagation analysis

engine.run(programResource, ctx.getModel(), props, listener);
Use of propagation analysis in a builder rule
The following example uses dead-code analysis with a tag marker reporter, by extending AbstractPropagationAnalysisRule,
which exposes some abstract methods (buildListener()) that could be overriden to return the appropiate PropagationListener
for the analysis (and where reporters could be configured). Nothing more is needed to have a builder rule based on propagation
analysis.
package myPackage;
import com.optimyth.aim.propagation.engine.PropagationContext;
import com.optimyth.aim.propagation.engine.PropagationConstants;
import com.optimyth.aim.propagation.listener.PropagationListener;
import com.optimyth.aim.propagation.deadcode.*;
import com.optimyth.apm.model.ApmAtom;
import com.optimyth.apm.model.ApmEntity;
public class DeadCodeRule extends AbstractPropagationAnalysisRule {

private String tag = null;
/** The tag to apply to detected unused entities */

public void setTag(String tag) { this.tag = tag; }
public String getTag() { return tag; }
@Override protected PropagationListener<ApmAtom> buildListener() {

// Prepare reporter (tagging)
DeadCodeReporter reporter = getTagDeadCodeReporter();
// Prepare listener
return new DeadCodeListener(reporter, true);
}
protected DeadCodeReporter getTagDeadCodeReporter() {

if(tag==null || tag.length()==0) return null;
return new DeadCodeReporter() {

public void onUnused(ApmEntity e, PropagationContext ctx) {
e.addTag(tag); // tag added to unused entity
}
public String getReportPath() { return null; }

public void setReportPath(String reportPath) { }
public String getEncoding() { return null; }
public void setEncoding(String encoding) { }
public void onStart(PropagationContext ctx) {}
public void onEnd(PropagationContext ctx) {}
};
}
}
AIM - Extending SoftwareResolver
Purpose
This document is a quick guide in order to know how to extend product softwareResolvers for specific behavior on client installations.
Application Portfolio provides a set of product softwareResolvers, but depending on client requirements these product ones could not fit
on client scenario.
For any new particular softwareResolver we are going to explain how to setup them, avoiding to edit any product configuration.
Extending SoftwareResolver
Once we have created a java class for our specific softwareResolver implementing
com.optimyth.apm.builder.rules.common.appresolution.SoftwareResolver interface, we should package it in a JAR file, and place this
JAR file into PLUGIN_EXTENSION_DIR directory, which is the directory where APPMAP extensions are located ($
CHECKING_DATA/config/plugins/APPMAP)
JAR file must contain a META-INF directory, and we must place there the XML descriptor file for our specific softwareResolver named
aim.resolvers.descriptor.xml. AIM will use this XML descriptor in order to create dinamically the defined software resolvers, adding them
to the application's context.
Structure of XML descriptor file
Here is the structure of the XML file descriptor (aim.resolvers.descriptor.xml):
<xml declaration>
<resolvers>
<software-resolvers>
<resolver>
<name>
<description>
<properties>
<resolver>
</software-resolvers>
</resolvers>
Example of software resolvers file descriptor

<resolvers>
<software-resolvers>
<resolver key="aim.common.appresolver.single" class=
"com.optimyth.apm.builder.rules.common.appresolution.SingleNameSoftwareResolver">
<name>Single Application</name>
<description>
Single Application resolver is the simplest possible application resolution:
all the code belongs to the same ONE application. The sole parameter you will
need to configure is the application's name.
</description>
<properties>
<property id="softwareName" type="string">
<name>applicationName</name>
<description>Application Name</description>
</property>
<property id="softwareType" type="string">
<name>softwareType</name>
<description>Software type. It can be: application (default value), module, layer,
library, middleware, tool, product, framework, database, other</description>
</property>
</properties>
</resolver>
</software-resolvers>
</resolvers>
Software Resolver properties
Once we have declared properties specific softwareResolver is going to use, we can setup values within aim.common.properties file.
This properties can be refered by software resolver key declared in descriptor file plus property id
(i.e.: aim.common.appresolver.single.softwareName)
Apart from above configuration we must add declared key of our specific software resolver in aim.common.properties file editing list of
aim.common.resolvers property
Software resolvers extension logic does not support Maps on properties as Spring. This type may be defined as a list of
values separated by a token, and then treat values on specific software resolver in order to map them into a specific
map.
AIM Rules API

API Home
API Home
The following pages are technical documentation about AIM rules; They are generated automatically from source files to
extract all relevant information. It's not intended to replace javadoc pages; these are usefull in order to help in
customers' configuration processes instead javadoc, used to enchance AIM's API.
RuleCallbackBase
Page created on 04/20/2015
Class RuleCallbackBase
Structure
Methods Summary
Class RuleCallbackBase
extends from Object

implements RuleTransformation
package com.optimyth.apm.builder
RuleCallbackBase - Extend your callbacks with this class to benefit from some handy methods.
Structure
Methods Summary
public void setHelper(rules.model.IComponentsHelper helper)
Set your own helper or ComponentsHelper would be used as default.
helper
public void setSoftwareResolver(rules.common.appresolution.SoftwareResolver softwareResolver)
SoftwareResolver that may be injected to return the Sofware where the components returned by this callback will be placed.
public void setDatabaseObjectResolver(rules.common.dbresolution.DatabaseObjectResolver
databaseObjectResolver)
The database object resolver to use for finding mapped database objects. When set, dbType / dbName are used as fallback if the
resolver does not match the target table.
public void setSoftwareName(String softwareName)
The name of the containing software, to use as fallback if no explicit or global software resolver can resolve container for artifacts
public void setSoftwareType(String softwareType)
The software type (default: "application"), to use as fallback if no explicit or global software resolver can resolve artifact
public void setOverrideSoftwareResolver(boolean overrideSoftwareResolver)
Override SoftwareResolver: this is the old (default) behavior for some webapp rules, where these detection is embedded, and
they use the default resolution as a fallback
public void setResolveArtifacts(boolean resolveArtifacts)
If true, add Artifacts property for each analyzed component (defaults to true).
resolveArtifacts Boolean flag.
public void setTransformation(transformation.RuleTransformation transformation)
The RuleTransformation to use with this callback (please note that transformation logic may be added to rules as well)
public void setup(BuilderContext ctx)
The setup() method could be invoked on the first onXXX() method invoked in element processing,
to ensure that a helper is registered and that the helper has the BuilderContext set.
ctx BuilderContext
rules.abap
com.optimyth.apm.builder.rules.abap
com.optimyth.apm.builder.rules.abap
rules.abap.AbapBuilderRule
Class AbapBuilderRule
Structure
Methods Summary
Class AbapBuilderRule
extends from AbstractBuilderRule
package rules.abap
AbapBuilderRule - Rule for processing ABAP source code files.
Structure
Methods Summary
public void setCallback(rules.abap.AbapCallback callback)
Callback to use for updating AIM model with entities and relations found in ABAP code.
public void setSapRepository(rules.abap.SapRepository sapRepository)
The SAP repository information for resolving certain items
rules.abap.AbapCallback
Class AbapCallback
Structure
Field Summary
Class AbapCallback
extends from RuleCallbackBase
package rules.abap
AbapCallback - Callback for creating ABAP components and dependencies in AIM model.
Structure
Field Summary
Properties Name Desc
public static NULL
rules.abap.DefaultAbapCallback
Class DefaultAbapCallback
Structure
Methods Summary
Class DefaultAbapCallback
extends from rules.abap.AbapCallback
package rules.abap
DefaultAbapCallback - Default implementation for rules.abap.AbapCallback.
Structure
Methods Summary
public void setTemporaryDataOnFile(boolean temporaryDataOnFile)
If true, temporary data is stored in a system file (useful with huge code volume).
Default: false (temporary data is created in out-of-heap memory)
TODO probably this should be "global configuration" and not to be stored in every single rule ...
public void setSapRepository(rules.abap.SapRepository sapRepository)
The SAP repository information for resolving certain items

public void setCreateSqlNodes(boolean createSqlNodes)
If true, create a node for SQL statements found in source element. If false, no explicit nodes for SQL statements are created.
public void setDatabaseType(String databaseType)
The database type (e.g. SAP/R3) or database name for container of referenced tables.
Used as fallback if no global database object resolver, or the resolver cannot find the target entity.
public void setDatabaseName(String databaseName)
The database name or database schema (e.g. SAP) for container of referenced tables.
Used as fallback if no global database object resolver, or the resolver cannot find the target entity.
rules.actionscript
com.optimyth.apm.builder.rules.actionscript
com.optimyth.apm.builder.rules.actionscript
rules.actionscript.ActionScriptBuilderRule
Class ActionScriptBuilderRule
Structure
Methods Summary
Class ActionScriptBuilderRule
package rules.actionscript
ActionScriptBuilderRule - Rule for processing ActionScript source code files.
Structure
Methods Summary
public void setSqlProcessor(rules.sql.SqlProcessor sqlProcessor)

public void setObjectsSql(String objectsSql)
public void setMethodsSql(String methodsSql)
public void setResolver(rules.actionscript.ActionScriptObjectResolver resolver)
public void setCallback(rules.actionscript.ActionScriptCallback callback)
Callback to use for updating AIM model with entities and relations found in ActionScript code.
public void setProcessFunctions(boolean processFunctions)
rules.actionscript.ActionScriptCallback
Class ActionScriptCallback
Structure
Field Summary
Class ActionScriptCallback

implements rules.sql.SqlCallback
Abstract class callback for components of type ActionScript
Structure
Field Summary
public static NULL
rules.actionscript.DefaultActionScriptCallback
Class DefaultActionScriptCallback
Structure
Field Summary
Methods Summary
Class DefaultActionScriptCallback
extends from rules.actionscript.ActionScriptCallback
Implementation class callback for components of type ActionScript
Structure
Field Summary
protected null dbType
protected null dbInstance
protected null boolean ignoreCase
Methods Summary
public void setFinder(rules.database.DatabaseObjectFinder finder)
public void setDbType(String dbType)
public void setDbInstance(String dbInstance)
public void setIgnoreCase(boolean ignoreCase)
public void setExcludePredicate(rules.common.Predicate excludePredicate)
rules.asp
com.optimyth.apm.builder.rules.asp
com.optimyth.apm.builder.rules.asp
rules.asp.AspBuilderRule
Class AspBuilderRule
Goal
Technology
Configuration examples
Structure
Methods Summary
Class AspBuilderRule
package rules.asp
AspBuilderRule -
Rule for resolving outgoing dependencies for ASP WebPages.
Goal
Rule for resolving outgoing dependencies for ASP WebPages.
Technology
ASP 3.0
Structure
Methods Summary
public void setCallback(rules.asp.AspCallback callback)
public void setTagResolver(rules.asp.TagResolver tagResolver)
The helper to use when resolving HTML static tags (links, images, etc.)
rules.asp.AspCallback
Interface AspCallback
Structure
Field Summary
Methods Summary
Interface AspCallback
package rules.asp
AspCallback -
Structure
Field Summary
public static final NULL
Methods Summary
public onPage(java.io.File file, com.als.core.ast.BaseNode pageNode, BuilderContext ctx)
Registers a new ASP page for the given webapp
file File containing the ASP page

pageNode BaseNode
ctx
returns Component that models the ASP page
public onIncludedPage(com.optimyth.apm.model.portfolio.Component page, java.io.File

includedPage, BuilderContext ctx)
A  page-include relation
public onInvokedPage(com.optimyth.apm.model.portfolio.Component page, java.io.File invokedPage,

String role, BuilderContext ctx)
A Request.Redirect(stringliteral) was found
public onObjectReference(com.optimyth.apm.model.portfolio.Component page, String

referencedControl, BuilderContext ctx)
A COM object created by an ASP page: CreateObject() or Server.CreateObject() has been found
public onCss(String url, java.io.File resolvedFile, com.optimyth.apm.model.portfolio.Component
page, BuilderContext ctx)
public onScript(String url, java.io.File resolvedFile, String lang,

com.optimyth.apm.model.portfolio.Component page, BuilderContext ctx)
public onLink(String url, java.io.File resolvedFile, com.optimyth.apm.model.portfolio.Component

page, BuilderContext ctx)
public onImage(String url, java.io.File resolvedFile,

public onForm(String url, String resolvedUrl, String id, String method,

com.als.jsp.utils.JspElement t, com.optimyth.apm.model.portfolio.Component page, BuilderContext
ctx)
rules.asp.BasicAspCallback
Class BasicAspCallback
Structure
Methods Summary
Class BasicAspCallback

implements rules.asp.AspCallback AspPropertyDefinitions
package rules.asp
BasicAspCallback - Basic callback that resolves ASP common elements (pages, com objects, referred html elements)
Structure
Methods Summary
public void setWebappName(String webappName)
The name of the webapp to build if no webapp was provided (default: WEBAPP)
rules.aspnet.aspx
com.optimyth.apm.builder.rules.aspnet.aspx
com.optimyth.apm.builder.rules.aspnet.aspx
rules.aspnet.aspx.AspxBuilderRule
Class AspxBuilderRule
Goal
Technology
Structure
Methods Summary
Class AspxBuilderRule
package rules.aspnet.aspx
AspxBuilderRule -
This class may use as Software container the web applications discovered by the rules.aspnet.webapp.WebAppBuilderRule, or simply
use a single container named after the setAppname property as fallback.
Rule for resolving outgoing dependencies for ASPX WebPages (including "master" pages).
See also
rules.aspnet.aspx.AspxCallback
rules.aspnet.aspx.BasicAspxCallback
TagResolver
Goal
Rule for resolving outgoing dependencies for ASPX WebPages (including "master" pages).
Technology
ASP.NET
<bean id="apm_rule_aspx_tagresolver" class=
"com.optimyth.apm.builder.rules.aspnet.aspx.TagResolver">
<description>Resolver for static HTML resources</description>
<property name="tagExtractors">
<map>
<entry key="link">
<bean class=
"com.optimyth.apm.builder.rules.aspnet.aspx.TagResolver$CssTagExtractor">
<property name="acceptUnresolvedResources" value="true"/>
</bean>
</entry>
<entry key="script">
<bean class=
"com.optimyth.apm.builder.rules.aspnet.aspx.TagResolver$JavascriptTagExtractor">
</bean>
</entry>
<entry key="a">
<bean class="com.optimyth.apm.builder.rules.aspnet.aspx.TagResolver$ATagExtractor"
>
</bean>
</entry>
<entry key="img" value-ref="imgExtractor"/>
<entry key="asp:Image" value-ref="imgExtractor"/>
</map>
</property>
</bean>
<bean id="imgExtractor" class=

"com.optimyth.apm.builder.rules.aspnet.aspx.TagResolver$ImgTagExtractor">
</bean>
<bean id="apm_rule_aspx" class=

"com.optimyth.apm.builder.rules.aspnet.aspx.AspxBuilderRule">
<description>Resolves dependencies in ASP.NET elements and its code-behind artifacts
</description>
<property name="filter" ref="apm_filter_web_artifacts"/>
<property name="tagResolver" ref="apm_rule_aspx_tagresolver"/>
<property name="callback">
<bean class="com.optimyth.apm.builder.rules.aspnet.aspx.BasicAspxCallback"/>
</property>
<property name="taglibsToParse">
<list><value>asp</value></list>
</property>
<property name="webContents" value="Z:/proyectos/CEx/codePoC/codigoBurofax/aplicacion
Web"/>
</bean>
Structure
Methods Summary
public void setAppname(String appname)
Application name to set if the webapps were not discovered by a WebAppBuilderRule

public void setCallback(rules.aspnet.aspx.AspxCallback callback)
public void setWebContents(java.io.File webContents)
The directory where web content can be found (for resolving relative URLs to code resources).
If not specified, no static dependencies will be resolved
public void setTaglibsToParse(java.util.List taglibsToParse)
List of taglibs to consider when parsing JSP/JSP elements (e.g. custom UIComponents)
taglibsToParse List{String}. Each element is an URI of taglibs to parse.
public void setTagResolver(rules.aspnet.aspx.TagResolver tagResolver)
rules.aspnet.aspx.AspxCallback
Interface AspxCallback
Structure
Field Summary
Methods Summary
Interface AspxCallback
AspxCallback -
Structure
Field Summary
public static final ASPX_LANG
public static final ASCX_LANG
public static final ASMX_LANG

Methods Summary
public onItem(java.io.File file, com.optimyth.qaking.aspnet.model.AspnetItem item,

rules.aspnet.webapp.WebApp webapp, BuilderContext ctx)
Registers a new ASP.NET item (page, webservice, custom control) for the given webapp
file File containing the ASP.NET item (for page: .aspx, for webservice: .asmx, for control: .ascx)
item
webapp
ctx
returns Component that models the ASP.NET entity
public onIncludedPage(com.optimyth.apm.model.portfolio.Component page, java.io.File

includedPage, rules.aspnet.webapp.WebApp webapp, BuilderContext ctx)
A  page-include relation
public onInvokedPage(com.optimyth.apm.model.portfolio.Component page, java.io.File invokedPage,

rules.aspnet.webapp.WebApp webapp, BuilderContext ctx)
A Server.Tranfer(invokedPage) found
public onReferencedControl(com.optimyth.apm.model.portfolio.Component page,

com.optimyth.qaking.aspnet.model.Reference referencedControl, rules.aspnet.webapp.WebApp webapp,
BuilderContext ctx)
A <%@ Register
public onReferencedAssembly(com.optimyth.apm.model.portfolio.Component page,

com.optimyth.qaking.aspnet.model.Assembly assembly, rules.aspnet.webapp.WebApp webapp,
BuilderContext ctx)
public onTag(com.optimyth.apm.model.portfolio.Component page,
com.optimyth.qaking.aspnet.model.Register taglib, String name, rules.aspnet.webapp.WebApp webapp,
BuilderContext ctx)
public onRegisteredControl(com.optimyth.apm.model.portfolio.Component page,

com.optimyth.qaking.aspnet.model.Register reg, rules.aspnet.webapp.WebApp webapp, BuilderContext
ctx)
public onCss(String url, java.io.File resolvedFile, rules.aspnet.webapp.WebApp webapp,

public onScript(String url, java.io.File resolvedFile, String lang, rules.aspnet.webapp.WebApp

webapp, com.optimyth.apm.model.portfolio.Component page, BuilderContext ctx)
public onLink(String url, java.io.File resolvedFile, rules.aspnet.webapp.WebApp webapp,

public onImage(String url, java.io.File resolvedFile, rules.aspnet.webapp.WebApp webapp,

public onForm(String url, String resolvedUrl, String id, String method,

com.als.jsp.utils.JspElement t, rules.aspnet.webapp.WebApp webapp,
rules.aspnet.aspx.BasicAspxCallback
Class BasicAspxCallback
Structure
Methods Summary
Class BasicAspxCallback

implements rules.aspnet.aspx.AspxCallback AspnetPropertyDefinitions
BasicAspxCallback - Basic callback that resolves ASP.NET common elements (pages, user controls, webservices) and their (optional)
code-behind classes.
Structure
Methods Summary
The name of the webapp to build if no webapp was provided
rules.aspnet.webapp
com.optimyth.apm.builder.rules.aspnet.webapp
com.optimyth.apm.builder.rules.aspnet.webapp
rules.aspnet.webapp.BasicWebappCallback
Class BasicWebappCallback
Structure

implements rules.aspnet.webapp.WebappCallback AspnetPropertyDefinitions
package rules.aspnet.webapp
BasicWebappCallback - Default WebappCallback implementation.
Structure
rules.aspnet.webapp.WebAppBuilderRule
Class WebAppBuilderRule
Goal
Technology
Components
Relations
Code examples
Structure
Methods Summary
Class WebAppBuilderRule
WebAppRule -
The rule looks for web application descriptors (typically Web.Config) to identify the application root directory (APPDIR), then resolves the
assemblies (both in APPDIR/bin directory and in the application descriptor).
Discovered web applications are used by other rules, so logic is placed in the #initialize method. Other ASP.NET discovery rules, like
rules.aspnet.aspx.AspxBuilderRule, use the web application information collected by this rule.
TODO top-level now, hierarchical configs later

Rule for parsing resources and configurations used in ASP.NET applications.
See also
rules.aspnet.webapp.WebappCallback
rules.aspnet.aspx.AspxBuilderRule
Goal
Rule for parsing resources and configurations used in ASP.NET applications.
Technology
ASP.NET
Components
application Software for each webapp found, assemblies (library Software)
Relations
application configures> resource (Web.Config descriptor), application uses> library (referenced assemblies)
<bean id="apm_rule_webapp" class=

"com.optimyth.apm.builder.rules.aspnet.webapp.WebAppBuilderRule">
<description>Detects ASP.NET applications under analyzed directories</description>
<property name="webConfigPatterns" value="** /Web.Config"/>

<property name="xpathAppName"
value="concat(//ApplicationIdentity/add[@key='AppType']/@value, '-'
,//ApplicationIdentity/add[@key='AppID']/@value)"/>
<bean class="com.optimyth.apm.builder.rules.aspnet.webapp.BasicWebappCallback"/>
</property>
</bean>
Code examples
concat(//ApplicationIdentity/add[@key='AppType']/@value, '-'
,//ApplicationIdentity/add[@key='AppID']/@value)
Example of setXpathAppName method
Structure
Methods Summary
public void setCallback(rules.aspnet.webapp.WebappCallback callback)
Mandatory WebappCallback for registering web application and other webapp resources configured in Web.config descriptors
public void setBasedir(String basedir)
(Optional) directory from where ASP.NET applications will be discovered. If not set, all engine basedirs will be used
public void setWebConfigPatterns(String webxmlPatterns)
(Optional) Comma-separated list of ANT patterns for matching web.xml descriptors under basedirs
If not provided, ** /Web.Config will be used.
public void setXpathAppName(String xpathAppName)
XPath expression for computing the from contents of Web.Config file. If not set, the application name will be the name
of the webapp root directory.
xpathAppName
rules.aspnet.webapp.WebappCallback
Interface WebappCallback
Structure
Field Summary
Methods Summary
WebappCallback - Callback for updating model with all the elements found in a web.xml descriptor, of interest for "application discovery".
Structure
Field Summary
public static final NULL The /dev/null WebappCallback. All callback methods return null, ignoring the events
Methods Summary
public onWebApplication(rules.aspnet.webapp.WebApp webapp, BuilderContext ctx)
Invoked when a web application is discovered
public onAssembly(rules.aspnet.webapp.AssemblyInfo assembly,

com.optimyth.apm.model.portfolio.Software webapp, BuilderContext ctx)
Invoked when an assembly (.dll) is referenced in the webapp (placed under the /bin dir, or referenced in Web.Config)
rules.cl400
com.optimyth.apm.builder.rules.cl400
com.optimyth.apm.builder.rules.cl400
rules.cl400.CLScriptCallback
Interface CLScriptCallback
Structure
Field Summary
Methods Summary
Interface CLScriptCallback
package rules.cl400
CLScriptCallback - Callback that receive events from CLScriptRule
See also
rules.cl400.CLScriptRule
Structure
Field Summary
public static final LANG_CL400
public static final PROGTYPE_SCRIPT
public static final FILENAME

Methods Summary
public onScript(String scriptName, java.io.File scriptFile, BuilderContext ctx)
Called when a new CL script is being processed.
scriptName
scriptFile The source file for the script
ctx @return Component representing the script.
public onCalledProgram(com.optimyth.apm.model.portfolio.Component callerScript, String

calledProgName, String callType, BuilderContext ctx)
Called when a CALL dependency found originated from callerScript, to calledProgName,

using CL command callType.
callerScript caller
calledProgName Name of the program to run
callType CL Command used in the call (CALL, SBMJOB)
ctx BuilderContext
returns ApmRelation callerScript -> calledProgram, possibly null if relation was discarded.
public void resolveCalledProgs(BuilderContext ctx)
Resolves outgoing calls from caller Component to Components belonging to batch

or backend layers. To be called at rule's postProcess method.
public onDataAreaUsed(com.optimyth.apm.model.portfolio.Component script, String command,

com.optimyth.cl400.model.ObjectName dataArea, BuilderContext ctx)
Resolves usages of any data area from script
script
command CL Data area command used (one of CRTDTAARA,CHGDTAARA,RTVDTAARA,DLTDTAARA)
dataArea Name of the data area
ctx BuilderContext
returns ApmRelation for script -> dataArea, possibly null if relation was discarded.
public onFileUsed(com.optimyth.apm.model.portfolio.Component script, String command,
com.optimyth.cl400.model.ObjectName dataStore, String kind, BuilderContext ctx)
Resolves usages of any data store from script
script
command CL Data file usage command (one of OVRDBF or CPYF)
dataStore Filename
kind The kind of the file (data file, display file, DDS...)
ctx BuilderContext
returns ApmRelation for script -> dataStore, possibly null if relation was discarded.
public onIncludedFile(com.optimyth.apm.model.portfolio.Component script, String

qualifiedMember, com.optimyth.cl400.model.ObjectName srcFile, BuilderContext ctx)
Resolves INCLUDE SRCMEMBER(member) SRCFILE(file) command (from OS/400 6.1)
script
qualifiedMember
srcFile
ctx
returns ApmRelation with the include relation between script and CL/400 included script.
rules.cl400.CLScriptRule
Class CLScriptRule
Goal
Technology
Components
Relations
Structure
Methods Summary
Class CLScriptRule
package rules.cl400
CLScriptRule -
Extract dependencies from CL400 scripts
Goal
Extract dependencies from CL400 scripts
Technology
CL (OS/400 control language)
Components
Script is modelled as program
Relations
Outgoing dependencies resolved are:
called programs or jobs (via CALL or SBMJOB commands): CLScriptCallback#onCalledProgram

Data areas used: CLScriptCallback#onDataAreaUsed
Data files used: CLScriptCallback#onFileUsed
<bean name="apm_rule_cl400" class="com.optimyth.apm.builder.rules.cl400.CLScriptRule">

<description>Extract dependencies from CL/400 scripts</description>
<property name="filter" ref="cl400_filter"/>
<bean class="com.optimyth.apm.builder.rules.cl400.DefaultCLScriptCallback">
<property name="scriptApplication" value="myScriptApplication"/>
<property name="backendApplication" value="myBackendApplication"/>
</bean>
</property>
</bean>
Where apm_filter_cl is a FileFilter matching only CL scripts, and apm_callback_CLScript is a bean which
class implements rules.cl400.CLScriptCallback.
Structure
Methods Summary
public void setCallback(rules.cl400.CLScriptCallback callback)
CLScriptCallback to use for registering dependencies found in CL
rules.cl400.DefaultCLScriptCallback
Class DefaultCLScriptCallback
Structure
Methods Summary
Class DefaultCLScriptCallback
implements rules.cl400.CLScriptCallback
package rules.cl400
DefaultCLScriptCallback - Default implementation of rules.cl400.CLScriptCallback which basically resolves CL scripts found and their
calls to other programs or scripts, file usages (display files, data files or DDS), and included CL scripts.
<bean id="apm_callback_CLScript" class=

"com.optimyth.apm.builder.rules.cl400.DefaultCLScriptCallback">
</bean>
Where myScriptApplication and myBackendApplication are the names of the applications where scripts and
programs should be added, respectively. Both of them are optional.
Structure
Methods Summary
public void setScriptApplication(String scriptApplication)
public void setBackendApplication(String backendApplication)
The name of the backend software containing all referenced programs that are not scripts
If true (the default), all entity names are converted to upper-case; if false, case is not changed
public void setCalledResolver(rules.common.callresolution.CalledResolver calledResolver)
Resolves programs called in CL scripts

public void setIncludeResolver(rules.common.callresolution.CalledResolver includeResolver)
Resolves scripts included in CL scripts
rules.cobol
com.optimyth.apm.builder.rules.cobol
com.optimyth.apm.builder.rules.cobol
rules.cobol.BasicCobolDependenciesCallback
Class BasicCobolDependenciesCallback
Structure
Field Summary
Methods Summary
Class BasicCobolDependenciesCallback

implements rules.cobol.CobolDependenciesCallback
package rules.cobol
BasicCobolDependenciesCallback - A basic callback for responding to rules.cobol.CobolBuilderRule "events". Delegates model entities
construction into ComponentsHelper.
<bean id="apm_callback_Cobol" class=

"com.optimyth.apm.builder.rules.cobol.BasicCobolDependenciesCallback">
<property name="application" value="myApp"/>
<property name="dbType" value="myDBType"/>
<property name="dbInstance" value="myDBInstance"/>
</bean>
Where application, dbType and dbInstance are the application where entities should be added, the type of the
database and the name of its instance, respectively. All three properties are optional.
Structure
Field Summary
protected static final ROLE_DYNAMIC
protected static final ROLE_STATIC
protected static final mf
protected null boolean markUnresolvedDynamicCalls
Methods Summary
public void setFinder(rules.database.DatabaseObjectFinder finder)
public void setApplication(String application)
Name of container application, alias to #setSoftwareName (if not provided, defaults to ModelConstants#DEFAULT_APP)
public void setApplicationType(String applicationType)
Type of the container, alias to #setSoftwareType (default: application)
DB type for database entities usages discovered from EXEC SQL embedded statement. If not provided, defaults to
ModelConstants#DB2

DB instance name for database entities usages discovered from EXEC SQL embedded statement. If not provided, defaults to
ModelConstants#DB2
public void setDatafileTransform(<any> datafileTransform)
The transformation to apply on each datafile to get the name that will be given to datafiles from the info in its descriptor
public void setExcludePredicate(rules.common.Predicate exclude)
Predicate for database object names that, when matched, will skip the database object
public void setMarkUnresolvedDynamicCalls(boolean markUnresolvedDynamicCalls)
If true, unresolved dynamic CALLs will be created with the name of the Cobol variable as target program,
and a toCheck property set. If false (the default) the dynamic CALL will be ignored when value for target
variable cannot be resolved for the Cobol program.
public void setCopyClassifier(rules.cobol.CobolCopyClassifier classifier)
Copy classifier: identifies a copy by different strategies
protected void setReadWriteFlags(com.optimyth.apm.model.relation.ApmRelation rel, boolean

isWrite)
rules.cobol.BetterCobolDependenciesCallback
Class BetterCobolDependenciesCallback
Structure
Methods Summary
Class BetterCobolDependenciesCallback
extends from rules.cobol.BasicCobolDependenciesCallback
package rules.cobol
BetterCobolDependenciesCallback - CobolDependenciesCallback that will register Cobol programs, COPY includes (cobol -> copy),
program calls (cobol -> cobol, cobol -> CL) and table calls (cobol -> DB2).
Extends rules.cobol.BasicCobolDependenciesCallback with CalledResolver for more accurate resolution of COPYs, called entities, and
DDS files.
Structure
Methods Summary
Set resolver for components participating in call relations
public void setCopyResolver(rules.common.callresolution.CalledResolver copyResolver)
Set copy resolver
public void setDataStoreResolver(rules.common.callresolution.CalledResolver ddsResolver)
Data store resolver
rules.cobol.CobolBuilderRule

Class CobolBuilderRule
Goal
Components
Relations
Structure
Methods Summary
Class CobolBuilderRule
package rules.cobol
CobolBuilderRule - .
Resolves Cobol dependencies: called programs, included copybooks, used SQL tables, used datafiles and DSP (a.k.a. screen
formatting records)
See also
rules.cobol.CobolDependenciesCallback
Goal
Resolves Cobol dependencies: called programs, included copybooks, used SQL tables, used datafiles and DSP (a.k.a. screen
formatting records)
Components
Cobol program
Relations
When the rule detects one of the above dependencies on the Cobol program AST,
invokes the proper callback method:
CobolDependenciesCallback#onCobolProgram for the program under analysis.

CobolDependenciesCallback#onCalledProgram for static / dynamic calls (from CALL statement or EXEC CICS LINK).
CobolDependenciesCallback#onCopy for included COPYs (COPY clause or EXEC SQL INCLUDE).
CobolDependenciesCallback#onUsedSqlTable for tables used in EXEC SQL statements.
CobolDependenciesCallback#onUsedFile for datafile read/write operations.
CobolDependenciesCallback#onUsedDSP for screen formats (DSP) read/write operations.
<bean id="apm_rule_Cobol" class="com.optimyth.apm.builder.rules.cobol.CobolBuilderRule">

<property name="filter" ref="apm_filter_cobol"/>
<property name="callback" ref="apm_callback_Cobol"/>
<property name="copysToIgnore" value="myIgnoredCopysPattern"/>
<property name="callsToIgnore" value="myIgnoredCallsPattern"/>
<property name="parseSqlDependencies" value="true"/>
<property name="parseFileDependencies" value="true"/>
</bean>
Where apm_filter_cobol is a FileFilter matching only Cobol files, apm_callback_Cobol is a bean which class
implements CobolDependenciesCallback}, and myIgnoredCallsPattern are regular expressions matching
copys/calls that should be ignored, parseSqlDependencies property decides if embedded SQL should be parsed,
and parseSqlDependencies property decides if operations on datafiles should be analyzed. The last four properties
are optional.
Structure
Methods Summary
public void setCopysToIgnore(String copysToIgnore)
Regular expression with the COPY pattern to ignore (if not specified, all COPYs will be considered)
copysToIgnore Regular expression that, when matched by a COPY name, will ignore that COPY
public void setCallsToIgnore(String callsToIgnore)
Regular expression with the program pattern to ignore in both (if not specified, all COPYs will be considered)
callsToIgnore Regular expression that, when matched by a program name, will ignore the call to that program name
public void setParseSqlDependencies(boolean parseSqlDependencies)
If set to true, Cobol - SQL dependencies will be extracted from EXEC SQL statements
public void setParseCicsDependencies(boolean parseCicsDependencies)
If set to true, EXEC CICS blocks will be parsed and cobol-related dependencies resolved (basically LINK/XCTL command)
public void setParseFileDependencies(boolean parseFileDependencies)
If set to true, usages of physical files will be resolved
public void setAddCodeToRelations(boolean addCodeToRelations)

public void setParseSqlColumns(boolean parseSqlColumns)
If set to true, SQL queries and their relationships with used tables are inserted into the model. Ignored if parseSqlDependencies is
false
public void setAddSqlToModel(boolean addSqlToModel)
If set to true, SQL code is added as property into the queries. Ignored if parseSqlDependencies is false
public void setCallback(rules.cobol.CobolDependenciesCallback callback)
The CobolDependenciesCallback to use for adding detected dependencies to the model
rules.cobol.CobolDependenciesCallback
Interface CobolDependenciesCallback
Structure
Field Summary
Methods Summary
Interface CobolDependenciesCallback
package rules.cobol
CobolDependenciesCallback - Callback for resolving dependencies between Cobol programs and Cobol-SQL.
Structure
Field Summary
public static final COBOL_LANG
public static final CICS
public static final DDS
public static final DSP

public static final COBOL_SQL_TOCHECK Property for queries that cannot be parsed so the outgoing relations should be reviewed
Methods Summary
public onCobolProgram(String programName, com.als.core.ast.BaseNode root, BuilderContext ctx)
Callback called when currently analyzed sourcefile corresponds to a COBOL program
programName Name of current COBOL program

root BaseNode AST root node
ctx BuilderContext
returns Component in APM model, or null if the Cobol program should be discarded
public onCopy(com.optimyth.apm.model.portfolio.Component program, String copyName,

com.als.core.ast.BaseNode copyClause, BuilderContext ctx)
Adds a COPY program, linked to program. A copybook could be added in a COPY or EXEC SQL INCLUDE clauses.
program The Cobol program that COPYs the COPYBOOK

copyName The name of the COPYBOOK
copyClause The AST BaseNode with COPY or EXEC SQL INCLUDE statement
ctx BuilderContext
returns ApmRelation with left=program, right=new Component based on copyName, or null if the callback decided to ignore
the copy
public onUsedDDS(com.optimyth.apm.model.portfolio.Component program, String ddsName,

com.als.core.ast.BaseNode copyClause, boolean isWrite, BuilderContext ctx)
Adds a DDS usage (a data source referenced by the program)
program The Cobol program that COPYs the DDS

ddsName The name of the DDS file
copyClause The AST BaseNode with COPY statement
isWrite If true, the operation on the DSP was a WRITE ('send'); if false, was a READ ('receive')
ctx BuilderContext
returns ApmRelation with left=program, right=new Component based on ddsName, or null if the callback decided to ignore
the DDS reference
public onUsedDSP(com.optimyth.apm.model.portfolio.Component calling, String dspName,

com.als.core.ast.BaseNode copyClause, boolean isWrite, BuilderContext ctx)
Adds an usage of a DSP (a screen format)
calling The Cobol program that exec'ed the SQL

dspName DSP referenced, or DSP.screen
copyClause The AST BaseNode with COPY statement
isWrite If true, the operation on the DSP was a WRITE ('send'); if false, was a READ ('receive')
ctx BuilderContext
returns ApmRelation with left=program, right=new Component based on dspName, or null if the callback decided to ignore
the DSP reference
public onCalledProgram(com.optimyth.apm.model.portfolio.Component calling, String calledName,

boolean isDynamic, BuilderContext ctx)
Adds a CALL between two Cobol programs
calling The Cobol program that CALLs

calledName
isDynamic If true, the call is dynamic (program name is a variable, not a literal)
ctx BuilderContext
returns ApmRelation with left=calling, right=new program (calledName), or null if the callback decided to ignore the call
public onCalledProgram(com.optimyth.apm.model.portfolio.Component calling, String calledName,

com.als.cobol.rule.model.ExecCics cics, BuilderContext ctx)
Adds a CALL between two Cobol programs, using EXEC CICS LINK
calling The Cobol program that EXEC CICS LINK

calledName The called program
cics ExecCics that parsed the AST node representing the EXEC CICS LINK Statement
ctx BuilderContext
public onUnresolvedDynamicCalledProgram(com.optimyth.apm.model.portfolio.Component calling,

String targetVar, BuilderContext ctx)
Adds a CALL between a cobol program and an unresolved called program in a dynamic CALL.
calling The Cobol program that executed (e.g. in dynamic CALL) the program
targetVar Name of the variable containing the program name, which value cannot be resolved via static analysis
ctx BuilderContext
public onUsedFile(com.optimyth.apm.model.portfolio.Component calling,
rules.cobol.FileDescriptor fd, com.als.core.ast.BaseNode operation, BuilderContext ctx)
Adds an usage of a datafile.
calling
fd FileDescriptor bean representing the used file
operation BaseNode with the statement that uses the file represented by fd
ctx BuilderContext
returns ApmRelation with left=calling, right=new file resource (physical file), or null if the callback decided to ignore the file
usage
public onCicsTransaction(com.optimyth.apm.model.portfolio.Component calling, String transId,

com.als.cobol.rule.model.ExecCics cics, BuilderContext ctx)
Adds a CICS transaction usage (for START, RETURN or CANCEL commands) between a cobol program and CICS transaction.
transId Name of the CICS transaction
cics CICS command object
ctx BuilderContext
public onStoredProcedure(com.optimyth.apm.model.portfolio.Component calling, String procName,

String operation, BuilderContext ctx)
Add stored procedures or functions to database model
procName Procedure or function name
operation Type of operation Call
ctx BuilderContext
returns ApmRelation with left=calling, right=new procedure or function (calledName), or null if the callback decided to ignore
the call
rules.cobol.PlSqlCobolDependenciesCallback
Class PlSqlCobolDependenciesCallback
Structure
Field Summary
Class PlSqlCobolDependenciesCallback
extends from rules.cobol.BetterCobolDependenciesCallback

package rules.cobol
PlSqlCobolDependenciesCallback - CobolDependenciesCallback that will register Cobol programs, COPY includes (cobol -> copy),
program calls (cobol -> cobol, cobol -> CL) and table calls (cobol -> Pl/Sql).
Extends rules.cobol.BetterCobolDependenciesCallback for more accurate resolution of embedded SQL code.
Structure
Field Summary
public static final SELECT_STMT_PREDICATE
public static final DML_STMT_PREDICATE
public static final SQL_STMT_PREDICATE
public static final COLUMN_NODE_PREDICATE
rules.common
com.optimyth.apm.builder.rules.common
com.optimyth.apm.builder.rules.common
rules.common.BaseNodeCallback
Interface BaseNodeCallback
Structure
Field Summary
Methods Summary
Interface BaseNodeCallback
package rules.common
BaseNodeCallback - Generic callback for any BaseNode that should be considered as a PortfolioEntity.
Structure
Field Summary
public static final NULL Empty implementation. #onNode simply returns null.
Methods Summary
public onNode(com.als.core.ast.BaseNode node, BuilderContext context)
rules.common.XPathRule
Class XPathRule
Structure
Methods Summary
Class XPathRule
package rules.common
XPathRule - Generic APM discovery rule that will fetch AST BaseNodes matching an XPath expression, and invoke the registered
BaseNode callback on each matched BaseNode.
XPath is a "declarative" way to select certain constructs in the parsed source code. All the model update logic should be encoded in the
rules.common.BaseNodeCallback implementation, that will take as input matched BaseNode (and the BuilderContext).
See also
rules.common.BaseNodeCallback
<bean id="apm_rule_XPath" class="com.optimyth.apm.builder.rules.common.XPathRule">

<property name="filter" ref="apm_filter_common"/>
<property name="callback" ref="apm_callback_BaseNode"/>
</bean>
Where apm_filter_common is a FileFilter matching only desired files, and apm_callback_BaseNode is a bean
which class implements rules.common.BaseNodeCallback.
Structure
Methods Summary
public void setXpath(String xpath)
Sets XPath expression (that should return a List of matching AST BaseNodes)
xpath The XPath expression
public void setCallback(rules.common.BaseNodeCallback callback)
Sets the callback to use for notifying any BaseNode matched by the XPath expression on the currently analyzed AST.
callback BaseNodeCallback implementation
rules.cpp
com.optimyth.apm.builder.rules.cpp
com.optimyth.apm.builder.rules.cpp
rules.cpp.BasicCppCallback
Class BasicCppCallback
Structure
Methods Summary
Class BasicCppCallback

implements rules.cpp.CppCallback CppPropertyDefinitions
package rules.cpp
Basic creation of C++ classes, methods, functions
Structure
Methods Summary
public void setLevel(String level)
rules.cpp.BasicCppClassRule
Class BasicCppClassRule
Goal
Technology
Components
Relations
Structure
Field Summary
Methods Summary
Class BasicCppClassRule
package rules.cpp
TODO This rule is incomplete. Must resolve all dependencies in C/C++ sources...
Adds cpp file to the model and all dependencies to its includes files. This rule is really simple, to solve a more complete model, we're
working on CppClassRule.
Goal
Adds cpp file to the model and all dependencies to its includes files. This rule is really simple, to solve a more complete model, we're
working on CppClassRule.
Technology
C++
Components
Classes and Resources
Relations
This rule simply adds an 'includes' relation: class -> included header
<bean id="apm_rule_BasicCppClass" class=

"com.optimyth.apm.builder.rules.cpp.BasicCppClassRule">
<property name="application" value="TEST_CPP_APP"/> 
<property name="cppCallback" ref="cpp.callback"/> 
</bean>
<bean id="cpp.callback" class="com.optimyth.apm.builder.rules.cpp.BasicCppCallback">
<property name="level" value="class"/> 
</bean>
Structure
Field Summary
public static TOP_LEVEL_FUNCTION
Methods Summary
name of container software (if not provided, defaults to ModelConstants#DEFAULT_APP)
Type of the container software (default: SoftwareType#APPLICATION)
public void setCppCallback(rules.cpp.CppCallback cppCallback)

Simple callback for c++ components creation
rules.cpp.CppCallback
Interface CppCallback
Structure
Field Summary
Methods Summary
Interface CppCallback
package rules.cpp
Interface for cpp callback
Structure
Field Summary
public static final FILE_LEVEL
public static final CLASS_LEVEL
public static final FUNCTION_LEVEL
Methods Summary
set granularity level: 'FILE', 'CLASS' or 'FUNCTION'
public java.lang.String getLevel()
public onSourceFile(String path, BuilderContext ctx)
called when a new c source file is found

public onClass(com.optimyth.apm.model.portfolio.Component source, String name, BuilderContext
ctx)
called when a new c++ class is found
public onMethod(com.optimyth.apm.model.portfolio.Component source, String functionName,

BuilderContext ctx)
called when a new c++ method is found
public onFunction(com.optimyth.apm.model.portfolio.Component source, String functionName,

BuilderContext ctx)
called when a new c function is found
public onStruct(com.optimyth.apm.model.portfolio.Component source, String structName,

BuilderContext ctx)
called when a new c struct is found
public onCursor(com.optimyth.apm.model.portfolio.Component source, String cursorName,

BuilderContext ctx)
Pro*C cursor: it can be declared in a "EXEC SQL INCLUDEd" file, and used in the same file with different relations (open, fetch,
close)
public onInclude(java.io.File includedFile, com.optimyth.apm.model.portfolio.Component source,

BuilderContext ctx)
Called when #include directive in source matches a file present in code

public onCursorUse(com.optimyth.apm.model.portfolio.Component calling,
com.optimyth.apm.model.portfolio.Component cursor, String relationType, BuilderContext ctx)
open, fetch, close, etc...
public onCall(com.optimyth.apm.model.portfolio.Component calling,

com.optimyth.apm.model.portfolio.Component called, BuilderContext ctx)
rules.cpp.ExtendedCppCallback
Class ExtendedCppCallback
Structure
Methods Summary
Class ExtendedCppCallback
extends from BasicClassCallback

implements rules.cpp.CppCallback CppPropertyDefinitions
package rules.cpp
Basic creation of C++ classes, methods, functions
Structure
Methods Summary
public void setIncludeHeaders(String includeHeaders)
public void setResolver(rules.oo.ClassDepsResolver resolver)
The resolver for dependencies between Cpp classes

rules.cpp.ExtendedCppClassRule
Class ExtendedCppClassRule
Goal
Technology
Components
Relations
Structure
Field Summary
Methods Summary
Class ExtendedCppClassRule
extends from AbstractTypeResolverRule
package rules.cpp
TODO resolve enum, control class field / global variables usages

Adds C++ file to the model and all dependencies to its includes files.
Goal
Adds C++ file to the model and all dependencies to its includes files.
Technology
C++
Components
Relations
This rule simply adds an 'contains' relation: class -> included methods
<bean id="apm_rule_BasicCppClass" class=
"com.optimyth.apm.builder.rules.cpp.ExtendedCppClassRule">
<property name="application" value="TEST_CPP_APP"/> 
<property name="cppCallback" ref="cpp.callback"/> 
</bean>
<bean id="cpp.callback" class="com.optimyth.apm.builder.rules.cpp.ExtendedCppCallback">
<property name="level" value="class"/> 
</bean>
Structure
Field Summary
protected null cppCallback
Methods Summary
public void setIgnoredCallsSameClass(boolean ignoredCallsSameClass)
Simple callback for c++ components creation
rules.cpp.ProcDatabaseRule
Class ProcDatabaseRule
Goal
Technology
Components
Relations
Structure
Field Summary
Methods Summary
Class ProcDatabaseRule
package rules.cpp
It can be configured with different granularity levels (@see CppCallback): FILE, CLASS, FUNCTION
Adds cpp file to the model and all SQL dependencies to plsql objects.
Goal
Adds cpp file to the model and all SQL dependencies to plsql objects.
Technology
C++, PL/SQL
Components
Relations
This rule simply adds a 'uses' relation: source -> PL/SQL object
Structure
Field Summary
public static METHOD
public static TOP_LEVEL_FUNCTION
Methods Summary
public void setSqlLanguageSupport(com.als.core.language.LanguageSupport sqlLanguageSupport)
public void setPlsqlProcessor(rules.plsql.PlsqlCodeProcessor plsqlProcessor)
Inject here the PL/SQL code processor
public void setAllClasses(boolean allClasses)

set true if we want to add all classes (even those with no relations to PL/SQL sentences) to the model
rules.database.hibernate
com.optimyth.apm.builder.rules.database.hibernate
com.optimyth.apm.builder.rules.database.hibernate
rules.database.hibernate.AbstractHibernateRule
Class AbstractHibernateRule
Structure
Methods Summary
Class AbstractHibernateRule
package rules.database.hibernate
AbstractHibernateRule - Base class for rules that process Hibernate framework artefacts.
Structure
Methods Summary
public void setCallback(rules.database.hibernate.HibernateMappingCallback callback)
Hibernate callback to interact with model
rules.database.hibernate.BasicHibernateCallback
Class BasicHibernateCallback
Structure
Methods Summary
Class BasicHibernateCallback

implements rules.database.hibernate.HibernateCallback
BasicHibernateCallback - Default implementation for rules.database.hibernate.HibernateCallback with generic behaviour on descriptors
discovery, class-table mapping and relations between mapped classes.
<bean id="apm_callback_Hibernate" class=

"com.optimyth.apm.builder.rules.database.hibernate.BasicHibernateCallback">
<property name="application" value="myApplication"/>
<property name="dbName" value="myDBName"/>
</bean>
Where application, dbType and dbName are the application where entities should be added, the type of the
database and the name of its instance, respectively. All three properties are optional, with default values
ModelConstants#DEFAULT_APP, #dbType and #dbName respectively.
Structure
Methods Summary
Name of (fallback) container application (if not provided, defaults to ModelConstants#DEFAULT_APP)
public void setDbName(String dbName)
If false, the name of the tables referenced in Hibernate descriptors are not transformed.
If true (the default), the table (and schema) names are converted to upper-case.
rules.database.hibernate.BasicHibernateMappingCallback

Class BasicHibernateMappingCallback
Structure
Methods Summary
Class BasicHibernateMappingCallback

implements rules.database.hibernate.HibernateMappingCallback
BasicHibernateMappingCallback - Callback for Hibernate framework, used in hibernate rules.
Structure
Methods Summary
Name of (fallback) container application (if not provided, defaults to ModelConstants#DEFAULT_APP)
The fallback type of the database name (for schema databases) or database type
The fallback type of the database schema (for schema databases) or database name
public void setAddSqlToModel(boolean addSqlToModel)

If true, add sql components to model
public void setParser(com.optimyth.qaking.hibernate.hql.HqlSqlParser parser)
public void setQueryProcessor(rules.database.hibernate.QueryProcessor queryProcessor)
rules.database.hibernate.HibernateCallback
Interface HibernateCallback
Structure
Field Summary
Methods Summary
Interface HibernateCallback
HibernateCallback - Common interface for Hibernate callbacks, modeling descriptors, class mapped, and relations between mapped
classes.
Structure
Field Summary
public static final HIBERNATE_DESCRIPTOR
Methods Summary
public onDescriptor(java.io.File hbmFile, BuilderContext ctx)
public onClassTableMapping(String classname, com.optimyth.apm.model.portfolio.Component

descriptor, String table, BuilderContext ctx)
public onManyToOne(com.optimyth.apm.model.portfolio.Component classComp, String clazz, String
property, BuilderContext ctx)
public onOneToOne(com.optimyth.apm.model.portfolio.Component classComp, String clazz, String

property, BuilderContext ctx)
public onOneToMany(com.optimyth.apm.model.portfolio.Component classComp, String clazz, String

tableName, String property, BuilderContext ctx)
public onManyToMany(com.optimyth.apm.model.portfolio.Component classComp, String entity, String

tableName, String property, BuilderContext ctx)
rules.database.hibernate.HibernateDescriptorRule
Class HibernateDescriptorRule
Structure
Methods Summary
Class HibernateDescriptorRule
HibernateDescriptorRule - Parses XML Hibernate descriptors and extracts information about mapping between classes and database
tables.
<bean id="apm_rule_Hibernate" class=

"com.optimyth.apm.builder.rules.database.hibernate.HibernateDescriptorRule">
<property name="callback" ref="apm_callback_Hibernate"/>
<property name="hibernateMappingsPattern" value="** /*.hbm.xml"/>
</bean>
Where apm_callback_Hibernate is a bean which class implements rules.database.hibernate.HibernateCallback

and hibernateMappingsPattern is a comma-separated list of ANT Pattern matching desired files.
Structure
Methods Summary
public void setCallback(rules.database.hibernate.HibernateCallback callback)
public void setHibernateMappingsPattern(String hibernateMappingsPattern)
The (comma-separated) ANT patterns where hibernate mapping XML files could be found
rules.database.hibernate.HibernateJavaRule
Class HibernateJavaRule
Structure
Methods Summary
Class HibernateJavaRule
extends from rules.database.hibernate.AbstractHibernateRule
HibernateJavaRule - Analyze Java code for database mappings defined via JPA/Hibernate annotations, or queries declared in
JPA/Hibernate API.
Structure
Methods Summary
public void setHibernatePackages(String hibernatePackages)
Comma-separated list of additional hibernate API packages to consider. Add your own framework hibernate-extension packages
public void setSourceExtractor(com.optimyth.qaking.hibernate.extractor.SourceExtractor

sourceExtractor)
The SourceExtractor to use for extracting HQL/SQL code

rules.database.hibernate.HibernateMappingCallback
Interface HibernateMappingCallback
Structure
Field Summary
Methods Summary
Interface HibernateMappingCallback
HibernateMappingCallback - Models Hibernate entities in AIM model.

Used in all rules that process Hibernate elements.
See also
rules.database.hibernate.HibernateMappingRule
rules.database.hibernate.HibernateJavaRule
Structure
Field Summary
public static HIBERNATE_DESCRIPTOR Property for hibernate descriptors

final
public static HIBERNATE_PERSISTENT_TYPE Property for hibernate persistent types

final
public static HIBERNATE_PERSISTENT_COLLECTION Property for hibernate persistent collections

final
public static HIBERNATE_QUERY Property for hibernate named queries

final
public static HIBERNATE_SQL_TOCHECK Property for queries that cannot be parsed so the outgoing relations
final should be reviewed
public static HIBERNATE_SQL

final
public static NULL /dev/null implementation for HibernateMappingCallback, does nothing

final
Methods Summary
public onDescriptor(com.optimyth.qaking.hibernate.descriptor.HibernateMapping mapping,

BuilderContext ctx)
public onPersistentType(com.optimyth.qaking.hibernate.model.PersistentType pc,

com.optimyth.apm.model.portfolio.Component descriptor, BuilderContext ctx)
public onClientClass(String classname, java.io.File file, BuilderContext ctx)

public onTableUsage(String qualifiedTable, String operation,
com.optimyth.apm.model.portfolio.Component source, BuilderContext ctx)
public onSequenceUsage(String qualifiedSequence, com.optimyth.apm.model.portfolio.Component

source, BuilderContext ctx)
public onPrimaryKey(com.optimyth.qaking.hibernate.model.Id id,

com.optimyth.apm.model.portfolio.Component persistentType, BuilderContext ctx)
public onPersistentCollection(com.optimyth.qaking.hibernate.model.PersistentCollection pc,

public onAssociation(com.optimyth.qaking.hibernate.model.Association assoc,

public onQuery(com.optimyth.qaking.hibernate.model.Query query,

com.optimyth.apm.model.portfolio.Component container, BuilderContext ctx)
public onQuery(com.optimyth.qaking.hibernate.extractor.Fragment fragment,

com.optimyth.apm.model.portfolio.Component caller, BuilderContext ctx)
public onNoSqlQuery(com.als.core.ast.BaseNode where, com.optimyth.apm.model.portfolio.Component

caller, BuilderContext ctx)
public onProcedureCall(String qualifiedProc, boolean isFunction,

public void onEnd(BuilderContext ctx)
rules.database.hibernate.HibernateMappingRule
Class HibernateMappingRule
Structure
Field Summary
Methods Summary
Class HibernateMappingRule
extends from rules.database.hibernate.AbstractHibernateRule
HibernateMappingRule - Parses XML Hibernate descriptors and extracts information about mapping between classes and database
tables.
The alternate rules.database.hibernate.HibernateJavaRule process Java sources looking for Java5 annotation-based mapping
information and analyze programmatic queries (HQL or native SQL) for dependencies (with persistent classes or database objects).
See also
HibernateVisitor
<bean id="aim.hibernate.rule" class=

"com.optimyth.apm.builder.rules.database.hibernate.HibernateMappingRule">
<property name="callback" ref="aim.hibernate.callback"/>
<property name="filter" ref="aim.hibernate.filter.mappings"/>
</bean>
Where aim.hibernate.callback is a bean which class implements

rules.database.hibernate.HibernateMappingCallback and aim.hibernate.filter.mappings is a filter for
Hibernate mapping descriptors.
Structure
Field Summary
public static final DEFAULT_FILTER
Methods Summary
public void setProcessPhase(int processPhase)
When to process Hibernate .hbm.xml descriptors:

At initialize (<0, the default),
at visit (=0),
at postProcess (>0)
rules.database.ibatis
com.optimyth.apm.builder.rules.database.ibatis
com.optimyth.apm.builder.rules.database.ibatis
rules.database.ibatis.AbstractIbatisRule
Class AbstractIbatisRule
Structure
Methods Summary
Class AbstractIbatisRule
package rules.database.ibatis
AbstractIbatisRule -
Structure
Methods Summary
public void setCallback(rules.database.ibatis.IbatisCallback callback)
rules.database.ibatis.BasicIbatisCallback
Class BasicIbatisCallback
Structure
Methods Summary
Class BasicIbatisCallback

implements rules.database.ibatis.IbatisCallback
BasicIbatisCallback -
Structure
Methods Summary
public void setQueryProcessor(rules.database.ibatis.QueryProcessor queryProcessor)

public void setAddSqlCode(boolean addSqlCode)
If true, add SQL as a property to sql component
rules.database.ibatis.IbatisCallback
Interface IbatisCallback
Structure
Field Summary
Methods Summary
Interface IbatisCallback
IbatisCallback -
Structure
Field Summary

public static final IBATIS
public static final IBATIS_DESCRIPTOR
public static final IBATIS_MAPPER_CLASS
public static final IBATIS_SQL_STATEMENT
public static final IBATIS_CLIENT
public static final IBATIS_SQL
public static final IBATIS_SQL_TOCHECK
Methods Summary
public onDescriptor(java.io.File file, com.optimyth.apm.model.portfolio.Component parent,

BuilderContext ctx)
public onSql(String id, String sql, String op, com.optimyth.apm.model.portfolio.Component

container, BuilderContext ctx)
public onMapperClass(String className, BuilderContext ctx)
public onClientClass(String className, com.optimyth.apm.model.portfolio.Component target,

String method, BuilderContext ctx)
public onUsedTable(String tableName, String operation,

com.optimyth.apm.model.portfolio.Component sqlComponent, BuilderContext ctx)
public onUsedSequence(String sequenceName, String operation,

com.optimyth.apm.model.portfolio.Component dbQuery, BuilderContext ctx)
public onCall(String procedureName, boolean isFunction,

rules.database.ibatis.IbatisDescriptorRule
Class IbatisDescriptorRule
Structure
Methods Summary
Class IbatisDescriptorRule
extends from rules.database.ibatis.AbstractIbatisRule
IbatisDescriptorRule - Parses iBatis/myBatis XML configuration / mapper descriptors. SQL statements found will be registered as
Components in the software for the descriptor. TODO how to process and model resultMap / parameterMap / resultType /
parameterType ?
Structure
Methods Summary
public void setDescriptorFilter(java.io.FileFilter filter)
The file filter for iBatis XML descriptors. Configuration may use a particular Ant pattern for a specific naming convention.
When not given, *\/.xml Ant pattern will be used, and files processed to see if they correspond to iBatis configuration / mapper
XML files.
public void setDescriptorResolver(rules.common.fileresolution.FileResolver descriptorResolver)
FileResolver to find the included resources in sql-mapping-config.xml (root) descriptors.

The default is DescriptorFileResolver, that locates resources as relative to the root
descriptor or in Maven-style layouts.
public void setExpressionValuesResource(org.springframework.core.io.Resource resource)
Resource of an optional .properties file to be used for replacing dynamic macros (like ${myvar})
in SQL statements found in iBatis descriptor
public void setDefaultExpressionValue(String value)
The default value for dynamic expressions ${myvar} in iBatis descriptors
rules.database.ibatis.IbatisJavaRule
Class IbatisJavaRule
Structure
Methods Summary
Class IbatisJavaRule
extends from rules.database.ibatis.AbstractIbatisRule
IbatisJavaRule - Rule that process java classes for iBatis annotations and calls to iBatis API.
Structure
Methods Summary
public void setApiResolver(rules.database.ibatis.IbatisApiResolver apiResolver)
The instance of IbatisApiResolver to use for resolving the ID of the mapped SQL statement
from a call to iBatis API (default: DefaultIbatisApiResolver).
rules.database.schema
com.optimyth.apm.builder.rules.database.schema
com.optimyth.apm.builder.rules.database.schema
rules.database.schema.DatabaseSchemaCallback
Class DatabaseSchemaCallback
Structure
Methods Summary
Class DatabaseSchemaCallback
package rules.database.schema
Structure
Methods Summary

If true (the default), names of database elements are converted to upper-case; if false, database element names are left
unchanged
public void setSchemaAwareBeans(java.util.List schemaAwareBeans)
rules.database.schema.DatabaseSchemaRule
Class DatabaseSchemaRule
Structure
Methods Summary
Class DatabaseSchemaRule

implements IAnalysisDirectoryProvider
DatabaseSchemaRule - Models database components from schema descriptors extracted by schemaExtract script (GLOBAL plugin).
Configuration: Specify either schemaFile (full path to the XML schema descriptor file), or schemaDirectory + schemaFilePattern (if
multiple schema descriptors need to be processed).
This rule models schema entity with tables (linked to indexes, primary key, and other tables in foreign key relations), and views.
Database-specific rules may extend this to add other entities and relations (like triggers, stored procedures, etc.). For example, for
Oracle, rules.database.schema.OracleDatabaseSchemaRule resolves more entities (subclasses override #processSchemaExtension).
See also
rules.database.schema.OracleDatabaseSchemaRule
Structure
Methods Summary
public void setSchemaFile(java.io.File schemaFile)
The XML schema descriptor to analyze. Set either schemaFile or schemaDirectory+schemaFilePatterns.

if schemaFile is set, schemaDirectory + schemaFilePatterns are ignored.
public void setSchemaDirectory(String schemaDirectories)
The directory where schema descriptors and SQL entities are exported
public void setSchemaDirectories(java.util.List schemaDirectories)
public void setSchemaFilePatterns(String schemaFilePatterns)
Comma-separated list of Ant-like patterns for schema files in schema directory
public void setCallback(rules.database.schema.DatabaseSchemaCallback callback)
Callback for schema entities and relations (if not set, a DatabaseSchemaCallback instance will be used)
public void setJdbcSqlListener(rules.j2ee.jdbc.JdbcSqlListener jdbcSqlListener)
If set, the views SQL code is parsed for relations with other views/tables
public void setDatabaseIndex(rules.database.schema.DatabaseIndex databaseIndex)
Utility to resolve references to database entities, with different levels of qualification
rules.database.schema.OracleDatabaseSchemaRule
Class OracleDatabaseSchemaRule
Structure
Methods Summary
Class OracleDatabaseSchemaRule
extends from rules.database.schema.DatabaseSchemaRule
OracleDatabaseSchemaRule - Models extended schema entities for Oracle. Sample schema entities produced: <pre> software(dn:
'sys=DB', type: 'software', name: 'DB', description: 'database DB', softwareType: 'database') component(dn: 'sys=DB,db=SCHEMA',
type: 'component', name: 'SCHEMA', description: 'database schema DB.SCHEMA', componentType: 'databaseInstance') component(dn:
'sys=DB,db=SCHEMA,table=T', type: 'component', name: 'VISA_FICHEROS_ENVIADOS', description: 'Table SCHEMA.T',
componentType: 'table', sqlType: 'table', columns: 'ID,FIELD1,FIELD2,FIELD3', rows: 1612972) component(dn:
'sys=DB,db=SCHEMA,table=T,index=T_ID02', type: 'component', name: 'T_ID02', componentType: 'index', description: 'Index on table
T', columns: 'ID,FIELD1') component(dn: 'sys=DB,db=SCHEMA,table=T,index=T_PK', type: 'component', name: 'T_PK',
componentType: 'primaryKey', description: 'PrimaryKey on table T', columns: 'ID') component(dn: 'sys=DB,db=SCHEMA,table=V', type:
'component', name: 'V', description: 'Table V', componentType: 'view', sqlType: 'view', columns: 'F1,...,Fn', rows: 0, sqlcode: 'SELECT *
FROM T') </pre>
Structure
Methods Summary
public void setExtendedSchemaFile(java.io.File extendedSchemaFile)
The XML schema descriptor to analyze. Set either extendedSchemaFile or schemaDirectory+extendedSchemaFilePatterns.

if schemaFile is set, schemaDirectory + schemaFilePatterns are ignored.
public void setExtendedSchemaFilePatterns(String extendedSchemaFilePatterns)
Comma-separated list of Ant-like patterns for schema files in schema directory
rules.dotnet
com.optimyth.apm.builder.rules.dotnet
com.optimyth.apm.builder.rules.dotnet
rules.dotnet.CSharpClassRule
Class CSharpClassRule
Goal
Technology
Components
Relations
Structure
Class CSharpClassRule
package rules.dotnet
CsharpClassRule -
A class rule that will resolve outgoing dependencies for C# class.
See also
rules.oo.AbstractClassRule
rules.oo.ClassCallback
ClassDepsResolver
Goal
A class rule that will resolve outgoing dependencies for C# class.
Technology
csharp
Components
Component (componentType = class)
Relations
inheritance, calls, field reference relations to outgoing classes.
<bean id="apm_rule_csharp" class="com.optimyth.apm.builder.rules.dotnet.CSharpClassRule">

<description>Resolves dependencies in C# classes and code-behind artifacts</description>
<property name="filter" ref="apm_filter_csharp"/>
<property name="callback" ref="apm_rule_csharp_cb"/>
<property name="resolver" ref="apm_rule_csharp_classDepsResolver"/>
<property name="resolveInheritance" value="true"/>
<property name="resolveCalls" value="true"/>
<property name="resolveInstantiations" value="true"/>
<property name="resolveFieldReferences" value="true"/>
<property name="resolveTypeReferences" value="true"/>
</bean>
Where callback is the rules.oo.ClassCallback to use for interacting with the model, and ClassDepsResolver that will
decide if outgoing classes should be registered in the model.
Structure
rules.dotnet.DotnetClassCallback
Class DotnetClassCallback
Structure
Class DotnetClassCallback
DotnetClassCallback - A BasicClassCallback for .net languages, uses specific logic for inferring the language from file extensions; when
the language could not be inferred, "dotnet" is used as language name.
Structure
rules.dotnet.DotnetClassRule
Class DotnetClassRule
Structure
Methods Summary
Class DotnetClassRule
DotnetClassRule - Composite class for any dotnet language
Structure
Methods Summary
public void setRules(java.util.Map rules)
The language-specific rules (keyed by language name, like csharp or vbnet) that will be applied
rules.dotnet.DotnetProjectRule
Class DotnetProjectRule
Structure
Field Summary
Methods Summary
Class DotnetProjectRule
DotnetProjectRule - Analyzes references to a set of (Visual Studio) .net projects, discovering software entities (modules or applications)
for each .vbproj / .csproj found, and resolving references to external resources (application assemblies).
Structure
Field Summary
public static final DEFAULT_CSPROJ_PATTERN
public static final DEFAULT_VBPROJ_PATTERN
public static final DEFAULT_SCHEMA_URI
public static final IMAGE_EXTENSIONS
public static final PROJECT_PROPERTY

Methods Summary
public void setProjectFilePatterns(String projectFilePatterns)
Comma-separated list of ANT patterns for matching .*proj files (relative to basedirs). Defaults to #DEFAULT_CSPROJ_PATTERN
and #DEFAULT_VBPROJ_PATTERN
public void setAppNameXpath(String xpath)
XPath expression for fetching application name (defaults to /PropertyGroup/AssemblyName)
public void setLanguage(String language)
Language for applications (default: csharp)
public void setResolveExternalAssemblies(boolean resolveExternalAssemblies)
If false, assemblies referenced but not matching applications analized will NOT be added to the model (default: true)
public void setResolveStandardAssemblies(boolean resolveStandardAssemblies)
If true, dot.net standard assemblies will be added to the model (default: false)
public void setResolveResources(boolean resolveResources)
If true, resolve resx files and images

public void setResolveImages(boolean resolveImages)
If true, resolve images files
public void setResolveArtifacts(boolean resolveArtifacts)
If true (the default), resolve artifacts
public void setSchemaUri(String schemaUri)
The schema URI to use for the .*proj files (default: #DEFAULT_SCHEMA_URI)
The ComponentsHelper implementation to use (default: standard ComponentsHelper)
rules.dotnet.VbNetClassRule
Class VbNetClassRule
Goal
Technology
Components
Relations
Structure
Field Summary
Class VbNetClassRule
VbNetClassRule -
A class rule that will resolve outgoing dependencies for Visual Basic .NET class.
See also
ClassDepsResolver
Goal
A class rule that will resolve outgoing dependencies for Visual Basic .NET class.
Technology
vbnet
Components
Component (componentType = class)
Relations
inheritance, calls, field reference relations to outgoing classes.
<bean id="apm_rule_vbnet" class="com.optimyth.apm.builder.rules.dotnet.VbNetClassRule">

<description>Resolves dependencies in vb.net classes and code-behind artifacts
</description>
<property name="filter" ref="apm_filter_vbnet"/>
<property name="callback" ref="apm_rule_vbnet_cb"/>
<property name="resolver" ref="apm_rule_vbnet_classDepsResolver"/>
</bean>
Where callback is the rules.oo.ClassCallback to use for interacting with the model, and ClassDepsResolver that will
decide if outgoing classes should be registered in the model.
Structure
Field Summary
public static final OO_DECLARATION
rules.grouping
com.optimyth.apm.builder.rules.grouping
com.optimyth.apm.builder.rules.grouping
rules.grouping.GroupRule
Class GroupRule
Structure
Methods Summary
Class GroupRule
package rules.grouping
Structure
Methods Summary
public void setGroupDescriptors(java.util.List groupDescriptors)
Inject a list of {{GroupDescriptor}}s, describing dynamic groups
public void setClassifier(com.optimyth.apm.model.group.GroupClassify classifier)
Inject a classfier responsible for interpreting filters and create membership relations
The ComponentsHelper implementation to use (default: standard ComponentsHelper)
rules.html
com.optimyth.apm.builder.rules.html
com.optimyth.apm.builder.rules.html
rules.html.DefaultHtmlCallback
Class DefaultHtmlCallback
Structure
Methods Summary
Class DefaultHtmlCallback
implements rules.html.HtmlCallback
package rules.html
DefaultHtmlCallback - Basic implementation of rules.html.HtmlCallback.
Structure
Methods Summary
public void setWebApplication(String webApplication)
rules.html.DynamicHtmlRule
Class DynamicHtmlRule
Goal
Structure
Methods Summary
Class DynamicHtmlRule
extends from rules.html.HtmlRule
package rules.html
DynamicHtmlRule -
Extends HtmlRule by letting a webapp resolver determine the name of the web application container where each discovered html pages
and their dependencies should be placed.
See also
WebAppResolver
Goal
Extends HtmlRule by letting a webapp resolver determine the name of the web application container where each discovered html pages
and their dependencies should be placed.
<bean id="apm_rule_html_tags" class="java.util.HashMap">
<constructor-arg><map>
<entry key="link"><bean class=
"com.optimyth.apm.builder.rules.html.HtmlRule$CssTagExtractor"><property name=
"acceptUnresolvedResources" value="true"/></bean></entry>
<entry key="a"><bean class=
"com.optimyth.apm.builder.rules.html.HtmlRule$ATagExtractor"><property name=
<entry key="img"><bean class=
"com.optimyth.apm.builder.rules.html.HtmlRule$ImgTagExtractor"><property name=
<entry key="script"><bean class=
"com.optimyth.apm.builder.rules.html.HtmlRule$JavascriptTagExtractor"><property name=
<entry key="frame"><bean class=
"com.optimyth.apm.builder.rules.html.HtmlRule$FrameTagExtractor"><property name=
<entry key="iframe"><bean class=
<entry key="form"><bean class=
"com.optimyth.apm.builder.rules.html.HtmlRule$FormTagExtractor"><property name=
</map></constructor-arg>
</bean>
<bean id="apm_rule_html" class="com.optimyth.apm.builder.rules.html.DynamicHtmlRule">

<description>Resolves dependencies from HTML files in multiple web apps</description>
<property name="webAppResolver">
<bean class="com.optimyth.apm.builder.rules.html.WebAppResolver">
<property name="patterns"><map>
<entry key="MyFirstWebApp" value="src/FirstApp/WebContent"/>
<entry key="MySecondWebApp" value="src/SecondApp/WebContent"/>
</map></property>
</bean>
</property>
<property name="tagsToParse" value="link,a,img,script,frame,iframe,form"/>
<property name="extractors" ref="apm_rule_html_tags"/>
<property name="filter" ref="filter_html"/>
<property name="callback"><bean class=
"com.optimyth.apm.builder.rules.html.DefaultHtmlCallback">
<property name="resolveArtifacts" value="true"/>
<property name="webApplication" value="UnknownWebApp"/>
</bean></property>
</bean>
Structure
Methods Summary
public void setWebAppResolver(rules.html.WebAppResolver webAppResolver)
the class that will be used to resolve entities
rules.html.HtmlCallback

Interface HtmlCallback
Structure
Field Summary
Methods Summary
Interface HtmlCallback
package rules.html
HtmlCallback - Callback used by extraction rules for "plain html" code. Provides callback methods for the usual elements found in HTML
pages (currently: page, css, script, image, link, form).
Structure
Field Summary
public static final HTML_LANG
public static final CSS_LANG
public static final PAGE_EXTS The (lowercase) extensions for pages, static or dynamic: htm,html,xhtml,jsp,asp,jspx,aspx,php
Methods Summary
public onPage(String relativeUrl, BuilderContext ctx)
public onCss(rules.html.TagResource tagResource, com.optimyth.apm.model.portfolio.Component

page)
public onScript(rules.html.TagResource tagResource, String lang,

com.optimyth.apm.model.portfolio.Component page)
public onImage(rules.html.TagResource tagResource, com.optimyth.apm.model.portfolio.Component

page)
public onLink(rules.html.TagResource tagResource, com.optimyth.apm.model.portfolio.Component

page)
public onForm(rules.html.TagResource tagResource, String id, String method,

com.als.parsers.html.Tag t, com.optimyth.apm.model.portfolio.Component page)
public void setWebApplication(String webApplication)
rules.html.HtmlRule
Class HtmlRule
Goal
Components
Relations
Structure
Methods Summary
Class HtmlRule
package rules.html
HtmlRule - BuilderRule for extracting dependencies between HTML files and outgoing static dependencies (for example, CSS,
JavaScript, links, images, forms...)
This rule places all components discovered under the web application configured in the callback. The derived
rules.html.DynamicHtmlRule uses a WebAppResolver for determining which application the components should be placed, based on
file/url patterns.
Extracts static dependencies in HTML files (CSS stylesheets, JavaScript files, links, images, forms, frames...)
See also
rules.html.HtmlCallback
TagResource
Goal
Extracts static dependencies in HTML files (CSS stylesheets, JavaScript files, links, images, forms, frames...)
Components
Component of type page (language=html)
Relations
See rules.html.HtmlCallback for the relations that may be resolved for css, scripts, links, forms, and images.
<bean id="apm_rule_html_tags" class="java.util.HashMap">
<constructor-arg><map>
<entry key="link"><bean class=
"com.optimyth.apm.builder.rules.html.HtmlRule$CssTagExtractor"><property name=
<entry key="a"><bean class=
"com.optimyth.apm.builder.rules.html.HtmlRule$ATagExtractor"><property name=
<entry key="img"><bean class=
"com.optimyth.apm.builder.rules.html.HtmlRule$ImgTagExtractor"><property name=
<entry key="script"><bean class=
"com.optimyth.apm.builder.rules.html.HtmlRule$JavascriptTagExtractor"><property name=
<entry key="frame"><bean class=
<entry key="iframe"><bean class=
<entry key="form"><bean class=
"com.optimyth.apm.builder.rules.html.HtmlRule$FormTagExtractor"><property name=
</map></constructor-arg>
</bean>
<bean id="apm_rule_html" class="com.optimyth.apm.builder.rules.html.HtmlRule">

<description>Resolves dependencies from HTML files</description>
<property name="filter" ref="apm_filter_html"/>
<property name="webContents" value="${web.src}"/>
<property name="tagsToParse" value="link,a,img,script,frame,iframe,form"/>
<property name="extractors" ref="apm_rule_html_tags"/>
<property name="callback"><bean class=
"com.optimyth.apm.builder.rules.html.DefaultHtmlCallback">
<property name="resolveArtifacts" value="true"/>
<property name="webApplication" value="MyWebAPP"/>
</bean></property>
</bean>
The (optional) extractors property permits fine-grained configuration of each tag extractor.
Structure
Methods Summary
public void setCallback(rules.html.HtmlCallback callback)
HtmlCallback to use for model operations
public void setExtractors(java.util.Map extractors)

Inject the Map(String, TagExtractor) extractors for any HTML tag that should be processed by paired TagExtractor. If set via this
method, tagsToParse property is ignored
public void setTagsToParse(String tags)
Comma-separated list of tags to parse (defaults to "link,script,a,img,form"). If injected via "extractors", this property is ignored.
The directory where web content can be found (for resolving relative URLs to code resources)
rules.j2ee
com.optimyth.apm.builder.rules.j2ee
com.optimyth.apm.builder.rules.j2ee
rules.j2ee.JavaDependenciesCallback
Interface JavaDependenciesCallback
Structure
Methods Summary
Interface JavaDependenciesCallback
package rules.j2ee
JavaDependenciesCallback - Generic callback for Java classes.
Structure
Methods Summary
public onClass(org.objectweb.asm.tree.ClassNode clazz, BuilderContext ctx)
rules.j2ee.ejb

com.optimyth.apm.builder.rules.j2ee.ejb
com.optimyth.apm.builder.rules.j2ee.ejb
rules.j2ee.ejb.BasicEjb3DependenciesCallback
Class BasicEjb3DependenciesCallback
Structure
Methods Summary
Class BasicEjb3DependenciesCallback

implements rules.j2ee.ejb.Ejb3DependenciesCallback EjbPropertyDefinitions
package rules.j2ee.ejb
EJB callback, works for both rules.j2ee.ejb.EjbDescriptorRule (1.x or 2.x, descriptor-based) and rules.j2ee.ejb.Ejb3BuilderRule (3.x,
Java5 annotation-based).
Structure
Methods Summary
Name of container application (if not provided, defaults to ModelConstants#DEFAULT_APP)
public void setDatabaseName(String dbName)
Name of database
public void setDefaultSchema(String dbDefaultSchema)
(optional) Name of default schema name: for referred tables without a specified schema
public void setClassCallback(rules.oo.ClassCallback classCallback)
(optional) ClassCallback that may be called to create classes so that we can relate them with EJBs
rules.j2ee.ejb.Ejb3BuilderRule
Class Ejb3BuilderRule
Structure
Methods Summary
Class Ejb3BuilderRule
extends from AbstractClassRule

implements EjbPropertyDefinitions
Ejb3BuilderRule - Looks for EJB3 beans that use javax.ejb.* annotations for declaring EJB properties. Please note that there is an
alternative way to declare EJB using a descriptor (e.g. EJB2's ejb-jar.xml descriptor).
<bean id="apm_rule_ejb3" class="com.optimyth.apm.builder.rules.j2ee.ejb.Ejb3BuilderRule">

<property name="filter" ref="apm_filter_ejb3"/>
<property name="ejbCallback" ref="apm_callback_Ejb"/>
<property name="resolveEntities" value="false" /> (default value = true)
</bean>
Where apm_filter_ejb3 is a FileFilter matching only desired files, and apm_callback_Ejb is a bean which class
implements rules.j2ee.ejb.Ejb3DependenciesCallback.
Structure
Methods Summary
public void setResolveEntities(boolean resolveEntities)
Resolve dependencies with database objects in EBJ3 entity beans, described in annotations
public void setEjbCallback(rules.j2ee.ejb.Ejb3DependenciesCallback ejbCallback)
EJB3 dependencies callback
public void setCallback(rules.oo.ClassCallback callback)
Java dependencies callback.
rules.j2ee.ejb.Ejb3DependenciesCallback
Interface Ejb3DependenciesCallback
Structure
Field Summary
Methods Summary
Interface Ejb3DependenciesCallback
Ejb3DependenciesCallback - Callback used in rules.j2ee.ejb.Ejb3BuilderRule and rules.j2ee.ejb.EjbDescriptorRule for processing EJB

dependences.
Structure
Field Summary
public static final JAVA_LANG
public static final NULL The /dev/null Ejb3DependenciesCallback
Methods Summary

public onDescriptor(java.io.File ejbDescriptor, BuilderContext ctx)
Registers an EJB descriptor file (e.g. used with EJB 1.x / 2.x)
public onClass(String classname, BuilderContext ctx)
Registers an EJB artifact class
public onEJB(String ejbName, com.optimyth.apm.model.Property ejbType, String beanClass,

BuilderContext ctx)
Invoked when an EJB bean of the given ejbType is found. This method return the ejb component (an element)
with
ejbName The name (identifier) of the ejb

ejbType one of EjbPropertyDefinitions#EJB_STATELESS,
EjbPropertyDefinitions#EJB_STATEFUL,
EjbPropertyDefinitions#EJB_MESSAGEDRIVEN or
EjbPropertyDefinitions#EJB_ENTITY
beanClass The bean (implementation) fully qualified classname
ctx BuilderContext
public onReferencedDatabaseItem(com.optimyth.apm.model.portfolio.Component ejb,

rules.j2ee.ejb.QualifiedName dbItem, java.util.List dbTypes, BuilderContext ctx)
public onReferencedEjb(com.optimyth.apm.model.portfolio.Component source,

com.optimyth.apm.model.portfolio.Component calledBean, BuilderContext ctx)
Invoked when a reference to an EJB is referenced by another component (e.g. another EJB, or another class).
source Component that shows a reference to an EJB

calledBean The referenced EJB
ctx
public onConfiguredBean(com.optimyth.apm.model.portfolio.Component descriptor,
com.optimyth.apm.model.portfolio.Component ejb, BuilderContext ctx)
Registers a "configures" dependency between EJB descriptor (1.x or 2.x) and ejb declared in that descriptor
public onEjbPart(com.optimyth.apm.model.portfolio.Component ejb, String className,

com.optimyth.apm.model.PropertyDefinition type, BuilderContext ctx)
Registers one of the consituent class part of the EJB (local/remote interface, local/remote home interface, bean class, primary key
class...)
public onEjbInterface(rules.j2ee.ejb.Ejb3Interface interfac,

com.optimyth.apm.model.portfolio.Component ejb, BuilderContext ctx)
Invoked when a local or remote interface is found.

Implementations may register the interface class, create relation with the interface class,
or simply add marker properties in the ejb component.
interfac
ejb
ctx
public onTableColumns(com.optimyth.apm.model.relation.ApmRelation ejbTableRel, java.util.Set

columns)
Add columns to the ejb -> table relation.
ejbTableRel ejb -> table relation

columns Columns to add
returns the modified ejb -> table relation
rules.j2ee.ejb.EjbDescriptorRule
Class EjbDescriptorRule
Structure
Methods Summary
Class EjbDescriptorRule
EjbDescriptorRule - Process EJB ejb-jar.xml descriptors to find EJB beans. The alternative, for EJB3, is to use annotations to describe
EJB elements.
Structure
Methods Summary
public void setPatterns(String patterns)
public void setEjbCallback(rules.j2ee.ejb.Ejb3DependenciesCallback ejbCallback)
EJB3 dependencies callback
rules.j2ee.jdbc
com.optimyth.apm.builder.rules.j2ee.jdbc
com.optimyth.apm.builder.rules.j2ee.jdbc
rules.j2ee.jdbc.BasicJdbcCallback
Class BasicJdbcCallback
Structure
Methods Summary
Class BasicJdbcCallback

implements rules.j2ee.jdbc.JdbcCallback
package rules.j2ee.jdbc
BasicJdbcCallback - Simple callback that will register all referenced tables, with a select/insert/update/delete usage relation.
If the addCodeToRelations property is true, SQL code may be registered at the relation in the property "code" (List of the SQL code
discovered).
<bean id="apm_callback_Jdbc" class=
"com.optimyth.apm.builder.rules.j2ee.jdbc.BasicJdbcCallback">
<property name="dbName" value="myDBInstance"/>
<property name="addCodeToRelations" value="true"/>
</bean>
Where application, dbType and dbName are the application where entities should be added, the type of the
database and the name of its instance, respectively. All three properties are optional, with default values
ModelConstants#DEFAULT_APP, #dbType and #dbName. The property addCodeToRelations decides if extracted
SQL should be added as a relation's property (default is false).
Structure
Methods Summary
Name of container application, to use as fallback (if not provided, defaults to ModelConstants#DEFAULT_APP)
The (default) database name (with schema-oriented db systems) or database type (with database-oriented db systems)
The (default) schema name (with schema-oriented db systems) or database name (with database-oriented db systems)
If true (the default), all database elements will be set to upper-case; if false, no case transformation will be done on element
names
The language for the element that embeds SQL operations (default: java)
If set to true, code for the dependency (property RELATION_CODE with List{String}) is added to the relations (default: false)
rules.j2ee.jdbc.JdbcBytecodeRule
Class JdbcBytecodeRule
Structure
Methods Summary
Class JdbcBytecodeRule
JdbcBytecodeRule - Operates on bytecode to extract dependences with database via JDBC code
Structure
Methods Summary
public void setCallback(rules.j2ee.jdbc.JdbcCallback callback)
JdbcCallback to use for updating model with discovered table usages in embedded SQL
public void setListener(rules.j2ee.jdbc.JdbcSqlListener listener)
ParsingSqlExtractor to use for extracting SQL embedded in Java AST
rules.j2ee.jdbc.JdbcCallback
Interface JdbcCallback
Structure
Field Summary
Methods Summary
Interface JdbcCallback
JdbcCallback - Generic JDBC callback interface.
Structure
Field Summary
public static final JCBC_SQL
public static final JDBC_SQL_TOCHECK
Methods Summary
public onClass(String fqcn, BuilderContext currentContext)
A new class is visited. Return the component modelling the class, or null if the class should be ignored
public onSql(com.optimyth.apm.model.portfolio.Component currentClass, String operation, String

line, String sql, BuilderContext ctx)
An SQL statement is found, creates intermediate sql component and a 'calls' relation between currentClass and sql component
public onSelect(com.optimyth.apm.model.portfolio.Component currentClass, String fqtn, String

sql, String columnsList, BuilderContext currentContext)
A SELECT ... FROM fqtb found. fqtn is the (possibly qualified with schema or database name) table/view name
public onDelete(com.optimyth.apm.model.portfolio.Component currentClass, String fqtn, String

sql, BuilderContext currentContext)
A DELETE FROM fqtb found.
public onInsert(com.optimyth.apm.model.portfolio.Component currentClass, String fqtn, String

sql, BuilderContext currentContext)
An INSERT INTO fqtb found.
public onUpdate(com.optimyth.apm.model.portfolio.Component currentClass, String fqtn, String

sql, String columnsList, BuilderContext currentContext)
An UPDATE fqtn SET found.
public onUsedTable(com.optimyth.apm.model.portfolio.Component currentClass, String fqtn, String

sql, String operation, BuilderContext currentContext)
A generic table/view usage, for extraction techniques that cannot process the full statement
public onSequence(com.optimyth.apm.model.portfolio.Component source, String sequenceName,

BuilderContext ctx)
A sequence usage
public onCall(com.optimyth.apm.model.portfolio.Component source, String procName, boolean

isFunction, BuilderContext ctx)
A call to a stored procedure of user-defined function
rules.j2ee.jdbc.JdbcRule
Class JdbcRule
Goal
Technology
Structure
Field Summary
Methods Summary
Class JdbcRule
JdbcRule -
This rule uses sql extractor / sql listener solution for extracting and parsing embedded SQL code. Obviously only a few SQL statement
can be extracted due to the complexity of the task (SQL code may be constructed programmatically, and the extraction logic is too
complex but for the simplest cases).
Standard APPMAP discovery rule for resolving SQL dependencies (to tables) in SQL embedded in Java source code.
See also
rules.j2ee.jdbc.JdbcCallback
Goal
Standard APPMAP discovery rule for resolving SQL dependencies (to tables) in SQL embedded in Java source code.
Technology
J2EE / JDBC API
<bean id="apm_rule_Jdbc" class="com.optimyth.apm.builder.rules.j2ee.jdbc.JdbcRule">
<property name="filter" ref="apm_filter_javaSource"/>
<property name="callback" ref="apm_callback_Jdbc"/>
<property name="extractor">
<bean class="com.als.sql.extractor.java.JdbcCodeSqlExtractor">
<property name="parser" ref="ls_sql_parser"/>
<property name="listener" ref="apm_listener_Jdbc"/>
</bean>
</property>
</bean>
Where apm_filter_javaSource is a FileFilter matching only java source files, apm_callback_Jdbc is a bean
which class implements JdbcCallback}, is qaKing's SQL parser (typically defined in apm-qaking.xml), and
apm_listener_Jdbc is a bean which class implements SqlExtractListener.
Structure
Field Summary
public static final PROP_CLASS
Methods Summary
public void setCallback(rules.j2ee.jdbc.JdbcCallback callback)
JdbcCallback to use for updating model with discovered table usages in embedded SQL
public void setExtractor(com.als.sql.extractor.ParsingSqlExtractor extractor)
ParsingSqlExtractor to use for extracting SQL embedded in Java AST
rules.j2ee.webapp.jsf
com.optimyth.apm.builder.rules.j2ee.webapp.jsf
com.optimyth.apm.builder.rules.j2ee.webapp.jsf
rules.j2ee.webapp.jsf.BasicFacesConfigCallback

Class BasicFacesConfigCallback
Structure
Class BasicFacesConfigCallback

implements rules.j2ee.webapp.jsf.FacesConfigCallback J2eePropertyDefinitions
package rules.j2ee.webapp.jsf
BasicFacesConfigCallback - Default implementation of rules.j2ee.webapp.jsf.FacesConfigCallback which basically resolves UI

components and managed beans definitions in faces-config descriptors.
<bean id="apm_callback_Faces" class=

"com.optimyth.apm.builder.rules.j2ee.webapp.jsf.BasicFacesConfigCallback"/>
This callback does not need further configuration.
Structure
rules.j2ee.webapp.jsf.FacesConfigCallback
Interface FacesConfigCallback
Structure
Field Summary
Methods Summary
Interface FacesConfigCallback
FacesConfigCallback - Receive events from rules.j2ee.webapp.jsf.FacesConfigRule (currently, only UI components and managed
beans) are supported).
See also
rules.j2ee.webapp.jsf.FacesConfigRule
Structure
Field Summary
Methods Summary
public onFacesConfig(rules.j2ee.webapp.jsf.FacesConfigInfo faces,

com.optimyth.apm.model.portfolio.Software parent, BuilderContext ctx)
public onUIComponent(rules.j2ee.webapp.jsf.FacesConfigInfo.JsfComponent comp,
rules.j2ee.webapp.jsf.FacesConfigInfo facesConfig, com.optimyth.apm.model.portfolio.Software app,
BuilderContext ctx)
A Faces component (UIComponent) declaration found in faces config file
public onManagedBean(rules.j2ee.webapp.jsf.FacesConfigInfo.JsfManagedBean mbean,

rules.j2ee.webapp.jsf.FacesConfigInfo facesConfig, com.optimyth.apm.model.portfolio.Software app,
BuilderContext ctx)
A Faces managed-bean declaration found in faces config file
public void onEnd(java.util.Set allBeans, BuilderContext ctx)
rules.j2ee.webapp.jsf.FacesConfigRule
Class FacesConfigRule
Goal
Technology
Components
Structure
Methods Summary
Class FacesConfigRule
FacesConfigRule -
At rule's initialization, all faces-config files obtained from WebAppRegistry are processed and their JSF components and managed beans
are sent to the callback.
IMPORTANT: This rule should be placed after the rules.j2ee.webapp.webxml.WebXmlRule rule, that is required for discovery of the
web.xml descriptors where the faces descriptors are referenced. If not, the rule simply does nothing.
The rule logic is performed at initialization, where Faces config descriptors discovered by the WebXmlRule are processed.
Parses faces configs based on Faces Config Specification 1.2
Goal
Parses faces configs based on Faces Config Specification 1.2

Technology
J2EE / JSF (Java Server Faces) web application framework
Components
faces descriptor (resource), UI components, managed beans. See rules.j2ee.webapp.jsf.FacesConfigCallback for details.
<bean id="apm_rule_Faces" class=

"com.optimyth.apm.builder.rules.j2ee.webapp.jsf.FacesConfigRule">
<property name="callback" ref="apm_callback_Faces"/>
</bean>
Where apm_callback_Faces is a bean implementing rules.j2ee.webapp.jsf.FacesConfigCallback.
Structure
Methods Summary
public void setCallback(rules.j2ee.webapp.jsf.FacesConfigCallback callback)
rules.j2ee.webapp.jsp
com.optimyth.apm.builder.rules.j2ee.webapp.jsp
com.optimyth.apm.builder.rules.j2ee.webapp.jsp
rules.j2ee.webapp.jsp.BasicJspCallback
Class BasicJspCallback
Structure
Methods Summary
Class BasicJspCallback

implements rules.j2ee.webapp.jsp.JspCallback J2eePropertyDefinitions
package rules.j2ee.webapp.jsp
BasicJspCallback - Default implementation for rules.j2ee.webapp.jsp.JspCallback resolving JSP elements found. All components are
placed in a Software item as resolved by software resolver, or to application named after injected #setWebappName property.
<bean id="apm_callback_Jsp" class=
"com.optimyth.apm.builder.rules.j2ee.webapp.jsp.BasicJspCallback">
<property name="webappName" value="myWebappName"/>
</bean>
Where myWebappName is the application where pages and other elements should be added.
Structure
Methods Summary
The name of the webapp to build if no webapp was provided (default: {@link
com.optimyth.apm.factory.ModelConstants#DEFAULT_APP ModelConstants.DEFAULT_APP)
rules.j2ee.webapp.jsp.JspBuilderRule
Class JspBuilderRule
Goal
Technology
Components
Relations
Structure
Methods Summary
Class JspBuilderRule
JspBuilderRule - Builder rule for JSP pages.
The rule dependes on TagResolver for resolving static HTML dependencies, and JavaResolver for resolving dependencies with Java
classes referenced in the JSP page.
Discovers JSP pages and their common dependencies (HTML "static", tags, taglibs referenced, Java classes)
See also
rules.j2ee.webapp.jsp.JspCallback
JavaResolver
TagResolver
Goal
Discovers JSP pages and their common dependencies (HTML "static", tags, taglibs referenced, Java classes)
Technology
J2EE
Components
JSP pages
Relations
This rule extracts dependencies in JSP pages:
Referenced taglibs
Included JSPs (via <%@ include %>)
JSPs included / forwarded (when the URL resolves to a JSP in the codebase)
Tags (e.g. JSF UIComponents) in the given set of taglibs (infrastructure libraries are should be ignored)
Static HTML dependencies (references to CSS, IMG, JavaScript, and links to resolvable app resources)
See rules.j2ee.webapp.jsp.JspCallback for details
<bean id="apm_rule_Jsp" class=

"com.optimyth.apm.builder.rules.j2ee.webapp.jsp.JspBuilderRule">
<property name="filter" ref="apm_filter_jsp"/>
<property name="callback" ref="apm_callback_Jsp"/>
<property name="webContents" ref="PATH/TO/WEBAPP"/>
<property name="taglibsToParse">
<list>
<value>/WEB-INF/tld/myTaglib1.tld</value>
<value>/WEB-INF/tld/myTaglib2.tld</value>
...
<value>/WEB-INF/tld/myTaglibN.tld</value>
</list>
</property>
</bean>
Where apm_filter_jsp is a FileFilter matching only JSP pages, apm_callback_Jsp is a bean which class
implements rules.j2ee.webapp.jsp.JspCallback and taglibsToParse is a list with paths to libraries which tags
should be parsed.
Structure
Methods Summary
public void setCallback(rules.j2ee.webapp.jsp.JspCallback callback)

The (fallback) directory where web content can be found (for resolving relative URLs to code resources).
Matching WebApp bean
(detected by rules.j2ee.webapp.webxml.WebXmlRule)
will be tried. If no WebApp is matched, this webContents is used as fallback base dir for JSP resources.
This permits the rule to operate without a WebXmlRule resolving web applications explicitely.
public void setTaglibsToParse(java.util.List taglibsToParse)
List of taglibs to consider when parsing JSP/JSP elements (e.g. custom UIComponents)
taglibsToParse List(String). Each element is an URI of taglibs to parse.
public void setJspResolver(com.als.jsp.JspResolver jspResolver)
Sets JSP resolver to use for resolving JSP includes/forwards (static and dynamic)
public void setTagResolver(rules.j2ee.webapp.jsp.TagResolver tagResolver)
public void setJavaResolver(rules.j2ee.webapp.jsp.JavaResolver javaResolver)
The helper to use when resolving JSP -> Java dependencies
public void setResolveUnparsedJsp(boolean resolveUnparsedJsp)
If true (the default), create component for any JSP, including unparseable pages; if false ignore JSP files that were not parsed
rules.j2ee.webapp.jsp.JspCallback
Interface JspCallback
Structure
Field Summary
Methods Summary
Interface JspCallback
JspCallback - Generic callback for JSP elements. Provide callback methods for discovered JSP pages (#onJsp), JSP-specific
dependencies (#onIncludedJsp, #onInvokedJsp, #onTaglibReferenced and #onTag), HTML "static" dependencies (#onCss, #onScript,
#onLink, #onImage, #onForm).
This callback does not process JSP - Java relations, which are processed by JavaResolver.
Structure
Field Summary
public static final JSP_LANG
Methods Summary
public onJsp(java.io.File jspFile, java.io.File webroot, rules.j2ee.webapp.webxml.WebApp

webapp, BuilderContext ctx)
public com.optimyth.apm.builder.rules.html.TagResource resolveUrl(String url, String tagType,

java.io.File webContentsDir, boolean acceptUnresolvedResources, BuilderContext ctx)
Resolves a given web resource URL for the given tagType as a TagResource
public onIncludedJsp(com.optimyth.apm.model.portfolio.Component jspPage, java.io.File

includedJsp, java.io.File webroot, rules.j2ee.webapp.webxml.WebApp webapp, BuilderContext ctx)
public onInvokedJsp(com.optimyth.apm.model.portfolio.Component jspPage, java.io.File

invokedJsp, boolean include, java.io.File webroot, rules.j2ee.webapp.webxml.WebApp webapp,
BuilderContext ctx)
public onTaglibReferenced(com.optimyth.apm.model.portfolio.Component jspPage, String uri,

rules.j2ee.webapp.webxml.WebApp webapp, BuilderContext ctx)
public onTag(com.optimyth.apm.model.portfolio.Component jspPage, String taglibUri, String name,
com.als.core.ast.BaseNode tag, rules.j2ee.webapp.webxml.WebApp webapp, BuilderContext ctx)
public onCss(rules.html.TagResource resource, com.optimyth.apm.model.portfolio.Component page)
public onScript(rules.html.TagResource resource, String lang,

com.optimyth.apm.model.portfolio.Component page)
public onLink(rules.html.TagResource resource, com.optimyth.apm.model.portfolio.Component page)
public onImage(rules.html.TagResource resource, com.optimyth.apm.model.portfolio.Component

page)
public onForm(rules.html.TagResource resource, String id, String method,

com.als.jsp.utils.JspElement t, com.optimyth.apm.model.portfolio.Component page)
rules.j2ee.webapp.servlet
com.optimyth.apm.builder.rules.j2ee.webapp.servlet
com.optimyth.apm.builder.rules.j2ee.webapp.servlet
rules.j2ee.webapp.servlet.BasicServletCallback
Class BasicServletCallback
Structure
Methods Summary
Class BasicServletCallback

implements rules.j2ee.webapp.servlet.ServletCallback
package rules.j2ee.webapp.servlet
BasicServletCallback - Basic implementation for rules.j2ee.webapp.servlet.ServletCallback.
<bean id="apm_callback_Servlet" class=
"com.optimyth.apm.builder.rules.j2ee.webapp.servlet.BasicServletCallback">
<property name="webappName" value="myWebappName"/>
</bean>
Where myWebappName is the application where servlets belong to.
Structure
Methods Summary
The name of the webapp to build if no webapp was provided (default: "common")
rules.j2ee.webapp.servlet.ServletBuilderRule
Class ServletBuilderRule
Technology
Structure
Methods Summary
Class ServletBuilderRule
extends from JavaClassMethodBytecodeRule
ServletBuilderRule - Builds servlet and filter dependencies, from compiled bytecode (.class). This rule finds servlet and filter
implementation classes, links to their definition in web.xml (if any, previously parsed by the WebXmlRule), and passes to the
rules.j2ee.webapp.servlet.ServletCallback callback.
See also
rules.j2ee.webapp.servlet.ServletCallback
Technology
J2EE
<bean id="apm_rule_Servlet" class=
"com.optimyth.apm.builder.rules.j2ee.webapp.servlet.ServletBuilderRule">
<property name="filter" ref="apm_filter_servlets"/>
<property name="servletCallback" ref="apm_callback_Servlet"/>
<property name="baseServlets">
<set>
<value>my/base/servlet/NumberOne</value>
<value>my/base/servlet/NumberTwo</value>
...
<value>my/base/servlet/NumberN</value>
</set>
</property>
<property name="baseFilters">
<set>
<value>my/base/filter/NumberOne</value>
<value>my/base/filter/NumberTwo</value>
...
<value>my/base/filter/NumberN</value>
</set>
</property>
</bean>
Where apm_filter_servlets is a FileFilter matching only servlet files, apm_callback_Servlet is a bean which
class implements rules.j2ee.webapp.servlet.ServletCallback, and baseServlets/baseFilters are sets defining
custom base servlets/filters, respectively, both of them optional.
Structure
Methods Summary
public void setBaseServlets(java.util.Set baseServlets)
Set of fully-qualified classnames with custom base servlet classes used by

this application, like com.mypkg.MyBaseServlet
public void setBaseFilters(java.util.Set baseFilters)
Set of fully-qualified classnames with custom base filter classes used by

this application, like com.mypkg.MyBaseFilter
public void setCallback(rules.j2ee.webapp.servlet.ServletCallback callback)

Please, use servletCallback property
rules.j2ee.webapp.servlet.ServletCallback
Interface ServletCallback
Structure
Field Summary
Methods Summary
Interface ServletCallback
ServletCallback - Callback for servlet API entities (servlets, filters). Extends ClassCallback (which process Java language dependencies,
like inheritance, method calls, field usage) with servletAPI-specific callbacks.
See also
rules.j2ee.webapp.servlet.BasicServletCallback
Structure
Field Summary
Methods Summary
public onServlet(String fqcn, rules.j2ee.webapp.webxml.ServletInfo servletInfo,

public onFilter(String fqcn, rules.j2ee.webapp.webxml.FilterInfo filterInfo,

public onUrlRedirect(com.optimyth.apm.model.portfolio.Component servlet,

org.objectweb.asm.tree.MethodNode method, String url)
rules.j2ee.webapp.webxml
com.optimyth.apm.builder.rules.j2ee.webapp.webxml
com.optimyth.apm.builder.rules.j2ee.webapp.webxml
rules.j2ee.webapp.webxml.BasicWebappCallback
Structure
Methods Summary

implements rules.j2ee.webapp.webxml.WebappCallback J2eePropertyDefinitions
package rules.j2ee.webapp.webxml
BaseWebappCallback - Basic implementation for rules.j2ee.webapp.webxml.WebappCallback resolving elements found in web.xml

descriptors. The logic for resolving webapp name is the following: - First, use the webappResolver, if defined. -
Second, use the webappName, if defined. - Third, use the name defined in web.xml <display-name> tag
<bean id="apm_callback_Webapp" class=

"com.optimyth.apm.builder.rules.j2ee.webapp.webxml.BasicWebappCallback">
<property name="webappResolver" ref="MyWebappResolver"/> 
or
<property name="webappName" value="AppName"/> 
</bean>
Structure
Methods Summary
(Optional) If set, use this for the application name. If not set, take appname from web.xml descriptor
public void setWebappResolver(rules.j2ee.webapp.webxml.WebappResolver webappResolver)
(Optional) Alternative to webappName: put here your logic to solve customer-specific webApp resolution
protected void setEjbProperties(com.optimyth.apm.model.portfolio.Component ejb,

rules.j2ee.webapp.webxml.EjbInfo ejbInfo)
rules.j2ee.webapp.webxml.WebappCallback
Structure
Field Summary
Methods Summary
WebappCallback - Callback for updating model with all the elements found in a web.xml descriptor, of interest for "web application
discovery". Relevant presentation-layer J2EE elements are considered: servlets, filters, resources, ejb references, context listeners, tag
libraries, and JSF (faces) descriptors.
Structure
Field Summary
Methods Summary
public onWebApplication(rules.j2ee.webapp.webxml.WebApp webapp, BuilderContext ctx)
public onServlet(rules.j2ee.webapp.webxml.ServletInfo servlet,

com.optimyth.apm.model.portfolio.Software webapp)
public onFilter(rules.j2ee.webapp.webxml.FilterInfo servlet,

public onResource(rules.j2ee.webapp.webxml.ResourceInfo resource,

public onListener(rules.j2ee.webapp.webxml.ListenerInfo listener,

public onEjbReference(rules.j2ee.webapp.webxml.EjbInfo resource,

com.optimyth.apm.model.portfolio.Software webapp, BuilderContext ctx)
public onTaglib(rules.j2ee.webapp.webxml.TaglibInfo taglib,
public onFacesConfig(java.io.File facesConfigFile, com.optimyth.apm.model.portfolio.Software

webapp)
rules.j2ee.webapp.webxml.WebXmlRule
Class WebXmlRule
Goal
Technology
Structure
Methods Summary
Class WebXmlRule
WebXmlRule -
NOTE: Typically there should be a single instance of this rule in a configuration, with the webxmlPatterns property set, and with a
WebappCallback configured to resolve the application where the descriptor lives, based e.g. on the descriptor path.
As other rules may need access to the descriptors processed by this rule, the rule logic is performed in the initialize() method (so
no filter is needed). Some rules that use the webapps discovered by this rule are: rules.j2ee.webapp.jsp.JspBuilderRule,
rules.j2ee.webapp.jsf.FacesConfigRule, rules.j2ee.webapp.servlet.ServletBuilderRule, rules.spring.webflow.SpringWebflowRule.
If the rule successfully processes each web.xml descriptor found, the WebApp bean representing configuration is stored in a map (keyed
by the Software corresponding to the application resolved by the callback) under the WEB.XML.CONTENTS key, so other J2EE rules may
use that information (for example, taglibs found in JSP files, etc.)
Rule that parses web.xml descriptor file for any J2EE "web applications", emitting events to the
rules.j2ee.webapp.webxml.WebappCallback that will update the model with descriptor-discovered information.
See also
rules.j2ee.webapp.webxml.WebappCallback
Goal
Rule that parses web.xml descriptor file for any J2EE "web applications", emitting events to the
rules.j2ee.webapp.webxml.WebappCallback that will update the model with descriptor-discovered information.
Technology
J2EE
<bean id="apm_rule_WebXml" class=
"com.optimyth.apm.builder.rules.j2ee.webapp.webxml.WebXmlRule">
<property name="callback" ref="apm_callback_Webapp"/>
<property name="webxmlPatterns" value="myWebxmlPattern"/>
</bean>
Where apm_callback_Webapp is a bean which class implements rules.j2ee.webapp.webxml.WebappCallback and

myWebxmlPattern is a comma-separated list of ANT patterns for matching web.xml descriptors under basedirs (**
/WEB-INF/web.xml is default value).
Structure
Methods Summary
public void setCallback(rules.j2ee.webapp.webxml.WebappCallback callback)
The WebappCallback to use for updating the model
public void setWebxmlPatterns(String webxmlPatterns)
(Optional) Comma-separated list of ANT patterns for matching web.xml descriptors under basedirs
If not provided, ** /WEB-INF/web.xml will be used.
public void setWebxmlPaths(java.util.Set webxmlPaths)
(Optional) Set of (relative) paths for matching web.xml descriptors under basedirs
public void setApplicationsMap(java.util.Map appsMap)
(Optional) a map with the maps that will convert application names found in display-name elements of web.xml descriptor
into the logical webapp name mapped to.
appsMap
rules.j2ee.weblogic
com.optimyth.apm.builder.rules.j2ee.weblogic
com.optimyth.apm.builder.rules.j2ee.weblogic
rules.j2ee.weblogic.JavaControlsRule
Class JavaControlsRule
Structure
Methods Summary
Class JavaControlsRule
extends from JavaClassMethodRule
package rules.j2ee.weblogic
JavaControlsRule - Process Java Control source code (.jcx files), looking at dependencies with J2EE resources encoded in Javadoc
comments (attributes prefixed with @prefix:suffix).
Structure
Methods Summary
public void setProcessors(java.util.List processors)
The processors that will derive model entities and dependencies from JavaControl tags
rules.j2ee.webservice
com.optimyth.apm.builder.rules.j2ee.webservice
com.optimyth.apm.builder.rules.j2ee.webservice
rules.j2ee.webservice.AxisWsddRule
Class AxisWsddRule
Components
Relations
Structure
Methods Summary
Class AxisWsddRule

package rules.j2ee.webservice
AxisWsddRule - Process WSDD (Axis Web Service Deployment Descriptor). <pre> <service name="Pago" provider="java:RPC">
<namespace>http://faults.samples</namespace> <parameter name="className"
value="com.pelayo.diversos.pago.service.PagoServiceImpl" /> <parameter name="allowedMethods" value="capturarPago"/>
<parameter name="scope" value="Session" /> <wsdlFile>../colab-ws.wsdl</wsdlFile> </service> </pre>
{technology}j2ee/webservice{technology}
Components
webservice, configuration, class, operation
Relations
Configuration component for WSDD file, that configures each webService WS. Component for implementation class C
is created, with WS - implementedBy -> C relation. If wsdlFile is provided and exists as physical file,
a configuration component for the WSDL file is created, with WSDL - configures -> WS relation.
If createWebServiceMethods is true, operation component is created for each operation O in WS, with
WS - contains -> O.
Structure
Methods Summary
public void setCreateWebServiceMethods(boolean createWebServiceMethods)
If set to true, webservice methods (annotated with @WebMethod) will be created
rules.j2ee.webservice.JaxwsRule
Class JaxwsRule
Structure
Methods Summary
Class JaxwsRule
JaxwsRule - Creates web services and web service proxies based on JAX-WS annotations in Java classes (JSR-181).
Structure
Methods Summary
public void setProcessWebServiceClient(boolean processWebServiceClient)
If true (default), @WebServiceClient annotations will be processed (JAX-WS client proxies)
public void setProcessWebServiceServer(boolean processWebServiceServer)
If true (default), @WebService annotations will be processed (JAX-WS service implementations)
public void setCreateUnresolvedWebServices(boolean createUnresolvedWebServices)
If set to true, webservices used in proxies that cannot be resolved are created in the same proxy software.
If set to true, webservice methods (annotated with @WebMethod) will be created
rules.j2ee.webservice.JBuilderWebServiceRule
Class JBuilderWebServiceRule
Structure
Methods Summary
Class JBuilderWebServiceRule

JBuilderWebServiceRule - Process <wsdl2java> elements in Borland's WebServicesDesigner WSDU file.

See Axis wsdl2java Ant task for description of the <wsdl2java> element.
Example: <pre> <wsdl2java autoValidateOnBuild="true" enabled="true" displayName="MyService" internalId="1331132415573"
isLiveSyncImportEnabled="false" all="false" debug="false" deployscope="Request" helpergen="false" noimports="false" output="src"
serverside="false" skeletondeploy="false" testcase="true" testcaseoverwrite="false" timeout="0" typemappingversion="1.2"
url="doc/FacturacionService3.wsdl" verbose="false" wrapped="true" packageforall="false" overWriteTypes="true"> <mapping
namespace="http://common.ws.myorg.com/" packagename="com.myorg.ws.common"/> <mapping
namespace="http://myservice.ws.myorg.com/" packagename="com.myorg.ws.myservice"/> <generatedFile
file="../src/com/myorg/ws/common/WSException.java"/> <generatedFile file="../src/com/myorg/ws/common/CommonDTO.java"/>
<generatedFile file="../src/com/myorg/ws/myservice/MyService.java"/> <generatedFile
file="../src/com/myorg/ws/myservice/MyServicePortBindingStub.java"/> <generatedFile
file="../src/com/myorg/ws/myservice/MyServiceService.java"/> <generatedFile
file="../src/com/myorg/ws/myservice/MyServiceServiceLocator.java"/> <generatedFile
file="../src/com/myorg/ws/myservice/MyServiceDTO.java"/> <generatedFile
file="../test/com/myorg/ws/myservice/MyServiceTestCase.java"/> </wsdl2java> </pre>
Structure
Methods Summary
The callback to use when generating class components. Default: ClassCallback.NULL
public void setCreateUnresolvedWebServices(boolean createUnresolvedWebServices)
If set to true, webservices referenced in .wsdu that cannot be resolved are created in the same software that contains the
descriptor
rules.java
com.optimyth.apm.builder.rules.java
com.optimyth.apm.builder.rules.java
rules.java.JavaClassBytecodeRule
Class JavaClassBytecodeRule
Technology
Components
Structure
Class JavaClassBytecodeRule
package rules.java
JavaClassBytecodeRule - Rule that builds Java classes as components, resolving Java-type dependencies (method calls, object
instantiations, inheritance and variable references) by analyzing bytecode (compiled .class files).
This rule DOES NOT resolve any Java API dependency, or dependencies that cannot be resolved to other classes in the same model
("inter-model deps"). This is done purposely, to limit model growth.
Implementation note: This rule uses bytecode.
TODO complete with varReferences
Technology
Java
Components
Classes
<bean id="apm_rule_JavaClassBytecode" class=

"com.optimyth.apm.builder.rules.java.JavaClassBytecodeRule">

<property name="resolveCallingMethods" value="true"/> 
<property name="resolveCalledMethods" value="true"/> 
</bean>
Structure
rules.java.JavaClassMethodBytecodeRule
Class JavaClassMethodBytecodeRule
Structure
Methods Summary
Class JavaClassMethodBytecodeRule
extends from rules.java.JavaClassBytecodeRule
package rules.java
JavaClassMethodBytecodeRule - Extension to the base rules.java.JavaClassBytecodeRule, that registers dependencies with

method-level granularity. Method is registered for any source or target class matching the registered predicate (the predicate operates
on fully qualified class name string). By default this predicate matches nothing, so this rule behaves exactly like
rules.java.JavaClassBytecodeRule. When a specific predicate is injected, methods in matched types will be registered as components.
See also
rules.java.JavaClassMethodRule
Structure
Methods Summary
public void setResolveMethodsFilter(rules.common.Predicate classnameFilter)
The filter for the classnames where the source/target method will be resolved as components. Defaults to none (do not register
methods in model).
public void setMethodPredicate(rules.common.Predicate methodPredicate)
Predicate that, when matches a candidate ASM MethodNode, the rule will register the method as component of the enclosing
class.
Class JavaClassMethodRule
Technology
Components
Relations
Structure
Methods Summary
Class JavaClassMethodRule
extends from rules.java.JavaClassRule
package rules.java
JavaClassMethodRule - Rule that builds Java classes and methods as components, resolving Java-type dependencies (method calls,
object instantiations, inheritance, variable and type references)
IMPORTANT NOTE: The method component in model does not use the full method signature. This is done purposely, to reduce the size
of the method key. That means that all overloaded methods collapse to a single method. This is OK for most of the purposes, but
obviously is not accurate 100% due to method overloading.
Implementation note: This rule uses source-based AST.
See also
rules.java.JavaClassRule
Technology
Java
Components
Java methods and their enclosing classes
Relations
Dependencies resolved are: inheritance, call, var usage, type reference. Methods are resolved
if the enclosing class matches the resolveMethodsFilter predicate.
If a NodePredicate is registered in #setMethodPredicate, method declarations matching it
and in classes whose name was matched by #setResolveMethodsFilter are registered as components.
If you want to represent dependencies without method-level granularity, use
rules.java.JavaClassRule instead.
<bean id="apm_rule_JavaClass" class=

"com.optimyth.apm.builder.rules.java.JavaClassMethodRule">
-->
</bean>
Structure
Methods Summary
public void setResolveMethodsFilter(rules.common.Predicate classnameFilter)
The filter for the classnames where the source/target method will be resolved as components. Defaults to none (do not register
methods in model).
public void setMethodPredicate(com.als.core.ast.NodePredicate methodPredicate)
NodePredicate that, when matches a candidate MethodDeclaration, the rule will register the method as component of the
enclosing class.
Class JavaClassRule
Goal
Technology
Components
Relations
Structure
Field Summary
Class JavaClassRule
package rules.java
JavaClassRule -
Implementation note: This rule uses source-based AST.
Rule that builds Java classes as components, resolving Java-type dependencies (method calls, object instantiations, inheritance,
variable and type references)
See also
Goal
Rule that builds Java classes as components, resolving Java-type dependencies (method calls, object instantiations, inheritance,
variable and type references)
Technology
Java
Components
Classes
Relations
Dependencies resolved are: inheritance, call, var usage, type reference. Methods are NOT resolved. If you
want to represent dependencies with method-level granularity, use rules.java.JavaClassMethodRule
instead.
<bean id="apm_rule_JavaClass" class="com.optimyth.apm.builder.rules.java.JavaClassRule">

-->
</bean>
Structure
Field Summary
protected null qe
protected null CALL_PRED
protected null VARREF_PRED
protected static final CLASS_INTERFACE_ENUM
rules.java.jar
com.optimyth.apm.builder.rules.java.jar
com.optimyth.apm.builder.rules.java.jar
rules.java.jar.BasicJarCallback
Class BasicJarCallback
Structure
Class BasicJarCallback

implements rules.java.jar.JarCallback
package rules.java.jar
Resolves JAR files as libraries (Software), with contained classes or resources inside. TODO currently unused. Create rule for
processing packed files (JARs, WARs, EARs...)
Structure
rules.java.jar.JarCallback
Interface JarCallback
Structure
Field Summary
Methods Summary
Interface JarCallback
JarCallback - this callback define the events for updating model for every jar found in the java application.
Structure
Field Summary
Methods Summary
public onJar(java.io.File jarFile, BuilderContext ctx)
Callback invoked when a jar is found in a java application
public onClass(com.optimyth.apm.model.portfolio.Software jar, String className, BuilderContext

ctx)
Creates classes found in a jar
public onResource(com.optimyth.apm.model.portfolio.Software jar, String resourceName,

BuilderContext ctx)
Creates resources found in a jar
rules.java.jar.JarRule
Class JarRule
Goal
Technology
Components
Structure
Methods Summary
Class JarRule
JarRule -
Rule that extracts a list of jars and its contents from a java application, creating containing relations between a jar and its classes.
Goal
Rule that extracts a list of jars and its contents from a java application, creating containing relations between a jar and its classes.
Technology
Java
Components
Jars and Classes
<bean id="apm_rule_jar" class="com.optimyth.apm.builder.rules.java.JarRule">
<property name="xxxx" ref="apm_callback_jar"/>
</bean>
Where apm_callback_Webapp is a bean which class .....
Structure
Methods Summary
public void setCallback(rules.java.jar.JarCallback callback)
callback for updating the model
public void setJarPatterns(String patterns)
comma separated jar ant patterns to use for updating the model
public void setClassFilters(String patterns)
comma separated jar ant patterns to use on class names: only jars containing filtered classes will be added to the model
rules.jcl
com.optimyth.apm.builder.rules.jcl
com.optimyth.apm.builder.rules.jcl
rules.jcl.DefaultJclJobCallback
Class DefaultJclJobCallback
Components
Relations
Structure
Methods Summary
Class DefaultJclJobCallback

implements rules.jcl.JclJobCallback
package rules.jcl
DefaultJclJobCallback - Default implementation for rules.jcl.JclJobCallback resolving procedures, jobs and calls found in JCL scripts.
Components
JCL programs (scripts with language=jcl) and called programs
Relations
calls between the JCL and the called program (which could be another JCL, or an external program)
<bean id="apm_callback_JclJob" class=

"com.optimyth.apm.builder.rules.jcl.DefaultJclJobCallback">
</bean>
Where myScriptApplication and myBackendApplication are the names of the applications where scripts and
programs should be added, respectively. Both of them are optional, with default value
ModelConstants#DEFAULT_APP.
Structure
Methods Summary
public void setScriptApplication(String scriptApplication)
Name for the Software container that will hold batch scripts
public void setScriptContainerType(String scriptContainerType)
Type of the Software container for holding batch scripts

public void setBackendApplication(String backendApplication)
Name for the Software container that will hold called programs (not batch scripts)
public void setBackendContainerType(String backendContainerType)
Type of the Software container for holding backend (non batch script) to reference
public void setAcceptUnresolved(boolean acceptUnresolved)
If true, target called programs not found in model are created (in batch application).
If false, those calls are ignored.
public void setSaveStepInformation(boolean saveStepInformation)
If true, be mapped so many relationships between the JCL and the element as are referred to in various steps.
If false, be mapped a single relationship between JCL and the element although references the element more than once inside.
public void setInstreamProcedures(boolean instreamProcedures)
If true, internal procedures are modeled

Set resolver for components participating in call relations
public void setInlineProcedureResolver(rules.jcl.InlineProcedureResolver

inlineProcedureResolver)
Set inline procedure resolver
public void setRegisterUtilities(boolean registerUtilities)
If true, register utilities as model components; if false, utilities are not registered as model components. Default: true
rules.jcl.JclJobCallback
Interface JclJobCallback
Structure
Field Summary
Methods Summary
Interface JclJobCallback
package rules.jcl
JclJobCallback - Generic callback for JCL jobs found.
Structure
Field Summary
Methods Summary
public onJob(String jobName, BuilderContext ctx, com.als.core.ast.TreeNode job)

Callback invoked when a job is found in a JCL
jobName Name of the job

ctx BuilderContext
job BaseNode for the job AST subtree.
returns Component (or null if should be skipped)
public onProcedure(com.optimyth.apm.model.portfolio.Component job, String procedureName,

com.als.core.ast.TreeNode procedure, BuilderContext ctx)
Callback invoked when an job-embedded procedure or catproc is found
job The job containing the procedure definition (null for catprocs)
procedureName Procedure name
procedure TreeNode with the proc AST node for the procedure.
ctx Buildercontext
returns Component for the procedure (or null if it should be skipped)
public onProgramCall(com.optimyth.apm.model.portfolio.Component caller, String stepname, int

stepline, String callingProcedure, String calledProgram, com.als.core.ast.TreeNode step,
BuilderContext ctx)
Callback invoked when a step in job calls external program
caller Caller (Component matching job or catproc)

stepname Caller step (name assigned in the EXEC statement)
stepline Number of line where is the step
callingProcedure Procedure where the EXEC statement was found (could be null if not inside a PROC)
calledProgram Called program
step TreeNode (of type exec_statement) for EXEC statement
ctx BuilderContext
returns ApmRelation, or null if the relation should be discarded.
public onProcedureCall(com.optimyth.apm.model.portfolio.Component caller, String stepname, int

stepline, String callingProcedure, String calledProcedure, com.als.core.ast.TreeNode step,
BuilderContext ctx)
Callback invoked when a step in job calls a procedure (in-flow proc or catproc)
caller Caller (Component matching job or catproc)

callingProcedure Procedure where the EXEC statement was found (could be null if not inside a PROC)
calledProcedure Called procedure
step TreeNode (of type exec_statement) for EXEC statement
ctx BuilderContext
returns ApmRelation, or null if the relation should be discarded.
public addFile(String fileName, String disp, String dcb, String unit,

com.optimyth.apm.model.portfolio.Component caller, String stepname, int stepline,
com.als.core.ast.TreeNode step, BuilderContext ctx)
Callback invoked when a step uses a file
fileName DSN or DSNAME statement value

disp DISP parameter value
dcb DCB parameter value
unit UNIT parameter value
caller Caller
step TreeNode of type dd_statement
ctx BuilderContext
returns Component
public onInlineProcedure(com.optimyth.apm.model.portfolio.Component job, String procedureName,

com.als.core.ast.TreeNode procedure, BuilderContext ctx)
Callback invoked when an inline procedure is found
job The job containing the procedure definition

procedureName Procedure name
procedure TreeNode with the inline_proc AST node for the procedure.
ctx Buildercontext
returns Component for the procedure
public addUtility(String utilityName, String calledProgram,

com.optimyth.apm.model.portfolio.Component caller, String stepname, int stepline,
com.als.core.ast.TreeNode step, BuilderContext ctx)
Add an utility to execute DB2 programs to the model.
utilityName Name of the utility

calledProgram Program called inside the utility (could be null: the relation returned will be caller calls> utiltyName)
caller Caller
stepname Caller step
step TreeNode
ctx BuilderContext
returns ApmRelation caller calls> calledProgram (if calledProgram is resolved), or caller-calls-> utilityName
public void addVariable(com.als.core.ast.TreeNode variable, BuilderContext ctx)
Add variable declarations to a component
variable Node with variable declarations

ctx BuilderContext
public java.lang.String getVariableValue(String variable)
Return variable value
variable Variable name

returns null when no exists
public void clearVariables()
Clear all defined variables in a component
rules.jcl.JclRule
Class JclRule
Goal
Technology
Structure
Methods Summary
Class JclRule
package rules.jcl
JclRule -
The rules.jcl.JclJobCallback may be used to construct the job/step structure in batch JCL scripts, and resolve calls to programs and
procedures.
Extracts dependencies from JCL to called external programs.
See also
rules.jcl.JclJobCallback
Goal
Extracts dependencies from JCL to called external programs.
Technology
JCL (IBM's Job Control Language)
<bean id="apm_rule_Jcl" class="com.optimyth.apm.builder.rules.jcl.JclRule">

<property name="filter" ref="apm_filter_jcl"/>
<property name="callback" ref="apm_callback_JclJob"/>
</bean>
Where apm_filter_jcl is a FileFilter matching only JCL scripts, and apm_callback_JclJob is a bean which
class implements rules.jcl.JclJobCallback.
Structure
Methods Summary
public void setVisitorType(String visitorType)
Extended visitor (E) or Default visitor (D)
public void setCallback(rules.jcl.JclJobCallback callback)
The callback to use for processing discovered dependencies
public void setUtilityResolver(rules.jcl.UtilityResolver utilityResolver)

The UtilityResolver bean to use for matching utility calls (host, DB2, Control-M...)
public void setDb2Resolver(rules.jcl.Db2Resolver db2Resolver)
The Db2Resolver bean to use for resolving SQL operations
public void setResolveSqlStatements(boolean resolveSqlStatements)
If true (the default), sql statements launched by DB2 utilities executed in JCL will be processed.
If false, SQL is not processed by the rule.
rules.metrics
com.optimyth.apm.builder.rules.metrics
com.optimyth.apm.builder.rules.metrics
rules.metrics.MetricsRule
Class MetricsRule
Structure
Methods Summary
Class MetricsRule
package rules.metrics
MetricsRule - Rule for add metrics of other plugin to the model
Structure
Methods Summary
public void setDirectoriesMetrics(String directoriesMetrics)

public void setMetrics(String metrics)
rules.natural
com.optimyth.apm.builder.rules.natural
com.optimyth.apm.builder.rules.natural
rules.natural.BasicNaturalDependenciesCallback
Class BasicNaturalDependenciesCallback
Goal
Structure
Methods Summary
Class BasicNaturalDependenciesCallback

implements rules.natural.NaturalDependenciesCallback
package rules.natural
BasicNaturalDependenciesCallback -
Callback for converting rule events to model entities for Natural programs.
See also
ByExtensionMapper
CalledProgramResolver
Goal
Callback for converting rule events to model entities for Natural programs.
<bean id="apm_rule_natural_callback" class=
"com.optimyth.apm.builder.rules.natural.BasicNaturalDependenciesCallback">
<property name="application" value="${model.name}"/>
<property name="resolver" ref="apm_rule_natural_resolver"/>
<property name="mapper" ref="apm_rule_natural_mapper"/>
<property name="databaseType" ref="${database.type}"/>
<property name="databaseName" ref="${database.name}"/>
</bean>
<bean id="apm_rule_natural_resolver" class=

"com.optimyth.apm.builder.rules.natural.CalledProgramResolver">
<property name="fileResolver" ref="apm_rule_natural_resolver_file"/>
<property name="mapper" ref="apm_rule_natural_mapper"/>
<property name="acceptUnresolvedArtifacts" value="false"/>
<property name="application" value="${model.name}"/>
</bean>
<bean id="apm_rule_natural_resolver_file" class=

"com.optimyth.apm.builder.rules.common.fileresolution.SingleDirFileResolver">
<property name="basedir" value="${basedir}"/>
<property name="recurseDirs" value="false"/>
</bean>
<bean id="apm_rule_natural_mapper" class=

"com.optimyth.apm.builder.rules.natural.ByExtensionMapper">
<property name="typesMap"><map>
<entry key="NLP" value="PROGRAM"/><entry key="NSP" value="PROGRAM"/>
<entry key="NLS" value="SUBROUTINE"/><entry key="NSS" value="SUBROUTINE"/>
<entry key="NLH" value="HELPROUTINE"/><entry key="NSH" value="HELPROUTINE"/>
<entry key="NLM" value="MAP"/><entry key="NSM" value="MAP"/>
</map></property>
</bean>
Where calledResolver is the CalledResolver to use (see CalledProgramResolver for a typical implementation for
Natural systems), and mapper is the Mapper that will classify each file in Natural system to the proper entity type (see
ByExtensionMapper for a typical implementation). \\\{{application}}, databaseType and databaseName are the
application where entities should be added, the type of the database and the name of its instance, respectively. All
three properties are optional.
Structure
Methods Summary
Name of container application (if not provided, defaults to ModelConstants#DEFAULT_APP)

Type of the container (default: application)
public void setMapper(rules.natural.Mapper mapper)
public void setDatabaseType(String dbType)
The database type (default: Adabas)
public void setDatabaseName(String dbName)
The database name (default: ADABAS)
rules.natural.NaturalBuilderRule
Class NaturalBuilderRule
Goal
Structure
Methods Summary
Class NaturalBuilderRule
NaturalBuilderRule -
Extraction rule for Software AG's Natural system
See also
Goal
Extraction rule for Software AG's Natural system
<bean id="apm_rule_natural" class=

"com.optimyth.apm.builder.rules.natural.NaturalBuilderRule">
<description>Extraction rule for Natural</description>
<property name="callback" ref="apm_rule_natural_callback"/>
<property name="active" value="true"/>
<property name="filter" ref="apm_filter_natural"/>
<property name="processDatabaseOperations" value="true"/>
</bean>
Structure
Methods Summary
public void setCallback(rules.natural.NaturalDependenciesCallback callback)
The rules.natural.NaturalDependenciesCallback to use for updating dependencies model
public void setProcessDatabaseOperations(boolean processDatabaseOperations)

If true (the default), process database operations
rules.natural.NaturalDependenciesCallback
Interface NaturalDependenciesCallback
Structure
Field Summary
Methods Summary
Interface NaturalDependenciesCallback
NaturalDependenciesCallback - Callback interface for Natural extraction rules.
See also
Structure
Field Summary
Methods Summary
public getHelper()
public void start(BuilderContext ctx)
Initializes the callback
public onApplication(java.io.File codeFile, BuilderContext ctx)
Get the Software container for the code file
public onProgram(String progName, BuilderContext ctx)

A new Natural program found
public onSubroutine(String progName, BuilderContext ctx)
A new Natural Subroutine found
public onDataArea(String dataAreaName, String dataAreaType,

com.optimyth.apm.model.portfolio.Component item, BuilderContext ctx)
Invoked for a GLOBAL/LOCAL/PARAMETER USING name
public onDataView(String viewName, String aliasName, com.optimyth.apm.model.portfolio.Component

dataArea, com.optimyth.apm.model.portfolio.Component area, BuilderContext ctx)
Invoked for an Adabas view declared in a data area
public onInclude(String includeName, com.optimyth.apm.model.portfolio.Component item,

BuilderContext ctx)
Invoked for an INCLUDE name
public onCall(String routine, com.optimyth.qaking.natural.ast.NaturalNode call,

public onWindow(String winName, com.optimyth.qaking.natural.ast.NaturalNode win,

Invoked for a window definition (DEFINE WINDOW name)

public onMap(String mapName, com.optimyth.apm.model.portfolio.Component item, BuilderContext
ctx)
Invoked for a INPUT MAP name
public onDatabase(String item, BuilderContext ctx)
Invoked for creating Database entities corresponding to the item (typically an Adabas view)
public onDatabaseOperation(String view, com.optimyth.qaking.natural.ast.NaturalNode op,

Invoked when a certain (Adabas) database operation (op) is detected on a certain view, inside item (a Natural program/routine)
public void end(BuilderContext ctx)
Terminates the callback
rules.natural.NaturalViewRule
Class NaturalViewRule
Structure
Methods Summary
Class NaturalViewRule
NaturalViewRule - Process Natural local data area descriptors (e.g. .NSL files), looking for lines that declare views: <pre> 0010 V 1
VIEWNAME-VIEW VIEWNAME </pre> For each view declared, a new component is declared
Structure
Methods Summary
public void setInclude(String include)
Comma-separated patterns for datafile descriptors to include
public void setExclude(String exclude)
Comma-separated patterns for datafile descriptors to exclude
public void setViewPattern(String viewPattern)
Regexp pattern to use for extracting view name from view records (default: \d+\s+V\s\d+\s+(\S+)\s+(\S+)\s*)
Must have two groups for extracting view alias and view name from the line.
public void setCallback(rules.natural.NaturalDependenciesCallback callback)
The rules.natural.NaturalDependenciesCallback to use
rules.oo
com.optimyth.apm.builder.rules.oo
com.optimyth.apm.builder.rules.oo
Class AbstractClassRule
Structure
Field Summary
Methods Summary
Class AbstractClassRule
package rules.oo
AbstractClassRule - Extends AbstractBuilderRule with common behaviour for extraction rules for any class-oriented language (like Java,
.NET, etc.).
This class adds several setters, so a bean declaration may contain the following lines:
See also
ClassDepsResolver
rules.java.JavaClassBytecodeRule
rules.dotnet.CSharpClassRule
<property name="filter" ref="apm_filter_java"/>

<property name="callback" ref="apm_callback_Class"/>
<property name="sourceDirs" ref="apm_callback_Class"/>

<property name="resolveReturnReferences" value="true"/>
<property name="resolveSqlReferences" value="true"/>
<property name="resolver" ref="apm_classResolver"/>
Where apm_filter_java is a FileFilter matching only java files, apm_callback_Class is a bean which class
implements ClassCallback}, flags decides which dependencies to resolve, and apm_classResolver is a bean that
implements ClassDepsResolver and resolves dependencies found to model entities and relations. Boolean flags are
optional, with default values true for all.
Structure
Field Summary
protected null callback
protected null resolver
protected null boolean resolveInheritance
protected null boolean resolveCalls
protected null boolean resolveInstantiations
protected null boolean resolveTypeReferences
protected null boolean resolveFieldReferences
protected null boolean resolveReturnReferences
protected null boolean resolveSqlReferences
Methods Summary
public void setSourceDirs(java.util.List sourceDirs)
The source dirs where class source files start (in Java, roots of package directories)
public void setSourceDir(java.io.File sourceDir)
The single source dir where class source files start (in Java, root of package directories)
public void setSourcePatterns(String patterns)
Comma-separated list of Ant patterns to use for finding source directories where used classnames will be resolved.
Use this instead of List) or File) if the source
directories are not known in advance but source directories follow certain pattern(s).
NOTE: sourceDir/sourceDirs have precedence over sourcePatterns. If both are specified, sourcePatterns are discarded.
public void setResolveInheritance(boolean resolveInheritance)
If true, inheritance deps will be resolved (default: true)
public void setResolveCalls(boolean resolveCalls)
If true, rule will resolve calls to outer classes matching the filter (default: true)
public void setResolveInstantiations(boolean resolveInstantiations)
If true, rule will resolve object instantiations for outer classes matching the filter (default: false)
public void setResolveTypeReferences(boolean resolveTypeReferences)
If true, rule will resolve type references for outer classes matching the filter (default: false)
public void setResolveFieldReferences(boolean resolveFieldReferences)
If true, rule will resolve field references for outer classes matching the filter (default: false)
public void setCallback(rules.oo.ClassCallback callback)
Callback that will receive the "events" when a new class (or dependency) is matched
callback
The resolver that will resolve candidate dependencies to APM model components and relations
rules.oo.AbstractTypeResolverRule
Class AbstractTypeResolverRule
Structure
Field Summary
Methods Summary
Class AbstractTypeResolverRule
extends from rules.oo.AbstractClassRule
package rules.oo
AbstractTypeResolverRule - In the AbstractClassRule we register different lists of candidate dependencies (var references, type
usages, inheritance, etc...)
These dependencies are solved in the postProcess()</code method. In this class, in the
{{rememberNotResolved() method, we wait before saving a candidate into those lists used by AbstractClassRule. Before that,
we register them as CandidateType.
Every time the rule finds a type, it must call checkResolution method, in order to remove that CandidateType from the
type-resolution pending list, and put it in the correct list (e.g. AbstractClassRule.instantiationsToResolve)
Structure
Field Summary
protected null boolean resolveCode
Methods Summary
public void setTypeResolver(TypeResolver typeResolver)
If set, this resolver tries to resolve a referenced type to its qualified name.
public void setCandidatesToResolve(java.util.List candidatesToResolve)
rules.oo.BasicClassCallback
Class BasicClassCallback
Structure
Methods Summary
Class BasicClassCallback

implements rules.oo.ClassCallback
package rules.oo
BasicClassCallback - Default implementation for rules.oo.ClassCallback. Subclasses may change onXXX callbacks, if needed.
<bean class="com.optimyth.apm.builder.rules.oo.BasicClassCallback">
<property name="addCodeToRelations" value="true"/>
<property name="language" value="vbnet"/>
</bean>
Where myApp is the name of the application where entities should be added, addCodeToRelations decides if the
piece of code behind a relation between classes should be added as a relation's property, and language is the OO
technology being used. All of them are optional with default values ModelConstants#DEFAULT_APP}, and
ClassCallback#JAVA_LANG respectively.
If the application name should be fetched dynamically, a SoftwareResolver could be injected,
Structure
Methods Summary
Name of container application to use if no software resolver is provided (if not provided, defaults to
ModelConstants#DEFAULT_APP)
If set to true, code for the dependency (property RELATION_CODE with List(String)) is added to the relations (default: false)
Language (defaults to java)
Interface ClassCallback
Structure
Field Summary
Methods Summary
Interface ClassCallback
package rules.oo
ClassCallback - Callback that will receive events for extraction rules that process classes in any OO language.
Structure
Field Summary
public static final JAVA_LANG
public static final CSHARP_LANG
public static final VBNET_LANG
public static final CPP_LANG
public static final NULL The /dev/null of ClassCallback. Does nothing: All callback methods return null.
Methods Summary
public boolean isAddCodeToRelations()
public java.lang.String getLanguage()
public onClass(String classname, Object root, BuilderContext ctx)
Adds a new Component under the registered application, adding the current file as artifact.
classname FQCN of the Java class to register

root Object matching the class (e.g. an AST ClassOrInterfaceDeclaration or an ASM ClassNode)
ctx BuilderContext
returns Component with the current Java class registered, added to registered application.
public onReferencedClass(String classname, Object root, BuilderContext ctx)
Adds a new Component under the registered application.
classname FQCN of the Java class to register

root Object matching the class (e.g. an AST ClassOrInterfaceDeclaration or an ASM ClassNode), or ApmEntity containing the
target class
ctx BuilderContext
returns Component with the referenced Java class registered, added to registered application.
public onInheritance(com.optimyth.apm.model.portfolio.Component subclass,
com.optimyth.apm.model.portfolio.Component target, boolean anImplements, BuilderContext ctx)
Adds subclass as a derived class/interface for target (superclass)
subclass Subtype Component (class or interface)

target Supertype Component (class or interface)
anImplements If true, relation is an interface "implements"
ctx Buildercontext
returns ApmRelation subclass -< target (typically named "inherits", with role "extends" or "implements")
public onCall(com.optimyth.apm.model.portfolio.Component source,

com.optimyth.apm.model.portfolio.Component target, String method, String callText, BuilderContext
ctx)
public onInstantiation(com.optimyth.apm.model.portfolio.Component source,

com.optimyth.apm.model.portfolio.Component target, String callText, BuilderContext ctx)
public onTypeReference(com.optimyth.apm.model.portfolio.Component caller,

com.optimyth.apm.model.portfolio.Component called, String refText, BuilderContext ctx)
public onVarReference(com.optimyth.apm.model.portfolio.Component source,

com.optimyth.apm.model.portfolio.Component target, String varname, String refText, BuilderContext
ctx)
public void addCode(String code, com.optimyth.apm.model.relation.ApmRelation rel)
public getHelper()
rules.oracleforms
com.optimyth.apm.builder.rules.oracleforms
com.optimyth.apm.builder.rules.oracleforms
rules.oracleforms.BasicOracleFormsCallback
Class BasicOracleFormsCallback
Structure
Field Summary
Methods Summary
Class BasicOracleFormsCallback

implements rules.oracleforms.OracleFormsCallback OracleFormsPropertyDefinitions PlsqlPropertyDefinitions
package rules.oracleforms
Oracle FORMS callback.
Structure
Field Summary
public static final tokenFinder
Methods Summary
ModelConstants#DB2

ModelConstants#DB2
public void setSchemaResolver(rules.plsql.SchemaResolver schemaResolver)
Set the schema resolver here. Use this alternatively to schema name, but at least one must be specified!
public void setTypeResolver(rules.plsql.PlsqlTypeResolver typeResolver)
The type resolver to use, for resolving referenced PL/SQL types
public void setup(BuilderContext ctx, rules.plsql.PlsqlTypeResolver typeResolver)
rules.oracleforms.OracleFormsCallback
Interface OracleFormsCallback
Structure
Field Summary
Methods Summary
Interface OracleFormsCallback
Structure
Field Summary
Methods Summary
called when a new Oracle Forms source file is found
public onForm(com.optimyth.apm.model.portfolio.Component source, String formName,

BuilderContext ctx)
Callback invoked when a new form is going to be analyzed
returns Component for the form, or null. The component should be linked to a Software element
public onReport(com.optimyth.apm.model.portfolio.Component source, String reportName,

BuilderContext ctx)
Callback invoked when a new report is going to be analyzed
public onMenu(com.optimyth.apm.model.portfolio.Component source, String menuName,

BuilderContext ctx)
Callback invoked when a new menu is going to be analyzed
public onLibrary(com.optimyth.apm.model.portfolio.Component source, String libraryName,

BuilderContext ctx)
Callback invoked when a new library is going to be analyzed

public onReference(com.optimyth.apm.model.portfolio.Component calling,
Callback invoked when a new reference is going to be analyzed
Callback initialization is done here
public getHelper(BuilderContext ctx)
rules.oracleforms.OracleFormsRule
Class OracleFormsRule
Structure
Field Summary
Methods Summary
Class OracleFormsRule
Rule extracts components ORACLE FORMS and their dependencies
Structure
Field Summary
protected null formsCallback
Methods Summary
public void setPlsqlProcessor(rules.plsql.PlsqlCodeProcessor plsqlProcessor)
Sets PLSQL Processor to include PLSQL elements to the model

Sets PLSQL Type Resolver
public void setOracleFormsCallback(rules.oracleforms.OracleFormsCallback formsCallback)
Simple callback for Oracle Forms components creation
public void setAddSqlCode(boolean addSqlCode)
If true, SQL operations are added as entities to containing form
rules.php
com.optimyth.apm.builder.rules.php
com.optimyth.apm.builder.rules.php
rules.php.BasicPhpCallback
Class BasicPhpCallback
Structure
Class BasicPhpCallback

implements rules.php.PhpCallback
package rules.php
BasicPhpCallback - Basic implementation for PhpCallback.
Structure
rules.php.PhpBuilderRule
Class PhpBuilderRule
Structure
Methods Summary
Class PhpBuilderRule
package rules.php
PhpBuilderRule - AIM builder rule for PHP.
Structure
Methods Summary
public void setMethodPredicate(<any> methodPredicate)
NodePredicate that, when matches a candidate MethodDeclaration, the rule will register the method as component of the
enclosing class.
public void setRegisterMethods(boolean registerMethods)
If true, PHP class methods are modelled as operation Components; if false, only dependencies between classes are modelled.
public void setResolveSQL(boolean resolveSQL)
If true, resolve dependencies in embedded SQL code; if false, no SQL code is processed
public void setRegisterFunctions(boolean registerFunctions)
When true, PHP functions are registered as operation Components; when false, only dependencies between PHP programs or
classes are modelled.
public void setCallback(rules.php.PhpCallback callback)
Callback to reflect PHP entities and dependencies in model
public void setSqlListener(rules.j2ee.jdbc.JdbcSqlListener sqlListener)
If set, the views SQL code is parsed for relations with other views/tables
public void setFallbackSqlListener(rules.php.FallbackSqlListener fallbackSqlListener)
Optional FallbackSqlListener instance to process SQL statements when sqlListener cannot parse it
rules.php.PhpCallback
Interface PhpCallback
Structure
Methods Summary
Interface PhpCallback
package rules.php
PhpCallback -
Structure
Methods Summary
public onPhpFile(java.io.File phpFile, BuilderContext ctx)

public onInclude(com.optimyth.apm.model.portfolio.Component currentScript, java.io.File target,
BuilderContext builderContext)
public onClass(String classname, com.optimyth.qaking.php.ast.PhpNode classDecl,

com.optimyth.apm.model.portfolio.Component container, BuilderContext builderContext)
public onMethod(com.optimyth.apm.model.portfolio.Component clazz,

com.optimyth.qaking.php.model.Method m, BuilderContext builderContext)
public onFunction(String fname, com.optimyth.apm.model.portfolio.Component container,

BuilderContext builderContext)
rules.php.PhpDatabaseCallback
Class PhpDatabaseCallback
Structure
Class PhpDatabaseCallback
extends from BasicJdbcCallback
package rules.php
PhpDatabaseCallback -
Structure
rules.plsql
com.optimyth.apm.builder.rules.plsql
com.optimyth.apm.builder.rules.plsql
rules.plsql.BasicPlsqlCallback
Class BasicPlsqlCallback
Structure
Methods Summary
Class BasicPlsqlCallback

implements rules.plsql.PlsqlCallback PlsqlPropertyDefinitions
package rules.plsql
Basic plsql callback, configurable for one database.
Structure
Methods Summary
public void setCaseSensitive(boolean isCaseSensitive)
public void setIgnoreCaseColumns(boolean ignoreCaseColumns)
public void setDatabaseName(String databaseName)
Set the database name here
public void setSchemaResolver(rules.plsql.SchemaResolver schemaResolver)
Set the schema resolver here. Use this alternatively to schema name, but at least one must be specified!
public void setSchemaName(String schemaName)
Set the schema name here. Use this alternatively to schema resolver, but at least one must be specified!
public void setScriptFilter(java.io.FileFilter scriptFilter)
The file filter to match standalone SQL scripts that will be registered in the model.
Useful for discriminating between schema exported SQL (that should not be registered in the model)
and application scripts (that should be registered).
Default: Rejects any script file.

The type resolver to use, for resolving referenced PL/SQL types
rules.plsql.PlsqlBuilderRule
Class PlsqlBuilderRule
Goal
Components
Relations
Structure
Field Summary
Methods Summary
Class PlsqlBuilderRule

implements ApplicationContextAware
package rules.plsql
PlsqlBuilderRule - .
Extracts PL/SQL dependencies: types, functions, procedures, packages (its internal functions/procedures/types as well), triggers, used
SQL queries and tables, used sequences. This rule is typically used for parsing PL/SQL exported by the schemaExtract script for Oracle
(GLOBAL plugin). If your PL/SQL code contains other PL/SQL, the rules.plsql.PlsqlDatabaseSchemaRule subclass could be used
instead for extracting other Oracle entities in PL/SQL code.
Goal
Extracts PL/SQL dependencies: types, functions, procedures, packages (its internal functions/procedures/types as well), triggers, used
SQL queries and tables, used sequences. This rule is typically used for parsing PL/SQL exported by the schemaExtract script for Oracle
(GLOBAL plugin). If your PL/SQL code contains other PL/SQL, the rules.plsql.PlsqlDatabaseSchemaRule subclass could be used
instead for extracting other Oracle entities in PL/SQL code.
Components
Types: class component

Function: storeProcedure component (plsqlType=function)
Procedure: storeProcedure component (plsqlType=procedure)
Package: library software + a bean component representing the body
(Both have plsqlType=package)
Trigger: storeProcedure component (plsqlType=trigger)
Query: databaseObject component
Table: databaseObject component
Sequence: databaseObject component (plsqlType=sequence)
Relations
When the rule detects one of the above dependencies on the PL/SQL program AST,
invokes the proper callback method.
<bean id="apm_rule_plsql" class="com.optimyth.apm.builder.rules.plsql.PlsqlBuilderRule">

<description>Extract dependencies from PL/SQL programs</description>
<property name="filter" ref="apm_filter_plsql"/>
<property name="createInternalObjects" value="true"/> 
<bean class="com.optimyth.apm.builder.rules.plsql.BasicPlsqlCallback">
<property name="databaseName" value="MyDb"/>
<property name="schemaName" value="MySchema"/> 
or:
<property name="schemaResolver" value="MySchema"/> 
</bean>
</property>
</bean>
Structure
Field Summary
protected static CODE_TO_PROCESS
Methods Summary
public void setProcessPhase(int processPhase)
When to process plsql files:

At initialize (<0, the default),
at visit (=0),
at postProcess (>0)
public void setApplicationContext(org.springframework.context.ApplicationContext context)
public void setCreateInternalObjects(boolean createInternalObjects)

If set to true (the default), PL/SQL packages will be analyzed and internal PROCEDURES, FUNCTIONS and TYPES will be
modeled.
If false (the default) they will be analyzed but its dependecies are modeled as top-level dependecies. e.g. Db.function ->
Db.package
public void setAcceptUnresolvedResources(boolean acceptUnresolvedResources)
If set to true, PL/SQL entities (types, stored procedures, schemas and packages) not found in software sources will be created
(when possible).
If set to false, no extra PL/SQL entities. Please remember that when a reference is not fully qualified, it is not possible to infer the
target element.
public void setCallback(rules.plsql.PlsqlCallback callback)
The callback is responsible for adding PL/SQL components to the model
public void setPlsqlProcessor(rules.plsql.PlsqlCodeProcessor codeProcessor)
Inject here the PL/SQL code processor
rules.plsql.PlsqlCallback
Interface PlsqlCallback
Structure
Field Summary
Methods Summary
Interface PlsqlCallback
package rules.plsql
Structure
Field Summary

Methods Summary
Callback initialization is done here
public getHelper(BuilderContext ctx)
public onSqlFile(java.io.File currentFile, BuilderContext ctx)
Called when processing any SQL file. Returns database schema where the SQL file belongs (e.g. with exported schema files)
public onSqlScript(java.io.File currentFile, com.optimyth.apm.model.portfolio.PortfolioEntity

container, BuilderContext ctx)
Called when a SQL script (not a exported schema file) is found. Returns the component modelling the script
public onSchema(String schema, BuilderContext ctx)
Called when a new schema found. Returns the schema component
public onFunction(com.optimyth.apm.model.portfolio.Component dbOrPkg, String functionName,

java.io.File functionFile, BuilderContext ctx)
Called when a PL/SQL function declaration is found
public onProcedure(com.optimyth.apm.model.portfolio.Component dbOrPkg, String procedureName,

java.io.File procedureFile, BuilderContext ctx)
Called when a PL/SQL stored procedure declaration is found
public onType(com.optimyth.apm.model.portfolio.Component typeContainer, String typeName,

java.io.File typeFile, String metatype, BuilderContext ctx)
Called when a PL/SQL type declaration is found
public onTrigger(com.optimyth.apm.model.portfolio.Component db, String triggerName,

java.io.File triggerFile, String timing, BuilderContext ctx)
Called when a PL/SQL trigger declaration is found
public onPackage(com.optimyth.apm.model.portfolio.Component db, String packageName,

java.io.File packageFile, BuilderContext ctx)
Called when a PL/SQL package declaration is found
public onDbLink(com.optimyth.apm.model.portfolio.Component schema, String dbLink,

BuilderContext ctx)
Called when a PL/SQL dblink declaration or usage is found
public onSequenceNextVal(com.optimyth.apm.model.portfolio.Component calling, String

sequenceName, com.als.core.ast.BaseNode sqlStatement, String operation, BuilderContext ctx)
Called when a sequence NEXTVAL or CURRVAL is invoked (an usage of a SEQUENCE by the calling component)
public createRelation(com.optimyth.apm.model.portfolio.Component source,
com.optimyth.apm.model.ApmEntity destination, rules.plsql.PlsqlTypeResolver.RelationType
relationType)
rules.plsql.PlsqlDatabaseSchemaRule
Class PlsqlDatabaseSchemaRule
Structure
Methods Summary
Class PlsqlDatabaseSchemaRule
extends from rules.plsql.PlsqlBuilderRule
package rules.plsql
PlsqlDatabaseSchemaRule - Extends rules.plsql.PlsqlBuilderRule by processing database objects created in DDL statements inside
SQL scripts (CREATE/ALTER TABLE, CREATE VIEW, CREATE INDEX, CREATE SYNONYM, CREATE SEQUENCE, CREATE
DATABASE LINK, COMMENT).
Structure
Methods Summary
public void setDatabaseCallback(rules.sql.DatabaseCallback databaseCallback)
The DatabaseCallback to use for registering database elements not supported by plsql callback
rules.powerscript
com.optimyth.apm.builder.rules.powerscript
com.optimyth.apm.builder.rules.powerscript
rules.powerscript.BasicPowerscriptCallback
Class BasicPowerscriptCallback
Structure
Field Summary
Methods Summary
Class BasicPowerscriptCallback

implements rules.powerscript.PowerscriptCallback PowerscriptPropertyDefinitions
package rules.powerscript
Basic creation of Powerscript classes, methods, functions
Structure
Field Summary
Methods Summary
public void setAllmethods(boolean allmethods)
ModelConstants#DB2
ModelConstants#DB2

The resolver for dependencies between Powerscript classes
rules.powerscript.PowerscriptCallback
Interface PowerscriptCallback
Structure
Field Summary
Methods Summary
Interface PowerscriptCallback
Interface for powerscript callback
Structure
Field Summary
Methods Summary
public void setAllmethods(boolean allmethods)
set if to process all methods
public boolean isAllmethods()

called when a new powerscript source file is found
public onClass(com.optimyth.apm.model.portfolio.Component source, String name, BuilderContext

ctx)
called when a new powerscript class is found
public onMethod(com.optimyth.apm.model.portfolio.Component source, String functionName,

BuilderContext ctx)
called when a new powerscript method is found
public onFunction(com.optimyth.apm.model.portfolio.Component source, String functionName,

BuilderContext ctx)
called when a new powerscript function is found
public onCall(com.optimyth.apm.model.portfolio.Component calling,

called when a new call declaration is found
public onUse(com.optimyth.apm.model.portfolio.Component calling,

called when a new use declaration is found
public onUsedSqlTable(com.optimyth.apm.model.portfolio.Component calling,

rules.sql.QualifiedName tableName, String operation, BuilderContext ctx)
called when a used Table is found
public onSqlStatement(com.optimyth.apm.model.portfolio.Component calling, String operation,

com.als.core.ast.BaseNode sqlStatement, String line, BuilderContext ctx)
called when a sql Statement is found
rules.powerscript.PowerscriptClassRule
Class PowerscriptClassRule
Goal
Technology
Components
Relations
Structure
Field Summary
Methods Summary
Class PowerscriptClassRule
Adds Powerscript classes to the model and all dependencies to its includes files.
Goal
Adds Powerscript classes to the model and all dependencies to its includes files.
Technology
Powerscript
Components
Classes and functions
Relations
This rule simply adds an 'contains' relation: class -> included methods
<bean id="apm_rule_PowerscriptClass" class=

"com.optimyth.apm.builder.rules.database.PowerscriptClassRule">
<property name="application" value="TEST_POWERSCRIPT_APP"/> 
<property name="powerscriptCallback" ref="powerscript.callback"/> 
</bean>
<bean id="powerscript.callback" class=
"com.optimyth.apm.builder.rules.database.PowerscriptCallback">
<property name="allmethods" value="true"/> 
</bean>
Structure
Field Summary
protected null powerscriptCallback
public static CLASS_PRED
public static FUNCTION_PRED
public static INHERITANCE_PRED
public static CLASS_CALL_PRED
public static FUNCTION_CALL_PRED
public static IDENTIFIER_PRED
Methods Summary
Sets SQL Processor to include SQL elements to the model
public void setPowerscriptCallback(rules.powerscript.PowerscriptCallback powerscriptCallback)
Simple callback for powerscript components creation

rules.rpg
com.optimyth.apm.builder.rules.rpg
com.optimyth.apm.builder.rules.rpg
rules.rpg.BasicRpgCallback
Class BasicRpgCallback
Structure
Field Summary
Methods Summary
Class BasicRpgCallback

implements rules.rpg.RpgCallback rules.sql.SqlCallback
package rules.rpg
RpgCallback - Basic implementation of RpgCallback.
Structure
Field Summary
Methods Summary
public void setParseSqlDependencies(boolean parseSqlDependencies)
If set to true, RPG - SQL dependencies will be extracted from EXEC SQL statements
public void setParseFileDependencies(boolean parseFileDependencies)
If set to true, usages of datafiles in RPG will be resolved
public void setRegisterProcedures(boolean registerProcedures)
If true, procedures are registered, and calls to procedures are represented in the model
public void setCopyResolver(rules.common.callresolution.CalledResolver copyResolver)
Resolver to use for matching called programs by name
public void setRegisterUnresolved(boolean registerUnresolved)
If true, unresolved items are registered , under the default software
public void setDefaultSoftwareResolver(rules.common.appresolution.SoftwareResolver

defaultSoftwareResolver)
Default software resolver to use for unresolved items (only used if registerUnresolved = true)
public void setDefaultCalledResolver(rules.common.callresolution.CalledResolver

defaultCalledResolver)
The default resolver to use when injected #setCalledResolver cannot resolve called program.
public void setProgramsToIgnore(rules.common.Predicate programsToIgnore)
Predicate on the programs to ignore (e.g. system programs not of interest)

SqlProcessor for resolving dependencies in embedded EXEC SQL blocks
public void setDatabaseExcludePredicate(rules.common.Predicate databaseExcludePredicate)
ModelConstants#DB2
ModelConstants#DB2
rules.rpg.RpgBuilderRule
Class RpgBuilderRule
Structure
Methods Summary
Class RpgBuilderRule
package rules.rpg
RpgBuilderRule - Builder rule for RPG IV technology.
Structure
Methods Summary
public void setCallback(rules.rpg.RpgCallback callback)

rules.rpg.RpgCallback
Interface RpgCallback
Structure
Field Summary
Methods Summary
Interface RpgCallback
package rules.rpg
RpgCallback - Callback for processing RPG IV (RPG ILE) dependencies.
Structure
Field Summary
public static final RPG4_LANGUAGE
public static final FILETYPE_DATA
public static final FILETYPE_DISPLAY
public static final FILETYPE_SPECIAL
Methods Summary
public void initialize(BuilderContext ctx)
public onProgram(String programName, java.io.File programFile, BuilderContext ctx)
public onProcedure(String procedureName, com.optimyth.apm.model.portfolio.Component program,

BuilderContext ctx)
public onCopy(com.optimyth.apm.model.portfolio.Component source, com.optimyth.rpg4.ast.Copy

copy, BuilderContext ctx)
public onCall(com.optimyth.apm.model.portfolio.Component source, com.optimyth.rpg4.utils.Call

call, BuilderContext ctx)
public onUsedFile(com.optimyth.apm.model.portfolio.Component source,

com.optimyth.rpg4.ast.FileSpecification fileSpec, String fileType, BuilderContext ctx)
public onUsedDataArea(com.optimyth.apm.model.portfolio.Component source, String dataArea,
String command, BuilderContext ctx)
public onUsedDataArea(com.optimyth.apm.model.portfolio.Component source,

com.optimyth.apm.model.portfolio.Component dataArea, String command, BuilderContext ctx)
public void onExecSql(com.optimyth.apm.model.portfolio.Component source,

com.als.core.ast.BaseNode node, String sqlCode, BuilderContext ctx)
public void postProcess(BuilderContext ctx)
rules.soa
com.optimyth.apm.builder.rules.soa
com.optimyth.apm.builder.rules.soa
rules.soa.WSDLRule
Class WSDLRule
Structure
Methods Summary
Class WSDLRule
package rules.soa
Web Service WSDL Rule - Process WSDL descriptors, creating web service components and optionally operations (as method
components) when createWebServiceMethods = true.
Structure
Methods Summary
If set to true, webservice operations in WSDL will be registered as subcomponents of webservice

rules.spring
com.optimyth.apm.builder.rules.spring
com.optimyth.apm.builder.rules.spring
rules.spring.BasicSpringDescriptorCallback
Class BasicSpringDescriptorCallback
Structure
Field Summary
Methods Summary
Class BasicSpringDescriptorCallback

implements rules.spring.SpringDescriptorCallback SpringPropertyDefinitions
package rules.spring
BasicSpringDescriptorCallback - Basic implementation of rules.spring.SpringDescriptorCallback resolving bean definitions and

dependencies.
<bean id="apm_callback_SpringDescriptor" class=
"com.optimyth.apm.builder.rules.spring.BasicSpringDescriptorCallback">
<property name="beanFilter" value="myBeanFilter"/>
<property name="classFilter" value="myClassFilter"/>
</bean>
Where application is the application name where beans belong to, beanFilter decides what beans should be
filtered out and classFilter decides what beans should be filtered out based on their classname. All three
properties are optional, with default values ModelConstants#DEFAULT_APP, BeanFilter#ALL ("accept all beans") and
Predicate#JDK_FILTER ("ignore JDK classes"), respectively.
In the #setSpringProcessor property, extra processors for modelling specific resources could be registered, so the raw
beans could be related to extra model entities.
Structure
Field Summary
public static final SPRING_FILTER
Methods Summary
public void setBeanFilter(rules.spring.BeanFilter beanFilter)
The bean filter to use for deciding which beans and dependencies the rule will process
public void setClassFilter(rules.common.Predicate classFilter)
The bean classes that will be EXCLUDED from processing match classFilter.
public void setSpringProcessor(rules.spring.processors.SpringProcessor springProcessor)
The SpringProcessor to notify when Spring elements (descriptor, bean, dependency, imported descriptor) are processed.
The resolver for dependencies between Spring beans and Java classes
rules.spring.SpringDescriptorCallback
Interface SpringDescriptorCallback
Structure
Field Summary
Methods Summary
Interface SpringDescriptorCallback
SpringDescriptorCallback - Logic for converting Spring bean definitions and dependencies to Component entities.
Structure
Field Summary
Methods Summary
public void initialize(BuilderContext ctx)
Invoked at rule initialization, to initialize the callback
public onDescriptor(java.io.File descriptor, BuilderContext ctx)
Callback invoked when a new descriptor is going to be analyzed
descriptor File for the Spring descriptor

ctx BuilderContext
returns Component for the descriptor, or null. The component should be linked to a Software element
public onBean(rules.spring.BeanDeclaration beanDefinition, BuilderContext ctx)

Callback invoked when a bean definition was found
beanDefinition The bean definition data

ctx RuleContext @return Component (or null if the bean is discarded)
public onDependency(rules.spring.BeanDependency beanDependency, BuilderContext ctx)
Callback invoked when an injected dependency (setter or constructor) was found
beanDependency The dependency data

ctx BuilderContext
returns ApmRelation for the dependency (or null if callback decides to ignore it)
public void onAlias(String key, String alias, BuilderContext ctx)
Registers an alias
key The bean key

alias The aliased name on key
ctx BuilderContext
public void onImported(String resource, BuilderContext ctx)
Registers an imported descriptor
resource The imported Spring descriptor (a resource)

ctx BuilderContext
public void postProcess(BuilderContext ctx)
Callback invoked at rule post-processing, to try to resolve dependencies

on beans not available when the dependency was discovered
rules.spring.SpringDescriptorRule

Class SpringDescriptorRule
Goal
Technology
Components
Relations
Structure
Methods Summary
Class SpringDescriptorRule
SpringDescriptorRule -
Process parsed Spring descriptors looking for bean definitions, dependencies between them and imports.
See also
rules.spring.SpringDescriptorCallback
Goal
Process parsed Spring descriptors looking for bean definitions, dependencies between them and imports.
Technology
Java / Spring
Components
configuration (per Spring descriptor file), bean
Relations
uses relation (between injection dependencies between beans, configures relation between beans and the descriptors where they are
declared
<bean id="apm_rule_SpringDescriptor" class=

"com.optimyth.apm.builder.rules.spring.SpringDescriptorRule">
<property name="filter" ref="apm_filter_spring"/>
<property name="callback" ref="apm_callback_SpringDescriptor"/>
</bean>
Where apm_filter_spring is a FileFilter matching only Spring descriptors, and

apm_callback_SpringDescriptor is a bean which class implements rules.spring.SpringDescriptorCallback.
Structure
Methods Summary
public void setCallback(rules.spring.SpringDescriptorCallback callback)
The SpringDescriptorCallback to use
rules.spring.webflow
com.optimyth.apm.builder.rules.spring.webflow
com.optimyth.apm.builder.rules.spring.webflow
rules.spring.webflow.BasicSpringWebflowCallback
Class BasicSpringWebflowCallback
Structure
Methods Summary
Class BasicSpringWebflowCallback

implements rules.spring.webflow.SpringWebflowCallback
package rules.spring.webflow
BasicSpringWebflowCallback - Basic implementation for rules.spring.webflow.SpringWebflowCallback
<bean id="apm_callback_CLScript" class=

"com.optimyth.apm.builder.rules.cl400.DefaultCLScriptCallback">
<property name="parseBeanImports" value="true"/>
<property name="webappRoot" value="myWebappRootpath"/>
</bean>
Where application is the name of the Web Application using Spring Webflow, parseBeanImports decides if
bean-import elements should be processed, and webappRoot is the Web Application's basedir. If no
application were set, ModelConstants#DEFAULT_APP would be used. parseBeanImports is false by default.
webappRoot is not mandatory either, but you will need to fill it if you want to parse relations between view-states
and their JSP pages.
Structure
Methods Summary
Application name to use as Software container for discovered webflows
public void setWebappRoot(String webappRoot)
Web application root
public void setParseBeanImports(boolean parseBeanImports)
rules.spring.webflow.SpringWebflowCallback
Interface SpringWebflowCallback
Structure
Field Summary
Methods Summary
Interface SpringWebflowCallback
SpringWebflowCallback - Generic callback for flow descriptors found and their inner elements (states, transitions and imports).
Structure
Field Summary
Methods Summary
public onWebflow(java.io.File descriptor, BuilderContext ctx)
public onViewState(com.optimyth.apm.model.portfolio.Component webflow, String stateId)
public onView(com.optimyth.apm.model.portfolio.Component state, String view)

public onActionState(com.optimyth.apm.model.portfolio.Component webflow, String stateId)
public onDecisionState(com.optimyth.apm.model.portfolio.Component webflow, String stateId)
public onSubflowState(com.optimyth.apm.model.portfolio.Component webflow, String stateId)
public onEndState(com.optimyth.apm.model.portfolio.Component webflow, String stateId)
public onTransition(com.optimyth.apm.model.portfolio.Component webflow, String fromId, String

toId, String on)
public onBeanImport(com.optimyth.apm.model.portfolio.Component webflow, String beanResource)
rules.spring.webflow.SpringWebflowRule
Class SpringWebflowRule
Goal
Technology
Structure
Methods Summary
Class SpringWebflowRule
SpringWebflowRule -
Process Spring Webflow descriptors and looks for bean imports, view/action/decision/subflow/end states and transitions between them.
See also
rules.spring.webflow.SpringWebflowCallback
Goal
Process Spring Webflow descriptors and looks for bean imports, view/action/decision/subflow/end states and transitions between them.
Technology
Java / Spring Webflow
<bean id="apm_rule_SpringWebflow" class=

"com.optimyth.apm.builder.rules.spring.webflow.SpringWebflowRule">
<property name="filter" ref="apm_filter_flows"/>
<property name="callback" ref="apm_callback_SpringWebflow"/>
</bean>
Where apm_filter_flows is a FileFilter matching only Spring Webflow descriptors, and

apm_callback_SpringWebflow is a bean which class implements rules.spring.webflow.SpringWebflowCallback.
Structure
Methods Summary
public void setCallback(rules.spring.webflow.SpringWebflowCallback callback)
rules.sql
com.optimyth.apm.builder.rules.sql
com.optimyth.apm.builder.rules.sql
rules.sql.BasicDatabaseCallback
Class BasicDatabaseCallback
Structure
Methods Summary
Class BasicDatabaseCallback

implements rules.sql.DatabaseCallback
package rules.sql
BasicDatabaseCallback -
Structure
Methods Summary
public void setCaseSensitive(boolean caseSensitive)

If false (the default), all names are converted to uppercase; if true, names are left intact
Should be called to ensure that getHelper() returns a non-null helper instance
rules.sql.DatabaseCallback
Interface DatabaseCallback
Structure
Field Summary
Methods Summary
Interface DatabaseCallback
package rules.sql
DatabaseCallback - Basic callback for registering generic database entities.

The methods match what are considered the most common/generic elements in databases, relevant for dependency analysis.
Structure
Field Summary
Methods Summary
Should be called to ensure that helper instance is correctly setup

public onDatabase(String databaseName, String dbType,
com.optimyth.apm.model.portfolio.PortfolioEntity container)
public onSchema(String schemaName, String description,

com.optimyth.apm.model.portfolio.PortfolioEntity database)
public onTable(String tableName, String comment, String columnNames, int rows,

public onView(String viewName, String comment, String sql, String columnNames,

public onPrimaryKey(String pkName, String columnNames, String comment,

com.optimyth.apm.model.portfolio.Component table)
public onIndex(String indexName, String columnNames, String comment,

com.optimyth.apm.model.portfolio.Component table)
public onTrigger(String triggerName, String comment, String event,

com.optimyth.apm.model.portfolio.Component table,
public onDatabaseSequence(String seqName, String comment, String detail,

public onDatabaseLink(String name, String connection,

public onUserType(String typeName, String comment,

public onSynonym(String name, String target, com.optimyth.apm.model.portfolio.PortfolioEntity
container)
public onPackage(String pkgName, com.optimyth.apm.model.portfolio.PortfolioEntity container)
public onStoredProcedure(String procedureName, com.optimyth.apm.model.portfolio.PortfolioEntity

container)
public onDatabaseFunction(String functionName, com.optimyth.apm.model.portfolio.PortfolioEntity

container)
public onForeignKey(String name, String description, String actions,

com.optimyth.apm.model.portfolio.Component parentTable, String parentColumns,
com.optimyth.apm.model.portfolio.Component targetTable, String targetColumns)
rules.sql.SqlCallback
Interface SqlCallback
Structure
Methods Summary
Interface SqlCallback
package rules.sql
SQL-AST processing: this class is a sql helper (used for example by JDBC, Cobol or PLSQL rules)
Structure
Methods Summary
public onUsedSqlTable(com.optimyth.apm.model.portfolio.Component calling,

rules.sql.QualifiedName tableName, String operation, BuilderContext ctx)
Called when a table is reference. Calling is the component that uses the table. tableName is the qualified name.
Typically this finds in the model the schema where the table lives
public onSqlStatement(com.optimyth.apm.model.portfolio.Component calling, String operation,

com.als.core.ast.BaseNode sqlStatement, String line, BuilderContext ctx)
Called when a SQL statement is found. Calling is the component that emits the SQL.
This typically analyzes the SQL and registers the database objects used in the statement
rules.struts
com.optimyth.apm.builder.rules.struts
com.optimyth.apm.builder.rules.struts
rules.struts.JspStrutsCallback
Class JspStrutsCallback
Structure
Class JspStrutsCallback
extends from BasicJspCallback
package rules.struts
This callback creates the relation between the jsp and the Struts action (encoded as html:form element in JSP).
Creates a formBean (elementstrutsType=action) component, and a jsp (page) uses:action> formBean relation.
Structure
rules.struts.JspStrutsRule
Class JspStrutsRule
Structure
Methods Summary
Class JspStrutsRule
JspStrutsRule - Resolve Struts' actions referenced by html:form elements in JSP pages.
See also
rules.struts.JspStrutsCallback
Structure
Methods Summary
public void setCallback(rules.struts.JspStrutsCallback callback)

The (fallback) directory where web content can be found (for resolving
relative URLs to code resources).
Matching WebApp
bean (detected by
rules.j2ee.webapp.webxml.WebXmlRule) will
be tried. If no WebApp is matched, this webContents is used as fallback
base dir for JSP resources. This permits the rule to operate without a
WebXmlRule resolving web applications explicitely.
rules.struts.StrutsCallback
Class StrutsCallback
Structure
Field Summary
Methods Summary
Class StrutsCallback
StrutsCallback - struts-config.xml extraction callback
Structure
Field Summary
public static final pathDef
Methods Summary
rules.struts.StrutsRule
Class StrutsRule
Structure
Methods Summary
Class StrutsRule
StrutsRule - Process Struts XML descriptors, and registers actions and form beans found.
Structure
Methods Summary
public void setCallback(rules.struts.StrutsCallback callback)
rules.tag
com.optimyth.apm.builder.rules.tag
com.optimyth.apm.builder.rules.tag
rules.tag.PropagationTagRule
Class PropagationTagRule
Structure
Methods Summary
Class PropagationTagRule
extends from rules.tag.TagRule
package rules.tag
PropagationTagRule - A tag rule that use uses a startAql / startTagOperation to find and tag matched entities, and on each matched
entity applies a (typically relative) propagationAql to found "dependent" entities, that are tagged by the propagationTagOperation.
Structure
Methods Summary
public void setPropagationAql(String propagationAql)
the propagation AQL, that will return which entities from each source entity will be tagged
public void setPropagationTagOperation(com.optimyth.apm.model.tagging.tagops.TagOperation

propagationTagOperation)
Optional tag operation; if not set, uses the parent startTagOperation
rules.tag.TagRule
Class TagRule
Structure
Methods Summary
Class TagRule
package rules.tag
TagRule - Trivial tagging rule, for applying a tag operation on each entity matching an AQL query.
Structure
Methods Summary
public void setStartAql(String startAql)
AQL for selecting with entities to tag ("starters")
public void setStartTagOperation(com.optimyth.apm.model.tagging.tagops.TagOperation

startTagOperation)
Tag operation to execute on each entity matched by the startAql condition
public void setQueryEngine(com.optimyth.apm.modelquery.IQueryEngine queryEngine)
rules.transactsql
com.optimyth.apm.builder.rules.transactsql
com.optimyth.apm.builder.rules.transactsql
rules.transactsql.TransactSqlBuilderRule
Class TransactSqlBuilderRule
Structure
Methods Summary
Class TransactSqlBuilderRule

package rules.transactsql
TransactSqlBuilderRule - Models database entities found in Transact-SQL (T-SQL) code. Remember that SQL Server has a 4-part
naming scheme: server.database.ownerSchema.object.
Structure
Methods Summary
public void setCaseSensitive(boolean isCaseSensitive)
public void setDatabaseCallback(rules.sql.DatabaseCallback databaseCallback)
Database callback for creating database entities
public void setDatabaseResolver(rules.sql.DatabaseResolver databaseResolver)
Database resolver for classifying database names
rules.validation
com.optimyth.apm.builder.rules.validation
com.optimyth.apm.builder.rules.validation
rules.validation.DeclarativeValidationRule
Class DeclarativeValidationRule
Structure
Methods Summary
Class DeclarativeValidationRule
extends from AbstractValidationRule
package rules.validation
DeclarativeValidationRule - Rule that uses DEPendencies VAlidation Language (DEPVAL) to detect non-valid dependencies
found in a software system source code.
Please see checKing AIM Manual for a complete specification on DEPVAL.
Structure
Methods Summary
public void setCode(String code)
The VRL code could be injected directly
public void setCodeResource(org.springframework.core.io.Resource codeResource)
Specify the resource containing the VRL code
rules.vb
com.optimyth.apm.builder.rules.vb
com.optimyth.apm.builder.rules.vb
rules.vb.BasicVisualBasicCallback
Class BasicVisualBasicCallback
Structure
Field Summary
Methods Summary
Class BasicVisualBasicCallback

implements rules.vb.VisualBasicCallback
package rules.vb
Structure
Field Summary
public static final VB_LANG
Methods Summary
public void setApplicationName(String applicationName)

Set the application name here (alias to {@link #setSoftwareName)
public void setLibraryContainerName(String libraryContainerName)
Set the dll container here. Unused
rules.vb.VbpBuilderRule
Class VbpBuilderRule
Goal
Technology
Components
Relations
Structure
Class VbpBuilderRule
extends from rules.vb.VisualBasicBuilderRule
package rules.vb
VbpBuilderRule -
This rule gets the most important information from VBP project (.vbp) file . A VBP file contains the references to external components:
bas modules, ocxs, dlls... to be resolved. It also identifies the existence of a vbProject.
Goal
This rule gets the most important information from VBP project (.vbp) file . A VBP file contains the references to external components:
bas modules, ocxs, dlls... to be resolved. It also identifies the existence of a vbProject.
Technology
vb6
Components
VB application (Software of type application), referenced DLLs (as Software of type library), ActiveX controls or modules (as bean),
class, form (window)
Relations
relations between VB application and referenced elements
<bean id="apm_rule_vbp" class="com.optimyth.apm.builder.rules.vb.VbpBuilderRule">
<description>Resolves a VB6 application and dependencies declared in .vbp files
</description>
<property name="callback" ref="apm_rule_vb_callback"/>
</bean>
Where callback is the rules.vb.VisualBasicCallback to use for interacting with the model.
An optional filter could be used to limit the .vbp files to process (if not provided, all .vbp files will be processed).
Structure
rules.vb.VisualBasicBuilderRule
Class VisualBasicBuilderRule
Structure
Field Summary
Methods Summary
Class VisualBasicBuilderRule
package rules.vb
AbstractVisualBasicBuilderRule - A base for all the Visual Basic rules. TODO resolve calls and other language relevant elements
Structure
Field Summary
public static final STARTER_TAG
protected null callback
Methods Summary
public void setBasedir(java.io.File basedir)
Directory where application directories are placed
public void setCallback(rules.vb.VisualBasicCallback callback)

The callback is responsible for adding VB components to the model
rules.vb.VisualBasicCallback
Interface VisualBasicCallback
Structure
Field Summary
Methods Summary
Interface VisualBasicCallback
package rules.vb
Structure
Field Summary
Methods Summary
public getVbApplication(java.io.File file, java.io.File basedir, BuilderContext ctx)
public getLibraryContainer(com.optimyth.apm.model.portfolio.Software application, java.io.File

dllFile, BuilderContext ctx)
public onClass(com.optimyth.apm.model.portfolio.Software application, String className,

java.io.File classFile, BuilderContext ctx)
public onForm(com.optimyth.apm.model.portfolio.Software application, java.io.File formFile,

BuilderContext ctx)
public onForm(com.optimyth.apm.model.portfolio.Software application, String formName,

BuilderContext ctx)
public onModule(com.optimyth.apm.model.portfolio.Software application, String moduleName,

java.io.File moduleFile, BuilderContext ctx)
public onReferencedModule(com.optimyth.apm.model.portfolio.Software application, java.io.File
moduleFile, BuilderContext ctx)
public onReferencedControl(com.optimyth.apm.model.portfolio.Software application, String

controlName, String ext, BuilderContext ctx)
public onReferencedDll(com.optimyth.apm.model.portfolio.Software application, java.io.File

dllFile, BuilderContext ctx)
public onCalledWindow(String calledWin, com.optimyth.apm.model.portfolio.Software caller,

com.optimyth.apm.model.portfolio.Component callingWin, BuilderContext ctx)
variables.rules
com.optimyth.apm.builder.variables.rules
com.optimyth.apm.builder.variables.rules
variables.rules.DefaultVariablesCallback
Class DefaultVariablesCallback
Structure
Class DefaultVariablesCallback
extends from RuleVariablesCallbackBase
package variables.rules
Default Callback for variables
Structure
variables.rules.IVariablesCallback
Interface IVariablesCallback
Structure
Field Summary
Methods Summary
Interface IVariablesCallback
package variables.rules
IVariablesCallback - Callback for process variables of programs
Structure
Field Summary
Methods Summary
public com.optimyth.apm.model.variables.Program addProgram(String programName, BuilderContext

ctx)
Method that add any program with name programName
programName Program name

ctx Context
returns Object program
public com.optimyth.apm.model.variables.Program addProgramCalled(String calledName,

BuilderContext ctx)
Method that add program called
calledName Program called name

ctx
returns Program
public com.optimyth.apm.model.variables.ProgramCall
addProgramCall(com.optimyth.apm.model.variables.Program caller,
com.optimyth.apm.model.variables.Program called, BuilderContext ctx)
Method that add program call
caller Program caller

called Program called
ctx
returns ProgramCall
public com.optimyth.apm.model.variables.Variable
addVariable(com.optimyth.apm.model.variables.Variable v, BuilderContext ctx)
Method that add variable
v Data of Variable
ctx Context
returns Variable
public com.optimyth.apm.model.variables.RelationVar
addRelationVar(com.optimyth.apm.model.variables.RelationVar rel, BuilderContext ctx)
Method that add variable relation
rel Relation
ctx Context
returns RelationVar
public getVariablesHelper(BuilderContext ctx)
Method that provided access to helper
ctx Context
returns Helper for variables
variables.rules.cobol
com.optimyth.apm.builder.variables.rules.cobol
com.optimyth.apm.builder.variables.rules.cobol
variables.rules.cobol.CobolVariablesBuilderRule
Class CobolVariablesBuilderRule
Structure
Methods Summary
Class CobolVariablesBuilderRule
package variables.rules.cobol
CobolVariablesBuilderRule - Rule to process Variables cobol
Structure
Methods Summary
public void setStatementProcessor(variables.rules.IStatementProcessor statementProcessor)
public void setCallback(variables.rules.IVariablesCallback callback)
public void setSqlVariablesProcessor(variables.rules.cobol.SqlVariablesProcessor

sqlVariablesProcessor)
Model Builder Task Management interface
Model Builder Task Management interface
When a model build task is launched, a set of JMX MBeans (management objects) are published and could be accessed using any
external JMX-enabled tools, like jconsole or jvisualvm (provided with Oracle Java Runtime). Simply connect the JMX console to the
model builder java process (ConfigurationApmModelBuilderTask).
JMX management interfaces (beans) are exposed by the model builder script for monitoring and/or live configuration changes. The
beans could be seen in the JMX management console:
Execution traces
Sometimes, custom rules may produce infinite loops that are difficult to trace in a running model builder task. Using a JMX console you
may look at the existing processing thread (main):
This could help detecting problems (like infinite loops or performance problems) in custom rules.
Model building script: com.optimyth.aim:type=modelBuilder
Exposes management interface for the current model builder script under execution.
Statistics help to understand how model building is progressing.
CurrentFile string Full path to the software file currently processed.
CurrentRule string Identifier of the rule currently under execution.
CurrentState string The current analysis phase in execution.
Statistics table Statistics for analysis.
cancel void cancel() Force graceful cancellation of the model building task.
Note: Properties are also exposed as operations for programmatic access.
Detailed trace: com.optimyth.aim:type=listeners,name=logger
Controls trace logger, that generate log entries in the trace logfile for each model building event (rule execution, source file processing,
and creation of enties and relations in model).
Setting all log levels to DEBUG ensure that all events are logged (use with caution in production, as logging may impact performance).
Active boolean If true, trace is active.
Logfile string The full path to server trace logfile
MainLevel string Logging level for main model building events (DEBUG, INFO, WARN, ERROR,
OFF)
ModelLevel string Logging level for model entities & relations creation events (DEBUG, INFO, WARN,
ERROR, OFF)
ParseLevel string Logging level for source parsing events (DEBUG, INFO, WARN, ERROR, OFF)
RuleLevel string Logging level for rule execution events (DEBUG, INFO, WARN, ERROR, OFF)
clearLogFile void clearLogFile() Empties trace logfile
openLogHub void openLogHub(int port, string Create a log hub (server where log collectors can connect)
format)
Profiler: com.optimyth.aim:type=listeners,name=profiler
Controls the AIM profiler. This profiler remembers elapsed time in parsing and rule execution, and could be useful for optimizing custom
rules.
The output is generated in a CSV (comma-separated values) that could be opened in Excel.
Active boolean If true, profiler is active.
FilesProfiled boolean If true, elapsed time for processing each input file is stored. May penalize performance.
ParsersProfiled boolean If true, parse times are collected for each language processed.
RulesProfiled boolean If true, rule execution times are collected.
ReportPath string The full path to server profiling CSV file.
dump void dump(string path) Dumps current profiling data either to screen or to the given file path (when provided)
Configuration: com.optimyth.aim:type=configuration,tech=TECH,subtech=SUBTECH
Each configuration block is represented by a JMX bean that provides read-only access to the configuration properties.
These beans could be useful for checking configuration properties.
Configuration table Values for each configuration property (read-only)
Description string Description for the configuration block (read-only)
Technology string Name of the configuration block's technology (read-only)
SubTechnology string Name of the configuration block's subtechnology (read-only)
getProperty string getProperty(string key) The value for the requested configuration property
Represents query server logging system. This management interface permits live changes on the logging configuration.
DefaultLevel string Log4J default log level
LogFile string Path to the query server logfile (read-only)
getLevel string getLevel(string logger) Get logging level for the logger item
setLevel void setLevel(string logger, string level) Set logging level for logger item
configure void configure(string) Configures logging (properties text or path to .properties file)
clearLogFile void clearLogFile() Cleans logfile (remove all content)
getLoggers string[] getLoggers() Get names of logger items registered
deactivateLogging void deactivateLogging(string logger) Deactivate logging for the given logger
printConfiguration string printConfiguration() Dumps current Log4J logging configuration
openLogHub void openLogHub(int port, string format) Create a log hub (server where log collectors can connect)
APPENDIX I - Components types and subtypes

At the state of the art of, checkingAIM rules detect and add the following types and subtypes to APPMAP models:
Types
person
unit
organization
software
component
class
program
configuration
operation
webService
flow
page
resource
databaseInstance
databaseObject
storedProcedure
sql
window
group
other
Obsolete:
businessProcess
businessObject
businessService
table
view
Subtypes
softwareType
application
module
layer
library
middleware
tool
product
framework
database
other
programType (cobol)
script
copy
unitType
area
subarea
department
staff
workgroup
other
orgType
ownOrg
delegation
partner
softwareFactory
other
j2eeType
servlet
filter
jsp
resource
taglib
contextListener
statefulSessionBean
statelessSessionBean
entityBean
messageDrivenBean
springType
bean
plsqlType
function
procedure
trigger
package
sequence
aspnetType
page
masterpage
webservice
control
httpHandler
httpModule
resource
assembly
codeBehindClass
aspType
page
comobj
resource
abapType
report
program
fpool
class
interface
screen
selection
form
module
function
macro
data
dialog
table
query
transaction
transformation
APPENDIX II - System requeriments for AIM
Checking QA
Checking AIM is technically a plugin for checking QA product. This is then the main requirement: you need a full installation of
checking QA to get AIM working.
Please, also refer to "APPMAP plugin" section for installation details.
Disk capacity requirements

For each AIM model built, different files are created to persist the software model. The total size of files created depends on the following
variables:
1. The number of architectural violations encountered;

2. The number of components and relationships modelled.
The number of components and relations (registered in model datafile) dominates the size of the generated files, so only this factor will
be considered here. The number of components and relationships are intimately related with the source code analysed. The following
considerations are based on one specific model as follows:
Components: 10K
Relationships: 100K
The total size of all the files generated when a model with this size is analyzed is about 40MB.
If you know in advance the approximate number of entities to be represented in all your AIM model datafiles, a (conservative) rule of
thumb is to reserve 5KB of hard disk per entity.
Directories Access
Models are placed in the CHECKING_DATA/config/plugindata/appmap directory. Due to performance
considerations, it is recomended that this directory is placed in a local hard disk. Performance may suffer if this
directory is placed in a network (shared) disk unit.
Checking AIM requires read/write access to USER_HOME. For example, in Windows 7: C:\Users\<Username>
Memory requirements
The building model process is an intensive analysis job the goal of which is to extract the different components and relationships. It is
achieved by parsing all the source code.
For the previous specified model (with 22K components and 220K relationships) 1GB RAM should be necessary for each concurrent
analysis.

AIMDOCS

Uploaded by

Copyright:

Available Formats

AIMDOCS

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

AIMDOCS

Uploaded by

Copyright:

Available Formats

Appendix A - Deprecated API

com.optimyth.apm.modelquery.FunctionCallException.getNestedException() replaced by Throwable.getCause()

com.optimyth.apm.builder.rules.j2ee.jdbc.JdbcDependenciesCallback Use JdbcCallback instead (TODO: modify JdbcBuilderRule to

com.optimyth.apm.builder.rules.j2ee.jdbc.JdbcBuilderRule Use JdbcRule instead

com.optimyth.apm.builder.rules.model.ComponentsHelper.addMethod(String, Component) Use addBean(), is the same...

Appendix B - Rules migration

New Types class

Component.ComponentType and Software.SoftwareType objects and do not exist anymore.

To use a custom type, just pass an arbitrary string to ComponentsHelper.

Set<Software> apps = callingWindow.getSoftware().getParentSoftwares();

// should be replaced with:

Iterable<Software> apps = Softwares.getParentSoftwares(callingWindow.getSoftware());

// should be replaced with:

Most of the old collections are now returned are Iterable.

For example, the iteration PortfolioModel.getEntities():

for (Iterator i = ctx.getPortfolioModel().getEntities(); i.hasNext() \;) {

Almost all PropertyDefinitions remain centralized in com.optimyth.apm.model.PropertyDefinitions class.

In the previous version, there were multiple classes as com.optimyth.apm.model.portfolio.PropertyDefinitions which

ComponentsHelper has very few changes:

Now it implements an interface, IComponentsHelper, which is the return type of RuleCallbackBase.getHelper().

Good practices - Model semantics

Low level entity creation

public Component addDataArea(Component container, String dataAreaName) {

ApmRelation contains = contains(container, dataArea);

// would be replaced with:

public Component addDataArea(Component container, String dataAreaName) {

Component dataArea = getBuilderContext().getPortfolioModel().getComponent(key);

// Here is the component cretion... adding it to portfolioModel is now *not* necessary

dataArea.setDescription("Data area "+dataAreaName);

ApmRelation contains = contains(container, dataArea);

PropertyDefinition ENTRY_PROGRAM = new PropertyDefinition("cics.1", "entryProgram", "entry

// must be changed to:

Property<String> entryProgram = new Property<String>(ENTRY_PROGRAM, trans.program);

// should be translated to:

Tags class has disappeared, and a Set<String> is used.

Adding a tag to a component c (this remains unaltered)

Adding an artifact to a component c:

if (datafile != null) transaction.setArtifacts(new Artifacts(ctx.getModel().getBaseDirs(),

// should be replaced with:

String art = ArtifactsUtil.encode(ctx.getModel().getBaseDirs(), datafile);

Replacing getLocations() method:

Artifacts artifactsTarget = compTarget.getArtifacts();

// should be replaced with:

List<String> artifactsTarget = compTarget.getArtifacts();

checking AIM Basic Concepts

What does it do?

Merges, acquisitions and enterprise consolidations;

How does it do this?

checKing AIM allows the organisation to:

What are the benefits?

checKing AIM helps enterprises from different perspectives:

What are its potential usages?

Figure 1: Application Map Portfolio

Modules, components, application logic and dependencies;

What is the dependency Model

A model could be generated to answer the following questions:

What web services are related to a given business process?

APPMAP is a checKing plug-in that provides:

A browser (Swing technology, launchable via script or JNLP);

Types of rules according to their purpose

// Here is the component cretion... adding it to portfolioModel is now not necessary