pmd / pmd / 380

Committed 29 Jan 2026 03:55PM UTC coverage: 78.964%. Remained the same

Build # 380

Build Type

push

github

Committed by

adangel

Commit Message

[doc] ADR 3: Clarify javadoc tags (#6392)

Run Details

18537 of 24358 branches covered (76.1%)

Branch coverage included in aggregate %.

40391 of 50268 relevant lines covered (80.35%)

0.81 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

37.5

/pmd-core/src/main/java/net/sourceforge/pmd/lang/Language.java

/*
 * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
 */

package net.sourceforge.pmd.lang;

import java.util.List;
import java.util.ServiceLoader;
import java.util.Set;

import org.checkerframework.checker.nullness.qual.NonNull;
import org.checkerframework.checker.nullness.qual.Nullable;

import net.sourceforge.pmd.annotation.Experimental;
import net.sourceforge.pmd.cpd.CpdCapableLanguage;
import net.sourceforge.pmd.util.AssertionUtil;

/**
 * Represents a language module, and provides access to language-specific
 * functionality. You can get a language instance from a {@link LanguageRegistry},
 * see {@link LanguageRegistry#PMD} for instance.
 *
 * <p>Language instances are extensions to the core of PMD. They can be
 * registered with a {@linkplain ServiceLoader service file} so that
 * PMD automatically finds them on the classpath.
 *
 * <p>Instances of this interface are stateless and immutable after construction.
 * They mostly provide metadata about the language, like ID, name and different
 * versions that are supported.
 *
 * <p>Languages should implement the interfaces {@link PmdCapableLanguage}
 * or {@link CpdCapableLanguage} to be usable by PMD or CPD, respectively.
 *
 * @see LanguageVersion
 */
public interface Language extends Comparable<Language> {


    /**
     * Returns the full name of this Language. This is generally the name of this
     * language without the use of acronyms, but possibly some capital letters,
     * eg {@code "Java"}. It's suitable for displaying in a GUI.
     *
     * @return The full name of this language.
     */
    String getName();

    /**
     * Returns the short name of this language. This is the commonly
     * used short form of this language's name, perhaps an acronym,
     * but possibly with special characters.
     *
     * @return The short name of this language.
     */
    String getShortName();

    /**
     * Returns the ID of this language. This is a short, alphanumeric,
     * lowercase name, eg {@code "java"}. It's used to identify the language
     * in the ruleset XML, and is also in the package name of the language
     * module.
     *
     * @return The ID of this language.
     */
    String getId();

    /**
     * If this is a dialect of another language, returns the base language.
     * Dialects are for example different flavors of XML. Dialects must share
     * the same AST as their base language. This makes it so that rules written
     * for the base language can be applied files of all dialects uniformly.
     * @since 7.13.0
     * @experimental See <a href="https://github.com/pmd/pmd/pull/5438">[core] Support language dialects #5438</a>.
     */
    @Experimental
    default @Nullable String getBaseLanguageId() {
        return null;
    }

    /**
     * Return true if this language is a dialect of the given language.
     *
     * @param language A language (not null)
     * @since 7.13.0
     * @experimental See <a href="https://github.com/pmd/pmd/pull/5438">[core] Support language dialects #5438</a>.
     */
    @Experimental
    @SuppressWarnings("PMD.SimplifyBooleanReturns")
    default boolean isDialectOf(Language language) {
        AssertionUtil.requireParamNotNull("language", language);
        String base = getBaseLanguageId();
        if (base == null) {
            return false;
        }
        return base.equals(language.getId());
    }

    /**
     * Returns the list of file extensions associated with this language.
     * This list is unmodifiable. Extensions do not have a '.' prefix.
     *
     * @return A list of file extensions.
     */
    List<String> getExtensions();

    /**
     * Returns whether this language handles the given file extension.
     * The comparison is done ignoring case.
     *
     * @param extensionWithoutDot A file extension (without '.' prefix)
     *
     * @return <code>true</code> if this language handles the extension,
     *     <code>false</code> otherwise.
     */
    default boolean hasExtension(String extensionWithoutDot) {
        return getExtensions().contains(extensionWithoutDot);
    }

    /**
     * Returns an ordered list of supported versions for this language.
     *
     * @return All supported language versions.
     */
    List<LanguageVersion> getVersions();

    /**
     * Returns the latest language version. May not be the
     * {@linkplain #getDefaultVersion() default}.
     *
     * @return The latest language version
     */
    default LanguageVersion getLatestVersion() {
        List<LanguageVersion> versions = getVersions();
        return versions.get(versions.size() - 1);
    }

    /**
     * Returns a complete set of supported version names for this language
     * including all aliases.
     *
     * @return All supported language version names and aliases.
     */
    Set<String> getVersionNamesAndAliases();

    /**
     * Returns true if a language version with the given {@linkplain LanguageVersion#getVersion() version string}
     * is registered. Then, {@link #getVersion(String) getVersion} will return a non-null value.
     *
     * @param version A version string
     *
     * @return True if the version string is known
     */
    default boolean hasVersion(String version) {
        return getVersion(version) != null;
    }

    /**
     * Returns the language version with the given {@linkplain LanguageVersion#getVersion() version string}.
     * Returns null if no such version exists.
     *
     * @param version A language version string.
     *
     * @return The corresponding LanguageVersion, {@code null} if the
     *     version string is not recognized.
     */
    default @Nullable LanguageVersion getVersion(String version) {
        for (LanguageVersion v : getVersions()) {
            if (v.getVersion().equals(version)) {
                return v;
            }
        }
        return null;
    }

    /**
     * Returns the default language version for this language.
     * This is an arbitrary choice made by the PMD product, and can change
     * between PMD releases. Every language has a default version.
     *
     * @return The current default language version for this language.
     */
    @NonNull LanguageVersion getDefaultVersion();


    /**
     * Creates a new bundle of properties that will serve to configure
     * the {@link LanguageProcessor} for this language. The returned
     * bundle must have all supported properties already declared. See
     * {@link PmdCapableLanguage} and {@link CpdCapableLanguage} for sites
     * where properties are passed back to the language with user-provided
     * values.
     *
     * @return A new set of properties
     */
    default LanguagePropertyBundle newPropertyBundle() {
        return new LanguagePropertyBundle(this);
    }


    /**
     * Returns a set of the IDs of languages that this language instance
     * depends on. Whenever this language is loaded into a {@link LanguageProcessorRegistry},
     * those dependencies need to be loaded as well.
     */
    Set<String> getDependencies();

}

1	/*
2	* BSD-style license; for more info see http://pmd.sourceforge.net/license.html
3	*/
4
5	package net.sourceforge.pmd.lang;
6
7	import java.util.List;
8	import java.util.ServiceLoader;
9	import java.util.Set;
10
11	import org.checkerframework.checker.nullness.qual.NonNull;
12	import org.checkerframework.checker.nullness.qual.Nullable;
13
14	import net.sourceforge.pmd.annotation.Experimental;
15	import net.sourceforge.pmd.cpd.CpdCapableLanguage;
16	import net.sourceforge.pmd.util.AssertionUtil;
17
18	/**
19	* Represents a language module, and provides access to language-specific
20	* functionality. You can get a language instance from a {@link LanguageRegistry},
21	* see {@link LanguageRegistry#PMD} for instance.
22	*
23	* <p>Language instances are extensions to the core of PMD. They can be
24	* registered with a {@linkplain ServiceLoader service file} so that
25	* PMD automatically finds them on the classpath.
26	*
27	* <p>Instances of this interface are stateless and immutable after construction.
28	* They mostly provide metadata about the language, like ID, name and different
29	* versions that are supported.
30	*
31	* <p>Languages should implement the interfaces {@link PmdCapableLanguage}
32	* or {@link CpdCapableLanguage} to be usable by PMD or CPD, respectively.
33	*
34	* @see LanguageVersion
35	*/
36	public interface Language extends Comparable<Language> {
37
38
39	/**
40	* Returns the full name of this Language. This is generally the name of this
41	* language without the use of acronyms, but possibly some capital letters,
42	* eg {@code "Java"}. It's suitable for displaying in a GUI.
43	*
44	* @return The full name of this language.
45	*/
46	String getName();
47
48	/**
49	* Returns the short name of this language. This is the commonly
50	* used short form of this language's name, perhaps an acronym,
51	* but possibly with special characters.
52	*
53	* @return The short name of this language.
54	*/
55	String getShortName();
56
57	/**
58	* Returns the ID of this language. This is a short, alphanumeric,
59	* lowercase name, eg {@code "java"}. It's used to identify the language
60	* in the ruleset XML, and is also in the package name of the language
61	* module.
62	*
63	* @return The ID of this language.
64	*/
65	String getId();
66
67	/**
68	* If this is a dialect of another language, returns the base language.
69	* Dialects are for example different flavors of XML. Dialects must share
70	* the same AST as their base language. This makes it so that rules written
71	* for the base language can be applied files of all dialects uniformly.
72	* @since 7.13.0
73	* @experimental See <a href="https://github.com/pmd/pmd/pull/5438">[core] Support language dialects #5438</a>.
74	*/
75	@Experimental
76	default @Nullable String getBaseLanguageId() {
77	return null;	×
78	}
79
80	/**
81	* Return true if this language is a dialect of the given language.
82	*
83	* @param language A language (not null)
84	* @since 7.13.0
85	* @experimental See <a href="https://github.com/pmd/pmd/pull/5438">[core] Support language dialects #5438</a>.
86	*/
87	@Experimental
88	@SuppressWarnings("PMD.SimplifyBooleanReturns")
89	default boolean isDialectOf(Language language) {
90	AssertionUtil.requireParamNotNull("language", language);	1✔
91	String base = getBaseLanguageId();	1✔
92	if (base == null) {	1✔
93	return false;	1✔
94	}
95	return base.equals(language.getId());	1✔
96	}
97
98	/**
99	* Returns the list of file extensions associated with this language.
100	* This list is unmodifiable. Extensions do not have a '.' prefix.
101	*
102	* @return A list of file extensions.
103	*/
104	List<String> getExtensions();
105
106	/**
107	* Returns whether this language handles the given file extension.
108	* The comparison is done ignoring case.
109	*
110	* @param extensionWithoutDot A file extension (without '.' prefix)
111	*
112	* @return <code>true</code> if this language handles the extension,
113	* <code>false</code> otherwise.
114	*/
115	default boolean hasExtension(String extensionWithoutDot) {
116	return getExtensions().contains(extensionWithoutDot);	1✔
117	}
118
119	/**
120	* Returns an ordered list of supported versions for this language.
121	*
122	* @return All supported language versions.
123	*/
124	List<LanguageVersion> getVersions();
125
126	/**
127	* Returns the latest language version. May not be the
128	* {@linkplain #getDefaultVersion() default}.
129	*
130	* @return The latest language version
131	*/
132	default LanguageVersion getLatestVersion() {
133	List<LanguageVersion> versions = getVersions();	×
134	return versions.get(versions.size() - 1);	×
135	}
136
137	/**
138	* Returns a complete set of supported version names for this language
139	* including all aliases.
140	*
141	* @return All supported language version names and aliases.
142	*/
143	Set<String> getVersionNamesAndAliases();
144
145	/**
146	* Returns true if a language version with the given {@linkplain LanguageVersion#getVersion() version string}
147	* is registered. Then, {@link #getVersion(String) getVersion} will return a non-null value.
148	*
149	* @param version A version string
150	*
151	* @return True if the version string is known
152	*/
153	default boolean hasVersion(String version) {
154	return getVersion(version) != null;	×
155	}
156
157	/**
158	* Returns the language version with the given {@linkplain LanguageVersion#getVersion() version string}.
159	* Returns null if no such version exists.
160	*
161	* @param version A language version string.
162	*
163	* @return The corresponding LanguageVersion, {@code null} if the
164	* version string is not recognized.
165	*/
166	default @Nullable LanguageVersion getVersion(String version) {
167	for (LanguageVersion v : getVersions()) {	×
168	if (v.getVersion().equals(version)) {	×
169	return v;	×
170	}
171	}	×
172	return null;	×
173	}
174
175	/**
176	* Returns the default language version for this language.
177	* This is an arbitrary choice made by the PMD product, and can change
178	* between PMD releases. Every language has a default version.
179	*
180	* @return The current default language version for this language.
181	*/
182	@NonNull LanguageVersion getDefaultVersion();
183
184
185	/**
186	* Creates a new bundle of properties that will serve to configure
187	* the {@link LanguageProcessor} for this language. The returned
188	* bundle must have all supported properties already declared. See
189	* {@link PmdCapableLanguage} and {@link CpdCapableLanguage} for sites
190	* where properties are passed back to the language with user-provided
191	* values.
192	*
193	* @return A new set of properties
194	*/
195	default LanguagePropertyBundle newPropertyBundle() {
196	return new LanguagePropertyBundle(this);	1✔
197	}
198
199
200	/**
201	* Returns a set of the IDs of languages that this language instance
202	* depends on. Whenever this language is loaded into a {@link LanguageProcessorRegistry},
203	* those dependencies need to be loaded as well.
204	*/
205	Set<String> getDependencies();
206
207	}

pmd / pmd / 380

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous