https://openjdk.java.net/ 
/*
 * Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package jdk.jfr;

import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;


Event annotation, to associate the event type with a category, in the format
of a human-readable path.


The category determines how an event is presented to the user. Events that
are in the same category are typically displayed together in graphs and
trees. To avoid the overlap of durational events in graphical
representations, overlapping events must be in separate categories.


For example, to monitor image uploads to a web server with a separate thread
for each upload, an event called File Upload starts when the user uploads a
file and ends when the upload is complete. For advanced diagnostics about
image uploads, more detailed events are created (for example, Image Read,
Image Resize, and Image Write). During these detailed events. other low
level-events could occur (for example, Socket Read and File Write).


The following example shows a visualization that avoids overlaps:

-------------------------------------------------------------------
  |                         File Upload                        |
------------------------------------------------------------------
  |       Image Read          | Image Resize |   Image Write   |
------------------------------------------------------------------
  | Socket Read | Socket Read |              |    File Write   |
-------------------------------------------------------------------


The example can be achieved by using the following categories:


Recording options and their purpose. 


Event Name
Annotation


 


File Upload
@Category("Upload")




Image Read
@Category({"Upload", "Image Upload"})




Image Resize
@Category({"Upload", "Image Upload"})




Image Write
@Category({"Upload", "Image Upload"})




Socket Read
@Category("Java Application")




File Write
@Category("Java Application")







The File Upload, Image Read, and Socket Read events happen concurrently (in
the same thread), but the events are in different categories so they do not
overlap in the visualization.


The following examples shows how the category is used to determine how events
are visualized in a tree:

 |- Java Application
 |  |- Socket Read
 |  |- File Write
 |- Upload
    |- File Upload
    |- Image Upload
       |- Image Read
       |- Image Resize
       |- File Write



Since:9
/**
 * Event annotation, to associate the event type with a category, in the format
 * of a human-readable path.
 * <p>
 * The category determines how an event is presented to the user. Events that
 * are in the same category are typically displayed together in graphs and
 * trees. To avoid the overlap of durational events in graphical
 * representations, overlapping events must be in separate categories.
 * <p>
 * For example, to monitor image uploads to a web server with a separate thread
 * for each upload, an event called File Upload starts when the user uploads a
 * file and ends when the upload is complete. For advanced diagnostics about
 * image uploads, more detailed events are created (for example, Image Read,
 * Image Resize, and Image Write). During these detailed events. other low
 * level-events could occur (for example, Socket Read and File Write).
 * <p>
 * The following example shows a visualization that avoids overlaps:
 *
 * <pre>
 * -------------------------------------------------------------------
 *   |                         File Upload                        |
 * ------------------------------------------------------------------
 *   |       Image Read          | Image Resize |   Image Write   |
 * ------------------------------------------------------------------
 *   | Socket Read | Socket Read |              |    File Write   |
 * -------------------------------------------------------------------
 * </pre>
 *
 * The example can be achieved by using the following categories:
 *
 * <table class="striped">
 * <caption>Recording options and their purpose.</caption> <thead>
 * <tr>
 * <th scope="col">Event Name</th>
 * <th scope="col">Annotation</th>
 * </tr>
 * </thead> <tbody>
 * <tr>
 * <th scope="row">File Upload</th>
 * <td><code>@Category("Upload")</code></td>
 * </tr>
 * <tr>
 * <th scope="row">Image Read</th>
 * <td><code>@Category({"Upload", "Image Upload"})</code></td>
 * </tr>
 * <tr>
 * <th scope="row">Image Resize</th>
 * <td><code>@Category({"Upload", "Image Upload"})</code></td>
 * </tr>
 * <tr>
 * <th scope="row">Image Write</th>
 * <td><code>@Category({"Upload", "Image Upload"})</code></td>
 * </tr>
 * <tr>
 * <th scope="row">Socket Read</th>
 * <td><code>@Category("Java Application")</code></td>
 * </tr>
 * <tr>
 * <th scope="row">File Write</th>
 * <td><code>@Category("Java Application")</code></td>
 * </tr>
 * </tbody>
 * </table>
 * <p>
 * The File Upload, Image Read, and Socket Read events happen concurrently (in
 * the same thread), but the events are in different categories so they do not
 * overlap in the visualization.
 * <p>
 * The following examples shows how the category is used to determine how events
 * are visualized in a tree:
 *
 * <pre>
 *  |- Java Application
 *  |  |- Socket Read
 *  |  |- File Write
 *  |- Upload
 *     |- File Upload
 *     |- Image Upload
 *        |- Image Read
 *        |- Image Resize
 *        |- File Write
 * </pre>
 *
 * @since 9
 */
@MetadataDefinition
@Target({ ElementType.TYPE })
@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface Category {
    
Returns the category names for this annotation, starting with the root.

Returns:the category names
/**
     * Returns the category names for this annotation, starting with the root.
     *
     * @return the category names
     */
    String[] value();
}