0
# Language Module Integration
1

2
Core integration components that connect the Velocity template analysis module with PMD's multi-language framework, providing language registration, parsing coordination, and rule violation handling.
3

4
## Capabilities
5

6
### Language Module Registration
7

8
Main entry point for registering Velocity template support within PMD's language framework.
9

10
```java { .api }
11
/**
12
 * Main language module class that registers Velocity template support in PMD.
13
 * Extends BaseLanguageModule to integrate with PMD's multi-language architecture.
14
 */
15
public class VmLanguageModule extends BaseLanguageModule {
16
    /** Language identifier constant used throughout PMD */
17
    public static final String NAME = "VM";
18
    /** Short language identifier for command-line and configuration */
19
    public static final String TERSE_NAME = "vm";
20
    
21
    /**
22
     * Constructor that registers the Velocity language module with PMD.
23
     * Automatically called during PMD initialization.
24
     */
25
    public VmLanguageModule();
26
}
27
```
28

29
**Usage Example:**
30

31
```java
32
// PMD automatically discovers and registers language modules
33
// No manual instantiation required for standard PMD usage
34
VmLanguageModule module = new VmLanguageModule();
35

36
// Access language constants
37
String languageName = VmLanguageModule.NAME; // "VM"
38
String shortName = VmLanguageModule.TERSE_NAME; // "vm"
39
```
40

41
### Language Version Handler
42

43
Coordinates parsing, AST dumping, and rule violation creation for Velocity templates.
44

45
```java { .api }
46
/**
47
 * Language version handler that manages parsing and analysis coordination
48
 * for Velocity templates within PMD's processing pipeline.
49
 */
50
public class VmHandler extends AbstractLanguageVersionHandler {
51
    
52
    /**
53
     * Returns the rule violation factory for creating Velocity-specific violations.
54
     * @return VmRuleViolationFactory singleton instance
55
     */
56
    public RuleViolationFactory getRuleViolationFactory();
57
    
58
    /**
59
     * Creates a parser instance for processing Velocity template source code.
60
     * @param parserOptions Configuration options for parsing behavior
61
     * @return VmParser instance configured with the specified options
62
     */
63
    public Parser getParser(ParserOptions parserOptions);
64
    
65
    /**
66
     * Creates a visitor for dumping AST structure to output stream.
67
     * Used for debugging and analysis of parsed template structure.
68
     * @param writer Output writer for AST dump
69
     * @param prefix String prefix for formatting output
70
     * @param recurse Whether to recursively dump child nodes
71
     * @return VisitorStarter for AST dumping
72
     */
73
    public VisitorStarter getDumpFacade(Writer writer, String prefix, boolean recurse);
74
}
75
```
76

77
**Usage Example:**
78

79
```java
80
import java.io.StringWriter;
81
import net.sourceforge.pmd.lang.Parser;
82
import net.sourceforge.pmd.lang.ParserOptions;
83

84
// Get handler instance (typically done by PMD framework)
85
VmHandler handler = new VmHandler();
86

87
// Create parser for Velocity templates
88
ParserOptions options = new ParserOptions();
89
Parser parser = handler.getParser(options);
90

91
// Get rule violation factory
92
RuleViolationFactory factory = handler.getRuleViolationFactory();
93

94
// Create AST dump facility for debugging
95
StringWriter writer = new StringWriter();
96
VisitorStarter dumper = handler.getDumpFacade(writer, "  ", true);
97
```
98

99
### Rule Violation Factory
100

101
Singleton factory for creating standardized rule violations specific to Velocity templates.
102

103
```java { .api }
104
/**
105
 * Factory class for creating rule violations specific to Velocity templates.
106
 * Ensures consistent violation formatting and metadata.
107
 * @deprecated See RuleViolationFactory
108
 * @InternalApi This class is intended for internal PMD use
109
 */
110
@Deprecated
111
@InternalApi
112
public class VmRuleViolationFactory implements RuleViolationFactory {
113
    /** Singleton instance for creating Velocity rule violations */
114
    public static final VmRuleViolationFactory INSTANCE;
115
    
116
    // Implementation methods inherited from RuleViolationFactory
117
    // Used internally by PMD framework for violation creation
118
}
119
```
120

121
**Usage Example:**
122

123
```java
124
import net.sourceforge.pmd.RuleContext;
125
import net.sourceforge.pmd.lang.rule.RuleViolationFactory;
126

127
// Access singleton factory
128
RuleViolationFactory factory = VmRuleViolationFactory.INSTANCE;
129

130
// Factory is typically used internally by PMD during rule execution
131
// Custom rules use addViolation() method on AbstractVmRule instead
132
```
133

134
### Rule Chain Visitor
135

136
Optimized visitor implementation for efficient processing of multiple rules across Velocity template ASTs.
137

138
```java { .api }
139
/**
140
 * Specialized visitor that efficiently processes multiple rules in a single
141
 * AST traversal pass, improving performance for large templates.
142
 * @deprecated for removal with PMD 7. A language dependent rule chain visitor is not needed anymore.
143
 *      See RuleChainVisitor.
144
 */
145
@Deprecated
146
public class VmRuleChainVisitor extends AbstractRuleChainVisitor {
147
    // Implementation details are internal to PMD's rule processing pipeline
148
    // Automatically used by PMD for multi-rule analysis optimization
149
}
150
```
151

152
## Integration Examples
153

154
### Custom Language Handler Extension
155

156
```java
157
import net.sourceforge.pmd.lang.Parser;
158
import net.sourceforge.pmd.lang.ParserOptions;
159

160
public class CustomVmHandler extends VmHandler {
161
    
162
    @Override
163
    public Parser getParser(ParserOptions parserOptions) {
164
        // Customize parser behavior if needed
165
        Parser parser = super.getParser(parserOptions);
166
        // Apply custom configuration
167
        return parser;
168
    }
169
}
170
```
171

172
### PMD Configuration Integration
173

174
```xml
175
<!-- PMD ruleset configuration -->
176
<ruleset name="velocity-rules">
177
    <description>Rules for Velocity templates</description>
178
    
179
    <!-- PMD automatically detects VM language support -->
180
    <rule ref="category/vm/bestpractices.xml/AvoidReassigningParameters"/>
181
    <rule ref="category/vm/design.xml/ExcessiveTemplateLength"/>
182
</ruleset>
183
```
184

185
### Programmatic PMD Integration
186

187
```java
188
import net.sourceforge.pmd.PMD;
189
import net.sourceforge.pmd.PMDConfiguration;
190
import net.sourceforge.pmd.lang.LanguageRegistry;
191

192
// PMD automatically registers VmLanguageModule
193
PMDConfiguration config = new PMDConfiguration();
194
config.setInputPaths("src/main/resources/templates");
195

196
// Language is available via registry
197
LanguageRegistry registry = LanguageRegistry.getDefaultRegistry();
198
Language vmLanguage = registry.getLanguageByTerseName("vm");
199
```