feat(jdk8): move files to new folder to avoid resources compiled.

jdkSrc/jdk8/com/sun/tracing/Probe.java

@@ -0,0 +1,71 @@
+/*
+ * Copyright (c) 2008, 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 com.sun.tracing;
+
+/**
+ * The {@code Probe} interface represents a tracepoint.
+ *
+ * A {@code Probe} instance is obtained by calling the
+ * {@code Provider.getProbe()} method of a provider instance created by
+ * {@code ProviderFactory.createProvider()}.  A {@code Probe} can be used to
+ * trigger a probe manually (provided the correct arguments are passed to
+ * it), or to check a probe to see if anything is currently tracing it.
+ * <p>
+ * A tracing check can be used to avoid lengthy work that might be
+ * needed to set up the probe's arguments.  However, checking
+ * whether the probe is enabled generally takes the same amount of time
+ * as actually triggering the probe. So, you should only check a probe's status
+ * without triggering it if setting up the arguments is very expensive.
+ * <p>
+ * Users do not need to implement this interface: instances are
+ * created automatically by the system when a {@code Provider)} instance is
+ * created.
+ * <p>
+ * @since 1.7
+ */
+
+public interface Probe {
+    /**
+     * Checks whether there is an active trace of this probe.
+     *
+     * @return true if an active trace is detected.
+     */
+    boolean isEnabled();
+
+    /**
+     * Determines whether a tracepoint is enabled.
+     *
+     * Typically, users do not need to use this method. It is called
+     * automatically when a Provider's instance method is called. Calls to
+     * this method expect the arguments to match the declared parameters for
+     * the method associated with the probe.
+     *
+     * @param args the parameters to pass to the method.
+     * @throws IllegalArgumentException if the provided parameters do not
+     * match the method declaration for this probe.
+     */
+    void trigger(Object ... args);
+}

jdkSrc/jdk8/com/sun/tracing/ProbeName.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2008, 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 com.sun.tracing;
+
+import java.lang.annotation.Target;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.ElementType;
+
+/**
+ * An annotation used to override the name of a probe.
+ * <p>
+ * This annotation can be added to a method in a user-defined {@code Provider}
+ * interface, to set the name that will be used for the generated probe
+ * associated with that method.  Without this annotation, the name will be the
+ * name of the method.
+ * <p>
+ * @since 1.7
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+public @interface ProbeName {
+    String value();
+}
+

jdkSrc/jdk8/com/sun/tracing/Provider.java

@@ -0,0 +1,76 @@
+/*
+ * Copyright (c) 2008, 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 com.sun.tracing;
+
+/**
+ * {@code Provider} is a superinterface for user-defined tracing providers.
+ * <p>
+ * To define tracepoints, users must extend this interface
+ * and then use a {@code ProviderFactory} to create an instance of the
+ * newly-defined interface.  Each method in the defined interface represents a
+ * tracepoint (or probe), which can be triggered by calling the associated
+ * method on the returned instance.
+ * <p>
+ * This interface also contains a {@code getProbe()} method, which can be
+ * used to get direct handles to the {@code Probe} objects themselves.
+ * {@code Probe} objects can be triggered manually, or they can be queried to
+ * check their state.
+ * <p>
+ * When an application has finished triggering probes, it should call
+ * {@code dispose()} to free up any system resources associated with the
+ * Provider.
+ * <p>
+ * All methods declared in a subclass of this interface should have a
+ * {@code void} return type. Methods can have parameters, and when called the
+ * values of the arguments will be passed to the tracing implementation.
+ * If any methods do not have a {@code void} return type, an
+ * {@code java.lang.IllegalArgumentException} will be thrown when the
+ * provider is registered.
+ * @since 1.7
+ */
+
+public interface Provider {
+    /**
+     * Retrieves a reference to a Probe object, which is used to check status
+     * or to trigger the probe manually.
+     *
+     * If the provided method parameter is not a method of the provider
+     * interface,  or if the provider interface has been disposed, then
+     * this returns null
+     *
+     * @param method a method declared in the provider.
+     * @return the specified probe represented by that method, or null.
+     */
+    Probe getProbe(java.lang.reflect.Method method);
+
+    /**
+     * Disposes system resources associated with this provider.
+     *
+     * After calling this method, triggering the probes will have no effect.
+     * Additional calls to this method after the first call are ignored.
+     */
+    void dispose();
+}

