/*
 * Copyright (c) 2025, 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.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Event field annotation, specifies that the value carries contextual
 * information.
 * <p>
 * Contextual information is data that applies to all events happening in the
 * same thread from the beginning to the end of the event with a field annotated
 * with {@code Contextual}.
 * <p>
 * For example, to trace requests or transactions in a system, a trace event can
 * be created to provide context.
 * {@snippet class = "Snippets" region = "ContextualTrace"}
 * <p>
 * To track details within an order service, an order event can be created where
 * only the order ID provides context.
 * {@snippet class = "Snippets" region = "ContextualOrder"}
 * <p>
 * If an order in the order service stalls due to lock contention, a user
 * interface can display contextual information together with the
 * JavaMonitorEnter event to simplify troubleshooting, for example:
 * {@snippet lang=text :
 *   $ jfr print --events JavaMonitorEnter recording.jfr
 *   jdk.JavaMonitorEnter {
 *     Context: Trace.id = "00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01"
 *     Context: Trace.name = "POST /checkout/place-order"
 *     Context: Order.id = 314159
 *     startTime = 17:51:29.038 (2025-02-07)
 *     duration = 50.56 ms
 *     monitorClass = java.util.ArrayDeque (classLoader = bootstrap)
 *    previousOwner = "Order Thread" (javaThreadId = 56209, virtual = true)
 *    address = 0x60000232ECB0
 *    eventThread = "Order Thread" (javaThreadId = 52613, virtual = true)
 *    stackTrace = [
 *      java.util.zip.ZipFile$CleanableResource.getInflater() line: 685
 *      java.util.zip.ZipFile$ZipFileInflaterInputStream.<init>(ZipFile) line: 388
 *      java.util.zip.ZipFile.getInputStream(ZipEntry) line: 355
 *      java.util.jar.JarFile.getInputStream(ZipEntry) line: 833
 *      ...
 *    ]
 *   }
 * }
 * <p>
 * The difference between {@link Relational} and {@link Contextual} annotations
 * is that {@link Relational} ties event data together to form a global data
 * structure, similar to a foreign key in a relational database, but
 * {@link Contextual} represents a state that applies to all events that happen
 * at the same time, in the same thread. A field can be both contextual and
 * relational at the same time.
 * <p>
 * A contextual field may incur overhead on a parser reading a recording file,
 * since it must track active context, so it should be used sparingly and only
 * where appropriate.
 *
 * @since 25
 */
@MetadataDefinition
@Label("Context")
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD})
public @interface Contextual {
}