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  *
  42  * @library /lib /
  43  * @run main/othervm jdk.jfr.event.metadata.TestEventMetadata
  44  */
  45 
  46 public class TestEventMetadata {
  47 
  48     /*
  49      * Short guide to writing event metadata
  50      * =====================================
  51 
  52      * Name
  53      * ----
  54      *
  55      * Symbolic name that is used to identify an event, or a field. Referred to
  56      * as "id" and "field" in trace.xml-files and @Name in the Java API. If it is
  57      * the name of an event, the name should be prefixed "jdk.", which
  58      * happens automatically for native events.
  59      *
  60      * The name should be short, but not so brief that collision is likely with
  61      * future events or fields. It should only consist of letters and numbers.
  62      * Use Java naming convention , i.e. "FileRead" for an event and
  63      * "allocationRate" for a field. Do not use "_" and don't add the word
  64      * "Event" to the event name.
  65      *
  66      * Abbreviations should be avoided, but may be acceptable if the name
  67      * becomes long, or if it is a well established acronym. Write whole words,
  68      * i.e. "allocation" instead of "alloc". The name should not be a reserved
  69      * Java keyword, i.e "void" or "class".
  70      *
  71      * Label
  72      * -----
  73      *
  74      * Describes a human-readable name, typically 1-3 words. Use headline-style
  75      * capitalization, capitalize the first and last words, and all nouns,
  76      * pronouns, adjectives, verbs and adverbs. Do not include ending
  77      * punctuation.
  78      *
  79      * Description
  80      * -----------
  81      *
  82      * Describes an event with a sentence or two. It's better to omit the
  83      * description then copying the label. Use sentence-style
  84      * capitalization, capitalize the first letter of the first word, and any
  85      * proper names such as the word Java. If the description is one sentence,
  86      * period should not be included.
  87      *
  88      *
  89      * Do not forget to set proper units for fields, i.e "NANOS", "MILLS",
  90      * "TICKSPAN" ,"BYETS", "PECENTAGE" etc. in native and @Timespan, @Timespan
  91      * etc. in Java.
  92      */
  93     public static void main(String[] args) throws Exception {
  94         Set<String> types = new HashSet<>();
  95         List<EventType> eventTypes = FlightRecorder.getFlightRecorder().getEventTypes();
  96         Set<String> eventNames= new HashSet<>();
  97         for (EventType eventType : eventTypes) {
  98             verifyEventType(eventType);
  99             verifyValueDesscriptors(eventType.getFields(), types);
 100             System.out.println();
 101             String eventName = eventType.getName();
 102             if (eventNames.contains(eventName)) {
 103                 throw new Exception("Event with name " +eventName+ " already exists");
 104             }
 105             eventNames.add(eventName);
 106             Set<String> fieldNames = new HashSet<>();
 107             for (ValueDescriptor v : eventType.getFields()) {
 108                 String fieldName = v.getName();
 109                 if (fieldNames.contains(fieldName)) {
 110                     throw new Exception("Field with name " + fieldName +" is already in use in event name " +eventName);
 111                 }
 112                 fieldNames.add(fieldName);
 113             }
 114         }
 115     }
 116 
 117     private static void verifyValueDesscriptors(List<ValueDescriptor> fields, Set<String> visitedTypes) {
 118         for (ValueDescriptor v : fields) {
 119             if (!visitedTypes.contains(v.getTypeName())) {
 120                 visitedTypes.add(v.getTypeName());
 121                 verifyValueDesscriptors(v.getFields(), visitedTypes);
 122             }
 123             verifyValueDescriptor(v);
 124         }
 125     }
 126 
 127     private static void verifyValueDescriptor(ValueDescriptor v) {
 128         verifyName(v.getName());
 129         verifyLabel(v.getLabel());
 130         verifyDescription(v.getDescription());
 131     }
 132 
 133     private static void verifyDescription(String description) {
 134         if (description == null) {
 135             return;
 136         }
 137         Asserts.assertTrue(description.length() > 10, "Description must be at least ten characters");
 138         Asserts.assertTrue(description.length() < 300, "Description should not exceed 300 characters. Found " + description);
 139         Asserts.assertTrue(description.length() == description.trim().length(), "Description should not have trim character at start or end");
 140         Asserts.assertFalse(description.endsWith(".") && description.indexOf(".") == description.length() - 1, "Single sentence descriptions should not use end punctuation");
 141     }
 142 
 143     private static void verifyName(String name) {
 144         System.out.println("Verifying name: " + name);
 145         Asserts.assertNotEquals(name, null, "Name not allowed to be null");
 146         Asserts.assertTrue(name.length() > 1, "Name must be at least two characters");
 147         Asserts.assertTrue(name.length() < 32, "Name should not exceed 32 characters");
 148         Asserts.assertFalse(isReservedKeyword(name),"Name must not be reserved keyword in the Java language (" + name + ")");
 149         char firstChar = name.charAt(0);
 150         Asserts.assertTrue(Character.isAlphabetic(firstChar), "Name must start with a character");
 151         Asserts.assertTrue(Character.isLowerCase(firstChar), "Name must start with lower case letter");
 152         Asserts.assertTrue(Character.isJavaIdentifierStart(firstChar), "Not valid first character for Java identifier");
 153         for (int i = 1; i < name.length(); i++) {
 154             Asserts.assertTrue(Character.isJavaIdentifierPart(name.charAt(i)), "Not valid character for a Java identifier");
 155             Asserts.assertTrue(Character.isAlphabetic(name.charAt(i)), "Name must consists of characters, found '" + name.charAt(i) + "'");
 156         }
 157         Asserts.assertFalse(name.contains("ID"), "'ID' should not be used in name, consider using 'Id'");
 158         checkCommonAbbreviations(name);
 159     }
 160 
 161     private static void verifyLabel(String label) {
 162         Asserts.assertNotEquals(label, null, "Label not allowed to be null");
 163         Asserts.assertTrue(label.length() > 1, "Name must be at least two characters");
 164         Asserts.assertTrue(label.length() < 45, "Label should not exceed 45 characters, use description to explain " + label);
 165         Asserts.assertTrue(label.length() == label.trim().length(), "Label should not have trim character at start and end");
 166         Asserts.assertTrue(Character.isUpperCase(label.charAt(0)), "Label should start with upper case letter");
 167         for (int i = 0; i < label.length(); i++) {
 168             char c = label.charAt(i);
 169             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)
 170                     + "'");
 171         }
 172     }
 173 
 174     private static void verifyEventType(EventType eventType) {
 175         System.out.println("Verifying event: " + eventType.getName());
 176         verifyDescription(eventType.getDescription());
 177         verifyLabel(eventType.getLabel());
 178         Asserts.assertNotEquals(eventType.getName(), null, "Name not allowed to be null");
 179         Asserts.assertTrue(eventType.getName().startsWith(EventNames.PREFIX), "OpenJDK events must start with " + EventNames.PREFIX);
 180         String name = eventType.getName().substring(EventNames.PREFIX.length());
 181         Asserts.assertFalse(isReservedKeyword(name),"Name must not be reserved keyword in the Java language (" + name + ")");
 182         checkCommonAbbreviations(name);
 183           char firstChar = name.charAt(0);
 184         Asserts.assertFalse(name.contains("ID"), "'ID' should not be used in name, consider using 'Id'");
 185         Asserts.assertTrue(Character.isAlphabetic(firstChar), "Name " + name + " must start with a character");
 186         Asserts.assertTrue(Character.isUpperCase(firstChar), "Name " + name + " must start with upper case letter");
 187         for (int i = 0; i < name.length(); i++) {
 188             char c = name.charAt(i);
 189             Asserts.assertTrue(Character.isAlphabetic(c) || Character.isDigit(c), "Name " + name + " must consists of characters or numbers, found '" + name.charAt(i) + "'");
 190         }
 191     }
 192 
 193     static boolean isReservedKeyword(String s) {
 194         String[] keywords = new String[] {
 195                 // "module", "requires", "exports", "to", "uses", "provides", "with", module-info.java
 196                 "abstract", "assert", "boolean", "break", "byte", "case", "catch", "char", "class", "const", "continue", "default", "do", "double", "else", "enum",
 197                 "extends", "false", "final", "finally", "float", "for", "goto", "if", "implements", "import", "instanceof", "int", "interface", "long", "native", "new", "null", "package", "private",
 198                 "protected", "public", "return", "short", "static", "strictfp", "super", "switch", "synchronized", "this", "throw", "throws", "transient", "true", "try", "void", "volatile", "while" };
 199         for (int i = 0; i < keywords.length; i++) {
 200             if (s.equals(keywords[i])) {
 201                 return true;
 202             }
 203         }
 204         return false;
 205     }
 206 
 207     private static void checkCommonAbbreviations(String name) {
 208         String lowerCased = name.toLowerCase();
 209         Asserts.assertFalse(lowerCased.contains("info") && !lowerCased.contains("information"), "Use 'information' instead 'info' in name");
 210         Asserts.assertFalse(lowerCased.contains("alloc") && !lowerCased.contains("alloca"), "Use 'allocation' instead 'alloc' in name");
 211         Asserts.assertFalse(lowerCased.contains("config") && !lowerCased.contains("configuration"), "Use 'configuration' instead of 'config' in name");
 212         Asserts.assertFalse(lowerCased.contains("evac") && !lowerCased.contains("evacu"), "Use 'evacuation' instead of 'evac' in name");
 213         Asserts.assertFalse(lowerCased.contains("stat") && !(lowerCased.contains("state") ||lowerCased.contains("statistic")) , "Use 'statistics' instead of 'stat' in name");
 214         Asserts.assertFalse(name.contains("ID") , "Use 'id' or 'Id' instead of 'ID' in name");
 215     }
 216 }