jdkSrc/jdk8/com/sun/tracing/ProviderFactory.java

@@ -0,0 +1,138 @@
+/*
+ * Copyright (c) 2008, 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 com.sun.tracing;
+
+import java.util.HashSet;
+import java.io.PrintStream;
+import java.lang.reflect.Field;
+import java.security.AccessController;
+import java.security.PrivilegedActionException;
+import java.security.PrivilegedExceptionAction;
+import sun.security.action.GetPropertyAction;
+
+import sun.tracing.NullProviderFactory;
+import sun.tracing.PrintStreamProviderFactory;
+import sun.tracing.MultiplexProviderFactory;
+import sun.tracing.dtrace.DTraceProviderFactory;
+
+/**
+ * {@code ProviderFactory} is a factory class used to create instances of
+ * providers.
+ *
+ * To enable tracing in an application, this class must be used to create
+ * instances of the provider interfaces defined by users.
+ * The system-defined factory is obtained by using the
+ * {@code getDefaultFactory()} static method.  The resulting instance can be
+ * used to create any number of providers.
+ *
+ * @since 1.7
+ */
+public abstract class ProviderFactory {
+
+    protected ProviderFactory() {}
+
+    /**
+     * Creates an implementation of a Provider interface.
+     *
+     * @param cls the provider interface to be defined.
+     * @return an implementation of {@code cls}, whose methods, when called,
+     * will trigger tracepoints in the application.
+     * @throws NullPointerException if cls is null
+     * @throws IllegalArgumentException if the class definition contains
+     * non-void methods
+     */
+    public abstract <T extends Provider> T createProvider(Class<T> cls);
+
+    /**
+     * Returns an implementation of a {@code ProviderFactory} which
+     * creates instances of Providers.
+     *
+     * The created Provider instances will be linked to all appropriate
+     * and enabled system-defined tracing mechanisms in the JDK.
+     *
+     * @return a {@code ProviderFactory} that is used to create Providers.
+     */
+    public static ProviderFactory getDefaultFactory() {
+        HashSet<ProviderFactory> factories = new HashSet<ProviderFactory>();
+
+        // Try to instantiate a DTraceProviderFactory
+        String prop = AccessController.doPrivileged(
+            new GetPropertyAction("com.sun.tracing.dtrace"));
+
+        if ( (prop == null || !prop.equals("disable")) &&
+             DTraceProviderFactory.isSupported() ) {
+            factories.add(new DTraceProviderFactory());
+        }
+
+        // Try to instantiate an output stream factory
+        prop = AccessController.doPrivileged(
+            new GetPropertyAction("sun.tracing.stream"));
+        if (prop != null) {
+            for (String spec : prop.split(",")) {
+                PrintStream ps = getPrintStreamFromSpec(spec);
+                if (ps != null) {
+                    factories.add(new PrintStreamProviderFactory(ps));
+                }
+            }
+        }
+
+        // See how many factories we instantiated, and return an appropriate
+        // factory that encapsulates that.
+        if (factories.size() == 0) {
+            return new NullProviderFactory();
+        } else if (factories.size() == 1) {
+            return factories.toArray(new ProviderFactory[1])[0];
+        } else {
+            return new MultiplexProviderFactory(factories);
+        }
+    }
+
+    private static PrintStream getPrintStreamFromSpec(final String spec) {
+        try {
+            // spec is in the form of <class>.<field>, where <class> is
+            // a fully specified class name, and <field> is a static member
+            // in that class.  The <field> must be a 'PrintStream' or subtype
+            // in order to be used.
+            final int fieldpos = spec.lastIndexOf('.');
+            final Class<?> cls = Class.forName(spec.substring(0, fieldpos));
+
+            Field f = AccessController.doPrivileged(new PrivilegedExceptionAction<Field>() {
+                public Field run() throws NoSuchFieldException {
+                    return cls.getField(spec.substring(fieldpos + 1));
+                }
+            });
+
+            return (PrintStream)f.get(null);
+        } catch (ClassNotFoundException e) {
+            throw new AssertionError(e);
+        } catch (IllegalAccessException e) {
+            throw new AssertionError(e);
+        } catch (PrivilegedActionException e) {
+            throw new AssertionError(e);
+        }
+    }
+}
+

