1 /*
2 * Copyright (c) 2013, 2018, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package jdk.jfr.event.metadata;
27
28 import java.util.HashSet;
29 import java.util.List;
30 import java.util.Set;
31
32 import jdk.jfr.EventType;
33 import jdk.jfr.FlightRecorder;
34 import jdk.jfr.ValueDescriptor;
35 import jdk.test.lib.Asserts;
36 import jdk.test.lib.jfr.EventNames;
37
38 /*
39 * @test
40 * @key jfr
41 * @library /test/lib
42 * @run main/othervm jdk.jfr.event.metadata.TestEventMetadata
43 */
44
45 public class TestEventMetadata {
46
47 /*
48 * Short guide to writing event metadata
49 * =====================================
50
51 * Name
52 * ----
53 *
54 * Symbolic name that is used to identify an event, or a field. Referred to
55 * as "id" and "field" in trace.xml-files and @Name in the Java API. If it is
56 * the name of an event, the name should be prefixed "jdk.", which
57 * happens automatically for native events.
58 *
59 * The name should be short, but not so brief that collision is likely with
60 * future events or fields. It should only consist of letters and numbers.
61 * Use Java naming convention , i.e. "FileRead" for an event and
62 * "allocationRate" for a field. Do not use "_" and don't add the word
63 * "Event" to the event name.
64 *
65 * Abbreviations should be avoided, but may be acceptable if the name
66 * becomes long, or if it is a well established acronym. Write whole words,
67 * i.e. "allocation" instead of "alloc". The name should not be a reserved
68 * Java keyword, i.e "void" or "class".
69 *
70 * Label
71 * -----
72 *
73 * Describes a human-readable name, typically 1-3 words. Use headline-style
74 * capitalization, capitalize the first and last words, and all nouns,
75 * pronouns, adjectives, verbs and adverbs. Do not include ending
76 * punctuation.
77 *
78 * Description
79 * -----------
80 *
81 * Describes an event with a sentence or two. It's better to omit the
82 * description then copying the label. Use sentence-style
83 * capitalization, capitalize the first letter of the first word, and any
84 * proper names such as the word Java. If the description is one sentence,
85 * period should not be included.
86 *
87 *
88 * Do not forget to set proper units for fields, i.e "NANOS", "MILLS",
89 * "TICKSPAN" ,"BYETS", "PECENTAGE" etc. in native and @Timespan, @Timespan
90 * etc. in Java.
91 */
92 public static void main(String[] args) throws Exception {
93 Set<String> types = new HashSet<>();
94 List<EventType> eventTypes = FlightRecorder.getFlightRecorder().getEventTypes();
95 Set<String> eventNames= new HashSet<>();
96 for (EventType eventType : eventTypes) {
97 verifyEventType(eventType);
98 verifyValueDesscriptors(eventType.getFields(), types);
99 System.out.println();
100 String eventName = eventType.getName();
101 if (eventNames.contains(eventName)) {
102 throw new Exception("Event with name " +eventName+ " already exists");
103 }
104 eventNames.add(eventName);
105 Set<String> fieldNames = new HashSet<>();
106 for (ValueDescriptor v : eventType.getFields()) {
107 String fieldName = v.getName();
108 if (fieldNames.contains(fieldName)) {
109 throw new Exception("Field with name " + fieldName +" is already in use in event name " +eventName);
110 }
111 fieldNames.add(fieldName);
112 }
113 }
114 }
115
116 private static void verifyValueDesscriptors(List<ValueDescriptor> fields, Set<String> visitedTypes) {
117 for (ValueDescriptor v : fields) {
118 if (!visitedTypes.contains(v.getTypeName())) {
119 visitedTypes.add(v.getTypeName());
120 verifyValueDesscriptors(v.getFields(), visitedTypes);
121 }
122 verifyValueDescriptor(v);
123 }
124 }
125
126 private static void verifyValueDescriptor(ValueDescriptor v) {
127 verifyName(v.getName());
128 verifyLabel(v.getLabel());
129 verifyDescription(v.getDescription());
130 }
131
132 private static void verifyDescription(String description) {
133 if (description == null) {
134 return;
135 }
136 Asserts.assertTrue(description.length() > 10, "Description must be at least ten characters");
137 Asserts.assertTrue(description.length() < 300, "Description should not exceed 300 characters. Found " + description);
138 Asserts.assertTrue(description.length() == description.trim().length(), "Description should not have trim character at start or end");
139 Asserts.assertFalse(description.endsWith(".") && description.indexOf(".") == description.length() - 1, "Single sentence descriptions should not use end punctuation");
140 }
141
142 private static void verifyName(String name) {
143 System.out.println("Verifying name: " + name);
144 Asserts.assertNotEquals(name, null, "Name not allowed to be null");
145 Asserts.assertTrue(name.length() > 1, "Name must be at least two characters");
146 Asserts.assertTrue(name.length() < 32, "Name should not exceed 32 characters");
147 Asserts.assertFalse(isReservedKeyword(name),"Name must not be reserved keyword in the Java language (" + name + ")");
148 char firstChar = name.charAt(0);
149 Asserts.assertTrue(Character.isAlphabetic(firstChar), "Name must start with a character");
150 Asserts.assertTrue(Character.isLowerCase(firstChar), "Name must start with lower case letter");
151 Asserts.assertTrue(Character.isJavaIdentifierStart(firstChar), "Not valid first character for Java identifier");
152 for (int i = 1; i < name.length(); i++) {
153 Asserts.assertTrue(Character.isJavaIdentifierPart(name.charAt(i)), "Not valid character for a Java identifier");
154 Asserts.assertTrue(Character.isAlphabetic(name.charAt(i)), "Name must consists of characters, found '" + name.charAt(i) + "'");
155 }
156 Asserts.assertFalse(name.contains("ID"), "'ID' should not be used in name, consider using 'Id'");
157 checkCommonAbbreviations(name);
158 }
159
160 private static void verifyLabel(String label) {
161 Asserts.assertNotEquals(label, null, "Label not allowed to be null");
162 Asserts.assertTrue(label.length() > 1, "Name must be at least two characters");
163 Asserts.assertTrue(label.length() < 45, "Label should not exceed 45 characters, use description to explain " + label);
164 Asserts.assertTrue(label.length() == label.trim().length(), "Label should not have trim character at start and end");
165 Asserts.assertTrue(Character.isUpperCase(label.charAt(0)), "Label should start with upper case letter");
166 for (int i = 0; i < label.length(); i++) {
167 char c = label.charAt(i);
168 Asserts.assertTrue(Character.isDigit(c) || Character.isAlphabetic(label.charAt(i)) || c == ' ' || c == '(' || c == ')' || c == '-', "Label should only consist of letters or space, found '" + label.charAt(i)
169 + "'");
170 }
171 }
172
173 private static void verifyEventType(EventType eventType) {
174 System.out.println("Verifying event: " + eventType.getName());
175 verifyDescription(eventType.getDescription());
176 verifyLabel(eventType.getLabel());
177 Asserts.assertNotEquals(eventType.getName(), null, "Name not allowed to be null");
178 Asserts.assertTrue(eventType.getName().startsWith(EventNames.PREFIX), "OpenJDK events must start with " + EventNames.PREFIX);
179 String name = eventType.getName().substring(EventNames.PREFIX.length());
180 Asserts.assertFalse(isReservedKeyword(name),"Name must not be reserved keyword in the Java language (" + name + ")");
181 checkCommonAbbreviations(name);
182 char firstChar = name.charAt(0);
183 Asserts.assertFalse(name.contains("ID"), "'ID' should not be used in name, consider using 'Id'");
184 Asserts.assertTrue(Character.isAlphabetic(firstChar), "Name " + name + " must start with a character");
185 Asserts.assertTrue(Character.isUpperCase(firstChar), "Name " + name + " must start with upper case letter");
186 for (int i = 0; i < name.length(); i++) {
187 char c = name.charAt(i);
188 Asserts.assertTrue(Character.isAlphabetic(c) || Character.isDigit(c), "Name " + name + " must consists of characters or numbers, found '" + name.charAt(i) + "'");
189 }
190 }
191
192 static boolean isReservedKeyword(String s) {
193 String[] keywords = new String[] {
194 // "module", "requires", "exports", "to", "uses", "provides", "with", module-info.java
195 "abstract", "assert", "boolean", "break", "byte", "case", "catch", "char", "class", "const", "continue", "default", "do", "double", "else", "enum",
196 "extends", "false", "final", "finally", "float", "for", "goto", "if", "implements", "import", "instanceof", "int", "interface", "long", "native", "new", "null", "package", "private",
197 "protected", "public", "return", "short", "static", "strictfp", "super", "switch", "synchronized", "this", "throw", "throws", "transient", "true", "try", "void", "volatile", "while" };
198 for (int i = 0; i < keywords.length; i++) {
199 if (s.equals(keywords[i])) {
200 return true;
201 }
202 }
203 return false;
204 }
205
206 private static void checkCommonAbbreviations(String name) {
207 String lowerCased = name.toLowerCase();
208 Asserts.assertFalse(lowerCased.contains("info") && !lowerCased.contains("information"), "Use 'information' instead 'info' in name");
209 Asserts.assertFalse(lowerCased.contains("alloc") && !lowerCased.contains("alloca"), "Use 'allocation' instead 'alloc' in name");
210 Asserts.assertFalse(lowerCased.contains("config") && !lowerCased.contains("configuration"), "Use 'configuration' instead of 'config' in name");
211 Asserts.assertFalse(lowerCased.contains("evac") && !lowerCased.contains("evacu"), "Use 'evacuation' instead of 'evac' in name");
212 Asserts.assertFalse(lowerCased.contains("stat") && !(lowerCased.contains("state") ||lowerCased.contains("statistic")) , "Use 'statistics' instead of 'stat' in name");
213 Asserts.assertFalse(name.contains("ID") , "Use 'id' or 'Id' instead of 'ID' in name");
214 }
215 }