jdkSrc/jdk8/com/sun/tracing/ProviderName.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2008, 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 com.sun.tracing;
+
+import java.lang.annotation.Target;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.ElementType;
+
+/**
+ * An annotation used to specify the name of a provider.
+ * <p>
+ * This annotation can be added to a user-defined {@code Provider}
+ * interface, to set the name that will be used
+ * for the provider in the generated probes.  Without this annotation,
+ * the simple class name of the provider interface is used.
+ * <p>
+ * @since 1.7
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface ProviderName {
+    String value();
+}
+

jdkSrc/jdk8/com/sun/tracing/dtrace/ArgsAttributes.java

@@ -0,0 +1,53 @@
+/*
+ * Copyright (c) 2008, 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 com.sun.tracing.dtrace;
+
+import java.lang.annotation.Target;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.ElementType;
+
+
+/**
+ * This annotation describes the interface attributes of the probe arguments in
+ * a single provider.
+ *
+ * This annotation can be added to a user-defined {@code Provider} specification
+ * interface to set the stability attributes of the probe arguments, for
+ * all the probes specified in that provider.
+ * <p>
+ * If this annotation is not present, the interface attributes for the
+ * arguments are Private/Private/Unknown.
+ * <p>
+ * @see <a href="http://docs.sun.com/app/docs/doc/817-6223/6mlkidlnp?a=view">Solaris Dynamic Tracing Guide, Chapter 39: Stability</a>
+ * @since 1.7
+ */
+
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.TYPE })
+public @interface ArgsAttributes {
+  Attributes value();
+}

jdkSrc/jdk8/com/sun/tracing/dtrace/Attributes.java

@@ -0,0 +1,66 @@
+/*
+ * Copyright (c) 2008, 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 com.sun.tracing.dtrace;
+
+import java.lang.annotation.Target;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.ElementType;
+
+
+/**
+ * This annotation describes the interface's field attributes
+ * for the probes in a provider.
+ *
+ * This annotation provides the contents of field-specific annotations
+ * that specify the stability attributes and dependency class of a
+ * particular field, for the probes in a provider.
+ * <p>
+ * The default interface attributes for unspecified fields is
+ * Private/Private/Unknown.
+ * <p>
+ * @see <a href="http://docs.sun.com/app/docs/doc/817-6223/6mlkidlnp?a=view">Solaris Dynamic Tracing Guide, Chapter 39: Stability</a>
+ * @since 1.7
+ */
+
+@Retention(RetentionPolicy.RUNTIME)
+@Target({})
+public @interface Attributes {
+  /**
+   * The stability level of the name.
+   */
+  StabilityLevel name() default StabilityLevel.PRIVATE;
+
+  /**
+   * The stability level of the data.
+   */
+  StabilityLevel data() default StabilityLevel.PRIVATE;
+
+  /**
+   * The interface attribute's dependency class.
+   */
+  DependencyClass dependency()  default DependencyClass.UNKNOWN;
+}

jdkSrc/jdk8/com/sun/tracing/dtrace/DependencyClass.java

@@ -0,0 +1,77 @@
+/*
+ * Copyright (c) 2008, 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 com.sun.tracing.dtrace;
+
+/**
+ * Enumeration for the DTrace dependency classes.
+ *
+ * @see <a href="http://docs.sun.com/app/docs/doc/817-6223/6mlkidlnp?a=view">Solaris Dynamic Tracing Guide for details, Chapter 39: Stability</a>
+ * @since 1.7
+ */
+public enum DependencyClass {
+    /**
+     * The interface has an unknown set of architectural dependencies.
+     */
+    UNKNOWN  (0),
+    /**
+     * The interface is specific to the CPU model of the current system.
+     */
+    CPU      (1),
+    /**
+     * The interface is specific to the hardware platform of the current
+     * system.
+     */
+    PLATFORM (2),
+    /**
+     * The interface is specific to the hardware platform group of the
+     * current system.
+     */
+    GROUP    (3),
+    /**
+     * The interface is specific to the instruction set architecture (ISA)
+     * supported by the microprocessors on this system.
+     */
+    ISA      (4),
+    /**
+     * The interface is common to all Solaris systems regardless of the
+     * underlying hardware.
+     */
+    COMMON   (5);
+
+    public String toDisplayString() {
+        return toString().substring(0,1) +
+               toString().substring(1).toLowerCase();
+    }
+
+    public int getEncoding() { return encoding; }
+
+    private int encoding;
+
+    private DependencyClass(int encoding) {
+        this.encoding = encoding;
+    }
+}
+

jdkSrc/jdk8/com/sun/tracing/dtrace/FunctionAttributes.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2008, 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 com.sun.tracing.dtrace;
+
+import java.lang.annotation.Target;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.ElementType;
+
+/**
+ * This annotation describes the interface attributes of the
+ * {@code function} field for a single provider.
+ *
+ * This annotation can be added to a user-defined {@code Provider} specification
+ * interface to set the stability attributes of the {@code function} field for
+ * all probes specified in that provider.
+ * <p>
+ * If this annotation is not present, the interface attributes for the
+ * {@code function} field are Private/Private/Unknown.
+ * <p>
+ * @see <a href="http://docs.sun.com/app/docs/doc/817-6223/6mlkidlnp?a=view">Solaris Dynamic Tracing Guide, Chapter 39: Stability</a>
+ * @since 1.7
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.TYPE })
+public @interface FunctionAttributes {
+    Attributes value();
+}

jdkSrc/jdk8/com/sun/tracing/dtrace/FunctionName.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) 2008, 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 com.sun.tracing.dtrace;
+
+import java.lang.annotation.Target;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.ElementType;
+
+/**
+ * An annotation used to specify the {@code function} field for a DTrace probe.
+ *
+ * This annotation can be added to a method in a user-defined Provider
+ * specification interface to set the {@code function} field that is used
+ * for the generated DTrace probe associated with that method.
+ * <p>
+ * @since 1.7
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+public @interface FunctionName {
+    String value();
+}
+

jdkSrc/jdk8/com/sun/tracing/dtrace/ModuleAttributes.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2008, 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 com.sun.tracing.dtrace;
+
+import java.lang.annotation.Target;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.ElementType;
+
+/**
+ * This annotation is used to describe the interface attributes of the
+ * {@code module} field for a single provider.
+ *
+ * This annotation can be added to a user-defined Provider specification
+ * interface to set the stability attributes of the {@code module} field for
+ * all probes specified in that provider.
+ * <p>
+ * If this annotation is not present, the interface attributes for the
+ * {@code module} field is Private/Private/Unknown.
+ * <p>
+ * @see <a href="http://docs.sun.com/app/docs/doc/817-6223/6mlkidlnp?a=view">Solaris Dynamic Tracing Guide, Chapter 39: Stability</a>
+ * @since 1.7
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.TYPE })
+public @interface ModuleAttributes {
+    Attributes value();
+}

jdkSrc/jdk8/com/sun/tracing/dtrace/ModuleName.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) 2008, 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 com.sun.tracing.dtrace;
+
+import java.lang.annotation.Target;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.ElementType;
+
+/**
+ * An annotation used to specify the {@code module} field for a DTrace probe.
+ *
+ * This annotation can be added to a method in a user-defined Provider
+ * specification interface to set the {@code module} field that will be used
+ * for the generated DTrace probe associated with that method.
+ * <p>
+ * @since 1.7
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface ModuleName {
+    String value();
+}
+

jdkSrc/jdk8/com/sun/tracing/dtrace/NameAttributes.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2008, 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 com.sun.tracing.dtrace;
+
+import java.lang.annotation.Target;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.ElementType;
+
+/**
+ * This annotation describes the interface attributes of the
+ * {@code name} field for a single provider.
+ *
+ * This annotation can be added to a user-defined Provider specification
+ * interface to set the stability attributes of the {@code name} field for
+ * all probes specified in that provider.
+ * <p>
+ * If this annotation is not present, the interface attributes for the
+ * {@code name} field will be Private/Private/Unknown.
+ * <p>
+ * @see <a href="http://docs.sun.com/app/docs/doc/817-6223/6mlkidlnp?a=view">Solaris Dynamic Tracing Guide, Chapter 39: Stability</a>
+ * @since 1.7
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.TYPE })
+public @interface NameAttributes {
+    Attributes value();
+}

jdkSrc/jdk8/com/sun/tracing/dtrace/ProviderAttributes.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2008, 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 com.sun.tracing.dtrace;
+
+import java.lang.annotation.Target;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.ElementType;
+
+/**
+ * This annotation is used to describe the interface attributes of the
+ * {@code provider} field for a single provider.
+ *
+ * This annotation can be added to a user-defined Provider specification
+ * interface to set the stability attributes of the {@code provider} field for
+ * all probes specified in that provider.
+ * <p>
+ * If this annotation is not present, the interface attributes for the
+ * {@code provider} field will be Private/Private/Unknown.
+ * <p>
+ * @see <a href="http://docs.sun.com/app/docs/doc/817-6223/6mlkidlnp?a=view">Solaris Dynamic Tracing Guide, Chapter 39: Stability</a>
+ * @since 1.7
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.TYPE })
+public @interface ProviderAttributes {
+    Attributes value();
+}

jdkSrc/jdk8/com/sun/tracing/dtrace/StabilityLevel.java

@@ -0,0 +1,88 @@
+/*
+ * Copyright (c) 2008, 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 com.sun.tracing.dtrace;
+
+/**
+ * Enumeration for the DTrace stability levels.
+ *
+ * @see <a href="http://docs.sun.com/app/docs/doc/817-6223/6mlkidlnp?a=view">Solaris Dynamic Tracing Guide, Chapter 39: Stability</a>
+ * @since 1.7
+ */
+public enum StabilityLevel {
+    /**
+     * The interface is private to DTrace and represents an implementation
+     * detail of DTrace.
+     */
+    INTERNAL  (0),
+    /**
+     * The interface is private to Sun for use by other Sun products. It is
+     * not yet publicly documented for use by customers and ISVs.
+     */
+    PRIVATE  (1),
+    /**
+     * The interface is supported in the current release but is scheduled
+     * to be removed, most likely in a future minor release.
+     */
+    OBSOLETE (2),
+    /**
+     * The interface is controlled by an entity other than Sun.
+     */
+    EXTERNAL (3),
+    /**
+     * The interface gives developers early access to new or
+     * rapidly changing technology or to an implementation artifact that is
+     * essential for observing or debugging system behavior. A more
+     * stable solution is anticipated in the future.
+     */
+    UNSTABLE (4),
+    /**
+     * The interface might eventually become Standard or Stable but is
+     * still in transition.
+     */
+    EVOLVING (5),
+    /**
+     * The interface is a mature interface under Sun's control.
+     */
+    STABLE   (6),
+    /**
+     * The interface complies with an industry standard.
+     */
+    STANDARD (7);
+
+    String toDisplayString() {
+        return toString().substring(0,1) +
+               toString().substring(1).toLowerCase();
+    }
+
+    public int getEncoding() { return encoding; }
+
+    private int encoding;
+
+    private StabilityLevel(int encoding) {
+        this.encoding = encoding;
+    }
+}
+

jdkSrc/jdk8/com/sun/tracing/dtrace/package-info.java

@@ -0,0 +1,82 @@
+/*
+ * Copyright (c) 2008, 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.
+ */
+
+/**
+ * This package contains annotations and enumerations that are used to
+ * add DTrace-specific information to a tracing provider.
+ * <p>
+ * The DTrace-specific annotations modify the attributes of a DTrace provider
+ * implementation when it is used by the tracing subsystem.  The annotations are
+ * added to a {@code com.sun.tracing} provider specification to control
+ * specific attributes of the provider as it relates to DTrace.
+ * <p>
+ * Any other tracing subsystems supported by the system will ignore these
+ * annotations.
+ * <p>
+ * DTrace probes have additional fields and stability attributes that are
+ * not accounted for in the generic tracing package.  If unspecified, the
+ * default values are used for the stability and dependency attributes of
+ * probes, as well as for the module and field names of the generated probes.
+ * The values can be specified by adding the appropriate annotations to the
+ * provider specification.
+ * <p>
+ * The {@code FunctionName} annotation is used to annotate the tracepoint
+ * methods defined in the provider specification.  The value of this annotation
+ * is used as the {@code function} field in the generated DTrace probes. It
+ * is typically set to the name of the enclosing function where the
+ * tracepoint is triggered.
+ * <p>
+ * The {@code ModuleName} annotation is used to annotate the provider
+ * specification itself and applies to all the probes in the provider.  It
+ * sets the value of the {@code module} field in the generated DTrace probes.
+ * <p>
+ * The remaining annotations, are also applied to the provider itself, and
+ * are used to set the stability and dependency attributes of all probes in
+ * that provider.  Each probe field and the probe arguments can be
+ * independently assigned interface attributes to control the stability
+ * ratings of the probes.
+ * <p>
+ * Here is an example of how to declare a provider, specifying additional DTrace
+ * data:
+<PRE>
+    &#064;ProviderName("my_app_provider")
+    &#064;ModuleName("app.jar")
+    &#064;ProviderAttributes(&#064;Attributes={
+        name=StabilityLevel.STABLE,data=StabilityLevel.STABLE,
+        dependency=DependencyClass.COMMON})
+    &#064;ProbeAttributes(&#064;Attributes={
+        name=StabilityLevel.STABLE,data=StabilityLevel.STABLE,
+        dependency=DependencyClass.COMMON})
+    &#064;ModuleAttributes(&#064;Attributes={name=StabilityLevel.UNSTABLE})
+    public class MyProvider {
+        &#064;FunctionName("main") void startProbe();
+    }
+</PRE>
+ * <p>
+ * @see <a href="http://docs.sun.com/app/docs/doc/817-6223/6mlkidlms?a=view">Solaris Dynamic Tracing Guide, Chapter 34: Statically Defined Tracing for User Applications</a>
+ * @see <a href="http://docs.sun.com/app/docs/doc/817-6223/6mlkidlnp?a=view">Solaris Dynamic Tracing Guide, Chapter 39: Stability</a>
+ */
+
+package com.sun.tracing.dtrace;

jdkSrc/jdk8/com/sun/tracing/package-info.java

@@ -0,0 +1,183 @@
+/*
+ * Copyright (c) 2008, 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.
+ */
+
+/**
+ * This package provides a mechanism for defining and
+ * inserting tracepoints into Java-technology based applications, which
+ * can then be monitored by the tracing tools available on the system.
+ * <p>
+ * To add tracepoints to a program, you must first decide where to place the
+ * tracepoints, what the logical names are for these points, what information
+ * will be available to the tracing mechanisms at each point, and decide upon
+ * any logical grouping.
+ * <p>
+ * You add instrumentation to a program in three steps:
+ * <ul>
+ * <li>First, declare tracepoints by creating interfaces to define
+ * them, and include these interfaces in the program definition.
+ * The declared interfaces are standard Java technology-based
+ * interfaces and are compiled with the program.</li>
+ * <li>Second, add code in the application to create an instance of the
+ * interface at some point during the initialization of the application,
+ * using a factory class provided by the system. The reference to the
+ * instance can be stored as a global static, or passed as context to all
+ * the places where it is needed.</li>
+ * <li>Finally, add the actual tracepoints to the desired locations in the
+ * application by inserting a call to one of the methods defined in the
+ * interface, via the factory-created reference.</li>
+ * </ul>
+ * <p>
+ * The method calls representing the tracepoints have no logical
+ * impact on the program.  The side effect of the call is that any
+ * activated tracing mechanisms will be notified that the tracepoint has
+ * been hit, and will take whatever actions are appropriate (for example,
+ * logging  the tracepoint, or triggering a DTrace probe, etc.).  In most
+ * cases, the impact on performance of adding tracepoints to the application
+ * will be minimal.
+ * <p>
+ * Each logical grouping of tracepoints should be defined in a common
+ * interface, called a <i>provider</i>.  An application can have one or many
+ * providers.  Each provider is independent and can be created whenever
+ * it is appropriate for that provider, for example, when a subsytem is
+ * initialized.  Providers should be disposed of when they are no longer
+ * needed, to free up any associated system resources.  Each tracepoint
+ * in a provider is represented by a method in that interface.  These methods
+ * are referred to as <i>probes</i>.  The method signature determines the probe
+ * parameters.  A call to the method with the specified parameters triggers
+ * the probe and makes its parameter values visible to any associated tracing
+ * mechanism.
+ * <p>
+ * User-defined interfaces which represent providers must extend the
+ * {@code Provider} interface.  To activate the system-defined
+ * tracing mechanisms, you must obtain an instance of the
+ * {@code ProviderFactory} class, and pass the class of the provider to
+ * the {@code createProvider()} method.  The returned instance is then used to
+ * trigger the probes later in the application.
+ * <p>
+ * In addition to triggering the probes, the provider instance can be used
+ * to obtain direct references to the {@code Probe} objects, which can be used
+ * directly for triggering, or can be queried to determine whether the probe is
+ * currently being traced.  The {@code Provider} interface also defines a
+ * {@code Provider.dispose()} method which is used to free up any resources
+ * that might be associated with that provider.
+ * <p>
+ * When a probe is triggered, any activated tracing system will be given
+ * the provider name, the probe name, and the values of the probe arguments.
+ * The tracing system is free to consume this data is whatever way is
+ * appropriate.
+ * By default, the provider name is the same as the class name of the interface
+ * that defines the provider. Similarly, the probe name is
+ * the name of the method that defines the probe. These default values
+ * can be over-ridden by annotations.  The provider definition can be
+ * annotated with the {@code @ProviderName} annotation, whose value will
+ * indicate the provider name that the tracing system will use.  Similarly,
+ * the {@code @ProbeName} annotation annotates a declared method and
+ * indicates the probe name that should be used in the place of the
+ * method name.  These annotations can be used to define providers and
+ * probes with the same name, in cases where the semantics of the Java language
+ * may prevent this.
+ * <p>
+ * Here is a very small and simple usage example:
+ * <p>
+ *
+<PRE>
+   import com.sun.tracing.Provider;
+   import com.sun.tracing.ProviderFactory;
+
+   interface MyProvider extends Provider {
+       void startProbe();
+       void finishProbe(int value);
+   }
+
+   public class MyApplication {
+       public static void main(String argv[]) {
+           ProviderFactory factory = ProviderFactory.getDefaultFactory();
+           MyProvider trace = factory.createProvider(MyProvider.class);
+
+           trace.startProbe();
+           int result = foo();
+           trace.finishProbe(result);
+
+           trace.dispose();
+       }
+   }
+</PRE>
+ * <p>
+ * The Java Development Kit (JDK) currently only includes one system-defined
+ * tracing framework: DTrace. DTrace is enabled automatically whenever an
+ * application is run on a system and a JDK release that supports it. When
+ * DTrace is enabled, probes are made available for listing and matching by
+ * DTrace scripts as soon as the provider is created. At the tracepoint, an
+ * associated DTrace script is informed of the creation of the provider, and
+ * it takes whatever action it is designed to take. Tracepoints in the
+ * program have the following DTrace probe names:<br>
+ *   {@code <provider><pid>:<module>:<function>:<probe>}
+ * Where:
+ * <ul>
+ * <li>{@code <provider>} the provider name as specified by the application</li>
+ * <li>{@code <pid>} the operating system process ID</li>
+ * <li>{@code <module>} undefined, unless specified by the application</li>
+ * <li>{@code <function>} undefined, unless specified by the application</li>
+ * <li>{@code <probe>} the probe name as specified by the application</li>
+ * </ul>
+ * <p>
+ * The {@code com.sun.tracing.dtrace} package contains additional
+ * annotations that can be used to control the names used for the
+ * <code>module</code> and <code>function</code> fields, as well as annotations
+ * that can be added to the provider to control probe stability and dependency
+ * attributes.
+ * <p>
+ * Integer, float and string probe parameters are made available to DTrace
+ * using
+ * the built-in argument variables, {@code arg0 ... arg_n}.  Integer-types
+ * are passed by value (boxed values are unboxed), floating-point types are
+ * passed as encoded integer
+ * arguments, and {@code java.lang.String} objects are converted
+ * to UTF8 strings, so they can be read into the DTrace script using the
+ * {@code copyinstr()} intrinsic.  Non-string and non-boxed primitive
+ * reference arguments are only
+ * placeholders and have no value.
+ * <p>
+ * Using the example above, with a theoretical process ID of 123, these are
+ * the probes that can be traced from DTrace:
+<PRE>
+    MyProvider123:::startProbe
+    MyProvider123:::finishProbe
+</PRE>
+ * When {@code finishProbe} executes, {@code arg0} will contain the
+ * value of {@code result}.
+ * <p>
+ * The DTrace tracing mechanism is enabled for all providers, apart from in the
+ * following circumstances:
+ * <ul>
+ * <li>DTrace is not supported on the underlying system.</li>
+ * <li>The property {@code com.sun.tracing.dtrace} is set to "disable".</li>
+ * <li>The RuntimePermission {@code com.sun.tracing.dtrace.createProvider}
+ * is denied to the process.</li>
+ * </ul>
+ * <p>
+ */
+
+package com.sun.tracing;